fullstackgtm 0.34.0 → 0.38.0

package/dist/enrich.js

@@ -2,16 +2,17 @@ import { mkdirSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.js";
 import { HUBSPOT_DEFAULT_FIELD_MAPPINGS } from "./mappings.js";
+import { parseAssignmentPolicy, resolveAssignment } from "./assign.js";
 export const ENRICH_CONFIG_FILE_NAME = "enrich.config.json";
 export const DEFAULT_STALE_DAYS = 90;
 const OBJECT_TYPES = ["company", "contact"];
 /** Match keys the matcher knows how to read off canonical snapshot records. */
 const MATCH_KEYS = {
     company: ["domain", "name"],
-    contact: ["email", "name"],
+    contact: ["email", "name", "linkedin"],
 };
 /** 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
  * config may use for them (so `"crm": "numberofemployees"` and
@@ -171,10 +172,113 @@ export function parseEnrichConfig(raw) {
             }
         }
     }
-    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)');
+    }
+    // Normalize + validate the assignment policy (fails loud on shape errors so a
+    // misconfigured rule never silently mis-routes a created lead).
+    if (config.acquire?.assign !== undefined) {
+        try {
+            config.acquire.assign = parseAssignmentPolicy(config.acquire.assign);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error.message : String(error));
+        }
+    }
     return config;
 }
+/**
+ * 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 = {
+    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) {
+    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) {
+    const provider = source ?? "pipe0";
+    if (provider === "linkedin" || provider === "heyreach") {
+        // LinkedIn discovery reads our OWN HeyReach lead list, so it costs $0/record
+        // (no spend budget) and keys on the LinkedIn URL — leads are sparse on email,
+        // so email-keying would drop most of them. listId is supplied via --list.
+        return {
+            sources: { linkedin: { kind: "api" } },
+            match: { contact: { keys: ["linkedin", "email"], onAmbiguous: "skip" } },
+            fields: {},
+            policy: { overwrite: "never" },
+            acquire: {
+                budget: { records: { perDay: 50, perMonth: 500 } },
+                costPerRecord: { linkedin: 0 },
+                discovery: { linkedin: { provider: "linkedin", size: 25 } },
+                create: {
+                    contact: {
+                        matchKey: "linkedin",
+                        properties: {
+                            hs_linkedin_url: "linkedin",
+                            firstname: "firstName",
+                            lastname: "lastName",
+                            jobtitle: "jobTitle",
+                            company: "companyName",
+                            email: "email",
+                        },
+                    },
+                },
+            },
+        };
+    }
+    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) {
     let raw;
     try {
@@ -323,6 +427,10 @@ function normalizeKeyValue(key, value) {
             .replace(/^www\./, "")
             .replace(/\/.*$/, "");
     }
+    if (key === "linkedin") {
+        // Match crmContactKeys' `li:` normalization (lowercased, trailing slash stripped).
+        return text.trim().replace(/\/+$/, "");
+    }
     return text.replace(/\s+/g, " ");
 }
 function crmKeyValue(objectType, record, key) {
@@ -335,6 +443,8 @@ function crmKeyValue(objectType, record, key) {
     }
     if (key === "email")
         return normalizeKeyValue("email", record.email);
+    if (key === "linkedin")
+        return normalizeKeyValue("linkedin", record.linkedin);
     if (key === "name") {
         return normalizeKeyValue("name", `${record.firstName ?? ""} ${record.lastName ?? ""}`.trim());
     }
@@ -429,7 +539,12 @@ export function buildEnrichPlan(options) {
     for (const record of records) {
         const match = config.match[record.objectType];
         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;
@@ -583,6 +698,201 @@ export function buildEnrichPlan(options) {
     };
     return { plan, counts, stamps, ambiguities, unmatchedSourceIds };
 }
+/** First non-empty value among several candidate paths in a source payload. */
+function firstSourceValue(payload, paths) {
+    for (const path of paths) {
+        const value = sourceValueAt(payload, path);
+        if (!isEmptyValue(value))
+            return String(value).trim();
+    }
+    return undefined;
+}
+/**
+ * Lift a prospect/source payload into the routing attributes a territory rule
+ * reads. Tolerant of provider spellings (explorium vs pipe0); absent attributes
+ * stay undefined, so a rule that routes on them simply won't match (falling to
+ * the policy fallback) instead of mis-routing.
+ */
+export function acquireAssignmentContext(payload, companyName, accountOwnerByName) {
+    const ctx = {};
+    const title = firstSourceValue(payload, ["jobTitle", "job_title", "title"]);
+    if (title)
+        ctx.title = title.toLowerCase();
+    const geo = firstSourceValue(payload, ["geo", "country", "company_country_code", "companyCountry"]);
+    if (geo)
+        ctx.geo = geo.toLowerCase();
+    const industry = firstSourceValue(payload, ["industry", "company_industry", "companyIndustry"]);
+    if (industry)
+        ctx.industry = industry.toLowerCase();
+    const employeeBand = firstSourceValue(payload, ["employeeBand", "company_size", "companySize"]);
+    if (employeeBand)
+        ctx.employeeBand = employeeBand;
+    const department = firstSourceValue(payload, ["department", "job_department", "jobDepartment"]);
+    if (department)
+        ctx.department = department.toLowerCase();
+    if (companyName) {
+        const owner = accountOwnerByName.get(companyName.trim().toLowerCase());
+        if (owner)
+            ctx.accountOwnerId = owner;
+    }
+    return ctx;
+}
+/**
+ * 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) {
+    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 = [];
+    const evidence = [];
+    const counts = {
+        fetched: records.length,
+        matched: 0,
+        ambiguous: 0,
+        unmatched: 0,
+        created: 0,
+        withheldByMeter: 0,
+        assigned: 0,
+        unassigned: 0,
+    };
+    let estCostUsd = 0;
+    // Assignment context (built once): the set of owner ids the CRM will accept
+    // (active users), and a company-name → account-owner lookup for the
+    // "account-owner" inherit strategy. Empty when no assign policy is set.
+    const assignPolicy = acquire.assign;
+    const knownOwnerIds = new Set();
+    const accountOwnerByName = new Map();
+    if (assignPolicy) {
+        for (const user of snapshot.users ?? []) {
+            if (user.active === false)
+                continue;
+            if (user.crmId)
+                knownOwnerIds.add(user.crmId);
+            if (user.id)
+                knownOwnerIds.add(user.id);
+        }
+        for (const account of snapshot.accounts ?? []) {
+            if (account.name && account.ownerId) {
+                accountOwnerByName.set(account.name.trim().toLowerCase(), account.ownerId);
+            }
+        }
+    }
+    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 = {};
+        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;
+        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);
+        // Resolve ownership BEFORE the meter-charged create lands, so the lead is
+        // never born ownerless. `counts.created` is the within-run index, giving
+        // round-robin deterministic, even distribution with no persisted cursor.
+        let ownerId;
+        let assignedBy;
+        if (assignPolicy) {
+            const ctx = acquireAssignmentContext(record.payload, associateCompanyName, accountOwnerByName);
+            const resolved = resolveAssignment(assignPolicy, ctx, counts.created, knownOwnerIds);
+            if (resolved.ownerId) {
+                ownerId = resolved.ownerId;
+                assignedBy = resolved.rule;
+            }
+        }
+        const payload = {
+            properties,
+            matchKey: createMap.matchKey,
+            matchValue,
+            source,
+            estCostUsd: costPerRecord,
+            associateCompanyName,
+            ...(ownerId ? { ownerId, assignedBy } : {}),
+        };
+        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],
+        });
+        if (ownerId)
+            counts.assigned += 1;
+        else
+            counts.unassigned += 1;
+        counts.created += 1;
+        estCostUsd += costPerRecord;
+    }
+    const plan = {
+        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.
 /** Latest stamp per (objectType, objectId, field) across a source's runs. */

package/dist/format.d.ts

@@ -1,3 +1,5 @@
 import type { PatchPlan, PatchPlanRun } from "./types.ts";
-export declare function patchPlanToMarkdown(plan: PatchPlan): string;
+export declare function patchPlanToMarkdown(plan: PatchPlan, opts?: {
+    summary?: boolean;
+}): string;
 export declare function formatPatchPlanRun(run: PatchPlanRun): string;

package/dist/format.js

@@ -1,4 +1,9 @@
-export function patchPlanToMarkdown(plan) {
+// `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, opts = {}) {
     const lines = [
         `# ${plan.title}`,
         "",
@@ -20,6 +25,13 @@ export function patchPlanToMarkdown(plan) {
         });
         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 ?? [];
     if (findings.length > 0) {
@@ -58,7 +70,7 @@ export function patchPlanToMarkdown(plan) {
             lines.push(`- **${operation.operation}** ${operation.objectType}/${operation.objectId}`, `  - ID: ${operation.id}`, `  - Field/action: ${operation.field ?? operation.operation}`, `  - Findings: ${formatRefs(operation.findingIds)}`, `  - Evidence refs: ${formatRefs(operation.evidenceIds)}`, `  - Before: ${formatValue(operation.beforeValue)}`, `  - After: ${formatValue(operation.afterValue)}`, `  - Reason: ${operation.reason}`, `  - Source rule/policy: ${operation.sourceRuleOrPolicy ?? "unspecified"}`, `  - Risk: ${operation.riskLevel}`, `  - Approval required: ${operation.approvalRequired ? "yes" : "no"}`, `  - Rollback: ${operation.rollback ?? "restore prior value if apply is rejected or verification fails"}`, `  - Verification: ${formatVerification(operation.verification)}`);
         }
     }
-    lines.push("", "> This prototype is dry-run only. Real CRM writes must require explicit human approval before connector adapters apply any operation.");
+    lines.push("", "> 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`;
 }
 export function formatPatchPlanRun(run) {

package/dist/health.d.ts

@@ -0,0 +1,71 @@
+import type { AuditFindingSeverity, CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
+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 declare function computeHealth(plan: PatchPlan, snapshot: CanonicalGtmSnapshot, at: string): HealthEntry;
+/** Roll a timeline up into the current state, the change since last time, and per-rule deltas. */
+export declare function summarizeHealth(entries: HealthEntry[], profile: string): HealthRollup | null;
+/** Human-readable rollup: headline score + trend, then per-rule change since last audit. */
+export declare function healthToMarkdown(rollup: HealthRollup): string;
+/** `$FSGTM_HOME[/profiles/<name>]/health.jsonl` — append-only, one entry per audit-save. */
+export declare function healthFilePath(): string;
+/** `$FSGTM_HOME[/profiles/<name>]/snapshots/` — canonical snapshots correlated by plan id. */
+export declare function snapshotsDir(): string;
+/** Append a health entry to the active profile's timeline (0600, owner-only). */
+export declare function appendHealthEntry(entry: HealthEntry): void;
+/** Read the active profile's health timeline; tolerant of partial/corrupt lines. */
+export declare function readHealthTimeline(): HealthEntry[];
+/** Persist the snapshot behind a saved audit so the timeline can diff/attribute later. */
+export declare function saveWorkspaceSnapshot(planId: string, snapshot: CanonicalGtmSnapshot): string;
+/** The active profile name, for rollup labeling. */
+export declare function activeWorkspaceProfile(): string;

package/dist/health.js

@@ -0,0 +1,172 @@
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { activeProfile, credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.js";
+/**
+ * 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 = { info: 1, warning: 3, critical: 10 };
+/**
+ * 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, snapshot, at) {
+    const byRule = {};
+    const severityCounts = { 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, profile) {
+    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([
+        ...Object.keys(current.byRule),
+        ...(previous ? Object.keys(previous.byRule) : []),
+    ]);
+    const ruleDeltas = [...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) {
+    if (delta === 0)
+        return "·";
+    return delta > 0 ? "▲" : "▼";
+}
+/** Human-readable rollup: headline score + trend, then per-rule change since last audit. */
+export function healthToMarkdown(rollup) {
+    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) {
+    return iso.slice(0, 10);
+}
+// ── Profile-scoped storage ──────────────────────────────────────────────────
+/** `$FSGTM_HOME[/profiles/<name>]/health.jsonl` — append-only, one entry per audit-save. */
+export function healthFilePath() {
+    return join(credentialsDir(), "health.jsonl");
+}
+/** `$FSGTM_HOME[/profiles/<name>]/snapshots/` — canonical snapshots correlated by plan id. */
+export function snapshotsDir() {
+    return join(credentialsDir(), "snapshots");
+}
+/** Append a health entry to the active profile's timeline (0600, owner-only). */
+export function appendHealthEntry(entry) {
+    ensureSecureHomeDir();
+    appendFileSync(healthFilePath(), `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+}
+/** Read the active profile's health timeline; tolerant of partial/corrupt lines. */
+export function readHealthTimeline() {
+    let raw;
+    try {
+        raw = readFileSync(healthFilePath(), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            entries.push(JSON.parse(trimmed));
+        }
+        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, snapshot) {
+    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() {
+    return activeProfile();
+}