@lostgradient/weft 0.2.0

package/dist/core/engine/aggregate.js

@@ -0,0 +1,132 @@
+import { KEYS } from "../../storage/interface.js";
+import {
+  AGGREGATE_DEFAULT_LIMIT,
+  AggregateDistinctKeyCapExceededError,
+  MAX_AGGREGATE_DISTINCT_KEYS,
+  normalizeAggregateOptions
+} from "../aggregate-validation.js";
+import { decode } from "../codec.js";
+import { normalizeListFilter } from "../list-filter-validation.js";
+import { WeftError } from "../weft-error.js";
+import { normalizeWorkflowTags } from "../workflow-tags.js";
+import { resolveListCandidateIds } from "./list-candidate-resolution.js";
+import { matchesListFilter } from "./state-utilities.js";
+import { decodeWorkflowState } from "./validation.js";
+import { MAX_LIST_SCAN_ROWS, WorkflowListScanCapExceededError } from "./workflow-indexes.js";
+import { isTopLevelWorkflowStateKey } from "./workflow-state-stream.js";
+const ATTRIBUTE_VALUE_TO_KEY = (value) => {
+  if (value === void 0 || value === null)
+    return null;
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  if (value instanceof Date)
+    return value.toISOString();
+  if (Array.isArray(value))
+    return value.join(",");
+  return String(value);
+};
+async function resolveDimensionKey(internals, state, groupBy) {
+  if (groupBy === "status")
+    return state.status;
+  if (groupBy === "type")
+    return state.type;
+  if (groupBy === "failureCategory")
+    return state.failureCategory ?? null;
+  const attributeBytes = await internals.storage.get(KEYS.attribute(state.id));
+  if (!attributeBytes)
+    return null;
+  const attributes = decode(attributeBytes);
+  return ATTRIBUTE_VALUE_TO_KEY(attributes[groupBy.attribute]);
+}
+
+export class UnknownAggregateAttributeError extends WeftError {
+  attribute;
+  constructor(attribute) {
+    super("UnknownAggregateAttributeError", `Unknown search attribute "${attribute}". Aggregate groupBy requires a declared attribute.`);
+    this.attribute = attribute;
+  }
+}
+function validateAttributeDimension(internals, attributeName) {
+  let anySchemaDeclared = !1, attributeFound = !1;
+  for (const registration of internals.registrations.values())
+    if (registration.searchAttributes !== void 0) {
+      anySchemaDeclared = !0;
+      if (attributeName in registration.searchAttributes) {
+        attributeFound = !0;
+        break;
+      }
+    }
+  if (anySchemaDeclared && !attributeFound)
+    throw new UnknownAggregateAttributeError(attributeName);
+}
+function validateAggregateInputs(internals, filter, options, executionOptions) {
+  const normalizedFilter = normalizeListFilter({ ...filter, limit: void 0, offset: void 0 }), normalizedOptions = normalizeAggregateOptions(options), { groupBy } = normalizedOptions;
+  if (typeof groupBy === "object")
+    validateAttributeDimension(internals, groupBy.attribute);
+  return {
+    normalizedFilter,
+    groupBy,
+    requestedLimit: normalizedOptions.limit ?? AGGREGATE_DEFAULT_LIMIT,
+    distinctKeyCap: executionOptions.distinctKeyCap ?? MAX_AGGREGATE_DISTINCT_KEYS
+  };
+}
+async function accumulateAggregateState(internals, state, groupBy, distinctKeyCap, accumulator) {
+  const key = await resolveDimensionKey(internals, state, groupBy), current = accumulator.counts.get(key);
+  if (current === void 0) {
+    if (accumulator.counts.size >= distinctKeyCap)
+      throw new AggregateDistinctKeyCapExceededError(distinctKeyCap);
+    accumulator.counts.set(key, 1);
+  } else
+    accumulator.counts.set(key, current + 1);
+  accumulator.total += 1;
+}
+async function accumulateFromConstrainedIds(internals, constrainedIds, normalizedFilter, normalizedTagFilters, groupBy, distinctKeyCap, accumulator) {
+  if (constrainedIds.size > MAX_LIST_SCAN_ROWS)
+    throw new WorkflowListScanCapExceededError(MAX_LIST_SCAN_ROWS);
+  for (const workflowId of constrainedIds) {
+    const stateBytes = await internals.storage.get(KEYS.workflow(workflowId));
+    if (!stateBytes)
+      continue;
+    const state = decodeWorkflowState(stateBytes);
+    if (!matchesListFilter(state, normalizedFilter, constrainedIds, normalizedTagFilters))
+      continue;
+    await accumulateAggregateState(internals, state, groupBy, distinctKeyCap, accumulator);
+  }
+}
+async function accumulateFromFullScan(internals, normalizedFilter, normalizedTagFilters, groupBy, distinctKeyCap, accumulator) {
+  let scanned = 0;
+  for await (const [storageKey, value] of internals.storage.scan("wf:")) {
+    if (!isTopLevelWorkflowStateKey(storageKey))
+      continue;
+    scanned += 1;
+    if (scanned > MAX_LIST_SCAN_ROWS)
+      throw new WorkflowListScanCapExceededError(MAX_LIST_SCAN_ROWS);
+    const state = decodeWorkflowState(value);
+    if (!matchesListFilter(state, normalizedFilter, null, normalizedTagFilters))
+      continue;
+    await accumulateAggregateState(internals, state, groupBy, distinctKeyCap, accumulator);
+  }
+}
+function finalizeAggregateResult(accumulator, requestedLimit) {
+  const sortedGroups = [...accumulator.counts.entries()].map(([groupKey, count]) => ({ key: groupKey, count })).toSorted((left, right) => {
+    if (left.count !== right.count)
+      return right.count - left.count;
+    const leftKey = left.key ?? "", rightKey = right.key ?? "";
+    if (leftKey < rightKey)
+      return -1;
+    if (leftKey > rightKey)
+      return 1;
+    return 0;
+  }), truncated = sortedGroups.length > requestedLimit, groups = truncated ? sortedGroups.slice(0, requestedLimit) : sortedGroups;
+  return { total: accumulator.total, groups, truncated };
+}
+export async function aggregate(internals, filter, options, executionOptions = {}) {
+  const { normalizedFilter, groupBy, requestedLimit, distinctKeyCap } = validateAggregateInputs(internals, filter, options, executionOptions), normalizedTagFilters = normalizeWorkflowTags(normalizedFilter.tags), constrainedIds = await resolveListCandidateIds(internals, normalizedFilter, normalizedTagFilters), accumulator = { counts: new Map, total: 0 };
+  if (constrainedIds !== null)
+    await accumulateFromConstrainedIds(internals, constrainedIds, normalizedFilter, normalizedTagFilters, groupBy, distinctKeyCap, accumulator);
+  else
+    await accumulateFromFullScan(internals, normalizedFilter, normalizedTagFilters, groupBy, distinctKeyCap, accumulator);
+  return finalizeAggregateResult(accumulator, requestedLimit);
+}

