keelrun 0.1.0__py3-none-any.whl

keel/__init__.py

@@ -0,0 +1,26 @@
+"""Keel — the Python front end (Tier 1: resilience, zero code changes).
+
+`keel run app.py` installs, before user code loads: (1) a `sys.meta_path`
+import hook that wraps functions matching `py:` policy targets, and (2)
+per-call discovery recording to `.keel/discovery.db`. The resilience
+semantics live in the backend (`keel_core` native module when importable,
+else the in-repo pure-Python `keel_core_stub`); this package is the thin,
+stdlib-only front end that drives it.
+
+DX invariants (docs/dx-spec.md §3) this package must uphold:
+  1. zero code changes in user code;
+  2. uninstall = remove the package (no lock-in): see `uninstall_keel`;
+  4. silence on success (one stderr banner at startup, then quiet);
+  5. never swallow errors — the original exception propagates unchanged,
+     with a `keel_outcome` attachment for those who look;
+  and KEEL_DISABLE=1 makes a run byte-identical to one without Keel.
+
+The public entry points are `keel.bootstrap.install_keel` /
+`uninstall_keel` and the `keel._run` runner used by `python -m keel run`.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

keel/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m keel run app.py [args...]` — the module entry point."""
+
+from __future__ import annotations
+
+from ._run import main_module
+
+main_module()

keel/_backend.py

