Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
Rust ai-agentsai-gatewayclaude-codecodexcoding-agentcost-optimizationdeepseekllm-gatewayllm-routerlocal-firstmodel-routingrusttask-routingtauri
#!/usr/bin/env python3
"""Reject unregistered contract versions and legacy leakage into current paths."""
import argparse
import json
import re
import subprocess
import sys
from pathlib import Path
REGISTRY_PATH = Path("contracts/compatibility-support.v1.json")
# Storage owns the production declaration and startup support policy. A schema change
# must deliberately update this gate after reviewing migrations/startup_format.rs and
# docs/upgrade-storage-design.md; fixtures cannot satisfy it. This is not a migration test.
DATABASE_SCHEMA_SOURCE = "crates/local-storage/src/migrations/mod.rs"
EXPECTED_DATABASE_SCHEMA_VERSION = 31
VERSION_SUFFIX = re.compile(r"/v[0-9]+")
INTERNAL_CONTRACT = re.compile(r"hiroute(?:\.[a-z0-9][a-z0-9-]*)+/v[0-9]+")
VALID_MODES = {
"projection",
"frozen_fixture",
"recovery_read_only",
"legacy_adapter",
"rejection_fixture",
}
OBSOLETE_LIVE_CONTRACT_FILES = {
"contracts/cli/local-control-hello.v1.schema.json",
"contracts/cli/local-control.v1.schema.json",
"contracts/cli/machine-envelope.v1.schema.json",
"crates/application-api/src/routing_control.rs",
}
OBSOLETE_LIVE_RUST_FRAGMENTS = {
"crates/domain/src/routing/materialized.rs": {
"pub fn new(body: CompiledAgentPlanBodyV1",
},
"crates/domain/src/operation/routing.rs": {
"pub struct RoutingTransactionIntentV1",
"pub fn from_routing_planner",
},
}
def path_allowed(path, allowed):
return any(
path.startswith(value) if value.endswith("/") else path == value
for value in allowed
)
def repository_files(root):
output = subprocess.check_output(
["git", "ls-files", "-co", "--exclude-standard", "-z"], cwd=root
)
excluded = {str(REGISTRY_PATH), "scripts/check-contract-convergence.py"}
return sorted(
path for path in output.decode().split("\0") if path and path not in excluded
)
def load_text(root, path):
try:
return (root / path).read_text()
except (UnicodeDecodeError, OSError):
return ""
def historical_release_snapshot(path, source):
# These files describe released producers, never current readers/writers or test
# fixtures. Their full index, digest and Git-source validation belongs to
# release-contracts.py check. Do not exempt code, arbitrary JSON or other paths.
active = re.fullmatch(r"contracts/releases/v[0-9][0-9A-Za-z.+-]*\.json", path)
semver = r"v(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?"
archived = re.fullmatch(rf"contracts/releases/archive/({semver})\.([0-9a-f]{{40}})\.json", path)
if not active and not archived:
return False
try:
value = json.loads(source)
except ValueError:
return False
if not isinstance(value, dict) or value.get("schema") != "hiroute.release-contract-snapshot/v1":
return False
if archived:
release = value.get("release")
return (isinstance(release, dict) and release.get("tag") == archived[1]
and release.get("revision") == archived[2])
return True
def production_source_path(path):
"""Select shipped/internal Rust sources, not tests, fixtures, docs, or third-party data."""
value = Path(path)
if value.suffix != ".rs":
return False
parts = value.parts
if not parts:
return False
if parts[0] == "apps":
selected = "src" in parts
elif parts[0] == "crates":
selected = "src" in parts
elif parts[:2] == ("tools", "release-facts"):
selected = "src" in parts
else:
return False
if not selected or "tests" in parts or "test_control" in parts:
return False
name = value.name.lower()
return not (
name == "tests.rs"
or name.endswith("_tests.rs")
or name.startswith("test_")
or "fixture" in name
)
def without_cfg_test_items(source):
"""Remove items with a directly required positive `test` condition.
This deliberately leaves production code appearing after a test module in the scan. Braces in
Rust strings and macros are balanced in the formatted sources; the checker has regression tests
for both inline rejection tests and a production declaration appended after them.
"""
output = []
pending = False
depth = 0
# Conservative: unknown/nested cfg expressions remain in the production audit.
# In particular not(test) and any(test, feature = ...) are production-capable.
cfg_test = re.compile(
r"#\s*\[\s*cfg\s*\(\s*(?:test\s*|all\(\s*test\s*(?:,[^\]]*)?\))\s*\)\s*\]"
)
for line in source.splitlines(keepends=True):
if depth:
depth += line.count("{") - line.count("}")
if depth <= 0:
depth = 0
continue
if pending:
stripped = line.strip()
if not stripped or stripped.startswith("#["):
continue
item_depth = line.count("{") - line.count("}")
if item_depth > 0:
depth = item_depth
pending = False
continue
if cfg_test.search(line):
pending = True
continue
output.append(line)
return "".join(output)
def schema_source_tokens(source):
"""Lex only enough Rust to distinguish this gate's declaration from text.
This is not a Rust parser or a cfg evaluator. Literals stay opaque, nested
comments are skipped, and malformed lexical input fails closed.
"""
raw_string = re.compile(r'(?:b|c)?r(#{0,255})"')
quoted_string = re.compile(r'(?:b|c)?"(?:\\[\s\S]|[^"\\])*"')
character = re.compile(r"(?:b)?'(?:\\(?:u\{[0-9a-fA-F_]+\}|x[0-9a-fA-F]{2}|[^\n])|[^'\\\n])'")
token = re.compile(r"[A-Za-z_]\w*|[0-9][0-9_]*|.")
position = 0
while position < len(source):
if source[position].isspace():
position += 1
elif source.startswith("//", position):
end = source.find("\n", position)
position = len(source) if end < 0 else end
elif source.startswith("/*", position):
depth = 1
position += 2
while depth and position < len(source):
if source.startswith("/*", position):
depth += 1
position += 2
elif source.startswith("*/", position):
depth -= 1
position += 2
else:
position += 1
if depth:
raise ValueError("unterminated block comment")
elif match := raw_string.match(source, position):
ending = '"' + match[1]
end = source.find(ending, match.end())
if end < 0:
raise ValueError("unterminated raw string")
position = end + len(ending)
yield "<literal>"
elif source.startswith(('"', 'b"', 'c"'), position):
match = quoted_string.match(source, position)
if not match:
raise ValueError("unterminated string")
position = match.end()
yield "<literal>"
elif match := character.match(source, position):
position = match.end()
yield "<literal>"
else:
match = token.match(source, position)
position = match.end()
yield match[0]
def database_schema_declarations(source):
# Positive allowlist: one plain, unattributed module-level const. Do not infer
# production availability from arbitrary cfg/cfg_attr expressions or macros.
versions = []
item = []
stack = []
pairs = {"(": ")", "[": "]", "{": "}"}
declaration = re.compile(r"pub const LATEST_SCHEMA_VERSION : u32 = ([0-9][0-9_]*) ;")
for token in schema_source_tokens(source):
if not stack:
item.append(token)
if item[-2:] == ["#", "!"]:
raise ValueError("inner attributes require an explicit schema gate review")
if token in pairs:
stack.append(pairs[token])
elif token in pairs.values():
if not stack or stack.pop() != token:
raise ValueError("unbalanced delimiters")
if not stack and token in {";", "}"}:
if any(item[index:index + 2] == ["const", "LATEST_SCHEMA_VERSION"]
for index in range(len(item) - 1)):
match = declaration.fullmatch(" ".join(item))
versions.append(match[1] if match else None)
item = []
if stack:
raise ValueError("unclosed delimiter")
return versions
def audit_database_schema(root):
try:
versions = database_schema_declarations(load_text(root, DATABASE_SCHEMA_SOURCE))
except ValueError as error:
return [f"database schema: {DATABASE_SCHEMA_SOURCE}: {error}"]
if len(versions) != 1 or versions[0] is None:
return [f"database schema: {DATABASE_SCHEMA_SOURCE} must contain exactly one unconditional, unattributed top-level LATEST_SCHEMA_VERSION declaration"]
version = int(versions[0].replace("_", ""))
if version != EXPECTED_DATABASE_SCHEMA_VERSION:
return [f"database schema: {DATABASE_SCHEMA_SOURCE} declares V{version}; current storage requires V{EXPECTED_DATABASE_SCHEMA_VERSION} (storage owner must review schema and startup support policy together)"]
return []
def discover_production_contracts(texts):
occurrences = {}
for path, source in texts.items():
if not production_source_path(path):
continue
for contract in INTERNAL_CONTRACT.findall(without_cfg_test_items(source)):
occurrences.setdefault(contract, set()).add(path)
return occurrences
def validate_registry(registry):
errors = []
if registry.get("schema") != "hiroute.contract-compatibility-support/v1":
errors.append("registry schema is invalid")
subjects = registry.get("subjects")
if not isinstance(subjects, list) or not subjects:
return [*errors, "registry subjects are missing"]
names = set()
legacy_contracts = set()
production_contracts = registry.get("production_contracts")
if (
not isinstance(production_contracts, list)
or not production_contracts
or production_contracts != sorted(set(production_contracts))
or any(
not isinstance(contract, str)
or INTERNAL_CONTRACT.fullmatch(contract) is None
for contract in production_contracts
)
):
errors.append("production_contracts must be a sorted unique internal contract list")
for subject in subjects:
name = subject.get("subject")
if not isinstance(name, str) or not name or name in names:
errors.append(f"invalid or duplicate subject: {name!r}")
continue
names.add(name)
prefixes = subject.get("audited_prefixes")
currents = subject.get("current_contracts")
supports = subject.get("legacy_support")
if not all(isinstance(value, list) and value for value in (prefixes, currents)):
errors.append(f"{name}: audited prefixes and current contracts must be non-empty")
if not isinstance(supports, list):
errors.append(f"{name}: legacy_support must be a list")
continue
for support in supports:
contract = support.get("contract")
required = ("owner", "reason", "removal_condition")
if not isinstance(contract, str) or not VERSION_SUFFIX.search(contract):
errors.append(f"{name}: invalid legacy contract {contract!r}")
elif contract in legacy_contracts:
errors.append(f"duplicate legacy contract: {contract}")
else:
legacy_contracts.add(contract)
if support.get("mode") not in VALID_MODES:
errors.append(f"{name}: invalid support mode for {contract}")
if any(
not isinstance(support.get(field), str) or not support[field].strip()
for field in required
):
errors.append(f"{name}: {contract} lacks owner, reason, or removal condition")
paths = support.get("allowed_paths")
if not isinstance(paths, list) or not paths or any(
not isinstance(path, str)
or path.startswith(("/", "."))
or ".." in path
for path in paths
):
errors.append(f"{name}: {contract} has invalid allowed paths")
forbidden = registry.get("forbidden_contracts")
if not isinstance(forbidden, list) or any(
not isinstance(value, str) for value in forbidden
):
errors.append("forbidden_contracts must be a string list")
return errors
def audit(root, registry, paths=None):
errors = validate_registry(registry)
if errors:
return errors
paths = repository_files(root) if paths is None else sorted(paths)
for path in sorted(OBSOLETE_LIVE_CONTRACT_FILES):
if (root / path).is_file():
errors.append(f"obsolete live contract file reintroduced: {path}")
texts = {path: load_text(root, path) for path in paths}
texts = {path: source for path, source in texts.items()
if not historical_release_snapshot(path, source)}
production = discover_production_contracts(texts)
declared_production = set(registry["production_contracts"])
for contract in sorted(set(production) - declared_production):
locations = ", ".join(sorted(production[contract]))
errors.append(f"undeclared production contract {contract}: {locations}")
for contract in sorted(declared_production - set(production)):
errors.append(f"stale production contract declaration: {contract}")
for path, fragments in OBSOLETE_LIVE_RUST_FRAGMENTS.items():
value = texts.get(path, "")
for fragment in fragments:
if fragment in value:
errors.append(
f"obsolete live contract producer reintroduced in {path}: {fragment}"
)
rejection_paths = registry.get("rejection_paths", [])
all_current = set()
all_legacy = {}
for subject in registry["subjects"]:
currents = set(subject["current_contracts"])
all_current.update(currents)
for support in subject["legacy_support"]:
all_legacy[support["contract"]] = support
known = currents | {
support["contract"] for support in subject["legacy_support"]
}
for prefix in subject["audited_prefixes"]:
pattern = re.compile(re.escape(prefix) + r"/v[0-9]+")
for path, value in texts.items():
for contract in pattern.findall(value):
if contract not in known and not path_allowed(path, rejection_paths):
errors.append(
f"{path}: unregistered {subject['subject']} contract {contract}"
)
for contract in sorted(all_current):
if not any(contract in value for value in texts.values()):
errors.append(f"current contract is not implemented: {contract}")
production_by_family = {}
for contract in production:
family = contract.rsplit("/v", 1)[0]
production_by_family.setdefault(family, set()).add(contract)
for family, contracts in sorted(production_by_family.items()):
if len(contracts) < 2:
continue
classified = any(
family in subject["audited_prefixes"]
and contracts.issubset(
set(subject["current_contracts"])
| {
support["contract"]
for support in subject["legacy_support"]
}
)
for subject in registry["subjects"]
)
if not classified:
errors.append(
"unclassified production multi-version family "
f"{family}: {', '.join(sorted(contracts))}"
)
for contract, support in sorted(all_legacy.items()):
occurrences = [path for path, value in texts.items() if contract in value]
if not occurrences:
errors.append(f"stale compatibility registration has no occurrence: {contract}")
for path in occurrences:
if not path_allowed(path, support["allowed_paths"]):
errors.append(
f"{path}: legacy contract escapes registered support: {contract}"
)
for contract in registry["forbidden_contracts"]:
for path, value in texts.items():
if contract in value:
errors.append(f"{path}: forbidden contract reintroduced: {contract}")
joined = "\n".join(texts.values())
errors.extend(audit_database_schema(root))
if "control-v1.sock" in joined:
errors.append("legacy Local Control socket name reintroduced")
return sorted(set(errors))
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[1])
arguments = parser.parse_args()
root = arguments.root.resolve()
registry = json.loads((root / REGISTRY_PATH).read_text())
errors = audit(root, registry)
if errors:
for error in errors:
print(f"contract-convergence: {error}", file=sys.stderr)
return 1
supports = sum(
len(subject["legacy_support"]) for subject in registry["subjects"]
)
print(
json.dumps(
{
"state": "green",
"subjects": len(registry["subjects"]),
"legacy_supports": supports,
}
)
)
return 0
if __name__ == "__main__":
raise SystemExit(main())