@cleocode/lafs-protocol 0.1.1 → 1.0.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/examples/discovery-server.d.ts

@@ -0,0 +1,8 @@
+/**
+ * LAFS Discovery Example Server
+ *
+ * Run with: npx tsx examples/discovery-server.ts
+ * Or: npm run build && node dist/examples/discovery-server.js
+ */
+declare const app: import("express-serve-static-core").Express;
+export default app;

package/dist/examples/discovery-server.js

@@ -0,0 +1,216 @@
+/**
+ * LAFS Discovery Example Server
+ *
+ * Run with: npx tsx examples/discovery-server.ts
+ * Or: npm run build && node dist/examples/discovery-server.js
+ */
+import express from "express";
+import { discoveryMiddleware } from "../src/discovery.js";
+const app = express();
+const PORT = process.env.PORT || 3000;
+/**
+ * LAFS-compliant envelope endpoint handler
+ * Demonstrates proper LAFS envelope processing
+ */
+app.post("/api/v1/envelope", express.json(), (req, res) => {
+    const envelope = req.body;
+    // Validate basic envelope structure
+    if (!envelope._meta) {
+        return res.status(400).json({
+            success: false,
+            error: {
+                code: "INVALID_ENVELOPE",
+                message: "Missing _meta field",
+                category: "VALIDATION",
+                retryable: false,
+                retryAfterMs: null,
+                details: { missing: ["_meta"] }
+            },
+            result: null
+        });
+    }
+    // Process the request (simplified example)
+    const operation = envelope._meta.operation;
+    // Echo back with success
+    res.json({
+        $schema: "https://lafs.dev/schemas/v1/envelope.schema.json",
+        _meta: {
+            specVersion: envelope._meta.specVersion || "1.0.0",
+            schemaVersion: envelope._meta.schemaVersion || "1.0.0",
+            timestamp: new Date().toISOString(),
+            operation: `${operation}:response`,
+            requestId: envelope._meta.requestId || crypto.randomUUID(),
+            transport: "http",
+            strict: envelope._meta.strict ?? true,
+            mvi: envelope._meta.mvi || "standard",
+            contextVersion: (envelope._meta.contextVersion || 0) + 1
+        },
+        success: true,
+        result: {
+            received: true,
+            operation: operation,
+            data: envelope.payload || null
+        },
+        error: null
+    });
+});
+/**
+ * Context ledger endpoint
+ * Demonstrates context management capability
+ */
+app.get("/api/v1/context/:ledgerId", (req, res) => {
+    const ledgerId = req.params.ledgerId;
+    // Return mock context ledger
+    res.json({
+        $schema: "https://lafs.dev/schemas/v1/context-ledger.schema.json",
+        ledgerId,
+        version: 1,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        entries: [],
+        checksum: "sha256:mock",
+        maxEntries: 1000
+    });
+});
+app.post("/api/v1/context/:ledgerId/entries", express.json(), (req, res) => {
+    const ledgerId = req.params.ledgerId;
+    const entry = req.body;
+    res.json({
+        $schema: "https://lafs.dev/schemas/v1/envelope.schema.json",
+        _meta: {
+            specVersion: "1.0.0",
+            schemaVersion: "1.0.0",
+            timestamp: new Date().toISOString(),
+            operation: "context:append",
+            requestId: crypto.randomUUID(),
+            transport: "http",
+            strict: true,
+            mvi: "standard",
+            contextVersion: 2
+        },
+        success: true,
+        result: {
+            ledgerId,
+            entryId: crypto.randomUUID(),
+            committed: true,
+            timestamp: new Date().toISOString()
+        },
+        error: null
+    });
+});
+/**
+ * Discovery configuration
+ * Advertises all LAFS capabilities and endpoints
+ */
+const discoveryConfig = {
+    service: {
+        name: "example-lafs-service",
+        version: "1.0.0",
+        description: "Example LAFS-compliant API service demonstrating discovery protocol"
+    },
+    capabilities: [
+        {
+            name: "envelope-processor",
+            version: "1.0.0",
+            description: "Process and validate LAFS envelopes",
+            operations: ["process", "validate", "transform"]
+        },
+        {
+            name: "context-ledger",
+            version: "1.0.0",
+            description: "Manage context ledgers for stateful operations",
+            operations: ["read", "append", "query"]
+        },
+        {
+            name: "pagination-provider",
+            version: "1.0.0",
+            description: "Provide cursor and offset pagination for list endpoints",
+            operations: ["cursor", "offset", "none"],
+            optional: true
+        }
+    ],
+    endpoints: {
+        envelope: "/api/v1/envelope",
+        context: "/api/v1/context",
+        discovery: "https://lafs.dev/schemas/v1/discovery.schema.json"
+    },
+    cacheMaxAge: 3600,
+    lafsVersion: "1.0.0"
+};
+// Mount discovery middleware BEFORE other routes
+// This ensures /.well-known/lafs.json is served at the root
+app.use(discoveryMiddleware(discoveryConfig));
+/**
+ * Health check endpoint
+ */
+app.get("/health", (req, res) => {
+    res.json({
+        status: "healthy",
+        service: discoveryConfig.service.name,
+        version: discoveryConfig.service.version,
+        timestamp: new Date().toISOString()
+    });
+});
+/**
+ * Error handling middleware
+ */
+app.use((err, req, res, next) => {
+    console.error("Error:", err);
+    res.status(500).json({
+        success: false,
+        error: {
+            code: "INTERNAL_ERROR",
+            message: err.message || "Internal server error",
+            category: "INTERNAL",
+            retryable: false,
+            retryAfterMs: null,
+            details: process.env.NODE_ENV === "development" ? { stack: err.stack } : {}
+        },
+        result: null
+    });
+});
+/**
+ * Start server
+ */
+const server = app.listen(PORT, () => {
+    console.log(`
+╔════════════════════════════════════════════════════════╗
+║     LAFS Discovery Server Running                      ║
+╠════════════════════════════════════════════════════════╣
+║  Service:    ${discoveryConfig.service.name.padEnd(43)}║
+║  Version:    ${discoveryConfig.service.version.padEnd(43)}║
+║  Port:       ${String(PORT).padEnd(43)}║
+╠════════════════════════════════════════════════════════╣
+║  Endpoints:                                            ║
+║    GET  /.well-known/lafs.json  (Discovery document)   ║
+║    POST /api/v1/envelope        (Envelope processor)   ║
+║    GET  /api/v1/context/:id     (Context ledger)       ║
+║    GET  /health                 (Health check)         ║
+╚════════════════════════════════════════════════════════╝
+
+Test with:
+  curl http://localhost:${PORT}/.well-known/lafs.json | jq
+  curl http://localhost:${PORT}/health | jq
+  curl -X POST http://localhost:${PORT}/api/v1/envelope \
+    -H "Content-Type: application/json" \
+    -d '{"_meta":{"operation":"test","requestId":"123"},"payload":{"hello":"world"}}'
+`);
+});
+/**
+ * Graceful shutdown
+ */
+process.on("SIGTERM", () => {
+    console.log("\nShutting down gracefully...");
+    server.close(() => {
+        console.log("Server closed");
+        process.exit(0);
+    });
+});
+process.on("SIGINT", () => {
+    console.log("\nShutting down gracefully...");
+    server.close(() => {
+        console.log("Server closed");
+        process.exit(0);
+    });
+});
+export default app;

package/dist/examples/mcp-lafs-client.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * MCP-LAFS Client Example
+ *
+ * A client that connects to the MCP-LAFS server and validates responses
+ * are LAFS-compliant. Demonstrates budget negotiation and envelope validation.
+ *
+ * Usage: npx ts-node examples/mcp-lafs-client.ts
+ */
+export {};