things-api 0.8.0 → 0.10.0

package/dist/read/predicates.d.ts

@@ -0,0 +1,61 @@
+/** Real to-dos/projects (type IN 0,1), untrashed, excluding repeating templates. */
+export declare const LIVE = "t.type IN (0, 1) AND t.trashed = 0 AND (t.rt1_recurrenceRule IS NULL AND t.repeater IS NULL)";
+/** {@link LIVE} restricted to open (status = 0) rows. */
+export declare const OPEN = "t.type IN (0, 1) AND t.trashed = 0 AND (t.rt1_recurrenceRule IS NULL AND t.repeater IS NULL) AND t.status = 0";
+/**
+ * The GUI-visible set: open rows PLUS closed (completed/canceled) rows the
+ * periodic log-move sweep has NOT yet carried to the Logbook — completion ≠
+ * logged (src/read/log-boundary.ts). A closed row keeps its slot in its list
+ * until the sweep passes it, exactly as the GUI keeps it checked in place; it
+ * leaves when the sweep boundary advances past its stopDate (boundary-relative,
+ * no new state). This is {@link LIVE} widened to that set: swept iff
+ * status IN (2,3) AND stopDate IS NOT NULL AND stopDate <= boundary — the
+ * negation of the {@link markLogged} `logged` predicate, so an included closed
+ * row always materializes with `logged=false`. Mirrors the project/area card
+ * precedent (project-view.ts / area-view.ts keep a closed-but-unswept row
+ * checked in place). ONE bind: the log boundary as epoch seconds
+ * (logBoundary(db, now).getTime() / 1000). Ruling 2026-07-14 (Mike): GUI parity
+ * — `today` and `anytime` show checked-but-unswept rows.
+ */
+export declare const OPEN_OR_UNSWEPT = "t.type IN (0, 1) AND t.trashed = 0 AND (t.rt1_recurrenceRule IS NULL AND t.repeater IS NULL) AND NOT (t.status IN (2, 3) AND t.stopDate IS NOT NULL AND t.stopDate <= ?)";
+/**
+ * The `--overdue` content scope: OPEN items whose deadline falls strictly
+ * BEFORE today. Due-TODAY is deliberately NOT overdue (`<`, not `<=`) —
+ * mirroring the app's own Today badge split, where a deadline EQUAL to today
+ * reads as "due" and only an EARLIER deadline reads as "overdue". One bind:
+ * today as a packed-date int (encodePackedDate(localToday(now))), so the
+ * boundary rides the same injected clock every other view uses — never a
+ * hardcoded date. The `t.status = 0` clause re-tightens the OPEN_OR_UNSWEPT
+ * views (today/anytime) so a checked-but-unswept row that happens to sit past
+ * a deadline is excluded — overdue is remaining, OPEN work. Trash exclusion is
+ * the hosting view's job (every view this composes into already drops trashed
+ * and derived-trashed rows), so it is not repeated here.
+ */
+export declare const OVERDUE = "t.deadline IS NOT NULL AND t.deadline < ? AND t.status = 0";
+/** An item's own anytime membership: unscheduled-active, or dated <= today. */
+export declare const ANYTIME_SELF: (col: string) => string;
+/**
+ * The item's effective project: its own link, or its heading's project for
+ * headed children (heading rows carry the project link).
+ */
+export declare const EFF_PROJECT = "COALESCE(t.project, (SELECT h.project FROM TMTask h WHERE h.uuid = t.heading))";
+/**
+ * Container cascade (live-verified against the UI, 2026-07-09): a to-do
+ * inside a project that is NOT itself anytime-visible (someday or
+ * future-scheduled, logged, or trashed) is absent from Anytime regardless of
+ * the to-do's own start state — the project row alone represents it.
+ * Projects and container-less to-dos pass through. Two binds (packedToday ×2).
+ */
+export declare const PROJECT_ANYTIME_ACTIVE: string;
+/**
+ * DERIVED-trash exclusion: project deletion is SHALLOW (A24B — only the
+ * project row flips trashed=1; children keep trashed=0 and their links, so
+ * their Trash membership is derived through the container chain). Every live
+ * view must therefore check the chain, not just the row's own flag: the
+ * heading (if any) and the effective project (direct or via heading) must
+ * both be untrashed. Areas cannot be trashed (they delete permanently), so
+ * the chain is at most heading → project. Trash-adjacent surfaces stay
+ * exempt on purpose: `things trash` lists directly-flagged rows, and a
+ * trashed project's OWN view shows its would-be-recovered children.
+ */
+export declare const CONTAINER_UNTRASHED = "(t.heading IS NULL OR EXISTS (\n     SELECT 1 FROM TMTask hh WHERE hh.uuid = t.heading AND hh.trashed = 0))\n AND (COALESCE(t.project, (SELECT h.project FROM TMTask h WHERE h.uuid = t.heading)) IS NULL OR EXISTS (\n     SELECT 1 FROM TMTask cc WHERE cc.uuid = COALESCE(t.project, (SELECT h.project FROM TMTask h WHERE h.uuid = t.heading)) AND cc.trashed = 0))";

