fullstackgtm 0.18.0 → 0.19.0

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,7 +18,7 @@ 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 { assessAxes, axesReportToText, axisPosition, messageBreadth, pcaTop2, pearson, type AxesReport, type AxisAssessment, type AxisPairing, type PrincipalComponent, } from "./marketAxes.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,7 +18,7 @@ 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";

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/mcp.js

@@ -260,7 +260,7 @@ export async function startMcpServer() {
             captureRun: z.string().optional(),
         },
     }, async ({ vendorId, configPath, captureRun }) => {
-        const config = loadMarketConfig(resolve(process.cwd(), configPath ?? "market.config.json"));
+        const config = loadMarketConfigOrHint(resolve(process.cwd(), configPath ?? "market.config.json"));
         return content(buildWorksheet(config, vendorId, { captureRun }));
     });
     server.registerTool("fullstackgtm_market_observe", {
@@ -274,7 +274,7 @@ export async function startMcpServer() {
             configPath: z.string().optional().describe("Path to market.config.json (default ./market.config.json)"),
         },
     }, async ({ observationsPath, configPath }) => {
-        const config = loadMarketConfig(resolve(process.cwd(), configPath ?? "market.config.json"));
+        const config = loadMarketConfigOrHint(resolve(process.cwd(), configPath ?? "market.config.json"));
         const set = JSON.parse(readFileSync(resolve(process.cwd(), observationsPath), "utf8"));
         const problems = validateObservationSet(config, set);
         const failures = verifyEvidenceSpans(set.observations, loadCaptureTexts(config.category).textByHash);
@@ -292,3 +292,14 @@ export async function startMcpServer() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
+function loadMarketConfigOrHint(path) {
+    try {
+        return loadMarketConfig(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`No market config at ${path} — run \`fullstackgtm market init --category <name>\` in that directory first, or pass configPath.`);
+        }
+        throw error;
+    }
+}

package/dist/types.d.ts

@@ -222,6 +222,23 @@ export type PatchOperation = {
     evidenceIds?: string[];
     findingIds?: string[];
     verification?: PatchVerification;
+    /**
+     * Compare-and-set guards beyond the written field: each precondition is
+     * re-read at apply time and a mismatch turns the operation into a
+     * conflict instead of a write. Guards against a record drifting on a
+     * DIFFERENT field than the one being written (e.g. stage changed while
+     * an owner write was pending).
+     */
+    preconditions?: Array<{
+        field: string;
+        expectedValue: unknown;
+    }>;
+    /**
+     * Operations sharing a groupId are all-or-nothing at apply time: a
+     * conflict (beforeValue or precondition) on any member skips every
+     * member of the group.
+     */
+    groupId?: string;
 };
 /**
  * A patch plan is always a dry-run proposal. Applying a plan never mutates
@@ -238,6 +255,33 @@ export type PatchPlan = {
     pipelineFindings?: PipelineFinding[];
     evidence?: GtmEvidence[];
     operations: PatchOperation[];
+    /**
+     * The filter this plan's operations were selected by. Re-evaluated per
+     * record against a FRESH snapshot at apply time: any operation whose
+     * record no longer matches is reported as a conflict instead of applied.
+     * Unlike per-operation preconditions, this enforces the FULL filter —
+     * negations and relational pseudo-fields included.
+     */
+    filter?: {
+        objectType: "account" | "contact" | "deal";
+        where: string[];
+    };
+    /**
+     * Plan-level guards re-evaluated against a FRESH snapshot at apply time.
+     * If any guard fails, NO operation in the plan is applied. This is how a
+     * plan expresses cross-record eligibility ("apply only while the account
+     * still has no open deal in contractsent") that per-operation
+     * preconditions cannot reach.
+     */
+    guards?: PlanGuard[];
+};
+export type PlanGuard = {
+    objectType: "account" | "contact" | "deal";
+    /** filter expressions in bulk-update --where grammar, AND-ed */
+    where: string[];
+    /** none: guard passes when ZERO records match; some: when at least one matches */
+    expect: "none" | "some";
+    description?: string;
 };
 /** Pre-computed lookups shared by all rules so each rule stays O(n). */
 export type GtmSnapshotIndex = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM",