@jarenjs/contract 0.43.1 → 0.43.3

package/README.md

@@ -154,9 +154,10 @@ 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,
 normalizes the transport strings, validates (400 with `details` by
-`policy.errors.details`), claims the idempotency key, calls the handler
-through one promise boundary, validates the output (500 — the server
-broke the contract), applies `If-Match`/`If-None-Match`, serializes.
+`policy.errors.details`), claims the idempotency key, decides a declared
+precondition, calls the handler through one promise boundary, validates
+the output (500 — the server broke the contract), applies
+`If-Match`/`If-None-Match`, serializes.
 Every non-2xx body is `{ code, message, requestId, details?, retryable }`
 with `x-jaren-trace` on the response; a handler's thrown error never
 reaches the wire (`onError` sees it). `server.capabilities` says what
@@ -166,23 +167,54 @@ 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).
 
+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:
+a per-operation resolver of the CURRENT entity tag, decided before the
+handler, so a stale `If-Match` refuses 412 with zero handler runs and a
+matching `If-None-Match` read answers 304 without computing the
+representation.
+
+```js
+const server = serveHttp(contract, handlers, {
+  ledger: createMemoryLedger(),
+  preconditions: {
+    'product.save': (input) => `r${revisionOf(input.id)}`,   // a bare string is a STRONG tag; null = no representation
+  },
+});
+```
+
 ### Recipes: Fastify, Hono, Express
 
 None of these is a dependency; each recipe is executed by a test that
 imports the framework from the benchmark workspace.
 
 ```js
-// Fastify — a catch-all route, the raw body handed to dispatch
+// Fastify — hijack before parsing; the node adapter carries body limits, SSE and abort
 const app = fastify();
-app.removeAllContentTypeParsers();
-app.addContentTypeParser('*', { parseAs: 'buffer' }, (req, body, done) => done(null, body));
-app.all('/*', async (req, reply) => {
-  const r = await server.dispatch({ method: req.method, url: req.url, headers: req.headers, body: req.body ?? null });
-  reply.code(r.status).headers(r.headers);
-  return r.body === null ? reply.send() : reply.send(r.body);
-});
+const handler = toNodeHandler(server);
+app.all('/*', {
+  onRequest: (req, reply, done) => { reply.hijack(); handler(req.raw, reply.raw); done(); },
+}, () => {});
 ```
 
+`reply.hijack()` hands the untouched socket to the node adapter before
+any parser runs, so the recipe coexists with an existing app: routes
+registered beside it keep their parsers and parsed bodies, static paths
+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
+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
+shutdown note: a hijacked request never completes in Fastify's own
+bookkeeping, so its keep-alive socket never counts as idle — close the
+dispatcher first, then `app.server.closeAllConnections()` before
+`app.close()`.
+
 ```js
 // Hono — the fetch handler is the whole app (Bun.serve, Deno, workers alike)
 const app = new Hono();
@@ -195,6 +227,39 @@ const app = express();
 app.use(toNodeHandler(server));
 ```
 
+### Recipe: large outputs — validate on rebuild, serve by revision
+
+`validateOutput: "always"` proves every response against the contract
+and is the right default; on a multi-megabyte cached representation it
+is also the measured heavy share of the hot row (the benchmark's fourth
+column keeps it visible — docs/ROADMAP.md). The honest downgrade is not
+"skip validation" but "validate once per REVISION instead of once per
+request": prove the snapshot when it is rebuilt, arm its revision as the
+tag, and let `preconditions` answer 304 before the handler even runs.
+
+```js
+const validateCatalog = contract.operations['catalog.load'].output.validate;
+const cache = { revision: 0, value: null };
+function rebuild(next) {                 // on every write to the source
+  const v = validateCatalog(next);       // the JC2010 caught at build time, once
+  if (!(v === true || v?.valid === true)) throw new Error('the snapshot breaks the contract');
+  cache.revision += 1;
+  cache.value = next;
+}
+const server = serveHttp(contract, {
+  ...handlers,
+  'catalog.load': (input, ctx) => { ctx.etag(`r${cache.revision}`, { strong: true }); return cache.value; },
+}, {
+  validateOutput: 'never',               // declared: capabilities.validatedOutput === false
+  preconditions: { 'catalog.load': () => `r${cache.revision}` },   // 304 BEFORE the handler
+});
+```
+
+The tradeoff is declared, never silent: `validateOutput` is server-wide,
+so `capabilities.validatedOutput === false` tells every consumer the
+per-request guarantee moved to the rebuild path — keep that path the
+only writer of the cache, or the guarantee is gone.
+
 ## Call it from the other end
 
 ```js
@@ -478,7 +543,10 @@ deliberate decision, not a gap:
 - **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.
+  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)
+  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

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

@@ -1,9 +1,11 @@
 /**
  * @file The request pipeline of the HTTP server binding: one plain
  * request object in, one plain response object out — route, decode,
- * assemble, normalize, validate, claim idempotency, call the handler
- * through one uniform promise boundary, validate the output, apply the
- * entity-tag conditionals, serialize, commit. Every failure a request
+ * assemble, normalize, validate, claim idempotency, decide a declared
+ * precondition (the `preconditions` option: `If-Match`/`If-None-Match`
+ * against the resolver's CURRENT tag, before the handler), call the
+ * handler through one uniform promise boundary, validate the output,
+ * apply the post-handler entity-tag conditionals, serialize, commit. Every failure a request
  * can cause is a coded response (docs/CONTRACT-FORMAT.md §7); the
  * function rejects only for a malformed request OBJECT (`JC1004`, an
  * adapter author's mistake) — never for request content and never for
@@ -52,12 +54,24 @@ export type RawResponse = {
     headers?: Record<string, string>;
     body?: string | Uint8Array | null;
 };
+export type TagResolver = (input: any, ctx: RequestContext) => string | {
+    tag: string;
+    strong?: boolean;
+} | null | Promise<string | {
+    tag: string;
+    strong?: boolean;
+} | null>;
 export type Route = {
     op: CompiledOperation;
     /**
      * - `null` on a partial server
      */
     handler: Handler | null;
+    /**
+     * - the pre-handler resolver of the
+     * `preconditions` option; `null` = conditionals stay post-handler
+     */
+    tag: TagResolver | null;
     /**
      * - opaque: the handler is raw
      */
@@ -145,4 +159,5 @@ export type Armed = {
     status: number;
     outcome: number;
     retryable: boolean;
+    decided: boolean;
 };

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

@@ -55,6 +55,15 @@ export type ServeHttpOptions = {
      * - `'never'` is a declared downgrade, reported in `capabilities.validatedOutput`
      */
     validateOutput?: 'always' | 'never';
+    /**
+     * - operation id → the CURRENT entity-tag resolver, making `If-Match`/
+     * `If-None-Match` a PRE-handler decision for that operation: a stale
+     * precondition refuses `JC2014` with zero handler invocations, a
+     * matching `If-None-Match` read answers 304 without computing the
+     * representation (docs/CONTRACT-FORMAT.md §7.5); refused on a
+     * `subscribe` or opaque operation
+     */
+    preconditions?: Record<string, import('./dispatch.js').TagResolver>;
     /**
      * - the path answering `describe()`; default `/.well-known/jaren-contract`; `false` disables
      */

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

@@ -5,8 +5,9 @@
  * through a JSLT stylesheet), `toTypeScript` and `toMarkdown` (on
  * `@jarenjs/emit`'s type model), `contractTools` (`@jarenjs/ai` tool
  * definitions, no import edge) and the same-document bundler they share.
- * This is the one subpath that imports `@jarenjs/emit`; a consumer that
- * never imports it never loads it.
+ * This is the one subpath that imports `@jarenjs/emit` — the CLI loads
+ * it lazily, only for `types` and `docs`; a consumer that never imports
+ * either never loads it.
  */
 export { publicProjection } from '../public.js';
 export { toOpenApi } from './openapi.js';

package/docs/CONTRACT-FORMAT.md

@@ -184,7 +184,7 @@ the resolved value and marks it inferred.
 |---|---|---|---|
 | `task` | `switch` \| `exhaust` \| `concat` \| `parallel` | `switch` for a read or a subscribe, `exhaust` for a command | Which task mode a host effect runs the operation in: replace an in-flight attempt, let the first one finish, queue, or run concurrently. A **subscribe MUST be `switch`** (`JC0018`) — a subscription slot is replaced, never queued. |
 | `idempotency` | `none` \| `optional` \| `required` | `none` | Whether a command carries an idempotency key. A **read MUST be `none`** (`JC0014`); a **subscribe MUST be `none`** (`JC0020`). |
-| `revision` | `"input:<json-pointer>"` | absent (`null`) | Where in the input the revision a command asserts lives, as an RFC 6901 pointer after `input:` (`JC0014` on malformed). The operation MUST declare `input`, and the pointer's **first reference token** MUST name a member of `input.properties` (`JC0014` otherwise — "revision points at '/x' but input declares no member 'x'"); deeper tokens are not checked (a member's schema may be a `$ref` or open), and the empty pointer (`"input:"`) addresses the whole input. |
+| `revision` | `"input:<json-pointer>"` | absent (`null`) | Where in the input the revision a command asserts lives, as an RFC 6901 pointer after `input:` (`JC0014` on malformed). The operation MUST declare `input`, and the pointer's **first reference token** MUST name a member of `input.properties` (`JC0014` otherwise — "revision points at '/x' but input declares no member 'x'"); deeper tokens are not checked (a member's schema may be a `$ref` or open), and the empty pointer (`"input:"`) addresses the whole input. Distinct from the **contract revision** (`contract.revision()`, `describe().revision`, the client's `meta.revision` — the hash of the public projection, §14): `policy.revision` names the *resource* revision a command asserts, and no binding reads it at runtime — a `preconditions` resolver (§7.5) or the handler's own domain comparison is how a server enforces it. |
 | `cache` | `none` \| `revision` | `none` | Whether a read's result may be cached by revision. |
 | `limits.maxBodyBytes` | positive integer | `1048576` | The request-body ceiling a server binding enforces. |
 | `errors.details` | `none` \| `paths` \| `full` | `paths` | How much of a validation failure crosses the wire: nothing, instance path + keyword, or the raw validator errors. |
@@ -535,7 +535,7 @@ is `JC2008`.
    every matched operation, opaque and body-less included.
 4. **Opaque** → the transport input validated as in step 8 when no
    member is body-located (`JC2006`), then the raw handler through the
-   same boundary as step 10; done.
+   same boundary as step 11; done.
 5. **Media.** A body-carrying operation (a body-located member or a
    whole-body member) with a non-empty body requires a `content-type`
    whose `type/subtype` is the operation's `http.media` (parameters
@@ -571,26 +571,42 @@ is `JC2008`.
 9. **Idempotency** when `policy.idempotency !== "none"` (§8): a missing
    `Idempotency-Key` is `JC2007` under `required` and runs plainly under
    `optional`; otherwise the input is hashed and the ledger claimed.
-10. **The handler**, through **one uniform promise boundary** — a
+10. **Preconditions, opt-in** (§7.5): when the operation has a
+    `preconditions` resolver, the CURRENT tag is resolved BEFORE the
+    handler — a command consults it only under a conditional header, a
+    safe method always. `If-Match` first (strong comparison): a
+    mismatch, or a `null` resolution (`*` included), is `JC2014` with
+    **zero handler invocations** — on a claimed command the key is
+    released retryable, nothing ran; then `If-None-Match` (weak): a
+    match answers `304` before the handler on GET/HEAD and `JC2014` on
+    other methods, while a `null` resolution passes it — the
+    create-guard. On a pass a safe method arms the resolved tag (the
+    handler may re-arm), a command arms nothing, and step 13's
+    comparisons stand down. The claim (step 9) comes FIRST: a committed
+    key replays before the resolver runs.
+11. **The handler**, through **one uniform promise boundary** — a
     synchronous throw, a non-promise return and a rejection settle
     alike. A `ContractFailure` (from `ctx.fail`) or a thrown
     `ContractRuntimeError` with a declared code → the declared error
     response; anything else → `JC2008`, its cause handed to `onError`.
     A value whose `then` accessor throws is a rejection here — the
     hostile-value case of `JC2008`.
-11. **Output validation** (`validateOutput: "always"`, the default): the
+12. **Output validation** (`validateOutput: "always"`, the default): the
     value against the operation's output validator → `JC2010` on failure
     or on a throwing accessor; the validator's errors reach `onError`,
     never the wire. `"never"` is a declared downgrade
     (`capabilities.validatedOutput: false`).
-12. **Entity tags** when the handler armed one (§7.5): `If-Match` first
-    (strong comparison; mismatch → `JC2014`), then `If-None-Match` (weak
-    comparison; match → `304` on GET/HEAD, `JC2014` on other methods).
-    Because the tag is known only after the handler runs, both are
-    evaluated **after** step 10 and only when a tag was armed — a
-    handler that wants a pre-execution precondition compares
-    `ctx.headers["if-match"]` itself.
-13. **Serialize.** `JSON.stringify(value)`; a value JSON cannot carry
+13. **Entity tags** when the handler armed one and step 10 did not
+    already decide (§7.5): `If-Match` first (strong comparison; mismatch
+    → `JC2014`), then `If-None-Match` (weak comparison; match → `304` on
+    GET/HEAD, `JC2014` on other methods). Because the tag is known only
+    after the handler runs, both are evaluated **after** step 11 and
+    only when a tag was armed — **a cache device, never a write guard**:
+    a stale `If-Match` here means the handler already ran, and on a
+    claimed command the 412 is recorded non-retryable (§8). The
+    pre-handler guard is the `preconditions` option (step 10), or the
+    handler's own comparison of `ctx.headers["if-match"]`.
+14. **Serialize.** `JSON.stringify(value)`; a value JSON cannot carry
     (a cycle, a BigInt) is `JC2010`; `undefined` answers no body. Status
     is `ctx.status()` or `http.status`; headers `content-type: <media>;
     charset=utf-8` (when a body), `x-jaren-trace`, `etag` when armed;
@@ -702,13 +718,48 @@ the server's; `x-attempt` or any client attempt id is never read either.
 
 ### §7.5 Entity tags and conditionals
 
-`ctx.etag(tag)` arms a weak tag (`etag: W/"tag"`), `ctx.etag(tag, {
-strong: true })` a strong one (`etag: "tag"`). `If-None-Match` is
-compared weakly (`*` matches; `W/` indicators are ignored) → `304` with
-the `etag` header and no body on GET/HEAD, `412` (`JC2014`) on other
-methods; `If-Match` is compared strongly (`*` matches; a weak candidate
-or a weak armed tag never matches) → `412` on a mismatch. Both are
-evaluated after the handler ran, and only when it armed a tag.
+**Armed tags — post-handler, a cache device.** `ctx.etag(tag)` arms a
+weak tag (`etag: W/"tag"`), `ctx.etag(tag, { strong: true })` a strong
+one (`etag: "tag"`). `If-None-Match` is compared weakly (`*` matches;
+`W/` indicators are ignored) → `304` with the `etag` header and no body
+on GET/HEAD, `412` (`JC2014`) on other methods; `If-Match` is compared
+strongly (`*` matches; a weak candidate or a weak armed tag never
+matches) → `412` on a mismatch. Both are evaluated after the handler
+ran, and only when it armed a tag — so **this path is never a write
+guard**: a command's handler has already run, and may already have
+mutated, when its stale `If-Match` answers 412, and a handler that arms
+no tag has its conditionals silently pass. On a claimed command such a
+post-handler 412 is recorded non-retryable with its response (§8), so a
+blind retry replays the 412 instead of mutating again.
+
+**The `preconditions` option — pre-handler, the write guard.**
+`serveHttp(contract, handlers, { preconditions: { '<op>': (input, ctx)
+=> … } })` declares the CURRENT entity-tag resolver of an operation
+(refused at construction, `JC1001`, on a subscribe or opaque
+operation). The resolver answers a plain string — a **strong** tag (the
+deliberate asymmetry with `ctx.etag`, whose bare form is weak:
+`If-Match` needs strong comparison to mean anything) — or `{ tag,
+strong }`, or `null` for "no current representation", or a promise of
+any of those; a throw, a rejection or another shape is the host's fault
+(`JC2008`, a claimed key released retryable). A command consults its
+resolver only under a conditional header; a safe method always
+resolves, so its response carries the tag. The decision runs BEFORE the
+handler: `If-Match` first (strong; RFC 9110 §13.2.2) — a mismatch or a
+`null` resolution (`*` included) refuses `JC2014` with **zero handler
+invocations**, the current tag riding the 412's `etag` header for
+recovery; then `If-None-Match` (weak) — a match answers `304` before
+the handler on GET/HEAD (the cached-read win: the representation is
+never computed) and `JC2014` on other methods, while a `null`
+resolution passes it (`If-None-Match: *` is the create-guard). On a
+pass, a safe method arms the resolved tag — the handler's own
+`ctx.etag` then re-arms the RESPONSE tag only — and a command arms
+nothing (a mutated representation must not echo its pre-state tag, RFC
+9110 §8.8.3). Idempotency composes claim-first (§8): a committed key
+replays before the resolver runs, and a pre-handler 412 releases the
+key retryable — nothing ran. This is how a `policy.revision` command
+becomes HTTP-enforceable (§3.1): resolve the resource's current
+revision into a tag, and the domain transaction stays the final
+authority.
 
 ### §7.6 HEAD, the well-known path, options
 
@@ -720,10 +771,12 @@ answers `describe()` — `revision: null` until the revision lands, `compat`
 present — for negotiation. `trace` (default `crypto.randomUUID`) generates
 the server trace; `scope(ctx)` derives the idempotency scope (§8);
 `partial` allows missing handlers; `validateOutput` is `"always" |
