@cleocode/lafs-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# lafs-protocol
+
+LLM-Agent-First Specification (LAFS) as a standalone protocol repository.
+
+This repository is language-neutral at the protocol layer and TypeScript-first for reference tooling.
+
+## What this repo provides
+
+- 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/`
+
+## Install
+
+```bash
+npm install
+```
+
+## Commands
+
+```bash
+npm run typecheck
+npm test
+npm run conformance -- --envelope fixtures/valid-success-envelope.json --flags fixtures/flags-valid.json
+```
+
+## Canonical policy
+
+- 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`.
+
+## Layout
+
+```text
+lafs.md
+schemas/v1/
+src/
+tests/
+fixtures/
+docs/
+```

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

@@ -0,0 +1,193 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://lafs.dev/schemas/v1/envelope.schema.json",
+    "title": "LAFS Envelope v1",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+        "$schema",
+        "_meta",
+        "success",
+        "result",
+        "error",
+        "page"
+    ],
+    "properties": {
+        "$schema": {
+            "type": "string",
+            "const": "https://lafs.dev/schemas/v1/envelope.schema.json"
+        },
+        "_meta": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "specVersion",
+                "schemaVersion",
+                "timestamp",
+                "operation",
+                "requestId",
+                "transport",
+                "strict",
+                "mvi",
+                "contextVersion"
+            ],
+            "properties": {
+                "specVersion": {
+                    "type": "string",
+                    "pattern": "^\\d+\\.\\d+\\.\\d+$"
+                },
+                "schemaVersion": {
+                    "type": "string",
+                    "pattern": "^\\d+\\.\\d+\\.\\d+$"
+                },
+                "timestamp": {
+                    "type": "string",
+                    "format": "date-time"
+                },
+                "operation": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128
+                },
+                "requestId": {
+                    "type": "string",
+                    "minLength": 3,
+                    "maxLength": 128
+                },
+                "transport": {
+                    "type": "string",
+                    "enum": ["cli", "http", "grpc", "sdk"]
+                },
+                "strict": {
+                    "type": "boolean"
+                },
+                "mvi": {
+                    "type": "boolean"
+                },
+                "contextVersion": {
+                    "type": "integer",
+                    "minimum": 0
+                }
+            }
+        },
+        "success": {
+            "type": "boolean"
+        },
+        "result": {
+            "type": ["object", "array", "null"]
+        },
+        "error": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "required": [
+                "code",
+                "message",
+                "category",
+                "retryable",
+                "retryAfterMs",
+                "details"
+            ],
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "pattern": "^E_[A-Z0-9]+_[A-Z0-9_]+$"
+                },
+                "message": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1024
+                },
+                "category": {
+                    "type": "string",
+                    "enum": [
+                        "VALIDATION",
+                        "AUTH",
+                        "PERMISSION",
+                        "NOT_FOUND",
+                        "CONFLICT",
+                        "RATE_LIMIT",
+                        "TRANSIENT",
+                        "INTERNAL",
+                        "CONTRACT",
+                        "MIGRATION"
+                    ]
+                },
+                "retryable": {
+                    "type": "boolean"
+                },
+                "retryAfterMs": {
+                    "type": ["integer", "null"],
+                    "minimum": 0
+                },
+                "details": {
+                    "type": "object"
+                }
+            }
+        },
+        "page": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "required": [
+                "mode",
+                "limit",
+                "offset",
+                "nextCursor",
+                "hasMore",
+                "total"
+            ],
+            "properties": {
+                "mode": {
+                    "type": "string",
+                    "enum": ["offset", "cursor", "none"]
+                },
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 1000
+                },
+                "offset": {
+                    "type": "integer",
+                    "minimum": 0
+                },
+                "nextCursor": {
+                    "type": ["string", "null"],
+                    "maxLength": 2048
+                },
+                "hasMore": {
+                    "type": "boolean"
+                },
+                "total": {
+                    "type": ["integer", "null"],
+                    "minimum": 0
+                }
+            }
+        }
+    },
+    "allOf": [
+        {
+            "if": {
+                "properties": {
+                    "success": { "const": true }
+                }
+            },
+            "then": {
+                "properties": {
+                    "error": { "type": "null" }
+                }
+            }
+        },
+        {
+            "if": {
+                "properties": {
+                    "success": { "const": false }
+                }
+            },
+            "then": {
+                "properties": {
+                    "result": { "type": "null" },
+                    "error": { "type": "object" }
+                }
+            }
+        }
+    ]
+}

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

