things-api 0.12.0 → 0.14.0

package/dist/read/shape.js

@@ -56,9 +56,10 @@
  * - a template's `repeating.nextOccurrence` is GONE from the wire — `when` replaces
  *   it (same fact, one word); the resting-templates `{date: null}` group is
  *   unchanged (an unprojected template has no `when`).
- * - `when` is DROPPED inside the `today` view's own sections (the section key states
- *   today/evening) and inside any card/heading `upcoming` DATE-GROUP for a member
- *   whose `when` equals the group's date (the group states it). KEPT everywhere
+ * - `when` is DROPPED inside the `today` view's two `children` bucket records (the
+ *   bucket key `today`/`evening` states it) and inside any card/heading `upcoming`
+ *   DATE-GROUP for a member whose `when` equals the group's date (the group states
+ *   it). KEPT everywhere
  *   else it is present — including 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
@@ -77,9 +78,9 @@
  *   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 own sections become stage-PURE →
- *   `stage` is DROPPED there (TODAY_SECTION_DROP), alongside the section-implied
- *   `when`. The flat someday/inbox views EXCLUDE pulled rows and the anytime view
+ *   derives stage `anytime`, and the `today` view's two `children` buckets become
+ *   stage-PURE → `stage` is DROPPED there (TODAY_SECTION_DROP), alongside the
+ *   key-implied `when`. 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)
@@ -113,6 +114,46 @@
  * 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
