fullstackgtm 0.44.0 → 0.46.0

package/dist/connectors/signalSources.js

@@ -18,9 +18,10 @@
  *     the caller), it must never sink a multi-source run — the per-provider
  *     try/catch idiom of atsBoards/prospectSources.
  */
-import { readFileSync, readdirSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
 import { SIGNAL_BUCKETS } from "../signals.js";
+import { parseSpoolText, spoolFilesIn } from "../spoolFiles.js";
 // ---------------------------------------------------------------------------
 // file — local JSON / JSONL intake (also the webhook landing-zone reader)
 /**
@@ -59,6 +60,9 @@ export const fileSource = {
         catch {
             return []; // missing path: an empty source, not a crash
         }
+        // Container parsing lives in the shared spool reader (src/spoolFiles.ts) so
+        // `signals fetch --from`, `enrich ingest`, and `market observe --from` read
+        // the same convention; the "file source" label keeps error text unchanged.
         const files = isDir ? spoolFilesIn(abs) : [abs];
         const rows = [];
         for (const file of files) {
@@ -69,67 +73,11 @@ export const fileSource = {
             catch {
                 continue; // one unreadable file in a spool dir must not sink the rest
             }
-            const trimmed = raw.trim();
-            if (!trimmed)
-                continue;
-            const parsed = trimmed.startsWith("[") ? parseJsonArray(trimmed, file) : parseJsonl(trimmed, file);
-            rows.push(...parsed);
+            rows.push(...parseSpoolText(raw, file, "file source"));
         }
         return rows.map((row) => coerceRow(row, this.bucket));
     },
 };
-/** Spool files in a landing-zone directory: `*.jsonl` / `*.json`, name-sorted. */
-function spoolFilesIn(dir) {
-    let names;
-    try {
-        names = readdirSync(dir);
-    }
-    catch {
-        return [];
-    }
-    return names
-        .filter((name) => name.endsWith(".jsonl") || name.endsWith(".json"))
-        .sort()
-        .map((name) => join(dir, name));
-}
-function parseJsonArray(raw, path) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        throw new Error(`file source ${path}: not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
-    }
-    if (!Array.isArray(parsed))
-        throw new Error(`file source ${path}: expected a JSON array of staged signal rows.`);
-    return parsed.map((entry, index) => {
-        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-            throw new Error(`file source ${path}: row ${index} is not an object.`);
-        }
-        return entry;
-    });
-}
-function parseJsonl(raw, path) {
-    const out = [];
-    const lines = raw.split("\n");
-    lines.forEach((line, index) => {
-        const t = line.trim();
-        if (!t)
-            return;
-        let parsed;
-        try {
-            parsed = JSON.parse(t);
-        }
-        catch (error) {
-            throw new Error(`file source ${path}: line ${index} is not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
-        }
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-            throw new Error(`file source ${path}: line ${index} is not a JSON object.`);
-        }
-        out.push(parsed);
-    });
-    return out;
-}
 // ---------------------------------------------------------------------------
 // serpapi-news — funding/company signals from a news REST query (API key)
 const SERPAPI_BASE_URL = "https://serpapi.com";

package/dist/connectors/stripe.d.ts

@@ -1,10 +1,17 @@
 import type { GtmConnector } from "../types.ts";
+import { type ProgressEmitter } from "../progress.ts";
 export type StripeConnectorOptions = {
     /** Stripe secret key (sk_...) or restricted key. */
     getApiKey: () => string | Promise<string>;
     apiBaseUrl?: string;
     /** Injectable fetch for testing. */
     fetchImpl?: typeof fetch;
+    /**
+     * Shared progress vocabulary (src/progress.ts): the snapshot pull emits a
+     * `stage` per collection (customers, subscriptions) and an `items`
+     * heartbeat per page. Presentation-only — errors are swallowed.
+     */
+    progress?: ProgressEmitter;
 };
 /**
  * Read-only billing connector for Stripe — the first non-CRM connector,
@@ -25,3 +32,33 @@ export type StripeConnectorOptions = {
  *   collections are always empty.
  */
 export declare function createStripeConnector(options: StripeConnectorOptions): GtmConnector;
