@cleocode/lafs-protocol 0.1.0 → 0.5.0

package/README.md

@@ -1,45 +1,151 @@
-# lafs-protocol
+# LAFS Protocol
 
-LLM-Agent-First Specification (LAFS) as a standalone protocol repository.
+**LLM-Agent-First Specification** — a response envelope contract for AI agent systems.
 
-This repository is language-neutral at the protocol layer and TypeScript-first for reference tooling.
+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.
 
-## What this repo provides
+**Current version:** 0.5.0 | [Spec](lafs.md) | [Migration Guides](migrations/)
 
-- Canonical protocol spec: `lafs.md`
-- Versioned JSON schemas: `schemas/v1/`
-- Error registry and transport mappings: `schemas/v1/error-registry.json`
-- TypeScript validation/conformance toolkit: `src/`
-- Automated conformance tests: `tests/`
+## What LAFS provides
+
+| Layer | Files | Description |
+|-------|-------|-------------|
+| **Spec** | `lafs.md` | Protocol specification with RFC 2119 language |
+| **Schemas** | `schemas/v1/envelope.schema.json` | Envelope schema (Draft-07) with conditional pagination validation |
+| | `schemas/v1/context-ledger.schema.json` | Context ledger for state tracking across request/response cycles |
+| | `schemas/v1/error-registry.json` | 12 registered error codes with HTTP/gRPC/CLI transport mappings |
+| **Tooling** | `src/` | TypeScript validation, conformance runner, CLI diagnostic tool |
+| **Tests** | `tests/` | 31 tests covering envelope, pagination, strict mode, error handling |
+| **Fixtures** | `fixtures/` | 14 JSON fixtures (valid + invalid) for conformance testing |
+| **Docs** | `docs/` | Positioning, vision, conformance tiers, deprecation policy |
 
 ## Install
 
 ```bash
-npm install
+npm install @cleocode/lafs-protocol
+```
+
+## Usage
+
+```typescript
+import {
+  validateEnvelope,
+  runEnvelopeConformance,
+  isRegisteredErrorCode,
+} from "@cleocode/lafs-protocol";
+
+// Validate an envelope against the schema
+const result = validateEnvelope(envelope);
+if (!result.valid) {
+  console.error(result.errors);
+}
+
+// Run full conformance suite (schema + invariants + error codes + strict mode + pagination)
+const report = runEnvelopeConformance(envelope);
+console.log(report.ok); // true if all checks pass
 ```
 
-## Commands
+## CLI
 
 ```bash
-npm run typecheck
+# Run conformance checks on a fixture
+npm run conformance -- --envelope fixtures/valid-success-envelope.json
+
+# Run tests
 npm test
-npm run conformance -- --envelope fixtures/valid-success-envelope.json --flags fixtures/flags-valid.json
+
+# Type check
+npm run typecheck
 ```
 
-## Canonical policy
+## Envelope structure
 
-- JSON default output is REQUIRED.
-- Human-readable output is explicit opt-in (`--human`).
-- `--json` is optional but recommended explicit alias/override.
-- `--human --json` is invalid and MUST fail with `E_FORMAT_CONFLICT`.
+```json
+{
+  "$schema": "https://lafs.dev/schemas/v1/envelope.schema.json",
+  "_meta": {
+    "specVersion": "0.5.0",
+    "schemaVersion": "1.0.0",
+    "timestamp": "2026-02-13T00:00:00Z",
+    "operation": "example.list",
+    "requestId": "req_01",
+    "transport": "http",
+    "strict": true,
+    "mvi": "standard",
+    "contextVersion": 1
+  },
+  "success": true,
+  "result": { "items": [{ "id": "1", "title": "Example" }] },
+  "page": {
+    "mode": "cursor",
+    "nextCursor": "eyJpZCI6IjEwIn0=",
+    "hasMore": true
+  }
+}
+```
+
+## Key features
+
+- **Conditional pagination** — cursor, offset, and none modes with mode-specific required fields
+- **Strict/lenient mode** — `strict: true` rejects unknown properties; `strict: false` allows them
+- **MVI disclosure levels** — `minimal`, `standard`, `full`, `custom` control response verbosity
+- **Field selection** (`_fields`) and **expansion** (`_expand`) request parameters
+- **Context ledger** — tracks state across request/response cycles with monotonic versioning
+- **Error registry** — 12 codes with category, retryability, and transport-specific status mappings
+- **Extension mechanism** — `_extensions` field for vendor metadata (`x-` prefix convention)
+- **Adoption tiers** — Core, Standard, Complete with progressive conformance requirements
+
+## Conformance checks
+
+| Check | Description | Tier |
+|-------|-------------|------|
+| `envelope_schema_valid` | Validates against JSON Schema | Core |
+| `envelope_invariants` | success/result/error consistency | Core |
+| `error_code_registered` | Error code exists in registry | Core |
+| `meta_mvi_present` | Valid MVI disclosure level | Standard |
+| `meta_strict_present` | Strict mode declared | Standard |
+| `strict_mode_behavior` | Optional fields omitted (not null) in strict mode | Standard |
+| `strict_mode_enforced` | Additional properties rejected/allowed per mode | Standard |
+| `pagination_mode_consistent` | Page fields match declared mode | Standard |
 
-## Layout
+## Project layout
 
-```text
-lafs.md
+```
+lafs.md                          # Protocol specification
 schemas/v1/
