@lostgradient/weft 0.2.0

package/dist/core/engine/checkpoint-io.js

@@ -0,0 +1,183 @@
+import { KEYS, storageConditionalBatch } from "../../storage/interface.js";
+import {
+  advanceCheckpoint,
+  deserializeCheckpoint,
+  serializeCheckpoint,
+  validateCheckpointRoundTrip
+} from "../checkpoint.js";
+import { encode } from "../codec.js";
+import { EMPTY_EVENT_HEAD, EventLog } from "../event-log.js";
+import {
+  AttributesChangedEvent,
+  CheckpointSizeWarningEvent,
+  DevelopmentWarningEvent
+} from "../events.js";
+import { buildIndexOperations } from "../search-attributes.js";
+import {
+  getCommittedCheckpointBytes,
+  rememberCommittedCheckpointBytes
+} from "./checkpoint-commit-snapshots.js";
+import {
+  appendCompactionOperations,
+  serializeDeletedEntries
+} from "./event-log-compaction.js";
+import { getTimelineInputSummary, getTimelineOperationLabel } from "./state-utilities.js";
+import { buildPendingTimelineOperation } from "./termination.js";
+import { notifyWorkflowFeedCommit } from "./workflow-feed.js";
+export function appendTimelineBatchOperations(internals, workflowId, operation, step, timestamp, operations) {
+  const pendingTimelineOperation = buildPendingTimelineOperation(internals, workflowId), versionTuple = internals.workflowVersionTuples.get(workflowId);
+  if (pendingTimelineOperation)
+    operations.push(pendingTimelineOperation);
+  const entry = {
+    step,
+    operationType: operation.type,
+    operationLabel: getTimelineOperationLabel(operation),
+    inputSummary: getTimelineInputSummary(operation),
+    timestamp,
+    status: "running",
+    ...versionTuple ? { versionTuple } : {}
+  };
+  operations.push({
+    type: "put",
+    key: KEYS.timeline(workflowId, step),
+    value: encode(entry)
+  });
+  return {
+    startedAt: timestamp,
+    entry
+  };
+}
+export async function persistCheckpoint(internals, workflowId, operation, workerCheckpointBytes, callbacks) {
+  if (internals.inlineStrategy?.getContext(workflowId))
+    await persistInlineCheckpoint(internals, workflowId, operation, callbacks);
+  else if (workerCheckpointBytes && workerCheckpointBytes.byteLength > 0)
+    await persistWorkerCheckpoint(internals, workflowId, operation, workerCheckpointBytes, callbacks);
+}
+async function persistInlineCheckpoint(internals, workflowId, operation, callbacks) {
+  const current = internals.checkpoints.get(workflowId), context = internals.inlineStrategy?.getContext(workflowId);
+  if (!current || !context)
+    return;
+  const previousAttributes = { ...current.searchAttributes }, pendingAttributeChanges = context.checkpointPendingAttributeChanges, hasPendingAttributeChanges = context.hasPendingAttributeChanges, advanced = advanceCheckpoint(current, context.checkpointLocals, {
+    accumulatedResults: context.checkpointAccumulatedResults,
+    now: internals.options.getNow(),
+    ...pendingAttributeChanges !== void 0 ? { searchAttributes: pendingAttributeChanges } : {}
+  }), commit = createCheckpointCommit(internals, workflowId, advanced, serializeCheckpoint(advanced));
+  appendAttributeOperations(workflowId, commit, previousAttributes, pendingAttributeChanges, hasPendingAttributeChanges, callbacks);
+  await commitCheckpoint(internals, workflowId, operation, commit, callbacks);
+  if (hasPendingAttributeChanges)
+    callbacks.dispatchEvent(new AttributesChangedEvent(workflowId, { ...pendingAttributeChanges }));
+}
+async function persistWorkerCheckpoint(internals, workflowId, operation, workerCheckpointBytes, callbacks) {
+  const serialized = new Uint8Array(workerCheckpointBytes), checkpoint = deserializeCheckpoint(serialized);
+  await commitCheckpoint(internals, workflowId, operation, createCheckpointCommit(internals, workflowId, checkpoint, serialized), callbacks);
+}
+function createCheckpointCommit(internals, workflowId, checkpoint, serialized) {
+  const operations = [
+    { type: "put", key: KEYS.checkpoint(workflowId), value: serialized }
+  ];
+  if (internals.options.checkpointHistory > 0)
+    operations.push({
+      type: "put",
+      key: KEYS.checkpointHistory(workflowId, checkpoint.step),
+      value: serialized
+    });
+  const expectedSerialized = getCommittedCheckpointBytes(internals, workflowId);
+  return {
+    checkpoint,
+    serialized,
+    ...expectedSerialized !== void 0 ? { expectedSerialized } : {},
+    step: checkpoint.step,
+    timestamp: checkpoint.createdAt,
+    operations
+  };
+}
+function appendAttributeOperations(workflowId, commit, previousAttributes, pendingAttributeChanges, hasPendingAttributeChanges, callbacks) {
+  if (!hasPendingAttributeChanges)
+    return;
+  callbacks.validateAttributeValueSizes(pendingAttributeChanges ?? {});
+  commit.operations.push({
+    type: "put",
+    key: KEYS.attribute(workflowId),
+    value: encode(commit.checkpoint.searchAttributes)
+  });
+  commit.operations.push(...buildIndexOperations(workflowId, previousAttributes, commit.checkpoint.searchAttributes));
+}
+async function commitCheckpoint(internals, workflowId, operation, commit, callbacks) {
+  dispatchCheckpointSizeWarning(internals, workflowId, commit, callbacks);
+  const nextPendingTimelineEntry = callbacks.appendTimelineBatchOperations(workflowId, operation, commit.step, commit.timestamp, commit.operations), { newHead, timestamp } = appendCheckpointEventLog(internals, workflowId, commit), retentionWindow = internals.options.historyPolicy.retentionWindow, compaction = retentionWindow === null ? null : await appendCompactionOperations(internals.storage, workflowId, newHead.sequence, retentionWindow, commit.operations);
+  if (commit.expectedSerialized === void 0 || !internals.storage.capabilities().conditionalBatch)
+    await internals.storage.batch(commit.operations);
+  else
+    await writeCheckpointCommitBatch(internals, workflowId, commit, commit.expectedSerialized);
+  if (commit.expectedSerialized !== void 0)
+    rememberCommittedCheckpointBytes(internals, workflowId, commit.serialized);
+  internals.pendingTimelineEntries.set(workflowId, nextPendingTimelineEntry);
+  internals.checkpoints.set(workflowId, commit.checkpoint);
+  internals.eventLogHeads.set(workflowId, newHead);
+  if (compaction !== null)
+    dispatchCompactionArchival(internals, workflowId, compaction, callbacks);
+  notifyWorkflowFeedCommit(internals, workflowId, "events", {
+    workflowId,
+    selector: "events",
+    kind: "workflow:checkpoint",
+    sequence: newHead.sequence,
+    timestamp,
+    payload: { step: commit.step }
+  });
+  callbacks.swallowPromiseRejection(callbacks.pruneCheckpointHistory(workflowId, commit.step));
+  if (historyEventLimitBreached(internals, newHead.sequence))
+    await callbacks.enforceHistoryCircuitBreaker(workflowId);
+}
+async function writeCheckpointCommitBatch(internals, workflowId, commit, expectedSerialized) {
+  const conditions = [
+    {
+      key: KEYS.checkpoint(workflowId),
+      expectedValue: expectedSerialized
+    }
+  ];
+  if (!await storageConditionalBatch(internals.storage, conditions, commit.operations))
+    throw Error(`Checkpoint commit for workflow "${workflowId}" lost its CAS race against a newer checkpoint.`);
+}
+function historyEventLimitBreached(internals, sequence) {
+  const maxEvents = internals.options.historyPolicy.maxEvents;
+  return maxEvents !== null && sequence + 1 > maxEvents;
+}
+function dispatchCompactionArchival(internals, workflowId, compaction, callbacks) {
+  const adapter = internals.options.archiveAdapter;
+  if (adapter === null || compaction.deletedEntries.length === 0)
+    return;
+  const { from, to } = compaction.deletedRange, key = `events:${from}-${to}`, bytes = serializeDeletedEntries(compaction.deletedEntries);
+  callbacks.swallowPromiseRejection(Promise.resolve().then(() => adapter.store(workflowId, key, bytes)));
+}
+function dispatchCheckpointSizeWarning(internals, workflowId, commit, callbacks) {
+  if (commit.serialized.byteLength >= internals.options.checkpointSizeWarningThreshold)
+    callbacks.dispatchEvent(new CheckpointSizeWarningEvent(workflowId, commit.serialized.byteLength, commit.step));
+}
+function appendCheckpointEventLog(internals, workflowId, commit) {
+  return new EventLog(internals.storage, workflowId).appendToBatch({ type: "workflow:checkpoint", payload: { step: commit.step } }, commit.operations, internals.eventLogHeads.get(workflowId) ?? EMPTY_EVENT_HEAD, internals.workflowVersionTuples.get(workflowId));
+}
+export async function pruneCheckpointHistory(internals, workflowId, currentStep) {
+  const limit = internals.options.checkpointHistory;
+  if (limit <= 0)
+    return;
+  const overflowStep = currentStep - limit;
+  if (overflowStep < 1)
+    return;
+  const key = KEYS.checkpointHistory(workflowId, overflowStep);
+  await internals.storage.delete(key);
+}
+export function validateDevelopmentCheckpoint(internals, workflowId, callbacks) {
+  if (!internals.options.development)
+    return;
+  const context = internals.inlineStrategy?.getContext(workflowId);
+  if (!context)
+    return;
+  const step = context.stepIndex, current = internals.checkpoints.get(workflowId);
+  if (!current)
+    return;
+  const result = validateCheckpointRoundTrip(current);
+  if (!result.valid) {
+    const fieldPaths = result.divergences.map((divergence) => divergence.path), message = `Checkpoint at step ${step} has ${result.divergences.length} non-serializable field(s)`;
+    callbacks.dispatchEvent(new DevelopmentWarningEvent(workflowId, message, fieldPaths));
+  }
+}

