@cleocode/lafs 1.8.0

package/dist/src/budgetEnforcement.js

@@ -0,0 +1,328 @@
+/**
+ * LAFS Budget Enforcement
+ *
+ * Middleware for enforcing MVI (Minimal Viable Interface) token budgets on LAFS envelopes.
+ * Provides budget checking, truncation, and error generation for exceeded budgets.
+ */
+import { TokenEstimator } from "./tokenEstimator.js";
+/**
+ * Budget exceeded error code from LAFS error registry
+ */
+const BUDGET_EXCEEDED_CODE = "E_MVI_BUDGET_EXCEEDED";
+/**
+ * Default category for budget exceeded errors
+ */
+const BUDGET_ERROR_CATEGORY = "VALIDATION";
+/**
+ * Create a budget exceeded error object
+ */
+function createBudgetExceededError(estimated, budget) {
+    return {
+        code: BUDGET_EXCEEDED_CODE,
+        message: `Response exceeds declared MVI budget: estimated ${estimated} tokens, budget ${budget} tokens`,
+        category: BUDGET_ERROR_CATEGORY,
+        retryable: false,
+        retryAfterMs: null,
+        details: {
+            estimatedTokens: estimated,
+            budgetTokens: budget,
+            exceededBy: estimated - budget,
+            exceededByPercent: Math.round(((estimated - budget) / budget) * 100),
+        },
+    };
+}
+/**
+ * Truncate a result to fit within budget.
+ * Returns the truncated result and whether truncation occurred.
+ */
+function truncateResult(result, targetTokens, estimator) {
+    if (result === null) {
+        return { result: null, wasTruncated: false };
+    }
+    const currentEstimate = estimator.estimate(result);
+    // If already within budget, no truncation needed
+    if (currentEstimate <= targetTokens) {
+        return { result, wasTruncated: false };
+    }
+    // Calculate target size (conservative: assume 10% overhead)
+    const targetChars = Math.floor(targetTokens * 4 * 0.9);
+    if (Array.isArray(result)) {
+        return truncateArray(result, targetChars, targetTokens, estimator);
+    }
+    return truncateObject(result, targetChars, targetTokens, estimator);
+}
+/**
+ * Truncate an array to fit within budget.
+ */
+function truncateArray(arr, targetChars, targetTokens, estimator) {
+    if (arr.length === 0) {
+        return { result: arr, wasTruncated: false };
+    }
+    // Binary search to find how many items fit
+    let left = 0;
+    let right = arr.length;
+    let bestFit = 0;
+    while (left <= right) {
+        const mid = Math.floor((left + right) / 2);
+        const subset = arr.slice(0, mid);
+        const estimate = estimator.estimate(subset);
+        if (estimate <= targetTokens) {
+            bestFit = mid;
+            left = mid + 1;
+        }
+        else {
+            right = mid - 1;
+        }
+    }
+    // If we can fit all items, no truncation needed
+    if (bestFit >= arr.length) {
+        return { result: arr, wasTruncated: false };
+    }
+    // Create truncated result
+    const truncated = arr.slice(0, bestFit);
+    // If we couldn't fit any items, return minimal response
+    if (bestFit === 0 && arr.length > 0) {
+        return {
+            result: [{ _truncated: true, reason: "budget_exceeded" }],
+            wasTruncated: true
+        };
+    }
+    // Add truncation indicator to last element if it's an object
+    if (bestFit > 0 && typeof truncated[bestFit - 1] === 'object' && truncated[bestFit - 1] !== null) {
+        const lastItem = truncated[bestFit - 1];
+        truncated[bestFit - 1] = {
+            ...lastItem,
+            _truncated: true,
+            remainingItems: arr.length - bestFit,
+        };
+    }
+    return { result: truncated, wasTruncated: true };
+}
+/**
+ * Truncate an object to fit within budget.
+ */
+function truncateObject(obj, targetChars, targetTokens, estimator) {
+    const keys = Object.keys(obj);
+    if (keys.length === 0) {
+        return { result: obj, wasTruncated: false };
+    }
+    // Try to fit as many top-level properties as possible
+    let left = 0;
+    let right = keys.length;
+    let bestFit = 0;
+    while (left <= right) {
+        const mid = Math.floor((left + right) / 2);
+        const subsetKeys = keys.slice(0, mid);
+        const subset = {};
+        for (const key of subsetKeys) {
+            subset[key] = obj[key];
+        }
+        const estimate = estimator.estimate(subset);
+        if (estimate <= targetTokens) {
+            bestFit = mid;
+            left = mid + 1;
+        }
+        else {
+            right = mid - 1;
+        }
+    }
+    // If we can fit all properties, no truncation needed
+    if (bestFit >= keys.length) {
+        return { result: obj, wasTruncated: false };
+    }
+    // Create truncated result
+    const subsetKeys = keys.slice(0, bestFit);
+    const truncated = {};
+    for (const key of subsetKeys) {
+        truncated[key] = obj[key];
+    }
+    // If we couldn't fit any properties, return minimal response
+    if (bestFit === 0) {
+        return {
+            result: { _truncated: true, reason: "budget_exceeded" },
+            wasTruncated: true
+        };
+    }
+    // Add truncation metadata
+    truncated._truncated = true;
+    truncated._truncatedFields = keys.slice(bestFit);
+    return { result: truncated, wasTruncated: true };
+}
+/**
+ * Apply budget enforcement to an envelope.
+ *
+ * @param envelope - The LAFS envelope to check
+ * @param budget - Maximum allowed tokens
+ * @param options - Budget enforcement options
+ * @returns Enforce result with potentially modified envelope
+ */
+export function applyBudgetEnforcement(envelope, budget, options = {}) {
+    const { truncateOnExceed = false, onBudgetExceeded } = options;
+    const estimator = new TokenEstimator();
+    // Estimate the result payload
+    const estimatedTokens = estimator.estimate(envelope.result);
+    // Add estimate to metadata
+    const tokenEstimate = {
+        estimated: estimatedTokens,
+    };
+    // Check if within budget
+    const withinBudget = estimatedTokens <= budget;
+    // If within budget, just add the estimate to metadata
+    if (withinBudget) {
+        return {
+            envelope: {
+                ...envelope,
+                _meta: {
+                    ...envelope._meta,
+                    _tokenEstimate: tokenEstimate,
+                },
+            },
+            withinBudget: true,
+            estimatedTokens,
+            budget,
+            truncated: false,
+        };
+    }
+    // Budget exceeded - call callback if provided
+    if (onBudgetExceeded) {
+        onBudgetExceeded(estimatedTokens, budget);
+    }
+    // If truncation is enabled, try to truncate
+    if (truncateOnExceed) {
+        const { result, wasTruncated } = truncateResult(envelope.result, budget, estimator);
+        const truncatedEstimate = estimator.estimate(result);
+        if (truncatedEstimate <= budget) {
+            return {
+                envelope: {
+                    ...envelope,
+                    result,
+                    _meta: {
+                        ...envelope._meta,
+                        _tokenEstimate: {
+                            estimated: truncatedEstimate,
+                            truncated: true,
+                            originalEstimate: estimatedTokens,
+                        },
+                    },
+                },
+                withinBudget: true,
+                estimatedTokens: truncatedEstimate,
+                budget,
+                truncated: true,
+            };
+        }
+    }
+    // Return budget exceeded error
+    return {
+        envelope: {
+            ...envelope,
+            success: false,
+            result: null,
+            error: createBudgetExceededError(estimatedTokens, budget),
+            _meta: {
+                ...envelope._meta,
+                _tokenEstimate: tokenEstimate,
+            },
+        },
+        withinBudget: false,
+        estimatedTokens,
+        budget,
+        truncated: false,
+    };
+}
+/**
+ * Create a budget enforcement middleware function.
+ *
+ * @param budget - Maximum allowed tokens for response
+ * @param options - Budget enforcement options
+ * @returns Middleware function that enforces budget
+ *
+ * @example
+ * ```typescript
+ * const middleware = withBudget(1000, { truncateOnExceed: true });
+ * const result = await middleware(envelope, async () => nextEnvelope);
+ * ```
+ */
+export function withBudget(budget, options = {}) {
+    return async (envelope, next) => {
+        // Execute next middleware/handler
+        const result = await next();
+        // Apply budget enforcement to the result
+        const enforcement = applyBudgetEnforcement(result, budget, options);
+        return enforcement.envelope;
+    };
+}
+/**
+ * Check if an envelope has exceeded its budget without modifying it.
+ *
+ * @param envelope - The LAFS envelope to check
+ * @param budget - Maximum allowed tokens
+ * @returns Budget check result
+ */
+export function checkBudget(envelope, budget) {
+    const estimator = new TokenEstimator();
+    const estimated = estimator.estimate(envelope.result);
+    return {
+        exceeded: estimated > budget,
+        estimated,
+        remaining: Math.max(0, budget - estimated),
+    };
+}
+/**
+ * Synchronous version of withBudget for non-async contexts.
+ *
+ * @param budget - Maximum allowed tokens for response
+ * @param options - Budget enforcement options
+ * @returns Middleware function that enforces budget synchronously
+ */
+export function withBudgetSync(budget, options = {}) {
+    return (envelope, next) => {
+        const result = next();
+        const enforcement = applyBudgetEnforcement(result, budget, options);
+        return enforcement.envelope;
+    };
+}
+/**
+ * Higher-order function that wraps a handler with budget enforcement.
+ *
+ * @param handler - The handler function to wrap
+ * @param budget - Maximum allowed tokens
+ * @param options - Budget enforcement options
+ * @returns Wrapped handler with budget enforcement
+ *
+ * @example
+ * ```typescript
+ * const myHandler = async (request: Request) => ({ success: true, result: { data } });
+ * const budgetedHandler = wrapWithBudget(myHandler, 1000, { truncateOnExceed: true });
+ * const result = await budgetedHandler(request);
+ * ```
+ */
+export function wrapWithBudget(handler, budget, options = {}) {
+    return async (...args) => {
+        const result = await handler(...args);
+        const enforcement = applyBudgetEnforcement(result, budget, options);
+        return enforcement.envelope;
+    };
+}
+/**
+ * Compose multiple middleware functions into a single middleware.
+ * Middleware is executed in order (left to right).
+ */
+export function composeMiddleware(...middlewares) {
+    return async (envelope, next) => {
+        let index = 0;
+        async function dispatch(i) {
+            if (i >= middlewares.length) {
+                return next();
+            }
+            const middleware = middlewares[i];
+            if (!middleware) {
+                return dispatch(i + 1);
+            }
+            return middleware(envelope, () => dispatch(i + 1));
+        }
+        return dispatch(0);
+    };
+}
+export { TokenEstimator };
+export { BUDGET_EXCEEDED_CODE };

