@lostgradient/weft 0.2.0

package/dist/core/aggregate-validation.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { WeftError } from "./weft-error.js";
+const attributeDimensionSchema = z.object({ attribute: z.string().min(1) }).strict(), groupBySchema = z.union([
+  z.literal("status"),
+  z.literal("type"),
+  z.literal("failureCategory"),
+  attributeDimensionSchema
+]);
+export const AGGREGATE_DEFAULT_LIMIT = 1000, AGGREGATE_MAX_LIMIT = 1e4, MAX_AGGREGATE_DISTINCT_KEYS = 1e5, aggregateOptionsObjectSchema = z.object({
+  groupBy: groupBySchema,
+  limit: z.number().int().min(1).max(AGGREGATE_MAX_LIMIT).optional()
+}).strict();
+function flattenIssue(issue) {
+  const path = [];
+  for (const segment of issue.path)
+    if (typeof segment === "string" || typeof segment === "number")
+      path.push(segment);
+    else
+      path.push(String(segment));
+  return { path, message: issue.message, code: issue.code };
+}
+
+export class AggregateOptionsValidationError extends WeftError {
+  issues;
+  constructor(issues) {
+    const summary = issues.map((issue) => {
+      const path = issue.path.join(".");
+      return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+    }).join("; ");
+    super("AggregateOptionsValidationError", summary.length > 0 ? summary : "Invalid aggregate options");
+    this.issues = issues;
+  }
+}
+
+export class AggregateDistinctKeyCapExceededError extends WeftError {
+  cap;
+  constructor(cap) {
+    super("AggregateDistinctKeyCapExceededError", `Aggregate query would exceed the distinct-key cap of ${cap}. Narrow the filter or choose a lower-cardinality groupBy.`);
+    this.cap = cap;
+  }
+}
+export function normalizeAggregateOptions(input) {
+  const result = aggregateOptionsObjectSchema.safeParse(input ?? {});
+  if (!result.success)
+    throw new AggregateOptionsValidationError(result.error.issues.map(flattenIssue));
+  const { groupBy, limit } = result.data;
+  return { groupBy, ...limit !== void 0 && { limit } };
+}

