fullstackgtm 0.18.0 → 0.20.0

package/src/connector.ts

@@ -27,6 +27,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;
 };
 
 const FIELD_WRITE_OPERATIONS = new Set(["set_field", "clear_field", "link_record"]);
@@ -60,6 +66,129 @@ export async function applyPatchPlan(
   const results: PatchOperationResult[] = [];
   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<string>();
+  let guardFailure: string | null = null;
+  const refreshSnapshotChecks = async (): Promise<void> => {
+    if (!needsSnapshot) return;
+    const { evaluateGuard, eligibleIds } = await import("./bulkUpdate.ts");
+    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: Set<string> | null = 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<string, PatchOperationResult>();
+  const poisonedGroups = new Set<string>();
+  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: PatchOperationResult | null = 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)) {
@@ -81,28 +210,35 @@ export async function applyPatchPlan(
       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: PatchOperation =
@@ -112,7 +248,17 @@ export async function applyPatchPlan(
     try {
       const result = await connector.applyOperation(resolved);
       results.push(result);
-      if (result.status === "applied") applied += 1;
+      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({
         operationId: operation.id,

package/src/index.ts

@@ -1,4 +1,5 @@
 export { auditSnapshot, defaultPolicy } from "./audit.ts";
+export { buildBulkUpdatePlan, parseWhere, type BulkUpdateOptions } from "./bulkUpdate.ts";
 export {
   CONFIG_FILE_NAME,
   loadConfig,
@@ -118,6 +119,7 @@ export {
   DEFAULT_RUBRIC,
   detectProviderFromKey,
   extractInsightsLlm,
+  forcedToolCall,
   parseRubric,
   resolveLlmCredential,
   scoreCallLlm,
@@ -159,6 +161,7 @@ export {
   type ObservationConfidence,
   type ObservationSet,
   type ObservationStore,
+  type ScaleSignal,
   type SpanVerificationFailure,
 } from "./market.ts";
 export {
@@ -180,6 +183,21 @@ export {
   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 {

package/src/market.ts

@@ -38,6 +38,31 @@ 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 = {
@@ -49,6 +74,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;
 };
 
@@ -172,6 +201,9 @@ export function parseMarketConfig(raw: string): MarketConfig {
       if (!axis.id) throw new Error("market config: axis missing id");
       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}"`);