@bratsos/workflow-engine 0.7.0 → 0.8.0

package/skills/workflow-engine/references/10-annotations.md

@@ -0,0 +1,479 @@
+# Annotations — first-class provenance
+
+**Available from v0.8.0.** First-class API for attaching typed key-value facts to runs and stages, so future agents can read a run's history coherently. Inspired by OpenTelemetry semantic conventions.
+
+## When to use
+
+- **Trigger context** at `run.create`: who/what initiated the run, parent runs, source system.
+- **Decision records** inside a stage: outcomes, rationales, evidence, alternatives.
+- **Approvals and reviews**: post-hoc human sign-off, plugin-attributed events.
+- **Anything you'd later want to query by stable key.**
+
+## When *not* to use
+
+- **Time-ordered narrative logs**: use `ctx.log(...)`. Annotations are key-addressable; logs are time-ordered.
+- **State transitions**: the kernel emits `stage:started`/`completed`/`failed` events automatically. Don't duplicate them.
+- **Large rich blobs**: put queryable scalars in `attributes`, attach the blob via the `payload` slot.
+
+## Three call forms
+
+```ts
+// 1. TypedKey form — value type checked against the convention
+import { Decision } from "@bratsos/workflow-engine/conventions";
+
+ctx.annotate(Decision.outcome, "low");
+ctx.annotate(Decision.confidence, 0.42);
+ctx.annotate(Decision.confidence, "high"); // ❌ TS error — expected number
+
+// 2. String key form — escape hatch for custom org keys
+ctx.annotate("acme.compliance.signoff", "alice@acme.com");
+
+// 3. Batch form — shared envelope for many attributes
+ctx.annotate({
+  actor: { kind: "agent", id: "triage-v3", version: "3.0.1" },
+  attributes: {
+    "decision.outcome": "low",
+    "decision.rationale": "AI confidence below threshold",
+    "decision.confidence": 0.42,
+    "decision.alternatives": ["low", "medium", "high"],
+    "decision.used_fallback": true,
+  },
+  payload: { fullModelResponse: { /* opt-in rich blob */ } },
+  idempotencyKey: "decision-stage-1-attempt-0",
+});
+```
+
+All three return `void` — writes are buffered and flushed atomically with the stage outcome. `undefined` values are dropped silently (OTel pattern: `ctx.annotate("x.id", maybeId)` is safe without guards).
+
+## At run creation
+
+```ts
+await kernel.dispatch({
+  type: "run.create",
+  workflowId: "ticket-triage",
+  input: { ticket },
+  annotations: [
+    {
+      actor: { kind: "system", id: "zendesk-integration" },
+      attributes: {
+        "trigger.source": "webhook:zendesk",
+        "trigger.parent_run_id": previousRunId,
+        "trigger.reason": "auto-triage on ticket create",
+      },
+    },
+  ],
+});
+```
+
+Annotations land in the same transaction as `createRun`. If creation fails, no annotations persist.
+
+## External attach (plugins, post-hoc reviews)
+
+```ts
+await kernel.annotations.attach(workflowRunId, {
+  actor: { kind: "user", id: "alice@acme.com" },
+  attributes: { "review.disposition": "approved-anyway" },
+  scope: "run",       // default
+  idempotencyKey: "review-2026-05-24-alice",
+});
+```
+
+Single atomic transaction. With `idempotencyKey`, retries on the same `(runId, key, idempotencyKey)` are silently deduped.
+
+## Query API
+
+```ts
+// Everything attached to a run, ordered by createdAt then id
+await kernel.annotations.list(runId);
+
+// Filters (all AND-combined)
+await kernel.annotations.list(runId, {
+  key: "decision.outcome",        // exact key
+  keyPrefix: "decision.",          // namespace prefix (uses index on Postgres)
+  scope: "stage",                  // "run" | "stage" | custom
+  scopeId: "classify-urgency",
+  actorId: "triage-v3",
+  actorKind: "agent",
+  attempt: 0,
+  since: new Date("2026-05-20T00:00:00Z"),
+  until: new Date("2026-05-25T00:00:00Z"),
+  limit: 100,                      // default 1000
+});
+```
+
+### Cross-DB notes
+
+- **Postgres**: `keyPrefix` uses the `(workflowRunId, key)` btree index (LIKE 'prefix.%' range scan).
+- **SQLite**: same query path; `LIKE` is case-insensitive by default and may scan at scale. The engine convention is lowercase keys, which keeps the scan fast for small-to-mid datasets. For high-volume SQLite, consider Postgres.
+
+Value content is never queryable via the persistence port — only by key. If you need indexed value filtering for a specific attribute, extract that column in your own schema.
+
+## Conventions catalog (v0.8)
+
+Importable from `@bratsos/workflow-engine/conventions`. All `stable` unless noted.
+
+### `Trigger.*`
+
+What initiated the run. Attach at `run.create`.
+
+| Key | Value type | Description |
+|---|---|---|
+| `trigger.source` | `string` | What system or path initiated the run, e.g. `"webhook:zendesk"`, `"manual:cli"`, `"schedule:cron"` |
+| `trigger.parent_run_id` | `string` | Run ID of the prior run when this is a follow-up |
+| `trigger.reason` | `string` | Free-text rationale for triggering this run |
+| `trigger.actor.kind` | `string` | Recommended: `"user"` / `"agent"` / `"system"`. Open string. |
+| `trigger.actor.id` | `string` | Stable identifier for the triggering actor |
+
+### `Decision.*`
+
+Choices made during execution. Attach from inside a stage.
+
+| Key | Value type | Description |
+|---|---|---|
+| `decision.outcome` | `unknown` | The chosen outcome. Consumer-defined shape. |
+| `decision.rationale` | `string` | Human-readable reason |
+| `decision.confidence` | `number` | Confidence score, typically 0–1 |
+| `decision.alternatives` | `unknown[]` | Alternatives that were considered but not selected |
+| `decision.used_fallback` | `boolean` | Whether a fallback heuristic was used (experimental) |
+
+### `Approval.*`
+
+Sign-off events. Pluralization rule: `approvers` is always an array.
+
+| Key | Value type | Description |
+|---|---|---|
+| `approval.approvers` | `string[]` | All approvers; always an array, `["alice"]` for one |
+| `approval.timestamp` | `string` | ISO 8601 timestamp |
+| `approval.policy.version` | `string` | Policy version (experimental) |
+
+### `Revision.*`
+
+This run as a revision of a prior run.
+
+| Key | Value type | Description |
+|---|---|---|
+| `revision.previous_run_id` | `string` | Run ID this revision supersedes |
+| `revision.reason` | `string` | Why this revision was created |
+
+## Naming rules for custom keys
+
+- Lowercase, dot-delimited segments, underscores within a segment OK.
+- Org-prefixed for custom keys: `acme.compliance.signoff`, not `compliance.signoff`.
+- Pluralization rule (OTel): singular name = scalar value; plural name = array value. So `approval.approvers: string[]` always, even with one approver.
+- Three-segment structure preferred: `namespace.noun.qualifier`.
+
+## Migration from `WorkflowRun.metadata`
+
+The `metadata` parameter on `RunCreateCommand` is `@deprecated` in 0.8 and will be removed in 1.0. Existing rows with `WorkflowRun.metadata` populated are automatically projected as virtual `legacy.metadata.*` annotations when you call `kernel.annotations.list(runId)`:
+
+```ts
+// Run was created with:
+//   metadata: { tenantId: "acme", source: "webhook" }
+
+await kernel.annotations.list(runId);
+// → [
+//     { key: "legacy.metadata.source", value: "webhook", scope: "run", ... },
+//     { key: "legacy.metadata.tenantId", value: "acme", scope: "run", ... },
+//   ]
+```
+
+No dual-write — the column remains source of truth for legacy rows. If you want to explicitly migrate a row, attach the keys yourself and the shim stops projecting:
+
+```ts
+await kernel.annotations.attach(runId, {
+  attributes: { "legacy.metadata.tenantId": "acme" },
+});
+```
+
+## Annotation vs log vs outbox — decision matrix
+
+A fresh agent dropped into a workflow will mis-classify if they don't internalize this:
+
+| You want to record... | Use | Why |
+|---|---|---|
+| Time-ordered narrative for debugging | `ctx.log("INFO", "msg", { meta })` | Logs are streams; `metadata` is per-line context, not indexed by key |
+| A state transition (started/completed/failed/suspended) | Don't — kernel emits the outbox event for you | Don't duplicate kernel-emitted facts |
+| A decision the agent made (outcome, rationale, evidence, alternatives) | `ctx.annotate(Decision.*, ...)` | Key-addressable, queryable across runs, atomic with stage outcome |
+| Who/what triggered the run | `run.create` with `annotations: [{ "trigger.*": ... }]` | Atomic with run creation, queryable later |
+| Post-hoc human action on a run (approval, override, review note) | `kernel.annotations.attach(...)` | Single transaction, idempotent retries |
+| The actual stage output (what downstream stages consume) | `return { output: ... }` | Outputs are the contract between stages; annotations are out-of-band |
+| Large blob (full model response, debug trace) | `ctx.annotate({ attributes, payload: { ... } })` | `payload` is not indexed but lives alongside the queryable attributes |
+| A workflow-level artifact (file, embedding, generated content) | `ctx.storage.save(key, data)` | Artifacts live in the BlobStore; annotations are for labels/facts about them |
+
+**Rule of thumb**: if you'd want to filter or query by it across runs, it's an annotation. If it's a story being told in order, it's a log. If it's a state transition, the kernel handles it.
+
+## Query patterns
+
+These are the queries most consumers and future agents actually want to run.
+
+### Timeline reconstruction — "what happened in this run, in order?"
+
+```ts
+const timeline = await kernel.annotations.list(runId);
+// Already sorted by createdAt then id — stable across calls.
+
+for (const a of timeline) {
+  console.log(
+    `[${a.createdAt.toISOString()}] ` +
+    `${a.actorKind ?? "?"}:${a.actorId ?? "?"} → ` +
+    `${a.key} = ${JSON.stringify(a.value)}`,
+  );
+}
+```
+
+### Decision audit — "what decisions did the triage agent make?"
+
+```ts
+const decisions = await kernel.annotations.list(runId, {
+  keyPrefix: "decision.",
+  actorId: "triage-agent",
+});
+```
+
+### Who-did-what across one run
+
+```ts
+const trail = await kernel.annotations.list(runId, {
+  actorId: "compliance-agent-v2",
+});
+// Group by stage:
+const byStage = new Map<string, typeof trail>();
+for (const a of trail) {
+  const k = a.scopeId ?? "<run>";
+  byStage.set(k, [...(byStage.get(k) ?? []), a]);
+}
+```
+
+### Walking a chain of runs via `trigger.parent_run_id`
+
+```ts
+async function findChainRoot(runId: string): Promise<string> {
+  const trigger = await kernel.annotations.list(runId, {
+    key: "trigger.parent_run_id",
+    limit: 1,
+  });
+  const parent = trigger[0]?.value as string | undefined;
+  return parent ? findChainRoot(parent) : runId;
+}
+```
+
+### Recent annotations only
+
+```ts
+const lastHour = await kernel.annotations.list(runId, {
+  since: new Date(Date.now() - 60 * 60 * 1000),
+});
+```
+
+## Patterns for structured decision provenance
+
+The minimal-but-useful "decision" annotation shape, derived from agent-orchestration use cases:
+
+```ts
+ctx.annotate({
+  actor: { kind: "agent", id: "triage", version: "v3" },
+  attributes: {
+    "decision.outcome": chosen,                     // the answer
+    "decision.rationale": explanation,              // why
+    "decision.confidence": score,                   // 0–1
+    "decision.alternatives": alternativesConsidered,// what else was on the table
+    "decision.used_fallback": ranKeywordFallback,   // did we use the primary signal?
+  },
+  payload: {
+    rawAIResponse: fullModelOutput,                  // the evidence
+  },
+});
+```
+
+Why each field earns its place:
+- `outcome`: queryable. Lets you ask "how many runs decided X?"
+- `rationale`: human-readable; what a human reviewer or future agent reads first.
+- `confidence`: lets you find low-confidence decisions to spot-check.
+- `alternatives`: makes the decision space visible — "we considered X, picked Y." Plural per OTel rule.
+- `used_fallback`: cheap boolean for filtering all fallback paths.
+- `payload.rawAIResponse`: the evidence trail without polluting the queryable layer.
+
+## Testing annotations
+
+The in-memory persistence adapter exposes a test helper for asserting on writes:
+
+```ts
+import { InMemoryWorkflowPersistence } from "@bratsos/workflow-engine/testing";
+
+const persistence = new InMemoryWorkflowPersistence();
+// ... drive your workflow ...
+
+const annotations = persistence.getAllAnnotations();
+expect(annotations).toContainEqual(
+  expect.objectContaining({
+    key: "decision.outcome",
+    value: "low",
+    scope: "stage",
+    scopeId: "classify-urgency",
+  }),
+);
+```
+
+Or via the public query API:
+
+```ts
+const decisions = await kernel.annotations.list(runId, {
+  keyPrefix: "decision.",
+});
+expect(decisions).toHaveLength(3);
+```
+
+Annotations are flushed inside the stage-completion transaction. In tests this means: after `kernel.dispatch({ type: "job.execute", ... })` returns, all annotations written via `ctx.annotate` are persisted and queryable.
+
+## Common pitfalls
+
+### Don't put high-cardinality values in keys
+
+```ts
+// ❌ Wrong — every unique run gets its own key
+ctx.annotate(`decision.outcome.${runId}`, "low");
+
+// ✅ Right — the key is stable; the value carries the variance
+ctx.annotate("decision.outcome", "low");
+```
+
+The unique constraint and `(workflowRunId, key)` index only help when keys repeat. A key per run defeats the design.
+
+### Don't annotate state transitions
+
+```ts
+// ❌ Wrong — kernel already emits this as an outbox event
+ctx.annotate("stage.completed", true);
+
+// ✅ Right — annotate the *content* of what was decided, not the fact that the stage ran
+ctx.annotate("decision.outcome", "low");
+```
+
+`stage:started` / `stage:completed` / `stage:failed` / `stage:suspended` are kernel-emitted outbox events. Duplicating them in annotations clutters queries.
+
+### Don't write annotations from outside the kernel's transactional boundary
+
+```ts
+// ❌ Wrong — bypasses transactional semantics, no atomicity with stage outcome
+await persistence.appendAnnotations([{ ... }]);
+
+// ✅ Right — let the kernel handle it
+ctx.annotate(...);
+// or for plugin / external attach:
+await kernel.annotations.attach(runId, { ... });
+```
+
+Calling `persistence.appendAnnotations` directly bypasses the buffer-and-flush guarantee. Annotations could persist while the stage rolls back, or vice versa.
+
+### Don't use `value` as a blob slot
+
+```ts
+// ❌ Wrong — defeats key-prefix querying, breaks cross-DB indexing
+ctx.annotate("decision", {
+  outcome: "low",
+  evidence: { /* large nested object */ },
+});
+
+// ✅ Right — scalars in `value`, blobs in `payload`
+ctx.annotate({
+  attributes: {
+    "decision.outcome": "low",
+  },
+  payload: { evidence: { /* large nested object */ } },
+});
+```
+
+The `value` column is indexed and meant for scalars/arrays. The `payload` column is the explicit blob slot.
+
+### Don't use `idempotencyKey` for stage-scope annotations
+
+```ts
+// ❌ Unnecessary — stage annotations are already atomic with stage outcome
+ctx.annotate({
+  attributes: { "decision.outcome": "low" },
+  idempotencyKey: "stage-1-decision",  // redundant; stage outcome handles it
+});
+
+// ✅ Right — reserve idempotencyKey for external attach and run.create
+await kernel.annotations.attach(runId, {
+  attributes: { "review.disposition": "approved" },
+  idempotencyKey: "review-2026-05-24-alice",
+});
+```
+
+The buffer-and-flush model makes stage-scope writes inherently atomic. Idempotency keys are for retry-prone *external* paths.
+
+## Best practices
+
+- **Use TypedKeys for well-known concepts**: `ctx.annotate(Decision.outcome, ...)` beats `ctx.annotate("decision.outcome", ...)` because the value type is checked and typos are caught at compile time.
+- **Prefer scalars and scalar arrays in `attributes`**: they're indexable and queryable. Use the `payload` slot for rich blobs.
+- **Set `actor` on every annotation**: the future agent reading this should know who recorded it.
+- **Org-prefix custom keys**: `acme.compliance.signoff`, not `compliance.signoff`. Prevents accidental collisions with future engine conventions.
+- **Use `idempotencyKey` for retry-sensitive paths**: external attach calls especially. Stage-scope annotations don't need it.
+- **Don't annotate state transitions**: the kernel emits outbox events for those.
+- **Keep per-stage annotation counts modest**: a chatty agent writing 100+ annotations per stage will fan out 100+ rows per execution. Aim for a small set of high-signal facts, not full traces.
+- **Use logs for narrative, annotations for facts**: if it has a timestamp and reads as a sentence, it's a log. If it has a key and a typed value, it's an annotation.
+
+## Reruns and the `attempt` axis
+
+`run.rerunFrom` recreates stage records at and after the target group. The engine assigns the new stage records a fresh `attempt` value (one higher than the max attempt across the deleted stages), and `ctx.annotate(...)` inherits that value for the new annotations. Annotations from the prior attempt survive (the FK to the deleted stage record is `SetNull`, preserving the row with its original `attempt` value).
+
+This means a single run's annotations can carry multiple `attempt` values, distinguishing decisions made on different runs of the same logical stage. Filter by `attempt` to look at just one attempt:
+
+```ts
+// Just the most recent attempt
+const latestAttempt = await kernel.annotations.list(runId, { attempt: 1 });
+
+// All attempts in chronological order
+const allAttempts = await kernel.annotations.list(runId, { keyPrefix: "decision." });
+```
+
+## Outbox emission (opt-in)
+
+By default, writing an annotation does **not** emit an outbox event. If a plugin or external system needs push notifications on annotation writes (audit pipelines, SIEM, live dashboards), set `emitEvent: true` and the engine writes an `annotation:created` outbox event in the same transaction as the annotation row.
+
+**Caveat when combining `emitEvent` with `idempotencyKey`:** the engine skips duplicate `(workflowRunId, key, idempotencyKey)` rows under the unique constraint, but emits one `annotation:created` event per input regardless. On a retry with the same idempotency key, the row is deduplicated (correct) but the event fires again. If your downstream consumer cares about exactly-once delivery, dedupe events on `(causationId, key)` or use a stable identifier in the event payload — don't assume one event per persisted row.
+
+```ts
+// Stage-scope
+ctx.annotate("decision.outcome", "low", { emitEvent: true });
+
+// Batch
+ctx.annotate({
+  attributes: { "approval.approvers": ["alice", "bob"] },
+  emitEvent: true,
+});
+
+// External attach
+await kernel.annotations.attach(runId, {
+  attributes: { "review.disposition": "approved" },
+  emitEvent: true,
+});
+
+// At run.create
+annotations: [{
+  attributes: { "trigger.source": "webhook" },
+  emitEvent: true,
+}]
+```
+
+Subscribe via the existing event sink (the kernel routes `annotation:created` events through the same outbox machinery as `stage:completed` etc.):
+
+```ts
+const plugin = definePlugin({
+  id: "annotation-audit",
+  name: "Annotation Audit",
+  on: ["annotation:created"],
+  async handle(event) {
+    // event.key, event.value, event.scope, event.actorId, etc.
+  },
+});
+```
+
+Keep emission off for high-volume runs — every emit-on annotation is one outbox row to flush.
+
+## Cancellation safety
+
+When `run.cancel` commits **before** a stage's Phase 3 (or Phase 2 suspended-poll) transaction begins, the transaction reads the cancelled status from the run, throws, and rolls back atomically — the stage's annotations, status update, and outbox events all roll back together. This closes the common race window where cancel had clearly committed first but the stage was still mid-flight.
+
+There is a residual narrow window where cancel commits **after** the transaction's status check but **before** the transaction commits. Under standard READ COMMITTED isolation the status check is not a row lock, so a concurrent cancel can still slip through that gap. The window is small (microseconds inside a transaction) and applies equally to all Phase 3 writes (stage status, outbox events, annotations) — annotations don't introduce the race, they just inherit it. A future engine release may close this fully via `SELECT ... FOR UPDATE` or coordinated optimistic locking; for now consumers who need stronger cancel atomicity should rely on the kernel's existing ghost-job detection downstream.

