@jarenjs/contract 0.49.2 → 0.66.1

package/src/http/serve.js

@@ -19,10 +19,14 @@
 import { compileMessageCatalog } from '@jarenjs/core/message';
 
 import { ContractHostError } from '../errors.js';
+import { resolveHostRuntime } from '../runtime.js';
+import { resolveStreamLimits } from '../stream/server.js';
+import { resolveLifecycle } from '../host.js';
 import { dispatch } from './dispatch.js';
 import { HTTP_ERRORS, WELL_KNOWN_PATH } from './wire.js';
+import { BodyLimitError } from './body.js';
 
-export { HTTP_ERRORS, WELL_KNOWN_PATH };
+export { HTTP_ERRORS, WELL_KNOWN_PATH, BodyLimitError };
 
 /**
  * @typedef {import('./wire.js').HttpRequest} HttpRequest
@@ -41,7 +45,8 @@ export { HTTP_ERRORS, WELL_KNOWN_PATH };
 /**
  * The options of `serveHttp`; every one has a default.
  * @typedef {Object} ServeHttpOptions
- * @property {() => string} [trace] - the server trace generator; default `crypto.randomUUID`
+ * @property {() => string} [trace] - the server trace generator; default
+ *   the runtime record's `uuid`, itself `crypto.randomUUID` by default
  * @property {Ledger | null} [ledger] - the idempotency ledger; `null` refuses
  *   (`JC1003`) any operation whose `policy.idempotency` is not `none`
  * @property {(ctx: RequestContext) => string} [scope] - the idempotency scope
@@ -66,7 +71,31 @@ export { HTTP_ERRORS, WELL_KNOWN_PATH };
  *   - observes `JC2008`/`JC2010` causes and ledger faults; the response never carries them
  * @property {Record<string, string | ((params: object) => string)>} [catalog]
  *   - a message catalog (templates or compiled renderers) consulted before the English one
- * @property {() => number} [now] - the clock stamped into ledger claims; default `Date.now`
+ * @property {() => number} [now] - the clock stamped into ledger claims;
+ *   default the runtime record's `now`, itself `Date.now` by default
+ * @property {Partial<import('@jarenjs/core/runtime').Runtime>} [runtime]
+ *   - the host's runtime record: its `uuid` generates the server trace
+ *   and its `now` is the clock, each only where `trace` / `now` is absent
+ * @property {{ replay?: { limit?: number, maxBytes?: number }, queue?: { events?: number, bytes?: number } }} [streamLimits]
+ *   - the bounds of every SSE 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` SSE bytes
+ *   (default 256 / 1 MiB) before the stream ends with `JC2096`
+ * @property {(meta: import('../host.js').IdentifyMeta) => unknown} [identify]
+ *   - the host lifecycle's first hook (docs/CONTRACT-FORMAT.md §7.7):
+ *   runs after the route resolved and before any byte of the body is
+ *   read; answers a lease `{ host, release? }` — `host` is what `scope`
+ *   and, without `acquire`, the handler see as `ctx.host` — or a
+ *   declared failure (`meta.fail`); default `{ host: null }`
+ * @property {(input: unknown, identity: RequestContext, enter: (lease: unknown) => Promise<unknown>) => unknown} [acquire]
+ *   - the second hook: runs after the input validated and, on a claimed
+ *   command, after the claim answered `new`; calls `enter({ host,
+ *   release?, settlement? })` exactly once and answers what `enter`
+ *   answers — a host that opens a transaction around `enter` commits it
+ *   when `enter` resolves and rolls it back when it rejects; `settlement:
+ *   { ledger, required: true }` records the claim through that ledger
+ *   inside `enter`; default `enter({ host: identity.host })`
  */
 
 /**
@@ -287,12 +316,15 @@ export function serveHttp(contract, handlers, options = {}) {
   if (options.catalog !== undefined && (options.catalog === null || typeof options.catalog !== 'object')) {
     throw host('JC1001', 'options.catalog must be a message catalog object');
   }
+  const runtime = resolveHostRuntime(options.runtime, host, 'JC1001');
+  const streamLimits = resolveStreamLimits(options.streamLimits, (reason) => host('JC1001', reason));
+  const lifecycle = resolveLifecycle(options, (reason) => host('JC1001', reason));
 
   /** @type {Server} */
   const server = {
     contract,
     routes,
-    trace: options.trace === undefined ? () => globalThis.crypto.randomUUID() : options.trace,
+    trace: options.trace === undefined ? runtime.uuid : options.trace,
     ledger,
     scope: options.scope === undefined ? () => '' : options.scope,
     head,
@@ -301,9 +333,11 @@ export function serveHttp(contract, handlers, options = {}) {
     errorBody: options.errorBody === undefined ? null : options.errorBody,
     onError: options.onError === undefined ? null : options.onError,
     catalog: options.catalog === undefined ? null : compileMessageCatalog(options.catalog),
-    now: options.now === undefined ? Date.now : options.now,
+    now: options.now === undefined ? runtime.now : options.now,
     described: { text: null },
     streams: new Set(),
+    streamLimits,
+    lifecycle,
   };
 
   /** @type {HttpCapabilities} */

package/src/http/wire.js

@@ -24,30 +24,44 @@ import { contractCatalogEn } from '../messages.js';
  * test hands to `dispatch` directly. `url` is origin-less: the path plus
  * an optional `?query`; header names are lowercase; a header value is a
  * string, or an array of strings when the adapter can see repeated field
- * lines; `body` is the bytes/text as received (`null` for none);
- * `signal` is the request's abort signal when the host has one.
+ * lines; `body` is the text or bytes as received, or a pull source of
+ * chunks (an async iterable, or a Web `ReadableStream` the dispatcher
+ * normalizes) the pipeline drains under the operation's limit for a
+ * JSON operation and hands an opaque handler one chunk at a time
+ * (`null` for none); `signal` is the request's abort signal when the
+ * host has one.
  * @typedef {Object} HttpRequest
  * @property {string} method
  * @property {string} url
  * @property {Readonly<Record<string, string | readonly string[]>>} headers
- * @property {string | Uint8Array | null} body
+ * @property {string | Uint8Array | AsyncIterable<Uint8Array> | ReadableStream<Uint8Array> | null} body
  * @property {AbortSignal | null} [signal]
  */
 
 /**
  * A response as the binding answers it: a status, lowercase header names,
- * and a body that is a string (JSON text), bytes (an opaque operation) or
- * `null` (HEAD, 204, 304). A streaming response (a subscribe operation
+ * and a body that is a string (JSON text), bytes (an opaque operation), a
+ * pull source of chunks (an opaque handler's streamed body: the adapter
+ * writes it chunk by chunk behind the socket's backpressure and cancels
+ * it once when the peer goes away) or `null` (HEAD, 204, 304). A
+ * streaming response (a subscribe operation
  * under `accept: text/event-stream`) carries `body: null` plus `stream`:
  * the adapter writes the headers, then MUST call `stream` exactly once
  * with its sink — the pump writes SSE text through `sink.write` and
- * calls `sink.end()` when the stream terminates; the returned function
- * stops the stream when the consumer cancels.
+ * calls `sink.end()` when the stream terminates. The sink is a
+ * `SinkLike<string>` (`@jarenjs/core/async`): `write` may answer a
+ * promise that settles when the platform has taken the chunk — a Node
+ * response that answered `false` resolves on `drain`; a Web stream
+ * bridge resolves on the consumer's pull — and the pump writes the next
+ * chunk only after that; the optional `abort(reason)` is how the pump
+ * tears the carrier down when it must. The pump answers `{ stop, done }`:
+ * `stop()` ends the stream when the consumer cancels, `done` settles
+ * once the subscription is released and the sink has ended.
  * @typedef {Object} HttpResponse
  * @property {number} status
  * @property {Readonly<Record<string, string>>} headers
- * @property {string | Uint8Array | null} body
- * @property {(sink: { write: (chunk: string) => void, end: () => void }) => (() => void)} [stream]
+ * @property {string | Uint8Array | AsyncIterable<Uint8Array> | null} body
+ * @property {(sink: import('@jarenjs/core/async').SinkLike<string>) => { stop: () => void, done: Promise<void> }} [stream]
  */
 
 /**
@@ -249,8 +263,8 @@ export function exceedsBytes(body, limit) {
 //#region entity tags
 
 /**
- * Parse an `If-Match`/`If-None-Match` field into its opaque tags. `*` is
- * reported as `null` in the list; a weak indicator is dropped
+ * Parse an `If-Match`/`If-None-Match` field into its opaque tags. `*` sets
+ * `any`; commas inside quoted tags are retained. A weak indicator is dropped
  * (`W/"x"` → `x`) — the caller decides weak/strong comparison because a
  * strong comparison must reject weak tags, which `weak[i]` records.
  * @param {string} value
@@ -262,9 +276,14 @@ export function parseEntityTags(value) {
   /** @type {boolean[]} */
   const weak = [];
   let any = false;
-  const parts = value.split(',');
-  for (let i = 0; i < parts.length; i++) {
-    let part = parts[i].trim();
+  let start = 0;
+  let quoted = false;
+  for (let i = 0; i <= value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code === 0x22) quoted = !quoted;
+    if (i < value.length && (code !== 0x2c || quoted)) continue;
+    let part = value.slice(start, i).trim();
+    start = i + 1;
     if (part === '*') {
       any = true;
       continue;

package/src/ledger.js

@@ -16,11 +16,19 @@
  * fresh one.
  */
 
+import { resolveRuntime } from '@jarenjs/core/runtime';
+
+import { ContractHostError } from './errors.js';
+
 /**
  * The record a ledger keeps per `(op, scope, key)`; the schema of
  * `idempotencyLedgerModel`'s collection.
  * @typedef {Object} LedgerRecord
- * @property {string} id - `"<op>|<scope>|<key>"`
+ * @property {string} id - {@link ledgerId} of the tuple
+ * @property {string} generation - the identity of the claim that started
+ *   this record: minted per `started` record, carried by the `ref`, and
+ *   verified by `commit`/`fail` — a ref of an earlier generation settles
+ *   nothing (`JC1011`)
  * @property {string} op
  * @property {string} scope
  * @property {string} key
@@ -33,11 +41,18 @@
  * @property {number} expiresAt - epoch ms
  */
 
+/**
+ * The ref a `new` claim hands back and a settlement names: the record's
+ * `id` and the `generation` the claim minted — portable across
+ * processes, and stale the moment the key expires or is reclaimed.
+ * @typedef {{ readonly id: string, readonly generation: string }} LedgerRef
+ */
+
 /**
  * The claim result: `new` hands back a `ref` to commit or fail; `replay`
  * carries the stored response; `in-progress` and `mismatch` are the two
  * 409 answers.
- * @typedef {{ state: 'new', ref: unknown }
+ * @typedef {{ state: 'new', ref: LedgerRef }
  *   | { state: 'replay', response: any }
  *   | { state: 'in-progress' }
  *   | { state: 'mismatch' }} ClaimResult
@@ -51,26 +66,50 @@
  * different hash → `mismatch`; `started` and unexpired → `in-progress`;
  * `failed` with `retryable: true` → `new` (the key may be retried);
  * `failed` and not retryable → `replay` of the stored failure. `now` on
- * a claim is the binding's clock (epoch ms) a ledger may prefer to its
- * own.
+ * a claim, a commit, a failure and a lookup is the binding's clock
+ * (epoch ms): ONE clock must judge a record from claim to expiry, so a
+ * ledger that has no clock of its own follows the binding's, and a
+ * ledger with its own clock is given the same record as the binding
+ * (`runtime`) rather than a second one. A `commit`/`fail` whose ref
+ * settles no `started` record — expired, reclaimed under a newer
+ * generation, or settled already — throws (or rejects) `JC1011`; the
+ * binding reports it to `onError` and the response still goes out.
  * @typedef {Object} Ledger
  * @property {(claim: { op: string, scope: string, key: string, hash: string, now?: number }) => ClaimResult | Promise<ClaimResult>} claim
- * @property {(ref: unknown, response: any) => void | Promise<void>} commit
- * @property {(ref: unknown, retryable: boolean, response?: any) => void | Promise<void>} fail
- * @property {(key: { op: string, scope: string, key: string }) => LedgerRecord | null | Promise<LedgerRecord | null>} lookup
+ * @property {(ref: unknown, response: any, now?: number) => void | Promise<void>} commit
+ * @property {(ref: unknown, retryable: boolean, response?: any, now?: number) => void | Promise<void>} fail
+ * @property {(key: { op: string, scope: string, key: string, now?: number }) => LedgerRecord | null | Promise<LedgerRecord | null>} lookup
  */
 
 /** One day, the default retention of a key. */
 const DEFAULT_TTL_MS = 86_400_000;
 
 /**
+ * The id of one `(op, scope, key)` tuple: the version `1`, a colon, the
+ * JSON array of the three. Injective — a `|`, a control character or
+ * any Unicode inside a member cannot spell another tuple — and readable
+ * in a store. A record written under the legacy `"<op>|<scope>|<key>"`
+ * spelling is matched by no claim again: it expires by its own
+ * `expiresAt` (`sweep`), or a host rewrites its `id` once
+ * (docs/CONTRACT-FORMAT.md §8).
  * @param {string} op
  * @param {string} scope
  * @param {string} key
  * @returns {string}
  */
-function idOf(op, scope, key) {
-  return `${op}|${scope}|${key}`;
+export function ledgerId(op, scope, key) {
+  return `1:${JSON.stringify([op, scope, key])}`;
+}
+
+/**
+ * The `JC1011` refusal of a settlement whose ref settles no started record.
+ * @param {unknown} ref
+ * @returns {ContractHostError}
+ */
+function staleSettlement(ref) {
+  const r = /** @type {any} */ (ref);
+  const named = r !== null && typeof r === 'object' && typeof r.id === 'string' ? r.id : 'a ref this ledger did not issue';
+  return new ContractHostError('JC1011', `ledger: ${named} settles no started record — the key expired, was reclaimed under a newer generation, or was settled already`);
 }
 
 /**
@@ -78,21 +117,64 @@ function idOf(op, scope, key) {
  * expiring on `claim` (a record past `expiresAt` is dropped and the key
  * is `new` again). `sweep()` drops every expired record — a host may
  * call it on a timer.
- * @param {{ ttlMs?: number, now?: () => number }} [options]
- * @returns {Ledger & { sweep(): number, size: number }}
+ * ONE clock judges a record from claim to expiry. The ledger's own clock
+ * is `now`, else the runtime record's `now` (`@jarenjs/core/runtime`);
+ * given neither, the ledger has no clock of its own and FOLLOWS the
+ * binding: every stamp and every expiry decision uses the instant the
+ * binding passed with the call, and a host-side `lookup`/`sweep` that
+ * passes none uses the latest instant a binding reported. (A record
+ * stamped by an injected server clock and judged by the platform's was
+ * dropped as expired the moment `sweep()` ran, and the command ran
+ * twice.) A ledger WITH its own clock uses it for everything and is
+ * given the same record as the binding, never a second one. The runtime
+ * record's `uuid` mints each record's `generation`; `lookup` answers a
+ * copy, never the ledger's own record.
+ * @param {{ ttlMs?: number, now?: () => number,
+ *   runtime?: Partial<import('@jarenjs/core/runtime').Runtime> }} [options]
+ * @returns {Ledger & { sweep(now?: number): number, size: number }}
  */
 export function createMemoryLedger(options = {}) {
   const ttlMs = options.ttlMs === undefined ? DEFAULT_TTL_MS : options.ttlMs;
   if (!Number.isFinite(ttlMs) || ttlMs <= 0) throw new TypeError('createMemoryLedger: ttlMs must be a positive number');
-  const clock = options.now === undefined ? Date.now : options.now;
+  let runtime;
+  try {
+    runtime = resolveRuntime(options.runtime);
+  }
+  catch (error) {
+    throw new TypeError(`createMemoryLedger: runtime: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const clock = options.now === undefined ? runtime.now : options.now;
   if (typeof clock !== 'function') throw new TypeError('createMemoryLedger: now must be a function');
+  const ownClock = options.now !== undefined || options.runtime !== undefined;
+  /** The latest instant a binding reported, for a ledger without a clock. */
+  let latest = null;
+  /** The instant a call is judged and stamped at. */
+  const instant = (/** @type {number | undefined} */ given) => {
+    if (typeof given === 'number') {
+      if (!ownClock) latest = latest === null ? given : Math.max(latest, given);
+      return given;
+    }
+    return ownClock || latest === null ? clock() : latest;
+  };
   /** @type {Map<string, LedgerRecord>} */
   const records = new Map();
 
+  /**
+   * The started record a ref settles, or the `JC1011` refusal.
+   * @param {unknown} ref
+   * @returns {LedgerRecord}
+   */
+  function settling(ref) {
+    const r = /** @type {any} */ (ref);
+    const record = r !== null && typeof r === 'object' && typeof r.id === 'string' ? records.get(r.id) : undefined;
+    if (record === undefined || record.generation !== r.generation || record.status !== 'started') throw staleSettlement(ref);
+    return record;
+  }
+
   return {
     claim({ op, scope, key, hash, now }) {
-      const at = typeof now === 'number' ? now : clock();
-      const id = idOf(op, scope, key);
+      const at = instant(now);
+      const id = ledgerId(op, scope, key);
       const existing = records.get(id);
       if (existing !== undefined) {
         if (existing.expiresAt <= at) records.delete(id);
@@ -102,41 +184,40 @@ export function createMemoryLedger(options = {}) {
         else if (existing.retryable !== true && existing.response !== null) return { state: 'replay', response: existing.response };
         else records.delete(id);
       }
+      const generation = runtime.uuid();
       /** @type {LedgerRecord} */
       const record = {
-        id, op, scope, key, hash, status: 'started', response: null, retryable: null,
+        id, generation, op, scope, key, hash, status: 'started', response: null, retryable: null,
         createdAt: at, updatedAt: at, expiresAt: at + ttlMs,
       };
       records.set(id, record);
-      return { state: 'new', ref: record };
+      return { state: 'new', ref: Object.freeze({ id, generation }) };
     },
-    commit(ref, response) {
-      const record = /** @type {LedgerRecord} */ (ref);
-      if (records.get(record.id) !== record) return;
+    commit(ref, response, now = undefined) {
+      const record = settling(ref);
       record.status = 'committed';
       record.response = response;
       record.retryable = null;
-      record.updatedAt = clock();
+      record.updatedAt = instant(now);
     },
-    fail(ref, retryable, response) {
-      const record = /** @type {LedgerRecord} */ (ref);
-      if (records.get(record.id) !== record) return;
+    fail(ref, retryable, response, now = undefined) {
+      const record = settling(ref);
       record.status = 'failed';
       record.retryable = retryable === true;
       record.response = response === undefined ? null : response;
-      record.updatedAt = clock();
+      record.updatedAt = instant(now);
     },
-    lookup({ op, scope, key }) {
-      const record = records.get(idOf(op, scope, key));
+    lookup({ op, scope, key, now = undefined }) {
+      const record = records.get(ledgerId(op, scope, key));
       if (record === undefined) return null;
-      if (record.expiresAt <= clock()) {
+      if (record.expiresAt <= instant(now)) {
         records.delete(record.id);
         return null;
       }
-      return record;
+      return { ...record };
     },
-    sweep() {
-      const at = clock();
+    sweep(now = undefined) {
+      const at = instant(now);
       let dropped = 0;
       for (const [id, record] of records) {
         if (record.expiresAt <= at) {
@@ -154,11 +235,12 @@ export function createMemoryLedger(options = {}) {
 
 /**
  * The `$model` 0.1 document of a durable ledger: one collection,
- * `ledger`, keyed by `/id` (`"<op>|<scope>|<key>"`), indexed on
- * `expiresAt` (the sweep) and `status` (the in-flight scan). A host
- * opens it with `@jarenjs/db`'s `openStore` and implements the `Ledger`
- * interface over the collection; the record shape is exactly what
- * `createMemoryLedger` keeps.
+ * `ledger`, keyed by `/id` ({@link ledgerId}), indexed on `expiresAt`
+ * (the sweep) and `status` (the in-flight scan). A host opens it with
+ * `@jarenjs/db`'s `openStore` and implements the `Ledger` interface over
+ * the collection — `createDbLedger` in `@jarenjs/linq/db` is that
+ * implementation over the typed client; the record shape is exactly
+ * what `createMemoryLedger` keeps, the `generation` included.
  */
 export const idempotencyLedgerModel = Object.freeze({
   $model: '0.1',
@@ -166,9 +248,10 @@ export const idempotencyLedgerModel = Object.freeze({
     ledger: {
       schema: {
         type: 'object',
-        required: ['id', 'op', 'scope', 'key', 'hash', 'status', 'response', 'retryable', 'createdAt', 'updatedAt', 'expiresAt'],
+        required: ['id', 'generation', 'op', 'scope', 'key', 'hash', 'status', 'response', 'retryable', 'createdAt', 'updatedAt', 'expiresAt'],
         properties: {
           id: { type: 'string', minLength: 1 },
+          generation: { type: 'string', minLength: 1 },
           op: { type: 'string', minLength: 1 },
           scope: { type: 'string' },
           key: { type: 'string', minLength: 1 },

package/src/local/index.js

@@ -33,7 +33,9 @@
 import { compileMessageCatalog } from '@jarenjs/core/message';
 
 import { ContractHostError, ContractFailure } from '../errors.js';
-import { validateOperationInput, settleOperation, safeTrace, PORT_LOCAL_ERRORS } from '../pipeline.js';
+import { validateOperationInput, settleOperation, safeTrace, PORT_LOCAL_ERRORS, classifyDeclared } from '../pipeline.js';
+import { resolveLifecycle, identify as identifyHost, acquire as acquireHost, once, RollbackCarrier } from '../host.js';
+import { resolveHostRuntime } from '../runtime.js';
 import { renderMessage, declaredMessage } from '../http/wire.js';
 import {
   prepareOutcomeRoute, assembleOutcome, makeMeta, failedOutcome, outcomeError, clientError,
@@ -53,7 +55,11 @@ export { PORT_LOCAL_ERRORS };
 
 /**
  * @typedef {Object} LocalOptions
- * @property {() => string} [trace] - the trace generator; default `crypto.randomUUID`
+ * @property {() => string} [trace] - the trace generator; default the
+ *   runtime record's `uuid`, itself `crypto.randomUUID` by default
+ * @property {Partial<import('@jarenjs/core/runtime').Runtime>} [runtime]
+ *   - the host's runtime record: its `uuid` generates the trace where
+ *   `trace` is absent
  * @property {'always' | 'never'} [validateOutput] - `'never'` is a declared
  *   downgrade, reported in `capabilities.validatedOutput`
  * @property {Record<string, string | ((params: object) => string)>} [catalog]
@@ -152,6 +158,12 @@ function prepare(op, handler) {
 function race(settled, signal) {
   return new Promise((resolve) => {
     const onAbort = () => resolve(ABORTED);
+    // a signal already aborted when the race begins fires no event: it
+    // is an abort all the same, and the settlement lands into nothing
+    if (signal.aborted) {
+      resolve(ABORTED);
+      return;
+    }
     signal.addEventListener('abort', onAbort, { once: true });
     settled.then((result) => {
       signal.removeEventListener('abort', onAbort);
@@ -210,7 +222,9 @@ export function openLocalClient(contract, handlers, options = {}) {
   if (options.catalog !== undefined && (options.catalog === null || typeof options.catalog !== 'object')) {
     throw host('JC1001', 'options.catalog must be a message catalog object');
   }
-  const trace = options.trace === undefined ? () => globalThis.crypto.randomUUID() : options.trace;
+  const runtime = resolveHostRuntime(options.runtime, host, 'JC1001');
+  const lifecycle = resolveLifecycle(options, (reason) => host('JC1001', reason));
+  const trace = options.trace === undefined ? runtime.uuid : options.trace;
   const onError = options.onError === undefined ? null : options.onError;
   /** @type {Catalog | null} */
   const catalog = options.catalog === undefined ? null : compileMessageCatalog(options.catalog);
@@ -279,13 +293,59 @@ export function openLocalClient(contract, handlers, options = {}) {
     const meta = makeMeta(route.outcome.id, ctx.attempt, null);
     const caller = ctx.signal === undefined || ctx.signal === null ? null : ctx.signal;
     if ((caller !== null && caller.aborted) || closed) return cancelled(route, meta);
+    const signal = caller === null ? closer.signal : AbortSignal.any([closer.signal, caller]);
+    const id = safeTrace(trace);
+    meta.trace = id;
+    const opId = route.outcome.id;
+    const observed = (/** @type {unknown} */ error) => observe(error, { op: opId, trace: id });
+    /** @param {import('../pipeline.js').OperationResult} result */
+    const outcomeOf = (result) => {
+      if (result.kind === 'contract') {
+        if (result.cause !== undefined) observed(result.cause);
+        return failedOutcome('contract', outcomeError('JC2070',
+          renderMessage(catalog, PORT_LOCAL_ERRORS.JC2070.msgid, { op: opId }), null, null, false), meta);
+      }
+      if (result.kind === 'failure') {
+        return assembleOutcome(route.outcome, {
+          status: null,
+          headers: null,
+          error: {
+            code: result.code,
+            message: declaredMessage(catalog, opId, result.code, result.params),
+            details: result.details,
+            retryable: result.retryable,
+          },
+        }, meta, catalog);
+      }
+      return assembleOutcome(route.outcome, { status: null, headers: null, value: result.value }, meta, catalog);
+    };
+    /** The binding's host fault as an outcome. @param {unknown} cause */
+    const hostFault = (cause) => {
+      observed(cause);
+      return failedOutcome('contract', outcomeError('JC2070',
+        renderMessage(catalog, PORT_LOCAL_ERRORS.JC2070.msgid, { op: opId }), null, null, false), meta);
+    };
+
+    // 1. identify — before the input is judged (§7.7)
+    const identified = await identifyHost(lifecycle, Object.freeze({
+      op: route.op, trace: id, signal, carrier: /** @type {const} */ ('local'), method: null, path: null, headers: null, fail: ContractFailure,
+    }));
+    if (identified.kind === 'fault') return hostFault(identified.cause);
+    if (identified.kind === 'failure') return outcomeOf(classifyDeclared(route, identified.failure));
+    const identity = once(identified.lease.release, observed);
+    /** @type {(() => Promise<boolean>) | null} */
+    let acquired = null;
+    const release = () => (acquired === null ? identity() : acquired().then((a) => identity().then((b) => a && b)));
+    /** Release, then answer: a release that fails before the outcome is exposed is the host's fault — its cause was observed as it failed. @param {import('../client/outcome.js').Outcome} outcome */
+    const expose = async (outcome) => ((await release()) ? outcome : failedOutcome('contract', outcomeError('JC2070',
+      renderMessage(catalog, PORT_LOCAL_ERRORS.JC2070.msgid, { op: opId }), null, null, false), meta));
 
-    // 1. validate — the same verdict the pipeline would reach, once
+    // 2. validate — the same verdict the pipeline would reach, once
     let value;
     if (!route.hasInput) {
       if (input !== undefined && input !== null) {
-        return failedOutcome('contract', clientError(catalog, 'JC2050', { op: route.outcome.id }, null,
-          [{ path: '', keyword: 'input' }]), meta);
+        return expose(failedOutcome('contract', clientError(catalog, 'JC2050', { op: opId }, null,
+          [{ path: '', keyword: 'input' }]), meta));
       }
       value = null;
     }
@@ -294,40 +354,36 @@ export function openLocalClient(contract, handlers, options = {}) {
       const invalid = validateOperationInput(route, value);
       if (invalid !== null && invalid.kind === 'contract') {
         if (invalid.cause !== undefined) observe(invalid.cause, null);
-        return failedOutcome('contract', clientError(catalog, 'JC2050', { op: route.outcome.id }, null, invalid.details), meta);
+        return expose(failedOutcome('contract', clientError(catalog, 'JC2050', { op: opId }, null, invalid.details), meta));
       }
     }
+    // an abort that landed while identity ran is the race's to settle: the
+    // handler is still invoked with the aborted signal — told to stop, as
+    // a superseded attempt always was — and its settlement is dropped
 
-    // 2. run the neutral pipeline under the composed signal
-    const signal = caller === null ? closer.signal : AbortSignal.any([closer.signal, caller]);
-    const id = safeTrace(trace);
-    meta.trace = id;
-    const handlerCtx = Object.freeze({
-      op: route.op, trace: id, signal, params: null, headers: NO_HEADERS,
-      fail: ContractFailure, idempotency: null,
+    // 3. acquire, then the neutral pipeline inside enter under the composed signal
+    const identityCtx = Object.freeze({
+      op: route.op, trace: id, carrier: /** @type {const} */ ('local'), host: identified.lease.host, signal,
+      method: null, path: null, params: null, headers: NO_HEADERS, body: null,
+      fail: ContractFailure, idempotency: null, etag: null, status: null,
+    });
+    const out = await acquireHost(lifecycle, value, identityCtx, (lease) => {
+      acquired = once(lease.release, observed);
+      const handlerCtx = Object.freeze({ ...identityCtx, host: lease.host });
+      return race(settleOperation(route, value, handlerCtx, validate), signal).then((result) => {
+        // a host fault rejects enter with the carrier: a transaction around it rolls back, the fault stands
+        if (result !== ABORTED && result.kind === 'contract') throw new RollbackCarrier(result, result.cause);
+        return result;
+      });
     });
-    const result = await race(settleOperation(route, value, handlerCtx, validate), signal);
-    if (result === ABORTED) return cancelled(route, meta);
+    if (out.kind === 'fault') return expose(hostFault(out.cause));
+    if (out.kind === 'failure') return expose(outcomeOf(classifyDeclared(route, out.failure)));
+    if (out.afterFault !== undefined) observed(out.afterFault);
+    const result = /** @type {import('../pipeline.js').OperationResult | typeof ABORTED} */ (out.result);
+    if (result === ABORTED) return expose(cancelled(route, meta));
 
-    // 3. assemble the D6 outcome
-    if (result.kind === 'contract') {
-      if (result.cause !== undefined) observe(result.cause, { op: route.outcome.id, trace: id });
-      return failedOutcome('contract', outcomeError('JC2070',
-        renderMessage(catalog, PORT_LOCAL_ERRORS.JC2070.msgid, { op: route.outcome.id }), null, null, false), meta);
-    }
-    if (result.kind === 'failure') {
-      return assembleOutcome(route.outcome, {
-        status: null,
-        headers: null,
-        error: {
-          code: result.code,
-          message: declaredMessage(catalog, route.outcome.id, result.code, result.params),
-          details: result.details,
-          retryable: result.retryable,
-        },
-      }, meta, catalog);
-    }
-    return assembleOutcome(route.outcome, { status: null, headers: null, value: result.value }, meta, catalog);
+    // 4. assemble the D6 outcome
+    return expose(outcomeOf(result));
   }
 
   /** @type {LocalCapabilities} */

package/src/messages.js

@@ -62,6 +62,8 @@ export const contractMessagesEn = Object.freeze({
   '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). */

package/src/path.js

@@ -211,6 +211,9 @@ export function parsePathTemplate(source) {
     else {
       checkStaticSegment(source, pos, end);
       const text = source.slice(pos, end);
+      if (decodeSegment(text) === null) {
+        throw new TypeError(`a malformed percent-escape in segment "${text}"`);
+      }
       segments.push({ variable: false, text });
       canonical += `/${text}`;
     }
@@ -221,8 +224,10 @@ export function parsePathTemplate(source) {
 }
 
 /**
- * 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}
  */
@@ -231,7 +236,8 @@ export function pathShape(parsed) {
   let out = '';
   for (let i = 0; i < parsed.segments.length; i++) {
     const s = parsed.segments[i];
-    out += s.variable ? '/{}' : `/${s.text}`;
+    out += s.variable ? '/{}' : '/' + decodeURIComponent(s.text).replace(/[%/{}]/g,
+      (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
   }
   return out;
 }