package/dist/core/engine/checkpoint-reads.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Read-side queries over a workflow's durable checkpoint, event log, and
+ * timeline. These are inspection/visibility surfaces (no mutation); the write
+ * path lives in `checkpoint-io.ts`.
+ *
+ * @module core/engine/checkpoint-reads
+ */
+import type { CheckpointState, CheckpointSummary, WorkflowEvent, WorkflowReplay, WorkflowTimelineEntry } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+/** Retrieve the event history for a workflow. */
+export declare function getEvents(internals: EngineInternals, workflowId: string): Promise<WorkflowEvent[]>;
+/**
+ * List checkpoint history entries for a workflow, newest first.
+ * Returns summary metadata only — use getCheckpointAt for full state.
+ */
+export declare function listCheckpoints(internals: EngineInternals, workflowId: string): Promise<CheckpointSummary[]>;
+/** Retrieve the full deserialized checkpoint state at a specific step. */
+export declare function getCheckpointAt(internals: EngineInternals, workflowId: string, step: number): Promise<CheckpointState | null>;
+/** Return the durable per-step execution timeline for a workflow. */
+export declare function getTimeline(internals: EngineInternals, workflowId: string): Promise<WorkflowTimelineEntry[]>;
+/** Reconstruct workflow state at a historical checkpoint step. */
+export declare function replayTo(internals: EngineInternals, workflowId: string, step: number): Promise<WorkflowReplay | null>;