package/dist/read/predicates.js

@@ -0,0 +1,78 @@
+/**
+ * Shared SQL predicate fragments for the list views (src/read/views.ts).
+ * Every live view composes these so the membership rules — untrashed, open,
+ * anytime-self, the effective-project resolution, and the derived-trash
+ * container checks — are written once and cannot drift between views.
+ *
+ * Derivation and live-probe provenance are documented at each view's call
+ * site in views.ts and in docs/atlas/schema-v26.md.
+ */
+import { NOT_TEMPLATE } from "./queries.js";
+/** Real to-dos/projects (type IN 0,1), untrashed, excluding repeating templates. */
+export const LIVE = `t.type IN (0, 1) AND t.trashed = 0 AND ${NOT_TEMPLATE}`;
+/** {@link LIVE} restricted to open (status = 0) rows. */
+export const OPEN = `${LIVE} AND t.status = 0`;
+/**
+ * The GUI-visible set: open rows PLUS closed (completed/canceled) rows the
+ * periodic log-move sweep has NOT yet carried to the Logbook — completion ≠
+ * logged (src/read/log-boundary.ts). A closed row keeps its slot in its list
+ * until the sweep passes it, exactly as the GUI keeps it checked in place; it
+ * leaves when the sweep boundary advances past its stopDate (boundary-relative,
+ * no new state). This is {@link LIVE} widened to that set: swept iff
+ * status IN (2,3) AND stopDate IS NOT NULL AND stopDate <= boundary — the
+ * negation of the {@link markLogged} `logged` predicate, so an included closed
+ * row always materializes with `logged=false`. Mirrors the project/area card
+ * precedent (project-view.ts / area-view.ts keep a closed-but-unswept row
+ * checked in place). ONE bind: the log boundary as epoch seconds
+ * (logBoundary(db, now).getTime() / 1000). Ruling 2026-07-14 (Mike): GUI parity
+ * — `today` and `anytime` show checked-but-unswept rows.
+ */
+export const OPEN_OR_UNSWEPT = `${LIVE} AND NOT (t.status IN (2, 3) AND t.stopDate IS NOT NULL AND t.stopDate <= ?)`;
+/**
+ * The `--overdue` content scope: OPEN items whose deadline falls strictly
+ * BEFORE today. Due-TODAY is deliberately NOT overdue (`<`, not `<=`) —
+ * mirroring the app's own Today badge split, where a deadline EQUAL to today
+ * reads as "due" and only an EARLIER deadline reads as "overdue". One bind:
+ * today as a packed-date int (encodePackedDate(localToday(now))), so the
+ * boundary rides the same injected clock every other view uses — never a
+ * hardcoded date. The `t.status = 0` clause re-tightens the OPEN_OR_UNSWEPT
+ * views (today/anytime) so a checked-but-unswept row that happens to sit past
+ * a deadline is excluded — overdue is remaining, OPEN work. Trash exclusion is
+ * the hosting view's job (every view this composes into already drops trashed
+ * and derived-trashed rows), so it is not repeated here.
+ */
+export const OVERDUE = `t.deadline IS NOT NULL AND t.deadline < ? AND t.status = 0`;
+/** An item's own anytime membership: unscheduled-active, or dated <= today. */
+export const ANYTIME_SELF = (col) => `((${col}.start = 1 AND (${col}.startDate IS NULL OR ${col}.startDate <= ?))
+    OR (${col}.start = 2 AND ${col}.startDate IS NOT NULL AND ${col}.startDate <= ?))`;
+/**
+ * The item's effective project: its own link, or its heading's project for
+ * headed children (heading rows carry the project link).
+ */
+export const EFF_PROJECT = `COALESCE(t.project, (SELECT h.project FROM TMTask h WHERE h.uuid = t.heading))`;
+/**
+ * Container cascade (live-verified against the UI, 2026-07-09): a to-do
+ * inside a project that is NOT itself anytime-visible (someday or
+ * future-scheduled, logged, or trashed) is absent from Anytime regardless of
+ * the to-do's own start state — the project row alone represents it.
+ * Projects and container-less to-dos pass through. Two binds (packedToday ×2).
+ */
+export const PROJECT_ANYTIME_ACTIVE = `(${EFF_PROJECT} IS NULL OR EXISTS (
+     SELECT 1 FROM TMTask p WHERE p.uuid = ${EFF_PROJECT}
+     AND p.trashed = 0 AND p.status = 0 AND ${ANYTIME_SELF("p")}))`;
+/**
+ * DERIVED-trash exclusion: project deletion is SHALLOW (A24B — only the
+ * project row flips trashed=1; children keep trashed=0 and their links, so
+ * their Trash membership is derived through the container chain). Every live
+ * view must therefore check the chain, not just the row's own flag: the
+ * heading (if any) and the effective project (direct or via heading) must
+ * both be untrashed. Areas cannot be trashed (they delete permanently), so
+ * the chain is at most heading → project. Trash-adjacent surfaces stay
+ * exempt on purpose: `things trash` lists directly-flagged rows, and a
+ * trashed project's OWN view shows its would-be-recovered children.
+ */
+export const CONTAINER_UNTRASHED = `(t.heading IS NULL OR EXISTS (
+     SELECT 1 FROM TMTask hh WHERE hh.uuid = t.heading AND hh.trashed = 0))
+ AND (${EFF_PROJECT} IS NULL OR EXISTS (
+     SELECT 1 FROM TMTask cc WHERE cc.uuid = ${EFF_PROJECT} AND cc.trashed = 0))`;
+//# sourceMappingURL=predicates.js.map