-"never"`; `errorBody(wire, ctx)` and `onError(err, ctx)` are the two host
-hooks (`ctx` is `null` before an operation is matched); `catalog` is a
-message catalog (templates or compiled renderers) consulted before the
-English one; `now` is the clock stamped into ledger claims.
+"never"`; `preconditions` maps operation ids to pre-handler tag
+resolvers (§7.5); `errorBody(wire, ctx)` and `onError(err, ctx)` are the
+two host hooks (`ctx` is `null` before an operation is matched);
+`catalog` is a message catalog (templates or compiled renderers)
+consulted before the English one; `now` is the clock stamped into ledger
+claims.
 
 ## §8 Idempotency and the ledger
 
@@ -757,8 +810,12 @@ retryable); `started` and not expired → `in-progress` (409, `retry-after:
 key may be retried); `failed` and not retryable → `replay` of the stored
 failure. After the handler: a success **commits** the response; a
 declared failure is recorded as **failed** with its response and its
-`retryable`; a server fault (`JC2008`, `JC2010`, `JC2014`) **releases**
-the key as retryable with no response. `now` on a claim is the binding's
+`retryable`; a server fault (`JC2008`, `JC2010`, and a PRE-handler
+`JC2014` from a `preconditions` resolver — nothing ran) **releases** the
+key as retryable with no response; a POST-handler `JC2014` (the handler
+already ran and may have mutated) is recorded as **failed**, not
+retryable, with its 412 — a blind retry under the same key replays the
+412 instead of running the handler again. `now` on a claim is the binding's
 clock (`options.now`), which a ledger may prefer to its own. Opaque
 operations bypass the ledger; reads never carry a key. A ledger that
 throws or rejects is reported to `onError` and the response still goes
@@ -790,6 +847,104 @@ committed` on `commit`, `started → failed` on `fail`, `failed → started`
 on `claim` guarded by `$.context.retryable` — which the memory ledger
 walks exactly.
 
+### §8.1 A durable ledger over `node:sqlite` — an example, not an export
+
+A host that retries commands needs a ledger that survives a restart, and
+it does NOT need `@jarenjs/db` for that: `node:sqlite` is built into
+Node ≥ 24 — the suite's floor — so the ~60 lines below are as
+dependency-free as the package. Two design points carry the semantics:
+`BEGIN IMMEDIATE` makes each `claim` one writer (two processes cannot
+both claim a key), and the ref is the `AUTOINCREMENT` sequence of one
+specific insert — never reused, where a bare SQLite rowid would be — so
+a stale ref can never settle over a record a later claim re-created
+(the memory ledger's object-identity guard, spelled in SQL). Everything
+else mirrors `createMemoryLedger` exactly: expiry on `claim` and
+`lookup`, `sweep()` for a host timer, mismatch before status, a
+retryable failure handing the key back, a non-retryable one replaying
+its stored response. Remember the boundary (§8): this ledger
+deduplicates DELIVERY — the domain's own durable records stay
+authoritative for business state.
+
+```js
+import { DatabaseSync } from 'node:sqlite';
+
+/** A durable Ledger over one SQLite file — a host's example, not an export. */
+export function createSqliteLedger(path, { ttlMs = 86_400_000, now: clock = Date.now } = {}) {
+  const db = new DatabaseSync(path);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS ledger (
+      seq INTEGER PRIMARY KEY AUTOINCREMENT,
+      id TEXT NOT NULL UNIQUE, op TEXT NOT NULL, scope TEXT NOT NULL, key TEXT NOT NULL,
+      hash TEXT NOT NULL, status TEXT NOT NULL CHECK (status IN ('started', 'committed', 'failed')),
+      response TEXT, retryable INTEGER,
+      createdAt INTEGER NOT NULL, updatedAt INTEGER NOT NULL, expiresAt INTEGER NOT NULL);
+    CREATE INDEX IF NOT EXISTS ledger_by_expires ON ledger (expiresAt);
+    CREATE INDEX IF NOT EXISTS ledger_by_status ON ledger (status);`);
+  const one = db.prepare('SELECT * FROM ledger WHERE id = ?');
+  const put = db.prepare("INSERT INTO ledger (id, op, scope, key, hash, status, createdAt, updatedAt, expiresAt) VALUES (?, ?, ?, ?, ?, 'started', ?, ?, ?)");
+  const drop = db.prepare('DELETE FROM ledger WHERE id = ?');
+  const settle = db.prepare("UPDATE ledger SET status = ?, response = ?, retryable = ?, updatedAt = ? WHERE seq = ? AND status = 'started'");
+  const reap = db.prepare('DELETE FROM ledger WHERE expiresAt <= ?');
+  const stored = (row) => (row.response === null ? null : JSON.parse(row.response));
+  return {
+    claim({ op, scope, key, hash, now }) {
+      const at = typeof now === 'number' ? now : clock();
+      const id = `${op}|${scope}|${key}`;
+      db.exec('BEGIN IMMEDIATE'); // one writer: two processes cannot both claim the key
+      try {
+        const row = one.get(id);
+        if (row !== undefined) {
+          if (row.expiresAt <= at) drop.run(id);
+          else if (row.hash !== hash) { db.exec('COMMIT'); return { state: 'mismatch' }; }
+          else if (row.status === 'started') { db.exec('COMMIT'); return { state: 'in-progress' }; }
+          else if (row.status === 'committed') { db.exec('COMMIT'); return { state: 'replay', response: stored(row) }; }
+          else if (row.retryable !== 1 && row.response !== null) { db.exec('COMMIT'); return { state: 'replay', response: stored(row) }; }
+          else drop.run(id); // a retryable failure: the key runs again
+        }
+        const ref = { seq: put.run(id, op, scope, key, hash, at, at, at + ttlMs).lastInsertRowid };
+        db.exec('COMMIT');
+        return { state: 'new', ref };
+      }
+      catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+      }
+    },
+    commit(ref, response) {
+      settle.run('committed', JSON.stringify(response), null, clock(), ref.seq);
+    },
+    fail(ref, retryable, response) {
+      settle.run('failed', response === undefined ? null : JSON.stringify(response), retryable === true ? 1 : 0, clock(), ref.seq);
+    },
+    lookup({ op, scope, key }) {
+      const row = one.get(`${op}|${scope}|${key}`);
+      if (row === undefined) return null;
+      if (row.expiresAt <= clock()) {
+        drop.run(row.id);
+        return null;
+      }
+      const record = { ...row, response: stored(row), retryable: row.retryable === null ? null : row.retryable === 1 };
+      delete record.seq; // the record shape is exactly LedgerRecord (§8)
+      return record;
+    },
+    sweep: () => Number(reap.run(clock()).changes),
+    close: () => db.close(),
+  };
+}
+```
+
+The executable copy — the same listing, plus the `@ts-check` casts a
+test file carries — lives in `test/contract/ledger-sqlite.test.js`,
+which proves the memory-ledger contract over it (claim/commit/replay,
+mismatch, in-progress, retryable re-run, non-retryable replay), expiry
+and `sweep`, the stale-ref identity, `serveHttp` idempotency
+end-to-end, and durability across a second open of the same file. It is
+deliberately NOT an export of this package: the `Ledger` interface is
+the product, and an exported implementation would make `node:sqlite`'s
+locking part of this package's API surface. Scope keys by installation
+or principal through `options.scope`, give expiry a real TTL, and put
+`sweep()` on a host timer.
+
 ## §9 Adapters
 
 Two dependency-free, structurally typed adapters put a dispatcher behind
@@ -817,7 +972,10 @@ the platform:
 
 Fastify, Hono and Express are recipes in the README, each ≤15 lines and
 executed by a test that imports the framework from the benchmark
-workspace only — no framework is a dependency of this package.
+workspace only — no framework is a dependency of this package. Each
+recipe rides one of the two adapters (Fastify hijacks the raw
+request/response pair before any parser runs), so body limits, SSE
+streaming and peer abort behave identically through all three.
 
 ## §10 The HTTP client binding
 
@@ -1275,8 +1433,9 @@ operation's input schema or `null`, `seq` to a non-negative integer).
 
 Everything a consumer wants **beside** the runtime is a projection of the
 same compiled contract (`@jarenjs/contract/project` — the one subpath of
-this package that imports `@jarenjs/emit`, so a bundle that never
-projects never carries it): the public projection every other artifact
+this package that imports `@jarenjs/emit`, and the CLI loads it lazily,
+only for `types` and `docs`, so a bundle that never projects never
+carries it): the public projection every other artifact
 is built on (§12.1), OpenAPI 3.1 (§12.2), TypeScript declarations
 (§12.3), Markdown reference documentation (§12.4) and AI tool
 definitions (§12.5), with the `jaren-contract` CLI (§12.6) writing and

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/contract",
   "private": false,
-  "version": "0.43.1",
+  "version": "0.43.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -102,9 +102,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.43.1",
-    "@jarenjs/json": "^0.43.1",
-    "@jarenjs/validate": "^0.43.1",
-    "@jarenjs/emit": "^0.43.1"
+    "@jarenjs/core": "^0.43.3",
+    "@jarenjs/json": "^0.43.3",
+    "@jarenjs/validate": "^0.43.3",
+    "@jarenjs/emit": "^0.43.3"
   }
 }

package/src/cli.js

@@ -22,8 +22,6 @@ import { ContractCompileError, ContractHostError } from './errors.js';
 import { diffContracts } from './diff.js';
 import { publicProjection } from './public.js';
 import { toOpenApi } from './project/openapi.js';
-import { toTypeScript } from './project/typescript.js';
-import { toMarkdown } from './project/markdown.js';
 
 const USAGE = `jaren-contract — projections of a jaren-contract document
 