@@ -0,0 +1,149 @@
+"""Backend selection, isolated behind one seam (architecture §5.1, "the swap").
+
+A backend exposes `configure(policy)`, `execute(request, effect)`, and
+`report()` — the four-operation core surface the stub defines (advance_clock
+is test-only and unused here). Selection:
+
+  * native (`keel_core`) — the eventual PyO3 module (Task 6/14); probed by
+    import and required to expose `configure`/`execute`. It may not exist
+    yet, so a failed import is normal.
+  * stub (`keel_core_stub.KeelCoreStub`) — the in-repo pure-Python core.
+
+`KEEL_BACKEND` overrides selection:
+  * `stub`   → force the stub, never probe native
+  * `native` → require `keel_core`; raise KEEL-E040 if not loadable
+  * `auto` / unset → native if loadable, else the stub
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from pathlib import Path
+from typing import Any, Mapping, Protocol, runtime_checkable
+
+from ._errors import KeelError
+
+
+@runtime_checkable
+class Backend(Protocol):
+    def configure(self, policy: dict[str, Any]) -> None: ...
+
+    def execute(self, request: dict[str, Any], effect: Any) -> dict[str, Any]: ...
+
+    def report(self) -> dict[str, Any]: ...
+
+
+class _NativeBackend:
+    """Front-end adapter over the native ``keel_core`` core, adding one thing the
+    PyO3 surface does not expose: ``layer(target, key)``, resolved from the
+    configured policy exactly as the stub's ``_layer`` / Node's
+    ``NativeBackend.layer`` do. The adapter packs read ``backend.layer`` to honor
+    ``idempotency.header`` and gate cache-body buffering; without this the knob is
+    dead under native (a Python/Node parity break). Every other attribute
+    (``execute``/``execute_async``/``report``/``persistent``/the flow surface)
+    delegates straight through, so the swap is transparent."""
+
+    def __init__(self, core: Any) -> None:
+        self._core = core
+        self._policy: dict[str, Any] = {}
+
+    def configure(self, policy: dict[str, Any]) -> None:
+        self._policy = policy if isinstance(policy, dict) else {}
+        self._core.configure(policy)
+
+    def layer(self, target: str, key: str) -> Any:
+        t = self._policy.get("target")
+        if isinstance(t, dict) and isinstance(t.get(target), dict) and key in t[target]:
+            return t[target][key]
+        defaults = self._policy.get("defaults")
+        if not isinstance(defaults, dict):
+            return None
+        if target.startswith("llm:"):
+            llm = defaults.get("llm")
+            if isinstance(llm, dict) and key in llm:
+                return llm[key]
+        outbound = defaults.get("outbound")
+        return outbound.get(key) if isinstance(outbound, dict) else None
+
+    def __getattr__(self, name: str) -> Any:
+        # Delegate everything else to the native core (execute, execute_async,
+        # report, persistent, enter_flow/exit_flow/journal_*, advance_clock, …).
+        return getattr(self._core, name)
+
+
+def _journal_path(cwd: str | Path | None, env: Mapping[str, str]) -> str | None:
+    """Where the native core attaches its journal (persistent dev cache + Tier 2).
+    `KEEL_JOURNAL` overrides the path; an explicit empty value disables it. This
+    is the *construction-time* default: keel.toml's `journal` key replaces it at
+    configure time unless KEEL_JOURNAL is set, in which case the env wins
+    (see ``bootstrap.apply_journal_env_override``)."""
+    override = env.get("KEEL_JOURNAL")
+    if override is not None:
+        return override or None  # empty string ⇒ no journal
+    base = Path(cwd) if cwd is not None else Path.cwd()
+    return str(base / ".keel" / "journal.db")
+
+
+def _try_load_native(journal_path: str | None) -> Backend | None:
+    try:
+        mod = importlib.import_module("keel_core")
+    except ImportError:
+        return None
+    ctor = getattr(mod, "KeelCore", None) or getattr(mod, "Core", None)
+    if ctor is None:
+        return None
+    inst = None
+    if journal_path:
+        try:
+            inst = ctor(journal_path=journal_path)  # attaches the persistent journal
+        except Exception:
+            inst = None  # journal open failed — fall back to an in-memory native core
+    if inst is None:
+        inst = ctor()
+    if callable(getattr(inst, "configure", None)) and callable(getattr(inst, "execute", None)):
+        # The native KeelCore exposes configure/execute/execute_async/report/
+        # persistent; wrap it only to add `layer(target, key)` (idempotency.header
+        # + cache-ttl gate parity), delegating everything else.
+        return _NativeBackend(inst)  # type: ignore[return-value]
+    return None
+
+
+def load_backend(
+    preferred: str | None = None,
+    *,
+    cwd: str | Path | None = None,
+    env: Mapping[str, str] | None = None,
+) -> Backend:
+    """Resolve the runtime backend per `KEEL_BACKEND` (or `preferred`). Under a
+    native backend, a journal is attached at `<cwd>/.keel/journal.db` (created on
+    demand) so the dev cache's `scope=persistent` replays across runs."""
+    environ = env if env is not None else os.environ
+    choice = (preferred if preferred is not None else environ.get("KEEL_BACKEND", "auto")) or "auto"
+    if choice not in ("auto", "native", "stub"):
+        # A user env-var mistake, not a Keel bug — E001 (config-level), not E040.
+        raise KeelError(
+            "KEEL-E001",
+            f"KEEL_BACKEND must be one of auto, native, or stub (got {choice!r}); "
+            "unset it or correct the value",
+        )
+
+    if choice != "stub":
+        native = _try_load_native(_journal_path(cwd, environ))
+        if native is not None:
+            return native
+        if choice == "native":
+            # A missing build/install is a user-environment problem, not a Keel
+            # bug, and not a malformed policy: the configuration is valid, the
+            # capability is absent — E005 (unsupported-configuration) with a
+            # concrete next step, never E040 ("file an issue").
+            raise KeelError(
+                "KEEL-E005",
+                "KEEL_BACKEND=native requires the keel_core native module, which is not "
+                "installed; build it (`maturin develop -m crates/keel-py/Cargo.toml`) or "
+                "unset KEEL_BACKEND to use the pure-Python stub",
+            )
+
+    from keel_core_stub import KeelCoreStub
+
+    return KeelCoreStub()

keel/_defaults.py

