@nifrajs/core 1.13.0 → 2.1.0

package/src/internal/effect-execution.ts

@@ -0,0 +1,70 @@
+/** Request-local owned-effect scope used by idempotency and every capability boundary. */
+
+import {
+  createEffectEvidenceScope,
+  type EffectEvidenceScope,
+  type EffectScopeEvidence,
+} from "../effect-scope.ts"
+
+export type RequestEffectEvidence = EffectScopeEvidence
+
+const scopeByRequest = new WeakMap<Request, EffectEvidenceScope>()
+
+export function beginRequestEffectTracking(request: Request): EffectEvidenceScope {
+  const scope = createEffectEvidenceScope()
+  scopeByRequest.set(request, scope)
+  return scope
+}
+
+export function requestEffectScope(request: Request): EffectEvidenceScope | undefined {
+  return scopeByRequest.get(request)
+}
+
+export function requestEffectEvidence(request: Request): RequestEffectEvidence {
+  return (
+    scopeByRequest.get(request)?.evidence() ??
+    Object.freeze({ began: false, committed: false, ambiguous: false })
+  )
+}
+
+export function effectScopeForContext(context: object): EffectEvidenceScope | undefined {
+  const request = (context as { readonly req?: unknown }).req
+  return request instanceof Request ? scopeByRequest.get(request) : undefined
+}
+
+export function markEffect(context: object, committed: boolean): void {
+  const scope = effectScopeForContext(context)
+  if (committed) scope?.markCommitted()
+  else scope?.markBegan()
+}
+
+/** A legacy beacon cannot prove what happens after the call, so it is immediately ambiguous. */
+export function markBeaconEffectBegan(context: object): void {
+  effectScopeForContext(context)?.markBegan()
+}
+
+export function markEffectExecuting(context: object): void {
+  effectScopeForContext(context)?.markBegan()
+}
+
+export function markEffectCommitted(context: object): void {
+  effectScopeForContext(context)?.markCommitted()
+}
+
+export function markEffectAmbiguous(context: object): void {
+  effectScopeForContext(context)?.markAmbiguous()
+}
+
+export function markRequestSafeToRetry(context: object): void {
+  const scope = effectScopeForContext(context)
+  if (scope === undefined) {
+    throw new Error(
+      "markIdempotencySafeToRetry() requires an active route with idempotency enabled",
+    )
+  }
+  scope.markSafeToRetry()
+}
+
+export function requestIsSafeToRetry(request: Request): boolean {
+  return scopeByRequest.get(request)?.safeToRetry() ?? false
+}

package/src/internal/safe-equal.ts

@@ -0,0 +1,27 @@
+/**
+ * Constant-time string comparison for credential-shaped values - lease tokens, token hashes, and
+ * binding digests.
+ *
+ * `a !== b` returns as soon as it finds a differing character, so how long it takes reveals how much
+ * of a guess was correct. That is only exploitable when an attacker can submit guesses and measure,
+ * which is not the case on every path here - but these values are credentials, the comparison is on
+ * the verification path, and doing it correctly costs nothing. Doing it inconsistently is what makes
+ * the one place that matters easy to miss.
+ *
+ * Length is compared first, so a length difference is still observable. Every value compared through
+ * this helper is fixed-width by construction (a UUID, a SHA-256 hex/base64url digest), so length
+ * carries no secret. Content comparison always visits every character.
+ *
+ * Synchronous on purpose: the callers are store transitions and lease checks that are themselves
+ * synchronous. A hash-then-compare variant (which would also hide length) is available as
+ * `timingSafeEqualString` in `@nifrajs/middleware`, but it is async and would force those paths async.
+ */
+export function safeEqual(a: string | undefined, b: string | undefined): boolean {
+  // Accepts `undefined` so optional binding fields keep their exact `!==` semantics at call sites:
+  // absent equals absent, and absent never equals present. Neither branch is secret-bearing.
+  if (a === undefined || b === undefined) return a === b
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  return diff === 0
+}