@@ -196,7 +194,7 @@ function runDiff(options) {
   }
 }
 
-function main() {
+async function main() {
   let options;
   try {
     options = parseArgs(process.argv);
@@ -239,8 +237,9 @@ function main() {
         rendered = JSON.stringify(document, null, 2) + '\n';
         break;
       }
-      case 'types': rendered = toTypeScript(contract); break;
-      case 'docs': rendered = toMarkdown(contract); break;
+      // the two emit-edged projections load lazily: diff/describe/public/openapi never touch @jarenjs/emit
+      case 'types': rendered = (await import('./project/typescript.js')).toTypeScript(contract); break;
+      case 'docs': rendered = (await import('./project/markdown.js')).toMarkdown(contract); break;
     }
     if (options.out === null) {
       process.stdout.write(rendered);
@@ -261,4 +260,4 @@ function main() {
   }
 }
 
-main();
+await main();

package/src/http/dispatch.js

@@ -2,9 +2,11 @@
 /**
  * @file The request pipeline of the HTTP server binding: one plain
  * request object in, one plain response object out — route, decode,
- * assemble, normalize, validate, claim idempotency, call the handler
- * through one uniform promise boundary, validate the output, apply the
- * entity-tag conditionals, serialize, commit. Every failure a request
+ * assemble, normalize, validate, claim idempotency, decide a declared
+ * precondition (the `preconditions` option: `If-Match`/`If-None-Match`
+ * against the resolver's CURRENT tag, before the handler), call the
+ * handler through one uniform promise boundary, validate the output,
+ * apply the post-handler entity-tag conditionals, serialize, commit. Every failure a request
  * can cause is a coded response (docs/CONTRACT-FORMAT.md §7); the
  * function rejects only for a malformed request OBJECT (`JC1004`, an
  * adapter author's mistake) — never for request content and never for
@@ -86,12 +88,28 @@ import {
  * @typedef {{ status: number, headers?: Record<string, string>, body?: string | Uint8Array | null }} RawResponse
  */
 
+/**
+ * The CURRENT entity-tag resolver of the `preconditions` option
+ * (docs/CONTRACT-FORMAT.md §7.5): called with the operation's validated
+ * input and the frozen context BEFORE the handler, it answers the tag of
+ * the current representation — a plain string is a STRONG tag (the
+ * asymmetry with `ctx.etag`, whose bare form is weak, is deliberate:
+ * `If-Match` needs strong comparison to mean anything), `{ tag, strong }`
+ * spells it out, `null` means "no current representation" (`If-Match`,
+ * `*` included, fails on it; `If-None-Match`, `*` included, passes — the
+ * create-guard). A throw, a rejection or any other shape is the host's
+ * fault (`JC2008`).
+ * @typedef {(input: any, ctx: RequestContext) => string | { tag: string, strong?: boolean } | null | Promise<string | { tag: string, strong?: boolean } | null>} TagResolver
+ */
+
 /**
  * One operation as `serveHttp` prepared it: everything the pipeline
  * reads per request, decided once.
  * @typedef {Object} Route
  * @property {CompiledOperation} op
  * @property {Handler | null} handler - `null` on a partial server
+ * @property {TagResolver | null} tag - the pre-handler resolver of the
+ *   `preconditions` option; `null` = conditionals stay post-handler
  * @property {boolean} raw - opaque: the handler is raw
  * @property {boolean} stream - a subscribe operation: the handler answers a subscription
  * @property {number} maxBody
@@ -295,9 +313,15 @@ function signalOf(request) {
 /**
  * Per-request mutable state: what the context's `etag`/`status` armed,
  * and how the settlement classified — `outcome` 0 success, 1 declared
- * failure (with `retryable`), 2 server fault — which is what the ledger
- * needs to commit, record or release the claim.
- * @typedef {{ etag: string | null, strong: boolean, status: number, outcome: number, retryable: boolean }} Armed
+ * failure (with `retryable`), 2 server fault (a pre-handler `JC2014`
+ * among them: nothing ran, the claim is released retryable), 3 a
+ * POST-handler precondition failure (the handler already ran and may
+ * have mutated: the claim is recorded non-retryable with its 412) —
+ * which is what the ledger needs to commit, record or release the
+ * claim. `decided` is set by a `preconditions` resolver that already
+ * evaluated the conditionals; the post-handler comparison then stands
+ * down.
+ * @typedef {{ etag: string | null, strong: boolean, status: number, outcome: number, retryable: boolean, decided: boolean }} Armed
  */
 
 /**
@@ -411,7 +435,7 @@ function run(server, request) {
   const transported = route.normalize === null ? input : route.normalize(input);
 
   /** @type {Armed} */
-  const armed = { etag: null, strong: false, status: 0, outcome: 0, retryable: false };
+  const armed = { etag: null, strong: false, status: 0, outcome: 0, retryable: false, decided: false };
   /** @type {RequestContext} */
   const ctx = {
     op, trace, method, path, params, headers: ctxHeaders,
@@ -514,6 +538,7 @@ function run(server, request) {
   }
 
   Object.freeze(ctx);
+  if (route.tag !== null) return preconditionedBoundary(server, route, ctx, assembled, trace, armed, isHead, ifMatch, ifNoneMatch);
   return boundary(server, route, ctx, assembled, trace, armed, isHead, ifMatch, ifNoneMatch, false);
 }
 
@@ -733,6 +758,83 @@ function sseResponse(server, route, ctx, sub, trace, headers) {
 
 //#region the handler boundary
 
+/**
+ * The pre-handler conditionals of a declared tag resolver
+ * (docs/CONTRACT-FORMAT.md §7.5): resolve the CURRENT entity tag, decide
+ * `If-Match` (strong comparison, first — RFC 9110 §13.2.2) and
+ * `If-None-Match` (weak) BEFORE the handler, and only then run it. A
+ * stale precondition refuses `JC2014` with ZERO handler invocations —
+ * the write guard the post-handler comparison cannot be; a matching
+ * `If-None-Match` on a safe method answers 304 without computing the
+ * representation. A command consults its resolver only under a
+ * conditional header; a safe method always resolves, so its response
+ * carries the tag (the handler's own `ctx.etag` re-arms the RESPONSE
+ * tag only — the conditionals are already decided). On pass, an unsafe
+ * method arms nothing: a mutated representation must not echo its
+ * pre-state tag (RFC 9110 §8.8.3).
+ * @param {Server} server
+ * @param {Route} route
+ * @param {RequestContext} ctx - frozen
+ * @param {any} input
+ * @param {string} trace
+ * @param {Armed} armed
+ * @param {boolean} isHead
+ * @param {string | undefined} ifMatch
+ * @param {string | undefined} ifNoneMatch
+ * @returns {HttpResponse | Promise<HttpResponse>}
+ */
+function preconditionedBoundary(server, route, ctx, input, trace, armed, isHead, ifMatch, ifNoneMatch) {
+  const safe = ctx.method === 'GET' || ctx.method === 'HEAD';
+  if (!safe && ifMatch === undefined && ifNoneMatch === undefined) {
+    return boundary(server, route, ctx, input, trace, armed, isHead, ifMatch, ifNoneMatch, false);
+  }
+  /** @param {unknown} err @returns {HttpResponse} */
+  const fault = (err) => {
+    observe(server, err === undefined ? new TypeError(`the tag resolver of '${route.op.id}' rejected with undefined`) : err, ctx);
+    armed.outcome = 2;
+    return refuse(server, 'JC2008', trace, { op: route.op.id }, undefined, null, ctx);
+  };
+  /** @param {unknown} resolution @returns {HttpResponse | Promise<HttpResponse>} */
+  const decide = (resolution) => {
+    /** @type {{ tag: string, strong: boolean } | null} */
+    let resolved;
+    if (resolution === null) resolved = null;
+    else if (typeof resolution === 'string') resolved = { tag: resolution, strong: true };
+    else if (typeof resolution === 'object' && typeof (/** @type {any} */ (resolution).tag) === 'string') {
+      resolved = { tag: /** @type {any} */ (resolution).tag, strong: /** @type {any} */ (resolution).strong !== false };
+    }
+    else return fault(new TypeError(`the tag resolver of '${route.op.id}' must answer a string, { tag, strong? } or null`));
+    if (resolved !== null && (resolved.tag.length === 0 || resolved.tag.indexOf('"') !== -1)) {
+      return fault(new TypeError(`the tag resolver of '${route.op.id}' answered a tag that is empty or carries a double quote`));
+    }
+    if (ifMatch !== undefined && (resolved === null || !entityTagMatches(ifMatch, resolved.tag, resolved.strong, true))) {
+      armed.outcome = 2; // nothing ran: on a claimed command the key is released retryable
+      const extra = resolved === null ? null : { etag: formatEntityTag(resolved.tag, resolved.strong) };
+      return refuse(server, 'JC2014', trace, { op: route.op.id }, undefined, extra, ctx);
+    }
+    if (ifNoneMatch !== undefined && resolved !== null && entityTagMatches(ifNoneMatch, resolved.tag, resolved.strong, false)) {
+      const etag = formatEntityTag(resolved.tag, resolved.strong);
+      if (safe) return { status: 304, headers: { etag, 'x-jaren-trace': trace }, body: null };
+      armed.outcome = 2;
+      return refuse(server, 'JC2014', trace, { op: route.op.id }, undefined, { etag }, ctx);
+    }
+    armed.decided = true;
+    if (safe && resolved !== null) {
+      armed.etag = resolved.tag;
+      armed.strong = resolved.strong;
+    }
+    return boundary(server, route, ctx, input, trace, armed, isHead, ifMatch, ifNoneMatch, false);
+  };
+  let resolution;
+  try {
+    resolution = /** @type {NonNullable<Route['tag']>} */ (route.tag)(input, ctx);
+  }
+  catch (err) {
+    return fault(err);
+  }
+  return isThenable(resolution) ? toPromise(resolution).then(decide, fault) : decide(resolution);
+}
+
 /**
  * Call the handler through the pipeline's uniform promise boundary and
  * project the classified result onto the HTTP wire.
@@ -812,20 +914,28 @@ function finishValue(server, route, ctx, value, trace, armed, isHead, ifMatch, i
   /** @type {Record<string, string>} */
   const headers = { 'x-jaren-trace': trace };
   if (armed.etag !== null) {
-    // If-Match first (RFC 9110 §13.2.2), strong comparison; then
-    // If-None-Match, weak comparison: 304 for GET/HEAD, 412 otherwise
-    if (ifMatch !== undefined && !entityTagMatches(ifMatch, armed.etag, armed.strong, true)) {
-      armed.outcome = 2;
-      return refuse(server, 'JC2014', trace, { op: route.op.id }, undefined, null, ctx);
-    }
     const etag = formatEntityTag(armed.etag, armed.strong);
-    if (ifNoneMatch !== undefined && entityTagMatches(ifNoneMatch, armed.etag, armed.strong, false)) {
-      if (ctx.method === 'GET' || ctx.method === 'HEAD') {
-        headers.etag = etag;
-        return { status: 304, headers, body: null };
+    if (!armed.decided) {
+      // the POST-handler conditionals — a cache device, never a write
+      // guard: the handler has already run when they are compared, so a
+      // 412 here does not mean the work did not happen. Outcome 3
+      // records that on a claimed command (non-retryable, the 412
+      // replays). If-Match first (RFC 9110 §13.2.2), strong comparison;
+      // then If-None-Match, weak: 304 for GET/HEAD, 412 otherwise. A
+      // `preconditions` resolver (§7.5) decides these BEFORE the
+      // handler instead and stands this block down (`armed.decided`).
+      if (ifMatch !== undefined && !entityTagMatches(ifMatch, armed.etag, armed.strong, true)) {
+        armed.outcome = 3;
+        return refuse(server, 'JC2014', trace, { op: route.op.id }, undefined, null, ctx);
+      }
+      if (ifNoneMatch !== undefined && entityTagMatches(ifNoneMatch, armed.etag, armed.strong, false)) {
+        if (ctx.method === 'GET' || ctx.method === 'HEAD') {
+          headers.etag = etag;
+          return { status: 304, headers, body: null };
+        }
+        armed.outcome = 3;
+        return refuse(server, 'JC2014', trace, { op: route.op.id }, undefined, { etag }, ctx);
       }
-      armed.outcome = 2;
-      return refuse(server, 'JC2014', trace, { op: route.op.id }, undefined, { etag }, ctx);
     }
     headers.etag = etag;
   }
@@ -956,8 +1066,13 @@ function idempotent(server, route, ctx, input, trace, armed, isHead, ifMatch, if
       return fault(err);
     }
     if (state === 'new') {
-      return boundary(server, route, ctx, input, trace, armed, isHead, ifMatch, ifNoneMatch, false)
-        .then((response) => settleClaim(server, ledger, ref, response, ctx, armed));
+      // claim first, precondition second: a committed key replays its
+      // stored response before the resolver runs (a retried command
+      // that already succeeded must not answer 412)
+      const ran = route.tag !== null
+        ? preconditionedBoundary(server, route, ctx, input, trace, armed, isHead, ifMatch, ifNoneMatch)
+        : boundary(server, route, ctx, input, trace, armed, isHead, ifMatch, ifNoneMatch, false);
+      return toPromise(ran).then((response) => settleClaim(server, ledger, ref, response, ctx, armed));
     }
     if (state === 'replay') return replay(server, route, stored, trace, ctx);
     if (state === 'in-progress') {
@@ -992,9 +1107,12 @@ function idempotent(server, route, ctx, input, trace, armed, isHead, ifMatch, if
  * Settle a `new` claim with the response the handler produced: a
  * success commits (replayed verbatim later); a declared failure is
  * recorded as failed with its response and retryability; a server fault
- * (`JC2008`/`JC2010`/`JC2014`) releases the key as retryable. TOTAL: a
- * ledger that throws or rejects is reported, and the response still
- * goes out.
+ * (`JC2008`/`JC2010`, and a PRE-handler `JC2014` — nothing ran)
+ * releases the key as retryable; a POST-handler `JC2014` (outcome 3) is
+ * recorded NON-retryable with its 412 — the handler already ran and may
+ * have mutated, so a blind retry with the same key replays the 412
+ * instead of running it again. TOTAL: a ledger that throws or rejects
+ * is reported, and the response still goes out.
  * @param {Server} server
  * @param {Ledger} ledger
  * @param {unknown} ref
@@ -1008,6 +1126,7 @@ function settleClaim(server, ledger, ref, response, ctx, armed) {
   try {
     if (armed.outcome === 0) settlement = ledger.commit(ref, response);
     else if (armed.outcome === 1) settlement = ledger.fail(ref, armed.retryable, response);
+    else if (armed.outcome === 3) settlement = ledger.fail(ref, false, response);
     else settlement = ledger.fail(ref, true, undefined);
   }
   catch (err) {

package/src/http/serve.js

@@ -50,6 +50,13 @@ export { HTTP_ERRORS, WELL_KNOWN_PATH };
  * @property {boolean} [partial] - allow missing handlers; a missing one answers 501 `JC2013`
  * @property {boolean} [head] - answer HEAD for GET operations by running the handler and dropping the body; default true
  * @property {'always' | 'never'} [validateOutput] - `'never'` is a declared downgrade, reported in `capabilities.validatedOutput`
+ * @property {Record<string, import('./dispatch.js').TagResolver>} [preconditions]
+ *   - operation id → the CURRENT entity-tag resolver, making `If-Match`/
+ *   `If-None-Match` a PRE-handler decision for that operation: a stale
+ *   precondition refuses `JC2014` with zero handler invocations, a
+ *   matching `If-None-Match` read answers 304 without computing the
+ *   representation (docs/CONTRACT-FORMAT.md §7.5); refused on a
+ *   `subscribe` or opaque operation
  * @property {string | false} [wellKnown] - the path answering `describe()`; default `/.well-known/jaren-contract`; `false` disables
  * @property {(wire: WireErrorBody & { status: number }, ctx: RequestContext | null) => unknown} [errorBody]
  *   - projects the wire error record into the response body (a legacy
@@ -111,9 +118,10 @@ function headerNameOf(member) {
  * Prepare one operation for the pipeline.
  * @param {CompiledOperation} op
  * @param {Handler | null} handler
+ * @param {import('./dispatch.js').TagResolver | null} tag
  * @returns {Route}
  */
-function prepare(op, handler) {
+function prepare(op, handler, tag) {
   const http = op.http;
   const input = op.input;
   const transport = input === null ? null : input.transport;
@@ -156,6 +164,7 @@ function prepare(op, handler) {
   return Object.freeze({
     op,
     handler,
+    tag,
     raw: http.opaque,
     stream: op.kind === 'subscribe',
     maxBody: op.policy.limits.maxBodyBytes,
@@ -224,6 +233,29 @@ export function serveHttp(contract, handlers, options = {}) {
       throw host('JC1001', `the handler of '${id}' must be a function, got ${typeof handlers[id]}`);
     }
   }
+  const preconditions = options.preconditions === undefined ? null : options.preconditions;
+  if (preconditions !== null && (typeof preconditions !== 'object' || Array.isArray(preconditions))) {
+    throw host('JC1001', 'options.preconditions must be an object of operation id → tag resolver');
+  }
+  if (preconditions !== null) {
+    const ids = Object.keys(preconditions);
+    for (let i = 0; i < ids.length; i++) {
+      const id = ids[i];
+      if (!Object.hasOwn(contract.operations, id)) {
+        throw host('JC1001', `preconditions names '${id}', which is not an operation of the contract`);
+      }
+      if (typeof preconditions[id] !== 'function') {
+        throw host('JC1001', `the tag resolver of '${id}' must be a function, got ${typeof preconditions[id]}`);
+      }
+      const op = contract.operations[id];
+      if (op.kind === 'subscribe') {
+        throw host('JC1001', `operation '${id}' is a subscribe — a stream has no single representation for a precondition to guard`);
+      }
+      if (op.http.opaque) {
+        throw host('JC1001', `operation '${id}' is opaque — its raw handler owns the bytes and the headers; preconditions cannot apply`);
+      }
+    }
+  }
   /** @type {Map<string, Route>} */
   const routes = new Map();
   for (let i = 0; i < contract.ids.length; i++) {
@@ -236,7 +268,7 @@ export function serveHttp(contract, handlers, options = {}) {
     if (op.policy.idempotency !== 'none' && ledger === null) {
       throw host('JC1003', `operation '${id}' declares policy.idempotency '${op.policy.idempotency}' and no ledger was given — this binding cannot carry idempotency without one`);
     }
-    routes.set(id, prepare(op, handler));
+    routes.set(id, prepare(op, handler, preconditions !== null && Object.hasOwn(preconditions, id) ? preconditions[id] : null));
   }
 
   const validateOutput = options.validateOutput === undefined ? 'always' : options.validateOutput;

package/src/project/index.js

@@ -6,8 +6,9 @@
  * through a JSLT stylesheet), `toTypeScript` and `toMarkdown` (on
  * `@jarenjs/emit`'s type model), `contractTools` (`@jarenjs/ai` tool
  * definitions, no import edge) and the same-document bundler they share.
- * This is the one subpath that imports `@jarenjs/emit`; a consumer that
- * never imports it never loads it.
+ * This is the one subpath that imports `@jarenjs/emit` — the CLI loads
+ * it lazily, only for `types` and `docs`; a consumer that never imports
+ * either never loads it.
  */
 
 export { publicProjection } from '../public.js';