From 4be809c8e13256fcfed0578d6193b28820ca68ea Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 11 Aug 2026 01:27:05 +0000 Subject: [PATCH] =?UTF-8?q?docs(board):=20record=20merged=20#917=20?= =?UTF-8?q?=E2=80=94=20normalized-substrate=20reference?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Post-merge board hygiene for #917 (a CONTENT PR — new knowledge doc + two corrections — so it carries the full merged-PR obligation, not the hygiene-only termination clause). - LATEST_STATE PREPEND: what #917 establishes about already-shipped code (no new types) — the z-vs-2z reading split, helix360 as the existing HelixResidue lane read 2x24 in/out, the [G-absence] pair-writer gap, and floor scoping resolved as an ingest policy with probes P1-P6 all NOT RUN. - PR_ARC PREPEND: Added / Locked / Deferred / Docs + Confidence, with a provenance note recording the five-correction arc and the meta-rule it produced (consult-don't-guess applies to one's own prior in-session statements). This commit is itself hygiene-only and therefore generates no further board obligation (CLAUDE.md termination clause). Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01CcpLeEC3XK8Eye53GKBVvi --- .claude/board/LATEST_STATE.md | 13 +++++++++++++ .claude/board/PR_ARC_INVENTORY.md | 10 ++++++++++ 2 files changed, 23 insertions(+) diff --git a/.claude/board/LATEST_STATE.md b/.claude/board/LATEST_STATE.md index 34b336a12..f213c6990 100644 --- a/.claude/board/LATEST_STATE.md +++ b/.claude/board/LATEST_STATE.md @@ -1,3 +1,16 @@ +## 2026-08-11 — lance-graph #917 (MERGED) — the normalized-substrate reference: palette256 × helix360 + +### Current Contract Inventory — no new types (docs-only; the primitives were already shipped) + +- **`.claude/knowledge/weather-normalized-substrate.md`** — the product/engineering reference for weather AI on the substrate. Every code claim carries `file:line` + a `[G]`/`[G-absence]`/`[H]`/`[S]` grade; measured numbers carry their conditions AND a *not-yet-re-runnable* flag until probe P1 commits them. +- **What it establishes about already-shipped code (no new surface):** `helix::Similarity` is ONE `arctanh` core with two readings — `fisher_z` (variance-stabilizing statistic, `fisher_z.rs:14,55-58`) and `hyperbolic_depth` (`2·arctanh`, the Poincaré-disk arc length, `:60-78`). The encoder stores the **z-form** and never materializes geometry (`residue.rs:150,159`); `hyperbolic_depth` is called from **no encode path** (`[G-absence]`, grep 2026-08-11) — that is the DESIGN, not an unwired seam. Normalization is the load-bearing property: it makes 8 bits sufficient per scalar AND puts unlike variables on one scale, which is what licenses cross-variable LUT correlation. +- **helix360 = the existing `ValueTenant::HelixResidue` lane**, `ColumnKind::U8 × 6 @ row_offset 112` (`canonical_node.rs:837-840, 960-967`), documented there as *"2× the 24-bit equal-area hemisphere"* — i.e. inbound AND outbound bearing, in the width already reserved. `Signed360::{to,from}_bytes` (`residue.rs:92-105`) is ONE sanctioned reading of that content-blind register; 2×24 in/out is another (same doctrine as the V3 12-byte facet + `EdgeBlock` flavor rule). +- **`[G-absence]` no in/out PAIR-writer exists** — `encode_signed` emits one signed point (`residue.rs:182-204`); nothing in `crates/helix/src` or the contract composes the pair into the lane. Queued as probe P4; deliberately not invented inline. +- **Floor scoping RESOLVED as a policy, not a crate property** (read from `quantize.rs`/`distance.rs`): `quantize` is **linear** over a per-instance `[lo,hi]` window (`quantize.rs:99-108`) — all non-linearity is the upstream Fisher-Z — and `bucket_center` (`:248-250`) makes index meaning floor-dependent, so cross-variable code comparability is an **ingest calibration decision** (shared canonical z-floor / per-variable / hybrid), stamped by `floor_version` under the crate's own versioning contract (`quantize.rs:20-26`). Proposal `[S]`: freeze per epoch, align re-rolls with Lance dataset versions so `at(v)` rehydrates with the floor that produced the codes. Gated on probes P2/P3/P6. +- **Probe queue P1–P6** (P1 re-runnability · P2 shared-floor cross-variable · P3 per-variable resolution cost · P4 pair-writer · P5 `drift_sigma` under spatial autocorrelation · P6 Lance↔floor version alignment) — **all NOT RUN**. Per the process rule, the next deliverable is a probe, not more synthesis. + +**Companion corrections in the same PR:** `weather-substrate-poc-v2.md` §0 gains append-only **⊘ C3** — the plan's Zarr object name `era5/1959-2023_01_10-full_37-1h-1440x721.zarr` does NOT exist; the session-verified object is `1959-2023_01_10-full_37-1h-0p25deg-chunk-1.zarr` under `gcp-public-data-arco-era5` (`ar/` prefix). Grid math unchanged; only the name was invented. + ## 2026-08-09 — branch `claude/phase-a-owned-writer` — Phase A: the artifact-backed commit contract + the SOLE owned Lance writer (`LanceCycleWriter`) > **⊘ This entry SUPERSEDES the #911 entry below it** (operator ruling 2026-08-09). The §I.6 "every cycle publishes exactly one `DatasetVersion`" contract, the compensating delete, and the per-operation-reopen sink are all REMOVED — not repaired. Canonical record: `.claude/plans/persistence-artifact-backed-commit-v1.md`. Nothing below is deleted; it is read through that document. diff --git a/.claude/board/PR_ARC_INVENTORY.md b/.claude/board/PR_ARC_INVENTORY.md index b354800df..cfde62b5f 100644 --- a/.claude/board/PR_ARC_INVENTORY.md +++ b/.claude/board/PR_ARC_INVENTORY.md @@ -33,6 +33,16 @@ > - **Docs** — knowledge files produced (immutable) > - **Confidence (YYYY-MM-DD):** — the ONLY mutable field +## 2026-08-11 — lance-graph #917 (MERGED) — the normalized-substrate reference: palette256 × helix360, and the five-correction ledger that produced it + +- **Added.** `.claude/knowledge/weather-normalized-substrate.md` (~330 lines): doctrine (§1), helix360 projection + wire shapes + ABI lane (§2), palette256 quantizer + distance surface (§3), floor-scoping decision (§4), per-variable weather mapping (§5), measured-evidence ledger (§6), inbound-tax economics (§7), ingest spec (§8), verification battery (§9), probe queue P1–P6 (§10), correction ledger (§11), API appendix. Docs-only — zero code, zero new types. +- **Locked.** **Normalized > materialized**: the substrate stores the Fisher-Z z-form and hydrates geometry (`2z` Poincaré depth, sphere coordinates, full φ-arcs) on demand from deterministic templates — `hyperbolic_depth` exposed-but-uncalled is the design. The value of the transform is variance stabilization: uniform information per palette bucket (⇒ 8 bits suffice) AND unlike variables on one scale (⇒ cross-variable LUT correlation is legitimate rather than a unit error). **helix360 is not a codec to design — it is the shipped 6-byte `HelixResidue` lane read as 2 × 24-bit hemispheres = wind in/out**, at `row_offset 112` inside the operator-locked 512-byte row. **The `Signed360` polar sign-partition is load-bearing** (codex P2 #498): a naive `128 + y·127` loses the hemisphere sign exactly at the rim where `|y| → 0` — any "simplification" reintroduces the bug. **Floor scoping is an ingest policy, not a crate property** — three admissible policies enumerated with their LUT semantics, hybrid recommended `[S]`, all gated on probes. **Every significance claim on pooled/compared z-values takes Jirak 2016 weak-dependence rates**, never classical `1/(n−3)` — weather fields are autocorrelated, so effective n ≪ nominal. +- **Deferred.** All six probes (P1–P6) NOT RUN; the in/out pair-writer (`[G-absence]`, P4); the weather wiring itself (no weather code exists in-tree — the POC plan is the vehicle); exact metric definitions behind three §6 rows (mean-abs error, obs-error reference) to be pinned when P1 commits them as examples. +- **Docs.** The knowledge doc; EPIPHANIES `E-HELIX360-IS-THE-NORMALIZED-SUBSTRATE-NOT-A-BIT-BUDGET-1`; plan §0 ⊘ C3 (Zarr object name). + +**Confidence (2026-08-11):** merged. Code claims verified against the tree this session with `file:line`; the weather mapping is design-`[H]` composing only shipped primitives; the floor policy is `[S]` and must not be built on before P2. +**Provenance note — the corrections ARE part of the record.** This doc exists because five operator-caught errors in one arc shared a species: *asserting from API surface or first principles what the code already answered*. (1) A 48-bit budget invented while `Signed360` existed. (2) `Pair48`/12 B proposed for a lane already 2× by construction. (3) "unwired 2z seam" where not-materializing is the point — first mis-described as "an absorbed rescale, not a defect", i.e. smoothed rather than named; both readings wrong. (4) "scalar similarity" where the value is the normalization. (5) Measurement-apparatus inversions (the `rint`-snapped bearing artifact; "wind_speed is derivable"). Meta-rule now recorded in §11: **consult-don't-guess applies to one's own prior in-session statements** — a confident earlier message carries the same evidentiary weight as a stale doc (none) until checked against the tree. + ## 2026-08-09 — branch `claude/phase-a-owned-writer` (PR pending) — Phase A: the artifact-backed commit contract + the SOLE owned writer - **Added.** `.claude/plans/persistence-artifact-backed-commit-v1.md` (the canonical persistence contract, ratified). `lance_graph::graph::cycle_sink::LanceCycleWriter` (~900 LOC incl. 11 reopened-store falsifiers) replacing `LanceCycleSink`. In `persist_sink`: `CommitOutcome` / `CommitError` / `FrameMeta`, `DetachedCycleBatch::batch_hash`, the reshaped `WalSink` (`commit_cycle(&mut self, batch)`, `scan_sealed(after_cycle)`, `timeline()`), `PersistError::Commit`, and 5 contract falsifiers.