@cleocode/lafs 2026.4.0 → 2026.4.4

package/dist/src/fieldExtraction.d.ts

@@ -1,68 +1,168 @@
+/**
+ * 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. */
+    /** 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

@@ -1 +1 @@
-{"version":3,"file":"fieldExtraction.d.ts","sourceRoot":"","sources":["../../src/fieldExtraction.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGzD,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,yEAAyE;IACzE,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACxC,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,kDAAkD;IAClD,GAAG,EAAE,QAAQ,CAAC;IACd,gGAAgG;IAChG,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,yBAAyB,CAmC7F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CA4B7F;AAED,wEAAwE;AACxE,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,YAAY,CAuCvF"}
+{"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"}

package/dist/src/fieldExtraction.js

@@ -1,5 +1,38 @@
+/**
+ * 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 { LAFSFlagError } from './flagSemantics.js';
 import { isMVILevel } from './types.js';
+/**
+ * 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 function resolveFieldExtraction(input) {
     if (input.fieldFlag && input.fieldsFlag) {
         throw new LAFSFlagError('E_FIELD_CONFLICT', 'Cannot combine --field and --fields: --field extracts a single value ' +
@@ -30,20 +63,29 @@ export function resolveFieldExtraction(input) {
 /**
  * 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 function extractFieldFromResult(result, field) {
     if (result === null || typeof result !== 'object')
@@ -76,28 +118,55 @@ export function extractFieldFromResult(result, field) {
     }
     return undefined;
 }
-/** 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 function extractFieldFromEnvelope(envelope, field) {
     return extractFieldFromResult(envelope.result, field);
 }
 /**
  * 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 function applyFieldFilter(envelope, fields) {
     if (fields.length === 0 || envelope.result === null)

package/dist/src/fieldExtraction.js.map

@@ -1 +1 @@
-{"version":3,"file":"fieldExtraction.js","sourceRoot":"","sources":["../../src/fieldExtraction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA4BxC,MAAM,UAAU,sBAAsB,CAAC,KAA2B;IAChE,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACxC,MAAM,IAAI,aAAa,CACrB,kBAAkB,EAClB,uEAAuE;YACrE,mEAAmE;YACnE,uBAAuB,EACzB,EAAE,gBAAgB,EAAE,CAAC,yBAAyB,EAAE,oBAAoB,CAAC,EAAE,CACxE,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GACV,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ;QAClC,CAAC,CAAC,KAAK,CAAC,UAAU;aACb,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,OAAO,CAAC;QACpB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC;YAC/B,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;YACvD,CAAC,CAAC,SAAS,CAAC;IAElB,iEAAiE;IACjE,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC;IACzE,MAAM,GAAG,GAAa,QAAQ,CAAC,CAAC,CAAE,KAAK,CAAC,OAAoB,CAAC,CAAC,CAAC,SAAS,CAAC;IACzE,MAAM,SAAS,GAA2C,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAExF,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAE5C,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,SAAS,IAAI,SAAS;QACnC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;QACtC,GAAG;QACH,SAAS;QACT,gBAAgB,EAAE,SAAS;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA8B,EAAE,KAAa;IAClF,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAEpE,oCAAoC;IACpC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAA4B,CAAC;QACnD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC;QAC9E,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,4CAA4C;IAC5C,MAAM,MAAM,GAAG,MAAiC,CAAC;IACjD,IAAI,KAAK,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAE1C,4EAA4E;IAC5E,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1C,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAChE,MAAM,MAAM,GAAG,KAAgC,CAAC;YAChD,IAAI,KAAK,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAA4B,CAAC;YAClD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,IAAI,KAAK;gBAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,wBAAwB,CAAC,QAAsB,EAAE,KAAa;IAC5E,OAAO,sBAAsB,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAsB,EAAE,MAAgB;IACvE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IAErE,MAAM,IAAI,GAAG,CAAC,GAA4B,EAA2B,EAAE,CACrE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7E,IAAI,QAAgC,CAAC;IAErC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACnC,wBAAwB;QACxB,QAAQ,GAAI,QAAQ,CAAC,MAAoC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC;SAAM,CAAC;QACN,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAiC,CAAC;QAC1D,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC;QAEtD,IAAI,aAAa,EAAE,CAAC;YAClB,uBAAuB;YACvB,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,2EAA2E;YAC3E,QAAQ,GAAG,MAAM,CAAC,WAAW,CAC3B,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE;gBACpC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;oBACrB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAA+B,CAAC,CAAC,CAAC,CAAC;gBACrE,CAAC;gBACD,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;oBAC/B,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAA4B,CAAC,CAAC,CAAC;gBACjD,CAAC;gBACD,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAChB,CAAC,CAAC,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,GAAG,QAAQ;QACX,KAAK,EAAE,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,QAAoB,EAAE;QACvD,MAAM,EAAE,QAAQ;KACjB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"fieldExtraction.js","sourceRoot":"","sources":["../../src/fieldExtraction.ts"],"names":[],"mappings":"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"}

package/dist/src/flagResolver.d.ts

@@ -8,40 +8,106 @@
  */
 import { type FieldExtractionResolution } from './fieldExtraction.js';
 import { type FlagResolution } from './flagSemantics.js';