package/dist/core/atomic-state-events.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Sleep function signature. Accepts a duration in milliseconds and returns
+ * a promise that resolves after the delay. Injectable for tests.
+ *
+ * @example
+ * ```ts
+ * import type { SleepFunction } from '@lostgradient/weft';
+ *
+ * const sleep: SleepFunction = async (milliseconds) => {
+ *   await Bun.sleep(milliseconds);
+ * };
+ * void sleep;
+ * ```
+ */
+export type SleepFunction = (milliseconds: number) => Promise<void>;
+/**
+ * Options for a storage-backed {@link AtomicState} handle.
+ *
+ * @example
+ * ```ts
+ * import type { AtomicStateOptions } from '@lostgradient/weft';
+ *
+ * const options: AtomicStateOptions<number> = {
+ *   initial: 0,
+ *   maxRetries: 5,
+ * };
+ * ```
+ */
+export interface AtomicStateOptions<T = unknown> {
+    /**
+     * Value returned by `get()` before the slot has ever been written. Once a
+     * write or delete creates a version tombstone, an absent value reads as
+     * `undefined`.
+     */
+    initial?: T;
+    /** Maximum number of CAS attempts before giving up. Defaults to 10. */
+    maxRetries?: number;
+    /**
+     * Sleep function used between retry attempts. Defaults to portable `sleep`.
+     * Injection point for tests that need to observe backoff without paying
+     * real time costs.
+     */
+    sleep?: SleepFunction;
+}
+/**
+ * Storage scope for a durable atomic state slot.
+ *
+ * @example
+ * ```ts
+ * import type { AtomicStateScope } from '@lostgradient/weft';
+ *
+ * const scope: AtomicStateScope = {
+ *   type: 'workflow',
+ *   workflowType: 'invoice',
+ * };
+ * ```
+ */
+export type AtomicStateScope = {
+    type: 'execution';
+    ownerWorkflowId: string;
+} | {
+    type: 'workflow';
+    workflowType: string;
+};
+/**
+ * Point-in-time read result for an {@link AtomicState} slot.
+ *
+ * @example
+ * ```ts
+ * import type { AtomicStateSnapshot } from '@lostgradient/weft';
+ *
+ * const snapshot: AtomicStateSnapshot<number> = { value: 1, version: 2 };
+ * console.log(snapshot.version);
+ * ```
+ */
+export interface AtomicStateSnapshot<T = unknown> {
+    value: T | undefined;
+    version: number;
+}
+/**
+ * Result returned by an atomic state commit attempt.
+ *
+ * @example
+ * ```ts
+ * import type { AtomicStateCommitResult } from '@lostgradient/weft';
+ *
+ * const result: AtomicStateCommitResult<string> = {
+ *   applied: true,
+ *   value: 'ready',
+ *   version: 3,
+ * };
+ * console.log(result.applied);
+ * ```
+ */
+export interface AtomicStateCommitResult<T = unknown> extends AtomicStateSnapshot<T> {
+    applied: boolean;
+}
+/**
+ * Local event emitted by an {@link AtomicState} handle.
+ *
+ * @example
+ * ```ts
+ * import { AtomicStateChangeEvent, type AtomicStateEvent } from '@lostgradient/weft';
+ *
+ * const event: AtomicStateEvent<number> = new AtomicStateChangeEvent(1, undefined, 1);
+ * console.log(event.type);
+ * ```
+ */
+export type AtomicStateEvent<T = unknown> = AtomicStateChangeEvent<T> | AtomicStateConflictEvent | AtomicStateExhaustedEvent;
+/**
+ * Observer shape accepted by the {@link AtomicState} observable projection.
+ *
+ * @example
+ * ```ts
+ * import type { AtomicStateObserver } from '@lostgradient/weft';
+ *
+ * const observer: AtomicStateObserver<number> = {
+ *   next(event) {
+ *     console.log(event.type);
+ *   },
+ * };
+ * ```
+ */
+export type AtomicStateObserver<T = unknown> = ((event: AtomicStateEvent<T>) => void) | {
+    next?: (event: AtomicStateEvent<T>) => void;
+    error?: (error: unknown) => void;
+    complete?: () => void;
+};
+/**
+ * Subscription returned by an {@link AtomicState} observable.
+ *
+ * @example
+ * ```ts
+ * import type { AtomicStateSubscription } from '@lostgradient/weft';
+ *
+ * const subscription: AtomicStateSubscription = {
+ *   unsubscribe() {},
+ * };
+ * subscription.unsubscribe();
+ * ```
+ */
+export interface AtomicStateSubscription {
+    unsubscribe(): void;
+}
+declare global {
+    interface SymbolConstructor {
+        readonly observable: unique symbol;
+    }
+}
+/**
+ * Runtime symbol used by {@link AtomicState} to expose its observable
+ * projection. This is `Symbol.observable` when the platform provides it and
+ * `Symbol.for('observable')` otherwise.
+ *
+ * @example
+ * ```ts
+ * import { AtomicState, OBSERVABLE_SYMBOL } from '@lostgradient/weft';
+ * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
+ *
+ * const state = new AtomicState<number>(new MemoryStorage(), 'state:workflow-scope:default:count');
+ * const observable = state[OBSERVABLE_SYMBOL]();
+ * void observable;
+ * ```
+ */
+export declare const OBSERVABLE_SYMBOL: typeof Symbol.observable;
+/**
+ * Event emitted after an atomic state value changes.
+ *
+ * @example
+ * ```ts
+ * import { AtomicStateChangeEvent } from '@lostgradient/weft';
+ *
+ * const event = new AtomicStateChangeEvent('next', 'previous', 4);
+ * console.log(event.value, event.previousValue, event.version);
+ * ```
+ */
+export declare class AtomicStateChangeEvent<T> extends Event {
+    readonly value: T | undefined;
+    readonly previousValue: T | undefined;
+    readonly version: number;
+    constructor(value: T | undefined, previousValue: T | undefined, version: number);
+}
+/**
+ * Event emitted when a CAS attempt observes a concurrent write.
+ *
+ * @example
+ * ```ts
+ * import { AtomicStateConflictEvent } from '@lostgradient/weft';
+ *
+ * const event = new AtomicStateConflictEvent('state:workflow-scope:default:count', 2);
+ * console.log(event.stateKey, event.attempt);
+ * ```
+ */
+export declare class AtomicStateConflictEvent extends Event {
+    readonly stateKey: string;
+    readonly attempt: number;
+    constructor(stateKey: string, attempt: number);
+}
+/**
+ * Event emitted when the CAS retry budget is exhausted.
+ *
+ * @example
+ * ```ts
+ * import { AtomicStateExhaustedEvent } from '@lostgradient/weft';
+ *
+ * const event = new AtomicStateExhaustedEvent('state:workflow-scope:default:count', 10);
+ * console.log(event.stateKey, event.attempts);
+ * ```
+ */
+export declare class AtomicStateExhaustedEvent extends Event {
+    readonly stateKey: string;
+    readonly attempts: number;
+    constructor(stateKey: string, attempts: number);
+}