package/dist/core/engine/anonymous-signal-sequence.d.ts

@@ -0,0 +1,4 @@
+import type { BatchOperation } from '../../storage/interface.ts';
+import type { EngineInternals } from './internals.ts';
+import type { BufferedSignalDelivery } from './signals.ts';
+export declare function commitAnonymousSignalOperations(internals: EngineInternals, workflowId: string, deliveries: BufferedSignalDelivery[], appendTerminalCleanupOperation: (operations: BatchOperation[]) => void, markTerminalCleanupTracked: () => void): Promise<void>;

package/dist/core/engine/anonymous-signal-sequence.js

@@ -0,0 +1,101 @@
+import {
+  KEYS,
+  encodeStorageKeyComponent,
+  requireStorageCapability,
+  storageConditionalBatch
+} from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { encodePayloadWithinLimit } from "../payload-size.js";
+const MAX_SIGNAL_SEQUENCE_COMMIT_ATTEMPTS = 5, anonymousSignalSequenceLocks = new WeakMap;
+export async function commitAnonymousSignalOperations(internals, workflowId, deliveries, appendTerminalCleanupOperation, markTerminalCleanupTracked) {
+  const sequenceKey = KEYS.signalSequence(workflowId);
+  if (!internals.storage.capabilities().conditionalBatch) {
+    await runWithAnonymousSignalSequenceLock(internals.storage, workflowId, async () => {
+      const currentSequenceBytes = await internals.storage.get(sequenceKey), nextSequence = await deriveNextAnonymousSignalSequence(internals, workflowId, currentSequenceBytes), operations = createAnonymousSignalOperations(internals, workflowId, deliveries, nextSequence, sequenceKey);
+      appendTerminalCleanupOperation(operations);
+      await internals.storage.batch(operations);
+      markTerminalCleanupTracked();
+    });
+    return;
+  }
+  requireStorageCapability(internals.storage, "conditionalBatch", "anonymous signal ordering");
+  for (let attempt = 0;attempt < MAX_SIGNAL_SEQUENCE_COMMIT_ATTEMPTS; attempt += 1) {
+    const currentSequenceBytes = await internals.storage.get(sequenceKey), nextSequence = await deriveNextAnonymousSignalSequence(internals, workflowId, currentSequenceBytes), operations = createAnonymousSignalOperations(internals, workflowId, deliveries, nextSequence, sequenceKey);
+    appendTerminalCleanupOperation(operations);
+    if (await storageConditionalBatch(internals.storage, [{ key: sequenceKey, expectedValue: currentSequenceBytes }], operations)) {
+      markTerminalCleanupTracked();
+      return;
+    }
+  }
+  throw Error(`Could not allocate anonymous signal sequence for workflow "${workflowId}" after ${MAX_SIGNAL_SEQUENCE_COMMIT_ATTEMPTS} attempts`);
+}
+async function runWithAnonymousSignalSequenceLock(storage, workflowId, operation) {
+  let storageLocks = anonymousSignalSequenceLocks.get(storage);
+  if (!storageLocks) {
+    storageLocks = new Map;
+    anonymousSignalSequenceLocks.set(storage, storageLocks);
+  }
+  const previous = storageLocks.get(workflowId) ?? Promise.resolve();
+  let releaseCurrentLock;
+  const current = new Promise((resolve) => {
+    releaseCurrentLock = resolve;
+  }), lockChain = previous.then(() => current, () => current);
+  storageLocks.set(workflowId, lockChain);
+  try {
+    await previous.catch(() => {});
+    await operation();
+  } finally {
+    releaseCurrentLock();
+    if (storageLocks.get(workflowId) === lockChain)
+      storageLocks.delete(workflowId);
+  }
+}
+function createAnonymousSignalOperations(internals, workflowId, deliveries, nextSequence, sequenceKey) {
+  const operations = deliveries.map(({ signalName, payload }, index) => ({
+    type: "put",
+    key: KEYS.signal(workflowId, signalName, generatedSignalId(nextSequence + index)),
+    value: encodePayloadWithinLimit(payload, internals.options.payloadSizePolicy.maxBytes, "signal payload")
+  }));
+  operations.push({
+    type: "put",
+    key: sequenceKey,
+    value: encode(nextSequence + deliveries.length)
+  });
+  return operations;
+}
+function generatedSignalId(sequenceValue) {
+  return `anonymous:${String(sequenceValue).padStart(16, "0")}:${crypto.randomUUID()}`;
+}
+async function deriveNextAnonymousSignalSequence(internals, workflowId, currentSequenceBytes) {
+  if (currentSequenceBytes !== null)
+    return decodeSignalSequence(currentSequenceBytes);
+  return scanNextAnonymousSignalSequence(internals, workflowId);
+}
+async function scanNextAnonymousSignalSequence(internals, workflowId) {
+  const prefix = `sig:${encodeStorageKeyComponent(workflowId)}:`;
+  let nextSequence = 0;
+  for await (const [key] of internals.storage.scan(prefix)) {
+    const sequence = extractAnonymousSignalSequence(key);
+    if (sequence !== null && sequence >= nextSequence)
+      nextSequence = sequence + 1;
+  }
+  return nextSequence;
+}
+function extractAnonymousSignalSequence(key) {
+  const marker = ":anonymous%3A", markerIndex = key.lastIndexOf(marker);
+  if (markerIndex === -1)
+    return null;
+  const sequenceStart = markerIndex + marker.length, sequenceEnd = key.indexOf("%3A", sequenceStart);
+  if (sequenceEnd === -1)
+    return null;
+  const sequence = Number(key.slice(sequenceStart, sequenceEnd));
+  return Number.isSafeInteger(sequence) && sequence >= 0 ? sequence : null;
+}
+function decodeSignalSequence(bytes) {
+  if (bytes === null)
+    return 0;
+  const value = decode(bytes);
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+    throw Error("Stored anonymous signal sequence must be a non-negative safe integer");
+  return value;
+}

