@lostgradient/weft 0.2.0

package/dist/core/engine/validation.js

@@ -0,0 +1,144 @@
+import { decode } from "../codec.js";
+import { isRecord } from "../debug-output.js";
+import { normalizeFailureCategory } from "../failure-categories.js";
+import { coerceStartWorkflowId, parseStartWorkflowDuration } from "../start-workflow-validation.js";
+import { isWorkflowTagArray } from "../workflow-tags.js";
+const WORKFLOW_TIMELINE_STATUSES = new Set([
+  "running",
+  "completed",
+  "failed",
+  "cancelled",
+  "timed-out"
+]);
+export function isSanitizedSearchAttributeValue(value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+    return !0;
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+export function isWorkflowVersionTuple(value) {
+  if (!isRecord(value) || typeof value.workflowVersion !== "string")
+    return !1;
+  if (value.agentVersion !== void 0 && typeof value.agentVersion !== "string")
+    return !1;
+  return value.toolVersions === void 0 || Array.isArray(value.toolVersions) && value.toolVersions.every((entry) => typeof entry === "string");
+}
+export function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+export function isTimelineStep(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+}
+const TIMELINE_ENTRY_FIELD_CHECKS = [
+  (entry) => isTimelineStep(entry.step),
+  (entry) => typeof entry.operationType === "string",
+  (entry) => typeof entry.operationLabel === "string",
+  (entry) => typeof entry.inputSummary === "string",
+  (entry) => isFiniteNumber(entry.timestamp),
+  (entry) => WORKFLOW_TIMELINE_STATUSES.has(entry.status),
+  (entry) => entry.outputSummary === void 0 || typeof entry.outputSummary === "string",
+  (entry) => entry.duration === void 0 || isFiniteNumber(entry.duration),
+  (entry) => entry.versionTuple === void 0 || isWorkflowVersionTuple(entry.versionTuple)
+];
+export function isWorkflowTimelineEntry(value) {
+  if (!isRecord(value))
+    return !1;
+  return TIMELINE_ENTRY_FIELD_CHECKS.every((check) => check(value));
+}
+export function normalizeBulkFilterNumber(value, fieldName) {
+  if (value === void 0)
+    return;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+    throw Error(`filter.${fieldName} must be a non-negative number when provided`);
+  return Math.floor(value);
+}
+export function isValidDecodedTags(value) {
+  return value === void 0 || isWorkflowTagArray(value);
+}
+export function decodeWorkflowState(bytes) {
+  const state = decode(bytes);
+  if ("tenant" in state)
+    delete state.tenant;
+  if (!isValidDecodedTags(state.tags)) {
+    console.warn(`[weft] Decoded workflow state for "${String(state.id)}" has invalid tags; dropping the malformed tag list from the decoded state.`);
+    delete state.tags;
+  }
+  if (state.failureCategory !== void 0 && state.failureCategory !== null) {
+    const normalizedFailureCategory = normalizeFailureCategory(state.failureCategory);
+    if (normalizedFailureCategory === void 0)
+      delete state.failureCategory;
+    else
+      state.failureCategory = normalizedFailureCategory;
+  }
+  if (state.executionStateOwnerId !== void 0)
+    try {
+      coerceStartWorkflowId(state.executionStateOwnerId, "executionStateOwnerId");
+    } catch {
+      console.warn(`[weft] Decoded workflow state for "${String(state.id)}" has an invalid executionStateOwnerId field; falling back to the workflow id as the execution owner. This usually indicates corruption or tampering of the storage record.`);
+      delete state.executionStateOwnerId;
+    }
+  return state;
+}
+export function normalizeRetentionDuration(value, fieldName) {
+  if (value === void 0)
+    return;
+  const milliseconds = parseStartWorkflowDuration(value, fieldName);
+  return Math.ceil(milliseconds);
+}
+export function normalizeHistoryPolicy(policy, context) {
+  return {
+    maxEvents: normalizePositiveCountOrDisabled(policy?.maxEvents, `${context}.maxEvents`),
+    retentionWindow: normalizePositiveCountOrDisabled(policy?.retentionWindow, `${context}.retentionWindow`)
+  };
+}
+function normalizePositiveCountOrDisabled(value, field) {
+  if (value === void 0 || value === 0)
+    return null;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+    throw TypeError(`${field} must be a positive safe integer (or 0/undefined to disable); received ${String(value)}`);
+  return value;
+}
+export function normalizePayloadSizePolicy(policy, context) {
+  const maxBytes = policy?.maxBytes;
+  if (maxBytes === void 0 || maxBytes === null || maxBytes === 0)
+    return { maxBytes: null };
+  if (typeof maxBytes !== "number" || !Number.isSafeInteger(maxBytes) || maxBytes < 0)
+    throw TypeError(`${context}.maxBytes must be a positive safe integer (or 0/null/undefined to disable); received ${String(maxBytes)}`);
+  return { maxBytes };
+}
+export function normalizeRetentionPolicy(policy, context) {
+  if (!policy)
+    return null;
+  const normalized = {}, completed = normalizeRetentionDuration(policy.completed, `${context}.completed`), failed = normalizeRetentionDuration(policy.failed, `${context}.failed`), cancelled = normalizeRetentionDuration(policy.cancelled, `${context}.cancelled`), timedOut = normalizeRetentionDuration(policy.timedOut, `${context}.timedOut`);
+  if (completed !== void 0)
+    normalized.completed = completed;
+  if (failed !== void 0)
+    normalized.failed = failed;
+  if (cancelled !== void 0)
+    normalized.cancelled = cancelled;
+  if (timedOut !== void 0)
+    normalized.timedOut = timedOut;
+  return normalized.completed === void 0 && normalized.failed === void 0 && normalized.cancelled === void 0 && normalized.timedOut === void 0 ? null : normalized;
+}
+export function resolveRetentionForStatus(policy, status) {
+  switch (status) {
+    case "completed":
+      return policy?.completed;
+    case "failed":
+      return policy?.failed;
+    case "cancelled":
+      return policy?.cancelled;
+    case "timed-out":
+      return policy?.timedOut;
+    default:
+      return;
+  }
+}
+export function isTerminalWorkflowStatus(status) {
+  return status === "completed" || status === "failed" || status === "cancelled" || status === "timed-out";
+}
+export function isPlainObjectRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return !1;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}

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

