@jarenjs/contract 0.56.0 → 0.67.0

package/dist/types/host.d.ts

@@ -0,0 +1,179 @@
+/**
+ * @file The host lifecycle (docs/CONTRACT-FORMAT.md §7.7): one
+ * carrier-neutral coordinator every server binding runs a request
+ * through. A host names two hooks at construction — `identify(meta)`,
+ * before anything of the request is parsed, and `acquire(input,
+ * identity, enter)`, after the input validated and (on HTTP) the
+ * idempotency claim answered `new` — each answering a LEASE `{ host,
+ * release? }` the handler sees as `ctx.host`, or a declared failure the
+ * binding renders like the handler's own. `acquire` hands its lease to
+ * `enter`, the binding's continuation that runs the handler, validates
+ * the output, serializes the response and — when the lease carries
+ * `settlement: { ledger, required: true }` — settles the idempotency
+ * claim through that ledger BEFORE `enter` resolves, so a host that
+ * opened a transaction around `enter` commits the domain write and the
+ * receipt together or not at all. Releases run once each, acquired
+ * before identity, at the boundary the binding declares (the response
+ * exposed, the opaque body settled, the stream done).
+ *
+ * The defaults are exactly `identify → { host: null }` and `acquire →
+ * enter({ host: identity.host })`: a host that names only `identify`
+ * sees its host in `scope(ctx)` and in the handler; one that names
+ * `acquire` owns the handler's host. Every returned lease is validated
+ * by shape (an object with an own `host`); a hook that throws, answers
+ * a malformed lease, never calls `enter` or calls it twice is the host's
+ * fault — observed through the binding's observer and rendered as the
+ * binding's host-fault code (`JC2008` on HTTP, `JC2070` on port and
+ * local); a declared failure is recognized by the `ContractFailure`
+ * brand, never by shape, and validated against the operation like a
+ * handler's. No policy data of the hooks reaches a wire.
+ */
+import { ContractFailure } from './errors.js';
+export type IdentifyMeta = {
+    op: import('./compile.js').CompiledOperation;
+    trace: string;
+    signal: AbortSignal | null;
+    carrier: 'http' | 'port' | 'local';
+    /**
+     * - the request line on HTTP; `null` elsewhere
+     */
+    method: string | null;
+    path: string | null;
+    /**
+     * - the raw request headers on HTTP; `null` elsewhere
+     */
+    headers: Readonly<Record<string, string | readonly string[]>> | null;
+    /**
+     * - the declared-failure factory
+     */
+    fail: typeof ContractFailure;
+};
+export type Lease = {
+    host: unknown;
+    release: (() => unknown) | undefined;
+    settlement: {
+        ledger: import('./ledger.js').Ledger;
+        required: true;
+    } | null;
+};
+export type Lifecycle = {
+    identify: (meta: IdentifyMeta) => unknown;
+    acquire: (input: unknown, identity: {
+        host: unknown;
+    }, enter: (lease: unknown) => unknown) => unknown;
+};
+/**
+ * A host fault of the lifecycle: what the binding observes and renders
+ * as its host-fault code.
+ */
+export declare class HostLifecycleError extends Error {
+    /**
+     * @param {string} message
+     * @param {unknown} [cause]
+     */
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Validate the hooks a binding was given; each defaults. Rejections are
+ * the binding's `JC1001` through `host`.
+ * @param {{ identify?: unknown, acquire?: unknown }} options
+ * @param {(reason: string) => Error} host - the binding's construction refusal
+ * @returns {Lifecycle}
+ */
+export declare function resolveLifecycle(options: {
+    identify?: unknown;
+    acquire?: unknown;
+}, host: (reason: string) => Error): Lifecycle;
+/**
+ * Read a hook's answer as a lease: an object with an own `host`, an
+ * optional function `release`, and (when `acquired`) an optional
+ * `settlement` whose `ledger` has `commit`/`fail` and whose `required`
+ * is `true`. Anything else is the host's fault.
+ * @param {unknown} value
+ * @param {'identify' | 'acquire'} hook
+ * @returns {Lease}
+ * @throws {HostLifecycleError}
+ */
+export declare function leaseOf(value: unknown, hook: 'identify' | 'acquire'): Lease;
+/**
+ * A release that runs at most once, whatever the number of exits that
+ * reach it; its own failure is handed to `observed` and swallowed, and
+ * the answer says whether the release was clean (`true`) — a later
+ * call answers `true` without running anything again.
+ * @param {(() => unknown) | undefined} release
+ * @param {(error: unknown) => void} observed
+ * @returns {() => Promise<boolean>}
+ */
+export declare function once(release: (() => unknown) | undefined, observed: (error: unknown) => void): () => Promise<boolean>;
+/**
+ * Classify a hook's settled answer: a lease, a declared failure, or a
+ * host fault. Total for hostile values.
+ * @param {unknown} value
+ * @param {'identify' | 'acquire'} hook
+ * @returns {{ kind: 'lease', lease: Lease } | { kind: 'failure', failure: import('./errors.js').ContractFailureValue } | { kind: 'fault', cause: unknown }}
+ */
+export declare function classifyAnswer(value: unknown, hook: 'identify' | 'acquire'): {
+    kind: 'lease';
+    lease: Lease;
+} | {
+    kind: 'failure';
+    failure: import('./errors.js').ContractFailureValue;
+} | {
+    kind: 'fault';
+    cause: unknown;
+};
+/**
+ * Run `identify`: the hook's answer (sync or async) classified.
+ * @param {Lifecycle} lifecycle
+ * @param {IdentifyMeta} meta
+ * @returns {Promise<ReturnType<typeof classifyAnswer>> | ReturnType<typeof classifyAnswer>}
+ */
+export declare function identify(lifecycle: Lifecycle, meta: IdentifyMeta): Promise<ReturnType<typeof classifyAnswer>> | ReturnType<typeof classifyAnswer>;
+/**
+ * The private carrier a required settlement's failure travels in: the
+ * wire fault the dispatcher intends is preserved while the host's
+ * transaction around `enter` rolls back on the rejection.
+ */
+export declare class RollbackCarrier extends Error {
+    response: unknown;
+    /**
+     * @param {unknown} response - the response the binding will answer
+     * @param {unknown} cause - what failed inside `enter`
+     */
+    constructor(response: unknown, cause: unknown);
+}
+/**
+ * Run `acquire` around `enter`. `enter` receives the validated lease and
+ * answers the binding's result (a response, an outcome) or a promise of
+ * it; what the hook itself answers is the value of `enter` — a hook
+ * that resolves before `enter` settled, or to something else, is a
+ * fault. The result: `{ kind: 'entered', lease, result }` when `enter`
+ * ran and settled (its rejection, when it is not a RollbackCarrier of
+ * ours, is a fault of the binding's continuation); `{ kind: 'failure' }`
+ * for a declared failure answered instead of entering; `{ kind:
+ * 'fault' }` for everything else — `enter` never called, called twice,
+ * a malformed lease, a throw.
+ * @param {Lifecycle} lifecycle
+ * @param {unknown} input
+ * @param {{ host: unknown }} identity
+ * @param {(lease: Lease) => unknown} enter
+ * @returns {Promise<{ kind: 'entered', lease: Lease, result: unknown, rolledBack: RollbackCarrier | null, afterFault?: unknown }
+ *   | { kind: 'failure', failure: import('./errors.js').ContractFailureValue }
+ *   | { kind: 'fault', cause: unknown }>}
+ */
+export declare function acquire(lifecycle: Lifecycle, input: unknown, identity: {
+    host: unknown;
+}, enter: (lease: Lease) => unknown): Promise<{
+    kind: 'entered';
+    lease: Lease;
+    result: unknown;
+    rolledBack: RollbackCarrier | null;
+    afterFault?: unknown;
+} | {
+    kind: 'failure';
+    failure: import('./errors.js').ContractFailureValue;
+} | {
+    kind: 'fault';
+    cause: unknown;
+}>;
+export { ContractFailure };

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

@@ -0,0 +1,147 @@
+/**
+ * @file Byte bodies of the HTTP binding, carrier-neutral: the one
+ * normalizer that turns whatever an adapter or a handler hands over (a
+ * string, bytes, an async iterable of chunks, a Web `ReadableStream`)
+ * into the shape the pipeline reads; the bounded collector a JSON
+ * operation drains its source through (a JSON body must be parsed and
+ * validated whole, so it materializes — under the operation's limit
+ * and never past it); and the counting source an opaque handler
+ * receives, which never yields a byte past the limit and cancels its
+ * upstream exactly once. Nothing here keeps a chunk it has handed on:
+ * the opaque path holds one chunk at a time, and the JSON path holds
+ * at most `maxBodyBytes`.
+ */
+export type Body = string | Uint8Array | AsyncIterable<Uint8Array> | null;
+/**
+ * A body as the pipeline reads it: text, bytes, a pull source of byte
+ * chunks, or none.
+ * @typedef {string | Uint8Array | AsyncIterable<Uint8Array> | null} Body
+ */
+/**
+ * The limit crossing a counting source raises to whoever is pulling
+ * it: recognized by class, so a handler that lets it propagate answers
+ * `JC2003` rather than a host fault, and a handler that catches it
+ * decides for itself.
+ */
+export declare class BodyLimitError extends Error {
+    /** @type {number} */
+    limit: number;
+    /** @param {number} limit */
+    constructor(limit: number);
+}
+/**
+ * Whether a value is an async iterable — the pull shape of a byte source.
+ * @param {unknown} value
+ * @returns {value is AsyncIterable<Uint8Array>}
+ */
+export declare function isAsyncByteSource(value: unknown): value is AsyncIterable<Uint8Array>;
+/**
+ * Whether a value is a Web `ReadableStream` (by its reader, the one
+ * member every platform's stream has).
+ * @param {unknown} value
+ * @returns {value is ReadableStream<Uint8Array>}
+ */
+export declare function isReadableStream(value: unknown): value is ReadableStream<Uint8Array>;
+/**
+ * Normalize a body: `undefined`/`null` → `null`; a string or bytes
+ * pass; a Web stream becomes an async iterable over its reader; an
+ * async iterable passes. Anything else answers `undefined` — not a
+ * body, for the caller to refuse.
+ * @param {unknown} body
+ * @returns {Body | undefined}
+ */
+export declare function normalizeBody(body: unknown): Body | undefined;
+export type Collected = {
+    ok: true;
+    bytes: Uint8Array;
+} | {
+    ok: false;
+    kind: 'limit' | 'aborted';
+} | {
+    ok: false;
+    kind: 'error';
+    cause: unknown;
+};
+/**
+ * What the collector answers: the whole body, or why it stopped —
+ * `limit` (the read crossed `limit`; the crossing chunk was never
+ * retained), `aborted` (the signal fired between pulls), `error` (the
+ * source threw, or yielded a non-byte chunk). In every failed case the
+ * upstream iterator's `return()` ran exactly once.
+ * @typedef {{ ok: true, bytes: Uint8Array }
+ *   | { ok: false, kind: 'limit' | 'aborted' }
+ *   | { ok: false, kind: 'error', cause: unknown }} Collected
+ */
+/**
+ * Drain a byte source into one `Uint8Array` under a limit: at most
+ * `limit` bytes are ever held; the chunk that would cross it is not
+ * retained, the upstream is cancelled once, and the crossing is
+ * reported.
+ * @param {AsyncIterable<Uint8Array>} source
+ * @param {number} limit - inclusive
+ * @param {AbortSignal | null} signal - checked between pulls
+ * @returns {Promise<Collected>}
+ */
+export declare function collectBytes(source: AsyncIterable<Uint8Array>, limit: number, signal: AbortSignal | null): Promise<Collected>;
+export type SourceState = {
+    /**
+     * - a chunk was pulled
+     */
+    started: boolean;
+    /**
+     * - EOF was reached, or the source was cancelled
+     */
+    finished: boolean;
+    /**
+     * - `return()` ran (a crossing, a consumer's return, the binding's cancel)
+     */
+    cancelled: boolean;
+    /**
+     * - the limit was crossed
+     */
+    crossed: boolean;
+    /**
+     * - the bytes yielded so far
+     */
+    bytes: number;
+};
+export type CountingSource = AsyncIterable<Uint8Array> & {
+    cancel: () => Promise<void>;
+    state: SourceState;
+};
+/**
+ * The state of a counting source, readable by the binding that made it.
+ * @typedef {Object} SourceState
+ * @property {boolean} started - a chunk was pulled
+ * @property {boolean} finished - EOF was reached, or the source was cancelled
+ * @property {boolean} cancelled - `return()` ran (a crossing, a consumer's return, the binding's cancel)
+ * @property {boolean} crossed - the limit was crossed
+ * @property {number} bytes - the bytes yielded so far
+ */
+/**
+ * A counting source over an upstream: what an opaque handler receives.
+ * @typedef {AsyncIterable<Uint8Array> & { cancel: () => Promise<void>, state: SourceState }} CountingSource
+ */
+/**
+ * Wrap an upstream source so it never yields a byte past `limit`: the
+ * chunk that would cross it is not yielded — the upstream is cancelled
+ * once and a `BodyLimitError` is thrown to the puller. `return()` (a
+ * consumer that stops early) and `cancel()` (the binding, when a
+ * response goes out with the request unread) both cancel the upstream
+ * exactly once; `state` says what happened.
+ * @param {AsyncIterable<Uint8Array>} upstream
+ * @param {number} limit
+ * @returns {CountingSource}
+ */
+export declare function countingSource(upstream: AsyncIterable<Uint8Array>, limit: number): CountingSource;
+/**
+ * Run `after` once when a response source completes, throws or is
+ * cancelled by its consumer — the hook a binding uses to release what
+ * the response held (an unread request source). A throw from the
+ * source reaches the consumer after the hook; the hook's own answer
+ * is awaited but never replaces the source's outcome.
+ * @param {AsyncIterable<Uint8Array>} source
+ * @param {(cause: unknown) => unknown} after - `cause` is the throw, or `undefined` on EOF/return
+ * @returns {AsyncIterable<Uint8Array>}
+ */
+export declare function onSettled(source: AsyncIterable<Uint8Array>, after: (cause: unknown) => unknown): AsyncIterable<Uint8Array>;

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

@@ -30,11 +30,19 @@ export type Ledger = import('../ledger.js').Ledger;
 export type RequestContext = {
     op: CompiledOperation;
     trace: string;
+    /**
+     * - the binding this context comes from
+     */
+    carrier: 'http';
+    /**
+     * - the identity's host until `acquire` entered; the acquired host in the handler's context (§7.7) — `any`, so a table typed by the projection's `HandlerContext<Host>` is a `Handler`
+     */
+    host: any;
     method: string;
     path: string;
     params: Readonly<Record<string, string>>;
     headers: Readonly<Record<string, string>>;
-    body: string | Uint8Array | null;
+    body: string | Uint8Array | AsyncIterable<Uint8Array> | null;
     signal: AbortSignal | null;
     idempotency: Readonly<{
         key: string;
@@ -52,7 +60,7 @@ export type Handler = (input: any, ctx: RequestContext) => unknown;
 export type RawResponse = {
     status: number;
     headers?: Record<string, string>;
-    body?: string | Uint8Array | null;
+    body?: string | Uint8Array | AsyncIterable<Uint8Array> | ReadableStream<Uint8Array> | null;
 };
 export type TagResolver = (input: any, ctx: RequestContext) => string | {
     tag: string;
@@ -142,6 +150,21 @@ export type Server = {
      * streams' stoppers; the dispatcher's `close()` ends them all
      */
     streams: Set<(reason: string | null) => void>;
+    /**
+     * - the bounds of every SSE stream
+     */
+    streamLimits: import('../stream/server.js').StreamLimits;
+    /**
+     * - the host lifecycle hooks (§7.7)
+     */
+    lifecycle: import('../host.js').Lifecycle;
+};
+export type Life = {
+    op: string;
+    trace: string;
+    identity: () => Promise<boolean>;
+    acquired: (() => Promise<boolean>) | null;
+    deferred: boolean;
 };
 /**
  * The one entry point. Validates the request object (a malformed one is
@@ -160,4 +183,5 @@ export type Armed = {
     outcome: number;
     retryable: boolean;
     decided: boolean;
+    settled: boolean;
 };

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

@@ -15,7 +15,8 @@
  * decided here, once, into a `Route` per operation.
  */
 import { HTTP_ERRORS, WELL_KNOWN_PATH } from './wire.js';
-export { HTTP_ERRORS, WELL_KNOWN_PATH };
+import { BodyLimitError } from './body.js';
+export { HTTP_ERRORS, WELL_KNOWN_PATH, BodyLimitError };
 export type HttpRequest = import('./wire.js').HttpRequest;
 export type HttpResponse = import('./wire.js').HttpResponse;
 export type WireErrorBody = import('./wire.js').WireErrorBody;
@@ -29,7 +30,8 @@ export type Contract = import('../compile.js').Contract;
 export type CompiledOperation = import('../compile.js').CompiledOperation;
 export type ServeHttpOptions = {
     /**
-     * - the server trace generator; default `crypto.randomUUID`
+     * - the server trace generator; default
+     * the runtime record's `uuid`, itself `crypto.randomUUID` by default
      */
     trace?: () => string;
     /**
@@ -85,9 +87,50 @@ export type ServeHttpOptions = {
      */
     catalog?: Record<string, string | ((params: object) => string)>;
     /**
-     * - the clock stamped into ledger claims; default `Date.now`
+     * - the clock stamped into ledger claims;
+     * default the runtime record's `now`, itself `Date.now` by default
      */
     now?: () => number;
+    /**
+     * - the host's runtime record: its `uuid` generates the server trace
+     * and its `now` is the clock, each only where `trace` / `now` is absent
+     */
+    runtime?: Partial<import('@jarenjs/core/runtime').Runtime>;
+    /**
+     * - 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`
+     */
+    streamLimits?: {
+        replay?: {
+            limit?: number;
+            maxBytes?: number;
+        };
+        queue?: {
+            events?: number;
+            bytes?: number;
+        };
+    };
+    /**
+     * - 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 }`
+     */
+    identify?: (meta: import('../host.js').IdentifyMeta) => unknown;
+    /**
+     * - 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 })`
+     */
+    acquire?: (input: unknown, identity: RequestContext, enter: (lease: unknown) => Promise<unknown>) => unknown;
 };
 export type HttpCapabilities = {
     name: 'http';

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

@@ -17,17 +17,17 @@ export type HttpRequest = {
     method: string;
     url: string;
     headers: Readonly<Record<string, string | readonly string[]>>;
-    body: string | Uint8Array | null;
+    body: string | Uint8Array | AsyncIterable<Uint8Array> | ReadableStream<Uint8Array> | null;
     signal?: AbortSignal | null;
 };
 export type HttpResponse = {
     status: number;
     headers: Readonly<Record<string, string>>;
-    body: string | Uint8Array | null;
-    stream?: (sink: {
-        write: (chunk: string) => void;
-        end: () => void;
-    }) => (() => void);
+    body: string | Uint8Array | AsyncIterable<Uint8Array> | null;
+    stream?: (sink: import('@jarenjs/core/async').SinkLike<string>) => {
+        stop: () => void;
+        done: Promise<void>;
+    };
 };
 export type WireErrorBody = {
     /**
@@ -52,29 +52,43 @@ export type WireErrorRow = {
  * 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]
  */
 /**
  * The D7 error body of every non-2xx JSON response.
@@ -245,8 +259,8 @@ export declare function mediaMatches(contentType: string | undefined, media: str
  */
 export declare function exceedsBytes(body: string | Uint8Array, limit: number): boolean;
 /**
- * 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

package/dist/types/ledger.d.ts

@@ -16,9 +16,16 @@
  */
 export type LedgerRecord = {
     /**
-     * - `"<op>|<scope>|<key>"`
+     * - {@link ledgerId} of the tuple
      */
     id: string;
+    /**
+     * - 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`)
+     */
+    generation: string;
     op: string;
     scope: string;
     key: string;
@@ -48,9 +55,13 @@ export type LedgerRecord = {
      */
     expiresAt: number;
 };
+export type LedgerRef = {
+    readonly id: string;
+    readonly generation: string;
+};
 export type ClaimResult = {
     state: 'new';
-    ref: unknown;
+    ref: LedgerRef;
 } | {
     state: 'replay';
     response: any;
@@ -67,36 +78,66 @@ export type Ledger = {
         hash: string;
         now?: number;
     }) => ClaimResult | Promise<ClaimResult>;
-    commit: (ref: unknown, response: any) => void | Promise<void>;
-    fail: (ref: unknown, retryable: boolean, response?: any) => void | Promise<void>;
+    commit: (ref: unknown, response: any, now?: number) => void | Promise<void>;
+    fail: (ref: unknown, retryable: boolean, response?: any, now?: number) => void | Promise<void>;
     lookup: (key: {
         op: string;
         scope: string;
         key: string;
+        now?: number;
     }) => LedgerRecord | null | Promise<LedgerRecord | null>;
 };
+/**
+ * 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}
+ */
+export declare function ledgerId(op: string, scope: string, key: string): string;
 /**
  * The reference ledger over a `Map`: synchronous, single-process,
  * 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 declare function createMemoryLedger(options?: {
     ttlMs?: number;
     now?: () => number;
+    runtime?: Partial<import('@jarenjs/core/runtime').Runtime>;
 }): Ledger & {
-    sweep(): number;
+    sweep(now?: number): number;
     size: number;
 };
 /**
  * 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 declare const idempotencyLedgerModel: Readonly<{
     $model: "0.1";
@@ -110,6 +151,10 @@ export declare const idempotencyLedgerModel: Readonly<{
                         type: string;
                         minLength: number;
                     };
+                    generation: {
+                        type: string;
+                        minLength: number;
+                    };
                     op: {
                         type: string;
                         minLength: number;