@jarenjs/contract 0.49.2 → 0.66.1

package/README.md

@@ -51,8 +51,9 @@ published as JSON Schema in
   "$contract": "0.1",
   "id": "shop",
   "$defs": {
-    "Product": { "type": "object", "required": ["id", "name"],
-                 "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }
+    "Product": { "type": "object",
+                 "properties": { "id": { "type": "integer" }, "name": { "type": "string" } },
+                 "required": ["id", "name"] }
   },
   "operations": {
     "catalog.load": {
@@ -64,9 +65,10 @@ published as JSON Schema in
     },
     "product.save": {
       "kind": "command",
-      "input":  { "type": "object", "required": ["id", "revision", "product"], "properties": {
+      "input":  { "type": "object", "properties": {
                   "id": { "type": "integer" }, "revision": { "type": "integer" },
-                  "product": { "$ref": "#/$defs/Product" } } },
+                  "product": { "$ref": "#/$defs/Product" } },
+                  "required": ["id", "revision", "product"] },
       "output": { "$ref": "#/$defs/Product" },
       "errors": { "conflict": { "status": 409 }, "not-found": { "status": 404 } },
       "policy": { "idempotency": "required", "revision": "input:/revision" },
@@ -74,7 +76,7 @@ published as JSON Schema in
     },
     "image.bytes": {
       "kind": "read",
-      "input":  { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" } } },
+      "input":  { "type": "object", "properties": { "id": { "type": "integer" } }, "required": ["id"] },
       "output": true,
       "http":   { "method": "GET", "path": "/api/images/{id}", "media": "application/octet-stream" }
     }
@@ -88,7 +90,54 @@ a command by default, or an explicit `in` map). Path and query strings
 are decoded by a normalizer compiled over exactly those members; body
 members are never coerced. An operation without `http` is bound to the
 canonical `POST /<op-id>`. A non-JSON `media` marks an operation
-*opaque*: routed and matched, never validated as JSON.
+*opaque*: routed and matched, never validated as JSON, its bytes
+streamed both ways — the handler pulls the upload chunk by chunk and
+may answer a stream, and the HTTP client reaches it through `bytes()`.
+
+## The same document, by code
+
+`@jarenjs/linq/contract` is the pen that writes this format. The
+builders are the schema pen's, every `named()` schema is hoisted into
+the contract's `$defs`, the members land in the order §12.1 fixes, and
+no default is written — so the document below is byte for byte the one
+above:
+
+```js
+import * as s from '@jarenjs/linq/schema';
+import { command, defineContract, error, http, read } from '@jarenjs/linq/contract';
+
+const Product = s.named('Product', s.object({ id: s.integer(), name: s.string() }).open());
+
+export const shop = defineContract({ id: 'shop' }, {
+  'catalog.load': read({
+    input: s.object({ since: s.string().format('date-time').optional() }).open(),
+    output: s.array(Product),
+    policy: { task: 'switch', cache: 'revision' },
+    http: http({ method: 'GET', path: '/api/catalog' }),
+  }),
+  'product.save': command({
+    input: s.object({ id: s.integer(), revision: s.integer(), product: Product }).open(),
+    output: Product,
+    errors: { conflict: error({ status: 409 }), 'not-found': error({ status: 404 }) },
+    policy: { idempotency: 'required', revision: 'input:/revision' },
+    http: http({ method: 'PUT', path: '/api/products/{id}/master' }),
+  }),
+  'image.bytes': read({
+    input: s.object({ id: s.integer() }).open(),
+    output: true,
+    http: http({ method: 'GET', path: '/api/images/{id}', media: 'application/octet-stream' }),
+  }),
+});
+
+compileContract(shop.document);                    // the same compile, the same errors
+```
+
+The types come with it, without the `types` projection: `ContractOf<typeof
+shop>` is the operation map, and `typedClient`, `typedHandlers` and
+`typedTools` carry it onto a client, a handler table and an AI toolbox.
+The pen's document is
+[CONTRACT-PEN.md](../linq/docs/CONTRACT-PEN.md); it imports nothing of
+this package.
 
 ## Compile once, use everywhere
 
@@ -150,6 +199,20 @@ response.headers['x-jaren-trace'];                           // the server trace
 JSON.parse(response.body);                                   // the catalog
 ```
 
+Every option has a default. The host facts among them come from a
+`runtime` record (`@jarenjs/core/runtime`) when one is given — and every
+binding takes one: `serveHttp`, `servePort` and `openLocalClient` mint
+their trace from its `uuid`, `openPortClient` its client id, `openHttpClient`
+its idempotency keys (its `now` stamps the key records and its `random`
+draws the retry jitter), and `createMemoryLedger` stamps claims with its
+`now`. So a server, its ledger, a client, a store and a job queue share
+one record and a deterministic run is configured once; an explicit `trace`,
+`keys` or `now` still wins over the record's member, and with no record
+every binding reads the platform as it always did. Give the server and its
+ledger the SAME record: a ledger built without a clock follows the
+binding's instants, and one built with its own clock must not disagree
+with the server that stamps its claims.
+
 The pipeline routes (404/405 with `Allow`), enforces the body limit
 (413) before reading, checks the media (415), parses (400), assembles the
 input from path, query and headers through a prototype-safe setter,
@@ -167,6 +230,34 @@ is refused at construction. `GET /.well-known/jaren-contract` answers
 `describe()`. The normative pipeline, taxonomy and ledger interface are
 [CONTRACT-FORMAT.md §7–§9](docs/CONTRACT-FORMAT.md#7-the-http-server-binding).
 
+**The host lifecycle.** Every server binding takes the same two hooks
+([§7.7](docs/CONTRACT-FORMAT.md#77-the-host-lifecycle-identify-acquire-release-settle)):
+`identify(meta)` runs after the route resolved and before a byte of the
+body is read, and answers `{ host, release? }` — the host `scope(ctx)`
+sees; `acquire(input, identity, enter)` runs after the input validated
+and after a new idempotency claim, and calls `enter({ host, release?,
+settlement? })` once — the host the handler sees as `ctx.host`, frozen
+beside it. A host that opens a transaction around `enter` commits it
+when `enter` resolves and rolls it back when it rejects, and a lease
+whose `settlement` is `{ ledger: createDbLedger(tx), required: true }`
+has the claim recorded inside `enter`, so the domain write and the
+receipt commit together or not at all. Releases run once each, acquired
+before identity, before the response is exposed — or when an opaque
+body or an SSE stream is done. A hook fault is the host's (`JC2008`,
+observed), a hook's `meta.fail(code)` a declared failure. The generated
+`HandlerContext<Host, Carrier>` carries `ctx.host` and `ctx.carrier`;
+port and local contexts spell the HTTP-only members as `null`.
+
+```js
+const server = serveHttp(contract, handlers, {
+  ledger: createDbLedger(db),
+  identify: (meta) => ({ host: { tenant: meta.headers['x-tenant'] ?? null } }),
+  acquire: (input, identity, enter) => db.transaction(
+    (tx) => enter({ host: { db: tx }, settlement: { ledger: createDbLedger(tx), required: true } }),
+    { mode: 'immediate' }),
+});
+```
+
 Without a declared resolver, `If-Match`/`If-None-Match` are applied
 **after** the handler and only when it armed a tag — a cache device,
 **never a write guard**. The `preconditions` option is the write guard:
@@ -205,8 +296,10 @@ beat the wildcard, and Fastify's own `bodyLimit` never answers — the
 operation's `policy.limits.maxBodyBytes` is the single body ceiling,
 refusing as the contract's coded `JC2003` instead of Fastify's
 `FST_ERR_CTP_BODY_TOO_LARGE`. Subscribe operations stream (the adapter
-calls `response.stream`) and a dropped peer reaches the handler as
-`ctx.signal` — the earlier buffer-parser recipe carried neither. To
+calls `response.stream`, writing each event only after the previous one
+drained — a slow reader parks the source instead of growing a buffer)
+and a dropped peer reaches the handler as `ctx.signal` — the earlier
+buffer-parser recipe carried neither. To
 confine the contract, register the same route in an encapsulated plugin
 with `{ prefix }`; the prefix must then prefix the contract's declared
 paths (canonical bindings and the well-known path included). One
@@ -352,10 +445,10 @@ its frozen `capabilities`:
 |---|---|---|---|
 | `status` | yes | no (`error.status: null`) | no (`error.status: null`) |
 | `headers` | yes | no | no |
-| `media` (opaque operations) | yes | no (`JC1005` at invoke) | no (`JC1005`; `JC2071` to a foreign asker) |
+| `media` (opaque operations) | yes — streamed both ways; `client.bytes()` | no (`JC1005` at invoke) | no (`JC1005`; `JC2071` to a foreign asker) |
 | `etag` | yes | no | no |
 | `idempotency` | with a `ledger` / always sent | no — declared policy inert, stated | no — `key` reserved in the frame grammar |
-| `stream` (`subscribe`) | yes — SSE, `Last-Event-ID` resumption | no (`JC1005` at invoke) | yes — push frames, per-client streams |
+| `stream` (`subscribe`) | yes — SSE, `Last-Event-ID` resumption (paged replay, bounded queue) | no (`JC1005` at invoke) | yes — push frames, per-client streams (the same replay and bounds) |
 | `cancel` | `'signal'` | `'signal'` | `'message'` |
 
 The normative bindings are [CONTRACT-FORMAT.md §15–§16](docs/CONTRACT-FORMAT.md#15-the-local-binding),
@@ -426,12 +519,27 @@ And on the command line, the drift gate:
 
 ```sh
 jaren-contract openapi --contract shop.json --out api/ --info-title Shop
-jaren-contract types   --contract shop.json --out src/shop.d.ts --check   # exit 1 when stale
+jaren-contract types   --contract shop.js   --out src/shop.d.ts --check   # exit 1 when stale; the module IS the source
 jaren-contract docs    --contract shop.json --out docs/
+jaren-contract diff    --from api/v1.json --to shop.js --fail-on breaking
 ```
 
+Every document flag — `--contract`, `--from`, `--to` — takes a `.json`
+file or a pure module (`.js`, `.mjs`, `.cjs`, and `.ts`/`.mts`/`.cts`
+where Node strips types) whose `default` or `contract` export is the
+document or a `@jarenjs/linq/contract` pen (its `toJSON()` is the
+emission); the module is evaluated twice and refused (exit 2) when the
+two emissions differ, so a clock or randomness in a contract module
+never projects two different declarations. The loader is
+`@jarenjs/json/node`, the Node-only subpath `jaren-db` shares — this
+package imports neither `linq` nor `db`. `types --out … --check` against
+the module is the types twin CI runs: exit 1 when the declaration is
+missing or stale, 0 when current, and an ordinary run rewrites nothing
+that did not change.
+
 `describe` and `public` print JSON; exit 0 current/written, 1 drift
-under `--check`, 2 on a compile refusal printed as `code docPath reason`.
+under `--check`, 2 on a compile refusal printed as `code docPath reason`
+or an unreadable, impure or undocumented input.
 The normative projection rules — the public projection's member order
 (the revision hashes those bytes), the OpenAPI mapping and keyword
 policy, the tool naming — are
@@ -477,6 +585,9 @@ isCompatible(clientContract, serverContract);
 jaren-contract diff --from api/v1.json --to api/v2.json --fail-on breaking   # exit 1 on a breaking change
 ```
 
+`--fail-on` requires at least one change class; a missing or empty value is a
+usage error (exit 2), so an unset CI variable cannot silently disable the gate.
+
 The revision answers "is this byte-for-byte the contract I compiled
 against?"; `version`/`compat` answer "do the authors claim we speak?";
 the diff answers "what exactly moved, and does it break me?". They are
@@ -492,19 +603,19 @@ benchmark-figure gate so no number here is typed by hand:
 
 - **Route match**: the compiled matcher resolves the probe mix —
   static hot paths, variables, the static-beats-variable case, a miss —
-  at <!--bm:contract.match.vs-fmw-->172 ns per lookup vs find-my-way's 180 ns<!--/bm-->;
-  hono's TrieRouter is <!--bm:contract.match.vs-hono-->1.8x<!--/bm--> behind, and its RegExpRouter refuses this
+  at <!--fact:contract.match.vs-fmw-->172 ns per lookup vs find-my-way's 185 ns<!--/fact-->;
+  hono's TrieRouter is <!--fact:contract.match.vs-hono-->1.9x<!--/fact--> behind, and its RegExpRouter refuses this
   route table outright (a static path registered after a param sibling).
 - **Dispatch, in-process**: the whole pipeline (route, decode, validate
   input, handler, validate output,
-  serialize) is <!--bm:contract.dispatch.vs-fastify-->2.8–15.1x<!--/bm-->
+  serialize) is <!--fact:contract.dispatch.vs-fastify-->2.8–11.9x<!--/fact-->
   faster than Fastify driven through its own `inject` — a number that
   includes Fastify's mock-stream harness, which is why the next row
   exists.
 - **The honest loss**: the bare pieces Fastify composes — find-my-way +
   Ajv + fast-json-stringify, called directly with no harness and no
   response validation
-  — are <!--bm:contract.dispatch.losses-->2.4–7.5x<!--/bm--> faster than
+  — are <!--fact:contract.dispatch.losses-->2.5–11.4x<!--/fact--> faster than
   this pipeline. The wide end of that band is the bare `{ok:true}`
   route, where the rival's compiled serializer answers in ~200 ns and
   there is almost no work to amortize the pipeline against; on the
@@ -513,8 +624,16 @@ benchmark-figure gate so no number here is typed by hand:
   hostile input settles into a coded response) that also proves the
   server kept its own contract before a byte leaves. Over a real
   loopback socket the two stacks are level: the socket dominates both.
