@bratsos/workflow-engine 0.7.0 → 0.8.0

package/dist/conventions/index.js

@@ -0,0 +1,95 @@
+// src/conventions/index.ts
+function typedKey(key, meta) {
+  return {
+    key,
+    stability: meta?.stability ?? "experimental",
+    description: meta?.description
+  };
+}
+var Trigger = {
+  /** What system or path initiated the run, e.g. `"webhook:zendesk"`, `"manual:cli"`, `"schedule:cron"`. */
+  source: typedKey("trigger.source", {
+    stability: "stable",
+    description: "What system or path initiated this run."
+  }),
+  /** Run ID of the prior run when this run is a follow-up / retry / chained execution. */
+  parentRunId: typedKey("trigger.parent_run_id", {
+    stability: "stable",
+    description: "Run ID of the prior run when this is a follow-up."
+  }),
+  /** Free-text reason — `"auto-triage on ticket create"`, `"manual rerun after policy change"`, etc. */
+  reason: typedKey("trigger.reason", {
+    stability: "stable",
+    description: "Free-text rationale for triggering this run."
+  }),
+  /** Actor kind discriminator — recommended values: `"user"`, `"agent"`, `"system"`. Open string. */
+  actorKind: typedKey("trigger.actor.kind", {
+    stability: "stable",
+    description: "Open string. Recommended: 'user' | 'agent' | 'system'. Use the envelope `actor.kind` for the equivalent on stage-scope annotations."
+  }),
+  /** Stable identifier for the actor — user email, agent name, service identifier. */
+  actorId: typedKey("trigger.actor.id", {
+    stability: "stable",
+    description: "Stable identifier for the triggering actor."
+  })
+};
+var Decision = {
+  /** The chosen outcome. Shape is consumer-defined; `unknown` here for flexibility. */
+  outcome: typedKey("decision.outcome", {
+    stability: "stable",
+    description: "The chosen outcome of this decision. Shape is consumer-defined."
+  }),
+  /** Free-text rationale — why the agent picked this outcome. */
+  rationale: typedKey("decision.rationale", {
+    stability: "stable",
+    description: "Human-readable reason for the decision."
+  }),
+  /** Confidence score, typically `0`–`1`. */
+  confidence: typedKey("decision.confidence", {
+    stability: "stable",
+    description: "Confidence score for the decision, typically 0\u20131."
+  }),
+  /** Alternative outcomes that were considered but not selected. */
+  alternatives: typedKey("decision.alternatives", {
+    stability: "stable",
+    description: "Alternative outcomes considered but not selected."
+  }),
+  /** Whether a fallback heuristic was used (e.g., AI confidence below threshold). */
+  usedFallback: typedKey("decision.used_fallback", {
+    stability: "experimental",
+    description: "Whether the agent fell back to a heuristic after the primary signal was inconclusive."
+  })
+};
+var Approval = {
+  /** Identifiers of all approvers. Always an array — `["alice"]` for a single approver. */
+  approvers: typedKey("approval.approvers", {
+    stability: "stable",
+    description: "Identifiers of all approvers (always an array, plural-rule)."
+  }),
+  /** When the approval was recorded. ISO 8601. */
+  timestamp: typedKey("approval.timestamp", {
+    stability: "stable",
+    description: "ISO 8601 timestamp when approval was recorded."
+  }),
+  /** Version of the policy the approval was checked against. */
+  policyVersion: typedKey("approval.policy.version", {
+    stability: "experimental",
+    description: "Version of the policy the approval was checked against."
+  })
+};
+var Revision = {
+  /** Run ID this revision supersedes. */
+  previousRunId: typedKey("revision.previous_run_id", {
+    stability: "stable",
+    description: "Run ID this revision explicitly supersedes."
+  }),
+  /** Why this revision was created. */
+  reason: typedKey("revision.reason", {
+    stability: "stable",
+    description: "Why this revision was created."
+  })
+};
+
+export { Approval, Decision, Revision, Trigger, typedKey };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/conventions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/conventions/index.ts"],"names":[],"mappings":";AA2CO,SAAS,QAAA,CACd,KACA,IAAA,EACa;AACb,EAAA,OAAO;AAAA,IACL,GAAA;AAAA,IACA,SAAA,EAAW,MAAM,SAAA,IAAa,cAAA;AAAA,IAC9B,aAAa,IAAA,EAAM;AAAA,GACrB;AACF;AAYO,IAAM,OAAA,GAAU;AAAA;AAAA,EAErB,MAAA,EAAQ,SAAiB,gBAAA,EAAkB;AAAA,IACzC,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACd,CAAA;AAAA;AAAA,EAGD,WAAA,EAAa,SAAiB,uBAAA,EAAyB;AAAA,IACrD,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACd,CAAA;AAAA;AAAA,EAGD,MAAA,EAAQ,SAAiB,gBAAA,EAAkB;AAAA,IACzC,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACd,CAAA;AAAA;AAAA,EAGD,SAAA,EAAW,SAAiB,oBAAA,EAAsB;AAAA,IAChD,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EACE;AAAA,GACH,CAAA;AAAA;AAAA,EAGD,OAAA,EAAS,SAAiB,kBAAA,EAAoB;AAAA,IAC5C,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACd;AACH;AAaO,IAAM,QAAA,GAAW;AAAA;AAAA,EAEtB,OAAA,EAAS,SAAkB,kBAAA,EAAoB;AAAA,IAC7C,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EACE;AAAA,GACH,CAAA;AAAA;AAAA,EAGD,SAAA,EAAW,SAAiB,oBAAA,EAAsB;AAAA,IAChD,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACd,CAAA;AAAA;AAAA,EAGD,UAAA,EAAY,SAAiB,qBAAA,EAAuB;AAAA,IAClD,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACd,CAAA;AAAA;AAAA,EAGD,YAAA,EAAc,SAAoB,uBAAA,EAAyB;AAAA,IACzD,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACd,CAAA;AAAA;AAAA,EAGD,YAAA,EAAc,SAAkB,wBAAA,EAA0B;AAAA,IACxD,SAAA,EAAW,cAAA;AAAA,IACX,WAAA,EACE;AAAA,GACH;AACH;AAYO,IAAM,QAAA,GAAW;AAAA;AAAA,EAEtB,SAAA,EAAW,SAAmB,oBAAA,EAAsB;AAAA,IAClD,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACd,CAAA;AAAA;AAAA,EAGD,SAAA,EAAW,SAAiB,oBAAA,EAAsB;AAAA,IAChD,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACd,CAAA;AAAA;AAAA,EAGD,aAAA,EAAe,SAAiB,yBAAA,EAA2B;AAAA,IACzD,SAAA,EAAW,cAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACd;AACH;AAcO,IAAM,QAAA,GAAW;AAAA;AAAA,EAEtB,aAAA,EAAe,SAAiB,0BAAA,EAA4B;AAAA,IAC1D,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACd,CAAA;AAAA;AAAA,EAGD,MAAA,EAAQ,SAAiB,iBAAA,EAAmB;AAAA,IAC1C,SAAA,EAAW,QAAA;AAAA,IACX,WAAA,EAAa;AAAA,GACd;AACH","file":"index.js","sourcesContent":["/**\n * @bratsos/workflow-engine/conventions\n *\n * Well-known annotation keys for common provenance scenarios — trigger\n * context, decisions, approvals, revisions. Inspired by OpenTelemetry\n * semantic conventions: dot-namespaced flat keys, value type linked to\n * the key via TypeScript phantom-type inference.\n *\n * ## Usage\n *\n * ```ts\n * import { Trigger, Decision } from \"@bratsos/workflow-engine/conventions\";\n *\n * // Type-checked: value must match the TypedKey<T> parameter.\n * ctx.annotate(Decision.outcome, \"low\");\n * ctx.annotate(Decision.confidence, 0.42);\n * ctx.annotate(Decision.confidence, \"high\"); // ❌ TS error\n *\n * // Custom org-defined keys keep working with the string form:\n * ctx.annotate(\"acme.compliance.signoff\", \"alice@acme.com\");\n * ```\n *\n * ## Versioning policy\n *\n * - Keys are **immutable once `stable`**. Additions only.\n * - Renames and value-type changes ship as **new keys**; the old key\n *   gets a `@deprecated` JSDoc tag.\n * - We deliberately do **not** copy OpenTelemetry's\n *   `OTEL_SEMCONV_STABILITY_OPT_IN` env-var dance — versioning is\n *   handled through semver and JSDoc.\n *\n * See `src/conventions/README.md` for the full policy.\n */\n\nimport type { Stability, TypedKey } from \"../core/stage\";\n\nexport type { Stability, TypedKey } from \"../core/stage\";\n\n/**\n * Define a well-known annotation key. The value-type parameter `T` is\n * phantom — never set at runtime, used only for TypeScript inference\n * when the key is passed to `ctx.annotate(key, value)`.\n */\nexport function typedKey<T = unknown>(\n  key: string,\n  meta?: { stability?: Stability; description?: string },\n): TypedKey<T> {\n  return {\n    key,\n    stability: meta?.stability ?? \"experimental\",\n    description: meta?.description,\n  };\n}\n\n// ============================================================================\n// Trigger — what initiated the run\n// ============================================================================\n\n/**\n * Trigger conventions describe how a workflow run was initiated:\n * caller identity, source system, parent run, free-text reason.\n *\n * Attach at `run.create` time via the `annotations` parameter.\n */\nexport const Trigger = {\n  /** What system or path initiated the run, e.g. `\"webhook:zendesk\"`, `\"manual:cli\"`, `\"schedule:cron\"`. */\n  source: typedKey<string>(\"trigger.source\", {\n    stability: \"stable\",\n    description: \"What system or path initiated this run.\",\n  }),\n\n  /** Run ID of the prior run when this run is a follow-up / retry / chained execution. */\n  parentRunId: typedKey<string>(\"trigger.parent_run_id\", {\n    stability: \"stable\",\n    description: \"Run ID of the prior run when this is a follow-up.\",\n  }),\n\n  /** Free-text reason — `\"auto-triage on ticket create\"`, `\"manual rerun after policy change\"`, etc. */\n  reason: typedKey<string>(\"trigger.reason\", {\n    stability: \"stable\",\n    description: \"Free-text rationale for triggering this run.\",\n  }),\n\n  /** Actor kind discriminator — recommended values: `\"user\"`, `\"agent\"`, `\"system\"`. Open string. */\n  actorKind: typedKey<string>(\"trigger.actor.kind\", {\n    stability: \"stable\",\n    description:\n      \"Open string. Recommended: 'user' | 'agent' | 'system'. Use the envelope `actor.kind` for the equivalent on stage-scope annotations.\",\n  }),\n\n  /** Stable identifier for the actor — user email, agent name, service identifier. */\n  actorId: typedKey<string>(\"trigger.actor.id\", {\n    stability: \"stable\",\n    description: \"Stable identifier for the triggering actor.\",\n  }),\n} as const;\n\n// ============================================================================\n// Decision — choices made during execution\n// ============================================================================\n\n/**\n * Decision conventions describe choices an agent or stage made\n * during execution: the chosen outcome, the reasoning, evidence,\n * alternatives that were considered.\n *\n * Attach from inside `ctx.annotate(...)` within a stage's `execute()`.\n */\nexport const Decision = {\n  /** The chosen outcome. Shape is consumer-defined; `unknown` here for flexibility. */\n  outcome: typedKey<unknown>(\"decision.outcome\", {\n    stability: \"stable\",\n    description:\n      \"The chosen outcome of this decision. Shape is consumer-defined.\",\n  }),\n\n  /** Free-text rationale — why the agent picked this outcome. */\n  rationale: typedKey<string>(\"decision.rationale\", {\n    stability: \"stable\",\n    description: \"Human-readable reason for the decision.\",\n  }),\n\n  /** Confidence score, typically `0`–`1`. */\n  confidence: typedKey<number>(\"decision.confidence\", {\n    stability: \"stable\",\n    description: \"Confidence score for the decision, typically 0–1.\",\n  }),\n\n  /** Alternative outcomes that were considered but not selected. */\n  alternatives: typedKey<unknown[]>(\"decision.alternatives\", {\n    stability: \"stable\",\n    description: \"Alternative outcomes considered but not selected.\",\n  }),\n\n  /** Whether a fallback heuristic was used (e.g., AI confidence below threshold). */\n  usedFallback: typedKey<boolean>(\"decision.used_fallback\", {\n    stability: \"experimental\",\n    description:\n      \"Whether the agent fell back to a heuristic after the primary signal was inconclusive.\",\n  }),\n} as const;\n\n// ============================================================================\n// Approval — sign-off events\n// ============================================================================\n\n/**\n * Approval conventions describe sign-off events on runs or stages.\n * Pluralization follows the OTel rule: `approvers` is plural because a\n * single approval can have multiple approvers; the value type is\n * always `string[]`, even with one approver.\n */\nexport const Approval = {\n  /** Identifiers of all approvers. Always an array — `[\"alice\"]` for a single approver. */\n  approvers: typedKey<string[]>(\"approval.approvers\", {\n    stability: \"stable\",\n    description: \"Identifiers of all approvers (always an array, plural-rule).\",\n  }),\n\n  /** When the approval was recorded. ISO 8601. */\n  timestamp: typedKey<string>(\"approval.timestamp\", {\n    stability: \"stable\",\n    description: \"ISO 8601 timestamp when approval was recorded.\",\n  }),\n\n  /** Version of the policy the approval was checked against. */\n  policyVersion: typedKey<string>(\"approval.policy.version\", {\n    stability: \"experimental\",\n    description: \"Version of the policy the approval was checked against.\",\n  }),\n} as const;\n\n// ============================================================================\n// Revision — chained/related runs\n// ============================================================================\n\n/**\n * Revision conventions describe a run as a revision of a prior run:\n * a deliberate redo, a corrected attempt, a manual override.\n *\n * Distinct from `Trigger.parentRunId` — that's any causal parent\n * (including independent follow-ups), revision is specifically\n * \"this run supersedes that one.\"\n */\nexport const Revision = {\n  /** Run ID this revision supersedes. */\n  previousRunId: typedKey<string>(\"revision.previous_run_id\", {\n    stability: \"stable\",\n    description: \"Run ID this revision explicitly supersedes.\",\n  }),\n\n  /** Why this revision was created. */\n  reason: typedKey<string>(\"revision.reason\", {\n    stability: \"stable\",\n    description: \"Why this revision was created.\",\n  }),\n} as const;\n"]}

