@uuaid/pillar 2.0.2 → 2.2.0

package/src/mailbox/mailbox.mjs

@@ -69,12 +69,99 @@ export class Mailbox {
     this.db.pragma("journal_mode = WAL");
     this.db.pragma("synchronous = NORMAL");
     this.db.exec(SCHEMA);
+    // Several processes open one home at once (the courier's `inbox` beside a
+    // daemon's `recv`). A check-then-ALTER outside a lock lets the loser throw
+    // "duplicate column name", so every migration runs in ONE immediate
+    // transaction that re-reads table_info inside it: the second opener waits
+    // on the write lock (busy timeout) and then finds nothing left to add.
+    this.db.transaction(() => this._migrate()).immediate();
+  }
+
+  _migrate() {
     // v2 migration: quarantine marker (trust-policy gate). Nullable text =
     // reason; null = normal mail. Chain hashes are unaffected (metadata only).
     const cols = this.db.pragma("table_info(inbox)").map(c => c.name);
     if (!cols.includes("quarantined")) {
       this.db.exec("alter table inbox add column quarantined text");
     }
+    // v3 migration. Every column is metadata beside the chain (the chain
+    // hashes envelope_sha256 only), so none of it can alter an audit.
+    //   inbox.pulled_by   the reader key of the process that stored the row;
+    //                     lets a reader see that SOMEONE ELSE pulled its mail.
+    //   inbox.group_id    the pillar-group id the sealed payload carried.
+    //   outbox.kind/thread/group_id  what a receipt is matched against: the
+    //                     sender cannot decrypt its own sealed outbox rows.
+    //   outbox.recipient_* the recipient's own signed ack / read receipt.
+    //                     `status = 'delivered'` keeps meaning what it always
+    //                     meant: a CARRIER accepted the envelope.
+    const addCols = (table, specs) => {
+      const have = new Set(this.db.pragma(`table_info(${table})`).map(c => c.name));
+      for (const [name, type] of specs) {
+        if (!have.has(name)) this.db.exec(`alter table ${table} add column ${name} ${type}`);
+      }
+    };
+    addCols("inbox", [["pulled_by", "text"], ["group_id", "text"]]);
+    addCols("outbox", [
+      ["kind", "text"], ["thread", "text"], ["group_id", "text"], ["group_msg_id", "text"],
+      ["recipient_ack_at", "text"], ["recipient_ack_id", "text"], ["recipient_read_at", "text"],
+    ]);
+    this.db.exec(`
+      create table if not exists readers (
+        name        text primary key,
+        cursor      integer not null default 0,
+        pid         integer,
+        host        text,
+        cwd         text,
+        command     text,
+        last_seen   text
+      );
+      create table if not exists reader_leases (
+        reader      text not null,
+        host        text not null,
+        pid         integer not null,
+        cwd         text,
+        command     text,
+        started_at  text not null,
+        lease_until text not null,
+        primary key (reader, host, pid)
+      );
+      create table if not exists groups (
+        id          text primary key,
+        name        text not null,
+        members     text not null,
+        keys        text,
+        created_by  text,
+        created_at  text not null,
+        updated_at  text not null,
+        pending     integer not null default 0,
+        left_at     text
+      );
+      create table if not exists group_v2_sendq (
+        id             text primary key,
+        group_id       text not null,
+        recipient      text not null,
+        recipient_key  text,
+        op             text not null,
+        mv_version     integer not null,
+        want_from      integer,
+        want_to        integer,
+        manifest_hash  text,
+        conflicts_with text,
+        queued_at      text not null,
+        state          text not null default 'queued',
+        state_at       text,
+        envelope_id    text,
+        reason         text
+      );
+      create index if not exists group_v2_sendq_state on group_v2_sendq (state, group_id);
+      create index if not exists inbox_group on inbox (group_id);
+      create index if not exists outbox_thread on outbox (recipient, thread);
+    `);
+    // groups.v2_synced_at: set when the pillar-group/2 sync writes the row (the
+    // verified head minus leavers). A marked row is a v2 group's for good: v1 tags
+    // and `pillar group` verbs naming it go to v2 (Pillar._receive, groupCommandRoute),
+    // and with its v2 store file gone it is cleared, not handed back to v1.
+    addCols("groups", [["v2_synced_at", "text"]]);
   }
 
   close() { try { this.db.close(); } catch (_e) {} }