+/**
+ * One PAID Stripe invoice, normalized for the backfill plan builder
+ * (`backfill stripe`). Amounts are major units (Stripe returns cents);
+ * `paidAt` is the payment date (YYYY-MM-DD) from status_transitions.paid_at.
+ */
+export type StripePaidInvoice = {
+    id: string;
+    number?: string;
+    customerId?: string;
+    customerName?: string;
+    customerEmail?: string;
+    /** Lowercased domain of the customer's billing email — the CRM match key. */
+    customerDomain?: string;
+    /** Major currency units (amount_paid / 100). */
+    amountPaid: number;
+    currency?: string;
+    /** YYYY-MM-DD from status_transitions.paid_at (unix seconds). */
+    paidAt?: string;
+    description?: string;
+};
+/**
+ * Read-only pull of PAID invoices (GET /v1/invoices?status=paid with the
+ * customer expanded), the revenue source of truth the backfill plan builder
+ * turns into closed-won deal proposals. Invoices with a zero amount_paid or
+ * no id are skipped — a $0 invoice is not a won deal.
+ */
+export declare function fetchStripePaidInvoices(options: StripeConnectorOptions, opts?: {
+    sinceIso?: string;
+    onPage?: (fetched: number) => void;
+}): Promise<StripePaidInvoice[]>;

package/dist/connectors/stripe.js

@@ -1,4 +1,42 @@
+import { STRIPE_SNAPSHOT_STAGES } from "../progress.js";
 const DEFAULT_API_BASE_URL = "https://api.stripe.com";
+// Module-scope request/list (parameterized by options) so the connector
+// factory and fetchStripePaidInvoices share one implementation.
+async function stripeRequest(options, path) {
+    const baseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const apiKey = await options.getApiKey();
+    const response = await fetchImpl(`${baseUrl}${path}`, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!response.ok) {
+        // Status line only — the body can echo request details bound to a live
+        // billing key, and these errors land in scheduled-run records.
+        await response.text().catch(() => undefined);
+        throw new Error(`Stripe API error ${response.status}. Check the restricted key and request.`);
+    }
+    return response.json();
+}
+/** Stripe list pagination: follow `has_more` with `starting_after=<last id>`. */
+async function stripeList(options, path, onPage) {
+    const results = [];
+    let startingAfter;
+    do {
+        const separator = path.includes("?") ? "&" : "?";
+        const data = await stripeRequest(options, `${path}${startingAfter ? `${separator}starting_after=${encodeURIComponent(startingAfter)}` : ""}`);
+        const page = data.data ?? [];
+        results.push(...page);
+        try {
+            onPage?.(results.length);
+        }
+        catch {
+            // progress is presentation-only; never let it fail a pull
+        }
+        startingAfter =
+            data.has_more === true && page.length > 0 ? String(page.at(-1).id) : undefined;
+    } while (startingAfter);
+    return results;
+}
 /**
  * Read-only billing connector for Stripe — the first non-CRM connector,
  * proving the GtmConnector contract generalizes to billing systems.
@@ -18,40 +56,16 @@ const DEFAULT_API_BASE_URL = "https://api.stripe.com";
  *   collections are always empty.
  */
 export function createStripeConnector(options) {
-    const baseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
-    const fetchImpl = options.fetchImpl ?? fetch;
-    async function request(path) {
-        const apiKey = await options.getApiKey();
-        const response = await fetchImpl(`${baseUrl}${path}`, {
-            headers: { Authorization: `Bearer ${apiKey}` },
-        });
-        if (!response.ok) {
-            // Status line only — the body can echo request details bound to a live
-            // billing key, and these errors land in scheduled-run records.
-            await response.text().catch(() => undefined);
-            throw new Error(`Stripe API error ${response.status}. Check the restricted key and request.`);
-        }
-        return response.json();
-    }
-    /** Stripe list pagination: follow `has_more` with `starting_after=<last id>`. */
-    async function list(path) {
-        const results = [];
-        let startingAfter;
-        do {
-            const separator = path.includes("?") ? "&" : "?";
-            const data = await request(`${path}${startingAfter ? `${separator}starting_after=${encodeURIComponent(startingAfter)}` : ""}`);
-            const page = data.data ?? [];
-            results.push(...page);
-            startingAfter =
-                data.has_more === true && page.length > 0 ? String(page.at(-1).id) : undefined;
-        } while (startingAfter);
-        return results;
-    }
+    const list = (path, onPage) => stripeList(options, path, onPage);
+    // Shared progress vocabulary: stage per collection, items per page.
+    const pullStage = (stage) => options.progress?.stage(stage, STRIPE_SNAPSHOT_STAGES.indexOf(stage), STRIPE_SNAPSHOT_STAGES.length);
+    const pullItems = (fetched) => options.progress?.items(fetched);
     async function assembleSnapshot(createdGte) {
         // Stripe filters list endpoints on the integer `created` field via
         // created[gte]=<unix seconds>; omitted on a full snapshot.
         const createdFilter = createdGte === undefined ? "" : `&created[gte]=${createdGte}`;
-        const customers = await list(`/v1/customers?limit=100${createdFilter}`);
+        pullStage("customers");
+        const customers = await list(`/v1/customers?limit=100${createdFilter}`, pullItems);
         const accounts = [];
         const contacts = [];
         for (const customer of customers) {
@@ -86,7 +100,8 @@ export function createStripeConnector(options) {
                 });
             }
         }
