things-api 0.14.0 → 0.16.0

package/dist/read/shape.js

@@ -1,16 +1,16 @@
 /**
- * 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 read-payload SHAPING transform: the token-economy rules RS1 and RS2, the
+ * universal item-DTO reshapes (RS4), and the RS5 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
+ * Both RS1/RS2 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)
+ * ## RS5 — 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
@@ -18,11 +18,11 @@
  * 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
+ * - `stage` is DROPPED only where the enclosing node PROVABLY states it — the RS1
  *   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
+ *   BY stage). The `anytime` catalogue is stage-PURE (RS5.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.
@@ -32,12 +32,13 @@
  *   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.
+ * - the former `todaySection` field is DELETED from the entity model entirely:
+ *   it merely duplicated the presence-keyed `today`/`evening` markers
+ *   (`todaySection: "evening"` ⇔ `evening: true`; `"today"` ⇔ `today && !evening`),
+ *   which every consumer now reads directly (the human render, the write-verify
+ *   delta, the today-view evening split).
  *
- * ## R12 — `when`, the derived TIME-AXIS position (replaces startDate + markers)
+ * ## RS7 — `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
@@ -62,11 +63,11 @@
  *   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
+ *   mixed search/changes surfaces, informatively; note RS8 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
+ * ## RS8 — 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
@@ -83,35 +84,38 @@
  *   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)
+ * ## Universal item-DTO reshapes (RS4 — 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
+ * - **repeating template/instance split (RS6)** — 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
+ *   moved to the top-level `when` (RS7 — 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}.
+ *   `instanceOf: <templateUuid>` and no `repeating`; on a DETAIL read it also
+ *   gains a sibling `repeats: {rule?, next?, paused?}` — its template's repeat
+ *   context (the GUI's lower-corner caption), `rule` byte-consistent with the
+ *   template card's `repeating.rule` and `next` the fixed-mode next occurrence. 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)
+ * ## RS1 — 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.)
+ * `heading` ref is additionally dropped everywhere — RS2.)
  *
- * ## R7 — named detail tiers (compact | full)
+ * ## RS2 — 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.
+ * `status` is omitted when `open`. FULL keeps them but still applies RS1, the
+ * universal reshapes, and RS5.
  */
 import { deriveStage, deriveWhen, whenIsProvisional } from "./stage.js";
 /** The DB-less default: assume every title round-trips (bare title, no uuid sibling). */
