Skip to content

Commit 68fcfbc

Browse files
committed
docs: backfill W1.5 board entries and correct the stale W1.5 contract section
Two hygiene gaps, both found while closing out the #293/#294/#295 arc. 1. Board backfill. `.claude/blackboard.md` and `.claude/board/AGENT_LOG.md` contained ZERO mentions of the W1.5 signature primitives — all three PRs landed with no board entry, in violation of CLAUDE.md's Agent Protocol ("write decisions to the blackboard, not just to chat"). A session reading the blackboard would not have known signature_pde or randomized_signature existed. Entries added for #293, #294 and #295, carrying the decisions, the measured numbers, and the loose ends. 2. Contract-section correction. The W1.5 section of `.claude/knowledge/vertical-simd-consumer-contract.md` still described all three primitives as future work "gated on jc Pillar 11 activation". That gate opened 2026-05-07 (lance-graph jc/src/lib.rs:26), and #6 and #7 have shipped. The section is regraded in place with the workspace's existing ⊘-blockquote convention: original sketches kept verbatim, each followed by a correction block, rather than silently rewritten. The correction worth carrying forward: this doc's API sketches have now been wrong the same way TWICE. Both #6 and #7 were sketched as f32/F32x16 while the real consumer (lance-graph crates/sigker) is f64/Vec<f64>, so both shipped on F64x8. #294 additionally found the sketch wrong about buffer ownership (projections are materialized once per encoder and reused, not re-derived per step) and about shape (k is runtime, so the hot path is a k×k GEMV, not a single-register update). W1.5-#8's `I16x16` sketch is therefore marked UNVERIFIED — 2-for-2 miss rate — and must be read off crates/sigker/src/log_signature.rs before any implementation starts. Also recorded: W1.5-#8 is unblocked, not deferred; and #295 merged ~5s after leaving draft, so its 100% docstring figure is a manual /// scan rather than bot-confirmed. Markdown only — no source, tests, or build files touched. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WkNBjHc2e3zuyz9i8qJEv
1 parent 183c324 commit 68fcfbc

3 files changed

Lines changed: 155 additions & 4 deletions

File tree