@@ -0,0 +1,96 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "version": "1.0.0",
+    "codes": [
+        {
+            "code": "E_FORMAT_CONFLICT",
+            "category": "CONTRACT",
+            "description": "Mutually exclusive format flags requested",
+            "retryable": false,
+            "httpStatus": 400,
+            "grpcStatus": "INVALID_ARGUMENT",
+            "cliExit": 2
+        },
+        {
+            "code": "E_VALIDATION_SCHEMA",
+            "category": "VALIDATION",
+            "description": "Input failed schema validation",
+            "retryable": false,
+            "httpStatus": 400,
+            "grpcStatus": "INVALID_ARGUMENT",
+            "cliExit": 2
+        },
+        {
+            "code": "E_NOT_FOUND_RESOURCE",
+            "category": "NOT_FOUND",
+            "description": "Referenced resource was not found",
+            "retryable": false,
+            "httpStatus": 404,
+            "grpcStatus": "NOT_FOUND",
+            "cliExit": 4
+        },
+        {
+            "code": "E_CONFLICT_VERSION",
+            "category": "CONFLICT",
+            "description": "Version or concurrency conflict",
+            "retryable": true,
+            "httpStatus": 409,
+            "grpcStatus": "ABORTED",
+            "cliExit": 7
+        },
+        {
+            "code": "E_RATE_LIMITED",
+            "category": "RATE_LIMIT",
+            "description": "Rate limit exceeded",
+            "retryable": true,
+            "httpStatus": 429,
+            "grpcStatus": "RESOURCE_EXHAUSTED",
+            "cliExit": 8
+        },
+        {
+            "code": "E_TRANSIENT_UPSTREAM",
+            "category": "TRANSIENT",
+            "description": "Upstream dependency temporary failure",
+            "retryable": true,
+            "httpStatus": 503,
+            "grpcStatus": "UNAVAILABLE",
+            "cliExit": 9
+        },
+        {
+            "code": "E_INTERNAL_UNEXPECTED",
+            "category": "INTERNAL",
+            "description": "Unexpected internal failure",
+            "retryable": false,
+            "httpStatus": 500,
+            "grpcStatus": "INTERNAL",
+            "cliExit": 1
+        },
+        {
+            "code": "E_CONTEXT_MISSING",
+            "category": "CONTRACT",
+            "description": "Required context ledger fields are missing",
+            "retryable": false,
+            "httpStatus": 400,
+            "grpcStatus": "FAILED_PRECONDITION",
+            "cliExit": 6
+        },
+        {
+            "code": "E_CONTEXT_STALE",
+            "category": "CONFLICT",
+            "description": "Context ledger or references are stale",
+            "retryable": true,
+            "httpStatus": 409,
+            "grpcStatus": "ABORTED",
+            "cliExit": 7
+        },
+        {
+            "code": "E_MIGRATION_UNSUPPORTED_VERSION",
+            "category": "MIGRATION",
+            "description": "Requested protocol/schema version unsupported",
+            "retryable": false,
+            "httpStatus": 426,
+            "grpcStatus": "FAILED_PRECONDITION",
+            "cliExit": 10
+        }
+    ]
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { runEnvelopeConformance, runFlagConformance } from "./conformance.js";
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const current = argv[i];
+        const next = argv[i + 1];
+        if (current === "--envelope" && next) {
+            args.envelopePath = next;
+            i += 1;
+        }
+        else if (current === "--flags" && next) {
+            args.flagsPath = next;
+            i += 1;
+        }
+    }
+    return args;
+}
+async function readJson(path) {
+    const content = await readFile(path, "utf8");
+    return JSON.parse(content);
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const reports = [];
+    if (args.envelopePath) {
+        const envelope = await readJson(args.envelopePath);
+        reports.push({ name: "envelope", report: runEnvelopeConformance(envelope) });
+    }
+    if (args.flagsPath) {
+        const flags = await readJson(args.flagsPath);
+        reports.push({ name: "flags", report: runFlagConformance(flags) });
+    }
+    if (reports.length === 0) {
+        throw new Error("Provide --envelope and/or --flags JSON files.");
+    }
+    console.log(JSON.stringify({ success: true, reports }, null, 2));
+}
+main().catch((error) => {
+    console.error(JSON.stringify({
+        success: false,
+        error: {
+            code: "E_INTERNAL_UNEXPECTED",
+            message: error instanceof Error ? error.message : String(error)
+        }
+    }, null, 2));
+    process.exit(1);
+});

