@byollm/relay 0.1.0-alpha.8 → 0.1.0-alpha.80

package/dist/index.js

@@ -1,128 +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.
-   *
-   * **Idempotent by job id, and that is a security property rather than a
-   * convenience.** Site-plane calls are authenticated by signature, and
-   * byollm_009 §4.2's argument for signing the request instead of a
-   * server-issued nonce rests entirely on every write being idempotent per the
-   * instance it names. This one was not: re-enqueueing a known id built a
-   * fresh `queued` job over the top of the old one, discarding a live claim,
-   * its lease and any payload the site had already sealed to a device. A
-   * replayed enqueue inside the two-minute freshness window was therefore a
-   * way to yank a job back from the machine running it — the `release` bug of
-   * §4.2, rediscovered on the other plane.
-   *
-   * So a known id returns what is already routing, unchanged. A site that
-   * restarts and republishes its queue is the normal case, and it must not
-   * disturb work in flight.
-   */
-  enqueue(input) {
-    const existing = this.#jobs.get(input.id);
-    if (existing) return existing;
-    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);
+    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");
   }
-  everyone() {
-    return [...this.#presence.values()];
+  byDeviceCode(deviceCode) {
+    return Promise.resolve(this.#live(this.#byDevice.get(deviceCode)));
   }
-  /**
-   * 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;
-  }
-  /**
-   * 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 }
@@ -142,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");
@@ -150,16 +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 site = this.#deps.projection.siteFor(this.#deps.siteId);
-    if (!site) {
-      return fail(403, "unauthorized", "this site is not registered");
+    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
@@ -167,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: site.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,
@@ -205,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.revokedDevice(known.runnerId);
+    if (revoked && options.allowRevoked !== true) {
       return fail(403, "revoked", "routing for this runner has been revoked");
     }
     known.lastSeenAt = this.#deps.now();
@@ -216,43 +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 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 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 (job.siteId !== this.#deps.siteId) continue;
-        if (!kinds.has(job.stub.kind)) continue;
-        if (!this.#deps.projection.mayRunFor(device.owner, job.stub.owner)) {
+      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 });
     });
   }
   /**
@@ -266,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 });
     });
   }
   /**
@@ -292,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) {
@@ -312,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 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 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 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 });
     });
   }
@@ -386,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">
@@ -426,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>
@@ -434,7 +701,12 @@ ${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. */
@@ -446,13 +718,61 @@ var SiteRecord = z2.object({
    * signatures and seals nothing. This is the key-exchange half of consent
    * (cloud_004 §3), and both endpoints pin what they receive.
    */
-  site: PublicIdentity2
+  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)
+  siteId: z2.string().min(1),
+  /**
+   * The consent stands, and nothing routes under it — cloud_008 finding 48.
+   *
+   * 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.
+   */
+  paused: z2.boolean().default(false)
 }).strict();
 var RosterRecord = z2.object({
   /** Stable id for the group, used only inside the relay. */
@@ -468,7 +788,23 @@ var DeviceRecord = z2.object({
   /** The id the control plane assigned — the device does not choose it. */
   runnerId: z2.string().min(1),
   /** The keys a human compared a fingerprint of before approving. */
-  device: PublicIdentity2
+  device: PublicIdentity2,
+  /**
+   * Whether this device — this one — has been revoked.
+   *
+   * Optional because a control plane that predates it says nothing, and
+   * saying nothing must read as "not revoked": the alternative is a missing
+   * field stopping every device on the fleet, which is the failure mode this
+   * whole entry exists to end.
+   *
+   * Device-scoped by ruling (2026-09-03). Revocation used to be answered
+   * from the owner's route-revocation list, so an account with any
+   * revocation on record and no live site consents refused **every** device
+   * it owned — including one paired thirty seconds earlier, whose daemon
+   * then deleted its own pairings file. Revoking an experiment and pairing a
+   * replacement, which is the ordinary first hour, killed the replacement.
+   */
+  revoked: z2.boolean().optional()
 }).strict();
 var RevocationRecord = z2.object({ owner: z2.string().min(1), siteId: z2.string().min(1) }).strict();
 var RelayFixture = z2.object({
@@ -530,7 +866,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
@@ -540,6 +884,167 @@ 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 device* been revoked — ruled 2026-09-03?
+   *
+   * This method has now been wrong in both directions, which is why it reads
+   * the way it does.
+   *
+   * First it answered "is there nothing to serve", so an empty or half-written
+   * projection was indistinguishable from a human's decision and cost every
+   * daemon its pinned keys. The fix asked for evidence — a revocation on
+   * record — but asked it of the **owner**, and added
+   * `sitesFor(owner).length > 0` as a softener. That produced the opposite
+   * failure: an account with any revocation and no live consents refused every
+   * device it had, one paired seconds ago included.
+   *
+   * So: revocation is a fact about one device, never a mood about an owner.
+   * This looks up the device that signed the request and reports what the
+   * control plane says about *it*.
+   *
+   * The softener is gone with it. A guard whose answer changes with unrelated
+   * state is not a guard — enabling a site must never be the thing that
+   * un-revokes a machine, and under the old shape it was exactly that.
+   *
+   * A projection that knows nothing about a runner still says nothing here;
+   * `deviceFor` is what refuses an unknown one, with 401, which is a different
+   * sentence for a different situation.
+   *
+   * REVOCATION_IMMEDIATE is untouched: revoking device A still stops A on its
+   * next call. It stops stopping B and C.
+   */
+  revokedDevice(runnerId) {
+    const device = this.#fixture.devices.find(
+      (record) => record.runnerId === runnerId
+    );
+    return device?.revoked === true;
+  }
+  /** 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`?
    *
@@ -559,6 +1064,10 @@ var Projection = class {
 
 // src/site-plane.ts
 import {
+  MAX_ENVELOPE_BYTES as MAX_ENVELOPE_BYTES3,
+  PROTOCOL_VERSION as PROTOCOL_VERSION2,
+  envelopeBytes as envelopeBytes2,
+  keyId as keyId2,
   JobStub,
   RequestSignature as RequestSignature2,
   SealedEnvelope,
@@ -566,6 +1075,7 @@ import {
 } 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.
@@ -577,11 +1087,17 @@ 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) => ({
@@ -607,7 +1123,7 @@ var SitePlane = class {
    * 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.
    */
-  #authed(auth, body, schema, siteIdOf, run) {
+  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");
@@ -617,23 +1133,30 @@ var SitePlane = class {
     if (!site) {
       return fail2(401, "unauthorized", "this site is not registered");
     }
-    const failure = verifySiteRequest({
-      identityPublic: site.site.identity,
-      endpoint: auth.endpoint,
-      body: auth.rawBody,
-      signature: signature.data,
-      now: this.#deps.now()
-    });
+    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, "unauthorized", "that is not your site");
-    }
-    if (siteId !== this.#deps.routesFor) {
-      return fail2(403, "unauthorized", "this relay does not route for you");
+      return fail2(403, "forbidden", "that is not your site");
     }
     return run(parsed.data, siteId);
   }
@@ -643,12 +1166,61 @@ var SitePlane = class {
       body,
       EnqueueRequest,
       (request) => request.siteId,
-      (request, siteId) => {
-        const job = this.#deps.state.enqueue({
+      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"
+          );
+        }
+        if (answer?.verdict === "waiting") {
+          return fail2(
+            409,
+            "slot-waiting",
+            "nothing can answer this right now \u2014 try again later"
+          );
+        }
+        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 });
       }
     );
