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

package/dist/index.js

@@ -1,109 +1,165 @@
+import {
+  AWAITING_PAYLOAD_MS,
+  RETRY_AFTER_MS,
+  RelayState,
+  routeKey
+} from "./chunk-OB6LPEEE.js";
+
+// src/index.ts
+import {
+  checkProtocolVersion,
+  declaredVersion
+} from "@byollm/protocol";
+
 // src/daemon-plane.ts
 import {
+  PairPollRequest,
+  PairStartRequest,
   ClaimRequest,
   FetchRequest,
   HeartbeatRequest,
+  MAX_ENVELOPE_BYTES as MAX_ENVELOPE_BYTES2,
   PROTOCOL_VERSION,
   ReleaseRequest,
   ResultRequest,
   RequestSignature,
+  envelopeBytes,
   keyId,
   verifyRequest,
   verifyPublicIdentity,
-  PublicIdentity
+  PublicIdentity,
+  ERROR_STATUS as ERROR_STATUS2
 } from "@byollm/protocol";
-import { randomUUID } from "crypto";
 import { z } from "zod";
 
-// src/state.ts
-var AWAITING_PAYLOAD_MS = 1e4;
-var RelayState = class {
-  #jobs = /* @__PURE__ */ new Map();
-  #presence = /* @__PURE__ */ new Map();
-  /** Take a stub for routing. The payload is not here and will not be. */
-  enqueue(input) {
-    const job = {
-      id: input.id,
-      siteId: input.siteId,
-      stub: input.stub,
-      state: "queued"
-    };
-    this.#jobs.set(job.id, job);
-    return job;
-  }
-  job(jobId) {
-    return this.#jobs.get(jobId);
-  }
-  jobs() {
-    return [...this.#jobs.values()];
-  }
-  /** Jobs a site must seal for, right now. */
-  awaiting(siteId) {
-    return this.jobs().filter(
-      (j) => j.siteId === siteId && j.state === "awaiting-payload"
-    );
+// src/pairing-codes.ts
+import { randomBytes } from "crypto";
+var PAIRING_BUSY_MESSAGE = "too many pairings are in progress right now \u2014 try again in a few minutes";
+var HUMAN_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function newUserCode() {
+  const groups = Array.from(
+    randomBytes(8),
+    (byte) => HUMAN_ALPHABET.charAt(byte % HUMAN_ALPHABET.length)
+  );
+  return `${groups.slice(0, 4).join("")}-${groups.slice(4).join("")}`;
+}
+var newDeviceCode = () => randomBytes(32).toString("base64url");
+var PAIRING_CODE_TTL_MS = 10 * 60 * 1e3;
+var MAX_OUTSTANDING_PAIRINGS = 500;
+var MemoryPairingCodes = class {
+  #byDevice = /* @__PURE__ */ new Map();
+  #now;
+  #capacity;
+  constructor(now = Date.now, capacity = MAX_OUTSTANDING_PAIRINGS) {
+    this.#now = now;
+    this.#capacity = capacity;
   }
-  /** Sealed results waiting to go home. */
-  finished(siteId) {
-    return this.jobs().filter(
-      (j) => j.siteId === siteId && j.state === "done" && j.result !== void 0
-    );
+  #live(pending) {
+    if (!pending) return void 0;
+    return pending.expiresAt > this.#now() ? pending : void 0;
   }
-  seen(presence) {
-    const existing = this.#presence.get(presence.runnerId);
-    if (existing) {
-      existing.lastSeenAt = presence.lastSeenAt;
-      return existing;
+  put(pending) {
+    const now = this.#now();
+    for (const [code, held] of this.#byDevice) {
+      if (held.expiresAt <= now) this.#byDevice.delete(code);
     }
-    const fresh = { ...presence, revoked: false };
-    this.#presence.set(presence.runnerId, fresh);
-    return fresh;
-  }
-  presence(runnerId) {
-    return this.#presence.get(runnerId);
-  }
-  everyone() {
-    return [...this.#presence.values()];
+    const fingerprint = pending.device.identity;
+    for (const [code, held] of this.#byDevice) {
+      if (held.device.identity === fingerprint) this.#byDevice.delete(code);
+    }
+    if (this.#byDevice.size >= this.#capacity)
+      return Promise.resolve("at-capacity");
+    this.#byDevice.set(pending.deviceCode, pending);
+    return Promise.resolve("stored");
   }
-  /**
-   * 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) {
-    job.state = "queued";
-    delete job.claimedBy;
-    delete job.awaitingUntil;
-    delete job.payload;
+  byDeviceCode(deviceCode) {
+    return Promise.resolve(this.#live(this.#byDevice.get(deviceCode)));
   }
-  /**
-   * 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) {
-    const requeued = [];
-    for (const job of this.#jobs.values()) {
-      if (job.state === "awaiting-payload" && (job.awaitingUntil ?? 0) <= now) {
-        this.requeue(job);
-        requeued.push(job);
-      }
-      const lease = job.claimedBy;
-      if (lease && (job.state === "ready" || job.state === "running") && lease.leaseExpiresAt <= now) {
-        this.requeue(job);
-        requeued.push(job);
-      }
+  byUserCode(userCode) {
+    const wanted = userCode.trim().toUpperCase();
+    for (const pending of this.#byDevice.values()) {
+      if (pending.userCode === wanted)
+        return Promise.resolve(this.#live(pending));
     }
-    return requeued;
+    return Promise.resolve(void 0);
+  }
+  drop(deviceCode) {
+    this.#byDevice.delete(deviceCode);
+    return Promise.resolve();
   }
 };
 
+// src/refusals.ts
+import {
+  ERROR_STATUS,
+  MAX_CLOCK_SKEW_MS,
+  MAX_ENVELOPE_BYTES
+} from "@byollm/protocol";
+function clockSkewRefusal(now) {
+  return {
+    status: ERROR_STATUS["clock-skew"],
+    body: {
+      error: "clock-skew",
+      message: "this request's timestamp is too far from the server's clock; check the machine's time and try again",
+      // So the far side can say *how far off* rather than *that something is
+      // wrong*. Not a disclosure: the heartbeat response returns the same
+      // value, and so does every `Date` header.
+      serverTime: now,
+      maxSkewMs: MAX_CLOCK_SKEW_MS
+    }
+  };
+}
+function tooLargeRefusal(bytes) {
+  const mb = (n) => `${(Math.ceil(n / (1024 * 1024) * 10) / 10).toFixed(1)} MB`;
+  const limit = `${(MAX_ENVELOPE_BYTES / (1024 * 1024)).toFixed(1)} MB`;
+  return {
+    status: ERROR_STATUS["bad-request"],
+    body: {
+      error: "bad-request",
+      message: `this message is ${mb(bytes)} and the limit is ${limit} \u2014 every plan has the same ceiling, and it is a limit on one message rather than on how many you send. Split the work into smaller jobs and send them separately.`
+    }
+  };
+}
+
 // src/daemon-plane.ts
 var ok = (body) => ({ status: 200, body });
+var REFUSALS = {
+  "not-found": {
+    status: 404,
+    body: { error: "not-found", message: "unknown job" }
+  },
+  // `forbidden`, not `unauthorized` — V1-13. Both of these are an
+  // *identified* caller being refused, which is what 403 means and what the
+  // table says `forbidden` is for; `unauthorized` is 401 and means "we do not
+  // know who you are". Served as 403 with a 401's code, a revoked daemon and
+  // an unsigned one looked alike in every log and every client branch, and
+  // "check your keys" is the wrong advice for both in opposite directions.
+  "not-holder": {
+    status: 403,
+    body: {
+      error: "forbidden",
+      message: "this runner does not hold the job"
+    }
+  },
+  "stale-lease": {
+    status: 403,
+    body: { error: "forbidden", message: "that lease is no longer current" }
+  },
+  "not-ready": {
+    status: 409,
+    body: {
+      error: "not-ready",
+      message: "the site has not sealed this job yet"
+    }
+  },
+  // Also a 409, and deliberately a different code: `not-ready` means keep
+  // asking and this means stop. A daemon that read them as one would poll a
+  // finished job until its lease ran out.
+  terminal: {
+    status: 409,
+    body: { error: "too-late", message: "this job has already finished" }
+  }
+};
 var fail = (status, error, message) => ({
   status,
   body: { error, message }
@@ -123,7 +179,11 @@ var DaemonPlane = class {
    * relay that substituted its own identity here could inject work — and would
    * need a private key to do it, which is why it has none.
    */
-  pair(body) {
+  async pair(body) {
+    const start = PairStartRequest.safeParse(body);
+    if (start.success) return this.#pairStart(start.data);
+    const poll = PairPollRequest.safeParse(body);
+    if (poll.success) return this.#pairPoll(poll.data);
     const parsed = PairFixtureRequest.safeParse(body);
     if (!parsed.success) {
       return fail(400, "bad-request", "pair request failed schema validation");
@@ -131,12 +191,9 @@ var DaemonPlane = class {
     if (!verifyPublicIdentity(parsed.data.device)) {
       return fail(400, "bad-request", "the device identity is not consistent");
     }
-    const consent = this.#deps.projection.consentFor(
-      parsed.data.owner,
-      this.#deps.siteId
-    );
-    if (!consent) {
-      return fail(403, "unauthorized", "no consent record for this user");
+    const sites = this.#deps.projection.sitesFor(parsed.data.owner);
+    if (sites.length === 0) {
+      return fail(403, "forbidden", "no consent record for this user");
     }
     const approved = this.#deps.projection.deviceByFingerprint(
       parsed.data.device.identity
@@ -144,36 +201,167 @@ var DaemonPlane = class {
     if (!approved) {
       return fail(
         403,
-        "unauthorized",
+        "forbidden",
         "this device has not been approved by its owner"
       );
     }
     if (approved.owner !== parsed.data.owner) {
-      return fail(403, "unauthorized", "this device belongs to another owner");
+      return fail(403, "forbidden", "this device belongs to another owner");
     }
     const runnerId = approved.runnerId;
-    this.#deps.state.seen({
+    await this.#deps.state.seen({
       runnerId,
       owner: parsed.data.owner,
       device: parsed.data.device,
-      lastSeenAt: this.#deps.now()
+      // The fixture exchange carries no matrix — it models a consent that
+      // arrived from a file, not a daemon describing itself. Empty until the
+      // first heartbeat, which is seconds away and is the authority anyway.
+      capabilities: [],
+      withheld: []
     });
     return ok({
       protocolVersion: PROTOCOL_VERSION,
       runnerId,
-      /** The *site's* key. See the note above — this is load-bearing. */
-      site: consent.site
+      /**
+       * The *sites'* keys. See the note above — this is load-bearing.
+       *
+       * The set this owner has consented to, keyed by each site's identity
+       * key id (cloud_009 §5). Paused sites are here: a paused consent keeps
+       * its pin so re-consenting never costs a re-pair, and what it does not
+       * do is route.
+       */
+      sites: Object.fromEntries(
+        sites.map((record) => [keyId(record.site.identity), record.site])
+      ),
+      // The key every later grant is checked against — Amendment J. Sent
+      // here and nowhere else: pairing is the ceremony where a human is
+      // already deciding whether to trust this upstream, so a key learned
+      // here rides a decision that has been made rather than inventing one.
+      ...this.#deps.controlPlanePublic === void 0 ? {} : { controlPlanePublic: this.#deps.controlPlanePublic }
+    });
+  }
+  /**
+   * Mint a code, remember the keys it stands for, and send the human away.
+   *
+   * Nothing is decided here. The relay holds an assertion — "this keypair
+   * would like to be a machine" — for ten minutes, and the decision happens
+   * where the person is signed in.
+   */
+  async #pairStart(request) {
+    const codes = this.#deps.pairingCodes;
+    const verificationUrl = this.#deps.verificationUrl;
+    if (!codes || verificationUrl === void 0) {
+      return fail(
+        501,
+        "bad-request",
+        "this relay does not offer device-code pairing"
+      );
+    }
+    if (!verifyPublicIdentity(request.device)) {
+      return fail(400, "bad-request", "the device identity is not consistent");
+    }
+    const pending = {
+      deviceCode: newDeviceCode(),
+      userCode: newUserCode(),
+      device: request.device,
+      label: request.daemon.label,
+      platform: request.daemon.platform,
+      capabilities: request.capabilities,
+      expiresAt: this.#deps.now() + PAIRING_CODE_TTL_MS
+    };
+    if (await codes.put(pending) === "at-capacity") {
+      return fail(
+        ERROR_STATUS2["rate-limited"],
+        "rate-limited",
+        PAIRING_BUSY_MESSAGE
+      );
+    }
+    return ok({
+      deviceCode: pending.deviceCode,
+      userCode: pending.userCode,
+      verificationUrl,
+      expiresAt: pending.expiresAt,
+      // Two seconds: fast enough that approving feels immediate, slow enough
+      // that a forgotten terminal is not a load generator.
+      pollIntervalMs: 2e3
+    });
+  }
+  /**
+   * Has anybody approved this keypair yet?
+   *
+   * The answer comes from the **projection** — the control plane's own record
+   * of devices a human approved — and never from a flag set here. That is the
+   * whole shape of the fence: the dashboard writes the approval to its own
+   * database, the hub's projection catches up within a poll, and this notices.
+   * No write crosses in either direction.
+   */
+  async #pairPoll(request) {
+    const codes = this.#deps.pairingCodes;
+    if (!codes) {
+      return fail(
+        501,
+        "bad-request",
+        "this relay does not offer device-code pairing"
+      );
+    }
+    const pending = await codes.byDeviceCode(request.deviceCode);
+    if (!pending) return ok({ status: "expired" });
+    const approved = this.#deps.projection.deviceByFingerprint(
+      pending.device.identity
+    );
+    if (!approved) return ok({ status: "pending" });
+    const sites = this.#deps.projection.sitesFor(approved.owner);
+    await this.#deps.state.seen({
+      runnerId: approved.runnerId,
+      owner: approved.owner,
+      device: pending.device,
+      // What this machine said it could run when it asked to pair, so the
+      // approval screen and the machines page have an answer in the same
+      // moment the device appears. The next heartbeat replaces it.
+      capabilities: pending.capabilities,
+      // A pairing request describes what a machine *can* run, not what it is
+      // holding back — the daemon resolves defaults locally, and the first
+      // heartbeat is where that answer arrives.
+      withheld: []
+    });
+    await codes.drop(pending.deviceCode);
+    return ok({
+      status: "approved",
+      runnerId: approved.runnerId,
+      owner: approved.owner,
+      sites: Object.fromEntries(
+        sites.map((record) => [keyId(record.site.identity), record.site])
+      ),
+      // The key every later grant is checked against — Amendment J. Sent
+      // here and nowhere else: pairing is the ceremony where a human is
+      // already deciding whether to trust this upstream, so a key learned
+      // here rides a decision that has been made rather than inventing one.
+      ...this.#deps.controlPlanePublic === void 0 ? {} : { controlPlanePublic: this.#deps.controlPlanePublic }
     });
   }
   /** Every authenticated call: signature first, then consent, then work. */
-  #authed(input, body, schema, run, options = {}) {
+  async #authed(input, body, schema, run, options = {}) {
     const signature = RequestSignature.safeParse(input.signature);
     if (!signature.success) {
       return fail(401, "unauthorized", "this request is not signed");
     }
-    const known = this.#deps.state.presence(signature.data.runnerId);
+    let known = await this.#deps.state.presence(signature.data.runnerId);
+    let rebuilt = false;
     if (!known) {
-      return fail(401, "unauthorized", "this runner is not recognised");
+      const approved = this.#deps.projection.deviceFor(signature.data.runnerId);
+      if (!approved) {
+        return fail(401, "unauthorized", "this runner is not recognised");
+      }
+      known = {
+        ...approved,
+        lastSeenAt: this.#deps.now(),
+        // Not invented. The heartbeat is the authority on what a machine can
+        // run, and it is seconds away; claiming a matrix here would be this
+        // file guessing about a backend it cannot see.
+        capabilities: [],
+        withheld: []
+      };
+      rebuilt = true;
     }
     const failure = verifyRequest({
       identityPublic: known.device.identity,
@@ -182,8 +370,21 @@ var DaemonPlane = class {
       signature: signature.data,
       now: this.#deps.now()
     });
+    if (failure === "stale") return this.#clockSkew();
     if (failure) return fail(401, "unauthorized", "signature check failed");
-    if (known.revoked && options.allowRevoked !== true) {
+    if (rebuilt) {
+      await this.#deps.state.seen({
+        runnerId: known.runnerId,
+        owner: known.owner,
+        device: known.device,
+        capabilities: [],
+        // Nothing has described itself yet, so nothing is withheld — the
+        // first heartbeat is the authority on both.
+        withheld: []
+      });
+    }
+    const revoked = this.#deps.projection.revokedOutright(known.owner);
+    if (revoked && options.allowRevoked !== true) {
       return fail(403, "revoked", "routing for this runner has been revoked");
     }
     known.lastSeenAt = this.#deps.now();
@@ -193,42 +394,104 @@ var DaemonPlane = class {
     }
     return run(parsed.data, known);
   }
+  /**
+   * A clock too far from ours, said plainly and with the number to fix it by.
+   *
+   * Its own error code rather than a generic `unauthorized`, because it is the
+   * one refusal a retry can never fix and an `ntpdate` always can — the same
+   * reasoning `version-unsupported` already carries on the daemon side. A
+   * daemon that reports this as a generic rejection sends its owner looking at
+   * their network.
+   *
+   * `serverTime` is included so the far side can say *how far off* rather than
+   * *that something is wrong*. It is not a disclosure: the heartbeat response
+   * returns the same value, and so does every `Date` header.
+   */
+  #clockSkew() {
+    return clockSkewRefusal(this.#deps.now());
+  }
   claim(auth, body) {
-    return this.#authed(auth, body, ClaimRequest, (request, device) => {
+    return this.#authed(auth, body, ClaimRequest, async (request, device) => {
       if (request.runnerId !== device.runnerId) {
-        return fail(401, "unauthorized", "runner id does not match the key");
+        return fail(403, "forbidden", "runner id does not match the key");
       }
-      const now = this.#deps.now();
-      this.#deps.state.sweep(now);
-      const kinds = new Set(request.capabilities.map((c) => c.kind));
-      const granted = [];
-      for (const job of this.#deps.state.jobs()) {
-        if (granted.length >= request.max) break;
-        if (job.state !== "queued") continue;
-        if (!kinds.has(job.stub.kind)) continue;
-        if (!this.#deps.projection.mayRunFor(device.owner, job.stub.owner)) {
+      const granted = await this.#deps.state.claim({
+        runnerId: device.runnerId,
+        owner: device.owner,
+        device: device.device,
+        // Every kind this device can run, from any of its services.
+        //
+        // This used to send only the *defaults* — the rows an unselected job
+        // should reach — beside the whole menu as (kind, service) pairs. A
+        // job names no service now, so there is no menu to match against and
+        // no unselected case for a default to catch: a device answering a
+        // kind at all is a candidate, and which of its services runs the work
+        // is resolved from the person's mapping when the grant is signed.
+        kinds: new Set(request.capabilities.map((c) => c.kind)),
+        // The projection, collapsed to data the store can match on — a
+        // predicate does not travel, and a set of (site, owner) pairs is
+        // what a route is (cloud_009 §3).
+        //
+        // A paused consent (cloud_008 finding 48) drops its routes and
+        // leaves the rest, which is the whole difference between "we are
+        // waiting for you to read something about one site" and "a human cut
+        // you off from everything".
+        routes: this.#deps.projection.routesFor(device.owner),
+        max: request.max,
+        leaseMs: this.#deps.leaseMs
+      });
+      const author = this.#deps.authorGrant;
+      if (author === void 0) {
+        return ok({ jobs: granted, leaseMs: this.#deps.leaseMs });
+      }
+      const withGrants = [];
+      const refused = [];
+      const returned = [];
+      for (const job of granted) {
+        const siteId = this.#deps.projection.siteIdForKey(job.site);
+        const decision = siteId === null ? (
+          // A stub naming a site this projection cannot place. Transient
+          // rather than permanent: the projection is what is behind, not
+          // the job.
+          { declined: { permanent: false, reason: "unknown-site" } }
+        ) : await author({
+          job,
+          siteId,
+          // Straight off the stub. A relay that computed this would be
+          // choosing which site a grant says it is for, which is the
+          // one thing the signature exists to take out of its hands.
+          siteKey: job.site,
+          // The site's own purpose, straight off the stub. A relay does
+          // not interpret it — it does not hold the manifest and does
+          // not hold the mapping; it carries the site's word to the one
+          // party that can join them.
+          ...job.purpose === void 0 ? {} : { purpose: job.purpose },
+          owner: device.owner,
+          runnerId: device.runnerId,
+          capabilities: request.capabilities
+        });
+        if (decision.granted === void 0) {
+          const lease = { jobId: job.id, leaseId: job.lease.id };
+          (decision.declined.permanent ? refused : returned).push(lease);
           continue;
         }
-        const leaseId = randomUUID();
-        job.state = "awaiting-payload";
-        job.claimedBy = {
+        withGrants.push({ ...job, grant: decision.granted });
+      }
+      if (refused.length > 0) {
+        await this.#deps.state.releaseLeases({
           runnerId: device.runnerId,
-          owner: device.owner,
-          device: device.device,
-          leaseId,
-          leaseExpiresAt: now + this.#deps.leaseMs
-        };
-        job.awaitingUntil = now + AWAITING_PAYLOAD_MS;
-        granted.push({
-          ...job.stub,
-          lease: {
-            id: leaseId,
-            runnerId: device.runnerId,
-            expiresAt: job.claimedBy.leaseExpiresAt
-          }
+          leases: refused,
+          reason: "refused"
         });
       }
-      return ok({ jobs: granted, leaseMs: this.#deps.leaseMs });
+      if (returned.length > 0) {
+        await this.#deps.state.releaseLeases({
+          runnerId: device.runnerId,
+          leases: returned,
+          retryAfter: this.#deps.now() + RETRY_AFTER_MS
+        });
+      }
+      return ok({ jobs: withGrants, leaseMs: this.#deps.leaseMs });
     });
   }
   /**
@@ -242,20 +505,14 @@ var DaemonPlane = class {
    * awaiting-payload clock says otherwise.
    */
   fetch(auth, body) {
-    return this.#authed(auth, body, FetchRequest, (request, device) => {
-      const job = this.#deps.state.job(request.jobId);
-      if (!job) return fail(404, "not-found", "unknown job");
-      if (job.claimedBy?.runnerId !== device.runnerId) {
-        return fail(403, "unauthorized", "this runner does not hold the job");
-      }
-      if (job.claimedBy.leaseId !== request.leaseId) {
-        return fail(403, "unauthorized", "that lease is no longer current");
-      }
-      if (!job.payload) {
-        return fail(409, "not-ready", "the site has not sealed this job yet");
-      }
-      job.state = "running";
-      return ok({ envelope: job.payload });
+    return this.#authed(auth, body, FetchRequest, async (request, device) => {
+      const taken = await this.#deps.state.takePayload({
+        jobId: request.jobId,
+        runnerId: device.runnerId,
+        leaseId: request.leaseId
+      });
+      if ("refused" in taken) return REFUSALS[taken.refused];
+      return ok({ envelope: taken.envelope });
     });
   }
   /**
@@ -268,19 +525,18 @@ var DaemonPlane = class {
    * only verifiable there.
    */
   result(auth, body) {
-    return this.#authed(auth, body, ResultRequest, (request, device) => {
-      const job = this.#deps.state.job(request.jobId);
-      if (!job) return fail(404, "not-found", "unknown job");
-      if (job.claimedBy?.runnerId !== device.runnerId) {
-        return fail(403, "unauthorized", "this runner does not hold the job");
-      }
-      if (job.state === "done") {
-        return ok({ accepted: false, state: job.state });
-      }
-      job.result = request.envelope;
-      job.disposition = request.disposition;
-      job.state = "done";
-      return ok({ accepted: true, state: job.state });
+    return this.#authed(auth, body, ResultRequest, async (request, device) => {
+      const bytes = envelopeBytes(request.envelope);
+      if (bytes > MAX_ENVELOPE_BYTES2) return tooLargeRefusal(bytes);
+      const recorded = await this.#deps.state.complete({
+        jobId: request.jobId,
+        runnerId: device.runnerId,
+        leaseId: request.leaseId,
+        envelope: request.envelope,
+        disposition: request.disposition
+      });
+      if ("refused" in recorded) return REFUSALS[recorded.refused];
+      return ok(recorded);
     });
   }
   heartbeat(auth, body) {
@@ -288,41 +544,76 @@ var DaemonPlane = class {
       auth,
       body,
       HeartbeatRequest,
-      (request, device) => {
+      async (request, device) => {
         const now = this.#deps.now();
-        this.#deps.state.sweep(now);
-        const known = this.#deps.state.presence(device.runnerId);
-        const consent = this.#deps.projection.consentFor(
-          device.owner,
-          this.#deps.siteId
+        await this.#deps.state.sweep();
+        await this.#deps.state.seen({
+          runnerId: device.runnerId,
+          owner: device.owner,
+          device: device.device,
+          capabilities: request.capabilities,
+          // Arrives on the same beat as the matrix and goes stale with it.
+          // A daemon that resolves a contended kind stops sending it here,
+          // which is what retires the owner's prompt to choose.
+          withheld: request.withheld
+        });
+        const pinned = this.#deps.projection.sitesFor(device.owner);
+        const sites = Object.fromEntries(
+          pinned.map((record) => [keyId(record.site.identity), record.site])
         );
-        const revoked = consent === null;
-        if (known) known.revoked = revoked;
-        const lost = request.activeLeases.filter(({ jobId, leaseId }) => {
-          const job = this.#deps.state.job(jobId);
-          return job?.claimedBy?.leaseId !== leaseId;
-        }).map(({ jobId }) => jobId);
+        const successions = Object.fromEntries(
+          pinned.filter((record) => (record.succeeds?.length ?? 0) > 0).map((record) => [
+            keyId(record.site.identity),
+            {
+              succeeds: record.succeeds ?? [],
+              ...record.retiringUntil === void 0 ? {} : { retiringUntil: record.retiringUntil }
+            }
+          ])
+        );
+        const rotations = Object.keys(successions).length > 0 ? { successions } : {};
+        const awaitingConsent = pinned.filter(
+          (record) => !this.#deps.projection.mayRouteFor(device.owner, record.siteId)
+        ).map((record) => keyId(record.site.identity));
+        if (pinned.length === 0) {
+          return ok({
+            sites,
+            ...rotations,
+            awaitingConsent,
+            cancel: [],
+            lost: request.activeLeases.map((lease) => ({
+              jobId: lease.jobId,
+              leaseId: lease.leaseId
+            })),
+            serverTime: now
+          });
+        }
+        const cancel = await this.#deps.state.cancelRequests(device.runnerId);
+        const { lost } = await this.#deps.state.renewLeases({
+          runnerId: device.runnerId,
+          leases: request.activeLeases,
+          leaseMs: this.#deps.leaseMs
+        });
         return ok({
-          revoked,
-          cancel: [],
-          leases: [],
+          sites,
+          ...rotations,
+          awaitingConsent,
+          cancel,
           lost,
           serverTime: now
         });