package/dist/core/engine/checkpoint-reads.js

@@ -0,0 +1,98 @@
+import { KEYS } from "../../storage/interface.js";
+import { deserializeCheckpoint } from "../checkpoint.js";
+import { decode } from "../codec.js";
+import { sanitizeDebugValueForDisplay } from "../debug-output.js";
+import { EventLog } from "../event-log.js";
+import { readEventLogWatermark } from "./event-log-compaction.js";
+import {
+  sanitizeCheckpointState,
+  sanitizeTimelineSummary,
+  sanitizeWorkflowEventPayload
+} from "./state-utilities.js";
+import { isWorkflowTimelineEntry } from "./validation.js";
+export async function getEvents(internals, workflowId) {
+  const events = [], eventLog = new EventLog(internals.storage, workflowId);
+  for await (const entry of eventLog.scan())
+    events.push({
+      type: entry.type,
+      timestamp: entry.timestamp,
+      data: sanitizeWorkflowEventPayload(entry.payload)
+    });
+  return events;
+}
+export async function listCheckpoints(internals, workflowId) {
+  if (internals.options.checkpointHistory <= 0)
+    return [];
+  const prefix = `${KEYS.checkpoint(workflowId)}:`, summaries = [];
+  for await (const [, value] of internals.storage.scan(prefix, {
+    reverse: !0,
+    limit: internals.options.checkpointHistory
+  })) {
+    const checkpoint = deserializeCheckpoint(value);
+    summaries.push({
+      step: checkpoint.step,
+      timestamp: checkpoint.createdAt,
+      sizeBytes: value.byteLength
+    });
+  }
+  return summaries;
+}
+export async function getCheckpointAt(internals, workflowId, step) {
+  const bytes = await internals.storage.get(KEYS.checkpointHistory(workflowId, step));
+  if (!bytes)
+    return null;
+  const checkpoint = deserializeCheckpoint(bytes);
+  return sanitizeCheckpointState({
+    step: checkpoint.step,
+    locals: checkpoint.locals,
+    searchAttributes: checkpoint.searchAttributes,
+    version: checkpoint.version,
+    createdAt: checkpoint.createdAt
+  });
+}
+export async function getTimeline(internals, workflowId) {
+  const timeline = [];
+  for await (const [, value] of internals.storage.scan(KEYS.timelinePrefix(workflowId))) {
+    let decoded;
+    try {
+      decoded = decode(value);
+    } catch {
+      continue;
+    }
+    if (isWorkflowTimelineEntry(decoded))
+      timeline.push({
+        ...decoded,
+        inputSummary: sanitizeTimelineSummary(decoded.inputSummary) ?? decoded.inputSummary,
+        ...decoded.outputSummary !== void 0 ? {
+          outputSummary: sanitizeTimelineSummary(decoded.outputSummary) ?? decoded.outputSummary
+        } : {}
+      });
+  }
+  timeline.sort((left, right) => left.step - right.step);
+  return timeline;
+}
+export async function replayTo(internals, workflowId, step) {
+  const bytes = await internals.storage.get(KEYS.checkpointHistory(workflowId, step));
+  if (!bytes)
+    return null;
+  const checkpoint = deserializeCheckpoint(bytes), entries = await new EventLog(internals.storage, workflowId).replay(Math.max(step - 1, -1)), watermark = await readEventLogWatermark(internals.storage, workflowId);
+  return {
+    checkpoint: sanitizeCheckpointState({
+      step: checkpoint.step,
+      locals: checkpoint.locals,
+      searchAttributes: checkpoint.searchAttributes,
+      version: checkpoint.version,
+      createdAt: checkpoint.createdAt
+    }),
+    accumulatedResults: checkpoint.accumulatedResults.map(([index, value]) => [
+      index,
+      sanitizeDebugValueForDisplay(value)
+    ]),
+    events: entries.map((entry) => ({
+      type: entry.type,
+      timestamp: entry.timestamp,
+      data: sanitizeWorkflowEventPayload(entry.payload)
+    })),
+    ...watermark !== null ? { compactedBefore: watermark.sequence } : {}
+  };
+}

