@unbrained/pm-cli 2026.7.19 → 2026.7.20

package/dist/sdk/item-transaction.d.ts

@@ -0,0 +1,131 @@
+import { type PmClientFullMutationOptions } from "./runtime.js";
+import { type CommitWorkspaceTransactionOptions, type WorkspaceTransactionJsonValue, type WorkspaceTransactionStep } from "./workspace-transaction.js";
+/**
+ * One atomic item creation inside a bulk mutation batch. The explicit `id`
+ * doubles as the idempotency key: recovery treats an existing item with this id
+ * as the already-applied result, so ids must be stable and transaction-owned.
+ */
+export interface BulkItemCreateMutation {
+    /** Discriminates the creation operation. */
+    op: "create";
+    /** Explicit stable item id (normalized with the configured id_prefix). */
+    id: string;
+    /** Creation options forwarded to the public `create` runtime primitive. */
+    options: PmClientFullMutationOptions;
+}
+/** One atomic item update inside a bulk mutation batch. */
+export interface BulkItemUpdateMutation {
+    /** Discriminates the update operation. */
+    op: "update";
+    /** Target item id. */
+    id: string;
+    /** Update options forwarded to the public `update` runtime primitive. */
+    options: PmClientFullMutationOptions;
+}
+/** One atomic item closure inside a bulk mutation batch. */
+export interface BulkItemCloseMutation {
+    /** Discriminates the close operation. */
+    op: "close";
+    /** Target item id. */
+    id: string;
+    /** Close reason recorded on the item. */
+    reason: string;
+    /** Close options forwarded to the public `close` runtime primitive. */
+    options?: PmClientFullMutationOptions;
+}
+/** Union of the item mutations a bulk transaction batch can carry. */
+export type BulkItemMutation = BulkItemCreateMutation | BulkItemUpdateMutation | BulkItemCloseMutation;
+/** Options accepted by the bulk item-mutation transaction helper. */
+export interface CommitItemMutationsOptions {
+    /** Tracker root that owns the journal and workspace-wide writer lock. */
+    pmRoot: string;
+    /** Stable idempotency key reused to recover an interrupted batch. */
+    transactionId: string;
+    /** Attributable actor recorded in the journal and forwarded to mutations. */
+    author: string;
+    /** Ordered item mutations; compensations run in reverse order. */
+    mutations: readonly BulkItemMutation[];
+    /**
+     * Compensation strategy for created items: `close` (default) preserves the
+     * item and its history with an explanatory close reason, `delete` removes
+     * the item document (its history stream is retained by `pm delete`).
+     */
+    createCompensation?: "close" | "delete";
+    /** Lock lifetime in seconds; size this above the longest expected attempt. */
+    lockTtlSeconds?: number;
+    /** Maximum time to wait for the workspace writer lock. */
+    lockWaitMs?: number;
+    /** Optional transition observer used by telemetry and deterministic crash tests. */
+    onTransition?: CommitWorkspaceTransactionOptions["onTransition"];
+}
+/** Journal-safe outcome recorded for one committed bulk item mutation. */
+export interface BulkItemMutationOutcome {
+    /** Canonical id of the mutated item. */
+    id: string;
+    /** Operation the batch applied for this item. */
+    op: BulkItemMutation["op"];
+}
+/** Successful durable result of a bulk item-mutation transaction. */
+export interface CommitItemMutationsResult {
+    /** Stable transaction identifier. */
+    transactionId: string;
+    /** Final durable state. */
+    status: "committed";
+    /** Whether an interrupted journal was resumed. */
+    recovered: boolean;
+    /** One outcome per mutation, keyed by the derived transaction step id. */
+    results: Record<string, BulkItemMutationOutcome>;
+}
+interface LocatedItemSnapshot {
+    id: string;
+    closedAt: string | undefined;
+    updatedAt: string;
+}
+/** Read one item's transaction-relevant fields, mapping not-found to undefined. */
+declare function readItemSnapshot(pmRoot: string, id: string): Promise<LocatedItemSnapshot | undefined>;
+/** Derive a journal-safe step id from one mutation's position and target. */
+declare function deriveStepId(mutation: BulkItemMutation, index: number): string;
+/** Build the durable history-message marker for one bulk mutation phase. */
+declare function bulkHistoryMarker(transactionId: string, stepId: string, phase: "apply" | "compensate"): string;
+/**
+ * Report whether an update step's forward mutation is durably applied. Updates
+ * cannot be inferred from field values (a moving target), so the applied apply
+ * marker in the item's immutable history is the source of truth; a later
+ * compensate marker means the mutation was rolled back and must re-apply.
+ */
+declare function isUpdateMarkerApplied(pmRoot: string, canonicalId: string, transactionId: string, stepId: string): Promise<boolean>;
+/** Idempotently restore an item to its captured pre-mutation version. */
+declare function compensateByRestore(config: {
+    pmRoot: string;
+    author: string;
+    transactionId: string;
+}, itemId: string, stepId: string, data: WorkspaceTransactionJsonValue | undefined): Promise<void>;
+/** Build the workspace-transaction step for one item creation. */
+declare function buildCreateStep(config: {
+    pmRoot: string;
+    author: string;
+    transactionId: string;
+    createCompensation: "close" | "delete";
+}, mutation: BulkItemCreateMutation, stepId: string): WorkspaceTransactionStep;
+/**
+ * Commit an ordered batch of item create/update/close mutations atomically
+ * (all-or-nothing) in one durable workspace transaction. This is the
+ * high-level companion to `commitWorkspaceTransaction`: instead of
+ * hand-writing `inspect`/`prepareCompensation`/`apply`/`compensate` for the
+ * ubiquitous bulk import/sync case, callers describe the mutations and the
+ * helper wires the crash-consistency contract — exists-by-id inspection for
+ * creates, version-restore compensation for updates and closes, and
+ * close-or-delete compensation for creates. A stable `transactionId` makes
+ * interrupted batches resumable across processes and agents.
+ */
+export declare function commitItemMutations(options: CommitItemMutationsOptions): Promise<CommitItemMutationsResult>;
+/** Public contract for test only item transaction internals, shared with white-box specs. */
+export declare const _testOnlyItemTransaction: {
+    buildCreateStep: typeof buildCreateStep;
+    bulkHistoryMarker: typeof bulkHistoryMarker;
+    compensateByRestore: typeof compensateByRestore;
+    deriveStepId: typeof deriveStepId;
+    isUpdateMarkerApplied: typeof isUpdateMarkerApplied;
+    readItemSnapshot: typeof readItemSnapshot;
+};
+export {};

