@elisym/sdk 0.5.0 → 0.7.0

package/dist/runtime.cjs

@@ -0,0 +1,200 @@
+'use strict';
+
+// src/runtime/jobLedger.ts
+var JOB_LEDGER_VERSION = 1;
+var TERMINAL_STATES = /* @__PURE__ */ new Set([
+  "delivered",
+  "result_received",
+  "failed",
+  "cancelled"
+]);
+async function pendingJobs(adapter, side) {
+  const latest = await adapter.loadLatest(side);
+  const pending = [];
+  for (const entry of latest.values()) {
+    if (!TERMINAL_STATES.has(entry.state)) {
+      pending.push(entry);
+    }
+  }
+  pending.sort((left, right) => left.jobCreatedAt - right.jobCreatedAt);
+  return pending;
+}
+async function findByJobId(adapter, jobEventId) {
+  const latest = await adapter.loadLatest();
+  return latest.get(jobEventId);
+}
+
+// src/runtime/memoryAdapter.ts
+function createMemoryJobLedgerAdapter() {
+  const log = [];
+  let rowCounter = 0;
+  function latestByJobId(side) {
+    const latest = /* @__PURE__ */ new Map();
+    const latestRowAt = /* @__PURE__ */ new Map();
+    for (const row of log) {
+      if (side && row.entry.side !== side) {
+        continue;
+      }
+      const jobId = row.entry.jobEventId;
+      const previous = latestRowAt.get(jobId) ?? -Infinity;
+      if (row.rowAt >= previous) {
+        latest.set(jobId, row.entry);
+        latestRowAt.set(jobId, row.rowAt);
+      }
+    }
+    return latest;
+  }
+  return {
+    async write(entry) {
+      const finalized = {
+        ...entry,
+        transitionAt: Date.now(),
+        version: JOB_LEDGER_VERSION
+      };
+      rowCounter += 1;
+      log.push({ entry: finalized, rowAt: rowCounter });
+    },
+    async loadLatest(side) {
+      return latestByJobId(side);
+    },
+    async pruneOldEntries(retentionMs) {
+      const cutoff = Date.now() - retentionMs;
+      const latest = latestByJobId();
+      const dropIds = /* @__PURE__ */ new Set();
+      for (const [jobId, entry] of latest) {
+        if (TERMINAL_STATES.has(entry.state) && entry.transitionAt < cutoff) {
+          dropIds.add(jobId);
+        }
+      }
+      if (dropIds.size === 0) {
+        return 0;
+      }
+      let deleted = 0;
+      for (let index = log.length - 1; index >= 0; index--) {
+        const row = log[index];
+        if (row && dropIds.has(row.entry.jobEventId)) {
+          log.splice(index, 1);
+          deleted += 1;
+        }
+      }
+      return deleted;
+    },
+    clear() {
+      log.length = 0;
+      rowCounter = 0;
+    },
+    rows() {
+      return log.map((row) => row.entry);
+    }
+  };
+}
+
+// src/runtime/recoveryLoop.ts
+function createRecoveryLoop(options) {
+  const { adapter, onProviderPending, onCustomerPending, intervalMs, retentionMs, concurrency } = options;
+  const logger = options.logger ?? {};
+  if (intervalMs <= 0) {
+    throw new RangeError("intervalMs must be > 0");
+  }
+  if (concurrency <= 0) {
+    throw new RangeError("concurrency must be > 0");
+  }
+  if (retentionMs <= 0) {
+    throw new RangeError("retentionMs must be > 0");
+  }
+  let timer;
+  let running = false;
+  async function runBatch(entries, handler) {
+    let index = 0;
+    const workerCount = Math.min(concurrency, entries.length);
+    const workers = Array.from({ length: workerCount }, async () => {
+      while (index < entries.length) {
+        const currentIndex = index++;
+        const entry = entries[currentIndex];
+        if (!entry) {
+          continue;
+        }
+        try {
+          await handler(entry);
+        } catch (error) {
+          logger.warn?.(
+            {
+              err: error instanceof Error ? error.message : String(error),
+              jobEventId: entry.jobEventId,
+              side: entry.side,
+              state: entry.state
+            },
+            "recovery handler threw"
+          );
+        }
+      }
+    });
+    await Promise.all(workers);
+  }
+  async function sweepSide(side, handler) {
+    if (!handler) {
+      return;
+    }
+    const pending = await pendingJobs(adapter, side);
+    if (pending.length === 0) {
+      return;
+    }
+    logger.info?.({ [side]: pending.length }, "recovery sweep: resuming pending jobs");
+    await runBatch(pending, handler);
+  }
+  async function sweepOnce() {
+    if (running) {
+      return;
+    }
+    running = true;
+    try {
+      try {
+        await adapter.pruneOldEntries(retentionMs);
+      } catch (error) {
+        logger.warn?.(
+          { err: error instanceof Error ? error.message : String(error) },
+          "recovery: pruneOldEntries failed"
+        );
+      }
+      await sweepSide("provider", onProviderPending);
+      await sweepSide("customer", onCustomerPending);
+    } finally {
+      running = false;
+    }
+  }
+  function start() {
+    if (timer) {
+      return;
+    }
+    sweepOnce().catch(
+      (error) => logger.warn?.(
+        { err: error instanceof Error ? error.message : String(error) },
+        "initial recovery sweep failed"
+      )
+    );
+    timer = setInterval(() => {
+      sweepOnce().catch(
+        (error) => logger.warn?.(
+          { err: error instanceof Error ? error.message : String(error) },
+          "recovery sweep failed"
+        )
+      );
+    }, intervalMs);
+  }
+  function stop() {
+    if (timer) {
+      clearInterval(timer);
+      timer = void 0;
+    }
+  }
+  return { start, stop, sweepOnce };
+}
+
+exports.JOB_LEDGER_VERSION = JOB_LEDGER_VERSION;
+exports.TERMINAL_STATES = TERMINAL_STATES;
+exports.createMemoryJobLedgerAdapter = createMemoryJobLedgerAdapter;
+exports.createRecoveryLoop = createRecoveryLoop;
+exports.findByJobId = findByJobId;
+exports.pendingJobs = pendingJobs;
+//# sourceMappingURL=runtime.cjs.map
+//# sourceMappingURL=runtime.cjs.map