@@ -0,0 +1,82 @@
+import type { EngineInternals } from './internals.ts';
+/**
+ * Discriminator for `replayWorkflowFeed` / `snapshotWorkflowFeedTail`
+ * / `subscribeWorkflowFeedCommits`. Mirrored by `EventSelector` in
+ * `src/server/workflow-event-feed.ts` so the core engine takes no
+ * dependency on the server package.
+ */
+export type WorkflowFeedSelector = 'events' | 'tokens';
+/**
+ * Hard-coded stream key for the `tokens` selector. Matches the
+ * legacy REST SSE endpoint's key so resumption cursors round-trip
+ * across transports.
+ */
+export declare const TOKENS_STREAM_KEY = "tokens";
+/** Record `kind` for every token stream chunk emitted by the feed. */
+export declare const STREAM_CHUNK_KIND = "stream:chunk";
+/**
+ * Record `kind` emitted when a subscriber resumes from a cursor below the
+ * event-log compaction watermark. The `[cursor, watermark.sequence)` records
+ * were truncated, so the feed reports an explicit boundary marker (rather than
+ * silently skipping) before continuing from the surviving records. `sequence`
+ * is the watermark sequence (the first surviving record).
+ */
+export declare const COMPACTION_BOUNDARY_KIND = "workflow:compaction-boundary";
+/**
+ * A committed workflow-feed record surfaced to subscribers of
+ * `subscribeWorkflowFeedCommits()`. Fires after `storage.batch()`
+ * (events) or `storage.put()` (tokens) resolves, so replay and live
+ * delivery share the same committed sequence authority. The same
+ * shape covers both selectors — consumers filter on `selector`
+ * before interpreting `payload`.
+ *
+ *   - `events` selector: `kind` is the durable log entry type
+ *     (e.g. `'workflow:checkpoint'`). `sequence` / `timestamp` come
+ *     from the `WorkflowLogEntry` written inside the batch.
+ *   - `tokens` selector: `kind` is always `'stream:chunk'`.
+ *     `sequence` is the chunk index; `timestamp` is wall-clock at
+ *     write time.
+ */
+export type WorkflowFeedRecord = {
+    readonly workflowId: string;
+    readonly selector: WorkflowFeedSelector;
+    readonly kind: string;
+    readonly sequence: number;
+    readonly timestamp: number;
+    readonly payload: unknown;
+};
+export type WorkflowFeedRecordValue = WorkflowFeedRecord;
+/**
+ * Listener signature for `subscribeWorkflowFeedCommits()`. Returning
+ * `void | Promise<void>` is explicit: an async listener's rejected
+ * promise is caught by the notifier and discarded, exactly like a
+ * sync throw. This is the only correct shape for a notifier called
+ * from a hot path — an escaped unhandled rejection would surface as
+ * a test-runner or Node process-level crash.
+ */
+export type WorkflowFeedListener = (record: WorkflowFeedRecord) => void | Promise<void>;
+/**
+ * Iterate over the workflow's post-commit records for a given selector.
+ */
+export declare function replayWorkflowFeed(internals: EngineInternals, workflowId: string, selector: WorkflowFeedSelector, afterSequence: number): AsyncIterable<WorkflowFeedRecord>;
+/**
+ * Snapshot the current tail sequence for the selector.
+ */
+export declare function snapshotWorkflowFeedTail(internals: EngineInternals, workflowId: string, selector: WorkflowFeedSelector): Promise<number>;
+/**
+ * Subscribe to post-commit workflow-feed notifications.
+ */
+export declare function subscribeWorkflowFeedCommits(internals: EngineInternals, workflowId: string, selector: WorkflowFeedSelector, listener: WorkflowFeedListener): () => void;
+/**
+ * Replay committed workflow event-log entries after a durable sequence cursor.
+ */
+export declare function replayWorkflowEventLog(internals: EngineInternals, workflowId: string, afterSequence: number): AsyncIterable<WorkflowFeedRecord>;
+/**
+ * Replay committed token stream chunks after a durable sequence cursor.
+ */
+export declare function replayWorkflowTokens(internals: EngineInternals, workflowId: string, afterSequence: number): AsyncIterable<WorkflowFeedRecord>;
+/**
+ * Dispatch a committed record to every listener registered for
+ * `(workflowId, selector)`.
+ */
+export declare function notifyWorkflowFeedCommit(internals: EngineInternals, workflowId: string, selector: WorkflowFeedSelector, record: WorkflowFeedRecord): void;

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

