Deploy the admission boundary

Place the durable v2 Worker in front of one scarce GET or HEAD route. The Worker owns capacity, payments, execution leases, and the signed handoff to a fixed upstream.

Installation status

There is no public npm install path yet. Deploy packages/admission-worker from an authenticated checkout of this private repository. The optional npm run sdk:bundle -- <directory> output is client-only and deliberately excludes this Worker and console. The older @x429/hono example is unmistakably legacy v1 and does not provide the v2 proof, auction, exact-payment, lease, or origin-assertion boundary.

npm ci
npm run check
install -d -m 700 .x429/staging-secrets
npm run keys:generate -- x429-staging-2026-07 \
  --secret-output .x429/staging-secrets/issuer.json
npm run keys:generate -- x429-origin-staging-2026-07 --origin \
  --secret-output .x429/staging-secrets/origin.json
npm run worker:preflight:staging
npm run worker:bootstrap:staging -- \
  --secrets-file .x429/staging-secrets/bootstrap.json

Key generation prints only public metadata. Import both distinct owner-only JSON files directly into the operator secret manager without displaying their private fields.

The first secret-bearing deployment requires one flat mode-0600 JSON file containing exactly the names declared by secrets.required. It validates both keypairs, distinct operator tokens, and two different RPC hostnames before one strict issuance-disabled upload. Do not install these Worker secrets one at a time. Later safe redeployments use worker:deploy:staging without a secrets file.

Never cat, echo, shell-substitute, or put a private field in argv. The credential writers are POSIX-only. On native Windows, use reviewed secret-manager-native tooling that does not invoke them, or WSL with output on a private Linux filesystem—not /mnt/c or another shared mount. Otherwise, do not run them; native Windows support is not claimed.

The launch templates start with X429_ISSUANCE_DISABLED=true. Verify health, discovery, keys, economics, upstream isolation, and an optional fail-closed 503 admission_draining resource probe first. Enable issuance only after those gates pass, redeploy, and verify the explicitly enabled state.

Request decision order

Reject protected methods other than GET and HEAD, normalize the exact target, and verify the client's fresh Ed25519 proof.
Select one deterministic SQLite Durable Object for the canonical resource and method.
Admit instant capacity or, under overload, reserve one future free slot and return a signed ticket plus a finite paid auction offer.
For a free ticket or paid permit, acquire a durable execution lease before the fixed upstream request.
Send X429-Origin-Assertion bound to the upstream audience, method, exact target, lane, request id, receipt digest, expiry, and one-time nonce.
Release the execution identity only if fetch never starts. Once dispatch begins, finalize it as consumed even when transport returns no response; if finalization fails, keep it fenced until bounded consumed-state recovery. A retry cannot start a second application execution.

Existing API versus greenfield

For an existing API, route one measured scarce GET or HEAD endpoint through the Worker, set one fixed X429_UPSTREAM_ORIGIN, preserve the origin's own authentication, and block direct origin access. x429 schedules an already-authorized request; it does not grant account access.

For a greenfield service, the same separate boundary is the safest start. Running without an upstream returns the local admission response and proves mechanics only; it is not a deployed application.

For a deployed exact launch profile, generate the one tester's Ed25519 identity with npm run client:identity -- --kid x429-client-NAME --output PRIVATE_FILE. The command writes a new mode-0600 file and prints no private key. Import it into a secret manager, vet the thumbprint/public key out of band, and place exactly that thumbprint in X429_ALLOWED_CLIENTS. Keep one paid slot, reserve equal to maximum, and one outstanding paid obligation.

Current resource identity

