@lostgradient/weft 0.2.0

package/dist/core/codec/index.d.ts

@@ -0,0 +1,3 @@
+export { decode, encode } from './api.ts';
+export { validateCloneable } from './validation.ts';
+export type { CloneValidationError, CloneValidationResult } from './validation.ts';

package/dist/core/codec/index.js

@@ -0,0 +1,2 @@
+export { decode, encode } from "./api.js";
+export { validateCloneable } from "./validation.js";

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

@@ -0,0 +1,28 @@
+export interface CloneValidationError {
+    path: string;
+    value: unknown;
+    reason: string;
+    suggestion: string;
+}
+export interface CloneValidationResult {
+    valid: boolean;
+    errors: CloneValidationError[];
+}
+/**
+ * Validate that a value is cloneable (structuredClone compatible).
+ * Returns errors for non-cloneable values. Reports ALL errors, not just the first.
+ *
+ * @example
+ * ```ts
+ * import { validateCloneable } from '@lostgradient/weft';
+ *
+ * const safe = validateCloneable({ name: 'Alice', scores: [1, 2, 3] });
+ * console.log(safe.valid);   // true
+ * console.log(safe.errors);  // []
+ *
+ * const unsafe = validateCloneable({ fn: () => 42 });
+ * console.log(unsafe.valid);           // false
+ * console.log(unsafe.errors[0]?.path); // 'fn'
+ * ```
+ */
+export declare function validateCloneable(value: unknown, path?: string): CloneValidationResult;

package/dist/core/codec/validation.js

@@ -0,0 +1,139 @@
+export function validateCloneable(value, path = "") {
+  const errors = [];
+  walkValue(value, path, errors, new Set);
+  return { valid: errors.length === 0, errors };
+}
+function isClassInstanceWithMethods(value) {
+  const prototype = Object.getPrototypeOf(value);
+  return hasCustomPrototype(prototype) && !isSupportedStructuredCloneType(value) && hasPrototypeMethods(prototype);
+}
+function hasCustomPrototype(prototype) {
+  return prototype !== Object.prototype && prototype !== null;
+}
+function isSupportedStructuredCloneType(value) {
+  return Array.isArray(value) || value instanceof Date || value instanceof RegExp || value instanceof Map || value instanceof Set || value instanceof Error || value instanceof Uint8Array || value instanceof ArrayBuffer;
+}
+function hasPrototypeMethods(prototype) {
+  if (typeof prototype !== "object" || prototype === null)
+    return !1;
+  return Object.getOwnPropertyNames(prototype).some((name) => {
+    if (name === "constructor")
+      return !1;
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+    return descriptor !== void 0 && typeof descriptor.value === "function";
+  });
+}
+function pushCloneValidationError(errors, path, value, failure) {
+  errors.push({
+    path,
+    value,
+    reason: failure.reason,
+    suggestion: failure.suggestion
+  });
+}
+function getPrimitiveCloneValidationFailure(value) {
+  if (typeof value === "function")
+    return {
+      reason: "Functions cannot be serialized.",
+      suggestion: "Move this into ctx.run() or reconstruct it on resume."
+    };
+  if (typeof value === "symbol")
+    return {
+      reason: "Symbols cannot be serialized.",
+      suggestion: "Use a string identifier instead of a Symbol."
+    };
+  return null;
+}
+function getObjectCloneValidationFailure(value, visited) {
+  if (value instanceof WeakRef)
+    return {
+      reason: "WeakRef cannot be serialized.",
+      suggestion: "Store the referenced value directly instead of using a WeakRef."
+    };
+  if (value instanceof WeakMap)
+    return {
+      reason: "WeakMap cannot be serialized.",
+      suggestion: "Use a Map instead of a WeakMap."
+    };
+  if (value instanceof WeakSet)
+    return {
+      reason: "WeakSet cannot be serialized.",
+      suggestion: "Use a Set instead of a WeakSet."
+    };
+  if (visited.has(value))
+    return {
+      reason: "Circular reference detected.",
+      suggestion: "Remove the circular reference or restructure the data."
+    };
+  if (isClassInstanceWithMethods(value))
+    return {
+      reason: "Class instances with methods cannot be serialized.",
+      suggestion: "Store only the data and reconstruct the instance."
+    };
+  return null;
+}
+function isSerializableLeafValue(value) {
+  return value instanceof Date || value instanceof RegExp || value instanceof Error || value instanceof Uint8Array || value instanceof ArrayBuffer;
+}
+function walkMapValues(value, path, errors, visited) {
+  for (const [key, mapValue] of value) {
+    const keyString = String(key);
+    walkValue(mapValue, path ? `${path}.${keyString}` : keyString, errors, visited);
+  }
+}
+function walkSetValues(value, path, errors, visited) {
+  let index = 0;
+  for (const setValue of value) {
+    const elementPath = path ? `${path}[${index}]` : `[${index}]`;
+    walkValue(setValue, elementPath, errors, visited);
+    index++;
+  }
+}
+function walkArrayValues(value, path, errors, visited) {
+  for (let index = 0;index < value.length; index++) {
+    const elementPath = path ? `${path}[${index}]` : `[${index}]`;
+    walkValue(value[index], elementPath, errors, visited);
+  }
+}
+function walkRecordValues(value, path, errors, visited) {
+  for (const key of Object.keys(value)) {
+    const propertyPath = path ? `${path}.${key}` : key;
+    walkValue(value[key], propertyPath, errors, visited);
+  }
+}
+function walkValue(value, path, errors, visited) {
+  if (value === null || value === void 0)
+    return;
+  const primitiveFailure = getPrimitiveCloneValidationFailure(value);
+  if (primitiveFailure) {
+    pushCloneValidationError(errors, path, value, primitiveFailure);
+    return;
+  }
+  if (typeof value !== "object")
+    return;
+  const objectFailure = getObjectCloneValidationFailure(value, visited);
+  if (objectFailure) {
+    pushCloneValidationError(errors, path, value, objectFailure);
+    return;
+  }
+  visited.add(value);
+  try {
+    if (isSerializableLeafValue(value))
+      return;
+    if (value instanceof Map) {
+      walkMapValues(value, path, errors, visited);
+      return;
+    }
+    if (value instanceof Set) {
+      walkSetValues(value, path, errors, visited);
+      return;
+    }
+    if (Array.isArray(value)) {
+      walkArrayValues(value, path, errors, visited);
+      return;
+    }
+    walkRecordValues(value, path, errors, visited);
+  } finally {
+    visited.delete(value);
+  }
+}

package/dist/core/codec-helpers.d.ts

@@ -0,0 +1,8 @@
+/** Coerce a decoded MessagePack value to an object record for extension decoding. */
+export declare function coerceCodecRecord(value: unknown): Record<string, unknown>;
+/** Coerce a decoded MessagePack value to an array for extension decoding. */
+export declare function coerceCodecArray(value: unknown): unknown[];
+/** Encode a Date extension payload as float64 milliseconds since epoch. */
+export declare function encodeCodecDate(value: unknown): Uint8Array | null;
+/** Decode a Date extension payload from float64 milliseconds since epoch. */
+export declare function decodeCodecDate(data: Uint8Array): Date;

package/dist/core/codec-helpers.js

@@ -0,0 +1,19 @@
+export function coerceCodecRecord(value) {
+  if (typeof value === "object" && value !== null && !Array.isArray(value))
+    return value;
+  return {};
+}
+export function coerceCodecArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+export function encodeCodecDate(value) {
+  if (!(value instanceof Date))
+    return null;
+  const buffer = new ArrayBuffer(8);
+  new DataView(buffer).setFloat64(0, value.getTime());
+  return new Uint8Array(buffer);
+}
+export function decodeCodecDate(data) {
+  const milliseconds = new DataView(data.buffer, data.byteOffset, data.byteLength).getFloat64(0);
+  return new Date(milliseconds);
+}

package/dist/core/codec.d.ts

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

package/dist/core/codec.js

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