package/dist/core/engine/child-workflow.d.ts

@@ -0,0 +1,20 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { ComposedWorkflowInterceptor } from '../interceptor.ts';
+import type { StartOptions, WorkflowState } from '../types.ts';
+import type { WorkflowHandle } from './handles.ts';
+import type { EngineInternals } from './internals.ts';
+type ChildWorkflowOperation = Extract<ContextOperationRequest, {
+    type: 'child-workflow';
+}>;
+export type ChildWorkflowOperationCallbacks = {
+    runOperationWithResult: (workflowId: string, operation: ChildWorkflowOperation, execute: () => Promise<unknown>) => Promise<void>;
+    start: (type: string, input: unknown, options?: StartOptions) => Promise<WorkflowHandle>;
+    loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>;
+    getHandle: (workflowId: string) => WorkflowHandle;
+    getComposedWorkflowInterceptor: () => ComposedWorkflowInterceptor | null;
+};
+export declare function processChildWorkflowOperation(internals: EngineInternals, workflowId: string, operation: ChildWorkflowOperation, callbacks: ChildWorkflowOperationCallbacks): Promise<void>;
+export declare function assertChildWorkflowNestingDepth(internals: EngineInternals, workflowId: string): number;
+export declare function getWorkflowNestingDepth(internals: EngineInternals, workflowId: string): number;
+export declare function executeChildWorkflow(internals: EngineInternals, workflowId: string, operation: ChildWorkflowOperation, currentDepth: number, callbacks: Pick<ChildWorkflowOperationCallbacks, 'getComposedWorkflowInterceptor' | 'getHandle' | 'loadWorkflowState' | 'start'>): Promise<unknown>;
+export {};