@@ -260,7 +301,7 @@ function whenOf(s, stage) {
  * (`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) {
+function shapeItem(src, drop, compact, promoter) {
     if (src === null || typeof src !== "object")
         return src;
     const s = src;
@@ -318,6 +359,12 @@ function shapeItem(src, drop, compact) {
     // 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"];
@@ -325,6 +372,30 @@ function shapeItem(src, drop, compact) {
         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).
@@ -341,20 +412,22 @@ function shapeItem(src, drop, compact) {
     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.
-    delete o["heading"];
+    // 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) {
+function shapeList(items, drop, compact, promoter) {
     if (!Array.isArray(items))
         return items;
-    return items.map((i) => shapeItem(i, drop, compact));
+    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) {
+function withShapedItems(base, drop, compact, promoter) {
     const out = { ...base };
-    out["items"] = shapeList(base["items"], drop, compact);
+    out["items"] = shapeList(base["items"], drop, compact, promoter);
     return out;
 }
 /**
@@ -372,13 +445,13 @@ function withShapedItems(base, drop, compact) {
  * then run through {@link shapeItem} with the section drop (ancestry + `stage`,
  * since the bucket states it).
  */
-function rebucketChildren(children, drop, compact) {
+function rebucketChildren(children, drop, compact, promoter) {
     const anytime = [];
     const someday = [];
     const datedByKey = new Map();
     const datedOrder = [];
     const restingTemplates = [];
-    const shape = (c) => shapeItem(c, drop, compact);
+    const shape = (c) => shapeItem(c, drop, compact, promoter);
     for (const raw of children) {
         if (raw === null || typeof raw !== "object")
             continue;
@@ -441,9 +514,22 @@ function flattenGroups(groups) {
 }
 /** Coerce an unknown value to an array (empty when absent). */
 const asArray = (v) => (Array.isArray(v) ? v : []);
-/** The R6 ref drop for every child bucket of a project view (unheaded members). */
-const PROJECT_CHILD_DROP = { project: true, area: true, stage: true };
-/** Heading-group members drop the heading ref too (the group states it). */
+/**
+ * The R6 ref drop for the un-headed BODY's four `children` bucket records (v2):
+ * every body child drops project/area (the card states them), the bucket-implied
+ * stage (each of `anytime`/`upcoming`/`someday`/`logbook` is stage-pure), and the
+ * heading ref — a body child is by construction un-headed (its `heading` is null),
+ * and a project view surfaces no bare `heading: null` (drop it explicitly rather
+ * than leaning on omit-empty).
+ */
+const PROJECT_CHILD_DROP = { project: true, area: true, heading: true, stage: true };
+/**
+ * The R6 ref drop for a HEADING's four `children` bucket records (v2): a headed
+ * child drops project/area (the card states them), the heading ref (its position
+ * UNDER `headings[].children` states membership — structural, #362 / task item 6),
+ * and the bucket-implied stage. Applied uniformly to the heading's live buckets
+ * AND its `logbook` — the logbook is stage-pure (all logged), so stage drops too.
+ */
 const HEADING_MEMBER_DROP = { project: true, area: true, heading: true, stage: true };
 /** Area-view child-item buckets drop their area (the card states it) + the bucket-implied stage. */
 const AREA_CHILD_DROP = { area: true, stage: true };
@@ -465,101 +551,327 @@ 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 own sections: drop the section-implied `when` (R12) AND the
- * section-implied `stage` (R13). Every Today member now 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 sections are provably stage-PURE `anytime` and the field
- * is redundant there (verified strict by the today-section purity property test
- * in test/unit/stage.test.ts). `provisional` is NOT a drop — the banner is not a
- * section, so nothing implies it.
+ * The today view's two `children` bucket records: drop the key-implied `when`
+ * (R12 — the `today`/`evening` bucket key states it) AND the bucket-implied
+ * `stage` (R13). Every Today member now 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
+ * both buckets are provably stage-PURE `anytime` and the field is redundant there
+ * (verified strict by the today purity property test in test/unit/stage.test.ts).
+ * `provisional` is NOT a drop — the banner is not a bucket, so nothing implies it.
  */
 const TODAY_SECTION_DROP = { when: true, stage: true };
-/** Shape every collection bucket of a project view; the card node is left full + ancestry-intact. */
-function shapeProjectView(view, compact) {
-    const cd = PROJECT_CHILD_DROP;
-    const hd = HEADING_MEMBER_DROP;
-    const shapeHeadingGroup = (g) => {
-        if (g === null || typeof g !== "object")
-            return g;
-        const grp = g;
-        const out = {};
-        // The heading NODE itself drops its `project` ref — the card states it.
-        if (grp["heading"] !== null && typeof grp["heading"] === "object") {
-            const h = { ...grp["heading"] };
-            delete h["project"];
-            out["heading"] = h;
-        }
-        else {
-            out["heading"] = grp["heading"];
-        }
-        const members = [
-            ...asArray(grp["items"]),
-            ...flattenGroups(grp["scheduled"]),
-            ...asArray(grp["someday"]),
-            ...asArray(grp["repeating"]),
-        ];
-        const { anytime, upcoming, someday } = rebucketChildren(members, hd, compact);
-        out["anytime"] = anytime;
-        out["upcoming"] = upcoming;
-        out["someday"] = someday;
-        return out;
+/**
+ * Shape a heading GROUP node (the `headings[].heading` / `loggedHeadings[].heading`
+ * keyed sub-object). The type is triply 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 keyed sub-object);
+ * - 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. Region
+ *   membership (live `headings` vs the logged region) expresses sweep state; the
+ *   node carries only whether-and-when it was archived.
+ */
+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;
+}
+/** A bucket record `{items, total?}` (v2 R1): `total` present IFF the bucket was capped. */
+export function bucketRecord(items, total) {
+    return total !== undefined && items.length < total ? { items, total } : { items };
+}
+/** The `stopped` epoch of an internal entity (a Date pre-shaping), or 0 — for logbook DESC ordering. */
+function stoppedMs(o) {
+    const s = o["stopped"];
+    return s instanceof Date ? s.getTime() : 0;
+}
+/**
+ * Build ONE container's four v2 `children` bucket records (PR 2) from its flat
+ * child set (live AND logged alike). Every child is routed by DERIVED STAGE, so
+ * one entity lands in exactly one place (R5/#V12):
+ * - `logbook: {items, total?}` — the swept/resolved children (`logged` flag),
+ *   most-recently-completed first (`stopped` DESC — the certified HEADARC3/logbook
+ *   ordering), stage-pure so `stage` drops;
+ * - `anytime` / `someday: {items, total?}` — stage-pure records;
+ * - `upcoming: [{when, items, total?} …]` — the day-block ARRAY (R3): dated blocks
+ *   chronological, then a single trailing `{when: null, items}` resting block for
+ *   date-less recurring templates (#V8). An open child stranded under an archived
+ *   heading (HEADARC2-C anomaly) is NOT logged, so it rides `anytime` here — its
+ *   presence in a live bucket under an `archived` heading node is self-evident.
+ * `drop` carries the container's ancestry drops (body vs heading); the day-block
+ * `when` renames the internal date group's `date` (rebucketChildren) — `null` for
+ * the resting block. No bucket is capped in the project view today, so every
+ * `total` is absent (R1: an untruncated bucket never restates its length); the
+ * `total?` argument keeps the record + day-block shape ready for PR 5's sweep and
+ * is exercised by the unit tests.
+ */
+function shapeContainerChildren(children, drop, compact, promoter) {
+    const live = [];
+    const logged = [];
+    for (const c of asArray(children)) {
+        if (c !== null && typeof c === "object" && c["logged"] === true)
+            logged.push(c);
+        else
+            live.push(c);
+    }
+    const { anytime, upcoming, someday } = rebucketChildren(live, drop, compact, promoter);
+    const loggedSorted = logged.toSorted((a, b) => stoppedMs(b) - stoppedMs(a));
+    const logbook = shapeList(loggedSorted, drop, compact, promoter);
+    return {
+        anytime: bucketRecord(anytime),
+        // The day-block ARRAY: `date` → `when` (R3); `null` is the resting block (#V8).
+        upcoming: upcoming.map((g) => ({ when: g.date, items: g.items })),
+        someday: bucketRecord(someday),
+        logbook: bucketRecord(logbook),
+    };
+}
+/**
+ * Shape a project view into the read-shape v2 wire (PR 2):
+ * `{ project, children, headings[] }` — NOTHING else at this level. `children` is
+ * the un-headed BODY's four stage-keyed bucket records; `headings[]` is EVERY
+ * heading (index order, all lifecycle classes — R5) as `{uuid, title, archived?,
+ * children}` with the SAME recursive `children` shape. The per-container `logbook`
+ * lives inside each `children` (R6, no root logbook); the v1-era `logbookHeadings`
+ * and BOTH advisory keys (`openChildrenWhileResolved` /
+ * `openChildrenUnderArchivedHeading`) are DELETED (#V12) — anomalous open children
+ * seat in the normal recursive buckets, the heading's `archived` mark making the
+ * anomaly self-evident. The card node keeps everything (children derive their
+ * container from it). `out` is built fresh, so no render-only field leaks.
+ */
+function shapeProjectView(view, compact, promoter) {
+    const headingContainers = asArray(view["headingContainers"]).map((c) => {
+        const grp = (c ?? {});
+        // The heading NODE (`{uuid, title, archived?}`) gains the recursive `children`
+        // (last key, so it reads after the identity). Object.assign mutates the fresh
+        // node copy shapeHeadingNode already returns — no spread-in-map.
+        const node = shapeHeadingNode(grp["heading"]);
+        return Object.assign(node, {
+            children: shapeContainerChildren(grp["children"], HEADING_MEMBER_DROP, compact, promoter),
+        });
+    });
+    return {
+        // The card NODE keeps everything but is still an item DTO (universal + R10 reshapes).
+        project: shapeItem(view["project"], NO_DROP, false, promoter),
+        children: shapeContainerChildren(view["bodyChildren"], PROJECT_CHILD_DROP, compact, promoter),
+        headings: headingContainers,
+    };
+}
+/**
+ * Build an area's THREE v2 `children` bucket records (PR 3) from its flat direct
+ * to-do set (live only — an area has NO logged-children region, so no `logbook`
+ * key; the area logbook is the bounded query `things logbook --area <ref>`, #346).
+ * The same stage-derived bucketing as {@link shapeContainerChildren} minus the
+ * logbook split: `anytime`/`someday` are `{items, total?}` records, `upcoming` is
+ * the day-block ARRAY (R3, `date` → `when`) with the trailing `{when: null, items}`
+ * resting block for date-less recurring templates (#V8). Inline `total` is stamped
+ * downstream by {@link withAreaBucketTotals} (only `anytime` can be capped — the
+ * `--area-limit` scope; the scheduled/someday direct to-dos always survive).
+ */
+function shapeAreaChildren(members, drop, compact, promoter) {
+    const { anytime, upcoming, someday } = rebucketChildren(members, drop, compact, promoter);
+    return {
+        anytime: bucketRecord(anytime),
+        // The day-block ARRAY: `date` → `when` (R3); `null` is the resting block (#V8).
+        upcoming: upcoming.map((g) => ({ when: g.date, items: g.items })),
+        someday: bucketRecord(someday),
     };
-    const headings = Array.isArray(view["headings"])
-        ? view["headings"].map(shapeHeadingGroup)
-        : view["headings"];
-    const looseMembers = [
-        ...asArray(view["active"]),
-        ...flattenGroups(view["scheduled"]),
-        ...asArray(view["someday"]),
-        ...asArray(view["repeating"]),
-    ];
-    const { anytime, upcoming, someday } = rebucketChildren(looseMembers, cd, compact);
-    const out = { ...view };
-    delete out["active"];
-    delete out["scheduled"];
-    delete out["repeating"];
-    delete out["logged"];
-    // 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);
-    out["anytime"] = anytime;
-    out["upcoming"] = upcoming;
-    out["someday"] = someday;
-    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`.
-    out["logbook"] = shapeList(view["logged"], cd, compact);
-    return out;
 }
-/** Shape every collection bucket of an area view; the area node keeps its identity (tags folded). */
-function shapeAreaView(view, compact) {
+/**
+ * Shape an area view into the read-shape v2 wire (PR 3):
+ * `{ area | null, children, projects }` — NOTHING else at this level. `children`
+ * is the area's direct to-dos as three stage-keyed bucket records (`anytime`,
+ * `upcoming[]`, `someday` — NO `logbook`, #346); `projects` is the child-project
+ * sidebar-rank scope as a bucket record `{items, total?}` — a mixed-stage listing
+ * that KEEPS `stage`/`when` (the someday-projects / active split is TTY-only). The
+ * loose pseudo-area keeps `area: null`. The area node keeps its identity (tags
+ * folded to names); each direct-to-do row drops `area` (the node states it) + the
+ * bucket-implied `stage`. Inline `total` (present iff a scope was capped, R1) is
+ * injected downstream by {@link withAreaBucketTotals}, where the pre-cap sizes are
+ * known. `out` is built fresh, so no render-only field leaks.
+ */
+function shapeAreaView(view, compact, promoter) {
     const looseMembers = [
         ...asArray(view["active"]),
         ...flattenGroups(view["scheduled"]),
         ...asArray(view["someday"]),
         ...asArray(view["repeating"]),
     ];
-    const { anytime, upcoming, someday } = rebucketChildren(looseMembers, AREA_CHILD_DROP, compact);
-    const out = { ...view };
-    delete out["active"];
-    delete out["scheduled"];
-    delete out["repeating"];
-    // 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"]);
-    out["anytime"] = anytime;
-    // The projects list is a mixed listing of the area's project rows — keep stage.
-    out["projects"] = shapeList(view["projects"], AREA_PROJECTS_DROP, compact);
-    out["upcoming"] = upcoming;
-    out["someday"] = someday;
-    return out;
+    return {
+        // The area NODE, or `null` for the loose pseudo-area (shapeArea passes null).
+        area: shapeArea(view["area"]),
+        children: shapeAreaChildren(looseMembers, AREA_CHILD_DROP, compact, promoter),
+        // The projects list is a mixed listing of the area's project rows — keep stage.
+        projects: bucketRecord(shapeList(view["projects"], AREA_PROJECTS_DROP, compact, promoter)),
+    };
+}
+/**
+ * Inject the area view's inline scope `total`s (read-shape v2 R1, PR 3): present
+ * iff the scope was capped (`items.length < total`), absent otherwise — no
+ * `meta.truncation.blocks[]` sidecar. `children.anytime` carries the direct-to-dos
+ * (`--area-limit`) total; `projects` carries the project-rows (`--project-limit`)
+ * total. The scheduled/someday direct-to-do blocks and the scheduled/someday
+ * project rows are never capped, so they never gain a `total`. Both the CLI `view`
+ * wrapper and the MCP data block run the shaped view through this so completeness
+ * is answerable locally. Returns the view unchanged when it is not the expected
+ * shape.
+ */
+export function withAreaBucketTotals(view, totals) {
+    if (view === null || typeof view !== "object")
+        return view;
+    const v = view;
+    const children = v["children"];
+    const withChildTotals = children !== null && typeof children === "object"
+        ? {
+            ...children,
+            anytime: withBucketTotal(children["anytime"], totals.anytime),
+        }
+        : children;
+    // Spread-then-override keeps the `area` / `children` / `projects` key order.
+    return {
+        ...v,
+        children: withChildTotals,
+        projects: withBucketTotal(v["projects"], totals.projects),
+    };
+}
+/**
+ * The global `upcoming` view's DAY-BLOCK key for one raw item (read-shape v2 PR 4):
+ * its `startDate` when scheduled; else, for a NON-template, its `deadline` (a
+ * deadline-forecast row appears at its due day — cohort 2, UPC1); else `null` —
+ * a date-LESS recurring template rides the trailing resting block (#V8). This is
+ * the emit-boundary twin of the renderer's `groupDate` (src/cli/render.ts) and of
+ * {@link upcomingBlockTotals} (the pre-cap sizer), so the wire's day blocks match
+ * the TTY grouping row-for-row and each block's inline `total` lines up with its
+ * scope. The library keeps its own day grouping; only the wire reshapes here.
+ */
+function upcomingBlockKey(o) {
+    const startDate = o["startDate"] ?? null;
+    if (startDate !== null)
+        return startDate;
+    const repeating = o["repeating"];
+    const isTemplate = repeating !== null &&
+        typeof repeating === "object" &&
+        repeating["isTemplate"] === true;
+    if (isTemplate)
+        return null; // a date-less template → the resting block (#V8)
+    return o["deadline"] ?? null; // a forecast row appears at its deadline
+}
+/**
+ * Reshape the global `upcoming` view into the read-shape v2 day-block sections
+ * (PR 4): `[{ when, items, total? } …]` — chronological dated blocks keyed by
+ * {@link upcomingBlockKey} (each the COMPLETE global day scope, its `when` doubling
+ * as the `--in <when>` reorder token), then ONE trailing `{ when: null, items }`
+ * block holding the date-less resting recurring templates (#V8) when any exist.
+ * The incoming stream is already day-ordered (COALESCE(startDate, deadline) ASC,
+ * then the UI's within-day drag order), so encounter order preserves both the
+ * block chronology and the within-block order — no re-sort, matching the renderer.
+ * Rows KEEP `stage` (the view is projection-side stage-MIXED, R7: future-dated
+ * `upcoming` rows beside deadline-forecast `anytime`/`someday` ones) and drop
+ * `when` only when it equals the block's date (the block states it — the same rule
+ * {@link rebucketChildren} applies to a container day block); a forecast row's
+ * `when` is absent already, and a divergent projected `when` (horizon > 1) is kept.
+ * Every row keeps its container refs (a global mixed view — NO_DROP). Inline
+ * `total` is stamped downstream by {@link withUpcomingBlockTotals}.
+ */
+function shapeUpcomingView(items, compact, promoter) {
+    const datedByKey = new Map();
+    const datedOrder = [];
+    const resting = [];
+    for (const raw of items) {
+        if (raw === null || typeof raw !== "object")
+            continue;
+        const key = upcomingBlockKey(raw);
+        const shaped = shapeItem(raw, NO_DROP, compact, promoter);
+        if (key === null) {
+            resting.push(shaped);
+            continue;
+        }
+        if (!datedByKey.has(key)) {
+            datedByKey.set(key, []);
+            datedOrder.push(key);
+        }
+        // R12 — inside a dated block the block states the date, so a member whose
+        // `when` equals it drops it (a scheduled row's when IS the key). A forecast
+        // row has no `when`; a horizon-projected row whose `when` diverges keeps it.
+        if (shaped !== null && typeof shaped === "object" && shaped["when"] === key) {
+            delete shaped["when"];
+        }
+        datedByKey.get(key).push(shaped);
+    }
+    const sections = datedOrder.map((when) => ({ when, items: datedByKey.get(when) }));
+    if (resting.length > 0)
+        sections.push({ when: null, items: resting });
+    return sections;
+}
+/**
+ * Inject each global-`upcoming` day block's inline `total` (read-shape v2 R1,
+ * PR 4): present iff that day's scope was capped by the flat row limit
+ * (`items.length < total`), absent otherwise — no `meta.truncation.blocks[]`
+ * sidecar (the whole-view `{shown,total,limit,truncated}` rollup still rides
+ * `meta.truncation` for the row hint). The flat cut across the day-ordered stream
+ * leaves at most ONE straddling block partial (its pre-cap size looked up by
+ * `when` from `totals`); blocks fully before the cut are complete (no `total`),
+ * and blocks fully past it never appear. The resting block keys on `null`. Both
+ * the CLI `sections` wrapper and the MCP data block run the shaped sections
+ * through this so completeness is answerable locally. Returns the input unchanged
+ * when it is not the expected sections array.
+ */
+export function withUpcomingBlockTotals(sections, totals) {
+    if (!Array.isArray(sections))
+        return sections;
+    return sections.map((s) => {
+        if (s === null || typeof s !== "object")
+            return s;
+        const sec = s;
+        const when = (sec["when"] ?? null);
+        const total = totals.get(when);
+        const items = sec["items"];
+        const shown = Array.isArray(items) ? items.length : 0;
+        // Spread-then-add keeps the `when` / `items` / `total` key order.
+        return total !== undefined && shown < total ? { ...sec, total } : sec;
+    });
+}
+/**
+ * Inject each global anytime/someday section's inline `total` (read-shape v2 R1,
+ * PR 5): present iff that section's `items` were capped (`items.length < total`),
+ * absent otherwise — an untruncated section never restates its own length, and
+ * the pre-v2 `meta.truncation.blocks[]` descriptor-join sidecar is RETIRED. The
+ * pre-cap section sizes come from {@link previewSections}/{@link
+ * previewSomedaySections} keyed by area uuid (`null` for the loose section); the
+ * per-block "… N more" render detail is carried separately (internal
+ * {@link GroupBlock}[]), never on the wire. Both the CLI `sections` wrapper and
+ * the MCP data block run the shaped sections through this so completeness is
+ * answerable locally. Returns the input unchanged when it is not the expected
+ * sections array.
+ */
+export function withSectionTotals(sections, totals) {
+    if (!Array.isArray(sections))
+        return sections;
+    return sections.map((s) => {
+        if (s === null || typeof s !== "object")
+            return s;
+        const sec = s;
+        const area = sec["area"];
+        const key = area !== null && typeof area === "object" ? area["uuid"] : null;
+        const total = totals.get(key);
+        const items = sec["items"];
+        const shown = Array.isArray(items) ? items.length : 0;
+        // Spread-then-add keeps the `area` / `items` / `total` key order.
+        return total !== undefined && shown < total ? { ...sec, total } : sec;
+    });
 }
 /** Fold an area entity's tags to string names in place (returns a shallow copy). */
 function shapeArea(src) {
@@ -569,32 +881,70 @@ function shapeArea(src) {
     flattenTags(o);
     return o;
 }
-/** Shape the today/evening split (mixed list — keep refs + stage; drop the section-implied `when`). */
-function shapeTodayView(view, compact) {
+/**
+ * Shape the today view into its two `children` bucket records (read-shape v2 R1):
+ * `{ today: { items }, evening: { items } }`, each a stage/`when`-pure list (the
+ * bucket key states both — TODAY_SECTION_DROP). The whole-view `counts` aggregate
+ * is NOT here — it rides `meta.counts` (runRead / the MCP metadata block). Inline
+ * per-bucket `total` (present iff capped) is injected downstream by
+ * {@link withTodayBucketTotals}, where the pre-cap sizes are known.
+ */
+function shapeTodayView(view, compact, promoter) {
+    return {
+        today: { items: shapeList(view["today"], TODAY_SECTION_DROP, compact, promoter) },
+        evening: { items: shapeList(view["evening"], TODAY_SECTION_DROP, compact, promoter) },
+    };
+}
+/**
+ * Inject each today bucket's inline `total` (read-shape v2 R1): present iff the
+ * bucket was capped (`items.length < total`), absent otherwise — an untruncated
+ * bucket never restates its own length. `totals` are the pre-cap bucket sizes
+ * from `truncateToday`. Both the CLI `data.children` wrapper and the MCP data
+ * block run the shaped children through this so completeness is answerable
+ * locally, with no truncation sidecar. Returns the children object unchanged when
+ * it is not the expected shape.
+ */
+export function withTodayBucketTotals(children, totals) {
+    if (children === null || typeof children !== "object")
+        return children;
+    const c = children;
     return {
-        ...view,
-        today: shapeList(view["today"], TODAY_SECTION_DROP, compact),
-        evening: shapeList(view["evening"], TODAY_SECTION_DROP, compact),
+        today: withBucketTotal(c["today"], totals.today),
+        evening: withBucketTotal(c["evening"], totals.evening),
     };
 }
+/**
+ * Stamp a bucket record's inline `total` (read-shape v2 R1) iff it was capped
+ * (`items.length < total`) — an untruncated bucket never restates its own length.
+ * The pre-cap `total` comes from the bounding layer; returns the bucket unchanged
+ * when it is not a `{items}` record. Shared by the today and area inline-total
+ * injectors.
+ */
+function withBucketTotal(bucket, total) {
+    if (bucket === null || typeof bucket !== "object")
+        return bucket;
+    const b = bucket;
+    const items = b["items"];
+    const shown = Array.isArray(items) ? items.length : 0;
+    return shown < total ? { ...b, total } : b;
+}
 /** Shape sidebar sections (anytime/someday catalogues) with the section's drop spec. */
-function shapeSections(sections, drop, compact) {
+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));
+    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.
+ * The mixed/derived surfaces (search/changes/projects) keep it. The global
+ * `upcoming` view is NOT here — it reshapes into `data.sections` day blocks
+ * ({@link shapeUpcomingView}), keeping `stage` (R10.2: stage-mixed — future-dated
+ * `upcoming` rows beside deadline-forecast `anytime`/`someday` ones).
  */
 const FLAT_LIST_DROP = new Map([
     ["inbox", { stage: true }],
-    ["upcoming", NO_DROP],
     ["logbook", { stage: true }],
     ["trash", { stage: true }],
     ["changes", NO_DROP],
@@ -608,28 +958,35 @@ const FLAT_LIST_DROP = new Map([
  * mutated (shallow copies throughout), so the human-render path keeps the full
  * entities.
  */
-export function shapeReadPayload(kind, data, full) {
+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);
+        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);
+        return shapeList(data, flatDrop, compact, p);
+    // The global `upcoming` view reshapes into `data.sections` day blocks (PR 4).
+    if (kind === "upcoming" && Array.isArray(data))
+        return shapeUpcomingView(data, compact, p);
     if (kind === "today" && data !== null && typeof data === "object") {
-        return shapeTodayView(data, compact);
+        return shapeTodayView(data, compact, p);
     }
     if (kind === "anytime" && Array.isArray(data)) {
-        return shapeSections(data, ANYTIME_SECTION_DROP, compact); // stage-pure → drop stage
+        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); // stage-pure → drop stage
+        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);
+        return shapeAreaView(data, compact, p);
     }
     if (kind === "project-view" && data !== null && typeof data === "object") {
-        return shapeProjectView(data, compact);
+        return shapeProjectView(data, compact, p);
     }
     // The `areas` listing carries Area entities whose tags fold to names.
     if (kind === "areas" && Array.isArray(data))
@@ -663,8 +1020,10 @@ export function candidateRef(type, src) {
     const out = {
         uuid: typeof s["uuid"] === "string" ? s["uuid"] : "",
         title: typeof s["title"] === "string" ? s["title"] : "",
-        type,
     };
+    // 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;