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

package/dist/index.d.ts

@@ -1,144 +1,8 @@
-import { PublicIdentity, JobStub, SealedEnvelope } from '@byollm/protocol';
+import { PublicIdentity, CapabilityMatrix, ClaimedStub, SignedGrant } from '@byollm/protocol';
+import { R as RoutingStore } from './store-DPCLO12l.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-DPCLO12l.js';
 import { z } from 'zod';
 
-/**
- * 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.
- *
- * 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.
- */
-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;
-
 /**
  * What the relay is told about the world — cloud_004 §14.
  *
@@ -171,6 +35,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 +81,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>;
 /**
@@ -231,14 +127,27 @@ declare const RevocationRecord: z.ZodObject<{
 }, 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;
@@ -275,6 +184,13 @@ declare class Projection {
     constructor(fixture?: RelayFixture);
     /** Replace the projection wholesale — the control plane pushed a new one. */
     replace(fixture: RelayFixture): void;
+    /**
+     * 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.
      *
@@ -284,8 +200,135 @@ declare class Projection {
     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. */
+    /**
+     * 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[];
+    /**
+     * Which registered site owns this identity key id?
+     *
+     * A stub names its site by *key id* (Amendment A §A.3) so a daemon can
+     * check it against a pinned key without a lookup. A control plane knows
+     * sites by their account id. This is the one place that holds both, so it
+     * is the one place that joins them — a control plane asked to accept key
+     * ids would need its own copy of the registry.
+     *
+     * `null` for a key id no registered site carries, which is a projection
+     * that is behind rather than a job that is wrong.
+     */
+    siteIdForKey(keyId: string): string | null;
+    /**
+     * 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`?
      *
@@ -298,6 +341,173 @@ 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>;
+}
+
+/**
+ * What the relay asks a control plane, as one named shape.
+ *
+ * Spelled out twice — here and on `RelayOptions` — until adding `siteKey`
+ * made one of them wrong and the build caught it. That was luck: the two are
+ * structurally compared, so a field added to the *caller's* copy alone would
+ * have been accepted silently and the grant would have carried nothing.
+ */
+type GrantAuthor = (input: {
+    readonly job: ClaimedStub;
+    /** The site's id in the control plane's namespace, for its policy read. */
+    readonly siteId: string;
+    /**
+     * The same site as the stub names it — the key id the device pinned.
+     *
+     * Carried, never derived. This is the value that gets signed, and the one a
+     * device can compare against `stub.site` without a lookup and without
+     * trusting the party that routed it.
+     */
+    readonly siteKey: string;
+    readonly purpose?: string;
+    readonly owner: string;
+    readonly runnerId: string;
+    readonly capabilities: CapabilityMatrix;
+}) => Promise<GrantDecision> | GrantDecision;
+
+declare function debugPage(state: RoutingStore, now: number, 
+/**
+ * Asked whether each device's owner still consents — cloud_008 §2.3.
+ *
+ * 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.
+ */
+routesFor?: {
+    siteId: string;
+    consents: (owner: string) => boolean;
+}): Promise<string>;
+
 /**
  * `@byollm/relay` — the reference relay (cloud_004 §14).
  *
@@ -323,6 +533,30 @@ declare class Projection {
  * able to read a payload is to change its types, which is a review someone
  * would have to justify rather than a line someone could slip in.
  */
+/**
+ * What a control plane answers when a relay asks about one job.
+ *
+ * Declared here rather than imported, and deliberately narrower than what
+ * `@byollm/control-plane` returns: a relay needs to know whether it got a
+ * grant and whether a refusal is forever, and nothing else. Stating only that
+ * keeps the two packages independent — a relay can be wired to any control
+ * plane, and the reference engine satisfies this by having more, not less.
+ *
+ * `reason` is for the log. The relay never branches on it, because a relay
+ * that acted differently per reason would be a second implementation of a
+ * policy it does not own.
+ */
+type GrantDecision = {
+    readonly granted: SignedGrant;
+    readonly declined?: undefined;
+} | {
+    readonly granted?: undefined;
+    readonly declined: {
+        /** Never offer this job to this device again. */
+        readonly permanent: boolean;
+        readonly reason?: string;
+    };
+};
 interface RelayOptions {
     /**
      * Which site this relay routes for.
@@ -330,20 +564,129 @@ 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. */
+    /** Consent and routing, projected from the control plane. */
     readonly fixture?: RelayFixture;
+    /**
+     * The control plane's grant-signing public key — Amendment J.
+     *
+     * Handed to daemons at pairing, and the thing every grant is checked
+     * against. Configuring it without {@link RelayOptions.authorGrant} is
+     * refused at construction: a device told to expect signed grants and then
+     * sent none refuses every job, and it would do so with no signal here.
+     */
+    readonly controlPlanePublic?: string | undefined;
+    /**
+     * Whether a purpose can be satisfied for this person, asked at enqueue.
+     *
+     * The relay does not hold the answer and must not: one that filtered on
+     * mappings would hold the mapping, which is the one thing it cannot have. So
+     * it asks whoever does — in practice the control plane, which already
+     * decides this at claim, a moment later.
+     *
+     * Optional. A relay without it refuses nothing, which is a supported
+     * arrangement and one an operator must be able to see they are in: say so at
+     * boot and on the health surface, because a check that quietly is not there
+     * reads as a check that passed.
+     */
+    readonly satisfiable?: (query: {
+        readonly siteId: string;
+        readonly owner: string;
+        readonly purpose: string | undefined;
+        readonly kind: string;
+    }) => Promise<{
+        readonly verdict: "ok" | "not-declared" | "unmapped";
+    }>;
+    /**
+     * Author a grant for one claimed job — Amendment J.
+     *
+     * **The relay asks; it does not decide.** Everything a grant asserts —
+     * whose job this is, whether they are still a member, which of the owner's
+     * services their mapping resolves to — is the control plane's knowledge,
+     * and this callback is the seam between the two. A relay wired to a
+     * deployment that has no control plane simply has no callback, and its
+     * devices serve their owners alone.
+     *
+     * Declining says whether the refusal is **permanent**, and that is the
+     * whole reason this returns a shape rather than `SignedGrant | undefined`.
+     * A relay releases a declined job, and a release can carry `refused`, which
+     * means never offer this job to this device again. "This person was removed
+     * from the team" is forever — removal stops queued claims, per hole 1.
+     * "Their mapping resolved to another of your machines" is emphatically not:
+     * marking that permanently would mean the job could never reach the device
+     * it was always meant for, and nothing would ever report it.
+     *
+     * The capability matrix is passed because resolution needs it — the control
+     * plane chooses from what this device actually advertised, never from a
+     * name it invented. Until byollm_016 Amendment L lands, "resolution" is the
+     * job's own selection or the device's default; after it, the user's
+     * per-purpose mapping. The seam does not change.
+     */
+    readonly authorGrant?: GrantAuthor;
     /** 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. */
@@ -357,11 +700,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, DeviceRecord, EMPTY_FIXTURE, type Presence, Projection, Relay, RelayFixture, RelayFixture as RelayFixtureSchema, type RelayOptions, RelayState, RevocationRecord, RosterRecord, type RoutedJob, type RoutedState, debugPage };
+export { ConsentRecord, DeviceRecord, EMPTY_FIXTURE, type GrantDecision, 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 };