@@ -0,0 +1,96 @@
+import { EventLog } from "../event-log.js";
+import { readEventLogWatermark } from "./event-log-compaction.js";
+import { workflowFeedListenerKey } from "./state-utilities.js";
+import { loadStoredStreamChunks } from "./stream-chunk-loading.js";
+export const TOKENS_STREAM_KEY = "tokens", STREAM_CHUNK_KIND = "stream:chunk", COMPACTION_BOUNDARY_KIND = "workflow:compaction-boundary";
+export async function* replayWorkflowFeed(internals, workflowId, selector, afterSequence) {
+  if (selector === "events") {
+    yield* replayWorkflowEventLog(internals, workflowId, afterSequence);
+    return;
+  }
+  yield* replayWorkflowTokens(internals, workflowId, afterSequence);
+}
+export async function snapshotWorkflowFeedTail(internals, workflowId, selector) {
+  if (selector === "events") {
+    const head = internals.eventLogHeads.get(workflowId);
+    if (head)
+      return head.sequence;
+    return (await new EventLog(internals.storage, workflowId).loadHead()).sequence;
+  }
+  const chunks = await loadStoredStreamChunks(internals.storage, workflowId, TOKENS_STREAM_KEY);
+  if (chunks.length === 0)
+    return -1;
+  let max = -1;
+  for (const chunk of chunks)
+    if (chunk.sequence > max)
+      max = chunk.sequence;
+  return max;
+}
+export function subscribeWorkflowFeedCommits(internals, workflowId, selector, listener) {
+  const key = workflowFeedListenerKey(workflowId, selector);
+  let bucket = internals.workflowFeedListeners.get(key);
+  if (!bucket) {
+    bucket = new Set;
+    internals.workflowFeedListeners.set(key, bucket);
+  }
+  bucket.add(listener);
+  return () => {
+    const set = internals.workflowFeedListeners.get(key);
+    if (!set)
+      return;
+    set.delete(listener);
+    if (set.size === 0)
+      internals.workflowFeedListeners.delete(key);
+  };
+}
+export async function* replayWorkflowEventLog(internals, workflowId, afterSequence) {
+  const eventLog = new EventLog(internals.storage, workflowId);
+  let fromSequence = afterSequence < 0 ? 0 : afterSequence + 1;
+  const watermark = await readEventLogWatermark(internals.storage, workflowId);
+  if (watermark !== null && fromSequence < watermark.sequence) {
+    yield {
+      workflowId,
+      selector: "events",
+      kind: COMPACTION_BOUNDARY_KIND,
+      sequence: watermark.sequence - 1,
+      timestamp: 0,
+      payload: { compactedBefore: watermark.sequence, requestedFrom: fromSequence }
+    };
+    fromSequence = watermark.sequence;
+  }
+  for await (const entry of eventLog.scan({ fromSequence }))
+    yield {
+      workflowId,
+      selector: "events",
+      kind: entry.type,
+      sequence: entry.sequence,
+      timestamp: entry.timestamp,
+      payload: entry.payload
+    };
+}
+export async function* replayWorkflowTokens(internals, workflowId, afterSequence) {
+  const chunks = afterSequence >= 0 ? await loadStoredStreamChunks(internals.storage, workflowId, TOKENS_STREAM_KEY, {
+    after: afterSequence
+  }) : await loadStoredStreamChunks(internals.storage, workflowId, TOKENS_STREAM_KEY), timestamp = Date.now();
+  for (const chunk of chunks)
+    yield {
+      workflowId,
+      selector: "tokens",
+      kind: STREAM_CHUNK_KIND,
+      sequence: chunk.sequence,
+      timestamp,
+      payload: chunk.value
+    };
+}
+export function notifyWorkflowFeedCommit(internals, workflowId, selector, record) {
+  const bucket = internals.workflowFeedListeners.get(workflowFeedListenerKey(workflowId, selector));
+  if (!bucket || bucket.size === 0)
+    return;
+  const listeners = [...bucket];
+  for (const listener of listeners)
+    try {
+      const result = listener(record);
+      if (result && typeof result.then === "function")
+        result.catch(() => {});
+    } catch {}
+}

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

