annoscript 0.1.0__py3-none-any.whl

annoscript/server/__init__.py

@@ -0,0 +1 @@
+"""Single-host durable execution service (Python 3.12+). Imported only explicitly."""

annoscript/server/__main__.py

@@ -0,0 +1,49 @@
+"""python -m annoscript.server {api,worker} --db jobs.sqlite --config service.json"""
+
+import argparse
+import asyncio
+import signal
+
+from annoscript.server.releases import load_config
+from annoscript.server.store import Store
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("command", choices=("api", "worker", "releases"))
+    parser.add_argument("--db", default="anno-jobs.sqlite")
+    parser.add_argument("--config", required=True)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument("--concurrency", type=int, default=8)
+    parser.add_argument("--max-generation-inflight", type=int)
+    parser.add_argument("--max-decision-inflight", type=int)
+    args = parser.parse_args()
+    releases, tokens = load_config(args.config)
+    if args.command == "releases":
+        from annoscript.job_protocol import encode
+        print(encode({"default_release": releases.default, "releases": releases.manifests}).decode())
+        return
+    store = Store(args.db)
+    if args.command == "api":
+        import uvicorn
+        from annoscript.server.api import create_app
+        uvicorn.run(create_app(store, releases, tokens), host=args.host, port=args.port, access_log=False)
+    else:
+        from annoscript.server.worker import Worker
+        limits = None
+        if args.max_generation_inflight is not None or args.max_decision_inflight is not None:
+            if args.max_generation_inflight is None or args.max_decision_inflight is None:
+                parser.error("both shared model limits must be provided")
+            limits = {"generation": args.max_generation_inflight, "decision": args.max_decision_inflight}
+        async def serve():
+            stop = asyncio.Event()
+            loop = asyncio.get_running_loop()
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                loop.add_signal_handler(sig, stop.set)
+            await Worker(store, releases, concurrency=args.concurrency, model_request_limits=limits).run(stop=stop)
+        asyncio.run(serve())
+
+
+if __name__ == "__main__":
+    main()

annoscript/server/_plan_cache.py

@@ -0,0 +1,79 @@
+"""Worker-local bounded plan cache. Never contains input or inference state."""
+
+import asyncio
+from collections import OrderedDict
+from concurrent.futures import ThreadPoolExecutor
+import hashlib
+import time
+
+from annoscript.job_protocol import encode
+
+MAX_ENTRIES = 32
+MAX_BYTES = 64 * 1024 * 1024
+
+
+class PlanCache:
+    def __init__(self, *, max_entries=MAX_ENTRIES, max_bytes=MAX_BYTES):
+        self.max_entries, self.max_bytes = max_entries, max_bytes
+        self.entries, self.pending = OrderedDict(), {}
+        self.bytes = 0
+        self.stats = dict(hits=0, misses=0, waits=0, compiles=0, failures=0, evictions=0)
+        self.executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="anno-plan")
+        self.closed = False
+
+    async def get(self, release_id, ir, compile_plan):
+        if self.closed:
+            raise RuntimeError("plan cache is closed")
+        started = time.monotonic()
+        encoded = encode(ir, canonical=True)
+        key = (release_id, hashlib.sha256(encoded).hexdigest())
+        status = "hit"
+        if key in self.entries:
+            self.stats["hits"] += 1
+            entry = self.entries[key]
+            self.entries.move_to_end(key)
+        else:
+            status = "wait" if key in self.pending else "miss"
+            self.stats["waits" if status == "wait" else "misses"] += 1
+            if status == "miss":
+                self.pending[key] = asyncio.create_task(self._compile(key, encoded, compile_plan))
+                # Retrieve exceptions even if every input waiting for this plan was cancelled.
+                self.pending[key].add_done_callback(lambda t: None if t.cancelled() else t.exception())
+            entry = await asyncio.shield(self.pending[key])
+        plan, size, compile_seconds = entry
+        return plan, {"event": "plan_cache", "status": status, "ir_sha256": key[1],
+                      "seconds": time.monotonic() - started,
+                      "compile_seconds": compile_seconds if status != "hit" else 0.0,
+                      "plan_bytes": size, "cached_bytes": self.bytes,
+                      "cached_entries": len(self.entries), "counters": dict(self.stats)}
+
+    async def _compile(self, key, encoded, compile_plan):
+        def build():
+            started = time.monotonic()
+            plan = compile_plan(encoded)
+            size = len(plan.to_json(indent=None).encode("utf-8"))
+            return plan, size, time.monotonic() - started
+        try:
+            entry = await asyncio.get_running_loop().run_in_executor(self.executor, build)
+            self.stats["compiles"] += 1
+            size = entry[1]
+            if self.max_entries > 0 and size <= self.max_bytes:
+                while self.entries and (len(self.entries) >= self.max_entries or self.bytes + size > self.max_bytes):
+                    _, old = self.entries.popitem(last=False)
+                    self.bytes -= old[1]
+                    self.stats["evictions"] += 1
+                self.entries[key] = entry
+                self.bytes += size
+            return entry
+        except Exception:
+            self.stats["failures"] += 1
+            raise
+        finally:
+            self.pending.pop(key, None)
+
+    async def aclose(self):
+        self.closed = True
+        await asyncio.gather(*self.pending.values(), return_exceptions=True)
+        self.executor.shutdown(wait=True)
+        self.entries.clear()
+        self.bytes = 0

