chainlesschain 0.160.1 → 0.161.3

package/src/commands/mtc.js

@@ -1640,6 +1640,1127 @@ function registerFederationCommands(mtc) {
         process.exit(1);
       }
     });
+
+  registerFederationGovernanceCommands(fed);
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Federation governance log (MTC_联邦治理_v1.md §9.1) — 8 subcommands
+// ─────────────────────────────────────────────────────────────────────────
+
+function getGovernanceLogPath(federationId) {
+  return path.join(getFederationDir(), "governance", `${federationId}.jsonl`);
+}
+
+function loadGovernanceLog(federationId) {
+  const file = getGovernanceLogPath(federationId);
+  if (!fs.existsSync(file)) return [];
+  const raw = fs.readFileSync(file, "utf-8");
+  const events = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      events.push(JSON.parse(line));
+    } catch (_err) {
+      /* skip corrupt line — replay-from-source-of-truth, don't crash */
+    }
+  }
+  return events;
+}
+
+function appendGovernanceEvent(federationId, event) {
+  const file = getGovernanceLogPath(federationId);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(event) + "\n", "utf-8");
+}
+
+/**
+ * Look up a member's keys + alg for signing a governance event as that
+ * member. Throws if not joined.
+ */
+function loadMemberSigner(federationId, memberId) {
+  const registry = loadFederationRegistry();
+  const fedEntry = registry.federations[federationId];
+  if (!fedEntry || !fedEntry.members[memberId]) {
+    throw new Error(
+      `not joined as "${memberId}" in federation "${federationId}" — \`cc mtc federation join ${federationId} --member-id ${memberId}\` first`,
+    );
+  }
+  const member = fedEntry.members[memberId];
+  if (!member.key_file || !fs.existsSync(member.key_file)) {
+    throw new Error(`member key file missing: ${member.key_file}`);
+  }
+  let signerInfo;
+  if (member.alg === "Ed25519") signerInfo = resolveSigner("ed25519");
+  else if (member.alg === "SLH-DSA-SHA2-128F")
+    signerInfo = resolveSigner("slh-dsa-128f");
+  else throw new Error(`unknown member alg: ${member.alg}`);
+  const keys = loadOrGenerateKeyPair(member.key_file, signerInfo);
+  return { member, keys, alg: member.alg };
+}
+
+function emitAndPersist(federationId, params) {
+  const event = mtcLib.createGovernanceEvent({
+    federationId,
+    ...params,
+  });
+  appendGovernanceEvent(federationId, event);
+  return event;
+}
+
+/**
+ * Pre-flight check that a confirm-* event has its matching propose-*.
+ * Reads the local governance log + checks for an unresolved proposal.
+ * Throws on missing — caller decides whether to log a warning or hard-fail.
+ *
+ * @param {string} federationId
+ * @param {string} proposalType — "propose-revoke" | "propose-threshold"
+ * @param {(payload: object) => boolean} matcher — returns true when payload matches
+ */
+function requireOpenProposal(federationId, proposalType, matcher) {
+  const events = loadGovernanceLog(federationId);
+  // Walk forward; an open proposal is one not yet matched by a confirm of
+  // the same target. v0.1 quorum gating only checks "is there at least one
+  // proposal event with a matching target" — full quorum cooldown logic
+  // lives in lib replay, this is a CLI-side guardrail.
+  // Matcher signature: (payload, event) => boolean
+  const open = events.some(
+    (e) =>
+      e && e.event_type === proposalType && e.payload && matcher(e.payload, e),
+  );
+  if (!open) {
+    throw new Error(
+      `no open ${proposalType} proposal matches — emit ${proposalType} first`,
+    );
+  }
+}
+
+/**
+ * Internal helper used by both the `governance-publish` CLI handler and
+ * the `governance-sync-serve` daemon. Pure side-effect free aside from
+ * filesystem writes to <drop-zone>/federation-governance/<fed>/.
+ *
+ * @returns {{ federation_id, drop_zone, local_total, published, skipped }}
+ */
+function runGovernancePublish(federationId, dropZone) {
+  const events = loadGovernanceLog(federationId);
+  const targetDir = path.join(dropZone, "federation-governance", federationId);
+  fs.mkdirSync(targetDir, { recursive: true });
+  let published = 0;
+  let skipped = 0;
+  for (const ev of events) {
+    if (!ev || typeof ev.event_id !== "string") continue;
+    const target = path.join(targetDir, `${ev.event_id}.json`);
+    if (fs.existsSync(target)) {
+      skipped++;
+      continue;
+    }
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(ev, null, 2), "utf-8");
+    fs.renameSync(tmp, target);
+    published++;
+  }
+  return {
+    federation_id: federationId,
+    drop_zone: targetDir,
+    local_total: events.length,
+    published,
+    skipped,
+  };
+}
+
+/**
+ * Internal helper for governance-pull + governance-sync-serve.
+ * Reads remote events from drop-zone, optionally signature-verifies them,
+ * dedupes by event_id against local log, sorts chronologically, and appends
+ * new events to the local jsonl.
+ *
+ * @returns {{
+ *   federation_id, drop_zone, remote_total, local_total_before,
+ *   appended, duplicates, invalid_signature, unknown_signer
+ * }}
+ */
+function statsPath(federationId) {
+  return path.join(
+    getFederationDir(),
+    "governance",
+    `${federationId}.sync-stats.json`,
+  );
+}
+
+function loadStats(federationId) {
+  const file = statsPath(federationId);
+  if (!fs.existsSync(file)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch (_err) {
+    return {};
+  }
+}
+
+function saveStats(federationId, stats) {
+  const file = statsPath(federationId);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Atomic write so polling readers never see partial JSON
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(stats, null, 2), "utf-8");
+  fs.renameSync(tmp, file);
+}
+
+function runGovernancePull(federationId, dropZone, opts = {}) {
+  const sourceDir = path.join(dropZone, "federation-governance", federationId);
+  if (!fs.existsSync(sourceDir)) {
+    // Daemon-friendly: empty drop-zone is "nothing to pull yet", not an error.
+    return {
+      federation_id: federationId,
+      drop_zone: sourceDir,
+      remote_total: 0,
+      local_total_before: loadGovernanceLog(federationId).length,
+      appended: 0,
+      duplicates: 0,
+      invalid_signature: 0,
+      unknown_signer: 0,
+    };
+  }
+
+  const remote = [];
+  for (const name of fs.readdirSync(sourceDir)) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      const ev = JSON.parse(
+        fs.readFileSync(path.join(sourceDir, name), "utf-8"),
+      );
+      if (ev && typeof ev.event_id === "string") remote.push(ev);
+    } catch (_err) {
+      /* skip malformed */
+    }
+  }
+
+  let invalid = 0;
+  let unknown = 0;
+  let candidates = remote;
+  if (opts.verify) {
+    const registry = loadFederationRegistry();
+    const fedEntry = registry.federations[federationId] || { members: {} };
+    const lookup = (actor /* , keyId */) => {
+      const m = fedEntry.members[actor];
+      if (!m || !m.pubkey_jwk) return null;
+      try {
+        return Buffer.from(m.pubkey_jwk.x, "base64url");
+      } catch (_err) {
+        return null;
+      }
+    };
+    const result = mtcLib.verifyGovernanceLog(remote, lookup);
+    invalid = result.invalid.length;
+    unknown = result.unknown.length;
+    candidates = result.valid;
+  }
+
+  const localEvents = loadGovernanceLog(federationId);
+  const localIds = new Set(
+    localEvents.filter((e) => e && e.event_id).map((e) => e.event_id),
+  );
+  const newEvents = candidates.filter((e) => !localIds.has(e.event_id));
+  const sorted = mtcLib.sortGovernanceEventsChronologically(newEvents);
+  for (const ev of sorted) appendGovernanceEvent(federationId, ev);
+
+  return {
+    federation_id: federationId,
+    drop_zone: sourceDir,
+    remote_total: remote.length,
+    local_total_before: localEvents.length,
+    appended: sorted.length,
+    duplicates: candidates.length - newEvents.length,
+    invalid_signature: invalid,
+    unknown_signer: unknown,
+  };
+}
+
+function registerFederationGovernanceCommands(fed) {
+  // mtc federation invite — propose adding a candidate member
+  fed
+    .command("invite <federation-id> <candidate-member-id>")
+    .description("Propose adding a candidate member (governance.log event)")
+    .requiredOption("--actor <member-id>", "Existing member casting the invite")
+    .requiredOption("--candidate-pubkey-id <id>", "Candidate's pubkey_id")
+    .option("--candidate-alg <alg>", "ed25519 | slh-dsa-128f", "ed25519")
+    .option("--json", "JSON output")
+    .action((federationId, candidateMemberId, options) => {
+      try {
+        const { keys, alg } = loadMemberSigner(federationId, options.actor);
+        const event = emitAndPersist(federationId, {
+          eventType: "invite",
+          actorMemberId: options.actor,
+          secretKey: keys.secretKey,
+          publicKey: keys.publicKey,
+          alg,
+          payload: {
+            candidate_member_id: candidateMemberId,
+            candidate_pubkey_id: options.candidatePubkeyId,
+            candidate_alg: options.candidateAlg,
+          },
+        });
+        if (options.json) return console.log(JSON.stringify(event, null, 2));
+        logger.success(
+          `Invited ${candidateMemberId} into ${federationId} (event ${event.event_id})`,
+        );
+      } catch (err) {
+        logger.error(`mtc federation invite failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // mtc federation vote — vote on an outstanding invite
+  fed
+    .command("vote <federation-id> <candidate-member-id>")
+    .description("Vote on an outstanding invite")
+    .requiredOption("--actor <member-id>", "Voting member")
+    .requiredOption("--decision <approve|reject>", "Vote decision")
+    .option("--json", "JSON output")
+    .action((federationId, candidateMemberId, options) => {
+      try {
+        if (!["approve", "reject"].includes(options.decision)) {
+          throw new Error("--decision must be approve or reject");
+        }
+        const { keys, alg } = loadMemberSigner(federationId, options.actor);
+        const event = emitAndPersist(federationId, {
+          eventType: "vote",
+          actorMemberId: options.actor,
+          secretKey: keys.secretKey,
+          publicKey: keys.publicKey,
+          alg,
+          payload: {
+            invite_target_member_id: candidateMemberId,
+            decision: options.decision,
+          },
+        });
+        if (options.json) return console.log(JSON.stringify(event, null, 2));
+        logger.success(
+          `${options.actor} voted ${options.decision} on ${candidateMemberId} (event ${event.event_id})`,
+        );
+      } catch (err) {
+        logger.error(`mtc federation vote failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // mtc federation propose-revoke
+  fed
+    .command("propose-revoke <federation-id> <target-member-id>")
+    .description("Propose revoking a member (7-day grace period)")
+    .requiredOption("--actor <member-id>", "Proposing member")
+    .requiredOption("--reason <text>", "Reason (e.g. inactive, key-compromise)")
+    .option("--json", "JSON output")
+    .action((federationId, targetMemberId, options) => {
+      try {
+        const { keys, alg } = loadMemberSigner(federationId, options.actor);
+        const event = emitAndPersist(federationId, {
+          eventType: "propose-revoke",
+          actorMemberId: options.actor,
+          secretKey: keys.secretKey,
+          publicKey: keys.publicKey,
+          alg,
+          payload: { target_member_id: targetMemberId, reason: options.reason },
+        });
+        if (options.json) return console.log(JSON.stringify(event, null, 2));
+        logger.success(
+          `Proposed revoke of ${targetMemberId} (reason: ${options.reason}, event ${event.event_id})`,
+        );
+      } catch (err) {
+        logger.error(`mtc federation propose-revoke failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // mtc federation confirm-revoke
+  fed
+    .command("confirm-revoke <federation-id> <target-member-id>")
+    .description("Confirm a previously-proposed revoke (after grace period)")
+    .requiredOption("--actor <member-id>", "Confirming member")
+    .option(
+      "--reason <text>",
+      "Confirmation reason (key-compromise → mark key compromised)",
+    )
+    .option(
+      "--no-quorum-check",
+      "Skip the pre-flight check that a matching propose-revoke exists (caller assumes responsibility)",
+    )
+    .option("--json", "JSON output")
+    .action((federationId, targetMemberId, options) => {
+      try {
+        if (options.quorumCheck !== false) {
+          requireOpenProposal(
+            federationId,
+            "propose-revoke",
+            (p) => p.target_member_id === targetMemberId,
+          );
+        }
+        const { keys, alg } = loadMemberSigner(federationId, options.actor);
+        const event = emitAndPersist(federationId, {
+          eventType: "confirm-revoke",
+          actorMemberId: options.actor,
+          secretKey: keys.secretKey,
+          publicKey: keys.publicKey,
+          alg,
+          payload: { target_member_id: targetMemberId, reason: options.reason },
+        });
+        if (options.json) return console.log(JSON.stringify(event, null, 2));
+        logger.success(
+          `Confirmed revoke of ${targetMemberId} (event ${event.event_id})`,
+        );
+      } catch (err) {
+        logger.error(`mtc federation confirm-revoke failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // mtc federation rotate-key
+  fed
+    .command("rotate-key <federation-id>")
+    .description("Rotate the actor's signing key to a new pubkey")
+    .requiredOption("--actor <member-id>", "Member rotating their key")
+    .requiredOption("--new-pubkey-id <id>", "New public-key id")
+    .option("--new-alg <alg>", "ed25519 | slh-dsa-128f")
+    .option("--json", "JSON output")
+    .action((federationId, options) => {
+      try {
+        const { keys, alg } = loadMemberSigner(federationId, options.actor);
+        const event = emitAndPersist(federationId, {
+          eventType: "rotate-key",
+          actorMemberId: options.actor,
+          secretKey: keys.secretKey,
+          publicKey: keys.publicKey,
+          alg,
+          payload: {
+            new_pubkey_id: options.newPubkeyId,
+            new_alg: options.newAlg,
+          },
+        });
+        if (options.json) return console.log(JSON.stringify(event, null, 2));
+        logger.success(
+          `${options.actor} rotated key to ${options.newPubkeyId} (event ${event.event_id})`,
+        );
+      } catch (err) {
+        logger.error(`mtc federation rotate-key failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // mtc federation propose-threshold
+  fed
+    .command("propose-threshold <federation-id> <new-threshold>")
+    .description("Propose a new M-of-N threshold (30-day cooldown)")
+    .requiredOption("--actor <member-id>", "Proposing member")
+    .option("--json", "JSON output")
+    .action((federationId, newThreshold, options) => {
+      try {
+        const target = parseInt(newThreshold, 10);
+        if (!Number.isInteger(target) || target < 1) {
+          throw new Error("new-threshold must be a positive integer");
+        }
+        const { keys, alg } = loadMemberSigner(federationId, options.actor);
+        const event = emitAndPersist(federationId, {
+          eventType: "propose-threshold",
+          actorMemberId: options.actor,
+          secretKey: keys.secretKey,
+          publicKey: keys.publicKey,
+          alg,
+          payload: { proposed_threshold: target },
+        });
+        if (options.json) return console.log(JSON.stringify(event, null, 2));
+        logger.success(
+          `Proposed threshold ${target} (event ${event.event_id}, 30-day cooldown)`,
+        );
+      } catch (err) {
+        logger.error(`mtc federation propose-threshold failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // mtc federation confirm-threshold — apply a specific (or most recent) propose-threshold
+  fed
+    .command("confirm-threshold <federation-id>")
+    .description(
+      "Confirm a propose-threshold (default: most recent; --proposal-event-id picks a specific one)",
+    )
+    .requiredOption("--actor <member-id>", "Confirming member")
+    .option(
+      "--proposal-event-id <id>",
+      "Specific propose-threshold event_id (CRDT-style explicit selection when multiple proposals are open)",
+    )
+    .option(
+      "--no-quorum-check",
+      "Skip the pre-flight check that an open propose-threshold exists",
+    )
+    .option("--json", "JSON output")
+    .action((federationId, options) => {
+      try {
+        if (options.quorumCheck !== false) {
+          requireOpenProposal(federationId, "propose-threshold", (p, ev) => {
+            if (!Number.isInteger(p.proposed_threshold)) return false;
+            if (
+              options.proposalEventId &&
+              ev &&
+              ev.event_id !== options.proposalEventId
+            ) {
+              return false;
+            }
+            return true;
+          });
+        }
+        const { keys, alg } = loadMemberSigner(federationId, options.actor);
+        const payload = options.proposalEventId
+          ? { proposal_event_id: options.proposalEventId }
+          : {};
+        const event = emitAndPersist(federationId, {
+          eventType: "confirm-threshold",
+          actorMemberId: options.actor,
+          secretKey: keys.secretKey,
+          publicKey: keys.publicKey,
+          alg,
+          payload,
+        });
+        if (options.json) return console.log(JSON.stringify(event, null, 2));
+        logger.success(
+          `Confirmed${options.proposalEventId ? " specific" : ""} threshold proposal (event ${event.event_id})`,
+        );
+      } catch (err) {
+        logger.error(`mtc federation confirm-threshold failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // mtc federation fork
+  fed
+    .command("fork <federation-id> <new-federation-id>")
+    .description(
+      "Spawn a new federation with a subset of current members (members leave the original)",
+    )
+    .requiredOption("--actor <member-id>", "Forking member")
+    .requiredOption(
+      "--members <ids>",
+      "Comma-separated list of member-ids leaving for the new federation",
+    )
+    .option("--json", "JSON output")
+    .action((federationId, newFedId, options) => {
+      try {
+        const memberIds = options.members
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean);
+        const { keys, alg } = loadMemberSigner(federationId, options.actor);
+        const event = emitAndPersist(federationId, {
+          eventType: "fork",
+          actorMemberId: options.actor,
+          secretKey: keys.secretKey,
+          publicKey: keys.publicKey,
+          alg,
+          payload: {
+            new_federation_id: newFedId,
+            member_ids: memberIds,
+          },
+        });
+        if (options.json) return console.log(JSON.stringify(event, null, 2));
+        logger.success(
+          `Forked ${federationId} → ${newFedId} (members: ${memberIds.join(", ")}; event ${event.event_id})`,
+        );
+      } catch (err) {
+        logger.error(`mtc federation fork failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // mtc federation merge
+  fed
+    .command("merge <federation-id> <other-federation-id> <new-federation-id>")
+    .description(
+      "Mark this federation as winding down into a new merged federation",
+    )
+    .requiredOption("--actor <member-id>", "Merging member")
+    .option("--json", "JSON output")
+    .action((federationId, otherFedId, newFedId, options) => {
+      try {
+        const { keys, alg } = loadMemberSigner(federationId, options.actor);
+        const event = emitAndPersist(federationId, {
+          eventType: "merge",
+          actorMemberId: options.actor,
+          secretKey: keys.secretKey,
+          publicKey: keys.publicKey,
+          alg,
+          payload: {
+            other_federation_id: otherFedId,
+            new_federation_id: newFedId,
+          },
+        });
+        if (options.json) return console.log(JSON.stringify(event, null, 2));
+        logger.success(
+          `Merged ${federationId} + ${otherFedId} → ${newFedId} (event ${event.event_id})`,
+        );
+      } catch (err) {
+        logger.error(`mtc federation merge failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // mtc federation governance-sync-libp2p — pubsub gossipsub variant
+  fed
+    .command("governance-sync-libp2p <federation-id>")
+    .description(
+      "Sync governance events over libp2p gossipsub (topic mtc-federation-governance/v1/<fed>)",
+    )
+    .option("--listen <maddr>", "libp2p listen multiaddr", "/ip4/0.0.0.0/tcp/0")
+    .option(
+      "--connect <maddr>",
+      "Seed peer multiaddr (repeatable)",
+      (v, prev) => (prev ? [...prev, v] : [v]),
+      [],
+    )
+    .option(
+      "--interval <seconds>",
+      "Publish-new-events interval (default: 10)",
+      (v) => parseInt(v, 10),
+      10,
+    )
+    .option("--verify", "Verify signatures before appending received events")
+    .option(
+      "--once",
+      "Subscribe + publish-once + wait <interval> seconds, then exit (test/cron)",
+    )
+    .option("--json", "Per-tick JSON output")
+    .action(async (federationId, options) => {
+      try {
+        await runGovernanceSyncLibp2p(federationId, options);
+      } catch (err) {
+        logger.error(
+          `mtc federation governance-sync-libp2p failed: ${err.message}`,
+        );
+        process.exit(1);
+      }
+    });
+
+  // mtc federation governance-sync-stats — read live tick stats written by sync daemons
+  fed
+    .command("governance-sync-stats <federation-id>")
+    .description(
+      "Read live sync stats (last tick + cumulative counters) written by governance-sync-serve / governance-sync-libp2p",
+    )
+    .option("--json", "JSON output")
+    .action((federationId, options) => {
+      try {
+        const file = path.join(
+          getFederationDir(),
+          "governance",
+          `${federationId}.sync-stats.json`,
+        );
+        if (!fs.existsSync(file)) {
+          const empty = {
+            federation_id: federationId,
+            stats_file: file,
+            available: false,
+            note: "No sync daemon has written stats yet — start governance-sync-serve or governance-sync-libp2p first.",
+          };
+          if (options.json) return console.log(JSON.stringify(empty, null, 2));
+          logger.warn(empty.note);
+          return;
+        }
+        const data = JSON.parse(fs.readFileSync(file, "utf-8"));
+        if (options.json) return console.log(JSON.stringify(data, null, 2));
+        logger.log(`Federation: ${federationId}`);
+        logger.log(`Last tick:  ${data.last_tick_at || "—"}`);
+        logger.log(`Mode:       ${data.mode || "—"}`);
+        if (data.publish) {
+          logger.log(
+            `Publish:    last=${data.publish.last_published || 0} new (${data.publish.last_skipped || 0} skipped); total=${data.publish.total_published || 0}`,
+          );
+        }
+        if (data.pull) {
+          logger.log(
+            `Pull:       last=${data.pull.last_appended || 0} new (dedup=${data.pull.last_duplicates || 0}); total=${data.pull.total_appended || 0}`,
+          );
+        }
+        if (data.libp2p) {
+          logger.log(
+            `Libp2p:     wire received=${data.libp2p.wire_received || 0} appended=${data.libp2p.wire_appended || 0} invalid=${data.libp2p.wire_invalid || 0} unknown=${data.libp2p.wire_unknown || 0}`,
+          );
+        }
+      } catch (err) {
+        logger.error(
+          `mtc federation governance-sync-stats failed: ${err.message}`,
+        );
+        process.exit(1);
+      }
+    });
+
+  // mtc federation cross-trust-create — emit a cross-federation trust anchor record (v0.3)
+  fed
+    .command("cross-trust-create <host-fed> <trusted-fed>")
+    .description(
+      "Build a cross-federation trust anchor record (host accepts landmarks from trusted)",
+    )
+    .requiredOption(
+      "--threshold <m>",
+      "Trusted federation's threshold at snapshot time",
+      (v) => parseInt(v, 10),
+    )
+    .requiredOption(
+      "--member <id:pubkey>",
+      "Trusted member entry, id:pubkey_id (repeatable)",
+      (v, prev) => (prev ? [...prev, v] : [v]),
+      [],
+    )
+    .option(
+      "--accepted-kinds <kinds>",
+      "Comma-separated landmark kinds to accept (default: did,skill,bridge,audit)",
+    )
+    .option("--expires-at <iso>", "ISO 8601 expiry (default: 90 days)")
+    .option(
+      "--out <path>",
+      "Write the anchor JSON to a file (otherwise stdout)",
+    )
+    .option("--json", "JSON output (default unless --out given)")
+    .action((hostFed, trustedFed, options) => {
+      try {
+        const roster = (options.member || []).map((entry) => {
+          const [member_id, pubkey_id] = entry.split(":", 2);
+          if (!member_id || !pubkey_id) {
+            throw new Error(
+              `bad --member entry "${entry}", expected id:pubkey_id`,
+            );
+          }
+          return { member_id, pubkey_id, alg: "ed25519" };
+        });
+        const anchor = mtcLib.createCrossFederationTrustAnchor({
+          host_federation_id: hostFed,
+          trusted_federation_id: trustedFed,
+          member_roster_snapshot: roster,
+          threshold: options.threshold,
+          accepted_kinds: options.acceptedKinds
+            ? options.acceptedKinds.split(",").map((s) => s.trim())
+            : undefined,
+          expires_at: options.expiresAt,
+        });
+        const json = JSON.stringify(anchor, null, 2);
+        if (options.out) {
+          fs.mkdirSync(path.dirname(options.out), { recursive: true });
+          fs.writeFileSync(options.out, json, "utf-8");
+          if (options.json) console.log(json);
+          else
+            logger.success(
+              `Cross-fed trust anchor written: ${options.out} (expires ${anchor.expires_at})`,
+            );
+        } else {
+          console.log(json);
+        }
+      } catch (err) {
+        logger.error(
+          `mtc federation cross-trust-create failed: ${err.message}`,
+        );
+        process.exit(1);
+      }
+    });
+
+  // mtc federation cross-trust-validate — validate an anchor's structure + freshness
+  fed
+    .command("cross-trust-validate <anchor-path>")
+    .description("Validate a cross-federation trust anchor JSON file")
+    .option("--json", "JSON output")
+    .action((anchorPath, options) => {
+      try {
+        const anchor = JSON.parse(fs.readFileSync(anchorPath, "utf-8"));
+        const result = mtcLib.validateCrossFederationTrustAnchor(anchor);
+        if (options.json) {
+          console.log(
+            JSON.stringify({ ...result, anchor_path: anchorPath }, null, 2),
+          );
+          if (!result.ok) process.exit(2);
+          return;
+        }
+        if (result.ok) {
+          logger.success(
+            `✓ Anchor valid: ${anchor.host_federation_id} → ${anchor.trusted_federation_id} (expires ${anchor.expires_at})`,
+          );
+        } else {
+          logger.error(`✗ Anchor invalid: ${result.code}`);
+          process.exit(2);
+        }
+      } catch (err) {
+        logger.error(
+          `mtc federation cross-trust-validate failed: ${err.message}`,
+        );
+        process.exit(1);
+      }
+    });
+
+  // mtc federation audit — independent third-party auditor of governance.log (v0.3)
+  fed
+    .command("audit <federation-id>")
+    .description(
+      "Offline audit: replay governance.log + verify each event signature against the rolling roster",
+    )
+    .option("--json", "JSON output (full report incl. final_state)")
+    .option("--summary", "Show only the finding counts + ok/fail")
+    .action((federationId, options) => {
+      try {
+        const events = loadGovernanceLog(federationId);
+        const report = mtcLib.auditGovernanceLog(events, federationId);
+        if (options.json) return console.log(JSON.stringify(report, null, 2));
+        const errorCount = report.findings.filter(
+          (f) => f.severity === "error",
+        ).length;
+        const warnCount = report.findings.filter(
+          (f) => f.severity === "warn",
+        ).length;
+        if (options.summary) {
+          logger.log(
+            `${report.ok ? "✓" : "✗"} ${federationId}: ${report.events_count} events, ${errorCount} errors, ${warnCount} warnings`,
+          );
+          if (!report.ok) process.exit(2);
+          return;
+        }
+        logger.log(`Federation: ${federationId}`);
+        logger.log(`Events:     ${report.events_count}`);
+        logger.log(
+          `Audit:      ${report.ok ? "✓ PASS" : "✗ FAIL"} (errors=${errorCount}, warnings=${warnCount})`,
+        );
+        if (report.findings.length > 0) {
+          logger.log(`\nFindings:`);
+          for (const f of report.findings) {
+            const sev = f.severity === "error" ? "ERROR" : "WARN ";
+            logger.log(`  [${sev}] ${f.code}: ${f.message}`);
+            logger.log(`           event_id=${f.event_id}`);
+          }
+        }
+        if (!report.ok) process.exit(2);
+      } catch (err) {
+        logger.error(`mtc federation audit failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // v0.3 #2 — On-chain governance anchor (Q-COMP-3 unlocked 2026-05-03)
+  // The CLI ships filesystem-backed mock chain client; production wires
+  // a real ConsortiumChainClient via --chain-impl <module> (future).
+
+  fed
+    .command("governance-anchor <federation-id>")
+    .description(
+      "Compute snapshot hash of governance.log + publish to a chain-anchor store (Q-COMP-3 v0.3 #2)",
+    )
+    .requiredOption("--actor <member-id>", "Anchoring member")
+    .requiredOption(
+      "--chain-store <dir>",
+      "Filesystem dir simulating the chain anchor store (production: --chain-impl swap-in)",
+    )
+    .option("--chain-name <name>", "Chain name label", "consortium-mock")
+    .option("--json", "JSON output")
+    .action(async (federationId, options) => {
+      try {
+        const events = loadGovernanceLog(federationId);
+        const record = mtcLib.buildGovernanceAnchorRecord(
+          events,
+          federationId,
+          options.actor,
+        );
+        const client = new mtcLib.FilesystemChainAnchorClient({
+          rootDir: options.chainStore,
+          chainName: options.chainName,
+        });
+        const receipt = await client.publish(record);
+        const out = {
+          federation_id: federationId,
+          anchored: true,
+          snapshot_hash: record.snapshot_hash,
+          events_count: record.events_count,
+          last_event_id: record.last_event_id,
+          tx_hash: receipt.tx_hash,
+          block_height: receipt.block_height,
+          chain_name: options.chainName,
+          anchored_at: receipt.anchored_at,
+        };
+        if (options.json) return console.log(JSON.stringify(out, null, 2));
+        logger.success(
+          `Anchored ${federationId} snapshot (${record.events_count} events, hash=${record.snapshot_hash}) → tx=${receipt.tx_hash} @ block=${receipt.block_height}`,
+        );
+      } catch (err) {
+        logger.error(`mtc federation governance-anchor failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  fed
+    .command("governance-verify-anchor <federation-id>")
+    .description(
+      "Fetch latest chain anchor + compare against local governance.log snapshot hash",
+    )
+    .requiredOption(
+      "--chain-store <dir>",
+      "Filesystem dir simulating the chain anchor store",
+    )
+    .option("--json", "JSON output")
+    .action(async (federationId, options) => {
+      try {
+        const client = new mtcLib.FilesystemChainAnchorClient({
+          rootDir: options.chainStore,
+        });
+        const latest = await client.fetchLatest(federationId);
+        if (!latest) {
+          const out = {
+            federation_id: federationId,
+            ok: false,
+            code: "NO_ANCHOR_ON_CHAIN",
+            message:
+              "No anchor record found for this federation in the chain store",
+          };
+          if (options.json) {
+            console.log(JSON.stringify(out, null, 2));
+            process.exit(2);
+            return;
+          }
+          logger.error(out.message);
+          process.exit(2);
+        }
+        const events = loadGovernanceLog(federationId);
+        const result = mtcLib.verifyGovernanceAnchor(latest, events);
+        const out = {
+          federation_id: federationId,
+          ...result,
+          anchor_block_height: latest.block_height,
+          anchor_tx_hash: latest.tx_hash,
+          anchor_anchored_at: latest.anchored_at,
+        };
+        if (options.json) {
+          console.log(JSON.stringify(out, null, 2));
+          if (!result.ok) process.exit(2);
+          return;
+        }
+        if (result.ok) {
+          logger.success(
+            `✓ Anchor matches: ${result.expected_hash} (block=${latest.block_height}, anchored=${latest.anchored_at})`,
+          );
+        } else {
+          logger.error(
+            `✗ Anchor mismatch: ${result.code}\n  expected: ${result.expected_hash}\n  actual:   ${result.actual_hash}`,
+          );
+          if (result.drift) {
+            logger.log(
+              `  drift: events_count_diff=${result.drift.events_count_diff}`,
+            );
+          }
+          process.exit(2);
+        }
+      } catch (err) {
+        logger.error(
+          `mtc federation governance-verify-anchor failed: ${err.message}`,
+        );
+        process.exit(1);
+      }
+    });
+
+  // mtc federation governance-sync-serve — daemon: periodically publish + pull
+  fed
+    .command("governance-sync-serve <federation-id>")
+    .description(
+      "Daemon: periodically publish local governance events + pull remote ones from a shared drop-zone",
+    )
+    .requiredOption("--drop-zone <dir>", "Shared filesystem directory")
+    .option(
+      "--interval <seconds>",
+      "Sync interval (default: 60)",
+      (v) => parseInt(v, 10),
+      60,
+    )
+    .option(
+      "--verify",
+      "Verify signatures against local registry on pull (default: trust schema only)",
+    )
+    .option("--once", "Sync once and exit (no daemon loop)")
+    .option("--json", "Emit per-tick JSON results to stdout")
+    .action(async (federationId, options) => {
+      const tick = () => {
+        const stamp = new Date().toISOString();
+        try {
+          const pubResult = runGovernancePublish(
+            federationId,
+            options.dropZone,
+          );
+          const pullResult = runGovernancePull(federationId, options.dropZone, {
+            verify: !!options.verify,
+          });
+          // Persist live stats so governance-sync-stats / web GUI can poll
+          const stats = loadStats(federationId);
+          stats.federation_id = federationId;
+          stats.mode = "filesystem";
+          stats.last_tick_at = stamp;
+          stats.publish = stats.publish || { total_published: 0 };
+          stats.publish.last_published = pubResult.published;
+          stats.publish.last_skipped = pubResult.skipped;
+          stats.publish.total_published =
+            (stats.publish.total_published || 0) + pubResult.published;
+          stats.pull = stats.pull || { total_appended: 0 };
+          stats.pull.last_appended = pullResult.appended;
+          stats.pull.last_duplicates = pullResult.duplicates;
+          stats.pull.last_invalid = pullResult.invalid_signature;
+          stats.pull.last_unknown = pullResult.unknown_signer;
+          stats.pull.total_appended =
+            (stats.pull.total_appended || 0) + pullResult.appended;
+          saveStats(federationId, stats);
+
+          if (options.json) {
+            console.log(
+              JSON.stringify(
+                {
+                  tick_at: stamp,
+                  publish: pubResult,
+                  pull: pullResult,
+                },
+                null,
+                2,
+              ),
+            );
+          } else {
+            console.log(
+              `[${stamp}] publish: ${pubResult.published} new (${pubResult.skipped} skipped) | pull: ${pullResult.appended} new (dedup ${pullResult.duplicates}, invalid ${pullResult.invalid_signature}, unknown ${pullResult.unknown_signer})`,
+            );
+          }
+        } catch (err) {
+          console.error(`[${stamp}] tick error: ${err.message}`);
+        }
+      };
+
+      tick();
+      if (options.once) return;
+
+      console.log(
+        `governance-sync-serve: federation=${federationId} interval=${options.interval}s drop-zone=${options.dropZone}. Ctrl-C to stop.`,
+      );
+      const handle = setInterval(tick, options.interval * 1000);
+      const stop = () => {
+        clearInterval(handle);
+        console.log("governance-sync-serve: stopped.");
+        process.exit(0);
+      };
+      process.on("SIGINT", stop);
+      process.on("SIGTERM", stop);
+      await new Promise(() => {});
+    });
+
+  // mtc federation governance-publish — push local events to a shared drop-zone
+  fed
+    .command("governance-publish <federation-id>")
+    .description(
+      "Publish local governance events to a shared drop-zone (filesystem path / NFS / Syncthing)",
+    )
+    .requiredOption("--drop-zone <dir>", "Shared filesystem directory")
+    .option("--json", "JSON output")
+    .action((federationId, options) => {
+      try {
+        const result = runGovernancePublish(federationId, options.dropZone);
+        if (options.json) return console.log(JSON.stringify(result, null, 2));
+        logger.success(
+          `Published ${result.published} new event(s) (${result.skipped} already in drop-zone) to ${result.drop_zone}`,
+        );
+      } catch (err) {
+        logger.error(
+          `mtc federation governance-publish failed: ${err.message}`,
+        );
+        process.exit(1);
+      }
+    });
+
+  // mtc federation governance-pull — pull events from a shared drop-zone, dedupe + verify, append locally
+  fed
+    .command("governance-pull <federation-id>")
+    .description(
+      "Pull governance events from a shared drop-zone, dedupe by event_id, append new ones to the local log (with optional signature verify)",
+    )
+    .requiredOption("--drop-zone <dir>", "Shared filesystem directory")
+    .option(
+      "--verify",
+      "Verify signatures against local registry before appending (default: trust schema only)",
+    )
+    .option("--json", "JSON output")
+    .action((federationId, options) => {
+      try {
+        // CLI surface keeps the strict "must exist" contract; the daemon
+        // helper treats absent drop-zone as "nothing yet" and returns zeros.
+        const sourceDir = path.join(
+          options.dropZone,
+          "federation-governance",
+          federationId,
+        );
+        if (!fs.existsSync(sourceDir)) {
+          throw new Error(
+            `drop-zone has no events for ${federationId}: ${sourceDir}`,
+          );
+        }
+        const result = runGovernancePull(federationId, options.dropZone, {
+          verify: !!options.verify,
+        });
+        if (options.json) return console.log(JSON.stringify(result, null, 2));
+        logger.success(
+          `Pulled ${result.appended} new event(s) (dedup: ${result.duplicates}, invalid: ${result.invalid_signature}, unknown: ${result.unknown_signer})`,
+        );
+      } catch (err) {
+        logger.error(`mtc federation governance-pull failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // mtc federation governance-log — show all events + replayed state
+  fed
+    .command("governance-log <federation-id>")
+    .description("Show governance.log events + current replayed state")
+    .option("--json", "JSON output")
+    .option("--events-only", "Only print events, skip replay state")
+    .action((federationId, options) => {
+      try {
+        const events = loadGovernanceLog(federationId);
+        if (options.eventsOnly) {
+          if (options.json) return console.log(JSON.stringify(events, null, 2));
+          for (const e of events) {
+            logger.log(
+              `${e.issued_at}  ${e.event_type.padEnd(20)} actor=${e.actor_member_id}  event_id=${e.event_id}`,
+            );
+          }
+          return;
+        }
+        const state = mtcLib.replayGovernanceLog(events, federationId);
+        if (options.json) {
+          return console.log(JSON.stringify({ events, state }, null, 2));
+        }
+        logger.log(
+          `Federation: ${state.federation_id}  status=${state.status}  threshold=${state.threshold}`,
+        );
+        logger.log(`Members (${state.members.length}):`);
+        for (const m of state.members) {
+          logger.log(
+            `  ${m.member_id.padEnd(20)} weight=${m.weight} status=${m.status} alg=${m.alg}`,
+          );
+        }
+        if (state.pending_invites.length) {
+          logger.log(`Pending invites (${state.pending_invites.length}):`);
+          for (const i of state.pending_invites) {
+            logger.log(
+              `  ${i.member_id}  approve=${i.votes.approve.length}/${i.required}  reject=${i.votes.reject.length}`,
+            );
+          }
+        }
+        if (state.pending_threshold) {
+          logger.log(
+            `Pending threshold: ${state.pending_threshold.target} (activates ${state.pending_threshold.activates_at})`,
+          );
+        }
+        if (state.archived_keys.length || state.compromised_keys.length) {
+          logger.log(
+            `Archived keys: ${state.archived_keys.length}, compromised: ${state.compromised_keys.length}`,
+          );
+        }
+      } catch (err) {
+        logger.error(`mtc federation governance-log failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
 }
 
 // ─────────────────────────────────────────────────────────────────────────
@@ -1895,6 +3016,219 @@ function federationTopic(federationId) {
   return `${FEDERATION_TOPIC_PREFIX}/${federationId}`;
 }
 
+function governanceTopic(federationId) {
+  return `mtc-federation-governance/v1/${federationId}`;
+}
+
+/**
+ * libp2p gossipsub-based governance sync (Phase 2 of v0.9 sync work).
+ *
+ * Each peer subscribes to mtc-federation-governance/v1/<fed>; on each tick
+ * the peer publishes any local events that haven't been published yet
+ * (tracked in <governance-dir>/<fed>.libp2p-pos.json — a tiny offset file
+ * mapping event_id → already-published flag). Receivers dedupe + optionally
+ * verify each event before appending to their local jsonl.
+ *
+ * --once mode subscribes, publishes one batch, waits one interval to drain
+ * inbox, then exits — suitable for cron / tests.
+ */
+async function runGovernanceSyncLibp2p(federationId, options) {
+  const { Libp2pTransport } =
+    await import("@chainlesschain/core-mtc/transports/libp2p");
+
+  const node = await Libp2pTransport.create({
+    listen: options.listen,
+    mode: "gossipsub",
+  });
+
+  const closeOnError = async (err) => {
+    try {
+      await node.close();
+    } catch (_e) {
+      /* ignore */
+    }
+    throw err;
+  };
+
+  try {
+    return await runGovernanceSyncLibp2pInner(federationId, options, node);
+  } catch (err) {
+    return closeOnError(err);
+  }
+}
+
+function loadLibp2pPubMarkers(federationId) {
+  const file = path.join(
+    getFederationDir(),
+    "governance",
+    `${federationId}.libp2p-pos.json`,
+  );
+  if (!fs.existsSync(file)) return new Set();
+  try {
+    return new Set(JSON.parse(fs.readFileSync(file, "utf-8")));
+  } catch (_err) {
+    return new Set();
+  }
+}
+
+function saveLibp2pPubMarkers(federationId, ids) {
+  const file = path.join(
+    getFederationDir(),
+    "governance",
+    `${federationId}.libp2p-pos.json`,
+  );
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify([...ids]), "utf-8");
+}
+
+async function runGovernanceSyncLibp2pInner(federationId, options, node) {
+  const topic = governanceTopic(federationId);
+  let received = 0;
+  let appendedFromWire = 0;
+  let invalidFromWire = 0;
+  let unknownFromWire = 0;
+
+  // verify lookup (built once from local registry)
+  let verifyLookup = null;
+  if (options.verify) {
+    const registry = loadFederationRegistry();
+    const fedEntry = registry.federations[federationId] || { members: {} };
+    verifyLookup = (actor) => {
+      const m = fedEntry.members[actor];
+      if (!m || !m.pubkey_jwk) return null;
+      try {
+        return Buffer.from(m.pubkey_jwk.x, "base64url");
+      } catch (_err) {
+        return null;
+      }
+    };
+  }
+
+  // Subscribe + dispatch
+  node.subscribeRaw(topic, (bytes) => {
+    received++;
+    let ev;
+    try {
+      ev = JSON.parse(new TextDecoder().decode(bytes));
+    } catch (_err) {
+      return;
+    }
+    if (!ev || typeof ev.event_id !== "string") return;
+
+    if (verifyLookup) {
+      const result = mtcLib.verifyGovernanceLog([ev], verifyLookup);
+      if (result.invalid.length) {
+        invalidFromWire++;
+        return;
+      }
+      if (result.unknown.length) {
+        unknownFromWire++;
+        return;
+      }
+    }
+
+    // Dedupe vs local log
+    const local = loadGovernanceLog(federationId);
+    if (local.some((e) => e && e.event_id === ev.event_id)) return;
+    appendGovernanceEvent(federationId, ev);
+    appendedFromWire++;
+  });
+
+  // Dial seed peers
+  for (const peer of options.connect || []) {
+    try {
+      await node.dial(peer);
+    } catch (err) {
+      console.warn(`[libp2p] dial ${peer} failed: ${err.message}`);
+    }
+  }
+
+  const publishTick = async () => {
+    const stamp = new Date().toISOString();
+    const local = loadGovernanceLog(federationId);
+    const published = loadLibp2pPubMarkers(federationId);
+    let publishedThisTick = 0;
+    for (const ev of local) {
+      if (!ev || typeof ev.event_id !== "string") continue;
+      if (published.has(ev.event_id)) continue;
+      try {
+        await node.publishRaw(topic, JSON.stringify(ev));
+        published.add(ev.event_id);
+        publishedThisTick++;
+      } catch (err) {
+        console.warn(`[libp2p] publish ${ev.event_id} failed: ${err.message}`);
+      }
+    }
+    if (publishedThisTick > 0) saveLibp2pPubMarkers(federationId, published);
+
+    // Persist live stats so governance-sync-stats / web GUI can poll
+    const stats = loadStats(federationId);
+    stats.federation_id = federationId;
+    stats.mode = "libp2p";
+    stats.last_tick_at = stamp;
+    stats.publish = stats.publish || { total_published: 0 };
+    stats.publish.last_published = publishedThisTick;
+    stats.publish.total_published =
+      (stats.publish.total_published || 0) + publishedThisTick;
+    stats.libp2p = stats.libp2p || {};
+    stats.libp2p.wire_received = received;
+    stats.libp2p.wire_appended = appendedFromWire;
+    stats.libp2p.wire_invalid = invalidFromWire;
+    stats.libp2p.wire_unknown = unknownFromWire;
+    stats.libp2p.topic = topic;
+    saveStats(federationId, stats);
+
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            tick_at: stamp,
+            published: publishedThisTick,
+            wire_received: received,
+            wire_appended: appendedFromWire,
+            wire_invalid: invalidFromWire,
+            wire_unknown: unknownFromWire,
+          },
+          null,
+          2,
+        ),
+      );
+    } else {
+      console.log(
+        `[${stamp}] published ${publishedThisTick} new event(s); wire received=${received} appended=${appendedFromWire} invalid=${invalidFromWire} unknown=${unknownFromWire}`,
+      );
+    }
+  };
+
+  await publishTick();
+
+  if (options.once) {
+    // Wait one interval to drain inbox, then exit cleanly
+    await new Promise((r) => setTimeout(r, options.interval * 1000));
+    await publishTick();
+    await node.close();
+    return;
+  }
+
+  console.log(
+    `governance-sync-libp2p: federation=${federationId} topic=${topic} interval=${options.interval}s. Ctrl-C to stop.`,
+  );
+  const handle = setInterval(publishTick, options.interval * 1000);
+  const stop = async () => {
+    clearInterval(handle);
+    try {
+      await node.close();
+    } catch (_e) {
+      /* ignore */
+    }
+    console.log("governance-sync-libp2p: stopped.");
+    process.exit(0);
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  await new Promise(() => {});
+}
+
 async function runFederationDiscoverLibp2p(federationId, options) {
   const FederationAnnounceCache = mtcLib.FederationAnnounceCache;
   const { Libp2pTransport } =