11CContact

Piper · Chapter 1 of 1

Authority

Who may move money, and how that is enforced: three work classes, a signer the build fences off, autonomy as a class, one write per mandate, and a bound only the owner may widen.

Every other part of Piper depends on one guarantee: nothing moves money except a hop, and nothing widens a bound except the owner. This chapter is how the runtime makes that true, and how each piece was tested against the incidents that came close to breaking it.

Three work classes

The runtime is one container image. Each deployment chooses its class when it starts. A missing or unrecognized class refuses to start. It never defaults, and above all never defaults to the class that signs, because a typo that silently starts the signer is the expensive direction to fail. The start command checks the class before it migrates the database, then migrates, then starts.

The split is the order path against everything else. It is not a split on cadence.

verbs public reads signed writes its own account Phone console Front door Research class Owner shell Postgres rows Signing class Broker class Primary venue Broker account
Three classes from one image. Only the signing class can sign the primary venue, and it never listens.

Every durable fact is a Postgres row. Redis holds liveness, locks, and leases, and it is never the authority. Exact decimals travel as strings, so a value comes back with the sign and scale it went in with, and a missing value stays NULL rather than becoming zero.

One live process per class

The hosting platform starts a new deployment before it stops the old one, so for a few seconds on every redeploy two processes of a class exist. Two clock groups driving one account is the thing that must not happen. So each class holds a lease, renewed and released only by the token that took it.

It is a lease and not a semaphore because a counter has no owner. Once a counter's slot lapses and a second process takes it, the first process's renewal extends somebody else's admission and its release frees somebody else's slot. A counter is right for at most N concurrent things and wrong for exactly one live process, which needs identity. A successor waits for the lease rather than refusing, because a predecessor holding it is the normal case. A process that exited on contention would exit cleanly, the platform would mark the deployment complete, and the class would have no live process at all. An exhausted wait exits with an error, so the platform restarts it.

Boundaries are not intervals

Each class runs one loop that evaluates its clocks, runs the due ones in order, records each fire, and sleeps. The risk clock is an interval. The others are boundaries, which an interval cannot build: an hourly interval started at 12:34 fires at 13:34 and misses every top of the hour by thirty-four minutes, forever. A boundary clock asks whether the boundary containing this instant has already been serviced, answered against its last recorded fire, so a restart neither misses one nor fires it twice. A fire is recorded after the handler returns, so a crash mid-tick leaves the clock due rather than silently consumed.

A clock whose work has not landed carries a handler that says so out loud. A handler that looks like a risk check and is not one is worse than an empty clock, because the next session believes risk is covered, and a structural test keeps the placeholder in place until something real replaces it.

Streams run beside the clocks, never on them, and they start only once the class holds its lease, so a successor never shares a socket or a port with its predecessor. Anything that signs runs inside the signing class's risk tick, never in a sidecar on the research class.

The platform's default grace between a stop signal and a kill turned out to be zero seconds. That was measured, not assumed. A stop asks the clock group to finish between clocks, never mid-tick, and if the deadline lapses the process exits and its lease lapses with it, which is safe because of the recovery sweep at the end of this chapter.

The signer boundary is a build property

The research class holds no signing key. The whole design leans on that sentence, so it is enforced twice, by two independent mechanisms, because either alone is one edit away from being wrong.

The first is the process. The research class's environment does not contain the signing key, the signer's address, or any broker credential, and the signing class does not hold the broker's either. Each secret sits on the one service that uses it, and a deploy check prints, by name only, which watched secret each service holds and flags one that should not be there.

The second is the build. A test walks the import graph from the research class's entry module and asserts that it never reaches the signing modules, the hop, or the loop that operates. A module that cannot be imported cannot be called, however a future edit is written. The walker is guarded against passing vacuously: it asserts that it finds real direct and transitive edges, and a positive control walks from the live adapter and asserts that it does reach the signer, so the check cannot pass because the signing code was deleted.

supplies supplies never never Owner shell Live road Research class entry Front door listener Perception stream Shared verb module Execute road, declared Read-only road Signing module
The conversation declares the execute road it needs. Only the owner's shell supplies one that can reach the signer.

