@periodic/vanadium 1.0.0

package/dist/esm/resilience/circuitBreaker.js

@@ -0,0 +1,124 @@
+import { createStorageError } from '../errors/index.js';
+import { sleep } from '../utils/sleep.js';
+const DEFAULT_FAILURE_THRESHOLD = 5;
+const DEFAULT_RESET_TIMEOUT_MS = 30000;
+const DEFAULT_HALF_OPEN_MAX_CALLS = 1;
+// ─── Circuit Breaker ──────────────────────────────────────────────────────────
+/**
+ * Wraps a StorageAdapter with a circuit breaker pattern.
+ * Protects the application from repeated storage failures.
+ *
+ * States:
+ * - CLOSED: Normal operation. Failures counted.
+ * - OPEN: Storage blocked. All calls throw immediately.
+ * - HALF_OPEN: Probe mode. Limited calls allowed to test recovery.
+ */
+export class CircuitBreakerAdapter {
+    constructor(adapter, options = {}, clock = Date.now) {
+        this.state = 'CLOSED';
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.halfOpenCalls = 0;
+        this.adapter = adapter;
+        this.name = `circuit-breaker(${adapter.name})`;
+        this.failureThreshold = options.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD;
+        this.resetTimeoutMs = options.resetTimeoutMs ?? DEFAULT_RESET_TIMEOUT_MS;
+        this.halfOpenMaxCalls = options.halfOpenMaxCalls ?? DEFAULT_HALF_OPEN_MAX_CALLS;
+        this.clock = clock;
+        this.lastFailureAt = clock();
+    }
+    // ── StorageAdapter implementation ─────────────────────────────────────────
+    async get(key) {
+        return this._execute(() => this.adapter.get(key), key);
+    }
+    async set(key, value, ttlMs) {
+        return this._execute(() => this.adapter.set(key, value, ttlMs), key);
+    }
+    async delete(key) {
+        return this._execute(() => this.adapter.delete(key), key);
+    }
+    async compareAndSet(key, expectedOwnerToken, newValue, ttlMs) {
+        if (!this.adapter.compareAndSet) {
+            throw createStorageError(key, this.name, new Error('Adapter does not support compareAndSet'), this.clock);
+        }
+        return this._execute(() => this.adapter.compareAndSet(key, expectedOwnerToken, newValue, ttlMs), key);
+    }
+    // ── State Inspection ──────────────────────────────────────────────────────
+    getState() {
+        this._checkReset();
+        return this.state;
+    }
+    reset() {
+        this.state = 'CLOSED';
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.halfOpenCalls = 0;
+    }
+    // ── Private ───────────────────────────────────────────────────────────────
+    async _execute(fn, key) {
+        this._checkReset();
+        if (this.state === 'OPEN') {
+            throw createStorageError(key, this.name, new Error(`Circuit breaker is OPEN for adapter "${this.adapter.name}". Storage calls blocked.`), this.clock);
+        }
+        if (this.state === 'HALF_OPEN' && this.halfOpenCalls >= this.halfOpenMaxCalls) {
+            await sleep(100); // brief backoff
+            throw createStorageError(key, this.name, new Error('Circuit breaker is HALF_OPEN. Probe call limit reached.'), this.clock);
+        }
+        if (this.state === 'HALF_OPEN') {
+            this.halfOpenCalls++;
+        }
+        try {
+            const result = await fn();
+            this._onSuccess();
+            return result;
+        }
+        catch (err) {
+            this._onFailure();
+            throw err;
+        }
+    }
+    _onSuccess() {
+        this.failureCount = 0;
+        this.successCount++;
+        if (this.state === 'HALF_OPEN') {
+            this.state = 'CLOSED';
+            this.halfOpenCalls = 0;
+        }
+    }
+    _onFailure() {
+        this.failureCount++;
+        this.lastFailureAt = this.clock();
+        if (this.state === 'HALF_OPEN') {
+            this.state = 'OPEN';
+            this.halfOpenCalls = 0;
+        }
+        else if (this.failureCount >= this.failureThreshold) {
+            this.state = 'OPEN';
+        }
+    }
+    _checkReset() {
+        if (this.state === 'OPEN') {
+            const elapsed = this.clock() - this.lastFailureAt;
+            if (elapsed >= this.resetTimeoutMs) {
+                this.state = 'HALF_OPEN';
+                this.halfOpenCalls = 0;
+            }
+        }
+    }
+}
+// ─── Factory ──────────────────────────────────────────────────────────────────
+/**
+ * Wrap any StorageAdapter with a circuit breaker.
+ *
+ * @example
+ * ```ts
+ * const protectedAdapter = createCircuitBreaker(redisAdapter, {
+ *   failureThreshold: 3,
+ *   resetTimeoutMs: 15_000,
+ * });
+ * ```
+ */
+export function createCircuitBreaker(adapter, options, clock) {
+    return new CircuitBreakerAdapter(adapter, options, clock);
+}
+//# sourceMappingURL=circuitBreaker.js.map