package/dist/src/circuit-breaker/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * LAFS Circuit Breaker Module
+ *
+ * Provides circuit breaker pattern for resilient service calls
+ */
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+export interface CircuitBreakerConfig {
+    name: string;
+    failureThreshold?: number;
+    resetTimeout?: number;
+    halfOpenMaxCalls?: number;
+    successThreshold?: number;
+}
+export interface CircuitBreakerMetrics {
+    state: CircuitState;
+    failures: number;
+    successes: number;
+    lastFailureTime?: Date;
+    consecutiveSuccesses: number;
+    totalCalls: number;
+}
+export declare class CircuitBreakerError extends Error {
+    constructor(message: string);
+}
+/**
+ * Circuit breaker for protecting against cascading failures
+ *
+ * @example
+ * ```typescript
+ * import { CircuitBreaker } from '@cleocode/lafs/circuit-breaker';
+ *
+ * const breaker = new CircuitBreaker({
+ *   name: 'external-api',
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000
+ * });
+ *
+ * try {
+ *   const result = await breaker.execute(async () => {
+ *     return await externalApi.call();
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerError) {
+ *     console.log('Circuit breaker is open');
+ *   }
+ * }
+ * ```
+ */
+export declare class CircuitBreaker {
+    private config;
+    private state;
+    private failures;
+    private successes;
+    private lastFailureTime?;
+    private consecutiveSuccesses;
+    private totalCalls;
+    private halfOpenCalls;
+    private resetTimer?;
+    constructor(config: CircuitBreakerConfig);
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get current circuit breaker state
+     */
+    getState(): CircuitState;
+    /**
+     * Get circuit breaker metrics
+     */
+    getMetrics(): CircuitBreakerMetrics;
+    /**
+     * Manually open the circuit breaker
+     */
+    forceOpen(): void;
+    /**
+     * Manually close the circuit breaker
+     */
+    forceClose(): void;
+    private onSuccess;
+    private onFailure;
+    private transitionTo;
+    private shouldAttemptReset;
+    private scheduleReset;
+    private reset;
+}
+/**
+ * Circuit breaker registry for managing multiple breakers
+ *
+ * @example
+ * ```typescript
+ * const registry = new CircuitBreakerRegistry();
+ *
+ * registry.add('payment-api', {
+ *   failureThreshold: 3,
+ *   resetTimeout: 60000
+ * });
+ *
+ * const paymentBreaker = registry.get('payment-api');
+ * ```
+ */
+export declare class CircuitBreakerRegistry {
+    private breakers;
+    add(name: string, config: Omit<CircuitBreakerConfig, 'name'>): CircuitBreaker;
+    get(name: string): CircuitBreaker | undefined;
+    getOrCreate(name: string, config: Omit<CircuitBreakerConfig, 'name'>): CircuitBreaker;
+    getAllMetrics(): Record<string, CircuitBreakerMetrics>;
+    resetAll(): void;
+}
+/**
+ * Create a circuit breaker middleware for Express
+ *
+ * @example
+ * ```typescript
+ * app.use('/external-api', circuitBreakerMiddleware({
+ *   name: 'external-api',
+ *   failureThreshold: 5
+ * }));
+ * ```
+ */
+export declare function circuitBreakerMiddleware(config: CircuitBreakerConfig): (req: any, res: any, next: any) => Promise<void>;

