Tollgate

Quota admission and usage accounting for latency-critical services, with no I/O on the request path.

A metered API has to answer "may this caller do this, and what does it cost?" on every request, and record the answer for billing. The usual answers put a database or a shared counter on the request path, which costs orders of magnitude more than the work it guards when that work takes nanoseconds or microseconds. Rate limiters remove the round trip but don't bill anything.

Tollgate splits the problem into two planes:

• The request path admits against an immutable compiled snapshot of the account and debits a fenced quota lease through local atomic counters. It performs no I/O, takes no blocking locks, and reads no clock for a policy decision.
• The control plane does everything slow in the background: it allocates leases from a central balance, distributes snapshots and revocations, and ingests idempotent, batched usage events as the billing record.

The core is domain-agnostic. It knows cost units, operations by index and permission bits, never plan names, product currencies or SQL.

What you get

• Admission in one call chain: snapshot lookup, status and permission checks, a direct-indexed cost quote, weighted rate limiting, concurrency limits, and a lease debit that opens a pending charge.
• Fast lane: reserve execution capacity for priority customers, protected from best-effort traffic saturation. Assured traffic can use shared capacity plus its protected reserve.
• Charging at execution start: success, failure and timeout are all charged, and cancelling before execution releases the debit for zero units. A committed charge is recorded even across a panic.
• Strict or elastic enforcement: a strict account never spends past its allocation. An elastic account may run past an unfunded lease, and every unit it does is recorded as overage.
• Budgets and periods: allowances roll per period, with expired units accounted for rather than lost.
• Credentials: HMAC API keys with digests at rest, session-scoped caching, and bounded revocation windows.
• Backends: an in-memory store that is the executable specification, and a PostgreSQL store that passes the same scenario suite by name.
• A control-plane server over rustls with mTLS, rotating bearer tokens or Google service-account identity, disjoint instance, operator and scoped self-service provisioner roles, and an audit trail for every administrative change and refusal.

Guarantees, and how they're checked

Tollgate is built so that its claims are checked, not asserted:

• 41 numbered invariants form the testable contract. Each one names the tests that enforce it, and CI fails if a named witness stops existing.
• Fail closed: unknown, stale, exhausted or backpressured states deny with zero units charged. There is no slower fallback path to fail open into.
• Exact conservation: every backend's suite asserts, per account, deposited + overage_recorded == balance + active grants + settled usage + settlement loss + expired.
• Machine-checked proofs: 24 Lean 4 modules with 369 theorems, and no sorry or axioms, model a request's charge lifecycle, lease timing and fencing, idempotent ingest, sharded counters, snapshot revocation, conservation and more. CI checks them on every pull request.
• Mutation testing: every pull request is mutation-tested, so a test that doesn't bite fails the build.
• Measured performance: hot-path benchmarks and allocation counts are gated. In September 2026, full admission measured about 134 ns on an Apple M1 Pro, cached credential authentication about 38 ns, and HMAC verification on a cache miss about 800 ns. Those are host-specific microbenchmarks, not end-to-end HTTP latency; the performance workflow records the workloads and their limits.

Install

The library crates release together at one version. Depend on the ones you need, at the same version:

[dependencies]
tollgate-core = "0.30"
tollgate-admission = "0.30"
# The managed runtime: snapshot distribution, lease renewal, usage batching.
tollgate-client = "0.30"

A request, end to end

begin looks the caller up and pins its snapshot, admit quotes the operation and debits the lease, commit charges at execution start, and dropping the committed guard records the billing event. In a service, the snapshot and lease below arrive from the control plane.

#![allow(unused)]
fn main() {
use std::sync::{Arc, Mutex};

use jiff::Timestamp;
use tollgate_admission::{
    AdmissionEngine, ArcSwapSnapshotMap, LeaseSlot, NoGate, Principal, SnapshotMap,
};
use tollgate_core::{
    AccountId, AccountSnapshot, AccountStatus, CostTable, CostUnits, FencingToken, Generation,
    LeaseGrant, LeaseId, LocalLease, OpIndex, PermissionBits, PublishableSnapshot, RequestId,
    ResolvedLimits, UsageEvent, UsageSlot,
};

/// The one operation this API meters.
struct Price;

impl OpIndex for Price {
    fn index(&self) -> usize {
        0
    }
}

/// Where committed charges go. In a service, a permit from the usage writer.
struct Billing(Arc<Mutex<Vec<UsageEvent>>>);

impl UsageSlot for Billing {
    fn record(self, event: UsageEvent) {
        self.0.lock().unwrap().push(event);
    }
}

let now = Timestamp::from_second(1_755_600_000).unwrap();
let expires = Timestamp::from_second(1_755_600_060).unwrap();

// From the control plane: the account's compiled snapshot (1 unit per
// request plus 2 per priced item) and a 1,000-unit lease.
let costs = CostTable::builder(CostUnits(1), CostUnits(1))
    .weight(&Price, CostUnits(2))
    .build();
let snapshot = AccountSnapshot::builder(
    AccountId(1),
    Generation(1),
    AccountStatus::Active,
    expires,
    PermissionBits::bit(0),
    ResolvedLimits::new(64),
    Arc::new(costs),
)
.build();
let lease = LocalLease::new(
    LeaseGrant {
        lease_id: LeaseId(1),
        account_id: AccountId(1),
        fencing_token: FencingToken(1),
        units: CostUnits(1_000),
        expires_at: expires,
    },
    CostUnits(100),
);

let engine = AdmissionEngine::new(ArcSwapSnapshotMap::new());
let slot = LeaseSlot::for_account(AccountId(1));
drop(slot.replace(Arc::new(lease)));
engine
    .map()
    .install_publishable(
        Principal(42),
        PublishableSnapshot::try_new(Arc::new(snapshot)).expect("valid snapshot"),
        slot,
    )
    .expect("installed");

// The request path: no I/O from here on.
let billed = Arc::new(Mutex::new(Vec::new()));
let committed = engine
    .begin(Principal(42), PermissionBits::bit(0), now)
    .expect("known, active, permitted caller")
    .admit(&[(Price, 3)], Billing(Arc::clone(&billed)), now)
    .expect("within limits and funded")
    .acquire_capacity(&NoGate)
    .expect("no capacity gate configured")
    .commit(RequestId(1), now)
    .map_err(|(error, _released)| error)
    .expect("inside the lease window");

// ... do the work ...
drop(committed);

assert_eq!(billed.lock().unwrap()[0].units, CostUnits(7)); // 1 + 2 × 3
}

Embedding Tollgate gives the supported request order, what you implement, what is sealed, and how to shut down without losing usage.

Beyond the request path

• InstanceRuntime (in tollgate-client) supervises accounts dynamically: it distributes snapshots, acquires and renews leases, batches usage, reports continuous readiness, and shuts down within a bound.
• HTTP-backed services authenticate customer keys through a read-only KeySource, with a KeyManager beside the runtime whose verifier bounds cached evidence by feed freshness and each key's expiry. See credential projection.
• Direct-store services with budget schedules run a PeriodRoller, which funds schedules at startup and rolls due periods in bounded batches. See its lifecycle example. With HttpStore, the server does period maintenance instead.
• Batch rejection, PostgreSQL limits and recovery are covered in usage accounting, and generation refusals in snapshot operations.

Try the example service

examples/pricing-api is a complete metered API with HMAC-verified keys, admission, commit at execution start, and billing:

cargo run -p pricing-api --bin pricing-api
curl -s -H 'Authorization: Bearer demo-key-1' -H 'Content-Type: application/json' \
     -d '{"contracts":[{"spot":100,"strike":105,"rate":0.05,"vol":0.2,"tte_years":0.25}]}' \
     http://127.0.0.1:8081/v1/price
curl -s http://127.0.0.1:8081/metrics   # what it admitted and refused, by reason

Set TOLLGATE_LOCAL_SHARDS=8 only after profiling sustained same-account contention across cores; instance-local sharding explains how to size it. The control-plane server starts with TOLLGATE_SECURITY_CONFIG=/path/to/security.json cargo run -p tollgate-server once identities and TLS are configured, and refuses remote plaintext and anonymous calls.

Every binary answers --help and --version before reading any configuration. pricing-api and tollgate-server take no positional arguments, and exit with status 2 on any they are given.

Documentation

The documentation site is at https://morphiq-labs.github.io/tollgate/, and the API reference is on docs.rs.

• Using Tollgate: embedding, account administration, usage accounting, snapshot operations, lease timing, lease ownership, local sharding, and credential projection.
• Operating it: the control-plane security runbook covers TLS, service identity, credential rotation and audit collection. Signals, what normal looks like, and the ledger reconciliation query are in Observability.
• Why it's built this way: the design record, and the technique disclosures, published as prior art with no patent claims.

Status

Tollgate is pre-1.0. A breaking change moves the minor version, so a caret requirement ("0.30") never crosses one; the changelog marks every break. The minimum supported Rust version is 1.89, and CI checks it on every pull request.

Contributing

See CONTRIBUTING.md for setup, the local gates and the pull-request process. AGENTS.md is the full engineering contract. Report security issues privately; see SECURITY.md. Participation is governed by the code of conduct.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tollgate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Tollgate is a product of MorphIQ Labs, a trade name of Prophetizo LLC. cargo deny --locked check licenses gates every dependency against deny.toml, which admits only permissive licenses.

Getting started

This tutorial builds a metered service's admission layer end to end, in one process: it provisions an account, starts the runtime that keeps an instance supplied, serves a request, watches two refusals, and shuts down with the ledger balanced.

It runs the control plane in-process with MemoryStore, the reference backend, so there is nothing to deploy. In production the same runtime talks to PostgreSQL directly or to a tollgate-server over TLS; nothing on the request path changes.

The whole program is crates/tollgate-client/tests/getting_started.rs. Every excerpt below is copied from it, and a repository check fails if they drift apart. To run it:

cargo test -p tollgate-client --test getting_started

Concepts defines the terms used here.

Dependencies

[dependencies]
tollgate-core = "0.30"
tollgate-admission = "0.30"
tollgate-client = "0.30"
tollgate-store = "0.30"
jiff = "0.2"
tokio = { version = "1", features = ["macros", "rt-multi-thread", "time"] }

Tollgate takes timestamps as arguments and never reads a clock on the request path, so jiff appears in its API. The runtime's background tasks run on Tokio.

1. Describe what you meter

Operations are dense indices into a cost table, and permissions are bits. The names are yours; Tollgate only sees the numbers.

#![allow(unused)]
fn main() {
/// The operations the service meters, as dense indices into a cost table.
#[derive(Clone, Copy)]
enum Op {
    Quote,
    Report,
}

impl OpIndex for Op {
    fn index(&self) -> usize {
        *self as usize
    }
}

/// What a caller needs to be allowed to call the service at all.
const CALL: PermissionBits = PermissionBits::bit(0);
/// A permission this caller's plan does not include.
const EXPORT: PermissionBits = PermissionBits::bit(1);
}

2. Provision an account

This is control-plane work, done once per account and once per policy change, never per request. The account gets a deposit of 10,000 units. The plan is compiled into an immutable snapshot, with its cost table, permissions and limits, and published under the caller's principal: the stable identity a verified credential resolves to.

#![allow(unused)]
fn main() {
let store = MemoryStore::new(GrantPolicy::default()).expect("default grant policy is valid");
let clock: Arc<dyn Clock> = Arc::new(SystemClock);

let account = AccountId(1);
store.create_account(AccountConfig {
    account_id: account,
    initial_balance: CostUnits(10_000),
    status: AccountStatus::Active,
    capacity_class: CapacityClass::Assured,
});

// The plan, compiled once per policy change and never per request:
// 5 units per request, plus 1 per quote and 20 per report.
let costs = CostTable::builder(CostUnits(5), CostUnits(5))
    .weight(&Op::Quote, CostUnits(1))
    .weight(&Op::Report, CostUnits(20))
    .build();
let valid_until = clock
    .now()
    .checked_add(SignedDuration::from_hours(1))
    .expect("an hour from now is a valid timestamp");
let snapshot = AccountSnapshot::builder(
    account,
    Generation(1),
    AccountStatus::Active,
    valid_until,
    CALL,
    ResolvedLimits::new(64),
    Arc::new(costs),
)
.build();

// The caller's credential resolves to this principal.
let caller = Principal(42);
store
    .publish_snapshot(
        caller,
        PublishableSnapshot::try_new(Arc::new(snapshot)).expect("a consistent snapshot"),
    )
    .expect("the account exists");
}

3. Start the runtime

InstanceRuntime runs everything slow in the background: it loads and refreshes snapshots, keeps a lease of units in hand for each account it serves, and batches usage events to the store. Every field of its configuration is a decision about your deployment, so it has no defaults; the values here are reasonable for a small service.

#![allow(unused)]
fn main() {
let config = InstanceRuntimeConfig {
    snapshots: SnapshotManagerConfig {
        // Serve every principal the store knows about.
        principals: TrackedPrincipals::All { seed: vec![caller] },
        refresh_interval: Duration::from_secs(30),
        unknown_ttl: SignedDuration::from_secs(60),
        revoked_ttl: SignedDuration::from_hours(1),
        retry_backoff: Duration::from_millis(200),
        max_concurrent_fetches: 16,
        fetch_timeout: Duration::from_secs(5),
        enumeration_timeout: Duration::from_secs(30),
    },
    leases: AccountLeaseConfig {
        // Draw 1,000 units at a time; refill below 100.
        target_grant: CostUnits(1_000),
        low_water: CostUnits(100),
        lease_ttl: SignedDuration::from_secs(60),
        expiry_safety_margin: SignedDuration::from_secs(2),
        poll_interval: Duration::from_millis(20),
        store_call_timeout: Duration::from_secs(5),
        shutdown_release_deadline: Duration::from_secs(5),
    },
    usage: UsageWriterConfig {
        queue_capacity: 4_096,
        max_batch: 256,
        flush_interval: Duration::from_millis(25),
        retry_backoff: Duration::from_millis(50),
        shutdown_drain_deadline: Duration::from_secs(5),
        ingest_timeout: Duration::from_secs(5),
    },
    sharding: LocalSharding::SINGLE,
    snapshot_history_capacity:
        tollgate_admission::ArcSwapSnapshotMap::DEFAULT_GENERATION_CAPACITY,
    idle_account_linger: Duration::from_secs(1),
    manager_restart_backoff: Duration::from_millis(200),
    shutdown_deadline: Duration::from_secs(15),
};

// One store plays all three control-plane roles here: the snapshot
// source, the lease allocator, and the usage sink.
let (runtime, handle) = InstanceRuntime::spawn(
    store.clone(),
    store.clone(),
    store.clone(),
    Arc::clone(&clock),
    config,
)
.expect("a valid runtime configuration");

// Ready means: snapshots loaded, a lease in hand, and usage accounting up.
while !handle.readiness(clock.now()).is_ready() {
    tokio::time::sleep(Duration::from_millis(10)).await;
}
}

The runtime is ready once it has a snapshot, a usable lease and a healthy usage writer. Serve readiness from handle.readiness(now), so a load balancer sends no traffic to an instance that would refuse it.

4. Serve a request

This is the request path. It performs no I/O: every call below reads local state that the runtime keeps current.

#![allow(unused)]
fn main() {
let now = clock.now();
// 1. Authenticate (not shown), then `begin`: one snapshot lookup and the
//    route's permission check. Everything after reads this generation.
let context = handle
    .begin(caller, CALL, now)
    .expect("a known, active caller with the permission");
// 2. Reserve room for the billing event before reading the request body,
//    so a full usage queue sheds load before any work is done.
let slot = handle
    .recorder()
    .try_reserve()
    .expect("the usage queue has room");
// 3. Quote the workload and debit the local lease: three quotes and one
//    report cost 5 + 3 × 1 + 1 × 20 = 28 units.
let pending = context
    .admit(&[(Op::Quote, 3), (Op::Report, 1)], slot, now)
    .expect("within limits and funded");
// 4. Commit when execution actually starts.
let committed = pending
    .acquire_capacity(&NoGate)
    .expect("no capacity gate configured")
    .commit(RequestId(1), clock.now())
    .map_err(|(error, _released)| error)
    .expect("the lease is still usable");

// ... do the work ...

// 5. Dropping the guard records the charge, on every exit path.
drop(committed);
}

The order is the contract; Embedding Tollgate says what each position buys. Cancelling at any point before commit releases the debit and charges nothing. Once committed, the request is charged whether the work succeeds, fails or times out, because the resources were spent either way.

5. Refusals charge nothing

Tollgate fails closed: an unknown caller, a missing permission, a stale snapshot, an exhausted lease or a full usage queue all deny, with zero units charged and a DenyReason that says which.

#![allow(unused)]
fn main() {
// A permission the plan does not include: denied, and nothing is charged.
let refused = handle.begin(caller, EXPORT, clock.now());
assert!(matches!(refused, Err(DenyReason::MissingPermission)));

// A caller the control plane never published.
let stranger = handle.begin(Principal(7), CALL, clock.now());
assert!(matches!(stranger, Err(DenyReason::UnknownPrincipal)));
}

Each DenyReason carries retry advice, and the example service maps them to HTTP statuses in examples/pricing-api.

6. Shut down and check the ledger

Shutdown order matters: usage must land while its lease is still live. Stop your listener first, then let the runtime drain in-flight work, flush usage and release leases under one deadline.

#![allow(unused)]
fn main() {
// Stop accepting requests first (your listener), then drain: the runtime
// flushes usage while leases are still live, then releases them.
let report = runtime.shutdown().await.expect("the runtime task finished");
assert!(!report.deadline_expired);
assert_eq!(report.usage.expect("usage drained").accepted, 1);

// The ledger: one request billed 28 units, the released lease returned
// the rest, and every unit deposited is accounted for.
assert_eq!(store.usage_recorded(account), CostUnits(28));
assert_eq!(store.balance(account), CostUnits(9_972));
let ledger = store.conservation(account).expect("the account exists");
assert_eq!(ledger.deposited, CostUnits(10_000));
assert_eq!(ledger.settled_usage, CostUnits(28));
assert_eq!(ledger.active_lease_grants, CostUnits::ZERO);
}

The released lease returned its unspent units, so the balance is the deposit less exactly what was billed. Every backend's test suite asserts this conservation equation, per account, at every step.

Where next

• Concepts: the model behind each step.
• Embedding Tollgate: the full request contract, what you implement, adopting in stages, and shutdown.
• Account administration: provisioning accounts, budgets and credentials over HTTP.
• Credential projection: authenticating customer keys in front of begin.
• examples/pricing-api: a complete HTTP service with authentication, admission, metrics and billing.

Concepts

Tollgate answers two questions for a metered service: may this caller do this, and what does it cost? on every request, and what did each account use? for billing. This page defines the terms the rest of the documentation uses. Getting started shows them working together.

Two planes

Everything Tollgate does belongs to one of two planes, and the line between them is the design.

• The request path decides admission. It reads only local, immutable or atomic state, so it performs no I/O, takes no blocking locks, and reads no clock for a policy decision: the caller passes now in. It lives in tollgate-core and tollgate-admission.
• The control plane does everything slow in background tasks: it distributes account state, allocates quota, and records usage. It is tollgate-client's runtime on each instance, plus a store backend and, optionally, tollgate-server.

The request path never waits for the control plane. When local state is missing, stale or exhausted, the request is refused, and the control plane catches up in the background.

Accounts, principals and permissions

An account is the unit that holds a balance and is billed. A principal is a stable identity that a verified credential resolves to; an account can have several (one per API key, say), and they share its funding.

Permissions are bits. A route declares the bits it requires, a snapshot carries the bits a principal holds, and begin checks one against the other. What each bit means is your product's decision.

Snapshots

An account snapshot is the compiled, immutable form of everything admission needs to know about a principal: the account's status, its permissions, its rate, concurrency and shape limits, its cost table, its enforcement mode, and how long the snapshot is valid. You compile it once per policy change, never per request, and the control plane distributes it to every instance.

Snapshots carry a generation. An instance never moves a principal back to an older generation, and a revocation is a durable, generation-ordered tombstone, so a delayed message cannot resurrect a revoked credential. A snapshot past its validity window is refused (SnapshotExpired) until a replacement arrives, so a partitioned instance stops admitting rather than serving stale policy; staleness never triggers an inline fetch. See snapshot operations.

Cost units and cost tables

A cost unit is Tollgate's only currency. Your product's credits, requests or compute units map onto it at compile time. Arithmetic on cost units is always checked; an overflow is a refusal, never a wrap.

A cost table prices a request's workload, a list of (operation, count) pairs: a fixed charge per request plus a weight per operation. You index operations densely, so a quote is O(1) in the size of the table and O(distinct operations) in the request.

Leases

A lease is a block of units that the control plane allocates to one instance from an account's central balance. The instance spends it locally with atomic counters, which is why admission needs no round trip. A lease is the answer to "how can many instances enforce one balance without coordinating per request?": units leave the balance when the lease is granted, so the instances together can never spend more than was allocated.

• A lease carries a fencing token. The store accepts usage and releases only when the token matches the lease record, so a stale holder cannot settle against a lease it no longer owns.
• A lease expires. It is usable only until expires_at minus a safety margin, and the store reclaims it only after expires_at plus a grace period, so an instance never spends a lease the store has already taken back. See lease timing.
• The runtime refills a lease when it falls below a low-water mark, and releases unspent units on graceful shutdown. A lease abandoned by a crash is forfeited after its grace period and recorded as settlement loss: executed work can never become spendable again.

A request's life

A request moves through typed stages, and each stage can only be reached from the one before it:

1. begin looks the principal up once, pins that snapshot generation for the rest of the request, and checks the route's permission.
2. Reserve a usage slot, room in the usage queue for this request's billing event, before reading the request body. If the queue is full, the request is shed before any work is done.
3. admit quotes the workload, takes rate and concurrency tokens, and debits the lease. The result is a pending reservation.
4. acquire_capacity applies the instance's execution-capacity policy, if one is configured.
5. commit, at the moment execution starts, turns the reservation into a charge. It can fail if the lease stopped being usable in the meantime.
6. Dropping the committed guard records the usage event into the slot reserved in step 2, on every exit path, including a panic that unwinds.

Cancelling at any stage before commit releases the debit and charges nothing. After commit, success, failure and timeout are all charged. The exact contract is in Embedding Tollgate.

Fast lane: reserved execution capacity

Tollgate's fast lane protects execution capacity for priority customers when best-effort traffic saturates an instance. Enable ExecutionCapacityMode::Reserved and classify priority accounts as Assured. An operator sets each account's capacity class through account administration.

• BestEffort requests can use only the shared pool.
• Assured requests try the shared pool first, then their protected reserve. Best-effort traffic cannot consume that reserve, even while it is idle.

For example, an instance with 100 capacity units and a 20-unit reserve allows best-effort work to occupy at most 80 units. Assured work can use the shared 80 plus the protected 20, subject to available capacity and request size.

The reserve is per instance and does not preempt running work or queue requests. An assured request is still refused if neither eligible pool has enough room, and the usual permission, rate, concurrency and funding rules still apply. The feature protects capacity under contention; it does not guarantee a fixed latency or that every priority request will succeed. See the design record for pool sizing and deployment details.

Refusals

Every refusal is a DenyReason with retry advice, and every refusal charges zero units. Tollgate fails closed: an unknown principal, a stale snapshot, a missing permission, an exceeded limit, an exhausted lease or a full usage queue all deny. There is no slower fallback path, because a fallback that reached the store would put I/O back on the request path.

Enforcement modes

A snapshot's enforcement mode decides the one question a lease can't answer by itself: what happens when the lease cannot fund the quote?

• Strict (the default) denies. An account never spends past what was allocated to it.
• Elastic admits past the lease, up to a per-instance overage cap, and records every unit it admits that way as overage, billed like any other usage.

Only funding is elastic. An unknown principal, a missing permission or a stale snapshot is refused under either mode.

Usage events and the ledger

A usage event is the billing record of one committed request: its request ID, the account, what funded it (a lease, or overage), the units charged, and when. Events are idempotent by request ID and are written to the store in batches, so a retried batch never bills twice. Usage events, not leases, are the billing truth: a lease bounds what an instance may spend, and the events record what it did. See usage accounting.

Every backend keeps a per-account ledger that must satisfy one equation exactly, at every step:

deposited + overage_recorded
    == balance + active grants + settled usage + settlement loss + expired

The in-memory store and the PostgreSQL store assert it in the same test suite.

Budgets and periods

An account can have a budget schedule: an allowance deposited at each period boundary, such as a monthly allowance that resets. When a period closes, unspent allowance is expired, not lost: it stays in the ledger as its own term. A direct-store service runs a PeriodRoller to apply schedules; with tollgate-server, the server does it. See account administration.

Readiness

An instance is ready when it has current snapshots, usable leases for the accounts it serves, and a healthy usage writer. Readiness is continuous, not a startup flag: an instance that loses its snapshots, its leases or its accounting becomes unready, so a load balancer can stop sending it traffic it would only refuse.

Topologies

The request path is the same in every deployment. What changes is where the control plane's store lives:

• In-process: MemoryStore, the reference implementation. For tests, examples and single-process tools.
• Direct store: each instance's runtime talks to PostgreSQL through tollgate-store-postgres.
• Via server: instances talk to tollgate-server over authenticated TLS with HttpStore, and only the server holds database credentials. See the control-plane security runbook.

Embedding Tollgate on a request path

For a service putting Tollgate's staged admission pipeline in front of its own work. It states the contract: the request order, what you implement, what you cannot, and how to shut down without losing usage.

It is not the rationale. docs/DESIGN.md § "Staged admission interface (GL-96)" says why the seam has this shape and is the document an interface change amends first. It is also not the provisioning API — creating accounts, setting budgets and issuing credentials is docs/ACCOUNT_ADMINISTRATION.md.

examples/pricing-api is the worked example. Read it alongside this; the last section says which of its choices are the contract and which are its own.

Depending on Tollgate

The crates are published to crates.io and release as one unit: every crate carries the same version, and they depend on each other at exactly that version, so Cargo resolves a consistent set. Depend on the same 0.x series for each:

[dependencies]
tollgate-core = "0.30"
tollgate-admission = "0.30"
# Only if you want the managed runtime — see "Two ways in" below.
tollgate-client = "0.30"

Under 0.x, a breaking change moves the minor version, so a caret requirement never crosses one. Pin the exact version your conformance run was recorded against ("=0.30.1"), and move it deliberately.

Two ways in

tollgate_admission::AdmissionEngine is the request path itself. You own snapshot publication, lease funding and usage export.

tollgate_client::InstanceRuntime owns those for you — snapshot distribution, lease acquisition and renewal, usage batching, readiness and shutdown — and hands back a RuntimeHandle whose begin delegates straight to the engine. This is what the example uses and what most services want.

Everything below is identical either way: RuntimeHandle::begin and AdmissionEngine::begin have the same signature and return the same RequestContext.

The supported request order

This is the contract, from docs/DESIGN.md:

The supported request order is authenticate, begin, reserve the usage slot, read/decode under ctx.limits(), then call ctx.admit.

Each position earns its place, and reordering them loses something specific:

1. Authenticate from bounded transport metadata — a header, not a body.
2. begin resolves the account snapshot once and checks the route permission. Everything downstream reads that one pinned generation, so a snapshot refresh mid-request cannot change the answer under you.
3. Reserve the usage slot. After begin, so an unknown or unauthorized credential never occupies the usage queue. Before the body, so backpressure sheds before expensive input work.
4. Read and decode under ctx.limits(). A body-read failure drops the context and the slot and creates no funding reservation.
5. admit with the compiled workload. This is the stage that can create pending funding — everything before it is free to fail.

Then acquire_capacity, commit at the moment execution actually starts, and drop the Committed guard when the work is done.

The stages

#![allow(unused)]
fn main() {
// 2. begin — one snapshot lookup plus the route permission.
pub fn begin(&self, principal: Principal, required: PermissionBits, now: Timestamp)
    -> Result<RequestContext, DenyReason>;

// 5. admit — shape, rate, concurrency and funding.
pub fn admit<O: OpIndex, S: UsageSlot>(self, workload: &[(O, u64)], slot: S, now: Timestamp)
    -> Result<Pending<S>, DenyReason>;

// 6. capacity — a startup-selected policy, not caller input.
pub fn acquire_capacity<G: CapacityGate>(self, gate: &G)
    -> Result<ReadyToStart<S, G::Permit>, (DenyReason, Released)>;

// 7. commit — at actual execution start, not at admission.
pub fn commit(self, request_id: RequestId, now: Timestamp)
    -> Result<Committed<S, P>, (CommitError, Released)>;
}

RequestContext is Send + Sync + 'static and cheap to hold, so it crosses the body-read await. It carries snapshot(), limits(), generation() and policy_revision() — read your effective limits from it rather than from anywhere else, because it is the generation this request was authorized under.

Commit can fail. CommitError at execution start means funding lapsed between reserving and starting. The Result is what forces the executor to check before running the kernel; the #[must_use] on commit is deliberate.

The workload is borrowed. &[(O, u64)] — a stack array or your own fixed-capacity buffer. Tollgate owns no Vec, box, hash table, string or product identifier, and quoting is O(distinct classes), not O(policy records).

Dropping Committed is what bills. The usage event is emitted from Drop, so the guard must live exactly as long as the work. cancel() before commit releases everything and charges nothing.

What you implement

OpIndex — dense indices for your operation classes.

#![allow(unused)]
fn main() {
impl OpIndex for Op {
    fn index(&self) -> usize { *self as usize }
}
}

UsageSlot — pre-reserved capacity for exactly one event.

#![allow(unused)]
fn main() {
pub trait UsageSlot: Send + 'static {
    fn record(self, event: UsageEvent);
}
}

record must not perform fallible I/O. Obtaining the slot is the backpressure decision; consuming it is the committed-charge path, and it runs from Drop. Take tollgate_client::UsagePermit from the runtime's recorder unless you have a reason not to.

Authentication — verify before the body. tollgate_auth::CredentialVerifier is the scheme seam and HmacRegistry the implementation in the box. Strip any transport prefix before the library sees the bytes, so what you cache and what you verify are the same bytes by construction.

A panic boundary around your kernel. Tollgate's guard is drop-safe and allocation-free, but a panic that escapes a worker thread can leak the guard rather than drop it, and a leaked guard emits nothing. catch_unwind (or your executor's equivalent) is yours to place. Under panic = "abort" this does not apply, and INVARIANTS GL-13 states the process-loss boundary instead.

Shutdown ordering — see below.

What you cannot implement

CapacityGate and CapacityPermit are sealed. An application's own compute permit is not a Tollgate capacity decision, and a type outside the crate satisfying the permit would be a way to start work the gate refused. Choose a policy at startup: NoGate (zero-sized, disabled) or ExecutionCapacityGate with Uniform or Reserved.

Your own compute admission stays yours and stays separate. Weights you use to schedule work are not cost units.

Adopting in stages

You do not have to wire everything at once. Two zero-cost stand-ins exist for exactly this, and both are honest about being stand-ins:

• NoGate — admission without execution-capacity limiting.
• DiscardedUsageSlot — admission without usage export. It counts what it discarded, deliberately: a silently dropping slot makes "usage is not wired up" indistinguishable from "no usage happened", and one of those means you are admitting billable work and losing the record. Not for production billing.

Shutting down

One safe order, because usage events must land while their lease is still live:

1. Stop admitting — stop your listener first.
2. Quiesce request tasks still holding permits or Committed guards, bounded by the deadline the runtime returns.
3. Await the usage writer's shutdown; it refuses new reservations, drains outstanding permits, and reports anything unresolved.
4. Only then release leases.

InstanceRuntime does steps 2–4 under one deadline. Step 1 is yours, and so is bounding your own tasks by the deadline it gives back.

What is contract, and what is pricing-api's own choice

Contract:

• the request order, and every signature above;
• reading limits from the pinned context;
• commit at execution start, and checking its Result;
• the Committed guard living as long as the work;
• the shutdown order.

pricing-api's own choices, which you should not copy without deciding:

• Doing admission inside an Axum FromRequest extractor. It is a tidy place to enforce "before the body" in that framework, and nothing requires it.
• MemoryStore in-process. Pointing the same stack at a tollgate-server is a swap to HttpStore.
• NoGate by default, with the capacity gate behind configuration.
• A per-connection credential cache. Sound for long-lived connections; irrelevant if yours are short.
• Its error mapping. RFC-7807 shapes and which DenyReason becomes which status are product decisions.

Keeping an account on one core

Admission writes a handful of per-account cache lines — the rate bucket, the concurrency gauges, the lease counter, and the reference counts of the account state and lease — and each is fast only while it stays in the cache of the core that last wrote it. A work-stealing runtime moves a connection's task between worker threads, so an account's next request often runs on a different core and pulls every one of those lines across first.

On the controlled host, eight threads admitting for eight distinct accounts cost about 115 ns per admission when each account stays on one thread and about 1 µs when the threads cycle through the accounts (admission/full_check_contended_8_distinct_accounts and its _rotating twin). In the example service at ten connections the in-handler admit grew from about 200 ns to about 500 ns for this reason alone (GL-138). Nothing in the library is shared between those accounts; the cost is the account's own lines moving.

The library does not choose where your tasks run, so this is yours to decide. It matters when admission is a meaningful share of your request cost:

• A thread-per-core runtime — one single-threaded runtime per core, each accepting its own connections (for example through SO_REUSEPORT) — keeps a connection's requests on one core for its whole life.
• Connection affinity keeps an account's traffic on few connections, so its requests land on few cores. Many connections for one account spread it back out whatever the runtime does.
• A default multi-threaded runtime is correct and usually fine; it pays this migration on some fraction of requests, which is what the example measures.

Related

• docs/DESIGN.md § "Staged admission interface (GL-96)" — the rationale, and the document an interface change amends first.
• docs/ACCOUNT_ADMINISTRATION.md — provisioning accounts, budgets and credentials over HTTP, with a conformance list for that surface.
• docs/CREDENTIAL_PROJECTION.md — authenticating customer keys in an HTTP-backed deployment.
• docs/USAGE_ACCOUNTING.md — what happens to the events you emit.
• docs/DESIGN.md § "Instance-local admission sharding (GL-3)" — the opt-in layout, once same-account contention warrants it. It is off by default and costs nothing until you enable it.
• INVARIANTS.md — the testable contract. Three of them are reachable from outside, which is why they appear above: GL-8 accounting backpressure sheds (why the slot is reserved before the body), GL-12 no commit outside the usability window (why leases are released last), and GL-13 a committed charge is always emitted (whose process-loss boundary is what your panic boundary keeps you inside).

Funding refusal and retry advice

Two reasons say the account itself cannot fund a request. Both are Retry::Never under the current funding, both charge nothing, and both are reached only after local lease credit and any elastic fallback have failed:

• DenyReason::BalanceExhausted: the allocator confirmed that no account funding remains, including units held in leases. Callers need a top-up, a changed funding policy, or the next budget period.
• DenyReason::BalanceInsufficient { remaining }: the account still has remaining units of funding, counting units held in leases, and this request's quote is larger. Retrying this quote needs new funding or the next period; a request that quotes at most remaining may still succeed.

The pricing example returns HTTP 402 with balance-exhausted or balance-insufficient for these, and 429/503 for the lease refusals. A service that exposes a reset time can use the budget period end.

remaining is an upper bound on what the account can spend, never an estimate to show as a balance: unreported usage can only lower it. A quote within it is not a promise of admission. Such a quote keeps the lease refusal's transient advice (LeaseUnavailable, LeaseExpired, LeaseExhausted), because funds held by another instance can return when that instance releases its lease. Usage is batched, so evidence can lag consumption until billing has recorded it and the background manager has talked to the allocator again. Do not turn an estimated remaining balance or a snapshot's old budget view into a funding refusal.

Evidence comes from the allocator in two ways. Every grant carries the ledger's remaining funding as of the transaction that made it. A refusal with nothing allocatable carries it as AllocateError::BalanceExhausted (zero remaining) or AllocateError::BalanceInsufficient (held in other leases). InsufficientBalance remains the refusal that attests nothing. A consolidation whose rolled-back settlement would have recorded loss or expired allowance returns it. So do custom allocators that cannot establish the ledger fact.

Evidence is shared by all principals and localities of an account. A new grant replaces it with that grant's own evidence. Accepted snapshots clear it when the budget view or enforcement mode changes. So does a grant whose allocator call overlapped such a change. Snapshot maps order generations separately for each principal: an accepted change clears account evidence even if its generation is below another principal's. Rejected replays and unchanged funding do not clear it. A stored period end expires the evidence using caller-supplied admission time, even if the allocator response arrives after rollover. Unscheduled balances retain evidence until a funding observation replaces or invalidates it. Top-ups propagate through the normal grant and snapshot loops, not synchronously. A funding refusal still rings the lease's refill doorbell, so the next consolidation carries fresh evidence. Refundable pending elastic reservations and an in-flight overage commit retain their transient and AfterInFlight advice, because they can recover without new funding.

Contract changes (GL-130)

• LeaseAllocator::acquire and consolidate return tollgate_store::Allocation { grant, funding } instead of a bare LeaseGrant. funding: None means the allocator attested nothing. Custom allocators may return None until they can read committed ledger state inside the grant's own transaction.
• New enum variants: AllocateError::BalanceInsufficient(BalanceShortfall) and DenyReason::BalanceInsufficient { remaining }. Exhaustive matches need them.
• Dense counters append balance_insufficient: deny slot 23 and allocator slot 10. Existing slots do not move.
• FundingAttempt::exhausted is now shortfall, and there is a new granted. LeaseSlot::balance_exhausted is now funding_evidence, which returns the evidenced remaining.
• Problem and ApiError gain an optional balance_shortfall field, so Rust struct literals need it.

The wire change is backward compatible in both directions and needs no ordering or migration:

• Grant responses flatten the grant and add an optional funding object. Old clients ignore it; old servers omit it, and new clients then have no evidence.
• A confirmed shortfall keeps the insufficient-balance code and adds a balance_shortfall extension, whose period_end is required and may be null. Old clients read the unattested refusal they always did.
• New clients discard malformed or zero-remaining extensions, and grant evidence below the grant's own units, rather than letting them refuse fundable quotes.

The exhaustion code from GL-128, balance-exhausted, still wants clients updated before servers: a client older than that code reads it as an unknown storage error.

Local evidence publication uses a mutex only in the control plane. Admission reads one atomic word on a stable funding refusal when no evidence is live. Live evidence is read as a seqlock, four more loads, with no allocation, lock, I/O or clock read.

Grant sizing and large quotes

GrantPolicy halves grants near exhaustion by default (shrink_divisor = 2), so one instance cannot hoard a small balance ahead of demand. A quote larger than a lease the policy would grant is still reachable. The lease records the largest quote it refused for want of units. The refill plane consolidates the lease, and the allocator grows the replacement to that quote when the account's restored balance can fund it. The first such request is refused with transient LeaseExhausted advice, and a retry after the consolidation is funded. Growth is at most one refused quote. A quote the account cannot fund does not grow the grant; GL-130's evidence answers it instead.

Consolidation is the safety net, not the steady state. A rising consolidated count means target_grant is undersized against the largest quote the service prices.

Contract changes (GL-131)

• LeaseAllocator::consolidate takes needed: CostUnits after requested: the largest quote the returned lease refused. Custom allocators should size with GrantPolicy::consolidation_grant; passing zero keeps the earlier sizing.
• LocalLease::largest_refused_quote exposes the recorded demand, which is exact at quiescence.
• ConsolidateRequest gains an optional needed field, omitted when zero. Old servers ignore it and keep the earlier sizing; old clients omit it. No rollout order or migration is needed.

Crashes and forfeited leases

Only a release returns a lease's unspent units. An instance that dies without a graceful shutdown (SIGKILL, host loss, OOM, preemption without drain) never releases. Its committed-but-unflushed usage also dies with it, so nobody can prove any of its units unspent. After expires_at + reclaim_grace, server maintenance sweeps such a lease and forfeits its whole unaccounted remainder as settlement loss: nothing is credited back, and executed work cannot become spendable again (INVARIANTS.md GL-9, GL-136). The same applies to a lease a graceful shutdown abandoned because its release deadline lapsed.

• Cost: a hard kill forfeits the unspent remainder of every lease the instance held, parked ones included. Size target_grant and lease_ttl with that in mind: smaller, shorter grants forfeit less and rotate more.
• Late usage is still billed. An instance that outlives a control-plane outage past its lease's grace flushes its backlog afterwards, and those events bill against the forfeit instead of being rejected. Usage beyond what was forfeited is rejected and reported.
• Graceful drain matters. InstanceRuntime::shutdown releases every quiesced lease, which returns its units. Give shutdown_release_deadline enough room for your control plane.

Contract changes (GL-136)

• ReclaimedLease.reclaimed is renamed forfeited, in Rust and in the JSON that POST /v1/leases/reclaim returns, because its meaning changed: units recorded as loss, not units credited.
• The server's sweep event reports forfeited_units (was units, or reclaimed_units on failure) and is warn when it is non-zero.
• No schema change or migration is needed. Leases swept before the upgrade keep their recorded credit and still reject stragglers, which is correct because they were credited.

Account, budget and credential administration

An application backend provisions and inspects one customer account over HTTP: its status and capacity class, its periodic allowance, its funding position, and the credentials it authenticates with. Tollgate owns generic accounts, credential lifecycle and quota accounting. The application owns customer login, consent, plan names, prices and billing, and supplies resolved generic policy values — an allowance in CostUnits, a credential limit — rather than its own vocabulary.

This is the supported alternative to reaching into Tollgate's tables or re-implementing credential and budget authority in a second service (GL-121).

Authority and transport

Every route below admits the operator role from the control-plane security runbook, and every route but deposit also admits the provisioner role. An instance credential authenticates the request path and cannot administer accounts: it must not reach a customer's funding position or credential list. Anonymous callers are refused. TLS is required outside loopback.

A self-service signup service should hold a provisioner, not an operator. It can run this whole sequence except deposits, and nothing else: it cannot fund an account, suspend or close one, grant Assured, set a budget above its max_budget_allowance, publish an Elastic snapshot, or touch an account an operator created. An operator's suspension holds against it — a customer cannot undo an abuse suspension by retrying signup. The provisioner scope lists every limit; each refusal is 403 and is audited.

Identifiers — account_id, key_id — are 32 lowercase hexadecimal characters, as elsewhere in this API.

The provisioning sequence

Each step is safe to repeat. A caller that loses a response resends the same request; none of these steps creates a second account, funds a period twice, or discloses a secret again.

1. Create the account. POST /v1/admin/accounts

{ "account_id": "…32 hex…", "initial_balance": 0, "status": "Suspended" }

201 on creation, 409 account-exists if it already exists — which is the retry answer, not a failure: the account is there and creation is never destructive. An operator's creation assigns CapacityClass::Assured; step 2 changes it if the plan calls for something else. A provisioner must send exactly this body — zero balance, Suspended — and its account is created BestEffort, so step 2 is already done.

Create suspended and activate in step 4, so an account cannot lease before its budget and credentials exist.

2. Set the capacity class, if not Assured. A provisioner may only set BestEffort. POST /v1/admin/accounts/{account}/capacity-class with {"capacity_class": "BestEffort"}. Idempotent; the response reports how many live snapshots the change republished.

3. Set the periodic allowance. PUT /v1/admin/accounts/{account}/budget

{ "budget": { "allowance": 500, "period": "UtcCalendarMonth", "rollover": "None" } }

The response reports both states, so a repeat is visibly a no-op:

{ "previous": null, "current": { "allowance": 500, … } }

"budget": null clears the schedule. That is not the same as an allowance of zero: null means the balance does not expire, zero means the account is funded nothing each period. The budget field must be present: {} is rejected as 422 invalid-json and preserves the existing schedule. Concurrent updates report the predecessor captured under the account lock.

A one-off deposit is not a substitute for an allowance. POST /v1/admin/accounts/{account}/deposit adds units once; a schedule funds the account at every period boundary and expires what the previous period did not spend. Setting a schedule deposits nothing by itself — the first funding arrives at the next boundary — so an account that must be usable immediately needs both.

4. Activate. POST /v1/admin/accounts/{account}/status with {"status": "Active"}. Idempotent. Closed is terminal: no transition leaves it, and the request is refused with 409 account-closed. A provisioner's activation is refused with 403 operator-hold when an operator set the account's current status — typically an abuse suspension — and only an operator can lift it.

5. Issue a credential. See below. Do this last: a credential that exists before the account is active authenticates into denials.

6. Bind its policy. PUT /v1/admin/accounts/{account}/keys/{key}/snapshot publishes the snapshot the credential authorizes against. See binding a policy. Until this step the credential authenticates, but no snapshot authorizes it.

Issuing a credential

POST /v1/admin/accounts/{account}/keys

{ "key_id": "…32 hex, chosen by you…", "max_active_keys": 3,
  "not_after": "2027-01-01T00:00:00Z" }

201 with the secret, disclosed exactly once:

{ "key_id": "…", "secret": "…hex…", "not_after": "2027-01-01T00:00:00Z" }

secret is the credential exactly as it is presented: 64 lowercase hexadecimal characters, which the owner sends verbatim — for example as Authorization: Bearer <secret>. Do not decode it. The stored digest covers these characters, and a verifier is handed the same bytes.

The caller chooses key_id, and that choice is the retry contract. Generate an unguessable one — a v4 UUID — and keep it until the call is acknowledged. Resending the same request answers 409 credential-exists, which is true and discloses nothing: your first call succeeded.

Nothing can return that secret again. What Tollgate stores is an HMAC of it; the secret is not recoverable from anything retained, by anyone, including an operator with database access. If you lose it, revoke the credential and issue a new one under a new key_id. There is no reissue, and no endpoint that re-reveals.

Order inside the server is mint, store, return. A crash between minting and storing loses a secret nobody has ever seen. The reverse would hand out a credential the server has no record of, which no reconciliation could repair.

max_active_keys is your policy, enforced atomically against concurrent issuers — two requests racing for the last place do not both win. 409 active-key-limit means the account already holds that many live credentials; revoked and expired ones do not count, so an account cannot be stranded behind credentials nobody can authenticate with.

Listing

GET /v1/admin/accounts/{account}/keys?after=…&limit=…

{ "as_of": "…", "keys": [ { "key_id": "…", "not_after": null,
  "revoked_at": null, "live": true } ], "next_after": null }

Metadata only. No secret, no verifier digest, and no principal — the principal is the digest's leading 128 bits, so returning it would disclose half of what the verifier compares against. key_id is the non-secret handle, and the only one you need: it is what revocation names and what an audit shows.

Revoked and expired credentials are listed, and distinguishable: revoked_at says an operator withdrew it, not_after says it lapsed on its own. live is derived against as_of so you need not re-implement the rule. Page with next_after; null means this page is the last. limit must be between 1 and 4096. Malformed cursors or query values return 400 invalid-query; zero or oversized limits return 422 invalid-limit. These are client errors and do not trigger a store read or backend diagnostic.

Revoking

DELETE /v1/admin/accounts/{account}/keys/{key} → {"key_id": "…", "retired": true}.

retired: false means it was already revoked. That is a success, not an error — your intent is satisfied — but the distinction is what an audit needs. Audit resources identify {account}/keys/{key}. Confirmed issuance records Absent to Credential { account_id, key_id, revoked: false }; first retirement changes revoked to true, and repeated retirement records equal states. These receipts come from the store's mutation lock, not a separate HTTP read. An unrevoked credential may still be expired. No secret, digest or principal is included in the audit receipt.

Revocation is bound to the account in the path. A key_id belonging to another account answers 404 unknown-credential and revokes nothing. You cannot retire another customer's credential by guessing or mistyping an id.

Revoking a key is two calls. Revocation retires the credential but leaves its bound snapshot in place. That is safe for authorization, because a revoked credential leaves the key projection and fails authentication. It is still a stale positive grant, so follow every revocation with DELETE /v1/admin/accounts/{account}/keys/{key}/snapshot.

Revocation is terminal and generation-ordered. It is not instant across a fleet: serving instances hold a projection and converge at their next refresh. See the credential projection runbook for that window. Treat revocation as "no new sessions promptly", not "every in-flight request stops now".

Binding a policy

PUT /v1/admin/accounts/{account}/keys/{key}/snapshot with {"snapshot": { … }} → 204. DELETE on the same path withdraws it → 204.

You name the credential by the handles you already hold. The server resolves its principal from its own key record, and the principal never appears in a request, response or audit. The principal routes (PUT/DELETE /v1/admin/snapshots/{principal}) remain for embedders that derive principals themselves.

• Bound to the key in the path. Leave the snapshot's key_id unset and the server fills it in, or state the path's key. A snapshot that names a different key, or another account, answers 422 invalid-credential-binding and publishes nothing.
• Bound to the account in the path. Another account's key_id answers 404 unknown-credential, as revocation does.
• The ledger owns status and capacity class. A snapshot must carry the account's current values (409 snapshot-status-mismatch, 409 snapshot-capacity-class-mismatch). The server stamps the budget.
• Retired credentials are never granted a policy again. PUT on a revoked key answers 409 credential-retired. DELETE still works, and is how you finish revoking it. An expired but unrevoked key may still be published.
• Generations only move forward. A publish at or below the stored generation answers 204 and changes nothing: the audit receipt records equal before and after. After a withdrawal, only a strictly higher generation republishes. Increase the generation on every policy change.

Audit resources identify {account}/keys/{key}/snapshot, with actions publish_key_snapshot and remove_key_snapshot. Receipts record the snapshot's generation and whether it is withdrawn, and never a principal.

Reading an account

GET /v1/admin/accounts/{account}

{ "account_id": "…", "as_of": "…", "status": "Active",
  "capacity_class": "Assured", "origin": "Operator", "status_set_by": "Operator",
  "budget": { … }, "period_start": "…",
  "balance": 600, "outstanding_lease_grants": 400, "settled_usage": 0,
  "expired_allowance": 0, "settlement_loss": 0,
  "deposited": 1000, "overage_recorded": 0 }

origin names the authority that created the account and status_set_by the one that set its current status, each Operator or Provisioner. They are what a provisioner's scope and an operator hold are decided from.

Authoritative as of as_of, from one consistent backend snapshot, so the figures agree with each other. It is not a live feed: an admission committed a millisecond later is not in it, and two reads are two instants. 404 unknown-account for an account that does not exist — never a zeroed body, because "does not exist" and "exists with no funding" are different answers.

All counts are CostUnits: whole units, never fractional, never a currency. Converting to money is your job, with your prices.

Balance is not a bill

A falling balance is not spend. It falls for three unrelated reasons, and only one of them is billable:

A dashboard that shows depletion as usage will overstate what a customer owes, by exactly the capacity they are currently holding. settled_usage is the usage number.

deposited and overage_recorded are the left side of the funding equation whose right side is balance + outstanding_lease_grants + settled_usage + settlement_loss + expired_allowance. It holds exactly; a caller may check it.

Unobserved activity. Work admitted against a live lease is inside outstanding_lease_grants until that lease settles — it is neither in settled_usage nor lost. An account with outstanding grants has usage not yet attributable, and a bill drawn before those leases settle is provisional.

Errors

Every failure is RFC 7807 with a stable code. Retry behaviour by class:

State conflicts return 409: those requests are well-formed. Invalid bodies and limits return 422; malformed queries return 400. Secrets and digest material never appear in an error body or a log line.

Deployment

Issuance requires a configured credential issuer. The tollgate-server binary issues only when its security manifest names one: "issuer": {"secret_file": "issuer.secret"}. See credential issuer for the format, validation, reload and rotation rules. Without it, issuance answers 501 issuance-unsupported. That default is deliberate: an instance that only verifies should not hold the capability to create credentials. The registry the server builds for control-plane bearers is never used for issuance, because its secret is regenerated at every start — the wrong authority and the wrong lifetime for a credential a customer keeps. Embedders that build their own server still pass any CredentialIssuer through ServerState::issuer, for example an HSM- or KMS-backed one. Every other route on this page works without an issuer.

Credentials are digested as presented. Releases before this one disclosed the secret as hex but digested the 32 bytes it encodes, so a credential they issued verified only for a caller that hex-decoded the presented value. A verifier that forwards the presented text, like the reference embedder, refused every such credential. Credentials issued now verify as presented. Re-issue any credential minted by an earlier tollgate-server and revoke the old one.

Migration 0019 adds (account_id, key_id) to the credential table for the account-scoped listing. Additive and forward-only: no data change, safe to apply before the code that uses it, and harmless if the deployment is rolled back.

Backend now requires KeyDirectory. A server administers credentials as well as projecting them. HttpStore implements KeySource but not KeyDirectory — correctly, since it is a client of a server rather than the authority behind one — so it cannot back a server. No in-tree backend is affected.

KeyDirectory requires publish_key_snapshot and remove_key_snapshot. Key-bound binding must resolve the principal, check retirement and publish in one indivisible step, so a backend implements it rather than a caller composing reads. This is breaking for implementations outside this repository; MemoryStore and PostgresStore implement both. No migration: the lookup uses the (account_id, key_id) index from 0019.

Conformance

A consumer adapter should pin an exact Tollgate release tag and verify, against that tag, that:

1. repeating each provisioning step changes nothing and reports the repeat;
2. a lost issuance response resent with the same key_id answers 409 and discloses no secret;
3. a listing contains no secret, digest or principal field;
4. revoking another account's key_id answers 404 and leaves it live;
5. settled_usage stays zero while a lease is outstanding, and the funding equation holds across the grant;
6. a policy binds by (account_id, key_id) without the caller handling a principal; another account's key answers 404; a revoked key answers 409 credential-retired, and revoking a key is followed by withdrawing its policy.

crates/tollgate-server/tests/api.rs exercises 1–6 against the in-process router, with the issuer built through the same manifest path the binary uses. It is the executable reference for the expected status codes and bodies. crates/tollgate-server/tests/backend_features.rs runs issuance, verification, binding and revocation against the stock binary.

Usage ingestion and database guards

UsageSink::ingest classifies each input as accepted, duplicate or rejected. Only accepted events affect billing, lease usage and credential activity. Duplicate detection precedes payload validation, including when a replay changes its units or funding source. A rejected input does not claim its request ID; a corrected event with that ID can still be accepted.

MemoryStore's unit domain is 0..=u64::MAX. PostgreSQL uses nonnegative BIGINT, 0..=i64::MAX. Both admit zero-unit events. PostgreSQL rejects an individual event outside its domain while retaining valid neighbors. Memory's larger range remains supported; moving workloads between backends requires values that fit the destination's existing domain.

A batch of individually representable events can still overflow an aggregate or a monotonic accounting counter. Both backends then return IngestError::Refused and apply none of the batch, including request IDs and credential activity. This is terminal for the unchanged batch: the usage writer accounts for undelivered events through its existing loss reporting instead of retrying forever. Operational errors and stored corruption remain retryable; corruption needs explicit repair before retries can succeed.

The request path, wire DTOs and accepted-event ledger equations are unchanged. PostgreSQL's oversized-event outcome changes from a failed batch to an individual rejection. Its accounting-overflow outcome becomes a permanent refusal. MemoryStore's leased-usage overflow becomes a refusal instead of a panic.

Migration and rollout

0015 installs checks for nonnegative tollgate_usage_events.units and positive fences in usage events, leases and the account's next_fence counter. Overage retains a null lease and fence; the existing all-or-nothing capability check still applies. All legitimate prior writers already use positive fences.

0015 uses NOT VALID to install guards without scanning usage history under an exclusive lock. It still needs brief exclusive locks for the catalogue changes; plan deployment around long-running transactions that could delay them. 0016 validates the guards in a separate transaction with SHARE UPDATE EXCLUSIVE, which permits ordinary row reads and writes during the scan. Validation time and I/O scale with existing table contents. These lock modes follow PostgreSQL's constraint validation rules.

Before deployment, inspect existing data without changing it:

SELECT request_id, units, fencing_token FROM tollgate_usage_events
WHERE units < 0 OR fencing_token <= 0;
SELECT lease_id, fencing_token FROM tollgate_leases WHERE fencing_token <= 0;
SELECT account_id, next_fence FROM tollgate_accounts WHERE next_fence <= 0;

Prepare migration-aware deployment and rollback binaries with both unchanged migration files. PostgresStore::connect runs SQLx migration validation before serving. A binary whose embedded catalogue ends at 0014 refuses a cold start after 0015 is applied. Already-running old binaries retain compatible SQL write shapes, but keep the old batch-failure behavior until upgraded. Prevent old binaries from restarting or scaling out during the transition.

If 0016 finds invalid history, startup fails and 0015 remains committed. Its guards continue checking new writes; the invalid historical rows are preserved. Reconcile affected rows from authoritative usage and lease evidence, preserving the audit trail, then rerun startup to validate. Do not clamp negative units, invent replacement fences, drop guards or delete migration history to make startup pass. In particular, repairing a counter requires establishing the account's allocation sequence, not merely replacing zero with one.

Rollback retains the schema and migration history and uses a rollback build that knows both migrations. An unmodified older binary is not a cold-rollback artifact. Any later schema change requires a new forward migration.

Evidence

The mirrored store suites test mixed-batch classification, duplicate precedence, zero and maximum representable units, and atomic refusal in both event orders. PostgreSQL cases additionally exercise out-of-range inputs, negative and zero stored fences, and schema write rejection. Isolated-schema migration tests upgrade populated 0014 tables, preserve leased/overage rows, reject an old startup catalogue, and exercise validation failure followed by evidence-based fixture repair without removing migration history.

The natural-number conservation proofs in formal/lean/Tollgate/Conservation.lean continue to describe accepted transitions. These changes do not add a ledger term or change those equations. The finite-width limits, rejection partition and transaction rollback are implementation obligations covered by these tests and the mutation gate; the exact model does not prove SQL locking or overflow behavior.

Snapshot distribution health and refusals

SnapshotManager::ready() reports the configured resolution rule while the task is alive: Fixed requires every tracked principal to be resolved; All requires some resolved principal, or an empty catalogue. A fresh negative resolution counts as resolved. The admission map independently refuses unknown, revoked and stale requests. InstanceRuntime adds funding and other background task health to this snapshot rule.

The snapshot and lease managers store false before their health watch closes on normal exit, unwind or task cancellation. Retained receivers can read that value directly. Channel closure still distinguishes an exited task from a live but unhealthy one. Cancellation takes effect when the executor destroys the future; it cannot preempt blocking custom source code. The publishers are owned before spawning, so cancellation before the first poll also closes with false. Graceful shutdown remains the way to drain usage and return quota.

Read SnapshotManager::counters().snapshot() directly, or use RuntimeHandle::report().snapshots. The pricing example exports the same snapshot counters under snapshots in /metrics:

An ordinary refresh of an already installed positive at the same generation is quiet and does not increment refused_updates. Newer positives, accepted revocations and unversioned absences also leave that counter unchanged. The counter includes older positives/revocations and positive replays at a retained revocation's generation. A refusal preserves the previous resolution, deadline and generation; the existing refresh retry backoff still applies.

Each refusal emits a warning with origin (push or refresh), principal, kind (positive or revoked), offered generation and retained watermark. Use these fields to identify a delayed publisher or lagging source replica. Recover the source's authoritative generation; do not clear tombstones or lower watermarks to make a replay pass. The aggregate counter supports alerting even when event collection is disabled, and carries no per-principal metric labels.

Interpret counters with task health. A stopped manager may retain unresolved = 0 while readiness is false. All mode can remain ready with a nonzero unresolved count. A flat attempt counter alone does not establish task death: an empty catalogue or negative-cache schedule can also explain it.

Snapshot maps retain a bounded number of generation histories, including pending source reads. MokaSnapshotMap::new(max_capacity) uses that many history slots (at least one when visible caching is disabled); with_capacities configures visible and history budgets independently. ArcSwap defaults to 65,536 histories and 4,096 visible negatives, with with_capacities for explicit budgets. InstanceRuntimeConfig::snapshot_history_capacity is a required NonZeroUsize. Choose it to cover the maximum simultaneously served principal set and refresh working set. Fixed sets exceeding the budget fail startup validation. All mode can exceed it, but eviction then denies principals until authoritative refetch; unresolved and history_evictions expose that capacity pressure. For a service that must serve its whole catalogue continuously, provision the budget for that catalogue rather than treating churn eviction as equivalent availability.

Ordinary visible eviction and expiry preserve generation history. History reclamation removes visible entries and outstanding read permissions together; TTL expiry alone never deletes a watermark. A push for forgotten history is a refetch hint, not authority to reinstall its payload. A fresh source read must start after reservation and must observe the durable authoritative store. Configure HTTP/store adapters against the authoritative primary, bypassing response caches and lagging replicas for reconstruction. An unavailable primary must return an error. Source errors leave misses denying, increment refresh_failures, and retry on the existing refresh/negative-retry schedule; an unknown response also denies and cannot reopen forgotten history to pushes. publication_failures reports superseded reads or failed reservations separately.

For direct SnapshotMap users, handle the Result from every publication. On RefreshRequired, call prepare_refreshes, immediately process its evicted principals, invoke each returned read's fetch (or synchronous read) with a new authoritative operation, translate the result with filter_map, and publish through apply_refreshed_many_at. A Superseded response must be discarded and retried with a new reservation/read. Split batches at generation_capacity. Read identities use checked allocation; exhaustion requires replacing the map and rebuilding from the source, preserving live account lease slots. Never attach an old response to a new read or clear durable tombstones to recover. The running SnapshotManager owns this publication/resolution protocol; avoid independent publishers mutating its map and bypassing its readiness bookkeeping.

The history bound covers generation entries and their ordering index, not the source catalogue, tracked membership, caller-owned in-flight responses, or irreversible account spend history. history_stats reports retained occupancy. Increasing the budget requires constructing a replacement map/runtime and doing a fresh initial load; durable store state remains authoritative. Drain and shut down the old runtime normally so accounting and lease retirement complete.

Rust callers must handle publication results and supply the runtime history budget; custom SnapshotMap adapters must forward the new refresh, occupancy and visibility methods when wrapping a bounded map. Unbounded custom maps retain compatibility defaults and do not acquire a bounded-retention guarantee. Metrics structs add history_evictions and publication_failures; JSON consumers should accept these additional numeric fields. Rebuild callers against the same tag. There is no database or snapshot-wire migration. Older and newer instances may coexist against the same durable source, provided reconstruction reads satisfy the source-ordering contract. No request-path or threshold changes are involved.

Lease timing and PostgreSQL upgrades

Both allocators preserve the nanosecond precision of the caller's Timestamp and positive SignedDuration. The policy clamps a requested TTL only to max_ttl. Acquire and consolidation return the exact resulting expiry; an unrepresentable expiry returns a structured storage error before any balance debit or settlement. Grace remains a nonnegative duration, including zero and values too large for a timestamp deadline.

A lease with expiry e is reclaimable at supplied time n exactly when e + reclaim_grace <= n. Release is accepted before that boundary, subject to its normal capability, state and accounting checks. GrantPolicy::reclaim_cutoff computes n - reclaim_grace with checked timestamp arithmetic. Underflow means no representable expiry is due. A deadline beyond Timestamp::MAX has not elapsed even at Timestamp::MAX; it is never saturated to an earlier time. These rules apply equally to MemoryStore and PostgresStore. Grace configuration must remain consistent across backends sharing the same grants.

PostgreSQL stores new lease instants in two columns:

Together the first two fields represent 1000 * floor_us + submicro_ns exact nanoseconds since the Unix epoch. Database constraints enforce the complete Jiff timestamp domain. Tuple comparison has the same ordering as the original instant, including before the epoch. The active expiry index covers both components. Release decodes that same stored instant; reclaim compares it to the same exact policy cutoff. No grace duration is converted to microseconds.

Migration 0017

This is a coordinated backend upgrade with a database maintenance window. Public allocator signatures, HTTP DTOs, error codes and valid configuration retain their contracts. Old PostgreSQL lease statements are incompatible with the migrated schema. The schema change does not enter the request path.

1. Preserve a recoverable database backup and the running policy configuration. Quiesce incoming work, drain usage and shut down old store/server processes, including reclaim workers and direct-store clients. Keep the same reclaim grace throughout the upgrade. Active grants do not need to be discarded.
2. Start a backend carrying migration 0017. The migration takes a table lock, renames the expiry column, adds its remainder and provenance, backfills legacy bounds, validates every row and rebuilds the partial expiry index in one transaction. Allow for table-size-dependent backfill/index work and lock acquisition. It changes no unit, fencing, state or accounting field.
3. Start only compatible backends. Check storage and maintenance readiness, normal accounting conservation and the count of active legacy bounds below; then resume traffic. Existing HTTP clients and retained lease capabilities continue to work with the upgraded service.

The column rename is a database-enforced compatibility fence. An old acquire, release, consolidation or reclaim query fails with an undefined-column error, including on a connection opened before migration. The normal transaction rollback preserves any preceding account debit. An old process starting after the migration refuses the unknown migration version. A mixed fleet therefore loses availability at old lease endpoints rather than accepting an early reclamation. Do not bypass either fence. Already-running old transactions hold table locks that the migration must wait for; the new format is not visible until the migration commits.

Legacy writers truncated fractional microseconds toward zero. The original expiry cannot be reconstructed from those rows. Migration records the latest possible expiry consistent with the stored value: add 999 ns for nonnegative microseconds, and retain the stored instant for negative microseconds. This can delay settlement by at most 999 ns, except the zero-microsecond bucket spans -999 through +999 ns and can delay it by 1,998 ns. It never makes a previously advertised expiry earlier. The true marker makes this uncertainty inspectable; it remains on settled history. Ordinary release, consolidation or reclaim drains active legacy grants, and every new grant is marked exact.

SELECT state, expiry_is_upper_bound, count(*)
FROM tollgate_leases
GROUP BY state, expiry_is_upper_bound;

There is no automatic schema downgrade. An older binary cannot run its lease operations against migration 0017. Recovery after a successful upgrade is a compatible corrected binary or a separately designed, reconciled restore; dropping the remainder would lose live timing evidence. A failed migration rolls back its schema and data changes and leaves version 0016 authoritative. For out-of-domain historical timestamps, inspect the offending records and repair only from authoritative evidence before retrying. Blind clamping would invent an expiry. The migration does not reconstruct loss from grants already settled by older software.

Evidence and limits

Tollgate.LeaseTiming proves integer-pair encoding/order, exact cutoff equivalence, underflow/overflow safety and the conservative legacy bounds. It assumes integer nanoseconds and valid timing inputs; it does not prove driver behavior, PostgreSQL isolation, clock accuracy or a Rust refinement. Property tests compare finite timestamp arithmetic with an independent i128 oracle. Mirrored backend tests cover fractional TTL/grace, policy clamping, negative timestamps, both domain endpoints, consolidation, release and idempotent reclamation with exact ledger checks. Migration tests cover retained old connections, old startup refusal, accounting preservation, restart durability, legacy bounds, invalid history and schema constraints. Mutation and formal gates run in CI.

No request-path code, measured benchmark path, timing threshold or baseline changes. The control plane retains its existing transaction count and bounded reclaim batches. Migration backfill and index creation scale with stored rows; the account-order reclaim sorting concern was fixed separately, in GL-65.

Lease ownership and PostgreSQL test support

LeaseSlot::replace publishes a grant and returns the previous handle, if any. LeaseSlot::take empties the slot and returns its handle. Both results are must_use: removing a local handle does not return its unspent quota to the allocator. Retain it until all reservations and local views have quiesced, then release its exact remainder. LeaseManager handles this for supported runtimes, including a grant displaced when a consolidation call finishes.

The single-view slot swaps atomically; sharded publications serialize mutators while requests continue to load without a blocking lock. Each returned handle names the displaced grant's shared state. Never release it just because it was removed from the slot: an in-flight request may still debit or refund it.

Migrating lease callers

LeaseSlot::install and LeaseSlot::clear have been removed. This is a Rust API break; the service wire protocol and store schema are unchanged.

• Replace install(fresh) with replace(fresh) and retain any displaced grant for quiesced release.
• Replace clear() with take() and handle the returned grant. If its state is already settled, or deliberately abandoned, dispose of the handle explicitly.
• drop(slot.replace(fresh)) and drop(slot.take()) deliberately abandon the old handle. An unsettled grant then waits for TTL reclamation. In-repository tests and benchmarks use this spelling for synthetic grants with no allocator to settle; production refill paths retain the grant.

replace and take otherwise retain their signatures and publication behavior. No request-path algorithm, benchmark workload or performance threshold changes.

PostgreSQL fixture operations

PostgresStore does not expose truncate_all or explain_active_lease_sum methods. Tests that need them enable the backend's non-default test-support feature and call the functions in tollgate_store_postgres::test_support:

use tollgate_store_postgres::test_support;

test_support::truncate_all(&store).await?;
let plan = test_support::explain_active_lease_sum(&store, account).await?;

Use only an isolated disposable database. Reset deletes account, credential, lease, snapshot and usage rows, including dependent rows through CASCADE; schema and migration history remain. Plan inspection runs ANALYZE before EXPLAIN, so it also mutates database statistics. Neither belongs in a serving application's operational API.

Ordinary consumers do not enable test-support. In-repository backend and server tests opt in through test-only self dependencies, preserving the existing test commands without enabling the helpers in normal builds. The server forwards the feature only when its optional PostgreSQL dependency is already enabled; its --no-default-features build and tests remain independent of PostgreSQL. External test harnesses enable the feature on their backend dev-dependency. Cargo features are additive: a production build that explicitly requests all features also opts into this module, so deployments should select their required features rather than treating all features as a production profile.

The helper SQL, connection usage and database migration catalogue are unchanged. Public read operations (balance, usage_recorded, conservation) remain on the normal store handle.

Instance-local sharding

Opt-in. The default, LocalSharding::SINGLE, is one shard and this document does not apply to it — with one exception. The engine's outcome tallies (AdmissionCounters) are one set per instance, shared by every account, so they are partitioned per locality under every layout, including the default: at least as finely as the lease layout and the host's parallelism, as a power of two (GL-132). AdmissionCounters::local_sharding reports that layout. It carries none of the condition below, because a tally is a sum however it is split — two threads that share a tally shard cost each other contention, never correctness.

What it buys, and the condition attached

A sharded instance keeps one copy of each account's mutable hot-path state per shard — admission state, lease counters, rate buckets, outcome tallies — so that worker threads hammering the same account stop fighting over the same cache lines. Measured on a 24-core x86_64 development host, eight threads on one account cost 176 ns per admission when each held its own shard and 862 ns when two shared one: a factor of 4.9 (GL-123). Across eight different accounts the same collision cost ×1.38, because those threads share less per-shard state to begin with.

That benefit has a condition, and the condition is a property of your deployment rather than of the library:

Each request-serving thread must hold an affinity that no other request-serving thread shares, after reduction by the shard count.

Affinities come from one process-global counter. A thread takes its number on its first use of the request path, not when it is spawned, and numbers are never recycled — a thread that took one and exited keeps it. Locality::index reduces the number onto the shard count, so two threads whose numbers are congruent modulo that count share every sharded structure they touch.

The counter hands out 0, 1, 2, …, so the condition holds exactly while the affinities handed out do not outnumber the shards.

Whether an account needs it

Sharding helps an account whose funding line is written from several cores at the same moment. RuntimeHandle::report() carries a contention block that says which accounts that is happening to:

#![allow(unused)]
fn main() {
let contention = handle.report().contention;
// `contention.contended_exchanges`: admission exchanges on this instance —
// lease and overage debits, concurrency-gauge acquisitions — that lost a
// compare-exchange to another core, since the process started.
// `contention.hottest`: up to eight `(AccountId, count)` pairs, most first.
}

LeaseSlot::contended_exchanges reads the same count for one account. Both are control-plane reads; the request path only counts, in a register, and records once per debit that actually lost a race.

Read it as a rate between two reports. A count that climbs steadily for one account is direct evidence that its admissions overlap across cores, and that account is the candidate for a sharded deployment. The count is a lower bound: only the retry loops — lease and overage debits, concurrency-gauge acquisitions — can observe a lost race, while the rate bucket, reference counts and settlement pay for a contended line without ever failing. So a zero does not prove the account costs nothing — ten connections on one account at about 93,000 admissions a second recorded zero on the controlled host while their end-to-end overhead was measurable — but a nonzero count is never noise on x86-64 or aarch64 with LSE atomics.

What sharding costs in return is paid by every account on the instance: retained memory grows from about 4.0 KB per account unsharded to 14.6 KB at eight shards and 26.0 KB at sixteen, and each account's rate burst is partitioned across shard buckets.

Choosing a shard count

Start at the runtime's worker-thread count and validate on your own host.

A Tokio multi-thread runtime defaults to one worker per logical CPU, and LocalSharding::available_parallelism() returns the same number, so those two agree unless you have configured worker_threads yourself. If you have, size the shards to the workers, not to the CPUs.

Sizing below the worker count guarantees crowding: there are not enough shards to go round, and some workers will share. Sizing above it costs memory per account and buys nothing.

Threads that are not serving requests still consume affinities if they reach the request path, and every one they take displaces a worker. The library no longer does this to you — control-plane reads inside tollgate-client use a fixed observer affinity and claim nothing (GL-124) — but an embedder that admits from spawn_blocking, from a second runtime, or from short-lived threads is spending the same budget.

Reading the report

RuntimeHandle::report() carries a sharding block:

#![allow(unused)]
fn main() {
let occupancy = handle.report().sharding;
if occupancy.is_crowded() {
    // `occupancy.shards` shards, `occupancy.affinities_assigned` affinities,
    // `occupancy.crowded_shards()` of them carrying more than one.
}
}

Embedders that drive AdmissionEngine without InstanceRuntime can read the same thing from the map's own layout:

#![allow(unused)]
fn main() {
let occupancy = engine.map().local_sharding().occupancy();
}

is_crowded() is true when this process has handed out more affinities than it has shards. It is a statement about affinities, not about live threads: the process can say how many it issued but not which threads still hold them, because nothing is recycled. That is the useful reading rather than a weaker one — an affinity a departed thread took still displaces every affinity issued after it.

Both reads are control-plane calls. No admission decision consults them, and they take no locks.

What to do about a crowded instance

1. Compare shards against your worker count. If shards are fewer, raise them to match and redeploy. This is the common case and the only one with a configuration fix.
2. If they already match, something else is consuming affinities. Look for request-path calls from outside the worker pool: spawn_blocking, a second runtime, or threads created per unit of work. Move that work onto the worker pool or stop admitting from it.
3. Do not raise the shard count to out-run the leak. Affinities are never recycled, so a process that issues them continuously will crowd any count you pick; raising it delays the report without changing the outcome.

A crowded instance is not incorrect. Every accounting and authorization guarantee holds unchanged — affinity is a cache-locality hint and never authorization evidence. What is lost is the performance the layout was enabled to buy, which is why this is reported rather than refused.

Related

• docs/DESIGN.md — why sharding is opt-in, and what each sharded component partitions.
• INVARIANTS.md GL-40 — the property stated as a contract, and what enforces which half of it.
• docs/PERFORMANCE.md — running the benchmarks that price the layout.

Customer credential projection

An HTTP-backed instance obtains active customer credential digests through KeySource, implemented by HttpStore. It needs neither a database connection nor KeyDirectory or AdminStore mutation authority. Direct memory and PostgreSQL backends implement the same read trait through KeyDirectory. Account policy and authorization remain in the separate snapshot feed.

Endpoint and deployment

GET /v1/keys requires the instance role described in the control-plane security runbook. Operator authority does not grant this read. TLS is required outside loopback. The server selects active, non-revoked credentials using its own clock on every page. The only query fields are after (exclusive, 32 lowercase hexadecimal key ID) and limit (1–4096, default 256). Malformed or unknown fields return 400 invalid-query; zero or excessive limits return 422 invalid-limit. Clients cannot choose a historical activity time.

Each HTTP 200 response is a page:

{"revision":12,"as_of":"2026-09-09T12:00:00Z","keys":[],"next_after":null}

Records contain key_id, principal (32 lowercase hexadecimal characters), digest (64 lowercase hexadecimal characters), and required not_after (timestamp or explicit null). Account policy, customer secrets, and the HMAC secret are absent. next_after is required even when null. A continuation is the final returned key ID, and exists only if lookahead found another active record. An exactly full final page is terminal. Success carries Cache-Control: no-store; clients refuse partial statuses and Content-Range. The derived body limit admits every maximal legitimate page, including widest IDs and timestamps. Do not log the digest catalogue.

Records and revision come from one committed backend read. Mutations advance the revision; a manager that observes different revisions discards its candidate and restarts from the beginning. Expiry can narrow later pages without changing revision, so the manager also filters accumulated records at the later of its own clock and the latest page's server time. A revocation after the final page's read is subject to the refresh window: this protocol provides a coherent committed revision, not a transaction extending through publication on the instance.

The PostgreSQL schema includes a revision table, a transactional mutation trigger and a partial key_id index. Direct writers do not manage revisions; the trigger advances them atomically, including rollback and overflow checks. Removing the trigger or resetting the revision while readers run is unsupported. Migration 0018 preserves exact credential expiry and requires the coordinated upgrade below. Old expiry readers and issuers are incompatible with that schema.

KeyDirectory has the KeySource supertrait, and Backend requires its read bound; custom backends implement the paged contract. KeyDirectory::active_keys remains an unbounded operator read. Allocator/authentication APIs, HTTP page fields and error codes retain their contracts in this precision correction. Pin server/client consumers to the same tested Git tag.

Expiry precision and upgrade

New credentials retain the complete nanosecond not_after timestamp through insertion, directory reads, every page, HTTP decoding and verifier/session evidence. The expiry is exclusive: an unchanged credential works one nanosecond before it and refuses at the instant itself. None continues to mean no individual expiry; managed projections still impose their freshness bound. All representable timestamps, including pre-epoch values and both domain endpoints, remain valid. Revocation's timestamp is informational: its presence retires the credential immediately, independently of the supplied read time. Credential activity remains a separate microsecond reporting contract.

PostgreSQL stores finite expiry as not_after_floor_us plus not_after_submicro_ns (0–999). Both fields must be present or both absent. Their integer pair preserves exact timestamp ordering. The existing key-ID indexes and page bounds remain; there is no request-path change. Constraints refuse partial or out-of-domain rows, and readers report incomplete evidence rather than interpret it as indefinite validity.

Migration 0018 cannot reconstruct fractions discarded by legacy writers. It uses the earliest possible expiry consistent with truncation toward zero: positive microseconds start at their stored instant; negative and zero values start 999 ns before it, bounded by Timestamp::MIN. This can end authority up to 999 ns early, or 1,998 ns for the zero bucket, but cannot extend it. Finite legacy rows carry not_after_is_lower_bound = true; indefinite rows remain exact nulls, and every new insertion declares exact evidence. This marker is durable operator evidence and is not added to the wire DTO.

This upgrade requires a maintenance window across credential sources and consuming instances, not only the database:

1. Preserve a recoverable backup and the running configuration. Stop ingress, drain admitted work and usage, and stop old issuers, credential servers, projection managers and direct-store consumers. Follow the lease shutdown order for instances that also hold quota.
2. Clear all old registry projections and SessionCredential proofs. Restarting every process that owns them provides this boundary. A refresh alone is insufficient: an existing session retains its originally issued deadline even after a corrected table replaces it. An embedder doing an in-process upgrade must demonstrably clear every such session before resuming ingress.
3. Start a backend with migration 0018. The transaction locks the credential table, renames the old expiry column, backfills bounds and validates all rows. The existing trigger advances revision once if finite rows change; revision overflow or invalid history rolls back schema and data together. Allow for table-size-dependent backfill and lock acquisition.
4. Start compatible issuers/readers, then fresh instance projections and sessions. Require key-manager and runtime readiness before resuming ingress. Inspect the uncertainty counts below; rotate affected credentials through the normal durable issuance/revocation lifecycle when exact replacement evidence is needed. Do not clear a marker or extend a bound by guessing.

SELECT revoked_at_us IS NOT NULL AS revoked,
       not_after_is_lower_bound, count(*)
FROM tollgate_credential_keys
GROUP BY revoked, not_after_is_lower_bound;

The renamed column makes old expiry reads/writes fail, including on connections opened before migration. Old insertion shapes that omit the new evidence declaration also fail. Old revocation-only statements remain valid because they only remove authority. Old startup refuses the unknown migration version. These database fences cannot retroactively invalidate a proof already cached in another process; the session reset above is required. The migration does not alter key IDs, accounts, principals, digests, retirement or billing history.

There is no automatic downgrade to the old expiry schema. Recovery after commit uses a compatible corrected binary or a separately reconciled restore; dropping nanoseconds would reintroduce the defect. A failed migration retains the old schema and history. Repair invalid timestamps only from authoritative evidence; revision exhaustion requires a deliberate source-generation recovery plan, never lowering the revision under live readers. Finite legacy uncertainty remains on retired history; normal rotation replaces active credentials with new exact records without erasing that history.

The Lean projection model proves that conservative source bounds cannot extend authority and that reset sessions inherit them. Integer-pair order uses the existing exact timing model. Shared backend scenarios, migration/rollback tests and real memory/PostgreSQL HTTP-to-session tests are separate finite arithmetic, driver, transaction and rollout witnesses; these do not prove cryptography or fleet-wide operator execution.

Instance lifecycle

Own a KeyManager beside InstanceRuntime. Pass the same Arc<HttpStore> as the credential source and the snapshot/lease/usage backend, with a common business clock. Set KeyManagerConfig.refresh_interval no longer than the snapshot refresh interval; include the pass duration in the propagation budget. Each key attempt starts immediately at boot, then waits that interval after the previous attempt completes. The independent tasks have no shared publication barrier: onboarding becomes usable after both projections are available and the account is funded.

Supply the HMAC secret used by the customer key issuer from the deployment's secret store. It must contain at least 32 bytes. When the issuer is the stock tollgate-server configured through its manifest's issuer entry, the secret is exactly that file's 64 hexadecimal characters as bytes, without the trailing newline — not their decoded value (see credential issuer). This secret is separate from the instance's control-plane bearer identity and is never fetched through this endpoint. The manager exposes only KeyVerifier, which implements CredentialVerifier; it cannot mint keys or install an unbounded table. Hand it the credential exactly as presented — the 64 characters issuance disclosed, after stripping only the transport framing such as Bearer — never a decoded form. Use it with SessionCredential::authenticate(credential, &verifier, now) before staged admission. Keep session state scoped to the same authenticated connection or session as before. Every request still checks current snapshot authorization.

For readiness, require both runtime.handle().readiness(now).is_ready() and keys.monitor().report(now).ready. Retain cloned handles/monitors for the application. Key readiness means a live task with a fresh complete projection; an authoritative empty catalogue is healthy even though no customer can authenticate. Report health, stats, revision, projected_keys, fetched_at, and usable_until without customer labels. projected_keys is the installed entry count, not the number of customers currently authorized or individually unexpired. A failed attempt is Degraded while the previous projection is fresh; readiness becomes false at its exact exclusive deadline. Task death is Failed and withdraws readiness immediately when observed.

Stop ingress and request admission-runtime shutdown to drain committed usage and release leases in its supported order. Shut down the key manager as part of the same application shutdown, either concurrently or after that drain; it owns no leases or usage. Include its shutdown_timeout in the application's total budget. Shutdown cancels a pending credential fetch and reports failures and deadline expiry. Dropping either the manager or its unpolled shutdown future aborts its owned task. Task teardown withdraws the published verifier table; previously issued cached proofs retain their original expiry. Tokio timeouts and aborts require cooperative tasks and do not preempt synchronous CPU work or a blocking custom source.

Freshness, rotation and outages

Defaults are a five-second refresh pause, five-second per-call timeout, ten-second pass timeout, 256 records per page, 1024 page calls per pass, 30-second max_age, and five-second shutdown timeout. Page calls spent on revision restarts count against the same budget. Hitting either budget publishes nothing and reports degradation; increase the budget deliberately for a larger catalogue. No partial table becomes a successful result.

Durations must be positive and representable, fetch_timeout ≤ pass_timeout, and max_age must strictly exceed refresh_interval + 2 * pass_timeout. The prior drain, pause, and next drain must fit inside a window measured from the prior drain's start. The deadline must also fit in Timestamp. Configure synchronized clocks across the fleet; session expiry uses caller-supplied time.

Every successful projection gives a credential evidence valid until the earlier of its own not_after and fetch start + max_age. Network time consumes this window. A response already past it cannot publish. Refresh failure retains the previous table and its original deadline; it cannot renew authority. Thus a feed outage denies authentication once the last successful window expires, including on warm sessions. The request path does no fetching and reads no clock itself: SessionCredential enforces the bound using caller-supplied time.

Key removal or rotation replaces the table on the next successful refresh, immediately affecting new verifications. An already cached session can continue through its original evidence deadline (at most max_age from that fetch's start), unless snapshot withdrawal rejects it earlier. Refreshing other keys does not renew that proof. This is bounded revocation, not instant cache eviction. Do not expose authenticated traffic when only one readiness component is healthy. Tune the freshness and snapshot windows to the revocation tolerance.

Customer key rotation can overlap old and new records; new principals also need published snapshots, which an operator binds by account and key ID without handling the principal (see account administration). The HMAC secret itself is fixed for a manager's lifetime: coordinated issuer/verifier replacement is required to change it. The API does not introduce a multi-secret rotation scheme. Control-plane service-account or bearer rotation remains independent and uses HttpStore's existing transport replacement.

Each pass has bounded page calls, transport bytes per call and elapsed time. A completed refresh still materializes the whole active set, O(active keys) memory, temporarily retaining the prior table. MemoryStore scans an ordered unrevoked-key index with hash lookups; PostgreSQL uses a partial key-ID index. Expired-but-unrevoked candidates may still be scanned. Paging removes retired history and sorting from each page, not the need to inspect expiry candidates. No request-path catalogue scan is added. A cache miss adds one immutable projection load before HMAC lookup. Warm sessions keep the existing cache path with an explicit finite expiry check; renewal allocates the new cached proof.

Operator key issuance and revocation over HTTP remain outside this API. Direct issuers persist minted records before disclosure and project afterwards. The pricing example uses digest_credential to import its public demo-key-N fixtures into MemoryStore before starting this same manager; its asynchronous builders ensure bootstrap completes before background reads start.

Credential activity is a separate projection of accepted committed usage. Publishers set a matching AccountSnapshot.key_id; operator readers distinguish unknown keys, missing observations and last_committed_at. An absent timestamp never proves non-use. The usage writer reports attribution gaps and unavailable support. See Credential activity for coverage, atomicity, operator reads and rollout. Activity never changes this feed's revision or liveness decisions.

Credential activity

KeyDirectory::credential_activity(&[KeyId]) reports the latest recorded attributable commitment for each requested key. Committed { last_committed_at } is the maximum execution-start timestamp from accepted usage events, normalized to PostgreSQL's microsecond precision. It is an instance-supplied timestamp, not independent evidence from the server's clock.

The other states distinguish an unknown credential from a known credential with no recorded attributable commitment. Neither absence nor an old timestamp establishes that revocation is harmless. Requests denied or cancelled before execution are absent; so are committed events that never reached the ledger, were refused there, or lacked valid attribution. A running execution can still own an event that has not been emitted. This API is not an authentication audit.

Publishing and reading

A key-scoped publisher sets AccountSnapshotBuilder::key_id to the issued key's ID. Both stores verify the binding against the publishing Principal and snapshot AccountId before replacing state or pushing it. Unknown or mismatched bindings return PublishSnapshotError::CredentialMismatch; the existing HTTP publication endpoint returns 422 invalid-credential-binding. MemoryStore's inherent helper and AdminStore implementation share credential, status and capacity-class checks. Custom snapshot sources/direct map installers remain trusted publishers.

The pinned snapshot supplies the key ID to the committed UsageEvent. There is no verifier lookup, clock read or activity write in authentication, and no new background task. Existing UsageWriter batching and transport deliver the event. Ingest checks the key's AccountId independently. Unknown and different-account keys leave the bill intact and supply no activity. Retired and expired keys retain their identity and can receive delayed committed events.

The read is an operator-side direct-store capability on KeyDirectory; there is no activity HTTP endpoint and HttpStore gains no lifecycle authority. Input order and repeated IDs are preserved. Output memory grows with the explicitly requested list. PostgreSQL bounds each query internally and fails the whole read on error; successive chunks need not describe one instant.

Attribution coverage

Successful ingest replies partition each submitted event into accepted, duplicate or rejected. Only newly accepted events supply activity evidence. Replays retain the first event's identity even when the submitted key ID or timestamp differs. Older/equal timestamps are attributable monotonic no-ops.

IngestReport.unattributed counts newly accepted events that lack an existing, same-account credential. Its range is zero through accepted. Some(0) is a confirmed zero; None (JSON null or a missing field from an older server) means attribution reporting is unavailable. Duplicate and rejected events do not contribute to this count. Counts measure events before grouping by credential.

UsageWriter exposes confirmed unattributed counts, the number of replies lacking attribution support, and a sticky counter-overflow flag in live/shutdown stats. Coverage gaps and recovery emit structured events. Saturation never wraps totals. These are acknowledged-outcome counters: a lost reply followed by a duplicate reply cannot recover the original accepted/unattributed count. They do not prove complete historical coverage. Existing lost/unresolved usage diagnostics remain relevant to activity too.

Both custom and HTTP sink replies must account for the complete batch before the writer releases evidence. Malformed counts, partial HTTP success and oversized acknowledgements remain uncertain/retryable failures. The HTTP success contract is 200 without Content-Range. Domain attribution mistakes do not reject billing; storage failures still roll back the complete ingest transaction and retry.

Persistence and rollout

The activity-only compatibility discussion below applies to migration 0014. Deployments including credential expiry migration 0018 must follow the coordinated source and session upgrade; its expiry-column fence supersedes the earlier additive-schema rollout.

Migration 0014 adds a nullable key_id to usage rows and a separate tollgate_credential_activity table. The usage column deliberately has no key FK: an unknown attribution must not lose a bill. The aggregate references retained credential rows and advances only to a newer accepted timestamp in the same transaction as billing. Replays are not historical backfill.

Neither write touches the credential table or 0013's revision triggers. Account snapshots, key-feed payloads and the conservation equation gain no activity term. Activity is never an authorization input. Deterministic key ordering bounds transaction lock ordering; conditional updates avoid rewriting equal/older maxima.

Prepare migration-aware PostgreSQL binaries and a tested rollback build before applying 0014. PostgresStore::connect runs SQLx's migration validation: a released v0.17 binary knows only through 0013 and refuses a cold start after 0014 is recorded. Already-running old processes can continue using the additive schema, but prevent old PostgreSQL embedders from restarting or scaling out during that transition. New binaries apply pending migrations before serving.

For rollback, retain the column/table, migration history and a rollback binary whose embedded catalogue includes the unchanged 0014 migration. Validate that binary's older business logic against the upgraded schema before deployment. An unmodified v0.17 binary is not a cold-rollback artifact. Never delete SQLx history or disable its unknown-migration guard to force an old binary to start. Any later schema removal needs a forward migration after writers stop. These startup constraints qualify the additive-schema notes in the migration header.

Update servers before enabling producers and key-scoped publishers. Existing writers omit key_id; new servers report their accepted events as unattributed. Old servers accept new payloads while ignoring the additive field; new clients report unavailable attribution support. Validate any existing key annotations against their directory bindings before upgrading publication. Pre-upgrade events with unknown identity stay unknown.

The Rust API changes are intentional in unpublished crates: UsageEvent::new, Reservation::usage_event, KeyDirectory, publication errors/the inherent helper's result, IngestReport and writer statistics. Wire additions default safely without pretending unknown coverage is zero. The widest event is 410 bytes, including a present key ID, expanded negative year and fractional timestamp; a full 4,096-event batch fits the existing 2 MiB request ceiling. Serialization tests pin both bounds.

Assurance

Invariant 35 names the owning operations and test witnesses. The shared credential_activity scenarios run against both backends; PostgreSQL additionally tests restart, rollback, source metadata and conflicting request IDs. Loopback tests exercise actual authentication, commitment and activity over HTTP, TLS bearer and mTLS. The pricing example issues and publishes matching key IDs.

formal/lean/Tollgate/CredentialActivity.lean proves exact-model max laws, first-event replay identity, report partitioning, failed transaction preservation and revision isolation. Backend execution, timestamp representation, authentication and delivery are implementation assumptions, checked separately by Rust tests and mutation/performance gates. The new commit benchmarks construct and emit events; the existing reserve/commit CAS benchmarks alone do not exercise that work. The older-catalogue restart witness pins SQLx's unknown-migration refusal and confirms that reconnecting with the current catalogue preserves activity history.

The paired measurements in testing/credential_activity_evidence.json record the baseline revision, host, profiles and individual results. UsageEvent grows from 128 to 160 bytes on that host, adding 32 bytes per queued event. The twelve event-emission cases range from 0.956 to 1.049 times their old means; these are measurements, not a zero-cost claim. Six attributed/unattributed ratios run in the ordinary performance gate with a 1.25 ceiling. PostgreSQL measurements cover 256 distinct accounts and a single frequently updated key; they include real advancing maxima and matching old-binary workloads. Updating 256 distinct credentials measured 14.7 ms per batch versus 9.5 ms before; the single-credential case measured 5.6 ms versus 5.8 ms. The extra per-credential database writes have a throughput cost even though the warmed owned commit path remains allocation-free. Size sink capacity using the attributed workload. These local PostgreSQL latencies are capacity evidence, not portable thresholds. The reproducible query-plan fixture measures bounded joins against a 100,000-key catalogue in temporary tables.

Control-plane security

Usage ingestion also derives non-authoritative credential activity from accepted events. Its instance role and secured transport are unchanged. A publisher's optional key ID must match the snapshot principal/account or publication returns 422 invalid-credential-binding. Unknown attribution at ingestion preserves the bill and is reported; activity grants no lifecycle or authorization capability. See Credential activity for coverage and mixed-version reporting. There is no additional activity HTTP endpoint.

tollgate-server authenticates every lease, snapshot, credential, usage, and administrative route. /livez and /readyz accept unauthenticated probes. Readiness checks storage reachability and the server-owned maintenance task's latest reclaim and rollover outcomes. It does not certify that every configured identity is usable. Monitor security reload warnings separately. The independently owned reloader reports unexpected task exit at error with operation=security-reload and reason=unexpected-exit; restart its owner to restore refresh. The last valid configuration and signing-key expiry retain their existing authority. Deliberately dropping the owner is not a failure alert.

Server configuration

Lease TTL compatibility

Both /v1/leases/acquire and /v1/leases/consolidate accept positive whole seconds as before ("ttl_seconds": 60). A fractional or wider duration uses an exact Jiff duration string with a zero compatibility sentinel, for example "ttl_seconds": 0, "ttl": "PT0.5S". A non-null ttl requires the sentinel to be zero; two nonzero declarations are refused with 422 invalid-ttl, even when they express the same duration. Malformed fields return invalid-json. The server's allocator continues to apply its configured maximum TTL and supplies the authoritative expiry in its response.

Upgrade every control-plane server before enabling fractional or greater-than- u32::MAX-second TTLs in HTTP clients. Whole-second clients remain compatible throughout the rollout. An older server ignores ttl and rejects the zero sentinel with invalid-ttl, so a mixed deployment cannot silently grant a different lifetime. Before rolling servers back, stop clients from issuing the precise form; otherwise those lease operations refuse until compatible servers return. Existing grant responses are unchanged. PostgreSQL's durable nanosecond timing requires the coordinated migration 0017 upgrade described in Lease timing; that storage upgrade has its own compatibility fence and must precede resuming lease operations on the new backend.

Rust callers constructing AcquireRequest or ConsolidateRequest must replace the ttl_seconds member with ttl: LeaseTtl::try_from(duration)?. This is a Rust DTO source break. HttpStore's public allocator signatures and valid runtime configuration remain unchanged; nonpositive durations return InvalidTtl before HTTP I/O. The invalid-ttl code remains stable; its title says that a TTL must specify one positive duration.

Security manifest

Set TOLLGATE_SECURITY_CONFIG to a JSON manifest. There is no default credential, including on loopback. Relative paths resolve against the manifest's directory. Unknown fields, duplicate credential mappings, malformed credentials, and invalid TLS material reject the initial configuration. Failed reloads preserve the last valid generation.

{
  "tls": {
    "certificate": "server-chain.pem",
    "private_key": "server-key.pem",
    "client_ca": "instance-ca.pem"
  },
  "bearers": [
    {"identity": "deployment-operator", "role": "operator", "token_file": "operator.token"},
    {"identity": "signup-service", "role": "provisioner", "token_file": "signup.token",
     "max_budget_allowance": 100000, "allowed_policy_templates": ["standard"]}
  ],
  "certificates": [
    {"identity": "instance-service", "role": "instance", "certificate": "instance-leaf.pem"}
  ],
  "google": {
    "audience": "https://tollgate.example.net",
    "subjects": [
      {"subject": "123456789012345678901", "identity": "pricing-api", "role": "instance"}
    ]
  },
  "issuer": {"secret_file": "issuer.secret"},
  "policy_templates": {
    "standard": {
      "cost_table": {"fixed_request": 1, "minimum_charge": 1, "weights": [1]},
      "limits": {"max_items_per_request": 100, "rate_units_per_second": 1000,
                 "rate_burst_units": 1000},
      "permissions": 1
    }
  }
}

The subject above is illustrative; replace it with the service account's numeric unique ID. google, tls, client_ca and issuer are optional; bearers and certificates default to empty lists. An empty role map intentionally denies all protected operations. Keep the TLS block when withdrawing all identities from an encrypted listener.

Use separate instance, operator and provisioner identities. Roles are disjoint:

Give an internet-facing account service a provisioner, never an operator. A provisioner creates only unfunded, suspended, best-effort accounts; activates them; sets budgets up to its max_budget_allowance; and manages credentials and strict key snapshots — all on accounts a provisioner created. It cannot deposit, suspend, close, grant Assured, publish a principal snapshot, reach an account an operator created, or lift a status an operator set. Compromising it therefore cannot fund an account or undo an abuse suspension. Keep operator for people and trusted tooling.

max_budget_allowance and a nonempty allowed_policy_templates list are required on every provisioner bearer, certificate or Google subject entry. Both fields are refused on other roles. Names resolve in the manifest's policy_templates map; a missing name, missing/empty allowlist or invalid template rejects startup. Failed reloads retain the last valid generation.

A provisioner's key snapshot must match one complete approved template's cost_table, limits, permissions and policy_revision. Revision defaults to the unstated value when omitted. Equality compares the typed values, including every operation weight/permission and legacy rate fallback; JSON object order is irrelevant. Templates cannot be combined field by field. Strict enforcement remains mandatory. A mismatched snapshot receives audited 403 scope-forbidden before any store read or write. Operators remain unrestricted by these templates.

Templates exclude account/key binding, status, capacity class, valid_until, generation and budget. Existing store checks own binding/status/class; provisioner generations and budget views are assigned by the store. The provisioner chooses snapshot validity. Template changes are part of the normal atomic security-generation reload and constrain requests authenticated after installation. Already authenticated requests retain their captured generation; already published snapshots remain valid until expiry, replacement or withdrawal. Revoke or replace existing snapshots separately when withdrawing an entitlement; changing an allowlist is not retroactive revocation.

For an existing provisioner deployment, stage the templates and identity allowlists before starting the upgraded server; there is no allow-all fallback or database migration. Replace/drain every old server before resuming provisioner traffic. An old binary rejects the new manifest and can retain its previous permissive generation on reload, so a mixed fleet does not enforce this restriction uniformly. Instance/operator-only manifests are unchanged. Library embedders pass the approved policies to the now-fallible ProvisionerLimits::new; an empty set cannot create an identity.

A provisioner reaches only accounts whose origin is Provisioner. Every account that existed before the role did is an operator's, so a signup service moved from an operator credential to a provisioner cannot administer the accounts it created under the old credential. Keep administering those with operator tooling, or re-create them through the provisioner.

GET /keys serves customer credential digests from the store's KeyDirectory. That key space is separate from this server's control-plane bearer credentials, which are loaded from the security manifest into their own HmacRegistry. The route sends neither customer secrets nor the HMAC secret already held by a customer verifier. See credential projection for paging, clock, freshness and rollout contracts.

Static credential files contain 32–16,377 visible ASCII bytes; a trailing newline is accepted. Generate at least 256 random bits and store them using a secret manager or protected mounted file. Only HMAC digests remain in the loaded static verifier. Identities are non-secret audit names, limited to 128 ASCII identifier characters. Raw tokens, authorization headers, private keys, and JWT bodies are not logged. Snapshot publication logs the affected principal at debug, so do not run RUST_LOG=debug in production: principals are digest material that no administrative response or audit event discloses.

Credential issuer

The optional issuer entry lets this server mint customer credentials: POST /admin/accounts/{id}/keys answers 501 issuance-unsupported without it. See account administration for the routes.

• Format. The file holds exactly 64 lowercase hexadecimal characters, with one optional trailing newline (openssl rand -hex 32). Anything else, including uppercase, rejects the configuration.
• The HMAC key is those 64 characters as bytes, not their decoded value. Give every verifier (tollgate_client::KeyManager::spawn) the same 64 characters without the newline, so one stored value configures both sides. Uppercase is refused because under this rule it would be a different key.
• Distinct authority. The issuer secret must differ from every bearer token in the manifest; a match rejects the configuration. It is unrelated to the per-start registry that verifies control-plane bearers.
• Fixed for the process lifetime. The issuer is read when the server starts. A reload whose manifest names a different issuer — changed, added or removed — still applies TLS, bearer, certificate and Google changes, keeps the running issuer, and logs reason="issuer-change-requires-restart" once per distinct staged value. An invalid issuer file fails the reload like any other malformed file, and the previous generation stays live.
• Neither the secret nor anything derived from it is logged, returned or audited.

Rotating the issuer secret invalidates every credential issued under the old one, because a credential verifies only under the secret that minted it and a verifier holds exactly one (see credential projection). There is no multi-secret overlap. To rotate: write the new secret, restart the server, restart every verifier with the same new value, then re-issue each account's credentials and revoke the old ones. Plan the rotation as a credential reissue, not a transparent reload.

The server accepts a single Authorization: Bearer … header, bounded to 16 KiB. Bearer verification uses tollgate-auth::CredentialVerifier. The configured role map authorizes the verified principal. Invalid, missing, expired, or conflicting credentials return RFC-7807 401 authentication-required with a Bearer challenge; valid identities without the required role return 403 scope-forbidden, and the refusal is written to the audit log. These checks precede path/body decoding and store calls. Existing JSON errors and wire DTOs retain their meanings.

TLS uses rustls with safe protocol defaults. TOLLGATE_BIND defaults to 127.0.0.1:8080; a non-loopback bound address requires TLS and fails startup without it. Network restriction alone does not permit remote plaintext. The library serve function enforces the same rule. Embedders must use this listener entry point; the standalone router is useful for in-process tests and cannot validate an external listener it does not own. Its /readyz returns 503 because it has no maintenance owner; /livez and authenticated API handlers still work.

An optional client CA requests and verifies client certificates while allowing bearer-only callers and probes. A trusted certificate also needs an exact leaf SHA-256 fingerprint mapping to gain authority; the manifest derives that fingerprint from the configured leaf PEM. HTTP headers such as X-Forwarded-Client-Cert never create an identity. If bearer and certificate credentials are both supplied, they must resolve to the same name, role and provisioner ceiling.

TLS handshakes run concurrently, with at most 128 pending tasks and a five-second deadline each. Excess connections wait in the OS backlog. Library embedders may set these bounds with TlsConfig::with_handshake_limits; the binary uses the defaults. Dropping the listener aborts pending handshakes. SIGTERM and Ctrl-C start graceful HTTP shutdown; cancelling the server also aborts its maintenance task. This does not introduce a total deadline for all server HTTP requests. The caller's shutdown future remains owned by serve. Cancellation or task failure also releases its internal signal waiter and tells existing connections to shut down.

Maintenance readiness and recovery

serve starts maintenance immediately. /readyz stays 503 until both the reclaim and budget-rollover passes reach a partial batch successfully, and returns 200 only while their latest outcomes are successful, the task is alive and the store answers ping. A failed pass withdraws readiness immediately, even if the other pass succeeds. Successful recovery of the failed operation restores its own health; /livez remains 200 while the service can run. The handlers continue to return their normal domain results while maintenance retries on its existing cadence. No partial batch or failed call is treated as proof of rollback.

Each operation logs its first two consecutive failures at warn, the third and subsequent failures at error. Monitor operation (reclaim or budget-rollover) and consecutive_failures; one info event reports after_failures on recovery. The three-attempt threshold is an alerting policy, not proof that a particular lease TTL has expired. Inspect backend permissions, connectivity and transaction health; successful ping alone does not prove that maintenance writes can run. Completed progress fields survive a later failed batch. No backend details are formatted into these events.

A successful sweep that settled leases logs leases, forfeited_units and batches. A swept lease is one its holder never released, so its remainder is forfeited as settlement loss rather than returned to the account (GL-136). The event is warn when forfeited_units is non-zero: an instance crashed, or its shutdown's release deadline lapsed. Late usage for a forfeited lease is still billed against the forfeit. The failure events carry forfeited_units for the batches that committed.

An unexpected maintenance return, cancellation or unwinding panic emits an error with operation=maintenance and a static reason, then serve returns an I/O error and stops listening. Process supervision should restart it. A build using panic=abort terminates the process immediately on panic; it cannot emit the unwind supervisor's event. Graceful shutdown withdraws readiness before cancelling maintenance, and expected cancellation is not a task-failure alert. Pending store calls may have committed effects even when cancelled; reconcile with backend records rather than inferring rollback from shutdown.

This health policy observes completed outcomes and task liveness. It adds no timeout or cancellation deadline to a backend call that remains pending, and it does not certify that SKIP LOCKED left no rows with another replica. Backend futures must yield to the executor for task supervision and cancellation to run.

There are no Rust signature, database or wire-schema changes. Readiness is intentionally stricter: deployments should allow initial maintenance to complete before routing traffic. Embedders using the bare router for a listener must move to serve; their probe now stays 503 instead of claiming health without an owned worker. Existing TOLLGATE_RECLAIM_INTERVAL_SECS retains its scheduling meaning. Zero or a duration that cannot fit the monotonic clock is rejected before starting tasks. Rolling back restores the old false-ready behavior.

Instance shutdown accounting

The instance runtime has the same allocation boundary. A successful InstanceRuntime::shutdown can leave a grant whose acquire or consolidation result never reached the manager. Its known leases can all be released while that unanswered capability still holds units in the backend. Retain a RuntimeHandle and inspect report().uncertain_acquires and account_reports(now) after the join, alongside the shutdown report's abandoned leases, task failures and usage-drain counters. Uncertainty is a count of possible grants, not a unit amount or proof that each call committed. Such units remain in active grants until server maintenance sweeps them after expiry and grace, when they are forfeited as settlement loss rather than returned (GL-136). Do not credit them manually: nobody can prove them unspent. Nor should you classify the liquidity difference alone as lost billing, because late usage for the lease still bills against the forfeit. Reconcile recorded usage and ledger conservation both before and after reclamation. Expiry does not erase the runtime's historical counters.

Instance clients and Google service-account identity

HttpStore::with_config validates its URL, credentials, TLS roots and deadlines before construction. HTTPS verifies the server certificate and host name. A custom root_ca_pem replaces public trust roots; identity_pem contains the client certificate chain followed by its private key. StaticBearer supplies a rotatable token. HttpStoreConfig defaults to a two-second connection deadline and a ten-second total request deadline, including credential retrieval and response reading. Redirects and environment proxies are disabled. Plain HTTP is accepted only for literal loopback addresses or localhost, which is pinned to loopback rather than resolved through DNS. URL userinfo, queries and fragments are refused.

Instances running on Google Cloud can use their attached service account, through the platform's metadata server, without distributing per-replica secrets:

use tollgate_client::{GoogleIdentity, HttpStore, HttpStoreConfig};

let identity = GoogleIdentity::new("https://tollgate.example.net")?;
let store = HttpStore::with_config("https://tollgate.example.net", HttpStoreConfig {
    bearer: Some(identity),
    ..Default::default()
})?;

The provider obtains a Google ID token from the fixed metadata identity endpoint with the configured audience and Metadata-Flavor: Google. It caches tokens for 60 seconds and bounds metadata requests to five seconds and 16 KiB. The server accepts only RS256 signatures under Google's published keys, Google issuer names, the exact configured audience, a nonempty subject, and unexpired verified evidence. Authorization uses sub, not a mutable email claim. This is service-account identity support; customer login, arbitrary OIDC issuers and user directories are outside this API. Replicas sharing a service account share one identity and revocation scope.

The server fetches Google signing keys off the handler path. Their usability is bounded by the issuer's Cache-Control/Age policy and at most one hour after fetch; absent cache metadata defaults to five minutes. Refresh is attempted at half the remaining lifetime, between five seconds and five minutes. Fetch or validation failures retain the preceding keys with their original expiry and never extend identity validity. Expired or unknown keys fail closed until a valid refresh succeeds. Internet access to Google's signing-key endpoint and accurate server time are deployment prerequisites for this mode.

The supported topology has clients connecting over TLS to a directly encrypted server endpoint, with PostgreSQL behind the server. The server must therefore run where it can expose its own TLS listener. A platform front end that terminates TLS and forwards plaintext is not an exemption from the non-loopback plaintext rule; this feature does not provide a forwarded-identity or trusted-proxy bypass.

References: Google ID tokens for service accounts, Google ID token validation and key caching.

Rotation and revocation

1. Write new versioned credential/certificate files and validate them. For CA changes, allow both old and new CAs and certificate identities during overlap.
2. Atomically replace the manifest only after all referenced files exist. The owned SecurityReloader checks every five seconds, stages the complete set, then publishes verification, role mapping and TLS as one immutable generation.
3. Rotate client bearers with StaticBearer::replace, or roots, mTLS identity and bearer provider together with HttpStore::reconfigure. Existing managers keep the same Arc<HttpStore>; new calls use the replacement. Invalid replacements preserve the working transport. Embedders own client file watching.
4. Remove retired mappings/roots after clients have moved. Monitor rejected calls and reload warnings. StaticBearer::revoke prevents subsequent client calls from silently becoming anonymous.

New requests, including those on keep-alive connections, use the current role map and recheck a presented certificate against the current CA and verification time. Requests already authorized retain their pinned generation. New TLS handshakes use the configuration current at connection acceptance. Existing TLS connections do not renegotiate the server certificate; clients needing immediate server-trust withdrawal must replace their transport. Enabling or disabling TLS requires a listener restart, so a reload cannot expose an encrypted service as plaintext. Changing the credential issuer requires a server restart; a reload defers it without blocking the rest (see credential issuer).

Usage ingestion treats authentication failures as retryable. Rotation can pause billing delivery but must not turn a valid usage batch into a terminal refusal. Existing writer buffering, backpressure and shutdown bounds still apply; a long credential outage eventually denies admissions rather than losing usage silently.

Backend failures and diagnostics

Backend errors carry arbitrary text. The server does not expose that text in HTTP bodies, ApiError debug output or its backend-failure logs. Public storage failures use 503 / storage / backend unavailable; permanent usage refusals use 422 / usage-refused / usage batch refused. Existing domain codes, generation responses and retry decisions are preserved. Credential-page failures retain their existing credential-source-unavailable code and title.

HTTP problem responses with 5xx or usage-refused add an optional error_id containing 32 lowercase hexadecimal digits. Find the matching warning on tollgate::diagnostics to identify the route template, status and code. The server generates this ID; request headers cannot choose it. It is diagnostic context, not authorization evidence. If system entropy is unavailable, the failure keeps its original status, omits the ID and logs error_id_unavailable=true.

Retain this target at warn or above, for example with RUST_LOG=info,tollgate::diagnostics=warn. Library embedders own subscriber installation and log delivery. Correlation is limited by that delivery; it is not a durable record across process death. Problem's public Rust shape is unchanged, and existing clients ignore the additive JSON field. HTTP consumers that need the correlation ID can read error_id from the response object.

Readiness retains its empty 200/503 response and logs failures by operation. Maintenance logs retain static operation codes and completed progress counters; PostgreSQL startup logs identify initialization failure and the configuration to check. Neither connection strings nor driver text are logged. Inspect connectivity, backend health, migration status and appropriately protected backend operational records using the incident's time and operation. An error does not prove rollback: administrative audit receipts remain the authority for confirmed writes, and ambiguous failures need reconciliation.

This change requires no schema or configuration migration and preserves the public Rust error types. Deploying the server updates the public titles and adds the optional field. Consumers must classify errors by status/code, not by parsing the old backend-specific title. A rollback to an older server restores the disclosure defect.

Administrative audit

Every HTTP administrative operation reaching the store emits structured tollgate::audit events with a random operation ID, stable actor, role, action, resource and server time. started precedes the store call. confirmed carries the backend's typed AdminReceipt: before/after values captured under the memory lock or inside the PostgreSQL transaction that serialized the mutation. It never substitutes a separate read that could describe somebody else's concurrent write.

Receipts identify changed fields: creation balance/status/class/origin, deposited and top-up totals, status and the authority that set it, capacity class, or snapshot generation plus revocation state. The resource identifies the account or principal. Snapshot receipts name the immutable publication generation; they do not copy its full policy graph. No-op operations report equal states. failed carries a stable code/status; cancelled_unknown marks an interrupted operation. Neither invents a before/after pair or asserts that a storage error ruled out a commit. Unmatched started events after a process crash also require reconciliation.

A request refused for its scope emits one refused event and no started, because it never reaches the store. It carries the actor, role, action, resource, time and code. A credential on a route its role does not reach is refused by the router: its action is the method and route template (POST /v1/admin/accounts/{account}/deposit) and its code scope-forbidden. A provisioner refused for an argument or an account is refused by the handler: its action is the operation name (create_account) and its code scope-forbidden or account-not-provisioned, with a reason. An operator hold is found inside the store transaction, so it is a failed event with code operator-hold. Alert on refused events from a provisioner: a signup service that asks for a deposit is not behaving like one.

The binary keeps audit events enabled even with RUST_LOG=error; library embedders must install a subscriber that retains this target. Route these events to the deployment's retained, access-controlled audit log and alert on delivery failures. This is structured audit logging, not a durable transaction outbox: process death or logging infrastructure failure can lose delivery after a commit. No database migration or audit table is introduced. Direct AdminStore callers receive receipts but remain responsible for attaching identity and persisting their own audit record.

Rollout and local development

This is an intentional Rust/configuration API break in unpublished crates: ServerState requires security, HttpStore constructors return Result, and six HTTP-facing AdminStore mutations return AdminReceipt<T> (read .outcome for the previous result). Custom backends must capture receipts at their serialization point. Wire payloads, existing domain error codes, and database schemas are unchanged; 401/403 authentication codes are additive.

Bring up a secure endpoint against the existing PostgreSQL backend, configure instance identity and TLS, then deploy clients using the new configuration. Keep overlapping identities during rotation and remove the old endpoint once clients have moved. Rollback must preserve an authenticated TLS endpoint; reverting to an older unauthenticated server on a public listener is not a compatible rollback. No schema rollback is required.

For a disposable loopback demonstration only:

mkdir -m 700 .local-control
printf '%s\n' 'demo-only-operator-token-do-not-deploy-98' > .local-control/operator.token
printf '%s\n' '{"bearers":[{"identity":"demo-operator","role":"operator","token_file":"operator.token"}]}' > .local-control/security.json
chmod 600 .local-control/*
TOLLGATE_SECURITY_CONFIG="$PWD/.local-control/security.json" cargo run -p tollgate-server

This uses the ephemeral memory backend and grants no instance role. Supply an independent instance credential to exercise HttpStore, or run the generated TLS/bearer/mTLS fixtures in cargo test -p tollgate-server. Keep local security material out of version control. --help and --version work without secrets or database configuration; -- ends option processing.

HTTP API reference

The control-plane HTTP API that tollgate-server serves: every route, the role that may call it, its request and response bodies, and the problem codes it can return. Instances reach it through HttpStore in tollgate-client; operators and application backends call the administrative routes directly.

The router is router_with_maintenance in crates/tollgate-server/src/lib.rs. The request and response types are the wire DTOs in crates/tollgate-store/src/wire.rs, plus the store and core types they embed. Every problem code is described in the error reference.

Transport and authentication

The control-plane security runbook is the authority for deployment; this is a summary.

• TLS off loopback. The server refuses to start a plaintext listener on a non-loopback address. TLS is terminated by the server itself.
• Three kinds of evidence. A request authenticates with a client certificate verified by mutual TLS, a static bearer token (Authorization: Bearer <token>), or a Google service-account ID token presented as a bearer. The security manifest maps each certificate fingerprint, token file or token subject to a named identity with one role. A request that presents both a certificate and a bearer must resolve both to the same identity.
• Three disjoint roles. instance calls the lease, snapshot, credential-feed and usage routes. operator calls everything under /v1/admin. provisioner calls the self-service subset of /v1/admin — every account route except deposit, and no principal-snapshot route — and only with the arguments and on the accounts its scope allows. A credential on a route its role does not reach answers 403 scope-forbidden, and the refusal is audited.
• Probes are open. /livez and /readyz take no credential.

Missing, malformed, unverifiable or expired evidence answers 401 authentication-required with WWW-Authenticate: Bearer realm="tollgate-control". Evidence that verifies but maps to no identity, or to an identity whose role the route does not admit, answers 403 scope-forbidden. Authorization runs before the body or path is decoded, so an unauthenticated request never reaches validation.

Conventions

• Prefix. Every route except the probes is under /v1 (API_PREFIX in wire.rs).

• Identifiers. Every 128-bit identifier — account_id, lease_id, key_id, request_id, a principal — is exactly 32 lowercase hexadecimal characters, in JSON strings and in path segments. A path segment in any other form answers 400 invalid-id.

• Units. CostUnits and fencing tokens are JSON integers. Timestamps are RFC 3339 strings.

• Bodies. Requests are application/json. Every error is an RFC 7807 application/problem+json body with a stable machine code:

  {"status": 409, "code": "insufficient-balance",
   "title": "insufficient balance (5 units remain, all held in leases)",
   "balance_shortfall": {"remaining": 5, "period_end": null}}
  

  status, code and title are always present. generation, balance_exhaustion, balance_shortfall and error_id appear only where the error reference says. Classify by status and code; the title is for people.

• Body limits. POST /v1/usage/ingest accepts bodies up to 2 MiB (MAX_INGEST_BODY_BYTES), both snapshot PUT routes up to 4 MiB (MAX_SNAPSHOT_BODY_BYTES), and every other route axum's 2 MiB default. A larger body answers 413 batch-too-large.

• Common errors. Every protected route can answer 401 authentication-required, 403 scope-forbidden and 503 storage. Every route with a JSON body can answer invalid-json and 413 batch-too-large; every route with a path identifier can answer 400 invalid-id. The per-route lists below name only the codes particular to each route.

• Unmatched requests. A path the router does not serve answers 404, and a method it does not serve on a known path answers 405, both with an empty body rather than a problem.

Routes

The table is checked against the router by tollgate-repo-check (src/http_routes.rs): a route added, removed or re-roled without updating it fails the build.

A provisioner's argument and account limits are listed under the provisioner scope.

Probes

GET /livez

200 with an empty body while the process can serve HTTP. No role.

GET /readyz

200 with an empty body when the store answers ping and the server's maintenance task is healthy: both the reclaim and the budget-rollover passes have completed and their latest outcomes succeeded. Otherwise 503 with an empty body. No role. A router built with tollgate_server::router rather than serve has no maintenance task and always answers 503. See maintenance readiness and recovery.

Leases

The lease lifecycle. Semantics are LeaseAllocator's in crates/tollgate-store/src/traits.rs; the concepts page introduces them.

POST /v1/leases/acquire

Role instance. Debit a grant from the account's balance.

Request AcquireRequest. requested is a ceiling: the backend's grant policy may grant less. The TTL is ttl_seconds (whole seconds), or ttl_seconds: 0 with an exact duration string in ttl; see lease TTL compatibility.

{"account_id": "…32 hex…", "requested": 1000, "ttl_seconds": 60}

200 with AcquireResponse (an Allocation): the LeaseGrant fields, and funding, the ledger's remaining funding after the grant, when the backend attests it.

{"lease_id": "…", "account_id": "…", "fencing_token": 7, "units": 1000,
 "expires_at": "2026-09-28T12:01:00Z",
 "funding": {"remaining": 4000, "period_end": null}}

Errors: 404 unknown-account, 409 account-inactive, 409 insufficient-balance, 409 balance-exhausted, 422 invalid-ttl.

POST /v1/leases/release

Role instance. Return a lease's unspent units and close it.

Request ReleaseRequest:

{"lease_id": "…", "fencing_token": 7, "unspent": 120}

204 with no body.

Errors: 404 unknown-lease, 409 fenced, 409 lease-not-active, 422 invalid-release.

POST /v1/leases/consolidate

Role instance. Return an active lease's unspent units and re-grant against the restored balance, in one backend transaction. The new grant is for the account the returned lease names.

Request ConsolidateRequest: the release half (lease_id, fencing_token, unspent), the grant half (requested, and the TTL fields as for acquire), and needed, the largest quote the returned lease refused. needed is omitted when zero, and reads as zero when absent.

{"lease_id": "…", "fencing_token": 7, "unspent": 30, "requested": 1000,
 "needed": 51, "ttl_seconds": 60}

200 with ConsolidateResponse (an Allocation, as for acquire).

Errors: every acquire and release code above. A domain refusal leaves the original lease unchanged; 503 storage leaves the outcome unknown, and the caller must not resume spending from the old lease.

POST /v1/leases/reclaim

Role instance. Settle every lease whose TTL and reclaim grace have lapsed, exactly as the server's own maintenance sweep does. No request body.

200 with a JSON array of ReclaimedLease. forfeited is recorded as settlement loss, not credited back.

[{"lease_id": "…", "account_id": "…", "forfeited": 880}]

Errors: only the common ones. A 503 storage after some batches committed leaves those batches committed.

Snapshots

GET /v1/snapshots

Role instance. The principal catalogue, revoked principals included.

200 with PrincipalsResponse:

{"principals": ["…32 hex…", "…32 hex…"]}

Errors: 501 enumeration-unsupported when the backend cannot enumerate principals. That is not an empty catalogue.

GET /v1/snapshots/{principal}

Role instance. One principal's compiled snapshot.

200 with the whole AccountSnapshot, cost table included. Its fields are defined in crates/tollgate-core/src/snapshot.rs.

Errors: 404 unknown-principal when no snapshot was ever published; 410 revoked-principal, with the tombstone's generation, when it was withdrawn.

Credential feed

GET /v1/keys

Role instance. One page of active customer credential digests, for instance verifiers. Query: after, an exclusive key-ID cursor, and limit, 1–4096 (default 256). The response carries Cache-Control: no-store.

200 with KeysResponse:

{"revision": 12, "as_of": "2026-09-09T12:00:00Z",
 "keys": [{"key_id": "…", "principal": "…", "digest": "…64 hex…",
           "not_after": null}],
 "next_after": null}

Errors: 400 invalid-query, 422 invalid-limit, 503 credential-source-unavailable in place of storage. The credential projection page states the paging and revision contract.

Usage

POST /v1/usage/ingest

Role instance. Record a batch of committed usage events, idempotently by request_id. A batch holds at most 4096 events (MAX_INGEST_BATCH), within a 2 MiB body.

Request IngestRequest:

{"events": [{"request_id": "…", "account_id": "…",
             "source": {"Leased": {"lease_id": "…", "fencing_token": 7}},
             "units": 64, "occurred_at": "2026-09-28T12:00:00Z",
             "policy_revision": "…64 hex…", "key_id": "…"}]}

source is {"Leased": {…}} for units spent from a lease, or "Overage" for units admitted under elastic enforcement without one. policy_revision and key_id may be omitted.

200 with an IngestReport. accepted + duplicate + rejected equals the number of events sent. unattributed counts newly accepted events whose key attribution was absent, unknown or for another account; it is null from a sink that does not report attribution.

{"accepted": 63, "duplicate": 1, "rejected": 0, "unattributed": 0}

Errors: 422 usage-refused when the store examined the batch and will refuse it again unchanged; 413 batch-too-large. See usage accounting for what rejected means for billing.

Account administration

Every route in this section admits operator; all but deposit also admit provisioner, within its scope. Mutations are audited with a receipt captured by the backend; see administrative audit. The account administration page is the provisioning guide these routes serve.

The provisioner scope

A provisioner credential is what an internet-facing signup service holds, so compromising it must not fund, close, grant Assured, or reach an account an operator made. Its limits are enforced before any write, and every refusal is written to the audit log with the actor, the role and the action.

Every route that names an account also requires that a provisioner created it. An account an operator created — every account that predates the role included — answers 403 account-not-provisioned, and one that does not exist answers 404 unknown-account. Activation additionally answers 403 operator-hold when an operator set the account's current status: an operator's suspension holds until an operator lifts it. The account's origin and status_set_by report both facts.

A provisioner's snapshot must match one complete operator-approved template from its identity's allowed_policy_templates in the security manifest: cost_table, limits, permissions and policy_revision are compared exactly as typed values. Strict enforcement is mandatory. Mismatches return audited 403 scope-forbidden before any store call. Account/key binding and status/class remain subject to the existing store checks; the caller chooses valid_until, and the store owns generations and budget views. Templates do not revoke previously published snapshots. See the security manifest for configuration, reload semantics and the fail-closed rollout.

POST /v1/admin/accounts

Create an account. An operator's is always Assured; a provisioner's is always BestEffort, unfunded and suspended.

Request CreateAccountRequest:

{"account_id": "…", "initial_balance": 0, "status": "Suspended"}

201 with no body. Errors: 409 account-exists, and for a provisioner 403 scope-forbidden.

GET /v1/admin/accounts/{account}

One account's administrative state and funding position, read from one consistent backend snapshot as of as_of.

200 with AccountResponse:

{"account_id": "…", "as_of": "…", "status": "Active",
 "capacity_class": "Assured", "origin": "Operator", "status_set_by": "Operator",
 "budget": null, "period_start": "…",
 "balance": 600, "outstanding_lease_grants": 400, "settled_usage": 0,
 "expired_allowance": 0, "settlement_loss": 0, "deposited": 1000,
 "overage_recorded": 0}

origin is the authority that created the account, Operator or Provisioner, and never changes. status_set_by is the authority that set the current status. A client reading a server that predates them sees Operator for both.

Errors: 404 unknown-account; for a provisioner, 403 account-not-provisioned.

PUT /v1/admin/accounts/{account}/budget

Set or clear the periodic allowance. The budget field is required; null clears the schedule.

Request SetBudgetRequest:

{"budget": {"allowance": 500, "period": "UtcCalendarMonth", "rollover": "None"}}

200 with SetBudgetResponse, the schedule the call replaced and the one now in force; equal values mean the call changed nothing.

{"previous": null, "current": {"allowance": 500, "period": "UtcCalendarMonth", "rollover": "None"}}

Errors: 404 unknown-account; for a provisioner, 403 scope-forbidden above its ceiling and 403 account-not-provisioned. An absent budget field or an unknown field is 422 invalid-json.

POST /v1/admin/accounts/{account}/deposit

Role operator only. Add units to the account's balance once, as a top-up that survives period boundaries.

Request DepositRequest: {"units": 1000}. 204 with no body.

Errors: 400 zero-deposit, 404 unknown-account. A deposit that would overflow the account's balance or deposited total is refused as 422 balance-overflow and changes nothing. An amount outside the backend's unit domain is refused the same way (u64 for memory, nonnegative BIGINT through i64::MAX for PostgreSQL). Never retry the unchanged request. Backend outages remain 503 storage.

POST /v1/admin/accounts/{account}/status

Set the account's status and republish every live snapshot of the account with it.

Request SetStatusRequest: {"status": "Active"} — Active, Suspended or Closed.

200 with SetStatusResponse: republished is the number of live snapshots rewritten; unreadable is the number of stored rows that changed but could not be decoded to push, which converge at their next refresh.

{"republished": 2, "unreadable": 0}

An operator's status is recorded as an operator hold: a provisioner cannot change it.

Errors: 404 unknown-account, 409 account-closed; for a provisioner, 403 scope-forbidden for anything but Active, 403 account-not-provisioned and 403 operator-hold.

POST /v1/admin/accounts/{account}/capacity-class

Set the account's execution-capacity class and republish its live snapshots.

Request SetCapacityClassRequest: {"capacity_class": "BestEffort"} — Assured or BestEffort. 200 with SetStatusResponse, as for status.

Errors: 404 unknown-account, 409 account-closed; for a provisioner, 403 scope-forbidden for Assured and 403 account-not-provisioned.

Credential administration

POST /v1/admin/accounts/{account}/keys

Roles operator and provisioner. Issue a credential. The response is the only time its secret is disclosed.

Request IssueKeyRequest. The caller chooses key_id; max_active_keys is the caller's bound on the account's live credentials; not_after is optional.

{"key_id": "…", "max_active_keys": 3, "not_after": "2027-01-01T00:00:00Z"}

201 with IssuedKeyResponse:

{"key_id": "…", "secret": "…64 hex…", "not_after": "2027-01-01T00:00:00Z"}

Errors: 404 unknown-account, 409 credential-exists, 409 active-key-limit, 501 issuance-unsupported when the server has no credential issuer, 503 entropy-unavailable, 500 issuer-misconfigured; for a provisioner, 404 unknown-account and 403 account-not-provisioned, checked before anything is minted.

GET /v1/admin/accounts/{account}/keys

Roles operator and provisioner. One page of the account's credentials, revoked and expired ones included: metadata only, never a secret, digest or principal. Query: after and limit, as for GET /v1/keys. An existing account with no matching credentials answers an empty page. An unknown account returns 404 unknown-account; existence and the page are read in one store operation.

200 with AccountKeysResponse, whose entries are AccountKeyResponse. next_after is null on the last page.

{"as_of": "…", "keys": [{"key_id": "…", "not_after": null,
  "revoked_at": null, "live": true}], "next_after": null}

Errors: 400 invalid-query, 422 invalid-limit, 404 unknown-account; for a provisioner, 403 account-not-provisioned.

DELETE /v1/admin/accounts/{account}/keys/{key}

Roles operator and provisioner. Revoke one of the account's credentials. Revocation leaves its bound snapshot in place; withdraw that with the DELETE below.

200 with RevokeKeyResponse. retired: false means it was already revoked.

{"key_id": "…", "retired": true}

Errors: 404 unknown-credential, including for another account's key; for a provisioner, 404 unknown-account and 403 account-not-provisioned.

PUT /v1/admin/accounts/{account}/keys/{key}/snapshot

Roles operator and provisioner. Publish the snapshot one credential authorizes against. The server resolves the principal from its own key record, and fills in the snapshot's key_id when it is unset.

Request PublishSnapshotRequest: {"snapshot": { … }}, an AccountSnapshot. 204 with no body. For an operator, a generation at or below the stored one changes nothing and still answers 204.

For a provisioner, the submitted generation is ignored. The store assigns 1 on first publication, then the stored live snapshot or tombstone's generation plus one, atomically with publication. Repeats receive a fresh generation; concurrent writes are ordered by the store, so a retry can replace a newer policy. Serialize policy updates per key when their order matters. The audit receipt records the allocated generation. Arbitrary caller-selected jumps cannot exhaust the counter and obstruct operator suspension, closure or capacity-class changes. Exhaustion of the stored counter returns 503 storage without a publication; the generation never wraps or resets.

Errors: 404 unknown-credential, 409 credential-retired, 422 invalid-credential-binding, 422 invalid-snapshot-limits, 409 snapshot-status-mismatch, 409 snapshot-capacity-class-mismatch; for a provisioner, 403 scope-forbidden for a snapshot outside its approved templates (including Elastic enforcement), 404 unknown-account and 403 account-not-provisioned.

DELETE /v1/admin/accounts/{account}/keys/{key}/snapshot

Roles operator and provisioner. Withdraw the snapshot bound to one credential, revoked or not. 204 with no body.

Errors: 404 unknown-credential; for a provisioner, 404 unknown-account and 403 account-not-provisioned.

Principal snapshots

For embedders that derive principals themselves. The key-bound routes above are the supported path for credentials this server issues.

PUT /v1/admin/snapshots/{principal}

Role operator only. Publish a principal's snapshot, generation-monotonically.

Request PublishSnapshotRequest. 204 with no body.

Errors: 422 invalid-snapshot-limits, 422 invalid-credential-binding when the snapshot names a key_id that does not bind this principal and account, 409 snapshot-status-mismatch, 409 snapshot-capacity-class-mismatch.

DELETE /v1/admin/snapshots/{principal}

Role operator. Withdraw a principal's snapshot, replacing it with a tombstone at the same generation, which instances observe as 410 revoked-principal. 204 with no body. A principal with no live snapshot is left unchanged and also answers 204.

Errors: only the common ones.

Error reference

Two vocabularies of refusal. The control plane answers HTTP requests with RFC 7807 problem bodies, each carrying a stable machine code. The request path refuses admission with a DenyReason, which never involves I/O and always charges zero units; how a service turns one into an HTTP response is its own choice.

Codes and reasons are contracts: tollgate-client's HTTP transport maps problem codes back to domain errors, and deny-reason labels name exported counters. An embedder can match on them.

The problem body

Every tollgate-server error is application/problem+json, built in crates/tollgate-server/src/error.rs from the Problem type in crates/tollgate-store/src/wire.rs:

A 401 also carries WWW-Authenticate: Bearer realm="tollgate-control".

There is no type member: the code is the problem type. Requests to a path or method the router does not serve get axum's plain 404 or 405 with an empty body, not a problem.

Problem codes

Every code the server can return. "Retry" means resending the same request. The HTTP API reference lists which routes return which codes.

Authentication and request shape

Leases

tollgate-client maps each of these to an AllocateError variant of the same name. See LeaseAllocator.

Snapshots and principals

Accounts and credentials

Usage and availability

tollgate-client treats an ingest answer of 401, 403, 408, 429 or any 5xx as retryable, and every other 4xx as a refusal it must not replay; see usage accounting.

Deny reasons

DenyReason, in crates/tollgate-core/src/deny.rs, is every reason admission can refuse a request. Each carries a Retry classification from DenyReason::retry, so every embedder gives the same advice for the same refusal:

• Transient — the same request can become admissible when capacity or freshness recovers, without a funding change.
• AfterInFlight — retry once a concurrent admission decision finishes publishing. The retry may then report transient capacity.
• Never — the same request cannot become admissible under the current policy and funding. New funding, a new budget period or a policy change can change that.

label is DenyReason::name, the metric label the reason is counted under (see the metrics reference).

The last column is the status and problem code that examples/pricing-api answers with, in its deny_response. That mapping is the example's own choice, not part of Tollgate's contract; another embedder may choose differently. It is recorded here because it is a worked answer to the question each reason poses.

The payload fields in braces are for the caller's response; they are not part of the label, so a label never mints a time series per value. The example renders DenyReason's Display text as the problem title and sends no Retry-After header: no reason carries a retry instant.

The concepts page introduces refusals, and embedding Tollgate states which parts of pricing-api are contract.

Metrics reference

Every counter, gauge and report field an operator reads from a running instance, where it comes from, and what a change in it means. The thresholds and the reasoning behind them are in the design record's Observability section; this page is the field-by-field reference and defers to that section, in particular Signals worth a response, for when to act.

The numbers come from these library surfaces:

All of them are per instance and since process start: nothing survives a restart, and a fleet view is the scraper's job to aggregate. Counters are cumulative, so read them as rates between two scrapes. Gauges (marked below) are the current value. None of these reads is consulted by an admission decision.

Units: requests, events, leases and the like are plain counts. Cost units are whole CostUnits, never a currency; converting to money is the application's job.

The pricing-api /metrics document

examples/pricing-api publishes these surfaces as one JSON document on GET /metrics. It is one way to expose them, not a product surface: an embedder chooses its own format. The field names are the example's and match the library names one for one, except where a table below says otherwise.

Every labelled map (denials, commit_refusals, input_rejections, refill.refusals, the _by_class maps) carries every label, zeros included, in a fixed order. A zero means "has not happened", never "this counter does not exist", and two scrapes diff cleanly.

Nested blocks are null when their plane is not running: accounting, refill, snapshots and contention are absent when admission is disabled, and capacity is absent when no execution-capacity gate is installed. Absent is the honest answer for a disabled plane; zeroes would read as an exhausted one.

Admission outcomes

From CountersSnapshot, plus the example's own input counters.

Execution outcomes

What became of every admitted request. execution_started, canceled_before_start, capacity_shed and refused_at_start partition admitted, so no reader has to infer one from a difference.

Capacity

From the execution-capacity gate's occupancy. Pool sizes and free counts only, never labelled by account. The free counts are live reads and therefore estimates.

Funding estimates

From RuntimeHandle::funding(now) (RuntimeFundingReport). Diagnostic estimates read off the request path.

Contention

From RuntimeReport::contention (ContentionReport). Admission exchanges — lease and overage debits and concurrency-gauge acquisitions — that lost a race to another core. Cumulative lower bounds; compare two scrapes.

accounting

From WriterHealth, the usage writer's live health.

The library's WriterStats (inside WriterHealth::stats) carries four more fields the example does not publish:

refill

From LeaseStats, summed over every account's lease manager. null when the runtime's aggregate overflowed, in which case counter_overflow is true.

The library's LeaseStats carries three more fields the example does not publish:

snapshots

From SnapshotStats. The snapshot operations guide covers the refusal fields and recovery procedure.

Deny-reason labels

denials has one label per DenyReason, in slot order. The label is DenyReason::name(); the meaning, retry advice and the example's HTTP status for each are in Errors.

unknown_principal, account_suspended, account_closed, snapshot_expired, missing_permission, request_too_large, unpriced_operation, rate_limited, request_rate_limited, concurrency_limited, unpriceable_under_limits, lease_unavailable, lease_expired, lease_exhausted, overage_cap_exhausted, cost_overflow, accounting_backpressure, overage_cap_temporarily_exhausted, overage_commit_in_progress, empty_workload, funding_expired_at_start, capacity_unavailable, balance_exhausted, balance_insufficient.

The labels most worth watching, and what their rise means, are in Signals worth a response: lease_exhausted with balance left is a refill problem, not enforcement; unknown_principal is either rotation or distribution, told apart by snapshots.unresolved; snapshot_expired is an outage failing closed; accounting_backpressure is a sink falling behind.

accounting_backpressure is decided by the embedder before admission, so it counts only if the service calls AdmissionCounters::record_deny when it sheds; pricing-api does. Refusals at execution start are never counted here; they are commit_refusals.

The AdmissionCounters tallies are relaxed atomics that wrap at u64::MAX rather than saturate: a wrapped monitoring counter is not a correctness event, and at a billion admissions a second admitted needs centuries to wrap. A snapshot() is lock-free, so it is not a single instant; skew between fields is microseconds.

Runtime report fields not in /metrics

RuntimeHandle exposes more than the example publishes. These are library fields an embedder can export.

RuntimeReport

account_reports(now) returns the same data per account (phase, eligible, fundable, task_healthy, restarts, unrecovered_grants, uncertain_acquires, refill). It is deliberately separate from metric labels: labelling a metric by account is unbounded cardinality.

RuntimeReadiness

What readiness(now) decides and why. is_ready() is the probe answer.

/readyz false while every task is alive is not a crash; see Signals worth a response.

Credential feed

KeyManagerMonitor::report(now) returns a KeyManagerReport. pricing-api reads its ready bit in /readyz. Configuration and outage behavior are in Freshness, rotation and outages.

Budget rollover

A direct-store service that applies budget schedules runs a PeriodRoller. PeriodRollerMonitor::report() returns a PeriodRollerReport. The counters are confirmed observations, not a second ledger: an unanswered call may have committed more than they report.

Control-plane server

tollgate-server exports no counters. It reports through tracing events (maintenance sweep outcomes with consecutive_failures, audit events, and failure diagnostics carrying an error_id) and through /readyz. See Control-plane security for audit collection and the HTTP API for the probes.

Guarantees

Tollgate makes specific claims: a strict account never spends past its allocation, a refusal never charges, every committed charge is billed once, and the ledger always balances. This page explains how each kind of claim is checked, maps the whole contract to its proofs, and states what is not established.

The contract itself is the invariants: 41 numbered statements, each naming how it is enforced and the tests that witness it. Violating one is a defect even if every test passes.

How an invariant is enforced

Every invariant states its enforcement, chosen from a ladder, highest first:

1. Unrepresentable by construction. Types and guards make the wrong state impossible to write. A Reservation can be committed or cancelled, not both, because each consumes it.
2. Enforced inside the owning component. The store, the runtime or the admission map refuses the violation, whatever its caller does.
3. A tested convention, hardened by mutation testing. Used only when neither of the above is possible, because a rule that relies on every caller's discipline drifts.

Tests verify enforcement; they don't replace it.

The evidence

Timed performance runs locally rather than in CI on purpose: shared runners can't produce comparable timings, and a gate that fails at random teaches people to ignore it. CI still compiles every benchmark and enforces the allocation counts.

The invariant map

Each invariant, and the Lean modules whose theorems it cites. 27 of the 41 rest partly on a machine-checked proof. The others are enforced by types, by their owning component, or by tested convention, as each one states. A dash means no proof is claimed, not that the invariant is unchecked.

This table is checked: a test fails if it stops matching INVARIANTS.md row by row, including which theorems each invariant cites, or if a module, theorem or invariant count stated on this page or in the README goes stale.

What the proofs cover, and what they don't

A proof is only as strong as what it states. So the models are themselves mutation-tested: check_lean_mutants changes one operator in one transition at a time, checks the mutated model with Lean, and requires a theorem to fail. Only definition bodies are mutated; signatures are types, and specifications (definitions of type Prop) are what the theorems claim, so weakening one would prove nothing. This pushes the proofs to pin down exact behaviour: not only that a limit refuses what exceeds it, but that it accepts exactly what fits. Every mutant that typechecks fails a theorem, apart from one that is equivalent by construction and is listed in formal/lean/mutants-allowed.txt with its reason.

The Lean models use exact integer arithmetic and atomic transitions. A green proof says that a modeled transition preserves its property. It does not say that the Rust or SQL implements that transition faithfully; the Rust property, backend-parity and mutation tests make that argument, and each invariant says which ones.

The models deliberately leave out scheduling, data-structure internals, finite-width overflow, SQL and the network. Those are separate Rust obligations, and the formal models README lists them module by module.

What is not claimed

• No end-to-end refinement proof. There is no machine-checked link from the Lean models to the Rust code. The connection is tests, and tests support a proof-to-code argument; they are not proof.
• Performance numbers are host-specific. They are microbenchmarks on a controlled host, not HTTP latency guarantees on yours. Ratios travel better than absolutes; performance records the conditions.
• Losing the process loses unflushed usage. A committed charge is emitted on every exit path Rust controls, including a panic that unwinds. A killed process, or a panic = "abort" build that aborts, loses what it had not flushed. Its leases are then forfeited as settlement loss, so the account is never credited for work that may have run. Invariants 9 and 13 state this boundary.
• Trusted inputs stay trusted. The proofs and tests assume what their invariants name: an atomic store transaction, accurate clocks, verified credentials, and correct cryptographic primitives.

Checking it yourself

cargo test --workspace --all-features         # tests, witnesses, parity, docs checks
./scripts/check_formal.sh                     # the Lean proofs
./scripts/check_formal_mutants.sh             # mutation testing of the Lean models
./scripts/check_mutations.sh --diff main      # mutation testing on a branch
./scripts/check_perf_thresholds.sh            # timed gates, on your own host

Contributing lists every gate.

tollgate invariants

A change that violates one of these is a defect even when every test passes. Each invariant names the test(s) that enforce it; a new invariant is not "done" until it has one. scripts/check_invariant_witnesses.sh checks backticked snake-case references (including qualified brace groups) against Rust declarations and Lean definitions/theorems, and verifies named proof files. External API, lint, SQL and event names are documented explicitly in testing/invariant_external_symbols.json. This checks citation integrity, not whether a declaration enforces the surrounding claim; test execution, mutation assurance and Lean elaboration remain separate gates. See docs/INVARIANT_REFERENCES.md for the supported notation and limitations. The checker is witnessed by a_stale_witness_and_a_wrong_qualifier_both_fail, comments_strings_and_unexpanded_generators_cannot_supply_a_witness, and a_missing_or_misqualified_lean_witness_fails_even_when_mentioned_in_comments.

1. Bounded spend. Under EnforcementMode::Strict, total committed usage across all instances never exceeds the units allocated to the account, under any interleaving of concurrent clients. Enforced by centrally allocated leases: units are spent only from a lease, and a lease's units were atomically debited from the account at allocation. Opt-in local shards partition that one grant exactly; a debit first uses its sticky local counter, then siblings, and fragmented debits carry a fixed-size exact-total receipt. Sharding never creates capacity and never leaves a positive aggregate unspendable at exhaustion. A live aggregate read is an estimate — the walk is not one atomic instant and a refund may concentrate on a shard it has passed or not yet reached — so it is clamped to the grant, never asserted against it; settlement reads it only at quiescence, where it is exact.

   A funded unit is reachable. Sharding partitions a grant and never strands a positive aggregate at exhaustion; the refill plane partitions an account's allowance the same way, between what one instance holds and what is left in the ledger, and owes the same guarantee. It is not free: an instance holding a tail grant too small for the quote it is offered is holding exactly the units the next grant needs, and asking for one while still holding them sizes it against a balance they are missing from. So the two halves are exchanged in one allocator transaction — the unspent units returned and the replacement granted against the restored balance — with the grant policy's shrink cap applied as a floor against what was returned. The exchange preserves at least the spendable credit it restores, and no other instance can take the returned units in between. Neither property is available to a holder composing release and acquire itself, which is why the operation belongs to the component that owns both the policy and the transaction. The policy's shrink cap does not bound reachability either: it stops one holder hoarding a small balance ahead of demand, and a quote the holder already refused is demand. The lease records the largest quote it refused for want of units, the refill plane forwards it, and the exchange grows the replacement to it when the restored balance can fund it and never otherwise. Growth is at most that one quote, and the request that proved it spends it; a plain acquire and the rest of the balance keep the ordinary policy. Enforcement: the allocator owns sizing, in one GrantPolicy::consolidation_grant both backends call; the lease owns the record of demand.

   A consolidation is a settlement, so the boundary rule applies to it in full: the allowance half of a lease funded by a period that has since closed expires rather than returning (28), and the replacement is sized against what the credit restores, never against the units nominally handed back. Tests: consolidation_never_grants_less_than_it_folded_in, consolidation_folds_the_tail_grant_and_the_ledger_into_one_lease, a_refused_consolidation_leaves_the_original_lease_spendable, consolidating_without_the_lease_capability_moves_no_units, a_consolidation_with_an_invalid_ttl_settles_nothing, consolidating_across_a_boundary_regrants_only_what_the_credit_restores, consolidation_after_a_budget_reduction_uses_only_restored_credit_as_floor (memory and Postgres variants), consolidation_under_a_shrinking_policy_never_returns_less_than_it_folded, consolidation_grows_to_a_proven_quote_under_a_shrinking_policy, consolidation_never_grows_past_the_restored_balance, and growth_leaves_the_rest_for_another_instance (memory and Postgres variants), consolidation_grows_only_to_a_fundable_needed_quote, a_refused_debit_records_its_largest_quote, consolidation_carries_the_refused_quote, a_shrinking_policy_funds_a_quote_above_half_the_balance, a_quote_above_half_the_balance_is_funded_after_one_refusal, consolidation_demand_is_invisible_until_used, consolidation_needed_round_trips_over_http, and a_consolidation_folds_the_tail_grant_over_http for the wire. The reference backend holds a mutex where the SQL backend holds a transaction and so has nothing to roll back: it establishes all-or-nothing by planning both halves before applying either, which a_refused_consolidation_leaves_the_original_lease_spendable is what pins. Postgres returns the restored credit from the same account update that settles the old grant; the replacement consumes that evidence. Conservation.settlement_restores_consolidation_credit, consolidation_grant_respects_restored_balance, and expired_allowance_cannot_enlarge_consolidation, consolidation_growth_is_bounded, and unfundable_demand_changes_nothing prove the exact-model credit, floor and growth bounds; the mirrored tests witness backend arithmetic.

   Under EnforcementMode::Elastic { overage_cap } an account may spend beyond its allocation, and the bound becomes a different one: at most overage_cap unfunded units per service instance, so a fleet of N instances can extend up to N * overage_cap. That multiplication is deliberate — the counter is a local atomic, like every other local mechanism here, and aggregating it would need the synchronous coordination the request path exists to avoid (1). Size the cap against the fleet, not one process. The cap is not sharded the way the grant is: a grant divides because its shards sum back to it, while N per-locality caps would either refuse an elastic request while headroom sat unreachable on another core, or silently raise the cap to N × overage_cap on the instance.

   What the mode does not relax: every unfunded unit is recorded. Overage is billed as ordinary usage and funded by its own ledger term, so per-account conservation stays exact (see Ledger roles) and no unit is ever spent without being accounted for. Elastic mode changes whether a request is admitted; it changes nothing about whether its units are counted.

   Elastic funding is decided twice: at admission, when no lease can fund the quote, and at execution start, when the funding lease's window lapsed in between (3, 12). Both go through the same cap and the same compare-exchange, so both are bounded identically. A commit-time attempt reports the overage counter's own refusal verbatim — OverageCapExhausted, OverageCapTemporarilyExhausted, or OverageCommitInProgress — because each carries a different retry classification — the same three states the retry-state paragraph below defines — and collapsing them would tell a caller to retry immediately against units that are already irrevocable.

   While a commit-time attempt is in flight the account's units are momentarily counted against both its lease and its overage counter. That window cannot be closed — the counters are separate atomics, and returning the lease earlier is the double-refund defect (3) — but it only ever over-states local occupancy, so every refusal it can cause is conservative and none of them can admit work the cap should have refused. Tests: no_double_spend_across_instances (memory and Postgres variants), tollgate-core reservation proptests; lease_units_are_conserved and concurrent_commit_conservation across sharded layouts, sharded_grant_and_low_water_partitions_are_exact, a_whole_sibling_is_used_before_fragmenting, sharded_lease_spends_to_exact_exhaustion_without_stranding, failed_fragmented_debit_reports_true_remaining_and_rolls_back, a_torn_aggregate_above_the_grant_reads_as_the_grant, a_fragmenting_rollback_never_panics_a_concurrent_aggregate_read, and the exact aggregate model in formal/lean/Tollgate/LeaseShards.lean; elastic_refuses_once_the_local_overage_cap_is_spent, every_principal_of_an_account_shares_one_cap, republishing_a_snapshot_does_not_reset_the_cap, concurrent_debits_never_exceed_the_cap, a_sharded_slot_does_not_multiply_the_overage_cap and a_sharded_slot_still_prefers_the_lease_that_can_fund_the_quote (the cap and the sharded lease views sharing one slot), and Tollgate.Conservation.an_accepted_debit_stays_within_the_cap.

   Pending and committed occupancy are distinct retry states. Reservation phase and account occupancy publish through a guard-owned transition. A zero-delta observer RMW participates in the marker's modification order, so an observer overlapping it receives OverageCommitInProgress/AfterInFlight, never a claim that irrevocable units remain refundable or a promise that funding is already required. In a stable state, a refusal is OverageCapTemporarilyExhausted/Transient only when refunding all pending reservations would make that request fit; otherwise it is stable local OverageCapExhausted. These reasons are Transient: neither alone proves central account exhaustion, and an ordinary lease refill can fund the unchanged request. Confirmed exhaustion may replace the committed-cap refusal as described below; refundable occupancy remains transient. Tests: pending_overage_is_transient_only_when_its_refund_would_make_room, overage_retry_class_matches_stable_occupancy, pending_overage_saturation_is_transient_until_cancel, and elastic_refuses_once_the_local_overage_cap_is_spent, committed_overage_exhaustion_remains_retryable_after_lease_refill, plus overage_commit_publication_never_looks_refundable and overage_retry_classes_map_to_distinct_http_contracts for the canonical embedder. The commit-time attempt reaches the same three states: an_elastic_lapse_with_no_committed_headroom_releases_the_lease_for_zero, an_elastic_lapse_blocked_by_refundable_occupancy_is_temporarily_exhausted, and an_elastic_lapse_overlapping_a_sibling_publication_reports_an_in_flight_commit. Proof: formal/lean/Tollgate/OveragePublication.lean.

   Funding refusals require ledger evidence. An allocatable balance of zero does not prove spent funding: another instance may return a lease. Only the allocator's locked ledger, including outstanding units and recorded consumption, produces BalanceShortfall { remaining, period_end }: what the account was funded with minus what it consumed or lost. Unreported consumption can only lower true remaining funding, so remaining is an upper bound and a quote above it cannot be funded under current funding; a quote within it proves nothing. Every grant carries this evidence as read from the ledger it commits into, settlement included; a refusal carries it as BalanceExhausted when remaining is zero and BalanceInsufficient otherwise. A rolled-back consolidation cannot certify a shortfall caused by its uncommitted loss or expiry, and returns the unattested InsufficientBalance. Admission uses the evidence only after local lease funding and any elastic fallback fail. Refundable overage and in-flight commits retain their own retry classes. Zero remaining produces BalanceExhausted; a quote above a positive remaining produces BalanceInsufficient { remaining }; both are Retry::Never under the current funding. A quote within remaining keeps the lease refusal's transient advice. A new grant replaces the evidence with its own; an accepted changed funding snapshot invalidates it, as does reaching its stored period boundary. This classification charges no units.

   Enforcement: the allocator owns ledger classification; FundingAttempt binds publication to an identity epoch in the account's LeaseSlot. Control-plane publishers serialize; a new grant or changed funding snapshot replaces that identity before clearing the evidence. FundingAttempt::granted installs a grant and publishes its evidence under that same lock, and only when no funding change was accepted while the call was outstanding. Snapshot maps order generations per principal before publication; the account-shared slot compares only budget and enforcement mode, so an accepted change from any principal invalidates the account's evidence. Restoring the same lease does not clear it. Admission reads one atomic deadline on a funding refusal, using caller-supplied time; only live evidence costs a remaining load and a deadline re-read, and a pair that straddles a publication is discarded. Deadline flooring can discard evidence early, never extend it. An HTTP grant whose evidence is below its own units carries none. No request-path I/O, allocation or blocking lock is added.

   Witnesses: an_insufficient_balance_recovers_when_another_instance_returns_its_lease, a_reclaimed_lease_forfeits_its_funding_instead_of_restoring_it, exhaustion_requires_recorded_consumption_and_survives_lease_expiry, exhaustion_evidence_names_the_stored_period_and_rollover_restores_funding, zero_requested_units_never_produce_exhaustion_evidence, grants_report_ledger_remaining_including_outstanding_leases, a_partial_balance_refusal_reports_remaining_funding, shortfall_evidence_names_the_stored_period, and a_refused_consolidation_leaves_the_original_lease_spendable in both backend suites; authoritative_exhaustion_classifies_only_failed_local_funding, insufficient_funding_refuses_only_quotes_above_evidence, grant_evidence_is_published_with_its_lease, exhausted_evidence_survives_local_expiry_but_not_its_period_end, central_exhaustion_does_not_hide_refundable_elastic_capacity, central_shortfall_does_not_hide_elastic_capacity, exhaustion_is_shared_by_account_and_isolated_from_other_accounts, exhaustion_deadlines_are_conservative_at_subsecond_and_domain_boundaries, paired_evidence_reads_are_conservative, funding_publication_invalidates_late_exhaustion_responses, accepted_funding_changes_from_independently_versioned_principals_clear_exhaustion, refill_publishes_exhaustion_and_a_topup_clears_it, refill_publishes_shortfall_and_a_topup_clears_it, a_refill_gap_with_credit_held_elsewhere_is_not_exhaustion, a_rolled_back_consolidation_returns_the_lease_to_the_slot, a_consolidated_tail_publishes_the_accounts_remaining_funding, authoritative_exhaustion_round_trips_over_http, shortfall_evidence_round_trips_over_http, incomplete_exhaustion_responses_never_become_authoritative, incomplete_shortfall_responses_never_become_authoritative, grant_evidence_below_the_grant_itself_is_discarded, a_quote_above_remaining_funding_is_payment_required_until_a_top_up, confirmed_balance_exhaustion_allocates_nothing, and confirmed_shortfall_allocates_nothing. Exact ledger, shortfall, epoch and paired-read laws: formal/lean/Tollgate/BalanceExhaustion.lean. These proofs assume serialized ledger/publication transitions; backend, transport, arithmetic and allocation tests are separate implementation evidence.

2. Zero charge before execution. A reservation that never reaches commit_at_execution_start charges zero units, and its units return to the local lease. Dropping a pending reservation is a release, not a leak. A fragmented sharded reservation refunds its exact aggregate once; shards may rebalance because they are partitions of the same lease bound. A commit-time elastic fallback is a commit, not a release: it returns the lease receipt because overage now funds the same units, and the charge stands in full. ChargeLifecycle.lean proves the exact lifecycle model: only a committed request is charged (Tollgate.ChargeLifecycle.uncommitted_charges_nothing, Tollgate.ChargeLifecycle.admit_charges_nothing), cancellation refunds exactly the admitted debit (Tollgate.ChargeLifecycle.cancel_refunds_exactly), and every transition conserves the lease (Tollgate.ChargeLifecycle.admit_wf, Tollgate.ChargeLifecycle.cancel_wf). Tests: reservation::tests::{drop_releases_pending, cancel_charges_zero_and_refunds}, fragmented_reservation_refunds_without_stranding_capacity, a_fallback_commit_refunds_its_lease_exactly_once, and lease_units_are_conserved.

3. Atomic commit-vs-cancel. Commit and cancel race on a single atomic transition; exactly one wins. A cancelled reservation can never later commit; a committed reservation reports its full charge to a late canceller. Overage wraps that phase transition and committed occupancy in a visible publication guard, so observers never treat the interval between the two atomic words as stable. Once both racers return its retry classification agrees with the winner.

   That race is reachable across threads without a lock. ReadyToStart::split moves the reservation into one shared object and hands the asynchronous side a CancelHandle; both halves resolve the same compare-exchange, so splitting changes who may ask for a cancellation and never how the race is decided. Cancellation being requested is a separate fact from whether it changed the funding: the request flag is set before the phase is attempted, so a worker that wins still observes it and may stop computing work whose caller has gone, while the charge stands in full. The worker's half releases eagerly on drop rather than waiting for the handle to let go, so abandoning a request refunds at the instant the worker gives up. Splitting is opt-in and costs exactly one allocation; an unsplit request has no handle, so nothing can have asked it to stop.

   The phase word carries five values, and the terminal one names the funding that settled the charge: PENDING_LEASE reaches COMMITTED_LEASE, COMMITTED_OVERAGE, or RELEASED; PENDING_OVERAGE reaches COMMITTED_OVERAGE or RELEASED. The middle edge is the commit-time elastic fallback, and it is one transition rather than a release followed by a second reservation — which would give a canceller one phase to win while a worker committed another, and let both report success. It is funded by a revocable overage debit taken strictly before the claim, so a winning claim can never name overage the account never recorded, and it returns the lease receipt strictly after the claim, so a losing claim cannot double-refund alongside the canceller that already returned it. An unresolved tentative debit is returned by its own guard, making "debited but never resolved" unrepresentable rather than merely tested. Tests: reservation::tests::commit_cancel_race_one_winner, reservation::tests::overage_commit_publication_never_looks_refundable, reservation::tests::overage_commit_cancel_race_preserves_retry_classification, reservation::tests::fallback_commit_and_cancel_leave_exactly_one_funding_term, reservation::tests::a_fallback_that_loses_to_cancel_strands_no_overage_capacity, lease::tests::dropping_an_unresolved_tentative_debit_returns_the_credit, funding_terms_are_conserved_across_lapse_and_fallback, reservation::tests::split_commit_and_handle_cancel_have_exactly_one_winner, reservation::tests::a_shared_fallback_and_a_handle_cancel_leave_one_funding_term, reservation::tests::a_late_cancel_reports_the_full_charge_and_still_records_the_request, and engine::tests::dropping_the_worker_side_refunds_before_the_cancel_handle_does. Proofs: formal/lean/Tollgate/OveragePublication.lean and formal/lean/Tollgate/CommitFallback.lean.

4. Lease capabilities are exact and lease-scoped. Every acquired lease is stamped with the next fencing token in its account's strictly increasing sequence, beginning at one; zero is not a persisted capability or counter. The sequence is an allocation and audit order, not an account-wide validity epoch: issuing a newer token does not invalidate an older lease that is still active. Release accepts only the stored (lease_id, fencing_token) pair; usage accepts only the stored (lease_id, account_id, fencing_token) triple. Lease state and remaining capacity are independent checks: a matching capability cannot revive a reclaimed lease or exceed its accounting capacity. A stored fence outside the token domain is surfaced as a storage error, never aliased to fence 0 — aliasing would misattribute corruption to the caller and break the monotonic audit trail. If release rejects the token attached to a grant the client believed valid, the client clears its slot and fails closed because its local lease identity can no longer be trusted relative to the store. LeaseFencing.lean proves the exact model: fences are positive, unique per account and increasing (Tollgate.LeaseFencing.capability_names_one_lease, Tollgate.LeaseFencing.acquire_fence_exceeds_existing); a newer lease leaves existing ones untouched (Tollgate.LeaseFencing.acquire_preserves_existing); a mismatched pair or triple is refused (Tollgate.LeaseFencing.release_refuses_wrong_fence, Tollgate.LeaseFencing.ingest_refuses_wrong_fence, Tollgate.LeaseFencing.ingest_refuses_wrong_account); each operation changes only the lease it names (Tollgate.LeaseFencing.ingest_scoped, Tollgate.LeaseFencing.release_scoped); a settled lease never revives (Tollgate.LeaseFencing.settled_lease_never_revives); and billed plus returned units stay within the grant (Tollgate.LeaseFencing.billed_and_returned_within_grant, Tollgate.LeaseFencing.ingest_refuses_past_capacity). It assumes atomic store operations and does not prove the Rust or SQL refinement, which the tests below witness. Tests: newer_lease_does_not_invalidate_older_active_capability, wrong_token_release_leaves_lease_reclaimable, and usage_rejects_mismatched_lease_capability (store suites); reclaim_forfeits_an_unreleased_remainder_as_provisional_loss, straggler_usage_after_release_is_billed, and fenced_release_clears_the_slot; acquire_surfaces_nonpositive_stored_fence and release_and_ingest_surface_nonpositive_stored_fence (Postgres suite; the memory backend owns a counter seeded at one, updated only by checked increments); zero_fences_are_refused_in_every_persisted_capability (Postgres schema checks).

5. Fail closed, zero I/O. Unknown principal, suspended/closed account, expired snapshot, missing permission, cost overflow, accounting backpressure: all deny locally, under every enforcement mode. A lease that cannot fund the quote — absent, expired, or exhausted — also denies locally under Strict; it is the one condition Elastic may admit past, because it is the one that says something about funding rather than about validity (1). Nothing else in this list is mode-dependent. The request path performs no database, file, lock-file, or network access — not even on a miss.

   This is a rule about I/O, and it is worth saying what it is not, because two other documents used to cite it as forbidding locks outright. The hot path takes no blocking lock and reads no wall or business clock for a policy decision. A dependency's own bounded, non-blocking bookkeeping is a different thing and is permitted: MokaSnapshotMap lets moka's housekeeper drain its read log inline behind a try_lock, updating the frequency sketch and evicting at capacity, and governor reads a monotonic clock for bucket arithmetic. Neither can block a request and neither is a source of snapshot or lease truth. They are measured, not assumed: the allocation share by moka_reads_stay_within_their_amortized_allocation_budget (24), and the latency by the admission/snapshot_lookup_moka row, and — once its bound is recorded on the controlled host — by the at-capacity benchmark beside it, which exists because a moka cache below half its capacity does not enable its frequency sketch at all, so an under-filled benchmark prices neither the sketch nor eviction. No test asserts the absence of a try_lock on the request path; this invariant does not claim one does.

   A deny also says which kind it is: a request that can never be admitted under the account's current schedule — its quote exceeds the whole burst — is UnpriceableUnderLimits, never RateLimited, so a caller is never told to retry something that cannot succeed and an operator is never shown throttling for a misconfiguration. Tests: tollgate-core deny-path unit tests; admission-crate miss tests assert no store calls from the request path; batch_cap_above_burst_is_unpriceable_not_throttled, zero_burst_denies_every_priced_request, quote_beyond_the_bucket_domain_is_unpriceable, and rate_limiter_weights_by_cost (the converse: genuine throttling stays RateLimited); and elastic_does_not_relax_any_refusal_that_is_not_about_funding, which pins that an elastic account still denies every non-funding refusal and claims no credit while doing so. AccountSnapshot::builder requires the administrative status, and builder_requires_account_status_at_construction pins that incomplete construction cannot silently become Active. An opt-in sharded limiter partitions (never copies) the instance-local account rate and burst; publication's already-validated maximum quote limits the shard count so every shard can admit the largest legitimate request. That limit is account-wide, because the bucket is: it is the tightest ceiling accepted publications from principals sharing the account have presented. An accepted principal snapshot can tighten it even when its account-policy generation is older; a rejected replay cannot affect it. The ceiling never widens, so a key with a heavier cost table is never wedged by a split its sibling sized. Raw snapshot installs retain one defensive bucket because they do not carry that proof. A shard that cannot hold a request is not the account's answer: siblings are tried. If none admits now but at least one can hold the weight, the weighted refusal is RateLimited; UnpriceableUnderLimits applies only when no bucket can hold it. Both RateLimited and RequestRateLimited classify as Retry::Transient. Neither carries a retry instant or delay, and neither promises admission at an earliest retry time. Enforcement: payload-free denial variants and DenyReason::retry own the public contract; admission consumes the governor refusal without exposing its timing. Tests: every_reason_has_the_expected_retry_class (core deny tests), rate_limiter_weights_by_cost, and request_rate_limiter_counts_requests_not_cost. Additional tests: rate_shards_partition_one_account_burst_without_multiplying_it, maximum_quote_limits_shards_to_buckets_that_can_admit_it, publication_accepts_a_worst_case_quote_equal_to_the_burst, publishable_install_carries_maximum_quote_into_rate_sharding, a_heavier_principal_resplits_the_account_bucket_it_shares, an_unproven_principal_collapses_the_account_split, a_stale_snapshot_still_narrows_the_split_it_cannot_widen, and a_shared_split_bucket_never_wedges_a_principal_the_burst_can_hold. Tightening that safe split publishes one replacement through the account's single AccountPolicyState indirection. Every subsequent request, from every principal, loads that one current authority; no installed principal retains an independently refillable old bucket. Test: shard_tightening_cannot_leave_two_spendable_account_buckets. Request-count rate is a second optional account bucket with unit weight; it is checked before the optional cost-weighted bucket, and tokens from either are never refunded after a later refusal. Each dimension binds its immutable enforced parameters to its mutable bucket. Publishing a change in one dimension, including inactive compatibility metadata, retains the exact bucket and consumed state of every unchanged dimension. RateState owns the exact AccountRatePolicy its buckets implement. Rate and account concurrency are selected by the same accepted account-policy generation and published in one AccountPolicyState; a request loads it once and uses it for every account-wide decision. Principal snapshots remain the authorities for status, permissions, request shaping, pricing, funding mode, and optional principal concurrency. A divergent same-generation or older principal can therefore neither bypass nor manufacture an account bucket or ceiling, and a genuinely newer accepted account policy reaches every principal on its next request. Omitting either bucket performs no governor operation for that dimension.

   Generation acceptance precedes runtime resolution in both snapshot maps. A rejected replay, and a positive overwritten before an atomic batch is published, cannot mutate the account policy registry. This ordering is the enforcement boundary for authorization monotonicity (15), not a downstream request-path check. Additional tests: request_rate_limiter_counts_requests_not_cost, disabled_weighted_rate_performs_no_weighted_check, changing_disabled_weighted_fallback_does_not_refill_request_rate, enabling_request_rate_does_not_refill_weighted_rate, divergent_enabled_snapshot_cannot_outlive_a_disabled_account_bucket, divergent_disabled_snapshot_cannot_bypass_an_enabled_account_bucket, resolved_account_authority_carries_the_generation_winners_policy, moka_rejects_replays_before_resolving_account_state, arc_swap_rejects_replays_before_resolving_account_state, an_overwritten_batch_positive_never_becomes_account_authority, a_later_funding_refusal_releases_concurrency_but_keeps_rate_tokens, limit_change_is_one_account_authority_for_every_principal, and one_batch_with_two_generations_keeps_the_newer. Proof: formal/lean/Tollgate/RatePublication.lean, including unchanged_weighted_authority_is_preserved and unchanged_request_authority_is_preserved.

6. Foreground isolation. Lease refill and snapshot replacement never block an in-flight request, and the request path never waits on the plane that refills it. A draining lease tells the refill task rather than being discovered by it — the debit that crosses low water raises a signal whose implementation is contractually non-blocking — so refill latency is no longer bounded below by the poll interval, and a funded account is not refused between ticks. Cold start keeps the interval as its backstop, having no debit to announce it. In a sharded lease, an early local low-water crossing wakes at most once per shard; if the aggregate is not low yet, the manager clears those doorbells and rechecks the aggregate so a concurrent crossing cannot be lost. Publishing The doorbell only removes that floor if nothing in the loop body puts one back: the release pass carries a single store_call_timeout across every parked lease, so a wedged backend cannot make refill latency grow with the parked count (GL-78). A refusal is announced, and it is announced as a different thing. A debit the lease cannot fund — for units or because its usability window has lapsed — raises the same doorbell, once per lease, and the plane is told which happened. The two are not degrees of one signal and cannot share a response. A crossing is anticipatory: the lease still serves, so the plane acquires alongside it and no request is refused meanwhile. A refusal is that failure already realised, and it is a statement about the grant's size rather than its depletion — a lease can sit above every threshold and still be too small for the quote offered, which is precisely the state adaptive allocation produces at the end of an allowance and low water then caps itself below. Acquiring alongside such a lease sizes the next grant against a balance its own unspent units are missing from, and installs the smaller answer; the plane must instead consolidate, folding those units back in as it re-grants (1's reachability clause). A refusal for units also records its quote on the lease, keeping the largest, and the consolidation carries it to the allocator as the demand the replacement may grow to.

   The units are exact only once the lease has quiesced, so consolidation takes it out of the slot first. That is a deny window, so quiescence is tested and never waited for: a lease with a reservation in flight goes straight back and the next refusal rings again. A consolidation whose outcome the store did not report is parked, never reinstated — the transaction may have committed, and serving from a lease the ledger has already credited back is the one outcome worse than the refusal being repaired. A consolidation interrupted by shutdown retains its pending-acquire marker: settling the predecessor cannot recover an unanswered replacement, whose capability remains uncertain until TTL reclaim. Successful consolidation records acquisition and settlement together inside LeaseCounters, so the runtime's terminal inventory excludes the settled predecessor. Timeouts and Storage acquisition errors also remain counted as uncertain while a manager runs and after a clean join; domain refusals do not. The same counter owner classifies ordinary and consolidating acquisitions. Witnesses: shutdown_reports_an_unanswered_consolidation_grant and a_consolidated_predecessor_is_not_reported_as_crash_exposure, ambiguous_consolidations_remain_visible_after_a_clean_shutdown, and only_ambiguous_acquire_outcomes_increase_uncertainty, with AccountLifecycle.consolidation_preserves_parked_inventory proving the exact-model inventory transition. The HTTP boundary also witnesses both delivered and cancelled acquisition results: shutdown_accounts_for_unanswered_grants_over_http, shutdown_accounts_for_unanswered_grants_over_tls, and shutdown_accounts_for_unanswered_grants_over_mtls. They reconcile billing and active grants at shutdown, preserve the reclaim grace period, and verify the exact unspent balance returns when the reported unanswered grant expires. Uncertainty counts possible grants, not units or confirmed transactions.

   Publishing a lease to N locality views is N swaps, so mutators are serialized: a reader straddles one publication exactly as it straddled the single-view slot's one swap, but the slot never ends a publication holding two different leases, which is what would let a locality keep spending past a revocation. Rotation and shutdown wait for every locality's independently reference-counted lease view before releasing the exact aggregate. Shutdown waits inside its own budget and abandons what has not quiesced by the deadline: releasing units a request may still spend cannot be undone, while abandoning them forfeits their remainder at TTL reclaim (GL-9), a bounded cost that can never over-spend. The lifecycle order in GL-13 asks an embedder to quiesce before shutting down; this no longer depends on that, the predicate being the one the steady-state pass already applies (GL-62). A lease leaves this instance's books only by being released or by being reported. Tests: refill_begins_on_the_crossing_debit_not_the_next_tick, shutdown_abandons_a_lease_an_in_flight_request_still_holds, fenced_release_clears_the_slot, a_refill_does_not_wait_behind_the_release_pass, a_burst_across_a_rotation_never_denies_a_funded_account, refill_installs_lease_on_cold_start, usability_window_rollover_returns_unspent_capacity, the_crossing_debit_raises_the_signal, a_lease_signals_at_most_once_however_long_it_drains, an_early_shard_signal_is_rearmed_until_the_aggregate_crosses, rotation_at_low_water_installs_fresh_lease, a_refused_debit_reports_a_refusal_and_never_a_crossing, a_refused_debit_tells_the_refill_plane_rather_than_waiting_to_be_polled, a_refusal_storm_rings_once_and_reports_once, a_refusal_outranks_a_low_water_crossing, a_sharded_refusal_reports_once_for_the_whole_grant, a_lease_with_no_doorbell_still_records_its_refusal, an_expired_lease_reports_its_refusal_rather_than_waiting_for_the_tick, a_refused_lease_consolidates_rather_than_stranding_the_tail, a_successful_consolidation_installs_the_grant_and_parks_nothing, consolidation_retains_a_grant_published_during_the_store_call, a_rolled_back_consolidation_returns_the_lease_to_the_slot, an_ambiguous_consolidation_parks_the_grant_rather_than_reinstating_it, a_settled_lease_falls_through_to_an_ordinary_acquire, an_over_claimed_fold_withdraws_readiness_and_keeps_serving, a_consolidation_defers_while_a_reservation_is_in_flight, shutdown_releases_unspent_units, sharded_slot_keeps_release_parked_while_any_local_view_is_held, racing_mutators_never_leave_a_slot_holding_two_answers, and the RefillRequests handoff tests. Configuration ownership is witnessed by mismatched_local_sharding_is_rejected_before_tasks_start.

7. Idempotent partial accounting. Replaying a usage batch (same request IDs) never double-bills. Every successful mixed batch classifies each input exactly once as accepted, duplicate, or rejected; only accepted events change either ledger, and their grouped lease/account effects stay in the same atomic transaction.

   A duplicate is recognized before its payload is examined. A new event outside the backend's unit domain is rejected individually and does not claim its request ID. Memory retains its full u64 domain; PostgreSQL's nonnegative BIGINT domain is 0..=i64::MAX. Representable events whose combined deltas or resulting monotonic accounting totals overflow refuse the whole batch with IngestError::Refused; a retry cannot recover capacity. Stored corruption and operational failures remain retryable store errors.

   Deposits outside the backend's unit domain or overflowing either funding counter return AllocateError::BalanceOverflow, mapped to HTTP 422 balance-overflow; the unchanged request must never be retried. Both counters remain unchanged. Memory checks both sums before applying either; PostgreSQL's single UPDATE rolls back on numeric overflow. Witnesses: deposits_accept_the_unit_ceiling_and_refuse_overflow and a_refused_deposit_moves_neither_column (both backends), a_deposit_outside_bigint_is_a_permanent_refusal (PostgreSQL), and deposit_overflow_is_a_permanent_client_error (HTTP).

   Credential activity consumes that accepted set too (35); a duplicate's changed key ID or timestamp cannot become fresh evidence.

   A batch that fails changes neither ledger. This is where the reference backend has to work for its living: PostgresStore gets it from one transaction and finish_transaction, while MemoryStore must reach the same outcome by computing every fallible value before it mutates anything — the rule acquire states and set_account_status splits into plan/apply. Applying as it walked left earlier events of a failed batch committed while the caller was told the batch failed, which inverts "partial data is surfaced, never silently absorbed": the replay counts them as duplicates, so a partial success is reported as a total failure and nothing says otherwise (GL-57).

   IdempotentIngest.lean proves the exact model for any acceptance decision: each input is classified once (Tollgate.IdempotentIngest.classified_once); a duplicate is recognized from its request ID before its payload (Tollgate.IdempotentIngest.duplicate_ignores_payload); a rejected event claims nothing (Tollgate.IdempotentIngest.rejected_claims_nothing); the ledger only appends accepted events (Tollgate.IdempotentIngest.plan_ledger), so no request ID is billed twice across any replay (Tollgate.IdempotentIngest.billed_at_most_once, Tollgate.IdempotentIngest.replay_accepts_nothing_twice); the billed total grows by exactly the accepted units (Tollgate.IdempotentIngest.billed_grows_by_accepted); and a failed batch changes nothing (Tollgate.IdempotentIngest.failed_batch_changes_nothing). It assumes the batch applies atomically, as stated above.

   Tests: usage_replay_is_idempotent, mixed_usage_batch_preserves_partial_acceptance, usage_accepts_zero_and_the_backends_unit_ceiling, overage_accounting_overflow_is_surfaced, a_failed_ingest_batch_leaves_the_ledger_untouched, and a_refused_deposit_moves_neither_column (all mirrored across both store suites); unrepresentable_usage_rejects_only_that_event_and_does_not_claim_its_id (Postgres: UsageEvent cannot exceed MemoryStore's u64 domain).

8. Accounting backpressure sheds. When the usage queue is full, new work is refused with zero units charged. Usage events are never silently dropped and enqueue never blocks unboundedly. The queue is partitioned into lanes by request locality, and "full" means every lane is full: a request whose own lane is full takes a slot in another before it sheds, so the shed point is exactly the configured queue_capacity (GL-137). Shutdown closes every lane (new reservations refuse from that instant), then drains until every lane is empty and every outstanding permit has resolved by sending or dropping — a lane that is merely momentarily empty is not drained — bounded by the configured shutdown_drain_deadline — which governs the ingest calls the drain makes as well as its receives, so the bound is the drain's total wall clock. It flushes in configured-size batches, counts any event still undeliverable after the bounded final retries in WriterStats::lost (a timed-out ingest is undelivered, never a silent success), and reports permits still outstanding at the deadline in WriterStats::unresolved — a deadline expiry is never a clean flush. The reporting holds across the writer's own death: every charge that enters the queue is counted until it is given a billing outcome, in a counter outside the task, so a writer that panics or is aborted returns WriterShutdownError carrying a lower bound on the charges it was holding. A zeroed WriterStats is never returned for a task that did not report one — and, since the type is deliberately not Default, cannot be conjured from a failure. Those numbers are readable at any time, not only from a graceful shutdown — which is precisely the case where loss is least likely. They live in counters outside the task, and shutdown returns a snapshot of those same counters rather than a parallel tally, so the running totals and the final report cannot disagree. Queue depth against its capacity makes backpressure visible before it sheds; sheds are counted at try_reserve, the only place a refusal can happen, so no embedder can forget to; and the time the sink last answered separates a quiet writer from an unreachable one — a distinction lost cannot make while the process runs, since the steady-state path retries an unavailable sink forever and declares that loss only at the final flush. A batch the sink refuses outright is the exception: it is counted lost and dropped when refused, so a permanent error cannot stall every event queued behind it. The drain's budget is total wall clock, so its retry backoffs sleep into whatever remains and never past it: an overrun spends the margin expiry_safety_margin + reclaim_grace reserves (GL-12), and bounding by attempt count alone is not a bound (GL-18, GL-63). ChargeLifecycle.lean proves the slot model: the slots in use never exceed the queue's capacity (Tollgate.ChargeLifecycle.reserve_wf), and a request finding the queue full is shed with nothing charged (Tollgate.ChargeLifecycle.full_queue_sheds). Lanes, the drain deadline and the writer's counters are outside the model. Tests: client writer overflow tests, the_final_flush_backoff_cannot_overrun_the_drain_deadline, shutdown_flushes_in_configured_batch_sizes, shutdown_during_outage_terminates_and_reports_loss, reserve_fails_once_shutdown_begins, shutdown_waits_for_outstanding_permit, late_permit_drop_completes_drain, drain_deadline_expiry_reports_unresolved, panicked_writer_reports_unaccounted_charges, panic_after_partial_flush_counts_only_unflushed, running_totals_are_readable_and_match_the_final_report, queue_depth_rises_before_the_shed_and_sheds_are_counted, the_shed_point_is_the_whole_queue_across_lanes, the_drain_delivers_every_lane_and_reports_every_lanes_permits, a_resolving_permit_in_any_lane_completes_the_drain, a_failing_sink_does_not_advance_the_last_ingest_time, rejected_events_are_visible_while_running, and metrics_report_accounting_health_while_running.

9. A crashed holder can never over-spend. A lease its holder never released is settled by the expiry sweep after expires_at + grace, and the sweep credits nothing back: the whole granted - recorded usage is recorded as provisional settlement loss, exactly as a release claiming nothing unspent would record it (GL-136). No unit can be proven unspent without a release. A lease accepts commits until usable_until, and a holder killed with a non-empty usage queue executed work the ledger never saw, so crediting the remainder would let that work be spent twice. Usage for the lease that arrives later, from a holder that outlived an outage, converts loss into billed usage and can never exceed it. The ledger equation is unchanged, because loss is already one of its terms. The cost is bounded by what the holder held: a crash or a shutdown whose release deadline lapsed forfeits the unspent remainder of its outstanding grants. Only a release returns units. Enforcement: the allocator owns settlement in both backends, and no caller can request a credit. Each reclaim transaction is bounded; the server fixes one expiry cutoff and drains saturated batches immediately, so bounding lock scope never caps the legitimate backlog that returns. A bounded batch is also the oldest due leases and stops at the first one that is not due, identically in both backends — and on PostgreSQL the batch's read work is bounded by the batch rather than by the backlog, because the sweep orders by the expiry index's own columns so the LIMIT stops the walk (GL-65). Tests: reclaim_forfeits_an_unreleased_remainder_as_provisional_loss, straggler_usage_after_reclaim_is_billed_against_the_forfeit, a_reclaimed_lease_forfeits_its_funding_instead_of_restoring_it, expired_backlog_is_reclaimed_in_bounded_batches and a_bounded_reclaim_page_settles_the_oldest_due_leases_first (store suites), the_expiry_sweep_stops_at_its_batch_instead_of_sorting_the_backlog and a_bounded_rollover_page_crosses_the_oldest_boundaries_first (PostgreSQL plan and page order), plus one_scheduled_sweep_drains_every_saturated_batch and the_server_reclaims_expired_leases_on_its_interval (server suite, which also witnesses the forfeit warning), and a_sweep_with_nothing_to_forfeit_reports_at_info_and_idle_ticks_stay_silent (server suite), and the crash witnesses a_killed_holders_unflushed_usage_is_not_credited_back, a_kill_during_an_outage_with_a_full_backlog_forfeits_everything_held and a_survivor_flushes_after_reclaim_and_is_billed (client suite). Proof: Conservation.forfeit_credits_nothing, forfeit_preserves_conservation and straggler_moves_loss_to_usage_conserves.

   Routine publication preserves ownership of the displaced grant. LeaseSlot exposes only replace and take, both returning a must-use handle; no convenience mutation silently drops it. The caller retains that handle for quiesced release or explicitly abandons it to TTL reclamation. LeaseManager owns retention through publish_and_park, including publications after a consolidation call while another publisher may have filled the slot. Enforcement: the API removes silent-discard operations; must-use diagnostics catch ignored outcomes; the manager retains displaced handles internally. A caller can still deliberately drop a handle, so this does not prove every external embedder releases it. Tests: superseding_a_lease_hands_back_the_old_one, racing_mutators_never_leave_a_slot_holding_two_answers, consolidation_retains_a_grant_published_during_the_store_call, and the compile-fail examples on LeaseSlot, LeaseSlot::replace, and LeaseSlot::take.

   Both backends retain exact nanosecond expiry and grace. PostgreSQL stores a canonical integer pair and compares it to GrantPolicy::reclaim_cutoff; MemoryStore uses the same checked cutoff. An underflow has no due expiry, and a deadline beyond Timestamp::MAX is never shortened to that instant. Migration 0017 retains an explicit conservative upper bound for legacy rows with lost precision and fences old lease SQL through a column rename. Tests: nanosecond_lease_boundaries_preserve_release_reclaim_and_consolidation, a_grace_deadline_beyond_timestamp_max_never_reclaims_early, an_unrepresentable_replacement_expiry_leaves_the_original_grant_untouched (both stores), reclaim_cutoff_matches_an_independent_nanosecond_oracle, reclaim_cutoff_preserves_single_nanosecond_boundaries, durable_pairs_round_trip_and_preserve_order, lease_instants_preserve_epoch_edges_and_the_full_timestamp_domain, expiry_upgrade_preserves_accounting_and_fences_old_lease_queries, legacy_expiry_bounds_cover_both_sides_of_the_epoch, and invalid_legacy_expiry_rolls_back_upgrade_and_exact_rows_enforce_the_domain. Proof: formal/lean/Tollgate/LeaseTiming.lean; finite representation and database behavior are separate test evidence. See docs/LEASE_TIMING.md for migration bounds, deployment and recovery.

   The server owns and observes its maintenance task. Each reclaim and rollover outcome is published independently; readiness requires both to have completed successfully and the publisher to remain alive. A first failure withdraws readiness before the next operation can suspend. Failure of one pass does not prevent the other from running. Unexpected task completion, cancellation or unwinding panic stops the listener with an operational error. Graceful shutdown and owner cancellation withdraw readiness before aborting the task; a late success cannot restore it. These are observed-outcome/liveness claims, not a new deadline on a pending backend call or proof that another replica holds no skipped rows. Enforcement: maintenance::Publisher, Monitor, Task and serve. Tests: readiness_requires_both_passes_and_tracks_independent_failure_and_recovery, a_panicked_maintenance_call_stops_the_server_with_a_safe_error, graceful_shutdown_cancels_pending_maintenance_without_failure_events, cancelling_the_server_drops_its_shutdown_future, owner_drop_withdraws_readiness_before_abort_is_polled, closed_publication_cannot_preserve_a_healthy_last_value, and cancellation_without_a_stop_request_closes_maintenance_health. Tollgate.ServerMaintenance proves independent failure, recovery, and terminal stop/exit properties over atomic observations. Rust tests witness the watch, task, HTTP and finite-counter implementation boundaries separately.

10. Ready means currently admissible. An instance reports ready only while its snapshot resolutions meet the bar below, it can still fund work, and its snapshot and refill/accounting tasks are alive. Readiness falls again on exhaustion, expiry, or task exit; fail-closed correctness must not masquerade as availability.

    Snapshot and lease tasks own the sole health publisher through TaskHealth. Its destructor stores false before closing the channel on normal return, unwind or cancellation, including cancellation before the first poll. Retained watch receivers cannot preserve a true value after the task exits. Aborting a task requests cancellation; this guarantee applies when its future is destroyed, not before the executor processes the abort. Whole-process abort has no surviving in-process observer. Tests: snapshot_readiness_is_false_after_shutdown_or_owner_drop, a_snapshot_task_panic_withdraws_the_retained_readiness_value, lease_health_is_false_after_an_unpolled_abort_or_panic, shutdown_releases_unspent_units, and cancelling_lease_shutdown_aborts_the_owned_release_task.

    "Can still fund work" is the same question admission asks, and it is mode-dependent for the same reason (1). Under Strict it is a lease inside the local usability window with units left. Under Elastic an empty or absent lease is not the end of the answer: an account with overage headroom is admissible, and reporting it unready would withdraw from rotation exactly the instances the mode exists to keep serving — availability masquerading as fail-closed correctness, the same error in the other direction. Readiness reads the mode from the snapshot the request path reads, never a copy, so the two cannot disagree after a republish.

    Elastic readiness does not establish that the first lease has arrived. A workload that requires lease-funded requests must observe installed funding separately; a ready instance with only overage headroom may bill every admission as overage. HTTP tests: an_elastic_account_serves_past_its_deposit_and_bills_the_overage and elastic_readiness_serves_before_the_first_grant_and_recovers_after_funding.

    The snapshot bar depends on how the tracked set is chosen, because the same rule means opposite things at the two scales (GL-48). For a Fixed set — hand-configured, small — ready requires every tracked principal to hold a fresh positive or negative resolution: the set was chosen deliberately, so any gap in it is a real one. For an All set — every principal the source knows, which is the whole customer base — that rule inverts into a fault, holding an instance serving 15,999 of 16,000 principals out of rotation for the one its source cannot answer for. There ready requires only that some tracked principal is resolved, falling when none is; per-principal admissibility needs no help from readiness, because the map already denies fail-closed for anything unresolved. An instance tracking nobody is healthy, not broken.

    InstanceRuntime applies the same split to funding: All requires some fresh active account with usable lease units or elastic headroom; Fixed requires every eligible account to be fundable. Freshness and funding must belong to the same account. The runtime evaluates resolution deadlines at the probe's supplied timestamp and reports unresolved and unfundable counts alongside readiness. With no positive snapshots, the instance is healthy once its tracked resolutions and background tasks meet their requirements. Positive snapshots that are all inactive or stale do not advertise available funding. Tests: an_exhausted_account_withdraws_a_fixed_instance_but_not_a_discovering_one, readiness_checks_freshness_at_the_callers_time_before_a_background_wakeup, and a_fixed_instance_with_only_inactive_accounts_does_not_advertise_funding.

    Readiness is a single bit either way, so it says that an instance is unready and never how much is unresolved; the count of principals without a valid resolution is exported alongside it and is derived from the same pass that decides the resolution part of readiness. Task liveness is separate: an exited task can be unready with a last unresolved count of zero. Enumeration failures are counted apart from fetch failures, since they freeze the tracked set rather than staling it and are otherwise invisible. Tests: initial_load_gates_readiness_and_installs, readiness_falls_when_snapshot_expires_during_outage, readiness_falls_if_refresh_hangs_across_snapshot_expiry, readiness_falls_when_background_planes_stop, one_unanswerable_principal_unreadies_only_a_fixed_instance, snapshot_counters_track_failures_and_the_unresolved_gauge, readiness_closes_the_lease_window_exactly_when_debits_do, and readiness_counts_overage_headroom_for_an_elastic_account.

11. Checked arithmetic only. Cost and lease arithmetic never wraps; any overflow is an explicit error that denies (fail closed), never a wrap to a small charge. Stored ledger values follow the same rule in both directions: a negative unit column is surfaced as an explicit store error, never clamped to zero — clamping would let the conservation equation pass over the corruption it exists to detect. The Postgres schema additionally CHECK-constrains unit columns non-negative, including billing-event units, and every persisted fence strictly positive. Tests: tollgate-core proptests; all seven of negative_account_column_fails_conservation_read, negative_account_column_fails_balance_and_usage_reads, negative_lease_sum_fails_conservation_read, acquire_surfaces_negative_stored_balance, reclaim_refuses_a_negative_remainder, straggler_exceeding_recorded_loss_fails_ingest, and checked_ledger_columns_reject_negative_writes (Postgres suite only; the memory backend makes negative state unrepresentable via u64, so it has no counterpart to any of them); usage_guard_upgrade_preserves_legacy_rows_and_refuses_an_old_catalogue and invalid_history_blocks_validation_but_leaves_write_guards_and_can_be_repaired (Postgres migration suite).

12. No commit outside the usability window. A lease is locally usable until expires_at - safety margin; both debits and commits stop there, and the allocator reclaims only after expires_at + grace (accepting releases and late usage through the window). Work committed inside the window therefore always has margin + grace to be flushed and billed; work cannot commit against capacity the allocator may have re-granted.

    Under Elastic a lapsed window is not a refusal but a change of funding: the charge settles against overage and the lease receipt is returned. The bill it emits therefore names no lease capability, and that follows from the terminal phase rather than the funding receipt. This is not a stylistic choice — the receipt returned to the lease, so the lease never funded that work, and a leased bill would claim units its settlement already accounted for: rejected against a release's credit, silently dropping the charge for work that ran, or billed against a reclaim's forfeit (9) the fallback did not cause. Under Strict the lapse still releases for zero and the kernel must not run. Tests: reservation::tests::{commit_after_window_closes_releases_for_zero, safety_margin_closes_window_before_expiry, an_elastic_lapse_at_execution_start_bills_as_overage_with_no_lease_capability, a_strict_lapse_at_execution_start_releases_for_zero_and_yields_no_event}, engine::tests::a_strict_expiry_at_execution_start_produces_no_committed_guard, reclaim_waits_for_grace_and_release_works_within_it and a_commit_time_fallback_is_ingested_as_overage_after_its_lease_settles (both store suites). Proof: formal/lean/Tollgate/CommitFallback.lean.

13. A committed charge is always emitted. The usage slot is bound at admission, not at commit: RequestContext::admit takes the pre-reserved queue permit and carries it through Pending and ReadyToStart into Committed, whose Drop records the billing event and only then releases concurrency and execution capacity. Normal completion, early return, panic unwind, and task abort therefore all enqueue the event. Binding the slot one stage earlier than the charge removes the window in which a committed request had no place to be billed. ReadyToStart::commit returns the guard directly, rather than hiding it in a tuple, and Committed is #[must_use], so discarding execution-start evidence is rejected under unused_must_use. The guarantee extends through shutdown: the writer's drain waits for the permit, so the event is ingested or explicitly counted in WriterStats::unresolved — never silently dropped. The safe lifecycle order is: stop admitting, quiesce request tasks holding permits or guards, shut the usage writer down, then release leases. A spent lease with no billing event requires losing the whole process. ChargeLifecycle.lean proves the binding in the exact model: a committed request holds the slot bound at reservation (Tollgate.ChargeLifecycle.committed_holds_its_slot), so emitting its event needs no capacity and cannot be refused (Tollgate.ChargeLifecycle.committed_always_emits); the charge is fixed at commit (Tollgate.ChargeLifecycle.commit_charges_admitted_units) and emitted once (Tollgate.ChargeLifecycle.emitted_once, Tollgate.ChargeLifecycle.emit_keeps_charge); and an instance never charges more than its lease granted (Tollgate.ChargeLifecycle.charged_within_grant). Process loss is the stated boundary, outside the model.

    InstanceRuntime owns this order under one total deadline: stop snapshot discovery and pause refills, close the accounting queue and drain issued permits/guards, then release all account leases concurrently. A task still holding a lease prevents its release and is reported at the deadline. Concurrent requests and background failures share the immutable deadline sampled inside the first shutdown publication. Dropping the owner or cancelling shutdown aborts owned tasks; the three component shutdown futures retain their join handles until completion. HTTP embedders start their own bounded quiescence with the runtime's first shutdown request, rather than awaiting an unbounded server drain first. Tests: shutdown_waits_for_committed_usage_before_returning_the_grant, shutdown_with_an_unresolved_permit_still_obeys_the_total_deadline, and a_shutdown_deadline_shorter_than_its_phases_is_rejected, cancelling_writer_shutdown_aborts_the_owned_ingest_task, cancelling_lease_shutdown_aborts_the_owned_release_task, and shutdown_interrupts_normal_ingest_before_its_long_timeout, repeated_shutdown_requests_share_the_first_deadline, http_shutdown_joins_the_listener_and_settles_usage_before_returning, and http_quiescence_is_bounded_by_the_runtime_deadline, a_runtime_stop_closes_the_queue_and_bounds_the_actual_drain, and a_held_reservation_exhausts_and_reports_the_shared_shutdown_deadline, and cancelling_http_shutdown_aborts_the_server_before_or_after_first_poll.

    Unwinding is safe on Tollgate's side by construction: the event is built at commit rather than at drop, so Drop takes no lock that could be poisoned, allocates nothing, and cannot fail — and the shared cancel path is a compare-exchange rather than a mutex precisely so it stays usable from a thread that is already panicking. The panic boundary around the kernel belongs to the consumer, because Tollgate does not run the kernel and cannot wrap it. A panic in a Rayon spawn closure propagates at the join and can abort a pool thread, so without a consumer-installed catch_unwind the guard is leaked rather than dropped on the worker, and a leaked guard emits nothing. Under the production profile's panic=abort unwinding does not exist and the process-loss boundary above is the whole story. Tests: panic_after_commit_still_bills, a_panicking_kernel_under_catch_unwind_still_bills, shutdown_waits_for_committed_guard, committed_charge_holds_concurrency_until_execution_guard_drops, and failed_commit_releases_concurrency_and_accounting_capacity, plus the Committed discarded-result and CancelHandle cannot-commit compile-fail doctests.

14. Account creation is never destructive. Recreating an existing account is a surfaced AlreadyExists in every backend — never an overwrite, never a silent no-op. Tests: recreate_account_is_refused_and_nondestructive (both store suites).

15. Authorization generations never move backward. Positive snapshots and revocation tombstones retain the highest generation observed. A delayed positive at or below a tombstone cannot resurrect a principal, and a delayed older tombstone cannot revoke a newer positive snapshot. The source stores tombstones durably so the rule survives instance restarts; evicting a request-visible entry does not evict its revocation watermark. Reclaiming bounded local history is a separate control-plane transition: it removes visible state and invalidates that incarnation's outstanding reads. Reopening requires a new authoritative read, linearizable against durable source publications and tombstones. A private map/principal/read fence enforces this boundary before account-policy resolution. Pending reconstruction refuses pushes; an unknown response cannot authorize them. Source-read freshness remains an explicit source contract, not something the cache can infer from a generation number or timestamp. The rule is about tombstones, and the implementation now says so: only a generation the source published a revocation at may refuse that same generation back. A generation this instance merely observed orders snapshots — a strictly older one is still refused — but asserts nothing about being dead, so the same generation arriving again is a re-observation. Conflating the two stranded any principal whose row went briefly absent, since the absence inherited the positive's generation and then refused it back forever; that is GL-17's rule — keyed on what the source answered, never on what the instance remembers — applied to admission rather than to TTL selection. Tests: both snapshot-map contract tests, negative_eviction_preserves_generation_monotonicity, revoked_generation_rejects_replay_after_visible_entry_is_evicted, revocation_reaches_instances_via_refresh, snapshot_publish_fetch_and_push, snapshot_publish_fetch_and_generation_monotonicity, and a_vestigial_jsonb_generation_is_ignored_in_favour_of_the_column (which pins which stored number the watermark is, now that a backend keeps only one), a_generation_survives_an_absence_and_returns_unchanged, a_revocation_refuses_its_own_generation_back, a_visible_snapshot_refuses_its_own_generation_again, an_absence_never_makes_a_generation_dead, and a_live_principal_that_goes_absent_recovers_on_the_unknown_ttl together with a_revoked_principal_stays_tracked_and_cannot_be_resurrected — the pair that separates an absence from a revocation at equality, which is the only generation where the two rules differ. Proof: formal/lean/Tollgate/SnapshotCache.lean and formal/lean/Tollgate/SnapshotHistory.lean. Retention witnesses: reclaimed_history_requires_a_fresh_authority_before_replay, a_recreated_principal_rejects_the_old_in_flight_response, refresh_fences_are_bound_to_the_map_principal_and_whole_batch, a_refused_push_invalidates_an_older_reconstruction, an_unknown_revalidation_cannot_reopen_forgotten_history, a_source_read_cannot_overwrite_a_concurrent_revocation, reclaimed_principals_refetch_authority_instead_of_replaying_a_push, an_unseen_principal_needs_authority_once_history_is_full_or_has_reclaimed, a_push_batch_may_not_exceed_the_room_history_has_left, and a_push_for_an_unresolved_principal_is_discovery_not_authority.

16. Unsafe configuration never becomes authoritative. Nonpositive lease TTLs, polling/refresh/reclaim intervals, negative safety margins or reclaim grace, and internally inconsistent lease thresholds are rejected before allocation or task startup. A snapshot is publishable only when both carried weighted-rate scalars fit governor's non-zero u32 domain in full width — including the rollback pair carried while weighted rate is disabled — and when checked arithmetic proves that its worst registered operation at max_items_per_request — including fixed and minimum charges — does not exceed rate_burst_units; overflow and above-burst results are refused at every publication or decode boundary. Tests: nonpositive_lease_ttl_is_rejected_without_debiting (both stores), invalid_lease_manager_durations_are_rejected, invalid_snapshot_manager_intervals_are_rejected, invalid_grant_policy_is_rejected, zero_reclaim_interval_is_rejected, invalid_writer_config_is_rejected, invalid_lease_manager_timeouts_are_rejected, and invalid_pool_config_is_rejected_before_connecting, plus publication_uses_the_largest_registered_weight, publication_rejects_weighted_values_outside_governors_domain, snapshot_publication_matches_u128_worst_case_oracle, admin_refuses_snapshot_whose_batch_quote_exceeds_burst, admin_refuses_weighted_rate_outside_governors_u32_domain, http_store_rejects_invalid_snapshot_from_legacy_server, and legacy_invalid_snapshot_is_rejected_on_read. Proof: formal/lean/Tollgate/SnapshotLimits.lean. Values are never silently repaired: coercing a declared capacity would change its contract.

    Lease TTLs cross HTTP without truncation or saturation. LeaseTtl::try_from rejects nonpositive caller input before a request is built; its wire representation retains positive whole u32 seconds or carries the exact SignedDuration with a zero legacy sentinel. LeaseTtl::duration refuses nonpositive or conflicting declarations before either acquire or consolidation invokes a backend. The allocator alone applies its policy ceiling. Fractional and wide positive TTLs remain valid configuration. Tests: whole_second_ttls_keep_the_legacy_wire_contract, precise_ttls_carry_an_exact_string_and_a_refusing_legacy_sentinel, every_positive_duration_round_trips_in_both_lease_requests, nonpositive_and_ambiguous_ttls_are_rejected, malformed_or_partial_ttl_fields_are_not_repaired, duplicated_ttl_fields_are_rejected_inside_both_request_envelopes, http_acquire_preserves_positive_ttl, http_consolidation_preserves_positive_ttl, postgres_and_http_preserve_ttl_across_acquire_and_consolidation, invalid_wire_ttls_never_debit_or_settle_a_lease, legacy_servers_reject_precise_ttls_and_invalid_input_never_reaches_http, and fractional_and_wide_lease_ttls_remain_valid_configuration.

    Performance-gate configuration rejects unknown keys before policy is used. This includes the benchmark manifest, its trust policy and bounds, recorded baseline settings and load thresholds. A misspelled optional key cannot activate its default or disable a comparison. Explicitly documented comment and reserved-ID metadata is inert; it is not an open extension namespace. Omitted optional trust settings and legacy baseline defaults retain their existing meanings. Every operational load setting remains required; null disables a nullable bound only when its key is explicitly present. Enforcement is inside each owning serde decoder. These are schema and CLI witnesses, not new numerical or performance proofs. Tests: misspelled_gate_settings_never_become_defaults, partial_trust_settings_preserve_explicit_values_and_omitted_defaults, gate_metadata_is_explicit_and_does_not_hide_unknown_settings, baseline_setting_typos_are_rejected_without_changing_legacy_defaults, every_load_setting_is_required_independent_of_json_layout, load_settings_accept_documented_comments_and_reject_unknown_keys, unknown_manifest_keys_fail_before_measurement_reads_or_output_changes, unknown_baseline_keys_cannot_be_used_for_comparison_or_promoted_over, and unknown_load_settings_produce_parse_errors_in_both_verdict_modes.

17. Negative caching is bounded and self-healing. The ArcSwap map retains at most its configured count of request-visible negatives, removes expired negatives during control writes, and evicts the earliest expiry first. Expiry schedules a targeted source pull even when push is unavailable and the full refresh interval is much longer; source errors retry with backoff. In the routine case that targeted pull is the only thing that reresolves a negative: the full sweep covers principals an instance can serve and skips negatives, which already carry a deadline of their own. Broadcast lag is the exception and refetches the unfiltered tracked set, because a dropped push is most often a reinstatement, and filtering by local resolution would skip exactly what recovery is for. Which TTL applies is keyed on what the source answered, never on the generation the instance remembers: an absent row takes unknown_ttl, a published revocation tombstone takes revoked_ttl. Conflating them strands a live principal for the reinstatement TTL whenever a source is merely rebuilding or failing over, while readiness still reports healthy. Pruning visible negatives never weakens invariant GL-15, and neither does skipping them in the sweep: a live principal is always swept, so withdrawing one still propagates within refresh_interval; what the longer TTL bounds is the Negative → Present direction only. Both maps also bound retained generation histories and their eviction index, including pending reconstructions. The client removes reclaimed resolution/deadline entries before source I/O, batches reads within that budget, and rejects fixed sets exceeding it before tasks start. Visible eviction alone is repaired by an equal-generation refresh without making a background probe count as a request-frequency hit. Reclamation cannot reset account lease slots or irreversible spend. This local-history bound does not bound the authoritative catalogue or account spend history. Retention tests: generation_churn_is_bounded_in_both_maps, churn_bounds_both_history_and_its_index, history_reclamation_bounds_resolution_and_deadline_indexes, a_superseded_publication_cannot_claim_a_resolved_deadline, a_discovered_catalogue_larger_than_history_is_refreshed_in_bounded_batches, a_fixed_set_larger_than_history_is_rejected_before_tasks_start, same_generation_refresh_repairs_a_visible_cache_eviction, a_refresh_pass_reserves_at_the_retention_budget_not_per_principal, and the_visibility_probe_tracks_installation_and_eviction_in_every_map. An embedder's own map inherits the unbounded compatibility defaults instead, which both maps here override and therefore never execute: a_map_without_reclamation_never_demands_a_refresh_and_retains_everything, the_default_visibility_probe_answers_from_the_request_lookup, the_default_batch_writes_dispatch_every_update_variant, the_default_install_many_publishes_the_whole_batch, and an_unfenced_reservation_round_trip_publishes_its_reads. NegativeCache.lean proves the exact cache model: it never holds more than its bound (Tollgate.NegativeCache.record_bounded, Tollgate.NegativeCache.prune_bounded); eviction removes an entry whose deadline is no later than any other's (Tollgate.NegativeCache.evict_removes_earliest); pruning keeps exactly the unexpired negatives (Tollgate.NegativeCache.prune_exact); a principal's negative is due at the TTL its source answer selects, whatever was remembered before (Tollgate.NegativeCache.record_sets_answer_deadline, Tollgate.NegativeCache.absent_takes_unknown_ttl, Tollgate.NegativeCache.tombstone_takes_revoked_ttl); and a present answer clears it (Tollgate.NegativeCache.resolve_clears). Pull scheduling, backoff and lag recovery are outside the model. Tests: arc_swap_negative_cache_is_bounded_and_evicts_oldest_deadline_first, arc_swap_control_write_drops_expired_negatives, many_unknowns_leave_only_the_configured_number_visible, http_negative_ttl_refetches_without_push, negative_ttl_retry_is_backed_off_and_recovers_without_push, the_sweep_does_not_refetch_tombstones, revocation_still_propagates_within_the_refresh_interval, a_live_principal_that_goes_absent_recovers_on_the_unknown_ttl, a_reinstated_principal_comes_back_on_the_revoked_ttl, lag_recovery_covers_the_negatives_a_sweep_skips, and deadline_helpers_are_exact_in_the_supported_domain.

18. Background store calls are wall-clock bounded, and so is every pass over them. No background task may be parked by a backend that hangs rather than answering: every allocator, sink, and snapshot-source call a client task makes carries a configured timeout, and each graceful shutdown carries a total budget, so shutdown terminates whatever the backend does. Bounding by retry count alone is not a bound, and neither is a per-call bound on a pass that makes N calls: the lease manager's release pass carries one store_call_timeout across every parked lease, so no loop-body cost scales with the parked count (GL-78). Every long await in a background loop's body is raced against that task's shutdown watch, so the signal is acted on where it arrives rather than at the next loop top — this is what makes LeaseManager::shutdown's documented shutdown_release_deadline bound true. A bound must also let the loop return: a fetch future that never resolves is abandoned at fetch_timeout rather than awaited forever, because a JoinSet that cannot empty stops the snapshot sweep from returning at all, and readiness then falls without ever recovering (GL-103). An abandoned call is counted apart from a refusal — refresh_timeouts beside refresh_failures, as acquire_timeouts sits beside the lease manager's refusals — because a timeout is not a domain answer: the backend may have done the work and simply not said so in time. Racing a call against shutdown is not a substitute for bounding it: it frees the shutdown path and leaves every other caller parked, which is how principal enumeration stayed unbounded after its cancellation was fixed (GL-59). What a bound could not complete is reported — a lease left unreleased is LeaseManagerReport::abandoned and is forfeited at TTL reclaim (GL-9); an undelivered batch is WriterStats::lost — never silently assumed done. Tests: hung_ingest_cannot_stall_shutdown, hung_ingest_times_out_into_the_retry_path, hung_release_times_out_and_reparks, hung_release_cannot_stall_shutdown, shutdown_during_a_hung_acquire_is_not_delayed_by_it, a_hung_enumeration_does_not_hold_shutdown_open, a_hung_enumeration_is_abandoned_so_the_loop_keeps_sweeping, a_zero_enumeration_timeout_is_rejected, a_hung_fetch_is_abandoned_so_the_sweep_keeps_running, a_zero_fetch_timeout_is_rejected, lease_manager::tests::{a_release_pass_costs_one_budget_whatever_the_parked_count, a_lease_that_eats_the_budget_yields_its_place, shutdown_during_a_release_reparks_every_lease}, and invalid_pool_config_is_rejected_before_connecting.

    PeriodRoller bounds each administrative rollover call and the entire multi-batch pass, including yields between batches. Each pass freezes one business-time cutoff; the next pass starts after a configured pause, so a long pass cannot produce a burst of catch-up retries. Shutdown interrupts the pending call and also has its own total join deadline. These bounds assume store futures cooperate with the executor; synchronous blocking cannot be preempted by a Tokio deadline. Witnesses: one_pass_budget_bounds_every_batch_and_preserves_its_progress, a_pass_deadline_can_interrupt_a_call_before_its_own_timeout, a_hung_call_times_out_and_the_next_pass_recovers, shutdown_interrupts_a_hung_call_and_reports_its_uncertainty, and shutdown_has_a_total_deadline_even_if_its_task_does_not_observe_the_signal.

19. A control-plane failure is never silent. Every fallible call a background plane makes either succeeds, is reported through a typed result the caller can act on, or emits a structured event — never nothing. This is what makes "fail closed, the background plane recovers" checkable in production rather than merely intended: retrying forever is correct behavior, so without a report an unreachable backend is indistinguishable from an idle one. Level follows consequence: a refusal the instance can absorb is debug, one that leaves it denying every request is warn, and accounting divergence or a dead task is error. Enforcement is mechanical, not conventional — the library crates deny clippy::let_underscore_must_use, so discarding a fallible call fails the build unless an #[allow] states why there is nothing to say. Tests: refill_failure_with_an_empty_slot_warns, healthy_refill_emits_no_warning (the converse: a healthy plane stays quiet, or the signal is worthless), ping_surfaces_a_closed_pool, and usage_sink_outage_and_recovery_are_reported.

    Snapshot generation decisions own their refusal evidence: both push and refresh paths emit one structured warning per refused positive or revocation and increment SnapshotStats::refused_updates once. Events identify the origin, principal, offered kind/generation and retained watermark. An unchanged visible positive at its current generation is an idempotent no-op, not a refusal to report. Accepted absences and revocations are not counted. Acceptance, retained deadlines, publication and retry backoff retain the shared generation model's semantics (15). Tests: snapshot_refusals_are_reported_and_counted_for_pushes_and_refreshes, unchanged_snapshots_and_accepted_updates_do_not_report_refusals, a_push_reinstates_an_absent_principal_at_its_own_generation, and a_refused_answer_is_retried_with_backoff_not_at_source_latency.

    Release refusal severity and ownership remain consistent at shutdown: invalid counts are an error and abandoned release, never a clean settlement. The shared classification already enforces this in refill and shutdown. Tests: refused_release_at_shutdown_is_reported and shutdown_distinguishes_settled_leases_from_unconfirmed_or_invalid_releases.

    Server reclaim and rollover failures each carry an independent checked consecutive-failure count: the first two are warn, the third and later are error. Recovery emits one info with the preceding count and resets the streak. Three attempts is an alerting policy, not a derived TTL bound; readiness falls on the first failure. Counter exhaustion stops maintenance and is explicit, never wrapping or silently saturating. Task-exit events contain only a static reason, never a backend or panic payload (37). Tests: persistent_failures_escalate_and_recovery_resets_each_operation, failure_counter_exhaustion_withdraws_health_without_wrapping, and readiness_matches_both_operation_outcomes_for_every_short_trace.

    The separately owned security reloader reports unexpected task exit at its drop boundary, without exposing panic text. Its owner marks deliberate stop before abort, including before the task's first poll. This does not change the validity of the previously installed security configuration or signing keys. Tests: a_dead_security_reloader_reports_a_safe_error and dropping_an_unpolled_reloader_is_an_expected_stop.

20. Every admission outcome is counted, exactly once, under its own reason. The request path may not log (5), so its tallies are the only account it can give of itself; an instance refusing every request must be distinguishable from one serving none. The snapshot map owns one shared counter identity and installs its Arc into every request state.

    A request has three deciding stages, and each records exactly one outcome. begin records a stage-one refusal. A successful context records one stage-two outcome when admit consumes it. An admitted request then records one terminal outcome at execution start: it started executing, it was shed by the capacity gate, it was refused by its own funding, or it resolved for zero before starting. Those four partition admitted exactly — execution_started + capacity_shed + refused_at_start + canceled_before_start == admitted — and the partition is enforced by construction rather than by call-site discipline: the execution-lifetime concurrency guard is the one value every admitted request holds exactly once, so its Drop records the zero-charge outcome for any request no later phase claimed, including a pending state that was simply abandoned.

    A context dropped before stage two creates neither pending funding nor an admission outcome, and is counted as contexts_abandoned — its own phase, neither an admission nor a denial. Counting it is the point: an instance authenticating a flood of requests whose bodies never arrive would otherwise be indistinguishable from one serving nothing.

    No later outcome joins the pre-admission denial total. A request refused at execution start was already counted under admitted, so adding it to denials would give one request two contradictory identities; denied() therefore stays pre-admission and refused_at_start() reads the later phase. A cancellation that wins Tollgate's compare-exchange is a Tollgate outcome and is recorded here, not left for the consumer to infer. Commit-time refusals get their own dense vocabulary rather than a second twenty-one-slot table: only four refusals can reach commit, and CommitRefusal::index keeps DenyReason's forcing function — an exhaustive match, stable slots pinned by literal — at the size the outcome space actually has.

    The two elastic qualifiers stay disjoint. admitted_overage counts admissions no lease could fund; committed_at_overage counts admissions a lease did fund whose window lapsed before execution start (3, 12). They answer different operational questions and an account can produce either without the other, so neither is a subset of the other and adding them is never correct.

    DenyReason::index is an exhaustive match, making a slot per reason total by construction and a shared slot unrepresentable; a new variant fails to compile until it has one. Those slots are also stable: the denial tally is exported through the public CountersSnapshot as dense positions, so a reason's number is a contract with whatever reads them. Reasons append at the next free slot and COUNT only grows; renumbering an existing one silently re-attributes a counter a consumer already reads, and stays internally consistent while doing it, so it is pinned by literal rather than left to the permutation check. Denials add no units, because a refusal charges zero (2). units_admitted counts what was quoted, not what was billed — usage events remain the billing record. Refusals decided before the engine is reached (accounting backpressure, 8) are recorded by the embedder against the same tally, so no reason exports a permanent zero that reads as "never happens". An admission that no lease funded is counted under admitted and under admitted_overage, a qualifier rather than a sibling, so a reader of admitted never has to add two numbers to get the total. The qualifier may equal the total when every admission is unfunded; a strict inequality requires at least one lease-funded admission. Tests: indices_cover_every_slot_exactly_once, shipped_slots_and_labels_never_move, labels_are_distinct_and_payload_free, payload_does_not_affect_the_slot, counters_attribute_every_outcome, each_reason_reaches_its_own_slot, denied_requests_add_no_units, concurrent_increments_are_not_lost, shared_counters_follow_engines_and_owned_contexts, metrics_separate_admissions_from_each_kind_of_refusal, an_elastic_account_serves_past_its_deposit_and_bills_the_overage, elastic_readiness_serves_before_the_first_grant_and_recovers_after_funding, an_overage_admission_is_counted_twice_over_and_a_refusal_once, every_admitted_request_reaches_exactly_one_terminal_counter, an_abandoned_context_is_counted_and_denies_nothing, a_consumed_context_is_never_counted_as_abandoned, a_commit_time_funding_refusal_is_counted_under_its_own_reason, a_commit_time_fallback_is_counted_under_its_own_qualifier, an_admission_time_overage_is_not_counted_as_a_commit_time_one, commit_refusal_indices_cover_every_slot_exactly_once, shipped_commit_refusal_slots_and_labels_never_move, every_commit_time_funding_refusal_reaches_a_slot, transition_counters_never_move_the_denied_total, a_sharded_layout_reports_the_same_transition_totals, and concurrency_guard_carries_the_exact_occupied_state.

    The tallies every request touches — admissions, quoted units, denials, execution starts and pre-start cancellations — are partitioned per locality under every lease layout, at least as finely as the lease layout and the host's parallelism, and summed only when read. The shared counter identity is one per map, so an unpartitioned tally would be a line that unrelated accounts contend on; there is no inline variant to fall back to (GL-132). Tests: the_counter_layout_covers_the_leases_and_the_host_as_a_power_of_two, the_default_lease_layout_still_separates_localities, and each_counter_occupies_its_own_cache_line.

21. Every opaque identifier has one portable wire spelling. AccountId, KeyId, LeaseId, RequestId, and Principal are exactly 32 lowercase hexadecimal characters without a prefix in human-readable serialization and URL paths. PolicyRevision is the same rule at 64 characters, being 256 bits rather than 128.

    One rule, at two widths — validate_hex_digits is the single function both go through, and ParseIdError carries the width it was applying so a caller is never told a 64-digit value should have been 32. Two parsers that had to agree would be the defect; the widths are nevertheless enforced separately, and each rejects the other's canonical form. Strictness earns its keep differently for the revision: nothing in Tollgate reads it, but a consumer compares it for equality to select its own metadata, so two spellings of one revision would silently look like two policies. A malformed path is a structured invalid-id, never an unknown principal; only a structured 404 unknown-principal is negative evidence that may enter the authorization cache. The pre-public v1 contract is updated in place; numeric identifiers are rejected rather than silently reinterpreted. PostgreSQL's storage-local snapshot JSON deliberately retains numeric ids in the legacy u64 range and uses canonical text for values the old codec could not represent. The owning conversion keeps pre-existing rows and ordinary writes rollback-safe while extending storage to the full u128 domain. Tests: every_id_uses_the_same_fixed_width_lowercase_hexadecimal_text, identifier_text_round_trips_the_full_u128_domain, revision_text_round_trips_the_full_256_bit_domain, noncanonical_revision_spellings_are_rejected, the_two_identifier_widths_reject_each_others_canonical_form, the_parse_error_names_the_width_it_expected, revision_serde_is_textual_and_strict, high_bit_ids_are_portable_text_in_an_untyped_json_consumer, identifier_failures_are_structured_and_never_unknown, an_unstructured_route_404_is_not_a_confirmed_unknown_principal, full_stack_over_loopback_http, snapshot_json_preserves_legacy_numbers_and_encodes_high_ids_exactly, and malformed_storage_id_explains_both_accepted_representations.

22. An account's status has one writer and one propagation path. The ledger's tollgate_accounts.status and the AccountStatus inside every live snapshot of that account are written by a single transactional operation, AdminStore::set_account_status, and cannot be observed disagreeing: either the ledger moved and every live snapshot of the account was republished carrying it at generation + 1, or nothing moved. Snapshots already at the target status are not rewritten, so a repeat converges and bumps no generation. Revoked principals are never republished — resurrecting a tombstone is what GL-15 forbids, and revocation stays a separate per-credential mechanism. A snapshot published directly with a status contradicting the ledger is refused, not accepted and reconciled later. Closed is terminal: an account enters it from any status and leaves it never, and the refusal changes nothing. Suspension does not reclaim outstanding leases — their units were debited at grant and GL-9 already bounds them — so the bound on "requests stop" is one SnapshotManager refresh interval, not zero. The operation reports what it changed: how many snapshots it republished, and how many changed durably but could not be decoded to push, so a partial result is surfaced rather than absorbed. StatusPropagation.lean proves the exact model: the ledger and every live snapshot always agree (Tollgate.StatusPropagation.setStatus_agrees, Tollgate.StatusPropagation.publish_agrees); a change republishes exactly the account's live snapshots not already at the target, each at generation + 1 (Tollgate.StatusPropagation.setStatus_restamps_exactly), never a tombstone (Tollgate.StatusPropagation.revoked_never_republished) and never backward (Tollgate.StatusPropagation.generation_monotone); repeating it changes nothing (Tollgate.StatusPropagation.repeat_changes_nothing); a contradicting publication is refused (Tollgate.StatusPropagation.contradicting_publication_refused); and Closed is terminal (Tollgate.StatusPropagation.closed_is_terminal, Tollgate.StatusPropagation.closed_stays_closed). The operation is atomic by assumption. Tests: suspending_an_account_stops_leases_and_republishes_its_snapshots, suspension_republishes_only_the_suspended_accounts_snapshots, suspending_an_account_does_not_resurrect_revoked_principals, reactivating_an_account_restores_admission_and_bumps_generations, a_closed_account_cannot_be_reactivated, repeating_a_status_change_publishes_nothing_new, a_status_change_pushes_every_republished_principal, a_non_active_account_refuses_leases, creating_a_suspended_account_denies_from_birth, unknown_account_status_update_is_refused, and publishing_a_snapshot_that_contradicts_the_ledger_is_refused, and a_status_change_that_cannot_republish_moves_neither_record (all mirrored across both backend suites); the_account_column_is_derived_for_both_stored_id_spellings and an_unrecognized_status_column_is_a_storage_error (PostgreSQL); account_status_transitions_keep_the_two_records_equal (property); account_status_text_matches_its_serde_spelling and restamping_preserves_everything_validation_depends_on (core); account_status_endpoint_speaks_the_status_vocabulary (server).

23. A cached credential proves identity, never authorization, and never outlives its own validity. A SessionCredential may reuse a Principal only within the session it verified in, only when the presented credential is byte-for-byte equal under a constant-time comparison to the one whose verification produced it, and only while that verification is still reusable at the caller's now. A missing or different credential clears that session's proof before any replacement is verified, so a failed verification can never leave the previous principal reusable; failed and already-expired verifications are never cached.

    The validity bound is what makes the verifier seam safe to open. Schemes the seam invites — PASETO, JWT, client certificates — carry expiry, and a cache that ignored it would honour a dead token for as long as a session stayed open, with admission unable to compensate because expiry is a property of the credential and not of the account snapshot. Verified::reusable_until carries it, and HmacRegistry populates it from the credential's own not_after when its record carries one (GL-104). A key without one is indefinite: it expires only by withdrawal, and withdrawal travels by snapshot.

    A cache hit skips the credential check and nothing else: every request still enters AdmissionEngine::admit and consults the current snapshot, so status, staleness, permissions, rate and quota are decided fresh and revocation stays bounded by snapshot refresh exactly as it is with no cache at all. That is why this lives in tollgate-auth rather than in each embedder: the ordering above is a security convention, and conventions upheld by caller discipline at many call sites drift.

    The credential bytes live only in that session-scoped cache — never in the verifier, durable state, or logs — and are wiped on drop rather than merely freed, so a core dump cannot recover credentials from sessions that have closed. Drop for VerifiedCredential is what enforces that, and it is witnessed: reading the buffer after the drop would be undefined behaviour, so the wipe is observed from inside the drop instead — the last instant those bytes are still defined to read. SessionCredential.lean proves the exact cache model for any verifier: every principal the cache returns is what the verifier answers for the presented bytes and is still reusable at now (Tollgate.SessionCredential.answer_is_current_verification, Tollgate.SessionCredential.authenticate_sound); a hit requires the identical credential and a reusable proof (Tollgate.SessionCredential.hit_requires_identical_and_reusable); a changed or failed credential never leaves the previous principal reusable (Tollgate.SessionCredential.fresh_replaces_or_clears, Tollgate.SessionCredential.failed_verification_clears); an expired answer is neither returned nor cached (Tollgate.SessionCredential.expired_answer_refused); and sessions are isolated (Tollgate.SessionCredential.sessions_isolated). Constant-time comparison and the wipe on drop are Rust obligations. Tests: an_unchanged_credential_is_verified_once_per_session, the_cache_is_isolated_per_session, a_failed_replacement_does_not_leave_the_previous_principal_usable, a_changed_credential_revalidates_as_the_new_principal, a_prefix_or_extension_of_the_cached_credential_is_not_accepted, no_credential_is_retained_in_the_registry, the_cache_works_with_an_arbitrary_verifier, a_cached_answer_does_not_outlive_the_validity_it_was_given, an_already_expired_answer_is_refused_and_not_cached, an_expired_answer_that_no_longer_verifies_denies, a_dropped_cache_entry_is_wiped_not_merely_freed, and every_forwarding_impl_reaches_the_verifier (tollgate-auth); price_route_requires_connection_context and cached_principal_still_observes_snapshot_revocation (pricing-api, the wiring).

24. Steady-state embedding admission allocates nothing it owns and performs exactly one snapshot lookup. After the measuring thread has initialised dependency-owned thread-local state and the bounded usage queue has a reusable block, cached authentication through usage-slot reservation, begin, body-independent usage-slot reservation, stage-two admission, commit or cancellation, and usage recording performs no heap allocation or reallocation attributable to Tollgate. Every admission invokes SnapshotMap::get_at exactly once in begin; RequestContext::admit never re-enters the map or calls get. An implementation may still satisfy get_at through the trait's compatibility default. Body decoding and later execution consume the owned context and typed pending/committed evidence rather than retrieve policy again.

    This is an enforcement-ladder rung 3 convention because it spans four crates and neither Rust's type system nor any one owning component can express process allocation or map-call cardinality. A test-only global allocator scopes counts to the current thread, while a forwarding map decorator counts the observable lookup calls. Cold first-touch allocation by dependencies, Tokio queue-block acquisition, caller-owned request buffers, and the consumer executor's job object are not hidden: the gate reports them under separate attribution lines. Moka and governor's internal monotonic reads likewise do not become policy time; snapshot and lease decisions continue to use the caller's Timestamp.

    Moka's access-log housekeeping is dependency-owned amortized allocation, not a strict zero-allocation promise for every individual cache read. Its separate allocation witness enforces the existing per-call average budget over its batch; Tollgate-owned admission scopes remain zero.

    Tests: a_box_inside_the_scope_is_counted, alloc_zeroed_and_realloc_are_both_visible, a_pure_scope_is_zero_and_outside_work_is_excluded, another_threads_allocations_are_excluded, and nested_scopes_compose_and_panics_restore_the_depth, and report_rows_are_appended_as_valid_json_lines (tollgate-alloc-count); core_hot_path_allocates_nothing (core); a_cached_credential_allocates_nothing (auth); admission_allocates_nothing_on_the_arc_swap_default, configured_and_disabled_guards_allocate_nothing_after_warmup, moka_reads_stay_within_their_amortized_allocation_budget, and admit_consults_the_map_exactly_once (admission); and embedding_path_allocates_nothing_after_warmup (client). The required allocation-assertions CI job runs them through scripts/check_allocations.sh and proves the counter crate has no normal reverse dependency from a release binary.

25. Concurrency ceilings are exact, per instance, and released once. Each stable account and principal gauge tracks every admitted request, including while its optional ceiling is absent. Before first activation, occupancy is direct-indexed by request locality so opt-in sharding does not recreate a shared cache line. Activation publishes a draining phase before the new policy. Draining seals the shards to new permits; it does not suspend admission. An acquisition carrying no ceiling of its own is never refused by another policy's activation, and one carrying the activated ceiling is admitted on the central counter bounded by that ceiling less the undrained shard residue — that residue is live work and occupies the ceiling being published, so total occupancy never passes it. Enabling a ceiling therefore narrows admission to that ceiling instead of closing the account for the lifetime of the longest request already running. Exact shard permits release to their owning counters, and only an all-zero shard set can atomically promote to the central CAS-bounded counter. Once central, the gauge never resets or returns to sharded tracking, so disabling and re-enabling retains occupancy; a ceiling withdrawn while the handoff is still draining, before any central work exists, does return the gauge to sharded tracking. A successful bounded compare-exchange never increments at or above the configured ceiling.

    The account ceiling comes from the same canonical AccountPolicyState every principal loads for rate policy. A configured principal ceiling is validated not to widen its account ceiling, acquired first, and undone if the account acquisition refuses. Both gauges are counted per service instance, like local rate state rather than fleet-wide leased funding.

    Occupancy survives snapshot replacement and cache eviction: account and principal registries retain weak references, while installed state and an in-flight RAII guard keep the exact gauges strongly reachable. The guard is constructed only after both occupancy increments and owns the exact state containing both gauges; it has no callable release operation. Every field of RequestContext, Pending, ReadyToStart, and Committed is private, and the guard moves from Pending through ReadyToStart into Committed without ever exposing a raw Reservation: cancellation consumes the state that holds it, and commit consumes it into the execution guard. The public commit result is the must-use guard itself, not a tuple that suppresses its diagnostic. Safe code therefore cannot retain committed funding while accidentally dropping the concurrency authority. Witnesses: the Pending private-reservation compile-fail doctest (E0616, with its companion that pins the refusal to the field rather than to a vanished API), and the Committed discarded-result doctest under unused_must_use. The concurrency guard is the last admission field dropped and releases account then principal exactly once on cancellation, refusal, panic unwinding, or ordinary drop. The unbounded path performs the same two occupancy transitions against its locality shards without a limit comparison or scan; both paths remain allocation-free. Shard scans are confined to the one-time activation handoff: once when control publishes it, once more when a ceiling-carrying request computes its headroom while that handoff is open, and then only when a formerly nonempty shard releases its last old permit.

    Tests: account_concurrency_is_held_for_the_admitted_lifetime, a_principal_ceiling_narrows_without_bypassing_the_account_ceiling, every_principal_observes_the_canonical_account_concurrency_ceiling, newer_account_concurrency_policy_reaches_existing_principals, enabling_account_concurrency_counts_already_in_flight_work, enabling_principal_concurrency_counts_already_in_flight_work, reenabled_account_concurrency_counts_work_admitted_while_disabled, a_later_funding_refusal_releases_concurrency_but_keeps_rate_tokens, an_in_flight_principal_gauge_survives_removal_and_reinstall, and concurrent_gauge_never_exceeds_its_ceiling_and_releases_exactly_once, enabling_a_concurrency_ceiling_observes_unbounded_occupancy, activation_admits_within_the_new_ceiling_while_old_work_drains, publishing_a_ceiling_arms_the_gauge_before_the_policy_is_readable, withdrawing_a_ceiling_mid_handoff_returns_the_gauge_to_sharded_tracking, a_concurrent_activation_never_denies_an_unlimited_caller, unbounded_gauge_fails_closed_at_its_representation_limit, concurrency_guard_carries_the_exact_occupied_state, committed_charge_holds_concurrency_until_execution_guard_drops, failed_commit_releases_concurrency_and_accounting_capacity, and the Pending raw-reservation compile-fail doctest — pinned to E0616 and paired with a compiling companion, so it cannot pass for an unresolved name or a vanished API; formal witnesses Tollgate.ConcurrencyGauge.successful_acquire_never_exceeds_account, successful_acquire_never_exceeds_principal, principal_ceiling_cannot_bypass_account, account_refusal_undoes_principal, release_restores_counts, a_second_release_is_refused, execution_start_transfers_without_releasing, pending_cancel_releases_occupancy, execution_finish_releases_occupancy, and released_owner_cannot_release_twice, plus publication_preserves_occupancy, activation_with_existing_occupancy_enters_draining, draining_admits_an_unlimited_acquisition, draining_admits_below_the_activated_ceiling, draining_acquire_never_exceeds_the_ceiling, draining_refuses_a_ceiling_the_residue_already_fills, nonempty_shards_cannot_promote, drained_shards_promote_to_central, central_disable_reenable_preserves_occupancy, central_reenable_observes_existing_work, and promote_outside_its_precondition_is_a_no_op, which establishes that promotion's precondition lives inside promote_if_drained rather than in its callers — so release_shard's guard is a cost short-circuit, and the mutation excluded in .cargo/mutants.toml is equivalent rather than untested.

26. A staged request retains its principal generation and reads one current account authority at admission. AdmissionEngine::begin performs the one principal lookup and returns an owned RequestContext containing the exact Arc<AccountAdmissionState> and its selected locality. The installed state pins its immutable snapshot; a later publication cannot change its principal permissions, batch limit, cost table or policy revision. Account-wide rate and concurrency policy is shared through one authority, loaded once in stage two (5). Retaining an old independently spendable rate bucket would multiply capacity. Stable concurrency gauges remain shared across generations because resetting live occupancy would violate their ceiling. For principal validity, stage two consults the pinned snapshot: it rechecks that snapshot's expiry boundary and tests the workload's per-class work permissions against the permissions that snapshot pinned. Both read the context it is consuming, never the map, so neither can observe a generation the request did not begin with. Route permission is checked once, in begin; work permission cannot be, because which classes a request touches is a property of its decoded body. Status or permission changes published after begin govern the next request, never splice two generations into one.

    This is enforcement-ladder rung 1 for ownership and single use: the context owns the state, has no engine borrow, is not cloneable, and admit(self, ...) consumes it. Map-call cardinality remains the rung 3 witness in (24). Tests: a_workload_requiring_ungranted_bits_is_denied_at_stage_two, a_workload_within_granted_bits_admits, a_staged_context_keeps_principal_policy_after_republication_and_owner_drop, stage_two_checks_the_pinned_expiry_after_republication, a_staged_context_observes_account_rate_published_after_begin, limit_change_is_one_account_authority_for_every_principal, and admit_consults_the_map_exactly_once.

Ledger roles (context for 1 and 7): leases bound spend; usage events are the billing record; reconciliation compares the two and steady-state drift is zero. Per account, exactly:

deposited + overage_recorded
    == balance + active lease grants + settled usage + settlement loss + expired

Read it as a funding statement: the left side is everything the account was ever funded with — money in, and credit extended under Elastic (1) — and the right side is where those units now sit. overage_recorded is a funding term, not a bucket: overage usage also lands in settled usage, so without it the equation would fail by exactly the overage and reconciliation would report corruption on a correctly working ledger. expired is the mirror of that on the sink side: units a closed budget period took away (28) are neither spendable nor billable, and without a resting place the equation would fail by exactly the units that expired. Both sides use checked arithmetic and an overflow answers "violated" rather than wrapping (11), because this equation exists to detect corrupt state and must not be able to launder it. Tests: conservation_requires_an_exact_equation_without_overflow, overage_funds_the_usage_it_bills, expiry_accounts_for_an_allowance_that_was_never_spent, overflowing_the_funding_sum_is_a_violation_not_a_wrap, overage_usage_is_billed_and_funds_itself and settlement_is_unaffected_by_an_account_carrying_overage (both store suites); Tollgate.Conservation.overage_preserves_conservation, unfunded_overage_always_breaks_conservation, rollover_preserves_conservation and unrecorded_expiry_always_breaks_conservation.

27. A credential is durable before it is disclosed, and its digest table is a projection. Credential lifecycle is control-plane state like every other: the durable record lives behind [KeyDirectory] and the verifier holds a read projection of it, installed whole. Two orderings are load-bearing and neither is recoverable if broken. Durability before disclosure: the record commits before the secret is returned to anyone, because a crash between the two leaves a credential the server has never heard of, and the digest cannot be recovered from the record — that being the point of storing digests. Replacement, never merge: a projection that merged would keep verifying a credential the directory has already retired, so the directory decides which credentials are live and the registry reflects a complete committed revision of that set. A refresh window can lag later commits; failed refresh preserves the prior table without extending its finite deadline (34).

    Last-committed activity is derived separately from canonical accepted usage (35), never from or into this projection.

    The secret never reaches a store and the server secret never leaves the verifier, so neither half alone verifies or mints anything — the property HMAC is paid for, preserved across the persistence boundary rather than only within one process.

    Revocation is durable and terminal, like a snapshot tombstone (GL-15): a retired credential is never resurrected, and issuance refuses to overwrite an existing KeyId rather than silently retiring what it replaces. A credential's own not_after is enforced by the directory, so every backend answers "active" the same way. KeySource pages bind records to a revision in the same backend read. The manager accepts only a complete coherent drain and narrows it with source and instance expiry checks. The projection may cross the instance-only secured control-plane link (32); it cannot invent liveness absent from the selected ledger revision.

    The disclosed secret is the credential as presented: HmacRegistry::mint mints 64 lowercase hexadecimal characters and digests exactly those bytes, and issuance discloses them without re-encoding. An embedder issuer whose secret is not presentable text is refused before its record is stored. Tests: a_minted_credential_verifies_as_the_text_it_is_disclosed_as, an_issuer_minting_an_unpresentable_secret_is_refused_before_storage, and the_binary_issues_from_a_manifest_configured_issuer.

    Binding a policy by credential cannot resurrect a retired one either. KeyDirectory::publish_key_snapshot resolves the principal, refuses a revoked credential and publishes in one store operation: MemoryStore under its shared mutex, PostgreSQL holding the credential row FOR SHARE against revocation's FOR UPDATE. So a racing revocation either precedes the publish, which is then refused, or follows it. Withdrawal by credential remains allowed, because revocation does not withdraw a snapshot. Tests: a_retired_credential_is_never_granted_a_snapshot_but_can_be_withdrawn (shared backend scenario), key_bound_publication_and_revocation_serialize (PostgreSQL), and a_retired_key_cannot_be_granted_a_snapshot_but_can_be_withdrawn (HTTP).

    Both credential issuance methods serialize on the owning account before inserting a credential. PostgreSQL owns this order in one shared transaction implementation; MemoryStore holds its shared mutex. With an existing account and room under the supplied bound, two competing attempts to create the same previously absent key or principal yield one success and one AlreadyExists, without an account/credential lock cycle. The unbounded API still omits the live-key limit. Tests: mixed_issuers_report_duplicates (shared backend scenario), mixed_issuers_waiting_on_an_account_report_duplicates (PostgreSQL lock-queue witness, covering key and principal uniqueness).

    New credential expiry is preserved at nanosecond precision through every backend read and projection. PostgreSQL's StoredInstant representation and schema constraints own the exact pair; a missing component is a storage error, never an indefinite credential. Migration 0018 marks legacy finite rows with the earliest compatible expiry and fences old readers/issuers. It cannot extend source authority. Existing cached proofs must be cleared during the coordinated upgrade described in docs/CREDENTIAL_PROJECTION.md. Tests: credential_expiry_is_exact_in_directory_and_every_page (both stores), credential_expiry_preserves_the_final_fractional_second, credential_expiry_upgrade_bounds_legacy_authority_and_fences_old_queries, invalid_credential_history_or_revision_overflow_preserves_the_old_schema, credential_expiry_constraints_and_readers_refuse_incomplete_evidence, an_indefinite_catalogue_migrates_without_inventing_expiry_or_revision, memory_expiry_reaches_http_projection_and_session_exactly, postgres_expiry_reaches_http_projection_and_session_exactly, and repairing_source_expiry_requires_resetting_preupgrade_cached_proofs. Proof: the legacy lower-bound and reset-session theorems in formal/lean/Tollgate/CredentialProjection.lean; actual schema and session behavior are separate implementation witnesses.

    Per-credential withdrawal reaches the request path by the mechanism that already exists: a Principal is the credential's digest fingerprint, so revoking one is install_revoked for that principal, and admission already denies a tombstoned principal on every request regardless of what any verifier's cache holds.

    Tests: a_minted_credential_verifies_until_it_is_revoked, a_credentials_own_expiry_travels_to_the_verifier, rotation_keeps_both_credentials_live_until_the_old_one_is_retired, issuance_refuses_a_duplicate_key_or_an_unknown_account, and minting_never_repeats_a_credential, credential_diagnostics_never_disclose_issuer_or_customer_secrets; plus the paging, freshness and transport witnesses in 34.

28. A budget period is crossed exactly once, and only its allowance expires. An account may carry a [BudgetSchedule]: an allowance replenished each period, with unspent units that do not carry over. The balance is therefore two buckets — the current period's allowance and manual top-ups — spent allowance-first, so the units with an expiry date go first. A rollover deposits one allowance, expires what is left of the old one, and moves the account's period marker, all in one transaction. Manual top-ups are never touched by a boundary; that is what the split exists to guarantee, and a single balance could only expire both or neither.

    Crossing is the store's job, not the caller's. The scheduled pass runs on every control-plane replica, so two of them will race a boundary: the backend crosses it under a row lock (a mutex in MemoryStore, FOR UPDATE SKIP LOCKED in PostgresStore) guarded on the stored period, and the loser finds the account already current. A caller that read the period and then rolled would produce two deposits under exactly that race. One allowance is deposited however many boundaries have passed — an account left unrolled for two months is entitled to what its schedule gives it now, not to a backlog. The pass is bounded per transaction and its caller drains saturated batches, because every scheduled account comes due at the same instant.

    Direct-store scheduling has an owner. PeriodRoller runs an immediate startup pass and periodic bounded drains through AdminStore. It owns no account catalogue or calendar logic. A cloneable monitor retains confirmed progress and derives task death from channel closure, so a stale healthy publication cannot conceal a dead task. A partial batch means this pass completed, not that every account is current: PostgreSQL can skip rows held by another replica. Errors, timeouts, and interrupted calls may have committed unknown work; confirmed totals exclude it and uncertain_calls preserves that distinction through recovery and shutdown. Counter overflow is explicit and stops further scheduling. Dropping the owner or cancelling shutdown aborts the owned task. Witnesses: startup_drains_saturated_batches_without_waiting_for_a_tick, a_pass_freezes_its_cutoff_even_when_the_clock_crosses_another_boundary, failure_preserves_confirmed_progress_and_waits_before_retrying, uncertain_commits_remain_visible_after_recovery_and_shutdown, a_task_that_dies_after_a_healthy_pass_is_reported_failed, dropping_the_owner_or_an_unpolled_shutdown_aborts_the_task, cancelling_a_polled_shutdown_keeps_ownership_of_the_task, generated_period_and_failure_traces_preserve_funding_and_observations, and counter_overflow_preserves_the_last_known_totals_and_reports_incompleteness. Tollgate.PeriodRoller.every_trace_is_safe, at_most_one_owned_call, cutoff_is_frozen_during_a_pass, and stopped_is_terminal prove the abstract ownership and transition rules; paused-time tests witness actual Rust scheduling and cancellation.

    Leases drain, then expire. An active lease at a boundary keeps serving to its own TTL: there is no admission gap, and the request path still reads no clock for policy. The boundary is applied at release instead, where a lease funded by a period older than the account's credits its unspent allowance half to expired rather than to the balance. The top-up half returns to its bucket either way. The reclaim sweep credits nothing at all (9), so it cannot resurrect a closed period's allowance: its remainder is forfeited as loss. Usage is unaffected, so a straggling event bills against the period its lease was granted in.

    What an instance is told is a projection, never an authority. A published snapshot carries a [BudgetView] — what the account could still spend at publication, its balance plus every active lease's unspent remainder, and when the period ends. The store stamps it on every publish and is its only writer: AccountSnapshot's builder has no setter, and the overwrite is unconditional, so a value arriving over the wire cannot survive publication. Absent means the control plane said nothing, which a reader reports as nothing rather than as a zero balance.

    estimate_remaining subtracts what the instance has admitted since that publication, saturating at zero. It is an estimate, wrong by the fleet's spend elsewhere and by this instance's cancelled admissions, both of which make it read low rather than high. It never decides admission: quota comes from the lease and the ledger (1), so a stale figure cannot turn a refresh delay into an outage.

    This is rung 2 of the enforcement ladder: the store owns the crossing, the settlement decision, and the published view, and none is expressible by a caller. The expired term makes the outcome auditable rather than merely correct — see Ledger roles. Tests: racing_passes_cross_a_boundary_exactly_once, a_top_up_survives_rollover_but_the_allowance_does_not, a_missed_period_does_not_accrue_a_backlog, a_lease_from_the_closed_period_expires_its_unspent_allowance, a_lease_funded_by_a_top_up_is_unaffected_by_a_boundary, a_split_funded_lease_charges_the_allowance_half_first, reclaim_never_resurrects_a_closed_period_lease_it_sweeps, the_rollover_pass_is_bounded_and_saturation_says_there_is_more, and the_allowance_split_cannot_exceed_what_it_is_part_of (both store suites but the last, which is the PostgreSQL schema's half); a_published_snapshot_carries_the_ledgers_budget, the_budget_view_counts_units_out_on_lease, the_budget_view_does_not_report_expired_units_as_spendable, the_budget_view_writes_off_settlement_loss, a_supplied_budget_never_survives_publication, an_instance_reports_no_estimate_when_the_control_plane_reported_no_budget, an_estimate_subtracts_what_this_instance_admitted_since_publication, a_republish_rebases_the_estimate, an_estimate_saturates_at_zero_rather_than_wrapping, a_committed_request_reports_the_estimate_its_response_carries, an_exhausted_estimate_does_not_deny, a_snapshot_without_a_budget_key_decodes_as_no_budget, a_partially_populated_schedule_is_reported_not_interpreted, and an_unrecognized_stored_schedule_name_is_refused; Tollgate.Conservation.rollover_preserves_conservation, a_rollover_never_touches_a_top_up, a_top_up_funded_lease_expires_nothing, and unrecorded_expiry_always_breaks_conservation.

29. The application's policy identity is carried, never interpreted. A snapshot may name the product policy it was compiled from — a [PolicyRevision], 256 opaque bits — and every charge admitted under that snapshot is billed carrying the same value. Tollgate stores it, transports it, and hands it back; it never parses, hashes, orders, or branches on it. That is what keeps product vocabulary out of an enforcement substrate while still letting a consumer say which of its policies priced a request.

    It is pinned with everything else. The revision a request reports is the one its snapshot carried when begin resolved it, so a republication mid-request reaches the next request and not this one (26). A consumer can therefore resolve its own customer-visible metadata locally from the same value, with no I/O, and know it describes the policy that actually priced the work. Committed::policy_revision reads it from the usage event it will emit rather than from the snapshot a second time, which is what makes "what the response says" and "what the bill says" one value rather than two reads that agree.

    Distinct from generation, in both directions. [Generation] orders publications and decides staleness (15, 26); this identifies the inputs one publication was compiled from and carries no order at all — which is why it is deliberately not comparable. Two generations may share a revision (the same policy republished after a status change) and each generation carries exactly one. Neither may be derived from the other.

    Unstated is a value. All zeroes means "no revision stated", and an absent field on the wire or in storage decodes to it rather than failing. That is safe precisely because nothing in Tollgate reads the value: an unstated revision cannot change an enforcement outcome, only the identity reported alongside one. Tests: a_committed_event_carries_the_pinned_revision, an_unstated_revision_reaches_the_charge_unstated, a_republished_revision_does_not_reach_an_already_pinned_request, a_snapshot_without_a_revision_key_decodes_as_unstated, a_builder_without_a_revision_states_none, an_event_without_a_revision_key_decodes_as_unstated, a_revision_survives_the_event_round_trip_exactly, the_unstated_revision_is_all_zeroes_and_round_trips, the_policy_revision_is_cold, a_snapshot_revision_round_trips_through_the_store and ..._through_postgres, a_usage_event_is_ingested_with_its_revision_and_conserves, a_usage_row_carries_its_policy_revision, a_usage_row_cannot_carry_a_wrong_width_revision, a_legacy_snapshot_document_defaults_the_revision_to_unstated, admin_preserves_the_policy_revision_over_http, admin_refuses_a_noncanonical_policy_revision, full_stack_over_loopback_http, and the_response_and_the_bill_name_the_same_policy_revision.

30. Execution capacity is conserved, and the reserve is reachable. An instance may bound how much work it starts, separately from what an account may fund. Capacity is two exactly partitioned pools — shared plus an assured reserve — and at every instant live permits from both sum to at most the configured total. Each successful acquisition returns exactly its unit, to the shard and pool that issued it, exactly once when its permit drops.

    Best effort cannot consume the assured reserve. Under every concurrent interleaving, best-effort permits are funded only from shared. A saturated best-effort flood therefore leaves the configured reserve reachable by assured work — which is the entire point of the feature, and is why the reserve transition takes the class's permission as a precondition rather than checking it. Both classes try shared first, so an instance with no best-effort traffic is not partitioned against itself: assured work reaches shared and reserve.

    A capacity refusal is zero-charge. A request that never obtains capacity returns all pending funding, resolves its writer permit without an event, and records neither settled usage nor overage. Rate tokens stay consumed — the request arrived and was priced, and refunding them would amplify an overload retry loop. It is counted as capacity_shed, its own terminal outcome, never as a second pre-admission denial (20).

    Classification is verified and generation-pinned. The class comes from the same immutable snapshot that authorized and priced the request, through evidence with no public constructor. It is never re-derived from caller input or a second lookup, and it is an account-owned fact with one writer (22's ownership, applied to a second field): a snapshot whose class contradicts its account is refused at publication.

    The gate is request-path local. Acquisition is synchronous and fail-fast: bounded in the configured shard count, no I/O, no blocking lock, no allocation, no clock. There is deliberately no queue — holding a request that cannot start would convert a capacity bound into an unbounded latency tail. Pools are sharded on cache-isolated lines for the reason leases are: this gate is global to the instance, so a single atomic would put every core on one line exactly during the overload it exists to handle.

    Disabled means absent. Under ExecutionCapacityMode::Disabled the service composes a zero-sized gate: no capacity state is allocated, no class branch runs, and no capacity atomic is touched. Classification cannot change an outcome because there is nothing for it to change. That is a startup composition boundary rather than a runtime enum, because a branch matched inside every request could not honestly promise it. Tests: capacity::tests::disabled_never_refuses_and_ignores_the_class, uniform_bounds_total_and_treats_both_classes_alike, a_best_effort_flood_cannot_consume_the_assured_reserve, assured_work_reaches_shared_and_reserve_when_alone, assured_work_spends_shared_before_its_reserve, a_sharded_pool_strands_no_capacity, shards_are_capped_at_the_pools_units, a_partition_sums_to_the_whole, a_reserve_that_swallows_the_instance_is_refused, concurrent_acquisition_never_exceeds_the_total, concurrent_best_effort_load_leaves_the_reserve_reachable, engine::tests::a_capacity_shed_is_counted_without_a_second_denial, and the account-ownership witnesses named in 22. The allocation-free and disabled-costs-nothing claims are gated rather than asserted: allocations::acquiring_and_refusing_execution_capacity_allocates_nothing records the capacity/disabled, capacity/uniform, capacity/reserved_shared, capacity/reserved_fallback and capacity/shed scopes at zero under ./scripts/check_allocations.sh, and the capacity/disabled : admission/full_check same-run ratio in testing/perf_thresholds.json bounds what the gate call costs when the gate is NoGate. End to end, load/mixed_saturation drives assured and best-effort traffic at one instance and requires best-effort work to be shed several times more often than assured work, with a class-blind Uniform pool of the same size as the control that says the advantage belongs to the class; api::two_classes_share_an_instance_and_each_start_is_attributed carries the class through the whole embedding, and a_capacity_refusal_is_a_retryable_503_and_not_a_rate_limit pins what a caller is told. Proof: formal/lean/Tollgate/ExecutionCapacity.lean.

31. An account has at most one owned refill manager, including retirement. Runtime membership follows the snapshot map's accepted publication, never a candidate that generation ordering rejected. Catalogue removal withdraws admission and membership together. A fresh active principal makes its account eligible; removal, revocation, suspension, or freshness expiry of its last eligible principal arms a configurable linger. Reactivation cancels linger. After retirement begins, a replacement waits for the prior task's join and backoff. Notifications are matched to their task identity, so an old task cannot retire a new one. Unexpected task death is visible; accounting-integrity faults shut down the instance instead of being erased by restart. Stable slots retain irreversible overage spend for the process lifetime. Tasks and pending transitions scale with eligible, lingering, and retiring accounts; slot and diagnostic history scale with accounts ever seen.

    Enforcement: the runtime owns publication and one supervisor owns manager handles and indexed timers; coalesced registry notifications carry no historical event backlog. formal/lean/Tollgate/AccountLifecycle.lean proves ownership conservation, at most one owner, retirement before replacement, and inert duplicate joins in the abstract transition system. It does not prove Tokio scheduling or Rust refinement. Implementation witnesses: arbitrary_catalogue_churn_retires_each_owner_once, sibling_principals_share_one_manager_and_refresh_does_not_restart_it, reactivation_during_linger_reuses_the_manager_and_later_reactivation_releases_then_refills, retiring_an_elastic_account_does_not_reset_its_spend_cap, a_dead_manager_is_joined_then_restarted_with_backoff, and a_refresh_outage_preserves_a_fresh_accounts_manager, catalogue_removal_withdraws_a_still_fresh_map_entry_and_can_restore_it, suspension_retires_funding_and_reinstatement_starts_it_again, and shutdown_racing_onboarding_joins_every_started_manager, membership_wakes_once_per_publication_and_expires_at_its_exact_deadline, repeated_shutdown_requests_share_the_first_deadline, shutdown_pauses_refills_while_previously_issued_permits_drain, and an_in_flight_release_cannot_start_a_refill_after_shutdown_pauses_it, and a_second_crash_reports_parked_grants_after_releasing_an_inherited_capability, repeated_inactive_publications_do_not_extend_the_initial_linger, and supervisor_exit_withdraws_readiness_before_children_receive_their_abort, and removing_the_last_principal_cancels_a_pending_manager_restart, and integrity_faults_in_idle_and_final_release_are_reported_as_terminal, and shutdown_distinguishes_settled_leases_from_unconfirmed_or_invalid_releases.

32. Control-plane authority is verified before decoding or mutation. Every protected HTTP handler requires private instance, operator or admin (operator-or-provisioner) evidence; middleware authenticates and authorizes before body/path extraction. The roles are disjoint: each route admits one fixed role set, and a credential outside it is refused with 403 scope-forbidden and a refused audit event naming the actor, role and route before any extractor runs (41). A client certificate must pass TLS key possession and current CA/time validation, and its leaf fingerprint must have a role. Bearer schemes return verified principals with validity bounds, mapped to roles in the same immutable generation. Conflicting evidence, expired evidence, missing credentials, and wrong roles fail closed. Forwarded headers cannot manufacture TLS evidence. Probes carry no authority.

    Exposed server listeners require TLS; clients refuse remote plaintext, redirects, and credential-bearing URLs. A reload stages and validates the entire verifier/role/TLS generation before atomic publication. Failed loads preserve the previous generation and its original expiry. New requests recheck current authority even on existing connections; already authorized requests retain their pinned proof. Client transport replacement atomically rotates roots, identity and provider. Handshake count/time and total HTTP call time (including credential retrieval) are bounded off-path.

    The manifest's optional customer-credential issuer is validated with the rest of the generation: exactly 64 lowercase hexadecimal characters, keyed as those bytes, and distinct from every bearer token, or the load fails. It is fixed at SecurityLoader::start for the process lifetime. A later generation naming a different issuer still publishes its TLS and role changes, never replaces the live issuer, and reports the pending change through SecurityLoader::issuer_change_pending and one warning per distinct staged value, so a stray issuer edit cannot freeze certificate or bearer rotation. Neither the secret nor its fingerprint is logged or returned. Witnesses: issuer_secret_files_must_be_exactly_64_lowercase_hex_characters, an_issuer_secret_equal_to_a_bearer_is_refused, the_manifest_issuer_keys_on_the_file_text, an_issuer_change_is_deferred_without_blocking_other_rotation, an_invalid_issuer_on_reload_keeps_the_live_generation, the_binary_issues_from_a_manifest_configured_issuer, the_binary_without_an_issuer_answers_issuance_unsupported, and the_binary_refuses_an_invalid_issuer_before_listening.

    Enforcement: private handler extractors, ServerSecurity, SecureListener, SecurityLoader, and the generation-owning HttpRequest. Exact-model proof: formal/lean/Tollgate/ControlPlane.lean proves role separation, route role-set admission (admission_requires_a_listed_role) and agreement of presented evidence, assuming verification and atomic generation selection. It does not prove cryptography, rustls, Tokio, clock accuracy or Rust refinement. Implementation witnesses: every_control_plane_route_requires_its_own_role_before_decoding, ambiguous_framing_and_forged_peer_headers_authenticate_nobody, exposed_plaintext_is_rejected_before_the_server_starts, unsafe_client_urls_and_deadlines_are_rejected_without_io, control_plane_redirects_are_not_followed, google_tokens_require_signature_issuer_audience_subject_and_live_expiry, signing_keys_never_outlive_the_issuer_cache_policy_or_one_hour, failed_key_refresh_never_extends_verified_identity_validity, security_reload_stages_validates_and_only_then_replaces, a_failed_install_is_retried_and_cannot_remove_tls, file_boundaries_are_part_of_the_rotation_fingerprint, bearer_rotation_changes_existing_connections_and_preserves_usage_for_retry, mtls_and_bearer_fund_and_settle_over_tls_and_revocation_affects_keepalive, a_hung_credential_provider_is_inside_the_http_deadline, google_metadata_cache_refreshes_at_its_exact_deadline_and_never_caches_failure, metadata_requires_success_google_provenance_and_a_complete_bounded_token, client_validation_rejects_each_unsafe_url_component_independently, static_credential_files_enforce_both_length_bounds_and_visible_framing, signing_key_refresh_honors_success_cadence_and_failure_backoff, initial_signing_key_failure_preserves_the_dependency_error, dropping_the_reloader_releases_its_owned_task_and_clock, every_signing_key_must_independently_name_an_rs256_signature_key, signing_key_transport_enforces_status_cache_policy_and_complete_body_bounds, bearer_framing_checks_each_condition_before_scheme_verification, overlapping_bearer_schemes_must_agree_on_the_verified_identity, certificate_configuration_checks_trust_key_pairs_and_handshake_bounds, the_binary_refuses_an_exposed_plaintext_listener_before_opening_the_backend, pending_tls_handshakes_are_bounded_expire_and_drop_with_the_listener, a_refused_role_is_audited_with_its_actor_role_and_action, full_stack_over_tls_bearer and full_stack_over_mtls.

33. An administrative audit receipt describes its own serialized mutation. Each successful HTTP-facing store mutation returns a typed receipt alongside its result, captured under the owning memory lock or PostgreSQL transaction. Concurrent operations must name the actual predecessor they replaced; a separate audit read cannot substitute for that evidence. Idempotent no-ops have equal before/after states. Snapshot state is identified by principal, immutable generation and revocation status; receipts do not duplicate complete policy graphs.

    Budget changes require the budget field; only explicit null clears a schedule. PostgreSQL locks the predecessor before updating the coupled schedule columns. Credential administration uses KeyDirectory's audited methods; issuance reports absence to an unrevoked credential, and retirement reports the actual prior retirement state. Receipts include the owning account and non-secret key ID, never a digest or principal. Binding or withdrawing a policy by credential reports snapshot state under the resource {account}/keys/{key}/snapshot; the store resolves the principal and it never reaches a receipt, response or audit event. Expiry is independent of the retirement flag. Repeated retirement returns equal states. Both credential listings reject malformed or oversized queries as structured client errors before a backend read. Account-scoped listing distinguishes an absent owner (KeyError::UnknownAccount, HTTP 404 unknown-account) from an existing account's empty page. The owning store reads existence and keys under the same memory lock or PostgreSQL statement snapshot; a separate HTTP preflight cannot establish that consistency. Both backends and HTTP are witnessed by account_key_listing_distinguishes_unknown_from_empty. Revocation retains 404 unknown-credential for an absent owner.

    The HTTP admin guard emits actor, role, operation ID, action, resource and time before a store call, then confirms with the receipt, or reports failure or cancellation without inventing a state transition. Storage errors and cancellation can conceal a commit. Delivery uses the embedder's tracing subscriber; this contract does not claim transactional durability across process death or logging failure. The binary retains audit events separately from normal verbosity; operators retain and monitor their log delivery.

    A request refused for its scope never reaches that guard: it emits one refused event with the actor, role, action, resource, time and code, and no started, because nothing was attempted (41).

    Enforcement: AdminReceipt in trait return types, receipt creation inside both backends, and the shared audited guard behind OperatorIdentity::run and AdminIdentity::run around every admin mutation. formal/lean/Tollgate/ControlPlane.lean proves abstract deposit receipt conservation and predecessor composition; checked arithmetic and database serialization are separate implementation evidence. Mirrored backend tests: admin_receipts_identify_the_state_each_operation_replaced, concurrent_deposit_receipts_form_one_exact_funding_history, and racing_publication_and_revocation_receipts_name_the_actual_predecessor. HTTP witnesses: every_admin_mutation_logs_its_actor_and_the_backend_receipt, cancelled_admin_operations_report_an_unknown_commit_without_a_receipt, and normal_log_verbosity_cannot_silence_the_binarys_audit_target. Additional witnesses: a_budget_mutation_requires_explicit_field_presence, explicit_null_clears_while_zero_remains_a_budget_schedule, an_omitted_budget_is_rejected_without_clearing_the_schedule, concurrent_budget_receipts_form_one_serial_history (both stores), queued_budget_updates_report_the_locked_predecessor (PostgreSQL), credential_receipts_identify_issuance_and_concurrent_revocation (both stores), credential_auditing_refuses_a_corrupt_owner_without_retiring_it (PostgreSQL), credential_audits_name_the_key_and_actual_lifecycle_transition, key_snapshot_audits_name_the_key_and_never_the_principal, and both_credential_listings_validate_queries_before_backend_reads. ControlPlane additionally proves generic replacement predecessor composition and credential retirement identity preservation, idempotency and terminality; these models assume serialization rather than prove the SQL lock behavior.

34. A credential projection cannot renew stale identity evidence. A single owned publisher replaces the complete validated active-key table. Duplicate principals or a digest naming a different principal reject the entire set; failed, incomplete or expired reads preserve the previous table and its original deadline. A successful empty set withdraws all entries. Every installed credential carries an exclusive evidence deadline equal to the earlier of its source expiry and fetch start plus configured max_age. Fetch time consumes freshness. Overflow cannot publish authority.

    KeyVerifier exposes verification only. It cannot mint credentials or install an indefinite table. SessionCredential checks its evidence at caller-supplied time (23); cached sessions can survive removal only until their original deadline, and snapshot authorization still runs every request. No request fetches credentials or reads a business clock. A live task and a fresh complete table are required for key-manager readiness; readiness reads the same published deadline as verification. A fresh empty catalogue is healthy. Task teardown clears the published table, while already-issued proofs keep their original bound. Manager drop owns abort, including when its consuming shutdown future is never polled.

    The HTTP read requires instance evidence (32), selects active keys at the server's clock, rejects caller-selected cutoffs, and disallows caching. KeySource gives instances read authority without lifecycle or administrative mutation capability. Both stores derive the projection from their own coherent revisioned active-key pages; transport reconstructs KeyPage identity, ordering, request and expiry evidence. Revision changes discard the candidate and restart within the same pass budget. Budget exhaustion never publishes a partial table or silently succeeds. Installed revisions never move backward. Nullable expiry and continuation fields are required on the wire; partial HTTP responses never become successful reads.

    Enforcement: private CredentialSet, immutable KeyVerifier projection, single-owner KeyManager, and existing session evidence checks. Exact-model proof: formal/lean/Tollgate/CredentialProjection.lean establishes expiry bounds and complete replacement/failure semantics, assuming coherent reads, atomic publication, verified digests and accurate clocks. It does not prove cryptography, Tokio, timestamp representation or Rust refinement. Implementation witnesses: projected_evidence_is_bounded_by_both_source_expiry_and_fetch_start, complete_refresh_replaces_keys_and_cached_proofs_keep_their_original_deadline, an_outage_never_extends_projection_validity_and_recovery_replaces_it, fetch_time_consumes_freshness_and_expired_responses_cannot_replace_the_table, timestamp_overflow_cannot_renew_a_previously_valid_projection, hung_fetches_timeout_retry_and_shutdown_interrupts_the_pending_read, dropping_an_unpolled_shutdown_future_aborts_the_owned_refresh, task_death_withdraws_new_verification_and_is_visible_to_the_monitor, unusable_key_refresh_configuration_is_rejected_before_starting, a_large_legitimate_projection_is_installed_without_truncation, revision_change_restarts_from_the_beginning_instead_of_omitting_a_new_key, page_budget_and_revision_regression_preserve_the_previous_table_and_deadline, page_budget_cannot_publish_an_incomplete_first_table, the_instance_clock_narrows_the_server_set_at_publication, credential_refresh_failure_is_structured_without_exposing_the_source_body, credential_pages_order_bound_skip_retired_and_expose_every_mutation (both stores), credential_revision_covers_direct_writes_rollback_and_overflow (PostgreSQL), maximal_key_pages_fit_the_derived_envelope_and_digests_are_canonical, cached_projected_credentials_remain_allocation_free_through_expiry, only_instances_receive_active_keys_at_the_server_clock_without_caching, http_projection_refuses_partial_ambiguous_or_unsuccessful_responses, the mirrored backend credential_projection_preserves_lifecycle_truth_and_refuses_corrupt_identity, and the three full-stack HTTP/TLS/mTLS conservation tests named in 32.

35. Credential activity derives from canonical accepted commitments. A pinned snapshot supplies its optional key ID when commitment constructs the usage event. Store publication validates a stated key's principal and account binding; custom snapshot producers remain trusted. Publication by credential resolves the principal from the account's own key record inside the same store operation and requires the snapshot to state that key, so an operator never supplies a principal and cannot bind one account's policy to another's credential. Ingest checks account ownership and derives activity only from newly accepted events. Duplicate request IDs cannot replace their original identity or timestamp. Activity advances by maximum at microsecond precision and remains outside the credential revision, snapshots, authorization and conservation equation.

    Missing, unknown or different-account key attribution never rejects an otherwise valid bill. Such accepted events are reported unattributed; older/equal attributable timestamps remain successful no-ops. The count is bounded by accepted events, not the number of credential rows updated. Missing attribution reporting is unknown, never a fabricated zero. Complete report cardinality is validated before a writer releases queued evidence; cumulative outcome overflow saturates and is reported. Storage failures still roll back the complete ingest transaction and remain retryable.

    No observation is proof only of missing recorded evidence, never of non-use. Pre-execution denials/cancellation, unflushed, lost, rejected and unattributed commitments are outside this history. Activity cannot certify that revocation is harmless and never supplies authentication or authorization evidence.

    Enforcement: the shared MemoryStore publication operation and PostgreSQL publication transaction own identity checks; accepted-event classification, the memory plan/apply operation and conditional SQL upsert own activity. UsageWriter validates acknowledgements from every sink. The separate table has no credential-revision trigger; its regression witness checks isolation. CredentialActivity.lean proves exact-model max/idempotency laws, first-event replay identity, report partitioning, revision isolation and atomic failure preservation, assuming correct classification and transaction execution. It does not prove authentication, Rust/SQL refinement or lossless delivery.

    Tests: the shared memory/PostgreSQL scenarios committed_usage_attributes_each_event_and_preserves_replay_identity, missing_unknown_and_wrong_account_attribution_preserve_billing, retired_activity_never_changes_the_credential_revision, publication_checks_the_stated_credential_binding, key_bound_publication_resolves_the_principal_in_the_store, key_bound_publication_is_bound_to_the_account_and_key, concurrent_activity_commits_converge_to_the_maximum, activity_uses_durable_microsecond_precision, activity_reads_preserve_every_requested_key_and_its_state, and a_failed_batch_preserves_activity_and_canonical_events; PostgreSQL's activity_failure_rolls_back_billing_and_source_metadata, a_commit_failure_after_activity_staging_preserves_the_predecessor, activity_and_source_identity_survive_restart_and_reset_together, and competing_request_ids_preserve_the_first_attribution; the core property committed_evidence_carries_the_supplied_credential; admission's emitted_usage_pins_the_key_and_cancelled_work_emits_nothing; writer's attribution_and_existing_outcome_counters_saturate_visibly, attribution_coverage_reports_transitions_without_repeating_incidents, and the uncertain-retry/drain scenarios in usage_attribution; the HTTP usage_acknowledgements_require_complete_bounded_valid_evidence, invalid_published_key_binding_has_a_structured_code, a_key_snapshot_is_bound_to_the_account_in_the_path and a_key_snapshot_naming_another_key_is_refused; PostgreSQL's key_bound_publication_and_status_changes_never_deadlock, which witnesses the credential, account, snapshot lock order; the wire-limit, attributed embedding allocation and three full-stack transport witnesses.

36. Calibration counts comparable benchmark runs, and replacement preserves the previous contract on refusal. The performance recorder owns a minimum of three distinct, complete readable runs at one committed revision and one host, target, CPU, OS, compiler and profile. Reprocessing a run or copying its sample cannot increase its weight; divergent evidence is an error. Legacy samples lacking identity or environment contribute nothing. Ordinary gate verdicts remain independent of optional sample collection.

    Enforcement: argument validation requires a samples directory for recording; sample publication is atomic and exclusive; loading deduplicates run IDs and matches complete recording contexts. The recorder reserves exclusive staging before validating the actual destination, carries that destination's bounds, and validates the replacement before atomic promotion. A partial current run cannot record using earlier complete samples. Mean inputs must be finite and positive; median arithmetic avoids intermediate overflow.

    Tests: optional_samples_preserve_gate_verdicts_without_recordable_provenance, recording_requires_samples_before_reading_input_and_help_still_works, checker_retries_cannot_satisfy_the_minimum_run_count, samples_from_different_revisions_or_environments_are_not_combined, profile_changes_and_legacy_samples_cannot_supply_missing_runs, replay_cannot_relabel_a_runs_environment_or_replace_its_measurements, concurrent_retries_publish_one_complete_sample, recording_validates_the_destination_and_preserves_its_bounds, a_foreign_or_invalid_destination_survives_recording_without_baseline_input, an_existing_staging_owner_blocks_replacement_without_touching_either_file, a_partial_run_cannot_record_using_previous_complete_samples, divergent_copies_and_invalid_sample_values_preserve_the_destination, and calibration_medians_reject_invalid_means_and_avoid_intermediate_overflow.

37. Backend error text is private across the HTTP and diagnostic boundaries. The server converts opaque StoreError payloads to fixed public titles, retaining the existing status/code and retry classification. This covers allocation, account creation/status, publication and both ingest outcomes. Server-owned readiness, maintenance and PostgreSQL startup failure logs retain operation and progress context without formatting backend text or connection strings. Authentication does not make a backend payload public.

    The router reports HTTP problem responses with 5xx or usage-refused using a private response marker containing only a static code and a generated 128-bit ID. Its warning records status and the route template, never raw path values, queries, headers or bodies. The optional JSON error_id matches that warning and carries no authority. Entropy failure preserves the original refusal, omits the ID and reports error_id_unavailable; it cannot invent an ID or turn a failed operation into success. Delivery requires a tracing subscriber retaining tollgate::diagnostics warnings and is not a durable audit outbox.

    Enforcement: ApiError conversions, its response marker and the router's diagnostic middleware; fixed fields at the background/startup log sites. Tests: every_backend_error_conversion_keeps_opaque_details_out_of_responses_and_debug, router_correlates_backend_failures_without_logging_request_or_error_payloads, diagnostic_identifiers_use_all_entropy_and_surface_entropy_failure, entropy_failure_preserves_the_error_without_inventing_an_identifier, readyz_is_503_when_the_store_cannot_answer, a_failing_sweep_reports_consecutive_failures, failed_rollover_retains_safe_progress_without_backend_text, and backend_startup_failure_never_discloses_connection_strings_or_driver_text.

38. CLI information requests precede application startup and validation. Every binary recognizes --help/-h and --version/-V; the first such argument before -- selects an information response and exits successfully. Those commands do not construct async runtimes, bind application listeners, start application tasks, read gate inputs or run measurements. After --, all arguments are literal positional inputs. The service binaries accept no positionals; a bare marker is equivalent to their ordinary no-argument startup. Invalid service arguments return status 2 with a visible diagnostic, regardless of log filtering. Native arguments are inspected before UTF-8 validation, so a non-UTF-8 argument cannot panic or conceal a subsequent information flag.

    Enforcement: each entry point owns the control decision; the pricing executable's Startup result selects whether its runtime is constructed. Gate parsers return their existing Command variants before decoding or validating operational arguments. This is component-owned enforcement with a cross-binary tested convention, not a mathematical proof of process I/O. Tests: pricing_help_and_version_precede_configuration_and_argument_validation, pricing_information_does_not_attempt_to_bind_a_configured_listener, pricing_rejects_arguments_and_treats_everything_after_the_marker_literally, load_cli_information_does_not_open_files_or_start_measurements, native_arguments_cannot_panic_or_hide_information_flags, help_and_version_precede_configuration_and_respect_the_end_marker, server_native_arguments_cannot_panic_or_hide_help_and_version, benchmark_information_precedes_validation_and_uses_the_first_flag, benchmark_native_arguments_report_errors_after_information_flags_are_checked, and command_line_controls_precede_validation_and_terminator_is_respected.

39. Load execution failures remain reportable under the deployment panic policy. Socket and protocol failures are returned by the owning client, never converted to a panic. Every client must finish warmup before measurement starts; failure or coordinator destruction releases waiting clients, and an incomplete run cannot return successful sample data. Only an HTTP 503 problem explicitly naming capacity unavailability is a shed outcome; other refusals are execution failures. Readiness and socket inactivity are bounded.

    Once command parsing supplies a report destination, configuration and execution errors publish a failed report with stage, message and run context and exit unsuccessfully in both verdict modes. Partial measurements are not presented as latency evidence. Reports are exclusively staged, validated and atomically replaced; a publication failure preserves the old destination and explicitly reports that the new report is unavailable. Concurrent writers have last-successful-publication semantics, with no merging of partial files. Response payloads do not enter diagnostics. Arbitrary panics or process death cannot be recovered under abort and are not covered by this guarantee.

    Enforcement: fallible client operations, one owned coordinator whose Drop releases the rendezvous, and the common atomic report publisher. These are component-owned contracts with implementation evidence, not an accounting proof or a formal refinement of Tokio and filesystem behavior. Tests: concurrent_driver_surfaces_client_startup_failure_without_deadlock, failed_clients_publish_diagnostics_without_measurements, response_framing_accepts_fragmentation_and_only_capacity_shedding, invalid_responses_are_errors_without_response_payloads, socket_failures_are_returned_at_the_io_boundary, measurement_gate_publishes_run_and_abort_decisions, coordinator_drop_releases_waiters_and_poison_is_an_error, cancelling_the_driver_releases_ready_clients_and_refuses_late_readiness, readiness_io_cannot_outlive_the_startup_deadline, readiness_retries_incomplete_responses_until_a_complete_success, reports_replace_atomically_and_failures_keep_the_previous_file, and load_configuration_failures_write_reports_even_in_evidence_mode, and load_runtime_configuration_errors_are_reported_before_starting_tasks. The CI production-profile fixture reuses the client/report implementation to witness ordinary process completion and readable failure reports with abort enabled; it performs no performance measurement.

40. Instance-local sharding separates request-serving threads only while affinities outnumber neither the shards nor their holders. A thread takes its affinity from one process-global counter on its first use of the request path, never at spawn and never recycled, and each component reduces that number by its own shard count. Two threads whose affinities are congruent modulo that count therefore share every sharded structure they touch: admission state, lease counters, rate buckets and outcome tallies. Because the counter issues 0, 1, 2, …, the separation the layout is bought for holds exactly while the affinities issued do not outnumber the shards. Losing it costs performance and nothing else — an affinity is a cache locality hint, carries no authorization or accounting meaning, and selecting a shared shard still conserves every unit (3, 25, 26).

    Control-plane work never spends an affinity. Reads that ask whether a grant is present, until when, or what a published generation says are answered identically by every view of one slot and every shard of one entry, so they resolve a fixed observer affinity rather than claiming the caller's. An instance reports what its layout is carrying — the shard count, the affinities issued, and how many shards hold more than one — as a control-plane read that no admission decision consults.

    Enforcement: the two control-plane readers own their half — load_observed on the slot and the observer affinity threaded through snapshot publication — and crowded_shards is exact arithmetic over the counter's own output rather than a sample. The other half is a deployment responsibility and is reported, not enforced: this library does not choose how many threads serve requests, cannot know which threads still hold the affinities it issued, and so cannot make crowding unrepresentable. Sizing shards against the worker pool, and keeping the request path off threads outside it, belong to the embedder; docs/LOCAL_SHARDING.md is that guidance. This is component-owned enforcement for what the library controls plus a reported contract for what it does not, never a proof that a deployment's threads are distinct. Tests: crowded_shards_counts_the_residues_the_counter_hands_out, a_layout_with_room_reports_every_affinity_distinct, occupancy_reports_the_counter_without_consuming_from_it, the_observer_affinity_costs_nothing_and_never_moves, observing_a_publication_does_not_consume_an_affinity, an_observed_slot_read_answers_without_claiming_an_affinity, and a_runtime_report_carries_the_effective_shard_layout.

41. A provisioner can neither fund, close, grant Assured, exceed its budget ceiling, extend credit, reach an operator's account, nor undo an operator's status, exhaust snapshot generations through caller-selected jumps, or publish unapproved policy. A provisioner identity (#39) reaches every admin route except deposit and principal-snapshot publication. On those it reaches, it may create only an unfunded, suspended, best-effort account; move status only to Active; set only BestEffort; set an allowance no larger than its identity's max_budget_allowance; and publish only Strict key snapshots matching one whole policy template approved for that identity. Key-snapshot generations are store-allocated: first publication is 1, then the locked live or revoked watermark plus one, regardless of the submitted generation. A repeat is a new publication; arithmetic overflow changes nothing. This removes arbitrary jumps that could block the operator's status or capacity-class republishing. Every account-scoped route requires the account's origin to be Provisioner, and activation refuses an account whose current status an operator set. Every scope refusal is 403 and audited; none moves the store.

    Enforcement, top of the ladder first. Unrepresentable: a provisioner ControlIdentity cannot be built without ProvisionerLimits, nor any other role with them, and the manifest refuses a missing or misplaced max_budget_allowance; AdminStore::create_provisioned_account takes only an id, so the balance, status, class and origin it writes are the store's, not the caller's. Component-owned: the router admits deposit and principal publication to [operator] only; the store's activate_provisioned checks provenance and the status author under the same row lock or mutex as the write, and every set_account_status records the operator as author, so a racing suspension either lands first and holds or lands second and wins. KeyDirectory::publish_key_snapshot_next allocates and publishes under the same mutex or snapshot-row lock, with insert conflicts resolved against the winning row before allocation. origin is immutable, so the handlers' AdminIdentity::check_account may read it before a separate write without a race. Argument refusals (balance, status, class, ceiling, enforcement mode) are handler checks made before any store call — tested convention, hardened by the witnesses below. Existing rows default to Operator in migration 0020, so upgrading grants a provisioner nothing. Exact-model proof: formal/lean/Tollgate/ControlPlane.lean proves a_provisioner_cannot_fund_or_publish_principals, an_operator_suspension_holds, activation_only_activates and an_operators_account_is_out_of_reach, assuming each transition is atomic; it does not model balances or the handler argument checks. The policy approval model is described below. allocated_generation_advances_exactly_once, exhausted_generation_refuses and first_allocated_generation_is_one prove bounded successor allocation in the same model. Finite-width and concurrency witnesses in both backends: store_allocated_generations_ignore_input_and_follow_tombstones, store_allocated_generations_preserve_operator_transitions, concurrent_store_allocated_publications_have_distinct_generations, exhausted_store_allocated_generation_changes_nothing, and store_allocated_publication_preserves_binding_retirement_and_ledger_checks. The HTTP dispatch witness is provisioner_generation_extremes_cannot_block_operator_transitions. Mirrored backend tests: a_provisioned_account_is_born_unfunded_suspended_and_best_effort and provisioned_activation_honours_provenance_and_operator_holds and repeating_operator_suspension_establishes_a_hold; PostgreSQL: stored_authorities_reject_unknown_vocabulary and accounts_predating_provenance_belong_to_operators. HTTP witnesses: a_provisioner_completes_every_self_service_call, a_provisioner_is_refused_and_audited_before_the_store_moves, a_provisioner_cannot_reach_an_account_an_operator_created, an_operator_suspension_holds_against_provisioner_activation, and a_refused_role_is_audited_with_its_actor_role_and_action. Configuration: a_provisioner_entry_requires_its_ceiling_and_no_other_role_takes_one and a_google_provisioner_subject_requires_its_ceiling.

    Policy approval (#43). ProvisionerLimits owns a nonempty, validated set of operator-approved templates. A manifest's per-identity allowed_policy_templates resolves only named entries from its policy_templates; missing, empty or unknown references fail closed. Complete cost tables (including per-operation permissions), limits (including compatibility fallbacks), permissions and policy revision must equal one template, with strict enforcement. Mixing approved fields from different templates is not approval. The handler refuses mismatches before any store call and audits 403 scope-forbidden. Operators are exempt. Binding, account status/class, budget stamping and generation allocation retain their store-owned contracts; validity is caller-supplied.

    Approval is captured in the immutable authorization generation. Reloading changes future authentications; an in-flight request keeps its generation, and published snapshots are not retroactively revoked. Failed reloads keep the last valid generation. Exact-model witnesses in ControlPlane.lean: approved_policy_is_one_whole_template, an_approved_strict_policy_can_publish, an_empty_template_set_grants_nothing, templates_never_authorize_elastic and removing_approval_refuses_future_publication. These assume complete field equality and do not prove Rust/serde refinement. Implementation tests: provisioner_templates_match_whole_policies_and_are_identity_scoped, provisioner_limits_refuse_missing_or_unpublishable_templates, unapproved_snapshot_fields_are_audited_before_any_store_call, template_reload_changes_future_publications_and_bad_reload_preserves_approval, operators_can_publish_policies_outside_provisioner_templates, manifest_policy_allowlists_fail_closed_for_bearers_and_certificates, and a_google_provisioner_subject_requires_its_ceiling.

Invariant reference checks

Run ./scripts/check_invariant_witnesses.sh from a checkout. The same command runs in the blocking repository-hygiene job on every pull request. It builds only the small tollgate-repo-check tool; it does not compile the workspace, execute tests, run mutation testing, start PostgreSQL, or measure performance. The binary accepts an optional repository path, --help, --version, and --.

The checker owns citation resolution for INVARIANTS.md. Every inline code span that is a snake-case identifier or qualified identifier is checked, including references outside a Tests paragraph. Wrapped brace groups such as reservation::tests::{drop_releases_pending, cancel_charges_zero_and_refunds} expand into separate references. Rust uses :: qualification and Lean uses .. A qualification must match a complete suffix of the declaration's scope; an arbitrary wrong prefix cannot pass because the final name exists elsewhere. An unqualified name may resolve in multiple backend suites. That is deliberate: the prose can cite one shared scenario name for memory and PostgreSQL.

Rust declarations are parsed under crates/ and examples/ with syn, including functions, methods, fields and modules. This distinguishes code and configuration names from absent symbols without maintaining a list of every field. The proptest! token stream is inspected separately because its strategy parameters are not ordinary Rust function syntax. Rust comments, string literals and opaque generator macros do not contribute declarations. Conditional declarations are included regardless of the current host's enabled features. File and inline module names supply lexical scopes; this is not compiler name resolution for re-exports, renamed imports, include!, or arbitrary macro expansion. If those become necessary, extend the resolver and its fixture tests in that change.

Lean's namespace/section, definition and theorem declarations are indexed after removing comments (including nested comments) and strings. Named paths under formal/ ending in .lean must exist within the checkout. The scanner covers the declaration notation used by the checked models; it does not elaborate Lean or check proofs. The formal job does that separately.

Fenced examples and compound code expressions are not candidate names. Neither are single-word or CamelCase type names. Use ordinary inline snake-case names for test witnesses. The guard intentionally does not scan historical narrative in docs/DESIGN.md, where removed test names remain useful explanations.

A second checker, scripts/check_seam_contract.sh, does read docs/DESIGN.md, and the two rules are opposite on purpose. This guard skips fenced blocks because there an example is prose; that one reads only code — fenced blocks and inline spans — because the staged admission seam's blocks are its declaration, and its English is not. It also reads one section rather than the document: that section makes a binding promise about signatures, while the rest of docs/DESIGN.md is the history this guard is right to leave alone.

External APIs, compiler lints, SQL objects and static event names that are not Rust/Lean declarations have exact entries with reasons in testing/invariant_external_symbols.json. Do not add a test name there to bypass a missing witness: correct the citation or supply its enforcing test. Empty explanations and unused entries fail. If a formerly external name gains a repository declaration, the entry must be removed. Changes to this small reviewed manifest are the durable record of non-declaration classifications; the normal checker reports obsolete entries and supplies the removal action.

Unreadable directories/files, source symlinks, malformed Rust, malformed reference groups, unclosed spans/fences, absent source trees and empty candidate sets fail rather than produce a successful partial audit. Diagnostics identify the document line and unresolved name. The checker never replaces source or evidence files.

Passing establishes that references have declarations, not that every cited function is a test or that a test enforces the stated invariant. In particular, a helper with a matching name is not evidence of behavior. Review still checks the enforcement ladder and the surrounding claim; unit/integration/property tests, CI mutation testing and Lean verification establish their respective evidence. The guard's integration tests use synthetic repositories as parser input and assert the observable accept/reject contract. They do not assert production source text or statement order.

syn 2 and proc-macro2 1 were already in the lockfile. They are maintained MIT/Apache-2.0 Rust parser components; taking them directly avoids a second, partial Rust lexer/parser. The additional full-AST/visitor feature work is confined to this unpublished tool. It has no dependency path into Tollgate's libraries or deployed services. Existing advisory, MSRV and workspace lint gates cover it. No dependency version, production API, wire contract, database schema, performance threshold or baseline changes with this check.

Tollgate Formal Models

This Lean package contains exact models for critical contracts:

• LeaseTiming proves exact integer-pair encoding and ordering, equivalence of the reclaim cutoff to expiry plus full grace, safe underflow/overflow behavior, and conservative bounds for migrated legacy timestamps. Rust property tests and PostgreSQL migration tests separately witness the finite timestamp domain, driver representation and database compatibility fence.

• LeaseShards models the aggregate of cache-isolated lease counters and exact-total debit/refund receipts. It proves conservation through reserve, cancel, and commit, proves committed spend stays within the grant, and proves that sufficient aggregate capacity always has an exact debit (the Rust algorithm and property tests establish that the implementation finds it).

• SnapshotCache models the generation watermark independently from the evictable request-visible entry. The watermark records why it exists — a generation the source published a revocation at, or the newest positive this instance installed — and only the first may refuse an equal generation. It proves that unknown transitions and eviction preserve the watermark, that an absence never turns an observation into a revocation, that revocation advances the watermark to the maximum observed generation, and that a positive replay at or below a revoked generation cannot resurrect the principal after eviction. It also proves the converse the distinction exists for: a principal whose row went absent is admitted again at the generation it already had, while a duplicate publish of a visible snapshot stays a no-op.

• ConcurrencyGauge models principal-then-account acquisition, rollback when the account is full, exact ceiling preservation, and single release. Rust's ownership transition from Pending through ReadyToStart into Committed separately enforces that execution start transfers the funding reservation without releasing its concurrency permit. The model proves that transfer retains occupancy and that only finishing either the pending or execution owner releases it; Rust's private fields, behavior witness, and compile-fail witness connect that model to the API.

• LeaseFencing models lease capabilities: a store of leases keyed by ID with a per-account fence counter starting at one. It proves that fences are positive, unique per account and increasing; that acquiring a lease leaves every existing lease unchanged, so the sequence is an audit order and not a validity epoch; that release and ingest refuse a mismatched (lease, fence) pair or (lease, account, fence) triple; that each operation changes only the lease it names; that a settled lease is never active again; and that billed plus returned units never exceed the grant. Expiry reclaim is modeled as forfeiture. Operations are atomic by assumption; the store suites' capability tests witness the Rust and SQL.

• IdempotentIngest models batched usage ingest keyed by request ID, with acceptance left as an arbitrary decision over the ledger planned so far. It proves that every input is classified exactly once; that a duplicate is recognized from its ID before its payload or the decision is consulted; that the ledger only appends accepted events, so no settled event is replaced and no request ID is billed twice across any replay; that the billed total grows by exactly the accepted units; that a rejected event does not claim its ID; and that a failed batch changes nothing. Batch atomicity is an assumption; the mirrored store suites witness it.

• ChargeLifecycle models a request's charge lifecycle on one instance: a list of requests sharing a lease and a usage queue of fixed capacity, moving through reserve, admit, cancel, commit, emit and deliver. It proves that the slots in use never exceed capacity and a full queue sheds with no charge; that nothing is charged before commit and cancellation refunds exactly the admitted debit, so the lease is conserved; and that a committed request holds the slot bound at reservation, so its event is emitted without a capacity check, once, with the charge fixed at commit. Queue lanes, the drain deadline, sharded counters and process loss are outside the model.

• NegativeCache models the bounded request-visible negative cache as a list of principal deadlines. It proves the bound holds under recording and pruning; that a full cache evicts an entry with the earliest deadline; that pruning keeps exactly the unexpired entries; that each principal has one negative, due at now plus the TTL the source's answer selects (unknown for an absent row, revoked for a tombstone); and that a present answer clears it. Pull scheduling, retry backoff and broadcast-lag recovery are the snapshot manager's, witnessed by its tests.

• StatusPropagation models an account's status as one ledger value and the status inside each of its snapshots, written together by one operation. It proves that the ledger and every live snapshot always agree; that a status change republishes exactly the account's live snapshots not already at the target, each at generation + 1, never a revocation tombstone and never backward; that repeating a change republishes nothing; that publication contradicting the ledger is refused; and that closed is terminal. The operation's atomicity is an assumption the backend suites witness.

• SessionCredential models the session-scoped credential cache over an arbitrary verifier, so it holds for any scheme the verifier seam admits. It proves that every principal the cache returns is exactly the verifier's answer for the presented bytes and is still reusable at now; that a hit requires the identical credential; that a changed or failed credential never leaves the previous principal reusable; that an already-expired answer is neither returned nor cached; and that sessions are isolated. Constant-time comparison and wiping on drop are the tollgate-auth tests'.

• Conservation models the per-account ledger equation deposited + overage = balance + activeGrants + settledUsage + loss + expired, where balance = allowanceBalance + topupBalance, and proves each transition preserves it: deposit, acquire, release, reclaim, a straggler on a settled lease, overage ingest, and budget rollover. It also proves that billing overage without funding it, or discarding an allowance without recording its expiry, breaks the equation by exactly the omitted units. An accepted overage debit never carries the counter past its cap.

• OveragePublication models the observer-visible split between pending and committed overage and the publication marker around the reservation phase CAS. It proves an in-flight commit is never reported as refundable, stable refundable/committed-saturation answers agree with committed occupancy, and commit, cancellation, and a lost commit claim preserve occupancy bounds. It intentionally does not infer central account exhaustion from local cap saturation.

• RatePublication models accepted account-policy publication. It proves that a rejected snapshot cannot mutate account state, newer accepted generations select their complete account-wide policy, same/older generations retain the current policy, and every principal request reads the one current rate authority rather than retaining a principal-local copy.

• SnapshotLimits proves that checking the largest registered operation weight at the configured batch cap bounds every registered operation at every permitted item count. Consequently, a worst-case quote at or below the burst keeps all in-limit quotes at or below the burst.

• CommitFallback models single-transition commit funding and its overage fallback, separating terminal accounting outcomes from request ownership.

• ExecutionCapacity models conservation across shared and reserved execution pools and excludes best-effort work from the assured reserve.

• AccountLifecycle models at most one account-manager owner, retirement before replacement, and inert duplicate joins.

• PeriodRoller models bounded independent maintenance: one pending call, a fixed cutoff per pass, and terminal stopping.

• ServerMaintenance models independent reclaim/rollover outcomes and terminal owner stop or task exit. It proves that the other operation cannot conceal a failure and that later successes cannot restore readiness after stop/exit. Watch-channel closure, task cancellation, HTTP delivery and finite counters remain separate implementation obligations.

• ControlPlane models disjoint role evidence, route role-set admission, the provisioner's account provenance and operator hold (#39), whole-template policy approval with strict enforcement (#43), and serialized administrative receipt composition, whole-value replacement predecessors, and credential retirement identity preservation, idempotency and terminality. It assumes credential authenticity and atomic policy selection; it does not prove cryptography or database serialization.

• CredentialProjection models exact integer-time expiry intersection and complete table replacement. It proves that fetch delay consumes freshness, failure preserves original deadlines, and empty success withdraws all keys. The bounded fixed-catalogue drain has no omissions or duplicates; mixed revisions preserve the predecessor. Cached evidence retains its original bound. Ordered cursor refinement, coherent source reads, atomic publication, verified input and accurate clocks are assumptions. Its legacy expiry model proves that migration's earliest compatible timestamp cannot extend source authority, including the zero bucket and domain minimum; a reset session inherits that bound. Rust tests separately exercise timestamp overflow, transport and session behavior.

Run from the repository root:

./scripts/check_formal.sh
./scripts/check_formal_mutants.sh

The second command mutates every transition definition, one operator at a time, and requires some theorem to fail for each: a proof that still passes against a broken model states less than it appears to. A surviving mutant fails the gate unless mutants-allowed.txt names it as equivalent, with a reason. When you add or change a model, add the theorems that kill its mutants. In practice these are the liveness and exactness facts beside the safety ones: that the exact limit is accepted, not only that exceeding it is refused.

The models use exact natural-number or integer arithmetic and atomic transitions. Rust property, cache, manager, HTTP, and backend-parity tests establish the proof-to-code argument. The proofs do not model scheduling, data-structure internals, the sharded CAS/fixed-receipt algorithm, the maximum-weight scan, finite-width overflow, SQL, or the derivation of settled usage from recorded usage and active lease usage; those remain separate Rust obligations. In particular a green formal job says the equation closes under each modeled transition — not that either backend performs them atomically, nor that the client applies the same rules the admission map does.

Local performance validation

Timed Criterion benchmarks and loopback load tests run locally. Remote CI compiles every benchmark and enforces deterministic allocation counts, but it does not execute timed performance jobs. A green pipeline therefore establishes no latency or throughput verdict. Performance-sensitive changes and releases need reviewed local evidence before merge.

Run and retain evidence

Use a quiet host on AC power and an isolated checkout/target directory. Keep power mode consistent throughout a calibration series. Do not run builds, mutation testing, load tests or another benchmark suite alongside a measurement. Keep baseline and candidate build directories separate; shared Cargo artifacts previously caused an invalid comparison. Run the full scripts for acceptance: filtered benchmarks are useful diagnostics but do not replace the full workload.

./scripts/check_perf_thresholds.sh
./scripts/check_load_thresholds.sh
./scripts/check_allocations.sh

Criterion uses the release profile with codegen-units = 1, pinned as [profile.bench] in the workspace manifest. The default sixteen units are not reproducible across unrelated change: rustc repartitions a crate as its code grows and cross-unit inlining moves with it, so a row's measurement shifts while its own source stands still. That is what GL-114 was -- admission/snapshot_lookup_moka read 66.92ns before a feature commit and 88.19ns after it, with get_at, the cache builder, StoredEntry, MapEntry and the hasher byte-identical across the pair; one codegen unit put the same two revisions at 55.84ns and 56.40ns. One unit is also what production compiles, so the gate stops pricing a configuration nobody deploys. The cost is slower benchmark builds. Load tests use the production profile (fat LTO, panic=abort). Preserve reports/perf_gate_report.json, reports/load_gate_report.json, the allocation report and command logs with the review evidence. Reports are generated artifacts, not files to add to the source tree. Attach them to the pull request or retain an inspectable evidence artifact and link it.

Record the tested commit and any uncommitted changes, host/CPU, OS, Rust version, profile, commands, date, background load and verdict. Record all failures and inconclusive results as well as successes. Changing a measurement environment is a diagnostic step; repeated retries until one passes are not a regression fix.

Absolute bounds are calibrated measurements. The current recorded regression baseline identifies mistral-apple-m1-pro; only that actual host should set TOLLGATE_PERF_HOST=mistral-apple-m1-pro when running the Criterion script to activate its baseline comparisons. Never set a host label to make foreign measurements appear comparable.

A full run that does not enforce the baseline exits 4 and reports UNENFORCED. That is deliberate: a full report is what a reviewer accepts a performance-sensitive change on, and one with every regression row marked baseline-skipped established nothing about this host. Do not treat it as evidence, and do not clear it by unsetting the host.

On another host, ./scripts/check_perf_thresholds.sh --ratios-only can provide local diagnostic ratios while skipping absolute and recorded-baseline decisions. Its historical unreadable-run abstention remains part of the CLI contract: an exit code of zero is not by itself proof of a readable performance pass. Inspect the report's trust, drift and verdict fields. drift gives the median and quartiles of every row's ratio against the baseline: a run whose median sits well above ×1.00 was slow as a whole, and the rows that crossed their bound in it are the ones with the least headroom rather than the ones that changed. The load command's --evidence mode and testing/load_thresholds_ci.json remain available as diagnostic configuration; they do not schedule remote CI or establish full acceptance.

An isolated checkout starts with no reports/perf_gate_history.json, so the run-to-run trust verdict is no_history unless you carry one. Pass --history <path> through to the gate to point successive runs at a stable file when you want that verdict.

Configuration keys

The gate decoders reject unknown configuration keys. A typo such as trust.moved_shft is an error; it cannot silently select the default moved_shift. The same rule covers the manifest's optional trust and ratios keys, benchmark and ratio rows, load settings, and baseline settings such as samples and max_regression. Comparison and recording use the same baseline decoder; an invalid recording destination is preserved.

Documentation is supported only at these locations:

For custom manifests, remove unsupported annotations or put them in a supported comment. Generated baselines must match the recorder's schema: use a compatible tool version or record a complete new file at a new destination; never hand-edit a baseline. There is no numeric migration for valid files: known settings and all checked-in files keep their meanings. An omitted trust block still selects the defaults, and a partial block overrides only its named fields. Older baselines without samples still mean one sample; an omitted row regression allowance still means 5%. Every load setting remains required, including the nullable bounds: null means deliberately disabled and an absent key is an error. No manifest or baseline needs recalibration for this parser change, and its tests perform no measurement.

Load execution failures

The load tool returns socket, HTTP framing, coordination and scenario failures as errors under the production profile, including panic=abort. Once it has a valid command and report destination, configuration and execution failures write an error report and exit 1 in both normal and --evidence modes. A failed run contains passed: false, error.stage, error.message and run context; it has no latency or throughput fields. Consumers must check for error before reading measurement fields. Complete measurement reports retain their existing shape. Argument errors have no validated report destination and remain stderr-only.

Only an HTTP 503 problem with code capacity-unavailable counts as capacity shedding. Other refusals, unexpected statuses, malformed framing, truncated responses and oversized replies fail the scenario. Diagnostics identify the client and warmup/measurement phase without copying response bodies or headers. Every client must finish warmup before measurement starts; a warmup failure or coordinator cancellation releases waiting clients without measured requests. Partial client samples are discarded on failure. Clients use ten-second socket inactivity timeouts, and readiness has a five-second deadline covering its I/O.

Both report shapes are serialized, exclusively staged in the destination directory, read back and validated, then atomically renamed. Publication failure preserves the previous destination and prints report unavailable, never a successful verdict or a claim that the old report belongs to this run. Concurrent writers publish complete files; the last successful rename wins. These reports are observations, not a merged history or durable billing records.

CI's load-failure-reporting job executes fixed failure fixtures against the same client and report modules under the production profile:

cargo run --locked --profile production -p pricing-api --example load_gate_failure_probe

It retains reports/load-failure-fixtures/. This is correctness evidence only: the fixture starts no pricing service, runs no performance workload and produces no timing verdict. Ordinary unit tests separately exercise protocol boundaries, poisoned coordination state and report-publication failures. Arbitrary panics and whole-process termination remain outside the reporting guarantee.

Recalibrating the baseline

testing/perf_baseline.json is generated, never hand-edited. A readable, complete full run with recording provenance deposits its measurements under target/perf-samples. --record takes the per-row median over distinct runs at the current revision in the same measurement environment:

# start a fresh series at the revision you are recording
TOLLGATE_PERF_HOST=mistral-apple-m1-pro ./scripts/check_perf_thresholds.sh --fresh-samples
TOLLGATE_PERF_HOST=mistral-apple-m1-pro ./scripts/check_perf_thresholds.sh
TOLLGATE_PERF_HOST=mistral-apple-m1-pro ./scripts/check_perf_thresholds.sh --record

Recording refuses with fewer than three distinct readable samples, because a baseline says where a benchmark usually lands and one run cannot. It refuses a run the gate would not read, a row that is missing from any sample, a partial manifest, a dirty worktree, provenance it was not given, and a host that does not match the file it would replace. It stages and validates before promoting, so a refusal leaves the previous baseline intact. Per-row max_regression values carry forward, widened by the run history where it shows more spread (below), and the file records how many runs its medians came from.

Each sample retains the revision, host ID, target architecture, CPU, OS, compiler and Criterion profile. All must match the recording context; other contexts are skipped with a diagnostic. The freshness marker's timestamp identifies the benchmark run, so processing the same marker and estimates again counts once, even if a sample file has been copied. A conflicting copy or a retry with different means or provenance is refused. Create the marker once before each benchmark suite and keep it unchanged when retrying the checker. Legacy samples without run identity and environment are skipped with a warning; collect a new series using --fresh-samples.

Sample collection is optional during ordinary gating. Dirty worktrees, missing recording provenance or sample-write failures produce a diagnostic without changing the normal verdict. --ratios-only does not deposit samples. Recording still requires complete, readable measurements and valid provenance; invoking the binary directly with --record also requires --samples <dir>.

Allowances come from the run history

Every run that deposits a sample also keeps it in target/perf-history (--run-history), a window of the newest 40 runs that --fresh-samples never clears. --record derives each row's max_regression from that window instead of leaving it at whatever was last typed in:

• Only runs on this host, environment and profile count; the revision may differ.
• Runs are grouped by revision, and each is divided by its own revision's median, so a code change between revisions — which moves a row's level, not its noise — drops out. What is pooled is run-to-run spread on one build.
• A run more than ×1.5 its revision's median is an excursion: listed in the recording's output, never absorbed.
• The allowance is the worst believed ratio, less one, plus 0.03, rounded up to the next 0.05, and at least the 0.05 default. It needs six believed runs across two revisions, or the row keeps its carried allowance.
• It never narrows a carried allowance. Lowering one stays a deliberate edit made before recording, with the evidence in the pull request.

The recording prints every allowance it widened and every excursion it set aside. Every full run lists the rows carrying an allowance above 0.30 as weak per-row gates, in its output and in the report's wide_allowances: such a row is guarded by a same-run ratio or an absolute threshold, and a reviewer should look there rather than at its baseline comparison. A new row with no history starts at the default and is sized by the first recording that has evidence for it.

The recording destination supplies the host check and carried regression bounds even when --baseline is absent or points to another file. --baseline selects only the input used to judge this run. A successful recording does not change that verdict or replace the required fresh validation run.

Sample publication is atomic and exclusive: concurrent retries retain one complete sample. Baseline recording exclusively reserves its sibling .json.staged file before reading the destination, validates the replacement, then renames it atomically. If interrupted, confirm the recorder has stopped before removing its leftover staging file and retrying. Do not remove an active writer's staging file. A refusal preserves the previous baseline.

Then validate with a fresh full run that exits 0 with enforced: true, and put both the recalibration and that validating report in the pull request.

Leave the host idle between runs — several minutes, not seconds. Back-to-back full-suite runs on Apple Silicon degrade: in the GL-114 measurements the first run after an idle gap was clean while the two immediately following it both came back unreadable, with ten of fifty-eight rows exceeding the confidence -interval bound. Judge a run by the report, not by how quiet the machine looked when it started: one GL-114 run began at 73% idle under a load average of 2.62, finished at 88% idle, was marked trusted with only two unstable rows, and still put nineteen rows over their bound on a drift of ×1.048. Idle and load average are context; drift and trust are the verdict.

A row whose measurement moved because a change added work to its path is recalibrated by the change that added the work — not later, and not alone.

Review and CI contract

Performance acceptance is a local review responsibility. There is currently no CI attestation that a reviewer ran or inspected these reports. A missing local report is an incomplete performance-sensitive change even when CI is green. Unreadable measurements require a suitable measurement environment; genuine regressions require a fix or an explicitly justified threshold/baseline change. This policy changes where measurements run, not the benchmark workloads, thresholds, request-path constraints or baseline data.

CI continues to require format, lint, toolchain compatibility, tests, PostgreSQL parity, dependency advisories, benchmark compilation, allocation assertions, formal verification and mutation assurance. Formal and mutation jobs run on every pull request regardless of its target. scripts/check_ci_rules.sh enforces their blocking status and rejects restoration of the retired timed performance jobs or direct timed benchmark commands.

The decision follows release !177's inconsistent ratios on unchanged source: one run failed reserved/uniform capacity; the next passed that comparison and failed disabled-capacity/admission. Separately tagged runner registrations also reported the same host identity. Infrastructure investigation remains tracked in GL-113; remote timing must not be restored without a separately reviewed design and evidence of repeatable measurement conditions. See docs/DESIGN.md for the incident evidence and decision history.

Credential projection evidence (GL-108)

Measured on 2026-09-09 on mistral, Apple M1 Pro, Darwin 25.6.0, Rust 1.97.1. Crates use the ordinary Criterion release profile; loopback load uses production (fat LTO, panic abort). These measurements accompany the owning invariants and tests; they do not prove cryptography, scheduler behavior or SQL-to-Rust refinement.

Request and session cost

./scripts/check_perf_thresholds.sh passed all 46 benchmark rows. The new same-run ratios passed: cached managed/direct 0.992, uncached managed/direct 1.011, each bounded at 1.25. Historical baseline enforcement was not enabled (active_host unset); the existing gate reported some unstable unrelated rows as inconclusive. No existing threshold was relaxed. New baseline rows record this run on the same host as the baseline header.

The existing indefinite-cache fixture measured 16.50 ns. Finite proof expiry activates the existing timestamp comparison, so its cost must be stated rather than claiming that every warm credential remains at the indefinite-cache cost. A cold managed verification adds one projection load; warm hits do not consult the registry. Expired proofs are checked using caller-supplied time.

./scripts/check_allocations.sh passed, including required report scopes auth/projected_cache_hit and auth/projected_expiry: both allocate zero. Renewal creates new cached evidence and is measured separately from warm hits.

The production loopback load gate passed:

Admitted throughput was 29,344 requests/s sequentially and 104,924 requests/s with ten connections. The example imports its documented demo-key-N tokens into durable MemoryStore records, then authenticates through KeyManager. Its API test additionally retires a stored key, refreshes, and checks that new verification refuses it with no extra usage charge. Account snapshot checks continue on every request, independently of cached credential identity.

Page and publication scaling

Reproduce with:

cargo bench -p tollgate-client --bench key_projection_scaling -- \
  --warm-up-time 1 --measurement-time 2 --sample-size 30

The page fixture holds 256 active keys and returns 64 per read. Retired history is deliberately before the cursor's first active key.

The ordered unrevoked-key index removes retired-history scans. Expired but unrevoked rows remain candidates, and the whole installed table still costs O(active keys) memory. The per-pass deadline and total page-call budget include revision-conflict restarts and candidate construction.

PostgreSQL 16 EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) used 100,000 retired rows and 256 active rows, with LIMIT 65 (64 records plus lookahead). Both the first page and a cursor in the live set used tollgate_credential_keys_projection: 65 rows, zero rows removed by the expiry filter, four shared blocks, no sort. Execution times were 0.038 ms and 0.027 ms. The fixture was inserted in a transaction and rolled back; plans are in the generated reports/credential_pg_plans.json artifact. Reproduce against the local fixture:

docker compose exec -T postgres psql -U tollgate -d tollgate \
  -v ON_ERROR_STOP=1 -f - < testing/credential_projection_plans.sql

These are query-plan observations, not a latency promise for arbitrary expiry distributions or remote databases.

Those PostgreSQL observations used the pre-0018 expiry schema. The runnable fixture now uses exact timestamp pairs; GL-118 does not claim a fresh timing measurement or reuse these historical query timings as validation of that schema. Its correctness evidence covers both page predicates and the complete HTTP/session boundary without changing the measured request-path code.

Reproducible assurance

The invariant witnesses live in INVARIANTS.md 27 and 34. Core commands:

cargo fmt --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
TOLLGATE_REQUIRE_PG=1 TOLLGATE_PG_URL=<local-fixture-url> \
  cargo test --workspace --all-features
./scripts/check_formal.sh
TOLLGATE_PG_URL=<local-fixture-url> ./scripts/check_mutations.sh --diff main
./scripts/check_allocations.sh
./scripts/check_perf_thresholds.sh
./scripts/check_load_thresholds.sh
./scripts/check_advisories.sh
./scripts/check_ci_rules.sh

The Lean model proves exact fixed-catalogue drains, no omissions or duplicates, whole replacement, failed/mixed-revision preservation and finite expiry bounds. Backend tests cover revisions from the same committed read, legacy writes, rollback, no-op idempotency and overflow. HTTP tests cover the role boundary, server-selected time, strict query and digest decoding, complete response semantics, and exact body bounds with and without Content-Length.

tollgate design

Status: proof of concept, complete through the goals below. This document is the architecture, the decisions made against the originating design thread, and the findings the PoC produced. The testable contract lives in INVARIANTS.md; this file explains why.

Problem

A latency-sensitive API service (an options-pricing API is the motivating consumer, with a microsecond-scale in-process request budget) must enforce account policy, rate limits, quota, and billing without any synchronous I/O on the request path. One database round-trip per request would be two to three orders of magnitude over budget.

Measurement context. Absolute timings in this document are host-dependent Criterion results. Unless a passage names another host, they were measured on the Apple M1 Pro development laptop that later became the controlled performance host. The same-run ratios are the portable claims; PERFORMANCE.md records the procedure and its limits.

Architecture

Two planes. The request path is entirely local; the control plane owns every slow operation and the source of truth.

request path (tollgate-core + tollgate-admission, zero I/O; policy time passed in, governor reads its own monotonic clock)
  per-connection exact-header proof → verified credential fingerprint (Principal)
    → snapshot map lookup (arc-swap immutable map or moka)
    → status / staleness / permission bits        (AccountSnapshot::admit)
    → batch cap + cost quote                      (CostTable, direct-indexed)
    → weighted rate token                         (governor; optional local shards)
    → lease debit → Reservation                   (LocalLease, optional local CAS shards)
    → commit-at-execution-start | release
    → usage event via pre-reserved permit         (bounded channel)

control plane (tollgate-client tasks + tollgate-server + tollgate-store backend)
  lease acquire/release/reclaim (lease-scoped capability, TTL-bounded, adaptive grants)
  snapshot compilation & distribution (generation-monotonic)
  usage ingest (idempotent, batched) → billing ledger
  expiry reclaim sweeps

The store is three narrow async traits — LeaseAllocator, SnapshotSource, UsageSink (plus AdminStore) — implemented by MemoryStore (reference, executable spec), PostgresStore, and HttpStore (the client-side transport to tollgate-server). The same LeaseManager/UsageWriter instance runtime runs unchanged over a direct backend or over HTTP: both topologies are exercised by the same end-to-end drain test (tollgate-client/tests/ no_double_spend.rs and tollgate-server/tests/loopback.rs).

HTTP acquire and consolidation share wire::LeaseTtl: it preserves the full positive SignedDuration value, with legacy whole seconds or an exact duration string and a zero legacy sentinel. Positivity and unambiguous decoding are checked before allocation; the backend still owns TTL policy clamping and the server still supplies now. See the operator TTL compatibility section in CONTROL_PLANE_SECURITY.md for the server-first rollout and Rust DTO migration.

tollgate-server's library remains generic over those store traits. Concrete backend selection belongs to its binary: memory support is always compiled, while Postgres support is the default-enabled postgres Cargo feature. An embedder using the generic service with its own store can disable default features without compiling tollgate-store-postgres or sqlx.

SnapshotSource resolves each pull explicitly as Present(snapshot), Revoked(generation), or Unknown. HTTP preserves the distinction: 200 carries a snapshot, 410 carries a generation-ordered revocation, and 404 means the source has never known the principal. A pull or process restart therefore cannot discard a tombstone generation.

A present resolution carries PublishableSnapshot, a typed proof created by the owning validation in tollgate-core, rather than an unchecked Arc<AccountSnapshot>. Admin writes require the same proof. Wire and database records remain raw snapshots because they are trust boundaries; the server, HTTP client, and Postgres reader validate them before converting them into the proof. This makes backend-specific publication without validation unrepresentable while preserving raw AccountSnapshot construction for the request path's defensive backstop.

The explicit three-state resolution was an intentional Rust trait break and an additive problem-body field, plus a 404-to-410 status change for revoked principals. For a rolling HTTP deployment, update clients before servers: new clients safely understand both the old 404 and new 410 behavior, while old clients classify 410 as a retryable store failure and may retain a positive until its own validity deadline.

Portable identifier wire contract (GL-24, 2026-08-24)

The original v1 transport had two representations for the same opaque value: all five 128-bit id newtypes displayed as zero-padded hexadecimal, while URL paths bypassed Display and JSON serialized the inner u128 as a decimal number. The default Rust JSON number type rejects values above u64, and a conventional JavaScript consumer cannot preserve even valid JSON integers above 2^53. The path mismatch was also a refactor trap. Axum 0.8 actually rejects an unparseable Path<u128> as 400 rather than the 404 first reported, so the current client did surface that particular mismatch as a store error; the broader contract and portability defects remained.

V1 now gives AccountId, KeyId, LeaseId, RequestId, and Principal one spelling everywhere: exactly 32 lowercase hexadecimal characters, no 0x. The owning types implement Display, strict FromStr, and textual Serde from the same rule; server paths extract those types rather than raw integers. Malformed bodies and paths remain RFC-7807 responses. HttpStore accepts a negative snapshot resolution only from a structured 404 carrying unknown-principal; a route-level 404 or any other code is an operational failure and cannot poison the negative cache.

This deliberately updates /v1 in place because Tollgate's HTTP API has not been published yet. The Rust Serde and HTTP contracts are breaking for the same reason, so clients and servers must be deployed from the same revision; numeric and textual peers are not wire-compatible. HttpStore treats an old server's unstructured route 404 as an error rather than confirmed absence.

No database migration accompanies the wire break. PostgreSQL snapshots own a storage-specific id DTO: values in the legacy u64 range stay numeric, while larger values use the canonical string that the former JSON codec could not represent. Existing rows remain readable, and a rollback binary can still read new rows whose identifiers remain in the legacy range. Larger textual values deliberately require the new reader. This exception is owned at the database trust boundary rather than hidden inside the canonical id parser.

Charging semantics

Charging follows a fixed-charge-once-per-request contract (commit_at_execution_start): admission debits the lease immediately but the charge is only pending; execution start commits the full quote for success, failure, or timeout alike; anything ending the request before execution — validation failure, cancellation, shed, drop — releases for zero charge. Commit and cancel race on a single compare-exchange; exactly one wins.

Two ledgers, one truth

Leases bound spend (admission control); usage events are the billing record. The ledger contract, implemented by Conservation::holds for both backends, states the exact per-account equation:

deposited + overage_recorded
    == balance + active lease grants + settled usage + settlement loss + expired

Usage on an active lease lives inside its grant; it stands alone only after the lease settles. The backend suites assert this equation after ledger transitions.

The left side is funding, the right side is where funded units sit — which is why elastic enforcement (GL-1) adds its term on the left. Overage is spend no deposit paid for and no lease debited, and it is billed like any other usage, so it also lands in settled usage. Recording only that half would make the equation fail by exactly the overage and report corruption on a correctly working ledger; recording both halves in one transaction closes it by construction. expired accounts for funded allowance units a closed budget period removed (GL-97); they remain part of the ledger even though they are no longer spendable or billable. Tollgate.Conservation proves the modeled transitions preserve the equation, and that omitting overage funding or expiry accounting breaks it by exactly the omitted units.

Findings (what the PoC changed or proved)

1. Rotation must not strand units. Naïve low-water rotation stranded ~33% of an account in superseded leases until TTL. Fix: the manager parks a superseded lease and releases it only at quiescence — when it holds the only outer Arc and no locality alias remains, no reservation exists and none can be created, so the remaining count is final and the release is race-free.
2. Settlement must tolerate release-before-flush. A quiesced lease can be released while its usage events still sit in the writer's queue. A release credits only the claimed unspent; the gap granted − used − unspent is provisional loss, and a late event that fits inside it converts to billed usage. Expired-lease reclaim credits the whole remainder, so its stragglers never fit and stay rejected — no double-count either way.
3. arc-swap beats moka for the snapshot map, ~5× (13.9 ns vs 69.5 ns hit on the development laptop), confirming the thread's caution about moka's TinyLFU bookkeeping. Both stay behind SnapshotMap; the perf gate carries both, and both hash principals the same way (GL-9) so the ratio keeps measuring the data structures rather than their hashers. That ~5× was measured on a cache one-eighth full, where moka enables neither its frequency sketch nor eviction — see "The map choice was measured with moka's bookkeeping switched off" below. Filling the cache costs moka more than arc-swap, but the gap does not widen: it measured ×6.40 under-filled against ×5.04 at capacity on the controlled host.
4. Same-account cross-core contention needs an explicit local topology. The former one-counter layout took 2–4 µs with eight threads against one account versus roughly 100 ns uncontended. LocalSharding now partitions the mutable admission state and cache-isolates request-owned handles; the default remains one shard. The perf gate compares the eight-thread and uncontended paths from the same run and requires a ratio at or below ×3.
5. Sequential and contended end-to-end overhead meet separate gates: across five development-host production-profile loopback repetitions, the paired admitted-vs-baseline p50 ratio ranged ×0.997–×1.101 for one persistent connection (gate max ×1.15) and ×1.015–×1.104 for 10 persistent connections contending on one account (gate max ×1.20). Those measurements predate GL-2, which is why they showed most of the sequential delta as per-request HMAC-SHA256 credential verification, not quota machinery. Pricing-api now authenticates once per connection and reuses the verified fingerprint only while the complete authorization header remains exactly equal; paired post-change measurements are recorded with GL-2's threshold decision.
6. The quota edge needs adaptive grants: GrantPolicy caps a grant at balance / shrink_divisor (floored at min_grant), so N instances can't strand a small balance behind one oversized lease; the tail drains to the last unit.

Instance-local admission sharding (GL-3, 2026-08-24)

Sharding is explicit and opt-in. LocalSharding::SINGLE is the compatibility default; an embedder that has measured real same-account saturation supplies the same value to ArcSwapSnapshotMap::with_sharding (or the Moka equivalent) and SlotRegistry::with_sharding. LocalSharding::available_parallelism is a control-plane convenience, not an automatic policy. The pricing example also accepts TOLLGATE_LOCAL_SHARDS; an invalid or zero value is a startup error, never a silent fallback. A deployment should normally start with its worker thread count and validate memory and latency on its controlled host. SnapshotManager::spawn rejects a map/slot mismatch before starting either background work or admission publication.

The root cause was broader than the lease counter named in the issue. The lease CAS, governor state, admission tally, and several shared Arc strong-count words all bounced between the same-account workers; splitting only the lease improved the provisional benchmark from 2.64 µs to 2.29 µs. The false-sharing assumption also said 64-byte lines on aarch64, while the supported Apple Silicon host reports 128. Existing safeguards missed the pattern because the uncontended and distinct-account gates cannot create it, and the contended benchmark had only a loose provisional absolute ceiling rather than the same-run ratio the issue required. The prevention is structural locality plus 128-byte layout witnesses and a gating contended/uncontended ratio. A same-pattern search across the workspace found one other 64-byte assumption, the request-written UsageWriter counters; it is corrected and layout-tested in this change. No other repr(align(64)) site remains.

The locality is a sticky process-local number assigned once per participating OS thread. It is deliberately not a CPU id: Tokio tasks can move and operating systems migrate threads. Reducing that value modulo each effective shard count is enough to keep a worker's routine writes on stable cache lines. Keeping them on lines no peer writes is a further condition, and GL-124 records that it is reported rather than enforced — a deployment responsibility, because the library does not choose how many threads serve requests. All mutable hot-path components use it:

• A lease grant and its low-water threshold are quotient/remainder partitioned exactly across 128-byte-aligned counters. Debit tries the local counter, then steals a whole debit from siblings. Only genuine fragmentation takes pieces from several counters. Its fixed-size receipt records the exact total and one refund shard; cancel and a failed gather may rebalance counters while restoring the aggregate exactly. No debit path allocates. Aggregate remaining is exact at quiescence, which is when release uses it; a live read walks shards one at a time while others move, so it is a bounded estimate in both directions and is clamped to the grant rather than asserted against it.
• A sharded LeaseSlot publishes an independently reference-counted outer lease view per locality. Those views share the accounting counters, but Arc ownership traffic stays local. Publishing N views is N swaps, so mutators hold a publication lock: readers still straddle one publication as they always did, but the slot cannot end one holding two different leases. Rotation removes all published views and releases only after the parked outer handle and the shared inner view count both prove quiescence, so an in-flight sibling cannot be missed.
• The account rate and burst are partitioned, never copied, across independent governor buckets. The already-validated PublishableSnapshot carries its maximum quote into the map; the effective shard count is capped so every bucket can admit that largest legitimate request. The account-wide cap is the tightest ceiling supplied by accepted principals. An older account-policy generation can still tighten it, and it never widens. A rejected principal replay cannot affect that ceiling. A local denial tries each sibling and calls a request unpriceable only when no bucket can hold its weight. If a bucket can hold it but none admits now, the weighted refusal is RateLimited. Both rate refusal variants classify as Retry::Transient and expose no retry instant or delay; governor's internal denial timing does not cross the admission API. Independent buckets can conservatively throttle when their residual tokens are fragmented, but their summed rate and burst never exceed the configured instance-local account budget. Raw snapshot installs retain one bucket because they carry no publication proof.
• Admission state, immutable snapshots, lease handles, rate state, and outcome counters are cache-isolated on 128-byte Apple Silicon lines (harmlessly over-aligned on 64-byte x86-64). Sharded maps keep one state/snapshot Arc per locality so reference-count writes do not recreate the bottleneck after the accounting atomics are split. A stored entry stays a shard array until the engine's already-resolved locality indexes it, so a cache that clones on its write path cannot fix the choice to whichever thread installed the entry. Counter snapshots and lease-manager operations aggregate on the control plane.

Low-water notification is shard-local because computing an aggregate on every debit would put an O(shards) scan back on the request path. One local crossing wakes the manager early. If the aggregate is not low, the manager clears every doorbell and rechecks the sum; a debit racing the clear is therefore included in the recheck or observes a clear flag and wakes again. The interval remains the cold-start and expiry backstop.

The exact natural-number conservation argument lives in formal/lean/Tollgate/LeaseShards.lean. Rust property tests vary the shard count and finite-width request sequence; concurrent, rotation, shutdown, and fault-path tests establish the proof-to-code bridge. No wire DTO, database schema, or existing constructor changed semantics. The public changes are additive, though opt-in sharding deliberately spends more per-account memory.

The gated benchmark ids name the shipped default, and the _sharded ones price the option: admission/full_check and admission/full_check_contended_8 keep measuring the single-counter layout they were calibrated against, while admission/full_check_sharded and admission/full_check_contended_8_sharded measure the eight-shard one. Pointing the existing ids at the opt-in topology would have left the layout nearly every deployment runs with no threshold at all, and would have redefined two manifest entries in place.

Measured on the development host at load average 17–26, which is why these are backstops rather than calibration: 103–110 ns default uncontended, 116–124 ns sharded uncontended (the price of the locality read and shard index), 2.74–2.80 µs default contended, and 446–618 ns sharded contended. The portable same-run ratios are what the manifest gates: sharded-contended over default-contended (measured 0.17, bound 0.5) is what sharding buys, and sharded-contended over sharded-uncontended (measured 4.09, bound 8.0) is the sharded layout's own contention budget — wider than an idle host would need, because on a machine this loaded the foreground measurement competes with far more than its seven background threads.

Review round: what sharding broke that single-counter code could not (GL-3)

Four defects shared one shape — a claim that held for one counter, one view, or one snapshot, restated unchanged over N of them.

• An aggregate read asserted a bound it no longer had. remaining() summed shards with checked_add(..).expect(..) and a debug_assert! against the grant, three lines below a doc admitting the walk is not one atomic instant. A failed fragmented reservation returns its whole aggregate to one shard (the fixed-size receipt), so a reader that has already counted a shard the refund lands behind counts those units twice. That panics: the assertion in any debug or test build, the expect in release once grants approach u64::MAX — which the change's own boundary test treats as legitimate. The callers are the request path's LeaseExhausted reason, the refill task, and the example's readiness handler. Fixed by making the estimate honest: saturating sum, clamped to the grant, documented as an estimate in both directions and exact only at quiescence.
• A per-snapshot bound sized an account-wide bucket. Shard count came from the installing snapshot's maximum quote, but AccountLimiter is shared by every principal of the account and update returned early at an already-installed generation. A key whose cost table quoted more than one shard's burst — while still fitting the account's whole burst, so publication accepted it — was denied UnpriceableUnderLimits permanently, for a request that admitted before sharding existed. The ceiling is now account-wide, tightened by every install regardless of generation ordering and never widened; the alternative, per-principal evidence, would need its own eviction story for churned credentials, and holding the floor costs only a coarser split.
• A publication documented as atomic was N swaps. LeaseSlot::take said it "atomically" removed every view; install, replace, and clear were equally multi-step. Two mutators — an embedder clearing on revocation while the refill plane rotates — interleave into a slot that is half empty and half fresh, so some localities keep spending after a revocation the single-view slot made indivisible. Only latent in shipped code, which has one writer per slot, but LeaseSlot is public API. Mutators now serialize.
• The moka map's sharding was inert. Its entry resolved locality inside Clone, and moka clones on its write path: the entry was already reduced to the installing thread's shard before any request saw it, so every worker shared one state and the get_at locality argument was ignored. Discovered by the test written for the smaller complaint that get_at was not overridden. The stored entry now stays a shard array — behind one Arc, so the clone stays a single refcount bump — and get_at indexes it. Resolving from an owned entry keeps the single-shard path free of the extra clone/drop pair that would otherwise land on every lookup.

The common prevention is the same in each case: a test that exercises N of the thing. The perf gate had the same shape of gap — the change had pointed its two gated full-pipeline ids at the opt-in topology, leaving the default layout with no threshold — and is fixed the same way, by gating both.

Lease-scoped fencing contract (GL-35, 2026-08-24)

The word fencing originally overstated the store contract. Invariant GL-4 and the first FencingToken API documentation were written before either store backend and described an account-wide epoch: any token older than the newest issued token would be stale. The stores subsequently implemented a different, deliberate model. Rotation acquires a replacement before the prior lease has quiesced, so several leases for one account can be active at once. Each keeps its own capability until settlement; immediately invalidating the older lease would break in-flight reservations and the quiescence-gated release protocol. There is no lease-renewal operation.

The enforced contract is therefore exact and lease-scoped. Tokens are drawn from a strictly increasing per-account sequence, which supplies allocation and audit order without acting as an account validity epoch. Release matches the stored (lease_id, fencing_token) pair. Usage ingest matches the stored (lease_id, account_id, fencing_token) triple before applying the independent lease-state and conservation-capacity checks. A later grant never invalidates an older active grant; settlement or reclaim makes the lease unusable, and a matching capability cannot revive it. The capability is evidence that the operation names the stored grant, not proof that its token is globally newest.

The misleading contract survived because fenced_out_holder_rejected reclaimed the first lease before allocating its replacement. Its rejection proved only that a wrong token is refused and that a reclaimed lease stays settled; it never exercised two simultaneous active leases. The backend suites now name those obligations separately and mirror witnesses for concurrent active grants, wrong-token and wrong-account usage, settlement, reclaim, and capacity. Fenced remains the stable error/code for a token mismatch. When a client receives it for a token copied from its grant, clearing the current slot is a conservative fail-closed response to local/store divergence, not evidence that a newer account holder superseded the lease.

Failure behavior

Fail closed, always locally: unknown principal (negative-cached), suspended/ closed account, stale snapshot, missing permission, exhausted/expired/absent lease, cost overflow, accounting backpressure — all deny with zero units and zero I/O. Recovery is the background planes' job.

EnforcementMode::Elastic moves exactly one item off that list, per account: a lease that cannot fund the quote. The other conditions stay absolute under every mode, because a lease refusal is the only one of them that says something about funding rather than about validity. An elastic admission is not a fall-through to a slower path — there is still no I/O, and the elastic path adds no clock read — it is a debit against a different local counter, and the resulting units are recorded as overage rather than forgiven. The counter distinguishes committed spend from pending reservations because the retry contract depends on that boundary. Reservation phase and aggregate committed occupancy are separate atomic words, so AccountOverage::publish_commit installs a publication marker before it invokes the phase CAS and removes it only after committed occupancy advances. OverageCommitInProgress is the observer-visible answer inside that interval; it is AfterInFlight and maps to 503 because retrying after the publication settles obtains the stable answer without promising that answer will admit. OverageCapTemporarilyExhausted then means refundable pending occupancy is what prevents this request from fitting; cancellation or drop can recover, so it is transient and maps to 503. OverageCapExhausted means this request still would not fit in the local overage allowance after every pending reservation refunded. That is a stable statement about this instance's overage counter, not evidence about the account's central balance. Admission reaches it only after the installed lease was unavailable, expired, or exhausted, and an ordinary background grant can fund the unchanged request from existing balance. It is therefore transient and maps to 503; claiming payment is required would cross the request/control plane boundary without evidence.

The earlier counter stored only total occupancy. That was sufficient to prove the cap bound, but not to tell why a request hit it. Tests covered committed exhaustion and cancellation refunds separately, so none asked for the retry classification while the first reservation was still pending. The account counter now retains committed occupancy beside the total; reservation commit advances it only after winning the same commit/cancel CAS, and refusal compares the requested units against committed occupancy to decide whether refunding all pending work would help.

That first two-counter correction still left one invalid intermediate state: the reservation CAS could publish COMMITTED and the thread could stop before the aggregate counter advanced. The concurrency witness originally checked only after both racers joined, so it could not observe the interval. Reordering the writes merely reverses the defect — committed occupancy would then include units cancellation could still win — and spinning on a descheduled request would violate the bounded hot path. The publication guard is therefore owned by AccountOverage, and its method owns the caller's phase-CAS closure: the required order is encoded in the API rather than repeated as caller convention. A refusing observer uses a zero-delta RMW rather than a load, so it is ordered before, within, or after the marker's modification interval instead of accepting a stale zero that skips an already-linearized publication start. The marker is a third lock-free atomic; it adds no allocation, I/O, clock read, or blocking lock to admission. formal/lean/Tollgate/OveragePublication.lean proves that an active publication is never classified as refundable, that stable refundable/committed-saturation answers agree with committed occupancy, and that commit, cancellation, and a lost commit claim preserve occupancy bounds.

The deny vocabulary distinguishes transient from terminal, because the two call for opposite responses (GL-40). RateLimited means the bucket is momentarily empty and refills; UnpriceableUnderLimits means the quote exceeds the account's whole burst, so no wait can help — a schedule whose batch cap admits a request its burst cannot hold. The engine decides this in full width against the configured rate_burst_units before narrowing the weight into governor's u32 bucket, so narrowing cannot disguise the terminal case as the transient one, and the bucket-construction clamps in build_limiter never decide a verdict. Since tollgate-admission carries no logging dependency by design, the deny reason is the only channel this condition has.

Snapshot limit validation and rollout

Publication computes one worst-case quote from the largest registered per-item weight:

max(fixed_request + max_weight * max_items_per_request, minimum_charge)

The fixed-width operations are checked. Before that scan, both weighted-rate scalars are checked in full width against governor's non-zero u32 domain; zero or a wider value refuses publication rather than being repaired by the request-path defensive narrowing (GL-66). The carried pair is checked even when the new weighted-rate flag is disabled because a pre-GL-91 reader still enforces it during rollback. Overflow or a result greater than the carried rate_burst_units refuses publication; equality is valid. A table with no registered operation is valid only after the rate-domain check because no request can obtain a quote from it, but the configuration still has to be safe for every reader that accepts it. Selecting the largest weight is an O(n) control-plane scan, while request quoting remains direct-indexed O(1) with no new request-path work. The exact Lean model proves that the largest weight at the cap bounds every registered operation at every permitted item count; a Rust property test separately checks the maximum scan and u64 behavior against a u128 oracle.

The policy is strict refusal, not an implicit burst override: configuration values are operator contracts, and silently raising the burst would change the plan's rate semantics. The admin API returns 422 with stable problem code invalid-snapshot-limits. UnpriceableUnderLimits remains in the admission engine as defense in depth for a raw snapshot embedded directly by a caller.

This changes the public Rust store API (AdminStore::publish_snapshot and SnapshotResolution::Present) but not the wire DTO or database schema. For a rolling deployment, first audit stored and generated plans with the new validator and publish corrected snapshots at a higher generation, then upgrade every server/admin writer and client before relying on the invariant. Mixed versions are safe only in the fail-closed sense: an older writer can still persist invalid data, while a new Postgres reader or HTTP client refuses it. An already cached older snapshot remains usable only through its existing valid_until; if no corrected generation arrives, continuous readiness falls and admission denies. Recovery is to correct the plan and publish a higher generation. No SQL migration or automatic data rewrite is performed.

Two deliberate consequences:

• Cold start and degradation: an instance requires its snapshot set and healthy background tasks. Strict funding also requires a usable lease; Elastic may serve from overage headroom before the first grant arrives. Readiness (/readyz) continuously reflects snapshot freshness and task health, the refill task, current lease capacity/usability, and the accounting writer — it is not a one-way startup latch.
• Backend outage: instances drain their leases, then deny; the usage writer retries with backoff while the bounded queue sheds new work upstream with zero charge. Memory stays bounded; billing events are never silently dropped. For an elastic account the "then deny" becomes "then extend credit, then deny": the outage window is bounded by overage_cap per instance rather than by the lease, which is the trade the mode exists to make. Note this is the case that multiplies fastest across a fleet, since an outage reaches every instance at once.

Observability

Every failure mode in this design is deliberately silent and deliberately recoverable: the system denies, the background plane repairs, nothing throws. The difference between "working as designed" and "broken for twenty minutes" is therefore entirely a matter of reading the right signal at the right threshold, and those thresholds cannot be inferred from the metric names by anyone who does not already know the two-plane architecture. This section is that knowledge. Why the request path and the accounting plane report the way they do is in the dated entries below (GL-37, GL-38).

The three surfaces

Each background plane exposes its counters as a shared handle, because the manager itself is normally moved into whatever owns shutdown while a service keeps the counters in its request state. They outlive their task, so a reader keeps working after a plane dies.

The counters and health reads are library API. examples/pricing-api publishes them as JSON on /metrics, which is one way to expose them, not a product surface — an embedder chooses the format. Field names below are that example's, and match the library field names one for one.

Both counter sets are per instance, like the rate limiter: they say what this process admitted, refused and billed, and a fleet view is the scrape's job to aggregate. Neither survives a restart.

How events are chosen

The libraries emit tracing events and never install a subscriber — that is the embedding binary's decision. Two rules shape them. Level follows consequence, not cause: a lease acquire refused during ordinary rotation is debug because the instance keeps serving, while the same refusal against an empty slot is warn because every request is now denied. And an outage is a duration, not an event — the writer reports entering one once, stays quiet at debug while it persists, and reports recovery with how long it lasted and how many attempts it took, because WriterStats shows a recovered outage as a perfectly clean run.

tollgate-core and tollgate-admission are deliberately excluded: they gain no logging dependency, exactly as they take no I/O, which is why a request-path condition must be expressed in the deny vocabulary instead (see UnpriceableUnderLimits above) and why the request path reports itself with counters rather than events. The gate binaries (check_benchmark_thresholds, load_gate) keep println!: their stdout is a report consumed by CI, not diagnostics.

Events carry identifiers, never secrets: accounts, principals and leases are opaque newtypes, and a connection string is reported with its userinfo stripped before it can reach a log line.

Signals worth a response

Each of these looks benign in isolation, which is why each is written down. "Sustained" means across several scrape intervals — every one of these can tick once under normal operation.

denials.lease_exhausted rising while the account still has balance. Not enforcement — a refill-latency artifact. The instance spent its lease and the background manager has not yet acquired the next one, so requests are denied against an account that is funded (issue GL-10). Normal is zero outside brief rotation windows. Sustained means the refill loop cannot keep up with demand or cannot reach the allocator, and refill.refusals says which: insufficient_balance is a genuinely empty account, storage is a backend this instance cannot reach, and refill.acquire_timeouts is an allocator too slow to answer — which is not a refusal at all, since it may well have granted the lease and failed to say so. Do not route this to the customer as a quota problem unless the breakdown says insufficient_balance; otherwise they have paid for capacity they are being refused.

admitted_overage rising, on an elastic account. Not an error — it is the mode working — but it is the leading indicator of an invoice, the way accounting.rejected is the leading indicator of billing loss. It says this instance is admitting work the account has not paid for. Read it against total_overage_spent / total_overage_cap: the ratio is how much runway is left before a cap refusal starts. Both are per instance. Fleet exposure is the cap times the number of instances, so a cap that looks conservative on one box is not, and a control-plane outage reaches every instance at once. Restore lease capacity first; add funding only when the allocator specifically reports insufficient_balance. Raising the cap only buys time.

denials.overage_cap_temporarily_exhausted above zero. Pending overage reservations currently occupy the headroom this request needs. Cancellation or drop can return that credit without a funding or policy change, so the refusal is transient and maps to 503. Sustained activity means work is staying pending long enough to saturate the cap; inspect queue and execution-start latency before treating it as an account balance problem.

denials.overage_commit_in_progress above zero. A request reached a full cap while another request was publishing its commit decision into aggregate occupancy. The refusal maps to 503/AfterInFlight: retry after that decision settles, then act on the stable refundable or committed-saturation answer. A small count under contention is expected; sustained activity means committers are being delayed inside the short execution-start transition, so inspect CPU starvation and execution-start scheduling before changing account funding.

denials.overage_cap_exhausted above zero. This instance has spent enough non-refundable credit that the request would not fit even if every pending reservation cancelled. It is distinct from refundable saturation so operators can see that cancellation will not recover local overage headroom, but it is still a transient 503: a background lease refill can fund the unchanged request from existing central balance. Inspect the refill breakdown; fund the account only when it reports insufficient_balance, otherwise repair refill health or revisit the per-instance cap.

denials.unknown_principal spiking. Two very different causes. Either credentials rotated and callers are presenting keys this instance has never been told about, or snapshot distribution has failed and the instance has forgotten principals it used to know. snapshots.unresolved is the disambiguator: nonzero means distribution, zero means credentials. Only the first is an outage.

denials.snapshot_expired above zero. The control plane has stopped delivering and the installed snapshot has aged past valid_until. This is fail-closed working exactly as designed and an outage — the two are not alternatives. Normal is zero; anything else means the snapshot manager cannot reach its source. /readyz should already be false.

denials.accounting_backpressure / accounting.shed rising. The usage sink is behind and admission is shedding to protect the queue (INVARIANTS GL-8). Revenue-neutral by design — a shed request is charged zero — but it is the leading indicator of everything worse. Watch accounting.queue_depth approaching accounting.queue_capacity; the shed begins when they meet.

accounting.rejected above zero. The sink refused usage: unknown lease, lease-capability mismatch, or no remaining lease capacity. This is bounded billing loss that has already happened, and reconciliation is supposed to catch it. Normal is zero. A steady trickle usually means events are arriving after their lease settled — the drain deadline is sized too close to expiry_safety_margin + reclaim_grace.

accounting.lost above zero — and why it will not warn you first. These are committed charges that never reached the ledger. Any nonzero value is money. But it stays zero for the entire life of a process that cannot reach its sink: the steady-state path retries forever, so loss is only ever declared during the final flush at shutdown. Alerting on lost alone would mean discovering a twenty-minute outage at the moment the process exits. Alert on accounting.ingest_age_seconds instead — a sink that has not answered in minutes is the actual signal — and treat lost as the confirmation, not the warning. The same applies to the usage-writer shutdown failed event, which carries unaccounted: a lower bound on charges a dying writer was holding.

snapshots.refresh_attempts flat. Check task health before inferring an outage: an empty catalogue or the negative-cache schedule can also explain no fetches. An exited snapshot task leaves its retained readiness value false. Pair attempts with refresh_failures, refresh_timeouts and refused_updates to distinguish unavailable, slow and generation-incompatible sources. The snapshot operations guide defines the counters, structured refusal fields and recovery procedure.

refill.abandoned above zero. Leases a shutdown budget could not return to the allocator. Their units are stranded until TTL reclaim (INVARIANTS GL-9) — bounded, not lost, but capacity is unavailable meanwhile. Like accounting.lost this can only move at shutdown, so it is a post-mortem number: a rising count across restarts means shutdown_release_deadline is too tight for the allocator's real latency.

/readyz false while every task is alive. Not a crash: either the lease is unusable (expired, or exhausted) or the snapshot set is stale. This is INVARIANTS GL-10 keeping fail-closed correctness from masquerading as availability. snapshots.unresolved reports the last resolution pass; Fixed requires every tracked principal resolved, whereas All can serve with a partially unresolved set. Use the runtime's current funding and resolution report alongside that gauge. Zero unresolved alone does not establish readiness.

Reclaim sweep failure (consecutive_failures rising). INVARIANTS GL-9's server half: a store can answer ping and still fail reclaim_expired. While it fails, units from crashed holders stay stranded rather than returning to their accounts. Server readiness withdraws on the first failed reclaim or rollover pass, and three consecutive failures of either operation escalate its event to error. Recovery resets only that operation's streak. See the maintenance policy in CONTROL_PLANE_SECURITY.md for task-exit and shutdown behavior.

Any error from the control plane, always. None of them is routine: a snapshot or writer task that died, an allocator answering a release with an acquire-only refusal, and — most serious — the store rejected this release as an accounting error, which means local counts disagree with the ledger and readiness has already dropped.

Suspension, revocation, and closure: which mechanism

Three operator actions sound interchangeable and are not. Each has a different scope, a different blast radius, and a different answer to "can I undo it".

The status change answers with what it did — republished, and unreadable for rows that changed durably but could not be decoded to push. republished: 0 is the one worth reading: the account had no live snapshot to change, so it has no credentials, or they are all revoked, or the call was a repeat. Any of those is better learned at the call than from a later denial.

Suspension is per account and closure is the same action made terminal; revocation is per credential. Rotating one leaked API key should not suspend the customer, which is why revocation stayed a separate mechanism rather than being folded into the status change (GL-51).

An outstanding lease is not reclaimed by a status change. Its units were debited when it was granted, so spend after suspension is bounded by units the instance already holds, and the lease settles at release or TTL reclaim (GL-9). For an elastic account that bound is looser by the overage cap: until the suspending snapshot installs, an instance may extend up to overage_cap unfunded units on top of what it holds. The units are still recorded and still billed, so the exposure is visible rather than lost — but an operator sizing a cap should read it as "what a suspension cannot stop for one refresh interval", not only as "what a funded account may overdraw". Reclaiming early was considered and rejected: it would credit a lease back out from under an instance that may still commit against it, which is the GL-12 window the whole reservation protocol exists to protect. An operator who needs a harder stop than one refresh interval has to cut the tenant's traffic off upstream; the ledger cannot offer one without breaking that window.

Worth knowing before choosing a refresh_interval: a status change on an account with more than PUSH_CHANNEL_CAPACITY (256) live principals overruns the push channel, so every subscriber lags and resyncs its whole tracked set. That is correct and bounded by max_concurrent_fetches, and it is logged, but it is the reason a very wide account propagates by resync rather than by push.

Elastic enforcement has no account-level operator action (GL-1)

EnforcementMode rides on the snapshot and is set by publishing one, like ResolvedLimits, PermissionBits and the cost table. There is deliberately no set_enforcement_mode mirroring set_account_status, and the reason is worth recording because GL-51 argued the opposite for status and the two cases look alike.

What made status different was two records for one fact: the ledger's status column and the published AccountStatus, with two propagation paths and nothing checking them against each other, so "deactivate" returned success while the request path kept admitting. The mode has one record. No store operation consults it — leases are granted the same way for either mode — so adding a ledger column would create the second record that unification existed to remove.

The remaining worry is divergence across an account's principals, and the shared counter already bounds it. Every principal of an account debits one AccountOverage, so N credentials with N caps expose the account to the largest cap, never their sum — which is the difference from the per-principal rate limiter that would have multiplied an account's allowance (review finding GL-4). divergent_caps_bound_an_account_by_the_largest_not_the_sum pins it. What divergence does cost is that lowering a cap does not bind until every principal of the account is republished; that is true of every per-principal policy value already, and the control plane owns it.

PublishableSnapshot::restamped therefore stays infallible and stays unable to change the mode. The mode participates in publication validation — a cap that cannot fund one worst-case request is refused, for the same reason a batch cap above the burst is — so re-stamping it would need a fallible signature and would carry a proof forward over a value that proof depends on.

Reconciliation: checking the two ledgers agree

The per-account equation above includes both overage funding and expired allowances.

Both backends implement it as conservation(account), returning a Conservation whose holds() performs the comparison in checked arithmetic on both sides — an overflow answers "violated" rather than wrapping to a total that might coincidentally match. That is the supported way to check a live system — every backend suite asserts it exactly, so it is the same check the tests run:

#![allow(unused)]
fn main() {
// PostgresStore: async, and None when the account does not exist.
let c = store.conservation(account).await?.expect("account exists");
assert!(c.holds(), "{c:?}");

// MemoryStore: the same shape, synchronous.
let c = store.conservation(account).expect("account exists");
}

Against a Postgres deployment directly, the sweep below reports every account whose ledgers disagree. It returns no rows on a healthy system — that is the passing result, and it is what to alert on being non-empty. state = 0 is an active lease; usage on active leases sits inside their grants, which is why settled_usage subtracts it back out. The funding sum is promoted to PostgreSQL numeric, as the lease sums already are, so adding individually valid BIGINT columns cannot overflow the sweep.

WITH parts AS (
    SELECT a.account_id,
           a.deposited,
           a.overage_recorded,
           a.balance,
           COALESCE(SUM(l.granted) FILTER (WHERE l.state = 0), 0) AS active_grants,
           a.usage_recorded
             - COALESCE(SUM(l.used) FILTER (WHERE l.state = 0), 0) AS settled_usage,
           a.settlement_loss,
           a.expired
    FROM tollgate_accounts a
    LEFT JOIN tollgate_leases l ON l.account_id = a.account_id
    GROUP BY a.account_id
)
SELECT encode(account_id, 'hex') AS account,
       deposited, overage_recorded, balance, active_grants, settled_usage,
       settlement_loss, expired,
       deposited::numeric + overage_recorded
         - (balance + active_grants + settled_usage + settlement_loss + expired) AS drift
FROM parts
WHERE deposited::numeric + overage_recorded
      <> balance + active_grants + settled_usage + settlement_loss + expired;

account_id is the 128-bit id stored big-endian, so a single account is WHERE a.account_id = '\x00000000000000000000000000000001' for account 1.

A companion sweep, in the same idiom, for the other pair of records that must agree — an account's ledger status and the status its live snapshots carry (GL-51). Since set_account_status writes both in one transaction this is now unnecessary by construction, which is exactly why it is worth publishing: it is the cheap auditor for hand-edited rows and for anything that ever writes tollgate_snapshots outside this code.

SELECT encode(a.account_id, 'hex') AS account, a.status AS ledger,
       encode(s.principal, 'hex')  AS principal,
       s.snapshot ->> 'status'     AS published,
       s.generation
  FROM tollgate_accounts a
  JOIN tollgate_snapshots s ON s.account_id = a.account_id
 WHERE s.deleted = FALSE
   AND s.snapshot ->> 'status' IS DISTINCT FROM a.status;

-- Companion: snapshots whose account cannot be derived from their JSON. These
-- are exactly the rows `StoredSnapshot` already fails to decode, so a nonzero
-- count is corruption -- and it is also the set a status change cannot reach.
SELECT count(*) FROM tollgate_snapshots WHERE account_id IS NULL;

The ledger stores the status as text in the same spelling AccountStatus serializes, rather than a SMALLINT code, so this check is an equality an operator can read with no codec in between.

A nonzero settlement_loss is not by itself a fault. A lease can be released while its usage events are still queued; the gap granted − used − unspent is provisional loss, and a late event that fits inside it converts back into billed usage (Finding 2). Expect it to appear transiently and trend to zero. What is a fault is loss that persists with an idle writer, which means those events never arrived.

If the equation does not hold, that is a defect, not drift. Steady-state drift is zero by design; the ledger reads are checked (INVARIANTS GL-11), so a negative column surfaces as an explicit store error rather than being clamped past the corruption this check exists to detect. A failing holds() on otherwise clean reads therefore means a genuine accounting bug. Capture the account row and its lease rows before restarting anything — a restart reclaims expired leases and rewrites the state that would explain what happened.

Consistency stance

Bounded consistency by choice: snapshot staleness is bounded by valid_until + push latency; revocation propagates via generation bumps and expiry. Revocation tombstones retain the removed generation in memory and Postgres. Request-visible negatives are bounded and evictable, but their generation watermarks survive ordinary visible eviction, so cache expiry cannot resurrect stale authorization. Bounded history reclamation removes visible state and fences outstanding reads; reopening requires a new authoritative source read. Source tombstones remain durable. Negative validity expiry schedules a targeted pull with retry backoff; it does not wait for a longer full-refresh interval and works over HTTP's explicitly closed push stream. A crashed instance strands quota at most until lease TTL. Immediate global revocation and durable-before-response accounting would require synchronous coordination per request — a separate strict-accounting mode could accept that cost, and nothing in the trait surface precludes it, but it is out of PoC scope.

Second review round (2026-08-20)

An external review surfaced eleven findings; all are fixed and regression- tested. The load-bearing ones and their resolutions:

1. Expiry race (critical): reservations could commit after their lease was reclaimed and re-granted. Now a three-part protocol — local usability window (expires_at - safety margin: debits AND commits stop, absorbing allocator/holder clock skew), commit-time recheck (post-window commits release for zero and must not execute), and store-side reclaim grace (expires_at + grace, with releases and late usage honored through it). Invariant GL-12.
2. Writer shutdown livelock (critical): edge-triggered shutdown could be consumed inside the retry loop; shutdown is now level-checked at every loop boundary, with a bounded, loss-reporting final flush. Dropped handles abort their tasks.
3. Commit/emission gap: the queue permit is the usage slot bound at admission; Committed's drop emits under panic/abort. Invariant GL-13.
4. Per-principal limiters multiplied account allowances; limiters now live in a per-map registry keyed by AccountId. Rate limits are enforced per engine instance (documented), leases aggregate spend globally.
5. Snapshot distribution: SnapshotManager (initial load gates readiness, push + lag recovery, periodic refresh doubling as bounded-window revocation); memory backend now generation-monotonic like Postgres.
6. Request ids: random 128-bit (UUID) — process-local counters collide across instances and misclassify legitimate usage as duplicates.
7. Account creation is AlreadyExists-surfacing in both backends (invariant GL-14); resets are a deliberate separate workflow (unbuilt).
8. Postgres ingest is one transaction per batch: sorted ANY() row locks, one dedup lookup, in-memory classification, UNNEST bulk insert, and set-wise grouped aggregate updates.
9. Bulk snapshot install: install_many — 512 principals load in ~54 µs vs ~820 µs as a per-entry loop on the arc-swap map.
10. Deadlines/Drop: HttpStore carries connect/request timeouts; background handles abort on drop instead of leaking spinning tasks.
11. Server: the service stays backend-generic; the binary selects memory or default-featured Postgres at build time, with versioned sqlx migrations. /readyz pings the store, and non-loopback binds warn.

Follow-up review round (2026-08-20)

The follow-up review found nine edge cases left after the first remediation; all now have regression coverage:

1. Usability-window rollover returns quota. A lease removed when its local usability window closes is parked under the same quiescence rule as a low-water rotation, then released during allocator grace instead of being forgotten until TTL reclaim.
2. Limit updates reach every sibling principal. Each account owns a stable limiter indirection. A newer account generation atomically swaps its inner governor bucket, so existing principal states immediately see the new limits; stale snapshots cannot roll it back.
3. Revocation is a versioned state. Positive and negative map entries share generation ordering. Memory and Postgres retain deleted snapshot rows as tombstones; migration 0002_snapshot_tombstones.sql adds the durable marker.
4. Timing configuration is validated. Stores, lease/snapshot managers, and the server reject unsafe signs, zero scheduler intervals, and inconsistent lease thresholds before starting. A nonpositive requested TTL is refused before any balance debit.
5. Readiness is continuous. Snapshot resolution deadlines are tracked even while a source fetch hangs; task/channel closure, an exhausted or unusable lease, or a stopped accounting writer all lower /readyz.
6. Final accounting respects the batch contract. Shutdown drains no more than max_batch per sink call, retries each chunk a bounded number of times, and reports rejected/lost totals to the embedding application. The drain waits for outstanding permits, not just buffered events (GL-32): closing the receiver refuses new reservations while permits reserved earlier can still deliver, and a real receive distinguishes "a reserved slot is still out there" from "done" — try_recv cannot. The wait is bounded by shutdown_drain_deadline; permits unresolved at the deadline are reported in WriterStats::unresolved, their charges bounded thereafter by TTL reclaim. The report survives the writer's own death (GL-41): charges are counted from the moment they enter the queue until they are given an outcome, in a counter held outside the task, so a panicked or aborted writer returns WriterShutdownError with a lower bound rather than a zeroed report. WriterStats is intentionally not Default — that derive is what made unwrap_or_default() on a dead task's JoinError spell "nothing was lost".
7. Snapshot sweeps are bounded and cancellable. Fetches use configured concurrency, shutdown aborts outstanding calls, results are classified in linear time, and mixed positive/negative results land in one arc-swap RCU update. The same property now holds for the other two background planes (GL-34), by a different mechanism: a sweep owns spawned tasks and can abort them, whereas an ingest/acquire/release future borrows its arguments, so those are bounded with timeout instead — per call, and per shutdown in total. HttpStore had carried these bounds at the transport since the beginning; the client now holds them for whichever backend is plugged in, including a direct MemoryStore or PostgresStore.
8. Postgres lock order is deterministic. Multi-account ingest aggregates use ordered maps and explicitly pre-lock accounts in byte order before their set-wise update; reclaim pre-locks its accounts the same way. Neither path relies on an UPDATE ... FROM executor preserving input-array order, so the random HashMap account-row deadlock cycle cannot return.
9. Postgres generation conversion is explicit. Values above the signed BIGINT range return an error instead of silently aliasing to i64::MAX.
10. Postgres stored values cannot go, or read as, negative (GL-15, GL-45). Unit columns and fence counters carry schema CHECK constraints, the settlement-loss subtraction refuses (and rolls back) a batch that would underflow it — the SQL form of the memory backend's straggler assertion — and every read of a unit column or fence surfaces a negative value as a storage error naming it. Clamping negatives to zero would let Conservation::holds() pass over exactly the corruption class the equation exists to detect, and aliasing a corrupt fence to 0 would misreport corruption as a caller's capability mismatch. Accepted usage events reuse the validated stored fence rather than reconverting the event's token, making the insert-side aliasing unrepresentable.

Negative-cache remediation (GL-14, 2026-08-22)

The ArcSwap map previously retained every negative indefinitely and treated the TTL as request-invisible metadata. The root fix separates two concerns: the request-visible negative set is capped, expires on control writes, and evicts earliest deadlines first; the separately retained generation watermark keeps authorization monotonic. The later GL-67 retention boundary bounds that history through fenced authoritative reconstruction, independently of TTLs. SnapshotManager owns each negative's deadline and per-principal retry schedule, so expiry triggers a targeted pull. The same generation transition functions have property tests and a Lean model proving that revocation followed by eviction still rejects an at-or-below-generation positive replay.

Continuous accounting health (GL-38, 2026-08-23)

WriterStats existed exactly once — a local on the writer task's stack, materialised only when the task returned. So the numbers that decide whether billing is intact were legible only after a graceful shutdown, which is the one ending where loss is least likely; a process that crashed, was killed, or simply kept serving said nothing.

The fix was not to add a second tally but to move the existing one out of the task, following the unaccounted counter that already lived outside it for exactly this reason. shutdown now returns a snapshot of those same counters, so "the running totals match the final report" is true by construction rather than by test. The counters written from the request path — unaccounted and the new shed count — take a cache line each, because folding them in beside the task's own counters would have introduced false sharing that the previous standalone Arc<AtomicU64> did not have.

What an operator should actually watch, which is not what it looks like. lost is the number that matters for billing integrity, and it stays zero for a healthy-but-cut-off process's entire life: the steady-state path retries a failing sink forever, so nothing is declared lost until the final flush gives up. Told to "watch lost", an operator would be watching a counter that can only move at shutdown. The runtime signals are the age of the last successful ingest, a queue depth approaching its capacity, and rejected — events the sink has already refused, which is bounded billing loss reconciliation is meant to catch. This is the substance GL-39 has to convey.

Readiness is deliberately untouched. A sink outage does not stop an instance admitting — leases still fund requests — so flipping /readyz would withdraw healthy capacity during a billing-backend outage. INVARIANTS GL-10's bar is that the accounting task is alive, which recorder.is_closed() already answers.

Request-path counters (GL-37, 2026-08-23)

The control plane reports itself with structured events (GL-36). The request path cannot: INVARIANTS GL-5 bars I/O there, the hot-path budget bars blocking locks and policy clock reads, and a logging call is all three — which is why tollgate-admission still carries no logging dependency. The affordable channel is a counter, and DenyReason being a closed enum is what makes it cheap: DenyReason::COUNT slots in a fixed array indexed by an exhaustive DenyReason::index, so there is no map, no string key, and no way for a new variant to reach a slot it shares with another.

Three things fell out of building it that were not obvious from the issue:

• One recording point, not ten. Several reasons never appear literally in admit — AccountSnapshot::admit and Reservation::reserve raise them and ? carries them out. Instrumenting the exits would have produced counters that were quietly incomplete for exactly the reasons an operator most wants (staleness, permissions, lease expiry). Recording the single outcome of admit cannot miss one.
• Padding helps the array, but the contended case required sharding. Each original counter took its own line so cores counting different reasons did not false-share. That did nothing for full_check_contended_8, where every thread admits and writes one slot — true sharing. Issue GL-3 subsequently moved opt-in counters to sticky-locality shards and corrected the supported line assumption to 128 bytes; the instance snapshot aggregates them.
• No deny path was benchmarked at all. Both hot-path benches set limits high enough that only the admit path runs, so "the counters are free" had no witness on the path the counters exist for. admission/full_check_denied fills that gap at 19.7 ns — the cheapest refusal, where a per-outcome tally is the largest possible share of the work.

units_admitted counts what admission quoted, never what was billed: a reservation cancelled before execution charges zero, and usage events remain the billing record (see "Two ledgers, one truth"). Refusals decided before the engine is consulted — accounting backpressure under INVARIANTS GL-8, and a credential that fails verification — are recorded by the embedder against the same tally, so no reason exports a permanent zero that would read as "this never happens". The example exposes the tallies as JSON on /metrics deliberately: naming the metrics is this change; choosing an exposition format and documenting it for operators belongs to GL-38 and GL-39.

Set-wise PostgreSQL usage ingest (GL-5, 2026-08-23)

Review round 8 aggregated accepted events in memory but left both aggregate writes as per-key executor loops, so a 256-event batch could still hold its row locks across hundreds of database round trips. The semantic store suites could not expose query-count scaling, and there was no PostgreSQL ingest benchmark spanning many distinct leases and accounts. The benchmark added with this remediation makes that missing dimension reproducible without encoding SQL source text into a test.

The first merge-request mutation run also exposed an unwitnessed branch in the mixed-batch contract: a missing lease must contribute one rejection. The mirrored scenario now includes that case. An earlier local parallel run had reported the mutant caught for the wrong reason because independent nextest processes could truncate the same PostgreSQL test database underneath each other. The mutation wrapper therefore permits only one cargo-mutants worker whenever PostgreSQL is enabled; nextest test groups alone serialize only inside one process and cannot enforce that cross-process ownership rule.

Usage ingest preserves its partial-acceptance contract in application code: each input is classified once against the locked lease rows and the existing request-id set, then the accepted subset is committed atomically. Encoded IDs and timestamps are prepared once per event before the transaction. Checked BIGINT units are computed once after duplicate and capability classification. An out-of-domain new event contributes one rejection; a stored invalid value remains a store error. Accepted units are reused by every write, preserving the existing rule that a replay is a duplicate regardless of its other fields. Duplicate and rejected inputs never enter the insert or either aggregate delta.

Accepted events still land through one UNNEST insert. Per-lease usage and per-account usage/loss movements now land through one UPDATE ... FROM UNNEST(...) statement each instead of one statement per distinct record. The grouped deltas use checked arithmetic, and inserted or updated row counts must equal the verified input cardinalities before commit. Lease update deltas are stored as Option<NonZeroI64> during classification, so rejected, duplicate, and zero-unit events cannot make a no-op lease row enter the set-wise write.

Set-wise update execution does not promise row-lock order. The transaction therefore pre-locks leases in (account_id, lease_id) order — shared with any concurrent ingest, which is what a lease-lock cycle would need, and no longer shared with reclaim, which since GL-65 selects in expiry order and cannot be a party to such a cycle because SKIP LOCKED means it never waits for a lease — and explicitly locks every affected account with ORDER BY account_id FOR UPDATE before the account update. The account IDs come from a BTreeMap, and the locked rows are also where stored usage overflow and settlement-loss underflow are validated before mutation. This preserves the global lease-then-account order and the deterministic multi-account ordering established by the earlier concurrency remediation.

For E events, D_l distinct leases, and D_a distinct accounts, preparation is O(E), ordered lease indexing/classification is O(E log D_l), and ordered account aggregation is O(E log D_a). SQL bound-parameter and touched-row volume is O(E + D_l + D_a). The number of database round trips is constant in D_l and D_a; the old aggregate phase issued D_l + D_a sequential updates while holding the transaction locks. No schema, migration, configuration, wire, production-dependency, public Rust API, or request-hot-path change is involved.

The committed non-gating Criterion scenario measures 256 accepted events spanning 256 leases and 256 accounts against the same local PostgreSQL host; its fixture is isolated in a generated temporary schema rather than truncating the URL's existing tables. Absolute timings are host-dependent, so evidence is collected by running this scenario on both revisions against the same database without competing workloads. Two uncontended same-host runs on 2026-08-23, performed in reversed revision order, produced central estimates of 240.10 ms and 208.31 ms for untouched origin/main, versus 6.7127 ms and 7.1645 ms for the set-wise implementation: 35.8× and 29.1× faster in the paired runs.

Bounded PostgreSQL expiry reclaim (GL-6, 2026-08-23)

Expiry reclaim is bounded at the transaction boundary, not at the size of a legitimate outage backlog. LeaseAllocator::reclaim_expired_batch takes a nonzero limit and returns ReclaimBatch: its private saturation evidence is derived from the returned row count, so the server consumes verified evidence rather than guessing whether to continue. The original reclaim_expired(now) API remains as a full-drain convenience over bounded batches; if a later batch fails, its error names the already-committed partial progress. Existing callers and the /v1/leases/reclaim JSON array therefore retain their contract. Store trait implementors must add the bounded primitive; that is the sole source migration.

The server reads one clock value per scheduled cycle and drains against that fixed cutoff until a batch is not saturated. The backlog is therefore finite even while new leases expire, and a yield between batches keeps the in-memory backend from monopolising an executor thread. A failure after earlier batches reports their lease, unit, and batch totals; committed recovery work is never silently presented as a wholly failed sweep.

The PostgreSQL transaction locks at most 256 leases through the partial expiry index, ordered by that index's own (expires_at_floor_us, expires_at_submicro_ns) so the LIMIT stops the walk (GL-65), with SKIP LOCKED cooperation between sweepers. It validates every credit before mutation, aggregates account credits in a BTreeMap, explicitly locks the affected account rows in byte order, then updates all selected leases and all affected accounts with two UPDATE ... FROM UNNEST(...) statements. Account pre-locking matters because a set-wise update does not itself promise row-lock order. Row counts are checked before commit, and all exits retain the explicit commit/rollback completion contract below.

For a batch bound B, each transaction now performs a constant number of SQL round trips and holds O(B) rows, while an N-lease backlog drains through O(ceil(N/B)) short transactions. The old shape held all N lease and account locks across 2N sequential update round trips. No schema, configuration, wire, dependency, or request-hot-path change is involved.

PostgreSQL transaction completion (2026-08-23)

The Postgres wrong-token release scenario exposed a scheduler-sensitive failure: a rejected release returned, then the immediately following reclaim sweep sometimes found no expired lease. The ledger was intact. The first operation had dropped an open sqlx::Transaction; SQLx queues rollback on drop for a later async connection operation, while reclaim deliberately uses SKIP LOCKED. Under the failing interleaving, reclaim skipped the lease row whose failed release had already returned but whose queued rollback had not yet released the lock.

The original backend relied on drop rollback on every ? and domain refusal. Local runs normally completed the queued rollback quickly enough, and the failure-path tests generally checked ledger state through a later pooled query rather than checking that the returning operation had released its locks. The wrong-token scenario's immediate sweep was the one indirect witness, and it passed until a slower CI schedule produced the narrow interleaving. Transaction completion is now owned in one pair of helpers: acquire, release, reclaim, and ingest route their entire transactional bodies through them, await commit on success, and await rollback before exposing any failure. wrong_token_release_leaves_lease_reclaimable is the regression witness because its immediate release-then-reclaim sequence exercises the contract without a sleep or retry that could conceal it.

Fast principal hashing (GL-9, 2026-08-23)

Every request-path lookup hashed a 16-byte Principal through SipHash-1-3, because the snapshot maps used the default RandomState. That resistance defends against an attacker steering keys into one bucket — and Principal is a fingerprint of an already-verified credential, derived under a secret the caller does not hold, so the keys cannot be steered.

The stronger form of the argument is what settled it. An embedder who does key admission by a raw client-supplied token has not merely weakened their hashing: that value selects which account's snapshot, lease and rate limiter a request lands on, so a caller who can choose it can aim at another tenant. SipHash never defended against that. There is no configuration in which it was buying the protection its cost implied, which is why the fix is a hasher swap plus documentation on Principal rather than a per-deployment switch.

Both maps use foldhash::fast::RandomState through one alias, PrincipalHasher. foldhash was already compiled into tollgate-admission's graph (governor → hashbrown → foldhash), so taking it directly adds no package to the build — the same argument atomic-waker carries for GL-10. Moka changed alongside arc-swap deliberately: the gap between the two lookup benchmarks is the evidence for which map to deploy, and it would have quietly become "one of them hashes differently" had only one side moved.

Measured paired in one session, reverting the alias in place rather than comparing against a stored baseline (the method GL-49 records):

cost_table/quote, snapshot/admit and both lease/reserve_* benchmarks were identical on both sides, which is what makes the rest credible: an untouched control moving would have meant a disturbed host rather than a real change. full_check's 15.9 ns saving exceeds the 9.8 ns measured on the isolated lookup, and the remainder is not accounted for by the hash alone — recorded rather than explained away. full_check_contended_8 improved too, but its own baseline spread was 20% across runs, so no figure from it is quoted.

The choice of hasher is argued, not assumed. A raw identity fold over the u128 — the cheaper alternative — fails on sequential principals: hashbrown takes its control byte from the top seven bits of the hash, and consecutive integers leave those constant, collapsing 4,096 keys onto one control byte. principal_hashing_stays_spread_for_sequential_and_random_keys checks the low bits and the top bits separately, on both key shapes an embedder produces.

The first version of that witness constructed RandomState directly and required every bucket count to stay below a statistical threshold. That made the test depend on the process-generated shared and per-hasher seeds even though foldhash::fast is designed for hash tables and explicitly does not promise statistical-quality output. A release pipeline found 87 sequential keys in one low-bit bucket where the test allowed 64; the identity-fold defect the test exists to reject would put all 4,096 sequential keys in one top-bit control value. Local and prior CI runs missed the defect because each process sampled a different seed.

The witness now exercises a fixed matrix of shared and per-hasher seeds through SeedableRandomState, while a compile-time assignment keeps the production alias tied to fast::RandomState. The map therefore retains randomized seeds; only the evidence is deterministic. A same-pattern search of the Rust tests found no other randomized hasher distribution bounds.

Credential verification belongs in the library (GL-2, 2026-08-24)

The pricing-api recomputed HMAC-SHA256 on every request even though the load gate deliberately uses persistent connections. Paired profiling showed the credential check, not quota admission, dominated the sequential overhead, and measurement put numbers on it: ~800 ns to verify a credential against ~107 ns for an entire admission. The step in front of tollgate cost seven times everything tollgate does.

That is why this landed in crates/tollgate-auth rather than in the example where it was first written. A library that tunes 107 ns to the nanosecond while leaving 800 ns to each embedder is tuning the wrong end, and the load gate cannot honestly attribute overhead to tollgate while example-service HMAC dominates the delta.

The crate is split where the problem splits. Credential schemes differ per deployment, so CredentialVerifier is a trait and the embedder may bring PASETO, JWT, or a certificate fingerprint; HmacRegistry is the scheme in the box. What is not deployment-specific is the caching, and that is the part worth centralising: SessionCredential verifies at most once per session and compares thereafter. The embedder supplies only the two transport-bound facts the library refuses to guess — what a session is, and how to get credential bytes out of the wire format.

Measured on one machine:

A miss is ~238 ns dearer than the uncached path, because the entry has to be installed. A session serving exactly one request is therefore slower than before; the extra is repaid by the first hit, so the cache is ahead from the second request on a session onward. The load gate runs 5 000 requests over 10 persistent connections — 500 per connection — so the configuration this project measures sits at the asymptote, not the break-even. An embedder serving one-shot connections should know the trade runs the other way for them.

Why HMAC survived the move. Plain SHA-256 is 181 ns against HMAC's 741 ns — four times cheaper, better than the halving originally guessed. But caching moved that saving from once-per-request to once-per-session, making it ~5.6 ns per request at a hundred requests per session, against a 16 ns cached path it cannot touch. HMAC keeps the secret and the digest table separately insufficient; the cheaper digest buys a rounding error and costs that. Caching did not make the swap more attractive — it removed most of the reason for it.

The cache proves identity, never authorization (INVARIANTS.md GL-23). A hit skips the credential check and nothing else: admission still runs against the current snapshot every request, so revocation stays bounded by snapshot refresh exactly as it is with no cache. Requiring ConnectInfo<PricingConnection> in the handler makes incorrect server wiring fail visibly instead of silently reverting to per-request verification, and credential/verify_cached is gated so a regression that bypasses the cache shows up as a number rather than as nothing at all.

Memory backend sweep cost and growth (GL-23, 2026-08-23)

MemoryStore never deletes, and both of its scans walked the whole lease table: the reclaim sweep filtering for active-and-due leases, and conservation summing one account's active grants. The server runs the sweep every five seconds by default, so its cost climbed for the life of the process while the live population stayed flat.

Postgres never had this. Its equivalents push the filter into SQL (WHERE account_id = $1 AND state = 0, plus GL-6's partial expiry index), so the reference implementation — the one whose job is to define the semantics the real backend reproduces — was the only one whose cost model was wrong.

Active leases are now indexed by expiry in crate::leases, and the sweep walks that index in order, stopping at the first lease not yet due. The interesting decision was where the index lives. It is derived state maintained at three transition points spread across acquire, release and the sweep, and the drift it invites is silent and severe: a lease left active in the table but missing from the index is never reclaimed and stops being counted by conservation, so the ledger checker goes blind to the leak it caused. So the table and the index live behind one type, with state and credited private to it and a single settle transition — no call site can retire a lease and forget the index, because none of them can retire a lease at all. That also makes state and credit move together, which two settlement sites previously maintained by hand.

conservation still recomputes its sums from the lease records. Caching per-account aggregates would be faster and is the wrong trade: this function exists to catch ledger bugs, and one that reads a total maintained by the same writers that might be wrong cannot catch them. The index narrows which records it reads; it is never the source of the numbers.

Reclaim order becomes expiry-ordered rather than HashMap-arbitrary. Nothing depended on the old order — expired_backlog_is_reclaimed_in_bounded_batches sorts before comparing — and determinism is an improvement.

Growth itself is unchanged and now visible: MemoryStore::stored_records reports usage events, lease records, and how many of those are active, and the sweep logs them once per drain at debug. Putting the active count beside the total is the point — the sweep's cost tracks the one that stays flat while the others climb. Usage-event retention remains deferred; it needs a dedup-window decision, not a deletion.

The reconciliation query's account filter (GL-12, 2026-08-23)

conservation sums one account's active leases, and nothing indexed account_id. The issue that raised this predicted a sequential scan of a table that grows with every lease rotation and is never pruned. Measured, that is not the mechanism, and the difference matters for what the fix is worth.

tollgate_leases_expiry is already partial on state = 0, so PostgreSQL scans that — the live set, fleet-wide — and discards the rows other accounts own. The cost therefore never grew with lifetime rows. It grew with the number of live leases across the whole fleet: a per-account reconciliation query paying for every other account's live set. Bounded, but the wrong bound.

Measured on 220,000 lease rows, 20,000 of them live across 2,000 accounts, asking for one account's ten:

"Rows Removed by Filter: 19990" is the whole story, and migration 0005 removes it: (account_id) WHERE state = 0, partial for the same reason the expiry index is, so it stays proportional to live leases rather than to the table.

Two notes on the migration itself. It is CONCURRENTLY, unlike 0003 and 0004 — those add constraints to tollgate_accounts, one row per account, where a brief ACCESS EXCLUSIVE scan costs nothing; this one touches the unbounded table, where a plain CREATE INDEX would hold a SHARE lock and block lease acquisition for its duration, which in this system means the request path failing closed. And it deliberately omits IF NOT EXISTS: a concurrent build that fails leaves an INVALID index, and IF NOT EXISTS would let the retry skip it silently while the query kept discarding rows. Failing loudly is the only version an operator can act on; the migration carries the recovery step.

The regression witness is a plan assertion rather than a timing, and what it pins is that the account predicate is an Index Cond rather than a Filter. "No sequential scan" would have been the wrong property twice over: there was no sequential scan before the fix in the settled-heavy shape, and there is one without the index in the live-heavy shape. Only "answered by an index, not by discarding rows" is true in both.

Dependency advisory gate (GL-26, 2026-08-23)

Every merge-request and default-branch pipeline audits the committed Cargo.lock with pinned cargo-audit 0.22.2. Vulnerabilities fail by default, and --deny warnings promotes yanked, unmaintained and unsound dependency findings to failures too. The version lives in .cargo/audit-version; the CI job installs exactly that locked release without the unrelated binary-scanning feature, and scripts/check_advisories.sh refuses to run under a different one. cargo-deny was not selected because this issue establishes an advisory contract, while license, source and duplicate-version policy each need their own deliberate baseline rather than defaults smuggled in with the security gate.

The initial strict scan found one advisory: RUSTSEC-2023-0071 against rsa 0.9.10, with no fixed release. The workspace enables only SQLx's PostgreSQL support, but Cargo records the published sqlx-macros-core package's optional MySQL graph in the lockfile, and that graph contains sqlx-mysql and rsa. An all-target, all-feature inverse cargo tree over normal, build and development edges finds no workspace path to rsa, so it is not compiled into any Tollgate target.

That exception is executable rather than permanent. Before auditing, the wrapper fails if rsa becomes reachable under the broad workspace graph. The ignored audit then blocks every other finding. Finally, an unignored audit against the same freshly fetched advisory database must fail; if it passes, the exception is stale and the gate requires its removal. This gives the sole escape hatch both an immediate safety boundary and an automatic exit.

The change is CI-only: it alters no public API, wire contract, migration, runtime behavior, allocation, or request-path performance.

GitLab Cargo cache policy (GL-30, 2026-08-24)

The GitLab migration replaced Woodpecker's within-run shared target/ with a static cargo-registry archive inherited by every job. That made unrelated jobs restore Cargo state, and GitLab's default pull-push policy let parallel jobs replace the same archive with whichever partial view finished last. It stayed green because a cache miss is recoverable and the configuration is syntactically valid; the failure was wasted work, visible in runner traces rather than test results.

The shared build cache is now content-addressed by both Cargo.lock and rust-toolchain.toml. It contains the narrow Cargo registry and Git database paths from the canonical pipeline plus target/, accepting one archive upload per merge-request pipeline to recover cross-job build sharing. clippy is the sole pull-push producer in the check stage. The Rust build jobs in later stages inherit one pull-only cache mapping; formatting, repository checks, dependency audit, formal verification, and the Rust 1.89 MSRV job do not extract target artifacts they cannot use. Formal verification and release-plz retain their own disjoint keys and lifecycles.

CI uses .ci-cargo rather than .cargo for generated Cargo state because the latter contains tracked audit and mutation configuration. CI caches are not assumed to be distributed or durable, so every job must remain correct when the cache is absent. A shared mapping makes pull-only the default, with the one writer expressed as the sole explicit policy override.

Mutation baseline for the pre-gate crates (GL-43, 2026-08-24)

INVARIANTS.md names a test behind every invariant, which is the right rule but does not establish that the named test would fail if the invariant broke. The diff-scoped gate has answered that for everything written since it landed; these three crates were written before it.

The expectation going in was the client's first-run rate — 66 of 88 viable, a 25% survival — which would have meant roughly 80 survivors across 321 mutants. The measurement was 12. Reservation commit/cancel, the lease usability window, settlement arithmetic and the conservation equation were all already pinned. What survived was almost entirely accessors and admin operations: code whose callers were tests rather than the paths the suites were built around.

Ten were gaps and got tests. Two were equivalent and are excluded with their arguments. Three findings were worth more than the tests themselves:

• The two backend suites had drifted. inactive_account_refuses_leases called the inherent set_active on the memory side and AdminStore::set_active on the PostgreSQL side, so the memory backend's trait implementation could be replaced by Ok(()) — suspending an account and continuing to serve it — with everything green. Neither suite exercised deposit or the TTL clamp at all. Those scenarios now exist on both sides, which is what a mirror is for.
• Arc<T>'s SnapshotMap delegation had no witness for its bulk writes. install_many and apply_many could both be no-ops. That impl is ?Sized, so SnapshotManager's own Arc<dyn SnapshotMap> dispatches through it: a silent no-op means a refresh pass that reports success and installs nothing, every principal ageing out to SnapshotExpired with no error anywhere.
• One survivor was dead code, not a missing test. Correcting the memory suite to call the trait method left the inherent MemoryStore::set_active with no callers anywhere in the workspace. Writing a test for it would have turned the gate green without making anything safer, so it was deleted.