-        const subscriptions = await list(`/v1/subscriptions?status=all&limit=100${createdFilter}`);
+        pullStage("subscriptions");
+        const subscriptions = await list(`/v1/subscriptions?status=all&limit=100${createdFilter}`, pullItems);
         const deals = subscriptions
             .filter((subscription) => subscription.id)
             .map((subscription) => {
@@ -125,6 +140,8 @@ export function createStripeConnector(options) {
                 raw: subscription,
             };
         });
+        // Deliver any throttled trailing items heartbeat before the pull returns.
+        options.progress?.flush();
         return {
             generatedAt: new Date().toISOString(),
             provider: "stripe",
@@ -165,6 +182,61 @@ export function createStripeConnector(options) {
         applyOperation,
     };
 }
+/**
+ * Read-only pull of PAID invoices (GET /v1/invoices?status=paid with the
+ * customer expanded), the revenue source of truth the backfill plan builder
+ * turns into closed-won deal proposals. Invoices with a zero amount_paid or
+ * no id are skipped — a $0 invoice is not a won deal.
+ */
+export async function fetchStripePaidInvoices(options, opts = {}) {
+    let createdFilter = "";
+    if (opts.sinceIso !== undefined) {
+        const sinceMs = Date.parse(opts.sinceIso);
+        if (!Number.isFinite(sinceMs))
+            throw new Error(`Invalid since timestamp: ${opts.sinceIso}`);
+        createdFilter = `&created[gte]=${Math.floor(sinceMs / 1000)}`;
+    }
+    const invoices = await stripeList(options, `/v1/invoices?status=paid&limit=100&expand[]=data.customer${createdFilter}`, opts.onPage);
+    const paid = [];
+    for (const invoice of invoices) {
+        if (!invoice?.id)
+            continue;
+        const amountPaidCents = numberOrUndefined(invoice.amount_paid);
+        if (amountPaidCents === undefined || amountPaidCents <= 0)
+            continue;
+        // customer is the expanded object when expand[]=data.customer was honored,
+        // else the plain id string — handle both.
+        const customer = invoice.customer;
+        const customerId = typeof customer === "string" ? customer : stringOrUndefined(customer?.id);
+        // Invoices also carry flat customer_name/customer_email copies — use them
+        // when the customer object wasn't expanded (or lacks the field).
+        const customerName = (typeof customer === "object" && customer !== null
+            ? stringOrUndefined(customer.name)
+            : undefined) ?? stringOrUndefined(invoice.customer_name);
+        const customerEmail = typeof customer === "object" && customer !== null
+            ? stringOrUndefined(customer.email) ?? stringOrUndefined(invoice.customer_email)
+            : stringOrUndefined(invoice.customer_email);
+        const customerDomain = customerEmail?.includes("@")
+            ? customerEmail.split("@").at(-1).toLowerCase()
+            : undefined;
+        const paidAtSeconds = numberOrUndefined(invoice.status_transitions?.paid_at);
+        paid.push({
+            id: String(invoice.id),
+            number: stringOrUndefined(invoice.number),
+            customerId,
+            customerName,
+            customerEmail,
+            customerDomain,
+            amountPaid: amountPaidCents / 100,
+            currency: stringOrUndefined(invoice.currency)?.toUpperCase(),
+            paidAt: paidAtSeconds !== undefined
+                ? new Date(paidAtSeconds * 1000).toISOString().split("T")[0]
+                : undefined,
+            description: stringOrUndefined(invoice.description),
+        });
+    }
+    return paid;
+}
 function stringOrUndefined(value) {
     if (value === undefined || value === null || value === "")
         return undefined;

package/dist/enrich.d.ts

@@ -1,4 +1,5 @@
 import type { AcquireBudget } from "./acquireMeter.ts";
+import type { ProgressEmitter } from "./progress.ts";
 import type { AssignmentContext, AssignmentPolicy } from "./assign.ts";
 import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
 /**
@@ -250,6 +251,12 @@ export type BuildAcquirePlanOptions = {
     /** Meter ceiling: max create ops to emit. null/undefined = unlimited. */
     maxRecords?: number | null;
     now?: () => Date;
+    /**
+     * Shared progress vocabulary (src/progress.ts): `items` over the candidate
+     * rows as they are routed, plus a `meter` reading of creates vs the meter
+     * ceiling. Presentation-only — never changes what the plan proposes.
+     */
+    progress?: ProgressEmitter;
 };
 /**
  * Lift a prospect/source payload into the routing attributes a territory rule

package/dist/enrich.js

@@ -816,7 +816,10 @@ export function buildAcquirePlan(options) {
             }
         }
     }
+    let routed = 0;
     for (const record of records) {
+        // Progress heartbeat over the candidate rows (throttled by the emitter).
+        options.progress?.items((routed += 1), records.length);
         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
@@ -923,6 +926,10 @@ export function buildAcquirePlan(options) {
         counts.created += 1;
         estCostUsd += costPerRecord;
     }
+    options.progress?.flush();
+    // Meter reading: creates proposed this run against the meter's ceiling.
+    if (cap !== null)
+        options.progress?.meter(counts.created, cap, "creates");
     const plan = {
         id: `patch_plan_acq_${fnv1a(`${source}:${runLabel}:${nowIso}`)}`,
         title: `Acquire leads — ${source}`,

package/dist/health.d.ts

@@ -1,74 +1,16 @@
-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>;
-    /**
-     * Per-object-type breakdown — so "is my contact data clean but my pipeline
-     * messy?" is answerable without re-auditing. Each type carries its own
-     * record-normalized score (same curve as the overall score, scoped to that
-     * type's records + findings).
-     */
-    byObjectType: Record<"account" | "contact" | "deal", {
-        records: number;
-        findings: number;
-        weightedFindings: number;
-        score: 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;
-    }>;
-};
+import type { CanonicalGtmSnapshot } from "./types.ts";
+import type { HealthEntry } from "./healthScore.ts";
+export { computeHealth, summarizeHealth, healthToMarkdown, type HealthEntry, type HealthRuleDelta, type HealthRollup, } from "./healthScore.ts";
 /**
- * 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.
+ * 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.
  */
