0021: cljwit.edn -- sync!, status and check, shaped by its own review

S2's first unit. The project file holds what write-ns! takes, keyed by
namespace so a duplicate is unrepresentable; discovery is the working
directory plus :file, matching what the shadow-cljs precedent actually
does rather than what the first draft claimed for it.

An adversarial review changed most of the surface before implementation:

- Drift is tiered, not byte-equality. Byte-compare's certain failure is
  the first generator release flagging every user file as drifted with a
  message blaming their component. So: exports-hash line differs =>
  :stale (the component changed); bytes differ under a matching hash =>
  :modified (hand edit, option change, or newer generator -- the new
  generator: header line says which). This supersedes 0020 A's "string
  compare" sentence, recorded there and here.
- sync! plans everything before writing anything -- source-for is pure,
  so a bad entry aborts with zero bytes written, failures collected
  across entries, each carrying its namespace.
- status also looks in the other direction: a generated file no entry
  claims (:orphans) is exactly the silent staleness this unit exists to
  kill. Nothing is deleted.
- check enumerates the drift on stdout and in ex-message, because -X
  shows a caller nothing else (measured: ex-data goes to a temp-file
  report CI discards). The documented CI form is an alias carrying
  --enable-native-access, and the note now states the real prerequisite:
  the runner needs libwasmtime.
- The review also caught write-ns! silently dropping unknown keys --
  0014's nil-on-typo, live in the REPL path. known-opts! now rejects
  them for every caller.

The -X coordinate (cljwit.project/check) is provisional until the S2
server process is designed; the note says so.

Claude-Session: https://claude.ai/code/session_01XF5Hfq4Ca2N2XYEzWQQuHt

Author: chaploud

doc/design/0021-cljwit-edn.md