package/dist/src/conformance.d.ts

@@ -0,0 +1,3 @@
+import type { ConformanceReport, FlagInput } from "./types.js";
+export declare function runEnvelopeConformance(envelope: unknown): ConformanceReport;
+export declare function runFlagConformance(flags: FlagInput): ConformanceReport;

package/dist/src/conformance.js

@@ -0,0 +1,45 @@
+import { isRegisteredErrorCode } from "./errorRegistry.js";
+import { resolveOutputFormat, LAFSFlagError } from "./flagSemantics.js";
+import { validateEnvelope } from "./validateEnvelope.js";
+function pushCheck(checks, name, pass, detail) {
+    checks.push({ name, pass, ...(detail ? { detail } : {}) });
+}
+export function runEnvelopeConformance(envelope) {
+    const checks = [];
+    const validation = validateEnvelope(envelope);
+    pushCheck(checks, "envelope_schema_valid", validation.valid, validation.valid ? undefined : validation.errors.join("; "));
+    if (!validation.valid) {
+        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");
+    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, "meta_mvi_present", typeof typed._meta.mvi === "boolean");
+    pushCheck(checks, "meta_strict_present", typeof typed._meta.strict === "boolean");
+    return { ok: checks.every((check) => check.pass), checks };
+}
+export function runFlagConformance(flags) {
+    const checks = [];
+    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));
+    }
+    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 };
+        }
+        pushCheck(checks, "flag_resolution", false, error instanceof Error ? error.message : String(error));
+        return { ok: false, checks };
+    }
+    return { ok: checks.every((check) => check.pass), checks };
+}

package/dist/src/errorRegistry.d.ts

@@ -0,0 +1,15 @@
+export interface RegistryCode {
+    code: string;
+    category: string;
+    description: string;
+    retryable: boolean;
+    httpStatus: number;
+    grpcStatus: string;
+    cliExit: number;
+}
+export interface ErrorRegistry {
+    version: string;
+    codes: RegistryCode[];
+}
+export declare function getErrorRegistry(): ErrorRegistry;
+export declare function isRegisteredErrorCode(code: string): boolean;

package/dist/src/errorRegistry.js

@@ -0,0 +1,8 @@
+import errorRegistry from "../schemas/v1/error-registry.json" with { type: "json" };
+export function getErrorRegistry() {
+    return errorRegistry;
+}
+export function isRegisteredErrorCode(code) {
+    const registry = getErrorRegistry();
+    return registry.codes.some((item) => item.code === code);
+}

package/dist/src/flagSemantics.d.ts

@@ -0,0 +1,10 @@
+import type { FlagInput } from "./types.js";
+export interface FlagResolution {
+    format: "json" | "human";
+    source: "flag" | "project" | "user" | "default";
+}
+export declare class LAFSFlagError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare function resolveOutputFormat(input: FlagInput): FlagResolution;