-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. */

package/dist/health.js

@@ -1,6 +1,10 @@
 import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { activeProfile, credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.js";
+// Pure scoring lives in healthScore.ts (node-free, importable from V8 runtimes
+// like the hosted app's Convex queries); this module owns the fs-backed
+// profile timeline. Re-exported so existing imports keep working.
+export { computeHealth, summarizeHealth, healthToMarkdown, } from "./healthScore.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
@@ -11,140 +15,6 @@ import { activeProfile, credentialsDir, ensureSecureHomeDir, writeSecureFile } f
  * 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 };
-    const typeTally = {
-        account: { findings: 0, weightedFindings: 0 },
-        contact: { findings: 0, weightedFindings: 0 },
-        deal: { findings: 0, weightedFindings: 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 t = finding.objectType;
-        if (t === "account" || t === "contact" || t === "deal") {
-            typeTally[t].findings += 1;
-            typeTally[t].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 scoreFor = (weighted, recordCount) => Math.round(100 / (1 + weighted / Math.max(recordCount, 1)));
-    const recordsByType = { account: records.accounts, contact: records.contacts, deal: records.deals };
-    const byObjectType = ["account", "contact", "deal"].reduce((acc, t) => {
-        acc[t] = {
-            records: recordsByType[t],
-            findings: typeTally[t].findings,
-            weightedFindings: typeTally[t].weightedFindings,
-            score: scoreFor(typeTally[t].weightedFindings, recordsByType[t]),
-        };
-        return acc;
-    }, {});
-    const score = scoreFor(weightedFindings, records.total);
-    return {
-        at,
-        planId: plan.id,
-        score,
-        findings: plan.findings.length,
-        weightedFindings,
-        records,
-        byRule,
-        severityCounts,
-        byObjectType,
-    };
-}
-/** 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`, "");
-    lines.push("## By object type", "", "| Type | Score | Findings | Records |", "| --- | --- | --- | --- |");
-    for (const t of ["account", "contact", "deal"]) {
-        const b = current.byObjectType[t];
-        lines.push(`| ${t} | ${b.score}/100 | ${b.findings} | ${b.records} |`);
-    }
-    lines.push("");
-    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() {

package/dist/healthScore.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>;
+    /**
+     * Per-object-type breakdown — so "is my contact data clean but my pipeline
+     * messy?" is answerable without re-auditing. Each type carries its own
+     * record-normalized score (same curve as the overall score, scoped to that
+     * type's records + findings).
+     */
+    byObjectType: Record<"account" | "contact" | "deal", {
+        records: number;
+        findings: number;
+        weightedFindings: number;
+        score: 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;