The verb module is signer-free by construction

The owner's conversation with the operator lives in one module that both transports call. The first version built the live execution path inline, so the moment the front door on the research class imported it, that class's graph reached the signer. Gating the hop at runtime would not have been the same property: a runtime check is one edit away from being wrong, while an absent module is not callable. So the dependency is inverted. The conversation declares the execution path it needs, and each transport supplies one. The owner's shell supplies the live path. The front door supplies a metered read path and no way to execute, and a request to open a position through it is refused by name.

The walk is enumerated, not listed

The test walks from the listener and from every module in the verbs directory, discovered from the filesystem. A hand-written list is the very defect a reachability check exists to catch. An earlier guard listed three command-line entry points and omitted the one that spends money, which was the one with the bug. A verb added tomorrow is walked without anyone remembering to add it.

The credential that signs

Perceiving the venue needs no key. The live credential is trade-only: its allowlist names the order actions and nothing else. Withdrawal and every transfer are absent and stay absent, and widening the allowlist is a visible commit. The one time it was widened, for order modification and the venue's time-weighted order, the allowlist refused the first live attempt during verification, which is the rail working.

Two identities stamp every hop. The workload identity names which instance is running and holds the trade-only credential. The principal identity names on whose behalf, and it is where account state is read, never from the signing key. One protection the venue offers turned out to be unavailable to the account below a threshold its documentation does not mention, so the service says on boot that the protection is absent rather than believing in a switch it does not have. A false belief in protection is worse than none, because it changes what an operator is willing to risk.

The broker class is fenced in both directions. A second test proves that the two original classes never import the broker's modules and that the broker service never imports the primary venue's signer or its hop. Its credential is sealed in a vault that only that service holds the key to. The other services share the database, so they can read the ciphertext and cannot use it.

Autonomy is a class

Human-in-the-loop is a class, not a default. Binary governance, either fully locked or simply trusted, is a failed design. There are four classes, and each selects which human step sits in front of the same gate. None deletes the gate.

A missing standing register fails closed to act with approval, and so does one that has expired. Neither invents a write. The two acting classes are two sequences in exact order: propose, confirm, type-gate, claim; or propose, standing, type-gate, claim. A hop that claims to be both standing and confirmed is refused, because an autonomous hop is not a second class with a confirmation attached. A hop that is neither is refused, because a hop requires the owner somewhere in front of it.

Act with approval Fresh confirm on this reviewable Act autonomous Standing grant: what may be open One register per put-on Type-gate Atomic claim Hop: one write Kill or expiry Halt new hops only
Every class meets the same gate. The class only decides which human step comes first.

The standing grant is a bucket

A register authorizes one hop, so at first every put-on from the phone needed a mint at the laptop, and the loop's own put-on was refused for want of one. The standing grant replaced that as the default: an expiring allowance in the owner's currency, minted once from the shell. Every live put-on draws on it inside the same Postgres transaction that takes its one-hop register.

It was first built on the pattern of a periodic spend permission: a sum of the day's draws that a close never gave back. The owner had meant something else, a bound on how much may be open at once. The two agree on a quiet day and diverge on a busy one. The console once showed less than a fifth of one percent of the grant left while about a third of it was actually open, and every entry was refused until midnight. Now each draw is weighted by how much of its position is still open, read from the venue's own fills, and a close gives its draw back. The first version of that count read the venue's fills in the wrong unit and would have read every open draw as whole. The read, run from the merged commit against production before the deploy, printed nearly the whole grant open beside about a third on the venue, and the deploy stopped.

Three bounds sit above the owner's taste. The venue bounds the expiry: a mint that would outlive the signing credential's own validity is refused with the date named, rather than clamped, because a grant that silently ended earlier than asked is a grant the owner did not mint. The owner's cap bounds the grant's figure, and no cap means no grant. The kill bounds the whole: the phone's kill suspends the grant, and only a resume from the shell lifts it. A principal holds one active grant, and replacing it never refills the bucket, because what is open is summed across every grant the principal has had.

The hop