package/dist/core/engine/child-workflow.js

@@ -0,0 +1,72 @@
+import { WorkflowAlreadyExistsError } from "./errors.js";
+import { encodedValuesEqual } from "./state-utilities.js";
+export async function processChildWorkflowOperation(internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, () => executeChildWorkflow(internals, workflowId, operation, assertChildWorkflowNestingDepth(internals, workflowId), callbacks));
+}
+export function assertChildWorkflowNestingDepth(internals, workflowId) {
+  const currentDepth = getWorkflowNestingDepth(internals, workflowId);
+  if (currentDepth + 1 > internals.options.maxNestingDepth)
+    throw Error(`Child workflow nesting depth exceeded: ${currentDepth + 1} exceeds maximum of ${internals.options.maxNestingDepth}. Configure maxNestingDepth in engine options to increase the limit.`);
+  return currentDepth;
+}
+export function getWorkflowNestingDepth(internals, workflowId) {
+  return internals.inlineStrategy?.getContext(workflowId)?.nestingDepth ?? internals.workflowNestingDepths.get(workflowId) ?? 0;
+}
+function applyPendingChildExecutionContext(internals, context) {
+  internals.pendingNestingDepth = context.pendingNestingDepth;
+  internals.pendingParentHeaders = context.pendingParentHeaders;
+  internals.pendingExecutionStateOwnerId = context.pendingExecutionStateOwnerId;
+}
+function clearPendingChildExecutionContext(internals, context) {
+  if (internals.pendingNestingDepth === context.pendingNestingDepth)
+    internals.pendingNestingDepth = void 0;
+  if (internals.pendingParentHeaders === context.pendingParentHeaders)
+    internals.pendingParentHeaders = void 0;
+  if (internals.pendingExecutionStateOwnerId === context.pendingExecutionStateOwnerId)
+    internals.pendingExecutionStateOwnerId = void 0;
+}
+function existingChildMatchesRequest(existingState, operation, executionStateOwnerId) {
+  return existingState.type === operation.workflowType && encodedValuesEqual(existingState.input, operation.input) && existingState.executionStateOwnerId === executionStateOwnerId;
+}
+async function resolveCollisionChildHandle(childWorkflowId, operation, executionStateOwnerId, collisionError, callbacks) {
+  const existingState = await callbacks.loadWorkflowState(childWorkflowId);
+  if (!existingState)
+    throw collisionError;
+  if (!existingChildMatchesRequest(existingState, operation, executionStateOwnerId))
+    throw Error(`Child workflow id collision for "${childWorkflowId}" does not match the requested child workflow`, { cause: collisionError });
+  return callbacks.getHandle(childWorkflowId);
+}
+async function dispatchChildWorkflowStart(internals, childWorkflowId, operation, context, callbacks) {
+  applyPendingChildExecutionContext(internals, context);
+  try {
+    return await callbacks.start(operation.workflowType, operation.input, {
+      id: childWorkflowId
+    });
+  } catch (error) {
+    if (!(error instanceof WorkflowAlreadyExistsError))
+      throw error;
+    return resolveCollisionChildHandle(childWorkflowId, operation, context.pendingExecutionStateOwnerId, error, callbacks);
+  } finally {
+    clearPendingChildExecutionContext(internals, context);
+  }
+}
+export async function executeChildWorkflow(internals, workflowId, operation, currentDepth, callbacks) {
+  const rawId = operation.options?.id, childWorkflowId = typeof rawId === "string" ? rawId : crypto.randomUUID(), parentHeaders = internals.workflowHeaders.get(workflowId) ?? new Map, executionStateOwnerId = (await callbacks.loadWorkflowState(workflowId))?.executionStateOwnerId ?? workflowId, executeChild = async () => {
+    const context = {
+      pendingNestingDepth: currentDepth + 1,
+      pendingParentHeaders: internals.workflowHeaders.get(workflowId),
+      pendingExecutionStateOwnerId: executionStateOwnerId
+    };
+    return (await dispatchChildWorkflowStart(internals, childWorkflowId, operation, context, callbacks)).result();
+  }, composedInterceptor = callbacks.getComposedWorkflowInterceptor();
+  if (!composedInterceptor)
+    return executeChild();
+  return composedInterceptor.childWorkflow({
+    workflowId,
+    childWorkflowId,
+    workflowType: operation.workflowType,
+    input: operation.input,
+    headers: new Map,
+    parentHeaders
+  }, executeChild);
+}

