things-api 0.11.0 → 0.13.0

package/dist/read/scope.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Container-scoped sandbox — the ONE membership relation, shared by reads,
+ * writes, and reference resolution. Generalizes the `--area` post-filter
+ * (`area-filter.ts`) from "one area" to "one container" (an area OR a project),
+ * and adds the leak-critical SQL fragments the single-row / candidate paths and
+ * the write ancestry check share so an out-of-scope item is indistinguishable
+ * from a nonexistent one (the no-oracle guarantee — see
+ * docs/design/container-scope.md).
+ *
+ * A scope is resolved ONCE at `openThings()` and pinned for the client's life
+ * (never re-resolved per call — a deleted container becomes a safe empty jail,
+ * a recreated same-named one never silently re-binds). Every read reaches the
+ * consumer through `client.read.*` and every write through `runMutation`, so the
+ * two forms below (the entity predicate `inScopeItem` and the SQL fragments) are
+ * the only two places the relation is expressed.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { AnyTask } from "../model/entities.ts";
+import { ReferenceResolutionError } from "./queries.ts";
+import type { ListItem, SidebarSection, TodayView } from "./views.ts";
+import type { IsoDate } from "../model/dates.ts";
+/** Where a scope declaration came from — surfaced as `meta.scope.source`. */
+export type ScopeSource = "flag" | "env" | "config";
+/**
+ * A resolved container scope: pinned at open, carried on the client. `kind`
+ * distinguishes an area jail from a project jail; `uuid`/`title` name the
+ * container; `areaUuid` is the containing area (the scope area itself for an
+ * area scope; the project's own area — or null for an area-less project — for a
+ * project scope), used to scope the `areas` view and area-ref resolution.
+ */
+export interface ResolvedScope {
+    kind: "area" | "project";
+    uuid: string;
+    title: string;
+    source: ScopeSource;
+    /** The relevant area context (area scope: itself; project scope: the project's area, null if area-less). */
+    areaUuid: string | null;
+}
+/** The `meta.scope` wire shape (a subset of {@link ResolvedScope}). */
+export interface ScopeMeta {
+    kind: "area" | "project";
+    uuid: string;
+    title: string;
+    source: ScopeSource;
+}
+/**
+ * Fail-closed if a requested scope is unresolvable — `things mcp --scope <bogus>`
+ * refuses to start, a CLI invocation errors as usage — so the daemon never runs
+ * unscoped when a scope was asked for. A subclass of {@link ReferenceResolutionError}
+ * so existing usage-class handlers treat it uniformly.
+ */
+export declare class ScopeResolutionError extends ReferenceResolutionError {
+    constructor(message: string, ref: string);
+}
+/**
+ * Resolve a scope ref (uuid, uuid-prefix, or unique area/project name) to a
+ * pinned {@link ResolvedScope}. Areas win over same-named projects (mirroring
+ * `classifyShowTarget`). A to-do / heading / tag ref is a usage error — only an
+ * area or a project can be a container. Fail-closed: an unresolvable ref throws
+ * {@link ScopeResolutionError}.
+ */
+export declare function resolveScope(db: DatabaseSync, ref: string, source: ScopeSource): ResolvedScope;
+/** The `meta.scope` projection of a resolved scope (drops the internal `areaUuid`). */
+export declare function scopeMeta(scope: ResolvedScope): ScopeMeta;
+/**
+ * The entity-level membership predicate — the SAME relation as
+ * {@link scopeMembershipSql}, for an already-shaped view row. Area scope: the
+ * row's EFFECTIVE area is the scope (its `area` Ref, which queries.ts already
+ * resolves transitively). Project scope: the row IS the project, is a direct
+ * child, or is nested under one of the project's headings.
+ */
+export declare function inScopeItem(item: ListItem | AnyTask, scope: ResolvedScope): boolean;
+/**
+ * The SQL fragment on alias `t` — the single membership source the leak-critical
+ * query paths AND the write ancestry check share. Area: the effective-area
+ * COALESCE equals the scope. Project: the row is the project, its direct child,
+ * or a heading-nested child.
+ */
+export declare function scopeMembershipSql(scope: ResolvedScope): {
+    where: string;
+    binds: string[];
+};
+/** True when the given uuid is an in-scope TMTask row (single-row leak paths, write parity). */
+export declare function isUuidInScope(db: DatabaseSync, uuid: string, scope: ResolvedScope): boolean;
+/**
+ * The membership clause for {@link resolveTaskUuidPrefix} (alias `t`): the same
+ * fragment as {@link scopeMembershipSql}, so an out-of-scope uuid resolves to
+ * "not found" through the identical code path a nonexistent one does.
+ */
+export declare function taskMembershipClause(scope: ResolvedScope): {
+    where: string;
+    binds: string[];
+};
+/**
+ * The membership clause for {@link resolveNamedRef} over TMTask projects
+ * (UNqualified columns — that resolver aliases nothing). A project carries its
+ * area directly (no inheritance), so area scope compares `area`; project scope
+ * pins the one project uuid.
+ */
+export declare function namedProjectClause(scope: ResolvedScope): {
+    where: string;
+    binds: string[];
+};
+/**
+ * The membership clause for {@link resolveNamedRef} over TMArea (UNqualified).
+ * Area scope: the one scope area. Project scope: the project's own area (an
+ * area-less project has none, so nothing resolves — `0`).
+ */
+export declare function namedAreaClause(scope: ResolvedScope): {
+    where: string;
+    binds: string[];
+};
+/** Filter a flat view (upcoming/logbook/trash/search/changes) to in-scope rows. */
+export declare function filterListByScope<T extends ListItem>(items: T[], scope: ResolvedScope): T[];
+/**
+ * Filter the grouped sidebar catalogue (anytime/someday) to in-scope rows: each
+ * section's items are filtered and empty sections drop, so the per-block caps
+ * size the survivors.
+ */
+export declare function filterSectionsByScope(sections: SidebarSection[], scope: ResolvedScope): SidebarSection[];
+/**
+ * Filter the today view to in-scope rows, RECOMPUTING the counts over the
+ * surviving OPEN members so they never count a dropped (out-of-scope) row — the
+ * same treatment `filterTodayByArea` gives the area filter.
+ */
+export declare function filterTodayByScope(view: TodayView, scope: ResolvedScope, todayIso: IsoDate): TodayView;