@@ -0,0 +1,103 @@
+/**
+ * Build the storage operations that keep the workflow visibility indexes in
+ * sync with workflow state writes. Called from every state-mutation chokepoint
+ * (start, status transition, attribute/tag updates, termination cleanup).
+ *
+ * The runtime path mirrors the backfill path: read the per-workflow manifest
+ * to learn which index keys are currently occupied, delete them, write the
+ * new index keys derived from `nextState`, and persist the new manifest. When
+ * `nextState` is `null` the workflow is being removed and we simply drop the
+ * manifest and every key it lists.
+ *
+ * @module core/engine/workflow-indexes
+ */
+import { type BatchOperation, type Storage } from '../../storage/interface.ts';
+import type { WorkflowState } from '../types.ts';
+import { WeftError } from '../weft-error.ts';
+/**
+ * Bumped whenever the index layout or population rules change. The engine
+ * compares this to the watermark stored at `wf-idx-meta:version` to decide
+ * whether the indexes are trustworthy for query-time use.
+ */
+export declare const WORKFLOW_VISIBILITY_INDEX_VERSION = 1;
+/**
+ * Hard cap on the number of candidate workflow ids the engine will
+ * materialize for a single `list` or `aggregate` query. Exceeding the cap
+ * raises a {@link WorkflowListScanCapExceededError} — the operator should
+ * narrow the filter or run the visibility-index backfill so a narrower
+ * scan applies.
+ */
+export declare const MAX_LIST_SCAN_ROWS = 1000000;
+/**
+ * Thrown when `list`/`aggregate` would materialize more candidates than
+ * {@link MAX_LIST_SCAN_ROWS} allows. Transport layers map this to an
+ * `Unprocessable` fault.
+ */
+export declare class WorkflowListScanCapExceededError extends WeftError<'WorkflowListScanCapExceededError'> {
+    readonly cap: number;
+    constructor(cap: number);
+}
+/**
+ * Per-workflow manifest payload — the exact set of visibility-index keys
+ * this workflow occupies right now. Decoded from the
+ * `wf-idx-manifest:{id}` storage entry.
+ */
+export type WorkflowVisibilityManifest = {
+    /** Schema version that wrote this manifest. */
+    version: number;
+    /** Sorted list of index keys this workflow currently owns. */
+    keys: string[];
+};
+/**
+ * Compute the visibility-index keys a workflow should occupy given its
+ * current state. Returns a deterministic, sorted list so manifests compare
+ * stably across runs.
+ */
+export declare function deriveWorkflowVisibilityIndexKeys(state: WorkflowState): string[];
+/**
+ * Decode a manifest payload read from storage. Returns `null` for missing or
+ * malformed values so callers fall back to the "treat as empty" path — the
+ * derived diff still produces the right set of inserts.
+ */
+export declare function decodeWorkflowVisibilityManifest(bytes: Uint8Array | null): WorkflowVisibilityManifest | null;
+/**
+ * Result of {@link buildWorkflowVisibilityIndexOperations}. `nextManifestKeys`
+ * is `null` when the workflow is being removed (delete manifest + all keys).
+ */
+export type WorkflowVisibilityIndexUpdate = {
+    batchOps: BatchOperation[];
+    nextManifestKeys: string[] | null;
+};
+/**
+ * Build the batch operations required to transition a workflow's visibility
+ * indexes from `currentManifest` (whatever the storage currently records) to
+ * the keys derived from `nextState`. Pass `nextState = null` to drop the
+ * workflow's index footprint entirely.
+ *
+ * The caller is responsible for appending the returned `batchOps` to its own
+ * write batch so storage commits the index update atomically with the state
+ * write it accompanies.
+ */
+export declare function buildWorkflowVisibilityIndexOperations(workflowId: string, currentManifest: WorkflowVisibilityManifest | null, nextState: WorkflowState | null): WorkflowVisibilityIndexUpdate;
+/**
+ * Variant of {@link buildWorkflowVisibilityIndexOperations} that derives the
+ * previous index keys directly from `previousState` instead of from a stored
+ * manifest. Use this on every runtime state-transition write — it avoids an
+ * extra storage round-trip per write and is always correct because the index
+ * is a deterministic function of state.
+ *
+ * The manifest-based variant remains the right choice for backfill, which
+ * may need to delete rows produced by a different schema version.
+ */
+export declare function buildWorkflowVisibilityIndexTransition(workflowId: string, previousState: WorkflowState | null, nextState: WorkflowState | null): WorkflowVisibilityIndexUpdate;
+/**
+ * Watermark recorded by the backfill once every workflow has a manifest at
+ * the current schema version. `engine.list()` and `engine.aggregate()` only
+ * consult the new `wf-idx-*` rows when the watermark is `current`.
+ */
+export type WorkflowVisibilityWatermark = 'current' | 'stale';
+/**
+ * Read the visibility-index watermark. Returns `'current'` when the
+ * persisted version is at or above {@link WORKFLOW_VISIBILITY_INDEX_VERSION}.
+ */
+export declare function getWorkflowVisibilityWatermark(storage: Storage): Promise<WorkflowVisibilityWatermark>;

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

