things-api 0.8.0 → 0.10.0

package/dist/model/serialize.js

@@ -0,0 +1,80 @@
+/**
+ * The emit-time omit-empty transform for entity/data payloads (the "Omit-empty"
+ * contract in docs/design/contracts.md). Applied at the JSON emit boundary of
+ * the read surfaces ONLY — the CLI `--json` read envelope (src/cli/read-driver.ts)
+ * and the MCP read tool results (src/mcp/server.ts) — never to the in-memory
+ * entities the library returns, and never to the error envelope.
+ *
+ * The rule: an ENTITY object omits any optional field whose value is empty —
+ * null, undefined, "" (empty string), or [] (empty array). A consumer MUST
+ * read an absent key as unset/empty/default and MUST NOT distinguish absent
+ * from empty. Values that are semantically meaningful when "empty" are kept:
+ * booleans (a real `false`) and numbers (a `0` count) are never omitted, and
+ * the identity keys ({@link IDENTITY_KEYS}) are always present.
+ *
+ * Why entity-scoped, not a blanket deep prune: the same key means opposite
+ * things on different shapes. A to-do's `area: null` is "no area" (omit), but a
+ * sidebar section's `area: null` is the load-bearing "top-level/loose block"
+ * discriminant (keep). So pruning is gated to the recognized entity shapes;
+ * the view scaffolding that CARRIES entities (today/evening split, project/area
+ * card sections, grouped blocks) is structural and passes through untouched —
+ * only its nested entities are pruned.
+ */
+/**
+ * Keys never omitted from an entity even when empty: the identity a consumer
+ * always keys on. `uuid`/`type` are never empty in practice; `title`/`name`
+ * can be "" (an untitled to-do) and MUST still be present.
+ */
+const IDENTITY_KEYS = new Set(["uuid", "type", "title", "name"]);
+/** A to-do/project/heading row: uuid + a task-type discriminant. */
+function isTaskEntity(o) {
+    return (typeof o["uuid"] === "string" &&
+        (o["type"] === "to-do" || o["type"] === "project" || o["type"] === "heading"));
+}
+/** An area: uuid + the `visible` flag (distinguishes it from a bare Ref). */
+function isAreaEntity(o) {
+    return typeof o["uuid"] === "string" && typeof o["visible"] === "boolean";
+}
+/** A taxonomy tag row (uuid-free): a title plus the parent/shortcut columns. */
+function isTagEntity(o) {
+    return (o["uuid"] === undefined && typeof o["title"] === "string" && "parent" in o && "shortcut" in o);
+}
+/** Whether this object's empty optional fields should be omitted. */
+function prunesEmpties(o) {
+    return isTaskEntity(o) || isAreaEntity(o) || isTagEntity(o);
+}
+/** null | undefined | "" | [] — the values an entity omits the key for. */
+function isEmpty(v) {
+    return v === null || v === undefined || v === "" || (Array.isArray(v) && v.length === 0);
+}
+function prune(value) {
+    if (value === null || value === undefined)
+        return value;
+    // Dates serialize to ISO strings via JSON.stringify — never recurse into them.
+    if (value instanceof Date)
+        return value;
+    if (Array.isArray(value))
+        return value.map(prune);
+    if (typeof value === "object") {
+        const o = value;
+        const omitEmpties = prunesEmpties(o);
+        const out = {};
+        for (const key of Object.keys(o)) {
+            const v = o[key];
+            if (omitEmpties && !IDENTITY_KEYS.has(key) && isEmpty(v))
+                continue;
+            out[key] = prune(v);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Return a deep copy of `payload` with every entity's empty optional fields
+ * omitted (the "Omit-empty" contract). Pure — the input is never mutated, so
+ * the human-render path keeps the full entity beside the JSON emit.
+ */
+export function omitEmpty(payload) {
+    return prune(payload);
+}
+//# sourceMappingURL=serialize.js.map

package/dist/model/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../../src/model/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;GAIG;AACH,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAItF,oEAAoE;AACpE,SAAS,YAAY,CAAC,CAAM;IAC1B,OAAO,CACL,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ;QAC7B,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,OAAO,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,SAAS,CAAC,CAC9E,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,SAAS,YAAY,CAAC,CAAM;IAC1B,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,SAAS,CAAC;AAC5E,CAAC;AAED,gFAAgF;AAChF,SAAS,WAAW,CAAC,CAAM;IACzB,OAAO,CACL,CAAC,CAAC,MAAM,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,QAAQ,IAAI,CAAC,IAAI,UAAU,IAAI,CAAC,CAC9F,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,SAAS,aAAa,CAAC,CAAM;IAC3B,OAAO,YAAY,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,2EAA2E;AAC3E,SAAS,OAAO,CAAC,CAAU;IACzB,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,SAAS,KAAK,CAAC,KAAc;IAC3B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxD,+EAA+E;IAC/E,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,KAAY,CAAC;QACvB,MAAM,WAAW,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;QACrC,MAAM,GAAG,GAAQ,EAAE,CAAC;QACpB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACjC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YACjB,IAAI,WAAW,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC;gBAAE,SAAS;YACnE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAI,OAAU;IACrC,OAAO,KAAK,CAAC,OAAO,CAAM,CAAC;AAC7B,CAAC"}

package/dist/model/when-sugar.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The `<when>@<time>` scheduling sugar, shared by every consumer surface. A
+ * single string like `2026-07-05@09:00` (or `today@evening`-style keyword +
+ * time) carries BOTH the schedule and its reminder; this splits it into the
+ * separate `when` + `reminder` the write pipeline expects, or reports the one
+ * usage error. Extracted from the CLI so the CLI and MCP validate the suffix
+ * identically instead of each re-deriving it — see docs/design/architecture.md
+ * (Consumer boundary).
+ *
+ * Pure: it neither mutates its input nor validates the DATE/TIME values (the
+ * pipeline does that downstream) — it only owns the `@` split and the two
+ * usage messages. The flag/parameter LABELS are injected so each surface keeps
+ * its own vocabulary (`--when`/`--reminder` vs `when`/`reminder`).
+ */
+/** The surface's spelling of the two parameters, interpolated into usage copy. */
+export interface WhenSugarLabels {
+    when: string;
+    reminder: string;
+}
+/** CLI flag spellings — the default, since the sugar originated there. */
+export declare const CLI_WHEN_LABELS: WhenSugarLabels;
+/** MCP tool-parameter spellings. */
+export declare const MCP_WHEN_LABELS: WhenSugarLabels;
+/**
+ * The result of inspecting a `when` value for the `@time` suffix:
+ * - `unchanged` — no suffix; pass `when` through as-is.
+ * - `split` — a valid suffix; use the split `when` + `reminder`.
+ * - `error` — a malformed suffix, or a suffix given ALONGSIDE a separate
+ *   reminder; emit `message` as a usage error.
+ */
+export type WhenSugar = {
+    kind: "unchanged";
+} | {
+    kind: "split";
+    when: string;
+    reminder: string;
+} | {
+    kind: "error";
+    message: string;
+};
+/**
+ * Split a `when` value on its `@time` suffix. `reminderProvided` reflects
+ * whether the caller ALSO passed a separate reminder — a suffix plus an
+ * explicit reminder is ambiguous and rejected. A non-string or suffix-free
+ * `when` is `unchanged`.
+ */
+export declare function splitWhenSugar(when: unknown, reminderProvided: boolean, labels?: WhenSugarLabels): WhenSugar;

package/dist/model/when-sugar.js

@@ -0,0 +1,45 @@
+/**
+ * The `<when>@<time>` scheduling sugar, shared by every consumer surface. A
+ * single string like `2026-07-05@09:00` (or `today@evening`-style keyword +
+ * time) carries BOTH the schedule and its reminder; this splits it into the
+ * separate `when` + `reminder` the write pipeline expects, or reports the one
+ * usage error. Extracted from the CLI so the CLI and MCP validate the suffix
+ * identically instead of each re-deriving it — see docs/design/architecture.md
+ * (Consumer boundary).
+ *
+ * Pure: it neither mutates its input nor validates the DATE/TIME values (the
+ * pipeline does that downstream) — it only owns the `@` split and the two
+ * usage messages. The flag/parameter LABELS are injected so each surface keeps
+ * its own vocabulary (`--when`/`--reminder` vs `when`/`reminder`).
+ */
+/** CLI flag spellings — the default, since the sugar originated there. */
+export const CLI_WHEN_LABELS = { when: "--when", reminder: "--reminder" };
+/** MCP tool-parameter spellings. */
+export const MCP_WHEN_LABELS = { when: "when", reminder: "reminder" };
+/**
+ * Split a `when` value on its `@time` suffix. `reminderProvided` reflects
+ * whether the caller ALSO passed a separate reminder — a suffix plus an
+ * explicit reminder is ambiguous and rejected. A non-string or suffix-free
+ * `when` is `unchanged`.
+ */
+export function splitWhenSugar(when, reminderProvided, labels = CLI_WHEN_LABELS) {
+    if (typeof when !== "string" || !when.includes("@"))
+        return { kind: "unchanged" };
+    const at = when.indexOf("@");
+    const date = when.slice(0, at);
+    const time = when.slice(at + 1);
+    if (date === "" || time === "" || time.includes("@")) {
+        return {
+            kind: "error",
+            message: `invalid ${labels.when} "${when}" — expected today | evening | anytime | someday | YYYY-MM-DD (set a reminder with ${labels.reminder} HH:mm)`,
+        };
+    }
+    if (reminderProvided) {
+        return {
+            kind: "error",
+            message: `${labels.when} "${when}" carries an @time suffix and ${labels.reminder} was also given — use one`,
+        };
+    }
+    return { kind: "split", when: date, reminder: time };
+}
+//# sourceMappingURL=when-sugar.js.map

package/dist/model/when-sugar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"when-sugar.js","sourceRoot":"","sources":["../../src/model/when-sugar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,eAAe,GAAoB,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;AAE3F,oCAAoC;AACpC,MAAM,CAAC,MAAM,eAAe,GAAoB,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAcvF;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAa,EACb,gBAAyB,EACzB,SAA0B,eAAe;IAEzC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAClF,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAChC,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACrD,OAAO;YACL,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,WAAW,MAAM,CAAC,IAAI,KAAK,IAAI,sFAAsF,MAAM,CAAC,QAAQ,SAAS;SACvJ,CAAC;IACJ,CAAC;IACD,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO;YACL,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,KAAK,IAAI,iCAAiC,MAAM,CAAC,QAAQ,2BAA2B;SAC5G,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AACvD,CAAC"}

package/dist/read/area-view.d.ts

@@ -6,6 +6,7 @@
  */
 import type { DatabaseSync } from "node:sqlite";
 import type { Area, IsoDateGroup, Project, Todo } from "../model/entities.ts";
+import { type ViewFilter } from "./views.ts";
 export interface AreaView {
     area: Area;
     /** Open, unscheduled/current direct to-dos, by index. */
@@ -22,5 +23,11 @@ export interface AreaView {
     logged: Todo[];
     trashed: Todo[];
 }
+/** A someday project row: open, incubated, no start date. */
+export declare const isSomedayProjectRow: (p: Project) => boolean;
+/** A future-scheduled project row (start date strictly after `todayIso`). */
+export declare const isScheduledProjectRow: (p: Project, todayIso: string) => boolean;
+/** An active project row — everything that is neither someday nor future-scheduled. */
+export declare const isActiveProjectRow: (p: Project, todayIso: string) => boolean;
 /** Resolves by uuid or unique (case-insensitive) title; throws like the ref resolvers. */
-export declare function areaView(db: DatabaseSync, ref: string, now?: Date): AreaView;
+export declare function areaView(db: DatabaseSync, ref: string, now?: Date, filter?: ViewFilter): AreaView;

package/dist/read/area-view.js

@@ -2,9 +2,25 @@ import { encodePackedDate, localToday, decodePackedDate } from "../model/dates.j
 import { mapProject, mapTodo } from "../model/mappers.js";
 import { fetchTagsForTasks, fetchTaskRows, makeRefResolver, resolveAreaUuid } from "./queries.js";
 import { logBoundary, markLogged } from "./log-boundary.js";
+import { OVERDUE } from "./predicates.js";
 import { areaTags } from "./tags.js";
+import { tagFilter } from "./views.js";
+// The area card splits its open projects into three display buckets by their
+// own schedule (the card mirrors the GUI: active projects as rows, scheduled
+// ones under Upcoming, someday ones under Someday). Closed-but-unswept projects
+// stay "active" (checked in place) — start/startDate only classify OPEN rows.
+// Shared by the bounding layer (capAreaSections keeps scheduled/someday whole
+// while capping the active rows) and the human renderer, so the split is
+// defined ONCE and the two never drift.
+/** A someday project row: open, incubated, no start date. */
+export const isSomedayProjectRow = (p) => p.status === "open" && p.start === "someday" && p.startDate === null;
+/** A future-scheduled project row (start date strictly after `todayIso`). */
+export const isScheduledProjectRow = (p, todayIso) => p.status === "open" && p.startDate !== null && p.startDate > todayIso;
+/** An active project row — everything that is neither someday nor future-scheduled. */
+export const isActiveProjectRow = (p, todayIso) => !isSomedayProjectRow(p) && !isScheduledProjectRow(p, todayIso);
 /** Resolves by uuid or unique (case-insensitive) title; throws like the ref resolvers. */
-export function areaView(db, ref, now) {
+export function areaView(db, ref, now, filter = {}) {
+    const overdue = filter.overdue === true;
     const uuid = resolveAreaUuid(db, ref);
     const row = db
         .prepare(`SELECT uuid, title, visible, "index" FROM TMArea WHERE uuid = ?`)
@@ -15,18 +31,38 @@ export function areaView(db, ref, now) {
         uuid: row.uuid,
         title: row.title ?? "",
         visible: row.visible !== 0,
-        tags: areaTags(db, uuid),
+        // Area tags by NAME only (tag uuids are internal).
+        tags: areaTags(db, uuid).map((t) => ({ title: t.title })),
     };
     const refs = makeRefResolver(db);
     const tagsOf = (rows) => fetchTagsForTasks(db, rows.map((r) => r.uuid));
     const boundary = logBoundary(db, now);
+    // OWN-DEADLINE UNIFORM: `--overdue` filters BOTH displayed row kinds by each
+    // row's OWN deadline (open, strictly before today) via the shared OVERDUE
+    // predicate — the area's child PROJECTS by the project's own deadline AND the
+    // loose to-dos by theirs. There is NO descent into project contents (an
+    // overdue to-do inside a non-overdue project never surfaces here — that is
+    // `project show --overdue`). Sections with no surviving rows collapse.
+    const overdueSql = overdue ? ` AND ${OVERDUE}` : "";
+    const overdueBinds = overdue ? [encodePackedDate(localToday(now))] : [];
+    // Tag scope (§9a): BOTH displayed row kinds — the child PROJECTS and the
+    // loose to-dos — are filtered by a tag carried DIRECTLY on the row (the
+    // container semantics). The area's own tags are inherited by every row it
+    // holds, so an inheritance-inclusive `--tag` would be vacuous; suppressing the
+    // container hop makes `--tag` mean "rows with this tag on themselves" (still
+    // descendant-expanded) and `--untagged` "rows with no direct tag". Computed
+    // once, spliced into both queries; NO descent into project contents (a child
+    // of a matching project is never inspected here). The tag binds trail each
+    // query's own binds.
+    const tf = tagFilter(db, filter, { container: true });
     // Open projects PLUS closed ones the log-move sweep has not passed — the
-    // GUI keeps those checked in place (completion ≠ logged).
+    // GUI keeps those checked in place (completion ≠ logged). Under --overdue the
+    // OVERDUE predicate's own `status = 0` narrows this to open overdue projects.
     const projectRows = fetchTaskRows(db, `t.type = 1 AND t.area = ? AND t.trashed = 0
-     AND (t.status = 0 OR t.stopDate > ?) ORDER BY t."index" ASC`, [uuid, boundary.getTime() / 1000]);
+     AND (t.status = 0 OR t.stopDate > ?)${overdueSql}${tf.sql} ORDER BY t."index" ASC`, [uuid, boundary.getTime() / 1000, ...overdueBinds, ...tf.binds]);
     const projectTags = tagsOf(projectRows);
     const projects = markLogged(projectRows.map((r) => mapProject(r, refs, projectTags.get(r.uuid) ?? [])), boundary);
-    const todoRows = fetchTaskRows(db, `t.type = 0 AND t.area = ? ORDER BY t."index" ASC`, [uuid]);
+    const todoRows = fetchTaskRows(db, `t.type = 0 AND t.area = ?${overdueSql}${tf.sql} ORDER BY t."index" ASC`, [uuid, ...overdueBinds, ...tf.binds]);
     const todoTags = tagsOf(todoRows);
     const todos = todoRows.map((r) => ({
         row: r,
@@ -40,8 +76,8 @@ export function areaView(db, ref, now) {
     const someday = [];
     const logged = [];
     const trashed = [];
-    for (const { row, todo } of todos) {
-        if (row.trashed === 1) {
+    for (const { row: todoRow, todo } of todos) {
+        if (todoRow.trashed === 1) {
             trashed.push(todo);
             continue;
         }
@@ -49,7 +85,7 @@ export function areaView(db, ref, now) {
             repeating.push(todo);
             continue;
         }
-        if (row.status !== 0) {
+        if (todoRow.status !== 0) {
             // Completion ≠ logged: closed-but-unswept items stay checked in the
             // active block, like the GUI.
             if (todo.logged)
@@ -58,14 +94,14 @@ export function areaView(db, ref, now) {
                 active.push(todo);
             continue;
         }
-        if (row.start === 2 && row.startDate === null) {
+        if (todoRow.start === 2 && todoRow.startDate === null) {
             someday.push(todo);
             continue;
         }
-        if (row.startDate !== null && row.startDate > packedToday) {
+        if (todoRow.startDate !== null && todoRow.startDate > packedToday) {
             scheduledRows.push({
-                date: decodePackedDate(row.startDate) ?? "",
-                ti: row.todayIndex ?? 0,
+                date: decodePackedDate(todoRow.startDate) ?? "",
+                ti: todoRow.todayIndex ?? 0,
                 todo,
             });
             continue;
@@ -75,7 +111,7 @@ export function areaView(db, ref, now) {
     logged.sort((a, b) => (b.stopped?.getTime() ?? 0) - (a.stopped?.getTime() ?? 0));
     const scheduled = [];
     // Within a day the UI sorts by todayIndex ASC (Upcoming drag order).
-    for (const { date, todo } of scheduledRows.sort((a, b) => a.date.localeCompare(b.date) || a.ti - b.ti)) {
+    for (const { date, todo } of scheduledRows.toSorted((a, b) => a.date.localeCompare(b.date) || a.ti - b.ti)) {
         const last = scheduled[scheduled.length - 1];
         if (last && last.date === date)
             last.items.push(todo);

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

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

package/dist/read/caps.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The one shared decision behind every surface's `--limit`/`--all` (CLI) and
+ * `limit`/`all` (MCP) cap resolution: given an explicit value, the `all`
+ * flag, and a default, decide the effective row cap. Each surface keeps its
+ * own input parsing and error emission (the CLI validates the string and
+ * writes a usage error; MCP validates via zod and returns a tool error) —
+ * only this pure conflict/default logic is shared.
+ */
+/**
+ * Resolve one cap against `all` into a row cap: `null` = every row,
+ * `"conflict"` when an explicit value combines with `all: true`, otherwise
+ * the explicit value or the default.
+ */
+export declare function resolveCap(value: number | undefined, all: boolean | undefined, defaultLimit: number): number | null | "conflict";

package/dist/read/caps.js

@@ -0,0 +1,21 @@
+/**
+ * The one shared decision behind every surface's `--limit`/`--all` (CLI) and
+ * `limit`/`all` (MCP) cap resolution: given an explicit value, the `all`
+ * flag, and a default, decide the effective row cap. Each surface keeps its
+ * own input parsing and error emission (the CLI validates the string and
+ * writes a usage error; MCP validates via zod and returns a tool error) —
+ * only this pure conflict/default logic is shared.
+ */
+/**
+ * Resolve one cap against `all` into a row cap: `null` = every row,
+ * `"conflict"` when an explicit value combines with `all: true`, otherwise
+ * the explicit value or the default.
+ */
+export function resolveCap(value, all, defaultLimit) {
+    if (all === true && value !== undefined)
+        return "conflict";
+    if (all === true)
+        return null;
+    return value ?? defaultLimit;
+}
+//# sourceMappingURL=caps.js.map

package/dist/read/caps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caps.js","sourceRoot":"","sources":["../../src/read/caps.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,KAAyB,EACzB,GAAwB,EACxB,YAAoB;IAEpB,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC3D,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO,KAAK,IAAI,YAAY,CAAC;AAC/B,CAAC"}

package/dist/read/filter-contract.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The per-view filter contract — the ONE declarative statement of which read
+ * filters each view honors, plus the shared predicates that enforce them. Both
+ * consumer surfaces (CLI commands, MCP tools) derive their per-view guards from
+ * this table instead of hand-coding view lists, so a filter's applicability is
+ * stated once and can never drift between surfaces.
+ *
+ * The table says, per view: whether the `overdue` content scope applies; what
+ * tag semantics the view carries (inheritance-inclusive `inherited`, container-
+ * direct `direct`, or `rejected` where the view has no per-row tags to filter);
+ * the bound model the view truncates under (`flat` row cap, `grouped` per-block
+ * caps, or `none`); and whether the view offers the status-widening flags
+ * (search's logged/trashed/all) that `overdue` refuses to combine with.
+ *
+ * The exact usage-error COPY stays surface-owned (consumer voice differs per
+ * surface — CLI `--tag`, MCP `tag`; docs/design/surface-copy.md): a surface
+ * hands {@link validateViewArgs} its own phrasing via {@link FilterVocab}, and
+ * this module owns only the DECISION of which message applies.
+ */
+import type { ViewFilter } from "./views.ts";
+/** Every read view whose filter applicability the contract governs. */
+export type ViewName = "today" | "inbox" | "anytime" | "someday" | "upcoming" | "logbook" | "trash" | "search" | "changes" | "projects" | "areas" | "project-show" | "area-show";
+/**
+ * How a view's tag filter behaves:
+ * - `inherited` — FLAT views: a `--tag` matches direct OR container-inherited
+ *   membership (plus hierarchy descendants).
+ * - `direct` — CONTAINER views (`project show`, `area show`): a `--tag` matches
+ *   a tag carried DIRECTLY on the row (the container's own inherited tags are
+ *   suppressed, since every child inherits them).
+ * - `rejected` — the view has no per-row tag list to filter (an area list row,
+ *   a tag list row, the changes feed); tag flags do not apply.
+ */
+export type TagSemantics = "inherited" | "direct" | "rejected";
+/** The truncation model a view bounds under. */
+export type BoundModel = "flat" | "grouped" | "none";
+/** One row of {@link FILTER_CONTRACT}: a single view's filter applicability. */
+export interface ViewFilterSpec {
+    /** Whether the `overdue` content scope (open, past-deadline) applies. */
+    readonly overdue: boolean;
+    /** The view's tag-filter semantics. */
+    readonly tag: TagSemantics;
+    /** The bound model the view truncates under. */
+    readonly bound: BoundModel;
+    /**
+     * Whether the view offers the status-widening flags (logged/trashed/all).
+     * Only `search` does; `overdue` refuses to combine with them there.
+     */
+    readonly statusWidening: boolean;
+}
+/**
+ * The single source of truth for read-filter applicability, one row per view.
+ * Consumed by both surfaces' per-view guards (CLI command actions, MCP tool
+ * handlers) so no surface hand-maintains its own view list.
+ */
+export declare const FILTER_CONTRACT: Record<ViewName, ViewFilterSpec>;
+/**
+ * The three universal tag-filter inputs in their canonical (CLI-flag) spelling.
+ * The CLI's parsed options match this verbatim; the MCP surface maps its
+ * snake_case inputs (`exact_tag`) onto it before calling the shared predicates.
+ */
+export interface TagPresence {
+    tag?: readonly string[] | undefined;
+    exactTag?: boolean | undefined;
+    untagged?: boolean | undefined;
+}
+/** True when any tag-PRESENCE flag was passed (a positive filter, not a negation). */
+export declare function hasTagPresence(a: TagPresence): boolean;
+/**
+ * True when the tag flags are mutually incoherent: the `untagged` negation
+ * inverts a tag presence, so it does not combine with a tag-presence flag. A
+ * pure predicate — each surface emits its own usage error in its own voice.
+ */
+export declare function tagFlagConflict(a: TagPresence): boolean;
+/** Build the {@link ViewFilter} tag fields from the parsed flags (empty keys omitted). */
+export declare function tagFilterFields(a: TagPresence): ViewFilter;
+/** The parsed read-filter inputs {@link validateViewArgs} inspects. */
+export interface FilterArgs extends TagPresence {
+    overdue?: boolean | undefined;
+    /** search only: the status-widening flags overdue refuses to combine with. */
+    logged?: boolean | undefined;
+    trashed?: boolean | undefined;
+    all?: boolean | undefined;
+}
+/**
+ * The surface's exact usage-error copy for each conflict {@link validateViewArgs}
+ * can detect. Built per call by the surface (it knows the view/kind and its own
+ * flag spellings), so the SHARED module decides WHICH message applies while the
+ * message text stays consumer-voiced per surface.
+ */
+export interface FilterVocab {
+    /** `untagged` combined with a tag-presence flag. */
+    untaggedConflict: string;
+    /** `overdue` passed to a view that does not honor it. */
+    overdueRejected: string;
+    /** `overdue` combined with a status-widening flag (search). */
+    overdueStatusWiden: string;
+}
+/** {@link validateViewArgs} outcome: the built filter, or the usage message to emit. */
+export type ViewValidation = {
+    ok: true;
+    filter: ViewFilter;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Validate a view's filter arguments against {@link FILTER_CONTRACT} and, when
+ * coherent, build the {@link ViewFilter} tag+overdue portion. The checks (and
+ * their precedence) live here so both surfaces stay in lockstep; the surface
+ * supplies its own exact copy via {@link FilterVocab}.
+ *
+ * Does NOT enforce tag-REJECTION (a view refusing tag flags outright): that
+ * lives at the two call sites that currently reject — the areas/projects/tags
+ * collection listers — so this stays a pure no-op for the flat/container views
+ * that merely ignore tags on a sub-path (e.g. `trash`).
+ */
+export declare function validateViewArgs(view: ViewName, args: FilterArgs, vocab: FilterVocab): ViewValidation;

package/dist/read/filter-contract.js

@@ -0,0 +1,78 @@
+/**
+ * The single source of truth for read-filter applicability, one row per view.
+ * Consumed by both surfaces' per-view guards (CLI command actions, MCP tool
+ * handlers) so no surface hand-maintains its own view list.
+ */
+export const FILTER_CONTRACT = {
+    // Current-work flat views: overdue applies, tags are inheritance-inclusive.
+    today: { overdue: true, tag: "inherited", bound: "flat", statusWidening: false },
+    inbox: { overdue: true, tag: "inherited", bound: "flat", statusWidening: false },
+    // Grouped catalogues: overdue applies, per-block caps.
+    anytime: { overdue: true, tag: "inherited", bound: "grouped", statusWidening: false },
+    someday: { overdue: true, tag: "inherited", bound: "grouped", statusWidening: false },
+    // Forward-looking / closed-item flat views: overdue deliberately does NOT apply.
+    upcoming: { overdue: false, tag: "inherited", bound: "flat", statusWidening: false },
+    logbook: { overdue: false, tag: "inherited", bound: "flat", statusWidening: false },
+    trash: { overdue: false, tag: "rejected", bound: "flat", statusWidening: false },
+    // Search: overdue applies but refuses the status-widening flags.
+    search: { overdue: true, tag: "inherited", bound: "flat", statusWidening: true },
+    // Sync feed: neither overdue nor tags apply.
+    changes: { overdue: false, tag: "rejected", bound: "flat", statusWidening: false },
+    // Projects LIST is a FLAT view — each project row filtered by its own
+    // (inheritance-inclusive) tags; overdue keeps past-deadline projects.
+    projects: { overdue: true, tag: "inherited", bound: "none", statusWidening: false },
+    // Areas LIST rows carry no deadline and no per-row tag filter.
+    areas: { overdue: false, tag: "rejected", bound: "none", statusWidening: false },
+    // Single-container views: overdue and DIRECT-tag filtering apply to children.
+    "project-show": { overdue: true, tag: "direct", bound: "grouped", statusWidening: false },
+    "area-show": { overdue: true, tag: "direct", bound: "grouped", statusWidening: false },
+};
+/** True when any tag-PRESENCE flag was passed (a positive filter, not a negation). */
+export function hasTagPresence(a) {
+    return (a.tag?.length ?? 0) > 0 || a.exactTag === true;
+}
+/**
+ * True when the tag flags are mutually incoherent: the `untagged` negation
+ * inverts a tag presence, so it does not combine with a tag-presence flag. A
+ * pure predicate — each surface emits its own usage error in its own voice.
+ */
+export function tagFlagConflict(a) {
+    return a.untagged === true && hasTagPresence(a);
+}
+/** Build the {@link ViewFilter} tag fields from the parsed flags (empty keys omitted). */
+export function tagFilterFields(a) {
+    return {
+        ...(a.tag !== undefined && a.tag.length > 0 && { tags: [...a.tag] }),
+        ...(a.exactTag === true && { exactTag: true }),
+        ...(a.untagged === true && { untagged: true }),
+    };
+}
+/**
+ * Validate a view's filter arguments against {@link FILTER_CONTRACT} and, when
+ * coherent, build the {@link ViewFilter} tag+overdue portion. The checks (and
+ * their precedence) live here so both surfaces stay in lockstep; the surface
+ * supplies its own exact copy via {@link FilterVocab}.
+ *
+ * Does NOT enforce tag-REJECTION (a view refusing tag flags outright): that
+ * lives at the two call sites that currently reject — the areas/projects/tags
+ * collection listers — so this stays a pure no-op for the flat/container views
+ * that merely ignore tags on a sub-path (e.g. `trash`).
+ */
+export function validateViewArgs(view, args, vocab) {
+    const spec = FILTER_CONTRACT[view];
+    if (tagFlagConflict(args))
+        return { ok: false, message: vocab.untaggedConflict };
+    if (args.overdue === true && !spec.overdue) {
+        return { ok: false, message: vocab.overdueRejected };
+    }
+    if (args.overdue === true &&
+        spec.statusWidening &&
+        (args.logged === true || args.trashed === true || args.all === true)) {
+        return { ok: false, message: vocab.overdueStatusWiden };
+    }
+    return {
+        ok: true,
+        filter: { ...tagFilterFields(args), ...(args.overdue === true && { overdue: true }) },
+    };
+}
+//# sourceMappingURL=filter-contract.js.map

package/dist/read/filter-contract.js.map

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

package/dist/read/log-boundary.d.ts

@@ -8,10 +8,15 @@
  * GUI Logbook share every TMTask column shape with logged history; only
  * the stopDate-vs-boundary relation differs).
  *
- * logInterval semantics: 0 = immediately, 1 = daily (VERIFIED live),
- * 2 = weekly, 3 = monthly (both assumed by analogy — lab probe queued in
- * docs/lab/probe-backlog.md), anything else = manual-only. manualLogDate
- * is the user's last explicit "log now"; it can only move the boundary
+ * logInterval semantics (GUI enum VERIFIED live in a clone, 2026-07-12,
+ * s-campaign-results.md round 3): 0 = immediately, 1 = daily, 4 = manual
+ * ("When I choose"). Things 3.22.11's "Move completed items to Logbook"
+ * dropdown offers ONLY these three — there is NO weekly or monthly option,
+ * so the `case 2`/`case 3` branches below are UNREACHABLE with the current
+ * app (kept as defensive analogues in case a future build adds them; the
+ * real manual value 4 falls to `default`, which is correct). manualLogDate
+ * is the user's last explicit "log now" (an AppleScript `log completed now`
+ * advances it to the current time — VERIFIED); it can only move the boundary
  * FORWARD past the interval's own edge.
  */
 import type { DatabaseSync } from "node:sqlite";

package/dist/read/log-boundary.js.map

@@ -1 +1 @@
-{"version":3,"file":"log-boundary.js","sourceRoot":"","sources":["../../src/read/log-boundary.ts"],"names":[],"mappings":"AAkBA,MAAM,UAAU,WAAW,CAAC,EAAgB,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE;IAC5D,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,mDAAmD,CAAC,CAAC,GAAG,EAElE,CAAC;IACd,MAAM,MAAM,GAAG,GAAG,EAAE,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtF,MAAM,UAAU,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IACjC,UAAU,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAChC,IAAI,IAAU,CAAC;IACf,QAAQ,GAAG,EAAE,WAAW,IAAI,CAAC,EAAE,CAAC;QAC9B,KAAK,CAAC;YACJ,IAAI,GAAG,GAAG,CAAC;YACX,MAAM;QACR,KAAK,CAAC;YACJ,IAAI,GAAG,UAAU,CAAC;YAClB,MAAM;QACR,KAAK,CAAC,CAAC,CAAC,CAAC;YACP,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/B,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;YACpC,IAAI,GAAG,CAAC,CAAC;YACT,MAAM;QACR,CAAC;QACD,KAAK,CAAC,CAAC,CAAC,CAAC;YACP,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/B,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACb,IAAI,GAAG,CAAC,CAAC;YACT,MAAM;QACR,CAAC;QACD;YACE,IAAI,GAAG,MAAM,IAAI,GAAG,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1D,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,UAAU,CACxB,KAAU,EACV,QAAc;IAEd,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,KAAK,MAAM,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,QAAQ,CAAC;IAC5F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"log-boundary.js","sourceRoot":"","sources":["../../src/read/log-boundary.ts"],"names":[],"mappings":"AAuBA,MAAM,UAAU,WAAW,CAAC,EAAgB,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE;IAC5D,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,mDAAmD,CAAC,CAAC,GAAG,EAElE,CAAC;IACd,MAAM,MAAM,GAAG,GAAG,EAAE,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtF,MAAM,UAAU,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IACjC,UAAU,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAChC,IAAI,IAAU,CAAC;IACf,QAAQ,GAAG,EAAE,WAAW,IAAI,CAAC,EAAE,CAAC;QAC9B,KAAK,CAAC;YACJ,IAAI,GAAG,GAAG,CAAC;YACX,MAAM;QACR,KAAK,CAAC;YACJ,IAAI,GAAG,UAAU,CAAC;YAClB,MAAM;QACR,KAAK,CAAC,CAAC,CAAC,CAAC;YACP,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/B,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;YACpC,IAAI,GAAG,CAAC,CAAC;YACT,MAAM;QACR,CAAC;QACD,KAAK,CAAC,CAAC,CAAC,CAAC;YACP,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/B,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACb,IAAI,GAAG,CAAC,CAAC;YACT,MAAM;QACR,CAAC;QACD;YACE,IAAI,GAAG,MAAM,IAAI,GAAG,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1D,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,UAAU,CACxB,KAAU,EACV,QAAc;IAEd,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,KAAK,MAAM,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,QAAQ,CAAC;IAC5F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}