package/dist/core/engine/completed-review-storage.d.ts

@@ -0,0 +1,14 @@
+import type { Storage } from '../../storage/interface.ts';
+import type { HumanReviewResult, ReviewRequest } from '../review/index.ts';
+import type { CompletedReviewEntry, ReviewListFilter } from '../types.ts';
+type ReviewListFilterableEntry = {
+    workflowId?: string;
+    reviewType?: string;
+};
+export declare function matchesReviewListFilter(review: ReviewListFilterableEntry, filter: ReviewListFilter): boolean;
+export declare function completedReviewStoragePrefix(workflowId?: string): string;
+export declare function completedReviewStorageKey(workflowId: string, reviewId: string): string;
+export declare function listCompletedReviewsFromStorage(storage: Storage, filter: ReviewListFilter): Promise<CompletedReviewEntry[]>;
+export declare function persistCompletedReviewRecord(storage: Storage, reviewKey: string, reviewData: ReviewRequest, decisionResult: HumanReviewResult): Promise<void>;
+export declare function deleteCompletedReviewsForWorkflow(storage: Storage, workflowId: string): Promise<void>;
+export {};

package/dist/core/engine/completed-review-storage.js

@@ -0,0 +1,61 @@
+import { encodeStorageKeyComponent } from "../../storage/interface.js";
+import { encode } from "../codec.js";
+import { parseCompletedReviewEntry, toCompletedReviewEntry } from "./review-list-entries.js";
+export function matchesReviewListFilter(review, filter) {
+  if (filter.workflowId !== void 0 && review.workflowId !== filter.workflowId)
+    return !1;
+  if (filter.reviewType !== void 0 && review.reviewType !== filter.reviewType)
+    return !1;
+  return !0;
+}
+export function completedReviewStoragePrefix(workflowId) {
+  if (workflowId === void 0)
+    return "review-decision:";
+  return `review-decision:${encodeStorageKeyComponent(workflowId)}:`;
+}
+export function completedReviewStorageKey(workflowId, reviewId) {
+  return `${completedReviewStoragePrefix(workflowId)}${encodeStorageKeyComponent(reviewId)}`;
+}
+async function appendCompletedReviews(reviews, entries, filter, keyPredicate = () => !0) {
+  for await (const [key, value] of entries) {
+    if (!keyPredicate(key))
+      continue;
+    const completedReview = parseCompletedReviewEntry(value);
+    if (completedReview !== null && matchesReviewListFilter(completedReview, filter))
+      reviews.push(completedReview);
+  }
+}
+export async function listCompletedReviewsFromStorage(storage, filter) {
+  const reviews = [], scopedPrefix = filter.workflowId === void 0 ? null : completedReviewStoragePrefix(filter.workflowId);
+  if (scopedPrefix !== null)
+    await appendCompletedReviews(reviews, storage.scan(scopedPrefix), filter);
+  await appendCompletedReviews(reviews, storage.scan("review-decision:"), filter, (key) => scopedPrefix === null || !key.startsWith(scopedPrefix));
+  return reviews;
+}
+export async function persistCompletedReviewRecord(storage, reviewKey, reviewData, decisionResult) {
+  const completedReview = toCompletedReviewEntry(reviewData, decisionResult);
+  await storage.batch([
+    {
+      type: "put",
+      key: completedReviewStorageKey(reviewData.workflowId, reviewData.reviewId),
+      value: encode(completedReview)
+    },
+    { type: "delete", key: reviewKey }
+  ]);
+}
+export async function deleteCompletedReviewsForWorkflow(storage, workflowId) {
+  const completedPrefix = completedReviewStoragePrefix(workflowId), deleteOperations = [];
+  if (storage.deletePrefix)
+    await storage.deletePrefix(completedPrefix);
+  else
+    for await (const [key] of storage.scan(completedPrefix))
+      deleteOperations.push({ type: "delete", key });
+  for await (const [key, value] of storage.scan("review-decision:")) {
+    if (key.startsWith(completedPrefix))
+      continue;
+    if (parseCompletedReviewEntry(value)?.workflowId === workflowId)
+      deleteOperations.push({ type: "delete", key });
+  }
+  if (deleteOperations.length > 0)
+    await storage.batch(deleteOperations);
+}