package/dist/core/compression.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Payload compression utilities for transparent gzip/brotli compression
+ * at the storage layer. Uses a 2-byte header (magic byte `0xC1` + algorithm
+ * byte) for format detection and cross-algorithm reads.
+ *
+ * @module core/compression
+ */
+/**
+ * Identifies the compression algorithm applied to storage payloads.
+ * `'gzip'` and `'brotli'` compress before storage; `'none'` disables
+ * compression. Pass to {@link EngineOptions.compression} or to
+ * {@link createCompressor}.
+ *
+ * @example
+ * ```ts
+ * import { createCompressor, type CompressionAlgorithm } from '@lostgradient/weft';
+ *
+ * const algorithm: CompressionAlgorithm = 'brotli';
+ * const compressor = createCompressor(algorithm);
+ * const data = new TextEncoder().encode('payload'.repeat(100));
+ * const compressed = compressor.compress(data);
+ * console.log(compressed instanceof Uint8Array); // true
+ * ```
+ */
+export type CompressionAlgorithm = 'gzip' | 'brotli' | 'none';
+/**
+ * Configuration for storage-layer compression. Pass as
+ * {@link EngineOptions.compression} to enable payload compression on
+ * checkpoints and activity results. `threshold` prevents compression of
+ * small payloads (default 4 096 bytes); `algorithm` picks the codec.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type CompressionOptions } from '@lostgradient/weft';
+ *
+ * const compression: CompressionOptions = {
+ *   algorithm: 'brotli',
+ *   threshold: 8_192,
+ * };
+ * const engine = new Engine({ compression });
+ * void engine;
+ * ```
+ */
+export type CompressionOptions = {
+    /** Minimum size in bytes before compression kicks in. Default: 4096. */
+    threshold?: number;
+    /** Algorithm to use. Default: 'gzip'. */
+    algorithm?: CompressionAlgorithm;
+};
+/**
+ * A compression implementation returned by {@link createCompressor} or
+ * {@link createBunCompressor}. The `compress` method accepts raw bytes
+ * and returns compressed bytes (or a promise). Provide a custom
+ * `Compressor` if you need to swap in a different algorithm.
+ *
+ * @example
+ * ```ts
+ * import { createCompressor, type Compressor } from '@lostgradient/weft';
+ *
+ * const compressor: Compressor = createCompressor('gzip');
+ * const payload = new TextEncoder().encode('hello'.repeat(200));
+ * const compressed = await compressor.compress(payload);
+ * console.log(compressor.algorithm);            // 'gzip'
+ * console.log(compressed.byteLength < payload.byteLength); // true
+ * ```
+ */
+export type Compressor = {
+    compress(data: Uint8Array): Uint8Array | Promise<Uint8Array>;
+    readonly algorithm: CompressionAlgorithm;
+};
+/**
+ * Create a compressor backed by the portable runtime layer.
+ *
+ * - `gzip`: uses Bun's native gzip when available, otherwise `node:zlib`
+ * - `brotli`: uses `node:zlib` brotli (available in both Bun and Node)
+ * - `none`: pass-through (no compression)
+ *
+ * @example
+ * ```ts
+ * import { createBunCompressor } from '@lostgradient/weft';
+ *
+ * const compressor = createBunCompressor('gzip');
+ * const data = new TextEncoder().encode('hello world'.repeat(100));
+ * const compressed = await compressor.compress(data);
+ * console.log(compressed.byteLength < data.byteLength); // true
+ * ```
+ */
+export declare function createBunCompressor(algorithm: CompressionAlgorithm): Compressor;
+/**
+ * Create a compressor. Preferred portable factory — delegates to the runtime
+ * abstraction layer for gzip and brotli implementations.
+ *
+ * @example
+ * ```ts
+ * import { createCompressor } from '@lostgradient/weft';
+ *
+ * const gzip = createCompressor('gzip');
+ * const brotli = createCompressor('brotli');
+ * const none = createCompressor('none');
+ *
+ * const payload = new TextEncoder().encode('workflow state'.repeat(50));
+ * const compressed = gzip.compress(payload);
+ * console.log(compressed instanceof Uint8Array); // true
+ * ```
+ */
+export declare function createCompressor(algorithm: CompressionAlgorithm): Compressor;
+/**
+ * Compress a payload, prepending a 2-byte header: magic byte (`0xC1`) +
+ * algorithm byte.
+ *
+ * If the data is below the threshold or the algorithm is `'none'`, the payload
+ * is stored with a `[0xC1, 0x00]` header and no compression is applied.
+ */
+export declare function compressPayload(data: Uint8Array, compressor: Compressor, threshold: number): Promise<Uint8Array>;
+/**
+ * Decompress a payload by reading the 2-byte header (magic + algorithm).
+ *
+ * - `[0xC1, 0x00]` → uncompressed, return the rest as-is
+ * - `[0xC1, 0x01]` → gzip-compressed, decompress
+ * - `[0xC1, 0x02]` → brotli-compressed, decompress
+ *
+ * Empty payloads are valid only when framed as `[0xC1, 0x00]`. Unframed empty
+ * input is rejected because it cannot prove which storage format produced it.
+ */
+export declare function decompressPayload(data: Uint8Array): Promise<Uint8Array>;
+/** Resolve partial compression options into a fully specified configuration. */
+export declare function resolveCompressionOptions(options?: CompressionOptions): Required<CompressionOptions>;