+- **The optimization trigger**: on the heaviest in-process row (the
+  5×4-body PUT), response serialization is <!--fact:contract.serialization.share-->11.5%<!--/fact-->
+  of the request and output validation is <!--fact:contract.validateOutput.share-->29%<!--/fact-->.
+  A schema-driven serializer stays unscheduled while serialization is below
+  25%: even making that stage free would move the whole request by only about a
+  tenth. The suite republishes both shares on every measured run; for a large
+  cached representation, validate on rebuild and serve by revision instead of
+  paying validation on every request.
 - **Revision**: computing it
-  costs <!--bm:contract.revision.ms-->1.4 ms<!--/bm--> for the 123-operation
+  costs <!--fact:contract.revision.ms-->2.8 ms<!--/fact--> for the 123-operation
   contract, once per process.
 
 ## What it is not
@@ -538,19 +657,31 @@ deliberate decision, not a gap:
   a nonce scheme and does not authenticate the sender.
 - **Bytes are not JSON.** A non-JSON `media` marks an operation opaque:
   routed and matched, path and query still decoded and validated, the
-  body handed over raw and never modeled. Images and OAuth redirects
-  are host paths, not JSON operations.
-- **No replication or durability.** The ledger and the command
-  lifecycle ship as JSON documents (`$model`, `$fsm`) a host may open
-  with `@jarenjs/db`; the in-memory ledger is for tests and
-  single-process hosts. Durability is the host's — and needs no
-  dependency: [CONTRACT-FORMAT.md §8.1](docs/CONTRACT-FORMAT.md#81-a-durable-ledger-over-nodesqlite--an-example-not-an-export)
+  body streamed to the handler as a pull source that never yields past
+  the declared limit, and never modeled. `client.bytes()` is its typed
+  door — a live response stream, never a JSON value — and `invoke`
+  refuses it. Images and OAuth redirects are host paths, not JSON
+  operations.
+- **No replication, and no storage of its own.** The ledger and the
+  command lifecycle ship as JSON documents (`$model`, `$fsm`); the
+  in-memory ledger is for tests and single-process hosts. A durable
+  ledger is one import away and adds no dependency here:
+  `createDbLedger` in `@jarenjs/linq/db` implements the ledger over a
+  `@jarenjs/db` store (immediate claims, a persisted generation fence,
+  settlement inside the host's transaction), and
+  [CONTRACT-FORMAT.md §8.1](docs/CONTRACT-FORMAT.md#81-a-durable-ledger-over-nodesqlite--an-example-not-an-export)
   is a complete, tested ~60-line ledger over `node:sqlite` (built into
-  Node ≥ 24), deliberately an example rather than an export.
-- **No automatic reconnect.** A stream that ends with a `network`
-  outcome is re-entered by the host calling `subscribe` again with the
-  last delivered seq (`lastSeq` is the hook); the backoff/resume/give-up
-  policy is the open decision tracked in the repository ROADMAP.
+  Node ≥ 24) for a host without the store — an example, not an export.
+- **Reconnect is opt-in, HTTP-only, and network-only.**
+  `subscribe(op, input, { reconnect: { max } })` re-establishes a
+  stream after a network loss — a rejected request, a missed heartbeat,
+  the server's `JC2096`, a body that ends before `end` — from the last
+  delivered seq under the retry backoff, and ends with one `JC2097`
+  when the budget is spent; a declared failure, a contract outcome or
+  the server's `end` never reconnects, and the port client has no
+  network loss to reconnect from. Absent, a `network` outcome is
+  delivered as is and the host re-enters `subscribe` with the
+  subscription's `lastSeq`.
 
 ## What is here
 
@@ -560,7 +691,10 @@ Here: the document and its grammar, `compileContract`, `contract.match`,
 `fetch` and `node` adapters, the ledger interface with `createMemoryLedger`
 and the `idempotencyLedgerModel`/`commandLifecycleFsm` documents); the HTTP
 client (`openHttpClient`, the D6 outcomes with the `JC2050–JC2058` client
-codes, the client half of idempotency, retry, `negotiate`); the app
+codes, the client half of idempotency, retry, `negotiate`, and `bytes`
+for the opaque operations — a live response stream and a streamed
+upload, typed as `HttpClient`/`ByteOperations` by the projection and
+`typedHttpClient`/`OpaqueOf` by the pen); the app
 binding (`contractAppBinding`, `createContractEffect`); the projections
 (`publicProjection`, `toOpenApi` with `JC0060`, `toTypeScript`,
 `toMarkdown`, `contractTools`); `contract.revision()` with `JC0061`,
