@bratsos/workflow-engine 0.6.0 → 0.8.0

package/dist/{chunk-HOGDFLCG.js → chunk-XPWAEYOO.js}

@@ -1,4 +1,4 @@
-import { StaleVersionError } from './chunk-2MWO6UVR.js';
+import { StaleVersionError } from './chunk-NANAXHS5.js';
 import { z } from 'zod';
 
 z.object({
@@ -28,6 +28,16 @@ var IdempotencyInProgressError = class extends Error {
     this.name = "IdempotencyInProgressError";
   }
 };
+var RunNotRunningError = class extends Error {
+  constructor(workflowRunId, currentStatus) {
+    super(
+      `Run ${workflowRunId} is ${currentStatus}, not RUNNING \u2014 transactional write aborted`
+    );
+    this.workflowRunId = workflowRunId;
+    this.currentStatus = currentStatus;
+    this.name = "RunNotRunningError";
+  }
+};
 
 // src/kernel/helpers/load-workflow-context.ts
 async function loadWorkflowContext(workflowRunId, deps) {
@@ -56,6 +66,76 @@ async function saveStageOutput(runId, workflowType, stageId, output, deps) {
   return key;
 }
 
+// src/kernel/helpers/annotation-buffer.ts
+function normalizeAnnotateArgs(args) {
+  const first = args[0];
+  if (typeof first === "string") {
+    return [
+      { key: first, value: args[1], opts: args[2] }
+    ];
+  }
+  if (first !== null && typeof first === "object" && "key" in first && typeof first.key === "string" && !("attributes" in first)) {
+    return [
+      {
+        key: first.key,
+        value: args[1],
+        opts: args[2]
+      }
+    ];
+  }
+  const batch = first;
+  const attributes = batch?.attributes ?? {};
+  const opts = {
+    actor: batch.actor,
+    payload: batch.payload,
+    idempotencyKey: batch.idempotencyKey,
+    emitEvent: batch.emitEvent
+  };
+  return Object.entries(attributes).map(([key, value]) => ({
+    key,
+    value,
+    opts
+  }));
+}
+var AnnotationBuffer = class {
+  items = [];
+  push(input) {
+    this.items.push(input);
+  }
+  /**
+   * Return all buffered items and clear the buffer. Idempotent — calling
+   * flush again returns an empty array.
+   */
+  flush() {
+    const out = this.items;
+    this.items = [];
+    return out;
+  }
+  size() {
+    return this.items.length;
+  }
+};
+function createAnnotationBuffer() {
+  return new AnnotationBuffer();
+}
+
+// src/kernel/helpers/annotation-events.ts
+function buildAnnotationEvents(inputs, now) {
+  return inputs.filter((input) => input.emitEvent === true).map((input) => ({
+    type: "annotation:created",
+    timestamp: now,
+    workflowRunId: input.workflowRunId,
+    key: input.key,
+    value: input.value,
+    scope: input.scope,
+    scopeId: input.scopeId ?? void 0,
+    attempt: input.attempt,
+    actorKind: input.actor?.kind,
+    actorId: input.actor?.id,
+    actorVersion: input.actor?.version
+  }));
+}
+
 // src/kernel/helpers/create-storage-shim.ts
 function createStorageShim(workflowRunId, workflowType, deps) {
   return {
@@ -78,6 +158,60 @@ function createStorageShim(workflowRunId, workflowType, deps) {
   };
 }
 
+// src/kernel/helpers/legacy-metadata-shim.ts
+function synthesizeLegacyMetadata(run, filters = {}) {
+  if (!run.metadata || typeof run.metadata !== "object") return [];
+  if (Array.isArray(run.metadata)) return [];
+  if (filters.scope !== void 0 && filters.scope !== "run") return [];
+  if (filters.scopeId !== void 0 && filters.scopeId !== null) return [];
+  if (filters.actorId !== void 0) return [];
+  if (filters.actorKind !== void 0) return [];
+  if (filters.attempt !== void 0 && filters.attempt !== 0) return [];
+  if (filters.since !== void 0 && run.createdAt < filters.since) return [];
+  if (filters.until !== void 0 && run.createdAt > filters.until) return [];
+  const rows = [];
+  for (const [originalKey, value] of Object.entries(
+    run.metadata
+  )) {
+    const key = `legacy.metadata.${originalKey}`;
+    if (filters.key !== void 0 && filters.key !== key) continue;
+    if (filters.keyPrefix !== void 0 && !key.startsWith(filters.keyPrefix))
+      continue;
+    rows.push({
+      id: `synthesized:${run.id}:${originalKey}`,
+      createdAt: run.createdAt,
+      workflowRunId: run.id,
+      workflowStageRecordId: null,
+      attempt: 0,
+      scope: "run",
+      scopeId: null,
+      actorKind: null,
+      actorId: null,
+      actorVersion: null,
+      key,
+      value,
+      payload: null,
+      idempotencyKey: null
+    });
+  }
+  return rows;
+}
+function filterCouldMatchLegacy(filters) {
+  if (filters.scope !== void 0 && filters.scope !== "run") return false;
+  if (filters.scopeId !== void 0 && filters.scopeId !== null) return false;
+  if (filters.actorId !== void 0) return false;
+  if (filters.actorKind !== void 0) return false;
+  if (filters.attempt !== void 0 && filters.attempt !== 0) return false;
+  if (filters.key !== void 0 && !filters.key.startsWith("legacy.metadata."))
+    return false;
+  if (filters.keyPrefix !== void 0) {
+    if (!"legacy.metadata.".startsWith(filters.keyPrefix) && !filters.keyPrefix.startsWith("legacy.metadata.")) {
+      return false;
+    }
+  }
+  return true;
+}
+
 // src/kernel/helpers/resolve-execution-group-output.ts
 function resolveExecutionGroupOutput(workflow, groupIndex, workflowContext) {
   const stages = workflow.getStagesInExecutionGroup(groupIndex);
@@ -181,6 +315,7 @@ async function handleJobExecute(command, deps) {
     return record;
   });
   const progressEvents = [];
+  const annotationBuffer = createAnnotationBuffer();
   try {
     const rawInput = resolveStageInput(
       workflow,
@@ -206,6 +341,27 @@ async function handleJobExecute(command, deps) {
       }).catch(() => {
       });
     };
+    const annotateFn = ((...args) => {
+      const stageScopeFields = {
+        workflowRunId,
+        workflowStageRecordId: stageRecord.id,
+        attempt: stageRecord.attempt,
+        scope: "stage",
+        scopeId: stageId
+      };
+      for (const { key, value, opts } of normalizeAnnotateArgs(args)) {
+        if (value === void 0 || value === null) continue;
+        annotationBuffer.push({
+          ...stageScopeFields,
+          actor: opts?.actor,
+          key,
+          value,
+          payload: opts?.payload,
+          idempotencyKey: opts?.idempotencyKey,
+          emitEvent: opts?.emitEvent
+        });
+      }
+    });
     const context = {
       workflowRunId,
       stageId,
@@ -228,6 +384,7 @@ async function handleJobExecute(command, deps) {
       },
       onLog: logFn,
       log: logFn,
+      annotate: annotateFn,
       storage: createStorageShim(workflowRunId, workflowRun.workflowType, deps),
       workflowContext
     };
@@ -246,30 +403,54 @@ async function handleJobExecute(command, deps) {
       const nextPollAt = new Date(
         pollConfig.nextPollAt?.getTime() ?? deps.clock.now().getTime() + (pollConfig.pollInterval || 6e4)
       );
-      await deps.persistence.withTransaction(async (tx) => {
-        await tx.updateStage(stageRecord.id, {
-          status: "SUSPENDED",
-          suspendedState: state,
-          nextPollAt,
-          pollInterval: pollConfig.pollInterval,
-          maxWaitUntil: pollConfig.maxWaitTime ? new Date(deps.clock.now().getTime() + pollConfig.maxWaitTime) : void 0,
-          metrics
+      const bufferedAnnotations = annotationBuffer.flush();
+      try {
+        await deps.persistence.withTransaction(async (tx) => {
+          const currentStatus = await tx.getRunStatus(workflowRunId);
+          if (currentStatus !== "RUNNING") {
+            throw new RunNotRunningError(
+              workflowRunId,
+              currentStatus ?? "DELETED"
+            );
+          }
+          await tx.updateStage(stageRecord.id, {
+            status: "SUSPENDED",
+            suspendedState: state,
+            nextPollAt,
+            pollInterval: pollConfig.pollInterval,
+            maxWaitUntil: pollConfig.maxWaitTime ? new Date(deps.clock.now().getTime() + pollConfig.maxWaitTime) : void 0,
+            metrics
+          });
+          if (bufferedAnnotations.length > 0) {
+            await tx.appendAnnotations(bufferedAnnotations);
+          }
+          const suspendedEvent = {
+            type: "stage:suspended",
+            timestamp: deps.clock.now(),
+            workflowRunId,
+            stageId,
+            stageName: stageDef.name,
+            nextPollAt
+          };
+          await tx.appendOutboxEvents(
+            toOutboxEvents(workflowRunId, causationId, [
+              ...progressEvents,
+              suspendedEvent,
+              ...buildAnnotationEvents(bufferedAnnotations, deps.clock.now())
+            ])
+          );
         });
-        const suspendedEvent = {
-          type: "stage:suspended",
-          timestamp: deps.clock.now(),
-          workflowRunId,
-          stageId,
-          stageName: stageDef.name,
-          nextPollAt
-        };
-        await tx.appendOutboxEvents(
-          toOutboxEvents(workflowRunId, causationId, [
-            ...progressEvents,
-            suspendedEvent
-          ])
-        );
-      });
+      } catch (txError) {
+        if (txError instanceof RunNotRunningError) {
+          return {
+            outcome: "failed",
+            ghost: true,
+            error: txError.message,
+            _events: []
+          };
+        }
+        throw txError;
+      }
       return { outcome: "suspended", nextPollAt, _events: [] };
     } else {
       const duration = deps.clock.now().getTime() - startTime;
@@ -287,33 +468,57 @@ async function handleJobExecute(command, deps) {
         result.artifacts,
         deps
       ) : void 0;
-      await deps.persistence.withTransaction(async (tx) => {
-        await tx.updateStage(stageRecord.id, {
-          status: "COMPLETED",
-          completedAt: deps.clock.now(),
-          duration,
-          outputData: {
-            _artifactKey: outputKey,
-            ...artifactKeys ? { _artifactKeys: artifactKeys } : {}
-          },
-          metrics: result.metrics,
-          embeddingInfo: result.embeddings
+      const bufferedAnnotations = annotationBuffer.flush();
+      try {
+        await deps.persistence.withTransaction(async (tx) => {
+          const currentStatus = await tx.getRunStatus(workflowRunId);
+          if (currentStatus !== "RUNNING") {
+            throw new RunNotRunningError(
+              workflowRunId,
+              currentStatus ?? "DELETED"
+            );
+          }
+          await tx.updateStage(stageRecord.id, {
+            status: "COMPLETED",
+            completedAt: deps.clock.now(),
+            duration,
+            outputData: {
+              _artifactKey: outputKey,
+              ...artifactKeys ? { _artifactKeys: artifactKeys } : {}
+            },
+            metrics: result.metrics,
+            embeddingInfo: result.embeddings
+          });
+          if (bufferedAnnotations.length > 0) {
+            await tx.appendAnnotations(bufferedAnnotations);
+          }
+          const completedEvent = {
+            type: "stage:completed",
+            timestamp: deps.clock.now(),
+            workflowRunId,
+            stageId,
+            stageName: stageDef.name,
+            duration
+          };
+          await tx.appendOutboxEvents(
+            toOutboxEvents(workflowRunId, causationId, [
+              ...progressEvents,
+              completedEvent,
+              ...buildAnnotationEvents(bufferedAnnotations, deps.clock.now())
+            ])
+          );
         });
-        const completedEvent = {
-          type: "stage:completed",
-          timestamp: deps.clock.now(),
-          workflowRunId,
-          stageId,
-          stageName: stageDef.name,
-          duration
-        };
-        await tx.appendOutboxEvents(
-          toOutboxEvents(workflowRunId, causationId, [
-            ...progressEvents,
-            completedEvent
-          ])
-        );
-      });
+      } catch (txError) {
+        if (txError instanceof RunNotRunningError) {
+          return {
+            outcome: "failed",
+            ghost: true,
+            error: txError.message,
+            _events: []
+          };
+        }
+        throw txError;
+      }
       return {
         outcome: "completed",
         output: result.output,
@@ -323,14 +528,25 @@ async function handleJobExecute(command, deps) {
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
     const duration = deps.clock.now().getTime() - startTime;
+    const bufferedAnnotations = annotationBuffer.flush();
     try {
       await deps.persistence.withTransaction(async (tx) => {
+        const currentStatus = await tx.getRunStatus(workflowRunId);
+        if (currentStatus !== "RUNNING") {
+          throw new RunNotRunningError(
+            workflowRunId,
+            currentStatus ?? "DELETED"
+          );
+        }
         await tx.updateStage(stageRecord.id, {
           status: "FAILED",
           completedAt: deps.clock.now(),
           duration,
           errorMessage
         });
+        if (bufferedAnnotations.length > 0) {
+          await tx.appendAnnotations(bufferedAnnotations);
+        }
         const failedEvent = {
           type: "stage:failed",
           timestamp: deps.clock.now(),
@@ -342,11 +558,20 @@ async function handleJobExecute(command, deps) {
         await tx.appendOutboxEvents(
           toOutboxEvents(workflowRunId, causationId, [
             ...progressEvents,
-            failedEvent
+            failedEvent,
+            ...buildAnnotationEvents(bufferedAnnotations, deps.clock.now())
           ])
         );
       });
-    } catch {
+    } catch (txError) {
+      if (txError instanceof RunNotRunningError) {
+        return {
+          outcome: "failed",
+          ghost: true,
+          error: txError.message,
+          _events: []
+        };
+      }
       throw error;
     }
     await deps.persistence.createLog({
@@ -614,6 +839,31 @@ async function handleRunCreate(command, deps) {
     priority,
     metadata: command.metadata
   });
+  const annotationEvents = [];
+  if (command.annotations && command.annotations.length > 0) {
+    const annotationInputs = [];
+    for (const entry of command.annotations) {
+      for (const [key, value] of Object.entries(entry.attributes)) {
+        if (value === void 0 || value === null) continue;
+        annotationInputs.push({
+          workflowRunId: run.id,
+          scope: "run",
+          actor: entry.actor,
+          key,
+          value,
+          payload: entry.payload,
+          idempotencyKey: entry.idempotencyKey,
+          emitEvent: entry.emitEvent
+        });
+      }
+    }
+    if (annotationInputs.length > 0) {
+      await deps.persistence.appendAnnotations(annotationInputs);
+      annotationEvents.push(
+        ...buildAnnotationEvents(annotationInputs, deps.clock.now())
+      );
+    }
+  }
   return {
     workflowRunId: run.id,
     status: "PENDING",
@@ -623,7 +873,8 @@ async function handleRunCreate(command, deps) {
         timestamp: deps.clock.now(),
         workflowRunId: run.id,
         workflowId: command.workflowId
-      }
+      },
+      ...annotationEvents
     ]
   };
 }
@@ -703,6 +954,11 @@ async function handleRunRerunFrom(command, deps) {
     (s) => s.executionGroup >= targetGroup
   );
   const deletedStageIds = stagesToDelete.map((s) => s.stageId);
+  const priorMaxAttempt = stagesToDelete.reduce(
+    (max, s) => s.attempt > max ? s.attempt : max,
+    0
+  );
+  const newAttempt = priorMaxAttempt + 1;
   for (const stage of stagesToDelete) {
     const prefix = `workflow-v2/${run.workflowType}/${workflowRunId}/${stage.stageId}/`;
     const keys = await deps.blobStore.list(prefix).catch(() => []);
@@ -731,6 +987,7 @@ async function handleRunRerunFrom(command, deps) {
       stageName: stage.name,
       stageNumber: workflow.getStageIndex(stage.id) + 1,
       executionGroup: targetGroup,
+      attempt: newAttempt,
       status: "PENDING",
       config: run.config?.[stage.id] || {}
     });
@@ -775,6 +1032,11 @@ async function claimRunTransition(run, deps) {
 }
 async function enqueueExecutionGroup(run, workflow, groupIndex, deps) {
   const stages = workflow.getStagesInExecutionGroup(groupIndex);
+  const existingStages = await deps.persistence.getStagesByRun(run.id);
+  const currentAttempt = existingStages.reduce(
+    (max, s) => s.attempt > max ? s.attempt : max,
+    0
+  );
   const stagesToEnqueue = [];
   for (const stage of stages) {
     const record = await deps.persistence.upsertStage({
@@ -786,6 +1048,7 @@ async function enqueueExecutionGroup(run, workflow, groupIndex, deps) {
         stageName: stage.name,
         stageNumber: workflow.getStageIndex(stage.id) + 1,
         executionGroup: groupIndex,
+        attempt: currentAttempt,
         status: "PENDING",
         config: run.config?.[stage.id] || {}
       },
@@ -932,6 +1195,10 @@ async function markStageCancelled(stageId, deps) {
 async function withClaimedRun(workflowRunId, expectedVersion, deps, fn) {
   try {
     const value = await deps.persistence.withTransaction(async (tx) => {
+      const runStatus = await tx.getRunStatus(workflowRunId);
+      if (runStatus !== "RUNNING") {
+        throw new RunNotRunningError(workflowRunId, runStatus ?? "DELETED");
+      }
       await tx.updateRun(workflowRunId, {
         expectedVersion
       });
@@ -942,6 +1209,9 @@ async function withClaimedRun(workflowRunId, expectedVersion, deps, fn) {
     if (error instanceof StaleVersionError) {
       return { status: "stale" };
     }
+    if (error instanceof RunNotRunningError) {
+      return { status: "cancelled", runStatus: error.currentStatus };
+    }
     throw error;
   }
 }
@@ -1027,6 +1297,28 @@ async function handleStagePollSuspended(command, deps) {
       }).catch(() => {
       });
     };
+    const annotationBuffer = createAnnotationBuffer();
+    const annotateFn = ((...args) => {
+      const stageScopeFields = {
+        workflowRunId: stageRecord.workflowRunId,
+        workflowStageRecordId: stageRecord.id,
+        attempt: stageRecord.attempt,
+        scope: "stage",
+        scopeId: stageRecord.stageId
+      };
+      for (const { key, value, opts } of normalizeAnnotateArgs(args)) {
+        if (value === void 0 || value === null) continue;
+        annotationBuffer.push({
+          ...stageScopeFields,
+          actor: opts?.actor,
+          key,
+          value,
+          payload: opts?.payload,
+          idempotencyKey: opts?.idempotencyKey,
+          emitEvent: opts?.emitEvent
+        });
+      }
+    });
     const checkContext = {
       workflowRunId: run.id,
       stageId: stageRecord.stageId,
@@ -1034,6 +1326,7 @@ async function handleStagePollSuspended(command, deps) {
       config: stageRecord.config || {},
       log: logFn,
       onLog: logFn,
+      annotate: annotateFn,
       storage
     };
     try {
@@ -1042,6 +1335,7 @@ async function handleStagePollSuspended(command, deps) {
         checkContext
       );
       if (checkResult.error) {
+        const bufferedAnnotations = annotationBuffer.flush();
         const claimResult = await withClaimedRun(
           stageRecord.workflowRunId,
           run.version,
@@ -1057,6 +1351,9 @@ async function handleStagePollSuspended(command, deps) {
               status: "FAILED",
               completedAt: deps.clock.now()
             });
+            if (bufferedAnnotations.length > 0) {
+              await tx.appendAnnotations(bufferedAnnotations);
+            }
             await tx.appendOutboxEvents(
               toOutboxEvents2(stageRecord.workflowRunId, [
                 {
@@ -1072,7 +1369,8 @@ async function handleStagePollSuspended(command, deps) {
                   timestamp: deps.clock.now(),
                   workflowRunId: stageRecord.workflowRunId,
                   error: checkResult.error
-                }
+                },
+                ...buildAnnotationEvents(bufferedAnnotations, deps.clock.now())
               ])
             );
           }
@@ -1086,6 +1384,10 @@ async function handleStagePollSuspended(command, deps) {
           }
           continue;
         }
+        if (claimResult.status === "cancelled") {
+          await markStageCancelled(stageRecord.id, deps);
+          continue;
+        }
         failed++;
       } else if (checkResult.ready) {
         let outputRef;
@@ -1105,6 +1407,7 @@ async function handleStagePollSuspended(command, deps) {
           outputRef = { _artifactKey: outputKey };
         }
         const duration = deps.clock.now().getTime() - (stageRecord.startedAt?.getTime() ?? deps.clock.now().getTime());
+        const bufferedAnnotations = annotationBuffer.flush();
         const claimResult = await withClaimedRun(
           stageRecord.workflowRunId,
           run.version,
@@ -1119,6 +1422,9 @@ async function handleStagePollSuspended(command, deps) {
               metrics: checkResult.metrics,
               embeddingInfo: checkResult.embeddings
             });
+            if (bufferedAnnotations.length > 0) {
+              await tx.appendAnnotations(bufferedAnnotations);
+            }
             await tx.appendOutboxEvents(
               toOutboxEvents2(stageRecord.workflowRunId, [
                 {
@@ -1128,7 +1434,8 @@ async function handleStagePollSuspended(command, deps) {
                   stageId: stageRecord.stageId,
                   stageName: stageRecord.stageName,
                   duration
-                }
+                },
+                ...buildAnnotationEvents(bufferedAnnotations, deps.clock.now())
               ])
             );
           }
@@ -1142,11 +1449,16 @@ async function handleStagePollSuspended(command, deps) {
           }
           continue;
         }
+        if (claimResult.status === "cancelled") {
+          await markStageCancelled(stageRecord.id, deps);
+          continue;
+        }
         resumed++;
         resumedWorkflowRunIds.add(stageRecord.workflowRunId);
       } else {
         const pollInterval = checkResult.nextCheckIn ?? stageRecord.pollInterval ?? 6e4;
         const nextPollAt = new Date(deps.clock.now().getTime() + pollInterval);
+        const bufferedAnnotations = annotationBuffer.flush();
         const claimResult = await withClaimedRun(
           stageRecord.workflowRunId,
           run.version,
@@ -1155,6 +1467,9 @@ async function handleStagePollSuspended(command, deps) {
             await tx.updateStage(stageRecord.id, {
               nextPollAt
             });
+            if (bufferedAnnotations.length > 0) {
+              await tx.appendAnnotations(bufferedAnnotations);
+            }
           }
         );
         if (claimResult.status === "stale") {
@@ -1166,9 +1481,14 @@ async function handleStagePollSuspended(command, deps) {
           }
           continue;
         }
+        if (claimResult.status === "cancelled") {
+          await markStageCancelled(stageRecord.id, deps);
+          continue;
+        }
       }
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
+      const bufferedAnnotations = annotationBuffer.flush();
       const claimResult = await withClaimedRun(
         stageRecord.workflowRunId,
         run.version,
@@ -1184,6 +1504,9 @@ async function handleStagePollSuspended(command, deps) {
             status: "FAILED",
             completedAt: deps.clock.now()
           });
+          if (bufferedAnnotations.length > 0) {
+            await tx.appendAnnotations(bufferedAnnotations);
+          }
           await tx.appendOutboxEvents(
             toOutboxEvents2(stageRecord.workflowRunId, [
               {
@@ -1199,7 +1522,8 @@ async function handleStagePollSuspended(command, deps) {
                 timestamp: deps.clock.now(),
                 workflowRunId: stageRecord.workflowRunId,
                 error: errorMessage
-              }
+              },
+              ...buildAnnotationEvents(bufferedAnnotations, deps.clock.now())
             ])
           );
         }
@@ -1213,6 +1537,10 @@ async function handleStagePollSuspended(command, deps) {
         }
         continue;
       }
+      if (claimResult.status === "cancelled") {
+        await markStageCancelled(stageRecord.id, deps);
+        continue;
+      }
       failed++;
     }
   }
@@ -1407,7 +1735,69 @@ function createKernel(config) {
       throw error;
     }
   }
-  return { dispatch };
+  const annotations = {
+    async attach(workflowRunId, input) {
+      const scope = input.scope ?? "run";
+      const inputs = [];
+      for (const [key, value] of Object.entries(input.attributes)) {
+        if (value === void 0 || value === null) continue;
+        inputs.push({
+          workflowRunId,
+          workflowStageRecordId: input.workflowStageRecordId ?? null,
+          attempt: input.attempt,
+          scope,
+          scopeId: input.scopeId ?? null,
+          actor: input.actor,
+          key,
+          value,
+          payload: input.payload,
+          idempotencyKey: input.idempotencyKey,
+          emitEvent: input.emitEvent
+        });
+      }
+      if (inputs.length === 0) return;
+      const causationId = input.idempotencyKey ?? crypto.randomUUID();
+      await persistence.withTransaction(async (tx) => {
+        await tx.appendAnnotations(inputs);
+        const events = buildAnnotationEvents(inputs, clock.now());
+        if (events.length > 0) {
+          await tx.appendOutboxEvents(
+            events.map((event) => ({
+              workflowRunId: event.workflowRunId,
+              eventType: event.type,
+              payload: event,
+              causationId,
+              occurredAt: event.timestamp
+            }))
+          );
+        }
+      });
+    },
+    async list(workflowRunId, filters) {
+      const persisted = await persistence.listAnnotations(
+        workflowRunId,
+        filters
+      );
+      if (!filterCouldMatchLegacy(filters ?? {})) return persisted;
+      const migrationCheck = await persistence.listAnnotations(workflowRunId, {
+        keyPrefix: "legacy.metadata.",
+        limit: 1
+      });
+      if (migrationCheck.length > 0) return persisted;
+      const run = await persistence.getRun(workflowRunId);
+      if (!run) return persisted;
+      const synthesized = synthesizeLegacyMetadata(run, filters);
+      if (synthesized.length === 0) return persisted;
+      const merged = [...persisted, ...synthesized].sort((a, b) => {
+        const cmp = a.createdAt.getTime() - b.createdAt.getTime();
+        if (cmp !== 0) return cmp;
+        return a.id.localeCompare(b.id);
+      });
+      const limit = filters?.limit ?? 1e3;
+      return merged.slice(0, limit);
+    }
+  };
+  return { dispatch, annotations };
 }
 
 // src/kernel/plugins.ts
@@ -1437,5 +1827,5 @@ function createPluginRunner(config) {
 }
 
 export { IdempotencyInProgressError, createKernel, createPluginRunner, definePlugin, loadWorkflowContext, saveStageOutput };
-//# sourceMappingURL=chunk-HOGDFLCG.js.map
-//# sourceMappingURL=chunk-HOGDFLCG.js.map
+//# sourceMappingURL=chunk-XPWAEYOO.js.map
+//# sourceMappingURL=chunk-XPWAEYOO.js.map