@@ -1,7 +1,12 @@
 # 0020 — Generated namespaces: the ergonomics layer, as a file
 
-**Status:** proposed · 2026-07-30 · the shape `0015` accepted for later, picked
+**Status:** accepted · 2026-07-30 · the shape `0015` accepted for later, picked
 up now that its two blockers — marshalling and host imports — are gone.
+Rewritten after an adversarial review: D inverted (the throwing variant lost),
+C gained the per-interface exit its collision rule needed, and the sha moved
+from the component bytes to the API. This layer **opens S2** — its option keys
+are `cljwit.edn`'s keys, so the file becomes the edn's implementation rather
+than its rival — and S1 closes without it.
 
 ## The question
 
@@ -29,9 +34,20 @@ file looks like.
 is a dev-time act that reads a component's type, and requiring it in
 production buys nothing. The generated file is ordinary checked-in source —
 reviewed in diffs, seen by clj-kondo, clojure-lsp, and CIDER exactly because
-it is not clever. Its header names the source component, its sha-256, and the
-form that regenerates it, so drift is visible where drift is looked for: in
-version control.
+it is not clever. Its header names the source component, a sha-256 **of the
+`describe` output** — the API, not the bytes, so a toolchain bump that
+changes the `@producers` section without changing a signature does not churn
+the header — and the form that regenerates it.
+
+**What the file cannot do is notice it is stale.** Nothing reads the header
+at run time; a `.wasm` swapped under an unregenerated file produces no diff
+anywhere. The *loud* half is already covered — marshalling is rebuilt from
+the live component at instantiate, so a renamed export fails
+`:no-such-export` with a did-you-mean and a changed argument list fails
+`:wrong-arity`. The silent half is exactly the regenerate-and-diff check
+that `cljwit.edn` (S2) owes its components; the API hash makes it a string
+compare. Until S2 exists, staleness detection is the reviewer's, and this
+paragraph is the warning.
 
 ### B. Every var takes the instance first
 
@@ -44,13 +60,20 @@ version control.
 
 `0015` measured why ambience loses: `binding` conveys to exactly the paths
 that race (`future`, `pmap`) and a lazy seq realised under a second instance
-runs against the second silently. The explicit argument is not a compromise —
-it is what makes handing an instance to a `future` a visible act. Arity and
-names now exist statically: `(thumbnail i img)` is a clj-kondo warning and an
+runs against the second silently. The explicit argument is what makes handing
+an instance to a `future` a visible act. Arity and names now exist
+statically: `(thumbnail i img)` is a clj-kondo warning and an
 `ArityException` naming `acme.resize/thumbnail`, not a gensym (`0015`'s
 macro-arity finding was about interned gensyms; a named `defn` does not have
 that problem).
 
+Two warts, named rather than hidden. A resource method takes **two**
+contexts — `(counter-bump i c 5)` — and the signature permits a handle from
+instance A with instance B. The runtime catches that mismatch when lowering
+the handle (`:wrong-instance`, since a `Handle` carries its context), which
+is a call-time error, not the visible act B advertises for instances; the
+docstring of every method var says which instance the handle must come from.
+
 ### C. Names: the last WIT segment, and a collision is an error
 
 The exact WIT string stays the runtime key inside the generated body — `0014`
@@ -65,38 +88,72 @@ WIT's grammar demands it:
 | `…#[method]counter.bump` | `counter-bump` |
 | `…#[static]counter.reset` | `counter-reset` |
 
