@cleocode/lafs 2026.3.74 → 2026.4.3

package/dist/src/errorRegistry.d.ts

@@ -1,28 +1,188 @@
-import type { LAFSAgentAction } from "./types.js";
+import type { LAFSAgentAction } from './types.js';
+/**
+ * A single entry in the LAFS error-code registry.
+ *
+ * @remarks
+ * Each entry defines the canonical error code, its category, human-readable
+ * description, retry semantics, and transport-specific status mappings.
+ */
 export interface RegistryCode {
+    /** The canonical LAFS error code (e.g., `"E_FORMAT_CONFLICT"`). */
     code: string;
+    /** Broad error category (e.g., `"client"`, `"server"`, `"auth"`). */
     category: string;
+    /** Human-readable description of when this error occurs. */
     description: string;
+    /** Whether the operation that produced this error is safe to retry. */
     retryable: boolean;
+    /** HTTP status code mapped to this error. */
     httpStatus: number;
+    /** gRPC status string mapped to this error. */
     grpcStatus: string;
+    /** CLI exit code mapped to this error. */
     cliExit: number;
+    /**
+     * Suggested agent action from the registry (e.g., `"retry"`, `"abort"`).
+     * @defaultValue undefined
+     */
     agentAction?: string;
+    /**
+     * RFC 9457 type URI for this error, used in Problem Details responses.
+     * @defaultValue undefined
+     */
     typeUri?: string;
+    /**
+     * URL pointing to human-readable documentation for this error.
+     * @defaultValue undefined
+     */
     docUrl?: string;
 }
+/**
+ * Top-level shape of the LAFS error-registry JSON file.
+ *
+ * @remarks
+ * Contains a version string for schema evolution and the complete list
+ * of registered error codes.
+ */
 export interface ErrorRegistry {
+    /** Semantic version of the error-registry schema. */
     version: string;
+    /** All registered LAFS error codes. */
     codes: RegistryCode[];
 }
+/**
+ * A transport-specific status value resolved from the error registry.
+ *
+ * @remarks
+ * For HTTP and CLI, `value` is a number (status code / exit code).
+ * For gRPC, `value` is a string (status name).
+ */
 export type TransportMapping = {
-    transport: "http" | "grpc" | "cli";
+    /** The transport protocol this mapping applies to. */
+    transport: 'http' | 'grpc' | 'cli';
+    /** The transport-specific status value (numeric for HTTP/CLI, string for gRPC). */
     value: number | string;
 };
+/**
+ * Loads the full LAFS error registry from the bundled JSON.
+ *
+ * @remarks
+ * Returns the parsed `error-registry.json` as a typed {@link ErrorRegistry}.
+ *
+ * @returns The complete error registry with version and all registered codes.
+ *
+ * @example
+ * ```ts
+ * const registry = getErrorRegistry();
+ * console.log(registry.version, registry.codes.length);
+ * ```
+ */
 export declare function getErrorRegistry(): ErrorRegistry;
+/**
+ * Checks whether a given error code exists in the LAFS error registry.
+ *
+ * @remarks
+ * Performs a linear scan of the registry codes array. Suitable for
+ * validation-time lookups; not optimized for hot-path usage.
+ *
+ * @param code - The error code string to look up (e.g., `"E_FORMAT_CONFLICT"`).
+ * @returns `true` if the code is registered, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * isRegisteredErrorCode('E_FORMAT_CONFLICT'); // true
+ * isRegisteredErrorCode('E_UNKNOWN');         // false
+ * ```
+ */
 export declare function isRegisteredErrorCode(code: string): boolean;
+/**
+ * Retrieves the full registry entry for a given error code.
+ *
+ * @remarks
+ * Returns `undefined` when the code is not found, allowing callers to
+ * distinguish between "code exists" and "code absent" without exceptions.
+ *
+ * @param code - The error code string to look up.
+ * @returns The matching {@link RegistryCode} or `undefined` if not found.
+ *
+ * @example
+ * ```ts
+ * const entry = getRegistryCode('E_FORMAT_CONFLICT');
+ * if (entry) {
+ *   console.log(entry.httpStatus); // 409
+ * }
+ * ```
+ */
 export declare function getRegistryCode(code: string): RegistryCode | undefined;
