fullstackgtm 0.40.0 → 0.42.0

package/dist/connectors/salesforce.js

@@ -489,6 +489,117 @@ export function createSalesforceConnector(options) {
             providerData: { id: contactId, created: true },
         };
     }
+    /**
+     * Batch create_record for contacts: bulk resolve-first (SOQL IN), then create
+     * the misses via the Composite sObject Collections API (allOrNone:false,
+     * 200/call), instead of two round-trips per lead. A record-level failure in
+     * the collection (e.g. a duplicate rule) falls back to per-record createRecord
+     * so one bad row never sinks the rest. Returns one result per input op.
+     */
+    async function applyCreateContactsBatch(operations) {
+        const byId = new Map();
+        const groups = new Map();
+        for (const op of operations) {
+            const matchKey = op.afterValue?.matchKey || "email";
+            const searchField = mappedField(mappings, "contacts", matchKey, SALESFORCE_DEFAULT_FIELD_MAPPINGS.contacts[matchKey] ?? matchKey);
+            let arr = groups.get(searchField);
+            if (!arr)
+                groups.set(searchField, (arr = []));
+            arr.push(op);
+        }
+        for (const [searchField, ops] of groups) {
+            // 1. Bulk resolve-first via SOQL IN (chunked; values SOQL-escaped).
+            const existing = new Map();
+            const uniqueValues = [
+                ...new Set(ops.map((op) => String(op.afterValue.matchValue ?? "").trim()).filter(Boolean)),
+            ];
+            for (let i = 0; i < uniqueValues.length; i += 200) {
+                const inList = uniqueValues
+                    .slice(i, i + 200)
+                    .map((v) => `'${v.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`)
+                    .join(",");
+                const rows = await query(`SELECT Id, ${searchField} FROM Contact WHERE ${searchField} IN (${inList})`);
+                for (const row of rows) {
+                    const v = row?.[searchField];
+                    if (typeof v === "string" && row.Id)
+                        existing.set(v.toLowerCase(), String(row.Id));
+                }
+            }
+            // 2. Partition: existing / already-this-run / dup-in-batch / to-create.
+            const toCreate = [];
+            const seenInBatch = new Set();
+            for (const op of ops) {
+                const payload = op.afterValue;
+                const matchKey = payload.matchKey || "email";
+                const matchValue = String(payload.matchValue ?? "").trim();
+                if (!matchValue) {
+                    byId.set(op.id, { operationId: op.id, status: "skipped", detail: "create_record needs a non-empty matchValue to resolve-first." });
+                    continue;
+                }
+                const lower = matchValue.toLowerCase();
+                const dedupeKey = `${matchKey}:${lower}`;
+                const already = createdContactsByMatch.get(dedupeKey);
+                if (already) {
+                    byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already created earlier in this run; not duplicating.`, providerData: { id: already, existing: true } });
+                    continue;
+                }
+                const existingId = existing.get(lower);
+                if (existingId) {
+                    createdContactsByMatch.set(dedupeKey, existingId);
+                    byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already exists (${existingId}); resolve-first declined to create.`, providerData: { id: existingId, existing: true } });
+                    continue;
+                }
+                if (seenInBatch.has(lower)) {
+                    byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} duplicated within this batch; not duplicating.` });
+                    continue;
+                }
+                seenInBatch.add(lower);
+                toCreate.push(op);
+            }
+            // 3. Bulk create via Composite sObject Collections (allOrNone:false →
+            //    per-record results in request order).
+            for (let i = 0; i < toCreate.length; i += 200) {
+                const chunk = toCreate.slice(i, i + 200);
+                const records = chunk.map((op) => {
+                    const payload = op.afterValue;
+                    const fields = { ...payload.properties };
+                    if (payload.ownerId) {
+                        const ownerField = mappedField(mappings, "contacts", "ownerId", SALESFORCE_DEFAULT_FIELD_MAPPINGS.contacts.ownerId ?? "OwnerId");
+                        if (!fields[ownerField])
+                            fields[ownerField] = String(payload.ownerId);
+                    }
+                    return { attributes: { type: "Contact" }, ...fields };
+                });
+                let results;
+                try {
+                    results = (await request(`/services/data/${apiVersion}/composite/sobjects`, {
+                        method: "POST",
+                        body: JSON.stringify({ allOrNone: false, records }),
+                    }));
+                }
+                catch {
+                    for (const op of chunk)
+                        byId.set(op.id, await createRecord(op));
+                    continue;
+                }
+                for (let j = 0; j < chunk.length; j++) {
+                    const op = chunk[j];
+                    const res = Array.isArray(results) ? results[j] : undefined;
+                    const payload = op.afterValue;
+                    const matchKey = payload.matchKey || "email";
+                    const matchValue = String(payload.matchValue).trim();
+                    if (res?.success && res.id) {
+                        createdContactsByMatch.set(`${matchKey}:${matchValue.toLowerCase()}`, String(res.id));
+                        byId.set(op.id, { operationId: op.id, status: "applied", detail: `Created contact ${matchKey}=${matchValue} (${res.id}).`, providerData: { id: String(res.id), created: true } });
+                    }
+                    else {
+                        byId.set(op.id, await createRecord(op)); // record-level failure → isolate per record
+                    }
+                }
+            }
+        }
+        return operations.map((op) => byId.get(op.id) ?? { operationId: op.id, status: "skipped", detail: "create_record was not processed." });
+    }
     async function applyOperation(operation) {
         try {
             switch (operation.operation) {
@@ -568,6 +679,7 @@ export function createSalesforceConnector(options) {
         fetchSnapshot,
         fetchChanges,
         applyOperation,
+        applyCreateContactsBatch,
         readField,
     };
 }

package/dist/draft.d.ts

@@ -0,0 +1,182 @@
+import { type LlmCallOptions } from "./llm.ts";
+import { type JudgeDecision } from "./judge.ts";
+import { type Signal } from "./signals.ts";
+import type { GtmEvidence, PatchPlan } from "./types.ts";
+/**
+ * The draft layer: turn a judge `send` decision into ONE trigger-grounded opener
+ * per hot account, emitted as a governed `create_task` PatchOperation so it flows
+ * through the existing `plans approve` → `apply` chain. This is the last thin
+ * piece of the brain: signals (when) → judge (who) → DRAFT (what to say) →
+ * governed apply (sent only on approval).
+ *
+ * GOVERNANCE — structural, forever: a draft is a PROPOSAL, never a send. `draft`
+ * stages a `needs_approval` PatchPlan of `create_task` ops carrying the opener
+ * text; it calls NO email/LinkedIn send API and adds none. `apply` writes the
+ * draft into the CRM (as a task for a human/downstream sender to act on); it does
+ * not transmit a message. `riskLevel: "low"` (a draft is reversible — it's text
+ * in a task) but `approvalRequired: true` ALWAYS, so a draft is never auto-applied
+ * even under a scheduled run.
+ *
+ * EVIDENCE GATE — structural: the opener's FIRST LINE must contain a verbatim
+ * normalized-whitespace span (≥12 chars) of the decision's `whyNow` (itself a
+ * verbatim span of a credited signal quote, gated by the judge). A draft whose
+ * line 1 does not ground in the trigger is REJECTED, not saved — the self-discard
+ * rule: "if the message could have gone out last month unchanged, throw it away."
+ *
+ * NO-KEY PATH — honestly degraded: without an LLM key, `draft` emits a clearly
+ * labeled template stub (`[[DRAFT - no LLM key]] ...`) rather than fake authored
+ * copy, so an operator without a key sees the structure but is never handed wooden
+ * copy passed off as a real draft.
+ */
+export type DraftChannel = "email" | "linkedin" | "task";
+export declare const DRAFT_CHANNELS: DraftChannel[];
+/** A single authored opener for one hot account, before it becomes a patch op. */
+export type Draft = {
+    accountDomain: string;
+    /** The full opener body. */
+    opener: string;
+    /** The decision this draft was authored from. */
+    decision: JudgeDecision;
+    /** The credited signal whose quote grounds the opener (the trigger anchor). */
+    signal: Signal;
+    /** "deterministic" (the labeled stub) | "llm:<provider>:<model>". */
+    producedBy: string;
+    /** True when the grounding signal is older than the freshness window. */
+    staleTrigger: boolean;
+};
+/** A draft that failed the first-line evidence gate — surfaced, never saved. */
+export type RejectedDraft = {
+    accountDomain: string;
+    opener: string;
+    reason: string;
+};
+export type DraftResult = {
+    plan: PatchPlan;
+    drafts: Draft[];
+    rejected: RejectedDraft[];
+};
+/** Stable patch-operation id for a draft op (mirrors enrich's `op_enr_<hash>`). */
+export declare function draftOperationId(channel: string, accountDomain: string): string;
+/** Stable evidence id for the signal a draft is grounded in. */
+export declare function draftEvidenceId(signalId: string): string;
+/**
+ * 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 declare const DEFAULT_FRESHNESS_DAYS = 14;
+export declare function isStaleTrigger(firstSeen: string, now: Date, windowDays?: number): boolean;
+export declare const DEFAULT_DRAFT_PROMPT = "You are writing ONE cold opener for a single hot account, grounded in a real, fresh trigger.\nThe opener's FIRST LINE must quote the trigger back in the buyer's own words \u2014 copy a verbatim span of the why-now below into line 1. Never open with \"Hi {{firstName}}\" or any greeting placeholder.\nRules (the operator owns these \u2014 edit this prompt to change them):\n- Line 1: open on the real trigger, in the buyer's words. It MUST contain a verbatim span of the why-now quote.\n- One sentence tying the trigger to ONE problem you solve. Specific, not generic.\n- End with ONE low-friction ask. No fake urgency, no \"circling back\".\n- No em dashes. No \"Hi {{firstName}}\". Keep it short \u2014 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 declare function sanitizeOpener(opener: string): string;
+/** The first non-empty line of an opener — the line the evidence gate checks. */
+export declare function firstLine(opener: string): string;
+/**
+ * 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 declare function firstLineGroundedInTrigger(opener: string, whyNow: string): boolean;
+/** Reject openers that lead with a banned greeting placeholder. */
+export declare function hasBannedGreeting(opener: string): boolean;
+/**
+ * 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 declare function draftEvidence(signal: Signal, capturedAt: string): GtmEvidence;
+/**
+ * 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 declare function deterministicOpener(decision: JudgeDecision): string;
+export declare const DRAFT_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["opener"];
+    readonly properties: {
+        readonly opener: {
+            readonly type: "string";
+            readonly description: string;
+        };
+    };
+};
+/**
+ * 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 declare function draftOpenerLlm(decision: JudgeDecision, signal: Signal, promptTemplate: string, llm: LlmCallOptions): Promise<{
+    opener: string;
+    producedBy: string;
+    grounded: boolean;
+}>;
+/**
+ * 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 declare function draft(opts: {
+    decisions: JudgeDecision[];
+    /** Credited signals by id — supplies the verbatim quote each opener grounds in. */
+    signalsById: Map<string, Signal>;
+    minScore?: number;
+    channel?: DraftChannel;
+    /** Pre-authored openers by accountDomain (the LLM path runs in the async caller). */
+    openers?: Map<string, {
+        opener: string;
+        producedBy: string;
+        grounded: boolean;
+        signalId: string;
+    }>;
+    freshnessDays?: number;
+    now?: Date;
+}): DraftResult;
+/**
+ * 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 declare function creditedTriggerSignal(decision: JudgeDecision, signalsById: Map<string, Signal>): Signal | undefined;
+/**
+ * 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 declare function authorOpeners(opts: {
+    decisions: JudgeDecision[];
+    signalsById: Map<string, Signal>;
+    minScore?: number;
+    promptTemplate?: string;
+    llm?: LlmCallOptions;
+}): Promise<Map<string, {
+    opener: string;
+    producedBy: string;
+    grounded: boolean;
+    signalId: string;
+}>>;

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";