@jarenjs/contract 0.43.1

package/dist/types/revision.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file The contract revision: the lowercase hex SHA-256 over the RFC
+ * 8785 canonical bytes of the public projection (docs/CONTRACT-FORMAT.md
+ * §14) — the compatibility identity two independent processes agree on.
+ * It hashes the PUBLIC projection, never the source document, so a
+ * server-audience operation, a `policy.limits` value or an error-detail
+ * level can change without moving the revision, while any member a
+ * client can observe moves it. Memoized per compiled contract in a
+ * private `WeakMap`, so `compileContract` stays synchronous and the
+ * digest is computed at most once per process; `peekRevision` is the
+ * synchronous read `describe()` uses (`null` until the promise settled).
+ */
+export type Contract = import('./compile.js').Contract;
+/**
+ * Compute (once) the revision of a compiled contract: SHA-256 over the
+ * canonical bytes of `publicProjection(contract)`, as 64 lowercase hex
+ * characters. A projection that is not canonicalizable — a string member
+ * carrying an unpaired surrogate, say — rejects with `JC0061`
+ * (`ContractCompileError`, its `docPath` the offending value's pointer
+ * INTO THE PROJECTION).
+ * @param {Contract} contract
+ * @returns {Promise<string>}
+ * @example
+ * const contract = compileContract(doc);
+ * await contract.revision(); // 'e3b0c442…' — stable across compiles of equal documents
+ */
+export declare function contractRevision(contract: Contract): Promise<string>;
+/**
+ * The revision of a compiled contract if it has been computed, else
+ * `null` — the synchronous read `describe()` renders, so a description
+ * taken before anyone awaited `revision()` honestly says "not computed"
+ * rather than blocking.
+ * @param {Contract} contract
+ * @returns {string | null}
+ */
+export declare function peekRevision(contract: Contract): string | null;

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

@@ -0,0 +1,104 @@
+/**
+ * @file The client half of the stream binding, carrier-neutral
+ * (docs/CONTRACT-FORMAT.md §19): one consumer state machine that both
+ * `client.subscribe` implementations feed — the HTTP client with
+ * decoded SSE events, the port client with push frames. It validates
+ * every snapshot against the operation's output schema, enforces the
+ * strictly-increasing seq (`JC2092`), classifies a server `error` event
+ * (a declared code is a `failure` outcome under its own code; anything
+ * else is `contract` `JC2093` with the server's record in `details`),
+ * and delivers each `on*` callback totally — a callback that throws
+ * never breaks the machine. After the first terminal event (`error`,
+ * `end`, a local failure) the machine is finished: the carrier's
+ * `finish` hook has run and every later event is dropped.
+ */
+import { STREAM_ERRORS } from './sse.js';
+export type OutcomeRoute = import('../client/outcome.js').OutcomeRoute;
+export type OutcomeMeta = import('../client/outcome.js').OutcomeMeta;
+export type Outcome = import('../client/outcome.js').Outcome;
+export type Catalog = import('../http/wire.js').Catalog;
+export type StreamCallbacks = {
+    onSnapshot?: (value: unknown, info: {
+        seq: number;
+        resumed: boolean;
+    }) => void;
+    onPatch?: (emission: {
+        patch: unknown[];
+        seq: number;
+    }) => void;
+    onError?: (outcome: Outcome) => void;
+    onEnd?: (info: {
+        reason: string;
+    }) => void;
+};
+export type StreamConsumerOptions = {
+    route: OutcomeRoute & {
+        details: 'none' | 'paths' | 'full';
+    };
+    catalog: Catalog | null;
+    /**
+     * - mutated: `trace` is refreshed from error records
+     */
+    meta: OutcomeMeta;
+    callbacks: StreamCallbacks;
+    /**
+     * - the carrier's cleanup (remove the entry,
+     * cancel readers and timers); called exactly once, before the terminal callback
+     */
+    finish: () => void;
+    /**
+     * - the resume seq the caller passed (the
+     * regression baseline until a snapshot or patch moves it)
+     */
+    lastSeq: number | null;
+};
+/**
+ * @typedef {import('../client/outcome.js').OutcomeRoute} OutcomeRoute
+ * @typedef {import('../client/outcome.js').OutcomeMeta} OutcomeMeta
+ * @typedef {import('../client/outcome.js').Outcome} Outcome
+ * @typedef {import('../http/wire.js').Catalog} Catalog
+ */
+/**
+ * The callbacks of one `client.subscribe` call; every one optional.
+ * @typedef {Object} StreamCallbacks
+ * @property {(value: unknown, info: { seq: number, resumed: boolean }) => void} [onSnapshot]
+ * @property {(emission: { patch: unknown[], seq: number }) => void} [onPatch]
+ * @property {(outcome: Outcome) => void} [onError]
+ * @property {(info: { reason: string }) => void} [onEnd]
+ */
+/**
+ * @typedef {Object} StreamConsumerOptions
+ * @property {OutcomeRoute & { details: 'none' | 'paths' | 'full' }} route
+ * @property {Catalog | null} catalog
+ * @property {OutcomeMeta} meta - mutated: `trace` is refreshed from error records
+ * @property {StreamCallbacks} callbacks
+ * @property {() => void} finish - the carrier's cleanup (remove the entry,
+ *   cancel readers and timers); called exactly once, before the terminal callback
+ * @property {number | null} lastSeq - the resume seq the caller passed (the
+ *   regression baseline until a snapshot or patch moves it)
+ */
+/**
+ * The consumer the carriers feed. `snapshot`/`patch` take the seq the
+ * 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.
+ * @param {StreamConsumerOptions} options
+ * @returns {{ snapshot: (seq: number | null, data: unknown) => void,
+ *   patch: (seq: number | null, data: unknown) => void,
+ *   error: (data: unknown) => void,
+ *   end: (data: unknown) => void,
+ *   fail: (outcome: Outcome) => void,
+ *   cancel: () => void,
+ *   finished: () => boolean }}
+ */
+export declare function createStreamConsumer(options: StreamConsumerOptions): {
+    snapshot: (seq: number | null, data: unknown) => void;
+    patch: (seq: number | null, data: unknown) => void;
+    error: (data: unknown) => void;
+    end: (data: unknown) => void;
+    fail: (outcome: Outcome) => void;
+    cancel: () => void;
+    finished: () => boolean;
+};
+export { STREAM_ERRORS };

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

@@ -0,0 +1,106 @@
+/**
+ * @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.
+ *
+ * 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.
+ */
+export type PipelineRoute = import('../pipeline.js').PipelineRoute;
+export type SubscriptionLike = {
+    result?: unknown;
+    snapshot?: () => unknown;
+    subscribe: (cb: (emission: any) => void) => (() => void);
+    close: () => void;
+    replay?: (seq: number) => unknown;
+    mode?: unknown;
+};
+export type StreamHooks = {
+    snapshot: (seq: number, value: unknown, resumed: boolean) => void;
+    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;
+};
+export type StreamOptions = {
+    /**
+     * - the peer's `Last-Event-ID` / `lastSeq`, or `null`
+     */
+    lastSeq: number | null;
+    /**
+     * - whether snapshots run the output validator
+     */
+    validate: boolean;
+};
+/**
+ * @typedef {import('../pipeline.js').PipelineRoute} PipelineRoute
+ */
+/**
+ * The duck-typed subscription of docs/CONTRACT-FORMAT.md §17.1.
+ * @typedef {{ result?: unknown, snapshot?: () => unknown,
+ *   subscribe: (cb: (emission: any) => void) => (() => void),
+ *   close: () => void, replay?: (seq: number) => unknown, mode?: unknown }} SubscriptionLike
+ */
+/**
+ * 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.
+ * @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
+ */
+/**
+ * @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
+ */
+/**
+ * Whether a settled handler value is a usable subscription.
+ * Reads guardedly; a hostile value classifies as "not a subscription".
+ * @param {unknown} value
+ * @returns {value is SubscriptionLike}
+ */
+export declare function isSubscriptionLike(value: unknown): value is SubscriptionLike;
+/**
+ * Run one subscription over a carrier. Emissions are forwarded
+ * verbatim (a patch is never mutated); an emission whose serialized
+ * patch exceeds `policy.stream.maxPatchBytes` is replaced by a fresh
+ * 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.
+ *
+ * @param {PipelineRoute} route
+ * @param {SubscriptionLike} sub
+ * @param {StreamHooks} hooks
+ * @param {StreamOptions} options
+ * @returns {{ stop: (reason: string | null) => void }}
+ */
+export declare function runSubscription(route: PipelineRoute, sub: SubscriptionLike, hooks: StreamHooks, options: StreamOptions): {
+    stop: (reason: string | null) => void;
+};
+export { STREAM_ERRORS, STREAM_EVENTS, STREAM_MEDIA, HEARTBEAT_LINE, encodeStreamEvent } from './sse.js';

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

