[antoinetoussaint-byte]

Closes #1154

What we are trying to do

Let the policy-log witness run on a hosted cell before any warehouse front exists, so the host can get a policy-log transport and stop refusing every narrowing of authority. And make the evidence it writes immutable in the way its README requires: "with retention and IAM, in addition to application checks".

The decision

Owner, 2026-10-18, verbatim: "YES LET'S IMPROVE ALL THIS". That was the answer to: "should the witness be allowed to start with no mirror configured, saying so at boot, the way accounts does?" It reverses the 2026-10-17 call that policy-log stays in CreateContainerConfigError until a warehouse front exists.

#1133, the mirror speaking the warehouse front, stays open. It is no longer on the start path.

Changes

• resolveSettings. The bucket is always required. POLICY_LOG_WAREHOUSE_ENDPOINT and POLICY_LOG_WAREHOUSE_TOKEN are optional, but only together; one without the other is refused as a half-provisioned group, naming the missing key. Every missing key is still named in one refusal, and there is still no process-environment fallback and no value in any refusal.
• startMirror. A whole mirror builds the writer and starts the bounded worker, as before; a writer refusal (for example a non-https endpoint) still refuses the boot. With no mirror configured it wires mirror.None and prints one line naming both settings: the object store is the authority, and Read is what a warehouse added later backfills from. mirror.None is a named value rather than a nil, so "no mirror" is something the wiring states. service.New still refuses a nil mirror.
• Settings are read with WorkspaceValueIfSet. A value nothing carries is absent. A value the carrier could not read is refused by name, so a broken delivery of both mirror settings cannot boot claiming no mirror is configured.
• Locked retention on every entry. POLICY_LOG_RETENTION_DAYS is required with the bucket: a whole number of days, bounded in days before it is multiplied, and at most ten years. Every entries/ object is created under a Locked GCS object retention until now plus that horizon. Nobody, a project owner included, can delete or replace it before then. The head carries none, because it is rewritten on every append. A bucket without object retention enabled rejects the write, so it refuses every append rather than accepting evidence it cannot protect. This is the retention half of the README's requirement; the infrastructure's half is IAM:
  • the witness identity may create under entries/ and set retention only there;
  • it may replace only head.json;
  • it holds no delete under entries/.
• README. It covers the boot order, the configuration rules, the "Warehouse mirror" section, the IAM scope the lock needs, the fact that enabling object retention cannot be undone, the 400/403 symptoms of a misprovisioned bucket, and how an entry orphaned by a lost head commit is unstuck (retry the identical entry).
• Local defaults. The shipped secret default leaves the optional token out instead of shipping a placeholder that would read as half a mirror, and the local policy-log.env declares POLICY_LOG_RETENTION_DAYS.

Fix or hack: a fix, at the owner of the behaviour. The witness decides what it needs to witness, and its authority never depended on the mirror.

Reused, not rebuilt: the existing mirror.Worker, mirror.NewWriter and service.Mirror interface are unchanged. mirror.None is a five-line implementation of that same interface. No second mirror path was added.

Testing / Validation

• go build ./..., go vet, gofmt -l (clean) and go test -count=1 ./... all pass in module/services/policy-log/code.
• node module/tools/naming-gate.mjs check passes.
• TestEveryDeclaredGroupShipsALocalDefault passes; it caught the empty token default.
• New tests:
  • TestABucketWithNoMirrorIsAStartableWitness: a bucket with no mirror resolves, with no mirror.
  • TestNoMirrorIsStatedByNameAtBoot: wires mirror.None and prints exactly one line naming both settings.
  • TestAConfiguredMirrorIsBuiltAndStaysSilent: a whole mirror starts the worker and prints nothing; a writer refusal still refuses the boot.
  • TestResolveSettingsNamesEveryMissingKeyAtOnce now covers "no bucket and half a mirror" in one refusal.
  • TestAnUnreadableMirrorIsRefusedNotReadAsAbsent, TestTheEntryRetentionIsAWholeBoundedNumberOfDays (including 213504 and the int64 maximum), TestEntriesAreLockedForTheDeclaredRetentionAndTheHeadIsNot (the lock is asserted on the wire), and TestTheRetentionIsRequiredAndBounded.

Independent security review

• Round 1 (f9991ba): MERGE WITH FOLLOW-UPS. Fixed: an unreadable setting was read as "no mirror"; the README still called the token mandatory; the local token placeholder.
• Round 2 (de0e477): MERGE WITH FOLLOW-UPS. Fixed:
  • g1, a day count that overflowed into a 25-minute lock;
  • g2, the setRetention IAM scope (documented; the infrastructure grants it only under entries/);
  • g3, the misprovisioning symptoms (documented);
  • g4, the orphaned-slot procedure (documented).
• Owner question raised by the review: there is no retention minimum, so 1 is accepted.

Not verified: the binary has not booted against real GCS here. That needs the dedicated evidence bucket and its head.json, which the infrastructure side provisions. The 400/403 behaviour, and how the IAM condition applies to an upload that carries a retention, are read from Google's documentation and have not been exercised.

🤖 Generated with Claude Code

[antoinetoussaint-byte]

Superseded by #1257 (3c53033): the policy-log witness service is deleted and accounts' narrowings now apply directly through the shared authority core.