puremethod 0.1.0__py3-none-any.whl

app/repo.py

@@ -0,0 +1,746 @@
+"""Tenant-scoped data access (08-app.md §5 step 6, INV-1). A `TenantRepo` is bound to one
+tenant and every statement filters on it; there is no unscoped helper. The one cross-tenant
+query, finding work for workers, lives in `app.scan`, which `app.api` may not import."""
+
+from __future__ import annotations
+
+import json
+import secrets
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from app import ssh_machines
+from app.db import Conn, Database
+from app.keys import seal
+
+CREDENTIAL_TYPES = ("llm-key", "ssh-key", "data-token", "purescholar-key", "puretrace-key",
+                    "literature-key")
+# What `POST /credentials/{id}/check` can check, by credential type (08-app.md §3, KB-029,
+# KB-039).
+CHECK_KINDS = {"llm-key": "llm", "purescholar-key": "purescholar", "puretrace-key": "puretrace",
+               "literature-key": "source"}
+SERVICES = ("literature", "puretrace")
+
+
+def now_iso() -> str:
+    return datetime.now(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}_{secrets.token_hex(8)}"
+
+
+class StaleEdit(Exception):
+    """The profile changed after this edit was made from it (KB-041)."""
+
+
+@dataclass(frozen=True)
+class CredentialInfo:
+    """A stored credential's public facts. There is deliberately no value field (INV-2)."""
+    id: str
+    name: str
+    type: str
+    created_at: str
+
+
+@dataclass(frozen=True)
+class Sealed:
+    id: str
+    nonce: bytes
+    ciphertext: bytes
+
+
+@dataclass(frozen=True)
+class ExecutorRow:
+    id: str
+    name: str
+    kind: str
+    config: dict[str, Any]
+    created_at: str
+
+
+@dataclass(frozen=True)
+class MachineRow:
+    id: str
+    name: str
+    config: dict[str, Any]
+    created_at: str
+
+
+@dataclass(frozen=True)
+class ProfileRow:
+    id: str
+    name: str
+    roles: dict[str, dict[str, Any]]
+    prices: dict[str, dict[str, float]]
+    created_at: str
+    # Raised by each change to roles or prices; a check counts for the version it checked
+    # (08 §3 Profile edits, KB-041). A rename keeps the version.
+    version: int = 1
+
+
+@dataclass(frozen=True)
+class RunRow:
+    id: str
+    title: str
+    ledger_run_id: str | None
+    state: str  # queued | starting | started | start_failed
+    start_error: str | None
+    worker_error: str | None
+    config: dict[str, Any]
+    prices: dict[str, dict[str, float]]
+    executor: dict[str, Any]  # snapshot at creation: id, name, kind, config
+    created_at: str
+    # Snapshot at creation of where the run reaches PureScholar and PureTrace: a URL, "local"
+    # (the bundled PureScholar) or None. None for runs created before KB-029.
+    services: dict[str, str | None] | None = None
+    # The LLM profile the run was started from; None for runs created before KB-041.
+    llm_profile_id: str | None = None
+
+
+@dataclass(frozen=True)
+class CommandRow:
+    id: str
+    run_id: str
+    seq: int
+    kind: str
+    payload: dict[str, Any]
+    state: str  # pending | done | refused
+    reason: str | None
+    created_at: str
+    done_at: str | None
+
+
+@dataclass(frozen=True)
+class CheckRow:
+    id: str
+    executor_id: str
+    state: str  # pending | done
+    report: dict[str, Any] | None
+    created_at: str
+    done_at: str | None
+
+
+@dataclass(frozen=True)
+class CredentialCheckRow:
+    id: str
+    credential_id: str
+    kind: str  # llm | purescholar | puretrace
+    request: dict[str, Any]  # what to check against; never a credential value
+    state: str  # pending | done
+    report: dict[str, Any] | None  # {"ok": bool, "problems": [...]}
+    created_at: str
+    done_at: str | None
+
+
+def _ccheck(r: tuple[Any, ...]) -> CredentialCheckRow:
+    return CredentialCheckRow(r[0], r[1], r[2], json.loads(r[3]), r[4],
+                              json.loads(r[5]) if r[5] else None, r[6], r[7])
+
+
+_CC_COLS = "id, credential_id, kind, request, state, report, created_at, done_at"
+
+
+def _run(r: tuple[Any, ...]) -> RunRow:
+    return RunRow(r[0], r[1], r[2], r[3], r[4], r[5], json.loads(r[6]), json.loads(r[7]),
+                  json.loads(r[8]), r[9], json.loads(r[10]) if r[10] else None, r[11])
+
+
+def _cmd(r: tuple[Any, ...]) -> CommandRow:
+    return CommandRow(r[0], r[1], int(r[2]), r[3], json.loads(r[4]), r[5], r[6], r[7], r[8])
+
+
+_RUN_COLS = ("id, title, ledger_run_id, state, start_error, worker_error, config, prices, "
+             "executor, created_at, services, llm_profile_id")
+_CMD_COLS = "id, run_id, seq, kind, payload, state, reason, created_at, done_at"
+
+
+class TenantRepo:
+    def __init__(self, db: Database, tenant_id: str, master_key: bytes | None = None) -> None:
+        if not tenant_id:
+            raise ValueError("a tenant id is required")
+        self._db = db
+        self.tenant_id = tenant_id
+        self._key = master_key  # sealing only; nothing here decrypts
+
+    # ---- credentials ------------------------------------------------------------------
+
+    def add_credential(self, name: str, type_: str, value: str) -> CredentialInfo:
+        if self._key is None:
+            raise RuntimeError("this repository cannot seal credentials")
+        if type_ not in CREDENTIAL_TYPES:
+            raise ValueError(f"unknown credential type {type_!r}")
+        cid, at = new_id("k"), now_iso()
+        nonce, ct = seal(self._key, self.tenant_id, cid, value)
+        with self._db.tx(write=True) as c:
+            if c.execute("SELECT 1 FROM credentials WHERE tenant_id = ? AND name = ?",
+                         (self.tenant_id, name)):
+                raise ValueError(f"a credential named {name!r} exists")
+            c.execute("INSERT INTO credentials VALUES (?, ?, ?, ?, ?, ?, ?)",
+                      (cid, self.tenant_id, name, type_, nonce, ct, at))
+        return CredentialInfo(cid, name, type_, at)
+
+    def list_credentials(self) -> list[CredentialInfo]:
+        with self._db.tx() as c:
+            rows = c.execute("SELECT id, name, type, created_at FROM credentials "
+                             "WHERE tenant_id = ? ORDER BY name", (self.tenant_id,))
+        return [CredentialInfo(*r) for r in rows]
+
+    def credential_types(self) -> dict[str, str]:
+        return {c.name: c.type for c in self.list_credentials()}
+
+    def delete_credential(self, credential_id: str) -> bool:
+        with self._db.tx(write=True) as c:
+            c.execute("DELETE FROM credential_checks WHERE tenant_id = ? AND credential_id = ?",
+                      (self.tenant_id, credential_id))
+            return c.rowcount("DELETE FROM credentials WHERE tenant_id = ? AND id = ?",
+                              (self.tenant_id, credential_id)) == 1
+
+    def credential(self, credential_id: str) -> CredentialInfo | None:
+        return next((c for c in self.list_credentials() if c.id == credential_id), None)
+
+    def sealed(self, name: str) -> Sealed | None:
+        with self._db.tx() as c:
+            rows = c.execute("SELECT id, nonce, ciphertext FROM credentials "
+                             "WHERE tenant_id = ? AND name = ?", (self.tenant_id, name))
+        return Sealed(rows[0][0], bytes(rows[0][1]), bytes(rows[0][2])) if rows else None
+
+    # ---- rate limits (08 INV-11, KB-036) -------------------------------------------------
+
+    def take(self, kind: str, limit: int, window_s: float, now: float) -> bool:
+        """Counts one use of `kind`; False (nothing counted) when `limit` uses already fall
+        in the last `window_s` seconds."""
+        with self._db.tx(write=True) as c:
+            c.execute("DELETE FROM rate_events WHERE tenant_id = ? AND at < ?",
+                      (self.tenant_id, now - window_s))
+            used = c.execute("SELECT COUNT(*) FROM rate_events WHERE tenant_id = ? AND kind = ?",
+                             (self.tenant_id, kind))[0][0]
+            if used >= limit:
+                return False
+            c.execute("INSERT INTO rate_events VALUES (?, ?, ?)", (self.tenant_id, kind, now))
+        return True
+
+    # ---- model searches (08 §3 `/llm-servers/search`, KB-036) -----------------------------
+
+    def add_search(self, target: dict[str, Any]) -> dict[str, Any]:
+        sid, at = new_id("ls"), now_iso()
+        with self._db.tx(write=True) as c:
+            c.execute("INSERT INTO llm_searches VALUES (?, ?, ?, 'pending', NULL, ?, NULL)",
+                      (sid, self.tenant_id, json.dumps(target), at))
+        return {"id": sid, "target": target, "state": "pending", "report": None,
+                "created_at": at, "done_at": None}
+
+    def get_search(self, search_id: str) -> dict[str, Any] | None:
+        with self._db.tx() as c:
+            rows = c.execute("SELECT id, target, state, report, created_at, done_at "
+                             "FROM llm_searches WHERE tenant_id = ? AND id = ?",
+                             (self.tenant_id, search_id))
+        if not rows:
+            return None
+        r = rows[0]
+        return {"id": r[0], "target": json.loads(r[1]), "state": r[2],
+                "report": json.loads(r[3]) if r[3] else None, "created_at": r[4],
+                "done_at": r[5]}
+
+    def finish_search(self, search_id: str, report: dict[str, Any]) -> None:
+        with self._db.tx(write=True) as c:
+            c.execute("UPDATE llm_searches SET state = 'done', report = ?, done_at = ? "
+                      "WHERE tenant_id = ? AND id = ?",
+                      (json.dumps(report), now_iso(), self.tenant_id, search_id))
+
+    # ---- SSH machines (KB-036) ----------------------------------------------------------
+
+    def list_machines(self) -> list[MachineRow]:
+        with self._db.tx() as c:
+            rows = c.execute("SELECT id, name, config, created_at FROM ssh_machines "
+                             "WHERE tenant_id = ? ORDER BY name", (self.tenant_id,))
+        return [MachineRow(r[0], r[1], json.loads(r[2]), r[3]) for r in rows]
+
+    def get_machine(self, machine_id: str) -> MachineRow | None:
+        return next((m for m in self.list_machines() if m.id == machine_id), None)
+
+    def save_machine(self, machine_id: str | None, name: str,
+                     config: dict[str, Any]) -> MachineRow:
+        """Adds (`machine_id` None) or replaces a machine, then re-resolves every `ssh`
+        executor from the machines, all in one transaction: an executor's copy never
+        disagrees with its machine. Raises ValueError (name taken, unknown or looping jump
+        hosts, a hop without a confirmed host key) with nothing written; KeyError if the
+        machine is not this tenant's."""
+        mid, at = machine_id or new_id("m"), now_iso()
+        with self._db.tx(write=True) as c:
+            if c.execute("SELECT 1 FROM ssh_machines WHERE tenant_id = ? AND name = ? "
+                         "AND id <> ?", (self.tenant_id, name, mid)):
+                raise ValueError(f"an SSH machine named {name!r} exists")
+            if machine_id is None:
+                c.execute("INSERT INTO ssh_machines VALUES (?, ?, ?, ?, ?)",
+                          (mid, self.tenant_id, name, json.dumps(config), at))
+            elif not c.rowcount("UPDATE ssh_machines SET name = ?, config = ? "
+                                "WHERE tenant_id = ? AND id = ?",
+                                (name, json.dumps(config), self.tenant_id, mid)):
+                raise KeyError(machine_id)
+            else:
+                at = c.execute("SELECT created_at FROM ssh_machines WHERE id = ?", (mid,))[0][0]
+            self._resolve_executors(c)
+        return MachineRow(mid, name, config, at)
+
+    def _resolve_executors(self, c: Any) -> None:
+        machines = {r[0]: json.loads(r[1]) for r in c.execute(
+            "SELECT id, config FROM ssh_machines WHERE tenant_id = ?", (self.tenant_id,))}
+        for mid in machines:
+            ssh_machines.chain(machines, mid)  # every machine's chain must hold
+        for xid, raw in c.execute("SELECT id, config FROM executors WHERE tenant_id = ? "
+                                  "AND kind = 'ssh'", (self.tenant_id,)):
+            cfg = json.loads(raw)
+            if cfg.get("machine") in machines:
+                cfg.update(ssh_machines.resolve(machines, cfg["machine"]))
+                c.execute("UPDATE executors SET config = ? WHERE tenant_id = ? AND id = ?",
+                          (json.dumps(cfg), self.tenant_id, xid))
+
+    def resolve_machine(self, machine_id: str) -> dict[str, Any]:
+        """The connection fields an `ssh` executor stores for this machine. KeyError if it is
+        not this tenant's."""
+        machines = {m.id: m.config for m in self.list_machines()}
+        if machine_id not in machines:
+            raise KeyError(machine_id)
+        return ssh_machines.resolve(machines, machine_id)
+
+    def delete_machine(self, machine_id: str) -> list[str] | None:
+        """Deletes an unused machine: returns [] when deleted, None when there is no such
+        machine, or what uses it (nothing deleted)."""
+        with self._db.tx(write=True) as c:
+            rows = c.execute("SELECT id, name, config FROM ssh_machines WHERE tenant_id = ?",
+                             (self.tenant_id,))
+            machines = {r[0]: (r[1], json.loads(r[2])) for r in rows}
+            if machine_id not in machines:
+                return None
+            executors = [(r[0], json.loads(r[1])) for r in c.execute(
+                "SELECT name, config FROM executors WHERE tenant_id = ? AND kind = 'ssh'",
+                (self.tenant_id,))]
+            used = ssh_machines.users(machines, executors, machine_id)
+            for pname, raw in c.execute("SELECT name, roles FROM llm_profiles WHERE "
+                                        "tenant_id = ? AND deleted_at IS NULL",
+                                        (self.tenant_id,)):
+                specs = json.loads(raw).values()
+                if any(machine_id in (s.get("machine"), (s.get("fallback") or {}).get("machine"))
+                       for s in specs):
+                    used.append(f"LLM profile {pname}")
+            if used:
+                return used
+            c.execute("DELETE FROM ssh_machines WHERE tenant_id = ? AND id = ?",
+                      (self.tenant_id, machine_id))
+        return []
+
+    # ---- executors --------------------------------------------------------------------
+
+    def add_executor(self, name: str, kind: str, config: dict[str, Any]) -> ExecutorRow:
+        xid, at = new_id("x"), now_iso()
+        with self._db.tx(write=True) as c:
+            if c.execute("SELECT 1 FROM executors WHERE tenant_id = ? AND name = ?",
+                         (self.tenant_id, name)):
+                raise ValueError(f"an executor named {name!r} exists")
+            c.execute("INSERT INTO executors VALUES (?, ?, ?, ?, ?, ?)",
+                      (xid, self.tenant_id, name, kind, json.dumps(config), at))
+        return ExecutorRow(xid, name, kind, config, at)
+
+    def list_executors(self) -> list[ExecutorRow]:
+        with self._db.tx() as c:
+            rows = c.execute("SELECT id, name, kind, config, created_at FROM executors "
+                             "WHERE tenant_id = ? ORDER BY name", (self.tenant_id,))
+        return [ExecutorRow(r[0], r[1], r[2], json.loads(r[3]), r[4]) for r in rows]
+
+    def get_executor(self, executor_id: str) -> ExecutorRow | None:
+        with self._db.tx() as c:
+            rows = c.execute("SELECT id, name, kind, config, created_at FROM executors "
+                             "WHERE tenant_id = ? AND id = ?", (self.tenant_id, executor_id))
+        return ExecutorRow(rows[0][0], rows[0][1], rows[0][2], json.loads(rows[0][3]),
+                           rows[0][4]) if rows else None
+
+    def update_executor(self, executor_id: str, name: str, config: dict[str, Any]) -> bool:
+        with self._db.tx(write=True) as c:
+            if c.execute("SELECT 1 FROM executors WHERE tenant_id = ? AND name = ? AND id <> ?",
+                         (self.tenant_id, name, executor_id)):
+                raise ValueError(f"an executor named {name!r} exists")
+            return c.rowcount("UPDATE executors SET name = ?, config = ? "
+                              "WHERE tenant_id = ? AND id = ?",
+                              (name, json.dumps(config), self.tenant_id, executor_id)) == 1
+
+    def delete_executor(self, executor_id: str) -> bool:
+        with self._db.tx(write=True) as c:
+            c.execute("DELETE FROM preflight_checks WHERE tenant_id = ? AND executor_id = ?",
+                      (self.tenant_id, executor_id))
+            return c.rowcount("DELETE FROM executors WHERE tenant_id = ? AND id = ?",
+                              (self.tenant_id, executor_id)) == 1
+
+    # ---- LLM profiles -----------------------------------------------------------------
+
+    def add_profile(self, name: str, roles: dict[str, dict[str, Any]],
+                    prices: dict[str, dict[str, float]]) -> ProfileRow:
+        pid, at = new_id("p"), now_iso()
+        with self._db.tx(write=True) as c:
+            self._name_free(c, name)
+            c.execute("INSERT INTO llm_profiles (id, tenant_id, name, roles, prices, created_at) "
+                      "VALUES (?, ?, ?, ?, ?, ?)",
+                      (pid, self.tenant_id, name, json.dumps(roles), json.dumps(prices), at))
+        return ProfileRow(pid, name, roles, prices, at)
+
+    def _name_free(self, c: Conn, name: str, but: str | None = None) -> None:
+        if any(r[0] != but for r in c.execute(
+                "SELECT id FROM llm_profiles WHERE tenant_id = ? AND name = ?",
+                (self.tenant_id, name))):
+            raise ValueError(f"a profile named {name!r} exists")
+
+    def list_profiles(self) -> list[ProfileRow]:
+        with self._db.tx() as c:
+            rows = c.execute("SELECT id, name, roles, prices, created_at, version "
+                             "FROM llm_profiles WHERE tenant_id = ? AND deleted_at IS NULL "
+                             "ORDER BY name", (self.tenant_id,))
+        return [ProfileRow(r[0], r[1], json.loads(r[2]), json.loads(r[3]), r[4], int(r[5]))
+                for r in rows]
+
+    def get_profile(self, profile_id: str) -> ProfileRow | None:
+        return next((p for p in self.list_profiles() if p.id == profile_id), None)
+
+    def rename_profile(self, profile_id: str, name: str) -> None:
+        """A rename keeps the version, so the profile's checks still count (KB-041)."""
+        with self._db.tx(write=True) as c:
+            self._name_free(c, name, but=profile_id)
+            if not c.rowcount("UPDATE llm_profiles SET name = ? WHERE tenant_id = ? AND id = ? "
+                              "AND deleted_at IS NULL", (name, self.tenant_id, profile_id)):
+                raise KeyError(profile_id)
+
+    def edit_profile_unchecked(self, profile_id: str, roles: dict[str, dict[str, Any]],
+                               prices: dict[str, dict[str, float]], version: int) -> int:
+        """Saved without checking (KB-041): applied at once, and the new version has no
+        check yet. `version` is the one the user edited; a newer one refuses the edit."""
+        with self._db.tx(write=True) as c:
+            return self._bump(c, profile_id, roles, prices, version)
+
+    def _bump(self, c: Conn, profile_id: str, roles: dict[str, dict[str, Any]],
+              prices: dict[str, dict[str, float]], version: int) -> int:
+        rows = c.execute("SELECT version FROM llm_profiles WHERE tenant_id = ? AND id = ? AND "
+                         "deleted_at IS NULL", (self.tenant_id, profile_id))
+        if not rows:
+            raise KeyError(profile_id)
+        if int(rows[0][0]) != version:
+            raise StaleEdit(profile_id)
+        c.execute("UPDATE llm_profiles SET roles = ?, prices = ?, version = ? "
+                  "WHERE tenant_id = ? AND id = ?",
+                  (json.dumps(roles), json.dumps(prices), version + 1, self.tenant_id,
+                   profile_id))
+        return version + 1
+
+    def delete_profile(self, profile_id: str) -> bool:
+        """Hidden, not removed, so its past checks stay readable (KB-041). The stored name
+        gets the id appended, which frees the name for a new profile."""
+        with self._db.tx(write=True) as c:
+            return c.rowcount("UPDATE llm_profiles SET deleted_at = ?, "
+                              "name = name || ' (deleted ' || id || ')' "
+                              "WHERE tenant_id = ? AND id = ? AND deleted_at IS NULL",
+                              (now_iso(), self.tenant_id, profile_id)) == 1
+
+    def profile_checked(self, profile: ProfileRow) -> bool:
+        """Its latest check passed and checked its current version (08 §3 Profile edits)."""
+        check = self.latest_profile_check(profile.id)
+        return bool(check and check["state"] == "done" and (check["report"] or {}).get("ok")
+                    and check["version"] == profile.version)
+
+    # ---- profile checks (08 §3, §5 step 14, KB-037; edits, KB-041) ------------------------
+
+    def add_profile_check(self, profile_id: str, proposal: dict[str, Any] | None = None,
+                          version: int | None = None) -> dict[str, Any]:
+        """A check of the profile as it is, or of a proposed edit of it (`proposal`: roles
+        and prices) made from `version`."""
+        cid, at = new_id("pc"), now_iso()
+        with self._db.tx(write=True) as c:
+            rows = c.execute("SELECT version FROM llm_profiles WHERE tenant_id = ? AND id = ? "
+                             "AND deleted_at IS NULL", (self.tenant_id, profile_id))
+            if not rows:
+                raise KeyError(profile_id)
+            current = int(rows[0][0])
+            if version is not None and version != current:
+                raise StaleEdit(profile_id)
+            c.execute("INSERT INTO profile_checks (id, tenant_id, profile_id, state, report, "
+                      "created_at, done_at, version, proposal, applied) "
+                      "VALUES (?, ?, ?, 'pending', NULL, ?, NULL, ?, ?, 0)",
+                      (cid, self.tenant_id, profile_id, at, current,
+                       json.dumps(proposal) if proposal is not None else None))
+        return {"id": cid, "profile_id": profile_id, "state": "pending", "report": None,
+                "created_at": at, "done_at": None, "version": current,
+                "proposal": proposal, "applied": False}
+
+    def _profile_checks(self, where: str, args: tuple[Any, ...]) -> list[dict[str, Any]]:
+        with self._db.tx() as c:
+            rows = c.execute("SELECT id, profile_id, state, report, created_at, done_at, "  # noqa: S608
+                             "version, proposal, applied "
+                             f"FROM profile_checks WHERE tenant_id = ? AND {where} "
+                             "ORDER BY created_at DESC, rowid DESC", (self.tenant_id, *args))
+        return [{"id": r[0], "profile_id": r[1], "state": r[2],
+                 "report": json.loads(r[3]) if r[3] else None, "created_at": r[4],
+                 "done_at": r[5], "version": int(r[6]),
+                 "proposal": json.loads(r[7]) if r[7] else None, "applied": bool(r[8])}
+                for r in rows]
+
+    def profile_check(self, check_id: str) -> dict[str, Any] | None:
+        rows = self._profile_checks("id = ?", (check_id,))
+        return rows[0] if rows else None
+
+    def get_profile_check(self, profile_id: str, check_id: str) -> dict[str, Any] | None:
+        rows = self._profile_checks("profile_id = ? AND id = ?", (profile_id, check_id))
+        return rows[0] if rows else None
+
+    def latest_profile_check(self, profile_id: str) -> dict[str, Any] | None:
+        """The latest check of the profile itself: a proposed edit's check counts only once
+        it was applied (KB-041)."""
+        rows = self._profile_checks("profile_id = ? AND (proposal IS NULL OR applied = 1)",
+                                    (profile_id,))
+        return rows[0] if rows else None
+
+    def finish_profile_check(self, check_id: str, report: dict[str, Any]) -> dict[str, Any]:
+        """Records the report. A passed check of a proposed edit applies it, unless the
+        profile changed after the edit was proposed (KB-041). Returns the report stored."""
+        with self._db.tx(write=True) as c:
+            rows = c.execute("SELECT profile_id, version, proposal FROM profile_checks "
+                             "WHERE tenant_id = ? AND id = ?", (self.tenant_id, check_id))
+            applied, version = 0, None
+            if rows and rows[0][2] and report.get("ok"):
+                proposal = json.loads(rows[0][2])
+                try:
+                    version = self._bump(c, rows[0][0], proposal["roles"], proposal["prices"],
+                                         int(rows[0][1]))
+                    applied = 1
+                except (KeyError, StaleEdit):
+                    report = {"ok": False, "problems": [
+                        "the profile changed after this edit was proposed, so nothing was "
+                        "applied. Open the profile again and redo the edit"]}
+            c.execute("UPDATE profile_checks SET state = 'done', report = ?, done_at = ?, "
+                      "applied = ?, version = COALESCE(?, version) "
+                      "WHERE tenant_id = ? AND id = ?",
+                      (json.dumps(report), now_iso(), applied, version, self.tenant_id,
+                       check_id))
+        return report
+
+    # ---- runs and commands --------------------------------------------------------------
+
+    def create_run(self, title: str, config: dict[str, Any], prices: dict[str, dict[str, float]],
+                   executor: ExecutorRow, services: dict[str, str | None] | None = None,
+                   llm_profile_id: str | None = None) -> tuple[RunRow, CommandRow]:
+        """A queued run and its `start` command, in one transaction (KB-021). The executor is
+        stored as it is now, so later edits never reach this run."""
+        rid, cid, at = new_id("r"), new_id("c"), now_iso()
+        snap = {"id": executor.id, "name": executor.name, "kind": executor.kind,
+                "config": executor.config}
+        with self._db.tx(write=True) as c:
+            c.execute("INSERT INTO runs (id, tenant_id, title, ledger_run_id, state, "
+                      "start_error, worker_error, config, prices, executor, created_at, "
+                      "services, llm_profile_id) "
+                      "VALUES (?, ?, ?, NULL, 'queued', NULL, NULL, ?, ?, ?, ?, ?, ?)",
+                      (rid, self.tenant_id, title, json.dumps(config), json.dumps(prices),
+                       json.dumps(snap), at,
+                       json.dumps(services) if services is not None else None,
+                       llm_profile_id))
+            c.execute("INSERT INTO commands VALUES (?, ?, ?, 1, 'start', '{}', 'pending', NULL, "
+                      "?, NULL)", (cid, self.tenant_id, rid, at))
+        return (RunRow(rid, title, None, "queued", None, None, config, prices, snap, at,
+                       services, llm_profile_id),
+                CommandRow(cid, rid, 1, "start", {}, "pending", None, at, None))
+
+    def list_runs(self) -> list[RunRow]:
+        with self._db.tx() as c:
+            rows = c.execute(f"SELECT {_RUN_COLS} FROM runs WHERE tenant_id = ? "  # noqa: S608
+                             "ORDER BY created_at DESC, id", (self.tenant_id,))
+        return [_run(r) for r in rows]
+
+    def get_run(self, run_id: str) -> RunRow | None:
+        with self._db.tx() as c:
+            rows = c.execute(f"SELECT {_RUN_COLS} FROM runs "  # noqa: S608
+                             "WHERE tenant_id = ? AND id = ?", (self.tenant_id, run_id))
+        return _run(rows[0]) if rows else None
+
+    def set_run_state(self, run_id: str, state: str, *, ledger_run_id: str | None = None,
+                      start_error: str | None = None) -> None:
+        with self._db.tx(write=True) as c:
+            c.execute("UPDATE runs SET state = ?, ledger_run_id = COALESCE(?, ledger_run_id), "
+                      "start_error = ? WHERE tenant_id = ? AND id = ?",
+                      (state, ledger_run_id, start_error, self.tenant_id, run_id))
+
+    def set_worker_error(self, run_id: str, error: str | None) -> None:
+        with self._db.tx(write=True) as c:
+            c.execute("UPDATE runs SET worker_error = ? WHERE tenant_id = ? AND id = ?",
+                      (error, self.tenant_id, run_id))
+
+    def add_command(self, run_id: str, kind: str, payload: dict[str, Any]) -> CommandRow:
+        """Queues a user action. A new command also clears a worker error, so a worker is
+        tried again (KB-021: a later command starts a new worker)."""
+        cid, at = new_id("c"), now_iso()
+        with self._db.tx(write=True) as c:
+            if not c.execute("SELECT 1 FROM runs WHERE tenant_id = ? AND id = ?",
+                             (self.tenant_id, run_id)):
+                raise KeyError(run_id)
+            seq = int(c.execute("SELECT COALESCE(MAX(seq), 0) FROM commands WHERE run_id = ?",
+                                (run_id,))[0][0]) + 1
+            c.execute("INSERT INTO commands VALUES (?, ?, ?, ?, ?, ?, 'pending', NULL, ?, NULL)",
+                      (cid, self.tenant_id, run_id, seq, kind, json.dumps(payload), at))
+            c.execute("UPDATE runs SET worker_error = NULL WHERE tenant_id = ? AND id = ?",
+                      (self.tenant_id, run_id))
+        return CommandRow(cid, run_id, seq, kind, payload, "pending", None, at, None)
+
+    def get_command(self, run_id: str, command_id: str) -> CommandRow | None:
+        with self._db.tx() as c:
+            rows = c.execute(f"SELECT {_CMD_COLS} FROM commands "  # noqa: S608
+                             "WHERE tenant_id = ? AND run_id = ? AND id = ?",
+                             (self.tenant_id, run_id, command_id))
+        return _cmd(rows[0]) if rows else None
+
+    def pending_commands(self, run_id: str) -> list[CommandRow]:
+        with self._db.tx() as c:
+            rows = c.execute(f"SELECT {_CMD_COLS} FROM commands "  # noqa: S608
+                             "WHERE tenant_id = ? AND run_id = ? AND state = 'pending' "
+                             "ORDER BY seq", (self.tenant_id, run_id))
+        return [_cmd(r) for r in rows]
+
+    def finish_command(self, command_id: str, state: str, reason: str | None = None) -> None:
+        if state not in ("done", "refused"):
+            raise ValueError(state)
+        with self._db.tx(write=True) as c:
+            c.execute("UPDATE commands SET state = ?, reason = ?, done_at = ? "
+                      "WHERE tenant_id = ? AND id = ? AND state = 'pending'",
+                      (state, reason, now_iso(), self.tenant_id, command_id))
+
+    # ---- executor preflight -------------------------------------------------------------
+
+    def add_check(self, executor_id: str) -> CheckRow:
+        pid, at = new_id("pf"), now_iso()
+        with self._db.tx(write=True) as c:
+            if not c.execute("SELECT 1 FROM executors WHERE tenant_id = ? AND id = ?",
+                             (self.tenant_id, executor_id)):
+                raise KeyError(executor_id)
+            c.execute("INSERT INTO preflight_checks VALUES (?, ?, ?, 'pending', NULL, ?, NULL)",
+                      (pid, self.tenant_id, executor_id, at))
+        return CheckRow(pid, executor_id, "pending", None, at, None)
+
+    def get_check(self, executor_id: str, check_id: str) -> CheckRow | None:
+        with self._db.tx() as c:
+            rows = c.execute("SELECT id, executor_id, state, report, created_at, done_at "
+                             "FROM preflight_checks WHERE tenant_id = ? AND executor_id = ? "
+                             "AND id = ?", (self.tenant_id, executor_id, check_id))
+        if not rows:
+            return None
+        r = rows[0]
+        return CheckRow(r[0], r[1], r[2], json.loads(r[3]) if r[3] else None, r[4], r[5])
+
+    def check(self, check_id: str) -> CheckRow | None:
+        with self._db.tx() as c:
+            rows = c.execute("SELECT executor_id FROM preflight_checks "
+                             "WHERE tenant_id = ? AND id = ?", (self.tenant_id, check_id))
+        return self.get_check(str(rows[0][0]), check_id) if rows else None
+
+    def finish_check(self, check_id: str, report: dict[str, Any]) -> None:
+        with self._db.tx(write=True) as c:
+            c.execute("UPDATE preflight_checks SET state = 'done', report = ?, done_at = ? "
+                      "WHERE tenant_id = ? AND id = ?",
+                      (json.dumps(report), now_iso(), self.tenant_id, check_id))
+
+    # ---- credential checks (08-app.md §3, KB-029) ------------------------------------------
+
+    def add_credential_check(self, credential_id: str, request: dict[str, Any]
+                             ) -> CredentialCheckRow:
+        cid, at = new_id("cc"), now_iso()
+        with self._db.tx(write=True) as c:
+            rows = c.execute("SELECT type FROM credentials WHERE tenant_id = ? AND id = ?",
+                             (self.tenant_id, credential_id))
+            if not rows:
+                raise KeyError(credential_id)
+            kind = CHECK_KINDS.get(str(rows[0][0]))
+            if kind is None:
+                raise ValueError(f"a {rows[0][0]} credential cannot be checked")
+            c.execute("INSERT INTO credential_checks VALUES (?, ?, ?, ?, ?, 'pending', NULL, ?, "
+                      "NULL)", (cid, self.tenant_id, credential_id, kind, json.dumps(request), at))
+        return CredentialCheckRow(cid, credential_id, kind, request, "pending", None, at, None)
+
+    def get_credential_check(self, credential_id: str, check_id: str
+                             ) -> CredentialCheckRow | None:
+        with self._db.tx() as c:
+            rows = c.execute(f"SELECT {_CC_COLS} FROM credential_checks "  # noqa: S608
+                             "WHERE tenant_id = ? AND credential_id = ? AND id = ?",
+                             (self.tenant_id, credential_id, check_id))
+        return _ccheck(rows[0]) if rows else None
+
+    def credential_check(self, check_id: str) -> CredentialCheckRow | None:
+        with self._db.tx() as c:
+            rows = c.execute(f"SELECT {_CC_COLS} FROM credential_checks "  # noqa: S608
+                             "WHERE tenant_id = ? AND id = ?", (self.tenant_id, check_id))
+        return _ccheck(rows[0]) if rows else None
+
+    def latest_credential_check(self, credential_id: str) -> CredentialCheckRow | None:
+        with self._db.tx() as c:
+            rows = c.execute(f"SELECT {_CC_COLS} FROM credential_checks "  # noqa: S608
+                             "WHERE tenant_id = ? AND credential_id = ? "
+                             "ORDER BY created_at DESC, rowid DESC LIMIT 1",
+                             (self.tenant_id, credential_id))
+        return _ccheck(rows[0]) if rows else None
+
+    def finish_credential_check(self, check_id: str, report: dict[str, Any]) -> None:
+        with self._db.tx(write=True) as c:
+            c.execute("UPDATE credential_checks SET state = 'done', report = ?, done_at = ? "
+                      "WHERE tenant_id = ? AND id = ?",
+                      (json.dumps(report), now_iso(), self.tenant_id, check_id))
+
+    def latest_preflight(self, executor_id: str) -> CheckRow | None:
+        with self._db.tx() as c:
+            rows = c.execute("SELECT id FROM preflight_checks WHERE tenant_id = ? AND "
+                             "executor_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1",
+                             (self.tenant_id, executor_id))
+        return self.get_check(executor_id, str(rows[0][0])) if rows else None
+
+    # ---- the bundled PureScholar (08-app.md §5 step 12, KB-025, KB-031) ----------------------
+
+    def bundled(self) -> dict[str, Any] | None:
+        """state (pending | starting | ready | failed | stopped), reason, port, and the hash
+        and credential id of the PureScholar key it was started with."""
+        with self._db.tx() as c:
+            rows = c.execute("SELECT state, reason, port, key_sha256, key_credential_id "
+                             "FROM bundled_services WHERE tenant_id = ?", (self.tenant_id,))
+        if not rows:
+            return None
+        state, reason, port, digest, cred = rows[0]
+        return {"state": state, "reason": reason or "", "port": port, "key_sha256": digest,
+                "key_credential_id": cred}
+
+    def set_bundled(self, state: str, reason: str = "", *, port: int | None = None,
+                    key: tuple[str, str] | None = None,
+                    expect: tuple[str, ...] | None = None) -> bool:
+        """Sets the state, only if the current one is in `expect` (when given): a start never
+        overwrites a newer request or a stop made meanwhile. `port` is kept only while ready;
+        `key` (sha256, credential id) replaces the recorded key. Returns whether it was set."""
+        with self._db.tx(write=True) as c:
+            old = c.execute("SELECT state, key_sha256, key_credential_id FROM bundled_services "
+                            "WHERE tenant_id = ?", (self.tenant_id,))
+            if expect is not None and (not old or old[0][0] not in expect):
+                return False
+            digest, cred = key if key else ((old[0][1], old[0][2]) if old else (None, None))
+            c.execute("DELETE FROM bundled_services WHERE tenant_id = ?", (self.tenant_id,))
+            c.execute("INSERT INTO bundled_services VALUES (?, ?, ?, ?, ?, ?, ?)",
+                      (self.tenant_id, state, reason, port if state == "ready" else None,
+                       digest, cred, now_iso()))
+        return True
+
+    # ---- service settings (08-app.md §4, KB-025, KB-029) -------------------------------------
+
+    def service_setting(self, service: str) -> dict[str, Any] | None:
+        if service not in SERVICES:
+            raise ValueError(service)
+        with self._db.tx() as c:
+            rows = c.execute("SELECT config FROM service_settings WHERE tenant_id = ? AND "
+                             "service = ?", (self.tenant_id, service))
+        return dict(json.loads(rows[0][0])) if rows else None
+
+    def set_service_setting(self, service: str, config: dict[str, Any] | None) -> None:
+        if service not in SERVICES:
+            raise ValueError(service)
+        with self._db.tx(write=True) as c:
+            c.execute("DELETE FROM service_settings WHERE tenant_id = ? AND service = ?",
+                      (self.tenant_id, service))
+            if config is not None:
+                c.execute("INSERT INTO service_settings VALUES (?, ?, ?, ?)",
+                          (self.tenant_id, service, json.dumps(config), now_iso()))