@@ -0,0 +1,62 @@
+/**
+ * @file The stream wire's shared shapes (docs/CONTRACT-FORMAT.md §18):
+ * the stream code table as data (`STREAM_ERRORS`, the same
+ * table-as-data shape as `HTTP_ERRORS` and `PORT_LOCAL_ERRORS`), the
+ * event names both carriers speak, and the SSE text framing on top of
+ * `@jarenjs/core/text/sse` — one JSON value per event, a heartbeat
+ * comment line, and the `JC1009` host refusal for text the frame
+ * cannot carry. The port carrier uses the same tables and data shapes
+ * with no SSE text at all (§18.2).
+ */
+/**
+ * The stream request-time codes — code → `{ kind, msgid, retryable }`.
+ * The normative table is docs/CONTRACT-FORMAT.md §18.3; a test holds
+ * them equal. `JC2095` (a refused resume) is deliberately absent: it is
+ * informational, carried as `resumed: false` in a snapshot's event
+ * data, never an outcome.
+ */
+export declare const STREAM_ERRORS: Readonly<{
+    JC2090: Readonly<{
+        kind: "contract";
+        msgid: "contract/not-a-stream";
+        retryable: false;
+    }>;
+    JC2091: Readonly<{
+        kind: "contract";
+        msgid: "contract/invalid-snapshot";
+        retryable: false;
+    }>;
+    JC2092: Readonly<{
+        kind: "contract";
+        msgid: "contract/seq-regression";
+        retryable: false;
+    }>;
+    JC2093: Readonly<{
+        kind: "contract";
+        msgid: "contract/stream-error";
+        retryable: false;
+    }>;
+    JC2094: Readonly<{
+        kind: "network";
+        msgid: "contract/heartbeat-missed";
+        retryable: true;
+    }>;
+}>;
+/** The event names of the stream wire, on both carriers. */
+export declare const STREAM_EVENTS: readonly string[];
+/** The media type of the SSE carrier. */
+export declare const STREAM_MEDIA = "text/event-stream";
+/** The heartbeat comment line the SSE carrier writes every `heartbeatMs`. */
+export declare const HEARTBEAT_LINE = ":\n\n";
+/**
+ * One stream event as SSE text: the event name, the seq as the SSE id,
+ * the JSON data. JSON output never carries a raw CR, so the encoder's
+ * refusal is reachable only through a host handing this function
+ * non-JSON text — `JC1009`, thrown.
+ * @param {string} event - `snapshot | patch | error | end`
+ * @param {number | null} seq - the event's seq; `null` writes no id line
+ * @param {unknown} data - the event's JSON data
+ * @returns {string}
+ * @throws {ContractHostError} `JC1009` when the text cannot ride an SSE frame
+ */
+export declare function encodeStreamEvent(event: string, seq: number | null, data: unknown): string;

package/docs/APP-INTEGRATION.md