package/dist/core/atomic-state-events.js

@@ -0,0 +1,39 @@
+const symbolConstructor = Symbol, fallbackObservableSymbol = Symbol.for("observable");
+export const OBSERVABLE_SYMBOL = symbolConstructor.observable ?? fallbackObservableSymbol;
+if (symbolConstructor.observable === void 0)
+  Object.defineProperty(Symbol, "observable", {
+    value: OBSERVABLE_SYMBOL,
+    configurable: !0
+  });
+
+export class AtomicStateChangeEvent extends Event {
+  value;
+  previousValue;
+  version;
+  constructor(value, previousValue, version) {
+    super("change");
+    this.value = value;
+    this.previousValue = previousValue;
+    this.version = version;
+  }
+}
+
+export class AtomicStateConflictEvent extends Event {
+  stateKey;
+  attempt;
+  constructor(stateKey, attempt) {
+    super("conflict");
+    this.stateKey = stateKey;
+    this.attempt = attempt;
+  }
+}
+
+export class AtomicStateExhaustedEvent extends Event {
+  stateKey;
+  attempts;
+  constructor(stateKey, attempts) {
+    super("exhausted");
+    this.stateKey = stateKey;
+    this.attempts = attempts;
+  }
+}

package/dist/core/atomic-state.d.ts

