things-api 0.5.0

package/dist/read/queries.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Low-level row fetchers. Every SELECT names columns exclusively from the
+ * 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 { ChecklistRow, TaskRow } from "../model/mappers.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)";
+/**
+ * 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().
+ */
+export declare function tagScopeSql(uuidCount: number): string;
+export declare function tagScopeBinds(uuids: string[]): 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
+ * this way), not lab-oracled: the UI's filter clicks aren't automatable.
+ * UNION (not UNION ALL): dedupes, so a parent cycle in TMTag data can't
+ * recurse forever.
+ */
+export declare function tagWithDescendants(db: DatabaseSync, uuid: string): string[];
+/** Resolve a tag reference (uuid or unique case-insensitive title) — loud on miss. */
+export declare function resolveTagUuid(db: DatabaseSync, ref: string): string;
+/** Resolve a project reference (uuid or unique case-insensitive title) — loud on miss. */
+export declare function resolveProjectUuid(db: DatabaseSync, ref: string): string;
+/** Resolve an area reference (uuid or unique case-insensitive title) — loud on miss. */
+export declare function resolveAreaUuid(db: DatabaseSync, ref: string): string;
+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). */
+export declare function fetchTagsForTasks(db: DatabaseSync, taskUuids: string[]): Map<string, Ref[]>;
+/** Lazy uuid -> Ref resolver over TMTask + TMArea titles, cached per instance. */
+export declare function makeRefResolver(db: DatabaseSync): (uuid: string | null) => Ref | null;

package/dist/read/queries.js

