2.4 KiB
ADR-0050: Persisted project onboarding and bounded service-key overlap
Status: accepted for RC-02, 2026-09-08.
Persist operator-created projects in the existing registry. A separate immutable onboarding record owns owner, environment and labels; existing manifest-backed projects retain their identities and bindings. Startup reconciliation must never overwrite operator bindings. New requirements target the stable capability gateway, not a model or candidate. Require explicit reindex/schema migration support when the contract requires it. A production environment label never grants promotion.
Use the existing hash-only service credential domain for online project-key administration. This does not depend on a generic secret vault or change the deployment-owned human identity provider. Credential administration remains administrator-only. Project creation and requirements require operator; viewers can inspect non-secret metadata and readiness.
Add superseded_at and enforce one current non-revoked credential per client with a partial unique
index. Rotation conditionally claims the exact current credential and creates its replacement in
the same transaction as audit. A bounded overlap (zero to 24 hours) may retain one predecessor;
it never extends the predecessor's existing expiry. A subsequent rotation retires older overlaps.
Typed revocation claims the same current credential and revokes every key of that service identity.
Concurrent rotation/revocation has one winner. Historical secrets cannot be restored by rotation.
Readiness is derived, not a writable boolean: current credential authentication plus a successful gateway request from that exact credential, the current stable deployment and the last 24 hours. Persist the credential ID in gateway decision evidence; no plaintext key or input is added. A test performed with the previous overlapping key cannot qualify the new key. Missing deployment or fresh evidence remains a visible blocker. Engineering readiness never substitutes for lifecycle production approval or real-consumer certification.
Migration 0026 preserves existing projects and credential hashes. A mechanical downgrade is allowed only before onboarding or rotation history exists. Thereafter recover the verified pre-migration backup. Recovery permits exactly an empty onboarding table and null supersession metadata during an older-schema upgrade; current-schema restore preserves both exactly.