fullstackgtm 0.42.0 → 0.44.0

package/dist/judge.js

@@ -223,22 +223,54 @@ export function accountRecentlyTouched(accountDomain, snapshot, now = new Date()
     return false;
 }
 /**
- * Find the best-matching contact for an account from the snapshot, for fit
- * scoring: the account's contacts, preferring one with a title (a title is what
- * fit scores on). Returns undefined when the account/contact isn't in snapshot.
+ * Resolve a signal's account domain to the CRM account record and the best
+ * contact at it (preferring one with a title). The single domain→account→contact
+ * join used by both fit scoring and target surfacing — so "who do I message at
+ * this account" is computed once and consistently.
  */
-export function bestContactForAccount(accountDomain, snapshot) {
+function findAccountAndBestContact(accountDomain, snapshot) {
     const domain = normalizeAccountDomain(accountDomain);
     if (!domain)
         return undefined;
     const account = (snapshot.accounts ?? []).find((a) => normalizeAccountDomain(a.domain ?? "") === domain);
     if (!account)
         return undefined;
-    const contacts = (snapshot.contacts ?? []).filter((c) => c.accountId === account.id);
-    const withTitle = contacts.find((c) => c.title) ?? contacts[0];
-    if (!withTitle)
+    // Titled contacts first (a title is what fit scores on); the first is primary.
+    const contacts = (snapshot.contacts ?? [])
+        .filter((c) => c.accountId === account.id)
+        .sort((a, b) => (b.title ? 1 : 0) - (a.title ? 1 : 0));
+    return { account, contact: contacts[0], contacts };
+}
+/**
+ * Best-matching contact for an account, shaped for fit scoring (the title is
+ * what `scoreProspectAgainstIcp` reads). Returns undefined when the
+ * account/contact isn't in the snapshot.
+ */
+export function bestContactForAccount(accountDomain, snapshot) {
+    const found = findAccountAndBestContact(accountDomain, snapshot);
+    if (!found?.contact)
         return undefined;
-    return { jobTitle: withTitle.title };
+    return { jobTitle: found.contact.title };
+}
+/** Cap on candidate contacts surfaced per account (the rest stay in the CRM). */
+const MAX_CANDIDATE_CONTACTS = 10;
+const toContactRef = (c) => ({
+    id: c.id,
+    ...(c.email ? { email: c.email } : {}),
+    ...(c.title ? { title: c.title } : {}),
+});
+export function resolveAccountTarget(accountDomain, snapshot) {
+    const found = findAccountAndBestContact(accountDomain, snapshot);
+    if (!found)
+        return {};
+    const { account, contact, contacts } = found;
+    return {
+        accountId: account.id,
+        ...(contact ? { contact: toContactRef(contact) } : {}),
+        // The candidate contacts at the account, so an agent can multi-thread
+        // beyond the single primary. Capped; primary is contacts[0].
+        ...(contacts.length ? { contacts: contacts.slice(0, MAX_CANDIDATE_CONTACTS).map(toContactRef) } : {}),
+    };
 }
 // ---------------------------------------------------------------------------
 // Deterministic baseline decision
@@ -406,8 +438,9 @@ export async function judgeSignals(opts) {
     }
     const decisions = [];
     for (const [domain, signals] of byAccount) {
+        // Memory + fit stay gated on --with-history (scoring semantics unchanged).
         const recentlyTouched = opts.withHistory && opts.snapshot ? accountRecentlyTouched(domain, opts.snapshot, now) : false;
-        const bestContact = opts.icp && opts.snapshot ? bestContactForAccount(domain, opts.snapshot) : undefined;
+        const bestContact = opts.withHistory && opts.icp && opts.snapshot ? bestContactForAccount(domain, opts.snapshot) : undefined;
         const score = scoreAccount({
             accountDomain: domain,
             signals,
@@ -422,7 +455,10 @@ export async function judgeSignals(opts) {
         const decision = opts.llm && opts.promptTemplate
             ? await judgeDecisionLlm(score, opts.promptTemplate, opts.llm)
             : deterministicDecision(score);
-        decisions.push(decision);
+        // Surface the CRM target (accountId + best contact) whenever a snapshot is
+        // present — independent of --with-history. This is what makes a decision
+        // actionable: draft writes against contact.id / accountId, never the domain.
+        decisions.push(opts.snapshot ? { ...decision, ...resolveAccountTarget(domain, opts.snapshot) } : decision);
     }
     return decisions.sort((a, b) => b.score - a.score || a.accountDomain.localeCompare(b.accountDomain));
 }

package/dist/judgeEval.d.ts

@@ -110,6 +110,13 @@ export declare function defaultJudgeFn(opts?: {
     icp?: Icp;
     now?: Date;
 }): EvalJudgeFn;
+/**
+ * The default golden set's clock. Every `firstSeen` below is relative to this
+ * instant, so grading MUST pin `now: new Date(DEFAULT_GOLDEN_NOW_ISO)` —
+ * grading against wall time lets freshness decay rot the "fresh → send" rows,
+ * and the gate starts failing on a calendar date instead of a code change.
+ */
+export declare const DEFAULT_GOLDEN_NOW_ISO = "2026-06-23T12:00:00.000Z";
 /**
  * A starter labeled set covering the four rubric corners, so `icp eval --golden
  * default` runs offline and the deterministic baseline passes it (>= the default

package/dist/judgeEval.js

@@ -85,7 +85,14 @@ export function defaultJudgeFn(opts = {}) {
 }
 // ---------------------------------------------------------------------------
 // The default golden set (ships inline so `icp eval --golden default` is free)
-const GOLD_NOW_ISO = "2026-06-23T12:00:00.000Z";
+/**
+ * The default golden set's clock. Every `firstSeen` below is relative to this
+ * instant, so grading MUST pin `now: new Date(DEFAULT_GOLDEN_NOW_ISO)` —
+ * grading against wall time lets freshness decay rot the "fresh → send" rows,
+ * and the gate starts failing on a calendar date instead of a code change.
+ */
+export const DEFAULT_GOLDEN_NOW_ISO = "2026-06-23T12:00:00.000Z";
+const GOLD_NOW_ISO = DEFAULT_GOLDEN_NOW_ISO;
 function goldSignal(over) {
     const domain = normalizeAccountDomain(over.accountDomain);
     return {

package/dist/runReport.d.ts

@@ -1,5 +1,31 @@
+/**
+ * Per-row finding for the hosted run timeline. IDs + issue type ONLY — no field
+ * values ever leave the CLI, keeping the audit's row data on the operator's side
+ * while still giving the dashboard navigable, filterable detail.
+ */
+export type RunFinding = {
+    objectType: string;
+    objectId: string;
+    severity: string;
+    ruleId: string;
+    field?: string;
+    operation?: string;
+};
+/**
+ * Where a run's findings live in the source CRM, so the dashboard can deep-link
+ * each record. `recordUrlBase` is the provider's record URL prefix; the
+ * dashboard appends the per-object path. Just an URL prefix — no record data.
+ */
+export type RunCrm = {
+    provider: string;
+    recordUrlBase: string;
+};
 /** A command annotates its headline metrics (merged). */
 export declare function reportCounts(values: Record<string, unknown>): void;
+/** A command reports per-row findings (IDs + issue type, no values). */
+export declare function reportFindings(values: RunFinding[]): void;
+/** A command reports the source CRM's record-URL base for dashboard deep-links. */
+export declare function reportCrm(value: RunCrm): void;
 /** A command annotates a structured event (plan saved, meter charged, …). */
 export declare function reportEvent(type: string, detail?: string): void;
 /**

package/dist/runReport.js

@@ -8,12 +8,25 @@
  * pure added value for users who granted it.
  */
 import { getCredential } from "./credentials.js";
+// Bound the fire-and-forget POST: a pathological audit could surface thousands
+// of findings; cap what we ship (counts still carry the true total).
+const MAX_REPORTED_FINDINGS = 2000;
 let counts;
+let findings;
+let crm;
 const events = [];
 /** A command annotates its headline metrics (merged). */
 export function reportCounts(values) {
     counts = { ...(counts ?? {}), ...values };
 }
+/** A command reports per-row findings (IDs + issue type, no values). */
+export function reportFindings(values) {
+    findings = values.slice(0, MAX_REPORTED_FINDINGS);
+}
+/** A command reports the source CRM's record-URL base for dashboard deep-links. */
+export function reportCrm(value) {
+    crm = value;
+}
 /** A command annotates a structured event (plan saved, meter charged, …). */
 export function reportEvent(type, detail) {
     events.push({ ts: Date.now(), type, detail });
@@ -54,6 +67,8 @@ export async function flushRunReport(args, status, startedAt, error) {
                 finishedAt,
                 durationMs: finishedAt - startedAt,
                 counts,
+                findings: findings?.length ? findings : undefined,
+                crm,
                 events: events.length ? events : undefined,
                 error,
             }),

package/dist/schedule.js

@@ -29,7 +29,13 @@ const SCHEDULABLE = {
     suggest: null,
     report: null,
     doctor: null,
-    enrich: ["append", "refresh"],
+    // `enrich append|refresh` fill blanks; `enrich acquire` creates net-new
+    // leads — but ONLY as a needs_approval `create_record` plan (`--save`,
+    // required below), never a write. This is what lets `tam populate` chip away
+    // at a TAM unattended: each firing queues a fresh lead plan, the meter is
+    // charged only at apply, and apply stays `apply --plan-id` (re-checked
+    // approved). So scheduled acquire accumulates proposals, never surprise leads.
+    enrich: ["append", "refresh", "acquire"],
     market: ["capture", "refresh"],
     // The GTM brain. `signals fetch` is read-only re: CRM (--save persists only
     // the local signal ledger). `icp judge`/`icp eval` are read-only/grade-only
@@ -41,9 +47,9 @@ const SCHEDULABLE = {
     icp: ["judge", "eval"],
     draft: null,
 };
-const ALLOWLIST_SUMMARY = "audit, snapshot, enrich append|refresh, market capture|refresh, signals fetch, " +
-    "icp judge|eval, draft (stages a plan), suggest, report, doctor — " +
-    "plus apply --plan-id <id> (re-checked approved at every firing)";
+const ALLOWLIST_SUMMARY = "audit, snapshot, enrich append|refresh, enrich acquire --save (stages a lead plan), " +
+    "market capture|refresh, signals fetch, icp judge|eval, draft (stages a plan), " +
+    "suggest, report, doctor — plus apply --plan-id <id> (re-checked approved at every firing)";
 /**
  * Validate that an argv resolves to a schedulable fullstackgtm command.
  * Enforced at `schedule add` time AND re-checked at `schedule run` time (the
@@ -89,6 +95,14 @@ export function validateSchedulableArgv(argv) {
                 .map((name) => `${head} ${name}`)
                 .join(", ")}.`);
         }
+        // `enrich acquire` is schedulable ONLY in its plan-producing form: without
+        // --save it's a dry-run that writes nothing AND queues nothing, so an
+        // unattended firing would silently no-op. Require --save so a scheduled
+        // acquire always leaves a needs_approval plan behind (apply stays gated).
+        if (head === "enrich" && sub === "acquire" && !argv.includes("--save")) {
+            throw new Error("Scheduled `enrich acquire` must include --save so each firing queues a needs_approval lead plan " +
+                "(without it the run produces nothing). Apply stays a separate human gate (`apply --plan-id <id>`).");
+        }
     }
 }
 /**

package/dist/signals.d.ts

@@ -53,6 +53,9 @@ export type SignalOutcome = {
     id: string;
     accountDomain: string;
     touchId?: string;
+    /** The contact the touch went to (from the judge decision), when known — so an
+     *  outcome credits the person reached, not just the account domain. */
+    contactId?: string;
     result: SignalOutcomeResult;
     recordedAt: string;
     /** Signal ids credited (from the judge decision). */
@@ -129,6 +132,41 @@ export declare function buildSignalsFromAts(rawJobs: Array<AtsJob & {
     now?: Date;
     priorSignals?: Signal[];
 }): Signal[];
+/**
+ * One staged signal row: the platform-agnostic intake shape every NON-job source
+ * produces (a source connector's output, or a `--from` JSON row). It carries the
+ * evidence anchor (`quote`) but none of the derived fields (`id`, `weight`,
+ * `source`) — `stagedRowToSignal` fills those so there is ONE place that gates
+ * evidence and stamps identity, whether the row came from a file or an API.
+ */
+export type StagedSignalRow = {
+    bucket: SignalBucket;
+    accountDomain: string;
+    trigger: string;
+    /** VERBATIM evidence — required, non-empty. */
+    quote: string;
+    sourceUrl?: string;
+    /** ISO 8601; defaults to run time when absent. */
+    firstSeen?: string;
+    /** Optional explicit weight; defaults to the bucket's configured weight. */
+    weight?: number;
+};
+/**
+ * Validate one loosely-typed staged row and turn it into a `Signal`, applying
+ * the verbatim-evidence gate (a row with no quote is rejected, never faked) and
+ * the same id/normalization logic the ATS path uses. `errorLabel` lets the
+ * caller produce a precise message ("--from f.json: row 3", "serpapi-news row 0")
+ * since both the `--from` ingest and the source-connector registry funnel here.
+ *
+ * Throws on a malformed row; returns the canonical `Signal` on success. Bucket
+ * FILTERING (skip rows outside a `--bucket` selection) stays with the caller —
+ * this function is per-row validation only.
+ */
+export declare function stagedRowToSignal(entry: Record<string, unknown>, opts: {
+    now: Date;
+    source: string;
+    errorLabel: string;
+}): Signal;
 /**
  * Split candidate signals into fresh vs. deduped against prior signals. A
  * candidate is deduped when a prior signal shares its `dedupKey`
@@ -157,6 +195,25 @@ export declare function dedupeSignals(candidates: Signal[], priorSignals: Signal
  */
 export declare function computeWeights(config: SignalsConfig, outcomes: SignalOutcome[], signalsById?: Map<string, Signal>): Record<SignalBucket, number>;
 export declare function signalsDir(baseDir?: string): string;
+/**
+ * Conventional webhook landing zone: `<signals>/spool`, profile-scoped. A
+ * webhook receiver (hosted, or the operator's own glue) appends one JSONL row
+ * per event to a `*.jsonl` file here; `signals fetch --connector file` reads the
+ * whole directory when given no explicit path. The CLI never writes here — the
+ * receiver does — so this is just the agreed-upon location, not a managed store.
+ * Per-source files (`rb2b.jsonl`, `hubspot.jsonl`, …) coexist. See
+ * docs/signal-spool-format.md.
+ */
+export declare function signalsSpoolDir(baseDir?: string): string;
+/**
+ * Conventional outbox: `<signals>/outbox`, profile-scoped — the SEND-side mirror
+ * of the spool. `apply --channel outbox` renders each APPROVED drafted opener to
+ * a `<channel>.jsonl` file here (one row per touch); a downstream sender (hosted,
+ * or the operator's own) drains it. The CLI WRITES governed, approved send
+ * intents here but TRANSMITS NOTHING — the "drafts everything, transmits nothing"
+ * invariant holds. See docs/outbox-format.md.
+ */
+export declare function signalsOutboxDir(baseDir?: string): string;
 export type SignalRun = {
     id: string;
     runLabel: string;
@@ -191,6 +248,7 @@ export declare function createFileSignalStore(directory?: string): SignalStore;
 export declare function makeOutcome(input: {
     accountDomain: string;
     touchId?: string;
+    contactId?: string;
     result: SignalOutcomeResult;
     creditedSignals?: string[];
     recordedAt?: string;

package/dist/signals.js

@@ -292,6 +292,47 @@ function withinWindow(iso, now, windowDays) {
         return false;
     return now.getTime() - t <= windowDays * DAY_MS;
 }
+/**
+ * Validate one loosely-typed staged row and turn it into a `Signal`, applying
+ * the verbatim-evidence gate (a row with no quote is rejected, never faked) and
+ * the same id/normalization logic the ATS path uses. `errorLabel` lets the
+ * caller produce a precise message ("--from f.json: row 3", "serpapi-news row 0")
+ * since both the `--from` ingest and the source-connector registry funnel here.
+ *
+ * Throws on a malformed row; returns the canonical `Signal` on success. Bucket
+ * FILTERING (skip rows outside a `--bucket` selection) stays with the caller —
+ * this function is per-row validation only.
+ */
+export function stagedRowToSignal(entry, opts) {
+    const { now, source, errorLabel } = opts;
+    const bucket = String(entry.bucket ?? "");
+    if (!SIGNAL_BUCKETS.includes(bucket)) {
+        throw new Error(`${errorLabel} has unknown bucket "${bucket}" (one of ${SIGNAL_BUCKETS.join(", ")}).`);
+    }
+    const accountDomain = normalizeAccountDomain(String(entry.accountDomain ?? entry.domain ?? ""));
+    if (!accountDomain)
+        throw new Error(`${errorLabel} is missing accountDomain.`);
+    const trigger = String(entry.trigger ?? "").trim();
+    if (!trigger)
+        throw new Error(`${errorLabel} is missing trigger.`);
+    const quote = String(entry.quote ?? "").trim();
+    if (!quote)
+        throw new Error(`${errorLabel} is missing the verbatim quote (the evidence anchor).`);
+    const base = { accountDomain, bucket: bucket, trigger };
+    const firstSeen = typeof entry.firstSeen === "string" && entry.firstSeen ? entry.firstSeen : now.toISOString();
+    return {
+        id: signalId(base),
+        accountDomain,
+        bucket: bucket,
+        trigger,
+        quote,
+        sourceUrl: String(entry.sourceUrl ?? ""),
+        firstSeen,
+        weight: typeof entry.weight === "number" ? entry.weight : DEFAULT_SIGNALS_CONFIG.buckets[bucket].weight,
+        source,
+        judgedBy: null,
+    };
+}
 // ---------------------------------------------------------------------------
 // Dedup
 /**
@@ -392,6 +433,29 @@ function blankCounts() {
 export function signalsDir(baseDir) {
     return join(baseDir ?? credentialsDir(), "signals");
 }
+/**
+ * Conventional webhook landing zone: `<signals>/spool`, profile-scoped. A
+ * webhook receiver (hosted, or the operator's own glue) appends one JSONL row
+ * per event to a `*.jsonl` file here; `signals fetch --connector file` reads the
+ * whole directory when given no explicit path. The CLI never writes here — the
+ * receiver does — so this is just the agreed-upon location, not a managed store.
+ * Per-source files (`rb2b.jsonl`, `hubspot.jsonl`, …) coexist. See
+ * docs/signal-spool-format.md.
+ */
+export function signalsSpoolDir(baseDir) {
+    return join(signalsDir(baseDir), "spool");
+}
+/**
+ * Conventional outbox: `<signals>/outbox`, profile-scoped — the SEND-side mirror
+ * of the spool. `apply --channel outbox` renders each APPROVED drafted opener to
+ * a `<channel>.jsonl` file here (one row per touch); a downstream sender (hosted,
+ * or the operator's own) drains it. The CLI WRITES governed, approved send
+ * intents here but TRANSMITS NOTHING — the "drafts everything, transmits nothing"
+ * invariant holds. See docs/outbox-format.md.
+ */
+export function signalsOutboxDir(baseDir) {
+    return join(signalsDir(baseDir), "outbox");
+}
 export function signalRunId(runLabel) {
     return `sigr_${fnv1a(runLabel)}`;
 }
@@ -508,6 +572,7 @@ export function makeOutcome(input) {
         id: outcomeId({ accountDomain, touchId: input.touchId, result: input.result, recordedAt }),
         accountDomain,
         ...(input.touchId !== undefined ? { touchId: input.touchId } : {}),
+        ...(input.contactId !== undefined ? { contactId: input.contactId } : {}),
         result: input.result,
         recordedAt,
         creditedSignals: input.creditedSignals ?? [],

package/dist/tam.d.ts

@@ -0,0 +1,225 @@
+/**
+ * `tam` — Total Addressable Market mapping.
+ *
+ * Market mapping (`market`) answers "who else is in this category and where are
+ * the open fronts." TAM mapping answers a different, longer-horizon question:
+ * "how big is the reachable market for *my* ICP, and how far along am I in
+ * actually putting it in the CRM?"
+ *
+ * It is deliberately NOT a one-shot "$10B TAM" headline. The flow is iterative:
+ *   1. `tam estimate` — derive a defensible universe from the ICP: a real
+ *      account count (a discovery provider's total-match for the ICP filter, or
+ *      an explicit assumption), × ACV for the dollar figure, with buyers/account
+ *      giving the *contact* population target. Citable cross-checks optional.
+ *   2. `tam populate` — schedule governed `enrich acquire --save` runs that chip
+ *      away at the universe (plan-only; apply stays a separate human gate).
+ *   3. `tam status` / `tam report` — coverage over time: accounts/contacts/$
+ *      in the CRM vs. the universe, what THIS campaign added since baseline, and
+ *      an ETA at the current burn rate — so "it'll take a while" is quantified.
+ *
+ * This module is the pure, deterministic core (estimation + coverage + ETA math
+ * + a profile-scoped store). The CLI wires it to the ICP, the CRM snapshot, the
+ * discovery providers, and the scheduler.
+ */
+import type { CanonicalAccount, CanonicalGtmSnapshot } from "./types.ts";
+/**
+ * ACV basis. `account` (per logo / contract — the standard TAM basis) makes
+ * TAM = accounts × ACV. `buyer` (per seat) makes TAM = contacts × ACV, for
+ * genuinely seat-priced products. Buyers/account always drives the *contact*
+ * population target regardless of basis.
+ */
+export type AcvBasis = "account" | "buyer";
+/** A citable market-research figure that cross-checks the bottom-up estimate. */
+export type TamCrossCheck = {
+    claim: string;
+    /** Parsed dollar value, when the claim is a $ figure — enables a direct compare. */
+    valueUsd?: number;
+    sourceUrl: string;
+    /** Verbatim snippet (same evidence posture as market signals). */
+    quote: string;
+    asOf?: string;
+};
+/** Real CRM counts that "fill" the TAM — accounts with a domain + their contacts. */
+export type TamCoverageCounts = {
+    accounts: number;
+    contacts: number;
+};
+export type TamUniverse = {
+    accounts: number;
+    /** Where the account count came from: "provider:explorium" or "assumption". */
+    accountsSource: string;
+    buyersPerAccount: number;
+    /** how buyersPerAccount was set: "crm:avg-contacts-per-account (N)" or "explicit" or "assumption:...". */
+    buyersSource: string;
+    /** accounts × buyersPerAccount — the contact population target. */
+    contacts: number;
+};
+/**
+ * The ICP criteria the TAM was estimated against — captured at estimate time so
+ * `status` can classify CRM accounts as in/out of THIS TAM. geo/technology aren't
+ * on a CanonicalAccount, so only `employeeBands`/`industries` are CRM-checkable;
+ * geo + technographic verification needs re-enrichment (`--reverify`, future).
+ */
+export type TamTargeting = {
+    geos?: string[];
+    employeeBands?: string[];
+    industries?: string[];
+    technologies?: string[];
+};
+export type TamModel = {
+    name: string;
+    icpName: string;
+    universe: TamUniverse;
+    /** the ICP filter this TAM was sized against (for coverage classification). */
+    targeting?: TamTargeting;
+    /** ACV must be REAL, never a fabricated default: `source` says where it came
+     *  from ("explicit" from the operator, or "crm:closed-won (N deals, median)"). */
+    acv: {
+        basis: AcvBasis;
+        valueUsd: number;
+        source: string;
+    };
+    /** accounts × ACV (account basis) or contacts × ACV (buyer basis). */
+    tamUsd: number;
+    crossChecks: TamCrossCheck[];
+    /** CRM counts at estimate time, so `status` can attribute what the campaign added. */
+    baseline: TamCoverageCounts;
+    createdAt: string;
+};
+/** CRM accounts classified against the TAM ICP — only the in-TAM bucket counts. */
+export type TamClassified = {
+    /** matches every CRM-checkable criterion (no contradiction) — counts toward coverage. */
+    inTam: number;
+    /** fails a checkable criterion (wrong size/industry) — NOT in this market. */
+    outOfTam: number;
+    /** missing the data to classify — surfaced, never silently counted. */
+    unknown: number;
+    /** all domain-bearing CRM accounts (inTam + outOfTam + unknown). */
+    totalCrm: number;
+    /** which criteria were CRM-checkable, e.g. ["size","industry"]. */
+    criteria: string[];
+};
+export type TamCoverage = {
+    at: string;
+    universe: {
+        accounts: number;
+        contacts: number;
+        tamUsd: number;
+    };
+    inCrm: TamCoverageCounts;
+    /** current − baseline (floored at 0) — what's been added since the TAM was set. */
+    addedSinceBaseline: TamCoverageCounts;
+    /** in-TAM (or total when unclassified) / universe, capped at 1. */
+    accountCoverage: number;
+    contactCoverage: number;
+    /** accountCoverage × tamUsd. */
+    dollarCovered: number;
+    /** present when the model carries targeting — the in/out/unknown breakdown. */
+    classified?: TamClassified;
+    /** max(estimate, inTam): the bottom-up count is a floor on the real universe. */
+    reconciledUniverse?: number;
+    /** inTam > the top-down estimate — the estimate was low; revise it UP. */
+    bottomUpExceedsEstimate?: boolean;
+};
+/** Linear projection of when the universe is filled, from the coverage timeline. */
+export type TamEta = {
+    /** accounts added per day, measured across the timeline window. */
+    accountsPerDay: number;
+    accountsRemaining: number;
+    daysRemaining: number;
+    /** ISO date (YYYY-MM-DD) the account universe is projected to be covered. */
+    etaDate: string;
+    /** how the rate was measured — the timeline span used. */
+    basis: string;
+};
+export type EstimateTamInput = {
+    name: string;
+    icpName: string;
+    accounts: number;
+    accountsSource: string;
+    buyersPerAccount?: number;
+    buyersSource?: string;
+    targeting?: TamTargeting;
+    acv: {
+        basis?: AcvBasis;
+        valueUsd: number;
+        source?: string;
+    };
+    crossChecks?: TamCrossCheck[];
+    baseline: TamCoverageCounts;
+    createdAt: string;
+};
+export declare function estimateTam(input: EstimateTamInput): TamModel;
+export type DerivedAcv = {
+    valueUsd: number;
+    dealCount: number;
+    meanUsd: number;
+};
+/**
+ * Derive a real ACV from the CRM's closed-won deals (median amount — robust to
+ * outliers). Returns null when there are no usable won deals, so the caller can
+ * refuse to fabricate a dollar TAM. The median is the headline; the mean is
+ * surfaced too so a skewed pipeline is visible.
+ */
+export declare function deriveAcvFromClosedWon(snapshot: CanonicalGtmSnapshot): DerivedAcv | null;
+export type DerivedBuyers = {
+    value: number;
+    accountsSampled: number;
+};
+/**
+ * Derive buyers/account from the CRM: the average number of contacts on accounts
+ * that have at least one. A real proxy for the buying group, vs. a hardcoded
+ * guess. Returns null when no account has a contact.
+ */
+export declare function deriveBuyersPerAccount(snapshot: CanonicalGtmSnapshot): DerivedBuyers | null;
+/**
+ * Count what "fills" the TAM from a CRM snapshot: accounts that carry a domain
+ * (real, signal-watchable records — a name-only stub doesn't count) and the
+ * contacts at them. Coverage is measured against these, so a TAM you've started
+ * filling reads truthfully even for accounts that pre-dated the campaign.
+ */
+export declare function coverageCountsFromSnapshot(snapshot: CanonicalGtmSnapshot): TamCoverageCounts;
+export type AccountTamClass = "in" | "out" | "unknown";
+/** The TAM criteria checkable from a CanonicalAccount — geo/technology are NOT on
+ *  the record, so they need re-enrichment and are excluded here. */
+export declare function crmCheckableCriteria(t: TamTargeting): string[];
+/**
+ * Classify one CRM account against the TAM ICP, using only CRM-checkable criteria
+ * (size, industry). "out" if any criterion contradicts (wrong size/industry);
+ * "in" if at least one passes and none contradict; "unknown" if nothing could be
+ * evaluated (missing fields, or the TAM is defined only by geo/technology). Note:
+ * geo + "uses a CRM" can't be confirmed from a CanonicalAccount, so an "in" here
+ * means "matches what the CRM lets us check" — not a full technographic match.
+ */
+export declare function classifyAccount(account: CanonicalAccount, t: TamTargeting): AccountTamClass;
+/**
+ * Coverage that classifies CRM accounts against THIS TAM's ICP — so accounts
+ * loaded from anywhere that DON'T match the target market (wrong size/industry)
+ * land in out-of-TAM/unknown and never inflate coverage. Reconciles bottom-up vs
+ * top-down: the in-TAM count is a FLOOR on the real universe (you've verified
+ * those exist), so when it exceeds the estimate, the estimate was low.
+ */
+export declare function classifyCoverage(model: TamModel, snapshot: CanonicalGtmSnapshot, at: string): TamCoverage;
+/** The covered-account count a coverage reading represents: in-TAM when
+ *  classified, else the raw CRM count (legacy). Used for ETA + reconciliation. */
+export declare function coveredAccounts(c: TamCoverage): number;
+export declare function computeCoverage(model: TamModel, inCrm: TamCoverageCounts, at: string): TamCoverage;
+/**
+ * Project when the account universe is filled, from the coverage timeline. Uses
+ * the first and last readings that show real movement. Returns null when there
+ * isn't enough signal (fewer than two readings, no elapsed time, or a flat/
+ * negative burn rate) — an honest "can't project yet" rather than a fake date.
+ */
+export declare function projectEta(model: TamModel, timeline: TamCoverage[]): TamEta | null;
+/** `$FSGTM_HOME[/profiles/<profile>]/tam/<name>/`. */
+export declare function tamDir(name: string): string;
+export declare function saveTamModel(model: TamModel): string;
+export declare function loadTamModel(name: string): TamModel | null;
+/** Append a coverage reading to the TAM's append-only timeline (0600). */
+export declare function appendCoverage(name: string, coverage: TamCoverage): void;
+/** Read the TAM's coverage timeline; tolerant of partial/corrupt lines. */
+export declare function readCoverageTimeline(name: string): TamCoverage[];
+/** A compact human summary for `tam status`. */
+export declare function coverageToText(model: TamModel, coverage: TamCoverage, eta: TamEta | null): string;
+/** A client-ready markdown deliverable for `tam report`. */
+export declare function tamReportToMarkdown(model: TamModel, timeline: TamCoverage[], eta: TamEta | null): string;