things-api 0.11.0 → 0.13.0

package/dist/read/shape.js

@@ -0,0 +1,737 @@
+/**
+ * The read-payload SHAPING transform: the token-economy rules R6 and R7, the
+ * universal item-DTO reshapes (R9), and the R10 lifecycle taxonomy — applied at
+ * the JSON emit boundary of the read surfaces (the CLI `--json` read envelope,
+ * src/cli/read-driver.ts, and the MCP read tool results, src/mcp/server.ts), the
+ * same boundaries omit-empty runs at. Shaping runs BEFORE omit-empty. The
+ * human-render path keeps the full, unshaped entities, so this is JSON-only.
+ *
+ * Both R6/R7 are deterministic BY VIEW KIND / SECTION — the emitter knows whether
+ * it is inside a single-container view, a lifecycle bucket, or a mixed list —
+ * never a per-item heuristic.
+ *
+ * ## R10 — the `stage` lifecycle taxonomy (every tier, every kind incl. detail)
+ * The three former wire fields `start` / `logged` / `trashed` are DELETED from
+ * every item and replaced by ONE derived `stage` ∈ `inbox | upcoming | anytime |
+ * someday | logbook | trash` (src/read/stage.ts `deriveStage`, the single pure
+ * derivation reused by the card bucketing so `stage` can never disagree with the
+ * bucket a view puts an item in). Today/evening membership is a SEPARATE
+ * presence-keyed axis — `today: true` / `evening: true` (evening implies today) —
+ * derived in the mapper with the Today view's own two-arm predicate.
+ * - `stage` is DROPPED only where the enclosing node PROVABLY states it — the R6
+ *   rule (drop only what the node provably says). That is the stage-PURE flat
+ *   views (inbox, `anytime`, someday, logbook, trash) and the stage-named card
+ *   sub-buckets (anytime/upcoming/someday/logbook/trash, which the bucketer splits
+ *   BY stage). The `anytime` catalogue is stage-PURE (R10.2): every member is an
+ *   Anytime-view row (ANYTIME_SELF) — undated-active, arrived-active, or arrived
+ *   someday-scheduled — and an ARRIVED dated row derives `anytime` (Upcoming is
+ *   STRICTLY FUTURE, UPC1), so the field is redundant there.
+ *   `stage` is KEPT on the stage-MIXED or derived surfaces: the `upcoming` view
+ *   carries deadline-forecast stage-`anytime`/`someday` rows alongside its
+ *   future-dated stage-`upcoming` ones — dropping `stage` there would delete
+ *   non-redundant information — plus `today` (mixes upcoming + anytime-deadline
+ *   rows), search, changes, the projects/areas listings, the card NODE, and
+ *   detail.
+ * - the former `todaySection` field is RETIRED from the wire entirely (R10.1):
+ *   `todaySection: "evening"` merely duplicated the `evening: true` marker. It
+ *   remains an internal entity field (the human render and the write-verify delta
+ *   still read it); shaping deletes it from the JSON copy.
+ *
+ * ## R12 — `when`, the derived TIME-AXIS position (replaces startDate + markers)
+ * Today/evening membership and the scheduled/projected date collapse onto ONE
+ * derived, presence-keyed field `when` (src/read/stage.ts `deriveWhen`): `"today"`
+ * / `"evening"` (Today-view membership, from the SAME `today`/`evening` markers the
+ * mapper stamps — never re-derived, so `when` can never disagree with the star), a
+ * FUTURE ISO date (a strictly-future scheduled row, or a template's projected next
+ * occurrence), or absent (unscheduled + not in Today; also an unprojected template
+ * and every logged/trashed row). The doctrine line: **`stage` enumerates the
+ * sidebar BUCKETS an item lives in; `when` enumerates its TIME POSITIONS (today |
+ * evening | a future date).** Someday is deliberately NOT a `when` value (it is a
+ * bucket → stage). Tier/drop rules:
+ * - the former `today`/`evening` marker KEYS are DELETED from the wire on EVERY
+ *   tier — `when` carries the fact; the markers stay internal (they feed `when`).
+ * - the raw `startDate` is DELETED in COMPACT (a list needs the position, not the
+ *   substrate) and KEPT in FULL/DETAIL beside `when` — different facts: `startDate`
+ *   = what is stored, `when` = where it sits.
+ * - a template's `repeating.nextOccurrence` is GONE from the wire — `when` replaces
+ *   it (same fact, one word); an unprojected template has no `when`.
+ * - `when` is KEPT on every row it is present on. (The read-shape doctrine
+ *   flattened the card `upcoming` date-groups into the project-/area-view flat
+ *   `items[]`, so no enclosing node states the position anymore.) It rides the
+ *   today view's flat `items[]` (Today-proper vs This-Evening), the project-/area-
+ *   view `items[]`, and the flat `upcoming`/`anytime`/`inbox`/`someday` catalogues,
+ *   search, changes (a deadline-pulled row reads `when: "today"` in the mixed
+ *   search/changes surfaces, informatively; note R13 re-files it to stage `anytime`
+ *   and the flat inbox/someday views now EXCLUDE it — it appears in the `anytime`
+ *   catalogue instead, `when: "today"` kept, stage dropped as pure).
+ *
+ * ## R13 — provisional Today members + GUI-faithful pulled-row membership
+ * BANNER1 / BANNER1b (docs/lab/banner1-research.md). Two coupled facts:
+ * - **`provisional: true`** — a presence-keyed marker on every Today member the GUI
+ *   pips / counts in the "You have N new to-dos" banner: a Today member NOT yet
+ *   materialized (`start != active OR startDate IS NULL`, BANNER1 L1). Derived from
+ *   the SAME today/evening markers + fields the stage/`when` axes use (never
+ *   re-derived). Emitted on EVERY tier, NEVER dropped (the banner is not a section,
+ *   so no node implies it). Absent on non-Today rows and on materialized ones.
+ *   Read-only: the app clears it by materializing the row on banner-OK, a GUI-only
+ *   side effect our read cannot perform (watchers beware).
+ * - **stage `anytime` for a deadline pull** — a due-deadline pull re-files an undated
+ *   Inbox/Someday row into Anytime (deriveStage step 2½, L-A). So EVERY Today member
+ *   derives stage `anytime`, and the today view's flat `items[]` is stage-PURE →
+ *   `stage` is DROPPED there (TODAY_ITEM_DROP) while `when` is KEPT. The flat
+ *   someday/inbox views EXCLUDE pulled rows and the anytime view INCLUDES them
+ *   (src/read/views.ts + predicates.ts DEADLINE_PULLED) — GUI fidelity.
+ *
+ * ## Universal item-DTO reshapes (R9 — EVERY tier, EVERY read kind incl. detail)
+ * - **checklist nesting** — flat counts → presence-keyed `checklist: {open,total}`.
+ * - **todos counts** — a project's flat leaf-action counts → presence-keyed
+ *   `todos: {open, total}` (omit when total 0).
+ * - **repeating template/instance split (R11)** — the wire drops the
+ *   `isTemplate`/`isInstance` discriminators; key presence carries the fact. A
+ *   TEMPLATE keeps a nested `repeating: {paused?, deadlined?, rule?,
+ *   latestInstance?}` — the series object (rule config + backward pointer +
+ *   state flags); presence MEANS template. The forward pointer `nextOccurrence`
+ *   moved to the top-level `when` (R12 — a template's projected date IS its time
+ *   position); `latestInstance` is detail-only (SL1). An INSTANCE keeps a flat
+ *   `instanceOf: <templateUuid>` and no `repeating`. A plain row keeps neither.
+ *   See {@link reshapeRepeatingWire}.
+ * - **string tags** — `tags`/`inheritedTags` become plain arrays of names.
+ * - **one project key** — a headed item's owning project (formerly
+ *   `headingProject`) is merged into `project`; `headingProject` never appears.
+ *
+ * ## R6 — no-redundant-ancestry (both tiers)
+ * project-view children drop `project`+`area` (heading-group members also drop
+ * `heading`); area-view children/project-cards drop `area`; anytime/someday
+ * section items drop `area`. Mixed lists keep every ref. (In the COMPACT tier the
+ * `heading` ref is additionally dropped everywhere — R7.)
+ *
+ * ## R7 — named detail tiers (compact | full)
+ * List contexts default to COMPACT; `detail`/`show` and `--full` / `full:true`
+ * use FULL. Compact drops `created`/`modified`, the full `notes` string (a
+ * presence-keyed `hasNotes: true` marks a row with notes), and the `heading` ref;
+ * `status` is omitted when `open`. FULL keeps them but still applies R6, the
+ * universal reshapes, and R10.
+ */
+import { deriveStage, deriveWhen, whenIsProvisional } from "./stage.js";
+/** The DB-less default: assume every title round-trips (bare title, no uuid sibling). */
+const ALWAYS_ROUND_TRIPS = { roundTrips: () => true };
+/** The uuid of a `{uuid,title}` container Ref, or undefined for a non-object / string. */
+function refUuid(v) {
+    if (v !== null && typeof v === "object" && typeof v["uuid"] === "string") {
+        return v["uuid"];
+    }
+    return undefined;
+}
+/**
+ * Whether a still-unflattened container Ref carries the repeating-TEMPLATE mark.
+ * Only project/container refs ever set it (area/heading refs never do — see
+ * entities.Ref), so this reads true only for a template PROJECT container.
+ */
+function refIsTemplate(v) {
+    return v !== null && typeof v === "object" && v["isRepeatingTemplate"] === true;
+}
+/**
+ * Flatten ONE container ref `o[key]` from a `{uuid,title}` object to its bare
+ * TITLE string, adding a flat sibling `o[uuidKey]` = the full uuid ONLY when the
+ * round-trip law demands it: `forceUuid` (the FULL/detail tier — uuid siblings
+ * unconditional) OR the bare title does not resolve back to this exact entity
+ * (`!promoter.roundTrips`). A null/absent ref, or one already flattened to a
+ * string, is left untouched. The container's `isRepeatingTemplate` marker (a
+ * TTY-render disambiguator on the internal entity) does not survive the flatten
+ * — the human render reads the unshaped entity. {@link shapeItem} re-emits that
+ * fact for the JSON container PROJECT as the flat presence-keyed sibling
+ * `projectIsTemplate: true` BEFORE this flatten runs.
+ */
+function flattenRef(o, key, uuidKey, kind, forceUuid, promoter, projectUuid) {
+    const ref = o[key];
+    if (ref === null || typeof ref !== "object")
+        return; // absent, or already a bare string
+    const r = ref;
+    const uuid = typeof r["uuid"] === "string" ? r["uuid"] : "";
+    const title = typeof r["title"] === "string" ? r["title"] : "";
+    o[key] = title;
+    if (forceUuid || !promoter.roundTrips(kind, title, uuid, projectUuid))
+        o[uuidKey] = uuid;
+}
+/**
+ * Fold the flat `tags` / `inheritedTags` arrays of `{title}` objects into plain
+ * arrays of tag NAMES (universal across tiers and kinds). Tag uuids were never
+ * on the wire; the title is the identity. A missing key is left missing; an
+ * empty array stays `[]` (omit-empty prunes it later).
+ */
+function flattenTags(o) {
+    for (const key of ["tags", "inheritedTags"]) {
+        const v = o[key];
+        if (!Array.isArray(v))
+            continue;
+        o[key] = v.map((t) => t !== null && typeof t === "object" && "title" in t ? t["title"] : t);
+    }
+}
+/**
+ * Reshape the flat checklist counts (and, on a `detail` read, the items array)
+ * into ONE presence-keyed `checklist` object — universal across tiers and kinds.
+ * No checklist → the `checklist` key is absent entirely; otherwise
+ * `{open, total}`, plus `items` when the source carried them (detail reads).
+ */
+function reshapeChecklist(o) {
+    const total = typeof o["checklistItemsCount"] === "number" ? o["checklistItemsCount"] : 0;
+    const open = typeof o["openChecklistItemsCount"] === "number" ? o["openChecklistItemsCount"] : 0;
+    const items = o["checklist"]; // ChecklistItem[] on a detail read; absent on list rows
+    delete o["checklistItemsCount"];
+    delete o["openChecklistItemsCount"];
+    delete o["checklist"];
+    const hasItems = Array.isArray(items) && items.length > 0;
+    if (total === 0 && !hasItems)
+        return; // no checklist → omit the key
+    const cl = { open, total };
+    if (Array.isArray(items))
+        cl["items"] = items;
+    o["checklist"] = cl;
+}
+/**
+ * Reshape a project's flat leaf-action counts into ONE presence-keyed `todos`
+ * object — universal across tiers and kinds, mirroring {@link reshapeChecklist}.
+ * The source columns are the app-maintained materialized child counts
+ * (`untrashedLeafActionsCount` / `openUntrashedLeafActionsCount`), which count
+ * to-do children only (headings and checklist items excluded by construction).
+ * No to-do children (total 0) → the `todos` key is absent entirely; otherwise
+ * `{open, total}`. A no-op on to-dos (they carry no such columns).
+ */
+function reshapeTodos(o) {
+    const total = typeof o["untrashedLeafActionsCount"] === "number"
+        ? o["untrashedLeafActionsCount"]
+        : 0;
+    const open = typeof o["openUntrashedLeafActionsCount"] === "number"
+        ? o["openUntrashedLeafActionsCount"]
+        : 0;
+    delete o["untrashedLeafActionsCount"];
+    delete o["openUntrashedLeafActionsCount"];
+    if (total === 0)
+        return; // presence-keyed: no to-do children → omit the key
+    o["todos"] = { open, total };
+}
+/**
+ * R11 — rewrite the internal `repeating` block into the wire's template/instance
+ * split, mutating `o` in place. The internal entity carries the full
+ * RepeatingInfo (`isTemplate`/`isInstance`/`templateUuid`/…); the wire loses the
+ * `isTemplate`/`isInstance` discriminators entirely and instead lets KEY
+ * PRESENCE carry the fact:
+ *
+ * - **Template** (`isTemplate`) → a nested `repeating` object — the series state
+ *   `{paused?, deadlined?, rule?, latestInstance?}`. Presence of `repeating` MEANS
+ *   template (an unadorned template emits `repeating: {}` — a bare `{}` is NOT
+ *   pruned by omit-empty, so the presence signal survives). The inner false
+ *   booleans are default-pruned (presence-keyed). The forward pointer
+ *   `nextOccurrence` moved OUT to the top-level `when` (R12 — a template's
+ *   projected date IS its time position); `rule` and `latestInstance` stay
+ *   detail-only (populated by src/read/detail.ts on `entity.repeating`);
+ *   `latestInstance` is the backward pointer symmetric to `when`.
+ * - **Instance** (`isInstance`) → a flat presence-keyed `instanceOf:
+ *   <templateUuid>` and NO `repeating` object. Presence of `instanceOf` MEANS
+ *   instance.
+ * - **Plain** (neither) → neither key.
+ */
+function reshapeRepeatingWire(o) {
+    const rep = o["repeating"];
+    delete o["repeating"];
+    if (rep === null || typeof rep !== "object")
+        return;
+    const r = rep;
+    if (r["isTemplate"] === true) {
+        const out = {}; // presence MEANS template — a bare {} survives omit-empty
+        if (r["paused"] === true)
+            out["paused"] = true;
+        if (r["deadlined"] === true)
+            out["deadlined"] = true;
+        if (r["rule"] != null)
+            out["rule"] = r["rule"]; // detail read only
+        // The SL1 "Show Latest" pick — detail-only; the backward pointer symmetric to
+        // the top-level `when` (the forward pointer, R12).
+        if (typeof r["latestInstance"] === "string")
+            out["latestInstance"] = r["latestInstance"];
+        o["repeating"] = out;
+    }
+    else if (r["isInstance"] === true) {
+        if (typeof r["templateUuid"] === "string")
+            o["instanceOf"] = r["templateUuid"];
+    }
+}
+/** The R10 stage input read straight off a materialized task entity. */
+function stageOf(s) {
+    const repeating = s["repeating"];
+    const isTemplate = repeating !== null &&
+        typeof repeating === "object" &&
+        repeating["isTemplate"] === true;
+    return deriveStage({
+        trashed: s["trashed"] === true,
+        logged: s["logged"] === true,
+        start: s["start"],
+        startDate: s["startDate"] ?? null,
+        repeating: { isTemplate },
+        // The presence-keyed Today marker (stamped at materialize with the response
+        // clock) discriminates an ARRIVED dated row (→ anytime) from a strictly-
+        // future one (→ upcoming). Read BEFORE the marker is stripped downstream.
+        today: s["today"] === true,
+    });
+}
+/** The R12 `when` input read straight off a materialized task entity (given its stage). */
+function whenOf(s, stage) {
+    const repeating = s["repeating"];
+    const isTemplate = repeating !== null &&
+        typeof repeating === "object" &&
+        repeating["isTemplate"] === true;
+    const nextOccurrence = isTemplate && typeof repeating["nextOccurrence"] === "string"
+        ? repeating["nextOccurrence"]
+        : null;
+    return deriveWhen({
+        stage,
+        // The SAME presence-keyed markers stageOf reads — never re-derived, so a
+        // `when` of today/evening can never disagree with Today-view membership.
+        today: s["today"] === true,
+        evening: s["evening"] === true,
+        startDate: s["startDate"] ?? null,
+        repeating: { isTemplate, nextOccurrence },
+    });
+}
+/**
+ * Shape ONE task entity (to-do or project): the universal reshapes, the R10/R12
+ * stage/`when` rewrite, then the R6 ancestry drops, then — when `compact` — the
+ * R7 default-pruning. A shallow copy is taken so unknown sibling keys
+ * (`changeKind` on a changes row, `match` on a search hit) pass through
+ * untouched. Non-task values (areas, tags, refs, headings) are returned as-is.
+ */
+function shapeItem(src, drop, compact, promoter) {
+    if (src === null || typeof src !== "object")
+        return src;
+    const s = src;
+    const type = s["type"];
+    if (type !== "to-do" && type !== "project")
+        return src; // not a shaped entity
+    const stage = stageOf(s); // from the ORIGINAL fields, before any reshape
+    const when = whenOf(s, stage); // R12 — derived from the same fields + markers
+    // R13 (BANNER1 law L-B): a Today member is PROVISIONAL — the GUI pips it and
+    // counts it in the "You have N new to-dos" banner — until the app MATERIALIZES
+    // it (start:=1, startDate:=today). Presence-keyed marker, derived from the SAME
+    // inputs as the stage/`when` axes (never an independent re-derivation): the row
+    // is a Today member (via the today/evening markers `whenOf` reuses — so it can
+    // never disagree with the star) AND not yet materialized (BANNER1 L1:
+    // `start != active OR startDate IS NULL`). Templates are never Today members,
+    // so they never mark. NEVER dropped by any view/section — the banner is not a
+    // section, so no enclosing node implies it. The app rewrites start/startDate
+    // when the user acknowledges the banner; that is a GUI-only side effect our
+    // read cannot clear (watchers beware — see contract.md `provisional`).
+    const provisional = whenIsProvisional(when, s["start"], s["startDate"] ?? null);
+    const o = { ...s };
+    // R9 universal reshapes (every tier, every kind incl. detail).
+    reshapeChecklist(o);
+    reshapeTodos(o);
+    flattenTags(o);
+    reshapeRepeatingWire(o);
+    if (o["project"] == null && o["headingProject"] != null)
+        o["project"] = o["headingProject"];
+    delete o["headingProject"];
+    // R10 — the three lifecycle fields are replaced by the one derived `stage`.
+    delete o["start"];
+    delete o["logged"];
+    delete o["trashed"];
+    // R10.1 — `todaySection` is retired from the wire (it duplicated `evening`);
+    // the internal entity keeps it for the render / write-verify paths.
+    delete o["todaySection"];
+    if (drop.stage !== true)
+        o["stage"] = stage;
+    // R12 — the today/evening marker KEYS are replaced by the derived `when` on
+    // EVERY tier (they never appear on the wire); `when` is emitted on every row it
+    // is present on (since the read-shape doctrine flattened the card date-groups,
+    // no enclosing node states the position anymore — the flat lists carry it).
+    delete o["today"];
+    delete o["evening"];
+    // §9n — a reminder byte is presentation-dead once its `startDate` goes strictly
+    // past: the GUI hides the bell but never clears the byte. The materialize-time
+    // `reminderLive` marker (mappers, via `reminderIsLive` under the response clock)
+    // says whether the stored reminder still renders; drop the `reminder` key when
+    // it does not, mirroring the GUI. The marker itself never rides the wire.
+    if (o["reminderLive"] !== true)
+        delete o["reminder"];
+    delete o["reminderLive"];
+    if (drop.when !== true && when !== undefined)
+        o["when"] = when;
+    // R13 — the provisional banner marker (never dropped; presence-keyed).
+    if (provisional)
+        o["provisional"] = true;
+    // The owning project's uuid scopes the heading round-trip (headings resolve
+    // within their project). Captured BEFORE the R6 project-drop so a project-view
+    // LOGBOOK row — whose `project` is dropped as redundant, yet which KEEPS its
+    // heading ref (drop.keepHeading) — can still promote its `headingUuid` in the
+    // project's scope.
+    const projectUuid = refUuid(o["project"]);
+    // R6 — drop redundant ancestry (both tiers).
+    if (drop.project === true)
+        delete o["project"];
+    if (drop.area === true)
+        delete o["area"];
+    if (drop.heading === true)
+        delete o["heading"];
+    // Absent `type` = to-do — omit it on to-do rows (project/heading keep theirs).
+    if (o["type"] === "to-do")
+        delete o["type"];
+    // Flatten the surviving container refs to bare TITLE strings, adding a flat
+    // `*Uuid` sibling per the round-trip law (FULL tier: unconditional; compact:
+    // only when the title would not resolve back to this entity). The `heading`
+    // ref is compact-dropped below (except drop.keepHeading), so it is flattened
+    // on the FULL tier OR when a logbook row explicitly keeps it.
+    const forceUuid = !compact;
+    // The container PROJECT's repeating-TEMPLATE fact — the JSON twin of the TTY ↻
+    // glyph (src/cli/render.ts). flattenRef discards the internal ref's
+    // `isRepeatingTemplate` marker, so re-emit it here as a flat presence-keyed
+    // sibling of the `project` ref (never `false`), riding wherever `project`
+    // rides. A heading-nested row already merged its owning project into `project`
+    // above, so direct AND headed template children mark; the R6 project-drop
+    // above already removed `project` where the view implies it, so a project-view
+    // child carries no orphaned marker. Both tiers — it is a correctness signal,
+    // not detail. Only project refs ever carry the flag (area/heading never do).
+    if (refIsTemplate(o["project"]))
+        o["projectIsTemplate"] = true;
+    flattenRef(o, "project", "projectUuid", "project", forceUuid, promoter);
+    flattenRef(o, "area", "areaUuid", "area", forceUuid, promoter);
+    if (!compact || drop.keepHeading === true)
+        flattenRef(o, "heading", "headingUuid", "heading", forceUuid, promoter, projectUuid);
+    // R12 — FULL/DETAIL keep the raw `startDate` beside `when` as the SUBSTRATE
+    // (`startDate` = what is stored, `when` = where it sits). COMPACT drops it below
+    // (the position `when` carries is what a list needs).
+    if (!compact)
+        return o;
+    // R7 compact — default-pruning (absence = the default).
+    delete o["startDate"]; // R12 — position lives in `when`; substrate is full-tier only
+    if (o["status"] === "open")
+        delete o["status"];
+    delete o["created"];
+    delete o["modified"];
+    const notes = typeof o["notes"] === "string" ? o["notes"] : "";
+    delete o["notes"];
+    if (notes !== "")
+        o["hasNotes"] = true;
+    // The heading ref is compact-dropped everywhere (the GUI shows the project,
+    // never the heading, outside a project view). Full tier / detail keep it; a
+    // project-view logbook row (drop.keepHeading) keeps it too — flattened above.
+    if (drop.keepHeading !== true)
+        delete o["heading"];
+    return o;
+}
+/** Map a plain array of items with the item shaper. */
+function shapeList(items, drop, compact, promoter) {
+    if (!Array.isArray(items))
+        return items;
+    return items.map((i) => shapeItem(i, drop, compact, promoter));
+}
+/** Copy `base` and overwrite `items` with the shaped list (avoids spread-in-map). */
+function withShapedItems(base, drop, compact, promoter) {
+    const out = { ...base };
+    out["items"] = shapeList(base["items"], drop, compact, promoter);
+    return out;
+}
+/** Coerce an unknown value to an array (empty when absent). */
+const asArray = (v) => (Array.isArray(v) ? v : []);
+/**
+ * The flat project-view `items[]` rows (read-shape doctrine §3.12): drop
+ * project/area (the card states them) but KEEP `stage` (the list is stage-MIXED:
+ * anytime + upcoming + someday + closed-unswept), `when`, and the `heading` ref.
+ * The heading ref is kept + flattened even in compact (keepHeading), scoped to
+ * the owning project — flat title + `headingUuid` when the title would not
+ * round-trip — so a consumer reconstructs a heading's members from the rows.
+ */
+const PROJECT_ITEM_DROP = { project: true, area: true, keepHeading: true };
+/**
+ * Project-view LOGBOOK (flat logged) rows (read-shape doctrine §3.12 / #C4): drop
+ * project/area (the card states them) but KEEP `stage` and the `heading` ref
+ * (drop.keepHeading). The bucket is stage-MIXED since it absorbs the children of
+ * SWEPT ARCHIVED headings too — mostly `logbook`, but it can hold the odd OPEN
+ * child a Put-Back stranded under an archived heading (HEADARC2-C, stage
+ * `anytime`) — so `stage` is not provably implied and is kept. The heading ref is
+ * the GUI hint (the in-project logged toggle labels the HEADING; the global
+ * Logbook labels the PROJECT — the two-view asymmetry, HEADARC2-B), flat title +
+ * project-scoped `headingUuid`.
+ */
+const PROJECT_LOGBOOK_DROP = {
+    project: true,
+    area: true,
+    keepHeading: true,
+};
+/**
+ * The flat area-view `items[]` rows (read-shape doctrine §3.13): drop `area` (the
+ * card states it) but KEEP `stage` (the list is stage-MIXED — anytime + upcoming
+ * + someday + closed-unswept) and `when`. Area direct to-dos are never headed and
+ * never project-nested, so nothing else to drop.
+ */
+const AREA_ITEM_DROP = { area: true };
+/** Area-view PROJECTS list: a mixed listing of the area's project rows — keep `stage`, drop area. */
+const AREA_PROJECTS_DROP = { area: true };
+/**
+ * Anytime sidebar-section items: stage-PURE → drop area + the section-implied
+ * stage (R10.2). Every Anytime-view member derives `anytime`: ANYTIME_SELF
+ * (undated-active, arrived-active, arrived someday-scheduled) — an ARRIVED dated
+ * row is Anytime, not Upcoming (Upcoming is STRICTLY FUTURE, UPC1) — AND, since
+ * R13, the DEADLINE-PULLED undated Inbox/Someday rows the view now includes
+ * (BANNER1b), which derive `anytime` too (deriveStage step 2½: a Today-marked
+ * undated row is a pull → anytime). Repeating templates are excluded from the
+ * view (NOT_TEMPLATE), so no stage-`upcoming` row can appear here — still pure.
+ */
+const ANYTIME_SECTION_DROP = { area: true, stage: true };
+/** Someday sidebar-section items: stage-PURE → drop area + the bucket-implied stage. */
+const SOMEDAY_SECTION_DROP = { area: true, stage: true };
+/** The card NODE / detail / mixed lists: keep every ref, `stage`, and `when`. */
+const NO_DROP = {};
+/**
+ * The today view's flat `items[]`: drop the view-implied `stage` (R13) but KEEP
+ * `when`. Every Today member derives stage `anytime` by construction — an ARRIVED
+ * `startDate` (step 5) or a DEADLINE PULL (step 2½) both derive `anytime`, and
+ * there are no future-dated or undated-someday Today members — so the today view
+ * is provably stage-PURE `anytime` and the field is redundant (verified strict by
+ * the today purity property test in test/unit/stage.test.ts). `when` is KEPT: the
+ * flat list interleaves Today-proper (`when: "today"`) and This-Evening
+ * (`when: "evening"`) members, so each row must carry which render section it
+ * belongs to — the split is derived from `when`, not a wire bucket. `provisional`
+ * is NOT a drop — the banner pip is per-row, nothing implies it.
+ */
+const TODAY_ITEM_DROP = { stage: true };
+/**
+ * Shape a heading catalog entry (a `headings[]` node — the flat `{uuid,title,
+ * archived?}` catalog, read-shape doctrine §3.12 / #C3). The type is implied by
+ * position, and a heading has no open/canceled/completed vocabulary the reader
+ * needs — so:
+ * - DROP `type` (positional: this slot is always a heading; the "absent type =
+ *   to-do" convention is scoped to ROWS/candidates, never this catalog entry);
+ * - DROP `project` (the card states it);
+ * - REPLACE `status` with the presence-keyed `archived` (the stopDate, an ISO
+ *   date-time following the `stopped`/logged-row convention) — emitted ONLY when
+ *   the heading is archived (status "completed"), OMITTED when open. The entry
+ *   carries only whether-and-when it was archived; sweptness (past the logbook
+ *   boundary) is not on the wire — the TTY derives it (#C3a).
+ */
+function shapeHeadingNode(src) {
+    if (src === null || typeof src !== "object")
+        return src;
+    const h = { ...src };
+    delete h["project"];
+    delete h["type"];
+    const isArchived = h["status"] !== undefined && h["status"] !== "open";
+    const stopped = h["stopped"];
+    delete h["status"];
+    delete h["stopped"];
+    // Presence-keyed `archived` — the ISO archive timestamp (past-participle twin of
+    // `stopped`/`created`/`modified`), full-datetime serialization like `stopped`.
+    if (isArchived && stopped != null)
+        h["archived"] = stopped;
+    return h;
+}
+/** Stopped-DESC comparator for the flat logbook (open odd children — no stopDate — sort last). */
+function byStoppedDesc(a, b) {
+    const t = (x) => {
+        const s = x !== null && typeof x === "object" ? x["stopped"] : null;
+        return s instanceof Date ? s.getTime() : -Infinity;
+    };
+    return t(b) - t(a);
+}
+/**
+ * Shape a project view (read-shape doctrine §3.12 / #C3 / #C4). The live children
+ * are ONE flat `items[]` in project index order — each row carrying `stage`,
+ * `when`, and its `heading` ref (flat title + project-scoped `headingUuid`) — so a
+ * consumer reconstructs a heading's members by filtering `items` on `heading`.
+ * `headings[]` is the flat catalog `[{uuid,title,archived?}]` of EVERY heading
+ * (live + swept archived) in index order — the ORDER axis. `logbook` is one flat
+ * `stopDate DESC` list of ALL swept children — of open headings, un-headed, AND
+ * archived headings — each carrying its `heading` ref; `logbookHeadings` is gone
+ * (its rows folded in, the archived heading itself now a catalog entry with
+ * `archived`). The card node is left full + ancestry-intact.
+ */
+function shapeProjectView(view, compact, promoter) {
+    // The heading catalog: every heading node (live + swept archived), index order,
+    // flattened to `{uuid,title,archived?}`. Membership rides the flat item/logbook
+    // row `heading` refs; archived-ness reads off `archived` here.
+    const headings = Array.isArray(view["headingCatalog"])
+        ? view["headingCatalog"].map(shapeHeadingNode)
+        : [];
+    // The flat logbook: swept children of open/un-headed headings (`logged`) PLUS
+    // the children of swept archived headings (`loggedHeadings`), merged into ONE
+    // stopDate-DESC list (open odd children last), each carrying its heading ref.
+    const loggedRows = [
+        ...asArray(view["logged"]),
+        ...asArray(view["loggedHeadings"]).flatMap((g) => g !== null && typeof g === "object" ? asArray(g["items"]) : []),
+    ].toSorted(byStoppedDesc);
+    const out = { ...view };
+    delete out["active"];
+    delete out["scheduled"];
+    delete out["repeating"];
+    delete out["someday"];
+    delete out["logged"];
+    delete out["loggedHeadings"];
+    delete out["headingCatalog"];
+    // Trashed children live only in `things trash` — never a project-view bucket.
+    // Delete defensively in case an untyped source carries the old key.
+    delete out["trashed"];
+    // The project card NODE keeps everything (children derive their container from
+    // it), but is still an item DTO, so the universal + R10 reshapes apply.
+    out["project"] = shapeItem(view["project"], NO_DROP, false, promoter);
+    // The flat live children — stage/when/heading kept, project/area dropped (the
+    // card states them). The heading ref is kept + flattened even in compact
+    // (keepHeading), project-scoped like the logbook rows.
+    out["items"] = shapeList(view["items"], PROJECT_ITEM_DROP, compact, promoter);
+    out["headings"] = headings;
+    // A project keeps its in-context `logbook` (a project is a bounded object with a
+    // real done-state); trashed children live only in `things trash`. The flat
+    // rows KEEP stage (mixed) + their heading ref (PROJECT_LOGBOOK_DROP).
+    out["logbook"] = shapeList(loggedRows, PROJECT_LOGBOOK_DROP, compact, promoter);
+    return out;
+}
+/**
+ * Shape an area view (read-shape doctrine §3.13). The direct to-dos dissolve into
+ * ONE flat `items[]` in index order — each row carrying `stage` + `when`, `area`
+ * dropped (the card states it). The stage/date sub-buckets (anytime/upcoming/
+ * someday) are gone. `projects[]` is KEPT — the area's child-project sidebar rank
+ * is a DISTINCT order axis from the direct-to-do index, so it earns its own list
+ * (mixed-stage, someday/scheduled projects included; the render split is TTY-only).
+ * The area node keeps its identity (tags folded).
+ */
+function shapeAreaView(view, compact, promoter) {
+    const out = { ...view };
+    delete out["active"];
+    delete out["scheduled"];
+    delete out["repeating"];
+    delete out["someday"];
+    // No `logbook` or `trash` bucket: an area's logbook is the bounded query
+    // `things logbook --area <ref>`, and trashed rows live only in `things trash`.
+    // Delete defensively in case an untyped source carries the old keys.
+    delete out["logged"];
+    delete out["trashed"];
+    out["area"] = shapeArea(view["area"]);
+    // The flat direct to-dos — stage/when kept, area dropped.
+    out["items"] = shapeList(view["items"], AREA_ITEM_DROP, compact, promoter);
+    // The projects list is a mixed listing of the area's project rows — keep stage,
+    // sidebar order (the distinct order axis).
+    out["projects"] = shapeList(view["projects"], AREA_PROJECTS_DROP, compact, promoter);
+    return out;
+}
+/** Fold an area entity's tags to string names in place (returns a shallow copy). */
+function shapeArea(src) {
+    if (src === null || typeof src !== "object")
+        return src;
+    const o = { ...src };
+    flattenTags(o);
+    return o;
+}
+/** Shape sidebar sections (anytime/someday catalogues) with the section's drop spec. */
+function shapeSections(sections, drop, compact, promoter) {
+    if (!Array.isArray(sections))
+        return sections;
+    return sections.map((s) => s === null || typeof s !== "object" ? s : withShapedItems(s, drop, compact, promoter));
+}
+/**
+ * The flat, mixed-provenance list kinds mapped to their drop spec. Only the
+ * stage-PURE catalogues (inbox/someday/logbook/trash; the section-based `anytime`
+ * is pure too, handled via shapeSections below) drop the bucket-implied `stage`.
+ * `upcoming` KEEPS it (R10.2): the Upcoming view is stage-mixed — it carries
+ * deadline-forecast stage-`anytime`/`someday` rows alongside future-dated
+ * stage-`upcoming` ones. The mixed/derived surfaces (search/changes/projects)
+ * keep it too.
+ */
+const FLAT_LIST_DROP = new Map([
+    ["inbox", { stage: true }],
+    ["upcoming", NO_DROP],
+    ["logbook", { stage: true }],
+    ["trash", { stage: true }],
+    ["changes", NO_DROP],
+    ["search", NO_DROP],
+    ["projects", NO_DROP],
+]);
+/**
+ * Apply the universal reshapes + R6 + R7 + R10 to a read payload for one view
+ * `kind`. `full` forces the FULL tier (R7 default-pruning off, everything else
+ * applied); an unrecognized kind passes through unchanged. The input is never
+ * mutated (shallow copies throughout), so the human-render path keeps the full
+ * entities.
+ */
+export function shapeReadPayload(kind, data, full, promoter) {
+    // The ref-promotion oracle drives the round-trip law for flat container refs.
+    // Absent (a DB-less unit shaping): assume every title round-trips — bare
+    // titles, no uuid siblings. Production always passes the client's promoter.
+    const p = promoter ?? ALWAYS_ROUND_TRIPS;
+    // `detail` is the FULL record and drops no ancestry / stage / `when`.
+    if (kind === "detail")
+        return shapeItem(data, NO_DROP, false, p);
+    const compact = !full;
+    const flatDrop = FLAT_LIST_DROP.get(kind);
+    if (flatDrop !== undefined)
+        return shapeList(data, flatDrop, compact, p);
+    // The today view: one flat `items[]` of Today members (Today-proper + This
+    // Evening interleaved in comparator order); drop the view-implied `stage`,
+    // KEEP `when` (it carries the render section). The `counts` aggregate rides
+    // `meta.counts`, not `data`. The wire wrapper is `{ items }` (read-driver).
+    if (kind === "today" && data !== null && typeof data === "object") {
+        return shapeList(data["items"], TODAY_ITEM_DROP, compact, p);
+    }
+    if (kind === "anytime" && Array.isArray(data)) {
+        return shapeSections(data, ANYTIME_SECTION_DROP, compact, p); // stage-pure → drop stage
+    }
+    if (kind === "someday" && Array.isArray(data)) {
+        return shapeSections(data, SOMEDAY_SECTION_DROP, compact, p); // stage-pure → drop stage
+    }
+    if (kind === "area-view" && data !== null && typeof data === "object") {
+        return shapeAreaView(data, compact, p);
+    }
+    if (kind === "project-view" && data !== null && typeof data === "object") {
+        return shapeProjectView(data, compact, p);
+    }
+    // The `areas` listing carries Area entities whose tags fold to names.
+    if (kind === "areas" && Array.isArray(data))
+        return data.map(shapeArea);
+    // tags / legend / snapshot / diagnostics: not tag-carrying entity payloads.
+    return data;
+}
+/** The fixed cap on a listed candidate array; the error `message` states the total when it overflows. */
+export const CANDIDATE_CAP = 8;
+/** Read a container hint — a Ref `{title}` or a plain title string — to its non-empty title, else null. */
+function candidateContainerTitle(v) {
+    if (typeof v === "string")
+        return v === "" ? null : v;
+    if (v !== null && typeof v === "object") {
+        const t = v["title"];
+        if (typeof t === "string" && t !== "")
+            return t;
+    }
+    return null;
+}
+/**
+ * Project ONE entity — a materialized to-do/project/area/heading, or a thin
+ * `{uuid, title}` resolver row — to the fixed {@link CandidateRef}. The SINGLE
+ * source every error-candidate emit flows through (the did-you-mean fallback and
+ * every not-found/ambiguous resolver), so the candidate shape can never vary by
+ * site. Reuses the wire's own {@link stageOf}/{@link whenOf} derivations — the
+ * lifecycle words are never re-derived here.
+ */
+export function candidateRef(type, src) {
+    const s = (src ?? {});
+    const out = {
+        uuid: typeof s["uuid"] === "string" ? s["uuid"] : "",
+        title: typeof s["title"] === "string" ? s["title"] : "",
+    };
+    // Absent `type` = to-do — emit it only for the other kinds.
+    if (type !== "to-do")
+        out.type = type;
+    const area = candidateContainerTitle(s["area"]);
+    if (area !== null)
+        out.area = area;
+    const project = candidateContainerTitle(s["project"]) ?? candidateContainerTitle(s["headingProject"]);
+    if (project !== null)
+        out.project = project;
+    // stage/when only for the task kinds, and only when the source carries the
+    // materialized lifecycle substrate (`start`) — a thin uuid+title resolver row
+    // does not, so the keys stay absent (presence-keyed, like the wire).
+    if ((type === "to-do" || type === "project") && typeof s["start"] === "string") {
+        const stage = stageOf(s);
+        out.stage = stage;
+        const when = whenOf(s, stage);
+        if (when !== undefined)
+            out.when = when;
+    }
+    return out;
+}
+//# sourceMappingURL=shape.js.map