diff --git a/.claude/board/INTEGRATION_PLANS.md b/.claude/board/INTEGRATION_PLANS.md index 25c92e83..e330b78e 100644 --- a/.claude/board/INTEGRATION_PLANS.md +++ b/.claude/board/INTEGRATION_PLANS.md @@ -1,3 +1,20 @@ +## 2026-06-07 — singleton-to-snapshot-nudge-v1 (workspace-wide audit: every shared-mutable singleton → per-owner MailboxSoA + Arc-swap COW snapshot; read-only codebooks explicitly left as-is) + +**Status:** PROPOSAL. Design-spec + audit only, no code beyond the AttentionMatrix correctness fix. **Plan file:** `.claude/plans/singleton-to-snapshot-nudge-v1.md`. +**Owns:** 7 deliverables D-SNGL-1..7. +- D-SNGL-1: workspace-wide singleton census (codebook vs shared-mutable classification) +- D-SNGL-2: classification gate — the mechanical "mutated-after-init?" decision procedure +- D-SNGL-3: `AttentionMatrix.gestalt` correctness (TD-UNBUNDLE-FROM-1) → raw-sum+count or rebuild-on-read +- D-SNGL-4: `ndarray/crates/burn` ATTENTION_CACHE / LINEAR_CACHE audit (JIT-kernel cache = keep; runtime belief = nudge) +- D-SNGL-5: `SnapshotProvider` adoption checklist per nudged crate (reuses cycle-coherent-soa-snapshot-v1 trait) +- D-SNGL-6: no-cross-cycle-lag falsification per nudged crate (reuses D-SOA-SNAP-5 test shape) +- D-SNGL-7: board hygiene + candidate epiphany E-SINGLETON-IS-CODEBOOK-OR-SOA +**Key distinction:** read-only `LazyLock` codebooks (role keys, UDFs, simd_caps) are NOT targets — only shared-mutable runtime state is. The test is mechanical: mutated-after-init → nudge; never-mutated → codebook, keep. +**Companion plans:** `bindspace-singleton-to-mailbox-soa-v1` (BindSpace singleton dissolution — referenced, not duplicated), `cycle-coherent-soa-snapshot-v1` (the snapshot mechanism reused here). +**Anchored epiphanies:** E-MAILBOX-IS-BINDSPACE, E-BATON-1, E-DEINTERLACE-TWO-SCALES. **Anchored debt:** TD-UNBUNDLE-FROM-1. + +--- + ## 2026-06-06 — cycle-coherent-soa-snapshot-v1 (Arc-swap COW at column granularity; byte-scale deinterlace; no-cross-cycle-lag guarantee) **Status:** QUEUED. Design-spec only, no code. **Plan file:** `.claude/plans/cycle-coherent-soa-snapshot-v1.md`. diff --git a/.claude/board/STATUS_BOARD.md b/.claude/board/STATUS_BOARD.md index d2330524..ffb1347b 100644 --- a/.claude/board/STATUS_BOARD.md +++ b/.claude/board/STATUS_BOARD.md @@ -1,3 +1,19 @@ +## singleton-to-snapshot-nudge-v1 — every shared-mutable singleton → per-owner MailboxSoA + Arc-swap snapshot (7 deliverables; codebooks left as-is) + +Plan path: `.claude/plans/singleton-to-snapshot-nudge-v1.md`. Companions: `bindspace-singleton-to-mailbox-soa-v1` (BindSpace dissolution), `cycle-coherent-soa-snapshot-v1` (snapshot mechanism). Debt: TD-UNBUNDLE-FROM-1. + +| D-id | Title | Crate(s) / repo | Risk | Status | PR / Evidence | +|---|---|---|---|---|---| +| D-SNGL-1 | Workspace-wide singleton census (codebook vs shared-mutable) | docs/architecture | LOW | **Queued** | audit only; gates classification | +| D-SNGL-2 | Classification gate — "mutated-after-init?" decision procedure | docs/architecture | LOW | **Queued** | gates on D-SNGL-1 | +| D-SNGL-3 | `AttentionMatrix.gestalt` correctness (raw-sum+count or rebuild) | `lance-graph-planner::cache::kv_bundle` | MED | **In progress** | `unbundle_from` deprecated this session (branch `claude/stoic-turing-M0Eiq`); full fix pending | +| D-SNGL-4 | `ndarray/crates/burn` ATTENTION_CACHE / LINEAR_CACHE audit | `ndarray` | LOW | **Queued** | classify JIT-cache vs runtime-belief | +| D-SNGL-5 | `SnapshotProvider` adoption checklist per nudged crate | workspace | LOW | **Queued** | gates on D-SOA-SNAP-1/2 | +| D-SNGL-6 | No-cross-cycle-lag falsification per nudged crate | workspace | MED | **Queued** | reuses D-SOA-SNAP-5 shape | +| D-SNGL-7 | Board hygiene + E-SINGLETON-IS-CODEBOOK-OR-SOA | `.claude/board` | LOW | **In progress** | this entry + INTEGRATION_PLANS prepend | + +--- + ## cesium-osm-substrate-v1 — OpenStreetMap as 6th Cesium ingest source class (7 deliverables; substrate-reuse with splat-native) Plan path: `.claude/plans/cesium-osm-substrate-v1.md`. Parent: `3DGS-ArcGIS-Cesium-ingestion-plan.md` (structural). Sibling: `splat-native-ultrasound-v1.md` (Gaussian3D carrier reuse). OGAR coordination 2026-06-05 locked Q1/Q2/Q3 rulings. OGAR-side docs PR (DOMAIN-INSTANCES §2.6 + RDF-OWL-ALIGNMENT §10 Phase 2c) queued behind this PR. diff --git a/.claude/plans/singleton-to-snapshot-nudge-v1.md b/.claude/plans/singleton-to-snapshot-nudge-v1.md new file mode 100644 index 00000000..b0e31ab8 --- /dev/null +++ b/.claude/plans/singleton-to-snapshot-nudge-v1.md @@ -0,0 +1,168 @@ +# Plan: Singleton → Snapshot Nudge — every shared-mutable singleton becomes a per-owner SoA with Arc-swap COW snapshot + +**Version:** v1 +**Date:** 2026-06-07 +**Status:** PROPOSAL +**D-ids:** D-SNGL-1 through D-SNGL-7 +**Branch:** `claude/stoic-turing-M0Eiq` + +--- + +## The thesis + +The workspace has one architectural direction for shared state: + +> **No shared mutable singleton. State is owned per-mailbox as a `MailboxSoA`, +> read via cycle-coherent Arc-swap COW snapshots, and calcified to SPO + Lance +> tombstone. Cross-boundary state is the discrete LE baton, never a materialized +> singleton.** + +This is already ratified across three epiphanies and two plans: + +- `E-MAILBOX-IS-BINDSPACE` — `MailboxSoA` *is* the per-mailbox thoughtspace; + the singleton `Arc` is dissolved, not copied. +- `E-BATON-1` — inter-mailbox state is the `(u16 target, CausalEdge64)` baton; + no persisted/transmitted singleton. +- `E-DEINTERLACE-TWO-SCALES` — deinterlace is one operation at two scales; + byte-scale is the SoA Arc-swap snapshot at `cycle()` granularity. +- Plan `bindspace-singleton-to-mailbox-soa-v1` — dissolves the `ShaderDriver` + `Arc` singleton specifically. +- Plan `cycle-coherent-soa-snapshot-v1` — the Arc-swap COW snapshot mechanism + (no-cross-cycle-lag guarantee). + +**What is missing:** a single, enumerated audit that nudges *every* +singleton-shaped construct in the workspace onto this architecture, so the +migration is exhaustive rather than ad-hoc. This plan is that audit. + +--- + +## Two kinds of "singleton" — only one is a target + +The grep for `LazyLock` / `OnceLock` / `static` / `Arc<…>` returns two +fundamentally different shapes. The distinction is the whole game: + +### NOT a target — read-only immutable codebooks (LEAVE AS-IS) + +These are built once and never mutated. They are the I-VSA-IDENTITIES +Layer-2 role catalogues and Layer-1 codebooks. A `LazyLock` here is correct +and idiomatic — it is a const table, not shared mutable state. + +| Construct | Home | Verdict | +|---|---|---| +| `SUBJECT_KEY` / `PREDICATE_KEY` / … role keys | `contract::grammar::role_keys` | ✅ Keep — immutable role identity codebook | +| `FINNISH_KEYS` / `TENSE_KEYS` / `NARS_KEYS` | `contract::grammar::role_keys` | ✅ Keep — immutable codebook | +| `KUNDE_KEY` / `RECHNUNG_KEY` / … callcenter keys | `contract::grammar::role_keys` | ✅ Keep — immutable codebook | +| `VECTOR_DISTANCE_*_UDF` / `HAMMING_*_UDF` | `lance-graph::datafusion_planner::udf` | ✅ Keep — DataFusion UDF registration, immutable | +| `simd_caps()` singleton | `ndarray::simd_caps` | ✅ Keep — hardware capability probe, immutable | + +**Rule:** a `LazyLock` where `T` is never mutated after init is a codebook, +not a singleton. The data-flow invariant (`ndarray/.claude/rules/data-flow.md` +§2) already blesses these: "Caches use interior mutability (`RwLock`, +`LazyLock`) or are built once." + +### IS a target — shared mutable runtime state (NUDGE) + +These hold mutable runtime state behind a shared handle. They are the +singletons the architecture dissolves into per-owner SoA + snapshot. + +| Construct | Home | Nudge | Owning plan | +|---|---|---|---| +| `ShaderDriver.bindspace: Arc` | cognitive-shader-driver | Dissolve into per-mailbox `MailboxSoA`; driver holds a sea-star of mailboxes | `bindspace-singleton-to-mailbox-soa-v1` (D-MBX-3/5) | +| `Arc::new(BindSpace::zeros(4096))` in `bin/serve.rs:29` (REST debug server) | cognitive-shader-driver | Delete; mailboxes allocate their own SoA | `bindspace-singleton-to-mailbox-soa-v1` (D-MBX-5) | +| `Arc::new(BindSpace::zeros(4096))` in `bin/grpc.rs:29` (gRPC debug server) | cognitive-shader-driver | Delete; same nudge as `serve.rs` — both debug-server entry points must move together or one singleton is left behind | `bindspace-singleton-to-mailbox-soa-v1` (D-MBX-5) | +| `AttentionMatrix.gestalt` (shared mutable summary, drifting via `unbundle_from`) | `lance-graph-planner::cache::kv_bundle` | Either rebuild-from-scratch or raw-sum+count; the gestalt is a snapshot read, not an incrementally-mutated singleton | THIS PLAN (D-SNGL-3) + TD-UNBUNDLE-FROM-1 | +| `ATTENTION_CACHE` / `LINEAR_CACHE` `LazyLock>` | `ndarray/crates/burn::ops::matmul` | Audit: is this a JIT-kernel cache (keep, like UDFs) or runtime belief state (nudge)? | THIS PLAN (D-SNGL-4) | +| any `Arc>` / `Arc>` runtime caches surfaced by the audit | workspace-wide | Classify codebook-vs-singleton; nudge only the latter | THIS PLAN (D-SNGL-2) | + +--- + +## Deliverables + +### D-SNGL-1 — Workspace-wide singleton census + +Grep every crate for `LazyLock` / `OnceLock` / `OnceCell` / `Lazy` / `static …` / +`Arc Is the static ever mutated after init? **No → codebook, keep.** **Yes → is it +> per-owner runtime state? Yes → nudge to `MailboxSoA` + snapshot. No (truly +> process-global, e.g. a JIT-kernel cache) → keep behind `RwLock` per data-flow +> §2, but document why it is not per-owner.** + +### D-SNGL-3 — `AttentionMatrix.gestalt` correctness + snapshot shape + +Fix TD-UNBUNDLE-FROM-1: the gestalt is a derived snapshot, not an +incrementally-subtracted singleton. Switch to raw-sum + count so the gestalt is +exactly `(sum[d] / count).round()`, OR rebuild on read. Remove the deprecated +`unbundle_from` once no caller remains. The gestalt then matches the snapshot +doctrine: a coherent read over the heads at a cycle stamp, not a drifting +accumulator. + +### D-SNGL-4 — burn matmul cache audit + +Classify `ATTENTION_CACHE` / `LINEAR_CACHE` in `ndarray/crates/burn`. If they +cache *compiled kernels* keyed by shape, they are JIT-kernel caches (keep, +document as process-global per D-SNGL-2). If they cache *runtime activations / +beliefs*, they are singletons and must move to the SoA. Record the verdict. + +### D-SNGL-5 — Snapshot trait adoption checklist + +For each nudged singleton, the migration target is the same trait surface from +`cycle-coherent-soa-snapshot-v1`: implement `SnapshotProvider` (D-SOA-SNAP-2), +return a `MailboxSoaSnapshot` (D-SOA-SNAP-1) under a cycle stamp. This deliverable +is the per-crate checklist binding each nudge to the snapshot contract so the +migration is uniform. + +### D-SNGL-6 — No-cross-cycle-lag falsification per nudged crate + +Each nudged crate inherits the D-SOA-SNAP-5 test shape: writer thread advancing +cycles + N reader threads snapshotting; assert every snapshot is single-cycle. +The test is the merge gate for that crate's nudge. + +### D-SNGL-7 — Board hygiene + EPIPHANIES + +This plan + INTEGRATION_PLANS prepend + STATUS_BOARD rows + (if the census +surfaces a genuinely new finding) an EPIPHANIES entry. The candidate epiphany: +`E-SINGLETON-IS-CODEBOOK-OR-SOA` — every static is exactly one of two things, +and the test (mutated-after-init?) is mechanical. + +--- + +## Execution ordering + +1. **D-SNGL-1 + D-SNGL-2 first** (census + gate) — settles codebook-vs-singleton + verdicts before any code moves. Pure doc/audit work. +2. **D-SNGL-3** (AttentionMatrix) — the one concrete correctness bug; ships with + the kv_bundle deprecation already landed this session. +3. **D-SNGL-4** (burn audit) — independent; classify, then keep-or-nudge. +4. **D-SNGL-5/6** per nudged crate — gated on `cycle-coherent-soa-snapshot-v1` + D-SOA-SNAP-1/2 landing first (the trait surface must exist to adopt it). +5. **D-SNGL-7** lands with D-SNGL-1 (board hygiene is same-commit, per CLAUDE.md). + +--- + +## Non-goals + +- Not touching read-only codebooks (role keys, UDFs, simd_caps). Those are + correct as-is. +- Not re-deriving the BindSpace dissolution — that is owned by + `bindspace-singleton-to-mailbox-soa-v1`. This plan references it, does not + duplicate it. +- No new snapshot mechanism — reuses `cycle-coherent-soa-snapshot-v1`'s trait. + +--- + +## Cross-references + +- `bindspace-singleton-to-mailbox-soa-v1` — BindSpace singleton dissolution +- `cycle-coherent-soa-snapshot-v1` — the Arc-swap COW snapshot mechanism reused here +- `EPIPHANIES.md` E-MAILBOX-IS-BINDSPACE, E-BATON-1, E-DEINTERLACE-TWO-SCALES +- `TECH_DEBT.md` TD-UNBUNDLE-FROM-1 — the AttentionMatrix gestalt drift +- `ndarray/.claude/rules/data-flow.md` §2 — the "caches built once" invariant + that keeps codebooks legal +- `docs/architecture/soa-three-tier-model.md` — the zero-copy lifecycle target