package/dist/core/engine/async-activity-completion.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Out-of-band ("async") activity completion.
+ *
+ * An activity can hand its work off to an external system — a webhook, a human
+ * callback, a third-party async job — by calling `ctx.completeAsync()` on its
+ * {@link ActivityContext}. That call throws an {@link AsyncActivityDeferral}
+ * sentinel which the engine catches: instead of completing or failing the
+ * activity operation (which would resume the workflow), the engine records a
+ * pending entry keyed by a durable, deterministic task token and leaves the
+ * workflow suspended at that step.
+ *
+ * Some external system later resolves the activity by token through
+ * `engine.completeAsyncActivity(token, result)` or
+ * `engine.failAsyncActivity(token, error)`. Completion resumes the workflow
+ * generator with the supplied value; failure throws the supplied error into the
+ * generator (the same path an inline activity failure takes, so the workflow's
+ * retry/catch handling applies unchanged).
+ *
+ * Durability: the pending entry is persisted under
+ * {@link KEYS.asyncActivity}. The token is derived from the workflow id, the
+ * deterministic workflow step index, and the activity attempt, so it is stable
+ * across replay. After an engine restart, `recoverAll()` replays the workflow
+ * from its checkpoint; the deferred activity re-runs, re-defers, and produces
+ * the *same* token. A callback that arrives after the crash therefore still
+ * resolves the correct activity.
+ *
+ * Internal-only. Imported from `src/core/engine/**` and the `ActivityContext`
+ * construction path.
+ */
+import type { OperationOutcome } from '../types.ts';
+import { WeftError } from '../weft-error.ts';
+import type { EngineInternals } from './internals.ts';
+/**
+ * Per-workflow prefix for all async-activity storage keys. Used by cleanup and
+ * purge paths that need to sweep every async-activity record for a workflow
+ * without enumerating individual tokens.
+ */
+export declare function asyncActivityWorkflowPrefix(workflowId: string): string;
+/**
+ * Sentinel thrown by `ActivityContext.completeAsync()` to signal that the
+ * activity is handing off to an out-of-band completion. The engine recognizes
+ * this exact class (not a generic `Error`) and parks the activity rather than
+ * treating it as a failure. The `token` is the durable task token an external
+ * system uses to complete the activity later.
+ */
+export declare class AsyncActivityDeferral extends Error {
+    readonly token: string;
+    constructor(token: string);
+}
+/**
+ * Thrown by {@link Engine.completeAsyncActivity} and
+ * {@link Engine.failAsyncActivity} when no pending async activity matches the
+ * supplied token. This covers unknown tokens, tokens for a different engine's
+ * workflows, and tokens that were already completed or failed (each token is
+ * single-use).
+ *
+ * @example
+ * ```ts
+ * import { AsyncActivityTokenNotFoundError } from '@lostgradient/weft';
+ *
+ * function isStaleCallbackToken(error: unknown): boolean {
+ *   return error instanceof AsyncActivityTokenNotFoundError;
+ * }
+ * ```
+ */
+export declare class AsyncActivityTokenNotFoundError extends WeftError<'AsyncActivityTokenNotFoundError'> {
+    readonly token: string;
+    constructor(token: string);
+}
+/**
+ * In-memory record of an activity that deferred to out-of-band completion and
+ * is awaiting `completeAsyncActivity` / `failAsyncActivity`.
+ */
+export type PendingAsyncActivity = {
+    readonly token: string;
+    readonly workflowId: string;
+    readonly activityName: string;
+    readonly operationId: string;
+    readonly step: number;
+    readonly attempt: number;
+    readonly createdAt: number;
+};
+/**
+ * Derive the durable, deterministic task token for an async activity.
+ *
+ * The token is anchored to the workflow id, the workflow step index, and the
+ * dispatch attempt — all of which are stable across replay — so a workflow that
+ * crashes while parked on an async activity mints the identical token after
+ * recovery. `operationId` is deliberately excluded because it is regenerated on
+ * every yield and would change on replay.
+ */
+export declare function deriveAsyncActivityToken(workflowId: string, step: number, attempt: number): string;
+/**
+ * Register a deferred activity: record it in memory and durably, then announce
+ * the token via {@link ActivityAsyncPendingEvent}. Idempotent on `token`: if the
+ * token is already registered (e.g. because `recoverPendingAsyncActivities` loaded
+ * it before the workflow replayed and re-deferred), the durable record is
+ * refreshed but the event is NOT re-emitted, preventing duplicate side-effects
+ * (e.g. re-sending a webhook notification) on replay.
+ */
+export declare function registerPendingAsyncActivity(internals: EngineInternals, pending: PendingAsyncActivity): Promise<void>;
+/**
+ * Park an activity that threw {@link AsyncActivityDeferral}: register the
+ * pending entry durably and return a promise that never settles, so the
+ * surrounding `runOperationWithResult` leaves the workflow suspended until an
+ * out-of-band completion resumes it. Keeps the operation-pipeline catch site a
+ * one-liner.
+ */
+export declare function parkDeferredAsyncActivity(internals: EngineInternals, deferral: AsyncActivityDeferral, details: Omit<PendingAsyncActivity, 'token' | 'createdAt'>): Promise<never>;
+/**
+ * Reload pending async-activity records from storage into memory. Called by
+ * `recoverAll()` so a token minted before a crash is resolvable again — even
+ * before the recovered workflow has replayed far enough to re-register it.
+ */
+export declare function recoverPendingAsyncActivities(internals: EngineInternals): Promise<void>;
+/**
+ * Complete a deferred activity out-of-band with `result`, resuming the parked
+ * workflow as though the activity had returned `result` inline.
+ */
+export declare function completeAsyncActivity(internals: EngineInternals, token: string, result: unknown, feedOperationResult: (workflowId: string, outcome: OperationOutcome) => void, finalizeTimeline: (workflowId: string, status: 'completed' | 'failed', output: unknown) => void): Promise<void>;
+/**
+ * Drive a generator that may yield promises — the workflow interceptor's
+ * `activity` hook returns such a generator. Forwards rejections into the
+ * generator so try/catch/finally blocks inside the interceptor run correctly
+ * instead of being abandoned.
+ *
+ * Placed here to reduce the line count of operations-activity.ts (which was
+ * approaching the 500-line lint ceiling). The function is used only from
+ * `executeActivity` in operations-activity.ts and has no coupling to the async
+ * activity completion logic — it is a general generator-driving utility.
+ */
+export declare function driveWorkflowInterceptorGenerator(generator: Generator<unknown, unknown, unknown>): Promise<unknown>;
+/**
+ * Fail a deferred activity out-of-band with `error`. The error is thrown into
+ * the workflow generator at the parked step — identical to an inline activity
+ * that threw — so the workflow's own try/catch and any configured retry policy
+ * apply unchanged.
+ */
+export declare function failAsyncActivity(internals: EngineInternals, token: string, error: unknown, feedOperationResult: (workflowId: string, outcome: OperationOutcome, originalReason?: {
+    value: unknown;
+}) => void, finalizeTimeline: (workflowId: string, status: 'completed' | 'failed', output: unknown) => void): Promise<void>;

