things-api 0.9.0 → 0.10.0

package/dist/read/views.js

@@ -3,19 +3,84 @@ import { logBoundary, markLogged } from "./log-boundary.js";
 import { mapProject, mapTodo } from "../model/mappers.js";
 import { projectOccurrences } from "../model/occurrences.js";
 import { decodeRecurrenceRule } from "../model/recurrence.js";
-import { fetchTagsForTasks, fetchTaskRows, makeHeadingProjectResolver, makeRefResolver, NOT_TEMPLATE, resolveAreaUuid, resolveProjectUuid, resolveTagUuid, tagScopeBinds, tagScopeSql, tagWithDescendants, } from "./queries.js";
-import { ANYTIME_SELF, CONTAINER_UNTRASHED, EFF_PROJECT, LIVE, OPEN, PROJECT_ANYTIME_ACTIVE, } from "./predicates.js";
+import { directTagScopeSql, directUntaggedScopeSql, fetchTagsForTasks, fetchTaskRows, makeHeadingProjectResolver, makeRefResolver, NOT_TEMPLATE, resolveAreaUuid, resolveProjectUuid, resolveTagUuid, tagScopeBinds, tagScopeSql, tagWithDescendants, untaggedScopeSql, } from "./queries.js";
+import { ANYTIME_SELF, CONTAINER_UNTRASHED, EFF_PROJECT, LIVE, OPEN, OPEN_OR_UNSWEPT, OVERDUE, PROJECT_ANYTIME_ACTIVE, } from "./predicates.js";
 import { groupBySidebar } from "./sidebar-order.js";
 import { areasView } from "./tags.js";
 import { compareSearchMatches } from "./search-rank.js";
-function tagFilter(db, filter) {
-    if (filter?.tag === undefined)
+/**
+ * Escape a user term for a SQL LIKE pattern so `%` and `_` match LITERALLY,
+ * not as wildcards (search "my_task" must not match "myXtask"; "50%" must not
+ * match "50"-anything). Backslash is the escape character — escape it first,
+ * then the two wildcard metacharacters. Every LIKE fed an escaped term must
+ * append `ESCAPE '\'` (see {@link LIKE_ESCAPE}).
+ */
+function escapeLike(term) {
+    return term.replace(/[\\%_]/g, (c) => `\\${c}`);
+}
+/** SQL clause suffix pairing an escaped LIKE pattern with its escape char. */
+const LIKE_ESCAPE = " ESCAPE '\\'";
+/**
+ * Compose the tag scope for a filter into an AND-chained SQL fragment plus its
+ * binds. Every clause AND-combines: the `untagged` negation and each `--tag`
+ * ref (each ref independently resolved and descendant-expanded per `exactTag`).
+ * The mutually-exclusive combination (`untagged` with a tag-presence flag) is
+ * refused at the CLI/MCP surfaces; here it would simply AND to an empty result.
+ * Splices in before {@link overdueFilter} so the tag binds precede the overdue
+ * bind.
+ *
+ * `options.container` selects the CONTAINER semantics (`project show` /
+ * `area show` / the `projects` list): the view's own inheritance hop is dropped,
+ * so `--tag` matches a DIRECT assignment (still descendant-expanded) and
+ * `--untagged` means "no direct tag". Every child inherits its container's tags,
+ * so an inheritance-inclusive filter there is vacuous — direct-on-the-row is the
+ * useful, GUI-faithful behavior. FLAT views omit the option and keep the
+ * inheritance-inclusive relation.
+ */
+export function tagFilter(db, filter, options) {
+    const container = options?.container === true;
+    const clauses = [];
+    const binds = [];
+    if (filter?.untagged === true)
+        clauses.push(container ? directUntaggedScopeSql() : untaggedScopeSql());
+    const exact = filter?.exactTag === true;
+    const tagRefs = [...(filter?.tags ?? []), ...(filter?.tag !== undefined ? [filter.tag] : [])];
+    const expand = (ref) => {
+        const target = resolveTagUuid(db, ref);
+        return exact ? [target] : tagWithDescendants(db, target);
+    };
+    for (const ref of tagRefs) {
+        const uuids = expand(ref);
+        if (container) {
+            clauses.push(directTagScopeSql(uuids.length));
+            binds.push(...uuids);
+        }
+        else {
+            clauses.push(tagScopeSql(uuids.length));
+            binds.push(...tagScopeBinds(uuids));
+        }
+    }
+    if (clauses.length === 0)
+        return { sql: "", binds: [] };
+    return { sql: ` AND ${clauses.join(" AND ")}`, binds };
+}
+/**
+ * The `--overdue` content scope as a spliceable SQL fragment (empty when off).
+ * Appended AFTER {@link tagFilter} in every host view so it intersects with the
+ * tag scope, and its single packed-today bind trails the tag binds in the same
+ * order. `packedToday` is encodePackedDate(localToday(now)) — the caller's
+ * injected clock — never a hardcoded date.
+ */
+function overdueFilter(filter, packedToday) {
+    if (filter?.overdue !== true)
         return { sql: "", binds: [] };
-    const target = resolveTagUuid(db, filter.tag);
-    const uuids = filter.exactTag === true ? [target] : tagWithDescendants(db, target);
-    return { sql: ` AND ${tagScopeSql(uuids.length)}`, binds: tagScopeBinds(uuids) };
+    return { sql: ` AND ${OVERDUE}`, binds: [packedToday] };
 }
-function materialize(db, rows) {
+// `boundary` is REQUIRED (no wall-clock default): every caller threads the
+// view's injected `now` via logBoundary(db, now) so the `logged` flag it stamps
+// honors the same clock as the SQL membership filter (a pinned test clock, a
+// lab run) — nothing here silently reaches for real time.
+function materialize(db, rows, boundary) {
     const refs = makeRefResolver(db);
     const headingProject = makeHeadingProjectResolver(db);
     const tags = fetchTagsForTasks(db, rows.map((r) => r.uuid));
@@ -30,12 +95,18 @@ function materialize(db, rows) {
         }
         return todo;
     });
-    return markLogged(items, logBoundary(db));
+    // The caller may pass the boundary it already used for the SQL membership
+    // filter so the `logged` flag and the row's presence agree (a checked-unswept
+    // row must materialize with logged=false).
+    return markLogged(items, boundary);
 }
