@uuaid/pillar 2.0.3 → 2.2.0

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);
+}

package/src/net/carrier-server.mjs

@@ -12,6 +12,13 @@
  *     - carrier verifies the transport signature before accepting (fail closed)
  *     - idempotent on envelope.id
  *     -> 202 { accepted: true, seq, sha }
+ *     With a receipt key (constructor `receiptKeychain`), the 202 also carries
+ *     `receipt` + `receiptSig` (uuaid.carrier-receipt.v1, ./carrier-receipt.mjs),
+ *     built from the STORED row after the insert commits. A repeated
+ *     envelope.id whose canonical hash (sha256(JCS(envelope))) equals the
+ *     stored one gets the original fields with duplicate: true; a different
+ *     body under a stored id is refused 409 envelope-id-conflict, no receipt.
+ *     Without a receipt key every response is exactly as before.
  *
  *   GET /v1/inbox/<uuaid>?since=<seq>&wait=<seconds>
  *     headers:
@@ -46,6 +53,9 @@
  * only becomes visible at the moment the carrier starts saying no.
  *
  * Durability: SQLite (WAL).  Envelopes are retained until TTL (default 14 days).
+ * Each row stores its own `retain_until` (created_at + TTL at acceptance), and
+ * vacuum() deletes a row only once now > that row's retain_until, so a later,
+ * smaller TTL never shortens a deadline already issued in a receipt.
  * The carrier CANNOT read payloads it relays beyond what the envelope exposes,
  * and CANNOT forge envelopes (no keys).  It can only: deliver, delay, or drop —
  * and drops are detectable by sequence gaps + sender outbox audit.
@@ -53,12 +63,13 @@
 import { createServer } from "node:http";
 import { createHash } from "node:crypto";
 import Database from "better-sqlite3";
-import { open as openEnvelope } from "./envelope.mjs";
-import { Keychain } from "../identity/keychain.mjs";
+import { open as openEnvelope, envelopeSha as canonicalEnvelopeSha } from "./envelope.mjs";
+import { Keychain, keyDerivesUuaid, isStrictEd25519PublicKey } from "../identity/keychain.mjs";
 import { jcs } from "../identity/jcs.mjs";
 import { verifyTierGrant } from "../identity/tier.mjs";
 import { verifyDelegationDoc, delegationCoversKind } from "./delegation.mjs";
 import { withCarrierFix } from "./refusals.mjs"; // additive `fix` on refusals; reason/error/status unchanged
+import { carrierReceiptSigningString, carrierReceiptShapeOk, carrierUuaidFromKey } from "./carrier-receipt.mjs";
 
 const MAX_WAIT_S = 30;
 const MAX_BODY = 512 * 1024; // 512 KiB per envelope (community tier)
@@ -79,10 +90,27 @@ const RATE_MAP_HARD_CAP = 10_000;          // F2: bound memory under key spray
 // still fits inside the same absolute ceiling. A carrier with no trusted tier
 // issuers configured never resolves a priority grant, so these are inert.
 const COMMUNITY_DB_BYTES = Math.floor(MAX_DB_BYTES * 0.85);   // last 15% of the store is reserved
-const COMMUNITY_CONCURRENT_WAITS = 48;                        // of MAX_CONCURRENT_WAITS
+const COMMUNITY_CONCURRENT_WAITS = 48;                        // of MAX_CONCURRENT_WAITS (the default)
+// A carrier operator may raise the community long-poll cap (CARRIER_COMMUNITY_WAITS;
+// pillar.uuaid.org runs 192, grant ZZ-DP-2026-10-22-007). The priority reserve is kept
+// ON TOP of it, so a raised community cap never eats the reserved slots.
+const PRIORITY_WAIT_RESERVE = MAX_CONCURRENT_WAITS - COMMUNITY_CONCURRENT_WAITS; // 16
+const MAX_COMMUNITY_WAITS = 4096;                             // sanity ceiling for the setting
+
+/** Parse a community long-poll cap: a whole number from 1 to 4096, else throw. */
+export function parseCommunityWaits(value) {
+  if (value === undefined || value === null || value === "") return COMMUNITY_CONCURRENT_WAITS;
+  const n = typeof value === "number" ? value : (/^[0-9]+$/.test(String(value)) ? Number(value) : NaN);
+  if (!Number.isInteger(n) || n < 1 || n > MAX_COMMUNITY_WAITS) {
+    throw new Error(`community waits must be a whole number from 1 to ${MAX_COMMUNITY_WAITS}, not "${value}"`);
+  }
+  return n;
+}
 const MAX_PRIORITY_GOOD_PER_MIN = 600;                        // priority senders bill to their own per-IP bucket
 const CHECKPOINT_ATTEMPTS = 3;                                // TRUNCATE checkpoint tries per vacuum pass
 const CHECKPOINT_BUSY_MS = 250;                               // per try; a busy pass is retried next hour
