From 37d9a9e76f3b9f0e8febc76f6a885668e78a99c0 Mon Sep 17 00:00:00 2001 From: Greg Soucy Date: Fri, 20 Mar 2026 12:27:00 -0400 Subject: [PATCH] [runtime] sync docs to v1.1.0 runtime cut Why: align runtime-layer docs with the v1.1.0 route, x402 default, and schema-validation behavior described for this cut. Contract impact: none --- README.md | 6 ++++-- SECURITY.md | 4 +++- docs/CONFIGURATION.md | 12 ++++++++++-- docs/OPERATIONS.md | 6 ++++-- 4 files changed, 21 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 77b90ee..5548aa3 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The runtime currently exposes: - `GET /health` — health and signer/verifier readiness. - `GET /healthz` — alias for `/health`. - `POST /verify` — receipt hash/signature verification, with optional ENS lookup and optional schema validation. -- `POST //v1.0.0` for the verbs enabled by `ENABLED_VERBS`. +- `POST //v1.1.0` for the verbs enabled by `ENABLED_VERBS`. The default enabled verbs are: @@ -99,7 +99,9 @@ Supported query flags: - `refresh=1` — refresh ENS cache before verifying. - `schema=1` — validate the receipt against the verb receipt schema. -When `schema=1`, schema validation uses the receipt verb to compute a schema URL under `SCHEMA_HOST`. +When `schema=1`, schema validation uses the receipt verb to compute a `v1.1.0` receipt schema URL under `SCHEMA_HOST`. + +When a verb request omits `x402`, the runtime fabricates defaults from the live route version: `version: "1.1.0"` and `entry: "x402://agent.eth//v1.1.0"`. When `VERIFY_SCHEMA_CACHED_ONLY=1` (the default), `/verify?schema=1` returns HTTP `202` with `validator_not_warmed_yet` if the validator for that verb has not been compiled yet. `POST /debug/prewarm` can queue validator warmup, and `GET /debug/validators` shows cache state. diff --git a/SECURITY.md b/SECURITY.md index d2d9f78..4ff018b 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -17,7 +17,7 @@ Include: | Version | Supported | |---|---| -| `1.0.x` | Yes | +| `1.1.x` | Yes | ## Current implementation notes @@ -78,6 +78,8 @@ ENS-backed verification currently reads these TXT records directly from the sign The server does not implement `VERIFIER_ENS_NAME` or `ENS_SIGNER_TEXT_KEY`. +When schema verification is requested, the runtime resolves receipt schemas from the `v1.1.0` schema tree under `SCHEMA_HOST`. When a verb request omits `x402`, the runtime fabricates `version: "1.1.0"` and `entry: "x402://agent.eth//v1.1.0"` before signing. + ### Controls not implemented by the current server Do not rely on these as live controls in this repository: diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 77ca3bd..51e6ee9 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -10,7 +10,7 @@ This file documents environment variables that are actually read by `server.mjs` | `PORT` | `8080` | HTTP listen port. | | `SERVICE_NAME` | `commandlayer-runtime` | Returned by `GET /` and `GET /health`. | | `SERVICE_VERSION` | `1.0.0` | Returned by `GET /` and `GET /health`. | -| `API_VERSION` | `1.0.0` | Version segment used when mounting verb routes. | +| `API_VERSION` | `1.1.0` | Version segment used when mounting verb routes. | | `CANONICAL_BASE_URL` | `https://runtime.commandlayer.org` | Returned by `GET /` and `GET /health`. | | `RAILWAY_SERVICE_NAME` | unset | Used only in runtime trace/debug metadata; does not rename the service fields above. | @@ -20,7 +20,7 @@ This file documents environment variables that are actually read by `server.mjs` |---|---| | `ENABLED_VERBS` | `fetch,describe,format,clean,parse,summarize,convert,explain,analyze,classify` | -The server mounts `POST //v1.0.0` only for verbs in this list. If a listed verb has no handler implementation, requests still return `404`. +The server mounts `POST //v1.1.0` only for verbs in this list. If a listed verb has no handler implementation, requests still return `404`. ## Signing identity and key material @@ -83,6 +83,12 @@ Behavior: - `*_PEM`, `*_PEM_FILE`, and `*_PEM_B64` are treated as PEM public keys. - the server converts accepted public-key inputs to SPKI PEM internally for verification. + +If a verb request omits `x402`, the runtime fabricates default values with the live API version: + +- `version: "1.1.0"` +- `entry: "x402://agent.eth//v1.1.0"` + ### Startup behavior - If signing configuration is missing or invalid and `DEV_AUTO_KEYS` is not enabled, the process exits at boot. @@ -125,6 +131,8 @@ Important current behavior: | `VERIFY_SCHEMA_CACHED_ONLY` | `1` | If `1`, `/verify?schema=1` uses only precompiled validators and returns `202` on a cold cache. | | `VERIFY_MAX_MS` | `30000` | Overall timeout budget for `/verify`. | +`SCHEMA_HOST` is used to construct `v1.1.0` receipt schema URLs during `/verify?schema=1`. + `REQUEST_SCHEMA_VALIDATION` is not implemented by `server.mjs`. ## Schema and validator caches diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index cd1c2a7..66cc4df 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -26,10 +26,12 @@ The current server implements: - `GET /health` - `GET /healthz` - `POST /verify` -- `POST //v1.0.0` for enabled verbs +- `POST //v1.1.0` for enabled verbs It does not implement `GET /ready` or `GET /version`. +When callers omit `x402` on a verb request, the runtime fabricates `version: "1.1.0"` and `entry: "x402://agent.eth//v1.1.0"` before signing the receipt. + ### Basic checks ```bash @@ -76,7 +78,7 @@ If debug access is not enabled correctly, the server returns `404` rather than ` ### Schema warmup flow -When `VERIFY_SCHEMA_CACHED_ONLY=1`, schema verification for a cold verb returns `202` and queues warmup work. +When `VERIFY_SCHEMA_CACHED_ONLY=1`, schema verification for a cold verb returns `202` and queues warmup work. Schema validation targets the verb receipt schema under `SCHEMA_HOST/schemas/v1.1.0/...`. You can prewarm validators through the implemented debug route: