things-api 0.10.0 → 0.12.0

package/dist/read/project-view.js

@@ -11,15 +11,36 @@ export class ProjectNotFoundError extends Error {
         this.name = "ProjectNotFoundError";
     }
 }
-export function projectView(db, uuid, now, filter = {}) {
+/** Append `value` to the list at `key`, creating it on first use. */
+function pushInto(map, key, value) {
+    const list = map.get(key) ?? [];
+    list.push(value);
+    map.set(key, list);
+}
+/** Group scheduled rows into per-day buckets (date ASC, within-day todayIndex ASC). */
+function groupByDate(rows) {
+    const out = [];
+    for (const { date, todo } of rows.toSorted((a, b) => a.date.localeCompare(b.date) || a.ti - b.ti)) {
+        const last = out[out.length - 1];
+        if (last && last.date === date)
+            last.items.push(todo);
+        else
+            out.push({ date, items: [todo] });
+    }
+    return out;
+}
+export function projectView(db, uuid, now, filter = {}, zone) {
     const overdue = filter.overdue === true;
     const projectRow = fetchTaskByUuid(db, uuid);
     if (!projectRow || projectRow.type !== 1)
         throw new ProjectNotFoundError(uuid);
     const refs = makeRefResolver(db);
+    // The view's injected clock — gates `todaySection` to Today members in the
+    // mapper AND drives the scheduled/overdue bucketing below.
+    const packedToday = encodePackedDate(localToday(now, zone));
     const tagsOf = (rows) => fetchTagsForTasks(db, rows.map((r) => r.uuid));
     const projectTags = tagsOf([projectRow]);
-    const project = mapProject(projectRow, refs, projectTags.get(projectRow.uuid) ?? []);
+    const project = mapProject(projectRow, refs, projectTags.get(projectRow.uuid) ?? [], packedToday);
     // The card view surfaces area-inherited tags (the UI's tag filter honors them).
     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]);
@@ -30,7 +51,7 @@ export function projectView(db, uuid, now, filter = {}) {
     // 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))] : [];
+    const overdueBinds = overdue ? [encodePackedDate(localToday(now, zone))] : [];
     // 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;
@@ -40,36 +61,46 @@ export function projectView(db, uuid, now, filter = {}) {
     // 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 (
+    const childRows = fetchTaskRows(db, `t.type = 0 AND t.trashed = 0 AND (t.project = ? OR t.heading IN (
        SELECT uuid FROM TMTask WHERE type = 2 AND project = ?
      ))${tf.sql}${overdueSql}
      ORDER BY t."index" ASC`, [uuid, uuid, ...tf.binds, ...overdueBinds]);
     const childTags = tagsOf(childRows);
-    const boundary = logBoundary(db, now);
+    const boundary = logBoundary(db, now, zone);
     const todos = childRows.map((r) => ({
         row: r,
-        todo: mapTodo(r, refs, childTags.get(r.uuid) ?? []),
+        todo: mapTodo(r, refs, childTags.get(r.uuid) ?? [], packedToday),
     }));
     markLogged([project, ...todos.map((t) => t.todo)], boundary);
-    const packedToday = encodePackedDate(localToday(now));
+    // Project-level (UNHEADED) buckets.
     const active = [];
-    const byHeading = new Map();
     const scheduledRows = [];
     const repeating = [];
     const someday = [];
     const logged = [];
-    const trashed = [];
+    // Per-heading sub-buckets, keyed by heading uuid (§9 fidelity fix): a headed
+    // scheduled/someday/repeating child nests under its heading, NOT at the
+    // project level.
+    const headingItems = new Map();
+    const headingScheduled = new Map();
+    const headingSomeday = new Map();
+    const headingRepeating = new Map();
+    // Known (fetched, untrashed) headings — a child whose heading FK is not one
+    // of these falls back to the project-level (unheaded) buckets rather than
+    // vanishing (mirrors the render's historical loose fallback).
+    const headingSet = new Set(headings.map((h) => h.uuid));
+    const headingUuidOf = (row) => row.heading !== null && headingSet.has(row.heading) ? row.heading : null;
     // 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);
-            continue;
-        }
+        const h = headingUuidOf(row);
         if (todo.repeating.isTemplate) {
-            repeating.push(todo);
+            if (h !== null)
+                pushInto(headingRepeating, h, todo);
+            else
+                repeating.push(todo);
             continue;
         }
         if (row.status === 0)
@@ -82,61 +113,65 @@ export function projectView(db, uuid, now, filter = {}) {
                 logged.push(todo);
                 continue;
             }
-            if (row.heading) {
-                const list = byHeading.get(row.heading) ?? [];
-                list.push(todo);
-                byHeading.set(row.heading, list);
-            }
-            else {
+            if (h !== null)
+                pushInto(headingItems, h, todo);
+            else
                 active.push(todo);
-            }
             continue;
         }
         if (row.start === 2 && row.startDate === null) {
-            someday.push(todo);
+            if (h !== null)
+                pushInto(headingSomeday, h, todo);
+            else
+                someday.push(todo);
             continue;
         }
         if (row.startDate !== null && row.startDate > packedToday) {
-            scheduledRows.push({
+            const sr = {
                 date: decodePackedDate(row.startDate) ?? "",
                 ti: row.todayIndex ?? 0,
                 todo,
-            });
-            continue;
-        }
-        if (row.heading) {
-            const list = byHeading.get(row.heading) ?? [];
-            list.push(todo);
-            byHeading.set(row.heading, list);
+            };
+            if (h !== null)
+                pushInto(headingScheduled, h, sr);
+            else
+                scheduledRows.push(sr);
             continue;
         }
