@rindle/api-server 0.8.0 → 0.10.0

package/dist/streams.d.ts

@@ -138,6 +138,38 @@ export interface AuthorizeStreamInput<User> {
     meta: unknown;
     request?: unknown;
 }
+/**
+ * Optional cross-process transport for the LIVE plane
+ * (designs-implemented/LM-STREAM-RELAY-DESIGN.md). Both methods are independently optional; which
+ * ones you implement is which topology you built — an addressing adapter (a Durable Object named by
+ * `streamId`, `fly-replay`) implements only `attach`; a broadcast adapter (Redis pub/sub, NATS)
+ * mirrors with `publish` and subscribes with `attach`; a log adapter (Redis Streams, Kafka) appends
+ * and replays. Never consulted for the durable plane — checkpoints are unaffected by any of this.
+ *
+ * The plane does not trust what `attach` yields: frames are run through the conform pass
+ * ({@link StreamRelayConform}) and any contract violation downgrades the subscription to `stale`,
+ * which already means "you are on the durable plane now". A broken relay costs a reader smooth
+ * tokens, never corrupted text — and can never reach the producer.
+ */
+export interface StreamRelay {
+    /** Producer side: every frame this process's producer fans out (`chunk`, `durable`, and the
+     *  terminal `end`), mirrored outward. MUST NOT block; a throw or rejected promise is caught and
+     *  routed to {@link RindleStreamOptions.onRelayError} — a relay outage may cost the live leg,
+     *  never the generation. Returned promises are observed but never awaited. */
+    publish?(streamId: string, frame: StreamFrame): void | PromiseLike<void>;
+    /** Subscriber side: this process is not hosting `streamId`. Return a frame source, or `undefined`
+     *  for `absent` — exactly the no-relay answer. Consulted only AFTER `authorize` has passed, and
+     *  only on a live-plane miss (a local stream always wins). The plane closes the source
+     *  (`return()`) when the reader disconnects. An adapter that cannot serve `from` (pub/sub has no
+     *  history) yields `stale` and stops — the reader converges on the durable plane (§5). */
+    attach?(streamId: string, from: number): Promise<AsyncIterable<StreamFrame> | undefined>;
+}
+export interface StreamRelayErrorInfo {
+    streamId: string;
+    /** Where it failed: mirroring a frame out (`publish`), dialing the adapter (`attach`), or
+     *  consuming/conforming its frames (`frames`). */
+    phase: "publish" | "attach" | "frames";
+}
 export interface RindleStreamOptions<User> {
     /** Where checkpoints land: the app's tables (the default path) or a raw `commit` callback. */
     checkpoint: StreamCheckpointTarget;
@@ -160,7 +192,9 @@ export interface RindleStreamOptions<User> {
     retainChars?: number;
     /** How long a sealed stream stays joinable before eviction. Default 30s. */
     lingerMs?: number;
-    /** Per-subscriber frame queue cap; overflow drops that subscriber with `stale` (§4). Default 1024. */
+    /** Per-subscriber frame queue cap; overflow drops that subscriber with `stale` (§4). Default 1024.
+     *  Relayed readers reuse the same bound: a slow reader on a relayed stream costs itself the live
+     *  leg exactly as a local one does. */
     maxQueuedFrames?: number;
     /** A checkpoint that exhausted its retries. The stream keeps streaming — this is a durability
      *  stall, not a stream stall — so the error must not vanish. Absent ⇒ `console.error`. */
@@ -169,6 +203,19 @@ export interface RindleStreamOptions<User> {
         from: number;
         seq: number;
     }) => void;
+    /** Cross-process transport for the live plane ({@link StreamRelay}). Without one, a subscriber
+     *  that lands on a process not hosting its stream gets `absent` and reads the durable plane at
+     *  checkpoint granularity — correct, just chunky. */
+    relay?: StreamRelay;
+    /** Bound on `relay.attach`: a hung adapter yields `absent`, not a hung HTTP request. An
+     *  addressing adapter MAY deliberately spend this window waiting out a subscribe that races its
+     *  own kick. Default 2000. */
+    relayAttachTimeoutMs?: number;
+    /** A diagnostic, never a control path: relay failures (a throwing or rejecting `publish`, a failed
+     *  or timed-out `attach`, a conform violation in the frames) land here, wrapped so a throwing hook
+     *  cannot reach the plane. The reader-facing outcome is always the same legal `absent`/`stale`.
+     *  Absent ⇒ `console.error`. */
+    onRelayError?: (err: unknown, info: StreamRelayErrorInfo) => void;
 }
 export interface OpenStreamInput<User> {
     user: User;
@@ -245,6 +292,49 @@ export declare function streamChunkId(streamId: string, seq: number): string;
  * generated rather than hand-written.
  */
 export declare function streamChunkTableDdl(tables: StreamTables, dialect: SqlDialect): string[];
+/**
+ * One frame source arriving over a relay, conformed to the CP §4 contract
+ * (designs-implemented/LM-STREAM-RELAY-DESIGN.md §4).
+ *
+ * An adapter is app code talking to Redis or a socket, and its frames feed `spliceStreamText` on a
+ * browser — so the plane does not trust them. This pass enforces the frame invariants against the
+ * prefix actually delivered and downgrades EVERY violation to a legal `stale` and nothing else:
+ * `stale` already means "you are on the durable plane now, the store is the whole truth", so a
+ * broken relay costs a reader smooth tokens, never corrupted text — and cannot wedge a producer.
+ *
+ * Replayed spans (a reconnecting adapter re-delivering what it already sent) are ABSORBED rather
+ * than punished — deduping against the delivered prefix is what makes reconnect-replay safe without
+ * every adapter hand-rolling it. Spans that overlap the prefix but extend past it pass through
+ * whole: the client splices at the frame's own offset, so an exact overlap re-covers and appends.
+ *
+ * Pure state, no I/O, no plane: `feed` maps one incoming frame to 0-2 outgoing frames (a missing
+ * `open` is synthesized at the join offset); `end`/`fail` close out a source that finished or threw
+ * without a terminal. After a terminal, every method returns `[]`.
+ */
+export declare class StreamRelayConform {
+    private readonly streamId;
+    /** The requested join offset — the synthesized `open`'s position, and where the prefix starts. */
+    private readonly from;
+    private readonly onViolation;
+    /** End of the delivered prefix. */
+    private pos;
+    private lastDurable;
+    private opened;
+    private done;
+    constructor(streamId: string, from: number, onViolation?: (reason: string) => void);
+    feed(frame: StreamFrame): StreamFrame[];
+    /** The source completed without a terminal (a truncated relay): the reader falls back. */
+    end(): StreamFrame[];
+    /** The source threw mid-iteration, or the plane is dropping a reader that stopped draining:
+     *  a bare `stale` at the delivered position. */
+    fail(): StreamFrame[];
+    /** A synthesized join, for an adapter that (correctly, in broadcast mode) never mirrors the
+     *  per-subscriber `open`: positioned at the requested offset, which the reader asked from because
+     *  its durable view already holds it. */
+    private synthOpen;
+    private terminate;
+    private violate;
+}
 /** What the plane needs from the api-server to write a checkpoint: the backend's OUTSIDE-transaction
  *  SQL surface (`batch` is one transaction on every backend) and its dialect. Deliberately narrow so
  *  `streams.ts` never imports the server (no cycle). */
@@ -259,7 +349,10 @@ export declare class StreamPlane<User> {
     readonly retainChars: number;
     readonly lingerMs: number;
     readonly maxQueuedFrames: number;
+    readonly relayAttachTimeoutMs: number;
     private readonly live;
+    /** Live relayed subscriptions, so teardown ({@link closeSync}) releases their drivers too. */
+    private readonly relayed;
     private readonly opts;
     private readonly sink;
     private readonly mapped;
@@ -290,6 +383,24 @@ export declare class StreamPlane<User> {
      */
     private assertOpenable;
     subscribe(input: SubscribeStreamInput<User>): Promise<StreamSubscription>;
+    /** The subscribe-miss leg (LM-STREAM-RELAY §3): ask the app's relay for the frames of a stream
+     *  this process is not hosting. `undefined` — no relay, no `attach`, the adapter declined, timed
+     *  out, or threw — is `absent`, exactly today's answer. */
+    private attachRelay;
+    /** `attach`, bounded by {@link RindleStreamOptions.relayAttachTimeoutMs}: a hung adapter yields
+     *  `absent`, not a hung HTTP request. A source that resolves after the deadline is closed, not
+     *  leaked. */
+    private boundedAttach;
+    /** Wrap an adapter's frame source as a plane subscription: conform every frame (LM-STREAM-RELAY
+     *  §4), bound the reader with the same queue cap as a local one (§7), and tear the adapter down
+     *  when either side lets go. The driver never throws into the plane: adapter failures become one
+     *  `stale`. */
+    private relaySubscription;
+    /** Mirror one producer frame outward (LM-STREAM-RELAY §3). Never blocks or breaks the producer:
+     *  a throw or rejected promise is reported and swallowed — a relay outage may cost relayed
+     *  readers the live leg, never the generation or its checkpoints. */
+    publishRelay(streamId: string, frame: StreamFrame): void;
+    reportRelayError(err: unknown, info: StreamRelayErrorInfo): void;
     /** Seal every live stream `interrupted`. In mapped-table mode the seal IS the compaction, so a
      *  graceful drain loses nothing PRODUCED; the status still says the response was cut short rather
      *  than claiming completion (§5). Wire it to SIGTERM. */

package/dist/streams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streams.d.ts","sourceRoot":"","sources":["../src/streams.ts"],"names":[],"mappings":"AAuCA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGhE,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAQpE,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAIhE,oGAAoG;AACpG,MAAM,MAAM,iBAAiB;AAC3B;2DAC2D;AACzD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AACvF;;;8FAG8F;GAC5F;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAC/E;;;;kGAIkG;GAChG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzI;;;;;;8FAM8F;AAC9F,MAAM,MAAM,YAAY,GAAG,CACzB,KAAK,EAAE,iBAAiB,KACrB,OAAO,CAAC,IAAI,GAAG;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjE;;sDAEsD;AACtD,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qGAAqG;IACrG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;mDAC+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;wFAGoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,YAAY;IAC3B,gGAAgG;IAChG,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,MAAM,sBAAsB,GAAG;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC;AAIzF;6EAC6E;AAC7E,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB,CAAC,IAAI;IACxC,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb;2FACuF;IACvF,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB,CAAC,IAAI;IACvC,8FAA8F;IAC9F,UAAU,EAAE,sBAAsB,CAAC;IACnC;gGAC4F;IAC5F,SAAS,EAAE,UAAU,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC;IAClD,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC;;;;;;2CAMuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;uGAGmG;IACnG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;8FAC0F;IAC1F,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACnG;AAID,MAAM,WAAW,eAAe,CAAC,IAAI;IACnC,IAAI,EAAE,IAAI,CAAC;IACX;8FAC0F;IAC1F,QAAQ,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;yDACqD;IACrD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,mFAAmF;IACnF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;sGAEkG;IAClG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB;;gCAE4B;IAC5B,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD;;oFAEgF;IAChF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,wFAAwF;IACxF,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,oBAAoB,CAAC,IAAI;IACxC,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB;6CACyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC5C,wDAAwD;IACxD,KAAK,IAAI,IAAI,CAAC;CACf;AA0CD,6FAA6F;AAC7F,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,qBAAqB,CAc9F;AAUD;2FAC2F;AAC3F,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,GAAG,MAAM,EAAE,CAcvF;AA2hBD;;wDAEwD;AACxD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;CACzB;AAED,qBAAa,WAAW,CAAC,IAAI;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuC;IAC5D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD;8BAC0B;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,IAAI,EAAE,mBAAmB,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,aAAa;IA8BjE;;iEAE6D;IACvD,IAAI,CAAC,KAAK,EAAE,eAAe,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC;IA6C/D;;;;;;;;;;;;;;;OAeG;YACW,cAAc;IAuCtB,SAAS,CAAC,KAAK,EAAE,oBAAoB,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgB/E;;6DAEyD;IACnD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC,0FAA0F;IAC1F,SAAS,IAAI,IAAI;IAKjB;iFAC6E;IAC7E,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAU9B,qBAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAWhG;;;yBAGqB;IACf,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,eAAe,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;YAcrF,UAAU;IAoCxB;;;;;8BAK0B;YACZ,gBAAgB;IAa9B;;;;kGAI8F;YAChF,eAAe;IAW7B;;8FAE0F;IACpF,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAQrE;AAED;gGACgG;AAChG,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED;;kDAEkD;AAClD,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;CAK7B;AAyBD;iFACiF;AACjF,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAKrD,CAAC;AAEF;;mFAEmF;AACnF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAC/C,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAOrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,kBAAkB,EACvB,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9B,cAAc,CAAC,UAAU,CAAC,CAuC5B"}
+{"version":3,"file":"streams.d.ts","sourceRoot":"","sources":["../src/streams.ts"],"names":[],"mappings":"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"}

package/dist/streams.js

@@ -1,4 +1,4 @@
-// LM stream checkpointing — the two-plane response path (designs/LM-STREAM-CHECKPOINT-DESIGN.md).
+// LM stream checkpointing — the two-plane response path (designs-implemented/LM-STREAM-CHECKPOINT-DESIGN.md).
 //
 // A model response arrives as hundreds of tiny deltas per second. Every one wants to be on a screen
 // immediately; none wants to be a durable write. So the response runs on TWO planes sharing ONE
@@ -49,6 +49,7 @@ const DEFAULT_CHECKPOINT_RETRIES = 3;
 const DEFAULT_RETAIN_CHARS = 64 * 1024;
 const DEFAULT_LINGER_MS = 30_000;
 const DEFAULT_MAX_QUEUED_FRAMES = 1024;
+const DEFAULT_RELAY_ATTACH_TIMEOUT_MS = 2000;
 /** Retry backoff base — 50ms, 100ms, 200ms, … A checkpoint failure is usually a blip at the write
  *  authority; the text is safe in the buffer meanwhile, so there is nothing to rush. */
 const RETRY_BACKOFF_MS = 50;
@@ -303,6 +304,148 @@ class Subscriber {
         };
     }
 }
+// ------------------------------------------------------------------------------- the relay conform pass
+/**
+ * One frame source arriving over a relay, conformed to the CP §4 contract
+ * (designs-implemented/LM-STREAM-RELAY-DESIGN.md §4).
+ *
+ * An adapter is app code talking to Redis or a socket, and its frames feed `spliceStreamText` on a
+ * browser — so the plane does not trust them. This pass enforces the frame invariants against the
+ * prefix actually delivered and downgrades EVERY violation to a legal `stale` and nothing else:
+ * `stale` already means "you are on the durable plane now, the store is the whole truth", so a
+ * broken relay costs a reader smooth tokens, never corrupted text — and cannot wedge a producer.
+ *
+ * Replayed spans (a reconnecting adapter re-delivering what it already sent) are ABSORBED rather
+ * than punished — deduping against the delivered prefix is what makes reconnect-replay safe without
+ * every adapter hand-rolling it. Spans that overlap the prefix but extend past it pass through
+ * whole: the client splices at the frame's own offset, so an exact overlap re-covers and appends.
+ *
+ * Pure state, no I/O, no plane: `feed` maps one incoming frame to 0-2 outgoing frames (a missing
+ * `open` is synthesized at the join offset); `end`/`fail` close out a source that finished or threw
+ * without a terminal. After a terminal, every method returns `[]`.
+ */
+export class StreamRelayConform {
+    streamId;
+    /** The requested join offset — the synthesized `open`'s position, and where the prefix starts. */
+    from;
+    onViolation;
+    /** End of the delivered prefix. */
+    pos;
+    lastDurable = 0;
+    opened = false;
+    done = false;
+    constructor(streamId, from, onViolation) {
+        this.streamId = streamId;
+        this.from = from;
+        this.pos = from;
+        this.onViolation = onViolation;
+    }
+    feed(frame) {
+        if (this.done)
+            return [];
+        switch (frame.type) {
+            case "open": {
+                if (this.opened)
+                    return []; // a reconnecting adapter's second open: absorbed
+                if (frame.streamId !== this.streamId ||
+                    !Number.isInteger(frame.from) ||
+                    !Number.isInteger(frame.seq) ||
+                    !Number.isInteger(frame.durableSeq) ||
+                    frame.from < 0 ||
+                    frame.seq < frame.from) {
+                    return this.violate(`relay open for ${JSON.stringify(frame.streamId)} at ${frame.from} is malformed`);
+                }
+                // An open PAST the requested offset is the adapter saying it cannot serve `from` (pub/sub
+                // has no history, §5): delivering it would leave a hole in the middle of the response, so
+                // the honest answer is the durable plane.
+                if (frame.from > this.from) {
+                    return this.violate(`relay open at ${frame.from} cannot serve the requested ${this.from}`);
+                }
+                this.opened = true;
+                this.pos = frame.from;
+                return [frame];
+            }
+            case "chunk": {
+                if (!Number.isInteger(frame.from) ||
+                    !Number.isInteger(frame.seq) ||
+                    frame.from < 0 ||
+                    typeof frame.text !== "string" ||
+                    frame.text.length !== frame.seq - frame.from) {
+                    return this.violate(`relay chunk ${frame.from}→${frame.seq} does not span exactly its offsets`);
+                }
+                if (frame.from > this.pos) {
+                    return this.violate(`relay chunk at ${frame.from} leaves a gap after ${this.pos}`);
+                }
+                if (frame.seq <= this.pos)
+                    return []; // entirely within the delivered prefix (a replay): absorbed
+                const out = this.opened ? [] : [this.synthOpen()];
+                this.pos = frame.seq;
+                out.push(frame);
+                return out;
+            }
+            case "durable": {
+                // Purely informational to a reader (the hook ignores it; SSE uses it as a resume id), so a
+                // claim that rewinds — or outruns what this subscription has SEEN produced, which P forbids
+                // — is dropped rather than downgraded.
+                if (!Number.isInteger(frame.seq) || frame.seq < this.lastDurable || frame.seq > this.pos)
+                    return [];
+                const out = this.opened ? [] : [this.synthOpen()];
+                this.lastDurable = frame.seq;
+                out.push(frame);
+                return out;
+            }
+            case "end": {
+                if (!Number.isInteger(frame.seq) || frame.seq < 0) {
+                    return this.violate(`relay end at ${String(frame.seq)} is malformed`);
+                }
+                // An `end` whose durable length outruns the delivered prefix means the adapter LOST text
+                // (durable never exceeds produced), so the reader is short and must not be told it saw
+                // everything. Downgrading keeps `end` meaning the same thing relayed as local: the whole
+                // produced text arrived.
+                if (frame.seq > this.pos) {
+                    return this.violate(`relay end at ${frame.seq} outruns the ${this.pos} characters delivered`);
+                }
+                this.done = true;
+                const out = this.opened ? [] : [this.synthOpen()];
+                out.push(frame);
+                return out;
+            }
+            case "stale":
+            case "absent": {
+                // Legal bare — the local plane's own floor/eviction answers carry no `open` either.
+                this.done = true;
+                return [frame];
+            }
+        }
+    }
+    /** The source completed without a terminal (a truncated relay): the reader falls back. */
+    end() {
+        if (this.done)
+            return [];
+        this.onViolation?.("relay source ended without a terminal frame");
+        return this.terminate();
+    }
+    /** The source threw mid-iteration, or the plane is dropping a reader that stopped draining:
+     *  a bare `stale` at the delivered position. */
+    fail() {
+        return this.done ? [] : this.terminate();
+    }
+    /** A synthesized join, for an adapter that (correctly, in broadcast mode) never mirrors the
+     *  per-subscriber `open`: positioned at the requested offset, which the reader asked from because
+     *  its durable view already holds it. */
+    synthOpen() {
+        this.opened = true;
+        return { type: "open", streamId: this.streamId, from: this.from, seq: this.from, durableSeq: this.from, ended: false };
+    }
+    terminate() {
+        this.done = true;
+        return [{ type: "stale", floorSeq: this.pos, durableSeq: this.lastDurable }];
+    }
+    violate(reason) {
+        this.onViolation?.(reason);
+        return this.terminate();
+    }
+}
 class LiveStream {
     /** Retained text; `buf[0]` sits at offset {@link bufFrom}. */
     buf = "";
@@ -541,6 +684,8 @@ class LiveStream {
             status: seal.status,
             ...(seal.error !== undefined ? { error: seal.error } : {}),
         };
+        // The terminal reaches the relay too (it bypasses `fanout` locally only to bypass the cap).
+        this.plane.publishRelay(this.streamId, frame);
         for (const sub of [...this.subs])
             sub.finish(frame);
         this.plane.retire(this.streamId);
@@ -587,6 +732,9 @@ class LiveStream {
     }
     // ---- subscriber side
     fanout(frame) {
+        // Every frame local subscribers get, the relay gets — including when nobody local is attached
+        // (a broadcast relay's whole point). Wrapped so an outage costs the live leg, never this stream.
+        this.plane.publishRelay(this.streamId, frame);
         for (const sub of [...this.subs]) {
             if (!sub.offer(frame)) {
                 // Bounded, then dropped: a reader that stopped draining costs itself a rejoin, never the
@@ -644,7 +792,10 @@ export class StreamPlane {
     retainChars;
     lingerMs;
     maxQueuedFrames;
+    relayAttachTimeoutMs;
     live = new Map();
+    /** Live relayed subscriptions, so teardown ({@link closeSync}) releases their drivers too. */
+    relayed = new Set();
     opts;
     sink;
     mapped;
@@ -660,7 +811,15 @@ export class StreamPlane {
         this.retries = opts.policy?.retries ?? DEFAULT_CHECKPOINT_RETRIES;
         this.lingerMs = opts.lingerMs ?? DEFAULT_LINGER_MS;
         this.maxQueuedFrames = opts.maxQueuedFrames ?? DEFAULT_MAX_QUEUED_FRAMES;
+        this.relayAttachTimeoutMs = opts.relayAttachTimeoutMs ?? DEFAULT_RELAY_ATTACH_TIMEOUT_MS;
         this.openToken = opts.hostId ?? randomOpenToken();
+        // Relay misconfiguration is refused loudly (the room-profile rule), never ignored.
+        if (opts.relay !== undefined && opts.relay.publish === undefined && opts.relay.attach === undefined) {
+            throw new TypeError("streams.relay implements neither publish nor attach — which topology is this? (LM-STREAM-RELAY §3.1)");
+        }
+        if (opts.relay === undefined && (opts.relayAttachTimeoutMs !== undefined || opts.onRelayError !== undefined)) {
+            throw new TypeError("streams.relayAttachTimeoutMs/onRelayError do nothing without streams.relay");
+        }
         if ("tables" in opts.checkpoint) {
             if (!sink)
                 throw new TypeError("streams.checkpoint.tables needs a SQL-capable mutation backend");
@@ -787,10 +946,162 @@ export class StreamPlane {
         });
         if (verdict === false)
             throw new StreamForbidden(input.streamId);
-        if (!stream)
-            return oneFrame(input.streamId, { type: "absent" });
+        if (!stream) {
+            // The relay is consulted only on a live-plane miss, and only after `authorize` passed — a
+            // denial must not become an existence probe against the relay either. A local stream always
+            // wins: the producer's own readers keep the lowest-latency path.
+            const relayed = await this.attachRelay(input.streamId, from);
+            return relayed ?? oneFrame(input.streamId, { type: "absent" });
+        }
         return stream.subscribe(from);
     }
+    /** The subscribe-miss leg (LM-STREAM-RELAY §3): ask the app's relay for the frames of a stream
+     *  this process is not hosting. `undefined` — no relay, no `attach`, the adapter declined, timed
+     *  out, or threw — is `absent`, exactly today's answer. */
+    async attachRelay(streamId, from) {
+        const relay = this.opts.relay;
+        if (relay?.attach === undefined)
+            return undefined;
+        // Floored like the local join, but clamped only below: the producer's length is not known here.
+        const at = Number.isFinite(from) ? Math.max(Math.floor(from), 0) : 0;
+        let source;
+        try {
+            source = await this.boundedAttach(relay, streamId, at);
+        }
+        catch (err) {
+            this.reportRelayError(err, { streamId, phase: "attach" });
+            return undefined;
+        }
+        if (source === undefined)
+            return undefined;
+        return this.relaySubscription(streamId, at, source);
+    }
+    /** `attach`, bounded by {@link RindleStreamOptions.relayAttachTimeoutMs}: a hung adapter yields
+     *  `absent`, not a hung HTTP request. A source that resolves after the deadline is closed, not
+     *  leaked. */
+    boundedAttach(relay, streamId, from) {
+        // `async` wrapping so a synchronously-throwing adapter is an attach failure, not a plane throw.
+        const attempt = (async () => relay.attach(streamId, from))();
+        return new Promise((resolve, reject) => {
+            let late = false;
+            const t = timer(() => {
+                late = true;
+                reject(new Error(`stream ${streamId}: relay.attach timed out after ${this.relayAttachTimeoutMs}ms`));
+            }, this.relayAttachTimeoutMs);
+            attempt.then((source) => {
+                clearTimeout(t);
+                if (!late)
+                    return resolve(source);
+                closeFrameSource(source); // too late to serve the reader; don't leak the channel
+            }, (err) => {
+                clearTimeout(t);
+                if (!late)
+                    reject(err);
+            });
+        });
+    }
+    /** Wrap an adapter's frame source as a plane subscription: conform every frame (LM-STREAM-RELAY
+     *  §4), bound the reader with the same queue cap as a local one (§7), and tear the adapter down
+     *  when either side lets go. The driver never throws into the plane: adapter failures become one
+     *  `stale`. */
+    relaySubscription(streamId, from, source) {
+        const conform = new StreamRelayConform(streamId, from, (reason) => this.reportRelayError(new Error(reason), { streamId, phase: "frames" }));
+        let closed = false;
+        let signalClose;
+        const closedP = new Promise((resolve) => (signalClose = resolve));
+        const closedTag = closedP.then(() => "closed");
+        const release = () => {
+            if (!closed) {
+                closed = true;
+                signalClose();
+            }
+        };
+        const sub = new Subscriber(this.maxQueuedFrames, (s) => {
+            this.relayed.delete(s);
+            release();
+        });
+        this.relayed.add(sub);
+        let it;
+        /** @returns false once the subscription finished (terminal delivered, or the reader dropped). */
+        const deliver = (frames) => {
+            for (const frame of frames) {
+                if (frame.type === "end" || frame.type === "stale" || frame.type === "absent") {
+                    sub.finish(frame);
+                    return false;
+                }
+                if (!sub.offer(frame)) {
+                    // The same bound as a local reader: a relayed subscriber that stops draining costs
+                    // itself the live leg, never unbounded memory.
+                    const [stale] = conform.fail();
+                    if (stale)
+                        sub.finish(stale);
+                    return false;
+                }
+            }
+            return true;
+        };
+        void (async () => {
+            try {
+                // Iterator construction is adapter code too: keep a throwing factory inside the same
+                // stale/report/cleanup boundary as a throwing `next()`.
+                it = source[Symbol.asyncIterator]();
+                for (;;) {
+                    // Raced rather than awaited bare: a reader disconnect must release this driver even when
+                    // the adapter never yields another frame (its own `return()` may be queued behind the
+                    // pending `next()` forever).
+                    const res = await Promise.race([it.next(), closedTag]);
+                    if (res === "closed")
+                        return;
+                    if (res.done) {
+                        deliver(conform.end());
+                        return;
+                    }
+                    if (!deliver(conform.feed(res.value)))
+                        return;
+                }
+            }
+            catch (err) {
+                this.reportRelayError(err, { streamId, phase: "frames" });
+                deliver(conform.fail());
+            }
+            finally {
+                release();
+                // If construction itself threw there is no iterator to return, and asking the source to
+                // construct a second one during cleanup could repeat side effects or throw again.
+                closeFrameSource(undefined, it);
+            }
+        })();
+        return { streamId, frames: sub.frames(), close: () => sub.close() };
+    }
+    /** Mirror one producer frame outward (LM-STREAM-RELAY §3). Never blocks or breaks the producer:
+     *  a throw or rejected promise is reported and swallowed — a relay outage may cost relayed
+     *  readers the live leg, never the generation or its checkpoints. */
+    publishRelay(streamId, frame) {
+        const relay = this.opts.relay;
+        if (relay?.publish === undefined)
+            return;
+        try {
+            const published = relay.publish(streamId, frame);
+            if (published !== undefined) {
+                void Promise.resolve(published).catch((err) => this.reportRelayError(err, { streamId, phase: "publish" }));
+            }
+        }
+        catch (err) {
+            this.reportRelayError(err, { streamId, phase: "publish" });
+        }
+    }
+    reportRelayError(err, info) {
+        // Same discipline as reportCheckpointError: a diagnostic must never take its caller down.
+        try {
+            if (this.opts.onRelayError)
+                this.opts.onRelayError(err, info);
+            else
+                console.error(`[rindle api-server] stream ${info.streamId}: relay ${info.phase} failed:`, err);
+        }
+        catch (hookErr) {
+            console.error(`[rindle api-server] stream ${info.streamId}: onRelayError itself threw:`, hookErr);
+        }
+    }
     /** Seal every live stream `interrupted`. In mapped-table mode the seal IS the compaction, so a
      *  graceful drain loses nothing PRODUCED; the status still says the response was cut short rather
      *  than claiming completion (§5). Wire it to SIGTERM. */
@@ -802,6 +1113,9 @@ export class StreamPlane {
         for (const s of this.live.values())
             s.detachAll();
         this.live.clear();
+        for (const s of [...this.relayed])
+            s.close();
+        this.relayed.clear();
     }
     /** A sealed stream stays joinable for the linger window, so a subscribe that races the last token
      *  still gets `end` (and the tail it missed) rather than a bare `absent`. */
@@ -950,6 +1264,18 @@ export class StreamForbidden extends Error {
         this.streamId = streamId;
     }
 }
+/** Best-effort adapter teardown (the `for await` discipline, by hand): never awaited into the
+ *  plane — a hung `return()` must not hold anything — and a synchronously-throwing one is the
+ *  adapter's bug, not the plane's problem. */
+function closeFrameSource(source, it) {
+    try {
+        const iter = it ?? source?.[Symbol.asyncIterator]();
+        void Promise.resolve(iter?.return?.()).catch(() => { });
+    }
+    catch {
+        // ignored — see above
+    }
+}
 function oneFrame(streamId, frame) {
     let taken = false;
     return {