@lostgradient/weft 0.2.0

package/dist/storage/interface.d.ts

@@ -0,0 +1,340 @@
+import { type StorageCapabilities } from './capabilities.ts';
+import type { DeleteRangeOptions } from './delete-range.ts';
+export { assertDurableStorageForRecovery, requireStorageCapability } from './capabilities.ts';
+export type { GatedStorageCapabilityKey, StorageCapabilities } from './capabilities.ts';
+export { DEFAULT_SCOPE } from './default-scope.ts';
+export { WEFT_RESERVED_KEY_PREFIXES } from './key-prefixes.ts';
+/**
+ * A single KV operation in a batch.
+ *
+ * Either a put (write `value` at `key`) or a delete (remove `key`). The `type`
+ * discriminant selects the variant; delete operations carry no value.
+ */
+export type BatchOperation = {
+    type: 'put';
+    key: string;
+    value: Uint8Array;
+} | {
+    type: 'delete';
+    key: string;
+};
+/**
+ * A key/value precondition for {@link Storage.conditionalBatch}.
+ *
+ * The batch commits only when every listed key currently matches the expected
+ * value. Use `null` to require that the key is absent.
+ */
+export interface ConditionalBatchCondition {
+    key: string;
+    expectedValue: Uint8Array | null;
+}
+/**
+ * Options for range scans.
+ *
+ * @example
+ * ```ts
+ * import { MemoryStorage, type ScanOptions } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * const options: ScanOptions = { limit: 10, reverse: true };
+ * for await (const [key, value] of storage.scan('wf:', options)) {
+ *   console.log(key);
+ * }
+ * ```
+ */
+export interface ScanOptions {
+    limit?: number;
+    reverse?: boolean;
+    gt?: string;
+    lt?: string;
+    gte?: string;
+    lte?: string;
+}
+/**
+ * KV-oriented storage interface. All storage adapters implement this.
+ *
+ * Required methods are `get`, `put`, `delete`, `scan`, and `batch`. Optional
+ * fast paths are `conditionalBatch`, `has`, `deletePrefix`, `deleteRange`,
+ * `keys`, `count`, `scoped`, and `query`. Adapters that omit optional methods
+ * get generic fallbacks via `storageHas`, `storageKeys`, `storageCount`,
+ * `storageDeletePrefix`, and `storageConditionalBatch` (all from this module),
+ * plus `storageDeleteRange` (exported from `@lostgradient/weft` / `@lostgradient/weft/storage`, defined in
+ * `storage/delete-range.ts`). Callers should use those wrappers rather than
+ * calling optional methods directly.
+ *
+ * @example
+ * ```ts
+ * import { MemoryStorage } from '@lostgradient/weft';
+ * import type { Storage } from '@lostgradient/weft/storage/interface';
+ *
+ * await using storage: Storage = new MemoryStorage();
+ * const encoded = new TextEncoder().encode('hello');
+ * await storage.put('my-key', encoded);
+ * const value = await storage.get('my-key');
+ * console.log(new TextDecoder().decode(value!)); // 'hello'
+ * ```
+ */
+export interface Storage extends Disposable {
+    /**
+     * Self-report the backend's consistency and feature guarantees. Required on
+     * every adapter so the engine and feature gates can act on an honest,
+     * declarative profile rather than duck-typing optional methods. See
+     * {@link StorageCapabilities} for the contract each field promises and which
+     * fields are runtime-gated versus trusted.
+     */
+    capabilities(): StorageCapabilities;
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    scan(prefix: string, options?: ScanOptions): AsyncIterable<[string, Uint8Array]>;
+    batch(operations: BatchOperation[]): Promise<void>;
+    conditionalBatch?(conditions: ConditionalBatchCondition[], operations: BatchOperation[]): Promise<boolean>;
+    has?(key: string): Promise<boolean>;
+    deletePrefix?(prefix: string): Promise<number>;
+    deleteRange?(prefix: string, options: DeleteRangeOptions): Promise<number>;
+    keys?(prefix: string, options?: ScanOptions): AsyncIterable<string>;
+    count?(prefix: string): Promise<number>;
+    scoped?(prefix: string): Storage;
+    /** Optional SQL passthrough for dashboard/debugging. */
+    query?<T>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+/**
+ * Resolve the exclusive upper bound for a lexicographic prefix scan.
+ *
+ * @example
+ * ```ts
+ * import { resolvePrefixRangeEnd } from '@lostgradient/weft/storage/interface';
+ *
+ * const end = resolvePrefixRangeEnd('wf:');
+ * console.log(end); // 'wf;'
+ * // Use as an exclusive upper bound in range queries
+ * ```
+ */
+export declare function resolvePrefixRangeEnd(prefix: string): string;
+/**
+ * Apply gt/gte/lt/lte scan bounds to a single key.
+ *
+ * @example
+ * ```ts
+ * import { matchesScanOptions } from '@lostgradient/weft/storage/interface';
+ *
+ * console.log(matchesScanOptions('wf:b', { gt: 'wf:a', lt: 'wf:c' })); // true
+ * console.log(matchesScanOptions('wf:a', { gt: 'wf:a' }));              // false
+ * ```
+ */
+export declare function matchesScanOptions(key: string, options?: ScanOptions): boolean;
+/**
+ * Compare two storage values for byte-for-byte equality.
+ *
+ * @example
+ * ```ts
+ * import { storageValuesEqual } from '@lostgradient/weft';
+ *
+ * const a = new Uint8Array([1, 2, 3]);
+ * const b = new Uint8Array([1, 2, 3]);
+ * console.log(storageValuesEqual(a, b)); // true
+ * console.log(storageValuesEqual(a, null)); // false
+ * ```
+ */
+export declare function storageValuesEqual(left: Uint8Array | null, right: Uint8Array | null): boolean;
+/**
+ * Check key existence using the adapter method when available or a core fallback otherwise.
+ *
+ * @example
+ * ```ts
+ * import { MemoryStorage } from '@lostgradient/weft';
+ * import { storageHas } from '@lostgradient/weft/storage/interface';
+ *
+ * await using storage = new MemoryStorage();
+ * await storage.put('my-key', new Uint8Array([1]));
+ * console.log(await storageHas(storage, 'my-key'));    // true
+ * console.log(await storageHas(storage, 'other-key')); // false
+ * ```
+ */
+export declare function storageHas(storage: Storage, key: string): Promise<boolean>;
+/**
+ * Iterate keys only, using the adapter shortcut when available or `scan()` as a fallback.
+ *
+ * @example
+ * ```ts
+ * import { MemoryStorage } from '@lostgradient/weft';
+ * import { storageKeys } from '@lostgradient/weft/storage/interface';
+ *
+ * await using storage = new MemoryStorage();
+ * for await (const key of storageKeys(storage, 'wf:')) {
+ *   console.log(key); // 'wf:abc'
+ * }
+ * ```
+ */
+export declare function storageKeys(storage: Storage, prefix: string, options?: ScanOptions): AsyncIterable<string>;
+/**
+ * Count keys for a prefix using the adapter method when available or iteration otherwise.
+ *
+ * @example
+ * ```ts
+ * import { MemoryStorage } from '@lostgradient/weft';
+ * import { storageCount } from '@lostgradient/weft/storage/interface';
+ *
+ * await using storage = new MemoryStorage();
+ * await storage.put('wf:1', new Uint8Array([1]));
+ * await storage.put('wf:2', new Uint8Array([2]));
+ * console.log(await storageCount(storage, 'wf:')); // 2
+ * ```
+ */
+export declare function storageCount(storage: Storage, prefix: string): Promise<number>;
+/**
+ * Delete a whole prefix using the adapter method when available or a batched fallback otherwise.
+ *
+ * @example
+ * ```ts
+ * import { MemoryStorage } from '@lostgradient/weft';
+ * import { storageDeletePrefix } from '@lostgradient/weft/storage/interface';
+ *
+ * await using storage = new MemoryStorage();
+ * await storage.put('wf:a', new Uint8Array([1]));
+ * await storage.put('wf:b', new Uint8Array([2]));
+ * const deleted = await storageDeletePrefix(storage, 'wf:');
+ * console.log(deleted); // 2
+ * ```
+ */
+export declare function storageDeletePrefix(storage: Storage, prefix: string): Promise<number>;
+/**
+ * Run a conditional batch or throw when the backend does not support it.
+ *
+ * Built-in Memory, BunSQLite, NodeSQLite, LMDB, Turso, and IndexedDB backends
+ * provide `conditionalBatch`; custom adapters may omit it.
+ *
+ * @throws {Error} This storage backend does not support conditionalBatch(), which is required for this operation.
+ *
+ * @example
+ * ```ts
+ * import { MemoryStorage } from '@lostgradient/weft';
+ * import { storageConditionalBatch } from '@lostgradient/weft/storage/interface';
+ *
+ * await using storage = new MemoryStorage();
+ * const key = 'my-key';
+ * // Commit only if key is absent
+ * const applied = await storageConditionalBatch(
+ *   storage,
+ *   [{ key, expectedValue: null }],
+ *   [{ type: 'put', key, value: new Uint8Array([1]) }],
+ * );
+ * console.log(applied); // true
+ * ```
+ */
+export declare function storageConditionalBatch(storage: Storage, conditions: ConditionalBatchCondition[], operations: BatchOperation[]): Promise<boolean>;
+/**
+ * Encode an untrusted string so it is safe to embed in a colon-delimited storage key.
+ *
+ * @example
+ * ```ts
+ * import { encodeStorageKeyComponent } from '@lostgradient/weft/storage/interface';
+ *
+ * const safe = encodeStorageKeyComponent('user:123/profile');
+ * console.log(safe); // 'user%3A123%2Fprofile'
+ * ```
+ */
+export declare function encodeStorageKeyComponent(value: string): string;
+/**
+ * Decode a storage-key component produced by {@link encodeStorageKeyComponent}.
+ * Throws when `value` is malformed percent-encoded text. Callers handling
+ * untrusted input should prefer {@link tryDecodeStorageKeyComponent}.
+ *
+ * @throws {URIError} When `value` contains malformed percent-encoded data.
+ *
+ * @example
+ * ```ts
+ * import { encodeStorageKeyComponent, decodeStorageKeyComponent } from '@lostgradient/weft/storage/interface';
+ *
+ * const encoded = encodeStorageKeyComponent('user:123');
+ * const decoded = decodeStorageKeyComponent(encoded);
+ * console.log(decoded); // 'user:123'
+ * ```
+ */
+export declare function decodeStorageKeyComponent(value: string): string;
+/**
+ * Decode a storage-key component produced by {@link encodeStorageKeyComponent}.
+ * Returns `null` when the component is malformed instead of throwing.
+ *
+ * @example
+ * ```ts
+ * import { tryDecodeStorageKeyComponent } from '@lostgradient/weft/storage/interface';
+ *
+ * console.log(tryDecodeStorageKeyComponent('user%3A123')); // 'user:123'
+ * console.log(tryDecodeStorageKeyComponent('%GG'));        // null
+ * ```
+ */
+export declare function tryDecodeStorageKeyComponent(value: string): string | null;
+/**
+ * Key layout constants for hierarchical key encoding. Timestamps are
+ * zero-padded to 16 digits for lexicographic ordering.
+ *
+ * @example
+ * ```ts
+ * import { KEYS } from '@lostgradient/weft/storage/interface';
+ * KEYS.workflow('workflow-id');
+ * ```
+ */
+export declare const KEYS: {
+    readonly workflow: (id: string) => string;
+    readonly checkpoint: (id: string) => string;
+    readonly checkpointHistory: (id: string, step: number) => string;
+    readonly timelinePrefix: (id: string) => string;
+    readonly timeline: (id: string, step: number) => string;
+    readonly schedule: (id: string) => string;
+    readonly scheduleTick: (fireAt: number, id: string) => string;
+    readonly scheduleRun: (workflowId: string) => string;
+    readonly operation: (queue: string, scheduledAt: number, id: string) => string;
+    readonly operationInflight: (id: string) => string;
+    readonly operationQueued: (id: string) => string;
+    readonly operationResolved: (id: string) => string;
+    readonly bulkOperationAuditPrefix: () => string;
+    readonly bulkOperationAudit: (timestamp: number, requestId: string, confirmationToken: string) => string;
+    readonly operationResolvedByTimePrefix: () => string;
+    readonly operationResolvedByTime: (resolvedAt: number, id: string) => string;
+    readonly asyncActivity: (workflowId: string, token: string) => string;
+    readonly activityReconciliationPrefix: (workflowId: string) => string;
+    readonly activityReconciliation: (workflowId: string, activityName: string, idempotencyKeyDigest: string) => string;
+    readonly eventPrefix: (workflowId: string) => string;
+    readonly event: (workflowId: string, sequence: number) => string;
+    readonly eventHead: (workflowId: string) => string;
+    readonly eventWatermark: (workflowId: string) => string;
+    readonly signal: (workflowId: string, name: string, id: string) => string;
+    readonly signalSequence: (workflowId: string) => string;
+    readonly signalAcceptedResponsePrefix: (workflowId: string) => string;
+    readonly signalAcceptedResponse: (workflowId: string, name: string, signalId: string) => string;
+    readonly deadline: (deadline: number, workflowId: string) => string;
+    readonly terminalCleanup: (fireAt: number, timerId: string) => string;
+    readonly delayedStart: (startAt: number, workflowId: string) => string;
+    readonly terminalWorkflowPrefix: () => string;
+    readonly terminalWorkflow: (updatedAt: number, workflowId: string) => string;
+    readonly attribute: (workflowId: string) => string;
+    readonly attributeIndex: (attributeName: string, encodedValue: string, workflowId: string) => string;
+    readonly tagIndex: (tag: string, workflowId: string) => string;
+    readonly updatePrefix: (workflowId: string) => string;
+    readonly update: (workflowId: string, updateId: string) => string;
+    readonly updateResponse: (updateId: string) => string;
+    readonly updateIdempotency: (workflowId: string, key: string) => string;
+    readonly budget: (namespace: string, period: string, date: string) => string;
+    readonly review: (workflowId: string, reviewId: string) => string;
+    readonly workflowHeaders: (workflowId: string) => string;
+    readonly terminalCleanupNeeded: (workflowId: string) => string;
+    readonly offload: (workflowId: string, key: string) => string;
+    readonly archive: (workflowId: string, key: string) => string;
+    readonly stateExecution: (ownerWorkflowId: string, key: string) => string;
+    readonly stateWorkflow: (workflowType: string, key: string) => string;
+    readonly streamChunkPrefix: (workflowId: string, key: string) => string;
+    readonly streamChunk: (workflowId: string, key: string, chunkIndex: number) => string;
+    readonly streamMetadata: (workflowId: string, key: string) => string;
+    readonly budgetCharged: (operationId: string) => string;
+    readonly toolEffect: (workflowId: string, agentId: string, semanticHash: string) => string;
+    readonly workflowVisibilityStatus: (status: string, workflowId: string) => string;
+    readonly workflowVisibilityType: (type: string, workflowId: string) => string;
+    readonly workflowVisibilityCreated: (createdAt: number, workflowId: string) => string;
+    readonly workflowVisibilityUpdated: (updatedAt: number, workflowId: string) => string;
+    readonly workflowVisibilityDeadline: (deadline: number, workflowId: string) => string;
+    readonly workflowVisibilityManifest: (workflowId: string) => string;
+    readonly workflowVisibilityMetaVersion: () => string;
+    readonly workflowVisibilityMetaBuiltAt: () => string;
+    readonly workflowVisibilityMetaCursor: () => string;
+};

package/dist/storage/interface.js

@@ -0,0 +1,2 @@
+// @bun
+var $=Object.defineProperty;var j=(E)=>E;function L(E,_){this[E]=j.bind(null,_)}var H=(E,_)=>{for(var F in _)$(E,F,{get:_[F],enumerable:!0,configurable:!0,set:L.bind(_,F)})};var G=(E,_)=>()=>(E&&(_=E(E=0)),_);function U(E,_,F){if(!E.capabilities()[_])throw Error(`Feature "${F}" requires storage capability "${_}", but this storage backend does not provide it.`)}function z(E){let _=E.capabilities(),F=[];if(_.persistence!=="local")F.push(`persistence must be "local" (got "${_.persistence}")`);if(_.readAfterWrite!=="linearizable")F.push(`readAfterWrite must be "linearizable" (got "${_.readAfterWrite}")`);if(_.scanConsistency!=="snapshot")F.push(`scanConsistency must be "snapshot" (got "${_.scanConsistency}")`);if(!_.atomicBatch)F.push("atomicBatch must be true");if(!_.conditionalBatch)F.push("conditionalBatch must be true");if(F.length>0)throw Error(`Storage is not durable enough for recovery: ${F.join("; ")}.`)}var B="default";async function J(E,_){return await E.get(_)!==null}async function*X(E,_,F){for await(let[Y]of E.scan(_,F))yield Y}async function M(E,_){let F=0;for await(let Y of X(E,_))F++;return F}async function O(E,_){let F=[];for await(let Y of X(E,_))F.push({type:"delete",key:Y});if(F.length===0)return 0;return await E.batch(F),F.length}async function A(E,_,F){let Y=[];for await(let Z of X(E,_,F))Y.push({type:"delete",key:Z});if(Y.length===0)return 0;return await E.batch(Y),Y.length}var Q;var V=G(()=>{Q=["actrec:","archive:","async-act:","attr:","audit:bulk:","blob:","budget:","budget-charged:","ev:","idx:","offload:","op:","review:","schedule:","schedule-due:","schedule-run:","sig:","sigres:","sigseq:","state:","tag:","tool-effect:","upd:","upk:","upr:","wf:","wf-cleanup:","wf-cleanup-needed:","wf-deadline:","wf-delayed:","wf-headers:","wf-idx-","wf-terminal:"]});function K(E){return E.length>0?E.slice(0,-1)+String.fromCharCode(E.charCodeAt(E.length-1)+1):"\xFF"}function S(E,_={}){if(_.gt!==void 0&&E<=_.gt)return!1;if(_.gte!==void 0&&E<_.gte)return!1;if(_.lt!==void 0&&E>=_.lt)return!1;if(_.lte!==void 0&&E>_.lte)return!1;return!0}function C(E,_){if(E===null||_===null)return E===_;if(E.byteLength!==_.byteLength)return!1;for(let F=0;F<E.byteLength;F++)if(E[F]!==_[F])return!1;return!0}async function c(E,_){if(E.has)return E.has(_);return J(E,_)}function I(E,_,F){if(E.keys)return E.keys(_,F);return X(E,_,F)}async function k(E,_){if(E.count)return E.count(_);return M(E,_)}async function y(E,_){if(E.deletePrefix)return E.deletePrefix(_);return O(E,_)}async function m(E,_,F){if(U(E,"conditionalBatch","storageConditionalBatch"),!E.conditionalBatch)throw Error("This storage backend reports conditionalBatch capability but does not implement the conditionalBatch() method.");return E.conditionalBatch(_,F)}function W(E){return encodeURIComponent(E)}function f(E){return decodeURIComponent(E)}function l(E){try{return decodeURIComponent(E)}catch{return null}}var P=(E)=>String(E).padStart(16,"0"),g;var D=G(()=>{V();g={workflow:(E)=>`wf:${W(E)}`,checkpoint:(E)=>`wf:${W(E)}:ckpt`,checkpointHistory:(E,_)=>`wf:${W(E)}:ckpt:${String(_).padStart(10,"0")}`,timelinePrefix:(E)=>`wf:${W(E)}:timeline:`,timeline:(E,_)=>`wf:${W(E)}:timeline:${String(_).padStart(10,"0")}`,schedule:(E)=>`schedule:${W(E)}`,scheduleTick:(E,_)=>`schedule-due:${String(E).padStart(16,"0")}:${W(_)}`,scheduleRun:(E)=>`schedule-run:${W(E)}`,operation:(E,_,F)=>`op:${E}:${P(_)}:${F}`,operationInflight:(E)=>`op:inflight:${E}`,operationQueued:(E)=>`op:queued:${E}`,operationResolved:(E)=>`op:resolved:${E}`,bulkOperationAuditPrefix:()=>"audit:bulk:",bulkOperationAudit:(E,_,F)=>`audit:bulk:${P(E)}:${W(_)}:${W(F)}`,operationResolvedByTimePrefix:()=>"op:resolved-by-time:",operationResolvedByTime:(E,_)=>`op:resolved-by-time:${P(E)}:${W(_)}`,asyncActivity:(E,_)=>`async-act:v1:${W(E)}:${W(_)}`,activityReconciliationPrefix:(E)=>`actrec:v1:${W(E)}:`,activityReconciliation:(E,_,F)=>`actrec:v1:${W(E)}:${W(_)}:${F}`,eventPrefix:(E)=>`ev:${W(E)}:`,event:(E,_)=>`ev:${W(E)}:${String(_).padStart(10,"0")}`,eventHead:(E)=>`ev:${W(E)}:head`,eventWatermark:(E)=>`ev:${W(E)}:watermark`,signal:(E,_,F)=>`sig:${W(E)}:${_}:${W(F)}`,signalSequence:(E)=>`sigseq:v1:${W(E)}`,signalAcceptedResponsePrefix:(E)=>`sigres:v1:${W(E)}:`,signalAcceptedResponse:(E,_,F)=>`sigres:v1:${W(E)}:${W(_)}:${W(F)}`,deadline:(E,_)=>`wf-deadline:${P(E)}:${W(_)}`,terminalCleanup:(E,_)=>`wf-cleanup:${P(E)}:${W(_)}`,delayedStart:(E,_)=>`wf-delayed:${P(E)}:${W(_)}`,terminalWorkflowPrefix:()=>"wf-terminal:",terminalWorkflow:(E,_)=>`wf-terminal:${P(E)}:${W(_)}`,attribute:(E)=>`attr:${W(E)}`,attributeIndex:(E,_,F)=>`idx:${E}:${_}:${W(F)}`,tagIndex:(E,_)=>`tag:${W(E)}:${W(_)}`,updatePrefix:(E)=>`upd:${W(E)}:`,update:(E,_)=>`upd:${W(E)}:${_}`,updateResponse:(E)=>`upr:${E}`,updateIdempotency:(E,_)=>`upk:${W(E)}:${_}`,budget:(E,_,F)=>`budget:${E}:${_}:${F}`,review:(E,_)=>`review:${W(E)}:${_}`,workflowHeaders:(E)=>`wf-headers:${W(E)}`,terminalCleanupNeeded:(E)=>`wf-cleanup-needed:${W(E)}`,offload:(E,_)=>`offload:${W(E)}:${_}`,archive:(E,_)=>`archive:${W(E)}:${_}`,stateExecution:(E,_)=>`state:execution:${W(E)}:${W(_)}`,stateWorkflow:(E,_)=>`state:workflow-scope:${B}:${W(E)}:${W(_)}`,streamChunkPrefix:(E,_)=>`blob:${W(E)}:${_}:chunk:`,streamChunk:(E,_,F)=>`blob:${W(E)}:${_}:chunk:${String(F).padStart(10,"0")}`,streamMetadata:(E,_)=>`blob:${W(E)}:${_}:meta`,budgetCharged:(E)=>`budget-charged:${E}`,toolEffect:(E,_,F)=>`tool-effect:${W(E)}:${_}:${F}`,workflowVisibilityStatus:(E,_)=>`wf-idx-status:${W(E)}:${W(_)}`,workflowVisibilityType:(E,_)=>`wf-idx-type:${W(E)}:${W(_)}`,workflowVisibilityCreated:(E,_)=>`wf-idx-created:${P(E)}:${W(_)}`,workflowVisibilityUpdated:(E,_)=>`wf-idx-updated:${P(E)}:${W(_)}`,workflowVisibilityDeadline:(E,_)=>`wf-idx-deadline:${P(E)}:${W(_)}`,workflowVisibilityManifest:(E)=>`wf-idx-manifest:${W(E)}`,workflowVisibilityMetaVersion:()=>"wf-idx-meta:version",workflowVisibilityMetaBuiltAt:()=>"wf-idx-meta:built-at",workflowVisibilityMetaCursor:()=>"wf-idx-meta:cursor"}});D();export{l as tryDecodeStorageKeyComponent,C as storageValuesEqual,I as storageKeys,c as storageHas,y as storageDeletePrefix,k as storageCount,m as storageConditionalBatch,K as resolvePrefixRangeEnd,U as requireStorageCapability,S as matchesScanOptions,W as encodeStorageKeyComponent,f as decodeStorageKeyComponent,z as assertDurableStorageForRecovery,Q as WEFT_RESERVED_KEY_PREFIXES,g as KEYS,B as DEFAULT_SCOPE};

package/dist/storage/key-prefixes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Prefixes reserved for Weft-owned runtime data in a shared storage backend.
+ *
+ * Application state should live under an application namespace instead, for
+ * example `scopedStorage(base, 'app:my-service')` or keys beginning with
+ * `app:my-service:`. Treat this list as a stable keyspace contract: Weft may
+ * add new reserved prefixes, but application code should not write under the
+ * prefixes listed here.
+ *
+ * @example
+ * ```ts
+ * import { WEFT_RESERVED_KEY_PREFIXES } from '@lostgradient/weft/storage';
+ *
+ * const key = 'wf:order-123';
+ * const isWeftKey = WEFT_RESERVED_KEY_PREFIXES.some((prefix) => key.startsWith(prefix));
+ * console.log(isWeftKey); // true
+ * ```
+ */
+export declare const WEFT_RESERVED_KEY_PREFIXES: readonly ["actrec:", "archive:", "async-act:", "attr:", "audit:bulk:", "blob:", "budget:", "budget-charged:", "ev:", "idx:", "offload:", "op:", "review:", "schedule:", "schedule-due:", "schedule-run:", "sig:", "sigres:", "sigseq:", "state:", "tag:", "tool-effect:", "upd:", "upk:", "upr:", "wf:", "wf-cleanup:", "wf-cleanup-needed:", "wf-deadline:", "wf-delayed:", "wf-headers:", "wf-idx-", "wf-terminal:"];

package/dist/storage/key-prefixes.js

@@ -0,0 +1,35 @@
+export const WEFT_RESERVED_KEY_PREFIXES = [
+  "actrec:",
+  "archive:",
+  "async-act:",
+  "attr:",
+  "audit:bulk:",
+  "blob:",
+  "budget:",
+  "budget-charged:",
+  "ev:",
+  "idx:",
+  "offload:",
+  "op:",
+  "review:",
+  "schedule:",
+  "schedule-due:",
+  "schedule-run:",
+  "sig:",
+  "sigres:",
+  "sigseq:",
+  "state:",
+  "tag:",
+  "tool-effect:",
+  "upd:",
+  "upk:",
+  "upr:",
+  "wf:",
+  "wf-cleanup:",
+  "wf-cleanup-needed:",
+  "wf-deadline:",
+  "wf-delayed:",
+  "wf-headers:",
+  "wf-idx-",
+  "wf-terminal:"
+];

package/dist/storage/lmdb.d.ts

@@ -0,0 +1,40 @@
+import { type DeleteRangeOptions } from './delete-range';
+import { type BatchOperation, type ConditionalBatchCondition, type ScanOptions, type Storage, type StorageCapabilities } from './interface';
+/**
+ * LMDB-backed storage adapter. Reads hit lmdb-js's synchronous memory-mapped
+ * path internally, but the Storage interface presents them as Promises and
+ * copies the bytes into a fresh Uint8Array on each call. Writes use lmdb-js's
+ * async batching: individual `put`/`remove` calls return promises that resolve
+ * once the next batched transaction commits to disk. The adapter resets
+ * lmdb-js's cached read transaction after every write so subsequent reads
+ * observe just-written data.
+ *
+ * @example
+ * ```ts
+ * import { LMDBStorage } from '@lostgradient/weft/storage/lmdb';
+ * import { workflow, Engine } from '@lostgradient/weft';
+ *
+ * await using storage = new LMDBStorage('./weft-data');
+ * await using engine = new Engine({ storage });
+ * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
+ * ```
+ */
+export declare class LMDBStorage implements Storage {
+    #private;
+    constructor(path: string);
+    capabilities(): StorageCapabilities;
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    deletePrefix(prefix: string): Promise<number>;
+    deleteRange(prefix: string, options: DeleteRangeOptions): Promise<number>;
+    scan(prefix: string, options?: ScanOptions): AsyncIterable<[string, Uint8Array]>;
+    keys(prefix: string, options?: ScanOptions): AsyncIterable<string>;
+    count(prefix: string): Promise<number>;
+    scoped(prefix: string): Storage;
+    batch(operations: BatchOperation[]): Promise<void>;
+    conditionalBatch(conditions: ConditionalBatchCondition[], operations: BatchOperation[]): Promise<boolean>;
+    close(): Promise<void>;
+    [Symbol.dispose](): void;
+}

package/dist/storage/lmdb.js

@@ -0,0 +1,2 @@
+// @bun
+var y=Object.defineProperty;var g=(E)=>E;function f(E,_){this[E]=g.bind(null,_)}var l=(E,_)=>{for(var W in _)y(E,W,{get:_[W],enumerable:!0,configurable:!0,set:f.bind(_,W)})};var j=(E,_)=>()=>(E&&(_=E(E=0)),_);function B(E,_,W){if(!E.capabilities()[_])throw Error(`Feature "${W}" requires storage capability "${_}", but this storage backend does not provide it.`)}function d(E){let _=E.capabilities(),W=[];if(_.persistence!=="local")W.push(`persistence must be "local" (got "${_.persistence}")`);if(_.readAfterWrite!=="linearizable")W.push(`readAfterWrite must be "linearizable" (got "${_.readAfterWrite}")`);if(_.scanConsistency!=="snapshot")W.push(`scanConsistency must be "snapshot" (got "${_.scanConsistency}")`);if(!_.atomicBatch)W.push("atomicBatch must be true");if(!_.conditionalBatch)W.push("conditionalBatch must be true");if(W.length>0)throw Error(`Storage is not durable enough for recovery: ${W.join("; ")}.`)}var L="default";async function A(E,_){return await E.get(_)!==null}async function*Q(E,_,W){for await(let[Y]of E.scan(_,W))yield Y}async function z(E,_){let W=0;for await(let Y of Q(E,_))W++;return W}async function P(E,_){let W=[];for await(let Y of Q(E,_))W.push({type:"delete",key:Y});if(W.length===0)return 0;return await E.batch(W),W.length}async function O(E,_,W){let Y=[];for await(let X of Q(E,_,W))Y.push({type:"delete",key:X});if(Y.length===0)return 0;return await E.batch(Y),Y.length}var p;var h=j(()=>{p=["actrec:","archive:","async-act:","attr:","audit:bulk:","blob:","budget:","budget-charged:","ev:","idx:","offload:","op:","review:","schedule:","schedule-due:","schedule-run:","sig:","sigres:","sigseq:","state:","tag:","tool-effect:","upd:","upk:","upr:","wf:","wf-cleanup:","wf-cleanup-needed:","wf-deadline:","wf-delayed:","wf-headers:","wf-idx-","wf-terminal:"]});function V(E){return E.length>0?E.slice(0,-1)+String.fromCharCode(E.charCodeAt(E.length-1)+1):"\xFF"}function N(E,_={}){if(_.gt!==void 0&&E<=_.gt)return!1;if(_.gte!==void 0&&E<_.gte)return!1;if(_.lt!==void 0&&E>=_.lt)return!1;if(_.lte!==void 0&&E>_.lte)return!1;return!0}function v(E,_){if(E===null||_===null)return E===_;if(E.byteLength!==_.byteLength)return!1;for(let W=0;W<E.byteLength;W++)if(E[W]!==_[W])return!1;return!0}async function C(E,_){if(E.has)return E.has(_);return A(E,_)}function K(E,_,W){if(E.keys)return E.keys(_,W);return Q(E,_,W)}async function b(E,_){if(E.count)return E.count(_);return z(E,_)}async function S(E,_){if(E.deletePrefix)return E.deletePrefix(_);return P(E,_)}async function u(E,_,W){if(B(E,"conditionalBatch","storageConditionalBatch"),!E.conditionalBatch)throw Error("This storage backend reports conditionalBatch capability but does not implement the conditionalBatch() method.");return E.conditionalBatch(_,W)}function F(E){return encodeURIComponent(E)}function YE(E){return decodeURIComponent(E)}function XE(E){try{return decodeURIComponent(E)}catch{return null}}var J=(E)=>String(E).padStart(16,"0"),JE;var q=j(()=>{h();JE={workflow:(E)=>`wf:${F(E)}`,checkpoint:(E)=>`wf:${F(E)}:ckpt`,checkpointHistory:(E,_)=>`wf:${F(E)}:ckpt:${String(_).padStart(10,"0")}`,timelinePrefix:(E)=>`wf:${F(E)}:timeline:`,timeline:(E,_)=>`wf:${F(E)}:timeline:${String(_).padStart(10,"0")}`,schedule:(E)=>`schedule:${F(E)}`,scheduleTick:(E,_)=>`schedule-due:${String(E).padStart(16,"0")}:${F(_)}`,scheduleRun:(E)=>`schedule-run:${F(E)}`,operation:(E,_,W)=>`op:${E}:${J(_)}:${W}`,operationInflight:(E)=>`op:inflight:${E}`,operationQueued:(E)=>`op:queued:${E}`,operationResolved:(E)=>`op:resolved:${E}`,bulkOperationAuditPrefix:()=>"audit:bulk:",bulkOperationAudit:(E,_,W)=>`audit:bulk:${J(E)}:${F(_)}:${F(W)}`,operationResolvedByTimePrefix:()=>"op:resolved-by-time:",operationResolvedByTime:(E,_)=>`op:resolved-by-time:${J(E)}:${F(_)}`,asyncActivity:(E,_)=>`async-act:v1:${F(E)}:${F(_)}`,activityReconciliationPrefix:(E)=>`actrec:v1:${F(E)}:`,activityReconciliation:(E,_,W)=>`actrec:v1:${F(E)}:${F(_)}:${W}`,eventPrefix:(E)=>`ev:${F(E)}:`,event:(E,_)=>`ev:${F(E)}:${String(_).padStart(10,"0")}`,eventHead:(E)=>`ev:${F(E)}:head`,eventWatermark:(E)=>`ev:${F(E)}:watermark`,signal:(E,_,W)=>`sig:${F(E)}:${_}:${F(W)}`,signalSequence:(E)=>`sigseq:v1:${F(E)}`,signalAcceptedResponsePrefix:(E)=>`sigres:v1:${F(E)}:`,signalAcceptedResponse:(E,_,W)=>`sigres:v1:${F(E)}:${F(_)}:${F(W)}`,deadline:(E,_)=>`wf-deadline:${J(E)}:${F(_)}`,terminalCleanup:(E,_)=>`wf-cleanup:${J(E)}:${F(_)}`,delayedStart:(E,_)=>`wf-delayed:${J(E)}:${F(_)}`,terminalWorkflowPrefix:()=>"wf-terminal:",terminalWorkflow:(E,_)=>`wf-terminal:${J(E)}:${F(_)}`,attribute:(E)=>`attr:${F(E)}`,attributeIndex:(E,_,W)=>`idx:${E}:${_}:${F(W)}`,tagIndex:(E,_)=>`tag:${F(E)}:${F(_)}`,updatePrefix:(E)=>`upd:${F(E)}:`,update:(E,_)=>`upd:${F(E)}:${_}`,updateResponse:(E)=>`upr:${E}`,updateIdempotency:(E,_)=>`upk:${F(E)}:${_}`,budget:(E,_,W)=>`budget:${E}:${_}:${W}`,review:(E,_)=>`review:${F(E)}:${_}`,workflowHeaders:(E)=>`wf-headers:${F(E)}`,terminalCleanupNeeded:(E)=>`wf-cleanup-needed:${F(E)}`,offload:(E,_)=>`offload:${F(E)}:${_}`,archive:(E,_)=>`archive:${F(E)}:${_}`,stateExecution:(E,_)=>`state:execution:${F(E)}:${F(_)}`,stateWorkflow:(E,_)=>`state:workflow-scope:${L}:${F(E)}:${F(_)}`,streamChunkPrefix:(E,_)=>`blob:${F(E)}:${_}:chunk:`,streamChunk:(E,_,W)=>`blob:${F(E)}:${_}:chunk:${String(W).padStart(10,"0")}`,streamMetadata:(E,_)=>`blob:${F(E)}:${_}:meta`,budgetCharged:(E)=>`budget-charged:${E}`,toolEffect:(E,_,W)=>`tool-effect:${F(E)}:${_}:${W}`,workflowVisibilityStatus:(E,_)=>`wf-idx-status:${F(E)}:${F(_)}`,workflowVisibilityType:(E,_)=>`wf-idx-type:${F(E)}:${F(_)}`,workflowVisibilityCreated:(E,_)=>`wf-idx-created:${J(E)}:${F(_)}`,workflowVisibilityUpdated:(E,_)=>`wf-idx-updated:${J(E)}:${F(_)}`,workflowVisibilityDeadline:(E,_)=>`wf-idx-deadline:${J(E)}:${F(_)}`,workflowVisibilityManifest:(E)=>`wf-idx-manifest:${F(E)}`,workflowVisibilityMetaVersion:()=>"wf-idx-meta:version",workflowVisibilityMetaBuiltAt:()=>"wf-idx-meta:built-at",workflowVisibilityMetaCursor:()=>"wf-idx-meta:cursor"}});function s(E){if(E===void 0)return;if(typeof E!=="number"||!Number.isInteger(E)||E<0)throw Error("deleteRange limit must be a finite non-negative integer");return E===0?0:E}function H(E){let _={},W=!1;for(let X of["gt","gte","lt","lte"]){let U=E[X];if(U===void 0)continue;if(typeof U!=="string")throw Error("deleteRange bounds must be strings");_[X]=U,W=!0}if(!W)throw Error("deleteRange requires at least one of gt/gte/lt/lte; use deletePrefix to delete a whole prefix");let Y=s(E.limit);if(Y!==void 0)_.limit=Y;return _}async function I(E,_,W){let Y=H(W);if(E.deleteRange)return E.deleteRange(_,Y);return O(E,_,Y)}var D=()=>{};function R(E){return E.replaceAll(/:+$/g,"")}function a(E,_){let W=R(E),Y=R(_);if(W.length===0)return Y;if(Y.length===0)return W;return`${W}:${Y}`}function x(E,_){return new T(E,_)}var T;var c=j(()=>{D();q();T=class T{#E;#F;constructor(E,_){this.#E=E,this.#F=R(_)}#_(E){if(this.#F.length===0)return E;return E.length===0?`${this.#F}:`:`${this.#F}:${E}`}#W(E){if(this.#F.length===0)return E;return E.slice(this.#F.length+1)}#Y(E={}){let _={};if(E.limit!==void 0)_.limit=E.limit;if(E.reverse!==void 0)_.reverse=E.reverse;if(E.gt!==void 0)_.gt=this.#_(E.gt);if(E.gte!==void 0)_.gte=this.#_(E.gte);if(E.lt!==void 0)_.lt=this.#_(E.lt);if(E.lte!==void 0)_.lte=this.#_(E.lte);return _}#X(E){let _={};if(E.limit!==void 0)_.limit=E.limit;if(E.gt!==void 0)_.gt=this.#_(E.gt);if(E.gte!==void 0)_.gte=this.#_(E.gte);if(E.lt!==void 0)_.lt=this.#_(E.lt);if(E.lte!==void 0)_.lte=this.#_(E.lte);return _}capabilities(){return this.#E.capabilities()}scoped(E){return new T(this.#E,a(this.#F,E))}async get(E){return this.#E.get(this.#_(E))}async put(E,_){await this.#E.put(this.#_(E),_)}async delete(E){await this.#E.delete(this.#_(E))}async*scan(E,_){for await(let[W,Y]of this.#E.scan(this.#_(E),this.#Y(_)))yield[this.#W(W),Y]}async batch(E){await this.#E.batch(E.map((_)=>{if(_.type==="put")return{type:"put",key:this.#_(_.key),value:_.value};return{type:"delete",key:this.#_(_.key)}}))}async conditionalBatch(E,_){return u(this.#E,E.map((W)=>({key:this.#_(W.key),expectedValue:W.expectedValue})),_.map((W)=>{if(W.type==="put")return{type:"put",key:this.#_(W.key),value:W.value};return{type:"delete",key:this.#_(W.key)}}))}async has(E){return C(this.#E,this.#_(E))}async deletePrefix(E){return S(this.#E,this.#_(E))}async deleteRange(E,_){let W=this.#X(H(_));return I(this.#E,this.#_(E),W)}async*keys(E,_){for await(let W of K(this.#E,this.#_(E),this.#Y(_)))yield this.#W(W)}async count(E){return b(this.#E,this.#_(E))}[Symbol.dispose](){this.#E[Symbol.dispose]()}}});var i={};l(i,{LMDBStorage:()=>k});import*as w from"lmdb";var k;var r=j(()=>{D();q();c();k=class k{#E;#F=!1;#_=null;constructor(E){this.#E=w.open({path:E,encoding:"binary"})}#W(){if(this.#F)throw Error("LMDBStorage is closed")}capabilities(){return{persistence:"local",readAfterWrite:"linearizable",scanConsistency:"snapshot",atomicBatch:!0,conditionalBatch:!0,boundedRangeDelete:!1}}async get(E){this.#W();let _=this.#E.get(E);if(_===void 0)return null;return new Uint8Array(_)}async put(E,_){this.#W(),await this.#E.put(E,Buffer.from(_))}async delete(E){this.#W(),await this.#E.remove(E)}async has(E){return this.#W(),this.#E.doesExist(E)}async deletePrefix(E){this.#W();let _=[];for await(let W of this.keys(E))_.push(W);if(_.length===0)return 0;return await this.#E.batch(()=>{for(let W of _)this.#E.remove(W)}),_.length}async deleteRange(E,_){this.#W();let W=H(_),Y=[];for await(let X of this.keys(E,W))Y.push(X);if(Y.length===0)return 0;return await this.#E.batch(()=>{for(let X of Y)this.#E.remove(X)}),Y.length}async*scan(E,_={}){this.#W();let{limit:W,reverse:Y}=_,X=V(E),U=Y?this.#E.getRange({start:X,end:E,reverse:!0}):this.#E.getRange({start:E,end:X}),$=0,G=!1;for(let{key:Z,value:m}of U){if(!Z.startsWith(E)){if(Y&&!G)continue;break}if(G=!0,!N(Z,_))continue;if(W!==void 0&&$>=W)break;yield[Z,new Uint8Array(m)],$++}}async*keys(E,_={}){this.#W();let{limit:W,reverse:Y}=_,X=V(E),U=Y?this.#E.getKeys({start:X,end:E,reverse:!0}):this.#E.getKeys({start:E,end:X}),$=0,G=!1;for(let Z of U){if(!Z.startsWith(E)){if(Y&&!G)continue;break}if(G=!0,!N(Z,_))continue;if(W!==void 0&&$>=W)break;yield Z,$++}}async count(E){this.#W();let _=V(E);return this.#E.getKeysCount({start:E,end:_})}scoped(E){return this.#W(),x(this,E)}async batch(E){if(this.#W(),E.length===0)return;await this.#E.batch(()=>{for(let _ of E)if(_.type==="put")this.#E.put(_.key,Buffer.from(_.value));else this.#E.remove(_.key)})}async conditionalBatch(E,_){return this.#W(),this.#E.transactionSync(()=>{for(let Y of E){let X=this.#E.get(Y.key),U=X===void 0?null:new Uint8Array(X);if(!v(U,Y.expectedValue))return!1}for(let Y of _)if(Y.type==="put")this.#E.putSync(Y.key,Buffer.from(Y.value));else this.#E.removeSync(Y.key);return!0})}close(){return this.#F=!0,this.#_??=(async()=>{await Promise.resolve(),await this.#E.close()})(),this.#_}[Symbol.dispose](){this.close()}}});r();export{k as LMDBStorage};

package/dist/storage/memory.d.ts

@@ -0,0 +1,46 @@
+import { type DeleteRangeOptions } from './delete-range';
+import { type BatchOperation, type ConditionalBatchCondition, type ScanOptions, type Storage, type StorageCapabilities } from './interface';
+/**
+ * In-memory {@link Storage} implementation.
+ *
+ * Backs the engine with a `Map<string, Uint8Array>` — fast, dependency-free,
+ * and ideal for tests, ephemeral runs, and CI. State is lost when the process
+ * exits, so don't use it for anything you care about between restarts.
+ *
+ * @example Run an engine with in-memory storage
+ * ```ts
+ * import { workflow, Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * await using engine = new Engine({ storage });
+ * engine.register(
+ *   workflow({ name: 'noop' }).execute(async function* () {
+ *     return 'done';
+ *   }),
+ * );
+ *
+ * const handle = await engine.start('noop', null);
+ * const result = await handle.result();
+ * ```
+ */
+export declare class MemoryStorage implements Storage {
+    #private;
+    constructor();
+    capabilities(): StorageCapabilities;
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    scan(prefix: string, options?: ScanOptions): AsyncIterable<[string, Uint8Array]>;
+    batch(operations: BatchOperation[]): Promise<void>;
+    conditionalBatch(conditions: ConditionalBatchCondition[], operations: BatchOperation[]): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    deletePrefix(prefix: string): Promise<number>;
+    deleteRange(prefix: string, options: DeleteRangeOptions): Promise<number>;
+    keys(prefix: string, options?: ScanOptions): AsyncIterable<string>;
+    count(prefix: string): Promise<number>;
+    scoped(prefix: string): Storage;
+    get size(): number;
+    clear(): void;
+    snapshot(): Map<string, Uint8Array>;
+    [Symbol.dispose](): void;
+}

package/dist/storage/memory.js

@@ -0,0 +1,2 @@
+// @bun
+var c=Object.defineProperty;var k=(_)=>_;function y(_,E){this[_]=k.bind(null,E)}var g=(_,E)=>{for(var W in E)c(_,W,{get:E[W],enumerable:!0,configurable:!0,set:y.bind(E,W)})};var j=(_,E)=>()=>(_&&(E=_(_=0)),E);function L(_,E,W){if(!_.capabilities()[E])throw Error(`Feature "${W}" requires storage capability "${E}", but this storage backend does not provide it.`)}function f(_){let E=_.capabilities(),W=[];if(E.persistence!=="local")W.push(`persistence must be "local" (got "${E.persistence}")`);if(E.readAfterWrite!=="linearizable")W.push(`readAfterWrite must be "linearizable" (got "${E.readAfterWrite}")`);if(E.scanConsistency!=="snapshot")W.push(`scanConsistency must be "snapshot" (got "${E.scanConsistency}")`);if(!E.atomicBatch)W.push("atomicBatch must be true");if(!E.conditionalBatch)W.push("conditionalBatch must be true");if(W.length>0)throw Error(`Storage is not durable enough for recovery: ${W.join("; ")}.`)}var B="default";async function A(_,E){return await _.get(E)!==null}async function*Q(_,E,W){for await(let[Y]of _.scan(E,W))yield Y}async function z(_,E){let W=0;for await(let Y of Q(_,E))W++;return W}async function O(_,E){let W=[];for await(let Y of Q(_,E))W.push({type:"delete",key:Y});if(W.length===0)return 0;return await _.batch(W),W.length}async function P(_,E,W){let Y=[];for await(let J of Q(_,E,W))Y.push({type:"delete",key:J});if(Y.length===0)return 0;return await _.batch(Y),Y.length}var l;var h=j(()=>{l=["actrec:","archive:","async-act:","attr:","audit:bulk:","blob:","budget:","budget-charged:","ev:","idx:","offload:","op:","review:","schedule:","schedule-due:","schedule-run:","sig:","sigres:","sigseq:","state:","tag:","tool-effect:","upd:","upk:","upr:","wf:","wf-cleanup:","wf-cleanup-needed:","wf-deadline:","wf-delayed:","wf-headers:","wf-idx-","wf-terminal:"]});function G(_){return _.length>0?_.slice(0,-1)+String.fromCharCode(_.charCodeAt(_.length-1)+1):"\xFF"}function H(_,E={}){if(E.gt!==void 0&&_<=E.gt)return!1;if(E.gte!==void 0&&_<E.gte)return!1;if(E.lt!==void 0&&_>=E.lt)return!1;if(E.lte!==void 0&&_>E.lte)return!1;return!0}function v(_,E){if(_===null||E===null)return _===E;if(_.byteLength!==E.byteLength)return!1;for(let W=0;W<_.byteLength;W++)if(_[W]!==E[W])return!1;return!0}async function b(_,E){if(_.has)return _.has(E);return A(_,E)}function C(_,E,W){if(_.keys)return _.keys(E,W);return Q(_,E,W)}async function K(_,E){if(_.count)return _.count(E);return z(_,E)}async function u(_,E){if(_.deletePrefix)return _.deletePrefix(E);return O(_,E)}async function S(_,E,W){if(L(_,"conditionalBatch","storageConditionalBatch"),!_.conditionalBatch)throw Error("This storage backend reports conditionalBatch capability but does not implement the conditionalBatch() method.");return _.conditionalBatch(E,W)}function F(_){return encodeURIComponent(_)}function W_(_){return decodeURIComponent(_)}function F_(_){try{return decodeURIComponent(_)}catch{return null}}var U=(_)=>String(_).padStart(16,"0"),Y_;var N=j(()=>{h();Y_={workflow:(_)=>`wf:${F(_)}`,checkpoint:(_)=>`wf:${F(_)}:ckpt`,checkpointHistory:(_,E)=>`wf:${F(_)}:ckpt:${String(E).padStart(10,"0")}`,timelinePrefix:(_)=>`wf:${F(_)}:timeline:`,timeline:(_,E)=>`wf:${F(_)}:timeline:${String(E).padStart(10,"0")}`,schedule:(_)=>`schedule:${F(_)}`,scheduleTick:(_,E)=>`schedule-due:${String(_).padStart(16,"0")}:${F(E)}`,scheduleRun:(_)=>`schedule-run:${F(_)}`,operation:(_,E,W)=>`op:${_}:${U(E)}:${W}`,operationInflight:(_)=>`op:inflight:${_}`,operationQueued:(_)=>`op:queued:${_}`,operationResolved:(_)=>`op:resolved:${_}`,bulkOperationAuditPrefix:()=>"audit:bulk:",bulkOperationAudit:(_,E,W)=>`audit:bulk:${U(_)}:${F(E)}:${F(W)}`,operationResolvedByTimePrefix:()=>"op:resolved-by-time:",operationResolvedByTime:(_,E)=>`op:resolved-by-time:${U(_)}:${F(E)}`,asyncActivity:(_,E)=>`async-act:v1:${F(_)}:${F(E)}`,activityReconciliationPrefix:(_)=>`actrec:v1:${F(_)}:`,activityReconciliation:(_,E,W)=>`actrec:v1:${F(_)}:${F(E)}:${W}`,eventPrefix:(_)=>`ev:${F(_)}:`,event:(_,E)=>`ev:${F(_)}:${String(E).padStart(10,"0")}`,eventHead:(_)=>`ev:${F(_)}:head`,eventWatermark:(_)=>`ev:${F(_)}:watermark`,signal:(_,E,W)=>`sig:${F(_)}:${E}:${F(W)}`,signalSequence:(_)=>`sigseq:v1:${F(_)}`,signalAcceptedResponsePrefix:(_)=>`sigres:v1:${F(_)}:`,signalAcceptedResponse:(_,E,W)=>`sigres:v1:${F(_)}:${F(E)}:${F(W)}`,deadline:(_,E)=>`wf-deadline:${U(_)}:${F(E)}`,terminalCleanup:(_,E)=>`wf-cleanup:${U(_)}:${F(E)}`,delayedStart:(_,E)=>`wf-delayed:${U(_)}:${F(E)}`,terminalWorkflowPrefix:()=>"wf-terminal:",terminalWorkflow:(_,E)=>`wf-terminal:${U(_)}:${F(E)}`,attribute:(_)=>`attr:${F(_)}`,attributeIndex:(_,E,W)=>`idx:${_}:${E}:${F(W)}`,tagIndex:(_,E)=>`tag:${F(_)}:${F(E)}`,updatePrefix:(_)=>`upd:${F(_)}:`,update:(_,E)=>`upd:${F(_)}:${E}`,updateResponse:(_)=>`upr:${_}`,updateIdempotency:(_,E)=>`upk:${F(_)}:${E}`,budget:(_,E,W)=>`budget:${_}:${E}:${W}`,review:(_,E)=>`review:${F(_)}:${E}`,workflowHeaders:(_)=>`wf-headers:${F(_)}`,terminalCleanupNeeded:(_)=>`wf-cleanup-needed:${F(_)}`,offload:(_,E)=>`offload:${F(_)}:${E}`,archive:(_,E)=>`archive:${F(_)}:${E}`,stateExecution:(_,E)=>`state:execution:${F(_)}:${F(E)}`,stateWorkflow:(_,E)=>`state:workflow-scope:${B}:${F(_)}:${F(E)}`,streamChunkPrefix:(_,E)=>`blob:${F(_)}:${E}:chunk:`,streamChunk:(_,E,W)=>`blob:${F(_)}:${E}:chunk:${String(W).padStart(10,"0")}`,streamMetadata:(_,E)=>`blob:${F(_)}:${E}:meta`,budgetCharged:(_)=>`budget-charged:${_}`,toolEffect:(_,E,W)=>`tool-effect:${F(_)}:${E}:${W}`,workflowVisibilityStatus:(_,E)=>`wf-idx-status:${F(_)}:${F(E)}`,workflowVisibilityType:(_,E)=>`wf-idx-type:${F(_)}:${F(E)}`,workflowVisibilityCreated:(_,E)=>`wf-idx-created:${U(_)}:${F(E)}`,workflowVisibilityUpdated:(_,E)=>`wf-idx-updated:${U(_)}:${F(E)}`,workflowVisibilityDeadline:(_,E)=>`wf-idx-deadline:${U(_)}:${F(E)}`,workflowVisibilityManifest:(_)=>`wf-idx-manifest:${F(_)}`,workflowVisibilityMetaVersion:()=>"wf-idx-meta:version",workflowVisibilityMetaBuiltAt:()=>"wf-idx-meta:built-at",workflowVisibilityMetaCursor:()=>"wf-idx-meta:cursor"}});function d(_){if(_===void 0)return;if(typeof _!=="number"||!Number.isInteger(_)||_<0)throw Error("deleteRange limit must be a finite non-negative integer");return _===0?0:_}function V(_){let E={},W=!1;for(let J of["gt","gte","lt","lte"]){let X=_[J];if(X===void 0)continue;if(typeof X!=="string")throw Error("deleteRange bounds must be strings");E[J]=X,W=!0}if(!W)throw Error("deleteRange requires at least one of gt/gte/lt/lte; use deletePrefix to delete a whole prefix");let Y=d(_.limit);if(Y!==void 0)E.limit=Y;return E}async function I(_,E,W){let Y=V(W);if(_.deleteRange)return _.deleteRange(E,Y);return P(_,E,Y)}var q=()=>{};function D(_){return _.replaceAll(/:+$/g,"")}function s(_,E){let W=D(_),Y=D(E);if(W.length===0)return Y;if(Y.length===0)return W;return`${W}:${Y}`}function x(_,E){return new R(_,E)}var R;var w=j(()=>{q();N();R=class R{#_;#W;constructor(_,E){this.#_=_,this.#W=D(E)}#E(_){if(this.#W.length===0)return _;return _.length===0?`${this.#W}:`:`${this.#W}:${_}`}#F(_){if(this.#W.length===0)return _;return _.slice(this.#W.length+1)}#Y(_={}){let E={};if(_.limit!==void 0)E.limit=_.limit;if(_.reverse!==void 0)E.reverse=_.reverse;if(_.gt!==void 0)E.gt=this.#E(_.gt);if(_.gte!==void 0)E.gte=this.#E(_.gte);if(_.lt!==void 0)E.lt=this.#E(_.lt);if(_.lte!==void 0)E.lte=this.#E(_.lte);return E}#X(_){let E={};if(_.limit!==void 0)E.limit=_.limit;if(_.gt!==void 0)E.gt=this.#E(_.gt);if(_.gte!==void 0)E.gte=this.#E(_.gte);if(_.lt!==void 0)E.lt=this.#E(_.lt);if(_.lte!==void 0)E.lte=this.#E(_.lte);return E}capabilities(){return this.#_.capabilities()}scoped(_){return new R(this.#_,s(this.#W,_))}async get(_){return this.#_.get(this.#E(_))}async put(_,E){await this.#_.put(this.#E(_),E)}async delete(_){await this.#_.delete(this.#E(_))}async*scan(_,E){for await(let[W,Y]of this.#_.scan(this.#E(_),this.#Y(E)))yield[this.#F(W),Y]}async batch(_){await this.#_.batch(_.map((E)=>{if(E.type==="put")return{type:"put",key:this.#E(E.key),value:E.value};return{type:"delete",key:this.#E(E.key)}}))}async conditionalBatch(_,E){return S(this.#_,_.map((W)=>({key:this.#E(W.key),expectedValue:W.expectedValue})),E.map((W)=>{if(W.type==="put")return{type:"put",key:this.#E(W.key),value:W.value};return{type:"delete",key:this.#E(W.key)}}))}async has(_){return b(this.#_,this.#E(_))}async deletePrefix(_){return u(this.#_,this.#E(_))}async deleteRange(_,E){let W=this.#X(V(E));return I(this.#_,this.#E(_),W)}async*keys(_,E){for await(let W of C(this.#_,this.#E(_),this.#Y(E)))yield this.#F(W)}async count(_){return K(this.#_,this.#E(_))}[Symbol.dispose](){this.#_[Symbol.dispose]()}}});var p={};g(p,{MemoryStorage:()=>m});var m;var a=j(()=>{q();N();w();m=class m{#_;constructor(){this.#_=new Map}capabilities(){return{persistence:"ephemeral",readAfterWrite:"linearizable",scanConsistency:"snapshot",atomicBatch:!0,conditionalBatch:!0,boundedRangeDelete:!0}}#W(_,E,W){return _>=E&&_<W}#E(_,E){let W=[];for(let Y of this.#_.keys())if(this.#W(Y,_,E))W.push(Y);return W.toSorted()}async get(_){return this.#_.get(_)??null}async put(_,E){this.#_.set(_,E)}async delete(_){this.#_.delete(_)}async*scan(_,E={}){let{limit:W,reverse:Y}=E,J=G(_),X=this.#E(_,J);if(X=X.filter(($)=>H($,E)),Y)X.reverse();let Z=0;for(let $ of X){if(W!==void 0&&Z>=W)break;let T=this.#_.get($);if(T!==void 0)yield[$,T],Z++}}async batch(_){this.#F(_)}#F(_){for(let E of _)if(E.type==="put")this.#_.set(E.key,E.value);else this.#_.delete(E.key)}async conditionalBatch(_,E){for(let W of _){let Y=this.#_.get(W.key)??null;if(!v(Y,W.expectedValue))return!1}return this.#F(E),!0}async has(_){return this.#_.has(_)}async deletePrefix(_){let E=G(_),W=this.#E(_,E);for(let Y of W)this.#_.delete(Y);return W.length}async deleteRange(_,E){let W=V(E),Y=G(_),J=this.#E(_,Y).filter((Z)=>H(Z,W)),X=W.limit===void 0?J:J.slice(0,W.limit);for(let Z of X)this.#_.delete(Z);return X.length}async*keys(_,E={}){let{limit:W,reverse:Y}=E,J=G(_),X=this.#E(_,J);if(X=X.filter(($)=>H($,E)),Y)X.reverse();let Z=0;for(let $ of X){if(W!==void 0&&Z>=W)break;yield $,Z++}}async count(_){let E=G(_);return this.#E(_,E).length}scoped(_){return x(this,_)}get size(){return this.#_.size}clear(){this.#_.clear()}snapshot(){let _=new Map;for(let[E,W]of this.#_)_.set(E,new Uint8Array(W));return _}[Symbol.dispose](){this.#_.clear()}}});a();export{m as MemoryStorage};

package/dist/storage/node-sqlite.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Node-compatible SQLite storage adapter using `better-sqlite3`.
+ *
+ * Implements the same `Storage` interface and SQL schema as `BunSQLiteStorage`
+ * but uses `better-sqlite3` instead of `bun:sqlite`, enabling the same
+ * storage layer to run on Node.js 22+.
+ *
+ * `better-sqlite3` is a peer dependency — it must be installed separately by
+ * consumers who import `@lostgradient/weft/storage/sqlite/node`.
+ *
+ * @module storage/node-sqlite
+ */
+import type { BatchOperation, ConditionalBatchCondition, ScanOptions, Storage, StorageCapabilities } from './interface.ts';
+/**
+ * Minimal subset of the `better-sqlite3` API surface that this adapter uses.
+ * Defined here so the module compiles without the package installed — the
+ * actual dependency is resolved lazily at construction time.
+ */
+type BetterSqliteStatement = {
+    run(...parameters: unknown[]): unknown;
+    get(...parameters: unknown[]): Record<string, unknown> | undefined;
+    all(...parameters: unknown[]): Record<string, unknown>[];
+};
+type BetterSqliteTransaction = (...args: unknown[]) => unknown;
+type BetterSqliteDatabase = {
+    pragma(source: string): unknown;
+    exec(source: string): void;
+    prepare(source: string): BetterSqliteStatement;
+    transaction(fn: (...args: unknown[]) => unknown): BetterSqliteTransaction;
+    close(): void;
+};
+type BetterSqliteConstructor = new (path: string) => BetterSqliteDatabase;
+/**
+ * Runtime-neutral alias for the Node SQLite adapter. Consumers that import
+ * from `@lostgradient/weft/storage/sqlite` get this class under Node.
+ */
+export { NodeSQLiteStorage as SQLiteStorage };
+/**
+ * SQLite-backed {@link Storage} using `better-sqlite3` for Node.js 22+
+ * environments.
+ *
+ * Implements the same WAL-mode schema as {@link BunSQLiteStorage}
+ * but resolves the `better-sqlite3` peer dependency lazily at construction time,
+ * so the module compiles without it installed.  Import from
+ * `@lostgradient/weft/storage/sqlite/node` to use this adapter.
+ *
+ * Unlike BunSQLiteStorage, this adapter currently implements only the required
+ * Storage methods (`get`, `put`, `delete`, `scan`, `batch`, and
+ * `conditionalBatch`). The optional `has`, `keys`, `count`, `deletePrefix`, and
+ * `scoped` helpers fall back to the generic implementations in
+ * `@lostgradient/weft/storage/interface`; `deleteRange` falls back to `storageDeleteRange`
+ * (exported from `@lostgradient/weft` / `@lostgradient/weft/storage`). There is no SQL passthrough
+ * `query()` method.
+ *
+ * @example
+ * ```ts
+ * import { NodeSQLiteStorage } from '@lostgradient/weft/storage/sqlite/node';
+ * import { workflow, Engine } from '@lostgradient/weft';
+ *
+ * // Requires: bun add better-sqlite3
+ * await using storage = new NodeSQLiteStorage('./weft.db');
+ * await using engine = new Engine({ storage });
+ *
+ * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
+ * const handle = await engine.start('ping', null);
+ * console.log(await handle.result()); // 'pong'
+ * ```
+ */
+export declare class NodeSQLiteStorage implements Storage {
+    #private;
+    /**
+     * Number of distinct prepared-statement cache entries for scan().
+     * Exposed for regression tests that assert the cache stays bounded.
+     */
+    get scanStatementCacheSize(): number;
+    capabilities(): StorageCapabilities;
+    constructor(path?: string, databaseConstructor?: BetterSqliteConstructor);
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    scan(prefix: string, options?: ScanOptions): AsyncIterable<[string, Uint8Array]>;
+    batch(operations: BatchOperation[]): Promise<void>;
+    conditionalBatch(conditions: ConditionalBatchCondition[], operations: BatchOperation[]): Promise<boolean>;
+    [Symbol.dispose](): void;
+}