@uuaid/pillar 2.0.2 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uuaid/pillar",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "Pillar (Protocol for Inter-agent Linked Ledger And Relay) — the secure delivery layer of UACP, the Universal Agent Communication Protocol. UACP = UUAID (identity) + Envelope (signed, encrypted container) + Pillar (relay, mailbox, routing, store-and-forward). Reference implementation of the UACP delivery layer; includes VDA-1 (IAASO-3901, in ballot) delivery attestation and a blind escrow for the Zilligon ZGN / EVM rails.",
   "license": "Apache-2.0",
   "type": "module",
@@ -13,6 +13,7 @@
     "pillar-seed": "bin/pillar-seed.mjs",
     "pillar-directory": "bin/pillar-directory.mjs",
     "pillar-escrow": "bin/pillar-escrow.mjs",
+    "pillar-group-v2": "bin/pillar-group-v2.mjs",
     "pillar-blob": "bin/pillar-blob.mjs"
   },
   "exports": {

package/src/address-book.mjs

@@ -1,27 +1,106 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { keyBindsUuaid } from "./groups.mjs";
+
+const UUAID_RE = /^uuaid:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9][a-z0-9-]*$/i;
+const PUBKEY_RE = /^[0-9a-f]{64}$/i;
+// Field names people reach for instead of `publicKey`; named in the diagnostic.
+const KEY_LOOKALIKES = ["pubkey", "pubKey", "public_key", "publicKeyHex", "key", "pk", "ed25519"];
+
+/**
+ * Read and check a fleet.json address book without touching a Pillar.
+ *
+ * Shape: { "fleet": { "<name>": { uuaid, publicKey, addrs?, peerId? } } }.
+ *
+ * Every way a file can fail to yield a usable contact is reported as a
+ * problem naming the file and the entry, because the failure used to be
+ * silent: a malformed or mis-shaped file loaded as zero contacts, and the
+ * first sign of it was `send: no public key known for …` about a peer the
+ * operator could see in the file.
+ *
+ * Returns { path, exists, error?, problems: string[], entries: [{ name, uuaid,
+ * publicKey?, addrs?, peerId? }], skipped: [{ name, uuaid?, reason }] }.
+ * `error` is set only when nothing could be read at all.
+ */
+export function inspectFleetFile(fleetPath) {
+  const out = { path: fleetPath, exists: false, problems: [], entries: [], skipped: [] };
+  if (!fleetPath || !existsSync(fleetPath)) return out;
+  out.exists = true;
+  let raw;
+  try { raw = JSON.parse(readFileSync(fleetPath, "utf-8")); }
+  catch (e) {
+    out.error = `${fleetPath} is not valid JSON (${e.message}); no contacts were loaded from it`;
+    out.problems.push(out.error);
+    return out;
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    out.error = `${fleetPath} must be a JSON object { "fleet": { "<name>": { "uuaid", "publicKey" } } }, found ${Array.isArray(raw) ? "an array" : typeof raw}; no contacts were loaded from it`;
+    out.problems.push(out.error);
+    return out;
+  }
+  if (!("fleet" in raw)) {
+    const keys = Object.keys(raw);
+    out.error = `${fleetPath} has no "fleet" key (top-level keys: ${keys.length ? keys.join(", ") : "none"}); expected { "fleet": { "<name>": { "uuaid", "publicKey" } } }; no contacts were loaded from it`;
+    out.problems.push(out.error);
+    return out;
+  }
+  const fleet = raw.fleet;
+  if (!fleet || typeof fleet !== "object" || Array.isArray(fleet)) {
+    out.error = `${fleetPath}: "fleet" must be an object keyed by name, found ${Array.isArray(fleet) ? "an array" : typeof fleet}; no contacts were loaded from it`;
+    out.problems.push(out.error);
+    return out;
+  }
+  for (const [name, e] of Object.entries(fleet)) {
+    const skip = (reason, uuaid) => {
+      out.skipped.push({ name, ...(uuaid ? { uuaid } : {}), reason });
+      out.problems.push(`${fleetPath}: entry "${name}" ${reason}`);
+    };
+    if (!e || typeof e !== "object" || Array.isArray(e)) { skip("is not an object"); continue; }
+    if (typeof e.uuaid !== "string" || !UUAID_RE.test(e.uuaid)) {
+      skip(e.uuaid === undefined ? "has no uuaid" : `has a malformed uuaid ${JSON.stringify(e.uuaid)}`);
+      continue;
+    }
+    const entry = { name, uuaid: e.uuaid };
+    if (Array.isArray(e.addrs)) entry.addrs = e.addrs;
+    if (typeof e.peerId === "string") entry.peerId = e.peerId;
+    if (e.publicKey === undefined) {
+      const alt = KEY_LOOKALIKES.find((k) => e[k] !== undefined);
+      out.problems.push(`${fleetPath}: entry "${name}" has no publicKey${alt ? ` (found "${alt}" — the field must be named "publicKey")` : ""}; it cannot be sent to`);
+    } else if (typeof e.publicKey !== "string" || !PUBKEY_RE.test(e.publicKey)) {
+      out.problems.push(`${fleetPath}: entry "${name}" publicKey must be 64 hex characters (the raw Ed25519 key), found ${JSON.stringify(String(e.publicKey).slice(0, 80))}; it cannot be sent to`);
+    } else if (!keyBindsUuaid(e.uuaid, e.publicKey)) {
+      out.problems.push(`${fleetPath}: entry "${name}" publicKey does not derive its uuaid ${e.uuaid} (wrong key pasted, or the peer rotated its identity); it cannot be sent to`);
+    } else {
+      entry.publicKey = e.publicKey.toLowerCase();
+    }
+    out.entries.push(entry);
+  }
+  return out;
+}
 
 /**
- * Load a fleet.json address book into a Pillar instance.
+ * Load a fleet.json address book into a Pillar instance. Returns the number
+ * of peers registered (unchanged contract). Entries that cannot be used are
+ * skipped, never thrown on, and each problem goes to `onProblem` (default: a
+ * `warning:` line on stderr; pass false to silence), so one bad row cannot
+ * stop an inbox check and a bad file is never silent.
  *
- * Shape: { "fleet": { "<role>": { uuaid, addrs?, peerId?, publicKey } } }.
  * `pillar init --directory` writes one from the directory's agents[] so a
  * fresh agent can `ask`/`send` with no manual key plumbing.
  */
