@rindle/client 0.7.11 → 0.8.0

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { KeyedRow, MutationOp, ServerWriteTx } from "./mutation-ops.ts";
 export { defineMutators, driveMutationAsync, driveMutationSync, isGeneratorMutator, isoTx, shared, } from "./mutation-ops.ts";
 export type { ArgSchema, AsyncEffectExec, BatchEffect, IsoTx, IsoTxOf, MutationGen, MutatorCtx, QueryArg, QueryEffect, QueryResultRow, ReadEffect, SharedMutator, SharedMutatorWithArgs, SyncEffectExec, YieldEffect, } from "./mutation-ops.ts";
 export { stableKey } from "./key.ts";
+export { STREAM_STATUS_STREAMING, assembleDurableText, frameResumePoint, spliceStreamText, } from "./stream.ts";
+export type { StreamFrame, StreamStatus } from "./stream.ts";
 export { COMPARATOR_VERSION, compareNumber, compareRows, compareString, compareValue } from "./compare.ts";
 export type { Backend, BackendDevObserver, BackendServerDelta, ChangeEvent, ColType, FlatChange, FlatOp, Mutation, MutationEnvelope, MutationOutcomeFrame, NormalizedEvent, NormalizedOp, NormalizedSource, NormalizedTableSchema, OptimisticSource, PathSeg, ProgressFrame, QueryId, RemoteQuery, ResultType, WireNode, WireProjection, WireRel, WireSchema, WireValue, } from "./types.ts";
 export { CLIENT_MUTATIONS_SCHEMA, CLIENT_MUTATIONS_TABLE, LMID_QUERY_NAME } from "./types.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE7D,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,GACP,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,SAAS,EACT,eAAe,EACf,WAAW,EACX,KAAK,EACL,OAAO,EACP,WAAW,EACX,UAAU,EACV,QAAQ,EACR,WAAW,EACX,cAAc,EACd,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3G,YAAY,EACV,OAAO,EACP,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,OAAO,EACP,UAAU,EACV,MAAM,EACN,QAAQ,EACR,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,OAAO,EACP,WAAW,EACX,UAAU,EACV,QAAQ,EACR,cAAc,EACd,OAAO,EACP,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG9F,YAAY,EACV,SAAS,EACT,GAAG,EACH,KAAK,EACL,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,aAAa,GACd,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE7D,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,GACP,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,SAAS,EACT,eAAe,EACf,WAAW,EACX,KAAK,EACL,OAAO,EACP,WAAW,EACX,UAAU,EACV,QAAQ,EACR,WAAW,EACX,cAAc,EACd,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAKrC,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3G,YAAY,EACV,OAAO,EACP,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,OAAO,EACP,UAAU,EACV,MAAM,EACN,QAAQ,EACR,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,OAAO,EACP,WAAW,EACX,UAAU,EACV,QAAQ,EACR,cAAc,EACd,OAAO,EACP,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG9F,YAAY,EACV,SAAS,EACT,GAAG,EACH,KAAK,EACL,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,aAAa,GACd,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -12,6 +12,10 @@ export { resolveChange, subRow } from "./resolve.js"; // positional FlatChange
 // shared (generator) mutator seam — one body, sync on the client + async on the server
 export { defineMutators, driveMutationAsync, driveMutationSync, isGeneratorMutator, isoTx, shared, } from "./mutation-ops.js";
 export { stableKey } from "./key.js"; // canonical viewKey for an AST (shared with @rindle/react)
