Docs: Chez-only, drop the Janet-era references and obsolete migration notes

Bring the docs in line with the actual implementation now that Chez is the sole
substrate.

Deleted the migration/spike/handoff artifacts that only documented the Janet
era or the port effort: the port plan, phase-0 and foundational-runtime spike
writeups (+ the stray root-level copy), the self-hosting design notes, the
architecture-refactor plan, and spike/chez/RESULTS.md.

Rewrote the current reference docs against the Chez facts: building-and-deps and
tools-deps (no jpm/build step — bin/joltc off the checked-in seed, deps via
jolt.deps into ~/.jolt/gitlibs), libraries (SQLite is built-in jdbc.core over
libsqlite3, not a Janet driver), the conformance/spec test-flow docs (the Chez
corpus runner + certify, no .janet harnesses), and the transient / type-hint /
seed-overlay design notes (Chez representations: mutable transients, flat
copy-on-write vectors, HAMT maps, the seed/overlay twin). Fixed the README
collections line (vectors aren't 32-way tries) and added the ffi/transient gate
targets. rfc 0001's numerics open-question is resolved (the Scheme tower).

Renamed the built-in HTTP adapter to jolt.http.server only (dropped the
ring-janet.adapter alias — a Janet-era name).

docs/rfc/0003-transients.md

@@ -1,50 +1,49 @@
-# RFC 0003: Transients — semantics and why they live in the Janet seed
+# RFC 0003: Transients — semantics and the Chez mutable backing
 
 Status: accepted (design note)
 
 This note pins down what transients *are* in Jolt, where their behavior
-deviates from JVM Clojure and why, and why the transient machinery is part of
-the irreducible Janet seed rather than a candidate for the core-in-Clojure
-migration (jolt-tzo). It exists so the kernel-shrink ladder doesn't revisit
+deviates from JVM Clojure and why, and how the transient machinery is
+represented in the Chez runtime. It exists so the design doesn't revisit
 transients every round.
 
 ## What a transient is in Jolt
 
-A transient is a tagged Janet table wrapping a *native* mutable host value
-(`core.janet`, "Transients" section):
+A transient is a Chez record (`jolt-transient`, `host/chez/transients.ss`)
+wrapping *true mutable* host backing, snapshotted to the immutable collection on
+`persistent!`. The backing is per kind:
 
-- transient vector — `@{:jolt/type :jolt/transient :kind :vector :arr ARRAY}`,
-  a Janet array.
-- transient map — `:kind :map :tbl TABLE`, a Janet table mapping
-  `canon-key(k)` → `@[k v]`. Keying by canonical key keeps collection keys
-  comparing by value across representations (`[1 2]` the pvec and `[1 2]` the
-  tuple are one key), and storing the `@[k v]` pair preserves the *original*
-  key for the rebuilt persistent map.
-- transient set — `:kind :set :tbl TABLE` mapping `canon-key(x)` → `x`.
+- transient vector — a growable Scheme vector (a capacity buffer plus a fill
+  count `n`). `conj!`/`pop!` are in-place, amortized O(1); the buffer doubles on
+  growth.
+- transient map — a Chez hashtable keyed by `key-hash` / `jolt=`
+  (value-equality, nil-safe). Hashing by value keeps collection keys comparing
+  across representations.
+- transient set — a Chez hashtable of elements.
+- `cow` — a copy-on-write fallback for anything else (e.g. a sorted coll).
 
-`transient` accepts pvecs, mutable-build arrays, tuples (reader vectors and
-map entries — added in the seed-shrink rounds so `(into [] (first {:a 1}))`
-works through the vector fast path), sets, phms, and untagged struct maps.
-Sorted collections are rejected, as on the JVM (not editable).
+`transient` accepts pvecs, pmaps, psets, and the exotic colls handled by the
+`cow` path. Each kind copies its source into the matching mutable backing once.
 
-The bang ops (`conj!`, `assoc!`, `dissoc!`, `disj!`, `pop!`) mutate that host
-value in place and return the transient — O(1) per op (amortized for array
-push). `persistent!` rebuilds a persistent value from the host value and
-invalidates the transient (`:jolt/persistent` flag; any further bang op or a
-second `persistent!` throws "Transient used after persistent! call", matching
-Clojure's invalidation contract).
+The bang ops (`conj!`, `assoc!`, `dissoc!`, `disj!`, `pop!`) mutate that backing
+in place and return the transient — O(1) per op (amortized for the vector push).
+`persistent!` snapshots a persistent value from the backing (folding the
+hashtable into a pmap/pset, handing off the buffer as a pvec) and invalidates the
+transient (the record's active flag clears; any further bang op or a second
+`persistent!` throws "transient used after persistent!", matching Clojure's
+invalidation contract).
 
 Read ops work on an active transient where Clojure supports them: `get`,
-`contains?`, `count`, and `nth` (vector kind) branch on the transient tag.
+`contains?`, `count`, and `nth` (vector kind) see through the transient.
 `seq` on a transient is not supported, as in Clojure.
 
 ## Deviations from JVM Clojure (deliberate)
 
 **O(n) edges, O(1) middle.** Clojure's `(transient v)` is O(1) — the transient
 *shares* the persistent trie and marks nodes editable; `persistent!` is O(1)
-too. Jolt's `transient` copies the source into a native array/table (O(n)) and
-`persistent!` rebuilds (O(n)). The bang ops in between are native-host O(1),
-which is *faster* per-op than trie editing. So the asymptotics of the usual
+too. Jolt's `transient` copies the source into a mutable buffer/hashtable (O(n))
+and `persistent!` snapshots back (O(n)). The bang ops in between are host-mutable
+O(1), which is *faster* per-op than trie editing. So the asymptotics of the usual
 pattern
 
     (persistent! (reduce conj! (transient []) coll))
@@ -53,13 +52,12 @@ are identical (O(n) total either way) with a better constant in the loop and a
 worse constant at the two edges. The pattern transients exist for — batch
 construction — is fully served. What is NOT served is transient-editing a
 *large* collection to change a few keys: that's O(n) in Jolt vs O(log n) in
-Clojure, because `transient` flattens the pvec trie / phm HAMT into a
-native array/table and `persistent!` rebuilds them.
+Clojure, because `transient` copies the source into a growable Scheme vector /
+Chez hashtable and `persistent!` snapshots it back.
 
 **No thread-ownership check.** JVM Clojure ≥1.7 also dropped the owner-thread
 assertion (for fork/join), keeping only "don't use after persistent!", which
-Jolt enforces. Jolt code is fiber-concurrent; when real OS-thread futures land
-(jolt-ejx), a transient handed across threads is a data race exactly as in
+Jolt enforces. A transient handed across threads is a data race exactly as in
 Clojure — documented, not checked, same as the JVM.
 
 **`(conj!)` / `(conj! t)` arities** follow Clojure's transducer-era contract:
@@ -68,51 +66,43 @@ zero args makes a fresh `(transient [])`, one arg returns it untouched.
 lenient kvs walk of Jolt's `assoc`.
 
 **No transient sorted variants** — same as Clojure. One leniency: Clojure
-throws on `(transient '(1))`, but Jolt's lists are Janet arrays underneath and
-fall into the mutable-build branch, yielding a transient *vector*. Harmless
-(the result of `persistent!` is a vector, never silently a list) but
-non-Clojure; tighten if it ever bites.
+throws on `(transient '(1))`, but Jolt routes a list through the `cow` fallback
+path, yielding a transient. Harmless but non-Clojure; tighten if it ever
+bites.
 
-## Why transients stay in the Janet seed
+## Why transients live in the host
 
-The migration ladder (jolt-tzo) moves anything expressible as *pure Clojure
-over existing primitives* out of the seed. Transients fail that test on three
+Transients are part of the value/representation layer in the Chez runtime
+(`host/chez/transients.ss`), not the portable `clojure.core` overlay, on three
 grounds:
 
 1. **They are the mutation kernel.** A transient's entire value is direct
-   mutation of a host array/table. The overlay's only mutation seam is
-   `jolt.host/ref-put!` (a single table-put). Re-expressing `tr-conj!` etc. in
-   Clojure would mean either growing the host surface one-for-one
-   (`host-array-push!`, `host-table-put!`, …, i.e. moving the same code behind
-   more indirection) or simulating mutation over persistent values (defeating
-   the point of transients). Either way the Janet line count moves, it doesn't
-   shrink.
+   mutation of a host buffer/hashtable. The overlay has no mutation seam of its
+   own. Re-expressing the bang ops in Clojure would mean either growing the host
+   surface one-for-one (a host-vector-push, a host-hashtable-put, …, i.e. moving
+   the same code behind more indirection) or simulating mutation over persistent
+   values (defeating the point of transients).
 
-2. **They sit under the seed's own dispatch.** `conj`/`assoc`/`get`/`count`/
-   `contains?` in the seed branch on the transient tag. Hoisting the transient
-   ops above that dispatch (the hierarchy-port pattern of lazily-resolved
-   overlay vars) would put an interpreted/compiled-Clojure call inside the
-   hottest native paths for no semantic gain — transients have no semantics to
-   *fix* (unlike hierarchy, which had real correctness gaps).
+2. **They sit under the collection dispatch.** `conj`/`assoc`/`get`/`count`/
+   `contains?` see through a transient. Hoisting the transient ops above that
+   dispatch would put a compiled-Clojure call inside the hottest paths for no
+   semantic gain — transients have no semantics to *fix*.
 
-3. **The value layer is declared irreducible.** The self-hosting design doc
-   (docs/self-hosting-compiler.md, "The kernel") keeps the value/representation
-   layer — persistent collections and, with them, their mutable scratch
-   counterparts — in the host. Transients are representation, not library.
+3. **The value layer is the host's job.** The persistent collections and, with
+   them, their mutable scratch counterparts, live in the Chez runtime alongside
+   the value model. Transients are representation, not library.
 
-What CAN move (and mostly has): anything *derived* — e.g. `into`'s
-transient-using fast path, or future `update!`-style conveniences — is plain
-Clojure over `transient`/bang-ops/`persistent!` and belongs in the overlay
-tiers as ordinary migration batches.
+What lives in the overlay: anything *derived* — e.g. `into`'s transient-using
+fast path, or `update!`-style conveniences — is plain Clojure over
+`transient`/bang-ops/`persistent!`.
 
 ## Future work
 
-- pvec is already a 32-way trie with structural sharing (pv.janet), so
-  Clojure-style O(1) `transient`/`persistent!` via editable nodes is a real
-  option for vectors — an internal change behind the same surface, not a
-  semantics change. phm is now a HAMT with structural sharing too (jolt-684u),
-  and sorted maps/sets are a red-black tree (jolt-0hbr), so the same editable-
-  node trick is open for those as well — the transient surface here is still the
-  copy-to-native-table flatten.
+- The persistent map/set are a bitmap HAMT with structural sharing
+  (`host/chez/collections.ss`), so Clojure-style O(1) `transient`/`persistent!`
+  via editable nodes is a real option there — an internal change behind the same
+  surface, not a semantics change. The persistent vector is a flat
+  copy-on-write Scheme vector rather than a trie, so the transient surface for
+  it stays the copy-to-growable-vector path.
 - `transient?` (Jolt extension, useful in tests) stays; Clojure has no public
   predicate, so it must not leak into portability-sensitive code.