Upload folder using huggingface_hub

atp/__init__.py

@@ -0,0 +1,23 @@
+"""
+ATP — the Agentic Training Platform data + store layer.
+
+`atp.get_data()` returns the full `window.ATP_DATA` payload (seed, cached).
+The store also exposes append-only HITL reward logging and the compose /
+train-to-order request log.
+"""
+
+from .store import (
+    get_data,
+    append_hitl,
+    read_hitl,
+    append_request,
+    read_requests,
+)
+
+__all__ = [
+    "get_data",
+    "append_hitl",
+    "read_hitl",
+    "append_request",
+    "read_requests",
+]

atp/crypto.py

@@ -0,0 +1,139 @@
+"""
+Envelope encryption for T2 ("crown jewels") columns — docs/TENANCY.md.
+
+Key model (leak surface #10 — one key must not unlock all orgs):
+
+  * Master key: `DATA_ENCRYPTION_KEY` env var, read at CALL time (never at
+    import). Any high-entropy string; its utf-8 bytes are the HKDF input key
+    material. Only ever supplied via env — never stored in the repo or DB.
+  * Per-org subkey: HKDF-SHA256(master, info=org_id) → 32 bytes → urlsafe-b64
+    → Fernet key. Deterministic, so no key table is needed; compromise of one
+    derived key does not reveal the master or any sibling org's key.
+  * Rotation (re-wrap): stand up the new master alongside the old
+    (`DATA_ENCRYPTION_KEY_OLD` by operator convention), then for each T2 row:
+    decrypt with the old master's per-org subkey, encrypt with the new one,
+    write back. `enc1:` is the version tag — a future algorithm/rotation
+    scheme bumps to `enc2:` so mixed-version tables stay readable.
+
+Wire format: `'enc1:' + Fernet token` stored in TEXT columns. Values WITHOUT
+the prefix are legacy plaintext and read through unchanged — decryption of
+legacy rows never requires a key, so pre-encryption databases keep working.
+
+Fail-loud: encrypting anything, or decrypting an `enc1:` token, without
+`DATA_ENCRYPTION_KEY` raises RuntimeError immediately (no silent plaintext
+writes, no silent empty reads). A token that fails authentication (tampered,
+or decrypted under the wrong org's subkey) raises ValueError.
+
+Public:
+  encrypt_for_org(org_id, data)        -> 'enc1:…' str  (data: bytes or str)
+  decrypt_for_org(org_id, value)       -> bytes | None  (plaintext passthrough)
+  decrypt_text_for_org(org_id, value)  -> str | None    (utf-8 convenience)
+  is_encrypted(value)                  -> bool
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import threading
+
+from cryptography.fernet import Fernet, InvalidToken
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+ENC_PREFIX = "enc1:"
+
+_LOCK = threading.Lock()
+# (master_bytes, org_id) -> Fernet. Keyed by master so tests / rotation that
+# change the env var never serve a stale subkey.
+_FERNET_CACHE: dict[tuple[bytes, str], Fernet] = {}
+
+
+def _master() -> bytes:
+    """Return the master key bytes, failing loudly when encryption was
+    requested but no key is configured."""
+    key = os.environ.get("DATA_ENCRYPTION_KEY", "")
+    if not key.strip():
+        raise RuntimeError(
+            "DATA_ENCRYPTION_KEY is not set but an encrypt/decrypt of T2 "
+            "data was requested. Refusing to continue (docs/TENANCY.md data "
+            "class T2). Set DATA_ENCRYPTION_KEY in the deployment "
+            "environment (see .env.example); legacy plaintext values still "
+            "read through without it."
+        )
+    return key.strip().encode("utf-8")
+
+
+def _fernet_for_org(org_id: str) -> Fernet:
+    """Per-org Fernet from HKDF-SHA256(master, info=org_id)."""
+    if not org_id or not isinstance(org_id, str):
+        raise ValueError("org_id must be a non-empty string")
+    master = _master()
+    cache_key = (master, org_id)
+    f = _FERNET_CACHE.get(cache_key)
+    if f is None:
+        with _LOCK:
+            f = _FERNET_CACHE.get(cache_key)
+            if f is None:
+                derived = HKDF(
+                    algorithm=hashes.SHA256(),
+                    length=32,
+                    salt=None,  # HKDF treats absent salt as zeros — fine:
+                                # uniqueness comes from info=org_id
+                    info=org_id.encode("utf-8"),
+                ).derive(master)
+                f = Fernet(base64.urlsafe_b64encode(derived))
+                _FERNET_CACHE[cache_key] = f
+    return f
+
+
+def is_encrypted(value: str | bytes | None) -> bool:
+    """True when `value` carries the enc1 envelope prefix."""
+    if isinstance(value, bytes):
+        return value.startswith(ENC_PREFIX.encode("ascii"))
+    if isinstance(value, str):
+        return value.startswith(ENC_PREFIX)
+    return False
+
+
+def encrypt_for_org(org_id: str, data: bytes | str) -> str:
+    """Encrypt `data` under `org_id`'s subkey → 'enc1:<fernet token>'.
+
+    Fails loudly (RuntimeError) when DATA_ENCRYPTION_KEY is unset — callers
+    must never fall back to writing plaintext for T2 fields.
+    """
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    if not isinstance(data, bytes):
+        raise TypeError(f"encrypt_for_org expects bytes or str, got {type(data).__name__}")
+    token = _fernet_for_org(org_id).encrypt(data)
+    return ENC_PREFIX + token.decode("ascii")
+
+
+def decrypt_for_org(org_id: str, value: str | bytes | None) -> bytes | None:
+    """Decrypt an 'enc1:' envelope; pass legacy plaintext through as bytes.
+
+    * None → None.
+    * 'enc1:…' → decrypted bytes (RuntimeError without a key; ValueError if
+      the token is tampered with or belongs to a different org's subkey).
+    * anything else → returned unchanged as bytes (str is utf-8 encoded):
+      pre-encryption rows keep reading without DATA_ENCRYPTION_KEY.
+    """
+    if value is None:
+        return None
+    if not is_encrypted(value):
+        return value.encode("utf-8") if isinstance(value, str) else bytes(value)
+    token = value[len(ENC_PREFIX):] if isinstance(value, str) else value[len(ENC_PREFIX):].decode("ascii")
+    try:
+        return _fernet_for_org(org_id).decrypt(token.encode("ascii") if isinstance(token, str) else token)
+    except InvalidToken:
+        raise ValueError(
+            f"enc1 token failed to decrypt under org {org_id!r}: wrong org "
+            "subkey, wrong master key, or tampered ciphertext"
+        ) from None
+
+
+def decrypt_text_for_org(org_id: str, value: str | bytes | None) -> str | None:
+    """decrypt_for_org, decoded as utf-8 (T2 columns are TEXT)."""
+    out = decrypt_for_org(org_id, value)
+    return None if out is None else out.decode("utf-8")

atp/db.py

@@ -0,0 +1,312 @@
+"""
+DB access layer — SQLAlchemy Core engine, tiny SQL helpers, migration runner.
+
+One engine per process (module-level singleton), configured by env:
+
+  DATABASE_URL     — full SQLAlchemy URL. Unset → SQLite (see below).
+                     Postgres: postgresql+psycopg2://user:pass@host:5432/db
+                     (bare postgres:// / postgresql:// URLs, as handed out by
+                     Render/Heroku, are normalized to the psycopg2 driver).
+  BRAIN_DB         — SQLite path used when DATABASE_URL is unset
+                     (default data/brain_university.db; parent dir created).
+  BU_DB_POOL_SIZE  — Postgres pool size (default 5; max_overflow fixed at 5).
+
+Public:
+  get_engine() -> Engine             lazy singleton
+  is_postgres() -> bool              True when the engine talks to Postgres
+  query(sql, params) -> list[dict]   SELECTs; named params (:name), both dialects
+  execute(sql, params) -> ExecResult (.rowcount, .lastrowid)
+  run_migrations() -> list[str]      apply pending migrations/ files (idempotent)
+  reset_engine()                     dispose the singleton (tests / env changes)
+
+Writing SQL that works on BOTH dialects:
+  * Bind values with SQLAlchemy named params (:name) — never string-format
+    values into SQL. `query`/`execute` wrap the SQL in sqlalchemy.text().
+  * For INSERT ids, append `RETURNING <id_col>` — both Postgres and SQLite
+    >= 3.35 (Python 3.11's bundled build) support it, and `execute()` surfaces
+    the first returned column as `.lastrowid`. Plain INSERTs also populate
+    `.lastrowid` on SQLite; on Postgres use RETURNING.
+
+Migrations live in migrations/ as `NNN_name[.pg|.sqlite].sql`. For a given
+base name (`NNN_name`) the file suffixed with the current dialect wins over
+the plain `.sql` one. Applied base names are tracked in `schema_migrations`;
+each file is applied inside a single transaction, so a failed migration
+leaves the DB untouched (Postgres; SQLite DDL is best-effort transactional).
+
+Statement-separator convention (also documented at the top of each migration
+file): a line containing only `--;;` splits the file into statements — needed
+because trigger bodies contain ';'. Files without any `--;;` line are split
+on plain ';'.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+from pathlib import Path
+from typing import NamedTuple
+
+from sqlalchemy import create_engine, text
+from sqlalchemy.engine import Engine, make_url
+from sqlalchemy.pool import NullPool
+
+PROJECT_ROOT = Path(__file__).parent.parent
+MIGRATIONS_DIR = PROJECT_ROOT / "migrations"
+DEFAULT_SQLITE_DB = PROJECT_ROOT / "data" / "brain_university.db"
+
+STATEMENT_MARKER = "--;;"
+
+_ENGINE: Engine | None = None
+
+
+class ExecResult(NamedTuple):
+    """Outcome of a write statement.
+
+    rowcount  — rows affected (UPDATE/DELETE; driver-dependent for INSERT).
+    lastrowid — SQLite: rowid of the last INSERT. Postgres: only populated
+                when the statement uses RETURNING (first column of the first
+                returned row) — RETURNING also works on SQLite >= 3.35, so
+                `INSERT ... RETURNING id` is the portable way to get new ids.
+    """
+
+    rowcount: int
+    lastrowid: int | None
+
+
+# ── Engine ──────────────────────────────────────────────────────────────────
+
+def _database_url() -> str:
+    url = os.environ.get("DATABASE_URL", "").strip()
+    if url:
+        # Render/Heroku hand out postgres:// — SQLAlchemy 2.x needs the
+        # explicit driver segment.
+        if url.startswith("postgres://"):
+            url = "postgresql+psycopg2://" + url[len("postgres://"):]
+        elif url.startswith("postgresql://"):
+            url = "postgresql+psycopg2://" + url[len("postgresql://"):]
+        return url
+    # No DATABASE_URL → SQLite. Honour BRAIN_DB (already set by Dockerfile /
+    # render.yaml) so deployments keep pointing at the same file as before.
+    path = Path(os.environ.get("BRAIN_DB") or DEFAULT_SQLITE_DB)
+    return f"sqlite:///{path}"
+
+
+def get_engine() -> Engine:
+    """Return the process-wide engine, creating it on first use."""
+    global _ENGINE
+    if _ENGINE is None:
+        url = make_url(_database_url())
+        if url.get_backend_name() == "sqlite":
+            if url.database and url.database != ":memory:":
+                Path(url.database).parent.mkdir(parents=True, exist_ok=True)
+            # NullPool + check_same_thread=False: FastAPI serves requests on
+            # a thread pool; a fresh short-lived connection per operation is
+            # the safe pattern for SQLite.
+            _ENGINE = create_engine(
+                url,
+                poolclass=NullPool,
+                connect_args={"check_same_thread": False},
+            )
+        else:
+            _ENGINE = create_engine(
+                url,
+                pool_pre_ping=True,   # survive dropped/idle-closed connections
+                pool_size=int(os.environ.get("BU_DB_POOL_SIZE", "5")),
+                max_overflow=5,
+            )
+    return _ENGINE
+
+
+def is_postgres() -> bool:
+    return get_engine().dialect.name == "postgresql"
+
+
+def reset_engine() -> None:
+    """Dispose the singleton so the next call rebuilds it from env (tests)."""
+    global _ENGINE
+    if _ENGINE is not None:
+        _ENGINE.dispose()
+        _ENGINE = None
+
+
+# ── SQL helpers ─────────────────────────────────────────────────────────────
+
+def query(sql: str, params: dict | None = None) -> list[dict]:
+    """Run a SELECT (named params `:name`) and return rows as list[dict]."""
+    with get_engine().connect() as conn:
+        rows = conn.execute(text(sql), params or {}).mappings().all()
+        return [dict(r) for r in rows]
+
+
+def execute(sql: str, params: dict | None = None) -> ExecResult:
+    """Run a write statement in its own transaction. See ExecResult."""
+    with get_engine().begin() as conn:
+        result = conn.execute(text(sql), params or {})
+        lastrowid: int | None = None
+        if result.returns_rows:  # INSERT ... RETURNING <id> (both dialects)
+            row = result.first()
+            if row is not None:
+                lastrowid = row[0]
+        else:
+            try:
+                lastrowid = result.lastrowid  # meaningful on SQLite
+            except Exception:  # noqa: BLE001 — drivers without lastrowid
+                lastrowid = None
+        return ExecResult(rowcount=result.rowcount, lastrowid=lastrowid)
+
+
+# ── Migrations ──────────────────────────────────────────────────────────────
+
+# NNN_name.sql | NNN_name.pg.sql | NNN_name.sqlite.sql
+_MIGRATION_RE = re.compile(r"^(?P<base>\d+_\w+?)(?:\.(?P<dialect>pg|sqlite))?\.sql$")
+
+
+def run_migrations() -> list[str]:
+    """Apply every unapplied migration file, in order. Returns applied names.
+
+    Idempotent: applied base names are recorded in schema_migrations, so a
+    second call is a no-op. Each migration runs in a single transaction
+    together with its schema_migrations bookkeeping row.
+    """
+    engine = get_engine()
+    with engine.begin() as conn:
+        conn.exec_driver_sql(
+            "CREATE TABLE IF NOT EXISTS schema_migrations ("
+            "  name       TEXT PRIMARY KEY,"
+            "  applied_at DOUBLE PRECISION NOT NULL"
+            ")"
+        )
+    already = {r["name"] for r in query("SELECT name FROM schema_migrations")}
+
+    applied: list[str] = []
+    for base, path in _discover_migrations():
+        if base in already:
+            continue
+        statements = _split_statements(path.read_text())
+        with engine.begin() as conn:
+            # Raw DBAPI cursor, no parameters: exec_driver_sql() hands the
+            # driver an (empty) params object, which makes psycopg2 run its
+            # %-interpolation over the SQL — any literal '%' in a migration
+            # (e.g. plpgsql RAISE '%' placeholders in 002_atp.pg.sql) then
+            # raises TypeError. cursor.execute(sql) with no params skips
+            # interpolation entirely, on both drivers.
+            cursor = conn.connection.cursor()
+            try:
+                for stmt in statements:
+                    cursor.execute(stmt)
+            finally:
+                cursor.close()
+            conn.execute(
+                text("INSERT INTO schema_migrations (name, applied_at)"
+                     " VALUES (:name, :ts)"),
+                {"name": base, "ts": time.time()},
+            )
+        applied.append(base)
+    return applied
+
+
+def _discover_migrations() -> list[tuple[str, Path]]:
+    """Return [(base_name, path)] sorted by base name.
+
+    For each base name, the file suffixed with the current dialect
+    (.pg.sql / .sqlite.sql) is preferred over the shared .sql one. A base
+    that only ships the OTHER dialect's file is an error — migrations must
+    cover whichever dialect the deployment runs on.
+    """
+    if not MIGRATIONS_DIR.is_dir():
+        return []
+    dialect = "pg" if is_postgres() else "sqlite"
+    by_base: dict[str, dict[str | None, Path]] = {}
+    for p in MIGRATIONS_DIR.iterdir():
+        m = _MIGRATION_RE.match(p.name)
+        if not m:
+            continue
+        by_base.setdefault(m.group("base"), {})[m.group("dialect")] = p
+
+    out: list[tuple[str, Path]] = []
+    for base in sorted(by_base):
+        files = by_base[base]
+        path = files.get(dialect) or files.get(None)
+        if path is None:
+            raise RuntimeError(
+                f"migration {base!r} has no file for dialect {dialect!r} "
+                f"(found: {sorted(p.name for p in files.values())})"
+            )
+        out.append((base, path))
+    return out
+
+
+def _split_statements(sql: str) -> list[str]:
+    """Split migration SQL into individual statements.
+
+    If the file contains any line that is exactly `--;;`, those lines are the
+    only separators (lets trigger/function bodies keep their internal ';').
+    Otherwise the file is split on top-level ';' — ignoring ';' inside `--`
+    line comments, `/* */` block comments, and 'quoted strings'. Files with
+    BEGIN...END trigger bodies or $$-quoted function bodies MUST use the
+    marker. Chunks that are empty or comment-only are dropped.
+    """
+    lines = sql.splitlines()
+    if any(line.strip() == STATEMENT_MARKER for line in lines):
+        chunks: list[str] = []
+        current: list[str] = []
+        for line in lines:
+            if line.strip() == STATEMENT_MARKER:
+                chunks.append("\n".join(current))
+                current = []
+            else:
+                current.append(line)
+        chunks.append("\n".join(current))
+    else:
+        chunks = _split_on_semicolons(sql)
+
+    statements: list[str] = []
+    for chunk in chunks:
+        meaningful = "\n".join(
+            line for line in chunk.splitlines()
+            if line.strip() and not line.strip().startswith("--")
+        )
+        if meaningful.strip():
+            statements.append(chunk.strip())
+    return statements
+
+
+def _split_on_semicolons(sql: str) -> list[str]:
+    """Split on ';' outside comments and string literals (both dialects)."""
+    chunks: list[str] = []
+    buf: list[str] = []
+    i, n = 0, len(sql)
+    while i < n:
+        two = sql[i:i + 2]
+        if two == "--":  # line comment — runs to end of line
+            j = sql.find("\n", i)
+            j = n if j == -1 else j
+            buf.append(sql[i:j])
+            i = j
+        elif two == "/*":  # block comment
+            j = sql.find("*/", i + 2)
+            j = n if j == -1 else j + 2
+            buf.append(sql[i:j])
+            i = j
+        elif sql[i] == "'":  # string literal ('' is the escaped quote)
+            j = i + 1
+            while j < n:
+                if sql[j] == "'":
+                    if sql[j + 1:j + 2] == "'":
+                        j += 2
+                        continue
+                    break
+                j += 1
+            j = min(j + 1, n)
+            buf.append(sql[i:j])
+            i = j
+        elif sql[i] == ";":
+            chunks.append("".join(buf))
+            buf = []
+            i += 1
+        else:
+            buf.append(sql[i])
+            i += 1
+    chunks.append("".join(buf))
+    return chunks

atp/exams.py

@@ -0,0 +1,435 @@
+"""
+atp/exams.py — Phase 3 certification engine (docs/HARDENING.md).
+
+Turns the ATP standard's promises (docs/ATP.md §2) into enforced code:
+
+  blueprint → item bank (atp/items/<cert_id>.json, human-editable)
+            → candidate answers via agents.backend.get_backend(candidate_spec)
+            → judge from a DIFFERENT model family — family_of(judge) !=
+              family_of(candidate) is checked BEFORE any model call, else
+              SeparationError (principle 2)
+            → verdict vs the cert's passCriteria (overall + perSection)
+            → evidence rows, append-only + HMAC-signed with a per-org
+              prev_hash chain via atp/signing.py (principles 1 & 3)
+            → award row in atp_cert_awards.
+
+Reproducibility semantics: every evidence payload records the cert's
+passCriteria seed and temperature (0). Backends are expected to decode
+deterministically (greedy/temperature-0 — the HF/local backends already pin
+do_sample=False / temperature 0.0); a run's `runs` repeats exist to surface
+any residual nondeterminism, and each repeat's judged score is kept in
+run_scores with the item score as their mean. runs = min(passCriteria.runs, 3)
+to keep real exams affordable.
+
+Dry-run mode (CI): `dry_run=True` routes the judge to 'dryrun:judge' and a
+missing candidate to 'dryrun:candidate' — both DryRunBackend, deterministic
+pure functions of the prompts, mapped to distinct synthetic families so the
+separation check passes. Same inputs → same payloads → same sigs (given the
+same EVIDENCE_SIGNING_KEY and chain position).
+
+All DB access goes through atp/tenant_db.py (org-scoped; RLS on Postgres).
+
+Public:
+    run_exam(cert_id, candidate_spec=None, org_id='org-demo',
+             dry_run=False, agent_id=None) -> award dict
+    SeparationError / UnknownCertError / MissingItemBankError
+
+CLI:
+    BU_AUTH_DISABLED=1 python3 -m atp.exams atp-l4-math --dry-run --verify-chain
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from pathlib import Path
+
+from agents.backend import family_of, get_backend
+from atp import db, signing, store, tenant_db
+
+ITEMS_DIR = Path(__file__).parent / "items"
+HARNESS_VERSION = "atp-exams@2026.1-p3"
+DEFAULT_JUDGE_SPEC = "claude-haiku-4-5"   # env ATP_JUDGE_SPEC overrides
+MAX_RUNS = 3                              # cap on passCriteria.runs per item
+
+_ITEM_KEYS = ("id", "section", "type", "prompt", "expected", "points")
+
+_MIGRATED = False
+_MIGRATE_LOCK = threading.Lock()
+
+
+class SeparationError(RuntimeError):
+    """Judge and candidate resolve to the same model family (principle 2)."""
+
+
+class UnknownCertError(ValueError):
+    """cert_id does not exist in the seed (atp/seed.py CERTS)."""
+
+
+class MissingItemBankError(FileNotFoundError):
+    """No usable item bank for the cert — blueprints-before-commissioning."""
+
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _ensure_db() -> None:
+    """Idempotently apply migrations so a fresh SQLite file just works."""
+    global _MIGRATED
+    if _MIGRATED:
+        return
+    with _MIGRATE_LOCK:
+        if not _MIGRATED:
+            db.run_migrations()
+            _MIGRATED = True
+
+
+# ── Cert + item bank loading ─────────────────────────────────────────────────
+
+#: Phase 6 extension point (docs/HARDENING.md — first-customer UX).
+#: Cert refs of the form f"{ORG_CERT_PREFIX}<draft_id>" resolve through
+#: atp/knowledge.py: SME-approved company-knowledge drafts whose item banks
+#: are T2 (encrypted at rest, docs/TENANCY.md) and are therefore materialized
+#: IN MEMORY — never written under atp/items/ or any shared directory.
+#: Plain cert ids keep the pre-Phase-6 seed + items-file behavior unchanged;
+#: callers that don't pass org_id (or deployments without atp/knowledge.py)
+#: are byte-for-byte the old path. Must equal knowledge.EXAM_CERT_PREFIX.
+ORG_CERT_PREFIX = "org-l5-draft:"
+
+
+def _org_bank(cert_id: str, org_id: str | None) -> dict | None:
+    """Resolve an org-scoped draft bank, or None for the classic path."""
+    if not org_id or not cert_id.startswith(ORG_CERT_PREFIX):
+        return None
+    try:
+        from atp import knowledge  # lazy — optional Phase 6 module
+    except ImportError:  # pragma: no cover — knowledge not deployed
+        return None
+    return knowledge.load_org_item_bank(org_id, cert_id)
+
+
+def _load_cert(cert_id: str, org_id: str | None = None) -> dict:
+    org_bank = _org_bank(cert_id, org_id)
+    if org_bank is not None:
+        return org_bank["cert"]
+    if cert_id.startswith(ORG_CERT_PREFIX):
+        # Same error whether the draft is unknown, unapproved, or belongs to
+        # another org — no cross-tenant existence oracle (TENANCY.md #6).
+        raise UnknownCertError(
+            f"unknown cert {cert_id!r} — no SME-approved company-knowledge "
+            f"draft with this ref in the caller's org (atp/knowledge.py)"
+        )
+    for cert in store.get_data()["CERTS"]:
+        if cert["id"] == cert_id:
+            return cert
+    raise UnknownCertError(
+        f"unknown cert {cert_id!r} — certs are defined in atp/seed.py CERTS"
+    )
+
+
+def _load_item_bank(cert: dict, org_id: str | None = None) -> list[dict]:
+    """Load + validate the cert's item bank against its blueprint.
+
+    Classic path: atp/items/<cert_id>.json. Phase 6 org path (ORG_CERT_PREFIX
+    refs + org_id): the in-memory bank from atp/knowledge.py — same
+    validation, same errors.
+    """
+    cert_id = cert["id"]
+    org_bank = _org_bank(cert_id, org_id)
+    if org_bank is not None:
+        source = f"org bank {cert_id}"
+        items = org_bank.get("items") or []
+        if not items:
+            raise MissingItemBankError(f"item bank {source} has an empty 'items' list")
+    else:
+        path = ITEMS_DIR / f"{cert_id}.json"
+        if not path.is_file():
+            raise MissingItemBankError(
+                f"no item bank at {path} — a cert cannot be examined before its "
+                f"blueprint has a bank (blueprints-before-commissioning, "
+                f"docs/ATP.md §7). See atp/items/README.md."
+            )
+        bank = json.loads(path.read_text(encoding="utf-8"))
+        items = bank.get("items") or []
+        if not items:
+            raise MissingItemBankError(f"item bank {path} has an empty 'items' list")
+        source = str(path)
+
+    section_names = {s["name"] for s in cert["blueprint"]["sections"]}
+    for item in items:
+        missing = [k for k in _ITEM_KEYS if k not in item]
+        if missing:
+            raise ValueError(
+                f"item bank {source}: item {item.get('id', '?')!r} is missing "
+                f"key(s) {missing} (format: atp/items/README.md)"
+            )
+        if item["section"] not in section_names:
+            raise ValueError(
+                f"item bank {source}: item {item['id']!r} names unknown section "
+                f"{item['section']!r} — blueprint sections are "
+                f"{sorted(section_names)}"
+            )
+    uncovered = section_names - {i["section"] for i in items}
+    if uncovered:
+        raise ValueError(
+            f"item bank {source} has no items for blueprint section(s) "
+            f"{sorted(uncovered)} — passCriteria.perSection would be "
+            f"unverifiable"
+        )
+    return items
+
+
+# ── Judge prompt + defensive parsing ─────────────────────────────────────────
+
+_JUDGE_SYSTEM = (
+    "You are the certification judge for the ATP (Agentic Training Platform) "
+    "exam harness. Grade the candidate's answer strictly against the "
+    "reference answer/criteria and the rubric. Respond with ONLY a strict "
+    "JSON object — no prose, no code fences: "
+    '{"score": <float between 0 and 1>, "rationale": "<one short sentence>"}'
+)
+_JUDGE_SYSTEM_RETRY = (
+    _JUDGE_SYSTEM
+    + " Your previous reply was not parseable JSON. Output the JSON object "
+      "and NOTHING else."
+)
+
+
+def _judge_user(cert: dict, item: dict, answer: str) -> str:
+    rubric = "; ".join(
+        f"{r['axis']} (weight {r['weight']}): {r['desc']}"
+        for r in cert.get("rubric", [])
+    )
+    return (
+        f"Exam: {cert['label']}\n"
+        f"Rubric: {rubric}\n\n"
+        f"Question [{item['section']} / {item['type']}]:\n{item['prompt']}\n\n"
+        f"Reference answer / grading criteria (not shown to candidate):\n"
+        f"{item['expected']}\n\n"
+        f"Candidate answer:\n{answer}\n\n"
+        'Return strict JSON only: {"score": <float 0..1>, "rationale": "<one sentence>"}'
+    )
+
+
+def _parse_judge(raw: str) -> dict | None:
+    """Defensive parse: first '{' .. last '}', score must be a number in 0..1."""
+    try:
+        start = raw.index("{")
+        end = raw.rindex("}") + 1
+        obj = json.loads(raw[start:end])
+        score = float(obj["score"])
+    except (ValueError, KeyError, TypeError, AttributeError):
+        return None
+    if not (0.0 <= score <= 1.0):
+        return None
+    return {"score": score, "rationale": str(obj.get("rationale", ""))}
+
+
+# ── Evidence writing (signed, chained, org-scoped) ───────────────────────────
+# All evidence rows for a run are accumulated in memory during the (slow)
+# model-call loop and appended in ONE signing.append_chain() call — a single
+# serialized transaction, so concurrent runs can't interleave the chain and
+# a crash mid-run leaves no partially signed exam on disk.
+
+
+# ── The exam loop ────────────────────────────────────────────────────────────
+
+def run_exam(cert_id: str, candidate_spec: str | None = None,
+             org_id: str = tenant_db.DEFAULT_ORG, dry_run: bool = False,
+             agent_id: str | None = None) -> dict:
+    """Run a full certification exam and return the award dict.
+
+    Raises UnknownCertError / MissingItemBankError / SeparationError before
+    any model call; SigningKeyError surfaces from atp/signing.py if evidence
+    cannot be signed.
+    """
+    # org_id also feeds the Phase 6 loader path (ORG_CERT_PREFIX refs only;
+    # seed cert ids are unaffected by the extra argument).
+    cert = _load_cert(cert_id, org_id)
+    items = _load_item_bank(cert, org_id)
+
+    candidate = candidate_spec or "dryrun:candidate"
+    judge = "dryrun:judge" if dry_run else os.environ.get(
+        "ATP_JUDGE_SPEC", DEFAULT_JUDGE_SPEC)
+
+    # Principle 2 — judge/candidate separation, enforced BEFORE any model call.
+    if family_of(judge) == family_of(candidate):
+        raise SeparationError(
+            f"judge/candidate separation violated: judge {judge!r} and "
+            f"candidate {candidate!r} both resolve to model family "
+            f"{family_of(judge)!r} (docs/ATP.md §2 principle 2). Set "
+            f"ATP_JUDGE_SPEC to a different family, or pass a different "
+            f"candidate."
+        )
+
+    pc = cert["passCriteria"]
+    runs = max(1, min(int(pc.get("runs", 1)), MAX_RUNS))
+    seed = int(pc.get("seed", 0))
+    temperature = pc.get("temperature", 0)
+
+    _ensure_db()
+    candidate_backend = get_backend(candidate)
+    judge_backend = get_backend(judge)
+
+    candidate_system = (
+        f"You are sitting the {cert['label']} certification exam "
+        f"({cert['domain']}, layer L{cert['layer']}). Answer each question "
+        f"precisely and show your work. Reproducibility: decoding is pinned "
+        f"to temperature {temperature}, seed {seed} "
+        f"(harness {HARNESS_VERSION})."
+    )
+
+    agent = agent_id or candidate
+    ev_records: list[dict] = []          # appended to the chain in one txn
+    graded: list[tuple[dict, list[float], bool]] = []
+
+    for item in items:
+        run_scores: list[float] = []
+        flagged = False
+        for _ in range(runs):
+            answer = candidate_backend.complete(
+                candidate_system, item["prompt"], max_tokens=800)
+            judge_prompt = _judge_user(cert, item, answer)
+            verdict = _parse_judge(
+                judge_backend.complete(_JUDGE_SYSTEM, judge_prompt,
+                                       max_tokens=300))
+            if verdict is None:   # retry once, stricter instruction
+                verdict = _parse_judge(
+                    judge_backend.complete(_JUDGE_SYSTEM_RETRY, judge_prompt,
+                                           max_tokens=300))
+            if verdict is None:   # still unparseable → item flagged
+                flagged = True
+                run_scores.append(0.0)
+            else:
+                run_scores.append(round(verdict["score"], 4))
+
+        payload = {
+            "certId": cert_id,
+            "itemId": item["id"],
+            "run_scores": run_scores,
+            "judge": judge,
+            "candidate": candidate,
+            "seed": seed,
+            "temperature": temperature,
+        }
+        ev_records.append({"ts": _now(), "agent_id": agent,
+                           "cert_id": cert_id, "kind": "exam_item",
+                           "payload": payload})
+        graded.append((item, run_scores, flagged))
+
+    # ── Aggregate: points-weighted per section, blueprint-weighted overall ──
+    item_bar = float(pc.get("perSection", 0.7))   # per-item pass bar
+    per_section: dict[str, list[tuple[float, float]]] = {}
+    breakdown = {"passed": 0, "failed": 0, "flagged": 0}
+    for item, run_scores, flagged in graded:
+        mean = sum(run_scores) / len(run_scores)
+        per_section.setdefault(item["section"], []).append(
+            (mean, float(item["points"])))
+        if flagged:
+            breakdown["flagged"] += 1
+        elif mean >= item_bar:
+            breakdown["passed"] += 1
+        else:
+            breakdown["failed"] += 1
+
+    section_scores = {
+        name: round(sum(s * p for s, p in vals) / sum(p for _, p in vals), 4)
+        for name, vals in per_section.items()
+    }
+    weights = {s["name"]: float(s["weight"])
+               for s in cert["blueprint"]["sections"]}
+    weight_sum = sum(weights[name] for name in section_scores)
+    overall = round(
+        sum(section_scores[name] * weights[name] for name in section_scores)
+        / weight_sum, 4)
+
+    verdict_str = (
+        "pass"
+        if overall >= float(pc["overall"])
+        and all(v >= float(pc["perSection"]) for v in section_scores.values())
+        and breakdown["flagged"] == 0
+        else "fail"
+    )
+
+    # ── Summary evidence row (kind=benchmark_run) ───────────────────────────
+    summary_payload = {
+        "certId": cert_id,
+        "overall": overall,
+        "sectionScores": section_scores,
+        "verdict": verdict_str,
+        "itemBreakdown": breakdown,
+        "judge": judge,
+        "candidate": candidate,
+        "seed": seed,
+        "temperature": temperature,
+        "runs": runs,
+        "harness": HARNESS_VERSION,
+    }
+    ev_records.append({"ts": _now(), "agent_id": agent, "cert_id": cert_id,
+                       "kind": "benchmark_run", "payload": summary_payload})
+
+    # One serialized, atomic chain append for the whole run.
+    evidence_ids = [row_id for row_id, _sig in
+                    signing.append_chain(org_id, ev_records)]
+
+    # ── Award row ───────────────────────────────────────────────────────────
+    ts = _now()
+    res = tenant_db.insert_scoped("atp_cert_awards", {
+        "ts": ts,
+        "agent_id": agent,
+        "cert_id": cert_id,
+        "score": overall,
+        "section_scores": json.dumps(section_scores, sort_keys=True),
+        "item_breakdown": json.dumps(breakdown, sort_keys=True),
+        "evidence_ids": json.dumps(evidence_ids),
+    }, org_id)
+
+    return {
+        "agentId": agent,
+        "certId": cert_id,
+        "ts": ts,
+        "score": overall,
+        "verdict": verdict_str,
+        "sectionScores": section_scores,
+        "itemBreakdown": breakdown,
+        "evidenceIds": evidence_ids,
+        "judge": judge,
+        "candidate": candidate,
+        "runs": runs,
+        "seed": seed,
+        "temperature": temperature,
+        "harness": HARNESS_VERSION,
+        "awardRowId": res.lastrowid,
+        "dryRun": bool(dry_run),
+    }
+
+
+# ── CLI ──────────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Run an ATP certification exam (Phase 3 engine).")
+    parser.add_argument("cert_id", help="e.g. atp-l4-math")
+    parser.add_argument("--candidate", default=None,
+                        help="candidate backend spec (default: dryrun:candidate)")
+    parser.add_argument("--org", default=tenant_db.DEFAULT_ORG)
+    parser.add_argument("--agent-id", default=None,
+                        help="agent id recorded on evidence/award rows "
+                             "(default: the candidate spec)")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="deterministic stub judge/candidate — no model "
+                             "calls, no cost (CI mode)")
+    parser.add_argument("--verify-chain", action="store_true",
+                        help="verify the org's evidence chain after the run")
+    args = parser.parse_args()
+
+    award = run_exam(args.cert_id, args.candidate, org_id=args.org,
+                     dry_run=args.dry_run, agent_id=args.agent_id)
+    print(json.dumps(award, indent=2))
+    if args.verify_chain:
+        print(json.dumps(signing.verify_chain(args.org), indent=2))

atp/items/README.md

@@ -0,0 +1,63 @@
+# ATP item banks — `atp/items/*.json`
+
+One JSON file per certification, named exactly after the cert id in
+`atp/seed.py` (e.g. `atp-l4-math.json` for cert `atp-l4-math`). These are the
+concrete exam questions behind each cert's blueprint. They are **generated +
+human-editable**: SMEs edit these files directly; no build step.
+
+**Blueprints-before-commissioning invariant** (docs/ATP.md §7): an exam can
+only run for a cert whose item bank exists — `atp/exams.py` raises
+`MissingItemBankError` otherwise. Adding a cert to the seed without adding its
+bank here means it cannot be examined, by design.
+
+## File format
+
+```json
+{
+  "certId":  "atp-l4-math",          // must equal the filename + seed cert id
+  "label":   "ATP-L4.math@2026.1",   // cosmetic, copied from the cert
+  "version": "2026.1",               // bump when the bank changes materially
+  "notes":   "free-text for SMEs",
+  "items":   [ ... ]                 // the bank — see below
+}
+```
+
+Each item:
+
+| key        | type   | meaning |
+|------------|--------|---------|
+| `id`       | str    | stable unique id, `<cert-shorthand>-<sec>-NN` (e.g. `l4m-sym-01`). Never reuse or renumber a shipped id — evidence rows reference it forever. |
+| `section`  | str    | MUST match one of the cert blueprint's `sections[].name` in `atp/seed.py` **verbatim** (copy-paste it). Unknown sections fail exam load. |
+| `type`     | str    | one of `recall` \| `apply` \| `synthesize` \| `adversarial`, and it should be one of that section's `itemTypes` in the blueprint. |
+| `prompt`   | str    | the question exactly as shown to the candidate model. Self-contained: include any passage/data inline. |
+| `expected` | str    | reference answer **and/or grading criteria** for the judge model. State what full credit requires and name known-wrong answers where useful. Never shown to the candidate. |
+| `points`   | int    | weight of the item *within its section* (section scores are points-weighted; sections are then combined by the blueprint's section weights). |
+
+## Validation at exam load (`atp/exams.py`)
+
+* file exists and has a non-empty `items` list;
+* every item carries all six keys;
+* every item's `section` is a blueprint section of the cert;
+* every blueprint section has at least one item (otherwise the
+  `passCriteria.perSection` bar would be unverifiable).
+
+## How SMEs edit
+
+1. Edit the cert's JSON in place (any editor; keep it valid JSON — trailing
+   commas are not).
+2. **Add** items freely (new ids, correct `section`/`type`); **retire** items
+   by deleting them — but never recycle a deleted id.
+3. Keep `expected` judge-ready: it is pasted into the judge prompt as the
+   reference. Write criteria ("full credit requires…"), not just an answer,
+   for synthesize/adversarial items.
+4. Adversarial items should contain a trap (flawed premise, tempting wrong
+   method) and `expected` must say what falling into the trap looks like.
+5. Bump `version`, then sanity-check with a dry run (no model calls, no cost):
+
+   ```bash
+   BU_AUTH_DISABLED=1 python3 -m atp.exams atp-l4-math --dry-run --verify-chain
+   ```
+
+L5 (company-knowledge) banks additionally require SME sign-off on the cert
+itself (`smeSignoff` in `atp/seed.py`) before awards are meaningful — the
+bank alone is not enough (docs/ATP.md §1, L5 row).

atp/items/atp-l1-core.json

@@ -0,0 +1,96 @@
+{
+  "certId": "atp-l1-core",
+  "label": "ATP-L1.core@2026.1",
+  "version": "2026.1",
+  "notes": "Item bank for the L1 Core Skills cert (Exeter-modeled K-12 competencies). Sections MUST match the cert blueprint in atp/seed.py verbatim. See atp/items/README.md for the format and editing rules.",
+  "items": [
+    {
+      "id": "l1c-num-01",
+      "section": "Numeracy",
+      "type": "recall",
+      "prompt": "What is 7 x 8?",
+      "expected": "56. Exact answer required.",
+      "points": 1
+    },
+    {
+      "id": "l1c-num-02",
+      "section": "Numeracy",
+      "type": "apply",
+      "prompt": "Compute 3/4 + 1/6, giving the answer as a fraction in lowest terms. Show the common-denominator step.",
+      "expected": "11/12. Common denominator 12: 3/4 = 9/12 and 1/6 = 2/12, so 9/12 + 2/12 = 11/12 (already in lowest terms). The common-denominator step must be shown.",
+      "points": 2
+    },
+    {
+      "id": "l1c-num-03",
+      "section": "Numeracy",
+      "type": "apply",
+      "prompt": "A jacket costs $80 and is discounted by 15%. What is the sale price? Show the calculation.",
+      "expected": "$68. Discount is 0.15 x 80 = $12, so 80 - 12 = 68 (equivalently 0.85 x 80). The working must be shown, not just the final number.",
+      "points": 2
+    },
+    {
+      "id": "l1c-red-01",
+      "section": "Reading comprehension",
+      "type": "recall",
+      "prompt": "Passage: 'Honeybees tell hive-mates where food is through a waggle dance. The angle of the dance relative to vertical encodes the direction of the food relative to the sun, while the duration of the waggle encodes the distance.' Question: according to the passage, what does the DURATION of the waggle encode?",
+      "expected": "The distance to the food. (Direction is encoded by the angle, not the duration — answers citing direction are wrong.)",
+      "points": 1
+    },
+    {
+      "id": "l1c-red-02",
+      "section": "Reading comprehension",
+      "type": "apply",
+      "prompt": "Passage: 'Maria watered her ferns every morning, yet their leaves kept yellowing. When she finally moved the pots away from the bright south-facing window, the ferns recovered within two weeks — same watering schedule as before.' Question: what most likely caused the yellowing, and which detail in the passage supports that inference?",
+      "expected": "Too much direct sunlight (not under-watering): the ferns recovered when moved away from the bright window while the watering schedule stayed identical, so light exposure is the variable that changed. Both the inference and the supporting detail are required.",
+      "points": 2
+    },
+    {
+      "id": "l1c-red-03",
+      "section": "Reading comprehension",
+      "type": "apply",
+      "prompt": "Passage: 'The town library began opening on Sundays last year. Weekend visits doubled, late returns fell by a third, and — to the surprise of the council — weekday visits rose too, as families who discovered the library on Sundays started coming back midweek.' Question: state the main idea of the passage in one sentence.",
+      "expected": "Opening the library on Sundays improved usage overall — not just on weekends, but on weekdays as well. A main-idea answer must cover the spillover effect; restating only one statistic is insufficient.",
+      "points": 2
+    },
+    {
+      "id": "l1c-cmp-01",
+      "section": "Composition",
+      "type": "synthesize",
+      "prompt": "Write a paragraph of exactly three sentences arguing that schools should have vegetable gardens. Sentence 1 must state the claim, sentence 2 must give one concrete supporting reason, sentence 3 must conclude.",
+      "expected": "Grading criteria, not a fixed text: (1) exactly three sentences; (2) first sentence states the claim plainly; (3) second sentence gives one concrete, relevant reason (e.g. hands-on science learning, nutrition); (4) third sentence concludes without introducing a new argument. Grammatical, coherent prose.",
+      "points": 3
+    },
+    {
+      "id": "l1c-cmp-02",
+      "section": "Composition",
+      "type": "synthesize",
+      "prompt": "Rewrite this run-on sentence as correct English, preserving all of its information: 'The experiment failed we forgot to label the samples so we had to start over.'",
+      "expected": "Any grammatical fix that keeps all three facts, e.g. 'The experiment failed because we forgot to label the samples, so we had to start over.' or 'The experiment failed. We had forgotten to label the samples, so we had to start over.' Must eliminate the comma-splice/run-on and preserve failure, cause, and restart.",
+      "points": 2
+    },
+    {
+      "id": "l1c-sci-01",
+      "section": "Scientific & chronological reasoning",
+      "type": "apply",
+      "prompt": "A student wants to test whether a fertilizer makes bean plants grow taller. She plants 10 beans with fertilizer and 10 beans without, keeping light, water, soil, and pot size identical for all 20. Which group is the control, and why is it needed?",
+      "expected": "The 10 plants WITHOUT fertilizer are the control group. It is needed as the baseline: without it, any growth in the fertilized group could not be attributed to the fertilizer rather than to the shared conditions. Both identification and justification required.",
+      "points": 2
+    },
+    {
+      "id": "l1c-sci-02",
+      "section": "Scientific & chronological reasoning",
+      "type": "adversarial",
+      "prompt": "In summer, both ice-cream sales and drowning deaths rise sharply, and the two track each other closely all year. A report concludes that ice cream causes drowning. Explain the error in this conclusion and identify the more plausible explanation.",
+      "expected": "Correlation is not causation: both variables are driven by a confounding third factor — hot weather brings more swimming (hence more drownings) AND more ice-cream sales. The answer must name the confounder (season/heat) and reject the causal claim; simply saying 'correlation isn't causation' without the confounder is partial credit at best.",
+      "points": 3
+    },
+    {
+      "id": "l1c-sci-03",
+      "section": "Scientific & chronological reasoning",
+      "type": "apply",
+      "prompt": "Place these four events in chronological order, earliest first: the first telephone call (Bell), the moon landing, the printing press (Gutenberg), the first public telegraph line (Morse).",
+      "expected": "Printing press (c. 1440) -> telegraph (1844) -> telephone (1876) -> moon landing (1969). All four in the correct order required; exact years are not required but wreck nothing if given correctly.",
+      "points": 2
+    }
+  ]
+}

atp/items/atp-l4-math.json

@@ -0,0 +1,152 @@
+{
+  "certId": "atp-l4-math",
+  "label": "ATP-L4.math@2026.1",
+  "version": "2026.1",
+  "notes": "Item bank for the L4 Math cert (world-knowledge engines: CAS interop). Sections MUST match the cert blueprint in atp/seed.py verbatim. See atp/items/README.md for the format and editing rules.",
+  "items": [
+    {
+      "id": "l4m-sym-01",
+      "section": "Symbolic manipulation (CAS interop)",
+      "type": "apply",
+      "prompt": "Expand (x + 2)^3 completely. Show the intermediate binomial steps.",
+      "expected": "x^3 + 6x^2 + 12x + 8. Full credit requires the binomial expansion steps (coefficients 1,3,3,1 with powers of 2) or an equivalent two-stage multiplication.",
+      "points": 2
+    },
+    {
+      "id": "l4m-sym-02",
+      "section": "Symbolic manipulation (CAS interop)",
+      "type": "apply",
+      "prompt": "Factor x^4 - 5x^2 + 4 completely over the integers.",
+      "expected": "(x - 1)(x + 1)(x - 2)(x + 2). Substitution u = x^2 gives (u - 1)(u - 4), then each difference of squares splits. All four linear factors required.",
+      "points": 2
+    },
+    {
+      "id": "l4m-sym-03",
+      "section": "Symbolic manipulation (CAS interop)",
+      "type": "apply",
+      "prompt": "Simplify the rational expression (x^2 - 9) / (x^2 - x - 6) and state every excluded value of x.",
+      "expected": "(x + 3)/(x + 2), with x != 3 and x != -2 excluded (zeros of the ORIGINAL denominator). Numerator factors as (x-3)(x+3), denominator as (x-3)(x+2). Both exclusions must be stated.",
+      "points": 3
+    },
+    {
+      "id": "l4m-sym-04",
+      "section": "Symbolic manipulation (CAS interop)",
+      "type": "apply",
+      "prompt": "Decompose (3x + 5) / ((x + 1)(x + 2)) into partial fractions.",
+      "expected": "2/(x + 1) + 1/(x + 2). Setting 3x + 5 = A(x + 2) + B(x + 1): x = -1 gives A = 2, x = -2 gives B = 1.",
+      "points": 3
+    },
+    {
+      "id": "l4m-sym-05",
+      "section": "Symbolic manipulation (CAS interop)",
+      "type": "apply",
+      "prompt": "Differentiate f(x) = x^2 sin(x) with respect to x, naming the rule used.",
+      "expected": "f'(x) = 2x sin(x) + x^2 cos(x), by the product rule. Both terms required; naming the product rule required for full rigor credit.",
+      "points": 2
+    },
+    {
+      "id": "l4m-prf-01",
+      "section": "Proof & synthesis",
+      "type": "synthesize",
+      "prompt": "Prove that sqrt(2) is irrational.",
+      "expected": "Proof by contradiction: assume sqrt(2) = p/q in lowest terms, so p^2 = 2q^2, hence p is even (p = 2k), then 4k^2 = 2q^2 gives q^2 = 2k^2 so q is also even — contradicting lowest terms. Must state the lowest-terms assumption and derive the parity contradiction; no skipped steps.",
+      "points": 4
+    },
+    {
+      "id": "l4m-prf-02",
+      "section": "Proof & synthesis",
+      "type": "synthesize",
+      "prompt": "Prove by mathematical induction that 1 + 3 + 5 + ... + (2n - 1) = n^2 for all integers n >= 1.",
+      "expected": "Base case n = 1: LHS = 1 = 1^2. Inductive step: assume sum to k terms = k^2; adding the next odd number (2k + 1) gives k^2 + 2k + 1 = (k + 1)^2. Both the base case and an explicitly stated inductive hypothesis are required.",
+      "points": 4
+    },
+    {
+      "id": "l4m-prf-03",
+      "section": "Proof & synthesis",
+      "type": "adversarial",
+      "prompt": "Claim: if f is differentiable and f'(c) = 0, then f has a local maximum or local minimum at c. Prove the claim or refute it.",
+      "expected": "The claim is FALSE. Counterexample: f(x) = x^3 at c = 0 has f'(0) = 0 but is strictly increasing, so x = 0 is neither a local max nor a local min (it is an inflection point). A single valid counterexample suffices; a 'proof' of the claim scores 0 on correctness.",
+      "points": 4
+    },
+    {
+      "id": "l4m-prf-04",
+      "section": "Proof & synthesis",
+      "type": "adversarial",
+      "prompt": "The following argument concludes 2 = 1. Identify the exact flawed step and explain why it is invalid. Let a = b. Then a^2 = ab; a^2 - b^2 = ab - b^2; (a - b)(a + b) = b(a - b); a + b = b; 2b = b; therefore 2 = 1.",
+      "expected": "The step dividing both sides by (a - b) is invalid: since a = b, a - b = 0, and division by zero is undefined. Every other step is legal. The answer must locate the cancellation of (a - b) specifically, not just say 'division by zero somewhere'.",
+      "points": 3
+    },
+    {
+      "id": "l4m-prf-05",
+      "section": "Proof & synthesis",
+      "type": "synthesize",
+      "prompt": "Prove that there are infinitely many prime numbers.",
+      "expected": "Euclid's argument: suppose p1..pk were all the primes; let N = p1*p2*...*pk + 1. N leaves remainder 1 on division by every pi, so any prime factor of N (which exists since N > 1) is a prime not in the list — contradiction. Must note N need not itself be prime, only that its prime factor is new.",
+      "points": 4
+    },
+    {
+      "id": "l4m-eng-01",
+      "section": "Engine tool-use (SymPy/CAS)",
+      "type": "apply",
+      "prompt": "Write the exact SymPy code to solve x^2 - 5x + 6 = 0 for x, and state the result the engine returns.",
+      "expected": "import sympy; x = sympy.symbols('x'); sympy.solve(x**2 - 5*x + 6, x) — returns [2, 3]. Code must be runnable (symbol declared, correct API) and the reported roots must be exactly 2 and 3.",
+      "points": 3
+    },
+    {
+      "id": "l4m-eng-02",
+      "section": "Engine tool-use (SymPy/CAS)",
+      "type": "apply",
+      "prompt": "Using SymPy, compute the indefinite integral of x*exp(x) with respect to x. Give the code and the engine's result.",
+      "expected": "sympy.integrate(x*sympy.exp(x), x) returns (x - 1)*exp(x). Answer must report the engine output faithfully — writing x*exp(x) - exp(x) is equivalent and acceptable; omitting the code or misreading the result is not.",
+      "points": 3
+    },
+    {
+      "id": "l4m-eng-03",
+      "section": "Engine tool-use (SymPy/CAS)",
+      "type": "apply",
+      "prompt": "Using SymPy, evaluate the limit of sin(x)/x as x approaches 0. Give the code and the result.",
+      "expected": "sympy.limit(sympy.sin(x)/x, x, 0) returns 1. Full credit requires the limit() call (not a numeric approximation) and the exact value 1.",
+      "points": 2
+    },
+    {
+      "id": "l4m-eng-04",
+      "section": "Engine tool-use (SymPy/CAS)",
+      "type": "apply",
+      "prompt": "Using SymPy's Matrix class, invert the matrix [[2, 1], [1, 1]]. Give the code and the exact inverse.",
+      "expected": "sympy.Matrix([[2, 1], [1, 1]]).inv() returns Matrix([[1, -1], [-1, 2]]) (determinant is 1). The exact integer inverse is required; a decimal/numeric inverse shows the engine was not used faithfully.",
+      "points": 3
+    },
+    {
+      "id": "l4m-num-01",
+      "section": "Numerical stability",
+      "type": "apply",
+      "prompt": "In float64 arithmetic, computing 1 - cos(x) directly for very small x (say x = 1e-8) loses almost all significant digits. Explain why, and give a numerically stable equivalent expression.",
+      "expected": "Catastrophic cancellation: cos(x) is approximately 1 - x^2/2, so 1 - cos(x) subtracts two nearly equal numbers and the leading digits cancel, leaving only rounding noise. Stable rewrite: 2*sin(x/2)^2 (exactly equal analytically, no subtraction of near-equal quantities).",
+      "points": 3
+    },
+    {
+      "id": "l4m-num-02",
+      "section": "Numerical stability",
+      "type": "adversarial",
+      "prompt": "Solving x^2 - 1e8*x + 1 = 0 with the textbook quadratic formula in float64 returns 0.0 for the small root. Diagnose the failure and give a stable procedure that recovers both roots accurately.",
+      "expected": "For the small root the formula computes (1e8 - sqrt(1e16 - 4))/2: sqrt(1e16 - 4) rounds to 1e8 in float64, so the subtraction cancels catastrophically to 0. Stable: compute the large root x1 = (-b - sign(b)*sqrt(b^2 - 4ac)) / (2a) (no cancellation), then the small root via Vieta: x2 = c/(a*x1) = 1e-8. Both the diagnosis (cancellation in the subtraction) and the Vieta rescue are required.",
+      "points": 4
+    },
+    {
+      "id": "l4m-num-03",
+      "section": "Numerical stability",
+      "type": "adversarial",
+      "prompt": "True or false: IEEE-754 float64 addition is associative. Justify with a concrete counterexample evaluated in float64.",
+      "expected": "False. Counterexample: (1e16 + 1.0) - 1e16 evaluates to 0.0 because 1e16 + 1.0 rounds back to 1e16 (the spacing between adjacent float64 values at 1e16 is 2), while 1e16 - 1e16 + 1.0 evaluates to 1.0. Any counterexample with correct float64 rounding behaviour is acceptable.",
+      "points": 3
+    },
+    {
+      "id": "l4m-num-04",
+      "section": "Numerical stability",
+      "type": "apply",
+      "prompt": "Naive Gaussian elimination WITHOUT pivoting fails badly on the system [[1e-20, 1], [1, 1]] * [x, y] = [1, 2] in float64. Explain the mechanism and name the standard fix.",
+      "expected": "Using the tiny pivot 1e-20 produces the multiplier 1e20; the row update computes 1 - 1e20 which rounds to -1e20, wiping out the original coefficients (the true data is absorbed into rounding error), yielding x = 0 instead of x approximately 1. Fix: partial pivoting — swap rows so the largest-magnitude entry in the column is the pivot, keeping multipliers bounded by 1.",
+      "points": 3
+    }
+  ]
+}

atp/knowledge.py

@@ -0,0 +1,641 @@
+"""
+Company-knowledge ingestion + L5 exam drafting — Phase 6 (docs/HARDENING.md).
+
+Pipeline (first-customer UX contract):
+
+    upload (md/txt/pdf) ──> vault_docs row              [T2: content encrypted]
+                     │
+                     └──> generate_l5_draft()           [deterministic heuristic
+                          blueprint + >=8 items          — NO LLM dependency]
+                     │
+    SME sign-off ────┴──> approve_draft()               ['sme_signoff' evidence
+                          │                              on the signed chain]
+                          └──> load_org_item_bank()     [in-memory bank consumed
+                               by atp/exams.py           via its Phase 6 loader
+                               ORG_CERT_PREFIX path]     -> run_exam -> award
+
+Tenancy & data class (docs/TENANCY.md — T2 "crown jewels"):
+
+  * Every row is org-scoped; all SQL here goes through atp/tenant_db.py
+    scoped helpers and carries a `:org` bind by construction (`_scoped()`
+    below asserts it). vault_docs / l5_drafts are not (yet) listed in
+    tenant_db.TENANT_TABLES — that registry lives in a file owned by the
+    tenancy workstream — so the DAL's parse guard does not fire for them;
+    the local assert plus Postgres FORCE RLS (migration 007) close the gap.
+  * Document content, summaries, and draft ITEMS are encrypted at rest via
+    atp/crypto.py encrypt_for_org (per-org HKDF subkey, 'enc1:' envelope).
+    The draft BLUEPRINT (section names/weights only) stays plaintext so
+    listings render without a decrypt.
+  * Approved banks are materialized IN MEMORY only. They are NEVER written
+    to atp/items/ or any shared directory (leak surfaces #4 and #7: no
+    plaintext T2 on disk, nothing under public media prefixes).
+
+Separation of duties: admins manage docs and drafts; only SMEs sign.
+approve_draft / reject_draft record the reviewer decision as a signed
+'sme_signoff' evidence row (atp/signing.py append_chain), making sign-off
+tamper-evident even though l5_drafts itself is mutable by design.
+
+Public:
+  ingest_doc(org_id, filename, mime, content_bytes, uploaded_by) -> doc dict
+  list_docs(org_id)                          -> [doc dict]  (summaries only)
+  get_doc(org_id, doc_id)                    -> doc dict | None (full text)
+  generate_l5_draft(org_id, doc_ids, created_by, title='') -> draft dict
+  list_drafts(org_id, include_items=False)   -> [draft dict]
+  get_draft(org_id, draft_id, include_items=False) -> draft dict | None
+  approve_draft(org_id, draft_id, reviewer, note='') -> sign-off dict
+  reject_draft(org_id, draft_id, reviewer, note='')  -> sign-off dict
+  load_org_item_bank(org_id, cert_ref)       -> {cert, items} | None
+  UnsupportedDocumentError / KnowledgeError / DraftStateError
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import re
+import threading
+import time
+import uuid
+from pathlib import Path
+
+from atp import crypto, db, signing, tenant_db
+
+#: Cert refs for approved drafts: f"{EXAM_CERT_PREFIX}{draft_id}". Must equal
+#: atp/exams.py ORG_CERT_PREFIX (defined there — the loader checks the prefix
+#: BEFORE importing this module; asserted equal in load_org_item_bank).
+EXAM_CERT_PREFIX = "org-l5-draft:"
+
+#: Seed cert whose passCriteria/rubric an org draft inherits — the L5
+#: company-knowledge archetype in atp/seed.py.
+L5_TEMPLATE_CERT_ID = "atp-l5-company-ops"
+
+SUMMARY_WORDS = 40      # heuristic summary length (first N words)
+MIN_ITEMS = 8           # a draft bank must have at least this many items
+MIN_SECTIONS = 2        # ... spread across at least this many sections
+MAX_UNITS_PER_DOC = 8   # cap: at most this many (heading, passage) units/doc
+MIN_UNIT_CHARS = 40     # passages shorter than this are too thin to examine
+MAX_EXPECTED_CHARS = 1200  # cap pasted passage length in judge references
+
+_MIGRATED = False
+_MIGRATE_LOCK = threading.Lock()
+
+# (org_id, draft_id) -> materialized bank dict. In-memory ONLY (T2: approved
+# banks never land as plaintext on shared disk); repopulated lazily from the
+# encrypted l5_drafts row after a restart. Entries are only ever created for
+# status='approved' drafts, and approve/reject are terminal transitions, so
+# no invalidation is needed.
+_BANK_CACHE: dict[tuple[str, str], dict] = {}
+_BANK_LOCK = threading.Lock()
+
+
+class KnowledgeError(ValueError):
+    """Invalid ingestion/drafting input (unknown doc ids, corpus too thin)."""
+
+
+class UnsupportedDocumentError(KnowledgeError):
+    """Unsupported document type — the API maps this to HTTP 415."""
+
+
+class DraftStateError(RuntimeError):
+    """A draft transition was attempted from the wrong status (HTTP 409)."""
+
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _ensure_db() -> None:
+    """Idempotently apply migrations so a fresh SQLite file just works
+    (same idiom as atp/exams.py)."""
+    global _MIGRATED
+    if _MIGRATED:
+        return
+    with _MIGRATE_LOCK:
+        if not _MIGRATED:
+            db.run_migrations()
+            _MIGRATED = True
+
+
+def _scoped(sql: str) -> str:
+    """Belt-and-braces layer-2 check for THIS module's tenant tables.
+
+    vault_docs / l5_drafts are not in tenant_db.TENANT_TABLES (that frozenset
+    lives in atp/tenant_db.py, owned by the tenancy workstream — follow-up:
+    add both there), so scoped_query/scoped_execute would not force the
+    ':org' bind for them. Assert it locally instead; on Postgres the
+    migration-007 FORCE RLS policies are the deny-by-default backstop.
+    """
+    if ":org" not in sql:
+        raise tenant_db.TenantScopeError(
+            f"knowledge-module statement lacks an ':org' bind: {sql!r}")
+    return sql
+
+
+# ── Text extraction (md/txt native; pdf via pypdf when importable) ──────────
+
+_EXT_KIND = {".md": "md", ".markdown": "md", ".txt": "txt", ".pdf": "pdf"}
+_MIME_KIND = {
+    "text/markdown": "md",
+    "text/x-markdown": "md",
+    "text/plain": "txt",
+    "application/pdf": "pdf",
+}
+
+
+def doc_kind(filename: str | None, mime: str | None) -> str | None:
+    """'md' | 'txt' | 'pdf' from the filename extension (authoritative),
+    falling back to the declared MIME type; None when neither is allowed."""
+    ext = Path(filename or "").suffix.lower()
+    if ext in _EXT_KIND:
+        return _EXT_KIND[ext]
+    if ext:  # an extension we do NOT allow — don't let MIME override it
+        return None
+    return _MIME_KIND.get((mime or "").split(";")[0].strip().lower())
+
+
+def _extract_text(filename: str | None, mime: str | None,
+                  content_bytes: bytes) -> str:
+    kind = doc_kind(filename, mime)
+    if kind is None:
+        raise UnsupportedDocumentError(
+            f"unsupported document type (filename={filename!r}, "
+            f"mime={mime!r}) — allowed: .md, .txt, .pdf")
+    if kind == "pdf":
+        try:
+            from pypdf import PdfReader  # optional dep (requirements.txt)
+        except ImportError:
+            raise UnsupportedDocumentError(
+                "PDF ingestion requires the 'pypdf' package, which is not "
+                "installed on this deployment — upload .md or .txt instead"
+            ) from None
+        try:
+            reader = PdfReader(io.BytesIO(content_bytes))
+            text = "\n\n".join((page.extract_text() or "")
+                               for page in reader.pages)
+        except Exception as e:  # noqa: BLE001 — pypdf raises many types
+            raise KnowledgeError(f"could not parse PDF: {e}") from None
+    else:
+        text = content_bytes.decode("utf-8", errors="replace")
+    text = text.strip()
+    if not text:
+        raise KnowledgeError("document contains no extractable text")
+    return text
+
+
+_HEADING_RE = re.compile(r"^\s{0,3}#{1,6}\s+(?P<h>.+?)\s*#*\s*$")
+
+
+def _title_from(text: str, filename: str | None) -> str:
+    """First markdown heading, else the cleaned filename stem."""
+    for line in text.splitlines()[:20]:
+        m = _HEADING_RE.match(line)
+        if m:
+            return m.group("h").strip()
+    stem = Path(filename or "document").stem
+    return re.sub(r"[_\-]+", " ", stem).strip() or "document"
+
+
+def _summarize(text: str) -> str:
+    """Deterministic heuristic summary: the first SUMMARY_WORDS words of the
+    body (heading markers stripped)."""
+    words = re.sub(r"^\s{0,3}#{1,6}\s+", "", text, flags=re.MULTILINE).split()
+    out = " ".join(words[:SUMMARY_WORDS])
+    return out + (" …" if len(words) > SUMMARY_WORDS else "")
+
+
+def _split_units(text: str) -> list[tuple[str, str]]:
+    """Split a document into (heading, passage) units, deterministically.
+
+    Blocks are separated by blank lines; a block that is a single markdown
+    heading line sets the current heading for the passages that follow.
+    Headingless documents fall back to positional labels ('passage N').
+    Passages shorter than MIN_UNIT_CHARS are skipped as unexaminable.
+    """
+    units: list[tuple[str, str]] = []
+    heading: str | None = None
+    n_anon = 0
+    for block in re.split(r"\n\s*\n", text):
+        block = block.strip()
+        if not block:
+            continue
+        lines = block.splitlines()
+        m = _HEADING_RE.match(lines[0])
+        if m:
+            heading = m.group("h").strip()[:80]
+            block = "\n".join(lines[1:]).strip()
+            if not block:
+                continue
+        if len(block) < MIN_UNIT_CHARS:
+            continue
+        if heading is None:
+            n_anon += 1
+            label = f"passage {n_anon}"
+        else:
+            label = heading
+        units.append((label, block))
+    return units
+
+
+# ── Documents ────────────────────────────────────────────────────────────────
+
+_DOC_LIST_COLS = "id, title, filename, mime, uploaded_by, created_at, status"
+
+
+def _doc_public(row: dict, org_id: str, *, content: bool = False) -> dict:
+    out = {
+        "id":         row["id"],
+        "title":      row["title"],
+        "filename":   row.get("filename"),
+        "mime":       row.get("mime"),
+        "status":     row["status"],
+        "uploadedBy": row.get("uploaded_by"),
+        "createdAt":  row.get("created_at"),
+        "summary":    crypto.decrypt_text_for_org(org_id, row.get("summary_enc")),
+    }
+    if content:
+        out["content"] = crypto.decrypt_text_for_org(org_id, row.get("content_enc"))
+    return out
+
+
+def ingest_doc(org_id: str, filename: str | None, mime: str | None,
+               content_bytes: bytes, uploaded_by: str) -> dict:
+    """Extract text, encrypt it under the org's subkey, store a vault_docs
+    row, and return the public doc dict (summary decrypted for the caller).
+
+    Raises UnsupportedDocumentError (bad type / pypdf missing → HTTP 415),
+    KnowledgeError (unparseable/empty → 400), RuntimeError from atp/crypto.py
+    when DATA_ENCRYPTION_KEY is unset (T2 is never written as plaintext).
+    """
+    _ensure_db()
+    text = _extract_text(filename, mime, content_bytes)
+    doc_id = "doc_" + uuid.uuid4().hex[:12]
+    row = {
+        "id": doc_id,
+        "title": _title_from(text, filename),
+        "filename": filename,
+        "mime": mime,
+        "content_enc": crypto.encrypt_for_org(org_id, text),
+        "summary_enc": crypto.encrypt_for_org(org_id, _summarize(text)),
+        "uploaded_by": uploaded_by,
+        "created_at": _now(),
+        "status": "uploaded",
+    }
+    tenant_db.scoped_execute(org_id, _scoped(
+        "INSERT INTO vault_docs (id, org_id, title, filename, mime, "
+        "  content_enc, summary_enc, uploaded_by, created_at, status) "
+        "VALUES (:id, :org, :title, :filename, :mime, :content_enc, "
+        "  :summary_enc, :uploaded_by, :created_at, :status)"),
+        {"org": org_id, **row})
+    return _doc_public({**row}, org_id)
+
+
+def list_docs(org_id: str) -> list[dict]:
+    """Org's vault docs, latest first — summaries decrypted, NO content."""
+    _ensure_db()
+    rows = tenant_db.scoped_query(org_id, _scoped(
+        f"SELECT {_DOC_LIST_COLS}, summary_enc FROM vault_docs "
+        f"WHERE org_id = :org ORDER BY created_at DESC, id DESC"),
+        {"org": org_id})
+    return [_doc_public(r, org_id) for r in rows]
+
+
+def _doc_row(org_id: str, doc_id: str) -> dict | None:
+    rows = tenant_db.scoped_query(org_id, _scoped(
+        "SELECT * FROM vault_docs WHERE org_id = :org AND id = :id LIMIT 1"),
+        {"org": org_id, "id": doc_id})
+    return rows[0] if rows else None
+
+
+def get_doc(org_id: str, doc_id: str) -> dict | None:
+    """One doc with the FULL decrypted text, or None (cross-tenant ids are
+    indistinguishable from unknown ones — TENANCY.md leak surface #6)."""
+    _ensure_db()
+    row = _doc_row(org_id, doc_id)
+    return None if row is None else _doc_public(row, org_id, content=True)
+
+
+# ── L5 draft generation (deterministic heuristic — no LLM dependency) ───────
+
+def _items_for_doc(doc_idx: int, title: str, units: list[tuple[str, str]]
+                   ) -> list[dict]:
+    """Recall + apply item pair per (heading, passage) unit. Pure function of
+    its inputs — same docs in the same order always produce the same items."""
+    items: list[dict] = []
+    for u_idx, (heading, passage) in enumerate(units[:MAX_UNITS_PER_DOC], 1):
+        passage = passage[:MAX_EXPECTED_CHARS]
+        base = f"l5d-{doc_idx:02d}-{u_idx:02d}"
+        items.append({
+            "id": f"{base}-r",
+            "section": title,
+            "type": "recall",
+            "prompt": (f'According to "{title}", what is stated about '
+                       f'"{heading}"?'),
+            "expected": (f'Full credit requires accurately restating the '
+                         f'substance of this passage from "{title}" '
+                         f'(section: {heading}); contradicting it or '
+                         f'inventing unstated policy is wrong:\n{passage}'),
+            "points": 2,
+        })
+        items.append({
+            "id": f"{base}-a",
+            "section": title,
+            "type": "apply",
+            "prompt": (f'A teammate must follow the guidance in "{title}" '
+                       f'regarding "{heading}". Explain, step by step, how '
+                       f'to apply what the document states, and note when '
+                       f'to escalate instead of guessing.'),
+            "expected": (f'Full credit requires steps grounded ONLY in this '
+                         f'passage from "{title}" (section: {heading}) — no '
+                         f'invented policy; ambiguous cases must escalate:\n'
+                         f'{passage}'),
+            "points": 3,
+        })
+    return items
+
+
+def _draft_public(row: dict, org_id: str, *, include_items: bool) -> dict:
+    blueprint = json.loads(row["blueprint_json"])
+    out = {
+        "id":         row["id"],
+        "certLabel":  row["cert_label"],
+        "blueprint":  blueprint,
+        "docIds":     json.loads(row["doc_ids_json"]),
+        "status":     row["status"],
+        "createdBy":  row.get("created_by"),
+        "createdAt":  row.get("created_at"),
+        "reviewedBy": row.get("reviewed_by"),
+        "reviewedAt": row.get("reviewed_at"),
+        "reviewNote": row.get("review_note"),
+        "itemCount":  sum(int(s.get("items", 0))
+                          for s in blueprint.get("sections", [])),
+        "examCertRef": EXAM_CERT_PREFIX + row["id"],
+    }
+    if include_items:
+        out["items"] = json.loads(
+            crypto.decrypt_text_for_org(org_id, row["items_json_enc"]))
+    return out
+
+
+def generate_l5_draft(org_id: str, doc_ids: list[str], created_by: str,
+                      title: str = "") -> dict:
+    """Deterministic heuristic L5 exam draft from the org's vault docs.
+
+    Blueprint sections = the docs' titles (one section per doc, weights
+    proportional to item count, normalized to sum 1). Items = a recall +
+    apply pair per (heading, passage) unit of each doc. Requires >= 2 docs
+    with distinct titles and >= 8 items total, else KnowledgeError.
+
+    Blueprint is stored plaintext; ITEMS (T2 — verbatim company passages)
+    are encrypted under the org subkey. Returns the draft dict with items
+    DECRYPTED for immediate SME review (the route role-gates that).
+    """
+    _ensure_db()
+    if not doc_ids:
+        raise KnowledgeError("docIds must be a non-empty list")
+    if len(set(doc_ids)) != len(doc_ids):
+        raise KnowledgeError("docIds contains duplicates")
+
+    docs: list[dict] = []
+    missing: list[str] = []
+    for doc_id in doc_ids:
+        row = _doc_row(org_id, doc_id)
+        if row is None:
+            missing.append(doc_id)
+        else:
+            docs.append(row)
+    if missing:
+        # Cross-tenant ids fail EXACTLY like unknown ones (TENANCY.md #6);
+        # only ids the caller itself supplied are echoed back.
+        raise KnowledgeError(f"unknown doc id(s): {sorted(missing)}")
+
+    items: list[dict] = []
+    sections: list[dict] = []
+    seen_titles: set[str] = set()
+    for d_idx, row in enumerate(docs, 1):
+        title_d = row["title"]
+        if title_d in seen_titles:
+            raise KnowledgeError(
+                f"two selected docs share the title {title_d!r} — blueprint "
+                f"sections are doc titles and must be distinct")
+        seen_titles.add(title_d)
+        text = crypto.decrypt_text_for_org(org_id, row["content_enc"])
+        units = _split_units(text)
+        doc_items = _items_for_doc(d_idx, title_d, units)
+        if not doc_items:
+            raise KnowledgeError(
+                f"doc {row['id']} ({title_d!r}) yields no examinable "
+                f"passages (needs paragraphs of >= {MIN_UNIT_CHARS} chars)")
+        items.extend(doc_items)
+        sections.append({"name": title_d, "items": len(doc_items),
+                         "itemTypes": ["recall", "apply"]})
+
+    if len(sections) < MIN_SECTIONS:
+        raise KnowledgeError(
+            f"an L5 draft needs >= {MIN_SECTIONS} blueprint sections "
+            f"(= distinct docs); got {len(sections)}")
+    if len(items) < MIN_ITEMS:
+        raise KnowledgeError(
+            f"an L5 draft needs >= {MIN_ITEMS} items; these docs only "
+            f"yield {len(items)} — upload richer documents")
+
+    # Weights proportional to item count, normalized to sum exactly 1
+    # (the last section absorbs the rounding remainder).
+    total = len(items)
+    for s in sections[:-1]:
+        s["weight"] = round(s["items"] / total, 6)
+    sections[-1]["weight"] = round(1.0 - sum(s["weight"]
+                                             for s in sections[:-1]), 6)
+
+    draft_id = "l5d_" + uuid.uuid4().hex[:12]
+    blueprint = {"sections": sections, "totalItems": total}
+    row = {
+        "id": draft_id,
+        "cert_label": (title or "").strip() or "ATP-L5 Company Knowledge (draft)",
+        "blueprint_json": json.dumps(blueprint, sort_keys=True),
+        "items_json_enc": crypto.encrypt_for_org(org_id, json.dumps(items)),
+        "doc_ids_json": json.dumps(list(doc_ids)),
+        "status": "draft",
+        "created_by": created_by,
+        "created_at": _now(),
+    }
+    tenant_db.scoped_execute(org_id, _scoped(
+        "INSERT INTO l5_drafts (id, org_id, cert_label, blueprint_json, "
+        "  items_json_enc, doc_ids_json, status, created_by, created_at) "
+        "VALUES (:id, :org, :cert_label, :blueprint_json, :items_json_enc, "
+        "  :doc_ids_json, :status, :created_by, :created_at)"),
+        {"org": org_id, **row})
+
+    # uploaded -> drafted (docs already 'drafted'/'signed' keep their status).
+    for doc_id in doc_ids:
+        tenant_db.scoped_execute(org_id, _scoped(
+            "UPDATE vault_docs SET status = 'drafted' "
+            "WHERE org_id = :org AND id = :id AND status = 'uploaded'"),
+            {"org": org_id, "id": doc_id})
+
+    return _draft_public(row, org_id, include_items=True)
+
+
+def list_drafts(org_id: str, include_items: bool = False) -> list[dict]:
+    """Org's L5 drafts, latest first. Items (T2) only when include_items —
+    the route restricts that to admin|sme."""
+    _ensure_db()
+    rows = tenant_db.scoped_query(org_id, _scoped(
+        "SELECT * FROM l5_drafts WHERE org_id = :org "
+        "ORDER BY created_at DESC, id DESC"),
+        {"org": org_id})
+    return [_draft_public(r, org_id, include_items=include_items) for r in rows]
+
+
+def _draft_row(org_id: str, draft_id: str) -> dict | None:
+    rows = tenant_db.scoped_query(org_id, _scoped(
+        "SELECT * FROM l5_drafts WHERE org_id = :org AND id = :id LIMIT 1"),
+        {"org": org_id, "id": draft_id})
+    return rows[0] if rows else None
+
+
+def get_draft(org_id: str, draft_id: str,
+              include_items: bool = False) -> dict | None:
+    _ensure_db()
+    row = _draft_row(org_id, draft_id)
+    return None if row is None else _draft_public(
+        row, org_id, include_items=include_items)
+
+
+# ── SME sign-off (separation of duties; evidence on the signed chain) ───────
+
+def _review(org_id: str, draft_id: str, reviewer: str, note: str,
+            to_status: str, outcome: str) -> dict | None:
+    """Shared approve/reject transition: guarded UPDATE from 'draft', then a
+    signed 'sme_signoff' evidence row. Returns None for unknown/cross-org
+    ids; DraftStateError when the draft is not in status 'draft'."""
+    _ensure_db()
+    row = _draft_row(org_id, draft_id)
+    if row is None:
+        return None
+    if row["status"] != "draft":
+        raise DraftStateError(
+            f"draft {draft_id} is '{row['status']}' — only status 'draft' "
+            f"can be {outcome}")
+    ts = _now()
+    res = tenant_db.scoped_execute(org_id, _scoped(
+        "UPDATE l5_drafts SET status = :to, reviewed_by = :rev, "
+        "  reviewed_at = :ts, review_note = :note "
+        "WHERE org_id = :org AND id = :id AND status = 'draft'"),
+        {"org": org_id, "id": draft_id, "to": to_status,
+         "rev": reviewer, "ts": ts, "note": note})
+    if res.rowcount == 0:  # lost a race — same answer as the pre-check
+        raise DraftStateError(
+            f"draft {draft_id} was reviewed concurrently — reload it")
+
+    cert_ref = EXAM_CERT_PREFIX + draft_id
+    doc_ids = json.loads(row["doc_ids_json"])
+    # The sign-off itself is the tamper-evident record (l5_drafts is mutable
+    # by design — migration 007 header): one HMAC-signed row on the org's
+    # evidence chain. NOTE: payload carries reviewer/note/doc ids — metadata,
+    # never document content or items (atp_evidence is not encrypted).
+    payload = {"draftId": draft_id, "reviewer": reviewer, "note": note,
+               "docIds": doc_ids, "certLabel": row["cert_label"],
+               "outcome": outcome}
+    (evidence_id, _sig), = signing.append_chain(org_id, [{
+        "ts": ts, "agent_id": reviewer, "cert_id": cert_ref,
+        "kind": "sme_signoff", "payload": payload,
+    }])
+
+    if to_status == "approved":
+        for doc_id in doc_ids:  # drafted -> signed
+            tenant_db.scoped_execute(org_id, _scoped(
+                "UPDATE vault_docs SET status = 'signed' "
+                "WHERE org_id = :org AND id = :id"),
+                {"org": org_id, "id": doc_id})
+        # Materialize the bank in memory now (also happens lazily on demand).
+        load_org_item_bank(org_id, cert_ref)
+
+    return {
+        "draftId": draft_id,
+        "status": to_status,
+        "outcome": outcome,
+        "reviewedBy": reviewer,
+        "reviewedAt": ts,
+        "note": note,
+        "evidenceId": evidence_id,
+        "examCertRef": cert_ref,
+        "examRunnable": to_status == "approved",
+    }
+
+
+def approve_draft(org_id: str, draft_id: str, reviewer: str,
+                  note: str = "") -> dict | None:
+    """SME approval: draft -> approved, 'sme_signoff' evidence appended,
+    covered docs flip to 'signed', and the exam bank becomes loadable via
+    load_org_item_bank (cert ref in the returned 'examCertRef')."""
+    return _review(org_id, draft_id, reviewer, note, "approved", "approved")
+
+
+def reject_draft(org_id: str, draft_id: str, reviewer: str,
+                 note: str = "") -> dict | None:
+    """SME rejection: draft -> rejected, with the SAME evidence trail
+    (kind 'sme_signoff', payload.outcome = 'rejected')."""
+    return _review(org_id, draft_id, reviewer, note, "rejected", "rejected")
+
+
+# ── Exam extension point (consumed by atp/exams.py's Phase 6 loader path) ───
+
+def _template_cert() -> dict:
+    """passCriteria/rubric archetype for org L5 drafts, deep-copied from the
+    seed L5 cert so the T0 seed is never mutated."""
+    from atp import store
+    for cert in store.get_data().get("CERTS", []):
+        if cert.get("id") == L5_TEMPLATE_CERT_ID:
+            return json.loads(json.dumps(cert))  # cheap deep copy
+    # Defensive fallback — the seed always ships this cert.
+    return {"passCriteria": {"overall": 0.9, "perSection": 0.85, "runs": 2,
+                             "temperature": 0, "seed": 5051,
+                             "judgeSeparation": True},
+            "rubric": []}
+
+
+def load_org_item_bank(org_id: str, cert_ref: str) -> dict | None:
+    """Materialize an org's APPROVED draft bank in memory for atp/exams.py.
+
+    cert_ref: f"{EXAM_CERT_PREFIX}<draft_id>". Returns
+        {"cert": <synthetic cert dict>, "items": [item, ...]}
+    or None when the ref does not name an approved draft of THIS org (a
+    cross-tenant ref is indistinguishable from an unknown one — #6).
+
+    The synthetic cert carries the draft's own blueprint (sections = doc
+    titles) plus the passCriteria/rubric of the seed L5 template cert, so
+    run_exam()'s aggregation and verdict logic work unchanged. Decrypted
+    items live only in this process's memory (_BANK_CACHE) — never on disk.
+    """
+    if not cert_ref.startswith(EXAM_CERT_PREFIX):
+        return None
+    draft_id = cert_ref[len(EXAM_CERT_PREFIX):]
+    key = (org_id, draft_id)
+    with _BANK_LOCK:
+        cached = _BANK_CACHE.get(key)
+    if cached is not None:
+        return cached
+
+    _ensure_db()
+    row = _draft_row(org_id, draft_id)
+    if row is None or row["status"] != "approved":
+        return None
+    items = json.loads(crypto.decrypt_text_for_org(org_id, row["items_json_enc"]))
+    template = _template_cert()
+    cert = {
+        "id": cert_ref,
+        "label": row["cert_label"],
+        "sentence": (f"Org-scoped L5 company-knowledge draft "
+                     f"({row['cert_label']}), SME-approved."),
+        "layer": 5,
+        "domain": "Company Knowledge",
+        "blueprint": json.loads(row["blueprint_json"]),
+        "rubric": template.get("rubric", []),
+        "passCriteria": template.get("passCriteria", {}),
+        "smeSignoff": [{"name": row.get("reviewed_by"),
+                        "ts": row.get("reviewed_at")}],
+    }
+    bank = {"cert": cert, "items": items, "draftId": draft_id}
+    with _BANK_LOCK:
+        _BANK_CACHE[key] = bank
+    return bank

atp/licensing.py

@@ -0,0 +1,508 @@
+"""
+Agent licensing — issue / verify / revoke / meter (Phase 4, docs/HARDENING.md).
+
+Licenses are T1 org-scoped data (docs/TENANCY.md): every read/write goes
+through atp/tenant_db.py (org from the verified request principal, NEVER from
+a payload), and on Postgres migration 006 adds FORCE row-level security with
+the 005 policy pattern. Stripe is OPTIONAL by design: without STRIPE_API_KEY
+the platform still issues 'manual' licenses (design partners pay by invoice)
+— stripe_customer/stripe_subscription stay NULL and gating/metering/
+revocation work identically. Stripe only adds self-serve checkout on top.
+
+License-key format (shown ONCE at issue time; only key_id is persisted):
+
+    atpk_<key_id>.<sig>
+    key_id = 24 hex chars (secrets.token_hex(12))
+    sig    = HMAC-SHA256(LICENSE_SIGNING_KEY, key_id) hex, first 32 chars
+
+Verification model — the key alone NEVER suffices:
+
+    check_license() first verifies the HMAC in constant time (cheap, no DB
+    hit for forged keys), then loads the row by key_id and enforces
+    status == 'active' AND (expires_at IS NULL OR in the future). Revocation
+    and expiry are DB STATE — a revoked/expired row fails on the very next
+    call regardless of a validly signed key. Rows whose expires_at has passed
+    are auto-flipped to status='expired' on check (`licenses` is mutable by
+    design; `usage_events` + the atp_evidence chain are the append-only
+    billing/audit record).
+
+Key resolution (mirrors atp/signing.py, fail-loud):
+
+    LICENSE_SIGNING_KEY       required whenever keys are issued/verified with
+                              auth enabled — LicenseSigningKeyError if unset.
+    BU_AUTH_DISABLED=1 (dev)  fallback: derive a stable key from
+                              BU_AUTH_SECRET when set, else a process-
+                              ephemeral random key with a loud warning
+                              (keys then don't verify across restarts).
+
+Public:
+    issue_license(org_id, agent_id, kind, expires_at=None,
+                  stripe_customer=None, stripe_subscription=None)
+                                        -> {license, licenseKey}
+    check_license(license_key)          -> {ok, license?, reason?}
+    revoke_license(org_id, license_id, reason) -> license dict (idempotent)
+    record_usage(org_id, license_id, agent_id, endpoint,
+                 tokens_in, tokens_out, status) -> usage-event dict
+    usage_summary(org_id, license_id=None)
+                                        -> {calls, tokensIn, tokensOut, byAgent}
+    list_licenses(org_id)               -> [license dict] latest-first
+
+Returned license dicts are camelCase and NEVER contain key material: the
+secret half of the key is not stored anywhere; `keyId` (the public identifier
+half, useless without LICENSE_SIGNING_KEY) is included so an admin can match
+a key in hand to its row. Like atp/store.py, returned dicts do not grow an
+org key.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import secrets
+import sys
+import time
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import text
+
+from atp import db, store, tenant_db
+
+#: License-key prefix (public, greppable — like Stripe's sk_/pk_).
+KEY_PREFIX = "atpk_"
+
+#: Hex chars of the HMAC kept in the key (128 bits of the 256-bit MAC).
+_SIG_LEN = 32
+
+#: Domain-separation tag for the BU_AUTH_SECRET-derived dev key — distinct
+#: from atp/signing.py's tag so evidence and license keys never share a key.
+_DERIVE_TAG = b"bu-license-signing-v1:"
+
+VALID_KINDS = frozenset({"evaluation", "production"})
+
+_EPHEMERAL_KEY: bytes | None = None
+_WARNED = False
+_MIGRATIONS_DONE = False
+
+
+class LicensingError(RuntimeError):
+    """Base class for licensing failures."""
+
+
+class LicenseSigningKeyError(LicensingError):
+    """Key issue/verify was requested but no usable signing key is set."""
+
+
+class UnknownAgentError(LicensingError):
+    """agent_id does not exist in the marketplace seed."""
+
+
+class AgentNotLicensableError(LicensingError):
+    """Agent exists but its seed says licensing.available is false."""
+
+
+class LicenseNotFoundError(LicensingError):
+    """No license with that id is visible to the caller's org."""
+
+
+# ── Signing key (mirrors atp/signing.py) ────────────────────────────────────
+
+def _signing_key() -> bytes:
+    """Resolve the HMAC key (see module docstring for the precedence)."""
+    global _EPHEMERAL_KEY, _WARNED
+    key = os.environ.get("LICENSE_SIGNING_KEY", "").strip()
+    if key:
+        return key.encode("utf-8")
+
+    if os.environ.get("BU_AUTH_DISABLED", "") == "1":
+        # Dev mode: never block the loop, but never sign with a hardcoded
+        # default either — derive from the auth secret when one exists.
+        auth_secret = os.environ.get("BU_AUTH_SECRET", "").strip()
+        if auth_secret:
+            return hashlib.sha256(_DERIVE_TAG + auth_secret.encode("utf-8")).digest()
+        if _EPHEMERAL_KEY is None:
+            _EPHEMERAL_KEY = secrets.token_bytes(32)
+        if not _WARNED:
+            _WARNED = True
+            print(
+                "WARNING: LICENSE_SIGNING_KEY unset (BU_AUTH_DISABLED=1 dev "
+                "mode) — signing license keys with a process-EPHEMERAL key. "
+                "Issued keys will NOT verify after a restart. Set "
+                "LICENSE_SIGNING_KEY (see .env.example).",
+                file=sys.stderr,
+            )
+        return _EPHEMERAL_KEY
+
+    raise LicenseSigningKeyError(
+        "LICENSE_SIGNING_KEY is not set. License-key signing is mandatory "
+        "when auth is enabled (docs/HARDENING.md Phase 4) — generate one with "
+        "python3 -c \"import secrets; print(secrets.token_hex(32))\" and "
+        "export it, or export BU_AUTH_DISABLED=1 for local dev only."
+    )
+
+
+def _key_sig(key_id: str) -> str:
+    """Secret half of a license key: truncated hex HMAC-SHA256 over key_id."""
+    return hmac.new(
+        _signing_key(), key_id.encode("utf-8"), hashlib.sha256
+    ).hexdigest()[:_SIG_LEN]
+
+
+def _parse_key(license_key) -> tuple[str, str] | None:
+    """Split 'atpk_<key_id>.<sig>' → (key_id, sig); None when malformed."""
+    if not isinstance(license_key, str) or not license_key.startswith(KEY_PREFIX):
+        return None
+    key_id, dot, sig = license_key[len(KEY_PREFIX):].partition(".")
+    if not dot or not key_id or not sig:
+        return None
+    return key_id, sig
+
+
+# ── Row plumbing ─────────────────────────────────────────────────────────────
+
+# camelCase API key ↔ snake_case column; declaration order = SELECT order.
+_LICENSE_COLS = {
+    "id": "id",
+    "agentId": "agent_id",
+    "kind": "kind",
+    "status": "status",
+    "keyId": "key_id",           # public identifier half only — never secret
+    "createdAt": "created_at",
+    "expiresAt": "expires_at",
+    "revokedAt": "revoked_at",
+    "revokedReason": "revoked_reason",
+    "stripeCustomer": "stripe_customer",
+    "stripeSubscription": "stripe_subscription",
+    "seats": "seats",
+}
+_LICENSE_SELECT = ", ".join(_LICENSE_COLS.values())
+
+
+def _to_camel(row: dict) -> dict:
+    """Map a licenses row to the public camelCase shape (org_id dropped —
+    same convention as atp/store.py: returned dicts don't grow an org key)."""
+    return {camel: row.get(col) for camel, col in _LICENSE_COLS.items()}
+
+
+def _now_iso() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _parse_ts(value) -> datetime | None:
+    """ISO-8601 → aware UTC datetime; None when unparseable."""
+    if not value or not isinstance(value, str):
+        return None
+    try:
+        return datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ").replace(
+            tzinfo=timezone.utc)
+    except ValueError:
+        pass
+    try:
+        dt = datetime.fromisoformat(value)
+        return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+    except ValueError:
+        return None
+
+
+def _ensure_migrations() -> None:
+    """Lazily apply pending migrations once per process (idempotent — the
+    startup run stays authoritative; this covers direct library use/tests)."""
+    global _MIGRATIONS_DONE
+    if not _MIGRATIONS_DONE:
+        db.run_migrations()
+        _MIGRATIONS_DONE = True
+
+
+def _load_by_key_id(key_id: str) -> dict | None:
+    """Load one licenses row by key_id — the key-based lookup path.
+
+    check_license() authenticates by license KEY, not by org (the caller of
+    the gated proxy may be a machine holding only the key); the org comes
+    FROM the row. On Postgres the `key_lookup` SELECT policy (migration 006)
+    makes exactly this one row visible after pinning the verified key_id:
+        SELECT set_config('app.license_key_id', :kid, true)   -- == SET LOCAL
+    in the same transaction. Writes still require the org GUC, so everything
+    that follows (expiry flip, metering) goes back through atp/tenant_db.py
+    scoped to the row's org.
+    """
+    engine = db.get_engine()
+    with engine.begin() as conn:
+        if engine.dialect.name == "postgresql":
+            conn.execute(
+                text("SELECT set_config('app.license_key_id', :kid, true)"),
+                {"kid": key_id},
+            )
+        row = conn.execute(
+            text(f"SELECT org_id, {_LICENSE_SELECT} FROM licenses "
+                 "WHERE key_id = :kid"),
+            {"kid": key_id},
+        ).mappings().first()
+        return dict(row) if row else None
+
+
+# ── Public API ───────────────────────────────────────────────────────────────
+
+def issue_license(org_id: str, agent_id: str, kind: str,
+                  expires_at: str | None = None,
+                  stripe_customer: str | None = None,
+                  stripe_subscription: str | None = None) -> dict:
+    """Issue a license for a marketplace agent to `org_id`.
+
+    Returns {"license": <camelCase dict>, "licenseKey": "atpk_..."} — the
+    licenseKey is shown exactly ONCE here; only its key_id half is stored.
+    Manual (invoice-billed) licenses simply pass no stripe_* values.
+
+    Raises UnknownAgentError / AgentNotLicensableError when the agent is not
+    in the seed or its seed licensing says available=false; ValueError on a
+    bad kind or unparseable expires_at.
+    """
+    agent = next(
+        (a for a in store.get_data()["AGENTS"] if a.get("id") == agent_id),
+        None)
+    if agent is None:
+        raise UnknownAgentError(f"unknown agent {agent_id!r}")
+    if not (agent.get("licensing") or {}).get("available"):
+        raise AgentNotLicensableError(
+            f"agent {agent_id!r} is not available for licensing")
+    if kind not in VALID_KINDS:
+        raise ValueError(
+            f"kind must be one of {sorted(VALID_KINDS)}, got {kind!r}")
+    if expires_at is not None and _parse_ts(expires_at) is None:
+        raise ValueError(
+            f"expires_at must be ISO-8601 UTC ('%Y-%m-%dT%H:%M:%SZ'), "
+            f"got {expires_at!r}")
+
+    _ensure_migrations()
+    key_id = secrets.token_hex(12)  # 96 bits; UNIQUE constraint is backstop
+    license_key = f"{KEY_PREFIX}{key_id}.{_key_sig(key_id)}"
+    row = {
+        "id": f"lic-{uuid.uuid4().hex[:12]}",
+        "agent_id": agent_id,
+        "kind": kind,
+        "status": "active",
+        "key_id": key_id,
+        "created_at": _now_iso(),
+        "expires_at": expires_at,
+        "revoked_at": None,
+        "revoked_reason": None,
+        "stripe_customer": stripe_customer,
+        "stripe_subscription": stripe_subscription,
+        "seats": 1,
+    }
+    tenant_db.scoped_execute(
+        org_id,
+        "INSERT INTO licenses "
+        "  (id, org_id, agent_id, kind, status, key_id, created_at, "
+        "   expires_at, revoked_at, revoked_reason, stripe_customer, "
+        "   stripe_subscription, seats) "
+        "VALUES (:id, :org, :agent_id, :kind, :status, :key_id, :created_at, "
+        "        :expires_at, :revoked_at, :revoked_reason, :stripe_customer, "
+        "        :stripe_subscription, :seats)",
+        {"org": org_id, **row},
+    )
+    return {"license": _to_camel(row), "licenseKey": license_key}
+
+
+def check_license(license_key) -> dict:
+    """Verify a presented license key. -> {ok, license?, reason?}
+
+    Order of enforcement:
+      1. parse — malformed keys fail without touching the signing key or DB;
+      2. constant-time HMAC verify (hmac.compare_digest) — forged keys fail
+         without a DB hit;
+      3. DB state — the row must exist, have status 'active', and not be past
+         expires_at. Revoked/expired rows fail REGARDLESS of a valid
+         signature: revocation is DB state, the key alone never suffices.
+    Rows expired by date but still marked 'active' are flipped to 'expired'
+    here (scoped to the row's own org).
+
+    reason ∈ {'malformed', 'invalid-signature', 'unknown', 'revoked',
+    'expired'}; on success the license dict is returned (no key material).
+    """
+    parsed = _parse_key(license_key)
+    if parsed is None:
+        return {"ok": False, "reason": "malformed"}
+    key_id, sig = parsed
+    expected = _key_sig(key_id)
+    if not hmac.compare_digest(expected.encode("utf-8"), sig.encode("utf-8")):
+        return {"ok": False, "reason": "invalid-signature"}
+
+    _ensure_migrations()
+    row = _load_by_key_id(key_id)
+    if row is None:
+        return {"ok": False, "reason": "unknown"}
+    if row["status"] == "revoked":
+        return {"ok": False, "reason": "revoked"}
+
+    expires = _parse_ts(row.get("expires_at")) if row.get("expires_at") else None
+    past_expiry = row.get("expires_at") is not None and (
+        expires is None  # unparseable date in DB → fail safe (deny)
+        or expires <= datetime.now(timezone.utc))
+    if row["status"] == "expired" or past_expiry:
+        if row["status"] == "active":
+            # Auto-transition: expiry-by-date becomes durable DB state.
+            # `licenses` is mutable by design (only usage/evidence are
+            # append-only); guard on status for concurrent checks.
+            tenant_db.scoped_execute(
+                row["org_id"],
+                "UPDATE licenses SET status = 'expired' "
+                "WHERE org_id = :org AND id = :id AND status = 'active'",
+                {"org": row["org_id"], "id": row["id"]},
+            )
+        return {"ok": False, "reason": "expired"}
+
+    return {"ok": True, "license": _to_camel(row)}
+
+
+def revoke_license(org_id: str, license_id: str, reason: str) -> dict:
+    """Revoke a license (idempotent). Returns the camelCase license dict.
+
+    Org-scoped: a license belonging to another org is simply not visible, so
+    cross-org revocation raises LicenseNotFoundError. Takes effect on the
+    very next check_license() call — the gate re-reads DB state every time.
+    """
+    _ensure_migrations()
+    rows = tenant_db.scoped_query(
+        org_id,
+        f"SELECT {_LICENSE_SELECT} FROM licenses "
+        "WHERE org_id = :org AND id = :id",
+        {"org": org_id, "id": license_id},
+    )
+    if not rows:
+        raise LicenseNotFoundError(
+            f"no license {license_id!r} in org {org_id!r}")
+    row = rows[0]
+    if row["status"] == "revoked":
+        return _to_camel(row)  # already revoked — idempotent no-op
+    row["status"] = "revoked"
+    row["revoked_at"] = _now_iso()
+    row["revoked_reason"] = str(reason or "")
+    tenant_db.scoped_execute(
+        org_id,
+        "UPDATE licenses SET status = 'revoked', revoked_at = :ts, "
+        "revoked_reason = :reason WHERE org_id = :org AND id = :id",
+        {"org": org_id, "id": license_id,
+         "ts": row["revoked_at"], "reason": row["revoked_reason"]},
+    )
+    return _to_camel(row)
+
+
+def reissue_key(org_id: str, license_id: str) -> dict:
+    """Mint a NEW key for an existing ACTIVE license (old key stops working
+    immediately — key_id is replaced, and check_license resolves by key_id).
+
+    The in-product delivery path for Stripe self-serve licenses, whose
+    webhook-issued plaintext key is discarded by design: an org admin
+    re-issues and hands the fresh key to the customer. Returns
+    {"license": ..., "licenseKey": ...}; the key appears exactly ONCE here.
+    """
+    _ensure_migrations()
+    rows = tenant_db.scoped_query(
+        org_id,
+        f"SELECT {_LICENSE_SELECT} FROM licenses "
+        "WHERE org_id = :org AND id = :id",
+        {"org": org_id, "id": license_id},
+    )
+    if not rows:
+        raise LicenseNotFoundError(
+            f"no license {license_id!r} in org {org_id!r}")
+    if rows[0]["status"] != "active":
+        raise ValueError(
+            f"only active licenses can be re-keyed "
+            f"(status is {rows[0]['status']!r})")
+    key_id = secrets.token_hex(12)
+    license_key = f"{KEY_PREFIX}{key_id}.{_key_sig(key_id)}"
+    tenant_db.scoped_execute(
+        org_id,
+        "UPDATE licenses SET key_id = :key_id "
+        "WHERE org_id = :org AND id = :id",
+        {"org": org_id, "id": license_id, "key_id": key_id},
+    )
+    rows[0]["key_id"] = key_id
+    return {"license": _to_camel(rows[0]), "licenseKey": license_key}
+
+
+def record_usage(org_id: str, license_id: str | None, agent_id: str,
+                 endpoint: str, tokens_in: int, tokens_out: int,
+                 status: str) -> dict:
+    """Append one metering row to usage_events (append-only billing evidence).
+
+    Returns the camelCase event including its row id.
+    """
+    _ensure_migrations()
+    event = {
+        "ts": _now_iso(),
+        "license_id": license_id,
+        "agent_id": agent_id,
+        "endpoint": endpoint,
+        "tokens_in": int(tokens_in or 0),
+        "tokens_out": int(tokens_out or 0),
+        "status": str(status),
+    }
+    result = tenant_db.scoped_execute(
+        org_id,
+        "INSERT INTO usage_events "
+        "  (ts, org_id, license_id, agent_id, endpoint, tokens_in, "
+        "   tokens_out, status) "
+        "VALUES (:ts, :org, :license_id, :agent_id, :endpoint, :tokens_in, "
+        "        :tokens_out, :status) "
+        "RETURNING id",
+        {"org": org_id, **event},
+    )
+    return {
+        "id": result.lastrowid,
+        "ts": event["ts"],
+        "licenseId": license_id,
+        "agentId": agent_id,
+        "endpoint": endpoint,
+        "tokensIn": event["tokens_in"],
+        "tokensOut": event["tokens_out"],
+        "status": event["status"],
+    }
+
+
+def usage_summary(org_id: str, license_id: str | None = None) -> dict:
+    """Aggregate an org's metering rows (optionally for one license).
+
+    -> {calls, tokensIn, tokensOut, byAgent: {agentId: {calls, tokensIn,
+    tokensOut}}}. Values are plain ints on both dialects.
+    """
+    _ensure_migrations()
+    sql = (
+        "SELECT agent_id, COUNT(*) AS calls, "
+        "       COALESCE(SUM(tokens_in), 0) AS tokens_in, "
+        "       COALESCE(SUM(tokens_out), 0) AS tokens_out "
+        "FROM usage_events WHERE org_id = :org"
+    )
+    params: dict = {"org": org_id}
+    if license_id is not None:
+        sql += " AND license_id = :license_id"
+        params["license_id"] = license_id
+    sql += " GROUP BY agent_id"
+    by_agent: dict[str, dict] = {}
+    totals = {"calls": 0, "tokensIn": 0, "tokensOut": 0}
+    for r in tenant_db.scoped_query(org_id, sql, params):
+        entry = {
+            "calls": int(r["calls"]),
+            "tokensIn": int(r["tokens_in"]),      # PG SUM → Decimal
+            "tokensOut": int(r["tokens_out"]),
+        }
+        by_agent[r["agent_id"] or ""] = entry
+        totals["calls"] += entry["calls"]
+        totals["tokensIn"] += entry["tokensIn"]
+        totals["tokensOut"] += entry["tokensOut"]
+    return {**totals, "byAgent": by_agent}
+
+
+def list_licenses(org_id: str) -> list[dict]:
+    """All of `org_id`'s licenses, latest-first, camelCase — never any key
+    material (only keyId, the public identifier half)."""
+    _ensure_migrations()
+    rows = tenant_db.scoped_query(
+        org_id,
+        f"SELECT {_LICENSE_SELECT} FROM licenses WHERE org_id = :org "
+        "ORDER BY created_at DESC, id DESC",
+        {"org": org_id},
+    )
+    return [_to_camel(r) for r in rows]

atp/reportcard.py

@@ -0,0 +1,697 @@
+"""
+atp/reportcard.py — Phase 6 (docs/HARDENING.md): official report-card PDF.
+
+    build_report_card_pdf(agent_id, org_id='org-demo') -> bytes
+
+Server-side PDF export of one agent's report card, written for a
+NON-TECHNICAL stakeholder: who the agent is, what it is certified for,
+where it is strong, and — deliberately IN the document, per the ATP
+'failure transparency' principle — where it will break.
+
+Data sources:
+  * Seed catalog (atp/store.get_data()) — T0 public: agent profile,
+    reportCard prose, skills, failure modes, cert metadata + seed awards.
+  * Live cert awards for the agent from atp_cert_awards, org-scoped through
+    atp/tenant_db.py ONLY (docs/TENANCY.md layer 2; org_id comes from the
+    verified request state at the route). Live awards whose evidence was
+    produced by the deterministic dry-run backend are marked DRY-RUN so a
+    stub exam can never read like a real certification.
+
+The PDF mirrors the Agent-view aesthetic (design/styles.css "university +
+standards-body tone"): navy header band, gold rules, mono labels, layer
+palette. reportlab only — built-in Helvetica/Courier faces, no external
+assets. Rendering is pure (bytes out, no files written); tenant files are
+NEVER involved and nothing is served from /videos or /media (TENANCY.md
+leak surface #4).
+
+Raises UnknownAgentError for an agent id that is not in the seed roster —
+the API route maps it to 404.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import threading
+import time
+from xml.sax.saxutils import escape as _xml_escape
+
+from reportlab.lib import colors
+from reportlab.lib.pagesizes import A4
+from reportlab.lib.styles import ParagraphStyle
+from reportlab.lib.units import mm  # noqa: F401  (kept: handy for tweaks)
+from reportlab.platypus import (
+    Flowable,
+    HRFlowable,
+    Paragraph,
+    SimpleDocTemplate,
+    Spacer,
+    Table,
+    TableStyle,
+)
+
+from atp import store, tenant_db
+
+# ── Palette — mirrors design/styles.css (ATP / Agent view tokens) ───────────
+
+NAVY = colors.HexColor("#0a0e22")        # --c-bg (header band)
+NAVY_ELEV = colors.HexColor("#0f1733")   # --c-bg-elev
+GOLD = colors.HexColor("#e8c268")        # --c-cert (on navy)
+GOLD_PAPER = colors.HexColor("#a3801f")  # --c-cert, paper palette (rules)
+INK = colors.HexColor("#1c2237")
+INK_MUTED = colors.HexColor("#5d6688")
+LINE = colors.HexColor("#c9cede")
+PANEL = colors.HexColor("#f4f5f9")
+CORAL = colors.HexColor("#c2403f")       # revoked / weak (paper-legible)
+AMBER = colors.HexColor("#b45309")       # developing
+GREEN = colors.HexColor("#2f7d4a")       # strong
+GREY = colors.HexColor("#9ca3af")        # untested
+
+#: layer palette (--c-atp-l1..l7), darkened where needed for white paper.
+LAYER_COLORS = {
+    1: colors.HexColor("#2f7fae"), 2: colors.HexColor("#1f8a63"),
+    3: colors.HexColor("#b45309"), 4: colors.HexColor("#c2410c"),
+    5: colors.HexColor("#c2403f"), 6: colors.HexColor("#7c5cbf"),
+    7: GOLD_PAPER,
+}
+
+_STATUS_COLORS = {
+    "strong": GREEN, "developing": AMBER, "weak": CORAL,
+    "untested": GREY, "active": GREEN, "training": AMBER, "revoked": CORAL,
+}
+
+PAGE_W, PAGE_H = A4
+MARGIN = 48
+BAND_H = 92          # first-page navy header band
+BAND_H_LATER = 24    # thin band on later pages
+FOOTER_H = 78
+
+_MONO, _MONO_B = "Courier", "Courier-Bold"
+_SANS, _SANS_B, _SANS_I = "Helvetica", "Helvetica-Bold", "Helvetica-Oblique"
+
+
+class UnknownAgentError(ValueError):
+    """agent_id is not in the seed roster (atp/seed.py AGENTS)."""
+
+
+# ── DB readiness (same lazy idiom as api/atp.py) ────────────────────────────
+
+_DB_READY = False
+_DB_LOCK = threading.Lock()
+
+
+def _ensure_db() -> None:
+    global _DB_READY
+    if _DB_READY:
+        return
+    with _DB_LOCK:
+        if not _DB_READY:
+            from atp import db
+            db.run_migrations()
+            _DB_READY = True
+
+
+# ── Data assembly ───────────────────────────────────────────────────────────
+
+def _find_agent(data: dict, agent_id: str) -> dict:
+    for a in data.get("AGENTS", []):
+        if a.get("id") == agent_id:
+            return a
+    raise UnknownAgentError(
+        f"agent {agent_id!r} not found in the seed roster (atp/seed.py)")
+
+
+def _seed_cert_rows(data: dict, agent_id: str) -> list[dict]:
+    """Seed awards for the agent: one row per cert grant, oldest first."""
+    rows = []
+    for cert in data.get("CERTS", []):
+        for award in cert.get("awards", []):
+            if award.get("agentId") != agent_id:
+                continue
+            rows.append({
+                "label": cert["label"],
+                "domain": cert["domain"],
+                "layer": cert["layer"],
+                "score": award.get("score"),
+                "ts": award.get("ts", ""),
+                "revoked": award.get("status") == "revoked",
+                "revokedTs": award.get("revokedTs"),
+                "live": False,
+                "dryRun": False,
+            })
+    rows.sort(key=lambda r: r["ts"])
+    return rows
+
+
+def _loads_maybe(v):
+    if not isinstance(v, str):
+        return v
+    try:
+        return json.loads(v)
+    except (json.JSONDecodeError, ValueError):
+        return v
+
+
+def _live_cert_rows(data: dict, agent_id: str, org_id: str) -> list[dict]:
+    """Live atp_cert_awards rows for the agent (org-scoped), oldest first.
+
+    DRY-RUN detection: an award's evidence rows (written in the same exam
+    run by atp/exams.py) record the candidate spec in their payload; if any
+    resolves to the deterministic dry-run backend ('dryrun:*'), the award is
+    marked so the table can never present a stub exam as a real one.
+    """
+    _ensure_db()
+    awards = tenant_db.scoped_query(
+        org_id,
+        "SELECT id, ts, cert_id, score, evidence_ids FROM atp_cert_awards"
+        " WHERE org_id = :org AND agent_id = :aid ORDER BY id ASC",
+        {"org": org_id, "aid": agent_id})
+    if not awards:
+        return []
+
+    ev_rows = tenant_db.scoped_query(
+        org_id,
+        "SELECT id, payload FROM atp_evidence"
+        " WHERE org_id = :org AND agent_id = :aid",
+        {"org": org_id, "aid": agent_id})
+    candidate_by_id: dict[str, str] = {}
+    for row in ev_rows:
+        payload = _loads_maybe(row.get("payload"))
+        if isinstance(payload, dict):
+            candidate_by_id[str(row["id"])] = str(payload.get("candidate", ""))
+
+    certs_by_id = {c["id"]: c for c in data.get("CERTS", [])}
+    out = []
+    for aw in awards:
+        cert = certs_by_id.get(aw.get("cert_id"), {})
+        evidence_ids = _loads_maybe(aw.get("evidence_ids")) or []
+        dry = any(
+            candidate_by_id.get(str(eid), "").startswith("dryrun")
+            for eid in evidence_ids)
+        out.append({
+            "label": cert.get("label", aw.get("cert_id", "?")),
+            "domain": cert.get("domain", "—"),
+            "layer": cert.get("layer", "—"),
+            "score": aw.get("score"),
+            # Live award ts is a full ISO stamp; the table shows the date
+            # (seed award dates are already date-only).
+            "ts": str(aw.get("ts") or "")[:10],
+            "revoked": False,
+            "revokedTs": None,
+            "live": True,
+            "dryRun": dry,
+        })
+    return out
+
+
+def _live_evidence_count(agent_id: str, org_id: str) -> int:
+    _ensure_db()
+    rows = tenant_db.scoped_query(
+        org_id,
+        "SELECT COUNT(*) AS n FROM atp_evidence"
+        " WHERE org_id = :org AND agent_id = :aid",
+        {"org": org_id, "aid": agent_id})
+    return int(rows[0]["n"]) if rows else 0
+
+
+def _citation(data: dict, agent: dict) -> str:
+    """The citable sentence (STANDARD.sentence grammar); honest on revoke."""
+    domain = (agent.get("domains") or ["—"])[0]
+    if agent.get("status") == "revoked":
+        return (f"{agent['name']} is NOT currently ATP-certified in {domain}: "
+                f"its L{agent['level']} certification was revoked.")
+    template = data.get("STANDARD", {}).get(
+        "sentence", "{agent} is an ATP L{n}-certified agent in {domain}.")
+    return (template.replace("{agent}", agent["name"])
+                    .replace("{n}", str(agent["level"]))
+                    .replace("{domain}", domain))
+
+
+# ── Small flowables ─────────────────────────────────────────────────────────
+
+class _MasteryBar(Flowable):
+    """Simple filled-rect mastery bar (per the UI's mastery meters)."""
+
+    def __init__(self, fraction: float, status: str,
+                 width: float = 108, height: float = 7):
+        super().__init__()
+        self.fraction = max(0.0, min(1.0, float(fraction or 0.0)))
+        self.fill = _STATUS_COLORS.get(status, GREY)
+        self.width, self.height = width, height
+
+    def wrap(self, availWidth, availHeight):  # noqa: N803 (reportlab API)
+        return self.width, self.height
+
+    def draw(self):
+        c = self.canv
+        c.setFillColor(PANEL)
+        c.rect(0, 0, self.width, self.height, stroke=0, fill=1)
+        if self.fraction > 0:
+            c.setFillColor(self.fill)
+            c.rect(0, 0, self.width * self.fraction, self.height,
+                   stroke=0, fill=1)
+        c.setStrokeColor(LINE)
+        c.setLineWidth(0.5)
+        c.rect(0, 0, self.width, self.height, stroke=1, fill=0)
+
+
+# ── Paragraph styles ────────────────────────────────────────────────────────
+
+def _styles() -> dict[str, ParagraphStyle]:
+    return {
+        "h1": ParagraphStyle("h1", fontName=_SANS_B, fontSize=17,
+                             leading=21, textColor=INK),
+        "section": ParagraphStyle("section", fontName=_MONO_B, fontSize=9.5,
+                                  leading=12, textColor=NAVY_ELEV,
+                                  spaceBefore=6),
+        "body": ParagraphStyle("body", fontName=_SANS, fontSize=9.5,
+                               leading=13.5, textColor=INK),
+        "bullet": ParagraphStyle("bullet", fontName=_SANS, fontSize=9.5,
+                                 leading=13.5, textColor=INK,
+                                 leftIndent=10, bulletIndent=2),
+        "cell": ParagraphStyle("cell", fontName=_SANS, fontSize=8.5,
+                               leading=11, textColor=INK),
+        "cellMono": ParagraphStyle("cellMono", fontName=_MONO, fontSize=8,
+                                   leading=10.5, textColor=INK),
+        "labelMono": ParagraphStyle("labelMono", fontName=_MONO, fontSize=7,
+                                    leading=9, textColor=INK_MUTED),
+        "note": ParagraphStyle("note", fontName=_SANS_I, fontSize=8.5,
+                               leading=11.5, textColor=INK_MUTED),
+    }
+
+
+def _esc(s) -> str:
+    return _xml_escape(str(s if s is not None else "—"))
+
+
+def _rule(color=GOLD_PAPER, thickness=1.1):
+    return HRFlowable(width="100%", thickness=thickness, color=color,
+                      spaceBefore=1, spaceAfter=6)
+
+
+def _section(title: str, story: list, st: dict) -> None:
+    story.append(Spacer(1, 10))
+    story.append(Paragraph(_esc(title.upper()), st["section"]))
+    story.append(_rule())
+
+
+# ── Page decoration (header band + footer, drawn on the canvas) ────────────
+
+def _make_page_decorators(agent: dict, citation: str, n_evidence: int,
+                          generated_at: str):
+    agent_name = agent.get("name", agent["id"])
+    deep_link = f"#/agent/{agent['id']}"
+
+    def _footer(canv, doc):
+        canv.saveState()
+        y = FOOTER_H - 20
+        canv.setStrokeColor(GOLD_PAPER)
+        canv.setLineWidth(1)
+        canv.line(MARGIN, y, PAGE_W - MARGIN, y)
+        canv.setFont(_SANS_I, 8)
+        canv.setFillColor(INK)
+        canv.drawString(MARGIN, y - 11, f"“{citation}”")
+        canv.setFont(_MONO, 6.8)
+        canv.setFillColor(INK_MUTED)
+        canv.drawString(
+            MARGIN, y - 22,
+            f"{deep_link} · generated {generated_at} · "
+            f"evidence: {n_evidence} signed records — "
+            f"verify at /atp/chain/verify")
+        canv.setFont(_MONO, 7)
+        canv.drawRightString(PAGE_W - MARGIN, y - 11,
+                             f"PAGE {canv.getPageNumber()}")
+        canv.restoreState()
+
+    def first_page(canv, doc):
+        canv.saveState()
+        canv.setFillColor(NAVY)
+        canv.rect(0, PAGE_H - BAND_H, PAGE_W, BAND_H, stroke=0, fill=1)
+        canv.setFillColor(GOLD)
+        canv.setFont(_MONO_B, 8.5)
+        canv.drawString(MARGIN, PAGE_H - 30,
+                        "ATP — AGENTIC TRAINING PLATFORM")
+        canv.setFont(_MONO, 7)
+        canv.drawRightString(PAGE_W - MARGIN, PAGE_H - 30,
+                             "STANDARD ATP@2026.1")
+        canv.setFillColor(colors.white)
+        canv.setFont(_SANS_B, 19)
+        canv.drawString(MARGIN, PAGE_H - 56, "Official Report Card")
+        canv.setFillColor(colors.HexColor("#9aa3c0"))
+        canv.setFont(_MONO, 7.5)
+        canv.drawString(MARGIN, PAGE_H - 72,
+                        "EVIDENCE-LINKED · REPRODUCIBLE · "
+                        "FAILURE-TRANSPARENT · REVOCABLE")
+        canv.setStrokeColor(GOLD)
+        canv.setLineWidth(2)
+        canv.line(0, PAGE_H - BAND_H, PAGE_W, PAGE_H - BAND_H)
+        canv.restoreState()
+        _footer(canv, doc)
+
+    def later_pages(canv, doc):
+        canv.saveState()
+        canv.setFillColor(NAVY)
+        canv.rect(0, PAGE_H - BAND_H_LATER, PAGE_W, BAND_H_LATER,
+                  stroke=0, fill=1)
+        canv.setFillColor(GOLD)
+        canv.setFont(_MONO_B, 7.5)
+        canv.drawString(MARGIN, PAGE_H - 16,
+                        f"ATP — OFFICIAL REPORT CARD · "
+                        f"{agent_name.upper()}")
+        canv.setStrokeColor(GOLD)
+        canv.setLineWidth(1.2)
+        canv.line(0, PAGE_H - BAND_H_LATER, PAGE_W, PAGE_H - BAND_H_LATER)
+        canv.restoreState()
+        _footer(canv, doc)
+
+    return first_page, later_pages
+
+
+# ── Story sections ──────────────────────────────────────────────────────────
+
+def _identity_block(agent: dict, story: list, st: dict) -> None:
+    status = agent.get("status", "—")
+    status_color = _STATUS_COLORS.get(status, INK)
+    story.append(Paragraph(_esc(agent.get("name", agent["id"])), st["h1"]))
+    story.append(Spacer(1, 4))
+
+    labels = ["AGENT ID", "BASE MODEL", "LEVEL", "CAREER STAGE", "TIER",
+              "STATUS"]
+    values = [
+        Paragraph(_esc(agent["id"]), st["cellMono"]),
+        Paragraph(_esc(agent.get("baseModel")), st["cell"]),
+        Paragraph(
+            f'<font name="{_MONO_B}" color="{LAYER_COLORS.get(agent.get("level"), INK).hexval()}">'
+            f'L{_esc(agent.get("level"))}</font>', st["cell"]),
+        Paragraph(_esc(agent.get("careerStage")), st["cell"]),
+        Paragraph(_esc(agent.get("tier")), st["cell"]),
+        Paragraph(
+            f'<font name="{_SANS_B}" color="{status_color.hexval()}">'
+            f'{_esc(status.upper())}</font>', st["cell"]),
+    ]
+    # AGENT ID gets the widest column so long slugs (gemma-physics-ocw)
+    # never wrap mid-word in the mono face.
+    w = PAGE_W - 2 * MARGIN
+    col_w = [w * f for f in (0.21, 0.17, 0.10, 0.16, 0.15, 0.21)]
+    table = Table(
+        [[Paragraph(lbl, st["labelMono"]) for lbl in labels], values],
+        colWidths=col_w)
+    table.setStyle(TableStyle([
+        ("TOPPADDING", (0, 0), (-1, -1), 1),
+        ("BOTTOMPADDING", (0, 0), (-1, 0), 0),
+        ("BOTTOMPADDING", (0, 1), (-1, 1), 4),
+        ("LEFTPADDING", (0, 0), (-1, -1), 0),
+        ("RIGHTPADDING", (0, 0), (-1, -1), 4),
+        ("LINEBELOW", (0, 1), (-1, 1), 0.5, LINE),
+    ]))
+    story.append(table)
+
+    prov = agent.get("provenance") or {}
+    if prov.get("origin") == "commissioned":
+        corpora = ", ".join(prov.get("corpora") or []) or "—"
+        req = prov.get("requestId") or "—"
+        story.append(Spacer(1, 5))
+        story.append(Paragraph(
+            f"PROVENANCE: COMMISSIONED (TRAIN-TO-ORDER) · "
+            f"CORPORA: {_esc(corpora)} · REQUEST: {_esc(req)}",
+            ParagraphStyle("prov", parent=st["cellMono"], fontSize=7.5,
+                           textColor=GOLD_PAPER)))
+        story.append(Paragraph(
+            "This agent was trained to order for a specific corpus and "
+            "certified through the identical exam blueprint as every "
+            "pre-existing agent — there is no separate trust tier for "
+            "commissioned experts.", st["note"]))
+
+    if agent.get("status") == "revoked":
+        story.append(Spacer(1, 7))
+        warn = Table([[Paragraph(
+            f'<font name="{_SANS_B}" color="{CORAL.hexval()}">'
+            f'CERTIFICATION REVOKED.</font> '
+            f'The ATP board has revoked this agent’s badge; the record '
+            f'below stays public on purpose (the “revocable” '
+            f'principle). See the certifications table and the failure '
+            f'transparency section before relying on this agent for '
+            f'anything.', st["cell"])]],
+            colWidths=[PAGE_W - 2 * MARGIN])
+        warn.setStyle(TableStyle([
+            ("BACKGROUND", (0, 0), (-1, -1), colors.HexColor("#faeceb")),
+            ("BOX", (0, 0), (-1, -1), 0.8, CORAL),
+            ("TOPPADDING", (0, 0), (-1, -1), 6),
+            ("BOTTOMPADDING", (0, 0), (-1, -1), 6),
+            ("LEFTPADDING", (0, 0), (-1, -1), 8),
+            ("RIGHTPADDING", (0, 0), (-1, -1), 8),
+        ]))
+        story.append(warn)
+
+
+def _report_card_block(agent: dict, story: list, st: dict) -> None:
+    rc = agent.get("reportCard") or {}
+    _section("Report card — in plain language", story, st)
+    if rc.get("summary"):
+        story.append(Paragraph(_esc(rc["summary"]), st["body"]))
+        story.append(Spacer(1, 6))
+    if rc.get("strengths"):
+        story.append(Paragraph("<b>Strengths</b>", st["body"]))
+        for s in rc["strengths"]:
+            story.append(Paragraph(_esc(s), st["bullet"],
+                                   bulletText="–"))
+        story.append(Spacer(1, 5))
+    if rc.get("weaknesses"):
+        story.append(Paragraph("<b>Weaknesses</b>", st["body"]))
+        for w in rc["weaknesses"]:
+            story.append(Paragraph(_esc(w), st["bullet"],
+                                   bulletText="–"))
+        story.append(Spacer(1, 5))
+    if rc.get("recommendation"):
+        rec = Table([[Paragraph(
+            f"<b>Recommendation</b> — {_esc(rc['recommendation'])}",
+            st["cell"])]], colWidths=[PAGE_W - 2 * MARGIN])
+        rec.setStyle(TableStyle([
+            ("BACKGROUND", (0, 0), (-1, -1), PANEL),
+            ("BOX", (0, 0), (-1, -1), 0.6, GOLD_PAPER),
+            ("TOPPADDING", (0, 0), (-1, -1), 6),
+            ("BOTTOMPADDING", (0, 0), (-1, -1), 6),
+            ("LEFTPADDING", (0, 0), (-1, -1), 8),
+            ("RIGHTPADDING", (0, 0), (-1, -1), 8),
+        ]))
+        story.append(rec)
+
+
+def _cert_table(rows: list[dict], story: list, st: dict) -> None:
+    _section("Certifications", story, st)
+    if not rows:
+        story.append(Paragraph(
+            "No certifications on record. This agent has not yet passed an "
+            "ATP exam.", st["note"]))
+        return
+
+    header = ["CERTIFICATION", "DOMAIN", "LAYER", "SCORE", "DATE", "STATUS"]
+    data = [[Paragraph(h, st["labelMono"]) for h in header]]
+    styles = TableStyle([
+        ("BACKGROUND", (0, 0), (-1, 0), NAVY),
+        ("LINEBELOW", (0, 0), (-1, -1), 0.4, LINE),
+        ("TOPPADDING", (0, 0), (-1, -1), 4),
+        ("BOTTOMPADDING", (0, 0), (-1, -1), 4),
+        ("LEFTPADDING", (0, 0), (-1, -1), 5),
+        ("RIGHTPADDING", (0, 0), (-1, -1), 5),
+        ("VALIGN", (0, 0), (-1, -1), "TOP"),
+    ])
+    header_lbl = ParagraphStyle("hdr", parent=st["labelMono"],
+                                textColor=GOLD)
+    data[0] = [Paragraph(h, header_lbl) for h in header]
+
+    for i, r in enumerate(rows, start=1):
+        layer_color = LAYER_COLORS.get(r["layer"], INK)
+        if r["revoked"]:
+            status_txt = (f'<font name="{_MONO_B}" color="{CORAL.hexval()}">'
+                          f'REVOKED {_esc(r.get("revokedTs") or "")}</font>')
+        elif r["live"] and r["dryRun"]:
+            status_txt = (f'<font name="{_MONO_B}" '
+                          f'color="{AMBER.hexval()}">LIVE · DRY-RUN'
+                          f'</font>')
+        elif r["live"]:
+            status_txt = (f'<font name="{_MONO_B}" '
+                          f'color="{GREEN.hexval()}">LIVE EXAM</font>')
+        else:
+            status_txt = (f'<font name="{_MONO}" '
+                          f'color="{GREEN.hexval()}">granted</font>')
+        score = r.get("score")
+        data.append([
+            Paragraph(_esc(r["label"]), st["cellMono"]),
+            Paragraph(_esc(r["domain"]), st["cell"]),
+            Paragraph(
+                f'<font name="{_MONO_B}" color="{layer_color.hexval()}">'
+                f'L{_esc(r["layer"])}</font>', st["cell"]),
+            Paragraph("—" if score is None else f"{float(score):.2f}",
+                      st["cellMono"]),
+            Paragraph(_esc(r["ts"]), st["cellMono"]),
+            Paragraph(status_txt, st["cellMono"]),
+        ])
+        if r["revoked"]:
+            styles.add("BACKGROUND", (0, i), (-1, i),
+                       colors.HexColor("#faeceb"))
+
+    w = PAGE_W - 2 * MARGIN
+    table = Table(data, colWidths=[w * 0.30, w * 0.17, w * 0.08, w * 0.10,
+                                   w * 0.15, w * 0.20], repeatRows=1)
+    table.setStyle(styles)
+    story.append(table)
+    if any(r["live"] and r["dryRun"] for r in rows):
+        story.append(Spacer(1, 3))
+        story.append(Paragraph(
+            "DRY-RUN entries were produced by the deterministic CI stub "
+            "backend, not a live model — they demonstrate the exam "
+            "pipeline and are not real certifications.", st["note"]))
+
+
+def _skills_table(agent: dict, story: list, st: dict) -> None:
+    _section("Skills — measured mastery", story, st)
+    skills = agent.get("skills") or []
+    if not skills:
+        story.append(Paragraph("No skills on record.", st["note"]))
+        return
+    header_lbl = ParagraphStyle("hdr2", parent=st["labelMono"],
+                                textColor=GOLD)
+    data = [[Paragraph(h, header_lbl)
+             for h in ("SKILL", "LAYER", "MASTERY", "SCORE", "STATUS")]]
+    for s in skills:
+        status = s.get("status", "untested")
+        color = _STATUS_COLORS.get(status, GREY)
+        mastery = float(s.get("mastery") or 0.0)
+        data.append([
+            Paragraph(_esc(s.get("name")), st["cell"]),
+            Paragraph(
+                f'<font name="{_MONO}" '
+                f'color="{LAYER_COLORS.get(s.get("layer"), INK).hexval()}">'
+                f'L{_esc(s.get("layer"))}</font>', st["cell"]),
+            _MasteryBar(mastery, status),
+            Paragraph(f"{mastery:.2f}", st["cellMono"]),
+            Paragraph(
+                f'<font name="{_MONO}" color="{color.hexval()}">'
+                f'{_esc(status)}</font>', st["cellMono"]),
+        ])
+    w = PAGE_W - 2 * MARGIN
+    table = Table(data, colWidths=[w * 0.36, w * 0.09, w * 0.27, w * 0.10,
+                                   w * 0.18], repeatRows=1)
+    table.setStyle(TableStyle([
+        ("BACKGROUND", (0, 0), (-1, 0), NAVY),
+        ("LINEBELOW", (0, 0), (-1, -1), 0.4, LINE),
+        ("TOPPADDING", (0, 0), (-1, -1), 3.5),
+        ("BOTTOMPADDING", (0, 0), (-1, -1), 3.5),
+        ("LEFTPADDING", (0, 0), (-1, -1), 5),
+        ("RIGHTPADDING", (0, 0), (-1, -1), 5),
+        ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+    ]))
+    story.append(table)
+    story.append(Spacer(1, 3))
+    story.append(Paragraph(
+        "“untested” means exactly that: the skill has not been "
+        "measured yet. ATP shows uncertainty rather than hiding it.",
+        st["note"]))
+
+
+def _failure_table(agent: dict, story: list, st: dict) -> None:
+    _section("Failure transparency — where this agent breaks", story, st)
+    story.append(Paragraph(
+        "The ATP standard publishes failure modes next to the passes. This "
+        "section is part of the official record — a badge tells you not "
+        "only what the agent can do, but concretely where it will fail.",
+        st["note"]))
+    story.append(Spacer(1, 4))
+    failures = agent.get("failures") or []
+    if not failures:
+        story.append(Paragraph(
+            "No failure modes recorded yet — usually a sign the agent "
+            "is too new to have been stress-tested, not that it is perfect.",
+            st["note"]))
+        return
+    header_lbl = ParagraphStyle("hdr3", parent=st["labelMono"],
+                                textColor=GOLD)
+    data = [[Paragraph(h, header_lbl)
+             for h in ("FAILURE MODE", "RATE", "BOUNDARY — WHEN NOT TO "
+                       "TRUST IT")]]
+    for f in failures:
+        rate = float(f.get("rate") or 0.0)
+        data.append([
+            Paragraph(f"<b>{_esc(f.get('mode'))}</b>", st["cell"]),
+            Paragraph(
+                f'<font name="{_MONO_B}" color="{CORAL.hexval()}">'
+                f'{rate:.0%}</font>', st["cellMono"]),
+            Paragraph(_esc(f.get("boundary")), st["cell"]),
+        ])
+    w = PAGE_W - 2 * MARGIN
+    table = Table(data, colWidths=[w * 0.27, w * 0.09, w * 0.64],
+                  repeatRows=1)
+    table.setStyle(TableStyle([
+        ("BACKGROUND", (0, 0), (-1, 0), NAVY),
+        ("LINEBELOW", (0, 0), (-1, -1), 0.4, LINE),
+        ("TOPPADDING", (0, 0), (-1, -1), 4),
+        ("BOTTOMPADDING", (0, 0), (-1, -1), 4),
+        ("LEFTPADDING", (0, 0), (-1, -1), 5),
+        ("RIGHTPADDING", (0, 0), (-1, -1), 5),
+        ("VALIGN", (0, 0), (-1, -1), "TOP"),
+    ]))
+    story.append(table)
+
+
+# ── Public builder ──────────────────────────────────────────────────────────
+
+def build_report_card_pdf(agent_id: str,
+                          org_id: str = tenant_db.DEFAULT_ORG) -> bytes:
+    """Render the official report-card PDF for `agent_id` → PDF bytes.
+
+    Seed profile + prose from atp/store.get_data(); live awards/evidence for
+    the caller's org via atp/tenant_db.py. Raises UnknownAgentError when the
+    agent is not in the seed roster.
+    """
+    data = store.get_data()
+    agent = _find_agent(data, agent_id)
+
+    cert_rows = _seed_cert_rows(data, agent_id)
+    cert_rows += _live_cert_rows(data, agent_id, org_id)
+
+    seed_evidence = sum(
+        1 for e in data.get("EVIDENCE", []) if e.get("agentId") == agent_id)
+    n_evidence = seed_evidence + _live_evidence_count(agent_id, org_id)
+
+    generated_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    citation = _citation(data, agent)
+    st = _styles()
+
+    buf = io.BytesIO()
+    doc = SimpleDocTemplate(
+        buf, pagesize=A4,
+        leftMargin=MARGIN, rightMargin=MARGIN,
+        topMargin=BAND_H + 22, bottomMargin=FOOTER_H,
+        title=f"ATP Official Report Card — {agent.get('name', agent_id)}",
+        author="ATP — Agentic Training Platform")
+
+    story: list = []
+    _identity_block(agent, story, st)
+    _report_card_block(agent, story, st)
+    _cert_table(cert_rows, story, st)
+    _skills_table(agent, story, st)
+    _failure_table(agent, story, st)
+
+    first_page, later_pages = _make_page_decorators(
+        agent, citation, n_evidence, generated_at)
+    doc.build(story, onFirstPage=first_page, onLaterPages=later_pages)
+    return buf.getvalue()
+
+
+# ── CLI (dev convenience) ───────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Render an agent's official report-card PDF (Phase 6).")
+    parser.add_argument("agent_id", help="e.g. atlas-ops")
+    parser.add_argument("out", help="output .pdf path")
+    parser.add_argument("--org", default=tenant_db.DEFAULT_ORG)
+    args = parser.parse_args()
+
+    pdf = build_report_card_pdf(args.agent_id, org_id=args.org)
+    with open(args.out, "wb") as fh:
+        fh.write(pdf)
+    print(f"wrote {len(pdf)} bytes to {args.out}")

atp/signing.py

@@ -0,0 +1,237 @@
+"""
+Evidence signing — HMAC-SHA256 over canonical payloads, per-org hash chain.
+
+Phase 3 (docs/HARDENING.md): every evidence row written by atp/exams.py is
+signed so the append-only tables (migration 002 triggers) become
+tamper-EVIDENT, not just append-only:
+
+    sig       = HMAC-SHA256(key, prev_hash || canonical(payload))
+    prev_hash = sig of the previous atp_evidence row for the SAME org
+                ('genesis' for an org's first row)
+
+Editing any historical payload breaks that row's sig; deleting or reordering
+rows breaks the prev_hash linkage — verify_chain() catches both.
+
+Key resolution (fail-loud, mirrors api/auth.py's posture):
+
+    EVIDENCE_SIGNING_KEY      required whenever signing/verification happens
+                              with auth enabled — RuntimeError if unset.
+    BU_AUTH_DISABLED=1 (dev)  fallback: derive a stable key from
+                              BU_AUTH_SECRET when set, else a process-
+                              ephemeral random key with a loud warning
+                              (sigs then don't verify across restarts).
+
+Public:
+    canonical(payload) -> bytes           stable JSON bytes (sorted keys,
+                                          no whitespace drift)
+    sign(payload, prev_hash) -> str       hex HMAC-SHA256
+    verify_row(row) -> bool               recompute + constant-time compare
+    last_sig(org_id) -> str               chain head for an org ('genesis'
+                                          when the org has no evidence yet)
+    verify_chain(org_id) -> dict          {ok, length, first_bad} walking
+                                          atp_evidence in id order (org-scoped
+                                          via atp/tenant_db.py)
+    GENESIS                               the chain-root sentinel string
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import sys
+import threading
+
+from sqlalchemy import text
+
+from atp import db, tenant_db
+
+#: prev_hash sentinel for the first evidence row of an org's chain.
+GENESIS = "genesis"
+
+#: Domain-separation tag for the BU_AUTH_SECRET-derived dev key.
+_DERIVE_TAG = b"bu-evidence-signing-v1:"
+
+_EPHEMERAL_KEY: bytes | None = None
+_WARNED = False
+
+
+class SigningKeyError(RuntimeError):
+    """Signing was requested but no usable key is configured."""
+
+
+def _signing_key() -> bytes:
+    """Resolve the HMAC key (see module docstring for the precedence)."""
+    global _EPHEMERAL_KEY, _WARNED
+    key = os.environ.get("EVIDENCE_SIGNING_KEY", "").strip()
+    if key:
+        return key.encode("utf-8")
+
+    if os.environ.get("BU_AUTH_DISABLED", "") == "1":
+        # Dev mode: never block the loop, but never sign with a hardcoded
+        # default either — derive from the auth secret when one exists.
+        auth_secret = os.environ.get("BU_AUTH_SECRET", "").strip()
+        if auth_secret:
+            return hashlib.sha256(_DERIVE_TAG + auth_secret.encode("utf-8")).digest()
+        if _EPHEMERAL_KEY is None:
+            _EPHEMERAL_KEY = secrets.token_bytes(32)
+        if not _WARNED:
+            _WARNED = True
+            print(
+                "WARNING: EVIDENCE_SIGNING_KEY unset (BU_AUTH_DISABLED=1 dev "
+                "mode) — signing evidence with a process-EPHEMERAL key. "
+                "Signatures will NOT verify after a restart. Set "
+                "EVIDENCE_SIGNING_KEY (see .env.example).",
+                file=sys.stderr,
+            )
+        return _EPHEMERAL_KEY
+
+    raise SigningKeyError(
+        "EVIDENCE_SIGNING_KEY is not set. Evidence signing is mandatory when "
+        "auth is enabled (docs/HARDENING.md Phase 3) — generate one with "
+        "python3 -c \"import secrets; print(secrets.token_hex(32))\" and "
+        "export it, or export BU_AUTH_DISABLED=1 for local dev only."
+    )
+
+
+# ── Canonicalisation + signing ───────────────────────────────────────────────
+
+def canonical(payload: dict) -> bytes:
+    """Stable byte serialisation of a payload dict.
+
+    json.dumps with sorted keys, compact separators, and ensure_ascii=True:
+    key order, whitespace, and non-ASCII escaping can never drift between the
+    signer and a later verifier (including across Python versions).
+    """
+    return json.dumps(
+        payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True
+    ).encode("utf-8")
+
+
+def sign(payload: dict, prev_hash: str) -> str:
+    """Hex HMAC-SHA256 over prev_hash || canonical(payload)."""
+    msg = (prev_hash or GENESIS).encode("utf-8") + canonical(payload)
+    return hmac.new(_signing_key(), msg, hashlib.sha256).hexdigest()
+
+
+def verify_row(row: dict) -> bool:
+    """Recompute a row's sig from its stored payload + prev_hash.
+
+    `row` needs keys payload (JSON text or dict), sig, prev_hash — i.e. an
+    atp_evidence row as returned by the DAL. Constant-time compare.
+    """
+    payload = row.get("payload")
+    if isinstance(payload, (str, bytes)):
+        try:
+            payload = json.loads(payload)
+        except (ValueError, TypeError):
+            return False
+    if not isinstance(payload, dict):
+        return False
+    expected = sign(payload, row.get("prev_hash") or GENESIS)
+    return hmac.compare_digest(expected, str(row.get("sig") or ""))
+
+
+# ── Chain access (org-scoped, via the tenant DAL only) ──────────────────────
+
+def last_sig(org_id: str) -> str:
+    """Current chain head for an org: sig of its newest evidence row,
+    or GENESIS when the org has no evidence yet."""
+    rows = tenant_db.scoped_query(
+        org_id,
+        "SELECT sig FROM atp_evidence WHERE org_id = :org "
+        "ORDER BY id DESC LIMIT 1",
+        {"org": org_id},
+    )
+    return rows[0]["sig"] if rows and rows[0].get("sig") else GENESIS
+
+
+# ── Serialized chain append (the ONLY sanctioned way to write evidence) ─────
+
+_CHAIN_LOCKS: dict[str, threading.Lock] = {}
+_CHAIN_LOCKS_GUARD = threading.Lock()
+
+
+def _chain_lock(org_id: str) -> threading.Lock:
+    with _CHAIN_LOCKS_GUARD:
+        return _CHAIN_LOCKS.setdefault(org_id, threading.Lock())
+
+
+def append_chain(org_id: str, records: list[dict]) -> list[tuple[int, str]]:
+    """Append `records` to an org's evidence chain atomically, in order.
+
+    records: [{ts, agent_id, cert_id, kind, payload(dict)}, ...]
+    returns: [(row_id, sig), ...] in the same order.
+
+    Why this exists: the chain head (prev_hash) must be read and written
+    under mutual exclusion or two concurrent exam runs interleave and
+    permanently fork the ledger. Serialization is layered:
+      - per-org threading.Lock — serializes writers within one process
+        (the jobs pool runs multiple worker threads);
+      - Postgres: pg_advisory_xact_lock(hashtext(org)) inside the same
+        transaction — serializes across processes AND instances;
+      - SQLite: single-file DB, and multi-process SQLite is already
+        unsupported (Dockerfile: WORKERS>1 requires Postgres).
+    The whole batch is one transaction, so an exam's evidence lands
+    all-or-nothing — no partially signed runs on crash.
+    """
+    out: list[tuple[int, str]] = []
+    with _chain_lock(org_id):
+        with tenant_db.scoped_txn(org_id) as conn:
+            if db.is_postgres():
+                conn.execute(
+                    text("SELECT pg_advisory_xact_lock(hashtext(:org))"),
+                    {"org": org_id},
+                )
+            row = conn.execute(
+                text("SELECT sig FROM atp_evidence WHERE org_id = :org "
+                     "ORDER BY id DESC LIMIT 1"),
+                {"org": org_id},
+            ).first()
+            prev = row[0] if row and row[0] else GENESIS
+            for rec in records:
+                sig = sign(rec["payload"], prev)
+                r = conn.execute(
+                    text("INSERT INTO atp_evidence "
+                         "  (ts, agent_id, cert_id, kind, payload, sig, "
+                         "   prev_hash, org_id) "
+                         "VALUES (:ts, :agent_id, :cert_id, :kind, :payload, "
+                         "        :sig, :prev_hash, :org) "
+                         "RETURNING id"),
+                    {
+                        "ts": rec["ts"],
+                        "agent_id": rec["agent_id"],
+                        "cert_id": rec["cert_id"],
+                        "kind": rec["kind"],
+                        "payload": canonical(rec["payload"]).decode("utf-8"),
+                        "sig": sig,
+                        "prev_hash": prev,
+                        "org": org_id,
+                    },
+                ).first()
+                out.append((r[0], sig))
+                prev = sig
+    return out
+
+
+def verify_chain(org_id: str) -> dict:
+    """Walk an org's whole evidence chain in id order.
+
+    Returns {ok: bool, length: int, first_bad: int | None} where first_bad is
+    the id of the first row whose sig doesn't verify OR whose prev_hash
+    doesn't equal the previous row's sig (GENESIS for the first row).
+    """
+    rows = tenant_db.scoped_query(
+        org_id,
+        "SELECT id, payload, sig, prev_hash FROM atp_evidence "
+        "WHERE org_id = :org ORDER BY id ASC",
+        {"org": org_id},
+    )
+    prev = GENESIS
+    for row in rows:
+        if (row.get("prev_hash") or GENESIS) != prev or not verify_row(row):
+            return {"ok": False, "length": len(rows), "first_bad": row["id"]}
+        prev = row["sig"]
+    return {"ok": True, "length": len(rows), "first_bad": None}

atp/store.py

@@ -0,0 +1,406 @@
+"""
+ATP store — seed access plus the two append-only logs.
+
+  get_data()                      → the full ATP_DATA dict (seed, cached)
+  append_hitl(event) -> event     → enrich with weightedDelta + ts + auditId,
+                                     insert into the atp_hitl table
+  read_hitl(limit=100)            → HITL log, latest first
+  append_request(payload) -> req  → compute status via the compose matching
+                                     rule, build pipeline stages, insert into
+                                     the atp_requests table
+  read_requests(limit=100)        → request log, latest first
+
+Phase 1 (docs/HARDENING.md): both logs live in DAL tables (atp_hitl /
+atp_requests — migration 002; append-only enforced by DB triggers) instead of
+JSONL on ephemeral disk. Public shapes are unchanged: the same camelCase dict
+keys (snake_case columns mapped back, JSON-text columns decoded) and read_*
+still return latest-first lists. Legacy data/sessions/atp_hitl.jsonl /
+atp_requests.jsonl are imported once into their empty table on first access,
+then renamed to *.jsonl.imported (idempotent; the rename doubles as the
+cross-process claim so rows land exactly once).
+
+Phase 2 (docs/TENANCY.md): the four log functions take an OPTIONAL
+`org_id` keyword (default `'org-demo'`, the bootstrap org every pre-tenancy
+row belongs to — migration 005's column default). All table access is routed
+through atp/tenant_db.py: writes stamp org_id, reads add `WHERE org_id =
+:org`, and on Postgres every statement runs under `SET LOCAL app.org_id`
+(RLS). Existing callers that don't pass org_id keep the exact pre-tenancy
+behaviour against the demo org — signatures and returned shapes unchanged
+(returned dicts do NOT grow an org key). Legacy JSONL imports land in
+'org-demo'.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+import uuid
+from pathlib import Path
+
+from sqlalchemy import inspect as sa_inspect
+
+from . import tenant_db
+from .seed import build_seed
+from .tenant_db import DEFAULT_ORG
+
+PROJECT_ROOT = Path(__file__).parent.parent
+SESSIONS_DIR = PROJECT_ROOT / "data" / "sessions"
+LEGACY_HITL_LOG = SESSIONS_DIR / "atp_hitl.jsonl"          # pre-Phase-1 log
+LEGACY_REQUESTS_LOG = SESSIONS_DIR / "atp_requests.jsonl"  # pre-Phase-1 log
+
+_DATA: dict | None = None
+
+
+# ── Seed access ─────────────────────────────────────────────────────────────
+
+def get_data() -> dict:
+    """Return the full ATP_DATA payload. Cached — seed is pure data."""
+    global _DATA
+    if _DATA is None:
+        _DATA = build_seed()
+    return _DATA
+
+
+# ── HITL reward log (§1 formula) ────────────────────────────────────────────
+
+def append_hitl(event: dict, org_id: str = DEFAULT_ORG) -> dict:
+    """Enrich a HITL reward signal and append it to the audit table.
+
+    Input:  {agentId, layer, signal (+1|-1), reason, rater}
+    Adds:   ts, weightedDelta, auditId
+    Formula (§1): weightedDelta = signal × 0.2 × (weight[layer] / 0.26)
+    The row is stamped with `org_id` (docs/TENANCY.md); the returned dict
+    keeps its pre-tenancy shape.
+    """
+    data = get_data()
+    weights = data["RL"]["rewardWeights"]
+
+    layer = int(event.get("layer", 1))
+    signal = int(event.get("signal", 0))
+    weight = float(weights.get(f"L{layer}", 0.0))
+    weighted_delta = round(signal * 0.2 * (weight / 0.26), 5)
+
+    enriched = {
+        "ts": event.get("ts") or _now(),
+        "rater": event.get("rater", "anonymous"),
+        "agentId": event.get("agentId"),
+        "layer": layer,
+        "signal": signal,
+        "weightedDelta": weighted_delta,
+        "reason": event.get("reason", ""),
+        "auditId": f"audit-{uuid.uuid4().hex[:10]}",
+    }
+    _ensure_ready("atp_hitl", LEGACY_HITL_LOG, _HITL_COLS)
+    tenant_db.insert_scoped("atp_hitl", _to_row(enriched, _HITL_COLS), org_id)
+    return enriched
+
+
+def read_hitl(limit: int = 100, org_id: str = DEFAULT_ORG) -> list[dict]:
+    """Return `org_id`'s HITL log, latest first (capped at `limit`)."""
+    _ensure_ready("atp_hitl", LEGACY_HITL_LOG, _HITL_COLS)
+    return _read_latest("atp_hitl", _HITL_COLS, limit, org_id)
+
+
+# ── Compose / train-to-order requests (§7.2) ────────────────────────────────
+
+def append_request(payload: dict, org_id: str = DEFAULT_ORG) -> dict:
+    """Create an expert-composition request from a wizard submission.
+
+    Input:  {major, specialty, badgeIds, packId}
+    Computes status against the seed agents with the same matching rule as
+    the client-side `matchExperts`, builds the pipeline stages, appends to
+    the request table (stamped with `org_id`), and returns the request.
+    """
+    data = get_data()
+    badge_ids = list(payload.get("badgeIds") or [])
+    pack_id = payload.get("packId")
+    major = str(payload.get("major") or "")
+
+    status, matched_agent_id, gap = _match(
+        data, major, badge_ids, pack_id,
+        # Wizard sends the concentration id as `specialty` (§7.2 payload);
+        # accept an explicit concentrationId too for parity with matchExperts.
+        payload.get("concentrationId") or payload.get("specialty") or None)
+    pipeline = _pipeline_for(status)
+
+    req = {
+        "id": f"req-{uuid.uuid4().hex[:8]}",
+        "ts": _now(),
+        "major": major,
+        "specialty": payload.get("specialty", ""),
+        "badgeIds": badge_ids,
+        "packId": pack_id,
+        "layers": list(payload.get("layers") or []),
+        "corpora": list(payload.get("corpora") or []),
+        "status": status,
+        "matchedAgentId": matched_agent_id,
+        "gap": gap,
+        "pipeline": pipeline,
+        "resultAgentId": None,
+    }
+    _ensure_ready("atp_requests", LEGACY_REQUESTS_LOG, _REQUEST_COLS)
+    tenant_db.insert_scoped("atp_requests", _to_row(req, _REQUEST_COLS), org_id)
+    return req
+
+
+def read_requests(limit: int = 100, org_id: str = DEFAULT_ORG) -> list[dict]:
+    """Return `org_id`'s request log, latest first (capped at `limit`)."""
+    _ensure_ready("atp_requests", LEGACY_REQUESTS_LOG, _REQUEST_COLS)
+    return _read_latest("atp_requests", _REQUEST_COLS, limit, org_id)
+
+
+# ── Matching rule (mirrors atp_data.js matchExperts) ────────────────────────
+
+def _match(data: dict, major: str, badge_ids: list[str], pack_id, concentration_id=None):
+    """Return (status, matchedAgentId, gap) for a composition request.
+
+    Mirrors the client-side `matchExperts`: competencies come from the named
+    concentration if `concentration_id` is given, otherwise the union of every
+    concentration in the major.
+
+    exact  = agent whose skills cover all of those competencies AND holds every
+             requested badge AND (packId ? bound to pack policies : true)
+    partial → gap analysis; else training (commission).
+    """
+    # Resolve the concentration tolerantly: by id ('18-C') or display name
+    # ('Applied Mathematics', case-insensitive prefix). Unresolvable text
+    # (free-form specialty) falls back to the whole-major union rather than
+    # an empty competency set.
+    want = str(concentration_id).strip().lower() if concentration_id else ""
+    resolved = None
+    majors = [m for m in data["COMPOSE"]["majors"] if str(m["course"]) == str(major)]
+    if want:
+        for m in majors:
+            for cc in m["concentrations"]:
+                nm = cc.get("name", "").lower()
+                if cc["id"].lower() == want or nm == want or (nm and want.startswith(nm)):
+                    resolved = cc["id"]
+                    break
+            if resolved:
+                break
+
+    comps: list[str] = []
+    for m in majors:
+        for cc in m["concentrations"]:
+            if resolved and cc["id"] != resolved:
+                continue
+            comps.extend(cc.get("competencies", []))
+    comps = list(dict.fromkeys(comps))  # de-dup, keep order
+
+    pack_policies: list[str] = []
+    if pack_id:
+        pk = next((p for p in data["COMPOSE"]["packs"] if p["id"] == pack_id), None)
+        if pk:
+            pack_policies = list(pk.get("policyIds", []))
+
+    exact: list[str] = []
+    partials: list[dict] = []
+    for a in data["AGENTS"]:
+        if a.get("status") == "revoked":
+            continue
+        skill_names = {s["name"] for s in a.get("skills", [])}
+        cert_ids = set(a.get("certIds", []))
+        policy_ids = set(a.get("policyIds", []))
+
+        covered = [c for c in comps if c in skill_names]
+        missing = [c for c in comps if c not in skill_names]
+        holds_badges = all(b in cert_ids for b in badge_ids)
+        bound_pack = (not pack_id) or all(p in policy_ids for p in pack_policies)
+
+        if comps and not missing and holds_badges and bound_pack:
+            exact.append(a["id"])
+        elif covered or any(b in cert_ids for b in badge_ids):
+            partials.append({"agentId": a["id"], "covered": covered, "missing": missing})
+
+    if exact:
+        return "matched", exact[0], None
+
+    if partials:
+        partials.sort(key=lambda p: len(p["covered"]), reverse=True)
+        covered = sorted({c for p in partials for c in p["covered"]})
+        missing = [c for c in comps if c not in covered]
+        gap = {"covered": covered, "missing": missing,
+               "coveringAgentIds": [p["agentId"] for p in partials[:3]]}
+        return "gap", None, gap
+
+    return "training", None, None
+
+
+def _pipeline_for(status: str) -> list[dict]:
+    stages = ["requested", "corpus-mapped", "fine-tuning", "certifying", "listed"]
+    if status == "matched":
+        done = {s: True for s in stages}  # existing asset already covers it
+    elif status == "gap":
+        done = {"requested": True}
+    else:  # training / commission
+        done = {"requested": True, "corpus-mapped": True}
+    now = _now()
+    return [{"stage": s, "ts": now if done.get(s) else None, "done": bool(done.get(s))}
+            for s in stages]
+
+
+# ── DAL access (atp/tenant_db.py — migrations 002 + 005) ────────────────────
+
+# dict key ↔ table column; declaration order = INSERT/SELECT column order.
+_HITL_COLS = {
+    "ts": "ts",
+    "rater": "rater",
+    "agentId": "agent_id",
+    "layer": "layer",
+    "signal": "signal",
+    "weightedDelta": "weighted_delta",
+    "reason": "reason",
+    "auditId": "audit_id",
+}
+_REQUEST_COLS = {
+    "id": "id",
+    "ts": "ts",
+    "major": "major",
+    "specialty": "specialty",
+    "badgeIds": "badge_ids",
+    "packId": "pack_id",
+    "layers": "layers",
+    "corpora": "corpora",
+    "status": "status",
+    "matchedAgentId": "matched_agent_id",
+    "gap": "gap",
+    "pipeline": "pipeline",
+    "resultAgentId": "result_agent_id",
+}
+_JSON_COLS = {"badge_ids", "layers", "corpora", "gap", "pipeline"}  # JSON text
+
+_DB_LOCK = threading.Lock()
+_DB_READY = False
+_LEGACY_DONE: set[str] = set()
+_ORDER: dict[str, str] = {}
+
+
+def _engine():
+    """Engine from the Phase-1 DAL. Imported lazily so this module (and
+    `import api.server`) stays importable before atp/db.py lands; first log
+    access also ensures migrations ran — the server runs them at startup too,
+    and the runner is idempotent, so a second call is a no-op."""
+    global _DB_READY
+    from atp import db  # deferred: see docstring
+
+    if not _DB_READY:
+        with _DB_LOCK:
+            if not _DB_READY:
+                fn = (getattr(db, "ensure_migrations", None)
+                      or getattr(db, "run_migrations", None)
+                      or getattr(db, "migrate", None))
+                if callable(fn):
+                    try:
+                        fn()
+                    except TypeError:  # runner variant that takes the engine
+                        fn(db.get_engine())
+                _DB_READY = True
+    return db.get_engine()
+
+
+def _ensure_ready(table: str, legacy: Path, cols: dict) -> None:
+    """Engine + migrations up, then the one-time legacy JSONL import."""
+    _engine()
+    _import_legacy_once(table, legacy, cols)
+
+
+def _read_latest(table: str, cols: dict, limit: int, org_id: str) -> list[dict]:
+    sel = ", ".join(cols.values())
+    rows = tenant_db.scoped_query(
+        org_id,
+        f"SELECT {sel} FROM {table} WHERE org_id = :org"
+        f" ORDER BY {_order_by(table)} LIMIT :n",
+        {"org": org_id, "n": int(limit)})
+    return [_to_dict(r, cols) for r in rows]
+
+
+def _order_by(table: str) -> str:
+    """Newest-first ordering. Prefer the monotonic surrogate key from
+    migration 002 (`seq`), tolerate an integer `id` pk, then fall back to
+    sqlite's implicit rowid / the ts column so reads survive DDL drift."""
+    cached = _ORDER.get(table)
+    if cached:
+        return cached
+    engine = _engine()
+    info = {c["name"]: str(c["type"]).upper() for c in sa_inspect(engine).get_columns(table)}
+    if "seq" in info:
+        order = "seq DESC"
+    elif "INT" in info.get("id", ""):
+        order = "id DESC"
+    elif engine.dialect.name == "sqlite":
+        order = "rowid DESC"
+    else:
+        order = "ts DESC"
+    _ORDER[table] = order
+    return order
+
+
+def _to_row(rec: dict, cols: dict) -> dict:
+    """camelCase log dict → snake_case column dict (JSON cols dumped)."""
+    row = {}
+    for key, col in cols.items():
+        v = rec.get(key)
+        if col in _JSON_COLS and v is not None:
+            v = json.dumps(v, default=str)
+        row[col] = v
+    return row
+
+
+def _to_dict(row: dict, cols: dict) -> dict:
+    """DB row (scoped_query dict) → the exact dict shape the JSONL logs used
+    (camelCase keys — org_id is intentionally NOT part of the shape)."""
+    rec = {}
+    for key, col in cols.items():
+        v = row[col]
+        if col in _JSON_COLS and v is not None:
+            v = json.loads(v)
+        rec[key] = v
+    return rec
+
+
+def _import_legacy_once(table: str, legacy: Path, cols: dict) -> None:
+    """One-time lazy migration of the pre-Phase-1 JSONL log.
+
+    If the legacy file exists and the table holds no 'org-demo' rows, rename
+    the file to *.jsonl.imported (the atomic rename is the cross-process
+    claim — a racing worker gets FileNotFoundError and skips) and import its
+    rows oldest-first so surrogate-key order matches insertion order.
+    Pre-tenancy rows belong to the bootstrap org, so imports are stamped
+    'org-demo' (docs/TENANCY.md leak surface #1). Idempotent: reruns see
+    either no file or existing rows and do nothing.
+    """
+    if table in _LEGACY_DONE:
+        return
+    with _DB_LOCK:
+        if table in _LEGACY_DONE:
+            return
+        if legacy.exists():
+            count = tenant_db.scoped_query(
+                DEFAULT_ORG,
+                f"SELECT COUNT(*) AS n FROM {table} WHERE org_id = :org",
+                {"org": DEFAULT_ORG})[0]["n"]
+            if not count:
+                claimed = legacy.with_name(legacy.name + ".imported")
+                try:
+                    legacy.rename(claimed)
+                except FileNotFoundError:
+                    claimed = None  # another worker claimed the import
+                if claimed:
+                    for line in claimed.read_text().splitlines():
+                        line = line.strip()
+                        if not line:
+                            continue
+                        try:
+                            rec = json.loads(line)
+                        except json.JSONDecodeError:
+                            continue  # same tolerance the JSONL reader had
+                        tenant_db.insert_scoped(
+                            table, _to_row(rec, cols), DEFAULT_ORG)
+        _LEGACY_DONE.add(table)
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())

atp/tenant_db.py

@@ -0,0 +1,219 @@
+"""
+Org-scoped DAL — enforcement layer 2 of docs/TENANCY.md (Phase 2).
+
+Tenant tables (atp_hitl, atp_requests, atp_evidence, atp_cert_awards, jobs,
+access_log) must be read/written EXCLUSIVELY through the helpers here — never
+through raw atp.db query()/execute() from routes (convention + CI grep, per
+TENANCY.md layer 2).
+
+What the helpers enforce:
+
+  * Scope validation (both dialects): any statement that mentions a tenant
+    table must (a) bind an `:org` parameter in its SQL and (b) pass
+    params['org'] equal to the org_id argument — otherwise TenantScopeError.
+    The check is a deliberately SIMPLE parse (word-boundary table-name match);
+    false positives (a tenant table named in a string literal) just demand an
+    `:org` bind, never weaker scoping.
+  * Postgres (layer 3): every statement runs inside a transaction that first
+    executes `SELECT set_config('app.org_id', :org, true)` — the exact
+    equivalent of `SET LOCAL app.org_id` but bind-parameter safe. Migration
+    005 enables FORCE ROW LEVEL SECURITY with policy
+    `USING (org_id = current_setting('app.org_id', true))`, so a transaction
+    that skips this wrapper sees ZERO tenant rows (deny by default — there is
+    intentionally no permissive fallback when the setting is absent).
+  * SQLite (dev/demo): no RLS — the `WHERE org_id = :org` the validation
+    forces into every statement IS the isolation (layers 1-2 only,
+    documented gap).
+
+The org_id passed in must come from the verified JWT (route layer) — never
+from a request body or query string.
+
+Public:
+  scoped_query(org_id, sql, params)   -> list[dict]   (SELECTs)
+  scoped_execute(org_id, sql, params) -> db.ExecResult (writes)
+  insert_scoped(table, row, org_id)   -> db.ExecResult (row['org_id'] forced)
+  log_access(org_id, user, role, method, path, table, row_count, status)
+  TENANT_TABLES, DEFAULT_ORG, TenantScopeError
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from contextlib import contextmanager
+
+from sqlalchemy import text
+
+from atp import db
+
+#: Bootstrap org every pre-tenancy row belongs to (migration 005 default).
+DEFAULT_ORG = "org-demo"
+
+#: Tables that carry org_id and may only be touched through this module.
+TENANT_TABLES = frozenset({
+    "atp_hitl",
+    "atp_requests",
+    "atp_evidence",
+    "atp_cert_awards",
+    "jobs",
+    "access_log",
+    "licenses",       # Phase 4 (migration 006) — atp/licensing.py; the
+    "usage_events",   # key_lookup read path is documented in _load_by_key_id
+    "vault_docs",     # Phase 6 (migration 007) — atp/knowledge.py (T2:
+    "l5_drafts",      # encrypted content; RLS on PG per 005 pattern)
+})
+
+_IDENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+# ':org' bind — \b so ':org_id' / ':organization' don't satisfy the check.
+_ORG_BIND_RE = re.compile(r":org\b")
+_TABLE_RES = {t: re.compile(rf"\b{t}\b", re.IGNORECASE) for t in TENANT_TABLES}
+
+
+class TenantScopeError(RuntimeError):
+    """A statement touched a tenant table without correct org scoping."""
+
+
+# ── Validation ──────────────────────────────────────────────────────────────
+
+def _require_org(org_id: str) -> str:
+    if not org_id or not isinstance(org_id, str):
+        raise TenantScopeError("org_id must be a non-empty string")
+    return org_id
+
+
+def _tables_in(sql: str) -> set[str]:
+    return {t for t, rx in _TABLE_RES.items() if rx.search(sql)}
+
+
+def _validate(org_id: str, sql: str, params: dict) -> None:
+    """Simple-parse scope check: tenant table named → ':org' bind required
+    and params['org'] must equal the org the caller authenticated as."""
+    _require_org(org_id)
+    touched = _tables_in(sql)
+    if not touched:
+        return
+    if not _ORG_BIND_RE.search(sql):
+        raise TenantScopeError(
+            f"statement touches tenant table(s) {sorted(touched)} without an "
+            f"':org' bind — every tenant-table statement must scope by org "
+            f"(docs/TENANCY.md layer 2): {sql!r}"
+        )
+    if params.get("org") != org_id:
+        raise TenantScopeError(
+            f"params['org'] ({params.get('org')!r}) does not match the "
+            f"authenticated org_id ({org_id!r})"
+        )
+
+
+# ── Scoped connection (PG: SET LOCAL app.org_id) ────────────────────────────
+
+@contextmanager
+def _scoped_conn(org_id: str):
+    """One transaction with the org GUC pinned (Postgres) — commit on exit.
+
+    set_config(..., is_local=true) == SET LOCAL: the setting dies with the
+    transaction, so pooled connections can never leak one org's scope into
+    the next request's transaction.
+    """
+    engine = db.get_engine()
+    with engine.begin() as conn:
+        if engine.dialect.name == "postgresql":
+            conn.execute(
+                text("SELECT set_config('app.org_id', :org, true)"),
+                {"org": org_id},
+            )
+        yield conn
+
+
+# ── Public helpers ──────────────────────────────────────────────────────────
+
+@contextmanager
+def scoped_txn(org_id: str):
+    """Public multi-statement transaction with the org GUC pinned.
+
+    For callers that must make several reads/writes ATOMICALLY (e.g. the
+    evidence-chain append in atp/signing.py, which reads the chain head and
+    inserts under it). Yields the SQLAlchemy connection; commit on exit,
+    rollback on exception. Statement-level :org validation is the caller's
+    responsibility inside the block — Postgres RLS remains the backstop.
+    """
+    _require_org(org_id)
+    with _scoped_conn(org_id) as conn:
+        yield conn
+
+
+def scoped_query(org_id: str, sql: str, params: dict | None = None) -> list[dict]:
+    """Org-scoped SELECT. Named params (:name); returns rows as list[dict]."""
+    params = dict(params or {})
+    _validate(org_id, sql, params)
+    with _scoped_conn(org_id) as conn:
+        rows = conn.execute(text(sql), params).mappings().all()
+        return [dict(r) for r in rows]
+
+
+def scoped_execute(org_id: str, sql: str, params: dict | None = None) -> db.ExecResult:
+    """Org-scoped write. Same ExecResult contract as atp.db.execute()."""
+    params = dict(params or {})
+    _validate(org_id, sql, params)
+    with _scoped_conn(org_id) as conn:
+        result = conn.execute(text(sql), params)
+        lastrowid: int | None = None
+        if result.returns_rows:  # INSERT ... RETURNING <id> (both dialects)
+            row = result.first()
+            if row is not None:
+                lastrowid = row[0]
+        else:
+            try:
+                lastrowid = result.lastrowid  # meaningful on SQLite
+            except Exception:  # noqa: BLE001 — drivers without lastrowid
+                lastrowid = None
+        return db.ExecResult(rowcount=result.rowcount, lastrowid=lastrowid)
+
+
+def insert_scoped(table: str, row: dict, org_id: str) -> db.ExecResult:
+    """INSERT `row` into tenant `table` with org_id forced to the caller's
+    org (any org_id already present in `row` is overwritten — the verified
+    org always wins over payload-supplied values)."""
+    _require_org(org_id)
+    if table not in TENANT_TABLES:
+        raise TenantScopeError(
+            f"insert_scoped only handles tenant tables {sorted(TENANT_TABLES)}, "
+            f"got {table!r} — use atp.db.execute() for non-tenant tables"
+        )
+    row = dict(row)
+    row["org_id"] = org_id
+    for col in row:
+        if not _IDENT_RE.match(col):
+            raise TenantScopeError(f"invalid column name {col!r}")
+    cols = ", ".join(row)
+    marks = ", ".join(f":{c}" for c in row)
+    with _scoped_conn(org_id) as conn:
+        result = conn.execute(
+            text(f"INSERT INTO {table} ({cols}) VALUES ({marks})"), row)
+        try:
+            lastrowid = result.lastrowid
+        except Exception:  # noqa: BLE001
+            lastrowid = None
+        return db.ExecResult(rowcount=result.rowcount, lastrowid=lastrowid)
+
+
+def log_access(org_id: str, user: str, role: str, method: str, path: str,
+               table: str | None = None, row_count: int = 0,
+               status: int = 200) -> None:
+    """Append one audit row to access_log (TENANCY.md layer 4).
+
+    access_log is append-only (triggers, migration 004) and itself org-scoped
+    under RLS (migration 005), so the insert goes through the scoped path.
+    Column names follow 004's schema and avoid reserved words: the `user`
+    argument → column `user_id`, `table` → column `target_table`.
+    """
+    insert_scoped("access_log", {
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "user_id": user,
+        "role": role,
+        "method": method,
+        "path": path,
+        "target_table": table,
+        "row_count": int(row_count),
+        "status": int(status),
+    }, org_id)