+/**
+ * Returns the default agent action for a given error code.
+ *
+ * @remarks
+ * Delegates to {@link getRegistryCode} and extracts the `agentAction`
+ * field. Returns `undefined` when the code is unregistered or has no
+ * default action.
+ *
+ * @param code - The error code string to look up.
+ * @returns The {@link LAFSAgentAction} or `undefined` if unavailable.
+ *
+ * @example
+ * ```ts
+ * const action = getAgentAction('E_RATE_LIMIT');
+ * console.log(action); // "retry"
+ * ```
+ */
 export declare function getAgentAction(code: string): LAFSAgentAction | undefined;
+/**
+ * Returns the RFC 9457 type URI for a given error code.
+ *
+ * @remarks
+ * Useful for constructing Problem Details responses. Returns `undefined`
+ * when the code is unregistered or has no type URI.
+ *
+ * @param code - The error code string to look up.
+ * @returns The type URI string or `undefined` if unavailable.
+ *
+ * @example
+ * ```ts
+ * const uri = getTypeUri('E_VALIDATION');
+ * // "https://lafs.dev/errors/E_VALIDATION"
+ * ```
+ */
 export declare function getTypeUri(code: string): string | undefined;
+/**
+ * Returns the documentation URL for a given error code.
+ *
+ * @remarks
+ * Provides a link to human-readable docs for the error. Returns
+ * `undefined` when the code is unregistered or has no doc URL.
+ *
+ * @param code - The error code string to look up.
+ * @returns The documentation URL string or `undefined` if unavailable.
+ *
+ * @example
+ * ```ts
+ * const url = getDocUrl('E_VALIDATION');
+ * // "https://lafs.dev/docs/errors/E_VALIDATION"
+ * ```
+ */
 export declare function getDocUrl(code: string): string | undefined;
-export declare function getTransportMapping(code: string, transport: "http" | "grpc" | "cli"): TransportMapping | null;
+/**
+ * Resolves the transport-specific status value for a given error code and transport.
+ *
+ * @remarks
+ * Looks up the registry entry and extracts `httpStatus`, `grpcStatus`, or
+ * `cliExit` depending on the requested transport. Returns `null` when the
+ * error code is not registered.
+ *
+ * @param code - The error code string to look up.
+ * @param transport - The transport protocol to resolve a mapping for.
+ * @returns A {@link TransportMapping} or `null` if the code is unregistered.
+ *
+ * @example
+ * ```ts
+ * const mapping = getTransportMapping('E_NOT_FOUND', 'http');
+ * console.log(mapping); // { transport: 'http', value: 404 }
+ * ```
+ */
+export declare function getTransportMapping(code: string, transport: 'http' | 'grpc' | 'cli'): TransportMapping | null;
+//# sourceMappingURL=errorRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errorRegistry.d.ts","sourceRoot":"","sources":["../../src/errorRegistry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,SAAS,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sDAAsD;IACtD,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;IACnC,mFAAmF;IACnF,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAGxE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG3D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GACjC,gBAAgB,GAAG,IAAI,CAazB"}

package/dist/src/errorRegistry.js

@@ -1,36 +1,152 @@
-import errorRegistry from "../schemas/v1/error-registry.json" with { type: "json" };
+import errorRegistry from '../schemas/v1/error-registry.json' with { type: 'json' };
+/**
+ * Loads the full LAFS error registry from the bundled JSON.
+ *
+ * @remarks
+ * Returns the parsed `error-registry.json` as a typed {@link ErrorRegistry}.
+ *
+ * @returns The complete error registry with version and all registered codes.
+ *
+ * @example
+ * ```ts
+ * const registry = getErrorRegistry();
+ * console.log(registry.version, registry.codes.length);
+ * ```
+ */
 export function getErrorRegistry() {
     return errorRegistry;
 }
+/**
+ * Checks whether a given error code exists in the LAFS error registry.
+ *
+ * @remarks
+ * Performs a linear scan of the registry codes array. Suitable for
+ * validation-time lookups; not optimized for hot-path usage.
+ *
+ * @param code - The error code string to look up (e.g., `"E_FORMAT_CONFLICT"`).
+ * @returns `true` if the code is registered, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * isRegisteredErrorCode('E_FORMAT_CONFLICT'); // true
+ * isRegisteredErrorCode('E_UNKNOWN');         // false
+ * ```
+ */
 export function isRegisteredErrorCode(code) {
     const registry = getErrorRegistry();
     return registry.codes.some((item) => item.code === code);
 }
