adopt-store 0.3.0__py3-none-any.whl

adopt_store/__init__.py

@@ -0,0 +1,60 @@
+"""SQLite realization, facades, transactions, the VectorIndex seam.
+
+Implementation spec §4.7. Invariants enforced here and by CI rather than by
+review:
+
+* **`sqlite3` is imported in `adopt_store.sqlite` and nowhere else**
+  (`no-raw-sqlite`), so no caller above the store can hold a connection.
+* **No facade returns a connection, cursor or raw SQL** (contracts §10.3).
+* **No destructive statement exists anywhere in the package** -- no `DROP`, no
+  `ALTER ... DROP`, no unpredicated `DELETE` -- checked by
+  `scripts/no_destructive_sql.py`.
+* **Ids are generated inside the facade and scope is injected by it**; neither
+  is accepted from a caller.
+* **`append_revision` is the only mutation on a revision family**, and no update
+  or delete method exists on any facade for a `*_revision` table
+  (`no-revision-update`, in both repositories).
+
+The coverage facade and the remaining contracts §10.3 accessors arrive with the
+tables they front, in S4 and later.
+"""
+
+from adopt_store.api import OpenRestriction, Store, open_store, scope_facade, writer_identity
+from adopt_store.doctor import Finding, doctor
+from adopt_store.facades import (
+    BindingFacade,
+    IdentityFacade,
+    KnowledgeFacade,
+    ProbeFacade,
+)
+from adopt_store.revisions import (
+    BindingRevisionDraft,
+    IdentityRevisionDraft,
+    KnowledgeRevisionDraft,
+    ProbeDefinitionRevisionDraft,
+    RevisionWriter,
+    UnknownFamilyError,
+)
+from adopt_store.vector.api import VECTOR_FEATURE_FLAG, VectorIndex
+
+__all__ = [
+    "VECTOR_FEATURE_FLAG",
+    "BindingFacade",
+    "BindingRevisionDraft",
+    "Finding",
+    "IdentityFacade",
+    "IdentityRevisionDraft",
+    "KnowledgeFacade",
+    "KnowledgeRevisionDraft",
+    "OpenRestriction",
+    "ProbeDefinitionRevisionDraft",
+    "ProbeFacade",
+    "RevisionWriter",
+    "Store",
+    "UnknownFamilyError",
+    "VectorIndex",
+    "doctor",
+    "open_store",
+    "scope_facade",
+    "writer_identity",
+]

adopt_store/annex/__init__.py

@@ -0,0 +1,25 @@
+"""The runtime annex realization: contracts §12, CR-08, CR-45.
+
+**Why this lives in `adopt-store` and not in `adopt-agent`.** `no-raw-sqlite`
+names `adopt_agent` a source module and follows indirect chains, so the seam
+cannot reach a driver even through a helper. `adopt-store` is the package the
+contract permits to hold a dialect, so the annex realization is here and
+`adopt_agent.AnnexRecords` is what the seam actually talks to -- the CR-34
+pattern, realized **structurally**: nothing in this module imports the protocol,
+and `test_annex.py` asserts the shapes still match.
+
+**This is a second store, not a second schema authority.** `open_annex` opens
+`.adopt/runtime.db`, applies `schema/annex/0001__agent_run.sql`, and never
+touches `PRAGMA user_version` -- the annex is outside `schema_version` by
+ratification (CR-08), and stamping it with a version number is precisely the
+confusion that would invite someone to migrate the two together.
+
+**It is never reachable from the export.** `adopt_export` iterates
+`Manifest.exportable_tables()` and `agent_run` is not in the manifest at all, so
+exclusion is by construction rather than by a filter someone could forget --
+which is the same argument S5 recorded for the annex in the first place.
+"""
+
+from adopt_store.annex.sqlite_annex import SqliteAnnexRecords, annex_path, open_annex
+
+__all__ = ["SqliteAnnexRecords", "annex_path", "open_annex"]

adopt_store/annex/sqlite_annex.py

