things-api 0.12.0 → 0.13.0

package/dist/read/shape.js

@@ -54,16 +54,16 @@
  *   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); 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
- *   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).
+ *   it (same fact, one word); an unprojected template has no `when`.
+ * - `when` is KEPT on every row it is present on. (The read-shape doctrine
+ *   flattened the card `upcoming` date-groups into the project-/area-view flat
+ *   `items[]`, so no enclosing node states the position anymore.) It rides the
+ *   today view's flat `items[]` (Today-proper vs This-Evening), the project-/area-
+ *   view `items[]`, and the flat `upcoming`/`anytime`/`inbox`/`someday` catalogues,
+ *   search, changes (a deadline-pulled row reads `when: "today"` in the mixed
+ *   search/changes surfaces, informatively; note R13 re-files it to stage `anytime`
+ *   and the flat inbox/someday views now EXCLUDE it — it appears in the `anytime`
+ *   catalogue instead, `when: "today"` kept, stage dropped as pure).
  *
  * ## R13 — provisional Today members + GUI-faithful pulled-row membership
  * BANNER1 / BANNER1b (docs/lab/banner1-research.md). Two coupled facts:
@@ -77,10 +77,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 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
- *   INCLUDES them (src/read/views.ts + predicates.ts DEADLINE_PULLED) — GUI fidelity.
+ *   derives stage `anytime`, and the today view's flat `items[]` is stage-PURE →
+ *   `stage` is DROPPED there (TODAY_ITEM_DROP) while `when` is KEPT. The flat
+ *   someday/inbox views EXCLUDE pulled rows and the anytime view INCLUDES them
+ *   (src/read/views.ts + predicates.ts DEADLINE_PULLED) — GUI fidelity.
  *
  * ## Universal item-DTO reshapes (R9 — EVERY tier, EVERY read kind incl. detail)
  * - **checklist nesting** — flat counts → presence-keyed `checklist: {open,total}`.
@@ -113,6 +113,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 +300,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;
@@ -300,9 +340,9 @@ function shapeItem(src, drop, compact) {
     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).
+    // EVERY tier (they never appear on the wire); `when` is emitted on every row it
+    // is present on (since the read-shape doctrine flattened the card date-groups,
+    // no enclosing node states the position anymore — the flat lists carry it).
     delete o["today"];
     delete o["evening"];
     // §9n — a reminder byte is presentation-dead once its `startDate` goes strictly
@@ -318,6 +358,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 +371,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,112 +411,58 @@ 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);
-    return out;
-}
-/**
- * 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).
- */
-function rebucketChildren(children, drop, compact) {
-    const anytime = [];
-    const someday = [];
-    const datedByKey = new Map();
-    const datedOrder = [];
-    const restingTemplates = [];
-    const shape = (c) => shapeItem(c, drop, compact);
-    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"]);
-        }
-    }
+    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 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). */
-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 };
+/**
+ * The flat project-view `items[]` rows (read-shape doctrine §3.12): drop
+ * project/area (the card states them) but KEEP `stage` (the list is stage-MIXED:
+ * anytime + upcoming + someday + closed-unswept), `when`, and the `heading` ref.
+ * The heading ref is kept + flattened even in compact (keepHeading), scoped to
+ * the owning project — flat title + `headingUuid` when the title would not
+ * round-trip — so a consumer reconstructs a heading's members from the rows.
+ */
+const PROJECT_ITEM_DROP = { project: true, area: true, keepHeading: true };
+/**
+ * Project-view LOGBOOK (flat logged) rows (read-shape doctrine §3.12 / #C4): drop
+ * project/area (the card states them) but KEEP `stage` and the `heading` ref
+ * (drop.keepHeading). The bucket is stage-MIXED since it absorbs the children of
+ * SWEPT ARCHIVED headings too — mostly `logbook`, but it can hold the odd OPEN
+ * child a Put-Back stranded under an archived heading (HEADARC2-C, stage
+ * `anytime`) — so `stage` is not provably implied and is kept. The heading ref is
+ * the GUI hint (the in-project logged toggle labels the HEADING; the global
+ * Logbook labels the PROJECT — the two-view asymmetry, HEADARC2-B), flat title +
+ * project-scoped `headingUuid`.
+ */
+const PROJECT_LOGBOOK_DROP = {
+    project: true,
+    area: true,
+    keepHeading: true,
+};
+/**
+ * The flat area-view `items[]` rows (read-shape doctrine §3.13): drop `area` (the
+ * card states it) but KEEP `stage` (the list is stage-MIXED — anytime + upcoming
+ * + someday + closed-unswept) and `when`. Area direct to-dos are never headed and
+ * never project-nested, so nothing else to drop.
+ */
+const AREA_ITEM_DROP = { area: true };
 /** Area-view PROJECTS list: a mixed listing of the area's project rows — keep `stage`, drop area. */
 const AREA_PROJECTS_DROP = { area: true };
 /**
@@ -465,100 +481,133 @@ 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 flat `items[]`: drop the view-implied `stage` (R13) but KEEP
+ * `when`. Every Today member derives stage `anytime` by construction — an ARRIVED
+ * `startDate` (step 5) or a DEADLINE PULL (step 2½) both derive `anytime`, and
+ * there are no future-dated or undated-someday Today members — so the today view
+ * is provably stage-PURE `anytime` and the field is redundant (verified strict by
+ * the today purity property test in test/unit/stage.test.ts). `when` is KEPT: the
+ * flat list interleaves Today-proper (`when: "today"`) and This-Evening
+ * (`when: "evening"`) members, so each row must carry which render section it
+ * belongs to — the split is derived from `when`, not a wire bucket. `provisional`
+ * is NOT a drop — the banner pip is per-row, nothing implies it.
  */
