@nifrajs/core 2.0.0 → 2.2.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/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,
+      }),
+  })
+}