fullstackgtm 0.25.2 → 0.27.0

package/dist/planStore.d.ts

@@ -11,6 +11,12 @@ export type StoredPlan = {
     status: ApprovalStatus;
     approvedOperationIds: string[];
     valueOverrides: Record<string, unknown>;
+    /**
+     * HMAC of each approved operation's content at approval time (see
+     * integrity.ts). Apply re-verifies these so a post-approval edit to the plan
+     * file is caught instead of written. Absent on plans approved before 0.26.0.
+     */
+    approvalDigests?: Record<string, string>;
     runs: PatchPlanRun[];
     createdAt: string;
     updatedAt: string;

package/dist/planStore.js

@@ -1,6 +1,7 @@
 import { chmodSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.js";
+import { computeApprovalDigests, loadOrCreateSigningKey } from "./integrity.js";
 /**
  * Plans as JSON files in a directory (default `$FSGTM_HOME/plans`), one file
  * per plan id. Filesystem-shaped on purpose: greppable, diffable, and any
@@ -90,11 +91,18 @@ export function createFilePlanStore(directory) {
                     throw new Error(`Plan ${planId} has no operation ${operationId}.`);
                 }
             }
+            const approvedOperationIds = Array.from(new Set([...stored.approvedOperationIds, ...operationIds]));
+            const mergedOverrides = { ...stored.valueOverrides, ...valueOverrides };
+            // Bind the approval to the operation content so apply can detect a
+            // post-approval edit. Recompute over ALL approved ops (a later approve
+            // call may add overrides that change an earlier op's resolved value).
+            const approvalDigests = computeApprovalDigests(stored.plan.operations, approvedOperationIds, mergedOverrides, loadOrCreateSigningKey());
             return write({
                 ...stored,
                 status: "approved",
-                approvedOperationIds: Array.from(new Set([...stored.approvedOperationIds, ...operationIds])),
-                valueOverrides: { ...stored.valueOverrides, ...valueOverrides },
+                approvedOperationIds,
+                valueOverrides: mergedOverrides,
+                approvalDigests,
             });
         },
         async reject(planId) {

package/dist/schedule.js

@@ -61,6 +61,10 @@ export function validateSchedulableArgv(argv) {
             throw new Error("A scheduled apply cannot take --plan/--approve — file-based approval would bypass the " +
                 "plan store's approval state. Use `apply --plan-id <id>` and approve via `plans approve`.");
         }
+        if (argv.includes("--value")) {
+            throw new Error("A scheduled apply cannot take --value — an unattended run must write exactly the values " +
+                "signed at approval. Set the value with `plans approve --value <op>=<v>` and re-approve.");
+        }
         return;
     }
     if (!Object.hasOwn(SCHEDULABLE, head)) {

package/dist/types.d.ts

@@ -239,6 +239,22 @@ export type PatchOperation = {
      * member of the group.
      */
     groupId?: string;
+    /**
+     * Set only when a human explicitly chose to archive a record that shares an
+     * identity key with another (`bulk-update --archive --force-archive-duplicates`).
+     * Without it, apply refuses to archive_record a record the live snapshot still
+     * sees as a duplicate — archiving a duplicate discards data that merging keeps,
+     * and an agent on a dedupe task must not silently substitute archive for merge.
+     */
+    forceArchiveDuplicate?: boolean;
+    /**
+     * For irreversible operations (merge_records, archive_record): the field
+     * values of the records that will be destroyed, captured at plan-build time.
+     * Merges and archives cannot be undone on any provider, so this is the
+     * recovery artifact a human uses to recreate a record by hand if a merge or
+     * archive was wrong — the plan file IS the backup.
+     */
+    recoverySnapshot?: Record<string, unknown>[];
 };
 /**
  * A patch plan is always a dry-run proposal. Applying a plan never mutates

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "fullstackgtm",
-  "version": "0.25.2",
+  "version": "0.27.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
-  "author": "Full Stack GTM",
+  "author": "Full Stack GTM <security@fullstackgtm.com> (https://fullstackgtm.com)",
   "homepage": "https://github.com/fullstackgtm/core#readme",
   "bugs": {
     "url": "https://github.com/fullstackgtm/core/issues"
@@ -31,7 +31,10 @@
     "INSTALL_FOR_AGENTS.md",
     "llms.txt",
     "skills",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE",
+    "SECURITY.md",
+    "DATA-FLOWS.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/src/auditLog.ts

@@ -0,0 +1,173 @@
+import { createHash, createHmac } from "node:crypto";
+import { loadOrCreateSigningKey, loadSigningKey } from "./integrity.ts";
+import type { PatchPlanRun } from "./types.ts";
+import type { StoredPlan } from "./planStore.ts";
+
+/**
+ * Exportable, tamper-evident audit log.
+ *
+ * Every apply run is already recorded per-plan in the store, but a compliance /
+ * change-management process needs ONE portable artifact it can archive and
+ * later prove was not edited. `audit-log export` flattens every run across all
+ * plans into a hash-chained sequence: each entry carries the hash of the
+ * previous entry, so removing, reordering, or editing any entry breaks the
+ * chain at that point and `audit-log verify` reports exactly where. When a
+ * per-install signing key exists, the chain head is also HMAC-signed, so the
+ * export can be attributed to this installation, not just shown internally
+ * consistent.
+ *
+ * This is a point-in-time attestation of the stored run history; it is not a
+ * real-time append-only journal (that is future work). It answers "give me an
+ * auditable record of every change this tool applied, that my auditor can
+ * verify hasn't been doctored."
+ */
+
+export type AuditLogEntry = {
+  seq: number;
+  planId: string;
+  planTitle: string;
+  provider: string;
+  startedAt: string;
+  finishedAt: string;
+  status: PatchPlanRun["status"];
+  trigger: string;
+  /** operationId → status, the per-operation outcome of this run */
+  operations: Array<{ operationId: string; status: string; detail?: string }>;
+  prevHash: string;
+  hash: string;
+};
+
+export type AuditLogExport = {
+  version: 1;
+  generatedAt: string;
+  entryCount: number;
+  chainHead: string;
+  /** HMAC of chainHead with the per-install key, or null when no key exists. */
+  signature: string | null;
+  entries: AuditLogEntry[];
+};
+
+const GENESIS = "0".repeat(64);
+
+/** The content that the chain hash covers — everything but prevHash/hash. */
+function entryContent(entry: Omit<AuditLogEntry, "prevHash" | "hash">): string {
+  return JSON.stringify([
+    entry.seq,
+    entry.planId,
+    entry.planTitle,
+    entry.provider,
+    entry.startedAt,
+    entry.finishedAt,
+    entry.status,
+    entry.trigger,
+    entry.operations,
+  ]);
+}
+
+function chainHash(prevHash: string, content: string): string {
+  return createHash("sha256").update(prevHash).update("\n").update(content).digest("hex");
+}
+
+/** Flatten all runs from the stored plans, oldest first, into chained entries. */
+export function buildAuditLog(plans: StoredPlan[], generatedAt: string): AuditLogExport {
+  const runs: Array<{ stored: StoredPlan; run: PatchPlanRun }> = [];
+  for (const stored of plans) {
+    for (const run of stored.runs ?? []) runs.push({ stored, run });
+  }
+  runs.sort((a, b) => a.run.finishedAt.localeCompare(b.run.finishedAt));
+
+  const entries: AuditLogEntry[] = [];
+  let prevHash = GENESIS;
+  runs.forEach(({ stored, run }, index) => {
+    const base = {
+      seq: index,
+      planId: run.planId,
+      planTitle: stored.plan.title,
+      provider: run.provider,
+      startedAt: run.startedAt,
+      finishedAt: run.finishedAt,
+      status: run.status,
+      trigger: (run as { trigger?: string }).trigger ?? "manual",
+      operations: run.results.map((result) => ({
+        operationId: result.operationId,
+        status: result.status,
+        ...(result.detail ? { detail: result.detail } : {}),
+      })),
+    };
+    const hash = chainHash(prevHash, entryContent(base));
+    entries.push({ ...base, prevHash, hash });
+    prevHash = hash;
+  });
+
+  // Always sign — an unsigned export's keyless sha256 chain is self-recomputable
+  // (an attacker can edit entries and rebuild the chain from the public genesis),
+  // so the per-install HMAC is the only real tamper barrier. Bind the header
+  // fields into the signed material so metadata can't be altered either.
+  const key = loadOrCreateSigningKey();
+  const entryCount = entries.length;
+  return {
+    version: 1,
+    generatedAt,
+    entryCount,
+    chainHead: prevHash,
+    signature: signHead(key, 1, generatedAt, entryCount, prevHash),
+    entries,
+  };
+}
+
+function signHead(key: Buffer, version: number, generatedAt: string, entryCount: number, chainHead: string): string {
+  return createHmac("sha256", key).update(JSON.stringify([version, generatedAt, entryCount, chainHead])).digest("hex");
+}
+
+export type AuditLogVerification = {
+  ok: boolean;
+  /** seq of the first entry whose hash does not verify, or null if the chain holds */
+  brokenAt: number | null;
+  signatureOk: boolean | null; // null = no signature present / no key to check
+  detail: string;
+};
+
+/** Recompute the chain (and the signature if a key is available). */
+export function verifyAuditLog(log: AuditLogExport): AuditLogVerification {
+  let prevHash = GENESIS;
+  for (const entry of log.entries) {
+    if (entry.prevHash !== prevHash) {
+      return { ok: false, brokenAt: entry.seq, signatureOk: null, detail: `Chain breaks at entry ${entry.seq}: prevHash does not match the previous entry's hash (an entry was removed, reordered, or edited).` };
+    }
+    const expected = chainHash(prevHash, entryContent(entry));
+    if (expected !== entry.hash) {
+      return { ok: false, brokenAt: entry.seq, signatureOk: null, detail: `Chain breaks at entry ${entry.seq}: its content was edited after export (hash mismatch).` };
+    }
+    prevHash = entry.hash;
+  }
+  if (prevHash !== log.chainHead) {
+    return { ok: false, brokenAt: log.entries.length, signatureOk: null, detail: "The recorded chainHead does not match the recomputed chain." };
+  }
+  // The keyless chain alone is self-recomputable, so a missing/stripped signature
+  // means the export is forgeable — refuse it. (Current exports are always
+  // signed; a null signature is an old/unsigned or a downgraded export.)
+  if (!log.signature) {
+    return {
+      ok: false,
+      brokenAt: null,
+      signatureOk: false,
+      detail: "Unsigned export: the hash chain alone is self-recomputable, so this log cannot be trusted (the signature is absent or was stripped). Re-export on the issuing install.",
+    };
+  }
+  const key = loadSigningKey();
+  if (!key) {
+    // A third party without the issuing install's key cannot verify attribution.
+    // The chain is internally consistent, but that is not proof of authenticity.
+    return {
+      ok: false,
+      brokenAt: null,
+      signatureOk: null,
+      detail: "Chain is internally consistent, but this machine has no signing key to verify the signature — authenticity is unattributed. Verify on the issuing install.",
+    };
+  }
+  const signatureOk = signHead(key, log.version, log.generatedAt, log.entryCount, prevHash) === log.signature;
+  if (!signatureOk) {
+    return { ok: false, brokenAt: null, signatureOk: false, detail: "Signature does not match this installation's key — the log was exported elsewhere, or its entries/metadata were altered after signing." };
+  }
+  return { ok: true, brokenAt: null, signatureOk: true, detail: `Verified ${log.entries.length} entries; chain intact and signature valid.` };
+}

package/src/bulkUpdate.ts

@@ -27,6 +27,7 @@
  * `account.ownerId`, `account.contactCount`; accounts get `contactCount`
  * and `openDealCount`.
  */
+import { recoverableFields } from "./dedupe.ts";
 import { normalizeDomain } from "./merge.ts";
 import { stableHash } from "./rules.ts";
 import type {
@@ -399,7 +400,11 @@ export function buildBulkUpdatePlan(
         beforeValue: null,
         afterValue: null,
         riskLevel: "high",
-        rollback: "Archived records can be restored from the provider's recycle bin within its retention window.",
+        // Carry the human's explicit force decision to the apply-time guard, and
+        // snapshot the record so it can be recreated if the archive was wrong.
+        ...(options.forceArchiveDuplicates ? { forceArchiveDuplicate: true } : {}),
+        recoverySnapshot: [recoverableFields(record)],
+        rollback: "Archived records can be restored from the provider's recycle bin within its retention window; recoverySnapshot also retains the field values.",
       });
       continue;
     }

