@nifrajs/coding-agent 3.2.0

package/src/orchestration/durable-jobs.ts

@@ -0,0 +1,374 @@
+/**
+ * Adapter from the dependency-free jobs lease contract to run-node dispatch.
+ *
+ * The supplied JobStore should be dedicated to this adapter (JobStore has no claim-by-name
+ * operation). Its persisted payload is the parsed, content-free RunDispatch identity. The adapter
+ * adds lease generations and rejects stale completions in-process; a durable operated implementation
+ * must enforce the same compare-and-commit rule in its data layer.
+ */
+
+import type { JobStore, StoredJob } from "@nifrajs/jobs"
+import { MemoryJobStore } from "@nifrajs/jobs"
+import {
+  DISPATCH_JOB_NAME,
+  type DispatchInspection,
+  type DispatchResultCode,
+  type DispatchState,
+  type DispatchWriteResult,
+  deriveRunIdempotencyKey,
+  parseRunCheckpoint,
+  parseRunDispatch,
+  parseRunDispatchEvidence,
+  parseRunLease,
+  RUN_DISPATCH_VERSION,
+  type RunCheckpoint,
+  type RunDispatch,
+  type RunDispatchEvidence,
+  type RunDispatchStore,
+  type RunLease,
+} from "./dispatch.ts"
+
+export interface DurableJobsStoreOptions {
+  /** A dedicated at-least-once JobStore. Defaults to disposable in-memory storage. */
+  readonly store?: JobStore
+  /** Injected time source used for lease and cancellation decisions. */
+  readonly now?: () => number
+}
+
+interface Entry {
+  readonly dispatch: RunDispatch
+  readonly jobId: string
+  state: DispatchState
+  attempt: number
+  generation: number
+  leaseId: string | undefined
+  leaseUntil: number
+  lease: RunLease | undefined
+  checkpoint: RunCheckpoint | undefined
+  readonly evidence: RunDispatchEvidence[]
+}
+
+function code(value: string): string {
+  if (!/^[A-Za-z0-9_.:-]{1,256}$/.test(value))
+    throw new TypeError("dispatch code must be a stable token")
+  return value
+}
+
+function result(codeValue: DispatchResultCode): DispatchWriteResult {
+  return { ok: codeValue === "accepted", code: codeValue }
+}
+
+function leaseMatches(entry: Entry | undefined, lease: RunLease): entry is Entry {
+  return (
+    entry !== undefined &&
+    entry.leaseId === lease.leaseId &&
+    entry.generation === lease.generation &&
+    entry.attempt === lease.attempt &&
+    entry.dispatch.dispatchId === lease.dispatch.dispatchId &&
+    entry.dispatch.planDigest === lease.dispatch.planDigest &&
+    entry.dispatch.nodeId === lease.dispatch.nodeId &&
+    entry.lease?.idempotencyKey === lease.idempotencyKey
+  )
+}
+
+function isTerminal(state: DispatchState): boolean {
+  return (
+    state === "succeeded" ||
+    state === "failed" ||
+    state === "cancelled" ||
+    state === "dead-lettered"
+  )
+}
+
+function evidenceFor(
+  entry: Entry,
+  state: DispatchState,
+  at: number,
+  scheduleToken: string,
+  idempotencyKey: string,
+  codeValue?: string,
+): RunDispatchEvidence {
+  return parseRunDispatchEvidence({
+    version: RUN_DISPATCH_VERSION,
+    dispatchId: entry.dispatch.dispatchId,
+    runId: entry.dispatch.runId,
+    nodeId: entry.dispatch.nodeId,
+    state,
+    attempt: entry.attempt,
+    generation: entry.generation,
+    at,
+    scheduleToken,
+    idempotencyKey,
+    ...(codeValue === undefined ? {} : { code: code(codeValue) }),
+  })
+}
+
+function appendEvidence(entry: Entry, item: RunDispatchEvidence): void {
+  entry.evidence.push(parseRunDispatchEvidence(item))
+}
+
+function dispatchFromJob(job: StoredJob): RunDispatch {
+  if (job.name !== DISPATCH_JOB_NAME) throw new TypeError("jobs adapter received an unrelated job")
+  return parseRunDispatch(job.payload)
+}
+
+/**
+ * Create an at-least-once run dispatch store over an existing JobStore.
+ *
+ * JobStore's `attempt` increments only when a caller explicitly retries; an expired lease is
+ * redelivered at the same logical attempt, which is what makes the idempotency key stable across a
+ * duplicate delivery. A retry intentionally advances the logical attempt and gets a new key.
+ */
+export function createDurableJobsStore(options: DurableJobsStoreOptions = {}): RunDispatchStore & {
+  readonly jobs: JobStore
+  deadLetters(): readonly RunDispatchEvidence[]
+} {
+  const jobs = options.store ?? new MemoryJobStore()
+  const now = options.now ?? (() => Date.now())
+  const byJobId = new Map<string, Entry>()
+  const byDispatchId = new Map<string, Entry>()
+  let generation = 0
+  const dead: RunDispatchEvidence[] = []
+
+  async function enqueue(source: RunDispatch): Promise<void> {
+    const dispatch = parseRunDispatch(source)
+    if (byDispatchId.has(dispatch.dispatchId)) throw new Error("duplicate dispatch id")
+    const jobId = await jobs.enqueue({
+      name: DISPATCH_JOB_NAME,
+      payload: dispatch,
+      runAt: dispatch.notBefore,
+      maxAttempts: dispatch.maxAttempts,
+    })
+    const entry: Entry = {
+      dispatch,
+      jobId,
+      state: "queued",
+      attempt: 1,
+      generation: 0,
+      leaseId: undefined,
+      leaseUntil: 0,
+      lease: undefined,
+      checkpoint: undefined,
+      evidence: [],
+    }
+    byJobId.set(jobId, entry)
+    byDispatchId.set(dispatch.dispatchId, entry)
+  }
+
+  async function lease(at: number, limit: number, leaseMs: number): Promise<RunLease[]> {
+    if (!Number.isSafeInteger(at) || at < 0) throw new RangeError("dispatch lease time is invalid")
+    if (!Number.isSafeInteger(limit) || limit < 1)
+      throw new RangeError("dispatch lease limit is invalid")
+    if (!Number.isFinite(leaseMs) || leaseMs <= 0)
+      throw new RangeError("dispatch lease duration is invalid")
+    const jobsLeased = await jobs.lease(at, limit, leaseMs)
+    const resultLeases: RunLease[] = []
+    for (const job of jobsLeased) {
+      const dispatch = dispatchFromJob(job)
+      const entry = byJobId.get(job.id) ?? byDispatchId.get(dispatch.dispatchId)
+      if (entry === undefined) throw new Error("jobs adapter lost dispatch identity")
+      if (isTerminal(entry.state)) continue
+      entry.state = "leased"
+      entry.attempt = job.attempt + 1
+      entry.generation = ++generation
+      entry.leaseUntil = at + leaseMs
+      entry.leaseId = `${job.id}:${entry.generation}`
+      const idempotencyKey = await deriveRunIdempotencyKey(
+        dispatch.planDigest,
+        dispatch.runId,
+        dispatch.nodeId,
+        entry.attempt,
+      )
+      const value = parseRunLease({
+        version: RUN_DISPATCH_VERSION,
+        leaseId: entry.leaseId,
+        dispatch,
+        attempt: entry.attempt,
+        generation: entry.generation,
+        leasedAt: at,
+        leaseUntil: entry.leaseUntil,
+        scheduleToken: `${job.id}:${entry.generation}`,
+        idempotencyKey,
+      })
+      entry.lease = value
+      appendEvidence(
+        entry,
+        evidenceFor(entry, "leased", at, value.scheduleToken, value.idempotencyKey),
+      )
+      resultLeases.push(value)
+    }
+    return resultLeases
+  }
+
+  function current(lease: RunLease): Entry | undefined {
+    return byDispatchId.get(lease.dispatch.dispatchId)
+  }
+
+  async function checkpoint(lease: RunLease, source: RunCheckpoint): Promise<DispatchWriteResult> {
+    const value = parseRunCheckpoint(source)
+    const entry = current(lease)
+    if (!leaseMatches(entry, lease)) return result("stale_lease")
+    if (entry.state === "cancelled") return result("cancelled")
+    if (isTerminal(entry.state)) return result("terminal")
+    if (now() >= entry.leaseUntil) return result("stale_lease")
+    if (
+      value.dispatchId !== lease.dispatch.dispatchId ||
+      value.runId !== lease.dispatch.runId ||
+      value.nodeId !== lease.dispatch.nodeId ||
+      value.attempt !== lease.attempt ||
+      value.generation !== lease.generation ||
+      value.idempotencyKey !== lease.idempotencyKey
+    )
+      return result("invalid_checkpoint")
+    entry.checkpoint = value
+    entry.state = "checkpointed"
+    appendEvidence(
+      entry,
+      evidenceFor(entry, "checkpointed", value.at, value.scheduleToken, value.idempotencyKey),
+    )
+    return result("accepted")
+  }
+
+  async function complete(
+    lease: RunLease,
+    source?: RunDispatchEvidence,
+  ): Promise<DispatchWriteResult> {
+    const entry = current(lease)
+    if (!leaseMatches(entry, lease)) return result("stale_lease")
+    if (entry.state === "cancelled") return result("cancelled")
+    if (isTerminal(entry.state)) return result("terminal")
+    if (now() >= entry.leaseUntil) return result("stale_lease")
+    if (source !== undefined) {
+      const evidence = parseRunDispatchEvidence(source)
+      if (
+        evidence.dispatchId !== lease.dispatch.dispatchId ||
+        evidence.attempt !== lease.attempt ||
+        evidence.generation !== lease.generation ||
+        evidence.idempotencyKey !== lease.idempotencyKey
+      )
+        return result("invalid_checkpoint")
+    }
+    await jobs.complete(entry.jobId)
+    entry.state = "succeeded"
+    appendEvidence(
+      entry,
+      source ?? evidenceFor(entry, "succeeded", now(), lease.scheduleToken, lease.idempotencyKey),
+    )
+    entry.lease = undefined
+    return result("accepted")
+  }
+
+  async function retry(
+    lease: RunLease,
+    runAt: number,
+    failureCode: string,
+  ): Promise<DispatchWriteResult> {
+    const entry = current(lease)
+    if (!leaseMatches(entry, lease)) return result("stale_lease")
+    if (entry.state === "cancelled") return result("cancelled")
+    if (isTerminal(entry.state)) return result("terminal")
+    if (now() >= entry.leaseUntil) return result("stale_lease")
+    if (!Number.isSafeInteger(runAt) || runAt < 0)
+      throw new RangeError("dispatch retry time is invalid")
+    await jobs.retry(entry.jobId, runAt)
+    entry.state = "retrying"
+    entry.checkpoint = undefined
+    appendEvidence(
+      entry,
+      evidenceFor(entry, "retrying", now(), lease.scheduleToken, lease.idempotencyKey, failureCode),
+    )
+    entry.lease = undefined
+    return result("accepted")
+  }
+
+  async function deadLetter(lease: RunLease, failureCode: string): Promise<DispatchWriteResult> {
+    const entry = current(lease)
+    if (!leaseMatches(entry, lease)) return result("stale_lease")
+    if (entry.state === "cancelled") return result("cancelled")
+    if (isTerminal(entry.state)) return result("terminal")
+    if (now() >= entry.leaseUntil) return result("stale_lease")
+    const stableCode = code(failureCode)
+    await jobs.deadLetter(entry.jobId, stableCode)
+    entry.state = "dead-lettered"
+    const evidence = evidenceFor(
+      entry,
+      "dead-lettered",
+      now(),
+      lease.scheduleToken,
+      lease.idempotencyKey,
+      stableCode,
+    )
+    appendEvidence(entry, evidence)
+    dead.push(evidence)
+    entry.lease = undefined
+    return result("accepted")
+  }
+
+  async function cancel(runId: string, cancellationCode = "cancelled"): Promise<number> {
+    const stableCode = code(cancellationCode)
+    let changed = 0
+    for (const entry of byDispatchId.values()) {
+      if (entry.dispatch.runId !== runId || isTerminal(entry.state)) continue
+      entry.state = "cancelled"
+      changed++
+      const lease = entry.lease
+      appendEvidence(
+        entry,
+        evidenceFor(
+          entry,
+          "cancelled",
+          now(),
+          lease?.scheduleToken ?? `${entry.jobId}:cancel`,
+          lease?.idempotencyKey ??
+            (await deriveRunIdempotencyKey(
+              entry.dispatch.planDigest,
+              entry.dispatch.runId,
+              entry.dispatch.nodeId,
+              entry.attempt,
+            )),
+          stableCode,
+        ),
+      )
+      if (lease !== undefined) await jobs.deadLetter(entry.jobId, stableCode)
+      else await jobs.deadLetter(entry.jobId, stableCode)
+      entry.lease = undefined
+    }
+    return changed
+  }
+
+  function inspect(dispatchId: string): DispatchInspection | undefined {
+    const entry = byDispatchId.get(dispatchId)
+    if (entry === undefined) return undefined
+    return Object.freeze({
+      dispatch: entry.dispatch,
+      state: entry.state,
+      attempt: entry.attempt,
+      generation: entry.generation,
+      ...(entry.checkpoint === undefined ? {} : { checkpoint: entry.checkpoint }),
+      evidence: Object.freeze([...entry.evidence]),
+    })
+  }
+
+  return {
+    jobs,
+    enqueue,
+    lease,
+    checkpoint,
+    complete,
+    retry,
+    deadLetter,
+    cancel,
+    inspect,
+    deadLetters: () => Object.freeze([...dead]),
+  }
+}
+
+/** Disposable local reference adapter; it makes no durability or exactly-once guarantee. */
+export function createMemoryRunDispatchStore(
+  options: { readonly now?: () => number } = {},
+): RunDispatchStore & {
+  readonly jobs: JobStore
+  deadLetters(): readonly RunDispatchEvidence[]
+} {
+  return createDurableJobsStore({ store: new MemoryJobStore(), ...options })
+}