-Two exports that munge to one name — two interfaces exporting `run`, say —
-**fail generation** with both WIT names in the message and a `:rename` option
-(`{:rename {"pkg:a/x@1.0.0#run" 'x-run}}`) as the exit. Silent suffixing
-(`run-2`) would bake an iteration order into an API; a namespace per
-interface multiplies files for a collision that `zoo.wit` — this repo's
-worst-case shape — does not have. Deterministic failure with a named exit
-follows `0014`'s nil-on-typo rule.
+The stripping **collides by construction** — the same finding that made
+`0014` B keep exact WIT strings at the key level. Both shapes were built and
+verified against the pinned wasm-tools during this note's adversarial
+review: a world exporting **two versions of one interface**
+(`acme:api/svc@1.0.0#run` / `…@2.0.0#run` — every function collides
+pairwise), and a single legal interface where `[method]counter.bump`
+strips to the same name as a plain export `counter-bump`.
+
+So a collision **fails generation** with the colliding WIT names in the
+message, and there are two exits at two granularities:
+
+- **`:interface`** — generate one namespace per interface:
+  `(gen/write-ns! wasm {:ns 'acme.api.v1 :interface "acme:api/svc@1.0.0"})`.
+  One option per interface, stable across regenerations. This is the exit
+  for the two-version world, where per-function renames would cost
+  O(functions) and have to be re-supplied verbatim forever.
+- **`:rename`** — `{:rename {"t:c/i#counter-bump" 'counter-bump2}}`, for a
+  leaf collision inside one interface.
+
+Silent suffixing (`run-2`) stays rejected: an API whose names depend on
+reflection order breaks on the component author's next reorder.
+Deterministic failure with a named exit follows `0014`'s nil-on-typo rule.
+
+A generated name that shadows `clojure.core` — `count`, `map`, `get` are
+all legal WIT identifiers — gets `(:refer-clojure :exclude [...])` computed
+into the `ns` form, because the measured alternative is a load-time warning
+per consumer and clj-kondo exiting 2, which takes this repo's own gate red.
+
+### D. One var per export, tagged — and `unwrap` lives in the library
+
+**Amended in review: the first draft generated a throwing `(f …)` plus a
+tagged `(f* …)`, and that inverted `0012`.** `0012`'s accepted decision is
+that the tagged value *is* the mapping and throwing is opt-in sugar; giving
+the throwing form the short, completion-first name is opt-out, not opt-in —
+and it hands `(map #(f i %) coll)` exactly the laziness hazard `0012`
+documents. It also encoded a type-level fact in the file: a stale throwing
+wrapper over an export whose return stopped being a `result` fails in
+undefined ways, silently.
+
+So: **one var per export, returning the value as `0012` maps it** — tagged,
+for a `result` return — and one function in the runtime library:
 
-### D. `result` in return position gets `0012`'s sugar here
+```clojure
+(host/unwrap (add i 2 3))   ; ok payload, or ex-info with :wit/error
+```
 
-This is the layer `0012` deferred to: `(f i args)` returns the ok payload and
-throws `ex-info` with the lifted error under `:wit/error` (the shrunk
-contract — no type name); `(f* i args)` returns `[:ok v]` / `[:err e]`
-untouched. Two vars, generated together, only for exports whose *return* is a
-`result`. Everywhere else one var, no throwing — `0012`'s laziness argument
-stands.
+Opt-in at the call site, zero generated duplication, and the sugar cannot go
+stale because it is not generated.
 
 ### E. Reflection moves to the artifact, and becomes public
 
-Generation needs exports and signatures without instantiating, and users have
-asked the same question of instances (`host/exports`, `host/signature`). The
-walk that `instantiate` does over the component type is extracted and exposed:
+Generation needs exports and signatures without instantiating. The walk that
+`instantiate` does over the component type is extracted and exposed:
 
 ```clojure
 (host/describe artifact)
 ;; => {"thumbnail" {:params [["img" {:kind :list :element :u8}] …]
 ;;                  :result {:kind :list :element :u8}}, …}
 ```
 