+  envelope.schema.json           # Envelope schema (Draft-07)
+  context-ledger.schema.json     # Context ledger schema
+  error-registry.json            # Error code registry
 src/
-tests/
-fixtures/
+  types.ts                       # TypeScript types (discriminated unions)
+  validateEnvelope.ts            # Ajv-based schema validator
+  conformance.ts                 # Conformance runner (8 checks)
+  errorRegistry.ts               # Error code helpers
+  flagSemantics.ts               # Format flag resolution
+  cli.ts                         # CLI diagnostic tool
+tests/                           # 31 tests (vitest)
+fixtures/                        # 14 JSON test fixtures
 docs/
+  POSITIONING.md                 # MCP/A2A complementary positioning
+  VISION.md                      # Project vision and primary persona
+  CONFORMANCE.md                 # Conformance checks and adoption tiers
+migrations/
+  v0.3.0-to-v0.4.0.md           # Envelope rationalization migration
+  v0.4.0-to-v0.5.0.md           # Pagination & MVI schema migration
+CONTRIBUTING.md                  # Contributor guidelines, RFC process
 ```
+
+## Version history
+
+| Version | Phase | Description |
+|---------|-------|-------------|
+| v0.5.0 | 2B | Conditional pagination, MVI field selection/expansion, context ledger schema |
+| v0.4.0 | 2A | Optional page/error, extensions, strict/lenient mode, warnings |
+| v0.3.0 | 1 | Strategic positioning, vision alignment, adoption tiers |
+| v0.2.0 | 0 | Protocol cleanup, fixtures, governance, security considerations |
+| v0.1.1 | — | Initial npm publish |
+| v0.1.0 | — | Bootstrap |
+
+## License
+
+MIT

package/dist/schemas/v1/envelope.schema.json

@@ -3,14 +3,11 @@
     "$id": "https://lafs.dev/schemas/v1/envelope.schema.json",
     "title": "LAFS Envelope v1",
     "type": "object",
-    "additionalProperties": false,
     "required": [
         "$schema",
         "_meta",
         "success",
-        "result",
-        "error",
-        "page"
+        "result"
     ],
     "properties": {
         "$schema": {
@@ -62,11 +59,28 @@
                     "type": "boolean"
                 },
                 "mvi": {
-                    "type": "boolean"
+                    "type": "string",
+                    "enum": ["minimal", "standard", "full", "custom"],
+                    "description": "Disclosure level: minimal (MVI only), standard (common fields), full (all fields), custom (per _fields parameter)"
                 },
                 "contextVersion": {
                     "type": "integer",
                     "minimum": 0
+                },
+                "warnings": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "code": { "type": "string", "description": "Warning identifier (e.g., DEPRECATED_FIELD)" },
+                            "message": { "type": "string", "description": "Human-readable warning" },
+                            "deprecated": { "type": "string", "description": "The deprecated feature or field name" },
+                            "replacement": { "type": "string", "description": "Suggested replacement, if any" },
+                            "removeBy": { "type": "string", "description": "Version when the deprecated feature will be removed" }
+                        },
+                        "required": ["code", "message"]
+                    },
+                    "description": "Non-fatal advisory warnings (deprecations, migration hints)"
                 }
             }
         },
@@ -127,14 +141,7 @@
         "page": {
             "type": ["object", "null"],
             "additionalProperties": false,
-            "required": [
-                "mode",
-                "limit",
-                "offset",
-                "nextCursor",
-                "hasMore",
-                "total"
-            ],
+            "required": ["mode"],
             "properties": {
                 "mode": {
                     "type": "string",
@@ -160,7 +167,61 @@
                     "type": ["integer", "null"],
                     "minimum": 0
                 }
-            }
+            },
+            "allOf": [
+                {
+                    "if": {
+                        "type": "object",
+                        "properties": { "mode": { "const": "cursor" } },
+                        "required": ["mode"]
+                    },
+                    "then": {
+                        "required": ["mode", "nextCursor", "hasMore"],
+                        "properties": {
+                            "mode": true,
+                            "nextCursor": true,
+                            "hasMore": true,
+                            "limit": true,
+                            "total": true
+                        }
+                    }
+                },
+                {
+                    "if": {
+                        "type": "object",
+                        "properties": { "mode": { "const": "offset" } },
+                        "required": ["mode"]
+                    },
+                    "then": {
+                        "required": ["mode", "limit", "offset", "hasMore"],
+                        "properties": {
+                            "mode": true,
+                            "limit": true,
+                            "offset": true,
+                            "hasMore": true,
+                            "total": true
+                        }
+                    }
+                },
+                {
+                    "if": {
+                        "type": "object",
+                        "properties": { "mode": { "const": "none" } },
+                        "required": ["mode"]
+                    },
+                    "then": {
+                        "required": ["mode"],
+                        "properties": {
+                            "mode": true
+                        }
+                    }
+                }
+            ]
+        },
+        "_extensions": {
+            "type": "object",
+            "description": "Vendor extensions. Keys SHOULD use x- prefix (e.g., x-myvendor-trace-id).",
+            "additionalProperties": true
         }
     },
     "allOf": [
@@ -183,11 +244,39 @@
                 }
             },
             "then": {
+                "required": ["error"],
                 "properties": {
                     "result": { "type": "null" },
                     "error": { "type": "object" }
                 }
             }
+        },
+        {
+            "if": {
+                "properties": {
+                    "_meta": {
+                        "type": "object",
+                        "properties": {
+                            "strict": { "const": true }
+                        }
+                    }
+                }
+            },
+            "then": {
+                "additionalProperties": false,
+                "properties": {
+                    "$schema": true,
+                    "_meta": true,
+                    "success": true,
+                    "result": true,
+                    "error": true,
+                    "page": true,
+                    "_extensions": true
+                }
+            },
+            "else": {
+                "additionalProperties": true
+            }
         }
     ]
 }

package/dist/schemas/v1/error-registry.json

@@ -1,5 +1,5 @@
 {
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$schema": "http://json-schema.org/draft-07/schema#",
     "version": "1.0.0",
     "codes": [
         {
@@ -91,6 +91,24 @@
             "httpStatus": 426,
             "grpcStatus": "FAILED_PRECONDITION",
             "cliExit": 10
+        },
+        {
+            "code": "E_DISCLOSURE_UNKNOWN_FIELD",
+            "category": "VALIDATION",
+            "description": "Unrecognized expansion field in _expand parameter",
+            "retryable": false,
+            "httpStatus": 400,
+            "grpcStatus": "INVALID_ARGUMENT",
+            "cliExit": 2
+        },
+        {
+            "code": "E_MVI_BUDGET_EXCEEDED",
+            "category": "VALIDATION",
+            "description": "Response exceeds declared MVI budget (token, byte, or item limit)",
+            "retryable": false,
+            "httpStatus": 413,
+            "grpcStatus": "RESOURCE_EXHAUSTED",
+            "cliExit": 2
         }
     ]
 }

package/dist/src/cli.d.ts

@@ -1,2 +1,16 @@
 #!/usr/bin/env node
+/**
+ * LAFS Conformance CLI — diagnostic/human-readable tool.
+ *
+ * This CLI is a **diagnostic utility** that validates envelopes and flags
+ * against the LAFS schema and conformance checks. It is NOT itself a
+ * LAFS-conformant envelope producer. Its output is for human consumption
+ * and CI pipelines, not for machine-to-machine chaining.
+ *
+ * Exemption: The CLI is exempt from LAFS envelope conformance requirements.
+ * Its output format is not a LAFS envelope and MUST NOT be validated as one.
+ *
+ * @task T042
+ * @epic T034
+ */
 export {};

package/dist/src/cli.js

@@ -1,4 +1,18 @@
 #!/usr/bin/env node
+/**
+ * LAFS Conformance CLI — diagnostic/human-readable tool.
+ *
+ * This CLI is a **diagnostic utility** that validates envelopes and flags
+ * against the LAFS schema and conformance checks. It is NOT itself a
+ * LAFS-conformant envelope producer. Its output is for human consumption
+ * and CI pipelines, not for machine-to-machine chaining.
+ *
+ * Exemption: The CLI is exempt from LAFS envelope conformance requirements.
+ * Its output format is not a LAFS envelope and MUST NOT be validated as one.
+ *
+ * @task T042
+ * @epic T034
+ */
 import { readFile } from "node:fs/promises";
 import { runEnvelopeConformance, runFlagConformance } from "./conformance.js";
 function parseArgs(argv) {

package/dist/src/conformance.js

@@ -12,17 +12,79 @@ export function runEnvelopeConformance(envelope) {
         return { ok: false, checks };
     }
     const typed = envelope;
-    const invariant = typed.success ? typed.error === null : typed.result === null;
-    pushCheck(checks, "envelope_invariants", invariant, invariant ? undefined : "success/result/error invariant violated");
+    // envelope_invariants: success=true allows error to be null OR omitted;
+    // success=false requires error to be a non-null object and result===null.
+    const invariant = typed.success
+        ? typed.error == null // null or undefined (omitted) both valid for success
+        : typed.result === null && typed.error != null;
+    pushCheck(checks, "envelope_invariants", invariant, invariant
+        ? undefined
+        : typed.success
+            ? "success=true but error is present and non-null"
+            : "success=false requires result===null and error to be a non-null object");
+    // error_code_registered: only checked when error is present (error is optional when success=true)
     if (typed.error) {
         const registered = isRegisteredErrorCode(typed.error.code);
         pushCheck(checks, "error_code_registered", registered, registered ? undefined : `unregistered code: ${typed.error.code}`);
     }
     else {
-        pushCheck(checks, "error_code_registered", true);
+        pushCheck(checks, "error_code_registered", true, "error field absent or null — skipped (optional when success=true)");
     }
-    pushCheck(checks, "meta_mvi_present", typeof typed._meta.mvi === "boolean");
+    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");
+    // strict_mode_behavior: when strict=true, the envelope MUST NOT contain
+    // explicit null for optional fields that can be omitted (page, error on success).
+    if (typed._meta.strict) {
+        const obj = envelope;
+        const hasExplicitNullError = typed.success && "error" in obj && obj["error"] === null;
+        const hasExplicitNullPage = "page" in obj && obj["page"] === null;
+        const strictClean = !hasExplicitNullError && !hasExplicitNullPage;
+        pushCheck(checks, "strict_mode_behavior", strictClean, strictClean
+            ? undefined
+            : "strict mode: optional fields should be omitted rather than set to null");
+    }
+    // pagination_mode_consistent: when page is present and is an object, verify
+    // that the fields present match the declared pagination mode.
+    if (typed.page && typeof typed.page === "object") {
+        const page = typed.page;
+        const mode = page["mode"];
+        let consistent = true;
+        let detail;
+        if (mode === "cursor") {
+            if (page["offset"] !== undefined) {
+                consistent = false;
+                detail = "cursor mode should not include offset field";
+            }
+        }
+        else if (mode === "offset") {
+            if (page["nextCursor"] !== undefined) {
+                consistent = false;
+                detail = "offset mode should not include nextCursor field";
+            }
+        }
+        else if (mode === "none") {
+            const extraFields = Object.keys(page).filter((k) => k !== "mode");
+            if (extraFields.length > 0) {
+                consistent = false;
+                detail = `none mode should only have mode field, found: ${extraFields.join(", ")}`;
+            }
+        }
+        pushCheck(checks, "pagination_mode_consistent", consistent, consistent ? undefined : detail);
+    }
+    // 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.
+    {
+        const extraPropEnvelope = { ...envelope, _unknown_extra: true };
+        const extraResult = validateEnvelope(extraPropEnvelope);
+        if (typed._meta.strict) {
+            pushCheck(checks, "strict_mode_enforced", !extraResult.valid, extraResult.valid ? "strict=true but additional properties were accepted" : undefined);
+        }
+        else {
+            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 };
 }
 export function runFlagConformance(flags) {
@@ -30,13 +92,24 @@ export function runFlagConformance(flags) {
     try {
         const resolved = resolveOutputFormat(flags);
         pushCheck(checks, "flag_conflict_rejected", !(flags.humanFlag && flags.jsonFlag));
-        pushCheck(checks, "json_default_when_unspecified", resolved.format === "json" || Boolean(flags.projectDefault || flags.userDefault));
+        // Protocol-default check: when nothing is specified (source === "default"),
+        // the protocol requires JSON as the default format.
+        const isProtocolDefault = resolved.source === "default";
+        pushCheck(checks, "json_protocol_default", !isProtocolDefault || resolved.format === "json", isProtocolDefault && resolved.format !== "json"
+            ? `protocol default should be json, got ${resolved.format}`
+            : undefined);
+        // Config-override check: when a project or user default is active,
+        // the resolved format must match the config-provided value.
+        const hasConfigOverride = resolved.source === "project" || resolved.source === "user";
+        const expectedOverride = resolved.source === "project" ? flags.projectDefault : flags.userDefault;
+        pushCheck(checks, "config_override_respected", !hasConfigOverride || resolved.format === expectedOverride, hasConfigOverride && resolved.format !== expectedOverride
+            ? `config override expected ${String(expectedOverride)}, got ${resolved.format}`
+            : undefined);
     }
     catch (error) {
         if (error instanceof LAFSFlagError && error.code === "E_FORMAT_CONFLICT") {
             pushCheck(checks, "flag_conflict_rejected", true);
-            pushCheck(checks, "json_default_when_unspecified", true);
-            return { ok: true, checks };
+            return { ok: checks.every((check) => check.pass), checks };
         }
         pushCheck(checks, "flag_resolution", false, error instanceof Error ? error.message : String(error));
         return { ok: false, checks };

package/dist/src/types.d.ts

@@ -1,5 +1,12 @@
 export type LAFSTransport = "cli" | "http" | "grpc" | "sdk";
 export type LAFSErrorCategory = "VALIDATION" | "AUTH" | "PERMISSION" | "NOT_FOUND" | "CONFLICT" | "RATE_LIMIT" | "TRANSIENT" | "INTERNAL" | "CONTRACT" | "MIGRATION";
+export interface Warning {
+    code: string;
+    message: string;
+    deprecated?: string;
+    replacement?: string;
+    removeBy?: string;
+}
 export interface LAFSMeta {
     specVersion: string;
     schemaVersion: string;
@@ -8,8 +15,9 @@ export interface LAFSMeta {
     requestId: string;
     transport: LAFSTransport;
     strict: boolean;
-    mvi: boolean;
+    mvi: 'minimal' | 'standard' | 'full' | 'custom';
     contextVersion: number;
+    warnings?: Warning[];
 }
 export interface LAFSError {
     code: string;
@@ -19,21 +27,48 @@ export interface LAFSError {
     retryAfterMs: number | null;
     details: Record<string, unknown>;
 }
-export interface LAFSPage {
-    mode: "offset" | "cursor" | "none";
+export interface LAFSPageCursor {
+    mode: "cursor";
+    nextCursor: string | null;
+    hasMore: boolean;
+    limit?: number;
+    total?: number | null;
+}
+export interface LAFSPageOffset {
+    mode: "offset";
     limit: number;
     offset: number;
-    nextCursor: string | null;
     hasMore: boolean;
-    total: number | null;
+    total?: number | null;
+}
+export interface LAFSPageNone {
+    mode: "none";
+}
+export type LAFSPage = LAFSPageCursor | LAFSPageOffset | LAFSPageNone;
+export interface ContextLedgerEntry {
+    entryId: string;
+    timestamp: string;
+    operation: string;
+    contextDelta: Record<string, unknown>;
+    requestId?: string;
+}
+export interface ContextLedger {
+    ledgerId: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    entries: ContextLedgerEntry[];
+    checksum: string;
+    maxEntries: number;
 }
 export interface LAFSEnvelope {
     $schema: "https://lafs.dev/schemas/v1/envelope.schema.json";
     _meta: LAFSMeta;
     success: boolean;
     result: Record<string, unknown> | Record<string, unknown>[] | null;
-    error: LAFSError | null;
-    page: LAFSPage | null;
+    error?: LAFSError | null;
+    page?: LAFSPage | null;
+    _extensions?: Record<string, unknown>;
 }
 export interface FlagInput {
     requestedFormat?: "json" | "human";

package/lafs.md

@@ -2,19 +2,41 @@
 
 ## 1. Scope
 
-LAFS defines a protocol for software systems whose primary consumer is an LLM agent.
+LAFS is a **response envelope contract specification**. It defines the canonical shape of structured responses — success envelopes, error envelopes, pagination metadata, and context preservation — for software systems whose primary consumer is an LLM agent or AI-driven tool.
 
-LAFS is transport-agnostic and language-agnostic. It applies to CLI, SDK, HTTP, gRPC, and orchestrated multi-agent systems.
+LAFS is **not** a protocol, framework, or runtime. It specifies **what** a conformant response looks like, not how that response is transported or generated. Implementations MAY deliver LAFS envelopes over HTTP, gRPC, CLI, SDK interfaces, message queues, or any other transport mechanism. LAFS is transport-agnostic and language-agnostic.
+
+LAFS is designed to complement — not compete with — existing agent and tool-integration protocols. The Model Context Protocol (MCP) defines how LLM hosts discover and invoke tools; the Agent-to-Agent protocol (A2A) defines how autonomous agents communicate and delegate tasks. LAFS operates at a different layer: it standardizes the **response contract** that tools and agents SHOULD return, regardless of the protocol used to invoke them. An MCP tool server, an A2A agent, or a plain REST API MAY all return LAFS-conformant envelopes.
+
+While LAFS is purpose-built for AI and LLM tool ecosystems — where deterministic, machine-parseable responses are critical — the specification is generally applicable to any API that benefits from structured, predictable response contracts.
 
 ---
 
-## 2. RFC 2119 Keywords
+## 2. Non-Goals
+
+The following capabilities are intentionally outside the scope of LAFS. This section exists to prevent scope creep and to clarify boundaries with complementary protocols.
+
+1. **Streaming responses.** LAFS defines discrete request/response envelopes. Streaming mechanisms such as SSE or WebSocket are transport concerns and MUST NOT be defined by LAFS.
+
+2. **Asynchronous processing.** LAFS envelopes are synchronous response contracts. Async job patterns (polling, webhooks, callback queues) are application-layer concerns and are outside LAFS scope.
+
+3. **Authentication and authorization.** LAFS is transport-agnostic; auth is a transport or middleware concern. LAFS MAY carry auth-related error codes (e.g., `E_AUTH_*`) but MUST NOT define authentication or authorization flows.
+
+4. **Multi-modal content.** LAFS envelopes carry structured JSON data. Binary payloads, media content negotiation, and multi-modal encoding are outside scope.
+
+5. **Transport binding.** LAFS defines the response envelope shape, not how it maps to HTTP status codes, gRPC metadata, or other transport semantics. Transport mapping specifications are a separate concern.
+
+6. **Service discovery.** LAFS does not define how consumers locate or enumerate LAFS-conformant endpoints. Discovery mechanisms SHOULD be provided by the deployment layer or complementary protocols.
+
+---
+
+## 3. RFC 2119 Keywords
 
 The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are interpreted per RFC 2119.
 
 ---
 
-## 3. Non-Negotiable Protocol Rules
+## 4. Non-Negotiable Protocol Rules
 
 1. Output default MUST be machine-readable JSON.
 2. Human-readable mode MUST be explicit opt-in.
@@ -25,9 +47,9 @@ The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are interpreted per RFC
 
 ---
 
-## 4. Format Semantics
+## 5. Format Semantics
 
-### 4.1 Required output semantics
+### 5.1 Required output semantics
 
 - Default format MUST be `json`.
 - `--human` MUST switch output mode to human-readable.
@@ -35,7 +57,7 @@ The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are interpreted per RFC
 - Providing both `--human` and `--json` MUST fail with `E_FORMAT_CONFLICT`.
 - Explicit flags MUST override env/config defaults.
 
-### 4.2 Recommended precedence
+### 5.2 Recommended precedence
 
 1. Explicit CLI/API request value
 2. Project config
@@ -44,7 +66,7 @@ The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are interpreted per RFC
 
 ---
 
-## 5. Canonical Response Envelope
+## 6. Canonical Response Envelope
 
 All responses MUST conform to `schemas/v1/envelope.schema.json`.
 
@@ -69,16 +91,25 @@ All responses MUST conform to `schemas/v1/envelope.schema.json`.
 }
 ```
 
