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

package/src/relay/test-mode.mjs

@@ -0,0 +1,73 @@
+// Cloud Commons relay: the --test-mode hooks (spec v3.4.5 13.2 "Test mode").
+//
+// server.mjs loads this module only when the relay starts with --test-mode, and only after the
+// conjunctive start refusal has passed (the test aud AND a loopback or named test-interface
+// bind). A non-test build can leave this file out entirely (security invariant: its entrypoint must not carry the
+// flag).
+//
+// - Clock: relay time is the integer (ms) in <dir>/clock, read on every use. The harness moves it;
+//   nothing in a request can set or move it.
+// - Barriers: a closed list of named points in the request path. While <dir>/barriers/<name>.hold
+//   exists, a request reaching that point writes <dir>/barriers/<name>.reached and waits until the
+//   .hold file is gone. No request can name, create or clear a barrier.
+// - Container-local only: <dir> is one absolute, normalized path given at start, never
+//   taken from a request, with no symlink anywhere in it (its realpath is itself). The directory and
+//   every file read from it must be a real directory or regular file (never a symlink, so no path is
+//   redirected elsewhere), owned by this process's user, and not writable by group or others. The
+//   harness asserts no host mounts (13.2).
+
+import { lstatSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, normalize } from "node:path";
+import { RelayError } from "./records.mjs";
+
+/**
+ * The closed barrier list. Relay: before the record handler runs, and after it committed (before the
+ * response). Reference client (13.2: "the reference client takes the same barrier hooks"): after it
+ * read an inbox record and before handling it, after handling and before acknowledging, and before
+ * it drains its outbox.
+ */
+export const BARRIERS = Object.freeze(["before-dispatch", "after-commit", "client-after-read", "client-after-handle", "client-before-drain"]);
+const POLL_MS = 10;
+
+function privateEntry(path, kind) {
+  let st;
+  try { st = lstatSync(path); } catch { return null; }
+  const ok = (kind === "dir" ? st.isDirectory() : st.isFile()) && !st.isSymbolicLink()
+    && (typeof process.getuid !== "function" || st.uid === process.getuid()) && (st.mode & 0o022) === 0;
+  if (!ok) throw new RelayError("test-mode-path", 500, `${kind} must be a private ${kind === "dir" ? "directory" : "regular file"} of this user, not a symlink`);
+  return st;
+}
+
+/**
+ * Open the hooks for one test directory. Throws (and the relay refuses to start) unless the
+ * directory and its clock file pass the checks above and the clock holds a valid time.
+ * Returns { now(), barrier(name, signal), dir }.
+ */
+export function openTestHooks(dir) {
+  if (typeof dir !== "string" || !isAbsolute(dir) || normalize(dir) !== dir || dir.length > 512) throw new RelayError("test-mode-path", 500, "test dir must be an absolute, normalized path");
+  if (!privateEntry(dir, "dir")) throw new RelayError("test-mode-path", 500, "test dir missing");
+  if (realpathSync(dir) !== dir) throw new RelayError("test-mode-path", 500, "test dir path must contain no symlink");
+  const clockPath = join(dir, "clock");
+  const barrierDir = join(dir, "barriers");
+
+  function now() {
+    if (!privateEntry(clockPath, "file")) throw new RelayError("test-clock", 500, "clock file missing");
+    const text = readFileSync(clockPath, "utf8");
+    if (!/^(0|[1-9][0-9]{0,15})\n?$/.test(text)) throw new RelayError("test-clock", 500, "clock file must hold one integer (ms)");
+    const t = Number(text.trim());
+    if (!Number.isSafeInteger(t)) throw new RelayError("test-clock", 500, "clock out of range");
+    return t;
+  }
+
+  /** Wait at a named point while its .hold file exists. Resolves at once when there is none. */
+  async function barrier(name, signal) {
+    if (!BARRIERS.includes(name)) throw new RelayError("test-barrier", 500, "unknown barrier");
+    const hold = join(barrierDir, `${name}.hold`);
+    if (!privateEntry(barrierDir, "dir") || !privateEntry(hold, "file")) return;
+    writeFileSync(join(barrierDir, `${name}.reached`), `${process.pid}\n`, { mode: 0o600 });
+    while (!signal?.aborted && privateEntry(hold, "file")) await new Promise(r => setTimeout(r, POLL_MS));
+  }
+
+  now();   // refuse to start on a missing or invalid clock
+  return Object.freeze({ now, barrier, dir });
+}

package/src/runtime.mjs

@@ -3,12 +3,15 @@ import { Keychain, seal, open, decrypt, envelopeSha, CarrierClient, jcs } from "
 import { CommonsStore } from "./store.mjs";
 import { RegistryTrust } from "./trust.mjs";
 import { BASE_PROTOCOL, createProfile, verifyProfile, proposeAlias, encode, decode, digest, signDocument, verifyDocument, contribution } from "./profiles.mjs";
-// L3 Slice 2 v6 §2.1: Pluggable transport and channel/tenant admission
+// Pluggable transport and channel/tenant admission
 import { PillarCarrierTransport } from "./transport.mjs";
 import { classifyThread, assertChannelSendAdmission, assertChannelReceiveAdmission, validateTenantBinding } from "./channels.mjs";
 