package/dist/core/compression.js

@@ -0,0 +1,88 @@
+import { gunzipSync, gzipSync, tryLoadNodeZlib } from "../runtime/portable.js";
+function getBrotliZlib() {
+  const zlib = tryLoadNodeZlib();
+  if (!zlib)
+    throw Error("Brotli compression requires Bun or Node 22.5+ with process.getBuiltinModule support. Use gzip compression for browser/edge runtimes.");
+  return zlib;
+}
+function brotliCompressSync(data) {
+  return new Uint8Array(getBrotliZlib().brotliCompressSync(data));
+}
+function brotliDecompressSync(data) {
+  return new Uint8Array(getBrotliZlib().brotliDecompressSync(data));
+}
+const MAGIC_BYTE = 193, ALGORITHM_UNCOMPRESSED = 0, ALGORITHM_GZIP = 1, ALGORITHM_BROTLI = 2, HEADER_SIZE = 2;
+export function createBunCompressor(algorithm) {
+  return createCompressor(algorithm);
+}
+export function createCompressor(algorithm) {
+  switch (algorithm) {
+    case "gzip":
+      return {
+        algorithm: "gzip",
+        compress(data) {
+          return gzipSync(data);
+        }
+      };
+    case "brotli":
+      return {
+        algorithm: "brotli",
+        compress(data) {
+          return brotliCompressSync(data);
+        }
+      };
+    case "none":
+      return {
+        algorithm: "none",
+        compress(data) {
+          return data;
+        }
+      };
+  }
+}
+export async function compressPayload(data, compressor, threshold) {
+  if (data.length < threshold || compressor.algorithm === "none") {
+    const result = new Uint8Array(data.length + HEADER_SIZE);
+    result[0] = MAGIC_BYTE;
+    result[1] = ALGORITHM_UNCOMPRESSED;
+    result.set(data, HEADER_SIZE);
+    return result;
+  }
+  const compressed = await compressor.compress(data);
+  if (compressed.length + HEADER_SIZE >= data.length + HEADER_SIZE) {
+    const result = new Uint8Array(data.length + HEADER_SIZE);
+    result[0] = MAGIC_BYTE;
+    result[1] = ALGORITHM_UNCOMPRESSED;
+    result.set(data, HEADER_SIZE);
+    return result;
+  }
+  const algorithmByte = compressor.algorithm === "gzip" ? ALGORITHM_GZIP : ALGORITHM_BROTLI, result = new Uint8Array(compressed.length + HEADER_SIZE);
+  result[0] = MAGIC_BYTE;
+  result[1] = algorithmByte;
+  result.set(compressed, HEADER_SIZE);
+  return result;
+}
+export async function decompressPayload(data) {
+  if (data.length < HEADER_SIZE)
+    throw Error("Compression payload missing 2-byte header.");
+  if (data[0] !== MAGIC_BYTE)
+    throw Error("Compression payload missing magic byte 0xC1.");
+  const algorithm = data[1], body = data.slice(HEADER_SIZE);
+  switch (algorithm) {
+    case ALGORITHM_UNCOMPRESSED:
+      return body;
+    case ALGORITHM_GZIP:
+      return gunzipSync(body);
+    case ALGORITHM_BROTLI:
+      return brotliDecompressSync(body);
+    default:
+      throw Error(`Compression payload uses unsupported algorithm byte 0x${algorithm.toString(16).padStart(2, "0")}.`);
+  }
+}
+const DEFAULT_THRESHOLD = 4096, DEFAULT_ALGORITHM = "gzip";
+export function resolveCompressionOptions(options) {
+  return {
+    threshold: options?.threshold ?? DEFAULT_THRESHOLD,
+    algorithm: options?.algorithm ?? DEFAULT_ALGORITHM
+  };
+}

