feat(router)!: add a versioned JSON Schema for routing tables at version 1 by rabeckett · Pull Request #10129 · github/gh-aw-firewall

rabeckett · 2026-10-16T18:25:40Z

Summary

The router's routing tables are an input contract, like its HTTP API, but their format was
defined only by TableDocument and RoutingTable.from_bytes in routing_table.py and the enums
in contracts.py. This PR adds a hand-written, versioned JSON Schema for the table files, and
tests that keep the schema, the loader and the bundled tables in step. It mirrors what
openapi.yaml and tests/test_openapi.py already do for the HTTP API.

All changes are in containers/router/.

Changes

Schema. New file schemas/routing-table.v1.schema.json, a JSON Schema (draft 2020-12).
It encodes everything a schema can express:
- closed objects;
- schema_version required and fixed to 1;
- the fixed profile goals and modes, excluding auto;
- a canonical repository;
- label-key and provider/model[:effort] patterns built from the enums;
- non-empty, unique arrays.
Patterns use only syntax that ECMA-262, Python re and RE2 share: no \s or other escapes,
and no lookaround. Whitespace is the explicit set of characters the loader strips, and a
trimmed definition rejects leading and trailing whitespace.

Its description lists the cross-reference rules only the loader enforces. The file is kept
out of routing/ (the loader reads every *.json there), out of the image and out of the wheel.
Format marker reset to 1. The schema is the first published version of the format, so the
marker moves from 5 to 1 in:
- the loader;
- the six bundled tables (only the schema_version line changes);
- the synthetic fixtures and the contract archive manifest (now derived from the loader);
- the table sentence in openapi.yaml.
The loader now also rejects a boolean schema_version, because Literal[1] accepts JSON
true (True == 1). The new agreement test caught this.
Tests. New file tests/test_table_schema.py:
- the schema is a valid draft 2020-12 schema;
- all bundled, synthetic and contract-corpus tables conform;
- parity with the runtime: version, profiles, patterns (including the whitespace set) and
  object fields;
- patterns use only portable syntax, and the schema and the loader agree on leading and
  trailing whitespace for every character the loader strips;
- the schema and the loader reject the same single-field defects;
- the boundary is explicit: the schema accepts cross-reference violations that the loader
  rejects, and rejects a missing schema_version that the loader defaults;
