Merge branch 'main' into claude/fix-borrow-ml-comment-1304

Author: hyperpolymath

.claude/CLAUDE.md

@@ -140,3 +140,117 @@ Rule: An issue is closed only by explicit merge of a PR with "Closes #N" OR by e
 Action (Hypatia): When asked to close an issue, confirm via a reply on the issue thread before doing so.
 Action (gitbot): Never use GitHub's "close issue" API directly; only close via PR merge with "Closes #N" keywords.
 
+## Agent operations notes
+
+Practical guidance for agents (Claude / other) operating in this repo,
+captured from parallel-bot session experience. Read once; saves turns.
+
+### CI signal reliability
+
+**"PR merged" does NOT mean "build green".** Auto-merge on this repo
+currently fires even when `build` or `lint` is failing — multiple
+recently-merged PRs (#334, #335, #336, #344) landed with `build` red,
+and the red persisted until PR #346's `FnExtern` interp fix. If you
+inherit a session reasoning about a recently-merged PR, do not assume
+its CI was green; check `mcp__github__pull_request_read` with method
+`get_check_runs` for the actual statuses, and check whether `main`
+itself is currently red before treating a build failure on your own
+PR as something *you* introduced.
+
+### Reading CI logs
+
+`WebFetch` against the GitHub Actions UI returns the React skeleton,
+not the log content. The fast paths for an agent are:
+
+* `mcp__github__pull_request_read` with method `get_check_runs` —
+  per-job status (queued / in_progress / success / failure) with
+  `details_url`. Sufficient for "did the build pass".
+* `mcp__github__pull_request_read` with method `get_status` —
+  combined commit status.
+* For actual log lines on a failed run, hand back to the user with
+  `gh run view --log-failed <run-id>`; do not loop trying to scrape
+  the UI.
+
+### Known-failing baseline checks
+
+These checks currently fail on *every* PR for repo-wide reasons, not
+because of any individual PR's changes. Do not waste turns
+investigating them on a per-PR basis:
+
+* `vscode-smoke` — npm 404 on `@hyperpolymath/affine-vscode` (the
+  in-editor harness depends on a not-yet-published npm package).
+* `migration-assistant` — was fixed by #342, but any branch created
+  from a base older than #342 will still see it red until rebased.
+* `governance / Language / package anti-pattern policy` — flags the
+  approved TypeScript exemptions (`affinescript-deno-test/*.ts`,
+  `editors/vscode/test/*.js`, etc., all documented in this file's
+  exemptions tables); the check has no allowlist for them.
+* The Hypatia security-scan bot comment — 143 findings; the bulk are
+  the same TypeScript exemption hits + pre-existing root files. A
+  real new finding will show as a *delta* in the count; otherwise
+  ignore.
+
+If a check from this list *changes status* on a PR (e.g.
+`vscode-smoke` suddenly passes, or Hypatia surfaces a new class of
+finding), that's signal worth investigating.
+
+### Branching discipline with concurrent merges
+
+When multiple agents are spawned in parallel, branch-creation time
+can lag `main` by hours and a stale base will silently revert other
+agents' work at merge time. **Before pushing any branch, run:**
+
+```
+git fetch origin main
+git rebase origin/main
+```
+
+Not just at branch-creation; immediately before push, after any
+in-session work. This guards against parallel-merge drift. Claude 1's
+STDLIB-04c branch (#337) accidentally reverted #334 and #335 because
+its base was stale; force-rebased to fix. Cheap to prevent, expensive
+to clean up.
+
+### Post-squash-merge branch divergence
+
+When a PR is squash-merged, the squashed commit on `main` gets a
+*new* SHA, distinct from any of the source-branch commits. If you
+then reset your local branch to `main` (or simply re-resolve it),
+`git status` reports N "ahead of origin/branch" — but those N
+commits are just the main-side commits the obsolete remote
+branch-tip never saw, not unpushed work.
+
+Recognising the situation:
+
+* The branch was already merged (PR closed, `merged: true`).
+* The local working tree matches `main`.
+* The remote branch still points at the *pre-merge* tip
+  (`origin/<branch>` is an old SHA, not the squashed one).
+* `git log origin/<branch>..HEAD` lists commits that look like
+  other people's work.
+
+Safe fix — pick the one matching intent:
+
+```
+git push origin --delete <branch>            # done with the branch
+git push --force-with-lease origin <branch>  # align the remote to main
+```
+
+`--force-with-lease` is safe here because nothing on the remote
+branch is unmerged work; force-push without `--lease` only matters
+if someone else pushed concurrently, which is irrelevant for an
+already-merged branch you're cleaning up.
+
+### Test-fixture hygiene for latent bug surfaces
+
+When you add a stdlib `extern fn` (or any other new declaration
+shape), add a test that feeds it to *every* downstream consumer
+(parse, resolve, typecheck, interp, every codegen target that
+shouldn't reject it). The PR #346 `FnExtern` interp bug had survived
+since the interpreter was written because no test had ever fed an
+inline `extern fn` to `Interp.eval_program` — STDLIB-04a's tests
+were the first, and only then did the missing match arm fire.
+
+Treat "first user of an existing-but-untested declaration shape" as a
+class-level surface, not a single test case.
+

lib/codegen.ml

@@ -11,12 +11,17 @@ open Ast
 open Wasm
 
 (** Ownership kind for typed-wasm schema annotations.
-    Maps AffineScript ownership qualifiers to typed-wasm Level 7/10 verification. *)
-type ownership_kind =
-  | Unrestricted  (** Plain value, no ownership constraint (Wasm i32/f64 etc.) *)
-  | Linear        (** TyOwn / own — consumed exactly once (typed-wasm Level 10 linearity) *)
-  | SharedBorrow  (** TyRef / ref — read-only aliasing safety (typed-wasm Level 7) *)
-  | ExclBorrow    (** TyMut / mut — exclusive mutable aliasing safety (typed-wasm Level 7) *)
+
+    Re-exported from [Tw_ownership_section] (the dedicated home,
+    extracted 2026-05-24 per A3 of TYPED-WASM-ROADMAP.adoc).  The
+    type equation preserves constructor accessibility so
+    [Codegen.Linear] etc. continue to resolve and [open Codegen]
+    in [Tw_verify] / [Tw_interface] / [Test_e2e] is unaffected. *)
+type ownership_kind = Tw_ownership_section.ownership_kind =
+  | Unrestricted
+  | Linear
+  | SharedBorrow
+  | ExclBorrow
 
 (** Code generation context *)
 type context = {
@@ -111,19 +116,9 @@ let create_context () : context = {
   wasi_func_indices = [];
 }
 
-(** Extract ownership kind from a parameter declaration.
-    Checks p_ownership first; falls back to the shape of p_ty. *)
-let ownership_kind_of_param (p : param) : ownership_kind =
-  match p.p_ownership with
-  | Some Own -> Linear
-  | Some Ref -> SharedBorrow
-  | Some Mut -> ExclBorrow
-  | None ->
-    match p.p_ty with
-    | TyOwn _ -> Linear
-    | TyRef _ -> SharedBorrow
-    | TyMut _ -> ExclBorrow
-    | _ -> Unrestricted
+(** Extract ownership kind from a parameter declaration. Re-exported
+    from [Tw_ownership_section] (A3 refactor, 2026-05-24). *)
+let ownership_kind_of_param = Tw_ownership_section.ownership_kind_of_param
 
 (** If [ty] names a known struct (through any number of own/ref/mut wrappers),
     return that struct's name. Lets us recover a struct's field layout from
@@ -136,45 +131,21 @@ let rec struct_name_of_ty (ty : type_expr) : string option =
   | TyOwn inner | TyRef inner | TyMut inner -> struct_name_of_ty inner
   | _ -> None
 
-(** Extract ownership kind from an optional return type expression *)
-let ownership_kind_of_ret (ret : type_expr option) : ownership_kind =
-  match ret with
-  | Some (TyOwn _) -> Linear
-  | Some (TyRef _) -> SharedBorrow
-  | Some (TyMut _) -> ExclBorrow
-  | _ -> Unrestricted
+(** Extract ownership kind from an optional return type expression.
+    Re-exported from [Tw_ownership_section]. *)
+let ownership_kind_of_ret = Tw_ownership_section.ownership_kind_of_ret
 
-(** Encode an ownership_kind as a single byte (0–3) *)
-let ownership_kind_byte = function
-  | Unrestricted -> 0 | Linear -> 1 | SharedBorrow -> 2 | ExclBorrow -> 3
+(** Encode an ownership_kind as a single byte (0–3).
+    Re-exported from [Tw_ownership_section]. *)
+let ownership_kind_byte = Tw_ownership_section.ownership_kind_byte
 
 (** Build the payload for the [affinescript.ownership] Wasm custom section.
-    Encoding (all little-endian):
-      u32  entry_count
-      per entry:
-        u32  func_index
-        u8   param_count
-        u8*  param_kind  (one per param, see kind encoding above)
-        u8   return_kind *)
-let build_ownership_section (annots : (int * ownership_kind list * ownership_kind) list) : bytes =
-  if annots = [] then Bytes.empty
-  else
-    let buf = Buffer.create 64 in
-    let write_u32_le n =
-      Buffer.add_char buf (Char.chr  (n         land 0xff));
-      Buffer.add_char buf (Char.chr ((n lsr  8) land 0xff));
-      Buffer.add_char buf (Char.chr ((n lsr 16) land 0xff));
-      Buffer.add_char buf (Char.chr ((n lsr 24) land 0xff))
-    in
-    let write_u8 n = Buffer.add_char buf (Char.chr (n land 0xff)) in
-    write_u32_le (List.length annots);
-    List.iter (fun (func_idx, param_kinds, ret_kind) ->
-      write_u32_le func_idx;
-      write_u8 (List.length param_kinds);
-      List.iter (fun k -> write_u8 (ownership_kind_byte k)) param_kinds;
-      write_u8 (ownership_kind_byte ret_kind)
-    ) annots;
-    Buffer.to_bytes buf
+    Re-exported from [Tw_ownership_section.build_section] (A3 refactor,
+    2026-05-24).  The dedicated module is the home for the on-wire format;
+    this alias preserves the [Codegen.build_ownership_section] public
+    API surface that downstream callers (lib/tw_verify.ml,
+    lib/tw_interface.ml, test/test_e2e.ml) rely on. *)
+let build_ownership_section = Tw_ownership_section.build_section
 
 (** Map AffineScript type to WASM value type *)
 let type_to_wasm (ty : type_expr) : value_type result =

lib/interp.ml

@@ -1027,14 +1027,25 @@ let create_initial_env () : env =
 let eval_decl (env : env) (decl : top_level) : env result =
   match decl with
   | TopFn fd ->
-    let closure = VClosure {
-      cl_params = fd.fd_params;
-      cl_body = (match fd.fd_body with
-        | FnBlock blk -> ExprBlock blk
-        | FnExpr e -> e);
-      cl_env = env;
-    } in
-    Ok (extend_env fd.fd_name.name closure env)
+    (match fd.fd_body with
+     | FnExtern ->
+       (* Externs have no AST body to evaluate. Their runtime binding is
+          provided by [create_initial_env]'s builtin table (panic, error,
+          make_ref, …). Skip here so an inline `extern fn` declaration in
+          a test source (e.g. the STDLIB-04a Mut round-trip tests) doesn't
+          blow up the [FnBlock|FnExpr] match below.
+          Refs #328 root-cause for the interp pattern-match-failure. *)
+       Ok env
+     | FnBlock _ | FnExpr _ ->
+       let closure = VClosure {
+         cl_params = fd.fd_params;
+         cl_body = (match fd.fd_body with
+           | FnBlock blk -> ExprBlock blk
+           | FnExpr e -> e
+           | FnExtern -> assert false (* unreachable: outer match guards *));
+         cl_env = env;
+       } in
+       Ok (extend_env fd.fd_name.name closure env))
 
   | TopConst tc ->
     let* v = eval env tc.tc_value in

lib/tw_ownership_section.ml

@@ -0,0 +1,96 @@
+(* SPDX-License-Identifier: MPL-2.0 *)
+(* SPDX-FileCopyrightText: 2026 hyperpolymath *)
+(*
+ * tw_ownership_section.ml — the dedicated home for the
+ * `affinescript.ownership` Wasm custom section: kind encoding,
+ * extraction from the AST, and binary serialisation.
+ *
+ * Extracted from lib/codegen.ml at 2026-05-24 per Tranche A3 of
+ * docs/specs/TYPED-WASM-ROADMAP.adoc. Behaviour-preserving move.
+ *
+ * The format itself is specified in
+ * docs/specs/TYPED-WASM-INTERFACE.adoc (v1, current) and
+ * docs/specs/TYPED-WASM-ROADMAP.adoc §"Tranche B" (v2, the
+ * ratified ADR-020 widening; landed via [Tw_verify] parse-support
+ * first, with the producer-emit flip deferred to the coordinated
+ * landing window per ADR-021 — see TYPED-WASM-COORDINATION-LEDGER.adoc
+ * Q-001).
+ *
+ * Backwards compatibility: [Codegen] re-exports the same names so
+ * `open Codegen` continues to expose [ownership_kind] and friends —
+ * downstream callers ([Tw_verify], [Tw_interface], [Test_e2e]) need
+ * no change.
+ *)
+
+open Ast
+
+(** Ownership kind for typed-wasm schema annotations.
+    Maps AffineScript ownership qualifiers to typed-wasm Level 7/10
+    verification. *)
+type ownership_kind =
+  | Unrestricted  (** Plain value, no ownership constraint (Wasm i32/f64 etc.) *)
+  | Linear        (** TyOwn / own — consumed exactly once (typed-wasm Level 10) *)
+  | SharedBorrow  (** TyRef / ref — read-only aliasing safety (typed-wasm Level 7) *)
+  | ExclBorrow    (** TyMut / mut — exclusive mutable aliasing safety (typed-wasm Level 7) *)
+
+(** Extract ownership kind from a parameter declaration.
+    Checks [p.p_ownership] first; falls back to the shape of [p.p_ty]. *)
+let ownership_kind_of_param (p : param) : ownership_kind =
+  match p.p_ownership with
+  | Some Own -> Linear
+  | Some Ref -> SharedBorrow
+  | Some Mut -> ExclBorrow
+  | None ->
+    match p.p_ty with
+    | TyOwn _ -> Linear
+    | TyRef _ -> SharedBorrow
+    | TyMut _ -> ExclBorrow
+    | _ -> Unrestricted
+
+(** Extract ownership kind from an optional return type expression *)
+let ownership_kind_of_ret (ret : type_expr option) : ownership_kind =
+  match ret with
+  | Some (TyOwn _) -> Linear
+  | Some (TyRef _) -> SharedBorrow
+  | Some (TyMut _) -> ExclBorrow
+  | _ -> Unrestricted
+
+(** Encode an [ownership_kind] as a single byte (0..3). *)
+let ownership_kind_byte = function
+  | Unrestricted -> 0
+  | Linear -> 1
+  | SharedBorrow -> 2
+  | ExclBorrow -> 3
+
+(** Build the payload for the [affinescript.ownership] Wasm custom section.
+
+    v1 encoding (current emit; LE):
+      u32  entry_count
+      per entry:
+        u32  func_index
+        u8   param_count
+        u8*  param_kind  (one per param, see kind encoding above)
+        u8   return_kind
+
+    Returns [Bytes.empty] when there are no annotations so the
+    caller can omit the section entirely. *)
+let build_section
+    (annots : (int * ownership_kind list * ownership_kind) list) : bytes =
+  if annots = [] then Bytes.empty
+  else
+    let buf = Buffer.create 64 in
+    let write_u32_le n =
+      Buffer.add_char buf (Char.chr  (n         land 0xff));
+      Buffer.add_char buf (Char.chr ((n lsr  8) land 0xff));
+      Buffer.add_char buf (Char.chr ((n lsr 16) land 0xff));
+      Buffer.add_char buf (Char.chr ((n lsr 24) land 0xff))
+    in
+    let write_u8 n = Buffer.add_char buf (Char.chr (n land 0xff)) in
+    write_u32_le (List.length annots);
+    List.iter (fun (func_idx, param_kinds, ret_kind) ->
+      write_u32_le func_idx;
+      write_u8 (List.length param_kinds);
+      List.iter (fun k -> write_u8 (ownership_kind_byte k)) param_kinds;
+      write_u8 (ownership_kind_byte ret_kind)
+    ) annots;
+    Buffer.to_bytes buf