45876998ad
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).
45 lines
2.3 KiB
Markdown
45 lines
2.3 KiB
Markdown
# Seed ↔ Overlay Registry
|
|
|
|
Jolt is Clojure on Chez Scheme. `clojure.core` is built from two tiers that both
|
|
define `clojure.core`-facing vars, and for a handful of names *both* tiers carry
|
|
a definition. This document records how the two tiers relate and which copy is
|
|
authoritative.
|
|
|
|
## The two tiers
|
|
|
|
- **Native shims** (`host/chez/natives-*.ss`) bind a set of `clojure.core` vars
|
|
directly to Scheme runtime values via `def-var!` — collection constructors,
|
|
seq fns, numeric/string ops, and so on. These cover names the overlay assumes
|
|
exist as bare `clojure.core` vars but does not define itself.
|
|
- **The Clojure overlay** (`jolt-core/clojure/core/NN-*.clj`) defines the rest of
|
|
`clojure.core` in dependency-ordered tiers, loaded in order: `00-syntax`,
|
|
`00-kernel`, `10-seq`, `20-coll`, `25-sorted`, `30-macros`, `40-lazy`, `50-io`.
|
|
|
|
The overlay loads after the native shims. When an overlay tier `(defn X …)` for a
|
|
name a native shim already bound, the **overlay def shadows the native binding** —
|
|
user code sees the overlay copy. The native binding then survives only if some
|
|
other native/runtime code still calls the Scheme value directly.
|
|
|
|
So a name's *home* is determined by two facts:
|
|
|
|
1. is it bound by a native shim? (the Scheme value is reachable from the runtime)
|
|
2. does an overlay tier `(defn X …)`? (the overlay copy is what user code sees)
|
|
|
|
## The compiled seed
|
|
|
|
`clojure.core` is compiled ahead of time into the checked-in seed
|
|
(`host/chez/seed/{prelude,image}.ss`) as Scheme `def-var!` forms. The seed's
|
|
source twin is the overlay (`jolt-core/clojure/core/*.clj` plus the stdlib
|
|
namespaces under `src/jolt/clojure/`); `host/chez/emit-image.ss` re-emits the
|
|
prelude from those sources on Chez. The build is a byte-fixpoint: rebuilding from
|
|
an up-to-date seed reproduces it exactly.
|
|
|
|
## Consistency guard
|
|
|
|
There is no separate drift-check test for the registry. The self-hosting
|
|
fixpoint is the guard: after changing a seed source (a core tier, the compiler
|
|
namespaces, the host contract, the reader, or `emit-image.ss`) you must re-mint
|
|
the seed (`make remint`), and `make selfhost` fails if the checked-in seed and
|
|
its sources have drifted. So if the overlay's shadowing relationship changes, the
|
|
re-minted prelude changes with it, and the fixpoint check keeps source and seed
|
|
in agreement.
|