-`describe` is useful on its own — a REPL user's first question about an alien
-`.wasm` — and it is the single source the generator consumes, so the
-generated file can never disagree with what `instantiate` will find.
+`describe` is the single source the generator consumes, so the generated
+file agrees with what `instantiate` finds **at generation time** — staleness
+after that is A's problem, not E's. Docstrings render these trees in WIT
+syntax, and they are **structural**: reflection has no declared type names
+(`0012`'s amendment), so `take-flags: func(p: perms) -> perms` documents as
+`flags{read, write, exec}`, never as `perms`.
 
 ## Why
 
@@ -118,10 +175,15 @@ generated file can never disagree with what `instantiate` will find.
 - **Interning vars at instantiate** (`intern` from a plain function). Vars
   appear at run time, so clj-kondo and lsp are exactly as blind as with the
   macro, minus even the macro's syntactic marker.
-- **A namespace per WIT interface.** Buys collision-freedom `zoo.wit` does
-  not need, at the cost of a file explosion and an import dance for the
-  common one-interface world. Reopen if a real component's interface count
-  makes the flat namespace unreadable.
+- **A namespace per interface as the only mode.** The common one-interface
+  world would pay a file explosion for nothing. It survives as the
+  `:interface` *exit* instead — the first draft rejected it outright, on the
+  strength of `zoo.wit` not colliding, which is this project's recorded
+  failure shape: checking the artifact in the repo, not the artifact the
+  design is for.
+- **Two generated vars per `result` export** (the first draft's D). Inverted
+  `0012`, doubled the surface, and created the one staleness mode the
+  runtime cannot catch.
 - **Silent collision suffixes.** An API whose names depend on reflection
   order breaks on the component author's next reorder.
 - **Emitting `defprotocol`/`definterface` for call-site speed.** `0013`:
@@ -132,9 +194,11 @@ generated file can never disagree with what `instantiate` will find.
 
 - A WIT export name whose last segment is not a readable Clojure symbol
   after the munge table above — the generator refuses it today; a real
-  component hitting that refusal reopens C.
-- A component whose regenerated file churns on every toolchain bump (sha in
-  the header making diffs noisy) — would argue for dropping the sha line.
-- clj-kondo flagging the generated shape itself — would demand a header
-  directive, and is checkable in this repo's own gate by generating against
-  a fixture and linting the output.
+  component hitting that refusal reopens C. (Names that *shadow* — `count`,
+  `map` — are already handled by the computed `:refer-clojure :exclude`.)
+- A real component whose interface count makes even `:interface`-split
+  namespaces unreadable — reopens C's granularity.
+- clj-kondo flagging the generated shape itself — the gate generates
+  against a fixture whose exports include a `clojure.core` shadow and a
+  `result` return, and the review measured arity warnings working through
+  exactly this shape.
@@ -433,7 +433,11 @@
     (lower alloc m v)
     m))
 