-### 5.1 Envelope invariants
+### 6.1 Envelope invariants
 
 - Exactly one of `result` or `error` MUST be non-null.
-- `success=true` implies `error=null`.
-- `success=false` implies `result=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.
 - Unknown fields SHOULD be rejected when strict mode is enabled.
 
+### 6.2 Extensions
+
+The envelope supports an optional `_extensions` object for vendor-specific metadata. Because `_extensions` is a declared property in the schema, it is permitted regardless of strict mode.
+
+- Keys SHOULD use the `x-` prefix convention (e.g., `x-myvendor-trace-id`).
+- Consumers MUST NOT rely on extension fields for protocol-required behavior.
+- Producers MAY omit `_extensions` entirely; the field is always optional.
+
 ---
 
-## 6. Error Contract
+## 7. Error Contract
 
 Errors MUST conform to envelope `error` shape and use codes from `schemas/v1/error-registry.json`.
 
@@ -95,7 +126,30 @@ Errors MUST conform to envelope `error` shape and use codes from `schemas/v1/err
 }
 ```
 
-### 6.1 Required behavior
+### 7.1 Error code naming convention
+
+Error codes MUST match the pattern: `^E_[A-Z0-9]+_[A-Z0-9_]+$`
+
+The structure is **E\_\<DOMAIN\>\_\<SPECIFIC\>**, where:
+
+- **E\_** — required prefix identifying the value as an error code.
+- **DOMAIN** — a short uppercase token describing the error's semantic area (e.g., `VALIDATION`, `CONTEXT`, `RATE`, `MIGRATION`). The domain is descriptive; it does not need to equal the `category` enum value.
+- **SPECIFIC** — one or more uppercase tokens (separated by `_`) that distinguish the error within its domain (e.g., `SCHEMA`, `MISSING`, `UNSUPPORTED_VERSION`).
+
+Examples from the registry:
+
+| Code | Domain | Specific | Category |
+|---|---|---|---|
+| `E_VALIDATION_SCHEMA` | `VALIDATION` | `SCHEMA` | VALIDATION |
+| `E_NOT_FOUND_RESOURCE` | `NOT` | `FOUND_RESOURCE` | NOT_FOUND |
+| `E_CONTEXT_MISSING` | `CONTEXT` | `MISSING` | CONTRACT |
+| `E_MIGRATION_UNSUPPORTED_VERSION` | `MIGRATION` | `UNSUPPORTED_VERSION` | MIGRATION |
+
+Registered categories (the `category` field in error objects): `VALIDATION`, `AUTH`, `PERMISSION`, `NOT_FOUND`, `CONFLICT`, `RATE_LIMIT`, `TRANSIENT`, `INTERNAL`, `CONTRACT`, `MIGRATION`.
+
+Custom error codes MUST match the same regex pattern. Implementations SHOULD choose a domain token that clearly communicates the error's origin.
+
+### 7.2 Required behavior
 
 - Error codes MUST be stable within major versions.
 - Retry semantics MUST be encoded in `retryable` and `retryAfterMs`.
@@ -103,7 +157,7 @@ Errors MUST conform to envelope `error` shape and use codes from `schemas/v1/err
 
 ---
 