annoscript/server/api.py

@@ -0,0 +1,146 @@
+"""Short-request JSON API. No model backend is constructed by this process."""
+
+import asyncio
+from contextlib import asynccontextmanager, suppress
+import hmac
+
+from fastapi import Depends, FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from annoscript.job_protocol import decode, integer, nonempty
+from annoscript.remote import RemoteProtocolError
+from annoscript.server.store import ServiceError
+
+
+def create_app(store, releases, tokens):
+    if not tokens or any(not nonempty(k) or not nonempty(v) for k, v in tokens.items()):
+        raise ValueError("service tokens must map to nonempty principals")
+
+    @asynccontextmanager
+    async def lifespan(app):
+        async def maintain():
+            while True:
+                await asyncio.to_thread(store.maintain)
+                await asyncio.sleep(1)
+        await asyncio.to_thread(store.maintain)
+        task = asyncio.create_task(maintain())
+        try:
+            yield
+        finally:
+            task.cancel()
+            with suppress(asyncio.CancelledError):
+                await task
+
+    app = FastAPI(lifespan=lifespan, docs_url=None, redoc_url=None, openapi_url=None,
+                  redirect_slashes=False)
+
+    @app.exception_handler(ServiceError)
+    async def service_error(request, error):
+        return JSONResponse({"error": {"code": error.code, "message": str(error)}}, status_code=error.status)
+
+    def principal(request: Request):
+        auth = request.headers.get("Authorization", "")
+        if not auth.lower().startswith("bearer "):
+            raise ServiceError("authentication_failed", "service authentication required", 401)
+        supplied = auth[7:]
+        for token, identity in tokens.items():
+            if hmac.compare_digest(supplied.encode(), token.encode()):
+                return identity
+        raise ServiceError("authentication_failed", "invalid service token", 401)
+
+    def key(request):
+        value = request.headers.get("Idempotency-Key")
+        if not nonempty(value) or len(value) > 256:
+            raise ServiceError("invalid_idempotency_key", "a nonempty Idempotency-Key of at most 256 characters is required")
+        return value
+
+    async def body(request, *, empty=False):
+        limit = max(m["policy"]["max_request_bytes"] for m in releases.manifests.values())
+        data = bytearray()
+        async for chunk in request.stream():
+            data.extend(chunk)
+            if len(data) > limit:
+                raise ServiceError("request_too_large", "request exceeds service body limit", 413)
+        if not data and empty:
+            return {}
+        if request.headers.get("content-type", "").split(";", 1)[0].lower() != "application/json":
+            raise ServiceError("invalid_content_type", "expected application/json", 415)
+        try:
+            value = decode(bytes(data))
+        except RemoteProtocolError as exc:
+            raise ServiceError("invalid_json", str(exc)) from None
+        if type(value) is not dict:
+            raise ServiceError("invalid_request", "request must be an object")
+        return value
+
+    def envelope(job):
+        return {"protocol_version": 1, "job": job}
+
+    @app.post("/v1/jobs", status_code=202)
+    async def submit(request: Request, identity=Depends(principal)):
+        idem = key(request)
+        payload = await body(request)
+        try:
+            job = await asyncio.to_thread(store.submit, identity, idem, payload, releases)
+        except (ValueError, TypeError, RecursionError) as exc:
+            raise ServiceError("invalid_request", "invalid job request or IR") from exc
+        return envelope(job)
+
+    @app.get("/v1/jobs:lookup")
+    def lookup(request: Request, identity=Depends(principal)):
+        return envelope(store.lookup(identity, key(request)))
+
+    @app.get("/v1/jobs/{job_id}")
+    def status(job_id: str, identity=Depends(principal)):
+        return envelope(store.status(identity, job_id))
+
+    @app.get("/v1/jobs/{job_id}/results")
+    def results(job_id: str, request: Request, identity=Depends(principal)):
+        try:
+            limit = int(request.query_params.get("limit", "100"))
+        except ValueError:
+            raise ServiceError("invalid_limit", "invalid page limit") from None
+        return store.results(identity, job_id, request.query_params.get("cursor"), limit)
+
+    @app.get("/v1/jobs/{job_id}/metrics")
+    def metrics(job_id: str, identity=Depends(principal)):
+        return store.metrics(identity, job_id)
+
+    @app.post("/v1/jobs/{job_id}:resume")
+    async def resume(job_id: str, request: Request, identity=Depends(principal)):
+        idem = key(request)
+        payload = await body(request)
+        if set(payload) != {"pause_generation"} or not integer(payload["pause_generation"], 1):
+            raise ServiceError("invalid_request", "resume requires a positive pause_generation")
+        return envelope(await asyncio.to_thread(store.resume, identity, job_id, idem, payload["pause_generation"], releases))
+
+    @app.post("/v1/jobs/{job_id}:cancel")
+    async def cancel(job_id: str, request: Request, identity=Depends(principal)):
+        if await body(request, empty=True):
+            raise ServiceError("invalid_request", "cancel body must be empty")
+        return envelope(await asyncio.to_thread(store.cancel, identity, job_id))
+
+    @app.get("/v1/releases/{release_id}")
+    def release(release_id: str, identity=Depends(principal)):
+        return {"protocol_version": 1, **store.release(release_id, releases)}
+
+    @app.post("/v1/sessions", status_code=201)
+    async def create_session(request: Request, identity=Depends(principal)):
+        idem = key(request)
+        if await body(request, empty=True):
+            raise ServiceError("invalid_request", "session body must be empty")
+        return {"protocol_version": 1, **await asyncio.to_thread(store.create_session, identity, idem)}
+
+    @app.post("/v1/sessions/{session_id}:heartbeat")
+    async def heartbeat(session_id: str, request: Request, identity=Depends(principal)):
+        if await body(request, empty=True):
+            raise ServiceError("invalid_request", "heartbeat body must be empty")
+        return {"protocol_version": 1, **await asyncio.to_thread(store.heartbeat_session, identity, session_id)}
+
+    @app.post("/v1/sessions/{session_id}:close")
+    async def close_session(session_id: str, request: Request, identity=Depends(principal)):
+        if await body(request, empty=True):
+            raise ServiceError("invalid_request", "close body must be empty")
+        return {"protocol_version": 1, **await asyncio.to_thread(store.close_session, identity, session_id)}
+
+    return app