package/dist/core/concurrency-lock-record.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The durable lock record and the pure reducers that mutate it. These are the
+ * deterministic core of the {@link DurableSemaphore}/{@link DurableMutex}
+ * primitives in `./concurrency.ts`: every acquire, release, and renew is one
+ * pure function over a {@link LockRecord}, so the algorithm is trivially
+ * replay-safe and unit-testable in isolation from any storage flavour.
+ *
+ * @module core/concurrency-lock-record
+ */
+/**
+ * One permit currently held against a {@link DurableSemaphore}. `leaseExpiresAt`
+ * is the deterministic timestamp (milliseconds since epoch) after which the
+ * permit may be reclaimed by another contender, preventing a crashed holder
+ * from deadlocking the lock.
+ *
+ * @example
+ * ```ts
+ * import type { LockHolder } from '@lostgradient/weft';
+ *
+ * const holder: LockHolder = { holderId: 'workflow-a', leaseExpiresAt: 1_717_000_030_000 };
+ * void holder;
+ * ```
+ */
+export interface LockHolder {
+    /** Caller-chosen identifier for the holder (typically `ctx.workflowId`). */
+    holderId: string;
+    /** Timestamp (ms since epoch) after which this lease may be reclaimed. */
+    leaseExpiresAt: number;
+}
+/**
+ * The durable record persisted in a single CAS state slot. `holders` are the
+ * permits currently granted (length never exceeds the semaphore's permit
+ * count); `waiters` is the FIFO queue of holder ids waiting for a permit.
+ *
+ * @example
+ * ```ts
+ * import type { LockRecord } from '@lostgradient/weft';
+ *
+ * const record: LockRecord = {
+ *   holders: [{ holderId: 'workflow-a', leaseExpiresAt: 1_717_000_030_000 }],
+ *   waiters: ['workflow-b'],
+ * };
+ * void record;
+ * ```
+ */
+export interface LockRecord {
+    holders: LockHolder[];
+    waiters: string[];
+}
+/**
+ * Outcome of a single non-blocking acquire attempt.
+ *
+ * @example
+ * ```ts
+ * import type { AcquireAttempt } from '@lostgradient/weft';
+ *
+ * const attempt: AcquireAttempt = { acquired: false, position: 0 };
+ * if (!attempt.acquired) {
+ *   // attempt.position is the caller's place in the FIFO queue.
+ * }
+ * ```
+ */
+export interface AcquireAttempt {
+    /** Whether the caller now holds a permit. */
+    acquired: boolean;
+    /**
+     * Zero-based position in the FIFO waiter queue when `acquired` is `false`.
+     * `0` means the caller is next in line. `-1` when `acquired` is `true`.
+     */
+    position: number;
+}
+/**
+ * A fresh empty {@link LockRecord}. Pass this as the `initial` option when
+ * constructing the CAS state handle so the first reader sees an empty lock
+ * rather than `undefined`.
+ *
+ * @example
+ * ```ts
+ * import { initialLockRecord, AtomicState } from '@lostgradient/weft';
+ * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
+ *
+ * const slot = new AtomicState(new MemoryStorage(), 'state:workflow-scope:default:lock', {
+ *   initial: initialLockRecord(),
+ * });
+ * void slot;
+ * ```
+ */
+export declare function initialLockRecord(): LockRecord;
+/**
+ * Pure reducer for one acquire attempt. Returns the next record alongside
+ * whether the caller acquired a permit and its queue position. Deterministic
+ * in its inputs so it replays identically.
+ */
+export declare function reduceAcquire(current: LockRecord | undefined, options: {
+    holderId: string;
+    now: number;
+    leaseMs: number;
+    permits: number;
+}): {
+    record: LockRecord;
+    attempt: AcquireAttempt;
+};
+/**
+ * Pure reducer for releasing a permit. Removes the holder (and any stale waiter
+ * entry) and reclaims expired leases so the record stays clean.
+ */
+export declare function reduceRelease(current: LockRecord | undefined, options: {
+    holderId: string;
+    now: number;
+}): LockRecord;
+/**
+ * Pure reducer for renewing a held lease. Extends the holder's
+ * `leaseExpiresAt`; a no-op if the caller is not currently a holder.
+ */
+export declare function reduceRenew(current: LockRecord | undefined, options: {
+    holderId: string;
+    now: number;
+    leaseMs: number;
+}): {
+    record: LockRecord;
+    renewed: boolean;
+};