-## 7. Context Preservation
+## 8. Context Preservation
 
 Multi-step operations MUST preserve a context ledger with at least:
 
@@ -124,20 +178,35 @@ Rules:
 
 ---
 
-## 8. MVI and Progressive Disclosure
+## 9. MVI and Progressive Disclosure
 
-### 8.1 MVI default
+### 9.1 MVI default
 
 - Default list/batch outputs MUST only contain fields required for next action.
 - Verbose fields SHOULD be omitted by default.
 - Systems SHOULD publish operation-level MVI budgets.
 
-### 8.2 Progressive disclosure
+### 9.2 Field selection (`_fields`)
 
-- Expanded detail retrieval MUST require explicit request.
-- Unknown expansion fields SHOULD fail validation.
+Clients MAY request a subset of response fields via the `_fields` request parameter.
 
-### 8.3 Pagination
+- `_fields` MUST be an array of strings identifying top-level result field names.
+- When `_fields` is present, the server MUST return only the requested fields plus any MVI-required fields for the declared disclosure level.
+- When `_fields` is absent, the server MUST return fields appropriate for the declared `_meta.mvi` disclosure level.
+- If a requested field does not exist on the resource, the server SHOULD omit it silently (no error). Servers MAY include a warning in `_meta.warnings` for unknown fields.
+- `_fields` MUST NOT affect envelope structural fields (`$schema`, `_meta`, `success`, `error`, `page`, `_extensions`); it applies only to the contents of `result`.
+
+### 9.3 Expansion mechanism (`_expand`)
+
+Clients MAY request expanded/nested data via the `_expand` request parameter.
+
+- `_expand` MUST be an array of strings identifying relationships or nested resources to include inline.
+- When `_expand` is present, the server MUST resolve and inline the requested expansions within `result`.
+- If a requested expansion field is not recognized, the server MUST return error code `E_DISCLOSURE_UNKNOWN_FIELD` with category `VALIDATION`.
+- Servers SHOULD document available expansion fields per operation.
+- Expansion depth MUST be limited to prevent unbounded recursion. Servers SHOULD enforce a maximum expansion depth and return `E_MVI_BUDGET_EXCEEDED` if exceeded.
+
+### 9.4 Pagination
 
 - List operations SHOULD return deterministic `page` metadata.
 - Pagination mode (offset or cursor) MUST be documented.
