OCapN port: Phase 0 actor model + Phases 1–21 wire interop & vat bridge

.claude/rules/prologos-syntax.md

@@ -85,6 +85,38 @@ it) and `=` never binds.
   ```
   Body at the **same** indent as `|` is a layout violation (currently produces a hard parser error; tracked in issue #27 for diagnostic improvement). Body indent must be **strictly greater than** the `|` column.
 
+- **Never write three-deep nested `match` as a single function body.** Three-deep nested `match` inside a single function body fails to elaborate at *import time* with "Unbound variable" errors in Prologos's current elaborator. The fix is mechanical: factor into a chain of single-match helpers. Each helper does one `match`, returns to the caller, the caller does the next `match`. Same semantics for the user, no elaborator failure. OCapN Phases 15 and 21 both shipped this workaround; codified after the second occurrence. Until the underlying elaborator bug is fixed, this is the safe pattern.
+  ```
+  ;; WRONG — fails at import time
+  defn pipeline-deliver [target args v]
+    match [lookup-actor target v]
+      | some _ -> send-only target args v
+      | none ->
+          match [lookup-promise target v]
+            | none -> v
+            | some pst ->
+                match pst
+                  | pst-unresolved msgs -> ...
+                  | _ -> v
+
+  ;; RIGHT — helper chain
+  spec deliver-to-promise Nat SyrupValue PromiseState Vat -> Vat
+  defn deliver-to-promise [pid args pst v]
+    match pst | pst-unresolved msgs -> ... | _ -> v
+
+  spec deliver-to-promise-or-drop Nat SyrupValue Vat -> Vat
+  defn deliver-to-promise-or-drop [target args v]
+    match [lookup-promise target v]
+      | none -> v
+      | some pst -> deliver-to-promise target args pst v
+
+  spec pipeline-deliver Nat SyrupValue Vat -> Vat
+  defn pipeline-deliver [target args v]
+    match [lookup-actor target v]
+      | some _ -> send-only target args v
+      | none -> deliver-to-promise-or-drop target args v
+  ```
+
 ## Application style
 
 - **Uncurried** -- `defn foo [x y z] body`, `spec f A B -> C`. Multiple arguments in one bracket group.
@@ -93,6 +125,38 @@ it) and `=` never binds.
 - **Pipeline `|>` and `compose`** for chaining named functions -- `|> 5 inc dbl sqr` is idiomatic.
 - **Eval is implicit** -- write `[f x]` not `eval [f x]`. Top-level expressions just evaluate.
 - **Don't wrap outer tree** -- top-level forms are implicit.
+- **Keep multi-arg applications on a single line.** A continuation line whose first token is a bare identifier is parsed as a sibling form, not as more args to the previous head. Pitfalls #36 and #38 (goblin-pitfalls log) both stem from this:
+  ```
+  ;; WRONG — `es as qs p oqs ir er pm` is parsed as an application of `es` to 7 args
+  bridge-state [list-filter-listeners-by-notified ls notified]
+               es as qs p oqs ir er pm
+
+  ;; WRONG — `let X := EXPR` value can't span lines; reader sees no value for X
+  let step1 := [captp-incoming-with-state op1 [alloc-vat sa]
+                 [bridge-state-with-our-session ver loc]]
+
+  ;; RIGHT — all positional args on the function-head line; break BEFORE a bracketed sub-call (which becomes the last arg) if the line gets too long
+  bridge-state [list-filter-listeners-by-notified ls notified] es as qs p oqs ir er pm
+  ```
+  If a line is unavoidably long, factor a sub-expression to a separate `let` or top-level helper rather than splitting positional args.
+
+- **Single-arg `defn` over a `data` type uses `defn name [arg] match arg | ...`, NOT multi-arity `defn name | [pat1] -> ... | [pat2] -> ...`.** The latter shape can cause the elaborator to lift a phantom 2nd parameter (pitfall #37 in goblin-pitfalls). Multi-arity `defn` is fine for 2+ args; for one-arg over a data type, prefer `match`:
+  ```
+  ;; WRONG — inferred type becomes `PromiseState SyrupValue -> [Option SyrupValue]` (2 args)
+  spec resolution-syrup-of-pst PromiseState -> [Option SyrupValue]
+  defn resolution-syrup-of-pst
+    | [pst-unresolved _] -> none
+    | [pst-broken     r] -> some [wrap-error r]
+    | [pst-fulfilled  v] -> some v
+
+  ;; RIGHT — inferred type matches the spec
+  spec resolution-syrup-of-pst PromiseState -> [Option SyrupValue]
+  defn resolution-syrup-of-pst [pst]
+    match pst
+      | pst-unresolved _ -> none
+      | pst-broken     r -> some [wrap-error r]
+      | pst-fulfilled  v -> some v
+  ```
 
 ## Type annotations
 
@@ -115,6 +179,11 @@ it) and `=` never binds.
 - Trait methods: short names (`eq?`, `from`, `add`)
 - Module paths use `::` not `.` -- `str::length`, `prologos::data::nat`
 - Dot access is for map keys -- `user.name` -> `[map-get user :name]`
+- **NEVER use `->` in identifiers** (silently fails to compile per pitfall #35). Use `-to-` for converters: `refr-to-syrup`, `op-to-syrup`, `syrup-to-op`. The Common Lisp / Scheme convention `refr->syrup` is incompatible with Prologos's WS-mode reader, which parses `->` as the function-arrow type operator inside any identifier.
+
+## Data type definitions
+
+- **Constructor signatures have IMPLICIT return type** (per pitfall #34). Write `data X { ctor : T1 -> T2 }` to mean "ctor takes 2 args of types T1 and T2 and returns X." Do NOT write `ctor : T1 -> T2 -> X` — that means "takes 3 args (T1, T2, X) and returns X." Existing examples: `data Listener { listener : Nat -> Nat }`, `data QEntry { q-entry : Nat -> Nat }`. Symptom of getting it wrong: smart constructors fail with `Type mismatch [Pi T -> Result -> Result]`.
 
 ## Relational syntax (`defr` / `rel` / goals)
 

.claude/rules/testing.md

@@ -4,11 +4,24 @@
 - **Full suite**: add `--all` flag. Also: `--jobs N`, `--timeout N`, `--no-record`, `--no-skip`
 - **Targeted tests (CRITICAL — use this, not bare `raco test`, after any production edit)**: `racket tools/run-affected-tests.rkt --tests tests/test-X.rkt --tests tests/test-Y.rkt` runs specific files with SCOPED PRECOMPILE (driver.rkt + the listed tests, ~0.5s incremental). This keeps test `.zo` linklets fresh after export changes in production modules, which `raco test FILE` alone does NOT do. Repeat `--tests FILE` per file (conventional command-line multi-arg pattern). **When to use targeted mode**: any time you've edited production code AND want to run specific tests — e.g., iterating on a failing test during development, verifying a fix hits the right paths, confirming a subset of tests before running the full suite. Avoids the class of "passes individually, fails in batch" / "reference to a variable that is not exported" (linklet mismatch) errors. Observed failure pattern: `raco make typing-propagators.rkt` + `raco test tests/test-X.rkt` → test's cached `.zo` holds a stale linklet snapshot of typing-propagators's exports; when exports changed, linklet-mismatch or silent wrong-results. The targeted runner's scoped precompile closes this gap. Origin: PPN 4C Phase 3c retrospective (2026-04-20) — the earlier sessions' runs didn't hit it because changes were internal (no export-surface changes); Phase 3c added multiple new provides and surfaced the gap.
 - **Reporting**: `racket tools/benchmark-tests.rkt --report` / `--trend FILE` / `--compare REF` / `--slowest N`
-- **Skip list**: `tests/.skip-tests` -- 2 pathological perf tests skipped by default (use `--no-skip` to include)
+- **Skip list**: `tests/.skip-tests` -- pathological perf tests + batch-worker-incompatible tests skipped by default (use `--no-skip` to include). When a test is genuinely incompatible with the batch worker (e.g., spawns subprocesses with `(exit 0)` skip-guards that kill the worker, exceeds the 120s per-file timeout for legitimate reasons), partition rather than patch the worker. The OCapN track skipped 9 tests (`test-ocapn-vat.rkt`, `test-ocapn-acceptance-l3.rkt`, plus 7 Node-spawning interop tests) and ran them via `raco test` directly in a separate CI workflow (`.github/workflows/interop.yml`). Patching the batch worker to handle subprocess-spawning would have been 1+ days of compiler infrastructure work; the partition was 30 minutes. Rule: **when test infrastructure mismatches a test's needs, partition rather than patch**; document in `.skip-tests` with the reason and the alternate runner.
+- **Microbench from Phase 1 in protocol stacks** -- protocol stacks (codecs, wire serializers, parsers over byte streams) have asymmetric latency hidden in tight inner loops. A microbench at the encode/decode boundary catches it during Phase 1 instead of Phase 9. OCapN's decoder shipped slow through Phases 1–8 because every test was a single small case; Phase 9's pipelined RPC was the first thing fast enough to expose the regression, and Phase 13 needed a tail-recursive accumulator + inline destructure for a 25× speedup. **Operational rule**: when implementing a codec/serializer/parser, every Phase 1 should include `tools/bench-ab.rkt` runs of encode + decode at varying message counts (1, 10, 100). Catching the perf bug at Phase 1 saves the multi-phase regression chain.
 - **Guideline**: Keep test files under ~20 test-cases / ~30s wall time for good thread-pool parallelism
 - **Delimiter check after .rkt edits**: Run `tools/check-parens.sh <file>` after EVERY edit to a `.rkt` file, BEFORE `raco make`. Instant (~100ms, read-only). Catches mismatched `()`, `[]`, `{}` with exact line:column. Eliminates trial-and-error bracket-balancing during compilation.
 - **Pre-compilation**: Both runners call `raco make driver.rkt` AND all test files before tests (skip with `--no-precompile`). The suite runner's `precompile-modules!` compiles BOTH — test files are NOT in driver.rkt's dependency graph, so `raco make driver.rkt` alone does NOT recompile them.
-- **Compile limit (`PLT_CS_COMPILE_LIMIT=1000000`) — ADOPTED (Rel T1 SUB.2, owner-blessed 2026-07-24)**: the runners (`run-affected-tests.rkt`, `bench-ab.rkt`) `putenv` it at startup, so all suite/bench builds get it automatically (subprocesses inherit; explicit user override respected). The compiler's giant match functions (shift/subst ~340 arms, whnf/nf ~990) exceed the CS default (10000) and fall back to the INTERPRETER — measured: shift ~830× faster compiled; suite 211→173s (−18%). **Manual `raco make` outside the runners should set it in the shell** (else the touched modules silently rebuild interpreted and the next suite run eats the difference): `PLT_CS_COMPILE_LIMIT=1000000 raco make driver.rkt`. ⚠ A/B measurement trap: `touch FILE && raco make` does NOT recompile (SHA short-circuit) — delete the `.zo`/`.dep` to force a true recompile. Evidence: `docs/tracking/2026-07-24_SUBSTITUTION_CONTAINMENT_DEFECT.md` §4.2.
+- **Compile limit (`PLT_CS_COMPILE_LIMIT=1000000`) — ADOPTED (Rel T1 SUB.2, owner-blessed 2026-07-24)**: the runners (`run-affected-tests.rkt`, `bench-ab.rkt`) `putenv` it at startup, so all suite/bench builds get it automatically (subprocesses inherit; explicit user override respected). The compiler's giant match functions (shift/subst ~340 arms, whnf/nf ~990) exceed the CS default (10000) and fall back to the INTERPRETER — measured: shift ~830× faster compiled; suite 211→173s (−18%). ⚠ **CI must set it at the JOB level, not rely on the runners** (added 2026-07-28): the
+workflows precompile with a bare `raco make`, which does NOT putenv it, and the `.zo`
+that step produces is interpreted for the rest of the job. This is not a slow-build
+nuisance — the OCapN interop gate reported **14 passed / 1 errored** on CI while passing
+**17/17** locally, and rebuilding locally without the limit reproduced 14/1 exactly.
+Upstream's tests carry their own wall-clock budgets (15s for a GC round trip), so
+interpreted reduction FAILS rather than merely lagging. All three workflows now set
+`env: PLT_CS_COMPILE_LIMIT: 1000000` at job level, and
+`tools/interop/run-ocapn-test-suite.sh` exports it itself so the gate does not depend on
+its caller. **When a CI-only failure has no local repro, check the build environment
+before the code** — an interpreted build is a different program.
+
+**Manual `raco make` outside the runners should set it in the shell** (else the touched modules silently rebuild interpreted and the next suite run eats the difference): `PLT_CS_COMPILE_LIMIT=1000000 raco make driver.rkt`. ⚠ A/B measurement trap: `touch FILE && raco make` does NOT recompile (SHA short-circuit) — delete the `.zo`/`.dep` to force a true recompile. Evidence: `docs/tracking/2026-07-24_SUBSTITUTION_CONTAINMENT_DEFECT.md` §4.2.
 - **Separate compile from test timing**: When measuring suite wall time for performance comparison, run `raco make driver.rkt` as a SEPARATE step first, THEN run the test suite with `--no-precompile`. Compilation time varies by cache state and pollutes wall time measurements.
 - **Stale test `.zo` auto-recompile** -- When `--no-precompile` is used, the runner now detects stale test `.zo` files (older than the production `.zo`) and auto-recompiles them before running. This fixes the historical trap where `raco make driver.rkt` + `--no-precompile` left test `.zo` stale (because tests aren't in driver's dependency graph). Stale test `.zo` silently produced wrong results via batch-worker `dynamic-require`. With auto-recompile, the runner just handles it — typical repair <5s when only a few files are stale. Use `--force-stale-zo` to override (for intentional reproduction of old behavior); otherwise the runner keeps you safe. Confirmed trap in BSP-LE Track 2B Phase T-a diagnosis (multiple cycles of "passes individually, fails in batch").
 - **DAG impact**: `prelude.rkt` or `syntax.rkt` -> nearly all tests; single `.prologos` lib -> 1-15 tests; single test -> 1 test