things-api 0.8.0 → 0.10.0

package/dist/read/views.js

@@ -3,17 +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";
-function tagFilter(db, filter) {
-    if (filter?.tag === undefined)
+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";
+/**
+ * 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: [] };
-    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 ${clauses.join(" AND ")}`, binds };
 }
-const LIVE = `t.type IN (0, 1) AND t.trashed = 0 AND ${NOT_TEMPLATE}`;
-const OPEN = `${LIVE} AND t.status = 0`;
-function materialize(db, rows) {
+/**
+ * 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: [] };
+    return { sql: ` AND ${OVERDUE}`, binds: [packedToday] };
+}
+// `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));
@@ -28,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):
@@ -45,180 +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));
 }
-/** An item's own anytime membership: unscheduled-active, or dated <= today. */
-const ANYTIME_SELF = (col) => `((${col}.start = 1 AND (${col}.startDate IS NULL OR ${col}.startDate <= ?))
-    OR (${col}.start = 2 AND ${col}.startDate IS NOT NULL AND ${col}.startDate <= ?))`;
-/**
- * The item's effective project: its own link, or its heading's project for
- * headed children (heading rows carry the project link).
- */
-const EFF_PROJECT = `COALESCE(t.project, (SELECT h.project FROM TMTask h WHERE h.uuid = t.heading))`;
-/**
- * Container cascade (live-verified against the UI, 2026-07-09): a to-do
- * inside a project that is NOT itself anytime-visible (someday or
- * future-scheduled, logged, or trashed) is absent from Anytime regardless of
- * the to-do's own start state — the project row alone represents it.
- * Projects and container-less to-dos pass through. Two binds (packedToday ×2).
- */
-const PROJECT_ANYTIME_ACTIVE = `(${EFF_PROJECT} IS NULL OR EXISTS (
-     SELECT 1 FROM TMTask p WHERE p.uuid = ${EFF_PROJECT}
-     AND p.trashed = 0 AND p.status = 0 AND ${ANYTIME_SELF("p")}))`;
-/**
- * DERIVED-trash exclusion: project deletion is SHALLOW (A24B — only the
- * project row flips trashed=1; children keep trashed=0 and their links, so
- * their Trash membership is derived through the container chain). Every live
- * view must therefore check the chain, not just the row's own flag: the
- * heading (if any) and the effective project (direct or via heading) must
- * both be untrashed. Areas cannot be trashed (they delete permanently), so
- * the chain is at most heading → project. Trash-adjacent surfaces stay
- * exempt on purpose: `things trash` lists directly-flagged rows, and a
- * trashed project's OWN view shows its would-be-recovered children.
- */
-const CONTAINER_UNTRASHED = `(t.heading IS NULL OR EXISTS (
-     SELECT 1 FROM TMTask hh WHERE hh.uuid = t.heading AND hh.trashed = 0))
- AND (${EFF_PROJECT} IS NULL OR EXISTS (
-     SELECT 1 FROM TMTask cc WHERE cc.uuid = ${EFF_PROJECT} AND cc.trashed = 0))`;
 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));
 }
 /**
- * Arranges view members into the UI's flat sidebar-mirroring order: the
- * area-less block first (direct to-dos, then each top-level project followed
- * by its members), then each area by its sidebar index (direct to-dos, then
- * its projects). Project and area order here mirrors the sidebar exactly —
- * both read the same "index" columns.
+ * 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.
  */
