@cleocode/lafs-protocol 1.3.2 → 1.4.0

package/README.md

@@ -4,7 +4,7 @@
 
 LAFS defines a standard envelope format for structured responses from LLM-powered agents and tools. It complements transport protocols like [MCP](https://modelcontextprotocol.io/) and [A2A](https://github.com/google/A2A) by standardizing what comes back — not how it gets there.
 
-**Current version:** 1.3.1 | [📚 Documentation](https://codluv.gitbook.io/lafs-protocol/) | [Spec](lafs.md) | [Migration Guides](migrations/)
+**Current version:** 1.4.0 | [📚 Documentation](https://codluv.gitbook.io/lafs-protocol/) | [Spec](lafs.md) | [Migration Guides](migrations/)
 
 [![GitBook](https://img.shields.io/badge/docs-gitbook-blue)](https://codluv.gitbook.io/lafs-protocol/)
 [![npm](https://img.shields.io/npm/v/@cleocode/lafs-protocol)](https://www.npmjs.com/package/@cleocode/lafs-protocol)
@@ -33,15 +33,35 @@ npm install @cleocode/lafs-protocol
 
 ```typescript
 import {
+  createEnvelope,
+  parseLafsResponse,
+  LafsError,
   validateEnvelope,
   runEnvelopeConformance,
   isRegisteredErrorCode,
 } from "@cleocode/lafs-protocol";
 
+// Build envelope with defaults
+const envelope = createEnvelope({
+  success: true,
+  result: { items: [] },
+  meta: { operation: "example.list", requestId: "req_1" },
+});
+
 // Validate an envelope against the schema
-const result = validateEnvelope(envelope);
-if (!result.valid) {
-  console.error(result.errors);
+const validation = validateEnvelope(envelope);
+if (!validation.valid) {
+  console.error(validation.errors);
+}
+
+// Parse envelope responses with one function
+try {
+  const parsed = parseLafsResponse(envelope);
+  console.log(parsed);
+} catch (error) {
+  if (error instanceof LafsError) {
+    console.error(error.code, error.message);
+  }
 }
 
 // Run full conformance suite (schema + invariants + error codes + strict mode + pagination)
@@ -49,6 +69,13 @@ const report = runEnvelopeConformance(envelope);
 console.log(report.ok); // true if all checks pass
 ```
 
+## LLM-agent implementation guides
+
+- `docs/guides/llm-agent-guide.md` - parser, success/error handling, strict JSON policy
+- `docs/guides/schema-extension.md` - operation-specific result validation on top of core schema
+- `docs/guides/compliance-pipeline.md` - generation middleware with validate + conformance gates
+- `docs/llms.txt` - LLM-oriented index and canonical sources
+
 ## CLI
 
 ```bash

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

@@ -1,8 +1,10 @@
 export * from "./types.js";
 export * from "./errorRegistry.js";
 export * from "./validateEnvelope.js";
+export * from "./envelope.js";
 export * from "./flagSemantics.js";
 export * from "./conformance.js";
+export * from "./compliance.js";
 export * from "./tokenEstimator.js";
 export * from "./budgetEnforcement.js";
 export * from "./mcpAdapter.js";

package/dist/src/index.js

@@ -1,8 +1,10 @@
 export * from "./types.js";
 export * from "./errorRegistry.js";
 export * from "./validateEnvelope.js";
+export * from "./envelope.js";
 export * from "./flagSemantics.js";
 export * from "./conformance.js";
+export * from "./compliance.js";
 export * from "./tokenEstimator.js";
 export * from "./budgetEnforcement.js";
 export * from "./mcpAdapter.js";

package/lafs.md

@@ -1,7 +1,7 @@
 # LAFS: LLM-Agent-First Specification
 
 > 📚 **Documentation:** https://codluv.gitbook.io/lafs-protocol/  
-> **Version:** 1.3.1 | **Status:** Production Ready
+> **Version:** 1.4.0 | **Status:** Production Ready
 
 ## 1. Scope
 
@@ -130,7 +130,7 @@ All responses MUST conform to `schemas/v1/envelope.schema.json`.
     "requestId": "req_123",
     "transport": "cli",
     "strict": true,
-    "mvi": true,
+    "mvi": "standard",
     "contextVersion": 0
   },
   "success": true,
@@ -142,7 +142,6 @@ All responses MUST conform to `schemas/v1/envelope.schema.json`.
 
 ### 6.1 Envelope invariants
 
-- Exactly one of `result` or `error` MUST be non-null.
 - `success=true` implies `error=null` or error omitted.
 - `success=false` implies `result=null` and `error` MUST be present.
 - The `page` and `error` fields are optional when their value would be null. In strict mode, producers SHOULD omit these fields rather than set them to null.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/lafs-protocol",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "private": false,
   "type": "module",
   "description": "LLM-Agent-First Specification schemas and conformance tooling",
@@ -22,7 +22,11 @@
     "./a2a/bindings": {
       "import": "./dist/src/a2a/bindings/index.js",
       "types": "./dist/src/a2a/bindings/index.d.ts"
-    }
+    },
+    "./schemas/v1/envelope.schema.json": "./schemas/v1/envelope.schema.json",
+    "./schemas/v1/error-registry.json": "./schemas/v1/error-registry.json",
+    "./schemas/v1/context-ledger.schema.json": "./schemas/v1/context-ledger.schema.json",
+    "./schemas/v1/discovery.schema.json": "./schemas/v1/discovery.schema.json"
   },
   "files": [
     "dist",