A spend is a settlement hop. A signed mandate carries an intent, an amount cap, an expiry, and exact counterparties. A wildcard counterparty fails closed. A live mandate must deny withdrawal and name a live parent. Those invariants are also database constraints, written so that they cannot be satisfied by omission: Postgres passes a check that evaluates to NULL, and the original constraints accepted an empty counterparty list and a policy stamp with no mode, the very things they forbade. Each constraint is now proven by inserting the bad row.

The type-gate is synchronous and pure, and it reads no database. It checks that the mandate's intent matches the reviewable's, that the reviewable's intent matches the catalog entry for its plan, and that the plan is feasible on the very read the order is about to be priced from. Admission for a declared tenant reads the database, so it sits beside the gate and runs first; making a pure primitive asynchronous to suit a tenant concern would be backwards.

Plans are discrete and enumerable: a small, versioned catalog of resting orders, a flatten, and an unwind. A model selects among them; it does not compose an order. The catalog contains no market-order plan, and the gate refuses one by name. A time-weighted order is a way of rendering a size the book cannot take at once, not a plan, so the catalog's version does not move when one fires.

The owner's cap is checked twice. It is checked on the requested amount before the venue is read or the order sized, and again on size times order price inside the hop's own gate, because the order prices from its own read. The sizer leaves a small headroom under the cap, because the loop's first live execute job was refused by a single price tick against it. The headroom shaves the size; the cap never moves.

The root may decide that a spend happens. The type-gate, the claim, the envelope, the loss check, the ownership claim, and the owner's cap decide whether this hop is legal. The model does not size, does not set risk, and does not hold the kill.

Only the owner widens

The owner talks to the operator through three callers: the shell, a front door served by the research class, and the loop itself, which acts with no owner present. All three call one verb module, because two implementations of a verb would be two operators. Every row records which caller wrote it. A row written before that column existed carries a fourth value that no acting caller may write, rather than being credited to the shell, which would have credited the owner with the loop's own first autonomous execution.

Every caller may narrow. Kill and pause are open to all of them, because a kill that is hard to reach is not there when it is needed. So are disarm, veto, hold, close, reduce, and tighten. Only the owner's own shell may widen: write the cap, resume anything paused, mint or renew the grant, register a program, widen or rewrite an exit plan, lift a hold, run a probe that places on the venue. There are seventeen such actions, held in one list in the code with a call site for each entry. A route that is always a widen declares it, and the front door refuses it before reading the body, answering 403 with the action's name rather than 404, because a missing route says the operator has no such feature and the refusal says the truth.

The rule is "shell only", not "not web", so the autonomous loop is held to it too. A clock that could raise its own cap would have no cap.

Two entries need their reasoning. Any resume is a widen, not only the system-wide one: with the system resumed and one thesis paused by the owner, resuming that thesis lets the loop put it back on, and undoing an owner's pause is loosening a bound whatever its scope. And placing a hop immediately is gated on the route it would actually take, not on a confirmation flag, because a caller that merely omitted the flag would otherwise have reached the signing path ungated.

A put-on from the door is a proposal

A live put-on from the front door lands in a state no consumer claims until the owner approves it. The approval expires after an hour, checked in SQL rather than read and then written, because a put-on composed against a book that has moved carries a stale price. A kill refuses waiting rows too: an unapproved row cannot be claimed, but leaving it approvable would let the owner's own next approval place what the owner had killed. Approval is open to every caller, because it only moves a row from unclaimable to claimable inside bounds the owner already wrote, and every gate below it still stands.

So the most a leaked front-door token can do is enqueue one position inside a cap and a grant the owner already set, and a kill refuses even that. Every other write the token can reach makes the book smaller or stops something.

Every refusal is a structured client error that carries the bound by name, never a server error. A refusal is the system working, and rendering it as "the operator is down" would hide the bound at exactly the moment the owner most needs to read it. Writes through the door are limited to twelve a minute on a sliding window. The limit bounds a runaway retry, not cost, which the cap already bounds, and it is deliberately not configurable: an environment variable that can raise a bound is a bound the owner no longer owns.

