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

## Summary

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.

**Depends on:** #350 (restores the ADR-020/021 + coordination ledger
records this PR references).

## 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` — 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 (ADR-020)` — hand-constructed v2 payload, asserts
canonical entry.
- `v2 unknown version -> [] (ADR-021)` — v2.99 (future version) yields
`[]`.

## 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
("verifier ships first").
- Once the sister repos land parse-support, the producer-emit flip is a
separate atomic PR across all three repos.

## Coordination ledger state

After this PR merges, **Q-001** in
`docs/specs/TYPED-WASM-COORDINATION-LEDGER.adoc` is partially de-blocked
on the AffineScript leg:
- `local.verifier-work`: ✅ shipped (this PR)
- `local.producer-work`: ⏳ still v1 emit (correct — verifier-first)
- `typed-wasm.verifier-work`: ⏳ awaiting sister-repo PR
- `ephapax.verifier-work`: ⏳ awaiting sister-repo PR

## Test plan

- [ ] CI `build` job clean
- [ ] CI `dune runtest` green (existing `ownership_schema_tests` v1
round-trips MUST still pass; two new v2 cases land as additions)
- [ ] No new lints
- [ ] Cross-references in commit message / verifier comment resolve once
#350 merges

Refs ADR-020 (parse-side), ADR-021 (coordinated landing).
Depends on: #350

---
_Generated by [Claude
Code](https://claude.ai/code/session_01WHUYQEPKgQU6jBgUj4snYU)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

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;
 ]
 
 (* ============================================================================