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
"""Freeze published contract inventories; never infer migration support from a release label."""
import argparse
from datetime import datetime
import hashlib
import json
import os
from pathlib import Path
import re
import subprocess
import tempfile
SNAPSHOT_SCHEMA = "hiroute.release-contract-snapshot/v1"
INDEX_SCHEMA = "hiroute.release-contract-index/v1"
INDEX = "index.v1.json"
TAG = re.compile(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.-]+)?")
SHA = re.compile(r"[0-9a-f]{40}")
HASH = re.compile(r"[0-9a-f]{64}")
SOURCES = {
"compatibility_register": "contracts/compatibility-support.v1.json",
"cli_contract_set": "contracts/cli/contract-set.v1.json",
}
STORAGE_SOURCE = "crates/local-storage/src/migrations/mod.rs"
def require(condition, message):
if not condition:
raise ValueError(message)
def encoded(value):
return (json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True) + "\n").encode()
def digest(value):
return hashlib.sha256(value).hexdigest()
def git(repo, *args):
return subprocess.check_output(["git", "-C", str(repo), *args], stderr=subprocess.PIPE)
def version(tag):
match = TAG.fullmatch(tag)
require(match is not None, "invalid release tag")
return tuple(int(part) for part in match.groups())
def create_snapshot(repo, release, manifest, revision, repository):
tag = release["tagName"]
version(tag)
require(re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repository), "invalid repository")
require(SHA.fullmatch(revision), "source revision must be an exact commit SHA")
require(release.get("isDraft") is False, "draft is not a published baseline")
require(isinstance(release.get("isPrerelease"), bool), "missing release channel")
published = release.get("publishedAt")
require(isinstance(published, str) and published.endswith("Z"), "missing publication time")
datetime.fromisoformat(published.replace("Z", "+00:00"))
resolved = git(repo, "rev-parse", "--verify", f"refs/tags/{tag}^{{commit}}").decode().strip()
require(resolved == revision, "tag differs from the verified package source")
channel = "preview" if release["isPrerelease"] else "stable"
require(channel != "stable" or "-" not in tag, "prerelease tag cannot advance stable baseline")
require(manifest.get("schema") in {"hiroute.website.releases/v2", "hiroute.website.releases/v3"}, "unknown release manifest")
records = [item for item in manifest["releases"] if item["version"] == tag[1:]]
require(len(records) == 1, "release manifest must contain exactly one matching version")
record = records[0]
require(record["channel"] == channel, "publication channel differs from manifest")
actual = {asset["name"]: asset for asset in release["assets"]}
require(len(actual) == len(release["assets"]), "duplicate published asset")
artifacts = []
for artifact in record["artifacts"]:
names = [(artifact["filename"], artifact["sha256"], artifact["size"])]
if artifact["kind"] == "standalone":
names.append((artifact["manifest_filename"], artifact["manifest_sha256"], artifact["manifest_size"]))
require(f"-{revision[:12]}-" in artifact["filename"], "artifact source differs from tag")
for filename, sha256, size in names:
require(Path(filename).name == filename and filename not in (".", ".."), "invalid asset name")
require(HASH.fullmatch(sha256), "invalid artifact digest")
asset = actual.get(filename, {})
require(type(size) is int and size > 0 and asset.get("size") == size, "published asset missing or size mismatch")
require(asset.get("digest") == "sha256:" + sha256, "published asset digest differs from verified manifest")
artifacts.append({"filename": filename, "sha256": sha256, "size": size})
require(artifacts and len({a["filename"] for a in artifacts}) == len(artifacts), "empty or duplicate manifest assets")
storage = git(repo, "show", f"{revision}:{STORAGE_SOURCE}")
versions = re.findall(rb"pub const LATEST_SCHEMA_VERSION:\s*u32\s*=\s*([0-9]+);", storage)
require(len(versions) == 1, "cannot identify released SQL schema")
contracts = {}
for key, path in SOURCES.items():
raw = git(repo, "show", f"{revision}:{path}")
contracts[key] = {"path": path, "sha256": digest(raw), "content": json.loads(raw)}
return {
"schema": SNAPSHOT_SCHEMA,
"release": {"repository": repository, "tag": tag, "revision": revision,
"channel": channel, "published_at": published,
"artifacts": sorted(artifacts, key=lambda a: a["filename"])},
"storage": {"sql_schema_version": int(versions[0]), "source_path": STORAGE_SOURCE,
"source_sha256": digest(storage)},
"contracts": contracts,
}
def validate_snapshot(snapshot, filename):
require(snapshot.get("schema") == SNAPSHOT_SCHEMA, "unknown snapshot schema")
release = snapshot["release"]
version(release["tag"])
require(filename == release["tag"] + ".json", "snapshot filename/tag mismatch")
require(SHA.fullmatch(release["revision"]), "invalid recorded revision")
require(release["channel"] in ("stable", "preview"), "unknown channel")
require(release["channel"] != "stable" or "-" not in release["tag"], "preview in stable ledger")
require(re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", release["repository"]), "invalid recorded repository")
published = release["published_at"]
require(isinstance(published, str) and published.endswith("Z"), "invalid recorded publication time")
datetime.fromisoformat(published.replace("Z", "+00:00"))
artifacts = release["artifacts"]
require(isinstance(artifacts, list) and artifacts, "missing recorded artifacts")
names = []
for artifact in artifacts:
name = artifact["filename"]
require(isinstance(name, str) and Path(name).name == name and name not in (".", ".."), "invalid recorded asset name")
require(f"-{release['revision'][:12]}-" in name, "recorded asset source differs from tag")
require(HASH.fullmatch(artifact["sha256"]), "invalid recorded asset digest")
require(type(artifact["size"]) is int and artifact["size"] > 0, "invalid recorded asset size")
names.append(name)
require(names == sorted(set(names)), "recorded assets must be sorted and unique")
require(type(snapshot["storage"]["sql_schema_version"]) is int and
snapshot["storage"]["sql_schema_version"] > 0, "missing storage contract")
require(set(snapshot["contracts"]) == set(SOURCES), "incomplete contract inventory")
for key, path in SOURCES.items():
contract = snapshot["contracts"][key]
require(contract["path"] == path and HASH.fullmatch(contract["sha256"]), "invalid source contract")
require(isinstance(contract["content"], dict), "invalid contract content")
def make_index(snapshots):
records = []
for name, snapshot in sorted(snapshots.items()):
validate_snapshot(snapshot, name)
release = snapshot["release"]
records.append({"tag": release["tag"], "revision": release["revision"],
"channel": release["channel"], "file": name,
"sha256": digest(encoded(snapshot))})
repositories = {s["release"]["repository"] for s in snapshots.values()}
require(len(repositories) <= 1, "mixed repositories in release ledger")
stable = [row for row in records if row["channel"] == "stable"]
keys = [version(row["tag"]) for row in stable]
require(len(set(keys)) == len(keys), "ambiguous stable versions")
latest = max(stable, key=lambda row: version(row["tag"]))["tag"] if stable else None
return {"schema": INDEX_SCHEMA, "latest_stable": latest, "releases": records}
def archive_name(snapshot):
release = snapshot["release"]
return f"{release['tag']}.{release['revision']}.json"
def read_archives(directory):
archive = directory / "archive"
require(not archive.is_symlink(), "archive directory must not be a symlink")
snapshots = {}
for path in sorted(archive.glob("*.json")):
require(not path.is_symlink() and path.is_file(), "invalid archive entry")
snapshot = json.loads(path.read_bytes())
validate_snapshot(snapshot, snapshot["release"]["tag"] + ".json")
require(path.name == archive_name(snapshot), "archive filename/revision mismatch")
snapshots[path.name] = snapshot
return snapshots
def read_directory(directory, pending=None, supersede_revision=None):
require(not directory.is_symlink(), "ledger directory must not be a symlink")
archives = read_archives(directory)
snapshots = {}
for path in sorted(directory.glob("*.json")):
require(not path.is_symlink() and path.is_file(), "invalid ledger entry")
if path.name != INDEX:
snapshots[path.name] = json.loads(path.read_bytes())
index_path = directory / INDEX
require(not index_path.is_symlink(), "ledger index must not be a symlink")
prior = dict(snapshots)
if pending is not None:
filename = pending["release"]["tag"] + ".json"
if prior.get(filename) == pending:
del prior[filename]
if supersede_revision:
old = archives.get(f"{pending['release']['tag']}.{supersede_revision}.json")
require(old is not None, "replacement retry lacks archived prior snapshot")
prior[filename] = old
if index_path.exists():
index = json.loads(index_path.read_bytes())
require(index == make_index(snapshots) or
(pending is not None and index == make_index(prior)), "ledger index/hash mismatch")
else:
require(not snapshots or (pending is not None and not prior), "existing snapshots lack their index")
return snapshots
def atomic_write(path, data):
with tempfile.NamedTemporaryFile(dir=path.parent, prefix=".release-contract-", delete=False) as handle:
temporary = Path(handle.name)
try:
handle.write(data)
handle.flush()
temporary.replace(path)
finally:
temporary.unlink(missing_ok=True)
def record_snapshot(directory, snapshot, supersede_revision=None):
if supersede_revision is not None:
require(SHA.fullmatch(supersede_revision), "superseded revision must be an exact SHA")
require(supersede_revision != snapshot["release"]["revision"], "replacement must have a new source revision")
snapshots = read_directory(directory, pending=snapshot, supersede_revision=supersede_revision)
filename = snapshot["release"]["tag"] + ".json"
old = snapshots.get(filename)
replacing = old is not None and old != snapshot
if filename in snapshots:
if replacing:
require(supersede_revision == old["release"]["revision"], "published contract snapshot is immutable; explicit prior revision required")
require(all(old["release"][key] == snapshot["release"][key]
for key in ("tag", "repository", "channel")), "replacement changed release identity")
elif supersede_revision:
raise ValueError("cannot supersede an absent release snapshot")
snapshots[filename] = snapshot
index = make_index(snapshots)
directory.mkdir(parents=True, exist_ok=True)
path = directory / filename
if replacing:
archive = directory / "archive"
archive.mkdir(exist_ok=True)
archived = archive / archive_name(old)
prior_bytes = path.read_bytes()
if archived.exists():
require(archived.read_bytes() == prior_bytes, "archived snapshot is immutable")
else:
atomic_write(archived, prior_bytes)
if not path.exists() or replacing:
atomic_write(path, encoded(snapshot))
atomic_write(directory / INDEX, encoded(index))
return index
def verify_sources(repo, snapshot, *, archived=False):
release = snapshot["release"]
revision = release["revision"]
if not archived:
tag_revision = git(repo, "rev-parse", "--verify", f"refs/tags/{release['tag']}^{{commit}}").decode().strip()
require(tag_revision == revision, "recorded tag has moved")
for key, path in SOURCES.items():
raw = git(repo, "show", f"{revision}:{path}")
require(snapshot["contracts"][key] == {"path": path, "sha256": digest(raw), "content": json.loads(raw)},
"snapshot differs from released contract")
raw = git(repo, "show", f"{revision}:{STORAGE_SOURCE}")
versions = re.findall(rb"pub const LATEST_SCHEMA_VERSION:\s*u32\s*=\s*([0-9]+);", raw)
require(len(versions) == 1 and snapshot["storage"] == {
"sql_schema_version": int(versions[0]), "source_path": STORAGE_SOURCE,
"source_sha256": digest(raw)}, "snapshot differs from released storage format")
def current(repo, directory):
snapshots = read_directory(directory)
tag = make_index(snapshots)["latest_stable"]
require(tag is not None, "no stable published baseline")
snapshot = snapshots[tag + ".json"]
verify_sources(repo, snapshot)
return snapshot
def pull_request_base(environment):
if environment.get("GITHUB_ACTIONS") != "true" or environment.get("GITHUB_EVENT_NAME") != "pull_request":
return None
event = json.loads(Path(environment["GITHUB_EVENT_PATH"]).read_bytes())
base = event["pull_request"]["base"]["sha"]
require(SHA.fullmatch(base), "invalid PR base revision")
return base
def check_append_only(repo, directory, base):
# Preserve every prior byte, either in place or at its revision-bound archive path.
require(not directory.is_symlink() and not (directory / "archive").is_symlink(), "ledger directory must not be a symlink")
revision = git(repo, "rev-parse", "--verify", f"{base}^{{commit}}").decode().strip()
paths = git(repo, "ls-tree", "-r", "--name-only", revision, "--", "contracts/releases").decode().splitlines()
for path in paths:
name = Path(path).name
if not path.endswith(".json") or name == INDEX:
continue
relative = Path(path).relative_to("contracts/releases")
target = directory / relative
require(not target.is_symlink(), "invalid ledger entry")
original = git(repo, "show", f"{revision}:{path}")
if relative.parent == Path(".") and target.is_file() and target.read_bytes() != original:
old = json.loads(original)
replacement = json.loads(target.read_bytes())
require(all(old["release"][key] == replacement["release"][key]
for key in ("tag", "repository", "channel")) and
old["release"]["revision"] != replacement["release"]["revision"],
f"historical snapshot changed or deleted: {path}")
target = directory / "archive" / archive_name(old)
require(target.is_file() and not target.is_symlink() and
target.read_bytes() == original,
f"historical snapshot changed or deleted: {path}")
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("command", choices=("record", "check", "current"))
parser.add_argument("--repo", type=Path, default=Path.cwd())
parser.add_argument("--directory", type=Path, default=Path("contracts/releases"))
parser.add_argument("--release-json", type=Path)
parser.add_argument("--manifest", type=Path, default=Path("apps/website/data/releases.json"))
parser.add_argument("--revision")
parser.add_argument("--repository")
parser.add_argument("--base", help="check historical snapshots against this Git ref; defaults to the Actions PR base")
parser.add_argument("--supersede-unpromoted-revision", help="explicitly replace an unpromoted same-version release; archive this exact prior revision")
args = parser.parse_args()
require(args.command == "record" or args.supersede_unpromoted_revision is None,
"supersession is only valid for record")
if args.command == "record":
require(args.release_json and args.revision and args.repository, "record requires release JSON, revision and repository")
snapshot = create_snapshot(args.repo, json.loads(args.release_json.read_bytes()),
json.loads(args.manifest.read_bytes()), args.revision, args.repository)
result = record_snapshot(args.directory, snapshot, args.supersede_unpromoted_revision)
elif args.command == "check":
base = args.base or pull_request_base(os.environ)
if base:
check_append_only(args.repo, args.directory, base)
snapshots = read_directory(args.directory)
result = make_index(snapshots)
require(result["releases"], "empty release ledger")
for snapshot in snapshots.values():
verify_sources(args.repo, snapshot)
for snapshot in read_archives(args.directory).values():
verify_sources(args.repo, snapshot, archived=True)
else:
result = current(args.repo, args.directory)
print(json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True))
if __name__ == "__main__":
main()