+/**
+ * Retrieves the full registry entry for a given error code.
+ *
+ * @remarks
+ * Returns `undefined` when the code is not found, allowing callers to
+ * distinguish between "code exists" and "code absent" without exceptions.
+ *
+ * @param code - The error code string to look up.
+ * @returns The matching {@link RegistryCode} or `undefined` if not found.
+ *
+ * @example
+ * ```ts
+ * const entry = getRegistryCode('E_FORMAT_CONFLICT');
+ * if (entry) {
+ *   console.log(entry.httpStatus); // 409
+ * }
+ * ```
+ */
 export function getRegistryCode(code) {
     return getErrorRegistry().codes.find((item) => item.code === code);
 }
+/**
+ * Returns the default agent action for a given error code.
+ *
+ * @remarks
+ * Delegates to {@link getRegistryCode} and extracts the `agentAction`
+ * field. Returns `undefined` when the code is unregistered or has no
+ * default action.
+ *
+ * @param code - The error code string to look up.
+ * @returns The {@link LAFSAgentAction} or `undefined` if unavailable.
+ *
+ * @example
+ * ```ts
+ * const action = getAgentAction('E_RATE_LIMIT');
+ * console.log(action); // "retry"
+ * ```
+ */
 export function getAgentAction(code) {
     const entry = getRegistryCode(code);
     return entry?.agentAction;
 }
+/**
+ * Returns the RFC 9457 type URI for a given error code.
+ *
+ * @remarks
+ * Useful for constructing Problem Details responses. Returns `undefined`
+ * when the code is unregistered or has no type URI.
+ *
+ * @param code - The error code string to look up.
+ * @returns The type URI string or `undefined` if unavailable.
+ *
+ * @example
+ * ```ts
+ * const uri = getTypeUri('E_VALIDATION');
+ * // "https://lafs.dev/errors/E_VALIDATION"
+ * ```
+ */
 export function getTypeUri(code) {
     const entry = getRegistryCode(code);
     return entry?.typeUri;
 }
+/**
+ * Returns the documentation URL for a given error code.
+ *
+ * @remarks
+ * Provides a link to human-readable docs for the error. Returns
+ * `undefined` when the code is unregistered or has no doc URL.
+ *
+ * @param code - The error code string to look up.
+ * @returns The documentation URL string or `undefined` if unavailable.
+ *
+ * @example
+ * ```ts
+ * const url = getDocUrl('E_VALIDATION');
+ * // "https://lafs.dev/docs/errors/E_VALIDATION"
+ * ```
+ */
 export function getDocUrl(code) {
     const entry = getRegistryCode(code);
     return entry?.docUrl;
 }