package/dist/read/predicates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicates.js","sourceRoot":"","sources":["../../src/read/predicates.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,oFAAoF;AACpF,MAAM,CAAC,MAAM,IAAI,GAAG,0CAA0C,YAAY,EAAE,CAAC;AAE7E,yDAAyD;AACzD,MAAM,CAAC,MAAM,IAAI,GAAG,GAAG,IAAI,mBAAmB,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,IAAI,8EAA8E,CAAC;AAErH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,4DAA4D,CAAC;AAEpF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAW,EAAU,EAAE,CAClD,KAAK,GAAG,mBAAmB,GAAG,yBAAyB,GAAG;UAClD,GAAG,kBAAkB,GAAG,8BAA8B,GAAG,mBAAmB,CAAC;AAEvF;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,gFAAgF,CAAC;AAE5G;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,WAAW;6CACR,WAAW;8CACV,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;QAE3B,WAAW;+CAC4B,WAAW,uBAAuB,CAAC"}

package/dist/read/project-view.d.ts

@@ -9,6 +9,7 @@
  */
 import type { DatabaseSync } from "node:sqlite";
 import type { Heading, IsoDateGroup, Project, Todo } from "../model/entities.ts";
+import { type ViewFilter } from "./views.ts";
 export interface ProjectView {
     project: Project;
     /** Open, unscheduled/current children not under a heading, by index. */
@@ -27,8 +28,18 @@ export interface ProjectView {
     };
     logged: Todo[];
     trashed: Todo[];
+    /**
+     * PLOG1 (additive): count of untrashed OPEN (status=0) children this project
+     * still holds while it is ITSELF completed or canceled — including once swept
+     * to the Logbook. Such items are invisible in every live app view (Today /
+     * Anytime / Inbox / Upcoming), reachable only by drilling into this card
+     * (the app's GUI "Put Back" into a completed parent can strand them —
+     * docs/lab/plog1-research.md). 0 when the project is open, or holds no such
+     * child.
+     */
+    openChildrenWhileResolved: number;
 }
 export declare class ProjectNotFoundError extends Error {
     constructor(uuid: string);
 }
