@cleocode/lafs 2026.4.0 → 2026.4.3

package/dist/src/flagSemantics.js

@@ -1,10 +1,56 @@
+/**
+ * Flag semantics for LAFS output format resolution.
+ *
+ * Implements the precedence chain defined in LAFS spec sections 5.1-5.3:
+ * explicit flag > project config > user config > TTY detection > default (json).
+ *
+ * @remarks
+ * This module is the single-layer resolver for format flags. For cross-layer
+ * resolution that also includes field extraction, use {@link resolveFlags} from
+ * `flagResolver.ts`.
+ *
+ * @since 1.0.0
+ */
 import { getRegistryCode } from './errorRegistry.js';
+/**
+ * Error thrown when LAFS flag validation fails.
+ *
+ * @remarks
+ * Wraps a registered LAFS error code with category and retryability information
+ * looked up from the error registry. The most common error is `E_FORMAT_CONFLICT`
+ * when `--human` and `--json` are used together.
+ */
 export class LAFSFlagError extends Error {
+    /** The LAFS error code (e.g. `'E_FORMAT_CONFLICT'`). */
     code;
+    /** The error category resolved from the error registry. */
     category;
+    /** Whether the operation that produced this error can be retried. */
     retryable;
+    /** Milliseconds to wait before retrying, or `null` if not applicable. */
     retryAfterMs;
+    /** Additional structured details about the error. */
     details;
+    /**
+     * Create a new LAFSFlagError.
+     *
+     * @param code - A registered LAFS error code (e.g. `'E_FORMAT_CONFLICT'`)
+     * @param message - Human-readable description of the error
+     * @param details - Optional structured details to attach to the error
+     *
+     * @remarks
+     * Looks up the error code in the LAFS error registry to populate
+     * `category` and `retryable`. Falls back to `'CONTRACT'` category
+     * and non-retryable if the code is not found.
+     *
+     * @example
+     * ```ts
+     * throw new LAFSFlagError(
+     *   'E_FORMAT_CONFLICT',
+     *   'Cannot combine --human and --json.',
+     * );
+     * ```
+     */
     constructor(code, message, details = {}) {
         super(message);
         this.name = 'LAFSFlagError';
@@ -16,6 +62,26 @@ export class LAFSFlagError extends Error {
         this.details = details;
     }
 }
+/**
+ * Resolve the output format from flag inputs using the LAFS precedence chain.
+ *
+ * @param input - The flag inputs including explicit flags, project/user defaults, and TTY state
+ * @returns The resolved format, its source layer, and quiet mode status
+ *
+ * @remarks
+ * Precedence (highest to lowest): explicit `requestedFormat` > `--human`/`--json` flag >
+ * project default > user default > TTY detection > protocol default (`'json'`).
+ * Throws `LAFSFlagError` with code `E_FORMAT_CONFLICT` if both `--human` and `--json`
+ * are set simultaneously.
+ *
+ * @example
+ * ```ts
+ * const resolution = resolveOutputFormat({ humanFlag: true });
+ * // => { format: 'human', source: 'flag', quiet: false }
+ * ```
+ *
+ * @throws {@link LAFSFlagError} When `humanFlag` and `jsonFlag` are both truthy.
+ */
 export function resolveOutputFormat(input) {
     if (input.humanFlag && input.jsonFlag) {
         throw new LAFSFlagError('E_FORMAT_CONFLICT', 'Cannot combine --human and --json in the same invocation.');

package/dist/src/flagSemantics.js.map

@@ -1 +1 @@
-{"version":3,"file":"flagSemantics.js","sourceRoot":"","sources":["../../src/flagSemantics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAUrD,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,IAAI,CAAS;IACb,QAAQ,CAAoB;IAC5B,SAAS,CAAU;IACnB,YAAY,CAAgB;IAC5B,OAAO,CAA0B;IAEjC,YAAY,IAAY,EAAE,OAAe,EAAE,UAAmC,EAAE;QAC9E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,QAAQ,GAAG,CAAC,KAAK,EAAE,QAAQ,IAAI,UAAU,CAAsB,CAAC;QACrE,IAAI,CAAC,SAAS,GAAG,KAAK,EAAE,SAAS,IAAI,KAAK,CAAC;QAC3C,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAgB;IAClD,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACtC,MAAM,IAAI,aAAa,CACrB,mBAAmB,EACnB,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC;IAEnC,IAAI,KAAK,CAAC,eAAe,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAClE,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACnD,CAAC;IACD,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;QACzB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpE,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QACtB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC9D,CAAC;IACD,gEAAgE;IAChE,kEAAkE;IAClE,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;QACd,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACtD,CAAC"}
+{"version":3,"file":"flagSemantics.js","sourceRoot":"","sources":["../../src/flagSemantics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAmBrD;;;;;;;GAOG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,wDAAwD;IACxD,IAAI,CAAS;IACb,2DAA2D;IAC3D,QAAQ,CAAoB;IAC5B,qEAAqE;IACrE,SAAS,CAAU;IACnB,yEAAyE;IACzE,YAAY,CAAgB;IAC5B,qDAAqD;IACrD,OAAO,CAA0B;IAEjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAY,IAAY,EAAE,OAAe,EAAE,UAAmC,EAAE;QAC9E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,QAAQ,GAAG,CAAC,KAAK,EAAE,QAAQ,IAAI,UAAU,CAAsB,CAAC;QACrE,IAAI,CAAC,SAAS,GAAG,KAAK,EAAE,SAAS,IAAI,KAAK,CAAC;QAC3C,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAgB;IAClD,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACtC,MAAM,IAAI,aAAa,CACrB,mBAAmB,EACnB,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC;IAEnC,IAAI,KAAK,CAAC,eAAe,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAClE,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACnD,CAAC;IACD,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;QACzB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpE,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QACtB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC9D,CAAC;IACD,gEAAgE;IAChE,kEAAkE;IAClE,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;QACd,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACtD,CAAC"}

package/dist/src/health/index.d.ts

@@ -1,28 +1,73 @@
 /**
  * LAFS Health Check Module
  *
- * Provides health check endpoints for monitoring and orchestration
+ * Provides health check endpoints for monitoring and orchestration.
+ *
+ * @packageDocumentation
  */
+/** Configuration for the {@link healthCheck} middleware. */
 export interface HealthCheckConfig {
+    /**
+     * URL path at which the health endpoint is mounted.
+     * @defaultValue '/health'
+     */
     path?: string;
+    /**
+     * Array of custom health check functions to run on each request.
+     * @defaultValue []
+     */
     checks?: HealthCheckFunction[];
 }
+/**
+ * A function that performs a single health check.
+ *
+ * @remarks
+ * May be synchronous or asynchronous. Must return a {@link HealthCheckResult}
+ * describing the outcome.
+ */
 export type HealthCheckFunction = () => Promise<HealthCheckResult> | HealthCheckResult;
+/** Result of an individual health check. */
 export interface HealthCheckResult {
+    /** Human-readable name identifying this check. */
     name: string;
+    /** Outcome status of the check. */
     status: 'ok' | 'warning' | 'error';
+    /**
+     * Optional descriptive message providing additional detail.
+     * @defaultValue undefined
+     */
     message?: string;
+    /**
+     * Execution duration of the check in milliseconds.
+     * @defaultValue undefined
+     */
     duration?: number;
 }
+/** Aggregated health status returned by the health endpoint. */
 export interface HealthStatus {
+    /** Overall service health derived from individual check results. */
     status: 'healthy' | 'degraded' | 'unhealthy';
+    /** ISO-8601 timestamp of when the health check was performed. */
     timestamp: string;
+    /** LAFS package version. */
     version: string;
+    /** Server uptime in seconds since the middleware was initialised. */
     uptime: number;
+    /** Individual check results. */
     checks: HealthCheckResult[];
 }
 /**
- * Health check middleware for Express applications
+ * Health check middleware for Express applications.
+ *
+ * @remarks
+ * Runs all configured checks on each request, determines an overall status
+ * (`healthy`, `degraded`, or `unhealthy`), and responds with a JSON
+ * {@link HealthStatus} body. Returns HTTP 200 for healthy/degraded and 503
+ * for unhealthy. Two built-in checks (`envelopeValidation` and
+ * `tokenBudgets`) are always appended.
+ *
+ * @param config - Optional health check configuration
+ * @returns An Express-compatible middleware function that serves the health endpoint
  *
  * @example
  * ```typescript
@@ -51,7 +96,17 @@ export declare function healthCheck(config?: HealthCheckConfig): (_req: unknown,
     };
 }) => Promise<void>;
 /**
- * Create a database health check
+ * Create a health check function that verifies database connectivity.
+ *
+ * @remarks
+ * Wraps a caller-supplied connection check and returns a {@link HealthCheckResult}
+ * with status `'ok'` or `'error'` depending on whether the connection succeeds.
+ * Exceptions thrown by `checkConnection` are caught and reported as errors.
+ *
+ * @param config - Database check configuration
+ * @param config.checkConnection - Async function returning `true` if the database is reachable
+ * @param config.name - Display name for this check in health output
+ * @returns A {@link HealthCheckFunction} suitable for use in {@link HealthCheckConfig.checks}
  *
  * @example
  * ```typescript
@@ -69,7 +124,18 @@ export declare function createDatabaseHealthCheck(config: {
     name?: string;
 }): HealthCheckFunction;
 /**
- * Create an external service health check
+ * Create a health check function that probes an external HTTP service.
+ *
+ * @remarks
+ * Sends a `GET` request to the configured URL with an abort timeout. Returns
+ * status `'ok'` when the response is successful (HTTP 2xx) and `'error'`
+ * otherwise. Network failures and timeouts are caught and reported.
+ *
+ * @param config - External service check configuration
+ * @param config.name - Display name for this check in health output
+ * @param config.url - URL to probe for health status
+ * @param config.timeout - Request timeout in milliseconds
+ * @returns A {@link HealthCheckFunction} suitable for use in {@link HealthCheckConfig.checks}
  *
  * @example
  * ```typescript
@@ -86,7 +152,14 @@ export declare function createExternalServiceHealthCheck(config: {
     timeout?: number;
 }): HealthCheckFunction;
 /**
- * Liveness probe - basic check that service is running
+ * Liveness probe -- a minimal check confirming the process is running.
+ *
+ * @remarks
+ * Returns a 200 response with `{ status: 'alive', timestamp }`. Intended for
+ * Kubernetes liveness probes or equivalent orchestrator health checks that
+ * only need to verify the process has not crashed.
+ *
+ * @returns An Express-compatible middleware function
  *
  * @example
  * ```typescript
@@ -99,7 +172,15 @@ export declare function livenessProbe(): (_req: unknown, res: {
     };
 }) => void;
 /**
- * Readiness probe - check that service is ready to accept traffic
+ * Readiness probe -- verifies the service can accept traffic.
+ *
+ * @remarks
+ * Runs all configured health checks and responds with 200 (`ready`) when
+ * every check passes or 503 (`not ready`) when any check reports an error.
+ * Intended for Kubernetes readiness probes or load balancer health checks.
+ *
+ * @param config - Optional configuration with custom health check functions
+ * @returns An Express-compatible async middleware function
  *
  * @example
  * ```typescript

package/dist/src/health/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/health/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,CAAC;AAEvF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,MAAM,GAAE,iBAAsB,IAMtD,MAAM,OAAO,EACb,KAAK;IAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,mBAsDvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,mBAAmB,CAiBtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,mBAAmB,CA4BtB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,KACnB,MAAM,OAAO,EAAE,KAAK;IAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,UAM5F;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE;IAAE,MAAM,CAAC,EAAE,mBAAmB,EAAE,CAAA;CAAO,IAE1E,MAAM,OAAO,EACb,KAAK;IAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,mBAiCvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/health/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,MAAM,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,CAAC;AAEvF,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IAEb,mCAAmC;IACnC,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC;IAEnC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAE7C,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAElB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAEhB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IAEf,gCAAgC;IAChC,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,WAAW,CAAC,MAAM,GAAE,iBAAsB,IAMtD,MAAM,OAAO,EACb,KAAK;IAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,mBAsDvE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,mBAAmB,CAiBtB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,mBAAmB,CA4BtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,KACnB,MAAM,OAAO,EAAE,KAAK;IAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,UAM5F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE;IAAE,MAAM,CAAC,EAAE,mBAAmB,EAAE,CAAA;CAAO,IAE1E,MAAM,OAAO,EACb,KAAK;IAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,mBAiCvE"}

package/dist/src/health/index.js

@@ -1,7 +1,9 @@
 /**
  * LAFS Health Check Module
  *
- * Provides health check endpoints for monitoring and orchestration
+ * Provides health check endpoints for monitoring and orchestration.
+ *
+ * @packageDocumentation
  */
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
@@ -13,7 +15,17 @@ catch {
     pkg = require('../../../package.json');
 }
 /**
- * Health check middleware for Express applications
+ * Health check middleware for Express applications.
+ *
+ * @remarks
+ * Runs all configured checks on each request, determines an overall status
+ * (`healthy`, `degraded`, or `unhealthy`), and responds with a JSON
+ * {@link HealthStatus} body. Returns HTTP 200 for healthy/degraded and 503
+ * for unhealthy. Two built-in checks (`envelopeValidation` and
+ * `tokenBudgets`) are always appended.
+ *
+ * @param config - Optional health check configuration
+ * @returns An Express-compatible middleware function that serves the health endpoint
  *
  * @example
  * ```typescript
@@ -88,7 +100,17 @@ export function healthCheck(config = {}) {
     };
 }
 /**
- * Create a database health check
+ * Create a health check function that verifies database connectivity.
+ *
+ * @remarks
+ * Wraps a caller-supplied connection check and returns a {@link HealthCheckResult}
+ * with status `'ok'` or `'error'` depending on whether the connection succeeds.
+ * Exceptions thrown by `checkConnection` are caught and reported as errors.
+ *
+ * @param config - Database check configuration
+ * @param config.checkConnection - Async function returning `true` if the database is reachable
+ * @param config.name - Display name for this check in health output
+ * @returns A {@link HealthCheckFunction} suitable for use in {@link HealthCheckConfig.checks}
  *
  * @example
  * ```typescript
@@ -121,7 +143,18 @@ export function createDatabaseHealthCheck(config) {
     };
 }
 /**
- * Create an external service health check
+ * Create a health check function that probes an external HTTP service.
+ *
+ * @remarks
+ * Sends a `GET` request to the configured URL with an abort timeout. Returns
+ * status `'ok'` when the response is successful (HTTP 2xx) and `'error'`
+ * otherwise. Network failures and timeouts are caught and reported.
+ *
+ * @param config - External service check configuration
+ * @param config.name - Display name for this check in health output
+ * @param config.url - URL to probe for health status
+ * @param config.timeout - Request timeout in milliseconds
+ * @returns A {@link HealthCheckFunction} suitable for use in {@link HealthCheckConfig.checks}
  *
  * @example
  * ```typescript
@@ -160,7 +193,14 @@ export function createExternalServiceHealthCheck(config) {
     };
 }
 /**
- * Liveness probe - basic check that service is running
+ * Liveness probe -- a minimal check confirming the process is running.
+ *
+ * @remarks
+ * Returns a 200 response with `{ status: 'alive', timestamp }`. Intended for
+ * Kubernetes liveness probes or equivalent orchestrator health checks that
+ * only need to verify the process has not crashed.
+ *
+ * @returns An Express-compatible middleware function
  *
  * @example
  * ```typescript
@@ -176,7 +216,15 @@ export function livenessProbe() {
     };
 }
 /**
- * Readiness probe - check that service is ready to accept traffic
+ * Readiness probe -- verifies the service can accept traffic.
+ *
+ * @remarks
+ * Runs all configured health checks and responds with 200 (`ready`) when
+ * every check passes or 503 (`not ready`) when any check reports an error.
+ * Intended for Kubernetes readiness probes or load balancer health checks.
+ *
+ * @param config - Optional configuration with custom health check functions
+ * @returns An Express-compatible async middleware function
  *
  * @example
  * ```typescript

package/dist/src/health/index.js.map

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

package/dist/src/index.d.ts

@@ -1,3 +1,14 @@
+/**
+ * LAFS (LLM-Agent-First Specification) TypeScript SDK.
+ *
+ * @packageDocumentation
+ *
+ * @remarks
+ * This is the main entry point for the `@cleocode/lafs` package. It re-exports all
+ * public modules including envelope creation, validation, conformance checking,
+ * error registry, flag resolution, MVI projection, A2A integration, and operational
+ * primitives (health, shutdown, circuit breaker).
+ */
 export type { Artifact, BuildLafsExtensionOptions, CreateTaskOptions, DataPart, ExtensionNegotiationMiddlewareOptions, ExtensionNegotiationResult, FilePart, JSONRPCErrorResponse, LafsA2AConfig, LafsExtensionParams, LafsSendMessageParams, ListTasksOptions, ListTasksResult, Message, MessageSendConfiguration, Part, PushNotificationConfig, PushNotificationDeliveryResult, PushTransport, SendMessageResponse, SendMessageSuccessResponse, StreamIteratorOptions, Task, TaskArtifactUpdateEvent, TaskState, TaskStatus, TaskStatusUpdateEvent, TaskStreamEvent, TextPart, } from './a2a/index.js';
 export { A2A_EXTENSIONS_HEADER, AGENT_CARD_PATH, attachLafsEnvelope, buildLafsExtension, createFileArtifact, createLafsArtifact, createTextArtifact, ExtensionSupportRequiredError, extensionNegotiationMiddleware, formatExtensionsHeader, getExtensionParams, HTTP_EXTENSION_HEADER, INTERRUPTED_STATES, InvalidStateTransitionError, isExtensionRequired, isInterruptedState, isTerminalState, isValidTransition, LAFS_EXTENSION_URI, LafsA2AResult, negotiateExtensions, PushNotificationConfigStore, PushNotificationDispatcher, parseExtensionsHeader, streamTaskEvents, TaskArtifactAssembler, TaskEventBus, TaskImmutabilityError, TaskManager, TaskNotFoundError, TaskRefinementError, TERMINAL_STATES, VALID_TRANSITIONS, } from './a2a/index.js';
 export * from './budgetEnforcement.js';
@@ -13,8 +24,8 @@ export * from './fieldExtraction.js';
 export * from './flagResolver.js';
 export * from './flagSemantics.js';
 export * from './health/index.js';
-export * from './mcpAdapter.js';
 export * from './mviProjection.js';
+export { isNativeAvailable } from './native-loader.js';
 export type { LafsProblemDetails } from './problemDetails.js';
 export { lafsErrorToProblemDetails, PROBLEM_DETAILS_CONTENT_TYPE } from './problemDetails.js';
 export * from './shutdown/index.js';

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,QAAQ,EACR,yBAAyB,EACzB,iBAAiB,EACjB,QAAQ,EACR,qCAAqC,EACrC,0BAA0B,EAC1B,QAAQ,EACR,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,OAAO,EACP,wBAAwB,EACxB,IAAI,EACJ,sBAAsB,EACtB,8BAA8B,EAC9B,aAAa,EACb,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACrB,IAAI,EACJ,uBAAuB,EACvB,SAAS,EACT,UAAU,EACV,qBAAqB,EACrB,eAAe,EACf,QAAQ,GACT,MAAM,gBAAgB,CAAC;AAKxB,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,6BAA6B,EAC7B,8BAA8B,EAC9B,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EAEjB,kBAAkB,EAElB,aAAa,EACb,mBAAmB,EACnB,2BAA2B,EAC3B,0BAA0B,EAC1B,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,EAErB,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EAEnB,eAAe,EACf,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAC9F,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,YAAY,EACV,QAAQ,EACR,yBAAyB,EACzB,iBAAiB,EACjB,QAAQ,EACR,qCAAqC,EACrC,0BAA0B,EAC1B,QAAQ,EACR,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,OAAO,EACP,wBAAwB,EACxB,IAAI,EACJ,sBAAsB,EACtB,8BAA8B,EAC9B,aAAa,EACb,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACrB,IAAI,EACJ,uBAAuB,EACvB,SAAS,EACT,UAAU,EACV,qBAAqB,EACrB,eAAe,EACf,QAAQ,GACT,MAAM,gBAAgB,CAAC;AAKxB,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,6BAA6B,EAC7B,8BAA8B,EAC9B,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EAEjB,kBAAkB,EAElB,aAAa,EACb,mBAAmB,EACnB,2BAA2B,EAC3B,0BAA0B,EAC1B,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,EAErB,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EAEnB,eAAe,EACf,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAC9F,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC"}

package/dist/src/index.js

@@ -1,3 +1,14 @@
+/**
+ * LAFS (LLM-Agent-First Specification) TypeScript SDK.
+ *
+ * @packageDocumentation
+ *
+ * @remarks
+ * This is the main entry point for the `@cleocode/lafs` package. It re-exports all
+ * public modules including envelope creation, validation, conformance checking,
+ * error registry, flag resolution, MVI projection, A2A integration, and operational
+ * primitives (health, shutdown, circuit breaker).
+ */
 // A2A Integration
 // Explicitly re-export to avoid naming conflicts with discovery types
 // (AgentCard, AgentSkill, AgentCapabilities, AgentExtension).
@@ -25,8 +36,8 @@ export * from './flagResolver.js';
 export * from './flagSemantics.js';
 // Operations & Reliability
 export * from './health/index.js';
-export * from './mcpAdapter.js';
 export * from './mviProjection.js';
+export { isNativeAvailable } from './native-loader.js';
 export { lafsErrorToProblemDetails, PROBLEM_DETAILS_CONTENT_TYPE } from './problemDetails.js';
 export * from './shutdown/index.js';
 export * from './tokenEstimator.js';

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAgCA,kBAAkB;AAClB,sEAAsE;AACtE,8DAA8D;AAC9D,wDAAwD;AACxD,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,6BAA6B,EAC7B,8BAA8B,EAC9B,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB;AACjB,oBAAoB;AACpB,kBAAkB;AAClB,SAAS;AACT,aAAa,EACb,mBAAmB,EACnB,2BAA2B,EAC3B,0BAA0B,EAC1B,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB;AACrB,6BAA6B;AAC7B,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,mBAAmB;AACnB,wBAAwB;AACxB,eAAe,EACf,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,2BAA2B;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AAEnC,OAAO,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAC9F,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkCH,kBAAkB;AAClB,sEAAsE;AACtE,8DAA8D;AAC9D,wDAAwD;AACxD,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,6BAA6B,EAC7B,8BAA8B,EAC9B,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB;AACjB,oBAAoB;AACpB,kBAAkB;AAClB,SAAS;AACT,aAAa,EACb,mBAAmB,EACnB,2BAA2B,EAC3B,0BAA0B,EAC1B,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB;AACrB,6BAA6B;AAC7B,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,mBAAmB;AACnB,wBAAwB;AACxB,eAAe,EACf,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,2BAA2B;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAC9F,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC"}

package/dist/src/mviProjection.d.ts

@@ -1,20 +1,56 @@
 /**
  * MVI-aware envelope projection.
+ *
  * Strips fields based on declared MVI level to reduce token cost.
- * At 'minimal': ~38 tokens per error (vs ~162 at 'full').
+ * At `'minimal'`: approximately 38 tokens per error (vs approximately 162 at `'full'`).
+ *
+ * @remarks
+ * Projection is applied after field extraction and before serialization. The four
+ * MVI levels control which envelope fields are included in the output:
+ * - `'minimal'`: only fields required for agent control flow
+ * - `'standard'`: all commonly useful fields (current default)
+ * - `'full'` / `'custom'`: complete envelope, no stripping
+ *
+ * @since 1.5.0
  */
 import type { LAFSEnvelope, MVILevel } from './types.js';
 /**
  * Project an envelope to the declared MVI verbosity level.
- * - 'minimal': Only fields required for agent control flow
- * - 'standard': All commonly useful fields (current default behavior)
- * - 'full': Complete echo-back including request parameters
- * - 'custom': No projection (controlled by _fields)
+ *
+ * @param envelope - The full LAFS envelope to project
+ * @param mviLevel - Override MVI level; falls back to `envelope._meta.mvi`, then `'standard'`
+ * @returns A plain object containing only the fields appropriate for the resolved MVI level
+ *
+ * @remarks
+ * MVI levels control projection behavior:
+ * - `'minimal'`: only fields required for agent control flow (success, error code, retry info)
+ * - `'standard'`: all commonly useful fields (current default behavior)
+ * - `'full'`: complete echo-back including request parameters
+ * - `'custom'`: no projection (controlled by field extraction layer)
+ *
+ * @example
+ * ```ts
+ * const minimal = projectEnvelope(envelope, 'minimal');
+ * // minimal contains only: success, _meta (requestId, contextVersion), result/error
+ * ```
  */
 export declare function projectEnvelope(envelope: LAFSEnvelope, mviLevel?: MVILevel): Record<string, unknown>;
 /**
  * Estimate token count for a projected envelope.
- * Uses simple heuristic: 1 token per ~4 characters of JSON.
+ *
+ * @param projected - The projected envelope object to estimate
+ * @returns The estimated token count based on JSON serialization length
+ *
+ * @remarks
+ * Uses a simple heuristic of 1 token per approximately 4 characters of
+ * JSON-serialized output. This is an approximation suitable for budget
+ * enforcement, not an exact tokenizer count.
+ *
+ * @example
+ * ```ts
+ * const tokens = estimateProjectedTokens(projectEnvelope(envelope, 'minimal'));
+ * // tokens ~= Math.ceil(JSON.stringify(projected).length / 4)
+ * ```
  */
 export declare function estimateProjectedTokens(projected: Record<string, unknown>): number;
 //# sourceMappingURL=mviProjection.d.ts.map

package/dist/src/mviProjection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mviProjection.d.ts","sourceRoot":"","sources":["../../src/mviProjection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAuB,QAAQ,EAAE,MAAM,YAAY,CAAC;AAW9E;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,YAAY,EACtB,QAAQ,CAAC,EAAE,QAAQ,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWzB;AAoGD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAGlF"}
+{"version":3,"file":"mviProjection.d.ts","sourceRoot":"","sources":["../../src/mviProjection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,YAAY,EAAuB,QAAQ,EAAE,MAAM,YAAY,CAAC;AAa9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,YAAY,EACtB,QAAQ,CAAC,EAAE,QAAQ,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWzB;AAoGD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAGlF"}

package/dist/src/mviProjection.js

@@ -1,9 +1,22 @@
 /**
  * Project an envelope to the declared MVI verbosity level.
- * - 'minimal': Only fields required for agent control flow
- * - 'standard': All commonly useful fields (current default behavior)
- * - 'full': Complete echo-back including request parameters
- * - 'custom': No projection (controlled by _fields)
+ *
+ * @param envelope - The full LAFS envelope to project
+ * @param mviLevel - Override MVI level; falls back to `envelope._meta.mvi`, then `'standard'`
+ * @returns A plain object containing only the fields appropriate for the resolved MVI level
+ *
+ * @remarks
+ * MVI levels control projection behavior:
+ * - `'minimal'`: only fields required for agent control flow (success, error code, retry info)
+ * - `'standard'`: all commonly useful fields (current default behavior)
+ * - `'full'`: complete echo-back including request parameters
+ * - `'custom'`: no projection (controlled by field extraction layer)
+ *
+ * @example
+ * ```ts
+ * const minimal = projectEnvelope(envelope, 'minimal');
+ * // minimal contains only: success, _meta (requestId, contextVersion), result/error
+ * ```
  */
 export function projectEnvelope(envelope, mviLevel) {
     const level = mviLevel ?? envelope._meta.mvi ?? 'standard';
@@ -108,7 +121,20 @@ function projectErrorMinimal(error) {
 }
 /**
  * Estimate token count for a projected envelope.
- * Uses simple heuristic: 1 token per ~4 characters of JSON.
+ *
+ * @param projected - The projected envelope object to estimate
+ * @returns The estimated token count based on JSON serialization length
+ *
+ * @remarks
+ * Uses a simple heuristic of 1 token per approximately 4 characters of
+ * JSON-serialized output. This is an approximation suitable for budget
+ * enforcement, not an exact tokenizer count.
+ *
+ * @example
+ * ```ts
+ * const tokens = estimateProjectedTokens(projectEnvelope(envelope, 'minimal'));
+ * // tokens ~= Math.ceil(JSON.stringify(projected).length / 4)
+ * ```
  */
 export function estimateProjectedTokens(projected) {
     const json = JSON.stringify(projected);

package/dist/src/mviProjection.js.map

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

package/dist/src/native-loader.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Native addon loader for lafs-core schema validation via napi-rs.
+ *
+ * @remarks
+ * Loads the napi-rs native addon synchronously on first use. Falls back
+ * gracefully if the native addon is not available (e.g., unsupported platform,
+ * Rust toolchain not installed). When unavailable, the AJV-based validator
+ * in `validateEnvelope.ts` is used instead.
+ *
+ * Follows the same pattern as `packages/cant/src/native-loader.ts`.
+ */
+/** Shape of a structured validation error from the native binding. */
+interface NativeValidationError {
+    /** JSON Pointer path to the failing property. */
+    path: string;
+    /** JSON Schema keyword that triggered the error. */
+    keyword: string;
+    /** Human-readable error message. */
+    message: string;
+    /** Keyword-specific parameters. */
+    params: Record<string, unknown>;
+}
+/** Shape of the validation result from the native binding. */
+export interface NativeValidationResult {
+    /** Whether the envelope conforms to the schema. */
+    valid: boolean;
+    /** Flattened human-readable error messages. */
+    errors: string[];
+    /** Structured error objects. */
+    structuredErrors: NativeValidationError[];
+}
+/** Shape of the native LAFS addon. */
+interface LafsNativeModule {
+    lafsValidateEnvelope(payload: string): NativeValidationResult;
+}
+/**
+ * Check if the native addon is available.
+ *
+ * @returns `true` if the native Rust binding was loaded successfully.
+ */
+export declare function isNativeAvailable(): boolean;
+/**
+ * Get the native module, or `null` if unavailable.
+ *
+ * @returns The loaded native module, or `null` for AJV fallback.
+ */
+export declare function getNativeModule(): LafsNativeModule | null;
+export {};
+//# sourceMappingURL=native-loader.d.ts.map

package/dist/src/native-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-loader.d.ts","sourceRoot":"","sources":["../../src/native-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,sEAAsE;AACtE,UAAU,qBAAqB;IAC7B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,8DAA8D;AAC9D,MAAM,WAAW,sBAAsB;IACrC,mDAAmD;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,gCAAgC;IAChC,gBAAgB,EAAE,qBAAqB,EAAE,CAAC;CAC3C;AAED,sCAAsC;AACtC,UAAU,gBAAgB;IACxB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,sBAAsB,CAAC;CAC/D;AA2BD;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAG3C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,GAAG,IAAI,CAGzD"}