package/dist/src/circuit-breaker/index.js

@@ -0,0 +1,249 @@
+/**
+ * LAFS Circuit Breaker Module
+ *
+ * Provides circuit breaker pattern for resilient service calls
+ */
+export class CircuitBreakerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CircuitBreakerError';
+    }
+}
+/**
+ * Circuit breaker for protecting against cascading failures
+ *
+ * @example
+ * ```typescript
+ * import { CircuitBreaker } from '@cleocode/lafs/circuit-breaker';
+ *
+ * const breaker = new CircuitBreaker({
+ *   name: 'external-api',
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000
+ * });
+ *
+ * try {
+ *   const result = await breaker.execute(async () => {
+ *     return await externalApi.call();
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerError) {
+ *     console.log('Circuit breaker is open');
+ *   }
+ * }
+ * ```
+ */
+export class CircuitBreaker {
+    config;
+    state = 'CLOSED';
+    failures = 0;
+    successes = 0;
+    lastFailureTime;
+    consecutiveSuccesses = 0;
+    totalCalls = 0;
+    halfOpenCalls = 0;
+    resetTimer;
+    constructor(config) {
+        this.config = config;
+        this.config = {
+            failureThreshold: 5,
+            resetTimeout: 30000,
+            halfOpenMaxCalls: 3,
+            successThreshold: 2,
+            ...config
+        };
+    }
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    async execute(fn) {
+        this.totalCalls++;
+        if (this.state === 'OPEN') {
+            if (this.shouldAttemptReset()) {
+                this.transitionTo('HALF_OPEN');
+            }
+            else {
+                throw new CircuitBreakerError(`Circuit breaker '${this.config.name}' is OPEN`);
+            }
+        }
+        if (this.state === 'HALF_OPEN') {
+            if (this.halfOpenCalls >= (this.config.halfOpenMaxCalls || 3)) {
+                throw new CircuitBreakerError(`Circuit breaker '${this.config.name}' is HALF_OPEN (max calls reached)`);
+            }
+            this.halfOpenCalls++;
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    /**
+     * Get current circuit breaker state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get circuit breaker metrics
+     */
+    getMetrics() {
+        return {
+            state: this.state,
+            failures: this.failures,
+            successes: this.successes,
+            lastFailureTime: this.lastFailureTime,
+            consecutiveSuccesses: this.consecutiveSuccesses,
+            totalCalls: this.totalCalls
+        };
+    }
+    /**
+     * Manually open the circuit breaker
+     */
+    forceOpen() {
+        this.transitionTo('OPEN');
+    }
+    /**
+     * Manually close the circuit breaker
+     */
+    forceClose() {
+        this.transitionTo('CLOSED');
+        this.reset();
+    }
+    onSuccess() {
+        this.successes++;
+        this.consecutiveSuccesses++;
+        if (this.state === 'HALF_OPEN') {
+            if (this.consecutiveSuccesses >= (this.config.successThreshold || 2)) {
+                this.transitionTo('CLOSED');
+                this.reset();
+            }
+        }
+    }
+    onFailure() {
+        this.failures++;
+        this.consecutiveSuccesses = 0;
+        this.lastFailureTime = new Date();
+        if (this.state === 'HALF_OPEN') {
+            this.transitionTo('OPEN');
+            this.scheduleReset();
+        }
+        else if (this.state === 'CLOSED') {
+            if (this.failures >= (this.config.failureThreshold || 5)) {
+                this.transitionTo('OPEN');
+                this.scheduleReset();
+            }
+        }
+    }
+    transitionTo(newState) {
+        console.log(`Circuit breaker '${this.config.name}': ${this.state} -> ${newState}`);
+        this.state = newState;
+        if (newState === 'HALF_OPEN') {
+            this.halfOpenCalls = 0;
+        }
+    }
+    shouldAttemptReset() {
+        if (!this.lastFailureTime)
+            return true;
+        const elapsed = Date.now() - this.lastFailureTime.getTime();
+        return elapsed >= (this.config.resetTimeout || 30000);
+    }
+    scheduleReset() {
+        if (this.resetTimer) {
+            clearTimeout(this.resetTimer);
+        }
+        this.resetTimer = setTimeout(() => {
+            if (this.state === 'OPEN') {
+                this.transitionTo('HALF_OPEN');
+            }
+        }, this.config.resetTimeout || 30000);
+    }
+    reset() {
+        this.failures = 0;
+        this.consecutiveSuccesses = 0;
+        this.halfOpenCalls = 0;
+        if (this.resetTimer) {
+            clearTimeout(this.resetTimer);
+            this.resetTimer = undefined;
+        }
+    }
+}
+/**
+ * Circuit breaker registry for managing multiple breakers
+ *
+ * @example
+ * ```typescript
+ * const registry = new CircuitBreakerRegistry();
+ *
+ * registry.add('payment-api', {
+ *   failureThreshold: 3,
+ *   resetTimeout: 60000
+ * });
+ *
+ * const paymentBreaker = registry.get('payment-api');
+ * ```
+ */
+export class CircuitBreakerRegistry {
+    breakers = new Map();
+    add(name, config) {
+        const breaker = new CircuitBreaker({ ...config, name });
+        this.breakers.set(name, breaker);
+        return breaker;
+    }
+    get(name) {
+        return this.breakers.get(name);
+    }
+    getOrCreate(name, config) {
+        let breaker = this.breakers.get(name);
+        if (!breaker) {
+            breaker = this.add(name, config);
+        }
+        return breaker;
+    }
+    getAllMetrics() {
+        const metrics = {};
+        this.breakers.forEach((breaker, name) => {
+            metrics[name] = breaker.getMetrics();
+        });
+        return metrics;
+    }
+    resetAll() {
+        this.breakers.forEach(breaker => breaker.forceClose());
+    }
+}
+/**
+ * Create a circuit breaker middleware for Express
+ *
+ * @example
+ * ```typescript
+ * app.use('/external-api', circuitBreakerMiddleware({
+ *   name: 'external-api',
+ *   failureThreshold: 5
+ * }));
+ * ```
+ */
+export function circuitBreakerMiddleware(config) {
+    const breaker = new CircuitBreaker(config);
+    return async (req, res, next) => {
+        try {
+            await breaker.execute(async () => {
+                next();
+            });
+        }
+        catch (error) {
+            if (error instanceof CircuitBreakerError) {
+                res.status(503).json({
+                    error: 'Service temporarily unavailable',
+                    reason: 'Circuit breaker is open'
+                });
+            }
+            else {
+                throw error;
+            }
+        }
+    };
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * LAFS Conformance CLI — diagnostic/human-readable tool.
+ *
+ * This CLI is a **diagnostic utility** that validates envelopes and flags
+ * against the LAFS schema and conformance checks. It is NOT itself a
+ * LAFS-conformant envelope producer. Its output is for human consumption
+ * and CI pipelines, not for machine-to-machine chaining.
+ *
+ * Exemption: The CLI is exempt from LAFS envelope conformance requirements.
+ * Its output format is not a LAFS envelope and MUST NOT be validated as one.
+ *
+ * @task T042
+ * @epic T034
+ */
+export {};