+// The LM stream plane's shared contract (LM-STREAM-CHECKPOINT-DESIGN.md): frame shapes + the two pure
+// reassembly functions. Lives here because BOTH tiers need them — `@rindle/api-server` re-exports
+// every name, and `@rindle/react`'s `useStreamedText` builds on them without a server import.
+export { STREAM_STATUS_STREAMING, assembleDurableText, frameResumePoint, spliceStreamText, } from "./stream.js";
 export { COMPARATOR_VERSION, compareNumber, compareRows, compareString, compareValue } from "./compare.js";
 export { CLIENT_MUTATIONS_SCHEMA, CLIENT_MUTATIONS_TABLE, LMID_QUERY_NAME } from "./types.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,0FAA0F;AAC1F,8CAA8C;AAE9C,cAAc,aAAa,CAAC,CAAC,oMAAoM;AACjO,cAAc,gBAAgB,CAAC,CAAC,mGAAmG;AACnI,cAAc,YAAY,CAAC,CAAC,uIAAuI;AACnK,cAAc,WAAW,CAAC,CAAC,uEAAuE;AAClG,cAAc,YAAY,CAAC,CAAC,kEAAkE;AAC9F,cAAc,aAAa,CAAC,CAAC,qDAAqD;AAClF,cAAc,UAAU,CAAC,CAAC,oGAAoG;AAE9H,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC,CAAC,mEAAmE;AAIzH,uFAAuF;AACvF,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,GACP,MAAM,mBAAmB,CAAC;AAmB3B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC,CAAC,2DAA2D;AAEjG,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA8B3G,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,0FAA0F;AAC1F,8CAA8C;AAE9C,cAAc,aAAa,CAAC,CAAC,oMAAoM;AACjO,cAAc,gBAAgB,CAAC,CAAC,mGAAmG;AACnI,cAAc,YAAY,CAAC,CAAC,uIAAuI;AACnK,cAAc,WAAW,CAAC,CAAC,uEAAuE;AAClG,cAAc,YAAY,CAAC,CAAC,kEAAkE;AAC9F,cAAc,aAAa,CAAC,CAAC,qDAAqD;AAClF,cAAc,UAAU,CAAC,CAAC,oGAAoG;AAE9H,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC,CAAC,mEAAmE;AAIzH,uFAAuF;AACvF,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,GACP,MAAM,mBAAmB,CAAC;AAmB3B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC,CAAC,2DAA2D;AAEjG,sGAAsG;AACtG,kGAAkG;AAClG,8FAA8F;AAC9F,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA8B3G,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/stream.d.ts

