things-api 0.11.0 → 0.13.0

package/dist/read/queries.d.ts

@@ -3,8 +3,9 @@
  * schema manifest so removed columns fail loudly (drift), never silently.
  */
 import type { DatabaseSync } from "node:sqlite";
-import type { Ref } from "../model/entities.ts";
+import { type Ref } from "../model/entities.ts";
 import type { ChecklistRow, TaskRow } from "../model/mappers.ts";
+import { type CandidateRef, type RefKind, type RefPromoter } from "./shape.ts";
 /** Rows that repeat via a template are normal; template rows are invisible in list views. */
 export declare const NOT_TEMPLATE = "(t.rt1_recurrenceRule IS NULL AND t.repeater IS NULL)";
 /**
@@ -83,37 +84,44 @@ export declare function stripThingsUri(ref: string): string;
  * 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
+ * `candidates` onto `error.detail.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).
+ * ("not-found" | "ambiguous") and `candidates` ({@link CandidateRef}[], the ONE
+ * fixed candidate shape) are the documented machine shape
+ * (docs/design/architecture.md, Consumer boundary). The list is capped at
+ * {@link CANDIDATE_CAP}; on overflow the `message` states the total.
  */
 export declare class ReferenceResolutionError extends RangeError {
     readonly code: "not-found" | "ambiguous";
     readonly ref: string;
-    readonly candidates: RefCandidate[];
+    readonly candidates: CandidateRef[];
     constructor(message: string, opts: {
         code: "not-found" | "ambiguous";
         ref: string;
-        candidates?: RefCandidate[];
+        candidates?: CandidateRef[];
     });
 }
