@portel/photon-core 2.8.3 → 2.9.0

package/dist/middleware.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Extensible Middleware System
+ *
+ * Every functional tag (@cached, @timeout, @retryable, etc.) is a MiddlewareDefinition.
+ * Custom middleware uses the same API via @use tag + defineMiddleware().
+ *
+ * Pipeline assembly: declarations sorted by phase, composed inner→outer.
+ * Lower phase = outer wrapper (executes first, returns last).
+ */
+export interface MiddlewareContext {
+    photon: string;
+    tool: string;
+    instance: string;
+    params: any;
+}
+export type NextFn = () => Promise<any>;
+export type MiddlewareHandler = (ctx: MiddlewareContext, next: NextFn) => Promise<any>;
+export interface MiddlewareDefinition<C = Record<string, any>> {
+    name: string;
+    /** Ordering — lower = outer (executes first). Default: 45 */
+    phase?: number;
+    /** Parse shorthand sugar like @cached 5m */
+    parseShorthand?(value: string): C;
+    /** Parse inline {@prop value} config */
+    parseConfig?(raw: Record<string, string>): C;
+    /** Create a handler from parsed config */
+    create(config: C, state: MiddlewareState): MiddlewareHandler;
+}
+export interface MiddlewareState {
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    delete(key: string): boolean;
+}
+/** Stored on ExtractedSchema per-tool */
+export interface MiddlewareDeclaration {
+    name: string;
+    config: Record<string, any>;
+    phase: number;
+}
+export declare function createStateStore(): MiddlewareState;
+export declare class MiddlewareRegistry {
+    private definitions;
+    register(def: MiddlewareDefinition): void;
+    get(name: string): MiddlewareDefinition | undefined;
+    has(name: string): boolean;
+    names(): string[];
+}
+export declare function defineMiddleware<C = Record<string, any>>(def: MiddlewareDefinition<C>): MiddlewareDefinition<C>;
+/** Hash parameters for cache key */
+export declare function hashParams(params: any): string;
+/** Built-in validators for @validate tag */
+export declare const BUILT_IN_VALIDATORS: Record<string, (value: any) => boolean>;
+export declare const builtinRegistry: MiddlewareRegistry;
+/**
+ * Build a middleware chain from declarations.
+ *
+ * Sort by phase (ascending), then reverse for wrapping:
+ *   chain = actualExecution
+ *   for each declaration (highest phase first → wraps innermost):
+ *     handler = definition.create(config, stateStore)
+ *     prev = chain
+ *     chain = () => handler(ctx, prev)
+ *
+ * Result: lowest phase runs outermost (executes first).
+ */
+export declare function buildMiddlewareChain(execute: () => Promise<any>, declarations: MiddlewareDeclaration[], registry: MiddlewareRegistry, stateStores: Map<string, MiddlewareState>, ctx: MiddlewareContext, 
+/** Optional overrides for specific middleware (e.g., locked with real lock impl) */
+handlerOverrides?: Map<string, (config: any, state: MiddlewareState) => MiddlewareHandler>): () => Promise<any>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,GAAG,CAAC;CACb;AAED,MAAM,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;AACxC,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAEvF,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,cAAc,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC;IAClC,wCAAwC;IACxC,WAAW,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7C,0CAA0C;IAC1C,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,eAAe,GAAG,iBAAiB,CAAC;CAC9D;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IACnC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACpC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AAED,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf;AAMD,wBAAgB,gBAAgB,IAAI,eAAe,CAalD;AAMD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,WAAW,CAA2C;IAE9D,QAAQ,CAAC,GAAG,EAAE,oBAAoB,GAAG,IAAI;IAIzC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAInD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,KAAK,IAAI,MAAM,EAAE;CAGlB;AAMD,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACtD,GAAG,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC3B,oBAAoB,CAAC,CAAC,CAAC,CAYzB;AAMD,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,MAAM,EAAE,GAAG,GAAG,MAAM,CAU9C;AAQD,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAWvE,CAAC;AAkeF,eAAO,MAAM,eAAe,oBAA2B,CAAC;AAiBxD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,EAC3B,YAAY,EAAE,qBAAqB,EAAE,EACrC,QAAQ,EAAE,kBAAkB,EAC5B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,GAAG,EAAE,iBAAiB;AACtB,oFAAoF;AACpF,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,eAAe,KAAK,iBAAiB,CAAC,GACzF,MAAM,OAAO,CAAC,GAAG,CAAC,CA4CpB"}