-/** Combined input for both format and field extraction layers. */
+/**
+ * Combined input for both format and field extraction layers.
+ *
+ * @remarks
+ * Merges the format-layer flags (sections 5.1-5.3) with the field extraction
+ * flags (section 9.2) into a single input object for {@link resolveFlags}.
+ */
 export interface UnifiedFlagInput {
+    /**
+     * Request human-readable output (`--human` flag).
+     * @defaultValue undefined
+     */
     human?: boolean;
+    /**
+     * Request JSON output (`--json` flag).
+     * @defaultValue undefined
+     */
     json?: boolean;
+    /**
+     * Suppress non-essential output for scripting (`--quiet` flag).
+     * @defaultValue undefined
+     */
     quiet?: boolean;
+    /**
+     * Explicit format override, taking highest precedence in the format layer.
+     * @defaultValue undefined
+     */
     requestedFormat?: 'json' | 'human';
+    /**
+     * Project-level default format from configuration.
+     * @defaultValue undefined
+     */
     projectDefault?: 'json' | 'human';
+    /**
+     * User-level default format from configuration.
+     * @defaultValue undefined
+     */
     userDefault?: 'json' | 'human';
     /**
      * TTY detection hint. When true, defaults to human format if no
      * explicit format flag or project/user default is set.
      * CLI tools should pass `process.stdout.isTTY ?? false`.
+     * @defaultValue undefined
      */
     tty?: boolean;
+    /**
+     * Extract a single field as plain text, discarding the envelope (`--field` flag).
+     * @defaultValue undefined
+     */
     field?: string;
+    /**
+     * Filter result to these fields while preserving the envelope (`--fields` flag).
+     * Accepts a comma-separated string or an array of field names.
+     * @defaultValue undefined
+     */
     fields?: string | string[];
+    /**
+     * Requested MVI verbosity level (`--mvi` flag).
+     * @defaultValue undefined
+     */
     mvi?: string;
 }