package/dist/read/scope.js

@@ -0,0 +1,161 @@
+import { EFFECTIVE_AREA, ReferenceResolutionError, resolveAreaUuid, resolveProjectUuid, } from "./queries.js";
+/**
+ * Fail-closed if a requested scope is unresolvable — `things mcp --scope <bogus>`
+ * refuses to start, a CLI invocation errors as usage — so the daemon never runs
+ * unscoped when a scope was asked for. A subclass of {@link ReferenceResolutionError}
+ * so existing usage-class handlers treat it uniformly.
+ */
+export class ScopeResolutionError extends ReferenceResolutionError {
+    constructor(message, ref) {
+        super(message, { code: "not-found", ref });
+        this.name = "ScopeResolutionError";
+    }
+}
+/**
+ * Resolve a scope ref (uuid, uuid-prefix, or unique area/project name) to a
+ * pinned {@link ResolvedScope}. Areas win over same-named projects (mirroring
+ * `classifyShowTarget`). A to-do / heading / tag ref is a usage error — only an
+ * area or a project can be a container. Fail-closed: an unresolvable ref throws
+ * {@link ScopeResolutionError}.
+ */
+export function resolveScope(db, ref, source) {
+    // Area first (an area outranks a same-named project, like the show router).
+    try {
+        const uuid = resolveAreaUuid(db, ref, { prefixTier: false });
+        const row = db.prepare("SELECT title FROM TMArea WHERE uuid = ?").get(uuid);
+        return { kind: "area", uuid, title: row?.title ?? "", source, areaUuid: uuid };
+    }
+    catch (err) {
+        // An ambiguous area name is a real conflict — surface it. A plain not-found
+        // falls through to project resolution.
+        if (err instanceof RangeError && err.message.includes("matches")) {
+            throw new ScopeResolutionError(`scope "${ref}" is ambiguous — ${err.message}`, ref);
+        }
+    }
+    try {
+        const uuid = resolveProjectUuid(db, ref, { prefixTier: false });
+        const row = db.prepare("SELECT title, area FROM TMTask WHERE uuid = ?").get(uuid);
+        return {
+            kind: "project",
+            uuid,
+            title: row?.title ?? "",
+            source,
+            areaUuid: row?.area ?? null,
+        };
+    }
+    catch (err) {
+        if (err instanceof RangeError && err.message.includes("matches")) {
+            throw new ScopeResolutionError(`scope "${ref}" is ambiguous — ${err.message}`, ref);
+        }
+    }
+    throw new ScopeResolutionError(`scope "${ref}" matches no area or project — a scope must name a container (only areas and ` +
+        "projects can be a container; to-dos, headings, and tags cannot)", ref);
+}
+/** The `meta.scope` projection of a resolved scope (drops the internal `areaUuid`). */
+export function scopeMeta(scope) {
+    return { kind: scope.kind, uuid: scope.uuid, title: scope.title, source: scope.source };
+}
+/**
+ * The entity-level membership predicate — the SAME relation as
+ * {@link scopeMembershipSql}, for an already-shaped view row. Area scope: the
+ * row's EFFECTIVE area is the scope (its `area` Ref, which queries.ts already
+ * resolves transitively). Project scope: the row IS the project, is a direct
+ * child, or is nested under one of the project's headings.
+ */
+export function inScopeItem(item, scope) {
+    if (scope.kind === "area") {
+        const area = "area" in item ? item.area : null;
+        return area != null && area.uuid === scope.uuid;
+    }
+    const p = scope.uuid;
+    if (item.uuid === p)
+        return true;
+    const project = "project" in item ? item.project : null;
+    if (project != null && project.uuid === p)
+        return true;
+    const hp = "headingProject" in item ? item.headingProject : undefined;
+    if (hp != null && hp.uuid === p)
+        return true;
+    return false;
+}
+/**
+ * The SQL fragment on alias `t` — the single membership source the leak-critical
+ * query paths AND the write ancestry check share. Area: the effective-area
+ * COALESCE equals the scope. Project: the row is the project, its direct child,
+ * or a heading-nested child.
+ */
+export function scopeMembershipSql(scope) {
+    if (scope.kind === "area") {
+        return { where: `${EFFECTIVE_AREA} = ?`, binds: [scope.uuid] };
+    }
+    return {
+        where: "(t.uuid = ? OR t.project = ? OR t.heading IN " +
+            "(SELECT uuid FROM TMTask WHERE type = 2 AND project = ?))",
+        binds: [scope.uuid, scope.uuid, scope.uuid],
+    };
+}
+/** True when the given uuid is an in-scope TMTask row (single-row leak paths, write parity). */
+export function isUuidInScope(db, uuid, scope) {
+    const mem = scopeMembershipSql(scope);
+    const row = db
+        .prepare(`SELECT 1 AS ok FROM TMTask t WHERE t.uuid = ? AND ${mem.where} LIMIT 1`)
+        .get(uuid, ...mem.binds);
+    return row !== undefined;
+}
+/**
+ * The membership clause for {@link resolveTaskUuidPrefix} (alias `t`): the same
+ * fragment as {@link scopeMembershipSql}, so an out-of-scope uuid resolves to
+ * "not found" through the identical code path a nonexistent one does.
+ */
+export function taskMembershipClause(scope) {
+    return scopeMembershipSql(scope);
+}
+/**
+ * The membership clause for {@link resolveNamedRef} over TMTask projects
+ * (UNqualified columns — that resolver aliases nothing). A project carries its
+ * area directly (no inheritance), so area scope compares `area`; project scope
+ * pins the one project uuid.
+ */
+export function namedProjectClause(scope) {
+    if (scope.kind === "area")
+        return { where: "area = ?", binds: [scope.uuid] };
+    return { where: "uuid = ?", binds: [scope.uuid] };
+}
+/**
+ * The membership clause for {@link resolveNamedRef} over TMArea (UNqualified).
+ * Area scope: the one scope area. Project scope: the project's own area (an
+ * area-less project has none, so nothing resolves — `0`).
+ */
+export function namedAreaClause(scope) {
+    if (scope.kind === "area")
+        return { where: "uuid = ?", binds: [scope.uuid] };
+    return scope.areaUuid === null
+        ? { where: "0", binds: [] }
+        : { where: "uuid = ?", binds: [scope.areaUuid] };
+}
+/** Filter a flat view (upcoming/logbook/trash/search/changes) to in-scope rows. */
+export function filterListByScope(items, scope) {
+    return items.filter((i) => inScopeItem(i, scope));
+}
+/**
+ * Filter the grouped sidebar catalogue (anytime/someday) to in-scope rows: each
+ * section's items are filtered and empty sections drop, so the per-block caps
+ * size the survivors.
+ */
+export function filterSectionsByScope(sections, scope) {
+    return sections
+        .map((s) => ({ area: s.area, items: s.items.filter((i) => inScopeItem(i, scope)) }))
+        .filter((s) => s.items.length > 0);
+}
+/**
+ * Filter the today view to in-scope rows, RECOMPUTING the counts over the
+ * surviving OPEN members so they never count a dropped (out-of-scope) row — the
+ * same treatment `filterTodayByArea` gives the area filter.
+ */
+export function filterTodayByScope(view, scope, todayIso) {
+    const items = view.items.filter((i) => inScopeItem(i, scope));
+    const open = items.filter((i) => i.status === "open");
+    const dueOrOverdue = open.filter((i) => i.deadline !== null && i.deadline <= todayIso).length;
+    return { items, counts: { dueOrOverdue, other: open.length - dueOrOverdue } };
+}
+//# sourceMappingURL=scope.js.map