-function groupBySidebar(db, items) {
-    if (items.length === 0)
-        return [];
-    const inList = (n) => Array.from({ length: n }, () => "?").join(", ");
-    // Headed children: resolve heading -> project.
-    const headingUuids = [
-        ...new Set(items.flatMap((i) => (i.type === "to-do" && i.heading !== null ? [i.heading.uuid] : []))),
-    ];
-    const headingProject = new Map();
-    if (headingUuids.length > 0) {
-        for (const row of db
-            .prepare(`SELECT uuid, project FROM TMTask WHERE uuid IN (${inList(headingUuids.length)})`)
-            .all(...headingUuids)) {
-            headingProject.set(row.uuid, row.project);
-        }
-    }
-    const effProject = (i) => i.type !== "to-do"
-        ? null
-        : (i.project?.uuid ??
-            (i.heading !== null ? (headingProject.get(i.heading.uuid) ?? null) : null));
-    // Sidebar rank + title for areas; index + area for every referenced project
-    // (a tag-filtered list can contain a child whose project row didn't match).
-    const areaRows = db
-        .prepare(`SELECT uuid, title, "index" FROM TMArea ORDER BY "index" ASC, uuid ASC`)
-        .all();
-    const areaRank = new Map(areaRows.map((a, rank) => [a.uuid, rank]));
-    const areaTitle = new Map(areaRows.map((a) => [a.uuid, a.title ?? ""]));
-    const projectUuids = [
-        ...new Set([
-            ...items.flatMap((i) => (i.type === "project" ? [i.uuid] : [])),
-            ...items.flatMap((i) => {
-                const p = effProject(i);
-                return p === null ? [] : [p];
-            }),
-        ]),
-    ];
-    const projectMeta = new Map();
-    if (projectUuids.length > 0) {
-        for (const row of db
-            .prepare(`SELECT uuid, "index", area FROM TMTask WHERE uuid IN (${inList(projectUuids.length)})`)
-            .all(...projectUuids)) {
-            projectMeta.set(row.uuid, { index: row.index ?? 0, area: row.area });
-        }
-    }
-    // items arrive in SQL "index" order, so array position IS the per-container
-    // rank (the internal index is no longer exposed on the entity).
-    const sortKey = (i, pos) => {
-        const project = i.type === "project" ? i.uuid : effProject(i);
-        const meta = project === null ? undefined : projectMeta.get(project);
-        const area = i.area?.uuid ?? meta?.area ?? null;
-        return {
-            areaRank: area === null ? -1 : (areaRank.get(area) ?? areaRows.length),
-            area: area ?? "",
-            inProject: project === null ? 0 : 1,
-            projectIndex: meta?.index ?? 0,
-            project: project ?? "",
-            headerFirst: i.type === "project" ? 0 : 1,
-            pos,
-            uuid: i.uuid,
-        };
-    };
-    const keyed = items.map((item, pos) => ({ item, k: sortKey(item, pos) }));
-    keyed.sort((a, b) => a.k.areaRank - b.k.areaRank ||
-        a.k.area.localeCompare(b.k.area) ||
-        a.k.inProject - b.k.inProject ||
-        a.k.projectIndex - b.k.projectIndex ||
-        a.k.project.localeCompare(b.k.project) ||
-        a.k.headerFirst - b.k.headerFirst ||
-        a.k.pos - b.k.pos ||
-        a.k.uuid.localeCompare(b.k.uuid));
-    const sections = [];
-    for (const { item, k } of keyed) {
-        const areaUuid = k.area === "" ? null : k.area;
-        const last = sections.at(-1);
-        if (last === undefined || (last.area?.uuid ?? null) !== areaUuid) {
-            sections.push({
-                area: areaUuid === null ? null : { uuid: areaUuid, title: areaTitle.get(areaUuid) ?? "" },
-                items: [],
-            });
-        }
-        sections.at(-1)?.items.push(item);
-    }
-    return sections;
-}
-/** The UI's star marker in Anytime: the item is also a Today member. */
 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 untilSql = until === undefined ? "" : " AND t.startDate <= ?";
+    const since = filter?.since;
     const untilBinds = until === undefined ? [] : [encodePackedDate(until)];
+    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}${tf.sql}
-     ORDER BY t.startDate ASC, t."index" ASC`, [packedToday, ...untilBinds, ...tf.binds]);
-    const items = materialize(db, rows);
+     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]);
+    // 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
@@ -227,16 +285,19 @@ export function upcomingView(db, now, filter) {
     const templateRows = fetchTaskRows(db, `t.type IN (0, 1) AND t.trashed = 0 AND t.status = 0 AND ${CONTAINER_UNTRASHED}
      AND (t.rt1_recurrenceRule IS NOT NULL OR t.repeater IS NOT NULL)
      AND t.rt1_instanceCreationPaused = 0
