@uuaid/pillar 2.0.3 → 2.3.0

package/src/groups.mjs

@@ -0,0 +1,175 @@
+/**
+ * Group threads — the `pillar-group` v1 app convention (INTERACTION-CONVENTION.md
+ * "group chats"), as the mobile app and chat-web already speak it.
+ *
+ * There is still no group key and no wire change: a group message is one
+ * ordinary 1:1 envelope per member, and the group rides INSIDE each sealed
+ * payload as `_group`. What this adds over the old `{ name, members }` tag is
+ * what makes it a thread rather than a fan-out:
+ *
+ *   id      stable `grp-<16 hex>`, so every member files it under one group
+ *   msgId   `gm-…`, identical across the fan-out copies of one message
+ *   op      message | create | rename | add | leave (roster changes travel
+ *           as ordinary group messages)
+ *   keys    optional sealing hints, binding-checked on receipt, so members
+ *           can reply to the whole group without a prior contact exchange
+ *
+ * Every member keeps its own roster (mailbox `groups` table) and applies the
+ * same rules: only a current member may rename or add, nobody can remove
+ * anyone but themselves, and a group a non-contact drops you into is a
+ * pending invitation until you accept it.
+ */
+import { randomBytes } from "node:crypto";
+import { localIdFromKey } from "./identity/keychain.mjs";
+
+export const GROUP_TAG_KEY = "_group";
+export const GROUP_TAG_V = 1;
+export const GROUP_OPS = Object.freeze(["message", "create", "rename", "add", "leave"]);
+export const MAX_GROUP_MEMBERS = 256;
+export const MAX_GROUP_NAME = 100;
+
+const GROUP_ID_RE = /^grp-[a-z0-9][a-z0-9-]{3,63}$/i;
+const UUAID_RE = /^uuaid:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9][a-z0-9-]*$/i;
+const PUBKEY_RE = /^[0-9a-f]{64}$/i;
+
+export function isGroupId(id) {
+  return typeof id === "string" && GROUP_ID_RE.test(id);
+}
+
+export function newGroupId() {
+  return `grp-${randomBytes(8).toString("hex")}`;
+}
+
+export function newGroupMsgId() {
+  return `gm-${Date.now().toString(36)}-${randomBytes(6).toString("hex")}`;
+}
+
+/** The key really owns the uuaid (the same check seal() makes). */
+export function keyBindsUuaid(uuaid, publicKeyHex) {
+  if (typeof uuaid !== "string" || typeof publicKeyHex !== "string" || !PUBKEY_RE.test(publicKeyHex)) return false;
+  try { return localIdFromKey(Buffer.from(publicKeyHex, "hex")) === uuaid.split(":")[3]; }
+  catch { return false; }
+}
+
+function djb2(s) {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+  return h;
+}
+
+/**
+ * A local id for an id-less tag (an older pillar that sent only
+ * `{ name, members }`). Same derivation as the mobile app, so the same
+ * conversation groups the same way there and here. Never an authority.
+ */
+export function deriveGroupId(name, members) {
+  const canon = `${String(name).trim().toLowerCase()}|${[...members].sort().join(",")}`;
+  const a = djb2(canon).toString(16).padStart(8, "0");
+  const b = djb2(canon.split("").reverse().join("")).toString(16).padStart(8, "0");
+  return `grp-ref-${a}${b}`;
+}
+
+/** Deduplicated, validated member list, order kept. */
+export function normalizeMembers(members) {
+  const out = [];
+  const seen = new Set();
+  for (const m of Array.isArray(members) ? members : []) {
+    if (typeof m !== "string" || !UUAID_RE.test(m) || seen.has(m)) continue;
+    seen.add(m);
+    out.push(m);
+    if (out.length >= MAX_GROUP_MEMBERS) break; // fan-out amplification guard
+  }
+  return out;
+}
+
+/** Parse a `_group` tag out of a decrypted payload; null when absent or unusable. */
+export function extractGroupTag(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const g = payload[GROUP_TAG_KEY];
+  if (!g || typeof g !== "object" || Array.isArray(g)) return null;
+  const name = typeof g.name === "string" ? g.name.trim().slice(0, MAX_GROUP_NAME) : "";
+  const members = normalizeMembers(g.members);
+  if (!members.length) return null;
+  const derivedId = !isGroupId(g.id);
+  const id = derivedId ? deriveGroupId(name || "group", members) : g.id;
+  let keys;
+  if (g.keys && typeof g.keys === "object" && !Array.isArray(g.keys)) {
+    for (const [u, pk] of Object.entries(g.keys)) {
+      if (UUAID_RE.test(u) && typeof pk === "string" && PUBKEY_RE.test(pk)) (keys ??= {})[u] = pk.toLowerCase();
+    }
+  }
+  const msgId = typeof g.msgId === "string" && g.msgId.length > 0 && g.msgId.length <= 64 ? g.msgId : null;
+  const op = typeof g.op === "string" && GROUP_OPS.includes(g.op) ? g.op : "message";
+  return { v: typeof g.v === "number" ? g.v : GROUP_TAG_V, id, name: name || "Group", members, keys, msgId, op, derivedId };
+}
+
+/** The `_group` tag for an outbound payload. */
+export function buildGroupTag(group, { msgId, keys, op = "message" }) {
+  const tag = { v: GROUP_TAG_V, id: group.id, name: group.name, members: [...group.members], msgId };
+  if (keys && Object.keys(keys).length) tag.keys = keys;
+  if (op && op !== "message") tag.op = op;
+  return tag;
+}
+
+/**
+ * Fold an inbound tag into the local roster (mailbox `groups`). Returns the
+ * group as stored, or null when the tag changed nothing we keep.
+ *
+ *   unknown group -> join it; pending when the sender is not a contact. A
+ *                    wire id (not derived here) needs the SENDER on its own
+ *                    roster: the first tag seen for an id sets the roster, so
+ *                    a stranger must not be able to seed it, and after that
+ *                    the real members would be the strangers
+ *   known group   -> only a current MEMBER may change it: `leave` drops the
+ *                    sender, `create`/`rename` set the name, every op unions
+ *                    new members in; a re-`add` naming us clears our `left`
+ *   key hints     -> kept per group, only when the key derives its uuaid;
+ *                    they let us SEAL to a member, and never make anyone a
+ *                    trusted sender (the address book and trust.json do that)
+ */
+export function absorbGroupTag(mailbox, tag, { sender, self, text = "", fromContact = false }) {
+  const hints = {};
+  for (const [u, pk] of Object.entries(tag.keys ?? {})) {
+    if (u !== self && keyBindsUuaid(u, pk)) hints[u] = pk;
+  }
+  const existing = mailbox.getGroup(tag.id);
+  if (!existing) {
+    if (!tag.derivedId && !tag.members.includes(sender)) return null;
+    const members = tag.members.includes(self) ? tag.members : [...tag.members, self];
+    return mailbox.putGroup({
+      id: tag.id, name: tag.name, members, keys: hints, createdBy: sender, pending: !fromContact,
+    });
+  }
+  if (!existing.members.includes(sender)) return existing; // strangers cannot touch our roster
+  const keys = { ...hints, ...existing.keys }; // first key wins
+  if (tag.op === "leave") {
+    return mailbox.putGroup({ ...existing, keys, members: existing.members.filter((m) => m !== sender) });
+  }
+  const members = [...existing.members];
+  for (const m of tag.members) if (!members.includes(m) && members.length < MAX_GROUP_MEMBERS) members.push(m);
+  const addedUs = tag.op === "add" && String(text).split(",").map((x) => x.trim()).includes(self);
+  return mailbox.putGroup({
+    ...existing,
+    keys,
+    members,
+    name: tag.op === "rename" || tag.op === "create" ? tag.name : existing.name,
+    left: existing.left && !addedUs,
+  });
+}
+
+/**
+ * Resolve a group by exact id, else by unique case-insensitive name.
+ * Throws with the candidates listed when the name is ambiguous or unknown.
+ */
+export function findGroup(mailbox, ref) {
+  const byId = mailbox.getGroup(ref);
+  if (byId) return byId;
+  const all = mailbox.listGroups();
+  const hits = all.filter((g) => g.name.toLowerCase() === String(ref).toLowerCase());
+  if (hits.length === 1) return hits[0];
+  const e = new Error(hits.length
+    ? `group name "${ref}" is ambiguous: ${hits.map((g) => g.id).join(", ")} — use the id`
+    : `no group "${ref}" in this home${all.length ? ` (known: ${all.map((g) => `${g.name} ${g.id}`).join("; ")})` : ""} — list them with: pillar groups`);
+  e.code = hits.length ? "group-ambiguous" : "group-unknown";
+  throw e;
+}

