@lostgradient/weft 0.2.0

package/dist/core/context/state-namespace.js

@@ -0,0 +1,138 @@
+import {
+  AtomicStateChangeEvent,
+  AtomicStateConflictError,
+  AtomicStateConflictEvent,
+  atomicStateDataKey,
+  AtomicStateExhaustedEvent
+} from "../atomic-state.js";
+import * as stateSessionHelpers from "./session-state.js";
+import { captureCallerStack } from "./validation.js";
+export function createStateNamespace(context, internals) {
+  const operationCache = createContextStateOperationCache(context, internals);
+  return {
+    session: (key, options) => stateSessionHelpers.stateSession(context, internals, key, options),
+    execution: (key, options) => new WorkflowAtomicStateHandle({ type: "execution", ownerWorkflowId: internals.executionStateOwnerId }, key, options, operationCache),
+    workflow: (key, options) => new WorkflowAtomicStateHandle({ type: "workflow", workflowType: context.workflowType }, key, options, operationCache)
+  };
+}
+function createContextStateOperationCache(context, internals) {
+  return {
+    nextStep: () => internals.stepIndex++,
+    has: (step) => internals.accumulatedResults?.has(step) ?? !1,
+    get: (step) => internals.accumulatedResults?.get(step),
+    set: (step, value) => {
+      context.accumulatedResults.set(step, value);
+    }
+  };
+}
+
+export class WorkflowAtomicStateHandle extends EventTarget {
+  #scope;
+  #key;
+  #dataKey;
+  #maxRetries;
+  #options;
+  #operationCache;
+  constructor(scope, key, options, operationCache) {
+    super();
+    this.#scope = scope;
+    this.#key = key;
+    this.#dataKey = atomicStateDataKey(scope, key);
+    this.#maxRetries = options?.maxRetries ?? 10;
+    this.#options = options && "initial" in options ? { initial: options.initial } : void 0;
+    this.#operationCache = operationCache;
+  }
+  *get() {
+    return (yield* this.#read()).value;
+  }
+  *set(value) {
+    return yield* this.update(() => value);
+  }
+  *update(updater) {
+    for (let attempt = 0;attempt < this.#maxRetries; attempt++) {
+      const snapshot = yield* this.#read(), nextValue = updater(snapshot.value), commit = yield* this.#commit(snapshot.version, "set", nextValue);
+      if (commit.applied) {
+        this.dispatchEvent(new AtomicStateChangeEvent(nextValue, snapshot.value, commit.version));
+        return nextValue;
+      }
+      this.dispatchEvent(new AtomicStateConflictEvent(this.#dataKey, attempt + 1));
+    }
+    this.dispatchEvent(new AtomicStateExhaustedEvent(this.#dataKey, this.#maxRetries));
+    throw new AtomicStateConflictError(this.#dataKey, this.#maxRetries);
+  }
+  *delete() {
+    for (let attempt = 0;attempt < this.#maxRetries; attempt++) {
+      const snapshot = yield* this.#read(), commit = yield* this.#commit(snapshot.version, "delete");
+      if (commit.applied) {
+        this.dispatchEvent(new AtomicStateChangeEvent(void 0, snapshot.value, commit.version));
+        return;
+      }
+      this.dispatchEvent(new AtomicStateConflictEvent(this.#dataKey, attempt + 1));
+    }
+    this.dispatchEvent(new AtomicStateExhaustedEvent(this.#dataKey, this.#maxRetries));
+    throw new AtomicStateConflictError(this.#dataKey, this.#maxRetries);
+  }
+  *increment(amount = 1) {
+    return yield* this.update((current) => (current ?? 0) + amount);
+  }
+  *decrement(amount = 1) {
+    return yield* this.update((current) => (current ?? 0) - amount);
+  }
+  *merge(patch) {
+    return yield* this.update((current) => ({ ...current ?? {}, ...patch }));
+  }
+  *append(item) {
+    return yield* this.update((current) => [...current ?? [], item]);
+  }
+  *removeFirst() {
+    let removed;
+    yield* this.update((current) => {
+      const next = [...current ?? []];
+      removed = next.shift();
+      return next;
+    });
+    return removed;
+  }
+  *removeLast() {
+    let removed;
+    yield* this.update((current) => {
+      const next = [...current ?? []];
+      removed = next.pop();
+      return next;
+    });
+    return removed;
+  }
+  *#read() {
+    return yield* this.#executeOperation({
+      type: "state-read",
+      operationId: crypto.randomUUID(),
+      scope: this.#scope,
+      key: this.#key,
+      ...this.#options !== void 0 ? { initial: this.#options.initial } : {},
+      callerStack: captureCallerStack()
+    });
+  }
+  *#commit(expectedVersion, mode, value) {
+    return yield* this.#executeOperation({
+      type: "state-commit",
+      operationId: crypto.randomUUID(),
+      scope: this.#scope,
+      key: this.#key,
+      expectedVersion,
+      mode,
+      ...mode === "set" ? { value } : {},
+      callerStack: captureCallerStack()
+    });
+  }
+  *#executeOperation(operation) {
+    const operationCache = this.#operationCache;
+    if (operationCache === void 0)
+      return yield operation;
+    const step = operationCache.nextStep();
+    if (operationCache.has(step))
+      return operationCache.get(step);
+    const result = yield operation;
+    operationCache.set(step, result);
+    return result;
+  }
+}

package/dist/core/context/types.d.ts

@@ -0,0 +1,181 @@
+import type { ActivityDefinition, SearchAttributeSchema, SearchAttributeValue } from '../types.ts';
+/**
+ * A single step in a saga: an activity definition and the input to pass to it.
+ *
+ * `TInput` and `TOutput` are inferred from the definition so that `compensate`
+ * receives correctly-typed arguments at the definition site. At the array
+ * boundary inside `ctx.saga`, types are erased to `unknown` — the
+ * implementation guarantees that the input passed to `execute` and `compensate`
+ * always matches what was supplied in the original step object.
+ *
+ * @example
+ * ```ts
+ * import { activity, type SagaStep, type WorkflowContext } from '@lostgradient/weft';
+ *
+ * const chargeCard = activity({
+ *   name: 'chargeCard',
+ *   execute: async (input: unknown) => ({ chargeId: 'ch-123' }),
+ *   compensate: async (_input, _output) => { return; },
+ * });
+ *
+ * const step: SagaStep<unknown, { chargeId: string }> = {
+ *   definition: chargeCard,
+ *   input: { amount: 99 },
+ * };
+ * void step;
+ * ```
+ */
+export interface SagaStep<TInput = unknown, TOutput = unknown> {
+    definition: ActivityDefinition<TInput, TOutput>;
+    input: TInput;
+}
+export interface ErasedActivityDefinition {
+    name: string;
+    execute(input: unknown, context?: unknown): unknown;
+    compensate?(input: unknown, output?: unknown): unknown;
+}
+export interface ErasedSagaStep {
+    definition: ErasedActivityDefinition;
+    input: unknown;
+}
+/**
+ * Reference returned by `ctx.offload(key, fn)`. Store this in a local
+ * variable or pass it downstream — the engine keeps the heavy payload in
+ * storage and only checkpoints the lightweight reference. Retrieve the
+ * original value with `ctx.load(reference)`. Offload references are plain
+ * JSON-shaped objects, so they survive structured cloning, MessagePack
+ * encoding, and worker postMessage transfers — return them as workflow
+ * results or store them in attributes.
+ *
+ * @example
+ * ```ts
+ * import { workflow, activity, Engine, type OffloadReference, type WorkflowContext } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(
+ *   workflow({ name: 'heavy' }).execute(async function* (ctx: WorkflowContext, input: unknown) {
+ *     const ref: OffloadReference = yield* ctx.offload(
+ *       'large-payload',
+ *       async () => ({ data: 'x'.repeat(100_000) }),
+ *     );
+ *     console.log(ref.sizeBytes);
+ *     const payload = yield* ctx.load(ref);
+ *     return payload;
+ *   }),
+ * );
+ * void engine;
+ * ```
+ */
+export interface OffloadReference {
+    key: string;
+    workflowId: string;
+    sizeBytes: number;
+}
+/**
+ * Reference to a multi-chunk stream stored via `ctx.stream(key, fn)`. Contains
+ * the storage key, workflow ID, chunk count, and total byte size.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, type StreamReference, type WorkflowContext } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(
+ *   workflow({ name: 'streamer' }).execute(async function* (ctx: WorkflowContext) {
+ *     const ref: StreamReference = yield* ctx.stream('tokens', async function* () {
+ *       yield 'hello';
+ *     });
+ *     return ref.chunkCount;
+ *   }),
+ * );
+ * ```
+ */
+export interface StreamReference {
+    key: string;
+    workflowId: string;
+    chunkCount: number;
+    totalSizeBytes: number;
+}
+/**
+ * A single chunk persisted by `ctx.stream`. The `sequence` field is the
+ * zero-based chunk index used to reassemble the stream in order on replay.
+ */
+export interface StoredStreamChunk<T = unknown> {
+    sequence: number;
+    value: T;
+}
+/**
+ * Callback object passed to the async generator function inside `ctx.stream`.
+ * Call `sink.heartbeat()` periodically to extend the stream's visibility
+ * timeout and prevent the engine from marking it as stalled.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, type StreamSink, type WorkflowContext } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(
+ *   workflow({ name: 'streamer' }).execute(async function* (ctx: WorkflowContext) {
+ *     yield* ctx.stream('tokens', async function* (sink: StreamSink) {
+ *       sink.heartbeat({ chunk: 0 });
+ *       yield 'hello';
+ *     });
+ *   }),
+ * );
+ * ```
+ */
+export interface StreamSink {
+    heartbeat(details?: unknown): void;
+}
+/**
+ * Construction options for the {@link Context} class. Populated by the engine
+ * before invoking a workflow generator; advanced consumers may construct
+ * `Context` directly with these options.
+ *
+ * @example
+ * ```ts
+ * import { Context, type ContextOptions } from '@lostgradient/weft';
+ *
+ * const controller = new AbortController();
+ * const options: ContextOptions = {
+ *   workflowId: 'wf-demo',
+ *   workflowType: 'demo',
+ *   startedAt: Date.now(),
+ *   abortController: controller,
+ * };
+ * const ctx = new Context(options);
+ * void ctx;
+ * ```
+ */
+export interface ContextOptions {
+    workflowId: string;
+    workflowType: string;
+    startedAt: number;
+    abortController: AbortController;
+    deadline?: number;
+    initialStep?: number;
+    accumulatedResults?: Map<number, unknown>;
+    locals?: Record<string, unknown>;
+    searchAttributes?: Record<string, SearchAttributeValue>;
+    searchAttributeSchema?: SearchAttributeSchema;
+    getNow?: () => number;
+    nestingDepth?: number;
+    /**
+     * Owner identifier for `ctx.state.execution()`. Defaults to the workflow id.
+     * Child workflows inherit the parent's owner so execution-scoped state is
+     * shared across a durable execution tree.
+     */
+    executionStateOwnerId?: string;
+    /**
+     * Reference timestamp used to compute `scheduledFireAt` for sleep operations.
+     * When resuming from a checkpoint, this should be the checkpoint's `createdAt`.
+     */
+    sleepReferenceTime?: number;
+    resolveWorkflowType?: (target: string | Function) => string;
+    /**
+     * Called by `ctx.onCancel()` to keep the handler in engine memory outside
+     * the transient context instance. The handler survives inline parking, but
+     * it is not persisted or restored after engine restart.
+     */
+    registerCancelHandler?: (handler: () => Promise<void> | void) => () => void;
+}

package/dist/core/context/updates.d.ts

@@ -0,0 +1,46 @@
+import type { ContextInternals } from './internals.ts';
+/**
+ * Options for `ctx.onUpdate`. Currently supports an optional pre-acceptance
+ * validator that runs before the update payload is durably written.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, update } from '@lostgradient/weft';
+ * import type { UpdateHandlerOptions } from '@lostgradient/weft';
+ *
+ * const setAge = update<{ age: number }, void>('setAge');
+ * const engine = new Engine();
+ * engine.register(
+ *   workflow({ name: 'demo' }).execute(async function* (ctx) {
+ *     const options: UpdateHandlerOptions = {
+ *       validator: (v): unknown => {
+ *         const age = (v as Record<string, unknown>)['age'];
+ *         if (typeof age !== 'number' || age < 0) {
+ *           return { issues: [{ message: 'age must be non-negative' }] };
+ *         }
+ *         return undefined;
+ *       },
+ *     };
+ *     ctx.onUpdate(setAge, () => undefined, options);
+ *     await new Promise(() => {});
+ *   }),
+ * );
+ * void engine;
+ * ```
+ */
+export type UpdateHandlerOptions = {
+    /**
+     * Pre-acceptance validator. Runs at the engine boundary before the payload
+     * is durably written or the workflow observes it.
+     *
+     * - **Throw** to reject: the thrown error message is wrapped into an
+     *   `UpdateValidationError`.
+     * - **Return `{ issues: [...] }`** (Standard Schema v1 failure result) to
+     *   reject with structured messages.
+     * - **Return anything else** (including `undefined`) to accept.
+     */
+    readonly validator?: (payload: unknown) => unknown;
+};
+export declare function onUpdate(internals: ContextInternals, name: string, handler: (payload: unknown) => unknown, options?: UpdateHandlerOptions): void;
+export declare function onQuery(internals: ContextInternals, name: string, handler: (input: unknown) => unknown): void;
+export declare function expose(internals: ContextInternals, accessors: Record<string, () => unknown>): void;

package/dist/core/context/updates.js

@@ -0,0 +1,21 @@
+import { isAsyncGeneratorFunction, isGeneratorFunction } from "../step-context.js";
+export function onUpdate(internals, name, handler, options) {
+  if (isGeneratorFunction(handler) || isAsyncGeneratorFunction(handler))
+    throw TypeError(`Update handler "${name}" cannot be a generator function. ` + "Use a plain function \u2014 update handlers run synchronously at checkpoint boundaries and cannot yield.");
+  internals.updateHandlers ??= new Map;
+  internals.updateHandlers.set(name, handler);
+  if (options?.validator !== void 0) {
+    internals.updateValidators ??= new Map;
+    internals.updateValidators.set(name, options.validator);
+  } else
+    internals.updateValidators?.delete(name);
+}
+export function onQuery(internals, name, handler) {
+  internals.queryHandlers ??= new Map;
+  internals.queryHandlers.set(name, handler);
+}
+export function expose(internals, accessors) {
+  internals.exposedValues ??= new Map;
+  for (const [key, accessor] of Object.entries(accessors))
+    internals.exposedValues.set(key, accessor);
+}

package/dist/core/context/validation.d.ts

@@ -0,0 +1,2 @@
+export declare function captureCallerStack(): string;
+export declare function trimCallerStack(stack: string): string;

package/dist/core/context/validation.js

@@ -0,0 +1,12 @@
+export function captureCallerStack() {
+  const error = Error();
+  return trimCallerStack(error.stack ?? "");
+}
+export function trimCallerStack(stack) {
+  const stackLines = stack.split(`
+`);
+  if (stackLines.length <= 4)
+    return stack;
+  return stackLines.slice(0, 4).join(`
+`);
+}

package/dist/core/context.d.ts

@@ -0,0 +1 @@
+export * from './context/index.ts';

package/dist/core/context.js

@@ -0,0 +1 @@
+export * from "./context/index.js";

package/dist/core/debug-output.d.ts

@@ -0,0 +1,3 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function sanitizeDebugValueForDisplay(value: unknown): unknown;
+export declare function safeDebugStringify(value: unknown, indentation?: number): string;

package/dist/core/debug-output.js

@@ -0,0 +1,112 @@
+const REDACTED_VALUE = "[REDACTED]", CIRCULAR_REFERENCE_VALUE = "[Circular]", UNSERIALIZABLE_VALUE = "[unserializable]", SENSITIVE_KEY_PATTERN = /(?:access[-_]?token|api[-_]?key|auth(?:orization)?|card(?:number)?|cookie|credential|cvc|cvv|pass(?:word|phrase)?|private[-_]?key|refresh[-_]?token|secret|session|ssn|token)/i;
+function isSensitiveKey(key) {
+  return SENSITIVE_KEY_PATTERN.test(key);
+}
+function looksLikeJsonWebToken(value) {
+  if (!/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(value))
+    return !1;
+  return value.split(".").every((segment) => segment.length >= 6);
+}
+function passesLuhnCheck(value) {
+  let sum = 0, shouldDouble = !1;
+  for (let index = value.length - 1;index >= 0; index--) {
+    let transformed = Number(value[index]);
+    if (shouldDouble) {
+      transformed *= 2;
+      if (transformed > 9)
+        transformed -= 9;
+    }
+    sum += transformed;
+    shouldDouble = !shouldDouble;
+  }
+  return sum % 10 === 0;
+}
+function looksLikePaymentCardNumber(value) {
+  const digitsOnly = value.replaceAll(/[\s-]/g, "");
+  return /^\d{13,19}$/.test(digitsOnly) && passesLuhnCheck(digitsOnly);
+}
+function sanitizeDebugString(value) {
+  const trimmed = value.trim();
+  if (/^(?:Bearer|Basic)\s+\S+/i.test(trimmed))
+    return REDACTED_VALUE;
+  if (looksLikeJsonWebToken(trimmed) || looksLikePaymentCardNumber(trimmed))
+    return REDACTED_VALUE;
+  return value;
+}
+export function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function unsupportedObject() {
+  return { supported: !1 };
+}
+function supportedObject(value) {
+  return { supported: !0, value };
+}
+function isPlainObject(value) {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function sanitizeMap(value, seen) {
+  const result = {};
+  for (const [key, entryValue] of value) {
+    const normalizedKey = String(key);
+    result[normalizedKey] = isSensitiveKey(normalizedKey) ? REDACTED_VALUE : sanitizeDebugValue(entryValue, seen);
+  }
+  return result;
+}
+function sanitizePlainObject(value, seen) {
+  const result = {};
+  for (const [key, entryValue] of Object.entries(value))
+    result[key] = isSensitiveKey(key) ? REDACTED_VALUE : sanitizeDebugValue(entryValue, seen);
+  return result;
+}
+const objectSanitizers = [
+  (value) => value instanceof Date ? supportedObject(value.toISOString()) : unsupportedObject(),
+  (value) => value instanceof Error ? supportedObject({ name: value.name, message: sanitizeDebugString(value.message) }) : unsupportedObject(),
+  (value) => value instanceof Uint8Array ? supportedObject(`[Uint8Array(${value.byteLength})]`) : unsupportedObject(),
+  (value, seen) => Array.isArray(value) ? supportedObject(value.map((entry) => sanitizeDebugValue(entry, seen))) : unsupportedObject(),
+  (value, seen) => value instanceof Set ? supportedObject([...value].map((entry) => sanitizeDebugValue(entry, seen))) : unsupportedObject(),
+  (value, seen) => value instanceof Map ? supportedObject(sanitizeMap(value, seen)) : unsupportedObject(),
+  (value, seen) => isPlainObject(value) ? supportedObject(sanitizePlainObject(value, seen)) : unsupportedObject()
+];
+function sanitizeObject(value, seen) {
+  if (seen.has(value))
+    return CIRCULAR_REFERENCE_VALUE;
+  seen.add(value);
+  try {
+    for (const sanitizer of objectSanitizers) {
+      const sanitized = sanitizer(value, seen);
+      if (sanitized.supported)
+        return sanitized.value;
+    }
+    return Object.prototype.toString.call(value);
+  } finally {
+    seen.delete(value);
+  }
+}
+function sanitizeDebugValue(value, seen) {
+  if (typeof value === "string")
+    return sanitizeDebugString(value);
+  if (value === null || value === void 0 || typeof value === "boolean" || typeof value === "number")
+    return value;
+  if (typeof value === "bigint" || typeof value === "symbol")
+    return String(value);
+  if (typeof value === "function")
+    return `[Function ${value.name || "anonymous"}]`;
+  return sanitizeObject(value, seen);
+}
+export function sanitizeDebugValueForDisplay(value) {
+  return sanitizeDebugValue(value, new WeakSet);
+}
+export function safeDebugStringify(value, indentation) {
+  if (value === void 0)
+    return "undefined";
+  const sanitized = sanitizeDebugValueForDisplay(value);
+  if (typeof sanitized === "string")
+    return JSON.stringify(sanitized);
+  try {
+    return JSON.stringify(sanitized, null, indentation) ?? Object.prototype.toString.call(sanitized);
+  } catch {
+    return UNSERIALIZABLE_VALUE;
+  }
+}