@@ -145,7 +214,7 @@ Rules:
 
 ---
 
-## 9. Strictness
+## 10. Strictness
 
 - Agent surfaces SHOULD default `strict=true`.
 - Strict mode violations SHOULD fail with contract/validation error codes.
@@ -153,7 +222,7 @@ Rules:
 
 ---
 
-## 10. Versioning and Deprecation
+## 11. Versioning and Deprecation
 
 - Protocol versions MUST follow SemVer.
 - Minor/patch changes MUST be backward compatible.
@@ -164,6 +233,81 @@ See `docs/VERSIONING.md` and `docs/DEPRECATION.md`.
 
 ---
 
-## 11. Conformance
+## 12. Conformance
 
 Conforming implementations MUST pass minimum checks in `docs/CONFORMANCE.md` and schema validation for the canonical envelope.
+
+### 12.1 Adoption Tiers
+
+LAFS defines three adoption tiers to enable gradual conformance. Each tier builds on the previous tier's requirements. Implementations MUST declare which tier they target and MUST pass all checks required by that tier.
+
+#### 12.1.1 Core Tier
+
+The Core tier represents **minimum viable LAFS adoption**. It verifies that responses use the canonical envelope shape and satisfy basic structural invariants.
+
+Required conformance checks:
+
+| Check | Description |
+|---|---|
+| `envelope_schema_valid` | Response validates against `schemas/v1/envelope.schema.json` |
+| `envelope_invariants` | `success`/`result`/`error` mutual exclusivity holds (Section 6.1) |
+
+Use cases: quick adoption, internal APIs, prototyping, evaluating LAFS fit.
+
+#### 12.1.2 Standard Tier
+
+The Standard tier is **recommended for production** use. It adds semantic checks for error codes, metadata flags, and format defaults on top of all Core tier requirements.
+
+Required conformance checks — all Core checks, plus:
+
+| Check | Description |
+|---|---|
+| `error_code_registered` | All error codes come from the registered error registry (Section 7) |
+| `meta_mvi_present` | `_meta.mvi` flag is present and valid (Section 9.1) |
+| `meta_strict_present` | `_meta.strict` flag is present and boolean (Section 10) |
+| `json_protocol_default` | JSON is the default output format when no explicit format is requested (Section 5.1) |
+
+Use cases: production APIs, public-facing services, third-party integrations.
+
+#### 12.1.3 Complete Tier
+
+The Complete tier represents **full LAFS compliance**. It adds configuration, flag-handling, and advanced feature checks on top of all Standard tier requirements.
+
+Required conformance checks — all Standard checks, plus:
+
+| Check | Description |
+|---|---|
+| `config_override_respected` | Project/user config-based format overrides are correctly applied (Section 5.2) |
+| `flag_conflict_rejected` | Conflicting format flags (e.g., `--human --json`) are properly rejected with `E_FORMAT_CONFLICT` (Section 5.1) |
+| `context_validation` | Context preservation invariants hold for multi-step operations (Section 8) |
+| `pagination_validation` | Pagination metadata validates when present (Section 9.3) |
+
+Use cases: official LAFS-conformant implementations, reference implementations, certification.
+
+> **Note:** `context_validation` and `pagination_validation` are reserved check names. Implementations SHOULD treat these as automatically passing until the corresponding conformance runners are available.
+
+---
+
+## 13. Security Considerations
+
+This section addresses security threats relevant to LAFS envelope production and consumption. LAFS is transport-agnostic and does not define its own cryptographic or authentication mechanisms; implementers MUST rely on the underlying transport and application layers for those controls.
+
+### 13.1 Injection attacks
+
+LAFS envelopes carry user-provided data in `result`, `error`, and `details` fields. Implementers MUST sanitize all envelope contents before rendering in HTML, constructing shell commands, or executing in eval-like contexts. Error messages MUST NOT contain unsanitized user input. Implementations that embed envelope values in SQL, LDAP, or similar query languages MUST use parameterized interfaces.
+
+### 13.2 Tampering
+
+LAFS does not define integrity protection at the envelope level. If envelope integrity is required, implementers SHOULD use transport-level security (e.g., TLS) and MAY implement envelope signing as an extension. Consumers MUST NOT trust envelope contents without verifying the transport channel. Implementations that relay envelopes across trust boundaries SHOULD re-validate against `schemas/v1/envelope.schema.json` at each boundary.
+
+### 13.3 Information disclosure
+
+Error details MAY contain sensitive information such as stack traces, internal paths, or database identifiers. Implementations SHOULD distinguish between development and production error detail levels. The `details` field in error objects MUST NOT expose internal system information in production environments. Implementations SHOULD define an explicit allow-list of fields permitted in production error responses.
+
+### 13.4 Replay attacks
+
+LAFS includes `requestId` and `timestamp` in `_meta` for correlation (Section 6). Implementers MAY use these fields for replay detection but MUST NOT rely solely on them, as LAFS does not mandate uniqueness or freshness guarantees for these values. Transport-level replay protection (e.g., TLS with appropriate session management) is RECOMMENDED.
+
+### 13.5 Denial of service
+
+Large envelope payloads could be used for resource exhaustion. Implementations SHOULD enforce maximum envelope size limits appropriate to their deployment context. Pagination (Section 9.3) SHOULD be used to bound response sizes for list operations. Implementations SHOULD reject envelopes that exceed the configured size limit with a structured error.

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@cleocode/lafs-protocol",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "description": "LLM-Agent-First Specification schemas and conformance tooling",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
   "files": [
     "dist",
     "schemas",
@@ -29,6 +35,7 @@
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "conformance": "tsx src/cli.ts"

package/schemas/v1/context-ledger.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lafs.dev/schemas/v1/context-ledger.schema.json",
+  "title": "LAFS Context Ledger",
+  "description": "Tracks state across request/response cycles for context preservation",
+  "type": "object",
+  "required": ["ledgerId", "version", "createdAt", "updatedAt", "entries", "checksum", "maxEntries"],
+  "properties": {
+    "ledgerId": {
+      "type": "string",
+      "description": "Unique identifier for this context ledger instance"
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Monotonically increasing version number matching _meta.contextVersion"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when the ledger was created"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the last ledger update"
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["entryId", "timestamp", "operation", "contextDelta"],
+        "properties": {
+          "entryId": {
+            "type": "string",
+            "description": "Unique identifier for this ledger entry"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "operation": {
+            "type": "string",
+            "description": "The operation that generated this entry"
+          },
+          "contextDelta": {
+            "type": "object",
+            "description": "The context changes introduced by this operation",
+            "additionalProperties": true
+          },
+          "requestId": {
+            "type": "string",
+            "description": "Correlation with the request that produced this entry"
+          }
+        }
+      },
+      "description": "Ordered array of context entries (append-only)"
+    },
+    "checksum": {
+      "type": "string",
+      "description": "Integrity checksum of the ledger contents"
+    },
+    "maxEntries": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Maximum number of entries before truncation/compaction"
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/v1/envelope.schema.json

@@ -3,14 +3,11 @@
   "$id": "https://lafs.dev/schemas/v1/envelope.schema.json",
   "title": "LAFS Envelope v1",
   "type": "object",
-  "additionalProperties": false,
   "required": [
     "$schema",
     "_meta",
     "success",
-    "result",
-    "error",
-    "page"
+    "result"
   ],
   "properties": {
     "$schema": {
@@ -62,11 +59,28 @@
           "type": "boolean"
         },
         "mvi": {
-          "type": "boolean"
+          "type": "string",
+          "enum": ["minimal", "standard", "full", "custom"],
+          "description": "Disclosure level: minimal (MVI only), standard (common fields), full (all fields), custom (per _fields parameter)"
         },
         "contextVersion": {
           "type": "integer",
           "minimum": 0
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "code": { "type": "string", "description": "Warning identifier (e.g., DEPRECATED_FIELD)" },
+              "message": { "type": "string", "description": "Human-readable warning" },
+              "deprecated": { "type": "string", "description": "The deprecated feature or field name" },
+              "replacement": { "type": "string", "description": "Suggested replacement, if any" },
+              "removeBy": { "type": "string", "description": "Version when the deprecated feature will be removed" }
+            },
+            "required": ["code", "message"]
+          },
+          "description": "Non-fatal advisory warnings (deprecations, migration hints)"
         }
       }
     },
