things-api 0.10.0 → 0.12.0

package/dist/write/pre-state.d.ts

@@ -3,8 +3,9 @@
  * world BEFORE a mutation. One read pass, snapshot semantics per statement.
  */
 import type { DatabaseSync } from "node:sqlite";
-import type { AnyTask, Project, TaskStatus, TaskType, Todo } from "../model/entities.ts";
-import type { ContainerRef, ReorderParams } from "./operations.ts";
+import { type IsoDate } from "../model/dates.ts";
+import type { AnyTask, TaskStatus, TaskType, Todo } from "../model/entities.ts";
+import type { ContainerRef, HeadingPlacement, ReorderParams } from "./operations.ts";
 export interface ResolvedContainer {
     uuid: string;
     title: string;
@@ -13,6 +14,14 @@ export interface ContainerResolution {
     resolved: ResolvedContainer | null;
     /** 0 = not found, 1 = ok, >1 = ambiguous title. */
     matches: number;
+    /**
+     * An honest not-found tail (`resolved === null && matches === 0`) when the NAME
+     * matched only non-open destination rows the resolver deliberately excludes —
+     * e.g. a completed/canceled project (which would strand an open child, PLOG1).
+     * Surfaced by H-UNKNOWN-DESTINATION so the caller learns the row exists and how
+     * to reach it (by uuid). Absent when the miss is a genuine no-match.
+     */
+    deadHint?: string;
 }
 export interface ReorderMember {
     uuid: string;
@@ -47,9 +56,25 @@ export interface ReorderPre {
     /** Full wire list: requested order first, remaining members after. */
     wireList: string[];
 }
+/** area.delete: live member census of the area (non-trashed direct rows). */
+export interface AreaMemberCounts {
+    /** Projects whose area FK is this area (trashed = 0). */
+    projects: number;
+    /** Direct to-dos in the area (trashed = 0, any status). */
+    todos: number;
+}
 export interface PreState {
     /** Primary target for uuid-addressed operations. */
     target: AnyTask | null;
+    /**
+     * The response clock's local calendar date (guest/host clock), captured at
+     * pre-read. Feeds §9n reminder-liveness: the `when=` reminder auto-preserve
+     * (commands.ts `effectiveReminder`) gates a STALE reminder byte out against
+     * the target's CURRENT startDate under this date, rather than resurrecting a
+     * presentation-dead reminder. Defaults to the host today (emptyPreState); the
+     * date-bearing update preReads stamp the injected clock.
+     */
+    todayIso: IsoDate;
     destProject: ContainerResolution | null;
     /** Status of the resolved destination project (reopen hazard, T19). */
     destProjectStatus: TaskStatus | null;
@@ -70,6 +95,13 @@ export interface PreState {
     entityTarget: ContainerResolution | null;
     /** tag.delete: descendant tags that a delete would CASCADE onto (P16). */
     childTags: string[];
+    /**
+     * area.delete: live (non-trashed) member counts, direct to-dos and projects
+     * carrying the area's FK. A non-empty area's delete trashes its to-dos and
+     * takes its projects with it (A25/A25B), so the delete refuses unless the
+     * caller allows it. Null for non-area ops (and when the area did not resolve).
+     */
+    areaMembers: AreaMemberCounts | null;
     /** project.complete / project.cancel: children by pre-status. */
     openChildren: Todo[];
     canceledChildren: Todo[];
@@ -90,6 +122,31 @@ export interface PreState {
     areaOrder: string[] | null;
     /** project.make-repeating: the row-selection taxonomy (UIC4-f). */
     projectRepeat: ProjectRepeatTaxonomy | null;
+    /**
+     * project.make-repeating: the uuids of the source subtree rows (non-trashed
+     * to-dos + headings) captured pre-write — the result's `childrenReplaced`
+     * counts how many of these are dead post-op. Null for non-project ops.
+     */
+    repeatSubtreeUuids: string[] | null;
+    /** project.promote-heading: the project-reveal + heading-row ordinal (HEADCERT1). */
+    headingConvert: HeadingConvertTaxonomy | null;
+    /** project.move-heading: current heading order + computed target order. */
+    headingMove: HeadingMovePre | null;
+    /** project.move-heading-to-project: source reveal + heading + destination (HEADXPROJ). */
+    headingMoveToProject: HeadingMoveToProjectTaxonomy | null;
+    /** project.dissolve-heading: parent reveal + heading title + children (DISS1). */
+    headingDissolve: HeadingDissolveTaxonomy | null;
+}
+/** project.move-heading pre-computation (spec §2/§4). */
+export interface HeadingMovePre {
+    /** Destination project resolution (the container the headings live in). */
+    project: ContainerResolution;
+    /** The project's non-trashed heading uuids in current display (index) order. */
+    current: string[];
+    /** Full target order after moving the block — feeds the native wire + delta. */
+    targetOrder: string[];
+    /** Reasons the move is illegal (empty = ok). */
+    problems: string[];
 }
 /**
  * Row-selection taxonomy for `project.make-repeating` (UIC4-f). A project is
@@ -125,6 +182,112 @@ export type ProjectRepeatTaxonomy = {
     detail: string;
 };
 export declare function emptyPreState(): PreState;
+/**
+ * Read a project's current heading order and compute the FULL target order
+ * after moving `headings` (an ordered block) to the requested placement. The
+ * block lands contiguously in selection order; every other heading keeps its
+ * relative order. Children follow their heading on the wire (scf P1). Illegal
+ * requests (unknown/duplicated movee, an anchor that is a movee or absent)
+ * collect problems and leave the order unchanged.
+ */
+export declare function computeHeadingMovePre(db: DatabaseSync, project: ContainerResolution, headings: string[], placement: HeadingPlacement): HeadingMovePre;
+/**
+ * The uuids of a project's source subtree rows (non-trashed to-dos AND
+ * headings, direct or heading-nested). `childrenReplaced` counts how many of
+ * these are dead post-op — the whole subtree in the delete-remint fate, just
+ * the flattened nested-template row in the nested-repeater preserve fate.
+ */
+export declare function projectSubtreeUuids(db: DatabaseSync, projectUuid: string): string[];
+/**
+ * Taxonomy for `project.promote-heading`'s pure-AX drive (HEADCERT1). A
+ * heading is not selectable via `things:///show` (the reveal URL selects to-dos
+ * only — the UIC1 blocker), but revealing the heading's PARENT PROJECT shows its
+ * content table, in which the heading renders as a selectable ROW. The row
+ * exposes no stable AX title handle (its title lives only in a hover-dependent
+ * "More" affordance), so identity is POSITIONAL: `ordinal` is the heading's
+ * 0-based position among the project's non-trashed headings in display (`index`)
+ * order, and the select-heading-row primitive walks the content table selecting
+ * the Nth row that is selectable AND has an empty `selected to dos` readback (a
+ * heading, not a to-do). Two same-titled headings are therefore unambiguous.
+ */
+export type HeadingConvertTaxonomy = {
+    kind: "ok";
+    projectReveal: string;
+    ordinal: number;
+} | {
+    kind: "refuse";
+    refusal: "not-a-heading" | "no-project" | "not-found";
+    detail: string;
+};
+export declare function classifyHeadingConvert(db: DatabaseSync, target: AnyTask | null): HeadingConvertTaxonomy;
+/**
+ * Taxonomy for `project.move-heading-to-project`'s ellipsis-`Move…` drive
+ * (HEADXPROJ). Unlike the promote drive (positional), the heading row is
+ * TITLE-addressable: its `…` button is an AXUnknown whose AXDescription is
+ * `"More. <title>"`, so the recipe HID-clicks that button, then `Move…`, then
+ * TYPES the destination project title into the search picker and presses Return.
+ * Two collision surfaces therefore fail closed: (a) the SOURCE heading title is
+ * shared by another heading in the same project (the `"More. <title>"` node
+ * matches both — indistinguishable), and (b) the DESTINATION title is shared by
+ * another project (the picker is search-by-title — Return would pick the wrong
+ * row). A titleless heading is refused (its `"More. "` description matches every
+ * titleless heading). Verify oracle: the heading row's `project` FK becomes the
+ * destination (children follow via their intact heading FK — a single-row change).
+ */
+export interface HeadingMoveToProjectPre {
+    /** Source project revealed via things:///show?id= to render the heading row. */
+    sourceProjectUuid: string;
+    /** The heading being moved (the verify oracle's target row). */
+    headingUuid: string;
+    /** The heading title — the `"More. <title>"` click target. */
+    headingTitle: string;
+    /** The destination project — the heading's `project` FK becomes this post-op. */
+    destProjectUuid: string;
+    /** The destination title typed into the Move… search picker. */
+    destProjectTitle: string;
+}
+export type HeadingMoveToProjectRefusal = "no-source" | "heading-not-found" | "heading-ambiguous" | "empty-heading-title" | "no-dest" | "dest-ambiguous" | "same-project";
+export type HeadingMoveToProjectTaxonomy = {
+    kind: "ok";
+    pre: HeadingMoveToProjectPre;
+} | {
+    kind: "refuse";
+    refusal: HeadingMoveToProjectRefusal;
+    detail: string;
+    candidates?: string[];
+};
+export declare function classifyHeadingMoveToProject(db: DatabaseSync, project: ContainerRef, headingSel: string, toProject: ContainerRef): HeadingMoveToProjectTaxonomy;
+/**
+ * Taxonomy for `project.dissolve-heading`'s ellipsis-`Delete` drive (DISS1). Same
+ * title-addressed `"More. <title>"` reveal as the cross-project move, driving the
+ * popover's Delete instead of Move…. DISS1 (2026-07-28, Things 3.22.11): Delete
+ * HARD-DELETES the heading row (removed from TMTask) while its children become
+ * DIRECT project children (heading→NULL, project→the parent, index preserved,
+ * NOT trashed) — no confirm sheet. Contrast the Shortcuts delete cascade (P12),
+ * which TRASHES the children. Fails closed on a title shared by another heading in
+ * the project (the drive addresses by title) and on a titleless heading.
+ */
+export interface HeadingDissolvePre {
+    /** Parent project revealed via things:///show?id= to render the heading row. */
+    projectReveal: string;
+    /** The heading being dissolved (the verify oracle's gone-target). */
+    headingUuid: string;
+    /** The heading title — the `"More. <title>"` click target. */
+    headingTitle: string;
+    /** Open children that become direct project children (for the result note). */
+    childUuids: string[];
+}
+export type HeadingDissolveRefusal = "not-a-heading" | "no-project" | "title-ambiguous" | "empty-title";
+export type HeadingDissolveTaxonomy = {
+    kind: "ok";
+    pre: HeadingDissolvePre;
+} | {
+    kind: "refuse";
+    refusal: HeadingDissolveRefusal;
+    detail: string;
+    candidates?: string[];
+};
+export declare function classifyHeadingDissolve(db: DatabaseSync, target: AnyTask | null): HeadingDissolveTaxonomy;
 /**
  * Classify a project for `project.make-repeating`'s pure-AX row-selection
  * recipe (UIC4-f), or refuse. Reads DB truth (area / start / template / status)
@@ -133,8 +296,19 @@ export declare function emptyPreState(): PreState;
  */
 export declare function classifyProjectRepeat(db: DatabaseSync, target: AnyTask | null): ProjectRepeatTaxonomy;
 export declare function resolveArea(db: DatabaseSync, ref: ContainerRef): ContainerResolution;
+/**
+ * Resolve a project DESTINATION (`--to-project` / `--project` on add/move). NAME
+ * resolution is OPEN-only (`status = 0`) — a completed/canceled project is not a
+ * valid live destination by name: placing an open child there strands it (PLOG1,
+ * "a completed-in-place project strands children identically, one sweep later").
+ * A UUID / partial-uuid still reaches a completed project (explicit intent —
+ * `nameExtraWhere` narrows the NAME tiers only). When a name matches ONLY non-open
+ * projects, the resolution carries a `deadHint` so the destination not-found says
+ * the row exists and how to reach it (by uuid), instead of a bare "project not
+ * found".
+ */
 export declare function resolveProject(db: DatabaseSync, ref: ContainerRef): ContainerResolution;
-export declare function resolveHeading(db: DatabaseSync, projectUuid: string, headingTitle: string): ContainerResolution;
+export declare function resolveHeading(db: DatabaseSync, projectUuid: string, headingSel: string): ContainerResolution;
 export declare function projectStatus(db: DatabaseSync, uuid: string): TaskStatus | null;
 export declare function resolveTag(db: DatabaseSync, ref: string): ContainerResolution;
 export declare function loadTarget(db: DatabaseSync, uuid: string): AnyTask | null;
@@ -157,6 +331,14 @@ export declare function projectChildren(db: DatabaseSync, projectUuid: string):
  * them. UNION (not UNION ALL): a parent cycle must terminate, not hang.
  */
 export declare function childTagTitles(db: DatabaseSync, tagUuid: string): string[];
+/**
+ * Live member census for `area.delete` (A25/A25B). Counts the area's non-trashed
+ * DIRECT members: to-dos carrying the area FK (any status — a logged to-do is
+ * still trashed by the delete) and projects carrying the area FK. Deleting a
+ * non-empty area trashes the to-dos and takes the projects with it, so the guard
+ * uses these counts to refuse fail-closed unless the caller allows it.
+ */
+export declare function areaMemberCounts(db: DatabaseSync, areaUuid: string): AreaMemberCounts;
 export declare function trashedCount(db: DatabaseSync): number;
 export declare function isRepeatingTemplate(task: AnyTask | null): boolean;
 /**
@@ -175,8 +357,6 @@ export declare function isRepeatingTemplate(task: AnyTask | null): boolean;
  *             unprobed and the guard rejects them.
  *  - inbox:   unscheduled to-dos with no container (start=0), by "index"
  *             (A6/P8a — the command ranks the sent list in order).
- *  - headings: the HEADING rows (type=2) of a project, by "index" (scf P1 —
- *             the private command accepts heading uuids; children follow).
  *  - someday: loose someday to-dos AND area-less someday projects, by
  *             "index"; same-type requests only. The Someday list handler is
  *             anchor-stacked with OPPOSITE stack directions by row type:
@@ -187,4 +367,15 @@ export declare function isRepeatingTemplate(task: AnyTask | null): boolean;
  *             when=anytime round-trip front-inserts (P8e).
  */
 export declare function computeReorderPre(db: DatabaseSync, params: ReorderParams, containerUuid: string | null, now: Date): ReorderPre;
-export declare function projectOf(task: AnyTask | null): Project | null;
+/**
+ * A row's live Today/Evening flag — `"today"`, `"evening"`, or `null` — read
+ * from the SAME marker the `today`/`evening` reorder membership uses
+ * ({@link computeReorderPre}, O01/O03/§9n): an ARRIVED scheduled row
+ * (`start IN (1,2)` AND `startDate <= today`) carries the flag — `evening` at
+ * raw `startBucket=1` (a live evening flag expires daily, so a stale past-dated
+ * bucket-1 row reads `today` proper), `today` otherwise. Someday, anytime,
+ * inbox, and future-scheduled rows carry NO flag. Single-sourced here so any
+ * de-Today guard (e.g. the `projects` bounce's de-star refusal in reorder.ts)
+ * keys off the one marker and can never drift from the membership query.
+ */
+export declare function todayEveningFlagOf(db: DatabaseSync, uuid: string, now: Date): "today" | "evening" | null;