+/** Badge = OPEN members only (the GUI badge counts remaining work). */
+const isOpen = (i) => i.status === "open";
 export function todayView(db, now, filter) {
     const todayIso = localToday(now);
     const packedToday = encodePackedDate(todayIso);
     const tf = tagFilter(db, filter);
+    const of = overdueFilter(filter, packedToday);
     // Membership + comparator per the UI-oracle research (lab, 2026-07-04;
     // docs/lab/today-order-research.md, two reproducing runs + exact live
     // reconciliation: 405 − 12 suppressed = 393 = the UI's own count):
@@ -47,59 +118,165 @@ export function todayView(db, now, filter) {
     //    (the date the item ENTERED Today: its startDate, or its deadline for
     //    deadline-driven members), then todayIndex ASC, then uuid (observed
     //    stable tiebreak).
-    const rows = fetchTaskRows(db, `${OPEN} AND ${CONTAINER_UNTRASHED} AND (
+    // Membership is OPEN_OR_UNSWEPT (not OPEN): a checked row the log-move sweep
+    // has not yet passed keeps its comparator slot in place (GUI-parity ruling
+    // 2026-07-14). The boundary is threaded into both the SQL filter and
+    // materialize so the row's presence and its `logged` flag agree.
+    const boundary = logBoundary(db, now);
+    const rows = fetchTaskRows(db, `${OPEN_OR_UNSWEPT} AND ${CONTAINER_UNTRASHED} AND (
        (t.startDate IS NOT NULL AND t.startDate <= ? AND t.start IN (1, 2))
        OR (t.deadline IS NOT NULL AND t.deadline <= ? AND t.startDate IS NULL
            AND (t.deadlineSuppressionDate IS NULL OR t.deadlineSuppressionDate < t.deadline))
-     )${tf.sql}
+     )${tf.sql}${of.sql}
      ORDER BY t.startBucket ASC,
               COALESCE(t.todayIndexReferenceDate, t.startDate, t.deadline) DESC,
-              t.todayIndex ASC, t.uuid ASC`, [packedToday, packedToday, ...tf.binds]);
-    const items = materialize(db, rows);
+              t.todayIndex ASC, t.uuid ASC`, [boundary.getTime() / 1000, packedToday, packedToday, ...tf.binds, ...of.binds]);
+    const items = materialize(db, rows, boundary);
     // Evening membership expires daily: raw startBucket=1 counts only while
     // startDate is exactly today; stale evening items belong to Today proper.
     const isEvening = (i) => i.todaySection === "evening" && i.startDate === todayIso;
-    const dueOrOverdue = items.filter((i) => i.deadline !== null && i.deadline <= todayIso).length;
+    const evening = items.filter(isEvening);
+    const dueIn = (list) => list.filter((i) => i.deadline !== null && i.deadline <= todayIso).length;
+    // Badge = OPEN members only (the GUI badge counts remaining work). A
+    // checked-but-unswept row is present in the list but never moves the badge —
+    // this preserves the exact live reconciliation computed under OPEN membership.
+    // The evening filter mirrors the tag filter's badge treatment: the badge
+    // reflects exactly the members the view now returns (here, evening only).
+    if (filter?.eveningOnly === true) {
+        const openEvening = evening.filter(isOpen);
+        const eveningDue = dueIn(openEvening);
+        return {
+            today: [],
+            evening,
+            badge: { dueOrOverdue: eveningDue, other: openEvening.length - eveningDue },
+        };
+    }
+    const openItems = items.filter(isOpen);
+    const dueOrOverdue = dueIn(openItems);
     return {
         today: items.filter((i) => !isEvening(i)),
-        evening: items.filter(isEvening),
-        badge: { dueOrOverdue, other: items.length - dueOrOverdue },
+        evening,
+        badge: { dueOrOverdue, other: openItems.length - dueOrOverdue },
     };
 }
