agent-control-plane-core 0.7.0 → 0.8.0

package/README.md

@@ -234,6 +234,44 @@ The harness pins both directions and rejects a vacuous suite:
 
 See `src/fixtures/claude.json` and `src/fixtures/codex.json` for the format.
 
+## Validating from another language
+
+A guardrail that is not JavaScript cannot import `ToolCallEvent`, so it
+hand-writes the field names it reads. It then drifts in the quietest direction:
+the contract renames a field, the hand-written reader sees `undefined`, and it
+takes its no-value branch instead of failing. The package ships the same
+contract as JSON Schema (draft 2020-12), so that reader validates against the
+seam instead of against its own copy.
+
+```python
+import json, pathlib, jsonschema  # a Python guardrail reading the event
+base = pathlib.Path("node_modules/agent-control-plane-core/schema/control-plane/v1")
+schema = json.loads((base / "tool-call-event.schema.json").read_text())
+jsonschema.validate(event, schema)  # raises on a field the contract does not model
+```
+
+`tool-input-keys.json` sits beside them and publishes the input field a judge
+should read per canonical tool (`Bash` → `command`, `Read` → `file_path`), so a
+consumer looks that up rather than hard-coding it. It is plain data, not a
+schema: a validator refuses an unknown keyword under its default options, so a
+document carrying that map inside itself would not compile for the consumer who
+installed it.
+
+The event document also refuses two claims a producer must not make, each one a
+veto the host will never perform: a `this_call_vetoable` `unknown` event, and a
+`this_call_vetoable` event on an `observe_only` transport.
+
+`pnpm gen:schema` generates the files from `src/control-plane.mjs`, and
+`test/json-schema.test.mjs` byte-compares the result, so a stale document reds
+the suite. The same suite validates every adapter's live output against the
+published bytes, so a renamed contract field reds too. A JavaScript caller
+builds the documents in memory from `agent-control-plane-core/json-schema`
+instead of reading the files.
+
+Read the schema from the installed package rather than pinning a copy by hand. A
+document is one release's rendering of the wire version, and an added optional
+field (backward-compatible, below) appears in the next release's document.
+
 ## Versioning
 
 `src/control-plane.mjs` is the frozen contract and its own single source of
@@ -249,6 +287,7 @@ and bumps the version.
 pnpm test           # node --test
 pnpm test:coverage  # c8, 100% lines/branches/functions per file
 pnpm check          # tsc --noEmit (JSDoc types)
