@vauban-org/agent-sdk 1.0.0 → 1.2.0

package/src/ports/workflow-runtime.ts

@@ -0,0 +1,327 @@
+/**
+ * WorkflowRuntimePort — durable workflow execution port (S3 spec).
+ *
+ * Defines: 9-state machine, journal invariants I-S3-1..8, replay determinism,
+ * ctx.* primitives, lease takeover pattern, handler versioning.
+ *
+ * Default adapter: DBOSWorkflowAdapter (DBOS-TS Apache 2.0, Postgres-native).
+ * Swap-able to Temporal/Restate via this port + test contract T-S3-1..12.
+ */
+
+// ─── Workflow run state machine (S3 §3.1) ─────────────────────────────────────
+
+export type WorkflowStatus =
+  | "PENDING"
+  | "RUNNING"
+  | "SLEEPING"
+  | "WAITING_SIGNAL"
+  | "AWAITING_BLOCK"
+  | "AWAITING_EVENT"
+  | "DONE"
+  | "FAILED"
+  | "CANCELLED";
+
+// ─── Journal types (S3 §4) ────────────────────────────────────────────────────
+
+export type StepKind =
+  | "tool_call"
+  | "sleep"
+  | "wait_signal"
+  | "await_block"
+  | "await_event"
+  | "submit_tx"
+  | "human"
+  | "ctx_now"
+  | "ctx_random"
+  | "ctx_uuid"
+  | "child_workflow";
+
+export type StepStatus = "pending" | "running" | "done" | "failed";
+
+export interface JournalEntry {
+  readonly journal_id: bigint;
+  readonly run_id: string; // UUID
+  readonly step_index: number; // monotone, I-S3-1
+  readonly step_name: string;
+  readonly step_kind: StepKind;
+  readonly status: StepStatus;
+  readonly input: unknown; // CBOR-encoded at rest
+  readonly output?: unknown;
+  readonly error?: { message: string; stack?: string };
+  readonly idempotency_key?: string; // 32-byte hex, I-S3-3
+  readonly started_at: Date;
+  readonly finished_at?: Date;
+}
+
+// ─── Workflow run (S3 §3.1 + §7) ─────────────────────────────────────────────
+
+export interface WorkflowRun<TOutput = unknown> {
+  readonly run_id: string;
+  readonly workflow_name: string;
+  readonly workflow_version: string; // locked per I-S3-6
+  readonly status: WorkflowStatus;
+  readonly input: unknown;
+  readonly output?: TOutput;
+  readonly error?: string;
+  readonly lease_owner?: string;
+  readonly lease_expires_at?: Date;
+  readonly wake_at?: Date;
+  readonly started_at: Date;
+  readonly finished_at?: Date;
+  readonly tenant_id: string;
+  readonly manifest_hash?: string; // crosslink S1
+}
+
+// ─── Step options ─────────────────────────────────────────────────────────────
+
+export interface StepOpts {
+  readonly maxAttempts?: number; // default 3, EC-S3-6
+  readonly backoffMs?: number; // default 1000 (1s/2s/4s)
+  readonly idempotencyKey?: string;
+  readonly timeoutMs?: number;
+}
+
+// ─── WorkflowContext — ctx.* primitives (S3 §5.3) ────────────────────────────
+
+export interface WorkflowContext {
+  readonly runId: string;
+  readonly tenantId: string;
+  readonly workflowName: string;
+  readonly workflowVersion: string;
+  readonly abortSignal: AbortSignal;
+
+  /**
+   * Wrap any side-effectful operation. Journaled + replayed from journal.
+   * FORBIDDEN outside ctx.step(): Date.now, Math.random, fetch, fs.*, etc. (S3 §5.4)
+   */
+  step<T>(name: string, fn: () => Promise<T>, opts?: StepOpts): Promise<T>;
+
+  /** Deterministic timestamp — journaled (Q3.2). Never use Date.now() in handlers. */
+  now(): Promise<Date>;
+
+  /** Deterministic random [0,1) — journaled (Q3.2). Never use Math.random(). */
+  random(): Promise<number>;
+
+  /** Deterministic UUID v4 — journaled (Q3.2). Never use crypto.randomUUID(). */
+  uuid(): Promise<string>;
+
+  /** Durable sleep until absolute timestamp. EC-S3-8: t < now() → no-op. */
+  sleepUntil(t: Date): Promise<void>;
+
+  /** Durable sleep for duration in ms. */
+  sleepFor(durationMs: number): Promise<void>;
+
+  /**
+   * Wait for a named signal. Returns signal payload.
+   * Times out → WorkflowSignalTimeoutError (S3 §3.3: FAILED, 'signal_timeout').
+   */
+  waitForSignal<T = unknown>(name: string, timeoutMs?: number): Promise<T>;
+
+  /** Await Starknet block height ≥ n. Transitions: RUNNING → AWAITING_BLOCK → RUNNING. */
+  awaitStarknetBlock(blockHeight: number): Promise<void>;
+
+  /** Await matching event from event bus. Transitions: RUNNING → AWAITING_EVENT → RUNNING. */
+  awaitEvent<T = unknown>(filter: EventFilter): Promise<T>;
+
+  /** Spawn a child workflow. Parent waits for child completion. */
+  childWorkflow<TInput, TOutput>(
+    name: string,
+    input: TInput,
+    opts?: ChildWorkflowOpts
+  ): Promise<TOutput>;
+
+  /** Cooperative cancellation. Step handlers should poll ctx.abortSignal. */
+  cancel(reason: string): Promise<void>;
+}
+
+export interface EventFilter {
+  readonly source?: string;
+  readonly type?: string;
+  readonly tenantId?: string;
+  readonly [key: string]: unknown;
+}
+
+export interface ChildWorkflowOpts {
+  readonly tenantId?: string;
+  readonly version?: string;
+  readonly idempotencyKey?: string;
+}
+
+// ─── Handler type ─────────────────────────────────────────────────────────────
+
+export type WorkflowHandler<TInput = unknown, TOutput = unknown> = (
+  ctx: WorkflowContext,
+  input: TInput
+) => Promise<TOutput>;
+
+// ─── Migration (S3 §6.3) ──────────────────────────────────────────────────────
+
+export type JournalMigrator = (journal: JournalEntry[]) => JournalEntry[];
+
+export interface MigrationResult {
+  readonly ok: boolean;
+  readonly run_id: string;
+  readonly from_version: string;
+  readonly to_version: string;
+  readonly entries_migrated: number;
+  readonly error?: string;
+}
+
+// ─── WorkflowRuntimePort ──────────────────────────────────────────────────────
+
+export interface StartWorkflowOpts {
+  readonly workflowName: string;
+  readonly workflowVersion: string;
+  readonly tenantId: string;
+  readonly input: unknown;
+  readonly idempotencyKey?: string;
+  readonly manifestHash?: string;
+}
+
+export interface ResumeWorkflowOpts {
+  readonly workerId: string;
+  readonly leaseTtlSeconds?: number; // default 60
+}
+
+export interface SendSignalOpts {
+  readonly payload?: unknown;
+}
+
+export interface WorkflowRuntimePort {
+  /**
+   * Register a handler for a workflow name + version.
+   * Must be called before start() for that workflow type.
+   */
+  register<TInput, TOutput>(
+    name: string,
+    version: string,
+    handler: WorkflowHandler<TInput, TOutput>
+  ): void;
+
+  /**
+   * Start a new workflow run. Returns run_id.
+   * Idempotent if idempotencyKey provided and run already exists.
+   */
+  start(opts: StartWorkflowOpts): Promise<string>;
+
+  /**
+   * Attempt to acquire lease and execute a pending/sleeping run.
+   * Returns null if no eligible run found (no work to do).
+   * Runs handler to completion (or suspension) before returning.
+   */
+  executeNext(opts: ResumeWorkflowOpts): Promise<WorkflowRun | null>;
+
+  /** Get current state of a run. */
+  getStatus(runId: string): Promise<WorkflowRun | null>;
+
+  /**
+   * Wait for a run to reach DONE or FAILED.
+   * Polls internally — do not call in a tight loop.
+   */
+  waitForCompletion<TOutput>(
+    runId: string,
+    opts?: { timeoutMs?: number; pollIntervalMs?: number }
+  ): Promise<WorkflowRun<TOutput>>;
+
+  /** Send a named signal to a waiting run (S3 §3.3). */
+  sendSignal(
+    runId: string,
+    signalName: string,
+    opts?: SendSignalOpts
+  ): Promise<void>;
+
+  /**
+   * Cancel a run cooperatively (S3 §3.3, EC-S3-7).
+   * Sets AbortSignal on next step boundary. Hard abort after 30s.
+   */
+  cancel(runId: string, reason: string): Promise<void>;
+
+  /**
+   * Migrate a suspended run to a new handler version (S3 §6.3).
+   * Only valid for runs in SLEEPING | WAITING_SIGNAL | AWAITING_* states.
+   */
+  migrateRun(
+    runId: string,
+    fromVersion: string,
+    toVersion: string,
+    migrator: JournalMigrator
+  ): Promise<MigrationResult>;
+
+  /** Read the journal entries for a run (read-only, audit). */
+  getJournal(runId: string): Promise<JournalEntry[]>;
+
+  /**
+   * Start the worker polling loop.
+   * Worker polls for PENDING runs and calls executeNext() in a loop.
+   */
+  startWorker(opts?: {
+    workerId?: string;
+    pollIntervalMs?: number;
+    maxConcurrent?: number;
+  }): Promise<void>;
+
+  /** Stop the worker polling loop gracefully. */
+  stopWorker(): Promise<void>;
+}
+
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+
+export class WorkflowNotFoundError extends Error {
+  constructor(public readonly runId: string) {
+    super(`Workflow run not found: ${runId}`);
+    this.name = "WorkflowNotFoundError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class WorkflowNonDeterminismError extends Error {
+  constructor(
+    public readonly runId: string,
+    public readonly stepIndex: number,
+    public readonly expected: string,
+    public readonly actual: string
+  ) {
+    super(
+      `Non-determinism at step ${stepIndex}: expected ${expected}, got ${actual} (run=${runId})`
+    );
+    this.name = "WorkflowNonDeterminismError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class WorkflowSignalTimeoutError extends Error {
+  constructor(
+    public readonly runId: string,
+    public readonly signalName: string,
+    public readonly timeoutMs: number
+  ) {
+    super(`Signal '${signalName}' timeout after ${timeoutMs}ms (run=${runId})`);
+    this.name = "WorkflowSignalTimeoutError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class WorkflowLeaseConflictError extends Error {
+  constructor(
+    public readonly runId: string,
+    public readonly currentOwner: string
+  ) {
+    super(`Cannot acquire lease for run ${runId}: held by ${currentOwner}`);
+    this.name = "WorkflowLeaseConflictError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class WorkflowVersionMismatchError extends Error {
+  constructor(
+    public readonly runId: string,
+    public readonly expected: string,
+    public readonly actual: string
+  ) {
+    super(
+      `Version mismatch for run ${runId}: expected ${expected}, got ${actual}`
+    );
+    this.name = "WorkflowVersionMismatchError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/proof/cert-verify.ts

@@ -0,0 +1,249 @@
+/**
+ * Run Certificate verifier — standalone surface for external clients (CLI, dashboards).
+ *
+ * This module is the **single source of truth** for offline verification of a
+ * `SignedRunProofCertificate`. The CC server (`src/proof/ed25519-{signer,verifier}.ts`)
+ * holds the signing side (DB-coupled assembly + signing); this module holds the
+ * verification side, which is intentionally dependency-free (no DB, no MCP).
+ *
+ * Pipeline (mirrors server signer):
+ *   1. Strip embedded `signature` field
+ *   2. JCS-canonicalize (RFC 8785 subset: sorted keys, -0 → 0)
+ *   3. SHA-256 → first 31 bytes → felt252-safe
+ *   4. Poseidon([0x1, sha_felt, CERT_MARKER_FELT]) → cert_hash_felt252
+ *   5. Felt → 32-byte buffer → Ed25519 verify
+ *
+ * Domain separator: `CERT_MARKER_FELT` = UTF-8 "run_cert" felt252 (right-aligned).
+ *
+ * @see ../../../src/proof/ed25519-signer.ts (signer, CC server)
+ * @see docs/ietf/draft-vauban-skill-attestation-00.md (RFC profile)
+ * @public
+ */
+
+import {
+  createHash,
+  createPublicKey,
+  verify as cryptoVerify,
+  type KeyObject,
+} from "node:crypto";
+import { hash } from "starknet";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * Ed25519 signature payload embedded in `SignedRunProofCertificate`.
+ * Mirrors the server-side `SignaturePayload` (single field schema).
+ */
+export interface SignaturePayload {
+  alg: "Ed25519";
+  kid: string;
+  value: string;
+  pubkey_spki_b64: string;
+  cert_hash_felt252: string;
+  signed_at: string;
+}
+
+/**
+ * A `SignedRunProofCertificate` for verification purposes — only the fields
+ * the verifier touches are typed. The cert may carry additional fields
+ * (decision_chain, merkle_root, etc.) which the verifier preserves but does
+ * not inspect.
+ */
+export interface SignedRunProofCertificateLike {
+  signature?: SignaturePayload;
+  // ... plus arbitrary other fields, opaque to the verifier
+  [key: string]: unknown;
+}
+
+export type CertVerifyFailReason =
+  | "missing_signature"
+  | "wrong_alg"
+  | "hash_mismatch"
+  | "pubkey_unresolvable"
+  | "kid_mismatch"
+  | "signature_invalid"
+  | "malformed_signature";
+
+export interface CertVerifyResult {
+  valid: boolean;
+  reason?: CertVerifyFailReason;
+  details?: string;
+  recomputed_cert_hash_felt252: string;
+}
+
+export interface CertVerifyOptions {
+  expectedPublicKey?: KeyObject;
+  expectedKid?: string;
+}
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+/** Domain separator: UTF-8 "run_cert" → felt252 right-aligned, zero-padded. */
+export const CERT_MARKER_FELT: string =
+  "0x" + Buffer.from("run_cert", "utf8").toString("hex").padStart(62, "0");
+
+// ─── JCS canonicalization (RFC 8785 subset) ──────────────────────────────────
+
+function normalizeValue(value: unknown): unknown {
+  if (value === null) return null;
+  if (typeof value === "number") {
+    if (Object.is(value, -0)) return 0;
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(normalizeValue);
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(obj).sort()) {
+      sorted[key] = normalizeValue(obj[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+function canonicalizeJcs(data: Record<string, unknown>): string {
+  return JSON.stringify(normalizeValue(data));
+}
+
+// ─── Felt helpers ─────────────────────────────────────────────────────────────
+
+function felt252ToBytes(felt: string): Buffer {
+  const hex = felt.replace(/^0x/, "").padStart(64, "0");
+  return Buffer.from(hex, "hex");
+}
+
+/**
+ * Compute the felt252 hash that Ed25519 signs over for a Run Certificate.
+ * Strips any embedded `signature` field before hashing — verification is
+ * idempotent.
+ */
+export function computeCertHashFelt252(
+  cert: SignedRunProofCertificateLike
+): string {
+  const { signature: _stripped, ...unsigned } = cert;
+  void _stripped;
+  const canonical = canonicalizeJcs(unsigned as Record<string, unknown>);
+  const sha = createHash("sha256").update(canonical, "utf8").digest("hex");
+  const shaFelt = "0x" + sha.substring(0, 62);
+  return hash.computePoseidonHashOnElements(["0x1", shaFelt, CERT_MARKER_FELT]);
+}
+
+// ─── Public-key reconstruction ────────────────────────────────────────────────
+
+/**
+ * Reconstruct an Ed25519 `KeyObject` from base64 SPKI DER (as embedded in
+ * `signature.pubkey_spki_b64`).
+ *
+ * @throws if base64 is malformed or the key is not Ed25519.
+ */
+export function publicKeyFromSpkiB64(pubkeySpkiB64: string): KeyObject {
+  const der = Buffer.from(pubkeySpkiB64, "base64");
+  if (der.length === 0) {
+    throw new Error("[cert-verify] empty SPKI buffer");
+  }
+  const key = createPublicKey({ key: der, format: "der", type: "spki" });
+  if (key.asymmetricKeyType !== "ed25519") {
+    throw new Error(
+      `[cert-verify] SPKI is not Ed25519 (got ${key.asymmetricKeyType})`
+    );
+  }
+  return key;
+}
+
+// ─── Verifier ─────────────────────────────────────────────────────────────────
+
+/**
+ * Verify a signed Run Certificate. Returns a structured result — never throws
+ * on verification failure (only on malformed input).
+ *
+ * The 7 possible failure reasons are typed via `CertVerifyFailReason` so callers
+ * can branch precisely. `recomputed_cert_hash_felt252` is always returned for
+ * audit trail / debug inspection.
+ */
+export function verifyRunCertificate(
+  cert: SignedRunProofCertificateLike,
+  opts: CertVerifyOptions = {}
+): CertVerifyResult {
+  const recomputed = computeCertHashFelt252(cert);
+
+  const sig = cert.signature;
+  if (!sig) {
+    return {
+      valid: false,
+      reason: "missing_signature",
+      recomputed_cert_hash_felt252: recomputed,
+    };
+  }
+  if (sig.alg !== "Ed25519") {
+    return {
+      valid: false,
+      reason: "wrong_alg",
+      details: `expected Ed25519, got ${String(sig.alg)}`,
+      recomputed_cert_hash_felt252: recomputed,
+    };
+  }
+  if (sig.cert_hash_felt252 !== recomputed) {
+    return {
+      valid: false,
+      reason: "hash_mismatch",
+      details: `embedded=${sig.cert_hash_felt252} recomputed=${recomputed}`,
+      recomputed_cert_hash_felt252: recomputed,
+    };
+  }
+  if (opts.expectedKid && opts.expectedKid !== sig.kid) {
+    return {
+      valid: false,
+      reason: "kid_mismatch",
+      details: `expected kid=${opts.expectedKid}, got ${sig.kid}`,
+      recomputed_cert_hash_felt252: recomputed,
+    };
+  }
+
+  let pubkey: KeyObject;
+  if (opts.expectedPublicKey) {
+    pubkey = opts.expectedPublicKey;
+  } else {
+    try {
+      pubkey = publicKeyFromSpkiB64(sig.pubkey_spki_b64);
+    } catch (err) {
+      return {
+        valid: false,
+        reason: "pubkey_unresolvable",
+        details: err instanceof Error ? err.message : String(err),
+        recomputed_cert_hash_felt252: recomputed,
+      };
+    }
+  }
+
+  let sigBytes: Buffer;
+  try {
+    sigBytes = Buffer.from(sig.value, "base64");
+  } catch {
+    return {
+      valid: false,
+      reason: "malformed_signature",
+      details: "signature.value is not valid base64",
+      recomputed_cert_hash_felt252: recomputed,
+    };
+  }
+  if (sigBytes.length !== 64) {
+    return {
+      valid: false,
+      reason: "malformed_signature",
+      details: `Ed25519 signature must be 64 bytes (got ${sigBytes.length})`,
+      recomputed_cert_hash_felt252: recomputed,
+    };
+  }
+
+  const msgBytes = felt252ToBytes(recomputed);
+  const ok = cryptoVerify(null, msgBytes, pubkey, sigBytes);
+  if (!ok) {
+    return {
+      valid: false,
+      reason: "signature_invalid",
+      recomputed_cert_hash_felt252: recomputed,
+    };
+  }
+  return { valid: true, recomputed_cert_hash_felt252: recomputed };
+}

package/src/replay/replay.ts

@@ -158,7 +158,7 @@ export interface ReplayRunner {
 export class NonDeterministicReplayError extends Error {
   constructor(
     public readonly stepIndex: number,
-    public readonly reason: string,
+    public readonly reason: string
   ) {
     super(`Non-deterministic replay at step ${stepIndex}: ${reason}`);
     this.name = "NonDeterministicReplayError";
@@ -171,10 +171,7 @@ export class NonDeterministicReplayError extends Error {
  * Compute a step-level diff between two traces.
  * Returns an empty array if the traces are identical at the step level.
  */
-function diffTraces(
-  original: Trace,
-  replayed: Trace,
-): ReplayResult["diff"] {
+function diffTraces(original: Trace, replayed: Trace): ReplayResult["diff"] {
   const diffs: NonNullable<ReplayResult["diff"]> = [];
 
   const minLen = Math.min(original.steps.length, replayed.steps.length);
@@ -223,16 +220,22 @@ export async function replayFrom(
   runId: string,
   loader: ReplayLoader,
   runner: ReplayRunner,
-  opts?: { mode?: ReplayMode; fromStepIndex?: number },
+  opts?: { mode?: ReplayMode; fromStepIndex?: number }
 ): Promise<ReplayResult> {
   const mode = opts?.mode ?? "strict";
 
   // 1. Load original artifacts
-  const [originalTrace, artifacts] = await Promise.all([
+  const [rawTrace, artifacts] = await Promise.all([
     loader.loadOriginalTrace(runId),
     loader.loadCacheEntries(runId),
   ]);
 
+  // Auto-migrate traces recorded under the draft schema to the frozen 1.0.0
+  const originalTrace =
+    (rawTrace.schemaVersion as string) === "0.1.0-draft"
+      ? { ...rawTrace, schemaVersion: "1.0.0" as const }
+      : rawTrace;
+
   // 2. Import concrete implementations lazily to avoid circular references
   const { RecordedClock } = await import("./clock.js");
   const { RecordedRandom } = await import("./random.js");
@@ -241,7 +244,7 @@ export async function replayFrom(
   const random = new RecordedRandom(
     artifacts.recordedNext,
     artifacts.recordedUuids,
-    mode,
+    mode
   );
 
   // 3. Build the replay context