@@ -0,0 +1,93 @@
+import { KEYS } from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { WeftError } from "../weft-error.js";
+export const WORKFLOW_VISIBILITY_INDEX_VERSION = 1, MAX_LIST_SCAN_ROWS = 1e6;
+
+export class WorkflowListScanCapExceededError extends WeftError {
+  cap;
+  constructor(cap) {
+    super("WorkflowListScanCapExceededError", `Listing workflows would exceed the scan cap of ${cap}. Narrow the filter or run the visibility-index backfill.`);
+    this.cap = cap;
+  }
+}
+export function deriveWorkflowVisibilityIndexKeys(state) {
+  const keys = [
+    KEYS.workflowVisibilityStatus(state.status, state.id),
+    KEYS.workflowVisibilityType(state.type, state.id),
+    KEYS.workflowVisibilityCreated(state.createdAt, state.id),
+    KEYS.workflowVisibilityUpdated(state.updatedAt, state.id)
+  ];
+  if (state.executionDeadline !== void 0)
+    keys.push(KEYS.workflowVisibilityDeadline(state.executionDeadline, state.id));
+  return keys.toSorted();
+}
+export function decodeWorkflowVisibilityManifest(bytes) {
+  if (!bytes)
+    return null;
+  let payload;
+  try {
+    payload = decode(bytes);
+  } catch {
+    return null;
+  }
+  if (typeof payload !== "object" || payload === null)
+    return null;
+  const candidate = payload;
+  if (typeof candidate.version !== "number")
+    return null;
+  if (!Array.isArray(candidate.keys))
+    return null;
+  const keys = [];
+  for (const entry of candidate.keys) {
+    if (typeof entry !== "string")
+      return null;
+    keys.push(entry);
+  }
+  return { version: candidate.version, keys };
+}
+export function buildWorkflowVisibilityIndexOperations(workflowId, currentManifest, nextState) {
+  return buildWorkflowVisibilityIndexOperationsInternal(workflowId, currentManifest?.keys ?? [], currentManifest !== null, nextState);
+}
+export function buildWorkflowVisibilityIndexTransition(workflowId, previousState, nextState) {
+  const previousKeys = previousState ? deriveWorkflowVisibilityIndexKeys(previousState) : [];
+  return buildWorkflowVisibilityIndexOperationsInternal(workflowId, previousKeys, previousState !== null, nextState);
+}
+function buildWorkflowVisibilityIndexOperationsInternal(workflowId, previousKeys, hadPriorManifest, nextState) {
+  const manifestKey = KEYS.workflowVisibilityManifest(workflowId);
+  if (nextState === null) {
+    const batchOps = [];
+    for (const key of previousKeys)
+      batchOps.push({ type: "delete", key });
+    if (hadPriorManifest)
+      batchOps.push({ type: "delete", key: manifestKey });
+    return { batchOps, nextManifestKeys: null };
+  }
+  const nextKeys = deriveWorkflowVisibilityIndexKeys(nextState), previousSet = new Set(previousKeys), nextSet = new Set(nextKeys), batchOps = [];
+  for (const key of previousKeys)
+    if (!nextSet.has(key))
+      batchOps.push({ type: "delete", key });
+  for (const key of nextKeys)
+    if (!previousSet.has(key))
+      batchOps.push({ type: "put", key, value: EMPTY_INDEX_VALUE });
+  const manifestPayload = {
+    version: WORKFLOW_VISIBILITY_INDEX_VERSION,
+    keys: nextKeys
+  };
+  batchOps.push({ type: "put", key: manifestKey, value: encode(manifestPayload) });
+  return { batchOps, nextManifestKeys: nextKeys };
+}
+const EMPTY_INDEX_VALUE = new Uint8Array(0);
+export async function getWorkflowVisibilityWatermark(storage) {
+  const bytes = await storage.get(KEYS.workflowVisibilityMetaVersion());
+  if (!bytes)
+    return "stale";
+  let payload;
+  try {
+    payload = decode(bytes);
+  } catch {
+    return "stale";
+  }
+  if (typeof payload !== "number")
+    return "stale";
+  return payload >= WORKFLOW_VISIBILITY_INDEX_VERSION ? "current" : "stale";
+}

