fullstackgtm 0.39.0 → 0.41.0

package/dist/draft.js

@@ -0,0 +1,333 @@
+import { forcedToolCall } from "./llm.js";
+import { isGroundedSpan } from "./judge.js";
+import { normalizeAccountDomain } from "./signals.js";
+export const DRAFT_CHANNELS = ["email", "linkedin", "task"];
+// ---------------------------------------------------------------------------
+// Stable hashing (FNV-1a) — duplicated to keep this file importable without the
+// audit engine (the judge.ts/signals.ts/market.ts/enrich.ts precedent).
+function fnv1a(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/** Stable patch-operation id for a draft op (mirrors enrich's `op_enr_<hash>`). */
+export function draftOperationId(channel, accountDomain) {
+    return `op_draft_${fnv1a(`${channel}:${accountDomain}`)}`;
+}
+/** Stable evidence id for the signal a draft is grounded in. */
+export function draftEvidenceId(signalId) {
+    return `ev_draft_${fnv1a(signalId)}`;
+}
+// ---------------------------------------------------------------------------
+// Freshness / stale-trigger
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Default freshness window for the self-discard rule. A draft whose grounding
+ * signal's `firstSeen` is older than this is flagged `staleTrigger` so the human
+ * reviewer catches a manufactured-relevance opener before approving it. 14 days
+ * mirrors the judge's `FRESH_SIGNAL_DAYS`.
+ */
+export const DEFAULT_FRESHNESS_DAYS = 14;
+export function isStaleTrigger(firstSeen, now, windowDays = DEFAULT_FRESHNESS_DAYS) {
+    const seen = Date.parse(firstSeen);
+    if (!Number.isFinite(seen))
+        return true; // an undateable trigger can't be proven fresh — treat as stale
+    return now.getTime() - seen > windowDays * DAY_MS;
+}
+// ---------------------------------------------------------------------------
+// Voice rules / opener hygiene (the editable prompt's mechanically-checkable contract)
+export const DEFAULT_DRAFT_PROMPT = `You are writing ONE cold opener for a single hot account, grounded in a real, fresh trigger.
+The opener's FIRST LINE must quote the trigger back in the buyer's own words — copy a verbatim span of the why-now below into line 1. Never open with "Hi {{firstName}}" or any greeting placeholder.
+Rules (the operator owns these — edit this prompt to change them):
+- Line 1: open on the real trigger, in the buyer's words. It MUST contain a verbatim span of the why-now quote.
+- One sentence tying the trigger to ONE problem you solve. Specific, not generic.
+- End with ONE low-friction ask. No fake urgency, no "circling back".
+- No em dashes. No "Hi {{firstName}}". Keep it short — a real trigger does not need nine sentences.`;
+/**
+ * Strip em dashes (voice rule), collapse runs of whitespace WITHIN a line while
+ * preserving line breaks (line 1 grounding depends on the first line surviving
+ * intact), and trim trailing whitespace. Returns the cleaned opener.
+ */
+export function sanitizeOpener(opener) {
+    return opener
+        .replace(/—/g, "-")
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+/g, " ").trimEnd())
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+/** The first non-empty line of an opener — the line the evidence gate checks. */
+export function firstLine(opener) {
+    for (const line of opener.split("\n")) {
+        if (line.trim())
+            return line.trim();
+    }
+    return "";
+}
+/**
+ * Does the opener's first line contain a verbatim ≥12-char normalized span of the
+ * decision's whyNow? This is the self-discard gate: a draft that doesn't ground
+ * line 1 in the trigger is rejected, not saved.
+ */
+export function firstLineGroundedInTrigger(opener, whyNow) {
+    return isGroundedSpan(whyNow, firstLine(opener));
+}
+/** Reject openers that lead with a banned greeting placeholder. */
+export function hasBannedGreeting(opener) {
+    return /\bhi\s+\{\{\s*firstname\s*\}\}/i.test(opener) || /^\s*hi\s+\{\{/i.test(opener);
+}
+// ---------------------------------------------------------------------------
+// Evidence builder (evidenceFor idiom)
+/**
+ * Build a `GtmEvidence` from the signal a draft is grounded in — the trigger that
+ * justified the opener. `sourceSystem` is "web" for fetched signals (ATS boards
+ * via global fetch) and "manual" for ingested ones; `text` is the VERBATIM signal
+ * quote (the evidence anchor reused all the way from `signals fetch`).
+ */
+export function draftEvidence(signal, capturedAt) {
+    const fetched = signal.source !== "ingest";
+    return {
+        id: draftEvidenceId(signal.id),
+        sourceSystem: fetched ? "web" : "manual",
+        sourceObjectType: "signal",
+        sourceObjectId: signal.id,
+        title: `${signal.bucket} signal for ${signal.accountDomain}: ${signal.trigger}`,
+        text: signal.quote,
+        capturedAt,
+        metadata: {
+            bucket: signal.bucket,
+            trigger: signal.trigger,
+            sourceUrl: signal.sourceUrl,
+            firstSeen: signal.firstSeen,
+            signalSource: signal.source,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Opener authoring: deterministic stub + gated LLM path
+/**
+ * The no-key, honestly-degraded baseline. Emits a clearly-labeled template stub
+ * — NEVER fake authored copy. Line 1 is the verbatim whyNow (so the first-line
+ * evidence gate passes by construction), followed by the play (if any) as the
+ * "what to say" scaffold the operator fills in once they add a key.
+ */
+export function deterministicOpener(decision) {
+    const whyNow = decision.whyNow.trim();
+    const play = decision.play.trim();
+    const tail = play ? `\n→ ${play}` : "";
+    return `[[DRAFT - no LLM key]] ${whyNow}${tail}`;
+}
+export const DRAFT_SCHEMA = {
+    type: "object",
+    required: ["opener"],
+    properties: {
+        opener: {
+            type: "string",
+            description: "The full cold opener. The FIRST line MUST contain a verbatim span copied from the why-now quote. " +
+                "One problem sentence, one low-friction ask. No greeting, no 'Hi {{firstName}}', no em dashes.",
+        },
+    },
+};
+/**
+ * The LLM drafter for one account. Forced tool call with `DRAFT_SCHEMA` + the
+ * editable prompt; then the FIRST-LINE evidence gate: line 1 must contain a
+ * verbatim ≥12-char span of the decision's whyNow. Retry once with corrective
+ * feedback (the judge/market idiom), then — rather than store an ungrounded
+ * opener — fall back to the deterministic stub. The brain NEVER ships an opener
+ * whose first line isn't grounded in the trigger.
+ */
+export async function draftOpenerLlm(decision, signal, promptTemplate, llm) {
+    const model = llm.model ?? "claude-haiku-4-5";
+    const producedBy = `llm:${llm.provider}:${model}`;
+    const basePrompt = `${promptTemplate}
+
+Account: ${decision.accountDomain}
+Why now (your FIRST line must contain a verbatim span of THIS): "${decision.whyNow}"
+The trigger quote (verbatim source): "${signal.quote}"${decision.play ? `\nA play the judge suggested (do not copy verbatim): ${decision.play}` : ""}`;
+    const attempt = async (feedback) => {
+        const result = (await forcedToolCall(feedback ? `${basePrompt}\n${feedback}` : basePrompt, "draft_opener", DRAFT_SCHEMA, model, llm));
+        const opener = sanitizeOpener((result.opener ?? "").trim());
+        if (!opener)
+            return null;
+        if (hasBannedGreeting(opener))
+            return null;
+        if (!firstLineGroundedInTrigger(opener, decision.whyNow))
+            return null; // gate failed
+        return opener;
+    };
+    const first = await attempt("");
+    if (first)
+        return { opener: first, producedBy, grounded: true };
+    const retried = await attempt("\nYour previous opener's FIRST line did NOT contain a verbatim span of the why-now quote " +
+        "(or it used a banned greeting). Copy a span character-for-character from the why-now into line 1 and rewrite.");
+    if (retried)
+        return { opener: retried, producedBy, grounded: true };
+    // Both attempts ungrounded — never store an ungrounded opener. Fall back to the
+    // labeled deterministic stub (grounded by construction), but stamp the path that
+    // ran so the operator can see the model was reached and gated.
+    return { opener: deterministicOpener(decision), producedBy, grounded: false };
+}
+// ---------------------------------------------------------------------------
+// Orchestration: judge decisions → drafts → governed plan
+/**
+ * Author one opener per hot account and stage them as a `needs_approval` plan of
+ * `create_task` PatchOperations, each carrying a `GtmEvidence` (the signal quote)
+ * on `plan.evidence` and referenced via `op.evidenceIds`. Read-only: builds the
+ * plan in memory; the caller persists it via `createFilePlanStore().save(plan)`
+ * only on `--save`. NEVER sends.
+ *
+ * - Takes decisions with `decision === "send"` and `score >= minScore`.
+ * - Picks the credited signal whose quote grounds the whyNow as the trigger
+ *   anchor (the evidence the opener traces back to).
+ * - Authors the opener: LLM (gated, first-line evidence) when `llm` is provided,
+ *   else the labeled deterministic stub.
+ * - First-line evidence gate: an opener whose line 1 doesn't ground in the whyNow
+ *   is REJECTED (surfaced in `rejected`, never an op). The deterministic stub and
+ *   the LLM fallback are grounded by construction, so they always pass.
+ * - Stale-trigger: a draft whose grounding signal is older than the freshness
+ *   window gets a `staleTrigger` warning appended to the op `reason`.
+ */
+export function draft(opts) {
+    const now = opts.now ?? new Date();
+    const nowIso = now.toISOString();
+    const minScore = opts.minScore ?? 80;
+    const channel = opts.channel ?? "task";
+    const freshnessDays = opts.freshnessDays ?? DEFAULT_FRESHNESS_DAYS;
+    // `task`/`email`/`linkedin` all write a CRM task through the same gate; the
+    // object the task hangs off is the contact when known, else the account.
+    const objectType = "contact";
+    const hot = opts.decisions
+        .filter((d) => d.decision === "send" && d.score >= minScore)
+        .sort((a, b) => b.score - a.score || a.accountDomain.localeCompare(b.accountDomain));
+    const operations = [];
+    const evidence = [];
+    const drafts = [];
+    const rejected = [];
+    for (const decision of hot) {
+        const domain = normalizeAccountDomain(decision.accountDomain);
+        const signal = creditedTriggerSignal(decision, opts.signalsById);
+        if (!signal) {
+            // No credited signal quote grounds the whyNow — we cannot trace this opener
+            // to a trigger, so we cannot draft it. Surface, never emit.
+            rejected.push({
+                accountDomain: domain,
+                opener: "",
+                reason: "no credited signal quote grounds the why-now — cannot anchor an opener",
+            });
+            continue;
+        }
+        const authored = opts.openers?.get(domain);
+        const opener = authored ? authored.opener : deterministicOpener(decision);
+        const producedBy = authored ? authored.producedBy : "deterministic";
+        // First-line evidence gate — the self-discard rule. The deterministic stub and
+        // the LLM fallback are grounded by construction; an LLM opener that reached here
+        // already passed in draftOpenerLlm, but we re-check defensively (a caller could
+        // inject any opener).
+        if (!firstLineGroundedInTrigger(opener, decision.whyNow)) {
+            rejected.push({
+                accountDomain: domain,
+                opener,
+                reason: "first line does not contain a verbatim span of the why-now trigger",
+            });
+            continue;
+        }
+        const stale = isStaleTrigger(signal.firstSeen, now, freshnessDays);
+        const ev = draftEvidence(signal, nowIso);
+        evidence.push(ev);
+        const reasonBase = `Signal-grounded opener for ${domain}: "${signal.trigger}"`;
+        const reason = stale
+            ? `${reasonBase} [staleTrigger: grounding signal first seen ${signal.firstSeen}, older than ${freshnessDays}d — could this have gone out last month unchanged?]`
+            : reasonBase;
+        operations.push({
+            id: draftOperationId(channel, domain),
+            objectType,
+            objectId: domain,
+            operation: "create_task",
+            field: "follow_up_task",
+            beforeValue: null,
+            afterValue: opener.slice(0, 255),
+            reason,
+            sourceRuleOrPolicy: `draft:${channel}`,
+            riskLevel: "low",
+            approvalRequired: true,
+            rollback: "Close or delete the created task; nothing was sent.",
+            evidenceIds: [ev.id],
+        });
+        drafts.push({
+            accountDomain: domain,
+            opener,
+            decision,
+            signal,
+            producedBy,
+            staleTrigger: stale,
+        });
+    }
+    const plan = {
+        id: `draft_${fnv1a(`${channel}:${nowIso}:${operations.map((o) => o.id).join(",")}`)}`,
+        title: `Draft openers (${channel}) — ${operations.length} hot account(s)`,
+        createdAt: nowIso,
+        status: operations.length > 0 ? "needs_approval" : "draft",
+        dryRun: true,
+        summary: `${operations.length} drafted opener(s) staged as create_task proposals` +
+            `${rejected.length ? `; ${rejected.length} rejected (ungrounded first line)` : ""}. ` +
+            "A draft is a proposal — nothing is sent until plans approve -> apply.",
+        findings: [],
+        evidence,
+        operations,
+    };
+    return { plan, drafts, rejected };
+}
+/**
+ * Pick the credited signal whose quote grounds the decision's whyNow — the
+ * trigger the opener traces back to. Prefers a signal whose quote verbatim
+ * contains the whyNow span; falls back to the first resolvable credited signal so
+ * the evidence chain is never empty when a credit exists.
+ */
+export function creditedTriggerSignal(decision, signalsById) {
+    let firstResolved;
+    for (const id of decision.evidence) {
+        const signal = signalsById.get(id);
+        if (!signal)
+            continue;
+        if (!firstResolved)
+            firstResolved = signal;
+        if (isGroundedSpan(decision.whyNow, signal.quote))
+            return signal;
+    }
+    return firstResolved;
+}
+/**
+ * Author openers for the hot decisions via the LLM path (or the deterministic
+ * stub when no `llm` is provided), returning the map `draft()` consumes. Kept
+ * separate from `draft()` so the plan-assembly stays pure/synchronous and the
+ * async authoring is testable in isolation.
+ */
+export async function authorOpeners(opts) {
+    const minScore = opts.minScore ?? 80;
+    const out = new Map();
+    for (const decision of opts.decisions) {
+        if (decision.decision !== "send" || decision.score < minScore)
+            continue;
+        const domain = normalizeAccountDomain(decision.accountDomain);
+        const signal = creditedTriggerSignal(decision, opts.signalsById);
+        if (!signal)
+            continue;
+        if (opts.llm && opts.promptTemplate) {
+            const { opener, producedBy, grounded } = await draftOpenerLlm(decision, signal, opts.promptTemplate, opts.llm);
+            out.set(domain, { opener, producedBy, grounded, signalId: signal.id });
+        }
+        else {
+            out.set(domain, {
+                opener: deterministicOpener(decision),
+                producedBy: "deterministic",
+                grounded: true,
+                signalId: signal.id,
+            });
+        }
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -39,4 +39,9 @@ export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 export { registrableDomain, categoryKeywords, pickCategoryPage, extractLogoUrl, resolveFinalUrl, detectDrift, findCategoryPageInSitemap, findCategoryPage, fetchLogoDataUri, discoverCompetitors, type FetchText, type FetchBytes, type ResolveUrl, type DiscoveredVendor, type DiscoverCompetitorsOptions, } from "./marketSourcing.ts";
 export { computeMissedFirings, createFileScheduleRunStore, createFileScheduleStore, cronMatches, crontabSentinels, expectedFirings, nextCronFiring, parseCron, renderManagedBlock, replaceManagedBlock, scheduleId, scheduleRunsDir, schedulesPath, systemCrontabIo, tokenizeCommand, validateSchedulableArgv, type CronExpression, type CrontabIo, type ScheduleEntry, type ScheduleProvider, type ScheduleRunRecord, type ScheduleRunStore, type ScheduleRunTrigger, type ScheduleStore, } from "./schedule.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
+export { buildSignalsFromAts, computeWeights, createFileSignalStore, DEFAULT_SIGNALS_CONFIG, dedupKey, dedupeSignals, loadSignalsConfig, makeOutcome, normalizeAccountDomain, parseSignalsConfig, recencyFactor, SIGNAL_BUCKETS, SIGNALS_CONFIG_FILE_NAME, signalId, signalRunId, signalsDir, signalWeight, type Signal, type SignalBucket, type SignalBucketConfig, type SignalOutcome, type SignalOutcomeResult, type SignalRun, type SignalsConfig, type SignalStore, } from "./signals.ts";
+export { fetchAtsJobs, snippetFor, type AtsBoardSource, type AtsJob, } from "./connectors/atsBoards.ts";
+export { scoreBand, judgeRunId, normalizeSpan, isGroundedSpan, scoreAccount, accountRecentlyTouched, bestContactForAccount, deterministicDecision, deterministicWhyNow, JUDGE_SCHEMA, DEFAULT_JUDGE_PROMPT, judgeDecisionLlm, judgeSignals, judgeDir, createFileJudgeStore, type JudgeDecisionKind, type JudgeDecision, type JudgeRun, type JudgeBand, type AccountScore, type JudgeStore, } from "./judge.ts";
+export { draft, authorOpeners, draftOpenerLlm, deterministicOpener, creditedTriggerSignal, draftEvidence, sanitizeOpener, firstLine, firstLineGroundedInTrigger, hasBannedGreeting, isStaleTrigger, draftOperationId, draftEvidenceId, DRAFT_CHANNELS, DRAFT_SCHEMA, DEFAULT_DRAFT_PROMPT, DEFAULT_FRESHNESS_DAYS, type Draft, type RejectedDraft, type DraftResult, type DraftChannel, } from "./draft.ts";
+export { DEFAULT_GOLDEN_SET, DEFAULT_MIN_ACCURACY, HOT_SCORE, defaultJudgeFn, gradeAgainstOutcomes, gradeJudge, parseGoldenSet, type Confusion, type EvalJudgeFn, type GoldenHistory, type GoldenRow, type GradeResult, type OutcomeCalibration, } from "./judgeEval.ts";
 export type { ApprovalStatus, AuditFinding, AuditFindingSeverity, CanonicalAccount, CanonicalActivity, CanonicalContact, CanonicalDeal, CanonicalGtmSnapshot, CanonicalUser, CrmProvider, GtmAuditRule, GtmConnector, GtmEvidence, GtmEvidenceSourceSystem, GtmObjectType, GtmPolicy, GtmRuleContext, GtmRuleResult, GtmSnapshotIndex, PatchOperation, PatchOperationResult, PatchOperationType, PatchPlan, PatchPlanRun, PatchPlanRunStatus, PatchVerification, PipelineFinding, PipelineFindingStatus, PipelineFindingType, ProviderIdentity, RiskLevel, SourceFreshness, } from "./types.ts";

package/dist/index.js

@@ -39,3 +39,8 @@ export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
 export { registrableDomain, categoryKeywords, pickCategoryPage, extractLogoUrl, resolveFinalUrl, detectDrift, findCategoryPageInSitemap, findCategoryPage, fetchLogoDataUri, discoverCompetitors, } from "./marketSourcing.js";
 export { computeMissedFirings, createFileScheduleRunStore, createFileScheduleStore, cronMatches, crontabSentinels, expectedFirings, nextCronFiring, parseCron, renderManagedBlock, replaceManagedBlock, scheduleId, scheduleRunsDir, schedulesPath, systemCrontabIo, tokenizeCommand, validateSchedulableArgv, } from "./schedule.js";
 export { suggestValues } from "./suggest.js";
+export { buildSignalsFromAts, computeWeights, createFileSignalStore, DEFAULT_SIGNALS_CONFIG, dedupKey, dedupeSignals, loadSignalsConfig, makeOutcome, normalizeAccountDomain, parseSignalsConfig, recencyFactor, SIGNAL_BUCKETS, SIGNALS_CONFIG_FILE_NAME, signalId, signalRunId, signalsDir, signalWeight, } from "./signals.js";
+export { fetchAtsJobs, snippetFor, } from "./connectors/atsBoards.js";
+export { scoreBand, judgeRunId, normalizeSpan, isGroundedSpan, scoreAccount, accountRecentlyTouched, bestContactForAccount, deterministicDecision, deterministicWhyNow, JUDGE_SCHEMA, DEFAULT_JUDGE_PROMPT, judgeDecisionLlm, judgeSignals, judgeDir, createFileJudgeStore, } from "./judge.js";
+export { draft, authorOpeners, draftOpenerLlm, deterministicOpener, creditedTriggerSignal, draftEvidence, sanitizeOpener, firstLine, firstLineGroundedInTrigger, hasBannedGreeting, isStaleTrigger, draftOperationId, draftEvidenceId, DRAFT_CHANNELS, DRAFT_SCHEMA, DEFAULT_DRAFT_PROMPT, DEFAULT_FRESHNESS_DAYS, } from "./draft.js";
+export { DEFAULT_GOLDEN_SET, DEFAULT_MIN_ACCURACY, HOT_SCORE, defaultJudgeFn, gradeAgainstOutcomes, gradeJudge, parseGoldenSet, } from "./judgeEval.js";

package/dist/judge.d.ts

@@ -0,0 +1,209 @@
+import { type LlmCallOptions } from "./llm.ts";
+import { type Icp } from "./icp.ts";
+import type { Signal, SignalBucket, SignalOutcome } from "./signals.ts";
+import { computeWeights } from "./signals.ts";
+import type { CanonicalGtmSnapshot } from "./types.ts";
+/**
+ * The judge layer: turn raw signals into a short ranked list of decisions on
+ * `timing × fit × memory`. Every other layer answers "is this CRM record
+ * correct?"; the judge answers "did something change at this account this week
+ * worth reaching out *about*, to the right person, whom we haven't already
+ * chased?" — and, crucially, says **no** when the answer is no.
+ *
+ * GOVERNANCE — structural, forever: judge is read-only. It reads signals + CRM
+ * history and writes a ranked DECISION artifact to the LOCAL judge store; it
+ * emits no `PatchOperation`, opens no plan, touches no provider record. `--save`
+ * persists a `JudgeRun` and stamps the consumed signals `judgedBy`. The write
+ * side is downstream and human-gated (`draft` → `plans approve` → `apply`).
+ *
+ * EVIDENCE GATE — structural: a decision's `whyNow` must be a verbatim
+ * normalized-whitespace substring of a credited signal's stored `quote`. The
+ * deterministic baseline takes the why-now verbatim from the top signal's quote
+ * (so it is grounded by construction); the LLM path is gated after the call —
+ * an ungrounded why-now is rejected (one retry, then fall back to the
+ * deterministic why-now). The brain NEVER stores an ungrounded why-now.
+ */
+export type JudgeDecisionKind = "send" | "nurture" | "skip";
+export type JudgeDecision = {
+    accountDomain: string;
+    /** 0-100. */
+    score: number;
+    decision: JudgeDecisionKind;
+    /** MUST be a verbatim normalized-whitespace substring of a credited signal.quote. */
+    whyNow: string;
+    /** One line a rep could say (LLM), or "" (deterministic baseline). */
+    play: string;
+    /** Credited signal ids — the evidence anchors for this decision. */
+    evidence: string[];
+    skippedReason?: string;
+    /** "deterministic" | "llm:<provider>:<model>". */
+    producedBy: string;
+};
+export type JudgeRun = {
+    id: string;
+    runLabel: string;
+    /** The signal run this judgement consumed. */
+    signalRunLabel: string;
+    createdAt: string;
+    decisions: JudgeDecision[];
+};
+export type JudgeBand = "strong" | "good" | "weak" | "noise";
+export declare function scoreBand(score: number): JudgeBand;
+export declare function judgeRunId(runLabel: string): string;
+/**
+ * Whitespace/punctuation-spacing-normalized, lowercased match — the EXACT rule
+ * `call`/`market` use for verbatim evidence gates (llm.ts normalizeSpan). A
+ * local copy keeps this file importable without the LLM engine (the cross-module
+ * duplication precedent in signals.ts/market.ts).
+ */
+export declare function normalizeSpan(value: string): string;
+/** Verbatim evidence gate: `produced` must be a ≥12-char normalized substring of `source`. */
+export declare function isGroundedSpan(produced: string, source: string): boolean;
+export type AccountScore = {
+    accountDomain: string;
+    /** 0-100. */
+    score: number;
+    band: JudgeBand;
+    decision: JudgeDecisionKind;
+    /** The single highest-credited signal — the why-now anchor. */
+    topSignal: Signal;
+    /** All credited signal ids (the cluster). */
+    evidence: string[];
+    /** Raw 0..1 fit against the best-matching contact. */
+    fit: number;
+    /** Raw timing component (max bucket weight × recency [+cluster bonus]). */
+    timing: number;
+    /** True when the account was touched within the memory window (caps to nurture/skip). */
+    recentlyTouched: boolean;
+    skippedReason?: string;
+    /**
+     * Internal: every credited signal indexed by id, attached by `judgeSignals`
+     * so the LLM path can resolve quotes beyond `topSignal`. Not part of the
+     * stored artifact.
+     */
+    _signalsById?: Map<string, Signal>;
+};
+/**
+ * Score one account on timing × fit × memory and map to a 0-100 score + band +
+ * decision. Deterministic.
+ *
+ * - **timing**: each credited signal's bucket weight (learned overlay over
+ *   config defaults via `computeWeights`) × recency decay × its already-baked
+ *   repost boost; the account's timing is the MAX credited signal weight, plus a
+ *   cluster bonus when ≥2 signals are fresh (the article's compounding "fresh
+ *   round AND a live req" case → 80-100 band).
+ * - **fit**: `scoreProspectAgainstIcp(bestContact, icp)` (0..1). No ICP / no
+ *   contact → a neutral 0.5 so a strong, well-grounded timing signal can still
+ *   surface (fit then doesn't sink an otherwise-hot account).
+ * - **memory** (`recentlyTouched`): touched within `TOUCHED_WINDOW_DAYS` → never
+ *   pile on: cap the decision at `nurture` (or `skip` if already lukewarm).
+ *
+ * `decision` from the band: strong→send, good→nurture, weak/noise→skip — then
+ * the memory cap applies. `skip` is a first-class output: a lone low-intent
+ * signal (e.g. a single `social` blip) lands in `weak`/`noise` and is skipped
+ * with a reason, not mailed.
+ */
+export declare function scoreAccount(opts: {
+    accountDomain: string;
+    signals: Signal[];
+    weights: Record<SignalBucket, number>;
+    icp?: Icp;
+    bestContact?: {
+        jobTitle?: string;
+        jobLevel?: string;
+        jobDepartment?: string;
+        headline?: string;
+    };
+    recentlyTouched?: boolean;
+    now?: Date;
+}): AccountScore;
+/**
+ * Has this account been touched within `TOUCHED_WINDOW_DAYS`? Reads the snapshot:
+ * the account record's `lastActivityAt`, plus any `activities` whose `occurredAt`
+ * is recent and that link to the account (directly or via a contact at it). Pure;
+ * with no snapshot, returns false (the no-history path — caller passes `false`).
+ */
+export declare function accountRecentlyTouched(accountDomain: string, snapshot: CanonicalGtmSnapshot, now?: Date, windowDays?: number): boolean;
+/**
+ * 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.
+ */
+export declare function bestContactForAccount(accountDomain: string, snapshot: CanonicalGtmSnapshot): {
+    jobTitle?: string;
+    jobLevel?: string;
+    jobDepartment?: string;
+    headline?: string;
+} | undefined;
+/**
+ * Build a `JudgeDecision` from an `AccountScore` with the deterministic baseline:
+ * whyNow taken VERBATIM from the top credited signal's quote (grounded by
+ * construction), no `play`, producedBy "deterministic".
+ */
+export declare function deterministicDecision(score: AccountScore): JudgeDecision;
+/**
+ * A grounded why-now drawn verbatim from the signal's quote — capped to a
+ * sentence-ish span so it reads as a why-now, not the whole JD. We take the
+ * leading clause up to the first sentence boundary (or the whole quote if
+ * short), guaranteeing `isGroundedSpan(whyNow, quote)` holds.
+ */
+export declare function deterministicWhyNow(signal: Signal): string;
+export declare const JUDGE_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["decision", "whyNow", "play"];
+    readonly properties: {
+        readonly decision: {
+            readonly type: "string";
+            readonly enum: readonly ["send", "nurture", "skip"];
+        };
+        readonly whyNow: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly play: {
+            readonly type: "string";
+            readonly description: "One line a rep could say out loud, grounded in the trigger. Max 25 words. No em dashes.";
+        };
+        readonly skippedReason: {
+            readonly type: "string";
+            readonly description: "skip only: one phrase why this is not a send.";
+        };
+    };
+};
+export declare const DEFAULT_JUDGE_PROMPT = "You are a GTM judge deciding whether to reach out to an account based on fresh signals.\nScore bands (the operator owns these \u2014 edit this prompt to change them):\n- 80-100 (send): strong fit AND high intent \u2014 a live demand search, fresh funding, or >=2 clustered signals.\n- 50-79 (nurture): good fit and one solid signal, but not enough to interrupt cold.\n- 20-49 (skip): a weak or lone low-intent signal.\n- 0-19 (skip): off-ICP or noise.\nRules:\n- whyNow MUST be a verbatim span copied from one of the signal quotes below. If you cannot ground a why-now in a real quote, you cannot send.\n- play is one line a rep could say out loud, tied to the trigger. No greeting, no \"Hi {{firstName}}\". No em dashes.\n- Saying \"skip\" is a first-class, valuable answer. A judge that skips a lukewarm account is doing its job.";
+/**
+ * The LLM judge for one account. Forced tool call with `JUDGE_SCHEMA` + an
+ * editable prompt; then the verbatim-quote GATE: `whyNow` must be a normalized
+ * ≥12-char substring of one of the credited signal quotes. Retry once with
+ * corrective feedback (the market classify idiom), then fall back to the
+ * deterministic why-now — NEVER store an ungrounded why-now. The deterministic
+ * `score`/`band`/`decision`/`evidence` are authoritative; the model contributes
+ * `whyNow` (gated) and `play` only — score is not delegated to the model.
+ */
+export declare function judgeDecisionLlm(score: AccountScore, promptTemplate: string, llm: LlmCallOptions): Promise<JudgeDecision>;
+/**
+ * Judge a batch of signals: group by account, score each, and produce one
+ * decision per account (deterministic when no LLM options, gated-LLM otherwise).
+ * `--min-score` filtering and the snapshot/ICP wiring happen in the caller; this
+ * takes resolved inputs. Returns decisions sorted by score desc (the ranked list).
+ */
+export declare function judgeSignals(opts: {
+    signals: Signal[];
+    outcomes?: SignalOutcome[];
+    config: Parameters<typeof computeWeights>[0];
+    icp?: Icp;
+    snapshot?: CanonicalGtmSnapshot;
+    withHistory?: boolean;
+    promptTemplate?: string;
+    llm?: LlmCallOptions;
+    now?: Date;
+}): Promise<JudgeDecision[]>;
+export declare function judgeDir(baseDir?: string): string;
+export interface JudgeStore {
+    /** Append a new judge run; refuses an existing label (runs are append-only). */
+    appendRun(run: JudgeRun): Promise<JudgeRun>;
+    getRun(runLabel: string): Promise<JudgeRun | null>;
+    listRuns(): Promise<JudgeRun[]>;
+    latestRun(): Promise<JudgeRun | null>;
+}
+export declare function createFileJudgeStore(directory?: string): JudgeStore;