@byollm/server 0.1.0-alpha.1 → 0.1.0-alpha.100

package/dist/index.js

@@ -1,63 +1,433 @@
 import {
   ByollmHandlers,
   SERVED_PROTOCOL_VERSION,
-  bearerFrom,
   createFetchHandler,
+  deadlineFor,
   generateDeviceCode,
   generateJobId,
+  generateLeaseId,
   generateRunnerId,
-  generateRunnerToken,
   generateUserCode,
   hashSecret,
+  openSealedOutcome,
+  resealForDevice,
   routeEndpoint,
-  secretsMatch
-} from "./chunk-HL6EYHQ7.js";
+  secretsMatch,
+  signatureFrom
+} from "./chunk-36Y77FUD.js";
 import {
   NoRunnerAvailableError,
   PollingDelivery,
   ResultTimeoutError
-} from "./chunk-7RKXFPBZ.js";
+} from "./chunk-YBNLLQZT.js";
 
 // src/app.ts
 import {
+  ENVELOPE_MAX_AGE_MS,
+  KindedPayload,
+  keyId as keyId2,
+  payloadTextLength,
+  publicIdentityOf as publicIdentityOf2,
+  seal,
+  sizeClassOf,
   backendDescriptor,
   matchAudience
 } from "@byollm/protocol";