@@ -0,0 +1,91 @@
+/**
+ * How a stream ended.
+ * - `complete` — the model finished.
+ * - `cancelled` — the reader asked it to stop and the producer honoured it.
+ * - `error` — the generation threw.
+ * - `interrupted` — the host went away mid-generation. The one status that implies the store may be
+ *   short of what was produced.
+ */
+export type StreamStatus = "complete" | "cancelled" | "error" | "interrupted";
+/** The value in the mapped status column while a stream is live. */
+export declare const STREAM_STATUS_STREAMING = "streaming";
+/**
+ * One frame of a subscription. A subscription always begins with `open` and always ends with exactly
+ * one terminal frame — `end`, `stale`, or `absent` — after which the iterator completes.
+ *
+ * `stale` and `absent` are the two "you are on the durable plane now" answers, and both are SAFE:
+ * the store holds everything below `floorSeq` and everything through `durableSeq`, so the reader's
+ * IVM view converges without the stream. Neither is an error.
+ */
+export type StreamFrame = 
+/** Join accepted. `from` is the (clamped) offset the replay starts at. */
+{
+    type: "open";
+    streamId: string;
+    from: number;
+    seq: number;
+    durableSeq: number;
+    ended: boolean;
+}
+/** PRODUCED text — not a durability claim. `text.length === seq - from`, always. */
+ | {
+    type: "chunk";
+    from: number;
+    seq: number;
+    text: string;
+}
+/** The store now holds the prefix through `seq`. */
+ | {
+    type: "durable";
+    seq: number;
+}
+/** Sealed. No further frames. */
+ | {
+    type: "end";
+    seq: number;
+    status: StreamStatus;
+    error?: string;
+}
+/** `from` is below the producer's retained buffer floor (or the subscriber fell too far behind):
+ *  read the store. (A raw `EventSource` rejoins automatically on its reconnect; `useStreamedText`
+ *  deliberately stays on the durable plane instead — correct, at checkpoint granularity.) */
+ | {
+    type: "stale";
+    floorSeq: number;
+    durableSeq: number;
+}
+/** The process serving this subscribe is not hosting the stream (wrong instance, already evicted,
+ *  or it never existed): the store is the whole truth. */
+ | {
+    type: "absent";
+};
+/** The resume point a frame implies — what rides an SSE `id:` line so a reconnecting `EventSource`
+ *  hands it straight back as `Last-Event-ID`. `undefined` for frames that are not a position. */
+export declare function frameResumePoint(frame: StreamFrame): number | undefined;
+/**
+ * Merge the durable plane with the live tail.
+ *
+ * `durable` is what the IVM view shows; `produced` is what a subscription has accumulated (the prefix
+ * it joined at, plus every `chunk`). Both are prefixes of the same response, so the merge is "take
+ * the longer" — no diffing, no overlap handling, no ranges.
+ *
+ * The length comparison is the whole algorithm, which is why a caller MUST seed its accumulator with
+ * the text it joined at: a tail carrying only the chunks it received would read as shorter than the
+ * durable text and be discarded. `useStreamedText` does that for you.
+ */
+export declare function spliceStreamText(durable: string, produced: string): string;
+/**
+ * The durable half of the splice for the mapped-table layout: the compacted `body` followed by
+ * whatever chunk rows have not been folded into it yet.
+ *
+ * Chunks are ALWAYS the suffix after `body` — the closing checkpoint rewrites `body` and drops the
+ * chunks it absorbed in ONE transaction — so a reader never observes a torn state where a chunk both
+ * is and is not in the body.
+ */
+export declare function assembleDurableText(message: {
+    body?: string | null;
+} | null | undefined, chunks?: ReadonlyArray<{
+    seq: number;
+    text: string;
+}>): string;
+//# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAUA;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,WAAW,GAAG,OAAO,GAAG,aAAa,CAAC;AAE9E,oEAAoE;AACpE,eAAO,MAAM,uBAAuB,cAAc,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW;AACrB,0EAA0E;AACxE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AACnG,oFAAoF;GAClF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAC5D,oDAAoD;GAClD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AAClC,iCAAiC;GAC/B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AACpE;;6FAE6F;GAC3F;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE;AACzD;0DAC0D;GACxD;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEvB;iGACiG;AACjG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAWvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EACpD,MAAM,GAAE,aAAa,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAM,GACxD,MAAM,CAGR"}

package/dist/stream.js

