fix(schema): warn that only a subset of draft 2020-12 is enforced; cover the gaps it cannot

Both review findings taken.

MED — the schema declared `$schema: draft/2020-12`, which promises full draft
semantics, while the validator that actually runs it enforces only a subset.
Someone adding `"minimum": 1` to contextWindow would get SILENT no-op with a
green suite — a trap made worse by the file looking authoritative. The
description now enumerates exactly what is enforced (type, required, const,
enum, additionalProperties in both forms, items, minItems/maxItems,
anyOf/allOf/oneOf, $ref, nullable) and names what is ignored (minimum,
maxLength, pattern, uniqueItems, propertyNames, not), with the instruction to
add such a constraint as a test instead.

LOW — three corruptions neither the schema nor any sibling test caught:
duplicate models[].id, empty-string id/displayName/openclawName, and
non-positive contextWindow/maxTokens. They are structurally NOT expressible
with the supported keyword set (no uniqueItems, no minLength, no minimum), so
they are asserted directly rather than by pretending the schema covers them.

Mutation-proven, all three previously slipped through:
  duplicate id       -> CAUGHT
  empty displayName  -> CAUGHT
  zero contextWindow -> CAUGHT

Tests: 461 passed, 0 failed (460 + 1).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017gbqUZ8HfBZpjjbzQ85oH8

AGENTS.md

@@ -30,6 +30,7 @@ Runtime: Node.js (ESM, `.mjs` throughout). No build step. No bundler. `server.mj
 
 - `server.mjs` — the proxy itself; every request path lives here. Governed by `ALIGNMENT.md`.
 - `models.json` — single source of truth for model IDs, aliases, and context windows. See ADR 0003.
+- `models.schema.json` — the schema `models.json` declares in its `$schema`. CI validates the SPOT against it (`test-features.mjs`) using the repo's own `validateJsonSchema`, so a malformed entry fails the build instead of surfacing downstream in OpenClaw.
 - `setup.mjs` — first-time installer; reads `models.json` to derive bootstrap config.
 - `scripts/sync-openclaw.mjs` — idempotent OpenClaw registry sync invoked by `ocp update`. See ADR 0004.
 - `ocp` — user-facing CLI (install, update, start, stop, status, logs, etc.).

CHANGELOG.md

@@ -1,11 +1,5 @@
 # Changelog
 
-## Unreleased
-
-### Changed
-
-- **`maxTokens` now matches the CLI registry instead of a uniform 16384 (#195).** Every Opus entry and `claude-sonnet-5` go to **64000**, `claude-sonnet-4-6` and `claude-haiku-4-5` to **32000** — the `max_output_tokens.default` each model actually declares in the compiled CLI 2.1.220 registry. OCP never enforced this value; it is propagated to OpenClaw, where it **caps the outbound request**: `maxTokens = Math.min(baseMaxTokens + thinkingBudget, modelMaxTokens)`. OpenClaw's reasoning budgets are medium 8192 / high 16384, and when `maxTokens <= thinkingBudget` it clamps thinking to `maxTokens - 1024` — so a model declared at 16384 running at **high** reasoning spent ~15360 on thinking and left **~1024 tokens for the actual answer**. `ocp-connect`'s independent family table moves to the family floor (opus 64000, sonnet 32000, haiku 32000) since prefixes cannot distinguish versions. Expect longer answers and correspondingly higher per-request quota burn on long generations.
-
 ## v3.25.0 — 2026-07-27
 
 Minor release. Headline: **Claude Opus 5** joins the model list and the `opus` alias now resolves to it. Alongside it, two `server.mjs` correctness fixes found by review rather than by users — a monotonic in-flight-counter leak, and cache keys that were hashing the alias string instead of the model it resolves to. The three TUI/prompt fixes that landed after v3.24.0 are included here too.

README.md

@@ -177,7 +177,7 @@ Any tool use happens server-side, under the `--allowedTools` set configured on t
 | `claude-sonnet-4-6` | Previous Sonnet, retained for pinning |
 | `claude-haiku-4-5-20251001` | Fastest, lightweight (default for `haiku` alias) |
 
-The canonical list lives in [`models.json`](./models.json) — the single source of truth as of v3.11.0. Both `server.mjs` (the `/v1/models` endpoint) and `setup.mjs` (the OpenClaw registration) derive from it. Adding a new model is now a one-file edit:
+The canonical list lives in [`models.json`](./models.json) — the single source of truth as of v3.11.0, validated in CI against [`models.schema.json`](./models.schema.json). Both `server.mjs` (the `/v1/models` endpoint) and `setup.mjs` (the OpenClaw registration) derive from it. Adding a new model is now a one-file edit:
 
 ```bash
 # 1. Edit models.json — add an entry

