things-api 0.18.0 → 0.19.1

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

@@ -1,7 +1,9 @@
 import { UI_DRIVE_OPS } from "../operations.js";
 /** The manifest profile — records the tier + Things build the suite certified. */
-export const UI_CERTIFICATION_PROFILE = "UIC1 + UIC3 + AXDRAG2 + UIC5 + UIC6 + UIC7 + UIC7b + HEADCERT1 + HXPC1 + DISS1 in-VM (Things 3.22.11) + " +
-    "UIC8 promote-via-clone compounds in-VM (golden-v2 / Things 3.22.12) — on-device pending";
+export const UI_CERTIFICATION_PROFILE = "UIC1 + UIC3 + AXDRAG2 + UIC5 + UIC6 + UIC7 + UIC7b + HEADCERT1 + HEADXPROJ + DISS1 in-VM (Things 3.22.11) + " +
+    "UIC8 promote-via-clone compounds in-VM (golden-v2 / Things 3.22.12) + RDLG2 recipe re-point + " +
+    "HXPC1 heading-ellipsis/Move-picker paths in-VM (golden-v4 / Things 3.23) + " +
+    "CHORDMH1 heading-order arrow chords in-VM (golden-v4 / Things 3.23) — on-device pending";
 const CERTIFICATION = {
     "todo.make-repeating": {
         status: "lab-certified",
@@ -48,16 +50,59 @@ const CERTIFICATION = {
         evidence: ["UI2-d", "UIC1-a", "HEADCERT1"],
     },
     "project.move-heading-to-project": {
-        // HXPC1 (2026-07-28, bjhx-lab, Things 3.22.11): the ellipsis Move… recipe ran
-        // end-to-end in the clone — HID-click the "More. <title>" button → Move… →
-        // type the destination → Return — and the exact HEADXPROJ delta was observed:
-        // heading `HXH` project-FK rewritten HX-PA → HX-PB, both children followed via
-        // their intact heading FK (project NULL, heading=HXH), single-row change, no
-        // index churn. The shipped recipe's popover-item AX PATHS (description-based
-        // click-element) are provisional pending an on-device sitting — HXPC1 drove the
-        // equivalent frame-center synthesis; the DB oracle + recipe flow are certified.
+        // HEADXPROJ (2026-07-27, bjhx-lab, Things 3.22.11) established the flow and the
+        // DB oracle with a hand-written driver: HID-click the "More. <title>" button →
+        // Move… → type the destination → Return, and heading `HXH`'s project FK
+        // rewritten HX-PA → HX-PB with both children following via their intact heading
+        // FK (project NULL, heading=HXH) — a single-row change, no index churn.
+        //
+        // HXPC1 (2026-08-25, hxpc1-lab, Things 3.23 / golden-v4) certified the SHIPPED
+        // recipe for the first time and corrected three of the four provisional paths:
+        // the "More. <title>" button is three levels below the content table (so the
+        // shipped one-level `whose` clause matched nothing and the drive never got past
+        // its first click), the picker is a detached `MovePopUpDialog-` window rather
+        // than a sheet of the main window, and the commit is a CLICK on the row whose
+        // title matches exactly — the blind Return could take the picker's
+        // `New Project "<typed>"` row whenever the destination was absent from it,
+        // which a completed or canceled destination is. 7/7 through the production CLI
+        // (clean match, prefix collision, completed-destination refusal with zero
+        // mutation). docs/lab/hxpc1-picker-assert.md.
         status: "lab-certified",
-        evidence: ["HXPC1"],
+        evidence: ["HEADXPROJ", "HXPC1"],
+    },
+    "project.move-heading": {
+        // HEADORD1 (2026-08-25, headord1-lab, Things 3.23 / golden-v4) discovered and
+        // characterised the affordance: ⌘↑/⌘↓ = ±1 slot, ⌘⌥↑/⌘⌥↓ = to top/bottom on a
+        // selected heading row; a single-row `index` rewrite with no sibling renumber
+        // and children untouched behind their FK; a chord with nowhere to go declined
+        // with zero delta and one alert beep; System Events modifiers frontmost-only,
+        // `CGEventPostToPid` background-capable.
+        //
+        // CHORDMH1 (2026-08-25, chordmh1-lab, Things 3.23 / golden-v4) certified the
+        // SHIPPED op. Its delivery gate re-measured the whole gesture with Things
+        // never activated at all — `open -g` reveal, pure-AX row select, pid-posted
+        // chord — and Finder frontmost at every stage, so the op ships BACKGROUND
+        // delivery with no `activate` step (the least-disruptive tier any ordering op
+        // has reached). The certification arms drove the production CLI over
+        // 3-heading fixtures: ±1 up, ±1 down, to-top, to-bottom, a multi-hop, the
+        // already-in-position no-op, the dry run, and the ungated call — children
+        // byte-identical on every arm, sibling indexes byte-identical, zero beeps on
+        // the normal paths. docs/lab/chordmh1-move-heading-build.md.
+        //
+        // CHORDMH2 (2026-08-25, chordmh2-lab, Things 3.23 / golden-v4) lifted CHORDMH1's
+        // one deliberate capability cut — the whole-project refusal on any archived
+        // heading — after CHORD2 cell 7a′ measured that an archived heading renders no
+        // content row, takes no ordinal in the walk, and is skipped by a live heading's
+        // ±1. The fence stood in for an ordinal mismatch, so the three reads that feed
+        // the plan, the driver and the bare-placement anchor now return the RENDERED
+        // (`status = 0`) order. Certified through the production CLI: one chord carried
+        // a heading past an archived row's slot, that heading was the only row
+        // rewritten, the archived row was byte-untouched on status/index/stopDate/umd,
+        // children intact, zero beeps; an archived heading named as a movee or an
+        // anchor still refuses with zero mutation.
+        // docs/lab/chordmh2-archived-fence-lift.md.
+        status: "lab-certified",
+        evidence: ["HEADORD1", "CHORDMH1", "CHORDMH2"],
     },
     "project.dissolve-heading": {
         // DISS1 (2026-07-28, bjhx-lab, Things 3.22.11): the ellipsis Delete recipe ran
@@ -66,8 +111,13 @@ const CERTIFICATION = {
         // TMTask), its 3 children re-homed as DIRECT project children (heading→NULL,
         // project→parent, index preserved: c1<c2<c3, trashed=0). NO confirm sheet.
         // Popover items are AX-description-enumerable (the recipe resolves Delete by
-        // description, scoped to the popover). The shipped recipe's popover AX paths are
-        // provisional pending an on-device sitting; the DB oracle + flow are certified.
+        // description, scoped to the popover) — the one provisional path HXPC1 measured
+        // CORRECT. Its sibling was not: the "More. <title>" button this drive opens the
+        // popover with was addressed one level too shallow, so it resolved nothing and
+        // the drive died at its first click on every host. HXPC1 (2026-08-25, Things
+        // 3.23) fixed the walk and certified it through the move-heading sibling, but
+        // this op was NOT driven end to end there — its next sitting should carry a cell
+        // (docs/lab/hxpc1-picker-assert.md §B0/§D). The DB oracle + flow are certified.
         status: "lab-certified",
         evidence: ["DISS1"],
     },

package/dist/write/vectors/ui-certification.js.map

@@ -1 +1 @@
-{"version":3,"file":"ui-certification.js","sourceRoot":"","sources":["../../../src/write/vectors/ui-certification.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ui-certification.js","sourceRoot":"","sources":["../../../src/write/vectors/ui-certification.ts"],"names":[],"mappings":"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"}

package/dist/write/vectors/ui-chord.d.ts

@@ -0,0 +1,144 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { UiCommand, UiRunner } from "./ui.ts";
+/** The move a `chord-reorder` step performs, compiled from the pre-state. */
+export interface HeadingChordSpec {
+    /** The project whose headings are being reordered. */
+    projectUuid: string;
+    /**
+     * Every LIVE (`status = 0`) heading of the project, in the order they must end
+     * up in — the full end state, not just the moved block. The driver places them
+     * left to right, so this doubles as the verification target. Archived headings
+     * are absent by construction: they render no row, so they are neither
+     * addressable nor displaced (CHORD2 cell 7a′).
+     */
+    targetOrder: string[];
+    /**
+     * The headings the caller named. Only these may ever be chorded: if the
+     * driver's placement walk would have to move a heading the caller did not
+     * name, it refuses rather than touch a bystander.
+     */
+    movees: string[];
+    /** The project view's content table (the recipe supplies the one path). */
+    tablePath: string;
+}
+/** The database read the driver asserts against between chords. */
+export interface HeadingOrderState {
+    /**
+     * The project's LIVE (`status = 0`) headings in `index` order, with their raw
+     * index — the rows the project view actually renders, and therefore the rows
+     * the positional `select-heading-row` walk enumerates. An ARCHIVED heading is
+     * absent: it renders no row, takes no ordinal, and a live heading's ±1 chord
+     * skips its slot in one dispatch (CHORD2 cell 7a′). Filtering here is what
+     * keeps the driver's ordinals in step with the walk's.
+     */
+    headings: {
+        uuid: string;
+        index: number;
+    }[];
+    /**
+     * Digest over every non-trashed child of those headings: `uuid:headingFK:index`.
+     * The chord law says children are untouched behind their FK — this is what
+     * proves it, and what catches the one measured hazard in the family (a row
+     * driven across a heading boundary has its heading FK rewritten, HEADORD1 §2
+     * cells 1h4/1i2; it cannot happen to a heading, and this asserts that).
+     */
+    childDigest: string;
+    /** How many child rows the digest covers (reported in the failure text). */
+    childCount: number;
+}
+/** The database seam the chord driver reads its ground truth through. */
+export type HeadingOrderReader = (projectUuid: string) => HeadingOrderState;
+/**
+ * The client-side default: heading order + child containment, from the open DB.
+ *
+ * The heading read is filtered to `status = 0` so it returns the RENDERED order
+ * (CHORD2 cell 7a′). The child digest is deliberately NOT filtered — it covers
+ * every non-trashed child of every heading of the project, archived headings
+ * included, because no heading chord may disturb any of them.
+ */
+export declare function createHeadingOrderReader(db: DatabaseSync): HeadingOrderReader;
+/**
+ * The four chords, as `(key code, CGEventFlags)` pairs. `126`/`125` are the
+ * arrow keys; `0x100000` is `kCGEventFlagMaskCommand` and `0x80000`
+ * `kCGEventFlagMaskAlternate`. Named rather than inlined so the recipe trace and
+ * the failure text can say which chord was posted.
+ */
+export type ChordId = "up-one" | "down-one" | "to-top" | "to-bottom";
+export declare function chordGlyph(id: ChordId): string;
+/**
+ * Post ONE modifier-bearing key event pair straight at the Things process
+ * (`CGEventPostToPid`), through the same JXA ObjC bridge every other synthetic
+ * input in this codebase rides.
+ *
+ * Why not System Events. The shipped `key` primitive emits `key code N` with no
+ * modifier support at all, and the System-Events spelling that DOES carry
+ * modifiers only lands while Things is FRONTMOST (HEADORD1 cell 1h2b: with
+ * Finder frontmost it produced no delta). `CGEventPostToPid` addresses the
+ * process rather than the focused surface, so the whole gesture — reveal,
+ * select, chord — runs with Things in the background and the user's focus
+ * untouched. Measured on Things 3.23 / golden-v4 (HEADORD1 1h2a; re-measured end
+ * to end, with Things never activated at all, by CHORDMH1's delivery gate).
+ *
+ * Note this is the KEYBOARD tap only. NATIVE1-e measured `CGEventPostToPid` as
+ * inert for Things' MOUSE hit-testing, which is why click synthesis still uses
+ * the HID tap and stays foreground-bound; keyboard events to the pid are a
+ * different path and do land.
+ */
+export declare function jxaChordScript(id: ChordId): string;
+export declare function chordCommand(id: ChordId): UiCommand;
+/** Select the Nth heading row of the revealed project view (the shipped primitive). */
+export declare function chordSelectCommand(tablePath: string, ordinal: number, script: string): UiCommand;
+export interface ChordDriveResult {
+    ok: boolean;
+    /** Human-readable outcome (chords posted) or the refusal reason. */
+    detail: string;
+    /** How many chords were posted before the outcome (partial-state honesty). */
+    chords: number;
+}
+/** One scheduled step: which heading to chord, with what, and where it must land. */
+export interface ChordStep {
+    /** The heading to select and move — ALWAYS one the caller named. */
+    uuid: string;
+    chord: ChordId;
+    /** The position the heading must occupy afterwards (the progress assertion). */
+    landsAt: number;
+}
+/**
+ * The next chord that advances `order` towards `target`, or null when they
+ * already agree. `movees` is the only set of rows a chord may ever move.
+ *
+ * THE SCHEDULE, and why it is this one. The obvious walk — "put target[i] into
+ * slot i, left to right" — is WRONG here, because target[i] is very often a row
+ * the caller never named: asking to move heading A down one slot produces a
+ * target whose first element is the BYSTANDER B. Moving B is not an option (it
+ * would break the untouched-siblings law the whole vector rests on), and the
+ * equally obvious repair — "push whichever movee sits at slot i down" — thrashes
+ * forever when two movees sit side by side, each pushing the other back.
+ *
+ * So the rule fixes the first mismatched slot `i` from the row's own side:
+ *
+ *  - target[i] IS a movee → it is necessarily BELOW slot i (everything above
+ *    already matches), so step it UP; from slot 0 the one-dispatch ⌘⌥↑ takes it
+ *    there directly.
+ *  - target[i] is a bystander `R` → every row between slot i and R's current
+ *    position is provably a movee (the non-movees keep their relative order, so
+ *    R is the first non-movee at or below i), and pushing the ONE movee directly
+ *    above R down past it moves R up by exactly one slot.
+ *
+ * Both branches strictly reduce a distance that cannot go below zero, so the
+ * schedule terminates, and every chord it emits moves a named heading by one
+ * slot. Two endpoint shortcuts run first, because they are the common single
+ * heading requests and each costs one dispatch instead of a walk: a movee whose
+ * target is the very top or the very bottom is sent there with ⌘⌥↑ / ⌘⌥↓.
+ */
+export declare function planChordStep(order: readonly string[], target: readonly string[], movees: ReadonlySet<string>): ChordStep | {
+    error: string;
+} | null;
+/**
+ * Drive a project's headings into `spec.targetOrder`, one verified chord at a
+ * time (see {@link planChordStep} for the schedule). Nothing here trusts the
+ * plan it made a moment ago: every step is re-derived from a fresh database
+ * read, and the step is only counted once the database says it landed where it
+ * was aimed with nothing else touched.
+ */
+export declare function driveHeadingChordReorder(spec: HeadingChordSpec, run: UiRunner, reader: HeadingOrderReader | undefined, selectScript: (ordinal: number) => string, sleep?: (ms: number) => Promise<void>): Promise<ChordDriveResult>;