@cleocode/lafs-protocol 0.1.1 → 1.0.0

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. 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.
 
 ---
 
-## 2. RFC 2119 Keywords
+## 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:
 
@@ -122,30 +176,209 @@ Rules:
 - Decisions affecting output MUST be represented in ledger state.
 - Missing required context for a mutating step MUST fail with structured error.
 
+### 8.1 Context Retrieval
+
+Agents MAY retrieve context ledger state via `GET /_lafs/context/{ledgerId}` with projection modes.
+
+#### 8.1.1 Projection Modes
+
+**Full Mode (`mode=full`):**
+Returns complete ledger including all entries.
+- Use for: Initial loads, recovery scenarios
+- Supports: Offset-based pagination
+- Response includes: All ledger fields
+
+**Delta Mode (`mode=delta&sinceVersion=N`):**
+Returns only entries added since version N.
+- Use for: Active workflows (efficient sync)
+- Response includes:
+```json
+{
+  "ledgerId": "ctx_abc123",
+  "mode": "delta",
+  "fromVersion": 10,
+  "toVersion": 15,
+  "entries": [/* new entries only */],
+  "removedConstraints": [/* constraints no longer active */],
+  "checksum": "sha256:..."
+}
+```
+
+**Summary Mode (`mode=summary`):**
+Returns checksum and version for validation.
+- Use for: Quick sync validation
+- Response includes only: `ledgerId`, `version`, `checksum`, `entryCount`
+
+#### 8.1.2 Query Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `mode` | enum | `full`, `delta`, `summary` |
+| `sinceVersion` | integer | For delta mode: return entries after this version |
+| `filterByOperation` | string[] | Filter entries by operation name(s) |
+| `limit` | integer | Max entries (1-1000, default 100) |
+| `includeChecksum` | boolean | Include integrity checksum (default true) |
+
+#### 8.1.3 Agent Guidance
+
+- **Initial load**: Use `mode=full` once
+- **Active workflows**: Use `mode=delta` with last known version
+- **Validation**: Use `mode=summary` to verify sync state
+- **Default recommendation**: `delta` mode for agent-optimal behavior
+
 ---
 
-## 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`)
+
+Clients MAY request a subset of response fields via the `_fields` request parameter.
+
+- `_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`.
 
-- Expanded detail retrieval MUST require explicit request.
-- Unknown expansion fields SHOULD fail validation.
+### 9.3 Expansion mechanism (`_expand`)
 
-### 8.3 Pagination
+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.
 - Mixed pagination modes in one request MUST fail validation.
 
+### 9.5 Token Budget Signaling
+
+Token budget signaling enables clients to declare resource constraints that servers MUST respect when generating responses. This mechanism prevents context window overflow in LLM-driven workflows.
+
+#### 9.5.1 Budget Declaration (`_budget`)
+
+Clients MAY declare resource constraints via the `_budget` request parameter:
+
+```json
+{
+  "_budget": {
+    "maxTokens": 4000,
+    "maxBytes": 32768,
+    "maxItems": 100
+  }
+}
+```
+
+**Fields:**
+- `maxTokens` (integer) - Maximum approximate tokens
+- `maxBytes` (integer) - Maximum byte size
+- `maxItems` (integer) - Maximum items in lists
+
+**Constraints:**
+- At least one field MUST be present
+- All values MUST be positive integers
+- Servers MAY reject budgets exceeding implementation limits
+
+#### 9.5.2 Server Behavior
+
+Servers MUST:
+1. Parse `_budget` from incoming requests
+2. Estimate/measure response size
+3. Return response within budget OR fail with `E_MVI_BUDGET_EXCEEDED`
+
+Servers MAY truncate responses using:
+- **Depth-first**: Remove deepest nested fields
+- **Field priority**: Remove non-essential fields first
+- **Hybrid**: Combine both strategies
+
+When truncation occurs, servers MUST include:
+```json
+{
+  "_meta": {
+    "warnings": [{
+      "code": "E_MVI_BUDGET_TRUNCATED",
+      "message": "Response truncated to fit token budget"
+    }],
+    "_tokenEstimate": {
+      "estimated": 2847,
+      "budget": 4000,
+      "method": "character_based"
+    }
+  }
+}
+```
+
+#### 9.5.3 Error Specification
+
+**E_MVI_BUDGET_EXCEEDED:**
+- **Category:** `VALIDATION`
+- **Retryable:** `true`
+- **Details:** `estimatedTokens`, `budget`, `excessTokens`, `constraint`
+
+```json
+{
+  "error": {
+    "code": "E_MVI_BUDGET_EXCEEDED",
+    "message": "Response exceeds declared token budget",
+    "category": "VALIDATION",
+    "retryable": true,
+    "details": {
+      "estimatedTokens": 5234,
+      "budget": 4000,
+      "excessTokens": 1234,
+      "constraint": "maxTokens"
+    }
+  }
+}
+```
+
+#### 9.5.4 Token Estimation Algorithm (Normative)
+
+Servers MUST implement this algorithm or equivalent (within +/- 10%):
+
+```
+FUNCTION estimate_tokens(value, depth = 0):
+    IF depth > 20: RETURN INFINITY
+    IF value IS null: RETURN 1
+    IF value IS boolean: RETURN 1
+    IF value IS number: RETURN max(1, len(stringify(value)) / 4)
+    IF value IS string:
+        graphemes = count_grapheme_clusters(value)
+        RETURN max(1, graphemes / 4.0)
+    IF value IS array:
+        tokens = 2  // []
+        FOR item IN value:
+            tokens += estimate_tokens(item, depth + 1) + 1
+        RETURN tokens
+    IF value IS object:
+        tokens = 2  // {}
+        FOR key, val IN value:
+            tokens += estimate_tokens(key, depth + 1)
+            tokens += 2  // : and ,
+            tokens += estimate_tokens(val, depth + 1)
+        RETURN tokens
+```
+
+**Requirements:**
+- Count grapheme clusters (not bytes) for unicode
+- Enforce max depth of 20
+- Handle circular references
+- Complete within 10ms for 100KB payloads
+
 ---
 