package/dist/read/scope.js.map

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

package/dist/read/search-rank.d.ts

@@ -18,12 +18,9 @@ import type { ListItem } from "./views.ts";
 export type MatchField = "title" | "notes" | "heading" | "checklist";
 export interface SearchMatch {
     item: ListItem;
+    /** The RANK field (strongest match by rank order); the displayed provenance
+     * annotation rides the item as `match` and follows its own precedence. */
     field: MatchField;
-    /** Present when `field === "heading"`: the heading whose title matched. */
-    matchedVia?: {
-        kind: "heading";
-        title: string;
-    };
 }
 export declare function fieldRank(field: MatchField): number;
 /** Containers (projects, areas) sort above to-dos. */

package/dist/read/shape.d.ts

@@ -0,0 +1,181 @@
+/**
+ * The read-payload SHAPING transform: the token-economy rules R6 and R7, the
+ * universal item-DTO reshapes (R9), and the R10 lifecycle taxonomy — applied at
+ * the JSON emit boundary of the read surfaces (the CLI `--json` read envelope,
+ * src/cli/read-driver.ts, and the MCP read tool results, src/mcp/server.ts), the
+ * same boundaries omit-empty runs at. Shaping runs BEFORE omit-empty. The
+ * human-render path keeps the full, unshaped entities, so this is JSON-only.
+ *
+ * Both R6/R7 are deterministic BY VIEW KIND / SECTION — the emitter knows whether
+ * it is inside a single-container view, a lifecycle bucket, or a mixed list —
+ * never a per-item heuristic.
+ *
+ * ## R10 — the `stage` lifecycle taxonomy (every tier, every kind incl. detail)
+ * The three former wire fields `start` / `logged` / `trashed` are DELETED from
+ * every item and replaced by ONE derived `stage` ∈ `inbox | upcoming | anytime |
+ * someday | logbook | trash` (src/read/stage.ts `deriveStage`, the single pure
+ * derivation reused by the card bucketing so `stage` can never disagree with the
+ * bucket a view puts an item in). Today/evening membership is a SEPARATE
+ * presence-keyed axis — `today: true` / `evening: true` (evening implies today) —
+ * derived in the mapper with the Today view's own two-arm predicate.
+ * - `stage` is DROPPED only where the enclosing node PROVABLY states it — the R6
+ *   rule (drop only what the node provably says). That is the stage-PURE flat
+ *   views (inbox, `anytime`, someday, logbook, trash) and the stage-named card
+ *   sub-buckets (anytime/upcoming/someday/logbook/trash, which the bucketer splits
+ *   BY stage). The `anytime` catalogue is stage-PURE (R10.2): every member is an
+ *   Anytime-view row (ANYTIME_SELF) — undated-active, arrived-active, or arrived
+ *   someday-scheduled — and an ARRIVED dated row derives `anytime` (Upcoming is
+ *   STRICTLY FUTURE, UPC1), so the field is redundant there.
+ *   `stage` is KEPT on the stage-MIXED or derived surfaces: the `upcoming` view
+ *   carries deadline-forecast stage-`anytime`/`someday` rows alongside its
+ *   future-dated stage-`upcoming` ones — dropping `stage` there would delete
+ *   non-redundant information — plus `today` (mixes upcoming + anytime-deadline
+ *   rows), search, changes, the projects/areas listings, the card NODE, and
+ *   detail.
+ * - the former `todaySection` field is RETIRED from the wire entirely (R10.1):
+ *   `todaySection: "evening"` merely duplicated the `evening: true` marker. It
+ *   remains an internal entity field (the human render and the write-verify delta
+ *   still read it); shaping deletes it from the JSON copy.
+ *
+ * ## R12 — `when`, the derived TIME-AXIS position (replaces startDate + markers)
+ * Today/evening membership and the scheduled/projected date collapse onto ONE
+ * derived, presence-keyed field `when` (src/read/stage.ts `deriveWhen`): `"today"`
+ * / `"evening"` (Today-view membership, from the SAME `today`/`evening` markers the
+ * mapper stamps — never re-derived, so `when` can never disagree with the star), a
+ * FUTURE ISO date (a strictly-future scheduled row, or a template's projected next
+ * occurrence), or absent (unscheduled + not in Today; also an unprojected template
+ * and every logged/trashed row). The doctrine line: **`stage` enumerates the
+ * sidebar BUCKETS an item lives in; `when` enumerates its TIME POSITIONS (today |
+ * evening | a future date).** Someday is deliberately NOT a `when` value (it is a
+ * bucket → stage). Tier/drop rules:
+ * - the former `today`/`evening` marker KEYS are DELETED from the wire on EVERY
+ *   tier — `when` carries the fact; the markers stay internal (they feed `when`).
+ * - the raw `startDate` is DELETED in COMPACT (a list needs the position, not the
+ *   substrate) and KEPT in FULL/DETAIL beside `when` — different facts: `startDate`
+ *   = what is stored, `when` = where it sits.
+ * - a template's `repeating.nextOccurrence` is GONE from the wire — `when` replaces
+ *   it (same fact, one word); an unprojected template has no `when`.
+ * - `when` is KEPT on every row it is present on. (The read-shape doctrine
+ *   flattened the card `upcoming` date-groups into the project-/area-view flat
+ *   `items[]`, so no enclosing node states the position anymore.) It rides the
+ *   today view's flat `items[]` (Today-proper vs This-Evening), the project-/area-
+ *   view `items[]`, and the flat `upcoming`/`anytime`/`inbox`/`someday` catalogues,
+ *   search, changes (a deadline-pulled row reads `when: "today"` in the mixed
+ *   search/changes surfaces, informatively; note R13 re-files it to stage `anytime`
+ *   and the flat inbox/someday views now EXCLUDE it — it appears in the `anytime`
+ *   catalogue instead, `when: "today"` kept, stage dropped as pure).
+ *
+ * ## R13 — provisional Today members + GUI-faithful pulled-row membership
+ * BANNER1 / BANNER1b (docs/lab/banner1-research.md). Two coupled facts:
+ * - **`provisional: true`** — a presence-keyed marker on every Today member the GUI
+ *   pips / counts in the "You have N new to-dos" banner: a Today member NOT yet
+ *   materialized (`start != active OR startDate IS NULL`, BANNER1 L1). Derived from
+ *   the SAME today/evening markers + fields the stage/`when` axes use (never
+ *   re-derived). Emitted on EVERY tier, NEVER dropped (the banner is not a section,
+ *   so no node implies it). Absent on non-Today rows and on materialized ones.
+ *   Read-only: the app clears it by materializing the row on banner-OK, a GUI-only
+ *   side effect our read cannot perform (watchers beware).
+ * - **stage `anytime` for a deadline pull** — a due-deadline pull re-files an undated
+ *   Inbox/Someday row into Anytime (deriveStage step 2½, L-A). So EVERY Today member
+ *   derives stage `anytime`, and the today view's flat `items[]` is stage-PURE →
+ *   `stage` is DROPPED there (TODAY_ITEM_DROP) while `when` is KEPT. The flat
+ *   someday/inbox views EXCLUDE pulled rows and the anytime view INCLUDES them
+ *   (src/read/views.ts + predicates.ts DEADLINE_PULLED) — GUI fidelity.
+ *
+ * ## Universal item-DTO reshapes (R9 — EVERY tier, EVERY read kind incl. detail)
+ * - **checklist nesting** — flat counts → presence-keyed `checklist: {open,total}`.
+ * - **todos counts** — a project's flat leaf-action counts → presence-keyed
+ *   `todos: {open, total}` (omit when total 0).
+ * - **repeating template/instance split (R11)** — the wire drops the
+ *   `isTemplate`/`isInstance` discriminators; key presence carries the fact. A
+ *   TEMPLATE keeps a nested `repeating: {paused?, deadlined?, rule?,
+ *   latestInstance?}` — the series object (rule config + backward pointer +
+ *   state flags); presence MEANS template. The forward pointer `nextOccurrence`
+ *   moved to the top-level `when` (R12 — a template's projected date IS its time
+ *   position); `latestInstance` is detail-only (SL1). An INSTANCE keeps a flat
+ *   `instanceOf: <templateUuid>` and no `repeating`. A plain row keeps neither.
+ *   See {@link reshapeRepeatingWire}.
+ * - **string tags** — `tags`/`inheritedTags` become plain arrays of names.
+ * - **one project key** — a headed item's owning project (formerly
+ *   `headingProject`) is merged into `project`; `headingProject` never appears.
+ *
+ * ## R6 — no-redundant-ancestry (both tiers)
+ * project-view children drop `project`+`area` (heading-group members also drop
+ * `heading`); area-view children/project-cards drop `area`; anytime/someday
+ * section items drop `area`. Mixed lists keep every ref. (In the COMPACT tier the
+ * `heading` ref is additionally dropped everywhere — R7.)
+ *
+ * ## R7 — named detail tiers (compact | full)
+ * List contexts default to COMPACT; `detail`/`show` and `--full` / `full:true`
+ * use FULL. Compact drops `created`/`modified`, the full `notes` string (a
+ * presence-keyed `hasNotes: true` marks a row with notes), and the `heading` ref;
+ * `status` is omitted when `open`. FULL keeps them but still applies R6, the
+ * universal reshapes, and R10.
+ */
+import { type Stage, type When } from "./stage.ts";
+/** The container-ref kinds whose bare title is round-trip-tested for uuid promotion. */
+export type RefKind = "area" | "project" | "heading";
+/**
+ * The emit-side promotion oracle: does a container ref's bare TITLE round-trip
+ * through its own resolver, in its own scope, back to THIS entity? Built by
+ * {@link makeRefPromoter} (src/read/queries.ts) over the live DB — it runs the
+ * REAL resolution path for the kind (areas = all areas; projects = the live+open
+ * write-target pool, uuid-prefix tier first; headings = within `projectUuid`)
+ * and returns true only when the sole resolution is this uuid; not-found or
+ * ambiguous is false. Memoized per (kind, title, scope) within one response
+ * emission. When a promoter is absent (a DB-less unit shaping), the default
+ * assumes every title round-trips — bare titles, no uuid siblings.
+ */
+export interface RefPromoter {
+    roundTrips(kind: RefKind, title: string, entityUuid: string, projectUuid?: string): boolean;
+}
+/**
+ * Apply the universal reshapes + R6 + R7 + R10 to a read payload for one view
+ * `kind`. `full` forces the FULL tier (R7 default-pruning off, everything else
+ * applied); an unrecognized kind passes through unchanged. The input is never
+ * mutated (shallow copies throughout), so the human-render path keeps the full
+ * entities.
+ */
+export declare function shapeReadPayload(kind: string, data: unknown, full: boolean, promoter?: RefPromoter): unknown;
+/** The disambiguation-candidate kinds an error may list (a subset of the entity kinds). */
+export type CandidateType = "to-do" | "project" | "heading" | "area" | "tag";
+/**
+ * The ONE fixed error-candidate shape — the presence-keyed disambiguation DTO a
+ * not-found / ambiguous resolution lists under `error.detail.candidates` (and the
+ * did-you-mean fallback under the same key). Deliberately minimal and INVARIANT
+ * across request flags: `--full` / `--all` / etc. NEVER widen it, because an
+ * error payload is the most determinism-critical surface. A candidate carries
+ * ONLY material that helps a caller pick the right entity, drawn from the SAME
+ * single-source derivations the read wire uses — never the raw internal entity
+ * (no counts, no notes, no dates, no null-stuffed keys):
+ * - `uuid` / `title` — always present.
+ * - `type` — names the kind, EXCEPT to-do: absent `type` = to-do (present for
+ *   `project` / `heading` / `area` / `tag`), the same convention the item wire uses.
+ * - `area` / `project` — container hint as a TITLE string, present only when set.
+ * - `stage` / `when` — the R10/R12 lifecycle words, present only for a to-do /
+ *   project candidate whose source row carries the materialized lifecycle fields
+ *   (a thin uuid+title resolver row carries neither — presence-keyed, so absent).
+ * A trashed / logged candidate needs no boolean: `stage` already reads `"trash"`
+ * / `"logbook"` for it — the same vocabulary the wire uses.
+ */
+export interface CandidateRef {
+    uuid: string;
+    title: string;
+    /** The kind — omitted for a to-do (absent `type` = to-do), present otherwise. */
+    type?: CandidateType;
+    area?: string;
+    project?: string;
+    stage?: Stage;
+    when?: When;
+}
+/** The fixed cap on a listed candidate array; the error `message` states the total when it overflows. */
+export declare const CANDIDATE_CAP = 8;
+/**
+ * Project ONE entity — a materialized to-do/project/area/heading, or a thin
+ * `{uuid, title}` resolver row — to the fixed {@link CandidateRef}. The SINGLE
+ * source every error-candidate emit flows through (the did-you-mean fallback and
+ * every not-found/ambiguous resolver), so the candidate shape can never vary by
+ * site. Reuses the wire's own {@link stageOf}/{@link whenOf} derivations — the
+ * lifecycle words are never re-derived here.
+ */
+export declare function candidateRef(type: CandidateType, src: unknown): CandidateRef;