+// D-12: only a string envelope id goes into an audit event; anything else a peer sends (absent, 1.5, an object) becomes null.
+const auditEnvelopeId=id=>typeof id==="string"?id:null;
+
 export class AgentCommons {
-  // L3 Slice 2 v6 §2.1: options.transport and channel/tenant policy flags
+  // options.transport and channel/tenant policy flags
   constructor({keychain,store=new CommonsStore(),policy={mode:"local",agents:{}},carriers=[],transport,trust}={}){
     if(!keychain?._identity)throw new Error("A loaded Pillar keychain is required");
     this.keychain=keychain;this.store=store;this.policy=policy;this.trust=trust??new RegistryTrust({policy});this.carriers=carriers;
@@ -111,7 +114,7 @@ export class AgentCommons {
     await this.trust.authorize(this.uuaid,this.publicKey,"commons:contribute");
     return signDocument(this.keychain,"profile-contribution",{contribution:contribution(this.profile(profileId),options)});
   }
-  // L3 Slice 2 v6 §2.1 / §4.2, §4.2.3, §5.2: channel/tenant admission, atomic authenticated admission record
+  // Channel/tenant admission, atomic authenticated admission record
   async send({recipient,profileId,namespace,body,thread="commons",kind="message",deferFlush=false}){
     if(typeof body!=="string"||Buffer.byteLength(body)>32000||typeof thread!=="string"||thread.length>120||!["message","profile-control"].includes(kind))throw new Error("Invalid bounded message");
     const classified=classifyThread(thread,this.policy);
@@ -146,7 +149,7 @@ export class AgentCommons {
     return {queued:queued.map(x=>({recipient:x.envelope.recipient,id:x.envelope.id})),deliveries:await this.flush(),groupPrivacy:"individually-sealed-recipient-copies"};
   }
   flush(){const next=this._flushTail.then(()=>this.flushInternal());this._flushTail=next.catch(()=>{});return next}
-  // L3 Slice 2 v6 §2.1 / §3.1, §4.2, §4.2.3, §5.2: pre-delivery rechecks, signature verification, and delivery
+  // Pre-delivery rechecks, signature verification, and delivery
   async flushInternal(){
     if(!this.transport)return [];
     const results=[];
@@ -192,7 +195,7 @@ export class AgentCommons {
     return results;
   }
   receive(envelope){const next=this._receiveTail.then(()=>this.receiveInternal(envelope));this._receiveTail=next.catch(()=>{});return next}
-  // L3 Slice 2 v6 §2.1 / §4.2, §4.2.3, §5.2: inbound channel and tenant admission
+  // Inbound channel and tenant admission
   async receiveInternal(envelope){
     const valid=open(envelope);if(!valid.ok)throw new Error(`Invalid Pillar envelope: ${valid.reason}`);
     if(envelope.delegation!==undefined)throw new Error("Delegated host admission requires a configured principal-status adapter; not yet enabled");
@@ -289,7 +292,7 @@ export class AgentCommons {
     }
     return results;
   }
-  // L3 Slice 2 v6 §2.1 / §3.1, §8 (R2): foreign item skip with cursor advance and recipient isolation
+  // Foreign item skip with cursor advance and recipient isolation
   async poll(){
     if(!this.transport)throw new Error("No carrier configured");
     const cursors=this.store.get("cursors",{}),health=this.store.get("carrierHealth",{}),results=[];
@@ -303,10 +306,14 @@ export class AgentCommons {
       for(const item of inbox.envelopes){
         // A carrier may not rewind or repeat sequence numbers within a response.
         if(!Number.isSafeInteger(item?.seq)||item.seq<=last){results.push({carrier,rejected:true,reason:"non-monotonic-carrier-sequence"});continue}
-        const valid=open(item?.envelope);
+        // D-12: open() can throw on peer input (it interpolates fields); a throw is one more invalid envelope, not a poll failure.
+        let valid;
+        try{valid=open(item?.envelope)}catch{valid={ok:false,reason:"validation-threw"}}
         if(!valid.ok){
-          results.push({id:item?.envelope?.id,rejected:true,reason:`Invalid Pillar envelope: ${valid.reason}`});
-          this.store.append(`rejected-${item?.envelope?.id}`,{kind:"quarantined-inbound",id:item?.envelope?.id,reason:`Invalid Pillar envelope: ${valid.reason}`});
+          // D-12: the peer's id is data inside the event, never the audit key; the cursor moves only after the audit write lands.
+          const id=auditEnvelopeId(item?.envelope?.id),reason=`Invalid Pillar envelope: ${typeof valid.reason==="string"?valid.reason:"invalid"}`;
+          results.push({id,rejected:true,reason});
+          this.store.append(randomUUID(),{kind:"quarantined-inbound",id,reason});
           last=item.seq;cursors[carrier]=item.seq;this.store.set("cursors",cursors);
           continue;
         }
@@ -321,10 +328,16 @@ export class AgentCommons {
           if(error?.transient===true){
             // Trust backend outage is not a verdict on the sender: keep the cursor so the envelope is retried, and stop to preserve order.
             const failures=(health[carrier]?.failures??0)+1;health[carrier]={failures,nextProbeAt:Date.now()+Math.min(60000,1000*2**Math.min(failures,6)),error:error.code??"trust-unavailable"};this.store.set("carrierHealth",health);
-            this.store.append(`deferred-${item.envelope?.id}`,{kind:"inbound-deferred-trust-unavailable",id:item.envelope?.id});
-            results.push({id:item.envelope?.id,rejected:false,deferred:true,state:"trust-unavailable-retry",reason:error.code??"trust-unavailable"});break;
+            // D-12: JSON.stringify keeps the key one-to-one with id (null vs "null", lone surrogates), and the event is a
+            // function of id alone, so a retry rewrites the same row and two different ids never share a key. The
+            // "deferred/v2:" namespace keeps these keys apart from rows written as `deferred-${id}` before this change.
+            const id=auditEnvelopeId(item.envelope?.id);
+            this.store.append(`deferred/v2:${JSON.stringify(id)}`,{kind:"inbound-deferred-trust-unavailable",id});
+            results.push({id,rejected:false,deferred:true,state:"trust-unavailable-retry",reason:error.code??"trust-unavailable"});break;
           }
-          results.push({id:item.envelope?.id,rejected:true,reason:error.message});this.store.append(`rejected-${item.envelope?.id}`,{kind:"quarantined-inbound",id:item.envelope?.id,reason:error.message});
+          // D-12: a thrown value need not carry a string message; never serialize it into the audit.
+          const id=auditEnvelopeId(item.envelope?.id),reason=typeof error?.message==="string"?error.message:"receive-failed";
+          results.push({id,rejected:true,reason});this.store.append(randomUUID(),{kind:"quarantined-inbound",id,reason});
         }
         last=item.seq;cursors[carrier]=item.seq;this.store.set("cursors",cursors);
       }

package/src/spaces/manifest.mjs

@@ -0,0 +1,245 @@
+/**
+ * Manifest verifier wrapper, admin signer and key→uuaid binding helpers
+ * (design §3, §4). Additive; imports the vendored pillar engine ONLY through
+ * ./pillar-group.mjs (C9). Computes no engine-vs-client hash (C13/V-7): the
+ * manifest path uses the vendored canonicalJson, never the engine's jcs (V-1).
+ *
+ * In scope here: V-3 (only whole chains yield a head), V-6's
+ * sign → verify → own-store-save → return order, B-1/B-2 (one binding,
+ * keyBindsRow: AC's parse-based rule-1 check plus the vendored strict-key
+ * rule), B-3 (policy-record candidates from the verified head), B-4 (full-uuaid
+ * keys admit only the roster's exact spelling at the engine trust gate), B-6
+ * (self check) and V-7's unit-level ASCII-key guard.
+ *
+ * R1: the admin change is the VENDORED `adminChange` (V-1, "vendor, don't
+ * write"), so a frozen record is refused and a leave/remove clears the target
+ * from `leaving` exactly as pillar's reference does (groups-v2.mjs:534, :541).
+ *
+ * Deferred by design, NOT stubbed: P-7 (a remove/leave manifest adds the
+ * pendingRemovals entry in the same step; it spans adapter.json),
+ * the sends themselves, V-7's send/receive wiring and
+ * B-5's transport-key snapshot.
+ */
+import {
+  adminChange, adminOf, isStrictPublicKey, manifestHash, verifyChain,
+} from "./pillar-group.mjs";
+import { keyBindsAgentUuaid } from "../uuaid-namespace.mjs";
+
+/** A named error, so a caller (and a pole) can tell refusals apart. */
+export class ManifestError extends Error {
+  constructor(name, message) { super(message); this.name = name; }
+}
+
+/** P-2: capabilities are exactly ["commons:message"] for every record. */
+const AGENT_CAPABILITIES = Object.freeze(["commons:message"]);
+
+// ── V-3: only whole chains ────────────────────────────────────────────────
+
+/**
+ * The usable head of a record, only if its chain verifies from version 1.
+ * Never takes a head from an unverified record: verifyChain runs here, in
+ * this call, whatever the record's provenance (SpaceStore.loadRoster output
+ * re-verifies too — this is the explicit gate for a supplied record).
+ *
+ * If `rec.head` is present it must agree with the verified chain's last
+ * manifest; a record without one is tolerated because the chain itself is
+ * the verified source of the head.
+ */
+export function verifiedHead(rec) {
+  if (!rec || !Array.isArray(rec.chain) || rec.chain.length === 0) {
+    throw new ManifestError("ChainVerifyError", "record: no chain to verify");
+  }
+  const v = verifyChain(rec.chain);
+  if (!v.ok) throw new ManifestError("ChainVerifyError", `chain rejected: ${v.reason}@${v.at}`);
+  const head = rec.chain[rec.chain.length - 1];
+  if (rec.head !== undefined && rec.head !== null) {
+    if (rec.head.version !== head.version || rec.head.hash !== manifestHash(head)) {
+      throw new ManifestError("HeadMismatchError", "rec.head does not match the verified chain's last manifest");
+    }
+  }
+  return head;
+}
+
+// ── B-6: self check ───────────────────────────────────────────────────────
+
+/** Normalize a Keychain instance (._identity) or a raw identity object. */
+function keychainIdentity(keychain) {
+  const id = keychain?._identity ?? keychain;
+  if (!id || typeof id.uuaid !== "string" || id.uuaid.length === 0 ||
+      typeof id.publicKeyHex !== "string" || id.publicKeyHex.length === 0) {
+    throw new ManifestError("SelfCheckError", "keychain: no loaded identity {uuaid, publicKeyHex}");
+  }
+  return id;
+}
+
+/**
+ * B-1/B-2: does `key` bind `uuaid`? Namespace alignment rule 1 — a key-derived
+ * agent UUAID in foundation, pillar or agentnet whose local id is the key's,
+ * PARSED, never rebuilt and compared (rule 2) — plus the vendored strict-key
+ * rule (no small-order or non-canonical point). One key therefore binds three
+ * spellings; B-4 is what keeps them apart at the gate.
+ */
+export function keyBindsRow(uuaid, key) {
+  return keyBindsAgentUuaid(uuaid, key) && isStrictPublicKey(key);
+}
+
+/**
+ * B-6. Passes only when (a) the keychain's uuaid is bound by its own public key
+ * (keyBindsRow) AND (b) the VERIFIED head holds a row for that uuaid carrying
+ * that same key. Otherwise throws SelfCheckError. On a chain that verified,
+ * (b)'s key-mismatch arm is unreachable when (a) held (B-1: the local id is a
+ * function of the key, and rowChecks binds every row), so it is kept as a
+ * guard against a future vendored change and for callers that hand-build a
+ * head — same posture as the space store's keep-only-if clauses.
+ */
+export function selfCheck(keychain, rec) {
+  const id = keychainIdentity(keychain);
+  if (!keyBindsRow(id.uuaid, id.publicKeyHex)) {
+    throw new ManifestError("SelfCheckError", "keychain uuaid does not derive from its own public key");
+  }
+  const head = verifiedHead(rec);
+  const row = head.members.find((r) => r.uuaid === id.uuaid);
+  if (!row) throw new ManifestError("SelfCheckError", "the verified head holds no row for this keychain's uuaid");
+  if (row.key !== id.publicKeyHex) throw new ManifestError("SelfCheckError", "the head's own row carries a different key");
+  return true;
+}
+
+// ── V-6: the admin signer (sign → verify → own-store-save → return) ──────
+
+/**
+ * The store the vendored `adminChange` writes through: SpaceStore's own
+ * roster load/save, so `loadRoster`'s absent-means-null (F13) and
+ * `saveRoster`'s verify-before-create plus 0700 tightening (S-1) are the only
+ * path to disk. `loadGroupForCommand` needs has/load; :542 needs save.
+ */
+function rosterStoreFor(store) {
+  return {
+    has: (id) => store.loadRoster(id) !== null,
+    load: (id) => {
+      const r = store.loadRoster(id);
+      if (!r) throw new ManifestError("RosterAbsentError", `no verified roster for ${String(id)}`);
+      return r;
+    },
+    save: (rec) => store.saveRoster(rec), // OWN STORE FIRST (S-1: refuses an unverified record)
+  };
+}
+
+/**
+ * Build, sign and apply the next manifest to the ADMIN's own store, then
+ * return it for the caller to send (the send itself is not done here — this never
+ * sends). Order is load-bearing:
+ *   1. load through SpaceStore.loadRoster, which re-verifies (F13, V-3);
+ *   2. explicit verifiedHead (V-3) and selfCheck (B-6);
+ *   3. the signer must be the head's single active admin (F14);
+ *   4. a frozen record is refused BEFORE anything is built — the named error
+ *      for pillar's own refusal (groups-v2.mjs:534);
+ *   5. the vendored `adminChange` builds, signs with the admin's own keychain
+ *      (F14), verifies the next version, extends the chain, clears the target
+ *      from `leaving` on leave/remove (:541) and saves to the admin's OWN
+ *      store FIRST (:542);
+ *   6. only then return { manifest, record }.
+ *
+ * `mailbox: null` makes the vendored mailbox coupling a no-op
+ * (`syncMailboxRoster`, :457-458) — this wrapper owns no mailbox row.
+ *
+ * P-7 (a remove/leave manifest puts the member into pendingRemovals in the
+ * same step) is not done here: it spans the roster and adapter.json. The record
+ * fields other than chain/head/leaving (seen, frozen, …) are preserved
+ * verbatim; the receiver-side application semantics are not applied here.
+ *
+ * Synchronous; the adapter's serial queue (I-5) is the caller's job.
+ * @returns {{ manifest: object, record: object }}
+ */
+export function signAndApplyNext(store, groupId, keychain, action, buildOpts = {}) {
+  const rec = store.loadRoster(groupId); // re-verifies from version 1 (F13); null = absent
+  if (!rec) throw new ManifestError("RosterAbsentError", `no verified roster for ${String(groupId)}`);
+  const head = verifiedHead(rec); // V-3, explicit
+  const id = keychainIdentity(keychain);
+  selfCheck(keychain, rec); // B-6
+  const admin = adminOf(head);
+  if (!admin || admin.uuaid !== id.uuaid || admin.key !== id.publicKeyHex) {
+    throw new ManifestError("NotAdminError", "the signer is not the head's single active admin");
+  }
+  // D1: pillar refuses an equivicated group here (:534); this is the named
+  // form of that refusal, and the vendored call below refuses it again.
+  if (rec.frozen) {
+    throw new ManifestError("FrozenGroupError",
+      `${String(groupId)} is frozen (equivocation); a frozen group can only be replaced by a new group`);
+  }
+  // A raw identity is accepted by signManifest but NOT by :543, which reads
+  // keychain._identity.uuaid unguarded — normalize to the keychain shape.
+  const signer = keychain?._identity ? keychain : { _identity: id };
+  const { rec: record, manifest } = adminChange({
+    store: rosterStoreFor(store), mailbox: null, keychain: signer,
+    groupId, action, opts: buildOpts,
+  });
+  return { manifest, record }; // …and only then handed back for sending
+}
+
+// ── B-3: policy-record candidates from the verified head ─────────────────
+
+/**
+ * One candidate `policy.agents` entry from one roster row. The binding is
+ * keyBindsRow (B-1/B-2: rule 1 plus the vendored strict-key rule). A failing
+ * row THROWS; it is never
+ * skipped silently. Exported so the binding re-check is unit-testable on a
+ * hand-built row (on a verified chain rowChecks already binds every row, so
+ * the aggregate below re-checks as defense in depth).
+ */
+export function agentRecordForRow(row) {
+  if (!row || typeof row.uuaid !== "string" || typeof row.key !== "string") {
+    throw new ManifestError("KeyBindingError", "row: expected {uuaid, key} strings");
+  }
+  if (!keyBindsRow(row.uuaid, row.key)) {
+    throw new ManifestError("KeyBindingError", `row ${row.uuaid}: key does not bind its uuaid`);
+  }
+  return { kind: "agent", publicKey: row.key, capabilities: [...AGENT_CAPABILITIES] };
+}
+
+/**
+ * B-3, pure: candidate `policy.agents` entries ONLY from the verified head's
+ * non-removed rows (active ∪ invited, design §5), keyed by the FULL row.uuaid
+ * — which is what makes B-4 hold. One key has a valid spelling in each of
+ * foundation, pillar and agentnet, all passing KEY_BINDING; a sender re-spelling
+ * a member's key in another of them is refused NOT_ADMITTED, because a policy
+ * built here holds only each row's EXACT spelling. A spelling outside the set
+ * never reaches policy: trust.authorize refuses it AGENT_ONLY. Writes no
+ * policy: the policy writer is the only writer and consumes this helper.
+ */
+export function agentRecordsFromVerifiedHead(rec) {
+  const head = verifiedHead(rec);
+  const agents = {};
+  for (const row of head.members) {
+    if (row.status === "removed") continue;
+    agents[row.uuaid] = agentRecordForRow(row); // full-uuaid key; throws, never skips
+  }
+  return agents;
+}
+
+// ── V-7 (unit level): no non-ASCII object keys, any depth ────────────────
+
+function isAsciiKey(k) {
+  for (const ch of k) if (ch.codePointAt(0) > 0x7f) return false;
+  return true;
+}
+
+/**
+ * V-7's guard, unit-tested here; its wiring into send and receive is
+ * slices 8/9. Refuses any non-ASCII object key at any depth — commons
+ * objects, charter objects and space profile documents including the
+ * lexicon. Pillar 2.0.2's jcs sorted by UTF-16LE bytes and disagreed with
+ * pillar-client's JCS on such keys (F16); the vendored 2.2.0 jcs sorts by code
+ * unit as RFC 8785 requires, but peers on older code still disagree, so no
+ * engine-vs-client hash may be computed over such keys (C13). Array indices are
+ * keys of an array object and are ASCII by construction. Contract: parsed-
+ * JSON or freshly built objects; a cyclic input is out of contract.
+ */
+export function assertAsciiKeys(obj, path = "$") {
+  if (obj === null || typeof obj !== "object") return;
+  for (const k of Object.keys(obj)) {
+    if (!isAsciiKey(k)) {
+      throw new ManifestError("NonAsciiKeyError", `${path}: non-ASCII object key ${JSON.stringify(k)}`);
+    }
+    assertAsciiKeys(obj[k], `${path}.${k}`);
+  }
+}

package/src/spaces/pillar-group.mjs

@@ -0,0 +1,12 @@
+/**
+ * The ONLY module under src/spaces/ that imports the vendored pillar groups-v2
+ * engine (C9). Later slices add names HERE; they never open a second import
+ * site. Re-exported by name, limited to what the space-store slice uses.
+ */
+export {
+  RosterStore, isGroupIdV2, STORE_V,
+  // the manifest verifier wrapper and admin signer, and the vendored
+  // strict-key rule that manifest.mjs's keyBindsRow pairs with AC's rule-1
+  // binding (the engine's own uuaidForKey/keyBindsUuaid are not used here):
+  adminChange, adminOf, isStrictPublicKey, manifestHash, verifyChain,
+} from "../vendor/pillar/groups-v2.mjs";

package/src/spaces/policy.mjs

@@ -0,0 +1,229 @@
+/** Synchronous space policy and operator stops. Queue ownership and sends belong to the adapter. */
+import { isDeepStrictEqual } from "node:util";
+import { manifestHash } from "./pillar-group.mjs";
+import { agentRecordForRow, agentRecordsFromVerifiedHead, keyBindsRow, verifiedHead, selfCheck, signAndApplyNext } from "./manifest.mjs";
+import { prunePendingRemovals, validateAdapterState } from "./store.mjs";
+import { RegistryTrust } from "../trust.mjs";
+
+const POLICY_FIELDS=["mode","channelsEnabled","holdBeforeAdmission","agents","tenantProfiles","channels"];
+const emergencyEngines=new WeakSet(); // replacement invalidates the cached shared identity until a fresh engine is constructed
+const quarantinedEngines=new WeakSet();
+const isCanonicalTrust=RegistryTrust.isCanonicalTrust;
+const denyTrust=RegistryTrust.prototype.denyPermanently;
+const reflectApply=Reflect.apply;
+function plainPolicy(value){return value!==null&&typeof value==="object"&&[Object.prototype,null].includes(Object.getPrototypeOf(value))}
+function latched(state){return state.hardStop!==null}
+export class PolicyError extends Error {
+  constructor(name,message){super(message);this.name=name}
+}
+export function assertPolicyIdentity(engine){
+  if(quarantinedEngines.has(engine)||!isCanonicalTrust(engine?.trust))throw new PolicyError("PolicyIdentityError","A fresh canonical RegistryTrust receiver is required");
+  const policy=engine?.policy,prototype=policy&&Object.getPrototypeOf(policy);
+  if(policy===null||typeof policy!=="object"||(prototype!==Object.prototype&&prototype!==null)||Object.isFrozen(policy)||!Object.isExtensible(policy)||policy!==engine?.trust?.policy){
+    throw new PolicyError("PolicyIdentityError","Engine and trust must share one mutable plain policy object");
+  }
+  return policy;
+}
+function channels(groupId){return {content:`channel://agentnet/group/${groupId}`,control:`channel://agentnet/group-ctl/${groupId}`}}
+function closed(groupId){
+  const uris=channels(groupId);
+  return {mode:"local",channelsEnabled:true,holdBeforeAdmission:true,agents:{},tenantProfiles:{},channels:{[uris.content]:{members:[]},[uris.control]:{members:[]}}};
+}
+function outsideAllowlist(rows,allowlist){
+  return rows.find(row=>!allowlist.some(allowed=>allowed.uuaid===row.uuaid&&allowed.key===row.key));
+}
+function outsider(rec,state,allowlist){
+  const head=verifiedHead(rec),rows=[...head.members.filter(row=>row.status!=="removed"),...state.pendingRemovals];
+  return outsideAllowlist(rows,allowlist);
+}
+function closePolicies(policy,groupId,engine){
+  let failure;
+  const references=[engine,engine?.trust].filter(Boolean);
+  for(const candidate of new Set([policy,engine?.policy,engine?.trust?.policy])){
+    try{
+      if(!plainPolicy(candidate)||!Object.isExtensible(candidate))throw new TypeError("Authority policy cannot be closed in place");
+      Object.assign(candidate,closed(groupId));
+    }catch(error){
+      failure??=error;
+      for(const owner of references){
+        if(owner.policy!==candidate)continue;
+        try{
+          const replacement=closed(groupId);owner.policy=replacement;
+          if(owner.policy!==replacement)throw new TypeError("Authority policy replacement did not take effect");
+          emergencyEngines.add(engine);
+        }catch(fallbackError){failure??=fallbackError}
+      }
+    }
+  }
+  let allClosed=false;
+  try{allClosed=(engine?[engine.policy,engine.trust?.policy]:[policy]).every(value=>plainPolicy(value)&&POLICY_FIELDS.every(field=>isDeepStrictEqual(value[field],closed(groupId)[field])))}catch(error){failure??=error}
+  if(!allClosed&&engine){
+    if(!isCanonicalTrust(engine.trust))throw new PolicyError("PolicyIdentityError","Cannot deny an unsupported trust receiver");
+    reflectApply(denyTrust,engine.trust,[]);
+    quarantinedEngines.add(engine);
+  }
+  return {closed:allClosed,error:failure??(allClosed?null:new PolicyError("PolicyCloseError","An authority consumer remains open"))};
+}
+function requireSharedPolicy(policy,engine){
+  if(assertPolicyIdentity(engine)!==policy)throw new PolicyError("PolicyIdentityError","Restart with a fresh engine to recover the shared policy identity");
+}
+function expectedPolicy(rec,self,state,ext,now){
+  if(latched(state))return closed(state.groupId);
+  const head=verifiedHead(rec),rows=head.members.filter(row=>row.status!=="removed");
+  const pending=prunePendingRemovals(state.pendingRemovals,rec,now).kept;
+  const agents=agentRecordsFromVerifiedHead(rec);
+  for(const entry of pending)agents[entry.uuaid]=agentRecordForRow(entry);
+  const tenantProfiles={};
+  if(ext.tenant!=null){for(const agent of Object.values(agents))agent.tenantId=ext.tenant;tenantProfiles[ext.profile.id]=ext.tenant}
+  const selfId=self?._identity?.uuaid??self?.uuaid??self,me=head.members.find(row=>row.uuaid===selfId);
+  const stopped=!!rec.frozen||state.softStop!==null;
+  const content=stopped?[]:head.members.filter(row=>row.status==="active"&&!rec.leaving.includes(row.uuaid)).map(row=>row.uuaid);
+  const control=[...new Set((rec.frozen?rows:[...rows,...pending]).map(row=>row.uuaid))];
+  // P-6: a self-removed instance has no content or control channel authority.
+  if(!me||me.status==="removed"){content.length=0;control.length=0}
+  const uris=channels(state.groupId);
+  return {mode:"local",channelsEnabled:true,holdBeforeAdmission:true,agents,tenantProfiles,channels:{[uris.content]:{members:content},[uris.control]:{members:control}}};
+}
+function stop(policy,state,reason,{engine,store,onSignal=()=>{},now=Date.now()}={}){
+  if(state.hardStop===null)state.hardStop={reason,at:now};
+  let persisted=false,failure;
+  try{store.saveAdapter(state.groupId,state);persisted=true}catch(error){failure=error}
+  const outcome=closePolicies(policy,state.groupId,engine);failure??=outcome.error;
+  try{onSignal({code:"SPACE_CLOSED",groupId:state.groupId,...state.hardStop,persisted,closed:outcome.closed})}catch(error){failure??=error}
+  if(failure)throw failure;
+  return false;
+}
+/** P-9 reads the verified files again; a policy file is never an input. */
+export function checkPolicy(policy,rec,self,state,ext,allowlist,options){
+  // rec, ext and allowlist remain for caller compatibility; the check reads the persisted inputs again.
+  const {engine,store,now=Date.now()}=options;
+  if(!isCanonicalTrust(engine?.trust))throw new PolicyError("PolicyIdentityError","A canonical RegistryTrust receiver is required");
+  if(quarantinedEngines.has(engine))requireSharedPolicy(policy,engine);
+  const loaded=store.loadAdapter(state.groupId,{now});
+  const saved=store.loadRoster(state.groupId),savedState=loaded?.state;
+  if(!savedState)throw new PolicyError("AdapterAbsentError","No persisted adapter state for policy check");
+  const expected=latched(savedState)?closed(state.groupId):expectedPolicy(saved,self,savedState,verifiedHead(saved).ext.commons,now);
+  const bound=Object.entries(policy.agents??{}).every(([uuaid,agent])=>keyBindsRow(uuaid,agent?.publicKey)&&agent?.kind==="agent"&&isDeepStrictEqual(agent?.capabilities,["commons:message"]));
+  if(policy===engine.policy&&policy===engine.trust.policy&&bound&&POLICY_FIELDS.every(field=>isDeepStrictEqual(policy[field],expected[field])))return true;
+  return stop(policy,state,"policy-mismatch",options);
+}
+/** One run-to-completion write. The options supply the actual engine, store and operator signal. */
+export function writePolicy(policy,rec,self,state,ext,allowlist,options){
+  try{
+  if(!isCanonicalTrust(options.engine?.trust))throw new PolicyError("PolicyIdentityError","A canonical RegistryTrust receiver is required");
+  if(quarantinedEngines.has(options.engine))requireSharedPolicy(policy,options.engine);
+  if(latched(state)){Object.assign(policy,closed(state.groupId));checkPolicy(policy,rec,self,state,ext,allowlist,options);return policy}
+  if(emergencyEngines.has(options.engine))requireSharedPolicy(policy,options.engine);
+  if(outsider(rec,state,allowlist)){stop(policy,state,"outsider",options);checkPolicy(policy,rec,self,state,ext,allowlist,options);return policy}
+  const expected=expectedPolicy(rec,self,state,ext,options.now??Date.now());
+  Object.assign(policy,expected);
+  checkPolicy(policy,rec,self,state,ext,allowlist,options);
+  return policy;
+  }catch(error){
+    closePolicies(policy,state.groupId,options.engine);
+    throw error;
+  }
+}
+
+/** Owns only policy/state operations; the future adapter invokes these on its serial queue. */
+export class SpacePolicy {
+  constructor({engine,store,groupId,allowlist,onSignal=()=>{},clock=Date.now}){
+    this.policy=assertPolicyIdentity(engine);
+    this.engine=engine;this.store=store;this.groupId=groupId;this.self=engine.keychain;
+    this.allowlist=allowlist;this.onSignal=onSignal;this.clock=clock;
+    if(!Array.isArray(allowlist))throw new PolicyError("AllowlistError","An explicit operator allowlist is required");
+    Object.assign(this.policy,closed(this.groupId));
+    this.rebuild();
+  }
+  _load(){
+    const now=this.clock(),loaded=this.store.loadAdapter(this.groupId,{now});
+    if(!loaded)throw new PolicyError("AdapterAbsentError","No adapter state; installation is a separate operation");
+    return {rec:this.store.loadRoster(this.groupId),state:loaded.state,now};
+  }
+  _options(now){return {engine:this.engine,store:this.store,onSignal:this.onSignal,now}}
+  rebuild(){
+    try{
+    if(!isCanonicalTrust(this.engine.trust))throw new PolicyError("PolicyIdentityError","A canonical RegistryTrust receiver is required");
+    if(quarantinedEngines.has(this.engine))requireSharedPolicy(this.policy,this.engine);
+    const {rec,state,now}=this._load();
+    if(latched(state))writePolicy(this.policy,rec,this.self,state,null,this.allowlist,this._options(now));
+    if(!rec){if(latched(state))return this.policy;throw new PolicyError("RosterAbsentError","No verified roster for policy rebuild")}
+    const head=verifiedHead(rec);selfCheck(this.self,rec);
+    if(!latched(state)&&emergencyEngines.has(this.engine))requireSharedPolicy(this.policy,this.engine);
+    // Inspect every verified change since consent, including changes reverted while this instance was down.
+    const after=rec.chain.filter(manifest=>manifest.version>state.consent.manifestVersion);
+    let previous=rec.chain.find(manifest=>manifest.version===state.consent.manifestVersion)?.ext.commons;
+    if(!previous)throw new PolicyError("ConsentHeadError","Consent must name a verified manifest version");
+    let changed=false,reconsentSignal=false;
+    for(const manifest of after){
+      const current=manifest.ext.commons;
+      if(!isDeepStrictEqual(previous.profile,current.profile)||previous.tenant!==current.tenant){
+        if(state.softStop===null){state.softStop={reason:"reconsent",at:now};changed=true;reconsentSignal=true}
+      }
+      previous=current;
+    }
+    const scanned=rec.chain.find(manifest=>manifest.version===state.outsiderScan.version);
+    const scanVersion=scanned&&manifestHash(scanned)===state.outsiderScan.hash?scanned.version:0;
+    const unseen=rec.chain.filter(manifest=>manifest.version>scanVersion);
+    const hit=unseen.some(manifest=>outsideAllowlist(manifest.members.filter(row=>row.status!=="removed"),this.allowlist));
+    const from=state.outsiderScan,to={version:head.version,hash:manifestHash(head)};
+    if(!isDeepStrictEqual(from,to)){state.outsiderScan=to;changed=true}
+    if(hit&&!latched(state))stop(this.policy,state,"outsider",this._options(now));
+    else{
+      if(changed)this.store.saveAdapter(this.groupId,state);
+      if(hit)this.onSignal({code:"SPACE_OUTSIDER_SEEN",groupId:this.groupId,from,to});
+    }
+    if(reconsentSignal)this.onSignal({code:"SPACE_RECONSENT_REQUIRED",groupId:this.groupId,at:now});
+    return writePolicy(this.policy,rec,this.self,state,head.ext.commons,this.allowlist,this._options(now));
+    }catch(error){
+      try{closePolicies(this.policy,this.groupId,this.engine)}catch{} // retain the original read/write failure
+      throw error;
+    }
+  }
+  /** Call after rebuild(), including after pending TTL expiry; the adapter owns the expiry timer. */
+  check(){
+    try{
+    const {rec,state,now}=this._load();
+    return checkPolicy(this.policy,rec,this.self,state,latched(state)?null:verifiedHead(rec).ext.commons,this.allowlist,this._options(now));
+    }catch(error){
+      try{closePolicies(this.policy,this.groupId,this.engine)}catch{}
+      throw error;
+    }
+  }
+  hardResume(){
+    requireSharedPolicy(this.policy,this.engine);
+    const {rec,state,now}=this._load(),head=verifiedHead(rec);selfCheck(this.self,rec);
+    if(!isDeepStrictEqual(state.outsiderScan,{version:head.version,hash:manifestHash(head)}))throw new PolicyError("OutsiderScanBehindError","Run rebuild first: outsider scan is behind the verified head");
+    if(outsider(rec,state,this.allowlist))throw new PolicyError("OutsiderError","Hard resume requires an outsider-free verified head and pending set");
+    state.hardStop=null;this.store.saveAdapter(this.groupId,state);
+    return this.rebuild();
+  }
+  reconsent(consent){
+    if(!isCanonicalTrust(this.engine.trust)||emergencyEngines.has(this.engine)||quarantinedEngines.has(this.engine))requireSharedPolicy(this.policy,this.engine);
+    const {rec,state}=this._load(),head=verifiedHead(rec);
+    state.consent=structuredClone(consent);state.profile=structuredClone(head.ext.commons.profile);state.softStop=null;
+    validateAdapterState(state,this.groupId);
+    if(state.consent.manifestVersion!==head.version)throw new PolicyError("ConsentHeadError","Reconsent must name the current verified manifest");
+    this.store.saveAdapter(this.groupId,state);
+    return this.rebuild(); // E-3's checked profile installation remains the installer's responsibility.
+  }
+  /** P-7: reserved envelope id is mandatory for a remove/leave; roster FIRST, adapter SECOND. */
+  applyOwnChange(action,buildOpts={}, {outboxId}={}){
+    if(!isCanonicalTrust(this.engine.trust)||emergencyEngines.has(this.engine)||quarantinedEngines.has(this.engine))requireSharedPolicy(this.policy,this.engine);
+    const {rec,state,now}=this._load(),head=verifiedHead(rec);
+    let nextState=state;
+    if(action==="remove"||action==="leave"){
+      const row=head.members.find(member=>member.uuaid===buildOpts.target);
+      if(!row)throw new PolicyError("RemovalTargetError","A pending removal requires a row in the verified head");
+      const pending={uuaid:row.uuaid,key:row.key,manifestVersion:head.version+1,queuedAt:now,outboxId};
+      nextState={...state,pendingRemovals:[...state.pendingRemovals.filter(entry=>entry.uuaid!==row.uuaid),pending]};
+      validateAdapterState(nextState,this.groupId); // preflight before either file write
+    }
+    let result;
+    try{
+    result=signAndApplyNext(this.store,this.groupId,this.self,action,buildOpts);
+    if(nextState!==state)this.store.saveAdapter(this.groupId,nextState);
+    }finally{this.rebuild()}
+    return result;
+  }
+}