@scp-dev/hub 0.2.0 → 0.3.1

package/dist/index.js

@@ -22,7 +22,8 @@ import {
   unreachable,
   validHandle,
   validHarness,
-  validSelector
+  validSelector,
+  WAKES
 } from "@scp-dev/core";
 var MACHINE_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
 var REMOTE = /^[a-z0-9][a-z0-9._-]{0,63}\/([a-z0-9][a-z0-9._-]{0,62})?$/;
@@ -770,6 +771,21 @@ var FederatedCore = class extends RelayCore {
       this.audit("forward", from, result.id, { to: result.deliveries.map((d) => d.address), kind, hop: result.hop, thread: result.thread });
     });
   }
+  /**
+   * records that a forwarded message reached mirrored endpoints of other machines, unacknowledged, as a hub's delivery rows would: their
+   * replies then join its thread here. For links that deliver machine to machine; a hub bridge never needs it
+   */
+  recordRemoteDelivery(messageId, endpoints) {
+    this.tx(() => {
+      const message = one(this.sql, `SELECT expires_at FROM messages WHERE id = ?`, messageId);
+      if (!message) return;
+      for (const endpoint of endpoints) {
+        if (this.machineOf(endpoint) === null) continue;
+        if (one(this.sql, `SELECT 1 FROM deliveries WHERE message_id = ? AND endpoint = ?`, messageId, endpoint)) continue;
+        this.insertDelivery(messageId, endpoint, message.expires_at);
+      }
+    });
+  }
   /** the earlier result of a forwarded send with this client_id, or null; a different message under the same client_id is refused */
   forwarded(from, params) {
     const clientId = cleanText(params.client_id, "client_id", 128);
@@ -1268,7 +1284,7 @@ var FederatedCore = class extends RelayCore {
     const was = this.view(before);
     const presence = was.presence !== view.presence;
     const status = before.status_state !== after.status_state || before.status_note !== after.status_note;
-    const other = ["kind", "harness", "model", "cwd", "labels", "title", "tree", "parent_ep", "depth", "rules", "caps", "incarnation"].some(
+    const other = ["kind", "harness", "model", "cwd", "labels", "title", "wake", "tree", "parent_ep", "depth", "rules", "caps", "incarnation"].some(
       (field) => before[field] !== after[field]
     );
     return presence || status || other ? { view, added: false, presence, status } : null;
@@ -1336,6 +1352,7 @@ var FederatedCore = class extends RelayCore {
       rules: rules === void 0 ? row.rules : rules && (rules.in || rules.out) ? JSON.stringify(rules) : null,
       caps,
       title: scope.title !== void 0 ? scope.title : fresh ? null : row.title,
+      wake: scope.wake !== void 0 ? scope.wake : fresh ? null : row.wake,
       incarnation: scope.incarnation ?? row.incarnation
     };
   }
@@ -1489,6 +1506,7 @@ function parseScope(view) {
     throw new RelayError("too_large", `an endpoint's rules and caps are more than ${SCOPE_BYTES} bytes`);
   if (given("title"))
     out.title = view.title === null ? null : cleanText(typeof view.title === "string" ? view.title.replace(/\s+/g, " ") : view.title, "title", 64) || null;
+  if (given("wake")) out.wake = typeof view.wake === "string" && view.wake !== "none" && WAKES.includes(view.wake) ? view.wake : null;
   if (given("incarnation")) {
     if (view.incarnation !== null && (typeof view.incarnation !== "string" || !INCARNATION.test(view.incarnation))) throw bad("incarnation");
     out.incarnation = view.incarnation ?? null;
@@ -1504,20 +1522,20 @@ import {
   cleanText as cleanText2,
   dayStart,
   declaredLimits,
-  findSecret as findSecret2,
+  findSecret as findSecret3,
   gateRefusal,
   HUMAN_HANDLE as HUMAN_HANDLE2,
   honestSender,
   joinRedacted,
   judgeDetailForAgents,
-  LIMITS as LIMITS2,
+  LIMITS as LIMITS3,
   MESSAGE_KINDS as MESSAGE_KINDS2,
-  newId as newId2,
-  one as one2,
+  newId as newId3,
+  one as one3,
   PREAMBLE,
   PROTOCOL,
   parseXMessage,
-  RelayError as RelayError2,
+  RelayError as RelayError3,
   randomHex as randomHex2,
   replyGrant,
   SERVER_FIELDS,
@@ -1528,6 +1546,470 @@ import {
   XLIMITS,
   xlimits
 } from "@scp-dev/core";
+
+// src/judge-gate.ts
+import {
+  applyRedactions,
+  DEFAULT_JUDGE_BUDGET,
+  findSecret as findSecret2,
+  HttpJudgeClient,
+  JUDGE_PROMPT_VERSION,
+  judgeBoundary,
+  LIMITS as LIMITS2,
+  mergeVerdicts,
+  newId as newId2,
+  newJudgeStats,
+  one as one2,
+  RelayError as RelayError2,
+  runJudge,
+  sha256Hex,
+  VerdictCache
+} from "@scp-dev/core";
+var JUDGE_LIMITS = {
+  endpointPerMinute: LIMITS2.pairPerMinute,
+  endpointPerHour: LIMITS2.pairPerHour,
+  treePerMinute: LIMITS2.pairPerMinute * 2,
+  treePerHour: LIMITS2.pairPerHour * 2,
+  heldPerSender: 100
+};
+var iso = (ms) => ms === null ? null : new Date(ms).toISOString();
+var JudgeGate = class {
+  constructor(o) {
+    this.o = o;
+    this.limits = { ...JUDGE_LIMITS, ...o.limits };
+    o.sql.all(
+      `CREATE TABLE IF NOT EXISTS judge_holds (id TEXT PRIMARY KEY, from_ep TEXT NOT NULL, params TEXT NOT NULL, origin TEXT NOT NULL, verdict TEXT NOT NULL,
+       created_at INTEGER NOT NULL, expires_at INTEGER NOT NULL, state TEXT NOT NULL, by TEXT, resolved_at INTEGER)`
+    );
+    o.sql.all(
+      `CREATE TABLE IF NOT EXISTS judge_sent (from_ep TEXT NOT NULL, client_id TEXT NOT NULL, fingerprint TEXT NOT NULL, result TEXT NOT NULL, created_at INTEGER NOT NULL,
+       PRIMARY KEY (from_ep, client_id))`
+    );
+    o.sql.all(`UPDATE judge_holds SET state = 'held' WHERE state = 'releasing'`);
+  }
+  o;
+  stats = newJudgeStats();
+  policy;
+  version = "";
+  client = null;
+  cache = new VerdictCache();
+  shadows = /* @__PURE__ */ new Set();
+  /** judged sends in the last hour per budget: `ep:<id>`, `tree:<root id>` and `*` for the whole broker */
+  spent = /* @__PURE__ */ new Map();
+  limits;
+  /** the policy's judge section; a model client only when its key is readable, else the prefilter alone */
+  configure(policy) {
+    this.policy = policy;
+    this.version = policy ? sha256Hex(JSON.stringify(policy)) : "";
+    this.client = null;
+    const model = policy?.model;
+    if (!policy || policy.mode === "off" || !model) return;
+    const key = this.keyReader(model);
+    if (!key) {
+      this.o.log(
+        `relay broker: the judge model's key (${model.key_env ? `key_env ${model.key_env}` : `key_file ${model.key_file}`}) is not readable; judging with the prefilter only`
+      );
+      return;
+    }
+    this.client = (this.o.client ?? ((m, k) => new HttpJudgeClient({ model: m.id, effort: m.effort, key: k })))(model, key);
+  }
+  keyReader(model) {
+    if (model.key_env) {
+      const name = model.key_env;
+      return this.o.env[name] ? async () => this.o.env[name] ?? "" : null;
+    }
+    return this.o.keyFile?.(model.key_file) ?? null;
+  }
+  /** resolves once every shadow judgement started so far finished */
+  async settled() {
+    await Promise.all([...this.shadows]);
+  }
+  /** a send or ask through the judge; an unjudged one goes straight to `deliver` */
+  async send(from, params, origin, deliver) {
+    const policy = this.policy;
+    const body = params.body;
+    if (!policy || policy.mode === "off" || typeof body !== "string" || new TextEncoder().encode(body).length > LIMITS2.bodyBytes || findSecret2(body))
+      return deliver(from, params, origin);
+    const targets = Array.isArray(params.to) ? params.to : [params.to];
+    if (targets.some((to) => this.o.core.foreignAccount(to) !== null)) {
+      if (policy.mode === "enforce") {
+        this.o.core.auditJudge("judge_skipped", from, null, {
+          side: "local",
+          boundary: "other account",
+          prompt_version: JUDGE_PROMPT_VERSION,
+          categories: [],
+          sha256: sha256Hex(body),
+          verdict: "skipped",
+          reason: "other_account_judged_by_hub",
+          to: targets.map(String)
+        });
+      }
+      return deliver(from, params, origin);
+    }
+    if (policy.mode === "shadow") {
+      const result = await deliver(from, params, origin);
+      if (!result.duplicate) this.shadow(policy, from, params, origin, result.id);
+      return result;
+    }
+    const { groups, tree } = this.boundaries(policy, from, params, origin);
+    if (!groups.size) return deliver(from, params, origin);
+    const ttl = params.ttl_s ?? LIMITS2.ttlDefaultS;
+    if (!Number.isInteger(ttl) || ttl < 1 || ttl > LIMITS2.ttlMaxS) throw new RelayError2("invalid_params", `ttl_s must be 1 to ${LIMITS2.ttlMaxS}`);
+    const seen = params.client_id === void 0 ? void 0 : this.seen(from, params);
+    if (seen) return seen;
+    const waiting = one2(this.o.sql, `SELECT COUNT(*) AS n FROM judge_holds WHERE from_ep = ? AND state IN ('held', 'releasing')`, from).n;
+    if (waiting >= this.limits.heldPerSender)
+      throw new RelayError2("rate_limited", `${waiting} of your messages wait for review by your human; send more once they released or refused some`, 3600);
+    this.spend(policy, from, tree);
+    const verdict = await this.judge(policy, from, body, groups);
+    const detail = this.detail(verdict, body, groups);
+    switch (verdict.verdict) {
+      case "refuse":
+        this.o.core.auditJudge("judge_refuse", from, null, detail);
+        throw new RelayError2(
+          "judge_refused",
+          `the relay judge refused this message (local; ${verdict.categories.join(", ") || "no category"}): ${verdict.reason}`,
+          void 0,
+          {
+            side: "local",
+            categories: verdict.categories,
+            reason: verdict.reason
+          }
+        );
+      case "hold":
+        return this.hold(from, params, origin, verdict, groups, detail);
+      case "redact": {
+        const applied = applyRedactions(body, verdict.redactions);
+        const result = await deliver(from, { ...params, body: applied.text }, origin);
+        const redacted = { n: applied.n, kinds: applied.kinds };
+        this.o.core.auditJudge(verdict.source === "error" ? "judge_skipped" : "judge_redact", from, result.id, { ...detail, redacted });
+        return this.remember(from, params, { ...result, redacted });
+      }
+      case "pass": {
+        const result = await deliver(from, params, origin);
+        if (verdict.source === "error") this.o.core.auditJudge("judge_skipped", from, result.id, detail);
+        return this.remember(from, params, result);
+      }
+    }
+  }
+  /** an earlier judged send or waiting hold under the send's client_id: the same message is answered as before, another one refused as core refuses it */
+  seen(from, params) {
+    const clientId = params.client_id;
+    const held = one2(
+      this.o.sql,
+      `SELECT id, params FROM judge_holds WHERE from_ep = ? AND json_extract(params, '$.client_id') = ? AND state IN ('held', 'releasing')`,
+      from,
+      clientId
+    );
+    const sent = held ? void 0 : one2(
+      this.o.sql,
+      `SELECT fingerprint, result FROM judge_sent WHERE from_ep = ? AND client_id = ? AND created_at > ?`,
+      from,
+      clientId,
+      this.o.now() - LIMITS2.idempotencyS * 1e3
+    );
+    const before = held ? fingerprint(JSON.parse(held.params)) : sent?.fingerprint;
+    if (before === void 0) return void 0;
+    if (before !== fingerprint(params)) throw new RelayError2("invalid_params", `client_id ${clientId} was already used for a different message`);
+    return held ? heldResult(held.id, params) : { ...JSON.parse(sent.result), duplicate: true };
+  }
+  remember(from, params, result) {
+    if (params.client_id !== void 0 && !result.duplicate) {
+      this.o.sql.all(
+        `INSERT OR REPLACE INTO judge_sent (from_ep, client_id, fingerprint, result, created_at) VALUES (?, ?, ?, ?, ?)`,
+        from,
+        params.client_id,
+        fingerprint(params),
+        JSON.stringify(result),
+        this.o.now()
+      );
+    }
+    return result;
+  }
+  /**
+   * a judged send counts before any model call against its sender's, its lineage tree's and the whole broker's budget, since refused and
+   * held sends never reach the send's own limits, and a new handle or a helper process must not bring a fresh budget
+   */
+  spend(policy, from, tree) {
+    const now = this.o.now();
+    const global = policy.budget ?? DEFAULT_JUDGE_BUDGET;
+    const budgets = [
+      [`ep:${from}`, this.limits.endpointPerMinute, this.limits.endpointPerHour, "from this endpoint"],
+      [`tree:${tree}`, this.limits.treePerMinute, this.limits.treePerHour, "from this lineage tree"],
+      ["*", global.per_minute, global.per_hour, "on this broker"]
+    ];
+    const recent = budgets.map(([key]) => (this.spent.get(key) ?? []).filter((at) => at > now - 36e5));
+    budgets.forEach(([key, perMinute, perHour, what], i) => {
+      for (const [limit, windowS] of [
+        [perMinute, 60],
+        [perHour, 3600]
+      ]) {
+        const inWindow = recent[i].filter((at) => at > now - windowS * 1e3);
+        if (inWindow.length >= limit) {
+          this.spent.set(key, recent[i]);
+          throw new RelayError2(
+            "rate_limited",
+            `${limit} judged messages ${what} in ${windowS} s`,
+            Math.max(1, Math.ceil((inWindow[0] + windowS * 1e3 - now) / 1e3))
+          );
+        }
+      }
+    });
+    for (const [i, [key]] of budgets.entries()) this.spent.set(key, [...recent[i], now]);
+  }
+  /** how many budgets are tracked (idle ones are evicted by the sweep) */
+  budgetKeys() {
+    return this.spent.size;
+  }
+  /** the held messages, newest first, without bodies */
+  holds(state) {
+    const rows = state ? this.o.sql.all(`SELECT * FROM judge_holds WHERE state = ? ORDER BY created_at DESC, rowid DESC LIMIT 200`, state) : this.o.sql.all(`SELECT * FROM judge_holds ORDER BY created_at DESC, rowid DESC LIMIT 200`);
+    return rows.map((row) => this.view(row));
+  }
+  /** one hold with its body and the judge's redactions while it waits */
+  show(id) {
+    const row = this.row(id);
+    const params = JSON.parse(row.params);
+    const verdict = JSON.parse(row.verdict);
+    return { ...this.view(row), ...typeof params.body === "string" ? { body: params.body } : {}, redactions: verdict.redactions };
+  }
+  /** delivers a held message as its sender, as stored or redacted: scope, policy and limits are checked again by the send itself */
+  async release(id, options, deliver) {
+    const row = one2(
+      this.o.sql,
+      `UPDATE judge_holds SET state = 'releasing' WHERE id = ? AND state = 'held' AND expires_at > ? RETURNING *`,
+      id,
+      this.o.now()
+    );
+    if (!row) throw new RelayError2("not_found", `no held message ${id}`);
+    const params = JSON.parse(row.params);
+    const verdict = JSON.parse(row.verdict);
+    let sent = params;
+    let redacted;
+    if (options.redacted) {
+      const applied = applyRedactions(params.body, verdict.redactions);
+      if (!applied.n) {
+        this.o.sql.all(`UPDATE judge_holds SET state = 'held' WHERE id = ?`, id);
+        throw new RelayError2("invalid_params", `hold ${id} has no redactions: release it as it is or refuse it`);
+      }
+      sent = { ...params, body: applied.text };
+      redacted = { n: applied.n, kinds: applied.kinds };
+    }
+    let result;
+    try {
+      result = await deliver(row.from_ep, sent, JSON.parse(row.origin));
+    } catch (error) {
+      this.o.sql.all(`UPDATE judge_holds SET state = 'held' WHERE id = ?`, id);
+      throw error;
+    }
+    this.remember(row.from_ep, params, { ...result, ...redacted ? { redacted } : {} });
+    this.resolve(row, "released", options.by);
+    this.o.core.auditJudge("judge_override", row.from_ep, id, {
+      ...this.storedDetail(row, verdict),
+      by: options.by,
+      action: redacted ? "release_redacted" : "release",
+      ...redacted ? { redacted } : {}
+    });
+    this.tell(
+      row.from_ep,
+      `relay: your message held for review as ${id} was released by your human${redacted ? " with redactions" : ""} and delivered as ${result.id}`
+    );
+    return { ...result, ...redacted ? { redacted } : {} };
+  }
+  /** refuses a held message: it is never delivered, and its sender hears the human's reason */
+  refuse(id, reason, by) {
+    this.expire(this.o.now());
+    const row = one2(this.o.sql, `SELECT * FROM judge_holds WHERE id = ? AND state = 'held'`, id);
+    if (!row) throw new RelayError2("not_found", `no held message ${id}`);
+    const verdict = JSON.parse(row.verdict);
+    this.resolve(row, "refused", by);
+    this.o.core.auditJudge("judge_override", row.from_ep, id, { ...this.storedDetail(row, verdict), by, action: "refuse", reason });
+    this.tell(row.from_ep, `relay: your message held for review as ${id} was refused by your human: ${reason}`);
+    return this.view(this.row(id));
+  }
+  /** expires holds past their message TTL (body purged, sender told) and drops resolved ones past the audit window */
+  sweep() {
+    const now = this.o.now();
+    this.expire(now);
+    this.o.sql.all(`DELETE FROM judge_holds WHERE state IN ('released', 'refused', 'expired') AND resolved_at <= ?`, now - LIMITS2.auditKeepS * 1e3);
+    this.o.sql.all(`DELETE FROM judge_sent WHERE created_at <= ?`, now - LIMITS2.idempotencyS * 1e3);
+    for (const [key, times] of this.spent) if (!times.length || times[times.length - 1] <= now - 36e5) this.spent.delete(key);
+  }
+  expire(now) {
+    for (const row of this.o.sql.all(`SELECT * FROM judge_holds WHERE state = 'held' AND expires_at <= ?`, now)) {
+      const verdict = JSON.parse(row.verdict);
+      this.resolve(row, "expired", null);
+      this.o.core.auditJudge("judge_expire", row.from_ep, row.id, this.storedDetail(row, verdict));
+      this.tell(row.from_ep, `relay: your message held for review as ${row.id} expired without review and was not delivered`);
+    }
+  }
+  /** the recipients by the boundary their message crosses; throws as send does for a target the sender cannot reach */
+  boundaries(policy, from, params, origin) {
+    const subjects = () => this.o.core.judgeSubjects(from, params, origin);
+    const { sender, recipients, tree } = this.o.within ? this.o.within(origin, subjects) : subjects();
+    const groups = /* @__PURE__ */ new Map();
+    for (const recipient of recipients) {
+      const label = judgeBoundary(policy, sender, recipient);
+      if (label !== null) groups.set(label, [...groups.get(label) ?? [], recipient.address]);
+    }
+    return { groups, tree };
+  }
+  async judge(policy, from, body, groups) {
+    const verdicts = await Promise.all(
+      [...groups].map(
+        ([boundary, to]) => runJudge({
+          body,
+          side: "local",
+          boundary,
+          configVersion: this.version,
+          client: this.client,
+          cache: this.cache,
+          timeoutMs: policy.timeout_s * 1e3,
+          failMode: policy.fail,
+          ...this.client && policy.model ? { model: policy.model.id } : {},
+          from: this.o.core.addressOf(from),
+          to,
+          now: this.o.now,
+          stats: this.stats
+        })
+      )
+    );
+    return mergeVerdicts(verdicts);
+  }
+  shadow(policy, from, params, origin, ref) {
+    const task = (async () => {
+      try {
+        const { groups, tree } = this.boundaries(policy, from, params, origin);
+        if (!groups.size) return;
+        this.spend(policy, from, tree);
+        const body = params.body;
+        const verdict = await this.judge(policy, from, body, groups);
+        this.o.core.auditJudge("judge_shadow", from, ref, this.detail(verdict, body, groups));
+      } catch (error) {
+        this.o.log(`relay broker: a shadow judgement failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    })();
+    this.shadows.add(task);
+    void task.finally(() => this.shadows.delete(task));
+  }
+  hold(from, params, origin, verdict, groups, detail) {
+    const now = this.o.now();
+    const id = newId2("hold", now);
+    const stored2 = { ...params, client_id: params.client_id ?? id };
+    const to = [...groups.values()].flat();
+    const record = { ...verdict, boundary: [...groups.keys()].join(" | "), to };
+    this.o.sql.all(
+      `INSERT INTO judge_holds (id, from_ep, params, origin, verdict, created_at, expires_at, state) VALUES (?, ?, ?, ?, ?, ?, ?, 'held')`,
+      id,
+      from,
+      JSON.stringify(stored2),
+      JSON.stringify(origin),
+      JSON.stringify(record),
+      now,
+      now + (params.ttl_s ?? LIMITS2.ttlDefaultS) * 1e3
+    );
+    this.o.core.auditJudge("judge_hold", from, id, detail);
+    return heldResult(id, params);
+  }
+  detail(verdict, body, groups) {
+    return {
+      side: "local",
+      boundary: [...groups.keys()].join(" | "),
+      prompt_version: verdict.prompt_version,
+      categories: verdict.categories,
+      sha256: sha256Hex(body),
+      verdict: verdict.verdict,
+      source: verdict.source,
+      reason: verdict.reason,
+      to: [...groups.values()].flat(),
+      ...verdict.model ? { model: verdict.model } : {},
+      ...verdict.ms !== void 0 ? { ms: verdict.ms } : {}
+    };
+  }
+  storedDetail(row, verdict) {
+    const params = JSON.parse(row.params);
+    return {
+      side: "local",
+      boundary: verdict.boundary,
+      prompt_version: verdict.prompt_version,
+      categories: verdict.categories,
+      sha256: params.sha256 ?? sha256Hex(params.body ?? ""),
+      verdict: verdict.verdict,
+      to: verdict.to,
+      ...verdict.model ? { model: verdict.model } : {}
+    };
+  }
+  /** marks a hold resolved and purges its body and the judge's quotes of it */
+  resolve(row, state, by) {
+    const { body, ...params } = JSON.parse(row.params);
+    const verdict = JSON.parse(row.verdict);
+    const purged = { ...params, bytes: new TextEncoder().encode(body).length, sha256: sha256Hex(body) };
+    const kinds = { ...verdict, redactions: verdict.redactions.map((r) => ({ kind: r.kind })) };
+    this.o.sql.all(
+      `UPDATE judge_holds SET state = ?, by = ?, resolved_at = ?, params = ?, verdict = ? WHERE id = ?`,
+      state,
+      by,
+      this.o.now(),
+      JSON.stringify(purged),
+      JSON.stringify(kinds),
+      row.id
+    );
+  }
+  tell(endpoint, text) {
+    try {
+      if (this.o.notice) this.o.notice(endpoint, text);
+      else {
+        this.o.core.judgeNotice(endpoint, text);
+        this.o.wake(endpoint);
+      }
+    } catch (error) {
+      if (!(error instanceof RelayError2)) throw error;
+    }
+  }
+  row(id) {
+    const row = one2(this.o.sql, `SELECT * FROM judge_holds WHERE id = ?`, id);
+    if (!row) throw new RelayError2("not_found", `no held message ${id}`);
+    return row;
+  }
+  view(row) {
+    const params = JSON.parse(row.params);
+    const verdict = JSON.parse(row.verdict);
+    return {
+      id: row.id,
+      from: this.o.core.addressOf(row.from_ep),
+      to: verdict.to,
+      state: row.state,
+      created_at: iso(row.created_at),
+      expires_at: iso(row.expires_at),
+      categories: verdict.categories,
+      reason: verdict.reason,
+      boundary: verdict.boundary,
+      source: verdict.source,
+      bytes: params.bytes ?? new TextEncoder().encode(params.body ?? "").length,
+      by: row.by,
+      resolved_at: iso(row.resolved_at)
+    };
+  }
+};
+var fingerprint = (p) => sha256Hex(
+  JSON.stringify([
+    [p.to].flat().map(String).sort(),
+    p.body,
+    p.kind ?? "message",
+    p.thread ?? null,
+    p.reply_to ?? null,
+    p.data_class ?? "public",
+    (p.attachments ?? []).map((a) => a?.path).sort(),
+    p.mime ?? null,
+    p.ttl_s ?? LIMITS2.ttlDefaultS,
+    p.require_reply ?? null
+  ])
+);
+function heldResult(id, params) {
+  return { id, thread: params.thread ?? "", hop: 0, deliveries: [], held: { hold_id: id, side: "local" } };
+}
+
+// src/hub.ts
 var GRAPH_MINUTES = 15;
 var GRAPH_MINUTES_MAX = 60;
 var HUB_LIMITS = {
@@ -1563,9 +2045,9 @@ var HUB_MIGRATION = [
 ];
 var OBSERVER_METHODS = /* @__PURE__ */ new Set(["list", "snapshot", "watch", "log", "machines", "machines_rm"]);
 var CLIENT_METHODS = /* @__PURE__ */ new Set(["whoami", "send", "ask", "ask_wait", "inbox", "ack", "status", "event", ...OBSERVER_METHODS]);
-var iso = (ms) => ms === null ? null : new Date(ms).toISOString();
+var iso2 = (ms) => ms === null ? null : new Date(ms).toISOString();
 function rpcError(error) {
-  if (!(error instanceof RelayError2)) return { code: -32603, message: "internal error", data: { code: "unavailable" } };
+  if (!(error instanceof RelayError3)) return { code: -32603, message: "internal error", data: { code: "unavailable" } };
   const code = error.code === "method_not_found" ? -32601 : error.code === "invalid_params" ? -32602 : -32e3;
   return { code, message: error.message, data: { code: error.code, ...error.retryAfterS ? { retry_after: error.retryAfterS } : {} } };
 }
@@ -1573,16 +2055,16 @@ function mirrorSync(value) {
   if (value === void 0 || value === null) return null;
   const { id, part, parts } = value;
   if (typeof id !== "string" || !id || id.length > 64 || !Number.isInteger(parts) || parts < 1 || parts > 4096 || !Number.isInteger(part) || part < 1 || part > parts) {
-    throw new RelayError2("invalid_params", "sync is { id, part, parts } of a full mirror in several frames");
+    throw new RelayError3("invalid_params", "sync is { id, part, parts } of a full mirror in several frames");
   }
   return { id, part, parts };
 }
 function serverFields(params) {
-  for (const field of SERVER_FIELDS) if (field in params) throw new RelayError2("invalid_params", `${field} is set by the relay, not the sender`);
+  for (const field of SERVER_FIELDS) if (field in params) throw new RelayError3("invalid_params", `${field} is set by the relay, not the sender`);
 }
 function object(value, what) {
   if (value === void 0) return {};
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw new RelayError2("invalid_params", `${what} must be an object`);
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new RelayError3("invalid_params", `${what} must be an object`);
   return value;
 }
 var fullLogin = (grant) => grant.scoped === false;
@@ -1629,6 +2111,8 @@ var RelayHub = class _RelayHub {
   xcounters = null;
   xkey = null;
   limits;
+  judgeConfig = null;
+  gate = null;
   /** idempotent: migrates and records the account handle (the address user part, e.g. "ada"); call before handling each request */
   init(account) {
     if (this.core && this.account === account.user) return;
@@ -1649,6 +2133,7 @@ var RelayHub = class _RelayHub {
     });
     core.migrate();
     this.core = core;
+    this.gate = null;
     this.account = account.user;
     if (this.deps.crossAccount) {
       this.xkey = core.xstate("key", () => randomHex2(32));
@@ -1663,12 +2148,37 @@ var RelayHub = class _RelayHub {
     this.denied = null;
     this.xcounters = null;
     this.xkey = null;
+    this.gate = null;
     this.buckets.clear();
     this.gone.clear();
   }
+  /**
+   * judges this account's own sends (client send and ask, bridge forward) before delivery; sends to other accounts are left to the
+   * cross-account gate. Without a policy, or with mode off, the hub holds no judge and creates no judge tables
+   */
+  configureJudge(policy, options = { env: {} }) {
+    this.gate = null;
+    this.judgeConfig = policy && policy.mode !== "off" ? { policy, options } : null;
+  }
+  /** the held messages, newest first, without bodies */
+  holds(state) {
+    return this.judged().holds(state);
+  }
+  /** one hold with its body while it waits */
+  holdShow(id) {
+    return this.judged().show(id);
+  }
+  /** delivers a held message as its sender, every send check run again */
+  holdRelease(id, options) {
+    return this.judged().release(id, options, this.deliverJudged);
+  }
+  /** refuses a held message: never delivered, its sender told why */
+  holdRefuse(id, reason, by) {
+    return this.judged().refuse(id, reason, by);
+  }
   /** a fresh connection state for an accepted socket */
   static connection(grant) {
-    return { id: newId2("conn"), grant, role: "new", machine: null, endpoint: null, watching: false, subscribed: false };
+    return { id: newId3("conn"), grant, role: "new", machine: null, endpoint: null, watching: false, subscribed: false };
   }
   /** a socket would exceed the `sockets` limit: the host refuses it (429) instead of accepting */
   full() {
@@ -1677,7 +2187,7 @@ var RelayHub = class _RelayHub {
   /** one JSON-RPC text frame from a socket; replies and pushes go out through socket.send */
   async message(socket, text) {
     if (new TextEncoder().encode(text).length > this.limits.frameBytes) {
-      this.write(socket, { jsonrpc: "2.0", id: null, error: rpcError(new RelayError2("too_large", `a frame is at most ${this.limits.frameBytes} bytes`)) });
+      this.write(socket, { jsonrpc: "2.0", id: null, error: rpcError(new RelayError3("too_large", `a frame is at most ${this.limits.frameBytes} bytes`)) });
       socket.close(1009, "frame too large");
       this.closed(socket);
       return;
@@ -1703,7 +2213,7 @@ var RelayHub = class _RelayHub {
   /** POST /v1/relay/rpc: a JSON-RPC request or batch run in order on a short-lived connection; returns the response(s) */
   async batch(grant, body) {
     if (JSON.stringify(body ?? null).length > this.limits.frameBytes) {
-      return { jsonrpc: "2.0", id: null, error: rpcError(new RelayError2("too_large", `a request is at most ${this.limits.frameBytes} bytes`)) };
+      return { jsonrpc: "2.0", id: null, error: rpcError(new RelayError3("too_large", `a request is at most ${this.limits.frameBytes} bytes`)) };
     }
     const requests = Array.isArray(body) ? body : [body];
     if (!requests.length) return { jsonrpc: "2.0", id: null, error: { code: -32600, message: "an empty batch" } };
@@ -1823,6 +2333,7 @@ var RelayHub = class _RelayHub {
       this.gone.clear();
       for (const [key, bucket] of this.buckets) if (bucket.tokens + (now - bucket.at) * bucket.rate / 6e4 >= bucket.rate) this.buckets.delete(key);
       this.xcounters?.prune();
+      this.judgeGate()?.sweep();
       this.setState("last_sweep", now);
     }
     if (this.idle(now)) {
@@ -1850,7 +2361,7 @@ var RelayHub = class _RelayHub {
       swept = now;
       this.setState("last_sweep", swept);
     }
-    const retrying = one2(this.deps.sql, `SELECT 1 FROM hub_state WHERE key LIKE ? LIMIT 1`, `${REVALIDATE_ERROR}%`) !== void 0;
+    const retrying = one3(this.deps.sql, `SELECT 1 FROM hub_state WHERE key LIKE ? LIMIT 1`, `${REVALIDATE_ERROR}%`) !== void 0;
     return Math.min(
       validated + (retrying ? REVALIDATE_RETRY_MS : this.limits.revalidateMs),
       swept + SWEEP_MS,
@@ -1866,7 +2377,7 @@ var RelayHub = class _RelayHub {
   /** while the hub holds rows: the earliest unacked delivery's expiry, at most a day and at least a minute away */
   retentionAlarm(now) {
     const sql = this.deps.sql;
-    const held = one2(
+    const held = one3(
       sql,
       `SELECT EXISTS (SELECT 1 FROM machines) OR EXISTS (SELECT 1 FROM machine_tombstones) OR EXISTS (SELECT 1 FROM endpoints WHERE handle NOT IN (?, ?))
        OR EXISTS (SELECT 1 FROM messages) OR EXISTS (SELECT 1 FROM deliveries) OR EXISTS (SELECT 1 FROM audit) AS held`,
@@ -1874,13 +2385,13 @@ var RelayHub = class _RelayHub {
       SYSTEM_HANDLE2
     ).held;
     if (!held) return null;
-    const expiry = one2(sql, `SELECT MIN(expires_at) AS at FROM deliveries WHERE acked_at IS NULL`).at;
+    const expiry = one3(sql, `SELECT MIN(expires_at) AS at FROM deliveries WHERE acked_at IS NULL`).at;
     return Math.max(now + MIN_ALARM_MS, Math.min(expiry ?? Number.POSITIVE_INFINITY, now + DAY_MS));
   }
   /** no machine bound or tombstoned, no live socket and nothing queued */
   idle(now) {
     if (this.deps.sockets().some((s) => !this.gone.has(s.conn.id))) return false;
-    return !one2(
+    return !one3(
       this.deps.sql,
       `SELECT EXISTS (SELECT 1 FROM machines) OR EXISTS (SELECT 1 FROM machine_tombstones) OR EXISTS (SELECT 1 FROM deliveries WHERE acked_at IS NULL AND expires_at > ?) AS busy`,
       now
@@ -1901,7 +2412,7 @@ var RelayHub = class _RelayHub {
       const result = await this.dispatch(socket, method, object(request.params, "params"));
       return request.id === void 0 ? null : { jsonrpc: "2.0", id, result };
     } catch (error) {
-      code = error instanceof RelayError2 ? error.code : "internal";
+      code = error instanceof RelayError3 ? error.code : "internal";
       if (code === "internal") this.deps.log?.("relay_internal_error", { account: this.account, method, error: error instanceof Error ? error.name : "error" });
       return request.id === void 0 ? null : { jsonrpc: "2.0", id, error: rpcError(error) };
     } finally {
@@ -1919,7 +2430,7 @@ var RelayHub = class _RelayHub {
     const now = this.now();
     if (method === "ack" && (conn.role === "client" || conn.role === "bridge") || method === "reject" && conn.role === "bridge") {
       const seqs = params?.seqs;
-      const cost = method === "ack" && Array.isArray(seqs) ? Math.min(Math.max(seqs.length, 1), LIMITS2.inboxPage) : 1;
+      const cost = method === "ack" && Array.isArray(seqs) ? Math.min(Math.max(seqs.length, 1), LIMITS3.inboxPage) : 1;
       const token = this.bucket(`${conn.grant.tokenId}:ack`, this.limits.acksPerMinute, now);
       const account2 = this.bucket("account:ack", this.limits.accountAcksPerMinute, now);
       for (const [b, scope] of [
@@ -1927,7 +2438,7 @@ var RelayHub = class _RelayHub {
         [account2, "an account"]
       ]) {
         if (b.tokens < cost)
-          throw new RelayError2("rate_limited", `at most ${b.rate} acked seqs per minute on ${scope}`, Math.max(1, Math.ceil((cost - b.tokens) * 60 / b.rate)));
+          throw new RelayError3("rate_limited", `at most ${b.rate} acked seqs per minute on ${scope}`, Math.max(1, Math.ceil((cost - b.tokens) * 60 / b.rate)));
       }
       token.tokens -= cost;
       account2.tokens -= cost;
@@ -1940,7 +2451,7 @@ var RelayHub = class _RelayHub {
     if (method === "event") {
       for (const b of [bucket, account]) {
         if (b.tokens < b.rate / 4)
-          throw new RelayError2(
+          throw new RelayError3(
             "rate_limited",
             "activity events wait while the token or the account is near its call limit",
             Math.max(1, Math.ceil((b.rate / 4 - b.tokens) * 60 / b.rate))
@@ -1952,14 +2463,14 @@ var RelayHub = class _RelayHub {
         socket.close(1013, "rate limited");
         this.closed(socket);
       }
-      throw new RelayError2(
+      throw new RelayError3(
         "rate_limited",
         `at most ${rate} ${bridge ? "bridge " : ""}calls per minute on a token`,
         Math.max(1, Math.ceil((1 - bucket.tokens) * 60 / rate))
       );
     }
     if (account.tokens < 1) {
-      throw new RelayError2(
+      throw new RelayError3(
         "rate_limited",
         `at most ${this.limits.accountCallsPerMinute} calls per minute on an account`,
         Math.max(1, Math.ceil((1 - account.tokens) * 60 / account.rate))
@@ -1978,36 +2489,36 @@ var RelayHub = class _RelayHub {
     return bucket;
   }
   async dispatch(socket, method, params) {
-    if (this.gone.has(socket.conn.id)) throw new RelayError2("unauthorized", "this connection is closed");
+    if (this.gone.has(socket.conn.id)) throw new RelayError3("unauthorized", "this connection is closed");
     if (method === "hello") return this.hello(socket, params);
-    if (socket.conn.role === "new") throw new RelayError2("unauthorized", "call hello first");
+    if (socket.conn.role === "new") throw new RelayError3("unauthorized", "call hello first");
     if (socket.conn.role === "bridge") return this.bridgeMethod(socket, method, params);
     if (socket.conn.role === "observer" && !OBSERVER_METHODS.has(method)) {
-      if (CLIENT_METHODS.has(method)) throw new RelayError2("unauthorized", "this connection only observes: say hello as an agent or the human");
-      throw new RelayError2("method_not_found", `no method ${method}`);
+      if (CLIENT_METHODS.has(method)) throw new RelayError3("unauthorized", "this connection only observes: say hello as an agent or the human");
+      throw new RelayError3("method_not_found", `no method ${method}`);
     }
     return this.clientMethod(socket, method, params);
   }
   hello(socket, params) {
     const core = this.relay;
     const conn = socket.conn;
-    if (conn.role !== "new") throw new RelayError2("invalid_params", "hello was already called on this connection");
-    if (params.protocol !== PROTOCOL) throw new RelayError2("invalid_params", `this relay speaks ${PROTOCOL}`);
+    if (conn.role !== "new") throw new RelayError3("invalid_params", "hello was already called on this connection");
+    if (params.protocol !== PROTOCOL) throw new RelayError3("invalid_params", `this relay speaks ${PROTOCOL}`);
     if (params.transient !== void 0)
-      throw new RelayError2("invalid_params", "the hub takes no hook connections: hooks report to the local broker, which bridges them");
+      throw new RelayError3("invalid_params", "the hub takes no hook connections: hooks report to the local broker, which bridges them");
     serverFields(params);
     const observe = params.observe === true;
     const named = params.machine;
     if ((!observe || named !== void 0) && (typeof named !== "string" || !MACHINE_NAME.test(named) || named === "me" || named === "local" || named === this.account)) {
-      throw new RelayError2("invalid_params", "machine is a name of lowercase letters, digits and -, other than me, local and the account handle");
+      throw new RelayError3("invalid_params", "machine is a name of lowercase letters, digits and -, other than me, local and the account handle");
     }
     const bridge = params.bridge === true;
     const human = params.human === true;
     this.deps.sql.all(`DELETE FROM hub_state WHERE key = 'idle_since'`);
-    const info = { account: this.account, capabilities: CAPABILITIES, server_time: new Date(this.now()).toISOString(), limits: { ...LIMITS2, ...this.limits } };
+    const info = { account: this.account, capabilities: CAPABILITIES, server_time: new Date(this.now()).toISOString(), limits: { ...LIMITS3, ...this.limits } };
     if (observe) {
       if (bridge || human || params.claim !== void 0 || params.resume !== void 0)
-        throw new RelayError2("invalid_params", "an observer hello has no bridge, human, claim or resume");
+        throw new RelayError3("invalid_params", "an observer hello has no bridge, human, claim or resume");
       conn.role = "observer";
       conn.machine = typeof named === "string" ? named : null;
       this.save(socket);
@@ -2015,11 +2526,11 @@ var RelayHub = class _RelayHub {
     }
     const machine = named;
     const base = { ...info, machine };
-    if (bridge && this.transient.has(socket)) throw new RelayError2("invalid_params", "a bridge connects over the WebSocket");
+    if (bridge && this.transient.has(socket)) throw new RelayError3("invalid_params", "a bridge connects over the WebSocket");
     if (human && typeof params.tty !== "boolean")
-      throw new RelayError2("invalid_params", "a human hello says whether a terminal is attached (tty: true or false)");
+      throw new RelayError3("invalid_params", "a human hello says whether a terminal is attached (tty: true or false)");
     if (human) {
-      if (!fullLogin(conn.grant)) throw new RelayError2("unauthorized", "a scoped token acts as an agent: use --as");
+      if (!fullLogin(conn.grant)) throw new RelayError3("unauthorized", "a scoped token acts as an agent: use --as");
       const endpoint2 = core.claimHuman(params.tty);
       conn.role = "client";
       conn.machine = machine;
@@ -2046,8 +2557,8 @@ var RelayHub = class _RelayHub {
       core.record("bridge", null, machine, { machine });
       return { ...base, endpoints: core.remoteViews({ except: machine }), others: this.othersOf(conn.grant, machine) };
     }
-    if (one2(this.deps.sql, `SELECT kind FROM machines WHERE name = ?`, machine)?.kind === "bridge") {
-      throw new RelayError2(
+    if (one3(this.deps.sql, `SELECT kind FROM machines WHERE name = ?`, machine)?.kind === "bridge") {
+      throw new RelayError3(
         "invalid_params",
         `machine ${machine} is linked through its broker's bridge; run the command there without --cloud, or pick another --machine`
       );
@@ -2068,23 +2579,23 @@ var RelayHub = class _RelayHub {
   }
   /** refuses a machine bound to another token, a revoked token's machine to anyone but its member or an admin, or one past the machine cap; returns whether this token already holds it */
   bindable(machine, grant) {
-    const bound = one2(this.deps.sql, `SELECT token_id FROM machines WHERE name = ?`, machine);
+    const bound = one3(this.deps.sql, `SELECT token_id FROM machines WHERE name = ?`, machine);
     if (bound && bound.token_id !== grant.tokenId) {
       this.relay.record("refuse", null, machine, { code: "unauthorized", machine });
-      throw new RelayError2("unauthorized", `machine ${machine} is bound to another token; release it with ${CLI_NAME} machines rm ${machine}`);
+      throw new RelayError3("unauthorized", `machine ${machine} is bound to another token; release it with ${CLI_NAME} machines rm ${machine}`);
     }
     if (bound) return true;
-    const tomb = one2(this.deps.sql, `SELECT actor_id FROM machine_tombstones WHERE name = ?`, machine);
+    const tomb = one3(this.deps.sql, `SELECT actor_id FROM machine_tombstones WHERE name = ?`, machine);
     if (tomb && !fullOf(grant, tomb.actor_id) && !accountAdmin(grant)) {
       this.relay.record("refuse", null, machine, { code: "unauthorized", machine });
-      throw new RelayError2(
+      throw new RelayError3(
         "unauthorized",
         `machine ${machine} was unbound when its token was revoked; a full login of the same member (or an org owner or admin) can take it back, or ${CLI_NAME} machines rm ${machine} drops its queued messages`
       );
     }
-    const count = one2(this.deps.sql, `SELECT COUNT(*) AS n FROM machines`).n;
+    const count = one3(this.deps.sql, `SELECT COUNT(*) AS n FROM machines`).n;
     if (count >= this.limits.machines)
-      throw new RelayError2("too_large", `at most ${this.limits.machines} machines per account; release one with ${CLI_NAME} machines rm`);
+      throw new RelayError3("too_large", `at most ${this.limits.machines} machines per account; release one with ${CLI_NAME} machines rm`);
     return false;
   }
   /** binds the machine to the token once its hello succeeded; `held` is what bindable() returned */
@@ -2141,7 +2652,7 @@ var RelayHub = class _RelayHub {
       case "machines_rm":
         return this.releaseMachine(socket, params.name);
     }
-    if (!me) throw new RelayError2("unauthorized", "this connection has no endpoint");
+    if (!me) throw new RelayError3("unauthorized", "this connection has no endpoint");
     switch (method) {
       case "whoami":
         return core.whoami(me);
@@ -2151,15 +2662,14 @@ var RelayHub = class _RelayHub {
         const send = { ...params };
         delete send.wait_s;
         if (method === "ask") send.kind = "request";
-        const bytes = this.room(me, send.body);
-        const result = core.within(conn.machine, () => core.send(me, send, conn.tty === void 0 ? {} : { tty: conn.tty }));
-        if (!result.duplicate) this.stash(bytes);
-        if (!result.duplicate) this.delivered(me, result, send.kind ?? "message");
-        if (method === "send") return result;
+        const origin = conn.tty === void 0 ? {} : { tty: conn.tty };
+        const gate = this.judgeGate();
+        const result = gate ? await gate.send(me, send, { ...origin, machine: conn.machine }, this.deliverJudged) : this.deliverOn(conn.machine, me, send, origin);
+        if (method === "send" || result.held) return result;
         return this.awaitReply(socket, me, result.id, this.waitMs(socket, params.wait_s), result);
       }
       case "ask_wait": {
-        if (typeof params.id !== "string") throw new RelayError2("invalid_params", "id is the request's message id");
+        if (typeof params.id !== "string") throw new RelayError3("invalid_params", "id is the request's message id");
         return this.awaitReply(socket, me, params.id, this.waitMs(socket, params.wait_s));
       }
       case "inbox": {
@@ -2187,7 +2697,7 @@ var RelayHub = class _RelayHub {
         return row;
       }
     }
-    throw new RelayError2("method_not_found", `no method ${method}`);
+    throw new RelayError3("method_not_found", `no method ${method}`);
   }
   async bridgeMethod(socket, method, params) {
     const core = this.relay;
@@ -2225,20 +2735,19 @@ var RelayHub = class _RelayHub {
         const send = { ...object(params.params, "params") };
         serverFields(send);
         const asked = params.hop_floor ?? 0;
-        if (!Number.isInteger(asked) || asked < 0 || asked > 1e3) throw new RelayError2("invalid_params", "hop_floor is a hop count");
+        if (!Number.isInteger(asked) || asked < 0 || asked > 1e3) throw new RelayError3("invalid_params", "hop_floor is a hop count");
         if ([send.to].flat().some((to) => core.foreignAccount(to) !== null)) return this.xsend(sender, send, { tty: params.tty === true, hop: asked });
         delete send.attachments;
-        const floor = Math.min(asked, LIMITS2.hopMax + 1);
+        const floor = Math.min(asked, LIMITS3.hopMax + 1);
         if (floor > 0) core.markReceived(sender, floor - 1);
-        const bytes = this.room(sender, send.body);
-        const result = core.within(machine, () => core.send(sender, send, { tty: params.tty === true }));
-        if (!result.duplicate) this.stash(bytes);
-        if (!result.duplicate) this.delivered(sender, result, send.kind ?? "message");
-        return result;
+        const gate = this.judgeGate();
+        const origin = { tty: params.tty === true };
+        if (gate) return gate.send(sender, send, { ...origin, machine }, this.deliverJudged);
+        return this.deliverOn(machine, sender, send, origin);
       }
       case "subscribe": {
         const after = params.after ?? 0;
-        if (!Number.isInteger(after) || after < 0) throw new RelayError2("invalid_params", "after is a seq");
+        if (!Number.isInteger(after) || after < 0) throw new RelayError3("invalid_params", "after is a seq");
         if (this.deps.crossAccount) core.xsenders(await this.xinbound());
         conn.subscribed = true;
         this.save(socket);
@@ -2275,7 +2784,7 @@ var RelayHub = class _RelayHub {
         this.save(socket);
         return core.snapshot({ activity: 20 });
     }
-    throw new RelayError2("method_not_found", `no method ${method} on a bridge`);
+    throw new RelayError3("method_not_found", `no method ${method} on a bridge`);
   }
   // other accounts
   /**
@@ -2287,22 +2796,22 @@ var RelayHub = class _RelayHub {
     const core = this.relay;
     const link = this.deps.crossAccount;
     const targets = [send.to].flat();
-    const missing = () => new RelayError2("not_found", `no endpoint ${targets.map(String).join(", ")}`);
-    if (targets.length !== 1) throw new RelayError2("invalid_params", "a message to another account goes to exactly one endpoint: no lists, groups or tree:");
+    const missing = () => new RelayError3("not_found", `no endpoint ${targets.map(String).join(", ")}`);
+    if (targets.length !== 1) throw new RelayError3("invalid_params", "a message to another account goes to exactly one endpoint: no lists, groups or tree:");
     const target = core.foreignAccount(targets[0]);
     if (!target || !link || !this.xcounters || !this.xkey) throw missing();
-    if (typeof send.body !== "string") throw new RelayError2("invalid_params", "body must be a string");
+    if (typeof send.body !== "string") throw new RelayError3("invalid_params", "body must be a string");
     const bytes = new TextEncoder().encode(send.body).length;
-    if (bytes > XLIMITS.bodyBytes) throw new RelayError2("too_large", `a message to another account is at most ${XLIMITS.bodyBytes} bytes; this one is ${bytes}`);
+    if (bytes > XLIMITS.bodyBytes) throw new RelayError3("too_large", `a message to another account is at most ${XLIMITS.bodyBytes} bytes; this one is ${bytes}`);
     if (send.attachments !== void 0 && !(Array.isArray(send.attachments) && !send.attachments.length))
-      throw new RelayError2("data_class_refused", "attachments stay in this account");
-    if (send.data_class === "private") throw new RelayError2("data_class_refused", "a private message stays in this account");
-    if (send.data_class !== void 0 && send.data_class !== "public") throw new RelayError2("invalid_params", "data_class must be public or private");
+      throw new RelayError3("data_class_refused", "attachments stay in this account");
+    if (send.data_class === "private") throw new RelayError3("data_class_refused", "a private message stays in this account");
+    if (send.data_class !== void 0 && send.data_class !== "public") throw new RelayError3("invalid_params", "data_class must be public or private");
     const kind = send.kind ?? "message";
-    if (!MESSAGE_KINDS2.includes(kind)) throw new RelayError2("invalid_params", `kind must be one of ${MESSAGE_KINDS2.join(", ")}`);
-    if (send.reply_to !== void 0 && typeof send.reply_to !== "string") throw new RelayError2("invalid_params", "reply_to is a message id");
+    if (!MESSAGE_KINDS2.includes(kind)) throw new RelayError3("invalid_params", `kind must be one of ${MESSAGE_KINDS2.join(", ")}`);
+    if (send.reply_to !== void 0 && typeof send.reply_to !== "string") throw new RelayError3("invalid_params", "reply_to is a message id");
     if (origin.hop > XLIMITS.hopMax)
-      throw new RelayError2(
+      throw new RelayError3(
         "loop_guard",
         `this message would be hop ${origin.hop} of a chain across accounts (limit ${XLIMITS.hopMax}); stop and report to your user`
       );
@@ -2317,16 +2826,16 @@ var RelayHub = class _RelayHub {
     const granted = answered && answered.from.address === address ? parent : null;
     if (!granted && !core.crossAdmission(sender, "out", target).ok) throw missing();
     const now = this.now();
-    const thread = granted?.thread ?? cleanText2(send.thread, "thread", 64) ?? newId2("thr", now);
+    const thread = granted?.thread ?? cleanText2(send.thread, "thread", 64) ?? newId3("thr", now);
     const hop = Math.max(origin.hop, granted ? answered.hop + 1 : 0);
     if (hop > XLIMITS.hopMax)
-      throw new RelayError2("loop_guard", `this message would be hop ${hop} of a chain across accounts (limit ${XLIMITS.hopMax}); stop and report to your user`);
+      throw new RelayError3("loop_guard", `this message would be hop ${hop} of a chain across accounts (limit ${XLIMITS.hopMax}); stop and report to your user`);
     this.xcounters.check(contact, me.remote, address, thread);
-    const secret = findSecret2(send.body);
-    if (secret) throw new RelayError2("secret_refused", `the message looks like it carries a credential (${secret}); send a reference instead`);
-    const ttl = send.ttl_s ?? LIMITS2.ttlDefaultS;
-    if (!Number.isInteger(ttl) || ttl < 1 || ttl > LIMITS2.ttlMaxS)
-      throw new RelayError2("invalid_params", `ttl_s must be 1 to ${LIMITS2.ttlMaxS}`);
+    const secret = findSecret3(send.body);
+    if (secret) throw new RelayError3("secret_refused", `the message looks like it carries a credential (${secret}); send a reference instead`);
+    const ttl = send.ttl_s ?? LIMITS3.ttlDefaultS;
+    if (!Number.isInteger(ttl) || ttl < 1 || ttl > LIMITS3.ttlMaxS)
+      throw new RelayError3("invalid_params", `ttl_s must be 1 to ${LIMITS3.ttlMaxS}`);
     const self = link.self;
     const own = `${self.handle}/${me.machine}/${me.handle || "me"}`;
     const human = me.kind === "human" && me.handle === "" && origin.tty;
@@ -2339,7 +2848,7 @@ var RelayHub = class _RelayHub {
       machine: me.machine,
       harness: me.harness
     };
-    const id = origin.id ?? newId2("msg", now);
+    const id = origin.id ?? newId3("msg", now);
     const expiresAt = now + ttl * 1e3;
     const declared = declaredLimits(contact.limits);
     const msg = {
@@ -2351,7 +2860,7 @@ var RelayHub = class _RelayHub {
       thread,
       reply_to: replyTo,
       hop,
-      client_id: origin.clientId ?? this.deps.hash(`${own}|${address}|${cleanText2(send.client_id, "client_id", 128) ?? newId2("cid", now)}`),
+      client_id: origin.clientId ?? this.deps.hash(`${own}|${address}|${cleanText2(send.client_id, "client_id", 128) ?? newId3("cid", now)}`),
       created_at: now,
       expires_at: expiresAt,
       ...granted?.grant ? { reply_grant: granted.grant, reply_grant_expires_at: granted.expires_at } : {},
@@ -2373,7 +2882,7 @@ var RelayHub = class _RelayHub {
     try {
       delivered = await link.deliver(contact, msg);
     } catch (error) {
-      if (!(error instanceof RelayError2) || error.code === "unavailable") refund();
+      if (!(error instanceof RelayError3) || error.code === "unavailable") refund();
       throw error;
     }
     this.fleet({ type: "message", machine: me.machine, id: delivered.id, thread, kind, from: from.address, to: [address], hop });
@@ -2396,7 +2905,7 @@ var RelayHub = class _RelayHub {
     const core = this.relay;
     const link = this.deps.crossAccount;
     const msg = parseXMessage(raw);
-    const missing = () => new RelayError2("not_found", `no endpoint ${link?.self.handle ?? this.account}/${msg.to}`);
+    const missing = () => new RelayError3("not_found", `no endpoint ${link?.self.handle ?? this.account}/${msg.to}`);
     if (!link || !this.xcounters || !this.xkey) throw missing();
     const contact = await link.contactById(fromAccountId);
     if (!contact || contact.dir === "out" || contact.peerId !== fromAccountId || msg.from.account !== contact.peerHandle) throw missing();
@@ -2412,11 +2921,11 @@ var RelayHub = class _RelayHub {
       handle: parts.length === 3 && parts[2] !== "me" ? parts[2] : ""
     };
     if (!granted && !core.crossAdmission(target.id, "in", peer).ok) throw missing();
-    if (!honestSender(msg.from)) throw new RelayError2("invalid_params", "the sender is not one its relay may name");
+    if (!honestSender(msg.from)) throw new RelayError3("invalid_params", "the sender is not one its relay may name");
     const bytes = new TextEncoder().encode(msg.body).length;
-    if (bytes > XLIMITS.bodyBytes) throw new RelayError2("too_large", `a message from another account is at most ${XLIMITS.bodyBytes} bytes`);
-    if (msg.hop > XLIMITS.hopMax) throw new RelayError2("loop_guard", `hop ${msg.hop} is past the limit across accounts (${XLIMITS.hopMax})`);
-    if (msg.expires_at <= this.now()) throw new RelayError2("invalid_params", "the message expired");
+    if (bytes > XLIMITS.bodyBytes) throw new RelayError3("too_large", `a message from another account is at most ${XLIMITS.bodyBytes} bytes`);
+    if (msg.hop > XLIMITS.hopMax) throw new RelayError3("loop_guard", `hop ${msg.hop} is past the limit across accounts (${XLIMITS.hopMax})`);
+    if (msg.expires_at <= this.now()) throw new RelayError3("invalid_params", "the message expired");
     const earlier = core.xduplicate(fromAccountId, msg.client_id);
     if (earlier) return { id: earlier.id, state: earlier.acked ? "delivered" : "queued", duplicate: true };
     const envelope = {
@@ -2446,8 +2955,8 @@ var RelayHub = class _RelayHub {
     const message = JSON.stringify(envelope);
     const stored2 = new TextEncoder().encode(message).length;
     this.xadmit(fromAccountId, contact, msg, target, stored2);
-    const secret = findSecret2(msg.body);
-    if (secret) throw new RelayError2("secret_refused", `the message looks like it carries a credential (${secret})`);
+    const secret = findSecret3(msg.body);
+    if (secret) throw new RelayError3("secret_refused", `the message looks like it carries a credential (${secret})`);
     const verdict = judged ? { verdict: "pass" } : await link.gate.ingress(msg, { side: "ingress", account: link.self.handle, peer: contact.peerHandle, peer_id: fromAccountId });
     if (verdict.verdict === "refuse") throw gateRefusal(verdict, "ingress");
     if (verdict.verdict === "hold") return { id: msg.id, state: "queued", held: { hold_id: verdict.hold_id } };
@@ -2513,16 +3022,16 @@ var RelayHub = class _RelayHub {
     const counts = core.xcounts(fromAccountId, msg.from.address, target.remote, dayStart(now));
     const retry = (since, ms) => Math.max(1, Math.ceil(((since ?? now) + ms - now) / 1e3));
     if (counts.minute >= perMinute)
-      throw new RelayError2("rate_limited", `${perMinute} messages from ${msg.from.address} to ${msg.to} a minute`, retry(counts.minuteAt, 6e4));
+      throw new RelayError3("rate_limited", `${perMinute} messages from ${msg.from.address} to ${msg.to} a minute`, retry(counts.minuteAt, 6e4));
     if (counts.hour >= perHour)
-      throw new RelayError2("rate_limited", `${perHour} messages from ${msg.from.address} to ${msg.to} an hour`, retry(counts.hourAt, 36e5));
-    if (counts.day >= perDay) throw new RelayError2("rate_limited", `${perDay} messages from ${contact.peerHandle} today`, untilTomorrow(now));
+      throw new RelayError3("rate_limited", `${perHour} messages from ${msg.from.address} to ${msg.to} an hour`, retry(counts.hourAt, 36e5));
+    if (counts.day >= perDay) throw new RelayError3("rate_limited", `${perDay} messages from ${contact.peerHandle} today`, untilTomorrow(now));
     if (core.xthreadCount(target.remote, msg.thread) >= XLIMITS.threadMax)
-      throw new RelayError2("loop_guard", `thread ${msg.thread} reached ${XLIMITS.threadMax} messages across accounts`);
+      throw new RelayError3("loop_guard", `thread ${msg.thread} reached ${XLIMITS.threadMax} messages across accounts`);
     const cap = this.limits.storedBytes;
-    if (this.storedNow() + bytes > cap) throw new RelayError2("inbox_full", `the receiving account's relay holds its cap of ${cap} bytes of messages`);
+    if (this.storedNow() + bytes > cap) throw new RelayError3("inbox_full", `the receiving account's relay holds its cap of ${cap} bytes of messages`);
     const unread = core.xunread(target);
-    if (unread >= LIMITS2.inboxMax) throw new RelayError2("inbox_full", `${msg.to} has ${unread} unread messages`);
+    if (unread >= LIMITS3.inboxMax) throw new RelayError3("inbox_full", `${msg.to} has ${unread} unread messages`);
   }
   /**
    * deletes the queued messages of every account that is no longer an active contact allowed to message this one, after the
@@ -2561,6 +3070,44 @@ var RelayHub = class _RelayHub {
       }))
     );
   }
+  // judge
+  /** the judge, made on first use once configured; null when it is not */
+  judgeGate() {
+    if (!this.judgeConfig) return null;
+    if (this.gate) return this.gate;
+    const core = this.relay;
+    const { policy, options } = this.judgeConfig;
+    const gate = new JudgeGate({
+      sql: this.deps.sql,
+      core,
+      now: this.now,
+      env: options.env,
+      client: options.client,
+      limits: options.limits,
+      log: (line) => this.deps.log?.("relay_judge", { account: this.account, line }),
+      wake: (endpoint) => this.wake(endpoint),
+      notice: (endpoint, text) => this.xnotice(endpoint, text),
+      within: (origin, fn) => core.within(origin.machine ?? null, fn)
+    });
+    gate.configure(policy);
+    this.gate = gate;
+    return gate;
+  }
+  judged() {
+    const gate = this.judgeGate();
+    if (!gate) throw new RelayError3("not_found", "this relay has no judge");
+    return gate;
+  }
+  /** a send of this account as it runs unjudged: room for the body, the core send on the sender's machine, then push */
+  deliverOn(machine, from, send, origin) {
+    const core = this.relay;
+    const bytes = this.room(from, send.body);
+    const result = core.within(machine, () => core.send(from, send, origin));
+    if (!result.duplicate) this.stash(bytes);
+    if (!result.duplicate) this.delivered(from, result, send.kind ?? "message");
+    return result;
+  }
+  deliverJudged = async (from, send, { machine, ...origin }) => this.deliverOn(machine ?? null, from, send, origin);
   // push and wait
   delivered(from, result, kind) {
     const core = this.relay;
@@ -2583,7 +3130,7 @@ var RelayHub = class _RelayHub {
     const cap = this.limits.storedBytes;
     if (this.storedNow() + bytes > cap) {
       this.relay.record("refuse", sender, null, { code: "too_large" });
-      throw new RelayError2(
+      throw new RelayError3(
         "too_large",
         `the account relay holds its cap of ${cap} bytes of message bodies; ack or let messages expire, or release a machine with ${CLI_NAME} machines rm`
       );
@@ -2593,7 +3140,7 @@ var RelayHub = class _RelayHub {
   /** bytes of message bodies held, and of the messages from other accounts */
   storedNow() {
     const xinbox = this.deps.crossAccount ? ` + (SELECT COALESCE(SUM(LENGTH(CAST(message AS BLOB))), 0) FROM xinbox)` : "";
-    this.stored ??= one2(this.deps.sql, `SELECT (SELECT COALESCE(SUM(LENGTH(CAST(body AS BLOB))), 0) FROM messages)${xinbox} AS n`).n;
+    this.stored ??= one3(this.deps.sql, `SELECT (SELECT COALESCE(SUM(LENGTH(CAST(body AS BLOB))), 0) FROM messages)${xinbox} AS n`).n;
     return this.stored;
   }
   stash(bytes) {
@@ -2633,7 +3180,7 @@ var RelayHub = class _RelayHub {
   }
   /** `own` tells each bridge whether a bound machine is its member's own device */
   toBridges(machine, params) {
-    const bound = one2(this.deps.sql, `SELECT actor_id FROM machines WHERE name = ?`, machine);
+    const bound = one3(this.deps.sql, `SELECT actor_id FROM machines WHERE name = ?`, machine);
     for (const socket of this.deps.sockets()) {
       if (socket.conn.role !== "bridge" || socket.conn.machine === machine) continue;
       const own = bound ? { own: (bound.actor_id ?? null) === (socket.conn.grant.actorId ?? null) } : {};
@@ -2662,8 +3209,8 @@ var RelayHub = class _RelayHub {
   }
   waitMs(socket, value) {
     if (value === void 0) return 0;
-    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new RelayError2("invalid_params", "wait_s must be a number of seconds");
-    return Math.min(value, this.transient.has(socket) ? this.limits.httpWaitS : LIMITS2.waitMaxS) * 1e3;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new RelayError3("invalid_params", "wait_s must be a number of seconds");
+    return Math.min(value, this.transient.has(socket) ? this.limits.httpWaitS : LIMITS3.waitMaxS) * 1e3;
   }
   wake(endpoint) {
     const set = this.waiters.get(endpoint);
@@ -2719,7 +3266,7 @@ var RelayHub = class _RelayHub {
       const endpoint = conn.endpoint;
       core.disconnect(endpoint);
       const machine = core.machineOf(endpoint);
-      if (machine && one2(this.deps.sql, `SELECT kind FROM machines WHERE name = ?`, machine)?.kind === "bridge") {
+      if (machine && one3(this.deps.sql, `SELECT kind FROM machines WHERE name = ?`, machine)?.kind === "bridge") {
         for (const delivery of core.adoptClaimed(machine, endpoint)) this.route(delivery.seq, delivery.endpoint);
       }
       this.wake(endpoint);
@@ -2790,7 +3337,7 @@ var RelayHub = class _RelayHub {
     const traffic = pairs.flatMap((row) => {
       const from = byId.get(row.from_ep);
       const to = byId.get(row.to_ep);
-      return from && to && from !== to ? [{ kind: "message", from, to, count: row.n, last_at: iso(row.last) }] : [];
+      return from && to && from !== to ? [{ kind: "message", from, to, count: row.n, last_at: iso2(row.last) }] : [];
     });
     edges.push(...traffic.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to)));
     return { minutes: window, machines: this.machineList(), nodes, edges };
@@ -2802,10 +3349,10 @@ var RelayHub = class _RelayHub {
       kind: row.kind,
       online: sockets.some((s) => this.boundMachine(s.conn) === row.name),
       bridge: sockets.some((s) => s.conn.role === "bridge" && s.conn.machine === row.name),
-      created_at: iso(row.created_at),
-      last_seen: iso(row.last_seen)
+      created_at: iso2(row.created_at),
+      last_seen: iso2(row.last_seen)
     }));
-    const revoked = this.deps.sql.all(`SELECT name, at FROM machine_tombstones WHERE name NOT IN (SELECT name FROM machines) ORDER BY name`).map((row) => ({ name: row.name, kind: "revoked", online: false, bridge: false, created_at: null, last_seen: iso(row.at) }));
+    const revoked = this.deps.sql.all(`SELECT name, at FROM machine_tombstones WHERE name NOT IN (SELECT name FROM machines) ORDER BY name`).map((row) => ({ name: row.name, kind: "revoked", online: false, bridge: false, created_at: null, last_seen: iso2(row.at) }));
     return [...bound, ...revoked];
   }
   /**
@@ -2814,15 +3361,15 @@ var RelayHub = class _RelayHub {
    */
   releaseMachine(caller, name) {
     const core = this.relay;
-    if (typeof name !== "string" || !MACHINE_NAME.test(name)) throw new RelayError2("invalid_params", "name is a machine name");
-    const bound = one2(this.deps.sql, `SELECT token_id, actor_id FROM machines WHERE name = ?`, name);
-    const tomb = bound ? void 0 : one2(this.deps.sql, `SELECT actor_id FROM machine_tombstones WHERE name = ?`, name);
-    if (!bound && !tomb) throw new RelayError2("not_found", `no machine ${name}`);
+    if (typeof name !== "string" || !MACHINE_NAME.test(name)) throw new RelayError3("invalid_params", "name is a machine name");
+    const bound = one3(this.deps.sql, `SELECT token_id, actor_id FROM machines WHERE name = ?`, name);
+    const tomb = bound ? void 0 : one3(this.deps.sql, `SELECT actor_id FROM machine_tombstones WHERE name = ?`, name);
+    if (!bound && !tomb) throw new RelayError3("not_found", `no machine ${name}`);
     const grant = caller.conn.grant;
     const member = !!bound && bound.actor_id !== null && grant.actorId === bound.actor_id;
     if (!(bound?.token_id === grant.tokenId || fullOf(grant, (bound ?? tomb).actor_id) || accountAdmin(grant) || member && !this.liveMachines().has(name))) {
       core.record("refuse", null, name, { code: "unauthorized", machine: name });
-      throw new RelayError2(
+      throw new RelayError3(
         "unauthorized",
         `only the token machine ${name} is bound to, a full login of the member who bound it, or an org owner or admin can release it${member ? "; any credential of that member can once it is offline" : ""}`
       );
@@ -2852,14 +3399,14 @@ var RelayHub = class _RelayHub {
     );
     for (const { name } of idle) {
       if (live.has(name)) continue;
-      const queued = one2(
+      const queued = one3(
         this.deps.sql,
         `SELECT 1 FROM deliveries d JOIN endpoints e ON e.id = d.endpoint WHERE substr(e.remote, 1, ?) = ? AND d.acked_at IS NULL AND d.expires_at > ? LIMIT 1`,
         name.length + 1,
         `${name}/`,
         now
       );
-      const asking = one2(
+      const asking = one3(
         this.deps.sql,
         `SELECT 1 FROM messages m JOIN endpoints e ON e.id = m.from_ep WHERE substr(e.remote, 1, ?) = ? AND m.kind = 'request' AND m.expires_at > ?
          AND NOT EXISTS (SELECT 1 FROM messages r WHERE r.reply_to = m.id AND r.kind = 'reply') LIMIT 1`,
@@ -2885,10 +3432,10 @@ var RelayHub = class _RelayHub {
         `DELETE FROM machine_tombstones WHERE at <= ? AND NOT EXISTS (SELECT 1 FROM deliveries d JOIN endpoints e ON e.id = d.endpoint
          WHERE substr(e.remote, 1, length(machine_tombstones.name) + 1) = machine_tombstones.name || '/' AND d.acked_at IS NULL AND d.expires_at > ?)
          RETURNING name`,
-        now - (LIMITS2.ttlMaxS + LIMITS2.purgeAfterS) * 1e3,
+        now - (LIMITS3.ttlMaxS + LIMITS3.purgeAfterS) * 1e3,
         now
       );
-      const unbound = names.map((row) => row.name).filter((name) => !one2(this.deps.sql, `SELECT 1 FROM machines WHERE name = ?`, name));
+      const unbound = names.map((row) => row.name).filter((name) => !one3(this.deps.sql, `SELECT 1 FROM machines WHERE name = ?`, name));
       for (const name of unbound) this.relay.record("machine_forget", null, name, { machine: name, endpoints: this.relay.dropMachine(name, { queue: true }) });
       return unbound;
     });
@@ -2906,13 +3453,13 @@ var RelayHub = class _RelayHub {
     const at = this.deniedGrants().get(DENIED + socket.conn.grant.tokenId);
     if (at === void 0 || at <= this.now() - this.limits.deniedS * 1e3) return;
     this.kick(socket, "the token was revoked");
-    throw new RelayError2("unauthorized", "the token was revoked");
+    throw new RelayError3("unauthorized", "the token was revoked");
   }
   tx(fn) {
     return this.deps.transaction ? this.deps.transaction(fn) : fn();
   }
   state(key) {
-    return one2(this.deps.sql, `SELECT value FROM hub_state WHERE key = ?`, key)?.value ?? null;
+    return one3(this.deps.sql, `SELECT value FROM hub_state WHERE key = ?`, key)?.value ?? null;
   }
   setState(key, value) {
     this.deps.sql.all(`INSERT OR REPLACE INTO hub_state (key, value) VALUES (?, ?)`, key, value);
@@ -2927,14 +3474,14 @@ var RelayHub = class _RelayHub {
     if (hold.side === "ingress") return this.xreceive(hold.from_account, hold.message, true);
     const msg = hold.message;
     const left = Math.ceil((msg.expires_at - this.now()) / 1e3);
-    if (left < 1) throw new RelayError2("invalid_params", "the held message expired");
+    if (left < 1) throw new RelayError3("invalid_params", "the held message expired");
     const send = {
       to: `${hold.peer}/${msg.to.endsWith("/") ? `${msg.to}me` : msg.to}`,
       body: msg.body,
       kind: msg.kind,
       thread: msg.thread,
       ...msg.reply_to ? { reply_to: msg.reply_to } : {},
-      ttl_s: Math.min(left, LIMITS2.ttlMaxS)
+      ttl_s: Math.min(left, LIMITS3.ttlMaxS)
     };
     return this.xsend(hold.sender, send, { tty: msg.from.human, hop: msg.hop, judged: true, clientId: msg.client_id, id: hold.hold_id });
   }
@@ -2948,6 +3495,8 @@ export {
   GRAPH_MINUTES,
   GRAPH_MINUTES_MAX,
   HUB_LIMITS,
+  JUDGE_LIMITS,
+  JudgeGate,
   MACHINE_NAME,
   RelayHub
 };