-      },
-      { allowRevoked: true }
+      }
     );
   }
   release(auth, body) {
-    return this.#authed(auth, body, ReleaseRequest, (request, device) => {
-      const released = [];
-      for (const { jobId, leaseId } of request.leases) {
-        const job = this.#deps.state.job(jobId);
-        if (!job || job.claimedBy?.runnerId !== device.runnerId) continue;
-        if (job.claimedBy.leaseId !== leaseId) continue;
-        this.#deps.state.requeue(job);
-        released.push(jobId);
-      }
+    return this.#authed(auth, body, ReleaseRequest, async (request, device) => {
+      const released = await this.#deps.state.releaseLeases({
+        runnerId: device.runnerId,
+        leases: request.leases,
+        // Was dropped here — cloud_008 §2.1. `reason` is on the wire, the
+        // schema's own docstring says an upstream MUST record `refused`, and
+        // this handler read every other field.
+        reason: request.reason
+      });
       return ok({ released });
     });
   }
@@ -362,9 +653,9 @@ function jobRow(job, now) {
     <td>${job.result ? escape(job.disposition ?? "?") : "<span class='dim'>\u2014</span>"}</td>
   </tr>`;
 }
-function debugPage(state, now) {
-  const jobs = state.jobs();
-  const devices = state.everyone();
+async function debugPage(state, now, routesFor) {
+  const jobs = await state.jobs();
+  const devices = await state.everyone();
   return `<!doctype html>
 <html><head><meta charset="utf-8"><title>byollm relay \u2014 debug</title>
 <meta http-equiv="refresh" content="1">
@@ -402,7 +693,7 @@ ${devices.length ? devices.map(
   <td>${escape(d.owner)}</td>
   <td><code>${escape(fingerprintOf(d.device))}</code></td>
   <td>${String(Math.max(0, now - d.lastSeenAt))}ms ago</td>
-  <td>${d.revoked ? "<b style='color:#c00'>revoked</b>" : "active"}</td>
+  <td>${routesFor && !routesFor.consents(d.owner) ? "<b style='color:#c00'>no consent</b>" : "active"}</td>
 </tr>`
   ).join("\n") : `<tr><td colspan="5" class="dim">no devices connected</td></tr>`}
 </table>
@@ -410,21 +701,78 @@ ${devices.length ? devices.map(
 }
 
 // src/fixture.ts
-import { PublicIdentity as PublicIdentity2 } from "@byollm/protocol";
+import {
+  MAX_SUCCESSION_CHAIN,
+  Succession,
+  PublicIdentity as PublicIdentity2,
+  keyId as keyIdOf
+} from "@byollm/protocol";
 import { z as z2 } from "zod";
+var SiteRecord = z2.object({
+  /** How the control plane names the site. */
+  siteId: z2.string().min(1),
+  /**
+   * The site's public identity.
+   *
+   * The relay distributes it and cannot use it: an identity key verifies
+   * signatures and seals nothing. This is the key-exchange half of consent
+   * (cloud_004 §3), and both endpoints pin what they receive.
+   */
+  site: PublicIdentity2,
+  /**
+   * How this site's current key can be traced back to one a daemon holds —
+   * byollm_009 Amendment C, ordered oldest last.
+   *
+   * A list rather than one predecessor because a daemon offline across two
+   * rotations holds K1 and meets K3: with a single predecessor it could not
+   * verify K3 without K2's record, so it would have to re-pair over
+   * housekeeping it did not ask for. The proofs are small, self-verifying,
+   * and kept indefinitely for the same reason.
+   *
+   * **The relay distributes these and cannot mint one.** Each is a signature
+   * by a key it does not hold, which is what lets rotation be automatic
+   * without becoming the substitution `SITES_LOCALLY_APPROVED` refuses.
+   */
+  succeeds: z2.array(Succession).max(MAX_SUCCESSION_CHAIN).optional(),
+  /**
+   * Until when the retired key may still sign work — epoch ms.
+   *
+   * Absent on a site that has never rotated. The daemon holds its own clock
+   * against this for the reason it holds its own allowlist: a projection
+   * that could extend the window indefinitely would be a two-key site
+   * forever, decided by the party the design does not trust.
+   */
+  retiringUntil: z2.number().int().positive().optional()
+}).strict();
 var ConsentRecord = z2.object({
   /** The user, as the control plane identifies them. */
   owner: z2.string().min(1),
   /** Which site this consent is for. Scoped: consent is never global. */
   siteId: z2.string().min(1),
   /**
-   * The site's public identity, as the relay will hand it to the daemon.
+   * The consent stands, and nothing routes under it — cloud_008 finding 48.
    *
-   * The relay distributes it and cannot use it: an identity key verifies
-   * signatures and seals nothing. This is the key-exchange half of consent
-   * (cloud_004 §3), and both endpoints pin what they receive.
+   * The disclosure this user agreed to no longer describes their
+   * arrangements: they read that their prompts stay on machines they own,
+   * and they have since been added to a roster whose owner can read them.
+   * Until they have been shown the other sentence and clicked, their work
+   * does not move.
+   *
+   * **A third state, because the two we had are both wrong here.** Dropping
+   * the consent makes `consentFor` return null, and the daemon plane reads
+   * exactly that as revoked: heartbeat answers `revoked: true` with `lost:
+   * all`, and the daemon prints "this runner was revoked" and *deletes its
+   * pairing*. So a user whose team changed a setting would be told a human
+   * cut them off, lose their pinned keys, and have to re-run `byollm
+   * connect` after re-consenting. Under cloud_009 that is worse still: the
+   * pairing is keyed by origin, so one stale consent would drop the pairing
+   * for every other site reached through that hub.
+   *
+   * Reporting it as revoked is the same falsehood finding 48 exists to
+   * delete, told one layer down. So the record stays, the relationship
+   * stays, and the routing stops.
    */
-  site: PublicIdentity2
+  paused: z2.boolean().default(false)
 }).strict();
 var RosterRecord = z2.object({
   /** Stable id for the group, used only inside the relay. */
@@ -444,6 +792,8 @@ var DeviceRecord = z2.object({
 }).strict();
 var RevocationRecord = z2.object({ owner: z2.string().min(1), siteId: z2.string().min(1) }).strict();
 var RelayFixture = z2.object({
+  /** Registered sites, by id. A consent for a site absent here routes not. */
+  sites: z2.array(SiteRecord).default([]),
   consents: z2.array(ConsentRecord),
   devices: z2.array(DeviceRecord).default([]),
   rosters: z2.array(RosterRecord).default([]),
@@ -463,6 +813,7 @@ var RelayFixture = z2.object({
   revoked: z2.array(RevocationRecord).default([])
 }).strict();
 var EMPTY_FIXTURE = {
+  sites: [],
   consents: [],
   devices: [],
   rosters: [],
@@ -477,6 +828,15 @@ var Projection = class {
   replace(fixture) {
     this.#fixture = RelayFixture.parse(fixture);
   }
+  /**
+   * 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) {
+    return this.#fixture.sites.find((s) => s.siteId === siteId) ?? null;
+  }
   /**
    * The device this runner id names, if a human approved it.
    *
@@ -490,7 +850,15 @@ var Projection = class {
   deviceByFingerprint(identityPublic) {
     return this.#fixture.devices.find((d) => d.device.identity === identityPublic) ?? 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, siteId) {
     const revoked = this.#fixture.revoked.some(
       (r) => r.owner === owner && r.siteId === siteId
@@ -500,6 +868,156 @@ var Projection = class {
       (c) => c.owner === owner && c.siteId === siteId
     ) ?? 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) {
+    return this.#fixture.sites.filter((site) => this.consentFor(owner, site.siteId) !== null).sort((a, b) => a.siteId < b.siteId ? -1 : 1);
+  }
+  /**
+   * 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(keyId3) {
+    return this.#fixture.sites.find(
+      (record) => keyIdOf(record.site.identity) === keyId3
+    )?.siteId ?? 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, siteId) {
+    const consent = this.consentFor(owner, siteId);
+    return consent !== null && !consent.paused;
+  }
+  /**
+   * 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) {
+    if (this.sitesFor(owner).length > 0) return false;
+    return this.#fixture.revoked.some((record) => record.owner === owner);
+  }
+  /** Whether this pair is consented and paused — what heartbeat reports. */
+  pausedFor(owner, siteId) {
+    return this.consentFor(owner, siteId)?.paused === true;
+  }
+  /**
+   * 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) {
+    const routes = /* @__PURE__ */ new Set();
+    for (const site of this.#fixture.sites) {
+      if (!this.mayRouteFor(deviceOwner, site.siteId)) continue;
+      for (const owner of this.ownersRunnableBy(deviceOwner)) {
+        if (!this.mayRouteFor(owner, site.siteId)) continue;
+        routes.add(routeKey(site.siteId, owner));
+      }
+    }
+    return routes;
+  }
+  /**
+   * 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) {
+    const owners = /* @__PURE__ */ new Set([deviceOwner]);
+    for (const roster of this.#fixture.rosters) {
+      if (roster.owner !== deviceOwner) continue;
+      for (const member of roster.members) owners.add(member);
+    }
+    return [...owners];
+  }
   /**
    * May this device's owner run work belonging to `jobOwner`?
    *
@@ -518,9 +1036,19 @@ var Projection = class {
 };
 
 // src/site-plane.ts
-import { JobStub, SealedEnvelope } from "@byollm/protocol";
+import {
+  MAX_ENVELOPE_BYTES as MAX_ENVELOPE_BYTES3,
+  PROTOCOL_VERSION as PROTOCOL_VERSION2,
+  envelopeBytes as envelopeBytes2,
+  keyId as keyId2,
+  JobStub,
+  RequestSignature as RequestSignature2,
+  SealedEnvelope,
+  verifySiteRequest
+} from "@byollm/protocol";
 import { z as z3 } from "zod";
 var EnqueueRequest = z3.object({
+  protocolVersion: z3.literal(PROTOCOL_VERSION2),
   siteId: z3.string().min(1),
   /**
    * Everything the relay learns about the job.
@@ -532,11 +1060,18 @@ var EnqueueRequest = z3.object({
   stub: JobStub
 }).strict();
 var PayloadRequest = z3.object({
+  protocolVersion: z3.literal(PROTOCOL_VERSION2),
   siteId: z3.string().min(1),
   jobId: z3.string().min(1),
   /** Sealed to the claiming device. Opaque to us and to the schema. */
   envelope: SealedEnvelope
 }).strict();
+var CancelRequest = z3.object({
+  protocolVersion: z3.literal(PROTOCOL_VERSION2),
+  siteId: z3.string().min(1),
+  jobId: z3.string().min(1)
+}).strict();
+var QueryRequest = z3.object({ siteId: z3.string().min(1) }).strict();
 var ok2 = (body) => ({ status: 200, body });
 var fail2 = (status, error, message) => ({
   status,
@@ -547,17 +1082,114 @@ var SitePlane = class {
   constructor(deps) {
     this.#deps = deps;
   }
-  enqueue(body) {
-    const parsed = EnqueueRequest.safeParse(body);
-    if (!parsed.success) {
-      return fail2(400, "bad-request", "enqueue failed schema validation");
+  /**
+   * Signature first, then the site id, then the work.
+   *
+   * The caller is whoever the signature says, verified against the key the
+   * control plane registered — never whoever the request claims. The `siteId`
+   * every request carries is then required to *match* that caller, so the two
+   * can never name different sites; a request that says one thing in its
+   * signed material and another in its body is refused rather than reconciled.
+   *
+   * Every endpoint goes through here, including the reads. That is deliberate:
+   * an authenticated write plane beside an open read plane would still hand a
+   * stranger presence, claims and lease ids, and "who is online right now" is
+   * exactly the fact a blind relay is otherwise so careful not to reveal.
+   */
+  async #authed(auth, body, schema, siteIdOf, run) {
+    const signature = RequestSignature2.safeParse(auth.signature);
+    if (!signature.success) {
+      return fail2(401, "unauthorized", "this request is not signed");
     }
-    const job = this.#deps.state.enqueue({
-      id: parsed.data.stub.id,
-      siteId: parsed.data.siteId,
-      stub: parsed.data.stub
-    });
-    return ok2({ jobId: job.id, state: job.state });
+    const siteId = signature.data.runnerId;
+    const site = this.#deps.projection.siteFor(siteId);
+    if (!site) {
+      return fail2(401, "unauthorized", "this site is not registered");
+    }
+    const acceptable = [
+      site.site.identity,
+      ...site.retiringUntil !== void 0 && this.#deps.now() < site.retiringUntil ? (site.succeeds ?? []).map((link) => link.identity.identity) : []
+    ];
+    let failure = "bad-signature";
+    for (const identityPublic of acceptable) {
+      failure = verifySiteRequest({
+        identityPublic,
+        endpoint: auth.endpoint,
+        body: auth.rawBody,
+        signature: signature.data,
+        now: this.#deps.now()
+      });
+      if (!failure) break;
+      if (failure === "stale") break;
+    }
+    if (failure === "stale") return clockSkewRefusal(this.#deps.now());
+    if (failure) return fail2(401, "unauthorized", "signature check failed");
+    const parsed = schema.safeParse(body);
+    if (!parsed.success || parsed.data === void 0) {
+      return fail2(400, "bad-request", "request failed schema validation");
+    }
+    if (siteIdOf(parsed.data) !== siteId) {
+      return fail2(403, "forbidden", "that is not your site");
+    }
+    return run(parsed.data, siteId);
+  }
+  enqueue(auth, body) {
+    return this.#authed(
+      auth,
+      body,
+      EnqueueRequest,
+      (request) => request.siteId,
+      async (request, siteId) => {
+        const registered = this.#deps.projection.siteFor(siteId);
+        if (!registered || keyId2(registered.site.identity) !== request.stub.site) {
+          return fail2(
+            403,
+            // V1-13, and one of the five the ruling itself named: an
+            // identified site claiming another site's stub is `forbidden`.
+            "forbidden",
+            "that stub does not name the site that signed it"
+          );
+        }
+        let answer;
+        try {
+          answer = await this.#deps.satisfiable?.({
+            siteId,
+            owner: request.stub.owner,
+            purpose: request.stub.purpose,
+            kind: request.stub.kind
+          });
+        } catch {
+          return fail2(
+            503,
+            "server-error",
+            "we could not check this just now \u2014 try again shortly"
+          );
+        }
+        if (answer?.verdict === "not-declared") {
+          return fail2(
+            409,
+            "purpose-not-declared",
+            `this site does not declare ${request.stub.purpose ?? "that purpose"} \u2014 declare it on Developer Sites, and the people who have already connected will each map the new slot before it routes`
+          );
+        }
+        if (answer?.verdict === "unmapped") {
+          return fail2(
+            409,
+            "slot-unsatisfiable",
+            "nobody has chosen what answers this yet"
+          );
+        }
+        const job = await this.#deps.state.enqueue({
+          id: request.stub.id,
+          siteId,
+          stub: request.stub
+        });
+        if ("refused" in job) {
+          return fail2(400, "bad-request", "that stub was not accepted");
+        }
+        return ok2({ jobId: job.id, state: job.state });
+      }
+    );
   }
   /**
    * What needs sealing, and who to seal it to.
@@ -567,56 +1199,124 @@ var SitePlane = class {
    * a participant: it tells the site an address, and what the site sends to
    * that address is unreadable on the way through.
    */
-  pending(siteId) {
-    this.#deps.state.sweep(this.#deps.now());
-    const jobs = this.#deps.state.awaiting(siteId).map((job) => ({
-      jobId: job.id,
-      // Non-null by construction: `awaiting` only returns claimed jobs. The
-      // optional chain is here so a future state-machine edit that broke that
-      // invariant would produce a missing field rather than a crash on the
-      // routing path.
-      device: job.claimedBy?.device,
-      runnerId: job.claimedBy?.runnerId,
-      leaseId: job.claimedBy?.leaseId,
-      /** So a site can decline to seal for a claim about to expire. */
-      awaitingUntil: job.awaitingUntil
-    }));
-    return ok2({ jobs });
-  }
-  payload(body) {
-    const parsed = PayloadRequest.safeParse(body);
-    if (!parsed.success) {
-      return fail2(400, "bad-request", "payload failed schema validation");
-    }
-    const job = this.#deps.state.job(parsed.data.jobId);
-    if (job?.siteId !== parsed.data.siteId) {
-      return fail2(404, "not-found", "unknown job");
-    }
-    if (job.state !== "awaiting-payload") {
-      return fail2(409, "too-late", `job is ${job.state}, not awaiting payload`);
-    }
-    job.payload = parsed.data.envelope;
-    job.state = "ready";
-    delete job.awaitingUntil;
-    return ok2({ jobId: job.id, state: job.state });
+  pending(auth, siteId) {
+    return this.#authed(
+      auth,
+      { siteId },
+      QueryRequest,
+      (request) => request.siteId,
+      async (_request, site) => {
+        await this.#deps.state.sweep();
+        const jobs = (await this.#deps.state.awaiting(site)).map((job) => ({
+          jobId: job.id,
+          // Non-null by construction: `awaiting` only returns claimed jobs.
+          // The optional chain is here so a future state-machine edit that
+          // broke that invariant would produce a missing field rather than a
+          // crash on the routing path.
+          device: job.claimedBy?.device,
+          runnerId: job.claimedBy?.runnerId,
+          leaseId: job.claimedBy?.leaseId,
+          /** So a site can decline to seal for a claim about to expire. */
+          awaitingUntil: job.awaitingUntil,
+          /**
+           * When the *grant* ends — cloud_008 §0.6.
+           *
+           * Distinct from `awaitingUntil`, which bounds how long this relay
+           * waits for the site to seal. A site adopting the lease into its own
+           * records needs the lease's clock; given the other one it recorded a
+           * grant that expired in seconds, then refused the device's own
+           * result for want of a matching lease.
+           */
+          leaseExpiresAt: job.claimedBy?.leaseExpiresAt
+        }));
+        return ok2({ jobs });
+      }
+    );
+  }
+  /**
+   * The site withdraws a job — cloud_008 §2.2.
+   *
+   * Signed and site-scoped like every other site-plane call. A cancellation
+   * is not a delete: a device already running the job has to be told, and it
+   * hears at its next heartbeat.
+   */
+  cancel(auth, body) {
+    return this.#authed(
+      auth,
+      body,
+      CancelRequest,
+      (request) => request.siteId,
+      async (request, siteId) => {
+        const cancelled = await this.#deps.state.cancel({
+          jobId: request.jobId,
+          siteId
+        });
+        return ok2({ cancelled });
+      }
+    );
+  }
+  payload(auth, body) {
+    return this.#authed(
+      auth,
+      body,
+      PayloadRequest,
+      (request) => request.siteId,
+      async (request, siteId) => {
+        const bytes = envelopeBytes2(request.envelope);
+        if (bytes > MAX_ENVELOPE_BYTES3) return tooLargeRefusal(bytes);
+        const sealed = await this.#deps.state.seal({
+          jobId: request.jobId,
+          siteId,
+          envelope: request.envelope
+        });
+        if ("refused" in sealed) {
+          return sealed.refused === "not-found" ? fail2(404, "not-found", "unknown job") : fail2(
+            409,
+            "too-late",
+            `job is ${sealed.was ?? "gone"}, not awaiting payload`
+          );
+        }
+        return ok2({ jobId: request.jobId, state: sealed.state });
+      }
+    );
   }
   /** Sealed results, for the site to open and verify. */
-  results(siteId) {
-    const jobs = this.#deps.state.finished(siteId).map((job) => ({
-      jobId: job.id,
-      envelope: job.result,
-      disposition: job.disposition,
-      runnerId: job.claimedBy?.runnerId,
-      /** The grant the site adopted, so it can complete against it. */
-      leaseId: job.claimedBy?.leaseId,
-      /**
-       * Which device ran it, so the site can verify the signature against the
-       * key it was told to seal to — and so `RESULT_PROVENANCE` can name a
-       * foreign device rather than guessing (cloud_004 §11.2).
-       */
-      device: job.claimedBy?.device
-    }));
-    return ok2({ jobs });
+  results(auth, siteId) {
+    return this.#authed(
+      auth,
+      { siteId },
+      QueryRequest,
+      (request) => request.siteId,
+      async (_request, site) => {
+        const jobs = (await this.#deps.state.finished(site)).map((job) => ({
+          jobId: job.id,
+          envelope: job.result,
+          disposition: job.disposition,
+          runnerId: job.claimedBy?.runnerId,
+          /** The grant the site adopted, so it can complete against it. */
+          leaseId: job.claimedBy?.leaseId,
+          /**
+           * Which device ran it, so the site can verify the signature against
+           * the key it was told to seal to — and so `PROVENANCE_NAMES_DEVICE` can
+           * name a foreign device rather than guessing (cloud_004 §11.2).
+           */
+          device: job.claimedBy?.device,
+          /**
+           * Whose machine ran it — cloud_008 §2.5, finding 41.
+           *
+           * The relay has held this since the claim: `claimedBy.owner` is the
+           * owner id the *projection* supplied, in the same namespace the
+           * direct plane's `runnerOwner` uses. The cloud lane was filling that
+           * field with `keyId(device.identity)` instead — a key id where every
+           * other plane puts a user id, so an app comparing provenance across
+           * lanes compared two namespaces for equality and got `false` for
+           * the same person.
+           */
+          runnerOwner: job.claimedBy?.owner
+        }));
+        return ok2({ jobs });
+      }
+    );
   }
 };
 
@@ -628,19 +1328,34 @@ var Relay = class {
   #site;
   #now;
   #basePath;
+  #debug;
   constructor(options) {
-    this.state = new RelayState();
+    this.state = options.store ?? new RelayState({ now: options.now ?? Date.now });
     this.projection = new Projection(options.fixture);
     this.#now = options.now ?? Date.now;
     this.#basePath = (options.basePath ?? "/byollm").replace(/\/+$/, "");
+    this.#debug = options.debug ?? false;
     this.#daemon = new DaemonPlane({
       state: this.state,
       projection: this.projection,
       now: this.#now,
       leaseMs: options.leaseMs ?? 6e4,
-      siteId: options.siteId
+      pairingCodes: options.pairingCodes ?? new MemoryPairingCodes(() => this.#now()),
+      ...options.verificationUrl === void 0 ? {} : { verificationUrl: options.verificationUrl },
+      ...options.controlPlanePublic === void 0 ? {} : { controlPlanePublic: options.controlPlanePublic },
+      ...options.authorGrant === void 0 ? {} : { authorGrant: options.authorGrant }
+    });
+    if (options.controlPlanePublic !== void 0 && options.authorGrant === void 0) {
+      throw new Error(
+        "controlPlanePublic is set but authorGrant is not: devices would be told to expect signed grants that nothing here can produce, and would refuse every job"
+      );
+    }
+    this.#site = new SitePlane({
+      state: this.state,
+      projection: this.projection,
+      now: this.#now,
+      ...options.satisfiable === void 0 ? {} : { satisfiable: options.satisfiable }
     });
-    this.#site = new SitePlane({ state: this.state, now: this.#now });
   }
   /** Replace the projection — a control-plane push, or a fixture edit. */
   project(fixture) {
@@ -655,49 +1370,96 @@ var Relay = class {
    * site vanished should return to the queue without waiting for someone to
    * ask about it.
    */
-  sweep() {
-    return { requeued: this.state.sweep(this.#now()).map((j) => j.id) };
+  async sweep() {
+    const requeued = await this.state.sweep();
+    return { requeued: requeued.map((j) => j.id) };
   }
   /** The whole HTTP surface. */
   async handle(request) {
     const url = new URL(request.url);
     const path = url.pathname;
     if (path === "/debug" || path === `${this.#basePath}/debug`) {
-      return new Response(debugPage(this.state, this.#now()), {
-        headers: { "content-type": "text/html; charset=utf-8" }
-      });
+      const siteId = url.searchParams.get("site");
+      if (!this.#debug) {
+        return new Response(JSON.stringify({ error: "not-found" }), {
+          status: 404,
+          headers: { "content-type": "application/json" }
+        });
+      }
+      if (siteId === null || this.projection.siteFor(siteId) === null) {
+        return new Response(JSON.stringify({ error: "bad-request" }), {
+          status: 400,
+          headers: { "content-type": "application/json" }
+        });
+      }
+      return new Response(
+        await debugPage(this.state, this.#now(), {
+          siteId,
+          consents: (owner) => this.projection.consentFor(owner, siteId) !== null
+        }),
+        { headers: { "content-type": "text/html; charset=utf-8" } }
+      );
     }
     const rawBody = request.method === "POST" ? await request.text() : "";
     const body = rawBody === "" ? void 0 : safeJson(rawBody);
+    const endpoint = path.slice(path.lastIndexOf("/") + 1);
     const auth = {
-      endpoint: path.slice(path.lastIndexOf("/") + 1),
+      endpoint,
+      rawBody,
+      signature: signatureFrom(request.headers, "x-byollm-runner")
+    };
+    if (path.startsWith("/byollm/") || path.startsWith("/relay/")) {
+      const refusal = checkProtocolVersion({
+        protocolVersion: declaredVersion({ body, query: url.searchParams })
+      });
+      if (refusal) return json({ status: 400, body: refusal });
+    }
+    const siteAuth = {
+      endpoint,
       rawBody,
-      signature: signatureFrom(request.headers)
+      signature: signatureFrom(request.headers, "x-byollm-site")
     };
-    if (path === "/relay/site/enqueue") return json(this.#site.enqueue(body));
-    if (path === "/relay/site/payload") return json(this.#site.payload(body));
+    if (path === "/relay/site/enqueue") {
+      return json(await this.#site.enqueue(siteAuth, body));
+    }
+    if (path === "/relay/site/payload") {
+      return json(await this.#site.payload(siteAuth, body));
+    }
+    if (path === "/relay/site/cancel") {
+      return json(await this.#site.cancel(siteAuth, body));
+    }
     if (path === "/relay/site/pending") {
-      return json(this.#site.pending(url.searchParams.get("siteId") ?? ""));
+      return json(
+        await this.#site.pending(
+          siteAuth,
+          url.searchParams.get("siteId") ?? ""
+        )
+      );
     }
     if (path === "/relay/site/results") {
-      return json(this.#site.results(url.searchParams.get("siteId") ?? ""));
+      return json(
+        await this.#site.results(
+          siteAuth,
+          url.searchParams.get("siteId") ?? ""
+        )
+      );
     }
     if (!path.startsWith(`${this.#basePath}/`)) {
       return json({ status: 404, body: { error: "not-found" } });
     }
     switch (auth.endpoint) {
       case "pair":
-        return json(this.#daemon.pair(body));
+        return json(await this.#daemon.pair(body));
       case "claim":
-        return json(this.#daemon.claim(auth, body));
+        return json(await this.#daemon.claim(auth, body));
       case "fetch":
-        return json(this.#daemon.fetch(auth, body));
+        return json(await this.#daemon.fetch(auth, body));
       case "result":
-        return json(this.#daemon.result(auth, body));
+        return json(await this.#daemon.result(auth, body));
       case "heartbeat":
-        return json(this.#daemon.heartbeat(auth, body));
+        return json(await this.#daemon.heartbeat(auth, body));
       case "release":
-        return json(this.#daemon.release(auth, body));
+        return json(await this.#daemon.release(auth, body));
       default:
         return json({ status: 404, body: { error: "not-found" } });
     }
@@ -710,8 +1472,8 @@ function safeJson(raw) {
     return void 0;
   }
 }
-function signatureFrom(headers) {
-  const runnerId = headers.get("x-byollm-runner");
+function signatureFrom(headers, callerHeader) {
+  const runnerId = headers.get(callerHeader);
   const issuedAt = headers.get("x-byollm-issued-at");
   const signature = headers.get("x-byollm-signature");
   if (runnerId === null || issuedAt === null || signature === null) {
@@ -728,12 +1490,20 @@ export {
   ConsentRecord,
   DeviceRecord,
   EMPTY_FIXTURE,
+  MAX_OUTSTANDING_PAIRINGS,
+  MemoryPairingCodes,
+  PAIRING_BUSY_MESSAGE,
+  PAIRING_CODE_TTL_MS,
   Projection,
   Relay,
   RelayFixture as RelayFixtureSchema,
   RelayState,
   RevocationRecord,
   RosterRecord,
-  debugPage
+  SiteRecord,
+  debugPage,
+  newDeviceCode,
+  newUserCode,
+  routeKey
 };
 //# sourceMappingURL=index.js.map