Merge pull request #393 from AdaWorldAPI/claude/sprint-13-i4-substrate-decisions

plan(sprint-13/spawn-gate): OQ-CSV-7..16 user-ratified + codex P2 follow-up — Wave I unblocked

Author: AdaWorldAPI

.claude/knowledge/i4-substrate-decisions.md

@@ -121,6 +121,27 @@ OQ-CSV-4 ratified: sibling-column-then-cutover (Phase 5a = add sibling; Phase 5b
 | **OQ-CSV-5** Pre-computed Magnitude column | **N/A** — ratified as on-demand (1 SIMD multiply per row sweep: `coherence × valence → i8`). Not a blocking gate. | Non-blocking per plan §11 |
 | **OQ-CSV-6** Σ10 Rubicon threshold derivation | **Hand-tuned for sprint-11/12 with TECH_DEBT (TD-7)** — bands default to Σk = k × 0.10. Jirak-derived calibration (VAMPE + Jirak coupled revival) deferred to sprint-13+. | PR #387 (sigma-tier-router); TECH_DEBT.md entry |
 
+### Sprint-13 ratifications (OQ-CSV-7..16) — user-ratified 2026-05-16
+
+User batch-ratified all 10 sprint-13 spawn blockers per PP-11 Opus recommendations
+in the `.claude/board/sprint-log-13/oq-catalog.md` per protocol §3. Source:
+autoattended ratification at the post-PR-#392-merge gate-closing moment.
+
+| OQ | Outcome | Wave / evidence |
+|---|---|---|
+| **OQ-CSV-7** PP-3 rayon feature gate name | **Ratified: `parallel`** — match ndarray's existing feature naming. Avoids feature-fork in the dependency graph; every existing parallel consumer already opts into `parallel`. | Sprint-13 D-CSV-17 (W-I4) |
+| **OQ-CSV-8** PP-3 par_* iteration chunk size | **Ratified: Fixed** — **8 rows for QualiaI4** (8×8B = 64B cache line), **4 rows for SplatField** (4×16B = 64B cache line). Cache-line aligned by construction; deterministic in benches. Auto-detect deferred to sprint-14+ if tuning need surfaces. | Sprint-13 D-CSV-17 (W-I4) |
+| **OQ-CSV-9** PP-4 splat_field carrier (Think vs sibling) | **Ratified: Add `splat_field: Vec<SplatField>` to `Think`** — keeps the canonical carrier per CLAUDE.md "Thinking is a struct" doctrine. Sibling `Splat` struct would re-create the free-function-on-state anti-pattern under a new name. Cost: +24B per Think (one Vec header) when splat is unused. | Sprint-13 D-CSV-14 (W-I2) |
+| **OQ-CSV-10** PP-4 splat generation source | **Ratified: Derive from `self.cycle`** — single source of truth; no new invariant; cycle already advances on every Think step. Sub-cycle granularity deferred until use case forces it. | Sprint-13 D-CSV-14 (W-I2) |
+| **OQ-CSV-11** PP-5 SPO → 256D adapter (VSA bind vs one-hot) | **Ratified: Option A (VSA bind of role-keyed fingerprints)** — `bind(S_key, s) XOR bind(P_key, p) XOR bind(O_key, o)`. Per I-VSA-IDENTITIES iron rule: role information must survive superposition; one-hot fails this litmus. Role keys live as constants in `lance-graph-contract::vsa::roles`. Cost: 3 XOR ops per SPO insert. | Sprint-13 D-CSV-16 (W-I3) |
+| **OQ-CSV-12** PP-5 WitnessCorpus cam_pq lazy vs eager | **Ratified: Lazy via `enable_cam_pq()`** — keeps ndarray/cam_pq an optional dep behind a feature gate; HashMap-only users see zero cost. Builders that want similarity query call `corpus.enable_cam_pq()` once after construction. cam_pq state lives in `Option<CamPqState>` field; query methods early-return `None` if disabled. | Sprint-13 D-CSV-16 (W-I3) |
+| **OQ-CSV-13** PP-6 SIMD i4 runtime vs compile-time dispatch | **Ratified: Runtime dispatch via `simd_caps()`** — matches ndarray's existing pattern (cf. `ndarray::simd::caps`); single binary that adapts to host; bench-friendly. Cost: one cached `LazyLock<SimdCaps>` and a branch per call site. Branch predictor handles cost trivially after warmup. | Sprint-13 D-CSV-13b (W-I1) |
+| **OQ-CSV-14** PP-6 bench speedup floor (SHIP vs LAND) | **Ratified: SHIP gate 4× AVX-512 vs scalar; LAND gate 2×** — below 2× blocks PR; 2×–4× lands with `TD-D-CSV-13b-PERF-FLOOR-1` TECH_DEBT note and follow-up; ≥4× ships. 4× = published expectation (8-wide i4 lanes after vpcompress, ~2× horizontal-sum overhead); 2× = floor at which AVX-512 is worth the binary cost. | Sprint-13 D-CSV-13b (W-I1) |
+| **OQ-CSV-15** PP-8 worker-template-v2 workspace member edit ownership | **Ratified: WORKER edits `members =`** — W-G6 proved feasible (PR landed clean, no CSI-7 recurrence). Avoids orphan pattern at root (worker tests crate against workspace; if `members =` is wrong, worker's own `cargo test` catches it). Worker template v2 documents the required edit as a checklist item. | Sprint-13 all new-crate workers (PP-3 splat-field-types, PP-5 witness-index-cam-pq) |
+| **OQ-CSV-16** Governance: E-META-10 + iron-rules-doctrine in BOOT.md Tier-1 | **Ratified: YES, add to BOOT.md Tier-1 trigger table** — promotion was already shipped via PR #391 (4 new agent trigger rows include iron-rules-doctrine as mandatory knowledge for PP-13/14/15/16). This ratification confirms the choice. Cost: +1 read per worker session that triggers; benefit: zero iron-rule violations make it past worker self-review. | PR #391 (already shipped); this ratification confirms the design |
+
+**Effect:** sprint-13 worker fleet dispatch (Wave I) is unblocked. W-I1 (D-CSV-13b SIMD) / W-I2 (D-CSV-14 splat-on-Think) / W-I3 (D-CSV-16 WitnessIndexCamPq) / W-I4 (D-CSV-17 rayon par_*) + W-Meta-Opus may now spawn.
+
 ---
 
 ## 5. Sprint-11 Codex P1 Anti-Pattern: v1-API-Under-v2-Feature Aliasing

.claude/specs/pr-sprint-13-rayon-streams.md

@@ -225,7 +225,7 @@ The ndarray `Cargo.toml` already exposes:
 This PR **re-uses the existing feature**. It does NOT add a new feature
 flag. The feature is enabled in three relevant downstream contexts:
 
-1. `cargo test --features rayon` — runs the 18 new tests in §7.
+1. `cargo test --features parallel` — runs the 18 new tests in §7.
 2. `[package.metadata.docs.rs] features = ["approx", "serde", "rayon"]` (Cargo.toml:255) — docs.rs build already includes rayon, so the new `par_*` doc-comments will render on docs.rs without further config.
 3. `[[bench]] name = "par_rayon", required-features = ["rayon"]` (Cargo.toml:122) — existing par_rayon bench already conditional on this feature; no conflict.
 
@@ -235,7 +235,7 @@ flag. The feature is enabled in three relevant downstream contexts:
 documented in Cargo.toml lines 56-60.
 
 **Why not gate behind a new `parallel` feature?** That would fragment the
-flag space — downstream consumers already write `--features rayon`
+flag space — downstream consumers already write `--features parallel`
 everywhere (par_rayon bench, docs.rs metadata). A second flag pointing at
 the same rayon dep is pure noise. The user-facing prompt mentioned
 `parallel` as a possibility; the audit shows `rayon` is the canonical
@@ -544,7 +544,7 @@ divergence in T-P-S-4 (uses `filter_energy_above` semantics):
 
 ### 7.4 Test invocation
 
-    cargo test -p ndarray --features rayon hpc::stream
+    cargo test -p ndarray --features parallel hpc::stream
 
 All 18 tests should pass on any host with ≥1 CPU; rayon falls back to
 a single-thread pool gracefully on uniprocessor builds.
@@ -557,7 +557,7 @@ a single-thread pool gracefully on uniprocessor builds.
 |---|---|---|---|
 | Rayon thread-pool init overhead dominates for small N | Med | Low — degrades to serial latency at small N | Doc-comment recommends serial `QualiaStream` for N < 1024; benchmark plumbing deferred to sprint-14 par_rayon bench |
 | `with_min_len` ignored by future rayon major version | Low | Med — chunk-boundary semantics drift | Pin rayon = "1.10.0" (already pinned in Cargo.toml); review on each rayon major bump |
-| Default-feature CI does not exercise the new tests | High | Low — that's the design; gated tests = silent dead code | Add `cargo test -p ndarray --features rayon` to the CI matrix; tracked separately as preflight-PP-4 |
+| Default-feature CI does not exercise the new tests | High | Low — that's the design; gated tests = silent dead code | Add `cargo test -p ndarray --features parallel` to the CI matrix; **co-shipped in the same ndarray PR as the par_* impl** (sprint-13 W-I4, the sonnet worker assigned D-CSV-17) — CI gate naturally belongs in the same PR as the `#[cfg(feature = "parallel")]` code it gates, not a separate planner. |
 | Pattern-C non-determinism caught by a golden-master test in lance-graph | Med | Med — flaky test triage cost | Doc-comment §6 makes the contract explicit; offending consumers must call `.with_min_len(rows.len())` |
 | `IndexedParallelIterator` return type prevents future migration to a non-rayon parallel backend | Low | High — would be SBP-breaking | Acceptable: rayon 1.x is the de facto Rust parallel standard; abstraction is premature pessimisation |
 | Cargo --no-default-features + miri build broken by accidental rayon import outside the cfg-gate | Low | High — breaks `thumbv6m-none-eabi` invariant | The `#[cfg(feature = "rayon")] use rayon::prelude::*;` placement is local to each function; verified by `cargo check --no-default-features` in §10 LOC count |
@@ -583,8 +583,10 @@ a single-thread pool gracefully on uniprocessor builds.
 - PP-4: D-CSV-14 on-Think method migration spec — co-evolves with this PR;
   the splat on-Think methods will internally call `par_splat_field_stream`
   for the fleet-evaluation hot path.
-- PP-4: CI matrix update — adds `--features rayon` to the ndarray test job
-  so the 18 new tests actually run.
+- W-I4 (sprint-13 sonnet impl worker assigned D-CSV-17): adds the
+  `--features parallel` row to ndarray's CI matrix in the same ndarray PR
+  that ships par_* — keeps the rayon gate co-located with the rayon
+  code it gates, prevents silent-dead-code drift.
 
 **Knowledge docs (READ BY):**
 
@@ -635,11 +637,11 @@ Before merging this PR:
 
 - [ ] `cargo check -p ndarray` (no rayon feature) — builds clean
 - [ ] `cargo check -p ndarray --no-default-features` — nostd build clean
-- [ ] `cargo check -p ndarray --features rayon` — rayon build clean
-- [ ] `cargo test -p ndarray --features rayon hpc::stream` — all 18 new tests pass
+- [ ] `cargo check -p ndarray --features parallel` — rayon build clean
+- [ ] `cargo test -p ndarray --features parallel hpc::stream` — all 18 new tests pass
 - [ ] `cargo test -p ndarray hpc::stream` (default) — existing scalar tests still pass; new par_tests modules are skipped
-- [ ] `cargo doc -p ndarray --features rayon` — doc-comment examples compile
-- [ ] `cargo clippy -p ndarray --features rayon -- -D warnings` — no lints
+- [ ] `cargo doc -p ndarray --features parallel` — doc-comment examples compile
+- [ ] `cargo clippy -p ndarray --features parallel -- -D warnings` — no lints
 - [ ] `cargo fmt --check` — rustfmt 1.95.0 gate
 - [ ] LATEST_STATE.md updated with D-CSV-17 entry
 - [ ] PR_ARC_INVENTORY.md PREPEND entry (Added: 3 fns / Locked: rayon feature surface / Deferred: bench tuning to sprint-14 / Docs: this spec / Confidence: HIGH)