package/src/orchestration/effect-key.ts

@@ -0,0 +1,35 @@
+/**
+ * Content-free idempotency identity for one side-effecting node attempt-boundary.
+ *
+ * The step author projects only the identity-bearing subset of its input into a byte `selector`
+ * (via `CatalogStep.selectEffect`). {@link deriveNodeEffectKey} frames that selector with the
+ * non-secret plan/node coordinates and hashes the whole to a digest. The digest is what crosses a
+ * boundary or lands in evidence; the selector bytes never leave this function. This mirrors
+ * `@nifrajs/core`'s `computeIdempotencyFingerprint`: the hash is the key, the material is consumed.
+ */
+
+import type { NodeEffectKey } from "@nifrajs/agent-protocol"
+import { sha256Hex } from "./hash.ts"
+
+const encoder = new TextEncoder()
+
+/** Inputs to the effect-key derivation. `selector` is the step's content-free identity projection. */
+export interface EffectKeyMaterial {
+  readonly planDigest: string
+  readonly nodeId: string
+  /** Identity-bearing bytes chosen by the step. Consumed into the hash, never retained. */
+  readonly selector: Uint8Array
+}
+
+/**
+ * Derive the stable, content-free key for a node attempt. The returned digest is safe to log and to
+ * cross a boundary; two attempts with the same identity converge, distinct identities diverge.
+ */
+export async function deriveNodeEffectKey(material: EffectKeyMaterial): Promise<NodeEffectKey> {
+  const header = encoder.encode(`${material.planDigest}\n${material.nodeId}\n`)
+  const framed = new Uint8Array(header.length + material.selector.length)
+  framed.set(header, 0)
+  framed.set(material.selector, header.length)
+  const digest = await sha256Hex(framed)
+  return { digest, planDigest: material.planDigest, nodeId: material.nodeId }
+}