-export function loadFleetAddressBook(fleetPath, pillar) {
-  if (!fleetPath || !existsSync(fleetPath)) return 0;
-  const fleet = JSON.parse(readFileSync(fleetPath, "utf-8")).fleet ?? {};
+export function loadFleetAddressBook(fleetPath, pillar, { onProblem = (p) => console.warn(`warning: ${p}`) } = {}) {
+  const info = inspectFleetFile(fleetPath);
+  if (onProblem) for (const p of info.problems) onProblem(p);
   // Warm handoff: fleet.json addrs come from a short-lived `pillar id` probe
   // on /tcp/0, so a running daemon's REAL addr differs. Each daemon writes
   // <home>/runtime.json on boot; prefer that addr when fresh.
-  const fleetRoot = dirname(fleetPath);
+  const fleetRoot = fleetPath ? dirname(fleetPath) : null;
   let n = 0;
-  for (const [role, id] of Object.entries(fleet)) {
-    if (!id.uuaid) continue;
+  for (const id of info.entries) {
     if (id.uuaid === pillar.uuaid) continue; // don't self-register
     let multiaddr = id.addrs?.[0];
     let peerId = id.peerId;
-    const rtPath = join(fleetRoot, role, "runtime.json");
+    const rtPath = join(fleetRoot, id.name, "runtime.json");
     if (existsSync(rtPath)) {
       try {
         const rt = JSON.parse(readFileSync(rtPath, "utf-8"));
@@ -34,9 +113,55 @@ export function loadFleetAddressBook(fleetPath, pillar) {
     pillar.registerAddress(id.uuaid, {
       peerId,
       multiaddr,
-      publicKey: id.publicKey, // REQUIRED for E2E sends
+      publicKey: id.publicKey, // REQUIRED for E2E sends; absent when the entry's key was unusable
     });
     n++;
   }
   return n;
 }
+
+/**
+ * A recipient argument as a UUAID. A UUAID passes through; anything else is
+ * a contact name looked up in fleet.json (exact, then case-insensitive; a
+ * leading `...` handle prefix is accepted). Returns { uuaid, name? } or
+ * throws an error that says what the address book does contain.
+ */
+export function resolveRecipient(arg, info) {
+  if (UUAID_RE.test(arg)) return { uuaid: arg };
+  const name = String(arg).replace(/^\.\.\./, "");
+  const exact = info.entries.find((e) => e.name === name);
+  const folded = exact ? [exact] : info.entries.filter((e) => e.name.toLowerCase() === name.toLowerCase());
+  if (folded.length === 1) return { uuaid: folded[0].uuaid, name: folded[0].name };
+  const e = new Error(explainUnknownName(arg, info, folded.length));
+  e.code = "unknown-recipient";
+  throw e;
+}
+
+function explainUnknownName(arg, info, matches) {
+  if (matches > 1) return `recipient "${arg}" matches ${matches} contacts in ${info.path} — use the full UUAID`;
+  const where = !info.path ? "no address book" : !info.exists ? `no address book at ${info.path}` : info.error ?? `${info.path}`;
+  const names = info.entries.map((e) => e.name);
+  return `recipient "${arg}" is not a UUAID and is not a contact name in ${where}` +
+    (names.length ? ` (contacts: ${names.slice(0, 20).join(", ")}${names.length > 20 ? ", …" : ""})` : "") +
+    ". Pass the full uuaid:… (with --to-pubkey for a peer outside the address book).";
+}
+
+/**
+ * Why no public key is known for `uuaid`, from the address book's point of
+ * view — the sentence `send` prints instead of a bare "no public key known".
+ */
+export function explainMissingKey(uuaid, info) {
+  const hint = "pass --to-pubkey <64-hex Ed25519 key>, or add { \"uuaid\", \"publicKey\" } for it under \"fleet\"";
+  if (!info.path) return `no public key known for ${uuaid}: no address book was given; ${hint}`;
+  if (!info.exists) return `no public key known for ${uuaid}: there is no address book at ${info.path}; ${hint}`;
+  if (info.error) return `no public key known for ${uuaid} because the address book could not be read: ${info.error}. Fix the file, or ${hint}`;
+  const entry = info.entries.find((e) => e.uuaid === uuaid);
+  if (entry) {
+    const problem = info.problems.find((p) => p.includes(`entry "${entry.name}"`));
+    return `no usable public key for ${uuaid}: ${problem ?? `entry "${entry.name}" in ${info.path} has none`}`;
+  }
+  const skipped = info.skipped.find((s) => s.uuaid === uuaid);
+  if (skipped) return `no public key known for ${uuaid}: its entry "${skipped.name}" in ${info.path} ${skipped.reason}`;
+  const bad = info.skipped.length ? ` ${info.skipped.length} entr${info.skipped.length === 1 ? "y was" : "ies were"} skipped as malformed (${info.skipped.map((s) => s.name).join(", ")}).` : "";
+  return `no public key known for ${uuaid}: it is not in ${info.path} (${info.entries.length} contact${info.entries.length === 1 ? "" : "s"}).${bad} ${hint}`;
+}

package/src/blob/blob.mjs

@@ -35,7 +35,8 @@
  */
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
 import { jcs } from "../identity/jcs.mjs";
-import { Keychain, localIdFromKey } from "../identity/keychain.mjs";
+import { Keychain, keyDerivedUuaidFor, keyDerivesUuaid } from "../identity/keychain.mjs";
+export { SELF_CERTIFYING_NAMESPACES } from "../identity/keychain.mjs";
 import { ABSOLUTE_MAX_BODY, TIER_DEFAULTS } from "../identity/tier.mjs";
 import { REFUSAL_FIXES } from "../net/refusals.mjs";
 
@@ -51,8 +52,9 @@ export const NONCE_BYTES = 12;
 export const DEK_BYTES = 32;
 /** keyId a broker request presents when the identity proves itself by its own key. */
 export const SELF_CERTIFIED_KEY_ID = "self-certified:ed25519";
-/** The one UUAID namespace and object type the broker accepts on the self-certified path. */
+/** @deprecated Default minting namespace only; verification uses SELF_CERTIFYING_NAMESPACES. */
 export const SELF_CERTIFIED_NAMESPACE = "foundation";
+/** The object type the broker accepts across self-certifying namespaces. */
 export const SELF_CERTIFIED_OBJECT_TYPE = "agent";
 
 // ---------------------------------------------------------------- errors ---
@@ -170,26 +172,22 @@ export function mkObjectName() {
 
 // ------------------------------------------------------ self-certified ---
 /**
- * The one UUAID a key self-certifies, rebuilt in full:
- * `uuaid:foundation:agent:` + sha256(publicKey)[:16] as a UUID (localIdFromKey,
- * the twin of pillar-client's localIdFromPublicKey). Null for a malformed key.
+ * Rebuild a key-derived agent UUAID in a self-certifying namespace.
+ * Foundation remains the default. Null for a malformed key or registry namespace.
  */
-export function selfCertifiedUuaidFor(publicKeyHex) {
-  if (typeof publicKeyHex !== "string" || !/^[0-9a-f]{64}$/i.test(publicKeyHex)) return null;
-  const localId = localIdFromKey(Buffer.from(publicKeyHex, "hex"));
-  return `uuaid:${SELF_CERTIFIED_NAMESPACE}:${SELF_CERTIFIED_OBJECT_TYPE}:${localId}`;
+export function selfCertifiedUuaidFor(publicKeyHex, namespace = "foundation") {
+  return keyDerivedUuaidFor(publicKeyHex, { namespace, objectType: SELF_CERTIFIED_OBJECT_TYPE });
 }
 
 /**
  * True only when `uuaid` is EXACTLY the UUAID the key self-certifies (full
- * string, namespace and object type included, the broker's rule); such an
+ * string, self-certifying namespace and agent object type included); such an
  * identity uses the broker without a registry badge. A device, a service,
- * another namespace, or a matching local id under any other prefix is not
+ * a registry namespace, or a matching local id under any other prefix is not
  * self-certified: it needs a registry badge naming its key.
  */
 export function isSelfCertifiedUuaid(uuaid, publicKeyHex) {
-  const expected = selfCertifiedUuaidFor(publicKeyHex);
-  return expected !== null && uuaid === expected;
+  return keyDerivesUuaid(publicKeyHex, uuaid, SELF_CERTIFIED_OBJECT_TYPE);
 }
 
 /**
@@ -471,7 +469,7 @@ export async function prepareBrokerBlobSend(keychain, { data, envelopeId, recipi
 
 /**
  * Production receive path; the sender key gate precedes broker redemption.
- * A sender whose UUAID is exactly the uuaid:foundation:agent UUAID of the
+ * A sender whose UUAID is exactly a self-certifying agent UUAID of the
  * ref's verified signing key passes without a badge; any other sender needs
  * a fresh registry badge naming that key (client.assertRegistryActiveSender).
  *

package/src/blob/http.mjs

@@ -72,7 +72,7 @@ function safeBase(url) {
  * `keyId` is optional. Given, it is presented as is. Omitted, the client
  * resolves one per identity (resolveKeyId): the registry badge's key when a
  * badge names this exact key, else "self-certified:ed25519" when the UUAID is
- * exactly the key's uuaid:foundation:agent UUAID, else a `blob-key-unproven`
+ * exactly a self-certifying agent UUAID of the key, else a `blob-key-unproven`
  * refusal.
  */
 /**
@@ -133,7 +133,7 @@ export class PillarBlobHttpClient {
    *   2. the registry badge's presentation keyId, when a fresh registry-signed
    *      badge for this UUAID names this exact public key (badge limits);
    *   3. "self-certified:ed25519", when this UUAID is exactly
-   *      `uuaid:foundation:agent:` + the key's local id (self-certified
+   *      a self-certifying agent namespace + the key's local id (self-certified
    *      limits; the full string, as the broker compares it);
    * else throws `blob-key-unproven`. A badge that names another key, a
    * missing badge and an unreachable registry all fall through to 3.
@@ -158,7 +158,7 @@ export class PillarBlobHttpClient {
     if (!value) {
       throw new BlobBrokerError(
         "blob-key-unproven",
-        `${uuaid} cannot sign broker requests: ${badgeProblem}, and it is not the uuaid:foundation:agent UUAID derived from its key`,
+        `${uuaid} cannot sign broker requests: ${badgeProblem}, and it is not a self-certifying agent UUAID derived from its key`,
         null,
         { fix: REFUSAL_FIXES["blob-key-unproven"] },
       );
@@ -310,7 +310,7 @@ export class PillarBlobHttpClient {
   /**
    * Recipient sender gate for a received blob-ref. "self-certified" when the
    * ref's signature verifies and its sender is exactly that signing key's
-   * uuaid:foundation:agent UUAID (proven key holder, unverified identity);
+   * self-certifying agent UUAID (proven key holder, unverified identity);
    * otherwise "active" when a registry badge names that key; otherwise
    * throws BlobSenderKeyError (code sender-key-not-active, with a fix).
    */

package/src/group-v2-cli.mjs

@@ -0,0 +1,231 @@
+/**
+ * `pillar group` for pillar-group/2 groups. bin/pillar.mjs runs this when
+ * groupCommandRoute says "v2"; tests call runGroupV2 in-process.
+ *
+ * WHAT SENDS, AND TO WHOM (an egress filter reads mailbox groups.members and
+ * the group_v2_sendq queue):
+ *   send <group> <text>|--json   message         the mailbox row minus self (Pillar.sendGroupV2)
+ *   accept <group>               accept.request  the admin, taken from the mailbox row
+ *   leave <group>                leave.request   the mailbox row minus self
+ *   rename <group> <name>        rename.request  the admin, taken from the mailbox row (a member's suggestion)
+ *   sync [<grp-id>]              queued rows     each row's own recipient and key (Pillar.syncGroupV2)
+ * EVERYTHING ELSE SENDS NOTHING:
+ *   create --v2, invite, remove, ext, transfer, the admin's accept/leave
+ *   <group> <uuaid> --request ENV, and the admin's rename: sign, verify as the
+ *   next version, store, write the mailbox row, and QUEUE the manifest sends
+ *   (adminManifestSends) for `sync`. They never start a transport.
+ *   list, show, queue: read only. They open no Pillar and no keychain.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { Mailbox } from "./mailbox/mailbox.mjs";
+import { refusalLine } from "./net/refusals.mjs";
+import { findGroup } from "./groups.mjs";
+import {
+  RosterStore, isGroupIdV2, adminOf, adminCreate, adminChange, adminManifestSends, parseMemberRef,
+  loadGroupForCommand, createV2FlagRefusal,
+} from "./groups-v2.mjs";
+
+export const GROUP_V2_USAGE = `usage (pillar-group/2):
+  pillar group create   <name> [<uuaid>:<pubkey>]... [--purpose TEXT] --v2
+  pillar group send     <group> <text> | --json '{...}' [--kind KIND]
+  pillar group invite   <group> <uuaid>:<pubkey>
+  pillar group accept   <group>                          an invitee asks the admin to let it in
+  pillar group accept   <group> <uuaid> --request ENV_ID the admin folds in that member's request
+  pillar group leave    <group>                          a member leaves
+  pillar group leave    <group> <uuaid> --request ENV_ID the admin records that member's leave
+  pillar group remove   <group> <uuaid>
+  pillar group rename   <group> <name...> [--purpose TEXT]  the admin renames; a member suggests
+  pillar group ext      <group> <json>
+  pillar group transfer <group> <uuaid>
+  pillar group show     <group>
+  pillar group list
+  pillar group queue    [<grp-id>]   the sends waiting for sync (read only)
+  pillar group sync     [<grp-id>]   send them
+<group> is a grp-<32 hex> id or a unique group name. An admin change is stored at once and its
+manifests are queued, not sent; pillar group sync <grp-id> delivers them.`;
+
+const newQueueId = () => `gq-${randomBytes(12).toString("hex")}`;
+
+function openMailbox(home) {
+  const p = join(home, "mailbox.db");
+  return existsSync(p) ? new Mailbox(p) : null;
+}
+
+/** A grp-<32 hex> id, or the id a unique name has in this mailbox; else null. */
+function resolveId(ref, mailbox) {
+  if (isGroupIdV2(ref)) return ref;
+  if (!mailbox || typeof ref !== "string") return null;
+  try { return findGroup(mailbox, ref).id; } catch { return null; }
+}
+
+/**
+ * Run one `pillar group <verb> ...` (args parsed by the bin's parseArgs) for a
+ * v2 group. io: { home, openPillar() -> an UNSTARTED Pillar for this home, out, err }.
+ * Returns the exit code: 0, 1 (refused or a send failed), 2 (usage).
+ */
+export async function runGroupV2(args, io) {
+  const out = io.out ?? ((s) => console.log(s));
+  const err = io.err ?? ((s) => console.error(s));
+  const usage = (why) => { err(why ? `pillar group: ${why}` : GROUP_V2_USAGE); return 2; };
+  const verb = args._[1];
+  try {
+    if (verb === "list") return listGroups(io, out);
+    if (verb === "queue") return queueList(args, io, out, usage); // @rule CLI-queue-read-only
+    if (verb === "show") return showGroup(args, io, out, usage);
+    if (verb === "sync") return queueSync(args, io, out, usage);
+    if (verb === "add") return usage("pillar-group/2 has no add: invite each member with pillar group invite <group> <uuaid>:<pubkey>");
+    if (!["create", "send", "invite", "accept", "leave", "remove", "rename", "ext", "transfer"].includes(verb)) return usage();
+    return await keyed(verb, args, io, out, err, usage);
+  } catch (e) {
+    err(refusalLine(e) ?? `pillar group: ${e.message}`);
+    return 1;
+  }
+}
+
+function listGroups(io, out) {
+  const store = new RosterStore(io.home);
+  const ids = store.list();
+  if (!ids.length) { out("no pillar-group/2 groups in this home"); return 0; }
+  for (const id of ids) {
+    let r;
+    try { r = store.load(id); } catch (e) { out(`${id}  unreadable: ${e.message}`); continue; }
+    const head = r.chain[r.chain.length - 1];
+    out(`${id}  v${head.version}  "${head.name}"  admin ${adminOf(head).uuaid}  ${head.members.filter((m) => m.status === "active").length} active${r.frozen ? "  FROZEN" : ""}${r.outOfDate ? "  out of date" : ""}`);
+  }
+  return 0;
+}
+
+function showGroup(args, io, out, usage) {
+  const ref = args._[2];
+  if (!ref) return usage();
+  const mb = openMailbox(io.home);
+  try {
+    const id = resolveId(ref, mb);
+    if (!id) return usage(`no pillar-group/2 group "${ref}" in this home`);
+    const r = loadGroupForCommand(new RosterStore(io.home), id);
+    const head = r.chain[r.chain.length - 1];
+    out(JSON.stringify({
+      id: r.id, head: r.head, name: head.name, purpose: head.purpose, epoch: head.epoch, members: head.members, ext: head.ext,
+      frozen: !!r.frozen, outOfDate: r.outOfDate, leaving: r.leaving, queued: mb ? mb.queuedGroupV2Sends(id).length : 0,
+    }, null, 2));
+    return 0;
+  } finally { mb?.close(); }
+}
+
+/** Read only: no Pillar, no keychain, no transport. */
+function queueList(args, io, out, usage) {
+  const ref = args._[2];
+  const mb = openMailbox(io.home);
+  try {
+    let id = null;
+    if (ref !== undefined) { id = resolveId(ref, mb); if (!id) return usage(`no pillar-group/2 group "${ref}" in this home`); }
+    const rows = mb ? mb.queuedGroupV2Sends(id) : [];
+    if (!rows.length) { out("nothing queued"); return 0; }
+    for (const q of rows) out(`${q.id}  ${q.group_id}  ${q.op}  -> ${q.recipient}${q.reason ? `  (last attempt: ${q.reason})` : ""}`);
+    out(`${rows.length} queued; send them with: pillar group sync <grp-id>`);
+    return 0;
+  } finally { mb?.close(); }
+}
+
+async function queueSync(args, io, out, usage) {
+  const ref = args._[2];
+  if (ref !== undefined && !isGroupIdV2(ref)) return usage("sync takes a grp-<32 hex> id; it does not resolve names"); // @rule CLI-sync-literal-id
+  const p = await io.openPillar();
+  try {
+    await p.start();
+    const rows = await p.syncGroupV2({ groupId: ref ?? null });
+    for (const r of rows) out(`${r.state}  ${r.groupId}  ${r.op} -> ${r.to}${r.envelopeId ? `  ${r.envelopeId}` : ""}${r.reason ? `  (${r.reason})` : ""}`);
+    out(`${rows.filter((r) => r.state === "sent").length} sent, ${rows.filter((r) => r.state === "dropped").length} dropped, ${rows.filter((r) => r.state === "queued").length} still queued`);
+    return rows.some((r) => r.state === "queued") ? 1 : 0;
+  } finally { await p.stop(); }
+}
+
+async function keyed(verb, args, io, out, err, usage) {
+  const p = await io.openPillar();
+  try {
+    const store = p.groupsV2.store, mb = p.mailbox, me = p.uuaid;
+    /** Queue the manifest sends of the change just stored, and say so. */
+    const queued = (rec, what) => {
+      const sends = adminManifestSends(rec, mb.getGroup(rec.id), me);
+      const ids = mb.enqueueGroupV2Sends(rec.id, sends, { newId: newQueueId });
+      out(`${rec.id}  v${rec.head.version} ${what}  manifest ${rec.head.hash}`);
+      out(`queued ${ids.length} manifest send(s)${ids.length < sends.length ? ` (${sends.length - ids.length} did not fit the queue)` : ""}; deliver with: pillar group sync ${rec.id}`);
+      return 0;
+    };
+    const change = (groupId, action, opts, what) => queued(adminChange({ store, mailbox: mb, keychain: p.keychain, groupId, action, opts }).rec, what);
+    /** A member's request or message, to the recipients the mailbox row gives (Pillar.sendGroupV2). */
+    const sendAs = async (groupId, op, payload, kind = "message") => {
+      await p.start();
+      const r = await p.sendGroupV2({ groupId, op, payload, kind });
+      let failed = 0;
+      for (const x of r.results) {
+        if (x.ok) out(`  ✓ ${x.member}  via ${x.via}  ${x.envelopeId}`);
+        else { failed++; err(`  ✗ ${x.member}  ${refusalLine(x) ?? x.error}`); }
+      }
+      out(`group "${r.group}" ${r.groupId} ${op} ${r.msgId}: ${r.results.length - failed}/${r.results.length} accepted by carrier`);
+      return failed ? 1 : 0;
+    };
+
+    if (verb === "create") {
+      if (createV2FlagRefusal(args)) return usage(createV2FlagRefusal(args)); // @rule CLI-create-flag-refused
+      const [name, ...members] = args._.slice(2);
+      if (!name) return usage();
+      const purpose = typeof args.purpose === "string" ? args.purpose : undefined;
+      return queued(adminCreate({ store, mailbox: mb, keychain: p.keychain, name, purpose, members: members.map(parseMemberRef) }).rec, "create");
+    }
+    const ref = args._[2];
+    if (!ref) return usage();
+    const id = resolveId(ref, mb);
+    if (!id) return usage(`no pillar-group/2 group "${ref}" in this home`);
+    const rec = loadGroupForCommand(store, id);
+    const head = rec.chain[rec.chain.length - 1];
+    const amAdmin = adminOf(head).uuaid === me;
+    const target = args._[3];
+    const request = typeof args.request === "string" ? args.request : null;
+
+    if (verb === "send") {
+      let payload;
+      if (typeof args.json === "string") {
+        try { payload = JSON.parse(args.json); } catch (e) { return usage(`--json is not valid JSON: ${e.message}`); }
+      } else {
+        const text = args._.slice(3).join(" ");
+        if (!text) return usage();
+        payload = { text };
+      }
+      return await sendAs(id, "message", payload, typeof args.kind === "string" ? args.kind : "message");
+    }
+    if (verb === "invite") {
+      if (!target) return usage();
+      return change(id, "invite", { member: parseMemberRef(target) }, `invite ${parseMemberRef(target).uuaid}`);
+    }
+    if (verb === "remove" || verb === "transfer") {
+      if (!target) return usage();
+      return change(id, verb === "remove" ? "remove" : "admin_transfer", { target }, `${verb} ${target}`);
+    }
+    if (verb === "ext") {
+      let ext;
+      try { ext = JSON.parse(args._.slice(3).join(" ")); } catch (e) { return usage(`ext is not JSON: ${e.message}`); }
+      return change(id, "ext_update", { ext }, "ext");
+    }
+    if (verb === "rename") {
+      const name = args._.slice(3).join(" ").trim();
+      if (!amAdmin) {
+        if (!name) return usage();
+        return await sendAs(id, "rename.request", { text: `suggests renaming the group to "${name}"`, name });
+      }
+      const opts = { name: name || head.name };
+      if (typeof args.purpose === "string") opts.purpose = args.purpose;
+      return change(id, "rename", opts, `rename "${opts.name}"`);
+    }
+    // accept / leave: with a member and --request, the admin's change; without, this member's request.
+    if (target !== undefined) {
+      if (!request) return usage(`${verb} ${target} folds in the member's signed ${verb}.request: pass --request <its envelope id>`);
+      return change(id, verb, { target, request }, `${verb} ${target}`);
+    }
+    if (verb === "accept") return await sendAs(id, "accept.request", { text: "asks to join the group" });
+    if (amAdmin) return usage("an admin may not leave: hand the group over first (pillar group transfer <group> <uuaid>)"); // @rule CLI-admin-no-leave
+    return await sendAs(id, "leave.request", { text: "leaves the group" });
+  } finally { await p.stop(); }
+}