fullstackgtm 0.18.0 → 0.20.0

package/dist/cli.js

@@ -20,10 +20,13 @@ import { sampleSnapshot } from "./sampleData.js";
 import { normalizeTranscript, parseCall, suggestCallDeal } from "./calls.js";
 import { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, loadCaptureTexts, loadMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, } from "./market.js";
 import { assessAxes, axesReportToText } from "./marketAxes.js";
+import { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, } from "./marketOverlay.js";
+import { computeScaleIndex, scaleReportToText } from "./marketScale.js";
 import { buildWorksheet, classifyMarket } from "./marketClassify.js";
 import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
 import { DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
 import { resolveRecord } from "./resolve.js";
+import { buildBulkUpdatePlan } from "./bulkUpdate.js";
 import { suggestValues } from "./suggest.js";
 function usage() {
     return `FullStackGTM — audit GTM data across providers, propose reviewable patch plans,
@@ -67,6 +70,8 @@ Usage:
   fullstackgtm market fronts [--run <label>] [--diff <prior-run>] [--json]
   fullstackgtm market axes [--run <label>] [--json]
   fullstackgtm market report [--run <label>] [--format md|html] [--out <path>]
+  fullstackgtm market overlay --snapshot <crm.json> [--calls <files>] [--save]
+  fullstackgtm market scale [--json]
   fullstackgtm market refresh [--run <label>] [--model m]
                                                the live competitive map: capture vendor pages (content-addressed),
                                                classify intensity per claim (LLM bring-your-own-key, or fill the
@@ -74,6 +79,18 @@ Usage:
                                                against the stored capture it cites before it's accepted — then
                                                compute deterministic front states and drift, render the field
                                                report. refresh = capture → classify → drift → report in one step
+  fullstackgtm bulk-update <account|contact|deal> --where <expr> [--where …] (--set <field>=<value> [--set …] | --archive | --create-task <text>) [--require <field>=<value> …] [--guard <object>:<where>[;<where>]:<none|some> …] [source options] [--save] [--json] [--out <path>]
+                                               governed generic writes: filter the snapshot
+                                               (field=value, field!=value, field~substr, field!~substr,
+                                               field:empty, field:notempty, '|' = any-of; canonical fields
+                                               like ownerId, stage, closeDate, amount; relational
+                                               pseudo-fields account.name/domain/ownerId/contactCount/
+                                               openDealStages on deals and contacts, contactCount/
+                                               openDealCount/openDealStages on accounts) into a dry-run
+                                               patch plan. The full filter is re-verified per record at
+                                               apply time (incl. mid-apply rechecks); equality filters
+                                               double as preconditions; per-record ops apply
+                                               all-or-nothing; guards assert cross-record conditions.
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
@@ -751,7 +768,9 @@ function buildCallPlan(parsed, deal, proposed, current, extraNextSteps) {
 async function marketCommand(args) {
     const [subcommand, ...rest] = args;
     const configPath = () => resolve(process.cwd(), option(rest, "--config") ?? "market.config.json");
-    if (!subcommand || subcommand === "--help") {
+    // Catch --help anywhere before loadMarketConfig/credential checks run —
+    // several subcommands (capture, refresh) have side effects on bare invocation.
+    if (!subcommand || subcommand === "--help" || subcommand === "-h" || rest.includes("--help") || rest.includes("-h")) {
         console.log(`Usage:
 market init --category <name> [--out <path>]   write a starter market.config.json
 market capture [--config <path>] [--run <label>]
@@ -760,9 +779,24 @@ market worksheet --vendor <id> [--capture-run <label>] [--out <path>]
 market observe --from <observations.json> [--unverified]
 market fronts [--config <path>] [--run <label>] [--diff <prior-run>] [--json]
 market axes [--config <path>] [--run <label>] [--json]
+market overlay --snapshot <crm.json> [--calls <parsed.json|manifest.json>]... [--prior-run <label>]
+               [--min-mentions N] [--promote-lift X] [--json] [--save --task-account <id>|--task-deal <id>]
+market scale [--config <path>] [--json]
 market report [--config <path>] [--run <label>] [--format md|html] [--out <path>]
 market refresh [--run <label>] [--model m]     capture → classify → fronts drift → HTML report
 
+overlay is the directive layer: joins the map to YOUR CRM ground truth and
+emits OCCUPY / PROMOTE / URGENT / RETREAT directives, each carrying ≥1
+observation and ≥1 CRM statistic with its sample size. Claim mentions are
+deterministic word-boundary matches of each claim's "terms" against call
+documents (call parse output); small samples refuse to become strategy
+(--min-mentions, default 3). --save turns directives into approval-gated
+create_task operations through the normal plans → approve → apply gate.
+
+scale prints the relative scale index that sizes the report's bubbles when
+vendors carry scaleSignals (citable review counts / headcount / revenue —
+a within-set index, never "market share" unqualified).
+
 axes runs the axis-discovery math: PCA over the vendor × claim intensity
 matrix (PC1 = the category's primary axis, PC2 = the max-differentiation
 direction orthogonal to it), triangulation of configured axes against the
@@ -967,7 +1001,76 @@ recomputed deterministically on every invocation — never stored.`);
         console.log(axesReportToText(report));
         return;
     }
-    throw new Error(`Unknown market subcommand: ${subcommand} (try: init, capture, classify, worksheet, observe, fronts, axes, report, refresh)`);
+    if (subcommand === "scale") {
+        const report = computeScaleIndex(config);
+        if (rest.includes("--json")) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        console.log(scaleReportToText(config, report));
+        return;
+    }
+    if (subcommand === "overlay") {
+        const set = await loadSet();
+        const snapshotPath = option(rest, "--snapshot");
+        if (!snapshotPath) {
+            throw new Error("market overlay requires --snapshot <canonical-snapshot.json> (fullstackgtm snapshot --out it first) — directives need CRM ground truth");
+        }
+        const snapshot = JSON.parse(readFileSync(resolve(process.cwd(), snapshotPath), "utf8"));
+        // --calls accepts ParsedCall JSON files (from `call parse --out`) and/or
+        // manifest arrays [{path, dealId?}] linking calls to deals. Repeatable.
+        const documents = [];
+        const addParsedCall = (parsedPath, dealId) => {
+            const parsed = JSON.parse(readFileSync(resolve(process.cwd(), parsedPath), "utf8"));
+            const text = [
+                ...(parsed.segments ?? []).map((segment) => segment.text ?? ""),
+                ...(parsed.insights ?? []).map((insight) => `${insight.text ?? ""} ${insight.evidence ?? ""}`),
+            ].join("\n");
+            documents.push({ id: parsed.id ?? parsedPath, text, dealId, occurredAt: parsed.evidence?.[0]?.capturedAt });
+        };
+        for (let i = 0; i < rest.length; i += 1) {
+            if (rest[i] !== "--calls")
+                continue;
+            const callsPath = rest[i + 1];
+            if (!callsPath)
+                throw new Error("--calls needs a path");
+            const raw = JSON.parse(readFileSync(resolve(process.cwd(), callsPath), "utf8"));
+            if (Array.isArray(raw)) {
+                for (const entry of raw)
+                    addParsedCall(entry.path, entry.dealId);
+            }
+            else {
+                addParsedCall(callsPath);
+            }
+        }
+        const priorLabel = option(rest, "--prior-run");
+        const priorSet = priorLabel ? await store.get(priorLabel) : null;
+        if (priorLabel && !priorSet)
+            throw new Error(`No observation run "${priorLabel}" for URGENT drift`);
+        const stats = computeOverlayStats(config, snapshot, documents);
+        const directives = computeDirectives(config, set, stats, {
+            minMentions: numericOption(rest, "--min-mentions") ?? undefined,
+            promoteLift: numericOption(rest, "--promote-lift") ?? undefined,
+            priorSet: priorSet ?? undefined,
+        });
+        if (rest.includes("--json")) {
+            console.log(JSON.stringify({ stats, directives }, null, 2));
+            return;
+        }
+        console.log(overlayToMarkdown(stats, directives));
+        if (rest.includes("--save")) {
+            const taskAccount = option(rest, "--task-account");
+            const taskDeal = option(rest, "--task-deal");
+            if (!taskAccount && !taskDeal) {
+                throw new Error("--save needs --task-account <id> or --task-deal <id>: directives become approval-gated create_task operations, and the CRM needs a record to hang them on (your own company's account record works well)");
+            }
+            const plan = directivesToPlan(config, set, directives, taskDeal ? { objectType: "deal", objectId: taskDeal } : { objectType: "account", objectId: taskAccount });
+            const stored = await createFilePlanStore().save(plan);
+            console.log(`Saved plan ${stored.plan.id} (${directives.length} directive task(s); approve via \`plans approve\`)`);
+        }
+        return;
+    }
+    throw new Error(`Unknown market subcommand: ${subcommand} (try: init, capture, classify, worksheet, observe, fronts, axes, overlay, scale, report, refresh)`);
 }
 /**
  * The resolve gate: exit 0 = safe to create, exit 2 = match found (exists or
@@ -1001,6 +1104,51 @@ async function resolveCommand(args) {
     if (result.verdict !== "safe_to_create")
         process.exitCode = 2;
 }
+/**
+ * Governed generic writes: build a dry-run patch plan from a snapshot filter
+ * plus field assignments (or --archive). Never writes — approve and apply the
+ * plan like any audit plan; compare-and-set protects every operation.
+ */
+async function bulkUpdateCommand(args) {
+    const [objectType, ...rest] = args;
+    if (!objectType || !["account", "contact", "deal"].includes(objectType)) {
+        throw new Error("Usage: fullstackgtm bulk-update <account|contact|deal> --where <field=value|field!=value|field~substr|field:empty|field:notempty> [--where …] (--set <field>=<value> [--set …] | --archive) [source options] [--reason <text>] [--max-operations <n>] [--save] [--out <path>] [--json]");
+    }
+    const where = repeatedOption(rest, "--where");
+    const set = {};
+    for (const pair of repeatedOption(rest, "--set")) {
+        const separator = pair.indexOf("=");
+        if (separator === -1)
+            throw new Error(`--set must look like <field>=<value>, got "${pair}"`);
+        set[pair.slice(0, separator)] = pair.slice(separator + 1);
+    }
+    const snapshot = await readSnapshot(rest);
+    const plan = buildBulkUpdatePlan(snapshot, {
+        objectType: objectType,
+        where,
+        set: Object.keys(set).length > 0 ? set : undefined,
+        archive: rest.includes("--archive"),
+        createTask: option(rest, "--create-task") ?? undefined,
+        require: repeatedOption(rest, "--require"),
+        guard: repeatedOption(rest, "--guard"),
+        reason: option(rest, "--reason") ?? undefined,
+        maxOperations: numericOption(rest, "--max-operations"),
+    });
+    const out = option(rest, "--out");
+    if (out) {
+        writeFileSync(resolve(process.cwd(), out), `${JSON.stringify(plan, null, 2)}\n`);
+    }
+    if (rest.includes("--save")) {
+        await createFilePlanStore().save(plan);
+        console.error(`Saved plan ${plan.id} (${plan.operations.length} operations). Review with \`fullstackgtm plans show ${plan.id}\`, approve with \`fullstackgtm plans approve ${plan.id} --operations <ids|all>\`, then \`fullstackgtm apply --plan-id ${plan.id} --provider <name>\`.`);
+    }
+    if (rest.includes("--json")) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else {
+        console.log(patchPlanToMarkdown(plan));
+    }
+}
 async function suggest(args) {
     const planId = option(args, "--plan-id");
     const planPath = option(args, "--plan");
@@ -1710,6 +1858,13 @@ export async function runCli(argv) {
         console.log(readPackageInfo().version);
         return;
     }
+    // Commands without bespoke help fall back to the top-level usage on --help
+    // instead of executing (audit used to silently run the sample audit).
+    // call/market/bulk-update print their own richer help.
+    if (!["call", "market", "bulk-update"].includes(command) && (args.includes("--help") || args.includes("-h"))) {
+        console.log(usage());
+        return;
+    }
     if (command === "login") {
         await login(args);
         return;
@@ -1750,6 +1905,10 @@ export async function runCli(argv) {
         await resolveCommand(args);
         return;
     }
+    if (command === "bulk-update") {
+        await bulkUpdateCommand(args);
+        return;
+    }
     if (command === "market") {
         await marketCommand(args);
         return;

package/dist/connector.d.ts

@@ -18,6 +18,12 @@ export type ApplyPatchPlanOptions = {
      * `readField`.
      */
     checkConflicts?: boolean;
+    /**
+     * For plans carrying a filter or guards: re-run the snapshot checks after
+     * the first applied write and then every N applied writes, so a record
+     * edited mid-apply is conflicted out instead of overwritten. Default 25.
+     */
+    recheckEvery?: number;
 };
 /**
  * Apply an approved subset of a patch plan through a connector.

package/dist/connector.js

@@ -23,6 +23,124 @@ export async function applyPatchPlan(connector, plan, options) {
     const results = [];
     let attempted = 0;
     let applied = 0;
+    let appliedSinceRecheck = 0;
+    // Pass 0 — snapshot-backed checks: plan-level guards and per-record
+    // filter re-verification, both against a FRESH snapshot. Cross-record
+    // eligibility ("the account still has no open contractsent deal") cannot
+    // be checked through per-operation field reads.
+    //
+    // These checks are NOT one-shot: a concurrent edit can land mid-apply,
+    // after the initial verification but before later writes (the TOCTOU
+    // window). Providers offer no compare-and-swap, so the window cannot be
+    // closed — but it can be shrunk: re-run the snapshot checks after the
+    // first write and every `recheckEvery` writes, conflicting out any
+    // operation whose record went stale mid-run.
+    const needsSnapshot = ((plan.guards && plan.guards.length > 0) || plan.filter) && connector.fetchSnapshot;
+    const recheckEvery = Math.max(1, options.recheckEvery ?? 25);
+    const staleIds = new Set();
+    let guardFailure = null;
+    const refreshSnapshotChecks = async () => {
+        if (!needsSnapshot)
+            return;
+        const { evaluateGuard, eligibleIds } = await import("./bulkUpdate.js");
+        const liveSnapshot = await connector.fetchSnapshot();
+        if (plan.filter) {
+            const stillEligible = eligibleIds(liveSnapshot, plan.filter.objectType, plan.filter.where);
+            staleIds.clear();
+            for (const operation of plan.operations) {
+                if (!stillEligible.has(operation.objectId))
+                    staleIds.add(operation.objectId);
+            }
+        }
+        for (const guard of plan.guards ?? []) {
+            const failure = evaluateGuard(liveSnapshot, guard);
+            if (failure) {
+                guardFailure = failure;
+                return;
+            }
+        }
+    };
+    await refreshSnapshotChecks();
+    if (guardFailure) {
+        for (const operation of plan.operations) {
+            results.push({
+                operationId: operation.id,
+                status: approved.has(operation.id) ? "conflict" : "skipped",
+                detail: approved.has(operation.id)
+                    ? `${guardFailure} No operation in this plan was applied — re-plan against current data.`
+                    : "Operation was not approved.",
+            });
+        }
+        return {
+            planId: plan.id,
+            provider: connector.provider,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            status: "rejected",
+            results,
+        };
+    }
+    const staleByFilter = plan.filter ? staleIds : null;
+    // Pass 1 — conflict detection. Re-read the written field (beforeValue
+    // compare-and-set) and any explicit preconditions. A conflicted operation
+    // never writes; if it carries a groupId, the whole group is poisoned so
+    // multi-record changes stay all-or-nothing.
+    const conflicts = new Map();
+    const poisonedGroups = new Set();
+    if (staleByFilter && staleByFilter.size > 0) {
+        for (const operation of plan.operations) {
+            if (!approved.has(operation.id) || !staleByFilter.has(operation.objectId))
+                continue;
+            conflicts.set(operation.id, {
+                operationId: operation.id,
+                status: "conflict",
+                detail: `Record ${operation.objectType}/${operation.objectId} no longer matches the plan's filter [${plan.filter.where.join(" AND ")}] — it changed since the plan was built. Re-plan against current data.`,
+            });
+            if (operation.groupId)
+                poisonedGroups.add(operation.groupId);
+        }
+    }
+    if (checkConflicts && connector.readField) {
+        for (const operation of plan.operations) {
+            if (!approved.has(operation.id) || conflicts.has(operation.id))
+                continue;
+            let conflict = null;
+            if (operation.field && FIELD_WRITE_OPERATIONS.has(operation.operation)) {
+                const current = await connector.readField(operation.objectType, operation.objectId, operation.field);
+                const expected = normalizeForComparison(operation.beforeValue);
+                const found = normalizeForComparison(current);
+                if (expected !== found) {
+                    conflict = {
+                        operationId: operation.id,
+                        status: "conflict",
+                        detail: `Value drifted since the plan was proposed: expected ${expected ?? "∅"}, found ${found ?? "∅"}. Re-run the audit.`,
+                        providerData: { currentValue: current ?? null },
+                    };
+                }
+            }
+            if (!conflict && operation.preconditions) {
+                for (const precondition of operation.preconditions) {
+                    const current = await connector.readField(operation.objectType, operation.objectId, precondition.field);
+                    const expected = normalizeForComparison(precondition.expectedValue);
+                    const found = normalizeForComparison(current);
+                    if (expected !== found) {
+                        conflict = {
+                            operationId: operation.id,
+                            status: "conflict",
+                            detail: `Precondition failed: ${precondition.field} was ${expected ?? "∅"} when the plan was built, found ${found ?? "∅"} now. The record changed — re-plan before writing.`,
+                            providerData: { preconditionField: precondition.field, currentValue: current ?? null },
+                        };
+                        break;
+                    }
+                }
+            }
+            if (conflict) {
+                conflicts.set(operation.id, conflict);
+                if (operation.groupId)
+                    poisonedGroups.add(operation.groupId);
+            }
+        }
+    }
     for (const operation of plan.operations) {
         if (!approved.has(operation.id)) {
             results.push({
@@ -41,30 +159,53 @@ export async function applyPatchPlan(connector, plan, options) {
             });
             continue;
         }
-        if (checkConflicts &&
-            connector.readField &&
-            operation.field &&
-            FIELD_WRITE_OPERATIONS.has(operation.operation)) {
-            const current = await connector.readField(operation.objectType, operation.objectId, operation.field);
-            const expected = normalizeForComparison(operation.beforeValue);
-            const found = normalizeForComparison(current);
-            if (expected !== found) {
-                results.push({
-                    operationId: operation.id,
-                    status: "conflict",
-                    detail: `Value drifted since the plan was proposed: expected ${expected ?? "∅"}, found ${found ?? "∅"}. Re-run the audit.`,
-                    providerData: { currentValue: current ?? null },
-                });
-                continue;
-            }
+        if (guardFailure) {
+            results.push({
+                operationId: operation.id,
+                status: "conflict",
+                detail: `${guardFailure} Detected mid-apply — this and all remaining operations were not applied.`,
+            });
+            continue;
+        }
+        const conflict = conflicts.get(operation.id);
+        if (conflict) {
+            results.push(conflict);
+            continue;
+        }
+        if (staleByFilter && staleByFilter.has(operation.objectId)) {
+            results.push({
+                operationId: operation.id,
+                status: "conflict",
+                detail: `Record ${operation.objectType}/${operation.objectId} no longer matches the plan's filter [${plan.filter.where.join(" AND ")}] (changed mid-apply). Not applied — re-plan against current data.`,
+            });
+            if (operation.groupId)
+                poisonedGroups.add(operation.groupId);
+            continue;
+        }
+        if (operation.groupId && poisonedGroups.has(operation.groupId)) {
+            results.push({
+                operationId: operation.id,
+                status: "skipped",
+                detail: `Skipped: another operation in group ${operation.groupId} hit a conflict — the group applies all-or-nothing.`,
+            });
+            continue;
         }
         const resolved = override === undefined ? operation : { ...operation, afterValue: override };
         attempted += 1;
         try {
             const result = await connector.applyOperation(resolved);
             results.push(result);
-            if (result.status === "applied")
+            if (result.status === "applied") {
                 applied += 1;
+                appliedSinceRecheck += 1;
+                // shrink the TOCTOU window: first write fires a re-check (a
+                // concurrent editor reacting to our changes shows up immediately),
+                // then re-check on a fixed cadence
+                if (applied === 1 || appliedSinceRecheck >= recheckEvery) {
+                    appliedSinceRecheck = 0;
+                    await refreshSnapshotChecks();
+                }
+            }
         }
         catch (error) {
             results.push({

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { auditSnapshot, defaultPolicy } from "./audit.ts";
+export { buildBulkUpdatePlan, parseWhere, type BulkUpdateOptions } from "./bulkUpdate.ts";
 export { CONFIG_FILE_NAME, loadConfig, mergePolicy, resolveConfiguredRules, type FullstackgtmConfig, type LoadedConfig, } from "./config.ts";
 export { applyPatchPlan, type ApplyPatchPlanOptions } from "./connector.ts";
 export { createHubspotConnector, type HubspotConnectorOptions } from "./connectors/hubspot.ts";
@@ -17,11 +18,13 @@ export { HUBSPOT_DEFAULT_FIELD_MAPPINGS, SALESFORCE_DEFAULT_FIELD_MAPPINGS, mapp
 export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, provenanceSummary, requiresHumanInput, staleDealRule, } from "./rules.ts";
 export { extractCallInsights, normalizeTranscript, parseCall, parseTranscript, suggestCallDeal, summarizeInsights, type CallDealSuggestion, type CallInsightType, type ExtractedCallInsight, type ParsedCall, type ParsedTranscriptSegment, } from "./calls.ts";
 export { sampleSnapshot } from "./sampleData.ts";
-export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, type CallScorecard, type LlmCredential, type LlmExtractedInsight, type LlmProvider, type Rubric, type ScoredDimension, } from "./llm.ts";
+export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, forcedToolCall, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, type CallScorecard, type LlmCredential, type LlmExtractedInsight, type LlmProvider, type Rubric, type ScoredDimension, } from "./llm.ts";
 export { resolveRecord, type ResolveCandidate, type ResolveMatch, type ResolveResult } from "./resolve.ts";
-export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadCaptureTexts, loadMarketConfig, marketHome, normalizeForMatch, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, type CaptureEntry, type CaptureOptions, type ClaimFront, type ClaimIntensity, type FrontDrift, type FrontState, type MarketAxis, type MarketClaim, type MarketConfig, type MarketObservation, type MarketVendor, type ObservationConfidence, type ObservationSet, type ObservationStore, type SpanVerificationFailure, } from "./market.ts";
+export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadCaptureTexts, loadMarketConfig, marketHome, normalizeForMatch, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, type CaptureEntry, type CaptureOptions, type ClaimFront, type ClaimIntensity, type FrontDrift, type FrontState, type MarketAxis, type MarketClaim, type MarketConfig, type MarketObservation, type MarketVendor, type ObservationConfidence, type ObservationSet, type ObservationStore, type ScaleSignal, type SpanVerificationFailure, } from "./market.ts";
 export { assessAxes, axesReportToText, axisPosition, messageBreadth, pcaTop2, pearson, type AxesReport, type AxisAssessment, type AxisPairing, type PrincipalComponent, } from "./marketAxes.ts";
 export { buildWorksheet, classifyMarket, type ClassifyMarketOptions, type ClassifyMarketResult, type MarketWorksheet, } from "./marketClassify.ts";
+export { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, type CallDocument, type ClaimMentionStats, type DirectiveStat, type DirectiveType, type MarketDirective, type OverlayOptions, type OverlayStats, type VendorMentionStats, } from "./marketOverlay.ts";
+export { computeScaleIndex, scaleReportToText, type ScaleReport, type VendorScale } from "./marketScale.ts";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.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

@@ -1,4 +1,5 @@
 export { auditSnapshot, defaultPolicy } from "./audit.js";
+export { buildBulkUpdatePlan, parseWhere } from "./bulkUpdate.js";
 export { CONFIG_FILE_NAME, loadConfig, mergePolicy, resolveConfiguredRules, } from "./config.js";
 export { applyPatchPlan } from "./connector.js";
 export { createHubspotConnector } from "./connectors/hubspot.js";
@@ -17,10 +18,12 @@ export { HUBSPOT_DEFAULT_FIELD_MAPPINGS, SALESFORCE_DEFAULT_FIELD_MAPPINGS, mapp
 export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, provenanceSummary, requiresHumanInput, staleDealRule, } from "./rules.js";
 export { extractCallInsights, normalizeTranscript, parseCall, parseTranscript, suggestCallDeal, summarizeInsights, } from "./calls.js";
 export { sampleSnapshot } from "./sampleData.js";
-export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
+export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, forcedToolCall, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
 export { resolveRecord } from "./resolve.js";
 export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadCaptureTexts, loadMarketConfig, marketHome, normalizeForMatch, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, } from "./market.js";
 export { assessAxes, axesReportToText, axisPosition, messageBreadth, pcaTop2, pearson, } from "./marketAxes.js";
 export { buildWorksheet, classifyMarket, } from "./marketClassify.js";
+export { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, } from "./marketOverlay.js";
+export { computeScaleIndex, scaleReportToText } from "./marketScale.js";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
 export { suggestValues } from "./suggest.js";

package/dist/market.d.ts

@@ -29,6 +29,30 @@ export type MarketClaim = {
     pricingStructure: string;
     /** Operational definition: how a reader judges LOUD vs QUIET vs ABSENT. */
     definition: string;
+    /**
+     * Exact terms buyers use for this claim, for deterministic mention
+     * matching against call transcripts (the overlay). No terms = no mention
+     * stats for this claim; matching is word-boundary, case-insensitive.
+     */
+    terms?: string[];
+};
+/**
+ * One public, citable scale signal for a vendor (G2 review count, LinkedIn
+ * headcount, disclosed revenue, self-reported customer count). The composite
+ * of several biased-in-different-directions signals sizes the report's
+ * bubbles — a RELATIVE scale index within the mapped set, never "market
+ * share" unqualified.
+ */
+export type ScaleSignal = {
+    /** e.g. "g2_reviews", "linkedin_employees", "revenue_usd", "self_reported_customers". */
+    metric: string;
+    value: number;
+    unit: string;
+    sourceUrl: string;
+    /** Verbatim snippet containing the number — same evidence posture as observations. */
+    quote: string;
+    asOf: string;
+    caveat?: string;
 };
 export type MarketVendor = {
     id: string;
@@ -39,6 +63,10 @@ export type MarketVendor = {
         pricing: string | null;
         product: string[];
     };
+    /** Alternate names/spellings for deterministic mention matching. */
+    aliases?: string[];
+    /** Public scale signals; see ScaleSignal. */
+    scaleSignals?: ScaleSignal[];
     notes?: string;
 };
 export type MarketAxis = {

package/dist/market.js

@@ -58,6 +58,9 @@ export function parseMarketConfig(raw) {
             if (axisIds.has(axis.id))
                 throw new Error(`market config: duplicate axis id "${axis.id}"`);
             axisIds.add(axis.id);
+            if (!axis.negativePole || !axis.positivePole) {
+                throw new Error(`market config: axis "${axis.id}" needs negativePole and positivePole labels (the strategic map renders them as axis ends)`);
+            }
             for (const claimId of Object.keys(axis.claimScores ?? {})) {
                 if (!claimIds.has(claimId)) {
                     throw new Error(`market config: axis "${axis.id}" scores unknown claim "${claimId}"`);

package/dist/marketOverlay.d.ts

@@ -0,0 +1,116 @@
+import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
+import type { MarketConfig, ObservationSet } from "./market.ts";
+/**
+ * The directive layer: the market map joined to the company's own ground
+ * truth. The map alone says what the category looks like; the overlay says
+ * what THIS company should do about it — and two companies running the same
+ * map see different directives, because the overlay is their own conversion
+ * fingerprint.
+ *
+ * Everything here is deterministic. Inputs are the observation store (front
+ * states), a CRM snapshot (won/lost deals), and call documents (transcript
+ * text, optionally linked to deals). Claim mentions are found by exact
+ * word-boundary term matching against each claim's configured `terms` —
+ * the same posture as the rest of the map: no model in the loop, every
+ * directive carries at least one observation and at least one CRM statistic
+ * with its sample size, and small samples refuse to become claims (the
+ * minimum-evidence thresholds are explicit options, not vibes).
+ */
+export type CallDocument = {
+    id: string;
+    text: string;
+    /** Links the document to a deal for win/loss statistics; optional. */
+    dealId?: string;
+    occurredAt?: string;
+};
+export type ClaimMentionStats = {
+    claimId: string;
+    /** Documents whose text matches any of the claim's terms. */
+    mentionDocIds: string[];
+    /** Distinct deals among those documents (only docs with dealId count). */
+    mentionDealIds: string[];
+    wonDeals: number;
+    lostDeals: number;
+    /** won / (won + lost) among closed mentioned deals; null below any closure. */
+    winRateWhenMentioned: number | null;
+};
+export type VendorMentionStats = {
+    vendorId: string;
+    mentionDocIds: string[];
+    mentionDealIds: string[];
+    wonWhenMentioned: number;
+    lostWhenMentioned: number;
+};
+export type OverlayStats = {
+    documents: number;
+    documentsWithDeal: number;
+    deals: {
+        total: number;
+        closed: number;
+        won: number;
+        baselineWinRate: number | null;
+    };
+    claims: ClaimMentionStats[];
+    vendors: VendorMentionStats[];
+};
+export type DirectiveType = "occupy" | "promote" | "urgent" | "retreat";
+export type DirectiveStat = {
+    name: string;
+    value: number | string;
+    n: number;
+};
+export type MarketDirective = {
+    id: string;
+    type: DirectiveType;
+    claimId: string;
+    title: string;
+    summary: string;
+    recommendation: string;
+    /** ≥1 observation id and ≥1 CRM stat — the spec's evidence-chain rule. */
+    observationIds: string[];
+    stats: DirectiveStat[];
+};
+export type OverlayOptions = {
+    /** Minimum mention documents before OCCUPY/PROMOTE may fire (default 3). */
+    minMentions?: number;
+    /** Minimum win-rate lift over baseline for PROMOTE (default 0.10). */
+    promoteLift?: number;
+    /** Minimum won deals in the corpus before RETREAT may fire (default 3). */
+    minWonDealsForRetreat?: number;
+    /** Prior run's observations: enables URGENT (front drift) directives. */
+    priorSet?: ObservationSet;
+};
+/**
+ * Deterministic claim/vendor mention statistics over a call corpus.
+ * Claims match on their configured `terms` (claims without terms simply have
+ * no mention stats — the directives that need mentions will not fire for
+ * them); vendors match on name + configured `aliases`.
+ */
+export declare function computeOverlayStats(config: MarketConfig, snapshot: CanonicalGtmSnapshot, documents: CallDocument[]): OverlayStats;
+/**
+ * Directive rules v1 — deterministic over (front states × overlay stats),
+ * with explicit minimum-evidence thresholds so small samples cannot mint
+ * strategy. Requires config.anchorVendor: directives are advice to someone.
+ *
+ *   OCCUPY  — open/vacant front the anchor doesn't own loudly, and buyers
+ *             demonstrably talk about it (≥ minMentions documents).
+ *   PROMOTE — anchor is quiet on a claim whose mentioned-deal win rate beats
+ *             baseline by ≥ promoteLift (with ≥ minMentions mentioned deals).
+ *   URGENT  — a front the anchor is loud on drifted toward saturation since
+ *             the prior run (requires priorSet).
+ *   RETREAT — saturated front the anchor is loud on, with zero presence in
+ *             won-deal conversations despite a corpus that contains wins.
+ */
+export declare function computeDirectives(config: MarketConfig, set: ObservationSet, stats: OverlayStats, options?: OverlayOptions): MarketDirective[];
+/**
+ * Emit directives as a standard dry-run patch plan: one approval-gated
+ * create_task per directive against a designated CRM record (the company's
+ * own account/deal record — directives are strategy tasks, and the CRM
+ * needs somewhere to hang them). Approving and applying goes through the
+ * normal plans → approve → apply gate; nothing here writes.
+ */
+export declare function directivesToPlan(config: MarketConfig, set: ObservationSet, directives: MarketDirective[], target: {
+    objectType: "account" | "deal";
+    objectId: string;
+}, now?: () => Date): PatchPlan;
+export declare function overlayToMarkdown(stats: OverlayStats, directives: MarketDirective[]): string;