docs: module map, RFC index, refactor plan (arch-refactor tier 0)

Navigability groundwork from the architecture review — zero behaviour change.

- docs/MODULES.md: the repo map. Area -> directory -> key files -> re-mint?, plus
  per-feature touch points (tree-shaking, direct-linking, numeric fl/fx, inlining,
  multimethods, deps) and where a given clojure.core fn lives. Answers "where does
  X live / what's related to Y" in one read.
- docs/rfc/README.md: index the 7 RFCs; flags RFC 0007's stale "no code yet" status
  (direct-linking + tree-shaking shipped) and the undocumented inlining/numeric work.
- CLAUDE.md: document the var-deref calling convention (public defns reached from the
  .ss runtime by string lookup aren't dead), the def-var! native pattern, and the
  overlay shadowing rule; point at MODULES.md.
- REFACTOR_PLAN.md: the prioritized, risk-tiered plan (working doc for this branch).
This commit is contained in:
Yogthos 2026-06-23 21:50:58 -04:00
parent 7d1f0b058c
commit d84c88f830
4 changed files with 242 additions and 0 deletions

View file

@ -109,6 +109,18 @@ Issue tracking and design notes live in beads (`bd prime`, `bd memories`).
forever. Use `jolt.host/ref-get`.
- **Map literals with `:jolt/type` as a key** parse as tagged reader forms —
don't tag overlay value maps in source.
- **The compiler is reached from the runtime by `var-deref` string lookup.** The
`.ss` runtime calls into the cross-compiled compiler with
`(var-deref "jolt.analyzer" "analyze")` etc., and the compiler resolves its own
unqualified `jolt.host/…` refs the same way against `host-contract.ss`. So a
public `defn` with no in-Clojure callers may still be a live entry point — don't
treat it as dead. Only a private `defn-` with no callers is safe to remove.
- **A native `clojure.core` fn is a `(def-var! "clojure.core" "name" …)`** in a
`host/chez/*.ss`; the rest of core is the overlay (`jolt-core/clojure/core/*.clj`).
A few natives are re-asserted in `post-prelude.ss` so they win over the overlay.
See [docs/MODULES.md](docs/MODULES.md) for where a given fn lives, and
[docs/seed-overlay-registry.md](docs/seed-overlay-registry.md) for the shadowing
rule. Start at [docs/MODULES.md](docs/MODULES.md) to find a feature's files.
- **Fix latent bugs to match Clojure** rather than preserving them, with a
regression case. Match the JVM (or provide a superset); the JVM-sourced corpus
is the contract.