package/src/identity/jcs.mjs

@@ -2,16 +2,27 @@
  * RFC 8785 JCS canonicalization.  Same implementation as the pillar-core reference,
  * kept independent so the pillar-node package has no upward dependency.
  *
- * Numbers: integers only (safe for the wire we design; enforce it).  Floats
- * throw because deterministic ECMA-262 number serialization requires more code
- * than we want in a reference impl and this package's message payloads never
- * legitimately contain non-integer numbers.
+ * Numbers — two entry points with one byte rule for integers:
+ *   jcs()         INTEGERS ONLY; floats throw. Every transport document (envelopes,
+ *                 delegations, receipts, escrow terms, blobs, VDA) keeps using it, so
+ *                 what the carrier and escrow refuse is unchanged — escrow v1/v2 rely
+ *                 on that throw to reject a hostile offer (src/escrow/terms.mjs).
+ *   jcsRfc8785()  full RFC 8785 §3.2.2.3 numbers (ECMAScript Number::toString, i.e.
+ *                 JSON.stringify(n)); used only for the SEALED PAYLOAD (crypto/e2e.mjs
+ *                 sealPayload) and documents carried inside it (PAM-1, AinFi). Byte-
+ *                 identical to jcs() for every finite integer. Added 2026-10-24 so an
+ *                 agent can send a device a value such as 21.5; byte-matches
+ *                 @uuaid/pillar-client jcsRfc8785.
  */
 export function jcs(value) {
-  return _ser(value);
+  return _ser(value, false);
 }
 