-export declare function resolveTaskUuidPrefix(db: DatabaseSync, refRaw: string, entity?: string): string;
+/**
+ * An optional membership clause (on alias `t`) restricting a resolver to
+ * in-scope rows — the container-scope no-oracle mechanism. When supplied, an
+ * out-of-scope row resolves to "not found" through the IDENTICAL code path a
+ * nonexistent one does, so the two are byte-indistinguishable. Built by
+ * `src/read/scope.ts`; queries.ts treats it as opaque SQL to avoid a runtime
+ * import cycle.
+ */
+export interface ScopeClause {
+    where: string;
+    binds: (string | number)[];
+}
+export declare function resolveTaskUuidPrefix(db: DatabaseSync, refRaw: string, entity?: string, scope?: ScopeClause): 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).
@@ -121,6 +129,9 @@ export declare function resolveTaskUuidPrefix(db: DatabaseSync, refRaw: string,
  * docs/design/reference-resolution.md.
  */
 export declare function normalizeNameKey(s: string): string;
+/** The fused TTY ref form `Title [8charPrefix]` — the round-trippable decorated ref every candidate renders. */
+export declare const REF_PREFIX_LEN = 8;
+export declare function fusedRef(title: string, uuid: string): string;
 export interface NamedResolution {
     resolved: {
         uuid: string;
@@ -147,7 +158,21 @@ export interface NamedResolution {
  */
 export declare function resolveNamedRef(db: DatabaseSync, table: string, extraWhere: string, extraBinds: (string | number)[], refRaw: string, options?: {
     prefixTier?: boolean;
+    scopeWhere?: string;
+    scopeBinds?: (string | number)[];
+    /**
+     * An extra clause AND-ed into the NAME tiers ONLY (exact/case-insensitive/
+     * normalized title) — never the uuid-exact or uuid-prefix tiers. Lets a
+     * resolver narrow name resolution (e.g. project write targets to OPEN rows)
+     * while a UUID / partial-uuid — explicit intent — still reaches every row.
+     */
+    nameExtraWhere?: string;
 }): NamedResolution;
+export declare function deadNameMatchHint(counts: {
+    trashed?: number;
+    logbook?: number;
+    completed?: number;
+}): string;
 /**
  * Resolve a PROJECT write target from a uuid, partial-uuid, or unique name.
  * Project write verbs (`things project update <ref>`, etc.) accept names
@@ -159,24 +184,135 @@ export declare function resolveNamedRef(db: DatabaseSync, table: string, extraWh
  * 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.
+ * a fork).
+ *
+ * The NAME pool is LIVE + OPEN-scoped by default (`trashed = 0 AND status = 0`)
+ * — a trashed OR completed/canceled project never resolves-by-name or appears as
+ * an ambiguity candidate for an ordinary write verb. A completed project is
+ * excluded deliberately (broader than "logged", which needs the log-boundary
+ * clock this pure resolver lacks): placing an open child in it strands the child
+ * one sweep later (PLOG1). A name that matches ONLY non-open/trashed rows fails
+ * not-found with an honest hint (`things trash` / target-by-uuid) rather than a
+ * dead candidate. A UUID / partial-uuid resolves FIRST (via
+ * {@link resolveTaskUuidPrefix}, status-blind), so explicit-uuid intent still
+ * reaches a completed/logged project. `includeNonOpen` (the `project.reopen`
+ * verb — its whole point is a non-open target) widens the name pool to
+ * completed/canceled rows; `includeTrashed` (the trash-domain `project.restore`
+ * op) widens it to trashed rows so a restore-by-name can disambiguate them.
+ * Fail-closed with a candidate listing on an ambiguous name.
  */
-export declare function resolveProjectWriteTarget(db: DatabaseSync, refRaw: string): string;
+export declare function resolveProjectWriteTarget(db: DatabaseSync, refRaw: string, scope?: {
+    task: ScopeClause;
+    named: {
+        where: string;
+        binds: (string | number)[];
+    };
+}, includeTrashed?: boolean, includeNonOpen?: boolean): string;
 export declare function resolveTagUuid(db: DatabaseSync, ref: string): string;
+/** Options shared by the read-side project resolvers (a name-tier narrowing subset). */
+interface ReadProjectOptions {
+    prefixTier?: boolean;
+    scopeWhere?: string;
+    scopeBinds?: (string | number)[];
+}
+/**
+ * A read-side PROJECT NAME resolution verdict under the liveness law (never
+ * throws) — the shared core behind the throwing {@link resolveProjectUuid}
+ * (`project show`) and the cross-kind {@link classifyShowTarget} router.
+ *
+ * The uuid / partial-uuid tiers reach EVERY project row (explicit intent stays
+ * able to view a trashed project by id); the NAME tiers resolve against LIVE
+ * (untrashed) rows only, so a dead twin never shadows a live one nor inflates
+ * an ambiguity count. When the live pool is empty, the TRASHED pool is consulted
+ * for the reads-only ergonomic fallback: a UNIQUELY-named trashed project still
+ * resolves by name (the render discloses it — the card's own `(trashed)` marker
+ * / `stage: "trash"`), while several dead twins report honestly instead.
+ */
+export interface ReadProjectVerdict {
+    /** The resolved winner — a live unique, a uuid/partial-uuid, or the unique-dead fallback; else null. */
+    resolved: {
+        uuid: string;
+        title: string;
+    } | null;
+    /** ALL live name-matching rows at the deciding tier (0, 1, or many). */
+    liveRows: {
+        uuid: string;
+        title: string;
+    }[];
+    /** 0 / 1 / >1 — the LIVE match count (the ambiguity count when > 1). */
+    liveMatches: number;
+    /** Count of TRASHED-name twins — feeds the disclosure tail / dead-hint. */
+    trashedMatches: number;
+}
+export declare function readProjectNameVerdict(db: DatabaseSync, ref: string, options?: ReadProjectOptions): ReadProjectVerdict;
 /**
  * Write destinations stay strict (a trashed project is not a valid target);
  * READ surfaces pass `trashed: true` so a project in the Trash can still be
- * viewed — its would-be-recovered children are only visible there.
+ * viewed. Under `trashed: true` the read-side liveness law applies: an explicit
+ * uuid / partial-uuid reaches any project, but a NAME resolves against LIVE rows
+ * only (a dead same-name twin never shadows a live one), with the reads-only
+ * unique-dead fallback + trash disclosure ({@link readProjectNameVerdict}).
  */
 export declare function resolveProjectUuid(db: DatabaseSync, ref: string, options?: {
     trashed?: boolean;
     prefixTier?: boolean;
+    scopeWhere?: string;
+    scopeBinds?: (string | number)[];
 }): string;
+/**
+ * The disclosure tail appended to a read-side project ambiguity when the
+ * uuid-reachable pool holds additional TRASHED twins of the ambiguous name. The
+ * ambiguity COUNT stays over live rows (coherent with the rendered candidate
+ * list); the dead ones are disclosed separately rather than inflating it. Empty
+ * when none are trashed.
+ */
+export declare function trashDisclosureTail(deadCount: number): string;
 export declare function resolveAreaUuid(db: DatabaseSync, ref: string, options?: {
     prefixTier?: boolean;
+    scopeWhere?: string;
+    scopeBinds?: (string | number)[];
 }): string;
+/**
+ * Resolve a HEADING SELECTOR (spec §2) inside one project through the SAME
+ * tiered core every other ref uses: exact title, or uuid (partial-uuid too).
+ * There is deliberately NO index/ordinal form — the "reindex hazard" makes an
+ * ordinal silently re-target a different heading after any reorder. An
+ * empty-string selector is a legal literal query (the app creates titleless
+ * headings); duplicates (or several titleless headings) are a resolution
+ * PRECONDITION, not an invariant, so ambiguity fails closed with uuid-bearing
+ * candidates (the H-DUPLICATE-TAG precedent). Shared by `todo add/move
+ * --heading` (via {@link resolveHeadingRef} → the H-AMBIGUOUS-HEADING guard)
+ * and by every project heading verb (via the thrower below).
+ */
+export declare function resolveHeadingRef(db: DatabaseSync, projectUuid: string, refRaw: string): NamedResolution;
+/**
+ * Resolve a heading selector to its uuid+title within a project, throwing a
+ * {@link ReferenceResolutionError} (with uuid candidates on ambiguity) the
+ * consumer surfaces render as a usage error. The project-scoped heading verbs
+ * and the MCP heading tool resolve through this.
+ */
+export declare function resolveHeadingUuid(db: DatabaseSync, projectUuid: string, refRaw: string): {
+    uuid: string;
+    title: string;
+};
+/**
+ * Does a container ref's bare TITLE round-trip through its own resolver, in its
+ * own scope, back to THIS entity's uuid? The single predicate the emit boundary
+ * consults for the JSON round-trip law — true only when the sole resolution is
+ * `entityUuid` (not-found / ambiguous / a different entity all → false, i.e. the
+ * title must promote its uuid sibling). See {@link resolveTitleForRoundTrip}.
+ */
+export declare function titleRoundTrips(db: DatabaseSync, kind: RefKind, title: string, entityUuid: string, projectUuid?: string): boolean;
+/**
+ * Build the {@link RefPromoter} the read-shaping transform ({@link shapeReadPayload})
+ * consults to decide flat-ref uuid promotion, memoized per (kind, title, scope)
+ * for ONE response emission so a large view never re-runs a resolution it has
+ * already made. A fresh promoter (fresh memo) per response — the consumer
+ * surfaces build one via the client. The memo caches the RESOLVED uuid (or null),
+ * independent of the comparison target, so twin entities sharing a title share
+ * the one resolution.
+ */
+export declare function makeRefPromoter(db: DatabaseSync): RefPromoter;
 /**
  * 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
@@ -193,6 +329,25 @@ export declare function resolveAreaUuid(db: DatabaseSync, ref: string, options?:
 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;
+/**
+ * The uuid of a repeating template's LATEST spawned instance, or null when the
+ * template has none. The GUI-verified "Show Latest" law (SL1,
+ * docs/lab/sl1-show-latest.md, 2026-07-29): the pick is `max(creationDate)`
+ * among the template's instances — the most recently spawned occurrence — and
+ * NOTHING else. It is INDEPENDENT of `startDate`, `userModificationDate`,
+ * `stopDate`, and completion `status`: a completed newest-spawned instance is
+ * still the latest (the SL1 D1 case). No status filter; spans both to-do and
+ * project instances (`rt1_repeatingTemplate` points at the template regardless
+ * of type). `creationDate` is the occurrence midnight and unique per occurrence
+ * for a normal series, so ties are not expected.
+ *
+ * TRASHED instances are EXCLUDED (SL2, docs/lab/sl2-trash-dynamics.md, law L1):
+ * the GUI Show Latest never selects a trashed instance — it skips to the newest
+ * UNTRASHED one, and re-resolves live after an empty-trash. Only `trashed` is
+ * filtered; `status` is NOT (a COMPLETED newest-spawned instance is still the
+ * latest — SL1 D1). A template with no untrashed instances derives `null`.
+ */
+export declare function latestInstanceUuid(db: DatabaseSync, templateUuid: string): string | null;
 export declare function fetchChecklistRows(db: DatabaseSync, taskUuid: string): ChecklistRow[];
 /**
  * Direct tags for a set of tasks, in one query. Returns uuid -> Ref[] in the
@@ -236,3 +391,4 @@ export declare function fetchTagsForTasks(db: DatabaseSync, taskUuids: string[])
 export declare function makeHeadingProjectResolver(db: DatabaseSync): (headingUuid: string) => Ref | null;
 /** Lazy uuid -> Ref resolver over TMTask + TMArea titles, cached per instance. */
 export declare function makeRefResolver(db: DatabaseSync): (uuid: string | null) => Ref | null;
+export {};