@@ -0,0 +1,301 @@
+# Calling a contract from @jarenjs/app
+
+How an application built with `@jarenjs/app` calls the operations of a
+contract with no route strings, no hand-written `fetch` wrappers and
+no per-operation effect handlers. The shape of the convention is one
+sentence: **every operation becomes a task slot in state plus three
+generated action documents, and one registered effect carries them all**
+— plain JSON the app compiles like any hand-written action, with the
+per-operation concurrency mode taken from the contract's `policy.task`
+and neither package importing the other. The test suite executes this
+document's two worked examples verbatim, against a real `serveHttp`
+dispatcher.
+
+The convention is `@jarenjs/app`'s own async-task convention
+([TASKS.md](../../app/docs/TASKS.md)): correctness lives in state (a
+monotonic slot `id`, a completion action that guards on it), cancellation
+lives in the host. The generator writes those documents so a consumer
+never writes the id guard by hand, and the effect settles every
+operation with the contract's **outcome** (CONTRACT-FORMAT §10) instead
+of a string.
+
+## The API
+
+```js
+import { createApp, createTaskEffect } from '@jarenjs/app';
+import { openHttpClient } from '@jarenjs/contract/client';
+import { contractAppBinding, createContractEffect } from '@jarenjs/contract/app';
+
+const client = openHttpClient(contract, { baseUrl: 'https://api.example' });
+
+const { slice, actions, schema } = contractAppBinding(contract, {
+  statePath: '/contract',      // where the slice lives in app state (default)
+  namespace: 'contract/',      // action-name prefix (default)
+  ops: contract.ids,           // the operations this app uses (default: all)
+});
+// slice   → { 'catalog.load': { id: 0, status: 'idle', kind: null, value: null, error: null, meta: null }, … }   mount it at statePath
+// actions → { 'contract/catalog.load/start', '…/done', '…/reset': <query docs>, … }                            spread into the app's actions
+// schema  → the slice's JSON Schema                                                                           compose into validateState
+
+createApp(doc, {
+  effects: { contract: createContractEffect(client, { createTaskEffect }) },   // ONE effect for every operation
+});
+```
+
+`createContractEffect` takes the `createTaskEffect` factory **from the
+host** — `@jarenjs/contract` imports nothing from `@jarenjs/app`, and
+there is exactly one task-effect implementation in the suite. It builds
+one inner task effect per distinct `policy.task` mode the contract
+uses (`switch` for a read, `exhaust` for a command by default) and
+routes each descriptor by its `op`, so a `switch` read and an `exhaust`
+command live behind the one `run: "contract"` the documents name. The
+mode is never *named* in a generated document; the generator derives the
+document's state-side guards from it instead (an `exhaust` start is a
+no-op in state while its slot is loading), so state and effect tell the
+same story in every mode.
+
+## The worked example
+
+A two-operation contract — a read with a query member and a command
+with a path variable, a required idempotency key and a declared
+`conflict` error:
+
+```json
+{
+  "$contract": "0.1",
+  "id": "shop",
+  "version": "1",
+  "$defs": {
+    "Product": {
+      "type": "object",
+      "required": ["id", "name", "price"],
+      "properties": {
+        "id": { "type": "integer" },
+        "name": { "type": "string", "minLength": 1 },
+        "price": { "type": "number", "minimum": 0 }
+      }
+    }
+  },
+  "operations": {
+    "catalog.load": {
+      "kind": "read",
+      "input": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" } } },
+      "output": { "type": "array", "items": { "$ref": "#/$defs/Product" } },
+      "http": { "method": "GET", "path": "/api/catalog" }
+    },
+    "product.save": {
+      "kind": "command",
+      "input": {
+        "type": "object",
+        "required": ["id", "product"],
+        "properties": { "id": { "type": "integer" }, "product": { "$ref": "#/$defs/Product" } }
+      },
+      "output": { "$ref": "#/$defs/Product" },
+      "errors": { "conflict": { "status": 409, "schema": { "$ref": "#/$defs/Product" } } },
+      "policy": { "idempotency": "required" },
+      "http": { "method": "PUT", "path": "/api/products/{id}" }
+    }
+  }
+}
+```
+
+The application document. `state.contract` is where the generated slice
+is mounted (the host replaces the placeholder with `slice`), the
+generated actions are spread beside the app's own, and the view reads
+the slots like any other state:
+
+```json
+{
+  "$app": "0.1",
+  "state": {
+    "contract": {},
+    "draft": { "id": 1, "name": "Kettle", "price": 12 }
+  },
+  "view": [
+    { "match": "$", "body": ["main", {},
+      ["p", { "class": "status" }, "$.contract['catalog.load'].status"],
+      ["ul", {}, { "$apply": "$.contract['catalog.load'].value[*]" }],
+      ["p", { "class": "save" }, "$.contract['product.save'].status"]
+    ] },
+    { "match": "$.contract['catalog.load'].value[*]", "body": ["li", {}, "$.name"] }
+  ],
+  "actions": {
+    "draft/name": { "patch": [{ "op": "replace", "path": "/draft/name", "value": "$payload" }] }
+  }
+}
+```
+
+Composed and mounted:
+
+```js
+const { slice, actions, schema } = contractAppBinding(contract, { ops: ['catalog.load', 'product.save'] });
+const validate = new JarenValidator().compile({
+  type: 'object',
+  required: ['contract', 'draft'],
+  properties: { contract: schema, draft: { type: 'object' } },
+});
+const app = createApp(
+  { ...doc, state: { ...doc.state, contract: slice }, actions: { ...actions, ...doc.actions } },
+  {
+    effects: { contract: createContractEffect(client, { createTaskEffect }) },
+    validateState: (state) => validate(state),
+  });
+
+app.dispatch('contract/catalog.load/start', { since: '2026-01-01T00:00:00Z' });
+// → state.contract['catalog.load'] = { id: 1, status: 'loading', kind: null, value: null, error: null, meta: null }
+// … the server answers …
+// → { id: 1, status: 'done', kind: null, value: [ {…}, {…} ], error: null, meta: { op, attempt: 1, trace, … } }
+
+app.dispatch('contract/product.save/start', { id: 1, product: app.getState().draft });
+// a 409 conflict → { id: 1, status: 'error', kind: 'failure', value: null, error: { code: 'conflict', status: 409, details: {…}, … }, meta }
+// state.draft is untouched; a later success → status 'done', kind null, value the saved product, error null
+app.dispatch('contract/product.save/reset');
+// → status 'idle', kind null, error null — id, value and meta untouched (dismiss the error, or release a slot the host cancelled)
+```
+
+## What the generated documents guarantee
+
+- **Staleness is rejected by construction.** Two quick `start`s take the
+  slot id to 2; the effect's `switch` mode aborts request 1, but even
+  when request 1's response arrives (it may already have resolved), its
+  `done` carries `id: 1`, the guard compares it with the slot's `2`,
+  `$if` takes no branch, and the action yields the empty sequence — no
+  state change, no render, no subscriber.
+- **A double-click does not double-run a command — and its result
+  lands.** `product.save` is a command, `policy.task` defaults to
+  `exhaust`: its generated `start` is wrapped in a state-side guard
+  (`$if: [{ $ne: [<slot>.status, "loading"] }, …]`), so while the slot
+  has an in-flight task a second `start` is a no-op in state *and* in
+  the effect — no patch, no effect invocation, no render; the id stays
+  at 1, the handler runs once, the single completion carries id 1
+  against a slot at 1 and lands as `done` with the saved product. (For
+  a command whose every dispatch must run, `policy.task: "concat"`
+  queues; the contract is the one place the choice is made.)
+- **`reset` releases a slot.** `contract/<op>/reset` writes `status:
+  "idle"`, `kind: null`, `error: null` and leaves `id`, `value` and
+  `meta` alone — the ordinary "dismiss the error" action, and the one
+  way out of a slot a host `effect.cancel(slot)` left `loading` on an
+  `exhaust` operation (the guarded `start` is a no-op while loading).
+  The id stays monotonic, so a late completion of the cancelled attempt
+  is still rejected.
+- **A failed reload keeps the last good value.** The error branch writes
+  `status`, `error` and `meta`; `value` is untouched, so a list stays on
+  screen while the error shows beside it.
+- **Cancellation is silent.** A `cancelled` outcome dispatches nothing
+  (the task effect's `AbortError` rule); the slot stays `loading` until
+  its successor settles or the host dispatches `reset`.
+- **`validateState` fails closed.** The slice schema pins `status` to
+  `idle | loading | done | error`, `kind` to `null | failure | network |
+  contract`, `value` to the operation's output schema or `null`, and
+  `error`/`meta` to the outcome shapes; a rogue hand-written action that
+  writes a nonsense status is `JA2005` and the state stands.
+- **Every failure lands as an outcome, and the slot says which kind.** A
+  declared error, a network failure, a contract violation — and a thrown
+  host value, projected to `JC2058` — arrive in `error` as the same
+  `{ code, message, status, details, retryable }`, and the slot's `kind`
+  carries the outcome's kind (`failure` | `network` | `contract`) while
+  `status` is `error`, so a view tells "you are offline" from "the
+  server refused this" without parsing `error.code`.
+
+## Honest divergences from TASKS.md
+
+- The completion payload is read through `$coalesce: ["$payload.result",
+  "$payload.error"]` rather than TASKS.md's `$exists: "$payload.error"`
+  branch: both members carry an outcome here (a resolved one, or a
+  projected host throw), and the outcome's own `ok` decides the branch.
+- The effect's `fail` prop is not emitted: one completion action per
+  operation is the query-friendliest shape, and the outcome already
+  distinguishes success from failure.
+- The state slot carries `kind`, `value` and `meta` beside TASKS.md's
+  `{ id, status, error }`: the operation's output has a schema, so it
+  has a typed home in the slice rather than a hand-chosen path, and the
+  failure class is a member rather than a code to parse.
+- One slot per operation makes `concat` and `parallel` **"latest
+  wins"**: every `start` increments the id, the effect runs them all
+  (queued, or concurrently), only the completion carrying the current
+  id lands, `status` stays `loading` until the newest does, and earlier
+  results and errors are dropped from state. TASKS.md's per-slot
+  convention says nothing about several results for one slot; a
+  consumer that needs every result of a fan-out needs a slot per key.
+- An `exhaust` operation's `start` carries a state-side guard TASKS.md
+  does not write by hand: TASKS.md's exhaust mode ignores duplicate
+  starts in the *effect*, but a hand-written start still moves the
+  slot id, so the one completion would be rejected; the generator
+  decides in state first, and the mode is still never named.
+
+## Live data: subscribe operations
+
+A subscribe operation reaches the app as a **subscription**, not a
+task: its slot in the slice is `{ id, status: 'idle' | 'live' |
+'error', kind, input, value, error, meta, seq }`, its generated
+actions are `start`, `stop`, `snapshot`, `patch`, `error` and `reset`,
+and the binding additionally emits one **`subs` entry** per subscribe
+operation (`run: "contract-stream"`) whose `when` watches `status ===
+'live'` and whose `withQuery` resolves the slot's `id` and `input`
+from state. `start` stores its payload as the slot's `input` and flips
+the slot `live` — it emits **nothing**; the app's own subscription
+reconciliation sees the liveness and runs the handler, exactly as
+APP-FORMAT §5.3 defines it. A second `start` while `live` is a no-op
+in state (the same state-first guard as an exhaust command's start);
+`stop` flips the slot `idle`, which stops the subscription through its
+own cleanup.
+
+The worked live contract (verbatim-tested, like the two examples
+above):
+
+```json
+{
+  "$contract": "0.1",
+  "id": "board",
+  "operations": {
+    "board.feed": {
+      "kind": "subscribe",
+      "input": { "type": "object", "required": ["room"], "properties": { "room": { "type": "string" } } },
+      "output": { "type": "object", "required": ["rows"], "properties": { "rows": { "type": "array" } } }
+    }
+  }
+}
+```
+
+Composed and mounted — the subs entries spread into the document, the
+handler registered under the app's `subs` option:
+
+```js
+const { slice, actions, subs, schema } = contractAppBinding(contract);
+const app = createApp(
+  { ...doc, state: { ...doc.state, contract: slice }, actions: { ...actions, ...doc.actions }, subs: [...(doc.subs ?? []), ...subs] },
+  {
+    effects: { contract: createContractEffect(client, { createTaskEffect }) },
+    subs: { 'contract-stream': createContractSubscription(client) },
+  });
+
+app.dispatch('contract/board.feed/start', { room: 'r1' });
+// → { id: 1, status: 'live', kind: null, input: { room: 'r1' }, value: null, error: null, meta: null, seq: 0 }
+// … the snapshot arrives … → value: { rows: [...] }, seq: <seq0>
+// … a write commits …     → value patched copy-on-write,  seq: <seq>
+app.dispatch('contract/board.feed/stop');
+// → status 'idle'; the subscription's cleanup ran (client stop → wire unsubscribe)
+```
+
+What the generated documents guarantee, in the same spirit as the task
+slots:
+
+- **The handler applies the patches; state replaces.** An app action's
+  `patch` member is a *literal* op list whose members are query
+  expressions — it cannot splice a runtime array of RFC 6902 ops — so
+  `createContractSubscription` applies each `{ patch, seq }` emission
+  host-side with `@jarenjs/json/patch` (copy-on-write; unaffected rows
+  stay reference-identical) and dispatches the `patch` action with the
+  patched document; the action `replace`s the slot's `value` and `seq`.
+- **A stale instance cannot write.** Every dispatched payload carries
+  the instance's `id`; `snapshot`/`patch`/`error` guard on it against
+  the slot id, and `patch` additionally on `seq` strictly greater than
+  the slot's — an out-of-order or replayed event is a provable no-op.
+- **A dead stream is visible.** An `onError` outcome lands in the slot
+  (`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).
+- **`reset` releases the slot** exactly as for tasks: `status 'idle'`,
+  `kind`/`error` cleared, `id`/`input`/`value`/`meta`/`seq` kept.