package/dist/src/flagSemantics.js

@@ -0,0 +1,29 @@
+export class LAFSFlagError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "LAFSFlagError";
+        this.code = code;
+    }
+}
+export function resolveOutputFormat(input) {
+    if (input.humanFlag && input.jsonFlag) {
+        throw new LAFSFlagError("E_FORMAT_CONFLICT", "Cannot combine --human and --json in the same invocation.");
+    }
+    if (input.requestedFormat) {
+        return { format: input.requestedFormat, source: "flag" };
+    }
+    if (input.humanFlag) {
+        return { format: "human", source: "flag" };
+    }
+    if (input.jsonFlag) {
+        return { format: "json", source: "flag" };
+    }
+    if (input.projectDefault) {
+        return { format: input.projectDefault, source: "project" };
+    }
+    if (input.userDefault) {
+        return { format: input.userDefault, source: "user" };
+    }
+    return { format: "json", source: "default" };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./errorRegistry.js";
+export * from "./validateEnvelope.js";
+export * from "./flagSemantics.js";
+export * from "./conformance.js";

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./errorRegistry.js";
+export * from "./validateEnvelope.js";
+export * from "./flagSemantics.js";
+export * from "./conformance.js";

package/dist/src/types.d.ts

@@ -0,0 +1,52 @@
+export type LAFSTransport = "cli" | "http" | "grpc" | "sdk";
+export type LAFSErrorCategory = "VALIDATION" | "AUTH" | "PERMISSION" | "NOT_FOUND" | "CONFLICT" | "RATE_LIMIT" | "TRANSIENT" | "INTERNAL" | "CONTRACT" | "MIGRATION";
+export interface LAFSMeta {
+    specVersion: string;
+    schemaVersion: string;
+    timestamp: string;
+    operation: string;
+    requestId: string;
+    transport: LAFSTransport;
+    strict: boolean;
+    mvi: boolean;
+    contextVersion: number;
+}
+export interface LAFSError {
+    code: string;
+    message: string;
+    category: LAFSErrorCategory;
+    retryable: boolean;
+    retryAfterMs: number | null;
+    details: Record<string, unknown>;
+}
+export interface LAFSPage {
+    mode: "offset" | "cursor" | "none";
+    limit: number;
+    offset: number;
+    nextCursor: string | null;
+    hasMore: boolean;
+    total: number | null;
+}
+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;
+}
+export interface FlagInput {
+    requestedFormat?: "json" | "human";
+    jsonFlag?: boolean;
+    humanFlag?: boolean;
+    projectDefault?: "json" | "human";
+    userDefault?: "json" | "human";
+}
+export interface ConformanceReport {
+    ok: boolean;
+    checks: Array<{
+        name: string;
+        pass: boolean;
+        detail?: string;
+    }>;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/validateEnvelope.d.ts

@@ -0,0 +1,7 @@
+import type { LAFSEnvelope } from "./types.js";
+export interface EnvelopeValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export declare function validateEnvelope(input: unknown): EnvelopeValidationResult;
+export declare function assertEnvelope(input: unknown): LAFSEnvelope;

package/dist/src/validateEnvelope.js

@@ -0,0 +1,28 @@
+import { createRequire } from "node:module";
+import envelopeSchema from "../schemas/v1/envelope.schema.json" with { type: "json" };
+const require = createRequire(import.meta.url);
+const AjvModule = require("ajv");
+const AddFormatsModule = require("ajv-formats");
+const AjvCtor = (typeof AjvModule === "function" ? AjvModule : AjvModule.default);
+const addFormats = (typeof AddFormatsModule === "function" ? AddFormatsModule : AddFormatsModule.default);
+const ajv = new AjvCtor({ allErrors: true, strict: true, allowUnionTypes: true });
+addFormats(ajv);
+const validate = ajv.compile(envelopeSchema);
+export function validateEnvelope(input) {
+    const valid = validate(input);
+    if (valid) {
+        return { valid: true, errors: [] };
+    }
+    const errors = (validate.errors ?? []).map((error) => {
+        const path = error.instancePath || "/";
+        return `${path} ${error.message ?? "validation error"}`.trim();
+    });
+    return { valid: false, errors };
+}
+export function assertEnvelope(input) {
+    const result = validateEnvelope(input);
+    if (!result.valid) {
+        throw new Error(`Invalid LAFS envelope: ${result.errors.join("; ")}`);
+    }
+    return input;
+}

package/lafs.md

@@ -0,0 +1,169 @@
+# LAFS: LLM-Agent-First Specification
+
+## 1. Scope
+
+LAFS defines a protocol for software systems whose primary consumer is an LLM agent.
+
+LAFS is transport-agnostic and language-agnostic. It applies to CLI, SDK, HTTP, gRPC, and orchestrated multi-agent systems.
+
+---
+
+## 2. RFC 2119 Keywords
+
+The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are interpreted per RFC 2119.
+
+---
+
+## 3. Non-Negotiable Protocol Rules
+
+1. Output default MUST be machine-readable JSON.
+2. Human-readable mode MUST be explicit opt-in.
+3. Context continuity MUST be preserved across steps.
+4. MVI (Minimal Viable Information) MUST be default response behavior.
+5. Progressive disclosure MUST be used for expanded detail retrieval.
+6. Contracts MUST be deterministic and testable.
+
+---
+
+## 4. Format Semantics
+
+### 4.1 Required output semantics
+
+- Default format MUST be `json`.
+- `--human` MUST switch output mode to human-readable.
+- `--json` MAY be supported as explicit alias/override and is RECOMMENDED.
+- Providing both `--human` and `--json` MUST fail with `E_FORMAT_CONFLICT`.
+- Explicit flags MUST override env/config defaults.
+
+### 4.2 Recommended precedence
+
+1. Explicit CLI/API request value
+2. Project config
+3. Global/user config
+4. Protocol default (`json`)
+
+---
+
+## 5. Canonical Response Envelope
+
+All responses MUST conform to `schemas/v1/envelope.schema.json`.
+
+```json
+{
+  "$schema": "https://lafs.dev/schemas/v1/envelope.schema.json",
+  "_meta": {
+    "specVersion": "1.0.0",
+    "schemaVersion": "1.0.0",
+    "timestamp": "2026-02-11T00:00:00Z",
+    "operation": "operation.name",
+    "requestId": "req_123",
+    "transport": "cli",
+    "strict": true,
+    "mvi": true,
+    "contextVersion": 0
+  },
+  "success": true,
+  "result": {},
+  "error": null,
+  "page": null
+}
+```
+
+### 5.1 Envelope invariants
+
+- Exactly one of `result` or `error` MUST be non-null.
+- `success=true` implies `error=null`.
+- `success=false` implies `result=null`.
+- Unknown fields SHOULD be rejected when strict mode is enabled.
+
+---
+
+## 6. Error Contract
+
+Errors MUST conform to envelope `error` shape and use codes from `schemas/v1/error-registry.json`.
+
+```json
+{
+  "code": "E_VALIDATION_SCHEMA",
+  "message": "Invalid input payload",
+  "category": "VALIDATION",
+  "retryable": false,
+  "retryAfterMs": null,
+  "details": {
+    "field": "limit"
+  }
+}
+```
+
+### 6.1 Required behavior
+
+- Error codes MUST be stable within major versions.
+- Retry semantics MUST be encoded in `retryable` and `retryAfterMs`.
+- CLI/HTTP/gRPC mappings SHOULD follow the registry.
+
+---
+
+## 7. Context Preservation
+
+Multi-step operations MUST preserve a context ledger with at least:
+
+- `objective`
+- `constraints[]`
+- `references[]`
+- `decisions[]`
+- `openIssues[]`
+- `state`
+- `version`
+
+Rules:
+
+- Version MUST increase monotonically by 1 for accepted mutations.
+- Accepted active constraints MUST NOT be silently removed.
+- Decisions affecting output MUST be represented in ledger state.
+- Missing required context for a mutating step MUST fail with structured error.
+
+---
+
+## 8. MVI and Progressive Disclosure
+
+### 8.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
+
+- Expanded detail retrieval MUST require explicit request.
+- Unknown expansion fields SHOULD fail validation.
+
+### 8.3 Pagination
+
+- List operations SHOULD return deterministic `page` metadata.
+- Pagination mode (offset or cursor) MUST be documented.
+- Mixed pagination modes in one request MUST fail validation.
+
+---
+
+## 9. Strictness
+
+- Agent surfaces SHOULD default `strict=true`.
+- Strict mode violations SHOULD fail with contract/validation error codes.
+- Response metadata MUST expose strict mode status.
+
+---
+
+## 10. Versioning and Deprecation
+
+- Protocol versions MUST follow SemVer.
+- Minor/patch changes MUST be backward compatible.
+- Breaking changes MUST require major version increments.
+- Deprecated fields MUST have documented sunset policy.
+
+See `docs/VERSIONING.md` and `docs/DEPRECATION.md`.
+
+---
+
+## 11. Conformance
+
+Conforming implementations MUST pass minimum checks in `docs/CONFORMANCE.md` and schema validation for the canonical envelope.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@cleocode/lafs-protocol",
+  "version": "0.1.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",
+  "files": [
+    "dist",
+    "schemas",
+    "lafs.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kryptobaseddev/lafs-protocol.git"
+  },
+  "homepage": "https://github.com/kryptobaseddev/lafs-protocol#readme",
+  "bugs": {
+    "url": "https://github.com/kryptobaseddev/lafs-protocol/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "lafs-conformance": "dist/src/cli.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "conformance": "tsx src/cli.ts"
+  },
+  "keywords": [
+    "lafs",
+    "llm",
+    "agent",
+    "protocol",
+    "schema",
+    "conformance"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^2.1.9"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  }
+}

package/schemas/v1/envelope.schema.json

@@ -0,0 +1,193 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lafs.dev/schemas/v1/envelope.schema.json",
+  "title": "LAFS Envelope v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "_meta",
+    "success",
+    "result",
+    "error",
+    "page"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://lafs.dev/schemas/v1/envelope.schema.json"
+    },
+    "_meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "specVersion",
+        "schemaVersion",
+        "timestamp",
+        "operation",
+        "requestId",
+        "transport",
+        "strict",
+        "mvi",
+        "contextVersion"
+      ],
+      "properties": {
+        "specVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$"
+        },
+        "schemaVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "operation": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "requestId": {
+          "type": "string",
+          "minLength": 3,
+          "maxLength": 128
+        },
+        "transport": {
+          "type": "string",
+          "enum": ["cli", "http", "grpc", "sdk"]
+        },
+        "strict": {
+          "type": "boolean"
+        },
+        "mvi": {
+          "type": "boolean"
+        },
+        "contextVersion": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "success": {
+      "type": "boolean"
+    },
+    "result": {
+      "type": ["object", "array", "null"]
+    },
+    "error": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": [
+        "code",
+        "message",
+        "category",
+        "retryable",
+        "retryAfterMs",
+        "details"
+      ],
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^E_[A-Z0-9]+_[A-Z0-9_]+$"
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "category": {
+          "type": "string",
+          "enum": [
+            "VALIDATION",
+            "AUTH",
+            "PERMISSION",
+            "NOT_FOUND",
+            "CONFLICT",
+            "RATE_LIMIT",
+            "TRANSIENT",
+            "INTERNAL",
+            "CONTRACT",
+            "MIGRATION"
+          ]
+        },
+        "retryable": {
+          "type": "boolean"
+        },
+        "retryAfterMs": {
+          "type": ["integer", "null"],
+          "minimum": 0
+        },
+        "details": {
+          "type": "object"
+        }
+      }
+    },
+    "page": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": [
+        "mode",
+        "limit",
+        "offset",
+        "nextCursor",
+        "hasMore",
+        "total"
+      ],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["offset", "cursor", "none"]
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000
+        },
+        "offset": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "nextCursor": {
+          "type": ["string", "null"],
+          "maxLength": 2048
+        },
+        "hasMore": {
+          "type": "boolean"
+        },
+        "total": {
+          "type": ["integer", "null"],
+          "minimum": 0
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "success": { "const": true }
+        }
+      },
+      "then": {
+        "properties": {
+          "error": { "type": "null" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "success": { "const": false }
+        }
+      },
+      "then": {
+        "properties": {
+          "result": { "type": "null" },
+          "error": { "type": "object" }
+        }
+      }
+    }
+  ]
+}