@@ -0,0 +1,169 @@
+# 0021 — `cljwit.edn`: the project file, starting as a list of components
+
+**Status:** accepted · 2026-07-30 · S2's first unit. `0020` promised its
+option keys would be this file's keys, and deferred the drift check here.
+Rewritten after an adversarial review ran its claims: the drift contract,
+the transaction semantics, the path story and the CI command all changed,
+and two of the first draft's factual claims were measured false.
+
+## The question
+
+`0020` generates one namespace per call, and what it wrote can go stale
+silently — the file cannot notice a swapped `.wasm`, and nothing regenerates
+it but a human remembering to. A project with three components has three
+invocations to remember, in the right directories, with the same options as
+last time. shadow-cljs answered the same question with a project file; the
+roadmap names `cljwit.edn` as S2's first deliverable. What goes in it now,
+and what does not?
+
+## The decision
+
+### A. One file, found in the working directory, components keyed by namespace
+
+```clojure
+;; cljwit.edn
+{:components {acme.resize {:wasm "components/resize.wasm"}
+              acme.api.v1 {:wasm      "components/api.wasm"
+                           :interface "acme:api/svc@1.0.0"
+                           :dir       "src/gen"}}}
+```
+
+Each value is `0020`'s option map minus `:ns`, which moved into the key —
+**a duplicate namespace is now unrepresentable** rather than validated, and
+the map diffs one line per component. What still needs a written check is
+the sibling collision edn cannot see: `acme.foo-bar` and `acme.foo_bar`
+munge to one file path.
+
+**Discovery is the working directory, plus `:file`.** `(project/sync!)`
+reads `./cljwit.edn` — the same rule shadow-cljs uses, and the same anchor
+`-X` already gives `deps.edn` — and a monorepo passes
+`{:file "sub/cljwit.edn"}`. No walking up: two `cljwit.edn`s in one tree is
+a question this note refuses to answer implicitly. `:wasm` and `:dir` are
+resolved relative to the file's directory **for I/O only**; the string
+printed into a generated header stays the edn-relative one, because a
+committed header carrying an absolute path is a machine-specific assumption
+in a committed file. (`write-ns!` grew a `:source` override to keep those
+two apart.)
+
+Unknown keys are an error naming the key — at the top level, in an entry,
+**and in `write-ns!` itself**: the review found the REPL path silently
+dropping `:renmae` today, which is `0014`'s nil-on-typo live in the
+function this file wraps. The check lives in `gen`, so both paths inherit
+it. Every failure `sync!` reports carries its provenance —
+`{:file "cljwit.edn" :ns acme.api.v1}` — because "identical to the REPL
+error" is the wrong goal for entry 3 of 5.
+
+### B. `sync!` returns data; `check` throws with the list in its message
+
+Both live in **`cljwit.project`**, not `cljwit.host.gen`: reading,
+validating and reconciling the project file is not "generation over a
+list", and the roadmap already names two more consumers of this file (the
+nREPL entry point, the watcher). A `-X` coordinate pasted into CI YAML is
+a public API; it should name the file's owner.
+
+```clojure
+(project/sync!)    ; plan everything, then write; {:wrote [...] :unchanged [...]}
+(project/status)   ; touch nothing; {:ok [...] :stale [...] :modified [...]
+                   ;                 :missing [...] :orphans [...]}
+(project/check)    ; status, printed, thrown if anything is not :ok
+```
+
+- **Plan all, then write all.** `source-for` is pure, so validation
+  failures in any entry abort before the first byte is written — no
+  half-synced tree. Failures are collected across entries, not
+  first-wins.
+- **Drift is tiered, because byte-equality misdiagnoses the certain case.**
+  The first draft said "differs from what regeneration would produce" and
+  the review pointed out what that flags: **every generated file in every
+  user project, on the first cljwit release that touches emission** — with
+  a message blaming their component. So: the `exports-hash` header line
+  differs → **`:stale`**, the component's API changed, regenerate. Hash
+  matches but bytes differ → **`:modified`** — a hand edit, a changed
+  option, or a newer generator, and the header's new `generator:` line
+  says which of those it was. This supersedes `0020` A's "the API hash
+  makes it a string compare" — the hash alone misses hand edits and
+  `:rename` changes; the bytes alone cannot name what happened. Both
+  tiers cost one `describe` of one `.wasm`.
+- **Orphans are findings, not garbage collection.** A file under a
+  configured `:dir` that carries the generated header but no entry —
+  someone deleted the entry and left the namespace loadable — is exactly
+  the silent staleness this unit exists to kill, so `status` reports it.
+  Nothing is deleted: removal is the human's, with the list in hand.
+- **`check` is the CI verb**, and it enumerates on stdout and in the
+  exception message — measured: `-X` shows a caller only `ex-message`;
+  `ex-data` lands in a temp-file report CI discards.
+
+### C. The CI invocation is an alias, and says its prerequisites out loud
+
+```clojure
+;; deps.edn
+:aliases {:cljwit {:jvm-opts ["--enable-native-access=ALL-UNNAMED"]
+                   :exec-fn  cljwit.project/check}}
+```
+
+`clojure -X:cljwit` exits non-zero on drift. The bare
+`clojure -X cljwit.project/check` of the first draft prints three JEP-472
+restricted-method warnings today and is scheduled to become an error, so
+the alias is the documented form. And the prerequisite is stated rather
+than implied: **this check runs the generator, so the runner needs
+libwasmtime** (`0019`) — a heavier ask than the `bb` this note's first
+draft rejected as too demanding. A CI without the native library cannot
+run `check`; committing the generated files and reviewing their diffs is
+what it has instead.
+
+The `-X` coordinate is **provisional until the S2 server process is
+designed** — the shadow-cljs model has a long-lived process end up owning
+this file and the engine, and that design may want to own the CLI too.
+
+### D. What is *not* in the file yet
+
+A file watcher, an nREPL entry point, compiler options — the rest of S2 —
+earn their keys when they exist. A config surface that anticipates its
+features is the scaffolding failure `0006` documents, in user-facing form.
+
+## Why
+
+- **The drift check has to live above the generated files.** `0020` settled
+  that a generated file cannot check itself; only the thing that knows every
+  component→namespace pair can. This file is that thing, and `status` makes
+  the knowledge executable in both directions — entries without files,
+  files without entries.
+- **Saved arguments beat remembered ones.** The regeneration command is
+  already printed in every generated header; this file is the same
+  information once, for all of them, diffable.
+- **shadow-cljs is the precedent, at its actual strength.** Its lesson is
+  the narrow one: a project file the tool reads and the human edits, at the
+  root, in edn, found in the working directory. It has no
+  find-from-anywhere property and neither does this.
+
+## Alternatives rejected
+
+- **Metadata in the generated files instead of a central file.** Loses the
+  complete set — no `:missing`, no `:orphans`.
+- **A `deps.edn` alias carrying the config.** tools.deps passes exec args,
+  it does not define config schemas. (An alias still *carries the JVM
+  flags* — C — which is a different job.)
+- **babashka tasks as the interface.** This repo uses bb; a library user
+  need not.
+- **Regenerating inside `require` / at load time.** Reopens `0015`'s
+  measured rejections through the back door.
+- **A vector of entries with `:ns` inside** (the first draft). Made the
+  file's one invariant — one owner per namespace — something to validate
+  instead of something unrepresentable.
+- **Byte-equality as the whole drift contract** (the first draft). Certain
+  to misfire on the first generator release; see B.
+- **`sync!` throwing on drift.** Hostile from a REPL; data composes,
+  `check` throws.
+
+## What would falsify this
+
+- A second S2 feature whose config does not fit "a map of `write-ns!`
+  argument maps" — the file would need a second top-level key, and this
+  note an amendment saying which.
+- A user's cljfmt config reformatting generated files, so that `:modified`
+  fires on every checked file. The generator's output is stable under this
+  repo's cljfmt (measured in review); a divergent user config would force
+  emission to normalize harder or `:modified` to diff structurally.
+- The S2 server design wanting different ownership of the file and the
+  `-X` coordinate — the coordinate is declared provisional for exactly
+  that.