package/dist/core/engine/async-activity-completion.js

@@ -0,0 +1,131 @@
+import { KEYS, encodeStorageKeyComponent } from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { ActivityAsyncPendingEvent } from "../events.js";
+import { assertPayloadWithinLimit } from "../payload-size.js";
+import { WeftError } from "../weft-error.js";
+const ASYNC_ACTIVITY_TOKEN_PREFIX = "async-act:v1", ASYNC_ACTIVITY_KEY_PREFIX = "async-act:v1:";
+export function asyncActivityWorkflowPrefix(workflowId) {
+  return `${ASYNC_ACTIVITY_KEY_PREFIX}${encodeStorageKeyComponent(workflowId)}:`;
+}
+
+export class AsyncActivityDeferral extends Error {
+  token;
+  constructor(token) {
+    super(`Activity deferred to out-of-band completion (token "${token}"). Complete it via engine.completeAsyncActivity(token, result) or engine.failAsyncActivity(token, error).`);
+    this.name = "AsyncActivityDeferral";
+    this.token = token;
+  }
+}
+
+export class AsyncActivityTokenNotFoundError extends WeftError {
+  token;
+  constructor(token) {
+    super("AsyncActivityTokenNotFoundError", `No pending async activity found for token "${token}". The token may be unknown, already completed, or already failed (tokens are single-use).`);
+    this.token = token;
+  }
+}
+function isPersistedAsyncActivity(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  const record = value;
+  return record.version === 1 && typeof record.token === "string" && typeof record.workflowId === "string" && typeof record.activityName === "string" && typeof record.operationId === "string" && typeof record.step === "number" && typeof record.attempt === "number" && typeof record.createdAt === "number";
+}
+export function deriveAsyncActivityToken(workflowId, step, attempt) {
+  return `${ASYNC_ACTIVITY_TOKEN_PREFIX}:${workflowId}:${step}:${attempt}`;
+}
+function persistPendingAsyncActivity(storage, pending) {
+  const record = {
+    version: 1,
+    token: pending.token,
+    workflowId: pending.workflowId,
+    activityName: pending.activityName,
+    operationId: pending.operationId,
+    step: pending.step,
+    attempt: pending.attempt,
+    createdAt: pending.createdAt
+  };
+  return storage.put(KEYS.asyncActivity(pending.workflowId, pending.token), encode(record));
+}
+export async function registerPendingAsyncActivity(internals, pending) {
+  const alreadyRegistered = internals.pendingAsyncActivities.has(pending.token);
+  internals.pendingAsyncActivities.set(pending.token, pending);
+  await persistPendingAsyncActivity(internals.storage, pending);
+  if (!alreadyRegistered)
+    internals.engine.dispatchEvent(new ActivityAsyncPendingEvent(pending.token, pending.operationId, pending.workflowId, pending.activityName, pending.attempt));
+}
+export async function parkDeferredAsyncActivity(internals, deferral, details) {
+  await registerPendingAsyncActivity(internals, {
+    token: deferral.token,
+    createdAt: internals.options.getNow(),
+    ...details
+  });
+  return new Promise(() => {});
+}
+export async function recoverPendingAsyncActivities(internals) {
+  for await (const [, bytes] of internals.storage.scan(ASYNC_ACTIVITY_KEY_PREFIX)) {
+    const decoded = decode(bytes);
+    if (!isPersistedAsyncActivity(decoded))
+      continue;
+    internals.pendingAsyncActivities.set(decoded.token, {
+      token: decoded.token,
+      workflowId: decoded.workflowId,
+      activityName: decoded.activityName,
+      operationId: decoded.operationId,
+      step: decoded.step,
+      attempt: decoded.attempt,
+      createdAt: decoded.createdAt
+    });
+  }
+}
+async function consumePendingAsyncActivity(internals, token) {
+  const pending = internals.pendingAsyncActivities.get(token);
+  if (!pending)
+    throw new AsyncActivityTokenNotFoundError(token);
+  internals.pendingAsyncActivities.delete(token);
+  try {
+    await internals.storage.delete(KEYS.asyncActivity(pending.workflowId, token));
+  } catch (error) {
+    internals.pendingAsyncActivities.set(token, pending);
+    throw error;
+  }
+  return pending;
+}
+async function resolvePendingAsyncActivity(internals, token, outcome, feedOperationResult, finalizeTimeline) {
+  const pending = await consumePendingAsyncActivity(internals, token), timelineOutput = outcome.status === "completed" ? outcome.value : outcome.error;
+  finalizeTimeline(pending.workflowId, outcome.status, timelineOutput);
+  feedOperationResult(pending.workflowId, outcome);
+}
+export async function completeAsyncActivity(internals, token, result, feedOperationResult, finalizeTimeline) {
+  assertPayloadWithinLimit(result, internals.options.payloadSizePolicy.maxBytes, "activity result");
+  await resolvePendingAsyncActivity(internals, token, { status: "completed", value: result }, feedOperationResult, finalizeTimeline);
+}
+export async function driveWorkflowInterceptorGenerator(generator) {
+  let current = generator.next();
+  while (!current.done) {
+    const yielded = current.value;
+    if (yielded instanceof Promise) {
+      let resolved;
+      try {
+        resolved = await yielded;
+      } catch (error) {
+        current = generator.throw(error);
+        continue;
+      }
+      current = generator.next(resolved);
+    } else
+      current = generator.next(yielded);
+  }
+  return current.value;
+}
+export async function failAsyncActivity(internals, token, error, feedOperationResult, finalizeTimeline) {
+  const message = error instanceof Error ? error.message : String(error), errorName = error instanceof Error ? error.name : void 0;
+  assertPayloadWithinLimit({ message, name: errorName }, internals.options.payloadSizePolicy.maxBytes, "activity result");
+  const pending = await consumePendingAsyncActivity(internals, token);
+  finalizeTimeline(pending.workflowId, "failed", message);
+  feedOperationResult(pending.workflowId, {
+    status: "failed",
+    error: message,
+    ...error instanceof Error ? { errorName: error.name } : {},
+    failureCategory: "application"
+  }, { value: error });
+}

