things-api 0.11.0 → 0.13.0

package/dist/surface-copy.js.map

@@ -1 +1 @@
-{"version":3,"file":"surface-copy.js","sourceRoot":"","sources":["../src/surface-copy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,yCAAyC;AACzC,MAAM,CAAC,MAAM,WAAW,GAAG,kDAAkD,CAAC;AAE9E,gEAAgE;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC;AAExC,6CAA6C;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEjD,uDAAuD;AACvD,MAAM,CAAC,MAAM,UAAU,GAAG,qBAAqB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,oEAAoE,CAAC;AACjG,MAAM,CAAC,MAAM,YAAY,GAAG,+DAA+D,CAAC;AAE5F,sEAAsE;AACtE,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,UAAU,GAAG,kCAAkC,kBAAkB,GAAG,CAAC;AAElF,6DAA6D;AAC7D,MAAM,CAAC,MAAM,QAAQ,GAAG,oCAAoC,CAAC;AAE7D,2EAA2E;AAC3E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,eAAe,GAAG,mGAAmG,kBAAkB,gCAAgC,CAAC;AAErL,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,4DAA4D,qBAAqB,sCAAsC,CAAC;AAE1J,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG,oDAAoD,CAAC;AAErF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,qJAAqJ,CAAC;AAExJ;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAsD;IACnF,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,IAAI;YACP,OAAO,EAAE,CAAC;QACZ,KAAK,OAAO;YACV,OAAO;gBACL,wEAAwE;oBACtE,8CAA8C;aACjD,CAAC;QACJ,KAAK,iBAAiB;YACpB,OAAO;gBACL,6EAA6E;oBAC3E,8CAA8C;aACjD,CAAC;IACN,CAAC;AACH,CAAC"}
+{"version":3,"file":"surface-copy.js","sourceRoot":"","sources":["../src/surface-copy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,yCAAyC;AACzC,MAAM,CAAC,MAAM,WAAW,GAAG,kDAAkD,CAAC;AAE9E,gEAAgE;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC;AAExC,6CAA6C;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEjD,uDAAuD;AACvD,MAAM,CAAC,MAAM,UAAU,GAAG,qBAAqB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,oEAAoE,CAAC;AACjG,MAAM,CAAC,MAAM,YAAY,GAAG,+DAA+D,CAAC;AAE5F,sEAAsE;AACtE,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,UAAU,GAAG,kCAAkC,kBAAkB,GAAG,CAAC;AAElF,6DAA6D;AAC7D,MAAM,CAAC,MAAM,QAAQ,GAAG,oCAAoC,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,sDAAsD,CAAC;AAEhF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,eAAe,GAAG,mGAAmG,kBAAkB,gCAAgC,CAAC;AAErL,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,4DAA4D,qBAAqB,sCAAsC,CAAC;AAE1J,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG,oDAAoD,CAAC;AAErF,oFAAoF;AACpF,MAAM,CAAC,MAAM,gBAAgB,GAAG,sEAAsE,UAAU,yCAAyC,CAAC;AAE1J;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,qJAAqJ,CAAC;AAExJ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,obAAob,CAAC;AAEvb;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAsD;IACnF,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,IAAI;YACP,OAAO,EAAE,CAAC;QACZ,KAAK,OAAO;YACV,OAAO;gBACL,wEAAwE;oBACtE,8CAA8C;aACjD,CAAC;QACJ,KAAK,iBAAiB;YACpB,OAAO;gBACL,6EAA6E;oBAC3E,8CAA8C;aACjD,CAAC;IACN,CAAC;AACH,CAAC"}

package/dist/write/batch.d.ts

@@ -1,12 +1,3 @@
-/**
- * Batch mutations: N ops through the SAME pipeline as single mutations —
- * every op individually pre-read, guarded, verified, and audited. The wins
- * are amortization (one process, one DB handle, one config load) and a
- * per-op result stream; there is deliberately NO transactional semantics
- * (the app's surfaces have none to offer). Ops run SEQUENTIALLY: the
- * mutation lock serializes them anyway, and create-probe verification must
- * never race.
- */
 import { type OperationKind } from "./operations.ts";
 import { type WriteDeps, type WriteOptions } from "./pipeline.ts";
 import { type ReorderResult } from "./reorder.ts";
@@ -14,12 +5,36 @@ import { type ReorderResult } from "./reorder.ts";
 export interface BatchOp {
     op: OperationKind;
     params: Record<string, unknown>;
+    /**
+     * Client handle for the uuid this op CREATES — a later line references it as
+     * `"$tempId"` (or `"$tempId.instance"` / `"$tempId.replaced"`) in any
+     * ref-accepting param. Valid only on uuid-minting ops (never `tag.add` — tags
+     * have no uuid; reference a tag by its title). `[A-Za-z0-9_-]{1,32}`; unique
+     * within one batch.
+     */
+    tempId?: string;
+    /**
+     * Client idempotency id: a resubmitted batch whose line carries the same id
+     * as a prior successful change is skipped (reported already-applied) instead
+     * of re-created. `[A-Za-z0-9_-]{1,64}`.
+     */
+    opId?: string;
     /** Per-op acknowledgements/overrides (a safe subset of WriteOptions). */
     options?: {
         acknowledgeChecklistReset?: boolean;
         acknowledgeProjectReopen?: boolean;
         dangerouslyPermanent?: boolean;
         acknowledgeTagSubtree?: boolean;
+        /** Delete a non-empty area together with its contents (area.delete). */
+        allowNonEmptyArea?: boolean;
+        /**
+         * Acknowledge a GUI-driven op (make-repeating, convert-to-project, …) — the
+         * second of its two keys. Required for any ui-drive op (several of which are
+         * uuid-minting, so tempId-eligible), or the per-leg H-UI-DRIVE gate blocks it.
+         */
+        dangerouslyDriveGui?: boolean;
+        /** Create any missing tag (mkdir-p for parent/child) instead of failing on an unknown tag. */
+        createTags?: boolean;
         vector?: WriteOptions["vector"];
         verifyTimeoutMs?: number;
         maxDisruption?: WriteOptions["maxDisruption"];
@@ -33,11 +48,35 @@ export type BatchItemOutcome = ReorderResult | {
     kind: "skipped";
     op: string;
     detail: string;
+} | {
+    /** An idempotency-id match: the op was already applied by an earlier submission. */
+    kind: "already-applied";
+    op: string;
+    uuid: string;
+    detail: string;
 };
 export interface BatchItemResult {
     index: number;
     op: string;
     outcome: BatchItemOutcome;
+    /** Echoed when the op declared a temp id (ADDITIVE). */
+    tempId?: string;
+    /** The uuid bound to this op's temp id, once the leg minted one (ADDITIVE). */
+    boundUuid?: string;
+    /** Echoed when the op carried a client idempotency id (ADDITIVE). */
+    opId?: string;
+}
+/** The whole-batch result: the per-op stream plus the batch-level additions. */
+export interface BatchResult {
+    results: BatchItemResult[];
+    /** Every temp id that bound a uuid → that uuid (ADDITIVE; empty when none declared). */
+    tempIdMapping: Record<string, string>;
+    /**
+     * The batch-level undo token — pass it to `things undo --txn <token>` to
+     * reverse the WHOLE submission as one unit. Absent for a dry-run, an
+     * all-rejected batch, or one where no leg reached the pipeline.
+     */
+    undoToken?: string;
 }
 export interface BatchOptions {
     /** Stop at the first non-ok outcome; remaining ops report kind "skipped". */
@@ -48,4 +87,4 @@ export interface BatchOptions {
 }
 /** True when an outcome should be treated as a failure for --fail-fast/exit. */
 export declare function outcomeFailed(outcome: BatchItemOutcome): boolean;
-export declare function runBatch(deps: WriteDeps, ops: BatchOp[], options?: BatchOptions, onResult?: (result: BatchItemResult) => void): Promise<BatchItemResult[]>;
+export declare function runBatch(deps: WriteDeps, ops: BatchOp[], options?: BatchOptions, onResult?: (result: BatchItemResult) => void): Promise<BatchResult>;

package/dist/write/batch.js

@@ -1,100 +1,452 @@
-/**
- * Batch mutations: N ops through the SAME pipeline as single mutations —
- * every op individually pre-read, guarded, verified, and audited. The wins
- * are amortization (one process, one DB handle, one config load) and a
- * per-op result stream; there is deliberately NO transactional semantics
- * (the app's surfaces have none to offer). Ops run SEQUENTIALLY: the
- * mutation lock serializes them anyway, and create-probe verification must
- * never race.
- */
 import { OPERATION_KINDS } from "./operations.js";
-import { runMutation } from "./pipeline.js";
+import { findAppliedOpId, OP_ID_RE } from "./opid.js";
+import { fingerprintLabel, runMutation } from "./pipeline.js";
 import { runReorder } from "./reorder.js";
+import { readAuditRecords } from "./undo.js";
 const KNOWN_OPS = new Set(OPERATION_KINDS);
+/**
+ * Ops that MINT a uuid, so may declare a `tempId` — the ratified rule is
+ * "anything that creates a new uuid". NB: `tag.add` is deliberately absent (tags
+ * have no uuid — identity is the title).
+ */
+const UUID_MINTING_OPS = new Set([
+    "todo.add",
+    "todo.add-logged",
+    "project.add",
+    "project.add-repeating",
+    "area.add",
+    "project.add-heading",
+    "todo.duplicate",
+    "project.duplicate",
+    "todo.make-repeating",
+    "project.make-repeating",
+    "todo.convert-to-project",
+    "project.promote-heading",
+]);
+const TEMP_ID_RE = /^[A-Za-z0-9_-]{1,32}$/;
+/**
+ * Param keys whose values are REFERENCES (uuid / name / container) — the only
+ * places a `"$temp"` handle is resolved. A value starting with `$` anywhere
+ * else (a title, notes) is a literal, never a ref. Container refs nest the id
+ * under `.uuid`; `uuids` is a list.
+ */
+const REF_KEYS = new Set([
+    "uuid",
+    "uuids",
+    "target",
+    "before",
+    "after",
+    "project",
+    "area",
+    "container",
+    "heading",
+    "headings",
+]);
 /** True when an outcome should be treated as a failure for --fail-fast/exit. */
 export function outcomeFailed(outcome) {
-    return outcome.kind !== "ok" && outcome.kind !== "dry-run";
+    return outcome.kind !== "ok" && outcome.kind !== "dry-run" && outcome.kind !== "already-applied";
+}
+/**
+ * Pre-flight scan of every declared `tempId`, BEFORE any leg runs. Returns the
+ * name→line index of valid declarations and, per offending line, the usage
+ * detail. Any declaration error rejects the WHOLE batch (nothing executes) —
+ * a temp-id script with a bad/duplicate/misplaced handle is a structural error,
+ * like a torn JSONL line.
+ */
+function validateDeclarations(ops) {
+    const declIndex = new Map();
+    const errors = new Map();
+    for (let i = 0; i < ops.length; i++) {
+        const entry = ops[i];
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const tempId = entry.tempId;
+        if (tempId === undefined)
+            continue;
+        if (entry.op === "tag.add") {
+            errors.set(i, 'tempId is not valid on "tag.add": a tag has no uuid to bind — reference a tag by its title instead');
+            continue;
+        }
+        if (!UUID_MINTING_OPS.has(entry.op)) {
+            errors.set(i, `tempId is only valid on an op that creates something (e.g. todo.add, project.add, project.add-heading) — not "${entry.op}"`);
+            continue;
+        }
+        if (typeof tempId !== "string" || !TEMP_ID_RE.test(tempId)) {
+            errors.set(i, "tempId must match [A-Za-z0-9_-] and be 1–32 characters");
+            continue;
+        }
+        const prior = declIndex.get(tempId);
+        if (prior !== undefined) {
+            errors.set(i, `duplicate tempId "${tempId}" (already declared on line ${prior + 1})`);
+            continue;
+        }
+        declIndex.set(tempId, i);
+    }
+    return { declIndex, errors };
+}
+/** Parse a `"$name"` / `"$name.instance"` token into its handle + accessor. */
+function parseRef(value) {
+    const body = value.slice(1); // drop the leading "$"
+    const dot = body.indexOf(".");
+    if (dot < 0)
+        return { name: body };
+    return { name: body.slice(0, dot), accessor: body.slice(dot + 1) };
+}
+/** Resolve one `$`-token to a uuid, or a fail-closed usage detail. */
+function resolveRef(value, declIndex, bindings, currentIndex) {
+    const { name, accessor } = parseRef(value);
+    const declaredAt = declIndex.get(name);
+    if (declaredAt === undefined) {
+        return {
+            ok: false,
+            detail: `unresolved-temp-ref: "${value}" names no tempId declared in this batch`,
+        };
+    }
+    const bound = bindings.get(name);
+    if (bound === undefined) {
+        if (declaredAt > currentIndex) {
+            return {
+                ok: false,
+                detail: `unresolved-temp-ref: "${value}" is a forward reference — tempId "${name}" is declared later (line ${declaredAt + 1})`,
+            };
+        }
+        return {
+            ok: false,
+            detail: `unresolved-temp-ref: tempId "${name}" bound nothing (its op failed or was skipped) — cannot resolve "${value}"`,
+        };
+    }
+    if (accessor === undefined)
+        return { ok: true, uuid: bound.primary };
+    if (accessor === "instance") {
+        if (bound.instance === null) {
+            return { ok: false, detail: `"${value}" has no spawned-instance uuid to resolve` };
+        }
+        return { ok: true, uuid: bound.instance };
+    }
+    if (accessor === "replaced") {
+        if (bound.replaced === null) {
+            return { ok: false, detail: `"${value}" has no replaced uuid to resolve` };
+        }
+        return { ok: true, uuid: bound.replaced };
+    }
+    return {
+        ok: false,
+        detail: `"${value}" uses an unknown accessor ".${accessor}" (only .instance and .replaced exist)`,
+    };
+}
+/** True for a string that must be treated as a temp ref (leading `$`). */
+function isRef(value) {
+    return typeof value === "string" && value.startsWith("$");
+}
+/**
+ * Resolve every `$`-reference in a line's ref-accepting params against the
+ * current bindings. Returns rewritten params, or the FIRST fail-closed detail
+ * (that line becomes invalid; independent later lines still run).
+ */
+function resolveRefs(params, declIndex, bindings, currentIndex) {
+    const out = { ...params };
+    const resolveOne = (value) => resolveRef(value, declIndex, bindings, currentIndex);
+    for (const key of Object.keys(out)) {
+        if (!REF_KEYS.has(key))
+            continue;
+        const value = out[key];
+        if (isRef(value)) {
+            const r = resolveOne(value);
+            if (!r.ok)
+                return r;
+            out[key] = r.uuid;
+        }
+        else if (Array.isArray(value)) {
+            const next = [...value];
+            for (let i = 0; i < next.length; i++) {
+                if (isRef(next[i])) {
+                    const r = resolveOne(next[i]);
+                    if (!r.ok)
+                        return r;
+                    next[i] = r.uuid;
+                }
+            }
+            out[key] = next;
+        }
+        else if (typeof value === "object" && value !== null) {
+            // Container ref: resolve a `$` uuid sub-field, leave title/others alone.
+            const ref = value;
+            if (isRef(ref["uuid"])) {
+                const r = resolveOne(ref["uuid"]);
+                if (!r.ok)
+                    return r;
+                out[key] = { ...ref, uuid: r.uuid };
+            }
+        }
+    }
+    return { ok: true, params: out };
+}
+/** Does any line use a `$`-reference in a ref-accepting param? (dry-run gate) */
+function usesRef(params) {
+    for (const key of Object.keys(params)) {
+        if (!REF_KEYS.has(key))
+            continue;
+        const value = params[key];
+        if (isRef(value))
+            return true;
+        if (Array.isArray(value) && value.some(isRef))
+            return true;
+        if (typeof value === "object" &&
+            value !== null &&
+            isRef(value["uuid"]))
+            return true;
+    }
+    return false;
+}
+/** Bind a leg's discovered uuids to its temp id, once it verifies ok. */
+function bindingFromResult(result) {
+    if (typeof result.uuid !== "string")
+        return null;
+    return {
+        primary: result.uuid,
+        instance: result.repeating?.instanceUuid ?? null,
+        replaced: result.repeating?.replacedUuid ?? null,
+    };
+}
+/** Write the batch-level summary audit record (role "summary"; its undoToken is the batch token). */
+function auditBatchSummary(deps, startedAt, txnId, legCount, tempIdMapping, actor) {
+    const fp = deps.fingerprint();
+    const hasMapping = Object.keys(tempIdMapping).length > 0;
+    const record = {
+        v: 1,
+        ts: startedAt.toISOString(),
+        actor,
+        host: deps.config.host,
+        op: "batch",
+        uuid: null,
+        vector: null,
+        disruption: null,
+        invocation: `batch ×${legCount}`,
+        txn: { id: txnId, role: "summary" },
+        requested: { legCount, ...(hasMapping && { tempIdMapping }) },
+        pre: null,
+        observed: hasMapping ? { tempIdMapping } : null,
+        result: "ok",
+        verify: null,
+        durationMs: (deps.now?.() ?? new Date()).getTime() - startedAt.getTime(),
+        env: {
+            pkg: deps.pkgVersion ?? "0.0.1",
+            dbVersion: fp.observation.databaseVersion,
+            fingerprint: fingerprintLabel(fp, deps.config),
+        },
+    };
+    deps.audit.append(record);
 }
 export async function runBatch(deps, ops, options = {}, onResult) {
+    const startedAt = deps.now?.() ?? new Date();
+    const actor = options.actor ?? deps.config.actor;
+    const bindings = new Map();
+    const tempIdMapping = {};
+    // Pre-flight: validate every temp-id declaration BEFORE any leg runs.
+    const { declIndex, errors: declErrors } = validateDeclarations(ops);
+    if (declErrors.size > 0) {
+        const results = ops.map((entry, index) => {
+            const op = String(entry?.op);
+            const detail = declErrors.get(index);
+            const outcome = detail !== undefined
+                ? { kind: "invalid", op, detail }
+                : {
+                    kind: "skipped",
+                    op,
+                    detail: "not run — the batch has a temp-id declaration error (see the invalid line)",
+                };
+            const result = { index, op, outcome };
+            onResult?.(result);
+            return result;
+        });
+        return { results, tempIdMapping };
+    }
+    // opId idempotency reads the recent trail ONCE, before executing.
+    const usesOpId = ops.some((o) => typeof o === "object" && o !== null && o.opId !== undefined);
+    const priorRecords = usesOpId && deps.auditDirPath !== undefined ? readAuditRecords(deps.auditDirPath) : [];
+    const txnId = `txn-batch-${startedAt.getTime().toString(36)}-${process.pid.toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
     const results = [];
     let halted = false;
-    for (let index = 0; index < ops.length; index++) {
-        const entry = ops[index];
-        let outcome;
-        if (halted) {
-            outcome = {
-                kind: "skipped",
-                op: String(entry?.op),
-                detail: "skipped after earlier failure (--fail-fast)",
+    let legsDispatched = 0;
+    /** Bind (or rebind) a temp id to a discovered uuid so later `$refs` resolve. */
+    const bind = (tempId, binding) => {
+        bindings.set(tempId, binding);
+        tempIdMapping[tempId] = binding.primary;
+    };
+    /** Compute one line's outcome + bound uuid; mutates bindings/dispatch counter. */
+    const runLine = async (entry, index, tempId, opId) => {
+        if (typeof entry !== "object" || entry === null || typeof entry.op !== "string") {
+            return {
+                outcome: {
+                    kind: "invalid",
+                    op: String(entry?.op),
+                    detail: "each op needs {op, params}",
+                },
             };
         }
-        else if (typeof entry !== "object" || entry === null || typeof entry.op !== "string") {
-            outcome = {
-                kind: "invalid",
-                op: String(entry?.op),
-                detail: "each op needs {op, params}",
+        if (!KNOWN_OPS.has(entry.op)) {
+            return {
+                outcome: {
+                    kind: "invalid",
+                    op: entry.op,
+                    detail: `unknown op "${entry.op}" — see \`things capabilities\``,
+                },
             };
         }
-        else if (!KNOWN_OPS.has(entry.op)) {
-            outcome = {
-                kind: "invalid",
-                op: entry.op,
-                detail: `unknown op "${entry.op}" — see \`things capabilities\``,
+        if (typeof entry.params !== "object" || entry.params === null) {
+            return { outcome: { kind: "invalid", op: entry.op, detail: "params must be an object" } };
+        }
+        if (opId !== undefined && !OP_ID_RE.test(opId)) {
+            return {
+                outcome: {
+                    kind: "invalid",
+                    op: entry.op,
+                    detail: "opId must match [A-Za-z0-9_-] and be 1–64 characters",
+                },
             };
         }
-        else if (typeof entry.params !== "object" || entry.params === null) {
-            outcome = { kind: "invalid", op: entry.op, detail: "params must be an object" };
+        // opId idempotency: an earlier submission already applied this line — skip,
+        // report already-applied with the recorded uuid, and rebind it so later
+        // $refs still resolve.
+        if (opId !== undefined) {
+            const applied = findAppliedOpId(priorRecords, opId, startedAt);
+            if (applied !== undefined) {
+                const uuid = applied.uuid ?? "";
+                if (tempId !== undefined && uuid !== "")
+                    bind(tempId, { primary: uuid, instance: null, replaced: null });
+                return {
+                    outcome: {
+                        kind: "already-applied",
+                        op: entry.op,
+                        uuid,
+                        detail: "already applied by an earlier submission (matching opId in the change history) — not re-run",
+                    },
+                    ...(tempId !== undefined && uuid !== "" && { boundUuid: uuid }),
+                };
+            }
         }
-        else {
-            const writeOptions = {
-                ...(entry.options?.acknowledgeChecklistReset !== undefined && {
-                    acknowledgeChecklistReset: entry.options.acknowledgeChecklistReset,
-                }),
-                ...(entry.options?.acknowledgeProjectReopen !== undefined && {
-                    acknowledgeProjectReopen: entry.options.acknowledgeProjectReopen,
-                }),
-                ...(entry.options?.dangerouslyPermanent !== undefined && {
-                    dangerouslyPermanent: entry.options.dangerouslyPermanent,
-                }),
-                ...(entry.options?.acknowledgeTagSubtree !== undefined && {
-                    acknowledgeTagSubtree: entry.options.acknowledgeTagSubtree,
-                }),
-                ...(entry.options?.vector !== undefined && { vector: entry.options.vector }),
-                ...(entry.options?.verifyTimeoutMs !== undefined && {
-                    verifyTimeoutMs: entry.options.verifyTimeoutMs,
-                }),
-                ...(entry.options?.maxDisruption !== undefined && {
-                    maxDisruption: entry.options.maxDisruption,
-                }),
-                ...(options.dryRun === true && { dryRun: true }),
-                ...(options.actor !== undefined && { actor: options.actor }),
+        // Temp refs resolve only during real execution — nothing is created in a
+        // dry-run to bind them, so preview a ref-using line as skipped (not a false
+        // failure).
+        if (options.dryRun === true && usesRef(entry.params)) {
+            return {
+                outcome: {
+                    kind: "skipped",
+                    op: entry.op,
+                    detail: "not previewed — temp-references resolve only during real execution (not --dry-run)",
+                },
             };
-            try {
-                // Params arrive as parsed JSON; the pipeline's pre-read + guards are
-                // the runtime validators (loud on bad shapes), same as single ops.
-                outcome =
-                    entry.op === "reorder"
-                        ? // batch ops run sequentially by design: the mutation lock serializes them and create-probe verification must never race
-                            await runReorder(deps, entry.params, writeOptions)
-                        : // same sequencing requirement as the reorder branch above; batch is
-                            // a consumer entry point, so a consumer `when` normalizes to the zone
-                            await runMutation(deps, entry.op, entry.params, { ...writeOptions, normalizeWhen: true });
+        }
+        const resolved = resolveRefs(entry.params, declIndex, bindings, index);
+        if (!resolved.ok) {
+            return { outcome: { kind: "invalid", op: entry.op, detail: resolved.detail } };
+        }
+        const writeOptions = {
+            ...(entry.options?.acknowledgeChecklistReset !== undefined && {
+                acknowledgeChecklistReset: entry.options.acknowledgeChecklistReset,
+            }),
+            ...(entry.options?.acknowledgeProjectReopen !== undefined && {
+                acknowledgeProjectReopen: entry.options.acknowledgeProjectReopen,
+            }),
+            ...(entry.options?.dangerouslyPermanent !== undefined && {
+                dangerouslyPermanent: entry.options.dangerouslyPermanent,
+            }),
+            ...(entry.options?.acknowledgeTagSubtree !== undefined && {
+                acknowledgeTagSubtree: entry.options.acknowledgeTagSubtree,
+            }),
+            ...(entry.options?.allowNonEmptyArea !== undefined && {
+                allowNonEmptyArea: entry.options.allowNonEmptyArea,
+            }),
+            ...(entry.options?.dangerouslyDriveGui !== undefined && {
+                dangerouslyDriveGui: entry.options.dangerouslyDriveGui,
+            }),
+            ...(entry.options?.createTags !== undefined && { createTags: entry.options.createTags }),
+            ...(entry.options?.vector !== undefined && { vector: entry.options.vector }),
+            ...(entry.options?.verifyTimeoutMs !== undefined && {
+                verifyTimeoutMs: entry.options.verifyTimeoutMs,
+            }),
+            ...(entry.options?.maxDisruption !== undefined && {
+                maxDisruption: entry.options.maxDisruption,
+            }),
+            ...(options.dryRun === true && { dryRun: true }),
+            ...(opId !== undefined && { opId }),
+            // Group every leg under one txn so the batch summary's undo token replays
+            // the whole submission (dry-run legs are not recorded, so no txn).
+            ...(options.dryRun !== true && { txn: { id: txnId, role: "leg" } }),
+            actor,
+        };
+        try {
+            // Params arrive as parsed JSON; the pipeline's pre-read + guards are the
+            // runtime validators (loud on bad shapes), same as single ops.
+            const result = entry.op === "reorder"
+                ? // batch ops run sequentially by design: the mutation lock serializes them and create-probe verification must never race
+                    await runReorder(deps, resolved.params, writeOptions)
+                : // same sequencing requirement as the reorder branch above; batch is a
+                    // consumer entry point, so a consumer `when` normalizes to the zone
+                    await runMutation(deps, entry.op, resolved.params, { ...writeOptions, normalizeWhen: true });
+            if (options.dryRun !== true)
+                legsDispatched += 1;
+            // A leg binds its temp id ONLY when it verified ok — a failed leg
+            // (including a rule-mismatch that surfaces discovery uuids in its error)
+            // binds nothing, so later refs to it fail fast.
+            let boundUuid;
+            if (result.kind === "ok" && tempId !== undefined) {
+                const binding = bindingFromResult(result);
+                if (binding !== null) {
+                    bind(tempId, binding);
+                    boundUuid = binding.primary;
+                }
             }
-            catch (err) {
-                // Param-shape errors (exclusive combos etc.) surface per-op, not fatally.
-                outcome = {
+            return { outcome: result, ...(boundUuid !== undefined && { boundUuid }) };
+        }
+        catch (err) {
+            // Param-shape errors (exclusive combos etc.) surface per-op, not fatally.
+            return {
+                outcome: {
                     kind: "invalid",
                     op: entry.op,
                     detail: err instanceof Error ? err.message : String(err),
-                };
-            }
+                },
+            };
+        }
+    };
+    for (let index = 0; index < ops.length; index++) {
+        const entry = ops[index];
+        const tempId = typeof entry === "object" && entry !== null ? entry.tempId : undefined;
+        const opId = typeof entry === "object" && entry !== null ? entry.opId : undefined;
+        let outcome;
+        let boundUuid;
+        if (halted) {
+            outcome = {
+                kind: "skipped",
+                op: String(entry?.op),
+                detail: "skipped after earlier failure (--fail-fast)",
+            };
         }
-        const result = { index, op: String(entry?.op), outcome };
+        else {
+            ({ outcome, boundUuid } = await runLine(entry, index, tempId, opId));
+        }
+        const result = {
+            index,
+            op: String(entry?.op),
+            outcome,
+            ...(tempId !== undefined && { tempId }),
+            ...(boundUuid !== undefined && { boundUuid }),
+            ...(opId !== undefined && { opId }),
+        };
         results.push(result);
         onResult?.(result);
         if (options.failFast === true && !halted && outcomeFailed(outcome))
             halted = true;
     }
-    return results;
+    // Write the batch summary (and mint the batch undo token) when at least one
+    // leg actually reached the pipeline. Skipped for dry-run and all-rejected
+    // batches — there is nothing to undo.
+    let undoToken;
+    if (options.dryRun !== true && legsDispatched > 0) {
+        auditBatchSummary(deps, startedAt, txnId, legsDispatched, tempIdMapping, actor);
+        undoToken = txnId;
+    }
+    return { results, tempIdMapping, ...(undoToken !== undefined && { undoToken }) };
 }
 //# sourceMappingURL=batch.js.map