pm-csv 2026.10.28 → 2026.10.30

package/dist/index.js

@@ -1,12 +1,17 @@
+import * as nativeSdk from "@unbrained/pm-cli/sdk";
 import { readFileSync, writeFileSync, createReadStream, mkdirSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { certifyCompleteListResult, inspectCompleteListResult, readSettingsWithMetadata, resolveRuntimeFieldRegistry, runWorkspaceTransactionGc } from "@unbrained/pm-cli/sdk";
+import { certifyCompleteListResult, inspectCompleteListResult, listAllComplete, readSettingsWithMetadata, resolveRuntimeFieldRegistry, runWorkspaceTransactionGc, create as createNativeCsv, update as updateNativeCsv, resolveRuntimeStatusRegistry, isTerminalStatus } from "@unbrained/pm-cli/sdk";
+import { captureSettings, inSettingsTransaction, normalizePinnedStatus, pinCreateDefaults, readPinnedSettings as readSettings, rethrowSettingsChange, settingsDigest, useSettings, verifySettings, withSettings, withSettingsFence } from "./settings-snapshot.js";
 import { importLineage, writeLineageBundle, LineageRefusal } from "./lineage.js";
 import { applyEditSession, exportEditSession, EditRefusal } from "./roundtrip.js";
+import { buildMutationIntent, mutationScopeArguments, matchesMutationScope } from "./mutation-intent.js";
+import { registerJoinCommands } from "./join-plans.js";
 import { registerTableSchemaCommands } from "./table-schema.js";
-import { captureUpdateCompensation, compensateUpdate, inspectUpdate, UPDATE_COMPENSATION_VERSION } from "./atomic-update.js";
+import { admitCSV, AdmissionRefusal, admissionPreviewFailure, admissionSettingsChanged, admissionTargetRevision, admissionTargetSequence, assertCSVAdmission, findAdmissionFailure, normalizeAdmissionFilter, parseAdmissionOptions, readAdmittedSource, registerAdmissionCommand, requireAdmissionCapability } from "./admission.js";
+import { captureUpdateCompensation, compensateUpdate, inspectUpdate, readUpdateDocument, UPDATE_COMPENSATION_VERSION } from "./atomic-update.js";
 // ---------------------------------------------------------------------------
 // Error contract
 // ---------------------------------------------------------------------------
@@ -31,10 +36,14 @@ const EXIT_CODE = {
 export class CommandError extends Error {
     /** Numeric exit code the runtime propagates to the shell. */
     exitCode;
-    constructor(message, exitCode = EXIT_CODE.GENERIC_FAILURE) {
+    /** Optional stable category for snapshot-sensitive mutation refusals. */
+    code;
+    constructor(message, exitCode = EXIT_CODE.GENERIC_FAILURE, code) {
         super(message);
         this.name = "CommandError";
         this.exitCode = exitCode;
+        if (code)
+            this.code = code;
     }
 }
 // Columns accepted on import (order independent — driven by header row).
@@ -199,16 +208,6 @@ function serializeCSV(rows, delimiterOrOpts) {
         .map((row) => row.map((f) => serializeField(f, opts.delimiter)).join(opts.delimiter))
         .join(eol);
 }
-// ---------------------------------------------------------------------------
-// Streaming CSV parser — for large files that should not be held in memory.
-// Same RFC-4180 state machine as parseCSV, but fed incrementally so quoted
-// fields spanning chunk boundaries are handled correctly.
-// ---------------------------------------------------------------------------
-/**
- * Incremental CSV state machine. Feed text via {@link push} and call
- * {@link end} when the input is exhausted. Each complete row is emitted to the
- * `onRow` callback exactly as in {@link parseCSV}.
- */
 class StreamingCSVParser {
     delimiter;
     onRow;
@@ -217,9 +216,27 @@ class StreamingCSVParser {
     inQuotes = false;
     recordStarted = false;
     pendingBoundaryChar = "";
-    constructor(delimiter, onRow) {
+    limits;
+    recordCodeUnits = 0;
+    constructor(delimiter, onRow, limits) {
         this.delimiter = delimiter;
         this.onRow = onRow;
+        this.limits = limits;
+    }
+    /** Bound allocations before appending even an unterminated adversarial field. */
+    appendField(value) {
+        if (this.limits && (this.field.length + value.length > this.limits.maxFieldCodeUnits ||
+            this.recordCodeUnits + value.length > this.limits.maxRecordCodeUnits))
+            throw new RangeError("csv_record_limit");
+        this.field += value;
+        this.recordCodeUnits += value.length;
+    }
+    /** Bound empty fields too, so delimiter-only input cannot grow an unbounded array. */
+    finishField() {
+        if (this.limits && this.row.length >= this.limits.maxColumns)
+            throw new RangeError("csv_column_limit");
+        this.row.push(this.field);
+        this.field = "";
     }
     push(text) {
         text = this.pendingBoundaryChar + text;
@@ -235,7 +252,7 @@ class StreamingCSVParser {
                         return;
                     }
                     if (text[i + 1] === '"') {
-                        this.field += '"';
+                        this.appendField('"');
                         i += 2;
                         continue;
                     }
@@ -243,7 +260,7 @@ class StreamingCSVParser {
                     i++;
                     continue;
                 }
-                this.field += ch;
+                this.appendField(ch);
                 i++;
                 continue;
             }
@@ -253,16 +270,15 @@ class StreamingCSVParser {
                 continue;
             }
             if (ch === this.delimiter) {
-                this.row.push(this.field);
-                this.field = "";
+                this.finishField();
                 i++;
                 continue;
             }
             if (ch === "\r" && text[i + 1] === "\n") {
-                this.row.push(this.field);
-                this.field = "";
+                this.finishField();
                 this.onRow(this.row);
                 this.row = [];
+                this.recordCodeUnits = 0;
                 this.recordStarted = false;
                 i += 2;
                 continue;
@@ -272,15 +288,15 @@ class StreamingCSVParser {
                 return;
             }
             if (ch === "\n") {
-                this.row.push(this.field);
-                this.field = "";
+                this.finishField();
                 this.onRow(this.row);
                 this.row = [];
+                this.recordCodeUnits = 0;
                 this.recordStarted = false;
                 i++;
                 continue;
             }
-            this.field += ch;
+            this.appendField(ch);
             i++;
         }
     }
@@ -289,15 +305,18 @@ class StreamingCSVParser {
             this.inQuotes = false;
         }
         else if (this.pendingBoundaryChar !== "") {
-            this.field += this.pendingBoundaryChar;
+            this.appendField(this.pendingBoundaryChar);
         }
         this.pendingBoundaryChar = "";
+        if (this.limits && this.inQuotes)
+            throw new SyntaxError("csv_unterminated_quote");
         if (this.recordStarted) {
-            this.row.push(this.field);
+            this.finishField();
             this.onRow(this.row);
             this.field = "";
             this.row = [];
             this.recordStarted = false;
+            this.recordCodeUnits = 0;
         }
     }
 }
@@ -339,7 +358,7 @@ function streamCSVFile(filePath, delimiter, encoding, onRow) {
  */
 function readBoolOption(options, ...keys) {
     for (const key of keys) {
-        if (options[key] !== undefined)
+        if (Object.hasOwn(options, key) && options[key] !== undefined)
             return Boolean(options[key]);
     }
     return false;
@@ -491,7 +510,7 @@ function completeListArgs(pmRoot) {
 /** Narrow an unknown JSON value to a non-array record. */
 function asRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
-        ? value
+        ? Object.assign(Object.create(null), value)
         : undefined;
 }
 /** Render a receipt value while preserving a missing field as evidence. */
@@ -656,9 +675,9 @@ function errorMessage(error) {
  * Example: `--map "Summary=title,Owner=tags"`.
  */
 function parseFieldMap(spec) {
-    const map = {};
+    const map = Object.create(null);
     if (spec === undefined)
-        return map;
+        return { ...map };
     const parts = (Array.isArray(spec) ? spec : [spec]).flatMap((s) => s.split(","));
     for (const part of parts) {
         const trimmed = part.trim();
@@ -675,14 +694,14 @@ function parseFieldMap(spec) {
         }
         map[from] = to;
     }
-    return map;
+    return { ...map };
 }
 /**
  * Apply a field map to a list of header names, producing the effective
  * (canonical) header used for column lookup.
  */
 function applyFieldMap(headers, fieldMap) {
-    return headers.map((h) => fieldMap[h] ?? h);
+    return headers.map((h) => Object.hasOwn(fieldMap, h) ? fieldMap[h] : h);
 }
 /**
  * Compute a simple Levenshtein edit distance between two lowercase strings.
@@ -788,9 +807,9 @@ const AUTO_MAP_ALIASES = {
  * alias mappings and never overrides an already-claimed canonical field.
  */
 function resolveImportFieldMap(headers, explicitMap, autoMap) {
-    const fieldMap = { ...explicitMap };
+    const fieldMap = Object.assign(Object.create(null), explicitMap);
     if (!autoMap || headers.length === 0)
-        return { fieldMap, autoMappings: [] };
+        return { fieldMap: { ...fieldMap }, autoMappings: [] };
     const headerCounts = new Map();
     for (const header of headers) {
         headerCounts.set(header, (headerCounts.get(header) ?? 0) + 1);
@@ -813,22 +832,25 @@ function resolveImportFieldMap(headers, explicitMap, autoMap) {
         claimedTargets.add(target);
         autoMappings.push({ from, to: target });
     }
-    return { fieldMap, autoMappings };
+    return { fieldMap: { ...fieldMap }, autoMappings };
 }
 function formatAutoMappings(mappings) {
     return mappings.map((m) => `${m.from}->${m.to}`).join(", ");
 }
 function autoMappingsToRecord(mappings) {
-    const record = {};
+    const record = Object.create(null);
     for (const m of mappings)
         record[m.from] = m.to;
-    return record;
+    return { ...record };
 }
 /**
  * Map an arbitrary status string (from the CSV) to a valid SDK status.
  * Falls back to "open".
  */
 function normalizeStatus(raw) {
+    const pinned = normalizePinnedStatus(raw);
+    if (pinned !== undefined)
+        return pinned;
     const s = raw.trim().toLowerCase();
     const map = {
         open: "open",
@@ -849,7 +871,7 @@ function normalizeStatus(raw) {
         cancelled: "canceled",
         draft: "draft",
     };
-    return map[s] ?? "open";
+    return Object.hasOwn(map, s) ? map[s] : "open";
 }
 /**
  * Parse a comma-separated tags string into an array, stripping whitespace.
@@ -885,10 +907,11 @@ function resolveEncoding(raw) {
  * Read rows from a CSV file, returning header and data rows separately.
  * Skips fully-empty rows. Decodes with the given encoding (default utf-8).
  */
-function readCSVFile(filePath, delimiter, encoding = "utf-8", skipHeaders = false) {
+function readCSVFile(filePath, delimiter, encoding = "utf-8", skipHeaders = false, admittedDigest, admittedMaxBytes) {
     // Node's BufferEncoding spells utf-8 as "utf8"; normalize.
     const bufEnc = encoding === "utf-8" ? "utf8" : encoding;
-    const text = stripBOM(readFileSync(filePath, bufEnc));
+    const bytes = admittedDigest === undefined ? readFileSync(filePath) : readAdmittedSource(filePath, admittedDigest, admittedMaxBytes);
+    const text = stripBOM(bytes.toString(bufEnc));
     const rows = parseCSV(text, delimiter).filter((r) => r.some((f) => f.trim() !== ""));
     if (rows.length === 0) {
         return { headers: [], dataRows: [] };
@@ -931,13 +954,13 @@ function rowFields(headers, row) {
         get,
         parsed: {
             title: get("title"),
-            status: rawStatus ? normalizeStatus(rawStatus) : "open",
+            status: rawStatus ? normalizeStatus(rawStatus) : undefined,
             priority: priority !== undefined && !isNaN(priority) ? priority : undefined,
             tags: parseTags(get("tags")),
             type: get("type") || undefined,
             // pm has no milestone/due_date fields; map deadline (accept legacy header).
             deadline: get("deadline") || get("due_date") || undefined,
-            body: get("body") || undefined,
+            body: get("body") ? row[col("body")] : undefined,
             parent: get("parent") || undefined,
             assignee: get("assignee") || undefined,
             sprint: get("sprint") || undefined,
@@ -977,10 +1000,10 @@ function parseImportFilter(statusRaw, typeRaw, priorityRaw) {
  * Pure predicate: does a parsed row satisfy every set filter criterion?
  * Unset criteria are wildcards. Exposed for unit testing.
  */
-function rowMatchesFilter(row, filter) {
+function rowMatchesFilter(row, filter, defaultStatus = "open") {
     if (!filter)
         return true;
-    if (filter.status !== undefined && row.status !== filter.status)
+    if (filter.status !== undefined && (row.status ?? defaultStatus) !== filter.status)
         return false;
     if (filter.type !== undefined && (row.type ?? "").toLowerCase() !== filter.type)
         return false;
@@ -995,7 +1018,6 @@ function rowMatchesFilter(row, filter) {
  * creates — so the envelope's receipt is checked before any key is read.
  */
 function loadKeyIndex(pmRoot, spawn = spawnPm) {
-    const index = new Map();
     const result = spawn(completeListArgs(pmRoot), { encoding: "utf-8", maxBuffer: pmListMaxBuffer() });
     // Route a stdout overrun (status: null, empty stderr, ENOBUFS) through
     // assertPmOutputFit as a hard, named error instead of the generic
@@ -1025,6 +1047,11 @@ function loadKeyIndex(pmRoot, spawn = spawnPm) {
             + "which would make --upsert create duplicates.");
     }
     items = assertListAllComplete(parsed);
+    return csvKeyIndex(items);
+}
+/** Build only the package-owned provenance-key index from a certified native read. */
+function csvKeyIndex(items) {
+    const index = new Map();
     for (const item of items) {
         for (const tag of item.tags ?? []) {
             if (tag.startsWith(KEY_TAG_PREFIX)) {
@@ -1060,6 +1087,7 @@ function processImportRow(pmRoot, headers, row, lineNo, opts, keyIndex, result)
         result.previews.push({
             action: existingId ? "update" : "create",
             ...parsed,
+            status: parsed.status ?? (existingId ? undefined : "open"),
             ...(opts.keyField ? { key: keyValue } : {}),
             ...(opts.source ? { csv_source: opts.source } : {}),
         });
@@ -1122,8 +1150,8 @@ function resolveImportHeaders(rawHeaders, opts) {
     return { headers, autoMappings: mapResolution.autoMappings, fieldMapWarnings };
 }
 /** Read and resolve the shared in-memory prelude for normal and atomic imports. */
-function prepareInMemoryImport(filePath, opts) {
-    const { headers: rawHeaders, dataRows } = readCSVFile(filePath, opts.delimiter, opts.encoding ?? "utf-8", opts.skipHeaders ?? false);
+function prepareInMemoryImport(filePath, opts, admittedDigest) {
+    const { headers: rawHeaders, dataRows } = readCSVFile(filePath, opts.delimiter, opts.encoding ?? "utf-8", opts.skipHeaders ?? false, admittedDigest, opts.admission?.maxAtomicBytes);
     return {
         rawHeaders,
         dataRows,
@@ -1153,7 +1181,21 @@ function processImportRows(pmRoot, dataRows, headers, opts, result) {
  * @returns The import outcome; rejects with a {@link CommandError} on a usage
  *          conflict or an unreadable file.
  */
-function importCSV(pmRoot, filePath, opts) {
+async function importCSV(pmRoot, filePath, opts) {
+    if (opts.admission !== undefined) {
+        if (!opts.atomic || opts.stream)
+            throw new AdmissionRefusal("csv_admission_options", "CSV admission apply requires --atomic without --stream.");
+        const admission = parseAdmissionOptions({ ...parseAdmissionOptions(opts.admission), mode: "full", delimiter: opts.delimiter,
+            fieldMap: opts.fieldMap, autoMap: opts.autoMap ?? false, encoding: opts.encoding ?? "utf-8", skipHeaders: opts.skipHeaders ?? false, filter: opts.filter });
+        const captured = { ...opts, delimiter: admission.delimiter, fieldMap: admission.fieldMap, encoding: admission.encoding,
+            autoMap: admission.autoMap, skipHeaders: admission.skipHeaders, filter: admission.filter, admission };
+        return withSettings(pmRoot, admissionSettingsChanged, async () => {
+            captured.filter = normalizeAdmissionFilter(admission.filter, await readSettings(pmRoot));
+            const receipt = await admitCSV(pmRoot, filePath, admission);
+            assertCSVAdmission(receipt);
+            return importCSVAtomic(pmRoot, filePath, captured, receipt.digest);
+        });
+    }
     if (opts.atomic && opts.stream) {
         return Promise.reject(new CommandError("--atomic cannot be combined with --stream: an unbounded stream cannot be committed as one bounded transaction.", EXIT_CODE.USAGE));
     }
@@ -1236,9 +1278,9 @@ export function atomicTransactionId(filePath, opts = {}) {
     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}`;
+function atomicStepId(rowIndex, existingId, revision, creation) {
+    const operation = existingId ? `update-${existingId}` : creation ? `create-${creation}` : "create";
+    return `csv-import-v${UPDATE_COMPENSATION_VERSION}-${operation}-row-${rowIndex}${revision === undefined ? "" : `-revision-${revision}`}`;
 }
 /**
  * Recover the original plan's update targets and create roles from SDK journal
@@ -1249,30 +1291,42 @@ function atomicStepId(rowIndex, existingId) {
  * 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) {
+export 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"));
+        return { bindings };
+    let journal;
+    try {
+        journal = JSON.parse(readFileSync(resolve(pmRoot, entry.file), "utf8"));
+    }
+    catch {
+        throw new CommandError("The recorded atomic journal cannot be read. Preserve its audit and reconcile the original attempt before retrying or previewing this import.", EXIT_CODE.USAGE);
+    }
     if (journal === null || typeof journal !== "object" || Array.isArray(journal)
-        || !("stepIds" in journal) || !Array.isArray(journal.stepIds)
+        || !Object.hasOwn(journal, "stepIds") || !("stepIds" in journal) || !Array.isArray(journal.stepIds)
         || !journal.stepIds.every((id) => typeof id === "string")) {
         throw new CommandError(`Workspace transaction ${transactionId} journal does not match the supplied plan: incompatible CSV step identity.`);
     }
-    if (!("schemaVersion" in journal) || journal.schemaVersion !== 1
-        || !("transactionId" in journal) || journal.transactionId !== transactionId) {
+    if (!Object.hasOwn(journal, "schemaVersion") || !("schemaVersion" in journal) || journal.schemaVersion !== 1
+        || !Object.hasOwn(journal, "transactionId") || !("transactionId" in journal) || journal.transactionId !== transactionId) {
         throw new CommandError(`Workspace transaction ${transactionId} journal does not match the supplied plan: incompatible CSV journal identity. Refusing before transaction coordination.`);
     }
-    const pattern = new RegExp(String.raw `^csv-import-v${UPDATE_COMPENSATION_VERSION}-(?:create|update-(.+))-row-(\d+)$`);
+    const revisions = new Map();
+    const creations = new Map();
+    const pattern = new RegExp(String.raw `^csv-import-v${UPDATE_COMPENSATION_VERSION}-(?:create(?:-(.+))?|update-(.+))-row-(\d+)(?:-revision-(absent|[a-f0-9]{64}))?$`);
     for (const id of journal.stepIds) {
         const match = pattern.exec(id);
         if (!match)
             throw new CommandError(`Workspace transaction ${transactionId} journal does not match the supplied plan: incompatible CSV step identity.`);
-        bindings.set(Number(match[2]), match[1]);
+        bindings.set(Number(match[3]), match[2]);
+        if (match[4] !== undefined)
+            revisions.set(Number(match[3]), match[4]);
+        if (match[1] !== undefined)
+            creations.set(Number(match[3]), match[1]);
     }
-    return bindings;
+    return { bindings, status: entry.status, ...(revisions.size ? { revisions } : {}), ...(creations.size ? { creations } : {}) };
 }
 /**
  * Load every item stamped with this transaction's per-row ownership marker
@@ -1305,7 +1359,6 @@ async function loadAtomicBindings(pmRoot, transactionId) {
  * compensateCreate.)
  */
 function loadAppliedByTransaction(pmRoot, transactionId, spawn = spawnPm) {
-    const byRowIndex = new Map();
     const rowMarkerPrefix = `${TX_ROW_TAG_PREFIX}${transactionId}${TX_ROW_TAG_SEPARATOR}`;
     const r = spawn(completeListArgs(pmRoot), {
         encoding: "utf-8",
@@ -1343,6 +1396,11 @@ function loadAppliedByTransaction(pmRoot, transactionId, spawn = spawnPm) {
     // resume scan that misses applied rows silently re-imports them (wrong
     // data, the exact failure this package exists to prevent).
     items = assertListAllComplete(parsed);
+    return csvAppliedIndex(items, rowMarkerPrefix);
+}
+/** Share per-row provenance interpretation between legacy CLI and admitted SDK reads. */
+function csvAppliedIndex(items, rowMarkerPrefix) {
+    const byRowIndex = new Map();
     for (const item of items) {
         for (const tag of item.tags ?? []) {
             if (!tag.startsWith(rowMarkerPrefix))
@@ -1446,7 +1504,7 @@ function compensateCreate(pmRoot, id, markers = [], reason = "atomic csv import
         }
     }
     if (markers.length > 0) {
-        const markerCleanup = spawnSync("pm", ["--path", pmRoot, "update", id, "--remove-tags", markers.join(",")], { encoding: "utf-8", maxBuffer: pmListMaxBuffer() });
+        const markerCleanup = spawnSync("pm", ["--path", pmRoot, "update", id, "--remove-tags", markers.join(","), ...mutationScopeArguments({}, "patch")], { encoding: "utf-8", maxBuffer: pmListMaxBuffer() });
         if (markerCleanup.status !== 0) {
             console.error(`atomic import: compensation marker cleanup failed for ${id}: ${markerCleanup.stderr?.trim() || markerCleanup.stdout?.trim()}`);
         }
@@ -1455,7 +1513,7 @@ function compensateCreate(pmRoot, id, markers = [], reason = "atomic csv import
 /**
  * Atomic in-memory import: every row that would CREATE an item becomes one
  * {@link WorkspaceTransactionStep} committed under a single workspace
- * writer-locked, crash-recoverable transaction. On success the same
+ * SDK-coordinated, crash-recoverable transaction. On success the same
  * {@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
@@ -1463,35 +1521,49 @@ function compensateCreate(pmRoot, id, markers = [], reason = "atomic csv import
  * prevent safe update compensation. An interrupted run resumes from the
  * durable journal (inspect() skips already applied rows).
  */
-async function importCSVAtomic(pmRoot, filePath, opts) {
-    const { rawHeaders, dataRows, result, resolvedHeaders } = prepareInMemoryImport(filePath, opts);
+async function importCSVAtomicInternal(pmRoot, filePath, opts, prepared, bindingSnapshot) {
+    const { rawHeaders, dataRows, result, resolvedHeaders } = prepared;
     if (!resolvedHeaders)
         return result;
     result.fieldMapWarnings = resolvedHeaders.fieldMapWarnings;
     result.autoMappings = resolvedHeaders.autoMappings;
     // A dry-run atomic import just previews like the non-atomic path (no
     // transaction is committed, nothing is written).
-    if (opts.dryRun) {
+    if (opts.dryRun && opts.admission === undefined) {
+        const existing = await loadAtomicBindings(pmRoot, deriveTransactionId(resolve(filePath), fingerprintContent(rawHeaders, dataRows)));
+        if (existing.status === "compensating")
+            throw new CommandError("Pending atomic compensation must be recovered with the original import options before previewing new work; dry-run did not modify the journal.", EXIT_CODE.USAGE);
         processImportRows(pmRoot, dataRows, resolvedHeaders.headers, opts, result);
         return result;
     }
     const commitTransaction = opts.commitTransaction;
-    if (!commitTransaction) {
+    if (!commitTransaction && !opts.dryRun) {
         throw new CommandError("--atomic requires the host-injected commitWorkspaceTransaction SDK primitive. Upgrade the pm CLI and invoke pm-csv through the pm host.", EXIT_CODE.USAGE);
     }
     // Fingerprint the exact parsed content (raw headers + all data rows) so that
     // editing the file in place yields a fresh transaction id instead of reusing
     // stale per-row markers from a previous import of different content.
-    const transactionId = deriveTransactionId(resolve(filePath), fingerprintContent(rawHeaders, dataRows));
+    const admissionPreview = opts.admission === undefined ? undefined : requireAdmissionCapability(nativeSdk.previewItemMutations);
+    const transactionId = opts.admission === undefined ? deriveTransactionId(resolve(filePath), fingerprintContent(rawHeaders, dataRows))
+        : `csv-import-${requireAdmissionCapability(nativeSdk.deriveMutationTransactionId)(JSON.stringify([
+            "admitted-v1", resolve(filePath), rawHeaders, dataRows, Object.entries(opts.fieldMap).sort(), opts.autoMap, opts.keyField ?? "",
+            [opts.filter?.status, opts.filter?.type, opts.filter?.priority], opts.skipHeaders, opts.source ?? "", settingsDigest(await readSettings(pmRoot)),
+        ]))}`;
     const author = opts.atomicAuthor ?? "pm-csv";
+    let rollback;
     const ownershipTag = `${TX_TAG_PREFIX}${transactionId}`;
     // Per-row ownership marker source of truth: `csv-txrow:<transactionId>#<rowIndex>`.
     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();
+    const { bindings, status: journalStatus, revisions, creations } = bindingSnapshot ?? await loadAtomicBindings(pmRoot, transactionId);
+    if (opts.admission !== undefined && opts.dryRun && journalStatus === "compensating") {
+        throw new AdmissionRefusal("csv_admission_target_changed", "Recover the retained atomic compensation with the original options before previewing this import; dry-run did not modify the journal.");
+    }
+    const admittedItems = opts.admission === undefined ? undefined : certifyCompleteListResult(await listAllComplete({}, { pmRoot })).items;
+    const applied = admittedItems === undefined ? loadAppliedByTransaction(pmRoot, transactionId)
+        : csvAppliedIndex(admittedItems, `${TX_ROW_TAG_PREFIX}${transactionId}${TX_ROW_TAG_SEPARATOR}`);
+    const keyIndex = admittedItems === undefined ? (opts.keyField ? loadKeyIndex(pmRoot) : new Map()) : csvKeyIndex(admittedItems);
     // In-batch duplicate-KEY guard: keys already claimed by an earlier planned
     // CREATE in THIS run (the keyIndex is not updated during planning, so
     // without this guard two rows sharing a not-yet-existing key would both
@@ -1499,6 +1571,8 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
     // claimed key is skipped with a clear per-row warning (see README).
     const claimedKeys = new Map();
     const planned = [];
+    const planningSettings = await readSettings(pmRoot);
+    const defaultStatus = opts.admission === undefined ? undefined : resolveRuntimeStatusRegistry(planningSettings.schema).open_status;
     for (let rowIndex = 0; rowIndex < dataRows.length; rowIndex++) {
         const lineNo = opts.skipHeaders ? rowIndex + 1 : rowIndex + 2;
         const row = dataRows[rowIndex];
@@ -1510,7 +1584,7 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
             result.skipped++;
             continue;
         }
-        if (!rowMatchesFilter(parsed, opts.filter)) {
+        if (!rowMatchesFilter(parsed, opts.filter, defaultStatus)) {
             result.skipped++;
             result.filtered++;
             continue;
@@ -1531,7 +1605,89 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
             : normalizedKey ? keyIndex.get(normalizedKey) : undefined;
         if (normalizedKey && !existingId)
             claimedKeys.set(normalizedKey, rowIndex);
-        planned.push({ rowIndex, lineNo, parsed, keyValue, existingId, isUpdate: Boolean(existingId) });
+        const revision = opts.admission === undefined ? undefined : revisions?.get(rowIndex) ??
+            (existingId ? await admissionTargetRevision(pmRoot, existingId) : "absent");
+        const creation = revision === undefined || existingId ? undefined : nativeSdk.normalizeItemId(requireAdmissionCapability(nativeSdk.deriveMutationTransactionId)(`${transactionId}:${rowIndex}`), (await readSettings(pmRoot)).id_prefix);
+        if (creations?.has(rowIndex) && creations.get(rowIndex) !== creation)
+            throw new AdmissionRefusal("csv_admission_target_changed", "A recorded creation identity differs from this admitted source domain. Reconcile the retained journal before applying.");
+        planned.push({ rowIndex, lineNo, parsed, keyValue, existingId, isUpdate: Boolean(existingId), revision, creation });
+    }
+    if (opts.admission !== undefined) {
+        await opts.onAdmissionBoundary?.("targets_read");
+        if (bindings.size === 0) {
+            const latest = await loadAtomicBindings(pmRoot, transactionId);
+            if (latest.bindings.size > 0)
+                return importCSVAtomicInternal(pmRoot, filePath, opts, { ...prepared, result: createImportResult() }, latest);
+        }
+    }
+    // Recheck current scope before the SDK can reuse a committed journal receipt.
+    if (bindings.size && (planned.length !== bindings.size || planned.some(row => !bindings.has(row.rowIndex)))) {
+        throw new CommandError("An existing atomic CSV journal has a different recorded row domain. Resume with its original filters, mappings and key options to finish recovery; no new journal or successful empty receipt was produced.", EXIT_CODE.USAGE);
+    }
+    // In particular, legacy creates may carry an unreviewed focus-inherited parent.
+    const comparisonSettings = planningSettings;
+    const sequences = new Map();
+    for (const row of planned)
+        if (row.revision !== undefined && row.isUpdate) {
+            const rows = sequences.get(row.existingId) ?? [];
+            rows.push(row);
+            sequences.set(row.existingId, rows);
+        }
+    const sequenceHeads = new Map();
+    /** Share ordered target progress between preview, durable step inspection and per-write revision guards. */
+    const admittedRowState = async (row) => {
+        const sequence = sequences.get(row.existingId);
+        if (sequence) {
+            const state = await admissionTargetSequence(pmRoot, row.existingId, row.revision, sequence.map(entry => rowTagFor(entry.rowIndex)));
+            sequenceHeads.set(row.existingId, state.revision);
+            return { revision: state.revision, applied: state.completed >= sequence.indexOf(row) };
+        }
+        const revision = await admissionTargetRevision(pmRoot, row.existingId ?? row.creation, row.revision, rowTagFor(row.rowIndex));
+        return { revision, applied: revision !== row.revision };
+    };
+    const admittedApplied = new Set();
+    for (const row of planned) {
+        const owned = applied.byRowIndex.get(row.rowIndex);
+        if (row.revision !== undefined) {
+            if ((await admittedRowState(row)).applied)
+                admittedApplied.add(row.rowIndex);
+        }
+        if (!owned || row.isUpdate)
+            continue;
+        const document = await readUpdateDocument(pmRoot, owned);
+        if (!matchesMutationScope(document, { parent: row.parsed.parent, assignee: row.parsed.assignee,
+            sprint: row.parsed.sprint, release: row.parsed.release, blockedBy: row.parsed.blocked_by,
+            ...(!row.parsed.blocked_by ? { dep: [] } : {}) }, comparisonSettings, undefined, "patch")) {
+            throw new CommandError("Atomic CSV replay scope differs from the reviewed rows. Reconcile current parent, assignment, planning and dependency fields before importing again.", EXIT_CODE.USAGE);
+        }
+    }
+    if (opts.admission !== undefined) {
+        await verifySettings(pmRoot);
+        const pending = planned.filter(row => !admittedApplied.has(row.rowIndex)).map(row => ({
+            op: row.isUpdate ? "update" : "create", id: row.existingId ?? row.creation,
+            options: nativeCsvOptions(row.parsed, comparisonSettings, row.isUpdate, row.isUpdate ? undefined : row.keyValue, opts.source, [ownershipTag, rowTagFor(row.rowIndex)]),
+        }));
+        if (pending.length) {
+            try {
+                await admissionPreview({ pmRoot, author, transactionId: `csv-admit-preview-${transactionId}`, mutations: pending });
+            }
+            catch (error) {
+                throw admissionPreviewFailure(error);
+            }
+        }
+    }
+    if (opts.dryRun) {
+        for (const row of planned) {
+            result.previews.push({ action: admittedApplied.has(row.rowIndex) ? "unchanged" : row.isUpdate ? "update" : "create",
+                ...nativeCsvOptions(row.parsed, comparisonSettings, row.isUpdate, row.isUpdate ? undefined : row.keyValue, opts.source, [ownershipTag, rowTagFor(row.rowIndex)]) });
+            if (admittedApplied.has(row.rowIndex))
+                continue;
+            if (row.isUpdate)
+                result.updated++;
+            else
+                result.imported++;
+        }
+        return result;
     }
     // Build one transaction step per row to be written (create or update).
     //   - create: apply() shells out to the same `pm create` as the non-atomic
@@ -1550,12 +1706,16 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
     // `state: "applied"` for items created during THIS run — not just for items
     // left over from a prior interrupted run (which the pre-run `applied` lookup
     // already detects).
+    const wrote = new Set();
     const steps = planned.map((row) => {
-        const stepId = atomicStepId(row.rowIndex, row.existingId);
+        const stepId = atomicStepId(row.rowIndex, row.existingId, row.revision, row.creation);
         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.revision !== undefined) {
+                return (await admittedRowState(row)).applied ? { state: "applied", result: row.existingId ?? row.creation } : { state: "pending" };
+            }
             if (row.isUpdate) {
                 return inspectUpdate(pmRoot, row.existingId, rowTag, row.parsed.status === "closed" || row.parsed.status === "canceled");
             }
@@ -1570,8 +1730,26 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
                 return { state: "applied", result: id };
             return { state: "pending" };
         };
-        const apply = async () => {
+        const apply = async () => inSettingsTransaction(pmRoot, () => withSettingsFence(pmRoot, async () => {
             const ownershipTags = [ownershipTag, rowTag];
+            if (row.revision !== undefined) {
+                await opts.onAdmissionBoundary?.("before_write", row.existingId ?? row.creation);
+                await verifySettings(pmRoot);
+                await admissionTargetRevision(pmRoot, row.existingId ?? row.creation, sequenceHeads.get(row.existingId) ?? row.revision);
+                if (!row.isUpdate && opts.keyField && row.keyValue && csvKeyIndex(certifyCompleteListResult(await listAllComplete({}, { pmRoot })).items).has(normalizeKeyValue(row.keyValue))) {
+                    throw new AdmissionRefusal("csv_admission_target_changed", "A key appeared after admission planning. Re-read current SDK state and preview a fresh import before writing.");
+                }
+                const options = nativeCsvOptions(row.parsed, comparisonSettings, row.isUpdate, row.isUpdate ? undefined : row.keyValue, opts.source, ownershipTags);
+                if (row.isUpdate)
+                    await updateNativeCsv(row.existingId, { ...options, author, message: `${rowTag}:apply` }, { pmRoot });
+                else
+                    await createNativeCsv({ ...options, id: row.creation, author, message: `${rowTag}:create` }, { pmRoot });
+                appliedId = row.existingId ?? row.creation;
+                wrote.add(row.rowIndex);
+                if (sequences.has(row.existingId))
+                    await admittedRowState(row);
+                return appliedId;
+            }
             if (row.isUpdate) {
                 upsertUpdate(pmRoot, row.existingId, row.parsed, opts.source, ownershipTags, `${rowTag}:apply`);
                 appliedId = row.existingId;
@@ -1580,28 +1758,53 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
             const newId = upsertCreate(pmRoot, row.parsed, opts.keyField ? row.keyValue : undefined, opts.source, ownershipTags);
             appliedId = newId;
             return newId;
-        };
-        const prepareCompensation = async () => row.isUpdate ? captureUpdateCompensation(pmRoot, row.existingId, rowTag, author) : undefined;
+        }));
+        const prepareCompensation = async () => row.isUpdate ? inSettingsTransaction(pmRoot, () => withSettingsFence(pmRoot, () => 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);
-            // Strip both markers so the rolled-back row is no longer recognized as
-            // applied on a retry (marker-presence — not status — is the applied signal).
-            if (typeof id === "string" && id)
-                compensateCreate(pmRoot, id, [rowTag, ownershipTag]);
+            rollback ??= captureSettings(pmRoot, opts.admission === undefined ? importSettingsChanged : admissionSettingsChanged);
+            const snapshot = await rollback;
+            return inSettingsTransaction(pmRoot, () => useSettings(pmRoot, snapshot, () => withSettingsFence(pmRoot, async () => {
+                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 ?? row.creation ?? applied.byRowIndex.get(row.rowIndex);
+                // Strip both markers so the rolled-back row is no longer recognized as
+                // applied on a retry (marker-presence — not status — is the applied signal).
+                if (typeof id === "string" && id) {
+                    if (row.revision !== undefined) {
+                        await opts.onAdmissionBoundary?.("before_compensate", id);
+                        await verifySettings(pmRoot);
+                        const current = await readUpdateDocument(pmRoot, id);
+                        const status = resolveRuntimeStatusRegistry(snapshot.settings.schema).close_status;
+                        const options = { ...buildMutationIntent({ parent: current.metadata.parent, assignee: current.metadata.assignee,
+                                sprint: current.metadata.sprint, release: current.metadata.release, blockedBy: current.metadata.blocked_by,
+                                status, closeReason: "Atomic CSV import rolled back", author, message: `${rowTag}:compensate` }, "patch"), removeTags: [rowTag, ownershipTag] };
+                        await admissionTargetRevision(pmRoot, id, "owned", rowTag);
+                        await updateNativeCsv(id, options, { pmRoot });
+                    }
+                    else
+                        compensateCreate(pmRoot, id, [rowTag, ownershipTag]);
+                }
+            })));
         };
         return { id: stepId, inspect, apply, prepareCompensation, compensate };
     });
     let committed;
     try {
-        committed = await commitTransaction({ transactionId, author, steps });
+        committed = await commitTransaction({ transactionId, author, steps, onTransition: event => {
+                if (journalStatus === "compensating" && ["compensated", "prepared"].includes(event.transition)) {
+                    throw new CommandError("Pending atomic compensation was recovered. Inspect the retained audit and retry the original import; this attempt did not restart forward work.", EXIT_CODE.USAGE);
+                }
+            } });
     }
     catch (err) {
+        rethrowSettingsChange(err, opts.admission === undefined ? importSettingsChanged : admissionSettingsChanged);
+        const admissionFailure = findAdmissionFailure(err);
+        if (admissionFailure)
+            throw admissionFailure;
         const msg = errorMessage(err);
         // The coordinator invokes compensations in reverse order, but this package
         // cannot prove a clean tracker: create cleanup deliberately tolerates an
@@ -1609,17 +1812,18 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
         // 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);
     }
+    await verifySettings(pmRoot);
     // Tally the ImportResult from the committed step results. Each committed
     // result is the created/updated item id. Only rows that were NOT already
     // applied at the start of this run (i.e. newly committed by this attempt)
     // 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 = atomicStepId(row.rowIndex, row.existingId);
-        const res = committed.results[stepId];
+        const stepId = atomicStepId(row.rowIndex, row.existingId, row.revision, row.creation);
+        const res = Object.hasOwn(committed.results, stepId) ? committed.results[stepId] : undefined;
         if (res === undefined)
             continue;
-        const alreadyApplied = applied.byRowIndex.has(row.rowIndex);
+        const alreadyApplied = row.revision === undefined ? applied.byRowIndex.has(row.rowIndex) : !wrote.has(row.rowIndex);
         if (alreadyApplied)
             continue;
         if (row.isUpdate)
@@ -1629,6 +1833,20 @@ async function importCSVAtomic(pmRoot, filePath, opts) {
     }
     return result;
 }
+/** Pin atomic planning, retry inspection and row batches to one settings revision. */
+async function importCSVAtomic(pmRoot, filePath, opts, admittedDigest) {
+    pmRoot = resolve(pmRoot);
+    filePath = resolve(filePath);
+    const captured = { ...opts, fieldMap: { ...opts.fieldMap }, filter: opts.filter ? { ...opts.filter } : undefined };
+    const prepared = prepareInMemoryImport(filePath, captured, admittedDigest);
+    if (captured.dryRun || !captured.commitTransaction)
+        return importCSVAtomicInternal(pmRoot, filePath, captured, prepared);
+    return withSettings(pmRoot, captured.admission === undefined ? importSettingsChanged : admissionSettingsChanged, () => importCSVAtomicInternal(pmRoot, filePath, captured, prepared));
+}
+/** Keep settings drift within the existing command error family. */
+function importSettingsChanged() {
+    return new CommandError("csv_settings_changed: Settings changed during atomic import. Inspect compensation and preview current settings before retrying.", EXIT_CODE.USAGE, "csv_settings_changed");
+}
 /**
  * Streaming import: reads the file via a readable stream so large CSV files
  * are never fully loaded into memory. The header row (or positional
@@ -1677,17 +1895,15 @@ async function importCSVStreaming(pmRoot, filePath, opts) {
  * Flag names verified against the installed `pm create`/`pm update` contracts:
  * --parent, --assignee, --sprint, --release, --blocked-by.
  */
-function appendRelationalArgs(args, p) {
-    if (p.parent)
-        args.push("--parent", p.parent);
-    if (p.assignee)
-        args.push("--assignee", p.assignee);
-    if (p.sprint)
-        args.push("--sprint", p.sprint);
-    if (p.release)
-        args.push("--release", p.release);
-    if (p.blocked_by)
-        args.push("--blocked-by", p.blocked_by);
+function csvRelationalOptions(p) {
+    // Updates own only nonempty cells. Absent/empty cells preserve current state,
+    // including all dependency edges; create mode still suppresses ambient defaults.
+    return Object.fromEntries(Object.entries({ parent: p.parent, assignee: p.assignee,
+        sprint: p.sprint, release: p.release, blockedBy: p.blocked_by }).filter(([, value]) => value !== undefined));
+}
+/** Render the same selected scope options used by admitted native mutations. */
+function appendRelationalArgs(args, p, mode) {
+    args.push(...mutationScopeArguments(csvRelationalOptions(p), mode));
 }
 /** Append item fields shared by create and update mutation commands. */
 function appendMutableItemArgs(args, p, preserveEmptyBody) {
@@ -1699,7 +1915,7 @@ function appendMutableItemArgs(args, p, preserveEmptyBody) {
         args.push("--type", p.type);
     if (p.deadline)
         args.push("--deadline", p.deadline);
-    appendRelationalArgs(args, p);
+    appendRelationalArgs(args, p, preserveEmptyBody ? "patch" : "create");
 }
 /** Build a normal validated close with factual CSV provenance and outcome fields. */
 function csvCloseArgs(pmRoot, id, reason, expected, actual) {
@@ -1718,6 +1934,21 @@ function importCloseReason(status, source) {
     const origin = source ? ` from ${source}` : "";
     return `Imported${origin} (source status: ${status})`;
 }
+/** Native options shared by admitted previews and apply; SDK owns field and lifecycle normalization. */
+function nativeCsvOptions(p, settings, update, keyValue, source, ownershipTags) {
+    const tags = [...p.tags, ...(!update && keyValue ? [`${KEY_TAG_PREFIX}${encodeKeyTagValue(normalizeKeyValue(keyValue))}`] : []),
+        ...(source ? [`${SOURCE_TAG_PREFIX}${encodeKeyTagValue(source)}`] : []), ...ownershipTags];
+    const values = buildMutationIntent({ title: p.title, ...(p.type ? { type: p.type } : {}), ...(p.status ? { status: p.status } : {}),
+        ...(!update && p.status === undefined ? { status: resolveRuntimeStatusRegistry(settings.schema).open_status } : {}),
+        ...(p.priority !== undefined ? { priority: p.priority } : {}), ...(p.body !== undefined ? { body: p.body } : {}),
+        ...(p.deadline ? { deadline: p.deadline } : {}), ...csvRelationalOptions(p),
+        ...(update ? { addTags: tags } : { tags: tags.join(",") }) }, update ? "patch" : "create");
+    const options = update ? values : pinCreateDefaults(values, settings);
+    if (options.status !== undefined && isTerminalStatus(options.status, resolveRuntimeStatusRegistry(settings.schema))) {
+        options.closeReason = importCloseReason(options.status, source);
+    }
+    return options;
+}
 /**
  * Create a new item, optionally carrying a csv-key provenance tag. Returns the
  * new id (empty string when `pm create` did not report one AND the row is not
@@ -1768,7 +1999,7 @@ function upsertCreate(pmRoot, p, keyValue, source, extraTags) {
         tags.push(...extraTags);
     // See the function docstring: terminal `closed` is applied via pm close
     // after the create, never via `pm create --status closed`.
-    const createStatus = p.status === "closed" ? "open" : p.status;
+    const createStatus = !p.status || p.status === "closed" ? "open" : p.status;
     const args = ["--path", pmRoot, "create", "--title", p.title, "--status", createStatus, "--json"];
     appendMutableItemArgs(args, p, false);
     if (tags.length > 0)
@@ -1902,7 +2133,7 @@ function upsertUpdate(pmRoot, id, p, source, extraTags, historyMessage) {
     if (addTags.length > 0)
         args.push("--add-tags", addTags.join(","));
     // `update` cannot set a closed status; only set non-closed statuses here.
-    if (p.status !== "closed" && p.status !== "canceled")
+    if (p.status && p.status !== "closed" && p.status !== "canceled")
         args.push("--status", p.status);
     const r = spawnSync("pm", args, { encoding: "utf-8", maxBuffer: pmListMaxBuffer() });
     // `pm update` is a WRITE: a null status (receipt overrun or a signal kill)
@@ -1954,7 +2185,7 @@ function validateCSV(filePath, opts) {
  * Core validation logic over already-parsed headers + rows. Pure and
  * side-effect-free so it can be unit tested directly.
  */
-function validateParsedCSV(rawHeaders, dataRows, fieldMap) {
+function validateParsedCSV(rawHeaders, dataRows, fieldMap, statusKnown = status => KNOWN_STATUSES.has(status)) {
     const mappedColumns = applyFieldMap(rawHeaders, fieldMap);
     const hasTitleColumn = mappedColumns.includes("title");
     const issues = [];
@@ -1980,7 +2211,7 @@ function validateParsedCSV(rawHeaders, dataRows, fieldMap) {
         }
         if (statusIdx >= 0) {
             const status = (row[statusIdx] ?? "").trim().toLowerCase();
-            if (status && !KNOWN_STATUSES.has(status))
+            if (status && !statusKnown(status))
                 rowsWithUnknownStatus++;
         }
         if (priorityIdx >= 0) {
@@ -2085,6 +2316,13 @@ function assertStrictImportReady(filePath, opts) {
 }
 /** Parse one host option record into the canonical CSV import contract. */
 function parseCsvImportInvocation(rawOptions, dryRun) {
+    const admitted = readBoolOption(rawOptions, "admission");
+    if (admitted && ["status", "type", "priority"].some(key => rawOptions[key] !== undefined && (typeof rawOptions[key] !== "string" || !rawOptions[key].trim()))) {
+        throw new AdmissionRefusal("csv_admission_options", "Supply nonempty configured status/type and integer priority filter values for admitted imports.");
+    }
+    const filter = parseImportFilter(rawOptions["status"], rawOptions["type"], rawOptions["priority"]);
+    if (admitted && rawOptions["status"] !== undefined)
+        filter.status = rawOptions["status"];
     return {
         strict: readBoolOption(rawOptions, "strict"),
         options: {
@@ -2095,16 +2333,17 @@ function parseCsvImportInvocation(rawOptions, dryRun) {
             keyField: (rawOptions["key"] ?? "").trim().toLowerCase() || undefined,
             encoding: resolveEncoding(rawOptions["encoding"]),
             source: (rawOptions["source"] ?? "").trim() || undefined,
-            filter: parseImportFilter(rawOptions["status"], rawOptions["type"], rawOptions["priority"]),
+            filter,
             skipHeaders: readBoolOption(rawOptions, "skip-headers", "skipHeaders"),
             stream: readBoolOption(rawOptions, "stream"),
             atomic: readBoolOption(rawOptions, "atomic"),
+            admission: admitted ? {} : undefined,
         },
     };
 }
 /** Validate strict input, then execute one fully parsed import invocation. */
 function executeCsvImport(pmRoot, filePath, invocation, commitTransaction, atomicAuthor) {
-    if (invocation.strict) {
+    if (invocation.strict && invocation.options.admission === undefined) {
         assertStrictImportReady(filePath, {
             delimiter: invocation.options.delimiter,
             fieldMap: invocation.options.fieldMap,
@@ -2177,7 +2416,7 @@ function selectExportColumns(spec, extraValid = []) {
  */
 async function resolveExportColumns(pmRoot, columnsSpec, discover) {
     const discovered = discover ? await discoverCustomFields(pmRoot) : [];
-    const columnSource = {};
+    const columnSource = Object.create(null);
     for (const f of discovered) {
         if (f.key !== f.metadataKey)
             columnSource[f.key] = f.metadataKey;
@@ -2253,8 +2492,8 @@ function buildCsvExport(pmRoot, opts, spawn = spawnPm) {
             item.csv_source = decodeKeyTagValue(sourceTag.slice(SOURCE_TAG_PREFIX.length));
     }
     const dataRows = items.map((item) => opts.columns.map((col) => {
-        const prop = opts.columnSource?.[col] ?? col;
-        const val = item[prop];
+        const prop = opts.columnSource && Object.hasOwn(opts.columnSource, col) ? opts.columnSource[col] : col;
+        const val = Object.hasOwn(item, prop) ? item[prop] : undefined;
         if (val === undefined || val === null)
             return "";
         if (Array.isArray(val)) {
@@ -2302,9 +2541,11 @@ async function prepareCsvExport(pmRoot, rawOptions) {
 }
 export default {
     name: "pm-csv",
-    version: "2026.10.28",
+    version: "2026.10.30",
     activate(api) {
         registerTableSchemaCommands(api);
+        registerJoinCommands(api);
+        registerAdmissionCommand(api);
         // -----------------------------------------------------------------------
         // Schema: register an optional `csv_source` provenance field so imported
         // items can record where they came from (set via `pm csv import --source`).
@@ -2361,7 +2602,7 @@ export default {
             description: "Export a conflict-aware CSV edit session and immutable baseline JSON (maximum 1000 items).",
             flags: [
                 { long: "--output", value_name: "file", description: "New CSV filename; baseline uses <file>.session.json" },
-                { long: "--ids", value_name: "ids", description: "Comma-separated canonical item IDs (default: complete tracker)" },
+                { long: "--ids", value_name: "ids", description: "Comma-separated distinct canonical item IDs; aliases refuse (default: complete tracker)" },
             ],
             async run(ctx) {
                 const output = ctx.options["output"];
@@ -2427,6 +2668,9 @@ export default {
                 "--key for idempotent re-import (upsert), --encoding for non-UTF-8 files, " +
                 "--source to record import provenance in the csv_source field, and " +
                 "--status/--type/--priority to import only matching rows (others are skipped). " +
+                "Keyed updates preserve absent columns and empty cells; nonempty cells set supported fields. " +
+                "Use none/null to clear parent/assignee/sprint/release/blocked_by; tags are additive and dependency edges are preserved. " +
+                "Custom fields are export-only. Creates suppress implicit focus and planning defaults. " +
                 "Use --strict to fail before writing when row-level data issues are present.",
             arguments: [{ name: "file", required: true, description: "CSV file to import" }],
             intent: "import items from a CSV file into pm",
@@ -2445,7 +2689,7 @@ export default {
                 "pm csv import items.csv --dry-run",
                 "pm csv import headerless.csv --skip-headers   # no header row, positional columns",
                 "pm csv import big.csv --stream   # stream large files without loading into memory",
-                "pm csv import tasks.csv --atomic # writer-locked, crash-recoverable import",
+                "pm csv import tasks.csv --atomic # SDK-coordinated, crash-recoverable import",
             ],
             flags: [
                 { long: "--delimiter", value_name: "char", description: "Field delimiter, or alias tab|comma|semicolon|pipe (default: ,)" },
@@ -2461,7 +2705,8 @@ 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 updates restore captured prior values unless a conflict prevents safe compensation. Inspect and reconcile any marked orphan before retrying. Incompatible with --stream" },
+                { long: "--admission", description: "Require a full bounded validation pass and the declared atomic materialization budgets; requires --atomic" },
+                { long: "--atomic", description: "Use one SDK-coordinated, 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];
@@ -2479,7 +2724,7 @@ export default {
                     ctx.sdk?.commitWorkspaceTransaction, ctx.global?.author ?? undefined);
                 }
                 catch (err) {
-                    if (err instanceof CommandError)
+                    if (err instanceof CommandError || err instanceof AdmissionRefusal)
                         throw err;
                     const msg = errorMessage(err);
                     const exitCode = /ENOENT|no such file/i.test(msg) ? EXIT_CODE.NOT_FOUND : EXIT_CODE.GENERIC_FAILURE;
@@ -2697,4 +2942,6 @@ export { importCSV };
 export { applyEditSession, exportEditSession, parseEditSession, editSessionHeader, EDIT_FIELDS, EditRefusal } from "./roundtrip.js";
 export { importLineage, writeLineageBundle, lineageDigest, LINEAGE_FIELDS, LineageRefusal } from "./lineage.js";
 export { describeTable, previewTable, parseTableSchema, importNegotiatedTable, TableSchemaRefusal } from "./table-schema.js";
+export { previewJoins, applyJoins, JoinRefusal } from "./join-plans.js";
+export { admitCSV, assertCSVAdmission, AdmissionRefusal, ADMISSION_LIMITS } from "./admission.js";
 //# sourceMappingURL=index.js.map