+
+// src/cloud.ts
+import {
+  PROTOCOL_VERSION,
+  keyId,
+  open,
+  publicIdentityOf,
+  provenanceFor,
+  signSiteRequest
+} from "@byollm/protocol";
+var RelayUnavailable = class extends Error {
+  retryable;
+  /** The protocol's own code, when the relay sent one. */
+  code;
+  constructor(message, retryable, code) {
+    super(message);
+    this.name = "RelayUnavailable";
+    this.retryable = retryable;
+    this.code = code;
+  }
+};
+var EnqueueRefused = class extends Error {
+  /** `purpose-not-declared` or `slot-unsatisfiable`. */
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "EnqueueRefused";
+    this.code = code;
+  }
+};
+var RETRYABLE_AT_ENQUEUE = /* @__PURE__ */ new Set(["not-ready"]);
+var ENQUEUE_ENDPOINT = "enqueue";
+var CloudLane = class {
+  #options;
+  #store;
+  #siteKeys;
+  #now;
+  #fetch;
+  constructor(deps) {
+    this.#options = deps.options;
+    this.#store = deps.store;
+    this.#siteKeys = deps.siteKeys;
+    this.#now = deps.now;
+    this.#fetch = deps.options.fetch ?? globalThis.fetch;
+  }
+  /**
+   * Publish a job's stub for routing.
+   *
+   * The stub and nothing else — byollm_009 §6 makes that exhaustive by
+   * construction, so this cannot leak a payload even by mistake: there is no
+   * field on `JobStub` to put one in.
+   */
+  async publish(record) {
+    const stub = {
+      id: record.id,
+      kind: record.kind,
+      owner: record.owner,
+      // This site, by its identity key id — Amendment A §A.3. The relay
+      // already knows which site it is routing for, so this discloses nothing
+      // new to it; what it adds is that the *daemon* can check the stub
+      // against the envelope's `senderKeyId` without asking the relay.
+      site: keyId(publicIdentityOf(this.#siteKeys).identity),
+      audience: record.audience,
+      // `audienceAllow` is deliberately **not** published — cloud_008 §0.2.
+      //
+      // It is a list of the people who may run this job, and on the direct
+      // plane that is unremarkable: the site authored the list and the site is
+      // the upstream, so the party receiving it already has it. Through a
+      // relay it is a third party, and byollm_009 §6's enumerated metadata —
+      // "exhaustive and normative… what an upstream can see, stated as a
+      // commitment" — does not include it. It was reaching the relay on every
+      // named-audience job.
+      //
+      // Nothing is lost by withholding it, which is why this is a Tier 0 fix
+      // rather than a trade. `matchAudience` treats it as a *narrowing*:
+      // `job.audienceAllow !== undefined && !includes(daemon.owner)` refuses,
+      // and its absence simply falls through to the checks that actually
+      // enforce — the daemon's own allowlist (`NAMED_LOCAL_ALLOWLIST`) and the
+      // backend's offer scope. On this lane the relay narrows too, from the
+      // control plane's rosters. The enforcement was never here.
+      ...record.purpose === void 0 ? {} : { purpose: record.purpose },
+      sizeClass: record.sizeClass,
+      streaming: false,
+      // The relay needs *a* deadline to bound routing. A job without one gets
+      // the envelope's, which is the outer bound on how long the ciphertext
+      // is worth carrying — never longer than the work could possibly matter.
+      // The same fallback the direct plane uses — cloud_008 Tier 4, finding
+      // 31. This said `createdAt + ENVELOPE_TTL_FALLBACK`, a local constant
+      // whose value happened to equal `ENVELOPE_MAX_AGE_MS`; the direct plane
+      // said `(claimableAt ?? now) + ttlMs`. One field, two meanings, and a
+      // job that was blocked on a dependency got a deadline measured from
+      // when it was *created* on one lane and from when it became *claimable*
+      // on the other.
+      deadlineAt: deadlineFor(record, this.#now())
+    };
+    await this.#post("enqueue", {
+      siteId: this.#options.siteId,
+      stub
+    });
+  }
+  /**
+   * Withdraw a job at the relay — cloud_008 §2.2.
+   *
+   * `app.cancel()` marks the site's own row terminal, which stops the *next*
+   * seal. It cannot stop a device that is already running the work, because
+   * on this lane the site is not the upstream: only the relay talks to the
+   * daemon, and it answered `cancel: []` unconditionally.
+   *
+   * So the cancellation has to travel. The relay marks the job, stops
+   * offering it, and names it to the holding device at its next heartbeat —
+   * the same path the direct plane has always had, arriving one hop later.
+   */
+  async cancel(jobId) {
+    await this.#post("cancel", { siteId: this.#options.siteId, jobId });
+  }
+  /**
+   * One cycle: seal for anything claimed, collect anything finished.
+   *
+   * Idempotent and safe to call as often as you like. Exposed as a single
+   * cycle rather than hidden behind a timer so a caller decides its own
+   * cadence — a serverless site runs it on a cron, a long-lived one on an
+   * interval, and a test runs it exactly when it means to.
+   */
+  async pump() {
+    const sealed = [];
+    const refused = [];
+    const completed = [];
+    try {
+      return await this.#cycle(sealed, refused, completed);
+    } catch (error) {
+      if (error instanceof RelayUnavailable && error.retryable) {
+        return { sealed, completed, refused, deferred: error.message };
+      }
+      throw error;
+    }
+  }
+  async #cycle(sealed, refused, completed) {
+    const pending = await this.#get("pending");
+    for (const claim of pending.jobs) {
+      const record = await this.#store.get(claim.jobId);
+      if (!record) continue;
+      const resealed = await resealForDevice({
+        siteKeys: this.#siteKeys,
+        job: {
+          id: record.id,
+          envelope: record.envelope,
+          createdAt: record.createdAt
+        },
+        device: claim.device
+      });
+      if (!resealed.ok) {
+        refused.push(claim.jobId);
+        continue;
+      }
+      const adopted = await this.#store.adopt({
+        jobId: claim.jobId,
+        leaseId: claim.leaseId,
+        expiresAt: claim.leaseExpiresAt,
+        now: this.#now()
+      });
+      if (!adopted) {
+        refused.push(claim.jobId);
+        continue;
+      }
+      await this.#post("payload", {
+        siteId: this.#options.siteId,
+        jobId: claim.jobId,
+        envelope: resealed.envelope
+      });
+      sealed.push(claim.jobId);
+    }
+    const finished = await this.#get("results");
+    for (const done of finished.jobs) {
+      const record = await this.#store.get(done.jobId);
+      if (!record || record.state === "ok" || record.state === "error") {
+        continue;
+      }
+      const outcome = await this.#openResult(done);
+      if (!outcome) {
+        refused.push(done.jobId);
+        continue;
+      }
+      await this.#store.complete({
+        jobId: done.jobId,
+        // The relay named the device; the signature above proved it — §3.6.
+        runnerId: done.runnerId,
+        // The grant, not the machine: this site never paired with the device
+        // that ran it, and the signature it verified above is the stronger
+        // claim about who did.
+        holder: { by: "lease", leaseId: done.leaseId },
+        outcome: outcome.outcome,
+        provenance: provenanceFor({
+          audience: record.audience,
+          runnerId: done.runnerId,
+          // The owner, from the relay's own record of who claimed it — not a
+          // key id. cloud_008 §2.5: this said `keyId(device.identity)`, which
+          // put a key id where the direct plane puts a user id, so an app
+          // comparing provenance across lanes compared two namespaces and got
+          // `false` for the same person. The device's key is still what the
+          // signature was verified against, above; that is a different
+          // question from whose machine it is.
+          runnerOwner: done.runnerOwner,
+          // From the envelope, not invented — cloud_008 §2.5. These were
+          // hardcoded `"http"` and `"unknown"` because the daemon's declared
+          // values stopped at the relay, which is right: a blind relay acts
+          // on neither. Sealing them carries them past it untouched.
+          backendClass: outcome.ran.backendClass,
+          model: outcome.ran.model
+        }),
+        now: this.#now()
+      });
+      completed.push(done.jobId);
+    }
+    return { sealed, completed, refused };
+  }
+  /**
+   * Open a sealed result and verify it came from the device that claimed it.
+   *
+   * The relay says which device ran the job; this checks that claim against a
+   * signature the relay cannot produce. A relay that named the wrong device
+   * gets a refusal, not a stored result — which is what keeps `RELAY_BLIND`
+   * from quietly becoming `RELAY_TRUSTED`.
+   */
+  async #openResult(done) {
+    const opened = await open({
+      envelope: done.envelope,
+      recipientKeys: this.#siteKeys,
+      senderIdentityPublic: done.device.identity,
+      expected: {
+        jobId: done.jobId,
+        senderKeyId: keyId(done.device.identity),
+        recipientKeyId: keyId(publicIdentityOf(this.#siteKeys).identity),
+        direction: "result"
+      }
+    });
+    if (!opened.ok) return null;
+    const outcome = openSealedOutcome({
+      plaintext: opened.plaintext,
+      disposition: done.disposition
+    });
+    return outcome.ok ? outcome.value : null;
+  }
+  /**
+   * Sign a site-plane call with this site's identity key.
+   *
+   * The same scheme the daemon uses against an upstream, because the site is
+   * in the same position: an outbound caller whose key the relay already holds
+   * for other reasons. Nothing else authenticates this plane — a relay that
+   * took the `siteId` in a body at face value would let anyone enqueue work in
+   * a site's name and read who claimed it.
+   */
+  #headers(endpoint, rawBody) {
+    const signature = signSiteRequest(this.#siteKeys, {
+      endpoint,
+      siteId: this.#options.siteId,
+      issuedAt: this.#now(),
+      body: rawBody
+    });
+    return {
+      "x-byollm-site": this.#options.siteId,
+      "x-byollm-issued-at": String(signature.issuedAt),
+      "x-byollm-signature": signature.signature
+    };
+  }
+  /**
+   * A relay answer, checked before it is believed — alpha.31.
+   *
+   * The bug this closes is one line long and its shape is general: a response
+   * body used without looking at the status. The daemon's client has always
+   * done this properly (`client.ts` maps every status to a typed refusal); the
+   * site's lane parsed JSON and hoped.
+   *
+   * Two classes, because they need opposite handling. **Retryable** — 503 from
+   * a draining pod, 429, 5xx, and the protocol's own `not-ready` — means the
+   * work is still there and this cycle should end quietly. **Refused** — a bad
+   * signature, an unknown site, a version this relay does not speak — will
+   * still be true in five seconds, and swallowing it would leave a site
+   * silently disconnected from its own users.
+   */
+  async #answer(response, endpoint) {
+    if (response.ok) return response.json();
+    let code = "";
+    let message;
+    try {
+      const body = await response.json();
+      code = body.error ?? "";
+      message = body.message ?? "";
+    } catch {
+      message = `HTTP ${String(response.status)}`;
+    }
+    const retryable = response.status >= 500 || response.status === 429 || code === "not-ready" || code === "server-error";
+    if (endpoint === ENQUEUE_ENDPOINT && response.status === 409 && !RETRYABLE_AT_ENQUEUE.has(code)) {
+      throw new EnqueueRefused(message, code);
+    }
+    throw new RelayUnavailable(
+      `${endpoint}: ${code || "refused"} \u2014 ${message}`,
+      retryable,
+      code
+    );
+  }
+  async #post(endpoint, body) {
+    const rawBody = JSON.stringify({
+      protocolVersion: PROTOCOL_VERSION,
+      ...body
+    });
+    const response = await this.#fetch(
+      `${this.#options.relayOrigin}/relay/site/${endpoint}`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...this.#headers(endpoint, rawBody)
+        },
+        body: rawBody
+      }
+    );
+    return this.#answer(response, endpoint);
+  }
+  async #get(endpoint) {
+    const url = `${this.#options.relayOrigin}/relay/site/${endpoint}?siteId=${encodeURIComponent(this.#options.siteId)}&protocolVersion=${encodeURIComponent(PROTOCOL_VERSION)}`;
+    const response = await this.#fetch(url, {
+      headers: this.#headers(endpoint, "")
+    });
+    return this.#answer(response, endpoint);
+  }
+};
+
+// src/app.ts
 var DEFAULT_LIVENESS_MS = 35e3;