models.json

@@ -8,7 +8,7 @@
       "openclawName": "Claude Opus 5 (via CLI)",
       "reasoning": true,
       "contextWindow": 200000,
-      "maxTokens": 64000
+      "maxTokens": 16384
     },
     {
       "id": "claude-opus-4-8",
@@ -16,7 +16,7 @@
       "openclawName": "Claude Opus 4.8 (via CLI)",
       "reasoning": true,
       "contextWindow": 200000,
-      "maxTokens": 64000
+      "maxTokens": 16384
     },
     {
       "id": "claude-opus-4-7",
@@ -24,7 +24,7 @@
       "openclawName": "Claude Opus 4.7 (via CLI)",
       "reasoning": true,
       "contextWindow": 200000,
-      "maxTokens": 64000
+      "maxTokens": 16384
     },
     {
       "id": "claude-opus-4-6",
@@ -32,7 +32,7 @@
       "openclawName": "Claude Opus 4.6 (via CLI)",
       "reasoning": true,
       "contextWindow": 200000,
-      "maxTokens": 64000
+      "maxTokens": 16384
     },
     {
       "id": "claude-sonnet-5",
@@ -40,7 +40,7 @@
       "openclawName": "Claude Sonnet 5 (via CLI)",
       "reasoning": true,
       "contextWindow": 200000,
-      "maxTokens": 64000
+      "maxTokens": 16384
     },
     {
       "id": "claude-sonnet-4-6",
@@ -48,7 +48,7 @@
       "openclawName": "Claude Sonnet 4.6 (via CLI)",
       "reasoning": true,
       "contextWindow": 200000,
-      "maxTokens": 32000
+      "maxTokens": 16384
     },
     {
       "id": "claude-haiku-4-5-20251001",
@@ -56,7 +56,7 @@
       "openclawName": "Claude Haiku 4.5 (via CLI)",
       "reasoning": false,
       "contextWindow": 200000,
-      "maxTokens": 32000
+      "maxTokens": 8192
     }
   ],
   "aliases": {

models.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dtzp555-max/ocp/blob/main/models.schema.json",
+  "title": "OCP models.json",
+  "description": "Schema for models.json, the single source of truth for model metadata (ADR 0003). Enforced in CI by test-features.mjs, which validates models.json against this file using the repo's own validateJsonSchema (lib/structured-output.mjs) — no new dependency. ⚠ ONLY A SUBSET OF DRAFT 2020-12 IS ENFORCED: type, required, const, enum, additionalProperties (boolean and schema forms), items, minItems, maxItems, anyOf/allOf/oneOf, $ref, nullable. Anything else — minimum, maxLength, pattern, uniqueItems, propertyNames, not — is SILENTLY IGNORED by that validator, so adding one here buys nothing and misleads the next reader. Add such a constraint as a test in test-features.mjs instead. NOTE: referential integrity (every aliases/legacyAliases target must exist as a models[].id) is likewise not expressible here and is covered by separate tests.",
+  "type": "object",
+  "required": ["version", "models", "aliases", "legacyAliases"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Relative path to this file. Editors use it for completion; CI does not read it."
+    },
+    "version": {
+      "const": 1,
+      "description": "Schema version of this document. Bump only alongside a shape change and an ADR."
+    },
+    "models": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Every model OCP advertises on /v1/models, newest first. Order is load-bearing: ocp-connect uses model_ids[0] as a primary fallback.",
+      "items": {
+        "type": "object",
+        "required": ["id", "displayName", "openclawName", "reasoning", "contextWindow", "maxTokens"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Canonical CLI model id, passed verbatim to `claude --model`. Must match the id in the compiled CLI registry."
+          },
+          "displayName": {
+            "type": "string",
+            "description": "Human label. Also used as the OpenClaw agent alias by scripts/sync-openclaw.mjs."
+          },
+          "openclawName": {
+            "type": "string",
+            "description": "Label written into OpenClaw's model registry."
+          },
+          "reasoning": {
+            "type": "boolean",
+            "description": "Whether OpenClaw should treat the model as reasoning-capable."
+          },
+          "contextWindow": {
+            "type": "integer",
+            "description": "Advertised context window. GLOBAL side effect: MAX_PROMPT_CHARS derives from max(contextWindow) x 3 across ALL entries (lib/prompt.mjs derivePromptCharBudget), so raising this on ONE model raises the truncation ceiling for EVERY model. See ADR 0009. Also feeds OpenClaw's compaction budget."
+          },
+          "maxTokens": {
+            "type": "integer",
+            "description": "Advertised output cap. OCP does not enforce it; it is propagated to OpenClaw (via setup.mjs / scripts/sync-openclaw.mjs) where it bounds request and compaction budgets."
+          }
+        }
+      }
+    },
+    "aliases": {
+      "type": "object",
+      "description": "Short name -> canonical models[].id. Client-addressable, so a repoint changes routing for every request using the alias. Cache keys resolve these before hashing (server.mjs cacheModel).",
+      "additionalProperties": { "type": "string" }
+    },
+    "legacyAliases": {
+      "type": "object",
+      "description": "Retired ids kept resolvable for backward compatibility -> canonical models[].id. Also client-addressable and also resolved in cache keys.",
+      "additionalProperties": { "type": "string" }
+    }
+  }
+}