-     AND t.rt1_nextInstanceStartDate IS NOT NULL AND t.rt1_nextInstanceStartDate > ?${until === undefined ? "" : " AND t.rt1_nextInstanceStartDate <= ?"}${tf.sql}
-     ORDER BY t.rt1_nextInstanceStartDate ASC, t."index" ASC`, [packedToday, ...untilBinds, ...tf.binds]);
+     AND t.rt1_nextInstanceStartDate IS NOT NULL AND t.rt1_nextInstanceStartDate > ?${until === undefined ? "" : " AND t.rt1_nextInstanceStartDate <= ?"}${since === undefined ? "" : " AND t.rt1_nextInstanceStartDate >= ?"}${tf.sql}
+     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 [];
-        // Only the rule-derived deadline is real: the template row's own deadline
-        // column carries app-internal sentinels (4001-01-01 observed live).
+        // Whether occurrences deadline is the TEMPLATE's property, not the rule's:
+        // a deadline-less template (repeating.deadlined false) spawns instances
+        // with NO deadline even for fixed ts=0 rules — its rt1_recurrenceRule is
+        // byte-identical to a deadlined ts=0 rule (oddities §8a, UI1 2026-07-12).
+        const deadlined = template.repeating.deadlined === true;
         let rule = null;
         const raw = rawByUuid.get(template.uuid);
         if (raw !== null && raw !== undefined) {
@@ -248,40 +309,30 @@ export function upcomingView(db, now, filter) {
             }
         }
         if (rule === null || horizon === 1 || rule.type !== "fixed") {
-            // Corpus-validated 2026-07-11 (1,900+ live instances): FIXED rules
-            // always deadline their occurrences at the event date — start − ts,
-            // INCLUDING ts=0 (deadline = the start date itself; birthday-style
-            // repeats). After-completion rules deadline only when ts < 0.
-            const deadline = rule !== null && (rule.type === "fixed" || rule.startOffsetDays < 0)
-                ? addDaysIso(startDate, -rule.startOffsetDays)
-                : null;
+            // Deadlined templates deadline the occurrence at the event date
+            // (start − ts, incl. ts=0); deadline-less ones carry no deadline.
+            const deadline = rule !== null && deadlined ? addDaysIso(startDate, -rule.startOffsetDays) : null;
             return [{ ...template, startDate, deadline }];
         }
         // horizon > 1: later occurrences PROJECTED from the decoded rule,
         // anchored on the app's own materialized next instance. The until bound
         // clips projections the same way it clips stored rows.
-        return projectOccurrences(rule, startDate, {
+        return (projectOccurrences(rule, startDate, {
             count: horizon,
             ...(until !== undefined && { until }),
-        })
+        }, deadlined)
             .filter((o) => until === undefined || o.startDate <= until)
+            .filter((o) => since === undefined || o.startDate >= since)
+            // oxlint-disable-next-line no-map-spread -- building fresh occurrence objects, not mutating
             .map((o) => ({
             ...template,
             startDate: o.startDate,
             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
@@ -291,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 {
@@ -305,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.
@@ -317,11 +371,24 @@ 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]);
-    return 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.
+    return sections.map((s) => ({
+        area: s.area,
+        items: [
+            ...s.items.filter((i) => i.type === "project"),
+            ...s.items.filter((i) => i.type === "to-do" && !isChild(i)),
+            ...s.items.filter(isChild),
+        ],
+    }));
 }
-export function logbookView(db, options) {
-    const limit = options?.limit ?? 100;
+export function logbookView(db, now, options) {
+    const cap = options?.limit === null ? null : (options?.limit ?? 100);
     const tf = tagFilter(db, options);
     const where = [];
     const binds = [];
@@ -344,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 LIMIT ?`, [logBoundary(db).getTime() / 1000, ...binds, ...tf.binds, limit]);
-    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) {
-    const limit = options?.limit ?? 200;
+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 LIMIT ?`, [limit]);
-    return materialize(db, rows);
+     ORDER BY t.userModificationDate DESC${cap === null ? "" : " LIMIT ?"}`, cap === null ? [] : [cap]);
+    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
@@ -374,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
@@ -437,22 +523,72 @@ 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) {
-    const limit = options.limit ?? 200;
+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 LIMIT ?`, [sinceEpoch, limit]);
-    return materialize(db, rows).map((item, i) => ({
+     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, logBoundary(db, now)).map((item, i) => ({
         ...item,
         changeKind: (rows[i]?.creationDate ?? 0) > sinceEpoch ? "created" : "modified",
     }));
 }
-export function searchView(db, query, options) {
-    const limit = options?.limit ?? 50;
-    const needle = `%${query}%`;
-    const where = [`${NOT_TEMPLATE} AND (t.title LIKE ? OR t.notes LIKE ?)`];
-    const binds = [needle, needle];
-    where.push(options?.type === "to-do"
+/**
+ * The did-you-mean fallback search: a case-insensitive SUBSTRING match on
+ * TITLES ONLY (never notes, headings, or checklist items), across areas,
+ * projects, and to-dos — open + untrashed only. Ordered per the house
+ * doctrine: containers (areas, then projects) first, then to-dos; within a
+ * group active rows precede someday rows, then most-recently-modified. `type`
+ * scopes to a single class (the typed-namespace paths). Results are capped
+ * (default 10); `total` reports the pre-cap match count so the caller can
+ * append a "… n more" tail.
+ */
+const somedayRank = (i) => (i.start === "someday" ? 1 : 0);
+/** Lite-search order within a task group: active before someday, then most-recently-modified. */
+function byStatusThenRecent(a, b) {
+    return somedayRank(a) - somedayRank(b) || b.modified.getTime() - a.modified.getTime();
+}
+export function liteTitleSearch(db, query, options, now) {
+    const cap = options?.limit ?? 10;
+    const type = options?.type;
+    const needle = query.toLowerCase();
+    const areas = type === undefined || type === "area"
+        ? areasView(db)
+            .filter((a) => a.title.toLowerCase().includes(needle))
+            .toSorted((a, b) => a.title.localeCompare(b.title))
+        : [];
+    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 ?${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);
+    const ordered = [
+        ...areas.map((area) => ({ kind: "area", area })),
+        ...projects.map((task) => ({ kind: "task", task })),
+        ...todos.map((task) => ({ kind: "task", task })),
+    ];
+    return { candidates: ordered.slice(0, cap), total: ordered.length };
+}
+export function searchView(db, query, options, now) {
+    const cap = options?.limit === null ? null : (options?.limit ?? 50);
+    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.
+    const scope = [NOT_TEMPLATE];
+    const scopeBinds = [];
+    scope.push(options?.type === "to-do"
         ? "t.type = 0"
         : options?.type === "project"
             ? "t.type = 1"
@@ -462,24 +598,65 @@ export function searchView(db, query, options) {
     // container chain (derived trash, A24B), not just the row's own flag.
     if (options?.all !== true) {
         const statuses = options?.logged === true ? "(0, 2, 3)" : "(0)";
-        where.push(`t.status IN ${statuses}`);
+        scope.push(`t.status IN ${statuses}`);
         if (options?.trashed !== true)
-            where.push(`t.trashed = 0 AND ${CONTAINER_UNTRASHED}`);
+            scope.push(`t.trashed = 0 AND ${CONTAINER_UNTRASHED}`);
     }
     if (options?.project !== undefined) {
         const uuid = resolveProjectUuid(db, options.project);
         // Children incl. headed ones (heading rows carry the project link).
-        where.push("(t.project = ? OR t.heading IN (SELECT uuid FROM TMTask WHERE type = 2 AND project = ?))");
-        binds.push(uuid, uuid);
+        scope.push("(t.project = ? OR t.heading IN (SELECT uuid FROM TMTask WHERE type = 2 AND project = ?))");
+        scopeBinds.push(uuid, uuid);
     }
     if (options?.area !== undefined) {
         const uuid = resolveAreaUuid(db, options.area);
-        where.push("t.area = ?");
-        binds.push(uuid);
+        scope.push("t.area = ?");
+        scopeBinds.push(uuid);
     }
     const tf = tagFilter(db, options);
-    const rows = fetchTaskRows(db, `${where.join(" AND ")}${tf.sql}
-     ORDER BY t.userModificationDate DESC LIMIT ?`, [...binds, ...tf.binds, limit]);
-    return materialize(db, rows);
+    // Needle matches: title OR notes. No SQL LIMIT — ranking runs before the cap.
+    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, 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 });
+    }
+    // Heading titles are treated as if they lived in the parent PROJECT's notes:
+    // a heading-title match surfaces the parent project (never a bare heading
+    // row), credited at the heading-via-project field rank. A to-do-only search
+    // has no project rows, so headings do not apply there.
+    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 ?${LIKE_ESCAPE}`)
+            .all(needle);
+        const headingTitleFor = new Map();
+        for (const h of headingRows) {
+            if (!headingTitleFor.has(h.projectUuid))
+                headingTitleFor.set(h.projectUuid, h.title ?? "");
+        }
+        // Surface only the projects NOT already matched by their own title/notes
+        // (a higher-ranked field already represents them), and only those passing
+        // the view's scope.
+        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}${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) ?? "",
+                };
+                // Annotate the freshly materialized entity in place (owned here).
+                item.matchedVia = matchedVia;
+                matches.set(item.uuid, { item, field: "heading", matchedVia });
+            }
+        }
+    }
+    const ranked = [...matches.values()].toSorted(compareSearchMatches);
+    const sliced = cap === null ? ranked : ranked.slice(0, cap);
+    return sliced.map((m) => m.item);
 }
 //# sourceMappingURL=views.js.map