package/dist/core/concurrency-lock-record.js

@@ -0,0 +1,53 @@
+export function initialLockRecord() {
+  return { holders: [], waiters: [] };
+}
+function normalizeRecord(record) {
+  if (record === void 0)
+    return initialLockRecord();
+  return {
+    holders: Array.isArray(record.holders) ? record.holders : [],
+    waiters: Array.isArray(record.waiters) ? record.waiters : []
+  };
+}
+function dropExpiredHolders(holders, now) {
+  return holders.filter((holder) => holder.leaseExpiresAt > now);
+}
+export function reduceAcquire(current, options) {
+  const { holderId, now, leaseMs, permits } = options, record = normalizeRecord(current), liveHolders = dropExpiredHolders(record.holders, now), existingIndex = liveHolders.findIndex((holder) => holder.holderId === holderId);
+  if (existingIndex !== -1)
+    return {
+      record: { holders: liveHolders.map((holder, index) => index === existingIndex ? { holderId, leaseExpiresAt: now + leaseMs } : holder), waiters: record.waiters.filter((id) => id !== holderId) },
+      attempt: { acquired: !0, position: -1 }
+    };
+  const waiters = record.waiters.includes(holderId) ? [...record.waiters] : [...record.waiters, holderId], freePermits = permits - liveHolders.length, isNextInLine = waiters[0] === holderId;
+  if (freePermits > 0 && isNextInLine)
+    return {
+      record: {
+        holders: [...liveHolders, { holderId, leaseExpiresAt: now + leaseMs }],
+        waiters: waiters.slice(1)
+      },
+      attempt: { acquired: !0, position: -1 }
+    };
+  return {
+    record: { holders: liveHolders, waiters },
+    attempt: { acquired: !1, position: waiters.indexOf(holderId) }
+  };
+}
+export function reduceRelease(current, options) {
+  const { holderId, now } = options, record = normalizeRecord(current);
+  return {
+    holders: dropExpiredHolders(record.holders, now).filter((holder) => holder.holderId !== holderId),
+    waiters: record.waiters.filter((id) => id !== holderId)
+  };
+}
+export function reduceRenew(current, options) {
+  const { holderId, now, leaseMs } = options, record = normalizeRecord(current), liveHolders = dropExpiredHolders(record.holders, now);
+  let renewed = !1;
+  return { record: { holders: liveHolders.map((holder) => {
+    if (holder.holderId === holderId) {
+      renewed = !0;
+      return { holderId, leaseExpiresAt: now + leaseMs };
+    }
+    return holder;
+  }), waiters: record.waiters }, renewed };
+}