-/** Combined resolution result with cross-layer warnings. */
+/**
+ * Combined resolution result with cross-layer warnings.
+ *
+ * @remarks
+ * Contains the independently resolved format and field extraction layers plus
+ * any cross-layer interaction warnings produced during validation (section 5.4).
+ */
 export interface UnifiedFlagResolution {
-    /** Resolved format layer. */
+    /** Resolved format layer from the format precedence chain. */
     format: FlagResolution;
-    /** Resolved field extraction layer. */
+    /** Resolved field extraction layer from field/fields/mvi flags. */
     fields: FieldExtractionResolution;
-    /** Warnings for cross-layer interactions (non-fatal). */
+    /** Warnings for cross-layer interactions (non-fatal, informational only). */
     warnings: string[];
 }
 /**
  * Resolve all flags across both layers and validate cross-layer semantics.
  *
- * Per §5.4, cross-layer combinations are valid but MAY produce warnings.
- * Format-layer conflicts (E_FORMAT_CONFLICT) and field-layer conflicts
- * (E_FIELD_CONFLICT) still throw as before — they are delegated to the
- * existing single-layer resolvers.
+ * @param input - Combined format and field extraction flags
+ * @returns The unified resolution containing format, fields, and any cross-layer warnings
+ *
+ * @remarks
+ * Delegates to {@link resolveOutputFormat} for the format layer and
+ * {@link resolveFieldExtraction} for the field extraction layer, then performs
+ * cross-layer validation per section 5.4. Cross-layer combinations are valid but
+ * MAY produce informational warnings. Format-layer conflicts (`E_FORMAT_CONFLICT`)
+ * and field-layer conflicts (`E_FIELD_CONFLICT`) still throw as before; they are
+ * delegated to the existing single-layer resolvers.
+ *
+ * @example
+ * ```ts
+ * const result = resolveFlags({ human: true, field: 'title' });
+ * // result.format => { format: 'human', source: 'flag', quiet: false }
+ * // result.fields => { field: 'title', mvi: 'minimal', ... }
+ * // result.warnings => ['Cross-layer: --human + --field "title". ...']
+ * ```
+ *
+ * @throws {@link LAFSFlagError} When format or field layer flags conflict.
  */
 export declare function resolveFlags(input: UnifiedFlagInput): UnifiedFlagResolution;
 //# sourceMappingURL=flagResolver.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"flagResolver.d.ts","sourceRoot":"","sources":["../../src/flagResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,KAAK,yBAAyB,EAA0B,MAAM,sBAAsB,CAAC;AAC9F,OAAO,EAAE,KAAK,cAAc,EAAuB,MAAM,oBAAoB,CAAC;AAG9E,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAE/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IAEd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACpC,6BAA6B;IAC7B,MAAM,EAAE,cAAc,CAAC;IACvB,uCAAuC;IACvC,MAAM,EAAE,yBAAyB,CAAC;IAClC,yDAAyD;IACzD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,qBAAqB,CAqC3E"}