+var ENQUEUE_OPTIONS = Object.freeze({
+  kind: true,
+  payload: true,
+  owner: true,
+  audience: true,
+  purpose: true,
+  audienceAllow: true,
+  dependsOn: true,
+  ttlMs: true,
+  deadlineAt: true,
+  id: true
+});
 var ByollmApp = class {
   #store;
+  #siteKeys;
   #now;
   #livenessMs;
   #delivery;
+  /** Present only in the cloud lane; the site's side of the relay. */
+  cloud;
   constructor(options) {
     this.#store = options.store;
+    this.#siteKeys = options.siteKeys;
     this.#now = options.now ?? Date.now;
     this.#livenessMs = options.livenessMs ?? DEFAULT_LIVENESS_MS;
+    this.cloud = options.lane === void 0 ? void 0 : new CloudLane({
+      options: options.lane,
+      store: options.store,
+      siteKeys: options.siteKeys,
+      now: this.#now
+    });
     const deps = {
       ...options.noRunnerGraceMs === void 0 ? {} : { graceMs: options.noRunnerGraceMs },
       read: (jobId) => this.result(jobId),
-      availability: async (jobId) => {
-        const job = await this.#store.get(jobId);
-        if (!job)
-          return { available: false, reason: "unknown-job", blocked: false };
-        if (job.claimableAt === null) {
-          return { available: true, blocked: true };
-        }
-        const availability = await this.runnerAvailability({
-          kind: job.kind,
-          owner: job.owner,
-          audience: job.audience,
-          ...job.audienceAllow === void 0 ? {} : { audienceAllow: job.audienceAllow }
-        });
-        return {
-          available: availability.available,
-          ...availability.reason === void 0 ? {} : { reason: availability.reason },
-          blocked: false
-        };
-      }
+      ...this.cloud !== void 0 ? {} : { availability: this.#availabilityFor() }
     };
     this.#delivery = options.delivery?.(deps) ?? new PollingDelivery(deps);
   }
+  /**
+   * The no-runner instrument, for a lane that can actually see runners.
+   *
+   * A method rather than an inline closure so the branch above reads as one
+   * decision — whether this deployment has the instrument at all — instead of
+   * a conditional wrapped around thirty lines of body.
+   */
+  #availabilityFor() {
+    return async (jobId) => {
+      const job = await this.#store.get(jobId);
+      if (!job)
+        return { available: false, reason: "unknown-job", blocked: false };
+      if (job.claimableAt === null) {
+        return { available: true, blocked: true };
+      }
+      const availability = await this.runnerAvailability({
+        kind: job.kind,
+        owner: job.owner,
+        audience: job.audience,
+        ...job.audienceAllow === void 0 ? {} : { audienceAllow: job.audienceAllow }
+      });
+      return {
+        available: availability.available,
+        ...availability.reason === void 0 ? {} : { reason: availability.reason },
+        blocked: false
+      };
+    };
+  }
   /**
    * Enqueue a job.
    *
@@ -66,7 +436,79 @@ var ByollmApp = class {
    * the app is obliged to disclose that to whoever reads it.
    */
   async enqueue(input) {
-    const record = await this.#store.create(input, this.#now());
+    const unknown = Object.keys(input).filter(
+      (key) => !(key in ENQUEUE_OPTIONS)
+    );
+    if (unknown.length > 0) {
+      throw new Error(
+        `enqueue does not understand ${unknown.map((k) => `\`${k}\``).join(", ")}. An option this @byollm/server does not know is refused rather than ignored, because an ignored option is a job that runs differently than you asked with nothing to see \u2014 most often an SDK older than the code calling it. Upgrade @byollm/server, or remove the option.`
+      );
+    }
+    if (this.cloud !== void 0 && input.audience !== void 0) {
+      throw new Error(
+        "enqueue does not take `audience` on the cloud lane. Who may serve a job is derived from the person's own mapping \u2014 the service they chose, its owner, and that owner's sharing \u2014 which your site is not told and cannot compute. Remove `audience`; ask for the kind and the purpose, and their decision does the rest."
+      );
+    }
+    const parsed = KindedPayload.safeParse({
+      kind: input.kind,
+      payload: input.payload
+    });
+    if (!parsed.success) {
+      const detail = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+      throw new Error(`invalid ${input.kind} payload \u2014 ${detail}`);
+    }
+    const createdAt = this.#now();
+    const envelopeDeadlineAt = createdAt + ENVELOPE_MAX_AGE_MS;
+    const jobId = input.id ?? generateJobId();
+    const senderKeyId = keyId2(publicIdentityOf2(this.#siteKeys).identity);
+    const envelope = await seal({
+      plaintext: JSON.stringify(parsed.data.payload),
+      senderKeys: this.#siteKeys,
+      recipientEncryptionPublic: this.#siteKeys.encryptionPublic,
+      context: {
+        jobId,
+        senderKeyId,
+        recipientKeyId: senderKeyId,
+        deadlineAt: envelopeDeadlineAt,
+        direction: "payload"
+      }
+    });
+    const record = await this.#store.create(
+      {
+        ...input,
+        /**
+         * Derived here, because on the cloud lane it is derivable and nowhere
+         * else knows the lane.
+         *
+         * Refusing the site's declaration is only half of "derived, never
+         * declared" — the stub still carries an audience to the relay, and a
+         * store that defaults it to `private` would keep every cloud job
+         * private no matter who was forbidden from saying so. The half that
+         * fixes anything is this one.
+         *
+         * `team` is the value that defers: it says a device whose owner
+         * admits this person may serve, and the hub then decides whether one
+         * does, from the mapping the person authored, its service's owner,
+         * that owner's offer scope, and the roster. Nothing is widened by
+         * saying it — both axes still have to agree, and the owner's scope is
+         * the other axis.
+         *
+         * Direct mode keeps the store's `private` default: there is no
+         * control plane there to derive from, and owner-only is the ruling.
+         */
+        ...this.cloud === void 0 ? {} : { audience: "team" },
+        id: jobId,
+        envelope,
+        sizeClass: sizeClassOf(
+          payloadTextLength({
+            kind: input.kind,
+            payload: parsed.data.payload
+          })
+        )
+      },
+      createdAt
+    );
+    await this.cloud?.publish(record);
     return {
       id: record.id,
       record,
@@ -87,7 +529,7 @@ var ByollmApp = class {
    * Check `provenance.untrusted` before rendering. It is true for every
    * `named`/`public` job, because that text came from someone else's machine
    * and the app must not present it as its own AI's answer
-   * ({@link MUSTS.RESULT_PROVENANCE}).
+   * ({@link MUSTS.PROVENANCE_NAMES_DEVICE}).
    */
   async result(jobId) {
     const job = await this.job(jobId);
@@ -101,7 +543,11 @@ var ByollmApp = class {
   }
   /** Ask a runner to stop. Queued jobs cancel at once; held jobs at the next heartbeat. */
   async cancel(jobId) {
-    return this.#store.cancel(jobId, this.#now());
+    const cancelled = await this.#store.cancel(jobId, this.#now());
+    if (cancelled && this.cloud) {
+      await this.cloud.cancel(jobId).catch(() => void 0);
+    }
+    return cancelled;
   }
   /**
    * Is there a live runner that could take a job of this shape?
@@ -110,6 +556,11 @@ var ByollmApp = class {
    * signal cannot promise a runner the claim would then refuse.
    */
   async runnerAvailability(query) {
+    if (this.cloud !== void 0) {
+      throw new Error(
+        "runnerAvailability cannot answer on the cloud lane. It counts runners this site knows about, and on the cloud lane devices pair with the relay rather than with you \u2014 so the answer would be `none` whatever the truth is. Enqueue the job: the result says whether it ran, and the person's own dashboard says why not."
+      );
+    }
     const now = this.#now();
     const all = await this.#store.listRunners();
     const live = all.filter(
@@ -123,26 +574,41 @@ var ByollmApp = class {
     }
     let capable = 0;
     let admitted = 0;
+    let lastRefusal;
     for (const runner of live) {
-      const capability = runner.capabilities.find((c) => c.kind === query.kind);
-      if (!capability) continue;
-      capable += 1;
-      const match = matchAudience(
-        {
-          owner: query.owner,
-          audience: query.audience ?? "self",
-          audienceAllow: query.audienceAllow
-        },
-        {
-          owner: runner.owner,
-          offerScope: capability.offerScope,
-          account: backendDescriptor(capability.backendId).account,
-          // Same conservative assumption the claim path makes: the server
-          // cannot see a remote daemon's local allowlist (protocol §4.2).
-          locallyAllows: () => true
-        }
-      );
-      if (match.ok) admitted += 1;
+      for (const capability of runner.capabilities.filter(
+        (c) => c.kind === query.kind
+      )) {
+        capable += 1;
+        const match = matchAudience(
+          {
+            owner: query.owner,
+            audience: query.audience ?? "private",
+            audienceAllow: query.audienceAllow
+          },
+          {
+            owner: runner.owner,
+            offerScope: capability.offerScope,
+            // A generic backend's cost depends on its base URL, which the
+            // server never sees; assume the expensive reading (byollm_007 §4).
+            cost: backendDescriptor(capability.backendId).cost ?? "metered",
+            // Consent is the daemon's to hold, and it has already applied it:
+            // the offer scope arriving here is the *effective* one, so a
+            // metered backend nobody agreed to share advertises `self` and is
+            // refused by the scope rule above. Re-deriving consent from
+            // `false` here would instead refuse every backend an owner
+            // deliberately shared, because the server has no way to learn they
+            // did — the signal would be wrong in the direction that breaks
+            // working setups.
+            spend: { acknowledged: true },
+            // Same conservative assumption the claim path makes: the server
+            // cannot see a remote daemon's local allowlist (protocol §4.2).
+            admits: () => true
+          }
+        );
+        if (match.ok) admitted += 1;
+        else lastRefusal = match.refusal;
+      }
     }
     if (capable === 0) {
       return {
@@ -152,9 +618,10 @@ var ByollmApp = class {
       };
     }
     if (admitted === 0) {
+      const ownersDoing = lastRefusal === "offer-scope-too-narrow" || lastRefusal === "subscription-self-lock" || lastRefusal === "metered-no-spend-consent" || lastRefusal === "metered-ceiling-reached";
       return {
         available: false,
-        reason: "audience-admits-nobody",
+        reason: ownersDoing ? "default-unusable" : "audience-admits-nobody",
         candidates: 0
       };
     }
@@ -168,13 +635,10 @@ var ByollmApp = class {
    * ({@link MUSTS.PAIR_ONE_USER}, {@link MUSTS.PAIR_INTERACTIVE}).
    */
   async approvePairing(args) {
-    const token = generateRunnerToken();
     return this.#store.approvePairing({
       userCode: normalizeUserCode(args.userCode),
       owner: args.owner,
       runnerId: generateRunnerId(),
-      runnerToken: token,
-      tokenHash: hashSecret(token),
       now: this.#now()
     });
   }
@@ -218,6 +682,59 @@ function normalizeUserCode(input) {
   return bare.length === 8 ? `${bare.slice(0, 4)}-${bare.slice(4)}` : bare;
 }
 
+// src/keys.ts
+import { StoredKeys, generateKeys, publicIdentityOf as publicIdentityOf3 } from "@byollm/protocol";
+import { fingerprint } from "@byollm/protocol";
+var generateSiteKeys = (now = Date.now()) => generateKeys(now);
+function siteKeysFromEnv(variable = "BYOLLM_SITE_KEYS", env = process.env) {
+  const raw = env[variable];
+  if (raw === void 0 || raw === "") {
+    throw new Error(
+      `${variable} is not set. Generate a site identity once with \`npx @byollm/server keygen\` and set it as ${variable}. Do not generate keys at startup: every instance would get a different identity and daemons would pin one and be refused by another.`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(raw, "base64").toString("utf8"));
+  } catch {
+    throw new Error(
+      `${variable} is not base64-encoded JSON. It should be exactly what \`npx @byollm/server keygen\` printed.`
+    );
+  }
+  const result = StoredKeys.safeParse(parsed);
+  if (!result.success) {
+    throw new Error(
+      `${variable} does not contain a valid site identity. Regenerate it with \`npx @byollm/server keygen\` \u2014 and if this site has already paired daemons, they will need to pair again.`
+    );
+  }
+  return result.data;
+}
+function formatSiteKeys(keys) {
+  const encoded = Buffer.from(JSON.stringify(keys)).toString("base64");
+  const pub = publicIdentityOf3(keys);
+  return `# \u2500\u2500 1. SECRET \u2014 set this on your server, and nowhere else \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+#
+# This is the site's identity. Anything holding it can *be* this site,
+# so it goes wherever your deployment keeps secrets \u2014 never in a repo,
+# never in a browser, never pasted into a dashboard.
+BYOLLM_SITE_KEYS=${encoded}
+
+# \u2500\u2500 2. PUBLIC \u2014 paste this line into the byollm dashboard \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+#
+# The public half. It proves signatures and seals nothing, so it is
+# safe to publish \u2014 which is the point: users pin it, and the relay
+# cannot forge work without the secret above.
+${JSON.stringify(pub)}
+
+# \u2500\u2500 3. Fingerprint \u2014 what a person compares by eye \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+#
+# A fingerprint is not secret. Show it on your site so somebody
+# connecting can check it against what their daemon printed.
+# The dashboard derives this itself, so there is nothing to paste.
+# ${fingerprint(pub.identity)}
+`;
+}
+
 // src/memory.ts
 import {
   backendDescriptor as backendDescriptor2,
@@ -236,7 +753,7 @@ var MemoryStore = class {
   }
   // -- jobs ---------------------------------------------------------------
   create(input, now) {
-    const id = input.id ?? generateJobId();
+    const id = input.id;
     const existing = this.#jobs.get(id);
     if (existing) return Promise.resolve(existing);
     const dependsOn = [...input.dependsOn ?? []];
@@ -246,13 +763,16 @@ var MemoryStore = class {
     const job = {
       id,
       kind: input.kind,
-      payload: input.payload,
-      audience: input.audience ?? "self",
+      envelope: input.envelope,
+      sizeClass: input.sizeClass,
+      audience: input.audience ?? "private",
+      purpose: input.purpose,
       owner: input.owner,
       audienceAllow: input.audienceAllow ? [...input.audienceAllow] : void 0,
       dependsOn,
       state: "queued",
       lease: null,
+      completedByLeaseId: null,
       createdAt: now,
       // The TTL clock starts here only if nothing blocks the job.
       claimableAt: blocked ? null : now,
@@ -264,7 +784,7 @@ var MemoryStore = class {
       provenance: null,
       updatedAt: now
     };
-    this.#jobs.set(id, job);
+    this.#write(id, job);
     return Promise.resolve(job);
   }
   get(jobId) {
@@ -283,13 +803,16 @@ var MemoryStore = class {
         ...job,
         state: "claimed",
         lease: {
+          // A fresh id per grant. Two claims of the same job by the same
+          // runner are two different leases, and must be distinguishable.
+          id: generateLeaseId(),
           runnerId: args.runnerId,
           expiresAt: args.now + args.leaseMs
         },
         attempts: job.attempts + 1,
         updatedAt: args.now
       };
-      this.#jobs.set(job.id, updated);
+      this.#write(job.id, updated);
       claimed.push(updated);
     }
     return Promise.resolve(claimed);
@@ -313,14 +836,21 @@ var MemoryStore = class {
       {
         owner: args.runnerOwner,
         offerScope: capability.offerScope,
-        // From the registry, not a local guess — the subscription self-lock
-        // must mean the same thing on both sides of the wire.
-        account: backendDescriptor2(capability.backendId).account,
+        // From the registry, not a local guess — the cost rules must mean the
+        // same thing on both sides of the wire. The server cannot see a
+        // remote daemon's base URL, so a generic backend with no declared
+        // cost is treated as metered: the expensive side, and the daemon
+        // refuses anyway if it disagrees (byollm_007 §2).
+        cost: backendDescriptor2(capability.backendId).cost ?? "metered",
+        // Nor can it see the owner's spend consent. It offers; the daemon is
+        // the enforcing side and releases with `refused` if its own rules say
+        // no — the same shape as the `named` allowlist.
+        spend: { acknowledged: true },
         // The server cannot see a remote daemon's local allowlist and must
         // not pretend to (protocol §4.2). It admits the job here; the daemon
         // is the enforcing side and releases with `refused` if its own list
         // says no.
-        locallyAllows: () => true
+        admits: () => true
       }
     );
     return match.ok;
@@ -329,37 +859,67 @@ var MemoryStore = class {
     this.#expireDueSync(args.now);
     const renewed = [];
     const lost = [];
-    for (const jobId of args.jobIds) {
+    for (const { jobId, leaseId } of args.leases) {
       const job = this.#jobs.get(jobId);
-      if (!job || job.lease?.runnerId !== args.runnerId) {
-        lost.push(jobId);
+      if (!job || job.lease?.runnerId !== args.runnerId || job.lease.id !== leaseId) {
+        lost.push({ jobId, leaseId });
         continue;
       }
       if (job.state !== "claimed" && job.state !== "running") {
-        lost.push(jobId);
+        lost.push({ jobId, leaseId });
         continue;
       }
       const expiresAt = args.now + args.leaseMs;
-      this.#jobs.set(jobId, {
+      this.#write(jobId, {
         ...job,
         state: "running",
-        lease: { runnerId: args.runnerId, expiresAt },
+        // Renewal extends the existing grant; it does not mint a new one.
+        lease: { ...job.lease, expiresAt },
         updatedAt: args.now
       });
       renewed.push({ jobId, expiresAt });
     }
     return Promise.resolve({ renewed, lost });
   }
+  adopt(args) {
+    const job = this.#jobs.get(args.jobId);
+    if (!job) return Promise.resolve(null);
+    if (job.state !== "queued" && job.state !== "claimed") {
+      return Promise.resolve(null);
+    }
+    if (job.lease && job.lease.id !== args.leaseId) {
+      return Promise.resolve(null);
+    }
+    const updated = {
+      ...job,
+      state: "claimed",
+      lease: {
+        id: args.leaseId,
+        // No runner: this site never paired with the machine holding it.
+        runnerId: "",
+        expiresAt: args.expiresAt
+      },
+      updatedAt: args.now
+    };
+    this.#write(updated.id, updated);
+    return Promise.resolve(updated);
+  }
   complete(args) {
     const job = this.#jobs.get(args.jobId);
     if (!job) return Promise.resolve({ accepted: false, job: null });
     if (job.state === "ok" || job.state === "error" || job.state === "canceled") {
+      const sameDevice = job.provenance?.runnerId !== void 0 && job.provenance.runnerId === args.runnerId;
+      const sameGrant = args.holder.by === "lease" && job.completedByLeaseId !== null && job.completedByLeaseId === args.holder.leaseId;
+      if (sameDevice && sameGrant) {
+        return Promise.resolve({ accepted: false, duplicate: true, job });
+      }
       return Promise.resolve({ accepted: false, job });
     }
     if (job.state === "expired") {
       return Promise.resolve({ accepted: false, job });
     }
-    if (job.lease?.runnerId !== args.runnerId) {
+    const holds = args.holder.by === "runner" ? job.lease?.runnerId === args.holder.runnerId : job.lease?.id === args.holder.leaseId;
+    if (!holds) {
       return Promise.resolve({ accepted: false, job });
     }
     const state = args.outcome.outcome === "ok" ? "ok" : args.outcome.outcome === "canceled" ? "canceled" : "error";
@@ -367,11 +927,13 @@ var MemoryStore = class {
       ...job,
       state,
       lease: null,
+      // The grant that recorded it, kept after the lease is dropped — §3.6.
+      completedByLeaseId: args.holder.by === "lease" ? args.holder.leaseId : job.lease?.id ?? null,
       outcome: args.outcome,
       provenance: args.provenance,
       updatedAt: args.now
     };
-    this.#jobs.set(job.id, updated);
+    this.#write(job.id, updated);
     this.#cancelRequests.delete(job.id);
     if (state === "ok") this.#unblockDependents(job.id, args.now);
     return Promise.resolve({ accepted: true, job: updated });
@@ -392,19 +954,70 @@ var MemoryStore = class {
         (depId) => this.#jobs.get(depId)?.state === "ok"
       );
       if (ready) {
-        this.#jobs.set(job.id, { ...job, claimableAt: now, updatedAt: now });
+        this.#write(job.id, { ...job, claimableAt: now, updatedAt: now });
+      }
+    }
+  }
+  /**
+   * Watchers, by job id (byollm_009 §8.3).
+   *
+   * A `Set` per job so an unsubscribe removes exactly the handler it
+   * registered — two waiters on the same job are ordinary, and removing by
+   * job id alone would silently cancel someone else's wait.
+   */
+  #watchers = /* @__PURE__ */ new Map();
+  subscribe(jobId, onChange) {
+    const existing = this.#watchers.get(jobId) ?? /* @__PURE__ */ new Set();
+    existing.add(onChange);
+    this.#watchers.set(jobId, existing);
+    let live = true;
+    return () => {
+      if (!live) return;
+      live = false;
+      const set = this.#watchers.get(jobId);
+      set?.delete(onChange);
+      if (set?.size === 0) this.#watchers.delete(jobId);
+    };
+  }
+  /**
+   * The single write path for a job.
+   *
+   * Every mutation goes through here so notification cannot be forgotten by
+   * a future one. Nine call sites existed when the push seam was added, and
+   * "remember to notify" is not a property nine call sites keep.
+   */
+  #write(jobId, record) {
+    this.#jobs.set(jobId, record);
+    this.#notify(jobId);
+  }
+  /**
+   * Tell anyone watching that a job changed.
+   *
+   * A throwing watcher must not corrupt the store's own bookkeeping, so each
+   * is isolated: this runs inside write paths, and one bad listener taking
+   * out an unrelated write would be a far worse failure than a missed
+   * notification.
+   */
+  #notify(jobId) {
+    for (const watcher of this.#watchers.get(jobId) ?? []) {
+      try {
+        watcher();
+      } catch {
       }
     }
   }
   release(args) {
     const released = [];
-    for (const jobId of args.jobIds) {
+    for (const { jobId, leaseId } of args.leases) {
       const job = this.#jobs.get(jobId);
-      if (!job || job.lease?.runnerId !== args.runnerId) continue;
-      this.#jobs.set(jobId, {
+      if (!job || job.lease?.runnerId !== args.runnerId || job.lease.id !== leaseId) {
+        continue;
+      }
+      this.#write(jobId, {
         ...job,
         state: "queued",
         lease: null,
+        completedByLeaseId: null,
         // Newly available again, so the TTL clock restarts here too.
         claimableAt: args.now,
         // A refusal is remembered, or the pair spins between claim and
@@ -434,6 +1047,7 @@ var MemoryStore = class {
           ...job,
           state: "queued",
           lease: null,
+          completedByLeaseId: null,
           // The TTL clock restarts: it measures how long a job has waited
           // *unclaimed*, and this job has just become available again. Without
           // this, a job whose runner died would expire for time it spent being
@@ -443,7 +1057,7 @@ var MemoryStore = class {
           claimableAt: now,
           updatedAt: now
         };
-        this.#jobs.set(job.id, requeued);
+        this.#write(job.id, requeued);
         changed.push(requeued);
       }
     }
@@ -456,9 +1070,10 @@ var MemoryStore = class {
         ...job,
         state: "expired",
         lease: null,
+        completedByLeaseId: null,
         updatedAt: now
       };
-      this.#jobs.set(job.id, expired);
+      this.#write(job.id, expired);
       changed.push(expired);
     }
     return changed;
@@ -471,9 +1086,10 @@ var MemoryStore = class {
         ...job,
         state: "canceled",
         lease: null,
+        completedByLeaseId: null,
         updatedAt: now
       };
-      this.#jobs.set(jobId, canceled);
+      this.#write(jobId, canceled);
       return Promise.resolve(canceled);
     }
     if (job.state === "claimed" || job.state === "running") {
@@ -491,9 +1107,7 @@ var MemoryStore = class {
   }
   listCancelRequests(runnerId) {
     return Promise.resolve(
-      [...this.#cancelRequests].filter(
-        (jobId) => this.#jobs.get(jobId)?.lease?.runnerId === runnerId
-      )
+      [...this.#cancelRequests].map((jobId) => ({ jobId, lease: this.#jobs.get(jobId)?.lease })).filter((row) => row.lease?.runnerId === runnerId).map((row) => ({ jobId: row.jobId, leaseId: row.lease?.id ?? "" }))
     );
   }
   // -- pairing and runners -------------------------------------------------
@@ -524,7 +1138,9 @@ var MemoryStore = class {
     const runner = {
       id: args.runnerId,
       owner: args.owner,
-      tokenHash: args.tokenHash,
+      // Carried from the pairing, not re-supplied at approval: the user
+      // approved a specific machine, and the runner must be that machine.
+      device: pairing.device,
       label: pairing.label,
       platform: pairing.platform,
       daemonVersion: pairing.daemonVersion,
@@ -540,7 +1156,7 @@ var MemoryStore = class {
       state: "approved",
       owner: args.owner,
       runnerId: runner.id,
-      runnerTokenOnce: args.runnerToken
+      collected: false
     });
     return Promise.resolve(runner);
   }
@@ -561,17 +1177,11 @@ var MemoryStore = class {
     if (pairing) {
       this.#pairings.set(deviceCodeHash, {
         ...pairing,
-        runnerTokenOnce: null
+        collected: true
       });
     }
     return Promise.resolve();
   }
-  getRunnerByTokenHash(hash) {
-    for (const runner of this.#runners.values()) {
-      if (runner.tokenHash === hash) return Promise.resolve(runner);
-    }
-    return Promise.resolve(null);
-  }
   getRunner(runnerId) {
     return Promise.resolve(this.#runners.get(runnerId) ?? null);
   }
@@ -613,22 +1223,27 @@ function capabilityFor(capabilities, kind) {
 export {
   ByollmApp,
   ByollmHandlers,
+  CloudLane,
+  EnqueueRefused,
   MemoryStore,
   NoRunnerAvailableError,
   PollingDelivery,
+  RelayUnavailable,
   ResultTimeoutError,
   SERVED_PROTOCOL_VERSION,
-  bearerFrom,
   capabilityFor,
   createFetchHandler,
+  formatSiteKeys,
   generateDeviceCode,
   generateJobId,
   generateRunnerId,
-  generateRunnerToken,
+  generateSiteKeys,
   generateUserCode,
   hashSecret,
   normalizeUserCode,
   routeEndpoint,
-  secretsMatch
+  secretsMatch,
+  signatureFrom,
+  siteKeysFromEnv
 };
 //# sourceMappingURL=index.js.map