-(defn- lower-fn [tree]
+(defn- lower-fn
+  "`ctx` is the store the compiled call belongs to, when there is one to
+   check handles against; the import direction passes nil (a resource in an
+   import's signature routes through the rep table, never here)."
+  [tree ctx]
   (if (keyword? tree)
     (case tree
       :string (fn [alloc ^MemorySegment seg v]
@@ -444,6 +448,13 @@
         (fn [_ ^MemorySegment seg v]
           (let [^Handle h v
                 ^MemorySegment p (live-ptr h (if own? "transferring" "borrowing"))]
+            ;; A handle from another instance would surface as wasmtime's
+            ;; `mismatched resource types` -- an error about the wrong thing.
+            ;; The handle knows its store; say so instead (0020 B).
+            (when (and ctx (not= (.address ^MemorySegment (.-ctx h))
+                                 (.address ^MemorySegment ctx)))
+              (throw (ex-info "resource handle belongs to a different instance"
+                              {:cljwit/error :wrong-instance})))
             (.set seg I8 (long 0) (byte RESOURCE))
             (.set seg ADDR (long UNION) p)
             ;; A borrow leaves the handle live; an own is stale the moment the
@@ -454,15 +465,15 @@
       :enum (fn [alloc ^MemorySegment seg v]
               (.set seg I8 (long 0) (byte 17))
               (write-name! alloc seg UNION (name v)))
-      :option (let [inner (lower-fn (:ty tree))]
+      :option (let [inner (lower-fn (:ty tree) ctx)]
                 (fn [alloc ^MemorySegment seg v]
                   (.set seg I8 (long 0) (byte 18))
                   (let [^MemorySegment q (if (nil? v)
                                            MemorySegment/NULL
                                            (val-of inner alloc v))]
                     (.set seg ADDR (long UNION) q))))
-      :result (let [lo (some-> (:ok tree) lower-fn)
-                    le (some-> (:err tree) lower-fn)]
+      :result (let [lo (some-> (:ok tree) (lower-fn ctx))
+                    le (some-> (:err tree) (lower-fn ctx))]
                 (fn [alloc ^MemorySegment seg v]
                   (let [[tag payload] v
                         ok? (= :ok tag)
@@ -473,7 +484,7 @@
                                              MemorySegment/NULL
                                              (val-of f alloc payload))]
                       (.set seg ADDR (long RES-VAL) q)))))
-      :variant (let [lowers (into {} (map (fn [[n t]] [n (some-> t lower-fn)]))
+      :variant (let [lowers (into {} (map (fn [[n t]] [n (some-> t (lower-fn ctx))]))
                                   (:cases tree))]
                  (fn [alloc ^MemorySegment seg v]
                    (let [[tag payload] v
@@ -496,7 +507,7 @@
                    (.set seg I8 (long 0) (byte 20))
                    (.set seg I64 (long (+ UNION VEC-SIZE)) (long (count on)))
                    (.set seg ADDR (long (+ UNION VEC-DATA)) buf))))
-      :tuple (let [els (mapv lower-fn (:types tree))]
+      :tuple (let [els (mapv #(lower-fn % ctx) (:types tree))]
                (fn [alloc ^MemorySegment seg v]
                  (let [n   (count els)
                        buf ^MemorySegment (alloc (max 1 (* VAL n)))]
@@ -505,7 +516,7 @@
                    (.set seg I8 (long 0) (byte 15))
                    (.set seg I64 (long (+ UNION VEC-SIZE)) (long n))
                    (.set seg ADDR (long (+ UNION VEC-DATA)) buf))))
-      :list (let [el (lower-fn (:element tree))]
+      :list (let [el (lower-fn (:element tree) ctx)]
               (fn [alloc ^MemorySegment seg v]
                 (let [n   (count v)
                       buf ^MemorySegment (alloc (max 1 (* VAL n)))]
@@ -514,7 +525,7 @@
                   (.set seg I8 (long 0) (byte 13))
                   (.set seg I64 (long (+ UNION VEC-SIZE)) (long n))
                   (.set seg ADDR (long (+ UNION VEC-DATA)) buf))))
-      :record (let [fs (mapv (fn [[n t]] [n (lower-fn t)]) (:fields tree))]
+      :record (let [fs (mapv (fn [[n t]] [n (lower-fn t ctx)]) (:fields tree))]
                 (fn [alloc ^MemorySegment seg v]
                   ;; Fields go out in declaration order: a Clojure map has none.
                   (let [buf ^MemorySegment (alloc (* ENTRY (count fs)))]
@@ -706,7 +717,7 @@
                      (invoke (:hres-delete api) hr)
                      (.set seg I8 (long 0) (byte RESOURCE))
                      (.set seg ADDR (long UNION) ^MemorySegment (.get out ADDR (long 0)))))
-                 :else (lower-fn rt))
+                 :else (lower-fn rt nil))
         ;; 0017 C: wasmtime frees what the callback writes, so every byte of a
         ;; result comes from malloc. Measured: an Arena pointer survives one
         ;; call and aborts the process at 2000.
@@ -913,7 +924,7 @@
    (`0014` E)."
   [api ^Arena arena ^MemorySegment ctx ^MemorySegment f sig
    ^AtomicBoolean closed ^AtomicReference in-call nm rt dead]
-  (let [ptypes  (mapv (comp lower-fn second) (:params sig))
+  (let [ptypes  (mapv (fn [[_ t]] (lower-fn t ctx)) (:params sig))
         n       (count ptypes)
         rlift   (when (:result sig) (lift-fn (:result sig) rt))
         args    ^MemorySegment (.allocate arena (long (max 1 (* VAL n))))
@@ -1321,6 +1332,23 @@
   [^Instance i]
   (let [a (:errs (.-rtab i))] (first (swap-vals! a (constantly [])))))
 
+(defn unwrap
+  "`0012`'s result sugar, as a library function rather than a generated
+   wrapper (`0020` D): `[:ok v]` → v, `[:err e]` → ex-info carrying e under
+   :wit/error. Anything else passes through untouched, so it composes over
+   exports that are not result-typed — which also means a *variant* whose
+   case happens to be named ok or err is indistinguishable here; unwrap is
+   opt-in for exactly that reason."
+  [v]
+  (if (and (vector? v) (= 2 (count v)))
+    (case (nth v 0)
+      :ok  (nth v 1)
+      :err (throw (ex-info (str "component returned an error: " (pr-str (nth v 1)))
+                           {:cljwit/error :wit-error
+                            :wit/error (nth v 1)}))
+      v)
+    v))
+
 (defn exports
   "Every exported function, by its exact WIT name."
   [^Instance i]