package/dist/chunk-2HEV5ZJL.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/persistence/interface.ts"],"names":[],"mappings":";AAkDO,IAAM,iBAAA,GAAN,cAAgC,KAAA,CAAM;AAAA,EAC3C,WAAA,CACkB,MAAA,EACA,EAAA,EACA,QAAA,EACA,MAAA,EAChB;AACA,IAAA,KAAA;AAAA,MACE,oBAAoB,MAAM,CAAA,CAAA,EAAI,EAAE,CAAA,WAAA,EAAc,QAAQ,SAAS,MAAM,CAAA;AAAA,KACvE;AAPgB,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AACA,IAAA,IAAA,CAAA,EAAA,GAAA,EAAA;AACA,IAAA,IAAA,CAAA,QAAA,GAAA,QAAA;AACA,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAKhB,IAAA,IAAA,CAAK,IAAA,GAAO,mBAAA;AAAA,EACd;AACF","file":"chunk-2HEV5ZJL.js","sourcesContent":["/**\n * Persistence Interfaces for Workflow Engine\n *\n * These interfaces abstract database operations to enable:\n * - Testing with mock implementations\n * - Future extraction into @bratsos/workflow-engine package\n * - Alternative database backends\n *\n * Implementations:\n * - PrismaWorkflowPersistence (default, in ./prisma/)\n * - InMemoryPersistence (for testing)\n */\n\n// ============================================================================\n// Unified Status Type\n// ============================================================================\n\n/**\n * Unified status type for workflows, stages, and jobs.\n *\n * - PENDING: Not started yet\n * - RUNNING: Currently executing\n * - SUSPENDED: Paused, waiting for external event (e.g., batch job completion)\n * - COMPLETED: Finished successfully\n * - FAILED: Finished with error\n * - CANCELLED: Manually stopped by user\n * - SKIPPED: Stage-specific - bypassed due to condition\n */\nexport type Status =\n  | \"PENDING\"\n  | \"RUNNING\"\n  | \"SUSPENDED\"\n  | \"COMPLETED\"\n  | \"FAILED\"\n  | \"CANCELLED\"\n  | \"SKIPPED\";\n\n/** @deprecated Use Status instead */\nexport type WorkflowStatus = Status;\n\n/** @deprecated Use Status instead */\nexport type WorkflowStageStatus = Status;\n\n/** @deprecated Use Status instead. Note: PROCESSING is now RUNNING. */\nexport type JobStatus = Status;\n\nexport type LogLevel = \"DEBUG\" | \"INFO\" | \"WARN\" | \"ERROR\";\n\nexport type ArtifactType = \"STAGE_OUTPUT\" | \"ARTIFACT\" | \"METADATA\";\n\nexport class StaleVersionError extends Error {\n  constructor(\n    public readonly entity: string,\n    public readonly id: string,\n    public readonly expected: number,\n    public readonly actual: number,\n  ) {\n    super(\n      `Stale version on ${entity} ${id}: expected ${expected}, got ${actual}`,\n    );\n    this.name = \"StaleVersionError\";\n  }\n}\n\n// ============================================================================\n// Record Types (minimal fields needed by the workflow engine)\n// ============================================================================\n\nexport interface WorkflowRunRecord {\n  id: string;\n  createdAt: Date;\n  updatedAt: Date;\n  version: number;\n  workflowId: string;\n  workflowName: string;\n  workflowType: string;\n  status: WorkflowStatus;\n  startedAt: Date | null;\n  completedAt: Date | null;\n  duration: number | null;\n  input: unknown;\n  output: unknown | null;\n  config: unknown;\n  totalCost: number;\n  totalTokens: number;\n  priority: number;\n  metadata: unknown | null;\n}\n\nexport interface WorkflowStageRecord {\n  id: string;\n  createdAt: Date;\n  updatedAt: Date;\n  version: number;\n  workflowRunId: string;\n  stageId: string;\n  stageName: string;\n  stageNumber: number;\n  executionGroup: number;\n  status: WorkflowStageStatus;\n  startedAt: Date | null;\n  completedAt: Date | null;\n  duration: number | null;\n  inputData: unknown | null;\n  outputData: unknown | null;\n  config: unknown | null;\n  suspendedState: unknown | null;\n  resumeData: unknown | null;\n  nextPollAt: Date | null;\n  pollInterval: number | null;\n  maxWaitUntil: Date | null;\n  metrics: unknown | null;\n  embeddingInfo: unknown | null;\n  errorMessage: string | null;\n}\n\nexport interface WorkflowLogRecord {\n  id: string;\n  createdAt: Date;\n  workflowStageId: string | null;\n  workflowRunId: string | null;\n  level: LogLevel;\n  message: string;\n  metadata: unknown | null;\n}\n\nexport interface WorkflowArtifactRecord {\n  id: string;\n  createdAt: Date;\n  updatedAt: Date;\n  workflowRunId: string;\n  workflowStageId: string | null;\n  key: string;\n  type: ArtifactType;\n  data: unknown;\n  size: number;\n  metadata: unknown | null;\n}\n\n// ============================================================================\n// Outbox and Idempotency Record Types (for kernel transactional outbox)\n// ============================================================================\n\nexport interface OutboxRecord {\n  id: string;\n  workflowRunId: string;\n  sequence: number;\n  eventType: string;\n  payload: unknown;\n  causationId: string;\n  occurredAt: Date;\n  publishedAt: Date | null;\n  retryCount: number;\n  dlqAt: Date | null;\n}\n\nexport interface CreateOutboxEventInput {\n  workflowRunId: string;\n  eventType: string;\n  payload: unknown;\n  causationId: string;\n  occurredAt: Date;\n}\n\nexport interface IdempotencyRecord {\n  key: string;\n  commandType: string;\n  result: unknown;\n  createdAt: Date;\n}\n\n// ============================================================================\n// AI Call Record Types\n// ============================================================================\n\nexport interface AICallRecord {\n  id: string;\n  createdAt: Date;\n  topic: string;\n  callType: string;\n  modelKey: string;\n  modelId: string;\n  prompt: string;\n  response: string;\n  inputTokens: number;\n  outputTokens: number;\n  cost: number;\n  metadata: unknown | null;\n}\n\nexport interface JobRecord {\n  id: string;\n  createdAt: Date;\n  updatedAt: Date;\n  workflowRunId: string;\n  workflowId: string;\n  stageId: string;\n  status: JobStatus;\n  priority: number;\n  workerId: string | null;\n  lockedAt: Date | null;\n  startedAt: Date | null;\n  completedAt: Date | null;\n  attempt: number;\n  maxAttempts: number;\n  lastError: string | null;\n  nextPollAt: Date | null;\n  payload: Record<string, unknown>;\n}\n\n// ============================================================================\n// Input Types (for creating/updating records)\n// ============================================================================\n\nexport interface CreateRunInput {\n  id?: string;\n  workflowId: string;\n  workflowName: string;\n  workflowType: string;\n  input: unknown;\n  config?: unknown;\n  priority?: number;\n  /** Optional metadata stored as JSON on the run record. NOT spread into Prisma fields. */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface UpdateRunInput {\n  status?: WorkflowStatus;\n  startedAt?: Date;\n  completedAt?: Date | null;\n  duration?: number | null;\n  output?: unknown;\n  totalCost?: number;\n  totalTokens?: number;\n  expectedVersion?: number;\n}\n\nexport interface CreateStageInput {\n  workflowRunId: string;\n  stageId: string;\n  stageName: string;\n  stageNumber: number;\n  executionGroup: number;\n  status?: WorkflowStageStatus;\n  startedAt?: Date;\n  config?: unknown;\n  inputData?: unknown;\n}\n\nexport interface UpdateStageInput {\n  status?: WorkflowStageStatus;\n  startedAt?: Date;\n  completedAt?: Date;\n  duration?: number;\n  outputData?: unknown;\n  config?: unknown;\n  suspendedState?: unknown;\n  resumeData?: unknown;\n  nextPollAt?: Date | null;\n  pollInterval?: number;\n  maxWaitUntil?: Date;\n  metrics?: unknown;\n  embeddingInfo?: unknown;\n  artifacts?: unknown;\n  errorMessage?: string;\n  expectedVersion?: number;\n}\n\nexport interface UpsertStageInput {\n  workflowRunId: string;\n  stageId: string;\n  create: CreateStageInput;\n  update: UpdateStageInput;\n}\n\nexport interface CreateLogInput {\n  workflowRunId?: string;\n  workflowStageId?: string;\n  level: LogLevel;\n  message: string;\n  metadata?: unknown;\n}\n\nexport interface SaveArtifactInput {\n  workflowRunId: string;\n  workflowStageId?: string;\n  key: string;\n  type: ArtifactType;\n  data: unknown;\n  size: number;\n  metadata?: unknown;\n}\n\nexport interface CreateAICallInput {\n  topic: string;\n  callType: string;\n  modelKey: string;\n  modelId: string;\n  prompt: string;\n  response: string;\n  inputTokens: number;\n  outputTokens: number;\n  cost: number;\n  metadata?: unknown;\n}\n\nexport interface EnqueueJobInput {\n  workflowRunId: string;\n  workflowId: string;\n  stageId: string;\n  priority?: number;\n  payload?: Record<string, unknown>;\n  scheduledFor?: Date;\n}\n\nexport interface DequeueResult {\n  jobId: string;\n  workflowRunId: string;\n  workflowId: string;\n  stageId: string;\n  priority: number;\n  attempt: number;\n  maxAttempts: number;\n  payload: Record<string, unknown>;\n}\n\n// ============================================================================\n// WorkflowPersistence Interface\n// ============================================================================\n\nexport interface WorkflowPersistence {\n  /** Execute operations within a transaction boundary. */\n  withTransaction<T>(fn: (tx: WorkflowPersistence) => Promise<T>): Promise<T>;\n\n  // WorkflowRun operations\n  createRun(data: CreateRunInput): Promise<WorkflowRunRecord>;\n  updateRun(id: string, data: UpdateRunInput): Promise<void>;\n  getRun(id: string): Promise<WorkflowRunRecord | null>;\n  getRunStatus(id: string): Promise<WorkflowStatus | null>;\n  getRunsByStatus(status: WorkflowStatus): Promise<WorkflowRunRecord[]>;\n  getStuckRuns(stuckSince: Date): Promise<WorkflowRunRecord[]>;\n\n  /**\n   * Atomically claim a pending workflow run for processing.\n   * Uses atomic update with WHERE status = 'PENDING' to prevent race conditions.\n   *\n   * @param id - The workflow run ID to claim\n   * @returns true if successfully claimed, false if already claimed by another worker\n   */\n  claimPendingRun(id: string): Promise<boolean>;\n\n  /**\n   * Atomically find and claim the next pending workflow run.\n   * Uses FOR UPDATE SKIP LOCKED pattern (in Postgres) to prevent race conditions\n   * when multiple workers try to claim workflows simultaneously.\n   *\n   * Priority ordering: higher priority first, then oldest (FIFO within same priority).\n   *\n   * @returns The claimed workflow run (now with status RUNNING), or null if no pending runs\n   */\n  claimNextPendingRun(): Promise<WorkflowRunRecord | null>;\n\n  // WorkflowStage operations\n  createStage(data: CreateStageInput): Promise<WorkflowStageRecord>;\n  upsertStage(data: UpsertStageInput): Promise<WorkflowStageRecord>;\n  updateStage(id: string, data: UpdateStageInput): Promise<void>;\n  updateStageByRunAndStageId(\n    workflowRunId: string,\n    stageId: string,\n    data: UpdateStageInput,\n  ): Promise<void>;\n  getStage(runId: string, stageId: string): Promise<WorkflowStageRecord | null>;\n  getStageById(id: string): Promise<WorkflowStageRecord | null>;\n  getStagesByRun(\n    runId: string,\n    options?: { status?: WorkflowStageStatus; orderBy?: \"asc\" | \"desc\" },\n  ): Promise<WorkflowStageRecord[]>;\n  getSuspendedStages(beforeDate: Date): Promise<WorkflowStageRecord[]>;\n  getFirstSuspendedStageReadyToResume(\n    runId: string,\n  ): Promise<WorkflowStageRecord | null>;\n  getFirstFailedStage(runId: string): Promise<WorkflowStageRecord | null>;\n  getLastCompletedStage(runId: string): Promise<WorkflowStageRecord | null>;\n  getLastCompletedStageBefore(\n    runId: string,\n    executionGroup: number,\n  ): Promise<WorkflowStageRecord | null>;\n  deleteStage(id: string): Promise<void>;\n\n  // WorkflowLog operations\n  createLog(data: CreateLogInput): Promise<void>;\n\n  // WorkflowArtifact operations (for StageStorage)\n  saveArtifact(data: SaveArtifactInput): Promise<void>;\n  loadArtifact(runId: string, key: string): Promise<unknown>;\n  hasArtifact(runId: string, key: string): Promise<boolean>;\n  deleteArtifact(runId: string, key: string): Promise<void>;\n  listArtifacts(runId: string): Promise<WorkflowArtifactRecord[]>;\n  getStageIdForArtifact(runId: string, stageId: string): Promise<string | null>;\n\n  // Stage output convenience methods (replaces separate StageStorage)\n  saveStageOutput(\n    runId: string,\n    workflowType: string,\n    stageId: string,\n    output: unknown,\n  ): Promise<string>;\n\n  // Outbox DLQ operations\n  /** Increment retry count for a failed outbox event. Returns new count. */\n  incrementOutboxRetryCount(id: string): Promise<number>;\n\n  /** Move an outbox event to DLQ (sets dlqAt). */\n  moveOutboxEventToDLQ(id: string): Promise<void>;\n\n  /** Reset DLQ events so they can be reprocessed by outbox.flush. Returns count reset. */\n  replayDLQEvents(maxEvents: number): Promise<number>;\n\n  // Outbox operations\n  /** Write events to the outbox. Sequences are auto-assigned per workflowRunId. */\n  appendOutboxEvents(events: CreateOutboxEventInput[]): Promise<void>;\n\n  /** Read unpublished events ordered by (workflowRunId, sequence). */\n  getUnpublishedOutboxEvents(limit?: number): Promise<OutboxRecord[]>;\n\n  /** Mark events as published. */\n  markOutboxEventsPublished(ids: string[]): Promise<void>;\n\n  // Idempotency operations\n  /** Atomically acquire an idempotency key for command execution. */\n  acquireIdempotencyKey(\n    key: string,\n    commandType: string,\n  ): Promise<\n    | { status: \"acquired\" }\n    | { status: \"replay\"; result: unknown }\n    | { status: \"in_progress\" }\n  >;\n\n  /** Mark an idempotency key as completed and cache the command result. */\n  completeIdempotencyKey(\n    key: string,\n    commandType: string,\n    result: unknown,\n  ): Promise<void>;\n\n  /** Release an in-progress idempotency key after command failure. */\n  releaseIdempotencyKey(key: string, commandType: string): Promise<void>;\n}\n\n// ============================================================================\n// AICallLogger Interface\n// ============================================================================\n\nexport interface AIHelperStats {\n  totalCalls: number;\n  totalInputTokens: number;\n  totalOutputTokens: number;\n  totalCost: number;\n  perModel: Record<\n    string,\n    { calls: number; inputTokens: number; outputTokens: number; cost: number }\n  >;\n}\n\nexport interface AICallLogger {\n  /**\n   * Log a single AI call (fire and forget)\n   */\n  logCall(call: CreateAICallInput): void;\n\n  /**\n   * Log batch results (for recording batch API results)\n   */\n  logBatchResults(batchId: string, results: CreateAICallInput[]): Promise<void>;\n\n  /**\n   * Get aggregated stats for a topic prefix\n   */\n  getStats(topicPrefix: string): Promise<AIHelperStats>;\n\n  /**\n   * Check if batch results are already recorded\n   */\n  isRecorded(batchId: string): Promise<boolean>;\n}\n\n// ============================================================================\n// JobQueue Interface\n// ============================================================================\n\nexport interface JobQueue {\n  /**\n   * Add a new job to the queue\n   */\n  enqueue(options: EnqueueJobInput): Promise<string>;\n\n  /**\n   * Enqueue multiple stages in parallel (same execution group)\n   */\n  enqueueParallel(jobs: EnqueueJobInput[]): Promise<string[]>;\n\n  /**\n   * Atomically dequeue the next available job\n   */\n  dequeue(): Promise<DequeueResult | null>;\n\n  /**\n   * Mark job as completed\n   */\n  complete(jobId: string): Promise<void>;\n\n  /**\n   * Mark job as suspended (for async-batch)\n   */\n  suspend(jobId: string, nextPollAt: Date): Promise<void>;\n\n  /**\n   * Mark job as failed\n   */\n  fail(jobId: string, error: string, shouldRetry?: boolean): Promise<void>;\n\n  /**\n   * Get suspended jobs that are ready to be checked\n   */\n  getSuspendedJobsReadyToPoll(): Promise<\n    Array<{ jobId: string; stageId: string; workflowRunId: string }>\n  >;\n\n  /**\n   * Release stale locks (for crashed workers)\n   */\n  releaseStaleJobs(staleThresholdMs?: number): Promise<number>;\n\n  /**\n   * Cancel all pending/suspended jobs for a workflow run.\n   * Returns count of cancelled jobs.\n   */\n  cancelByRun(workflowRunId: string): Promise<number>;\n}\n\n// ============================================================================\n// Default Implementations (lazy loaded to avoid circular deps)\n// ============================================================================\n\n// Re-export from prisma implementations for convenience\n// These will be the default implementations used when no custom persistence is provided\n"]}