package/dist/sdk/item-transaction.js

@@ -0,0 +1,280 @@
+/**
+ * @module sdk/item-transaction
+ *
+ * Provides the bulk item-mutation convenience layer over
+ * `commitWorkspaceTransaction`: atomic, resumable create/update/close batches
+ * with correct-by-construction inspection and compensation wiring.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2f005f55-4b5d-5f78-b688-132457f22f99")}catch(e){}}();
+import path from "node:path";
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
+import { readHistoryEntries } from "./history-read.js";
+import { close, create, deleteItem, get, restore, update, } from "./runtime.js";
+import { commitWorkspaceTransaction, } from "./workspace-transaction.js";
+/** Read one item's transaction-relevant fields, mapping not-found to undefined. */
+async function readItemSnapshot(pmRoot, id) {
+    try {
+        const located = await get(id, {}, { pmRoot });
+        const item = located.item;
+        return {
+            id: item.id,
+            closedAt: item.closed_at,
+            updatedAt: item.updated_at,
+        };
+    }
+    catch (error) {
+        if (error instanceof PmCliError &&
+            error.exitCode === EXIT_CODE.NOT_FOUND) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/** Derive a journal-safe step id from one mutation's position and target. */
+function deriveStepId(mutation, index) {
+    const sanitizedTarget = mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu, "_");
+    return `${index + 1}-${mutation.op}-${sanitizedTarget}`;
+}
+/** Build the durable history-message marker for one bulk mutation phase. */
+function bulkHistoryMarker(transactionId, stepId, phase) {
+    return `bulk-item-transaction ${transactionId} ${stepId} ${phase}`;
+}
+/**
+ * Report whether an update step's forward mutation is durably applied. Updates
+ * cannot be inferred from field values (a moving target), so the applied apply
+ * marker in the item's immutable history is the source of truth; a later
+ * compensate marker means the mutation was rolled back and must re-apply.
+ */
+async function isUpdateMarkerApplied(pmRoot, canonicalId, transactionId, stepId) {
+    const entries = await readHistoryEntries(path.join(pmRoot, "history", `${canonicalId}.jsonl`), canonicalId);
+    const applyMarker = bulkHistoryMarker(transactionId, stepId, "apply");
+    const compensateMarker = bulkHistoryMarker(transactionId, stepId, "compensate");
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const message = entries[index].message;
+        if (message === applyMarker) {
+            return true;
+        }
+        if (message === compensateMarker) {
+            return false;
+        }
+    }
+    return false;
+}
+/** Capture the restore target used to compensate an update or close mutation. */
+async function prepareRestoreCompensation(pmRoot, mutation) {
+    const snapshot = await readItemSnapshot(pmRoot, mutation.id);
+    if (snapshot?.updatedAt === undefined) {
+        throw new PmCliError(`Bulk ${mutation.op} target ${mutation.id} does not exist or has no restorable version`, EXIT_CODE.NOT_FOUND);
+    }
+    return { target_updated_at: snapshot.updatedAt };
+}
+/** Idempotently restore an item to its captured pre-mutation version. */
+async function compensateByRestore(config, itemId, stepId, data) {
+    const target = data !== null && typeof data === "object" && !Array.isArray(data)
+        ? data.target_updated_at
+        : undefined;
+    if (typeof target !== "string") {
+        return;
+    }
+    if ((await readItemSnapshot(config.pmRoot, itemId)) === undefined) {
+        return;
+    }
+    await restore(itemId, target, {
+        force: true,
+        author: config.author,
+        message: bulkHistoryMarker(config.transactionId, stepId, "compensate"),
+    }, { pmRoot: config.pmRoot });
+}
+/** Build the workspace-transaction step for one item creation. */
+function buildCreateStep(config, mutation, stepId) {
+    return {
+        id: stepId,
+        async inspect() {
+            const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
+            if (snapshot === undefined) {
+                return { state: "pending" };
+            }
+            return { state: "applied", result: { id: snapshot.id, op: "create" } };
+        },
+        async apply() {
+            const created = await create({ ...mutation.options, author: config.author, id: mutation.id }, { pmRoot: config.pmRoot });
+            const createdItem = created.item;
+            return { id: String(createdItem.id), op: "create" };
+        },
+        async compensate() {
+            const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
+            if (snapshot === undefined) {
+                return;
+            }
+            if (config.createCompensation === "delete") {
+                await deleteItem(mutation.id, {
+                    force: true,
+                    author: config.author,
+                    message: `Compensate interrupted bulk transaction ${config.transactionId}`,
+                }, { pmRoot: config.pmRoot });
+                return;
+            }
+            if (snapshot.closedAt !== undefined) {
+                return;
+            }
+            await close(mutation.id, `Compensated: interrupted bulk transaction ${config.transactionId}`, { force: true, author: config.author }, { pmRoot: config.pmRoot });
+        },
+    };
+}
+/** Build the workspace-transaction step for one item update. */
+function buildUpdateStep(config, mutation, stepId) {
+    return {
+        id: stepId,
+        async inspect() {
+            const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
+            if (snapshot === undefined) {
+                return { state: "pending" };
+            }
+            const applied = await isUpdateMarkerApplied(config.pmRoot, snapshot.id, config.transactionId, stepId);
+            if (!applied) {
+                return { state: "pending" };
+            }
+            return { state: "applied", result: { id: snapshot.id, op: "update" } };
+        },
+        async prepareCompensation() {
+            return prepareRestoreCompensation(config.pmRoot, mutation);
+        },
+        async apply() {
+            const updated = await update(mutation.id, {
+                ...mutation.options,
+                author: config.author,
+                message: bulkHistoryMarker(config.transactionId, stepId, "apply"),
+            }, { pmRoot: config.pmRoot });
+            const updatedItem = updated.item;
+            return { id: String(updatedItem.id), op: "update" };
+        },
+        async compensate(data) {
+            await compensateByRestore(config, mutation.id, stepId, data);
+        },
+    };
+}
+/** Build the workspace-transaction step for one item closure. */
+function buildCloseStep(config, mutation, stepId) {
+    return {
+        id: stepId,
+        // An already-terminal target counts as applied: closing it again would
+        // fight legitimate prior closure, and recovery must adopt completed work.
+        async inspect() {
+            const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
+            if (snapshot?.closedAt === undefined) {
+                return { state: "pending" };
+            }
+            return { state: "applied", result: { id: snapshot.id, op: "close" } };
+        },
+        async prepareCompensation() {
+            return prepareRestoreCompensation(config.pmRoot, mutation);
+        },
+        async apply() {
+            const closed = await close(mutation.id, mutation.reason, { ...mutation.options, author: config.author }, { pmRoot: config.pmRoot });
+            const closedItem = closed.item;
+            return { id: String(closedItem.id), op: "close" };
+        },
+        async compensate(data) {
+            await compensateByRestore(config, mutation.id, stepId, data);
+        },
+    };
+}
+/** Convert one validated bulk mutation into its workspace-transaction step. */
+function buildStepForMutation(config, mutation, index) {
+    const stepId = deriveStepId(mutation, index);
+    if (mutation.op === "create") {
+        return buildCreateStep(config, mutation, stepId);
+    }
+    if (mutation.op === "update") {
+        return buildUpdateStep(config, mutation, stepId);
+    }
+    return buildCloseStep(config, mutation, stepId);
+}
+/** Reject malformed bulk mutation rows before any journal or lock work. */
+function assertValidBulkMutation(mutation, index) {
+    if (mutation === null ||
+        typeof mutation !== "object" ||
+        Array.isArray(mutation)) {
+        throw new TypeError(`Bulk mutation ${index + 1} must be an object`);
+    }
+    if (!["create", "update", "close"].includes(mutation.op)) {
+        throw new TypeError(`Bulk mutation ${index + 1} op must be create, update, or close`);
+    }
+    if (typeof mutation.id !== "string" || mutation.id.trim().length === 0) {
+        throw new TypeError(`Bulk mutation ${index + 1} requires a non-empty id`);
+    }
+    if (mutation.op === "close" &&
+        (typeof mutation.reason !== "string" || mutation.reason.trim().length === 0)) {
+        throw new TypeError(`Bulk close mutation ${index + 1} requires a non-empty reason`);
+    }
+}
+/**
+ * Commit an ordered batch of item create/update/close mutations atomically
+ * (all-or-nothing) in one durable workspace transaction. This is the
+ * high-level companion to `commitWorkspaceTransaction`: instead of
+ * hand-writing `inspect`/`prepareCompensation`/`apply`/`compensate` for the
+ * ubiquitous bulk import/sync case, callers describe the mutations and the
+ * helper wires the crash-consistency contract — exists-by-id inspection for
+ * creates, version-restore compensation for updates and closes, and
+ * close-or-delete compensation for creates. A stable `transactionId` makes
+ * interrupted batches resumable across processes and agents.
+ */
+export async function commitItemMutations(options) {
+    const mutations = [...options.mutations];
+    if (mutations.length === 0) {
+        throw new TypeError("Bulk item transaction requires at least one mutation");
+    }
+    for (const [index, mutation] of mutations.entries()) {
+        assertValidBulkMutation(mutation, index);
+    }
+    const createCompensation = options.createCompensation ?? "close";
+    if (!["close", "delete"].includes(createCompensation)) {
+        throw new TypeError("Bulk item transaction createCompensation must be close or delete");
+    }
+    const stepConfig = {
+        pmRoot: options.pmRoot,
+        author: options.author,
+        transactionId: options.transactionId,
+        createCompensation,
+    };
+    const committed = await commitWorkspaceTransaction({
+        pmRoot: options.pmRoot,
+        transactionId: options.transactionId,
+        author: options.author,
+        steps: mutations.map((mutation, index) => buildStepForMutation(stepConfig, mutation, index)),
+        ...(options.lockTtlSeconds === undefined
+            ? {}
+            : { lockTtlSeconds: options.lockTtlSeconds }),
+        ...(options.lockWaitMs === undefined
+            ? {}
+            : { lockWaitMs: options.lockWaitMs }),
+        ...(options.onTransition === undefined
+            ? {}
+            : { onTransition: options.onTransition }),
+    });
+    const results = {};
+    for (const [stepId, value] of Object.entries(committed.results)) {
+        // Journal values round-trip this module's own step outputs, which are
+        // always {id, op} objects — the cast restores the concrete outcome shape.
+        results[stepId] = value;
+    }
+    return {
+        transactionId: committed.transactionId,
+        status: "committed",
+        recovered: committed.recovered,
+        results,
+    };
+}
+/** Public contract for test only item transaction internals, shared with white-box specs. */
+export const _testOnlyItemTransaction = {
+    buildCreateStep,
+    bulkHistoryMarker,
+    compensateByRestore,
+    deriveStepId,
+    isUpdateMarkerApplied,
+    readItemSnapshot,
+};
+//# sourceMappingURL=item-transaction.js.map
+//# debugId=2f005f55-4b5d-5f78-b688-132457f22f99