package/src/cli.ts

@@ -34,6 +34,8 @@ import {
 import { generateDemoSnapshot } from "./demo.ts";
 import { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
 import { mergeSnapshots } from "./merge.ts";
+import { verifyApprovalDigests } from "./integrity.ts";
+import { buildAuditLog, verifyAuditLog } from "./auditLog.ts";
 import { createFilePlanStore } from "./planStore.ts";
 import { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./report.ts";
 import { builtinAuditRules } from "./rules.ts";
@@ -60,6 +62,7 @@ import {
   type CallDocument,
 } from "./marketOverlay.ts";
 import { computeScaleIndex, scaleReportToText } from "./marketScale.ts";
+import { suggestMarketConfig } from "./marketTaxonomy.ts";
 import { buildWorksheet, classifyMarket } from "./marketClassify.ts";
 import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 import {
@@ -252,6 +255,7 @@ Usage:
   fullstackgtm plans approve <id> --values-from <suggestions.json> [--min-confidence high|low] [--include-creates]
   fullstackgtm apply --plan-id <id> --provider <name>
   fullstackgtm apply --plan <path> --provider <name> --approve <ids|all> [options]
+  fullstackgtm audit-log export [--out <path>] | verify --in <path>   tamper-evident apply-run record
   fullstackgtm rules [--json]
   fullstackgtm profiles [--json]               list credential profiles
   fullstackgtm doctor [--json]                 check install, credentials, and next step
@@ -976,6 +980,8 @@ async function marketCommand(args: string[]) {
   if (!subcommand || subcommand === "--help" || subcommand === "-h" || rest.includes("--help") || rest.includes("-h")) {
     console.log(`Usage:
 market init --category <name> [--out <path>]   write a starter market.config.json
+market init --category <name> --auto --vendor <url> [--vendor <url>...] [--anchor <url>] [--max-claims n]
+                                               LLM-propose vendors + claim taxonomy from seed pages (needs an API key)
 market capture [--config <path>] [--run <label>]
 market classify [--run <label>] [--capture-run <label>] [--vendor <id>] [--model m] [--out <path>]
 market worksheet --vendor <id> [--capture-run <label>] [--out <path>]
@@ -1025,6 +1031,31 @@ recomputed deterministically on every invocation — never stored.`);
     if (!category) throw new Error("market init requires --category <name>");
     const outPath = resolve(process.cwd(), option(rest, "--out") ?? "market.config.json");
     if (existsSync(outPath)) throw new Error(`${outPath} already exists — refusing to overwrite`);
+
+    if (rest.includes("--auto")) {
+      const vendorUrls = repeatedOption(rest, "--vendor");
+      if (vendorUrls.length === 0) {
+        throw new Error("market init --auto requires at least one --vendor <url> (the competitor homepages to seed from)");
+      }
+      const anchorUrl = option(rest, "--anchor");
+      const credential = await requireLlmCredential("market classify");
+      console.error(`Capturing ${vendorUrls.length} seed page(s) and proposing a claim taxonomy with ${credential.provider}…`);
+      const { config, unreadableVendorIds, model } = await suggestMarketConfig({
+        category,
+        vendors: vendorUrls.map((url) => ({ url, anchor: anchorUrl ? url === anchorUrl : false })),
+        llm: { ...credential, model: option(rest, "--model") ?? undefined },
+        maxClaims: numericOption(rest, "--max-claims"),
+      });
+      writeFileSync(outPath, `${JSON.stringify(config, null, 2)}\n`);
+      if (unreadableVendorIds.length > 0) {
+        console.error(`Note: no readable text for ${unreadableVendorIds.join(", ")} — excluded from taxonomy grounding.`);
+      }
+      console.log(
+        `Wrote ${outPath}: ${config.vendors.length} vendors, ${config.claims.length} proposed claims (${model}). Review it, then: fullstackgtm market refresh`,
+      );
+      return;
+    }
+
     writeFileSync(outPath, `${JSON.stringify(starterMarketConfig(category), null, 2)}\n`);
     console.log(`Wrote ${outPath}. Fill in vendors and claims, then: fullstackgtm market capture`);
     return;
@@ -2529,6 +2560,50 @@ function readSuggestionValues(path: string, minConfidence: string, includeCreate
   return { overrides, skipped };
 }
 
+async function auditLogCommand(args: string[]) {
+  const [sub, ...rest] = args;
+  if (!sub || sub === "--help" || sub === "-h" || (sub !== "export" && sub !== "verify")) {
+    console.log(`Usage:
+audit-log export [--out <path>] [--json]   hash-chained, signed record of every apply run
+audit-log verify [--in <path>]             re-check an exported log's chain and signature
+
+export flattens every apply run across all stored plans (this profile) into a
+tamper-evident chain — each entry carries the prior entry's hash, and the chain
+head is HMAC-signed with this install's key — so a change-management process can
+archive one file and later prove it was not edited. verify recomputes the chain
+and (if the signing key is present) the signature.`);
+    return;
+  }
+
+  if (sub === "export") {
+    const plans = await createFilePlanStore().list();
+    const log = buildAuditLog(plans, new Date().toISOString());
+    const payload = `${JSON.stringify(log, null, 2)}\n`;
+    const outPath = option(rest, "--out");
+    if (outPath) {
+      writeFileSync(resolve(process.cwd(), outPath), payload);
+      console.log(`Wrote ${outPath}: ${log.entryCount} run(s), chain head ${log.chainHead.slice(0, 12)}${log.signature ? " (signed)" : " (unsigned — no signing key on this install)"}.`);
+    } else if (rest.includes("--json")) {
+      console.log(payload);
+    } else {
+      console.log(`${log.entryCount} apply run(s); chain head ${log.chainHead.slice(0, 12)}${log.signature ? ", signed" : ", unsigned"}. Pass --out <path> to archive, or --json to print.`);
+    }
+    return;
+  }
+
+  // verify
+  const inPath = option(rest, "--in");
+  if (!inPath) throw new Error("audit-log verify requires --in <exported-log.json>");
+  const log = JSON.parse(readFileSync(resolve(process.cwd(), inPath), "utf8")) as Parameters<typeof verifyAuditLog>[0];
+  const result = verifyAuditLog(log);
+  if (rest.includes("--json")) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(result.ok ? `OK — ${result.detail}` : `TAMPERED — ${result.detail}`);
+  }
+  if (!result.ok) process.exitCode = 2;
+}
+
 async function apply(args: string[]) {
   const provider = option(args, "--provider");
   if (!provider) throw new Error("apply requires --provider <name>");
@@ -2552,7 +2627,40 @@ async function apply(args: string[]) {
     }
     plan = stored.plan;
     approvedOperationIds = stored.approvedOperationIds;
+    // Downgrade guard: an approved plan with no signatures is either pre-0.26
+    // (re-approve to gain them) or had its approvalDigests stripped to skip the
+    // integrity check. Either way, refuse rather than fall back to trusting the
+    // file. (A plan with zero approved operations has nothing to apply anyway.)
+    if (stored.approvedOperationIds.length > 0 && !stored.approvalDigests) {
+      throw new Error(
+        `Refusing to apply plan ${planId}: it was approved without integrity signatures ` +
+          "(approved before 0.26.0, or its signatures were removed). Re-approve it with " +
+          `\`fullstackgtm plans approve ${planId} --operations <ids|all>\`.`,
+      );
+    }
+    // Integrity gate: the plan file is re-read from disk, so verify each approved
+    // operation still matches what was signed at approval. Verify against the
+    // EFFECTIVE overrides (stored ∪ apply-time --value): the invariant is "what
+    // gets written must equal what was signed", so an apply-time --value that
+    // changes a value the human did not approve is treated as tamper, not a live
+    // override. A mismatch means the plan/overrides were edited after approval —
+    // refuse the whole apply rather than write an unapproved value.
     valueOverrides = { ...stored.valueOverrides, ...parseValueOverrides(args) };
+    const verification = verifyApprovalDigests(
+      stored.plan.operations,
+      stored.approvedOperationIds,
+      valueOverrides,
+      stored.approvalDigests,
+    );
+    if (!verification.ok) {
+      const detail =
+        verification.reason === "no_key"
+          ? "the plan-signing key is missing (was this plan approved on another machine?). Re-approve it here with `fullstackgtm plans approve`."
+          : `these operations differ from what was approved: ${verification.tampered.join(", ")}. ` +
+            "If you changed a value at apply time, set it at approval instead (`plans approve --value <op>=<v>`) and re-approve; " +
+            "otherwise the plan was edited after approval — review and re-approve.";
+      throw new Error(`Refusing to apply plan ${planId}: ${detail}`);
+    }
   } else {
     const approve = option(args, "--approve");
     if (!approve) {
@@ -3354,6 +3462,10 @@ export async function runCli(argv: string[]) {
     await plansCommand(args);
     return;
   }
+  if (command === "audit-log") {
+    await auditLogCommand(args);
+    return;
+  }
   if (command === "apply") {
     await apply(args);
     return;

package/src/connector.ts

@@ -1,5 +1,7 @@
+import { dedupeKey } from "./dedupe.ts";
 import { requiresHumanInput } from "./rules.ts";
 import type {
+  CanonicalGtmSnapshot,
   GtmConnector,
   PatchOperation,
   PatchOperationResult,
@@ -8,6 +10,75 @@ import type {
   PatchPlanRunStatus,
 } from "./types.ts";
 
+const IRREVERSIBLE_OPERATIONS = new Set(["merge_records", "archive_record"]);
+const IDENTITY_KEY_BY_TYPE: Partial<Record<string, "domain" | "email">> = {
+  account: "domain",
+  contact: "email",
+};
+
+/** snapshot collection for an object type */
+function collectionFor(objectType: string): "accounts" | "contacts" | "deals" | null {
+  if (objectType === "account") return "accounts";
+  if (objectType === "contact") return "contacts";
+  if (objectType === "deal") return "deals";
+  return null;
+}
+
+/**
+ * Drift/safety check for the two IRREVERSIBLE operations against a fresh
+ * snapshot. Returns a conflict detail string, or null if the op is safe to
+ * apply. These operations get NO field compare-and-set (there is no single
+ * field to compare), so this snapshot check is their only guard.
+ */
+function checkIrreversibleOp(operation: PatchOperation, snapshot: CanonicalGtmSnapshot): string | null {
+  const collection = collectionFor(operation.objectType);
+  if (!collection) return null;
+  const records = snapshot[collection] as Array<Record<string, unknown>>;
+  const byId = (id: string) => records.find((record) => String(record.id) === id);
+
+  if (operation.operation === "archive_record") {
+    if (!byId(operation.objectId)) {
+      return `Record ${operation.objectType}/${operation.objectId} no longer exists (already archived or merged). Re-plan against current data.`;
+    }
+    // Archiving a duplicate discards data a merge would keep — refuse unless the
+    // human explicitly forced it. This catches every archive_record path (agent,
+    // hand-edited plan, audit), not just `bulk-update --archive`.
+    if (!operation.forceArchiveDuplicate) {
+      const keyName = IDENTITY_KEY_BY_TYPE[operation.objectType];
+      if (keyName) {
+        const target = byId(operation.objectId)!;
+        const key = dedupeKey(target, keyName);
+        if (key) {
+          const sharers = records.filter(
+            (record) => String(record.id) !== operation.objectId && dedupeKey(record, keyName) === key,
+          );
+          if (sharers.length > 0) {
+            return (
+              `Refusing to archive ${operation.objectType}/${operation.objectId}: it shares ${keyName} "${key}" with ` +
+              `${sharers.length} other record(s) — that's a duplicate, and archiving discards its data where merging keeps it. ` +
+              `Merge with \`fullstackgtm dedupe ${operation.objectType} --key ${keyName}\` instead, or rebuild the op with --force-archive-duplicates.`
+            );
+          }
+        }
+      }
+    }
+    return null;
+  }
+
+  if (operation.operation === "merge_records") {
+    if (!byId(operation.objectId)) {
+      return `Merge survivor ${operation.objectType}/${operation.objectId} no longer exists (archived or merged away since the plan was built). Re-plan — merges are irreversible.`;
+    }
+    const groupIds = Array.isArray(operation.beforeValue) ? (operation.beforeValue as unknown[]).map(String) : [];
+    const losersStillPresent = groupIds.filter((id) => id !== operation.objectId && byId(id));
+    if (groupIds.length > 0 && losersStillPresent.length === 0) {
+      return `Every record to merge into ${operation.objectType}/${operation.objectId} is already gone (merge already applied?). Nothing to do — re-plan if duplicates remain.`;
+    }
+    return null;
+  }
+  return null;
+}
+
 export type ApplyPatchPlanOptions = {
   /**
    * Explicit allow-list of operation ids the human approved. Operations not
@@ -79,10 +150,20 @@ export async function applyPatchPlan(
   // closed — but it can be shrunk: re-run the snapshot checks after the
   // first write and every `recheckEvery` writes, conflicting out any
   // operation whose record went stale mid-run.
+  // Irreversible ops (merge/archive) need a fresh snapshot too — it is their
+  // only drift/safety guard (no field to compare-and-set). Respect a caller's
+  // explicit checkConflicts:false opt-out (a stub/known-stale snapshot).
+  const hasIrreversibleApproved =
+    checkConflicts &&
+    plan.operations.some(
+      (operation) => approved.has(operation.id) && IRREVERSIBLE_OPERATIONS.has(operation.operation),
+    );
   const needsSnapshot =
-    ((plan.guards && plan.guards.length > 0) || plan.filter) && connector.fetchSnapshot;
+    ((plan.guards && plan.guards.length > 0) || plan.filter || hasIrreversibleApproved) &&
+    connector.fetchSnapshot;
   const recheckEvery = Math.max(1, options.recheckEvery ?? 25);
   const staleIds = new Set<string>();
+  const irreversibleStale = new Map<string, string>();
   let guardFailure: string | null = null;
   const refreshSnapshotChecks = async (): Promise<void> => {
     if (!needsSnapshot) return;
@@ -95,6 +176,14 @@ export async function applyPatchPlan(
         if (!stillEligible.has(operation.objectId)) staleIds.add(operation.objectId);
       }
     }
+    irreversibleStale.clear();
+    if (checkConflicts) {
+      for (const operation of plan.operations) {
+        if (!approved.has(operation.id) || !IRREVERSIBLE_OPERATIONS.has(operation.operation)) continue;
+        const detail = checkIrreversibleOp(operation, liveSnapshot);
+        if (detail) irreversibleStale.set(operation.id, detail);
+      }
+    }
     for (const guard of plan.guards ?? []) {
       const failure = evaluateGuard(liveSnapshot, guard);
       if (failure) {
@@ -232,6 +321,12 @@ export async function applyPatchPlan(
       if (operation.groupId) poisonedGroups.add(operation.groupId);
       continue;
     }
+    const irreversibleConflict = irreversibleStale.get(operation.id);
+    if (irreversibleConflict) {
+      results.push({ operationId: operation.id, status: "conflict", detail: irreversibleConflict });
+      if (operation.groupId) poisonedGroups.add(operation.groupId);
+      continue;
+    }
     if (operation.groupId && poisonedGroups.has(operation.groupId)) {
       results.push({
         operationId: operation.id,

package/src/dedupe.ts

@@ -65,6 +65,21 @@ function populatedDataFields(record: Record<string, unknown>): number {
   ).length;
 }
 
+/**
+ * The subset of a record worth keeping as a merge-recovery artifact: its id (to
+ * reference) plus every populated data field, dropping bulky/plumbing fields
+ * (raw, identities, provenance) that aren't needed to recreate it by hand.
+ */
+export function recoverableFields(record: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { id: String(record.id) };
+  for (const [field, value] of Object.entries(record)) {
+    if (NON_DATA_FIELDS.has(field)) continue;
+    if (value === undefined || value === null || value === "") continue;
+    out[field] = value;
+  }
+  return out;
+}
+
 /** True when id `a` sorts before id `b` — numeric when both ids are numeric. */
 function idBefore(a: string, b: string): boolean {
   const numericA = Number(a);
@@ -137,6 +152,12 @@ export function buildDedupePlan(
     const groupIds = members
       .map((member) => String(member.id))
       .sort((a, b) => (idBefore(a, b) ? -1 : 1));
+    // Recovery artifact: the records that will be merged away (everyone but the
+    // survivor), captured with their field values so a human can recreate one by
+    // hand if the merge was wrong. Merges are irreversible — the plan is the backup.
+    const recoverySnapshot = members
+      .filter((member) => String(member.id) !== String(survivor.id))
+      .map((member) => recoverableFields(member));
     const survivorName =
       typeof survivor.name === "string" && survivor.name
         ? survivor.name
@@ -162,8 +183,9 @@ export function buildDedupePlan(
       approvalRequired: true,
       sourceRuleOrPolicy: "dedupe",
       groupId: `grp_${options.objectType}_${String(survivor.id)}`,
+      recoverySnapshot,
       rollback:
-        "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
+        "IRREVERSIBLE: provider merges cannot be unmerged. recoverySnapshot on this operation retains every merged-away record's field values; recreate a record manually from it if a merge was wrong.",
     });
   }
 

package/src/index.ts

@@ -115,6 +115,21 @@ export {
   type MergeSuggestion,
 } from "./merge.ts";
 export { createFilePlanStore, type PlanStore, type StoredPlan } from "./planStore.ts";
+export {
+  computeApprovalDigests,
+  loadOrCreateSigningKey,
+  loadSigningKey,
+  signApproval,
+  verifyApprovalDigests,
+  type ApprovalVerification,
+} from "./integrity.ts";
+export {
+  buildAuditLog,
+  verifyAuditLog,
+  type AuditLogEntry,
+  type AuditLogExport,
+  type AuditLogVerification,
+} from "./auditLog.ts";
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
 export { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./report.ts";
 export {