package/dist/core/engine/constraints.d.ts

@@ -0,0 +1,24 @@
+import type { OperationOutcome } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+import type { CapturedRejectionReason } from './strategy-helpers.ts';
+export type ConstraintCallbacks = {
+    cancelWorkflowInStrategy: (workflowId: string) => void;
+    dispatchEvent: (event: Event) => boolean;
+    failWorkflow: (workflowId: string, error: Error) => Promise<void>;
+    feedOperationResult: (workflowId: string, outcome: OperationOutcome, originalError?: CapturedRejectionReason) => void;
+};
+/**
+ * Evaluate all registered constraints for a workflow at the current checkpoint.
+ *
+ * Returns `true` if any constraint was violated and a 'fail' or 'compensate'
+ * reaction was triggered (meaning the operation should not proceed). Returns
+ * `false` if all constraints passed or only 'warn' violations occurred.
+ *
+ * **Note**: Constraints are only evaluated when the inline execution strategy
+ * is active. Worker execution mode cannot reach this code path with
+ * constraints present — `register()` throws at registration time if
+ * constraints are supplied while `inlineStrategy` is `null`, so the
+ * `!context` guard here only fires for benign cases (e.g. the workflow has
+ * already terminated or the context was cleared mid-evaluation).
+ */
+export declare function evaluateConstraints(internals: EngineInternals, workflowId: string, callbacks: ConstraintCallbacks): Promise<boolean>;

package/dist/core/engine/constraints.js

@@ -0,0 +1,57 @@
+import { ConstraintViolatedEvent } from "../events.js";
+export async function evaluateConstraints(internals, workflowId, callbacks) {
+  const context = internals.inlineStrategy?.getContext(workflowId);
+  if (!context)
+    return !1;
+  const constraints = internals.registrations.get(context.workflowType)?.constraints;
+  if (!constraints || constraints.length === 0)
+    return !1;
+  const stateSnapshot = {
+    id: workflowId,
+    type: context.workflowType,
+    status: "running"
+  };
+  for (const definition of constraints) {
+    if (!await isConstraintViolated(definition, stateSnapshot))
+      continue;
+    dispatchConstraintViolation(callbacks, workflowId, definition);
+    if (definition.onViolation === "warn") {
+      warnConstraintViolation(workflowId, definition);
+      continue;
+    }
+    const violationError = Error(`Constraint violated: ${definition.name} (scope: ${definition.scope})`);
+    if (definition.onViolation === "fail")
+      await failConstraintViolation(callbacks, workflowId, violationError);
+    else
+      compensateConstraintViolation(callbacks, workflowId, violationError);
+    return !0;
+  }
+  return !1;
+}
+async function isConstraintViolated(definition, stateSnapshot) {
+  try {
+    const result = definition.check(stateSnapshot);
+    return !(result instanceof Promise ? await result : result);
+  } catch (error) {
+    console.warn(`[weft] Constraint "${definition.name}" check() threw an error:`, error);
+    return !0;
+  }
+}
+function dispatchConstraintViolation(callbacks, workflowId, definition) {
+  callbacks.dispatchEvent(new ConstraintViolatedEvent(workflowId, definition.name, definition.scope, definition.onViolation));
+}
+function warnConstraintViolation(workflowId, definition) {
+  console.warn(`[weft] Constraint "${definition.name}" (scope: ${definition.scope}) violated on workflow "${workflowId}" \u2014 continuing (onViolation: 'warn')`);
+}
+async function failConstraintViolation(callbacks, workflowId, violationError) {
+  callbacks.cancelWorkflowInStrategy(workflowId);
+  await callbacks.failWorkflow(workflowId, violationError);
+}
+function compensateConstraintViolation(callbacks, workflowId, violationError) {
+  callbacks.feedOperationResult(workflowId, {
+    status: "failed",
+    error: violationError.message,
+    errorName: violationError.name,
+    failureCategory: "application"
+  }, { value: violationError });
+}