package/dist/sdk/item-transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-transaction.js","sources":["sdk/item-transaction.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/item-transaction\n *\n * Provides the bulk item-mutation convenience layer over\n * `commitWorkspaceTransaction`: atomic, resumable create/update/close batches\n * with correct-by-construction inspection and compensation wiring.\n */\nimport path from \"node:path\";\nimport { EXIT_CODE } from \"../core/shared/constants.js\";\nimport { PmCliError } from \"../core/shared/errors.js\";\nimport { readHistoryEntries } from \"./history-read.js\";\nimport {\n  close,\n  create,\n  deleteItem,\n  get,\n  restore,\n  update,\n  type PmClientFullMutationOptions,\n} from \"./runtime.js\";\nimport {\n  commitWorkspaceTransaction,\n  type CommitWorkspaceTransactionOptions,\n  type WorkspaceTransactionJsonValue,\n  type WorkspaceTransactionStep,\n  type WorkspaceTransactionStepInspection,\n} from \"./workspace-transaction.js\";\n\n/**\n * One atomic item creation inside a bulk mutation batch. The explicit `id`\n * doubles as the idempotency key: recovery treats an existing item with this id\n * as the already-applied result, so ids must be stable and transaction-owned.\n */\nexport interface BulkItemCreateMutation {\n  /** Discriminates the creation operation. */\n  op: \"create\";\n  /** Explicit stable item id (normalized with the configured id_prefix). */\n  id: string;\n  /** Creation options forwarded to the public `create` runtime primitive. */\n  options: PmClientFullMutationOptions;\n}\n\n/** One atomic item update inside a bulk mutation batch. */\nexport interface BulkItemUpdateMutation {\n  /** Discriminates the update operation. */\n  op: \"update\";\n  /** Target item id. */\n  id: string;\n  /** Update options forwarded to the public `update` runtime primitive. */\n  options: PmClientFullMutationOptions;\n}\n\n/** One atomic item closure inside a bulk mutation batch. */\nexport interface BulkItemCloseMutation {\n  /** Discriminates the close operation. */\n  op: \"close\";\n  /** Target item id. */\n  id: string;\n  /** Close reason recorded on the item. */\n  reason: string;\n  /** Close options forwarded to the public `close` runtime primitive. */\n  options?: PmClientFullMutationOptions;\n}\n\n/** Union of the item mutations a bulk transaction batch can carry. */\nexport type BulkItemMutation =\n  | BulkItemCreateMutation\n  | BulkItemUpdateMutation\n  | BulkItemCloseMutation;\n\n/** Options accepted by the bulk item-mutation transaction helper. */\nexport interface CommitItemMutationsOptions {\n  /** Tracker root that owns the journal and workspace-wide writer lock. */\n  pmRoot: string;\n  /** Stable idempotency key reused to recover an interrupted batch. */\n  transactionId: string;\n  /** Attributable actor recorded in the journal and forwarded to mutations. */\n  author: string;\n  /** Ordered item mutations; compensations run in reverse order. */\n  mutations: readonly BulkItemMutation[];\n  /**\n   * Compensation strategy for created items: `close` (default) preserves the\n   * item and its history with an explanatory close reason, `delete` removes\n   * the item document (its history stream is retained by `pm delete`).\n   */\n  createCompensation?: \"close\" | \"delete\";\n  /** Lock lifetime in seconds; size this above the longest expected attempt. */\n  lockTtlSeconds?: number;\n  /** Maximum time to wait for the workspace writer lock. */\n  lockWaitMs?: number;\n  /** Optional transition observer used by telemetry and deterministic crash tests. */\n  onTransition?: CommitWorkspaceTransactionOptions[\"onTransition\"];\n}\n\n/** Journal-safe outcome recorded for one committed bulk item mutation. */\nexport interface BulkItemMutationOutcome {\n  /** Canonical id of the mutated item. */\n  id: string;\n  /** Operation the batch applied for this item. */\n  op: BulkItemMutation[\"op\"];\n}\n\n/** Successful durable result of a bulk item-mutation transaction. */\nexport interface CommitItemMutationsResult {\n  /** Stable transaction identifier. */\n  transactionId: string;\n  /** Final durable state. */\n  status: \"committed\";\n  /** Whether an interrupted journal was resumed. */\n  recovered: boolean;\n  /** One outcome per mutation, keyed by the derived transaction step id. */\n  results: Record<string, BulkItemMutationOutcome>;\n}\n\ninterface LocatedItemSnapshot {\n  id: string;\n  closedAt: string | undefined;\n  updatedAt: string;\n}\n\n/** Read one item's transaction-relevant fields, mapping not-found to undefined. */\nasync function readItemSnapshot(\n  pmRoot: string,\n  id: string,\n): Promise<LocatedItemSnapshot | undefined> {\n  try {\n    const located = await get(id, {}, { pmRoot });\n    const item = located.item as {\n      id: string;\n      closed_at?: string;\n      updated_at: string;\n    };\n    return {\n      id: item.id,\n      closedAt: item.closed_at,\n      updatedAt: item.updated_at,\n    };\n  } catch (error) {\n    if (\n      error instanceof PmCliError &&\n      error.exitCode === EXIT_CODE.NOT_FOUND\n    ) {\n      return undefined;\n    }\n    throw error;\n  }\n}\n\n/** Derive a journal-safe step id from one mutation's position and target. */\nfunction deriveStepId(mutation: BulkItemMutation, index: number): string {\n  const sanitizedTarget = mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu, \"_\");\n  return `${index + 1}-${mutation.op}-${sanitizedTarget}`;\n}\n\n/** Build the durable history-message marker for one bulk mutation phase. */\nfunction bulkHistoryMarker(\n  transactionId: string,\n  stepId: string,\n  phase: \"apply\" | \"compensate\",\n): string {\n  return `bulk-item-transaction ${transactionId} ${stepId} ${phase}`;\n}\n\n/**\n * Report whether an update step's forward mutation is durably applied. Updates\n * cannot be inferred from field values (a moving target), so the applied apply\n * marker in the item's immutable history is the source of truth; a later\n * compensate marker means the mutation was rolled back and must re-apply.\n */\nasync function isUpdateMarkerApplied(\n  pmRoot: string,\n  canonicalId: string,\n  transactionId: string,\n  stepId: string,\n): Promise<boolean> {\n  const entries = await readHistoryEntries(\n    path.join(pmRoot, \"history\", `${canonicalId}.jsonl`),\n    canonicalId,\n  );\n  const applyMarker = bulkHistoryMarker(transactionId, stepId, \"apply\");\n  const compensateMarker = bulkHistoryMarker(transactionId, stepId, \"compensate\");\n  for (let index = entries.length - 1; index >= 0; index -= 1) {\n    const message = entries[index].message;\n    if (message === applyMarker) {\n      return true;\n    }\n    if (message === compensateMarker) {\n      return false;\n    }\n  }\n  return false;\n}\n\n/** Capture the restore target used to compensate an update or close mutation. */\nasync function prepareRestoreCompensation(\n  pmRoot: string,\n  mutation: BulkItemMutation,\n): Promise<WorkspaceTransactionJsonValue> {\n  const snapshot = await readItemSnapshot(pmRoot, mutation.id);\n  if (snapshot?.updatedAt === undefined) {\n    throw new PmCliError(\n      `Bulk ${mutation.op} target ${mutation.id} does not exist or has no restorable version`,\n      EXIT_CODE.NOT_FOUND,\n    );\n  }\n  return { target_updated_at: snapshot.updatedAt };\n}\n\n/** Idempotently restore an item to its captured pre-mutation version. */\nasync function compensateByRestore(\n  config: { pmRoot: string; author: string; transactionId: string },\n  itemId: string,\n  stepId: string,\n  data: WorkspaceTransactionJsonValue | undefined,\n): Promise<void> {\n  const target =\n    data !== null && typeof data === \"object\" && !Array.isArray(data)\n      ? data.target_updated_at\n      : undefined;\n  if (typeof target !== \"string\") {\n    return;\n  }\n  if ((await readItemSnapshot(config.pmRoot, itemId)) === undefined) {\n    return;\n  }\n  await restore(\n    itemId,\n    target,\n    {\n      force: true,\n      author: config.author,\n      message: bulkHistoryMarker(config.transactionId, stepId, \"compensate\"),\n    },\n    { pmRoot: config.pmRoot },\n  );\n}\n\n/** Build the workspace-transaction step for one item creation. */\nfunction buildCreateStep(\n  config: {\n    pmRoot: string;\n    author: string;\n    transactionId: string;\n    createCompensation: \"close\" | \"delete\";\n  },\n  mutation: BulkItemCreateMutation,\n  stepId: string,\n): WorkspaceTransactionStep {\n  return {\n    id: stepId,\n    async inspect(): Promise<WorkspaceTransactionStepInspection> {\n      const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);\n      if (snapshot === undefined) {\n        return { state: \"pending\" };\n      }\n      return { state: \"applied\", result: { id: snapshot.id, op: \"create\" } };\n    },\n    async apply(): Promise<WorkspaceTransactionJsonValue> {\n      const created = await create(\n        { ...mutation.options, author: config.author, id: mutation.id },\n        { pmRoot: config.pmRoot },\n      );\n      const createdItem = created.item as Record<string, unknown>;\n      return { id: String(createdItem.id), op: \"create\" };\n    },\n    async compensate(): Promise<void> {\n      const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);\n      if (snapshot === undefined) {\n        return;\n      }\n      if (config.createCompensation === \"delete\") {\n        await deleteItem(\n          mutation.id,\n          {\n            force: true,\n            author: config.author,\n            message: `Compensate interrupted bulk transaction ${config.transactionId}`,\n          },\n          { pmRoot: config.pmRoot },\n        );\n        return;\n      }\n      if (snapshot.closedAt !== undefined) {\n        return;\n      }\n      await close(\n        mutation.id,\n        `Compensated: interrupted bulk transaction ${config.transactionId}`,\n        { force: true, author: config.author },\n        { pmRoot: config.pmRoot },\n      );\n    },\n  };\n}\n\n/** Build the workspace-transaction step for one item update. */\nfunction buildUpdateStep(\n  config: { pmRoot: string; author: string; transactionId: string },\n  mutation: BulkItemUpdateMutation,\n  stepId: string,\n): WorkspaceTransactionStep {\n  return {\n    id: stepId,\n    async inspect(): Promise<WorkspaceTransactionStepInspection> {\n      const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);\n      if (snapshot === undefined) {\n        return { state: \"pending\" };\n      }\n      const applied = await isUpdateMarkerApplied(\n        config.pmRoot,\n        snapshot.id,\n        config.transactionId,\n        stepId,\n      );\n      if (!applied) {\n        return { state: \"pending\" };\n      }\n      return { state: \"applied\", result: { id: snapshot.id, op: \"update\" } };\n    },\n    async prepareCompensation(): Promise<WorkspaceTransactionJsonValue> {\n      return prepareRestoreCompensation(config.pmRoot, mutation);\n    },\n    async apply(): Promise<WorkspaceTransactionJsonValue> {\n      const updated = await update(\n        mutation.id,\n        {\n          ...mutation.options,\n          author: config.author,\n          message: bulkHistoryMarker(config.transactionId, stepId, \"apply\"),\n        },\n        { pmRoot: config.pmRoot },\n      );\n      const updatedItem = updated.item as Record<string, unknown>;\n      return { id: String(updatedItem.id), op: \"update\" };\n    },\n    async compensate(\n      data?: WorkspaceTransactionJsonValue,\n    ): Promise<void> {\n      await compensateByRestore(config, mutation.id, stepId, data);\n    },\n  };\n}\n\n/** Build the workspace-transaction step for one item closure. */\nfunction buildCloseStep(\n  config: { pmRoot: string; author: string; transactionId: string },\n  mutation: BulkItemCloseMutation,\n  stepId: string,\n): WorkspaceTransactionStep {\n  return {\n    id: stepId,\n    // An already-terminal target counts as applied: closing it again would\n    // fight legitimate prior closure, and recovery must adopt completed work.\n    async inspect(): Promise<WorkspaceTransactionStepInspection> {\n      const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);\n      if (snapshot?.closedAt === undefined) {\n        return { state: \"pending\" };\n      }\n      return { state: \"applied\", result: { id: snapshot.id, op: \"close\" } };\n    },\n    async prepareCompensation(): Promise<WorkspaceTransactionJsonValue> {\n      return prepareRestoreCompensation(config.pmRoot, mutation);\n    },\n    async apply(): Promise<WorkspaceTransactionJsonValue> {\n      const closed = await close(\n        mutation.id,\n        mutation.reason,\n        { ...mutation.options, author: config.author },\n        { pmRoot: config.pmRoot },\n      );\n      const closedItem = closed.item as Record<string, unknown>;\n      return { id: String(closedItem.id), op: \"close\" };\n    },\n    async compensate(\n      data?: WorkspaceTransactionJsonValue,\n    ): Promise<void> {\n      await compensateByRestore(config, mutation.id, stepId, data);\n    },\n  };\n}\n\n/** Convert one validated bulk mutation into its workspace-transaction step. */\nfunction buildStepForMutation(\n  config: {\n    pmRoot: string;\n    author: string;\n    transactionId: string;\n    createCompensation: \"close\" | \"delete\";\n  },\n  mutation: BulkItemMutation,\n  index: number,\n): WorkspaceTransactionStep {\n  const stepId = deriveStepId(mutation, index);\n  if (mutation.op === \"create\") {\n    return buildCreateStep(config, mutation, stepId);\n  }\n  if (mutation.op === \"update\") {\n    return buildUpdateStep(config, mutation, stepId);\n  }\n  return buildCloseStep(config, mutation, stepId);\n}\n\n/** Reject malformed bulk mutation rows before any journal or lock work. */\nfunction assertValidBulkMutation(\n  mutation: BulkItemMutation,\n  index: number,\n): void {\n  if (\n    mutation === null ||\n    typeof mutation !== \"object\" ||\n    Array.isArray(mutation)\n  ) {\n    throw new TypeError(`Bulk mutation ${index + 1} must be an object`);\n  }\n  if (![\"create\", \"update\", \"close\"].includes(mutation.op)) {\n    throw new TypeError(\n      `Bulk mutation ${index + 1} op must be create, update, or close`,\n    );\n  }\n  if (typeof mutation.id !== \"string\" || mutation.id.trim().length === 0) {\n    throw new TypeError(`Bulk mutation ${index + 1} requires a non-empty id`);\n  }\n  if (\n    mutation.op === \"close\" &&\n    (typeof mutation.reason !== \"string\" || mutation.reason.trim().length === 0)\n  ) {\n    throw new TypeError(\n      `Bulk close mutation ${index + 1} requires a non-empty reason`,\n    );\n  }\n}\n\n/**\n * Commit an ordered batch of item create/update/close mutations atomically\n * (all-or-nothing) in one durable workspace transaction. This is the\n * high-level companion to `commitWorkspaceTransaction`: instead of\n * hand-writing `inspect`/`prepareCompensation`/`apply`/`compensate` for the\n * ubiquitous bulk import/sync case, callers describe the mutations and the\n * helper wires the crash-consistency contract — exists-by-id inspection for\n * creates, version-restore compensation for updates and closes, and\n * close-or-delete compensation for creates. A stable `transactionId` makes\n * interrupted batches resumable across processes and agents.\n */\nexport async function commitItemMutations(\n  options: CommitItemMutationsOptions,\n): Promise<CommitItemMutationsResult> {\n  const mutations = [...options.mutations];\n  if (mutations.length === 0) {\n    throw new TypeError(\"Bulk item transaction requires at least one mutation\");\n  }\n  for (const [index, mutation] of mutations.entries()) {\n    assertValidBulkMutation(mutation, index);\n  }\n  const createCompensation = options.createCompensation ?? \"close\";\n  if (![\"close\", \"delete\"].includes(createCompensation)) {\n    throw new TypeError(\n      \"Bulk item transaction createCompensation must be close or delete\",\n    );\n  }\n  const stepConfig = {\n    pmRoot: options.pmRoot,\n    author: options.author,\n    transactionId: options.transactionId,\n    createCompensation,\n  };\n  const committed = await commitWorkspaceTransaction({\n    pmRoot: options.pmRoot,\n    transactionId: options.transactionId,\n    author: options.author,\n    steps: mutations.map((mutation, index) =>\n      buildStepForMutation(stepConfig, mutation, index),\n    ),\n    ...(options.lockTtlSeconds === undefined\n      ? {}\n      : { lockTtlSeconds: options.lockTtlSeconds }),\n    ...(options.lockWaitMs === undefined\n      ? {}\n      : { lockWaitMs: options.lockWaitMs }),\n    ...(options.onTransition === undefined\n      ? {}\n      : { onTransition: options.onTransition }),\n  });\n  const results: Record<string, BulkItemMutationOutcome> = {};\n  for (const [stepId, value] of Object.entries(committed.results)) {\n    // Journal values round-trip this module's own step outputs, which are\n    // always {id, op} objects — the cast restores the concrete outcome shape.\n    results[stepId] = value as unknown as BulkItemMutationOutcome;\n  }\n  return {\n    transactionId: committed.transactionId,\n    status: \"committed\",\n    recovered: committed.recovered,\n    results,\n  };\n}\n\n/** Public contract for test only item transaction internals, shared with white-box specs. */\nexport const _testOnlyItemTransaction = {\n  buildCreateStep,\n  bulkHistoryMarker,\n  compensateByRestore,\n  deriveStepId,\n  isUpdateMarkerApplied,\n  readItemSnapshot,\n};\n"],"names":[],"mappings":"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","debugId":"2f005f55-4b5d-5f78-b688-132457f22f99"}