@@ -0,0 +1,79 @@
+import type { Storage } from '../storage/interface.ts';
+import { OBSERVABLE_SYMBOL, type AtomicStateCommitResult, type AtomicStateEvent, type AtomicStateObserver, type AtomicStateOptions, type AtomicStateScope, type AtomicStateSnapshot, type AtomicStateSubscription } from './atomic-state-events.ts';
+import { WeftError } from './weft-error.ts';
+export { AtomicStateChangeEvent, AtomicStateConflictEvent, AtomicStateExhaustedEvent, OBSERVABLE_SYMBOL, } from './atomic-state-events.ts';
+export type { AtomicStateCommitResult, AtomicStateEvent, AtomicStateObserver, AtomicStateOptions, AtomicStateScope, AtomicStateSnapshot, AtomicStateSubscription, SleepFunction, } from './atomic-state-events.ts';
+/**
+ * Thrown by {@link AtomicState.update} when the CAS (compare-and-swap) loop
+ * exhausts its retry budget without successfully committing.
+ *
+ * @example
+ * ```ts
+ * import { AtomicState, AtomicStateConflictError } from '@lostgradient/weft';
+ * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
+ *
+ * const storage = new MemoryStorage();
+ * const state = new AtomicState<number>(storage, 'state:workflow-scope:default:counter', {
+ *   initial: 0,
+ *   maxRetries: 3,
+ * });
+ * try {
+ *   await state.increment();
+ * } catch (error) {
+ *   if (error instanceof AtomicStateConflictError) {
+ *     console.error('conflict on', error.stateKey, 'after', error.attempts, 'attempts');
+ *   }
+ * }
+ * ```
+ */
+export declare class AtomicStateConflictError extends WeftError<'AtomicStateConflictError'> {
+    readonly stateKey: string;
+    readonly attempts: number;
+    constructor(stateKey: string, attempts: number);
+}
+export declare function atomicStateDataKey(scope: AtomicStateScope, key: string): string;
+export declare function atomicStateVersionKey(dataKey: string): string;
+export declare function readAtomicStateSnapshot<T>(storage: Storage, dataKey: string, options?: Pick<AtomicStateOptions<T>, 'initial'>): Promise<AtomicStateSnapshot<T>>;
+export declare function commitAtomicStateValue<T>(storage: Storage, dataKey: string, expectedVersion: number, value: T): Promise<AtomicStateCommitResult<T>>;
+export declare function commitAtomicStateDelete(storage: Storage, dataKey: string, expectedVersion: number): Promise<AtomicStateCommitResult<never>>;
+/**
+ * Storage-backed compare-and-swap state slot. `AtomicState` is scoped by the
+ * storage key supplied to the constructor; use `engine.state.*` and
+ * `ctx.state.*` for the built-in execution and workflow scopes.
+ *
+ * @example
+ * ```ts
+ * import { AtomicState } from '@lostgradient/weft';
+ * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
+ *
+ * const storage = new MemoryStorage();
+ * const counter = new AtomicState<number>(storage, 'state:workflow-scope:default:count', { initial: 0 });
+ * await counter.increment();
+ * console.log(await counter.get()); // 1
+ * ```
+ */
+export declare class AtomicState<T> extends EventTarget {
+    #private;
+    constructor(storage: Storage, dataKey: string, options?: AtomicStateOptions<T>);
+    /** Read the current value. */
+    get(): Promise<T | undefined>;
+    /** Update the state with optimistic concurrency and automatic retry. */
+    update(updater: (current: T | undefined) => T): Promise<T>;
+    /** Replace the state value. */
+    set(value: T): Promise<T>;
+    /**
+     * Delete the state value while still advancing the version tombstone so
+     * concurrent writers cannot silently overwrite a delete.
+     */
+    delete(): Promise<void>;
+    increment(this: AtomicState<number>, amount?: number): Promise<number>;
+    decrement(this: AtomicState<number>, amount?: number): Promise<number>;
+    merge<TObject extends Record<string, unknown>>(this: AtomicState<TObject>, patch: Partial<TObject>): Promise<TObject>;
+    append<TItem>(this: AtomicState<TItem[]>, item: TItem): Promise<TItem[]>;
+    removeFirst<TItem>(this: AtomicState<TItem[]>): Promise<TItem | undefined>;
+    removeLast<TItem>(this: AtomicState<TItem[]>): Promise<TItem | undefined>;
+    [OBSERVABLE_SYMBOL](): {
+        subscribe: (observer: AtomicStateObserver<T>) => AtomicStateSubscription;
+    };
+    [Symbol.asyncIterator](): AsyncIterator<AtomicStateEvent<T>>;
+}

package/dist/core/atomic-state.js