package/src/ledger.ts

@@ -27,18 +27,24 @@ const EFFECT_PHASES: ReadonlySet<string> = new Set(["intent", "committed", "fail
  */
 export type EffectCost = Readonly<Record<string, number>>
 
-/** Caller-supplied fields for one entry. Everything else (`seq`, `at`) is assigned by the ledger. */
-export interface EffectEntryInput {
-  /** Capability token (`db.write`, `payments.charge`). Must be a valid capability id. */
-  readonly capability: string
-  /** Default `"intent"`. Record `committed`/`failed`/`compensated` only after the outcome is known. */
-  readonly phase?: EffectPhase
+/** Token-only caller metadata shared by an effect intent and outcome. */
+export interface EffectMetadata {
   /** Adapter/resource token (`repo:orders`, `provider:payments`). A token — never a value or a row. */
   readonly target?: string
   /** Dimensionless counters; see {@link EffectCost}. At most {@link MAX_COST_AXES} axes. */
   readonly cost?: EffectCost
   /** Optional keyed-HMAC digest of the effect payload (see {@link computeEffectDigest}); hex, 64 chars. */
   readonly digest?: string
+}
+
+/** Caller-supplied fields for one entry. Everything else (`seq`, `at`) is assigned by the ledger. */
+export interface EffectEntryInput extends EffectMetadata {
+  /** Opaque execution correlation token shared by one intent and its terminal outcome. */
+  readonly effectId?: string
+  /** Capability token (`db.write`, `payments.charge`). Must be a valid capability id. */
+  readonly capability: string
+  /** Default `"intent"`. Record `committed`/`failed`/`compensated` only after the outcome is known. */
+  readonly phase?: EffectPhase
   /** Outcome error as a bounded token code — never a message, never a stack. */
   readonly error?: { readonly code: string }
 }
@@ -49,6 +55,7 @@ export interface EffectEntry {
   readonly seq: number
   /** Milliseconds from the ledger's (injectable) clock at append time. */
   readonly at: number
+  readonly effectId?: string
   readonly capability: string
   readonly phase: EffectPhase
   readonly target?: string
@@ -147,9 +154,12 @@ function printableToken(value: string, maxLength: number): boolean {
 }
 
 function validateCost(cost: EffectCost): EffectCost {
+  if (Object(cost) !== cost || Array.isArray(cost)) {
+    throw new TypeError("effect ledger: invalid cost")
+  }
   const keys = Object.keys(cost)
   if (keys.length > MAX_COST_AXES) {
-    throw new TypeError(`effect ledger: cost carries more than ${MAX_COST_AXES} axes`)
+    throw new TypeError(`effect ledger: more than ${MAX_COST_AXES} cost axes`)
   }
   for (const key of keys) {
     if (!validCapabilityId(key)) {
@@ -157,12 +167,30 @@ function validateCost(cost: EffectCost): EffectCost {
     }
     const value = cost[key]
     if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
-      throw new TypeError(`effect ledger: cost axis ${key} must be a finite non-negative number`)
+      throw new TypeError(`effect ledger: invalid cost axis ${key}`)
     }
   }
   return Object.freeze({ ...cost })
 }
 
+/** Validate, copy, and freeze token-only effect metadata before it reaches a ledger or policy hook. */
+export function normalizeEffectMetadata(input: EffectMetadata): EffectMetadata {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new TypeError("effect ledger: effect metadata must be an object")
+  }
+  if (input.target !== undefined && !printableToken(input.target, TARGET_MAX_LENGTH)) {
+    throw new TypeError("effect ledger: invalid target")
+  }
+  if (input.digest !== undefined && !DIGEST_HEX.test(input.digest)) {
+    throw new TypeError("effect ledger: invalid digest")
+  }
+  return Object.freeze({
+    ...(input.target !== undefined ? { target: input.target } : {}),
+    ...(input.cost !== undefined ? { cost: validateCost(input.cost) } : {}),
+    ...(input.digest !== undefined ? { digest: input.digest } : {}),
+  })
+}
+
 const defaultClock = (): number => performance.now()
 
 class BoundedRequestLedger implements RequestLedger {
@@ -215,11 +243,14 @@ class BoundedRequestLedger implements RequestLedger {
     if (!EFFECT_PHASES.has(phase)) {
       throw new TypeError(`effect ledger: invalid phase ${JSON.stringify(phase)}`)
     }
+    if (input.effectId !== undefined && !printableToken(input.effectId, 64)) {
+      throw new TypeError("effect ledger: invalid effectId")
+    }
     if (input.target !== undefined && !printableToken(input.target, TARGET_MAX_LENGTH)) {
-      throw new TypeError("effect ledger: target must be a bounded printable token")
+      throw new TypeError("effect ledger: invalid target")
     }
     if (input.digest !== undefined && !DIGEST_HEX.test(input.digest)) {
-      throw new TypeError("effect ledger: digest must be 64 lowercase hex characters")
+      throw new TypeError("effect ledger: invalid digest")
     }
     if (input.error !== undefined && !ERROR_CODE.test(input.error.code)) {
       throw new TypeError("effect ledger: error code must be a bounded lowercase token")
@@ -232,6 +263,7 @@ class BoundedRequestLedger implements RequestLedger {
     const entry: EffectEntry = Object.freeze({
       seq: this.items.length,
       at,
+      ...(input.effectId !== undefined ? { effectId: input.effectId } : {}),
       capability: input.capability,
       phase,
       ...(input.target !== undefined ? { target: input.target } : {}),
@@ -293,7 +325,9 @@ function canonicalEntry(entry: EffectEntry): string {
           .map((key) => `${JSON.stringify(key)}:${JSON.stringify((entry.cost as EffectCost)[key])}`)
           .join(",")}}`
   return (
-    `{"seq":${entry.seq},"at":${JSON.stringify(entry.at)},"capability":${JSON.stringify(entry.capability)},"phase":${JSON.stringify(entry.phase)}` +
+    `{"seq":${entry.seq},"at":${JSON.stringify(entry.at)}` +
+    `${entry.effectId !== undefined ? `,"effectId":${JSON.stringify(entry.effectId)}` : ""}` +
+    `,"capability":${JSON.stringify(entry.capability)},"phase":${JSON.stringify(entry.phase)}` +
     `${entry.target !== undefined ? `,"target":${JSON.stringify(entry.target)}` : ""}` +
     cost +
     `${entry.digest !== undefined ? `,"digest":${JSON.stringify(entry.digest)}` : ""}` +

package/src/mcp.ts

@@ -0,0 +1,65 @@
+/**
+ * The opt-in MCP runtime plugin.
+ *
+ * `.use(mcp())` enables `.tool()`, `.resource()`, and `.prompt()`. Without it those methods throw at
+ * registration (fail-closed), so an ordinary HTTP app never evaluates or bundles the MCP wiring. This
+ * is the same install seam as `.use(idempotency())` / `.use(effectLedger())` - one consistent `.use()`
+ * opt-in, not a side-effect import.
+ */
+import { INSTALL_MCP } from "./server/install.ts"
+import type { McpRuntime } from "./server/mcp-hook.ts"
+import type { IdentityPlugin } from "./server/plugin.ts"
+import type { AnyServer } from "./server/server.ts"
+
+const MCP_RUNTIME: McpRuntime = {
+  tool(name, config, handler) {
+    const path = `/_nifra/tool/${name}`
+    return {
+      path,
+      schema:
+        config.output !== undefined
+          ? { body: config.input, response: config.output }
+          : { body: config.input },
+      run: (context) => handler(context.body, context),
+      descriptor: {
+        name,
+        description: config.description,
+        ...(config.annotations !== undefined ? { annotations: config.annotations } : {}),
+      },
+    }
+  },
+  resource(uri, config, read) {
+    return {
+      uri,
+      name: config.name,
+      ...(config.description !== undefined ? { description: config.description } : {}),
+      ...(config.mimeType !== undefined ? { mimeType: config.mimeType } : {}),
+      read,
+    }
+  },
+  prompt(name, config, handler) {
+    return {
+      name,
+      description: config.description,
+      ...(config.arguments !== undefined ? { arguments: config.arguments } : {}),
+      handler,
+    }
+  },
+}
+
+/** The install seam a server exposes so the `mcp()` plugin can hand it the runtime. */
+interface McpInstallable {
+  [INSTALL_MCP](runtime: McpRuntime): void
+}
+
+/**
+ * Enable MCP declarations on a server: `.use(mcp())` turns on `.tool()`, `.resource()`, and
+ * `.prompt()`. Applying it twice is a no-op (named plugin dedupe).
+ */
+export function mcp(): IdentityPlugin {
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as McpInstallable)[INSTALL_MCP](MCP_RUNTIME)
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:mcp" }) as IdentityPlugin
+}

package/src/node-direct.ts

@@ -0,0 +1,37 @@
+/**
+ * The opt-in Node-direct renderer plugin.
+ *
+ * `.use(nodeDirect())` enables `app.resolveNode()` for callers that invoke it themselves. Normal
+ * `@nifrajs/node` serving supplies the renderer directly, so it never needs this; only direct
+ * `resolveNode()` callers do. Same `.use()` install seam as `mcp()` / `idempotency()`.
+ */
+import { INSTALL_NODE_DIRECT } from "./server/install.ts"
+import { nodeOutcomeFromResponse, toNodeOutcome } from "./server/node-outcome.ts"
+import type { NodeOutcomeRuntime } from "./server/node-outcome-hook.ts"
+import type { IdentityPlugin } from "./server/plugin.ts"
+import type { AnyServer } from "./server/server.ts"
+
+const NODE_OUTCOME_RUNTIME: NodeOutcomeRuntime = {
+  toOutcome: toNodeOutcome,
+  fromResponse: nodeOutcomeFromResponse,
+  timeout: () => ({
+    kind: "response",
+    response: Response.json({ ok: false, error: "request_timeout" }, { status: 503 }),
+  }),
+}
+
+/** The install seam a server exposes so the `nodeDirect()` plugin can hand it the renderer. */
+interface NodeDirectInstallable {
+  [INSTALL_NODE_DIRECT](runtime: NodeOutcomeRuntime): void
+}
+
+/** Enable `app.resolveNode()` for direct callers. Applying it twice is a no-op (named plugin dedupe). */
+export function nodeDirect(): IdentityPlugin {
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as NodeDirectInstallable)[INSTALL_NODE_DIRECT](NODE_OUTCOME_RUNTIME)
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:node-direct" }) as IdentityPlugin
+}
+
+export type { NodeServeOutcome } from "./server/node-outcome.ts"

package/src/reconciliation-worker.ts

@@ -0,0 +1,372 @@
+/** Leased, cursor-checkpointed, bounded reconciliation worker orchestration. */
+import {
+  type DurableEffectStore,
+  type EffectReconciliationFinding,
+  reconcileEffectsPage,
+  reconcileSagasPage,
+  type SagaReconciliationFinding,
+  type SagaStore,
+} from "./durable-execution.ts"
+import { safeEqual } from "./internal/safe-equal.ts"
+
+const TOKEN = /^[!-~]{1,128}$/
+
+export interface ReconciliationLease {
+  readonly name: string
+  readonly owner: string
+  readonly token: string
+  readonly expiresAt: number
+  readonly cursor?: string
+}
+
+export interface ReconciliationLeaseStore {
+  readonly durability?: "memory" | "durable"
+  acquire(input: {
+    readonly name: string
+    readonly owner: string
+    readonly now: number
+    readonly leaseMs: number
+  }): ReconciliationLease | undefined | Promise<ReconciliationLease | undefined>
+  renew(input: {
+    readonly name: string
+    readonly owner: string
+    readonly token: string
+    readonly now: number
+    readonly leaseMs: number
+  }): boolean | Promise<boolean>
+  checkpoint(input: {
+    readonly name: string
+    readonly owner: string
+    readonly token: string
+    readonly cursor?: string
+  }): boolean | Promise<boolean>
+  release(input: {
+    readonly name: string
+    readonly owner: string
+    readonly token: string
+  }): boolean | Promise<boolean>
+}
+
+export type ReconciliationWorkerEvent =
+  | { readonly type: "acquired" | "released" | "lease-lost"; readonly name: string }
+  | {
+      readonly type: "page" | "checkpoint"
+      readonly name: string
+      readonly scanned: number
+      readonly handled: number
+    }
+  | { readonly type: "failed"; readonly name: string; readonly errorCode: "scan" | "handle" }
+
+export interface ReconciliationWorkerOptions<Finding> {
+  readonly name: string
+  readonly owner: string
+  readonly leases: ReconciliationLeaseStore
+  readonly leaseMs?: number
+  readonly batchSize?: number
+  readonly maxPages?: number
+  readonly concurrency?: number
+  readonly signal?: AbortSignal
+  readonly now?: () => number
+  readonly scan: (input: {
+    readonly cursor?: string
+    readonly limit: number
+    readonly signal: AbortSignal
+  }) =>
+    | { readonly findings: readonly Finding[]; readonly cursor?: string }
+    | Promise<{
+        readonly findings: readonly Finding[]
+        readonly cursor?: string
+      }>
+  readonly filter?: (finding: Finding) => boolean
+  readonly handle: (finding: Finding, signal: AbortSignal) => void | PromiseLike<void>
+  readonly observe?: (event: ReconciliationWorkerEvent) => void
+}
+
+export interface ReconciliationWorkerResult {
+  readonly acquired: boolean
+  readonly pages: number
+  readonly scanned: number
+  readonly handled: number
+}
+
+function positive(value: number, label: string, max: number): number {
+  if (!Number.isSafeInteger(value) || value < 1 || value > max)
+    throw new RangeError(`${label} must be an integer between 1 and ${max}`)
+  return value
+}
+
+function timestamp(value: number): number {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new RangeError("reconciliation clock must return a non-negative safe integer")
+  return value
+}
+
+function assertToken(value: string, label: string): void {
+  if (!TOKEN.test(value)) throw new TypeError(`${label} must be a bounded printable token`)
+}
+
+function throwIfAborted(signal: AbortSignal): void {
+  if (signal.aborted)
+    throw signal.reason instanceof Error ? signal.reason : new Error("reconciliation aborted")
+}
+
+async function boundedMap<T>(
+  values: readonly T[],
+  concurrency: number,
+  run: (value: T) => Promise<void>,
+): Promise<void> {
+  let next = 0
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const index = next++
+      if (index >= values.length) return
+      await run(values[index] as T)
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, () => worker()))
+}
+
+export async function runReconciliationWorker<Finding>(
+  options: ReconciliationWorkerOptions<Finding>,
+): Promise<ReconciliationWorkerResult> {
+  assertToken(options.name, "reconciliation worker name")
+  assertToken(options.owner, "reconciliation worker owner")
+  const leaseMs = positive(options.leaseMs ?? 30_000, "reconciliation leaseMs", 86_400_000)
+  const batchSize = positive(options.batchSize ?? 100, "reconciliation batchSize", 1_000)
+  const maxPages = positive(options.maxPages ?? 10, "reconciliation maxPages", 1_000)
+  const concurrency = positive(options.concurrency ?? 4, "reconciliation concurrency", 64)
+  const now = options.now ?? Date.now
+  const signal = options.signal ?? new AbortController().signal
+  throwIfAborted(signal)
+  const lease = await options.leases.acquire({
+    name: options.name,
+    owner: options.owner,
+    now: timestamp(now()),
+    leaseMs,
+  })
+  if (lease === undefined) return { acquired: false, pages: 0, scanned: 0, handled: 0 }
+  if (
+    lease.name !== options.name ||
+    lease.owner !== options.owner ||
+    !TOKEN.test(lease.token) ||
+    !Number.isSafeInteger(lease.expiresAt) ||
+    lease.expiresAt <= 0 ||
+    (lease.cursor !== undefined && !/^[ -~]{1,1024}$/u.test(lease.cursor))
+  ) {
+    throw new TypeError("reconciliation lease store returned an invalid lease")
+  }
+  options.observe?.({ type: "acquired", name: options.name })
+  let cursor = lease.cursor
+  let pages = 0
+  let scanned = 0
+  let handled = 0
+  try {
+    while (pages < maxPages) {
+      throwIfAborted(signal)
+      const renewed = await options.leases.renew({
+        name: options.name,
+        owner: options.owner,
+        token: lease.token,
+        now: timestamp(now()),
+        leaseMs,
+      })
+      if (!renewed) {
+        options.observe?.({ type: "lease-lost", name: options.name })
+        throw new Error("reconciliation lease lost")
+      }
+      let page: Awaited<ReturnType<typeof options.scan>>
+      try {
+        page = await options.scan({
+          ...(cursor === undefined ? {} : { cursor }),
+          limit: batchSize,
+          signal,
+        })
+      } catch (error) {
+        options.observe?.({ type: "failed", name: options.name, errorCode: "scan" })
+        throw error
+      }
+      if (!Array.isArray(page.findings) || page.findings.length > batchSize)
+        throw new TypeError("reconciliation scan returned an invalid or oversized page")
+      pages++
+      scanned += page.findings.length
+      const selected =
+        options.filter === undefined ? page.findings : page.findings.filter(options.filter)
+      try {
+        await boundedMap(selected, concurrency, async (finding) => {
+          throwIfAborted(signal)
+          await options.handle(finding, signal)
+          handled++
+        })
+      } catch (error) {
+        options.observe?.({ type: "failed", name: options.name, errorCode: "handle" })
+        throw error
+      }
+      const renewedAfterWork = await options.leases.renew({
+        name: options.name,
+        owner: options.owner,
+        token: lease.token,
+        now: timestamp(now()),
+        leaseMs,
+      })
+      if (!renewedAfterWork) {
+        options.observe?.({ type: "lease-lost", name: options.name })
+        throw new Error("reconciliation lease expired during page handling")
+      }
+      options.observe?.({
+        type: "page",
+        name: options.name,
+        scanned: page.findings.length,
+        handled: selected.length,
+      })
+      const checkpointed = await options.leases.checkpoint({
+        name: options.name,
+        owner: options.owner,
+        token: lease.token,
+        ...(page.cursor === undefined ? {} : { cursor: page.cursor }),
+      })
+      if (!checkpointed) {
+        options.observe?.({ type: "lease-lost", name: options.name })
+        throw new Error("reconciliation lease lost before checkpoint")
+      }
+      options.observe?.({
+        type: "checkpoint",
+        name: options.name,
+        scanned,
+        handled,
+      })
+      cursor = page.cursor
+      if (cursor === undefined) break
+    }
+    return { acquired: true, pages, scanned, handled }
+  } finally {
+    if (
+      await options.leases.release({
+        name: options.name,
+        owner: options.owner,
+        token: lease.token,
+      })
+    ) {
+      options.observe?.({ type: "released", name: options.name })
+    }
+  }
+}
+
+interface MemoryLeaseRecord {
+  owner?: string
+  token?: string
+  expiresAt?: number
+  cursor?: string
+}
+
+export class MemoryReconciliationLeaseStore implements ReconciliationLeaseStore {
+  readonly durability = "memory" as const
+  private readonly records = new Map<string, MemoryLeaseRecord>()
+
+  acquire(
+    input: Parameters<ReconciliationLeaseStore["acquire"]>[0],
+  ): ReconciliationLease | undefined {
+    assertToken(input.name, "reconciliation lease name")
+    assertToken(input.owner, "reconciliation lease owner")
+    const current = this.records.get(input.name)
+    if (
+      current?.owner !== undefined &&
+      current.expiresAt !== undefined &&
+      current.expiresAt > input.now
+    ) {
+      return undefined
+    }
+    const token = crypto.randomUUID()
+    const expiresAt = input.now + input.leaseMs
+    if (!Number.isSafeInteger(expiresAt)) throw new RangeError("reconciliation lease overflow")
+    this.records.set(input.name, {
+      owner: input.owner,
+      token,
+      expiresAt,
+      ...(current?.cursor === undefined ? {} : { cursor: current.cursor }),
+    })
+    return Object.freeze({
+      name: input.name,
+      owner: input.owner,
+      token,
+      expiresAt,
+      ...(current?.cursor === undefined ? {} : { cursor: current.cursor }),
+    })
+  }
+
+  renew(input: Parameters<ReconciliationLeaseStore["renew"]>[0]): boolean {
+    const record = this.records.get(input.name)
+    if (
+      record?.owner !== input.owner ||
+      !safeEqual(record.token, input.token) ||
+      (record.expiresAt ?? 0) <= input.now
+    )
+      return false
+    const expiresAt = input.now + input.leaseMs
+    if (!Number.isSafeInteger(expiresAt)) throw new RangeError("reconciliation lease overflow")
+    record.expiresAt = expiresAt
+    return true
+  }
+
+  checkpoint(input: Parameters<ReconciliationLeaseStore["checkpoint"]>[0]): boolean {
+    const record = this.records.get(input.name)
+    if (record?.owner !== input.owner || !safeEqual(record.token, input.token)) return false
+    if (input.cursor === undefined) delete record.cursor
+    else record.cursor = input.cursor
+    return true
+  }
+
+  release(input: Parameters<ReconciliationLeaseStore["release"]>[0]): boolean {
+    const record = this.records.get(input.name)
+    if (record?.owner !== input.owner || !safeEqual(record.token, input.token)) return false
+    delete record.owner
+    delete record.token
+    delete record.expiresAt
+    return true
+  }
+}
+
+interface SpecializedWorkerOptions<Finding> {
+  readonly name: string
+  readonly owner: string
+  readonly leases: ReconciliationLeaseStore
+  readonly staleBefore: number
+  readonly leaseMs?: number
+  readonly batchSize?: number
+  readonly maxPages?: number
+  readonly concurrency?: number
+  readonly signal?: AbortSignal
+  readonly now?: () => number
+  readonly filter?: (finding: Finding) => boolean
+  readonly handle: (finding: Finding, signal: AbortSignal) => void | PromiseLike<void>
+  readonly observe?: (event: ReconciliationWorkerEvent) => void
+}
+
+export function runEffectReconciliationWorker(
+  store: DurableEffectStore,
+  options: SpecializedWorkerOptions<EffectReconciliationFinding>,
+): Promise<ReconciliationWorkerResult> {
+  return runReconciliationWorker({
+    ...options,
+    scan: ({ cursor, limit }) =>
+      reconcileEffectsPage(store, {
+        staleBefore: options.staleBefore,
+        ...(cursor === undefined ? {} : { cursor }),
+        limit,
+      }),
+  })
+}
+
+export function runSagaReconciliationWorker(
+  store: SagaStore,
+  options: SpecializedWorkerOptions<SagaReconciliationFinding>,
+): Promise<ReconciliationWorkerResult> {
+  return runReconciliationWorker({
+    ...options,
+    scan: ({ cursor, limit }) =>
+      reconcileSagasPage(store, {
+        staleBefore: options.staleBefore,
+        ...(cursor === undefined ? {} : { cursor }),
+        limit,
+      }),
+  })
+}