@byollm/relay 0.1.0-alpha.7 → 0.1.0-alpha.71

package/dist/store-DPCLO12l.d.ts

@@ -0,0 +1,655 @@
+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;
+/** 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;
+    /**
+     * 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.
+ */
+interface RelayStateOptions {
+    readonly now?: () => number | Promise<number>;
+}
+/** 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, type ClaimInput as C, type Grant as G, type HolderRefusal as H, type Presence as P, type RoutingStore as R, RelayState as a, type ReleaseReason as b, type RoutedJob as c, type RoutedState as d, routeKey as r };