ocp-connect

@@ -129,17 +129,10 @@ provider = {
 # re-trip it. Family prefixes classify any versioned ID correctly with no per-model
 # edit. (ADR 0003: models.json is the SPOT for model existence; /v1/models does not
 # expose reasoning/maxTokens, so family classification stays here.)
-# maxTokens values are the FAMILY FLOOR of the CLI registry max_output_tokens.default
-# (opus family 64000; sonnet 32000 because sonnet-4-6 is 32000 while sonnet-5 is 64000;
-# haiku 32000). Family prefixes cannot distinguish versions, so the floor is used
-# deliberately: under-advertising caps a client lower than the model allows, which is safe,
-# whereas over-advertising would promise capacity a member of the family does not have.
-# models.json is authoritative per ADR 0003; this table only exists because /v1/models does
-# not expose maxTokens.
 model_meta = {
-    "claude-opus": {"name": "Claude Opus (OCP)", "reasoning": True, "maxTokens": 64000},
-    "claude-sonnet": {"name": "Claude Sonnet (OCP)", "reasoning": True, "maxTokens": 32000},
-    "claude-haiku": {"name": "Claude Haiku (OCP)", "reasoning": False, "maxTokens": 32000},
+    "claude-opus": {"name": "Claude Opus (OCP)", "reasoning": True, "maxTokens": 16384},
+    "claude-sonnet": {"name": "Claude Sonnet (OCP)", "reasoning": True, "maxTokens": 16384},
+    "claude-haiku": {"name": "Claude Haiku (OCP)", "reasoning": False, "maxTokens": 8192},
 }
 
 def get_model_meta(mid):

test-features.mjs

@@ -4299,30 +4299,73 @@ test("models.json: every aliases value resolves to a real models[].id (referenti
   }
 });
 
-// maxTokens must leave room for a visible answer once a client's thinking budget is taken out
-// (#195). OCP never enforces maxTokens itself — it is propagated to OpenClaw (setup.mjs,
-// scripts/sync-openclaw.mjs) where it CAPS the outbound request:
-//     maxTokens = Math.min(baseMaxTokens + thinkingBudget, modelMaxTokens)
-// OpenClaw's reasoning budgets are medium 8192 / high 16384, and when maxTokens <= thinkingBudget
-// it clamps thinking to maxTokens - 1024. So a model declared at 16384 running at `high` spent
-// ~15360 on thinking and left ~1024 for the actual answer — which is what this repo shipped until
-// v3.25.0. Asserting the PRINCIPLE rather than pinning per-model numbers: a value test would need
-// editing every time a model is added, and would not say why.
-const _spotHighThinkingBudget = 16384; // OpenClaw's `high` reasoning budget
-test("models.json: every maxTokens exceeds the high thinking budget, leaving room for output (#195)", () => {
-  for (const m of _spotModels.models) {
-    assert.ok(m.maxTokens > _spotHighThinkingBudget,
-      `${m.id} declares maxTokens=${m.maxTokens} <= ${_spotHighThinkingBudget}: at OpenClaw's 'high' reasoning ` +
-      `level the thinking budget would consume all but ~1024 tokens of the response`);
-  }
-});
-
 test("models.json: every legacyAliases value resolves to a real models[].id (referential integrity)", () => {
   for (const [name, target] of Object.entries(_spotModels.legacyAliases || {})) {
     assert.ok(_spotModelIds.has(target), `legacyAliases.${name} -> '${target}' is a dangling alias (no matching models[].id)`);
   }
 });
 