+/**
+ * Resolves the transport-specific status value for a given error code and transport.
+ *
+ * @remarks
+ * Looks up the registry entry and extracts `httpStatus`, `grpcStatus`, or
+ * `cliExit` depending on the requested transport. Returns `null` when the
+ * error code is not registered.
+ *
+ * @param code - The error code string to look up.
+ * @param transport - The transport protocol to resolve a mapping for.
+ * @returns A {@link TransportMapping} or `null` if the code is unregistered.
+ *
+ * @example
+ * ```ts
+ * const mapping = getTransportMapping('E_NOT_FOUND', 'http');
+ * console.log(mapping); // { transport: 'http', value: 404 }
+ * ```
+ */
 export function getTransportMapping(code, transport) {
     const registryCode = getRegistryCode(code);
     if (!registryCode) {
         return null;
     }
-    if (transport === "http") {
+    if (transport === 'http') {
         return { transport, value: registryCode.httpStatus };
     }
-    if (transport === "grpc") {
+    if (transport === 'grpc') {
         return { transport, value: registryCode.grpcStatus };
     }
     return { transport, value: registryCode.cliExit };
 }
+//# sourceMappingURL=errorRegistry.js.map

package/dist/src/errorRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorRegistry.js","sourceRoot":"","sources":["../../src/errorRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,mCAAmC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAsEpF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,aAA8B,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,MAAM,QAAQ,GAAG,gBAAgB,EAAE,CAAC;IACpC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,gBAAgB,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,KAAK,EAAE,WAA0C,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,KAAK,EAAE,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,KAAK,EAAE,MAAM,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,SAAkC;IAElC,MAAM,YAAY,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACzB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,CAAC,UAAU,EAAE,CAAC;IACvD,CAAC;IACD,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACzB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,CAAC,UAAU,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC;AACpD,CAAC"}

package/dist/src/fieldExtraction.d.ts

@@ -1,67 +1,168 @@
-import type { LAFSEnvelope, MVILevel } from "./types.js";
+/**
+ * Field extraction resolution for LAFS envelopes.
+ *
+ * Implements section 9.2 of the LAFS spec: `--field` extracts a single value
+ * as plain text (no envelope), `--fields` filters the JSON envelope to a subset,
+ * and `--mvi` controls envelope verbosity.
+ *
+ * @remarks
+ * This module provides both resolution (flag parsing) and runtime extraction/filtering
+ * functions. The resolution layer is consumed by the unified resolver in `flagResolver.ts`.
+ *
+ * @since 1.5.0
+ */
+import type { LAFSEnvelope, MVILevel } from './types.js';
+/**
+ * Input flags for the field extraction layer.
+ *
+ * @remarks
+ * Mutually exclusive: `fieldFlag` and `fieldsFlag` cannot both be set.
+ * Providing both causes an `E_FIELD_CONFLICT` error during resolution.
+ */
 export interface FieldExtractionInput {
-    /** --field <name>: extract single field as plain text, no envelope */
+    /**
+     * `--field <name>`: extract a single field as plain text, discarding the envelope.
+     * @defaultValue undefined
+     */
     fieldFlag?: string;
-    /** --fields <a,b,c>: filter result to these fields, preserve envelope */
+    /**
+     * `--fields <a,b,c>`: filter result to these fields while preserving the envelope.
+     * Accepts a comma-separated string or an array of field names.
+     * @defaultValue undefined
+     */
     fieldsFlag?: string | string[];
-    /** --mvi <level>: envelope verbosity (client-requestable levels only) */
+    /**
+     * `--mvi <level>`: requested envelope verbosity level (client-requestable levels only).
+     * The `'custom'` level is server-set and not valid here.
+     * @defaultValue undefined
+     */
     mviFlag?: MVILevel | string;
 }
+/**
+ * Resolved field extraction configuration.
+ *
+ * @remarks
+ * Produced by {@link resolveFieldExtraction}. Contains the parsed and validated
+ * field extraction settings ready for use by extraction and filtering functions.
+ */
 export interface FieldExtractionResolution {
-    /** When set: extract this field as plain text, discard envelope. */
+    /**
+     * When set, extract this field as plain text, discarding the envelope.
+     * @defaultValue undefined
+     */
     field?: string;
-    /** When set: filter result to these fields (envelope preserved). */
+    /**
+     * When set, filter the result to these fields (envelope is preserved).
+     * @defaultValue undefined
+     */
     fields?: string[];
-    /** Resolved MVI level. Defaults to 'standard'. */
+    /** Resolved MVI level. Falls back to `'minimal'` when no valid flag is provided. */
     mvi: MVILevel;
-    /** Which input determined the mvi value: 'flag' when mviFlag was valid, 'default' otherwise. */
-    mviSource: "flag" | "default";
+    /** Which input determined the mvi value: `'flag'` when mviFlag was valid, `'default'` otherwise. */
+    mviSource: 'flag' | 'default';
     /**
-     * True when _fields are requested, indicating the server SHOULD set
-     * _meta.mvi = 'custom' in the response per §9.1.
+     * True when `fields` are requested, indicating the server SHOULD set
+     * `_meta.mvi = 'custom'` in the response per section 9.1.
      * Separate from the client-resolved mvi level.
      */
     expectsCustomMvi: boolean;
 }
+/**
+ * Resolve field extraction flags into a validated configuration.
+ *
+ * @param input - The field extraction flag inputs
+ * @returns The resolved extraction configuration with mvi level and source
+ *
+ * @remarks
+ * Parses and validates the `--field`, `--fields`, and `--mvi` flags. Throws
+ * `E_FIELD_CONFLICT` if both `--field` and `--fields` are provided. The `'custom'`
+ * MVI level is server-set per section 9.1 and is rejected as a client-requested value;
+ * invalid or absent `--mvi` falls back to `'minimal'`.
+ *
+ * @example
+ * ```ts
+ * const resolution = resolveFieldExtraction({ fieldsFlag: 'id,title' });
+ * // => { fields: ['id', 'title'], mvi: 'minimal', mviSource: 'default', expectsCustomMvi: true }
+ * ```
+ *
+ * @throws {@link LAFSFlagError} When both `fieldFlag` and `fieldsFlag` are set.
+ */
 export declare function resolveFieldExtraction(input: FieldExtractionInput): FieldExtractionResolution;
 /**
  * Extract a named field from a LAFS result object.
  *
+ * @param result - The envelope result value (object, array, or null)
+ * @param field - The field name to extract
+ * @returns The extracted value, or `undefined` if not found at any level
+ *
+ * @remarks
  * Handles four result shapes:
- *   1. Direct array: result[0][field]       (list operations where result IS an array)
- *   2. Direct:       result[field]          (flat result object)
- *   3. Nested:       result.<key>[field]    (wrapper-entity, e.g. result.task.title)
- *   4. Array value:  result.<key>[0][field] (wrapper-array, e.g. result.items[0].title)
+ *   1. Direct array: `result[0][field]` (list operations where result IS an array)
+ *   2. Direct: `result[field]` (flat result object)
+ *   3. Nested: `result.<key>[field]` (wrapper-entity, e.g. `result.task.title`)
+ *   4. Array value: `result.<key>[0][field]` (wrapper-array, e.g. `result.items[0].title`)
  *
  * Returns the value from the first match only. For array results (shapes 1
  * and 4), returns the first element's field value only. To extract from all
- * elements, iterate the array or use applyFieldFilter().
+ * elements, iterate the array or use {@link applyFieldFilter}.
  *
  * When multiple wrapper keys contain the requested field (shapes 3 and 4),
  * the first key in property insertion order wins.
  *
- * Returns undefined if not found at any level.
+ * @example
+ * ```ts
+ * const result = { task: { id: 'T1', title: 'Fix bug' } };
+ * extractFieldFromResult(result, 'title'); // => 'Fix bug'
+ * ```
  */
 export declare function extractFieldFromResult(result: LAFSEnvelope['result'], field: string): unknown;
-/** Convenience wrapper — extracts a field from an envelope's result. */
+/**
+ * Extract a named field from an envelope's result.
+ *
+ * @param envelope - The LAFS envelope to extract from
+ * @param field - The field name to extract
+ * @returns The extracted value, or `undefined` if not found
+ *
+ * @remarks
+ * Convenience wrapper around {@link extractFieldFromResult} that accepts
+ * the full envelope and delegates to the result extraction logic.
+ *
+ * @example
+ * ```ts
+ * const value = extractFieldFromEnvelope(envelope, 'title');
+ * ```
+ */
 export declare function extractFieldFromEnvelope(envelope: LAFSEnvelope, field: string): unknown;
 /**
  * Filter result fields in a LAFS envelope to the requested subset.
  *
- * Handles the same four result shapes as extractFieldFromResult:
- *   1. Direct array:    project each element
- *   2. Flat result:     project top-level keys
- *   3. Wrapper-entity:  project nested entity's keys, preserve wrapper
- *   4. Wrapper-array:   project each element's keys, preserve wrapper
+ * @param envelope - The LAFS envelope whose result will be filtered
+ * @param fields - Array of field names to retain in the result
+ * @returns A new envelope with the filtered result and `_meta.mvi` set to `'custom'`
  *
- * Sets _meta.mvi = 'custom' per §9.1.
- * Returns a new envelope with a new _meta object. Result values are not
+ * @remarks
+ * Handles the same four result shapes as {@link extractFieldFromResult}:
+ *   1. Direct array: project each element
+ *   2. Flat result: project top-level keys
+ *   3. Wrapper-entity: project nested entity's keys, preserve wrapper
+ *   4. Wrapper-array: project each element's keys, preserve wrapper
+ *
+ * Sets `_meta.mvi = 'custom'` per section 9.1.
+ * Returns a new envelope with a new `_meta` object. Result values are not
  * deep-cloned; nested object references are shared with the original.
- * Unknown field names are silently omitted per §9.2.
+ * Unknown field names are silently omitted per section 9.2.
  *
  * When result is a wrapper (shapes 3/4) with multiple keys, each key is
  * projected independently. Primitive values at the wrapper level (numbers,
- * strings, booleans) are preserved as-is — _fields is applied to nested
+ * strings, booleans) are preserved as-is; field filtering is applied to nested
  * entity or array keys only, not to the wrapper's own primitive keys.
+ *
+ * @example
+ * ```ts
+ * const filtered = applyFieldFilter(envelope, ['id', 'title']);
+ * // filtered.result contains only 'id' and 'title' fields
+ * // filtered._meta.mvi === 'custom'
+ * ```
  */
 export declare function applyFieldFilter(envelope: LAFSEnvelope, fields: string[]): LAFSEnvelope;
+//# sourceMappingURL=fieldExtraction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fieldExtraction.d.ts","sourceRoot":"","sources":["../../src/fieldExtraction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGzD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,oFAAoF;IACpF,GAAG,EAAE,QAAQ,CAAC;IACd,oGAAoG;IACpG,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,yBAAyB,CAmC7F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CA4B7F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,YAAY,CAuCvF"}