@byollm/relay 0.1.0-alpha.9 → 0.1.0-alpha.91

package/dist/store-BNhCedHZ.d.ts

@@ -0,0 +1,771 @@
+import { PublicIdentity, CapabilityMatrix, WithheldKind, JobStub, SealedEnvelope, ClaimedStub } from '@byollm/protocol';
+
+/**
+ * The relay's routing state — byollm_009 §7, reachable at last.
+ *
+ * §7 described a state machine the direct plane could not produce. There, the
+ * site and the upstream are the same party: it seals when it likes, and a job
+ * is never claimed-but-unsealed. Here they are different parties, and the gap
+ * between them is a state:
+ *
+ * ```
+ * queued ──claim──▶ awaiting-payload ──sealed──▶ ready ──fetch──▶ running
+ *    ▲                    │                                          │
+ *    └────────────────────┘                                          ▼
+ *      site never seals, or seals too late              ok | error | canceled
+ * ```
+ *
+ * The relay cannot seal, so it cannot shortcut this. A payload is encrypted
+ * to *the device that claimed it*, and nobody knows which device that is until
+ * the claim happens — which is precisely why claim-then-fetch makes a blind
+ * relay possible at all. The window is the price.
+ *
+ * ## What the relay holds, and what it cannot
+ *
+ * Stubs (metadata the site chose to publish), sealed envelopes it cannot open,
+ * and public keys. There is no field on any type in this file that could hold
+ * a private key or a plaintext, which is `RELAY_BLIND` expressed as a data
+ * model rather than as a policy.
+ */
+/** Where a routed job is. */
+type RoutedState = "queued" | "awaiting-payload" | "ready" | "running" | "done";
+/**
+ * How long a site has to seal after one of its jobs is claimed.
+ *
+ * **Distinct from the lease, and distinct from the job's TTL** — byollm_009
+ * §7.1. Three clocks, three different questions:
+ *
+ * - the **TTL** asks how long the work is worth doing at all;
+ * - the **lease** asks how long this device gets to run it;
+ * - this asks how long we wait for a site that has gone away.
+ *
+ * Collapsing any pair of them looks harmless until a site restarts during a
+ * deploy: with only a lease, the device sits politely holding a job whose
+ * payload will never arrive, and the lease's whole minute is spent waiting on
+ * a party that is not coming back. Short, because a site that is up answers in
+ * milliseconds and a site that is down will not answer sooner for waiting.
+ */
+declare const AWAITING_PAYLOAD_MS = 10000;
+/**
+ * How many devices wait for a payload before the hub gives up on the job —
+ * B042.
+ *
+ * Three, matching the daemon's own patience, and for the same reason: a site
+ * that is slow, restarting, or briefly unreachable deserves more than one
+ * chance, and a site that is gone should not cost the whole fleet a turn
+ * each. At {@link AWAITING_PAYLOAD_MS} apiece this is thirty seconds of
+ * waiting before a job that nobody can complete is dropped.
+ *
+ * Dropped rather than marked terminal, exactly as a passed deadline is: the
+ * relay is a router, the site holds the authoritative record, and a stub
+ * nobody may run is not routing state. A daemon mid-flight learns through
+ * `renewLeases`, which reports a job the store no longer holds as `lost`.
+ */
+/**
+ * How many grants one (site, owner) pair may hold UNSEALED at once — B187,
+ * ruled 09-16.
+ *
+ * A site must be told which device claimed its job, because it seals the
+ * payload to that device's public key — that is what lets a blind relay
+ * exist at all. **The leak is the ratio, not the key**: nothing required a
+ * site to complete a single job, so one that enqueued a thousand and sealed
+ * none read a thousand device identities inside one
+ * {@link AWAITING_PAYLOAD_MS} window.
+ *
+ * Keyed on the PAIR rather than on the site, and that is load-bearing twice
+ * over. A flat per-site cap would throttle a real product to two in-flight
+ * jobs across all its users. And the pair is already how consent is modelled
+ * here — `routeKey(siteId, owner)` — so the cap is bounded by the same unit
+ * the permission is.
+ *
+ * **It buys time, not secrecy.** Which device claims is deliberately random
+ * (B194: ties are luck), so a patient site still samples a small fleet over
+ * minutes. That is the point: minutes leave a signature, and
+ * {@link RelayStateOptions.onUnsealedChurn} is what reads it.
+ */
+declare const UNSEALED_PER_PAIR = 2;
+declare const SEAL_ATTEMPTS_BEFORE_EVICTION = 3;
+/** A job the relay is routing. Metadata and ciphertext, nothing else. */
+/** Why a daemon gave a job back. Only `refused` means "not me, ever". */
+type ReleaseReason = "shutdown" | "pause" | "revoked" | "backend-down" | "refused";
+interface RoutedJob {
+    readonly id: string;
+    /** Which site enqueued it — the party that will be asked to seal. */
+    readonly siteId: string;
+    /**
+     * Everything the relay knows about the work, which is everything the site
+     * chose to publish and not one field more (byollm_009 §6).
+     */
+    readonly stub: JobStub;
+    state: RoutedState;
+    /** Set from the claim; the site seals to these keys. */
+    claimedBy?: {
+        readonly runnerId: string;
+        readonly owner: string;
+        readonly device: PublicIdentity;
+        readonly leaseId: string;
+        readonly leaseExpiresAt: number;
+    };
+    /** When {@link AWAITING_PAYLOAD_MS} runs out for this claim. */
+    awaitingUntil?: number;
+    /**
+     * How many devices have waited for this payload and not received it — B042.
+     *
+     * A job whose site never seals is offered, waited on, requeued, and offered
+     * again — to a different device each time. Every one of them does the same
+     * ten seconds of nothing, and none of them can tell that the last one
+     * already tried: the daemon's own patience is per-device by construction,
+     * so the fleet works through itself one machine at a time until the job's
+     * deadline, which can be an hour away.
+     *
+     * That is the poison at its source. **The daemon-side breaker (B041) stops
+     * one device looping; only the hub can stop the job.** Counted here rather
+     * than inferred from `awaitingUntil`, because a requeue clears that clock
+     * and the count has to survive it.
+     */
+    sealAttempts?: number;
+    /**
+     * The device an ABANDONED grant goes back to — B187's sticky re-offer,
+     * ruled 09-16.
+     *
+     * Set when an unsealed grant lapses, not at claim: a job nobody abandoned
+     * is free work for whoever asks, and that is the routing this product
+     * wants. Once a site has taken a grant and let it rot, the job is offered
+     * only to the device that already answered for it.
+     *
+     * **This is what turns "slower and visible" into "closed".** The cap bounds
+     * the rate; the churn report makes a walk noticeable; this removes the walk
+     * itself, because abandoning the same job repeatedly now reveals ONE
+     * identity instead of a fresh sample each window.
+     *
+     * Survives `#requeue` for the same reason `sealAttempts` does — the requeue
+     * is the thing it has to outlive.
+     *
+     * **The accepted edge (Todd, 09-16): a device that never comes back takes
+     * the job with it.** It is still evicted after
+     * {@link SEAL_ATTEMPTS_BEFORE_EVICTION}, so the queue does not fill with
+     * work nobody can reach; the site simply has to enqueue it again.
+     */
+    reofferTo?: string;
+    /**
+     * Runners that released this job with reason `refused` — cloud_008 §2.1.
+     *
+     * `REFUSAL_NOT_REOFFERED`, which the relay did not implement: it dropped
+     * `ReleaseRequest.reason` on the floor. The field's own docstring says why
+     * that is not cosmetic — an upstream cannot evaluate a daemon's *local*
+     * `named` allowlist, so it may legitimately offer work the daemon then
+     * declines, and without a record the two spin between claim and release
+     * forever. The direct plane has always kept this list.
+     */
+    refusedBy: string[];
+    /**
+     * Runners that may not be offered this job again *yet*, and from when.
+     *
+     * The middle ground {@link RoutingStore.releaseLeases} had no way to say.
+     * `refusedBy` is forever and a bare release is immediate; a control plane
+     * declining a job for a reason the world can change — an unfilled mapping
+     * slot, a resolution that named another machine, a store that was briefly
+     * unreachable — means neither. It means "ask again later", and later needs
+     * a number.
+     *
+     * Keyed by runner because it is a fact about a pairing, not about the job:
+     * the same job goes to another device immediately, which is the whole
+     * point of not marking it refused.
+     */
+    retryAfter?: Record<string, number>;
+    /**
+     * The site withdrew this job — cloud_008 §2.2.
+     *
+     * A flag rather than a state, because a cancelled job that a device is
+     * *running* is not finished: the daemon has to be told, abort its backend
+     * call and report `canceled`, and the ordinary `complete` path then closes
+     * it. Making it a state would strand the in-flight case between two
+     * machines' ideas of what happened.
+     */
+    cancelled?: boolean;
+    /** Sealed to the claiming device by the site. Opaque here. */
+    payload?: SealedEnvelope;
+    /** Sealed to the site by the device. Opaque here. */
+    result?: SealedEnvelope;
+    /**
+     * The result's clear-text discriminator — byollm_009 §6.1.
+     *
+     * The one outcome fact the relay is given, and the reason it is given:
+     * without it the relay cannot stop dispatching a finished job. A routing
+     * hint and never a fact — the *site* verifies it against the sealed
+     * outcome, because only the site can open the envelope. The relay acts on
+     * it and is entitled to be wrong; a lying daemon costs it a dispatch
+     * decision, not a security property.
+     */
+    disposition?: "ok" | "error" | "canceled";
+}
+/** A device the relay has seen recently. */
+interface Presence {
+    readonly runnerId: string;
+    readonly owner: string;
+    readonly device: PublicIdentity;
+    lastSeenAt: number;
+    /**
+     * What this machine last said it can run — cloud_009, 2026-08-24.
+     *
+     * **Capabilities are presence data.** They arrive on the same heartbeat as
+     * everything else here, they go stale at the same moment and for the same
+     * reason, and a machine that stops heartbeating has not stopped being able
+     * to run Llama — it has stopped being somewhere we can ask. Keeping them
+     * anywhere else would put capability truth outside the interface that owns
+     * presence, and every next consumer (a member's usable set, a dashboard's
+     * pulse, a degraded-state banner) would re-derive it from a different
+     * place. That is the two-owners shape this codebase keeps paying for.
+     *
+     * Empty is a real answer, not a missing one: it is a paired machine with no
+     * healthy backend, which is a legal state the whole connect-first ruling
+     * exists to make visible rather than refuse.
+     */
+    capabilities: CapabilityMatrix;
+    /**
+     * Kinds this machine is deliberately *not* advertising — byollm_016.
+     *
+     * Presence data for the same reason capabilities are, and stored beside
+     * them rather than derived: two services answering one kind with no
+     * `defaults` entry is a state only the daemon can see, and the hub cannot
+     * reconstruct it from the matrix — an absent kind and a withheld kind look
+     * identical there. Without this field the owner's page can say "nothing
+     * serves llm.generate", which is true and useless, instead of "two services
+     * answer it and you have not chosen", which is the sentence that ends with
+     * the owner doing something.
+     *
+     * Empty is the normal answer, and means every kind resolved.
+     */
+    withheld: readonly WithheldKind[];
+}
+/**
+ * What a routing store must do, expressed as operations — cloud_006 §3.2.
+ *
+ * Every method below is a **decision plus its write**, never a read the caller
+ * follows with a mutation. That is the whole point, and it is the difference
+ * between an interface a shared store can implement and one it cannot.
+ *
+ * `claim` is the specimen. It used to live in `DaemonPlane` as
+ * `jobs()` → filter → mutate, which is atomic for exactly one reason: Node is
+ * single-threaded and these Maps are local, so nothing runs between the read
+ * and the write. Neither survives a store on a network, and
+ * `packages/relay/test/two-replicas.test.ts` holds the resulting race as a
+ * failing assertion.
+ *
+ * So the rule for anything added here: **if a caller has to read, decide, and
+ * write back, the operation is in the wrong place.** Move the decision in.
+ *
+ * ## Why the projection does not come with it
+ *
+ * `claim` takes `owners: string[]` rather than a projection or a predicate.
+ * A closure cannot travel to Valkey, and the projection replicates for free
+ * from the control plane — so the caller collapses it with
+ * `Projection.ownersRunnableBy` and hands over data the store can match on.
+ * That keeps the store ignorant of consent, which is also what keeps it
+ * replaceable.
+ */
+interface ClaimInput {
+    readonly runnerId: string;
+    readonly owner: string;
+    readonly device: PublicIdentity;
+    /**
+     * The (site, owner) pairs this device may run work for — cloud_009 §3.
+     *
+     * **One set of pairs, not a set of sites and a set of owners.** Consent
+     * binds a user to a site, so the two cannot travel separately: a device
+     * whose owner consented to site A, serving a roster member who consented
+     * to site B, would have every element of both sets and no consented route
+     * between them. Two sets multiply; consent does not.
+     *
+     * Built by {@link Projection.routesFor} and matched with {@link routeKey},
+     * so the relay and a store in another repository agree on the encoding by
+     * calling the same function rather than by both spelling it out.
+     *
+     * This is the collapse that lets a claim stay one operation: a predicate
+     * cannot travel to a store over a network, and a set can.
+     */
+    readonly routes: ReadonlySet<string>;
+    /**
+     * Kinds this device can run — and that is now the whole of the match.
+     *
+     * A relay routes by kind and by consent; **which service answers is not its
+     * question**. A job names a purpose, a person's mapping names a service,
+     * and a control plane joins them at claim. A relay that filtered on the
+     * service would need the mapping, which is the one thing it is not supposed
+     * to hold.
+     *
+     * This carried a companion, `serves`, holding the (kind, service) pairs a
+     * device advertised, so a job naming a service reached only a device with
+     * it. Sites stopped naming services (Amendment L) and the field became wire
+     * nothing read — so it is gone rather than left for a reader to infer
+     * meaning from.
+     *
+     * The cost is stated plainly: a job may be offered to a device whose owner
+     * admits the person but whose machine their mapping did not name. The
+     * control plane declines it as not-here and it goes back with a
+     * {@link RETRY_AFTER_MS} wait, which is what that mechanism is for.
+     */
+    readonly kinds: ReadonlySet<string>;
+    readonly max: number;
+    readonly leaseMs: number;
+}
+/**
+ * How a (site, owner) route is written, so two implementations agree.
+ *
+ * The same `\u0000` the job key uses, for the same reason: it cannot appear
+ * in a site id or an owner id, so this is a key rather than a parser.
+ */
+declare const routeKey: (siteId: string, owner: string) => string;
+/**
+ * Where the store's sense of time comes from — cloud_006 §3.4.
+ *
+ * **The store owns its clock; callers do not pass one.** Every deadline the
+ * relay decides — a lease's expiry, the `awaiting-payload` window, what a
+ * sweep considers due — is now stamped by one source, and it is the same
+ * source that will later stamp them for every replica.
+ *
+ * It used to be a parameter. `claim` took `now`, `sweep` took `now`, and each
+ * plane called its own `now()` before calling in — which is fine in one
+ * process and is the recurring bug the moment there are two. A lease granted
+ * by a pod whose clock runs fast is short; the same lease swept by a pod whose
+ * clock runs slow outlives it. Nobody is wrong and the lease has no length.
+ *
+ * A Valkey-backed store returns `TIME` here, so the deadline and the sweep
+ * that enforces it are read from the same server. The injected clock stays for
+ * tests, which is what lets them move time instead of sleeping.
+ *
+ * **What deliberately does not use this**: request-signature freshness. That
+ * is checked against the *local* clock on purpose — it is a question about the
+ * caller's clock versus this process's, `MAX_CLOCK_SKEW_MS` already tolerates
+ * two minutes of disagreement, and a network round trip to timestamp every
+ * inbound request would be a cost with no property behind it.
+ */
+/**
+ * How often a pair may burn unsealed grants before it is worth a human's
+ * attention — B187's other half, ruled 09-16.
+ *
+ * **The cap buys time; it does not buy secrecy.** Which device claims is
+ * deliberately random (B194: ties are luck), so a patient site still samples a
+ * small fleet over minutes. You cannot cap your way out of a slow walk — but
+ * you can notice one, and this is the shape to notice: **an honest site never
+ * gets here at all**, because it seals in about a round trip and the grant
+ * never reaches {@link AWAITING_PAYLOAD_MS}.
+ *
+ * Six in five minutes is comfortably above the noise a flaky network makes and
+ * far below what a walk produces — a pair burning its {@link
+ * UNSEALED_PER_PAIR} slots every ten seconds passes this inside a minute.
+ */
+declare const CHURN_EXPIRIES = 6;
+declare const CHURN_WINDOW_MS: number;
+/** One report per pair per hour. An alert that repeats is an alert nobody reads. */
+declare const CHURN_QUIET_MS: number;
+/** A pair burning grants without sealing them — B187. */
+interface UnsealedChurn {
+    readonly siteId: string;
+    readonly owner: string;
+    /** How many unsealed grants expired inside the window. */
+    readonly expiries: number;
+    readonly windowMs: number;
+}
+interface RelayStateOptions {
+    readonly now?: () => number | Promise<number>;
+    /**
+     * Told when a pair keeps claiming and not sealing — B187.
+     *
+     * A callback rather than an email, because this package is the open-source
+     * relay: where a report GOES is a deployment's business, and `support@` is
+     * one deployment's address. The hub wires this to mail; a self-hoster wires
+     * it to whatever they read.
+     *
+     * Deliberately minimal — scaffolding until the signal system replaces it.
+     */
+    readonly onUnsealedChurn?: (churn: UnsealedChurn) => void;
+}
+/** Why a lease-scoped operation was refused, in the caller's vocabulary. */
+type HolderRefusal = "not-found" | "not-holder" | "stale-lease" | "not-ready"
+/** The job already ended — V1-6. A replay must not reopen it. */
+ | "terminal";
+declare class RelayState implements RoutingStore {
+    #private;
+    constructor(options?: RelayStateOptions);
+    /** The one clock every deadline in this store is stamped from. */
+    now(): Promise<number>;
+    /**
+     * Take a stub for routing. The payload is not here and will not be.
+     *
+     * **Idempotent by job id, and that is a security property rather than a
+     * convenience.** Site-plane calls are authenticated by signature, and
+     * byollm_009 §4.2's argument for signing the request instead of a
+     * server-issued nonce rests entirely on every write being idempotent per the
+     * instance it names. This one was not: re-enqueueing a known id built a
+     * fresh `queued` job over the top of the old one, discarding a live claim,
+     * its lease and any payload the site had already sealed to a device. A
+     * replayed enqueue inside the two-minute freshness window was therefore a
+     * way to yank a job back from the machine running it — the `release` bug of
+     * §4.2, rediscovered on the other plane.
+     *
+     * So a known id returns what is already routing, unchanged. A site that
+     * restarts and republishes its queue is the normal case, and it must not
+     * disturb work in flight.
+     */
+    enqueue(input: {
+        id: string;
+        siteId: string;
+        stub: JobStub;
+    }): Promise<RoutedJob>;
+    job(siteId: string, jobId: string): Promise<RoutedJob | undefined>;
+    jobs(): Promise<RoutedJob[]>;
+    /** Jobs a site must seal for, right now. */
+    awaiting(siteId: string): Promise<RoutedJob[]>;
+    /** Sealed results waiting to go home. */
+    finished(siteId: string): Promise<RoutedJob[]>;
+    /**
+     * Claim work — one operation, because it has to be.
+     *
+     * Moved here wholesale from `DaemonPlane`, where it was a scan followed by
+     * per-job mutation. Nothing about the *decision* changed; what changed is
+     * that a store can now implement it, because the filter and the write are
+     * one call rather than a loop the caller drives.
+     *
+     * The order of the guards is worth preserving as-is when this becomes a Lua
+     * script: cheapest first, and `owners` last because it is the only one that
+     * needed the projection.
+     */
+    claim(input: ClaimInput): Promise<ClaimedStub[]>;
+    /**
+     * Hand over the sealed payload to the device that holds the lease.
+     *
+     * The read and the state transition are one operation for the same reason
+     * `claim` is: `running` must be set by whoever was told the envelope, or two
+     * replicas can both hand out the same work and both believe they were first.
+     */
+    takePayload(input: {
+        jobId: string;
+        runnerId: string;
+        leaseId: string;
+    }): Promise<{
+        envelope: SealedEnvelope;
+    } | {
+        refused: HolderRefusal;
+    }>;
+    /**
+     * Record a finished job.
+     *
+     * `RESULT_IDEMPOTENT` lives here rather than in the caller: a replayed
+     * result must be a no-op decided by the same operation that would have
+     * written it, or two replicas can both decide they were the first.
+     */
+    complete(input: {
+        jobId: string;
+        runnerId: string;
+        leaseId: string;
+        envelope: SealedEnvelope;
+        disposition: "ok" | "error" | "canceled";
+    }): Promise<{
+        accepted: boolean;
+        duplicate?: boolean;
+        state: RoutedState;
+    } | {
+        refused: HolderRefusal;
+    }>;
+    /** Give back leases this runner holds, naming each grant it means. */
+    releaseLeases(input: {
+        runnerId: string;
+        leases: readonly {
+            jobId: string;
+            leaseId: string;
+        }[];
+        reason?: ReleaseReason;
+        retryAfter?: number;
+    }): Promise<string[]>;
+    /**
+     * Take a site's sealed payload for a claimed job.
+     *
+     * Refuses anything not `awaiting-payload`, which is what makes the timeout
+     * mean something: a late seal must not land on a claim that has moved.
+     */
+    seal(input: {
+        jobId: string;
+        siteId: string;
+        envelope: SealedEnvelope;
+    }): Promise<{
+        state: RoutedState;
+    } | {
+        refused: "not-found" | "too-late";
+        was?: RoutedState;
+    }>;
+    /** {@link RoutingStore.cancel} — the site withdraws a job. */
+    cancel(input: {
+        jobId: string;
+        siteId: string;
+    }): Promise<boolean>;
+    /** {@link RoutingStore.cancelRequests} — cancelled jobs this runner holds. */
+    cancelRequests(runnerId: string): Promise<Grant[]>;
+    /** {@link RoutingStore.renewLeases} — extend what is still held, name what is not. */
+    renewLeases(input: {
+        runnerId: string;
+        leases: readonly {
+            jobId: string;
+            leaseId: string;
+        }[];
+        leaseMs: number;
+    }): Promise<{
+        renewed: {
+            jobId: string;
+            expiresAt: number;
+        }[];
+        lost: Grant[];
+    }>;
+    seen(presence: Omit<Presence, "lastSeenAt">): Promise<Presence>;
+    presence(runnerId: string): Promise<Presence | undefined>;
+    /**
+     * Lose a record, the way a real store does.
+     *
+     * A shared store drops presence for reasons this one never will — a TTL, a
+     * reschedule, a restart — and the interesting behaviour is what the relay
+     * does next. `ValkeyRoutingStore` has carried the same helper since
+     * finding 52; this is its memory twin, so the case can be written once
+     * against the implementation that is easy to reason about.
+     */
+    dropPresenceForTests(runnerId: string): Promise<void>;
+    everyone(): Promise<Presence[]>;
+    /**
+     * Fire whatever the clock says is due, and report it.
+     *
+     * Returns the jobs it requeued so a caller can log or surface them — a
+     * timeout that fires invisibly is indistinguishable from a job that was
+     * never claimed, and those want very different debugging.
+     */
+    sweep(): Promise<RoutedJob[]>;
+}
+
+/**
+ * What the relay needs from a place to keep routing state — cloud_006 §3.2.
+ *
+ * `RelayState` implements this in memory and is the reference; a Valkey-backed
+ * store implements the same thing across replicas. The interface exists so the
+ * relay depends on the *contract* rather than on either, and so the properties
+ * below are stated once rather than rediscovered per implementation.
+ *
+ * ## Every method is a decision plus its write
+ *
+ * Not one is a read the caller follows with a mutation. That is the whole
+ * design, and it is not a style preference: `claim` used to be
+ * `jobs()` → filter → mutate in the plane, which is atomic for exactly one
+ * reason — Node is single-threaded and the Maps are local. Neither survives a
+ * store on a network, and `packages/relay/test/two-replicas.test.ts` holds the
+ * resulting race as a failing assertion.
+ *
+ * **The rule for anything added here:** if a caller has to read, decide, and
+ * write back, the operation is in the wrong place. Move the decision in.
+ *
+ * ## What an implementation must guarantee
+ *
+ * 1. **`claim` is atomic.** Two callers claiming concurrently must not both
+ *    receive the same job. `CLAIM_ATOMIC` is a protocol MUST.
+ * 2. **`enqueue` is idempotent by job id.** A known id returns what is already
+ *    routing rather than rebuilding it — byollm_009 §4.2's replay argument
+ *    rests on every write being idempotent per the instance it names.
+ * 3. **`complete` is idempotent.** A replayed result changes nothing, and the
+ *    decision is made by the same operation that would have written it.
+ * 4. **Lease-scoped operations name the grant.** `takePayload`, `complete` and
+ *    `releaseLeases` check the lease *id*, not just the runner — a runner
+ *    survives a claim-release-reclaim cycle and a grant does not.
+ * 5. **`now()` is the only clock.** Every deadline the store stamps and every
+ *    deadline it enforces come from here (§3.4). An implementation backed by a
+ *    server returns that server's time, so two replicas cannot disagree about
+ *    how long a lease is.
+ *
+ * ## What it must not do
+ *
+ * Hold a key, or learn about consent. `claim` takes `owners` as data because a
+ * predicate cannot travel to Valkey — and the effect is that the store cannot
+ * express an opinion about who may route, only about what it was told. That is
+ * what keeps `RELAY_BLIND` a property of the shape rather than of the code.
+ */
+/**
+ * One grant, named by both halves — V1-3.
+ *
+ * A job id is chosen per site, so two sites can pick the same one; the lease
+ * id is the unique thing an upstream and a daemon can both point at. Anywhere
+ * this store says "this piece of work, held by you", it says it with both.
+ */
+interface Grant {
+    readonly jobId: string;
+    readonly leaseId: string;
+}
+interface RoutingStore {
+    /** The one clock every deadline in this store is stamped from. */
+    now(): Promise<number>;
+    /**
+     * Take a stub for routing. Idempotent by id, **within a site**.
+     *
+     * A republished id belonging to the same site returns what is already
+     * routing, unchanged: a site that restarts and republishes its queue must
+     * not disturb work in flight (byollm_009 §4.2's replay argument rests on
+     * it).
+     *
+     * A republished id belonging to a **different** site is a different job —
+     * cloud_009 §3. Keys are `(site, id)`, so two sites choosing one id collide
+     * nowhere and there is nothing to refuse.
+     *
+     * cloud_008 finding 58 closed this by refusing the collision, which was as
+     * far as a single-site relay could go and left a cross-tenant existence
+     * oracle: a site knows its own stub is well-formed, so any answer it can
+     * tell apart from success confirms that somebody else holds that id. The
+     * refusal is gone with the collision.
+     */
+    enqueue(input: {
+        id: string;
+        siteId: string;
+        stub: JobStub;
+    }): Promise<RoutedJob>;
+    /**
+     * One job, named by the site that published it — cloud_009 §3.
+     *
+     * The site id is a parameter rather than a scan, and the difference is
+     * finding eleven wearing a different hat: a reader that finds a job by id
+     * alone is a reader that can see every tenant's state through one door,
+     * which is exactly the anonymous read the debug page had and lost. The
+     * debug page is per-site or it is nothing.
+     */
+    job(siteId: string, jobId: string): Promise<RoutedJob | undefined>;
+    jobs(): Promise<RoutedJob[]>;
+    /** Jobs a site must seal for, right now. */
+    awaiting(siteId: string): Promise<RoutedJob[]>;
+    /** Sealed results waiting to go home. */
+    finished(siteId: string): Promise<RoutedJob[]>;
+    /** Grant work to a device — one operation, because it has to be. */
+    claim(input: ClaimInput): Promise<ClaimedStub[]>;
+    /** Hand the sealed payload to the device that holds the lease. */
+    takePayload(input: {
+        jobId: string;
+        runnerId: string;
+        leaseId: string;
+    }): Promise<{
+        envelope: SealedEnvelope;
+    } | {
+        refused: HolderRefusal;
+    }>;
+    /** Record a finished job. Idempotent. */
+    complete(input: {
+        jobId: string;
+        runnerId: string;
+        /**
+         * The grant the result was produced under — cloud_008 §1.4a.
+         *
+         * `takePayload` and `releaseLeases` have always checked this and said why;
+         * the operation that *writes* checked only the runner, which survives a
+         * claim-release-reclaim cycle.
+         */
+        leaseId: string;
+        envelope: SealedEnvelope;
+        disposition: "ok" | "error" | "canceled";
+    }): Promise<{
+        accepted: boolean;
+        duplicate?: boolean;
+        state: RoutedState;
+    } | {
+        refused: HolderRefusal;
+    }>;
+    /** Give back the grants this runner names. */
+    releaseLeases(input: {
+        runnerId: string;
+        leases: readonly {
+            jobId: string;
+            leaseId: string;
+        }[];
+        /**
+         * Why — cloud_008 §2.1. `refused` MUST be remembered and that job MUST
+         * NOT be offered to that runner again (`REFUSAL_NOT_REOFFERED`); every
+         * other reason means "not now" and must leave the job claimable by the
+         * same device, or a restart would strand its own work.
+         */
+        reason?: ReleaseReason;
+        /**
+         * Epoch ms before which this job MUST NOT be offered to this runner
+         * again — the rate a transient refusal needs.
+         *
+         * "Not now" and "not ever" were the only two things a release could say,
+         * and a control plane declining a job for something the world can change
+         * means neither. Left immediate, the device re-claims at once and is
+         * declined again: a spin, and in a deployment one database read per turn
+         * of it.
+         *
+         * A store MUST NOT offer the job to that runner before this moment, and
+         * MUST go on offering it to every other device immediately — the whole
+         * reason it is not a refusal is that another machine may be the right
+         * one.
+         */
+        retryAfter?: number;
+    }): Promise<string[]>;
+    /** Take a site's sealed payload for a claimed job. */
+    seal(input: {
+        jobId: string;
+        siteId: string;
+        envelope: SealedEnvelope;
+    }): Promise<{
+        state: RoutedState;
+    } | {
+        refused: "not-found" | "too-late";
+        was?: RoutedState;
+    }>;
+    /**
+     * Extend the leases this runner still holds, and name the ones it does not.
+     *
+     * One call because it is one question — cloud_008 §0.6. This was
+     * `lostLeases`, which answered only the second half, and the relay's
+     * heartbeat answered the first half with the literal `leases: []`. A daemon
+     * was therefore told, every few seconds, that none of its work had been
+     * renewed; the sweep requeued at `leaseMs` regardless of how alive the
+     * device was, and any job that took longer than a lease was handed to
+     * somebody else while the first device was still running it. The direct
+     * plane has always renewed here (`handlers.ts` §3), so this was also the two
+     * upstreams disagreeing about a rule the daemon cannot see.
+     *
+     * Renewal and loss come from one read of one state: asked separately they
+     * are two answers to "who holds this now", and under two replicas they can
+     * differ.
+     */
+    renewLeases(input: {
+        runnerId: string;
+        leases: readonly {
+            jobId: string;
+            leaseId: string;
+        }[];
+        leaseMs: number;
+    }): Promise<{
+        renewed: readonly {
+            jobId: string;
+            expiresAt: number;
+        }[];
+        lost: readonly Grant[];
+    }>;
+    /**
+     * The site withdraws a job — cloud_008 §2.2.
+     *
+     * Returns false when the job is not this site's, which is the same scoping
+     * every other site-plane operation carries: a site must not cancel
+     * somebody else's work by guessing an id.
+     */
+    cancel(input: {
+        jobId: string;
+        siteId: string;
+    }): Promise<boolean>;
+    /**
+     * Cancelled jobs this runner is holding, for the heartbeat to report.
+     *
+     * The relay answered `cancel: []` unconditionally, so a site could not stop
+     * a job it had already withdrawn — a device went on running work whose
+     * result nobody would accept, on somebody's own machine, at their expense.
+     */
+    cancelRequests(runnerId: string): Promise<Grant[]>;
+    /** Record a device as present. The store stamps when. */
+    seen(presence: Omit<Presence, "lastSeenAt">): Promise<Presence>;
+    presence(runnerId: string): Promise<Presence | undefined>;
+    everyone(): Promise<Presence[]>;
+    /** Fire whatever the clock says is due, and report it. */
+    sweep(): Promise<RoutedJob[]>;
+}
+
+export { AWAITING_PAYLOAD_MS as A, CHURN_EXPIRIES as C, type Grant as G, type HolderRefusal as H, type Presence as P, type RoutingStore as R, SEAL_ATTEMPTS_BEFORE_EVICTION as S, type UnsealedChurn as U, CHURN_QUIET_MS as a, CHURN_WINDOW_MS as b, type ClaimInput as c, RelayState as d, type ReleaseReason as e, type RoutedJob as f, type RoutedState as g, UNSEALED_PER_PAIR as h, routeKey as r };