@@ -127,14 +141,7 @@
     "page": {
       "type": ["object", "null"],
       "additionalProperties": false,
-      "required": [
-        "mode",
-        "limit",
-        "offset",
-        "nextCursor",
-        "hasMore",
-        "total"
-      ],
+      "required": ["mode"],
       "properties": {
         "mode": {
           "type": "string",
@@ -160,7 +167,61 @@
           "type": ["integer", "null"],
           "minimum": 0
         }
-      }
+      },
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "properties": { "mode": { "const": "cursor" } },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["mode", "nextCursor", "hasMore"],
+            "properties": {
+              "mode": true,
+              "nextCursor": true,
+              "hasMore": true,
+              "limit": true,
+              "total": true
+            }
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": { "mode": { "const": "offset" } },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["mode", "limit", "offset", "hasMore"],
+            "properties": {
+              "mode": true,
+              "limit": true,
+              "offset": true,
+              "hasMore": true,
+              "total": true
+            }
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": { "mode": { "const": "none" } },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["mode"],
+            "properties": {
+              "mode": true
+            }
+          }
+        }
+      ]
+    },
+    "_extensions": {
+      "type": "object",
+      "description": "Vendor extensions. Keys SHOULD use x- prefix (e.g., x-myvendor-trace-id).",
+      "additionalProperties": true
     }
   },
   "allOf": [
@@ -183,11 +244,39 @@
         }
       },
       "then": {
+        "required": ["error"],
         "properties": {
           "result": { "type": "null" },
           "error": { "type": "object" }
         }
       }