-        active.push(todo);
+        if (h !== null)
+            pushInto(headingItems, h, todo);
+        else
+            active.push(todo);
     }
     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.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] });
-    }
+    const scheduled = groupByDate(scheduledRows);
     // 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).
+    // section; a heading with any surviving child (in ANY sub-bucket) 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);
+        .map((heading) => ({
+        heading,
+        items: headingItems.get(heading.uuid) ?? [],
+        scheduled: groupByDate(headingScheduled.get(heading.uuid) ?? []),
+        someday: headingSomeday.get(heading.uuid) ?? [],
+        repeating: headingRepeating.get(heading.uuid) ?? [],
+    }))
+        .filter((g) => !contentScoped ||
+        g.items.length > 0 ||
+        g.scheduled.length > 0 ||
+        g.someday.length > 0 ||
+        g.repeating.length > 0);
     return {
         project,
         active,
         headings: headingGroups,
-        later: { scheduled, repeating, someday },
+        scheduled,
+        someday,
+        repeating,
         logged,
-        trashed,
         openChildrenWhileResolved: project.status === "open" ? 0 : openChildren,
     };
 }

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/pseudo-area.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The `loose` pseudo-area: a reserved, case-insensitive ref that addresses the
+ * NULL area (area-less items) as if it were an area, on READ surfaces only. It
+ * mirrors the GUI sidebar's leading loose block — area-less projects, then loose
+ * direct to-dos — plus the "Later Projects" someday/scheduled block under
+ * `--show-later`. The reserved word ALWAYS wins over a real area that happens to
+ * be named "Loose" (that area is reachable only by uuid); when one shadows, the
+ * read surfaces a resolution disclosure. Every WRITE verb and the `open` command
+ * refuse the reserved word by name — the pseudo-area is a derived view, not a
+ * mutable container.
+ */
+import type { DatabaseSync } from "node:sqlite";
+/** The reserved ref (lowercase canonical form) that names the loose pseudo-area. */
+export declare const LOOSE_REF = "loose";
+/** True when a ref names the reserved `loose` pseudo-area (case-insensitive, trimmed). */
+export declare function isLooseRef(ref: string): boolean;
+/**
+ * The uuid of a real area whose title case-insensitively equals the reserved
+ * word, if any — for the resolution-shadow disclosure. Lowest sidebar index
+ * wins on the (pathological) chance of duplicates. Returns undefined when no
+ * real area shadows the reserved word.
+ */
+export declare function shadowingLooseArea(db: DatabaseSync): string | undefined;
+/** The disclosure appended to a loose read when a real area shadows the reserved word. */
+export declare function looseShadowNotice(uuid: string): string;
+/** Refusal for opening the loose pseudo-area — it is a derived view, not an app screen. */
+export declare const LOOSE_OPEN_REFUSAL = "the loose pseudo-area is a derived view \u2014 it cannot be opened; open a specific project or area by ref";
+/** Refusal for `--to-area loose` — the reserved word is a read-only view, not a destination. */
+export declare const LOOSE_TO_AREA_REFUSAL = "the loose pseudo-area is a derived view \u2014 it cannot be modified; to leave a to-do area-less use --loose (a project: --no-area), or target a real area named \"Loose\" by uuid";