package/dist/{events-D_P24UaY.d.ts → events-B3XPPu0c.d.ts}

@@ -97,8 +97,30 @@ interface StageProgressEvent {
     readonly message: string;
     readonly details?: Record<string, unknown>;
 }
+/**
+ * Emitted when an annotation is written with `emitEvent: true`. Lets
+ * plugins and external systems react to provenance writes in real time
+ * (audit pipelines, SIEM, live dashboards) without polling
+ * `kernel.annotations.list`.
+ *
+ * Off by default — annotations are primarily a queryable provenance
+ * surface, not an event stream. Most consumers won't need this.
+ */
+interface AnnotationCreatedEvent {
+    readonly type: "annotation:created";
+    readonly timestamp: Date;
+    readonly workflowRunId: string;
+    readonly key: string;
+    readonly value: unknown;
+    readonly scope: string;
+    readonly scopeId?: string;
+    readonly attempt?: number;
+    readonly actorKind?: string;
+    readonly actorId?: string;
+    readonly actorVersion?: string;
+}
 /** Discriminated union of every kernel event. */
-type KernelEvent = WorkflowCreatedEvent | WorkflowStartedEvent | WorkflowCompletedEvent | WorkflowFailedEvent | WorkflowCancelledEvent | WorkflowSuspendedEvent | StageStartedEvent | StageCompletedEvent | StageSuspendedEvent | StageFailedEvent | StageProgressEvent;
+type KernelEvent = WorkflowCreatedEvent | WorkflowStartedEvent | WorkflowCompletedEvent | WorkflowFailedEvent | WorkflowCancelledEvent | WorkflowSuspendedEvent | StageStartedEvent | StageCompletedEvent | StageSuspendedEvent | StageFailedEvent | StageProgressEvent | AnnotationCreatedEvent;
 /** String literal union of all kernel event type discriminants. */
 type KernelEventType = KernelEvent["type"];
 