package/dist/middleware.js

@@ -0,0 +1,570 @@
+/**
+ * Extensible Middleware System
+ *
+ * Every functional tag (@cached, @timeout, @retryable, etc.) is a MiddlewareDefinition.
+ * Custom middleware uses the same API via @use tag + defineMiddleware().
+ *
+ * Pipeline assembly: declarations sorted by phase, composed inner→outer.
+ * Lower phase = outer wrapper (executes first, returns last).
+ */
+import * as crypto from 'crypto';
+import { parseDuration, parseRate } from './utils/duration.js';
+// ═══════════════════════════════════════════════════════════════════════════════
+// STATE STORE
+// ═══════════════════════════════════════════════════════════════════════════════
+export function createStateStore() {
+    const store = new Map();
+    return {
+        get(key) {
+            return store.get(key);
+        },
+        set(key, value) {
+            store.set(key, value);
+        },
+        delete(key) {
+            return store.delete(key);
+        },
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// REGISTRY
+// ═══════════════════════════════════════════════════════════════════════════════
+export class MiddlewareRegistry {
+    definitions = new Map();
+    register(def) {
+        this.definitions.set(def.name, def);
+    }
+    get(name) {
+        return this.definitions.get(name);
+    }
+    has(name) {
+        return this.definitions.has(name);
+    }
+    names() {
+        return [...this.definitions.keys()];
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// DEFINE MIDDLEWARE
+// ═══════════════════════════════════════════════════════════════════════════════
+export function defineMiddleware(def) {
+    if (!def.name) {
+        throw new Error('MiddlewareDefinition requires a name');
+    }
+    if (typeof def.create !== 'function') {
+        throw new Error(`MiddlewareDefinition '${def.name}' requires a create function`);
+    }
+    // Apply default phase
+    if (def.phase === undefined) {
+        def.phase = 45;
+    }
+    return Object.freeze(def);
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELPERS (moved from loader.ts)
+// ═══════════════════════════════════════════════════════════════════════════════
+/** Hash parameters for cache key */
+export function hashParams(params) {
+    try {
+        return crypto
+            .createHash('sha256')
+            .update(JSON.stringify(params || {}))
+            .digest('hex')
+            .slice(0, 12);
+    }
+    catch {
+        return 'nohash';
+    }
+}
+/** Get nested value from object by dot path */
+function getNestedValue(obj, path) {
+    if (!obj || typeof obj !== 'object')
+        return undefined;
+    return path.split('.').reduce((o, key) => o?.[key], obj);
+}
+/** Built-in validators for @validate tag */
+export const BUILT_IN_VALIDATORS = {
+    'a valid email': (v) => typeof v === 'string' && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v),
+    'a valid url': (v) => typeof v === 'string' && /^https?:\/\/.+/.test(v),
+    positive: (v) => typeof v === 'number' && v > 0,
+    'non-negative': (v) => typeof v === 'number' && v >= 0,
+    'non-empty': (v) => v !== null && v !== undefined && v !== '' && (!Array.isArray(v) || v.length > 0),
+    'a valid uuid': (v) => typeof v === 'string' &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v),
+    'an integer': (v) => typeof v === 'number' && Number.isInteger(v),
+};
+// --- fallback (phase 3) ---
+const fallbackMiddleware = defineMiddleware({
+    name: 'fallback',
+    phase: 3,
+    parseShorthand(value) {
+        return { value: parseFallbackValue(value), warn: false };
+    },
+    parseConfig(raw) {
+        return {
+            value: raw.value !== undefined ? parseFallbackValue(raw.value) : null,
+            warn: raw.warn === 'true' || raw.warn === 'yes',
+        };
+    },
+    create(config, _state) {
+        return async (ctx, next) => {
+            try {
+                return await next();
+            }
+            catch (error) {
+                if (config.warn) {
+                    console.error(`[fallback] ${ctx.photon}.${ctx.tool} failed: ${error instanceof Error ? error.message : String(error)} — returning default`);
+                }
+                return config.value;
+            }
+        };
+    },
+});
+/** Parse a fallback value string into a JS value */
+function parseFallbackValue(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === 'null')
+        return null;
+    if (trimmed === 'undefined')
+        return undefined;
+    if (trimmed === 'true')
+        return true;
+    if (trimmed === 'false')
+        return false;
+    // Try JSON parse (handles [], {}, numbers, quoted strings)
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // Fall back to raw string
+        return trimmed;
+    }
+}
+// --- logged (phase 5) ---
+const loggedMiddleware = defineMiddleware({
+    name: 'logged',
+    phase: 5,
+    parseShorthand(value) {
+        const level = value.trim() || 'info';
+        return { level, tags: [] };
+    },
+    parseConfig(raw) {
+        return {
+            level: raw.level || 'info',
+            tags: raw.tags ? raw.tags.split(',').map((t) => t.trim()) : [],
+        };
+    },
+    create(config, _state) {
+        return async (ctx, next) => {
+            const start = Date.now();
+            try {
+                const result = await next();
+                const duration = Date.now() - start;
+                const tagStr = config.tags.length > 0 ? ` [${config.tags.join(',')}]` : '';
+                console.error(`[${config.level}] ${ctx.photon}.${ctx.tool}${tagStr} ${duration}ms`);
+                return result;
+            }
+            catch (error) {
+                const duration = Date.now() - start;
+                const tagStr = config.tags.length > 0 ? ` [${config.tags.join(',')}]` : '';
+                const msg = error instanceof Error ? error.message : String(error);
+                console.error(`[${config.level}] ${ctx.photon}.${ctx.tool}${tagStr} FAILED ${duration}ms — ${msg}`);
+                throw error;
+            }
+        };
+    },
+});
+const circuitBreakerMiddleware = defineMiddleware({
+    name: 'circuitBreaker',
+    phase: 8,
+    parseShorthand(value) {
+        const parts = value.trim().split(/\s+/);
+        const threshold = parseInt(parts[0], 10) || 5;
+        const resetAfterMs = parts[1] ? parseDuration(parts[1]) : 30_000;
+        return { threshold, resetAfterMs };
+    },
+    parseConfig(raw) {
+        return {
+            threshold: parseInt(raw.threshold || '5', 10),
+            resetAfterMs: raw.resetAfter ? parseDuration(raw.resetAfter) : 30_000,
+        };
+    },
+    create(config, state) {
+        return async (ctx, next) => {
+            const key = `${ctx.photon}:${ctx.instance}:${ctx.tool}`;
+            let circuit = state.get(key);
+            if (!circuit) {
+                circuit = { failures: 0, state: 'closed', openedAt: 0 };
+                state.set(key, circuit);
+            }
+            // OPEN → check if reset period elapsed
+            if (circuit.state === 'open') {
+                if (Date.now() - circuit.openedAt >= config.resetAfterMs) {
+                    circuit.state = 'half-open';
+                }
+                else {
+                    const error = new Error(`Circuit open: ${ctx.photon}.${ctx.tool} has failed ${config.threshold} consecutive times. Resets in ${Math.ceil((config.resetAfterMs - (Date.now() - circuit.openedAt)) / 1000)}s`);
+                    error.name = 'PhotonCircuitOpenError';
+                    throw error;
+                }
+            }
+            try {
+                const result = await next();
+                // Success → reset circuit
+                circuit.failures = 0;
+                circuit.state = 'closed';
+                return result;
+            }
+            catch (error) {
+                circuit.failures++;
+                if (circuit.failures >= config.threshold) {
+                    circuit.state = 'open';
+                    circuit.openedAt = Date.now();
+                }
+                throw error;
+            }
+        };
+    },
+});
+// --- throttled (phase 10) ---
+const throttledMiddleware = defineMiddleware({
+    name: 'throttled',
+    phase: 10,
+    parseShorthand(value) {
+        return parseRate(value);
+    },
+    parseConfig(raw) {
+        if (raw.rate) {
+            return parseRate(raw.rate);
+        }
+        return {
+            count: parseInt(raw.count || '10', 10),
+            windowMs: raw.window ? parseDuration(raw.window) : 60_000,
+        };
+    },
+    create(config, state) {
+        return async (ctx, next) => {
+            const key = `${ctx.photon}:${ctx.instance}:${ctx.tool}`;
+            const now = Date.now();
+            let entry = state.get(key);
+            if (!entry) {
+                entry = { timestamps: [] };
+                state.set(key, entry);
+            }
+            // Prune old timestamps
+            entry.timestamps = entry.timestamps.filter((t) => now - t < config.windowMs);
+            if (entry.timestamps.length >= config.count) {
+                const error = new Error(`Rate limited: ${ctx.photon}.${ctx.tool} exceeds ${config.count} calls per ${config.windowMs}ms`);
+                error.name = 'PhotonRateLimitError';
+                throw error;
+            }
+            entry.timestamps.push(now);
+            return next();
+        };
+    },
+});
+// --- debounced (phase 20) ---
+const debouncedMiddleware = defineMiddleware({
+    name: 'debounced',
+    phase: 20,
+    parseShorthand(value) {
+        return { delay: parseDuration(value) };
+    },
+    parseConfig(raw) {
+        return { delay: raw.delay ? parseDuration(raw.delay) : 500 };
+    },
+    create(config, state) {
+        return async (ctx, next) => {
+            const key = `${ctx.photon}:${ctx.instance}:${ctx.tool}`;
+            const existing = state.get(key);
+            if (existing) {
+                clearTimeout(existing.timer);
+                existing.reject(new Error('Debounced: superseded by newer call'));
+            }
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(async () => {
+                    state.delete(key);
+                    try {
+                        resolve(await next());
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                }, config.delay);
+                state.set(key, { timer, resolve, reject });
+            });
+        };
+    },
+});
+// --- cached (phase 30) ---
+const cachedMiddleware = defineMiddleware({
+    name: 'cached',
+    phase: 30,
+    parseShorthand(value) {
+        const ttl = parseDuration(value);
+        return { ttl: ttl || 300_000 };
+    },
+    parseConfig(raw) {
+        const config = {
+            ttl: raw.ttl ? parseDuration(raw.ttl) : 300_000,
+        };
+        if (raw.key)
+            config.key = raw.key;
+        return config;
+    },
+    create(config, state) {
+        return async (ctx, next) => {
+            const paramHash = config.key
+                ? getNestedValue(ctx.params, config.key)
+                : hashParams(ctx.params);
+            const cacheKey = `${ctx.photon}:${ctx.instance}:${ctx.tool}:${paramHash}`;
+            const cached = state.get(cacheKey);
+            if (cached && Date.now() - cached.timestamp < config.ttl) {
+                return cached.result;
+            }
+            const result = await next();
+            state.set(cacheKey, { result, timestamp: Date.now() });
+            return result;
+        };
+    },
+});
+// --- validate (phase 40) ---
+const validateMiddleware = defineMiddleware({
+    name: 'validate',
+    phase: 40,
+    parseConfig(raw) {
+        // Config comes pre-parsed from extractValidations
+        return { validations: [] };
+    },
+    create(config, _state) {
+        return async (ctx, next) => {
+            for (const { field, rule } of config.validations) {
+                const value = getNestedValue(ctx.params, field);
+                const ruleLower = rule.toLowerCase();
+                let valid = false;
+                let builtInMatched = false;
+                for (const [pattern, validator] of Object.entries(BUILT_IN_VALIDATORS)) {
+                    if (ruleLower.includes(pattern)) {
+                        valid = validator(value);
+                        builtInMatched = true;
+                        break;
+                    }
+                }
+                if (!builtInMatched && ruleLower.startsWith('must be ')) {
+                    valid = value !== null && value !== undefined && value !== '';
+                }
+                if (!valid) {
+                    const error = new Error(`Validation failed: ${field} ${rule} (got ${JSON.stringify(value)}) in ${ctx.photon}.${ctx.tool}`);
+                    error.name = 'PhotonValidationError';
+                    throw error;
+                }
+            }
+            return next();
+        };
+    },
+});
+// --- queued (phase 50) ---
+const queuedMiddleware = defineMiddleware({
+    name: 'queued',
+    phase: 50,
+    parseShorthand(value) {
+        return { concurrency: parseInt(value, 10) || 1 };
+    },
+    parseConfig(raw) {
+        return { concurrency: parseInt(raw.concurrency || '1', 10) };
+    },
+    create(config, state) {
+        return async (ctx, next) => {
+            const key = `${ctx.photon}:${ctx.instance}:${ctx.tool}`;
+            let queueState = state.get(key);
+            if (!queueState) {
+                queueState = { running: 0, queue: [] };
+                state.set(key, queueState);
+            }
+            const tryDequeue = () => {
+                const s = state.get(key);
+                if (!s)
+                    return;
+                while (s.running < config.concurrency && s.queue.length > 0) {
+                    const entry = s.queue.shift();
+                    s.running++;
+                    entry.fn().then((result) => {
+                        s.running--;
+                        entry.resolve(result);
+                        tryDequeue();
+                    }, (error) => {
+                        s.running--;
+                        entry.reject(error);
+                        tryDequeue();
+                    });
+                }
+            };
+            if (queueState.running < config.concurrency) {
+                queueState.running++;
+                return next().finally(() => {
+                    const s = state.get(key);
+                    if (s) {
+                        s.running--;
+                        tryDequeue();
+                    }
+                });
+            }
+            return new Promise((resolve, reject) => {
+                queueState.queue.push({ fn: next, resolve, reject });
+            });
+        };
+    },
+});
+// --- locked (phase 60) ---
+// Note: The actual lock implementation is injected from the loader since it depends
+// on the daemon's lock manager. This definition provides the structure.
+const lockedMiddleware = defineMiddleware({
+    name: 'locked',
+    phase: 60,
+    parseShorthand(value) {
+        return { name: value };
+    },
+    parseConfig(raw) {
+        return { name: raw.name || '' };
+    },
+    create(config, _state) {
+        // The actual withLock implementation is injected by the loader.
+        // At the photon-core level, we provide a passthrough that the loader overrides.
+        return async (ctx, next) => {
+            // Loader replaces this handler with one that calls withLockHelper
+            // If running without the loader, locks are a no-op
+            return next();
+        };
+    },
+});
+// --- timeout (phase 70) ---
+const timeoutMiddleware = defineMiddleware({
+    name: 'timeout',
+    phase: 70,
+    parseShorthand(value) {
+        return { ms: parseDuration(value) };
+    },
+    parseConfig(raw) {
+        return { ms: raw.ms ? parseDuration(raw.ms) : 30_000 };
+    },
+    create(config, _state) {
+        return async (ctx, next) => {
+            return Promise.race([
+                next(),
+                new Promise((_, reject) => {
+                    setTimeout(() => {
+                        const error = new Error(`Timeout: ${ctx.photon}.${ctx.tool} did not complete within ${config.ms}ms`);
+                        error.name = 'PhotonTimeoutError';
+                        reject(error);
+                    }, config.ms);
+                }),
+            ]);
+        };
+    },
+});
+// --- retryable (phase 80) ---
+const retryableMiddleware = defineMiddleware({
+    name: 'retryable',
+    phase: 80,
+    parseShorthand(value) {
+        const parts = value.trim().split(/\s+/);
+        const count = parseInt(parts[0], 10) || 3;
+        const delay = parts[1] ? parseDuration(parts[1]) : 1_000;
+        return { count, delay };
+    },
+    parseConfig(raw) {
+        return {
+            count: parseInt(raw.count || '3', 10),
+            delay: raw.delay ? parseDuration(raw.delay) : 1_000,
+        };
+    },
+    create(config, _state) {
+        return async (ctx, next) => {
+            let lastError;
+            for (let attempt = 0; attempt <= config.count; attempt++) {
+                try {
+                    return await next();
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error : new Error(String(error));
+                    if (attempt < config.count) {
+                        const backoffMs = config.delay * Math.pow(2, attempt);
+                        await new Promise((r) => setTimeout(r, backoffMs));
+                    }
+                }
+            }
+            throw lastError;
+        };
+    },
+});
+// ═══════════════════════════════════════════════════════════════════════════════
+// GLOBAL BUILT-IN REGISTRY
+// ═══════════════════════════════════════════════════════════════════════════════
+export const builtinRegistry = new MiddlewareRegistry();
+builtinRegistry.register(fallbackMiddleware);
+builtinRegistry.register(loggedMiddleware);
+builtinRegistry.register(circuitBreakerMiddleware);
+builtinRegistry.register(throttledMiddleware);
+builtinRegistry.register(debouncedMiddleware);
+builtinRegistry.register(cachedMiddleware);
+builtinRegistry.register(validateMiddleware);
+builtinRegistry.register(queuedMiddleware);
+builtinRegistry.register(lockedMiddleware);
+builtinRegistry.register(timeoutMiddleware);
+builtinRegistry.register(retryableMiddleware);
+// ═══════════════════════════════════════════════════════════════════════════════
+// PIPELINE ASSEMBLY
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Build a middleware chain from declarations.
+ *
+ * Sort by phase (ascending), then reverse for wrapping:
+ *   chain = actualExecution
+ *   for each declaration (highest phase first → wraps innermost):
+ *     handler = definition.create(config, stateStore)
+ *     prev = chain
+ *     chain = () => handler(ctx, prev)
+ *
+ * Result: lowest phase runs outermost (executes first).
+ */
+export function buildMiddlewareChain(execute, declarations, registry, stateStores, ctx, 
+/** Optional overrides for specific middleware (e.g., locked with real lock impl) */
+handlerOverrides) {
+    if (!declarations || declarations.length === 0) {
+        return execute;
+    }
+    // Resolve actual phases: use definition's phase if available (custom middleware
+    // defines its own phase, but schema extractor defaults to 45 for unknowns)
+    const resolved = declarations.map(decl => {
+        const def = registry.get(decl.name);
+        const phase = def?.phase !== undefined ? def.phase : decl.phase;
+        return { ...decl, phase };
+    });
+    // Stable sort by phase (preserves declaration order within same phase)
+    const sorted = resolved.sort((a, b) => a.phase - b.phase);
+    // Build chain: iterate reversed sorted list (highest phase = innermost wrapper)
+    let chain = execute;
+    for (let i = sorted.length - 1; i >= 0; i--) {
+        const decl = sorted[i];
+        const def = registry.get(decl.name);
+        if (!def) {
+            // Unknown middleware — skip with warning
+            continue;
+        }
+        // Get or create state store for this middleware
+        let state = stateStores.get(decl.name);
+        if (!state) {
+            state = createStateStore();
+            stateStores.set(decl.name, state);
+        }
+        // Check for handler override (e.g., locked middleware needs real lock manager)
+        const override = handlerOverrides?.get(decl.name);
+        const handler = override
+            ? override(decl.config, state)
+            : def.create(decl.config, state);
+        const prev = chain;
+        chain = () => handler(ctx, prev);
+    }
+    return chain;
+}
+//# sourceMappingURL=middleware.js.map