package/dist/read/pseudo-area.js

@@ -0,0 +1,27 @@
+/** The reserved ref (lowercase canonical form) that names the loose pseudo-area. */
+export const LOOSE_REF = "loose";
+/** True when a ref names the reserved `loose` pseudo-area (case-insensitive, trimmed). */
+export function isLooseRef(ref) {
+    return ref.trim().toLowerCase() === LOOSE_REF;
+}
+/**
+ * The uuid of a real area whose title case-insensitively equals the reserved
+ * word, if any — for the resolution-shadow disclosure. Lowest sidebar index
+ * wins on the (pathological) chance of duplicates. Returns undefined when no
+ * real area shadows the reserved word.
+ */
+export function shadowingLooseArea(db) {
+    const row = db
+        .prepare(`SELECT uuid FROM TMArea WHERE lower(title) = ? ORDER BY "index" ASC LIMIT 1`)
+        .get(LOOSE_REF);
+    return row?.uuid;
+}
+/** The disclosure appended to a loose read when a real area shadows the reserved word. */
+export function looseShadowNotice(uuid) {
+    return `resolved to the loose pseudo-area; an area named "Loose" exists (uuid ${uuid}) — target it by uuid`;
+}
+/** Refusal for opening the loose pseudo-area — it is a derived view, not an app screen. */
+export const LOOSE_OPEN_REFUSAL = "the loose pseudo-area is a derived view — it cannot be opened; open a specific project or area by ref";
+/** Refusal for `--to-area loose` — the reserved word is a read-only view, not a destination. */
+export const LOOSE_TO_AREA_REFUSAL = 'the loose pseudo-area is a derived view — it cannot be modified; to leave a to-do area-less use --loose (a project: --no-area), or target a real area named "Loose" by uuid';
+//# sourceMappingURL=pseudo-area.js.map

package/dist/read/pseudo-area.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pseudo-area.js","sourceRoot":"","sources":["../../src/read/pseudo-area.ts"],"names":[],"mappings":"AAaA,oFAAoF;AACpF,MAAM,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC;AAEjC,0FAA0F;AAC1F,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAgB;IACjD,MAAM,GAAG,GAAG,EAAE;SACX,OAAO,CAAC,6EAA6E,CAAC;SACtF,GAAG,CAAC,SAAS,CAAiC,CAAC;IAClD,OAAO,GAAG,EAAE,IAAI,CAAC;AACnB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,yEAAyE,IAAI,uBAAuB,CAAC;AAC9G,CAAC;AAED,2FAA2F;AAC3F,MAAM,CAAC,MAAM,kBAAkB,GAC7B,uGAAuG,CAAC;AAE1G,gGAAgG;AAChG,MAAM,CAAC,MAAM,qBAAqB,GAChC,6KAA6K,CAAC"}

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 } 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).
@@ -147,7 +155,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,11 +181,30 @@ 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;
 /**
  * Write destinations stay strict (a trashed project is not a valid target);
@@ -173,10 +214,37 @@ export declare function resolveTagUuid(db: DatabaseSync, ref: string): string;
 export declare function resolveProjectUuid(db: DatabaseSync, ref: string, options?: {
     trashed?: boolean;
     prefixTier?: boolean;
+    scopeWhere?: string;
+    scopeBinds?: (string | 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;
+};
 /**
  * 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 +261,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
@@ -229,7 +316,9 @@ export declare function fetchTagsForTasks(db: DatabaseSync, taskUuids: string[])
 /**
  * Lazy heading-uuid -> owning-project Ref resolver, cached per instance.
  * Heading-nested to-dos carry project = NULL in the DB (the heading holds
- * the link); list views use this to surface the GUI's container label.
+ * the link); list views use this to surface the GUI's container label. The
+ * owning project's recurrence columns ride along so a to-do nested under a
+ * heading of a repeating-template project inherits the template mark.
  */
 export declare function makeHeadingProjectResolver(db: DatabaseSync): (headingUuid: string) => Ref | null;
 /** Lazy uuid -> Ref resolver over TMTask + TMArea titles, cached per instance. */