fullstackgtm 0.33.0 → 0.37.0

package/src/enrich.ts

@@ -2,8 +2,10 @@ import { mkdirSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.ts";
 import { HUBSPOT_DEFAULT_FIELD_MAPPINGS } from "./mappings.ts";
+import type { AcquireBudget } from "./acquireMeter.ts";
 import type {
   CanonicalGtmSnapshot,
+  CreateRecordPayload,
   GtmEvidence,
   PatchOperation,
   PatchPlan,
@@ -76,6 +78,42 @@ export type EnrichConfig = {
   match: Partial<Record<EnrichObjectType, EnrichMatchConfig>>;
   fields: Partial<Record<EnrichObjectType, EnrichFieldConfig[]>>;
   policy: EnrichPolicyConfig;
+  /** Net-new lead creation (`enrich acquire`). Optional; absent = acquire off. */
+  acquire?: AcquireConfig;
+};
+
+/** Maps a sourced record to the CRM properties a net-new record is created with. */
+export type AcquireCreateMap = {
+  /** CRM property name → source payload path (read via sourceValueAt). */
+  properties: Record<string, string>;
+  /** Source path whose value becomes the dedupe key (e.g. "email"). */
+  matchKey: string;
+  /** Optional source path to a company name; the connector resolves-or-creates it. */
+  associateCompanyFrom?: string;
+};
+
+/**
+ * Net-new discovery for an API acquire source. `provider` selects the adapter
+ * (explorium = prospect search; pipe0 = work-email waterfall). `filters` is the
+ * provider-native query; `resolveEmailsWith` chains a second provider to fill
+ * real emails (e.g. explorium discovers, pipe0 resolves the work email).
+ */
+export type AcquireDiscoveryConfig = {
+  provider: "explorium" | "pipe0";
+  filters?: Record<string, unknown>;
+  size?: number;
+  resolveEmailsWith?: "pipe0";
+};
+
+export type AcquireConfig = {
+  /** Windowed budget enforced by the acquire meter; absent = unmetered. */
+  budget?: AcquireBudget;
+  /** Estimated provider cost (USD) per created record, by source id. */
+  costPerRecord?: Record<string, number>;
+  /** How to build a net-new record from a sourced row, per object type. */
+  create: Partial<Record<EnrichObjectType, AcquireCreateMap>>;
+  /** Net-new discovery params for API sources, by source id. */
+  discovery?: Record<string, AcquireDiscoveryConfig>;
 };
 
 export const ENRICH_CONFIG_FILE_NAME = "enrich.config.json";
@@ -91,7 +129,7 @@ const MATCH_KEYS: Record<EnrichObjectType, string[]> = {
 };
 
 /** API source ids the MVP can pull from. */
-export const SUPPORTED_API_SOURCES = ["apollo"];
+export const SUPPORTED_API_SOURCES = ["apollo", "explorium", "pipe0"];
 
 /**
  * Canonical fields enrich may target, plus the HubSpot property spellings the
@@ -263,11 +301,80 @@ export function parseEnrichConfig(raw: string): EnrichConfig {
       }
     }
   }
-  if (!anyField) fail('"fields" maps nothing — add at least one field entry');
+  // `fields` drives append/refresh. An acquire-only config (net-new lead
+  // creation, no blank-filling) legitimately maps no fields — accept it when
+  // an acquire.create mapping is present.
+  const hasAcquireCreate = Boolean(
+    config.acquire?.create && Object.keys(config.acquire.create).length > 0,
+  );
+  if (!anyField && !hasAcquireCreate) {
+    fail('"fields" maps nothing — add at least one field entry (or an "acquire.create" mapping)');
+  }
 
   return config as EnrichConfig;
 }
 
+/**
+ * Built-in zero-config presets for well-known sources, so the common Mode-A
+ * loop — "feed a Clay export, get the dedup/routing verdict" — needs no
+ * hand-authored config. These are **match-only** (empty `fields`): the value is
+ * the matched / unmatched / ambiguous routing and collision detection, not field
+ * writes. Drop an `enrich.config.json` next to your run to map fields for actual
+ * field enrichment; an explicit config always wins over a preset. Constructed
+ * directly (not via `parseEnrichConfig`) so the match-only shape is allowed.
+ */
+export const BUILTIN_ENRICH_PRESETS: Record<string, EnrichConfig> = {
+  clay: {
+    sources: { clay: { kind: "ingest", format: "csv" } },
+    policy: { overwrite: "never", defaultStaleDays: 90 },
+    match: {
+      company: { keys: ["domain"], onAmbiguous: "skip" },
+      contact: { keys: ["email"], onAmbiguous: "skip" },
+    },
+    fields: {},
+  },
+};
+
+export function builtinEnrichPreset(source: string | undefined): EnrichConfig | undefined {
+  return source ? BUILTIN_ENRICH_PRESETS[source] : undefined;
+}
+
+/**
+ * Zero-config `enrich acquire` preset so every client gets targeted, deduped,
+ * metered lead-fill out of the box — no hand-authored enrich.config.json. The
+ * ICP (icp.json) supplies the targeting; this supplies sensible plumbing. The
+ * create mapping writes the prospect's LinkedIn URL into hs_linkedin_url, so
+ * each created contact strengthens future dedup. An explicit config always wins.
+ */
+export function builtinAcquirePreset(source: string | undefined): EnrichConfig | undefined {
+  const provider = source ?? "pipe0";
+  if (provider !== "pipe0" && provider !== "explorium") return undefined;
+  return {
+    sources: { [provider]: { kind: "api" } },
+    match: { contact: { keys: ["email"], onAmbiguous: "skip" } },
+    fields: {},
+    policy: { overwrite: "never" },
+    acquire: {
+      budget: { records: { perDay: 50, perMonth: 500 }, spend: { perDay: 25, perMonth: 250 } },
+      costPerRecord: { pipe0: 0.1, explorium: 0.4 },
+      discovery: { [provider]: { provider, size: 25 } },
+      create: {
+        contact: {
+          matchKey: "email",
+          properties: {
+            email: "email",
+            firstname: "firstName",
+            lastname: "lastName",
+            jobtitle: "jobTitle",
+            company: "companyName",
+            hs_linkedin_url: "linkedin",
+          },
+        },
+      },
+    },
+  };
+}
+
 export function loadEnrichConfig(path: string): EnrichConfig {
   let raw: string;
   try {
@@ -634,7 +741,12 @@ export function buildEnrichPlan(options: BuildEnrichPlanOptions): EnrichPlanResu
     const fields = (config.fields[record.objectType] ?? []).filter(
       (field) => field.from[source] !== undefined,
     );
-    if (!match || fields.length === 0) {
+    // Run the matcher whenever the object type has match keys; field mappings
+    // only gate whether we EMIT field ops. With no fields (a match-only config,
+    // e.g. the built-in Clay preset) this still reports the matched / ambiguous
+    // / unmatched routing verdict and records collisions — the Mode-A hygiene
+    // gate — it just proposes zero field writes.
+    if (!match) {
       counts.unmatched += 1;
       unmatchedSourceIds.push(record.id);
       continue;
@@ -798,6 +910,166 @@ export function buildEnrichPlan(options: BuildEnrichPlanOptions): EnrichPlanResu
   return { plan, counts, stamps, ambiguities, unmatchedSourceIds };
 }
 
+// ---------------------------------------------------------------------------
+// Acquire: turn sourced-but-unmatched prospects into net-new lead creates.
+
+export type AcquireCounts = {
+  fetched: number;
+  matched: number;
+  ambiguous: number;
+  unmatched: number;
+  /** create_record ops emitted. */
+  created: number;
+  /** unmatched rows that would have been created but for the meter ceiling. */
+  withheldByMeter: number;
+};
+
+export type AcquirePlanResult = {
+  plan: PatchPlan;
+  counts: AcquireCounts;
+  estCostUsd: number;
+};
+
+export type BuildAcquirePlanOptions = {
+  config: EnrichConfig;
+  source: string;
+  snapshot: CanonicalGtmSnapshot;
+  records: EnrichSourceRecord[];
+  runLabel: string;
+  /** Meter ceiling: max create ops to emit. null/undefined = unlimited. */
+  maxRecords?: number | null;
+  now?: () => Date;
+};
+
+/**
+ * Match each sourced record against the snapshot and route it: matched =
+ * already in the CRM (skip), ambiguous = a possible duplicate exists (skip —
+ * resolve-first never creates over ambiguity), unmatched = a net-new lead.
+ * Unmatched rows with a dedupe key and at least one mapped property become
+ * `create_record` operations, capped at `maxRecords` (the meter's headroom).
+ * Always a dry-run plan; nothing is written until apply.
+ */
+export function buildAcquirePlan(options: BuildAcquirePlanOptions): AcquirePlanResult {
+  const { config, source, snapshot, records, runLabel } = options;
+  const nowIso = (options.now ?? (() => new Date()))().toISOString();
+  const sourceConfig = config.sources[source];
+  if (!sourceConfig) throw new Error(`enrich: source "${source}" is not declared in the config`);
+  const acquire = config.acquire;
+  if (!acquire) throw new Error('enrich acquire: config has no "acquire" section');
+
+  const cap = options.maxRecords ?? null;
+  const costPerRecord = acquire.costPerRecord?.[source] ?? 0;
+
+  const operations: PatchOperation[] = [];
+  const evidence: GtmEvidence[] = [];
+  const counts: AcquireCounts = {
+    fetched: records.length,
+    matched: 0,
+    ambiguous: 0,
+    unmatched: 0,
+    created: 0,
+    withheldByMeter: 0,
+  };
+  let estCostUsd = 0;
+
+  for (const record of records) {
+    const createMap = acquire.create[record.objectType];
+    const match = config.match[record.objectType];
+    // No create mapping or no match config for this type — can neither create
+    // nor dedupe it safely; count as unmatched and skip.
+    if (!createMap || !match) {
+      counts.unmatched += 1;
+      continue;
+    }
+    const outcome = matchSourceRecord(snapshot, record.objectType, match.keys, record.keys);
+    if (outcome.status === "matched") {
+      counts.matched += 1;
+      continue;
+    }
+    if (outcome.status === "ambiguous") {
+      // Resolve-first: a possible duplicate exists — never create over it.
+      counts.ambiguous += 1;
+      continue;
+    }
+
+    counts.unmatched += 1;
+    const matchValue = String(record.keys[createMap.matchKey] ?? "").trim();
+    if (!matchValue) continue; // no dedupe key → refuse to create (can't resolve-first)
+
+    if (cap !== null && counts.created >= cap) {
+      counts.withheldByMeter += 1;
+      continue;
+    }
+
+    const properties: Record<string, string> = {};
+    for (const [crmProp, path] of Object.entries(createMap.properties)) {
+      const value = sourceValueAt(record.payload, path);
+      if (!isEmptyValue(value)) properties[crmProp] = String(value);
+    }
+    if (Object.keys(properties).length === 0) continue; // nothing to write
+
+    let associateCompanyName: string | undefined;
+    if (createMap.associateCompanyFrom) {
+      const companyValue = sourceValueAt(record.payload, createMap.associateCompanyFrom);
+      if (!isEmptyValue(companyValue)) associateCompanyName = String(companyValue);
+    }
+
+    const recordEvidence = evidenceFor(
+      source,
+      sourceConfig.kind,
+      sourceConfig.format,
+      record,
+      undefined,
+      nowIso,
+    );
+    evidence.push(recordEvidence);
+
+    const payload: CreateRecordPayload = {
+      properties,
+      matchKey: createMap.matchKey,
+      matchValue,
+      source,
+      estCostUsd: costPerRecord,
+      associateCompanyName,
+    };
+    operations.push({
+      id: `op_acq_${fnv1a(`${source}:${record.objectType}:${matchValue}`)}`,
+      objectType: canonicalObjectType(record.objectType),
+      objectId: `create:${matchValue}`,
+      operation: "create_record",
+      beforeValue: null,
+      afterValue: payload,
+      reason:
+        `${source} sourced net-new ${record.objectType} "${describeSourceRecord(record)}" ` +
+        `(${createMap.matchKey}=${matchValue}); no CRM match — create as a lead.`,
+      sourceRuleOrPolicy: `acquire:${source}`,
+      riskLevel: "medium",
+      approvalRequired: true,
+      rollback: "Archive the created record (it was net-new).",
+      evidenceIds: [recordEvidence.id],
+    });
+    counts.created += 1;
+    estCostUsd += costPerRecord;
+  }
+
+  const plan: PatchPlan = {
+    id: `patch_plan_acq_${fnv1a(`${source}:${runLabel}:${nowIso}`)}`,
+    title: `Acquire leads — ${source}`,
+    createdAt: nowIso,
+    status: operations.length > 0 ? "needs_approval" : "draft",
+    dryRun: true,
+    summary:
+      `${counts.created} net-new lead(s) proposed from ${source} (${counts.fetched} sourced: ` +
+      `${counts.matched} already in CRM, ${counts.ambiguous} ambiguous skipped, ${counts.unmatched} unmatched` +
+      `${counts.withheldByMeter > 0 ? `, ${counts.withheldByMeter} withheld by meter` : ""}). ` +
+      `Est. cost $${estCostUsd.toFixed(2)}.`,
+    findings: [],
+    evidence,
+    operations,
+  };
+  return { plan, counts, estCostUsd };
+}
+
 // ---------------------------------------------------------------------------
 // Staleness: compute the refresh work set from run-store stamps.
 

package/src/format.ts

@@ -1,6 +1,11 @@
 import type { PatchPlan, PatchPlanRun } from "./types.ts";
 
-export function patchPlanToMarkdown(plan: PatchPlan) {
+// `summary: true` renders only the header + the Findings-by-Rule table + an
+// operation count, for read verbs like `audit` where the full per-operation
+// dump (1,400+ lines on a real portal) buries the signal. Defaults to the full
+// view so write-preview callers (bulk-update, fix, dedupe, plans show, MCP) —
+// where you approve specific operations — keep every operation's detail.
+export function patchPlanToMarkdown(plan: PatchPlan, opts: { summary?: boolean } = {}) {
   const lines = [
     `# ${plan.title}`,
     "",
@@ -24,6 +29,19 @@ export function patchPlanToMarkdown(plan: PatchPlan) {
     lines.push("");
   }
 
+  if (opts.summary) {
+    const ops = plan.operations.length;
+    lines.push(
+      ops === 0
+        ? "No patch operations proposed."
+        : `${ops} dry-run patch operation${ops === 1 ? "" : "s"} proposed — nothing written.`,
+      "",
+      "Full plan detail: re-run with `--full`.",
+      "Client-ready report: `fullstackgtm report` (add `--format html` for a printable file).",
+    );
+    return `${lines.join("\n")}\n`;
+  }
+
   lines.push("## Findings", "");
 
   const findings = plan.pipelineFindings ?? [];
@@ -107,7 +125,7 @@ export function patchPlanToMarkdown(plan: PatchPlan) {
 
   lines.push(
     "",
-    "> This prototype is dry-run only. Real CRM writes must require explicit human approval before connector adapters apply any operation.",
+    "> Dry-run plan — read-only. No provider write happens until you approve specific operations and run `apply`; placeholder values are refused without an explicit override. These safety invariants are not beta.",
   );
   return `${lines.join("\n")}\n`;
 }

package/src/health.ts

@@ -0,0 +1,238 @@
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { activeProfile, credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.ts";
+import type { AuditFindingSeverity, CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
+
+/**
+ * The engagement workspace: a per-client health timeline that accrues from the
+ * verb people already run (`audit --save`). State lives in the profile dir
+ * (`$FSGTM_HOME[/profiles/<name>]`) alongside credentials and plans, so a
+ * consultant working `--profile <client>` builds a continuous record of one
+ * org's CRM health over time — not just episodic one-off audits.
+ *
+ * The score is DETERMINISTIC (no LLM): same plan + same snapshot → same score,
+ * so it is stable in CI and comparable run-over-run.
+ */
+
+// Severity weights: a critical finding costs ~3× a warning, ~10× an info.
+const SEVERITY_WEIGHT: Record<AuditFindingSeverity, number> = { info: 1, warning: 3, critical: 10 };
+
+export type HealthEntry = {
+  /** ISO timestamp of the audit that produced this entry. */
+  at: string;
+  /** The saved plan this entry summarizes (correlates to plans/ and snapshots/). */
+  planId: string;
+  /** Deterministic 0–100 hygiene score (higher is healthier). */
+  score: number;
+  /** Total finding count across all rules. */
+  findings: number;
+  /** Severity-weighted finding total (drives the score). */
+  weightedFindings: number;
+  /** Record counts at audit time — the denominator that normalizes the score. */
+  records: { accounts: number; contacts: number; deals: number; total: number };
+  /** Finding count per rule id. */
+  byRule: Record<string, number>;
+  /** Finding count per severity. */
+  severityCounts: Record<AuditFindingSeverity, number>;
+};
+
+export type HealthRuleDelta = {
+  ruleId: string;
+  current: number;
+  previous: number;
+  /** current − previous: positive = more findings (worse), negative = fewer (better). */
+  delta: number;
+};
+
+export type HealthRollup = {
+  profile: string;
+  auditCount: number;
+  first: string;
+  latest: string;
+  current: HealthEntry;
+  previous: HealthEntry | null;
+  /** current.score − previous.score: positive = improving. null on the first audit. */
+  scoreDelta: number | null;
+  ruleDeltas: HealthRuleDelta[];
+  history: Array<{ at: string; score: number; findings: number }>;
+};
+
+/**
+ * Deterministically score a saved audit. score = 100 / (1 + weighted findings
+ * per record): 0 findings → 100; one weighted finding per record → 50; the
+ * curve is bounded (0, 100], monotonic, and needs no clamping or magic
+ * constants. A messy 50-record CRM scores worse than the same finding count
+ * across 5,000 records, which is the point.
+ */
+export function computeHealth(plan: PatchPlan, snapshot: CanonicalGtmSnapshot, at: string): HealthEntry {
+  const byRule: Record<string, number> = {};
+  const severityCounts: Record<AuditFindingSeverity, number> = { info: 0, warning: 0, critical: 0 };
+  let weightedFindings = 0;
+  for (const finding of plan.findings) {
+    byRule[finding.ruleId] = (byRule[finding.ruleId] ?? 0) + 1;
+    severityCounts[finding.severity] += 1;
+    weightedFindings += SEVERITY_WEIGHT[finding.severity];
+  }
+
+  const records = {
+    accounts: snapshot.accounts.length,
+    contacts: snapshot.contacts.length,
+    deals: snapshot.deals.length,
+    total: snapshot.accounts.length + snapshot.contacts.length + snapshot.deals.length,
+  };
+
+  const penalty = weightedFindings / Math.max(records.total, 1);
+  const score = Math.round(100 / (1 + penalty));
+
+  return {
+    at,
+    planId: plan.id,
+    score,
+    findings: plan.findings.length,
+    weightedFindings,
+    records,
+    byRule,
+    severityCounts,
+  };
+}
+
+/** Roll a timeline up into the current state, the change since last time, and per-rule deltas. */
+export function summarizeHealth(entries: HealthEntry[], profile: string): HealthRollup | null {
+  if (entries.length === 0) return null;
+  // Oldest → newest, so `current` is the last entry.
+  const sorted = [...entries].sort((a, b) => a.at.localeCompare(b.at));
+  const current = sorted[sorted.length - 1];
+  const previous = sorted.length > 1 ? sorted[sorted.length - 2] : null;
+
+  const ruleIds = new Set<string>([
+    ...Object.keys(current.byRule),
+    ...(previous ? Object.keys(previous.byRule) : []),
+  ]);
+  const ruleDeltas: HealthRuleDelta[] = [...ruleIds]
+    .map((ruleId) => {
+      const cur = current.byRule[ruleId] ?? 0;
+      const prev = previous?.byRule[ruleId] ?? 0;
+      return { ruleId, current: cur, previous: prev, delta: cur - prev };
+    })
+    .sort((a, b) => b.current - a.current || a.ruleId.localeCompare(b.ruleId));
+
+  return {
+    profile,
+    auditCount: sorted.length,
+    first: sorted[0].at,
+    latest: current.at,
+    current,
+    previous,
+    scoreDelta: previous ? current.score - previous.score : null,
+    ruleDeltas,
+    history: sorted.map((entry) => ({ at: entry.at, score: entry.score, findings: entry.findings })),
+  };
+}
+
+// Sign-based and uniform: ▲ = the number went up, ▼ = down. The reader supplies
+// the meaning (score up = good; findings up = bad) — mixing arrow direction with
+// good/bad reads as contradictory ("▲ -3").
+function arrow(delta: number): string {
+  if (delta === 0) return "·";
+  return delta > 0 ? "▲" : "▼";
+}
+
+/** Human-readable rollup: headline score + trend, then per-rule change since last audit. */
+export function healthToMarkdown(rollup: HealthRollup): string {
+  const { current, scoreDelta } = rollup;
+  const lines = [`# GTM health — profile \`${rollup.profile}\``, ""];
+
+  const deltaText =
+    scoreDelta === null
+      ? "(first audit — no prior reading)"
+      : `${arrow(scoreDelta)} ${scoreDelta >= 0 ? "+" : ""}${scoreDelta} since the previous audit`;
+  lines.push(
+    `Score: **${current.score}/100** ${deltaText}`,
+    `Audits: ${rollup.auditCount} over ${shortDate(rollup.first)} → ${shortDate(rollup.latest)}`,
+    `Findings: ${current.findings} (${current.severityCounts.critical} critical, ${current.severityCounts.warning} warning, ${current.severityCounts.info} info)`,
+    `Records: ${current.records.accounts} accounts, ${current.records.contacts} contacts, ${current.records.deals} deals`,
+    "",
+  );
+
+  if (rollup.history.length > 1) {
+    lines.push("## Trend", "");
+    for (const point of rollup.history) {
+      const marker = point.at === rollup.latest ? "  ← latest" : "";
+      lines.push(`- ${shortDate(point.at)}  score ${point.score}  (${point.findings} findings)${marker}`);
+    }
+    lines.push("");
+  }
+
+  if (rollup.ruleDeltas.length > 0) {
+    lines.push("## By rule (Δ since previous audit)", "", "| Rule | Findings | Δ |", "| --- | --- | --- |");
+    for (const rule of rollup.ruleDeltas) {
+      const sign = rule.delta > 0 ? `+${rule.delta}` : `${rule.delta}`;
+      const cell = rule.delta === 0 ? "·" : `${arrow(rule.delta)} ${sign}`;
+      lines.push(`| ${rule.ruleId} | ${rule.current} | ${cell} |`);
+    }
+    lines.push("");
+  }
+
+  lines.push("> Score is deterministic: 100 / (1 + severity-weighted findings per record). Lower findings or more clean records ⇒ higher score.");
+  return `${lines.join("\n")}\n`;
+}
+
+function shortDate(iso: string): string {
+  return iso.slice(0, 10);
+}
+
+// ── Profile-scoped storage ──────────────────────────────────────────────────
+
+/** `$FSGTM_HOME[/profiles/<name>]/health.jsonl` — append-only, one entry per audit-save. */
+export function healthFilePath(): string {
+  return join(credentialsDir(), "health.jsonl");
+}
+
+/** `$FSGTM_HOME[/profiles/<name>]/snapshots/` — canonical snapshots correlated by plan id. */
+export function snapshotsDir(): string {
+  return join(credentialsDir(), "snapshots");
+}
+
+/** Append a health entry to the active profile's timeline (0600, owner-only). */
+export function appendHealthEntry(entry: HealthEntry): void {
+  ensureSecureHomeDir();
+  appendFileSync(healthFilePath(), `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+}
+
+/** Read the active profile's health timeline; tolerant of partial/corrupt lines. */
+export function readHealthTimeline(): HealthEntry[] {
+  let raw: string;
+  try {
+    raw = readFileSync(healthFilePath(), "utf8");
+  } catch {
+    return [];
+  }
+  const entries: HealthEntry[] = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      entries.push(JSON.parse(trimmed) as HealthEntry);
+    } catch {
+      // Skip a torn line rather than failing the whole rollup.
+    }
+  }
+  return entries;
+}
+
+/** Persist the snapshot behind a saved audit so the timeline can diff/attribute later. */
+export function saveWorkspaceSnapshot(planId: string, snapshot: CanonicalGtmSnapshot): string {
+  if (!/^[\w.-]+$/.test(planId)) throw new Error(`Invalid plan id: ${planId}`);
+  ensureSecureHomeDir();
+  const dir = snapshotsDir();
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const path = join(dir, `${planId}.json`);
+  writeSecureFile(path, `${JSON.stringify(snapshot)}\n`);
+  return path;
+}
+
+/** The active profile name, for rollup labeling. */
+export function activeWorkspaceProfile(): string {
+  return activeProfile();
+}