@@ -0,0 +1,146 @@
+"""SQLite realization of the runtime annex. Contracts §12.
+
+The DDL is **read from `schema/annex/0001__agent_run.sql`**, not embedded as a
+string literal. Two reasons, and the second is the one that matters: a literal
+would put a `CREATE TABLE` inside `packages/`, which `no-foreign-tables` forbids
+and which CR-45 declined to route around; and a reader looking for "what is in
+the annex" should find one answer, in a file that says so, rather than a Python
+string that happens to be the truth today.
+"""
+
+import sqlite3
+from collections.abc import Iterator
+from contextlib import closing, contextmanager
+from pathlib import Path
+from typing import Final
+
+from adopt_agent.annex import AgentRunRecord
+from adopt_const import STORE_BUSY_TIMEOUT_MS
+from adopt_schema.assets import assets_root
+
+__all__ = ["SqliteAnnexRecords", "annex_path", "open_annex"]
+
+#: Contracts §12: `.adopt/runtime.db` locally. Resolved beside the canonical
+#: store so the two travel together -- an annex beside a *different* store is an
+#: idempotency table answering for runs that were never made against it.
+_ANNEX_FILENAME: Final[str] = "runtime.db"
+
+#: This module used to carry its own `parents[5]` walk to the checkout, and its
+#: comment cited `adopt_schema.manifest` and `adopt_store.api` doing the same --
+#: three copies of one assumption that held only in a checkout (CR-53). All three
+#: now resolve through `adopt_schema.assets`, which is also why this is looked up
+#: per call rather than at import: the answer can now fail, and a failure at
+#: import time would take down every command instead of the one that needs a
+#: store.
+
+_COLUMNS: Final[tuple[str, ...]] = (
+    "id",
+    "scope_ref",
+    "idempotency_key",
+    "skill_ref",
+    "skill_sha256",
+    "inputs_sha256",
+    "adapter",
+    "model",
+    "params_hash",
+    "status",
+    "input_tokens",
+    "output_tokens",
+    "cost_usd",
+    "wall_ms",
+    "trace_json",
+    "output_ref",
+    "created_at",
+)
+
+
+def annex_path(store_path: Path) -> Path:
+    """Where the annex lives for a given canonical store."""
+    return store_path.parent / _ANNEX_FILENAME
+
+
+@contextmanager
+def open_annex(path: Path, *, repo_root: Path | None = None) -> Iterator["SqliteAnnexRecords"]:
+    """Open (creating if absent) the annex at `path` and yield its records.
+
+    A context manager rather than a bare handle, because the annex is opened for
+    the duration of one seam call; holding it open across a process makes a
+    second writer wait on a lock for no reason, and `busy_timeout` covers the
+    case where one genuinely does.
+
+    **No `user_version` is read or written.** The annex is outside
+    `schema_version` (CR-08), and `IF NOT EXISTS` in the DDL is what makes
+    opening idempotent. A version stamp here would be the first step towards
+    someone migrating the annex alongside the canonical store, which is the
+    coupling the ratification exists to prevent.
+    """
+    root = repo_root if repo_root is not None else assets_root()
+    ddl = (root / "schema" / "annex" / "0001__agent_run.sql").read_text(encoding="utf-8")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    connection = sqlite3.connect(path, isolation_level=None)
+    try:
+        connection.row_factory = sqlite3.Row
+        connection.execute(f"PRAGMA busy_timeout = {int(STORE_BUSY_TIMEOUT_MS)};")
+        connection.executescript(ddl)
+        yield SqliteAnnexRecords(connection)
+    finally:
+        connection.close()
+
+
+class SqliteAnnexRecords:
+    """Realizes `adopt_agent.annex.AnnexRecords` structurally.
+
+    Two methods and no setter: contracts §12 records that a run happened, and
+    there is no operation for recording that it happened differently.
+    """
+
+    def __init__(self, connection: sqlite3.Connection) -> None:
+        self._connection = connection
+
+    def find_run(self, *, scope_ref: str, idempotency_key: str) -> AgentRunRecord | None:
+        """Look up by the §12 unique index, never by key alone.
+
+        Keying on the pair matters: two engagements may legitimately choose the
+        same idempotency key, and a global key space would hand one client's
+        recorded run to another client's replay.
+        """
+        columns = ", ".join(_COLUMNS)
+        with closing(
+            self._connection.execute(
+                f"SELECT {columns} FROM agent_run "  # noqa: S608 -- names are this module's
+                "WHERE scope_ref = ? AND idempotency_key = ?;",
+                (scope_ref, idempotency_key),
+            )
+        ) as cursor:
+            row = cursor.fetchone()
+        if row is None:
+            return None
+        return AgentRunRecord.model_validate({name: row[name] for name in _COLUMNS})
+
+    def record_run(self, record: AgentRunRecord) -> AgentRunRecord:
+        """Persist a completed run and return **what is stored afterwards**.
+
+        On a race the loser gets the winner's record back rather than an error,
+        and that is the correct answer rather than a lenient one: the caller
+        asked "what is the result for this key", two callers raced to record it,
+        and idempotency means they must both be told the same thing. Raising
+        would make the second caller retry a provider call that has already been
+        paid for -- the exact double-spend the annex exists to prevent.
+
+        `ON CONFLICT DO NOTHING` followed by a read is one statement and one
+        read, so the loser observes the winner's committed row. The same shape
+        the DBOS backend's `dedupe` uses (`02` §10.2, CR-43), for the same
+        reason: the marker must be claimed atomically or it claims nothing.
+        """
+        placeholders = ", ".join("?" for _ in _COLUMNS)
+        columns = ", ".join(_COLUMNS)
+        values = tuple(getattr(record, name) for name in _COLUMNS)
+        self._connection.execute(
+            f"INSERT INTO agent_run ({columns}) VALUES ({placeholders}) "  # noqa: S608
+            "ON CONFLICT(scope_ref, idempotency_key) DO NOTHING;",
+            values,
+        )
+        stored = self.find_run(scope_ref=record.scope_ref, idempotency_key=record.idempotency_key)
+        if stored is None:  # pragma: no cover -- the row was just inserted or already there
+            raise RuntimeError("agent_run vanished between insert and read")
+        return stored