@@ -108,16 +195,17 @@ export class Mailbox {
    * and MUST include at least `id`, `recipient`, `createdAt`.  Chain hash is computed
    * atomically with the insert; concurrent appends are serialized via the SQLite transaction.
    */
-  appendOutbound(envelope) {
+  appendOutbound(envelope, { thread = null, groupId = null, groupMsgId = null } = {}) {
     return this.db.transaction(() => {
       const envSha = Mailbox.envelopeSha(envelope);
       const prev = this._getHead("outbox");
       const chainInput = prev == null ? CHAIN_SEED + envSha : prev + envSha;
       const chain = createHash("sha256").update(chainInput).digest("hex");
       this.db.prepare(`
-        insert into outbox (envelope_id, envelope_sha256, recipient, created_at, envelope_json, chain_hash, status)
-        values (?, ?, ?, ?, ?, ?, 'pending')
-      `).run(envelope.id, envSha, envelope.recipient, envelope.createdAt, JSON.stringify(envelope), chain);
+        insert into outbox (envelope_id, envelope_sha256, recipient, created_at, envelope_json, chain_hash, status, kind, thread, group_id, group_msg_id)
+        values (?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?, ?)
+      `).run(envelope.id, envSha, envelope.recipient, envelope.createdAt, JSON.stringify(envelope), chain,
+        envelope.kind ?? null, thread ?? envelope.id, groupId, groupMsgId);
       this._setHead("outbox", chain);
       return { envelopeId: envelope.id, envelopeSha256: envSha, chainHash: chain };
     })();
@@ -126,23 +214,24 @@ export class Mailbox {
   /**
    * Append an incoming envelope.  Same shape.  MUST be idempotent on envelope.id;
    * a duplicate delivery does NOT re-append and does NOT advance the chain.
+   * `pulledBy` is the reader key of the storing process (metadata only).
    */
-  appendInbound(envelope) {
+  appendInbound(envelope, { pulledBy = null } = {}) {
     return this.db.transaction(() => {
-      const existing = this.db.prepare("select envelope_id, envelope_sha256 from inbox where envelope_id = ?").get(envelope.id);
+      const existing = this.db.prepare("select seq, envelope_id, envelope_sha256 from inbox where envelope_id = ?").get(envelope.id);
       if (existing) {
-        return { duplicate: true, envelopeId: envelope.id, envelopeSha256: existing.envelope_sha256 };
+        return { duplicate: true, seq: existing.seq, envelopeId: envelope.id, envelopeSha256: existing.envelope_sha256 };
       }
       const envSha = Mailbox.envelopeSha(envelope);
       const prev = this._getHead("inbox");
       const chainInput = prev == null ? CHAIN_SEED + envSha : prev + envSha;
       const chain = createHash("sha256").update(chainInput).digest("hex");
-      this.db.prepare(`
-        insert into inbox (envelope_id, envelope_sha256, sender, received_at, envelope_json, chain_hash)
-        values (?, ?, ?, ?, ?, ?)
-      `).run(envelope.id, envSha, envelope.sender ?? envelope.from ?? "unknown", new Date().toISOString(), JSON.stringify(envelope), chain);
+      const r = this.db.prepare(`
+        insert into inbox (envelope_id, envelope_sha256, sender, received_at, envelope_json, chain_hash, pulled_by)
+        values (?, ?, ?, ?, ?, ?, ?)
+      `).run(envelope.id, envSha, envelope.sender ?? envelope.from ?? "unknown", new Date().toISOString(), JSON.stringify(envelope), chain, pulledBy);
       this._setHead("inbox", chain);
-      return { duplicate: false, envelopeId: envelope.id, envelopeSha256: envSha, chainHash: chain };
+      return { duplicate: false, seq: Number(r.lastInsertRowid), envelopeId: envelope.id, envelopeSha256: envSha, chainHash: chain };
     })();
   }
 
@@ -191,11 +280,206 @@ export class Mailbox {
       .run(String(reason).slice(0, 100), envelopeId);
   }
 
+  // ── pillar-group/2 send queue: what the v2 receiver asked to send ─────────
+  // Nothing is sent from here. A row leaves only through an explicit command
+  // (Pillar.syncGroupV2), and an egress filter can read every queued recipient
+  // with: select recipient from group_v2_sendq where state = 'queued'.
+
+  static GROUP_V2_SENDQ_MAX = 1000;
+
+  /** Queue sends ({ to, key?, op, mvVersion, want?, manifestHash?, conflictsWith? }). Returns the ids queued. */
+  enqueueGroupV2Sends(groupId, sends, { now = new Date().toISOString(), newId }) {
+    const ids = [];
+    this.db.transaction(() => {
+      let queued = this.db.prepare("select count(*) as n from group_v2_sendq where state = 'queued'").get().n;
+      const ins = this.db.prepare(`insert into group_v2_sendq (id, group_id, recipient, recipient_key, op, mv_version, want_from, want_to, manifest_hash, conflicts_with, queued_at)
+        values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+      for (const s of sends) {
+        if (queued >= Mailbox.GROUP_V2_SENDQ_MAX) break; // bounded: the caller counts what did not fit
+        const id = newId();
+        ins.run(id, groupId, s.to, s.key ?? null, s.op, s.mvVersion, s.want?.from ?? null, s.want ? s.want.to : null,
+          s.manifestHash ?? null, s.conflictsWith ?? null, now);
+        ids.push(id);
+        queued++;
+      }
+    }).immediate();
+    return ids;
+  }
+
+  /** Queued rows, oldest first; one group or all. */
+  queuedGroupV2Sends(groupId = null) {
+    return groupId
+      ? this.db.prepare("select * from group_v2_sendq where state = 'queued' and group_id = ? order by queued_at, rowid").all(groupId)
+      : this.db.prepare("select * from group_v2_sendq where state = 'queued' order by queued_at, rowid").all();
+  }
+
+  /** state: sent | dropped (final), or queued with a reason (a failed attempt). */
+  markGroupV2Send(id, state, { envelopeId = null, reason = null } = {}) {
+    this.db.prepare("update group_v2_sendq set state = ?, state_at = ?, envelope_id = coalesce(?, envelope_id), reason = ? where id = ?")
+      .run(state, new Date().toISOString(), envelopeId, reason ? String(reason).slice(0, 200) : null, id);
+  }
+
+  clearQuarantine(envelopeId) {
+    this.db.prepare("update inbox set quarantined = null where envelope_id = ?").run(envelopeId);
+  }
+
   markInboxRead(envelopeId) {
     this.db.prepare("update inbox set read_at = ? where envelope_id = ? and read_at is null")
       .run(new Date().toISOString(), envelopeId);
   }
 
+  setInboundGroup(envelopeId, groupId) {
+    this.db.prepare("update inbox set group_id = ? where envelope_id = ?").run(groupId, envelopeId);
+  }
+
+  inboxTipSeq() {
+    return this.db.prepare("select coalesce(max(seq), 0) as n from inbox").get().n;
+  }
+
+  /** Non-quarantined rows after `seq`, oldest first — what a reader has not seen. */
+  inboxAfter(seq = 0, limit = 500) {
+    return this.db.prepare("select * from inbox where seq > ? and quarantined is null order by seq asc limit ?").all(seq, limit);
+  }
+
+  // ── Readers ────────────────────────────────────────────────────────────────
+  // A reader is one consumer of this home's inbox, with its OWN cursor over
+  // the local inbox table. The carrier cursor stays shared (carrier_cursors):
+  // fetching is idempotent on envelope id, so whoever pulls, every reader
+  // still sees the row after its own cursor.
+
+  getReader(name) {
+    return this.db.prepare("select * from readers where name = ?").get(name) ?? null;
+  }
+
+  listReaders() {
+    return this.db.prepare("select * from readers order by name").all();
+  }
+
+  /** Create or refresh a reader's last-run details; never moves its cursor. */
+  touchReader(name, { pid = null, host = null, cwd = null, command = null, cursor = 0 } = {}) {
+    this.db.prepare(`
+      insert into readers (name, cursor, pid, host, cwd, command, last_seen)
+      values (?, ?, ?, ?, ?, ?, ?)
+      on conflict(name) do update set pid = excluded.pid, host = excluded.host, cwd = excluded.cwd,
+        command = excluded.command, last_seen = excluded.last_seen
+    `).run(name, cursor, pid, host, cwd, command, new Date().toISOString());
+  }
+
+  setReaderCursor(name, seq) {
+    this.db.prepare("update readers set cursor = max(cursor, ?) where name = ?").run(seq, name);
+  }
+
+  /** A long-running consumer (pillar recv) holds a lease; renew it on a heartbeat. */
+  holdLease(reader, { host, pid, cwd = null, command = null, ttlMs = 90_000 }) {
+    const now = new Date();
+    this.db.prepare(`
+      insert into reader_leases (reader, host, pid, cwd, command, started_at, lease_until)
+      values (?, ?, ?, ?, ?, ?, ?)
+      on conflict(reader, host, pid) do update set lease_until = excluded.lease_until
+    `).run(reader, host, pid, cwd, command, now.toISOString(), new Date(now.getTime() + ttlMs).toISOString());
+  }
+
+  releaseLease(reader, { host, pid }) {
+    this.db.prepare("delete from reader_leases where reader = ? and host = ? and pid = ?").run(reader, host, pid);
+  }
+
+  /** Leases not yet expired. The caller decides which are really alive (pid check). */
+  unexpiredLeases() {
+    this.db.prepare("delete from reader_leases where lease_until < ?").run(new Date(Date.now() - 3600_000).toISOString());
+    return this.db.prepare("select * from reader_leases where lease_until >= ? order by started_at").all(new Date().toISOString());
+  }
+
+  // ── Receipts (the recipient's own signed ack / read receipt) ──────────────
+
+  /** Record a recipient-signed ack. Only for a row actually sent TO `from`. */
+  markOutboundAcked(envelopeId, { from, ackId = null, at = null }) {
+    const r = this.db.prepare(`
+      update outbox set recipient_ack_at = coalesce(recipient_ack_at, ?), recipient_ack_id = coalesce(recipient_ack_id, ?)
+      where envelope_id = ? and recipient = ?
+    `).run(at ?? new Date().toISOString(), ackId, envelopeId, from);
+    return r.changes > 0;
+  }
+
+  /** Mark rows read (read implies acked: a missing ack is backfilled). */
+  markOutboundRead(envelopeIds, { at = null } = {}) {
+    const ts = at ?? new Date().toISOString();
+    const stmt = this.db.prepare(`
+      update outbox set recipient_read_at = coalesce(recipient_read_at, ?), recipient_ack_at = coalesce(recipient_ack_at, ?)
+      where envelope_id = ?
+    `);
+    let n = 0;
+    this.db.transaction(() => { for (const id of envelopeIds) n += stmt.run(ts, ts, id).changes; })();
+    return n;
+  }
+
+  /** Outbound rows to one recipient, oldest first (receipt matching). */
+  outboundTo(recipient) {
+    return this.db.prepare("select * from outbox where recipient = ? order by seq asc").all(recipient);
+  }
+
+  outboxRecent(limit = 20) {
+    return this.db.prepare("select * from outbox order by seq desc limit ?").all(limit);
+  }
+
+  // ── Groups (pillar-group v1 rosters, INTERACTION-CONVENTION.md) ───────────
+
+  _groupRow(row) {
+    if (!row) return null;
+    return {
+      id: row.id,
+      name: row.name,
+      members: JSON.parse(row.members),
+      keys: row.keys ? JSON.parse(row.keys) : {},
+      createdBy: row.created_by,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+      pending: !!row.pending,
+      left: !!row.left_at,
+    };
+  }
+
+  getGroup(id) {
+    return this._groupRow(this.db.prepare("select * from groups where id = ?").get(id));
+  }
+
+  listGroups() {
+    return this.db.prepare("select * from groups order by updated_at desc").all().map(r => this._groupRow(r));
+  }
+
+  /** Mark a groups row as written by the pillar-group/2 sync (see _migrate). The row must exist. */
+  markGroupV2(id, at = new Date().toISOString()) {
+    this.db.prepare("update groups set v2_synced_at = ? where id = ?").run(at, id);
+  }
+
+  isGroupV2Marked(id) {
+    return !!this.db.prepare("select v2_synced_at from groups where id = ?").get(id)?.v2_synced_at;
+  }
+
+  /** Ids of every row the v2 sync has marked. */
+  groupV2MarkedIds() {
+    return this.db.prepare("select id from groups where v2_synced_at is not null order by id").all().map(r => r.id);
+  }
+
+  putGroup(g) {
+    const now = new Date().toISOString();
+    this.db.prepare(`
+      insert into groups (id, name, members, keys, created_by, created_at, updated_at, pending, left_at)
+      values (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      on conflict(id) do update set name = excluded.name, members = excluded.members, keys = excluded.keys,
+        updated_at = excluded.updated_at, pending = excluded.pending, left_at = excluded.left_at
+    `).run(g.id, g.name, JSON.stringify(g.members), JSON.stringify(g.keys ?? {}), g.createdBy ?? null,
+      g.createdAt ?? now, now, g.pending ? 1 : 0, g.left ? (g.leftAt ?? now) : null);
+    return this.getGroup(g.id);
+  }
+
+  groupInbound(groupId, limit = 50) {
+    return this.db.prepare("select * from inbox where group_id = ? and quarantined is null order by seq desc limit ?").all(groupId, limit).reverse();
+  }
+
+  groupOutbound(groupId, limit = 200) {
+    return this.db.prepare("select * from outbox where group_id = ? order by seq desc limit ?").all(groupId, limit).reverse();
+  }
+
   /**
    * Recompute the outbox chain from scratch and compare to stored chain_hash column.
    * Returns { ok, badSeq? }.  Used by adversarial tests + operator-driven audits.

package/src/net/carrier-client.mjs

@@ -20,6 +20,21 @@ function byTier(tiers) {
   return (a, b) => seedTier(tiers[a] ?? "probation").listRank - seedTier(tiers[b] ?? "probation").listRank;
 }
 
+/**
+ * The carrier's signed acceptance receipt (uuaid.carrier-receipt.v1), kept as
+ * the carrier sent it, plus this client's own clock when the answer arrived
+ * (design §12 rule 3: record received-at beside the carrier's acceptedAt,
+ * which is only the carrier's claim). NOT verified here: verify against the
+ * pinned key for this carrier and the exact envelope posted. {} when the
+ * carrier sent no receipt (an older or keyless carrier): that never fails a
+ * delivery, the outcome is simply unreceipted.
+ */
+function keptReceipt(body) {
+  const r = body?.receipt;
+  if (!r || typeof r !== "object" || Array.isArray(r) || typeof body.receiptSig !== "string") return {};
+  return { receipt: r, receiptSig: body.receiptSig, receivedAt: new Date().toISOString() }; // @rule client.keeps-receipt
+}
+
 export class CarrierClient {
   /**
    * @param {{keychain: import('../identity/keychain.mjs').Keychain, carriers: string[]}} opts
@@ -66,8 +81,13 @@ export class CarrierClient {
    * Resolves once every carrier has answered.  Succeeds if at least one
    * accepted; throws if every carrier rejects.  Returns the receipt from the
    * most PROVEN accepting carrier as the primary ({ carrier, seq, sha,
-   * duplicate }) plus `all` with every carrier's outcome ({ carrier, ok,
-   * seq?, sha?, duplicate?, error?, status?, reason?, fix? }).
+   * duplicate, receipt?, receiptSig?, receivedAt? }) plus `all` with every
+   * carrier's outcome ({ carrier, ok, seq?, sha?, duplicate?, receipt?,
+   * receiptSig?, receivedAt?, error?, status?, reason?, fix? }).
+   *
+   * `receipt` / `receiptSig` are present only when that carrier signed one
+   * (uuaid.carrier-receipt.v1); they are unverified carrier output, and
+   * `receivedAt` is this client's clock, not the carrier's.
    *
    * When every carrier refuses, the thrown error carries `code` (the most
    * proven carrier's `reason`, else carrier-unreachable / carrier-bad-response),
@@ -105,7 +125,7 @@ export class CarrierClient {
         let body = {};
         try { body = raw ? JSON.parse(raw) : {}; } catch (_error) {}
         if (res.status === 202 && body.accepted) {
-          return { carrier: base, ok: true, seq: body.seq, sha: body.sha, duplicate: !!body.duplicate };
+          return { carrier: base, ok: true, seq: body.seq, sha: body.sha, duplicate: !!body.duplicate, ...keptReceipt(body) };
         }
         const reason = typeof body.reason === "string" && body.reason ? body.reason
           : typeof body.error === "string" && body.error ? body.error : null;
@@ -132,15 +152,15 @@ export class CarrierClient {
       throw e;
     }
     const ranked = accepted.slice().sort((a, b) => byTier(this.carrierTiers)(a.carrier, b.carrier));
-    const { carrier, seq, sha, duplicate } = ranked[0];
-    return { carrier, seq, sha, duplicate, all };
+    const { carrier, seq, sha, duplicate, receipt, receiptSig, receivedAt } = ranked[0];
+    return { carrier, seq, sha, duplicate, ...(receipt ? { receipt, receiptSig, receivedAt } : {}), all };
   }
 
   /**
    * Fetch envelopes addressed to us with seq > since from a specific carrier.
    * Signed request; carrier verifies our key before serving.
    */
-  async fetchInbox(base, { since = 0, waitS = 0, timeoutMs = 40000 } = {}) {
+  async fetchInbox(base, { since = 0, waitS = 0, timeoutMs = 40000, signal = null } = {}) {
     const path = `GET /v1/inbox/${this.uuaid}?since=${since}`;
     const ts = String(Date.now());
     const sig = this.keychain.sign(Buffer.from(`${path}\n${ts}`, "utf-8")).toString("hex");
@@ -150,7 +170,9 @@ export class CarrierClient {
         "x-pillar-ts": ts,
         "x-pillar-sig": sig,
       },
-      signal: AbortSignal.timeout(timeoutMs),
+      // `signal` lets a caller cancel a long-poll early (peekCarrierInbox stops
+      // the other carriers once one has mail).
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
     });
     if (res.status !== 200) {
       const body = await res.json().catch(() => ({}));

package/src/net/carrier-receipt.mjs

@@ -0,0 +1,77 @@
+/**
+ * uuaid.carrier-receipt.v1 — the carrier's signed acceptance receipt.
+ *
+ * Design: uuaid docs/designs/2026-10-18-carrier-acceptance-receipt.md (§2 wire,
+ * §12 binding rules). A carrier configured with a receipt key answers an
+ * accepted POST /v1/envelopes with `receipt` + `receiptSig`, where receiptSig
+ * is Ed25519 (hex) over the UTF-8 bytes of
+ *
+ *     "uuaid.carrier-receipt.v1" + "\n" + JCS({ the 10 fields below })
+ *
+ * The fixed prefix is domain separation: a receipt can never be mistaken for
+ * the seed identity document (bare JCS, first byte "{"), an auth.v1 assertion
+ * or a directory listing, even when the same key signs them.
+ *
+ * A receipt is the carrier key holder's attributable claim of acceptance,
+ * sequence, time and a retention commitment. It does not prove delivery, the
+ * disk write or the clock (§12 rule 3).
+ *
+ * Verification lives in the clients (@uuaid/pillar-client verifyCarrierReceipt);
+ * this module is what the carrier signs, and is byte-identical to the
+ * pillar-client `carrierReceiptSigningString` (checked against the shared
+ * vectors in test/unit/carrier-receipt.test.mjs).
+ */
+import { jcs } from "../identity/jcs.mjs";
+import { SELF_CERTIFYING_NAMESPACES, localIdFromKey } from "../identity/keychain.mjs";
+
+export const CARRIER_RECEIPT_TYPE = "uuaid.carrier-receipt.v1";
+
+/** The exact receipt keys, in JCS (sorted) order. */
+export const CARRIER_RECEIPT_FIELDS = Object.freeze([
+  "acceptedAt", "carrier", "duplicate", "envelopeId", "envelopeSha",
+  "recipient", "retainUntil", "sender", "seq", "v",
+]);
+
+const ISO_MS_Z = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+const AGENT_UUAID = new RegExp(`^uuaid:(${SELF_CERTIFYING_NAMESPACES.join("|")}):agent:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`);
+const isParty = (s) => typeof s === "string" && s.length > "uuaid:".length && s.startsWith("uuaid:");
+
+/** The exact string whose UTF-8 bytes the carrier signs. Only the 10 receipt keys are covered. */
+export function carrierReceiptSigningString(fields) {
+  const body = {};
+  for (const k of CARRIER_RECEIPT_FIELDS) body[k] = fields[k];
+  return `${CARRIER_RECEIPT_TYPE}\n${jcs(body)}`;
+}
+
+/** The carrier uuaid a receipt key derives: uuaid:foundation:agent:<localIdFromKey(key)>. */
+export function carrierUuaidFromKey(publicKeyHex) {
+  return `uuaid:foundation:agent:${localIdFromKey(Buffer.from(publicKeyHex, "hex"))}`;
+}
+
+function isIsoMs(s) {
+  return typeof s === "string" && ISO_MS_Z.test(s) && !Number.isNaN(Date.parse(s)) && new Date(s).toISOString() === s;
+}
+
+/**
+ * True when `r` is a receipt a v1 verifier can accept on shape alone: exactly
+ * the 10 keys, v 1, seq a safe integer >= 1, boolean duplicate, ISO-8601 UTC
+ * millisecond times with retainUntil after acceptedAt, a key-derived agent
+ * uuaid as carrier, a non-empty envelopeId, a 64-hex envelopeSha and uuaid
+ * parties: the same schema rules as the pillar-client verifier. The carrier
+ * checks this before signing, so it never signs a claim no client could verify.
+ */
+export function carrierReceiptShapeOk(r) {
+  if (!r || typeof r !== "object" || Array.isArray(r)) return false;
+  const keys = Object.keys(r).sort();
+  if (keys.length !== CARRIER_RECEIPT_FIELDS.length || keys.some((k, i) => k !== CARRIER_RECEIPT_FIELDS[i])) return false;
+  if (r.v !== 1) return false;
+  if (!Number.isSafeInteger(r.seq) || r.seq < 1) return false;
+  if (typeof r.duplicate !== "boolean") return false;
+  if (!isIsoMs(r.acceptedAt) || !isIsoMs(r.retainUntil)) return false;
+  if (!(Date.parse(r.retainUntil) > Date.parse(r.acceptedAt))) return false;
+  if (typeof r.carrier !== "string" || !AGENT_UUAID.test(r.carrier)) return false;
+  if (typeof r.envelopeId !== "string" || !r.envelopeId) return false;
+  if (typeof r.envelopeSha !== "string" || !HEX64.test(r.envelopeSha)) return false;
+  return isParty(r.sender) && isParty(r.recipient);
+}