@@ -0,0 +1,134 @@
+import { q, selectList } from "../db/schema.js";
+/** Rows that repeat via a template are normal; template rows are invisible in list views. */
+export 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().
+ */
+export function tagScopeSql(uuidCount) {
+    const set = `(${Array.from({ length: uuidCount }, () => "?").join(", ")})`;
+    return `(
+  EXISTS (SELECT 1 FROM TMTaskTag tt WHERE tt.tasks = t.uuid AND tt.tags IN ${set})
+  OR EXISTS (SELECT 1 FROM TMTaskTag tt WHERE tt.tasks = t.project AND tt.tags IN ${set})
+  OR EXISTS (SELECT 1 FROM TMAreaTag at WHERE at.areas = t.area AND at.tags IN ${set})
+  OR EXISTS (SELECT 1 FROM TMTask p JOIN TMAreaTag at ON at.areas = p.area
+             WHERE p.uuid = t.project AND at.tags IN ${set})
+  OR EXISTS (SELECT 1 FROM TMTask h JOIN TMTaskTag tt ON tt.tasks = h.project
+             WHERE h.uuid = t.heading AND tt.tags IN ${set})
+  OR EXISTS (SELECT 1 FROM TMTask h JOIN TMTask p ON p.uuid = h.project
+             JOIN TMAreaTag at ON at.areas = p.area WHERE h.uuid = t.heading AND at.tags IN ${set})
+)`;
+}
+export function tagScopeBinds(uuids) {
+    return Array.from({ length: 6 }, () => uuids).flat();
+}
+/**
+ * A tag plus every hierarchy descendant. Filtering by a parent tag matches
+ * child-tagged items — DOCUMENTED app behavior (the UI's tag filter works
+ * this way), not lab-oracled: the UI's filter clicks aren't automatable.
+ * UNION (not UNION ALL): dedupes, so a parent cycle in TMTag data can't
+ * recurse forever.
+ */
+export function tagWithDescendants(db, uuid) {
+    const rows = db
+        .prepare(`WITH RECURSIVE d(uuid) AS (
+         SELECT ? UNION
+         SELECT tg.uuid FROM TMTag tg JOIN d ON tg.parent = d.uuid
+       ) SELECT uuid FROM d`)
+        .all(uuid);
+    return rows.map((r) => r.uuid);
+}
+/** Resolve a tag reference (uuid or unique case-insensitive title) — loud on miss. */
+export function resolveTagUuid(db, ref) {
+    const byId = db.prepare("SELECT uuid FROM TMTag WHERE uuid = ?").get(ref);
+    if (byId !== undefined)
+        return byId.uuid;
+    const rows = db.prepare("SELECT uuid FROM TMTag WHERE title = ? COLLATE NOCASE").all(ref);
+    if (rows.length === 1 && rows[0] !== undefined)
+        return rows[0].uuid;
+    throw new RangeError(rows.length === 0
+        ? `tag not found: ${ref} (list tags with \`things tags\`)`
+        : `tag reference is ambiguous: ${ref} (${rows.length} matches — use the uuid)`);
+}
+/** Resolve a project reference (uuid or unique case-insensitive title) — loud on miss. */
+export function resolveProjectUuid(db, ref) {
+    const byId = db
+        .prepare("SELECT uuid FROM TMTask WHERE uuid = ? AND type = 1 AND trashed = 0")
+        .get(ref);
+    if (byId !== undefined)
+        return byId.uuid;
+    const rows = db
+        .prepare("SELECT uuid FROM TMTask WHERE title = ? COLLATE NOCASE AND type = 1 AND trashed = 0")
+        .all(ref);
+    if (rows.length === 1 && rows[0] !== undefined)
+        return rows[0].uuid;
+    throw new RangeError(rows.length === 0
+        ? `project not found: ${ref} (list projects with \`things projects\`)`
+        : `project reference is ambiguous: ${ref} (${rows.length} matches — use the uuid)`);
+}
+/** Resolve an area reference (uuid or unique case-insensitive title) — loud on miss. */
+export function resolveAreaUuid(db, ref) {
+    const byId = db.prepare("SELECT uuid FROM TMArea WHERE uuid = ?").get(ref);
+    if (byId !== undefined)
+        return byId.uuid;
+    const rows = db.prepare("SELECT uuid FROM TMArea WHERE title = ? COLLATE NOCASE").all(ref);
+    if (rows.length === 1 && rows[0] !== undefined)
+        return rows[0].uuid;
+    throw new RangeError(rows.length === 0
+        ? `area not found: ${ref} (list areas with \`things areas\`)`
+        : `area reference is ambiguous: ${ref} (${rows.length} matches — use the uuid)`);
+}
+export function fetchTaskRows(db, where, params = []) {
+    const sql = `SELECT ${selectList("TMTask")
+        .split(", ")
+        .map((c) => `t.${c}`)
+        .join(", ")} FROM TMTask t WHERE ${where}`;
+    return db.prepare(sql).all(...params);
+}
+export function fetchTaskByUuid(db, uuid) {
+    const rows = fetchTaskRows(db, "t.uuid = ?", [uuid]);
+    return rows[0] ?? null;
+}
+export function fetchChecklistRows(db, taskUuid) {
+    const sql = `SELECT ${selectList("TMChecklistItem")} FROM TMChecklistItem WHERE task = ? ORDER BY ${q("index")} ASC`;
+    return db.prepare(sql).all(taskUuid);
+}
+/** Direct tags for a set of tasks, in one query. Returns uuid -> Ref[] (sorted by tag title). */
+export function fetchTagsForTasks(db, taskUuids) {
+    const map = new Map();
+    if (taskUuids.length === 0)
+        return map;
+    const placeholders = taskUuids.map(() => "?").join(",");
+    const sql = `SELECT tt.tasks AS task, tg.uuid AS uuid, tg.title AS title
+               FROM TMTaskTag tt JOIN TMTag tg ON tg.uuid = tt.tags
+               WHERE tt.tasks IN (${placeholders})
+               ORDER BY tg.title`;
+    const rows = db.prepare(sql).all(...taskUuids);
+    for (const row of rows) {
+        const list = map.get(row.task) ?? [];
+        list.push({ uuid: row.uuid, title: row.title });
+        map.set(row.task, list);
+    }
+    return map;
+}
+/** Lazy uuid -> Ref resolver over TMTask + TMArea titles, cached per instance. */
+export function makeRefResolver(db) {
+    const cache = new Map();
+    const taskStmt = db.prepare("SELECT uuid, title FROM TMTask WHERE uuid = ?");
+    const areaStmt = db.prepare("SELECT uuid, title FROM TMArea WHERE uuid = ?");
+    return (uuid) => {
+        if (uuid === null)
+            return null;
+        const cached = cache.get(uuid);
+        if (cached !== undefined)
+            return cached;
+        const hit = (taskStmt.get(uuid) ?? areaStmt.get(uuid));
+        const ref = hit ? { uuid: hit.uuid, title: hit.title ?? "" } : null;
+        cache.set(uuid, ref);
+        return ref;
+    };
+}
+//# sourceMappingURL=queries.js.map