-## 9. Strictness
+## 10. Strictness
 
 - Agent surfaces SHOULD default `strict=true`.
 - Strict mode violations SHOULD fail with contract/validation error codes.
@@ -153,7 +386,7 @@ Rules:
 
 ---
 
-## 10. Versioning and Deprecation
+## 11. Versioning and Deprecation
 
 - Protocol versions MUST follow SemVer.
 - Minor/patch changes MUST be backward compatible.
@@ -164,6 +397,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,6 +1,6 @@
 {
   "name": "@cleocode/lafs-protocol",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "private": false,
   "type": "module",
   "description": "LLM-Agent-First Specification schemas and conformance tooling",
@@ -50,13 +50,18 @@
   ],
   "license": "MIT",
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@types/express": "^5.0.6",
     "@types/node": "^24.3.0",
+    "@types/supertest": "^6.0.3",
+    "supertest": "^7.2.2",
     "tsx": "^4.20.5",
     "typescript": "^5.9.2",
     "vitest": "^2.1.9"
   },
   "dependencies": {
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1"
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "express": "^5.2.1"
   }
 }

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/discovery.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lafs.dev/schemas/v1/discovery.schema.json",
+  "title": "LAFS Discovery Document",
+  "description": "Schema for LAFS agent discovery documents served at /.well-known/lafs.json",
+  "type": "object",
+  "required": [
+    "$schema",
+    "lafs_version",
+    "service",
+    "capabilities",
+    "endpoints"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of the schema this document conforms to"
+    },
+    "lafs_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "LAFS protocol version (semantic versioning)"
+    },
+    "service": {
+      "type": "object",
+      "description": "Service identification and metadata",
+      "required": [
+        "name",
+        "version"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Unique service name (kebab-case recommended)"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Service version (semantic versioning)"
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Human-readable service description"
+        }
+      },
+      "additionalProperties": false
+    },
+    "capabilities": {
+      "type": "array",
+      "description": "List of LAFS capabilities this service provides",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "version",
+          "operations"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "description": "Capability identifier (kebab-case recommended)"
+          },
+          "version": {
+            "type": "string",
+            "pattern": "^\\d+\\.\\d+\\.\\d+$",
+            "description": "Capability version (semantic versioning)"
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "Human-readable capability description"
+          },
+          "operations": {
+            "type": "array",
+            "description": "List of operations this capability supports",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 50
+            }
+          },
+          "optional": {
+            "type": "boolean",
+            "default": false,
+            "description": "Whether this capability is optional for clients"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "endpoints": {
+      "type": "object",
+      "description": "URL endpoints for LAFS operations",
+      "required": [
+        "envelope",
+        "discovery"
+      ],
+      "properties": {
+        "envelope": {
+          "type": "string",
+          "minLength": 1,
+          "description": "URL for envelope submission (POST)"
+        },
+        "context": {
+          "type": "string",
+          "minLength": 1,
+          "description": "URL for context ledger operations"
+        },
+        "discovery": {
+          "type": "string",
+          "minLength": 1,
+          "description": "URL of this discovery document"
+        }
+      },
+      "additionalProperties": false
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Extension fields for vendor-specific metadata",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}