package/dist/esm/resilience/circuitBreaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuitBreaker.js","sourceRoot":"","sources":["../../../src/resilience/circuitBreaker.ts"],"names":[],"mappings":"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"}

package/dist/esm/types/index.js

@@ -0,0 +1,10 @@
+/**
+ * @periodic/vanadium — Core Type Definitions
+ * Deterministic idempotency and distributed lock engine
+ */
+export const VALID_TRANSITIONS = [
+    'IN_PROGRESS -> COMPLETED',
+    'IN_PROGRESS -> FAILED',
+    'IN_PROGRESS -> IN_PROGRESS', // expired takeover
+];
+//# sourceMappingURL=index.js.map

package/dist/esm/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA2OH,MAAM,CAAC,MAAM,iBAAiB,GAA+B;IAC3D,0BAA0B;IAC1B,uBAAuB;IACvB,4BAA4B,EAAE,mBAAmB;CACzC,CAAC"}

package/dist/esm/utils/crypto.js

@@ -0,0 +1,58 @@
+import { createHash, randomUUID } from 'node:crypto';
+/**
+ * Deterministically hash an arbitrary payload using SHA-256.
+ * JSON.stringify order is normalized using sorted keys for determinism.
+ */
+export function hashPayload(payload) {
+    const normalized = JSON.stringify(sortKeys(payload));
+    return createHash('sha256').update(normalized).digest('hex');
+}
+/**
+ * Recursively sort object keys for deterministic JSON serialization.
+ */
+function sortKeys(value) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(sortKeys);
+    }
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+        sorted[key] = sortKeys(value[key]);
+    }
+    return sorted;
+}
+/**
+ * Generate a cryptographically secure owner token (UUID v4).
+ */
+export function generateOwnerToken() {
+    return randomUUID();
+}
+/**
+ * Safely serialize a value to JSON string.
+ * Throws STORAGE_ERROR compatible message on failure.
+ */
+export function safeJsonStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`JSON serialization failed: ${msg}`);
+    }
+}
+/**
+ * Safely parse a JSON string.
+ * Throws STORAGE_ERROR compatible message on failure.
+ */
+export function safeJsonParse(raw, context = 'record') {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`JSON parse failure in ${context}: ${msg}`);
+    }
+}
+//# sourceMappingURL=crypto.js.map

package/dist/esm/utils/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../../src/utils/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAErD;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACrD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;IACD,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACvE,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAc,GAAW,EAAE,OAAO,GAAG,QAAQ;IACxE,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,KAAK,GAAG,EAAE,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC"}

package/dist/esm/utils/keys.js

@@ -0,0 +1,35 @@
+import { createConfigurationError } from '../errors/index.js';
+const MAX_KEY_LENGTH = 512;
+const VALID_KEY_PATTERN = /^[\w\-:.@/]+$/;
+/**
+ * Validate an idempotency key for safety and format correctness.
+ * Throws a VanadiumError (CONFIGURATION_ERROR) on invalid input.
+ */
+export function validateKey(key, adapterName) {
+    if (!key || key.trim().length === 0) {
+        throw createConfigurationError(key, adapterName, 'Idempotency key must be a non-empty string.');
+    }
+    if (key.length > MAX_KEY_LENGTH) {
+        throw createConfigurationError(key, adapterName, `Idempotency key exceeds maximum length of ${MAX_KEY_LENGTH} characters. Got ${key.length}.`);
+    }
+    if (!VALID_KEY_PATTERN.test(key)) {
+        throw createConfigurationError(key, adapterName, `Idempotency key "${key}" contains invalid characters. ` +
+            `Allowed: alphanumeric, hyphens, underscores, colons, dots, @, and forward slashes.`);
+    }
+}
+/**
+ * Build a namespaced key: prefix + namespace + key.
+ * Example: "vanadium:payments:order_123"
+ */
+export function buildNamespacedKey(key, prefix = '', namespace = '') {
+    const parts = [prefix, namespace, key].filter(Boolean);
+    return parts.join(':');
+}
+/**
+ * Assert the key is valid and return it unchanged (for chaining).
+ */
+export function assertValidKey(key, adapterName) {
+    validateKey(key, adapterName);
+    return key;
+}
+//# sourceMappingURL=keys.js.map