package/dist/read/queries.js.map

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

package/dist/read/snapshot.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Full normalized dump of the library — every TMTask row (all types and
+ * states, including repeating templates and trashed rows), all areas, tags,
+ * and checklist items. UUID-ordered for stable diffing; the lab harness and
+ * pre/post-mutation forensics both consume this.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { AnyTask, Area, ChecklistItem, Tag } from "../model/entities.ts";
+export interface Snapshot {
+    areas: Area[];
+    tags: Tag[];
+    tasks: AnyTask[];
+    checklistItems: ChecklistItem[];
+    counts: {
+        areas: number;
+        tags: number;
+        todos: number;
+        projects: number;
+        headings: number;
+        checklistItems: number;
+        trashed: number;
+        repeatingTemplates: number;
+    };
+}
+export declare function snapshotView(db: DatabaseSync): Snapshot;

package/dist/read/snapshot.js

@@ -0,0 +1,39 @@
+import { q, selectList } from "../db/schema.js";
+import { mapChecklistItem, mapHeading, mapProject, mapTodo, } from "../model/mappers.js";
+import { fetchTagsForTasks, fetchTaskRows, makeRefResolver } from "./queries.js";
+import { areasView, tagsView } from "./tags.js";
+export function snapshotView(db) {
+    const areas = areasView(db);
+    const tags = tagsView(db);
+    const rows = fetchTaskRows(db, "1=1 ORDER BY t.uuid ASC");
+    const refs = makeRefResolver(db);
+    const tagMap = fetchTagsForTasks(db, rows.map((r) => r.uuid));
+    const tasks = rows.map((row) => {
+        if (row.type === 2)
+            return mapHeading(row, refs);
+        const rowTags = tagMap.get(row.uuid) ?? [];
+        return row.type === 1 ? mapProject(row, refs, rowTags) : mapTodo(row, refs, rowTags);
+    });
+    const checklistRows = db
+        .prepare(`SELECT ${selectList("TMChecklistItem")} FROM TMChecklistItem ORDER BY ${q("uuid")} ASC`)
+        .all();
+    const checklistItems = checklistRows.map(mapChecklistItem);
+    return {
+        areas,
+        tags,
+        tasks,
+        checklistItems,
+        counts: {
+            areas: areas.length,
+            tags: tags.length,
+            todos: rows.filter((r) => r.type === 0).length,
+            projects: rows.filter((r) => r.type === 1).length,
+            headings: rows.filter((r) => r.type === 2).length,
+            checklistItems: checklistItems.length,
+            trashed: rows.filter((r) => r.trashed === 1).length,
+            repeatingTemplates: rows.filter((r) => r.rt1_recurrenceRule !== null || r.repeater !== null)
+                .length,
+        },
+    };
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/read/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/read/snapshot.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EACL,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,OAAO,GAER,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAmBhD,MAAM,UAAU,YAAY,CAAC,EAAgB;IAC3C,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC1B,MAAM,IAAI,GAAG,aAAa,CAAC,EAAE,EAAE,yBAAyB,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAG,eAAe,CAAC,EAAE,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,iBAAiB,CAC9B,EAAE,EACF,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CACxB,CAAC;IACF,MAAM,KAAK,GAAc,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACxC,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3C,OAAO,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACvF,CAAC,CAAC,CAAC;IACH,MAAM,aAAa,GAAG,EAAE;SACrB,OAAO,CACN,UAAU,UAAU,CAAC,iBAAiB,CAAC,kCAAkC,CAAC,CAAC,MAAM,CAAC,MAAM,CACzF;SACA,GAAG,EAA+B,CAAC;IACtC,MAAM,cAAc,GAAG,aAAa,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAE3D,OAAO;QACL,KAAK;QACL,IAAI;QACJ,KAAK;QACL,cAAc;QACd,MAAM,EAAE;YACN,KAAK,EAAE,KAAK,CAAC,MAAM;YACnB,IAAI,EAAE,IAAI,CAAC,MAAM;YACjB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM;YAC9C,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM;YACjD,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM;YACjD,cAAc,EAAE,cAAc,CAAC,MAAM;YACrC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM;YACnD,kBAAkB,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,kBAAkB,KAAK,IAAI,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC;iBACzF,MAAM;SACV;KACF,CAAC;AACJ,CAAC"}

package/dist/read/tags.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tag reads: taxonomy, and inherited-tag resolution.
+ *
+ * The DB stores DIRECT tags only (TMTaskTag/TMAreaTag). The native UI's tag
+ * filtering also honors tags inherited from ancestor area/project (validated
+ * T18: things.py misses this). inheritedTagsFor() reconstructs that chain:
+ * task -> heading's project -> project -> area, collecting each ancestor's
+ * direct tags.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { Area, Ref, Tag } from "../model/entities.ts";
+import type { TaskRow } from "../model/mappers.ts";
+export declare function tagsView(db: DatabaseSync): Tag[];
+export declare function areasView(db: DatabaseSync): Area[];
+export declare function areaTags(db: DatabaseSync, areaUuid: string): Ref[];
+/** Tags inherited from ancestors (heading's project, project, area) — direct tags excluded. */
+export declare function inheritedTagsFor(db: DatabaseSync, row: TaskRow): Ref[];

package/dist/read/tags.js

@@ -0,0 +1,64 @@
+import { q, selectList } from "../db/schema.js";
+import { fetchTagsForTasks, fetchTaskByUuid } from "./queries.js";
+export function tagsView(db) {
+    const rows = db
+        .prepare(`SELECT ${selectList("TMTag")} FROM TMTag ORDER BY ${q("index")} ASC`)
+        .all();
+    const byUuid = new Map(rows.map((r) => [r.uuid, r]));
+    return rows.map((row) => {
+        const parentRow = row.parent ? byUuid.get(row.parent) : undefined;
+        return {
+            uuid: row.uuid,
+            title: row.title ?? "",
+            shortcut: row.shortcut,
+            parent: parentRow ? { uuid: parentRow.uuid, title: parentRow.title ?? "" } : null,
+            index: row.index ?? 0,
+        };
+    });
+}
+export function areasView(db) {
+    const rows = db
+        .prepare(`SELECT ${selectList("TMArea")} FROM TMArea ORDER BY ${q("index")} ASC`)
+        .all();
+    return rows.map((row) => ({
+        uuid: row.uuid,
+        title: row.title ?? "",
+        visible: row.visible !== 0,
+        index: row.index ?? 0,
+        tags: areaTags(db, row.uuid),
+    }));
+}
+export function areaTags(db, areaUuid) {
+    const rows = db
+        .prepare(`SELECT tg.uuid AS uuid, tg.title AS title
+       FROM TMAreaTag at JOIN TMTag tg ON tg.uuid = at.tags
+       WHERE at.areas = ? ORDER BY tg.title`)
+        .all(areaUuid);
+    return rows.map((r) => ({ uuid: r.uuid, title: r.title ?? "" }));
+}
+/** Tags inherited from ancestors (heading's project, project, area) — direct tags excluded. */
+export function inheritedTagsFor(db, row) {
+    const collected = new Map();
+    const addAll = (refs) => {
+        for (const ref of refs)
+            collected.set(ref.uuid, ref);
+    };
+    let projectUuid = row.project;
+    if (!projectUuid && row.heading) {
+        const heading = fetchTaskByUuid(db, row.heading);
+        projectUuid = heading?.project ?? null;
+    }
+    let areaUuid = row.area;
+    if (projectUuid) {
+        const project = fetchTaskByUuid(db, projectUuid);
+        if (project) {
+            addAll(fetchTagsForTasks(db, [project.uuid]).get(project.uuid) ?? []);
+            areaUuid = areaUuid ?? project.area;
+        }
+    }
+    if (areaUuid)
+        addAll(areaTags(db, areaUuid));
+    const direct = new Set((fetchTagsForTasks(db, [row.uuid]).get(row.uuid) ?? []).map((t) => t.uuid));
+    return [...collected.values()].filter((t) => !direct.has(t.uuid));
+}
+//# sourceMappingURL=tags.js.map

package/dist/read/tags.js.map

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

package/dist/read/views.d.ts

@@ -0,0 +1,152 @@
+/**
+ * List views mirroring the Things sidebar. Predicates derived from the
+ * validated research plus live probes (docs/atlas/schema-v26.md):
+ *
+ * - inbox:    start=0
+ * - today:    (startDate <= today AND start IN (1, 2)) OR a DUE DEADLINE
+ *             with no startDate — a due/overdue deadline pulls an item into
+ *             Today even from the Inbox; a FUTURE startDate suppresses it
+ *             (UI-oracle research, lab 2026-07-04, two reproducing runs —
+ *             docs/lab/today-order-research.md; this CORRECTS the earlier
+ *             "deadline-only items never enter Today" badge inference, which
+ *             held only while no deadline-only item was actually due).
+ *             ORDER: startBucket, then todayIndexReferenceDate DESC (the
+ *             date the item ENTERED Today — newest cohorts on top), then
+ *             todayIndex ASC, then uuid (observed stable tiebreak). start=2
+ *             rows with a past date are "pending promotion" (Things
+ *             recomputes on launch; the UI shows them in Today either way).
+ *             THIS EVENING expires daily: an item renders in the Evening
+ *             section only when startBucket=1 AND startDate == today exactly;
+ *             overdue bucket=1 items roll back into Today proper (live-
+ *             verified against the UI, 2026-07-02).
+ *             Sidebar badge split: red = items with deadline <= today,
+ *             gray = the rest (exact 270/122 reconciliation on live data).
+ * - anytime:  ALL active items — unscheduled PLUS Today members (the UI
+ *             renders Today members with a star; live-verified via screenshot
+ *             2026-07-02: starred = in Today, unstarred = unscheduled).
+ *             Star equivalence: startDate != NULL && <= today.
+ *             CONTAINER CASCADE (live-verified 2026-07-09): children of a
+ *             project that is not itself anytime-visible (someday/future/
+ *             logged/trashed) are excluded — the project row represents
+ *             them. Result is grouped in sidebar order (SidebarSection[]).
+ * - upcoming: start=2 AND startDate > today, PLUS each fixed repeating
+ *             template's next occurrence synthesized from
+ *             rt1_nextInstanceStartDate (UI parity; opt out via
+ *             repeats:false). Occurrence deadline = start − rule.ts
+ *             (instance-validated 2026-07-04).
+ * - someday:  start=2 AND startDate IS NULL, container-less members only
+ *             (project children appear ONLY via the activeProjectItems
+ *             toggle, and only for anytime-active projects — mirrors the
+ *             UI's "Show items from active projects"). Grouped in sidebar
+ *             order like anytime.
+ * - logbook:  status IN (2,3), by stopDate DESC
+ * - trash:    trashed=1
+ *
+ * All views: to-dos + projects (type IN (0,1)), open (unless noted),
+ * untrashed (unless trash), repeating TEMPLATE rows excluded.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { Project, Ref, Todo } from "../model/entities.ts";
+export type ListItem = Todo | Project;
+/** Optional list-view filters. */
+export interface ViewFilter {
+    /**
+     * Tag (uuid or unique title): direct OR inherited membership (UI
+     * semantics), INCLUDING items tagged with a hierarchy descendant of the
+     * given tag (documented app behavior — the UI's tag filter matches
+     * child-tagged items; not lab-oracled).
+     */
+    tag?: string;
+    /**
+     * Match the given tag ONLY — no hierarchy descendants. Useful when a
+     * parent tag has its own direct assignments distinct from its children's.
+     */
+    exactTag?: boolean;
+}
+export interface TodayView {
+    today: ListItem[];
+    evening: ListItem[];
+    /** Mirrors the sidebar badge: red = deadline due/overdue, gray = the rest. */
+    badge: {
+        dueOrOverdue: number;
+        other: number;
+    };
+}
+export declare function todayView(db: DatabaseSync, now?: Date, filter?: ViewFilter): TodayView;
+export declare function inboxView(db: DatabaseSync, filter?: ViewFilter): ListItem[];
+/**
+ * One sidebar-ordered block of a grouped view (anytime/someday): the area
+ * (null = the top-level, area-less block, which the UI renders first) and its
+ * members in UI order — direct to-dos first, then each project block (the
+ * project row immediately followed by its member to-dos).
+ */
+export interface SidebarSection {
+    area: Ref | null;
+    items: ListItem[];
+}
+export declare function anytimeView(db: DatabaseSync, now?: Date, filter?: ViewFilter): SidebarSection[];
+/** The UI's star marker in Anytime: the item is also a Today member. */
+export declare function isTodayMember(item: ListItem, now?: Date): boolean;
+export interface UpcomingFilter extends ViewFilter {
+    /** Include repeating templates' next occurrences (UI parity; default true). */
+    repeats?: boolean;
+    /**
+     * Occurrences to surface per repeating template (default 1 = only the
+     * app-materialized next instance, exactly the UI). Higher values PROJECT
+     * later occurrences from the decoded rule (fixed rules only; capped at
+     * 10) — projections are host math the app has not materialized yet.
+     */
+    horizon?: number;
+}
+export declare function upcomingView(db: DatabaseSync, now?: Date, filter?: UpcomingFilter): ListItem[];
+export interface SomedayFilter extends ViewFilter {
+    /**
+     * Also list someday to-dos that live inside ACTIVE projects — the UI's
+     * "Show items from active projects" toggle (default false, the UI's
+     * default). Children of someday projects are never listed either way: the
+     * project row stands for them.
+     */
+    activeProjectItems?: boolean;
+}
+export declare function somedayView(db: DatabaseSync, now?: Date, filter?: SomedayFilter): SidebarSection[];
+export declare function logbookView(db: DatabaseSync, options?: {
+    limit?: number;
+    tag?: string;
+}): ListItem[];
+export declare function trashView(db: DatabaseSync, options?: {
+    limit?: number;
+}): ListItem[];
+export declare function projectsView(db: DatabaseSync, options?: {
+    areaUuid?: string;
+}): Project[];
+export interface SearchOptions extends ViewFilter {
+    limit?: number;
+    /** Restrict to one project's children (headed children included). */
+    project?: string;
+    /** Restrict to one area's direct members. */
+    area?: string;
+    type?: "to-do" | "project";
+    /** Include completed/canceled items (default: open only). */
+    logged?: boolean;
+    /** Include trashed items (default: untrashed only). */
+    trashed?: boolean;
+    /** Everything — the legacy behavior (open + logged + trashed). */
+    all?: boolean;
+}
+export type ChangeKind = "created" | "modified";
+export type ChangedItem = ListItem & {
+    changeKind: ChangeKind;
+};
+/**
+ * Everything that changed since a moment — created or modified TMTask rows,
+ * INCLUDING trashed, logged, and repeating-template rows (an agent syncing
+ * state needs to see deletions and template edits too; check `trashed`,
+ * `status`, and `repeating.isTemplate` on each item). Caveats: TMArea/TMTag
+ * carry no modification dates, and checklist-item edits do not bump the
+ * parent task — those changes are invisible here.
+ */
+export declare function changesView(db: DatabaseSync, options: {
+    since: Date;
+    limit?: number;
+}): ChangedItem[];
+export declare function searchView(db: DatabaseSync, query: string, options?: SearchOptions): ListItem[];