@elaraai/e3-ui 1.0.94 → 1.0.96

package/dist/src/schedule/events.js

@@ -20,6 +20,16 @@
  * events on one resource at once are a conflict (`overlaps`), and the kind's
  * own inspector for one event (`inspector`, #1197).
  *
+ * The builders over the app's own records take their roles beside Plan's
+ * (#1367, `Builder Interfaces Spec.md` §4.1): the Roster's — the fields a
+ * duty's shift, group, position and activity are (`shift`, `group`,
+ * `position`, `activity`), and the hours it counts (`hours`, an accessor) —
+ * and the Allocation's — the fields a bin's arrival, parts, hold and kind are
+ * (`arrival`, `parts`, `hold`, `kind`). A kind is one builder's or the
+ * other's. A builder ignores the roles it has no use for, so one record of
+ * duties drives a Calendar and the Roster at once. `title` is optional: the
+ * Calendar and Plan, which draw it, refuse a kind without one.
+ *
  * The kind closes the record behind East functions over beast2 bytes
  * ({@link ScheduleKindType}): its events over a window and its backlog, each
  * with the drafts in place; a gesture written into an entry; the author's
@@ -28,13 +38,15 @@
  * true })`); and its history. A builder's payload is one type whatever the
  * records hold, and the renderer never needs a row type.
  *
- * A record Slice reads overlap queries through its declared interval indexes
- * (`slice: Slice.bindRecord(...)`, with `range` naming the start field).
- * It shares the toolbar's filters and window, counts original events once,
- * and reads backlog through the same choices with an Unset start. It requires
- * `entries` for original-key inspection and Save. Existing drafts outside a
- * new narrowing remain in the session; Save includes them. Do not combine
- * this with a local `filter`, `window`, or `backlogWindow`.
+ * A builder's `Slice.bindRecords` narrows a kind through the source it names
+ * after the kind's slot (#1343): the builder hands that part to `build(slot,
+ * part)`, and the kind reads overlap queries through its declared interval
+ * indexes (the source's `range` naming the start field). It shares the
+ * toolbar's filters and window, counts original events once, and reads backlog
+ * through the same choices with an Unset start. It requires `entries` for
+ * original-key inspection and Save. Existing drafts outside a new narrowing
+ * remain in the session; Save includes them. A kind narrowed so takes no
+ * `window` or `backlogWindow`.
  *
  * A large record may also be read a window at a time (#1199, `window.ts`): given
  * `window`, a paged read of a day index keyed by `Schedule.days`, the kind's
@@ -50,36 +62,41 @@
  * editing session's, which is a session over the record's revision rather
  * than its snapshot — its drafts held by key, each checked by the record
  * against what it began from, and a Save's entries read back by key. It builds
- * two ways:
- * `build(slot)` is the Calendar's kind, which takes no notice of Plan's
- * options, and `buildPlan(slot)` Plan's ({@link PlanEventKindType}), the same
- * kind with how it draws, its roles, and its events as Plan draws them.
+ * four ways:
+ * `build(slot, part)` is the Calendar's kind, which takes no notice of Plan's
+ * options; `buildPlan(slot, part)` Plan's ({@link PlanEventKindType}), the
+ * same kind with how it draws, its roles, and its events as Plan draws them;
+ * and `buildRoster(slot, part)` the Roster's ({@link ScheduleRosterKindType})
+ * and `buildAllocation(slot, part)` the Allocation's
+ * ({@link ScheduleAllocationKindType}): the Calendar's kind, its form over the
+ * fields none of the builder's roles writes, with the stored rows of a
+ * period, and the builder's roles read from a row and written into one —
+ * every other field of the row as it was (B1), a new row's its type's
+ * default.
  *
  * A record may be keyed by any type: an event is named by its key's text, a
  * String key as it is, any other key as East prints it.
  *
  * @packageDocumentation
  */
-import { ArrayType, BlobType, BooleanType, DateTimeType, DictType, East, Expr, FloatType, IntegerType, OptionType, StringType, StructType, isTypeEqual, none, printType, some, toEastTypeValue, variant, } from "@elaraai/east";
-import { EventStateType } from "@elaraai/east-ui";
-import { EditingApplyResultType, EditingChangeSetTypeFor, EditingDraftFieldType, EditingReadinessType, EditingType, EditingWireApplyType, Fields, FieldSpecType, TickFormatType, } from "@elaraai/east-ui/internal";
-import { Record } from "../bind/record.js";
+import { ArrayType, BlobType, BooleanType, DateTimeType, DictType, East, Expr, FloatType, IntegerType, OptionType, StringType, StructType, defaultValue, isTypeEqual, none, printType, some, toEastTypeValue, variant, } from "@elaraai/east";
+import { EventStateType, TimeStepType } from "@elaraai/east-ui";
+import { EditingDraftFieldType, EditingReadinessType, Fields, FieldSpecType, TickFormatType } from "@elaraai/east-ui/internal";
 import { RowInspectorType, rowInspector } from "../utils/row-inspector.js";
+import { scheduleAccessor } from "./accessor.js";
 import { SCHEDULE_TEMPLATES, checkedTemplates } from "./templates.js";
 import { SCHEDULE_DEF } from "./resources.js";
 import { scheduleRecordWindow } from "./record-window.js";
-import { checkEntries, checkIndexWindow, scheduleBacklogWindow, scheduleDayWindow, scheduleEntryByKey, scheduleLastKey } from "./window.js";
-import { PlanEventItemType, PlanEventKindType, PlanEventReadType, ScheduleClockType, ScheduleDraftsType, ScheduleDurationType, ScheduleEntriesType, ScheduleItemType, ScheduleKindType, ScheduleReadyEntryType, ScheduleResourceRefType, ScheduleStatusCasesFor, ScheduleStatusType, ScheduleWriteType, ScheduleTemplateType, ScheduleReadType, } from "./types.js";
+import { scheduleRecordSession } from "./session.js";
+import { checkEntries, checkIndexWindow, optionOf, scheduleBacklogWindow, scheduleDayWindow, typeText } from "./window.js";
+import { PlanEventItemType, PlanEventKindType, PlanEventReadType, ScheduleAllocationEntryType, ScheduleAllocationKindType, ScheduleAllocationRolesType, ScheduleClockType, ScheduleDraftsType, ScheduleDurationType, ScheduleItemType, ScheduleKindType, ScheduleReadyEntryType, ScheduleResourceRefType, ScheduleRosterEntryType, ScheduleRosterKindType, ScheduleRosterRolesType, ScheduleStatusCasesFor, ScheduleStatusType, ScheduleWriteType, ScheduleTemplateType, ScheduleReadType, } from "./types.js";
+/** The Roster's roles, as a kind's options name them. */
+const ROSTER_ROLES = ["shift", "group", "position", "activity", "hours"];
+/** The Allocation's roles, as a kind's options name them. */
+const ALLOCATION_ROLES = ["arrival", "parts", "hold", "kind"];
 // ============================================================================
 // Reading East types
 // ============================================================================
-/** Whether a type is an Option, and of what. */
-function optionOf(type) {
-    if (type.type !== "Variant")
-        return undefined;
-    const some = type.cases["some"];
-    return some !== undefined && isTypeEqual(type, OptionType(some)) ? some : undefined;
-}
 /** A variant's cases, when every one of them holds a String. */
 function stringCases(type) {
     if (type.type !== "Variant" || optionOf(type) !== undefined)
@@ -91,17 +108,19 @@ function stringCases(type) {
 function fieldOf(row, name) {
     return row[name];
 }
-/** A type as the refusals name it: an Option as an Option of what it holds. */
-function typeText(type) {
-    const inner = optionOf(type);
-    return inner === undefined ? printType(type) : `an Option of ${printType(inner)}`;
-}
 /** The ways a kind draws. */
 const DRAWS = ["span", "buckets", "cards", "marks"];
 export function scheduleEvents(record, input) {
     const config = input;
     const where = `Schedule.events: "${config.name}"`;
-    const handle = record;
+    // The options #1343 moved to the builder, refused by name for an app that still passes them.
+    if ("slice" in config) {
+        throw new Error(`${where}: \`slice\` moves to the builder — name a source of its Slice.bindRecords after this kind's slot, ` +
+            "slice={{ slice: Slice.bindRecords(key, { <slot>: { source, fields, range } }) }}, and the builder narrows the kind through it");
+    }
+    if ("filter" in config) {
+        throw new Error(`${where}: \`filter\` is gone — narrow the kind through its builder's Slice.bindRecords, a source named after its slot, over the record's indexes`);
+    }
     const handleType = Expr.type(record);
     const read = handleType.type === "Struct" ? handleType.fields["read"] : undefined;
     if (handleType.type !== "Struct" || read === undefined || read.type !== "Function"
@@ -121,9 +140,10 @@ export function scheduleEvents(record, input) {
             throw new Error(`${where}: \`${prop}\` names "${name}", a field the row does not have (${Object.keys(fields).join(", ")})`);
         return type;
     };
-    // The title.
-    if (!isTypeEqual(fieldType("title", config.title), StringType)) {
-        throw new Error(`${where}: \`title\` names a String field — "${config.title}" holds ${typeText(fields[config.title])}`);
+    // The title: optional, as the Roster and the Allocation draw none (#1367); the Calendar and Plan refuse a kind without one.
+    const titleField = config.title;
+    if (titleField !== undefined && !isTypeEqual(fieldType("title", titleField), StringType)) {
+        throw new Error(`${where}: \`title\` names a String field — "${titleField}" holds ${typeText(fields[titleField])}`);
     }
     // The times: `start` and `end`, DateTime or Options of DateTime alike; or an instant kind's `at`, in their place.
     const instantKind = config.at !== undefined;
@@ -229,6 +249,33 @@ export function scheduleEvents(record, input) {
     const stateField = role("state", config.state, EventStateType, "an EventStateType field, the lifecycle an event wears");
     const quantityField = role("quantity.field", config.quantity === undefined ? undefined : config.quantity.field, FloatType, "a Float field, the quantity a bar prints");
     const laneField = role("lane", config.lane, StringType, "a String field, the lane a tile sits in");
+    // The builders' roles (#1367, `Builder Interfaces Spec.md` §4.1), each a field of the row, checked as Plan's are. A
+    // kind is the Roster's duties or the Allocation's bins, never both.
+    const given = (roles) => roles.filter((r) => config[r] !== undefined);
+    const rosterGiven = given(ROSTER_ROLES);
+    const allocationGiven = given(ALLOCATION_ROLES);
+    if (rosterGiven.length > 0 && allocationGiven.length > 0) {
+        throw new Error(`${where}: holds roles of both the Roster (${rosterGiven.join(", ")}) and the Allocation (${allocationGiven.join(", ")}) — ` +
+            "a kind is the Roster's duties or the Allocation's bins: give it one builder's roles");
+    }
+    const shiftField = role("shift", config.shift, StringType, "a String field");
+    const groupField = role("group", config.group, StringType, "a String field");
+    const positionField = role("position", config.position, StringType, "a String field");
+    const activityField = role("activity", config.activity, OptionType(StringType), "an Option of a String field");
+    const arrivalField = role("arrival", config.arrival, OptionType(StringType), "an Option of a String field");
+    const partsField = role("parts.field", config.parts === undefined ? undefined : config.parts.field, DictType(StringType, FloatType), "a Dict of String to Float field");
+    if (config.parts !== undefined && (typeof config.parts.of !== "string" || config.parts.of === "")) {
+        throw new Error(`${where}: \`parts.of\` names the resource slot its keys are of — the builder's resources a bin is allocated to (of: "kilns")`);
+    }
+    const holdField = role("hold", config.hold, TimeStepType, "a TimeStep field");
+    const kindField = role("kind", config.kind, OptionType(StringType), "an Option of a String field");
+    // The fields none of the Allocation's roles maps (#1371): what an arrival's values give a booked bin (B13) — every
+    // field but its time, its lane and its roles' fields — which the Allocation reads at build, and `buildAllocation` writes.
+    const allocationMapped = new Set([startField, endField, ...[resource?.field, arrivalField, quantityField, partsField, holdField, kindField]
+            .filter((name) => name !== undefined)]);
+    const allocationValues = StructType(Object.fromEntries(Object.entries(fields).filter(([name]) => !allocationMapped.has(name))));
+    // The hours a duty counts, reified once and called per row.
+    const hoursOf = config.hours === undefined ? undefined : scheduleAccessor(rowType, keyType, FloatType, config.hours, (returns) => `${where}: \`hours\` returns a Float, the hours a duty counts — and this one returns ${returns}`);
     // The removed verdict, named (#1260) — a plain JS caller would otherwise lose it silently.
     if ("review" in config) {
         throw new Error(`${where}: \`review\` is removed (#1260) — a Plan approves and rejects nothing: its changes are drafts of its session, saved together`);
@@ -241,6 +288,17 @@ export function scheduleEvents(record, input) {
     const valuesType = StructType(Object.fromEntries(Object.entries(fields).filter(([name]) => !placed.has(name))));
     const boundTemplates = config.templates !== undefined && SCHEDULE_TEMPLATES in config.templates
         ? checkedTemplates(config.templates, valuesType, where) : undefined;
+    // A templates record's events run as long as each says, or — an instant kind's — are one time (#1344).
+    if (config.templates !== undefined && SCHEDULE_TEMPLATES in config.templates) {
+        if (!instantKind && !config.templates.timed) {
+            throw new Error(`${where}: its templates give each event's \`duration\` — Schedule.templates(rows, { …, duration: (row) => variant("hours", …) }), how long the event a template creates runs`);
+        }
+        if (instantKind && config.templates.timed) {
+            throw new Error(`${where}: an instant kind's events are one time, and its templates give a \`duration\` — leave it out of Schedule.templates`);
+        }
+    }
+    // The builder's source whose shown keys filter the templates: the one a templates list names (#1343).
+    const templatesSource = config.templates !== undefined && SCHEDULE_TEMPLATES in config.templates ? config.templates.source : undefined;
     const templates = config.templates !== undefined && !(SCHEDULE_TEMPLATES in config.templates) ? config.templates : [];
     const seen = new Set();
     for (const t of templates) {
@@ -255,9 +313,6 @@ export function scheduleEvents(record, input) {
         }
     }
     // The windows (#1199): the days in view through a day index, the backlog through a backlog index.
-    if (config.slice !== undefined && (config.window !== undefined || config.backlogWindow !== undefined || config.filter !== undefined)) {
-        throw new Error(`${where}: slice replaces window, backlogWindow and local filter; narrow through the record's indexes`);
-    }
     const dayWindow = config.window === undefined ? undefined
         : checkIndexWindow(config.window, "window", keyType, rowType, DateTimeType, where);
     let backlogWindow;
@@ -275,34 +330,24 @@ export function scheduleEvents(record, input) {
     // Nor one event: it is read by its key through the record's own entries.
     let entries;
     if (config.entries !== undefined) {
-        if (dayWindow === undefined && config.slice === undefined) {
-            throw new Error(`${where}: \`entries\` reads one event by its key beside \`window\` or record \`slice\` — give one of those with it`);
-        }
         entries = checkEntries(config.entries, keyType, rowType, `${where}: \`entries\``);
     }
-    else if (dayWindow !== undefined || config.slice !== undefined) {
+    else if (dayWindow !== undefined) {
         throw new Error(`${where}: an indexed kind reads only the window — and one event, the inspector's ` +
             "or its editing's, is read by its key: give `entries` beside it, Data.bindPaged(record), the record's own entries");
     }
-    const byKey = entries === undefined ? undefined : scheduleEntryByKey(entries, keyType, rowType);
-    const lastKey = entries === undefined ? undefined : scheduleLastKey(entries, keyType);
-    // The inspector's form: the fields a gesture does not write, in the hints' order.
-    const omit = [...new Set([config.title, ...placed, ...(config.status === undefined ? [] : [config.status.field])])];
-    const formSpecs = Fields.specs(rowType, (config.fields ?? {}), omit);
-    // The Save: one patch commit through the record's patch door, its entries
-    // checked against what the drafts began from.
-    const apply = Record.onApply(record, { keyed: true });
+    // The record's session (`session.ts`): its reads, whole and by key, and its Save, one patch commit through the
+    // record's patch door, its entries checked against what the drafts began from — declared now, so a record bound
+    // without its patch door is refused where its kind is.
+    const session = scheduleRecordSession(record, keyType, rowType, entries);
+    const { readAll, byKey, idOf, keyOf } = session;
+    // The inspector's form: the fields a gesture does not write, in the hints' order. A builder over the app's own
+    // records draws its roles in its own sections, so its form leaves out the fields they name too.
+    const formOver = (omitted) => Fields.specs(rowType, (config.fields ?? {}), [...new Set(omitted.filter((name) => name !== undefined))]);
+    const formSpecs = formOver([titleField, ...placed, config.status?.field]);
     // ── The East the seams share ─────────────────────────────────────────
     const draftType = EditingDraftFieldType(rowType);
     const EntryRowType = StructType({ id: StringType, key: keyType, row: rowType });
-    const readAll = handle["read"];
-    // An entry's id is its key's text: a String key as it is, any other key as East prints it.
-    const idOf = (keyType.type === "String"
-        ? East.function([StringType], StringType, (_$, key) => key)
-        : East.function([keyType], StringType, (_$, key) => East.print(key)));
-    const keyOf = (keyType.type === "String"
-        ? East.function([StringType], StringType, (_$, id) => id)
-        : East.function([StringType], keyType, (_$, id) => id.parse(keyType)));
     // The entry a draft leaves: the drafted entry, none for one deleted, the held one for a draft it cannot read.
     const drafted = East.function([BlobType, OptionType(rowType)], OptionType(rowType), (_$, bytes, held) => bytes.decodeBeast(draftType, "v2").match({
         value: (_$2, row) => East.value(some(row), OptionType(rowType)),
@@ -313,7 +358,7 @@ export function scheduleEvents(record, input) {
     // entries it does not hold: a draft moved into a window shows, and one moved out of it leaves by its times.
     // Erased as the record's own read is, so the record whole and a window of it are one type.
     const HeldType = DictType(keyType, rowType);
-    const withDrafts = East.function([HeldType, ScheduleDraftsType], ArrayType(EntryRowType), ($, held, drafts) => {
+    const withDraftsFor = (narrowed) => East.function([HeldType, ScheduleDraftsType], ArrayType(EntryRowType), ($, held, drafts) => {
         const idText = $.const(idOf);
         const parse = $.const(keyOf);
         const draft = $.const(drafted);
@@ -332,7 +377,7 @@ export function scheduleEvents(record, input) {
                 // Existing drafts outside an indexed result stay in the session,
                 // but do not leak back into a different narrowing. New entries
                 // remain an explicit unsaved layer until their first Save.
-                if (config.slice !== undefined && byKey !== undefined) {
+                if (narrowed && byKey !== undefined) {
                     const find = $3.const(byKey);
                     $3.if(find(id).hasTag("absent").not(), $4 => { $4.continue(label); });
                 }
@@ -461,44 +506,73 @@ export function scheduleEvents(record, input) {
         }
     };
     collect(rowType, []);
-    // The rows a window reads (#1199): the days in view through the day index, and the backlog through
-    // the backlog index — each `none` while its search or a page is in flight. Without them, the record whole.
-    const readDays = config.slice !== undefined
-        ? scheduleRecordWindow(config.slice, keyType, rowType, startField, endField, optional, false, where)
-        : dayWindow === undefined ? undefined : scheduleDayWindow(dayWindow, keyType, rowType, where);
-    const indexedBacklog = config.slice !== undefined && optional
-        ? scheduleRecordWindow(config.slice, keyType, rowType, startField, endField, optional, true, where) : undefined;
-    const readBacklog = indexedBacklog === undefined
-        ? backlogWindow === undefined ? undefined : scheduleBacklogWindow(backlogWindow, keyType, rowType, where)
-        : East.function([], OptionType(HeldType), $ => {
-            const read = $.const(indexedBacklog);
-            return read(new Date(0), new Date(1));
+    const readsOf = (slot, part) => {
+        if (part === undefined) {
+            if (entries !== undefined && dayWindow === undefined) {
+                throw new Error(`${where}: \`entries\` reads one event by its key beside \`window\`, or beside the kind's source of its builder's ` +
+                    `Slice.bindRecords (one named "${slot}") — give one of those with it`);
+            }
+            const unscheduled = backlogWindow === undefined ? undefined : scheduleBacklogWindow(backlogWindow, keyType, rowType, where);
+            return {
+                days: dayWindow === undefined ? undefined : scheduleDayWindow(dayWindow, keyType, rowType, where),
+                // A backlog index's read takes no window: the window is given, and read past.
+                backlog: unscheduled === undefined ? undefined : East.function([DateTimeType, DateTimeType], OptionType(HeldType), ($, _from, _to) => {
+                    const read = $.const(unscheduled);
+                    return read();
+                }),
+                withDrafts: withDraftsFor(false),
+            };
+        }
+        if (dayWindow !== undefined || backlogWindow !== undefined) {
+            throw new Error(`${where}: the builder's source "${slot}" narrows this kind through its record's indexes — leave \`window\` and \`backlogWindow\` out`);
+        }
+        if (entries === undefined) {
+            throw new Error(`${where}: the builder's source "${slot}" reads only its narrowing — and one event, the inspector's ` +
+                "or its editing's, is read by its key: give `entries` beside it, Data.bindPaged(record), the record's own entries");
+        }
+        const scheduled = scheduleRecordWindow(part, slot, keyType, rowType, startField, endField, optional, false, where);
+        if (!optional)
+            return { days: scheduled, backlog: undefined, withDrafts: withDraftsFor(true) };
+        // A kind with a backlog reads both through its source as one: what its narrowing holds over the window and in
+        // its backlog. A draft then moves an event between the two by its times alone, and a draft the narrowing does
+        // not hold never shows in either (#1343).
+        const backlogged = scheduleRecordWindow(part, slot, keyType, rowType, startField, endField, optional, true, where);
+        const both = East.function([DateTimeType, DateTimeType], OptionType(HeldType), ($, from, to) => {
+            const inWindow = $.const(scheduled);
+            const inBacklog = $.const(backlogged);
+            const result = $.let(East.value(none, OptionType(HeldType)), OptionType(HeldType));
+            $.match(inWindow(from, to), {
+                some: ($2, rows) => {
+                    $2.match(inBacklog(from, to), {
+                        some: ($3, more) => {
+                            const all = $3.let(rows.copy());
+                            $3(all.unionInPlace(more, (_$4, held) => held));
+                            $3.assign(result, East.value(some(all), OptionType(HeldType)));
+                        },
+                    });
+                },
+            });
+            return result;
         });
-    // One event by its key through the record's own entries, and the largest key (#1199): what a kind read a
-    // window at a time reads in place of the record whole.
-    // Adapt the author's typed predicate once; Slice owns its semantics and state.
-    const filter = config.filter === undefined ? undefined
-        : East.function([rowType, keyType], BooleanType, (_$, row, key) => config.filter(row, key));
+        return { days: both, backlog: both, withDrafts: withDraftsFor(true) };
+    };
     /** An item seam over a window: the events whose items `itemFn` makes that overlap `[from, to)`. */
-    const windowOf = (itemType, itemFn) => East.function([DateTimeType, DateTimeType, ScheduleDraftsType], OptionType(ArrayType(itemType)), ($, from, to, drafts) => {
-        const inPlace = $.const(withDrafts);
+    const windowOf = (itemType, itemFn, reads) => East.function([DateTimeType, DateTimeType, ScheduleDraftsType], OptionType(ArrayType(itemType)), ($, from, to, drafts) => {
+        const inPlace = $.const(reads.withDrafts);
         const item = $.const(itemFn);
-        const accepts = filter === undefined ? undefined : $.const(filter);
         const result = $.let(East.value(none, OptionType(ArrayType(itemType))), OptionType(ArrayType(itemType)));
         let read;
-        if (readDays === undefined) {
+        if (reads.days === undefined) {
             read = $.let(East.value(some(readAll()), OptionType(HeldType)));
         }
         else {
-            const days = $.const(readDays);
+            const days = $.const(reads.days);
             read = $.let(days(from, to));
         }
         $.match(read, {
             some: ($2, rows) => {
                 const out = $2.let([], ArrayType(itemType));
-                $2.for(inPlace(rows, drafts), ($3, entry, _i, label) => {
-                    if (accepts !== undefined)
-                        $3.if(accepts(entry.row, entry.key).not(), $4 => { $4.continue(label); });
+                $2.for(inPlace(rows, drafts), ($3, entry) => {
                     // Every item type holds what every view draws, its start and end among them.
                     const one = $3.const(item(entry));
                     $3.match(one.start, {
@@ -520,28 +594,25 @@ export function scheduleEvents(record, input) {
         });
         return result;
     });
-    /** An item seam over the backlog: the rows with no time, as `itemFn` makes them. */
-    const backlogOf = (itemType, itemFn) => East.function([ScheduleDraftsType], OptionType(ArrayType(itemType)), ($, drafts) => {
+    /** An item seam over the backlog: the rows with no time, as `itemFn` makes them, the window the canvas reads given. */
+    const backlogOf = (itemType, itemFn, reads) => East.function([DateTimeType, DateTimeType, ScheduleDraftsType], OptionType(ArrayType(itemType)), ($, from, to, drafts) => {
         const result = $.let(East.value(some([]), OptionType(ArrayType(itemType))), OptionType(ArrayType(itemType)));
         if (optional) {
-            const inPlace = $.const(withDrafts);
+            const inPlace = $.const(reads.withDrafts);
             const item = $.const(itemFn);
-            const accepts = filter === undefined ? undefined : $.const(filter);
             let read;
-            if (readBacklog === undefined) {
+            if (reads.backlog === undefined) {
                 read = $.let(East.value(some(readAll()), OptionType(HeldType)));
             }
             else {
-                const backlog = $.const(readBacklog);
-                read = $.let(backlog());
+                const backlog = $.const(reads.backlog);
+                read = $.let(backlog(from, to));
             }
             $.assign(result, East.value(none, OptionType(ArrayType(itemType))));
             $.match(read, {
                 some: ($2, rows) => {
                     const out = $2.let([], ArrayType(itemType));
-                    $2.for(inPlace(rows, drafts), ($3, entry, _i, label) => {
-                        if (accepts !== undefined)
-                            $3.if(accepts(entry.row, entry.key).not(), $4 => { $4.continue(label); });
+                    $2.for(inPlace(rows, drafts), ($3, entry) => {
                         const one = $3.const(item(entry));
                         $3.if(one.start.hasTag("none"), ($4) => { $4(out.pushLast(one)); });
                     });
@@ -551,7 +622,7 @@ export function scheduleEvents(record, input) {
         }
         return result;
     });
-    const readEvent = (makeItem, readType) => East.function([StringType, ScheduleDraftsType, DateTimeType, DateTimeType], OptionType(readType), ($, id, drafts, from, to) => {
+    const readEvent = (makeItem, readType, reads) => East.function([StringType, ScheduleDraftsType, DateTimeType, DateTimeType], OptionType(readType), ($, id, drafts, from, to) => {
         const parse = $.const(keyOf);
         const make = $.const(makeItem);
         const key = $.const(parse(id));
@@ -567,17 +638,17 @@ export function scheduleEvents(record, input) {
             });
         });
         $.if(unread, ($2) => {
-            if (byKey === undefined || readDays === undefined) {
+            if (byKey === undefined || reads.days === undefined) {
                 const held = $2.const(readAll());
                 $2.assign(row, held.tryGet(key));
                 return;
             }
-            const days = $2.const(readDays);
+            const days = $2.const(reads.days);
             $2.match(days(from, to), { some: ($3, held) => { $3.assign(row, held.tryGet(key)); } });
-            if (readBacklog !== undefined) {
-                const backlog = $2.const(readBacklog);
+            if (reads.backlog !== undefined) {
+                const backlog = $2.const(reads.backlog);
                 $2.if(row.hasTag("none"), ($3) => {
-                    $3.match(backlog(), { some: ($4, held) => { $4.assign(row, held.tryGet(key)); } });
+                    $3.match(backlog(from, to), { some: ($4, held) => { $4.assign(row, held.tryGet(key)); } });
                 });
             }
             const find = $2.const(byKey);
@@ -590,8 +661,12 @@ export function scheduleEvents(record, input) {
             none: (_$2) => East.value(none, OptionType(readType)),
         });
     });
-    /** The Calendar's kind, part by part, under its slot — and the function that makes one of its events. */
-    const kindParts = (slot) => {
+    /**
+     * The Calendar's kind, part by part, under its slot and through its source's part, its form `form` — and the
+     * function that makes one of its events.
+     */
+    const kindParts = (slot, part, form) => {
+        const reads = readsOf(slot, part);
         // One event, as every view draws it.
         const itemOf = East.function([EntryRowType], ScheduleItemType, ($, entry) => {
             const row = entry.row;
@@ -626,7 +701,8 @@ export function scheduleEvents(record, input) {
             return East.value({
                 kind: slot,
                 key: entry.id,
-                title: fieldOf(row, config.title),
+                // A kind with no title titles its events with nothing (#1367): the Calendar and Plan refuse one.
+                title: titleField === undefined ? "" : fieldOf(row, titleField),
                 start,
                 end,
                 resource: ref(row),
@@ -635,8 +711,8 @@ export function scheduleEvents(record, input) {
                 due,
             }, ScheduleItemType);
         });
-        const items = windowOf(ScheduleItemType, itemOf);
-        const unscheduled = backlogOf(ScheduleItemType, itemOf);
+        const items = windowOf(ScheduleItemType, itemOf, reads);
+        const unscheduled = backlogOf(ScheduleItemType, itemOf, reads);
         // Each template's values, by key, as the templates on the wire carry them.
         const templateRows = boundTemplates ?? East.value(templates.map((t) => ({
             key: t.key, name: t.name, group: t.group === undefined ? none : some(t.group),
@@ -714,61 +790,9 @@ export function scheduleEvents(record, input) {
                 });
             });
         })();
-        // The shared session over the record: whole-entry drafts, keyed batches, Save through the patch door.
-        // Its base is the record's snapshot — or, for a kind read a window at a time (#1199), its revision,
-        // every entry it reads read by key through the record's own entries.
-        const batchType = EditingChangeSetTypeFor(rowType, keyType);
-        const encodedEntry = (row) => East.value(some(East.Blob.encodeBeast(row, "v2")), OptionType(BlobType));
-        const readEntry = byKey === undefined
-            ? East.function([StringType, IntegerType], OptionType(BlobType), ($, id, _offset) => {
-                const parse = $.const(keyOf);
-                const held = $.const(readAll());
-                return held.tryGet(parse(id)).match({
-                    some: (_$2, row) => encodedEntry(row),
-                    none: (_$2) => East.value(none, OptionType(BlobType)),
-                });
-            })
-            : East.function([StringType, IntegerType], OptionType(BlobType), ($, id, _offset) => {
-                const find = $.const(byKey);
-                const result = $.let(none, OptionType(BlobType));
-                $.match(find(id), { held: ($2, row) => { $2.assign(result, encodedEntry(row)); } });
-                return result;
-            });
-        const onApply = East.asyncFunction([BlobType], EditingApplyResultType, ($, blob) => {
-            const commit = $.const(apply);
-            return commit(blob.decodeBeast(batchType, "v2"));
-        });
-        const editing = East.value({
-            sourceId: handle["binding"].name,
-            entryType: toEastTypeValue(rowType),
-            idField: none,
-            draftType: toEastTypeValue(draftType),
-            children: none,
-            keyType: some(toEastTypeValue(keyType)),
-            snapshot: byKey === undefined ? some(East.Blob.encodeBeast(readAll(), "v2")) : none,
-            readEntry,
-            onPatch: none,
-            onApply: some(East.value(variant("async", onApply), EditingWireApplyType)),
-            mode: variant("batch", null),
-        }, EditingType);
-        // The record read by key (#1199): its revision and a move to another, one event's row, and its largest key.
-        let entriesSeam;
-        if (entries === undefined || byKey === undefined || lastKey === undefined) {
-            entriesSeam = East.value(none, OptionType(ScheduleEntriesType));
-        }
-        else {
-            const pinned = entries;
-            const entry = East.function([StringType], OptionType(OptionType(BlobType)), ($, id) => {
-                const find = $.const(byKey);
-                const result = $.let(none, OptionType(OptionType(BlobType)));
-                $.match(find(id), {
-                    held: ($2, row) => { $2.assign(result, some(encodedEntry(row))); },
-                    absent: ($2) => { $2.assign(result, some(none)); },
-                });
-                return result;
-            });
-            entriesSeam = East.value(some({ revision: pinned.revision, refresh: pinned.refresh, entry, last: lastKey }), OptionType(ScheduleEntriesType));
-        }
+        // The shared session over the record (`session.ts`): whole-entry drafts, keyed batches, Save through the
+        // patch door; its base the record's snapshot, or for a kind read a window at a time (#1199) its revision.
+        const { editing, entries: entriesSeam } = session.build();
         const fieldsOfKind = {
             key: slot,
             name: config.name,
@@ -777,22 +801,76 @@ export function scheduleEvents(record, input) {
             status: statusTable === undefined || statusCases === undefined ? [] : statusCases.map((c) => ({ case: c, status: fieldOf(statusTable, c) })),
             backlog: optional,
             templates: templateRows,
-            fields: East.value(formSpecs, ArrayType(FieldSpecType)),
+            templatesSource: templatesSource === undefined ? none : some(templatesSource),
+            fields: East.value(form, ArrayType(FieldSpecType)),
             items,
             unscheduled,
             write,
             ready: ready === undefined ? none : some(ready),
             editing,
             entries: entriesSeam,
-            history: handle["history"],
-            event: readEvent(itemOf, ScheduleReadType),
-            schedule: { title: config.title, start: startField, end: endField,
+            history: session.history,
+            event: readEvent(itemOf, ScheduleReadType, reads),
+            // A kind with no title names none: the Calendar and Plan, whose inspectors draw it, refuse one.
+            schedule: { title: titleField ?? "", start: startField, end: endField,
                 resource: resource === undefined ? none : some(resource.field),
                 status: config.status === undefined ? none : some(config.status.field) },
             overlaps: variant(overlaps, null),
             inspector: inspector === undefined ? none : some(inspector),
         };
-        return { fields: fieldsOfKind, itemOf };
+        return { fields: fieldsOfKind, itemOf, reads };
+    };
+    // ── The builders over the app's own records (#1367) ─────────────────────
+    /**
+     * The stored rows overlapping `[from, to)`, by their key's text: each its roles, read by `rolesOf` in the pass that
+     * reads the row, and the row as bytes — through the kind's reads (its source's part, its day index, or the record
+     * whole), `none` while a read is in flight. Overlap is the views' rule: a row starts before the window ends and
+     * ends after it starts, or, of no length, sits inside it. The builder puts its drafts in place itself (`Builder
+     * Interfaces Spec.md` §9). The times are plain DateTime fields: both builds refuse Option times.
+     */
+    const storedRows = (reads, EntryType, rolesOf) => {
+        const RowsType = OptionType(DictType(StringType, EntryType));
+        return East.function([DateTimeType, DateTimeType], RowsType, ($, from, to) => {
+            const text = $.const(idOf);
+            const roles = $.const(rolesOf);
+            const result = $.let(East.value(none, RowsType), RowsType);
+            let read;
+            if (reads.days === undefined) {
+                read = $.let(East.value(some(readAll()), OptionType(HeldType)));
+            }
+            else {
+                const days = $.const(reads.days);
+                read = $.let(days(from, to));
+            }
+            $.match(read, {
+                some: ($2, held) => {
+                    const out = $2.let(new Map(), DictType(StringType, EntryType));
+                    $2.for(held, ($3, row, key) => {
+                        const start = $3.const(fieldOf(row, startField));
+                        const end = $3.const(fieldOf(row, endField));
+                        $3.if(East.less(start, to).and(() => East.greater(end, from).or(() => East.greaterEqual(start, from))), ($4) => {
+                            const id = $4.const(text(key));
+                            $4(out.insert(id, East.value({ roles: roles(row, id), row: East.Blob.encodeBeast(row, "v2") }, EntryType)));
+                        });
+                    });
+                    $2.assign(result, East.value(some(out), RowsType));
+                },
+            });
+            return result;
+        });
+    };
+    /** Refuses two of a builder's roles naming one field: a builder writes each of its roles into a field of its own (B1). */
+    const oneFieldEach = (builder, named) => {
+        const seen = new Map();
+        for (const [prop, name] of named) {
+            if (name === undefined)
+                continue;
+            const prior = seen.get(name);
+            if (prior !== undefined) {
+                throw new Error(`${where}: \`${prior}\` and \`${prop}\` both name "${name}" — the ${builder} writes each of its roles into a field of its own`);
+            }
+            seen.set(name, prop);
+        }
     };
     return {
         [SCHEDULE_DEF]: "events",
@@ -800,13 +878,195 @@ export function scheduleEvents(record, input) {
         rowType,
         name: config.name,
         icon: config.icon,
+        title: titleField,
         takes,
         draw: draw,
-        build(slot) {
-            return East.value(kindParts(slot).fields, ScheduleKindType);
+        templatesSource,
+        templatesList: config.templates === undefined ? "none" : SCHEDULE_TEMPLATES in config.templates ? "record" : "code",
+        roles: [...rosterGiven, ...allocationGiven],
+        partsOf: config.parts?.of,
+        allocationValues,
+        build(slot, part) {
+            return East.value(kindParts(slot, part, formSpecs).fields, ScheduleKindType);
+        },
+        buildRoster(slot, part) {
+            // A duty runs from its start to its end, keyed by String, on its slot's shift and group, rostered to someone.
+            if (instantKind) {
+                throw new Error(`${where}: the Roster reads a duty's \`start\` and \`end\`; this kind is one instant (\`at\`) — give \`start\` and \`end\` in its place`);
+            }
+            if (optional)
+                throw new Error(`${where}: a duty has its times — \`start\` and \`end\` are DateTime fields, not Options`);
+            if (keyType.type !== "String") {
+                throw new Error(`${where}: the Roster's duties are keyed by String — a duty is named by its key, and this record is keyed by ${printType(keyType)}`);
+            }
+            if (shiftField === undefined || groupField === undefined) {
+                throw new Error(`${where}: the Roster places a duty by its \`shift\` and its \`group\` — give both`);
+            }
+            if (resource === undefined || resourceValue === undefined) {
+                throw new Error(`${where}: the Roster rosters each duty to a person or an agency, its \`resource\` — give it, resource: { field, of: "people" }`);
+            }
+            oneFieldEach("Roster", [["start", startField], ["end", endField], ["resource.field", resource.field], ["shift", shiftField],
+                ["group", groupField], ["position", positionField], ["activity", activityField]]);
+            const shift = shiftField;
+            const group = groupField;
+            const who = resource.field;
+            const whoOf = resourceValue;
+            const parts = kindParts(slot, part, formOver([startField, endField, who, shift, group, positionField, activityField]));
+            const Roles = ScheduleRosterRolesType;
+            // A row with the Roster's roles written from `roles`, the resource field from `value`, and every other field
+            // from `source`: the row as it was, or a new row's defaults. A kind with no `position` writes none.
+            const rosterRow = (source, roles, value) => East.value(Object.fromEntries(Object.keys(fields).map((f) => [f,
+                f === startField ? roles.start
+                    : f === endField ? roles.end
+                        : f === who ? value
+                            : f === shift ? roles.shift
+                                : f === group ? roles.group
+                                    : f === positionField ? roles.position.match({ some: (_$, held) => held, none: () => fieldOf(source, f) })
+                                        : f === activityField ? roles.activity
+                                            : fieldOf(source, f)])), rowType);
+            // A duty's roles, from its row and its key: its times and who, its shift and group, its position and
+            // activity, and the hours it counts.
+            const rolesOf = East.function([rowType, StringType], Roles, ($, row, key) => {
+                const ref = $.const(refOf);
+                const start = $.const(fieldOf(row, startField));
+                const end = $.const(fieldOf(row, endField));
+                let hours;
+                if (hoursOf === undefined) {
+                    // Its length.
+                    hours = $.const(start.durationMinutes(end).divide(60.0));
+                }
+                else {
+                    const count = $.const(hoursOf);
+                    hours = $.const(count(row, key));
+                }
+                return East.value({
+                    start, end, resource: ref(row), shift: fieldOf(row, shift), group: fieldOf(row, group),
+                    position: positionField === undefined ? none : some(fieldOf(row, positionField)),
+                    activity: activityField === undefined ? none : fieldOf(row, activityField),
+                    hours,
+                }, Roles);
+            });
+            // A drafted duty's roles, from its bytes: what `rows` gives a stored one in the pass that reads it.
+            const read = East.function([BlobType, StringType], Roles, ($, bytes, key) => {
+                const of = $.const(rolesOf);
+                return of(bytes.decodeBeast(rowType, "v2"), key);
+            });
+            // The row with its roles written, and every other field as it was (B1); `none` for a resource the kind refuses.
+            const write = East.function([BlobType, Roles], OptionType(BlobType), ($, bytes, roles) => {
+                const row = $.const(bytes.decodeBeast(rowType, "v2"));
+                const resolve = $.const(whoOf);
+                const result = $.let(East.value(none, OptionType(BlobType)), OptionType(BlobType));
+                $.match(resolve(roles.resource), {
+                    some: ($2, value) => { $2.assign(result, East.value(some(East.Blob.encodeBeast(rosterRow(row, roles, value), "v2")), OptionType(BlobType))); },
+                });
+                return result;
+            });
+            // A new duty: its roles written, and every other field its type's default.
+            const blank = East.value(defaultValue(rowType), rowType);
+            const create = East.function([Roles], OptionType(BlobType), ($, roles) => {
+                const row = $.const(blank);
+                const resolve = $.const(whoOf);
+                const result = $.let(East.value(none, OptionType(BlobType)), OptionType(BlobType));
+                $.match(resolve(roles.resource), {
+                    some: ($2, value) => { $2.assign(result, East.value(some(East.Blob.encodeBeast(rosterRow(row, roles, value), "v2")), OptionType(BlobType))); },
+                });
+                return result;
+            });
+            return East.value({
+                kind: East.value(parts.fields, ScheduleKindType),
+                rows: storedRows(parts.reads, ScheduleRosterEntryType, rolesOf),
+                read,
+                write,
+                create,
+                roles: { position: positionField !== undefined, activity: activityField !== undefined },
+                rowType: toEastTypeValue(rowType),
+            }, ScheduleRosterKindType);
+        },
+        buildAllocation(slot, part) {
+            // A bin is one instant, keyed by String, in one lane, booking an arrival, its quantity on its parts for its hold.
+            if (!instantKind) {
+                throw new Error(`${where}: the Allocation's bins are an instant kind: give \`at\` in place of \`start\` and \`end\``);
+            }
+            if (keyType.type !== "String") {
+                throw new Error(`${where}: the Allocation's bins are keyed by String — a bin is named by its key, and this record is keyed by ${printType(keyType)}`);
+            }
+            if (resource === undefined)
+                throw new Error(`${where}: the Allocation books a bin into a lane, its \`resource\` — give it`);
+            if (resource.shape !== "key" || resource.optional) {
+                throw new Error(`${where}: the Allocation books each bin into one lane — \`resource\` names a String field, a key of the lanes' kind, ` +
+                    `and "${resource.field}" holds ${typeText(fields[resource.field])}`);
+            }
+            if (arrivalField === undefined)
+                throw new Error(`${where}: the Allocation books a bin's \`arrival\` — give it`);
+            if (quantityField === undefined)
+                throw new Error(`${where}: the Allocation reads a bin's \`quantity\` — give it`);
+            if (partsField === undefined || config.parts === undefined)
+                throw new Error(`${where}: the Allocation allocates a bin's \`parts\` — give it`);
+            if (holdField === undefined)
+                throw new Error(`${where}: the Allocation holds a bin for its \`hold\` — give it`);
+            oneFieldEach("Allocation", [["at", startField], ["resource.field", resource.field], ["arrival", arrivalField], ["quantity.field", quantityField],
+                ["parts.field", partsField], ["hold", holdField], ["kind", kindField]]);
+            const lane = resource.field;
+            const arrival = arrivalField;
+            const quantity = quantityField;
+            const shares = partsField;
+            const hold = holdField;
+            // The fields no role maps (`allocationValues`): what an arrival's values give a booked bin, a reservation's their type's default.
+            const mapped = allocationMapped;
+            const ValuesType = allocationValues;
+            const parts = kindParts(slot, part, formOver([...mapped]));
+            const Roles = ScheduleAllocationRolesType;
+            // A row with the Allocation's roles written from `roles`, and every other field from `source`: the row as it
+            // was, or a booked bin's values. A kind with no `kind` writes none.
+            const binRow = (source, roles) => East.value(Object.fromEntries(Object.keys(fields).map((f) => [f,
+                f === startField ? roles.at
+                    : f === lane ? roles.lane
+                        : f === arrival ? roles.arrival
+                            : f === quantity ? roles.quantity
+                                : f === shares ? roles.parts
+                                    : f === hold ? roles.hold
+                                        : f === kindField ? roles.kind
+                                            : fieldOf(source, f)])), rowType);
+            // A bin's roles, from its row: its time and lane, the arrival it books, its quantity and parts, its hold and kind.
+            const rolesOf = East.function([rowType, StringType], Roles, (_$, row, _key) => East.value({
+                at: fieldOf(row, startField), lane: fieldOf(row, lane), arrival: fieldOf(row, arrival), quantity: fieldOf(row, quantity),
+                parts: fieldOf(row, shares), hold: fieldOf(row, hold), kind: kindField === undefined ? none : fieldOf(row, kindField),
+            }, Roles));
+            // A drafted bin's roles, from its bytes: what `rows` gives a stored one in the pass that reads it.
+            const read = East.function([BlobType], Roles, ($, bytes) => {
+                const of = $.const(rolesOf);
+                return of(bytes.decodeBeast(rowType, "v2"), "");
+            });
+            // The row with its roles written, and every other field as it was (B1).
+            const write = East.function([BlobType, Roles], BlobType, ($, bytes, roles) => {
+                const row = $.const(bytes.decodeBeast(rowType, "v2"));
+                return East.Blob.encodeBeast(binRow(row, roles), "v2");
+            });
+            // A new bin: its roles written, and every other field the arrival's values' — or, with none, its type's default (B13).
+            const blank = East.value(defaultValue(ValuesType), ValuesType);
+            const create = East.function([Roles, OptionType(BlobType)], BlobType, ($, roles, values) => {
+                const given = $.const(values.match({
+                    some: (_$2, bytes) => bytes.decodeBeast(ValuesType, "v2"),
+                    none: (_$2) => blank,
+                }));
+                return East.Blob.encodeBeast(binRow(given, roles), "v2");
+            });
+            return East.value({
+                kind: East.value(parts.fields, ScheduleKindType),
+                rows: storedRows(parts.reads, ScheduleAllocationEntryType, rolesOf),
+                read,
+                write,
+                create,
+                lanes: resource.of,
+                parts: config.parts.of,
+                kinded: kindField !== undefined,
+                unit: config.quantity?.unit === undefined ? none : some(config.quantity.unit),
+                values: toEastTypeValue(ValuesType),
+                rowType: toEastTypeValue(rowType),
+            }, ScheduleAllocationKindType);
         },
-        buildPlan(slot) {
-            const parts = kindParts(slot);
+        buildPlan(slot, part) {
+            const parts = kindParts(slot, part, formSpecs);
             const quantity = config.quantity;
             const format = quantity?.format === undefined ? undefined : East.value(quantity.format, TickFormatType);
             // One event as Plan draws it: what every view draws, with its roles read from their fields.
@@ -832,7 +1092,7 @@ export function scheduleEvents(record, input) {
             // is the record's: read whole, or for a kind read a window at a time (#1199) looked for first among the
             // rows its windows hold over [from, to) and its backlog's, where a gesture's event is drawn, then read
             // by its key.
-            const planEvent = readEvent(planItemOf, PlanEventReadType);
+            const planEvent = readEvent(planItemOf, PlanEventReadType, parts.reads);
             const name = (field) => (field === undefined ? none : some(field));
             return East.value({
                 ...parts.fields,
@@ -840,8 +1100,8 @@ export function scheduleEvents(record, input) {
                 instant: instantKind,
                 overlaps: variant(overlaps, null),
                 roles: { state: name(stateField), quantity: name(quantityField), lane: name(laneField) },
-                planItems: windowOf(PlanEventItemType, planItemOf),
-                planUnscheduled: backlogOf(PlanEventItemType, planItemOf),
+                planItems: windowOf(PlanEventItemType, planItemOf, parts.reads),
+                planUnscheduled: backlogOf(PlanEventItemType, planItemOf, parts.reads),
                 planEvent,
                 inspector: inspector === undefined ? East.value(none, OptionType(RowInspectorType)) : East.value(some(inspector), OptionType(RowInspectorType)),
             }, PlanEventKindType);