package/schemas/v1/error-registry.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "version": "1.0.0",
+  "codes": [
+    {
+      "code": "E_FORMAT_CONFLICT",
+      "category": "CONTRACT",
+      "description": "Mutually exclusive format flags requested",
+      "retryable": false,
+      "httpStatus": 400,
+      "grpcStatus": "INVALID_ARGUMENT",
+      "cliExit": 2
+    },
+    {
+      "code": "E_VALIDATION_SCHEMA",
+      "category": "VALIDATION",
+      "description": "Input failed schema validation",
+      "retryable": false,
+      "httpStatus": 400,
+      "grpcStatus": "INVALID_ARGUMENT",
+      "cliExit": 2
+    },
+    {
+      "code": "E_NOT_FOUND_RESOURCE",
+      "category": "NOT_FOUND",
+      "description": "Referenced resource was not found",
+      "retryable": false,
+      "httpStatus": 404,
+      "grpcStatus": "NOT_FOUND",
+      "cliExit": 4
+    },
+    {
+      "code": "E_CONFLICT_VERSION",
+      "category": "CONFLICT",
+      "description": "Version or concurrency conflict",
+      "retryable": true,
+      "httpStatus": 409,
+      "grpcStatus": "ABORTED",
+      "cliExit": 7
+    },
+    {
+      "code": "E_RATE_LIMITED",
+      "category": "RATE_LIMIT",
+      "description": "Rate limit exceeded",
+      "retryable": true,
+      "httpStatus": 429,
+      "grpcStatus": "RESOURCE_EXHAUSTED",
+      "cliExit": 8
+    },
+    {
+      "code": "E_TRANSIENT_UPSTREAM",
+      "category": "TRANSIENT",
+      "description": "Upstream dependency temporary failure",
+      "retryable": true,
+      "httpStatus": 503,
+      "grpcStatus": "UNAVAILABLE",
+      "cliExit": 9
+    },
+    {
+      "code": "E_INTERNAL_UNEXPECTED",
+      "category": "INTERNAL",
+      "description": "Unexpected internal failure",
+      "retryable": false,
+      "httpStatus": 500,
+      "grpcStatus": "INTERNAL",
+      "cliExit": 1
+    },
+    {
+      "code": "E_CONTEXT_MISSING",
+      "category": "CONTRACT",
+      "description": "Required context ledger fields are missing",
+      "retryable": false,
+      "httpStatus": 400,
+      "grpcStatus": "FAILED_PRECONDITION",
+      "cliExit": 6
+    },
+    {
+      "code": "E_CONTEXT_STALE",
+      "category": "CONFLICT",
+      "description": "Context ledger or references are stale",
+      "retryable": true,
+      "httpStatus": 409,
+      "grpcStatus": "ABORTED",
+      "cliExit": 7
+    },
+    {
+      "code": "E_MIGRATION_UNSUPPORTED_VERSION",
+      "category": "MIGRATION",
+      "description": "Requested protocol/schema version unsupported",
+      "retryable": false,
+      "httpStatus": 426,
+      "grpcStatus": "FAILED_PRECONDITION",
+      "cliExit": 10
+    }
+  ]
+}