@cleocode/lafs-protocol 1.3.2 → 1.4.1

package/dist/src/a2a/task-lifecycle.d.ts

@@ -38,10 +38,17 @@ export declare class TaskNotFoundError extends Error {
     readonly taskId: string;
     constructor(taskId: string);
 }
+/** Thrown when a refinement/follow-up task references invalid parent tasks */
+export declare class TaskRefinementError extends Error {
+    readonly referenceTaskIds: string[];
+    constructor(message: string, referenceTaskIds: string[]);
+}
 /** Options for creating a new task */
 export interface CreateTaskOptions {
     contextId?: string;
     metadata?: Record<string, unknown>;
+    referenceTaskIds?: string[];
+    parallelFollowUp?: boolean;
 }
 /** Options for listing tasks */
 export interface ListTasksOptions {
@@ -64,6 +71,8 @@ export declare class TaskManager {
     private contextIndex;
     /** Create a new task in the submitted state */
     createTask(options?: CreateTaskOptions): Task;
+    /** Create a refinement/follow-up task referencing existing task(s). */
+    createRefinedTask(referenceTaskIds: string[], options?: Omit<CreateTaskOptions, 'referenceTaskIds'>): Task;
     /** Get a task by ID. Throws TaskNotFoundError if not found. */
     getTask(taskId: string): Task;
     /** List tasks with optional filtering and pagination */
@@ -90,6 +99,8 @@ export declare class TaskManager {
     getTasksByContext(contextId: string): Task[];
     /** Check if a task is in a terminal state */
     isTerminal(taskId: string): boolean;
+    private resolveContextForReferenceTasks;
+    private validateReferenceTasks;
 }
 /**
  * Attach a LAFS envelope as an artifact to an A2A task.

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/compliance.d.ts

@@ -0,0 +1,31 @@
+import type { ConformanceReport, FlagInput, LAFSEnvelope } from "./types.js";
+import { type EnvelopeValidationResult } from "./validateEnvelope.js";
+export type ComplianceStage = "schema" | "envelope" | "flags" | "format";
+export interface ComplianceIssue {
+    stage: ComplianceStage;
+    message: string;
+    detail?: string;
+}
+export interface EnforceComplianceOptions {
+    checkConformance?: boolean;
+    checkFlags?: boolean;
+    flags?: FlagInput;
+    requireJsonOutput?: boolean;
+}
+export interface ComplianceResult {
+    ok: boolean;
+    envelope?: LAFSEnvelope;
+    validation: EnvelopeValidationResult;
+    envelopeConformance?: ConformanceReport;
+    flagConformance?: ConformanceReport;
+    issues: ComplianceIssue[];
+}
+export declare class ComplianceError extends Error {
+    readonly issues: ComplianceIssue[];
+    constructor(issues: ComplianceIssue[]);
+}
+export declare function enforceCompliance(input: unknown, options?: EnforceComplianceOptions): ComplianceResult;
+export declare function assertCompliance(input: unknown, options?: EnforceComplianceOptions): LAFSEnvelope;
+export declare function withCompliance<TArgs extends unknown[], TResult extends LAFSEnvelope>(producer: (...args: TArgs) => TResult | Promise<TResult>, options?: EnforceComplianceOptions): (...args: TArgs) => Promise<LAFSEnvelope>;
+export type ComplianceMiddleware = (envelope: LAFSEnvelope, next: () => LAFSEnvelope | Promise<LAFSEnvelope>) => Promise<LAFSEnvelope> | LAFSEnvelope;
+export declare function createComplianceMiddleware(options?: EnforceComplianceOptions): ComplianceMiddleware;

package/dist/src/compliance.js

@@ -0,0 +1,89 @@
+import { runEnvelopeConformance, runFlagConformance } from "./conformance.js";
+import { resolveOutputFormat } from "./flagSemantics.js";
+import { assertEnvelope, validateEnvelope } from "./validateEnvelope.js";
+export class ComplianceError extends Error {
+    issues;
+    constructor(issues) {
+        super(`LAFS compliance failed: ${issues.map((issue) => issue.message).join("; ")}`);
+        this.name = "ComplianceError";
+        this.issues = issues;
+    }
+}
+function conformanceIssues(report, stage) {
+    return report.checks
+        .filter((check) => !check.pass)
+        .map((check) => ({
+        stage,
+        message: `${check.name} failed`,
+        detail: check.detail,
+    }));
+}
+export function enforceCompliance(input, options = {}) {
+    const { checkConformance = true, checkFlags = false, flags, requireJsonOutput = false, } = options;
+    const issues = [];
+    const validation = validateEnvelope(input);
+    if (!validation.valid) {
+        issues.push(...validation.errors.map((error) => ({
+            stage: "schema",
+            message: "schema validation failed",
+            detail: error,
+        })));
+        return {
+            ok: false,
+            validation,
+            issues,
+        };
+    }
+    const envelope = assertEnvelope(input);
+    let envelopeConformance;
+    if (checkConformance) {
+        envelopeConformance = runEnvelopeConformance(envelope);
+        if (!envelopeConformance.ok) {
+            issues.push(...conformanceIssues(envelopeConformance, "envelope"));
+        }
+    }
+    let flagConformance;
+    if (checkFlags && flags) {
+        flagConformance = runFlagConformance(flags);
+        if (!flagConformance.ok) {
+            issues.push(...conformanceIssues(flagConformance, "flags"));
+        }
+    }
+    if (requireJsonOutput) {
+        const resolved = resolveOutputFormat(flags ?? {});
+        if (resolved.format !== "json") {
+            issues.push({
+                stage: "format",
+                message: "non-json output format resolved",
+                detail: `resolved format is ${resolved.format}`,
+            });
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        envelope,
+        validation,
+        envelopeConformance,
+        flagConformance,
+        issues,
+    };
+}
+export function assertCompliance(input, options = {}) {
+    const result = enforceCompliance(input, options);
+    if (!result.ok || !result.envelope) {
+        throw new ComplianceError(result.issues);
+    }
+    return result.envelope;
+}
+export function withCompliance(producer, options = {}) {
+    return async (...args) => {
+        const envelope = await producer(...args);
+        return assertCompliance(envelope, options);
+    };
+}
+export function createComplianceMiddleware(options = {}) {
+    return async (_envelope, next) => {
+        const candidate = await next();
+        return assertCompliance(candidate, options);
+    };
+}

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,11 @@
-import { isRegisteredErrorCode } from "./errorRegistry.js";
+import { getTransportMapping, isRegisteredErrorCode } from "./errorRegistry.js";
 import { resolveOutputFormat, LAFSFlagError } from "./flagSemantics.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,6 +31,50 @@ export function runEnvelopeConformance(envelope) {
     else {
         pushCheck(checks, "error_code_registered", true, "error field absent or null — skipped (optional when success=true)");
     }
+    // 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 validMviLevels = ["minimal", "standard", "full", "custom"];
     pushCheck(checks, "meta_mvi_present", validMviLevels.includes(typed._meta.mvi), validMviLevels.includes(typed._meta.mvi) ? undefined : `invalid mvi level: ${String(typed._meta.mvi)}`);
     pushCheck(checks, "meta_strict_present", typeof typed._meta.strict === "boolean");
@@ -72,6 +117,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 +133,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/envelope.d.ts

@@ -0,0 +1,46 @@
+import type { LAFSEnvelope, LAFSError, LAFSErrorCategory, LAFSMeta, LAFSTransport, MVILevel } from "./types.js";
+export declare const LAFS_SCHEMA_URL: "https://lafs.dev/schemas/v1/envelope.schema.json";
+export interface CreateEnvelopeMetaInput {
+    operation: string;
+    requestId: string;
+    transport?: LAFSTransport;
+    specVersion?: string;
+    schemaVersion?: string;
+    timestamp?: string;
+    strict?: boolean;
+    mvi?: MVILevel | boolean;
+    contextVersion?: number;
+    sessionId?: string;
+    warnings?: LAFSMeta["warnings"];
+}
+export interface CreateEnvelopeSuccessInput {
+    success: true;
+    result: LAFSEnvelope["result"];
+    page?: LAFSEnvelope["page"];
+    error?: null;
+    _extensions?: LAFSEnvelope["_extensions"];
+    meta: CreateEnvelopeMetaInput;
+}
+export interface CreateEnvelopeErrorInput {
+    success: false;
+    error: Partial<LAFSError> & Pick<LAFSError, "code" | "message">;
+    result?: null;
+    page?: LAFSEnvelope["page"];
+    _extensions?: LAFSEnvelope["_extensions"];
+    meta: CreateEnvelopeMetaInput;
+}
+export type CreateEnvelopeInput = CreateEnvelopeSuccessInput | CreateEnvelopeErrorInput;
+export declare function createEnvelope(input: CreateEnvelopeInput): LAFSEnvelope;
+export declare class LafsError extends Error implements LAFSError {
+    code: string;
+    category: LAFSErrorCategory;
+    retryable: boolean;
+    retryAfterMs: number | null;
+    details: Record<string, unknown>;
+    registered: boolean;
+    constructor(error: LAFSError);
+}
+export interface ParseLafsResponseOptions {
+    requireRegisteredErrorCode?: boolean;
+}
+export declare function parseLafsResponse<T = unknown>(input: unknown, options?: ParseLafsResponseOptions): T;

package/dist/src/envelope.js

@@ -0,0 +1,89 @@
+import { isRegisteredErrorCode } from "./errorRegistry.js";
+import { assertEnvelope } from "./validateEnvelope.js";
+export const LAFS_SCHEMA_URL = "https://lafs.dev/schemas/v1/envelope.schema.json";
+function resolveMviLevel(input) {
+    if (typeof input === "boolean") {
+        return input ? "minimal" : "standard";
+    }
+    return input ?? "standard";
+}
+function createMeta(input) {
+    return {
+        specVersion: input.specVersion ?? "1.0.0",
+        schemaVersion: input.schemaVersion ?? "1.0.0",
+        timestamp: input.timestamp ?? new Date().toISOString(),
+        operation: input.operation,
+        requestId: input.requestId,
+        transport: input.transport ?? "sdk",
+        strict: input.strict ?? true,
+        mvi: resolveMviLevel(input.mvi),
+        contextVersion: input.contextVersion ?? 0,
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        ...(input.warnings ? { warnings: input.warnings } : {}),
+    };
+}
+function normalizeError(error) {
+    return {
+        code: error.code,
+        message: error.message,
+        category: (error.category ?? "INTERNAL"),
+        retryable: error.retryable ?? false,
+        retryAfterMs: error.retryAfterMs ?? null,
+        details: error.details ?? {},
+    };
+}
+export function createEnvelope(input) {
+    const meta = createMeta(input.meta);
+    if (input.success) {
+        return {
+            $schema: LAFS_SCHEMA_URL,
+            _meta: meta,
+            success: true,
+            result: input.result,
+            ...(input.page !== undefined ? { page: input.page } : {}),
+            ...(input.error !== undefined ? { error: null } : {}),
+            ...(input._extensions !== undefined ? { _extensions: input._extensions } : {}),
+        };
+    }
+    return {
+        $schema: LAFS_SCHEMA_URL,
+        _meta: meta,
+        success: false,
+        result: null,
+        error: normalizeError(input.error),
+        ...(input.page !== undefined ? { page: input.page } : {}),
+        ...(input._extensions !== undefined ? { _extensions: input._extensions } : {}),
+    };
+}
+export class LafsError extends Error {
+    code;
+    category;
+    retryable;
+    retryAfterMs;
+    details;
+    registered;
+    constructor(error) {
+        super(error.message);
+        this.name = "LafsError";
+        this.code = error.code;
+        this.category = error.category;
+        this.retryable = error.retryable;
+        this.retryAfterMs = error.retryAfterMs;
+        this.details = error.details;
+        this.registered = isRegisteredErrorCode(error.code);
+    }
+}
+export function parseLafsResponse(input, options = {}) {
+    const envelope = assertEnvelope(input);
+    if (envelope.success) {
+        return envelope.result;
+    }
+    const error = envelope.error;
+    if (!error) {
+        throw new Error("Invalid LAFS envelope: success=false requires error object");
+    }
+    if (options.requireRegisteredErrorCode && !isRegisteredErrorCode(error.code)) {
+        throw new Error(`Unregistered LAFS error code: ${error.code}`);
+    }
+    throw new LafsError(error);
+}

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 };
+}