package/dist/{index-aNuJ2QgN.d.ts → index-CL0KmlyW.d.ts}

@@ -1,4 +1,4 @@
-import { A as AICallLogger, g as CreateAICallInput, h as AIHelperStats, l as WorkflowPersistence, C as CreateRunInput, W as WorkflowRunRecord, U as UpdateRunInput, m as WorkflowStatus, a as CreateStageInput, b as WorkflowStageRecord, c as UpsertStageInput, d as UpdateStageInput, n as WorkflowStageStatus, e as CreateLogInput, o as SaveArtifactInput, p as WorkflowArtifactRecord, f as CreateOutboxEventInput, O as OutboxRecord, J as JobQueue, E as EnqueueJobInput, D as DequeueResult } from './interface-BeEPzTFy.js';
+import { k as AICallLogger, l as CreateAICallInput, m as AIHelperStats, q as WorkflowPersistence, C as CreateRunInput, W as WorkflowRunRecord, U as UpdateRunInput, r as WorkflowStatus, a as CreateStageInput, b as WorkflowStageRecord, c as UpsertStageInput, d as UpdateStageInput, s as WorkflowStageStatus, e as CreateLogInput, t as SaveArtifactInput, u as WorkflowArtifactRecord, f as CreateAnnotationInput, A as AnnotationFilters, g as WorkflowAnnotationRecord, h as CreateOutboxEventInput, O as OutboxRecord, J as JobQueue, E as EnqueueJobInput, D as DequeueResult } from './interface-BPz138Hf.js';
 
 /**
  * PrismaAICallLogger - Prisma implementation of AICallLogger
@@ -109,6 +109,9 @@ declare class PrismaWorkflowPersistence implements WorkflowPersistence {
     deleteArtifact(runId: string, key: string): Promise<void>;
     listArtifacts(runId: string): Promise<WorkflowArtifactRecord[]>;
     getStageIdForArtifact(runId: string, stageId: string): Promise<string | null>;
+    appendAnnotations(inputs: CreateAnnotationInput[]): Promise<void>;
+    listAnnotations(workflowRunId: string, filters?: AnnotationFilters): Promise<WorkflowAnnotationRecord[]>;
+    private mapWorkflowAnnotation;
     saveStageOutput(runId: string, workflowType: string, stageId: string, output: unknown): Promise<string>;
     appendOutboxEvents(events: CreateOutboxEventInput[]): Promise<void>;
     getUnpublishedOutboxEvents(limit?: number): Promise<OutboxRecord[]>;

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-import { M as ModelKey } from './client-DYs5wlHp.js';
-export { A as AIBatch, a as AIBatchHandle, b as AIBatchProvider, c as AIBatchRequest, d as AIBatchResult, e as AICallType, f as AIEmbedResult, g as AIHelper, h as AIObjectResult, i as AIStreamResult, j as AITextResult, k as AVAILABLE_MODELS, l as AsyncBatchStageDefinition, B as BatchLogFn, D as DEFAULT_MODEL_KEY, E as EmbedOptions, m as EnhancedStageContext, I as InferInput, L as LogContext, n as ModelConfig, o as ModelRegistry, p as ModelStats, q as ModelStatsTracker, r as ModelSyncConfig, N as NoInputSchema, O as ObjectOptions, R as RecordCallParams, S as SimpleStageResult, s as StreamOptions, t as SyncStageDefinition, T as TextOptions, u as calculateCost, v as createAIHelper, w as defineAsyncBatchStage, x as defineStage, y as getDefaultModel, z as getModel, C as getModelById, F as getRegisteredModel, G as listModels, H as listRegisteredModels, J as modelSupportsBatch, K as printAvailableModels, P as registerEmbeddingProvider, Q as registerModels, U as requireStageOutput } from './client-DYs5wlHp.js';
-import { L as LogLevel } from './stage-_7BKqqUG.js';
-export { S as Stage, a as StageResult } from './stage-_7BKqqUG.js';
-import { y as Workflow } from './plugins-Cl0WVVrE.js';
-export { C as CommandResult, I as IdempotencyInProgressError, z as InferWorkflowStageIds, J as JobExecuteCommand, a as JobExecuteResult, b as Kernel, c as KernelCommand, d as KernelCommandType, e as KernelConfig, W as KernelWorkflowRegistry, L as LeaseReapStaleCommand, f as LeaseReapStaleResult, O as OutboxFlushCommand, g as OutboxFlushResult, P as PluginDefinition, h as PluginReplayDLQCommand, i as PluginReplayDLQResult, j as PluginRunner, k as PluginRunnerConfig, R as RunCancelCommand, l as RunCancelResult, m as RunClaimPendingCommand, n as RunClaimPendingResult, o as RunCreateCommand, p as RunCreateResult, q as RunRerunFromCommand, r as RunRerunFromResult, s as RunTransitionCommand, t as RunTransitionResult, S as StagePollSuspendedCommand, u as StagePollSuspendedResult, A as WorkflowBuilder, v as createKernel, w as createPluginRunner, x as definePlugin } from './plugins-Cl0WVVrE.js';
+import { M as ModelKey } from './client-YFKVt4p7.js';
+export { A as AIBatch, a as AIBatchHandle, b as AIBatchProvider, c as AIBatchRequest, d as AIBatchResult, e as AICallType, f as AIEmbedResult, g as AIHelper, h as AIObjectResult, i as AIStreamResult, j as AITextResult, k as AVAILABLE_MODELS, l as AsyncBatchStageDefinition, B as BatchLogFn, D as DEFAULT_MODEL_KEY, E as EmbedOptions, m as EnhancedStageContext, I as InferInput, L as LogContext, n as ModelConfig, o as ModelRegistry, p as ModelStats, q as ModelStatsTracker, r as ModelSyncConfig, N as NoInputSchema, O as ObjectOptions, R as RecordCallParams, S as SimpleStageResult, s as StreamOptions, t as SyncStageDefinition, T as TextOptions, u as calculateCost, v as createAIHelper, w as defineAsyncBatchStage, x as defineStage, y as getDefaultModel, z as getModel, C as getModelById, F as getRegisteredModel, G as listModels, H as listRegisteredModels, J as modelSupportsBatch, K as printAvailableModels, P as registerEmbeddingProvider, Q as registerModels, U as requireStageOutput } from './client-YFKVt4p7.js';
+import { L as LogLevel } from './stage-WuK0mfrC.js';
+export { a as Stage, b as StageResult } from './stage-WuK0mfrC.js';
+import { B as Workflow } from './plugins-zT-aIcEZ.js';
+export { C as CommandResult, I as IdempotencyInProgressError, D as InferWorkflowStageIds, J as JobExecuteCommand, a as JobExecuteResult, b as Kernel, d as KernelCommand, e as KernelCommandType, f as KernelConfig, W as KernelWorkflowRegistry, L as LeaseReapStaleCommand, g as LeaseReapStaleResult, O as OutboxFlushCommand, h as OutboxFlushResult, P as PluginDefinition, i as PluginReplayDLQCommand, j as PluginReplayDLQResult, k as PluginRunner, l as PluginRunnerConfig, R as RunCancelCommand, m as RunCancelResult, n as RunClaimPendingCommand, o as RunClaimPendingResult, q as RunCreateCommand, r as RunCreateResult, s as RunRerunFromCommand, t as RunRerunFromResult, u as RunTransitionCommand, v as RunTransitionResult, S as StagePollSuspendedCommand, w as StagePollSuspendedResult, E as WorkflowBuilder, x as createKernel, y as createPluginRunner, z as definePlugin } from './plugins-zT-aIcEZ.js';
 import z$1, { z } from 'zod';
-export { A as AICallLogger, i as AICallRecord, h as AIHelperStats, r as ArtifactType, g as CreateAICallInput, e as CreateLogInput, f as CreateOutboxEventInput, C as CreateRunInput, a as CreateStageInput, D as DequeueResult, E as EnqueueJobInput, I as IdempotencyRecord, J as JobQueue, j as JobRecord, L as LogLevel, O as OutboxRecord, o as SaveArtifactInput, s as StaleVersionError, S as Status, U as UpdateRunInput, d as UpdateStageInput, c as UpsertStageInput, p as WorkflowArtifactRecord, q as WorkflowLogRecord, l as WorkflowPersistence, W as WorkflowRunRecord, b as WorkflowStageRecord } from './interface-BeEPzTFy.js';
-export { P as PrismaAICallLogger, a as PrismaJobQueue, c as PrismaWorkflowPersistence, e as createPrismaAICallLogger, f as createPrismaJobQueue, g as createPrismaWorkflowPersistence } from './index-aNuJ2QgN.js';
+export { k as AICallLogger, n as AICallRecord, m as AIHelperStats, w as ArtifactType, l as CreateAICallInput, e as CreateLogInput, h as CreateOutboxEventInput, C as CreateRunInput, a as CreateStageInput, D as DequeueResult, E as EnqueueJobInput, I as IdempotencyRecord, J as JobQueue, o as JobRecord, L as LogLevel, O as OutboxRecord, t as SaveArtifactInput, x as StaleVersionError, S as Status, U as UpdateRunInput, d as UpdateStageInput, c as UpsertStageInput, u as WorkflowArtifactRecord, v as WorkflowLogRecord, q as WorkflowPersistence, W as WorkflowRunRecord, b as WorkflowStageRecord } from './interface-BPz138Hf.js';
+export { P as PrismaAICallLogger, a as PrismaJobQueue, c as PrismaWorkflowPersistence, e as createPrismaAICallLogger, f as createPrismaJobQueue, g as createPrismaWorkflowPersistence } from './index-CL0KmlyW.js';
 import { ToolSet } from 'ai';
-export { K as KernelEvent, a as KernelEventType } from './events-D_P24UaY.js';
-export { B as BlobStore, C as Clock, E as EventSink, J as JobTransport, P as Persistence, S as Scheduler } from './ports-swhiWFw4.js';
+export { K as KernelEvent, a as KernelEventType } from './events-B3XPPu0c.js';
+export { B as BlobStore, C as Clock, E as EventSink, J as JobTransport, P as Persistence, S as Scheduler } from './ports-DUL4hlQr.js';
 import '@ai-sdk/provider';
 
 /**

package/dist/index.js

@@ -1,10 +1,10 @@
 import { ModelKey } from './chunk-WWK2SPN7.js';
 export { AVAILABLE_MODELS, AnthropicBatchProvider, DEFAULT_MODEL_KEY, GoogleBatchProvider, ModelKey, ModelStatsTracker, NoInputSchema, OpenAIBatchProvider, calculateCost, createAIHelper, defineAsyncBatchStage, defineStage, getBestProviderForModel, getDefaultModel, getModel, getModelById, getRegisteredModel, listModels, listRegisteredModels, modelSupportsBatch, printAvailableModels, registerEmbeddingProvider, registerModels, requireStageOutput, resolveModelForProvider } from './chunk-WWK2SPN7.js';
 import './chunk-D7RVRRM2.js';
-export { PrismaAICallLogger, PrismaJobQueue, PrismaWorkflowPersistence, createPrismaAICallLogger, createPrismaJobQueue, createPrismaWorkflowPersistence } from './chunk-Q2XDO3UF.js';
+export { PrismaAICallLogger, PrismaJobQueue, PrismaWorkflowPersistence, createPrismaAICallLogger, createPrismaJobQueue, createPrismaWorkflowPersistence } from './chunk-TWYPSP7P.js';
 import './chunk-MUWP5SF2.js';
-export { IdempotencyInProgressError, createKernel, createPluginRunner, definePlugin } from './chunk-5C7LRNM7.js';
-export { StaleVersionError } from './chunk-2HEV5ZJL.js';
+export { IdempotencyInProgressError, createKernel, createPluginRunner, definePlugin } from './chunk-XPWAEYOO.js';
+export { StaleVersionError } from './chunk-NANAXHS5.js';
 import { z } from 'zod';
 
 // src/core/stage-ids.ts

package/dist/{interface-BeEPzTFy.d.ts → interface-BPz138Hf.d.ts}

@@ -67,6 +67,14 @@ interface WorkflowStageRecord {
     stageName: string;
     stageNumber: number;
     executionGroup: number;
+    /**
+     * Rerun generation. 0 for the original execution; incremented each
+     * time `run.rerunFrom` recreates this stage. Annotations written by
+     * `ctx.annotate(...)` during this stage inherit this value so a
+     * future agent can distinguish decisions made on different attempts
+     * of the same logical stage.
+     */
+    attempt: number;
     status: WorkflowStageStatus;
     startedAt: Date | null;
     completedAt: Date | null;
