@elaraai/east-ui 1.0.80 → 1.0.82

package/dist/src/collections/sheet/bridge.js

@@ -15,22 +15,42 @@
  * - `rowById` — the REAL source row by id: the captured collection or bind
  *   handle on the inline arm, the source's `page` at the row's offset on the
  *   paged arm. Built ONCE per sheet and shared by every wrapper;
- * - `decode` — the source row as the base (the row type's default when
- *   absent — an insert, a proposal), then each column's field from its cell
- *   by the static tag. A field with no column keeps the base row's value;
- * - `bridgeCtx` — the wire context to `Sheet.Types.Context(R, D)`;
+ * - `draftDecode` — current cells over the existing field draft, preserving
+ *   hidden values and retaining missing/invalid input without domain defaults;
+ * - `bridgeCtx` — the wire context to `Sheet.Types.DraftContext(R, D)`;
+ * - `bridgeReady` — a readiness batch to one `DraftContext` per check, its
+ *   rows built once (#882);
  * - the wrappers — a fill provider, a proposer, an arity rule, a member
- *   check, a custom kind's parse / print, `onEdit` — each the author's typed
- *   function inside its closed wire twin.
+ *   check, an options rule, a custom kind's parse / print — each the
+ *   author's typed function inside its closed wire twin;
+ * - the rule cells and sub rows (#844) — a column's `level` / `actual` /
+ *   `detail` accessors and the `subRows` mappers, each compiled once and
+ *   called inside the row projection.
+ *
+ * On a GROUPED sheet (#740) the source row is the group `P` and the columns
+ * are declared over the line `L` its lines field holds: `projectRow` /
+ * `draftRow` / the patch run over `L`, `rowById` returns the group, and the
+ * group half of the bridge ({@link SheetGroupBridge}) projects the group's
+ * summary cells and ordered children. Internal child keys preserve identity
+ * during local editing; the author's child arrays remain positional. A
+ * source with LOOSE rows between its groups (#846) holds entries
+ * `Sheet.Types.Entry(P, "lines")`: `rowById` returns the entry, a draft is
+ * the entry's draft, and a loose row decodes as a row of `L` whose id is its
+ * own.
  *
  * The bridge is the one place a string ever names a field: inside the
  * factory, against the column list it has already validated.
  *
  * @packageDocumentation
  */
-import { East, Expr, ArrayType, AsyncFunctionType, BooleanType, DateTimeType, DictType, FloatType, FunctionType, IntegerType, NullType, OptionType, StringType, StructType, defaultValue, variant, some, none, } from "@elaraai/east";
-import { SheetCellType, SheetLinkType, SheetContextType, SheetFillType, SheetProposalType, SheetProviderType, SheetProposerType, SheetCheckContextType, SheetCheckType, SheetCountedType, SheetEditType, SheetHalfType, SheetContextTypeFor, SheetCheckContextTypeFor, SheetEditTypeFor, SheetPatchTypeFor, SheetProposalTypeFor, } from "./types.js";
-import { SheetMembersType, SheetRegisterMembersType, parseLink, printLink, printLinkWith, EMPTY_LINK } from "./link.js";
+import { East, Expr, ArrayType, AsyncFunctionType, BooleanType, DateTimeType, DictType, FloatType, FunctionType, IntegerType, NullType, OptionType, StringType, StructType, isTypeEqual, variant, some, none, } from "@elaraai/east";
+import { SheetCellType, SheetLinkType, SheetRowType, SheetLineType, SheetContextType, SheetReadyBatchType, SheetFillType, SheetProposalType, SheetProviderType, SheetProposerType, SheetCheckContextType, SheetCheckType, SheetCountedType, SheetHalfType, SheetContextTypeFor, SheetCheckContextTypeFor, SheetPatchTypeFor, SheetProposalTypeFor, SheetGroupContextTypeFor, SheetGroupCheckContextTypeFor, SheetDateLevelType, SheetSubRowType, SheetOptionsRuleType, sheetLinesOf, sheetRuleCell, } from "./types.js";
+import { resolveTag } from "../plan/builders.js";
+import { SheetMembersType, SheetRegisterMembersType, parseLink, EMPTY_LINK } from "./link.js";
+import { buildDraftRowDecoder, buildDraftGroupDecoder, buildDraftEntryDecoder } from "./draft-bridge.js";
+import { buildDraftContextBridge, buildDraftBase, buildReadyContexts } from "./context-bridge.js";
+import { SheetDraftEntryTypeFor, SheetDraftGroupTypeFor } from "./drafts.js";
+import { SheetDraftTypeFor } from "./transactions.js";
 /** The wire cells dictionary type. */
 export const SheetCellsType = DictType(StringType, SheetCellType);
 /** The East type of an erased expression (`Expr.type` cannot infer through `ExprType<EastType>`). */
@@ -51,7 +71,7 @@ export function optionPayload(t) {
 }
 /** The cell arm a primitive payload lands in, or `undefined` for a type no cell holds. */
 export function cellTagOf(t) {
-    if (t === SheetLinkType)
+    if (isTypeEqual(t, SheetLinkType))
         return "Link";
     switch (t.type) {
         case "String": return "String";
@@ -66,6 +86,45 @@ const SCALAR_PAYLOAD = {
     text: StringType, lookup: StringType, reference: StringType, enum: StringType, stamped: StringType,
     date: DateTimeType, quantity: FloatType, integer: IntegerType,
 };
+/** Compile one rule accessor and check its payload — `String` or `DateTime`, or its Option. */
+function ruleCell(key, rule, rowType, accessor, tag) {
+    const fn = East.function([rowType], undefined, (_$, r) => accessor(r));
+    const out = Expr.type(fn).output;
+    const payload = optionPayload(out);
+    const unwrapped = payload ?? out;
+    if (cellTagOf(unwrapped) !== tag) {
+        throw new Error(`Sheet: column "${key}" has a \`${rule}\` rule returning ${describeType(out)} — it must return ${tag} or Option<${tag}>`);
+    }
+    return { key: sheetRuleCell(rule, key), fn, tag, optional: payload !== undefined };
+}
+/**
+ * The unrendered cells a column's rules project (#844) — `detail` on any
+ * column, `level` and `actual` on a date column.
+ */
+function ruleCellsOf(key, kind, cfg, rowType) {
+    const out = [];
+    if (cfg.detail !== undefined)
+        out.push(ruleCell(key, "detail", rowType, cfg.detail, "String"));
+    if (kind !== "date") {
+        if (cfg.level !== undefined || cfg.actual !== undefined) {
+            throw new Error(`Sheet: column "${key}" is a ${kind} column — \`level\` and \`actual\` are date-column rules`);
+        }
+        return out;
+    }
+    if (cfg.level !== undefined) {
+        const level = cfg.level;
+        const fn = East.function([rowType], StringType, (_$, r) => resolveTag(level(r), SheetDateLevelType).match({
+            week: (_$2) => "week",
+            day: (_$2) => "day",
+            range: (_$2) => "range",
+            time: (_$2) => "time",
+        }));
+        out.push({ key: sheetRuleCell("level", key), fn, tag: "String", optional: false });
+    }
+    if (cfg.actual !== undefined)
+        out.push(ruleCell(key, "actual", rowType, cfg.actual, "DateTime"));
+    return out;
+}
 /**
  * Describe one column against the row type — the build-time refusals of
  * §3.12 live here, every one naming the column and the remedy.
@@ -77,6 +136,15 @@ const SCALAR_PAYLOAD = {
  * @throws Error naming the column when the kind cannot sit on the field
  */
 export function describeColumn(key, col, rowType) {
+    const meta = describeKind(key, col, rowType);
+    const ruleCells = ruleCellsOf(key, col.kind, col.config, rowType);
+    if (col.config.options !== undefined && col.kind !== "enum" && col.kind !== "lookup" && col.kind !== "link") {
+        throw new Error(`Sheet: column "${key}" is a ${col.kind} column — an \`options\` rule narrows an enum, lookup or link column's members`);
+    }
+    return ruleCells.length > 0 ? { ...meta, ruleCells } : meta;
+}
+/** {@link describeColumn}'s kind-by-kind half. */
+function describeKind(key, col, rowType) {
     const fields = rowType.fields;
     const fieldType = fields[key];
     if (fieldType === undefined) {
@@ -94,11 +162,11 @@ export function describeColumn(key, col, rowType) {
         const out = Expr.type(derived).output;
         const outPayload = optionPayload(out);
         const outUnwrapped = outPayload ?? out;
-        if (outUnwrapped !== payloadType) {
+        if (!isTypeEqual(outUnwrapped, payloadType)) {
             throw new Error(`Sheet: column "${key}" is a ${kind} column whose \`value\` projection returns ${outUnwrapped.type} — a ${kind} column's projection must return ${payloadType.type} or its Option`);
         }
         return {
-            key, kind, config: cfg, fieldType, optional, payloadType,
+            key, field: key, kind, config: cfg, fieldType, optional, payloadType,
             cellTag: cellTagOf(payloadType), editable: false,
             derived, derivedOptional: outPayload !== undefined,
             ...(col.register !== undefined ? { register: col.register } : {}),
@@ -109,10 +177,10 @@ export function describeColumn(key, col, rowType) {
         let form;
         let ownHalf;
         let otherField;
-        if (fieldType === SheetLinkType || unwrapped === SheetLinkType) {
+        if (isTypeEqual(fieldType, SheetLinkType) || isTypeEqual(unwrapped, SheetLinkType)) {
             form = "link";
         }
-        else if (fieldType === SheetMembersType) {
+        else if (isTypeEqual(fieldType, SheetMembersType)) {
             form = "array";
             if (kind === "set") {
                 ownHalf = "to";
@@ -128,7 +196,8 @@ export function describeColumn(key, col, rowType) {
             else {
                 throw new Error(`Sheet: link column "${key}" sits on an Array<Member> field, so it must name the OTHER half's field — \`to: "…"\` when this field holds the from members, \`from: "…"\` when it holds the to members`);
             }
-            if (otherField !== undefined && fields[otherField] !== SheetMembersType) {
+            const otherType = otherField !== undefined ? fields[otherField] : undefined;
+            if (otherField !== undefined && (otherType === undefined || !isTypeEqual(otherType, SheetMembersType))) {
                 throw new Error(`Sheet: link column "${key}" names "${otherField}" as its other half, but that is not an Array<Sheet.Types.Member> field of the row`);
             }
         }
@@ -139,7 +208,7 @@ export function describeColumn(key, col, rowType) {
             throw new Error(`Sheet: ${kind} column "${key}" must sit on a Sheet.Types.Link, Array<Sheet.Types.Member> or String field — got ${fieldType.type}`);
         }
         return {
-            key, kind, config: cfg, fieldType, optional: form === "link" ? unwrapped === SheetLinkType && optional : optional,
+            key, field: key, kind, config: cfg, fieldType, optional: form === "link" ? isTypeEqual(unwrapped, SheetLinkType) && optional : optional,
             payloadType: SheetLinkType, cellTag: "Link", editable: cfg.editable !== false,
             form,
             ...(ownHalf !== undefined ? { ownHalf } : {}),
@@ -155,27 +224,50 @@ export function describeColumn(key, col, rowType) {
         if (parsed === undefined) {
             throw new Error(`Sheet: custom column "${key}" has a \`parse\` whose output is not an Option — it must return Option<payload>, \`none\` meaning unrecognised`);
         }
-        if (parsed !== unwrapped) {
+        if (!isTypeEqual(parsed, unwrapped)) {
             throw new Error(`Sheet: custom column "${key}" parses to ${parsed.type} but sits on a ${unwrapped.type} field — the payload must be the field's type (or its Option's)`);
         }
         const tag = cellTagOf(parsed);
         if (tag === undefined) {
             throw new Error(`Sheet: custom column "${key}" has payload ${parsed.type}, which no cell holds — use String, Integer, Float, DateTime, Boolean or Sheet.Types.Link`);
         }
-        return { key, kind, config: cfg, fieldType, optional, payloadType: parsed, cellTag: tag, editable: cfg.editable !== false };
+        return { key, field: key, kind, config: cfg, fieldType, optional, payloadType: parsed, cellTag: tag, editable: cfg.editable !== false };
     }
     const payloadType = SCALAR_PAYLOAD[kind];
-    if (unwrapped !== payloadType) {
+    if (!isTypeEqual(unwrapped, payloadType)) {
         throw new Error(`Sheet: ${kind} column "${key}" must sit on a ${payloadType.type} or Option<${payloadType.type}> field — got ${fieldType.type}`);
     }
     return {
-        key, kind, config: cfg, fieldType, optional, payloadType,
+        key, field: key, kind, config: cfg, fieldType, optional, payloadType,
         cellTag: cellTagOf(payloadType),
         editable: kind !== "stamped" && cfg.editable !== false,
         ...(col.register !== undefined ? { register: col.register } : {}),
         ...(col.driverType !== undefined ? { driverType: col.driverType } : {}),
     };
 }
+/**
+ * Describe one band cell against the GROUP's row type (#740) — a column
+ * declared over the group's field, keyed by the line column it sits under.
+ *
+ * @param cellKey - The line column the cell sits under, or `$title`
+ * @param cell - The built band cell
+ * @param groupType - The group's row type
+ * @returns The cell's metadata
+ * @throws Error naming the band cell when the kind cannot sit on the field, or is not a band kind
+ */
+export function describeGroupCell(cellKey, cell, groupType) {
+    if (cell.kind === "lookup" || cell.kind === "set" || cell.kind === "link" || cell.kind === "custom") {
+        throw new Error(`Sheet: band cell "${cellKey}" is a ${cell.kind} cell — a band draws text, date, quantity, integer, reference, enum and stamped cells only`);
+    }
+    let meta;
+    try {
+        meta = describeColumn(cell.field, { kind: cell.kind, config: cell.config, ...(cell.register !== undefined ? { register: cell.register } : {}) }, groupType);
+    }
+    catch (e) {
+        throw new Error(`Sheet: band cell "${cellKey}" — ${e.message.replace(/^Sheet: /, "")}`);
+    }
+    return { ...meta, key: cellKey, field: cell.field };
+}
 // ============================================================================
 // Cells — payload ↔ cell (the static-tag moves)
 // ============================================================================
@@ -186,11 +278,11 @@ export function cellOfPayload(tag, v) {
 /** The blank cell. */
 export const NULL_CELL = East.value(variant("Null", null), SheetCellType);
 /** A field VALUE (the payload or its Option) as a cell, by the column's static shape. */
-function cellOfFieldValue(meta, v, optional) {
+function cellOfFieldValue(tag, v, optional) {
     if (!optional)
-        return cellOfPayload(meta.cellTag, v);
+        return cellOfPayload(tag, v);
     return v.match({
-        some: (_$, x) => cellOfPayload(meta.cellTag, x),
+        some: (_$, x) => cellOfPayload(tag, x),
         none: (_$) => NULL_CELL,
     });
 }
@@ -202,13 +294,13 @@ function cellOfFieldValue(meta, v, optional) {
 function projectCell(meta, r, members) {
     const row = r;
     if (meta.derived !== undefined) {
-        return cellOfFieldValue(meta, meta.derived(r), meta.derivedOptional === true);
+        return cellOfFieldValue(meta.cellTag, meta.derived(r), meta.derivedOptional === true);
     }
-    const fv = row[meta.key];
+    const fv = row[meta.field];
     if (meta.form === undefined)
-        return cellOfFieldValue(meta, fv, meta.optional);
+        return cellOfFieldValue(meta.cellTag, fv, meta.optional);
     if (meta.form === "link")
-        return cellOfFieldValue(meta, fv, meta.optional);
+        return cellOfFieldValue(meta.cellTag, fv, meta.optional);
     if (meta.form === "array") {
         const half = fv;
         const empty = East.value([], SheetMembersType);
@@ -227,54 +319,19 @@ function projectCell(meta, r, members) {
         none: (_$) => NULL_CELL,
     });
 }
-/** The field value a cell decodes to — the payload or its Option, by the column's static shape. */
-function fieldValueOfCell(meta, cell, optional, payloadType) {
-    if (optional) {
-        return cell.match({ [meta.cellTag]: (_$, v) => East.value(some(v), OptionType(payloadType)) }, (_$) => East.value(none, OptionType(payloadType)));
-    }
-    return cell.match({ [meta.cellTag]: (_$, v) => v }, (_$) => East.value(defaultValue(payloadType), payloadType));
-}
 /**
- * The value of THIS column's field from its cell (the base field when the cell
- * is absent or the column is read-only). `members` is the column's register,
- * bound in the caller's block, for the String link form's canonical print.
+ * The id of a row — the id field; on a source with loose rows (#846) the id
+ * field of whichever arm the entry holds.
  */
-function decodeOwnField(meta, cellOpt, base, members) {
-    if (!meta.editable)
-        return base;
-    // The String form prints the link back through the grammar — the keys as
-    // typed, or the register's labels under `store: "canonical"` (B§4.2).
-    const print = (l) => meta.config.store === "canonical" && members !== undefined ? printLinkWith(l, members) : printLink(l);
-    return cellOpt.match({
-        none: (_$) => base,
-        some: (_$, cell) => {
-            if (meta.form === undefined)
-                return fieldValueOfCell(meta, cell, meta.optional, meta.payloadType);
-            if (meta.form === "link")
-                return fieldValueOfCell(meta, cell, meta.optional, SheetLinkType);
-            if (meta.form === "array") {
-                return cell.match({ Link: (_$2, l) => meta.ownHalf === "from" ? l.from : l.to }, (_$2) => East.value([], SheetMembersType));
-            }
-            if (meta.optional) {
-                return cell.match({ Link: (_$2, l) => East.value(some(print(l)), OptionType(StringType)) }, (_$2) => East.value(none, OptionType(StringType)));
-            }
-            return cell.match({ Link: (_$2, l) => print(l) }, (_$2) => East.value("", StringType));
-        },
-    });
-}
-/** The OTHER half's field of an `array`-form link column, from that column's cell. */
-function decodeOtherHalf(meta, cellOpt, base) {
-    if (!meta.editable)
-        return base;
-    return cellOpt.match({
-        none: (_$) => base,
-        some: (_$, cell) => cell.match({ Link: (_$2, l) => meta.ownHalf === "from" ? l.to : l.from }, (_$2) => East.value([], SheetMembersType)),
-    });
-}
-/** The id of a row — the id field, or the key of a keyed window. */
 function idOf(r, idField) {
     if (idField === undefined)
         throw new Error("Sheet: a positional source needs `id` — the String field that identifies a row");
+    if (Expr.type(r).type === "Variant") {
+        return r.match({
+            group: (_$, g) => g[idField],
+            row: (_$, l) => l[idField],
+        });
+    }
     return r[idField];
 }
 /**
@@ -284,23 +341,28 @@ function idOf(r, idField) {
  * @returns The bridge
  */
 export function buildBridge(input) {
-    const { rowType, idField, metas, registers, driver, source } = input;
+    const { rowType, idField, metas, registers, driver, source, group: groupInput, subRows } = input;
     const driverType = driver !== undefined ? driver.rowType : NullType;
-    const ctxType = SheetContextTypeFor(rowType, driverType);
-    const checkCtxType = SheetCheckContextTypeFor(rowType);
-    const editType = SheetEditTypeFor(rowType);
-    const patchType = SheetPatchTypeFor(rowType);
-    const proposalType = SheetProposalTypeFor(rowType);
-    const fields = rowType.fields;
-    const byField = new Map(metas.map((m) => [m.key, m]));
-    const otherHalfBy = new Map();
-    for (const m of metas)
-        if (m.otherField !== undefined)
-            otherHalfBy.set(m.otherField, m);
-    // R → the wire cells. Registers are bound ONCE per body for the String
+    // A grouped sheet's columns are declared over the LINE type; its source
+    // rows are groups — or, with loose rows between them (#846), entries of a
+    // group or a row of the line type. A flat sheet's line type is its row type.
+    const loose = rowType.type === "Variant";
+    const groupType = loose ? rowType.cases.group : rowType;
+    const shape = groupInput !== undefined ? sheetLinesOf(groupType, groupInput.linesField) : undefined;
+    const lineType = shape?.lineType ?? groupType;
+    const lineIdField = shape === undefined ? idField : undefined;
+    const ctxType = (groupInput !== undefined
+        ? SheetGroupContextTypeFor(groupType, groupInput.linesField, driverType)
+        : SheetContextTypeFor(lineType, driverType));
+    const checkCtxType = (groupInput !== undefined
+        ? SheetGroupCheckContextTypeFor(groupType, groupInput.linesField)
+        : SheetCheckContextTypeFor(lineType));
+    const patchType = SheetPatchTypeFor(lineType);
+    const proposalType = SheetProposalTypeFor(lineType);
+    // L → the wire cells. Registers are bound ONCE per body for the String
     // link form (the capture rule: data, never a spliced expression).
     const stringFormRegisters = [...new Set(metas.filter((m) => m.form === "string" && m.register !== undefined).map((m) => m.register))];
-    const projectRow = East.function([rowType], SheetCellsType, ($, r) => {
+    const projectRow = East.function([lineType], SheetCellsType, ($, r) => {
         const cells = $.let(new Map(), SheetCellsType);
         const bound = new Map();
         for (const name of stringFormRegisters) {
@@ -308,47 +370,41 @@ export function buildBridge(input) {
         }
         for (const m of metas) {
             $(cells.insert(m.key, projectCell(m, r, m.register !== undefined ? bound.get(m.register) : undefined)));
-        }
-        return cells;
-    });
-    // (id, cells, base) → R: the base row (the type's default when absent),
-    // every column's field from its cell, the id field from the wire id.
-    const decode = East.function([StringType, SheetCellsType, OptionType(rowType)], rowType, ($, id, cells, base) => {
-        const b = $.let(base.match({
-            some: (_$, x) => x,
-            none: (_$) => East.value(defaultValue(rowType), rowType),
-        }), rowType);
-        // The String link form's registers, bound once per body (the capture rule).
-        const bound = new Map();
-        for (const name of stringFormRegisters) {
-            bound.set(name, $.const(registers[name], SheetRegisterMembersType));
-        }
-        const out = {};
-        for (const f of Object.keys(fields)) {
-            const baseField = $.let(b[f], fields[f]);
-            if (f === idField) {
-                out[f] = id;
-                continue;
+            for (const rc of m.ruleCells ?? []) {
+                const rule = $.const(rc.fn);
+                $(cells.insert(rc.key, cellOfFieldValue(rc.tag, rule(r), rc.optional)));
             }
-            const own = byField.get(f);
-            if (own !== undefined) {
-                out[f] = decodeOwnField(own, cells.tryGet(own.key), baseField, own.register !== undefined ? bound.get(own.register) : undefined);
-                continue;
-            }
-            const other = otherHalfBy.get(f);
-            if (other !== undefined) {
-                out[f] = decodeOtherHalf(other, cells.tryGet(other.key), baseField);
-                continue;
-            }
-            out[f] = baseField;
         }
-        return East.value(out, rowType);
+        return cells;
     });
-    // (id, offset) → the real source row.
+    const projectSubRows = buildSubRowProjection(lineType, subRows);
+    // (id, offset) → the real source row. Inline, the row at its offset
+    // answers first — the renderer reads a resident row where it sits — and
+    // otherwise the nearest match outward from there, so a row that a local
+    // edit shifted is found in the steps it moved: a read is never a scan of
+    // the collection, which made every context and every readiness check
+    // quadratic in the rows (#859). The search starts inside the rows, so a
+    // stale offset still finds the row.
     const rowById = source.kind === "inline"
-        ? East.function([StringType, IntegerType], OptionType(rowType), ($, id, _offset) => {
+        ? East.function([StringType, IntegerType], OptionType(rowType), ($, id, offset) => {
             const rows = $.const(source.rows, ArrayType(rowType));
-            return rows.firstMap((_$, r) => idOf(r, idField).equal(id).ifElse((_$2) => East.value(some(r), OptionType(rowType)), (_$2) => East.value(none, OptionType(rowType))));
+            const size = $.let(rows.size());
+            const start = $.let(offset.less(0n).ifElse(() => 0n, () => offset.greaterEqual(size).ifElse(() => size.subtract(1n), () => offset)));
+            const step = $.let(0n);
+            $.while(start.subtract(step).greaterEqual(0n).or(() => start.add(step).less(size)), ($2) => {
+                const below = $2.let(start.subtract(step));
+                $2.if(below.greaterEqual(0n), ($3) => {
+                    const r = $3.let(rows.get(below));
+                    $3.if(idOf(r, idField).equal(id), ($4) => { $4.return(East.value(some(r), OptionType(rowType))); });
+                });
+                const above = $2.let(start.add(step));
+                $2.if(step.greater(0n).and(() => above.less(size)), ($3) => {
+                    const r = $3.let(rows.get(above));
+                    $3.if(idOf(r, idField).equal(id), ($4) => { $4.return(East.value(some(r), OptionType(rowType))); });
+                });
+                $2.assign(step, step.add(1n));
+            });
+            return East.value(none, OptionType(rowType));
         })
         : East.function([StringType, IntegerType], OptionType(rowType), ($, id, offset) => {
             const src = $.const(source.source);
@@ -368,28 +424,46 @@ export function buildBridge(input) {
             return dict.tryGet(k);
         })
         : East.function([StringType], OptionType(driverType), ($, _k) => $.const(none, OptionType(driverType)));
-    // The wire context → Sheet.Types.Context(R, D).
-    const bridgeCtx = East.function([SheetContextType], ctxType, ($, ctx) => {
-        const byId = $.const(rowById);
-        const dec = $.const(decode);
-        const row = $.let(dec(ctx.rowId, ctx.row, byId(ctx.rowId, ctx.offset)), rowType);
-        const rows = $.let(ctx.rows.map((_$, r, i) => dec(r.id, r.cells, byId(r.id, ctx.rowsOffset.add(i)))), ArrayType(rowType));
-        const lookup = $.const(lookupDriver);
-        const driverRow = $.let(ctx.driver.match({
-            none: (_$) => East.value(none, OptionType(driverType)),
-            some: (_$, k) => lookup(k),
-        }), OptionType(driverType));
-        return East.value({
-            rowIndex: ctx.rowIndex,
-            row,
-            rows,
-            partial: ctx.partial,
-            driver: driverRow,
-            today: ctx.today,
-        }, ctxType);
-    });
-    // Sheet.Types.Patch(R) → the set fields as cells.
-    const encodePatch = East.function([patchType], SheetCellsType, ($, patch) => {
+    // The drafts: a line's cells over its draft (no id — a line's identity is
+    // its place), and on a source with loose rows (#846) a loose row's, whose
+    // id field is its own.
+    const draftRow = buildDraftRowDecoder(lineType, metas, registers, lineIdField);
+    const looseRow = loose ? buildDraftRowDecoder(lineType, metas, registers, idField) : undefined;
+    const decodeGroup = groupInput !== undefined
+        ? buildDraftGroupDecoder(groupType, groupInput.linesField, groupInput.cellMetas, draftRow, registers, idField)
+        : undefined;
+    const flatDraft = SheetDraftTypeFor(groupType);
+    const draftDecode = (decodeGroup === undefined
+        ? East.function([SheetRowType, OptionType(flatDraft), OptionType(SheetRowType)], flatDraft, ($, row, base, _previous) => {
+            const decode = $.const(draftRow);
+            return decode(row.id, row.cells, base);
+        })
+        : looseRow !== undefined && groupInput !== undefined
+            ? buildDraftEntryDecoder(rowType, groupInput.linesField, decodeGroup, looseRow)
+            : decodeGroup);
+    // The group half (#740).
+    const group = groupInput !== undefined && shape !== undefined && decodeGroup !== undefined
+        ? { ...buildGroupBridge(groupType, groupInput, projectRow, projectSubRows), groupType, loose, decodeGroup, decodeLoose: looseRow }
+        : undefined;
+    const bridgeCtx = buildDraftContextBridge(rowType, lineType, groupInput?.linesField, ctxType, driverType, rowById, draftDecode, draftRow, lookupDriver, looseRow);
+    const bridgeReady = buildReadyContexts(rowType, groupInput?.linesField, ctxType, driverType, rowById, draftDecode, lookupDriver, loose);
+    const encodePatch = buildPatchCells(lineType, metas, registers);
+    return {
+        rowType, lineType, driverType, ctxType, checkCtxType, patchType, proposalType,
+        projectRow, projectSubRows, draftDecode, draftRow,
+        rowById: rowById,
+        bridgeCtx: bridgeCtx,
+        bridgeReady,
+        encodePatch, seedCells: buildPatchCells(lineType, metas, registers, false),
+        ...(group !== undefined ? { group } : {}),
+    };
+}
+/** Project supplied constructor/proposal fields without inventing a complete row. @internal */
+export function buildPatchCells(rowType, metas, registers, editableOnly = true) {
+    const patchType = SheetPatchTypeFor(rowType);
+    const fields = rowType.fields;
+    const stringFormRegisters = [...new Set(metas.filter(m => m.form === "string" && m.register !== undefined).map(m => m.register))];
+    return East.function([patchType], SheetCellsType, ($, patch) => {
         const cells = $.let(new Map(), SheetCellsType);
         const p = patch;
         const bound = new Map();
@@ -397,12 +471,12 @@ export function buildBridge(input) {
             bound.set(name, $.const(registers[name], SheetRegisterMembersType));
         }
         for (const m of metas) {
-            if (!m.editable || m.derived !== undefined)
+            if ((editableOnly && !m.editable) || m.derived !== undefined)
                 continue;
             if (m.form === "array") {
                 // The other half is `none` when the column names no other field.
                 const otherKey = m.otherField;
-                const own = $.let(p[m.key], OptionType(SheetMembersType));
+                const own = $.let(p[m.field], OptionType(SheetMembersType));
                 const other = $.let((otherKey !== undefined ? p[otherKey] : none), OptionType(SheetMembersType));
                 $.if(own.hasTag("some").or(() => other.hasTag("some")), ($2) => {
                     const empty = $2.const([], SheetMembersType);
@@ -415,21 +489,85 @@ export function buildBridge(input) {
                 });
                 continue;
             }
-            const field = $.let(p[m.key], OptionType(fields[m.key]));
+            const field = $.let(p[m.field], OptionType(fields[m.field]));
             $.if(field.hasTag("some"), ($2) => {
-                const v = $2.let(field.unwrap("some"), fields[m.key]);
-                const asRow = { [m.key]: v };
+                const v = $2.let(field.unwrap("some"), fields[m.field]);
+                const asRow = { [m.field]: v };
                 $2(cells.insert(m.key, projectCell(m, asRow, m.register !== undefined ? bound.get(m.register) : undefined)));
             });
         }
         return cells;
     });
-    return {
-        rowType, driverType, ctxType, checkCtxType, editType, patchType, proposalType,
-        projectRow, decode,
-        rowById: rowById,
-        bridgeCtx, encodePatch,
-    };
+}
+// ============================================================================
+// Sub rows (#844)
+// ============================================================================
+/**
+ * Compile the sub-row sources into one projection over the line type: each
+ * mapper is compiled ONCE as `East.function([L, T], SubRow)` and called in
+ * an eager map over its field; the sources concatenate in declaration order.
+ *
+ * @param lineType - The type the columns are built over
+ * @param subRows - The `subRows` declaration, if any
+ * @returns `L` → its sub rows
+ * @throws Error when the declaration was built over another type, or a key is not an array field
+ */
+export function buildSubRowProjection(lineType, subRows) {
+    const fields = lineType.fields;
+    const mappers = [];
+    if (subRows !== undefined) {
+        if (!isTypeEqual(subRows.rowType, lineType)) {
+            throw new Error("Sheet: `subRows` was built over a different type than the columns — pass the columns' type (a grouped sheet: the line type) to `Sheet.subRows(…)`");
+        }
+        for (const [field, map] of Object.entries(subRows.sources)) {
+            if (map === undefined)
+                continue;
+            const t = fields[field];
+            if (t === undefined || t.type !== "Array" || t.value === undefined) {
+                throw new Error(`Sheet: \`subRows\` names "${field}", which is ${t === undefined ? "not a field of the row type" : `a ${t.type} field`} — a sub-row source must be an Array field`);
+            }
+            mappers.push({ field, fn: East.function([lineType, t.value], SheetSubRowType, (_$, row, item) => map(item, row)) });
+        }
+    }
+    return East.function([lineType], ArrayType(SheetSubRowType), ($, r) => {
+        const row = r;
+        let all = $.const([], ArrayType(SheetSubRowType));
+        for (const m of mappers) {
+            const map = $.const(m.fn);
+            const part = $.let(row[m.field].map((_$2, x) => map(r, x)), ArrayType(SheetSubRowType));
+            all = mappers[0] === m ? part : $.let(all.concat(part), ArrayType(SheetSubRowType));
+        }
+        return all;
+    });
+}
+// ============================================================================
+// The group half (#740)
+// ============================================================================
+/**
+ * Compile a group's summary cells and ordered children into wire rows.
+ *
+ * @param rowType - The group's row type
+ * @param input - The child field and summary cell metadata
+ * @param projectRow - Child row to wire cells
+ * @param projectSubRows - Child row to its sub rows
+ * @returns The group half
+ */
+function buildGroupBridge(rowType, input, projectRow, projectSubRows) {
+    const { linesField, cellMetas } = input;
+    const linesType = rowType.fields[linesField];
+    const projectGroupCells = East.function([rowType], SheetCellsType, ($, p) => {
+        const cells = $.let(new Map(), SheetCellsType);
+        for (const m of cellMetas)
+            $(cells.insert(m.key, projectCell(m, p, undefined)));
+        return cells;
+    });
+    const projectLines = East.function([rowType], ArrayType(SheetLineType), ($, p) => {
+        const project = $.const(projectRow);
+        const subRowsOf = $.const(projectSubRows);
+        const lines = $.const(p[linesField], linesType);
+        return lines.map((_$, line, index) => East.value({ key: East.print(index), cells: project(line), subRows: subRowsOf(line) }, SheetLineType));
+    });
+    return { linesField, cellMetas, projectGroupCells, projectLines };
 }
 // ============================================================================
 // Wrappers — the author's typed functions inside their wire twins
@@ -446,27 +584,34 @@ function pinProvider(bridge, fn, where, expectedOutput) {
         throw new Error(`Sheet: ${where} must be an East.function or East.asyncFunction — got a ${t.type}`);
     }
     const inputs = t.inputs ?? [];
-    if (inputs.length !== 1 || inputs[0] !== bridge.ctxType) {
-        throw new Error(`Sheet: ${where} must take exactly this sheet's context — Sheet.Types.Context(RowType${bridge.driverType === NullType ? "" : ", DriverType"}) — as its one argument; a function written over another row or driver type cannot run here`);
+    if (inputs.length !== 1 || !isTypeEqual(inputs[0], bridge.ctxType)) {
+        throw new Error(`Sheet: ${where} must take exactly this sheet's context — ${contextName(bridge)} — as its one argument; a function written over another row or driver type cannot run here`);
     }
-    if (t.output !== expectedOutput) {
+    if (t.output === undefined || !isTypeEqual(t.output, expectedOutput)) {
         throw new Error(`Sheet: ${where} returns the wrong type — it must return ${describeType(expectedOutput)}`);
     }
     return { fn: expr, async: t.type === "AsyncFunction" };
 }
+/** How this sheet's context is spelt, for a refusal message. */
+function contextName(bridge) {
+    const driver = isTypeEqual(bridge.driverType, NullType) ? "" : ", DriverType";
+    return bridge.group !== undefined
+        ? `Sheet.Types.DraftContext(GroupType, "${bridge.group.linesField}"${driver})`
+        : `Sheet.Types.DraftContext(RowType${driver})`;
+}
 /** A short description of an East type for a refusal message. */
 function describeType(t) {
-    const v = t;
-    if (v.type === "Variant" && v.cases !== undefined && optionPayload(t) !== undefined)
-        return `Option<${describeType(optionPayload(t))}>`;
-    if (v.type === "Struct" && v.fields !== undefined)
-        return `{ ${Object.entries(v.fields).map(([k, f]) => `${k}: ${describeType(f)}`).join(", ")} }`;
-    if (v.type === "Array" && v.value !== undefined)
-        return `Array<${describeType(v.value)}>`;
-    return v.type;
+    const payload = optionPayload(t);
+    if (payload !== undefined)
+        return `Option<${describeType(payload)}>`;
+    if (t.type === "Struct")
+        return `{ ${Object.entries(t.fields).map(([k, f]) => `${k}: ${describeType(f)}`).join(", ")} }`;
+    if (t.type === "Array")
+        return `Array<${describeType(t.value)}>`;
+    return t.type;
 }
 /**
- * Wrap a fill provider — `Sheet.Types.Context(R, D)` → `Option<Fill(T)>` —
+ * Wrap a fill provider — `Sheet.Types.DraftContext(R, D)` → `Option<Fill(T)>` —
  * into the wire provider variant (sync or async by the function's type).
  */
 export function wrapProvider(bridge, meta, fn, index) {
@@ -487,7 +632,7 @@ export function wrapProvider(bridge, meta, fn, index) {
     return East.value(variant(async ? "async" : "sync", wire), SheetProviderType);
 }
 /**
- * Wrap a row proposer — `Sheet.Types.Context(R, D)` → `Array<Proposal(R)>` —
+ * Wrap a row proposer — `Sheet.Types.DraftContext(R, D)` → `Array<Proposal(R)>` —
  * into the wire proposer variant.
  */
 export function wrapProposer(bridge, fn, index) {
@@ -504,7 +649,7 @@ export function wrapProposer(bridge, fn, index) {
         : East.function([SheetContextType], ArrayType(SheetProposalType), body);
     return East.value(variant(async ? "async" : "sync", wire), SheetProposerType);
 }
-/** Wrap an arity rule — `Sheet.Types.Context(R, D)` → `Option<Counted>`. */
+/** Wrap an arity rule — `Sheet.Types.DraftContext(R, D)` → `Option<Counted>`. */
 export function wrapArity(bridge, meta, fn) {
     const { fn: author, async } = pinProvider(bridge, fn, `column "${meta.key}" arity rule`, OptionType(SheetCountedType));
     if (async)
@@ -515,19 +660,80 @@ export function wrapArity(bridge, meta, fn) {
         return a(bc(ctx));
     });
 }
+/**
+ * Wrap an options rule (#844) — `Sheet.Types.DraftContext(R, D)` →
+ * `Option<Array<String>>` — into the wire rule. Synchronous: the menu reads
+ * it as the cell opens.
+ */
+export function wrapOptions(bridge, meta, fn) {
+    const { fn: author, async } = pinProvider(bridge, fn, `column "${meta.key}" options rule`, OptionType(ArrayType(StringType)));
+    if (async)
+        throw new Error(`Sheet: column "${meta.key}" options rule must be synchronous — the menu reads it as the cell opens`);
+    return East.function([SheetContextType], OptionType(ArrayType(StringType)), ($, ctx) => {
+        const a = $.const(author);
+        const bc = $.const(bridge.bridgeCtx);
+        return a(bc(ctx));
+    });
+}
 /** Wrap an author member check — `Sheet.Types.CheckContext(R)` → `Option<String>` — into the `custom` check arm. */
 export function wrapCheck(bridge, meta, fn, index) {
     const expr = East.value(fn);
     const t = typeOf(expr);
-    if (t.type !== "Function" || (t.inputs ?? []).length !== 1 || t.inputs[0] !== bridge.checkCtxType || t.output !== OptionType(StringType)) {
-        throw new Error(`Sheet: column "${meta.key}" check #${index + 1} must be an East.function over Sheet.Types.CheckContext(RowType) returning Option<String>`);
+    if (t.type !== "Function" || (t.inputs ?? []).length !== 1 || !isTypeEqual(t.inputs[0], bridge.checkCtxType) ||
+        t.output === undefined || !isTypeEqual(t.output, OptionType(StringType))) {
+        const spelt = bridge.group !== undefined ? `Sheet.Types.CheckContext(GroupType, "${bridge.group.linesField}")` : "Sheet.Types.CheckContext(RowType)";
+        throw new Error(`Sheet: column "${meta.key}" check #${index + 1} must be an East.function over ${spelt} returning Option<String>`);
     }
+    const groupHalf = bridge.group;
+    const field = groupHalf?.linesField;
+    const entryDraft = SheetDraftEntryTypeFor(bridge.rowType, field);
+    const draftType = (groupHalf === undefined ? entryDraft : SheetDraftGroupTypeFor(groupHalf.groupType, groupHalf.linesField));
+    const rowDraft = SheetDraftTypeFor(bridge.lineType);
+    const base = buildDraftBase(bridge.rowType, field, bridge.rowById);
     const wire = East.function([SheetCheckContextType], OptionType(StringType), ($, c) => {
         const a = $.const(expr);
-        const byId = $.const(bridge.rowById);
-        const dec = $.const(bridge.decode);
-        const row = $.let(dec(c.rowId, c.row, byId(c.rowId, c.offset)), bridge.rowType);
-        return a(East.value({ rowIndex: c.rowIndex, row, half: c.half, member: c.member }, bridge.checkCtxType));
+        const read = $.const(base);
+        const dec = $.const(bridge.draftRow);
+        const original = $.const(read(c.drafts, c.rowId, c.offset), OptionType(entryDraft));
+        if (field === undefined || groupHalf === undefined) {
+            const row = $.const(dec(c.rowId, c.row, original));
+            return a($.const({ rowIndex: c.rowIndex, row, group: none, half: c.half, member: c.member }, bridge.checkCtxType));
+        }
+        const decGroup = $.const(groupHalf.decodeGroup);
+        /** A line's check: the line over its prior draft in its group, the group decoded over the wire group row. */
+        const lineCheck = ($2, own) => {
+            const group = $2.const(c.group.match({
+                none: () => own,
+                some: (_$, wire) => some(decGroup(wire, own, some(wire))),
+            }), OptionType(draftType));
+            const prior = $2.const(group.match({
+                none: () => none,
+                some: (_$, value) => {
+                    const children = value[field];
+                    return c.rowIndex.greaterEqual(0n).and(() => c.rowIndex.less(children.size())).ifElse(() => some(children.get(c.rowIndex)), () => none);
+                },
+            }), OptionType(rowDraft));
+            const row = $2.const(dec("", c.row, prior));
+            return a($2.const({ rowIndex: c.rowIndex, row, group, half: c.half, member: c.member }, bridge.checkCtxType));
+        };
+        const decLoose = groupHalf.decodeLoose;
+        if (decLoose === undefined)
+            return lineCheck($, original);
+        // A source with loose rows (#846): the entry's arms. A loose row has
+        // no line address — its own cells over its own draft, and no group.
+        const entry = original;
+        const decodeLoose = $.const(decLoose);
+        return c.line.match({
+            some: ($2) => {
+                const own = $2.const(entry.match({ none: () => none, some: (_$, e) => e.match({ group: (_$3, g) => some(g), row: () => none }) }), OptionType(draftType));
+                return lineCheck($2, own);
+            },
+            none: ($2) => {
+                const own = $2.const(entry.match({ none: () => none, some: (_$, e) => e.match({ row: (_$3, r) => some(r), group: () => none }) }), OptionType(rowDraft));
+                const row = $2.const(decodeLoose(c.rowId, c.row, own));
+                return a($2.const({ rowIndex: c.rowIndex, row, group: none, half: c.half, member: c.member }, bridge.checkCtxType));
+            },
+        });
     });
     return East.value(variant("custom", wire), SheetCheckType);
 }
@@ -536,8 +742,8 @@ export function wrapCustomParse(bridge, meta, fn) {
     const expr = East.value(fn);
     const t = typeOf(expr);
     const inputs = t.inputs ?? [];
-    if (t.type !== "Function" || inputs.length !== 2 || inputs[0] !== StringType || inputs[1] !== bridge.ctxType) {
-        throw new Error(`Sheet: custom column "${meta.key}" \`parse\` must be an East.function over (String, Sheet.Types.Context(RowType, DriverType)) returning Option<payload>`);
+    if (t.type !== "Function" || inputs.length !== 2 || !isTypeEqual(inputs[0], StringType) || !isTypeEqual(inputs[1], bridge.ctxType)) {
+        throw new Error(`Sheet: custom column "${meta.key}" \`parse\` must be an East.function over (String, ${contextName(bridge)}) returning Option<payload>`);
     }
     return East.function([StringType, SheetContextType], OptionType(SheetCellType), ($, text, ctx) => {
         const a = $.const(expr);
@@ -553,7 +759,8 @@ export function wrapCustomPrint(meta, fn) {
     const expr = East.value(fn);
     const t = typeOf(expr);
     const inputs = t.inputs ?? [];
-    if (t.type !== "Function" || inputs.length !== 1 || inputs[0] !== meta.payloadType || t.output !== StringType) {
+    if (t.type !== "Function" || inputs.length !== 1 || !isTypeEqual(inputs[0], meta.payloadType) ||
+        t.output === undefined || !isTypeEqual(t.output, StringType)) {
         throw new Error(`Sheet: custom column "${meta.key}" \`print\` must be an East.function over the payload (${describeType(meta.payloadType)}) returning String`);
     }
     return East.function([SheetCellType], StringType, ($, cell) => {
@@ -561,70 +768,6 @@ export function wrapCustomPrint(meta, fn) {
         return cell.match({ [meta.cellTag]: (_$, v) => a(v) }, (_$) => East.value("", StringType));
     });
 }
-/** Wrap a typed `onEdit` — `Sheet.Types.Edit(R)` → `Null` — into the wire edit handler. */
-export function wrapOnEdit(bridge, fn) {
-    const expr = East.value(fn, FunctionType([bridge.editType], NullType));
-    return East.function([SheetEditType], NullType, ($, e) => {
-        const a = $.const(expr);
-        const byId = $.const(bridge.rowById);
-        const dec = $.const(bridge.decode);
-        const noRow = $.const(none, OptionType(bridge.rowType));
-        const et = bridge.editType;
-        $(e.match({
-            commit: (_$, c) => a(East.value(variant("commit", {
-                rowId: c.rowId, key: c.key, row: dec(c.rowId, c.row.cells, byId(c.rowId, c.offset)), source: c.source,
-            }), et)),
-            insert: (_$, i) => a(East.value(variant("insert", {
-                afterRowId: i.afterRowId, row: dec(i.row.id, i.row.cells, noRow), source: i.source,
-            }), et)),
-            remove: (_$, r) => a(East.value(variant("remove", { rowIds: r.rowIds }), et)),
-        }));
-    });
-}
-/**
- * Compile `onUpdate` into the wire edit handler (§4.7) — the whole-value
- * rebuild: a commit rewrites one row, an insert appends a fresh row after
- * `afterRowId`, a remove filters ids; then the author's `onUpdate` receives
- * the collection.
- */
-export function compileOnUpdate(bridge, rows, idField, fn) {
-    const rowsType = ArrayType(bridge.rowType);
-    const expr = East.value(fn, FunctionType([rowsType], NullType));
-    return East.function([SheetEditType], NullType, ($, ev) => {
-        const current = $.let(rows, rowsType);
-        const upd = $.const(expr);
-        const dec = $.const(bridge.decode);
-        const noRow = $.const(none, OptionType(bridge.rowType));
-        const next = $.let(ev.match({
-            commit: (_$, c) => current.map((_$2, r) => idOf(r, idField).equal(c.rowId).ifElse((_$3) => dec(c.rowId, c.row.cells, East.value(some(r), OptionType(bridge.rowType))), (_$3) => r)),
-            insert: ($2, i) => {
-                const fresh = $2.let(dec(i.row.id, i.row.cells, noRow), bridge.rowType);
-                return i.afterRowId.match({
-                    none: (_$3) => current.concat(East.value([fresh], rowsType)),
-                    some: (_$3, after) => current.flatMap((_$4, r) => idOf(r, idField).equal(after).ifElse((_$5) => East.value([r, fresh], rowsType), (_$5) => East.value([r], rowsType))),
-                });
-            },
-            remove: ($2, rm) => {
-                const ids = $2.let(rm.rowIds.toSet());
-                return current.filter((_$3, r) => ids.has(idOf(r, idField)).not());
-            },
-        }), rowsType);
-        $(upd(next));
-    });
-}
-/** Both channels at once — `onEdit` observes, then `onUpdate` writes. */
-export function composeEditHandlers(observe, write) {
-    if (observe === undefined)
-        return write;
-    if (write === undefined)
-        return observe;
-    return East.function([SheetEditType], NullType, ($, e) => {
-        const o = $.const(observe);
-        const w = $.const(write);
-        $(o(e));
-        $(w(e));
-    });
-}
 /** Re-exported for the root's driver-typed refusals. */
 export { SheetHalfType, BooleanType, AsyncFunctionType, EMPTY_LINK };
 //# sourceMappingURL=bridge.js.map