+{"version":3,"file":"flagResolver.d.ts","sourceRoot":"","sources":["../../src/flagResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,KAAK,yBAAyB,EAA0B,MAAM,sBAAsB,CAAC;AAC9F,OAAO,EAAE,KAAK,cAAc,EAAuB,MAAM,oBAAoB,CAAC;AAG9E;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,MAAM,EAAE,cAAc,CAAC;IACvB,mEAAmE;IACnE,MAAM,EAAE,yBAAyB,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,qBAAqB,CAqC3E"}

package/dist/src/flagResolver.js

@@ -11,10 +11,26 @@ import { resolveOutputFormat } from './flagSemantics.js';
 /**
  * Resolve all flags across both layers and validate cross-layer semantics.
  *
- * Per §5.4, cross-layer combinations are valid but MAY produce warnings.
- * Format-layer conflicts (E_FORMAT_CONFLICT) and field-layer conflicts
- * (E_FIELD_CONFLICT) still throw as before — they are delegated to the
- * existing single-layer resolvers.
+ * @param input - Combined format and field extraction flags
+ * @returns The unified resolution containing format, fields, and any cross-layer warnings
+ *
+ * @remarks
+ * Delegates to {@link resolveOutputFormat} for the format layer and
+ * {@link resolveFieldExtraction} for the field extraction layer, then performs
+ * cross-layer validation per section 5.4. Cross-layer combinations are valid but
+ * MAY produce informational warnings. Format-layer conflicts (`E_FORMAT_CONFLICT`)
+ * and field-layer conflicts (`E_FIELD_CONFLICT`) still throw as before; they are
+ * delegated to the existing single-layer resolvers.
+ *
+ * @example
+ * ```ts
+ * const result = resolveFlags({ human: true, field: 'title' });
+ * // result.format => { format: 'human', source: 'flag', quiet: false }
+ * // result.fields => { field: 'title', mvi: 'minimal', ... }
+ * // result.warnings => ['Cross-layer: --human + --field "title". ...']
+ * ```
+ *
+ * @throws {@link LAFSFlagError} When format or field layer flags conflict.
  */
 export function resolveFlags(input) {
     const formatInput = {

package/dist/src/flagResolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"flagResolver.js","sourceRoot":"","sources":["../../src/flagResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAkC,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9F,OAAO,EAAuB,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAkC9E;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAuB;IAClD,MAAM,WAAW,GAAc;QAC7B,SAAS,EAAE,KAAK,CAAC,KAAK;QACtB,QAAQ,EAAE,KAAK,CAAC,IAAI;QACpB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,GAAG,EAAE,KAAK,CAAC,GAAG;KACf,CAAC;IACF,MAAM,MAAM,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAEhD,MAAM,UAAU,GAAyB;QACvC,SAAS,EAAE,KAAK,CAAC,KAAK;QACtB,UAAU,EAAE,KAAK,CAAC,MAAM;QACxB,OAAO,EAAE,KAAK,CAAC,GAAG;KACnB,CAAC;IACF,MAAM,MAAM,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;IAElD,gCAAgC;IAChC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CACX,mCAAmC,MAAM,CAAC,KAAK,KAAK;YAClD,gEAAgE,CACnE,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3E,QAAQ,CAAC,IAAI,CACX,oCAAoC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YAC/D,+DAA+D,CAClE,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACtC,CAAC"}
+{"version":3,"file":"flagResolver.js","sourceRoot":"","sources":["../../src/flagResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAkC,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9F,OAAO,EAAuB,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAkF9E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAuB;IAClD,MAAM,WAAW,GAAc;QAC7B,SAAS,EAAE,KAAK,CAAC,KAAK;QACtB,QAAQ,EAAE,KAAK,CAAC,IAAI;QACpB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,GAAG,EAAE,KAAK,CAAC,GAAG;KACf,CAAC;IACF,MAAM,MAAM,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAEhD,MAAM,UAAU,GAAyB;QACvC,SAAS,EAAE,KAAK,CAAC,KAAK;QACtB,UAAU,EAAE,KAAK,CAAC,MAAM;QACxB,OAAO,EAAE,KAAK,CAAC,GAAG;KACnB,CAAC;IACF,MAAM,MAAM,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;IAElD,gCAAgC;IAChC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CACX,mCAAmC,MAAM,CAAC,KAAK,KAAK;YAClD,gEAAgE,CACnE,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3E,QAAQ,CAAC,IAAI,CACX,oCAAoC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YAC/D,+DAA+D,CAClE,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACtC,CAAC"}

package/dist/src/flagSemantics.d.ts

@@ -1,17 +1,92 @@
+/**
+ * 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 type { FlagInput, LAFSError, LAFSErrorCategory } from './types.js';
+/**
+ * Result of resolving output format flags.
+ *
+ * @remarks
+ * Captures both the resolved format and which configuration layer determined it,
+ * enabling diagnostics and cross-layer validation in the unified resolver.
+ */
 export interface FlagResolution {
+    /** The resolved output format: `'json'` for machine-readable or `'human'` for human-readable. */
     format: 'json' | 'human';
+    /** Which configuration layer determined the format value. */
     source: 'flag' | 'project' | 'user' | 'default';
-    /** When true, suppress non-essential output for scripting */
+    /** When true, suppress non-essential output for scripting. */
     quiet: boolean;
 }
+/**
+ * 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 declare class LAFSFlagError extends Error implements LAFSError {
+    /** The LAFS error code (e.g. `'E_FORMAT_CONFLICT'`). */
     code: string;
+    /** The error category resolved from the error registry. */
     category: LAFSErrorCategory;
+    /** Whether the operation that produced this error can be retried. */
     retryable: boolean;
+    /** Milliseconds to wait before retrying, or `null` if not applicable. */
     retryAfterMs: number | null;
+    /** Additional structured details about the error. */
     details: Record<string, unknown>;
+    /**
+     * 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: string, message: string, details?: Record<string, unknown>);
 }
+/**
+ * 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 declare function resolveOutputFormat(input: FlagInput): FlagResolution;
 //# sourceMappingURL=flagSemantics.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"flagSemantics.d.ts","sourceRoot":"","sources":["../../src/flagSemantics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE1E,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IAChD,6DAA6D;IAC7D,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,aAAc,SAAQ,KAAM,YAAW,SAAS;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAErB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAUjF;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,cAAc,CA+BpE"}
+{"version":3,"file":"flagSemantics.d.ts","sourceRoot":"","sources":["../../src/flagSemantics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,iGAAiG;IACjG,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IAChD,8DAA8D;IAC9D,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,qBAAa,aAAc,SAAQ,KAAM,YAAW,SAAS;IAC3D,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,qEAAqE;IACrE,SAAS,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC;;;;;;;;;;;;;;;;;;;OAmBG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAUjF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,cAAc,CA+BpE"}