fullstackgtm 0.18.0 → 0.19.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,

package/src/market.ts

@@ -172,6 +172,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}"`);

package/src/mcp.ts

@@ -335,7 +335,7 @@ export async function startMcpServer() {
       },
     },
     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 }));
     },
   );
@@ -355,7 +355,7 @@ export async function startMcpServer() {
       },
     },
     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")) as ObservationSet;
       const problems = validateObservationSet(config, set);
       const failures = verifyEvidenceSpans(set.observations, loadCaptureTexts(config.category).textByHash);
@@ -375,3 +375,16 @@ export async function startMcpServer() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
+
+function loadMarketConfigOrHint(path: string): ReturnType<typeof loadMarketConfig> {
+  try {
+    return loadMarketConfig(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).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/src/types.ts

@@ -289,6 +289,20 @@ 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;
 };
 
 /**
@@ -306,6 +320,31 @@ 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;
 };
 
 // ── Audit rule engine ──────────────────────────────────────────