@@ -212,7 +216,7 @@ function reshapeTodos(o) {
     o["todos"] = { open, total };
 }
 /**
- * R11 — rewrite the internal `repeating` block into the wire's template/instance
+ * RS6 — 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
@@ -223,13 +227,21 @@ function reshapeTodos(o) {
  *   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
+ *   `nextOccurrence` moved OUT to the top-level `when` (RS7 — 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.
+ *   <templateUuid>` (the instance marker + the write handle) and, on a DETAIL
+ *   read, a sibling `repeats` object — the template's repeat CONTEXT joined onto
+ *   the instance (`{rule?, next?, paused?}`), the GUI's lower-corner "Repeats on
+ *   Aug 19" / "Repeats 1 day after completion" caption. `rule` is the SAME decoded
+ *   shape a template card emits under `repeating.rule` (one recurrence vocabulary
+ *   on the wire); `next` is the template's projected next occurrence, FIXED mode
+ *   ONLY (absent for after-completion — no successor date exists yet); `paused`
+ *   surfaces the template's paused flag. Populated by src/read/detail.ts's mirror
+ *   join; absent when the template is unresolvable (dangling FK) or carries no
+ *   caption. NO `repeating` object on an instance.
  * - **Plain** (neither) → neither key.
  */
 function reshapeRepeatingWire(o) {
@@ -247,7 +259,7 @@ function reshapeRepeatingWire(o) {
         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).
+        // the top-level `when` (the forward pointer, RS7).
         if (typeof r["latestInstance"] === "string")
             out["latestInstance"] = r["latestInstance"];
         o["repeating"] = out;
@@ -255,27 +267,43 @@ function reshapeRepeatingWire(o) {
     else if (r["isInstance"] === true) {
         if (typeof r["templateUuid"] === "string")
             o["instanceOf"] = r["templateUuid"];
+        // The instance's TEMPLATE context (detail-only mirror join). Presence-keyed:
+        // the whole `repeats` object is omitted unless it carries at least one fact.
+        const ctx = r["repeats"];
+        if (ctx !== null && typeof ctx === "object") {
+            const c = ctx;
+            const out = {};
+            if (c["rule"] != null)
+                out["rule"] = c["rule"]; // same shape as a template card's `repeating.rule`
+            if (typeof c["next"] === "string")
+                out["next"] = c["next"]; // FIXED mode only
+            if (c["paused"] === true)
+                out["paused"] = true;
+            if (Object.keys(out).length > 0)
+                o["repeats"] = out;
+        }
     }
 }
-/** The R10 stage input read straight off a materialized task entity. */
+/** The RS5 stage input read straight off a materialized task entity's `derived` bag. */
 function stageOf(s) {
     const repeating = s["repeating"];
     const isTemplate = repeating !== null &&
         typeof repeating === "object" &&
         repeating["isTemplate"] === true;
+    const d = (s["derived"] ?? {});
     return deriveStage({
-        trashed: s["trashed"] === true,
-        logged: s["logged"] === true,
-        start: s["start"],
+        trashed: d["trashed"] === true,
+        logged: d["logged"] === true,
+        start: d["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,
+        // future one (→ upcoming). Read from the `derived` substrate bag.
+        today: d["today"] === true,
     });
 }
-/** The R12 `when` input read straight off a materialized task entity (given its stage). */
+/** The RS7 `when` input read straight off a materialized task entity (given its stage). */
 function whenOf(s, stage) {
     const repeating = s["repeating"];
     const isTemplate = repeating !== null &&
@@ -284,20 +312,21 @@ function whenOf(s, stage) {
     const nextOccurrence = isTemplate && typeof repeating["nextOccurrence"] === "string"
         ? repeating["nextOccurrence"]
         : null;
+    const d = (s["derived"] ?? {});
     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,
+        today: d["today"] === true,
+        evening: d["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
+ * Shape ONE task entity (to-do or project): the universal reshapes, the RS5/RS7
+ * stage/`when` rewrite, then the RS1 ancestry drops, then — when `compact` — the
+ * RS2 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.
  */
@@ -309,8 +338,8 @@ function shapeItem(src, drop, compact, promoter) {
     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
+    const when = whenOf(s, stage); // RS7 — derived from the same fields + markers
+    // RS8 (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
@@ -321,9 +350,9 @@ function shapeItem(src, drop, compact, promoter) {
     // 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 provisional = whenIsProvisional(when, (s["derived"] ?? {})["start"], s["startDate"] ?? null);
     const o = { ...s };
-    // R9 universal reshapes (every tier, every kind incl. detail).
+    // RS4 universal reshapes (every tier, every kind incl. detail).
     reshapeChecklist(o);
     reshapeTodos(o);
     flattenTags(o);
@@ -331,41 +360,32 @@ function shapeItem(src, drop, compact, promoter) {
     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"];
+    // The ENTIRE internal derivation substrate leaves the wire in ONE structural
+    // drop (one-vocabulary Batch 2, Option B): `start`/`logged`/`trashed` (RS5 —
+    // replaced by `stage`), `today`/`evening` (RS7 — replaced by `when`), and the
+    // raw `reminder` byte all live in the nested `o.derived` bag. §9n: the
+    // top-level consumer `reminder` is ALREADY the live-gated value (null once the
+    // byte is presentation-dead — its `startDate` gone strictly past), gated at the
+    // mapper; a null key is pruned by omit-empty, so a stale reminder never reaches
+    // the wire without any drop here. `stage`/`when`/`provisional` are then stamped
+    // from the derivations above.
+    delete o["derived"];
     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 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
-    // 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"];
+    // RS7 — `when` is emitted unless the enclosing context provably states the
+    // position (the today view's sections; a card date-group in rebucketChildren).
     if (drop.when !== true && when !== undefined)
         o["when"] = when;
-    // R13 — the provisional banner marker (never dropped; presence-keyed).
+    // RS8 — 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
+    // within their project). Captured BEFORE the RS1 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).
+    // RS1 — drop redundant ancestry (both tiers).
     if (drop.project === true)
         delete o["project"];
     if (drop.area === true)
@@ -386,7 +406,7 @@ function shapeItem(src, drop, compact, promoter) {
     // `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, so direct AND headed template children mark; the RS1 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).
@@ -396,13 +416,13 @@ function shapeItem(src, drop, compact, 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
+    // RS7 — 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
+    // RS2 compact — default-pruning (absence = the default).
+    delete o["startDate"]; // RS7 — position lives in `when`; substrate is full-tier only
     if (o["status"] === "open")
         delete o["status"];
     delete o["created"];
@@ -432,12 +452,12 @@ function withShapedItems(base, drop, compact, promoter) {
 }
 /**
  * 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
+ * into the RS5 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
+ * - `upcoming` — stage upcoming, day-grouped `[{when, 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}`
+ *   templates (after-completion / paused) form a trailing `{when: 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,
@@ -477,7 +497,7 @@ function rebucketChildren(children, drop, compact, promoter) {
                     datedByKey.set(date, []);
                     datedOrder.push(date);
                 }
-                // R12 — inside a date-group the group states the date, so a member whose
+                // RS7 — 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);
@@ -495,12 +515,12 @@ function rebucketChildren(children, drop, compact, promoter) {
     }
     const upcoming = datedOrder
         .toSorted((a, b) => a.localeCompare(b))
-        .map((date) => ({ date, items: datedByKey.get(date) }));
+        .map((date) => ({ when: date, items: datedByKey.get(date) }));
     if (restingTemplates.length > 0)
-        upcoming.push({ date: null, items: restingTemplates });
+        upcoming.push({ when: null, items: restingTemplates });
     return { anytime, upcoming, someday };
 }
-/** Flatten an internal IsoDateGroup[] (`[{date, items}]`) to its items, in order. */
+/** Flatten an internal IsoDateGroup[] (`[{when, items}]`) to its items, in order. */
 function flattenGroups(groups) {
     if (!Array.isArray(groups))
         return [];
@@ -515,7 +535,7 @@ 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 the un-headed BODY's four `children` bucket records (v2):
+ * The RS1 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),
@@ -524,7 +544,7 @@ const asArray = (v) => (Array.isArray(v) ? v : []);
  */
 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
+ * The RS1 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
@@ -537,10 +557,10 @@ const AREA_CHILD_DROP = { area: true, stage: true };
 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
+ * stage (RS5.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
+ * RS8, 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.
@@ -552,8 +572,8 @@ const SOMEDAY_SECTION_DROP = { area: true, stage: true };
 const NO_DROP = {};
 /**
  * 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 —
+ * (RS7 — the `today`/`evening` bucket key states it) AND the bucket-implied
+ * `stage` (RS8). 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
@@ -613,7 +633,7 @@ function stoppedMs(o) {
  *   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
+ * key is `when` end-to-end (`rebucketChildren` builds it — no rename) — `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
@@ -623,7 +643,11 @@ 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)
+        // The logbook-boundary flag lives on the internal `derived` substrate bag.
+        const isLogged = c !== null &&
+            typeof c === "object" &&
+            c["derived"]?.["logged"] === true;
+        if (isLogged)
             logged.push(c);
         else
             live.push(c);
@@ -633,8 +657,9 @@ function shapeContainerChildren(children, drop, compact, promoter) {
     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 })),
+        // The day-block ARRAY (`{when, items}`, `when: null` the resting block #V8);
+        // `rebucketChildren` already keys each block by `when`.
+        upcoming,
         someday: bucketRecord(someday),
         logbook: bucketRecord(logbook),
     };
@@ -664,7 +689,7 @@ function shapeProjectView(view, compact, promoter) {
         });
     });
     return {
-        // The card NODE keeps everything but is still an item DTO (universal + R10 reshapes).
+        // The card NODE keeps everything but is still an item DTO (universal + RS5 reshapes).
         project: shapeItem(view["project"], NO_DROP, false, promoter),
         children: shapeContainerChildren(view["bodyChildren"], PROJECT_CHILD_DROP, compact, promoter),
         headings: headingContainers,
@@ -676,7 +701,7 @@ function shapeProjectView(view, compact, promoter) {
  * 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}`
+ * the day-block ARRAY (R3, keyed by `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).
@@ -685,8 +710,9 @@ 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 })),
+        // The day-block ARRAY (`{when, items}`, `when: null` the resting block #V8);
+        // `rebucketChildren` already keys each block by `when`.
+        upcoming,
         someday: bucketRecord(someday),
     };
 }
@@ -803,7 +829,7 @@ function shapeUpcomingView(items, compact, promoter) {
             datedByKey.set(key, []);
             datedOrder.push(key);
         }
-        // R12 — inside a dated block the block states the date, so a member whose
+        // RS7 — 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) {
@@ -938,9 +964,9 @@ 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`.
- * The mixed/derived surfaces (search/changes/projects) keep it. The global
+ * The mixed/derived surfaces (search/changes/deadlines/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
+ * ({@link shapeUpcomingView}), keeping `stage` (RS5.2: stage-mixed — future-dated
  * `upcoming` rows beside deadline-forecast `anytime`/`someday` ones).
  */
 const FLAT_LIST_DROP = new Map([
@@ -949,11 +975,13 @@ const FLAT_LIST_DROP = new Map([
     ["trash", { stage: true }],
     ["changes", NO_DROP],
     ["search", NO_DROP],
+    // deadlines is stage-MIXED (to-dos + projects, deadline-ordered) — keep `stage`.
+    ["deadlines", 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
+ * Apply the universal reshapes + RS1 + RS2 + RS5 to a read payload for one view
+ * `kind`. `full` forces the FULL tier (RS2 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.
@@ -1031,9 +1059,10 @@ export function candidateRef(type, src) {
     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") {
+    // materialized lifecycle substrate (`derived.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["derived"] ?? {})["start"] === "string") {
         const stage = stageOf(s);
         out.stage = stage;
         const when = whenOf(s, stage);