src/cljwit/host/gen.clj

@@ -13,6 +13,22 @@
 
 (set! *warn-on-reflection* true)
 
+(def VERSION
+  "Bumped when emission changes, so a `:modified` verdict from
+   `cljwit.project/status` can say \"newer generator\" instead of blaming
+   the component (`0021` B)."
+  "1")
+
+(def ^:private KNOWN-OPTS #{:ns :dir :interface :rename :engine :source :regenerate})
+
+(defn- known-opts!
+  "An unknown option silently dropped is `0014`'s nil-on-typo — a review
+   caught :renmae sailing through this very function's callers."
+  [opts]
+  (when-let [bad (seq (remove KNOWN-OPTS (keys opts)))]
+    (throw (ex-info (str "unknown option(s): " (pr-str (vec bad)))
+                    {:cljwit/error :bad-options :cljwit/keys (vec bad)}))))
+
 (defn- var-name
   "The last WIT segment as a symbol: annotations dropped, dots to dashes.
    `…#[method]counter.bump` → counter-bump."
@@ -127,6 +143,7 @@
    the collision rules and the emitted shape are testable without a
    component. `write-ns!` is the wrapper that reads one."
   [described {:keys [ns source] :as opts}]
+  (known-opts! opts)
   (when-not (symbol? ns)
     (throw (ex-info ":ns must be a symbol" {:cljwit/error :bad-options :cljwit/ns ns})))
   (let [rows     (plan described opts)
@@ -136,7 +153,10 @@
     (str ";; Generated by cljwit.host.gen (doc/design/0020). Do not edit by hand.\n"
          (when source (str ";; source: " source "\n"))
          ";; exports-hash: sha256:" (api-hash (into {} (map (juxt :wit :sig)) rows)) "\n"
-         ";; regenerate: (cljwit.host.gen/write-ns! \"" (or source "<component.wasm>") "\" '" regen ")\n"
+         ";; generator: cljwit.host.gen v" VERSION "\n"
+         ";; regenerate: " (or (:regenerate opts)
+                               (str "(cljwit.host.gen/write-ns! \""
+                                    (or source "<component.wasm>") "\" '" regen ")")) "\n"
          "(ns " ns "\n"
          "  \"Exports of a Wasm component, one var per export; the instance is the\n"
          "   first argument (doc/design/0020). cljwit.host/unwrap is the result sugar.\""