@byollm/relay 0.1.0-alpha.5 → 0.1.0-alpha.50

package/dist/index.d.ts

@@ -1,143 +1,21 @@
-import { PublicIdentity, JobStub, SealedEnvelope } from '@byollm/protocol';
+import { R as RoutingStore } from './store-C7jG6b9m.js';
+export { A as AWAITING_PAYLOAD_MS, C as ClaimInput, G as Grant, H as HolderRefusal, P as Presence, a as RelayState, b as ReleaseReason, c as RoutedJob, d as RoutedState, r as routeKey } from './store-C7jG6b9m.js';
 import { z } from 'zod';
+import { PublicIdentity, CapabilityMatrix } from '@byollm/protocol';
 
+declare function debugPage(state: RoutingStore, now: number, 
 /**
- * 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. */
-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;
-    /** 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;
-    /** Set on revocation so the next request is refused rather than routed. */
-    revoked: boolean;
-}
-/**
- * In-memory routing state.
+ * Asked whether each device's owner still consents — cloud_008 §2.3.
  *
- * Deliberately not durable. The skeleton proves the protocol, and the
- * production hub replaces this with the closed multi-tenant router behind the
- * same shape (cloud_004 §9). Anything a restart loses here is a job that
- * returns to its site's queue — which is the behaviour a lapsed lease already
- * has to produce, so nothing new needs to be true for this to be safe.
+ * The page used to read a `revoked` boolean off presence. That flag was a
+ * stored copy of a fact the projection owns, and it is gone; the page asks
+ * the authority instead, which is also the only thing that stays correct
+ * when one daemon serves several sites.
  */
