engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/ep_consumer_credentials.py

@@ -0,0 +1,473 @@
+"""Verifier-only Engineering Platform consumer credentials and qualification seam.
+
+Increment 2a permits one short-lived, operator-created qualification credential.
+It is not consumer registration or a general credential-issuance workflow.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+import hashlib
+import hmac
+import json
+from pathlib import Path
+import secrets
+
+from .contracts.ep_consumer import RequestEnvelope
+from .storage import open_storage
+
+# These fixed predecessor domains preserve existing verifier and fingerprint
+# values during the namespace migration.  Renaming the domains would invalidate
+# otherwise valid bearer credentials, so the opaque values are intentionally
+# retained as migration compatibility material rather than current authority.
+VERIFIER_DOMAIN = b"engineering-platform.local-api.verifier.v1\0"
+FINGERPRINT_DOMAIN = b"engineering-platform.local-api.fingerprint.v1\0"
+QUALIFICATION_PREFIX = "qualification-"
+QUALIFICATION_TTL = timedelta(minutes=15)
+PRODUCTION_PREFIX = "production-"
+MAX_ACTIVE_PRODUCTION_CREDENTIALS = 2
+
+
+def verifier(credential: str) -> bytes:
+    return hashlib.sha256(VERIFIER_DOMAIN + credential.encode("ascii")).digest()
+
+
+def fingerprint(credential: str) -> bytes:
+    return hashlib.sha256(FINGERPRINT_DOMAIN + credential.encode("ascii")).digest()
+
+
+def _timestamp(value: datetime) -> str:
+    return value.astimezone(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _scope(consumer_id: str, project_id: str) -> tuple[str, str]:
+    """Reuse the v1 contract validator rather than duplicating identity rules."""
+
+    envelope = RequestEnvelope.parse(
+        {
+            "contract_version": "1.0",
+            "request_type": "contract.foundation",
+            "request_id": "qualification-credential",
+            "project_id": project_id,
+            "consumer": {"consumer_id": consumer_id},
+            "auth": {"scheme": "bearer", "credential": "operator-carrier"},
+            "payload": {},
+        }
+    )
+    return envelope.consumer.consumer_id, envelope.project_id
+
+
+@dataclass(frozen=True)
+class CredentialScope:
+    consumer_id: str
+    project_id: str
+    verifier_value: bytes
+
+
+@dataclass(frozen=True)
+class QualificationCredential:
+    credential_id: str
+    consumer_id: str
+    project_id: str
+    fingerprint_hex: str
+    created_at: str
+    expires_at: str
+    credential: str = field(repr=False)
+
+    def disclosure(self) -> dict[str, str]:
+        """The sole plaintext handoff, used only by the create CLI command."""
+
+        return {
+            "credential_id": self.credential_id,
+            "consumer_id": self.consumer_id,
+            "project_id": self.project_id,
+            "purpose": "QUALIFICATION",
+            "created_at": self.created_at,
+            "expires_at": self.expires_at,
+            "credential": self.credential,
+        }
+
+
+def create_qualification_credential(
+    root: Path, *, consumer_id: str, project_id: str, now: datetime | None = None
+) -> QualificationCredential:
+    """Create the one active, short-lived qualification credential."""
+
+    consumer_id, project_id = _scope(consumer_id, project_id)
+    moment = now or datetime.now(timezone.utc)
+    created_at = _timestamp(moment)
+    expires_at = _timestamp(moment + QUALIFICATION_TTL)
+    credential = secrets.token_urlsafe(32)
+    credential_id = QUALIFICATION_PREFIX + secrets.token_hex(16)
+    candidate_verifier = verifier(credential)
+    candidate_fingerprint = fingerprint(credential)
+    connection = open_storage(root)
+    try:
+        active = connection.execute(
+            "SELECT 1 FROM ep_consumer_credentials WHERE credential_id LIKE ? "
+            "AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at>CURRENT_TIMESTAMP) LIMIT 1",
+            (f"{QUALIFICATION_PREFIX}%",),
+        ).fetchone()
+        if active is not None:
+            raise ValueError("An active qualification credential already exists; revoke it first.")
+        connection.execute(
+            "INSERT INTO ep_consumer_credentials(credential_id,consumer_id,project_id,verifier,fingerprint,issued_at,expires_at) "
+            "VALUES(?,?,?,?,?,?,?)",
+            (
+                credential_id,
+                consumer_id,
+                project_id,
+                candidate_verifier,
+                candidate_fingerprint,
+                created_at,
+                expires_at,
+            ),
+        )
+    finally:
+        connection.close()
+    return QualificationCredential(
+        credential_id=credential_id,
+        consumer_id=consumer_id,
+        project_id=project_id,
+        fingerprint_hex=candidate_fingerprint.hex(),
+        created_at=created_at,
+        expires_at=expires_at,
+        credential=credential,
+    )
+
+
+def qualification_status(root: Path) -> list[dict[str, str | bool | None]]:
+    """Return safe, bounded qualification metadata without token material."""
+
+    connection = open_storage(root)
+    try:
+        rows = connection.execute(
+            "SELECT credential_id,consumer_id,project_id,fingerprint,issued_at,expires_at,revoked_at "
+            "FROM ep_consumer_credentials WHERE credential_id LIKE ? ORDER BY issued_at DESC",
+            (f"{QUALIFICATION_PREFIX}%",),
+        ).fetchall()
+    finally:
+        connection.close()
+    now = _timestamp(datetime.now(timezone.utc))
+    return [
+        {
+            "credential_id": str(row[0]),
+            "consumer_id": str(row[1]),
+            "project_id": str(row[2]),
+            "fingerprint": bytes(row[3]).hex(),
+            "purpose": "QUALIFICATION",
+            "created_at": str(row[4]),
+            "expires_at": str(row[5]) if row[5] is not None else None,
+            "active": row[6] is None and (row[5] is None or str(row[5]) > now),
+            "revoked_at": str(row[6]) if row[6] is not None else None,
+        }
+        for row in rows
+    ]
+
+
+def revoke_qualification_credential(root: Path, credential_id: str) -> bool:
+    """Explicitly deactivate a qualification credential without deleting evidence."""
+
+    if not credential_id.startswith(QUALIFICATION_PREFIX):
+        raise ValueError("credential_id is not a qualification credential.")
+    connection = open_storage(root)
+    try:
+        result = connection.execute(
+            "UPDATE ep_consumer_credentials SET revoked_at=? WHERE credential_id=? AND revoked_at IS NULL",
+            (_timestamp(datetime.now(timezone.utc)), credential_id),
+        )
+        return result.rowcount == 1
+    finally:
+        connection.close()
+
+
+def _registration(root: Path, consumer_id: str, project_id: str) -> tuple[str, ...] | None:
+    connection = open_storage(root)
+    try:
+        return connection.execute(
+            "SELECT consumer_id,project_id,status,created_at,updated_at,disabled_at,revoked_at "
+            "FROM ep_consumer_registrations WHERE consumer_id=? AND project_id=?",
+            (consumer_id, project_id),
+        ).fetchone()
+    finally:
+        connection.close()
+
+
+def register_consumer(root: Path, *, consumer_id: str, project_id: str) -> dict[str, str | bool | None]:
+    consumer_id, project_id = _scope(consumer_id, project_id)
+    now = _timestamp(datetime.now(timezone.utc))
+    connection = open_storage(root)
+    try:
+        row = connection.execute(
+            "SELECT status,created_at,updated_at,disabled_at,revoked_at FROM ep_consumer_registrations "
+            "WHERE consumer_id=? AND project_id=?", (consumer_id, project_id)
+        ).fetchone()
+        if row is None:
+            connection.execute(
+                "INSERT INTO ep_consumer_registrations(consumer_id,project_id,status,created_at,updated_at,audit_metadata) "
+                "VALUES(?,?, 'ACTIVE',?,?,?)", (consumer_id, project_id, now, now, json.dumps({"action":"REGISTER"}, sort_keys=True))
+            )
+            return {"consumer_id":consumer_id,"project_id":project_id,"status":"ACTIVE","created_at":now,"updated_at":now,"idempotent":False}
+        if row[0] != "ACTIVE":
+            raise ValueError("consumer registration is not active.")
+        return {"consumer_id":consumer_id,"project_id":project_id,"status":"ACTIVE","created_at":str(row[1]),"updated_at":str(row[2]),"idempotent":True}
+    finally:
+        connection.close()
+
+
+def consumer_status(root: Path, *, consumer_id: str, project_id: str) -> dict[str, object]:
+    consumer_id, project_id = _scope(consumer_id, project_id)
+    row = _registration(root, consumer_id, project_id)
+    if row is None:
+        raise ValueError("consumer registration is absent.")
+    connection = open_storage(root)
+    try:
+        count = connection.execute(
+            "SELECT count(*) FROM ep_consumer_credentials WHERE consumer_id=? AND project_id=? AND credential_id LIKE ? "
+            "AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at>CURRENT_TIMESTAMP)",
+            (consumer_id, project_id, f"{PRODUCTION_PREFIX}%"),
+        ).fetchone()[0]
+    finally:
+        connection.close()
+    return {"consumer_id":row[0],"project_id":row[1],"status":row[2],"created_at":row[3],"updated_at":row[4],"disabled_at":row[5],"revoked_at":row[6],"active_production_credentials":count}
+
+
+def _set_registration_state(root: Path, *, consumer_id: str, project_id: str, state: str) -> bool:
+    consumer_id, project_id = _scope(consumer_id, project_id)
+    now = _timestamp(datetime.now(timezone.utc))
+    column = "disabled_at" if state == "DISABLED" else "revoked_at"
+    connection = open_storage(root)
+    try:
+        result = connection.execute(
+            f"UPDATE ep_consumer_registrations SET status=?,updated_at=?,{column}=?,audit_metadata=? "
+            "WHERE consumer_id=? AND project_id=? AND status='ACTIVE'",
+            (state, now, now, json.dumps({"action": "DISABLE" if state == "DISABLED" else "REVOKE_REGISTRATION"}, sort_keys=True), consumer_id, project_id),
+        )
+        existing = connection.execute("SELECT status FROM ep_consumer_registrations WHERE consumer_id=? AND project_id=?", (consumer_id, project_id)).fetchone()
+        if existing is None:
+            raise ValueError("consumer registration is absent.")
+        if existing[0] != state and result.rowcount != 1:
+            raise ValueError("consumer registration state conflicts.")
+        return result.rowcount == 1
+    finally:
+        connection.close()
+
+
+def disable_consumer(root: Path, *, consumer_id: str, project_id: str) -> bool:
+    return _set_registration_state(root, consumer_id=consumer_id, project_id=project_id, state="DISABLED")
+
+
+def revoke_consumer(root: Path, *, consumer_id: str, project_id: str) -> bool:
+    return _set_registration_state(root, consumer_id=consumer_id, project_id=project_id, state="REVOKED")
+
+
+@dataclass(frozen=True)
+class ProductionCredential:
+    credential_id: str
+    consumer_id: str
+    project_id: str
+    fingerprint_hex: str
+    created_at: str
+    credential: str = field(repr=False)
+
+    def disclosure(self) -> dict[str, str]:
+        return {"credential_id":self.credential_id,"consumer_id":self.consumer_id,"project_id":self.project_id,"purpose":"PRODUCTION_CONSUMER","created_at":self.created_at,"credential":self.credential}
+
+
+def issue_credential(root: Path, *, consumer_id: str, project_id: str) -> ProductionCredential:
+    consumer_id, project_id = _scope(consumer_id, project_id)
+    status = _registration(root, consumer_id, project_id)
+    if status is None or status[2] != "ACTIVE":
+        raise ValueError("active consumer registration is required.")
+    token = secrets.token_urlsafe(32)
+    now = _timestamp(datetime.now(timezone.utc))
+    credential_id = PRODUCTION_PREFIX + secrets.token_hex(16)
+    connection = open_storage(root)
+    try:
+        count = connection.execute("SELECT count(*) FROM ep_consumer_credentials WHERE consumer_id=? AND project_id=? AND credential_id LIKE ? AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at>CURRENT_TIMESTAMP)", (consumer_id,project_id,f"{PRODUCTION_PREFIX}%")).fetchone()[0]
+        if count >= MAX_ACTIVE_PRODUCTION_CREDENTIALS:
+            raise ValueError("active production credential limit reached.")
+        connection.execute("INSERT INTO ep_consumer_credentials(credential_id,consumer_id,project_id,verifier,fingerprint,issued_at) VALUES(?,?,?,?,?,?)", (credential_id,consumer_id,project_id,verifier(token),fingerprint(token),now))
+    finally:
+        connection.close()
+    return ProductionCredential(credential_id,consumer_id,project_id,fingerprint(token).hex(),now,token)
+
+
+def credential_status(root: Path, *, consumer_id: str, project_id: str) -> list[dict[str, object]]:
+    consumer_id, project_id = _scope(consumer_id, project_id)
+    connection = open_storage(root)
+    try:
+        rows = connection.execute("SELECT credential_id,fingerprint,issued_at,expires_at,revoked_at FROM ep_consumer_credentials WHERE consumer_id=? AND project_id=? AND credential_id LIKE ? ORDER BY issued_at DESC", (consumer_id,project_id,f"{PRODUCTION_PREFIX}%")).fetchall()
+    finally:
+        connection.close()
+    now = _timestamp(datetime.now(timezone.utc))
+    return [{"credential_id":str(r[0]),"fingerprint":bytes(r[1]).hex(),"purpose":"PRODUCTION_CONSUMER","created_at":str(r[2]),"expires_at":r[3],"revoked_at":r[4],"active":r[4] is None and (r[3] is None or str(r[3]) > now)} for r in rows]
+
+
+def revoke_credential(root: Path, credential_id: str) -> bool:
+    if not credential_id.startswith(PRODUCTION_PREFIX):
+        raise ValueError("credential_id is not a production credential.")
+    connection = open_storage(root)
+    try:
+        result = connection.execute("UPDATE ep_consumer_credentials SET revoked_at=? WHERE credential_id=? AND revoked_at IS NULL", (_timestamp(datetime.now(timezone.utc)),credential_id))
+        if result.rowcount == 0 and connection.execute(
+            "SELECT 1 FROM ep_consumer_credentials WHERE credential_id=?", (credential_id,)
+        ).fetchone() is None:
+            raise ValueError("production credential is absent.")
+        return result.rowcount == 1
+    finally:
+        connection.close()
+
+
+def rotate_credential(
+    root: Path, *, consumer_id: str, project_id: str, old_credential_id: str,
+    store: object, authenticate: Callable[[str], bool],
+) -> ProductionCredential:
+    """Issue, securely store and prove a replacement before revoking the old token."""
+    replacement = issue_credential(root, consumer_id=consumer_id, project_id=project_id)
+    try:
+        store.put_credential(consumer_id, project_id, replacement.credential)
+        if not authenticate(replacement.credential):
+            raise ValueError("replacement credential did not authenticate.")
+    except Exception:
+        revoke_credential(root, replacement.credential_id)
+        raise
+    revoke_credential(root, old_credential_id)
+    return replacement
+
+
+class CredentialAuthority:
+    """Read-only production authority with explicit in-memory test fixtures."""
+
+    def __init__(self, root: Path | None = None, record: CredentialScope | None = None) -> None:
+        self.root, self.record = root, record
+
+    @classmethod
+    def test_fixture(
+        cls, credential: str, *, consumer_id: str, project_id: str
+    ) -> "CredentialAuthority":
+        return cls(record=CredentialScope(consumer_id, project_id, verifier(credential)))
+
+    def ready(self) -> bool:
+        if self.root is None:
+            return True
+        try:
+            connection = open_storage(self.root)
+            try:
+                connection.execute("SELECT 1 FROM ep_consumer_credentials LIMIT 1").fetchone()
+                connection.execute("SELECT 1 FROM ep_consumer_registrations LIMIT 1").fetchone()
+            finally:
+                connection.close()
+            return True
+        except Exception:
+            return False
+
+    def authenticate(self, credential: str) -> CredentialScope | None:
+        try:
+            candidate = verifier(credential)
+        except UnicodeEncodeError:
+            return None
+        if self.record is not None:
+            return (
+                self.record if hmac.compare_digest(self.record.verifier_value, candidate) else None
+            )
+        if self.root is None:
+            return None
+        try:
+            connection = open_storage(self.root)
+            try:
+                row = connection.execute(
+                    "SELECT credential_id,consumer_id,project_id,verifier FROM ep_consumer_credentials "
+                    "WHERE verifier=? AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at>CURRENT_TIMESTAMP)",
+                    (candidate,),
+                ).fetchone()
+            finally:
+                connection.close()
+        except Exception:
+            return None
+        if row is None or not hmac.compare_digest(bytes(row[3]), candidate):
+            return None
+        return CredentialScope(str(row[1]), str(row[2]), bytes(row[3]))
+
+    def authorized(self, scope: CredentialScope) -> bool:
+        """Evaluate current registration state after bearer authentication."""
+
+        if self.root is None or self.record is not None:
+            return True
+        try:
+            connection = open_storage(self.root)
+            try:
+                row = connection.execute(
+                    "SELECT credential_id FROM ep_consumer_credentials WHERE verifier=?",
+                    (scope.verifier_value,),
+                ).fetchone()
+            finally:
+                connection.close()
+            if row is None or not str(row[0]).startswith(PRODUCTION_PREFIX):
+                return True
+            registration = _registration(self.root, scope.consumer_id, scope.project_id)
+            return registration is not None and registration[2] == "ACTIVE"
+        except Exception:
+            return False
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="engineering-ep-consumer-credentials")
+    parser.add_argument(
+        "command",
+        choices=(
+            "create-qualification-credential",
+            "qualification-status",
+            "revoke-qualification-credential", "consumer-register", "consumer-status",
+            "consumer-disable", "consumer-revoke", "credential-issue", "credential-status", "credential-revoke",
+        ),
+    )
+    parser.add_argument("--repo", type=Path, default=Path.cwd())
+    parser.add_argument("--consumer-id")
+    parser.add_argument("--project-id")
+    parser.add_argument("--credential-id")
+    args = parser.parse_args(argv)
+    root = args.repo.resolve()
+    try:
+        if args.command == "create-qualification-credential":
+            if args.consumer_id is None or args.project_id is None:
+                raise ValueError("--consumer-id and --project-id are required.")
+            print(
+                json.dumps(
+                    create_qualification_credential(
+                        root, consumer_id=args.consumer_id, project_id=args.project_id
+                    ).disclosure(),
+                    sort_keys=True,
+                )
+            )
+            return 0
+        if args.command == "qualification-status":
+            print(json.dumps(qualification_status(root), sort_keys=True))
+            return 0
+        if args.command in {"consumer-register", "consumer-status", "consumer-disable", "consumer-revoke", "credential-issue", "credential-status"}:
+            if args.consumer_id is None or args.project_id is None:
+                raise ValueError("--consumer-id and --project-id are required.")
+            actions = {"consumer-register": register_consumer, "consumer-status": consumer_status, "consumer-disable": disable_consumer, "consumer-revoke": revoke_consumer, "credential-issue": issue_credential, "credential-status": credential_status}
+            result = actions[args.command](root, consumer_id=args.consumer_id, project_id=args.project_id)
+            if isinstance(result, (ProductionCredential, QualificationCredential)):
+                result = result.disclosure()
+            print(json.dumps(result, sort_keys=True))
+            return 0
+        if args.credential_id is None:
+            raise ValueError("--credential-id is required.")
+        if args.command == "credential-revoke":
+            changed = revoke_credential(root, args.credential_id)
+        else:
+            changed = revoke_qualification_credential(root, args.credential_id)
+        print(json.dumps({"credential_id": args.credential_id, "revoked": True, "changed": changed}, sort_keys=True))
+        return 0
+    except ValueError as error:
+        print(f"ERROR: {error}")
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

engineering_platform/evidence_projection.py

@@ -0,0 +1,213 @@
+"""Invocation-local bounded projections for oversized shell evidence.
+
+The Engineering runner never persists raw tool output.  Codex executes shell
+tools inside its own provider turn, so the temporary PATH proxy created here is
+the only safe interception point: it preserves exit status, returns small or
+source output unchanged, and makes an explicit raw expansion available only to
+the same invocation via ``ENGINEERING_PLATFORM_EVIDENCE_EXPAND=1``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import json
+import shutil
+import subprocess  # nosec B404
+import sys
+from tempfile import TemporaryDirectory
+from typing import Iterable, Mapping
+
+
+# Limits are category-specific because passing logs are repetitive, while a
+# failure needs an assertion, traceback and surrounding context to be useful.
+PASSING_TEST_LIMIT = 768
+FAILED_DIAGNOSTIC_LIMIT = 12_288
+SEARCH_MATCH_LIMIT = 24
+SEARCH_LINE_LIMIT = 240
+GIT_FACT_LIMIT = 2_048
+GITHUB_FACT_LIMIT = 4_096
+PROXIED_TOOLS = ("git", "gh", "rg", "grep", "pytest", "python", "python3", "npm", "npx", "engineering-platform-context-escalate")
+
+
+@dataclass(frozen=True)
+class EvidenceProjection:
+    category: str
+    text: str
+    raw_bytes: int
+    projected_bytes: int
+    more_evidence_available: bool
+
+
+def category_for(command: Iterable[str]) -> str:
+    values = tuple(command)
+    executable = Path(values[0]).name if values else ""
+    normalized = " ".join(values).casefold()
+    if executable in {"rg", "grep"}:
+        return "search"
+    if executable == "git":
+        return "git"
+    if executable == "gh":
+        return "github"
+    if executable in {"pytest", "npm", "npx"} or (
+        executable in {"python", "python3"} and "unittest" in normalized
+    ):
+        return "test"
+    return "other"
+
+
+def _bytes(value: str) -> int:
+    return len(value.encode("utf-8"))
+
+
+def _bounded_lines(value: str, *, count: int, width: int) -> str:
+    return "\n".join(line[:width] for line in value.splitlines()[:count])
+
+
+def _failure_tail(value: str) -> str:
+    lines = value.splitlines()
+    if _bytes(value) <= FAILED_DIAGNOSTIC_LIMIT:
+        return value
+    head = "\n".join(lines[:30])
+    tail = "\n".join(lines[-90:])
+    return f"{head}\n… FAILED_DIAGNOSTIC_MIDDLE_OMITTED …\n{tail}"[-FAILED_DIAGNOSTIC_LIMIT:]
+
+
+def project_output(command: Iterable[str], output: str, exit_code: int) -> EvidenceProjection:
+    """Project one completed command without losing the raw expansion path."""
+    category = category_for(command)
+    raw_bytes = _bytes(output)
+    if not output or category == "other":
+        return EvidenceProjection(category, output, raw_bytes, raw_bytes, False)
+    if category == "test":
+        if exit_code:
+            text = _failure_tail(output)
+            more = text != output
+            if more:
+                marker = "\nMORE_EVIDENCE_AVAILABLE: set ENGINEERING_PLATFORM_EVIDENCE_EXPAND=1 for this command."
+                text = f"{text[:FAILED_DIAGNOSTIC_LIMIT - _bytes(marker)]}{marker}"
+        elif raw_bytes > PASSING_TEST_LIMIT:
+            passed = next((line for line in output.splitlines() if "passed" in line.casefold()), "PASS")
+            text = f"PASSING_TEST_OUTPUT_BOUNDED\n{passed[:PASSING_TEST_LIMIT // 2]}\nMORE_EVIDENCE_AVAILABLE: set ENGINEERING_PLATFORM_EVIDENCE_EXPAND=1 for this command."
+            more = True
+        else:
+            text, more = output, False
+    elif category == "search" and len(output.splitlines()) > SEARCH_MATCH_LIMIT:
+        text = _bounded_lines(output, count=SEARCH_MATCH_LIMIT, width=SEARCH_LINE_LIMIT)
+        text += f"\nMATCHES_BOUNDED: shown={SEARCH_MATCH_LIMIT} total={len(output.splitlines())}\nMORE_EVIDENCE_AVAILABLE: set ENGINEERING_PLATFORM_EVIDENCE_EXPAND=1 for this command."
+        more = True
+    elif category == "git" and raw_bytes > GIT_FACT_LIMIT:
+        text = _bounded_lines(output, count=32, width=SEARCH_LINE_LIMIT)
+        text += "\nGIT_EVIDENCE_BOUNDED\nMORE_EVIDENCE_AVAILABLE: set ENGINEERING_PLATFORM_EVIDENCE_EXPAND=1 for this command."
+        more = True
+    elif category == "github" and raw_bytes > GITHUB_FACT_LIMIT:
+        text = _bounded_lines(output, count=48, width=SEARCH_LINE_LIMIT)
+        text += "\nGITHUB_EVIDENCE_BOUNDED\nMORE_EVIDENCE_AVAILABLE: set ENGINEERING_PLATFORM_EVIDENCE_EXPAND=1 for this command."
+        more = True
+    else:
+        text, more = output, False
+    return EvidenceProjection(category, text, raw_bytes, _bytes(text), more)
+
+
+class ToolProxyEnvironment:
+    """Temporary PATH proxy. It retains no output after the invocation ends."""
+
+    def __init__(self) -> None:
+        self._temporary: TemporaryDirectory[str] | None = None
+
+    def __enter__(self) -> Mapping[str, str]:
+        self._temporary = TemporaryDirectory(prefix="engineering-platform-evidence-")
+        directory = Path(self._temporary.name)
+        repository_root = Path(__file__).resolve().parents[2]
+        for name in PROXIED_TOOLS:
+            launcher = directory / name
+            target = "context_escalation_main" if name == "engineering-platform-context-escalate" else "proxy_main"
+            launcher.write_text(
+                f"#!{sys.executable}\nimport sys\nsys.path.insert(0, {str(repository_root)!r})\nfrom engineering_platform.evidence_projection import {target}\n{target}({name!r})\n",
+                encoding="utf-8",
+            )
+            launcher.chmod(0o700)
+        environment = dict(os.environ)
+        environment["ENGINEERING_PLATFORM_EVIDENCE_ORIGINAL_PATH"] = environment.get("PATH", os.defpath)
+        environment["PATH"] = f"{directory}{os.pathsep}{environment['ENGINEERING_PLATFORM_EVIDENCE_ORIGINAL_PATH']}"
+        environment["ENGINEERING_PLATFORM_CONTEXT_ESCALATION_FILE"] = str(directory / "context-escalations.jsonl")
+        return environment
+
+    def __exit__(self, *_: object) -> None:
+        if self._temporary is not None:
+            self._temporary.cleanup()
+            self._temporary = None
+
+    def context_escalations(self) -> tuple[dict[str, object], ...]:
+        if self._temporary is None:
+            return ()
+        path = Path(self._temporary.name) / "context-escalations.jsonl"
+        try:
+            return tuple(
+                item for line in path.read_text(encoding="utf-8").splitlines()
+                if isinstance((item := json.loads(line)), dict)
+            )
+        except (OSError, json.JSONDecodeError):
+            return ()
+
+
+def proxy_main(name: str | None = None) -> None:
+    """Run the proxied command and emit only its bounded invocation-local view."""
+    name = name or Path(sys.argv[0]).name
+    original_path = os.environ.get("ENGINEERING_PLATFORM_EVIDENCE_ORIGINAL_PATH", os.defpath)
+    executable = shutil.which(name, path=original_path)
+    if executable is None:
+        raise SystemExit(f"Evidence proxy could not resolve {name}.")
+    completed = subprocess.run(  # nosec B603
+        (executable, *sys.argv[1:]), text=True, capture_output=True,
+        env={**os.environ, "PATH": original_path}, check=False,
+    )
+    raw = f"{completed.stdout}{completed.stderr}"
+    if os.environ.get("ENGINEERING_PLATFORM_EVIDENCE_EXPAND") == "1":
+        sys.stdout.write(raw)
+    else:
+        sys.stdout.write(project_output((name, *sys.argv[1:]), raw, completed.returncode).text)
+    raise SystemExit(completed.returncode)
+
+
+def context_escalation_main(_: str | None = None) -> None:
+    """Validate and record one bounded historical-context escalation."""
+    from .provider_context_scope import ContextEscalationReason, ContextEscalationRequest, HistoryBoundaryKind
+
+    arguments = sys.argv[1:]
+    try:
+        diagnostic_index = arguments.index("--diagnostic")
+        values, diagnostic = arguments[:diagnostic_index], " ".join(arguments[diagnostic_index + 1:])
+        if len(values) != 4:
+            raise ValueError("Expected REASON BOUNDARY_KIND BOUNDARY LIMIT.")
+        request = ContextEscalationRequest(
+            ContextEscalationReason(values[0]), HistoryBoundaryKind(values[1]), values[2], int(values[3]), diagnostic
+        ).validate()
+    except (ValueError, IndexError) as error:
+        sys.stderr.write(f"Context escalation rejected: {error}\n")
+        raise SystemExit(2)
+    path = os.environ.get("ENGINEERING_PLATFORM_CONTEXT_ESCALATION_FILE")
+    if not path:
+        sys.stderr.write("Context escalation is available only inside an Engineering Platform provider invocation.\n")
+        raise SystemExit(2)
+    record = {
+        "reason": request.reason.value, "boundary_kind": request.boundary_kind.value,
+        "boundary": request.boundary, "limit": request.limit, "diagnostic": request.diagnostic,
+    }
+    with open(path, "a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record, sort_keys=True, separators=(",", ":")) + "\n")
+    sys.stdout.write("CONTEXT_ESCALATION_ADMITTED\n")
+
+
+def deterministic_fixture() -> dict[str, object]:
+    """Comparable raw/projection fixture; it contains no provider or user data."""
+    cases = (
+        (("rg", "needle"), "\n".join(f"match {item}" for item in range(120)), 0),
+        (("git", "log", "--oneline"), "\n".join(f"{item:040x} commit" for item in range(90)), 0),
+        (("pytest",), "\n".join(". passing" for _ in range(500)) + "\n500 passed", 0),
+        (("pytest",), "FAILED test_example\nAssertionError: expected x\n" + "trace\n" * 400, 1),
+    )
+    projected = tuple(project_output(command, output, code) for command, output, code in cases)
+    raw = sum(item.raw_bytes for item in projected)
+    bounded = sum(item.projected_bytes for item in projected)
+    return {"raw_tool_output_bytes": raw, "projected_tool_output_bytes": bounded, "suppressed_tool_output_bytes": raw - bounded, "reduction": 0 if not raw else (raw - bounded) / raw, "required_evidence_retained": True, "more_evidence_available": any(item.more_evidence_available for item in projected)}