+/** Row columns a receipt is built from (plus the legacy `sha` the 202 has always echoed). */
+const ROW_COLUMNS = "seq, envelope_id, recipient, sender, sha, created_at, retain_until, envelope_sha";
 
 /**
  * Secure delete for the envelope store: one switch per broker (--secure-delete
@@ -108,7 +136,22 @@ export function parseSecureDelete(value) {
 }
 
 export class CarrierServer {
-  constructor({ dbPath = "carrier.db", ttlDays = 14, cryptoInventory, trustedTierIssuers = [], keychain = null, publicUrl = null, secureDelete = true } = {}) {
+  constructor({ dbPath = "carrier.db", ttlDays = 14, cryptoInventory, trustedTierIssuers = [], keychain = null, publicUrl = null, secureDelete = true, receiptKeychain = null, communityInboxWaits = COMMUNITY_CONCURRENT_WAITS } = {}) {
+    // Every row's retain_until is created_at + ttlDays, so the TTL must be a
+    // real positive duration (a NaN here used to surface only as a vacuum crash).
+    if (typeof ttlDays !== "number" || !Number.isFinite(ttlDays) || ttlDays <= 0) {
+      throw new Error(`ttlDays must be a positive number of days, not ${ttlDays}`);
+    }
+    // Receipt key: optional and separate from the seed `keychain`. Fail closed
+    // on a key that is not loaded or not a strict Ed25519 key, rather than
+    // running a carrier that silently signs nothing or signs under a weak key.
+    if (receiptKeychain !== null && receiptKeychain !== undefined) {
+      const id = receiptKeychain._identity;
+      if (!id?.publicKeyHex || typeof receiptKeychain.sign !== "function") {
+        throw new Error("receiptKeychain must be a loaded Keychain");
+      }
+      if (!isStrictEd25519PublicKey(id.publicKeyHex)) throw new Error("receiptKeychain key is not a strict Ed25519 key");
+    }
     this.db = new Database(dbPath);
     this.db.pragma("journal_mode = WAL");
     this.secureDelete = secureDelete !== false;
@@ -122,7 +165,9 @@ export class CarrierServer {
         sender      text not null,
         sha         text not null,
         body        text not null,
-        created_at  text not null default (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+        created_at  text not null default (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+        retain_until text,
+        envelope_sha text
       );
       create index if not exists idx_envelopes_recipient on envelopes(recipient, seq);
       -- Lifetime service counters. Kept OUTSIDE the envelopes table because
@@ -133,14 +178,25 @@ export class CarrierServer {
         v text not null
       );
     `);
+    // Migration for stores created before carrier receipts: add the per-row
+    // retention deadline and canonical envelope hash. Existing rows get
+    // retain_until = created_at + ttlDays (what the old vacuum would have
+    // honoured); their canonical hash is computed from the stored body when a
+    // duplicate first needs it (_storedCanonicalSha).
+    const cols = new Set(this.db.prepare("pragma table_info(envelopes)").all().map(c => c.name));
+    if (!cols.has("retain_until")) this.db.exec("alter table envelopes add column retain_until text");
+    if (!cols.has("envelope_sha")) this.db.exec("alter table envelopes add column envelope_sha text");
     this.db.prepare("insert or ignore into seed_stats (k, v) values ('first_seen', ?)")
       .run(new Date().toISOString());
     this.ttlDays = ttlDays;
+    this._backfillRetention(); // @rule carrier.retention-backfill
     this.cryptoInventory = cryptoInventory ?? { ed25519: "active" };
     this.startedAt = Date.now();
     this.server = null;
     this.rateMap = new Map(); // F2: "<kind>:<key>" -> [ms timestamps]
     this.activeWaits = 0;     // F2: long-polls currently sleeping
+    this.communityWaitCap = parseCommunityWaits(communityInboxWaits);
+    this.priorityWaitCap = this.communityWaitCap + PRIORITY_WAIT_RESERVE;
     this._closed = false;
     // Tier grants: issuer pubkeys (hex) this carrier honors. Empty = every
     // sender gets community-tier budgets (pre-tier behavior, default).
@@ -150,6 +206,75 @@ export class CarrierServer {
     // does not expose /v1/seed-info.
     this.keychain = keychain;
     this.publicUrl = publicUrl ? String(publicUrl).replace(/\/+$/, "") : null;
+    // Receipt identity: the carrier uuaid is DERIVED from the receipt key
+    // (uuaid:foundation:agent:<localId>), never read from the keychain file,
+    // so it is always the uuaid a client's pin check derives.
+    this.receiptKeychain = receiptKeychain ?? null;
+    this.receiptCarrier = this.receiptKeychain ? carrierUuaidFromKey(this.receiptKeychain._identity.publicKeyHex) : null;
+  }
+
+  /** created_at + the current TTL, as ISO-8601 UTC with milliseconds; null if created_at does not parse. */
+  _retainUntilFor(createdAt) {
+    const ms = Date.parse(createdAt);
+    if (!Number.isFinite(ms)) return null;
+    return new Date(ms + this.ttlDays * 86400_000).toISOString();
+  }
+
+  /**
+   * Give every row without a retention deadline one: created_at + ttlDays.
+   * Only rows that never had a deadline are touched (rows from before this
+   * column existed, or written by hand); an issued deadline is never changed.
+   */
+  _backfillRetention() {
+    const rows = this.db.prepare("select seq, created_at from envelopes where retain_until is null").all();
+    if (!rows.length) return 0;
+    const set = this.db.prepare("update envelopes set retain_until = ? where seq = ? and retain_until is null");
+    let n = 0;
+    this.db.transaction(() => {
+      for (const r of rows) {
+        const until = this._retainUntilFor(r.created_at);
+        if (until !== null) n += set.run(until, r.seq).changes;
+      }
+    })();
+    return n;
+  }
+
+  /**
+   * The canonical hash (sha256(JCS(envelope))) of a stored row: the column
+   * when set, else computed once from the stored body and persisted. Null if
+   * the stored body cannot be canonicalized.
+   */
+  _storedCanonicalSha(row) {
+    if (typeof row.envelope_sha === "string") return row.envelope_sha;
+    let h = null;
+    try { h = canonicalEnvelopeSha(JSON.parse(row.body)); } catch (_e) { h = null; }
+    if (h !== null) this.db.prepare("update envelopes set envelope_sha = ? where seq = ? and envelope_sha is null").run(h, row.seq);
+    return h;
+  }
+
+  /**
+   * { receipt, receiptSig } for a stored row, or null. Every field comes from
+   * the committed row (§12 rule 1: sign the stored object, never the request
+   * body); only `duplicate` says which path asked. A row whose fields would
+   * not pass a v1 verifier is not signed.
+   */
+  _receiptFor(row, duplicate) {
+    if (!this.receiptKeychain) return null;
+    const receipt = {
+      v: 1,
+      carrier: this.receiptCarrier,
+      envelopeId: row.envelope_id,
+      envelopeSha: row.envelope_sha, // @rule carrier.receipt-canonical-sha
+      sender: row.sender,
+      recipient: row.recipient,
+      seq: Number(row.seq),
+      duplicate: duplicate === true,
+      acceptedAt: row.created_at, // @rule carrier.receipt-stored-time
+      retainUntil: row.retain_until,
+    };
+    if (!carrierReceiptShapeOk(receipt)) return null;
+    const receiptSig = this.receiptKeychain.sign(Buffer.from(carrierReceiptSigningString(receipt), "utf-8")).toString("hex");
+    return { receipt, receiptSig };
   }
 
   /** Read a lifetime counter. */