V2 uses an explicit operator-owned scheduling boundary. X429_ROUTE_POOLS maps exact application paths or terminal /* prefixes to named finite pools. Deterministic longest-prefix matching selects one pool; paths in that pool share its Durable Object, query values remain bound into every proof and credential, and unmatched paths return 404 instead of reaching the origin.

The proxy strips inbound CF-* headers before forwarding. Edge-injected Access claims are not visible to the signing client and cannot be safely added to X429_BOUND_HEADERS; use client-visible bound application credentials unless a separate verified-edge-context design is implemented.

Operational state is explicit. X429_ISSUANCE_DISABLED=true performs a planned drain without invalidating existing claims. X429_SERVICE_DISABLED=true blocks existing credentials and origin forwarding while retaining authenticated payment maintenance. Its sole client-path exception validates and binds an exact submission already carrying PAYMENT-SIGNATURE, durably rejects it before facilitator I/O, and returns matching x429.payment.rejected; malformed or response-lost attempts remain ambiguous. Both states publish through health/discovery and force discovery to no-store.

Requests	Current behavior
`GET /v1/infer?model=small` and `?model=large`	Use the named pool selected for `/v1/infer`; the exact query is still signed.
`GET /v1/infer` and `HEAD /v1/infer`	Share the selected pool's finite capacity while retaining method-specific credentials.
Different plan or hardware pools	Map their explicit application paths to distinct pool names. Never derive a pool name from an untrusted query, tenant, or header.

Upstream verifier

Use the private @x429/origin workspace to verify the assertion envelope against the expected issuer identity, upstream audience, and the dedicated X429_ORIGIN_KEY_ID/X429_ORIGIN_PUBLIC_KEY. Never pin the client-facing protocol issuer key for this boundary. The verifier also checks method, exact target, lane, receipt hash, timing, and nonce. Its required consumeNonce callback must be durable and atomic; process the application request only after it succeeds.

Production notes

Keep the separate protocol-issuer and origin-assertion signing keys out of source control.
Give clients explicit issuer, audience, key-id, and public-key trust pins; do not trust discovery by location alone.
Keep the upstream private and reject missing, invalid, expired, or replayed origin assertions.
List every custom authentication, tenant, model, or cost-bearing application header in X429_BOUND_HEADERS. Authorization, cookie, and x-api-key are always bound; discovery publishes the canonical list used by clients.
List only intended application paths in X429_ROUTE_POOLS. Staging and production forbid a global /* pool, and unmatched paths fail 404.
Use conservative capacity and paid-slot settings until admission math is measured under real load.
For exact mode, configure two independently administered RPC providers on different HTTPS hostnames, X429_SETTLEMENT_SECURITY_LEVEL=safe, minimum depth within the agreed boundary, bounded timeout/poll/attempt settings, and a dedicated reconciliation token. The runtime rejects identical hostnames but cannot prove provider independence. Facilitator success issues no permit until both providers agree on the Base safe boundary block number and hash plus the exact receipt/events. Base safe typically takes about two minutes and is not irreversible.
Use the explicit exact schedule: configured payment timeout + chain-observation timeout + settlement grace + fixed 2,000ms permit-delivery lead after close. Deployed exact configuration requires at least 180,000ms of observation; the launch templates use 20 seconds + 240,000ms with 60,000ms polls and four attempts + 10 seconds + 2 seconds before interval rounding.
Make X429_MAX_FUTURE_WINDOWS * interval at least one interval + auction epoch + payment timeout + confirmation timeout + settlement grace + 2,000ms. Config/preflight reject a shorter exact horizon; runtime returns auction_horizon_full when all eligible paid targets inside it are occupied.
When a confirmed payment misses its original slot, recovery must occupy one unused future paid slot outside auction targets and rotate the permit nonce. A full horizon fails closed; it never creates capacity.
Expose metrics for tickets, awards, payment intent states, reconciliation, execution leases, and rejected assertions.
Log verification failures without leaking full ticket payloads.
Define response-delivery/refund terms: protected-origin dispatch irrevocably consumes a credential. The signed receipt proves consumption, not application success or body delivery.

Metrics to expose

Metric	Type	Why it matters
`x429_capacity_admitted_total`	Counter	Requests admitted without a ticket.
`x429_tickets_issued_total`	Counter	How often the resource is saturated.
`x429_tickets_redeemed_total`	Counter	Completed ticket redemptions after overload.
`x429_ticket_rejections_total`	Counter by reason	Signature, scope, binding, expiry, replay, early window.
`x429_redemption_lag_ms`	Histogram	Distance between offered `notBefore` and actual admission.
`x429_paid_priority_total`	Counter	How often priority was used and admitted.
`x429_payment_reconciliation_total`	Counter by resolution	Unknown settlement outcomes that required operator evidence.
`x429_payment_resume_total`	Counter by outcome	Confirmed payment recoveries, pending resumes, capacity reschedules, and recovery-horizon failures.
`x429_auction_horizon_full_total`	Counter	Paid demand/collisions exhausted every safe target inside the configured bound.
`x429_origin_assertion_rejections_total`	Counter by reason	Bypass, expiry, target mismatch, and replay attempts at the upstream.

Release checklist

/.well-known/x429.json returns the active issuer key.
/healthz reports a successful origin-key signing round trip, and its originAssertionKey exactly matches the key pinned at the protected origin.
Retry-After matches the free ticket wait.
Tickets are Cache-Control: no-store.
Nonce storage survives concurrent redemption attempts.
Origin assertion nonces are consumed once in durable upstream storage.
Indeterminate exact settlement cannot issue a permit and the reconciliation runbook succeeds against dual-RPC evidence.
Facilitator success remains non-authoritative until automatic dual-RPC Base-safe proof succeeds; insufficient depth within the agreed boundary, timeout, disagreement, and RPC-outage fixtures leave both ledgers indeterminate with no permit. Automatic proof is capped at four attempts and 40 RPC requests.
Post-signature transport/5xx/malformed responses stop with persisted recovery state, except for one identical-authorization retry of explicit confirmation-persistence-pending; confirmed reconciliation resumes without a second authorization.
Late confirmation reschedules into unused paid capacity, rotates the permit nonce, and fails closed when the configured horizon is full.
Origin handlers still enforce authentication and authorization. x429 is admission control, not auth.
Any timeout, transport error, body-stream failure, or client-delivery loss after dispatch neither replays admission nor silently refunds payment.

The repository has controlled exact-settlement tests, not a funded public-chain proof or an independent audit. Keep those as explicit production gates.