@@ -667,9 +1239,9 @@ var SitePlane = class {
       { siteId },
       QueryRequest,
       (request) => request.siteId,
-      (_request, site) => {
-        this.#deps.state.sweep(this.#deps.now());
-        const jobs = this.#deps.state.awaiting(site).map((job) => ({
+      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
@@ -679,34 +1251,66 @@ var SitePlane = class {
           runnerId: job.claimedBy?.runnerId,
           leaseId: job.claimedBy?.leaseId,
           /** So a site can decline to seal for a claim about to expire. */
-          awaitingUntil: job.awaitingUntil
+          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,
-      (request, siteId) => {
-        const job = this.#deps.state.job(request.jobId);
-        if (job?.siteId !== siteId) {
-          return fail2(404, "not-found", "unknown job");
-        }
-        if (job.state !== "awaiting-payload") {
-          return fail2(
+      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 ${job.state}, not awaiting payload`
+            `job is ${sealed.was ?? "gone"}, not awaiting payload`
           );
         }
-        job.payload = request.envelope;
-        job.state = "ready";
-        delete job.awaitingUntil;
-        return ok2({ jobId: job.id, state: job.state });
+        return ok2({ jobId: request.jobId, state: sealed.state });
       }
     );
   }
@@ -717,8 +1321,8 @@ var SitePlane = class {
       { siteId },
       QueryRequest,
       (request) => request.siteId,
-      (_request, site) => {
-        const jobs = this.#deps.state.finished(site).map((job) => ({
+      async (_request, site) => {
+        const jobs = (await this.#deps.state.finished(site)).map((job) => ({
           jobId: job.id,
           envelope: job.result,
           disposition: job.disposition,
@@ -727,10 +1331,22 @@ var SitePlane = class {
           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
+           * 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
+          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 });
       }
@@ -746,23 +1362,33 @@ 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,
-      routesFor: options.siteId
+      ...options.satisfiable === void 0 ? {} : { satisfiable: options.satisfiable }
     });
   }
   /** Replace the projection — a control-plane push, or a fixture edit. */
@@ -778,17 +1404,35 @@ 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);
@@ -798,25 +1442,40 @@ var Relay = class {
       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, "x-byollm-site")
     };
     if (path === "/relay/site/enqueue") {
-      return json(this.#site.enqueue(siteAuth, body));
+      return json(await this.#site.enqueue(siteAuth, body));
     }
     if (path === "/relay/site/payload") {
-      return json(this.#site.payload(siteAuth, body));
+      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(siteAuth, url.searchParams.get("siteId") ?? "")
+        await this.#site.pending(
+          siteAuth,
+          url.searchParams.get("siteId") ?? ""
+        )
       );
     }
     if (path === "/relay/site/results") {
       return json(
-        this.#site.results(siteAuth, url.searchParams.get("siteId") ?? "")
+        await this.#site.results(
+          siteAuth,
+          url.searchParams.get("siteId") ?? ""
+        )
       );
     }
     if (!path.startsWith(`${this.#basePath}/`)) {
@@ -824,17 +1483,17 @@ var Relay = class {
     }
     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" } });
     }
@@ -865,6 +1524,10 @@ export {
   ConsentRecord,
   DeviceRecord,
   EMPTY_FIXTURE,
+  MAX_OUTSTANDING_PAIRINGS,
+  MemoryPairingCodes,
+  PAIRING_BUSY_MESSAGE,
+  PAIRING_CODE_TTL_MS,
   Projection,
   Relay,
   RelayFixture as RelayFixtureSchema,
@@ -872,6 +1535,9 @@ export {
   RevocationRecord,
   RosterRecord,
   SiteRecord,
-  debugPage
+  debugPage,
+  newDeviceCode,
+  newUserCode,
+  routeKey
 };
 //# sourceMappingURL=index.js.map