@@ -0,0 +1,52 @@
+// The LM stream plane's SHARED contract (designs/LM-STREAM-CHECKPOINT-DESIGN.md): the frame shapes
+// both ends speak, plus the two pure functions that reassemble a response from its two planes.
+//
+// This lives in `@rindle/client` rather than `@rindle/api-server` because BOTH tiers need it and the
+// browser must never pull the server package (sql-client, daemon-client, …) to read a stream.
+// `@rindle/api-server` re-exports every name here, so the server-side import path is unchanged.
+//
+// Nothing in this module has state, I/O, or a React dependency — the hook that drives a subscription
+// is `useStreamedText` in `@rindle/react`; the transport is the app's choice.
+/** The value in the mapped status column while a stream is live. */
+export const STREAM_STATUS_STREAMING = "streaming";
+/** The resume point a frame implies — what rides an SSE `id:` line so a reconnecting `EventSource`
+ *  hands it straight back as `Last-Event-ID`. `undefined` for frames that are not a position. */
+export function frameResumePoint(frame) {
+    switch (frame.type) {
+        case "open":
+            return frame.from;
+        case "chunk":
+        case "durable":
+        case "end":
+            return frame.seq;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Merge the durable plane with the live tail.
+ *
+ * `durable` is what the IVM view shows; `produced` is what a subscription has accumulated (the prefix
+ * it joined at, plus every `chunk`). Both are prefixes of the same response, so the merge is "take
+ * the longer" — no diffing, no overlap handling, no ranges.
+ *
+ * The length comparison is the whole algorithm, which is why a caller MUST seed its accumulator with
+ * the text it joined at: a tail carrying only the chunks it received would read as shorter than the
+ * durable text and be discarded. `useStreamedText` does that for you.
+ */
+export function spliceStreamText(durable, produced) {
+    return produced.length > durable.length ? durable + produced.slice(durable.length) : durable;
+}
+/**
+ * The durable half of the splice for the mapped-table layout: the compacted `body` followed by
+ * whatever chunk rows have not been folded into it yet.
+ *
+ * Chunks are ALWAYS the suffix after `body` — the closing checkpoint rewrites `body` and drops the
+ * chunks it absorbed in ONE transaction — so a reader never observes a torn state where a chunk both
+ * is and is not in the body.
+ */
+export function assembleDurableText(message, chunks = []) {
+    const ordered = [...chunks].sort((a, b) => a.seq - b.seq);
+    return (message?.body ?? "") + ordered.map((c) => c.text).join("");
+}
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,+FAA+F;AAC/F,EAAE;AACF,qGAAqG;AACrG,8FAA8F;AAC9F,gGAAgG;AAChG,EAAE;AACF,qGAAqG;AACrG,8EAA8E;AAY9E,oEAAoE;AACpE,MAAM,CAAC,MAAM,uBAAuB,GAAG,WAAW,CAAC;AA2BnD;iGACiG;AACjG,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,KAAK,CAAC,IAAI,CAAC;QACpB,KAAK,OAAO,CAAC;QACb,KAAK,SAAS,CAAC;QACf,KAAK,KAAK;YACR,OAAO,KAAK,CAAC,GAAG,CAAC;QACnB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,QAAgB;IAChE,OAAO,QAAQ,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAC/F,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAoD,EACpD,SAAuD,EAAE;IAEzD,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1D,OAAO,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACrE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rindle/client",
-  "version": "0.7.11",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -43,6 +43,17 @@ export type {
 
 export { stableKey } from "./key.ts"; // canonical viewKey for an AST (shared with @rindle/react)
 
+// The LM stream plane's shared contract (LM-STREAM-CHECKPOINT-DESIGN.md): frame shapes + the two pure
+// reassembly functions. Lives here because BOTH tiers need them — `@rindle/api-server` re-exports
+// every name, and `@rindle/react`'s `useStreamedText` builds on them without a server import.
+export {
+  STREAM_STATUS_STREAMING,
+  assembleDurableText,
+  frameResumePoint,
+  spliceStreamText,
+} from "./stream.ts";
+export type { StreamFrame, StreamStatus } from "./stream.ts";
+
 export { COMPARATOR_VERSION, compareNumber, compareRows, compareString, compareValue } from "./compare.ts";
 
 export type {

package/src/stream.ts

@@ -0,0 +1,93 @@
+// The LM stream plane's SHARED contract (designs/LM-STREAM-CHECKPOINT-DESIGN.md): the frame shapes
+// both ends speak, plus the two pure functions that reassemble a response from its two planes.
+//
+// This lives in `@rindle/client` rather than `@rindle/api-server` because BOTH tiers need it and the
+// browser must never pull the server package (sql-client, daemon-client, …) to read a stream.
+// `@rindle/api-server` re-exports every name here, so the server-side import path is unchanged.
+//
+// Nothing in this module has state, I/O, or a React dependency — the hook that drives a subscription
+// is `useStreamedText` in `@rindle/react`; the transport is the app's choice.
+
+/**
+ * How a stream ended.
+ * - `complete` — the model finished.
+ * - `cancelled` — the reader asked it to stop and the producer honoured it.
+ * - `error` — the generation threw.
+ * - `interrupted` — the host went away mid-generation. The one status that implies the store may be
+ *   short of what was produced.
+ */
+export type StreamStatus = "complete" | "cancelled" | "error" | "interrupted";
+
+/** The value in the mapped status column while a stream is live. */
+export const STREAM_STATUS_STREAMING = "streaming";
+
+/**
+ * One frame of a subscription. A subscription always begins with `open` and always ends with exactly
+ * one terminal frame — `end`, `stale`, or `absent` — after which the iterator completes.
+ *
+ * `stale` and `absent` are the two "you are on the durable plane now" answers, and both are SAFE:
+ * the store holds everything below `floorSeq` and everything through `durableSeq`, so the reader's
+ * IVM view converges without the stream. Neither is an error.
+ */
+export type StreamFrame =
+  /** Join accepted. `from` is the (clamped) offset the replay starts at. */
+  | { type: "open"; streamId: string; from: number; seq: number; durableSeq: number; ended: boolean }
+  /** PRODUCED text — not a durability claim. `text.length === seq - from`, always. */
+  | { type: "chunk"; from: number; seq: number; text: string }
+  /** The store now holds the prefix through `seq`. */
+  | { type: "durable"; seq: number }
+  /** Sealed. No further frames. */
+  | { type: "end"; seq: number; status: StreamStatus; error?: string }
+  /** `from` is below the producer's retained buffer floor (or the subscriber fell too far behind):
+   *  read the store. (A raw `EventSource` rejoins automatically on its reconnect; `useStreamedText`
+   *  deliberately stays on the durable plane instead — correct, at checkpoint granularity.) */
+  | { type: "stale"; floorSeq: number; durableSeq: number }
+  /** The process serving this subscribe is not hosting the stream (wrong instance, already evicted,
+   *  or it never existed): the store is the whole truth. */
+  | { type: "absent" };
+
+/** The resume point a frame implies — what rides an SSE `id:` line so a reconnecting `EventSource`
+ *  hands it straight back as `Last-Event-ID`. `undefined` for frames that are not a position. */
+export function frameResumePoint(frame: StreamFrame): number | undefined {
+  switch (frame.type) {
+    case "open":
+      return frame.from;
+    case "chunk":
+    case "durable":
+    case "end":
+      return frame.seq;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Merge the durable plane with the live tail.
+ *
+ * `durable` is what the IVM view shows; `produced` is what a subscription has accumulated (the prefix
+ * it joined at, plus every `chunk`). Both are prefixes of the same response, so the merge is "take
+ * the longer" — no diffing, no overlap handling, no ranges.
+ *
+ * The length comparison is the whole algorithm, which is why a caller MUST seed its accumulator with
+ * the text it joined at: a tail carrying only the chunks it received would read as shorter than the
+ * durable text and be discarded. `useStreamedText` does that for you.
+ */
+export function spliceStreamText(durable: string, produced: string): string {
+  return produced.length > durable.length ? durable + produced.slice(durable.length) : durable;
+}
+
+/**
+ * The durable half of the splice for the mapped-table layout: the compacted `body` followed by
+ * whatever chunk rows have not been folded into it yet.
+ *
+ * Chunks are ALWAYS the suffix after `body` — the closing checkpoint rewrites `body` and drops the
+ * chunks it absorbed in ONE transaction — so a reader never observes a torn state where a chunk both
+ * is and is not in the body.
+ */
+export function assembleDurableText(
+  message: { body?: string | null } | null | undefined,
+  chunks: ReadonlyArray<{ seq: number; text: string }> = [],
+): string {
+  const ordered = [...chunks].sort((a, b) => a.seq - b.seq);
+  return (message?.body ?? "") + ordered.map((c) => c.text).join("");
+}