annoscript/server/metrics.py

@@ -0,0 +1,140 @@
+"""Fenced metric persistence. No provider bodies or client-side journal."""
+
+import asyncio
+import time
+import uuid
+
+from annoscript.job_protocol import TERMINAL, decode, encode
+from annoscript.metrics import aggregate, normalize_usage
+from annoscript.backends.base import BackendFatalError
+
+
+UPGRADE = """
+ALTER TABLE jobs ADD COLUMN metrics_available INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE jobs ADD COLUMN queued_monotonic REAL;
+ALTER TABLE jobs ADD COLUMN clock_epoch TEXT;
+ALTER TABLE attempts ADD COLUMN metered INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE attempts ADD COLUMN duration_seconds REAL;
+ALTER TABLE attempts ADD COLUMN queue_wait_seconds REAL;
+CREATE TABLE http_requests (
+ id TEXT PRIMARY KEY, job_id TEXT NOT NULL, idx INTEGER NOT NULL, attempt INTEGER NOT NULL,
+ backend TEXT NOT NULL, questions INTEGER NOT NULL, http_status INTEGER, seconds REAL, usage BLOB,
+ FOREIGN KEY(job_id,idx,attempt) REFERENCES attempts(job_id,idx,number));
+CREATE INDEX http_requests_job ON http_requests(job_id,idx,attempt);
+PRAGMA user_version=2;
+"""
+
+
+class MetricStore:
+    def meter_attempt(self, claim, supported):
+        with self._tx() as db:
+            if self._owned(db, claim) is None:
+                return False
+            db.execute("UPDATE attempts SET metered=? WHERE job_id=? AND idx=? AND number=?",
+                       (int(supported), claim["job_id"], claim["index"], claim["attempt"]))
+            return True
+
+    def request_started(self, claim, request_id, backend, questions):
+        if backend not in ("decision", "generation") or type(questions) is not int or questions < 1:
+            raise ValueError("invalid request metrics")
+        with self._tx() as db:
+            owned = self._owned(db, claim)
+            if owned is None or owned[0]["state"] not in ("queued", "running"):
+                return False
+            args = (request_id, claim["job_id"], claim["index"], claim["attempt"], backend, questions)
+            old = db.execute("SELECT id,job_id,idx,attempt,backend,questions FROM http_requests WHERE id=?", (request_id,)).fetchone()
+            if old is not None and tuple(old) != args:
+                raise ValueError("request metric identity conflict")
+            db.execute("INSERT OR IGNORE INTO http_requests(id,job_id,idx,attempt,backend,questions) VALUES (?,?,?,?,?,?)", args)
+            return True
+
+    def request_finished(self, claim, request_id, *, seconds, http_status, usage):
+        if type(seconds) not in (int, float) or not 0 <= seconds < float("inf"):
+            raise ValueError("invalid HTTP duration")
+        if http_status is not None and (type(http_status) is not int or not 100 <= http_status <= 599):
+            raise ValueError("invalid HTTP status")
+        with self._tx() as db:
+            if self._owned(db, claim) is None:
+                return False
+            db.execute("""UPDATE http_requests SET seconds=?,http_status=?,usage=?
+                          WHERE id=? AND job_id=? AND idx=? AND attempt=? AND seconds IS NULL""",
+                       (seconds, http_status, encode(normalize_usage(usage)), request_id,
+                        claim["job_id"], claim["index"], claim["attempt"]))
+            return True
+
+    def _attempt_duration(self, db, claim, seconds):
+        if seconds is not None and (type(seconds) not in (int, float) or not 0 <= seconds < float("inf")):
+            raise ValueError("invalid attempt duration")
+        db.execute("UPDATE attempts SET duration_seconds=? WHERE job_id=? AND idx=? AND number=?",
+                   (seconds, claim["job_id"], claim["index"], claim["attempt"]))
+
+    def metrics(self, principal, job_id):
+        with self._tx() as db:
+            job = self._job(db, job_id, principal)
+            status = self._status(db, job)
+            attempts = [dict(r) for r in db.execute("SELECT * FROM attempts WHERE job_id=? ORDER BY idx,number", (job_id,))]
+            requests = [dict(r) for r in db.execute("SELECT * FROM http_requests WHERE job_id=? ORDER BY id", (job_id,))]
+            for row in requests:
+                row["usage"] = decode(row["usage"]) if row["usage"] is not None else normalize_usage(None)
+            items, waits = [], []
+            for index in status["input_indices"]:
+                aa = [a for a in attempts if a["idx"] == index]
+                rr = [r for r in requests if r["idx"] == index]
+                # Queue intervals are valid only within the same monotonic
+                # clock epoch (boot); never subtract wall timestamps.
+                wait = aa[0]["queue_wait_seconds"] if aa else None
+                waits.append(wait)
+                items.append({"index": index, "metrics": aggregate(aa, rr, history=bool(job["metrics_available"]), waits=[wait])})
+            return {"protocol_version": 1, "metrics_version": 1, "job": status,
+                    "provisional": status["state"] not in TERMINAL,
+                    "summary": aggregate(attempts, requests, history=bool(job["metrics_available"]), waits=waits), "inputs": items}
+
+
+class RequestMeter:
+    """One meter per owned attempt, invoked only at the actual HTTP boundary."""
+    def __init__(self, store, claim, backend, *, clock=time.monotonic, observer=None, wall_clock=time.time):
+        self.store, self.claim, self.backend, self.clock = store, claim, backend, clock
+        self.observer, self.wall_clock = observer, wall_clock
+
+    def _observe(self, event):
+        if self.observer is not None:
+            try:
+                self.observer({"job_id": self.claim["job_id"], "index": self.claim["index"],
+                               "attempt": self.claim["attempt"], "stage": self.backend, **event})
+            except Exception:
+                raise BackendFatalError("request audit persistence failed", code="metrics_failed") from None
+
+    async def start(self, questions):
+        identity = uuid.uuid4().hex
+        try:
+            committed = await asyncio.to_thread(self.store.request_started, self.claim, identity, self.backend, questions)
+        except Exception:
+            raise BackendFatalError("request intent persistence failed", code="metrics_failed") from None
+        if not committed:
+            if self.store.renew(self.claim):
+                raise BackendFatalError("job is paused; no new model request was sent", code="job_paused")
+            raise asyncio.CancelledError()
+        self._observe({"event": "intent", "request_id": identity, "questions": questions,
+                       "started_unix": self.wall_clock()})
+        return identity
+
+    async def finish(self, identity, elapsed, status, usage):
+        outcome = {"event": "outcome", "request_id": identity, "seconds": elapsed,
+                   "http_status": status, "usage": usage, "finished_unix": self.wall_clock()}
+        committed = False
+        pending = asyncio.create_task(asyncio.to_thread(self.store.request_finished, self.claim, identity,
+                                                        seconds=elapsed, http_status=status, usage=usage))
+        try:
+            try:
+                committed = await asyncio.shield(pending)
+            except asyncio.CancelledError:
+                # Drain persistence and audit before propagating cancellation.
+                # Ownership fencing still applies to stale attempts.
+                committed = await pending
+                raise
+        except Exception:
+            raise BackendFatalError("request outcome persistence failed", code="metrics_failed") from None
+        finally:
+            self._observe({**outcome, "storage_committed": committed})
+        if not committed:
+            raise asyncio.CancelledError()

