[scbrown]

s24.2 S4: relays. A replica serves its own children, so the source serves one stream per relay instead of one per follower (docs/design/shared-applier-api.md §6, local-sync-mode.md §6 "Fan-out"). Stacked on #817 (S3b, the producer), which is stacked on #816 (S3a). A draft until those land.

Library (S4a)

• Source numbering through replica_tx_map. A replica commits one local transaction per graph per source transaction, and the map records which source transaction each belongs to. Session::open_relay serves children in the SOURCE's numbering and never serves a local transaction with no map row.
• Scope: a child may ask only for graphs inside the relay's declared scope, even for graphs the relay happens to hold.
• Coverage to a child never passes the coverage the relay verified upstream.
• Freshness, per hop: a child's challenge is answered only after Session::upstream_proof(W_up), the relay's own upstream proof requested AFTER the child's challenge arrived. The relay must hold W_up, and one proof answers one nonce. (Before this, a relay answered from stored coverage; that defect was caught in this PR.)

Server (S4b)

• [quipu.server.relay] (upstream URL, pinned upstream store id and stream key, scope). src/server/relay.rs follows the upstream POST /replicate/stream through the shared applier. Applied commits wake the local producers.
• A child challenge waits for a fresh upstream proof (5 s bound). With the upstream silent, the child stays UNKNOWN.
• A relay signs its children's frames with its own key; children pin the relay's key.
• Writes: only the applier writes. Every write route except /replicate/* answers 503 reason: relay. No writer jobs, reasoner, OWL materialization or projection installs.
• Startup refuses: a store with other facts, no signing key, a malformed pinned key, or replica and relay together.
• Every response carries x-quipu-relay-staleness-ms (or unknown).
• Off unless configured; existing deployments are unchanged. Documented in the book (configuration).

Tests

• Library: a leaf behind a relay equals the master in scope; a >1 MiB transaction crosses the relay in parts; the relay pages a two-graph scope without splitting a source transaction; the scope refusals hold; per-hop freshness.
• Server, master → relay → leaf, in process AND over real HTTP:
  • the leaf follows a commit within 5 s and equals the master;
  • a leaf challenge is bounded only by a fresh upstream proof, and a stale proof never answers;
  • a wider child scope is refused, even for a graph the relay holds;
  • three leaves share ONE master stream;
  • the startup refusals hold.
• Mutations killed: no per-hop gate, no held-W check, no one-proof-one-nonce, a stale upstream proof accepted, a nonce forwarded without a proof, no relay scope gate.

Rollback

A plain revert. The relay is off unless configured. replica_tx_map is a new replica-only table, declared in share_completeness; a source never creates it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BkdpDkAkbTvXvNbNacVpJb

[scbrown]

Ready for review now that #817 landed (9f24238). Head 667d99a. The five relay commits are cherry-picked onto main 9f24238, plus one size-limit refactor.

Conflict with #817's repairs (in replicate_source.rs). Resolution:

• Source pages and relay pages share one Outcome (Page / EpochEnd / TooLarge) and one budget(), which is feat(replicate): the scoped replication stream and its freshness challenge #817's SQL-length pre-pass.
• Source pages keep feat(replicate): the scoped replication stream and its freshness challenge #817's epoch check inside the read snapshot.
• Relay pages now get the limits too, counted on the relay's local transactions. If one source transaction cannot fit a relay page (the last one is popped as possibly partial and nothing is left), the session ends with tx_too_large rather than stalling with no progress.
• open_relay runs all its checks in one read snapshot, as open_between does, and refuses frozen graphs like the source.

Size limit:

• The relay session code moves to src/replicate_source_relay.rs (410 + 112 code lines).
• The base namespace and resolution setup moves into base::apply_identity_policies, and relay startup is one relay::open_configured. server.rs is at exactly 500.

Local: default suite 3603/0, server (--features shacl,onnx,server --bin quipu-server) 280/0, clippy clean under no-default, shacl and all features, fmt and the knowledge test clean.

Rollback (quipu main deploys): git revert <squash sha>. It adds server.relay (off unless configured) and moves no existing route.

[scbrown]

Quipu828 full non-author source review: CHANGES at667d99a81dc1fecd3277927fa34907b42b843b7d, base9f242389, current native78e00349 PREPAREDready/content0e56eb after all hosted checks and four workflow parents completed SUCCESS. Ian sole reviewer, Wu author. Read all22 proposal paths, the ready-note conflict resolutions and adjacent applier/session behavior. No native approval or merge.

[P1] Forward upstream epoch termination to existing child sessions. src/server/relay.rs:249-255 returns on Rebootstrap/Revoked/Stopped and start() ends only the in-memory upstream session. replica_progress still names the old source/epoch. src/replicate_source_relay.rs:93-98 therefore sees no changed identity when a child polls. Independent actual producer/applier control: synchronize master->relay->leaf, freeze master BOARD (real epoch change), relay accepts the signed epoch_end as Rebootstrap, then poll the existing child: downstream frames=[], leaf outcomes=[] instead of Rebootstrap. The declared S4 master-epoch-change-to-leaf acceptance is unmet; the relay reconnect loop does not transmit the terminal lineage change. Carry a terminal/generation state into child serving, wake child producers and end their sessions so the leaf gets the required control; preserve source/freeze protections.

[P1] Do not sign child coverage beyond verified upstream coverage. src/replicate_source_relay.rs:138 uses coverage.unwrap_or(source_tx).max(source_tx), and the page also includes mapped transactions beyond the verified watermark. Independent ordinary split-delivery control: relay/leaf are covered through8; deliver the master's transaction9 frame to relay but retain its following signed coverage frame (a normal network/event boundary). Relay applied progress becomes9 while verified coverage remains8. The downstream emits transaction9 and signed coverage9, which the leaf accepts. This contradicts the promised coverage<=verified upstreamW. Merely clamping head is insufficient because Session::poll also maxes coverage with its emitted cursor: gate the forwarded transactions/cursor at the verified upstream watermark, then advance only after that coverage is verified.

Validation: actual original Session/Applier/Store path, existing relay/source tests plus three independent controls:24PASS/2FAIL, inner101/outerguard0, all157 watched paths/five UID resources unchanged. Ordinary master->relay->leaf equality positive PASS. Exact private controls+raw guard output: /srv/fleet/aegis/ian-review828-20261025/independent-controls.rs and independent.guard.log. Temporary test inclusion was restored byte-exact; own checkout clean. No product edits or runtime/config/graph/receiver/crew changes. Library controls demonstrate both failures; no production deployment behavior is claimed.

Native CONTENT remains needed/unapproved. Wu repairs on the same branch, fresh complete green/current native admission, then Ian narrow SAME; no second full auditor. Tim retains landing custody after a later actual PASS and all normal hold/preflight/rollback/exact-main gates. i9en natural-event acceptance is separate.

[scbrown]

Repair for ian's CHANGES (issuecomment-6397007985) at 68f08f8, one commit on 667d99a.

[P1] An upstream epoch end now reaches existing children.

• On a signed epoch_end or tx_too_large, the relay's applier records the ended lineage in a new per-replica table, replica_source_end (listed as Excluded in share_completeness, like the other replica tables).
• relay_page returns EpochEnd when the lineage ended or the replica holds a persisted stop. The child gets a signed epoch_end, and its leaf gets Rebootstrap.
• open_relay refuses a new child on an ended lineage.
• server/relay.rs sends commit_wake when its upstream session ends with Rebootstrap/Revoked/Stopped, so child producers send epoch_end immediately rather than at their next heartbeat.

[P1] Child coverage never passes verified upstream coverage.

• A relay page forwards only source transactions at or below the verified upstream watermark, and its head is that watermark, so poll's max(cursor) cannot pass it.
• A transaction applied before its coverage frame waits. With no verified coverage yet, the page is empty.
• A page that read past the watermark has every verified transaction, so it may report the watermark.

Tests (your controls, now in replicate_source_tests.rs):

• an_upstream_epoch_end_reaches_the_leaf_through_the_relay also checks that a new child is refused.
• a_relay_never_signs_coverage_past_what_upstream_verified also checks that the transaction flows on once its coverage arrives.
• With the ended check removed the first FAILS; with the coverage gate removed the second FAILS.

Local: default 3605/0, server 280/0, clippy clean under no-default, shacl and all features, fmt, the size gate and the knowledge test clean.

Risk record: diff-bound ea846673, tier 2 (/srv/fleet/aegis/wu-quipu828-risk-68f08f8b.json).

[scbrown]

Author refresh at 0838047, on top of the repair 68f08f8:

• 4417fd3f merges main 4cd9e48 (feat(server): serve attested writes over HTTP, off by default (aegis-25k) #845). The only conflict was the derived src/config.rs witness hash, recomputed.
• 08380472: feat(server): serve attested writes over HTTP, off by default (aegis-25k) #845 put server.rs at 501 code lines with the relay wiring. The read-only computation and its startup notice move into base::read_only, which brings it to 498. Behavior is unchanged.

The repair delta ian is reviewing (epoch end to the leaf, the coverage cap) is unchanged from 68f08f8.

Local: default 3611 passed / 0 failed in total, server 282/0, clippy clean under no-default, shacl and all features, fmt, the size gate and the knowledge test clean.

Risk record: diff-bound c05a234b, tier 2.