+    },
+    {
+      "if": {
+        "properties": {
+          "_meta": {
+            "type": "object",
+            "properties": {
+              "strict": { "const": true }
+            }
+          }
+        }
+      },
+      "then": {
+        "additionalProperties": false,
+        "properties": {
+          "$schema": true,
+          "_meta": true,
+          "success": true,
+          "result": true,
+          "error": true,
+          "page": true,
+          "_extensions": true
+        }
+      },
+      "else": {
+        "additionalProperties": true
+      }
     }
   ]
 }

package/schemas/v1/error-registry.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$schema": "http://json-schema.org/draft-07/schema#",
   "version": "1.0.0",
   "codes": [
     {
@@ -91,6 +91,24 @@
       "httpStatus": 426,
       "grpcStatus": "FAILED_PRECONDITION",
       "cliExit": 10
+    },
+    {
+      "code": "E_DISCLOSURE_UNKNOWN_FIELD",
+      "category": "VALIDATION",
+      "description": "Unrecognized expansion field in _expand parameter",
+      "retryable": false,
+      "httpStatus": 400,
+      "grpcStatus": "INVALID_ARGUMENT",
+      "cliExit": 2
+    },
+    {
+      "code": "E_MVI_BUDGET_EXCEEDED",
+      "category": "VALIDATION",
+      "description": "Response exceeds declared MVI budget (token, byte, or item limit)",
+      "retryable": false,
+      "httpStatus": 413,
+      "grpcStatus": "RESOURCE_EXHAUSTED",
+      "cliExit": 2
     }
   ]
 }