@cleocode/lafs-protocol 0.1.1 → 1.0.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/cli.d.ts

@@ -1,2 +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 {};

package/dist/src/cli.js

@@ -1,4 +1,18 @@
 #!/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
+ */
 import { readFile } from "node:fs/promises";
 import { runEnvelopeConformance, runFlagConformance } from "./conformance.js";
 function parseArgs(argv) {

package/dist/src/conformance.js

@@ -12,17 +12,79 @@ export function runEnvelopeConformance(envelope) {
         return { ok: false, checks };
     }
     const typed = envelope;
-    const invariant = typed.success ? typed.error === null : typed.result === null;
-    pushCheck(checks, "envelope_invariants", invariant, invariant ? undefined : "success/result/error invariant violated");
+    // envelope_invariants: success=true allows error to be null OR omitted;
+    // success=false requires error to be a non-null object and result===null.
+    const invariant = typed.success
+        ? typed.error == null // null or undefined (omitted) both valid for success
+        : typed.result === null && typed.error != null;
+    pushCheck(checks, "envelope_invariants", invariant, invariant
+        ? undefined
+        : typed.success
+            ? "success=true but error is present and non-null"
+            : "success=false requires result===null and error to be a non-null object");
+    // error_code_registered: only checked when error is present (error is optional when success=true)
     if (typed.error) {
         const registered = isRegisteredErrorCode(typed.error.code);
         pushCheck(checks, "error_code_registered", registered, registered ? undefined : `unregistered code: ${typed.error.code}`);
     }
     else {
-        pushCheck(checks, "error_code_registered", true);
+        pushCheck(checks, "error_code_registered", true, "error field absent or null — skipped (optional when success=true)");
     }
-    pushCheck(checks, "meta_mvi_present", typeof typed._meta.mvi === "boolean");
+    const validMviLevels = ["minimal", "standard", "full", "custom"];
+    pushCheck(checks, "meta_mvi_present", validMviLevels.includes(typed._meta.mvi), validMviLevels.includes(typed._meta.mvi) ? undefined : `invalid mvi level: ${String(typed._meta.mvi)}`);
     pushCheck(checks, "meta_strict_present", typeof typed._meta.strict === "boolean");
+    // strict_mode_behavior: when strict=true, the envelope MUST NOT contain
+    // explicit null for optional fields that can be omitted (page, error on success).
+    if (typed._meta.strict) {
+        const obj = envelope;
+        const hasExplicitNullError = typed.success && "error" in obj && obj["error"] === null;
+        const hasExplicitNullPage = "page" in obj && obj["page"] === null;
+        const strictClean = !hasExplicitNullError && !hasExplicitNullPage;
+        pushCheck(checks, "strict_mode_behavior", strictClean, strictClean
+            ? undefined
+            : "strict mode: optional fields should be omitted rather than set to null");
+    }
+    // pagination_mode_consistent: when page is present and is an object, verify
+    // that the fields present match the declared pagination mode.
+    if (typed.page && typeof typed.page === "object") {
+        const page = typed.page;
+        const mode = page["mode"];
+        let consistent = true;
+        let detail;
+        if (mode === "cursor") {
+            if (page["offset"] !== undefined) {
+                consistent = false;
+                detail = "cursor mode should not include offset field";
+            }
+        }
+        else if (mode === "offset") {
+            if (page["nextCursor"] !== undefined) {
+                consistent = false;
+                detail = "offset mode should not include nextCursor field";
+            }
+        }
+        else if (mode === "none") {
+            const extraFields = Object.keys(page).filter((k) => k !== "mode");
+            if (extraFields.length > 0) {
+                consistent = false;
+                detail = `none mode should only have mode field, found: ${extraFields.join(", ")}`;
+            }
+        }
+        pushCheck(checks, "pagination_mode_consistent", consistent, consistent ? undefined : detail);
+    }
+    // strict_mode_enforced: verify the schema enforces additional-property rules.
+    // When strict=true, extra top-level properties must be rejected by validation.
+    // When strict=false, extra top-level properties must be allowed.
+    {
+        const extraPropEnvelope = { ...envelope, _unknown_extra: true };
+        const extraResult = validateEnvelope(extraPropEnvelope);
+        if (typed._meta.strict) {
+            pushCheck(checks, "strict_mode_enforced", !extraResult.valid, extraResult.valid ? "strict=true but additional properties were accepted" : undefined);
+        }
+        else {
+            pushCheck(checks, "strict_mode_enforced", extraResult.valid, !extraResult.valid ? "strict=false but additional properties were rejected" : undefined);
+        }
+    }
     return { ok: checks.every((check) => check.pass), checks };
 }
 export function runFlagConformance(flags) {
@@ -30,13 +92,24 @@ export function runFlagConformance(flags) {
     try {
         const resolved = resolveOutputFormat(flags);
         pushCheck(checks, "flag_conflict_rejected", !(flags.humanFlag && flags.jsonFlag));
-        pushCheck(checks, "json_default_when_unspecified", resolved.format === "json" || Boolean(flags.projectDefault || flags.userDefault));
+        // Protocol-default check: when nothing is specified (source === "default"),
+        // the protocol requires JSON as the default format.
+        const isProtocolDefault = resolved.source === "default";
+        pushCheck(checks, "json_protocol_default", !isProtocolDefault || resolved.format === "json", isProtocolDefault && resolved.format !== "json"
+            ? `protocol default should be json, got ${resolved.format}`
+            : undefined);
+        // Config-override check: when a project or user default is active,
+        // the resolved format must match the config-provided value.
+        const hasConfigOverride = resolved.source === "project" || resolved.source === "user";
+        const expectedOverride = resolved.source === "project" ? flags.projectDefault : flags.userDefault;
+        pushCheck(checks, "config_override_respected", !hasConfigOverride || resolved.format === expectedOverride, hasConfigOverride && resolved.format !== expectedOverride
+            ? `config override expected ${String(expectedOverride)}, got ${resolved.format}`
+            : undefined);
     }
     catch (error) {
         if (error instanceof LAFSFlagError && error.code === "E_FORMAT_CONFLICT") {
             pushCheck(checks, "flag_conflict_rejected", true);
-            pushCheck(checks, "json_default_when_unspecified", true);
-            return { ok: true, checks };
+            return { ok: checks.every((check) => check.pass), checks };
         }
         pushCheck(checks, "flag_resolution", false, error instanceof Error ? error.message : String(error));
         return { ok: false, checks };

package/dist/src/discovery.d.ts

@@ -0,0 +1,127 @@
+/**
+ * LAFS Agent Discovery - Express/Fastify Middleware
+ * Serves discovery document at /.well-known/lafs.json
+ */
+import type { RequestHandler } from "express";
+/**
+ * Capability definition for service advertisement
+ */
+export interface Capability {
+    name: string;
+    version: string;
+    description?: string;
+    operations: string[];
+    optional?: boolean;
+}
+/**
+ * Service configuration for discovery document
+ */
+export interface ServiceConfig {
+    name: string;
+    version: string;
+    description?: string;
+}
+/**
+ * Endpoint configuration for discovery document
+ */
+export interface EndpointConfig {
+    envelope: string;
+    context?: string;
+    discovery: string;
+}
+/**
+ * Complete discovery document served at /.well-known/lafs.json
+ */
+export interface DiscoveryDocument {
+    $schema: string;
+    lafs_version: string;
+    service: ServiceConfig;
+    capabilities: Capability[];
+    endpoints: EndpointConfig;
+}
+/**
+ * Configuration for the discovery middleware
+ */
+export interface DiscoveryConfig {
+    /** Service information */
+    service: ServiceConfig;
+    /** List of capabilities this service provides */
+    capabilities: Capability[];
+    /** Endpoint URLs - can be relative paths or absolute URLs */
+    endpoints: {
+        /** URL for envelope submission endpoint */
+        envelope: string;
+        /** Optional URL for context ledger endpoint */
+        context?: string;
+        /** URL for this discovery document (usually auto-detected) */
+        discovery?: string;
+    };
+    /** Cache duration in seconds (default: 3600) */
+    cacheMaxAge?: number;
+    /** LAFS protocol version (default: "1.0.0") */
+    lafsVersion?: string;
+    /** Schema URL override */
+    schemaUrl?: string;
+    /** Base URL for constructing absolute URLs */
+    baseUrl?: string;
+    /** Optional custom headers to include in response */
+    headers?: Record<string, string>;
+}
+/**
+ * Discovery middleware options
+ */
+export interface DiscoveryMiddlewareOptions {
+    /** Path to serve discovery document (default: /.well-known/lafs.json) */
+    path?: string;
+    /** Enable HEAD requests (default: true) */
+    enableHead?: boolean;
+    /** Enable ETag caching (default: true) */
+    enableEtag?: boolean;
+}
+/**
+ * Create Express middleware for serving LAFS discovery document
+ *
+ * @param config - Discovery configuration
+ * @param options - Middleware options
+ * @returns Express RequestHandler
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import { discoveryMiddleware } from "./discovery.js";
+ *
+ * const app = express();
+ *
+ * app.use(discoveryMiddleware({
+ *   service: {
+ *     name: "my-lafs-service",
+ *     version: "1.0.0",
+ *     description: "A LAFS-compliant API service"
+ *   },
+ *   capabilities: [
+ *     {
+ *       name: "envelope-processor",
+ *       version: "1.0.0",
+ *       operations: ["process", "validate"],
+ *       description: "Process LAFS envelopes"
+ *     }
+ *   ],
+ *   endpoints: {
+ *     envelope: "/api/v1/envelope",
+ *     context: "/api/v1/context"
+ *   }
+ * }));
+ * ```
+ */
+export declare function discoveryMiddleware(config: DiscoveryConfig, options?: DiscoveryMiddlewareOptions): RequestHandler;
+/**
+ * Fastify plugin for LAFS discovery (for Fastify users)
+ *
+ * @param fastify - Fastify instance
+ * @param options - Plugin options
+ */
+export declare function discoveryFastifyPlugin(fastify: unknown, options: {
+    config: DiscoveryConfig;
+    path?: string;
+}): Promise<void>;
+export default discoveryMiddleware;