things-api 0.13.0 → 0.14.0

package/dist/read/shape.js

@@ -54,16 +54,17 @@
  *   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).
+ *   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 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
+ *   `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:
@@ -77,10 +78,10 @@
  *   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.
+ *   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)
  * - **checklist nesting** — flat counts → presence-keyed `checklist: {open,total}`.
@@ -340,9 +341,9 @@ function shapeItem(src, drop, compact, promoter) {
     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).
+    // EVERY tier (they never appear on the wire); `when` is emitted unless the
+    // enclosing context provably states the position (the today view's sections;
+    // a card date-group — handled in rebucketChildren).
     delete o["today"];
     delete o["evening"];
     // §9n — a reminder byte is presentation-dead once its `startDate` goes strictly
@@ -429,40 +430,109 @@ function withShapedItems(base, drop, compact, promoter) {
     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.
+ * Re-bucket a project's / area's / heading's live (non-logbook/trash) children
+ * into the R10 card shape by their derived {@link deriveStage} — so the bucket an
+ * item lands in ALWAYS equals its `stage`:
+ * - `anytime` — stage anytime, in encounter order;
+ * - `upcoming` — stage upcoming, date-grouped `[{date, items}]` (a dated row under
+ *   its `startDate`, a template under its `nextOccurrence`), date ASC; date-LESS
+ *   templates (after-completion / paused) form a trailing `{date: null, items}`
+ *   group (explicit null per the `area: null` section precedent);
+ * - `someday` — stage someday.
+ * Items are already in view order (index / date+todayIndex) from the read layer,
+ * so encounter order within a date group preserves that ordering. Each item is
+ * then run through {@link shapeItem} with the section drop (ancestry + `stage`,
+ * since the bucket states it).
  */
-const PROJECT_ITEM_DROP = { project: true, area: true, keepHeading: true };
+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, promoter);
+    for (const raw of children) {
+        if (raw === null || typeof raw !== "object")
+            continue;
+        const c = raw;
+        const stage = stageOf(c);
+        if (stage === "anytime") {
+            anytime.push(shape(c));
+        }
+        else if (stage === "someday") {
+            someday.push(shape(c));
+        }
+        else if (stage === "upcoming") {
+            const repeating = c["repeating"];
+            const nextOcc = repeating != null && typeof repeating === "object"
+                ? (repeating["nextOccurrence"] ?? null)
+                : null;
+            const date = (c.startDate ?? null) !== null ? c.startDate : nextOcc;
+            if (date === null) {
+                restingTemplates.push(shape(c));
+            }
+            else {
+                if (!datedByKey.has(date)) {
+                    datedByKey.set(date, []);
+                    datedOrder.push(date);
+                }
+                // R12 — inside a date-group the group states the date, so a member whose
+                // `when` equals it drops it (every scheduled row and every projected
+                // template does — that IS the group key).
+                const shaped = shape(c);
+                if (shaped !== null && typeof shaped === "object" && shaped["when"] === date) {
+                    delete shaped["when"];
+                }
+                datedByKey.get(date).push(shaped);
+            }
+        }
+        else {
+            // inbox / logbook / trash should not appear among a card's live children;
+            // route defensively to anytime rather than drop the row.
+            anytime.push(shape(c));
+        }
+    }
+    const upcoming = datedOrder
+        .toSorted((a, b) => a.localeCompare(b))
+        .map((date) => ({ date, items: datedByKey.get(date) }));
+    if (restingTemplates.length > 0)
+        upcoming.push({ date: null, items: restingTemplates });
+    return { anytime, upcoming, someday };
+}
+/** Flatten an internal IsoDateGroup[] (`[{date, items}]`) to its items, in order. */
+function flattenGroups(groups) {
+    if (!Array.isArray(groups))
+        return [];
+    const out = [];
+    for (const g of groups) {
+        if (g !== null && typeof g === "object" && Array.isArray(g["items"])) {
+            out.push(...g["items"]);
+        }
+    }
+    return out;
+}
+/** Coerce an unknown value to an array (empty when absent). */
+const asArray = (v) => (Array.isArray(v) ? v : []);
 /**
- * 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`.
+ * 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_LOGBOOK_DROP = {
-    project: true,
-    area: true,
-    keepHeading: true,
-};
+const PROJECT_CHILD_DROP = { project: true, area: true, heading: true, stage: 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.
+ * 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 AREA_ITEM_DROP = { area: true };
+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 };
 /** Area-view PROJECTS list: a mixed listing of the area's project rows — keep `stage`, drop area. */
 const AREA_PROJECTS_DROP = { area: true };
 /**
@@ -481,31 +551,28 @@ 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.
+ * 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_ITEM_DROP = { stage: true };
+const TODAY_SECTION_DROP = { when: true, 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:
+ * 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 catalog entry);
+ *   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. 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).
+ *   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")
@@ -523,92 +590,288 @@ function shapeHeadingNode(src) {
         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;
+/** 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),
     };
-    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.
+ * 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) {
-    // 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;
+    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),
+    };
 }
 /**
- * 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).
+ * 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 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;
+    const looseMembers = [
+        ...asArray(view["active"]),
+        ...flattenGroups(view["scheduled"]),
+        ...asArray(view["someday"]),
+        ...asArray(view["repeating"]),
+    ];
+    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) {
@@ -618,6 +881,53 @@ function shapeArea(src) {
     flattenTags(o);
     return o;
 }
+/**
+ * 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 {
+        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, promoter) {
     if (!Array.isArray(sections))
@@ -628,14 +938,13 @@ function shapeSections(sections, 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],
@@ -661,12 +970,11 @@ export function shapeReadPayload(kind, data, full, promoter) {
     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).
+    // 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 shapeList(data["items"], TODAY_ITEM_DROP, compact, p);
+        return shapeTodayView(data, compact, p);
     }
     if (kind === "anytime" && Array.isArray(data)) {
         return shapeSections(data, ANYTIME_SECTION_DROP, compact, p); // stage-pure → drop stage