fullstackgtm 0.45.0 → 0.47.0

package/src/mcp.ts

@@ -53,6 +53,8 @@ import {
 import { generateDemoSnapshot } from "./demo.ts";
 import type { FieldMappings } from "./mappings.ts";
 import { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
+import { verifyApprovalDigests } from "./integrity.ts";
+import { createFilePlanStore, type StoredPlan } from "./planStore.ts";
 import { builtinAuditRules } from "./rules.ts";
 import { sampleSnapshot } from "./sampleData.ts";
 import { normalizeTranscript, parseCall } from "./calls.ts";
@@ -322,7 +324,11 @@ const toolDefinitions: ToolDefinition[] = [
       description:
         "Apply explicitly approved operations from a patch plan through a provider " +
         "connector. Operations not listed in approvedOperationIds are never written, " +
-        "and requires_human_* placeholders need a value override.",
+        "and requires_human_* placeholders need a value override. When the plan is in " +
+        "the local plan store (saved via `audit --save`), approvals are verified against " +
+        "the store's HMAC approval digests — ids not approved with `plans approve` are " +
+        "refused — and the run is recorded onto the stored plan so `plans show` and " +
+        "`audit-log export` include it.",
       inputSchema: {
         provider: z.enum(["hubspot", "salesforce"]),
         planPath: z.string(),
@@ -332,14 +338,128 @@ const toolDefinitions: ToolDefinition[] = [
       },
     },
     handler: async ({ provider, planPath, approvedOperationIds, valueOverrides, output }) => {
-      const plan = JSON.parse(
-        readFileSync(resolve(process.cwd(), planPath), "utf8"),
-      ) as PatchPlan;
+      // The file may be a raw PatchPlan (audit --out) or a StoredPlan envelope
+      // (a file straight out of the plan-store directory).
+      const parsed = JSON.parse(readFileSync(resolve(process.cwd(), planPath), "utf8")) as unknown;
+      const filePlan = isStoredPlanFile(parsed) ? parsed.plan : (parsed as PatchPlan);
+      if (!filePlan || !Array.isArray(filePlan.operations)) {
+        throw new Error(`${planPath} is not a patch plan (expected { id, operations: [...] }).`);
+      }
+
+      // Governance parity with CLI apply: when this plan id exists in the local
+      // plan store, the STORE is the source of truth — the approved-id set must
+      // come from `plans approve` (which HMAC-signed each approved op), the
+      // signatures are re-verified here, and the run is recorded back onto the
+      // plan so audit-log export sees MCP applies exactly like CLI applies.
+      const store = createFilePlanStore();
+      const stored =
+        typeof filePlan.id === "string" && /^[\w.-]+$/.test(filePlan.id)
+          ? await store.get(filePlan.id)
+          : null;
+
+      let plan: PatchPlan;
+      let effectiveOverrides: Record<string, unknown>;
+      if (stored) {
+        if (stored.status !== "approved") {
+          throw new Error(
+            `Plan ${filePlan.id} is ${stored.status}; approve operations first with ` +
+              `\`fullstackgtm plans approve ${filePlan.id} --operations <ids|all>\`.`,
+          );
+        }
+        // Downgrade guard (same as CLI apply): an approved plan with no
+        // signatures either predates 0.26 or had approvalDigests stripped to
+        // skip the integrity check. Refuse rather than trust the file.
+        if (stored.approvedOperationIds.length > 0 && !stored.approvalDigests) {
+          throw new Error(
+            `Refusing to apply plan ${filePlan.id}: it was approved without integrity signatures ` +
+              "(approved before 0.26.0, or its signatures were removed). Re-approve it with " +
+              `\`fullstackgtm plans approve ${filePlan.id} --operations <ids|all>\`.`,
+          );
+        }
+        // Never widen: every id the tool wants applied must already be
+        // store-approved. (A subset is fine — narrowing never writes more.)
+        const storeApproved = new Set(stored.approvedOperationIds);
+        const unapproved = approvedOperationIds.filter((id: string) => !storeApproved.has(id));
+        if (unapproved.length > 0) {
+          throw new Error(
+            `Refusing to apply plan ${filePlan.id}: operation(s) ${unapproved.join(", ")} were never ` +
+              "approved in the plan store. Approve them first with " +
+              `\`fullstackgtm plans approve ${filePlan.id} --operations <ids>\`.`,
+          );
+        }
+        // Integrity gate: verify against the EFFECTIVE overrides (stored ∪ tool
+        // args), so a tool-supplied value that changes what the human approved
+        // is treated as tamper, not a live override — what gets written must
+        // equal what was signed.
+        effectiveOverrides = { ...stored.valueOverrides, ...(valueOverrides ?? {}) };
+        const verification = verifyApprovalDigests(
+          stored.plan.operations,
+          stored.approvedOperationIds,
+          effectiveOverrides,
+          stored.approvalDigests,
+        );
+        if (!verification.ok) {
+          const detail =
+            verification.reason === "no_key"
+              ? "the plan-signing key is missing (was this plan approved on another machine?). Re-approve it here with `fullstackgtm plans approve`."
+              : `these operations differ from what was approved: ${verification.tampered.join(", ")}. ` +
+                "If you want a different value, set it at approval (`plans approve --value <op>=<v>`) and re-approve; " +
+                "otherwise the plan was edited after approval — review and re-approve.";
+          throw new Error(`Refusing to apply plan ${filePlan.id}: ${detail}`);
+        }
+        plan = stored.plan; // apply what was signed, not what the file says now
+      } else {
+        // External plan file, not in the store: no digests exist to verify, but
+        // approvals must still reference real operations in the plan content.
+        plan = filePlan;
+        const known = new Set(plan.operations.map((operation) => operation.id));
+        const unknown = approvedOperationIds.filter((id: string) => !known.has(id));
+        if (unknown.length > 0) {
+          throw new Error(
+            `Plan ${planPath} has no operation(s) ${unknown.join(", ")} — approvedOperationIds ` +
+              "must reference operations in the plan.",
+          );
+        }
+        effectiveOverrides = valueOverrides ?? {};
+      }
+
       const run = await applyPatchPlan(await connectorFor(provider), plan, {
         approvedOperationIds,
-        valueOverrides,
+        valueOverrides: effectiveOverrides,
       });
-      return content(output === "markdown" ? formatPatchPlanRun(run) : run);
+
+      // Persist the run (same data the CLI records) so runs[] and plan status
+      // update and audit-log export includes MCP applies. External plan files
+      // have no store entry to update — say so instead of silently dropping it.
+      let runRecorded = false;
+      if (stored) {
+        await store.recordRun(plan.id, run);
+        runRecorded = true;
+      }
+      const governance = {
+        planSource: stored ? ("store" as const) : ("external" as const),
+        approvalDigestsVerified: stored !== null,
+        runRecorded,
+        ...(stored
+          ? {}
+          : {
+              note:
+                "Plan file is not in the local plan store: approvals came from tool arguments " +
+                "(verified against the plan content only — no approval-digest check) and the run " +
+                "was not recorded. Use `fullstackgtm audit --save` + `plans approve` for " +
+                "store-backed governance.",
+            }),
+      };
+      if (output === "markdown") {
+        return content(
+          `${formatPatchPlanRun(run)}\n\nGovernance: plan source ${governance.planSource}; ` +
+            (runRecorded
+              ? "approval digests verified; run recorded on the stored plan (audit-log export includes it)."
+              : governance.note!),
+        );
+      }
+      // Backward compatible: the run's own fields stay top-level; governance is additive.
+      return content({ ...run, governance });
     },
   },
   {
@@ -456,6 +576,20 @@ export async function startMcpServer() {
   await server.connect(transport);
 }
 
+/**
+ * A plan-store file is a StoredPlan envelope ({ plan, status, runs, ... });
+ * `audit --out` writes a bare PatchPlan. fullstackgtm_apply accepts either.
+ */
+function isStoredPlanFile(value: unknown): value is StoredPlan {
+  if (typeof value !== "object" || value === null || !("plan" in value)) return false;
+  const plan = (value as { plan?: unknown }).plan;
+  return (
+    typeof plan === "object" &&
+    plan !== null &&
+    Array.isArray((plan as { operations?: unknown }).operations)
+  );
+}
+
 function loadMarketConfigOrHint(path: string): ReturnType<typeof loadMarketConfig> {
   try {
     return loadMarketConfig(path);

package/src/progress.ts

@@ -0,0 +1,197 @@
+/**
+ * The shared progress-event vocabulary — ONE set of semantics for every
+ * long-running process, rendered natively by each surface:
+ *
+ *   CLI  → ui.ts (spinner / checklist / apply-ticker; TTY-only styling)
+ *   app  → Convex heartbeat patches → reactive ProgressChip / StageTimeline
+ *   both → optional broker streaming (a paired CLI POSTs heartbeats to the
+ *          hosted app under its clientRunId, so long local runs tick live in
+ *          the org's activity feed)
+ *
+ * Renderer-agnostic by contract: no event assumes persistence (the CLI drops
+ * them after painting) or ANSI (the app can't use it). Listeners are
+ * best-effort — a throwing renderer must never fail the work — and the
+ * throttle policy lives HERE so both surfaces feel identical.
+ *
+ * Standing convention: if a verb loops, it emits. New long-running verbs wire
+ * an emitter at the package layer; surfaces get feedback for free.
+ */
+
+export type ProgressEvent =
+  | { kind: "stage"; stage: string; stageIndex: number; stageCount: number }
+  | { kind: "items"; done: number; total?: number }
+  | { kind: "note"; note: string }
+  | {
+      kind: "opResult";
+      opId: string;
+      status: "applied" | "skipped" | "failed" | "conflict";
+      detail?: string;
+    }
+  | { kind: "meter"; spent: number; budget: number; unit: string };
+
+/** Accumulated state — what a heartbeat persists / a chip renders. */
+export type ProgressSnapshot = {
+  stage?: string;
+  stageIndex?: number;
+  stageCount?: number;
+  itemsDone?: number;
+  itemsTotal?: number;
+  note?: string;
+  opsApplied: number;
+  opsSkipped: number;
+  opsFailed: number;
+  updatedAt: number;
+};
+
+export type ProgressListener = (event: ProgressEvent, snapshot: ProgressSnapshot) => void;
+
+export type ProgressEmitter = {
+  stage(stage: string, stageIndex: number, stageCount: number): void;
+  items(done: number, total?: number): void;
+  note(note: string): void;
+  opResult(opId: string, status: "applied" | "skipped" | "failed" | "conflict", detail?: string): void;
+  meter(spent: number, budget: number, unit: string): void;
+  /** Current accumulated state (always fresh, ignoring the throttle). */
+  snapshot(): ProgressSnapshot;
+  /** Force-deliver the latest state (call at stage ends / completion). */
+  flush(): void;
+};
+
+const DEFAULT_THROTTLE_MS = 2000;
+
+/**
+ * Throttled emitter: `items` heartbeats coalesce to at most one delivery per
+ * throttle window (terminal `done === total` always delivers); `stage`,
+ * `opResult`, `note`, and `meter` are structural and always deliver.
+ */
+export function createProgressEmitter(
+  listener: ProgressListener,
+  options: { throttleMs?: number; now?: () => number } = {},
+): ProgressEmitter {
+  const throttleMs = options.throttleMs ?? DEFAULT_THROTTLE_MS;
+  const now = options.now ?? Date.now;
+  const state: ProgressSnapshot = {
+    opsApplied: 0,
+    opsSkipped: 0,
+    opsFailed: 0,
+    updatedAt: now(),
+  };
+  let lastItemsDelivery = 0;
+  let pendingItems = false;
+
+  function deliver(event: ProgressEvent) {
+    state.updatedAt = now();
+    try {
+      listener(event, { ...state });
+    } catch {
+      // Renderers are presentation-only; never fail the work.
+    }
+  }
+
+  return {
+    stage(stage, stageIndex, stageCount) {
+      state.stage = stage;
+      state.stageIndex = stageIndex;
+      state.stageCount = stageCount;
+      state.itemsDone = undefined;
+      state.itemsTotal = undefined;
+      state.note = undefined;
+      pendingItems = false;
+      deliver({ kind: "stage", stage, stageIndex, stageCount });
+    },
+    items(done, total) {
+      state.itemsDone = done;
+      state.itemsTotal = total;
+      const terminal = total !== undefined && done >= total;
+      const due = now() - lastItemsDelivery >= throttleMs;
+      if (terminal || due) {
+        lastItemsDelivery = now();
+        pendingItems = false;
+        deliver({ kind: "items", done, total });
+      } else {
+        pendingItems = true;
+      }
+    },
+    note(note) {
+      state.note = note;
+      deliver({ kind: "note", note });
+    },
+    opResult(opId, status, detail) {
+      if (status === "applied") state.opsApplied += 1;
+      else if (status === "skipped") state.opsSkipped += 1;
+      else state.opsFailed += 1;
+      deliver({ kind: "opResult", opId, status, detail });
+    },
+    meter(spent, budget, unit) {
+      deliver({ kind: "meter", spent, budget, unit });
+    },
+    snapshot() {
+      return { ...state, updatedAt: now() };
+    },
+    flush() {
+      if (pendingItems && state.itemsDone !== undefined) {
+        lastItemsDelivery = now();
+        pendingItems = false;
+        deliver({ kind: "items", done: state.itemsDone, total: state.itemsTotal });
+      }
+    },
+  };
+}
+
+/**
+ * Fan one event stream out to several listeners (e.g. the CLI's local renderer
+ * plus the broker heartbeat streamer). Each listener is isolated: one throwing
+ * never starves the others, matching the emitter's own best-effort contract.
+ */
+export function composeListeners(
+  ...listeners: Array<ProgressListener | undefined | null>
+): ProgressListener {
+  const active = listeners.filter((listener): listener is ProgressListener => Boolean(listener));
+  return (event, snapshot) => {
+    for (const listener of active) {
+      try {
+        listener(event, snapshot);
+      } catch {
+        // Listeners are presentation/observability only; never fail the work.
+      }
+    }
+  };
+}
+
+// ── Shared stage registries ─────────────────────────────────────────────────
+// Package constants so the CLI checklist and the app StageTimeline render
+// LITERALLY the same stages in the same order — one mental model everywhere.
+
+export const CRM_SYNC_STAGES = [
+  "owners",
+  "accounts",
+  "contacts",
+  "deals",
+  "counters",
+  "health",
+] as const;
+
+/** A connector snapshot pull — the CRM-sync stages that happen CLI-side. */
+export const SNAPSHOT_PULL_STAGES = ["owners", "accounts", "contacts", "deals"] as const;
+
+/** The Stripe connector's snapshot pull (billing systems have no owners). */
+export const STRIPE_SNAPSHOT_STAGES = ["customers", "subscriptions"] as const;
+
+export const CALL_SYNC_STAGES = ["notes", "transcripts", "insights"] as const;
+
+export const BACKFILL_STRIPE_STAGES = ["invoices", "snapshot", "matching", "plan"] as const;
+
+/** `backfill runs` — replaying local plan runs + health history to the broker. */
+export const RUNS_REPLAY_STAGES = ["runs", "health"] as const;
+
+export const APPLY_STAGES = ["preflight", "operations", "results"] as const;
+
+/** `enrich acquire` — routing sourced candidate rows into a create plan. */
+export const ACQUIRE_STAGES = ["candidates"] as const;
+
+export const MARKET_CAPTURE_STAGES = ["sources", "capture", "classify", "persist"] as const;
+
+/** No-op emitter for callers that don't care (keeps signatures simple). */
+export function nullProgressEmitter(): ProgressEmitter {
+  return createProgressEmitter(() => {});
+}

package/src/runReport.ts

@@ -8,6 +8,7 @@
  * pure added value for users who granted it.
  */
 import { getCredential } from "./credentials.ts";
+import type { ProgressListener, ProgressSnapshot } from "./progress.ts";
 
 type RunEvent = { ts: number; type: string; detail?: string };
 
@@ -61,6 +62,16 @@ export function reportEvent(type: string, detail?: string): void {
   events.push({ ts: Date.now(), type, detail });
 }
 
+// FNV-1a — the stable-id hash used across the package (see backfill.ts).
+function fnv1a(value: string): string {
+  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");
+}
+
 // Setup/inspection verbs aren't interesting as "runs" — skip the noise.
 const SKIP_COMMANDS = new Set([
   "login",
@@ -74,6 +85,144 @@ const SKIP_COMMANDS = new Set([
   "-v",
 ]);
 
+/** The stable per-invocation identity flushRunReport and heartbeats share. */
+function runIdentity(
+  args: string[],
+  startedAt: number,
+): { command: string; clientRunId: string } | null {
+  const command = args[0];
+  if (!command || SKIP_COMMANDS.has(command)) return null;
+  const sub = args[1] && !args[1].startsWith("-") ? ` ${args[1]}` : "";
+  const full = `${command}${sub}`;
+  return { command: full, clientRunId: `run_${fnv1a(`${full}:${startedAt}:${process.pid}`)}` };
+}
+
+// ── Live progress streaming ─────────────────────────────────────────────────
+// While a long command runs, a paired CLI streams heartbeats to the hosted
+// app: POST /api/cli/run with the SAME clientRunId the final flushRunReport
+// will use, status "in_progress", and the progress emitter's snapshot. The
+// server upserts by clientRunId, so the terminal flush simply wins. Same
+// invariants as flushRunReport: opt-in (paired only), fire-and-forget,
+// time-capped, never affects the command's outcome or output.
+
+const HEARTBEAT_INTERVAL_MS = 5000;
+/** No heartbeat before the run is ~this old — fast commands never stream. */
+const HEARTBEAT_MIN_RUN_MS = 5000;
+const HEARTBEAT_TIMEOUT_MS = 2000;
+
+type RunContext = { command: string; clientRunId: string; startedAt: number };
+
+let runContext: RunContext | null = null;
+let lastHeartbeatAt = 0;
+// Broker credential resolved once per run (undefined = not looked up yet;
+// null = looked up, not paired).
+let heartbeatBroker: { baseUrl: string; accessToken: string } | null | undefined;
+let inflightHeartbeat: AbortController | null = null;
+
+/**
+ * Arm heartbeat streaming for this invocation. Call once from the entry point
+ * (alongside capturing `startedAt`); without it, progress listeners from
+ * `progressReporter()` are inert. Safe to call for any command — skip-listed
+ * commands simply never stream.
+ */
+export function beginRunReport(args: string[], startedAt: number): void {
+  lastHeartbeatAt = 0;
+  heartbeatBroker = undefined;
+  inflightHeartbeat = null;
+  const identity = runIdentity(args, startedAt);
+  runContext = identity ? { ...identity, startedAt } : null;
+}
+
+/**
+ * A ProgressListener that streams the run's progress snapshot to the paired
+ * hosted app. Verbs compose it with their local renderer:
+ *
+ *   createProgressEmitter(composeListeners(renderer.listener, progressReporter()))
+ *
+ * Throttled to one POST per ~5s, first no earlier than ~5s into the run,
+ * 2s-capped and fire-and-forget. Privacy: stage names and counts only — notes
+ * must stay generic ("batch 4/12"); CRM field values never leave the machine.
+ */
+export function progressReporter(
+  overrides: {
+    now?: () => number;
+    intervalMs?: number;
+    minRunMs?: number;
+    fetchImpl?: typeof fetch;
+  } = {},
+): ProgressListener {
+  const now = overrides.now ?? Date.now;
+  const intervalMs = overrides.intervalMs ?? HEARTBEAT_INTERVAL_MS;
+  const minRunMs = overrides.minRunMs ?? HEARTBEAT_MIN_RUN_MS;
+  const fetchImpl = overrides.fetchImpl ?? fetch;
+  return (_event, snapshot) => {
+    try {
+      if (!runContext) return;
+      const at = now();
+      if (at - runContext.startedAt < minRunMs) return;
+      if (at - lastHeartbeatAt < intervalMs) return;
+      if (heartbeatBroker === undefined) {
+        const broker = getCredential("broker");
+        heartbeatBroker =
+          broker?.baseUrl && broker.accessToken
+            ? { baseUrl: broker.baseUrl.replace(/\/+$/, ""), accessToken: broker.accessToken }
+            : null; // opt-in: only when paired
+      }
+      if (!heartbeatBroker) return;
+      lastHeartbeatAt = at;
+      sendHeartbeat(fetchImpl, heartbeatBroker, runContext, snapshot, at);
+    } catch {
+      // Observability is best-effort; never affect the command.
+    }
+  };
+}
+
+function sendHeartbeat(
+  fetchImpl: typeof fetch,
+  broker: { baseUrl: string; accessToken: string },
+  context: RunContext,
+  snapshot: ProgressSnapshot,
+  at: number,
+): void {
+  // One heartbeat in flight at a time: a stalled POST is superseded, and the
+  // terminal flush aborts any straggler so it can never delay process exit.
+  inflightHeartbeat?.abort();
+  const controller = new AbortController();
+  inflightHeartbeat = controller;
+  const timer = setTimeout(() => controller.abort(), HEARTBEAT_TIMEOUT_MS);
+  (timer as { unref?: () => void }).unref?.();
+  void fetchImpl(`${broker.baseUrl}/api/cli/run`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${broker.accessToken}`, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      command: context.command,
+      clientRunId: context.clientRunId,
+      status: "in_progress",
+      startedAt: context.startedAt,
+      finishedAt: at,
+      durationMs: at - context.startedAt,
+      progress: {
+        // Stage names + counts only — never CRM field values.
+        stage: snapshot.stage,
+        stageIndex: snapshot.stageIndex,
+        stageCount: snapshot.stageCount,
+        itemsDone: snapshot.itemsDone,
+        itemsTotal: snapshot.itemsTotal,
+        note: snapshot.note,
+        heartbeatAt: at,
+      },
+    }),
+    signal: controller.signal,
+  })
+    .catch(() => {
+      // fire-and-forget
+    })
+    .finally(() => {
+      clearTimeout(timer);
+      if (inflightHeartbeat === controller) inflightHeartbeat = null;
+    });
+}
+
 /**
  * Send the run record if the CLI is paired. Best-effort: a 4s-capped POST that
  * swallows every error. Call once per process from the entry point.
@@ -84,19 +233,25 @@ export async function flushRunReport(
   startedAt: number,
   error?: string,
 ): Promise<void> {
-  const command = args[0];
-  if (!command || SKIP_COMMANDS.has(command)) return;
+  // The terminal upsert supersedes any streaming heartbeat still in flight.
+  inflightHeartbeat?.abort();
+  inflightHeartbeat = null;
+  // Stable per-invocation identity: the server dedupes on clientRunId, so a
+  // retried report, an "in_progress" heartbeat, or a later `backfill runs`
+  // replay of local history never duplicates.
+  const identity = runIdentity(args, startedAt);
+  if (!identity) return;
   const broker = getCredential("broker");
   if (!broker?.baseUrl || !broker.accessToken) return; // opt-in: only when paired
 
-  const sub = args[1] && !args[1].startsWith("-") ? ` ${args[1]}` : "";
   const finishedAt = Date.now();
   try {
     await fetch(`${broker.baseUrl.replace(/\/+$/, "")}/api/cli/run`, {
       method: "POST",
       headers: { Authorization: `Bearer ${broker.accessToken}`, "Content-Type": "application/json" },
       body: JSON.stringify({
-        command: `${command}${sub}`,
+        command: identity.command,
+        clientRunId: identity.clientRunId,
         status,
         startedAt,
         finishedAt,

package/src/types.ts

@@ -48,7 +48,8 @@ export type PatchOperationType =
   // on matchKey at apply time (search is the source of truth; the plan-time
   // snapshot can be stale) and creates only on a confirmed miss, so apply is
   // resolve-first and never double-creates a record a concurrent writer added.
-  // Emitted only by `enrich acquire`, and metered against the acquire budget.
+  // Emitted by `enrich acquire` (metered against the acquire budget) and by
+  // `backfill stripe` (closed-won deals from paid invoices, unmetered).
   | "create_record"
   // Merge a duplicate group into a survivor. beforeValue is the group's
   // record ids; afterValue is the survivor id (requires_human_survivor_selection
@@ -59,7 +60,8 @@ export type PatchOperationType =
  * The afterValue of a `create_record` operation. The connector re-resolves on
  * `matchKey`/`matchValue` at apply time and creates only on a confirmed miss.
  * `estCostUsd` is the acquire meter's per-record charge, recorded against the
- * budget on a successful create.
+ * budget on a successful create. Emitted by `enrich acquire` (metered) and
+ * `backfill stripe` (closed-won deals from paid invoices, unmetered).
  */
 export type CreateRecordPayload = {
   properties: Record<string, string>;
@@ -83,6 +85,22 @@ export type CreateRecordPayload = {
   ownerId?: string;
   /** Audit label for how the owner was chosen (e.g. "fixed", "territory:0"). */
   assignedBy?: string;
+  /**
+   * Deal creates only: provider-neutral stage sentinel. "closed_won" tells the
+   * connector to resolve the target pipeline's REAL closed-won stage id from
+   * the provider's pipeline metadata at apply time (HubSpot: stage with
+   * `metadata.isClosed` true and probability 1) — never by substring-guessing
+   * a stage name. If no such stage is resolvable the operation is skipped.
+   * Plain deal properties (amount, closedate, dealname, …) travel in
+   * `properties` as provider property names, like every other create.
+   */
+  dealStage?: "closed_won";
+  /**
+   * Deal creates only: which pipeline to create the deal in — a pipeline id
+   * or a case-insensitive pipeline label. Absent = the portal's default
+   * pipeline (lowest displayOrder).
+   */
+  dealPipeline?: string;
 };
 
 export type AuditFindingSeverity = "info" | "warning" | "critical";
@@ -505,6 +523,21 @@ export type GtmConnector = {
    * result per input op. Optional: connectors without it use `applyOperation`.
    */
   applyCreateContactsBatch?: (operations: PatchOperation[]) => Promise<PatchOperationResult[]>;
+  /**
+   * Optional bulk apply path for homogeneous operation runs selected by
+   * `applyPatchPlan` (currently consecutive `set_field` ops on one object type
+   * and consecutive `archive_record` ops on one object type). Implementations
+   * MUST return exactly one result per input operation, preserve per-operation
+   * CAS/conflict semantics for field writes, and must not write operations that
+   * would have conflicted under the serial `readField` + `applyOperation` path.
+   * Connectors without it use `applyOperation` per operation.
+   */
+  applyBatch?: (operations: PatchOperation[]) => Promise<PatchOperationResult[]>;
+  /**
+   * Maximum number of operations `applyPatchPlan` should pass to one
+   * `applyBatch` call. Defaults to 200 when unspecified.
+   */
+  applyBatchLimit?: number;
   /**
    * Read the live value of one canonical field, used for compare-and-set:
    * apply orchestration refuses to write over values that drifted since the