@uuaid/agent-commons 0.0.0 → 0.2.0-alpha.4

package/src/spaces/store.mjs

@@ -0,0 +1,325 @@
+/**
+ * The space store (design §8). Additive; imports the vendored pillar engine
+ * ONLY through ./pillar-group.mjs (C9). Computes no engine-vs-client hash
+ * (C13/V-7). Never opens engine.db (F9); it only hands back the path.
+ *
+ * Layout under <commonsHome>/spaces/ (all dirs 0700, all files 0600, atomic):
+ *   groups-v2/grp-<32 hex>.json   roster record, via the vendored RosterStore
+ *   grp-<32 hex>/adapter.json     adapter state (this file)
+ *   grp-<32 hex>/engine.db        this space's own engine store (path only)
+ *   dispatcher.json               per-carrier cursors
+ */
+import { randomBytes } from "node:crypto";
+import {
+  chmodSync, closeSync, fsyncSync, mkdirSync, openSync,
+  readFileSync, renameSync, writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { RosterStore, isGroupIdV2 } from "./pillar-group.mjs";
+
+export const ADAPTER_V = "commons-space-adapter/1";
+export const DISPATCHER_V = "commons-space-dispatcher/1";
+export const PENDING_TTL_MS = 60 * 60 * 1000; // S-3: a pending removal lives at most 1 hour
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const HARD_REASONS = ["outsider", "policy-mismatch"]; // A-4, P-9 (HS-1)
+const SOFT_REASONS = ["reconsent"]; // P-12 (HS-1)
+
+// Exact key sets, one per level. A strict set at every level is what refuses a
+// `policy`/`agents` key anywhere (S-4: policy is derived, never stored) and a
+// `body` inside a heldRefs entry (L-6: metadata only) — neither is in a set.
+const ADAPTER_KEYS = ["v", "groupId", "channels", "profile", "consent", "outsiderScan", "hardStop", "softStop", "pendingRemovals", "heldRefs"];
+const CHANNELS_KEYS = ["content", "control"];
+const PROFILE_KEYS = ["id", "hash"];
+const CONSENT_KEYS = ["manifestVersion", "charterHash", "carriers"];
+const OUTSIDER_SCAN_KEYS = ["version", "hash"];
+const STOP_KEYS = ["reason", "at"];
+const PENDING_KEYS = ["uuaid", "key", "manifestVersion", "queuedAt", "outboxId"];
+const HELDREF_KEYS = ["ref", "groupId", "from", "msgId", "receivedAt"];
+const DISPATCHER_KEYS = ["v", "cursors"];
+
+const plain = (o) => o !== null && typeof o === "object" && !Array.isArray(o);
+const nonEmptyString = (s) => typeof s === "string" && s.length > 0;
+const hex64 = (s) => typeof s === "string" && HEX64.test(s);
+const safeInt = (n) => Number.isSafeInteger(n);
+const posInt = (n) => safeInt(n) && n >= 1;
+const nonNegInt = (n) => safeInt(n) && n >= 0;
+
+function exactKeys(obj, keys) {
+  if (!plain(obj)) return false;
+  const own = Object.keys(obj);
+  if (own.length !== keys.length) return false;
+  return keys.every((k) => Object.hasOwn(obj, k));
+}
+
+/** A named error, so a caller (and a pole) can tell a bad shape from an absent file. */
+export class SpaceStoreError extends Error {
+  constructor(name, message) { super(message); this.name = name; }
+}
+const badId = (id) => new SpaceStoreError("GroupIdError", `not a v2 group id: ${String(id)}`);
+const badAdapter = (why) => new SpaceStoreError("AdapterStateError", `adapter.json: ${why}`);
+const badDispatcher = (why) => new SpaceStoreError("DispatcherStateError", `dispatcher.json: ${why}`);
+
+function validateStop(stop, reasons, label) {
+  if (stop === null) return;
+  if (!exactKeys(stop, STOP_KEYS)) throw badAdapter(`${label}: expected null or {reason, at}`);
+  if (!reasons.includes(stop.reason)) throw badAdapter(`${label}.reason: not one of ${reasons.join("|")}`);
+  if (!safeInt(stop.at)) throw badAdapter(`${label}.at: not a safe integer`);
+}
+
+/**
+ * Strict shape check of an adapter state. Throws AdapterStateError on any
+ * deviation. When `id` is given, the record's groupId must match it.
+ */
+export function validateAdapterState(state, id) {
+  if (!exactKeys(state, ADAPTER_KEYS)) throw badAdapter("top-level key set is not exact (a policy/agents key is refused here, S-4)");
+  if (state.v !== ADAPTER_V) throw badAdapter(`v: expected ${ADAPTER_V}`);
+  if (!isGroupIdV2(state.groupId)) throw badAdapter("groupId: not a v2 group id");
+  if (id !== undefined && state.groupId !== id) throw badAdapter("groupId does not match the space it is stored under");
+  if (!exactKeys(state.channels, CHANNELS_KEYS)) throw badAdapter("channels: expected {content, control}");
+  if (!nonEmptyString(state.channels.content)) throw badAdapter("channels.content: not a non-empty string");
+  if (!nonEmptyString(state.channels.control)) throw badAdapter("channels.control: not a non-empty string");
+  if (!exactKeys(state.profile, PROFILE_KEYS)) throw badAdapter("profile: expected {id, hash}");
+  if (!nonEmptyString(state.profile.id)) throw badAdapter("profile.id: not a non-empty string");
+  if (!hex64(state.profile.hash)) throw badAdapter("profile.hash: not a 64-hex sha256");
+  if (!exactKeys(state.consent, CONSENT_KEYS)) throw badAdapter("consent: expected {manifestVersion, charterHash, carriers}");
+  if (!posInt(state.consent.manifestVersion)) throw badAdapter("consent.manifestVersion: not a positive safe integer");
+  if (!hex64(state.consent.charterHash)) throw badAdapter("consent.charterHash: not a 64-hex sha256");
+  if (!Array.isArray(state.consent.carriers)) throw badAdapter("consent.carriers: not an array");
+  if (!state.consent.carriers.every(nonEmptyString)) throw badAdapter("consent.carriers: every entry must be a non-empty string");
+  if (!exactKeys(state.outsiderScan, OUTSIDER_SCAN_KEYS) || !posInt(state.outsiderScan.version) || !hex64(state.outsiderScan.hash)) throw badAdapter("outsiderScan: expected {version: positive safe integer, hash: 64-hex}");
+  validateStop(state.hardStop, HARD_REASONS, "hardStop");
+  validateStop(state.softStop, SOFT_REASONS, "softStop");
+  if (!Array.isArray(state.pendingRemovals)) throw badAdapter("pendingRemovals: not an array");
+  for (const e of state.pendingRemovals) {
+    if (!exactKeys(e, PENDING_KEYS)) throw badAdapter("pendingRemovals entry: expected {uuaid, key, manifestVersion, queuedAt, outboxId}");
+    if (!nonEmptyString(e.uuaid)) throw badAdapter("pendingRemovals.uuaid: not a non-empty string");
+    if (!hex64(e.key)) throw badAdapter("pendingRemovals.key: not a 64-hex public key");
+    if (!posInt(e.manifestVersion)) throw badAdapter("pendingRemovals.manifestVersion: not a positive safe integer");
+    if (!safeInt(e.queuedAt)) throw badAdapter("pendingRemovals.queuedAt: not a safe integer");
+    if (!nonEmptyString(e.outboxId)) throw badAdapter("pendingRemovals.outboxId: not a non-empty string");
+  }
+  if (!Array.isArray(state.heldRefs)) throw badAdapter("heldRefs: not an array");
+  for (const e of state.heldRefs) {
+    if (!exactKeys(e, HELDREF_KEYS)) throw badAdapter("heldRefs entry: expected exactly {ref, groupId, from, msgId, receivedAt} (a body is refused here, L-6)");
+    if (!nonEmptyString(e.ref)) throw badAdapter("heldRefs.ref: not a non-empty string");
+    if (!isGroupIdV2(e.groupId)) throw badAdapter("heldRefs.groupId: not a v2 group id");
+    if (!nonEmptyString(e.from)) throw badAdapter("heldRefs.from: not a non-empty string");
+    if (!nonEmptyString(e.msgId)) throw badAdapter("heldRefs.msgId: not a non-empty string");
+    if (!safeInt(e.receivedAt)) throw badAdapter("heldRefs.receivedAt: not a safe integer");
+  }
+}
+
+function validateDispatcher(d) {
+  if (!exactKeys(d, DISPATCHER_KEYS)) throw badDispatcher("top-level key set is not exact");
+  if (d.v !== DISPATCHER_V) throw badDispatcher(`v: expected ${DISPATCHER_V}`);
+  if (!plain(d.cursors)) throw badDispatcher("cursors: not an object");
+  for (const [url, seq] of Object.entries(d.cursors)) {
+    if (!nonEmptyString(url)) throw badDispatcher("cursors: a carrier url key is empty");
+    if (!nonNegInt(seq)) throw badDispatcher(`cursors[${url}]: not a non-negative safe integer`);
+  }
+}
+
+/** temp 0600 + wx, fsync, rename — the RosterStore.save pattern (groups-v2.mjs:414-426). */
+function atomicWrite0600(filePath, text) {
+  const tmp = `${filePath}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+  writeFileSync(tmp, text, { mode: 0o600, flag: "wx" });
+  const fd = openSync(tmp, "r");
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+  renameSync(tmp, filePath);
+}
+
+/**
+ * S-3 load-time pruning. Re-checks every pendingRemovals entry against the
+ * roster record VERIFIED IN THE SAME CALL. An entry is kept only if (a) the
+ * verified head shows the row removed with the same key, (b) the verified chain
+ * carries the manifest at manifestVersion showing that row removed and
+ * manifestVersion <= head.version, and (c) now - queuedAt <= 1 hour and
+ * queuedAt <= now. Anything else is dropped, with one reason per entry.
+ * `now` is injectable for tests.
+ *
+ * Contract: `rec` MUST be the output of `loadRoster(id)` (i.e. of the vendored
+ * `RosterStore.load`), so it is a record whose chain verified from version 1 in
+ * that same call. This function does not verify `rec` — it trusts it — and an
+ * unverified or hand-built chain is accepted and read literally.
+ *
+ * Every clause is written KEEP-ONLY-IF, never drop-if: a keep widens policy
+ * (P-7 puts pending rows into `agents`), so anything this function cannot
+ * positively prove in-window is dropped. That includes a clock it cannot
+ * compare with: a `now` that is not a safe integer (undefined, NaN, a string,
+ * a fraction, a value past 2^53-1) drops every entry as `bad-clock`, and an
+ * entry whose own `queuedAt` is not a safe integer drops as `bad-entry`,
+ * because each comparison against such a value is false or coerced and a
+ * negated clause would read that as "in window".
+ */
+export function prunePendingRemovals(entries, rec, now) {
+  const kept = [];
+  const dropped = [];
+  const head = rec && Array.isArray(rec.chain) && rec.chain.length > 0 ? rec.chain[rec.chain.length - 1] : null;
+  for (const e of entries) {
+    let reason = null;
+    if (!rec || !head) {
+      reason = "roster-absent"; // no verified roster -> nothing grants a keep
+    } else {
+      // (a) verified head
+      const hrow = head.members?.find((r) => r.uuaid === e.uuaid);
+      if (!hrow) reason = "head-no-row";
+      else if (hrow.status !== "removed") reason = "head-not-removed";
+      else if (hrow.key !== e.key) reason = "head-key-mismatch";
+      // (b) verified chain carries the manifest at manifestVersion
+      if (reason === null) {
+        const man = rec.chain.find((m) => m.version === e.manifestVersion);
+        if (!man) reason = "chain-manifest-absent";
+        // Unreachable on a VERIFIED record: verifyChain (groups-v2.mjs:281) forces
+        // contiguous versions 1..N via verifyNext's prev/version checks, so a manifest
+        // present in the chain can never exceed the head. Kept because (i) the brief
+        // names "manifestVersion <= head.version" as a keep-condition and a reviewer
+        // reads the code against that text, (ii) it is a guard against a future change
+        // to the vendored verifyChain, and (iii) this function is exported and trusts
+        // its `rec` argument, so a hand-built out-of-order chain does reach it (pinned
+        // by a unit test).
+        else if (e.manifestVersion > head.version) reason = "manifest-ahead-of-head";
+        else {
+          const mrow = man.members?.find((r) => r.uuaid === e.uuaid);
+          if (!mrow || mrow.status !== "removed") reason = "chain-not-removed";
+        }
+      }
+      // (c) the 1-hour window, and no future stamp. KEEP-ONLY-IF: the clause is
+      // written as the positive keep condition, so a `now` that cannot be compared
+      // (undefined, NaN, a string, a fraction, a value past 2^53-1) drops as
+      // `bad-clock` instead of keeping. Written as "drop if X", both comparisons are
+      // false for such a `now`, which reads as "in window" and keeps a removed member
+      // authorized past the 1-hour bound. A safe integer is required, not merely a
+      // finite one: `Number.isFinite(now0 + 0.5)` is true, yet a fractional clock
+      // compares loosely against an integer stamp and cannot pin the window exactly.
+      // The entry's own stamp is held to the same bar — this function is exported and
+      // trusts its arguments, so an in-memory entry (a later slice's policy writer) can
+      // reach it with a string `queuedAt` that `<=` and `-` would silently coerce.
+      if (reason === null && !Number.isSafeInteger(now)) reason = "bad-clock";
+      else if (reason === null && !Number.isSafeInteger(e.queuedAt)) reason = "bad-entry";
+      else if (reason === null && !(e.queuedAt <= now && now - e.queuedAt <= PENDING_TTL_MS)) {
+        reason = e.queuedAt > now ? "future-stamp" : "expired";
+      }
+    }
+    if (reason === null) kept.push(e);
+    else dropped.push({ entry: e, reason });
+  }
+  return { kept, dropped };
+}
+
+export class SpaceStore {
+  /** @param {string} commonsHome the engine home chosen by the operator */
+  constructor(commonsHome) {
+    if (!nonEmptyString(commonsHome)) throw new SpaceStoreError("BadHomeError", "commonsHome: not a non-empty string");
+    this.commonsHome = commonsHome;
+    this.spacesHome = join(commonsHome, "spaces");
+    // The vendored RosterStore makes groups-v2/ (0700) and writes 0600 atomically itself.
+    this._roster = new RosterStore(this.spacesHome);
+  }
+
+  _ensureSpaces() {
+    mkdirSync(this.spacesHome, { recursive: true, mode: 0o700 });
+    chmodSync(this.spacesHome, 0o700);
+  }
+
+  _assertId(id) { if (!isGroupIdV2(id)) throw badId(id); }
+
+  /** spaces/grp-<id>/ — validated before any fs call (P7). */
+  groupDir(id) { this._assertId(id); return join(this.spacesHome, id); }
+  /** spaces/grp-<id>/adapter.json */
+  adapterPath(id) { return join(this.groupDir(id), "adapter.json"); }
+  /** spaces/grp-<id>/engine.db — path only; F9 gives one engine store per space. Never opened here. */
+  engineDbPath(id) { return join(this.groupDir(id), "engine.db"); }
+  /** spaces/dispatcher.json */
+  dispatcherPath() { return join(this.spacesHome, "dispatcher.json"); }
+  /** spaces/groups-v2/grp-<id>.json (the vendored roster record path). */
+  rosterPath(id) { this._assertId(id); return this._roster.path(id); }
+
+  // ── roster (S-1, F13) ──────────────────────────────────────────────────
+
+  /** Delegates to RosterStore.save, which refuses an unverified record (S-1). */
+  saveRoster(rec) {
+    // Verify before create: RosterStore.save runs checkStoreRecord and throws BEFORE
+    // its own mkdir, so an unverified record never makes spaces/ exist.
+    this._roster.save(rec); // throws if the chain does not verify / head mismatches
+    this._ensureSpaces(); // tighten spaces/ to 0700 once the record is known good
+  }
+
+  /** The verified record, or null. Any read, parse or verify failure reads as ABSENT (F13). */
+  loadRoster(id) {
+    this._assertId(id);
+    try { return this._roster.load(id); } catch { return null; }
+  }
+
+  // ── adapter.json ───────────────────────────────────────────────────────
+
+  /** Validates the strict shape, then writes 0600 atomically under grp-<id>/. */
+  saveAdapter(id, state) {
+    this._assertId(id);
+    validateAdapterState(state, id);
+    this._ensureSpaces(); // tighten a pre-existing spaces/ to 0700 before writing under it
+    const dir = this.groupDir(id);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    atomicWrite0600(this.adapterPath(id), JSON.stringify(state));
+  }
+
+  /**
+   * Loads adapter state and runs S-3 pruning against the roster verified in the
+   * same call. A MISSING file reads as null (no adapter state yet). A CORRUPT or
+   * wrong-shape file THROWS — it never defaults, because defaulting would turn a
+   * lost hardStop into "no stop" and widen authority (CL-1, HS-1).
+   * @returns {null | { state: object, dropped: Array<{entry, reason}> }}
+   */
+  loadAdapter(id, { now = Date.now() } = {}) {
+    this._assertId(id);
+    // The `= Date.now()` default catches only `undefined`. An explicitly passed
+    // NaN or "abc" flows through to prunePendingRemovals, whose keep-only-if clause
+    // drops every entry as `bad-clock` — a non-finite clock fails closed here too.
+    const p = this.adapterPath(id);
+    // Only ENOENT means "absent". Read inside try/catch instead of existsSync,
+    // which reports EACCES and ENOTDIR as absent too — so a grp dir at mode 000, or a
+    // grp path replaced by a regular file, would read a latched hardStop as "no state"
+    // and widen authority (CL-1, HS-1).
+    let raw;
+    try { raw = readFileSync(p, "utf-8"); }
+    catch (e) {
+      if (e.code === "ENOENT") return null;
+      throw badAdapter(`unreadable: ${e.code}: ${e.message}`);
+    }
+    let parsed;
+    try { parsed = JSON.parse(raw); } catch (e) { throw badAdapter(`not valid JSON: ${e.message}`); }
+    validateAdapterState(parsed, id); // throws AdapterStateError on a bad shape
+    const rec = this.loadRoster(id); // verified in THIS call
+    const { kept, dropped } = prunePendingRemovals(parsed.pendingRemovals, rec, now);
+    const state = { ...parsed, pendingRemovals: kept };
+    return { state, dropped };
+  }
+
+  // ── dispatcher.json ────────────────────────────────────────────────────
+
+  /** Validates and writes 0600 atomically at spaces/dispatcher.json. */
+  saveDispatcher(d) {
+    validateDispatcher(d);
+    this._ensureSpaces();
+    atomicWrite0600(this.dispatcherPath(), JSON.stringify(d));
+  }
+
+  /** A missing file means empty cursors; a bad shape throws (never defaults). */
+  loadDispatcher() {
+    const p = this.dispatcherPath();
+    // Only ENOENT means "empty cursors". Any other read failure (EACCES on a
+    // spaces/ at mode 000, ENOTDIR if the path is a file) throws the named error —
+    // existsSync would report those as absent and silently lose every cursor.
+    let raw;
+    try { raw = readFileSync(p, "utf-8"); }
+    catch (e) {
+      if (e.code === "ENOENT") return { v: DISPATCHER_V, cursors: {} };
+      throw badDispatcher(`unreadable: ${e.code}: ${e.message}`);
+    }
+    let parsed;
+    try { parsed = JSON.parse(raw); } catch (e) { throw badDispatcher(`not valid JSON: ${e.message}`); }
+    validateDispatcher(parsed);
+    return parsed;
+  }
+}

package/src/store.mjs

@@ -0,0 +1,73 @@
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync, chmodSync } from "node:fs";
+import { dirname } from "node:path";
+import { digest } from "./profiles.mjs";
+
+export class CommonsStore {
+  constructor(path=":memory:") {
+    if(path!==":memory:")mkdirSync(dirname(path),{recursive:true,mode:0o700});
+    this.db=new DatabaseSync(path);
+    this.db.exec(`PRAGMA journal_mode=WAL; CREATE TABLE IF NOT EXISTS kv(k TEXT PRIMARY KEY,v TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS envelopes(seq INTEGER PRIMARY KEY AUTOINCREMENT,id TEXT NOT NULL UNIQUE,sender TEXT NOT NULL,recipient TEXT NOT NULL,sha TEXT NOT NULL,body TEXT NOT NULL,expires INTEGER NOT NULL);
+      CREATE INDEX IF NOT EXISTS inbox_recipient ON envelopes(recipient,seq);
+      CREATE TABLE IF NOT EXISTS events(seq INTEGER PRIMARY KEY AUTOINCREMENT,id TEXT NOT NULL UNIQUE,previous TEXT NOT NULL,hash TEXT NOT NULL,body TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS outbox(id TEXT PRIMARY KEY,body TEXT NOT NULL,attempts INTEGER NOT NULL DEFAULT 0,next_at INTEGER NOT NULL DEFAULT 0,state TEXT NOT NULL DEFAULT 'pending',error TEXT);
+      CREATE TABLE IF NOT EXISTS processed(id TEXT PRIMARY KEY,hash TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS held(id TEXT PRIMARY KEY,msg_key TEXT NOT NULL UNIQUE,channel TEXT NOT NULL,sender TEXT NOT NULL,envelope TEXT NOT NULL,sha TEXT NOT NULL,expires_at INTEGER NOT NULL,created_at INTEGER NOT NULL);
+      CREATE INDEX IF NOT EXISTS held_channel ON held(channel);
+      CREATE INDEX IF NOT EXISTS held_sender ON held(sender);
+      CREATE INDEX IF NOT EXISTS held_channel_sender ON held(channel,sender);
+    `);
+    if(!this.db.prepare("PRAGMA table_info(outbox)").all().some(c=>c.name==="profile_id"))this.db.exec("ALTER TABLE outbox ADD COLUMN profile_id TEXT");
+    if(path!==":memory:")chmodSync(path,0o600);
+  }
+  get(key,fallback=null){const row=this.db.prepare("SELECT v FROM kv WHERE k=?").get(key);return row?JSON.parse(row.v):fallback}
+  set(key,value){this.db.prepare("INSERT INTO kv(k,v) VALUES(?,?) ON CONFLICT(k) DO UPDATE SET v=excluded.v").run(key,JSON.stringify(value))}
+  transaction(fn){this.db.exec("BEGIN IMMEDIATE");try{const result=fn();this.db.exec("COMMIT");return result}catch(e){this.db.exec("ROLLBACK");throw e}}
+  append(id,event){
+    const existing=this.db.prepare("SELECT * FROM events WHERE id=?").get(id);if(existing){if(digest(JSON.parse(existing.body))!==digest(event))throw new Error("Audit event ID conflicts with content");return {...existing,duplicate:true}};
+    const previous=this.db.prepare("SELECT hash FROM events ORDER BY seq DESC LIMIT 1").get()?.hash??"genesis";
+    const hash=digest({previous,event});
+    this.db.prepare("INSERT INTO events(id,previous,hash,body) VALUES(?,?,?,?)").run(id,previous,hash,JSON.stringify(event));
+    return {id,previous,hash};
+  }
+  verify(){let previous="genesis";return this.db.prepare("SELECT * FROM events ORDER BY seq").all().every(r=>{const ok=r.previous===previous&&r.hash===digest({previous,event:JSON.parse(r.body)});previous=r.hash;return ok})}
+  audit(){return this.db.prepare("SELECT * FROM events ORDER BY seq DESC LIMIT 100").all()}
+  seen(id,hash=null){const row=this.db.prepare("SELECT hash FROM processed WHERE id=?").get(id);if(row&&hash&&row.hash!==hash)throw new Error("Replay ID conflicts with signed content");return !!row}
+  mark(id,hash){this.db.prepare("INSERT INTO processed(id,hash) VALUES(?,?)").run(id,hash)}
+  retain(envelope,sha,ttlMs=14*86400000){
+    const existing=this.db.prepare("SELECT seq,sha FROM envelopes WHERE id=?").get(envelope.id);
+    if(existing){if(existing.sha!==sha)throw new Error("Envelope ID conflicts with existing content");return {...existing,duplicate:true}}
+    this.db.prepare("DELETE FROM envelopes WHERE expires<?").run(Date.now());
+    if(this.db.prepare("SELECT COUNT(*) AS n FROM envelopes").get().n>=10000||this.db.prepare("PRAGMA page_count").get().page_count*this.db.prepare("PRAGMA page_size").get().page_size>=256*1024*1024)throw new Error("Carrier storage budget exhausted");
+    const r=this.db.prepare("INSERT INTO envelopes(id,sender,recipient,sha,body,expires) VALUES(?,?,?,?,?,?)").run(envelope.id,envelope.sender,envelope.recipient,sha,JSON.stringify(envelope),Date.now()+ttlMs);
+    return {seq:Number(r.lastInsertRowid),sha,duplicate:false};
+  }
+  inbox(recipient,since=0){return this.db.prepare("SELECT seq,body FROM envelopes WHERE recipient=? AND seq>? AND expires>? ORDER BY seq LIMIT 100").all(recipient,since,Date.now()).map(r=>({seq:r.seq,envelope:JSON.parse(r.body)}))}
+  queue(envelope,profileId=null){this.db.prepare("INSERT OR IGNORE INTO outbox(id,body,profile_id) VALUES(?,?,?)").run(envelope.id,JSON.stringify(envelope),profileId)}
+  pending(){return this.db.prepare("SELECT * FROM outbox WHERE state='pending' AND next_at<=? ORDER BY rowid LIMIT 50").all(Date.now())}
+  delivered(id){this.db.prepare("UPDATE outbox SET state='accepted',error=NULL WHERE id=?").run(id)}
+  failure(id,error){const row=this.db.prepare("SELECT attempts FROM outbox WHERE id=?").get(id);const attempts=row.attempts+1;const state=attempts>=5?"quarantined":"pending";this.db.prepare("UPDATE outbox SET attempts=?,next_at=?,state=?,error=? WHERE id=?").run(attempts,Date.now()+Math.min(300000,1000*2**attempts),state,error.slice(0,300),id)}
+  hold(envelope,msgKey,channel,sender,sha,expiresAt){this.db.prepare("INSERT INTO held(id,msg_key,channel,sender,envelope,sha,expires_at,created_at) VALUES(?,?,?,?,?,?,?,?)").run(envelope.id,msgKey,channel,sender,JSON.stringify(envelope),sha,expiresAt,Date.now())}
+  isHeld(id,msgKey){return !!this.db.prepare("SELECT 1 FROM held WHERE id=? OR msg_key=?").get(id,msgKey)}
+  removeHeld(id){this.db.prepare("DELETE FROM held WHERE id=?").run(id)}
+  allHeld(){return this.db.prepare("SELECT * FROM held ORDER BY created_at ASC, rowid ASC").all()}
+  holdCounts(channel,sender){
+    const total=this.db.prepare("SELECT COUNT(*) AS n FROM held").get().n;
+    const channelCount=this.db.prepare("SELECT COUNT(*) AS n FROM held WHERE channel=?").get(channel).n;
+    const senderCount=this.db.prepare("SELECT COUNT(*) AS n FROM held WHERE sender=?").get(sender).n;
+    const channelSender=this.db.prepare("SELECT COUNT(*) AS n FROM held WHERE channel=? AND sender=?").get(channel,sender).n;
+    return {total,channel:channelCount,sender:senderCount,channelSender};
+  }
+  pruneExpiredHeld(now=Date.now()){
+    return this.transaction(()=>{
+      const expired=this.db.prepare("SELECT * FROM held WHERE expires_at<=?").all(now);
+      if(expired.length){
+        const del=this.db.prepare("DELETE FROM held WHERE id=?");
+        for(const row of expired)del.run(row.id);
+      }
+      return expired;
+    });
+  }
+  close(){this.db.close()}
+}

package/src/transport.d.mts

@@ -0,0 +1,76 @@
+export interface TransportCapabilities {
+  readonly name: string;
+  readonly canPush: boolean;          // Can receive inbound pushes
+  readonly canPoll: boolean;          // Supports inbox polling
+  readonly supportsStreaming: boolean; // Supports SSE / live streams
+  readonly maxMessageBytes: number;   // Transport-specific message size ceiling
+  readonly loopbackSafe: boolean;     // Works on 127.0.0.1 without external network
+}
+
+export interface DeliveryResult {
+  readonly carrier: string;           // Identifying URI of the accepting carrier
+  readonly seq?: number;              // Monotonic sequence assigned by carrier
+  readonly sha: string;               // Envelope SHA-256
+  readonly duplicate: boolean;        // Whether the carrier already held this envelope
+  readonly all?: any[];               // Multi-carrier replication or refusal details
+  readonly accepted: boolean;         // Must be true for outbox consumption
+  readonly retryable?: boolean;
+  readonly quarantine?: boolean;
+  readonly reason?: string;
+}
+
+export interface InboxEnvelopeItem {
+  readonly sourceId: string;
+  readonly seq: number;
+  readonly envelope: any;
+}
+
+export interface InboxBatch {
+  readonly sourceId: string;
+  readonly envelopes: InboxEnvelopeItem[];
+  readonly now: number;
+}
+
+export interface MessageTransport {
+  readonly capabilities: TransportCapabilities;
+  sources(): readonly string[];
+  deliver(envelope: any, options?: { timeoutMs?: number }): Promise<DeliveryResult>;
+  fetchInbox(sourceId: string, options?: { since?: number; waitS?: number; timeoutMs?: number }): Promise<InboxBatch>;
+  subscribe?(sourceId: string, onEnvelope: (item: InboxEnvelopeItem) => Promise<void>): () => void;
+  close(): Promise<void>;
+}
+
+export interface MemoryLoopbackOptions {
+  instanceId?: string;
+  capabilities?: Partial<TransportCapabilities>;
+}
+
+export class MemoryLoopbackTransport implements MessageTransport {
+  constructor(options?: MemoryLoopbackOptions);
+  readonly instanceId: string;
+  readonly sourceId: string;
+  readonly capabilities: TransportCapabilities;
+  sources(): readonly string[];
+  deliver(envelope: any, options?: { timeoutMs?: number }): Promise<DeliveryResult>;
+  fetchInbox(sourceId: string, options?: { since?: number; waitS?: number; timeoutMs?: number }): Promise<InboxBatch>;
+  subscribe(sourceId: string, onEnvelope: (item: InboxEnvelopeItem) => Promise<void>): () => void;
+  close(): Promise<void>;
+}
+
+export interface PillarCarrierOptions {
+  keychain?: any;
+  client?: any;
+  carriers?: string[];
+  env?: Record<string, string | undefined>;
+  capabilities?: Partial<TransportCapabilities>;
+}
+
+export class PillarCarrierTransport implements MessageTransport {
+  constructor(options?: PillarCarrierOptions);
+  readonly client: any;
+  readonly capabilities: TransportCapabilities;
+  sources(): readonly string[];
+  deliver(envelope: any, options?: { timeoutMs?: number }): Promise<DeliveryResult>;
+  fetchInbox(sourceId: string, options?: { since?: number; waitS?: number; timeoutMs?: number }): Promise<InboxBatch>;
+  close(): Promise<void>;
+}