things-api 0.18.0 → 0.19.1

package/dist/write/promote-clone.js

@@ -1,13 +1,15 @@
 import { undoToken } from "../audit/schema.js";
+import { uiAllowed, uiCapability as uiCapabilityDefault } from "../capability.js";
 import { addDaysIso, decodePackedDate, localToday } from "../model/dates.js";
 import { byUuid } from "../read/detail.js";
 import { resolveProjectWriteTarget, resolveTaskUuidPrefix } from "../read/queries.js";
 import { runCloneProject, runCloneTodo } from "./clone.js";
 import { promoteProjectViaGui } from "./make-repeating-project.js";
-import { fingerprintLabel, runMutation, } from "./pipeline.js";
+import { replayIfApplied } from "./opid.js";
+import { fingerprintLabel, runComposite, runMutation, } from "./pipeline.js";
 import { assessOffRuleFirst, daysBetweenIso, deriveFixedAnchor, isIsoDate, } from "./repeat-anchor.js";
-import { assertRepeatRule, ruleToInverseParams } from "./repeat-rule.js";
-import { createDbReader } from "./verify/delta.js";
+import { assertRepeatRule, ruleToInverseParams, splitAddRepeatingRule } from "./repeat-rule.js";
+import { createDbReader, } from "./verify/delta.js";
 import { H_UI_SESSION_UNREACHABLE } from "./vectors/session-reachability.js";
 const PLACEMENT_NOTE = "the series' current instance lands at its container's default position — its prior slot was " +
     "not automatically restored (best-effort placement is not yet wired for this container); " +
@@ -50,22 +52,51 @@ function blockedUiDrive(op) {
         detail: "this operation promotes an item to a repeating series by driving the local Things app " +
             "through the Accessibility API (the Repeat… dialog) — it may briefly interact with the UI",
         remediation: "pass dangerouslyDriveGui (--dangerously-drive-gui) to proceed; the vector also requires " +
-            "`things config set ui-enabled true` and Accessibility granted to this process (see docs/setup.md)",
+            "`things config set ui-enabled true` and `things helpers setup --gui`, which grants " +
+            "GUI-driving to the helper pair — the only identity it is granted to " +
+            "(docs/design/permissions-doctrine.md, Article IV)",
     };
 }
 /**
- * SESSGATE (#480) pre-seed reachability gate. A promote composite is NOT atomic:
- * it SEEDS a row (clone / add) before the GUI promote leg drives the dialog. If
- * the Mac's session is AX-blind (screen locked / full-screen Space), the dialog
- * would open on an unreachable window and the drive would fail — leaving an
- * orphan seed. So probe the live session BEFORE seeding and refuse fast (zero
- * mutation) on the certain-failure LOCKED signature. Only "session" scope refuses
- * here: a window merely on another Space is left for the in-drive relocation (the
- * reveal has not run yet, so refusing before the seed would be a false positive).
- * No ui vector (simulator / bench), ui disabled, or a fail-open probe → proceed
- * (the promote leg's own gate + cleanup remain the backstop).
+ * The pre-seed UI PREFLIGHT (SESSGATE #480 + issue #512). A promote composite is
+ * NOT atomic: it SEEDS a row (clone / add) before the GUI promote leg drives the
+ * dialog. Anything that will certainly stop that drive must be established BEFORE
+ * the seed exists, or the composite mutates, fails, and cleans up after itself for
+ * a reason it could have known up front. Two checks, cheapest and most decisive
+ * first, both prompt-free:
+ *
+ *  1. STANDING (permissions doctrine, Article IV). Driving the window needs
+ *     Accessibility + Automation → System Events, held by the helper pair and
+ *     nothing else. The pipeline already gates this — but only on the PROMOTE leg,
+ *     which runs after the seed, so a machine without the grants used to create
+ *     the row, refuse, and trash it. Same verdict, same copy, one leg earlier;
+ *     nothing is created. Keyed on a vector's `drivesGui` DECLARATION exactly as
+ *     the pipeline's gate is, never on its id, so a fake/simulator substituted
+ *     under "ui" is not gated on the developer's own host state.
+ *  2. REACHABILITY (SESSGATE). If the Mac's session is AX-blind (screen locked /
+ *     full-screen Space), the dialog would open on an unreachable window. Only
+ *     "session" scope refuses here: a window merely on another Space is left for
+ *     the in-drive relocation (the reveal has not run yet, so refusing before the
+ *     seed would be a false positive). A fail-open probe proceeds — the promote
+ *     leg's own gate + the seed cleanup remain the backstop.
+ *
+ * Running the standing check FIRST also keeps the probe itself doctrine-clean: no
+ * System Events call is attempted on a host that has not granted one.
  */