@@ -104,6 +112,41 @@ interface WorkflowArtifactRecord {
     size: number;
     metadata: unknown | null;
 }
+/**
+ * Annotation actor — who or what produced this annotation.
+ * `kind` is open (recommended values: "agent", "user", "system") so consumers
+ * can introduce custom kinds. `id` and `version` are indexed individually for
+ * cross-version queries.
+ */
+interface AnnotationActor {
+    kind?: string;
+    id?: string;
+    version?: string;
+}
+/**
+ * Annotation scope — which entity within a run this annotation describes.
+ * - "run": run-level (e.g., trigger context)
+ * - "stage": tied to a specific stage execution (linked via workflowStageRecordId)
+ * - "ai_call": tied to a specific AI call (custom; not used by the engine itself)
+ * - other strings allowed for consumer-defined scopes
+ */
+type AnnotationScope = "run" | "stage" | "ai_call" | (string & {});
+interface WorkflowAnnotationRecord {
+    id: string;
+    createdAt: Date;
+    workflowRunId: string;
+    workflowStageRecordId: string | null;
+    attempt: number;
+    scope: AnnotationScope;
+    scopeId: string | null;
+    actorKind: string | null;
+    actorId: string | null;
+    actorVersion: string | null;
+    key: string;
+    value: unknown;
+    payload: unknown | null;
+    idempotencyKey: string | null;
+}
 interface OutboxRecord {
     id: string;
     workflowRunId: string;
@@ -189,6 +232,8 @@ interface CreateStageInput {
     stageName: string;
     stageNumber: number;
     executionGroup: number;
+    /** Rerun generation. Defaults to 0. Set by `run.rerunFrom` for recreated stages. */
+    attempt?: number;
     status?: WorkflowStageStatus;
     startedAt?: Date;
     config?: unknown;
@@ -234,6 +279,53 @@ interface SaveArtifactInput {
     size: number;
     metadata?: unknown;
 }
+/**
+ * Input for appending an annotation. `attempt` defaults to 0; callers from
+ * `job-execute.ts` / `stage-poll-suspended.ts` are responsible for computing
+ * the correct attempt value (incremented when a stage is rerun).
+ *
+ * When `idempotencyKey` is set, the unique constraint on
+ * `(workflowRunId, key, idempotencyKey)` ensures duplicates are skipped on
+ * retry. When `idempotencyKey` is null, the constraint does not apply.
+ */
+interface CreateAnnotationInput {
+    workflowRunId: string;
+    workflowStageRecordId?: string | null;
+    attempt?: number;
+    scope: AnnotationScope;
+    scopeId?: string | null;
+    actor?: AnnotationActor;
+    key: string;
+    value: unknown;
+    payload?: unknown;
+    idempotencyKey?: string | null;
+    /**
+     * If true, the engine emits an `annotation:created` outbox event when
+     * this row is persisted. Plumbed through the buffered-flush path so
+     * the event lands in the same transaction as the annotation row.
+     * Off by default — most provenance is read-only and doesn't need to
+     * be a real-time event.
+     */
+    emitEvent?: boolean;
+}
+/**
+ * Filters for `listAnnotations`. All filters are AND-combined.
+ * `keyPrefix` is implemented with `startsWith` (Postgres uses the
+ * `(workflowRunId, key)` index; SQLite may table-scan unless the engine
+ * branches to GLOB — see PrismaWorkflowPersistence).
+ */
+interface AnnotationFilters {
+    key?: string;
+    keyPrefix?: string;
+    scope?: AnnotationScope;
+    scopeId?: string | null;
+    actorId?: string;
+    actorKind?: string;
+    attempt?: number;
+    since?: Date;
+    until?: Date;
+    limit?: number;
+}
 interface CreateAICallInput {
     topic: string;
     callType: string;
@@ -314,6 +406,21 @@ interface WorkflowPersistence {
     deleteArtifact(runId: string, key: string): Promise<void>;
     listArtifacts(runId: string): Promise<WorkflowArtifactRecord[]>;
     getStageIdForArtifact(runId: string, stageId: string): Promise<string | null>;
+    /**
+     * Append one or more annotations. Designed to be called both standalone
+     * (fire-and-forget from external attach) and inside an existing
+     * transaction (buffered during stage execution, flushed in the
+     * stage-completion transaction).
+     *
+     * Rows with the same `(workflowRunId, key, idempotencyKey)` are deduped
+     * via the unique constraint; duplicates are silently skipped.
+     */
+    appendAnnotations(inputs: CreateAnnotationInput[]): Promise<void>;
+    /**
+     * List annotations for a run, optionally filtered. Returns rows ordered
+     * by `createdAt` ascending (so consumers get a timeline by default).
+     */
+    listAnnotations(workflowRunId: string, filters?: AnnotationFilters): Promise<WorkflowAnnotationRecord[]>;
     saveStageOutput(runId: string, workflowType: string, stageId: string, output: unknown): Promise<string>;
     /** Increment retry count for a failed outbox event. Returns new count. */
     incrementOutboxRetryCount(id: string): Promise<number>;
@@ -415,4 +522,4 @@ interface JobQueue {
     cancelByRun(workflowRunId: string): Promise<number>;
 }
 
-export { type AICallLogger as A, type CreateRunInput as C, type DequeueResult as D, type EnqueueJobInput as E, type IdempotencyRecord as I, type JobQueue as J, type LogLevel as L, type OutboxRecord as O, type Status as S, type UpdateRunInput as U, type WorkflowRunRecord as W, type CreateStageInput as a, type WorkflowStageRecord as b, type UpsertStageInput as c, type UpdateStageInput as d, type CreateLogInput as e, type CreateOutboxEventInput as f, type CreateAICallInput as g, type AIHelperStats as h, type AICallRecord as i, type JobRecord as j, type JobStatus as k, type WorkflowPersistence as l, type WorkflowStatus as m, type WorkflowStageStatus as n, type SaveArtifactInput as o, type WorkflowArtifactRecord as p, type WorkflowLogRecord as q, type ArtifactType as r, StaleVersionError as s };
+export { type AnnotationFilters as A, type CreateRunInput as C, type DequeueResult as D, type EnqueueJobInput as E, type IdempotencyRecord as I, type JobQueue as J, type LogLevel as L, type OutboxRecord as O, type Status as S, type UpdateRunInput as U, type WorkflowRunRecord as W, type CreateStageInput as a, type WorkflowStageRecord as b, type UpsertStageInput as c, type UpdateStageInput as d, type CreateLogInput as e, type CreateAnnotationInput as f, type WorkflowAnnotationRecord as g, type CreateOutboxEventInput as h, type AnnotationActor as i, type AnnotationScope as j, type AICallLogger as k, type CreateAICallInput as l, type AIHelperStats as m, type AICallRecord as n, type JobRecord as o, type JobStatus as p, type WorkflowPersistence as q, type WorkflowStatus as r, type WorkflowStageStatus as s, type SaveArtifactInput as t, type WorkflowArtifactRecord as u, type WorkflowLogRecord as v, type ArtifactType as w, StaleVersionError as x };

package/dist/kernel/index.d.ts

@@ -1,10 +1,10 @@
-import { K as KernelDeps } from '../plugins-Cl0WVVrE.js';
-export { C as CommandResult, I as IdempotencyInProgressError, J as JobExecuteCommand, a as JobExecuteResult, b as Kernel, c as KernelCommand, d as KernelCommandType, e as KernelConfig, L as LeaseReapStaleCommand, f as LeaseReapStaleResult, O as OutboxFlushCommand, g as OutboxFlushResult, P as PluginDefinition, h as PluginReplayDLQCommand, i as PluginReplayDLQResult, j as PluginRunner, k as PluginRunnerConfig, R as RunCancelCommand, l as RunCancelResult, m as RunClaimPendingCommand, n as RunClaimPendingResult, o as RunCreateCommand, p as RunCreateResult, q as RunRerunFromCommand, r as RunRerunFromResult, s as RunTransitionCommand, t as RunTransitionResult, S as StagePollSuspendedCommand, u as StagePollSuspendedResult, W as WorkflowRegistry, v as createKernel, w as createPluginRunner, x as definePlugin } from '../plugins-Cl0WVVrE.js';
-export { K as KernelEvent, a as KernelEventType, S as StageCompletedEvent, b as StageFailedEvent, c as StageProgressEvent, d as StageStartedEvent, e as StageSuspendedEvent, W as WorkflowCancelledEvent, f as WorkflowCompletedEvent, g as WorkflowCreatedEvent, h as WorkflowFailedEvent, i as WorkflowStartedEvent, j as WorkflowSuspendedEvent } from '../events-D_P24UaY.js';
-export { B as BlobStore, C as Clock, E as EventSink, J as JobTransport, P as Persistence, S as Scheduler } from '../ports-swhiWFw4.js';
-export { f as CreateOutboxEventInput, I as IdempotencyRecord, O as OutboxRecord } from '../interface-BeEPzTFy.js';
+import { K as KernelDeps } from '../plugins-zT-aIcEZ.js';
+export { A as AnnotateAttachInput, C as CommandResult, I as IdempotencyInProgressError, J as JobExecuteCommand, a as JobExecuteResult, b as Kernel, c as KernelAnnotations, d as KernelCommand, e as KernelCommandType, f as KernelConfig, L as LeaseReapStaleCommand, g as LeaseReapStaleResult, O as OutboxFlushCommand, h as OutboxFlushResult, P as PluginDefinition, i as PluginReplayDLQCommand, j as PluginReplayDLQResult, k as PluginRunner, l as PluginRunnerConfig, R as RunCancelCommand, m as RunCancelResult, n as RunClaimPendingCommand, o as RunClaimPendingResult, p as RunCreateAnnotation, q as RunCreateCommand, r as RunCreateResult, s as RunRerunFromCommand, t as RunRerunFromResult, u as RunTransitionCommand, v as RunTransitionResult, S as StagePollSuspendedCommand, w as StagePollSuspendedResult, W as WorkflowRegistry, x as createKernel, y as createPluginRunner, z as definePlugin } from '../plugins-zT-aIcEZ.js';
+export { K as KernelEvent, a as KernelEventType, S as StageCompletedEvent, b as StageFailedEvent, c as StageProgressEvent, d as StageStartedEvent, e as StageSuspendedEvent, W as WorkflowCancelledEvent, f as WorkflowCompletedEvent, g as WorkflowCreatedEvent, h as WorkflowFailedEvent, i as WorkflowStartedEvent, j as WorkflowSuspendedEvent } from '../events-B3XPPu0c.js';
+export { i as AnnotationActor, A as AnnotationFilters, j as AnnotationScope, f as CreateAnnotationInput, h as CreateOutboxEventInput, I as IdempotencyRecord, O as OutboxRecord, g as WorkflowAnnotationRecord } from '../interface-BPz138Hf.js';
+export { B as BlobStore, C as Clock, E as EventSink, J as JobTransport, P as Persistence, S as Scheduler } from '../ports-DUL4hlQr.js';
 import 'zod';
-import '../stage-_7BKqqUG.js';
+import '../stage-WuK0mfrC.js';
 
 /**
  * Load workflow context from completed stages.

package/dist/kernel/index.js

@@ -1,4 +1,4 @@
-export { IdempotencyInProgressError, createKernel, createPluginRunner, definePlugin, loadWorkflowContext, saveStageOutput } from '../chunk-5C7LRNM7.js';
-import '../chunk-2HEV5ZJL.js';
+export { IdempotencyInProgressError, createKernel, createPluginRunner, definePlugin, loadWorkflowContext, saveStageOutput } from '../chunk-XPWAEYOO.js';
+import '../chunk-NANAXHS5.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/kernel/testing/index.d.ts

@@ -1,6 +1,6 @@
-import { K as KernelEvent, a as KernelEventType } from '../../events-D_P24UaY.js';
-import { E as EventSink, C as Clock, B as BlobStore, S as Scheduler } from '../../ports-swhiWFw4.js';
-import '../../interface-BeEPzTFy.js';
+import { K as KernelEvent, a as KernelEventType } from '../../events-B3XPPu0c.js';
+import { E as EventSink, C as Clock, B as BlobStore, S as Scheduler } from '../../ports-DUL4hlQr.js';
+import '../../interface-BPz138Hf.js';
 
 declare class CollectingEventSink implements EventSink {
     readonly events: KernelEvent[];

package/dist/persistence/index.d.ts

@@ -1,2 +1,2 @@
-export { A as AICallLogger, i as AICallRecord, h as AIHelperStats, r as ArtifactType, g as CreateAICallInput, e as CreateLogInput, C as CreateRunInput, a as CreateStageInput, D as DequeueResult, E as EnqueueJobInput, J as JobQueue, j as JobRecord, k as JobStatus, L as LogLevel, o as SaveArtifactInput, S as Status, U as UpdateRunInput, d as UpdateStageInput, c as UpsertStageInput, p as WorkflowArtifactRecord, q as WorkflowLogRecord, l as WorkflowPersistence, W as WorkflowRunRecord, b as WorkflowStageRecord, n as WorkflowStageStatus, m as WorkflowStatus } from '../interface-BeEPzTFy.js';
-export { P as PrismaAICallLogger, a as PrismaJobQueue, c as PrismaWorkflowPersistence, e as createPrismaAICallLogger, f as createPrismaJobQueue, g as createPrismaWorkflowPersistence } from '../index-aNuJ2QgN.js';
+export { k as AICallLogger, n as AICallRecord, m as AIHelperStats, w as ArtifactType, l as CreateAICallInput, e as CreateLogInput, C as CreateRunInput, a as CreateStageInput, D as DequeueResult, E as EnqueueJobInput, J as JobQueue, o as JobRecord, p as JobStatus, L as LogLevel, t as SaveArtifactInput, S as Status, U as UpdateRunInput, d as UpdateStageInput, c as UpsertStageInput, u as WorkflowArtifactRecord, v as WorkflowLogRecord, q as WorkflowPersistence, W as WorkflowRunRecord, b as WorkflowStageRecord, s as WorkflowStageStatus, r as WorkflowStatus } from '../interface-BPz138Hf.js';
+export { P as PrismaAICallLogger, a as PrismaJobQueue, c as PrismaWorkflowPersistence, e as createPrismaAICallLogger, f as createPrismaJobQueue, g as createPrismaWorkflowPersistence } from '../index-CL0KmlyW.js';

package/dist/persistence/index.js

@@ -1,6 +1,6 @@
 import '../chunk-D7RVRRM2.js';
-export { PrismaAICallLogger, PrismaJobQueue, PrismaWorkflowPersistence, createPrismaAICallLogger, createPrismaJobQueue, createPrismaWorkflowPersistence } from '../chunk-Q2XDO3UF.js';
+export { PrismaAICallLogger, PrismaJobQueue, PrismaWorkflowPersistence, createPrismaAICallLogger, createPrismaJobQueue, createPrismaWorkflowPersistence } from '../chunk-TWYPSP7P.js';
 import '../chunk-MUWP5SF2.js';
-import '../chunk-2HEV5ZJL.js';
+import '../chunk-NANAXHS5.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/persistence/prisma/index.d.ts

@@ -1,5 +1,5 @@
-export { D as DatabaseType, P as PrismaAICallLogger, a as PrismaJobQueue, b as PrismaJobQueueOptions, c as PrismaWorkflowPersistence, d as PrismaWorkflowPersistenceOptions, e as createPrismaAICallLogger, f as createPrismaJobQueue, g as createPrismaWorkflowPersistence } from '../../index-aNuJ2QgN.js';
-import '../../interface-BeEPzTFy.js';
+export { D as DatabaseType, P as PrismaAICallLogger, a as PrismaJobQueue, b as PrismaJobQueueOptions, c as PrismaWorkflowPersistence, d as PrismaWorkflowPersistenceOptions, e as createPrismaAICallLogger, f as createPrismaJobQueue, g as createPrismaWorkflowPersistence } from '../../index-CL0KmlyW.js';
+import '../../interface-BPz138Hf.js';
 
 /**
  * Prisma Enum Compatibility Layer

package/dist/persistence/prisma/index.js

@@ -1,5 +1,5 @@
-export { PrismaAICallLogger, PrismaJobQueue, PrismaWorkflowPersistence, createEnumHelper, createPrismaAICallLogger, createPrismaJobQueue, createPrismaWorkflowPersistence } from '../../chunk-Q2XDO3UF.js';
+export { PrismaAICallLogger, PrismaJobQueue, PrismaWorkflowPersistence, createEnumHelper, createPrismaAICallLogger, createPrismaJobQueue, createPrismaWorkflowPersistence } from '../../chunk-TWYPSP7P.js';
 import '../../chunk-MUWP5SF2.js';
-import '../../chunk-2HEV5ZJL.js';
+import '../../chunk-NANAXHS5.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{plugins-Cl0WVVrE.d.ts → plugins-zT-aIcEZ.d.ts}

@@ -1,7 +1,8 @@
 import { z } from 'zod';
-import { S as Stage } from './stage-_7BKqqUG.js';
-import { P as Persistence, B as BlobStore, J as JobTransport, E as EventSink, S as Scheduler, C as Clock } from './ports-swhiWFw4.js';
-import { a as KernelEventType, K as KernelEvent } from './events-D_P24UaY.js';
+import { a as Stage } from './stage-WuK0mfrC.js';
+import { i as AnnotationActor, j as AnnotationScope, A as AnnotationFilters, g as WorkflowAnnotationRecord } from './interface-BPz138Hf.js';
+import { P as Persistence, B as BlobStore, J as JobTransport, E as EventSink, S as Scheduler, C as Clock } from './ports-DUL4hlQr.js';
+import { a as KernelEventType, K as KernelEvent } from './events-B3XPPu0c.js';
 
 /**
  * Workflow Builder - Fluent API for composing type-safe workflows
@@ -218,6 +219,20 @@ type InferWorkflowStageIds<W> = W extends Workflow<any, any, infer C> ? keyof C
  *
  * This file contains ONLY types -- no runtime code.
  */
+
+/** Annotation to attach at run-creation time. */
+interface RunCreateAnnotation {
+    readonly attributes: Record<string, unknown>;
+    readonly actor?: AnnotationActor;
+    readonly payload?: Record<string, unknown>;
+    readonly idempotencyKey?: string;
+    /**
+     * If true, the engine writes an `annotation:created` outbox event for
+     * each attribute in this batch, in the same transaction as the run
+     * creation. Off by default.
+     */
+    readonly emitEvent?: boolean;
+}
 /** Creates a new workflow run. */
 interface RunCreateCommand {
     readonly type: "run.create";
@@ -226,7 +241,18 @@ interface RunCreateCommand {
     readonly input: Record<string, unknown>;
     readonly config?: Record<string, unknown>;
     readonly priority?: number;
+    /**
+     * @deprecated since 0.8.0. Use `annotations` instead — annotations are
+     * queryable, indexed, and follow stable conventions. `metadata` will be
+     * removed in 1.0.
+     */
     readonly metadata?: Record<string, unknown>;
+    /**
+     * Annotations to attach at run creation time. Each entry becomes one
+     * row per attribute, sharing the supplied envelope (actor / payload /
+     * idempotencyKey). Written inside the same transaction as the run.
+     */
+    readonly annotations?: ReadonlyArray<RunCreateAnnotation>;
 }
 /** Result of a `run.create` command. */
 interface RunCreateResult {
@@ -392,8 +418,41 @@ interface KernelConfig {
     clock: Clock;
     registry: WorkflowRegistry;
 }
+/** Input for the public `kernel.annotations.attach` helper. */
+interface AnnotateAttachInput {
+    attributes: Record<string, unknown>;
+    actor?: AnnotationActor;
+    /**
+     * Defaults to "run". Set to "stage" with `scopeId` to scope an
+     * annotation to a specific stage (e.g., from a plugin observing
+     * stage events).
+     */
+    scope?: AnnotationScope;
+    scopeId?: string | null;
+    workflowStageRecordId?: string | null;
+    attempt?: number;
+    payload?: Record<string, unknown>;
+    idempotencyKey?: string;
+    /**
+     * If true, the engine writes an `annotation:created` outbox event
+     * for each attribute in this batch, in the same transaction as the
+     * annotation rows. Off by default.
+     */
+    emitEvent?: boolean;
+}
+/**
+ * Public helpers for working with annotations directly — for plugins,
+ * post-hoc reviews, external integrations, and query tooling. The
+ * `attach` path commits in a single transaction; the `list` path is a
+ * read-only query honoring the persistence-port filters.
+ */
+interface KernelAnnotations {
+    attach(workflowRunId: string, input: AnnotateAttachInput): Promise<void>;
+    list(workflowRunId: string, filters?: AnnotationFilters): Promise<WorkflowAnnotationRecord[]>;
+}
 interface Kernel {
     dispatch<T extends KernelCommand>(command: T): Promise<CommandResult<T>>;
+    annotations: KernelAnnotations;
 }
 interface KernelDeps {
     persistence: Persistence;
@@ -434,4 +493,4 @@ interface PluginRunner extends EventSink {
 declare function definePlugin<T extends KernelEventType>(definition: PluginDefinition<T>): PluginDefinition<T>;
 declare function createPluginRunner(config: PluginRunnerConfig): PluginRunner;
 
-export { WorkflowBuilder as A, type CommandResult as C, IdempotencyInProgressError as I, type JobExecuteCommand as J, type KernelDeps as K, type LeaseReapStaleCommand as L, type OutboxFlushCommand as O, type PluginDefinition as P, type RunCancelCommand as R, type StagePollSuspendedCommand as S, type WorkflowRegistry as W, type JobExecuteResult as a, type Kernel as b, type KernelCommand as c, type KernelCommandType as d, type KernelConfig as e, type LeaseReapStaleResult as f, type OutboxFlushResult as g, type PluginReplayDLQCommand as h, type PluginReplayDLQResult as i, type PluginRunner as j, type PluginRunnerConfig as k, type RunCancelResult as l, type RunClaimPendingCommand as m, type RunClaimPendingResult as n, type RunCreateCommand as o, type RunCreateResult as p, type RunRerunFromCommand as q, type RunRerunFromResult as r, type RunTransitionCommand as s, type RunTransitionResult as t, type StagePollSuspendedResult as u, createKernel as v, createPluginRunner as w, definePlugin as x, Workflow as y, type InferWorkflowStageIds as z };
+export { type AnnotateAttachInput as A, Workflow as B, type CommandResult as C, type InferWorkflowStageIds as D, WorkflowBuilder as E, IdempotencyInProgressError as I, type JobExecuteCommand as J, type KernelDeps as K, type LeaseReapStaleCommand as L, type OutboxFlushCommand as O, type PluginDefinition as P, type RunCancelCommand as R, type StagePollSuspendedCommand as S, type WorkflowRegistry as W, type JobExecuteResult as a, type Kernel as b, type KernelAnnotations as c, type KernelCommand as d, type KernelCommandType as e, type KernelConfig as f, type LeaseReapStaleResult as g, type OutboxFlushResult as h, type PluginReplayDLQCommand as i, type PluginReplayDLQResult as j, type PluginRunner as k, type PluginRunnerConfig as l, type RunCancelResult as m, type RunClaimPendingCommand as n, type RunClaimPendingResult as o, type RunCreateAnnotation as p, type RunCreateCommand as q, type RunCreateResult as r, type RunRerunFromCommand as s, type RunRerunFromResult as t, type RunTransitionCommand as u, type RunTransitionResult as v, type StagePollSuspendedResult as w, createKernel as x, createPluginRunner as y, definePlugin as z };

package/dist/{ports-swhiWFw4.d.ts → ports-DUL4hlQr.d.ts}

@@ -1,5 +1,5 @@
-import { E as EnqueueJobInput, D as DequeueResult, C as CreateRunInput, W as WorkflowRunRecord, U as UpdateRunInput, S as Status, a as CreateStageInput, b as WorkflowStageRecord, c as UpsertStageInput, d as UpdateStageInput, e as CreateLogInput, f as CreateOutboxEventInput, O as OutboxRecord } from './interface-BeEPzTFy.js';
-import { K as KernelEvent } from './events-D_P24UaY.js';
+import { E as EnqueueJobInput, D as DequeueResult, C as CreateRunInput, W as WorkflowRunRecord, U as UpdateRunInput, S as Status, a as CreateStageInput, b as WorkflowStageRecord, c as UpsertStageInput, d as UpdateStageInput, e as CreateLogInput, f as CreateAnnotationInput, A as AnnotationFilters, g as WorkflowAnnotationRecord, h as CreateOutboxEventInput, O as OutboxRecord } from './interface-BPz138Hf.js';
+import { K as KernelEvent } from './events-B3XPPu0c.js';
 
 /**
  * Kernel Port Interfaces
@@ -67,6 +67,15 @@ interface Persistence {
     getLastCompletedStageBefore(runId: string, executionGroup: number): Promise<WorkflowStageRecord | null>;
     deleteStage(id: string): Promise<void>;
     createLog(data: CreateLogInput): Promise<void>;
+    /**
+     * Append annotations. Called both from outside transactions (run.create,
+     * external attach) and inside the stage-completion transactions in
+     * job-execute and stage-poll-suspended. Duplicates with the same
+     * `(workflowRunId, key, idempotencyKey)` are silently skipped.
+     */
+    appendAnnotations(inputs: CreateAnnotationInput[]): Promise<void>;
+    /** List annotations for a run, ordered by `createdAt` ascending. */
+    listAnnotations(workflowRunId: string, filters?: AnnotationFilters): Promise<WorkflowAnnotationRecord[]>;
     /** Write events to the outbox. Sequences are auto-assigned per workflowRunId. */
     appendOutboxEvents(events: CreateOutboxEventInput[]): Promise<void>;
     /** Read unpublished events ordered by (workflowRunId, sequence). */