pm-csv 2026.10.4 → 2026.10.12

package/dist/index.js

@@ -1,8 +1,9 @@
 import { readFileSync, writeFileSync, createReadStream } from "node:fs";
-import { resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { certifyCompleteListResult, inspectCompleteListResult } from "@unbrained/pm-cli/sdk";
+import { certifyCompleteListResult, inspectCompleteListResult, runWorkspaceTransactionGc } from "@unbrained/pm-cli/sdk";
+import { captureUpdateCompensation, compensateUpdate, inspectUpdate, UPDATE_COMPENSATION_VERSION } from "./atomic-update.js";
 // ---------------------------------------------------------------------------
 // Error contract
 // ---------------------------------------------------------------------------
@@ -1210,19 +1211,55 @@ export function atomicTransactionId(filePath, opts = {}) {
     const { headers: rawHeaders, dataRows } = readCSVFile(filePath, resolveDelimiter(opts.delimiter), opts.encoding ?? "utf-8", opts.skipHeaders ?? false);
     return deriveTransactionId(resolve(filePath), fingerprintContent(rawHeaders, dataRows));
 }
+/** Bind a CSV step to its format, operation, target, and original row. */
+function atomicStepId(rowIndex, existingId) {
+    const operation = existingId ? `update-${existingId}` : "create";
+    return `csv-import-v${UPDATE_COMPENSATION_VERSION}-${operation}-row-${rowIndex}`;
+}
+/**
+ * Recover the original plan's update targets and create roles from SDK journal
+ * step identities. Mutable CSV key tags cannot retarget an interrupted update
+ * or turn a previously planned create into an update. Incompatible identities
+ * refuse replay before any mutation; the SDK validates the remaining journal.
+ * The public read-only inventory supplies the path, including after SDK layout
+ * changes. Infinite retention and dry-run prevent recovery receipts being pruned.
+ */
+async function loadAtomicBindings(pmRoot, transactionId) {
+    const bindings = new Map();
+    const inventory = await runWorkspaceTransactionGc(pmRoot, { dryRun: true, retentionDays: Infinity });
+    const entry = inventory.entries.find(candidate => basename(candidate.file) === `${transactionId}.json`);
+    if (!entry)
+        return bindings;
+    const journal = JSON.parse(readFileSync(resolve(pmRoot, entry.file), "utf8"));
+    if (journal === null || typeof journal !== "object" || Array.isArray(journal)
+        || !("stepIds" in journal) || !Array.isArray(journal.stepIds)
+        || !journal.stepIds.every((id) => typeof id === "string")) {
+        throw new Error(`Workspace transaction ${transactionId} journal does not match the supplied plan: incompatible CSV step identity.`);
+    }
+    const pattern = new RegExp(String.raw `^csv-import-v${UPDATE_COMPENSATION_VERSION}-(?:create|update-(.+))-row-(\d+)$`);
+    for (const id of journal.stepIds) {
+        const match = pattern.exec(id);
+        if (!match)
+            throw new Error(`Workspace transaction ${transactionId} journal does not match the supplied plan: incompatible CSV step identity.`);
+        bindings.set(Number(match[2]), match[1]);
+    }
+    return bindings;
+}
 /**
  * Load every item stamped with this transaction's per-row ownership marker
  * (`csv-txrow:<transactionId>#<rowIndex>`) and build a single lookup the step
  * `inspect()` uses to detect rows already applied by a prior (interrupted) run:
  *   - byRowIndex: rowIndex -> item id
  *
- * The per-row marker is the source of truth for resume/compensation: it makes
+ * For creates, the per-row marker is the source of truth for resume: it makes
  * matching per-row-precise, so a CSV with duplicate titles or duplicate keys
  * can never trick inspect() into skipping the wrong row. The batch-level
  * `csv-tx:<transactionId>` marker is also stamped (handy for scanning) but is
  * NOT used for matching. Only items carrying a per-row marker for THIS
  * transaction are included, so pre-existing items this transaction never
- * touched are never mistaken for already-applied steps.
+ * touched are never mistaken for already-applied steps. Updates additionally
+ * inspect immutable history and bind their targets through journal step ids,
+ * so removing mutable tags cannot retarget an interrupted update.
  *
  * Presence of the row marker — NOT item status — is the applied signal. A row
  * whose CSV `status` is `closed`/`canceled` is legitimately imported as a
@@ -1366,12 +1403,8 @@ function compensateCreate(pmRoot, id, markers = [], reason = "atomic csv import
     if (status === undefined)
         return; // absent or unverified; never invent closure
     if (status !== "closed") {
-        // Compensation is an internal rollback, not a user closure: it must
-        // reliably undo the create regardless of closure-validation governance, so
-        // it bypasses `--validate-close` (off). `require_close_reason` still applies
-        // and is satisfied by `reason`. Used by both the atomic transaction path
-        // (rollback) and the non-atomic `upsertCreate` close-failure path.
-        const closeResult = spawnSync("pm", ["--path", pmRoot, "close", id, "--reason", reason, "--validate-close", "off"], { encoding: "utf-8", maxBuffer: pmListMaxBuffer() });
+        // Compensation records the rollback outcome through the normal close contract.
+        const closeResult = spawnSync("pm", csvCloseArgs(pmRoot, id, reason, "The failed CSV import leaves no active created item.", "Closing the created item as CSV import compensation."), { encoding: "utf-8", maxBuffer: pmListMaxBuffer() });
         if (closeResult.status !== 0) {
             // A non-zero receipt is not proof either way: the close may have persisted
             // before its receipt failed. Re-read the item and clean markers only with
@@ -1397,8 +1430,8 @@ function compensateCreate(pmRoot, id, markers = [], reason = "atomic csv import
  * {@link ImportResult} as the non-atomic path is returned (counts derived from
  * the committed step results). On failure the coordinator attempts reverse-
  * order compensation, but callers receive a conservative reconciliation
- * warning because create cleanup is best-effort and updates to pre-existing
- * items are intentionally not reverted. An interrupted run resumes from the
+ * warning because create cleanup is best-effort and concurrent writers can
+ * prevent safe update compensation. An interrupted run resumes from the
  * durable journal (inspect() skips already applied rows).
  */
 async function importCSVAtomic(pmRoot, filePath, opts) {
@@ -1427,6 +1460,7 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
     const rowTagFor = (rowIndex) => `${TX_ROW_TAG_PREFIX}${transactionId}${TX_ROW_TAG_SEPARATOR}${rowIndex}`;
     // Detect rows a prior interrupted run already applied (resumability) plus
     // the dedup index for --key upsert decisions, both from one fresh scan.
+    const bindings = await loadAtomicBindings(pmRoot, transactionId);
     const applied = loadAppliedByTransaction(pmRoot, transactionId);
     const keyIndex = opts.keyField ? loadKeyIndex(pmRoot) : new Map();
     // In-batch duplicate-KEY guard: keys already claimed by an earlier planned
@@ -1464,7 +1498,8 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
             result.skipped++;
             continue;
         }
-        const existingId = normalizedKey ? keyIndex.get(normalizedKey) : undefined;
+        const existingId = bindings.has(rowIndex) ? bindings.get(rowIndex)
+            : normalizedKey ? keyIndex.get(normalizedKey) : undefined;
         if (normalizedKey && !existingId)
             claimedKeys.set(normalizedKey, rowIndex);
         planned.push({ rowIndex, lineNo, parsed, keyValue, existingId, isUpdate: Boolean(existingId) });
@@ -1474,9 +1509,8 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
     //     path (parity) plus the csv-tx batch marker AND the per-row marker;
     //     compensate() closes the created id.
     //   - update (--key match): apply() updates the pre-existing item and stamps
-    //     both markers; compensate() is a no-op (an arbitrary update cannot be
-    //     safely reverted without capturing prior state; best-effort
-    //     compensation is therefore scoped to creates).
+    //     both markers; prepareCompensation captures prior state before apply;
+    //     compensate restores it under the item lock after a history check.
     //
     // Resume/compensation matching is per-row-precise via the per-row marker
     // (csv-txrow:<transactionId>#<rowIndex>), so duplicate titles or duplicate
@@ -1488,11 +1522,14 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
     // left over from a prior interrupted run (which the pre-run `applied` lookup
     // already detects).
     const steps = planned.map((row) => {
-        const stepId = `csv-import-row-${row.rowIndex}`;
+        const stepId = atomicStepId(row.rowIndex, row.existingId);
         const rowTag = rowTagFor(row.rowIndex);
         // Set by apply() in this run; undefined before that or on a fresh resume.
         let appliedId;
         const inspect = async () => {
+            if (row.isUpdate) {
+                return inspectUpdate(pmRoot, row.existingId, rowTag, row.parsed.status === "closed" || row.parsed.status === "canceled");
+            }
             // A step applied earlier in THIS run (apply() captured the id).
             if (appliedId)
                 return { state: "applied", result: appliedId };
@@ -1507,7 +1544,7 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
         const apply = async () => {
             const ownershipTags = [ownershipTag, rowTag];
             if (row.isUpdate) {
-                upsertUpdate(pmRoot, row.existingId, row.parsed, opts.source, ownershipTags);
+                upsertUpdate(pmRoot, row.existingId, row.parsed, opts.source, ownershipTags, `${rowTag}:apply`);
                 appliedId = row.existingId;
                 return row.existingId;
             }
@@ -1515,12 +1552,12 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
             appliedId = newId;
             return newId;
         };
-        const prepareCompensation = async () => undefined;
-        const compensate = async () => {
-            // Only creates are compensated (closed); updates to pre-existing items
-            // are intentionally left in place (documented limitation).
-            if (row.isUpdate)
+        const prepareCompensation = async () => row.isUpdate ? captureUpdateCompensation(pmRoot, row.existingId, rowTag, author) : undefined;
+        const compensate = async (data) => {
+            if (row.isUpdate) {
+                await compensateUpdate(pmRoot, row.existingId, rowTag, author, data);
                 return;
+            }
             // Prefer the id captured by apply() in this run; fall back to the
             // pre-run per-row lookup (resume-compensation of a prior run's applied step).
             const id = appliedId ?? applied.byRowIndex.get(row.rowIndex);
@@ -1540,8 +1577,8 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
         // The coordinator invokes compensations in reverse order, but this package
         // cannot prove a clean tracker: create cleanup deliberately tolerates an
         // unavailable status lookup or failed close so the remaining sweep can
-        // continue, and update steps intentionally preserve pre-existing items.
-        throw new CommandError(`Atomic CSV import failed. The transaction coordinator attempted reverse-order compensation, but pm-csv cannot claim a clean tracker: created items are closed on a best-effort basis, and pre-existing item updates are intentionally not reverted. Mutations from transaction ${transactionId} may remain; inspect and reconcile that transaction before retrying. Underlying error: ${msg}`, EXIT_CODE.GENERIC_FAILURE);
+        // continue, and update compensation refuses concurrent-writer conflicts.
+        throw new CommandError(`Atomic CSV import failed. The transaction coordinator attempted reverse-order compensation, but pm-csv cannot claim a clean tracker: created items are closed on a best-effort basis, and pre-existing updates restore captured prior values unless a conflict prevents safe compensation. Mutations from transaction ${transactionId} may remain; inspect and reconcile that transaction before retrying. Underlying error: ${msg}`, EXIT_CODE.GENERIC_FAILURE);
     }
     // Tally the ImportResult from the committed step results. Each committed
     // result is the created/updated item id. Only rows that were NOT already
@@ -1549,7 +1586,7 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
     // count toward imported/updated — resumed rows from a prior interrupted run
     // are already in the tracker and must not be double-counted.
     for (const row of planned) {
-        const stepId = `csv-import-row-${row.rowIndex}`;
+        const stepId = atomicStepId(row.rowIndex, row.existingId);
         const res = committed.results[stepId];
         if (res === undefined)
             continue;
@@ -1635,6 +1672,11 @@ function appendMutableItemArgs(args, p, preserveEmptyBody) {
         args.push("--deadline", p.deadline);
     appendRelationalArgs(args, p);
 }
+/** Build a normal validated close with factual CSV provenance and outcome fields. */
+function csvCloseArgs(pmRoot, id, reason, expected, actual) {
+    return ["--path", pmRoot, "close", id, "--reason", reason,
+        "--resolution", reason, "--expected-result", expected, "--actual-result", actual];
+}
 /**
  * Build the `pm close --reason` text for an imported row whose CSV status is
  * terminal (`closed`/`canceled`). Since pm-cli 2026.8.3 the CLI enforces
@@ -1671,8 +1713,8 @@ function importCloseReason(status, source) {
  *      operator can find and reconcile the open orphan manually. The created
  *      open item is left behind in this one unrecoverable case.
  *   2. `pm close` failed after the item was persisted as open. The orphan is
- *      compensated (closed) via {@link compensateCreate} with `--validate-close
- *      off`, so a verified cleanup leaves no open orphan and a retry re-imports
+ *      compensated (closed) via {@link compensateCreate} with explicit rollback
+ *      outcome fields, so a verified cleanup leaves no open orphan and a retry re-imports
  *      it. If
  *      compensation also fails, the thrown error carries the created id and
  *      states the item was left open, so the partial state is actionable and a
@@ -1745,7 +1787,7 @@ function upsertCreate(pmRoot, p, keyValue, source, extraTags) {
         // and the real resulting state (closed, or still-open with the close's
         // failure cause), so the operator never stops looking for an open orphan.
         if (id) {
-            const rc = spawnSync("pm", ["--path", pmRoot, "close", id, "--validate-close", "off", "--reason", "csv import create overran its receipt buffer; closing the orphaned created item"], { encoding: "utf-8", maxBuffer: pmListMaxBuffer() });
+            const rc = spawnSync("pm", csvCloseArgs(pmRoot, id, "csv import create overran its receipt buffer; closing the orphaned created item", "The failed CSV create leaves no active orphan.", "Closing the identified created item after its receipt failed."), { encoding: "utf-8", maxBuffer: pmListMaxBuffer() });
             const createCause = describePmNullStatus(r, "create");
             if (rc.status === 0) {
                 throw new CommandError(`${createCause}. The create for row (title '${p.title}', id ${id}) may have persisted; the orphaned item ${id} was closed — retry the import.`);
@@ -1768,7 +1810,7 @@ function upsertCreate(pmRoot, p, keyValue, source, extraTags) {
         throw new Error(`pm create succeeded for row (title '${p.title}', source status '${p.status}') but returned no id, so the source status cannot be applied and the created item cannot be identified or safely reconciled; it may have been left as an orphan — reconcile manually`);
     }
     if (p.status === "closed") {
-        const cr = spawnSync("pm", ["--path", pmRoot, "close", id, "--reason", importCloseReason("closed", source)], { encoding: "utf-8", maxBuffer: pmListMaxBuffer() });
+        const cr = spawnSync("pm", csvCloseArgs(pmRoot, id, importCloseReason("closed", source), "Persist the imported CSV row with source status closed.", "CSV fields imported; applying the source status closed."), { encoding: "utf-8", maxBuffer: pmListMaxBuffer() });
         // Deliberately NO assertPmOutputFit(cr, "close") here: a null close status
         // (receipt overrun or a signal kill) must route INTO the compensation branch
         // below rather than bypass it. The close may have persisted before its
@@ -1778,8 +1820,7 @@ function upsertCreate(pmRoot, p, keyValue, source, extraTags) {
             // (2) The close failed but the item is already persisted as open.
             // Compensate (close) the orphan so a verified cleanup leaves no open item
             // that a retry without --key-field could duplicate.
-            // Compensation bypasses closure-validation governance (it is a rollback,
-            // not a user closure) so a strict tracker cannot block the cleanup.
+            // Compensation supplies explicit rollback outcome fields for strict closure.
             compensateCreate(pmRoot, id, [], "csv import row failed; closing orphan created item");
             const closeErr = cr.stderr?.trim() || cr.stdout?.trim() || "pm close failed";
             // Only a status of exactly `closed` is evidence that compensation worked.
@@ -1815,13 +1856,14 @@ function upsertCreate(pmRoot, p, keyValue, source, extraTags) {
  * carries the item id and states explicitly that the mutation may already have
  * been applied, so the operator can verify and reconcile by id. The guarantee
  * is NOT that no mutation is left behind — an update has no inverse without the
- * prior field values, which this extension does not capture, so a failed update
- * is reported loudly by id rather than compensated with a second unreviewed
- * write on top of a failed one (see the deferred capture-prior-values feature).
+ * prior field values. Atomic imports journal those values before calling this
+ * helper and compensate from them; non-atomic imports report failures by id.
  */
-function upsertUpdate(pmRoot, id, p, source, extraTags) {
+function upsertUpdate(pmRoot, id, p, source, extraTags, historyMessage) {
     const args = ["--path", pmRoot, "update", id, "--title", p.title];
     appendMutableItemArgs(args, p, true);
+    if (historyMessage)
+        args.push("--message", historyMessage);
     // Preserve the csv-key tag (additive) and refresh the user tags.
     const addTags = [...p.tags];
     if (source)
@@ -1839,9 +1881,8 @@ function upsertUpdate(pmRoot, id, p, source, extraTags) {
     // failure must carry the item id and state that explicitly — matching the
     // create path. The guarantee is that no mutation is left un-IDENTIFIED, NOT
     // that no mutation is left behind: an update has no inverse without the prior
-    // field values, which this extension does not capture, so a failed update is
-    // reported loudly by id rather than papered over with a second unreviewed
-    // write on top of a failed one.
+    // field values. The atomic coordinator journals those before calling this
+    // helper; a non-atomic update only reports its failure by id.
     if (r.status === null) {
         throw new CommandError(`${describePmNullStatus(r, "update")}. The update for item ${id} may already have been applied — verify the item by id before retrying.`);
     }
@@ -1854,7 +1895,7 @@ function upsertUpdate(pmRoot, id, p, source, extraTags) {
     // and the explicit caveat that the terminal transition may already have taken
     // effect too — the close, like the update, is a single non-atomic subprocess.
     if (p.status === "closed" || p.status === "canceled") {
-        const cr = spawnSync("pm", ["--path", pmRoot, "close", id, "--reason", importCloseReason(p.status, source)], { encoding: "utf-8", maxBuffer: pmListMaxBuffer() });
+        const cr = spawnSync("pm", [...csvCloseArgs(pmRoot, id, importCloseReason(p.status, source), `Persist the imported CSV update with source status ${p.status}.`, `CSV fields updated; applying the source status ${p.status}.`), ...(historyMessage ? ["--message", historyMessage.replace(/:apply$/, ":close")] : [])], { encoding: "utf-8", maxBuffer: pmListMaxBuffer() });
         if (cr.status === null) {
             throw new CommandError(`${describePmNullStatus(cr, "close")}. The update for item ${id} was applied, but the terminal ${p.status} close may already have been applied too — verify the item by id before retrying.`);
         }
@@ -2282,7 +2323,7 @@ function prepareCsvExport(pmRoot, rawOptions) {
 }
 export default {
     name: "pm-csv",
-    version: "2026.10.4",
+    version: "2026.10.12",
     activate(api) {
         // -----------------------------------------------------------------------
         // Schema: register an optional `csv_source` provenance field so imported
@@ -2340,7 +2381,7 @@ export default {
                 { long: "--dry-run", description: "Preview without writing" },
                 { long: "--skip-headers", description: "The CSV file has no header row; map columns positionally to the standard import order (title, type, status, priority, tags, deadline, body, parent, assignee, sprint, release, blocked_by)" },
                 { long: "--stream", description: "Stream the file row-by-row instead of loading it fully into memory (recommended for large CSV files)" },
-                { long: "--atomic", description: "Use one writer-locked, crash-recoverable transaction. On failure, attempt best-effort create compensation; pre-existing item updates are intentionally not reverted. Inspect and reconcile any marked orphan before retrying. Incompatible with --stream" },
+                { long: "--atomic", description: "Use one writer-locked, crash-recoverable transaction. On failure, attempt best-effort create compensation; pre-existing updates restore captured prior values unless a conflict prevents safe compensation. Inspect and reconcile any marked orphan before retrying. Incompatible with --stream" },
             ],
             async run(ctx) {
                 const filePath = ctx.args[0];