carlos / platform Public

spec+plan: what a design review found in the half not yet written

Tasks 14-17 were reviewed BEFORE implementation, which is the point:
five blockers, and two of them are places the spec contradicted itself.

THE GUARANTEE WAS BACKWARDS. §6.4 said callbacks are at-least-once.
They are at-MOST-once: DrainApp deletes the queue items before delivery
is attempted, so a console that dies between the delete and the POST
loses that callback and nothing re-sends it — the sweep re-tags the
object but never delivers. Duplicates are still possible, so apps must
be idempotent AND must not treat the callback as the delivery mechanism.
The docs now have to say: if no callback arrives within your timeout,
poll. The case that makes it matter is `infected` + `recorded:false` +
a lost callback — enforcement is not in effect, the object is servable,
and nothing tells the app unless it asks.

THE BODY CONTRADICTED §11.7. §6.3 put the opaque version token in the
callback body; §11.7 says "no door or app sees the token" and calls it a
tested property. Both sentences were in the same document, facing each
other. §11.7 wins, because it is the property the version binding exists
to protect: an app holding the token is an app that can compare it
wrongly, which is the laundering bug arriving as a correctness bug. The
ETag stays — the app has it from its own PUT.

DELIVERY MUST NOT RUN IN THE DRAIN'S GOROUTINE. The plan named
scandrain.go and said nothing else, and the obvious implementation puts
a tenant's hanging endpoint directly in the path of every other tenant's
verdict: fifty items times a retry schedule, inside a tick that sweeps
apps sequentially. That is the starvation §7.2 and §7.3 exist to prevent,
and a tenant can trigger it by pointing a callback at a black hole. Now
specified as a bounded worker pool with a per-app in-flight cap.

BEHAVIOUR WITH NO MASTER WAS UNDEFINED, and the enqueue door already
accepts callback_path — so the implementer's three choices included
"send it unsigned", which is the hole §6.3 opens by describing. Decided:
the door refuses with 503 callbacks_not_configured, and delivery will not
build a request without a signer.

"PACED RE-SEAL" HAD NO MECHANISM. It is `scan sweep`'s now: one budget
per call, an answer saying how many apps remain, the CLI loops. Plus the
multi-console ordering nobody had written down — every console must hold
both masters before the rotation runs, or a console still on the old one
signs callbacks that apps re-sealed by another console cannot verify.

Two factual corrections. §6.2 claimed an app with only its own domain
gets no callbacks; the domains loop mints the platform host from ANY
ready route (`firstReadyUpstream`), custom domains included, so the true
condition is "no ready route at all". And §11.3's properties are
properties of the APP's verifier, which is tenant code — so task 14 now
ships `VerifyCallback` as the reference implementation the docs
reproduce, or the tests test nothing anybody runs.

Also added, all from the review: a per-app `webhook_gen` so a tenant that
leaks its key does not need a deployment-wide rotation and a reclaimed
app name cannot inherit a deleted app's key; a domain label in the
derivation; a key id under a different label from the tag scheme's; a
distinct app-side variable name, because the same name for master and
derived child is how a master ends up in a tenant environment; `revoke`
unsetting the secret; both secrets folded into one Apply so a first grant
restarts the app once rather than twice; and a note on why a delimiter is
right here when scantag.go uses length prefixes, so the next person to
notice the inconsistency finds the reason instead of "fixing" it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ExnZtUYmt2h8QFcymjPaSL