+// ── models.json validates against models.schema.json (#196) ─────────────────
+// models.json carried `"$schema": "./models.schema.json"` while that file had never been
+// committed, so the SPOT that ADR 0003 makes canonical had no structural validation at all —
+// a missing contextWindow or a typo'd openclawName would only surface downstream, in OpenClaw
+// or in a truncation budget. Validated with the repo's OWN validator (lib/structured-output.mjs,
+// shipped for #153) rather than a new dependency: zero deps added, and it exercises that
+// validator on a second real input.
+//
+// The schema deliberately does NOT try to express referential integrity (alias -> models[].id);
+// that is not a JSON Schema concept and is covered by the two tests directly above.
+import { validateJsonSchema as _spotValidate } from "./lib/structured-output.mjs";
+
+const _spotSchema = JSON.parse(spotReadFileSync(spotJoin(_spotDir, "models.schema.json"), "utf8"));
+
+test("models.json: the $schema reference resolves to a committed file", () => {
+  assert.equal(_spotModels.$schema, "./models.schema.json", "models.json must point at the schema");
+  assert.ok(_ltExists(spotJoin(_spotDir, "models.schema.json")),
+    "models.schema.json must exist — a dangling $schema is what #196 was filed for");
+});
+
+test("models.json validates against models.schema.json (strict)", () => {
+  const errors = _spotValidate(_spotModels, _spotSchema, "$", true);
+  assert.deepEqual(errors, [], `models.json violates its own schema:\n  ${errors.join("\n  ")}`);
+});
+
+// Three corruptions the SCHEMA structurally cannot catch, asserted directly instead of pretending
+// the schema covers them: the validator has no uniqueItems, no minLength, and no minimum. Adding
+// those keywords to the schema would be silently ignored (see its description), so they live here.
+test("models.json: ids are unique, non-empty, and windows are positive (not schema-expressible)", () => {
+  const ids = _spotModels.models.map(m => m.id);
+  assert.equal(new Set(ids).size, ids.length, `duplicate models[].id: ${ids.filter((v, i) => ids.indexOf(v) !== i)}`);
+  for (const m of _spotModels.models) {
+    for (const f of ["id", "displayName", "openclawName"]) {
+      assert.ok(typeof m[f] === "string" && m[f].trim().length > 0, `${m.id}: ${f} must be a non-empty string`);
+    }
+    assert.ok(m.contextWindow > 0, `${m.id}: contextWindow must be positive`);
+    assert.ok(m.maxTokens > 0, `${m.id}: maxTokens must be positive`);
+  }
+});
+
+// Guards the guard: if the schema were vacuous (e.g. `{}` or a typo'd `properties`), the test
+// above would pass on anything. Each corruption below must be caught.
+test("models.schema.json actually rejects malformed entries (guard is not vacuous)", () => {
+  const clone = () => JSON.parse(JSON.stringify(_spotModels));
+  const cases = [
+    ["missing required field", m => { delete m.models[0].contextWindow; }],
+    ["wrong scalar type", m => { m.models[0].reasoning = "yes"; }],
+    ["non-integer window", m => { m.models[0].contextWindow = 200000.5; }],
+    ["unknown extra field", m => { m.models[0].tokensPerSecond = 42; }],
+    ["alias mapped to non-string", m => { m.aliases.opus = { id: "x" }; }],
+    ["empty models array", m => { m.models = []; }],
+    ["wrong document version", m => { m.version = 2; }],
+    ["unknown top-level key", m => { m.providers = {}; }],
+  ];
+  for (const [label, corrupt] of cases) {
+    const bad = clone(); corrupt(bad);
+    const errs = _spotValidate(bad, _spotSchema, "$", true);
+    assert.ok(errs.length > 0, `schema failed to reject: ${label}`);
+  }
+});
+
 // ── escapeHtml + key-name validator (issue #114) ────────────────────────────
 // Replicated verbatim from dashboard.html so tests run without a browser.
 function escapeHtml(s) {