package/src/orchestration/evidence-store.ts

@@ -0,0 +1,233 @@
+/**
+ * Evidence-only run stores. A store keeps a bounded live window of the most recent
+ * {@link RunEvidence} records, a set of order-independent aggregates (completed node ids, artifact
+ * refs, counters), and an order-independent terminal digest - never the whole stream, so a 100k-event
+ * run stays bounded in memory. Every record is re-parsed through {@link parseRunEvidence} on the way
+ * in, so a payload-bearing or oversized record cannot be written through either store: the parser is
+ * the privacy gate, not the caller's discipline.
+ *
+ * There is no dependency on `FileSessionStore` or any session machinery: these stores hold run
+ * evidence only, and the file store persists exactly the content-free record it parsed.
+ */
+
+import { appendFile } from "node:fs/promises"
+import type { ArtifactRef, RunEvidence } from "@nifrajs/agent-protocol"
+import { assertEvidenceSize, parseRunEvidence } from "@nifrajs/agent-protocol"
+import { canonicalJson } from "./hash.ts"
+
+/** Terminal tally of a run's evidence stream. Counts only; no payloads. */
+export interface EvidenceCounters {
+  readonly total: number
+  readonly started: number
+  readonly completed: number
+  readonly failed: number
+}
+
+/** A bounded, evidence-only run store. Append is fail-closed; reads are content-free aggregates. */
+export interface EvidenceStore {
+  /** Parse, tally, and persist one record. Throws on a payload-bearing or oversized record. */
+  append(record: RunEvidence): Promise<void>
+  /** Total records appended (not the live-window size). */
+  readonly count: number
+  /** The most recent records, oldest first, capped at the configured window. */
+  live(): readonly RunEvidence[]
+  counters(): EvidenceCounters
+  /** Distinct node ids that reached `completed`, sorted for determinism. */
+  completedNodeIds(): readonly string[]
+  /** Every artifact ref referenced by the stream, in append order. */
+  artifacts(): readonly ArtifactRef[]
+  /** Order-independent SHA-256 of the run's outcome multiset (parallel order cannot change it). */
+  digest(): Promise<string>
+}
+
+const DEFAULT_MAX_LIVE = 1024
+const encoder = new TextEncoder()
+
+async function sha256Bytes(text: string): Promise<Uint8Array> {
+  const digest = await crypto.subtle.digest("SHA-256", encoder.encode(text))
+  return new Uint8Array(digest)
+}
+
+/**
+ * The identity of one record for the terminal digest: node outcome only. `seq`, `durationMs`, and
+ * `runId` are excluded so two runs of the same plan (or the same plan under a different parallel
+ * schedule) produce an identical digest - the deterministic-eval anchor. Each node emits at most one
+ * record per status, so XOR accumulation never cancels a distinct outcome.
+ */
+function digestKey(record: RunEvidence): string {
+  return canonicalJson({
+    planDigest: record.planDigest,
+    nodeId: record.nodeId,
+    status: record.status,
+    idempotent: record.idempotent,
+    ...(record.errorCode !== undefined ? { errorCode: record.errorCode } : {}),
+    ...(record.effectKey !== undefined ? { effectKey: record.effectKey } : {}),
+    ...(record.artifacts !== undefined ? { artifacts: record.artifacts } : {}),
+  })
+}
+
+/** Shared accumulator: bounded ring window plus order-independent aggregates. No payload retained. */
+class EvidenceAccumulator {
+  private readonly max: number
+  private readonly buf: RunEvidence[] = []
+  private head = 0
+  private filled = false
+  private readonly acc = new Uint8Array(32)
+  private readonly completed = new Set<string>()
+  private readonly artifactRefs: ArtifactRef[] = []
+  private totalCount = 0
+  private startedCount = 0
+  private completedCount = 0
+  private failedCount = 0
+
+  constructor(maxLive: number) {
+    if (!Number.isSafeInteger(maxLive) || maxLive < 0)
+      throw new RangeError("evidence store: maxLive must be a non-negative integer")
+    this.max = maxLive
+  }
+
+  /** `record` is already parsed and within the size cap. */
+  async add(record: RunEvidence): Promise<void> {
+    this.totalCount++
+    if (record.status === "started") this.startedCount++
+    else if (record.status === "completed") {
+      this.completedCount++
+      this.completed.add(record.nodeId)
+    } else this.failedCount++
+    if (record.artifacts !== undefined)
+      for (const ref of record.artifacts) this.artifactRefs.push(ref)
+    const hash = await sha256Bytes(digestKey(record))
+    for (let i = 0; i < 32; i++) this.acc[i] = (this.acc[i] as number) ^ (hash[i] as number)
+    this.pushLive(record)
+  }
+
+  private pushLive(record: RunEvidence): void {
+    if (this.max === 0) return
+    this.buf[this.head] = record
+    this.head = (this.head + 1) % this.max
+    if (this.head === 0) this.filled = true
+  }
+
+  get count(): number {
+    return this.totalCount
+  }
+
+  live(): readonly RunEvidence[] {
+    if (!this.filled) return this.buf.slice(0, this.head)
+    return [...this.buf.slice(this.head), ...this.buf.slice(0, this.head)]
+  }
+
+  counters(): EvidenceCounters {
+    return {
+      total: this.totalCount,
+      started: this.startedCount,
+      completed: this.completedCount,
+      failed: this.failedCount,
+    }
+  }
+
+  completedNodeIds(): readonly string[] {
+    return [...this.completed].sort()
+  }
+
+  artifacts(): readonly ArtifactRef[] {
+    return [...this.artifactRefs]
+  }
+
+  digest(): string {
+    let hex = ""
+    for (let i = 0; i < 32; i++) hex += (this.acc[i] as number).toString(16).padStart(2, "0")
+    return hex
+  }
+}
+
+/** Normalize on the way in: re-parse (content-free gate) then re-check the size cap. */
+function normalize(record: RunEvidence): RunEvidence {
+  const parsed = parseRunEvidence(record)
+  assertEvidenceSize(parsed)
+  return parsed
+}
+
+export interface MemoryEvidenceStoreOptions {
+  /** Records retained in the live window. Older records fall out; aggregates still count them. */
+  readonly maxLive?: number
+}
+
+/** A fully in-memory bounded store. Keeps a window plus aggregates; never the whole stream. */
+export class MemoryEvidenceStore implements EvidenceStore {
+  private readonly accumulator: EvidenceAccumulator
+
+  constructor(options: MemoryEvidenceStoreOptions = {}) {
+    this.accumulator = new EvidenceAccumulator(options.maxLive ?? DEFAULT_MAX_LIVE)
+  }
+
+  async append(record: RunEvidence): Promise<void> {
+    await this.accumulator.add(normalize(record))
+  }
+
+  get count(): number {
+    return this.accumulator.count
+  }
+  live(): readonly RunEvidence[] {
+    return this.accumulator.live()
+  }
+  counters(): EvidenceCounters {
+    return this.accumulator.counters()
+  }
+  completedNodeIds(): readonly string[] {
+    return this.accumulator.completedNodeIds()
+  }
+  artifacts(): readonly ArtifactRef[] {
+    return this.accumulator.artifacts()
+  }
+  async digest(): Promise<string> {
+    return this.accumulator.digest()
+  }
+}
+
+export interface FileEvidenceStoreOptions {
+  /** Append-only newline-delimited file. One canonical JSON record per line, in append order. */
+  readonly path: string
+  readonly maxLive?: number
+}
+
+/**
+ * A bounded store that also appends each parsed record as one canonical-JSON line to a file, in
+ * deterministic append order. The record is normalized (and so a forbidden-content record is
+ * rejected) BEFORE the line is written, so the file never receives a payload. The append uses the
+ * `a` flag, so each record is one O_APPEND write.
+ */
+export class FileEvidenceStore implements EvidenceStore {
+  private readonly accumulator: EvidenceAccumulator
+  private readonly path: string
+
+  constructor(options: FileEvidenceStoreOptions) {
+    this.path = options.path
+    this.accumulator = new EvidenceAccumulator(options.maxLive ?? DEFAULT_MAX_LIVE)
+  }
+
+  async append(record: RunEvidence): Promise<void> {
+    const parsed = normalize(record)
+    await this.accumulator.add(parsed)
+    await appendFile(this.path, `${canonicalJson(parsed)}\n`, { flag: "a" })
+  }
+
+  get count(): number {
+    return this.accumulator.count
+  }
+  live(): readonly RunEvidence[] {
+    return this.accumulator.live()
+  }
+  counters(): EvidenceCounters {
+    return this.accumulator.counters()
+  }
+  completedNodeIds(): readonly string[] {
+    return this.accumulator.completedNodeIds()
+  }
+  artifacts(): readonly ArtifactRef[] {
+    return this.accumulator.artifacts()
+  }
+  async digest(): Promise<string> {
+    return this.accumulator.digest()
+  }
+}