+pnpm gen:schema     # regenerate schema/ from the contract
 pnpm lint           # eslint
 pnpm build          # emit .d.mts declarations into types/
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane-core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Vendor-neutral control-plane contract for coding agents: a normalized ToolCallEvent/Verdict schema with per-agent adapters (Claude Code, Codex, Amp, Gemini CLI) and a conformance suite.",
   "type": "module",
   "repository": {
@@ -60,12 +60,17 @@
     "./runtime": {
       "types": "./types/runtime.d.mts",
       "import": "./src/runtime.mjs"
+    },
+    "./json-schema": {
+      "types": "./types/json-schema.d.mts",
+      "import": "./src/json-schema.mjs"
     }
   },
   "files": [
     "src",
     "types",
-    "bin"
+    "bin",
+    "schema"
   ],
   "keywords": [
     "claude",
@@ -117,6 +122,7 @@
     "@eslint/js": "^9.13.0",
     "@types/node": "^22.7.0",
     "@types/semver": "^7.5.8",
+    "ajv": "^8.20.0",
     "c8": "^10.1.2",
     "eslint": "^9.13.0",
     "fast-check": "^3.22.0",
@@ -127,6 +133,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "gen:schema": "node scripts/gen-json-schema.mjs",
     "test": "node --test test/*.test.mjs",
     "test:coverage": "c8 node --test test/*.test.mjs",
     "check": "tsc --noEmit",

package/schema/control-plane/v1/tool-call-event.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ToolCallEvent",
+  "description": "A normalized, agent-agnostic view of one agent event (control-plane/v1).",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "event",
+    "tool",
+    "input",
+    "this_call_vetoable",
+    "meta"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "event": {
+      "enum": [
+        "pre_tool",
+        "post_tool",
+        "prompt_submit",
+        "session_start",
+        "unknown"
+      ]
+    },
+    "tool": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Canonical tool name; null for prompt and session events. The raw native name is on meta.native_tool."
+    },
+    "input": {
+      "type": "object",
+      "description": "Passthrough tool input, verbatim; a submitted prompt is folded into input.prompt."
+    },
+    "response": {
+      "description": "Tool output, post_tool only: any JSON value, verbatim."
+    },
+    "this_call_vetoable": {
+      "type": "boolean",
+      "description": "false ⇒ the guardrail cannot veto THIS call, so a deny must degrade to a notification."
+    },
+    "meta": {
+      "$ref": "#/$defs/EventMeta"
+    }
+  },
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "if": {
+        "required": [
+          "event"
+        ],
+        "properties": {
+          "event": {
+            "const": "unknown"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "this_call_vetoable": {
+            "const": false
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "required": [
+          "meta"
+        ],
+        "properties": {
+          "meta": {
+            "required": [
+              "integration_mode"
+            ],
+            "properties": {
+              "integration_mode": {
+                "const": "observe_only"
+              }
+            }
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "this_call_vetoable": {
+            "const": false
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "EventMeta": {
+      "type": "object",
+      "required": [
+        "agent",
+        "native_event",
+        "integration_mode",
+        "primary_gate_present",
+        "passthrough"
+      ],
+      "properties": {
+        "agent": {
+          "type": "string",
+          "description": "Producing agent id (\"claude\", \"codex\", …)."
+        },
+        "native_event": {
+          "type": "string",
+          "description": "Original native event name, preserved verbatim."
+        },
+        "integration_mode": {
+          "enum": [
+            "external_hook",
+            "in_process",
+            "observe_only"
+          ],
+          "description": "How the guardrail attaches to the host."
+        },
+        "primary_gate_present": {
+          "type": "boolean",
+          "description": "The agent's own native gate already ran, so this verdict is a second opinion."
+        },
+        "passthrough": {
+          "type": "object",
+          "description": "Unmodelled native top-level fields, verbatim."
+        },
+        "native_tool": {
+          "type": "string",
+          "description": "Original native tool name, present iff the event carries a tool."
+        },
+        "session_id": {
+          "type": "string"
+        },
+        "cwd": {
+          "type": "string"
+        },
+        "permission_mode": {
+          "type": "string"
+        },
+        "transcript_path": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/control-plane/v1/tool-input-keys.json

@@ -0,0 +1,7 @@
+{
+  "Bash": "command",
+  "Edit": "file_path",
+  "Write": "file_path",
+  "Read": "file_path",
+  "WebFetch": "url"
+}

package/schema/control-plane/v1/verdict.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Verdict",
+  "description": "A normalized guardrail decision (control-plane/v1).",
+  "type": "object",
+  "required": [
+    "decision"
+  ],
+  "properties": {
+    "decision": {
+      "enum": [
+        "allow",
+        "deny",
+        "ask"
+      ]
+    },
+    "mutated_input": {
+      "type": "object",
+      "description": "Replacement tool input (pre_tool). A data channel, carried verbatim."
+    },
+    "mutated_output": {
+      "description": "Replacement tool output (post_tool): a string or the tool's structured output, verbatim. Any JSON value."
+    },
+    "additional_context": {
+      "type": "string",
+      "description": "Extra context to splice into the agent's stream."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Human-readable rationale, shown on deny and ask."
+    }
+  },
+  "additionalProperties": false
+}

package/src/adapters/amp.mjs

@@ -190,22 +190,52 @@ const EXIT_CODE_BY_DECISION = Object.freeze({
 });
 
 /**
- * Totality check at IMPORT: every {@link Decision} must have a row and every row
- * both vetoable columns. A decision added to the contract breaks this module
- * loudly at load instead of silently defaulting to exit 0.
+ * Totality check: every `decision` in `decisions` must have a row in `table`
+ * and every row both vetoable columns. A decision added to the contract with
+ * no matching row breaks loudly instead of silently defaulting to exit 0.
+ * Called at import against {@link Decision} and {@link EXIT_CODE_BY_DECISION};
+ * exported so a test can drive both branches.
+ * @param {readonly string[]} decisions
+ * @param {Readonly<Record<string, Readonly<Record<string, number>>>>} table
  */
-for (const decision of Object.values(Decision)) {
-  const row = lookup(EXIT_CODE_BY_DECISION, decision);
-  if (row === undefined)
-    throw new Error(
-      `amp adapter: exit-code table has no row for decision ${JSON.stringify(decision)}`,
-    );
-  for (const vetoable of ["true", "false"]) {
-    if (typeof lookup(row, vetoable) === "number") continue;
+export function assertExitCodeTableTotal(decisions, table) {
+  for (const decision of decisions) {
+    const row = lookup(table, decision);
+    if (row === undefined)
+      throw new Error(
+        `amp adapter: exit-code table has no row for decision ${JSON.stringify(decision)}`,
+      );
+    for (const vetoable of ["true", "false"]) {
+      if (typeof lookup(row, vetoable) === "number") continue;
+      throw new Error(
+        `amp adapter: exit-code table row ${JSON.stringify(decision)} has no this_call_vetoable=${vetoable} column`,
+      );
+    }
+  }
+}
+
+assertExitCodeTableTotal(Object.values(Decision), EXIT_CODE_BY_DECISION);
+
+/**
+ * Look up the exit code for `decision`/`vetoable` in `table`. Throws instead of
+ * returning `undefined`: the alternative is `exit_code: undefined`, which
+ * `process.exit` renders as 0 — the exact silent allow this table exists to
+ * eliminate. Unreachable from {@link render} on the real
+ * {@link EXIT_CODE_BY_DECISION} while {@link assertExitCodeTableTotal} holds at
+ * load; exported so a test can drive both branches against a synthetic,
+ * deliberately incomplete table.
+ * @param {Readonly<Record<string, Readonly<Record<string, number>>>>} table
+ * @param {string} decision
+ * @param {boolean} vetoable
+ * @returns {number}
+ */
+export function exitCodeFor(table, decision, vetoable) {
+  const exit_code = lookup(lookup(table, decision) ?? {}, String(vetoable));
+  if (exit_code === undefined)
     throw new Error(
-      `amp adapter: exit-code table row ${JSON.stringify(decision)} has no this_call_vetoable=${vetoable} column`,
+      `amp adapter: exit-code table has no entry for decision ${JSON.stringify(decision)} / this_call_vetoable ${JSON.stringify(vetoable)}`,
     );
-  }
+  return exit_code;
 }
 
 /**
@@ -234,18 +264,7 @@ export function render(verdict, event) {
       `amp adapter: this_call_vetoable must be a boolean, got ${JSON.stringify(vetoable)}`,
     );
   const enforced = vd.decision === Decision.DENY && vetoable;
-  const exit_code = lookup(
-    lookup(EXIT_CODE_BY_DECISION, vd.decision) ?? {},
-    String(vetoable),
-  );
-  // Unreachable while the import-time totality check and `normalizeVerdict` both
-  // hold; kept because the alternative to throwing is `exit_code: undefined`,
-  // which `process.exit` renders as 0 — the exact silent allow this table exists
-  // to eliminate.
-  if (exit_code === undefined)
-    throw new Error(
-      `amp adapter: exit-code table has no entry for decision ${JSON.stringify(vd.decision)} / this_call_vetoable ${JSON.stringify(vetoable)}`,
-    );
+  const exit_code = exitCodeFor(EXIT_CODE_BY_DECISION, vd.decision, vetoable);
   return nativeResponse({
     transport: INTEGRATION_MODE,
     exit_code,

package/src/conformance.mjs

@@ -218,17 +218,23 @@ const CONTENT_PROBE_VALUES = Object.freeze({
   ]),
 });
 
-// A field added to VERDICT_CONTENT_FIELDS with no probe value would be dropped
-// by normalizeVerdict and then reported as "reaches no native channel" against
-// every adapter, naming the adapter for the harness's own omission.
-if (
-  VERDICT_CONTENT_FIELDS.some(
-    (field) => (lookup(CONTENT_PROBE_VALUES, field) ?? []).length < 2,
-  )
-)
-  throw new Error(
-    `conformance: CONTENT_PROBE_VALUES needs two or more values for each of ${VERDICT_CONTENT_FIELDS.join(", ")}`,
-  );
+/**
+ * A field added to VERDICT_CONTENT_FIELDS with no probe value would be dropped
+ * by normalizeVerdict and then reported as "reaches no native channel" against
+ * every adapter, naming the adapter for the harness's own omission. Called at
+ * import against the live {@link CONTENT_PROBE_VALUES}; exported so a test can
+ * drive both branches.
+ * @param {readonly string[]} fields
+ * @param {Record<string, readonly unknown[]>} values
+ */
+export function assertContentProbeValuesComplete(fields, values) {
+  if (fields.some((field) => (lookup(values, field) ?? []).length < 2))
+    throw new Error(
+      `conformance: CONTENT_PROBE_VALUES needs two or more values for each of ${fields.join(", ")}`,
+    );
+}
+
+assertContentProbeValuesComplete(VERDICT_CONTENT_FIELDS, CONTENT_PROBE_VALUES);
 
 /**
  * Rule ⑩'s first half: the adapter declares a row for EVERY {@link EventKind}.
@@ -601,8 +607,13 @@ function assertContentChannels(adapter, event, caseName, assert, seen) {
   // nowhere to hide.
   /** @param {string} field @param {Record<string, unknown>} held @param {string} shape */
   const carries = (field, held, shape) => {
-    const values = lookup(CONTENT_PROBE_VALUES, field) ?? [];
-    if (values.length < 2) return;
+    // `field` is always a VERDICT_CONTENT_FIELDS member (the only caller below
+    // iterates it), and assertContentProbeValuesComplete guarantees at import
+    // that every such member has two or more entries here — so neither a
+    // missing row nor a short one can reach this point.
+    const values = /** @type {readonly unknown[]} */ (
+      lookup(CONTENT_PROBE_VALUES, field)
+    );
     const renders = values.map((value) =>
       adapter.render(
         { decision: Decision.ALLOW, ...held, [field]: value },
@@ -680,7 +691,11 @@ function assertContentChannels(adapter, event, caseName, assert, seen) {
     const held = others.reduce(
       (combinations, name) =>
         combinations.flatMap((carried) =>
-          (lookup(CONTENT_PROBE_VALUES, name) ?? []).map((value) => ({
+          // Same guarantee as `carries` above: `name` is a VERDICT_CONTENT_FIELDS
+          // member, so the row is always present.
+          /** @type {readonly unknown[]} */ (
+            lookup(CONTENT_PROBE_VALUES, name)
+          ).map((value) => ({
             ...carried,
             [name]: value,
           })),

package/src/control-plane.mjs

@@ -23,9 +23,11 @@
  * Dependency-free on purpose, so a fail-closed hook can import it without
  * dragging in eager config-file reads.
  *
- * VERSIONING — this module IS the frozen contract (its own SSOT, no parallel
- * schema file to drift). Adapters and guardrail consumers are built against it
- * in parallel, so its shapes are stable: {@link EventKind}, {@link Decision},
+ * VERSIONING — this module IS the frozen contract and its own SSOT. The JSON
+ * Schema documents under `schema/` are GENERATED from it by `pnpm gen:schema`
+ * and byte-compared in `json-schema.test.mjs`, so they are output rather than a
+ * second contract; never hand-edit one. Adapters and guardrail consumers are
+ * built against this module in parallel, so its shapes are stable: {@link EventKind}, {@link Decision},
  * {@link MODELED_TOOLS}, and {@link TOOL_ALIASES} are frozen, and
  * {@link SCHEMA_VERSION} / {@link CONTROL_PLANE_SCHEMA} are pinned
  * (control-plane.test.mjs asserts the exact values, so any shape change is a

package/src/json-schema.mjs

@@ -0,0 +1,331 @@
+/**
+ * JSON Schema (draft 2020-12) for the two wire shapes, for a consumer that is
+ * not JavaScript.
+ *
+ * A Python guardrail cannot import {@link ToolCallEvent} from this package, so
+ * it hand-writes the field names it reads and drifts silently: the contract
+ * renames a field, the hand-written reader sees `undefined`, and it takes its
+ * no-value branch instead of failing. These documents are the machine-readable
+ * form of the same contract, so that reader validates against the seam rather
+ * than against its own copy.
+ *
+ * EVERY ENUMERATED VALUE IS DERIVED, never typed a second time — each one is
+ * read off the frozen export that owns it: {@link EventKind},
+ * {@link Decision}, {@link IntegrationMode}, {@link STANDARD_META_FIELDS},
+ * {@link SCHEMA_VERSION}, {@link MODELED_TOOL_INPUT_KEYS}. The files under
+ * `schema/` are generated output that `json-schema.test.mjs` regenerates and
+ * byte-compares, not a second contract.
+ *
+ * FIELD NAMES ARE WRITTEN HERE, because the contract exports no list of them —
+ * the root fields and the always-present `EventMeta` fields are typedefs, which
+ * do not survive to runtime. So a renamed contract field is caught rather than
+ * declared: `json-schema.test.mjs` re-parses every golden native payload through
+ * the LIVE adapter and validates the result, and `additionalProperties: false`
+ * turns the rename into a rejection. {@link VERDICT_CONTENT_FIELDS} is the one
+ * list that does exist, and {@link assertVerdictFieldsDeclared} holds the
+ * verdict document to it — in the ADDING direction only. `reason` is outside
+ * that list (it is not probeable from one abstaining verdict), so its schema
+ * here rests on the `Verdict` typedef alone.
+ *
+ * SCOPE — the documents describe the contract's DECLARED shapes, which `tsc`
+ * checks at build time. `normalizeVerdict` re-checks only `decision` at run
+ * time, so a JavaScript caller who ignores the types can hand it a numeric
+ * `reason` and get one back; that value fails this document, correctly.
+ *
+ * A tool `input` stays unconstrained on purpose: an adapter forwards a native
+ * input object verbatim, so a schema demanding a string `command` on every Bash
+ * event would reject events the library legitimately emits — one golden Codex
+ * fixture carries `command` as an array. The per-tool field a judge should read
+ * is published beside the documents as data instead
+ * ({@link MODELED_TOOL_INPUT_KEYS}, in `tool-input-keys.json`).
+ */
+
+import {
+  CONTROL_PLANE_SCHEMA,
+  Decision,
+  EventKind,
+  IntegrationMode,
+  MODELED_TOOL_INPUT_KEYS,
+  SCHEMA_VERSION,
+  STANDARD_META_FIELDS,
+  VERDICT_CONTENT_FIELDS,
+} from "./control-plane.mjs";
+
+/** The JSON Schema dialect these documents are written in. */
+const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+
+/**
+ * Package-relative directory the generated files live in, versioned by the WIRE
+ * version. A breaking shape change bumps {@link CONTROL_PLANE_SCHEMA} and so
+ * writes a new directory, leaving the previous one in place for a consumer
+ * still on it.
+ *
+ * A document is THIS RELEASE's rendering of that wire version, not a statement
+ * about every release that will carry it. Adding an optional field is
+ * backward-compatible and stays at v1 (see the README's Versioning section), so
+ * the next release's document may carry a property this one does not. That is
+ * why the files ship inside the package: a consumer reads the schema from the
+ * same installed version that produced the event, and the two move together.
+ * Validate against the installed file, never a copy pinned by hand.
+ *
+ * Neither document carries an `$id`. A URL naming a mutable branch would resolve
+ * to whatever the contract says LATER, and two installed versions declaring one
+ * `$id` collide inside a single validator instance. `$ref` here is
+ * document-relative, so nothing needs one.
+ */
+export const SCHEMA_DIR = `schema/${CONTROL_PLANE_SCHEMA}`;
+
+/** Basename of each generated document, keyed by the shape it describes. */
+export const SCHEMA_FILES = Object.freeze({
+  ToolCallEvent: "tool-call-event.schema.json",
+  Verdict: "verdict.schema.json",
+});
+
+/**
+ * Basename of the per-tool input-key map, published as plain DATA rather than
+ * inside the event document. A vendor keyword there (`x-modeled-tool-input-keys`)
+ * is legal JSON Schema, but ajv refuses an unknown keyword under its default
+ * options, so the document a JavaScript consumer installed would not compile
+ * until that consumer registered a vocabulary it has no reason to know about.
+ */
+export const TOOL_INPUT_KEYS_FILE = "tool-input-keys.json";
+
+/**
+ * The schema for each optional {@link Verdict} field. Kept beside the
+ * assertion below rather than inlined, so a content field added to
+ * {@link VERDICT_CONTENT_FIELDS} fails loud here instead of quietly dropping
+ * out of the published document — a consumer would then read a field the
+ * schema calls forbidden and reject a verdict this library produces.
+ */
+const VERDICT_FIELD_SCHEMAS = Object.freeze({
+  mutated_input: {
+    type: "object",
+    description:
+      "Replacement tool input (pre_tool). A data channel, carried verbatim.",
+  },
+  mutated_output: {
+    description:
+      "Replacement tool output (post_tool): a string or the tool's structured output, verbatim. Any JSON value.",
+  },
+  additional_context: {
+    type: "string",
+    description: "Extra context to splice into the agent's stream.",
+  },
+  reason: {
+    type: "string",
+    description: "Human-readable rationale, shown on deny and ask.",
+  },
+});
+
+/**
+ * Assert every content field the contract models has a schema above. Throws
+ * (fail loud) on the first that does not: `additionalProperties: false` makes an
+ * undeclared field a REJECTION rather than an omission, so a consumer would
+ * refuse a verdict this library produces. Called at import against the live
+ * {@link VERDICT_CONTENT_FIELDS}; exported so a test can drive both branches.
+ * @param {readonly string[]} fields
+ * @param {Record<string, unknown>} declared
+ */
+export function assertVerdictFieldsDeclared(fields, declared) {
+  for (const field of fields)
+    if (!Object.hasOwn(declared, field))
+      throw new Error(
+        `json-schema: verdict content field ${JSON.stringify(field)} has no declared schema — add one to VERDICT_FIELD_SCHEMAS`,
+      );
+}
+
+assertVerdictFieldsDeclared(VERDICT_CONTENT_FIELDS, VERDICT_FIELD_SCHEMAS);
+
+/**
+ * The `EventMeta` subschema. The optional string fields are
+ * {@link STANDARD_META_FIELDS} plus `native_tool`; `string` is not a guess for
+ * them, it is what `baseMeta` enforces (a non-string value leaves the field
+ * absent rather than stamping a number onto a field consumers read as text).
+ * @returns {Record<string, unknown>}
+ */
+function eventMetaSchema() {
+  /** @type {Record<string, unknown>} */
+  const properties = {
+    agent: {
+      type: "string",
+      description: 'Producing agent id ("claude", "codex", …).',
+    },
+    native_event: {
+      type: "string",
+      description: "Original native event name, preserved verbatim.",
+    },
+    integration_mode: {
+      enum: Object.values(IntegrationMode),
+      description: "How the guardrail attaches to the host.",
+    },
+    primary_gate_present: {
+      type: "boolean",
+      description:
+        "The agent's own native gate already ran, so this verdict is a second opinion.",
+    },
+    passthrough: {
+      type: "object",
+      description: "Unmodelled native top-level fields, verbatim.",
+    },
+    native_tool: {
+      type: "string",
+      description:
+        "Original native tool name, present iff the event carries a tool.",
+    },
+  };
+  for (const field of STANDARD_META_FIELDS)
+    properties[field] = { type: "string" };
+  return {
+    type: "object",
+    required: [
+      "agent",
+      "native_event",
+      "integration_mode",
+      "primary_gate_present",
+      "passthrough",
+    ],
+    properties,
+    additionalProperties: false,
+  };
+}
+
+/**
+ * The document describing a normalized {@link ToolCallEvent}.
+ *
+ * `additionalProperties: false` is honest here rather than strict: `makeEvent`
+ * builds every event, and the unmodelled remainder of a native payload lands in
+ * `meta.passthrough`, so an extra key at the root is a hand-rolled event, not a
+ * newer library's.
+ * @returns {Record<string, unknown>}
+ */
+export function toolCallEventSchema() {
+  return {
+    $schema: JSON_SCHEMA_DIALECT,
+    title: "ToolCallEvent",
+    description: `A normalized, agent-agnostic view of one agent event (${CONTROL_PLANE_SCHEMA}).`,
+    type: "object",
+    required: [
+      "schema_version",
+      "event",
+      "tool",
+      "input",
+      "this_call_vetoable",
+      "meta",
+    ],
+    properties: {
+      schema_version: { const: SCHEMA_VERSION },
+      event: { enum: Object.values(EventKind) },
+      tool: {
+        type: ["string", "null"],
+        description:
+          "Canonical tool name; null for prompt and session events. The raw native name is on meta.native_tool.",
+      },
+      input: {
+        type: "object",
+        description:
+          "Passthrough tool input, verbatim; a submitted prompt is folded into input.prompt.",
+      },
+      response: {
+        description: "Tool output, post_tool only: any JSON value, verbatim.",
+      },
+      this_call_vetoable: {
+        type: "boolean",
+        description:
+          "false ⇒ the guardrail cannot veto THIS call, so a deny must degrade to a notification.",
+      },
+      meta: { $ref: "#/$defs/EventMeta" },
+    },
+    additionalProperties: false,
+    // Two claims a producer must not make, both the same fail-open: a veto the
+    // host will never perform, read downstream as a block that happened.
+    //
+    // An event the adapter could not name has no host response to veto, so a
+    // vetoable UNKNOWN is that claim. `makeEvent` throws on one. An OBSERVE_ONLY
+    // transport reads a transcript and cannot pre-empt anything, so a vetoable
+    // event on one is the same claim by a different route — every shipped
+    // adapter derives both flags from one "can this host enforce" answer, but
+    // `makeEvent` does NOT refuse it, so this document is the only place a
+    // producer is held to it.
+    allOf: [
+      vetoImpossibleWhen({ event: { const: EventKind.UNKNOWN } }),
+      vetoImpossibleWhen({
+        meta: {
+          required: ["integration_mode"],
+          properties: {
+            integration_mode: { const: IntegrationMode.OBSERVE_ONLY },
+          },
+        },
+      }),
+    ],
+    $defs: { EventMeta: eventMetaSchema() },
+  };
+}
+
+/**
+ * A conditional subschema forcing `this_call_vetoable: false` wherever `match`
+ * holds. `required` names every key `match` constrains, because an absent key
+ * satisfies a bare `properties` and would leave the `then` branch dead.
+ * @param {Record<string, unknown>} match
+ * @returns {Record<string, unknown>}
+ */
+function vetoImpossibleWhen(match) {
+  return {
+    if: { required: Object.keys(match), properties: match },
+    then: { properties: { this_call_vetoable: { const: false } } },
+  };
+}
+
+/**
+ * The document describing a normalized {@link Verdict}. Only `decision` is
+ * required; `normalizeVerdict` emits the optional fields only when present.
+ * @returns {Record<string, unknown>}
+ */
+export function verdictSchema() {
+  /** @type {Record<string, unknown>} */
+  const properties = { decision: { enum: Object.values(Decision) } };
+  // Cloned, not aliased. `Object.freeze` on VERDICT_FIELD_SCHEMAS freezes the
+  // outer object only, so assigning the nested `{type, description}` objects
+  // hands every caller the same two levels down: a consumer that tightens
+  // `properties.reason` on the document it was given would silently retighten
+  // every document produced afterwards. The other builders return fresh
+  // structures already.
+  for (const [field, schema] of Object.entries(VERDICT_FIELD_SCHEMAS))
+    properties[field] = structuredClone(schema);
+  return {
+    $schema: JSON_SCHEMA_DIALECT,
+    title: "Verdict",
+    description: `A normalized guardrail decision (${CONTROL_PLANE_SCHEMA}).`,
+    type: "object",
+    required: ["decision"],
+    properties,
+    additionalProperties: false,
+  };
+}
+
+/**
+ * Every generated file, keyed by its package-relative path — the SSOT the
+ * generator writes and the freshness test reads, so neither carries its own
+ * list of filenames. The two `.schema.json` entries are JSON Schema documents;
+ * `tool-input-keys.json` is the data map {@link TOOL_INPUT_KEYS_FILE} describes.
+ * @returns {Record<string, Record<string, unknown>>}
+ */
+export function jsonSchemaDocuments() {
+  return {
+    [`${SCHEMA_DIR}/${SCHEMA_FILES.ToolCallEvent}`]: toolCallEventSchema(),
+    [`${SCHEMA_DIR}/${SCHEMA_FILES.Verdict}`]: verdictSchema(),
+    [`${SCHEMA_DIR}/${TOOL_INPUT_KEYS_FILE}`]: { ...MODELED_TOOL_INPUT_KEYS },
+  };
+}
+
+/**
+ * The bytes a generated file is written as: 2-space JSON with a trailing newline.
+ * This is NOT Prettier's rendering — Prettier collapses a short array onto one
+ * line — so `schema/` is in `.prettierignore` and this function owns the bytes
+ * the freshness test compares. A formatter allowed to rewrite them would red
+ * that test on a change to nothing.
+ * @param {Record<string, unknown>} document
+ * @returns {string}
+ */
+export function serializeSchema(document) {
+  return `${JSON.stringify(document, null, 2)}\n`;
+}

package/src/runtime.mjs

@@ -120,6 +120,24 @@ export function renderHookResponse(
  */
 const RETRY_SLEEP = new Int32Array(new SharedArrayBuffer(4));
 
+/**
+ * Whether a failed `writeSync` is the one recoverable case: EAGAIN, meaning the
+ * non-blocking pipe is momentarily full because the host has not drained it
+ * yet. The caller sleeps 1ms and retries — the same wait a blocking write would
+ * have done in the kernel. Every other errno (EPIPE, EBADF, ...) propagates.
+ *
+ * A non-Error throw is NOT retryable, and is checked separately rather than
+ * left to the `code` comparison: a plain object carrying `code: "EAGAIN"` is
+ * not a write that the kernel asked us to repeat, and retrying one forever is a
+ * hang rather than a short write. Exported so a test can drive every branch —
+ * the real `writeSync` only ever throws an Error.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isRetryableWriteError(err) {
+  return err instanceof Error && /** @type {any} */ (err).code === "EAGAIN";
+}
+
 /**
  * Write `text` to `fd` IN FULL, looping until every byte lands.
  *
@@ -132,24 +150,23 @@ const RETRY_SLEEP = new Int32Array(new SharedArrayBuffer(4));
  * `mutated_input`) was silently truncated and the process still exited 0/2 with
  * a half-written JSON the host cannot parse: an enforced deny degrading to a
  * run. Looping restores the blocking-write semantics the caller assumes.
+ *
+ * Exported so a test can drive the propagation path against a real closed
+ * descriptor; {@link emit} is the only caller a consumer needs.
  * @param {number} fd
  * @param {string} text
  */
-function writeAllSync(fd, text) {
+export function writeAllSync(fd, text) {
   const buf = Buffer.from(text, "utf8");
   let written = 0;
   while (written < buf.length) {
     try {
       written += writeSync(fd, buf, written);
     } catch (err) {
-      // EAGAIN is the one recoverable case: the non-blocking pipe is momentarily
-      // full because the host has not drained it yet. Sleep 1ms and retry — the
-      // same wait a blocking write would have done in the kernel. Every other
-      // errno (EPIPE, EBADF, ...) propagates. There is deliberately no retry cap:
-      // a cap would reintroduce exactly the silent truncation this loop exists to
-      // kill, and a host that never reads would have blocked us forever anyway.
-      if (!(err instanceof Error) || /** @type {any} */ (err).code !== "EAGAIN")
-        throw err;
+      // There is deliberately no retry cap: a cap would reintroduce exactly the
+      // silent truncation this loop exists to kill, and a host that never reads
+      // would have blocked us forever anyway.
+      if (!isRetryableWriteError(err)) throw err;
       Atomics.wait(RETRY_SLEEP, 0, 0, 1);
     }
   }

package/types/adapters/amp.d.mts

@@ -3,6 +3,30 @@
  * @returns {ToolCallEvent}
  */
 export function parse(native: any): ToolCallEvent;
+/**
+ * Totality check: every `decision` in `decisions` must have a row in `table`
+ * and every row both vetoable columns. A decision added to the contract with
+ * no matching row breaks loudly instead of silently defaulting to exit 0.
+ * Called at import against {@link Decision} and {@link EXIT_CODE_BY_DECISION};
+ * exported so a test can drive both branches.
+ * @param {readonly string[]} decisions
+ * @param {Readonly<Record<string, Readonly<Record<string, number>>>>} table
+ */
+export function assertExitCodeTableTotal(decisions: readonly string[], table: Readonly<Record<string, Readonly<Record<string, number>>>>): void;
+/**
+ * Look up the exit code for `decision`/`vetoable` in `table`. Throws instead of
+ * returning `undefined`: the alternative is `exit_code: undefined`, which
+ * `process.exit` renders as 0 — the exact silent allow this table exists to
+ * eliminate. Unreachable from {@link render} on the real
+ * {@link EXIT_CODE_BY_DECISION} while {@link assertExitCodeTableTotal} holds at
+ * load; exported so a test can drive both branches against a synthetic,
+ * deliberately incomplete table.
+ * @param {Readonly<Record<string, Readonly<Record<string, number>>>>} table
+ * @param {string} decision
+ * @param {boolean} vetoable
+ * @returns {number}
+ */
+export function exitCodeFor(table: Readonly<Record<string, Readonly<Record<string, number>>>>, decision: string, vetoable: boolean): number;
 /**
  * Render into Amp's pure exit-code transport: the decision is the exit code,
  * with no stdout body. An ENFORCED deny also carries its `reason` on

package/types/conformance.d.mts

@@ -1,3 +1,13 @@
+/**
+ * A field added to VERDICT_CONTENT_FIELDS with no probe value would be dropped
+ * by normalizeVerdict and then reported as "reaches no native channel" against
+ * every adapter, naming the adapter for the harness's own omission. Called at
+ * import against the live {@link CONTENT_PROBE_VALUES}; exported so a test can
+ * drive both branches.
+ * @param {readonly string[]} fields
+ * @param {Record<string, readonly unknown[]>} values
+ */
+export function assertContentProbeValuesComplete(fields: readonly string[], values: Record<string, readonly unknown[]>): void;
 /**
  * Assert an adapter's {@link import("./control-plane.mjs").Adapter.COVERAGE}
  * hook-coverage matrix is well-formed: it classifies EXACTLY the canonical

package/types/control-plane.d.mts

@@ -279,9 +279,11 @@ export function nativeResponse({ transport, exit_code, enforced, stdout, stderr,
  * Dependency-free on purpose, so a fail-closed hook can import it without
  * dragging in eager config-file reads.
  *
- * VERSIONING — this module IS the frozen contract (its own SSOT, no parallel
- * schema file to drift). Adapters and guardrail consumers are built against it
- * in parallel, so its shapes are stable: {@link EventKind}, {@link Decision},
+ * VERSIONING — this module IS the frozen contract and its own SSOT. The JSON
+ * Schema documents under `schema/` are GENERATED from it by `pnpm gen:schema`
+ * and byte-compared in `json-schema.test.mjs`, so they are output rather than a
+ * second contract; never hand-edit one. Adapters and guardrail consumers are
+ * built against this module in parallel, so its shapes are stable: {@link EventKind}, {@link Decision},
  * {@link MODELED_TOOLS}, and {@link TOOL_ALIASES} are frozen, and
  * {@link SCHEMA_VERSION} / {@link CONTROL_PLANE_SCHEMA} are pinned
  * (control-plane.test.mjs asserts the exact values, so any shape change is a

package/types/json-schema.d.mts

@@ -0,0 +1,77 @@
+/**
+ * Assert every content field the contract models has a schema above. Throws
+ * (fail loud) on the first that does not: `additionalProperties: false` makes an
+ * undeclared field a REJECTION rather than an omission, so a consumer would
+ * refuse a verdict this library produces. Called at import against the live
+ * {@link VERDICT_CONTENT_FIELDS}; exported so a test can drive both branches.
+ * @param {readonly string[]} fields
+ * @param {Record<string, unknown>} declared
+ */
+export function assertVerdictFieldsDeclared(fields: readonly string[], declared: Record<string, unknown>): void;
+/**
+ * The document describing a normalized {@link ToolCallEvent}.
+ *
+ * `additionalProperties: false` is honest here rather than strict: `makeEvent`
+ * builds every event, and the unmodelled remainder of a native payload lands in
+ * `meta.passthrough`, so an extra key at the root is a hand-rolled event, not a
+ * newer library's.
+ * @returns {Record<string, unknown>}
+ */
+export function toolCallEventSchema(): Record<string, unknown>;
+/**
+ * The document describing a normalized {@link Verdict}. Only `decision` is
+ * required; `normalizeVerdict` emits the optional fields only when present.
+ * @returns {Record<string, unknown>}
+ */
+export function verdictSchema(): Record<string, unknown>;
+/**
+ * Every generated file, keyed by its package-relative path — the SSOT the
+ * generator writes and the freshness test reads, so neither carries its own
+ * list of filenames. The two `.schema.json` entries are JSON Schema documents;
+ * `tool-input-keys.json` is the data map {@link TOOL_INPUT_KEYS_FILE} describes.
+ * @returns {Record<string, Record<string, unknown>>}
+ */
+export function jsonSchemaDocuments(): Record<string, Record<string, unknown>>;
+/**
+ * The bytes a generated file is written as: 2-space JSON with a trailing newline.
+ * This is NOT Prettier's rendering — Prettier collapses a short array onto one
+ * line — so `schema/` is in `.prettierignore` and this function owns the bytes
+ * the freshness test compares. A formatter allowed to rewrite them would red
+ * that test on a change to nothing.
+ * @param {Record<string, unknown>} document
+ * @returns {string}
+ */
+export function serializeSchema(document: Record<string, unknown>): string;
+/**
+ * Package-relative directory the generated files live in, versioned by the WIRE
+ * version. A breaking shape change bumps {@link CONTROL_PLANE_SCHEMA} and so
+ * writes a new directory, leaving the previous one in place for a consumer
+ * still on it.
+ *
+ * A document is THIS RELEASE's rendering of that wire version, not a statement
+ * about every release that will carry it. Adding an optional field is
+ * backward-compatible and stays at v1 (see the README's Versioning section), so
+ * the next release's document may carry a property this one does not. That is
+ * why the files ship inside the package: a consumer reads the schema from the
+ * same installed version that produced the event, and the two move together.
+ * Validate against the installed file, never a copy pinned by hand.
+ *
+ * Neither document carries an `$id`. A URL naming a mutable branch would resolve
+ * to whatever the contract says LATER, and two installed versions declaring one
+ * `$id` collide inside a single validator instance. `$ref` here is
+ * document-relative, so nothing needs one.
+ */
+export const SCHEMA_DIR: "schema/control-plane/v1";
+/** Basename of each generated document, keyed by the shape it describes. */
+export const SCHEMA_FILES: Readonly<{
+    ToolCallEvent: "tool-call-event.schema.json";
+    Verdict: "verdict.schema.json";
+}>;
+/**
+ * Basename of the per-tool input-key map, published as plain DATA rather than
+ * inside the event document. A vendor keyword there (`x-modeled-tool-input-keys`)
+ * is legal JSON Schema, but ajv refuses an unknown keyword under its default
+ * options, so the document a JavaScript consumer installed would not compile
+ * until that consumer registered a vocabulary it has no reason to know about.
+ */
+export const TOOL_INPUT_KEYS_FILE: "tool-input-keys.json";

package/types/runtime.d.mts

@@ -36,6 +36,40 @@ export function demoJudge(event: import("./control-plane.mjs").ToolCallEvent): i
  * @returns {import("./control-plane.mjs").NativeResponse}
  */
 export function renderHookResponse(adapter: import("./control-plane.mjs").Adapter, rawInput: string, onFailure: import("./control-plane.mjs").NativeResponse, judge?: (event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict): import("./control-plane.mjs").NativeResponse;
+/**
+ * Whether a failed `writeSync` is the one recoverable case: EAGAIN, meaning the
+ * non-blocking pipe is momentarily full because the host has not drained it
+ * yet. The caller sleeps 1ms and retries — the same wait a blocking write would
+ * have done in the kernel. Every other errno (EPIPE, EBADF, ...) propagates.
+ *
+ * A non-Error throw is NOT retryable, and is checked separately rather than
+ * left to the `code` comparison: a plain object carrying `code: "EAGAIN"` is
+ * not a write that the kernel asked us to repeat, and retrying one forever is a
+ * hang rather than a short write. Exported so a test can drive every branch —
+ * the real `writeSync` only ever throws an Error.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isRetryableWriteError(err: unknown): boolean;
+/**
+ * Write `text` to `fd` IN FULL, looping until every byte lands.
+ *
+ * A single `writeSync` is not enough. When the host captures the hook, fd 1/2 is
+ * a pipe, and libuv puts that pipe in NON-BLOCKING mode the moment anything
+ * initializes `process.stdout`/`process.stderr` (a `console.log` in a judge, the
+ * fail-safe stderr diagnostic in {@link renderHookResponse}). A non-blocking
+ * `write(2)` returns a SHORT COUNT once the kernel pipe buffer fills — measured
+ * at ~143 KiB here — so a deny body larger than that (a long `reason`, a big
+ * `mutated_input`) was silently truncated and the process still exited 0/2 with
+ * a half-written JSON the host cannot parse: an enforced deny degrading to a
+ * run. Looping restores the blocking-write semantics the caller assumes.
+ *
+ * Exported so a test can drive the propagation path against a real closed
+ * descriptor; {@link emit} is the only caller a consumer needs.
+ * @param {number} fd
+ * @param {string} text
+ */
+export function writeAllSync(fd: number, text: string): void;
 /**
  * Emit a {@link NativeResponse} to the host: write the native stdout body when
  * the transport has one, then exit with the transport's exit code.