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:
parent
7d1f0b058c
commit
d84c88f830
4 changed files with 242 additions and 0 deletions
12
CLAUDE.md
12
CLAUDE.md
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue