#12 docs: boundaries charter + CI-enforced invariants

[gregoryfoster]

Closes #12 (step 1 of the sequencing agreed in the issue thread).

What ships

• docs/contracts/replicator-boundaries.md — the charter, sibling to the issuer contract: that settles the wire, this settles the service.
• tests/test_boundaries.py — eight invariants, run by the existing CI on every PR to main. All pass; each corpus scan was verified red against a planted violating module before commit.
• Cross-links from the issuer contract and AGENTS.md, plus the charter registered as a SocratiCode context artifact.

Departures from the draft in #12

Four, each because the assertion as drafted would not have held or would not have held for long:

Draft	Shipped	Why
grep for domain vocabulary	AST over identifiers and string literals, docstrings and comments skipped; bare watch dropped, watched_item kept	the grep matched both tasks watch one stop event in a docstring. A test whose first tripper is an English sentence gets deleted rather than heeded. String literals are in scope because leakage arrives as a dict key (detail={"info_source_id": ...}) as often as an attribute
ingress is health-only	ingress is read-only: allowlisted paths, GET/HEAD only, recursive route walk	FastAPI's three introspection routes are not the admin API the charter rejects; disabling them behind a dev flag would make the app under test differ from the app that ships, for a surface no deployment serves
six assertions	eight — added the deployed process has no ingress, and the tracked violation is pinned	the drafted ingress test covered src/api, which nothing deploys. The worker is what binds no port, and an admin listener could have grown inside src/worker/ with the invariant still green
every Settings field is REPLICATOR_*	plus BUILD_ID exempted by name, and a second test pinning the exemption list at one entry	the repo departed from the prefix rule deliberately; an unnamed exemption reads as the charter being wrong about the code, and an exemption list that grows is the convention ending quietly

Charter content beyond the draft

• Politeness promoted to the worked example. It is the case the three tests do not resolve to one side, so it is the one that teaches mechanism-vs-policy. Conditional GET kept, shorter.
• The policy stream is a Phase 4 cutover precondition, not a follow-on, with the conservative-default interim named as the cheap alternative. Cross-ref Phase 4 cutover blocker: per-domain rate limiting stops working the moment Watcher stops fetching watcher#245.
• MAXLEN trimming specified, because periodic full republication onto an untrimmed stream is unbounded growth — the same argument that deferred non-terminal facts in Publish fetch_failed facts so permanent failures stop being silent (cannobserv#270) #9 §3 — and here it costs boot time too.
• A Redis hash is rejected in writing, so it does not get re-litigated: no schema_version, no co-core model, couples to a key name rather than a payload contract.
• The park-and-reclaim rate floor is quantified. Verified against the Watcher checkout: DEFAULT_MIN_INTERVAL = 1.0 s baseline, BACKOFF_MAX_INTERVAL = 60.0 s. REPLICATOR_CLAIM_MIN_IDLE_MS is 60 s, so parking matches the backoff case and misses the normal case by 60×. Silent, and in the safe direction, which is what makes it easy to ship by accident. The charter states the constraint and two candidate resolutions without adopting either.

Verification

369 passed, 12 deselected — coverage 99.70%
ruff check . — All checks passed

Planted-violation check (one module importing sqlite3 + uvicorn and declaring event_type / info_source_id) fires five of the eight corpus assertions; removed before commit.

🤖 Generated with Claude Code

[gregoryfoster]

Step 2 added: per-host pacing (dfce7b0)

Scope grew by design — the charter's interim was cheap enough to ship in the same PR, and it is the thing that unblocks the cutover.

REPLICATOR_MIN_HOST_INTERVAL_SECONDS, default 1.0 s = Watcher's own DEFAULT_MIN_INTERVAL. Chosen because it invents nothing: the numbers are the issuer's under the charter, so the least-wrong stand-in is the one the cluster already commits to. The cutover changes who paces, not how much.

The split is the design

Wait	What happens
<= REPLICATOR_READ_BLOCK_MS (5 s)	slept through in the handler
longer	TransientFetchError → parks for claim_stale

Park-only is the obvious implementation and is wrong by 60×. A parked wait cannot be shorter than REPLICATOR_CLAIM_MIN_IDLE_MS (60 s) while the normal interval is 1 s, so every host would have been paced at 1/60th of today's rate — silently, and in the safe direction, which is exactly what would have made it easy to ship. Sleep-only holds every other host's commands, and a SIGTERM, behind one origin's politeness.

The park bound is derived from the poll window rather than given its own knob: a wait shorter than a poll the loop already performs adds nothing to the shutdown latency TimeoutStopSec is sized for. tests/test_deploy.py now pins that third term (5 + 5 + 120 < 180).

Details that are load-bearing

• Transient in both directions — being polite can never burn the delivery ceiling.
• The stop event cuts a sleep short and the command then parks, rather than fetching unpaced on the way out. An interrupted wait is not an elapsed one.
• Only a request that goes out calls record(). Stamping a parked attempt would space the origin from requests it never received, and a run of redeliveries would push the next real fetch out indefinitely.
• The pacer is built from settings when not injected — the seam fails open, and a byte path that quietly stopped pacing is indistinguishable from one that is working. Same argument as the BlobUsage identity pin one seam over, with a test to match.
• In-memory host → last-request map, pruned. Derived, bounded, rebuildable by replay — the second of the three state shapes the charter permits. Pruning drops only hosts whose interval has elapsed, so the bound can never be enforced by forgetting a host that is still owed space.

Issuer-visible, so the contract says so

New line under What Replicator does not guarantee: a burst of N commands for one host now takes at least N seconds, and a reaper's timeout (MUST-6) must be sized against the depth of the burst rather than against one fetch. Announcing on CannObserv/watcher#241 per the contract's change rule.

Verification

389 passed, 12 deselected — coverage 99.72% (pacing.py 100%)
ruff check . / ruff format --check . — clean
CI green on dfce7b0