package/dist/core/engine/workflow-state-stream.d.ts

@@ -0,0 +1,9 @@
+import type { AttributeFilter, ListFilter, WorkflowState } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+/** Stream decoded workflow states that match a list filter. */
+export declare function streamMatchingWorkflowStates(internals: EngineInternals, filter?: ListFilter): AsyncGenerator<WorkflowState>;
+/** Resolve the indexed workflow IDs implied by tag and search-attribute filters. */
+export declare function resolveConstrainedIds(internals: EngineInternals, filter: ListFilter | undefined, normalizedTagFilters: readonly string[] | undefined): Promise<Set<string> | null>;
+/** Query a single search-attribute index filter and return matching workflow IDs. */
+export declare function queryAttributeIndex(internals: EngineInternals, filter: AttributeFilter): Promise<Set<string>>;
+export declare function isTopLevelWorkflowStateKey(key: string): boolean;

package/dist/core/engine/workflow-state-stream.js

@@ -0,0 +1,126 @@
+import {
+  KEYS,
+  encodeStorageKeyComponent,
+  tryDecodeStorageKeyComponent
+} from "../../storage/interface.js";
+import { failureCategorySearchValues, isFailureCategory } from "../failure-categories.js";
+import { encodeAttributeValue, searchAttributeName } from "../search-attributes.js";
+import { normalizeWorkflowTags } from "../workflow-tags.js";
+import { intersectIdentifierSets, matchesListFilter } from "./state-utilities.js";
+import { decodeWorkflowState } from "./validation.js";
+const ATTRIBUTE_SCAN_CONCURRENCY = 8;
+export async function* streamMatchingWorkflowStates(internals, filter) {
+  const normalizedTagFilters = normalizeWorkflowTags(filter?.tags), constrainedIds = await resolveConstrainedIds(internals, filter, normalizedTagFilters);
+  if (constrainedIds !== null) {
+    for (const workflowId of constrainedIds) {
+      const state = await loadMatchingWorkflowState(internals, workflowId, filter, constrainedIds, normalizedTagFilters);
+      if (state === null)
+        continue;
+      yield state;
+    }
+    return;
+  }
+  for await (const [key, value] of internals.storage.scan("wf:")) {
+    if (!isTopLevelWorkflowStateKey(key))
+      continue;
+    const state = decodeWorkflowState(value);
+    if (!matchesListFilter(state, filter, constrainedIds, normalizedTagFilters))
+      continue;
+    yield state;
+  }
+}
+async function loadMatchingWorkflowState(internals, workflowId, filter, constrainedIds, normalizedTagFilters) {
+  const stateBytes = await internals.storage.get(KEYS.workflow(workflowId));
+  if (!stateBytes)
+    return null;
+  const state = decodeWorkflowState(stateBytes);
+  if (!matchesListFilter(state, filter, constrainedIds, normalizedTagFilters))
+    return null;
+  return state;
+}
+export async function resolveConstrainedIds(internals, filter, normalizedTagFilters) {
+  const attributeFilters = filter?.attributes, hasAttributeFilters = attributeFilters !== void 0 && attributeFilters.length > 0, hasTagFilters = normalizedTagFilters !== void 0 && normalizedTagFilters.length > 0;
+  if (!hasAttributeFilters && !hasTagFilters)
+    return null;
+  const queries = buildConstrainedIdQueries(internals, normalizedTagFilters, attributeFilters);
+  return intersectIdentifierSets(await runConstrainedIdQueries(queries));
+}
+export async function queryAttributeIndex(internals, filter) {
+  const ids = new Set, attributeName = searchAttributeName(filter.key), prefix = `idx:${attributeName}:`;
+  if (filter.value !== void 0)
+    await collectExactAttributeMatches(internals, filter, attributeName, ids);
+  else
+    await collectRangeAttributeMatches(internals, filter, prefix, ids);
+  return ids;
+}
+function buildConstrainedIdQueries(internals, normalizedTagFilters, attributeFilters) {
+  return [
+    ...normalizedTagFilters?.map((tag) => () => queryTagIndex(internals, tag)) ?? [],
+    ...attributeFilters?.map((attributeFilter) => () => queryAttributeIndex(internals, attributeFilter)) ?? []
+  ];
+}
+async function runConstrainedIdQueries(queries) {
+  const idSets = Array.from({ length: queries.length });
+  let nextIndex = 0;
+  const runWorker = async () => {
+    while (nextIndex < queries.length) {
+      const currentIndex = nextIndex;
+      nextIndex += 1;
+      idSets[currentIndex] = await queries[currentIndex]();
+    }
+  }, workerLimit = Math.max(1, Math.min(ATTRIBUTE_SCAN_CONCURRENCY, queries.length));
+  await Promise.all(Array.from({ length: workerLimit }, () => runWorker()));
+  return idSets.map(requireConstrainedIdSet);
+}
+function requireConstrainedIdSet(idSet) {
+  if (idSet === void 0)
+    throw Error("Attribute index query did not produce a workflow ID set.");
+  return idSet;
+}
+async function collectExactAttributeMatches(internals, filter, attributeName, ids) {
+  const exactValue = filter.value;
+  if (exactValue === void 0)
+    return;
+  const values = filter.key === "failureCategory" && isFailureCategory(exactValue) ? failureCategorySearchValues(exactValue) : [exactValue];
+  for (const value of values) {
+    const exactPrefix = `idx:${attributeName}:${encodeAttributeValue(value)}:`;
+    for await (const [key] of internals.storage.scan(exactPrefix))
+      addWorkflowIdFromIndexKey(ids, key.slice(exactPrefix.length));
+  }
+}
+async function collectRangeAttributeMatches(internals, filter, prefix, ids) {
+  for await (const [key] of internals.storage.scan(prefix, attributeRangeScanOptions(filter))) {
+    const afterPrefix = key.slice(prefix.length), lastColon = afterPrefix.lastIndexOf(":");
+    if (lastColon >= 0)
+      addWorkflowIdFromIndexKey(ids, afterPrefix.slice(lastColon + 1));
+  }
+}
+function attributeRangeScanOptions(filter) {
+  const scanOptions = {};
+  if (filter.gte !== void 0)
+    scanOptions.gte = `idx:${searchAttributeName(filter.key)}:${encodeAttributeValue(filter.gte)}:`;
+  if (filter.gt !== void 0)
+    scanOptions.gt = `idx:${searchAttributeName(filter.key)}:${encodeAttributeValue(filter.gt)}:\xFF`;
+  if (filter.lte !== void 0)
+    scanOptions.lte = `idx:${searchAttributeName(filter.key)}:${encodeAttributeValue(filter.lte)}:\xFF`;
+  if (filter.lt !== void 0)
+    scanOptions.lt = `idx:${searchAttributeName(filter.key)}:${encodeAttributeValue(filter.lt)}:`;
+  return scanOptions;
+}
+function addWorkflowIdFromIndexKey(ids, encodedWorkflowId) {
+  const workflowId = tryDecodeStorageKeyComponent(encodedWorkflowId);
+  if (workflowId !== null)
+    ids.add(workflowId);
+}
+async function queryTagIndex(internals, tag) {
+  const ids = new Set, prefix = `tag:${encodeStorageKeyComponent(tag)}:`;
+  for await (const [key] of internals.storage.scan(prefix)) {
+    const workflowId = tryDecodeStorageKeyComponent(key.slice(prefix.length));
+    if (workflowId !== null)
+      ids.add(workflowId);
+  }
+  return ids;
+}
+export function isTopLevelWorkflowStateKey(key) {
+  return !key.slice(3).includes(":");
+}