-export declare function projectView(db: DatabaseSync, uuid: string, now?: Date): ProjectView;
+export declare function projectView(db: DatabaseSync, uuid: string, now?: Date, filter?: ViewFilter): ProjectView;

package/dist/read/project-view.js

@@ -2,14 +2,17 @@ import { encodePackedDate, localToday, decodePackedDate } from "../model/dates.j
 import { mapHeading, mapProject, mapTodo } from "../model/mappers.js";
 import { fetchTagsForTasks, fetchTaskByUuid, fetchTaskRows, makeRefResolver } from "./queries.js";
 import { logBoundary, markLogged } from "./log-boundary.js";
+import { OVERDUE } from "./predicates.js";
 import { inheritedTagsFor } from "./tags.js";
+import { tagFilter } from "./views.js";
 export class ProjectNotFoundError extends Error {
     constructor(uuid) {
         super(`no project with uuid ${uuid}`);
         this.name = "ProjectNotFoundError";
     }
 }
-export function projectView(db, uuid, now) {
+export function projectView(db, uuid, now, filter = {}) {
+    const overdue = filter.overdue === true;
     const projectRow = fetchTaskByUuid(db, uuid);
     if (!projectRow || projectRow.type !== 1)
         throw new ProjectNotFoundError(uuid);
@@ -21,10 +24,26 @@ export function projectView(db, uuid, now) {
     project.inheritedTags = inheritedTagsFor(db, projectRow);
     const headingRows = fetchTaskRows(db, `t.type = 2 AND t.project = ? AND t.trashed = 0 ORDER BY t."index" ASC`, [uuid]);
     const headings = headingRows.map((h) => mapHeading(h, refs));
+    // OWN-DEADLINE UNIFORM: `--overdue` narrows the child TO-DOS to those whose
+    // OWN deadline is overdue (open, strictly before today) via the shared
+    // OVERDUE predicate — NO recursion into anything, and the project header
+    // itself always renders. Headings that keep no surviving child collapse
+    // (below). Its single packed-today bind trails the two uuid binds.
+    const overdueSql = overdue ? ` AND ${OVERDUE}` : "";
+    const overdueBinds = overdue ? [encodePackedDate(localToday(now))] : [];
+    // Tag scope (§9a): the child to-dos are filtered by a tag carried DIRECTLY on
+    // the row — the container semantics. The project's own tags are inherited by
+    // EVERY child, so an inheritance-inclusive `--tag` would be vacuous here;
+    // suppressing the container hop makes `--tag` mean "children with this tag on
+    // themselves" (still descendant-expanded), and `--untagged` "children with no
+    // direct tag". No recursion; the header always renders. The tag binds trail
+    // the two uuid binds and lead the overdue bind, matching their left-to-right
+    // order in the SQL.
+    const tf = tagFilter(db, filter, { container: true });
     const childRows = fetchTaskRows(db, `t.type = 0 AND (t.project = ? OR t.heading IN (
        SELECT uuid FROM TMTask WHERE type = 2 AND project = ?
-     ))
-     ORDER BY t."index" ASC`, [uuid, uuid]);
+     ))${tf.sql}${overdueSql}
+     ORDER BY t."index" ASC`, [uuid, uuid, ...tf.binds, ...overdueBinds]);
     const childTags = tagsOf(childRows);
     const boundary = logBoundary(db, now);
     const todos = childRows.map((r) => ({
@@ -40,6 +59,10 @@ export function projectView(db, uuid, now) {
     const someday = [];
     const logged = [];
     const trashed = [];
+    // Every untrashed, non-template OPEN child, regardless of which bucket it
+    // lands in below — surfaced (only when the project is itself resolved) as
+    // the PLOG1 stranded-open-child count.
+    let openChildren = 0;
     for (const { row, todo } of todos) {
         if (row.trashed === 1) {
             trashed.push(todo);
@@ -49,6 +72,8 @@ export function projectView(db, uuid, now) {
             repeating.push(todo);
             continue;
         }
+        if (row.status === 0)
+            openChildren += 1;
         if (row.status !== 0) {
             // Completion ≠ logged: closed items the log-move sweep has not
             // passed stay checked IN PLACE (their heading / the active block),
@@ -90,23 +115,29 @@ export function projectView(db, uuid, now) {
     logged.sort((a, b) => (b.stopped?.getTime() ?? 0) - (a.stopped?.getTime() ?? 0));
     const scheduled = [];
     // Within a day the UI sorts by todayIndex ASC (Upcoming drag order).
-    for (const { date, todo } of scheduledRows.sort((a, b) => a.date.localeCompare(b.date) || a.ti - b.ti)) {
+    for (const { date, todo } of scheduledRows.toSorted((a, b) => a.date.localeCompare(b.date) || a.ti - b.ti)) {
         const last = scheduled[scheduled.length - 1];
         if (last && last.date === date)
             last.items.push(todo);
         else
             scheduled.push({ date, items: [todo] });
     }
+    // Under any content scope (`--overdue` or a tag filter), a heading whose
+    // children were all filtered out collapses rather than rendering an empty
+    // section; a heading with a surviving child is kept. With no scope active
+    // every heading renders (its own empty state).
+    const contentScoped = overdue || tf.sql !== "";
+    const headingGroups = headings
+        .map((heading) => ({ heading, items: byHeading.get(heading.uuid) ?? [] }))
+        .filter((g) => !contentScoped || g.items.length > 0);
     return {
         project,
         active,
-        headings: headings.map((heading) => ({
-            heading,
-            items: byHeading.get(heading.uuid) ?? [],
-        })),
+        headings: headingGroups,
         later: { scheduled, repeating, someday },
         logged,
         trashed,
+        openChildrenWhileResolved: project.status === "open" ? 0 : openChildren,
     };
 }
 //# sourceMappingURL=project-view.js.map

package/dist/read/project-view.js.map

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

package/dist/read/queries.d.ts

@@ -9,13 +9,51 @@ import type { ChecklistRow, TaskRow } from "../model/mappers.ts";
 export declare const NOT_TEMPLATE = "(t.rt1_recurrenceRule IS NULL AND t.repeater IS NULL)";
 /**
  * UI-faithful tag membership for list filtering: direct tag, or inherited
- * through the ancestor chain heading → project → area (T18/U18/A13 — the
- * same chain inheritedTagsFor() walks). Takes a SET of tag uuids (the target
- * plus its hierarchy descendants) — each of the six clauses gets the full
- * set, so callers bind `uuids.length * 6` values via tagScopeBinds().
+ * through the ancestor chain heading → project → area — the OR of every
+ * {@link INHERITANCE_CLAUSES} hop. Takes a SET of tag uuids (the target plus its
+ * hierarchy descendants); each hop gets the full set, so callers bind
+ * `uuids.length * INHERITANCE_CLAUSES.length` values via {@link tagScopeBinds}.
  */
 export declare function tagScopeSql(uuidCount: number): string;
+/**
+ * The bind list for {@link tagScopeSql}: the uuid set repeated once per hop, in
+ * clause order. Derived from the clause count so the bind multiplicity can never
+ * drift from the number of hops the SQL actually emits.
+ */
 export declare function tagScopeBinds(uuids: string[]): string[];
+/**
+ * The DIRECT-ONLY projection of {@link tagScopeSql}: {@link DIRECT_TAG_CLAUSE}
+ * alone — the item's own `TMTaskTag` assignments — WITHOUT the five container-
+ * inheritance hops (project/area/heading). This is the SQL behind the CONTAINER
+ * `--tag` (the `project show` / `area show` / `projects` list views): every
+ * child inherits its container's tags, so the inheritance-inclusive relation is
+ * vacuous there — matching a DIRECT assignment is the useful, GUI-faithful
+ * behavior. It keeps tag-hierarchy descendant expansion (the uuid SET is still
+ * the tag plus its descendants, OR-matched) but drops container inheritance, so
+ * an item matches only when it is DIRECTLY tagged. Takes the uuid set once, so
+ * callers bind `uuids` exactly one time (not `× 6`).
+ */
+export declare function directTagScopeSql(uuidCount: number): string;
+/**
+ * The negation of tag membership — the SQL behind the `untagged` filter (the
+ * GUI's "No Tag"). It negates the SAME {@link INHERITANCE_CLAUSES} relation with
+ * the tag-set restriction dropped: "carries ANY tag by any hop", wrapped in NOT.
+ * An item is untagged iff NO possible `--tag X` could ever match it — so this
+ * negates the whole membership relation, not merely the row's own direct
+ * assignments. Takes no binds.
+ */
+export declare function untaggedScopeSql(): string;
+/**
+ * The DIRECT-ONLY counterpart of {@link untaggedScopeSql} — the SQL behind the
+ * CONTAINER `--untagged` (the GUI's in-context "No Tag" inside a project/area
+ * card). It negates only {@link DIRECT_TAG_CLAUSE} (the item's OWN direct
+ * assignments), leaving container inheritance untouched: an item qualifies when
+ * it carries no DIRECT tag, even if it inherits one from its project/area/
+ * heading. Every child inherits the container's tags, so the whole-relation
+ * {@link untaggedScopeSql} would exclude every row there — direct-only is the
+ * useful negation. Takes no binds.
+ */
+export declare function directUntaggedScopeSql(): string;
 /**
  * A tag plus every hierarchy descendant. Filtering by a parent tag matches
  * child-tagged items — DOCUMENTED app behavior (the UI's tag filter works
@@ -39,7 +77,43 @@ export declare function tagWithDescendants(db: DatabaseSync, uuid: string): stri
  * input passes through untouched (after trimming).
  */
 export declare function stripThingsUri(ref: string): string;
-export declare function resolveTaskUuidPrefix(db: DatabaseSync, refRaw: string): string;
+/**
+ * The single source for uuid-miss not-found copy. Reused by the read-side
+ * resolvers, the write guards, and the MCP item lookups so a uuid/partial-uuid
+ * that matches nothing reads identically wherever the miss is reported.
+ */
+export declare function noUuidMatch(entity: string, ref: string): string;
+/** A disambiguation candidate for a reference-resolution failure. */
+export interface RefCandidate {
+    uuid: string;
+    title: string;
+    /** Optional context that distinguishes same-named candidates (area for a project, parent path for a tag). */
+    context?: string;
+}
+/**
+ * A reference (uuid / partial-uuid / name) that did not resolve to exactly one
+ * entity. Extends RangeError so every existing `instanceof RangeError` handler
+ * keeps treating it as a usage-class failure — but the surfaces that know about
+ * it (CLI --json envelope, MCP tool result) additionally lift the structured
+ * `candidates` onto `error.details.candidates` so an agent can self-correct
+ * without re-parsing the prose message. `code` mirrors the envelope error code.
+ *
+ * PUBLIC API — exported from src/index.ts. This is the one error the consumer
+ * surfaces catch to render structured disambiguation; its `code`
+ * ("not-found" | "ambiguous") and `candidates` ({@link RefCandidate}[]) are the
+ * documented machine shape (docs/design/architecture.md, Consumer boundary).
+ */
+export declare class ReferenceResolutionError extends RangeError {
+    readonly code: "not-found" | "ambiguous";
+    readonly ref: string;
+    readonly candidates: RefCandidate[];
+    constructor(message: string, opts: {
+        code: "not-found" | "ambiguous";
+        ref: string;
+        candidates?: RefCandidate[];
+    });
+}
+export declare function resolveTaskUuidPrefix(db: DatabaseSync, refRaw: string, entity?: string): string;
 /**
  * Fold a name to its match key: NFC + case-fold + strip all whitespace and
  * dashes/hyphens (ASCII hyphen, the U+2010–2015 dash block, U+2212 minus).
@@ -54,6 +128,15 @@ export interface NamedResolution {
     } | null;
     /** 0 = not found, 1 = ok, >1 = ambiguous at the deciding tier. */
     matches: number;
+    /**
+     * The rows at the deciding tier when it was ambiguous (matches > 1) — the
+     * candidates a fail-closed resolver lists so the caller can disambiguate by
+     * uuid. Absent when resolved or not-found.
+     */
+    candidates?: {
+        uuid: string;
+        title: string;
+    }[];
 }
 /**
  * Tiered reference resolution (docs/design/reference-resolution.md): exact
@@ -62,7 +145,25 @@ export interface NamedResolution {
  * ambiguous; no tier is not-found. Shared by the read-side `resolve*Uuid`
  * throwers and the write-side `resolve*` (ContainerResolution) helpers.
  */
-export declare function resolveNamedRef(db: DatabaseSync, table: string, extraWhere: string, extraBinds: (string | number)[], refRaw: string): NamedResolution;
+export declare function resolveNamedRef(db: DatabaseSync, table: string, extraWhere: string, extraBinds: (string | number)[], refRaw: string, options?: {
+    prefixTier?: boolean;
+}): NamedResolution;
+/**
+ * Resolve a PROJECT write target from a uuid, partial-uuid, or unique name.
+ * Project write verbs (`things project update <ref>`, etc.) accept names
+ * through this; to-do and heading write targets stay uuid-only.
+ *
+ * A uuid / unique uuid-prefix resolves FIRST over every task (reusing
+ * {@link resolveTaskUuidPrefix}), so a wrong-TYPE id — a to-do uuid handed to a
+ * project verb — passes through to the op's own guard, which reports it with a
+ * targeted "that is a to-do, not a project" message rather than a misleading
+ * not-found. Otherwise the ref resolves as a project NAME through the SAME
+ * tiered {@link resolveNamedRef} matching the read side uses (shared core, not
+ * a fork) across projects (trashed included, for `project restore`), fail-
+ * closed with a candidate listing on an ambiguous name so a duplicated project
+ * title is disambiguated by uuid rather than guessed.
+ */
+export declare function resolveProjectWriteTarget(db: DatabaseSync, refRaw: string): string;
 export declare function resolveTagUuid(db: DatabaseSync, ref: string): string;
 /**
  * Write destinations stay strict (a trashed project is not a valid target);
@@ -71,12 +172,59 @@ export declare function resolveTagUuid(db: DatabaseSync, ref: string): string;
  */
 export declare function resolveProjectUuid(db: DatabaseSync, ref: string, options?: {
     trashed?: boolean;
+    prefixTier?: boolean;
 }): string;
-export declare function resolveAreaUuid(db: DatabaseSync, ref: string): string;
+export declare function resolveAreaUuid(db: DatabaseSync, ref: string, options?: {
+    prefixTier?: boolean;
+}): string;
+/**
+ * A row's EFFECTIVE area: its own `area` link, else the area of its project,
+ * else the area of its heading's project. To-dos nested in a project (or under a
+ * heading) carry `area = NULL` in the DB — the area lives on the container — so
+ * this resolves the nearest area walking the SAME chain the tag-inheritance SQL
+ * uses (t.area → t.project's area → t.heading's project's area). Projects carry
+ * their area directly (project/heading are NULL), so COALESCE returns `t.area`
+ * unchanged for them — areas are not inherited. Surfaced as the entity's `area`
+ * Ref (mappers.ts); whether it is direct vs effective stays derivable from
+ * whether `project`/`heading` is set. Emitted as the extra `effectiveArea`
+ * column so the raw `t.area` (which tag inheritance and the write layer read)
+ * stays available.
+ */
+export declare const EFFECTIVE_AREA = "COALESCE(\n  t.area,\n  (SELECT p.area FROM TMTask p WHERE p.uuid = t.project),\n  (SELECT hp.area FROM TMTask h JOIN TMTask hp ON hp.uuid = h.project WHERE h.uuid = t.heading)\n)";
 export declare function fetchTaskRows(db: DatabaseSync, where: string, params?: unknown[]): TaskRow[];
 export declare function fetchTaskByUuid(db: DatabaseSync, uuid: string): TaskRow | null;
 export declare function fetchChecklistRows(db: DatabaseSync, taskUuid: string): ChecklistRow[];
-/** Direct tags for a set of tasks, in one query. Returns uuid -> Ref[] (sorted by tag title). */
+/**
+ * Direct tags for a set of tasks, in one query. Returns uuid -> Ref[] in the
+ * app's CANONICAL tag order.
+ *
+ * CANONICAL ORDER (ratified 2026-07-14; tiebreak corrected 2026-07-15 by
+ * TAGORD1): `TMTag."index"` (INTEGER, often negative) is the user-draggable
+ * order from the app's Tags window, and the GUI renders every multi-tag pill row
+ * in ascending `index`. Live oracle: the `Replace CPAP mask & air filter` to-do
+ * shows `#recurring #home #housekeeping`, matching the tags' indexes, NOT their
+ * alphabetical order.
+ *
+ * TIEBREAK = `uuid`, NOT `title` (TAGORD1 lab oracle, docs/lab/taglab-probes.md).
+ * Never-dragged tags ubiquitously tie at `index = 0`; the app breaks that tie by
+ * the tag's UUID (ascending ASCII), NOT alphabetically. Proven across three
+ * surfaces in a VM (Tags window, a to-do's multi-tag pill row — input-order
+ * independent, and the list filter-bar chips): 8 tags seeded reverse-alpha all
+ * tied at 0 displayed in exact uuid order, and `ORDER BY "index", uuid`
+ * reproduced the whole Tags-window order byte-for-byte where `ORDER BY "index",
+ * title` diverged. TMTag has no creation-date column, so creation order is not
+ * even a candidate comparator.
+ *
+ * NESTED-TAG CAVEAT (open question, deliberately unsolved): child tags' indexes
+ * interleave globally with top-level ones — CONFIRMED by TAGORD1: `TMTag."index"`
+ * is a single GLOBAL space, not per-parent (a seeded child landed at -378 among
+ * root tags at 0/-35/-67). So a flat-index sort can place a child BEFORE its
+ * parent in a multi-tag row. No live item carries a nested tag alongside another
+ * tag, so there is no GUI oracle for the interleaved case — flat ascending
+ * `index` is the ratified comparator, isolated HERE. If a GUI oracle ever
+ * contradicts it, the fix is a DFS-rank swap in this one ORDER BY (rank children
+ * after parents).
+ */
 export declare function fetchTagsForTasks(db: DatabaseSync, taskUuids: string[]): Map<string, Ref[]>;
 /**
  * Lazy heading-uuid -> owning-project Ref resolver, cached per instance.