-function _ser(v) {
+export function jcsRfc8785(value) {
+  return _ser(value, true);
+}
+
+function _ser(v, fractions) {
   if (v === null) return "null";
   if (v === true) return "true";
   if (v === false) return "false";
@@ -19,16 +30,17 @@ function _ser(v) {
   if (typeof v === "number") {
     if (!Number.isFinite(v)) throw new Error("JCS: NaN/Infinity not permitted");
     if (Number.isInteger(v)) return String(v);
+    if (fractions) return JSON.stringify(v); // RFC 8785 §3.2.2.3
     throw new Error("JCS: non-integer numbers not permitted; use string decimal encoding");
   }
   if (typeof v === "bigint") return v.toString();
-  if (Array.isArray(v)) return "[" + v.map(_ser).join(",") + "]";
+  if (Array.isArray(v)) return "[" + v.map((x) => _ser(x, fractions)).join(",") + "]";
   if (typeof v === "object") {
     // RFC 8785 §3.2.3: keys sort by their UTF-16 code units, which is exactly
     // JavaScript's default string order. (Comparing UTF-16LE *bytes* is not: it
     // puts "Ā" (U+0100) before "a", and disagreed with @uuaid/pillar-client.)
     const keys = Object.keys(v).sort(); // @rule jcs.code-unit-order
-    return "{" + keys.map(k => JSON.stringify(k) + ":" + _ser(v[k])).join(",") + "}";
+    return "{" + keys.map(k => JSON.stringify(k) + ":" + _ser(v[k], fractions)).join(",") + "}";
   }
   throw new Error("JCS: unsupported type " + typeof v);
 }

package/src/identity/keychain.mjs

@@ -65,6 +65,54 @@ export function localIdFromKey(rawPub) {
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
 }
 
+/** Registry namespaces cannot be asserted by possession of a key alone. */
+export const SELF_CERTIFYING_NAMESPACES = Object.freeze(["foundation", "pillar", "agentnet"]);
+
+/**
+ * The namespace `pillar init` mints a NEW agent identity in when no --namespace is given.
+ * Expand before contract (owner order 2026-10-24; Uuaid-Codex review K1): 2.2.0 makes every
+ * verifier accept foundation, pillar and agentnet but still mints `foundation`, because a
+ * `pillar:` identity cannot read its inbox on a pre-2.2.0 carrier. 2.2.1 flips this to
+ * `pillar` once the carrier fleet, the main relay and the blob brokers run 2.2.x/1.2.0.
+ * Existing keychains keep the UUAID they were saved with. `Keychain.generate`'s own default
+ * stays `foundation` for library callers; CLI mint sites pass `mintNamespace(...)` instead.
+ */
+export const NEW_IDENTITY_NAMESPACE = "foundation";
+
+/**
+ * Carrier-infrastructure identities (pillar-seed, pillar-directory, pillar-escrow) stay in
+ * `foundation`: they are spoken to by third-party seeds and DHT peers on any version, and
+ * the owner's rule covers the identities people create, not the fleet's service keys
+ * (Uuaid-Codex review K2).
+ */
+export const SERVICE_IDENTITY_NAMESPACE = "foundation";
+
+/** The namespace to mint in: `requested` if it is self-certifying, else NEW_IDENTITY_NAMESPACE. Throws on any other namespace. */
+export function mintNamespace(requested) {
+  if (requested === undefined || requested === null) return NEW_IDENTITY_NAMESPACE;
+  if (typeof requested !== "string" || !SELF_CERTIFYING_NAMESPACES.includes(requested)) {
+    throw new Error(`namespace must be one of ${SELF_CERTIFYING_NAMESPACES.join(", ")} (a key alone cannot claim ${String(requested)})`);
+  }
+  return requested;
+}
+
+/** Rebuild the complete key-derived identity; minting still defaults to foundation. */
+export function keyDerivedUuaidFor(publicKeyHex, { namespace = "foundation", objectType = "agent" } = {}) {
+  if (!SELF_CERTIFYING_NAMESPACES.includes(namespace)
+    || typeof objectType !== "string" || !/^[a-z0-9-]+$/.test(objectType)
+    || typeof publicKeyHex !== "string" || !/^[0-9a-f]{64}$/i.test(publicKeyHex)) return null;
+  return `uuaid:${namespace}:${objectType}:${localIdFromKey(Buffer.from(publicKeyHex, "hex"))}`;
+}
+
+/** Compare the full identity, optionally constraining a path's existing object type. */
+export function keyDerivesUuaid(publicKeyHex, uuaid, objectType = null) {
+  if (typeof uuaid !== "string") return false;
+  const parts = uuaid.split(":");
+  if (parts.length !== 4 || parts[0] !== "uuaid" || (objectType !== null && parts[2] !== objectType)) return false;
+  const expected = keyDerivedUuaidFor(publicKeyHex, { namespace: parts[1], objectType: parts[2] });
+  return expected !== null && uuaid === expected;
+}
+
 export class Keychain {
   constructor(path) {
     this.path = path;
@@ -78,8 +126,9 @@ export class Keychain {
   /**
    * Generate a fresh identity.  Never overwrites.
    *
-   * uuaidNamespace: default "foundation" per IAASO-1001 today; will support
-   * federated forms once federation profile ratifies.
+   * uuaidNamespace: default "foundation" (the genesis namespace) for library
+   * callers. The Pillar CLIs pass mintNamespace(...) explicitly, so a new CLI
+   * identity is `pillar` unless the operator asks for agentnet or foundation.
    * objectType: default "agent"; overridable to "service" etc.
    * localId: default random UUIDv4-like; caller may supply.
    */

package/src/index.mjs

@@ -7,8 +7,8 @@
  * Entry point.  Not intended for import in browsers today — browser build
  * lives at @uuaid/pillar-browser (later).
  */
-export { Keychain, localIdFromKey } from "./identity/keychain.mjs";
-export { jcs } from "./identity/jcs.mjs";
+export { Keychain, localIdFromKey, SELF_CERTIFYING_NAMESPACES, NEW_IDENTITY_NAMESPACE, SERVICE_IDENTITY_NAMESPACE, mintNamespace, keyDerivedUuaidFor, keyDerivesUuaid } from "./identity/keychain.mjs";
+export { jcs, jcsRfc8785 } from "./identity/jcs.mjs";
 export { seal, open, decrypt, envelopeSha, keychainSeed, ENVELOPE_VERSION, E2E_ALG } from "./net/envelope.mjs";
 export { DELEGATION_VERSION, verifyDelegationDoc, delegationCoversKind } from "./net/delegation.mjs";
 export { sealPayload, openPayload, edPubToX25519, edSeedToX25519 } from "./crypto/e2e.mjs";

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.