-declare class RelayState {
-    #private;
-    /** Take a stub for routing. The payload is not here and will not be. */
-    enqueue(input: {
-        id: string;
-        siteId: string;
-        stub: JobStub;
-    }): RoutedJob;
-    job(jobId: string): RoutedJob | undefined;
-    jobs(): RoutedJob[];
-    /** Jobs a site must seal for, right now. */
-    awaiting(siteId: string): RoutedJob[];
-    /** Sealed results waiting to go home. */
-    finished(siteId: string): RoutedJob[];
-    seen(presence: Omit<Presence, "revoked">): Presence;
-    presence(runnerId: string): Presence | undefined;
-    everyone(): Presence[];
-    /**
-     * Return a job to the queue, forgetting the claim.
-     *
-     * The stub survives; nothing is lost. That is `LEASE_RECLAIMABLE` and it is
-     * why the awaiting-payload timeout is cheap to fire: the worst case is that
-     * a device did nothing for ten seconds and another one gets a turn.
-     */
-    requeue(job: RoutedJob): void;
-    /**
-     * 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(now: number): RoutedJob[];
-}
-
-declare function debugPage(state: RelayState, now: number): string;
+routesFor?: {
+    siteId: string;
+    consents: (owner: string) => boolean;
+}): Promise<string>;
 
 /**
  * What the relay is told about the world — cloud_004 §14.
@@ -171,6 +49,42 @@ declare function debugPage(state: RelayState, now: number): string;
  * can open anything, and {@link RelayFixture} has no field where one could be
  * put — `RELAY_BLIND` as a type, not as a promise.
  */
+/**
+ * A site the control plane registered and domain-verified — cloud_004 §5.
+ *
+ * **The one authority for a site's public identity.** It used to be inlined on
+ * every consent record, which meant a site's key had as many homes as it had
+ * users and nothing checked they agreed — the exact shape this project has now
+ * found in a version constant, a clock read, an envelope deadline, a reseal
+ * implementation, a package list and a docs page. Consents now reference a
+ * site by id and the key is looked up here.
+ *
+ * The relay needs it for two things it cannot do without:
+ *
+ * 1. **Telling a daemon who to pin** at pairing — the key that makes relayed
+ *    work unforgeable, since the relay holds no key that could produce it.
+ * 2. **Authenticating the site plane.** A site calls a relay the way a daemon
+ *    does, signing with this identity, and this is the key those signatures
+ *    are checked against.
+ */
+declare const SiteRecord: z.ZodObject<{
+    siteId: z.ZodString;
+    site: z.ZodObject<{
+        identity: z.ZodString;
+        encryption: z.ZodString;
+        encryptionSig: z.ZodString;
+    }, z.core.$strict>;
+    succeeds: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        identity: z.ZodObject<{
+            identity: z.ZodString;
+            encryption: z.ZodString;
+            encryptionSig: z.ZodString;
+        }, z.core.$strict>;
+        signature: z.ZodString;
+    }, z.core.$strict>>>;
+    retiringUntil: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+type SiteRecord = z.infer<typeof SiteRecord>;
 /**
  * A user's decision to let one site use their compute — cloud_004 §3.
  *
@@ -181,11 +95,7 @@ declare function debugPage(state: RelayState, now: number): string;
 declare const ConsentRecord: z.ZodObject<{
     owner: z.ZodString;
     siteId: z.ZodString;
-    site: z.ZodObject<{
-        identity: z.ZodString;
-        encryption: z.ZodString;
-        encryptionSig: z.ZodString;
-    }, z.core.$strict>;
+    paused: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>;
 type ConsentRecord = z.infer<typeof ConsentRecord>;
 /**
@@ -202,22 +112,75 @@ declare const RosterRecord: z.ZodObject<{
     members: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
 type RosterRecord = z.infer<typeof RosterRecord>;
+/**
+ * A device its owner has approved — cloud_005 §7.1.
+ *
+ * The relay refuses a device that is not here, and that refusal is the point.
+ * byollm_009's seventh finding stopped a daemon from *naming* itself; this
+ * stops it from *keying* itself. A device that presents keys nobody approved
+ * is a device whose owner never saw a fingerprint, and pairing it would make
+ * the relay the authority on identity — which is exactly what it must not be.
+ *
+ * The three-party shape consent already has, applied to identity: the device
+ * asserts, a human confirms in the control plane, the relay checks.
+ */
+declare const DeviceRecord: z.ZodObject<{
+    owner: z.ZodString;
+    runnerId: z.ZodString;
+    device: z.ZodObject<{
+        identity: z.ZodString;
+        encryption: z.ZodString;
+        encryptionSig: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+type DeviceRecord = z.infer<typeof DeviceRecord>;
+/** A revoked route, named by its parts. */
+declare const RevocationRecord: z.ZodObject<{
+    owner: z.ZodString;
+    siteId: z.ZodString;
+}, z.core.$strict>;
+type RevocationRecord = z.infer<typeof RevocationRecord>;
 declare const RelayFixture: z.ZodObject<{
-    consents: z.ZodArray<z.ZodObject<{
-        owner: z.ZodString;
+    sites: z.ZodDefault<z.ZodArray<z.ZodObject<{
         siteId: z.ZodString;
         site: z.ZodObject<{
             identity: z.ZodString;
             encryption: z.ZodString;
             encryptionSig: z.ZodString;
         }, z.core.$strict>;
+        succeeds: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            identity: z.ZodObject<{
+                identity: z.ZodString;
+                encryption: z.ZodString;
+                encryptionSig: z.ZodString;
+            }, z.core.$strict>;
+            signature: z.ZodString;
+        }, z.core.$strict>>>;
+        retiringUntil: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    consents: z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        siteId: z.ZodString;
+        paused: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
+    devices: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        runnerId: z.ZodString;
+        device: z.ZodObject<{
+            identity: z.ZodString;
+            encryption: z.ZodString;
+            encryptionSig: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>>;
     rosters: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         owner: z.ZodString;
         members: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>>;
-    revoked: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    revoked: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        siteId: z.ZodString;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;
 type RelayFixture = z.infer<typeof RelayFixture>;
 /** An empty projection: nothing consented, so nothing routes. */
@@ -235,8 +198,138 @@ declare class Projection {
     constructor(fixture?: RelayFixture);
     /** Replace the projection wholesale — the control plane pushed a new one. */
     replace(fixture: RelayFixture): void;
-    /** The consent binding this owner to this site, if it exists and stands. */
+    /**
+     * The site this id names, if the control plane registered it.
+     *
+     * The only source of a site's public identity in this package. Everything
+     * that pins, verifies or seals to a site starts here.
+     */
+    siteFor(siteId: string): SiteRecord | null;
+    /**
+     * The device this runner id names, if a human approved it.
+     *
+     * Returns null for a device the control plane does not know, which is how
+     * the relay refuses to be the authority on identity.
+     */
+    deviceFor(runnerId: string): DeviceRecord | null;
+    /** The device approved for these exact keys, if any. */
+    deviceByFingerprint(identityPublic: string): DeviceRecord | null;
+    /**
+     * The consent binding this owner to this site, if it exists and stands.
+     *
+     * **Liveness, not routing.** A paused consent is returned here: the
+     * relationship exists, the daemon is not revoked, the pairing stands. Ask
+     * {@link Projection.mayRouteFor} before moving anybody's work — the two
+     * questions have different answers and one method answering both is how a
+     * paused user would quietly start routing again.
+     */
     consentFor(owner: string, siteId: string): ConsentRecord | null;
+    /**
+     * Every site this owner may route with — cloud_009 §3.
+     *
+     * The set a pairing covers, and the set a claim will filter on. Consent
+     * decides it, which is the sentence the whole design rests on: a site
+     * appears here because a human clicked, never because a site asked to be
+     * here and never because a daemon named it.
+     *
+     * **Paused sites are here, and that is deliberate** — cloud_008 finding 48
+     * as ratified. A paused consent routes nothing and keeps its pin: the
+     * relationship stands, the key the daemon compared a fingerprint of stays
+     * pinned, and re-consenting never costs a re-pair. Written the other way
+     * round first, and three of the paused tests failed by refusing to pair at
+     * all — which is the trap the finding is about, arriving through the door
+     * marked "be stricter".
+     *
+     * So this is the *pairing* set and `mayRouteFor` is the *routing* set. Two
+     * questions with different answers, kept apart for the same reason
+     * `consentFor` and `mayRouteFor` are: one method answering both is how a
+     * paused user quietly starts routing again, or quietly loses their machine.
+     *
+     * Sorted by site id so two calls with the same projection produce the same
+     * answer: this ends up in a pairings file and in a fingerprint list a human
+     * compares by eye, and an order that drifts between polls is a diff nobody
+     * can read.
+     */
+    sitesFor(owner: string): SiteRecord[];
+    /**
+     * May this owner's work move for this site, right now?
+     *
+     * Consent exists, was not revoked, and is not paused. The routing question,
+     * kept apart from {@link Projection.consentFor}'s liveness one so that a
+     * caller has to pick which it means.
+     */
+    mayRouteFor(owner: string, siteId: string): boolean;
+    /**
+     * Has this owner's relationship *ended* — V1-2?
+     *
+     * Not "is there nothing to serve". Those were one question until the pre-v1
+     * review pulled them apart, and the difference is a machine's pinned keys:
+     * an empty answer made the daemon stop, cancel everything and **delete its
+     * pairings file**, so a projection that arrived empty or half-written — one
+     * bad control-plane push — cost every daemon its pins and every user a
+     * re-pair they never asked for.
+     *
+     * Revocation is a thing somebody did, and this asks for the evidence of it:
+     * a revocation record for this owner, and nothing left standing. A
+     * projection that simply knows nothing says nothing — the relay answers
+     * normally, the daemon serves nobody, and the pairing survives to be
+     * correct again when the next push lands.
+     *
+     * The `revoked` list exists precisely for this and was consulted by
+     * nothing. Its own doc said why: "the row is gone" and "the row was
+     * revoked" are different answers, and only one of them is a decision.
+     */
+    revokedOutright(owner: string): boolean;
+    /** Whether this pair is consented and paused — what heartbeat reports. */
+    pausedFor(owner: string, siteId: string): boolean;
+    /**
+     * Every (site, owner) route this device may run — cloud_009 §3.
+     *
+     * The claim filter, collapsed to data a store can match on. `routableOwners`
+     * was this for one site; the hub needs it for the set, and the shape had to
+     * change rather than repeat, because **a set of sites and a set of owners
+     * multiply**. A device whose owner consented to site A, serving a roster
+     * member who consented to site B, appears in both sets and has no consented
+     * route between them. Pairs cannot express a route nobody agreed to.
+     *
+     * Both halves of the rule are here, and neither was enforced before finding
+     * 48's work:
+     *
+     * - **This machine's owner** must have a live consent for the site, or
+     *   nothing of that site's runs here at all — including a roster member's
+     *   work. The roster says whose jobs may land on this machine; consent says
+     *   whether this machine is available to that site.
+     * - **Each job's owner** must have one too. That check did not exist:
+     *   consent was enforced by the daemon plane's blanket revoked guard, which
+     *   asks only about the claiming device's owner, so a roster member who
+     *   never consented to a site could have their work claimed by their admin's
+     *   machine — `CONSENT_BEFORE_ROUTE` read the other way round.
+     */
+    routesFor(deviceOwner: string): Set<string>;
+    /**
+     * Every owner whose work this device's owner may run, as a list.
+     *
+     * The same question {@link mayRunFor} answers, asked in the direction a
+     * *store* can use. That difference is the crux of making `claim` atomic
+     * (cloud_006 §3.2).
+     *
+     * Today `claim` scans every job and calls `mayRunFor` per candidate, which
+     * works because the projection is a local object. A shared routing store
+     * cannot do that: the filter has to travel to the store, and a predicate
+     * does not travel — you cannot send a closure to Valkey. So the projection
+     * is collapsed to **data** here and handed over as a set the store can
+     * match on.
+     *
+     * That the collapse is possible at all is a property of the design worth
+     * noticing: `mayRunFor` is a finite lookup over consent and rosters, not a
+     * computation over the jobs. If it ever became job-dependent — "may run
+     * work of this size", say — an atomic claim would stop being expressible,
+     * and that is the moment to argue rather than to add a parameter.
+     *
+     * The owner is always included: a device runs its owner's work, and the
+     * relay checks that before it checks a roster.
+     */
+    ownersRunnableBy(deviceOwner: string): string[];
     /**
      * May this device's owner run work belonging to `jobOwner`?
      *
@@ -249,6 +342,133 @@ declare class Projection {
     mayRunFor(deviceOwner: string, jobOwner: string): boolean;
 }
 
+/**
+ * Pending pairing codes — cloud_009, the cloud-pairing flow.
+ *
+ * `byollm connect` speaks the device-code flow: ask for a code, show it, poll
+ * while a human approves it in a browser. A relay had no way to hold that
+ * pending state, so cloud pairing was never implemented — the hub accepted
+ * only the shape where the device is *already* approved, and nothing in the
+ * control plane created device rows at all. Every test passed because they
+ * drive direct mode or seed the row with a service key: the checks proved the
+ * parts and never the seam.
+ *
+ * ## Why the relay holds the code, and the control plane holds the decision
+ *
+ * The code is a short-lived handle on an *assertion* — "this keypair would
+ * like to be a machine" — and the relay is allowed to hold assertions. The
+ * approval is a human looking at a fingerprint, which belongs to the control
+ * plane where that human is signed in.
+ *
+ * So nothing here approves anything. The daemon's poll asks whether the
+ * control plane's projection now contains this device as approved, and the
+ * answer comes from the projection rather than from a flag somebody set here.
+ * That is what keeps the fence intact in both directions: the hub never
+ * writes to the control plane, and the control plane never writes to the hub.
+ *
+ * ## What a code is worth on its own
+ *
+ * Nothing. Holding a device code lets you ask "has anyone approved this
+ * keypair yet", and the answer is only ever yes for a keypair whose owner
+ * approved it by eye. Stolen mid-flight it grants no access, which is why it
+ * can be a URL-safe string a person reads aloud rather than a credential.
+ */
+/** What the relay remembers between `start` and `poll`. */
+interface PendingPairing {
+    /** The secret the daemon polls with. Never shown to a human. */
+    readonly deviceCode: string;
+    /** The short code a person reads and types into the dashboard. */
+    readonly userCode: string;
+    /** The keys the daemon presented. What a human is about to approve. */
+    readonly device: PublicIdentity;
+    /**
+     * What the machine said it can run, as advertised when it asked to pair.
+     *
+     * Held so the approval screen can show a person what they are approving,
+     * and so presence has an answer the moment the device appears rather than
+     * one heartbeat later. It is a claim, like everything else in this record —
+     * the heartbeat is the authority and replaces it within seconds.
+     */
+    readonly capabilities: CapabilityMatrix;
+    /** Label the daemon offered, for the approval screen. */
+    readonly label: string;
+    readonly platform: string;
+    /** Epoch ms. After this the code is gone, approved or not. */
+    readonly expiresAt: number;
+}
+/**
+ * What happened when a code was offered for storage.
+ *
+ * `put` can refuse, and the reason it can is the whole of the rate-limit
+ * story on this surface: **anybody can ask to pair.** That is not a bug — a
+ * machine with no pairing has no credential to present — but it means a
+ * stranger with a script can mint pending codes in a loop, and each one
+ * occupies memory in a shared store for ten minutes. Without a ceiling the
+ * only limit is somebody's patience.
+ *
+ * So the store has a capacity and says so, and the daemon is told to try
+ * again shortly rather than given a code that crowds out a real one. A cap is
+ * a blunt instrument — under a flood, a person pairing a laptop is refused
+ * alongside the attacker — but a refusal that resolves in ten minutes is a
+ * better failure than a hub that stops routing. Per-IP limits belong at the
+ * edge, where the IP actually is.
+ */
+type PutResult = "stored" | "at-capacity";
+/**
+ * What a caller is told when pairings are being refused for load.
+ *
+ * Exported because it is said in two places by two different limits. This
+ * package says it when the store is at capacity; a deployment that adds a
+ * per-IP budget in front (the hub does — cloud_014) says it when one source
+ * has spent its share. **One sentence for one situation, whichever limit
+ * produced it**: the person reading it in a terminal is told to try again
+ * shortly, and which of the two bit is not a distinction they can act on.
+ *
+ * It lived inline here and the hub kept a copy, which is the one-value-two-
+ * names defect this codebase keeps finding — and the copy that drifts would
+ * drift silently, because both sentences would be plausible.
+ */
+declare const PAIRING_BUSY_MESSAGE = "too many pairings are in progress right now \u2014 try again in a few minutes";
+interface PairingCodes {
+    put(pending: PendingPairing): Promise<PutResult>;
+    /** By the secret the daemon holds. */
+    byDeviceCode(deviceCode: string): Promise<PendingPairing | undefined>;
+    /** By the short code a human typed. */
+    byUserCode(userCode: string): Promise<PendingPairing | undefined>;
+    /** After a successful pairing, so a code is single-use. */
+    drop(deviceCode: string): Promise<void>;
+}
+declare function newUserCode(): string;
+/** The secret half. Long and URL-safe; never shown to anybody. */
+declare const newDeviceCode: () => string;
+/** How long a person has to walk to their browser and type eight characters. */
+declare const PAIRING_CODE_TTL_MS: number;
+/**
+ * How many pairings may be in flight at once, across a whole relay.
+ *
+ * Sized against reality rather than fear: a pairing takes under a minute of
+ * human attention, so five hundred outstanding at the same instant is a
+ * number this product will not reach honestly for a long time — and one an
+ * attacker reaches in a second. Small enough to bound the store, large enough
+ * that nobody legitimate meets it.
+ */
+declare const MAX_OUTSTANDING_PAIRINGS = 500;
+/**
+ * The in-memory implementation, for the reference relay and its tests.
+ *
+ * The hub replaces it with one backed by Valkey, because a hub is two
+ * replicas and a code minted on one must be pollable on the other — the same
+ * reason its routing store is not a `Map`.
+ */
+declare class MemoryPairingCodes implements PairingCodes {
+    #private;
+    constructor(now?: () => number, capacity?: number);
+    put(pending: PendingPairing): Promise<PutResult>;
+    byDeviceCode(deviceCode: string): Promise<PendingPairing | undefined>;
+    byUserCode(userCode: string): Promise<PendingPairing | undefined>;
+    drop(deviceCode: string): Promise<void>;
+}
+
 /**
  * `@byollm/relay` — the reference relay (cloud_004 §14).
  *
@@ -281,20 +501,73 @@ interface RelayOptions {
      * One, in the skeleton. Multi-tenant routing is the closed piece
      * (cloud_004 §9), and it replaces this field rather than extending it.
      */
-    readonly siteId: string;
     /** Consent and rosters, projected from the control plane. */
     readonly fixture?: RelayFixture;
     /** How long a claim is good for. */
     readonly leaseMs?: number;
     /** Injectable clock, so tests move time instead of sleeping. */
     readonly now?: () => number;
+    /**
+     * Where pending pairing codes live — cloud_009's device-code flow.
+     *
+     * Defaults to an in-memory store, which is right for the reference relay
+     * and wrong for a hub: two replicas mean a code minted on one must be
+     * pollable on the other, the same reason the routing store is not a `Map`.
+     */
+    readonly pairingCodes?: PairingCodes;
+    /**
+     * Where a human approves a code. The control plane's own URL.
+     *
+     * Given rather than derived: the relay cannot approve anything, because
+     * approving is looking at a fingerprint while signed in and that session
+     * lives in the dashboard. Absent, the device-code flow is refused as
+     * unsupported rather than pointed somewhere useless.
+     */
+    readonly verificationUrl?: string;
     /** Where the daemon plane is mounted. */
     readonly basePath?: string;
+    /**
+     * Serve `/debug`, which is off unless somebody asks for it.
+     *
+     * The page shows every routed job for a site, its state, who claimed it and
+     * how long its timers have left. It shows no prompt or result text — the
+     * relay does not have them — and it is genuinely useful when a route is
+     * behaving strangely.
+     *
+     * It is also, on anything reachable from the internet, an anonymous read of
+     * exactly the metadata the site plane exists to protect. That was finding
+     * eleven, found by curling a deployed hub. The hub refuses the route
+     * outright; this package used to serve it by default and leave `D005` to
+     * warn whoever deployed it, which is a default that fails safe only if
+     * somebody reads the audit.
+     *
+     * So: off, and per-site when on (cloud_009 §3 — the debug page is per-site
+     * or it is nothing). `D005` still fails for a relay that turned it on,
+     * which is the audit doing its job for an operator who made a choice rather
+     * than warning everybody about a default.
+     */
+    readonly debug?: boolean;
+    /**
+     * Where routing state lives — cloud_006.
+     *
+     * Defaults to an in-process {@link RelayState}, which is correct for one
+     * replica and is what this package ships. A hub running more than one
+     * replica supplies a shared implementation of {@link RoutingStore} instead;
+     * `packages/relay/test/two-replicas.test.ts` is why that is not optional.
+     *
+     * **The implementation is deliberately not in this package.** A Valkey
+     * client is a dependency every consumer would carry to get a feature only a
+     * multi-replica deployment uses, and the production hub is the closed piece
+     * (cloud_001). What ships here is the interface, the reference
+     * implementation, and the tests that say what an implementation must
+     * guarantee.
+     */
+    readonly store?: RoutingStore;
 }
 /** A running relay: one fetch handler, two planes, one debug page. */
 declare class Relay {
     #private;
-    readonly state: RelayState;
+    readonly state: RoutingStore;
     readonly projection: Projection;
     constructor(options: RelayOptions);
     /** Replace the projection — a control-plane push, or a fixture edit. */
@@ -308,11 +581,11 @@ declare class Relay {
      * site vanished should return to the queue without waiting for someone to
      * ask about it.
      */
-    sweep(): {
+    sweep(): Promise<{
         requeued: string[];
-    };
+    }>;
     /** The whole HTTP surface. */
     handle(request: Request): Promise<Response>;
 }
 
-export { AWAITING_PAYLOAD_MS, ConsentRecord, EMPTY_FIXTURE, type Presence, Projection, Relay, RelayFixture, RelayFixture as RelayFixtureSchema, type RelayOptions, RelayState, RosterRecord, type RoutedJob, type RoutedState, debugPage };
+export { ConsentRecord, DeviceRecord, EMPTY_FIXTURE, MAX_OUTSTANDING_PAIRINGS, MemoryPairingCodes, PAIRING_BUSY_MESSAGE, PAIRING_CODE_TTL_MS, type PairingCodes, type PendingPairing, Projection, type PutResult, Relay, RelayFixture, RelayFixture as RelayFixtureSchema, type RelayOptions, RevocationRecord, RosterRecord, RoutingStore, SiteRecord, debugPage, newDeviceCode, newUserCode };