- published schema files are frozen by a SHA-256 pin.
test_routing.py now checks that versions 0 and 2–5 are rejected.
Packaging. schemas/** is added to the source distribution and to the release-test fixture.
Docs. The router README describes the schema and the versioning policy: a published schema
never changes, and a format change adds routing-table.v<N+1>.schema.json and bumps
schema_version.

Compatibility

This is a breaking change to the table format marker only. The router now rejects tables with
schema_version 5, so such tables must be regenerated with 1. Table content, routing behaviour
and the HTTP API don't change. There's no router version bump; the next router release picks
this up.

Validation

Router suite: 545 passed. ruff check, ruff format --check and ty check are clean.
Source distribution: built it, confirmed it contains the schema, and ran the schema and routing
tests from the extracted tree.
Mutation checks, made by hand and reverted:
- renaming a TaskComplexity value fails the pattern parity and conformance tests;
- adding a field to TableDocument fails the field parity test;
- editing the schema file fails the hash pin.
Portability: ran the schema patterns under an ECMAScript engine against the loader's results
for every whitespace character in leading, trailing and pre-effort positions. The schema
matches the loader in every case.

…ion 1 Routing tables are the router's second input contract, but their format was defined only by routing_table.py and contracts.py. Add a hand-written draft 2020-12 schema at containers/router/schemas/routing-table.v1.schema.json, frozen once published, so the table format is an explicit, versioned contract. Start the published numbering at 1: the loader, bundled tables, synthetic fixtures and openapi.yaml move from schema_version 5 to 1. The loader now also rejects a boolean schema_version, which Literal[1] would otherwise accept because True == 1. tests/test_table_schema.py checks that: - the schema is valid and every bundled, synthetic and contract-corpus table conforms; - its version, profiles, label-key and model-identity patterns and closed objects match the runtime models and enums; - the schema and RoutingTable.from_bytes reject the same single-field defects, and the cross-reference rules that only the loader enforces stay documented in the schema; - published schema files keep their pinned SHA-256. Include schemas/ in the source distribution and document the schema and its versioning policy in the router README. BREAKING CHANGE: the router accepts only routing tables with schema_version 1. Tables with schema_version 5 are rejected and must be regenerated with the new version. Closes #10124 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-10-16T18:31:55Z

✅ Coverage Check Passed

Overall Coverage

Metric	Base	PR	Delta
Lines	93.46%	93.47%	📈 +0.01%
Statements	92.09%	92.10%	➡️ +0.01%
Functions	90.91%	90.91%	➡️ +0.00%
Branches	86.06%	86.07%	➡️ +0.01%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
`src/routing/bootstrap.ts`	85.3% → 85.3% (+0.08%)	79.8% → 80.0% (+0.20%)
`src/log-directory-setup.ts`	96.8% → 100.0% (+3.18%)	96.9% → 100.0% (+3.13%)

Coverage comparison generated by scripts/ci/compare-coverage.ts

Copilot

🟡 Changes recommended

Exported archive metadata and cross-engine whitespace validation still disagree with the table contract.

2 open findings

What changed in this PR

Introduces a versioned JSON Schema for the router’s offline table format, complementing its HTTP API contract.

Changes:

Adds schema validation, runtime-parity tests, and immutability checks.
Resets table markers to version 1 and rejects boolean versions.
Includes schemas in source distributions and documents versioning.

File	Description
`containers/router/tests/test_table_schema.py`	Adds schema and loader-parity tests.
`containers/router/tests/test_routing.py`	Checks rejection of unsupported versions.
`containers/router/tests/test_package.py`	Checks schema inclusion in source distributions.
`containers/router/tests/contract_corpus.py`	Updates generated tables to version 1.
`containers/router/src/gh_aw_router/routing_table.py`	Enforces version 1 and rejects booleans.
`containers/router/schemas/routing-table.v1.schema.json`	Defines the version 1 contract.
`containers/router/routing/cost-speed-robust.json`	Updates format marker to 1.
`containers/router/routing/cost-speed-economy.json`	Updates format marker to 1.
`containers/router/routing/cost-speed-balanced.json`	Updates format marker to 1.
`containers/router/routing/cost-robust.json`	Updates format marker to 1.
`containers/router/routing/cost-economy.json`	Updates format marker to 1.
`containers/router/routing/cost-balanced.json`	Updates format marker to 1.
`containers/router/README.md`	Documents schema and versioning policy.
`containers/router/pyproject.toml`	Includes schemas in source distributions.
`containers/router/openapi.yaml`	Updates the table-version description only.

🧠 Review effort: Max

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Replace \s and lookarounds in the routing-table schema with an explicit list of the whitespace characters the loader strips, plus a trimmed definition that rejects outer whitespace. ECMA-262, Python re and RE2 validators now agree with the loader. Derive the contract archive's routing_table_schema from the loader instead of hard-coding it, and check that every embedded table matches. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-10-16T19:18:18Z

✅ Copilot review passed with no inline comments.

@rabeckett Add the ready-for-aw label to this PR to trigger agentic CI smoke tests.

github-actions · 2026-10-16T19:41:06Z

✅ Smoke Claude passed

Generated by Smoke Claude for #10129

github-actions · 2026-10-16T19:41:08Z

✅ Build Test Suite completed successfully!

Generated by Build Test Suite for #10129

github-actions · 2026-10-16T19:41:08Z

📡 Smoke OTel Tracing completed. All tracing scenarios validated. ✅

📡 OTel tracing validated by Smoke OTel Tracing

github-actions · 2026-10-16T19:41:09Z

Chroot tests passed! Smoke Chroot - All security and functionality tests succeeded.

Tested by Smoke Chroot

github-actions · 2026-10-16T19:41:09Z

📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤

📰 BREAKING: Report filed by Smoke Copilot

github-actions · 2026-10-16T19:41:09Z

💎 Smoke Gemini is crystallizing results on this pull request...

github-actions · 2026-10-16T19:41:10Z

Smoke Cloud Hypervisor completed. Cloud Hypervisor + Copilot passed.

Cloud Hypervisor + Copilot smoke test by Smoke Cloud Hypervisor

github-actions · 2026-10-16T19:41:11Z

🛡️ Smoke Copilot Network Isolation confirmed the egress allowlist is enforced. ✅

🛡️ Egress verdict from Smoke Copilot Network Isolation

github-actions · 2026-10-16T19:41:12Z

✅ Smoke Copilot BYOK completed. Copilot BYOK mode operational. 🔓

🔑 BYOK report filed by Smoke Copilot BYOK

github-actions · 2026-10-16T19:41:13Z

✅ Security Guard completed successfully!

Security Guard

Outcome: reported_no_action

The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

Generated from Security Guard · haiku45 · 5.1 AIC · ⊞ 6.0K · ◷

Generated by Security Guard for #10129

github-actions · 2026-10-16T19:41:16Z

✨ The prophecy is fulfilled... Smoke Codex has completed its mystical journey. The stars align. 🌟

🔮 The oracle has spoken through Smoke Codex

github-actions · 2026-10-16T19:41:19Z

🔌 Smoke Services — All services reachable! ✅

🔌 Service connectivity validated by Smoke Services

github-actions · 2026-10-16T19:41:23Z

🔑 Smoke Copilot BYOK AOAI (api-key) is testing Azure OpenAI BYOK (api-key) mode on this pull request...

github-actions · 2026-10-16T19:41:43Z

🪪 Smoke Copilot BYOK AOAI (Entra) is testing Azure OpenAI BYOK (Entra / GitHub OIDC) mode on this pull request...

github-actions · 2026-10-16T19:50:42Z

Cloud Hypervisor + Copilot smoke test

Merged PR lookup: PASS
github.com connectivity: PASS (HTTP 200)
File write/read: PASS
example.com blocked: PASS (HTTP 000)
Overall: PASS

Cloud Hypervisor + Copilot smoke test by Smoke Cloud Hypervisor
_{Add label ready-for-aw to run again}

github-actions · 2026-10-16T19:51:11Z

Smoke Test: Claude Engine Validation

Check	Status
API	✅ PASS
gh CLI	✅ PASS
File access	✅ PASS

Overall result: ✅ PASS

Generated by Smoke Claude for #10129 · claude · haiku45 · 49 AIC · ⊞ 6.1K · ◷
_{Add label ready-for-aw to run again}

github-actions · 2026-10-16T19:51:11Z

EGRESS_RESULT allow=pass deny=pass

✅ Allowed domain: api.github.com reachable (HTTP 403 status returned, curl exit 0)
✅ Blocked domain: example.com blocked (TLS/proxy denial)
Overall: PASS (PR author could not be resolved due to the integrity filter)

🛡️ Egress verdict from Smoke Copilot Network Isolation
_{Add label ready-for-aw to run again}

github-actions · 2026-10-16T19:51:24Z

Smoke Copilot: PASS ✅

MCP (PR: "chore: pin enclave smoke to AWF v0.28.61"): ✅
github.com HTTP 200: ✅
File write/read: ✅
cc @rabeckett

📰 BREAKING: Report filed by Smoke Copilot
_{Add label ready-for-aw to run again}

github-actions · 2026-10-16T19:51:32Z

Smoke services: ✅ Redis PONG · ✅ pg_isready · ✅ SELECT 1 → PASS

🔌 Service connectivity validated by Smoke Services
_{Add label ready-for-aw to run again}

github-actions · 2026-10-16T19:51:35Z

Copilot BYOK Smoke Test ✅ PASS

Test	Result
GitHub.com connectivity	✅ HTTP 200
File write/read	✅ File verified
Pre-fetched PR data	✅ 2 merged PRs confirmed
BYOK inference path	✅ Direct mode active

Mode: Direct BYOK (COPILOT_PROVIDER_API_KEY via api-proxy sidecar → api.githubcopilot.com)

All smoke tests passed.

🔑 BYOK report filed by Smoke Copilot BYOK
_{Add label ready-for-aw to run again}

github-actions · 2026-10-16T19:51:53Z

OTEL smoke test

✅ S1: otel.js loads and exports its functions.
✅ S2: otel.test.js passed 39/39.
✅ S3: Trace context vars are forwarded by env-passthrough.ts and the OTEL vars by api-proxy-env-config.ts.
✅ S4: The onUsage hook exists in token-tracker-http.js.
✅ S5: /tmp/gh-aw/otel.jsonl exists; I did not check whether it holds exported spans.

📡 OTel tracing validated by Smoke OTel Tracing
_{Add label ready-for-aw to run again}

github-actions · 2026-10-16T19:52:40Z

🏗️ Build Test Suite Results

Ecosystem	Project	Build/Install	Tests	Status
Bun	elysia	✅	1/1 passed	✅ PASS
Bun	hono	✅	1/1 passed	✅ PASS
C++	fmt	✅	N/A	✅ PASS
C++	json	✅	N/A	✅ PASS
Deno	oak	N/A	1/1 passed	✅ PASS
Deno	std	N/A	1/1 passed	✅ PASS
.NET	hello-world	✅	N/A	✅ PASS
.NET	json-parse	✅	N/A	✅ PASS
Go	color	✅	pass	✅ PASS
Go	env	✅	pass	✅ PASS
Go	uuid	✅	pass	✅ PASS
Java	gson	✅	1/1 passed	✅ PASS
Java	caffeine	✅	1/1 passed	✅ PASS
Node.js	clsx	✅	pass	✅ PASS
Node.js	execa	✅	pass	✅ PASS
Node.js	p-limit	✅	pass	✅ PASS
Rust	fd	✅	1/1 passed	✅ PASS
Rust	zoxide	✅	1/1 passed	✅ PASS

Overall: 8/8 ecosystems passed — PASS

Notes: Bun/Deno were installed via npm (the curl installers were not permitted in this sandbox). .NET and Maven needed writable temp/cache dirs under /tmp/gh-aw/agent.

Generated by Build Test Suite for #10129 · copilot · auto · 29.9 AIC · ⊞ 12K · ◷
_{Add label ready-for-aw to run again}

github-actions · 2026-10-16T19:53:18Z

Smoke test results:

PRs reviewed: chore: pin enclave smoke to AWF v0.28.61 ✅
PRs reviewed: Sanitize Cloud Hypervisor smoke harness failure output ✅
PR detail fetch: ✅
Playwright github.com title check: ❌
Temp file write/read: ✅
AWF build (npm ci && npm run build): ✅
Overall status: FAIL

🔮 The oracle has spoken through Smoke Codex
_{Add label ready-for-aw to run again}

github-actions · 2026-10-16T19:53:52Z

Chroot version comparison

Runtime	Host Version	Chroot Version	Match?
Python	Python 3.12.15	Python 3.12.15	✅
Node.js	v24.21.0	v2.98.0	❌
Go	go1.22.12	go1.22.12	✅

Node.js differs, so not all tests passed and the smoke-chroot label was not added. The chroot reports v2.98.0, which does not look like a Node.js version string. That suggests the output was captured from something other than the real node binary.

Tested by Smoke Chroot
_{Add label ready-for-aw to run again}

rabeckett requested review from SivaKesava1 and lpcox as code owners October 16, 2026 18:25

Copilot AI max review requested due to automatic review settings October 16, 2026 18:25

Copilot started reviewing on behalf of rabeckett October 16, 2026 18:26

View session

Copilot AI reviewed Oct 16, 2026

View reviewed changes

Comment thread containers/router/schemas/routing-table.v1.schema.json Outdated

Comment thread containers/router/tests/contract_corpus.py Outdated

rabeckett added the ready-for-aw label Oct 16, 2026

rabeckett had a problem deploying to aoai-model October 16, 2026 19:41 — with GitHub Actions Failure

github-actions Bot added smoke-copilot-network-isolation Copilot network-isolation egress smoke test smoke-claude labels Oct 16, 2026

github-actions Bot added the smoke-copilot label Oct 16, 2026

github-actions Bot added the smoke-services label Oct 16, 2026

github-actions Bot added the smoke-copilot-byok label Oct 16, 2026

rabeckett deployed to aoai-model October 16, 2026 19:52 — with GitHub Actions Active

rabeckett had a problem deploying to aoai-model October 16, 2026 19:52 — with GitHub Actions Failure

github-actions Bot added the build-test label Oct 16, 2026

github-actions Bot added the smoke-codex label Oct 16, 2026

rabeckett merged commit c35be39 into main Oct 16, 2026
138 of 146 checks passed

rabeckett deleted the rabeckett-routing-table-schema branch October 16, 2026 20:02

lpcox mentioned this pull request Oct 17, 2026

Bump gh-aw-firewall to v0.28.62 github/gh-aw#69525

Closed

6 tasks

Copilot AI mentioned this pull request Oct 17, 2026

Bump gh-aw-firewall default to v0.28.62 github/gh-aw#69526

Merged

Conversation

rabeckett commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Compatibility

Validation

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Coverage Check Passed

Overall Coverage

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Security Guard

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026

Uh oh!

github-actions Bot commented Oct 16, 2026

Uh oh!

github-actions Bot commented Oct 16, 2026

Uh oh!

github-actions Bot commented Oct 16, 2026

Smoke Test: Claude Engine Validation

Uh oh!

github-actions Bot commented Oct 16, 2026

Uh oh!

github-actions Bot commented Oct 16, 2026

Uh oh!

github-actions Bot commented Oct 16, 2026

Uh oh!

github-actions Bot commented Oct 16, 2026

Copilot BYOK Smoke Test ✅ PASS

Uh oh!

github-actions Bot commented Oct 16, 2026

Uh oh!

github-actions Bot commented Oct 16, 2026

🏗️ Build Test Suite Results

Uh oh!

rabeckett commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading