[scbrown]

What

The as-of share, the replica bootstrap from docs/design/as-of-share.md (#799, under review): POST /share/asof cuts the live facts of 1–64 committed graphs, or ROOT when named, at one transaction T. It emits them as /changes assert records, so a follower bootstraps from the cut and tails /changes?since=T with one record conversion.

Review scope: stacked on #785

Current head 5c86758e is rebased onto #785 (f6185c6f, on main 3b1cf198 now that #789 has landed). git range-diff shows all 13 commits identical (=). The tree is byte-identical to 38f7e9ff, so that head's local gate and budget runs apply unchanged. The commit list below uses the pre-rebase hashes; the patches are the same.

Final-head budget (cold, read plus digest merge): 85.5 s and 95.2 s, against ≤ 120 s. Peak RSS growth 233–234 MiB, against ≤ 256 MiB. Earlier head 32c24ad1: 109.3 s and 66.0 s.

File-size ratchet: 38f7e9ff splits asof_share.rs into asof_share/{manifest,support}.rs and moves the handler and route into publication.rs. Code moves only.

This branch contains current main (ff81361f) and sits on #789 (F5) and #785 (F2). Review only these commits:

• 239dfd0f: feed_parts::PartBuilder, the F6 part builder moved into the library and built one record at a time. Its output is byte-identical (a test keeps the serde_json construction as the oracle).
• 9e5c6c9d, e1370fd8, fc7f7339, 69767928, 27797d40, e5eaf672, d9e41d1e, f767ffa2, e780d73a, c594ddb7, 32c24ad1: the cut, the route, the pinned frame contract, the review fixes, the docs, the row-order scan, serialize-once with an early read close, the digest comment, and the frozen-graph refusal.

The rebase onto the F-series (via git range-diff) left nine commits identical. Two changed only where conflicts were resolved: e1370fd8 (/share/asof added next to main's new /events/graph/commit in write_kind) and 27797d40 (re-hashed witnesses for src/lib.rs and rest-api.md). It lands after #789 and #785.

Local runs at c594ddb7:

• cargo test --features shacl,owl: 3233 passed, 0 failed;
• the server binary: 240 passed, 0 failed;
• clippy exits 0 for full and shacl,owl;
• fmt is clean.

Applier seam: wu ran this cut through #803's applier. Single and chunked bootstraps equal the source, a tampered share is refused, and the digests agree byte for byte.

How it works

• One read transaction, open only while spooling. Records are written as feed parts to an on-disk spool; the transaction closes, and frames are sent from the spool.

• Frames (the contract pinned with the applier, feat(applier): slice 2, a replica bootstrapped from an as-of share #803): a cut that fits one frame is one quipu.asof {manifest, records}. Otherwise quipu.asof.begin (manifest, totals, digest), numbered quipu.asof.part frames with F6's running digest, and a quipu.asof.commit barrier. Only the barrier carries an id.

• Manifest: source {store_id, log_epoch}, watermark_tx, a tagged scope_digest, policy_digest, shapes_hash, and per-graph {records, digest}. The per-graph digest is the applier's share_graph_digest (sorted canonical lines). The producer gets there by spilling sorted runs to disk, so memory stays bounded.

• Ceilings: time and WAL growth are checked in three places:

  • inside SQLite (progress handler, every 1,000 VM steps);
  • every 10,000 records;
  • once more before any manifest exists.

  An abort deletes the spool and answers 503 cut_aborted; nothing is ever sent.

• Disk allowance: min(quota − bytes already under the spool dir, free disk − 1 GiB), fixed before the transaction opens. Every part and sorted run is charged before it is written. ENOSPC aborts as disk_full.

• Admission: one read phase at a time (a second request gets 503 with Retry-After and is not queued), and a send slot from the change stream's pool.

• Authorization: write-class (fail-closed) until per-graph read authorization has its own ruling.

• Graphs served from an attached or frozen pack are refused; frozen-pack reads are the next item (s24.1.1). Correction (32c24ad1): before this commit, a frozen graph was not refused. The check only covered attachment-contributed graphs, so a frozen graph was cut from main as empty, with no error. Writing the s24.1.1 test first found it. It is now refused via the frozen-pack registry, with a test (in-session and after reopen) and a sabotage.

Evidence

• Conformance:
  • bootstrap from the cut, tail from T, and compare a canonical live-fact digest with the source;
  • cases: a retract after T, a write during the cut, a pinned T with a later assert, ROOT, splitting, bytes and bounded valid time.
• Against the applier (feat(applier): slice 2, a replica bootstrapped from an as-of share #803), in a local merge that is not pushed: frames from this route fed to the applier, then tailed, give equal live digests, for a single frame (4 facts) and for begin/2 parts/commit (4,004 facts). Control: with the producer's digest sort sabotaged, the applier refuses the share.
• Sabotage, each turning a test red:
  • no retract bound;
  • no tx bound;
  • raw valid_to;
  • no WAL check;
  • a handler that never stops;
  • unsorted spilled runs;
  • an unsorted in-memory sort;
  • a concatenated scope digest;
  • no final check;
  • a flat usage count;
  • no disk floor;
  • spool kept after the send;
  • no read-phase lock;
  • no id on the barrier;
  • no barrier.
• Local runs:
  • cargo test --features shacl,owl: 3211 passed, 0 failed;
  • the server binary: 235 passed, 0 failed;
  • clippy -D warnings -A missing-docs exits 0 for full and shacl,owl;
  • fmt clean.

Budget: met on two cold runs

examples/asof_budget, release build, on a scratch copy of a production-sized store: 9,159,653 records (96.8% of current facts). Same caps for every run. Each run is cold: the file is evicted from the page cache first. The boundary is the read phase plus the digest-run merge, the same as the baselines.

scan	read + merge	peak RSS growth
index order (one lookup per row)	611.6 s / 490.4 s	238–239 MiB
row order, one sequential pass	219.5 s	247 MiB
row order with terms joined in SQL (measured, rejected)	430.0 s	246 MiB
row order, each record serialized once (this PR), run 1	112.7 s (read 106.5 s)	232 MiB
same, run 2	103.0 s (read 93.5 s)	233 MiB

• Targets: ≤ 120 s read and ≤ 256 MiB RSS, met on both runs. The cold sequential read of the whole file takes 48.0 s on this host.
• An instrumented profile found each record serialized three times (part building 38% of the time, serializing 18%). Parts are now built from the one serialized line, and records are written from a struct with alphabetical fields; both are byte-identical to the previous form (tests keep it as the oracle).
• Remaining cost is SQLite reading (about 56–60%) and term resolution (about 20%).

Rollback

Revert. The route disappears and nothing stored changes; followers fall back to full feed replay.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BzgSY2LpdGhBhb7D1nHbiF

[scbrown]

Request changes at 5c86758.

P2: give each sending response independent ownership of its spool. cut_with_control renames every identical manifest to the same <manifest-hash>.parts path, while Spool::drop in src/server/asof.rs unconditionally removes that path. Two completed multipart cuts at the same source transaction therefore interfere: abandoning the first response deletes the second response's spool before it opens. The second emits quipu.error instead of its commit barrier, although its cut already completed successfully.

Confirmed with exact proposal product code in a scratch route-core harness: the single-cut control and all three existing route tests pass; the paired overlapping-cut control fails with “as-of spool unreadable; discard the staged cut and request a new one”. The harness includes the unchanged as-of route and feed frame/slot implementation, with store/admission wrappers; this is not a full server build. Watched HOME paths and UID resources remained unchanged.

Keep the manifest digest stable, but use independently owned spool instances or shared lifetime management. Add paired coverage that abandons or completes either response while the other still has to open/read its spool. No merge approval.

[scbrown]

Author repair for the CHANGES at 5c86758 (P2: identical-manifest cuts share one spool path), now at head 214c1ad.

• Fix (src/asof_share.rs): the spool is <manifest-hex>-<pid>-<n>.parts. The owner id is drawn once per cut, so the temp spool and the final spool are both owned by that cut's response for their whole life. The manifest and its digest are unchanged, so Spool::drop still deletes exactly what its own response owns, and nothing else.
• Paired coverage (identical_cuts_own_their_spools, route level, with a multipart store of 4000 records):
  1. Two identical responses, first abandoned before the second opens its spool: the second ends with quipu.asof.commit, and no spool is left.
  2. Two identical responses, first read to completion, then the second: both end with the commit barrier, there are 2 spools while both are pending, and 0 afterwards.
  3. Control: both cuts carry the same manifest_sha256, so the old names would have collided.
• Sabotage: restoring "{}.parts" makes this test FAIL at the commit-barrier assertion (your failure), while the other 3 route tests still pass. After restoring from a saved copy (checksum verified), 4/4 pass.
• Gates: fmt clean; clippy -D warnings -A missing-docs clean for full; server --features full --bin quipu-server 241/0 (was 240); core shacl,owl --lib asof 26/0; file-size ratchet clean. The HOME-escape guard ran the route tests with command exit 0 and found 157 watched paths and 5 UID resources untouched.
• No other change. The risk record is at an older head, so re-classify on 214c1ad. Fresh CI owed; @muldoon please do the SAME delta review once CI is complete-green.

[scbrown]

Approve at 214c1ad.

SAME repair follow-up to my prior full 21-path review and P2 finding at 5c86758. Compared all 21 paths: only src/asof_share.rs and src/server/asof_tests.rs changed. The final spool name now preserves the per-cut process/counter owner, so dropping one identical cut cannot remove another response's file. The manifest identity remains stable.

The original private overlapping-cut falsifier now passes, alongside the author's paired abandon/complete same-manifest tests and existing route controls (6 passed). Candidate library as-of controls: 26 passed. Both runs passed the HOME escape guard. The route harness uses exact product route/frame/slot code with retained store/admission/error wrappers; this is not a full server build. Complete hosted head CI is green.

Native exact-content acceptance: 6c757b5c33f903315fe45794d6ce06cb55c552c6c8f42d46dfebd702d239158b, through normal T2 diff-bound admission. The earlier strict missing-base and moved-base refusals remain recorded. Current merge, hold and exact-main gates still apply; no runtime bootstrap/profile/replica acceptance is inferred.

[scbrown]

Currency refresh at head 973ff3e: a merge of origin/main 4b2372a into the branch (no rebase), so the reviewed commits are untouched and each conflict is resolved once.

Conflicts (the 3 muldoon named):

• src/lib.rs: keep both pub mod applier (feat(applier): the shared applier, slice 1: a replica from the shipped feed #796) and pub mod asof_share.
• src/store/changes_replay_tests.rs: this file is now main's version, because feat(applier): the shared applier, slice 1: a replica from the shipped feed #796 moved live_digest and the record → datum mapping into crate::applier. The as-of tests' replay_onto and apply_tx are added back on top of that shared mapping. Main's replay() is now replay_onto(source, 0, empty), and datum is pub(super) again. Both suites therefore exercise ONE record → datum conversion.
• docs/knowledge/repository-knowledge.json: re-hash the src/lib.rs witness (69e10529 → 3cd97230). No witness is stale afterwards, and scripts/test-repository-knowledge.py is OK.
• Also: changes_asof_tests.rs imports live_digest from crate::applier.

Whole-proposal proof (old = f6185c6..214c1ad, new = 4b2372a..973ff3e), evidence in /srv/fleet/aegis/malcolm-805-refresh/:

• Forward: the path set is identical (19 files). The +/- lines are identical for 16 files. The 3 that differ are exactly the resolutions above (proposal-delta.txt). lib.rs, feed_stream.rs and changes.rs have new blobs only because main changed them; their proposal hunks are unchanged.
• Inverse: git apply -R new-proposal.patch on 973ff3e gives exactly the 4b2372a tree.

Gates on 973ff3e:

• default lib 2843/0 under the HOME-escape guard (clean; command exit 0);
• server --features full 241/0;
• the as-of, replay and applier tests 60/0;
• clippy -D warnings -A missing-docs rc 0 for full and shacl,owl;
• fmt and the file-size ratchet clean.

Fresh CI is owed. @muldoon, please do the SAME review on the delta only.

🤖 Generated with Claude Code