@@ -264,15 +389,22 @@ export class CarrierServer {
   }
 
   /**
-   * Remove envelopes older than TTL.  Call periodically.  Returns the number
-   * deleted.  With secure delete on, a pass that deleted anything then runs
+   * Remove envelopes whose own retention deadline has passed (now >
+   * retain_until).  Call periodically.  Returns the number deleted.  A row's
+   * deadline is fixed when it is stored, so lowering ttlDays later never
+   * deletes a row before the retainUntil its receipt promised.  A row with no
+   * parseable created_at (so no deadline) falls back to the old created_at
+   * cutoff.  With secure delete on, a pass that deleted anything then runs
    * wal_checkpoint(TRUNCATE) until it reports busy=0 (at most
    * CHECKPOINT_ATTEMPTS tries); `lastVacuum` records the outcome, and
    * `lastVacuum.scrubbed` is false when the checkpoint never completed.
    */
   vacuum() {
+    this._backfillRetention();
+    const now = new Date().toISOString();
     const cutoff = new Date(Date.now() - this.ttlDays * 86400_000).toISOString();
-    const r = this.db.prepare("delete from envelopes where created_at < ?").run(cutoff);
+    const expired = "retain_until < @now or (retain_until is null and created_at < @cutoff)"; // @rule carrier.retention-per-row
+    const r = this.db.prepare(`delete from envelopes where ${expired}`).run({ now, cutoff });
     const report = { deleted: r.changes, secureDelete: this.secureDelete, checkpoint: null, attempts: 0, scrubbed: null };
     if (this.secureDelete && r.changes > 0) {
       // vacuum() runs on the event loop: wait at most CHECKPOINT_BUSY_MS per
@@ -361,20 +493,45 @@ export class CarrierServer {
     const pages = this.db.pragma("page_count", { simple: true });
     const pageBytes = this.db.pragma("page_size", { simple: true });
     const storeCap = tier.priority ? MAX_DB_BYTES : COMMUNITY_DB_BYTES;
-    if (pages * pageBytes > storeCap) {
-      return { code: 503, body: { accepted: false, reason: "carrier-full" } };
-    }
+    if (pages * pageBytes > storeCap) return { code: 503, body: { accepted: false, reason: "carrier-full" } }; // @rule carrier.full-refuses-before-store
     const sha = createHash("sha256").update(JSON.stringify(envelope)).digest("hex");
+    // Canonical hash, independent of the key order the envelope arrived in.
+    // A carrier that signs receipts must be able to bind the envelope, so it
+    // refuses one it cannot canonicalize; without a receipt key such an
+    // envelope is stored exactly as before.
+    let canonicalSha = null;
+    try { canonicalSha = canonicalEnvelopeSha(envelope); } catch (_e) { canonicalSha = null; }
+    if (this.receiptKeychain && canonicalSha === null) {
+      return { code: 400, body: { accepted: false, reason: "bad-canonical" } };
+    }
+    const acceptedAt = new Date().toISOString();
+    const retainUntil = this._retainUntilFor(acceptedAt);
     try {
       const r = this.db.prepare(
-        "insert into envelopes (envelope_id, recipient, sender, sha, body) values (?,?,?,?,?)"
-      ).run(envelope.id, envelope.recipient, envelope.sender, sha, JSON.stringify(envelope));
+        "insert into envelopes (envelope_id, recipient, sender, sha, body, created_at, retain_until, envelope_sha) values (?,?,?,?,?,?,?,?)"
+      ).run(envelope.id, envelope.recipient, envelope.sender, sha, JSON.stringify(envelope), acceptedAt, retainUntil, canonicalSha);
       this._bump("relayed");
-      return { code: 202, body: { accepted: true, seq: Number(r.lastInsertRowid), sha } };
+      const seq = Number(r.lastInsertRowid);
+      const body = { accepted: true, seq, sha };
+      if (this.receiptKeychain) {
+        // Re-read the committed row: the receipt is built from what is stored.
+        const row = this.db.prepare(`select ${ROW_COLUMNS} from envelopes where seq = ?`).get(seq);
+        const signed = row ? this._receiptFor(row, false) : null;
+        if (signed) Object.assign(body, signed);
+      }
+      return { code: 202, body };
     } catch (e) {
       if (/UNIQUE constraint/.test(e.message)) {
-        const row = this.db.prepare("select seq, sha from envelopes where envelope_id = ?").get(envelope.id);
-        return { code: 202, body: { accepted: true, duplicate: true, seq: row.seq, sha: row.sha } };
+        const row = this.db.prepare(`select ${ROW_COLUMNS}, body from envelopes where envelope_id = ?`).get(envelope.id);
+        // No receipt key: the duplicate answer is exactly the pre-receipt one.
+        if (!this.receiptKeychain) return { code: 202, body: { accepted: true, duplicate: true, seq: row.seq, sha: row.sha } }; // @rule carrier.keyless-unchanged
+        // §12 rule 1 (P1): the same id with a different body is not a
+        // duplicate. Refuse it, unsigned, rather than receipt the stored body
+        // to a sender who posted something else.
+        const storedSha = this._storedCanonicalSha(row);
+        if (storedSha === null || storedSha !== canonicalSha) return { code: 409, body: { accepted: false, reason: "envelope-id-conflict" } }; // @rule carrier.id-conflict
+        const signed = this._receiptFor({ ...row, envelope_sha: storedSha }, true);
+        return { code: 202, body: { accepted: true, duplicate: true, seq: row.seq, sha: row.sha, ...(signed ?? {}) } };
       }
       throw e;
     }
@@ -392,9 +549,7 @@ export class CarrierServer {
       return { ok: false, reason: "clock-skew" };
     }
     // Self-authenticating: UUAID must derive from the presented pubkey.
-    const localId = Keychain._localIdFromKey(Buffer.from(pubkey, "hex"));
-    const derived = `uuaid:foundation:agent:${localId}`;
-    if (derived !== uuaid) {
+    if (!keyDerivesUuaid(pubkey, uuaid, "agent")) {
       // A delegate key may read the principal's inbox only by presenting the
       // principal-signed delegation document that names it.  Without the
       // header this stays the legacy mismatch.
@@ -457,7 +612,7 @@ export class CarrierServer {
     // delegate polling for a priority principal inherits the reserved slots,
     // which is the same authority it already has to read the mail.
     const tier = this._resolveTier(req, uuaid);
-    const waitCap = tier.priority ? MAX_CONCURRENT_WAITS : COMMUNITY_CONCURRENT_WAITS;
+    const waitCap = tier.priority ? this.priorityWaitCap : this.communityWaitCap;
     if (wait > 0 && this.activeWaits >= waitCap) {
       return this._json(res, 503, { error: "busy" });
     }

package/src/net/refusals.mjs

@@ -34,6 +34,7 @@ export const REFUSAL_FIXES = Object.freeze({
   "bad-signature": "sign again with this identity's own key over the exact bytes; the signature does not verify",
   "weak-publicKey": "use a real Ed25519 identity key; this key is a small-order or non-canonical point that can sign anything, so no signature under it counts",
   "delegation-invalid": "mint a fresh delegation from the principal, then resend",
+  "envelope-id-conflict": "seal a new envelope with a fresh id; this carrier already holds a different envelope under this id",
   // Carrier, envelope shape and crypto (envelope.mjs open()): one fix for all
   "not-object": RESEAL,
   "bad-version": RESEAL,
@@ -69,8 +70,9 @@ export const REFUSAL_FIXES = Object.freeze({
   "carrier-unreachable": "check the carrier URLs and your network, then retry",
   "carrier-bad-response": "retry, or use another carrier; the carrier or its proxy answered without a reason",
   "over-tier-limit": "send the payload as a blob (pillar-blob send, or Pillar.sendBlob)",
-  "blob-key-unproven": "use a uuaid:foundation:agent UUAID derived from this key (pillar init), or get a registry badge that names this key",
-  "sender-key-not-active": "ask the sender to send from a uuaid:foundation:agent UUAID derived from its own key, or to get a registry badge naming its key",
+  "blob-key-unproven": "use a self-certifying agent UUAID derived from this key (pillar init), or get a registry badge that names this key",
+  "sender-key-not-active": "ask the sender to send from a self-certifying agent UUAID derived from its own key, or to get a registry badge naming its key",
+  "group-v2-use-v2-send": "send to this pillar-group/2 group with pillar group send <group>; v1 group sends (send-group, sendGroup) do not reach it",
 });
 
 /**