@@ -0,0 +1,231 @@
+import { sleep as portableSleep } from "../runtime/portable.js";
+import { KEYS, requireStorageCapability, storageConditionalBatch } from "../storage/interface.js";
+import {
+  AtomicStateChangeEvent,
+  AtomicStateConflictEvent,
+  AtomicStateExhaustedEvent,
+  OBSERVABLE_SYMBOL
+} from "./atomic-state-events.js";
+import { decode, encode } from "./codec.js";
+import { WeftError } from "./weft-error.js";
+export {
+  AtomicStateChangeEvent,
+  AtomicStateConflictEvent,
+  AtomicStateExhaustedEvent,
+  OBSERVABLE_SYMBOL
+} from "./atomic-state-events.js";
+const ATOMIC_STATE_BASE_DELAY_MS = 5, ATOMIC_STATE_MAX_DELAY_MS = 100, MAX_ATOMIC_STATE_KEY_LENGTH = 256, RESERVED_ATOMIC_STATE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+export class AtomicStateConflictError extends WeftError {
+  stateKey;
+  attempts;
+  constructor(stateKey, attempts) {
+    super("AtomicStateConflictError", `AtomicState conflict: failed to update "${stateKey}" after ${String(attempts)} attempts`);
+    this.stateKey = stateKey;
+    this.attempts = attempts;
+  }
+}
+export function atomicStateDataKey(scope, key) {
+  assertValidAtomicStateKey(key);
+  switch (scope.type) {
+    case "execution":
+      return KEYS.stateExecution(scope.ownerWorkflowId, key);
+    case "workflow":
+      return KEYS.stateWorkflow(scope.workflowType, key);
+  }
+}
+function assertValidAtomicStateKey(key) {
+  if (key.length === 0 || key.length > MAX_ATOMIC_STATE_KEY_LENGTH)
+    throw Error(`AtomicState key must be 1-${String(MAX_ATOMIC_STATE_KEY_LENGTH)} characters long.`);
+  if (RESERVED_ATOMIC_STATE_KEYS.has(key))
+    throw Error(`AtomicState key "${key}" is reserved.`);
+}
+export function atomicStateVersionKey(dataKey) {
+  return `${dataKey}:version`;
+}
+export async function readAtomicStateSnapshot(storage, dataKey, options) {
+  const [rawValue, rawVersion] = await Promise.all([
+    storage.get(dataKey),
+    storage.get(atomicStateVersionKey(dataKey))
+  ]), version = rawVersion ? decodeAtomicStateVersion(rawVersion, dataKey) : 0;
+  if (rawValue !== null)
+    return { value: decode(rawValue), version };
+  if (rawVersion === null && options && "initial" in options)
+    return { value: cloneInitialValue(options.initial), version };
+  return { value: void 0, version };
+}
+export async function commitAtomicStateValue(storage, dataKey, expectedVersion, value) {
+  requireStorageCapability(storage, "conditionalBatch", "AtomicState compare-and-swap");
+  const nextVersion = expectedVersion + 1, applied = await storageConditionalBatch(storage, [versionCondition(dataKey, expectedVersion)], [
+    { type: "put", key: dataKey, value: encode(value) },
+    { type: "put", key: atomicStateVersionKey(dataKey), value: encode(nextVersion) }
+  ]);
+  return { applied, value, version: applied ? nextVersion : expectedVersion };
+}
+export async function commitAtomicStateDelete(storage, dataKey, expectedVersion) {
+  requireStorageCapability(storage, "conditionalBatch", "AtomicState compare-and-swap");
+  const nextVersion = expectedVersion + 1, applied = await storageConditionalBatch(storage, [versionCondition(dataKey, expectedVersion)], [
+    { type: "delete", key: dataKey },
+    { type: "put", key: atomicStateVersionKey(dataKey), value: encode(nextVersion) }
+  ]);
+  return { applied, value: void 0, version: applied ? nextVersion : expectedVersion };
+}
+function versionCondition(dataKey, expectedVersion) {
+  return {
+    key: atomicStateVersionKey(dataKey),
+    expectedValue: expectedVersion === 0 ? null : encode(expectedVersion)
+  };
+}
+function decodeAtomicStateVersion(rawVersion, dataKey) {
+  const decodedVersion = decode(rawVersion);
+  if (typeof decodedVersion !== "number" || !Number.isInteger(decodedVersion) || decodedVersion < 0)
+    throw Error(`AtomicState version for "${dataKey}" is corrupt.`);
+  return decodedVersion;
+}
+function cloneInitialValue(value) {
+  return structuredClone(value);
+}
+function retryDelay(attempt) {
+  const exponential = Math.min(ATOMIC_STATE_MAX_DELAY_MS, ATOMIC_STATE_BASE_DELAY_MS * 2 ** attempt);
+  return Math.floor(Math.random() * exponential);
+}
+function dispatchAtomicStateEvent(target, event) {
+  target.dispatchEvent(event);
+  return event;
+}
+function notifyObserver(observer, event) {
+  if (typeof observer === "function") {
+    observer(event);
+    return;
+  }
+  observer.next?.(event);
+}
+
+export class AtomicState extends EventTarget {
+  #storage;
+  #dataKey;
+  #stateKey;
+  #maxRetries;
+  #sleep;
+  #options;
+  constructor(storage, dataKey, options) {
+    super();
+    this.#storage = storage;
+    this.#dataKey = dataKey;
+    this.#stateKey = dataKey;
+    this.#maxRetries = options?.maxRetries ?? 10;
+    this.#sleep = options?.sleep ?? portableSleep;
+    this.#options = options && "initial" in options ? { initial: options.initial } : void 0;
+  }
+  async get() {
+    return (await this.#read()).value;
+  }
+  async update(updater) {
+    for (let attempt = 0;attempt < this.#maxRetries; attempt++) {
+      const snapshot = await this.#read(), nextValue = updater(snapshot.value), commit = await commitAtomicStateValue(this.#storage, this.#dataKey, snapshot.version, nextValue);
+      if (commit.applied) {
+        dispatchAtomicStateEvent(this, new AtomicStateChangeEvent(nextValue, snapshot.value, commit.version));
+        return nextValue;
+      }
+      dispatchAtomicStateEvent(this, new AtomicStateConflictEvent(this.#stateKey, attempt + 1));
+      if (attempt < this.#maxRetries - 1)
+        await this.#sleep(retryDelay(attempt));
+    }
+    dispatchAtomicStateEvent(this, new AtomicStateExhaustedEvent(this.#stateKey, this.#maxRetries));
+    throw new AtomicStateConflictError(this.#stateKey, this.#maxRetries);
+  }
+  async set(value) {
+    return this.update(() => value);
+  }
+  async delete() {
+    for (let attempt = 0;attempt < this.#maxRetries; attempt++) {
+      const snapshot = await this.#read(), commit = await commitAtomicStateDelete(this.#storage, this.#dataKey, snapshot.version);
+      if (commit.applied) {
+        dispatchAtomicStateEvent(this, new AtomicStateChangeEvent(void 0, snapshot.value, commit.version));
+        return;
+      }
+      dispatchAtomicStateEvent(this, new AtomicStateConflictEvent(this.#stateKey, attempt + 1));
+      if (attempt < this.#maxRetries - 1)
+        await this.#sleep(retryDelay(attempt));
+    }
+    dispatchAtomicStateEvent(this, new AtomicStateExhaustedEvent(this.#stateKey, this.#maxRetries));
+    throw new AtomicStateConflictError(this.#stateKey, this.#maxRetries);
+  }
+  increment(amount = 1) {
+    return this.update((current) => (current ?? 0) + amount);
+  }
+  decrement(amount = 1) {
+    return this.update((current) => (current ?? 0) - amount);
+  }
+  merge(patch) {
+    return this.update((current) => ({ ...current ?? {}, ...patch }));
+  }
+  append(item) {
+    return this.update((current) => [...current ?? [], item]);
+  }
+  removeFirst() {
+    let removed;
+    return this.update((current) => {
+      const next = [...current ?? []];
+      removed = next.shift();
+      return next;
+    }).then(() => removed);
+  }
+  removeLast() {
+    let removed;
+    return this.update((current) => {
+      const next = [...current ?? []];
+      removed = next.pop();
+      return next;
+    }).then(() => removed);
+  }
+  [OBSERVABLE_SYMBOL]() {
+    return {
+      subscribe: (observer) => {
+        const listener = (event) => {
+          notifyObserver(observer, event);
+        };
+        this.addEventListener("change", listener);
+        this.addEventListener("conflict", listener);
+        this.addEventListener("exhausted", listener);
+        return {
+          unsubscribe: () => {
+            this.removeEventListener("change", listener);
+            this.removeEventListener("conflict", listener);
+            this.removeEventListener("exhausted", listener);
+          }
+        };
+      }
+    };
+  }
+  async* [Symbol.asyncIterator]() {
+    const queue = [];
+    let notify;
+    const listener = (event) => {
+      queue.push(event);
+      notify?.();
+      notify = void 0;
+    };
+    this.addEventListener("change", listener);
+    this.addEventListener("conflict", listener);
+    this.addEventListener("exhausted", listener);
+    try {
+      while (!0) {
+        if (queue.length === 0)
+          await new Promise((resolve) => {
+            notify = resolve;
+          });
+        const event = queue.shift();
+        if (event)
+          yield event;
+      }
+    } finally {
+      this.removeEventListener("change", listener);
+      this.removeEventListener("conflict", listener);
+      this.removeEventListener("exhausted", listener);
+    }
+  }
+  async#read() {
+    return readAtomicStateSnapshot(this.#storage, this.#dataKey, this.#options);
+  }
+}

package/dist/core/bulk-workflow-filter.d.ts

@@ -0,0 +1,23 @@
+import type { ListFilter } from './types.ts';
+export declare const BULK_WORKFLOW_FILTER_ERROR_MESSAGE = "Field \"filter\" must include at least one of status, type, tags, attributes, idPrefix (\u22653 chars), or failureCategory paired with status";
+/**
+ * Returns `true` when the filter narrows destructive bulk operations
+ * to a scoped subset rather than every workflow on the engine.
+ *
+ * Valid scopes:
+ * - `status` (non-empty after normalization).
+ * - `type` (non-empty after trim).
+ * - `tags` (at least one tag after normalization).
+ * - `attributes` (at least one attribute predicate with a non-empty key).
+ * - `idPrefix` (length ≥ 3 — short prefixes match too much to be a safe scope).
+ * - `failureCategory` is **not** a valid scope on its own — it must be
+ *   combined with a non-empty status filter. The engine doesn't enforce
+ *   the "failureCategory implies failed status" invariant (the attribute
+ *   could theoretically be set on a non-failed workflow), so deleting on
+ *   the attribute alone would be a footgun.
+ * - Time ranges (`createdAt`, `updatedAt`, `executionDeadline`) are
+ *   **not** valid scopes on their own — they must combine with another
+ *   dimension from the list above.
+ */
+export declare function hasScopedBulkWorkflowFilter(filter: ListFilter): boolean;
+export declare function assertScopedBulkWorkflowFilter(filter: ListFilter): ListFilter;

package/dist/core/bulk-workflow-filter.js

@@ -0,0 +1,38 @@
+import { searchAttributeName } from "./search-attributes.js";
+import { normalizeWorkflowTags } from "./workflow-tags.js";
+const ID_PREFIX_MIN_LENGTH = 3;
+export const BULK_WORKFLOW_FILTER_ERROR_MESSAGE = 'Field "filter" must include at least one of status, type, tags, attributes, idPrefix (\u22653 chars), or failureCategory paired with status';
+function hasScopedStatusFilter(filter) {
+  if (filter.status === void 0)
+    return !1;
+  if (Array.isArray(filter.status))
+    return filter.status.length > 0;
+  return filter.status.length > 0;
+}
+function hasScopedTypeFilter(filter) {
+  return filter.type !== void 0 && filter.type.trim().length > 0;
+}
+function hasScopedTagsFilter(filter) {
+  return (normalizeWorkflowTags(filter.tags)?.length ?? 0) > 0;
+}
+function hasScopedAttributesFilter(filter) {
+  return filter.attributes?.some((attribute) => searchAttributeName(attribute.key).trim().length > 0) ?? !1;
+}
+function hasScopedIdPrefix(filter) {
+  return filter.idPrefix !== void 0 && filter.idPrefix.length >= ID_PREFIX_MIN_LENGTH;
+}
+const BULK_FILTER_DIMENSION_CHECKS = {
+  status: hasScopedStatusFilter,
+  type: hasScopedTypeFilter,
+  tags: hasScopedTagsFilter,
+  attributes: hasScopedAttributesFilter,
+  idPrefix: hasScopedIdPrefix
+};
+export function hasScopedBulkWorkflowFilter(filter) {
+  return Object.values(BULK_FILTER_DIMENSION_CHECKS).some((check) => check(filter));
+}
+export function assertScopedBulkWorkflowFilter(filter) {
+  if (!hasScopedBulkWorkflowFilter(filter))
+    throw Error(BULK_WORKFLOW_FILTER_ERROR_MESSAGE);
+  return filter;
+}

package/dist/core/checkpoint/comparison.d.ts

@@ -0,0 +1,2 @@
+import type { CheckpointDivergence } from './interfaces.ts';
+export declare function compareValues(original: unknown, deserialized: unknown, path: string, divergences: CheckpointDivergence[]): void;