@@ -574,3 +708,30 @@ patches, `JC2090–JC2095`, the generated app subscription with
 `createContractSubscription`, and the one SSE codec of the suite in
 `@jarenjs/core/text/sse`); and the `contract/*` locale packs in all
 eleven `@jarenjs/locales` languages, key parity enforced by test.
+
+## Exports
+
+Every subpath a consumer can import, derived from the manifest by
+`npm run docs:derive` (`npm run docs:check` fails when the two drift):
+
+<!--fact:exports.contract-->
+| Import | Kind | Declarations |
+|---|---|---|
+| `@jarenjs/contract` | JavaScript | declared |
+| `@jarenjs/contract/http` | JavaScript | declared |
+| `@jarenjs/contract/fetch` | JavaScript | declared |
+| `@jarenjs/contract/node` | JavaScript | declared |
+| `@jarenjs/contract/ledger` | JavaScript | declared |
+| `@jarenjs/contract/diff` | JavaScript | declared |
+| `@jarenjs/contract/client` | JavaScript | declared |
+| `@jarenjs/contract/local` | JavaScript | declared |
+| `@jarenjs/contract/port` | JavaScript | declared |
+| `@jarenjs/contract/stream` | JavaScript | declared |
+| `@jarenjs/contract/app` | JavaScript | declared |
+| `@jarenjs/contract/project` | JavaScript | declared |
+| `@jarenjs/contract/schemas/jaren-contract-port.draft-07.schema.json` | schema | — |
+| `@jarenjs/contract/schemas/jaren-contract-port.schema.json` | schema | — |
+| `@jarenjs/contract/schemas/jaren-contract.draft-07.schema.json` | schema | — |
+| `@jarenjs/contract/schemas/jaren-contract.schema.json` | schema | — |
+| `@jarenjs/contract/package.json` | metadata | — |
+<!--/fact-->