package/dist/sdk/merge/driver.d.ts

@@ -0,0 +1,75 @@
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { type MergePreferredSide } from "./three-way.js";
+/** Supported values accepted by the merge driver artifact contract across CLI, SDK, and MCP surfaces. */
+export declare const MERGE_DRIVER_ARTIFACT_VALUES: readonly ["item", "history", "relationship", "json"];
+/** Restricts merge driver artifact values accepted by command, SDK, and storage contracts. */
+export type MergeDriverArtifact = (typeof MERGE_DRIVER_ARTIFACT_VALUES)[number];
+/** Documents the merge driver options payload exchanged by command, SDK, and package integrations. */
+export interface MergeDriverOptions {
+    /** Artifact class being merged: item document, history JSONL stream, relationship event JSONL store, or key-level JSON config. */
+    artifact: string;
+    /** Path to the common-ancestor version (git %O). */
+    basePath: string;
+    /** Path to the current-branch version (git %A); also the default output path per the git merge-driver protocol. */
+    oursPath: string;
+    /** Path to the other-branch version (git %B). */
+    theirsPath: string;
+    /** Optional explicit output path overriding the git default of writing to the ours path. */
+    outputPath?: string;
+    /** Original repository-relative item path supplied by Git as `%P`, used to detect item format when temporary side paths lack extensions. */
+    itemPath?: string;
+    /** Side that wins unresolvable conflicts (default "ours"). */
+    prefer?: string;
+}
+/** Documents the merge driver result payload exchanged by command, SDK, and package integrations. */
+export interface MergeDriverResult {
+    /** Whether the merge completed without unresolvable conflicts. */
+    ok: boolean;
+    /** Artifact class that was merged. */
+    artifact: MergeDriverArtifact;
+    /** Path the merged content was written to. */
+    output_path: string;
+    /** Side unresolvable conflicts were resolved toward. */
+    preferred: MergePreferredSide;
+    /** Unresolvable conflict labels: metadata field names (item), dotted key paths (json). Empty for history merges. */
+    conflicts: string[];
+    /** History-merge strategy and entry accounting; present only for the history artifact. */
+    history?: {
+        strategy: string;
+        common_entries: number;
+        entries_from_ours: number;
+        entries_from_theirs: number;
+        entries_total: number;
+        reanchored: boolean;
+    };
+    /** Relationship-event-merge strategy and accounting; present only for the relationship artifact. */
+    relationship?: {
+        strategy: string;
+        common_entries: number;
+        entries_from_ours: number;
+        entries_from_theirs: number;
+        entries_total: number;
+        reanchored: boolean;
+    };
+    /** Item-merge field accounting; present only for the item artifact. */
+    item?: {
+        fields_from_theirs: string[];
+        union_fields: string[];
+    };
+    /** JSON-merge key accounting; present only for the json artifact. */
+    json?: {
+        paths_from_theirs: string[];
+    };
+    /** Guidance for resolving remaining conflicts or verifying the merged workspace. */
+    guidance: string[];
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/**
+ * Execute one git merge-driver invocation for a tracker artifact. Reads the
+ * three per-side versions, applies the artifact's field-aware merge semantics,
+ * writes the merged content (parseable even when conflicted) to the output
+ * path, and reports remaining conflicts so the CLI can exit non-zero and let
+ * git mark the path unmerged.
+ */
+export declare function runMergeDriver(options: MergeDriverOptions, global: GlobalOptions): Promise<MergeDriverResult>;