fullstackgtm 0.34.0 → 0.37.0

package/dist/enrich.js

@@ -11,7 +11,7 @@ const MATCH_KEYS = {
     contact: ["email", "name"],
 };
 /** 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 +171,74 @@ 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)');
+    }
     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 !== "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 {
@@ -429,7 +493,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 +652,121 @@ export function buildEnrichPlan(options) {
     };
     return { plan, counts, stamps, ambiguities, unmatchedSourceIds };
 }
+/**
+ * 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,
+    };
+    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 = {};
+        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);
+        const payload = {
+            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 = {
+        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();
+}

package/dist/icp.d.ts

@@ -0,0 +1,96 @@
+/**
+ * ICP — the Ideal Customer Profile that makes `enrich acquire` targeted instead
+ * of random. One structured artifact drives two things:
+ *   1. discovery filters — translated per provider (Explorium, pipe0/Crustdata)
+ *      so the pull only returns ICP-shaped companies + people, and
+ *   2. fit scoring — every discovered prospect is scored against the persona so
+ *      only above-threshold leads become create_record ops.
+ *
+ * Develop one via interview: an agent (Claude Code / Codex) reads INTERVIEW_SPEC,
+ * asks the questions with its AskUserQuestion tool, and writes the answers into
+ * an Icp (CLI: `icp interview` emits the spec, `icp show` renders the result).
+ *
+ * Zero runtime deps; pure functions (translation + scoring take plain data).
+ */
+export type Icp = {
+    name: string;
+    firmographics: {
+        /** human industry labels, e.g. ["software","saas"] — used for keyword/industry filters */
+        industries?: string[];
+        /** Explorium naics_category codes, e.g. ["5112"] (software publishers) */
+        naics?: string[];
+        /** provider-agnostic employee bands: "1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10001+" */
+        employeeBands?: string[];
+        /** ISO country codes, lowercased, e.g. ["us"] */
+        geos?: string[];
+    };
+    persona: {
+        /** seniority: "cxo","vp","director","manager","owner","senior" */
+        jobLevels?: string[];
+        /** "sales","marketing","operations","finance" */
+        departments?: string[];
+        /** the title phrases that DEFINE the buyer — also the scoring signal */
+        titleKeywords?: string[];
+    };
+    signals?: {
+        intentTopics?: string[];
+    };
+    scoring?: {
+        /** minimum fit (0..1) for a prospect to become a create_record op. Default 0.5. */
+        threshold?: number;
+    };
+};
+export declare const DEFAULT_FIT_THRESHOLD = 0.5;
+export declare function parseIcp(raw: string): Icp;
+/** Explorium /v1/prospects filters from the ICP. */
+export declare function icpToExploriumFilters(icp: Icp): Record<string, {
+    values?: string[];
+    value?: boolean;
+}>;
+/**
+ * pipe0 Crustdata people-search config.filters from the ICP. `current_job_titles`
+ * matches real LinkedIn title strings (case-sensitive), so keywords are Title
+ * Cased. Seniority + industry are mapped to Crustdata's controlled vocab via the
+ * tables above. NOTE: the exact pipe0→Crustdata value set could not be re-run
+ * live (pipe0 credits were exhausted) — validate when credits refill; fit
+ * scoring is the safety net for persona precision regardless.
+ */
+export declare function icpToCrustdataFilters(icp: Icp): Record<string, unknown>;
+export type IcpFit = {
+    score: number;
+    reasons: string[];
+};
+/**
+ * Score a prospect's PERSONA fit 0..1. Title-keyword match is the strongest
+ * signal (it's what defines the buyer); job level and department add to it.
+ * Firmographics aren't re-scored here — discovery already filtered on them.
+ */
+export declare function scoreProspectAgainstIcp(prospect: {
+    jobTitle?: string;
+    jobLevel?: string;
+    jobDepartment?: string;
+}, icp: Icp): IcpFit;
+export declare function fitThreshold(icp: Icp): number;
+export type IcpInterviewQuestion = {
+    id: keyof FlatIcpAnswers;
+    header: string;
+    question: string;
+    multiSelect: boolean;
+    options: {
+        label: string;
+        value: string | string[];
+        description: string;
+    }[];
+};
+/** Flattened answer keys the interview collects (assembled into an Icp). */
+export type FlatIcpAnswers = {
+    industries: string[];
+    employeeBands: string[];
+    jobLevels: string[];
+    departments: string[];
+    titleKeywords: string[];
+    geos: string[];
+};
+export declare const INTERVIEW_SPEC: IcpInterviewQuestion[];
+/** Assemble an Icp from flattened interview answers. */
+export declare function icpFromAnswers(name: string, answers: FlatIcpAnswers): Icp;