.claude/blackboard.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,69 @@
33
> **Read this first.** The "Polyglot Notebook" architecture below is a
44
> separate/older program, not the current epoch.
55
6+
## 2026-09-04 (latest) — W1.5 signature primitives: PR #293/#294/#295 landed, no board entry until now
7+
8+
Three merged PRs closing W1.5 signature-kernel work items went unrecorded on
9+
this blackboard — corrected here.
10+
11+
**PR #293`hpc: signature_pde_sweep`** (merged), closes W1.5-#6
12+
`TD-NDARRAY-SIMD-SIGNATURE-PDE-SWEEP`. Signature kernel `<S(X),S(Y)>` via the
13+
Goursat PDE, anti-diagonal SIMD wavefront. **Correction it recorded:** the
14+
consumer-contract doc sketched `f32`/`F32x16`; sigker is actually
15+
`f64`/`Vec<f64>`. **Now wired:** lance-graph `crates/sigker/src/kernel.rs:35`
16+
does `use ndarray::hpc::signature_pde::signature_pde_sweep;`.
17+
18+
**PR #294`hpc: randomized_signature_sweep`** (merged), closes W1.5-#7
19+
`TD-NDARRAY-SIMD-RANDOMIZED-PROJECTION`. Cuchiero-Schmocker-Teichmann
20+
randomized-signature recurrence on `F64x8`. New file
21+
`src/hpc/randomized_signature.rs` + `examples/randomized_signature_bench.rs`.
22+
Public API: `randomized_signature_sweep`, `randomized_signature_sweep_with`,
23+
`randomized_signature_step`, `const INCREMENT_EPSILON = 1e-15`. Same
24+
lane-type correction as #293 (doc sketched `F32x16`; real consumer is f64 →
25+
`F64x8`); doc also wrongly sketched per-step re-derived Gaussians and a
26+
single-register update — real shape is materialize-once buffers + runtime-k
27+
`k×k` GEMV + axpy, `O(T·d·k²)`. Built only on already-parity-confirmed
28+
`F64x8` methods (splat, from_slice, mul_add, reduce_sum, copy_to_slice) → zero
29+
new arch-specific code, zero `unsafe`. [MEASURED] 2.00x @ k=32 up to 3.79x @
30+
k=512 vs scalar; max rel err 1e-14; cross-backend contract is 1e-9 relative
31+
tolerance, NOT bit-equality (reduce_sum order differs per backend). Second
32+
commit `c129662` fixed a real bug CodeRabbit caught: the ragged-path guard
33+
used `debug_assert_eq!`, which compiles out under `--release`; a wider later
34+
path point would silently truncate and return a signature for the WRONG
35+
path. Switched to `assert_eq!` + a `should_panic` test proving it fires in
36+
release. **Loose end:** sigker's `RandomizedSignatureBuilder::encode` does
37+
NOT yet delegate — still its own scalar loop
38+
(lance-graph `crates/sigker/src/randomized.rs:95`). Wiring is in flight this
39+
session.
40+
41+
**PR #295 — `hpc: docstring the randomized_signature tests, bench, and e2e
42+
pipeline tests`** (merged, master `183c324`). Comments only, no behavioural
43+
change. Motivation: CodeRabbit's docstring-coverage check on #294 reported
44+
61.76% against an 80% threshold, scoped to functions touched by that diff (34
45+
functions / 3 files) — gap was entirely test + bench code; all 3 public fns
46+
and all 4 private compute helpers were already documented. Commit 1:
47+
docstringed SplitMix64 methods, `wiggly_path`, `assert_matches_reference`, 10
48+
of 11 test bodies, 8 of 9 bench fns in `src/hpc/randomized_signature.rs` +
49+
`examples/randomized_signature_bench.rs`. Commit 2: docstringed the 7
50+
`e2e_tests` pipeline tests in `src/hpc/mod.rs` (outside the check's scope —
51+
#294's diff only added a `pub mod` line to that file — but the last
52+
undocumented fns in the hpc surface). Result: 42/42 functions documented
53+
across the three files. CI green: 13 non-skipped jobs incl.
54+
tests/{stable,beta,1.97.1}, clippy/1.97.1, format/stable, wasm-simd,
55+
neon-simd, tier4-avx512, nostd/thumbv6m. **Caveat worth recording:** the PR
56+
was merged ~5s after leaving draft, so CodeRabbit never re-ran the coverage
57+
check — the 100% figure is verified by a strict `///` scan, not by the bot's
58+
own (looser) heuristic.
59+
60+
**Loose ends (all three PRs):**
61+
- sigker randomized-signature wiring not yet landed (in flight, see #294).
62+
- W1.5-#8 `TD-NDARRAY-SIMD-LYNDON-PACK` is the last unbuilt W1.5 primitive.
63+
Its gate (jc Pillar 11, Hambly-Lyons) IS activated — `jc/src/lib.rs:26`
64+
says "Pillar 11 activated 2026-05-07" — so #8 is unblocked, not deferred.
65+
- The consumer-contract doc's W1.5 lane-type sketches have now been wrong
66+
twice (both #293 and #294). #8's `I16x16` sketch should be treated as
67+
unverified until checked against the real consumer.
68+
669
## 2026-09-01 (latest) — Pillar-11 lattice lane: BIT-EXACT i128 lattice signature + Hambly–Lyons Thm 5/6 certificate
770

871
`src/hpc/pillar/lattice_signature.rs` (feature `pillar`). For unit-step

.claude/board/AGENT_LOG.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,36 @@
55
> **Spawn protocol:** every agent reads this file before starting,
66
> appends one entry on completion via `tee -a`.
77
8+
## 2026-09-04 — main thread — W1.5 signature primitives (#293/#294/#295) board-hygiene backfill
9+
10+
**PRs:** #293 (merged), #294 (merged, `c129662` follow-up), #295 (merged, master `183c324`)
11+
**Closes:** W1.5-#6 `TD-NDARRAY-SIMD-SIGNATURE-PDE-SWEEP`, W1.5-#7
12+
`TD-NDARRAY-SIMD-RANDOMIZED-PROJECTION`
13+
14+
Three PRs landed with zero mentions in `.claude/blackboard.md` or this log —
15+
backfilled per the Agent Protocol ("write decisions to the blackboard, not
16+
just to chat"). No code changes this session; hygiene-only. Full detail in
17+
`.claude/blackboard.md` 2026-09-04 entry — summary here:
18+
19+
| PR | File(s) | Outcome |
20+
|---|---|---|
21+
| #293 | `src/hpc/signature_pde.rs` | Goursat-PDE signature kernel, anti-diagonal SIMD wavefront, f64/`F64x8` (doc sketch of f32/`F32x16` corrected); now consumed by lance-graph `crates/sigker/src/kernel.rs:35` |
22+
| #294 | `src/hpc/randomized_signature.rs`, `examples/randomized_signature_bench.rs` | Cuchiero-Schmocker-Teichmann randomized-signature recurrence, `F64x8`-only (zero new arch code, zero `unsafe`); 2.00x–3.79x vs scalar; follow-up `c129662` fixed a real `debug_assert_eq!`-compiles-out-in-release bug on the ragged-path guard |
23+
| #295 | same 3 files, docs only | Docstring coverage 61.76%→100% (42/42 fns) after CodeRabbit's scoped-diff coverage check flagged #294; caveat: merged before the bot could re-verify, so the 100% figure is a manual `///` scan, not bot-confirmed |
24+
25+
**Loose ends carried forward:** sigker `RandomizedSignatureBuilder::encode`
26+
still a standalone scalar loop, not yet delegating to
27+
`randomized_signature_sweep` (in flight per operator note); W1.5-#8
28+
`TD-NDARRAY-SIMD-LYNDON-PACK` is unblocked (jc Pillar 11 activated
29+
2026-05-07) but unbuilt — its `I16x16` lane-type sketch in the
30+
consumer-contract doc should be treated as unverified, since both #293 and
31+
#294 corrected an analogous sketch.
32+
33+
**Verification:** none run this session (edit-only, hygiene backfill; no
34+
`.rs` files touched).
35+
36+
---
37+
838
## 2026-07-29 — main thread — oracle repair + chacha20 reach + BLAKE3 gap
939

1040
**PRs:** #264 (merged), #265 (merged, `58521c3`)

.claude/knowledge/vertical-simd-consumer-contract.md

Lines changed: 62 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -226,9 +226,25 @@ impl U64x4 {
226226

227227
---
228228

229-
## W1.5 — DEFERRED primitives (gated on `lance-graph:crates/sigker` certification)
230-
231-
Three more primitives are queued behind a certification gate. `crates/sigker` is `lance-graph`'s path-signature codec — it's pure-scalar Rust today (zero raw intrinsics, zero ndarray dep), and is positioned as the **Index-regime third encoding lane** alongside palette-distance (bgz17) and NSM tiling (deepnsm). It explicitly bypasses the `I-NOISE-FLOOR-JIRAK` iron rule (Jirak 2016 Berry-Esseen for weak-dependence data) via Hambly-Lyons 2010 path-signature uniqueness.
229+
## W1.5 — sigker primitives (gate now OPEN; #6 and #7 SHIPPED)
230+
231+
> **⊘ CORRECTED (2026-09-04) — this section originally read as three
232+
> future/deferred primitives, gated on a certification that had not yet
233+
> happened. That framing is stale: the gate opened 2026-05-07
234+
> (`lance-graph:crates/jc/src/lib.rs:26`, "Pillar 11 activated
235+
> 2026-05-07"; `jc/src/hambly_lyons.rs` is a live module, `pub mod
236+
> hambly_lyons;` at `jc/lib.rs:37`), and W1.5-#6 and W1.5-#7 have since
237+
> shipped (ndarray PR #293, PR #294). The original sketches below are
238+
> kept verbatim, each followed by a correction block, rather than
239+
> silently rewritten — see the standing note at the end of this section
240+
> for why every remaining sketch (#8) must be treated as unverified.**
241+
242+
Three primitives were queued behind a certification gate. `crates/sigker` is `lance-graph`'s path-signature codec — it's pure-scalar Rust today (zero raw intrinsics, zero ndarray dep), and is positioned as the **Index-regime third encoding lane** alongside palette-distance (bgz17) and NSM tiling (deepnsm). It explicitly bypasses the `I-NOISE-FLOOR-JIRAK` iron rule (Jirak 2016 Berry-Esseen for weak-dependence data) via Hambly-Lyons 2010 path-signature uniqueness.
243+
244+
> **⊘ CORRECTED:** the paragraph above and the "When `jc Pillar 11`… lights
245+
> up" sentence below described the gate as future-conditional. **The gate is
246+
> OPEN as of 2026-05-07.** `crates/sigker` is also no longer purely scalar —
247+
> its consumer wiring for #6 is live (see #6 below).
232248
233249
When `jc Pillar 11` (Hambly-Lyons signature uniqueness on lance-graph paths) activates and sigker is benchmarked at production carrier widths, the W1.5 queue lights up:
234250

@@ -249,15 +265,57 @@ where
249265

250266
2D banded grid sweep; closure-parameterized kernel evaluator per step.
251267

268+
> **⊘ CORRECTED — SHIPPED (ndarray PR #293).** The sketch above is WRONG on
269+
> lane type and is superseded, not merely deferred. Real state:
270+
> - Shipped as `ndarray::hpc::signature_pde::signature_pde_sweep`, an
271+
> anti-diagonal SIMD wavefront sweep.
272+
> - **Lane type is f64-based, NOT `F32x16` as sketched.** The real
273+
> consumer (`lance-graph crates/sigker`) works in `f64`/`Vec<f64>`, so the
274+
> shipped primitive is built on `F64x8`.
275+
> - **Consumer wired:** `lance-graph crates/sigker/src/kernel.rs:35` imports
276+
> it directly; `sigker`'s `Cargo.toml` now carries ndarray as a mandatory
277+
> path dep (no longer the "zero ndarray dep" state described above).
278+
252279
### W1.5-#7`TD-NDARRAY-SIMD-RANDOMIZED-PROJECTION`
253280

254281
Cuchiero-Schmocker-Teichmann (2021) randomized signatures: Gaussian random-matrix-vector update with `F32x16` state. Same closure-batch shape as W1a-#1, different lane type.
255282

283+
> **⊘ CORRECTED — SHIPPED (ndarray PR #294).** The sketch above is WRONG on
284+
> lane type AND on data ownership. Real state:
285+
> - Shipped as `ndarray::hpc::randomized_signature`, exposing
286+
> `randomized_signature_sweep` / `_sweep_with` / `_step`, plus
287+
> `INCREMENT_EPSILON = 1e-15`.
288+
> - **Lane type is `F64x8`, not `F32x16`.**
289+
> - **Ownership model was wrong too:** the sketch implied Gaussian entries
290+
> re-derived per step from `(seed, depth)`. In reality the projections are
291+
> materialized ONCE per encoder instance (seeded SplitMix64 + Box-Muller)
292+
> and reused across every path and step — so the primitive must CONSUME
293+
> caller-owned buffers, not generate them internally.
294+
> - **`k` is a runtime value** (32…4096 in the consumer's own tests), not a
295+
> fixed lane width — the hot path is a `k×k` GEMV plus an axpy per path
296+
> dimension, O(T·d·k²), not a single-register lane update.
297+
> - **Consumer NOT yet wired:** `lance-graph crates/sigker/src/randomized.rs:95`
298+
> `RandomizedSignatureBuilder::encode` still runs its own scalar loop.
299+
> Wiring is in flight in a parallel task as of this correction — treat as
300+
> in-flight, not done.
301+
256302
### W1.5-#8`TD-NDARRAY-SIMD-LYNDON-PACK`
257303

258304
Log-signature compression in the Lyndon basis of the free Lie algebra (7-13× compression, lossless). Pack/unpack primitives on `I16x16` state with combinatorial-index awareness.
259305

260-
**No code needed today for W1.5.** Mentioned here so W1a additions are designed broad enough to compose with these later (in particular: the closure-batch shape introduced in W1a-#1 is the foundation for W1.5-#7).
306+
> **⊘ CORRECTED — still unbuilt, but NO LONGER GATED** (Pillar 11 is active,
307+
> see above). **The `I16x16` state sketch above is UNVERIFIED against the
308+
> real consumer** (`lance-graph crates/sigker/src/log_signature.rs`) — the
309+
> equivalent sketches for #6 and #7 were BOTH wrong on lane type (2-for-2
310+
> miss rate). Do not implement from this sketch. Read the actual consumer
311+
> source first and confirm the real lane type before writing any code.
312+
313+
**Standing note (2026-09-04):** the pattern across #6 and #7 is that this
314+
doc's API sketches predate the consumer code and drift from it — both
315+
missed the lane type, and #7 also missed the ownership model and the
316+
runtime-`k` shape. Treat every remaining sketch in this section as a
317+
starting hypothesis to verify against `lance-graph crates/sigker`, never as
318+
a spec.
261319

262320
---
263321

0 commit comments

Comments
 (0)