things-api 0.18.0 → 0.19.1

package/dist/write/vectors/ui-recipes.js

@@ -64,6 +64,36 @@ export function pauseRepeatRecipe(targetUuid) {
         ],
     };
 }
+/**
+ * `Items ▸ Repeat ▸ Create Next Copy` — Things 3.23's "spawn the pending
+ * occurrence now" command, and the first half of every template mutation we
+ * ship (CNC1, docs/lab/cnc1-template-mutations.md).
+ *
+ * One press materializes the instance the projection cursor points at AND
+ * advances the series, and the template delta is FIELD FOR FIELD what the app's
+ * own `Make Exception` writes (`rt1_instanceCreationCount +1`,
+ * `rt1_instanceCreationStartDate` → consumed slot + 1, `rt1_nextInstanceStartDate`
+ * → the next rule date, `todayIndexReferenceDate` → the cursor, `umd` silent,
+ * rule blob untouched) — measured on a fixed weekly rule against REPX3 §1.2 and
+ * on a daily rule against §2.1. Mutating the minted instance afterwards is
+ * therefore the exception the chooser withholds from automation.
+ *
+ * Template-only, like every verb in this submenu: with an INSTANCE selected the
+ * `Items` menu carries no `Repeat` item at all (REPX1 §5.1), which is what the
+ * eligibility assert catches before the press.
+ */
+export function createNextCopyRecipe(targetUuid) {
+    const item = `menu item "Create Next Copy" of menu 1 of menu item "Repeat" of ${ITEMS_MENU}`;
+    return {
+        op: "todo.create-next-copy",
+        targetUuid,
+        steps: [
+            ...preamble(targetUuid),
+            assertEligible(targetUuid, item),
+            menuPress("Items ▸ Repeat ▸ Create Next Copy", item, REPEAT_SUBMENU_ANCHOR),
+        ],
+    };
+}
 export function resumeRepeatRecipe(targetUuid) {
     return {
         op: "todo.resume-repeat",
@@ -82,12 +112,20 @@ export function convertToProjectRecipe(op, targetUuid) {
         steps: [
             ...preamble(targetUuid),
             menuPress("Items ▸ Convert to Project…", `menu item "Convert to Project…" of ${ITEMS_MENU}`),
+            // positional-ok: a window presents at most ONE attached sheet at a time, so
+            // `sheet 1` is a uniqueness statement, not an index among peers. It is also
+            // only ever a WAIT target here — the control acted on inside it is
+            // AXIdentifier-addressed below.
             waitFor("the confirmation sheet", `sheet 1 of ${MAIN_WINDOW}`),
             {
                 // The alert's primary button carries a stable, locale-proof
                 // AXIdentifier "action-button-1" (UIC1); prefer it over the English title.
+                // positional-ok: the `sheet 1` container is the one-sheet-per-window law
+                // above; the BUTTON is discriminated by AXIdentifier, never by position.
                 primitive: "press",
                 label: 'confirm — press "Convert"',
+                // positional-ok: `sheet 1` is the one attached sheet a window can present;
+                // the BUTTON inside it is AXIdentifier-discriminated, never positional.
                 path: `(first button of sheet 1 of ${MAIN_WINDOW} whose value of attribute "AXIdentifier" is "action-button-1")`,
                 dynamic: true,
                 addressing: "axidentifier",
@@ -107,6 +145,60 @@ export function convertToProjectRecipe(op, targetUuid) {
  * DB effect (UI2-d / HEADCERT1): the heading uuid dies, a new type=1 project is
  * promoted into the parent project's area, its children reparent (heading→NULL).
  */
+/**
+ * Reorder a project's HEADINGS with the arrow chords (CHORDMH1, on the HEADORD1
+ * law). Things exposes heading order through four bare keybindings and nothing
+ * else — no menu item, no context-menu item, no AX action anywhere carries the
+ * equivalent — so the recipe has no element to press: it reveals the project,
+ * confirms the content table is there, and hands the whole move to the chord
+ * driver, which selects each heading positionally and posts one verified chord
+ * at a time (src/write/vectors/ui-chord.ts).
+ *
+ * NO `activate` step, deliberately. The reveal is a background `open -g`, the
+ * row selection is pure System Events, and the chord is posted to the Things
+ * PROCESS rather than to the focused surface — so the entire gesture runs with
+ * Things behind whatever the user is looking at. Measured end to end on Things
+ * 3.23 / golden-v4 with Finder frontmost at every stage and Things never
+ * activated at all (docs/lab/chordmh1-move-heading-build.md §1).
+ *
+ * `needsWindowReachability` is set even though no sheet opens: the heading rows
+ * only exist in a rendered project view, so a locked screen or a full-screen
+ * Space must refuse (SESSGATE) rather than post chords at a window nothing can
+ * read back.
+ */
+export function moveHeadingChordRecipe(projectUuid, targetOrder, movees) {
+    const spec = {
+        projectUuid,
+        targetOrder,
+        movees,
+        tablePath: PROJECT_CONTENT_TABLE,
+    };
+    return {
+        op: "project.move-heading",
+        targetUuid: spec.projectUuid,
+        needsWindowReachability: true,
+        steps: [
+            {
+                primitive: "reveal",
+                label: "reveal the project in Things (things:///show?id=<project>)",
+                value: spec.projectUuid,
+            },
+            {
+                // Canaried: if the project view's content table is not there, the drive
+                // refuses before a single chord is posted.
+                primitive: "resolve",
+                label: "confirm the project view's content table is present",
+                path: PROJECT_CONTENT_TABLE,
+                addressing: "title",
+            },
+            {
+                primitive: "chord-reorder",
+                label: `reorder ${spec.movees.length} heading(s) with the arrow chords`,
+                chord: spec,
+            },
+        ],
+    };
+}
 export function headingConvertToProjectRecipe(projectUuid, ordinal) {
     return {
         op: "project.promote-heading",
@@ -135,12 +227,17 @@ export function headingConvertToProjectRecipe(projectUuid, ordinal) {
             // With the heading selected, Convert to Project… is enabled (it exists
             // regardless, so the canary resolves it; the press lands post-selection).
             menuPress("Items ▸ Convert to Project…", `menu item "Convert to Project…" of ${ITEMS_MENU}`),
+            // positional-ok: one attached sheet per window (see convertToProjectRecipe).
             waitFor("the confirmation sheet", `sheet 1 of ${MAIN_WINDOW}`),
             {
                 // The alert's primary button carries the locale-proof AXIdentifier
                 // "action-button-1" (UIC1); prefer it over the English title.
+                // positional-ok: one attached sheet per window; the button itself is
+                // AXIdentifier-discriminated.
                 primitive: "press",
                 label: 'confirm — press "Convert"',
+                // positional-ok: `sheet 1` is the one attached sheet a window can present;
+                // the BUTTON inside it is AXIdentifier-discriminated, never positional.
                 path: `(first button of sheet 1 of ${MAIN_WINDOW} whose value of attribute "AXIdentifier" is "action-button-1")`,
                 dynamic: true,
                 addressing: "axidentifier",
@@ -168,9 +265,16 @@ export function headingConvertToProjectRecipe(projectUuid, ordinal) {
 // The reminder-time control is undrivable (its AXDateTimeArea ignores AX writes),
 // so `--reminder` is refused upstream in assertRepeatRule; its recipe step is
 // retained but unreachable.
-/** The content list's table (row 0 = area/Someday header, then projects/to-dos). Confirmed UIC5. */
+/** The content list's table (row 0 = area/Someday header, then projects/to-dos). Confirmed UIC5.
+ *  positional-ok: a CONTAINER handle only — the main window's list area holds one
+ *  scroll area holding one table (UIC5), and no value is read or written through
+ *  this path. Every step that uses it resolves its target WITHIN the table by
+ *  title readback (select-row), by selection-readback ordinal (select-heading-row)
+ *  or by exact AXDescription (click-element's rowCellDescription walk, HXPC1 §B0). */
 const PROJECT_CONTENT_TABLE = `table 1 of scroll area 1 of ${MAIN_WINDOW}`;
-/** The Repeat editor when Things is frontmost — an attached sheet (interval nested in group 1, UIC1). */
+/** The Repeat editor when Things is frontmost — an attached sheet (interval nested in group 1, UIC1).
+ *  positional-ok: a window presents at most ONE attached sheet at a time, so
+ *  `sheet 1` names the only sheet there can be rather than picking among peers. */
 const REPEAT_SHEET = `sheet 1 of ${MAIN_WINDOW}`;
 /** The Repeat editor when Things is backgrounded — a detached AXUnknown window (UIC4-a). Its
  *  controls sit at the SAME depth as the sheet's (frequency a direct child, interval in group 1) — UIC5-e. */
@@ -182,10 +286,25 @@ function dualForm(inner) {
     return DIALOG_SHELLS.map((shell) => `${inner} of ${shell}`);
 }
 // --- CERTIFIED controls (UIC1/UIC5) --------------------------------------
-/** Frequency pop-up — a direct child of the dialog. */
+//
+// WHY THE POP-UPS BELOW MAY STAY POSITIONAL WHILE THE TEXT FIELDS MAY NOT.
+// A pop-up drive is SELF-DISCRIMINATING: `select-popup` opens the control and
+// clicks a menu item matched by its pinned English NAME, so a mis-addressed
+// pop-up has no such item and the step fails closed ("none of the candidate menu
+// items exist"). A text field accepts any string silently — which is precisely
+// how #589 wrote an interval into the ends-count field. The pop-up label sets are
+// also disjoint across the cadence group (`never`/`after`/`on date` for the ends
+// bound; `day(s)`…`year(s)` for the after-completion unit; weekday names, ordinals
+// and month names for the anchors), so a swapped index cannot land a plausible
+// value. Belt and braces: the PRE-COMMIT AUDIT re-reads every one of them by value
+// before the OK press, so a pop-up that took a wrong-but-existing item is caught
+// before anything is committed.
+/** Frequency pop-up — a direct child of the dialog.
+ *  positional-ok: MEASURED sole direct-child pop-up of the dialog shell in every
+ *  reachable state — the shell carries `popups=1`, every other pop-up living in the
+ *  cadence group (CGRD1 §B census, all four frequencies + after-completion). Its
+ *  menu items are matched by name, and the pre-commit audit re-reads its value. */
 const DIALOG_FREQUENCY = dualForm("pop up button 1");
-/** Interval field — nested in group 1 (UIC5-e). */
-const DIALOG_INTERVAL = dualForm("text field 1 of group 1");
 /** OK button. */
 const DIALOG_OK = dualForm(`button "OK"`);
 // --- UIC6-CERTIFIED controls, RE-INDEXED PER DIALOG SHAPE (RDLG2) ----------
@@ -199,18 +318,45 @@ const DIALOG_OK = dualForm(`button "OK"`);
 // driver measures in the open dialog (`probe-dialog-shape`), never to the app
 // version. Titles/`_NS:` ids are never used (both drift). Evidence:
 // docs/lab/uic6-rule-vocabulary.md (≤3.22) and docs/lab/rdlg2-323-recipe-cert.md.
-/** After-completion cadence unit pop-up — the ONLY group pop-up in that mode (both shapes). */
+/** After-completion cadence unit pop-up — the ONLY group pop-up in that mode (both shapes).
+ *  positional-ok: this and DIALOG_ENDS are the SAME spelling because they are the
+ *  same slot in two MUTUALLY EXCLUSIVE dialog states, and the recipe emits exactly
+ *  one of them per drive. Measured (CGRD1 §A census): an after-completion cadence
+ *  group has `popups=1` and no `Ends:` label at all, while every fixed frequency
+ *  puts the ends bound at group pop-up 1. Their menu-item sets are disjoint
+ *  (`day(s)`…`year(s)` vs `never`/`after`/`on date`), so a wrong-state drive fails
+ *  closed on the item name; the pre-commit audit re-reads whichever one ran. */
 const DIALOG_AC_UNIT = dualForm("pop up button 1 of group 1");
-/** "Ends" bound pop-up (`never` · `after` · `on date`) — always pop up button 1 of the group. */
+/** "Ends" bound pop-up (`never` · `after` · `on date`) — always pop up button 1 of the group.
+ *  positional-ok: see DIALOG_AC_UNIT — one slot, two exclusive states, name-matched
+ *  items, audited before the commit. */
 const DIALOG_ENDS = dualForm("pop up button 1 of group 1");
-/** The cadence group itself — the handle the shape probe and the weekday converge address. */
+/** The cadence group itself — the handle the shape probe and the weekday converge address.
+ *  positional-ok: MEASURED sole group of the dialog shell (`groups=1` in every
+ *  state, CGRD1 §B), and a CONTAINER handle only — every primitive that takes it
+ *  (set-group-number, probe-dialog-shape, converge-weekdays, audit-dialog)
+ *  discriminates WITHIN it by label row or control class and fails closed on
+ *  anything but exactly one match. */
 const DIALOG_GROUP = dualForm("group 1");
-/** The 3.23 `Next:` first-occurrence pop-up — group pop-up 2 (this shape only). */
+/** The 3.23 `Next:` first-occurrence pop-up — group pop-up 2 (this shape only).
+ *  positional-ok: reachable ONLY under a MEASURED dialog shape — the recipe's
+ *  probe-dialog-shape step must have returned `next-popup` (a positive match on the
+ *  control class occupying the `Next:` row) before this step runs, and an
+ *  unrecognized shape refuses the drive. The drive then matches a menu item by
+ *  PARSED DATE and reads the pop-up back; the pre-commit audit re-parses it. */
 const DIALOG_NEXT_POPUP = dualForm("pop up button 2 of group 1");
-/** A group pop-up addressed at DIFFERENT indices in the two dialog shapes (RDLG2). */
+/** A group pop-up addressed at DIFFERENT indices in the two dialog shapes (RDLG2).
+ *  positional-ok: the index is not a guess but the MEASURED consequence of the
+ *  shape the drive probed — CGRD1 §A counts the cadence group's pop-ups per
+ *  frequency on 3.23 (daily 2 · weekly 3 · monthly 4 · yearly 5, i.e. Ends + Next +
+ *  the per-frequency controls), which is the +1 fork these two index sets encode.
+ *  A step carrying `shaped` with no shape probed fails closed. Every one of these
+ *  is a name-matched pop-up, and all of them are re-read by the pre-commit audit. */
 function shapedPopup(nextPopupIndex, legacyIndex) {
     return {
+        // positional-ok: shape-MEASURED index, per this function's contract above.
         "next-popup": { pathCandidates: dualForm(`pop up button ${nextPopupIndex} of group 1`) },
+        // positional-ok: shape-MEASURED index, per this function's contract above.
         legacy: { pathCandidates: dualForm(`pop up button ${legacyIndex} of group 1`) },
     };
 }
@@ -228,13 +374,23 @@ const DIALOG_YEAR_ORDINAL = shapedPopup(5, 4);
  * the add button from live structure).
  */
 const WEEKDAY_BASE = { "next-popup": 3, legacy: 2 };
-/** "Ends after [n]" count field — becomes text field 1 of the group once shown (interval was set earlier while it was the sole field). */
-const DIALOG_ENDS_COUNT = dualForm("text field 1 of group 1");
 /** "Add reminders" checkbox (sheet-level, title-pinned). The time is an AXDateTimeArea driven by set-datetime. */
 const DIALOG_ADD_REMINDERS = dualForm(`checkbox "Add reminders"`);
-/** "Add deadlines" checkbox + the "start N days earlier" field it reveals as a DIRECT sheet child (text field 1 of the shell). */
+/** "Add deadlines" checkbox + the "and start [n] days earlier" offset field it reveals. */
 const DIALOG_ADD_DEADLINES = dualForm(`checkbox "Add deadlines"`);
-const DIALOG_START_EARLIER = dualForm("text field 1");
+/**
+ * The pinned English static text whose ROW the start-offset field sits on. The
+ * field shipped as `text field 1` of the dialog shell — a value-bearing numeric
+ * field picked by index out of a tree whose shape depends on the "Add deadlines"
+ * checkbox, verified only by re-reading the same index it wrote. That is the #589
+ * error class, and it happened to be right rather than provably right: measured on
+ * 3.23, the shell carries 0 direct text fields with deadlines OFF and exactly 1
+ * with them ON — `[and start] [ 0 ] [days earlier]`, the field at y=409 against the
+ * label's y=413 — whether or not reminders are also on (CGRD1 §B census). Now the
+ * field is found by that label's row, exactly like the cadence numbers, and
+ * anything but one match on it fails closed with the shell's field inventory.
+ */
+const DIALOG_START_EARLIER_LABEL = "days earlier";
 /**
  * After-completion cadence-unit pop-up labels. The options are NOT the frequency
  * word (`weekly`) — they are the time unit, and the app PLURALIZES them by the
@@ -317,11 +473,52 @@ function selectPopupAny(label, pathCandidates, valueCandidates) {
         addressing: "title",
     };
 }
-function setField(label, pathCandidates, value) {
+/**
+ * Drive a dialog-SHELL text field addressed by the pinned English label sharing
+ * its row — the {@link setGroupNumber} discrimination law, applied outside the
+ * cadence group. Its one caller is the start-days-earlier offset; see
+ * {@link DIALOG_START_EARLIER_LABEL} for why the old `text field 1` spelling had
+ * to go even though it resolved correctly on 3.23.
+ */
+function setRowField(label, rowLabel, value) {
     return {
-        primitive: "set-value",
+        primitive: "set-row-field",
         label,
-        pathCandidates,
+        pathCandidates: DIALOG_SHELLS,
+        rowLabel,
+        value,
+        dynamic: true,
+        addressing: "title",
+    };
+}
+/**
+ * Drive one of the Repeat dialog's TWO numeric fields — the cadence interval
+ * ("Every [n] days") or the "Ends: after [n] times" count. Both are text fields
+ * of the cadence group, and WHICH INDEX each holds depends on the dialog's
+ * state rather than on which one the caller means. Measured on Things 3.23
+ * (HXPC1, docs/lab/hxpc1-picker-assert.md §A):
+ *
+ *   Ends: never   →  1 text field  ·  #1 interval @[311,283]
+ *   Ends: after N →  2 text fields ·  #1 COUNT    @[402,372]  (`Ends:` label y=375)
+ *                                     #2 interval @[311,283]  (`Every` label y=286)
+ *
+ * Both used to be spelled `text field 1 of group 1`, which the create path
+ * survived only because it drives the interval BEFORE selecting the ends bound,
+ * while it is still the sole field. A RESCHEDULE opens the dialog PRE-POPULATED:
+ * a rule that already ends after N presents both fields from the first step, so
+ * the interval drive wrote the requested interval into the count field and the
+ * count drive then overwrote it — the interval never changed. The driver now
+ * resolves each field by the ROW it sits on (the count shares the `Ends:`
+ * label's row, the interval does not), which is order-independent and covers the
+ * after-completion dialog too: that one offers no ends bound at all, so the
+ * interval is again the only field. See ui.ts `axSetGroupNumberScript`.
+ */
+function setGroupNumber(label, numberTarget, value) {
+    return {
+        primitive: "set-group-number",
+        label,
+        pathCandidates: DIALOG_GROUP,
+        numberTarget,
         value,
         dynamic: true,
         addressing: "title",
@@ -423,7 +620,7 @@ function repeatDialogEntry(rule) {
     else {
         steps.push(selectPopup(`frequency = ${rule.frequency}`, DIALOG_FREQUENCY, rule.frequency));
     }
-    steps.push(setField(`interval = ${rule.interval}`, DIALOG_INTERVAL, String(rule.interval)));
+    steps.push(setGroupNumber(`interval = ${rule.interval}`, "interval", String(rule.interval)));
     // MEASURE the dialog before touching any control the 3.23 redesign moved
     // (RDLG2). Emitted only when such a control is actually addressed, so the
     // certified two-control path (frequency + interval + OK) costs no extra hop —
@@ -471,6 +668,31 @@ function repeatDialogEntry(rule) {
         steps.push(selectPopupShaped(`yearly month = ${y.month}`, DIALOG_YEAR_MONTH, MONTH_TITLE[y.month - 1] ?? ""));
         steps.push(...monthlyAnchorSteps(y, DIALOG_YEAR_MODE, DIALOG_YEAR_ORDINAL));
     }
+    // LET THE `Next:` POP-UP ABSORB THE RULE (NEXTPOP1) before any further input.
+    //
+    // The 3.23 dialog recomputes its first-occurrence pop-up — the displayed date
+    // AND the menu of occurrences behind it — ASYNCHRONOUSLY, ~0.4s after the
+    // calendar anchor moves, and an input that lands inside that window CANCELS
+    // the recompute permanently: the control keeps describing the PREVIOUS rule.
+    // The very next thing this recipe drives is the deadline checkbox, which is
+    // exactly such an input, so every deadlined monthly/yearly promote reached
+    // `select-next-occurrence` with the SEED's occurrence series in the menu and
+    // failed closed on a date the rule really does produce (VMRES1 §4.3).
+    //
+    // Emitted for the pop-up shape only — the ≤3.22 `Next:` is a free date area
+    // with no menu to recompute — and never for after-completion, which has no
+    // first-occurrence control at all. It is a WAIT, not a setter, so it
+    // contributes no control to the pre-commit audit.
+    if (needsShape && rule.afterCompletion !== true) {
+        steps.push({
+            primitive: "settle-occurrences",
+            label: "let the first-occurrence pop-up absorb the rule",
+            pathCandidates: DIALOG_NEXT_POPUP,
+            onlyShape: "next-popup",
+            dynamic: true,
+            addressing: "title",
+        });
+    }
     // "Add deadlines" / "start N days earlier" — DEADLINE MODE, converged (RRD1)
     // BEFORE the "Next:" field is driven below. In deadline mode the "Next:" field IS
     // the deadline date and the instance start = deadline − startDaysEarlier (YANCH1
@@ -496,7 +718,7 @@ function repeatDialogEntry(rule) {
         // startDaysEarlier is requested-fields-only too: drive the offset field only
         // when it was given (>0), else leave it at its pre-populated value.
         if (deadlineTarget && (rule.startDaysEarlier ?? 0) > 0) {
-            steps.push(setField(`start ${rule.startDaysEarlier} days earlier`, DIALOG_START_EARLIER, String(rule.startDaysEarlier)));
+            steps.push(setRowField(`start ${rule.startDaysEarlier} days earlier`, DIALOG_START_EARLIER_LABEL, String(rule.startDaysEarlier)));
         }
     }
     // Ends bound + "Next:" first-occurrence field (ANCH2, issue #476). ORDER MATTERS:
@@ -508,7 +730,7 @@ function repeatDialogEntry(rule) {
     const endsOnDate = rule.ends !== undefined && rule.ends.kind === "on-date" ? rule.ends : null;
     if (rule.ends !== undefined && rule.ends.kind === "after") {
         steps.push(selectPopup("ends = after", DIALOG_ENDS, "after"));
-        steps.push(setField(`ends after = ${rule.ends.count}`, DIALOG_ENDS_COUNT, String(rule.ends.count)));
+        steps.push(setGroupNumber(`ends after = ${rule.ends.count}`, "ends-count", String(rule.ends.count)));
     }
     else if (endsOnDate !== null) {
         steps.push(selectPopup("ends = on date", DIALOG_ENDS, "on date"));
@@ -550,9 +772,159 @@ function repeatDialogEntry(rule) {
         steps.push(ensureCheckbox("Add reminders", DIALOG_ADD_REMINDERS, true));
         steps.push(setDateTime(`reminder = ${rule.reminder}`, `time:${rule.reminder}`, "reminder"));
     }
+    const audit = dialogAuditStep(steps);
+    if (audit !== null)
+        steps.push(audit);
     steps.push(pressControl('press "OK"', DIALOG_OK));
     return steps;
 }
+/**
+ * Build the PRE-COMMIT FULL-DIALOG AUDIT step from the drive's OWN step list
+ * (CGRD1) — the last thing that runs before the OK press.
+ *
+ * Derivation from the steps, rather than a second hand-written list of controls,
+ * is the point: every setter the recipe emits contributes exactly one audit
+ * control, so a rule field added to `repeatDialogEntry` is audited the moment it
+ * is driven, and a control can never be silently left out. It also means the audit
+ * addresses each control through the SAME candidate paths / shape overrides / row
+ * anchors the drive used, so the two can never disagree about what was touched.
+ *
+ * Why it is needed at all: each setter's own read-back is SELF-REFERENTIAL — it
+ * re-reads the element it addressed, so it proves the keystrokes landed where they
+ * were aimed and nothing more. #589 was a wrong ADDRESS, invisible to that check.
+ * The audit is the outside view; any mismatch aborts the drive fail-closed before
+ * anything is committed.
+ *
+ * Steps that set nothing (waits, the menu press, the shape probe, the OK press)
+ * contribute nothing; a recipe that drove no control at all yields no audit step.
+ */
+function weekdayBaseOfEncoded(value) {
+    const base = Number(value.split("|", 1)[0]);
+    return Number.isFinite(base) && base > 0 ? Math.trunc(base) : 2;
+}
+/** The per-shape PATH overrides of a step, in the audit control's shape. */
+function shapedPaths(step) {
+    if (step.shaped === undefined)
+        return undefined;
+    return {
+        ...(step.shaped["next-popup"]?.pathCandidates !== undefined && {
+            "next-popup": { pathCandidates: step.shaped["next-popup"].pathCandidates },
+        }),
+        ...(step.shaped.legacy?.pathCandidates !== undefined && {
+            legacy: { pathCandidates: step.shaped.legacy.pathCandidates },
+        }),
+    };
+}
+function dialogAuditStep(steps) {
+    const controls = [];
+    for (const step of steps) {
+        const base = {
+            label: step.label,
+            ...(step.onlyShape !== undefined && { onlyShape: step.onlyShape }),
+        };
+        switch (step.primitive) {
+            case "select-popup": {
+                const shaped = shapedPaths(step);
+                controls.push({
+                    ...base,
+                    kind: "popup",
+                    ...(step.pathCandidates !== undefined && { pathCandidates: step.pathCandidates }),
+                    ...(shaped !== undefined && { shaped }),
+                    // valueCandidates carries the singular/plural pair the app pluralizes by
+                    // interval; ANY of them satisfies, exactly as the drive accepted any.
+                    expected: step.valueCandidates ?? [step.value ?? ""],
+                });
+                break;
+            }
+            case "set-group-number":
+                controls.push({
+                    ...base,
+                    kind: "group-number",
+                    numberTarget: step.numberTarget ?? "interval",
+                    expected: [step.value ?? ""],
+                });
+                break;
+            case "set-row-field":
+                controls.push({
+                    ...base,
+                    kind: "row-field",
+                    rowLabel: step.rowLabel ?? "",
+                    expected: [step.value ?? ""],
+                });
+                break;
+            case "ensure-checkbox":
+                controls.push({
+                    ...base,
+                    kind: "checkbox",
+                    ...(step.pathCandidates !== undefined && { pathCandidates: step.pathCandidates }),
+                    expected: [step.checkboxTarget === true ? "1" : "0"],
+                    expectedLabel: step.checkboxTarget === true ? "checked" : "unchecked",
+                });
+                break;
+            case "converge-weekdays": {
+                // The weekday step encodes "<base>|<Weekday>,<Weekday>…" per dialog shape
+                // (the base is the group pop-up index of the first weekday row, which the
+                // +1 fork moves). The audit reads every row pop-up from that base and
+                // compares as a SET: the converge law assigns EVERY row from the target set
+                // cycling, so a surplus row duplicates a target weekday rather than keeping
+                // a stale one, and set equality is the exact property to check.
+                const nextValue = step.shaped?.["next-popup"]?.value;
+                const legacyValue = step.shaped?.legacy?.value;
+                const encoded = nextValue ?? legacyValue;
+                if (encoded === undefined)
+                    break;
+                const titles = encoded
+                    .slice(encoded.indexOf("|") + 1)
+                    .split(",")
+                    .filter((t) => t !== "");
+                if (titles.length === 0)
+                    break;
+                controls.push({
+                    ...base,
+                    kind: "weekdays",
+                    expected: titles,
+                    expectedLabel: titles.join(" + "),
+                    shaped: {
+                        ...(nextValue !== undefined && {
+                            "next-popup": { weekdayBase: weekdayBaseOfEncoded(nextValue) },
+                        }),
+                        ...(legacyValue !== undefined && {
+                            legacy: { weekdayBase: weekdayBaseOfEncoded(legacyValue) },
+                        }),
+                    },
+                });
+                break;
+            }
+            case "select-next-occurrence":
+                controls.push({
+                    ...base,
+                    kind: "occurrence-popup",
+                    ...(step.pathCandidates !== undefined && { pathCandidates: step.pathCandidates }),
+                    expected: [step.value ?? ""],
+                });
+                break;
+            case "set-datetime":
+                controls.push({
+                    ...base,
+                    kind: "date-area",
+                    dtTarget: step.dtTarget ?? "next",
+                    dtSpec: step.value ?? "",
+                });
+                break;
+            default:
+                break;
+        }
+    }
+    if (controls.length === 0)
+        return null;
+    return {
+        primitive: "audit-dialog",
+        label: "audit the Repeat dialog against the requested rule (before committing)",
+        audit: { shells: DIALOG_SHELLS, groups: DIALOG_GROUP, controls },
+        dynamic: true,
+        addressing: "title",
+    };
+}
 export function makeRepeatingRecipe(targetUuid, frequency, interval, extras = {}) {
     return {
         op: "todo.make-repeating",
@@ -685,9 +1057,17 @@ export function rescheduleRepeatRecipe(targetUuid, frequency, interval, extras =
 // repeat bar, the popover, and the popover items are best-guess structural
 // paths derived from the UIC2 AX inventory; the certification pass confirms or
 // corrects them exactly as the to-do recipes were corrected in UIC1.
-/** The header cell of the project view (row 1 of the content table). */
+/** The header cell of the project view (row 1 of the content table).
+ *  positional-ok: the project view's header IS its first content-table row by
+ *  construction (UIC2/UIC3) — the row the app renders above the item list — and
+ *  this path only ever reaches a CLICK target, never a value. */
 const PROJECT_HEADER_CELL = `UI element 1 of row 1 of table 1 of scroll area 1 of ${MAIN_WINDOW}`;
-/** The always-visible repeat bar of a repeating project (UIC2/UIC3: text area 2). */
+/** The always-visible repeat bar of a repeating project (UIC2/UIC3: text area 2).
+ *  positional-ok: the bar carries no title or description to address it by (UIC2),
+ *  so its index in the header cell is the only handle the app offers. It is not a
+ *  value-bearing field: the step that uses it is a click whose `assertPath` REQUIRES
+ *  the repeat popover to appear afterwards, so a click that lands on the wrong text
+ *  area fails closed (Escape + abort) instead of cascading into blind presses. */
 const PROJECT_REPEAT_BAR = `text area 2 of ${PROJECT_HEADER_CELL}`;
 /**
  * The popover opened by clicking the repeat bar. Confirmed by UIC3 discovery: it
@@ -698,6 +1078,9 @@ const PROJECT_REPEAT_BAR = `text area 2 of ${PROJECT_HEADER_CELL}`;
  * utility window; its items live in the window's scroll area.
  */
 const PROJECT_REPEAT_POPOVER = `(first window whose subrole is "AXUnknown" and size is not {40, 40})`;
+// positional-ok: a CONTAINER handle only — these custom AXUnknown popovers hold
+// exactly one scroll area (MEASURED on the sibling Move… picker, HXPC1 §B2:
+// `scroll areas=1`), and every item inside is addressed by exact AXDescription.
 const PROJECT_REPEAT_POPOVER_ITEMS = `scroll area 1 of ${PROJECT_REPEAT_POPOVER}`;
 /** A project view + foreground preamble — the mouse segment needs Things frontmost. */
 function projectPreamble(targetUuid) {
@@ -775,6 +1158,8 @@ export function projectRescheduleRepeatRecipe(targetUuid, frequency, interval, e
             ...projectPreamble(targetUuid),
             openProjectRepeatPopover(),
             popoverItemClick("repeat menu ▸ Change…", "Change…", {
+                // positional-ok: a post-click EXISTENCE assert on the one attached sheet a
+                // window can present; nothing is read or written through this path.
                 path: `sheet 1 of ${MAIN_WINDOW}`,
                 label: "the Repeat dialog",
             }),
@@ -794,27 +1179,74 @@ export function projectRescheduleRepeatRecipe(targetUuid, frequency, interval, e
 // repeat popover. The popover (Archive / Move… / Convert to Project… / Delete) is
 // the same custom AXUnknown-window shape as the repeat popover.
 //
-// PROVISIONAL element paths (pending HXPC1 certification): the `…` button's
-// container path, the popover-item enumeration, and the picker's search field are
-// best-guess structural paths from the HEADXPROJ AX inventory; the certification
-// sitting confirms/corrects them exactly as UIC1 corrected the repeat recipes.
-/** The heading `…` "More. <title>" button — provisionally in the content table. */
-function headingMoreButton(headingTitle) {
-    return `(first UI element of ${PROJECT_CONTENT_TABLE} whose description is "More. ${headingTitle}")`;
+// CERTIFIED by HXPC1 (2026-08-25, Things 3.23 / golden-v4 —
+// docs/lab/hxpc1-picker-assert.md), which corrected three of the four provisional
+// paths the way UIC1 corrected the repeat recipes:
+//   * the `…` button is three levels below the content table, so no `whose`
+//     clause can reach it (§B0) — the click resolves it by walking rows/cells;
+//   * the picker is a DETACHED `MovePopUpDialog-` window, not a sheet of the main
+//     window (§B2), and its filter field is not addressable as a child of it;
+//   * the commit is a CLICK on the destination row, never a Return — the picker
+//     publishes no highlight to read back, and its `New Project "<typed>"` row
+//     turns an absent destination into a newly created project (§B4).
+// The popover-item enumeration (`whose description is "Move…"`) was the one
+// provisional path that measured correct: those items are direct children of the
+// popover's scroll area.
+/**
+ * The heading `…` "More. <title>" button. It carries the heading's title in its
+ * `AXDescription`, but it sits at `UI element N of cell 1 of row M` of the
+ * content table — three levels down — and a `whose` clause searches only DIRECT
+ * children, so the button is NOT addressable as a path. The click step names the
+ * table here and the description separately (`rowCellDescription`), and the
+ * driver walks rows → cells → children for the exact match (HXPC1 §B0; the
+ * one-level spelling this replaces matched nothing on 3.23, which is why every
+ * ellipsis drive died at its own frame resolution).
+ */
+function headingMoreDescription(headingTitle) {
+    return `More. ${headingTitle}`;
 }
 /** The ellipsis popover — a custom AXUnknown window (same shape as the repeat popover). */
 const HEADING_ELLIPSIS_POPOVER = `(first window whose subrole is "AXUnknown" and size is not {40, 40})`;
+// positional-ok: container handle only — one scroll area per popover (HXPC1 §B2),
+// items addressed by exact AXDescription.
 const HEADING_POPOVER_ITEMS = `scroll area 1 of ${HEADING_ELLIPSIS_POPOVER}`;
-/** The Move… project picker (a searchable list; provisionally a sheet of the main window). */
-const HEADING_MOVE_PICKER = `sheet 1 of ${MAIN_WINDOW}`;
-const HEADING_MOVE_PICKER_FIELD = `text field 1 of ${HEADING_MOVE_PICKER}`;
+/**
+ * The Move… project picker. NOT a sheet of the main window (the shape this
+ * recipe first assumed) — a DETACHED top-level window of the same custom
+ * `AXUnknown` class as the ellipsis popover, distinguished by an `AXIdentifier`
+ * beginning `MovePopUpDialog-` (HXPC1 §B2). The popover that opened it is gone
+ * by the time it appears, so the generic detached-window selector resolves it
+ * unambiguously; the row-commit script re-checks the identifier before clicking
+ * anything, so a different detached window can never be committed into.
+ */
+const HEADING_MOVE_PICKER = `(first window whose subrole is "AXUnknown" and size is not {40, 40})`;
+/**
+ * What proves the detached window that appeared IS the picker and not the
+ * ellipsis popover it replaced: the picker carries a direct child described
+ * `Move` (its header), the popover carries only its item list. Without this the
+ * post-click assert would be satisfied by the popover that was already open —
+ * i.e. by the click having done nothing (HXPC1 §B2).
+ */
+const HEADING_MOVE_PICKER_MARKER = `(first UI element of ${HEADING_MOVE_PICKER} whose description is "Move")`;
 /**
  * Move a HEADING to a different project via the ellipsis `Move…` menu (HEADXPROJ).
  * `sourceProjectUuid` is revealed to render the heading row; `headingTitle` is the
- * `"More. <title>"` click target; `destProjectTitle` is typed into the picker,
- * then Return selects the filtered match. DB effect (HEADXPROJ): the heading row's
- * `project` FK becomes the destination; its children follow via their intact
+ * `"More. <title>"` click target; `destProjectTitle` narrows the picker's list and
+ * then names the row that is CLICKED to commit. DB effect (HEADXPROJ): the heading
+ * row's `project` FK becomes the destination; its children follow via their intact
  * heading FK (a single-row change — no child rewrite, no index churn).
+ *
+ * The commit used to be a Return pressed BLIND on whatever the filter had
+ * highlighted, which is how a move could CREATE a project instead of performing
+ * one: the picker offers a trailing `New Project "<typed text>"` row, and it omits
+ * completed and canceled projects entirely — so a destination our pre-state had
+ * resolved from the database could be absent from the picker, leaving that row as
+ * the only offer. Measured on Things 3.23: the heading landed in a brand-new
+ * second project of the same name (HXPC1 §B4). The picker publishes no selection
+ * or highlight attribute on any row, so there is nothing to read back from a
+ * keyboard commit; the recipe therefore addresses the destination row by its exact
+ * title and clicks it, and fails closed — naming every row the picker offered —
+ * when that row is absent, duplicated, or scrolled out of view.
  */
 export function moveHeadingToProjectRecipe(sourceProjectUuid, headingTitle, destProjectTitle) {
     return {
@@ -836,7 +1268,8 @@ export function moveHeadingToProjectRecipe(sourceProjectUuid, headingTitle, dest
             {
                 primitive: "click-element",
                 label: `open the heading's ellipsis menu ("More. ${headingTitle}")`,
-                path: headingMoreButton(headingTitle),
+                path: PROJECT_CONTENT_TABLE,
+                rowCellDescription: headingMoreDescription(headingTitle),
                 assertPath: HEADING_ELLIPSIS_POPOVER,
                 assertLabel: "the heading ellipsis menu",
                 assertTimeoutMs: 5000,
@@ -847,24 +1280,28 @@ export function moveHeadingToProjectRecipe(sourceProjectUuid, headingTitle, dest
                 primitive: "click-element",
                 label: "ellipsis menu ▸ Move…",
                 path: `(first UI element of ${HEADING_POPOVER_ITEMS} whose description is "Move…")`,
-                assertPath: HEADING_MOVE_PICKER,
+                assertPath: HEADING_MOVE_PICKER_MARKER,
                 assertLabel: "the Move… project picker",
                 assertTimeoutMs: 5000,
                 dynamic: true,
                 addressing: "title",
             },
             {
-                primitive: "set-value",
-                label: `type the destination "${destProjectTitle}" into the Move… picker`,
-                path: HEADING_MOVE_PICKER_FIELD,
+                // The picker focuses its own filter field as it opens, and that field is
+                // not addressable as a child of the picker window — so the destination is
+                // typed at the focus. Nothing is committed on the strength of the
+                // keystroke: the next step resolves the destination row by name.
+                primitive: "type-text",
+                label: `narrow the Move… picker to "${destProjectTitle}"`,
                 value: destProjectTitle,
                 dynamic: true,
                 addressing: "title",
             },
             {
-                primitive: "key",
-                label: "press Return to select the filtered destination project",
-                keys: "return",
+                primitive: "click-picker-row",
+                label: `commit the Move… picker on the "${destProjectTitle}" row`,
+                path: HEADING_MOVE_PICKER,
+                value: destProjectTitle,
                 dynamic: true,
                 addressing: "title",
             },
@@ -900,7 +1337,8 @@ export function dissolveHeadingRecipe(projectReveal, headingTitle) {
             {
                 primitive: "click-element",
                 label: `open the heading's ellipsis menu ("More. ${headingTitle}")`,
-                path: headingMoreButton(headingTitle),
+                path: PROJECT_CONTENT_TABLE,
+                rowCellDescription: headingMoreDescription(headingTitle),
                 assertPath: HEADING_ELLIPSIS_POPOVER,
                 assertLabel: "the heading ellipsis menu",
                 assertTimeoutMs: 5000,