package/dist/core/engine/construction.d.ts

@@ -0,0 +1,60 @@
+import { AlertManager } from '../../alerting/alert-manager.ts';
+import type { Storage as WeftStorage } from '../../storage/interface.ts';
+import { ActivityWorkerDispatcher } from '../../workers/activity-worker-dispatcher.ts';
+import type { ComposedWorkflowInterceptor, Interceptor } from '../interceptor.ts';
+import { type AnyActivityDefinition, type AnyWorkflowDefinition, type EngineOptions, type RegisteredWorkflowDefinition } from '../types.ts';
+import type { EngineConstructorOptions, ExecutionStrategyBundle, RegistrationEntry, ResolvedOptions } from './engine-internal-types.ts';
+export type KnownWorkflowNames<TWorkflows extends object> = Extract<keyof TWorkflows, string>;
+declare const emptyWorkflowDefinitions: unique symbol;
+declare const emptyActivityDefinitions: unique symbol;
+export type EmptyWorkflowDefinitions = Record<string, never> & {
+    readonly [emptyWorkflowDefinitions]: true;
+};
+export type EmptyActivityDefinitions = Record<string, never> & {
+    readonly [emptyActivityDefinitions]: true;
+};
+export type EngineCreateRuntimeOptions = EngineConstructorOptions & {
+    activities?: Record<string, AnyActivityDefinition> | undefined;
+    workflows?: Record<string, AnyWorkflowDefinition> | undefined;
+    recover?: boolean | undefined;
+    acknowledgeUnknownWorkflowTypes?: boolean | undefined;
+    allowLegacyData?: boolean | undefined;
+};
+export type NormalizedWorkerExecutionConfiguration = {
+    mode: 'inline';
+    workerExecution: null;
+} | {
+    mode: 'worker';
+    workerExecution: NonNullable<EngineConstructorOptions['workerExecution']>;
+    workflowTurnTimeoutMs: number;
+    maxProtocolMessageBytes: number;
+    requireProtocolVersion: true;
+    discardOnCancel: true;
+};
+export declare function definitionEntries<TDefinition extends object>(definitions: Record<string, TDefinition> | undefined): Array<[string, TDefinition]>;
+export declare function typedEngineView<TViewWorkflows extends object, TViewActivities extends object>(engine: object, _phantomTypes?: readonly [TViewWorkflows, TViewActivities]): never;
+export declare function readEnvironmentVariableFromSources(name: string, sources: {
+    bunEnv?: Record<string, string | undefined> | undefined;
+    processEnv?: Record<string, string | undefined> | undefined;
+}): string | undefined;
+/** Test-only reset of the one-shot MemoryStorage-fallback warning latch. */
+export declare function resetMemoryStorageFallbackWarningForTesting(): void;
+export declare function resolveEngineStorage(options?: EngineConstructorOptions): WeftStorage;
+export declare function resolveEngineInterceptors(options?: EngineConstructorOptions): Interceptor[];
+export declare function copyWorkflowDefinition(type: string, registration: RegistrationEntry): RegisteredWorkflowDefinition;
+export declare function resolveEngineOptions(storage: WeftStorage, options: EngineConstructorOptions | undefined, getNow: () => number): ResolvedOptions;
+export declare function normalizeWorkerExecutionConfiguration(options: EngineConstructorOptions | undefined): NormalizedWorkerExecutionConfiguration;
+export declare function createExecutionStrategyBundle(parameters: {
+    options: EngineConstructorOptions | undefined;
+    getNow: () => number;
+    maxNestingDepth: number;
+    development: boolean;
+    broadcastEvents: boolean;
+    getRegistration: (workflowType: string) => RegistrationEntry | undefined;
+    getComposedWorkflowInterceptor?: () => ComposedWorkflowInterceptor | null;
+    resolveWorkflowType: (target: string | Function) => string;
+    registerCancelHandler?: (workflowId: string, handler: () => Promise<void> | void) => () => void;
+}): ExecutionStrategyBundle;
+export declare function createActivityWorkerDispatcher(activityExecution: EngineConstructorOptions['activityExecution']): ActivityWorkerDispatcher | null;
+export declare function createAlertManagerForEngine(engine: EventTarget, alerts: EngineOptions['alerts'] | undefined, getNow: () => number): AlertManager | null;
+export {};