-export function inboxView(db, filter) {
+export function inboxView(db, now, filter) {
     const tf = tagFilter(db, filter);
-    const rows = fetchTaskRows(db, `${OPEN} AND t.start = 0${tf.sql} ORDER BY t."index" ASC`, tf.binds);
-    return materialize(db, rows);
+    // `now` is threaded only for the `--overdue` boundary (the inbox order and
+    // the since/until window key on epoch creationDate, not on today).
+    const of = overdueFilter(filter, encodePackedDate(localToday(now)));
+    const where = [OPEN, "t.start = 0"];
+    const binds = [];
+    // creationDate is an epoch REAL (Unix seconds) — mirror the changes/logbook
+    // comparison (getTime()/1000 against the raw column), never encodePackedDate.
+    if (filter?.since !== undefined) {
+        where.push("t.creationDate >= ?");
+        binds.push(filter.since.getTime() / 1000);
+    }
+    if (filter?.until !== undefined) {
+        where.push("t.creationDate <= ?");
+        binds.push(filter.until.getTime() / 1000);
+    }
+    const rows = fetchTaskRows(db, `${where.join(" AND ")}${tf.sql}${of.sql} ORDER BY t."index" ASC`, [...binds, ...tf.binds, ...of.binds]);
+    return materialize(db, rows, logBoundary(db, now));
 }
 export function anytimeView(db, now, filter) {
     const packedToday = encodePackedDate(localToday(now));
     const tf = tagFilter(db, filter);
+    const of = overdueFilter(filter, packedToday);
     // Mirrors UI membership: every active item, including Today members
     // (starred in the UI) and pending-promotion rows (start=2, past-dated) —
-    // MINUS children of non-active containers (the project cascade).
-    const rows = fetchTaskRows(db, `${OPEN} AND ${ANYTIME_SELF("t")}
-     AND ${PROJECT_ANYTIME_ACTIVE}${tf.sql} ORDER BY t."index" ASC`, [packedToday, packedToday, packedToday, packedToday, ...tf.binds]);
-    return groupBySidebar(db, materialize(db, rows));
+    // MINUS children of non-active containers (the project cascade). Membership
+    // is OPEN_OR_UNSWEPT (GUI-parity ruling 2026-07-14): a checked row the sweep
+    // has not passed keeps its index slot. PROJECT_ANYTIME_ACTIVE still requires
+    // the parent project be open, so a closed-but-unswept project's children stay
+    // cascade-excluded — the checked project row represents them. The boundary is
+    // threaded into the SQL filter and materialize so presence and `logged` agree.
+    const boundary = logBoundary(db, now);
+    const rows = fetchTaskRows(db, `${OPEN_OR_UNSWEPT} AND ${ANYTIME_SELF("t")}
+     AND ${PROJECT_ANYTIME_ACTIVE}${tf.sql}${of.sql} ORDER BY t."index" ASC`, [
+        boundary.getTime() / 1000,
+        packedToday,
+        packedToday,
+        packedToday,
+        packedToday,
+        ...tf.binds,
+        ...of.binds,
+    ]);
+    return groupBySidebar(db, materialize(db, rows, boundary));
 }
-/** The UI's star marker in Anytime: the item is also a Today member. */
+/**
+ * The UI's star marker in Anytime: the item is also a Today member. Mirrors
+ * {@link todayView}'s two membership arms so an unscheduled item pulled into
+ * Today by a due deadline stars exactly like a scheduled one:
+ *   - SCHEDULED — a When-date that has arrived (startDate <= today); or
+ *   - DEADLINE-DRIVEN — no When-date, but a due/overdue deadline (deadline <=
+ *     today) pulls it into Today (the todayView arm that lets a bare deadline
+ *     surface an item). Only reached for anytime-visible rows (start=1,
+ *     startDate NULL), so it never over-stars someday/inbox rows.
+ * KNOWN LIMITATION: todayView's deadline arm also drops a DISMISSED-nag
+ * deadline (deadlineSuppressionDate >= deadline); that column is not surfaced
+ * on the entity, so a suppressed unscheduled overdue row is over-starred here.
+ */
 export function isTodayMember(item, now) {
-    return item.startDate !== null && item.startDate <= localToday(now);
+    const today = localToday(now);
+    if (item.startDate !== null)
+        return item.startDate <= today;
+    return item.deadline !== null && item.deadline <= today;
 }
+/**
+ * The merged date-ordered stream keys on COALESCE(startDate, deadline) — a
+ * scheduled row groups under its when-date, a forecast row under its deadline.
+ */
+const groupKey = (i) => i.startDate ?? i.deadline ?? "";
 export function upcomingView(db, now, filter) {
     const packedToday = encodePackedDate(localToday(now));
+    const boundary = logBoundary(db, now);
     const until = filter?.until;
     const since = filter?.since;
-    const untilSql = until === undefined ? "" : " AND t.startDate <= ?";
     const untilBinds = until === undefined ? [] : [encodePackedDate(until)];
-    const sinceSql = since === undefined ? "" : " AND t.startDate >= ?";
     const sinceBinds = since === undefined ? [] : [encodePackedDate(since)];
     const tf = tagFilter(db, filter);
+    // Cohort 1 — SCHEDULED: start=2 with a future startDate. The bounds clip the
+    // APPEARANCE date, which for these rows is the startDate (when-date).
+    const schedUntilSql = until === undefined ? "" : " AND t.startDate <= ?";
+    const schedSinceSql = since === undefined ? "" : " AND t.startDate >= ?";
     const rows = fetchTaskRows(db, `${OPEN} AND ${CONTAINER_UNTRASHED}
-     AND t.start = 2 AND t.startDate IS NOT NULL AND t.startDate > ?${untilSql}${sinceSql}${tf.sql}
+     AND t.start = 2 AND t.startDate IS NOT NULL AND t.startDate > ?${schedUntilSql}${schedSinceSql}${tf.sql}
      ORDER BY t.startDate ASC, t."index" ASC`, [packedToday, ...untilBinds, ...sinceBinds, ...tf.binds]);
-    const items = materialize(db, rows);
+    // Cohort 2 — DEADLINE-FORECAST (UPC1, GUI-verified): anytime/someday to-dos
+    // and someday projects carrying a FUTURE deadline and no when-date. Inbox
+    // (start=0) is excluded; a dismissed-nag deadline (deadlineSuppressionDate ==
+    // deadline) is dropped while a re-armed one (supp < deadline) survives — the
+    // todayView suppression clause one step earlier (deadline > today, not <=).
+    // These rows keep startDate NULL (JSON honesty) and APPEAR under their
+    // deadline, so the bounds clip on deadline, exactly as cohort 1 clips on
+    // startDate.
+    const fcUntilSql = until === undefined ? "" : " AND t.deadline <= ?";
+    const fcSinceSql = since === undefined ? "" : " AND t.deadline >= ?";
+    const forecastRows = fetchTaskRows(db, `${OPEN} AND ${CONTAINER_UNTRASHED}
+     AND t.startDate IS NULL AND t.start IN (1, 2)
+     AND t.deadline IS NOT NULL AND t.deadline > ?
+     AND (t.deadlineSuppressionDate IS NULL OR t.deadlineSuppressionDate < t.deadline)${fcUntilSql}${fcSinceSql}${tf.sql}
+     ORDER BY t.deadline ASC, t."index" ASC`, [packedToday, ...untilBinds, ...sinceBinds, ...tf.binds]);
+    const scheduled = materialize(db, rows, boundary);
+    const forecast = materialize(db, forecastRows, boundary);
+    // The merged date-ordered stream keys on COALESCE(startDate, deadline) — a
+    // scheduled row groups under its when-date, a forecast row under its deadline
+    // — then the UI's within-day drag order (todayIndex ASC; live-verified
+    // 2026-07-11 against the GUI — plain `index` disagrees), then a stable
+    // seed-order/uuid tiebreak.
+    const sortDated = (list, indexRows) => {
+        const todayIndexOf = new Map(indexRows.map((r) => [r.uuid, r.todayIndex ?? 0]));
+        return list
+            .map((item, pos) => ({ item, pos }))
+            .toSorted((a, b) => groupKey(a.item).localeCompare(groupKey(b.item)) ||
+            (todayIndexOf.get(a.item.uuid) ?? 0) - (todayIndexOf.get(b.item.uuid) ?? 0) ||
+            a.pos - b.pos ||
+            a.item.uuid.localeCompare(b.item.uuid))
+            .map((x) => x.item);
+    };
     if (filter?.repeats === false)
-        return items;
+        return sortDated([...scheduled, ...forecast], [...rows, ...forecastRows]);
     // UI parity: repeating templates surface at their app-materialized next
     // occurrence (rt1_nextInstanceStartDate). Fixed rules only — after-
     // completion templates carry no next date until the prior instance
@@ -112,7 +289,7 @@ export function upcomingView(db, now, filter) {
      ORDER BY t.rt1_nextInstanceStartDate ASC, t."index" ASC`, [packedToday, ...untilBinds, ...sinceBinds, ...tf.binds]);
     const horizon = Math.max(1, Math.min(10, Math.trunc(filter?.horizon ?? 1)));
     const rawByUuid = new Map(templateRows.map((r) => [r.uuid, r.rt1_recurrenceRule]));
-    const occurrences = materialize(db, templateRows).flatMap((template) => {
+    const occurrences = materialize(db, templateRows, boundary).flatMap((template) => {
         const startDate = template.repeating.nextOccurrence ?? null;
         if (startDate === null)
             return [];
@@ -153,17 +330,9 @@ export function upcomingView(db, now, filter) {
             deadline: o.deadline,
         })));
     });
-    // Within a day the UI's drag order is todayIndex ASC (live-verified
-    // 2026-07-11 against the GUI: plain `index` disagrees, todayIndex matches
-    // exactly), so the sortable Upcoming order survives the CLI.
-    const todayIndexOf = new Map([...rows, ...templateRows].map((r) => [r.uuid, r.todayIndex ?? 0]));
-    const dated = [...items, ...occurrences]
-        .map((item, pos) => ({ item, pos }))
-        .toSorted((a, b) => (a.item.startDate ?? "").localeCompare(b.item.startDate ?? "") ||
-        (todayIndexOf.get(a.item.uuid) ?? 0) - (todayIndexOf.get(b.item.uuid) ?? 0) ||
-        a.pos - b.pos ||
-        a.item.uuid.localeCompare(b.item.uuid))
-        .map((x) => x.item);
+    // The scheduled + forecast + occurrence rows share one date-ordered stream
+    // (COALESCE(startDate, deadline), then the UI's within-day drag order).
+    const dated = sortDated([...scheduled, ...forecast, ...occurrences], [...rows, ...forecastRows, ...templateRows]);
     // The UI's trailing "Repeating To-Dos" section: templates with NO set
     // next occurrence (after-completion rules between instances, rules past
     // their end date) plus paused ones — startDate stays null, the decoded
@@ -173,7 +342,7 @@ export function upcomingView(db, now, filter) {
      AND (t.rt1_nextInstanceStartDate IS NULL OR t.rt1_nextInstanceStartDate <= ?
           OR t.rt1_instanceCreationPaused = 1)${tf.sql}
      ORDER BY t.todayIndex ASC, t."index" ASC`, [packedToday, ...tf.binds]);
-    const resting = materialize(db, restingRows).map((item) => {
+    const resting = materialize(db, restingRows, boundary).map((item) => {
         const raw = restingRows.find((r) => r.uuid === item.uuid)?.rt1_recurrenceRule;
         if (raw !== null && raw !== undefined) {
             try {
@@ -187,9 +356,12 @@ export function upcomingView(db, now, filter) {
     });
     return [...dated, ...resting];
 }
+/** A someday to-do nested under a project (directly or via a heading). */
+const isChild = (i) => i.type === "to-do" && (i.project !== null || i.headingProject !== null);
 export function somedayView(db, now, filter) {
     const tf = tagFilter(db, filter);
     const packedToday = encodePackedDate(localToday(now));
+    const of = overdueFilter(filter, packedToday);
     // Default membership excludes ALL project children (the UI shows only
     // container-less someday to-dos, area members, and someday project rows);
     // the toggle adds someday children of anytime-ACTIVE projects only.
@@ -199,14 +371,13 @@ export function somedayView(db, now, filter) {
          AND p.trashed = 0 AND p.status = 0 AND ${ANYTIME_SELF("p")})`
         : "0";
     const rows = fetchTaskRows(db, `${OPEN} AND t.start = 2 AND t.startDate IS NULL
-     AND (${EFF_PROJECT} IS NULL OR ${childArm})${tf.sql} ORDER BY t."index" ASC`, [...(withActiveChildren ? [packedToday, packedToday] : []), ...tf.binds]);
-    const sections = groupBySidebar(db, materialize(db, rows));
+     AND (${EFF_PROJECT} IS NULL OR ${childArm})${tf.sql}${of.sql} ORDER BY t."index" ASC`, [...(withActiveChildren ? [packedToday, packedToday] : []), ...tf.binds, ...of.binds]);
+    const sections = groupBySidebar(db, materialize(db, rows, logBoundary(db, now)));
     // GUI order within a Someday group (live side-by-side, 2026-07-12):
     // PROJECT rows first (their sidebar order preserved), then direct to-dos in
     // drag order. Someday children of active projects (the activeProjectItems
     // toggle) trail the group, still clustered by their project — surfaces
     // present them as a separate "From active projects" section.
-    const isChild = (i) => i.type === "to-do" && (i.project !== null || i.headingProject !== null);
     return sections.map((s) => ({
         area: s.area,
         items: [
@@ -216,7 +387,7 @@ export function somedayView(db, now, filter) {
         ],
     }));
 }
-export function logbookView(db, options) {
+export function logbookView(db, now, options) {
     const cap = options?.limit === null ? null : (options?.limit ?? 100);
     const tf = tagFilter(db, options);
     const where = [];
@@ -240,21 +411,38 @@ export function logbookView(db, options) {
     }
     const extra = where.length > 0 ? ` AND ${where.join(" AND ")}` : "";
     // Completion ≠ logged: closed items past the log-move boundary still sit
-    // checked in their original lists, exactly like the GUI's Logbook.
-    const rows = fetchTaskRows(db, `${LIVE} AND t.status IN (2, 3) AND t.stopDate <= ?${extra}${tf.sql} ORDER BY t.stopDate DESC${cap === null ? "" : " LIMIT ?"}`, [logBoundary(db).getTime() / 1000, ...binds, ...tf.binds, ...(cap === null ? [] : [cap])]);
-    return materialize(db, rows);
+    // checked in their original lists, exactly like the GUI's Logbook. The
+    // membership boundary rides the injected clock (threaded into both the SQL
+    // filter and materialize so presence and the `logged` flag agree).
+    const boundary = logBoundary(db, now);
+    const rows = fetchTaskRows(db, `${LIVE} AND t.status IN (2, 3) AND t.stopDate <= ?${extra}${tf.sql} ORDER BY t.stopDate DESC${cap === null ? "" : " LIMIT ?"}`, [boundary.getTime() / 1000, ...binds, ...tf.binds, ...(cap === null ? [] : [cap])]);
+    return materialize(db, rows, boundary);
 }
-export function trashView(db, options) {
+export function trashView(db, now, options) {
     const cap = options?.limit === null ? null : (options?.limit ?? 200);
     const rows = fetchTaskRows(db, `t.type IN (0, 1) AND t.trashed = 1 AND ${NOT_TEMPLATE}
      ORDER BY t.userModificationDate DESC${cap === null ? "" : " LIMIT ?"}`, cap === null ? [] : [cap]);
-    return materialize(db, rows);
+    return materialize(db, rows, logBoundary(db, now));
 }
 export function projectsView(db, options) {
     // areaUuid accepts a uuid OR a unique (case-insensitive) title; ambiguous
     // or unknown references throw like every other ref resolver.
     const area = options?.areaUuid === undefined ? null : resolveAreaUuid(db, options.areaUuid);
     const packedToday = encodePackedDate(localToday(options?.now));
+    // Tag scope (§9a): the projects LIST is a FLAT view (like `anytime` restricted
+    // to project rows), NOT a single-container view — projects sit in different
+    // areas with heterogeneous inheritance, there is no universally-inherited tag
+    // set, and inherited tags are opaque here (area headers don't show what they
+    // confer), so filtering by an inherited tag is useful. `--tag`/`--untagged`
+    // are INHERITANCE-INCLUSIVE (a project inherits its area's tags). Its binds sit
+    // in the WHERE, after the overdue bind and before the active-first binds.
+    const tf = tagFilter(db, options);
+    // OWN-DEADLINE UNIFORM: `--overdue` keeps only projects whose OWN deadline is
+    // overdue (open, strictly before today) — projects carry a `deadline` column
+    // exactly like to-dos, so the shared OVERDUE predicate applies to project
+    // rows verbatim. A content scope: it narrows the list, never lifts a limit.
+    const overdueSql = options?.overdue === true ? ` AND ${OVERDUE}` : "";
+    const overdueBinds = options?.overdue === true ? [packedToday] : [];
     // Sidebar default: LATER (someday + future-scheduled) projects are hidden —
     // active means ANYTIME_SELF (a scheduled project whose date has arrived
     // counts active, exactly the Anytime membership test). With later=true they
@@ -270,16 +458,18 @@ export function projectsView(db, options) {
     // above the areas — then each area by ITS sidebar rank (TMArea."index"),
     // projects within an area by their drag order.
     const where = area
-        ? `${OPEN} AND t.type = 1 AND t.area = ?${laterSql}
+        ? `${OPEN} AND t.type = 1 AND t.area = ?${laterSql}${overdueSql}${tf.sql}
        ORDER BY ${activeFirst}t."index" ASC`
-        : `${OPEN} AND t.type = 1${laterSql} ORDER BY (t.area IS NOT NULL) ASC,
+        : `${OPEN} AND t.type = 1${laterSql}${overdueSql}${tf.sql} ORDER BY (t.area IS NOT NULL) ASC,
        (SELECT a."index" FROM TMArea a WHERE a.uuid = t.area) ASC, ${activeFirst}t."index" ASC`;
     const rows = fetchTaskRows(db, where, [
         ...(area ? [area] : []),
         ...laterBinds,
+        ...overdueBinds,
+        ...tf.binds,
         ...activeFirstBinds,
     ]);
-    const items = materialize(db, rows);
+    const items = materialize(db, rows, logBoundary(db, options?.now));
     if (options?.later !== true)
         return items;
     // Each group's later sub-block reads like Upcoming: SCHEDULED projects
@@ -333,13 +523,13 @@ export function projectsView(db, options) {
  * carry no modification dates, and checklist-item edits do not bump the
  * parent task — those changes are invisible here.
  */
-export function changesView(db, options) {
+export function changesView(db, now, options) {
     const cap = options.limit === null ? null : (options.limit ?? 200);
     const sinceEpoch = options.since.getTime() / 1000;
     const rows = fetchTaskRows(db, `t.type IN (0, 1) AND t.userModificationDate > ?
      ORDER BY t.userModificationDate DESC${cap === null ? "" : " LIMIT ?"}`, [sinceEpoch, ...(cap === null ? [] : [cap])]);
     // oxlint-disable-next-line no-map-spread -- building fresh change objects, not mutating
-    return materialize(db, rows).map((item, i) => ({
+    return materialize(db, rows, logBoundary(db, now)).map((item, i) => ({
         ...item,
         changeKind: (rows[i]?.creationDate ?? 0) > sinceEpoch ? "created" : "modified",
     }));
@@ -359,7 +549,7 @@ const somedayRank = (i) => (i.start === "someday" ? 1 : 0);
 function byStatusThenRecent(a, b) {
     return somedayRank(a) - somedayRank(b) || b.modified.getTime() - a.modified.getTime();
 }
-export function liteTitleSearch(db, query, options) {
+export function liteTitleSearch(db, query, options, now) {
     const cap = options?.limit ?? 10;
     const type = options?.type;
     const needle = query.toLowerCase();
@@ -371,8 +561,8 @@ export function liteTitleSearch(db, query, options) {
     let tasks = [];
     if (type === undefined || type === "to-do" || type === "project") {
         const typeSql = type === "to-do" ? "t.type = 0" : type === "project" ? "t.type = 1" : "t.type IN (0, 1)";
-        const rows = fetchTaskRows(db, `${OPEN} AND ${CONTAINER_UNTRASHED} AND ${typeSql} AND t.title LIKE ?`, [`%${query}%`]);
-        tasks = materialize(db, rows);
+        const rows = fetchTaskRows(db, `${OPEN} AND ${CONTAINER_UNTRASHED} AND ${typeSql} AND t.title LIKE ?${LIKE_ESCAPE}`, [`%${escapeLike(query)}%`]);
+        tasks = materialize(db, rows, logBoundary(db, now));
     }
     const projects = tasks.filter((t) => t.type === "project").toSorted(byStatusThenRecent);
     const todos = tasks.filter((t) => t.type === "to-do").toSorted(byStatusThenRecent);
@@ -383,9 +573,16 @@ export function liteTitleSearch(db, query, options) {
     ];
     return { candidates: ordered.slice(0, cap), total: ordered.length };
 }
-export function searchView(db, query, options) {
+export function searchView(db, query, options, now) {
     const cap = options?.limit === null ? null : (options?.limit ?? 50);
-    const needle = `%${query}%`;
+    const needle = `%${escapeLike(query)}%`;
+    // `--overdue` narrows to OPEN, past-deadline matches. Its open-only predicate
+    // is contradictory with the status-widening flags (logged/trashed/all); the
+    // CLI/MCP surfaces reject that combination, so here it simply intersects.
+    const of = overdueFilter(options, encodePackedDate(localToday(now)));
+    // Threaded into every materialize so the `logged` flag (--logged widens to
+    // closed rows) honors the injected clock, not wall time.
+    const boundary = logBoundary(db, now);
     // The scope predicates (everything except the match needle), reused verbatim
     // for the needle query AND the heading-credited-project query so both honor
     // the same type/status/scope constraints.
@@ -418,10 +615,10 @@ export function searchView(db, query, options) {
     }
     const tf = tagFilter(db, options);
     // Needle matches: title OR notes. No SQL LIMIT — ranking runs before the cap.
-    const rows = fetchTaskRows(db, `${scope.join(" AND ")} AND (t.title LIKE ? OR t.notes LIKE ?)${tf.sql}`, [...scopeBinds, needle, needle, ...tf.binds]);
+    const rows = fetchTaskRows(db, `${scope.join(" AND ")} AND (t.title LIKE ?${LIKE_ESCAPE} OR t.notes LIKE ?${LIKE_ESCAPE})${tf.sql}${of.sql}`, [...scopeBinds, needle, needle, ...tf.binds, ...of.binds]);
     const needleLower = query.toLowerCase();
     const matches = new Map();
-    for (const item of materialize(db, rows)) {
+    for (const item of materialize(db, rows, boundary)) {
         // Field credit: title beats notes when both carry the substring.
         const field = item.title.toLowerCase().includes(needleLower) ? "title" : "notes";
         matches.set(item.uuid, { item, field });
@@ -433,7 +630,7 @@ export function searchView(db, query, options) {
     if (options?.type !== "to-do") {
         const headingRows = db
             .prepare(`SELECT project AS projectUuid, title FROM TMTask
-         WHERE type = 2 AND project IS NOT NULL AND trashed = 0 AND title LIKE ?`)
+         WHERE type = 2 AND project IS NOT NULL AND trashed = 0 AND title LIKE ?${LIKE_ESCAPE}`)
             .all(needle);
         const headingTitleFor = new Map();
         for (const h of headingRows) {
@@ -446,8 +643,8 @@ export function searchView(db, query, options) {
         const wanted = [...headingTitleFor.keys()].filter((uuid) => !matches.has(uuid));
         if (wanted.length > 0) {
             const placeholders = wanted.map(() => "?").join(", ");
-            const projectRows = fetchTaskRows(db, `${scope.join(" AND ")} AND t.type = 1 AND t.uuid IN (${placeholders})${tf.sql}`, [...scopeBinds, ...wanted, ...tf.binds]);
-            for (const item of materialize(db, projectRows)) {
+            const projectRows = fetchTaskRows(db, `${scope.join(" AND ")} AND t.type = 1 AND t.uuid IN (${placeholders})${tf.sql}${of.sql}`, [...scopeBinds, ...wanted, ...tf.binds, ...of.binds]);
+            for (const item of materialize(db, projectRows, boundary)) {
                 const matchedVia = {
                     kind: "heading",
                     title: headingTitleFor.get(item.uuid) ?? "",