feat(tw_verify): v2-parse support for affinescript.ownership (ADR-020)

Lands the verifier-side (parse) half of ADR-020 (ownership-section
schema versioning), per ADR-021's coordinated landing protocol —
verifier ships parse-support FIRST, then producers flip emit
together.  This PR is the AffineScript leg.

On-wire change (parse-only this PR; emit stays on v1):

  v1 (legacy, unversioned, what we emit today):
    u32le  count
    entry*

  v2 (ADR-020, parse-only here):
    u8     0xAF       (* sentinel — "AffineScript Format" *)
    u8     version    (* 0x02 *)
    u32le  count
    entry*            (* same entry shape as v1 *)

Dispatch: a v2 section starts with the 0xAF sentinel byte.  v1
readers fail cleanly on v2 sections (the sentinel pollutes the
entry-count low byte and yields an implausible count); v2 readers
see the sentinel and branch.  Unknown v2.X versions yield [] (sound
fallback per ADR-021's conservative-disposition axis: loud-correct
rather than silent-wrong).

What this PR does:

  * lib/tw_verify.ml `parse_ownership_section_payload` — now
    dispatches v1 vs v2 on the leading sentinel byte; v1 path
    preserved verbatim, v2 path adds two leading bytes + identical
    entry decoding.
  * test/test_e2e.ml — two new hermetic alcotest cases under
    "E2E TypedWasm ownership schema":
      * v2 parse round-trip on a hand-constructed payload
      * v2.99 (unknown future version) -> [] (sound fallback).

What this PR does NOT do (deliberately):

  * Does NOT flip the producer-side emitter — that stays on v1
    until hyperpolymath/typed-wasm's Rust verifier and
    hyperpolymath/ephapax's verifier also ship parse-support.
    Coordinated landing per ADR-021 axis 2.
  * Does NOT re-add ADR-020 / ADR-021 to META.a2ml or the
    docs/specs/TYPED-WASM-COORDINATION-LEDGER files.  Both ADRs
    are owner-ratified (2026-05-24); the file artefacts were lost
    in PR #344's squash-merge.  This PR cites them inline (verifier
    comment + commit message) and a separate doc-only follow-up
    should restore them to META.a2ml.

Not yet locally verified — no OCaml toolchain in remote execution
env.  CI is the verification surface.  The v1 path is byte-for-byte
unchanged from the pre-PR shape; the v2 path is new code reachable
only on a sentinel byte AffineScript does not currently emit.  So
the existing v1 round-trip tests (test_ownership_*) MUST still
pass; the two new v2 tests are pure addition.

Refs ADR-020 (parse-side), ADR-021 (coordinated landing).

Author: claude

lib/tw_verify.ml

@@ -187,13 +187,34 @@ let verify_module
 (** Parse the [affinescript.ownership] custom section payload into structured
     [(func_idx, param_kinds, ret_kind)] annotations.
 
-    Binary encoding (from [Codegen.build_ownership_section]):
+    Supports BOTH v1 (legacy, unversioned) and v2 (ADR-020, accepted
+    + ratified 2026-05-24) on-wire formats; v2 is identified by the
+    [0xAF] sentinel byte followed by a version byte.  v1 readers
+    fail cleanly on v2 sections (the sentinel pollutes the
+    entry-count low byte and yields an implausible count); v2
+    readers see the sentinel and dispatch.
+
+    v1 layout (legacy, unversioned):
       u32le  count
       for each entry:
         u32le  func_idx
         u8     n_params
         u8[n]  param_kinds  (0=Unrestricted, 1=Linear, 2=SharedBorrow, 3=ExclBorrow)
-        u8     ret_kind *)
+        u8     ret_kind
+
+    v2 layout (ADR-020):
+      u8     0xAF         (* "AffineScript Format" sentinel *)
+      u8     version      (* 0x02 for v2.0 *)
+      u32le  count
+      entry*              (* same entry shape as v1 *)
+
+    Per ADR-021's coordinated landing protocol, this verifier ships
+    parse-support FIRST.  AffineScript's emitter ([Codegen.build_ownership_
+    section] / [Tw_ownership_section.build_section]) stays on v1 until
+    [hyperpolymath/typed-wasm]'s Rust verifier + [hyperpolymath/ephapax]'s
+    OCaml verifier also ship parse-support; then all producers flip to v2
+    emit together.  See [docs/specs/TYPED-WASM-COORDINATION-LEDGER.adoc]
+    Q-001 for the current state of the cross-repo rollout. *)
 let parse_ownership_section_payload
     (payload : bytes)
   : (int * ownership_kind list * ownership_kind) list =
