docs(scratchpad): the reset-per-rollout contract assumes one replica #518

Merged

coilyco-ops merged 1 commit from eng/the-scratchpad-assumes-one-replica into main

2026-08-13 15:03:34 +00:00

coilyco-ops commented

2026-08-13 15:01:18 +00:00

Member

The addressing model, which is what the issue could not check

The scratchpad is per requester, not per turn and not per context:

requester := RequesterFrom(ctx)
partition := filepath.Join(p.Root, scratchPartitionName(requester))

scratchPartitionName is sha256(requesterID)[:16], hashed rather than stripped so two ids differing only in punctuation cannot collide. A turn with no requester is refused outright rather than pooled into a shared directory.

So the partition is stable across turns for one requester. Cross-turn continuity is the capability, not a side effect of it — the doc already says the scratchpad is "useful across a conversation".

That makes the split the worst available shape. The thing a second replica breaks is exactly the thing the capability is for. A file written in one turn is present in the next only if the next turn lands on the same pod, and nothing binds a requester to one.

What changed

One paragraph, stating that the contract assumes a single replica and what a second pod would do to it.

Net zero on lines: sirens-echo-scratchpad.md sits exactly at the 80-line cap, so the paragraph was tightened rather than extended. I tried twice at 81 lines before getting it right, and the gate caught both.

Not decided here

The three options in the issue are still open, and this does not pick one. It makes the current contract accurate so that whoever picks is choosing rather than discovering.

Worth knowing when they do: #487 already settled the replica question against multi-replica on other grounds — the duplicate gate, the job store and the rate limiter are all per process, so two pods would double-reply, double-run jobs, and double the fleet-wide admission ceiling. The scratchpad is a fourth instance of that class rather than the deciding one.

closes #489

## The addressing model, which is what the issue could not check The scratchpad is **per requester**, not per turn and not per context: ```go requester := RequesterFrom(ctx) partition := filepath.Join(p.Root, scratchPartitionName(requester)) ``` `scratchPartitionName` is `sha256(requesterID)[:16]`, hashed rather than stripped so two ids differing only in punctuation cannot collide. A turn with no requester is refused outright rather than pooled into a shared directory. So the partition is **stable across turns for one requester**. Cross-turn continuity is the capability, not a side effect of it — the doc already says the scratchpad is "useful across a conversation". **That makes the split the worst available shape.** The thing a second replica breaks is exactly the thing the capability is for. A file written in one turn is present in the next only if the next turn lands on the same pod, and nothing binds a requester to one. ## What changed One paragraph, stating that the contract assumes a single replica and what a second pod would do to it. Net zero on lines: `sirens-echo-scratchpad.md` sits exactly at the 80-line cap, so the paragraph was tightened rather than extended. I tried twice at 81 lines before getting it right, and the gate caught both. ## Not decided here The three options in the issue are still open, and this does not pick one. It makes the current contract accurate so that whoever picks is choosing rather than discovering. Worth knowing when they do: #487 already settled the replica question against multi-replica on other grounds — the duplicate gate, the job store and the rate limiter are all per process, so two pods would double-reply, double-run jobs, and double the fleet-wide admission ceiling. The scratchpad is a fourth instance of that class rather than the deciding one. closes #489

coilyco-ops added 1 commit

2026-08-13 15:01:18 +00:00

docs(scratchpad): the reset-per-rollout contract assumes one replica

ci / image-build (pull_request) Successful in 22s

Details

ci / test (pull_request) Successful in 47s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

476c26a45f

The scratchpad is partitioned per requester by a hash of the account id
and is stable across turns, so cross-turn continuity is the capability
rather than a side effect of it. A second pod would carry a second
emptyDir with nothing binding a requester to either, which turns a rule a
member can learn into a coin flip.

Written net-zero on lines because the file sits exactly at the 80-line
cap, so the paragraph was tightened rather than extended.

closes #489

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-13 15:01:18 +00:00

coilyco-ops merged commit ad86e69b5b into main

2026-08-13 15:03:34 +00:00

coilyco-ops referenced this pull request from a commit

2026-08-13 15:03:36 +00:00

Merge pull request 'docs(scratchpad): the reset-per-rollout contract assumes one replica' (#518) from eng/the-scratchpad-assumes-one-replica into main