package/dist/esm/utils/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../src/utils/keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,MAAM,cAAc,GAAG,GAAG,CAAC;AAC3B,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAE1C;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,WAAmB;IAC1D,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,MAAM,wBAAwB,CAAC,GAAG,EAAE,WAAW,EAAE,6CAA6C,CAAC,CAAC;IAClG,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;QAChC,MAAM,wBAAwB,CAC5B,GAAG,EACH,WAAW,EACX,6CAA6C,cAAc,oBAAoB,GAAG,CAAC,MAAM,GAAG,CAC7F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,wBAAwB,CAC5B,GAAG,EACH,WAAW,EACX,oBAAoB,GAAG,iCAAiC;YACtD,oFAAoF,CACvF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW,EAAE,MAAM,GAAG,EAAE,EAAE,SAAS,GAAG,EAAE;IACzE,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,WAAmB;IAC7D,WAAW,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAC9B,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/esm/utils/sleep.js

@@ -0,0 +1,20 @@
+/**
+ * Non-blocking async sleep.
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Add ±jitter to a base delay to prevent thundering herd.
+ */
+export function jitter(baseMs, factor = 0.2) {
+    const delta = baseMs * factor;
+    return baseMs + (Math.random() * 2 - 1) * delta;
+}
+/**
+ * Sleep with jitter applied.
+ */
+export function sleepWithJitter(baseMs, factor = 0.2) {
+    return sleep(jitter(baseMs, factor));
+}
+//# sourceMappingURL=sleep.js.map

package/dist/esm/utils/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../../../src/utils/sleep.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,MAAM,CAAC,MAAc,EAAE,MAAM,GAAG,GAAG;IACjD,MAAM,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAC9B,OAAO,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,MAAM,GAAG,GAAG;IAC1D,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AACvC,CAAC"}

package/dist/types/adapters/memory/index.d.ts

@@ -0,0 +1,49 @@
+import type { StorageAdapter, StoredRecord } from '../../types/index.js';
+export interface MemoryAdapterOptions {
+    /** Maximum number of keys before LRU eviction (default: unlimited) */
+    maxKeys?: number;
+    /** Clock function — injectable for deterministic testing */
+    clock?: () => number;
+}
+/**
+ * Built-in in-memory storage adapter.
+ *
+ * Features:
+ * - O(1) key lookup via Map
+ * - Automatic TTL eviction on read
+ * - Optional maxKeys with LRU eviction to prevent unbounded growth
+ * - No global state — each instance is isolated
+ *
+ * @example
+ * ```ts
+ * import { createMemoryAdapter } from '@periodic/vanadium';
+ * const adapter = createMemoryAdapter({ maxKeys: 10_000 });
+ * ```
+ */
+export declare class MemoryAdapter implements StorageAdapter {
+    readonly name = "memory";
+    private readonly store;
+    private readonly maxKeys;
+    private readonly clock;
+    constructor(options?: MemoryAdapterOptions);
+    get<T = unknown>(key: string): Promise<StoredRecord<T> | null>;
+    set<T = unknown>(key: string, value: StoredRecord<T>, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    compareAndSet<T = unknown>(key: string, expectedOwnerToken: string, newValue: StoredRecord<T>, ttlMs?: number): Promise<boolean>;
+    setIfAbsent<T = unknown>(key: string, value: StoredRecord<T>, ttlMs?: number): Promise<boolean>;
+    /** Evict the single least-recently-accessed entry. */
+    private _evictLRU;
+    /** Return current number of stored keys. */
+    size(): number;
+    /** Clear all stored entries. */
+    clear(): void;
+    /** Expose adapter capabilities. */
+    capabilities(): {
+        transactions: boolean;
+        cas: boolean;
+        ttl: boolean;
+        advisoryLocks: boolean;
+    };
+}
+export declare function createMemoryAdapter(options?: MemoryAdapterOptions): MemoryAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/adapters/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adapters/memory/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAKzE,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAYD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,SAAgB,IAAI,YAAY;IAEhC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,OAAO,GAAE,oBAAyB;IAKxC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAiB9D,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBpF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,aAAa,CAAC,CAAC,GAAG,OAAO,EAC7B,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,MAAM,EAC1B,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,EACzB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;IAiBb,WAAW,CAAC,CAAC,GAAG,OAAO,EAC3B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EACtB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;IAkBnB,sDAAsD;IACtD,OAAO,CAAC,SAAS;IAgBjB,4CAA4C;IAC5C,IAAI,IAAI,MAAM;IAId,gCAAgC;IAChC,KAAK,IAAI,IAAI;IAIb,mCAAmC;IACnC,YAAY;;;;;;CAQb;AAID,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,aAAa,CAEjF"}

package/dist/types/adapters/mongodb/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * MongoDB Storage Adapter for @periodic/vanadium
+ *
+ * Peer dependency: "mongodb" >= 5.0.0
+ * Import: import { createMongoAdapter } from '@periodic/vanadium/adapters/mongodb'
+ *
+ * Uses the official MongoDB driver (NOT Mongoose).
+ * The caller is responsible for providing a connected MongoClient.
+ *
+ * Required indexes (run once):
+ * ```js
+ * db.collection('vanadium_records').createIndex({ expiresAt: 1 });
+ * db.collection('vanadium_records').createIndex({ status: 1, expiresAt: 1 });
+ * ```
+ */
+import type { StorageAdapter, StoredRecord } from '../../types/index.js';
+interface MongoCollection {
+    findOne(filter: any, options?: any): Promise<any>;
+    insertOne(doc: any, options?: any): Promise<any>;
+    findOneAndUpdate(filter: any, update: any, options?: any): Promise<any>;
+    deleteOne(filter: any, options?: any): Promise<any>;
+    createIndex(spec: any, options?: any): Promise<string>;
+}
+interface MongoDb {
+    collection(name: string): MongoCollection;
+}
+interface MongoClientLike {
+    db(name: string): MongoDb;
+    startSession(): any;
+}
+export interface MongoAdapterOptions {
+    /** Connected MongoClient */
+    client: MongoClientLike;
+    /** Database name */
+    dbName: string;
+    /** Collection name (default: "vanadium_records") */
+    collectionName?: string;
+    /** Use multi-document transactions (requires replica set) (default: true) */
+    useTransactions?: boolean;
+    /** Write concern (default: { w: "majority" }) */
+    writeConcern?: Record<string, any>;
+    /** Clock function for deterministic testing */
+    clock?: () => number;
+}
+interface VanadiumDocument {
+    _id: string;
+    status: string;
+    result?: unknown;
+    payloadHash?: string;
+    ownerToken?: string;
+    attempts: number;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt?: number;
+}
+export declare class MongoAdapter implements StorageAdapter {
+    readonly name = "mongodb";
+    private readonly db;
+    private readonly collectionName;
+    private readonly useTransactions;
+    private readonly clock;
+    constructor(options: MongoAdapterOptions);
+    private get collection();
+    get<T = unknown>(key: string): Promise<StoredRecord<T> | null>;
+    set<T = unknown>(key: string, value: StoredRecord<T>, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    compareAndSet<T = unknown>(key: string, expectedOwnerToken: string, newValue: StoredRecord<T>, ttlMs?: number): Promise<boolean>;
+    /**
+     * Atomic expired takeover using conditional findOneAndUpdate.
+     * Guarantees only one concurrent caller succeeds.
+     */
+    takeoverExpired(key: string, newOwnerToken: string, ttlMs: number): Promise<VanadiumDocument | null>;
+    capabilities(): {
+        transactions: boolean;
+        cas: boolean;
+        ttl: boolean;
+        advisoryLocks: boolean;
+    };
+    private _docToRecord;
+}
+/**
+ * Create a MongoDB storage adapter.
+ *
+ * @example
+ * ```ts
+ * import { MongoClient } from 'mongodb';
+ * import { createMongoAdapter } from '@periodic/vanadium/adapters/mongodb';
+ *
+ * const client = new MongoClient(process.env.MONGO_URL!);
+ * await client.connect();
+ *
+ * const adapter = createMongoAdapter({ client, dbName: 'myapp' });
+ * ```
+ */
+export declare function createMongoAdapter(options: MongoAdapterOptions): MongoAdapter;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/types/adapters/mongodb/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adapters/mongodb/index.ts"],"names":[],"mappings":"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"}

package/dist/types/adapters/mongoose/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Mongoose Storage Adapter Wrapper for @periodic/vanadium
+ *
+ * Peer dependency: "mongoose" >= 7.0.0
+ * Import: import { createMongooseAdapter } from '@periodic/vanadium/adapters/mongoose'
+ *
+ * This is a WRAPPER that preserves identical semantics to the MongoDB native adapter.
+ * Mongoose is purely an ORM layer — it does NOT change idempotency behavior.
+ *
+ * Required Prisma schema:
+ * ```prisma
+ * model vanadiumRecord {
+ *   id          String  @id @map("_id")
+ *   status      String
+ *   result      Json?
+ *   payloadHash String?
+ *   ownerToken  String?
+ *   attempts    Int     @default(0)
+ *   createdAt   BigInt
+ *   updatedAt   BigInt
+ *   expiresAt   BigInt?
+ * }
+ * ```
+ *
+ * Required Mongoose schema (use createVanadiumSchema() helper):
+ * ```ts
+ * import { createVanadiumSchema } from '@periodic/vanadium/adapters/mongoose';
+ * const VanadiumRecord = mongoose.model('VanadiumRecord', createVanadiumSchema());
+ * ```
+ */
+import type { StorageAdapter, StoredRecord } from '../../types/index.js';
+interface MongooseDocument {
+    _id: string;
+    status: string;
+    result?: unknown;
+    payloadHash?: string;
+    ownerToken?: string;
+    attempts: number;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt?: number;
+    toObject(): Record<string, unknown>;
+}
+interface MongooseModel {
+    create(doc: any): Promise<MongooseDocument>;
+    findOneAndUpdate(filter: any, update: any, options?: any): Promise<MongooseDocument | null>;
+    findOne(filter: any): Promise<MongooseDocument | null>;
+    deleteOne(filter: any): Promise<any>;
+    db: {
+        startSession(): Promise<any>;
+    };
+}
+type SchemaDefinition = Record<string, unknown>;
+interface MongooseSchemaConstructor {
+    new (definition: SchemaDefinition, options?: Record<string, unknown>): unknown;
+    Types: {
+        Mixed: unknown;
+    };
+}
+export interface MongooseAdapterOptions {
+    /** Mongoose Model with Vanadium schema */
+    model: MongooseModel;
+    /** Use transactions (requires replica set) (default: true) */
+    useTransactions?: boolean;
+    /** Custom session factory */
+    sessionFactory?: () => Promise<unknown>;
+    /** Clock function for deterministic testing */
+    clock?: () => number;
+}
+export declare class MongooseAdapter implements StorageAdapter {
+    readonly name = "mongoose";
+    private readonly model;
+    private readonly useTransactions;
+    private readonly clock;
+    constructor(options: MongooseAdapterOptions);
+    get<T = unknown>(key: string): Promise<StoredRecord<T> | null>;
+    set<T = unknown>(key: string, value: StoredRecord<T>, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    compareAndSet<T = unknown>(key: string, expectedOwnerToken: string, newValue: StoredRecord<T>, ttlMs?: number): Promise<boolean>;
+    capabilities(): {
+        transactions: boolean;
+        cas: boolean;
+        ttl: boolean;
+        advisoryLocks: boolean;
+    };
+    private _docToRecord;
+}
+/**
+ * Build the required Mongoose schema for Vanadium records.
+ * Pass the Mongoose Schema constructor from your mongoose import.
+ */
+export declare function createVanadiumSchema(Schema: MongooseSchemaConstructor): unknown;
+/**
+ * Create a Mongoose storage adapter.
+ *
+ * @example
+ * ```ts
+ * import mongoose from 'mongoose';
+ * import { createMongooseAdapter, createVanadiumSchema } from '@periodic/vanadium/adapters/mongoose';
+ *
+ * const VanadiumRecord = mongoose.model('VanadiumRecord', createVanadiumSchema(mongoose.Schema));
+ * const adapter = createMongooseAdapter({ model: VanadiumRecord });
+ * ```
+ */
+export declare function createMongooseAdapter(options: MongooseAdapterOptions): MongooseAdapter;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/types/adapters/mongoose/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adapters/mongoose/index.ts"],"names":[],"mappings":"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"}

package/dist/types/adapters/postgres/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * PostgreSQL Storage Adapter for @periodic/vanadium
+ *
+ * Peer dependency: "pg" >= 8.0.0
+ * Import: import { createPostgresAdapter } from '@periodic/vanadium/adapters/postgres'
+ *
+ * The caller MUST provide an already-created Pool or Client instance.
+ * This adapter never creates or closes connections.
+ *
+ * Required schema:
+ * ```sql
+ * CREATE TABLE public.vanadium_records (
+ *   key          TEXT PRIMARY KEY,
+ *   status       TEXT NOT NULL CHECK (status IN ('IN_PROGRESS','COMPLETED','FAILED')),
+ *   result       JSONB,
+ *   payload_hash TEXT,
+ *   owner_token  TEXT,
+ *   attempts     INTEGER NOT NULL DEFAULT 0,
+ *   created_at   BIGINT NOT NULL,
+ *   updated_at   BIGINT NOT NULL,
+ *   expires_at   BIGINT
+ * );
+ * CREATE INDEX idx_vanadium_expires_at ON public.vanadium_records (expires_at);
+ * CREATE INDEX idx_vanadium_status_expires ON public.vanadium_records (status, expires_at);
+ * ```
+ */
+import type { StorageAdapter, StoredRecord } from '../../types/index.js';
+interface PgQueryable {
+    query(text: string, values?: any[]): Promise<{
+        rows: any[];
+        rowCount: number | null;
+    }>;
+}
+export interface PostgresAdapterOptions {
+    /** Pre-created pg Pool or Client */
+    client: PgQueryable & {
+        connect?: () => Promise<PgQueryable & {
+            release: () => void;
+        }>;
+    };
+    /** Table name (default: "vanadium_records") */
+    tableName?: string;
+    /** Schema name (default: "public") */
+    schemaName?: string;
+    /** Use pg advisory locks for distributed lock mode (default: false) */
+    useAdvisoryLocks?: boolean;
+    /** Clock function for deterministic testing */
+    clock?: () => number;
+}
+export declare class PostgresAdapter implements StorageAdapter {
+    readonly name = "postgres";
+    private readonly client;
+    private readonly table;
+    private readonly useAdvisoryLocks;
+    private readonly clock;
+    constructor(options: PostgresAdapterOptions);
+    get<T = unknown>(key: string): Promise<StoredRecord<T> | null>;
+    set<T = unknown>(key: string, value: StoredRecord<T>, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    compareAndSet<T = unknown>(key: string, expectedOwnerToken: string, newValue: StoredRecord<T>, ttlMs?: number): Promise<boolean>;
+    tryAdvisoryLock(key: string): Promise<boolean>;
+    releaseAdvisoryLock(key: string): Promise<void>;
+    capabilities(): {
+        transactions: boolean;
+        cas: boolean;
+        ttl: boolean;
+        advisoryLocks: boolean;
+    };
+    private _rowToRecord;
+}
+/**
+ * Create a PostgreSQL storage adapter.
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { createPostgresAdapter } from '@periodic/vanadium/adapters/postgres';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const adapter = createPostgresAdapter({ client: pool });
+ * ```
+ */
+export declare function createPostgresAdapter(options: PostgresAdapterOptions): PostgresAdapter;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/types/adapters/postgres/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adapters/postgres/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAMzE,UAAU,WAAW;IACnB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CACxF;AAKD,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,MAAM,EAAE,WAAW,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,WAAW,GAAG;YAAE,OAAO,EAAE,MAAM,IAAI,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;IACzF,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAkBD,qBAAa,eAAgB,YAAW,cAAc;IACpD,SAAgB,IAAI,cAAc;IAElC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,OAAO,EAAE,sBAAsB;IAkBrC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAW9D,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCpF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASlC,aAAa,CAAC,CAAC,GAAG,OAAO,EAC7B,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,MAAM,EAC1B,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,EACzB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;IAsCb,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW9C,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYrD,YAAY;;;;;;IAWZ,OAAO,CAAC,YAAY;CAarB;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAEtF"}