@jarenjs/contract 0.49.2 → 0.66.1

package/dist/types/local/index.d.ts

@@ -39,9 +39,15 @@ export type OutcomeMeta = import('../client/outcome.js').OutcomeMeta;
 export type PipelineRoute = import('../pipeline.js').PipelineRoute;
 export type LocalOptions = {
     /**
-     * - the trace generator; default `crypto.randomUUID`
+     * - the trace generator; default the
+     * runtime record's `uuid`, itself `crypto.randomUUID` by default
      */
     trace?: () => string;
+    /**
+     * - the host's runtime record: its `uuid` generates the trace where
+     * `trace` is absent
+     */
+    runtime?: Partial<import('@jarenjs/core/runtime').Runtime>;
     /**
      * - `'never'` is a declared
      * downgrade, reported in `capabilities.validatedOutput`

package/dist/types/messages.d.ts

@@ -58,6 +58,8 @@ export declare const contractMessagesEn: Readonly<{
     'contract/seq-regression': "the stream of operation {op} violated its seq order";
     'contract/stream-error': "the stream of operation {op} ended with a server error ({code})";
     'contract/heartbeat-missed': "the stream of operation {op} went silent for {ms}ms";
+    'contract/slow-consumer': "the stream of operation {op} ended: the consumer fell behind its bounded queue";
+    'contract/reconnect-exhausted': "the stream of operation {op} could not be re-established after {attempts} attempts (last: {lastCode})";
 }>;
 /** The compiled English catalog (module-level singleton). */
 export declare const contractCatalogEn: Readonly<Record<string, (params: object, error?: object) => string>>;

package/dist/types/path.d.ts

@@ -65,8 +65,10 @@ export type ParsedPathTemplate = {
  */
 export declare function parsePathTemplate(source: unknown): ParsedPathTemplate;
 /**
- * The shape of a template with every variable normalized to `{}` — the
- * identity `JC0010` is decided on.
+ * The shape of a template with every variable normalized to `{}` and
+ * static delimiters re-escaped from decoded text — the identity `JC0010`
+ * is decided on. Escaped separators and braces stay inside their static
+ * segment, distinct from path boundaries and variable markers.
  * @param {ParsedPathTemplate} parsed
  * @returns {string}
  */

package/dist/types/pipeline.d.ts

@@ -114,7 +114,12 @@ export declare const PORT_LOCAL_ERRORS: Readonly<{
 }>;
 /**
  * A server trace id from a host generator. TOTAL: a generator that
- * throws or answers a non-string is replaced by the platform's UUID.
+ * throws or answers a non-string is replaced by the platform's UUID —
+ * the one last-resort platform read in this package, reached only when
+ * the injected generator (a `trace` option or the runtime record's
+ * `uuid`) has itself failed, so a request still carries a trace; a run
+ * whose generator fails was not the deterministic run the record
+ * configures, and the fallback says nothing about it.
  * @param {() => string} trace
  * @returns {string}
  */
@@ -130,6 +135,15 @@ export declare function safeTrace(trace: () => string): string;
  * @returns {OperationResult | null}
  */
 export declare function validateOperationInput(route: PipelineRoute, input: unknown): OperationResult | null;
+/**
+ * Classify a declared failure a HOST hook answered (`identify`/`acquire`,
+ * docs/CONTRACT-FORMAT.md §7.7): the same rules as a handler's `ctx.fail`
+ * — the code must be declared, the details must pass the declaration.
+ * @param {PipelineRoute} route
+ * @param {import('./errors.js').ContractFailureValue} failure
+ * @returns {OperationResult}
+ */
+export declare function classifyDeclared(route: PipelineRoute, failure: import('./errors.js').ContractFailureValue): OperationResult;
 /**
  * Call the handler through the uniform promise boundary and classify the
  * settlement. Never rejects; the returned promise always resolves an

package/dist/types/port/client.d.ts

@@ -43,6 +43,12 @@ export type PortClientOptions = {
      * - a message catalog consulted before the English one
      */
     catalog?: Record<string, string | ((params: object) => string)>;
+    /**
+     * - the host's runtime record: its `uuid` mints the client id every
+     * request id of this client is prefixed with; `crypto.randomUUID` by
+     * default
+     */
+    runtime?: Partial<import('@jarenjs/core/runtime').Runtime>;
 };
 export type PortInvokeContext = {
     /**
@@ -71,6 +77,9 @@ export type PortSubscribeOptions = {
     onSnapshot?: (value: unknown, info: {
         seq: number;
         resumed: boolean;
+        reset: boolean;
+        earliestAvailable: number | null;
+        highWatermark: number | null;
     }) => void;
     onPatch?: (emission: {
         patch: unknown[];
@@ -85,9 +94,17 @@ export type PortSubscribeOptions = {
      */
     signal?: AbortSignal;
     /**
-     * - the resume seq (what a reconnect passes)
+     * - the resume seq (what a re-entered subscribe passes)
      */
     lastSeq?: number;
+    /**
+     * - validated as on the HTTP client, then
+     * nothing: a channel has no network loss to reconnect from (a closed channel is
+     * `JC2074`, final), so the same options object serves both clients
+     */
+    reconnect?: {
+        max: number;
+    };
 };
 export type PortClient = {
     invoke: (op: string, input?: unknown, ctx?: PortInvokeContext) => Promise<Outcome>;

package/dist/types/port/serve.d.ts

@@ -34,7 +34,8 @@ export type ServePortOptions = {
      */
     channel: ChannelLike;
     /**
-     * - the server trace generator; default `crypto.randomUUID`
+     * - the server trace generator; default
+     * the runtime record's `uuid`, itself `crypto.randomUUID` by default
      */
     trace?: () => string;
     /**
@@ -46,14 +47,46 @@ export type ServePortOptions = {
      * - a message catalog consulted before the English one
      */
     catalog?: Record<string, string | ((params: object) => string)>;
-    /**
-     * - observes the cause behind every `JC2070` frame, validator throws
-     * and a channel whose `postMessage` throws
-     */
     onError?: (error: unknown, ctx: {
         op: string;
         trace: string;
     } | null) => void;
+    /**
+     * - the host lifecycle's first hook (docs/CONTRACT-FORMAT.md §7.7), run
+     * after the operation resolved and before the input is validated;
+     * `meta.carrier` is `'port'` and the request-line members are `null`
+     */
+    identify?: (meta: import('../host.js').IdentifyMeta) => unknown;
+    /**
+     * - the second hook, run after the input validated; a `settlement` on
+     * its lease is accepted and unused — this binding carries no
+     * idempotency
+     * - observes the cause behind every `JC2070` frame, validator throws
+     * and a channel whose `postMessage` throws
+     */
+    acquire?: (input: unknown, identity: unknown, enter: (lease: unknown) => Promise<unknown>) => unknown;
+    /**
+     * - the host's runtime record: its `uuid` generates the server trace
+     * where `trace` is absent
+     */
+    runtime?: Partial<import('@jarenjs/core/runtime').Runtime>;
+    /**
+     * - the bounds of every push-frame stream (docs/CONTRACT-FORMAT.md
+     * §18.1): a replay page asks for at most `replay.limit` emissions /
+     * `replay.maxBytes` patch bytes (default 256 / 1 MiB); the undelivered
+     * queue holds at most `queue.events` frames / `queue.bytes` frame
+     * bytes (default 256 / 1 MiB) before the stream ends with `JC2096`
+     */
+    streamLimits?: {
+        replay?: {
+            limit?: number;
+            maxBytes?: number;
+        };
+        queue?: {
+            events?: number;
+            bytes?: number;
+        };
+    };
 };
 export type PortServerCapabilities = {
     name: 'port';

package/dist/types/project/tools.d.ts

@@ -24,7 +24,7 @@ export type ToolDefinition = {
     execute: (args: any) => any;
 };
 export type ToolClient = {
-    invoke: (op: string, input: any, ctx?: any) => any;
+    invoke(op: string, input: any, ctx?: any): any;
 };
 export type ContractToolsOptions = {
     /**

package/dist/types/project/typescript.d.ts

@@ -22,6 +22,17 @@
  * stylesheet — the D6 shapes as every binding carries them
  * (`OUTCOME_META_MEMBERS` / `OUTCOME_ERROR_MEMBERS` in the client module
  * are the runtime twins; a test holds the text to them).
+ *
+ * One convention rides on top of emit's reading, the suite's: a string
+ * with `format: "date-time"` or `format: "date"` is the `DateTime`
+ * brand, so a consumer's generated types agree with `@jarenjs/db`'s
+ * entity types (`entityEmitModel`) and `@jarenjs/linq`'s schema pen,
+ * which both read a date format that way. Emit itself records a format
+ * only as a dropped constraint, so the brand is applied HERE, by
+ * rewriting date-formatted string nodes to a `$ref` of one shared
+ * definition before emit reads the document — in every position, an
+ * array item as much as a member — and giving that definition the brand
+ * intersection.
  */
 export type Contract = import('../compile.js').Contract;
 export type CompiledOperation = import('../compile.js').CompiledOperation;

package/dist/types/runtime.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file The one place a contract binding reads its `runtime` option:
+ * the record is resolved through `@jarenjs/core/runtime` — nothing given
+ * is the platform's own clock, identifier and source — and a malformed
+ * record is refused as the binding's OWN host error (`JC1001` for a
+ * server, `JC1008` for a client), naming the option, so the refusal
+ * reads like every other option refusal of that constructor. Every
+ * binding then takes its host facts from the record only where its
+ * explicit option (`trace`, `keys`, `now`) is absent: the record
+ * injects, it never replaces a published option.
+ */
+export type Runtime = import('@jarenjs/core/runtime').Runtime;
+/**
+ * @typedef {import('@jarenjs/core/runtime').Runtime} Runtime
+ */
+/**
+ * Resolve a binding's `options.runtime`, or refuse it as that binding's
+ * host error under the code it refuses every malformed option with.
+ * @param {Partial<Runtime> | undefined | null} candidate - `options.runtime`
+ * @param {(code: any, reason: string) => Error} host - the binding's host
+ *   error constructor
+ * @param {'JC1001' | 'JC1008'} code - the binding's malformed-option code
+ * @returns {Readonly<Runtime>}
+ */
+export declare function resolveHostRuntime(candidate: Partial<Runtime> | undefined | null, host: (code: any, reason: string) => Error, code: 'JC1001' | 'JC1008'): Readonly<Runtime>;

package/dist/types/stream/client.d.ts

@@ -21,6 +21,9 @@ export type StreamCallbacks = {
     onSnapshot?: (value: unknown, info: {
         seq: number;
         resumed: boolean;
+        reset: boolean;
+        earliestAvailable: number | null;
+        highWatermark: number | null;
     }) => void;
     onPatch?: (emission: {
         patch: unknown[];
@@ -60,8 +63,12 @@ export type StreamConsumerOptions = {
  */
 /**
  * The callbacks of one `client.subscribe` call; every one optional.
+ * `onSnapshot`'s `info` is stable in shape: `reset` says the snapshot
+ * re-seeds a consumer whose cursor fell behind the server's retention
+ * (its `seq` is then the cursor to resume from), and the two watermarks
+ * are the server log's when it reported them (`null` on a fresh stream).
  * @typedef {Object} StreamCallbacks
- * @property {(value: unknown, info: { seq: number, resumed: boolean }) => void} [onSnapshot]
+ * @property {(value: unknown, info: { seq: number, resumed: boolean, reset: boolean, earliestAvailable: number | null, highWatermark: number | null }) => void} [onSnapshot]
  * @property {(emission: { patch: unknown[], seq: number }) => void} [onPatch]
  * @property {(outcome: Outcome) => void} [onError]
  * @property {(info: { reason: string }) => void} [onEnd]
@@ -82,7 +89,9 @@ export type StreamConsumerOptions = {
  * wire carried (the SSE id, the frame's `seq`) — `null` falls back to
  * the data's own `seq`; `error`/`end` take the event data; `fail` takes
  * a ready outcome (a transport failure the carrier classified). All are
- * no-ops once finished.
+ * no-ops once finished. `lastSeq` reads the cursor: the resume seq the
+ * caller passed until a snapshot or patch moves it — what a further
+ * attempt resumes from.
  * @param {StreamConsumerOptions} options
  * @returns {{ snapshot: (seq: number | null, data: unknown) => void,
  *   patch: (seq: number | null, data: unknown) => void,
@@ -90,7 +99,8 @@ export type StreamConsumerOptions = {
  *   end: (data: unknown) => void,
  *   fail: (outcome: Outcome) => void,
  *   cancel: () => void,
- *   finished: () => boolean }}
+ *   finished: () => boolean,
+ *   lastSeq: () => number | null }}
  */
 export declare function createStreamConsumer(options: StreamConsumerOptions): {
     snapshot: (seq: number | null, data: unknown) => void;
@@ -100,5 +110,6 @@ export declare function createStreamConsumer(options: StreamConsumerOptions): {
     fail: (outcome: Outcome) => void;
     cancel: () => void;
     finished: () => boolean;
+    lastSeq: () => number | null;
 };
 export { STREAM_ERRORS };

package/dist/types/stream/server.d.ts

@@ -2,39 +2,111 @@
  * @file The server half of the stream binding, carrier-neutral
  * (docs/CONTRACT-FORMAT.md §17–§18): take the subscription a handler
  * settled (the duck-typed LIVE shape — `result`/`snapshot()`,
- * `subscribe(cb) → stop`, `close()`, optional `replay(seq)`), decide
- * resumption, read and validate the snapshot, forward each emission,
- * and guarantee `stop()` then `close()` run **exactly once** however
- * the stream ends — peer disconnect, unsubscribe, server shutdown, an
- * error emission, an invalid snapshot. The HTTP dispatcher renders the
- * intents this module raises as SSE events; the port server renders
- * them as push frames — the sequencing is decided here once so the two
- * carriers can never disagree.
+ * `subscribe(cb) → stop`, `close()`, optional `replay(after, options)`),
+ * decide resumption, read and validate the snapshot, forward each
+ * emission, and guarantee `stop()` then `close()` run **exactly once**
+ * however the stream ends — peer disconnect, unsubscribe, server
+ * shutdown, an error emission, an invalid snapshot, a slow consumer.
+ * The HTTP dispatcher renders the intents this module raises as SSE
+ * events; the port server renders them as push frames — the sequencing
+ * is decided here once so the two carriers can never disagree.
+ *
+ * The carrier encodes, the runner decides. A hook answers the WIRE
+ * FRAME of one event (an SSE text, a port frame object) or `null` to
+ * skip it; the runner measures it through the carrier's `size`, charges
+ * it to ONE bounded queue, and writes it through the carrier's `write`
+ * one frame at a time, each behind the previous one's settlement (the
+ * suite's awaited-sink primitive): an emission that arrives while a
+ * write is pending — or while a replay page is loading — waits its turn
+ * in order, never overlapped, never dropped. A frame's count and bytes
+ * stay charged until its write settled, so a blocked write cannot hide
+ * memory outside the bound; when the next frame would cross either
+ * bound the stream ends with `JC2096` and the carrier is told to tear
+ * its sink down. A write that rejects means the carrier is gone (the
+ * peer dropped the socket, the consumer cancelled the stream): the
+ * runner releases silently.
+ *
+ * Replay is paged, never an array (§18.1): `replay(after, { limit,
+ * maxBytes, signal })` answers one `changes.page()`-shaped page —
+ * `{ items, next?, earliestAvailable, highWatermark, hasMore,
+ * resetRequired }` — validated defensively; the first page's
+ * `highWatermark` is the target, and paging stops there however busy
+ * the writer is. A page with `resetRequired` delivers no suffix: the
+ * runner reads a fresh snapshot and emits it with `reset: true`, both
+ * watermarks, and an event id no lower than any live emission already
+ * buffered, so a patch the snapshot already reflects is never replayed.
+ *
+ * A source's `stop()` and `close()` may answer promises; the runner's
+ * `done` settles only after stop, then close, then the carrier's `done`
+ * hook have all settled, once — the completion signal a host's
+ * finalizers wait on.
  *
  * Total for everything a handler's subscription can do: a throwing
  * `snapshot()`/`result` accessor, a `subscribe` that throws, a hostile
- * emission, a throwing `stop`/`close` — every one settles into the
- * `fault` intent (the cause for the binding's `onError`, never the
- * wire) or is swallowed at close, and the stream still terminates.
+ * emission, a malformed or rejecting page, a throwing `stop`/`close` —
+ * every one settles into the `error` intent (the cause for the
+ * binding's `onError`, never the wire) or is swallowed at close, and
+ * the stream still terminates.
  */
 export type PipelineRoute = import('../pipeline.js').PipelineRoute;
+export type ReplayOptions = {
+    limit: number;
+    maxBytes: number;
+    signal: AbortSignal;
+};
+export type ReplayPage = {
+    items: {
+        patch: unknown[];
+        seq: number;
+    }[];
+    next?: number;
+    earliestAvailable: number | null;
+    highWatermark: number;
+    hasMore: boolean;
+    resetRequired: boolean;
+};
 export type SubscriptionLike = {
     result?: unknown;
     snapshot?: () => unknown;
-    subscribe: (cb: (emission: any) => void) => (() => void);
-    close: () => void;
-    replay?: (seq: number) => unknown;
+    subscribe: (cb: (emission: any) => void) => (() => unknown);
+    close: () => unknown;
+    replay?: (after: number, options: ReplayOptions) => ReplayPage | null | undefined | Promise<ReplayPage | null | undefined>;
     mode?: unknown;
 };
-export type StreamHooks = {
-    snapshot: (seq: number, value: unknown, resumed: boolean) => void;
+export type SnapshotData = {
+    value: unknown;
+    resumed: boolean;
+    reset: boolean;
+    earliestAvailable: number | null;
+    highWatermark: number | null;
+};
+export type ErrorIntent = 'invalid-snapshot' | 'source' | 'slow-consumer' | 'declared';
+export type DeclaredStreamFailure = {
+    code: string;
+    details: unknown;
+    retryable: boolean;
+};
+export type StreamHooks<F = unknown> = {
+    snapshot: (seq: number, data: SnapshotData) => F | null;
     patch: (seq: number, emission: {
         patch: unknown[];
         seq: number;
-    }) => void;
-    error: (intent: 'invalid-snapshot' | 'source', cause: unknown, lastSeq: number) => void;
-    end: (reason: string, lastSeq: number) => void;
-    done: () => void;
+    }) => F | null;
+    error: (intent: ErrorIntent, cause: unknown, lastSeq: number, declared: DeclaredStreamFailure | null) => F | null;
+    end: (reason: string, lastSeq: number) => F | null;
+    size: (frame: F) => number;
+    write: (frame: F) => unknown;
+    done: (reason: 'slow-consumer' | null) => unknown;
+};
+export type StreamLimits = {
+    replay: {
+        limit: number;
+        maxBytes: number;
+    };
+    queue: {
+        events: number;
+        bytes: number;
+    };
 };
 export type StreamOptions = {
     /**
@@ -45,36 +117,140 @@ export type StreamOptions = {
      * - whether snapshots run the output validator
      */
     validate: boolean;
+    /**
+     * - the bounds; the defaults when absent
+     */
+    limits?: StreamLimits;
+};
+export type StreamRunner = {
+    stop: (reason: string | null) => void;
+    done: Promise<void>;
 };
 /**
  * @typedef {import('../pipeline.js').PipelineRoute} PipelineRoute
  */
 /**
- * The duck-typed subscription of docs/CONTRACT-FORMAT.md §17.1.
+ * The options of one replay page call (§18.1): at most `limit`
+ * emissions and `maxBytes` serialized patch bytes, and the runner's
+ * signal, aborted when the stream stops while the page is loading.
+ * @typedef {{ limit: number, maxBytes: number, signal: AbortSignal }} ReplayOptions
+ */
+/**
+ * One replay page, in the shape `@jarenjs/db`'s `changes.page()`
+ * answers: the emissions after `after` in seq order, `next` the seq to
+ * continue from, the log's two watermarks, whether more remain, and
+ * the total refusal `resetRequired` — under which `items` is empty and
+ * `next` absent.
+ * @typedef {{ items: { patch: unknown[], seq: number }[], next?: number,
+ *   earliestAvailable: number | null, highWatermark: number, hasMore: boolean,
+ *   resetRequired: boolean }} ReplayPage
+ */
+/**
+ * The duck-typed subscription of docs/CONTRACT-FORMAT.md §17.1. `stop`
+ * (what `subscribe` answers) and `close` may answer a promise; the
+ * runner awaits each before it reports completion. `replay` answers one
+ * page per call, value or promise.
  * @typedef {{ result?: unknown, snapshot?: () => unknown,
- *   subscribe: (cb: (emission: any) => void) => (() => void),
- *   close: () => void, replay?: (seq: number) => unknown, mode?: unknown }} SubscriptionLike
+ *   subscribe: (cb: (emission: any) => void) => (() => unknown),
+ *   close: () => unknown,
+ *   replay?: (after: number, options: ReplayOptions) => ReplayPage | null | undefined | Promise<ReplayPage | null | undefined>,
+ *   mode?: unknown }} SubscriptionLike
+ */
+/**
+ * The data of a snapshot event (§18.1): the validated document, whether
+ * the stream resumed (never, today: a resumed stream starts with
+ * patches), whether this snapshot re-seeds a consumer whose cursor fell
+ * behind the log's retention (`reset`), and the log's watermarks as the
+ * replay source reported them (`null` on a fresh stream).
+ * @typedef {{ value: unknown, resumed: boolean, reset: boolean,
+ *   earliestAvailable: number | null, highWatermark: number | null }} SnapshotData
+ */
+/**
+ * The reasons a stream ends with an `error` event: `'invalid-snapshot'`
+ * (send `JC2091`), `'source'` (the subscription emitted `{ error }`
+ * with no declared code, or a page/subscribe/snapshot fault — send the
+ * host fault code), `'slow-consumer'` (the bounded queue would overflow
+ * — send `JC2096`), `'declared'` (the subscription emitted `{ error }`
+ * whose `code` the operation declares — send that code as the declared
+ * failure it is, with the {@link DeclaredStreamFailure} the runner
+ * classified).
+ * @typedef {'invalid-snapshot' | 'source' | 'slow-consumer' | 'declared'} ErrorIntent
+ */
+/**
+ * A source error the operation declares (§17.1): the declared `code`,
+ * JSON-safe `details` when the error carried some (`undefined`
+ * otherwise), and `retryable` — the error's own boolean, else whether
+ * `policy.retry.on` names the code. Nothing of the error's message or
+ * stack is here: the carrier renders the operation's declared message.
+ * @typedef {{ code: string, details: unknown, retryable: boolean }} DeclaredStreamFailure
  */
 /**
- * What the carrier renders. Every hook is called at most once per
- * event, in wire order; after `error` or `end` no further hook fires.
- * `error` carries the intent (`'invalid-snapshot'` — send `JC2091`;
- * `'source'` — the subscription emitted `{ error }`, send the host
- * fault code) and the cause for the observer. `done` fires exactly once
- * after the stream terminated for any reason — the carrier releases
- * its resources (timers, registries) there.
+ * What the carrier renders, as FRAMES. Each event hook answers the wire
+ * frame of one event — the SSE text, the port frame — or `null` to skip
+ * it (a frame the wire cannot carry, observed by the carrier). The
+ * runner measures a frame with `size` (its bytes on the wire), charges
+ * it to the bounded queue, and writes it with `write`, one at a time,
+ * each behind the previous write's settlement; `write` may answer a
+ * promise. After the `error` or `end` frame no further frame is
+ * written. A `write` that throws or rejects is read as "the carrier can
+ * no longer deliver": the subscription is released silently. `done`
+ * fires exactly once after the stream terminated for any reason, with
+ * `'slow-consumer'` when the queue overflowed — the carrier tears its
+ * sink down instead of ending it — else `null`; the carrier releases
+ * its resources (timers, registries, the sink) there.
+ * @template [F=unknown]
  * @typedef {Object} StreamHooks
- * @property {(seq: number, value: unknown, resumed: boolean) => void} snapshot
- * @property {(seq: number, emission: { patch: unknown[], seq: number }) => void} patch
- * @property {(intent: 'invalid-snapshot' | 'source', cause: unknown, lastSeq: number) => void} error
- * @property {(reason: string, lastSeq: number) => void} end
- * @property {() => void} done
+ * @property {(seq: number, data: SnapshotData) => F | null} snapshot
+ * @property {(seq: number, emission: { patch: unknown[], seq: number }) => F | null} patch
+ * @property {(intent: ErrorIntent, cause: unknown, lastSeq: number, declared: DeclaredStreamFailure | null) => F | null} error
+ * @property {(reason: string, lastSeq: number) => F | null} end
+ * @property {(frame: F) => number} size
+ * @property {(frame: F) => unknown} write
+ * @property {(reason: 'slow-consumer' | null) => unknown} done
+ */
+/**
+ * The bounds of one stream (§18.1): a replay page asks for at most
+ * `replay.limit` emissions and `replay.maxBytes` serialized patch
+ * bytes; the queue holds at most `queue.events` undelivered frames and
+ * `queue.bytes` of their wire bytes.
+ * @typedef {{ replay: { limit: number, maxBytes: number }, queue: { events: number, bytes: number } }} StreamLimits
  */
 /**
  * @typedef {Object} StreamOptions
  * @property {number | null} lastSeq - the peer's `Last-Event-ID` / `lastSeq`, or `null`
  * @property {boolean} validate - whether snapshots run the output validator
+ * @property {StreamLimits} [limits] - the bounds; the defaults when absent
+ */
+/**
+ * What `runSubscription` answers: the stopper, and the completion
+ * signal. `stop(reason)` with a string renders the `end` event with
+ * that reason first (a server shutdown) and then releases; `stop(null)`
+ * is silent (the peer is gone, or asked) and does not wait for a
+ * carrier write still pending — a late settlement is ignored. `done`
+ * settles (it never rejects) once the source's `stop()` and `close()`
+ * and the carrier's `done` hook have all run, in that order, once.
+ * @typedef {{ stop: (reason: string | null) => void, done: Promise<void> }} StreamRunner
  */
+/** The bounds every stream runs under unless the server says otherwise. */
+export declare const STREAM_LIMITS_DEFAULT: Readonly<{
+    replay: Readonly<{
+        limit: 256;
+        maxBytes: number;
+    }>;
+    queue: Readonly<{
+        events: 256;
+        bytes: number;
+    }>;
+}>;
+/**
+ * Resolve and validate a server's `streamLimits` option against the
+ * defaults: every member a positive integer (`Infinity` allowed), else
+ * the binding's host error.
+ * @param {unknown} option - the server's `streamLimits`, or `undefined`
+ * @param {(reason: string) => Error} refuse - the binding's host-error factory
+ * @returns {StreamLimits}
+ */
+export declare function resolveStreamLimits(option: unknown, refuse: (reason: string) => Error): StreamLimits;
 /**
  * Whether a settled handler value is a usable subscription.
  * Reads guardedly; a hostile value classifies as "not a subscription".
@@ -89,18 +265,16 @@ export declare function isSubscriptionLike(value: unknown): value is Subscriptio
  * snapshot at that emission's seq (§18.1); an `{ error }` emission —
  * and a hostile one — raises the `error` intent and ends the stream.
  *
- * Returns the stopper: `stop(reason)` with a string emits the `end`
- * event with that reason first (a server shutdown); `stop(null)` is
- * silent (the peer is gone, or asked). Idempotent; the subscription's
- * own `stop()` and `close()` run exactly once either way.
+ * Returns the stopper and the completion signal ({@link StreamRunner}).
+ * The stopper is idempotent; the subscription's own `stop()` and
+ * `close()` run exactly once either way.
  *
+ * @template F
  * @param {PipelineRoute} route
  * @param {SubscriptionLike} sub
- * @param {StreamHooks} hooks
+ * @param {StreamHooks<F>} hooks
  * @param {StreamOptions} options
- * @returns {{ stop: (reason: string | null) => void }}
+ * @returns {StreamRunner}
  */
-export declare function runSubscription(route: PipelineRoute, sub: SubscriptionLike, hooks: StreamHooks, options: StreamOptions): {
-    stop: (reason: string | null) => void;
-};
+export declare function runSubscription<F>(route: PipelineRoute, sub: SubscriptionLike, hooks: StreamHooks<F>, options: StreamOptions): StreamRunner;
 export { STREAM_ERRORS, STREAM_EVENTS, STREAM_MEDIA, HEARTBEAT_LINE, encodeStreamEvent } from './sse.js';

package/dist/types/stream/sse.d.ts

@@ -41,6 +41,16 @@ export declare const STREAM_ERRORS: Readonly<{
         msgid: "contract/heartbeat-missed";
         retryable: true;
     }>;
+    JC2096: Readonly<{
+        kind: "network";
+        msgid: "contract/slow-consumer";
+        retryable: true;
+    }>;
+    JC2097: Readonly<{
+        kind: "network";
+        msgid: "contract/reconnect-exhausted";
+        retryable: false;
+    }>;
 }>;
 /** The event names of the stream wire, on both carriers. */
 export declare const STREAM_EVENTS: readonly string[];

package/docs/APP-INTEGRATION.md

@@ -295,7 +295,9 @@ slots:
   (`status: 'error'`, the outcome's `kind`/`error`/`meta`); a server
   `end` lands the same way as a `network`-kind outcome with the
   channel-closed code — the stream is gone and the slot says so, so a
-  view can offer a reconnect (a fresh `start`; reconnection is never
-  automatic).
+  view can offer a reconnect: a fresh `start`. The binding passes no
+  `reconnect` to `client.subscribe`, so the client's opt-in reconnect
+  (CONTRACT-FORMAT.md §19) is for subscriptions the host opens itself;
+  a slot is re-entered by the view.
 - **`reset` releases the slot** exactly as for tasks: `status 'idle'`,
   `kind`/`error` cleared, `id`/`input`/`value`/`meta`/`seq` kept.