annoscript/server/migrate.py

@@ -0,0 +1,61 @@
+"""Explicit offline v1 -> v2 migration; stop API and workers before invoking."""
+
+import argparse
+from contextlib import closing
+import os
+from pathlib import Path
+import sqlite3
+
+from annoscript.server.metrics import UPGRADE
+
+
+def migrate(path, backup, *, _after_statement=None):
+    path, backup = Path(path), Path(backup)
+    if not path.is_file() or path.resolve() == backup.resolve():
+        raise ValueError("an existing database and a separate new backup path are required")
+    with closing(sqlite3.connect(path, isolation_level=None)) as db:
+        if db.execute("PRAGMA user_version").fetchone()[0] != 1:
+            raise RuntimeError("migration requires schema v1")
+        # O_EXCL protects an earlier backup. SQLite backup includes committed WAL.
+        fd = os.open(backup, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        os.close(fd)
+        with closing(sqlite3.connect(backup)) as target:
+            db.backup(target)
+            if target.execute("PRAGMA integrity_check").fetchone()[0] != "ok":
+                raise RuntimeError("backup integrity check failed")
+        with open(backup, "rb") as file:
+            os.fsync(file.fileno())
+        directory = os.open(backup.parent, os.O_RDONLY)
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+        db.execute("PRAGMA foreign_keys=ON")
+        db.execute("PRAGMA synchronous=FULL")
+        db.execute("BEGIN EXCLUSIVE")
+        try:
+            if db.execute("PRAGMA user_version").fetchone()[0] != 1:
+                raise RuntimeError("database changed during backup")
+            for statement in UPGRADE.split(";"):
+                if statement.strip():
+                    db.execute(statement)
+                    if _after_statement is not None:
+                        _after_statement(statement)
+            if db.execute("PRAGMA foreign_key_check").fetchone() is not None:
+                raise RuntimeError("foreign key check failed")
+            db.commit()
+        except BaseException:
+            db.rollback()
+            raise
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--db", required=True)
+    parser.add_argument("--backup", required=True)
+    args = parser.parse_args()
+    migrate(args.db, args.backup)
+
+
+if __name__ == "__main__":
+    main()

annoscript/server/releases.py

@@ -0,0 +1,143 @@
+"""Immutable execution manifests; credentials stay outside manifests and SQLite."""
+
+import hashlib
+from importlib.metadata import version
+import os
+from pathlib import Path
+import sys
+from annoscript._env import env_value
+from urllib.parse import urlsplit
+
+from annoscript.job_protocol import decode, encode
+from annoscript._backend_profiles import validate_generation_profile, validate_extract_mode
+from annoscript._request_adapters import (DEFAULT_DECISION_ADAPTER, DEFAULT_GENERATION_ADAPTER,
+                                   validate_request_adapter, normalize_decision_options)
+from annoscript.backends.base import LLM_BATCH_DEFAULTS, validate_batch_options
+from annoscript.backends._generation_policy import validate_policy, validate_token_ratio
+from annoscript.server._plan_cache import MAX_ENTRIES, MAX_BYTES
+from annoscript.backends._shared_rules import validate_rule_dedup
+
+RUNTIME = {"max_active_runs": 1, "max_decision_inflight": 4, "max_llm_inflight": 4,
+           "max_batch_questions": 32, "loop_window": 32, "local_task_budget": 1024, **LLM_BATCH_DEFAULTS}
+POLICY = {"max_attempts": 3, "input_timeout": 300.0, "model_timeout": 60.0,
+          "max_inputs": 500, "max_request_bytes": 32 * 1024 * 1024,
+          "retry_unknown_outcomes": True}
+
+
+def build_sha256():
+    root = Path(__file__).resolve().parents[1]
+    digest = hashlib.sha256()
+    for path in sorted(root.rglob("*.py")):
+        if path.name.startswith(("test_", "_test_")):
+            continue
+        digest.update(str(path.relative_to(root)).encode() + b"\0" + path.read_bytes() + b"\0")
+    return digest.hexdigest()
+
+
+def manifest(config):
+    allowed = {"decision", "generation", "server_optimize", "runtime", "policy", "disable_thinking"}
+    if type(config) is not dict or set(config) - allowed:
+        raise ValueError("invalid release configuration")
+    models = {}
+    for name in ("decision", "generation"):
+        model = config.get(name)
+        if name == "generation" and isinstance(model, dict) and "source_layout" in model:
+            raise ValueError("source_layout was removed; extract now uses source_field")
+        required = {"base_url", "model", "revision"}
+        allowed_model = required | {"request_adapter"} | ({"profile", "extract_mode", "batch_rule_dedup", "structured_output_revision", "request_policy", "assumed_avg_num_tokens_per_char"} if name == "generation" else {"request_adapter_options"})
+        if (type(model) is not dict or not required <= set(model) or set(model) - allowed_model
+                or any(type(v) is not str or not v.strip() for k, v in model.items() if k not in ("request_policy", "assumed_avg_num_tokens_per_char", "batch_rule_dedup", "request_adapter_options"))):
+            raise ValueError(f"{name} needs base_url, model and immutable deployment revision")
+        url = urlsplit(model["base_url"])
+        if url.scheme not in ("http", "https") or not url.hostname or url.username or url.password or url.query or url.fragment:
+            raise ValueError("model URL must be HTTP(S), without credentials, query or fragment")
+        models[name] = model.copy()
+        models[name]["request_adapter"] = validate_request_adapter(
+            model.get("request_adapter", DEFAULT_DECISION_ADAPTER if name == "decision" else DEFAULT_GENERATION_ADAPTER), name)
+        if name == "decision":
+            if "request_adapter_options" in model and type(model["request_adapter_options"]) is not dict:
+                raise ValueError("request_adapter_options must be an object")
+            options = normalize_decision_options(models[name]["request_adapter"], model.get("request_adapter_options"))
+            if options is not None:
+                models[name]["request_adapter_options"] = options
+            else:
+                models[name].pop("request_adapter_options", None)
+        if name == "generation":
+            models[name]["assumed_avg_num_tokens_per_char"] = validate_token_ratio(model.get("assumed_avg_num_tokens_per_char", 2))
+            models[name]["profile"] = validate_generation_profile(model.get("profile", "legacy"))
+            if "batch_rule_dedup" in model:
+                models[name]["batch_rule_dedup"] = validate_rule_dedup(model["batch_rule_dedup"], models[name]["profile"])
+            # Omitted mode keeps existing release hashes stable for old manifests.
+            mode = validate_extract_mode(model.get("extract_mode", "validated"), models[name]["profile"])
+            if "extract_mode" in model:
+                models[name]["extract_mode"] = mode
+            if mode == "substring_chars" and not model.get("structured_output_revision"):
+                raise ValueError("substring_chars requires immutable structured_output_revision")
+            if "request_policy" in model:
+                request_policy = validate_policy(model["request_policy"])
+                if request_policy is None or models[name]["profile"] != "qwen_vllm":
+                    raise ValueError("request_policy requires qwen_vllm")
+                if request_policy["tokenizer"]["revision"] != model["revision"]:
+                    raise ValueError("tokenizer revision differs from generation revision")
+                if not model.get("structured_output_revision"):
+                    raise ValueError("bounded outputs require immutable decoder build identity")
+                models[name]["request_policy"] = request_policy
+    runtime, policy = {**RUNTIME, **config.get("runtime", {})}, {**POLICY, **config.get("policy", {})}
+    validate_batch_options({k: runtime[k] for k in LLM_BATCH_DEFAULTS})
+    if (set(runtime) != set(RUNTIME) or any(type(v) is not int or v < 1 for k, v in runtime.items() if k != "llm_batch_repair_attempts")
+            or runtime["max_active_runs"] != 1 or set(policy) != set(POLICY)
+            or type(policy["retry_unknown_outcomes"]) is not bool
+            or any(type(v) not in (int, float) or not 0 < v < float("inf")
+                   for k, v in policy.items() if k != "retry_unknown_outcomes")
+            or any(type(policy[k]) is not int for k in ("max_attempts", "max_inputs", "max_request_bytes"))):
+        raise ValueError("invalid release runtime or resource policy")
+    generation_policy = models["generation"].get("request_policy")
+    optimize, thinking = config.get("server_optimize", True), config.get("disable_thinking", True)
+    if type(optimize) is not bool or type(thinking) is not bool:
+        raise ValueError("release switches must be booleans")
+    return {"format": "lev-release", "version": 1, "build_sha256": build_sha256(),
+            "engineering": {"plan_cache": {"max_entries": MAX_ENTRIES, "max_serialized_bytes": MAX_BYTES,
+                                            "compiler_threads": 1, "key": "release_id+canonical_ir_sha256"},
+                            "qwen_source_layout": "source_field_v1", "request_preparation": "immutable_v1",
+                            "worker_refill": "completion_event_v1", "shared_model_slots": "ready_at_admission_fifo_v1",
+                            "shared_slot_scope": "single_worker_process; limits bound by execution manifest"},
+            "python": f"{sys.version_info.major}.{sys.version_info.minor}", "ir_version": 1,
+            "dependencies": {name: version(name) for name in ("httpx", "httpcore", "fastapi", "starlette", "uvicorn")},
+            **models, "server_optimize": optimize, "disable_thinking": thinking,
+            "runtime": runtime, "policy": policy}
+
+
+class Releases:
+    def __init__(self, configs, default):
+        self.manifests, self.aliases = {}, {}
+        for alias, config in configs.items():
+            value = manifest(config)
+            release_id = hashlib.sha256(encode(value, canonical=True)).hexdigest()
+            self.manifests[release_id] = value
+            self.aliases[alias] = release_id
+        if default not in self.aliases:
+            raise ValueError("default_release must name a configured release")
+        self.default = self.aliases[default]
+
+    def resolve(self, release_id=None):
+        release_id = release_id or self.default
+        if release_id not in self.manifests:
+            raise KeyError(release_id)
+        return release_id, self.manifests[release_id]
+
+
+def load_config(path):
+    if sys.version_info < (3, 12):
+        raise RuntimeError("the AnnoScript job service requires Python 3.12+")
+    config = decode(Path(path).read_bytes())
+    if type(config) is not dict or set(config) != {"releases", "default_release", "auth"}:
+        raise ValueError("config requires releases, default_release and auth")
+    if type(config["auth"]) is not dict or not config["auth"]:
+        raise ValueError("auth must map principals to token environment variable names")
+    tokens = {}
+    for principal, variable in config["auth"].items():
+        token = env_value(variable) if variable.startswith("ANNO_") else os.environ.get(variable)
+        if not principal or not token or token in tokens:
+            raise ValueError("service authentication tokens must be present and unique")
+        tokens[token] = principal
+    return Releases(config["releases"], config["default_release"]), tokens