@lostgradient/weft 0.2.0

package/dist/core/engine/lifecycle/transition.js

@@ -0,0 +1,183 @@
+import { KEYS } from "../../../storage/interface.js";
+import { deserializeCheckpoint, serializeCheckpoint } from "../../checkpoint.js";
+import { Context, setContextWorkflowInterceptor } from "../../context.js";
+import { EMPTY_EVENT_HEAD } from "../../event-log.js";
+import { WorkflowRecoverySkippedEvent, WorkflowStartedEvent } from "../../events.js";
+import { createCancelHandlerRegistration, resetCancelHandlers } from "../cancel-handlers.js";
+import { forgetCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.js";
+import { WorkflowTypeNotRegisteredForRecoveryError } from "../errors.js";
+import { getWorkflowExecutionStartedAt } from "../handles.js";
+import { normalizeForkStep, selectPersistedWorkflowStartHeaders } from "../state-utilities.js";
+import { loadWorkflowState } from "../storage-io.js";
+import { getComposedWorkflowInterceptor } from "../strategy-helpers.js";
+import { decodeWorkflowState } from "../validation.js";
+import {
+  buildForkBatchOperations,
+  buildForkSearchAttributes,
+  createForkLineage,
+  createForkedWorkflowState
+} from "./fork-helpers.js";
+import { createWorkflowVersionTuple, derivePreparedExecutionState } from "./persist.js";
+import { resumeWorkflowFromStorage } from "./resume.js";
+import {
+  createWorkflowHandle,
+  enforceHistoryPolicyBeforeReplayById,
+  loadWorkflowStartHeaders,
+  setWorkflowStartHeaders
+} from "./shared.js";
+function isWorkflowSideRecordKey(key) {
+  return key.includes(":ckpt") || key.includes(":offload") || key.includes(":archive") || key.includes(":timeline:");
+}
+function classifyRecoveryState(internals, callbacks, state) {
+  const hasLocalCheckpointOwnershipResult = callbacks.hasLocalCheckpointOwnership(state.id, state.status);
+  if (state.status === "pending" || callbacks.isInlineWorkflowLocallyOwned(state.id, state.status) || hasLocalCheckpointOwnershipResult)
+    return { kind: "local", workflowId: state.id };
+  if (state.status !== "running")
+    return { kind: "ignored" };
+  if (!internals.registrations.has(state.type))
+    return { kind: "missing", workflow: { type: state.type, workflowId: state.id } };
+  return { kind: "recoverable", workflowId: state.id };
+}
+function appendRecoveryClassification(result, classification) {
+  if (classification.kind === "ignored")
+    return;
+  result.entries.push(classification);
+  if (classification.kind === "missing")
+    result.missingWorkflows.push(classification.workflow);
+}
+async function preflightRecoverAll(internals, callbacks) {
+  const result = {
+    entries: [],
+    missingWorkflows: []
+  };
+  for await (const [key, value] of internals.storage.scan("wf:")) {
+    if (isWorkflowSideRecordKey(key))
+      continue;
+    appendRecoveryClassification(result, classifyRecoveryState(internals, callbacks, decodeWorkflowState(value)));
+  }
+  return result;
+}
+export async function recoverAll(internals, callbacks, options) {
+  const preflight = await preflightRecoverAll(internals, callbacks), handles = [];
+  if (preflight.missingWorkflows.length > 0 && options?.acknowledgeUnknownWorkflowTypes !== !0)
+    throw new WorkflowTypeNotRegisteredForRecoveryError({
+      registeredTypes: internals.registrations.keys(),
+      missingWorkflows: preflight.missingWorkflows
+    });
+  for (const entry of preflight.entries) {
+    if (entry.kind === "local") {
+      handles.push(callbacks.getHandle(entry.workflowId));
+      continue;
+    }
+    if (entry.kind === "missing") {
+      callbacks.dispatchEvent(new WorkflowRecoverySkippedEvent(entry.workflow.workflowId, entry.workflow.type, "type-not-registered"));
+      continue;
+    }
+    handles.push(await resume(internals, entry.workflowId, callbacks));
+  }
+  return handles;
+}
+export async function resume(internals, workflowId, callbacks) {
+  const workflowState = await loadWorkflowState(internals, workflowId);
+  if (workflowState !== null) {
+    if (callbacks.isInlineWorkflowLocallyOwned(workflowId, workflowState.status) || callbacks.hasLocalCheckpointOwnership(workflowId, workflowState.status)) {
+      await enforceHistoryPolicyBeforeReplayById(internals, workflowId, callbacks);
+      return callbacks.getHandle(workflowId);
+    }
+  }
+  return resumeWorkflowFromStorage(internals, workflowId, !0, callbacks);
+}
+export async function fork(internals, sourceWorkflowId, options, callbacks) {
+  const sourceState = await loadWorkflowState(internals, sourceWorkflowId);
+  if (!sourceState)
+    throw Error(`Workflow "${sourceWorkflowId}" not found`);
+  const registration = internals.registrations.get(sourceState.type);
+  if (!registration)
+    throw Error(`No workflow registered with name "${sourceState.type}" (needed to fork "${sourceWorkflowId}")`);
+  const fromStep = options?.fromStep !== void 0 ? normalizeForkStep(options.fromStep) : void 0, checkpointKey = fromStep !== void 0 ? KEYS.checkpointHistory(sourceWorkflowId, fromStep) : KEYS.checkpoint(sourceWorkflowId), checkpointBytes = await internals.storage.get(checkpointKey);
+  if (!checkpointBytes) {
+    if (fromStep !== void 0)
+      throw Error(`Checkpoint not found at step ${String(fromStep)} for workflow "${sourceWorkflowId}"`);
+    throw Error(`Checkpoint not found for workflow "${sourceWorkflowId}"`);
+  }
+  const sourceCheckpoint = deserializeCheckpoint(checkpointBytes), preparedExecutionState = derivePreparedExecutionState(internals, sourceWorkflowId, sourceState, sourceCheckpoint, registration, callbacks), sourceWorkflowHeaders = internals.workflowHeaders.get(sourceWorkflowId) ?? await loadWorkflowStartHeaders(internals, sourceWorkflowId, callbacks), persistedWorkflowStartHeaders = selectPersistedWorkflowStartHeaders(sourceWorkflowHeaders), workflowId = crypto.randomUUID(), forkedAt = internals.options.getNow(), lineage = createForkLineage(internals, sourceWorkflowId, sourceCheckpoint, callbacks), forkCheckpoint = {
+    ...preparedExecutionState.checkpoint,
+    createdAt: forkedAt,
+    workflowId,
+    searchAttributes: buildForkSearchAttributes(internals, preparedExecutionState.checkpoint, lineage, callbacks)
+  }, forkState = createForkedWorkflowState(internals, workflowId, preparedExecutionState.state, preparedExecutionState.versionTuple, lineage, forkedAt, callbacks);
+  let forkStarted = !1;
+  try {
+    const forkCheckpointBytes = serializeCheckpoint(forkCheckpoint);
+    await internals.storage.batch(buildForkBatchOperations(internals, workflowId, forkState, forkCheckpoint, forkCheckpointBytes, persistedWorkflowStartHeaders, callbacks));
+    internals.eventLogHeads.set(workflowId, EMPTY_EVENT_HEAD);
+    setWorkflowStartHeaders(internals, workflowId, persistedWorkflowStartHeaders, callbacks);
+    const handle = launchWorkflowFromCheckpoint(internals, workflowId, forkState, forkCheckpoint, registration, callbacks);
+    forkStarted = !0;
+    return handle;
+  } finally {
+    if (!forkStarted) {
+      forgetCommittedCheckpointBytes(internals, workflowId);
+      internals.checkpoints.delete(workflowId);
+      internals.workflowVersionTuples.delete(workflowId);
+      internals.eventLogHeads.delete(workflowId);
+      internals.workflowHeaders.delete(workflowId);
+    }
+  }
+}
+function launchInlineWorkflowFromCheckpoint(internals, workflowId, state, checkpoint, registration, callbacks) {
+  const inlineStrategy = internals.inlineStrategy;
+  if (!inlineStrategy)
+    throw Error("Inline workflow launch requested without an inline strategy.");
+  const accumulatedResults = new Map(checkpoint.accumulatedResults), workflowAbort = new AbortController;
+  resetCancelHandlers(internals, workflowId);
+  const context = new Context({
+    workflowId,
+    workflowType: state.type,
+    startedAt: getWorkflowExecutionStartedAt(state),
+    abortController: workflowAbort,
+    getNow: internals.options.getNow,
+    resolveWorkflowType: callbacks.resolveWorkflowTypeTarget,
+    executionStateOwnerId: state.executionStateOwnerId ?? workflowId,
+    accumulatedResults,
+    searchAttributes: checkpoint.searchAttributes,
+    registerCancelHandler: createCancelHandlerRegistration(internals, workflowId),
+    ...registration.searchAttributes && {
+      searchAttributeSchema: registration.searchAttributes
+    },
+    sleepReferenceTime: checkpoint.createdAt,
+    ...state.executionDeadline !== void 0 && { deadline: state.executionDeadline }
+  });
+  setContextWorkflowInterceptor(context, getComposedWorkflowInterceptor(internals));
+  if (internals.options.development)
+    context.explain(!0);
+  const generator = registration.handler(context, state.input);
+  inlineStrategy.adoptWorkflow(workflowId, generator, context, workflowAbort);
+  inlineStrategy.continueWorkflow(workflowId, void 0);
+  callbacks.swallowPromiseRejection(callbacks.processPendingUpdatesAfterInlineAdvance(workflowId));
+}
+function launchWorkerWorkflowFromCheckpoint(internals, workflowId, state, checkpoint) {
+  const serialized = serializeCheckpoint(checkpoint);
+  internals.strategy.startWorkflow({
+    workflowId,
+    workflowType: state.type,
+    input: state.input,
+    checkpoint: serialized,
+    executionStateOwnerId: state.executionStateOwnerId ?? workflowId,
+    ...state.executionDeadline !== void 0 && { deadline: state.executionDeadline },
+    ...internals.workflowHeaders.has(workflowId) && {
+      headers: [...internals.workflowHeaders.get(workflowId)]
+    }
+  });
+}
+export function launchWorkflowFromCheckpoint(internals, workflowId, state, checkpoint, registration, callbacks) {
+  internals.checkpoints.set(workflowId, checkpoint);
+  internals.workflowVersionTuples.set(workflowId, createWorkflowVersionTuple(internals, registration, callbacks));
+  const handle = createWorkflowHandle(internals, workflowId, callbacks);
+  callbacks.dispatchEvent(new WorkflowStartedEvent(workflowId, state.type, state.input));
+  if (internals.inlineStrategy)
+    launchInlineWorkflowFromCheckpoint(internals, workflowId, state, checkpoint, registration, callbacks);
+  else
+    launchWorkerWorkflowFromCheckpoint(internals, workflowId, state, checkpoint);
+  return handle;
+}

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

@@ -0,0 +1,8 @@
+export { EMPTY_STORAGE_VALUE, createWorkflowHandle, loadTerminalCleanupTrackedState, loadWorkflowStartHeaders, normalizeStartWorkflowTags, processPendingUpdatesAfterReplay, setWorkflowStartHeaders, type LifecycleCallbacks, type RecoverAllOptions, } from './lifecycle/shared.ts';
+export { createWorkflowVersionTuple, derivePreparedExecutionState, prepareResumeState, throwVersionMismatch, workflowStateWithVersionTuple, workflowVersionTupleFromState, } from './lifecycle/persist.ts';
+export { beginWorkflowExecution, createInitialCheckpoint, createInitialWorkflowState, parseStartOptionDuration, resolveScheduledStartAt, start, startWorkflow, } from './lifecycle/start.ts';
+export { buildInitialSearchAttributeOperations, buildStartBatchOperations, validateSearchAttributes, } from './lifecycle/start-batch.ts';
+export { runWorkflowStartInterceptor, startWorkflowExecution } from './lifecycle/start-exec.ts';
+export { buildForkBatchOperations, buildForkSearchAttributes, createForkLineage, createForkedWorkflowState, } from './lifecycle/fork-helpers.ts';
+export { fork, launchWorkflowFromCheckpoint, recoverAll, resume } from './lifecycle/transition.ts';
+export { resumeWorkflowFromStorage } from './lifecycle/resume.ts';

package/dist/core/engine/lifecycle.js

@@ -0,0 +1,40 @@
+export {
+  EMPTY_STORAGE_VALUE,
+  createWorkflowHandle,
+  loadTerminalCleanupTrackedState,
+  loadWorkflowStartHeaders,
+  normalizeStartWorkflowTags,
+  processPendingUpdatesAfterReplay,
+  setWorkflowStartHeaders
+} from "./lifecycle/shared.js";
+export {
+  createWorkflowVersionTuple,
+  derivePreparedExecutionState,
+  prepareResumeState,
+  throwVersionMismatch,
+  workflowStateWithVersionTuple,
+  workflowVersionTupleFromState
+} from "./lifecycle/persist.js";
+export {
+  beginWorkflowExecution,
+  createInitialCheckpoint,
+  createInitialWorkflowState,
+  parseStartOptionDuration,
+  resolveScheduledStartAt,
+  start,
+  startWorkflow
+} from "./lifecycle/start.js";
+export {
+  buildInitialSearchAttributeOperations,
+  buildStartBatchOperations,
+  validateSearchAttributes
+} from "./lifecycle/start-batch.js";
+export { runWorkflowStartInterceptor, startWorkflowExecution } from "./lifecycle/start-exec.js";
+export {
+  buildForkBatchOperations,
+  buildForkSearchAttributes,
+  createForkLineage,
+  createForkedWorkflowState
+} from "./lifecycle/fork-helpers.js";
+export { fork, launchWorkflowFromCheckpoint, recoverAll, resume } from "./lifecycle/transition.js";
+export { resumeWorkflowFromStorage } from "./lifecycle/resume.js";

package/dist/core/engine/list-candidate-resolution.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared candidate-id resolver used by both `engine.list()` and
+ * `engine.aggregate()`. Reads the visibility-index watermark once,
+ * fans every supported filter dimension out to its query helper when
+ * the watermark is current, and intersects the results with the
+ * existing tag/attribute resolution.
+ *
+ * Returns `null` when no filter narrows the candidate set — the caller
+ * falls back to a full `wf:` prefix scan with post-filtering.
+ *
+ * @module core/engine/list-candidate-resolution
+ */
+import type { ListFilter } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+export declare function resolveListCandidateIds(internals: EngineInternals, filter: ListFilter | undefined, normalizedTagFilters: readonly string[] | undefined): Promise<Set<string> | null>;

package/dist/core/engine/list-candidate-resolution.js

@@ -0,0 +1,88 @@
+import { intersectIdentifierSets } from "./state-utilities.js";
+import { getWorkflowVisibilityWatermark } from "./workflow-indexes.js";
+import { queryAttributeIndex, resolveConstrainedIds } from "./workflow-state-stream.js";
+import {
+  queryWorkflowIdPrefixCandidates,
+  queryWorkflowStatusIndex,
+  queryWorkflowTimeRangeIndex,
+  queryWorkflowTypeIndex
+} from "./workflow-visibility-queries.js";
+function queryStatusDimension(internals, value) {
+  const statuses = Array.isArray(value) ? value : [value];
+  return queryWorkflowStatusIndex(internals.storage, statuses);
+}
+function queryTypeDimension(internals, value) {
+  return queryWorkflowTypeIndex(internals.storage, value);
+}
+function queryCreatedAtDimension(internals, value) {
+  return queryWorkflowTimeRangeIndex(internals.storage, "created", value);
+}
+function queryUpdatedAtDimension(internals, value) {
+  return queryWorkflowTimeRangeIndex(internals.storage, "updated", value);
+}
+function queryExecutionDeadlineDimension(internals, value) {
+  return queryWorkflowTimeRangeIndex(internals.storage, "deadline", value);
+}
+function queryIdPrefixDimension(internals, value) {
+  return queryWorkflowIdPrefixCandidates(internals.storage, value);
+}
+const LIST_FILTER_DIMENSION_QUERIES = {
+  status: queryStatusDimension,
+  type: queryTypeDimension,
+  createdAt: queryCreatedAtDimension,
+  updatedAt: queryUpdatedAtDimension,
+  executionDeadline: queryExecutionDeadlineDimension,
+  idPrefix: queryIdPrefixDimension
+};
+function collectVisibilityQueries(internals, filter, dimensions) {
+  const queries = [];
+  for (const dimension of dimensions) {
+    const value = filter[dimension];
+    if (value === void 0)
+      continue;
+    const query = LIST_FILTER_DIMENSION_QUERIES[dimension];
+    queries.push(query(internals, value));
+  }
+  return queries;
+}
+export async function resolveListCandidateIds(internals, filter, normalizedTagFilters) {
+  const [baseConstrainedIds, failureCategoryCandidateIds] = await Promise.all([
+    resolveConstrainedIds(internals, filter, normalizedTagFilters),
+    resolveFailureCategoryCandidateIds(internals, filter?.failureCategory)
+  ]);
+  if (await getWorkflowVisibilityWatermark(internals.storage) === "stale") {
+    const queries = filter === void 0 ? [] : collectVisibilityQueries(internals, filter, ["idPrefix"]), visibilitySets = await Promise.all(queries);
+    return combineCandidateSets([
+      baseConstrainedIds,
+      failureCategoryCandidateIds,
+      ...visibilitySets
+    ]);
+  }
+  const visibilityQueries = filter === void 0 ? [] : collectVisibilityQueries(internals, filter, [
+    "status",
+    "type",
+    "createdAt",
+    "updatedAt",
+    "executionDeadline",
+    "idPrefix"
+  ]);
+  if (visibilityQueries.length === 0)
+    return combineCandidateSets([baseConstrainedIds, failureCategoryCandidateIds]);
+  const visibilitySets = await Promise.all(visibilityQueries);
+  return combineCandidateSets([baseConstrainedIds, failureCategoryCandidateIds, ...visibilitySets]);
+}
+async function resolveFailureCategoryCandidateIds(internals, failureCategory) {
+  if (failureCategory === void 0)
+    return null;
+  const categories = Array.isArray(failureCategory) ? failureCategory : [failureCategory], categorySets = await Promise.all(categories.map((category) => queryAttributeIndex(internals, { key: "failureCategory", value: category }))), ids = new Set;
+  for (const categorySet of categorySets)
+    for (const workflowId of categorySet)
+      ids.add(workflowId);
+  return ids;
+}
+function combineCandidateSets(candidateSets) {
+  const presentSets = candidateSets.filter((set) => set !== null);
+  if (presentSets.length === 0)
+    return null;
+  return intersectIdentifierSets(presentSets);
+}

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

@@ -0,0 +1,17 @@
+import type { ListFilter, ListOptions, PaginatedResult, SearchAttributeValue, WorkflowState, WorkflowSummary } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+export declare const BULK_OPERATION_BATCH_SIZE = 1000;
+/** List workflow summaries that match a filter, using indexes when available. */
+export declare function list(internals: EngineInternals, filter?: ListFilter, options?: ListOptions): Promise<PaginatedResult<WorkflowSummary>>;
+/** Stream decoded workflow states that match a list filter. */
+export declare function streamWorkflowStates(internals: EngineInternals, filter?: ListFilter): AsyncGenerator<WorkflowState>;
+/** Stream decoded workflow states in fixed-size batches for bulk operations. */
+export declare function streamWorkflowStateBatches(internals: EngineInternals, filter?: ListFilter): AsyncGenerator<WorkflowState[]>;
+/** Retrieve search attributes for a workflow. */
+export declare function getAttributes(internals: EngineInternals, workflowId: string): Promise<Record<string, SearchAttributeValue> | null>;
+/** Merge search attributes into a workflow's existing attributes, updating the index. */
+export declare function setAttributes(internals: EngineInternals, workflowId: string, attributes: Record<string, SearchAttributeValue>): Promise<void>;
+/** Add one or more tags to a workflow. */
+export declare function addTags(internals: EngineInternals, workflowId: string, ...tags: string[]): Promise<void>;
+/** Remove one or more tags from a workflow. */
+export declare function removeTags(internals: EngineInternals, workflowId: string, ...tags: string[]): Promise<void>;

package/dist/core/engine/listing.js

@@ -0,0 +1,186 @@
+import { KEYS } from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { normalizeFailureCategory } from "../failure-categories.js";
+import { isFailureCategory, normalizeListFilter } from "../list-filter-validation.js";
+import { buildIndexOperations, validateAttributeType } from "../search-attributes.js";
+import { normalizeWorkflowTags } from "../workflow-tags.js";
+import { mutateWorkflowTags, validateAttributeValueSizes } from "./attributes-tags.js";
+import { resolveListCandidateIds } from "./list-candidate-resolution.js";
+import { matchesListFilter, paginateWorkflowSummaries } from "./state-utilities.js";
+import { decodeWorkflowState, normalizeBulkFilterNumber } from "./validation.js";
+import { MAX_LIST_SCAN_ROWS, WorkflowListScanCapExceededError } from "./workflow-indexes.js";
+import {
+  isTopLevelWorkflowStateKey,
+  streamMatchingWorkflowStates
+} from "./workflow-state-stream.js";
+export const BULK_OPERATION_BATCH_SIZE = 1000;
+export async function list(internals, filter, options) {
+  const normalizedFilter = filter === void 0 ? void 0 : normalizeListFilter(filter), normalizedTagFilters = normalizeWorkflowTags(normalizedFilter?.tags), constrainedIds = await resolveListCandidateIds(internals, normalizedFilter, normalizedTagFilters), items = constrainedIds !== null ? await collectSummariesFromConstrainedIds(internals, constrainedIds, normalizedFilter, normalizedTagFilters, options) : await collectSummariesFromFullScan(internals, normalizedFilter, normalizedTagFilters, options);
+  return paginateWorkflowSummaries(sortSummariesByCreatedAtDescending(items), normalizedFilter);
+}
+const CONSTRAINED_ID_CHUNK_SIZE = 64;
+async function collectSummariesFromConstrainedIds(internals, constrainedIds, normalizedFilter, normalizedTagFilters, options) {
+  const orderedIds = [...constrainedIds];
+  if (orderedIds.length > MAX_LIST_SCAN_ROWS)
+    throw new WorkflowListScanCapExceededError(MAX_LIST_SCAN_ROWS);
+  const items = [];
+  for (let start = 0;start < orderedIds.length; start += CONSTRAINED_ID_CHUNK_SIZE) {
+    const chunkIds = orderedIds.slice(start, start + CONSTRAINED_ID_CHUNK_SIZE), chunkBytes = await Promise.all(chunkIds.map((workflowId) => internals.storage.get(KEYS.workflow(workflowId)))), matchingStates = [];
+    for (const stateBytes of chunkBytes) {
+      if (!stateBytes)
+        continue;
+      const state = decodeWorkflowState(stateBytes);
+      if (!matchesListFilter(state, normalizedFilter, constrainedIds, normalizedTagFilters))
+        continue;
+      matchingStates.push(state);
+    }
+    items.push(...await summariesFromStates(internals, matchingStates, options));
+  }
+  return items;
+}
+async function collectSummariesFromFullScan(internals, normalizedFilter, normalizedTagFilters, options) {
+  const items = [];
+  let scanned = 0;
+  for await (const [key, value] of internals.storage.scan("wf:")) {
+    if (!isTopLevelWorkflowStateKey(key))
+      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;
+    const attributeBytes = shouldReadFailureCategoryAttribute(state, options) ? await internals.storage.get(KEYS.attribute(state.id)) : null;
+    items.push(summaryFromState(state, failureCategoryFromAttributeBytes(attributeBytes)));
+  }
+  return items;
+}
+async function summariesFromStates(internals, states, options) {
+  const attributeBytesByWorkflowId = new Map;
+  await Promise.all(states.map(async (state) => {
+    if (!shouldReadFailureCategoryAttribute(state, options))
+      return;
+    attributeBytesByWorkflowId.set(state.id, await internals.storage.get(KEYS.attribute(state.id)));
+  }));
+  return states.map((state) => summaryFromState(state, failureCategoryFromAttributeBytes(attributeBytesByWorkflowId.get(state.id) ?? null)));
+}
+function shouldReadFailureCategoryAttribute(state, options) {
+  return options?.includeFailureCategory === !0 && state.status === "failed" && (state.failureCategory === void 0 || state.failureCategory === null);
+}
+function failureCategoryFromAttributeBytes(attributeBytes) {
+  if (attributeBytes === null)
+    return;
+  const attributes = decode(attributeBytes);
+  if (!isRecord(attributes))
+    return;
+  const value = attributes.failureCategory;
+  if (isFailureCategory(value))
+    return value;
+  return normalizeFailureCategory(value);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function summaryFromState(state, attributeFailureCategory) {
+  const failureCategory = state.failureCategory ?? attributeFailureCategory;
+  return {
+    id: state.id,
+    type: state.type,
+    status: state.status,
+    ...state.tags !== void 0 && { tags: state.tags },
+    version: state.version,
+    createdAt: state.createdAt,
+    updatedAt: state.updatedAt,
+    ...state.executionDeadline !== void 0 && { executionDeadline: state.executionDeadline },
+    ...failureCategory !== void 0 && failureCategory !== null && { failureCategory }
+  };
+}
+function sortSummariesByCreatedAtDescending(items) {
+  return items.toSorted((left, right) => {
+    if (left.createdAt !== right.createdAt)
+      return right.createdAt - left.createdAt;
+    if (left.id < right.id)
+      return -1;
+    if (left.id > right.id)
+      return 1;
+    return 0;
+  });
+}
+export async function* streamWorkflowStates(internals, filter) {
+  yield* streamMatchingWorkflowStates(internals, filter);
+}
+export async function* streamWorkflowStateBatches(internals, filter) {
+  const window = resolveBulkWorkflowStateBatchWindow(filter);
+  if (isBulkWorkflowStateBatchWindowExhausted(window))
+    return;
+  let batch = [];
+  for await (const state of streamWorkflowStates(internals, filter)) {
+    if (skipWorkflowStateForBulkWindow(window))
+      continue;
+    batch.push(state);
+    consumeWorkflowStateFromBulkWindow(window);
+    if (batch.length === BULK_OPERATION_BATCH_SIZE) {
+      yield batch;
+      batch = [];
+    }
+    if (isBulkWorkflowStateBatchWindowExhausted(window))
+      break;
+  }
+  if (batch.length > 0)
+    yield batch;
+}
+function resolveBulkWorkflowStateBatchWindow(filter) {
+  return {
+    remainingOffset: normalizeBulkFilterNumber(filter?.offset, "offset") ?? 0,
+    remainingLimit: normalizeBulkFilterNumber(filter?.limit, "limit")
+  };
+}
+function skipWorkflowStateForBulkWindow(window) {
+  if (window.remainingOffset <= 0)
+    return !1;
+  window.remainingOffset -= 1;
+  return !0;
+}
+function consumeWorkflowStateFromBulkWindow(window) {
+  if (window.remainingLimit === void 0)
+    return;
+  window.remainingLimit -= 1;
+}
+function isBulkWorkflowStateBatchWindowExhausted(window) {
+  return window.remainingLimit === 0;
+}
+export async function getAttributes(internals, workflowId) {
+  const bytes = await internals.storage.get(KEYS.attribute(workflowId));
+  if (!bytes)
+    return null;
+  const decoded = decode(bytes);
+  if (!isRecord(decoded))
+    return null;
+  return decoded;
+}
+export async function setAttributes(internals, workflowId, attributes) {
+  const stateBytes = await internals.storage.get(KEYS.workflow(workflowId));
+  if (stateBytes) {
+    const state = decodeWorkflowState(stateBytes), registration = internals.registrations.get(state.type);
+    if (registration?.searchAttributes) {
+      const schema = registration.searchAttributes;
+      for (const [key, value] of Object.entries(attributes)) {
+        if (!(key in schema))
+          throw Error(`Unknown search attribute "${key}". Registered attributes: ${Object.keys(schema).join(", ")}`);
+        validateAttributeType(key, value, schema[key]);
+      }
+    }
+  }
+  validateAttributeValueSizes(attributes);
+  const existingBytes = await internals.storage.get(KEYS.attribute(workflowId)), existing = existingBytes ? decode(existingBytes) : {}, merged = { ...existing, ...attributes }, indexOperations = buildIndexOperations(workflowId, existing, merged), operations = [
+    { type: "put", key: KEYS.attribute(workflowId), value: encode(merged) },
+    ...indexOperations
+  ];
+  await internals.storage.batch(operations);
+}
+export async function addTags(internals, workflowId, ...tags) {
+  await mutateWorkflowTags(internals, workflowId, tags, "add");
+}
+export async function removeTags(internals, workflowId, ...tags) {
+  await mutateWorkflowTags(internals, workflowId, tags, "remove");
+}

package/dist/core/engine/operations-activity.d.ts

@@ -0,0 +1,40 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { ComposedActivityInterceptor, ComposedWorkflowInterceptor } from '../interceptor.ts';
+import type { ActivityContext, ActivityVerificationResult } from '../types.ts';
+import { buildActivityVerificationContext, type ActivityReconciliationMetadata } from './activity-reconciliation.ts';
+import type { EngineInternals } from './internals.ts';
+import type { SpeculativeExecutionState } from './speculative-execution-state.ts';
+export type ActivityFunctionWithMetadata = ((...arguments_: unknown[]) => unknown) & ActivityReconciliationMetadata & {
+    verify?: (result: unknown, context?: ReturnType<typeof buildActivityVerificationContext>) => Promise<ActivityVerificationResult> | ActivityVerificationResult;
+    compensate?: (input: unknown, output: unknown) => Promise<void> | void;
+};
+type ActivityOperation = Extract<ContextOperationRequest, {
+    type: 'activity';
+}>;
+export type ActivityOperationCallbacks = {
+    runOperationWithResult: (workflowId: string, operation: ActivityOperation, execute: () => Promise<unknown>) => Promise<void>;
+    getComposedActivityInterceptor: () => ComposedActivityInterceptor | null;
+    getComposedWorkflowInterceptor: () => ComposedWorkflowInterceptor | null;
+};
+export declare function getActivityFunctionWithMetadata(internals: EngineInternals, workflowId: string, operation: ActivityOperation): ActivityFunctionWithMetadata | undefined;
+/**
+ * Resolve the activity function for a given operation. Uses the same
+ * per-workflow-first-then-global ordering as `getActivityFunctionWithMetadata`.
+ * For inline-mode callers that pass an `operation.fn` directly, the registries
+ * are still consulted first so a workflow's locally-scoped activity wins over
+ * the bare callable. Throws `ActivityResolutionError` when neither path
+ * resolves.
+ */
+export declare function resolveActivityFunction(internals: EngineInternals, workflowId: string, operation: ActivityOperation): (...arguments_: unknown[]) => unknown;
+export declare function buildActivityVerification(_internals: EngineInternals, activityName: string, verify: ActivityFunctionWithMetadata['verify'], context: ReturnType<typeof buildActivityVerificationContext>, result: unknown): Promise<void>;
+export declare function buildActivityCompensation(internals: EngineInternals, workflowId: string, operation: ActivityOperation, result: unknown): (() => Promise<void>) | undefined;
+export declare function invokeWorkerActivity(internals: EngineInternals, operationId: string, activityName: string, input: unknown, attempt: number): Promise<unknown>;
+export declare function invokeInlineActivity(internals: EngineInternals, workflowId: string, operation: ActivityOperation, activityContext: ActivityContext, _activityName: string, input: unknown): unknown;
+/**
+ * Execute an activity function, dispatching to a Web Worker pool when
+ * `activityExecution` is configured, or running inline on the main thread.
+ */
+export declare function executeActivity(internals: EngineInternals, workflowId: string, operation: ActivityOperation, callbacks: ActivityOperationCallbacks, attempt?: number): Promise<unknown>;
+export declare function executeActivityOperationResult(internals: EngineInternals, workflowId: string, operation: ActivityOperation, callbacks: ActivityOperationCallbacks, speculativeState?: SpeculativeExecutionState): Promise<unknown>;
+export declare function processActivityOperation(internals: EngineInternals, workflowId: string, operation: ActivityOperation, callbacks: ActivityOperationCallbacks): Promise<void>;
+export {};