package/dist/core/engine/attributes-tags.d.ts

@@ -0,0 +1,31 @@
+import type { BatchOperation } from '../../storage/interface.ts';
+import type { BulkTagResult, ListFilter, SearchAttributeValue, WorkflowState, WorkflowStatus } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+type WorkflowStateUpdateOptions = {
+    allowedStatuses?: readonly WorkflowStatus[];
+    buildAdditionalOperations?: (previousState: WorkflowState, updatedAt: number) => BatchOperation[];
+};
+type WorkflowStateUpdateResult = {
+    previousState: WorkflowState;
+    updatedAt: number;
+};
+/** Delete a workflow's stored search attributes and their secondary index entries. */
+export declare function cleanupAttributeIndex(internals: EngineInternals, workflowId: string, currentAttributes?: Record<string, SearchAttributeValue>): Promise<void>;
+/**
+ * Keep engine-managed terminal attributes queryable after the broader
+ * attribute cleanup removes user-defined search attributes.
+ */
+export declare function buildRetainedTerminalSearchAttributes(currentAttributes: Record<string, SearchAttributeValue>, additionalAttributes?: Record<string, SearchAttributeValue>): Record<string, SearchAttributeValue>;
+/** Write retained terminal search attributes and their index entries. */
+export declare function writeRetainedTerminalSearchAttributes(internals: EngineInternals, workflowId: string, attributes: Record<string, SearchAttributeValue>): Promise<void>;
+/** Build secondary-index updates for terminal workflow state transitions. */
+export declare function buildTerminalWorkflowIndexOperations(previousState: WorkflowState, nextState: WorkflowState): BatchOperation[];
+/** Apply a serialized workflow-state update and return the previous state metadata. */
+export declare function updateWorkflowState(internals: EngineInternals, workflowId: string, updates: Partial<WorkflowState>, options?: WorkflowStateUpdateOptions): Promise<WorkflowStateUpdateResult | null>;
+/** Add or remove tags for a single workflow under the serialized state-write lock. */
+export declare function mutateWorkflowTags(internals: EngineInternals, workflowId: string, tags: string[], mode: 'add' | 'remove'): Promise<boolean>;
+/** Add or remove tags for every workflow selected by a scoped bulk filter. */
+export declare function bulkMutateWorkflowTags(internals: EngineInternals, filter: ListFilter, tags: string[], mode: 'add' | 'remove', workflowIds?: readonly string[]): Promise<BulkTagResult>;
+/** Validate that all attribute values in a record fit within the storage key size limit. */
+export declare function validateAttributeValueSizes(attributes: Record<string, SearchAttributeValue>): void;
+export {};