orbitkb 1.2.1__py3-none-any.whl

orbitkb/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.2.1"

orbitkb/cli.py

@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import orbitkb
+from orbitkb.cli_progress import RichProgressReporter
+from orbitkb.config import resolve_backend
+from orbitkb.db.connection import DEFAULT_DB_PATH, open_db
+from orbitkb.db.repositories import index_runs as index_runs_repo
+from orbitkb.db.repositories import indexed_files as indexed_files_repo
+from orbitkb.db.repositories import services as services_repo
+from orbitkb.db.repositories import verification as verification_repo
+from orbitkb.export.markdown import export_markdown
+from orbitkb.export.mermaid import export_mermaid
+from orbitkb.generation import change_surface
+from orbitkb.generation.backend_base import GenerationError
+from orbitkb.generation.orchestrator import DiscoveryError, index_path, index_service
+from orbitkb.generation.verification import verify_change_surface
+
+
+def _cmd_index(args: argparse.Namespace) -> int:
+    conn = open_db(args.db)
+    backend = resolve_backend(args.backend, args.model, args.claude_bare, args.codex_api_key)
+    try:
+        with RichProgressReporter() as progress:
+            results = index_path(
+                conn, Path(args.path), backend, service_override=args.service, force=args.force,
+                progress=progress, repository_name=args.repository_name,
+            )
+    except (DiscoveryError, GenerationError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    for r in results:
+        print(f"{r.service_name}: status={r.status} files_changed={r.files_changed} llm_calls={r.llm_calls}")
+    return 0 if all(r.status == "ok" for r in results) else 1
+
+
+def _cmd_update(args: argparse.Namespace) -> int:
+    conn = open_db(args.db)
+    row = services_repo.get_service_by_name(conn, args.service)
+    if row is None:
+        print(f"error: unknown service {args.service!r} (run `orbitkb list`)", file=sys.stderr)
+        return 1
+    root = Path(row["root_path"])
+    if not root.is_dir():
+        print(
+            f"error: root path for {args.service!r} no longer exists: {root}\n"
+            f"       re-run `orbitkb index <newpath> --service {args.service}` instead.",
+            file=sys.stderr,
+        )
+        return 1
+    from orbitkb.discovery.registry import detector_for
+
+    detector = detector_for(root)
+    if detector is None:
+        print(f"error: {root} no longer matches any known stack", file=sys.stderr)
+        return 1
+    backend = resolve_backend(args.backend, args.model, args.claude_bare, args.codex_api_key)
+    with RichProgressReporter() as progress:
+        result = index_service(conn, args.service, root, detector, backend, force=args.force, progress=progress)
+    print(f"{result.service_name}: status={result.status} files_changed={result.files_changed} llm_calls={result.llm_calls}")
+    return 0 if result.status == "ok" else 1
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    conn = open_db(args.db)
+    rows = services_repo.list_services(conn)
+    if not rows:
+        print("(nenhum serviço indexado ainda)")
+        return 0
+    for r in rows:
+        print(f"{r['name']:<30} stack={r['stack'] or '?':<14} apis={r['api_count']:<3} {r['short_desc'] or ''}")
+    return 0
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    conn = open_db(args.db)
+    if args.service:
+        row = services_repo.get_service_by_name(conn, args.service)
+        if row is None:
+            print(f"error: unknown service {args.service!r}", file=sys.stderr)
+            return 1
+        hashes = indexed_files_repo.get_indexed_file_hashes(conn, row["id"])
+        print(f"service: {row['name']} ({row['stack']}) — {row['root_path']}")
+        print(f"last_commit: {row['last_commit']}")
+        print(f"indexed files: {len(hashes)}")
+        for run in index_runs_repo.recent_index_runs(conn, row["id"], limit=5):
+            print(
+                f"  run#{run['id']} {run['started_at']} status={run['status']} backend={run['backend']} "
+                f"files_changed={run['files_changed']} llm_calls={run['llm_calls']} notes={run['notes']}"
+            )
+    else:
+        services = services_repo.list_services(conn)
+        print(f"services indexed: {len(services)}")
+        for run in index_runs_repo.recent_index_runs(conn, limit=10):
+            svc = services_repo.get_service_by_id(conn, run["service_id"]) if run["service_id"] else None
+            name = svc["name"] if svc else "?"
+            print(
+                f"  run#{run['id']} service={name} status={run['status']} backend={run['backend']} "
+                f"files_changed={run['files_changed']} llm_calls={run['llm_calls']}"
+            )
+        verifications = verification_repo.latest_verifications(conn, limit=5)
+        if verifications:
+            print("recent change surface verifications:")
+            for v in verifications:
+                print(
+                    f"  run#{v['run_id']} repository={v['repository']} since={v['since_commit']} "
+                    f"precision={v['precision']} recall={v['recall']}"
+                )
+    return 0
+
+
+def _cmd_export(args: argparse.Namespace) -> int:
+    conn = open_db(args.db)
+    if args.format == "mermaid":
+        written = export_mermaid(conn, Path(args.out), service_filter=args.service)
+    else:
+        written = export_markdown(conn, Path(args.out), service_filter=args.service)
+    print(f"wrote {len(written)} files under {args.out}")
+    return 0
+
+
+def _cmd_analyze(args: argparse.Namespace) -> int:
+    conn = open_db(args.db)
+    backend = resolve_backend(args.backend, args.model, args.claude_bare, args.codex_api_key)
+    result = change_surface.analyze_change_surface(conn, args.task, backend, hint_services=args.hint_services)
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    conn = open_db(args.db)
+    result = verify_change_surface(conn, args.run_id, args.repository, args.since, record_feedback=args.record_feedback)
+    if "error" in result:
+        print(f"error: {result['error']}", file=sys.stderr)
+        return 1
+    print(f"predicted: {result['predicted']}")
+    print(f"actual:    {result['actual']}")
+    print(f"true_positives:  {result['true_positives']}")
+    print(f"false_positives: {result['false_positives']}")
+    print(f"false_negatives: {result['false_negatives']}")
+    print(f"precision: {result['precision']}")
+    print(f"recall:    {result['recall']}")
+    if args.record_feedback:
+        print("feedback recorded for true/false positives")
+    return 0
+
+
+def _cmd_serve(args: argparse.Namespace) -> int:
+    from orbitkb.mcp.server import build_server
+
+    backend = resolve_backend(args.backend, args.model, args.claude_bare, args.codex_api_key)
+    server = build_server(args.db, backend=backend)
+    server.run()
+    return 0
+
+
+_TOP_LEVEL_EPILOG = """\
+The orbitkb workflow is index -> ask -> verify:
+
+  1. index   Point it at a repo (or several) so it builds a System Knowledge Model.
+  2. ask     Register it as an MCP server (`serve`) and have an agent call
+             find_change_surface with an engineering task/epic, before it opens
+             any file, to get the likely blast radius with evidence + confidence.
+  3. verify  Once the change ships, check whether the prediction was right
+             against the real git diff, closing the feedback loop.
+
+Examples:
+  orbitkb index ~/code/my-monorepo --repository-name my-monorepo
+  orbitkb serve --backend claude
+  orbitkb verify 3 --repository my-monorepo --since a1b2c3d
+
+Run `orbitkb <command> --help` for a runnable example of any single command.
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="orbitkb", epilog=_TOP_LEVEL_EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"orbitkb {orbitkb.__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def add_backend_args(p: argparse.ArgumentParser) -> None:
+        p.add_argument("--backend", choices=["claude", "codex"], default=None, help="LLM backend to shell out to headless (default: whichever CLI is on PATH)")
+        p.add_argument("--model", default=None, help="Override the backend's default model")
+        p.add_argument("--claude-bare", action="store_true", help="Use ANTHROPIC_API_KEY billing instead of the Claude Code subscription session")
+        p.add_argument("--codex-api-key", action="store_true", help="Use CODEX_API_KEY billing instead of the ChatGPT subscription session")
+        p.add_argument("--db", type=Path, default=DEFAULT_DB_PATH, help=f"SQLite database path (default: {DEFAULT_DB_PATH})")
+
+    p_index = sub.add_parser(
+        "index", help="Index a monorepo root or a single service repo",
+        epilog=(
+            "examples:\n"
+            "  orbitkb index ~/code/orders-service\n"
+            "  orbitkb index ~/code/my-monorepo --repository-name my-monorepo\n"
+            "  orbitkb index . --service custom-name --force\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_index.add_argument("path", help="A single service's root, or a monorepo root containing several")
+    p_index.add_argument("--service", default=None, help="Override the inferred service name (only valid for a single-service path)")
+    p_index.add_argument("--repository-name", default=None, help="Explicit repository name; avoids collisions when indexing several repos into one shared DB")
+    p_index.add_argument("--force", action="store_true", help="Regenerate everything, ignoring file-hash skip")
+    add_backend_args(p_index)
+    p_index.set_defaults(func=_cmd_index)
+
+    p_update = sub.add_parser(
+        "update", help="Re-index one already-known service by name",
+        epilog="example:\n  orbitkb update orders-service\n",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_update.add_argument("service", help="Exact name shown by `orbitkb list`")
+    p_update.add_argument("--force", action="store_true", help="Regenerate everything, ignoring file-hash skip")
+    add_backend_args(p_update)
+    p_update.set_defaults(func=_cmd_update)
+
+    p_list = sub.add_parser("list", help="List indexed services")
+    p_list.add_argument("--db", type=Path, default=DEFAULT_DB_PATH, help=f"SQLite database path (default: {DEFAULT_DB_PATH})")
+    p_list.set_defaults(func=_cmd_list)
+
+    p_status = sub.add_parser(
+        "status", help="Show indexing status/history, and recent change surface verifications",
+        epilog="examples:\n  orbitkb status\n  orbitkb status orders-service\n",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_status.add_argument("service", nargs="?", default=None, help="Show one service's indexing history instead of the whole DB's")
+    p_status.add_argument("--db", type=Path, default=DEFAULT_DB_PATH, help=f"SQLite database path (default: {DEFAULT_DB_PATH})")
+    p_status.set_defaults(func=_cmd_status)
+
+    p_export = sub.add_parser(
+        "export", help="Export the database to Markdown or Mermaid diagrams",
+        epilog=(
+            "examples:\n"
+            "  orbitkb export md --out docs/\n"
+            "  orbitkb export mermaid --out docs/\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_export.add_argument("format", choices=["md", "mermaid"], help="md: human-readable docs; mermaid: topology.mmd + one er.mmd per service")
+    p_export.add_argument("--out", default="docs", help="Output directory (default: docs)")
+    p_export.add_argument("--service", default=None, help="Export only this service instead of every indexed one")
+    p_export.add_argument("--db", type=Path, default=DEFAULT_DB_PATH, help=f"SQLite database path (default: {DEFAULT_DB_PATH})")
+    p_export.set_defaults(func=_cmd_export)
+
+    p_analyze = sub.add_parser(
+        "analyze", help="Run find_change_surface for a task and print the result as JSON",
+        epilog=(
+            "examples:\n"
+            "  orbitkb analyze \"Add support for Pix in checkout\"\n"
+            "  orbitkb analyze \"Add support for Pix in checkout\" --backend claude --db verify/sample_project.db\n"
+            "  orbitkb analyze \"xyz internal cleanup\" --hint-services notification-service\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_analyze.add_argument("task", help="Free-text engineering task/epic, e.g. \"Add support for Pix in checkout\"")
+    p_analyze.add_argument("--hint-services", nargs="+", default=None, help="Anchor the search on these services even without a keyword match")
+    add_backend_args(p_analyze)
+    p_analyze.set_defaults(func=_cmd_analyze)
+
+    p_verify = sub.add_parser(
+        "verify", help="Compare a past find_change_surface run against what a repository's commits actually changed",
+        epilog=(
+            "example:\n"
+            "  orbitkb verify 3 --repository my-monorepo --since a1b2c3d --record-feedback\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_verify.add_argument("run_id", type=int, help="run_id from a prior find_change_surface/analyze response")
+    p_verify.add_argument("--repository", required=True, help="Repository name, as shown by `orbitkb list`/`--repository-name` at index time")
+    p_verify.add_argument("--since", required=True, help="Commit the run was made against; actual changes are `git diff --since..HEAD`")
+    p_verify.add_argument("--record-feedback", action="store_true", help="Auto-record confirmed/rejected feedback for the predicted services")
+    p_verify.add_argument("--db", type=Path, default=DEFAULT_DB_PATH, help=f"SQLite database path (default: {DEFAULT_DB_PATH})")
+    p_verify.set_defaults(func=_cmd_verify)
+
+    p_serve = sub.add_parser(
+        "serve", help="Run the MCP server (stdio)",
+        epilog=(
+            "example (register with an MCP client, e.g. Claude Code/Codex):\n"
+            "  orbitkb serve --backend claude\n"
+            "  orbitkb serve --db ~/.orbitkb/orbitkb.db --backend codex\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_serve.add_argument("--transport", choices=["stdio"], default="stdio", help="MCP transport (only stdio is supported today)")
+    add_backend_args(p_serve)  # find_change_surface is the only tool that uses a backend
+    p_serve.set_defaults(func=_cmd_serve)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        print("\ncancelado pelo usuário (Ctrl+C)", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

orbitkb/cli_progress.py

@@ -0,0 +1,64 @@
+"""Rich-based terminal progress for `orbitkb index`/`update`.
+
+Kept separate from generation/orchestrator.py so the generation logic never depends
+on a UI library — it only calls the small ProgressReporter protocol.
+"""
+from __future__ import annotations
+
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+
+_STATUS_STYLE = {
+    "ok": "[green]ok[/green]",
+    "failed": "[bold red]falhou[/bold red]",
+    "skipped": "[dim]sem mudanças[/dim]",
+}
+
+
+class RichProgressReporter:
+    """One growing bar per service; finished services stay on screen at 100%, so a
+    multi-service run visibly fills up from top to bottom. TimeElapsedColumn keeps
+    ticking on the active row even while a single slow LLM call is in flight, so a
+    stalled step is visibly still "alive" (elapsed climbing) versus truly hung
+    (spinner frozen too, which only happens if the process itself died).
+    """
+
+    def __init__(self) -> None:
+        self._progress = Progress(
+            SpinnerColumn(),
+            TextColumn("[bold]{task.fields[service]}[/bold]"),
+            BarColumn(),
+            TaskProgressColumn(),
+            MofNCompleteColumn(),
+            TextColumn("{task.fields[detail]}"),
+            TimeElapsedColumn(),
+        )
+        self._tasks: dict[str, int] = {}
+
+    def __enter__(self) -> "RichProgressReporter":
+        self._progress.__enter__()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self._progress.__exit__(*exc)
+
+    def service_started(self, service: str, total_units: int) -> None:
+        task_id = self._progress.add_task(service, total=max(total_units, 1), service=service, detail="iniciando…")
+        self._tasks[service] = task_id
+
+    def unit_started(self, service: str, label: str) -> None:
+        self._progress.update(self._tasks[service], detail=f"gerando: {label}…")
+
+    def unit_finished(self, service: str, label: str, status: str) -> None:
+        style = _STATUS_STYLE.get(status, status)
+        self._progress.update(self._tasks[service], advance=1, detail=f"{label}: {style}")
+
+    def service_finished(self, service: str) -> None:
+        self._progress.update(self._tasks[service], detail="[bold green]concluído[/bold green]")

orbitkb/config.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from orbitkb.generation.backend_base import LLMBackend
+from orbitkb.generation.claude_backend import ClaudeBackend
+from orbitkb.generation.codex_backend import CodexBackend
+
+DEFAULT_BACKEND = "claude"
+DEFAULT_DB_PATH = Path.home() / ".orbitkb" / "orbitkb.db"
+
+
+def resolve_backend(
+    name: str | None, model: str | None = None, claude_bare: bool = False, codex_api_key: bool = False
+) -> LLMBackend:
+    chosen = name or os.environ.get("ORBITKB_BACKEND", DEFAULT_BACKEND)
+    if chosen == "claude":
+        return ClaudeBackend(model=model, bare=claude_bare)
+    if chosen == "codex":
+        return CodexBackend(model=model, api_key=codex_api_key)
+    raise ValueError(f"Unknown backend: {chosen!r} (expected 'claude' or 'codex')")

orbitkb/db/connection.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import sqlite3
+from importlib import resources
+from pathlib import Path
+
+SCHEMA_VERSION = "2"
+DEFAULT_DB_PATH = Path.home() / ".orbitkb" / "orbitkb.db"
+
+
+def open_db(db_path: Path | None = None) -> sqlite3.Connection:
+    path = db_path or DEFAULT_DB_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    _init_schema(conn)
+    return conn
+
+
+def _init_schema(conn: sqlite3.Connection) -> None:
+    schema_sql = resources.files("orbitkb.db").joinpath("schema.sql").read_text()
+    conn.executescript(schema_sql)
+    row = conn.execute("SELECT value FROM schema_meta WHERE key = 'schema_version'").fetchone()
+    if row is None:
+        conn.execute(
+            "INSERT INTO schema_meta (key, value) VALUES ('schema_version', ?)", (SCHEMA_VERSION,)
+        )
+        conn.commit()

orbitkb/db/repositories/__init__.py

@@ -0,0 +1,3 @@
+"""One module per aggregate, each owning the SQL for its own tables. These are the
+only modules allowed to run SQL against the orbitkb database (replaces the single
+db/repository.py, which had grown to own nine unrelated aggregates)."""

orbitkb/db/repositories/_util.py

@@ -0,0 +1,8 @@
+"""Shared helper for every repository module."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat()

orbitkb/db/repositories/apis.py

@@ -0,0 +1,81 @@
+"""The `apis` and `api_validations` tables: one microservice's HTTP endpoints and
+the validation/authorization rules attached to each."""
+from __future__ import annotations
+
+import json
+import sqlite3
+
+from ._util import now
+
+
+def upsert_api(
+    conn: sqlite3.Connection,
+    service_id: int,
+    method: str,
+    path: str,
+    summary: str,
+    description: str,
+    response_shape: dict,
+    evidence: list[dict],
+    request_shape: list[dict] | None = None,
+) -> int:
+    row = conn.execute(
+        "SELECT id FROM apis WHERE service_id = ? AND method = ? AND path = ?",
+        (service_id, method, path),
+    ).fetchone()
+    payload = (
+        summary, description, json.dumps(response_shape), json.dumps(request_shape or []),
+        json.dumps(evidence), now(),
+    )
+    if row is not None:
+        conn.execute(
+            """UPDATE apis SET summary = ?, description = ?, response_shape = ?, request_shape = ?,
+               evidence_json = ?, updated_at = ? WHERE id = ?""",
+            (*payload, row["id"]),
+        )
+        api_id = row["id"]
+    else:
+        cur = conn.execute(
+            """INSERT INTO apis (service_id, method, path, summary, description, response_shape,
+               request_shape, evidence_json, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (service_id, method, path, *payload),
+        )
+        api_id = cur.lastrowid
+    conn.commit()
+    return api_id
+
+
+def replace_api_validations(conn: sqlite3.Connection, api_id: int, validations: list[dict]) -> None:
+    conn.execute("DELETE FROM api_validations WHERE api_id = ?", (api_id,))
+    conn.executemany(
+        "INSERT INTO api_validations (api_id, kind, description) VALUES (?, ?, ?)",
+        [(api_id, v["kind"], v["description"]) for v in validations],
+    )
+    conn.commit()
+
+
+def prune_apis_not_in(conn: sqlite3.Connection, service_id: int, keep_keys: set[tuple[str, str]]) -> None:
+    rows = conn.execute("SELECT id, method, path FROM apis WHERE service_id = ?", (service_id,)).fetchall()
+    for row in rows:
+        if (row["method"], row["path"]) not in keep_keys:
+            conn.execute("DELETE FROM apis WHERE id = ?", (row["id"],))
+    conn.commit()
+
+
+def get_api_by_key(conn: sqlite3.Connection, service_id: int, method: str, path: str) -> sqlite3.Row | None:
+    return conn.execute(
+        "SELECT * FROM apis WHERE service_id = ? AND method = ? AND path = ?", (service_id, method, path)
+    ).fetchone()
+
+
+def list_apis(conn: sqlite3.Connection, service_id: int) -> list[sqlite3.Row]:
+    return conn.execute(
+        "SELECT method, path, summary, description, evidence_json FROM apis WHERE service_id = ? ORDER BY path, method",
+        (service_id,),
+    ).fetchall()
+
+
+def list_validations_for_api(conn: sqlite3.Connection, api_id: int) -> list[sqlite3.Row]:
+    return conn.execute(
+        "SELECT kind, description FROM api_validations WHERE api_id = ? ORDER BY kind", (api_id,)
+    ).fetchall()

orbitkb/db/repositories/architecture.py

@@ -0,0 +1,43 @@
+"""The `architecture_runs`/`architecture_findings` tables: deterministic, whole-graph
+structural findings recomputed after every index/update. See generation/architecture.py
+for the detectors themselves — this module only persists and reads their output."""
+from __future__ import annotations
+
+import json
+import sqlite3
+
+from ._util import now
+
+
+def start_run(conn: sqlite3.Connection, services_indexed: int) -> int:
+    cur = conn.execute(
+        "INSERT INTO architecture_runs (created_at, services_indexed) VALUES (?, ?)",
+        (now(), services_indexed),
+    )
+    conn.commit()
+    return cur.lastrowid
+
+
+def record_finding(
+    conn: sqlite3.Connection, run_id: int, kind: str, severity: str, services: list[str], reason: str,
+    detail: dict | None = None,
+) -> None:
+    conn.execute(
+        """INSERT INTO architecture_findings (run_id, kind, severity, services_json, detail_json, reason)
+           VALUES (?, ?, ?, ?, ?, ?)""",
+        (run_id, kind, severity, json.dumps(services), json.dumps(detail or {}), reason),
+    )
+    conn.commit()
+
+
+def latest_run_id(conn: sqlite3.Connection) -> int | None:
+    row = conn.execute("SELECT id FROM architecture_runs ORDER BY id DESC LIMIT 1").fetchone()
+    return row["id"] if row else None
+
+
+def list_findings(conn: sqlite3.Connection, run_id: int) -> list[sqlite3.Row]:
+    return conn.execute(
+        """SELECT kind, severity, services_json, detail_json, reason
+           FROM architecture_findings WHERE run_id = ? ORDER BY severity DESC, kind""",
+        (run_id,),
+    ).fetchall()

orbitkb/db/repositories/change_surface.py

@@ -0,0 +1,71 @@
+"""The change-surface audit trail: `change_surface_runs`, `change_surface_findings`
+and `change_surface_feedback` — every find_change_surface call and the outcome
+feedback agents report back (see generation/change_surface.py, which is the
+task-inference logic; this module is only the storage for it)."""
+from __future__ import annotations
+
+import json
+import sqlite3
+
+from ._util import now
+
+_ROLE_BY_RESULT_KEY = {
+    "primary": "primary",
+    "secondary": "secondary",
+    "no_change_hint": "no_change",
+    "external_integrations": "external_integration",
+    "unmapped_internal_hint": "unmapped_internal",
+}
+
+
+def record_change_surface_run(conn: sqlite3.Connection, task_text: str, backend: str, result: dict) -> int:
+    cur = conn.execute(
+        "INSERT INTO change_surface_runs (task_text, backend, created_at) VALUES (?, ?, ?)",
+        (task_text, backend, now()),
+    )
+    run_id = cur.lastrowid
+    rows = [
+        (run_id, f["service"], role, f.get("reason"), f.get("confidence"), json.dumps(f.get("evidence", [])))
+        for key, role in _ROLE_BY_RESULT_KEY.items()
+        for f in result.get(key, [])
+    ]
+    conn.executemany(
+        """INSERT INTO change_surface_findings (run_id, service, role, reason, confidence, evidence_json)
+           VALUES (?, ?, ?, ?, ?, ?)""",
+        rows,
+    )
+    conn.commit()
+    return run_id
+
+
+def get_change_surface_run(conn: sqlite3.Connection, run_id: int) -> sqlite3.Row | None:
+    return conn.execute("SELECT * FROM change_surface_runs WHERE id = ?", (run_id,)).fetchone()
+
+
+def list_change_surface_runs(conn: sqlite3.Connection, limit: int = 10) -> list[sqlite3.Row]:
+    return conn.execute("SELECT * FROM change_surface_runs ORDER BY id DESC LIMIT ?", (limit,)).fetchall()
+
+
+def list_change_surface_findings(conn: sqlite3.Connection, run_id: int) -> list[sqlite3.Row]:
+    return conn.execute(
+        "SELECT * FROM change_surface_findings WHERE run_id = ? ORDER BY id", (run_id,)
+    ).fetchall()
+
+
+def record_change_surface_feedback(conn: sqlite3.Connection, run_id: int, service: str, outcome: str) -> None:
+    conn.execute(
+        "INSERT INTO change_surface_feedback (run_id, service, outcome, recorded_at) VALUES (?, ?, ?, ?)",
+        (run_id, service, outcome, now()),
+    )
+    conn.commit()
+
+
+def get_feedback_stats(conn: sqlite3.Connection, service: str) -> dict[str, int]:
+    row = conn.execute(
+        """SELECT
+             SUM(CASE WHEN outcome = 'confirmed' THEN 1 ELSE 0 END) AS confirmed,
+             SUM(CASE WHEN outcome = 'rejected' THEN 1 ELSE 0 END) AS rejected
+           FROM change_surface_feedback WHERE service = ?""",
+        (service,),
+    ).fetchone()
+    return {"confirmed": row["confirmed"] or 0, "rejected": row["rejected"] or 0}