@@ -0,0 +1,116 @@
+"""Level 0 embedded smart-defaults pack (DX spec §1) + the policy-merge helper.
+
+The policy applied when no keel.toml is present. It MIRRORS
+contracts/defaults.toml verbatim (that file is the frozen source of truth);
+we embed rather than read it so the installed package is self-contained
+(stdlib-only, works offline). Drift against the contract is caught by the
+parity test, which parses contracts/defaults.toml with `tomllib` and asserts
+deep equality when the repo file is present.
+
+`apply_pack_defaults` layers these defaults (and any provider-pack fragments)
+UNDER the user's keel.toml — the Python twin of `applyPackDefaults` in
+node/keel/src/defaults.mjs; with no pack fragments it is identical to the Node
+twin, and both front ends must agree (merge parity is a cross-language
+contract).
+
+The Level 0 hard rules — never change success-path semantics; never retry
+non-idempotent calls; do nothing if a call can't be wrapped safely — are
+BEHAVIOR, not config, and are enforced in the front end / backend, not here.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any, Iterable
+
+
+def outbound_defaults() -> dict[str, Any]:
+    """`[defaults.outbound]` — any intercepted network call."""
+    return {
+        "timeout": "30s",
+        "retry": {
+            "attempts": 3,
+            "schedule": "exp(200ms, x2, max 30s, jitter)",
+            "on": ["conn", "timeout", "429", "5xx"],
+        },
+        "breaker": {"failures": 5, "cooldown": "15s"},
+    }
+
+
+def llm_defaults() -> dict[str, Any]:
+    """`[defaults.llm]` — any `llm:*` target; the generic LLM pack layer.
+
+    Retry-After-aware retry (retry on conn/timeout/429/5xx; the core waits
+    `max(schedule_wait, retry_after)`) plus the dev-loop response cache
+    (`cache = { mode = "dev" }`, resolved to a concrete ttl off-prod and
+    dropped in prod by `keel.packs.llm.resolve_dev_cache`).
+    """
+    return {
+        "timeout": "120s",
+        "retry": {
+            "attempts": 6,
+            "schedule": "exp(500ms, x2, max 60s, jitter)",
+            "on": ["conn", "timeout", "429", "5xx"],
+        },
+        "breaker": {"failures": 5, "cooldown": "30s"},
+        "cache": {"mode": "dev"},
+    }
+
+
+def level0_defaults() -> dict[str, Any]:
+    """The embedded Level 0 policy, as the dict the backend's `configure`
+    expects (identical shape to keel.toml parsed to JSON)."""
+    return {"defaults": {"outbound": outbound_defaults(), "llm": llm_defaults()}}
+
+
+def _table(v: Any) -> dict[str, Any]:
+    return v if isinstance(v, dict) else {}
+
+
+def apply_pack_defaults(
+    policy: dict[str, Any],
+    pack_fragments: Iterable[dict[str, Any]] = (),
+) -> dict[str, Any]:
+    """Merge Level 0 defaults, then provider-pack fragments, then the user
+    policy — precedence ``defaults < packs < user`` — filling in any
+    ``defaults.outbound`` / ``defaults.llm`` key a higher layer did not set,
+    while a higher layer replaces a key it DOES set wholesale (the
+    per-layer-wholesale semantics of the defaults.toml header, matching the
+    engine's own per-key layer resolution).
+
+    Target tables are left untouched — the engine resolves target →
+    defaults.llm → defaults.outbound precedence per key at execute time.
+
+    Provider packs (``keel.packs.openai_pack`` / ``anthropic_pack``) currently
+    emit the generic ``[defaults.llm]`` layer, so folding their fragments is the
+    identity over the embedded defaults; the parameter is the seam by which a
+    future per-provider refinement would take effect.
+
+    Returns a NEW policy; the input is never mutated. Idempotent on
+    ``level0_defaults()``. Mirrors Node's ``applyPackDefaults`` (empty
+    ``pack_fragments`` → identical result).
+    """
+    out = deepcopy(policy) if isinstance(policy, dict) else {}
+    user_defaults = _table(out.get("defaults"))
+
+    pack_outbound: dict[str, Any] = {}
+    pack_llm: dict[str, Any] = {}
+    for frag in pack_fragments:
+        frag_defaults = _table(frag.get("defaults")) if isinstance(frag, dict) else {}
+        pack_outbound.update(_table(frag_defaults.get("outbound")))
+        pack_llm.update(_table(frag_defaults.get("llm")))
+
+    out["defaults"] = {
+        **user_defaults,
+        "outbound": {
+            **outbound_defaults(),
+            **pack_outbound,
+            **_table(user_defaults.get("outbound")),
+        },
+        "llm": {
+            **llm_defaults(),
+            **pack_llm,
+            **_table(user_defaults.get("llm")),
+        },
+    }
+    return out

keel/_discovery.py

@@ -0,0 +1,368 @@
+"""The discovery store: per-target traffic aggregates in `.keel/discovery.db`.
+
+This is the third evidence source behind `keel init`/`status`/`doctor` (DX
+spec §2). Its schema matches the canonical one owned by the keel-journal
+crate (Task 1) column-for-column, so a `.keel/discovery.db` written by the
+Python front end is readable by the same tools as one written by the core:
+
+    CREATE TABLE discovery (
+        target            TEXT PRIMARY KEY,
+        calls             INTEGER NOT NULL DEFAULT 0,  -- intercepted calls
+        attempts          INTEGER NOT NULL DEFAULT 0,  -- upstream attempts (Σ)
+        retries           INTEGER NOT NULL DEFAULT 0,  -- attempts beyond the 1st
+        successes         INTEGER NOT NULL DEFAULT 0,
+        failures          INTEGER NOT NULL DEFAULT 0,
+        cache_hits        INTEGER NOT NULL DEFAULT 0,
+        throttled         INTEGER NOT NULL DEFAULT 0,
+        breaker_opens     INTEGER NOT NULL DEFAULT 0,
+        total_latency_ms  INTEGER NOT NULL DEFAULT 0,
+        max_latency_ms    INTEGER NOT NULL DEFAULT 0,
+        first_seen_ms     INTEGER NOT NULL,
+        last_seen_ms      INTEGER NOT NULL,
+        last_error_class  TEXT,
+        last_error_status INTEGER,
+        not_retried       INTEGER NOT NULL DEFAULT 0,  -- KEEL-E014: observed, not retried
+        unwrapped_calls   INTEGER NOT NULL DEFAULT 0   -- calls with no [target] policy entry
+    ) WITHOUT ROWID;
+
+    CREATE TABLE discovery_daily (                     -- rolling daily buckets
+        target          TEXT NOT NULL,                 -- (kept RETENTION_DAYS days)
+        day             INTEGER NOT NULL,               -- UTC day index: ms / 86_400_000
+        calls           INTEGER NOT NULL DEFAULT 0,
+        attempts        INTEGER NOT NULL DEFAULT 0,
+        retries         INTEGER NOT NULL DEFAULT 0,
+        successes       INTEGER NOT NULL DEFAULT 0,
+        failures        INTEGER NOT NULL DEFAULT 0,
+        cache_hits      INTEGER NOT NULL DEFAULT 0,
+        throttled       INTEGER NOT NULL DEFAULT 0,
+        breaker_opens   INTEGER NOT NULL DEFAULT 0,
+        not_retried     INTEGER NOT NULL DEFAULT 0,
+        unwrapped_calls INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (target, day)
+    ) WITHOUT ROWID;
+
+Accounting mirrors the crate: a cache hit is a `call` and a `cache_hit` only
+(no upstream attempt), so `calls == successes + failures + cache_hits`.
+`breaker_opens` counts calls that FAILED FAST on an open breaker — outcomes with
+error code `KEEL-E012` — matching the Rust core (`error.code == BreakerOpen`,
+crates/keel-journal/src/discovery.rs) and the Node twin, NOT every outcome whose
+`breaker` field reads "open" (that field is also stamped on the terminal failure
+that trips the breaker and on a cache hit served while open). `not_retried`
+counts calls that resolved KEEL-E014 (failed, and Keel refused to retry because
+the call is not idempotent — the DX Level 0 hard rule's "observed, not
+retried"). `unwrapped_calls` counts calls whose target had no explicit
+`[target."…"]` entry in the EFFECTIVE policy handed to `backend.configure()`
+(the same policy the core layers no pack underneath, per the CCR) — the honest
+coverage gap `keel status` reports; `Discovery` is told the set of explicit
+target keys once, at construction, by `bootstrap.install_keel`. Every mutation
+is a single UPSERT per table, so two processes recording into one file
+accumulate correctly without a transaction (WAL, `busy_timeout`).
+
+Migration: a file written by the previous (v1, `user_version = 0`) schema is
+upgraded in place on first open — the two counter columns are appended
+(`ALTER TABLE … ADD COLUMN`, so column order matches a fresh v2 file), the
+daily table is created, and `user_version` is stamped to 2. Mirrors
+`crates/keel-journal/src/discovery.rs::migrate` exactly, so either writer can
+open a file the other created.
+
+Discovery is best-effort: it must never throw into, slow, or add output to
+the user's program (DX invariant 4). Every public method swallows its own
+errors and returns quietly.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+from pathlib import Path
+from time import time as _wall_clock  # captured at import: immune to in-flow
+from typing import Any  # time virtualization (keel's own clock is never journaled)
+
+#: Current discovery schema version, stamped in `PRAGMA user_version`.
+#: Mirrors `keel_journal::discovery::DISCOVERY_SCHEMA_VERSION`.
+SCHEMA_VERSION = 2
+
+#: How many trailing UTC days of `discovery_daily` buckets are kept. Mirrors
+#: `keel_journal::discovery::RETENTION_DAYS`.
+RETENTION_DAYS = 30
+
+#: Milliseconds per UTC day; `day = now_ms // MS_PER_DAY` is the bucket key.
+MS_PER_DAY = 86_400_000
+
+_DISCOVERY_SCHEMA = """\
+CREATE TABLE IF NOT EXISTS discovery (
+    target            TEXT PRIMARY KEY,
+    calls             INTEGER NOT NULL DEFAULT 0,
+    attempts          INTEGER NOT NULL DEFAULT 0,
+    retries           INTEGER NOT NULL DEFAULT 0,
+    successes         INTEGER NOT NULL DEFAULT 0,
+    failures          INTEGER NOT NULL DEFAULT 0,
+    cache_hits        INTEGER NOT NULL DEFAULT 0,
+    throttled         INTEGER NOT NULL DEFAULT 0,
+    breaker_opens     INTEGER NOT NULL DEFAULT 0,
+    total_latency_ms  INTEGER NOT NULL DEFAULT 0,
+    max_latency_ms    INTEGER NOT NULL DEFAULT 0,
+    first_seen_ms     INTEGER NOT NULL,
+    last_seen_ms      INTEGER NOT NULL,
+    last_error_class  TEXT,
+    last_error_status INTEGER,
+    not_retried       INTEGER NOT NULL DEFAULT 0,
+    unwrapped_calls   INTEGER NOT NULL DEFAULT 0
+) WITHOUT ROWID;"""
+
+_DAILY_SCHEMA = """\
+CREATE TABLE IF NOT EXISTS discovery_daily (
+    target          TEXT NOT NULL,
+    day             INTEGER NOT NULL,
+    calls           INTEGER NOT NULL DEFAULT 0,
+    attempts        INTEGER NOT NULL DEFAULT 0,
+    retries         INTEGER NOT NULL DEFAULT 0,
+    successes       INTEGER NOT NULL DEFAULT 0,
+    failures        INTEGER NOT NULL DEFAULT 0,
+    cache_hits      INTEGER NOT NULL DEFAULT 0,
+    throttled       INTEGER NOT NULL DEFAULT 0,
+    breaker_opens   INTEGER NOT NULL DEFAULT 0,
+    not_retried     INTEGER NOT NULL DEFAULT 0,
+    unwrapped_calls INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (target, day)
+) WITHOUT ROWID;"""
+
+# `?` (qmark) placeholders in the same column order as the crate's numbered
+# statement; the ON CONFLICT body is identical (counters add, extremes keep,
+# first_seen shrinks / last_seen grows, error columns move together).
+_UPSERT = """\
+INSERT INTO discovery
+    (target, calls, attempts, retries, successes, failures, cache_hits,
+     throttled, breaker_opens, total_latency_ms, max_latency_ms,
+     first_seen_ms, last_seen_ms, last_error_class, last_error_status,
+     not_retried, unwrapped_calls)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(target) DO UPDATE SET
+    calls            = calls + excluded.calls,
+    attempts         = attempts + excluded.attempts,
+    retries          = retries + excluded.retries,
+    successes        = successes + excluded.successes,
+    failures         = failures + excluded.failures,
+    cache_hits       = cache_hits + excluded.cache_hits,
+    throttled        = throttled + excluded.throttled,
+    breaker_opens    = breaker_opens + excluded.breaker_opens,
+    total_latency_ms = total_latency_ms + excluded.total_latency_ms,
+    max_latency_ms   = max(max_latency_ms, excluded.max_latency_ms),
+    first_seen_ms    = min(first_seen_ms, excluded.first_seen_ms),
+    last_seen_ms     = max(last_seen_ms, excluded.last_seen_ms),
+    last_error_class = coalesce(excluded.last_error_class, last_error_class),
+    last_error_status = CASE
+        WHEN excluded.last_error_class IS NOT NULL THEN excluded.last_error_status
+        ELSE last_error_status END,
+    not_retried      = not_retried + excluded.not_retried,
+    unwrapped_calls  = unwrapped_calls + excluded.unwrapped_calls"""
+
+_DAILY_UPSERT = """\
+INSERT INTO discovery_daily
+    (target, day, calls, attempts, retries, successes, failures, cache_hits,
+     throttled, breaker_opens, not_retried, unwrapped_calls)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(target, day) DO UPDATE SET
+    calls           = calls + excluded.calls,
+    attempts        = attempts + excluded.attempts,
+    retries         = retries + excluded.retries,
+    successes       = successes + excluded.successes,
+    failures        = failures + excluded.failures,
+    cache_hits      = cache_hits + excluded.cache_hits,
+    throttled       = throttled + excluded.throttled,
+    breaker_opens   = breaker_opens + excluded.breaker_opens,
+    not_retried     = not_retried + excluded.not_retried,
+    unwrapped_calls = unwrapped_calls + excluded.unwrapped_calls"""
+
+
+class Discovery:
+    """A per-target traffic ledger over its own WAL-mode SQLite file. One
+    connection per process (shared across threads under a lock, matching the
+    crate's `Mutex<Connection>`); one UPSERT per table per recorded call.
+
+    `known_targets` is the set of EXPLICIT `[target."…"]` keys in the
+    effective policy (defaults < packs < user, before `backend.configure()`)
+    — used to classify each recorded call as wrapped (an explicit entry
+    applied) or not (the coverage gap `keel status` reports). Passing none
+    (the default) means every call is counted unwrapped, which is correct for
+    a store opened outside `bootstrap.install_keel` (e.g. read-only tooling
+    that never records)."""
+
+    def __init__(
+        self,
+        cwd: str | Path | None = None,
+        known_targets: frozenset[str] | None = None,
+    ) -> None:
+        self.db_path = Path(cwd or Path.cwd()) / ".keel" / "discovery.db"
+        self._known_targets = known_targets or frozenset()
+        self._lock = threading.Lock()
+        self._conn: sqlite3.Connection | None = None
+        self._last_prune_day: int | None = None
+
+    def _connect(self) -> sqlite3.Connection | None:
+        """Open (once) the connection, lazily so a disabled/never-recording
+        run never touches the filesystem. Returns None if the store can't be
+        opened (permissions, fs) — recording then no-ops."""
+        if self._conn is not None:
+            return self._conn
+        try:
+            self.db_path.parent.mkdir(parents=True, exist_ok=True)
+            conn = sqlite3.connect(self.db_path, check_same_thread=False)
+            conn.execute("PRAGMA journal_mode = WAL;")
+            conn.execute("PRAGMA busy_timeout = 5000;")
+            conn.execute("PRAGMA synchronous = NORMAL;")
+            _migrate(conn)
+        except sqlite3.Error:
+            return None
+        self._conn = conn
+        return conn
+
+    def record(self, target: str, outcome: dict[str, Any], latency_ms: int) -> None:
+        """Fold one intercepted call's outcome envelope into its target's
+        aggregates (lifetime row plus the clock-day bucket). Best-effort:
+        never raises."""
+        wrapped = target in self._known_targets
+        row = _row_from_outcome(target, outcome, latency_ms, wrapped)
+        now_ms = row[12]  # last_seen_ms, per _row_from_outcome's column order
+        day = now_ms // MS_PER_DAY
+        try:
+            with self._lock:
+                conn = self._connect()
+                if conn is None:
+                    return
+                conn.execute(_UPSERT, row)
+                conn.execute(_DAILY_UPSERT, _daily_row(row, day))
+                self._prune(conn, day)
+                conn.commit()
+        except sqlite3.Error:
+            pass  # best-effort: discovery never breaks the user's program
+
+    def _prune(self, conn: sqlite3.Connection, day: int) -> None:
+        """Drop daily buckets older than the retention window, at most once
+        per advanced day (mirrors the crate's `DiscoveryStore::prune`)."""
+        if self._last_prune_day == day:
+            return
+        self._last_prune_day = day
+        conn.execute(
+            "DELETE FROM discovery_daily WHERE day < ?",
+            (day - (RETENTION_DAYS - 1),),
+        )
+
+    def close(self) -> None:
+        with self._lock:
+            if self._conn is not None:
+                try:
+                    self._conn.close()
+                finally:
+                    self._conn = None
+
+
+def _migrate(conn: sqlite3.Connection) -> None:
+    """Bring a connection to [`SCHEMA_VERSION`]: create the current schema on
+    a fresh file, or append the v2 counter columns and the daily table to a
+    legacy (v1) one. Mirrors `keel_journal::discovery::migrate` — idempotent,
+    so re-opening an already-migrated file is a no-op."""
+    (version,) = conn.execute("PRAGMA user_version").fetchone()
+    if version >= SCHEMA_VERSION:
+        return
+    has_table = conn.execute(
+        "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'discovery')"
+    ).fetchone()[0]
+    if has_table:
+        has_column = conn.execute(
+            "SELECT EXISTS(SELECT 1 FROM pragma_table_info('discovery') "
+            "WHERE name = 'not_retried')"
+        ).fetchone()[0]
+        if not has_column:
+            # Appended, so a migrated file's column order matches a fresh v2 one.
+            conn.execute(
+                "ALTER TABLE discovery ADD COLUMN not_retried INTEGER NOT NULL DEFAULT 0"
+            )
+            conn.execute(
+                "ALTER TABLE discovery ADD COLUMN unwrapped_calls INTEGER NOT NULL DEFAULT 0"
+            )
+    else:
+        conn.executescript(_DISCOVERY_SCHEMA)
+    conn.executescript(_DAILY_SCHEMA)
+    conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+    conn.commit()
+
+
+def _row_from_outcome(
+    target: str, outcome: dict[str, Any], latency_ms: int, wrapped: bool = True
+) -> tuple[Any, ...]:
+    """Project a core outcome envelope onto one `discovery` row's 17 values."""
+    result = outcome.get("result")
+    from_cache = bool(outcome.get("from_cache"))
+    attempts = int(outcome.get("attempts", 0) or 0)
+
+    cache_hit = result == "ok" and from_cache
+    success = result == "ok" and not from_cache
+    failure = result != "ok"
+
+    err = outcome.get("error") or {}
+    last_error_class = err.get("class") if failure else None
+    last_error_status = err.get("http_status") if failure else None
+
+    now = int(_wall_clock() * 1000)
+    return (
+        target,
+        1,  # calls
+        attempts,
+        attempts - 1 if attempts > 0 else 0,  # retries
+        1 if success else 0,
+        1 if failure else 0,
+        1 if cache_hit else 0,
+        1 if outcome.get("throttled") else 0,
+        # breaker_opens = fail-fast rejections only (KEEL-E012), the canonical
+        # rule shared with the Rust core and Node — NOT any breaker=="open" stamp.
+        1 if err.get("code") == "KEEL-E012" else 0,
+        latency_ms,  # total_latency_ms
+        latency_ms,  # max_latency_ms
+        now,  # first_seen_ms
+        now,  # last_seen_ms
+        last_error_class,
+        last_error_status,
+        # not_retried = KEEL-E014: observed, not retried (Level 0 hard rule).
+        1 if err.get("code") == "KEEL-E014" else 0,
+        0 if wrapped else 1,  # unwrapped_calls
+    )
+
+
+def _daily_row(row: tuple[Any, ...], day: int) -> tuple[Any, ...]:
+    """Project a `discovery` row (see [`_row_from_outcome`]) onto its
+    `discovery_daily` twin: same target and counters, keyed by `day` instead
+    of the seen-timestamps and error columns the daily table omits."""
+    (
+        target,
+        calls,
+        attempts,
+        retries,
+        successes,
+        failures,
+        cache_hits,
+        throttled,
+        breaker_opens,
+        _total_latency_ms,
+        _max_latency_ms,
+        _first_seen_ms,
+        _last_seen_ms,
+        _last_error_class,
+        _last_error_status,
+        not_retried,
+        unwrapped_calls,
+    ) = row
+    return (
+        target,
+        day,
+        calls,
+        attempts,
+        retries,
+        successes,
+        failures,
+        cache_hits,
+        throttled,
+        breaker_opens,
+        not_retried,
+        unwrapped_calls,
+    )