@cleocode/lafs-protocol 1.4.0 → 1.5.0

package/dist/src/a2a/task-lifecycle.js

@@ -86,6 +86,15 @@ export class TaskNotFoundError extends Error {
         this.taskId = taskId;
     }
 }
+/** Thrown when a refinement/follow-up task references invalid parent tasks */
+export class TaskRefinementError extends Error {
+    referenceTaskIds;
+    constructor(message, referenceTaskIds) {
+        super(message);
+        this.name = 'TaskRefinementError';
+        this.referenceTaskIds = referenceTaskIds;
+    }
+}
 // ============================================================================
 // ID Generation
 // ============================================================================
@@ -106,7 +115,15 @@ export class TaskManager {
     /** Create a new task in the submitted state */
     createTask(options) {
         const id = generateId();
-        const contextId = options?.contextId ?? generateId();
+        const resolvedContextId = options?.contextId ?? this.resolveContextForReferenceTasks(options?.referenceTaskIds) ?? generateId();
+        const contextId = resolvedContextId;
+        const referenceTaskIds = options?.referenceTaskIds ?? [];
+        this.validateReferenceTasks(referenceTaskIds, contextId);
+        const metadata = {
+            ...(options?.metadata ?? {}),
+            ...(referenceTaskIds.length > 0 ? { referenceTaskIds } : {}),
+            ...(options?.parallelFollowUp ? { parallelFollowUp: true } : {}),
+        };
         const task = {
             id,
             contextId,
@@ -115,7 +132,7 @@ export class TaskManager {
                 state: 'submitted',
                 timestamp: new Date().toISOString(),
             },
-            ...(options?.metadata && { metadata: options.metadata }),
+            ...(Object.keys(metadata).length > 0 && { metadata }),
         };
         this.tasks.set(id, task);
         // Index by contextId
@@ -127,6 +144,14 @@ export class TaskManager {
         contextTasks.add(id);
         return structuredClone(task);
     }
+    /** Create a refinement/follow-up task referencing existing task(s). */
+    createRefinedTask(referenceTaskIds, options) {
+        return this.createTask({
+            ...options,
+            referenceTaskIds,
+            parallelFollowUp: options?.parallelFollowUp,
+        });
+    }
     /** Get a task by ID. Throws TaskNotFoundError if not found. */
     getTask(taskId) {
         const task = this.tasks.get(taskId);
@@ -249,6 +274,31 @@ export class TaskManager {
         }
         return isTerminalState(task.status.state);
     }
+    resolveContextForReferenceTasks(referenceTaskIds) {
+        if (!referenceTaskIds || referenceTaskIds.length === 0) {
+            return undefined;
+        }
+        const firstId = referenceTaskIds[0];
+        if (!firstId) {
+            return undefined;
+        }
+        const first = this.tasks.get(firstId);
+        return first?.contextId;
+    }
+    validateReferenceTasks(referenceTaskIds, contextId) {
+        if (referenceTaskIds.length === 0) {
+            return;
+        }
+        for (const refId of referenceTaskIds) {
+            const refTask = this.tasks.get(refId);
+            if (!refTask) {
+                throw new TaskRefinementError(`Referenced task not found: ${refId}`, referenceTaskIds);
+            }
+            if (refTask.contextId !== contextId) {
+                throw new TaskRefinementError(`Referenced task ${refId} has different contextId (${refTask.contextId}) than refinement (${contextId})`, referenceTaskIds);
+            }
+        }
+    }
 }
 // ============================================================================
 // LAFS Integration

package/dist/src/conformance.d.ts

@@ -1,3 +1,7 @@
 import type { ConformanceReport, FlagInput } from "./types.js";
-export declare function runEnvelopeConformance(envelope: unknown): ConformanceReport;
+import { type ConformanceTier } from "./conformanceProfiles.js";
+export interface EnvelopeConformanceOptions {
+    tier?: ConformanceTier;
+}
+export declare function runEnvelopeConformance(envelope: unknown, options?: EnvelopeConformanceOptions): ConformanceReport;
 export declare function runFlagConformance(flags: FlagInput): ConformanceReport;

package/dist/src/conformance.js

@@ -1,10 +1,12 @@
-import { isRegisteredErrorCode } from "./errorRegistry.js";
+import { getTransportMapping, isRegisteredErrorCode } from "./errorRegistry.js";
 import { resolveOutputFormat, LAFSFlagError } from "./flagSemantics.js";
+import { isMVILevel } from "./types.js";
+import { getChecksForTier } from "./conformanceProfiles.js";
 import { validateEnvelope } from "./validateEnvelope.js";
 function pushCheck(checks, name, pass, detail) {
     checks.push({ name, pass, ...(detail ? { detail } : {}) });
 }
-export function runEnvelopeConformance(envelope) {
+export function runEnvelopeConformance(envelope, options = {}) {
     const checks = [];
     const validation = validateEnvelope(envelope);
     pushCheck(checks, "envelope_schema_valid", validation.valid, validation.valid ? undefined : validation.errors.join("; "));
@@ -30,8 +32,52 @@ export function runEnvelopeConformance(envelope) {
     else {
         pushCheck(checks, "error_code_registered", true, "error field absent or null — skipped (optional when success=true)");
     }
-    const validMviLevels = ["minimal", "standard", "full", "custom"];
-    pushCheck(checks, "meta_mvi_present", validMviLevels.includes(typed._meta.mvi), validMviLevels.includes(typed._meta.mvi) ? undefined : `invalid mvi level: ${String(typed._meta.mvi)}`);
+    // transport_mapping_consistent: when an error is present, ensure the code has
+    // a transport-specific mapping in the registry for the declared transport.
+    if (typed.error) {
+        if (typed._meta.transport === "sdk") {
+            pushCheck(checks, "transport_mapping_consistent", true, "sdk transport does not require external status-code mapping");
+        }
+        else {
+            const mapping = getTransportMapping(typed.error.code, typed._meta.transport);
+            const mappingOk = mapping !== null;
+            pushCheck(checks, "transport_mapping_consistent", mappingOk, mappingOk
+                ? undefined
+                : `no ${typed._meta.transport} mapping found for code ${typed.error.code}`);
+        }
+    }
+    else {
+        pushCheck(checks, "transport_mapping_consistent", true, "no error present — mapping check skipped");
+    }
+    // context_mutation_failure: if the producer marks context as required for a
+    // mutation operation, missing context must fail with a context error code.
+    {
+        const ext = (typed._extensions ?? {});
+        const contextObj = (ext["context"] ?? {});
+        const lafsObj = (ext["lafs"] ?? {});
+        const contextRequired = ext["lafsContextRequired"] === true ||
+            contextObj["required"] === true ||
+            lafsObj["contextRequired"] === true;
+        if (!contextRequired) {
+            pushCheck(checks, "context_mutation_failure", true, "context not marked required — skipped");
+        }
+        else {
+            const hasContextIdentity = typed._meta.contextVersion > 0 || Boolean(typed._meta.sessionId);
+            if (typed.success) {
+                const pass = hasContextIdentity;
+                pushCheck(checks, "context_mutation_failure", pass, pass ? undefined : "context required but missing identity (expect E_CONTEXT_MISSING)");
+            }
+            else {
+                const code = typed.error?.code;
+                const pass = code === "E_CONTEXT_MISSING" || code === "E_CONTEXT_STALE";
+                pushCheck(checks, "context_mutation_failure", pass, pass
+                    ? undefined
+                    : `context required failures should return E_CONTEXT_MISSING or E_CONTEXT_STALE, got ${String(code)}`);
+            }
+        }
+    }
+    const mviValid = isMVILevel(typed._meta.mvi);
+    pushCheck(checks, "meta_mvi_present", mviValid, mviValid ? undefined : `invalid mvi level: ${String(typed._meta.mvi)}`);
     pushCheck(checks, "meta_strict_present", typeof typed._meta.strict === "boolean");
     // strict_mode_behavior: when strict=true, the envelope MUST NOT contain
     // explicit null for optional fields that can be omitted (page, error on success).
@@ -72,6 +118,9 @@ export function runEnvelopeConformance(envelope) {
         }
         pushCheck(checks, "pagination_mode_consistent", consistent, consistent ? undefined : detail);
     }
+    else {
+        pushCheck(checks, "pagination_mode_consistent", true, "page absent — skipped");
+    }
     // strict_mode_enforced: verify the schema enforces additional-property rules.
     // When strict=true, extra top-level properties must be rejected by validation.
     // When strict=false, extra top-level properties must be allowed.
@@ -85,7 +134,59 @@ export function runEnvelopeConformance(envelope) {
             pushCheck(checks, "strict_mode_enforced", extraResult.valid, !extraResult.valid ? "strict=false but additional properties were rejected" : undefined);
         }
     }
-    return { ok: checks.every((check) => check.pass), checks };
+    // context_preservation_valid: validate monotonic context version behavior and
+    // context-constraint integrity when a context ledger extension is present.
+    {
+        const ext = (typed._extensions ?? {});
+        const ledger = (ext["contextLedger"] ?? ext["context"]);
+        if (!ledger || typeof ledger !== "object") {
+            pushCheck(checks, "context_preservation_valid", true, "context ledger absent — skipped");
+        }
+        else {
+            const version = ledger["version"];
+            const previousVersion = ledger["previousVersion"];
+            const removedConstraints = ledger["removedConstraints"];
+            const hasNumericVersion = typeof version === "number";
+            const matchesEnvelopeVersion = hasNumericVersion && version === typed._meta.contextVersion;
+            const monotonicFromPrevious = typeof previousVersion !== "number" || (hasNumericVersion && version >= previousVersion);
+            const constraintsPreserved = !Array.isArray(removedConstraints) || removedConstraints.length === 0 || !typed.success;
+            let pass = matchesEnvelopeVersion && monotonicFromPrevious && constraintsPreserved;
+            let detail;
+            if (!hasNumericVersion) {
+                pass = false;
+                detail = "context ledger version must be numeric";
+            }
+            else if (!matchesEnvelopeVersion) {
+                detail = `context version mismatch: ledger=${String(version)} envelope=${typed._meta.contextVersion}`;
+            }
+            else if (!monotonicFromPrevious) {
+                detail = `non-monotonic context version: previous=${String(previousVersion)} current=${String(version)}`;
+            }
+            else if (!constraintsPreserved) {
+                detail = "context constraint removal detected on successful response";
+            }
+            // Error-path validation for stale/missing context signaling.
+            if (!typed.success && typed.error && ledger["required"] === true) {
+                const stale = ledger["stale"] === true;
+                if (stale && typed.error.code !== "E_CONTEXT_STALE") {
+                    pass = false;
+                    detail = `stale context should return E_CONTEXT_STALE, got ${typed.error.code}`;
+                }
+                if (!stale && typed.error.code !== "E_CONTEXT_MISSING" && typed.error.code !== "E_CONTEXT_STALE") {
+                    pass = false;
+                    detail = `required context failure should return E_CONTEXT_MISSING or E_CONTEXT_STALE, got ${typed.error.code}`;
+                }
+            }
+            pushCheck(checks, "context_preservation_valid", pass, detail);
+        }
+    }
+    const tier = options.tier;
+    if (!tier) {
+        return { ok: checks.every((check) => check.pass), checks };
+    }
+    const allowed = new Set(getChecksForTier(tier));
+    const tierChecks = checks.filter((check) => allowed.has(check.name));
+    return { ok: tierChecks.every((check) => check.pass), checks: tierChecks };
 }
 export function runFlagConformance(flags) {
     const checks = [];

package/dist/src/conformanceProfiles.d.ts

@@ -0,0 +1,11 @@
+export type ConformanceTier = "core" | "standard" | "complete";
+export interface ConformanceProfiles {
+    version: string;
+    tiers: Record<ConformanceTier, string[]>;
+}
+export declare function getConformanceProfiles(): ConformanceProfiles;
+export declare function getChecksForTier(tier: ConformanceTier): string[];
+export declare function validateConformanceProfiles(availableChecks: string[]): {
+    valid: boolean;
+    errors: string[];
+};

package/dist/src/conformanceProfiles.js

@@ -0,0 +1,34 @@
+import profilesJson from "../schemas/v1/conformance-profiles.json" with { type: "json" };
+export function getConformanceProfiles() {
+    return profilesJson;
+}
+export function getChecksForTier(tier) {
+    const profiles = getConformanceProfiles();
+    return profiles.tiers[tier] ?? [];
+}
+export function validateConformanceProfiles(availableChecks) {
+    const profiles = getConformanceProfiles();
+    const errors = [];
+    const core = new Set(profiles.tiers.core);
+    const standard = new Set(profiles.tiers.standard);
+    const complete = new Set(profiles.tiers.complete);
+    for (const check of core) {
+        if (!standard.has(check)) {
+            errors.push(`standard tier must include core check: ${check}`);
+        }
+    }
+    for (const check of standard) {
+        if (!complete.has(check)) {
+            errors.push(`complete tier must include standard check: ${check}`);
+        }
+    }
+    const known = new Set(availableChecks);
+    for (const [tier, checks] of Object.entries(profiles.tiers)) {
+        for (const check of checks) {
+            if (!known.has(check)) {
+                errors.push(`unknown check in ${tier} tier: ${check}`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

package/dist/src/deprecationRegistry.d.ts

@@ -0,0 +1,13 @@
+import type { LAFSEnvelope, Warning } from "./types.js";
+export interface DeprecationEntry {
+    id: string;
+    code: string;
+    message: string;
+    deprecated: string;
+    replacement?: string;
+    removeBy: string;
+    detector: (envelope: LAFSEnvelope) => boolean;
+}
+export declare function getDeprecationRegistry(): DeprecationEntry[];
+export declare function detectDeprecatedEnvelopeFields(envelope: LAFSEnvelope): Warning[];
+export declare function emitDeprecationWarnings(envelope: LAFSEnvelope): LAFSEnvelope;

package/dist/src/deprecationRegistry.js

@@ -0,0 +1,39 @@
+const DEPRECATION_REGISTRY = [
+    {
+        id: "meta-mvi-boolean",
+        code: "W_DEPRECATED_META_MVI_BOOLEAN",
+        message: "_meta.mvi boolean values are deprecated",
+        deprecated: "1.0.0",
+        replacement: "Use _meta.mvi as one of: minimal|standard|full|custom",
+        removeBy: "2.0.0",
+        detector: (envelope) => typeof envelope._meta.mvi === "boolean",
+    },
+];
+export function getDeprecationRegistry() {
+    return DEPRECATION_REGISTRY;
+}
+export function detectDeprecatedEnvelopeFields(envelope) {
+    return getDeprecationRegistry()
+        .filter((entry) => entry.detector(envelope))
+        .map((entry) => ({
+        code: entry.code,
+        message: entry.message,
+        deprecated: entry.deprecated,
+        replacement: entry.replacement,
+        removeBy: entry.removeBy,
+    }));
+}
+export function emitDeprecationWarnings(envelope) {
+    const detected = detectDeprecatedEnvelopeFields(envelope);
+    if (detected.length === 0) {
+        return envelope;
+    }
+    const existingWarnings = envelope._meta.warnings ?? [];
+    return {
+        ...envelope,
+        _meta: {
+            ...envelope._meta,
+            warnings: [...existingWarnings, ...detected],
+        },
+    };
+}

package/dist/src/errorRegistry.d.ts

@@ -11,5 +11,11 @@ export interface ErrorRegistry {
     version: string;
     codes: RegistryCode[];
 }
+export type TransportMapping = {
+    transport: "http" | "grpc" | "cli";
+    value: number | string;
+};
 export declare function getErrorRegistry(): ErrorRegistry;
 export declare function isRegisteredErrorCode(code: string): boolean;
+export declare function getRegistryCode(code: string): RegistryCode | undefined;
+export declare function getTransportMapping(code: string, transport: "http" | "grpc" | "cli"): TransportMapping | null;

package/dist/src/errorRegistry.js

@@ -6,3 +6,19 @@ export function isRegisteredErrorCode(code) {
     const registry = getErrorRegistry();
     return registry.codes.some((item) => item.code === code);
 }
+export function getRegistryCode(code) {
+    return getErrorRegistry().codes.find((item) => item.code === code);
+}
+export function getTransportMapping(code, transport) {
+    const registryCode = getRegistryCode(code);
+    if (!registryCode) {
+        return null;
+    }
+    if (transport === "http") {
+        return { transport, value: registryCode.httpStatus };
+    }
+    if (transport === "grpc") {
+        return { transport, value: registryCode.grpcStatus };
+    }
+    return { transport, value: registryCode.cliExit };
+}

package/dist/src/fieldExtraction.d.ts

@@ -0,0 +1,67 @@
+import type { LAFSEnvelope, MVILevel } from "./types.js";
+export interface FieldExtractionInput {
+    /** --field <name>: extract single field as plain text, no envelope */
+    fieldFlag?: string;
+    /** --fields <a,b,c>: filter result to these fields, preserve envelope */
+    fieldsFlag?: string | string[];
+    /** --mvi <level>: envelope verbosity (client-requestable levels only) */
+    mviFlag?: MVILevel | string;
+}
+export interface FieldExtractionResolution {
+    /** When set: extract this field as plain text, discard envelope. */
+    field?: string;
+    /** When set: filter result to these fields (envelope preserved). */
+    fields?: string[];
+    /** Resolved MVI level. Defaults to 'standard'. */
+    mvi: MVILevel;
+    /** 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.
+     * Separate from the client-resolved mvi level.
+     */
+    expectsCustomMvi: boolean;
+}
+export declare function resolveFieldExtraction(input: FieldExtractionInput): FieldExtractionResolution;
+/**
+ * Extract a named field from a LAFS result object.
+ *
+ * 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)
+ *
+ * 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().
+ *
+ * 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.
+ */
+export declare function extractFieldFromResult(result: LAFSEnvelope['result'], field: string): unknown;
+/** Convenience wrapper — extracts a field from an envelope's result. */
+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
+ *
+ * Sets _meta.mvi = 'custom' per §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.
+ *
+ * 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
+ * entity or array keys only, not to the wrapper's own primitive keys.
+ */
+export declare function applyFieldFilter(envelope: LAFSEnvelope, fields: string[]): LAFSEnvelope;

package/dist/src/fieldExtraction.js

@@ -0,0 +1,133 @@
+import { LAFSFlagError } from "./flagSemantics.js";
+import { isMVILevel } from "./types.js";
+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 '
+            + 'as plain text (no envelope); --fields filters the JSON envelope. '
+            + 'Use one or the other.', { conflictingModes: ['single-field-extraction', 'multi-field-filter'] });
+    }
+    const fields = typeof input.fieldsFlag === 'string'
+        ? input.fieldsFlag.split(',').map(f => f.trim()).filter(Boolean)
+        : Array.isArray(input.fieldsFlag)
+            ? input.fieldsFlag.map(f => f.trim()).filter(Boolean)
+            : undefined;
+    // 'custom' is server-set (§9.1) — not a client-requestable level
+    const validMvi = isMVILevel(input.mviFlag) && input.mviFlag !== 'custom';
+    const mvi = validMvi ? input.mviFlag : 'standard';
+    const mviSource = validMvi ? 'flag' : 'default';
+    const hasFields = (fields?.length ?? 0) > 0;
+    return {
+        field: input.fieldFlag || undefined,
+        fields: hasFields ? fields : undefined,
+        mvi,
+        mviSource,
+        expectsCustomMvi: hasFields,
+    };
+}
+/**
+ * Extract a named field from a LAFS result object.
+ *
+ * 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)
+ *
+ * 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().
+ *
+ * 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.
+ */
+export function extractFieldFromResult(result, field) {
+    if (result === null || typeof result !== 'object')
+        return undefined;
+    // Shape 1: result is a direct array
+    if (Array.isArray(result)) {
+        if (result.length === 0)
+            return undefined;
+        const first = result[0];
+        if (first && typeof first === 'object' && field in first)
+            return first[field];
+        return undefined;
+    }
+    // Shape 2: direct property on result object
+    const record = result;
+    if (field in record)
+        return record[field];
+    // Shapes 3 & 4: one level down (first matching key in insertion order wins)
+    for (const value of Object.values(record)) {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            const nested = value;
+            if (field in nested)
+                return nested[field];
+        }
+        if (Array.isArray(value) && value.length > 0) {
+            const first = value[0];
+            if (first && typeof first === 'object' && field in first)
+                return first[field];
+        }
+    }
+    return undefined;
+}
+/** Convenience wrapper — extracts a field from an envelope's result. */
+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
+ *
+ * Sets _meta.mvi = 'custom' per §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.
+ *
+ * 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
+ * entity or array keys only, not to the wrapper's own primitive keys.
+ */
+export function applyFieldFilter(envelope, fields) {
+    if (fields.length === 0 || envelope.result === null)
+        return envelope;
+    const pick = (obj) => Object.fromEntries(fields.filter(f => f in obj).map(f => [f, obj[f]]));
+    let filtered;
+    if (Array.isArray(envelope.result)) {
+        // Shape 1: direct array
+        filtered = envelope.result.map(pick);
+    }
+    else {
+        const record = envelope.result;
+        const topLevelMatch = fields.some(f => f in record);
+        if (topLevelMatch) {
+            // Shape 2: flat result
+            filtered = pick(record);
+        }
+        else {
+            // Shapes 3 & 4: wrapper — apply pick one level down, preserve wrapper keys
+            filtered = Object.fromEntries(Object.entries(record).map(([k, v]) => {
+                if (Array.isArray(v)) {
+                    return [k, v.map(item => pick(item))];
+                }
+                if (v && typeof v === 'object') {
+                    return [k, pick(v)];
+                }
+                return [k, v];
+            }));
+        }
+    }
+    return {
+        ...envelope,
+        _meta: { ...envelope._meta, mvi: 'custom' },
+        result: filtered,
+    };
+}

package/dist/src/flagSemantics.d.ts

@@ -1,12 +1,16 @@
-import type { FlagInput } from "./types.js";
+import type { FlagInput, LAFSError, LAFSErrorCategory } from "./types.js";
 export interface FlagResolution {
     format: "json" | "human";
     source: "flag" | "project" | "user" | "default";
     /** When true, suppress non-essential output for scripting */
     quiet: boolean;
 }
-export declare class LAFSFlagError extends Error {
+export declare class LAFSFlagError extends Error implements LAFSError {
     code: string;
-    constructor(code: string, message: string);
+    category: LAFSErrorCategory;
+    retryable: boolean;
+    retryAfterMs: number | null;
+    details: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
 }
 export declare function resolveOutputFormat(input: FlagInput): FlagResolution;

package/dist/src/flagSemantics.js

@@ -1,9 +1,19 @@
+import { getRegistryCode } from "./errorRegistry.js";
 export class LAFSFlagError extends Error {
     code;
-    constructor(code, message) {
+    category;
+    retryable;
+    retryAfterMs;
+    details;
+    constructor(code, message, details = {}) {
         super(message);
         this.name = "LAFSFlagError";
         this.code = code;
+        const entry = getRegistryCode(code);
+        this.category = (entry?.category ?? "CONTRACT");
+        this.retryable = entry?.retryable ?? false;
+        this.retryAfterMs = null;
+        this.details = details;
     }
 }
 export function resolveOutputFormat(input) {

package/dist/src/index.d.ts

@@ -1,9 +1,12 @@
 export * from "./types.js";
 export * from "./errorRegistry.js";
+export * from "./deprecationRegistry.js";
 export * from "./validateEnvelope.js";
 export * from "./envelope.js";
 export * from "./flagSemantics.js";
+export * from "./fieldExtraction.js";
 export * from "./conformance.js";
+export * from "./conformanceProfiles.js";
 export * from "./compliance.js";
 export * from "./tokenEstimator.js";
 export * from "./budgetEnforcement.js";
@@ -12,6 +15,6 @@ export * from "./discovery.js";
 export * from "./health/index.js";
 export * from "./shutdown/index.js";
 export * from "./circuit-breaker/index.js";
-export { LafsA2AResult, createLafsArtifact, createTextArtifact, createFileArtifact, isExtensionRequired, getExtensionParams, AGENT_CARD_PATH, HTTP_EXTENSION_HEADER, LAFS_EXTENSION_URI, A2A_EXTENSIONS_HEADER, parseExtensionsHeader, negotiateExtensions, formatExtensionsHeader, buildLafsExtension, ExtensionSupportRequiredError, extensionNegotiationMiddleware, TERMINAL_STATES, INTERRUPTED_STATES, VALID_TRANSITIONS, isValidTransition, isTerminalState, isInterruptedState, InvalidStateTransitionError, TaskImmutabilityError, TaskNotFoundError, TaskManager, attachLafsEnvelope, } from "./a2a/index.js";
-export type { LafsA2AConfig, LafsSendMessageParams, LafsExtensionParams, ExtensionNegotiationResult, BuildLafsExtensionOptions, ExtensionNegotiationMiddlewareOptions, CreateTaskOptions, ListTasksOptions, ListTasksResult, } from "./a2a/index.js";
+export { LafsA2AResult, createLafsArtifact, createTextArtifact, createFileArtifact, isExtensionRequired, getExtensionParams, AGENT_CARD_PATH, HTTP_EXTENSION_HEADER, LAFS_EXTENSION_URI, A2A_EXTENSIONS_HEADER, parseExtensionsHeader, negotiateExtensions, formatExtensionsHeader, buildLafsExtension, ExtensionSupportRequiredError, extensionNegotiationMiddleware, TERMINAL_STATES, INTERRUPTED_STATES, VALID_TRANSITIONS, isValidTransition, isTerminalState, isInterruptedState, InvalidStateTransitionError, TaskImmutabilityError, TaskNotFoundError, TaskRefinementError, TaskManager, attachLafsEnvelope, TaskEventBus, PushNotificationConfigStore, PushNotificationDispatcher, TaskArtifactAssembler, streamTaskEvents, } from "./a2a/index.js";
+export type { LafsA2AConfig, LafsSendMessageParams, LafsExtensionParams, ExtensionNegotiationResult, BuildLafsExtensionOptions, ExtensionNegotiationMiddlewareOptions, CreateTaskOptions, ListTasksOptions, ListTasksResult, TaskStreamEvent, StreamIteratorOptions, PushNotificationDeliveryResult, PushTransport, } from "./a2a/index.js";
 export type { Task, TaskState, TaskStatus, Artifact, Part, Message, PushNotificationConfig, MessageSendConfiguration, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, SendMessageResponse, SendMessageSuccessResponse, JSONRPCErrorResponse, TextPart, DataPart, FilePart, } from "./a2a/index.js";