things-api 0.18.0 → 0.19.1

package/dist/write/commands.js

@@ -1,16 +1,17 @@
-import { decodeReminderTime, encodeReminderTime, localToday, reminderUrlToken, zonedWallInstant, } from "../model/dates.js";
+import { localToday, zonedWallInstant } from "../model/dates.js";
 import { byUuid } from "../read/detail.js";
 import { manualLogDateEpoch, pendingLogCount } from "../read/log-boundary.js";
 import { isLooseRef } from "../read/pseudo-area.js";
-import { reminderIsLive } from "../read/stage.js";
-import { areaMemberCounts, childTagTitles, classifyHeadingConvert, classifyHeadingDissolve, classifyHeadingMoveToProject, classifyProjectRepeat, computeHeadingMovePre, computeReorderPre, emptyPreState, loadTarget, projectChildren, projectStatus, projectSubtreeUuids, resolveArea, resolveHeading, resolveProject, resolveTag, sameTitleTaskUuids, trashedCount, } from "./pre-state.js";
+import { RESOLUTION_TIMESTAMP_EXPECTED } from "../surface-copy.js";
+import { areaMemberCounts, childTagTitles, classifyHeadingConvert, classifyHeadingDissolve, classifyHeadingMoveToProject, classifyProjectRepeat, computeHeadingMovePre, computeReorderPre, emptyPreState, loadTarget, projectChildren, projectStatus, projectSubtreeUuids, resolveArea, resolveHeading, resolveProject, resolveTag, sameTitleTaskUuids, seriesRowUuids, trashedCount, } from "./pre-state.js";
+import { assertNotesModesExclusive, normalizeReminder, updateAssertions, updateWireParams, whenAssertions, whenWithReminder, } from "./update-fields.js";
 import { resolveTagRefs } from "./tag-refs.js";
 import { PRIVATE_REORDER_COMMAND } from "./experimental.js";
 import { assertRepeatRule } from "./repeat-rule.js";
 import { assessOffRuleFirst, deadlineDriveNext, deriveFixedAnchor } from "./repeat-anchor.js";
 import { expectedRuleAssertions } from "./repeat-asserts.js";
 import { escapeAppleScript } from "./vectors/applescript.js";