The phone console is a second deployable of the same conversation. Its browser calls a server-only proxy on its own origin, which forwards an allowlist that excludes the cap and resume routes. No environment variable is visible to the client, and a preview deployment holds the staging door, so a preview cannot operate the real book. Admission is the hosting platform's own authentication. The platform documents no header a function could verify as proof that the viewer passed, so the proxy does not invent a second check, and the deploy proof is an unauthenticated request being refused.

The claim and recovery

A mandate allows one hop. The claim is a row whose primary key makes a double claim impossible rather than unlikely, and the cap falls to zero in the same transaction as the claim insert. Concurrent claimers serialize on a row lock: three simultaneous claimers produce exactly one winner. Redis sits in front for fast mutual exclusion, but it is not the guarantee. The primary key is, and a caller with no Redis still cannot claim twice.

A release must own the claim it releases. The claim row is deleted by its token first, and a release that deletes nothing refuses instead of restoring the cap. Restoring unconditionally was a hole: a stale or duplicated release would write the cap back while a newer claim held it, and once that claim settled, spent capacity stayed reopened.

A process can die while holding a claim, which would leave the cap at zero with nobody to settle or release it, so the claim carries an owner, a lease, a heartbeat, and an in-flight mark written before the order is placed. On boot, before any new work, a sweep decides each claim whose lease has lapsed. A claim whose lease is live is never touched.

In-flight markOutcome recordedActionWhy
AbsentReleaseNo hop started, so no order can exist
PresentYesSettleThe write landed and the cap is correctly spent
PresentNoSettle and open an incidentAn order may have reached the venue while the record died

The third row is the one that matters. Releasing there would restore the cap while a position may exist. The ambiguous case fails closed and hands the truth to reconciliation rather than guessing in favour of availability. The in-flight mark must precede the place; after it is too late. One helper is the only sanctioned way to hold a claim across work, and it finishes the claim exactly once even when the body throws. A throw settles, because a throw is when the system knows least about whether an order landed.

throws no place attempted Register, cap 1 Claim inserted, cap to 0, one transaction Heartbeat while working In-flight mark, before the place Venue write Settle: cap stays spent Release: cap restored, owner-checked
A claim is settled or released exactly once. A release restores the cap only for the claim it owns.

The release that killed its own exit

Once the standing grant existed, a put-on drew a one-hop register and an exit drew one at a cap of zero, because a close spends none of the allowance. The two shared one register row. The release rule had been written for the first kind: a released draw is killed, so its restored cap is never a live hop outside the grant. Run on the second kind, it killed the register that had opened the position.

On the day it happened, a reduce was refused before its hop by the operator's own venue request budget. The refusal released the exit claim, the release killed the register, and for two and a half hours every later exit on a live winner was refused with "a killed register does not close a position". The resting venue stop was the only exit left, and the position kept about a quarter of its peak gain.

Now one function decides the kill from the cap the release writes back, and both the live release and the boot recovery call it. The lesson generalizes. A helper written for one caller is a helper with an unstated precondition, and the second caller is where it is found. A refusal that arrives before the hop on an exit path is a release, and a release must leave the position every exit it had.

The same shape, one level up

An execution job is claimed by a single update that skips locked rows, so a second tick finds nothing. A job whose body throws is marked refused with the reason on its row, never left claimed. A job waiting for the owner's approval has a different status from a queued one, so it is invisible to the claim without the claim's predicate changing. The exactly-once claim stays one predicate that no consumer can forget.

The venue's request budget is one window shared by every reader on the account. A background reader that checked the window and then sent spent the budget a put-on needed, and a put-on was refused just past the window's ceiling. A reader off the order path now reserves its share of the window atomically, under a lower ceiling, and waits for the reset time the refusal carries rather than retrying on a fixed interval. A placeholder reservation once stayed beside the read that replaced it and double-charged about 45 percent of a day's research spend, so a reservation is now replaced under the same lock as the read that supersedes it.

None of this asks the model to be careful. The claim, the gate, and the class boundary hold whatever the model writes, and the record of every refusal says which bound held.