-async function gateSessionReachability(deps, op) {
+async function gateUiPreflight(deps, op) {
+    const gui = deps.vectors.find((v) => v.drivesGui === true && v.simulates !== true);
+    if (gui !== undefined) {
+        const capability = (deps.uiCapability ?? (() => uiCapabilityDefault()))();
+        if (!uiAllowed(capability)) {
+            return {
+                kind: "blocked",
+                op,
+                reason: "environment",
+                detail: `this operation drives the Things window, and ${capability.detail} — nothing was created`,
+                remediation: capability.remediation.join("; "),
+            };
+        }
+    }
     if (!deps.config.ui.enabled)
         return null;
     const ui = deps.vectors.find((v) => v.probeReachability !== undefined);
@@ -117,35 +148,23 @@ async function cleanupSeed(deps, kind, createdUuid, promote, options, txnId) {
  *
  * The `rule` bag is the SUPERSET the make/add legs actually carry: make-repeating
  * passes a full {@link RepeatRuleParams} (rule-level `deadline`/`startDaysEarlier`
- * included), add-repeating an {@link AddRepeatingRuleFields} (which OMITS those —
- * the base add owns the item's own deadline). Every field is copied THROUGH so
- * neither is silently dropped: an earlier version keyed the param type to
- * AddRepeatingRuleFields and stripped `deadline`/`startDaysEarlier` from the
- * make-repeating promote entirely (the same class as the RRX1 reminder drop —
- * a deadlined make-repeating produced a NON-deadlined template, YANCH1 #493).
+ * and the requested `next` included), add-repeating an
+ * {@link AddRepeatingRuleFields} plus whichever of the deadline pair its geometry
+ * folded in. Every field flows through by SPREAD, never by a hand-copied field
+ * list — a list here is how the make-repeating promote once stripped
+ * `deadline`/`startDaysEarlier` (a deadlined make-repeating produced a
+ * NON-deadlined template, YANCH1 #493) and how the project promote later dropped
+ * `next` (#549). The ONE field that is deliberately re-derived rather than copied
+ * is `next`: the drive date is deadline-shifted by the caller, and an
+ * after-completion dialog has no first-occurrence field to drive at all.
  */
 function ruleParamsFor(uuid, rule, nextIso) {
-    return {
-        uuid,
-        frequency: rule.frequency,
-        interval: rule.interval,
-        ...(rule.afterCompletion !== undefined && { afterCompletion: rule.afterCompletion }),
-        ...(rule.weekdays !== undefined && { weekdays: rule.weekdays }),
-        ...(rule.monthly !== undefined && { monthly: rule.monthly }),
-        ...(rule.yearly !== undefined && { yearly: rule.yearly }),
-        ...(rule.ends !== undefined && { ends: rule.ends }),
-        // The repeat reminder picker is drivable (ANCH2). make-repeating carries a
-        // rule-level reminder through; add-repeating threads the base to-do's
-        // --reminder here too (ADR1 #480), since the dialog conversion otherwise drops
-        // the seed's one-off reminder from the series.
-        ...(rule.reminder !== undefined && { reminder: rule.reminder }),
-        // The deadline offset is a rule-level field on make-repeating (the "Add
-        // deadlines" checkbox + "start N days earlier"); it must ride the promote or a
-        // `make-repeating --deadline` lands a non-deadlined series (YANCH1 #493).
-        ...(rule.deadline !== undefined && { deadline: rule.deadline }),
-        ...(rule.startDaysEarlier !== undefined && { startDaysEarlier: rule.startDaysEarlier }),
-        ...(nextIso !== undefined && rule.afterCompletion !== true && { next: nextIso }),
-    };
+    const out = { ...rule, uuid };
+    // Never the caller's raw `next` — see above; the drive date arrives as `nextIso`.
+    delete out.next;
+    if (nextIso !== undefined && rule.afterCompletion !== true)
+        out.next = nextIso;
+    return out;
 }
 const UNIT_SINGULAR = {
     daily: "day",
@@ -214,6 +233,32 @@ function instanceStartDate(db, instanceUuid) {
         return null;
     return decodePackedDate(row.s);
 }
+/**
+ * The oracle for the post-drive first-occurrence check, picked by rule KIND
+ * (issue #508).
+ *
+ * A FIXED-schedule series is anchored on the calendar: the dialog's "Next:" field
+ * IS driven, and the template's own cursor (`rt1_instanceCreationStartDate`) holds
+ * the resulting first occurrence — the right thing to compare against.
+ *
+ * An AFTER-COMPLETION series has NO calendar anchor, so {@link ruleParamsFor}
+ * deliberately leaves "Next:" alone, and the app mints the template with an EMPTY
+ * cursor (RSIM2 / RSIM-P P4: no next / reference dates exist until a completion
+ * happens). Comparing that empty cursor against `--when` reported a FALSE
+ * `verify-failed:mismatch` on a perfectly correct creation (#508, reproduced 6/6
+ * on the live host). The requested date lives on the materialized INSTANCE's own
+ * `startDate` — the row the promote preserved and relinked — so that is the oracle
+ * for an after-completion series.
+ *
+ * Returns `null` when no oracle is reachable. For an after-completion rule that
+ * means "unverifiable" and the caller SKIPS the check (the create delta already
+ * proved the series landed); for a fixed rule an absent cursor is a genuine miss.
+ */
+function landedFirstStart(deps, templateUuid, instanceUuid, afterCompletion) {
+    if (!afterCompletion)
+        return firstOccurrenceOf(deps.db, templateUuid);
+    return instanceUuid === null ? null : instanceStartDate(deps.db, instanceUuid);
+}
 /**
  * DBLSPAWN1 (docs/lab/dblspawn1-preserved-instance.md, golden-v3 / Things 3.22.14):
  * a promote whose source is PRESERVED (SRCFATE deadline / terminal-element trigger)
@@ -234,7 +279,16 @@ function instanceStartDate(db, instanceUuid) {
  * promote did not preserve a future instance. Best-effort: a failed trash is reported
  * in the warning rather than failing the whole compound (the series is already sound).
  */
-async function trashRedundantFuturePreservedInstance(deps, kind, promote, options, txnId, now) {
+async function trashRedundantFuturePreservedInstance(deps, kind, promote, options, txnId, now, afterCompletion) {
+    // AFTER-COMPLETION series are exempt: the double-book is a CURSOR phenomenon
+    // (`rt1_nextInstanceStartDate` pointing at an already-materialized occurrence),
+    // and an after-completion template is minted with NO cursor at all — the next
+    // occurrence is unknown until a completion happens (RSIM2 / RSIM-P P4). Its
+    // preserved instance is therefore the series' ONLY occurrence, whatever its
+    // date; trashing it would destroy the series' current occurrence rather than a
+    // duplicate. (Unreachable before #508, whose false verify-failed returned first.)
+    if (afterCompletion)
+        return null;
     const rep = promote.repeating;
     // Preserved iff the native promote relinked the source (replacedUuid === null) AND
     // there is a materialized instance. A DELETE-fate promote reports replacedUuid !==
@@ -287,6 +341,36 @@ function discoveryOf(promote) {
     };
 }
 // -------------------------------------------------------------- audit summary
+/**
+ * The promote compound's presence oracle: "a repeating TEMPLATE with this title,
+ * created since this call started, exists". It is the same create-probe the
+ * compound's own dry-run plan states, TIME-BOUNDED to the call — the app mints a
+ * template with a fresh write-time creationDate even when the promoted row was
+ * created earlier (`--preserve-created`), so the bound is safe and it keeps an
+ * older namesake series from reading as this call's work. Recorded on an
+ * AMBIGUOUS summary so a resubmission can settle it (see {@link appendPromoteSummary}).
+ */
+function promotePresenceDelta(title, type, startedAt) {
+    return {
+        mode: "create",
+        probe: { title, type, sinceEpoch: Math.floor(startedAt.getTime() / 1000) },
+        assert: [{ field: "repeating.isTemplate", equals: true }],
+    };
+}
+/**
+ * Append the promote compound's SUMMARY record — the ONE record that stands for
+ * the whole verb (its legs are `leg`-role records, excluded from direct undo),
+ * and the one record the caller's `opId` rides, so a resubmission matches the
+ * whole promote exactly once instead of matching a leg or nothing at all.
+ *
+ * Two shapes, one record either way:
+ *  - the SUCCESS summary (default) — result `ok`, the single undoable unit;
+ *  - an AMBIGUOUS summary (`ambiguous`) — result `verify-failed:timeout` with the
+ *    presence oracle attached, written when a leg dispatched and never confirmed.
+ *    It is not an undo target (undo reads `ok` records only); it exists so a
+ *    resubmission carrying the same key re-reads state and decides instead of
+ *    minting a second series.
+ */
 function appendPromoteSummary(deps, args) {
     const fp = deps.fingerprint();
     const observed = {
@@ -297,7 +381,7 @@ function appendPromoteSummary(deps, args) {
     const record = {
         v: 1,
         ts: args.startedAt.toISOString(),
-        actor: deps.config.actor,
+        actor: args.options?.actor ?? deps.config.actor,
         host: deps.config.host,
         op: args.op,
         uuid: args.templateUuid,
@@ -306,9 +390,11 @@ function appendPromoteSummary(deps, args) {
         invocation: args.invocation,
         requested: args.requested,
         txn: { id: args.txnId, role: "summary" },
+        ...(args.options?.opId !== undefined && { opId: args.options.opId }),
+        ...(args.ambiguous !== undefined && { expected: args.ambiguous }),
         pre: null,
-        observed,
-        result: "ok",
+        observed: args.ambiguous === undefined ? observed : null,
+        result: args.ambiguous === undefined ? "ok" : "verify-failed:timeout",
         ...(args.preModDates !== undefined && { preModDates: args.preModDates }),
         verify: null,
         durationMs: (deps.now?.() ?? new Date()).getTime() - args.startedAt.getTime(),
@@ -320,6 +406,31 @@ function appendPromoteSummary(deps, args) {
     };
     deps.audit.append(record);
 }
+/**
+ * Record the AMBIGUOUS summary when a promote compound's own outcome is a
+ * timeout — the one verdict where the series may or may not exist. Returns the
+ * outcome unchanged, so it wraps a composite body without re-shaping it. Only a
+ * keyed call records one: without an `opId` there is nothing to reconcile
+ * against later, and the leg records already carry the failure.
+ */
+function recordAmbiguousPromote(deps, outcome, args) {
+    if (args.options.opId === undefined)
+        return outcome;
+    if (outcome.kind !== "verify-failed" || outcome.reason !== "timeout")
+        return outcome;
+    appendPromoteSummary(deps, {
+        startedAt: args.startedAt,
+        op: args.op,
+        txnId: args.txnId,
+        templateUuid: null,
+        instanceUuid: null,
+        invocation: args.invocation,
+        requested: args.requested,
+        options: args.options,
+        ambiguous: promotePresenceDelta(args.title, args.type, args.startedAt),
+    });
+    return outcome;
+}
 /** Build the ok result for a promote (make/add-repeating). */
 function promoteOk(args) {
     const repeating = {
@@ -356,6 +467,14 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
     const op = kind === "project" ? "project.make-repeating" : "todo.make-repeating";
     // Validate the rule BEFORE anything (a bad rule must never mint a clone).
     assertRepeatRule(params);
+    // Idempotency FIRST, before the target is even resolved: a successful promote
+    // moves the original to the Trash and hands back a different uuid, so a
+    // resubmission of the same key must be answered from the trail rather than
+    // re-driven against a source that is no longer the item it names. The key
+    // rides the compound's single summary record, so a match is the whole verb.
+    const replay = replayIfApplied(deps, options);
+    if (replay !== null)
+        return replay;
     const now = deps.now?.() ?? new Date();
     const srcUuid = kind === "project"
         ? resolveProjectWriteTarget(deps.db, params.uuid)
@@ -374,6 +493,9 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
                 : "verify the uuid with `things show <uuid>`, or use `things project make-repeating` for a project",
         };
     }
+    // Bound after the existence guard so the composite body (a hoisted function,
+    // where TypeScript cannot carry the narrowing) still sees a plain string.
+    const srcTitle = src.title;
     // ANCH2 (issue #476): the app's Repeat dialog HAS a "Next:" first-occurrence
     // field; its default is the today-anchored next match, but it is editable and
     // honored (docs/lab/anch2-next-field.md). Drive it with the requested first
@@ -396,10 +518,14 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
         ? (params.startDaysEarlier ?? 0)
         : 0;
     const driveIso = isIsoDate(whenIso) ? addDaysIso(whenIso, deadlineShift) : undefined;
-    // The dialog is driven with the deadline-adjusted date; the verify below expects
-    // the START to land back on the requested `--when`.
-    const nextIso = driveIso;
-    const expectedStartIso = isIsoDate(whenIso) ? whenIso : undefined;
+    // The ANCHOR is derived from the deadline-adjusted date (the anchor names the
+    // DUE date), but `next` is passed through as the requested START: the promote
+    // leg's own compile applies the "Next:" shift, and it is the ONLY place that
+    // does (NEXTPOP1 — shifting here as well made every downstream consumer that
+    // shifts, `assessOffRuleFirst` among them, shift a second time). The verify
+    // below expects the START to land on the requested `--when` either way.
+    const nextIso = isIsoDate(whenIso) ? whenIso : undefined;
+    const expectedStartIso = nextIso;
     const effParams = { ...params, ...deriveFixedAnchor(params, driveIso) };
     // The promote leg drives the GUI — block before minting a clone if the ack is missing.
     if (options.dangerouslyDriveGui !== true && options.dryRun !== true) {
@@ -424,142 +550,168 @@ async function makeRepeatingViaClone(deps, kind, params, options) {
             },
         };
     }
-    // SESSGATE (#480): refuse a locked / full-screen session BEFORE minting a clone
-    // — otherwise the promote's dialog opens on an unreachable window and the whole
-    // compound fails, stranding a disposable clone. Zero mutation on refusal.
-    const gate = await gateSessionReachability(deps, op);
+    // PRE-SEED UI PREFLIGHT (#480/#512): refuse a host that cannot drive the window,
+    // or a locked / full-screen session, BEFORE minting a clone — otherwise the
+    // promote's dialog never opens and the whole compound fails, stranding a
+    // disposable clone. Zero mutation on refusal.
+    const gate = await gateUiPreflight(deps, op);
     if (gate !== null)
         return gate;
     const startedAt = now;
     const txnId = newTxnId(startedAt);
-    // 1. Clone the source as a disposable, embedded leg (--preserve-created). The
-    // clone has captured X's full content by the time it returns.
-    const clone = kind === "project"
-        ? await runCloneProject(deps, { uuid: srcUuid, preserveCreated: true }, legOptions(options, txnId))
-        : await runCloneTodo(deps, { uuid: srcUuid, preserveCreated: true }, legOptions(options, txnId));
-    if (clone.kind !== "ok" || clone.uuid === null) {
-        // A clone refusal (nested repeating template, H-CLONE-SOURCE) surfaces
-        // coherently here — re-label it to the make-repeating op for the caller.
-        return clone.kind === "ok"
-            ? {
-                kind: "verify-failed",
-                op,
-                reason: "mismatch",
-                expected: {
-                    mode: "create",
-                    probe: { title: src.title, type: expectedType, sinceEpoch: 0 },
-                    assert: [],
-                },
-                observed: null,
-                detail: "the disposable clone was created but its uuid was not discovered — nothing was promoted or trashed",
-            }
-            : { ...clone, op };
-    }
-    const cloneUuid = clone.uuid;
-    // --preserve-modified: X is the ONLY pre-existing row the compound touches (the
-    // clone/promote legs mint fresh rows). Capture its pre-write umd BEFORE the
-    // trash bumps it — the trash leg restores it forward, and the value rides the
-    // summary record's preModDates so the symmetric undo restore fires on the
-    // revived X (undo.ts, 2026-08-13 ruling). The clone leg above reads X but never
-    // writes it, so its umd is still pristine here.
-    const preserveModified = options.preserveModified === true;
-    const preUmd = preserveModified
-        ? createDbReader(deps.db, now, deps.zone).modDateOf(srcUuid)
-        : null;
-    // 2. Trash the original BEFORE promoting — the clone already holds X's content,
-    // and a live same-titled X would make the promote's project row-selection
-    // ambiguous (H-PROJECT-REPEAT). X survives in the Trash (the recoverable half).
-    const trash = await runMutation(deps, `${kind}.delete`, { uuid: srcUuid }, legOptions(options, txnId, undefined, preserveModified ? { preserveModified: true } : undefined));
-    if (trash.kind !== "ok") {
-        return {
-            ...trash,
+    // COMPOSITE LOCK: everything below is ONE verb executed as several mutations
+    // (clone → trash → promote → the DBLSPAWN1 clean-up), and they must not
+    // interleave with another writer's legs — the promote's row selection is by
+    // TITLE, so a concurrent clone of the same item makes it ambiguous. One lock,
+    // held to the end; each leg's own acquisition is a reentrant no-op.
+    return runComposite(deps, op, async () => {
+        const outcome = await promoteBody();
+        // An unconfirmed outcome gets the compound's AMBIGUOUS summary, so a
+        // resubmission of the same key reconciles instead of minting a second series.
+        return recordAmbiguousPromote(deps, outcome, {
+            startedAt,
             op,
-            ...("detail" in trash
-                ? {
-                    detail: `${trash.detail} — the disposable clone (uuid ${cloneUuid}) was created but the ` +
-                        `original ${srcUuid} could not be moved to the Trash, so it was NOT promoted; trash ` +
-                        "the clone and retry",
-                }
-                : {}),
-        };
-    }
-    // 3. Native-promote the clone (with the ANCH2 Next drive + derived weekday).
-    const rule = ruleParamsFor(cloneUuid, effParams, nextIso);
-    const promote = kind === "project"
-        ? await promoteProjectViaGui(deps, rule, legOptions(options, txnId, "ui"))
-        : await runMutation(deps, "todo.make-repeating", rule, legOptions(options, txnId, "ui"));
-    if (promote.kind !== "ok") {
-        // The clone persists but was not promoted; best-effort ROLL BACK the trash so
-        // the original is not stranded in the Trash.
-        const restoreOp = kind === "project" ? "project.restore" : "todo.restore";
-        const rolledBack = await runMutation(deps, restoreOp, { uuid: srcUuid }, legOptions(options, txnId));
-        const rollNote = rolledBack.kind === "ok"
-            ? `the original ${srcUuid} was restored from the Trash`
-            : `the original ${srcUuid} could NOT be restored from the Trash — restore it in the app`;
-        return {
-            ...promote,
-            op,
-            ...("detail" in promote
+            txnId,
+            title: srcTitle,
+            type: expectedType,
+            invocation: `${op}: clone ${srcUuid} → trash ${srcUuid} → promote (unconfirmed)`,
+            requested: effParams,
+            options,
+        });
+    });
+    async function promoteBody() {
+        // 1. Clone the source as a disposable, embedded leg (--preserve-created). The
+        // clone has captured X's full content by the time it returns.
+        const clone = kind === "project"
+            ? await runCloneProject(deps, { uuid: srcUuid, preserveCreated: true }, legOptions(options, txnId))
+            : await runCloneTodo(deps, { uuid: srcUuid, preserveCreated: true }, legOptions(options, txnId));
+        if (clone.kind !== "ok" || clone.uuid === null) {
+            // A clone refusal (nested repeating template, H-CLONE-SOURCE) surfaces
+            // coherently here — re-label it to the make-repeating op for the caller.
+            return clone.kind === "ok"
                 ? {
-                    detail: `${promote.detail} — the disposable clone (uuid ${cloneUuid}) was created but the ` +
-                        `promote did not land; ${rollNote}. Trash the clone and retry`,
+                    kind: "verify-failed",
+                    op,
+                    reason: "mismatch",
+                    expected: {
+                        mode: "create",
+                        probe: { title: srcTitle, type: expectedType, sinceEpoch: 0 },
+                        assert: [],
+                    },
+                    observed: null,
+                    detail: "the disposable clone was created but its uuid was not discovered — nothing was promoted or trashed",
                 }
-                : {}),
-        };
-    }
-    const { templateUuid } = discoveryOf(promote);
-    let { instanceUuid } = discoveryOf(promote);
-    // Post-drive verify (ANCH2 + YANCH1): the instance START must have landed on the
-    // requested `--when` — for a deadlined rule the driven Next is the deadline
-    // (when + startDaysEarlier) and the app back-shifts the start to `--when`, so the
-    // check is against `expectedStartIso`, not the raw drive date. Fail closed on
-    // mismatch rather than report a wrong-phase ok.
-    if (expectedStartIso !== undefined) {
-        const landed = firstOccurrenceOf(deps.db, templateUuid);
-        if (landed !== expectedStartIso) {
-            return nextMismatch(op, templateUuid, expectedStartIso, landed);
+                : { ...clone, op };
         }
+        const cloneUuid = clone.uuid;
+        // --preserve-modified: X is the ONLY pre-existing row the compound touches (the
+        // clone/promote legs mint fresh rows). Capture its pre-write umd BEFORE the
+        // trash bumps it — the trash leg restores it forward, and the value rides the
+        // summary record's preModDates so the symmetric undo restore fires on the
+        // revived X (undo.ts, 2026-08-13 ruling). The clone leg above reads X but never
+        // writes it, so its umd is still pristine here.
+        const preserveModified = options.preserveModified === true;
+        const preUmd = preserveModified
+            ? createDbReader(deps.db, now, deps.zone).modDateOf(srcUuid)
+            : null;
+        // 2. Trash the original BEFORE promoting — the clone already holds X's content,
+        // and a live same-titled X would make the promote's project row-selection
+        // ambiguous (H-PROJECT-REPEAT). X survives in the Trash (the recoverable half).
+        const trash = await runMutation(deps, `${kind}.delete`, { uuid: srcUuid }, legOptions(options, txnId, undefined, preserveModified ? { preserveModified: true } : undefined));
+        if (trash.kind !== "ok") {
+            return {
+                ...trash,
+                op,
+                ...("detail" in trash
+                    ? {
+                        detail: `${trash.detail} — the disposable clone (uuid ${cloneUuid}) was created but the ` +
+                            `original ${srcUuid} could not be moved to the Trash, so it was NOT promoted; trash ` +
+                            "the clone and retry",
+                    }
+                    : {}),
+            };
+        }
+        // 3. Native-promote the clone (with the ANCH2 Next drive + derived weekday).
+        const rule = ruleParamsFor(cloneUuid, effParams, nextIso);
+        const promote = kind === "project"
+            ? await promoteProjectViaGui(deps, rule, legOptions(options, txnId, "ui"))
+            : await runMutation(deps, "todo.make-repeating", rule, legOptions(options, txnId, "ui"));
+        if (promote.kind !== "ok") {
+            // The clone persists but was not promoted; best-effort ROLL BACK the trash so
+            // the original is not stranded in the Trash.
+            const restoreOp = kind === "project" ? "project.restore" : "todo.restore";
+            const rolledBack = await runMutation(deps, restoreOp, { uuid: srcUuid }, legOptions(options, txnId));
+            const rollNote = rolledBack.kind === "ok"
+                ? `the original ${srcUuid} was restored from the Trash`
+                : `the original ${srcUuid} could NOT be restored from the Trash — restore it in the app`;
+            return {
+                ...promote,
+                op,
+                ...("detail" in promote
+                    ? {
+                        detail: `${promote.detail} — the disposable clone (uuid ${cloneUuid}) was created but the ` +
+                            `promote did not land; ${rollNote}. Trash the clone and retry`,
+                    }
+                    : {}),
+            };
+        }
+        const { templateUuid } = discoveryOf(promote);
+        let { instanceUuid } = discoveryOf(promote);
+        // Post-drive verify (ANCH2 + YANCH1): the instance START must have landed on the
+        // requested `--when` — for a deadlined rule the driven Next is the deadline
+        // (when + startDaysEarlier) and the app back-shifts the start to `--when`, so the
+        // check is against `expectedStartIso`, not the raw drive date. Fail closed on
+        // mismatch rather than report a wrong-phase ok. The ORACLE is rule-kind dependent
+        // (#508) — see landedFirstStart; an unverifiable after-completion series skips.
+        const afterCompletion = effParams.afterCompletion === true;
+        if (expectedStartIso !== undefined) {
+            const landed = landedFirstStart(deps, templateUuid, instanceUuid, afterCompletion);
+            if (!(afterCompletion && landed === null) && landed !== expectedStartIso) {
+                return nextMismatch(op, templateUuid, expectedStartIso, landed);
+            }
+        }
+        const warnings = [
+            landedRuleEcho(effParams, expectedStartIso ?? firstOccurrenceOf(deps.db, templateUuid)),
+            `the original ${expectedType} (uuid ${srcUuid}) was moved to the Trash; \`things undo\` ` +
+                "removes the new series (trash-both) and restores it",
+            PLACEMENT_NOTE,
+        ];
+        // DBLSPAWN1: if the promote PRESERVED the source (deadline / terminal-element
+        // trigger) as a FUTURE-dated instance, the app would spawn a duplicate on that date
+        // — trash the redundant occurrence and disclose (cursor mints the single real one).
+        const dbl = await trashRedundantFuturePreservedInstance(deps, kind, promote, options, txnId, now, afterCompletion);
+        if (dbl !== null) {
+            warnings.push(dbl.warning);
+            if (instanceUuid === dbl.trashedUuid)
+                instanceUuid = null;
+        }
+        const offRule = offRuleFirstNote(effParams);
+        if (offRule !== null)
+            warnings.push(offRule);
+        if (promote.warnings !== undefined)
+            warnings.push(...promote.warnings);
+        appendPromoteSummary(deps, {
+            startedAt,
+            op,
+            txnId,
+            templateUuid,
+            instanceUuid,
+            originalUuid: srcUuid,
+            invocation: `${op}: clone ${srcUuid} → trash ${srcUuid} → promote ${cloneUuid} → template ${templateUuid}`,
+            requested: effParams,
+            options,
+            ...(preserveModified && preUmd !== null && { preModDates: { [srcUuid]: preUmd } }),
+        });
+        return promoteOk({
+            op,
+            templateUuid,
+            instanceUuid,
+            replacedUuid: cloneUuid,
+            title: srcTitle,
+            txnId,
+            warnings,
+        });
     }
-    const warnings = [
-        landedRuleEcho(effParams, expectedStartIso ?? firstOccurrenceOf(deps.db, templateUuid)),
-        `the original ${expectedType} (uuid ${srcUuid}) was moved to the Trash; \`things undo\` ` +
-            "removes the new series (trash-both) and restores it",
-        PLACEMENT_NOTE,
-    ];
-    // DBLSPAWN1: if the promote PRESERVED the source (deadline / terminal-element
-    // trigger) as a FUTURE-dated instance, the app would spawn a duplicate on that date
-    // — trash the redundant occurrence and disclose (cursor mints the single real one).
-    const dbl = await trashRedundantFuturePreservedInstance(deps, kind, promote, options, txnId, now);
-    if (dbl !== null) {
-        warnings.push(dbl.warning);
-        if (instanceUuid === dbl.trashedUuid)
-            instanceUuid = null;
-    }
-    const offRule = offRuleFirstNote(effParams);
-    if (offRule !== null)
-        warnings.push(offRule);
-    if (promote.warnings !== undefined)
-        warnings.push(...promote.warnings);
-    appendPromoteSummary(deps, {
-        startedAt,
-        op,
-        txnId,
-        templateUuid,
-        instanceUuid,
-        originalUuid: srcUuid,
-        invocation: `${op}: clone ${srcUuid} → trash ${srcUuid} → promote ${cloneUuid} → template ${templateUuid}`,
-        requested: effParams,
-        ...(preserveModified && preUmd !== null && { preModDates: { [srcUuid]: preUmd } }),
-    });
-    return promoteOk({
-        op,
-        templateUuid,
-        instanceUuid,
-        replacedUuid: cloneUuid,
-        title: src.title,
-        txnId,
-        warnings,
-    });
 }
 export function runMakeRepeatingTodo(deps, params, options = {}) {
     return makeRepeatingViaClone(deps, "todo", params, options);
@@ -576,6 +728,12 @@ export function runMakeRepeatingProject(deps, params, options = {}) {
 async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options) {
     const op = kind === "project" ? "project.add-repeating" : "todo.add-repeating";
     assertRepeatRule(rule);
+    // Idempotency FIRST: this verb CREATES, so a blind resubmission is a duplicate
+    // series. The key rides the compound's single summary record, so a match is the
+    // whole verb — the add leg and the promote leg together — not one of them.
+    const replay = replayIfApplied(deps, options);
+    if (replay !== null)
+        return replay;
     // ANCH2 (issue #476): drive the Repeat dialog's "Next:" field with --when so the
     // series starts on the requested date (the field's default is today-anchored but
     // it is editable and honored). YANCH1 (issue #493): also DERIVE the calendar
@@ -595,8 +753,11 @@ async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options
     const whenIso = isIsoDate(addParams["when"]) ? addParams["when"] : null;
     const deadlineShift = rule.deadline === true || (rule.startDaysEarlier ?? 0) > 0 ? (rule.startDaysEarlier ?? 0) : 0;
     const driveIso = whenIso !== null ? addDaysIso(whenIso, deadlineShift) : null;
-    const nextIso = driveIso ?? undefined;
-    const expectedStartIso = whenIso ?? undefined;
+    // The ANCHOR is derived from the deadline-adjusted date; `next` passes through
+    // as the requested START and the promote leg's compile applies the "Next:"
+    // shift — the one place that does (NEXTPOP1; see promoteViaCloneAndMakeRepeating).
+    const nextIso = whenIso ?? undefined;
+    const expectedStartIso = nextIso;
     const effRule = {
         ...rule,
         ...deriveFixedAnchor(rule, driveIso),
@@ -636,165 +797,201 @@ async function addRepeatingViaCreate(deps, kind, addParams, rule, title, options
             },
         };
     }
-    // SESSGATE (#480): refuse a locked / full-screen session BEFORE seeding the row
-    // (the two legs are not atomic — a doomed promote would strand the seed). Zero
-    // mutation on refusal; a window merely on another Space is relocated in-drive.
-    const gate = await gateSessionReachability(deps, op);
+    // PRE-SEED UI PREFLIGHT (#480/#512): refuse a host that cannot drive the window,
+    // or a locked / full-screen session, BEFORE seeding the row (the two legs are not
+    // atomic — a doomed promote would strand the seed). Zero mutation on refusal; a
+    // window merely on another Space is relocated in-drive.
+    const gate = await gateUiPreflight(deps, op);
     if (gate !== null)
         return gate;
     const startedAt = deps.now?.() ?? new Date();
     const txnId = newTxnId(startedAt);
-    // 1. Create the item (full add vocabulary) as an embedded leg.
-    const addOp = kind === "project" ? "project.add" : "todo.add";
-    const add = await runMutation(deps, addOp, addParams, legOptions(options, txnId, "url-scheme"));
-    if (add.kind !== "ok" || add.uuid === null) {
-        return add.kind === "ok"
-            ? {
-                kind: "verify-failed",
-                op,
-                reason: "mismatch",
-                expected: {
-                    mode: "create",
-                    probe: { title, type: expectedType, sinceEpoch: 0 },
-                    assert: [],
-                },
-                observed: null,
-                detail: `the ${expectedType} was created but its uuid was not discovered — it cannot be promoted to repeating`,
-            }
-            : { ...add, op };
+    // COMPOSITE LOCK: add → promote (→ the seed auto-trash / DBLSPAWN1 clean-up)
+    // is one verb, several mutations; hold one lock across all of them so a
+    // concurrent composite cannot land its own legs between ours.
+    return runComposite(deps, op, async () => {
+        const outcome = await addBody();
+        // An unconfirmed outcome gets the compound's AMBIGUOUS summary, so a
+        // resubmission of the same key reconciles instead of creating a second series.
+        return recordAmbiguousPromote(deps, outcome, {
+            startedAt,
+            op,
+            txnId,
+            title,
+            type: expectedType,
+            invocation: `${op}: add "${title}" → promote (unconfirmed)`,
+            requested: { title, ...effRule },
+            options,
+        });
+    });
+    async function addBody() {
+        // 1. Create the item (full add vocabulary) as an embedded leg.
+        const addOp = kind === "project" ? "project.add" : "todo.add";
+        const add = await runMutation(deps, addOp, addParams, legOptions(options, txnId, "url-scheme"));
+        if (add.kind !== "ok" || add.uuid === null) {
+            return add.kind === "ok"
+                ? {
+                    kind: "verify-failed",
+                    op,
+                    reason: "mismatch",
+                    expected: {
+                        mode: "create",
+                        probe: { title, type: expectedType, sinceEpoch: 0 },
+                        assert: [],
+                    },
+                    observed: null,
+                    detail: `the ${expectedType} was created but its uuid was not discovered — it cannot be promoted to repeating`,
+                }
+                : { ...add, op };
+        }
+        const createdUuid = add.uuid;
+        // 2. Native-promote the fresh row (ANCH2 Next drive + derived weekday + the
+        //    base reminder driven onto the series, ADR1).
+        const ruleParams = ruleParamsFor(createdUuid, effRuleWithReminder, nextIso);
+        const promote = kind === "project"
+            ? await promoteProjectViaGui(deps, ruleParams, legOptions(options, txnId, "ui"))
+            : await runMutation(deps, "todo.make-repeating", ruleParams, legOptions(options, txnId, "ui"));
+        if (promote.kind !== "ok") {
+            // The seed persists (the two legs are not atomic) but the promote did not
+            // land. RATIFIED RULING (2026-08-15, issue #480): auto-trash our OWN seed
+            // inside the txn — it is our artifact, recreatable verbatim from the command
+            // args, and the Trash is recoverable — then disclose it. If the auto-trash
+            // itself fails, the result carries the seed's REAL, resolvable uuid with a
+            // working `delete` remediation, so cleanup is never ambiguous (the #480
+            // second bug: a failed add-repeating left a residue whose reported uuid was
+            // not actionable).
+            const patch = await cleanupSeed(deps, kind, createdUuid, promote, options, txnId);
+            return { ...promote, op, ...patch };
+        }
+        const { templateUuid } = discoveryOf(promote);
+        let { instanceUuid } = discoveryOf(promote);
+        // Post-drive verify (ANCH2 + DBLSPAWN1): the instance START must have landed on the
+        // requested `--when` — for a deadlined rule the driven Next is the deadline (when +
+        // startDaysEarlier) and the app back-shifts the start to `--when`, so the check is
+        // against `expectedStartIso`, not the raw drive date. Fail closed on mismatch rather
+        // than report a wrong-phase ok. The series EXISTS here (promote landed) but on the
+        // wrong phase, so this is a genuine partial success, NOT a seed to trash. The
+        // ORACLE is rule-kind dependent (#508) — see landedFirstStart; an after-completion
+        // series verifies against its materialized instance, and skips when it has none.
+        const afterCompletion = effRuleWithReminder.afterCompletion === true;
+        if (expectedStartIso !== undefined) {
+            const landed = landedFirstStart(deps, templateUuid, instanceUuid, afterCompletion);
+            if (!(afterCompletion && landed === null) && landed !== expectedStartIso)
+                return nextMismatch(op, templateUuid, expectedStartIso, landed);
+        }
+        const warnings = [
+            landedRuleEcho(ruleParams, expectedStartIso ?? firstOccurrenceOf(deps.db, templateUuid)),
+            PLACEMENT_NOTE,
+        ];
+        // DBLSPAWN1 backstop: the deadline-mapping above keeps the seed deadline-free (no
+        // SRCFATE preserve), but any OTHER preserve trigger reaching the seed (defensive)
+        // would double-book a future first occurrence — trash the redundant instance.
+        const dbl = await trashRedundantFuturePreservedInstance(deps, kind, promote, options, txnId, startedAt, afterCompletion);
+        if (dbl !== null) {
+            warnings.push(dbl.warning);
+            if (instanceUuid === dbl.trashedUuid)
+                instanceUuid = null;
+        }
+        const offRule = offRuleFirstNote(ruleParams);
+        if (offRule !== null)
+            warnings.push(offRule);
+        if (promote.warnings !== undefined)
+            warnings.push(...promote.warnings);
+        appendPromoteSummary(deps, {
+            startedAt,
+            op,
+            txnId,
+            templateUuid,
+            instanceUuid,
+            invocation: `${op}: add "${title}" ${createdUuid} → template ${templateUuid}`,
+            requested: { title, ...effRule },
+            options,
+        });
+        return promoteOk({
+            op,
+            templateUuid,
+            instanceUuid,
+            replacedUuid: createdUuid,
+            title,
+            txnId,
+            warnings,
+        });
     }
-    const createdUuid = add.uuid;
-    // 2. Native-promote the fresh row (ANCH2 Next drive + derived weekday + the
-    //    base reminder driven onto the series, ADR1).
-    const ruleParams = ruleParamsFor(createdUuid, effRuleWithReminder, nextIso);
-    const promote = kind === "project"
-        ? await promoteProjectViaGui(deps, ruleParams, legOptions(options, txnId, "ui"))
-        : await runMutation(deps, "todo.make-repeating", ruleParams, legOptions(options, txnId, "ui"));
-    if (promote.kind !== "ok") {
-        // The seed persists (the two legs are not atomic) but the promote did not
-        // land. RATIFIED RULING (2026-08-15, issue #480): auto-trash our OWN seed
-        // inside the txn — it is our artifact, recreatable verbatim from the command
-        // args, and the Trash is recoverable — then disclose it. If the auto-trash
-        // itself fails, the result carries the seed's REAL, resolvable uuid with a
-        // working `delete` remediation, so cleanup is never ambiguous (the #480
-        // second bug: a failed add-repeating left a residue whose reported uuid was
-        // not actionable).
-        const patch = await cleanupSeed(deps, kind, createdUuid, promote, options, txnId);
-        return { ...promote, op, ...patch };
+}
+/**
+ * Fold a concrete item-level `deadline` (and/or an explicit `startDaysEarlier`)
+ * into the RULE, returning the rule to promote with and the deadline the SEED
+ * should keep (none — the rule owns it). Shared by the to-do and project
+ * add-repeating verbs so one geometry, and one set of refusals, serves both.
+ *
+ * DBLSPAWN1 (docs/lab/dblspawn1-preserved-instance.md): each occurrence is due
+ * `deadline − when` days after its start (the "Add deadlines" + "start N days
+ * earlier" dialog fields). This is the deadline the series actually wants, and
+ * mapping it up front is also what keeps the SEED deadline-free — a to-do seed
+ * carrying a deadline is SRCFATE-preserved as a materialized instance, and a
+ * future-dated first occurrence then DOUBLE-BOOKS against the template cursor
+ * and spawns a duplicate on the date (cell C). A project seed is DELETE-fate, so
+ * there the un-mapped deadline was simply LOST rather than duplicated — a
+ * quieter bug with the same cause and the same fix. A deadline needs a concrete
+ * `when` (the per-occurrence offset is measured from the start) on/after it.
+ *
+ * DEADLINE/OFFSET AGREEMENT (ruling 2026-08-18): the same rule-global offset can
+ * be named two ways — a concrete `deadline` (offset = deadline − when) OR an
+ * explicit `startDaysEarlier` N (deadline derived as when + N). The geometry
+ * when/deadline/N is OVER-DETERMINED: the dialog's start-offset is rule-global
+ * and the first occurrence's start is derived as due − N, so there is no
+ * per-first-instance gap to absorb a disagreement (unlike DACON1's off-rule-first
+ * calendar freedom). So when BOTH are given they must AGREE — an exact match is
+ * harmless redundancy, a mismatch is inexpressible and refused fast (zero
+ * mutation). Either input ALONE maps to the rule.
+ */
+function mapDeadlineOntoRule(baseRule, when, deadline, startDaysEarlier) {
+    if (!isIsoDate(when)) {
+        throw new RangeError("a repeating --deadline or --start-days-earlier needs a concrete --when date (the deadline " +
+            "offset is measured from each occurrence's start) — schedule the series on a YYYY-MM-DD " +
+            "--when, or drop --deadline / --start-days-earlier");
     }
-    const { templateUuid } = discoveryOf(promote);
-    let { instanceUuid } = discoveryOf(promote);
-    // Post-drive verify (ANCH2 + DBLSPAWN1): the instance START must have landed on the
-    // requested `--when` — for a deadlined rule the driven Next is the deadline (when +
-    // startDaysEarlier) and the app back-shifts the start to `--when`, so the check is
-    // against `expectedStartIso`, not the raw drive date. Fail closed on mismatch rather
-    // than report a wrong-phase ok. The series EXISTS here (promote landed) but on the
-    // wrong phase, so this is a genuine partial success, NOT a seed to trash.
-    if (expectedStartIso !== undefined) {
-        const landed = firstOccurrenceOf(deps.db, templateUuid);
-        if (landed !== expectedStartIso)
-            return nextMismatch(op, templateUuid, expectedStartIso, landed);
+    let startEarlier;
+    if (deadline !== undefined) {
+        const derived = daysBetweenIso(when, deadline);
+        if (derived < 0) {
+            throw new RangeError(`--deadline (${deadline}) must be on or after --when (${when}) — a deadline cannot ` +
+                "precede the occurrence's own start");
+        }
+        if (startDaysEarlier !== undefined && startDaysEarlier !== derived) {
+            throw new RangeError(`--deadline (${deadline}) puts each occurrence's due date ${derived} day` +
+                `${derived === 1 ? "" : "s"} after its start (--when ${when}), but ` +
+                `--start-days-earlier says ${startDaysEarlier} — these disagree. Drop one, or make them ` +
+                `agree (--start-days-earlier ${derived}, or --deadline ${addDaysIso(when, startDaysEarlier)}).`);
+        }
+        startEarlier = derived;
     }
-    const warnings = [
-        landedRuleEcho(ruleParams, expectedStartIso ?? firstOccurrenceOf(deps.db, templateUuid)),
-        PLACEMENT_NOTE,
-    ];
-    // DBLSPAWN1 backstop: the deadline-mapping above keeps the seed deadline-free (no
-    // SRCFATE preserve), but any OTHER preserve trigger reaching the seed (defensive)
-    // would double-book a future first occurrence — trash the redundant instance.
-    const dbl = await trashRedundantFuturePreservedInstance(deps, kind, promote, options, txnId, startedAt);
-    if (dbl !== null) {
-        warnings.push(dbl.warning);
-        if (instanceUuid === dbl.trashedUuid)
-            instanceUuid = null;
+    else {
+        // `--start-days-earlier N` alone: the deadline is derived as when + N. A bad N
+        // (non-integer / negative) is refused by assertRepeatRule once mapped.
+        startEarlier = startDaysEarlier;
     }
-    const offRule = offRuleFirstNote(ruleParams);
-    if (offRule !== null)
-        warnings.push(offRule);
-    if (promote.warnings !== undefined)
-        warnings.push(...promote.warnings);
-    appendPromoteSummary(deps, {
-        startedAt,
-        op,
-        txnId,
-        templateUuid,
-        instanceUuid,
-        invocation: `${op}: add "${title}" ${createdUuid} → template ${templateUuid}`,
-        requested: { title, ...effRule },
-    });
-    return promoteOk({
-        op,
-        templateUuid,
-        instanceUuid,
-        replacedUuid: createdUuid,
-        title,
-        txnId,
-        warnings,
-    });
+    // The RULE owns the deadline; the seed carries none.
+    return {
+        rule: { ...baseRule, deadline: true, startDaysEarlier: startEarlier },
+        seedDeadline: undefined,
+    };
 }
 export async function runAddRepeatingTodo(deps, params, options = {}) {
-    const { frequency, interval, afterCompletion, weekdays, monthly, yearly, ends, startDaysEarlier, ...add } = params;
-    const baseRule = {
-        frequency,
-        interval,
-        ...(afterCompletion !== undefined && { afterCompletion }),
-        ...(weekdays !== undefined && { weekdays }),
-        ...(monthly !== undefined && { monthly }),
-        ...(yearly !== undefined && { yearly }),
-        ...(ends !== undefined && { ends }),
-    };
-    // DBLSPAWN1 (docs/lab/dblspawn1-preserved-instance.md): a concrete item-level
-    // `--deadline <date>` on add-repeating maps to the RULE's deadline — each occurrence
-    // is due `deadline − when` days after its start (the "Add deadlines" + "start N days
-    // earlier" dialog fields). This is the deadline the series actually wants, and it
-    // keeps the SEED deadline-free: a seed carrying a deadline is SRCFATE-preserved as a
-    // materialized instance, and when that first occurrence is future-dated the app
-    // DOUBLE-BOOKS it against the template cursor and spawns a duplicate on the date
-    // (cell C). The seed owning the deadline was the two-step dance the live agent hit
-    // (add-repeating dropped the rule deadline, forcing a follow-up reschedule-repeat);
-    // mapping it up front makes that unnecessary. A deadline needs a concrete `--when`
-    // (the per-occurrence offset is deadline − start) and must be on/after it.
-    //
-    // DEADLINE/OFFSET AGREEMENT (ruling 2026-08-18): the same rule-global offset can be
-    // named two ways — a concrete `--deadline <date>` (offset = deadline − when) OR an
-    // explicit `--start-days-earlier N` (offset = N, deadline derived as when + N). The
-    // geometry when/deadline/N is OVER-DETERMINED: the dialog's start-offset is
-    // rule-global and the first occurrence's start is derived as due − N, so there is no
-    // per-first-instance gap to absorb a disagreement (unlike DACON1's off-rule-first
-    // calendar freedom). So when BOTH are given they must AGREE (`deadline − when == N`)
-    // — an exact match is harmless redundancy, a mismatch is inexpressible and refused
-    // fast (zero mutation). Either input ALONE maps to the rule and keeps the seed
-    // deadline-free.
+    // The rule/add split is driven by the exhaustive key map (splitAddRepeatingRule),
+    // not by a hand-written destructure — a field added to either vocabulary lands on
+    // the right leg instead of falling between them (#549 / YANCH1 #493).
+    const { rule: baseRule, add } = splitAddRepeatingRule(params);
+    const { afterCompletion } = params;
+    const startDaysEarlier = add.startDaysEarlier;
+    // A concrete `--deadline` (or `--start-days-earlier`) belongs to the RULE, not
+    // the seed — see mapDeadlineOntoRule for the geometry and the refusals. The
+    // to-do stakes: an un-mapped seed deadline makes the app preserve the seed as a
+    // future-dated instance that double-books the cursor (DBLSPAWN1 cell C).
     let rule = baseRule;
     let seedDeadline = add.deadline;
     if ((add.deadline !== undefined || startDaysEarlier !== undefined) && afterCompletion !== true) {
-        if (!isIsoDate(add.when)) {
-            throw new RangeError("a repeating --deadline or --start-days-earlier needs a concrete --when date (the deadline " +
-                "offset is measured from each occurrence's start) — schedule the series on a YYYY-MM-DD " +
-                "--when, or drop --deadline / --start-days-earlier");
-        }
-        let startEarlier;
-        if (add.deadline !== undefined) {
-            const derived = daysBetweenIso(add.when, add.deadline);
-            if (derived < 0) {
-                throw new RangeError(`--deadline (${add.deadline}) must be on or after --when (${add.when}) — a deadline cannot ` +
-                    "precede the occurrence's own start");
-            }
-            if (startDaysEarlier !== undefined && startDaysEarlier !== derived) {
-                throw new RangeError(`--deadline (${add.deadline}) puts each occurrence's due date ${derived} day` +
-                    `${derived === 1 ? "" : "s"} after its start (--when ${add.when}), but ` +
-                    `--start-days-earlier says ${startDaysEarlier} — these disagree. Drop one, or make them ` +
-                    `agree (--start-days-earlier ${derived}, or --deadline ${addDaysIso(add.when, startDaysEarlier)}).`);
-            }
-            startEarlier = derived;
-        }
-        else {
-            // `--start-days-earlier N` alone: the deadline is derived as when + N. A bad N
-            // (non-integer / negative) is refused by assertRepeatRule once mapped.
-            startEarlier = startDaysEarlier;
-        }
-        rule = { ...baseRule, deadline: true, startDaysEarlier: startEarlier };
-        seedDeadline = undefined; // the RULE owns the deadline; the seed carries none
+        ({ rule, seedDeadline } = mapDeadlineOntoRule(baseRule, add.when, add.deadline, startDaysEarlier));
     }
     else if (startDaysEarlier !== undefined) {
         // afterCompletion === true here: an after-completion repeat has no calendar
@@ -802,45 +999,54 @@ export async function runAddRepeatingTodo(deps, params, options = {}) {
         throw new RangeError("--start-days-earlier applies only to a fixed-schedule deadline — an after-completion repeat " +
             "has no calendar start to count back from; drop --after-completion or --start-days-earlier");
     }
-    const addParams = {
-        title: add.title,
-        ...(add.notes !== undefined && { notes: add.notes }),
-        ...(add.when !== undefined && { when: add.when }),
-        ...(add.reminder !== undefined && { reminder: add.reminder }),
-        ...(seedDeadline !== undefined && { deadline: seedDeadline }),
-        ...(add.tags !== undefined && { tags: add.tags }),
-        ...(add.checklistItems !== undefined && { checklistItems: add.checklistItems }),
-        ...(add.project !== undefined && { project: add.project }),
-        ...(add.area !== undefined && { area: add.area }),
-        ...(add.heading !== undefined && { heading: add.heading }),
-        ...(add.createdAt !== undefined && { createdAt: add.createdAt }),
-    };
+    // The seed carries the WHOLE add vocabulary by spread (a field added to
+    // TodoAddRepeatingParams reaches the create leg without a line here), minus the
+    // two the rule took: `startDaysEarlier` is rule-only, and the deadline is
+    // whatever the geometry left for the seed (none, once mapped).
+    const addParams = { ...add };
+    delete addParams["startDaysEarlier"];
+    delete addParams["deadline"];
+    if (seedDeadline !== undefined)
+        addParams["deadline"] = seedDeadline;
     return addRepeatingViaCreate(deps, "todo", addParams, rule, add.title, options);
 }
-export function runAddRepeatingProject(deps, params, options = {}) {
-    const { frequency, interval, afterCompletion, weekdays, monthly, yearly, ends, ...add } = params;
-    const rule = {
-        frequency,
-        interval,
-        ...(afterCompletion !== undefined && { afterCompletion }),
-        ...(weekdays !== undefined && { weekdays }),
-        ...(monthly !== undefined && { monthly }),
-        ...(yearly !== undefined && { yearly }),
-        ...(ends !== undefined && { ends }),
-    };
+export async function runAddRepeatingProject(deps, params, options = {}) {
+    // Same exhaustive rule/add split as the to-do verb (one key map, both verbs).
+    const { rule: baseRule, add } = splitAddRepeatingRule(params);
+    const { afterCompletion } = params;
+    // A concrete `--deadline` maps to the RULE here exactly as it does on the to-do
+    // verb (DBLSPAWN1 residual). The project stakes are quieter than the to-do's but
+    // no more acceptable: a project seed is DELETE-fate, so the app does not preserve
+    // it into a double-booked instance — it simply DROPS the deadline, and the series
+    // came out undeadlined with nothing said. Mapped, every occurrence is due
+    // `deadline − when` days after its start.
+    let rule = baseRule;
+    let seedDeadline = add.deadline;
+    if (add.deadline !== undefined) {
+        if (afterCompletion === true) {
+            // The to-do verb can leave a deadline on an after-completion seed because
+            // that seed SURVIVES as the series' instance. An after-completion project's
+            // seed is deleted and its instance is minted deadline-free (RSIM-P P4), so
+            // the deadline would vanish either way — refuse rather than drop it quietly.
+            throw new RangeError("an after-completion repeating project cannot carry a --deadline: the rule has no calendar " +
+                "start to measure a per-occurrence deadline from, and the created project is replaced by " +
+                "the series' own instance, which is created without one — drop --after-completion to " +
+                "deadline every occurrence, or drop --deadline");
+        }
+        ({ rule, seedDeadline } = mapDeadlineOntoRule(baseRule, add.when, add.deadline, undefined));
+    }
     // Seed a pure-AX taxonomy: an area lands a selectable AREA-view row; otherwise
     // create in Someday (UIC4-f) so the promote skips the anytime-header problem.
     const seedWhen = add.when ?? (add.area === undefined ? "someday" : undefined);
-    const addParams = {
-        title: add.title,
-        ...(add.notes !== undefined && { notes: add.notes }),
-        ...(add.area !== undefined && { area: add.area }),
-        ...(seedWhen !== undefined && { when: seedWhen }),
-        ...(add.deadline !== undefined && { deadline: add.deadline }),
-        ...(add.todos !== undefined && { todos: add.todos }),
-        ...(add.items !== undefined && { items: add.items }),
-        ...(add.createdAt !== undefined && { createdAt: add.createdAt }),
-    };
+    // The whole add vocabulary by spread (see the to-do verb), with the two the
+    // promote owns re-derived: the seed taxonomy `when` and the mapped deadline.
+    const addParams = { ...add };
+    delete addParams["when"];
+    delete addParams["deadline"];
+    if (seedWhen !== undefined)
+        addParams["when"] = seedWhen;
+    if (seedDeadline !== undefined)
+        addParams["deadline"] = seedDeadline;
     return addRepeatingViaCreate(deps, "project", addParams, rule, add.title, options);
 }
 // ====================================================== template-direct clone
@@ -941,95 +1147,103 @@ export async function cloneTemplateViaRepromote(deps, kind, src, srcUuid, params
             },
         };
     }
-    // SESSGATE (#480): refuse a locked / full-screen session BEFORE minting the
-    // plain clone (a doomed promote would strand it). Zero mutation on refusal.
-    const gate = await gateSessionReachability(deps, op);
+    // PRE-SEED UI PREFLIGHT (#480/#512): refuse a host that cannot drive the window,
+    // or a locked / full-screen session, BEFORE minting the plain clone (a doomed
+    // promote would strand it). Zero mutation on refusal.
+    const gate = await gateUiPreflight(deps, op);
     if (gate !== null)
         return gate;
-    const startedAt = deps.now?.() ?? new Date();
-    const txnId = newTxnId(startedAt);
-    // 4. Mint the plain clone as an embedded leg — cloneTemplateAsPlain reaches the
-    //    clone orchestrator's plain-content path (recurrence + schedule stripped);
-    //    --title/--preserve-created ride through the CloneParams.
-    const cloneParams = {
-        uuid: srcUuid,
-        ...(params.title !== undefined && { title: params.title }),
-        ...(params.preserveCreated === true && { preserveCreated: true }),
-    };
-    const cloneOptions = { ...legOptions(options, txnId), cloneTemplateAsPlain: true };
-    const clone = kind === "project"
-        ? await runCloneProject(deps, cloneParams, cloneOptions)
-        : await runCloneTodo(deps, cloneParams, cloneOptions);
-    if (clone.kind !== "ok" || clone.uuid === null) {
-        // A nested-repeater refusal (a template CONTAINING a nested repeater) or any
-        // clone failure surfaces coherently here — re-label it to the compound op.
-        return clone.kind === "ok"
-            ? {
-                kind: "verify-failed",
-                op,
-                reason: "mismatch",
-                expected: {
-                    mode: "create",
-                    probe: { title, type: expectedType, sinceEpoch: 0 },
-                    assert: [],
-                },
-                observed: null,
-                detail: "the plain clone was created but its uuid was not discovered — nothing was promoted",
-            }
-            : { ...clone, op };
-    }
-    const cloneUuid = clone.uuid;
-    // 5. Native-promote the clone with the FULL decoded rule (ruleToInverseParams
-    //    carries deadline/start-earlier + the calendar anchors + ends).
-    const ruleParams = { uuid: cloneUuid, ...inverse };
-    const promote = kind === "project"
-        ? await promoteProjectViaGui(deps, ruleParams, legOptions(options, txnId, "ui"))
-        : await runMutation(deps, "todo.make-repeating", ruleParams, legOptions(options, txnId, "ui"));
-    if (promote.kind !== "ok") {
-        // The plain clone persists but was not promoted — honest report (no original
-        // to roll back; the clone is a fresh row the caller can trash and retry).
-        return {
-            ...promote,
-            op,
-            ...("detail" in promote
+    // COMPOSITE LOCK: clone-as-plain → promote-with-the-source's-rule is one verb;
+    // hold one lock across both legs.
+    return runComposite(deps, op, async () => {
+        const startedAt = deps.now?.() ?? new Date();
+        const txnId = newTxnId(startedAt);
+        // 4. Mint the plain clone as an embedded leg — cloneTemplateAsPlain reaches the
+        //    clone orchestrator's plain-content path (recurrence + schedule stripped);
+        //    --title/--preserve-created ride through the CloneParams.
+        const cloneParams = {
+            uuid: srcUuid,
+            ...(params.title !== undefined && { title: params.title }),
+            ...(params.preserveCreated === true && { preserveCreated: true }),
+        };
+        const cloneOptions = {
+            ...legOptions(options, txnId),
+            cloneTemplateAsPlain: true,
+        };
+        const clone = kind === "project"
+            ? await runCloneProject(deps, cloneParams, cloneOptions)
+            : await runCloneTodo(deps, cloneParams, cloneOptions);
+        if (clone.kind !== "ok" || clone.uuid === null) {
+            // A nested-repeater refusal (a template CONTAINING a nested repeater) or any
+            // clone failure surfaces coherently here — re-label it to the compound op.
+            return clone.kind === "ok"
                 ? {
-                    detail: `${promote.detail} — the plain clone (uuid ${cloneUuid}) was created but the promote ` +
-                        `did not land; trash the clone with \`things ${kind} delete ${cloneUuid}\` and retry`,
+                    kind: "verify-failed",
+                    op,
+                    reason: "mismatch",
+                    expected: {
+                        mode: "create",
+                        probe: { title, type: expectedType, sinceEpoch: 0 },
+                        assert: [],
+                    },
+                    observed: null,
+                    detail: "the plain clone was created but its uuid was not discovered — nothing was promoted",
                 }
-                : {}),
-        };
-    }
-    const { templateUuid, instanceUuid } = discoveryOf(promote);
-    const warnings = [NEW_SERIES_NOTE, PLACEMENT_NOTE];
-    if (params.preserveCreated === true) {
-        warnings.push("--preserve-created is best-effort on a template clone: the promote may replace the clone " +
-            "row with the new template, whose creation date is the conversion time");
-    }
-    if (src.repeating.paused === true) {
-        warnings.push(`the source template was PAUSED; the new series is created UNPAUSED and begins spawning — ` +
-            `pause it with \`things ${kind} pause-repeat\` if you want it suspended`);
-    }
-    if (promote.warnings !== undefined)
-        warnings.push(...promote.warnings);
-    // Summary WITHOUT originalUuid → undo is the add-repeating trash-both (remove
-    // the minted series; there is no original to restore).
-    appendPromoteSummary(deps, {
-        startedAt,
-        op,
-        txnId,
-        templateUuid,
-        instanceUuid,
-        invocation: `${kind}.clone (template) ${srcUuid}: clone → promote ${cloneUuid} → template ${templateUuid}`,
-        requested: { source: srcUuid, title, ...inverse },
-    });
-    return promoteOk({
-        op,
-        templateUuid,
-        instanceUuid,
-        replacedUuid: cloneUuid,
-        title,
-        txnId,
-        warnings,
+                : { ...clone, op };
+        }
+        const cloneUuid = clone.uuid;
+        // 5. Native-promote the clone with the FULL decoded rule (ruleToInverseParams
+        //    carries deadline/start-earlier + the calendar anchors + ends).
+        const ruleParams = { uuid: cloneUuid, ...inverse };
+        const promote = kind === "project"
+            ? await promoteProjectViaGui(deps, ruleParams, legOptions(options, txnId, "ui"))
+            : await runMutation(deps, "todo.make-repeating", ruleParams, legOptions(options, txnId, "ui"));
+        if (promote.kind !== "ok") {
+            // The plain clone persists but was not promoted — honest report (no original
+            // to roll back; the clone is a fresh row the caller can trash and retry).
+            return {
+                ...promote,
+                op,
+                ...("detail" in promote
+                    ? {
+                        detail: `${promote.detail} — the plain clone (uuid ${cloneUuid}) was created but the promote ` +
+                            `did not land; trash the clone with \`things ${kind} delete ${cloneUuid}\` and retry`,
+                    }
+                    : {}),
+            };
+        }
+        const { templateUuid, instanceUuid } = discoveryOf(promote);
+        const warnings = [NEW_SERIES_NOTE, PLACEMENT_NOTE];
+        if (params.preserveCreated === true) {
+            warnings.push("--preserve-created is best-effort on a template clone: the promote may replace the clone " +
+                "row with the new template, whose creation date is the conversion time");
+        }
+        if (src.repeating.paused === true) {
+            warnings.push(`the source template was PAUSED; the new series is created UNPAUSED and begins spawning — ` +
+                `pause it with \`things ${kind} pause-repeat\` if you want it suspended`);
+        }
+        if (promote.warnings !== undefined)
+            warnings.push(...promote.warnings);
+        // Summary WITHOUT originalUuid → undo is the add-repeating trash-both (remove
+        // the minted series; there is no original to restore).
+        appendPromoteSummary(deps, {
+            startedAt,
+            op,
+            txnId,
+            templateUuid,
+            instanceUuid,
+            invocation: `${kind}.clone (template) ${srcUuid}: clone → promote ${cloneUuid} → template ${templateUuid}`,
+            requested: { source: srcUuid, title, ...inverse },
+        });
+        return promoteOk({
+            op,
+            templateUuid,
+            instanceUuid,
+            replacedUuid: cloneUuid,
+            title,
+            txnId,
+            warnings,
+        });
     });
 }
 //# sourceMappingURL=promote-clone.js.map