@nifrajs/core 1.9.1 → 1.10.0

package/src/capabilities.ts

@@ -0,0 +1,430 @@
+/**
+ * Route effect/capability assurance. Declarations are reflected at build/CI time; runtime beacons
+ * are a fail-closed defence at owned effect seams. Static provenance remains the security anchor.
+ */
+
+import type { DataClassification } from "./classification.ts"
+import {
+  CAPABILITY_GUARD,
+  type CapabilityGuard,
+  type CapabilityUseEvent,
+  validCapabilityId,
+} from "./internal/capability-runtime.ts"
+import { NIFRA_ASSURANCE_IDS } from "./internal/route-assurance.ts"
+import { reflectRoutes } from "./reflection.ts"
+
+export type { CapabilityUseEvent }
+
+export type CapabilityZone = "domain" | "operational"
+export type CapabilityAccess = "read" | "write"
+export type CapabilityIdempotency = "none" | "request" | "durable"
+
+export interface CapabilityDefinition {
+  readonly id: string
+  /** Domain state is subject to HTTP method semantics; operational writes (logs/metrics) are not. */
+  readonly zone: CapabilityZone
+  readonly access: CapabilityAccess
+  /** Evidence required when this capability may execute. Default `none`. */
+  readonly idempotency?: CapabilityIdempotency
+}
+
+export interface CapabilityImportRule {
+  /** Exact module specifier, or a trailing `/*` prefix rule. */
+  readonly specifier: string
+  readonly capabilities: readonly string[]
+}
+
+export interface ForbiddenCapabilityImport {
+  /** Exact module specifier, or a trailing `/*` prefix rule. */
+  readonly specifier: string
+  readonly reason: string
+}
+
+export interface CapabilityRouteSelector {
+  readonly methods?: readonly string[]
+  readonly paths?: readonly string[]
+}
+
+export interface CapabilityRouteModule {
+  readonly match: CapabilityRouteSelector
+  /** Project-relative modules that implement the selected routes. */
+  readonly modules: readonly string[]
+}
+
+export interface CapabilityProvenancePolicy {
+  readonly imports: readonly CapabilityImportRule[]
+  readonly forbiddenImports: readonly ForbiddenCapabilityImport[]
+  /** Explicit associations for contract/generated routes that source scanning cannot locate. */
+  readonly routeModules?: readonly CapabilityRouteModule[]
+}
+
+export interface CapabilityPolicy {
+  readonly definitions: readonly CapabilityDefinition[]
+  /** Required: capability assurance without a static provenance firewall is incomplete. */
+  readonly provenance: CapabilityProvenancePolicy
+  /** Default `capabilities.lock.json`. */
+  readonly lockfile?: string
+}
+
+export type CapabilityEvidenceKind = "static" | "runtime"
+
+/** Token-only effect evidence. `source` is an adapter/module id, never request or business data. */
+export interface CapabilityEvidence {
+  readonly id: string
+  readonly kind: CapabilityEvidenceKind
+  readonly source: string
+}
+
+export interface RouteCapabilityEvidence {
+  readonly method: string
+  readonly path: string
+  /** True only when the route's reachable module graph was actually scanned. */
+  readonly covered: boolean
+  readonly evidence: readonly CapabilityEvidence[]
+}
+
+export interface CapabilityEvidenceSet {
+  readonly routes: readonly RouteCapabilityEvidence[]
+}
+
+export type CapabilityFindingCode =
+  | "unknown-capability"
+  | "provenance-uncovered"
+  | "undeclared-capability-evidence"
+  | "safe-method-domain-write"
+  | "missing-request-idempotency"
+  | "missing-durable-idempotency"
+  | "forbidden-effect-import"
+
+export interface CapabilityFinding {
+  readonly code: CapabilityFindingCode
+  readonly method: string
+  readonly path: string
+  readonly capability?: string
+  readonly message: string
+}
+
+export interface AssuredCapabilityRoute {
+  readonly method: string
+  readonly path: string
+  readonly declared: readonly string[]
+  readonly evidence: readonly CapabilityEvidence[]
+  /** Declared capabilities without static/runtime evidence. Informational, never treated as proof. */
+  readonly unproven: readonly string[]
+  readonly covered: boolean
+  /** Highest data-sensitivity the response carries, when the route declares it. */
+  readonly classification?: DataClassification
+}
+
+export interface CapabilityAssuranceReport {
+  readonly ok: boolean
+  readonly routes: readonly AssuredCapabilityRoute[]
+  readonly findings: readonly CapabilityFinding[]
+}
+
+export interface CapabilitySnapshotRoute {
+  readonly method: string
+  readonly path: string
+  readonly declared: readonly string[]
+  readonly evidenced: readonly string[]
+  readonly unproven: readonly string[]
+  /** Recorded so a route that starts returning `pii`/`secret` flips the lockfile and forces a review. */
+  readonly classification?: DataClassification
+}
+
+export interface CapabilitySnapshot {
+  readonly nifraCapabilities: 1
+  readonly routes: readonly CapabilitySnapshotRoute[]
+}
+
+const SAFE_METHODS = new Set(["GET", "HEAD"])
+
+export { validCapabilityId }
+
+function normalizedIds(values: readonly string[], label: string): readonly string[] {
+  if (!Array.isArray(values)) throw new TypeError(`${label} must be an array`)
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const value of values) {
+    if (typeof value !== "string" || !validCapabilityId(value)) {
+      throw new Error(`capability assurance: invalid ${label} id ${JSON.stringify(value)}`)
+    }
+    if (!seen.has(value)) {
+      seen.add(value)
+      out.push(value)
+    }
+  }
+  return Object.freeze(out)
+}
+
+function validSpecifier(value: string): boolean {
+  return value.trim() === value && value !== "" && !hasControlCharacter(value)
+}
+
+function hasControlCharacter(value: string): boolean {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index)
+    if (code <= 31 || code === 127) return true
+  }
+  return false
+}
+
+/** Validate and freeze a capability/provenance policy. */
+export function defineCapabilityPolicy(policy: CapabilityPolicy): CapabilityPolicy {
+  if (policy.provenance === undefined || policy.provenance === null) {
+    throw new Error("capability assurance: provenance policy is required")
+  }
+  const ids = new Set<string>()
+  const definitions = policy.definitions.map((definition): CapabilityDefinition => {
+    if (!validCapabilityId(definition.id)) {
+      throw new Error(
+        `capability assurance: invalid capability id ${JSON.stringify(definition.id)}`,
+      )
+    }
+    if (ids.has(definition.id)) {
+      throw new Error(`capability assurance: duplicate capability ${JSON.stringify(definition.id)}`)
+    }
+    ids.add(definition.id)
+    if (definition.zone !== "domain" && definition.zone !== "operational") {
+      throw new Error(`capability assurance: invalid zone for ${definition.id}`)
+    }
+    if (definition.access !== "read" && definition.access !== "write") {
+      throw new Error(`capability assurance: invalid access for ${definition.id}`)
+    }
+    const idempotency = definition.idempotency ?? "none"
+    if (idempotency !== "none" && idempotency !== "request" && idempotency !== "durable") {
+      throw new Error(`capability assurance: invalid idempotency for ${definition.id}`)
+    }
+    if (definition.access === "read" && idempotency !== "none") {
+      throw new Error(
+        `capability assurance: read capability ${definition.id} cannot require idempotency`,
+      )
+    }
+    return Object.freeze({ ...definition, idempotency })
+  })
+  const imports = policy.provenance.imports.map((rule): CapabilityImportRule => {
+    if (!validSpecifier(rule.specifier))
+      throw new Error("capability assurance: invalid import specifier")
+    const capabilities = normalizedIds(rule.capabilities, "import capability")
+    for (const id of capabilities) {
+      if (!ids.has(id)) throw new Error(`capability assurance: import references unknown ${id}`)
+    }
+    return Object.freeze({ specifier: rule.specifier, capabilities })
+  })
+  const forbiddenImports = policy.provenance.forbiddenImports.map(
+    (rule): ForbiddenCapabilityImport => {
+      if (!validSpecifier(rule.specifier) || rule.reason.trim() === "") {
+        throw new Error("capability assurance: forbidden import needs a specifier and reason")
+      }
+      return Object.freeze({ specifier: rule.specifier, reason: rule.reason.trim() })
+    },
+  )
+  const routeModules = policy.provenance.routeModules?.map((rule): CapabilityRouteModule => {
+    if (!Array.isArray(rule.modules) || rule.modules.length === 0) {
+      throw new Error("capability assurance: routeModules entry needs at least one module")
+    }
+    const modules = rule.modules.map((module) => {
+      if (!validSpecifier(module)) throw new Error("capability assurance: invalid route module")
+      return module.replace(/^\.\//, "")
+    })
+    return Object.freeze({
+      match: Object.freeze({
+        ...(rule.match.methods !== undefined
+          ? { methods: Object.freeze(rule.match.methods.map((method) => method.toUpperCase())) }
+          : {}),
+        ...(rule.match.paths !== undefined ? { paths: Object.freeze([...rule.match.paths]) } : {}),
+      }),
+      modules: Object.freeze(modules),
+    })
+  })
+  return Object.freeze({
+    definitions: Object.freeze(definitions),
+    provenance: Object.freeze({
+      imports: Object.freeze(imports),
+      forbiddenImports: Object.freeze(forbiddenImports),
+      ...(routeModules !== undefined ? { routeModules: Object.freeze(routeModules) } : {}),
+    }),
+    lockfile: policy.lockfile ?? "capabilities.lock.json",
+  })
+}
+
+function evidenceSourceValid(source: string): boolean {
+  return source.length > 0 && source.length <= 256 && !hasControlCharacter(source)
+}
+
+function routeKey(method: string, path: string): string {
+  return `${method.toUpperCase()}\n${path}`
+}
+
+/** Compare declared route capabilities against coverage-qualified static/runtime evidence. */
+export function evaluateCapabilityAssurance(
+  source: unknown,
+  policyInput: CapabilityPolicy,
+  evidenceSet: CapabilityEvidenceSet,
+): CapabilityAssuranceReport {
+  const policy = defineCapabilityPolicy(policyInput)
+  const definitions = new Map(policy.definitions.map((definition) => [definition.id, definition]))
+  const evidenceByRoute = new Map(
+    evidenceSet.routes.map((route) => [routeKey(route.method, route.path), route]),
+  )
+  const findings: CapabilityFinding[] = []
+  const routes: AssuredCapabilityRoute[] = []
+
+  for (const route of reflectRoutes(source)) {
+    const declared = route.capabilities ?? []
+    const supplied = evidenceByRoute.get(routeKey(route.method, route.path))
+    const covered = supplied?.covered === true
+    const evidence: CapabilityEvidence[] = []
+    const evidenceIds = new Set<string>()
+    for (const item of supplied?.evidence ?? []) {
+      if (
+        !validCapabilityId(item.id) ||
+        (item.kind !== "static" && item.kind !== "runtime") ||
+        !evidenceSourceValid(item.source)
+      ) {
+        continue
+      }
+      const key = `${item.id}\n${item.kind}\n${item.source}`
+      if (
+        evidence.some(
+          (candidate) => `${candidate.id}\n${candidate.kind}\n${candidate.source}` === key,
+        )
+      )
+        continue
+      evidence.push(Object.freeze({ id: item.id, kind: item.kind, source: item.source }))
+      evidenceIds.add(item.id)
+    }
+
+    for (const id of declared) {
+      if (!definitions.has(id)) {
+        findings.push({
+          code: "unknown-capability",
+          method: route.method,
+          path: route.path,
+          capability: id,
+          message: `${route.method} ${route.path} declares unknown capability ${id}`,
+        })
+      }
+    }
+    if (!covered) {
+      findings.push({
+        code: "provenance-uncovered",
+        method: route.method,
+        path: route.path,
+        message: `${route.method} ${route.path} has no static provenance coverage`,
+      })
+    }
+    for (const id of evidenceIds) {
+      if (!declared.includes(id)) {
+        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])
+    const assuranceIds = new Set((route.assurance ?? []).map((item) => item.id))
+    for (const id of effective) {
+      const definition = definitions.get(id)
+      if (definition === undefined) continue
+      if (
+        SAFE_METHODS.has(route.method) &&
+        definition.zone === "domain" &&
+        definition.access === "write"
+      ) {
+        findings.push({
+          code: "safe-method-domain-write",
+          method: route.method,
+          path: route.path,
+          capability: id,
+          message: `${route.method} ${route.path} cannot carry domain write capability ${id}`,
+        })
+      }
+      if (
+        definition.idempotency === "request" &&
+        !assuranceIds.has(NIFRA_ASSURANCE_IDS.IDEMPOTENCY_KEY)
+      ) {
+        findings.push({
+          code: "missing-request-idempotency",
+          method: route.method,
+          path: route.path,
+          capability: id,
+          message: `${route.method} ${route.path} capability ${id} requires request idempotency evidence`,
+        })
+      }
+      if (
+        definition.idempotency === "durable" &&
+        !assuranceIds.has(NIFRA_ASSURANCE_IDS.DURABLE_COMMAND)
+      ) {
+        findings.push({
+          code: "missing-durable-idempotency",
+          method: route.method,
+          path: route.path,
+          capability: id,
+          message: `${route.method} ${route.path} capability ${id} requires durable command/provider-key evidence`,
+        })
+      }
+    }
+    routes.push(
+      Object.freeze({
+        method: route.method,
+        path: route.path,
+        declared: Object.freeze([...declared]),
+        evidence: Object.freeze(evidence),
+        unproven: Object.freeze(declared.filter((id) => !evidenceIds.has(id))),
+        covered,
+        ...(route.classification !== undefined ? { classification: route.classification } : {}),
+      }),
+    )
+  }
+  return Object.freeze({
+    ok: findings.length === 0,
+    routes: Object.freeze(routes),
+    findings: Object.freeze(findings),
+  })
+}
+
+/**
+ * Runtime effect beacon for owned adapters. It fails closed when the route omitted the capability or
+ * when no route guard is present. Static provenance is still required: code can bypass a beacon.
+ */
+export function useCapability(context: object, capability: string): void {
+  if (!validCapabilityId(capability)) {
+    throw new Error(
+      `capability assurance: invalid runtime capability ${JSON.stringify(capability)}`,
+    )
+  }
+  const guard = (context as { readonly [CAPABILITY_GUARD]?: CapabilityGuard })[CAPABILITY_GUARD]
+  if (guard === undefined) {
+    throw new Error(
+      `capability assurance: ${capability} used on a route with no capability declaration`,
+    )
+  }
+  if (!guard.allowed.includes(capability)) {
+    throw new Error(
+      `capability assurance: ${capability} is not declared for ${guard.method} ${guard.path}`,
+    )
+  }
+  guard.onUse?.({ capability, method: guard.method, path: guard.path })
+}
+
+/** Deterministic, PII-free lockfile material. */
+export function snapshotCapabilities(report: CapabilityAssuranceReport): CapabilitySnapshot {
+  const routes = report.routes
+    .map(
+      (route): CapabilitySnapshotRoute => ({
+        method: route.method,
+        path: route.path,
+        declared: Object.freeze([...route.declared].sort()),
+        evidenced: Object.freeze([...new Set(route.evidence.map((item) => item.id))].sort()),
+        unproven: Object.freeze([...route.unproven].sort()),
+        ...(route.classification !== undefined ? { classification: route.classification } : {}),
+      }),
+    )
+    .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
+  return Object.freeze({ nifraCapabilities: 1, routes: Object.freeze(routes) })
+}

package/src/classification.ts

@@ -0,0 +1,44 @@
+/**
+ * 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
+ * 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
+ * *starts* returning PII flips the lockfile and forces a review.
+ */
+
+/** Sensitivity of the data a response carries. Ordered `public` < `pii` < `secret`. */
+export type DataClassification = "public" | "pii" | "secret"
+
+/** Total order over classifications; higher = more sensitive. */
+export const DATA_CLASSIFICATION_RANK: Readonly<Record<DataClassification, number>> = Object.freeze(
+  {
+    public: 0,
+    pii: 1,
+    secret: 2,
+  },
+)
+
+const CLASSIFICATIONS = Object.keys(DATA_CLASSIFICATION_RANK) as readonly DataClassification[]
+
+/** Whether `value` is a known classification token. */
+export function isDataClassification(value: unknown): value is DataClassification {
+  return typeof value === "string" && (CLASSIFICATIONS as readonly string[]).includes(value)
+}
+
+/** The most sensitive classification among the inputs; `"public"` when none are given. */
+export function maxClassification(values: Iterable<DataClassification>): DataClassification {
+  let max: DataClassification = "public"
+  for (const value of values) {
+    if (DATA_CLASSIFICATION_RANK[value] > DATA_CLASSIFICATION_RANK[max]) max = value
+  }
+  return max
+}
+
+/** True when `value` is at least as sensitive as `floor` (e.g. `classificationAtLeast(x, "pii")`). */
+export function classificationAtLeast(
+  value: DataClassification,
+  floor: DataClassification,
+): boolean {
+  return DATA_CLASSIFICATION_RANK[value] >= DATA_CLASSIFICATION_RANK[floor]
+}

package/src/errors.ts

@@ -24,6 +24,7 @@ export type RouteConfigErrorCode =
   | "INVALID_PARAM_NAME"
   | "WILDCARD_NOT_LAST"
   | "INVALID_METHOD"
+  | "INVALID_ASSURANCE"
 
 /**
  * Thrown at route registration when a route is misconfigured. This is the

package/src/idempotency.ts

@@ -0,0 +1,205 @@
+/**
+ * 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.
+ *
+ * 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
+ * body, consults the store, and captures the response. All logic here is pure/injectable so it is
+ * unit-tested without a server. A durable store (cross-restart) implements the same interface.
+ */
+
+/** Whether a route's idempotency is satisfied by an in-process store or a durable (cross-restart) one. */
+export type IdempotencyScope = "request" | "durable"
+
+/** Default retention for a stored idempotent response: 24 hours. */
+export const DEFAULT_IDEMPOTENCY_TTL_MS = 86_400_000
+
+/** Canonical request header carrying the client-chosen idempotency key. */
+export const DEFAULT_IDEMPOTENCY_HEADER = "idempotency-key"
+
+/** Header stamped on a replayed response so clients/proxies can tell a replay from a fresh run. */
+export const IDEMPOTENT_REPLAY_HEADER = "x-nifra-idempotent-replay"
+
+const KEY_MAX_LENGTH = 255
+
+/** A serialized response held by a store. `body` is base64 so binary payloads round-trip intact. */
+export interface StoredResponse {
+  readonly status: number
+  readonly headers: readonly (readonly [string, string])[]
+  /** Base64-encoded response body; `""` when the response had no body. */
+  readonly body: string
+}
+
+/**
+ * Outcome of reserving a key. `new` → the caller runs the handler and later calls {@link
+ * IdempotencyStore.complete}. `replay` → return the stored response, handler never runs. `mismatch`
+ * → same key, different request fingerprint (client bug) → 409. `in-flight` → the key is reserved but
+ * not yet completed (a concurrent duplicate) → 409 + Retry-After.
+ */
+export type IdempotencyBeginResult =
+  | { readonly state: "new" }
+  | { readonly state: "replay"; readonly response: StoredResponse }
+  | { readonly state: "mismatch" }
+  | { readonly state: "in-flight" }
+
+/**
+ * Storage seam for idempotent responses. `begin` MUST be atomic: for one key, exactly one concurrent
+ * caller sees `new`; the rest see `in-flight` (or `replay` once completed). The in-memory store gets
+ * this free from the single-threaded event loop; a durable store uses an atomic insert.
+ */
+export interface IdempotencyStore {
+  /** Reserve `key` for `fingerprint`, retaining any stored response for `ttlMs`. */
+  begin(
+    key: string,
+    fingerprint: string,
+    ttlMs: number,
+  ): IdempotencyBeginResult | Promise<IdempotencyBeginResult>
+  /** Persist the final response for a reserved key so later retries replay it. */
+  complete(key: string, response: StoredResponse): void | Promise<void>
+  /** Release a reservation that produced no cacheable response, so the client may retry. */
+  abandon(key: string): void | Promise<void>
+}
+
+/** A key must be a non-empty, bounded, control-char-free token. Fail closed on anything else. */
+export function validIdempotencyKey(key: string): boolean {
+  if (typeof key !== "string" || key.length === 0 || key.length > KEY_MAX_LENGTH) return false
+  for (let i = 0; i < key.length; i++) {
+    const code = key.charCodeAt(i)
+    if (code <= 31 || code === 127) return false
+  }
+  return true
+}
+
+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.
+ */
+export async function computeIdempotencyFingerprint(
+  method: string,
+  path: string,
+  body: Uint8Array,
+): Promise<string> {
+  const head = encoder.encode(`${method.toUpperCase()}\n${path}\n`)
+  const material = new Uint8Array(head.length + body.length)
+  material.set(head, 0)
+  material.set(body, head.length)
+  const digest = await crypto.subtle.digest("SHA-256", material)
+  const bytes = new Uint8Array(digest)
+  let hex = ""
+  for (let i = 0; i < bytes.length; i++) hex += (bytes[i] as number).toString(16).padStart(2, "0")
+  return hex
+}
+
+const BASE64_CHUNK = 0x8000
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = ""
+  for (let i = 0; i < bytes.length; i += BASE64_CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + BASE64_CHUNK))
+  }
+  return btoa(binary)
+}
+
+function base64ToBytes(value: string): Uint8Array {
+  const binary = atob(value)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+  return bytes
+}
+
+/** Buffer a response into a storable form. Clones first so the live response body stays intact. */
+export async function serializeResponse(response: Response): Promise<StoredResponse> {
+  const bytes = new Uint8Array(await response.clone().arrayBuffer())
+  return {
+    status: response.status,
+    headers: [...response.headers] as readonly (readonly [string, string])[],
+    body: bytes.length > 0 ? bytesToBase64(bytes) : "",
+  }
+}
+
+/** Rebuild a live response from storage, stamping the replay marker header. */
+export function responseFromStored(stored: StoredResponse): Response {
+  const headers = new Headers(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.
+  const body = (stored.body === "" ? null : base64ToBytes(stored.body)) as ConstructorParameters<
+    typeof Response
+  >[0]
+  return new Response(body, { status: stored.status, headers })
+}
+
+interface MemoryEntry {
+  readonly fingerprint: string
+  readonly expiresAt: number
+  response: StoredResponse | undefined
+}
+
+export interface MemoryIdempotencyStoreOptions {
+  /** Injectable clock (epoch ms) for deterministic TTL tests. Default `Date.now`. */
+  readonly now?: () => number
+}
+
+/**
+ * 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.
+ */
+export class MemoryIdempotencyStore implements IdempotencyStore {
+  private readonly entries = new Map<string, MemoryEntry>()
+  private readonly now: () => number
+
+  constructor(options: MemoryIdempotencyStoreOptions = {}) {
+    this.now = options.now ?? Date.now
+  }
+
+  begin(key: string, fingerprint: string, ttlMs: number): IdempotencyBeginResult {
+    const existing = this.entries.get(key)
+    if (existing !== undefined && existing.expiresAt > this.now()) {
+      if (existing.fingerprint !== fingerprint) return { state: "mismatch" }
+      if (existing.response !== undefined) return { state: "replay", response: existing.response }
+      return { state: "in-flight" }
+    }
+    this.entries.set(key, {
+      fingerprint,
+      expiresAt: this.now() + ttlMs,
+      response: undefined,
+    })
+    return { state: "new" }
+  }
+
+  complete(key: string, response: StoredResponse): void {
+    const entry = this.entries.get(key)
+    if (entry !== undefined) entry.response = response
+  }
+
+  abandon(key: string): void {
+    const entry = this.entries.get(key)
+    // Only drop a still-pending reservation; never evict a completed (replayable) response.
+    if (entry !== undefined && entry.response === undefined) this.entries.delete(key)
+  }
+
+  /** Evict expired entries. Callers may run this on an interval; access-time eviction covers the rest. */
+  sweep(): void {
+    const now = this.now()
+    for (const [key, entry] of this.entries) {
+      if (entry.expiresAt <= now) this.entries.delete(key)
+    }
+  }
+
+  /** Live entry count (post-sweep semantics are the caller's; this is a raw size for tests/metrics). */
+  get size(): number {
+    return this.entries.size
+  }
+}
+
+/** Convenience factory mirroring the other core primitives' `create*` style. */
+export function createMemoryIdempotencyStore(
+  options?: MemoryIdempotencyStoreOptions,
+): MemoryIdempotencyStore {
+  return new MemoryIdempotencyStore(options)
+}