package/src/orchestration/hash.ts

@@ -0,0 +1,43 @@
+/**
+ * Content-addressing helpers shared by the orchestration module: a SHA-256 hex digest over bytes
+ * and a canonical JSON encoding with sorted object keys so a digest is stable across key order.
+ * Mirrors `@nifrajs/core`'s idempotency fingerprint (the content-free key precedent).
+ */
+
+const encoder = new TextEncoder()
+
+/** SHA-256 of `bytes` as lowercase hex. Collision-resistant so a digest cannot be forged from content. */
+export async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  // Copy into a fresh ArrayBuffer-backed view so the digest input is a concrete BufferSource
+  // regardless of the caller's backing buffer (SharedArrayBuffer-typed views are rejected).
+  const digest = await crypto.subtle.digest("SHA-256", new Uint8Array(bytes))
+  const view = new Uint8Array(digest)
+  let hex = ""
+  for (let i = 0; i < view.length; i++) hex += (view[i] as number).toString(16).padStart(2, "0")
+  return hex
+}
+
+/** SHA-256 hex of a UTF-8 string. */
+export function sha256HexOf(text: string): Promise<string> {
+  return sha256Hex(encoder.encode(text))
+}
+
+/** Deterministic JSON with recursively sorted object keys. Arrays keep order. Rejects non-finite numbers. */
+export function canonicalJson(value: unknown): string {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value)
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("non-finite JSON number")
+    return JSON.stringify(value)
+  }
+  if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(",")}]`
+  if (typeof value === "object") {
+    const record = value as Record<string, unknown>
+    const keys = Object.keys(record)
+      .filter((key) => record[key] !== undefined)
+      .sort()
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`
+  }
+  throw new TypeError(`cannot canonicalize ${typeof value}`)
+}