package/dist/runtime.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime/jobLedger.ts","../src/runtime/memoryAdapter.ts","../src/runtime/recoveryLoop.ts"],"names":[],"mappings":"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","file":"runtime.cjs","sourcesContent":["/**\n * Shared JobLedger types + adapter interface for elisym crash recovery.\n *\n * The ledger is an append-only log of state transitions for each job,\n * keyed by the Nostr job-request event id. Each adapter chooses its own\n * storage backend (Eliza memory, SQLite, tests-only in-memory) and\n * exposes the minimal read/write surface this module defines.\n */\n\nexport type JobSide = 'provider' | 'customer';\n\nexport type ProviderState =\n  | 'waiting_payment'\n  | 'paid'\n  | 'executed'\n  | 'delivered'\n  | 'failed'\n  | 'cancelled';\n\nexport type CustomerState =\n  | 'submitted'\n  | 'waiting_payment'\n  | 'payment_sent'\n  | 'result_received'\n  | 'failed'\n  | 'cancelled';\n\nexport type JobState = ProviderState | CustomerState;\n\nexport const JOB_LEDGER_VERSION = 1;\n\nexport const TERMINAL_STATES: ReadonlySet<JobState> = new Set<JobState>([\n  'delivered',\n  'result_received',\n  'failed',\n  'cancelled',\n]);\n\nexport interface JobLedgerEntry {\n  jobEventId: string;\n  side: JobSide;\n  state: JobState;\n  capability: string;\n  priceLamports: string;\n  rawEventJson?: string;\n  customerPubkey?: string;\n  providerPubkey?: string;\n  input?: string;\n  paymentRequestJson?: string;\n  txSignature?: string;\n  resultContent?: string;\n  error?: string;\n  retryCount?: number;\n  transitionAt: number;\n  jobCreatedAt: number;\n  version: number;\n}\n\n/**\n * Input to `adapter.write`. The adapter is responsible for stamping\n * `transitionAt` (wall-clock) and `version` so callers can spread an\n * earlier entry safely without carrying those fields forward.\n */\nexport type JobLedgerWriteInput = Omit<JobLedgerEntry, 'transitionAt' | 'version'>;\n\nexport interface JobLedgerAdapter {\n  /** Append a new state transition for a job. */\n  write(entry: JobLedgerWriteInput): Promise<void>;\n  /**\n   * Return the latest entry per job id. If `side` is given, restrict to\n   * one side; otherwise include both.\n   */\n  loadLatest(side?: JobSide): Promise<Map<string, JobLedgerEntry>>;\n  /**\n   * Delete terminal entries whose last transition happened before\n   * `now - retentionMs`. Non-terminal entries are retained so recovery\n   * can keep retrying. Returns the number of entries dropped.\n   */\n  pruneOldEntries(retentionMs: number): Promise<number>;\n}\n\n/**\n * Convenience: return non-terminal entries for `side`, oldest-first by\n * `jobCreatedAt`. Derived from `loadLatest` so any adapter satisfies it.\n */\nexport async function pendingJobs(\n  adapter: JobLedgerAdapter,\n  side: JobSide,\n): Promise<JobLedgerEntry[]> {\n  const latest = await adapter.loadLatest(side);\n  const pending: JobLedgerEntry[] = [];\n  for (const entry of latest.values()) {\n    if (!TERMINAL_STATES.has(entry.state)) {\n      pending.push(entry);\n    }\n  }\n  pending.sort((left, right) => left.jobCreatedAt - right.jobCreatedAt);\n  return pending;\n}\n\nexport async function findByJobId(\n  adapter: JobLedgerAdapter,\n  jobEventId: string,\n): Promise<JobLedgerEntry | undefined> {\n  const latest = await adapter.loadLatest();\n  return latest.get(jobEventId);\n}\n","import {\n  JOB_LEDGER_VERSION,\n  TERMINAL_STATES,\n  type JobLedgerAdapter,\n  type JobLedgerEntry,\n  type JobLedgerWriteInput,\n  type JobSide,\n} from './jobLedger';\n\ninterface Row {\n  entry: JobLedgerEntry;\n  /** Row timestamp, separate from entry.transitionAt so we can resolve ties. */\n  rowAt: number;\n}\n\n/**\n * In-memory reference adapter. Useful for tests and ephemeral deployments\n * where no durable backing store is required. Not suitable for real\n * crash-recovery (everything is lost on process exit).\n */\nexport function createMemoryJobLedgerAdapter(): JobLedgerAdapter & {\n  /** Test-only: drop all rows. */\n  clear(): void;\n  /** Test-only: inspect the raw append log. */\n  rows(): ReadonlyArray<JobLedgerEntry>;\n} {\n  const log: Row[] = [];\n  let rowCounter = 0;\n\n  function latestByJobId(side?: JobSide): Map<string, JobLedgerEntry> {\n    const latest = new Map<string, JobLedgerEntry>();\n    const latestRowAt = new Map<string, number>();\n    for (const row of log) {\n      if (side && row.entry.side !== side) {\n        continue;\n      }\n      const jobId = row.entry.jobEventId;\n      const previous = latestRowAt.get(jobId) ?? -Infinity;\n      if (row.rowAt >= previous) {\n        latest.set(jobId, row.entry);\n        latestRowAt.set(jobId, row.rowAt);\n      }\n    }\n    return latest;\n  }\n\n  return {\n    async write(entry: JobLedgerWriteInput): Promise<void> {\n      const finalized: JobLedgerEntry = {\n        ...entry,\n        transitionAt: Date.now(),\n        version: JOB_LEDGER_VERSION,\n      };\n      rowCounter += 1;\n      log.push({ entry: finalized, rowAt: rowCounter });\n    },\n    async loadLatest(side?: JobSide): Promise<Map<string, JobLedgerEntry>> {\n      return latestByJobId(side);\n    },\n    async pruneOldEntries(retentionMs: number): Promise<number> {\n      const cutoff = Date.now() - retentionMs;\n      const latest = latestByJobId();\n      const dropIds = new Set<string>();\n      for (const [jobId, entry] of latest) {\n        if (TERMINAL_STATES.has(entry.state) && entry.transitionAt < cutoff) {\n          dropIds.add(jobId);\n        }\n      }\n      if (dropIds.size === 0) {\n        return 0;\n      }\n      let deleted = 0;\n      for (let index = log.length - 1; index >= 0; index--) {\n        const row = log[index];\n        if (row && dropIds.has(row.entry.jobEventId)) {\n          log.splice(index, 1);\n          deleted += 1;\n        }\n      }\n      return deleted;\n    },\n    clear(): void {\n      log.length = 0;\n      rowCounter = 0;\n    },\n    rows(): ReadonlyArray<JobLedgerEntry> {\n      return log.map((row) => row.entry);\n    },\n  };\n}\n","import { pendingJobs, type JobLedgerAdapter, type JobLedgerEntry, type JobSide } from './jobLedger';\n\nexport interface RecoveryLoopLogger {\n  info?(obj: Record<string, unknown>, msg?: string): void;\n  warn?(obj: Record<string, unknown>, msg?: string): void;\n  debug?(obj: Record<string, unknown>, msg?: string): void;\n}\n\nexport interface RecoveryLoopOptions {\n  adapter: JobLedgerAdapter;\n  /** Called for each non-terminal provider-side entry. Should advance state. */\n  onProviderPending?: (entry: JobLedgerEntry) => Promise<void>;\n  /** Called for each non-terminal customer-side entry. Should advance state. */\n  onCustomerPending?: (entry: JobLedgerEntry) => Promise<void>;\n  /** Sweep cadence. */\n  intervalMs: number;\n  /** Retention for terminal entries. Passed to adapter.pruneOldEntries each sweep. */\n  retentionMs: number;\n  /** Concurrent per-job worker count during a sweep. */\n  concurrency: number;\n  /** Optional structured logger. Falls back to silence. */\n  logger?: RecoveryLoopLogger;\n}\n\nexport interface RecoveryLoop {\n  /** Kick off an initial sweep (non-blocking) and start the periodic timer. */\n  start(): void;\n  /** Stop the periodic timer. Does not cancel an in-flight sweep. */\n  stop(): void;\n  /** Run a single sweep synchronously. Useful for tests or manual triggers. */\n  sweepOnce(): Promise<void>;\n}\n\n/**\n * Generic recovery scaffold: periodic pruning + concurrent replay of\n * non-terminal ledger entries. Per-side handlers own the business\n * semantics (retry budget, re-execute, payment verify, delivery retry).\n *\n * Notes:\n * - Overlap guard: if the previous sweep is still in flight, subsequent\n *   tick fires are skipped - no queueing. The next on-schedule fire will\n *   pick up where the previous left off (ledger is idempotent).\n * - Handler errors are caught and logged at `warn` so a single bad entry\n *   doesn't poison the batch.\n */\nexport function createRecoveryLoop(options: RecoveryLoopOptions): RecoveryLoop {\n  const { adapter, onProviderPending, onCustomerPending, intervalMs, retentionMs, concurrency } =\n    options;\n  const logger = options.logger ?? {};\n  if (intervalMs <= 0) {\n    throw new RangeError('intervalMs must be > 0');\n  }\n  if (concurrency <= 0) {\n    throw new RangeError('concurrency must be > 0');\n  }\n  if (retentionMs <= 0) {\n    throw new RangeError('retentionMs must be > 0');\n  }\n\n  let timer: ReturnType<typeof setInterval> | undefined;\n  let running = false;\n\n  async function runBatch(\n    entries: JobLedgerEntry[],\n    handler: (entry: JobLedgerEntry) => Promise<void>,\n  ): Promise<void> {\n    let index = 0;\n    const workerCount = Math.min(concurrency, entries.length);\n    const workers = Array.from({ length: workerCount }, async () => {\n      while (index < entries.length) {\n        const currentIndex = index++;\n        const entry = entries[currentIndex];\n        if (!entry) {\n          continue;\n        }\n        try {\n          await handler(entry);\n        } catch (error) {\n          logger.warn?.(\n            {\n              err: error instanceof Error ? error.message : String(error),\n              jobEventId: entry.jobEventId,\n              side: entry.side,\n              state: entry.state,\n            },\n            'recovery handler threw',\n          );\n        }\n      }\n    });\n    await Promise.all(workers);\n  }\n\n  async function sweepSide(\n    side: JobSide,\n    handler: ((entry: JobLedgerEntry) => Promise<void>) | undefined,\n  ): Promise<void> {\n    if (!handler) {\n      return;\n    }\n    const pending = await pendingJobs(adapter, side);\n    if (pending.length === 0) {\n      return;\n    }\n    logger.info?.({ [side]: pending.length }, 'recovery sweep: resuming pending jobs');\n    await runBatch(pending, handler);\n  }\n\n  async function sweepOnce(): Promise<void> {\n    if (running) {\n      return;\n    }\n    running = true;\n    try {\n      try {\n        await adapter.pruneOldEntries(retentionMs);\n      } catch (error) {\n        logger.warn?.(\n          { err: error instanceof Error ? error.message : String(error) },\n          'recovery: pruneOldEntries failed',\n        );\n      }\n      await sweepSide('provider', onProviderPending);\n      await sweepSide('customer', onCustomerPending);\n    } finally {\n      running = false;\n    }\n  }\n\n  function start(): void {\n    if (timer) {\n      return;\n    }\n    // Initial sweep kicked off in background so start() returns quickly.\n    sweepOnce().catch((error) =>\n      logger.warn?.(\n        { err: error instanceof Error ? error.message : String(error) },\n        'initial recovery sweep failed',\n      ),\n    );\n    timer = setInterval(() => {\n      sweepOnce().catch((error) =>\n        logger.warn?.(\n          { err: error instanceof Error ? error.message : String(error) },\n          'recovery sweep failed',\n        ),\n      );\n    }, intervalMs);\n  }\n\n  function stop(): void {\n    if (timer) {\n      clearInterval(timer);\n      timer = undefined;\n    }\n  }\n\n  return { start, stop, sweepOnce };\n}\n"]}

package/dist/runtime.d.cts

@@ -0,0 +1,116 @@
+/**
+ * Shared JobLedger types + adapter interface for elisym crash recovery.
+ *
+ * The ledger is an append-only log of state transitions for each job,
+ * keyed by the Nostr job-request event id. Each adapter chooses its own
+ * storage backend (Eliza memory, SQLite, tests-only in-memory) and
+ * exposes the minimal read/write surface this module defines.
+ */
+type JobSide = 'provider' | 'customer';
+type ProviderState = 'waiting_payment' | 'paid' | 'executed' | 'delivered' | 'failed' | 'cancelled';
+type CustomerState = 'submitted' | 'waiting_payment' | 'payment_sent' | 'result_received' | 'failed' | 'cancelled';
+type JobState = ProviderState | CustomerState;
+declare const JOB_LEDGER_VERSION = 1;
+declare const TERMINAL_STATES: ReadonlySet<JobState>;
+interface JobLedgerEntry {
+    jobEventId: string;
+    side: JobSide;
+    state: JobState;
+    capability: string;
+    priceLamports: string;
+    rawEventJson?: string;
+    customerPubkey?: string;
+    providerPubkey?: string;
+    input?: string;
+    paymentRequestJson?: string;
+    txSignature?: string;
+    resultContent?: string;
+    error?: string;
+    retryCount?: number;
+    transitionAt: number;
+    jobCreatedAt: number;
+    version: number;
+}
+/**
+ * Input to `adapter.write`. The adapter is responsible for stamping
+ * `transitionAt` (wall-clock) and `version` so callers can spread an
+ * earlier entry safely without carrying those fields forward.
+ */
+type JobLedgerWriteInput = Omit<JobLedgerEntry, 'transitionAt' | 'version'>;
+interface JobLedgerAdapter {
+    /** Append a new state transition for a job. */
+    write(entry: JobLedgerWriteInput): Promise<void>;
+    /**
+     * Return the latest entry per job id. If `side` is given, restrict to
+     * one side; otherwise include both.
+     */
+    loadLatest(side?: JobSide): Promise<Map<string, JobLedgerEntry>>;
+    /**
+     * Delete terminal entries whose last transition happened before
+     * `now - retentionMs`. Non-terminal entries are retained so recovery
+     * can keep retrying. Returns the number of entries dropped.
+     */
+    pruneOldEntries(retentionMs: number): Promise<number>;
+}
+/**
+ * Convenience: return non-terminal entries for `side`, oldest-first by
+ * `jobCreatedAt`. Derived from `loadLatest` so any adapter satisfies it.
+ */
+declare function pendingJobs(adapter: JobLedgerAdapter, side: JobSide): Promise<JobLedgerEntry[]>;
+declare function findByJobId(adapter: JobLedgerAdapter, jobEventId: string): Promise<JobLedgerEntry | undefined>;
+
+/**
+ * In-memory reference adapter. Useful for tests and ephemeral deployments
+ * where no durable backing store is required. Not suitable for real
+ * crash-recovery (everything is lost on process exit).
+ */
+declare function createMemoryJobLedgerAdapter(): JobLedgerAdapter & {
+    /** Test-only: drop all rows. */
+    clear(): void;
+    /** Test-only: inspect the raw append log. */
+    rows(): ReadonlyArray<JobLedgerEntry>;
+};
+
+interface RecoveryLoopLogger {
+    info?(obj: Record<string, unknown>, msg?: string): void;
+    warn?(obj: Record<string, unknown>, msg?: string): void;
+    debug?(obj: Record<string, unknown>, msg?: string): void;
+}
+interface RecoveryLoopOptions {
+    adapter: JobLedgerAdapter;
+    /** Called for each non-terminal provider-side entry. Should advance state. */
+    onProviderPending?: (entry: JobLedgerEntry) => Promise<void>;
+    /** Called for each non-terminal customer-side entry. Should advance state. */
+    onCustomerPending?: (entry: JobLedgerEntry) => Promise<void>;
+    /** Sweep cadence. */
+    intervalMs: number;
+    /** Retention for terminal entries. Passed to adapter.pruneOldEntries each sweep. */
+    retentionMs: number;
+    /** Concurrent per-job worker count during a sweep. */
+    concurrency: number;
+    /** Optional structured logger. Falls back to silence. */
+    logger?: RecoveryLoopLogger;
+}
+interface RecoveryLoop {
+    /** Kick off an initial sweep (non-blocking) and start the periodic timer. */
+    start(): void;
+    /** Stop the periodic timer. Does not cancel an in-flight sweep. */
+    stop(): void;
+    /** Run a single sweep synchronously. Useful for tests or manual triggers. */
+    sweepOnce(): Promise<void>;
+}
+/**
+ * Generic recovery scaffold: periodic pruning + concurrent replay of
+ * non-terminal ledger entries. Per-side handlers own the business
+ * semantics (retry budget, re-execute, payment verify, delivery retry).
+ *
+ * Notes:
+ * - Overlap guard: if the previous sweep is still in flight, subsequent
+ *   tick fires are skipped - no queueing. The next on-schedule fire will
+ *   pick up where the previous left off (ledger is idempotent).
+ * - Handler errors are caught and logged at `warn` so a single bad entry
+ *   doesn't poison the batch.
+ */
+declare function createRecoveryLoop(options: RecoveryLoopOptions): RecoveryLoop;
+
+export { type CustomerState, JOB_LEDGER_VERSION, type JobLedgerAdapter, type JobLedgerEntry, type JobLedgerWriteInput, type JobSide, type JobState, type ProviderState, type RecoveryLoop, type RecoveryLoopLogger, type RecoveryLoopOptions, TERMINAL_STATES, createMemoryJobLedgerAdapter, createRecoveryLoop, findByJobId, pendingJobs };

package/dist/runtime.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared JobLedger types + adapter interface for elisym crash recovery.
+ *
+ * The ledger is an append-only log of state transitions for each job,
+ * keyed by the Nostr job-request event id. Each adapter chooses its own
+ * storage backend (Eliza memory, SQLite, tests-only in-memory) and
+ * exposes the minimal read/write surface this module defines.
+ */
+type JobSide = 'provider' | 'customer';
+type ProviderState = 'waiting_payment' | 'paid' | 'executed' | 'delivered' | 'failed' | 'cancelled';
+type CustomerState = 'submitted' | 'waiting_payment' | 'payment_sent' | 'result_received' | 'failed' | 'cancelled';
+type JobState = ProviderState | CustomerState;
+declare const JOB_LEDGER_VERSION = 1;
+declare const TERMINAL_STATES: ReadonlySet<JobState>;
+interface JobLedgerEntry {
+    jobEventId: string;
+    side: JobSide;
+    state: JobState;
+    capability: string;
+    priceLamports: string;
+    rawEventJson?: string;
+    customerPubkey?: string;
+    providerPubkey?: string;
+    input?: string;
+    paymentRequestJson?: string;
+    txSignature?: string;
+    resultContent?: string;
+    error?: string;
+    retryCount?: number;
+    transitionAt: number;
+    jobCreatedAt: number;
+    version: number;
+}
+/**
+ * Input to `adapter.write`. The adapter is responsible for stamping
+ * `transitionAt` (wall-clock) and `version` so callers can spread an
+ * earlier entry safely without carrying those fields forward.
+ */
+type JobLedgerWriteInput = Omit<JobLedgerEntry, 'transitionAt' | 'version'>;
+interface JobLedgerAdapter {
+    /** Append a new state transition for a job. */
+    write(entry: JobLedgerWriteInput): Promise<void>;
+    /**
+     * Return the latest entry per job id. If `side` is given, restrict to
+     * one side; otherwise include both.
+     */
+    loadLatest(side?: JobSide): Promise<Map<string, JobLedgerEntry>>;
+    /**
+     * Delete terminal entries whose last transition happened before
+     * `now - retentionMs`. Non-terminal entries are retained so recovery
+     * can keep retrying. Returns the number of entries dropped.
+     */
+    pruneOldEntries(retentionMs: number): Promise<number>;
+}
+/**
+ * Convenience: return non-terminal entries for `side`, oldest-first by
+ * `jobCreatedAt`. Derived from `loadLatest` so any adapter satisfies it.
+ */
+declare function pendingJobs(adapter: JobLedgerAdapter, side: JobSide): Promise<JobLedgerEntry[]>;
+declare function findByJobId(adapter: JobLedgerAdapter, jobEventId: string): Promise<JobLedgerEntry | undefined>;
+
+/**
+ * In-memory reference adapter. Useful for tests and ephemeral deployments
+ * where no durable backing store is required. Not suitable for real
+ * crash-recovery (everything is lost on process exit).
+ */
+declare function createMemoryJobLedgerAdapter(): JobLedgerAdapter & {
+    /** Test-only: drop all rows. */
+    clear(): void;
+    /** Test-only: inspect the raw append log. */
+    rows(): ReadonlyArray<JobLedgerEntry>;
+};
+
+interface RecoveryLoopLogger {
+    info?(obj: Record<string, unknown>, msg?: string): void;
+    warn?(obj: Record<string, unknown>, msg?: string): void;
+    debug?(obj: Record<string, unknown>, msg?: string): void;
+}
+interface RecoveryLoopOptions {
+    adapter: JobLedgerAdapter;
+    /** Called for each non-terminal provider-side entry. Should advance state. */
+    onProviderPending?: (entry: JobLedgerEntry) => Promise<void>;
+    /** Called for each non-terminal customer-side entry. Should advance state. */
+    onCustomerPending?: (entry: JobLedgerEntry) => Promise<void>;
+    /** Sweep cadence. */
+    intervalMs: number;
+    /** Retention for terminal entries. Passed to adapter.pruneOldEntries each sweep. */
+    retentionMs: number;
+    /** Concurrent per-job worker count during a sweep. */
+    concurrency: number;
+    /** Optional structured logger. Falls back to silence. */
+    logger?: RecoveryLoopLogger;
+}
+interface RecoveryLoop {
+    /** Kick off an initial sweep (non-blocking) and start the periodic timer. */
+    start(): void;
+    /** Stop the periodic timer. Does not cancel an in-flight sweep. */
+    stop(): void;
+    /** Run a single sweep synchronously. Useful for tests or manual triggers. */
+    sweepOnce(): Promise<void>;
+}
+/**
+ * Generic recovery scaffold: periodic pruning + concurrent replay of
+ * non-terminal ledger entries. Per-side handlers own the business
+ * semantics (retry budget, re-execute, payment verify, delivery retry).
+ *
+ * Notes:
+ * - Overlap guard: if the previous sweep is still in flight, subsequent
+ *   tick fires are skipped - no queueing. The next on-schedule fire will
+ *   pick up where the previous left off (ledger is idempotent).
+ * - Handler errors are caught and logged at `warn` so a single bad entry
+ *   doesn't poison the batch.
+ */
+declare function createRecoveryLoop(options: RecoveryLoopOptions): RecoveryLoop;
+
+export { type CustomerState, JOB_LEDGER_VERSION, type JobLedgerAdapter, type JobLedgerEntry, type JobLedgerWriteInput, type JobSide, type JobState, type ProviderState, type RecoveryLoop, type RecoveryLoopLogger, type RecoveryLoopOptions, TERMINAL_STATES, createMemoryJobLedgerAdapter, createRecoveryLoop, findByJobId, pendingJobs };

package/dist/runtime.js

@@ -0,0 +1,193 @@
+// src/runtime/jobLedger.ts
+var JOB_LEDGER_VERSION = 1;
+var TERMINAL_STATES = /* @__PURE__ */ new Set([
+  "delivered",
+  "result_received",
+  "failed",
+  "cancelled"
+]);
+async function pendingJobs(adapter, side) {
+  const latest = await adapter.loadLatest(side);
+  const pending = [];
+  for (const entry of latest.values()) {
+    if (!TERMINAL_STATES.has(entry.state)) {
+      pending.push(entry);
+    }
+  }
+  pending.sort((left, right) => left.jobCreatedAt - right.jobCreatedAt);
+  return pending;
+}
+async function findByJobId(adapter, jobEventId) {
+  const latest = await adapter.loadLatest();
+  return latest.get(jobEventId);
+}
+
+// src/runtime/memoryAdapter.ts
+function createMemoryJobLedgerAdapter() {
+  const log = [];
+  let rowCounter = 0;
+  function latestByJobId(side) {
+    const latest = /* @__PURE__ */ new Map();
+    const latestRowAt = /* @__PURE__ */ new Map();
+    for (const row of log) {
+      if (side && row.entry.side !== side) {
+        continue;
+      }
+      const jobId = row.entry.jobEventId;
+      const previous = latestRowAt.get(jobId) ?? -Infinity;
+      if (row.rowAt >= previous) {
+        latest.set(jobId, row.entry);
+        latestRowAt.set(jobId, row.rowAt);
+      }
+    }
+    return latest;
+  }
+  return {
+    async write(entry) {
+      const finalized = {
+        ...entry,
+        transitionAt: Date.now(),
+        version: JOB_LEDGER_VERSION
+      };
+      rowCounter += 1;
+      log.push({ entry: finalized, rowAt: rowCounter });
+    },
+    async loadLatest(side) {
+      return latestByJobId(side);
+    },
+    async pruneOldEntries(retentionMs) {
+      const cutoff = Date.now() - retentionMs;
+      const latest = latestByJobId();
+      const dropIds = /* @__PURE__ */ new Set();
+      for (const [jobId, entry] of latest) {
+        if (TERMINAL_STATES.has(entry.state) && entry.transitionAt < cutoff) {
+          dropIds.add(jobId);
+        }
+      }
+      if (dropIds.size === 0) {
+        return 0;
+      }
+      let deleted = 0;
+      for (let index = log.length - 1; index >= 0; index--) {
+        const row = log[index];
+        if (row && dropIds.has(row.entry.jobEventId)) {
+          log.splice(index, 1);
+          deleted += 1;
+        }
+      }
+      return deleted;
+    },
+    clear() {
+      log.length = 0;
+      rowCounter = 0;
+    },
+    rows() {
+      return log.map((row) => row.entry);
+    }
+  };
+}
+
+// src/runtime/recoveryLoop.ts
+function createRecoveryLoop(options) {
+  const { adapter, onProviderPending, onCustomerPending, intervalMs, retentionMs, concurrency } = options;
+  const logger = options.logger ?? {};
+  if (intervalMs <= 0) {
+    throw new RangeError("intervalMs must be > 0");
+  }
+  if (concurrency <= 0) {
+    throw new RangeError("concurrency must be > 0");
+  }
+  if (retentionMs <= 0) {
+    throw new RangeError("retentionMs must be > 0");
+  }
+  let timer;
+  let running = false;
+  async function runBatch(entries, handler) {
+    let index = 0;
+    const workerCount = Math.min(concurrency, entries.length);
+    const workers = Array.from({ length: workerCount }, async () => {
+      while (index < entries.length) {
+        const currentIndex = index++;
+        const entry = entries[currentIndex];
+        if (!entry) {
+          continue;
+        }
+        try {
+          await handler(entry);
+        } catch (error) {
+          logger.warn?.(
+            {
+              err: error instanceof Error ? error.message : String(error),
+              jobEventId: entry.jobEventId,
+              side: entry.side,
+              state: entry.state
+            },
+            "recovery handler threw"
+          );
+        }
+      }
+    });
+    await Promise.all(workers);
+  }
+  async function sweepSide(side, handler) {
+    if (!handler) {
+      return;
+    }
+    const pending = await pendingJobs(adapter, side);
+    if (pending.length === 0) {
+      return;
+    }
+    logger.info?.({ [side]: pending.length }, "recovery sweep: resuming pending jobs");
+    await runBatch(pending, handler);
+  }
+  async function sweepOnce() {
+    if (running) {
+      return;
+    }
+    running = true;
+    try {
+      try {
+        await adapter.pruneOldEntries(retentionMs);
+      } catch (error) {
+        logger.warn?.(
+          { err: error instanceof Error ? error.message : String(error) },
+          "recovery: pruneOldEntries failed"
+        );
+      }
+      await sweepSide("provider", onProviderPending);
+      await sweepSide("customer", onCustomerPending);
+    } finally {
+      running = false;
+    }
+  }
+  function start() {
+    if (timer) {
+      return;
+    }
+    sweepOnce().catch(
+      (error) => logger.warn?.(
+        { err: error instanceof Error ? error.message : String(error) },
+        "initial recovery sweep failed"
+      )
+    );
+    timer = setInterval(() => {
+      sweepOnce().catch(
+        (error) => logger.warn?.(
+          { err: error instanceof Error ? error.message : String(error) },
+          "recovery sweep failed"
+        )
+      );
+    }, intervalMs);
+  }
+  function stop() {
+    if (timer) {
+      clearInterval(timer);
+      timer = void 0;
+    }
+  }
+  return { start, stop, sweepOnce };
+}
+
+export { JOB_LEDGER_VERSION, TERMINAL_STATES, createMemoryJobLedgerAdapter, createRecoveryLoop, findByJobId, pendingJobs };
+//# sourceMappingURL=runtime.js.map
+//# sourceMappingURL=runtime.js.map