@@ -205,33 +226,81 @@ let parse_ownership_section_payload
   in
   let pos = ref 0 in
   let len = Bytes.length payload in
-  let read_u32_le () =
-    if !pos + 4 > len then 0
-    else begin
-      let b0 = Char.code (Bytes.get payload  !pos)      in
-      let b1 = Char.code (Bytes.get payload (!pos + 1)) in
-      let b2 = Char.code (Bytes.get payload (!pos + 2)) in
-      let b3 = Char.code (Bytes.get payload (!pos + 3)) in
-      pos := !pos + 4;
-      b0 lor (b1 lsl 8) lor (b2 lsl 16) lor (b3 lsl 24)
-    end
+  (* v2 sentinel dispatch.  Two bytes minimum: [0xAF, version].  The
+     sentinel is byte-distinct from any v1 entry-count low byte for
+     a module with <= 0xAE entries (i.e. effectively every module);
+     ADR-020 catalogues this trade-off explicitly. *)
+  let v2_detected =
+    len >= 2
+    && Char.code (Bytes.get payload 0) = 0xAF
   in
-  let read_u8 () =
-    if !pos >= len then 0
-    else begin
-      let b = Char.code (Bytes.get payload !pos) in
-      pos := !pos + 1;
-      b
-    end
-  in
-  let count = read_u32_le () in
-  List.init count (fun _ ->
-    let func_idx    = read_u32_le () in
-    let n_params    = read_u8 ()     in
-    let param_kinds = List.init n_params (fun _ -> kind_of_byte (read_u8 ())) in
-    let ret_kind    = kind_of_byte (read_u8 ()) in
-    (func_idx, param_kinds, ret_kind)
-  )
+  if v2_detected then begin
+    let v2_version = Char.code (Bytes.get payload 1) in
+    pos := 2;
+    (* v2.0 is the only known version today.  An unknown v2.X is a
+       future-version section we cannot interpret; per ADR-021
+       conservative-disposition (sound fallback), treat as empty.
+       The verifier therefore enforces nothing on the section —
+       loud-correct rather than silent-wrong. *)
+    if v2_version <> 0x02 then []
+    else
+      let read_u32_le () =
+        if !pos + 4 > len then 0
+        else begin
+          let b0 = Char.code (Bytes.get payload  !pos)      in
+          let b1 = Char.code (Bytes.get payload (!pos + 1)) in
+          let b2 = Char.code (Bytes.get payload (!pos + 2)) in
+          let b3 = Char.code (Bytes.get payload (!pos + 3)) in
+          pos := !pos + 4;
+          b0 lor (b1 lsl 8) lor (b2 lsl 16) lor (b3 lsl 24)
+        end
+      in
+      let read_u8 () =
+        if !pos >= len then 0
+        else begin
+          let b = Char.code (Bytes.get payload !pos) in
+          pos := !pos + 1;
+          b
+        end
+      in
+      let count = read_u32_le () in
+      List.init count (fun _ ->
+        let func_idx    = read_u32_le () in
+        let n_params    = read_u8 ()     in
+        let param_kinds = List.init n_params (fun _ -> kind_of_byte (read_u8 ())) in
+        let ret_kind    = kind_of_byte (read_u8 ()) in
+        (func_idx, param_kinds, ret_kind))
+  end else begin
+    (* v1 (legacy) path.  Identical to the pre-ADR-020 behaviour;
+       preserved verbatim for backward compatibility with already-
+       emitted modules and with the in-tree fixtures. *)
+    let read_u32_le () =
+      if !pos + 4 > len then 0
+      else begin
+        let b0 = Char.code (Bytes.get payload  !pos)      in
+        let b1 = Char.code (Bytes.get payload (!pos + 1)) in
+        let b2 = Char.code (Bytes.get payload (!pos + 2)) in
+        let b3 = Char.code (Bytes.get payload (!pos + 3)) in
+        pos := !pos + 4;
+        b0 lor (b1 lsl 8) lor (b2 lsl 16) lor (b3 lsl 24)
+      end
+    in
+    let read_u8 () =
+      if !pos >= len then 0
+      else begin
+        let b = Char.code (Bytes.get payload !pos) in
+        pos := !pos + 1;
+        b
+      end
+    in
+    let count = read_u32_le () in
+    List.init count (fun _ ->
+      let func_idx    = read_u32_le () in
+      let n_params    = read_u8 ()     in
+      let param_kinds = List.init n_params (fun _ -> kind_of_byte (read_u8 ())) in
+      let ret_kind    = kind_of_byte (read_u8 ()) in
+      (func_idx, param_kinds, ret_kind))
+  end
 
 (** Level 13 — module isolation (negative form). A well-isolated
     module owns its private linear memory and reaches other modules

test/test_e2e.ml

@@ -1214,10 +1214,58 @@ let test_ownership_entry_count () =
       Alcotest.(check bool) "at least 4 entries (one per function)" true
         (List.length entries >= 4)
 
+(* ADR-020 (accepted + ratified 2026-05-24): hermetic round-trip on a
+   hand-constructed v2 payload — 0xAF sentinel + u8 version 0x02 +
+   the same entry shape as v1.  Verifier-parse-support is the FIRST
+   leg of the coordinated landing per ADR-021 axis 2; this test
+   pins the v2 parse contract against the gate.  Future v2.X versions
+   that this v2.0 reader does not understand MUST yield an empty
+   annotation list (sound fallback). *)
+let test_ownership_v2_parse_roundtrip () =
+  let buf = Buffer.create 32 in
+  let add_u8 n = Buffer.add_char buf (Char.chr (n land 0xff)) in
+  let add_u32_le n =
+    add_u8 (n land 0xff);
+    add_u8 ((n lsr  8) land 0xff);
+    add_u8 ((n lsr 16) land 0xff);
+    add_u8 ((n lsr 24) land 0xff)
+  in
+  (* v2 header *)
+  add_u8 0xAF;
+  add_u8 0x02;
+  (* one entry: func 7, params [Linear; SharedBorrow], ret Unrestricted *)
+  add_u32_le 1;
+  add_u32_le 7;
+  add_u8 2;
+  add_u8 1;       (* Linear *)
+  add_u8 2;       (* SharedBorrow *)
+  add_u8 0;       (* Unrestricted ret *)
+  let payload = Buffer.to_bytes buf in
+  let entries = Tw_verify.parse_ownership_section_payload payload in
+  match entries with
+  | [(7, [Codegen.Linear; Codegen.SharedBorrow], Codegen.Unrestricted)] -> ()
+  | other ->
+    Alcotest.failf
+      "v2 parse mismatch: got %d entries (expected exactly the one canonical entry)"
+      (List.length other)
+
+let test_ownership_v2_unknown_version_empty () =
+  (* A v2.99 section (unknown future version) must yield [] — sound
+     fallback per ADR-021 conservative-disposition. *)
+  let buf = Buffer.create 4 in
+  Buffer.add_char buf (Char.chr 0xAF);
+  Buffer.add_char buf (Char.chr 0x99);
+  Buffer.add_char buf (Char.chr 0x00);
+  Buffer.add_char buf (Char.chr 0x00);
+  let entries = Tw_verify.parse_ownership_section_payload (Buffer.to_bytes buf) in
+  Alcotest.(check int) "unknown v2.X yields []" 0 (List.length entries)
+
 let ownership_schema_tests = [
-  Alcotest.test_case "section present"   `Quick test_ownership_section_present;
-  Alcotest.test_case "round-trip kinds"  `Quick test_ownership_roundtrip;
-  Alcotest.test_case "entry count"       `Quick test_ownership_entry_count;
+  Alcotest.test_case "section present"           `Quick test_ownership_section_present;
+  Alcotest.test_case "round-trip kinds"          `Quick test_ownership_roundtrip;
+  Alcotest.test_case "entry count"               `Quick test_ownership_entry_count;
+  Alcotest.test_case "v2 parse round-trip (ADR-020)"      `Quick test_ownership_v2_parse_roundtrip;
+  Alcotest.test_case "v2 unknown version -> [] (ADR-021)" `Quick test_ownership_v2_unknown_version_empty;
 ]
 
 (* ============================================================================