package/dist/types/adapters/fetch.d.ts

@@ -5,16 +5,17 @@
  * Dependency-free and structurally typed: it needs only the platform's
  * `Request`, `Response` and `Headers`.
  *
- * The adapter reads the body only when the matched operation can carry
- * one (`text()` for a JSON operation, `arrayBuffer()` for an opaque one),
- * refuses a declared `content-length` above the operation's limit
- * BEFORE reading (the dispatcher answers the 413 from the header), never
- * reads an unmatched request's body, and hands everything else to
- * `dispatch`. `Headers` combines repeated field lines with `, `, so a
- * repeated scalar header member is invisible here (the node adapter sees
- * distinct lines); `text()` decodes with replacement, so invalid UTF-8
- * reaches the JSON parser as U+FFFD (the node adapter hands bytes over
- * and the dispatcher's strict decode answers `JC2005`).
+ * The adapter hands the request's body stream to the dispatcher as a
+ * pull source only when the matched operation can carry one — a JSON
+ * operation drains it under its limit there (the strict UTF-8 decode
+ * decides `JC2005`, as through the node adapter), an opaque handler
+ * pulls it chunk by chunk — refuses a declared `content-length` above
+ * the operation's limit BEFORE reading (the dispatcher answers the 413
+ * from the header), never reads an unmatched request's body, and hands
+ * everything else to `dispatch`. A streamed response body becomes a
+ * `ReadableStream` that pulls one chunk per demand. `Headers` combines
+ * repeated field lines with `, `, so a repeated scalar header member is
+ * invisible here (the node adapter sees distinct lines).
  */
 export type HttpDispatcher = import('../http/serve.js').HttpDispatcher;
 /**

package/dist/types/adapters/node.d.ts

@@ -6,19 +6,27 @@
  * `headersDistinct` (or `headers`) and a readable-stream event surface,
  * the response anything with `writeHead`/`end`.
  *
- * The body is collected chunk by chunk up to the matched operation's
- * `policy.limits.maxBodyBytes`; on overflow the read stops, the 413 is
- * answered with `connection: close`, and once the response has flushed
- * the socket lingers — draining and discarding the rest of the upload
- * (bounded by a grace timer) before it is destroyed, so the close is a
- * FIN the peer can read the 413 through, not an RST that discards it. A declared `content-length` above the limit
- * is never read at all; an unmatched request's body is never read (the
+ * The body reaches the dispatcher as a PULL SOURCE over the request's
+ * own chunks — nothing is collected here: a JSON operation drains it
+ * under `policy.limits.maxBodyBytes` in the dispatcher (its strict
+ * UTF-8 decode decides `JC2005`), an opaque handler pulls it one chunk
+ * at a time through a source that never yields past the limit. When an
+ * upload was pulled and left unread (a limit crossing, a response
+ * before EOF) the answer carries `connection: close`, and once it has
+ * flushed the socket lingers — draining and discarding the rest of the
+ * upload (bounded by a grace timer) before it is destroyed, so the
+ * close is a FIN the peer can read the 413 through, not an RST that
+ * discards it. A declared `content-length` above the limit is never
+ * read at all; an unmatched request's body is never read (the
  * dispatcher answers 404/405 without it and the platform discards the
- * rest). Bytes are handed to the dispatcher as received — for a JSON
- * operation too, so its strict UTF-8 decode decides `JC2005`. Repeated
+ * rest). A streamed response body is written chunk by chunk behind the
+ * socket's `drain`. Repeated
  * header lines reach the dispatcher as arrays (`headersDistinct`), which
  * is how a repeated scalar header member becomes `JC2015`. `ctx.signal`
- * aborts when the client goes away before the response finished.
+ * aborts when the client goes away before the response finished. A
+ * streaming (SSE) response writes each event only after the previous
+ * one drained: a `res.write()` that answers `false` parks the pump
+ * until `drain`, so a slow reader never grows the process's buffers.
  */
 export type HttpDispatcher = import('../http/serve.js').HttpDispatcher;
 export type NodeRequestLike = {
@@ -37,9 +45,15 @@ export type NodeResponseLike = {
     writeHead: (status: number, headers?: Record<string, string>) => unknown;
     end: (body?: string | Uint8Array, callback?: () => void) => unknown;
     on: (event: string, listener: (...args: any[]) => void) => unknown;
+    once?: (event: string, listener: (...args: any[]) => void) => unknown;
+    removeListener?: (event: string, listener: (...args: any[]) => void) => unknown;
+    off?: (event: string, listener: (...args: any[]) => void) => unknown;
     write?: (chunk: string | Uint8Array) => unknown;
     flushHeaders?: () => unknown;
+    destroy?: (error?: Error) => unknown;
     writableFinished?: boolean;
+    writableEnded?: boolean;
+    destroyed?: boolean;
     headersSent?: boolean;
 };
 /**

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

@@ -15,10 +15,14 @@
  *
  * `invoke` NEVER rejects for anything a server or a network can do; it
  * throws only for the host's own mistakes (`JC1005`: an unknown or
- * opaque operation). `url(op, input)` builds the URL of any operation —
- * what an `<img src>` uses for an opaque one. `negotiate()` asks the
- * server's well-known description whether the two ends speak compatible
- * versions. Everything per operation is decided once at `open`.
+ * opaque operation). `bytes(op, input, ctx)` is the opaque twin: one
+ * request whose success value carries the status, the headers, the
+ * media and the LIVE response body as a `ReadableStream` — never
+ * `text()`, never collected — and whose `ctx.body` streams an upload.
+ * `url(op, input)` builds the URL of any operation — what an `<img src>`
+ * uses for an opaque one. `negotiate()` asks the server's well-known
+ * description whether the two ends speak compatible versions.
+ * Everything per operation is decided once at `open`.
  */
 import { JarenValidator } from '@jarenjs/validate';
 import { CLIENT_ERRORS } from './outcome.js';
@@ -48,7 +52,8 @@ export type HttpClientOptions = {
      */
     headers?: Record<string, string>;
     /**
-     * - the idempotency key generator; default `crypto.randomUUID`
+     * - the idempotency key generator; default
+     * the runtime record's `uuid`, itself `crypto.randomUUID` by default
      */
     keys?: () => string;
     /**
@@ -72,13 +77,20 @@ export type HttpClientOptions = {
      */
     wellKnown?: string;
     /**
-     * - the clock stamped into key records; default `Date.now`
+     * - the clock stamped into key records; default
+     * the runtime record's `now`, itself `Date.now` by default
      */
     now?: () => number;
     /**
      * - the validator `url()` compiles its path/query check with
      */
     validator?: JarenValidator<any>;
+    /**
+     * - the host's runtime record: its `uuid` generates idempotency keys
+     * and its `now` stamps key records, each only where `keys` / `now` is
+     * absent, and its `random` draws the retry backoff jitter
+     */
+    runtime?: Partial<import('@jarenjs/core/runtime').Runtime>;
 };
 export type InvokeContext = {
     /**
@@ -106,6 +118,38 @@ export type InvokeContext = {
      */
     ifMatch?: string;
 };
+export type ByteContext = {
+    /**
+     * - cancels the request (`kind: "cancelled"`)
+     */
+    signal?: AbortSignal;
+    /**
+     * - the caller's attempt id, echoed in `meta.attempt`, never sent
+     */
+    attempt?: unknown;
+    /**
+     * - per-call headers (over the static ones)
+     */
+    headers?: Record<string, string>;
+    /**
+     * - sent as `If-None-Match`
+     */
+    ifNoneMatch?: string;
+    /**
+     * - sent as `If-Match`
+     */
+    ifMatch?: string;
+    /**
+     * - the request body
+     */
+    body?: string | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | null;
+};
+export type ByteResponse = {
+    status: number;
+    headers: Record<string, string>;
+    media: string | null;
+    body: ReadableStream<Uint8Array> | null;
+};
 export type Negotiation = {
     compatible: boolean;
     reason: 'same-version' | 'server-accepts' | 'client-accepts' | 'version-mismatch' | 'unreachable' | 'not-a-contract';
@@ -144,6 +188,9 @@ export type SubscribeOptions = {
     onSnapshot?: (value: unknown, info: {
         seq: number;
         resumed: boolean;
+        reset: boolean;
+        earliestAvailable: number | null;
+        highWatermark: number | null;
     }) => void;
     onPatch?: (emission: {
         patch: unknown[];
@@ -158,15 +205,35 @@ export type SubscribeOptions = {
      */
     signal?: AbortSignal;
     /**
-     * - the resume seq (what a reconnect passes)
+     * - the resume seq (what a re-entered subscribe passes)
      */
     lastSeq?: number;
+    /**
+     * - opt into re-establishing the
+     * stream after a network loss: at most `max` further attempts, each
+     * after the retry backoff and from the last delivered seq; the budget
+     * spent, `onError` gets one `JC2097`. Absent (or `max: 0`), a network
+     * outcome is delivered as is
+     */
+    reconnect?: {
+        max: number;
+    };
+};
+export type Subscription = {
+    stop: () => void;
+    /**
+     * - read-only
+     */
+    lastSeq: number | null;
 };
 export type HttpClient = {
     invoke: (op: string, input?: unknown, ctx?: InvokeContext) => Promise<Outcome>;
-    subscribe: (op: string, input?: unknown, options?: SubscribeOptions) => {
-        stop: () => void;
-    };
+    /**
+     * - an
+     * opaque operation: the outcome's value is a {@link ByteResponse} (§10.6)
+     */
+    bytes: (op: string, input?: unknown, ctx?: ByteContext) => Promise<Outcome>;
+    subscribe: (op: string, input?: unknown, options?: SubscribeOptions) => Subscription;
     url: (op: string, input?: unknown) => string;
     negotiate: (options?: {
         signal?: AbortSignal;

package/dist/types/compat.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file Version compatibility — the one implementation of the
- * negotiation rule (docs/CONTRACT-FORMAT.md §10.4, §13.1): two ends
+ * negotiation rule (docs/CONTRACT-FORMAT.md §10.4, §13): two ends
  * speak when they declare the same `version`, or when either end's
  * `compat` list names the other's `version`. The client's `negotiate()`
  * and any server that wants to refuse an incompatible peer both call

package/dist/types/errors.d.ts

@@ -61,6 +61,7 @@ export declare const CONTRACT_CODES: Readonly<{
     JC1008: "openHttpClient, openPortClient, client.url, createContractEffect, createContractSubscription or a projection (publicProjection, toOpenApi, toTypeScript, toMarkdown, contractTools): an argument or option is malformed (not a compiled contract, fetch/keys/sleep/createTaskEffect/projectError not a function, storage without read/write, a non-object input to url, an ops entry naming no or an opaque operation, a tool name outside ^[a-zA-Z0-9_-]{1,64}$ or shared by two operations)";
     JC1009: "encodeSseEvent (the stream wire): an event, id or data string the SSE frame cannot carry — a bare carriage return inside data, a line terminator inside event or id";
     JC1010: "client.subscribe was asked for an operation that is not a subscribe operation (invoke carries reads and commands; subscribe carries streams)";
+    JC1011: "a ledger commit or fail named a ref that settles no started record: the key expired, was reclaimed under a newer generation, or was settled already — the settlement is refused; the binding reports it to onError and the response still goes out";
     JC2001: "no operation matches the request method and path (404)";
     JC2002: "the path shape is served under other methods (405, Allow lists them)";
     JC2003: "the request body exceeds policy.limits.maxBodyBytes, by content-length or by read length (413)";
@@ -96,6 +97,8 @@ export declare const CONTRACT_CODES: Readonly<{
     JC2093: "the stream ended with a server error event whose code the operation does not declare (kind contract; a declared code is a failure outcome under its own code)";
     JC2094: "the stream went silent for twice policy.stream.heartbeatMs (kind network, client-side)";
     JC2095: "a requested resume was refused — informational, carried as resumed:false in the fresh snapshot's event data, never an outcome";
+    JC2096: "the stream's bounded queue would overflow — the consumer reads slower than the source emits, or a replay page outran it (kind network, retryable; the stream ends with an error event carrying this code and the carrier tears the connection down)";
+    JC2097: "the client's reconnect budget is exhausted: every attempt after a network loss failed the same way (kind network, not retryable; details carry the attempts made and the last network code, client-side)";
 }>;
 /**
  * A defect in the contract document itself, raised while