adopt_store/api.py

@@ -0,0 +1,444 @@
+"""`open_store` and the `Store` seam.
+
+Implementation spec §4.7 behaviour 1 and contracts §10.3. Opening a store is
+where two guarantees are made that everything above depends on:
+
+**The version matrix, and why it opens rather than refuses.** A store newer than
+the binary opens **read-only** and reports `SCHEMA_VERSION_TOO_NEW`; an older
+store opened without `migrate` opens **read-only** and reports
+`SCHEMA_MIGRATION_PENDING`. Neither raises, because §7.4 names exactly one
+recovery for a bad schema deploy — *older code against the newer store* — and a
+binary that refuses to open the store it was rolled back to have has removed the
+only rollback surface the schema has. The condition travels on
+`Store.restriction`, and any *write* then raises `STORE_READ_ONLY`.
+
+**`schema_meta` is read and written on every open** (contracts §14, CR-04),
+appended and never updated, which is what turns the table into the migration log
+CR-04 describes. A read-only open reads it and cannot append — that is a
+property of the file being read-only, not a branch anyone chose, and pretending
+otherwise would mean a reader silently mutating a store it was asked not to
+touch.
+
+**Facades arrive with their tables.** §10.3 declares eleven accessors. `scope()`
+came with S2's tables; `identities()`, `items()`, `bindings()`, `probes()` and
+`revisions()` arrived at S3 with the identity and revision families; `sensors()`
+came with the channel whose health gates freshness; and `boundary()` arrives with
+the tier negotiation that first has something to declare. The remaining three --
+`changes()`, `governance()` and `value()` -- land in the sprints that write the
+tables they front. An accessor that raises is not a seam, it is a placeholder
+wearing one.
+
+**Two ports are exposed that §10.3 does not declare**, and deliberately so:
+`coverage_records()` and `freshness_records()` are the storage halves of
+`adopt_coverage` and `adopt_freshness`, which declare their own protocols and
+import nothing from here. They are not facades and are not on the `Store` seam --
+a caller reaching for coverage calls `recompute_coverage`, not a records object.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from importlib import metadata
+from pathlib import Path
+from typing import TYPE_CHECKING, Final, Protocol, cast
+
+from adopt_const import (
+    EXPORT_VERSION,
+    MAX_SUPPORTED_SCHEMA_VERSION,
+    MIN_SUPPORTED_SCHEMA_VERSION,
+    SCHEMA_VERSION,
+)
+from adopt_obs import AdoptError, Clock, ErrorCode
+from adopt_schema.assets import assets_root
+from adopt_schema.migrate import apply as apply_migrations
+from adopt_scope import ScopeFacade
+from adopt_store.facades.boundary import BoundaryFacade
+from adopt_store.facades.identity import IdentityFacade
+from adopt_store.facades.knowledge import BindingFacade, KnowledgeFacade, ProbeFacade
+from adopt_store.facades.records import RevisionRecords
+from adopt_store.facades.sensors import SensorFacade
+from adopt_store.revisions import RevisionWriter
+from adopt_store.sqlite.records import (
+    SqliteBindingRecords,
+    SqliteBoundaryRecords,
+    SqliteCoverageRecords,
+    SqliteExportRecords,
+    SqliteFreshnessRecords,
+    SqliteIdentityRecords,
+    SqliteImportRecords,
+    SqliteKnowledgeRecords,
+    SqliteProbeRecords,
+    SqliteRevisionRecords,
+    SqliteScopeRecords,
+    SqliteSensorRecords,
+)
+from adopt_store.sqlite.store import SqliteStore
+
+__all__ = ["OpenRestriction", "Store", "open_store", "scope_facade", "writer_identity"]
+
+if TYPE_CHECKING:  # pragma: no cover -- import cycle: doctor reads this module
+    from adopt_store.doctor import Finding
+
+_DISTRIBUTION: Final[str] = "adopt-store"
+
+#: The tables `adopt store info` reports on, in a fixed order so two runs over
+#: one store produce one report.
+COUNTED_TABLES: Final[tuple[str, ...]] = (
+    "firm",
+    "engagement",
+    "system",
+    "environment",
+    "identity",
+    "identity_revision",
+    "knowledge_item",
+    "knowledge_revision",
+    "binding",
+    "binding_revision",
+    "probe_definition",
+    "probe_definition_revision",
+    "sensor",
+    "observability_boundary",
+)
+_SQLITE_DIALECT: Final[str] = "sqlite"
+
+
+def scope_facade(store: SqliteStore, *, clock: Clock | None = None) -> ScopeFacade:
+    """Bind the scope facade to a SQLite store.
+
+    The assembly lives here rather than in `adopt_store.facades` because that
+    package may not reach the driver even transitively (`no-raw-sqlite`), and
+    binding a facade to a realization is exactly such a reach. The facade
+    generates every id and accepts none, so there is no argument through which a
+    caller could supply one (contracts §10.3).
+    """
+    return ScopeFacade(SqliteScopeRecords(store), clock=clock)
+
+
+def writer_identity() -> str:
+    """What lands in `schema_meta.written_by`, e.g. ``adopt-core/0.3.0``.
+
+    Honest stamping: a development checkout that cannot resolve its own version
+    says so rather than claiming a release number it does not have.
+    """
+    try:
+        version = metadata.version(_DISTRIBUTION)
+    except metadata.PackageNotFoundError:  # pragma: no cover -- source checkout only
+        version = "0.0.0+unknown"
+    return f"adopt-core/{version}"
+
+
+@dataclass(frozen=True, slots=True)
+class OpenRestriction:
+    """Why a store opened read-only, in the vocabulary of contracts §13."""
+
+    code: ErrorCode
+    reason: str
+
+
+class Store(Protocol):
+    """The store seam, **exactly** the contracts §10.3 accessors this sprint provides.
+
+    `revision_records()` is deliberately absent even though the handle has one:
+    §10.3 declares the accessors a caller gets, and the append-only port is not
+    one of them. `doctor` needs it, so `doctor` declares its own one-method
+    protocol and takes the handle structurally -- which keeps the need visible
+    without widening the seam every future caller programs against.
+    """
+
+    read_only: bool
+    restriction: OpenRestriction | None
+    schema_version: int
+
+    def scope(self) -> ScopeFacade: ...
+    def identities(self) -> IdentityFacade: ...
+    def items(self) -> KnowledgeFacade: ...
+    def bindings(self) -> BindingFacade: ...
+    def probes(self) -> ProbeFacade: ...
+    def sensors(self) -> SensorFacade: ...
+    def boundary(self) -> BoundaryFacade: ...
+    def revisions(self) -> RevisionWriter: ...
+    def close(self) -> None: ...
+
+
+@dataclass(slots=True)
+class SqliteStoreHandle:
+    """A `Store` over SQLite. Returned by `open_store`; never constructed directly.
+
+    Facades are built once and cached, because each holds a records object over
+    the one connection this handle owns. Two `RevisionWriter`s over one store
+    would be two clocks and two transaction depths, and the second is how a
+    nested transaction silently commits half of someone else's work.
+    """
+
+    backend: SqliteStore
+    read_only: bool
+    restriction: OpenRestriction | None
+    schema_version: int
+    clock: Clock | None = None
+    _facades: dict[str, object] = field(default_factory=dict)
+
+    def _cached[TFacade](self, name: str, build: Callable[[], TFacade]) -> TFacade:
+        cached = self._facades.get(name)
+        if cached is None:
+            cached = build()
+            self._facades[name] = cached
+        return cast("TFacade", cached)
+
+    def scope(self) -> ScopeFacade:
+        return self._cached(
+            "scope", lambda: ScopeFacade(SqliteScopeRecords(self.backend), clock=self.clock)
+        )
+
+    def revision_records(self) -> RevisionRecords:
+        """The append-only port, for `doctor` and for the revision writer."""
+        return self._cached("revision_records", lambda: SqliteRevisionRecords(self.backend))
+
+    def revisions(self) -> RevisionWriter:
+        return self._cached(
+            "revisions",
+            lambda: RevisionWriter(
+                self.revision_records(),
+                SqliteKnowledgeRecords(self.backend),
+                clock=self.clock,
+            ),
+        )
+
+    def identities(self) -> IdentityFacade:
+        return self._cached(
+            "identities",
+            lambda: IdentityFacade(
+                SqliteIdentityRecords(self.backend), self.revisions(), clock=self.clock
+            ),
+        )
+
+    def items(self) -> KnowledgeFacade:
+        return self._cached(
+            "items",
+            lambda: KnowledgeFacade(SqliteKnowledgeRecords(self.backend), self.revisions()),
+        )
+
+    def bindings(self) -> BindingFacade:
+        return self._cached(
+            "bindings",
+            lambda: BindingFacade(
+                SqliteBindingRecords(self.backend), self.revisions(), clock=self.clock
+            ),
+        )
+
+    def probes(self) -> ProbeFacade:
+        return self._cached(
+            "probes",
+            lambda: ProbeFacade(
+                SqliteProbeRecords(self.backend), self.revisions(), clock=self.clock
+            ),
+        )
+
+    def sensors(self) -> SensorFacade:
+        return self._cached(
+            "sensors", lambda: SensorFacade(SqliteSensorRecords(self.backend), clock=self.clock)
+        )
+
+    def boundary(self) -> BoundaryFacade:
+        return self._cached(
+            "boundary",
+            lambda: BoundaryFacade(SqliteBoundaryRecords(self.backend), clock=self.clock),
+        )
+
+    def coverage_records(self) -> SqliteCoverageRecords:
+        """The read port `adopt_coverage.recompute_coverage` runs on."""
+        return self._cached("coverage_records", lambda: SqliteCoverageRecords(self.backend))
+
+    def freshness_records(self) -> SqliteFreshnessRecords:
+        """The read port `adopt_freshness.resolve_freshness` runs on."""
+        return self._cached("freshness_records", lambda: SqliteFreshnessRecords(self.backend))
+
+    def sensor_records(self) -> SqliteSensorRecords:
+        """The sensor port, for `doctor`'s NULL-cadence finding."""
+        return self._cached("sensor_records", lambda: SqliteSensorRecords(self.backend))
+
+    def export_records(self) -> SqliteExportRecords:
+        """The read port `adopt_export.write_bundle` runs on."""
+        return self._cached("export_records", lambda: SqliteExportRecords(self.backend))
+
+    def import_records(self) -> SqliteImportRecords:
+        """The write port `adopt_export.apply_bundle` runs on."""
+        return self._cached("import_records", lambda: SqliteImportRecords(self.backend))
+
+    def transaction(self) -> object:
+        """The shared transaction boundary (contracts §10.3)."""
+        return self.backend.transaction()
+
+    def counts(self) -> dict[str, int]:
+        """Row counts for the tables Build 0 writes -- `adopt store info`'s payload.
+
+        Here rather than in the CLI because it is SQL, and CR-36's whole argument
+        for exempting one wiring module is that the CLI holds **no** dialect
+        knowledge. A second realization answers the same question its own way.
+
+        Deliberately not all 37 tables: a count of zero for a table no code
+        populates is noise that hides the row that matters, and items 8-12 extend
+        this tuple as they gain writers.
+        """
+        counted: dict[str, int] = {}
+        for table in COUNTED_TABLES:
+            # The names are this module's own constant, never caller input.
+            rows = self.backend.query(f"SELECT COUNT(*) AS n FROM {table}")  # noqa: S608
+            counted[table] = int(rows[0]["n"]) if rows else 0
+        return counted
+
+    def doctor(self) -> list["Finding"]:
+        """Every finding in this store, reported and never repaired.
+
+        On the handle so the CLI can ask without importing `adopt_store` -- the
+        composition root is `adopt_cli.store_option` and nothing else (CR-36),
+        and `store doctor` is one of the two commands that exemption exists for.
+        """
+        from adopt_store.doctor import doctor as run_doctor
+
+        return run_doctor(self)
+
+    def close(self) -> None:
+        self.backend.close()
+
+    def __enter__(self) -> "SqliteStoreHandle":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+
+def _restriction_for(version: int) -> OpenRestriction | None:
+    if version > MAX_SUPPORTED_SCHEMA_VERSION:
+        return OpenRestriction(
+            ErrorCode.SCHEMA_VERSION_TOO_NEW,
+            f"the store is at schema version {version} and this binary supports "
+            f"at most {MAX_SUPPORTED_SCHEMA_VERSION}",
+        )
+    if version < MIN_SUPPORTED_SCHEMA_VERSION:
+        return OpenRestriction(
+            ErrorCode.SCHEMA_MIGRATION_PENDING,
+            f"the store is at schema version {version} and this binary needs at "
+            f"least {MIN_SUPPORTED_SCHEMA_VERSION}; re-open with migrate=True",
+        )
+    return None
+
+
+def open_store(
+    path: Path | str,
+    *,
+    migrate: bool = False,
+    read_only: bool = False,
+    repo_root: Path | None = None,
+    clock: Clock | None = None,
+) -> SqliteStoreHandle:
+    """Open a store, applying the version matrix in implementation spec §4.7.1.
+
+    Args:
+        path: The store file.
+        migrate: Create or upgrade the store to `SCHEMA_VERSION` first.
+        read_only: Open for reading only. Never creates and never migrates.
+        repo_root: Where `schema/migrations/` lives. Defaults to the packaged
+            location, and is injected by tests working against a scratch tree.
+        clock: Injected clock; tests pass `ManualClock`.
+
+    Returns:
+        A handle carrying `read_only`, `restriction` and `schema_version`.
+
+    Raises:
+        AdoptError: ``SCHEMA_MIGRATION_PENDING`` when asked to open a store that
+            does not exist without `migrate`. ``SCHEMA_MIGRATION_FAILED`` when a
+            migration fails; the store is left exactly as it was found.
+    """
+    store_path = Path(path)
+
+    if read_only and migrate:
+        raise AdoptError(
+            ErrorCode.STORE_READ_ONLY,
+            message="a read-only open cannot migrate",
+            hint="Migrating is a write. Choose one: open read-only to read a store as "
+            "it is, or open for writing with migrate=True to bring it to the "
+            "current schema version.",
+        )
+
+    if not store_path.exists() and not migrate:
+        # Deliberately checked before opening: a read-write connect would create
+        # an empty file, and an empty file that is not a store is worse than no
+        # file at all -- the next open finds something and has to decide what.
+        raise AdoptError(
+            ErrorCode.SCHEMA_MIGRATION_PENDING,
+            message=f"no store exists at {store_path}",
+            hint="Pass migrate=True to create schema version 3.",
+        )
+
+    if read_only:
+        backend = SqliteStore(store_path, read_only=True, clock=clock)
+        version = backend.current_version()
+        restriction = _restriction_for(version)
+        if restriction is not None:
+            backend.read_only_reason = restriction.reason
+        else:
+            backend.read_only_reason = "the caller opened it read-only"
+        return SqliteStoreHandle(
+            backend=backend,
+            read_only=True,
+            restriction=restriction,
+            schema_version=version,
+            clock=clock,
+        )
+
+    backend = SqliteStore(store_path, clock=clock)
+    version = backend.current_version()
+
+    if version > MAX_SUPPORTED_SCHEMA_VERSION:
+        backend.close()
+        return _reopen_read_only(store_path, version, clock)
+
+    if migrate and (version < SCHEMA_VERSION or backend.is_empty()):
+        root = repo_root if repo_root is not None else _packaged_repo_root()
+        # `apply` appends the `schema_meta` row for every file it runs, so a
+        # freshly created store already carries its open record.
+        applied = apply_migrations(backend, root, _SQLITE_DIALECT, writer_identity())
+        version = backend.current_version()
+        if applied:
+            return SqliteStoreHandle(
+                backend=backend,
+                read_only=False,
+                restriction=None,
+                schema_version=version,
+                clock=clock,
+            )
+
+    if version < MIN_SUPPORTED_SCHEMA_VERSION:
+        backend.close()
+        return _reopen_read_only(store_path, version, clock)
+
+    backend.append_schema_meta(SCHEMA_VERSION, EXPORT_VERSION, writer_identity())
+    return SqliteStoreHandle(
+        backend=backend, read_only=False, restriction=None, schema_version=version, clock=clock
+    )
+
+
+def _reopen_read_only(path: Path, version: int, clock: Clock | None) -> SqliteStoreHandle:
+    restriction = _restriction_for(version)
+    assert restriction is not None  # noqa: S101 -- only reached for an out-of-range version
+    backend = SqliteStore(path, read_only=True, read_only_reason=restriction.reason, clock=clock)
+    return SqliteStoreHandle(
+        backend=backend,
+        read_only=True,
+        restriction=restriction,
+        schema_version=version,
+        clock=clock,
+    )
+
+
+def _packaged_repo_root() -> Path:
+    """The root holding `schema/`, wherever this artefact carries it.
+
+    This function used to walk five parents up from `__file__` and its docstring
+    claimed that avoided "the failure that only shows up after release". **It
+    named the failure it did not prevent** (CR-53): from an installed wheel the
+    walk leaves `site-packages` and lands on the environment root, which holds no
+    `schema/`, and the migrations glob then found nothing and reported nothing
+    pending. `adopt_schema.assets` resolves it in one place and raises
+    `SCHEMA_ASSETS_MISSING` when it genuinely cannot be found.
+    """
+    return assets_root()