-import { areaReorderSidebarRecipe, convertToProjectRecipe, dissolveHeadingRecipe, headingConvertToProjectRecipe, moveHeadingToProjectRecipe, makeRepeatingRecipe, pauseRepeatRecipe, projectMakeRepeatingRecipe, projectPauseRepeatRecipe, projectRescheduleRepeatRecipe, projectResumeRepeatRecipe, rescheduleRepeatRecipe, resumeRepeatRecipe, } from "./vectors/ui-recipes.js";
+import { areaReorderSidebarRecipe, convertToProjectRecipe, dissolveHeadingRecipe, headingConvertToProjectRecipe, moveHeadingChordRecipe, moveHeadingToProjectRecipe, makeRepeatingRecipe, createNextCopyRecipe, pauseRepeatRecipe, projectMakeRepeatingRecipe, projectPauseRepeatRecipe, projectRescheduleRepeatRecipe, projectResumeRepeatRecipe, rescheduleRepeatRecipe, resumeRepeatRecipe, } from "./vectors/ui-recipes.js";
 import { buildRepeatingFingerprint } from "./verify/delta.js";
 // ------------------------------------------------------------------ helpers
 function thingsUrl(command, params, token) {
@@ -65,65 +66,6 @@ function q(value) {
 function unsupportedVector(op, vector) {
     throw new Error(`${op} cannot be compiled for vector ${vector} (planner bug)`);
 }
-function whenAssertions(when, todayIso, opts = { mode: "add" }) {
-    // Strict shape check: an unvalidated string used to flow straight into the
-    // URL (e.g. "2026-07-20@09:30", the raw URL grammar) — the app would SET
-    // date+reminder while verification asserted the literal string as the date,
-    // reporting a false mismatch on a write that succeeded.
-    if (when !== "today" &&
-        when !== "evening" &&
-        when !== "anytime" &&
-        when !== "someday" &&
-        !/^\d{4}-\d{2}-\d{2}$/.test(when)) {
-        throw new RangeError(when.includes("@")
-            ? `invalid when "${when}" — a reminder time is a separate parameter (reminder: "HH:mm"; CLI --reminder), not an @ suffix`
-            : `invalid when "${when}" — expected today | evening | anytime | someday | YYYY-MM-DD`);
-    }
-    switch (when) {
-        case "today":
-            // Today's non-evening section: in Today (the `today` marker) AND NOT in the
-            // evening sub-bucket (the presence-keyed `evening` marker absent — asserted
-            // as null, which valuesEqual treats as absent). Gated to Today members under
-            // the verify clock exactly as the retired `todaySection` was.
-            //
-            // The `startDate` assertion differs by op (field bug §0½.8):
-            //  - ADD mints a fresh Today item with no schedule history, so the app dates
-            //    it EXACTLY today — exact equality is right.
-            //  - UPDATE of an item ALREADY in Today whose `startDate` has already arrived
-            //    (past or today): the app PRESERVES that historical date rather than
-            //    rewriting the storage byte to today (arrived-date law). Assert the
-            //    arrived-date PREDICATE (non-null and <= today) so a preserved historical
-            //    date verifies, while an undated deadline-only pull (null startDate) is
-            //    still rejected — the item's Today membership then rests only on a
-            //    deadline, not on the requested schedule.
-            return [
-                { field: "start", equals: "active" },
-                opts.mode === "update"
-                    ? { field: "startDate", satisfies: { predicate: "arrived-on-or-before", date: todayIso } }
-                    : { field: "startDate", equals: todayIso },
-                { field: "today", equals: true },
-                { field: "evening", equals: null },
-            ];
-        case "evening":
-            // The This-Evening sub-bucket: the `evening` marker (which implies `today`).
-            return [
-                { field: "start", equals: "active" },
-                { field: "startDate", equals: todayIso },
-                { field: "evening", equals: true },
-            ];
-        case "anytime":
-            return [
-                { field: "start", equals: "active" },
-                { field: "startDate", equals: null },
-            ];
-        case "someday":
-            return [{ field: "start", equals: "someday" }];
-        default:
-            // Concrete date: assert only the date — start-state semantics differ
-            // for past/today/future dates (only the date itself is invariant).
-            return [{ field: "startDate", equals: when }];
-    }
-}
 function sortedTags(tags) {
     return [...tags].toSorted();
 }
@@ -139,21 +81,28 @@ function applyTagRefs(db, pre, tags) {
     pre.missingTags = res.missing;
     pre.resolvedTagTitles = res.titles;
 }
-/** Round-trip normalization: "6:5"-style inputs → canonical "06:05". */
-function normalizeReminder(time) {
-    return decodeReminderTime(encodeReminderTime(time)) ?? time;
-}
 /**
- * The URL `when` value with an optional reminder token appended through the
- * deterministic emitter (never a bare 1–11 hour — oddity 2d).
+ * Is a destination container SUPPLIED? A PRESENCE check, not a duck-test (#580):
+ * the parameter schema (param-schema.ts) has already proven that a present ref is
+ * a `{uuid}`/`{title}` object, so anything else reaching here is an engine bug,
+ * not caller input — and it THROWS rather than reading as "no destination given",
+ * which is precisely how a bare-string `project` used to compile an Inbox capture
+ * with no placement and no placement assertion, then verify clean.
  */
-function whenWithReminder(when, reminder) {
-    if (reminder === undefined || reminder === null)
-        return when;
-    return `${when}@${reminderUrlToken(reminder)}`;
+export function containerGiven(ref) {
+    if (ref === undefined || ref === null)
+        return false;
+    assertContainerRef(ref);
+    return true;
 }
-function containerGiven(ref) {
-    return ref !== undefined && (ref.uuid !== undefined || ref.title !== undefined);
+/** Belt-and-braces: a present container reference must carry a uuid or a title. */
+export function assertContainerRef(ref) {
+    if (typeof ref !== "object" || Array.isArray(ref)) {
+        throw new RangeError(`a container reference must be an object naming a uuid or a title — received ${JSON.stringify(ref)}`);
+    }
+    if (ref.uuid === undefined && ref.title === undefined) {
+        throw new RangeError("a container reference must name a uuid or a title — it names neither");
+    }
 }
 /**
  * The create-probe title for the duplicate / identity-replacement ops, whose
@@ -351,108 +300,35 @@ const todoAdd = {
     },
 };
 /**
- * The effective reminder a when-bearing update should leave behind. A bare
- * `when=` CLEARS an existing reminder (R07/R20), so when the caller
- * re-schedules to today/evening/a date without addressing the reminder we
- * auto-preserve the current one; an explicit null is the intentional clear.
- *
- * §9n: a reminder whose row's `startDate` is already strictly PAST is
- * presentation-dead (the GUI hides its bell; the byte lingers in the DB). We do
- * NOT auto-preserve such a stale byte — carrying it into the re-schedule would
- * RESURRECT a reminder the user believes gone. A LIVE reminder (startDate
- * today/future) is preserved as before. The liveness test is the SAME
- * {@link reminderIsLive} predicate the read side gates on, consulted against the
- * target's CURRENT `startDate` under the response clock.
+ * The to-do / project update pair. Both legs — the URL parameters and the
+ * expected-delta assertions — are DERIVED from the single exhaustive registry in
+ * update-fields.ts (the #491 exhaustive-map doctrine): the only per-verb
+ * difference is the URL command name, so neither verb can accept a field the
+ * other drops, and a field added to `UpdateFields` breaks compilation there
+ * until every leg handles it.
  */
-function effectiveReminder(pre, params) {
-    if (params.reminder !== undefined)
-        return params.reminder;
-    const when = params.when;
-    const schedulable = when === "today" ||
-        when === "evening" ||
-        (typeof when === "string" && /^\d{4}-\d{2}-\d{2}$/.test(when));
-    if (!schedulable)
-        return null;
-    const target = pre.target;
-    if (target === null || target.type === "heading")
-        return null;
-    if (!reminderIsLive(target.startDate, pre.todayIso))
-        return null;
-    // Read the RAW stored byte off the substrate (top-level `reminder` is
-    // live-gated under the LOAD clock, which can differ from `pre.todayIso` under a
-    // pinned THINGS_NOW). The `reminderIsLive` guard above applies liveness under
-    // the injected clock explicitly, so the raw byte + this gate reproduce the
-    // former semantics exactly.
-    return target.derived.reminder;
-}
-function assertNotesModesExclusive(params) {
-    if (params.notes !== undefined &&
-        (params.appendNotes !== undefined || params.prependNotes !== undefined)) {
-        throw new RangeError("notes (replace) is exclusive with appendNotes/prependNotes");
-    }
-    if (params.appendNotes !== undefined && params.prependNotes !== undefined) {
-        throw new RangeError("appendNotes and prependNotes cannot be combined in one update");
-    }
-}
-function expectedNotes(pre, params) {
-    const current = pre.target !== null && pre.target.type !== "heading" ? pre.target.notes : "";
-    // Separator semantics probed: newline-joined, no stray newline against an
-    // empty note (E04/E05/E11/E12).
-    if (params.appendNotes !== undefined) {
-        return current === "" ? params.appendNotes : `${current}\n${params.appendNotes}`;
-    }
-    if (params.prependNotes !== undefined) {
-        return current === "" ? params.prependNotes : `${params.prependNotes}\n${current}`;
-    }
-    return undefined;
+function updateSpec(op, urlCommand) {
+    return {
+        op,
+        hazards: ["H-UNKNOWN-DESTINATION", "H-REPEAT-SCHEDULE", "H-REMINDER-SCOPE"],
+        preRead(db, params, now) {
+            assertNotesModesExclusive(params);
+            const pre = emptyPreState();
+            pre.todayIso = localToday(now);
+            pre.target = loadTarget(db, params.uuid);
+            return pre;
+        },
+        expectedDelta(pre, params, ctx) {
+            return { mode: "update", uuid: params.uuid, assert: updateAssertions(params, pre, ctx) };
+        },
+        compile(params, vector, pre, ctx) {
+            if (vector !== "url-scheme")
+                unsupportedVector(op, vector);
+            return thingsUrl(urlCommand, { id: params.uuid, ...updateWireParams(params, pre) }, ctx.token);
+        },
+    };
 }
-const todoUpdate = {
-    op: "todo.update",
-    hazards: ["H-UNKNOWN-DESTINATION", "H-REPEAT-SCHEDULE", "H-REMINDER-SCOPE"],
-    preRead(db, params, now) {
-        assertNotesModesExclusive(params);
-        const pre = emptyPreState();
-        pre.todayIso = localToday(now);
-        pre.target = loadTarget(db, params.uuid);
-        return pre;
-    },
-    expectedDelta(pre, params, ctx) {
-        const assert = [];
-        if (params.title !== undefined)
-            assert.push({ field: "title", equals: params.title });
-        if (params.notes !== undefined)
-            assert.push({ field: "notes", equals: params.notes });
-        const joined = expectedNotes(pre, params);
-        if (joined !== undefined)
-            assert.push({ field: "notes", equals: joined });
-        if (params.when !== undefined) {
-            assert.push(...whenAssertions(params.when, ctx.todayIso, { mode: "update" }));
-            const reminder = effectiveReminder(pre, params);
-            assert.push({
-                field: "reminder",
-                equals: reminder === null ? null : normalizeReminder(reminder),
-            });
-        }
-        if (params.deadline !== undefined)
-            assert.push({ field: "deadline", equals: params.deadline });
-        return { mode: "update", uuid: params.uuid, assert };
-    },
-    compile(params, vector, pre, ctx) {
-        if (vector !== "url-scheme")
-            unsupportedVector(this.op, vector);
-        return thingsUrl("update", {
-            id: params.uuid,
-            title: params.title,
-            notes: params.notes,
-            "append-notes": params.appendNotes,
-            "prepend-notes": params.prependNotes,
-            when: params.when === undefined
-                ? undefined
-                : whenWithReminder(params.when, effectiveReminder(pre, params)),
-            deadline: params.deadline === null ? "" : params.deadline,
-        }, ctx.token);
-    },
-};
+const todoUpdate = updateSpec("todo.update", "update");
 function statusSpec(op, urlParam, asStatus, scriptStatus) {
     return {
         op,
@@ -826,6 +702,14 @@ const projectAdd = {
         const area = pre.destArea?.resolved;
         if (area !== undefined && area !== null)
             assert.push({ field: "area.uuid", equals: area.uuid });
+        // KNOWN SHALLOW SPOT (audited 2026-08-23, exhaustive-map sweep): the seeded
+        // children — `todos` and the structured `items` (headings + rich children) —
+        // contribute NO assertion, so a project born with an empty body still
+        // verifies `ok`. Unlike a to-do's `checklistItems` (asserted through
+        // `checklistTitles`) there is no child-list field on the delta vocabulary to
+        // compare against, and adding one needs probe evidence that the imported
+        // children are readable inside the verify window before a missing child may
+        // be called a failure. Tracked in docs/up-next.md; do NOT "fix" it blind.
         return {
             mode: "create",
             probe: {
@@ -873,55 +757,9 @@ const projectAdd = {
         }, ctx.token);
     },
 };
-const projectUpdate = {
-    op: "project.update",
-    hazards: ["H-UNKNOWN-DESTINATION", "H-REPEAT-SCHEDULE", "H-REMINDER-SCOPE"],
-    preRead(db, params, now) {
-        assertNotesModesExclusive(params);
-        const pre = emptyPreState();
-        pre.todayIso = localToday(now);
-        pre.target = loadTarget(db, params.uuid);
-        return pre;
-    },
-    expectedDelta(pre, params, ctx) {
-        const assert = [];
-        if (params.title !== undefined)
-            assert.push({ field: "title", equals: params.title });
-        if (params.notes !== undefined)
-            assert.push({ field: "notes", equals: params.notes });
-        const joined = expectedNotes(pre, params);
-        if (joined !== undefined)
-            assert.push({ field: "notes", equals: joined });
-        if (params.when !== undefined) {
-            assert.push(...whenAssertions(params.when, ctx.todayIso, { mode: "update" }));
-            // Projects carry the same reminderTime codec as to-dos (A3); a bare
-            // when= clears an existing reminder unless auto-preserved.
-            const reminder = effectiveReminder(pre, params);
-            assert.push({
-                field: "reminder",
-                equals: reminder === null ? null : normalizeReminder(reminder),
-            });
-        }
-        if (params.deadline !== undefined)
-            assert.push({ field: "deadline", equals: params.deadline });
-        return { mode: "update", uuid: params.uuid, assert };
-    },
-    compile(params, vector, pre, ctx) {
-        if (vector !== "url-scheme")
-            unsupportedVector(this.op, vector);
-        return thingsUrl("update-project", {
-            id: params.uuid,
-            title: params.title,
-            notes: params.notes,
-            "append-notes": params.appendNotes,
-            "prepend-notes": params.prependNotes,
-            when: params.when === undefined
-                ? undefined
-                : whenWithReminder(params.when, effectiveReminder(pre, params)),
-            deadline: params.deadline === null ? "" : params.deadline,
-        }, ctx.token);
-    },
-};
+// Projects carry the same reminderTime codec and notes/schedule semantics as
+// to-dos (A3/E18) — same registry, same legs, only the URL command differs.
+const projectUpdate = updateSpec("project.update", "update-project");
 const projectSetTags = {
     op: "project.set-tags",
     hazards: ["H-UNKNOWN-DESTINATION", "H-UNKNOWN-TAG"],
@@ -1579,22 +1417,26 @@ const reorder = {
 };
 // ---- resolution-timestamp normalization (§5 of the plan) ------------------
 /**
- * Parse an ISO date (`2025-01-15`) OR datetime (`2025-01-15T09:30[:ss]`) and
- * resolve it to a single UTC instant in the effective `zone`. A date-only value
- * lands at NOON in that zone (B-DATEONLY: noon decodes to the intended calendar
- * date in every zone; midnight can slip a day). A datetime is read as wall-clock
- * time in the effective zone. `zone` undefined = the process-local (app host)
- * zone, which for a local CLI run IS the app's own zone.
+ * Parse a date (`2025-01-15`) OR datetime (`2025-01-15T09:30[:ss]`, or the same
+ * value spelled with a space — `2025-01-15 09:30`) and resolve it to a single
+ * UTC instant in the effective `zone`. Both separators are first-class
+ * spellings of the SAME instant: the space form is what a human (or a shell
+ * heredoc) types, the `T` form is what a serializer emits, and neither is
+ * rewritten into the other. A date-only value lands at NOON in that zone
+ * (B-DATEONLY: noon decodes to the intended calendar date in every zone;
+ * midnight can slip a day). A datetime is read as wall-clock time in the
+ * effective zone. `zone` undefined = the process-local (app host) zone, which
+ * for a local CLI run IS the app's own zone.
  */
 export function resolveResolutionInstant(input, zone) {
     const dateOnly = /^(\d{4}-\d{2}-\d{2})$/.exec(input);
     if (dateOnly !== null)
         return zonedWallInstant(dateOnly[1], 12, 0, 0, zone);
-    const dt = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(input);
+    const dt = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?$/.exec(input);
     if (dt !== null) {
         return zonedWallInstant(dt[1], Number(dt[2]), Number(dt[3]), dt[4] === undefined ? 0 : Number(dt[4]), zone);
     }
-    throw new RangeError(`invalid timestamp "${input}" — expected an ISO date (YYYY-MM-DD) or datetime (YYYY-MM-DDTHH:mm)`);
+    throw new RangeError(`invalid timestamp "${input}" — expected ${RESOLUTION_TIMESTAMP_EXPECTED}`);
 }
 const pad2 = (n) => String(n).padStart(2, "0");
 /** The host-local calendar date (`YYYY-MM-DD`) an instant renders as — what the verify layer observes for stopped/created. */
@@ -1825,9 +1667,18 @@ const headingAdd = {
         });
     },
 };
+/**
+ * project.move-heading — within-project heading order, on the ARROW-CHORD ui
+ * vector (CHORDMH1, on the HEADORD1 law). Things 3.23 left the private reorder
+ * command declared and inert, which took heading order offline entirely; the
+ * replacement is the app's own keyboard affordance (⌘↑/⌘↓/⌘⌥↑/⌘⌥↓ on a selected
+ * heading row), driven as a verified closed loop by src/write/vectors/ui-chord.ts.
+ * This is the ONE reorder that leaves the `privateReorderIsNoOp` range — every
+ * other scope still routes through its own gate.
+ */
 const projectMoveHeading = {
     op: "project.move-heading",
-    hazards: ["H-UNKNOWN-DESTINATION", "H-HEADING-ORDER"],
+    hazards: ["H-UNKNOWN-DESTINATION", "H-HEADING-ORDER", "H-UI-DRIVE"],
     preRead(db, params) {
         const pre = emptyPreState();
         pre.destProject = resolveProject(db, params.project);
@@ -1835,24 +1686,41 @@ const projectMoveHeading = {
         return pre;
     },
     expectedDelta(pre) {
-        // The reorder wire re-ranks the FULL heading list; verify the whole target
-        // order (strictly ascending "index"). Children follow their heading (scf
-        // P1), so no per-child assertion is needed.
-        return { mode: "ordering", key: "index", sequence: pre.headingMove?.targetOrder ?? [] };
+        const move = pre.headingMove;
+        return {
+            mode: "ordering",
+            key: "index",
+            // The full end state: every heading of the project, strictly ascending.
+            sequence: move?.targetOrder ?? [],
+            // RRF1: the headings the caller did NOT name must hold their EXACT prior
+            // rank — a chord is a single-row write, and this is what proves the one
+            // that landed was the row the plan addressed (a heading row exposes no
+            // title to read the selection back through).
+            unchanged: move?.untouched ?? [],
+            // Children follow their heading through an intact FK, un-renumbered and
+            // un-touched (no userModificationDate bump — that is what `frozen` adds).
+            frozen: (move?.children ?? []).map((c) => ({
+                uuid: c.uuid,
+                assert: [{ field: "heading.uuid", equals: c.heading }],
+            })),
+            ...(move?.targetOrder[0] !== undefined && { subject: move.targetOrder[0] }),
+        };
     },
-    compile(_params, vector, pre) {
-        // The same native private-reorder wire the old `reorder --scope headings`
-        // used (experimental — gated by allow-experimental + the sdef canary),
-        // fed the computed full order.
-        if (vector !== "applescript")
+    compile(params, vector, pre) {
+        if (vector !== "ui")
             unsupportedVector(this.op, vector);
-        // #V11: send the MINIMAL front-cluster wire, not the full order — an archived
-        // heading that need not move stays out of it (untouched, HEADSORT H-UNSWEPT);
-        // any archived heading the target FORCES in (pre.headingMove.reopened) is
-        // reopened and disclosed. NEVER put un-targeted rows into the wire.
-        const order = pre.headingMove?.wire ?? [];
-        return osa(`${PRIVATE_REORDER_COMMAND} project id ${q(pre.destProject?.resolved?.uuid ?? "")} ` +
-            `with ids ${q(order.join(","))}`);
+        const move = pre.headingMove;
+        if (move === null || move.problems.length > 0) {
+            // The membership/anchor refusals are surfaced by H-HEADING-ORDER
+            // before compile; reaching here with one means the guard was bypassed.
+            throw new Error(`project.move-heading: ${move === null ? "no heading move computed (guard bypassed?)" : move.problems.join("; ")}`);
+        }
+        // The movee set is EXACTLY what the caller named — never derived from the
+        // untouched set, which fences a different (smaller) thing: a bystander whose
+        // POSITION shifts is still a bystander no chord may move.
+        return uiDrive(moveHeadingChordRecipe(pre.destProject?.resolved?.uuid ?? "", move.targetOrder, [
+            ...params.headings,
+        ]));
     },
 };
 const todoClearDatedReminder = {
@@ -1901,11 +1769,41 @@ function uiDrive(recipe) {
 // the validator from commands.ts; the implementation + the full combination
 // matrix live in repeat-rule.ts.
 export { assertRepeatRule };
+/**
+ * The recipe extras for a MAKE-REPEATING drive: {@link ruleExtras} with the
+ * "Next:" drive date deadline-adjusted, exactly as {@link reschedRuleExtras}
+ * does for a reschedule.
+ *
+ * ONE MEANING FOR `next`, ONE PLACE THAT SHIFTS IT (NEXTPOP1). `next` is the
+ * requested first-occurrence START — what `--when` means to a caller — in every
+ * params bag, at every layer. A DEADLINED rule anchors the dialog on the
+ * DEADLINE (YANCH1 #493), so the date the "Next:" control must carry is
+ * `next + startDaysEarlier`; that conversion belongs to the compile, where the
+ * dialog is, and nowhere else.
+ *
+ * It used to happen upstream too: the promote orchestrators shifted `next`
+ * before handing the bag to this op, so the SAME field meant a START coming from
+ * a caller and a DUE date coming from a composite. Everything downstream that
+ * shifts — `assessOffRuleFirst`, via `assertRepeatRule` in preRead — then shifted
+ * a second time, and a deadlined MONTHLY promote was refused before it ran with
+ * a message about a date the caller never asked for (`--deadline 2026-08-20`
+ * + `--when 2026-08-06` → "a first occurrence on 2026-08-20 would not hold",
+ * measured in-lab). The orchestrators now pass `--when` through unshifted.
+ */
+function makeRuleExtras(params) {
+    const base = ruleExtras(params);
+    const drive = deadlineDriveNext(params);
+    return drive !== undefined ? { ...base, next: drive } : base;
+}
 /**
  * The extended-vocabulary fields of a rule as a recipe `extras` bag, including
  * ONLY the keys that are present (exactOptionalPropertyTypes: never set an
  * optional field to undefined). A bare `{ uuid, frequency, interval }` yields
  * `{}`, so the recipe drives exactly the certified two-control path.
+ *
+ * `next` is copied through VERBATIM — a START. Every compile that drives the
+ * dialog wraps this with its own deadline shift ({@link makeRuleExtras},
+ * {@link reschedRuleExtras}); this function never shifts (NEXTPOP1).
  */
 function ruleExtras(params) {
     return {
@@ -1948,15 +1846,31 @@ function reschedEffParams(params) {
  * `--when` is the scheduled START, but a deadlined rule anchors on the DEADLINE,
  * so the dialog's "Next:" field is driven with `when + startDaysEarlier` and the
  * app back-shifts the instance start to `--when`. The expectedDelta keeps the RAW
- * `params.next` (the cursor asserts the START). make/add-repeating apply this shift
- * upstream (promote-clone.ts) and pass an already-adjusted rule, so only the
- * reschedule compile needs it here.
+ * `params.next` (the cursor asserts the START). {@link makeRuleExtras} is the
+ * make/add-repeating twin of this — the shift lands in the compile on every verb
+ * that drives the dialog, and nowhere upstream of it (NEXTPOP1).
  */
 function reschedRuleExtras(params) {
     const base = ruleExtras(reschedEffParams(params));
     const drive = deadlineDriveNext(params);
     return drive !== undefined ? { ...base, next: drive } : base;
 }
+/**
+ * The rule-vocabulary keys this reschedule REQUESTED — the input to the
+ * unexplained-delta check (CGRD1 guard 3): every decoded-rule field that moves
+ * must be attributable to one of these, or to a mapped co-mover of one.
+ *
+ * Built from the EFFECTIVE params, the same bag the recipe drives, so a
+ * `--when`-only reschedule that DERIVES a calendar anchor counts that anchor as
+ * requested rather than as an unexplained move (RSPA1 / YANCH1 #493) — the drive
+ * really does address those pop-ups. `uuid` is the target, not a rule field.
+ */
+function requestedRuleKeys(params) {
+    const eff = reschedEffParams(params);
+    return Object.entries(eff)
+        .filter(([key, value]) => key !== "uuid" && value !== undefined)
+        .map(([key]) => key);
+}
 /** ui ops all guard existence/type + the H-UI-DRIVE acknowledgement. */
 const UI_HAZARDS = ["H-UNKNOWN-DESTINATION", "H-UI-DRIVE"];
 const todoMakeRepeating = {
@@ -2004,7 +1918,7 @@ const todoMakeRepeating = {
     compile(params, vector) {
         if (vector !== "ui")
             unsupportedVector(this.op, vector);
-        return uiDrive(makeRepeatingRecipe(params.uuid, params.frequency, params.interval, ruleExtras(params)));
+        return uiDrive(makeRepeatingRecipe(params.uuid, params.frequency, params.interval, makeRuleExtras(params)));
     },
 };
 const todoRescheduleRepeat = {
@@ -2042,6 +1956,12 @@ const todoRescheduleRepeat = {
                 includeCursor: assessOffRuleFirst(eff)?.kind !== "honored",
             }),
             capture: [{ field: "repeating.rule" }, { field: "repeating.deadlined" }],
+            // UNEXPLAINED-DELTA DETECTION (CGRD1 guard 3). The assertions above prove
+            // the requested rule landed; this proves nothing ELSE did. A reschedule
+            // rewrites an EXISTING rule, so there is a full pre-state to diff against —
+            // which is why make-repeating / add-repeating do not carry it: they mint the
+            // rule, so every field is new by construction and there is nothing to compare.
+            collateral: { requested: requestedRuleKeys(params) },
         };
     },
     compile(params, vector) {
@@ -2072,6 +1992,56 @@ const todoPauseRepeat = {
         return uiDrive(pauseRepeatRecipe(params.uuid));
     },
 };
+/**
+ * `Items ▸ Repeat ▸ Create Next Copy` (CNC1) — materialize the pending
+ * occurrence and advance the series. The INTERNAL first leg of the
+ * template-mutation composites (template-mutation.ts); it is not a user-facing
+ * verb, because a bare "spawn one now" has no use we have been asked for and
+ * every honest use of it mutates the row it mints.
+ *
+ * Verified as a CREATE: the minted row wears the template's own title, is a
+ * to-do, carries a fresh (gesture wall-clock) creationDate, and is not one of
+ * the rows the series already had — which is exactly the create-probe's
+ * gauntlet, and it hands the composite back the minted uuid it needs. The one
+ * field assertion is the FK: the discovered row must be an instance of THIS
+ * template, so a same-titled row created by anything else in the window cannot
+ * pass. The cursor advance is deliberately NOT asserted here — a create delta
+ * asserts against the created row, and the composite re-reads the template
+ * afterwards anyway to disclose when the next occurrence lands.
+ */
+const todoCreateNextCopy = {
+    op: "todo.create-next-copy",
+    hazards: UI_HAZARDS,
+    preRead(db, params) {
+        const pre = emptyPreState();
+        pre.target = loadTarget(db, params.uuid);
+        // The series' existing rows — the template plus every instance it has
+        // already spawned, all of which share its title. They are the create
+        // probe's exclusion set, so "the new row" is unambiguous even on a series
+        // whose occurrences all look alike.
+        pre.sameTitleUuids = seriesRowUuids(db, params.uuid);
+        return pre;
+    },
+    expectedDelta(pre, params, ctx) {
+        const target = pre.target;
+        const title = target !== null && target.type !== "heading" ? target.title : "";
+        return {
+            mode: "create",
+            probe: {
+                title,
+                type: "to-do",
+                sinceEpoch: ctx.nowEpoch - 2,
+                excludeUuids: pre.sameTitleUuids,
+            },
+            assert: [{ field: "repeating.templateUuid", equals: params.uuid }],
+        };
+    },
+    compile(params, vector) {
+        if (vector !== "ui")
+            unsupportedVector(this.op, vector);
+        return uiDrive(createNextCopyRecipe(params.uuid));
+    },
+};
 const todoResumeRepeat = {
     op: "todo.resume-repeat",
     hazards: UI_HAZARDS,
@@ -2131,6 +2101,12 @@ const projectRescheduleRepeat = {
                 includeCursor: assessOffRuleFirst(eff)?.kind !== "honored",
             }),
             capture: [{ field: "repeating.rule" }, { field: "repeating.deadlined" }],
+            // UNEXPLAINED-DELTA DETECTION (CGRD1 guard 3). The assertions above prove
+            // the requested rule landed; this proves nothing ELSE did. A reschedule
+            // rewrites an EXISTING rule, so there is a full pre-state to diff against —
+            // which is why make-repeating / add-repeating do not carry it: they mint the
+            // rule, so every field is new by construction and there is nothing to compare.
+            collateral: { requested: requestedRuleKeys(params) },
         };
     },
     compile(params, vector) {
@@ -2240,7 +2216,7 @@ const projectMakeRepeating = {
             // Unreachable in practice: the guards block refuse/anytime before compile.
             throw new Error("project.make-repeating: no selectable-row taxonomy resolved (guard bypassed?)");
         }
-        return uiDrive(projectMakeRepeatingRecipe(tax.containerReveal, params.uuid, tax.title, params.frequency, params.interval, ruleExtras(params)));
+        return uiDrive(projectMakeRepeatingRecipe(tax.containerReveal, params.uuid, tax.title, params.frequency, params.interval, makeRuleExtras(params)));
     },
 };
 // project.add-repeating is delivered by the runAddRepeatingProject
@@ -2612,6 +2588,7 @@ export const COMMANDS = {
     "todo.make-repeating": todoMakeRepeating,
     "todo.reschedule-repeat": todoRescheduleRepeat,
     "todo.pause-repeat": todoPauseRepeat,
+    "todo.create-next-copy": todoCreateNextCopy,
     "todo.resume-repeat": todoResumeRepeat,
     "todo.convert-to-project": todoConvertToProject,
     "project.reschedule-repeat": projectRescheduleRepeat,