-const TODAY_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;
+const TODAY_ITEM_DROP = { stage: true };
+/**
+ * Shape a heading catalog entry (a `headings[]` node — the flat `{uuid,title,
+ * archived?}` catalog, read-shape doctrine §3.12 / #C3). The type is implied by
+ * position, and a heading has no open/canceled/completed vocabulary the reader
+ * needs — so:
+ * - DROP `type` (positional: this slot is always a heading; the "absent type =
+ *   to-do" convention is scoped to ROWS/candidates, never this catalog entry);
+ * - DROP `project` (the card states it);
+ * - REPLACE `status` with the presence-keyed `archived` (the stopDate, an ISO
+ *   date-time following the `stopped`/logged-row convention) — emitted ONLY when
+ *   the heading is archived (status "completed"), OMITTED when open. The entry
+ *   carries only whether-and-when it was archived; sweptness (past the logbook
+ *   boundary) is not on the wire — the TTY derives it (#C3a).
+ */
+function shapeHeadingNode(src) {
+    if (src === null || typeof src !== "object")
+        return src;
+    const h = { ...src };
+    delete h["project"];
+    delete h["type"];
+    const isArchived = h["status"] !== undefined && h["status"] !== "open";
+    const stopped = h["stopped"];
+    delete h["status"];
+    delete h["stopped"];
+    // Presence-keyed `archived` — the ISO archive timestamp (past-participle twin of
+    // `stopped`/`created`/`modified`), full-datetime serialization like `stopped`.
+    if (isArchived && stopped != null)
+        h["archived"] = stopped;
+    return h;
+}
+/** Stopped-DESC comparator for the flat logbook (open odd children — no stopDate — sort last). */
+function byStoppedDesc(a, b) {
+    const t = (x) => {
+        const s = x !== null && typeof x === "object" ? x["stopped"] : null;
+        return s instanceof Date ? s.getTime() : -Infinity;
     };
-    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);
+    return t(b) - t(a);
+}
+/**
+ * Shape a project view (read-shape doctrine §3.12 / #C3 / #C4). The live children
+ * are ONE flat `items[]` in project index order — each row carrying `stage`,
+ * `when`, and its `heading` ref (flat title + project-scoped `headingUuid`) — so a
+ * consumer reconstructs a heading's members by filtering `items` on `heading`.
+ * `headings[]` is the flat catalog `[{uuid,title,archived?}]` of EVERY heading
+ * (live + swept archived) in index order — the ORDER axis. `logbook` is one flat
+ * `stopDate DESC` list of ALL swept children — of open headings, un-headed, AND
+ * archived headings — each carrying its `heading` ref; `logbookHeadings` is gone
+ * (its rows folded in, the archived heading itself now a catalog entry with
+ * `archived`). The card node is left full + ancestry-intact.
+ */
+function shapeProjectView(view, compact, promoter) {
+    // The heading catalog: every heading node (live + swept archived), index order,
+    // flattened to `{uuid,title,archived?}`. Membership rides the flat item/logbook
+    // row `heading` refs; archived-ness reads off `archived` here.
+    const headings = Array.isArray(view["headingCatalog"])
+        ? view["headingCatalog"].map(shapeHeadingNode)
+        : [];
+    // The flat logbook: swept children of open/un-headed headings (`logged`) PLUS
+    // the children of swept archived headings (`loggedHeadings`), merged into ONE
+    // stopDate-DESC list (open odd children last), each carrying its heading ref.
+    const loggedRows = [
+        ...asArray(view["logged"]),
+        ...asArray(view["loggedHeadings"]).flatMap((g) => g !== null && typeof g === "object" ? asArray(g["items"]) : []),
+    ].toSorted(byStoppedDesc);
     const out = { ...view };
     delete out["active"];
     delete out["scheduled"];
     delete out["repeating"];
+    delete out["someday"];
     delete out["logged"];
+    delete out["loggedHeadings"];
+    delete out["headingCatalog"];
     // Trashed children live only in `things trash` — never a project-view bucket.
     // Delete defensively in case an untyped source carries the old key.
     delete out["trashed"];
     // The project card NODE keeps everything (children derive their container from
     // it), but is still an item DTO, so the universal + R10 reshapes apply.
-    out["project"] = shapeItem(view["project"], NO_DROP, false);
-    out["anytime"] = anytime;
-    out["upcoming"] = upcoming;
-    out["someday"] = someday;
+    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`.
-    out["logbook"] = shapeList(view["logged"], cd, compact);
+    // A project keeps its in-context `logbook` (a project is a bounded object with a
+    // real done-state); trashed children live only in `things trash`. The flat
+    // rows KEEP stage (mixed) + their heading ref (PROJECT_LOGBOOK_DROP).
+    out["logbook"] = shapeList(loggedRows, PROJECT_LOGBOOK_DROP, compact, promoter);
     return out;
 }
-/** Shape every collection bucket of an area view; the area node keeps its identity (tags folded). */
-function shapeAreaView(view, compact) {
-    const looseMembers = [
-        ...asArray(view["active"]),
-        ...flattenGroups(view["scheduled"]),
-        ...asArray(view["someday"]),
-        ...asArray(view["repeating"]),
-    ];
-    const { anytime, upcoming, someday } = rebucketChildren(looseMembers, AREA_CHILD_DROP, compact);
+/**
+ * Shape an area view (read-shape doctrine §3.13). The direct to-dos dissolve into
+ * ONE flat `items[]` in index order — each row carrying `stage` + `when`, `area`
+ * dropped (the card states it). The stage/date sub-buckets (anytime/upcoming/
+ * someday) are gone. `projects[]` is KEPT — the area's child-project sidebar rank
+ * is a DISTINCT order axis from the direct-to-do index, so it earns its own list
+ * (mixed-stage, someday/scheduled projects included; the render split is TTY-only).
+ * The area node keeps its identity (tags folded).
+ */
+function shapeAreaView(view, compact, promoter) {
     const out = { ...view };
     delete out["active"];
     delete out["scheduled"];
     delete out["repeating"];
+    delete out["someday"];
     // No `logbook` or `trash` bucket: an area's logbook is the bounded query
     // `things logbook --area <ref>`, and trashed rows live only in `things trash`.
     // Delete defensively in case an untyped source carries the old keys.
     delete out["logged"];
     delete out["trashed"];
     out["area"] = shapeArea(view["area"]);
-    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;
+    // The flat direct to-dos — stage/when kept, area dropped.
+    out["items"] = shapeList(view["items"], AREA_ITEM_DROP, compact, promoter);
+    // The projects list is a mixed listing of the area's project rows — keep stage,
+    // sidebar order (the distinct order axis).
+    out["projects"] = shapeList(view["projects"], AREA_PROJECTS_DROP, compact, promoter);
     return out;
 }
 /** Fold an area entity's tags to string names in place (returns a shallow copy). */
@@ -569,19 +618,11 @@ 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) {
-    return {
-        ...view,
-        today: shapeList(view["today"], TODAY_SECTION_DROP, compact),
-        evening: shapeList(view["evening"], TODAY_SECTION_DROP, compact),
-    };
-}
 /** 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
@@ -608,28 +649,36 @@ 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 today view: one flat `items[]` of Today members (Today-proper + This
+    // Evening interleaved in comparator order); drop the view-implied `stage`,
+    // KEEP `when` (it carries the render section). The `counts` aggregate rides
+    // `meta.counts`, not `data`. The wire wrapper is `{ items }` (read-driver).
     if (kind === "today" && data !== null && typeof data === "object") {
-        return shapeTodayView(data, compact);
+        return shapeList(data["items"], TODAY_ITEM_DROP, 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 +712,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;