@elaraai/east-ui 1.0.80 → 1.0.82

package/dist/src/contracts/source.js

@@ -11,8 +11,9 @@
  * positional surface, a `Dict<String, Row>` for a keyed one (#568). east-ui
  * declares the shape; whoever can actually fetch windows produces a value of
  * it. `Data.bindPaged` in `@elaraai/e3-ui` is the production implementation
- * (dataset windows over an e3 workspace) and {@link Paged.of} is the in-memory
- * one; neither is named here, and **nothing in this file imports e3**.
+ * (dataset windows over an e3 workspace) and {@link Paged.of} /
+ * {@link Paged.pinned} are the in-memory ones; e3 is never named here, and
+ * **nothing in this file imports e3**.
  *
  * # Why a variant, not a narrow struct
  *
@@ -28,7 +29,7 @@
  *
  * @packageDocumentation
  */
-import { East, Expr, ArrayType, BooleanType, DictType, FunctionType, IntegerType, OptionType, StringType, StructType, VariantType, variant, some, none, } from "@elaraai/east";
+import { East, Expr, ArrayType, BooleanType, DictType, FunctionType, IntegerType, NullType, OptionType, SetType, StringType, StructType, VariantType, isTypeEqual, variant, some, none, } from "@elaraai/east";
 // ============================================================================
 // Seek — where a key lands in a source's row space
 // ============================================================================
@@ -123,10 +124,10 @@ export const SeekQueryType = VariantType({
  *
  * Parameterised on the COLLECTION, not on the row: a window of an `Array<R>`
  * dataset is an `Array<R>`, a window of a `Dict<K, V>` dataset is a
- * `Dict<K, V>`, and the Plan's canvas windows are `Dict<String, PlanRow>`
- * (#568). That is what `Data.bindPaged` already produces — it returns
- * `Option<T>` at the dataset's own type — so the contract matches the producer
- * instead of narrowing it to arrays.
+ * `Dict<K, V>`, and the Plan's canvas windows are its blocks — one
+ * `Array<PlanRow>` stream per series (#823). That is what `Data.bindPaged`
+ * already produces — it returns `Option<T>` at the dataset's own type — so the
+ * contract matches the producer instead of narrowing it to arrays.
  *
  * `page` and `total` follow the in-flight-is-`none` convention: a window still
  * being fetched reads `none` and the call re-fires when it lands, so the reads
@@ -134,6 +135,28 @@ export const SeekQueryType = VariantType({
  * source is exhausted at that offset — a reader that walks offsets terminates
  * on an empty window, never on `none`.
  *
+ * A window may also hold FEWER than `limit` elements while the source still
+ * has more: a source that bounds its pages serves what fits. e3 trims every
+ * page of a dataset to a byte budget — the same number of elements on every
+ * page of one dataset — so wide elements come back in short windows (#829).
+ * Only an EMPTY window means exhausted. Components never see a short window:
+ * {@link buildRowSource}'s derived `page` re-requests whatever a trimmed page
+ * left out, so every window it serves is whole.
+ *
+ * A window that CANNOT be read — a failed fetch, a page that does not decode —
+ * makes `page` THROW its reason; it never reads `none`, which means in flight,
+ * and a reader waiting on it would wait forever (#811). A component shows the
+ * failure where that window's rows would be and asks again when the user
+ * retries. A source may rate-limit repeat attempts (e3 relaunches a failed
+ * window on a read at least two seconds later), and an authoring error — a
+ * dataset that cannot be paged — keeps throwing. `seek` follows the same rule.
+ *
+ * A paged source names no snapshot, so a component reads each of its windows
+ * once: the same `id` serves the same rows for as long as the component holds
+ * it. A source whose content moves under one id — a dataset the view follows,
+ * a source the view writes — is a {@link PinnedSourceType}, which names the
+ * snapshot its windows, total and searches belong to.
+ *
  * @typeParam C - The collection type one window carries.
  * @param c - The collection type value.
  * @returns The concrete `StructType` of a paged source over `c`.
@@ -144,11 +167,13 @@ export const SeekQueryType = VariantType({
  *   never re-renders when the source is swapped, and a window cache cannot key
  *   itself. Two sources with the same `id` must serve the same rows.
  * @property page - `(offset, limit)` → that window's elements as a value of the
- *   collection type; `none` while in flight, an EMPTY collection at exhaustion.
+ *   collection type; `none` while in flight, an EMPTY collection at exhaustion,
+ *   and possibly fewer than `limit` elements before it (see above). Throws when
+ *   the window cannot be read.
  * @property total - The source's total element count, once known; `none` until then.
  * @property seek - The source's key-search capability ({@link SeekType}) —
  *   `none` when the source is not key-ordered (an Array-backed source cannot
- *   seek; there is nothing to binary-search).
+ *   seek; there is nothing to binary-search). A search that fails throws.
  */
 export const PagedSourceType = (c) => StructType({
     id: StringType,
@@ -156,6 +181,46 @@ export const PagedSourceType = (c) => StructType({
     total: FunctionType([], OptionType(IntegerType)),
     seek: OptionType(FunctionType([SeekQueryType], OptionType(SeekRangeType))),
 });
+/**
+ * A {@link PagedSourceType} that names its SNAPSHOT — the contract a component
+ * follows through changes to the source's content, and the one it edits.
+ *
+ * @remarks
+ * Every window, the total and every search belong to one snapshot, the
+ * source's `revision`, so rows from two snapshots never sit side by side. When
+ * the revision moves — the data was written, `refresh` was asked for — a
+ * component reads its windows again at the new one, and the rows it had stand
+ * in until each lands: the view never empties between two snapshots of its
+ * data (#821). An edit is checked against the snapshot it was drafted on, and
+ * the drafts retire once the source reads back at the snapshot the write made
+ * (#880) — which is why the Sheet and the Plan edit a paged source only
+ * through this contract.
+ *
+ * `Data.bindPaged` in `@elaraai/e3-ui` returns one, its revision the dataset's
+ * content hash, and {@link Paged.pinned} is the in-memory one.
+ *
+ * @typeParam C - The collection type one window carries.
+ * @param c - The collection type value.
+ * @returns The concrete `StructType` of a pinned source over `c`.
+ *
+ * @property id - The logical source's identity, as {@link PagedSourceType}'s;
+ *   the rows it serves are its current revision's.
+ * @property page - As {@link PagedSourceType}'s, at the current revision.
+ * @property total - As {@link PagedSourceType}'s, at the current revision.
+ * @property seek - As {@link PagedSourceType}'s, at the current revision.
+ * @property revision - The snapshot the source serves; `none` while it is
+ *   being found. A reader re-fires when the source moves to another.
+ * @property refresh - Move the source: `some(hash)` to that snapshot — after a
+ *   write the view confirmed — or `none` to the one the source holds now.
+ */
+export const PinnedSourceType = (c) => StructType({
+    id: StringType,
+    page: FunctionType([IntegerType, IntegerType], OptionType(c)),
+    total: FunctionType([], OptionType(IntegerType)),
+    seek: OptionType(FunctionType([SeekQueryType], OptionType(SeekRangeType))),
+    revision: FunctionType([], OptionType(StringType)),
+    refresh: FunctionType([OptionType(StringType)], NullType),
+});
 // ============================================================================
 // The row-source variant — what components actually store
 // ============================================================================
@@ -163,10 +228,17 @@ export const PagedSourceType = (c) => StructType({
  * How a component's rows arrive: inline, or from a windowed source.
  *
  * @remarks
- * Both arms speak the same COLLECTION type — inline is the whole of it, paged
- * is a window of it — so a component that keys its rows (the Plan's
- * `Dict<String, PlanRow>`) and one that positions them (`Array<Row>`) share one
- * vocabulary without either shape leaking into the arm names (#568).
+ * Every arm speaks the same COLLECTION type — inline is the whole of it, the
+ * windowed arms a window of it — so a keyed source (a Sheet's
+ * `Dict<String, Row>`), a positional one (a Table's `Array<Row>`) and a
+ * composite one (the Plan's blocks, one row stream per series) share one
+ * vocabulary without any shape leaking into the arm names (#568).
+ *
+ * The two windowed arms differ in one thing: whether the source names its
+ * snapshot. `paged` is the released arm — exported UIs carry it, so it never
+ * changes — and a component reads each of its windows once; `pinned` names the
+ * revision its windows belong to, which is what lets a component follow the
+ * source as its content changes, and edit it.
  *
  * @typeParam C - The collection type.
  * @param c - The collection type value.
@@ -174,10 +246,12 @@ export const PagedSourceType = (c) => StructType({
  *
  * @property inline - The whole collection, already in hand.
  * @property paged - A {@link PagedSourceType} fetched a window at a time.
+ * @property pinned - A {@link PinnedSourceType} — windows at a named snapshot, followed from one to the next.
  */
 export const RowSourceType = (c) => VariantType({
     inline: c,
     paged: PagedSourceType(c),
+    pinned: PinnedSourceType(c),
 });
 /**
  * The element shape an ORDERED window carries: an index entry.
@@ -236,6 +310,34 @@ function keyTypeOf(t) {
         return type.key;
     return undefined;
 }
+/** The members a {@link PinnedSourceType} adds to a paged source, at their types. */
+const SNAPSHOT_MEMBERS = {
+    revision: FunctionType([], OptionType(StringType)),
+    refresh: FunctionType([OptionType(StringType)], NullType),
+};
+/**
+ * Whether a windowed source names its snapshot — `revision` and `refresh`,
+ * both, at {@link PinnedSourceType}'s types.
+ *
+ * @param fields - The source's struct fields
+ * @param label - Component name for the error message
+ * @returns Whether the source is pinned
+ * @throws Error when the source has one of the two without the other, or
+ *   either at another type — it would build neither arm faithfully
+ */
+function namesSnapshot(fields, label) {
+    const revision = fields["revision"];
+    const refresh = fields["refresh"];
+    if (revision === undefined && refresh === undefined)
+        return false;
+    if (revision !== undefined && refresh !== undefined
+        && isTypeEqual(revision, SNAPSHOT_MEMBERS.revision) && isTypeEqual(refresh, SNAPSHOT_MEMBERS.refresh)) {
+        return true;
+    }
+    const found = revision === undefined ? "only `refresh`" : refresh === undefined ? "only `revision`" : "them at other types";
+    throw new Error(`${label}: a paged source names its snapshot with both \`revision: () → Option<String>\` and ` +
+        `\`refresh: (Option<String>) → Null\`, as Data.bindPaged's handle and Paged.pinned do — this one has ${found}`);
+}
 /**
  * Classify a component's rows prop at BUILD time — the one dispatch every
  * collection shares, so no component re-sniffs shapes of its own.
@@ -243,7 +345,9 @@ function keyTypeOf(t) {
  * Accepted shapes, in order:
  * - a collection expression / value (`Array<R>`, `Dict<K, V>`, `Set<R>`) ⇒ `inline`;
  * - a struct carrying `page` + `total` ⇒ `paged` (a {@link PagedSourceType},
- *   or anything structurally matching it — `Data.bindPaged`'s handle);
+ *   or anything structurally matching it), marked `pinned` when it also
+ *   carries `revision` + `refresh` (a {@link PinnedSourceType} —
+ *   `Data.bindPaged`'s handle, `Paged.pinned`);
  * - a struct carrying `read` ⇒ a whole-value bind handle, which resolves by
  *   CALLING `read()` and recursing. The call becomes part of the surrounding
  *   East expression, so it is evaluated inside the component's reactive render
@@ -252,7 +356,7 @@ function keyTypeOf(t) {
  *
  * @param data - The rows prop as the author passed it
  * @param label - Component name for the error message (`"Plan"`, `"Table"`)
- * @returns The resolved arm — see {@link ResolvedRowSource}
+ * @returns The resolved arm, retaining a live handle for invocation-time reads — see {@link ResolvedRowSource}
  * @throws Error when the expression is none of the accepted shapes
  */
 export function resolveRowSource(data, label) {
@@ -274,6 +378,8 @@ export function resolveRowSource(data, label) {
             throw new Error(`${label}: the paged source's \`page\` must return \`Option<Collection>\` ` +
                 `(an Array, Dict or Set) — got ${JSON.stringify(page)}`);
         }
+        // A source that names its snapshot builds the `pinned` arm.
+        const pinned = namesSnapshot(fields, label);
         // An ORDERED window: positional, but every row carries its own key.
         // Recognised by the element's shape rather than announced by a flag,
         // so a source that serves index entries needs no second vocabulary.
@@ -281,19 +387,20 @@ export function resolveRowSource(data, label) {
         if (entry !== null) {
             return {
                 kind: "ordered", source: expr,
-                collectionType, elementType, keyType: entry.key, orderKeyType: entry.ik,
+                collectionType, elementType, keyType: entry.key, orderKeyType: entry.ik, pinned,
             };
         }
         return {
             kind: "paged", source: expr,
-            collectionType, elementType, keyType: keyTypeOf(collectionType),
+            collectionType, elementType, keyType: keyTypeOf(collectionType), pinned,
         };
     }
     if (fields !== undefined && fields["read"] !== undefined) {
         // A whole-value bind handle (`Data.bind`) — read it here, in the
         // surrounding East expression, and resolve the result.
         const handle = expr;
-        return resolveRowSource(handle.read(), label);
+        const resolved = resolveRowSource(handle.read(), label);
+        return resolved.kind === "inline" ? { ...resolved, live: expr } : resolved;
     }
     throw new Error(`${label}: rows must be a collection, a paged source (\`{ id, page, total }\` — e.g. Data.bindPaged), ` +
         `or a bound value (\`{ read }\` — e.g. Data.bind); got a ${t.type}`);
@@ -314,25 +421,40 @@ export function resolveRowSource(data, label) {
  * component's rows inherit the source's keys, and flattening at the boundary
  * would throw away exactly what makes a window's rows addressable (#568). A
  * positional component (Table) receives its `Array<Row>`; a keyed one (Plan) a
- * `Dict<String, R>`.
+ * `Dict<K, R>`.
  *
  * @typeParam Out - The component's own row COLLECTION type.
  * @param resolved - The output of {@link resolveRowSource}
  * @param outType - The component's row collection type
  * @param make - The source collection → the component's row collection
- * @param idSuffix - Appended to the paged source's `id` — see below
  * @returns The `RowSourceType(outType)` value to store in the IR
  *
  * @remarks
- * `idSuffix` exists because `make` is part of what the derived source SERVES.
- * {@link PagedSourceType} requires that two sources sharing an `id` serve the
- * same rows, and a component whose `make` changes — a Plan whose series list was
- * narrowed by a pick — now serves different rows from the same underlying
- * handle. Since a window cache keys on `id` alone and resident windows are never
- * re-read, an unsigned id leaves the previous rows on screen forever. A
- * component that can vary its `make` must pass a signature of what varied.
+ * The derived source keeps the handle's `id`: `make` is part of what it
+ * serves, and a component whose `make` changes (a Plan whose series list a
+ * pick narrowed) serves other rows from the same handle — which a renderer
+ * tells apart by comparing the derived source whole, closures included
+ * (`equivalentFor`, #809), not by its id (#822).
+ *
+ * The derived `page` serves WHOLE windows (#829). A handle may answer
+ * `(offset, limit)` with fewer than `limit` elements while it still has more —
+ * e3 trims every page to a byte budget — and every component addresses its
+ * windows at `w × size`, so a short window would silently drop its tail. The
+ * derived `page` therefore re-requests `(offset + served, limit − served)`
+ * until the window holds `limit` elements, the source is exhausted (an empty
+ * piece, or `offset + served` reaching a known `total()`), or a piece is still
+ * in flight — in which case the whole window reads `none` and re-fires when the
+ * piece lands. The pieces join in the collection's own order (arrays
+ * concatenate; dicts and sets union, their pieces being disjoint and ascending)
+ * and `make` runs once over the whole window. Each piece stays its own request,
+ * so a runtime caches them at the size the source chose to serve.
+ *
+ * A source that names its snapshot (`resolved.pinned`, a
+ * {@link PinnedSourceType}) builds the `pinned` arm, its `revision` and
+ * `refresh` carried through as they are; any other builds `paged`, which has
+ * neither. The derived `page` is the same either way.
  */
-export function buildRowSource(resolved, outType, make, idSuffix) {
+export function buildRowSource(resolved, outType, make) {
     const sourceType = RowSourceType(outType);
     if (resolved.kind === "inline") {
         return East.value(variant("inline", make(resolved.rows)), sourceType);
@@ -340,48 +462,208 @@ export function buildRowSource(resolved, outType, make, idSuffix) {
     // `ordered` and `paged` build the same value: by the time `make` has run,
     // the rows are the component's own shape, and whatever the entry carried —
     // its key, its order key — is in there because the component's `make` put
-    // it there. The distinction is a BUILD-time one, which is why there is no
-    // third arm here for a renderer to match on.
-    const handle = resolved.source;
+    // it there. The distinction is a BUILD-time one, which is why `ordered`
+    // has no arm of its own for a renderer to match on. What picks the arm is
+    // whether the source names its snapshot.
+    const handle = pagedHandleOf(resolved);
     // Erased locally: the window type is `Out`, but TS cannot see through the
     // generic to unify `Option<Out>`'s arms — the East type is what types it.
     const winType = outType;
+    // The WHOLE window of the source's own collection, then `make` over it
+    // (#829) — reified once, and shared with anything that must read the very
+    // windows a component reads (the Plan's editing, #880).
+    const window = buildPagedWindow(resolved);
     const page = East.function([IntegerType, IntegerType], OptionType(winType), ($, offset, limit) => {
-        const empty = $.const(none, OptionType(winType));
-        const win = $.let(handle.page(offset, limit));
-        return win.match({
-            some: ($, window) => {
-                const built = $.let(make(window), outType);
-                return $.const(some(built), OptionType(winType));
+        const read = $.const(window);
+        const result = $.let(none, OptionType(winType));
+        const whole = $.let(read(offset, limit));
+        $.match(whole, {
+            some: ($, entries) => {
+                const built = $.let(make(entries), outType);
+                $.assign(result, some(built));
             },
-            none: (_$) => empty,
         });
+        return result;
     });
     // A source predating the contract carries no `id` / `seek`; fall back to a
     // constant identity (it still compares equal to itself) and no seek.
     const fields = structFields(Expr.type(resolved.source)) ?? {};
-    const baseId = fields["id"] !== undefined ? handle.id : East.value("", StringType);
-    const id = idSuffix !== undefined
-        ? East.str `${baseId}#${East.value(idSuffix, StringType)}`
-        : baseId;
+    const id = fields["id"] !== undefined ? handle.id : East.value("", StringType);
     const seek = fields["seek"] !== undefined
         ? handle.seek
         : East.value(none, OptionType(FunctionType([SeekQueryType], OptionType(SeekRangeType))));
-    return East.value(variant("paged", { id, page, total: handle.total, seek }), sourceType);
+    if (!resolved.pinned) {
+        return East.value(variant("paged", { id, page, total: handle.total, seek }), sourceType);
+    }
+    const snapshot = resolved.source;
+    return East.value(variant("pinned", { id, page, total: handle.total, seek, revision: snapshot.revision, refresh: snapshot.refresh }), sourceType);
+}
+/** A resolved paged source's handle, at the contract's shape. */
+function pagedHandleOf(resolved) {
+    return resolved.source;
+}
+/**
+ * The WHOLE window `(offset, limit)` of a paged source's own collection — the
+ * pieces a trimmed page left out asked for until the window holds `limit`
+ * elements, the source is exhausted, or a piece is in flight (the window then
+ * reads `none`, #829). What {@link buildRowSource}'s derived `page` maps its
+ * `make` over; a caller that must read the very windows a component reads —
+ * the Plan's editing reads its entries back (#880) — asks for them here, so
+ * each piece is the same request the component made.
+ *
+ * @param resolved - A resolved paged source ({@link resolveRowSource})
+ * @returns `(offset, limit)` → the window, `none` while a piece is in flight
+ */
+export function buildPagedWindow(resolved) {
+    const handle = pagedHandleOf(resolved);
+    // The source's own collection — every piece of a window is a value of it.
+    // Its size and the in-order join of two pieces are reified ONCE, outside
+    // the block, per collection kind, then CALLED. Both are pure: a piece may
+    // be the very window object a runtime holds in its cache.
+    const pieceType = resolved.collectionType;
+    const pieceKind = pieceType.type;
+    const sizeOf = pieceKind === "Array"
+        ? East.function([pieceType], IntegerType, (_$, c) => c.length())
+        : pieceKind === "Dict"
+            ? East.function([pieceType], IntegerType, (_$, c) => c.size())
+            : East.function([pieceType], IntegerType, (_$, c) => c.size());
+    const joinOf = pieceKind === "Array"
+        ? East.function([pieceType, pieceType], pieceType, (_$, a, b) => a.concat(b))
+        : pieceKind === "Dict"
+            // Pieces are disjoint, so the conflict arm never runs.
+            ? East.function([pieceType, pieceType], pieceType, (_$, a, b) => a.union(b, (_$2, _mine, theirs) => theirs))
+            : East.function([pieceType, pieceType], pieceType, (_$, a, b) => a.union(b));
+    return East.function([IntegerType, IntegerType], OptionType(pieceType), ($, offset, limit) => {
+        // Bound ONCE: the handle may be a platform call (`Data.bindPaged(…)`
+        // passed inline), and this body reads it up to three times.
+        const src = $.const(handle);
+        const size = $.const(sizeOf);
+        const join = $.const(joinOf);
+        const result = $.let(none, OptionType(pieceType));
+        const first = $.let(src.page(offset, limit));
+        $.match(first, {
+            some: ($, head) => {
+                const window = $.let(head, pieceType);
+                const served = $.let(size(head), IntegerType);
+                const inFlight = $.let(false, BooleanType);
+                // An empty first window is exhaustion. A short one — the
+                // source trimmed it — asks for the rest, piece by piece.
+                $.while(served.greater(0n).and(() => served.less(limit)), ($, label) => {
+                    // A known total says where the source ends: no piece past it.
+                    const total = $.let(src.total());
+                    $.match(total, {
+                        some: ($, t) => {
+                            $.if(offset.add(served).greaterEqual(t), ($) => { $.break(label); });
+                        },
+                    });
+                    const next = $.let(src.page(offset.add(served), limit.subtract(served)));
+                    $.match(next, {
+                        none: ($) => {
+                            // Still in flight: the whole window waits, and the
+                            // piece's landing re-fires this evaluation.
+                            $.assign(inFlight, true);
+                            $.break(label);
+                        },
+                        some: ($, piece) => {
+                            const n = $.let(size(piece), IntegerType);
+                            $.if(n.equal(0n), ($) => { $.break(label); });
+                            $.assign(window, join(window, piece));
+                            $.assign(served, served.add(n));
+                        },
+                    });
+                });
+                $.if(inFlight.not(), ($) => { $.assign(result, some(window)); });
+            },
+        });
+        return result;
+    });
 }
 function createPagedOf(id, collection, options) {
-    const collectionExpr = East.value(collection);
-    if (Expr.type(collectionExpr).type === "Dict") {
-        return keyedPagedOf(id, collectionExpr);
+    return createInMemory(id, collection, options, false);
+}
+function createPagedPinned(id, collection, options) {
+    return createInMemory(id, collection, options, true);
+}
+/**
+ * The in-memory source over a collection — {@link Paged.of}'s, or, `pinned`,
+ * {@link Paged.pinned}'s.
+ *
+ * @param id - The source's identity
+ * @param collection - The whole collection
+ * @param options - {@link PagedOfOptions}
+ * @param pinned - Whether the source names its snapshot
+ * @returns The source, at the collection it was given
+ * @throws {Error} When `pageLimit` is not a positive integer
+ */
+function createInMemory(id, collection, options, pinned) {
+    const pageLimit = options?.pageLimit;
+    if (pageLimit !== undefined && !(Number.isInteger(pageLimit) && pageLimit > 0)) {
+        throw new Error(`${pinned ? "Paged.pinned" : "Paged.of"}: \`pageLimit\` must be a positive integer — the most elements one window serves (got ${pageLimit})`);
     }
-    return arrayPagedOf(id, collectionExpr, options);
+    const collectionExpr = East.value(collection);
+    const collectionType = Expr.type(collectionExpr);
+    const keyed = collectionType.type === "Dict";
+    const sourceType = pinned ? PinnedSourceType(collectionType) : PagedSourceType(collectionType);
+    // Evaluate the input once when creating the source, then detach nested
+    // mutable values. Page and seek closures share that captured snapshot;
+    // passing a live read expression cannot make later pages drift. The copy
+    // is beast v2: v1 writes neither a recursive type nor a function, and an
+    // entry may be either (a Plan's entries, #822).
+    const capture = East.function([StringType, collectionType], sourceType, ($, snapshotId, input) => {
+        const snapshot = $.const(East.Blob.encodeBeast(input, "v2").decodeBeast(collectionType, "v2"), collectionType);
+        return keyed ? keyedPagedOf(snapshotId, snapshot, pageLimit, pinned)
+            : arrayPagedOf(snapshotId, snapshot, options, pinned);
+    });
+    return East.value(capture)(id, collectionExpr);
+}
+/**
+ * An in-memory source's lifecycle when it is pinned: its one snapshot is its
+ * id. Built as real `East.function`s over the id, never spliced.
+ *
+ * @param id - The source's identity — its snapshot
+ * @returns `revision` and `refresh`, at {@link PinnedSourceType}'s types
+ */
+function fixedSnapshot(id) {
+    const revision = East.function([], OptionType(StringType), ($) => {
+        const snapshot = $.const(id, StringType);
+        return some(snapshot);
+    });
+    const refresh = East.function([OptionType(StringType)], NullType, ($, target) => {
+        const snapshot = $.const(id, StringType);
+        $.match(target, {
+            some: ($2, hash) => {
+                $2.if(hash.notEqual(snapshot), ($3) => {
+                    $3.error("Paged.pinned: an immutable snapshot — create a source with the requested snapshot id");
+                });
+            },
+            none: () => { },
+        });
+        return null;
+    });
+    return { revision, refresh };
+}
+/**
+ * The window size a source actually serves for a requested `limit` — the
+ * request itself, or `pageLimit` when that is smaller. Reified once as a real
+ * East function (the `shared/reify` rule), so a page body CALLS it instead of
+ * branching on host state. `none` ⇒ the source never trims.
+ */
+function servedLimitFn(pageLimit) {
+    const capValue = pageLimit === undefined ? none : some(BigInt(pageLimit));
+    return East.function([IntegerType], IntegerType, ($, limit) => {
+        const cap = $.const(capValue, OptionType(IntegerType));
+        return cap.match({
+            some: (_$, c) => limit.less(c).ifElse(() => limit, () => c),
+            none: (_$) => limit,
+        });
+    });
 }
 /**
  * The KEYED in-memory source — dict windows in canonical key order, with
  * `seek` derived from the keys themselves (a keyed collection needs no key
- * accessor: it already is one).
+ * accessor: it already is one). `pinned` adds its {@link fixedSnapshot}.
  */
-function keyedPagedOf(id, collection) {
+function keyedPagedOf(id, collection, pageLimit, pinned) {
     const all = collection;
     const valueType = Expr.type(all).value;
     const dictType = DictType(StringType, valueType);
@@ -389,14 +671,16 @@ function keyedPagedOf(id, collection) {
     const entriesType = ArrayType(entryType);
     // Built OUTSIDE every block (an East macro inside one splices per use).
     const keyOfEntry = East.function([entryType], StringType, (_$, e) => e.key);
+    const servedLimit = servedLimitFn(pageLimit);
     const page = East.function([IntegerType, IntegerType], OptionType(dictType), ($, offset, limit) => {
         const src = $.const(all, dictType);
+        const served = $.const(servedLimit);
         // `toArray` walks the dictionary in key order, so the window a given
         // offset serves is the window a keyed dataset would serve.
         const entries = $.let(src.toArray(($2, v, k) => $2.const({ key: k, value: v }, entryType)), entriesType);
         const n = $.let(entries.length(), IntegerType);
         const start = $.let(offset.less(n).ifElse(() => offset, () => n), IntegerType);
-        const rawEnd = $.let(offset.add(limit), IntegerType);
+        const rawEnd = $.let(offset.add(served(limit)), IntegerType);
         const end = $.let(rawEnd.less(n).ifElse(() => rawEnd, () => n), IntegerType);
         // In-memory windows are never in flight; an exhausted offset yields
         // the EMPTY window, which is how a walking reader terminates.
@@ -473,10 +757,14 @@ function keyedPagedOf(id, collection) {
         });
     });
     const seek = some(find);
-    return East.value({ id, page, total, seek }, PagedSourceType(dictType));
+    const members = { id, page, total, seek };
+    return (pinned
+        ? East.value({ ...members, ...fixedSnapshot(id) }, PinnedSourceType(dictType))
+        : East.value(members, PagedSourceType(dictType)));
 }
-/** The POSITIONAL in-memory source — array windows in stream order. */
-function arrayPagedOf(id, rows, options) {
+/** The POSITIONAL in-memory source — array windows in stream order.
+ *  `pinned` adds its {@link fixedSnapshot}. */
+function arrayPagedOf(id, rows, options, pinned) {
     const all = rows;
     const rowType = Expr.type(all).value;
     const rowsType = ArrayType(rowType);
@@ -486,11 +774,13 @@ function arrayPagedOf(id, rows, options) {
     const byFn = keyOf === undefined
         ? undefined
         : East.function([rowType], StringType, (_$, r) => keyOf(r));
+    const servedLimit = servedLimitFn(options?.pageLimit);
     const page = East.function([IntegerType, IntegerType], OptionType(rowsType), ($, offset, limit) => {
         const src = $.const(all, rowsType);
+        const served = $.const(servedLimit);
         const n = $.let(src.length(), IntegerType);
         const start = $.let(offset.less(n).ifElse(() => offset, () => n), IntegerType);
-        const rawEnd = $.let(offset.add(limit), IntegerType);
+        const rawEnd = $.let(offset.add(served(limit)), IntegerType);
         const end = $.let(rawEnd.less(n).ifElse(() => rawEnd, () => n), IntegerType);
         // In-memory windows are never in flight; an exhausted offset yields
         // the EMPTY window, which is how a walking reader terminates.
@@ -567,11 +857,16 @@ function arrayPagedOf(id, rows, options) {
     // Two-step cast (the `Data.bindPaged` idiom): the members are built
     // against the row type recovered from the expression, which TS sees as the
     // erased `EastType` rather than the caller's `R`. The East-side type —
-    // `PagedSourceType(rowsType)` — is what actually types the value.
-    return East.value({ id, page, total, seek }, PagedSourceType(rowsType));
+    // `PagedSourceType(rowsType)`, or `PinnedSourceType(rowsType)` — is what
+    // actually types the value.
+    const members = { id, page, total, seek };
+    return (pinned
+        ? East.value({ ...members, ...fixedSnapshot(id) }, PinnedSourceType(rowsType))
+        : East.value(members, PagedSourceType(rowsType)));
 }
 /**
- * The `Paged` namespace — building a {@link PagedSourceType} without a server.
+ * The `Paged` namespace — building a {@link PagedSourceType} or a
+ * {@link PinnedSourceType} without a server.
  *
  * @remarks
  * The contract itself is what components consume; this namespace is the
@@ -581,15 +876,19 @@ function arrayPagedOf(id, rows, options) {
 export const Paged = {
     /** Build an in-memory paged source over a collection already in hand. */
     of: createPagedOf,
+    /** Build an in-memory PINNED source — `of`, naming its one snapshot, for a fixture a view edits or follows. */
+    pinned: createPagedPinned,
     /** East types — the contract, for `$.const` / `$.let` annotations. */
     Types: {
         /** A windowed row source over a collection type. */
         Source: PagedSourceType,
+        /** A windowed row source that names its snapshot, over a collection type. */
+        PinnedSource: PinnedSourceType,
         /** Where a key query landed in a source's row order. */
         SeekRange: SeekRangeType,
         /** A key query — exact literal, String prefix, leading struct fields, or a range. */
         SeekQuery: SeekQueryType,
-        /** How a component's rows arrive (inline / paged), at a collection type. */
+        /** How a component's rows arrive (inline / paged / pinned), at a collection type. */
         RowSource: RowSourceType,
     },
 };