@nifrajs/core 2.1.0 → 2.3.0

package/src/binary.ts

@@ -0,0 +1,128 @@
+/**
+ * `@nifrajs/core/binary` - a route that returns bytes, and says so in its type.
+ *
+ * A download route had no way to be part of the contract. Returning a raw `Response` is the only way
+ * to send bytes, and a raw `Response` is exactly what the typed client cannot describe - so the route
+ * needed a `// nifra-expect raw-response` pragma to quiet the advisory, and its caller got no type at
+ * all. One whole category of endpoint sat outside the thing the framework is otherwise strict about.
+ *
+ *     import { bytes } from "@nifrajs/core/binary"
+ *
+ *     app.get("/invoice.pdf", async (c) => bytes(await render(c.params.id), {
+ *       type: "application/pdf",
+ *       filename: "invoice.pdf",
+ *     }))
+ *
+ * The client types `data` as `Blob` for that route, and gets the bytes intact.
+ *
+ * The brand is a phantom: `bytes()` returns a real `Response` and nothing is added to it at runtime.
+ * It exists so the type carries a fact the value cannot - that these bytes are the payload rather than
+ * a serialization accident - which is what lets `Jsonify` answer `Blob` instead of trying to describe
+ * a `Response`'s properties.
+ */
+
+/**
+ * Marker on a binary response's TYPE. A unique symbol rather than a string key, so no ordinary object
+ * can satisfy it by accident, and declared required rather than optional - an optional brand is
+ * satisfied by every type that lacks it, which would make the check match `Response` itself.
+ */
+declare const NIFRA_BYTES: unique symbol
+
+/** Runtime marker paired with the type-only brand so clients do not have to guess from media type. */
+export const NIFRA_BINARY_HEADER = "x-nifra-binary"
+
+/** A `Response` a route declared as binary. `Jsonify` maps this to `Blob`. */
+export type BinaryResponse = Response & { readonly [NIFRA_BYTES]: true }
+
+/** What can be sent as bytes without being re-encoded on the way out. */
+export type BinaryBody = ArrayBuffer | ArrayBufferView | Blob | ReadableStream<Uint8Array>
+
+export interface BytesOptions {
+  /** Media type. Defaults to `application/octet-stream`, the honest answer for unlabelled bytes. */
+  readonly type?: string
+  /**
+   * Offer the body as a download under this name.
+   *
+   * A filename derived from user data is the ordinary case - an upload's original name, a document
+   * title - so this has to survive anything a person can type. Two things follow, and both are tested:
+   * a `"` or a newline cannot end the value and write further parameters, and a non-Latin-1 name is
+   * encoded rather than thrown on.
+   */
+  readonly filename?: string
+  readonly status?: number
+  readonly headers?: Readonly<Record<string, string>>
+}
+
+/**
+ * Everything a header value may not contain: quotes, backslashes, and the CR/LF that would split the
+ * header. Replaced rather than rejected - a filename is cosmetic, and failing a download because a
+ * document was titled `Q1 "final"` would be worse than sending it with the quotes dropped.
+ */
+const UNSAFE_FILENAME = /["\\\r\n]/g
+
+/**
+ * Printable ASCII only.
+ *
+ * A header value is nominally Latin-1, but runtimes do not agree: Bun rejects `é` in a header outright,
+ * so "Latin-1 is fine" would have been a portability bug dressed as a standards reading. Printable
+ * ASCII is what every runtime and client accepts, and `filename*` carries everything else.
+ */
+const NON_ASCII = /[^\x20-\x7e]/g
+
+/**
+ * `Content-Disposition` for a name that may be anything a user typed.
+ *
+ * Setting a header containing `报告.pdf` or an emoji THROWS - which on a download route is a 500 for
+ * the ordinary act of naming a file in a language ASCII does not cover, and the name usually came from
+ * the user in the first place. RFC 6266 exists for exactly this: an ASCII `filename` every client
+ * understands, plus `filename*` carrying the real name UTF-8 percent-encoded, which browsers prefer.
+ *
+ * The ASCII fallback keeps the characters it can rather than substituting a placeholder, so
+ * `report 报告.pdf` still arrives as `report .pdf` on a client that ignores `filename*`.
+ *
+ * `filename*` is built from the SANITIZED name, not the raw one. Percent-encoding would make a hostile
+ * name inert either way, but round-tripping `"; attachment; filename="evil.exe` into the header - even
+ * encoded - puts an attacker's string somewhere a future reader has to reason about, and the second
+ * parameter is only there to carry characters ASCII cannot.
+ */
+function contentDisposition(filename: string): string {
+  const safe = filename.toWellFormed().replace(UNSAFE_FILENAME, "")
+  const ascii = safe.replace(NON_ASCII, "")
+  const disposition = `attachment; filename="${ascii}"`
+  // Only when it adds something: a name ASCII already carries needs no second parameter.
+  if (ascii === safe) return disposition
+  // encodeURIComponent leaves `'()*` untouched, but RFC 5987's attr-char grammar does not.
+  const encoded = encodeURIComponent(safe).replace(
+    /['()*]/g,
+    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
+  )
+  return `${disposition}; filename*=UTF-8''${encoded}`
+}
+
+export function bytes(body: BinaryBody, options: BytesOptions = {}): BinaryResponse {
+  const headers = new Headers(options.headers as Record<string, string> | undefined)
+  headers.set("content-type", options.type ?? "application/octet-stream")
+  headers.set(NIFRA_BINARY_HEADER, "1")
+  // Response headers outside the CORS safelist are hidden from cross-origin clients unless exposed.
+  // Preserve an existing list and add the marker so the typed contract works cross-origin too.
+  const exposed = headers.get("access-control-expose-headers")
+  if (exposed !== "*") {
+    const names = exposed
+      ?.split(",")
+      .map((name) => name.trim())
+      .filter(Boolean)
+    if (!names?.some((name) => name.toLowerCase() === NIFRA_BINARY_HEADER)) {
+      headers.set(
+        "access-control-expose-headers",
+        [...(names ?? []), NIFRA_BINARY_HEADER].join(", "),
+      )
+    }
+  }
+  if (options.filename !== undefined) {
+    headers.set("content-disposition", contentDisposition(options.filename))
+  }
+  return new Response(body as ConstructorParameters<typeof Response>[0], {
+    status: options.status ?? 200,
+    headers,
+  }) as BinaryResponse
+}

package/src/budget.ts

@@ -154,7 +154,7 @@ class UnboundedRequestBudget implements RequestBudget {
 
 /**
  * Create a budget from an admitted absolute deadline. Wall time is sampled once; every subsequent
- * `remaining()` call is monotonic. This function does not arm a timer—the owner of `signal` does.
+ * `remaining()` call is monotonic. This function does not arm a timer-the owner of `signal` does.
  */
 export function createRequestBudget(options: CreateRequestBudgetOptions): RequestBudget {
   assertDeadline(options.deadline)

package/src/capabilities.ts

@@ -44,6 +44,36 @@ export type {
   EffectLifecycleObserver,
 }
 
+const EXECUTION_JOURNAL = Symbol("nifra.capability.journal")
+
+/**
+ * Framework wiring: put a journal on a request context so every `executeCapability` on that request is
+ * journaled without each call site threading it. Not for application code - install the
+ * `durableCommand()` adapter, which calls this and declares the assurance evidence that goes with it.
+ *
+ * Symbol-keyed, mirroring `attachEffectLedger`: it cannot collide with an application field and does
+ * not show up in a context spread or a log of it.
+ *
+ * Deliberately here rather than beside the journal TYPE in `internal/capability-runtime.ts`. That
+ * module is reachable from a bare server - it holds the route-capability guard - so a seam living
+ * there ships to every app, while here it arrives only with `executeCapability`, the one thing that
+ * reads it. Measured rather than assumed: in the internal module this cost every bundle row in the
+ * size matrix 10-18 bytes gzip, enough to put `nifra-mcp` over its ceiling.
+ */
+export function attachCapabilityJournal(
+  context: object,
+  journal: CapabilityExecutionJournal,
+): void {
+  ;(context as Record<PropertyKey, unknown>)[EXECUTION_JOURNAL as unknown as string] = journal
+}
+
+/** The journal installed for this request, if any. */
+export function capabilityJournalOf(context: object): CapabilityExecutionJournal | undefined {
+  return (context as { readonly [EXECUTION_JOURNAL]?: CapabilityExecutionJournal })[
+    EXECUTION_JOURNAL
+  ]
+}
+
 export type CapabilityZone = "domain" | "operational"
 export type CapabilityAccess = "read" | "write"
 export type CapabilityIdempotency = "none" | "request" | "durable"
@@ -121,9 +151,11 @@ export type CapabilityFindingCode =
   | "provenance-uncovered"
   | "undeclared-capability-evidence"
   | "safe-method-domain-write"
+  | "unconfined-write-reach"
   | "missing-request-idempotency"
   | "missing-durable-idempotency"
   | "forbidden-effect-import"
+  | "provenance-truncated"
 
 export interface CapabilityFinding {
   readonly code: CapabilityFindingCode
@@ -343,16 +375,38 @@ export function evaluateCapabilityAssurance(
         message: `${route.method} ${route.path} has no static provenance coverage`,
       })
     }
+    // A safe-method route that REACHES a domain write without declaring it used to draw two findings
+    // giving opposite advice: declare it (evidence exceeds its declaration) and do not declare it (a
+    // safe method cannot carry a domain write). Both are right and together they are a dead end - the
+    // route cannot declare its way out, because the problem is not the declaration. Reach is computed
+    // from the module that registers the route, so a read endpoint sitting beside a write seam has
+    // write powers in scope, and the only fix is to confine them. Report that once, and say so.
+    const unconfined = new Set<string>()
     for (const id of evidenceIds) {
-      if (!declared.includes(id)) {
+      if (declared.includes(id)) continue
+      const definition = definitions.get(id)
+      if (
+        SAFE_METHODS.has(route.method) &&
+        definition?.zone === "domain" &&
+        definition.access === "write"
+      ) {
+        unconfined.add(id)
         findings.push({
-          code: "undeclared-capability-evidence",
+          code: "unconfined-write-reach",
           method: route.method,
           path: route.path,
           capability: id,
-          message: `${route.method} ${route.path} evidence exceeds its declaration: ${id}`,
+          message: `${route.method} ${route.path} can reach domain write capability ${id} without declaring it, and a safe method may not declare one - move the route or the effect so the write is not in its module's reach`,
         })
+        continue
       }
+      findings.push({
+        code: "undeclared-capability-evidence",
+        method: route.method,
+        path: route.path,
+        capability: id,
+        message: `${route.method} ${route.path} evidence exceeds its declaration: ${id}`,
+      })
     }
 
     const effective = new Set([...declared, ...evidenceIds])
@@ -363,7 +417,10 @@ export function evaluateCapabilityAssurance(
       if (
         SAFE_METHODS.has(route.method) &&
         definition.zone === "domain" &&
-        definition.access === "write"
+        definition.access === "write" &&
+        // Already reported as unconfined reach, with the fix that case actually has. Repeating "cannot
+        // carry" here is the half of the dead end that sends the reader back the way they came.
+        !unconfined.has(id)
       ) {
         findings.push({
           code: "safe-method-domain-write",
@@ -419,7 +476,7 @@ export function evaluateCapabilityAssurance(
 
 /**
  * Optional effect-ledger fields for one `useCapability` beacon. Token-only by design: an adapter
- * names *what* it touched and *how much resource* it used — never the value it read or wrote.
+ * names *what* it touched and *how much resource* it used - never the value it read or wrote.
  */
 export interface UseCapabilityOptions {
   /** Adapter/resource token recorded on the ledger entry (`repo:orders`). */
@@ -664,6 +721,11 @@ export async function executeCapability<T>(
   }
   const guard = guardFor(context, capability)
   const ledger = effectLedgerOf(context)
+  // An explicitly passed journal wins, so every existing call site behaves exactly as it did. The
+  // context journal is what the `durableCommand()` adapter installs, so that declaring the adapter
+  // once journals every effect on the request rather than each call site remembering to thread it -
+  // and so the `nifra.durable-command` evidence it declares is backed by something.
+  const journal = options.journal ?? capabilityJournalOf(context)
   const effectId = crypto.randomUUID()
   const metadata = normalizeEffectMetadata(options)
   const trace = effectTraceParentOf(context)
@@ -709,7 +771,7 @@ export async function executeCapability<T>(
       transitions: {
         async intent(execution) {
           ledger?.append({ capability, effectId: execution.effectId, ...metadata, phase: "intent" })
-          await options.journal?.intent({
+          await journal?.intent({
             effectId: execution.effectId,
             capability,
             ...(metadata.target === undefined ? {} : { target: metadata.target }),
@@ -720,18 +782,18 @@ export async function executeCapability<T>(
           })
         },
         async executing(execution) {
-          await options.journal?.executing(execution.effectId)
+          await journal?.executing(execution.effectId)
         },
         async committed(execution) {
           try {
-            await options.journal?.committed(execution.effectId)
+            await journal?.committed(execution.effectId)
           } catch {
             throw new CapabilityJournalTransitionError(capability, execution.effectId, "committed")
           }
         },
         async failed(execution, failure) {
           try {
-            await options.journal?.failed(execution.effectId, {
+            await journal?.failed(execution.effectId, {
               began: failure.began,
               errorCode: failure.errorCode,
             })

package/src/classification.ts

@@ -1,6 +1,6 @@
 /**
  * Response data-classification tags. A route can declare the highest sensitivity its response body
- * carries (`schema.classification`). This is a declarative, compile-time + introspection fact — never
+ * carries (`schema.classification`). This is a declarative, compile-time + introspection fact - never
  * read on the request hot path and never enforced at runtime here. Downstream consumers use it: a
  * partner-API surface refuses to expose a route whose response is `pii`/`secret`, privacy tooling
  * learns which routes emit regulated data, and the capability lockfile records it so a route that

package/src/diff.ts

@@ -1,21 +1,21 @@
 /**
  * API breaking-change detection over route reflection.
  *
- * `snapshotRoutes` turns an app (or reflected descriptors) into a plain-JSON snapshot — the
+ * `snapshotRoutes` turns an app (or reflected descriptors) into a plain-JSON snapshot - the
  * `standard` validators are dropped, so a snapshot survives `JSON.stringify` and can be committed
  * as a CI baseline. `diffRouteSnapshots` compares two snapshots and classifies every change by
  * wire compatibility, direction-aware:
  *
- *   request direction (body/query — what clients SEND):  a new required field, a removed field, or
+ *   request direction (body/query - what clients SEND):  a new required field, a removed field, or
  *     a narrowed type breaks existing callers; widening (new optional field, enum superset,
  *     required→optional) is compatible.
- *   response direction (response/sse/errors — what clients RECEIVE): a removed field, a field made
+ *   response direction (response/sse/errors - what clients RECEIVE): a removed field, a field made
  *     optional, or a widened type breaks existing readers; narrowing (new field, optional→required,
  *     enum subset) is compatible.
  *
  * The classifier FAILS CLOSED: a schema change it cannot prove compatible is reported as breaking.
  * Schemas without JSON Schema metadata (validation-only Standard Schemas) cannot be compared and
- * yield `info` — never a silent pass presented as proof.
+ * yield `info` - never a silent pass presented as proof.
  */
 
 import {
@@ -39,7 +39,7 @@ export interface RouteSnapshotSchema {
   readonly errors?: Readonly<Record<string, SchemaSnapshot>>
 }
 
-/** One route in a snapshot — plain JSON, safe to persist as a CI baseline. */
+/** One route in a snapshot - plain JSON, safe to persist as a CI baseline. */
 export interface RouteSnapshot {
   readonly method: string
   readonly path: string
@@ -61,7 +61,7 @@ export interface RouteChange {
 
 export interface RoutesDiff {
   readonly changes: readonly RouteChange[]
-  /** True when any change is `breaking` — the CI-gate signal. */
+  /** True when any change is `breaking` - the CI-gate signal. */
   readonly hasBreaking: boolean
 }
 
@@ -269,9 +269,9 @@ const diffSchemaSection = (
     return
   }
   if (before.jsonSchema === undefined || after.jsonSchema === undefined) {
-    // Validation-only schemas expose no JSON Schema metadata — nothing provable either way.
+    // Validation-only schemas expose no JSON Schema metadata - nothing provable either way.
     if (before.jsonSchema !== after.jsonSchema || before.fields !== after.fields) {
-      push(ctx, "info", `${ctx.section} schema is not introspectable — cannot verify compatibility`)
+      push(ctx, "info", `${ctx.section} schema is not introspectable - cannot verify compatibility`)
     }
     return
   }

package/src/durable-adapters.ts

@@ -461,10 +461,26 @@ export interface PostgresClient {
 }
 
 function sqlIdentifier(value: string): string {
-  if (!/^[a-z_][a-z0-9_]{0,62}$/u.test(value)) throw new TypeError("invalid SQL table prefix")
+  // PostgreSQL truncates identifiers to 63 bytes. Reserve `_records_reconcile` (18 bytes), the
+  // longest suffix this adapter appends, so two accepted prefixes can never collapse to one name.
+  if (!/^[a-z_][a-z0-9_]{0,44}$/u.test(value)) throw new TypeError("invalid SQL table prefix")
   return value
 }
 
+/** Explicit static-analysis boundary: every substitution is a validated, internal SQL fragment. */
+function sqlIdentifiers(strings: TemplateStringsArray, ...values: readonly string[]): string {
+  for (const value of values) {
+    if (!/^(?:[a-z_][a-z0-9_]{0,62}|\?(?:,\?)*)$/u.test(value)) {
+      throw new TypeError("invalid SQL identifier fragment")
+    }
+  }
+  return strings.reduce((sql, part, index) => sql + part + (values[index] ?? ""), "")
+}
+
+function sqlPlaceholders(count: number): string {
+  return Array.from({ length: count }, () => "?").join(",")
+}
+
 function recordFromRow<T>(row: Record<string, unknown> | undefined): T | undefined {
   if (row === undefined) return undefined
   const payload = row.payload
@@ -490,21 +506,13 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
 
   async migrate(): Promise<void> {
     await this.client.query(
-      "CREATE TABLE IF NOT EXISTS " +
-        this.recordsTable +
-        " (kind TEXT NOT NULL, id TEXT NOT NULL, state TEXT NOT NULL, updated_at BIGINT NOT NULL, version BIGINT NOT NULL, payload JSONB NOT NULL, PRIMARY KEY (kind, id))",
+      sqlIdentifiers`CREATE TABLE IF NOT EXISTS ${this.recordsTable} (kind TEXT NOT NULL, id TEXT NOT NULL, state TEXT NOT NULL, updated_at BIGINT NOT NULL, version BIGINT NOT NULL, payload JSONB NOT NULL, PRIMARY KEY (kind, id))`,
     )
     await this.client.query(
-      "CREATE INDEX IF NOT EXISTS " +
-        this.recordsTable +
-        "_reconcile ON " +
-        this.recordsTable +
-        " (kind, state, updated_at, id)",
+      sqlIdentifiers`CREATE INDEX IF NOT EXISTS ${this.recordsTable}_reconcile ON ${this.recordsTable} (kind, state, updated_at, id)`,
     )
     await this.client.query(
-      "CREATE TABLE IF NOT EXISTS " +
-        this.leasesTable +
-        " (name TEXT PRIMARY KEY, owner TEXT, token TEXT, expires_at BIGINT NOT NULL DEFAULT 0, cursor TEXT)",
+      sqlIdentifiers`CREATE TABLE IF NOT EXISTS ${this.leasesTable} (name TEXT PRIMARY KEY, owner TEXT, token TEXT, expires_at BIGINT NOT NULL DEFAULT 0, cursor TEXT)`,
     )
   }
 
@@ -514,9 +522,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
     record: { readonly version: number; readonly state?: string; readonly updatedAt?: number },
   ): Promise<boolean> {
     const result = await this.client.query(
-      "INSERT INTO " +
-        this.recordsTable +
-        " (kind,id,state,updated_at,version,payload) VALUES ($1,$2,$3,$4,$5,$6::jsonb) ON CONFLICT DO NOTHING RETURNING id",
+      sqlIdentifiers`INSERT INTO ${this.recordsTable} (kind,id,state,updated_at,version,payload) VALUES ($1,$2,$3,$4,$5,$6::jsonb) ON CONFLICT DO NOTHING RETURNING id`,
       [
         kind,
         id,
@@ -533,7 +539,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
     id: string,
   ): Promise<T | undefined> {
     const result = await this.client.query(
-      `SELECT payload FROM ${this.recordsTable} WHERE kind=$1 AND id=$2`,
+      sqlIdentifiers`SELECT payload FROM ${this.recordsTable} WHERE kind=$1 AND id=$2`,
       [kind, id],
     )
     return recordFromRow<T>(result.rows[0])
@@ -546,9 +552,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
   ): Promise<boolean> {
     if (record.version !== expectedVersion + 1) return false
     const result = await this.client.query(
-      "UPDATE " +
-        this.recordsTable +
-        " SET state=$4,updated_at=$5,version=$6,payload=$7::jsonb WHERE kind=$1 AND id=$2 AND version=$3 RETURNING id",
+      sqlIdentifiers`UPDATE ${this.recordsTable} SET state=$4,updated_at=$5,version=$6,payload=$7::jsonb WHERE kind=$1 AND id=$2 AND version=$3 RETURNING id`,
       [
         kind,
         id,
@@ -566,9 +570,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
     input: ReconciliationScanOptions<string>,
   ): Promise<ReconciliationScanPage<T>> {
     const result = await this.client.query(
-      "SELECT id,payload FROM " +
-        this.recordsTable +
-        " WHERE kind=$1 AND state = ANY($2::text[]) AND ($3::bigint IS NULL OR updated_at <= $3) AND ($4::text IS NULL OR id > $4) ORDER BY id LIMIT $5",
+      sqlIdentifiers`SELECT id,payload FROM ${this.recordsTable} WHERE kind=$1 AND state = ANY($2::text[]) AND ($3::bigint IS NULL OR updated_at <= $3) AND ($4::text IS NULL OR id > $4) ORDER BY id LIMIT $5`,
       [kind, input.states, input.updatedBefore ?? null, input.cursor ?? null, input.limit + 1],
     )
     const hasMore = result.rows.length > input.limit
@@ -584,11 +586,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
     const token = crypto.randomUUID()
     const expiresAt = input.now + input.leaseMs
     const result = await this.client.query(
-      "INSERT INTO " +
-        this.leasesTable +
-        " (name,owner,token,expires_at) VALUES ($1,$2,$3,$4) ON CONFLICT (name) DO UPDATE SET owner=EXCLUDED.owner,token=EXCLUDED.token,expires_at=EXCLUDED.expires_at WHERE " +
-        this.leasesTable +
-        ".expires_at <= $5 RETURNING name,owner,token,expires_at,cursor",
+      sqlIdentifiers`INSERT INTO ${this.leasesTable} (name,owner,token,expires_at) VALUES ($1,$2,$3,$4) ON CONFLICT (name) DO UPDATE SET owner=EXCLUDED.owner,token=EXCLUDED.token,expires_at=EXCLUDED.expires_at WHERE ${this.leasesTable}.expires_at <= $5 RETURNING name,owner,token,expires_at,cursor`,
       [input.name, input.owner, token, expiresAt, input.now],
     )
     const row = result.rows[0]
@@ -603,9 +601,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
   }
   async renewLease(input: Parameters<DurableRecordBackend["renewLease"]>[0]): Promise<boolean> {
     const result = await this.client.query(
-      "UPDATE " +
-        this.leasesTable +
-        " SET expires_at=$4 WHERE name=$1 AND owner=$2 AND token=$3 AND expires_at>$5 RETURNING name",
+      sqlIdentifiers`UPDATE ${this.leasesTable} SET expires_at=$4 WHERE name=$1 AND owner=$2 AND token=$3 AND expires_at>$5 RETURNING name`,
       [input.name, input.owner, input.token, input.now + input.leaseMs, input.now],
     )
     return result.rows.length === 1
@@ -614,18 +610,14 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
     input: Parameters<DurableRecordBackend["checkpointLease"]>[0],
   ): Promise<boolean> {
     const result = await this.client.query(
-      "UPDATE " +
-        this.leasesTable +
-        " SET cursor=$4 WHERE name=$1 AND owner=$2 AND token=$3 RETURNING name",
+      sqlIdentifiers`UPDATE ${this.leasesTable} SET cursor=$4 WHERE name=$1 AND owner=$2 AND token=$3 RETURNING name`,
       [input.name, input.owner, input.token, input.cursor ?? null],
     )
     return result.rows.length === 1
   }
   async releaseLease(input: Parameters<DurableRecordBackend["releaseLease"]>[0]): Promise<boolean> {
     const result = await this.client.query(
-      "UPDATE " +
-        this.leasesTable +
-        " SET owner=NULL,token=NULL,expires_at=0 WHERE name=$1 AND owner=$2 AND token=$3 RETURNING name",
+      sqlIdentifiers`UPDATE ${this.leasesTable} SET owner=NULL,token=NULL,expires_at=0 WHERE name=$1 AND owner=$2 AND token=$3 RETURNING name`,
       [input.name, input.owner, input.token],
     )
     return result.rows.length === 1
@@ -680,17 +672,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
   }
   migrate(): void {
     this.client.exec(
-      "CREATE TABLE IF NOT EXISTS " +
-        this.recordsTable +
-        " (kind TEXT NOT NULL, id TEXT NOT NULL, state TEXT NOT NULL, updated_at INTEGER NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL, PRIMARY KEY (kind,id));" +
-        "CREATE INDEX IF NOT EXISTS " +
-        this.recordsTable +
-        "_reconcile ON " +
-        this.recordsTable +
-        " (kind,state,updated_at,id);" +
-        "CREATE TABLE IF NOT EXISTS " +
-        this.leasesTable +
-        " (name TEXT PRIMARY KEY, owner TEXT, token TEXT, expires_at INTEGER NOT NULL DEFAULT 0, cursor TEXT);",
+      sqlIdentifiers`CREATE TABLE IF NOT EXISTS ${this.recordsTable} (kind TEXT NOT NULL, id TEXT NOT NULL, state TEXT NOT NULL, updated_at INTEGER NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL, PRIMARY KEY (kind,id));CREATE INDEX IF NOT EXISTS ${this.recordsTable}_reconcile ON ${this.recordsTable} (kind,state,updated_at,id);CREATE TABLE IF NOT EXISTS ${this.leasesTable} (name TEXT PRIMARY KEY, owner TEXT, token TEXT, expires_at INTEGER NOT NULL DEFAULT 0, cursor TEXT);`,
     )
   }
   async create(
@@ -700,9 +682,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
   ): Promise<boolean> {
     const result = this.client
       .query(
-        "INSERT OR IGNORE INTO " +
-          this.recordsTable +
-          " (kind,id,state,updated_at,version,payload) VALUES (?,?,?,?,?,?)",
+        sqlIdentifiers`INSERT OR IGNORE INTO ${this.recordsTable} (kind,id,state,updated_at,version,payload) VALUES (?,?,?,?,?,?)`,
       )
       .run(
         kind,
@@ -719,7 +699,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
     id: string,
   ): Promise<T | undefined> {
     const row = this.client
-      .query(`SELECT payload FROM ${this.recordsTable} WHERE kind=? AND id=?`)
+      .query(sqlIdentifiers`SELECT payload FROM ${this.recordsTable} WHERE kind=? AND id=?`)
       .get(kind, id)
     return recordFromRow<T>(row ?? undefined)
   }
@@ -732,9 +712,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
     if (record.version !== expectedVersion + 1) return false
     const result = this.client
       .query(
-        "UPDATE " +
-          this.recordsTable +
-          " SET state=?,updated_at=?,version=?,payload=? WHERE kind=? AND id=? AND version=?",
+        sqlIdentifiers`UPDATE ${this.recordsTable} SET state=?,updated_at=?,version=?,payload=? WHERE kind=? AND id=? AND version=?`,
       )
       .run(
         record.state ?? "",
@@ -752,14 +730,10 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
     input: ReconciliationScanOptions<string>,
   ): Promise<ReconciliationScanPage<T>> {
     if (input.states.length === 0) return { records: [] }
-    const placeholders = input.states.map(() => "?").join(",")
+    const placeholders = sqlPlaceholders(input.states.length)
     const rows = this.client
       .query(
-        "SELECT id,payload FROM " +
-          this.recordsTable +
-          " WHERE kind=? AND state IN (" +
-          placeholders +
-          ") AND (? IS NULL OR updated_at <= ?) AND (? IS NULL OR id > ?) ORDER BY id LIMIT ?",
+        sqlIdentifiers`SELECT id,payload FROM ${this.recordsTable} WHERE kind=? AND state IN (${placeholders}) AND (? IS NULL OR updated_at <= ?) AND (? IS NULL OR id > ?) ORDER BY id LIMIT ?`,
       )
       .all(
         kind,
@@ -785,11 +759,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
     const expiresAt = input.now + input.leaseMs
     const row = this.client
       .query(
-        "INSERT INTO " +
-          this.leasesTable +
-          " (name,owner,token,expires_at) VALUES (?,?,?,?) ON CONFLICT(name) DO UPDATE SET owner=excluded.owner,token=excluded.token,expires_at=excluded.expires_at WHERE " +
-          this.leasesTable +
-          ".expires_at <= ? RETURNING name,owner,token,expires_at,cursor",
+        sqlIdentifiers`INSERT INTO ${this.leasesTable} (name,owner,token,expires_at) VALUES (?,?,?,?) ON CONFLICT(name) DO UPDATE SET owner=excluded.owner,token=excluded.token,expires_at=excluded.expires_at WHERE ${this.leasesTable}.expires_at <= ? RETURNING name,owner,token,expires_at,cursor`,
       )
       .get(input.name, input.owner, token, expiresAt, input.now)
     if (row === undefined || row === null) return undefined
@@ -805,7 +775,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
     return (
       this.client
         .query(
-          `UPDATE ${this.leasesTable} SET expires_at=? WHERE name=? AND owner=? AND token=? AND expires_at>?`,
+          sqlIdentifiers`UPDATE ${this.leasesTable} SET expires_at=? WHERE name=? AND owner=? AND token=? AND expires_at>?`,
         )
         .run(input.now + input.leaseMs, input.name, input.owner, input.token, input.now).changes ===
       1
@@ -816,7 +786,9 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
   ): Promise<boolean> {
     return (
       this.client
-        .query(`UPDATE ${this.leasesTable} SET cursor=? WHERE name=? AND owner=? AND token=?`)
+        .query(
+          sqlIdentifiers`UPDATE ${this.leasesTable} SET cursor=? WHERE name=? AND owner=? AND token=?`,
+        )
         .run(input.cursor ?? null, input.name, input.owner, input.token).changes === 1
     )
   }
@@ -824,9 +796,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
     return (
       this.client
         .query(
-          "UPDATE " +
-            this.leasesTable +
-            " SET owner=NULL,token=NULL,expires_at=0 WHERE name=? AND owner=? AND token=?",
+          sqlIdentifiers`UPDATE ${this.leasesTable} SET owner=NULL,token=NULL,expires_at=0 WHERE name=? AND owner=? AND token=?`,
         )
         .run(input.name, input.owner, input.token).changes === 1
     )

package/src/durable-execution.ts

@@ -1,8 +1,8 @@
 /**
  * Durable capability execution primitives. This subpath is opt-in so the bare HTTP runtime stays
  * lean. Approval and journal records are token-only. Saga input, results, and compensation arguments
- * intentionally live only in the caller-supplied durable saga store — never in the effect ledger or
- * telemetry — and production stores should encrypt them according to the application's data policy.
+ * intentionally live only in the caller-supplied durable saga store - never in the effect ledger or
+ * telemetry - and production stores should encrypt them according to the application's data policy.
  */
 
 import { type EffectLifecycleObserver, emitEffectLifecycle } from "./effect-lifecycle.ts"

package/src/idempotency.ts

@@ -2,7 +2,7 @@
  * Idempotency primitive. A mutating route can declare `schema.idempotency`; the server then dedupes
  * on an `Idempotency-Key` header: the first request runs and its response is stored, and a retry with
  * the same key replays the stored response byte-for-byte without re-running the handler. A retry that
- * reuses a key with a *different* request body is rejected (409) — a key binds to one request.
+ * reuses a key with a *different* request body is rejected (409) - a key binds to one request.
  *
  * This module is the runtime-neutral core: the store interface, an in-memory store, the request
  * fingerprint, and response (de)serialization. The server owns the request-path lane that reads the
@@ -136,7 +136,7 @@ const encoder = new TextEncoder()
 
 /**
  * SHA-256 fingerprint binding a key to one request: method, path (+ query), and the raw body bytes.
- * A collision-resistant hash matters — a weak hash would let a crafted body replay another's response.
+ * A collision-resistant hash matters - a weak hash would let a crafted body replay another's response.
  */
 export async function computeIdempotencyFingerprint(
   method: string,
@@ -297,7 +297,7 @@ export function responseFromStored(
   const headers = new Headers(replaySafeHeaders(stored.headers) as [string, string][])
   headers.set(IDEMPOTENT_REPLAY_HEADER, "1")
   // Reference the Response body type structurally: `BodyInit` isn't a named type under every lib config,
-  // but a fresh `Uint8Array` is a valid body — the cast bridges the `ArrayBufferLike` generic variance.
+  // but a fresh `Uint8Array` is a valid body - the cast bridges the `ArrayBufferLike` generic variance.
   const body = (stored.body === "" ? null : base64ToBytes(stored.body)) as ConstructorParameters<
     typeof Response
   >[0]
@@ -320,7 +320,7 @@ export interface MemoryIdempotencyStoreOptions {
 }
 
 /**
- * In-process idempotency store. Reservation is atomic by construction — `begin` never awaits, so the
+ * In-process idempotency store. Reservation is atomic by construction - `begin` never awaits, so the
  * single-threaded event loop serializes concurrent callers for one key. Expired entries are treated
  * as absent (lazy eviction on access); a periodic {@link MemoryIdempotencyStore.sweep} bounds memory.
  */