functualize-state-sqlite 0.2.3__tar.gz → 0.3.0__tar.gz

{functualize_state_sqlite-0.2.3 → functualize_state_sqlite-0.3.0}/.gitignore

@@ -113,3 +113,30 @@ examples/plugins/file_based_plugin/.functualize/plugins/*
 .release/
 .worktrees/
 .claude/settings.local.json
+
+# Agent index directories. Which parts are tracked is decided by ONE property:
+# whether the stored paths are portable.
+#
+#   graphify  graph.json holds only repo-relative paths, so it travels into every
+#             worktree and every ephemeral cloud checkout for free. Tracked.
+#             Its cache/, manifest.json and .graphify_root are machine-local
+#             (mtimes, absolute paths), so the rule below is a whitelist: ignore
+#             everything, then un-ignore the two portable artifacts.
+#   zvec-grep index entries are keyed by ABSOLUTE path — copying one and rewriting
+#             its manifest yields 0% coverage and a full re-embed. Never tracked;
+#             each workspace builds its own (~21s scoped).
+#   serena    cache/ pickles hold absolute file:// URIs, so those and
+#             project.local.yml are machine-local; serena's own
+#             .serena/.gitignore already excludes cache/ and project.local.yml.
+#             memories/ is plain text and portable, but not tracked anyway: it
+#             duplicated contract docs that already have a committed home
+#             (`.claude/rules/spec-workflow.md`, `.spec/ARCHITECTURE.md`,
+#             AGENTS.md) and went stale the moment those changed underneath
+#             it. project.yml stays tracked and portable.
+graphify-out/*
+!graphify-out/graph.json
+!graphify-out/GRAPH_REPORT.md
+.zvec-grep/
+.serena/cache/
+.serena/project.local.yml
+.serena/memories/

functualize_state_sqlite-0.3.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

functualize_state_sqlite-0.3.0/NOTICE

@@ -0,0 +1,5 @@
+functualize
+Copyright 2025-2026 Mohammad Hakim Adiprasetya
+
+This product includes software developed by
+Mohammad Hakim Adiprasetya (https://github.com/raicing-ai/functualize).

{functualize_state_sqlite-0.2.3 → functualize_state_sqlite-0.3.0}/PKG-INFO

@@ -1,9 +1,11 @@
 Metadata-Version: 2.5
 Name: functualize-state-sqlite
-Version: 0.2.3
+Version: 0.3.0
 Summary: SQLite-backed state persistence and execution tracking plugin for functualize
 Author-email: Mohammad Hakim Adiprasetya <viltohmyst@gmail.com>
-License-Expression: MIT
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -11,7 +13,6 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: functualize-state<1.0.0,>=0.1.0
 Requires-Dist: functualize<1.0.0,>=0.1.0
 Provides-Extra: dev
 Requires-Dist: hypothesis>=6.82.0; extra == 'dev'
@@ -70,7 +71,7 @@ Public classes exported by this plugin:
 Internal classes (available via direct import but not part of the public protocol surface):
 
 - `SQLiteBackend` — Low-level connection manager with WAL mode, schema initialization, and query helpers for sessions, executions, steps, and namespaced state.
-- `SQLiteStateStore` — `StateStoreProtocol` implementation scoped to a `(scope_id, job_namespace)` pair, with `get()`, `set()`, `delete()`, `keys()`, `to_dict()`, `clear()`, and cross-job access via `get_job_state()`.
+- `SQLiteStateStore` — `StateStoreProtocol` implementation scoped to a `(scope_id, job_namespace)` pair, with `get()`, `set()`, `delete()`, `keys()`, `to_dict()` and `clear()`.
 - `ExecutionTracker` — High-level session management and execution recording with automatic session resume based on TTL, and AI context summary generation via `to_ai_context()`.
 
 ## Development

{functualize_state_sqlite-0.2.3 → functualize_state_sqlite-0.3.0}/README.md

@@ -49,7 +49,7 @@ Public classes exported by this plugin:
 Internal classes (available via direct import but not part of the public protocol surface):
 
 - `SQLiteBackend` — Low-level connection manager with WAL mode, schema initialization, and query helpers for sessions, executions, steps, and namespaced state.
-- `SQLiteStateStore` — `StateStoreProtocol` implementation scoped to a `(scope_id, job_namespace)` pair, with `get()`, `set()`, `delete()`, `keys()`, `to_dict()`, `clear()`, and cross-job access via `get_job_state()`.
+- `SQLiteStateStore` — `StateStoreProtocol` implementation scoped to a `(scope_id, job_namespace)` pair, with `get()`, `set()`, `delete()`, `keys()`, `to_dict()` and `clear()`.
 - `ExecutionTracker` — High-level session management and execution recording with automatic session resume based on TTL, and AI context summary generation via `to_ai_context()`.
 
 ## Development

{functualize_state_sqlite-0.2.3 → functualize_state_sqlite-0.3.0}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "functualize-state-sqlite"
-version = "0.2.3"
+version = "0.3.0"
 description = "SQLite-backed state persistence and execution tracking plugin for functualize"
 readme = "README.md"
-license = "MIT"
+license = "Apache-2.0"
 authors = [
     { name = "Mohammad Hakim Adiprasetya", email = "viltohmyst@gmail.com" }
 ]
@@ -18,7 +18,6 @@ classifiers = [
 ]
 dependencies = [
     "functualize>=0.1.0,<1.0.0",
-    "functualize-state>=0.1.0,<1.0.0",
 ]
 
 [project.entry-points."functualize.state_providers"]
@@ -37,7 +36,6 @@ build-backend = "hatchling.build"
 
 [tool.uv.sources]
 functualize = { workspace = true }
-functualize-state = { workspace = true }
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/functualize_state_sqlite"]

functualize_state_sqlite-0.3.0/src/functualize_state_sqlite/__init__.py

@@ -0,0 +1,14 @@
+"""SQLite-backed runtime state for functualize.
+
+One substrate, installed at boot. See `substrate.py` for why this replaced a
+key-value `StateBackend`, and `contributor/adr/022` for why that idea is
+retired rather than deferred.
+"""
+
+from functualize_state_sqlite._plugin import SQLiteStatePlugin
+from functualize_state_sqlite.substrate import SQLiteSubstrate
+
+__all__ = [
+    "SQLiteStatePlugin",
+    "SQLiteSubstrate",
+]

functualize_state_sqlite-0.3.0/src/functualize_state_sqlite/_plugin.py

@@ -0,0 +1,113 @@
+"""The plugin: install a SQLite substrate, and nothing else.
+
+`store-substrate`/T5, T6.
+
+This used to be three things at once — a `StateBackend`, an `ExecutionStore`,
+and a per-scope key-value store swapped in at `ON_SCOPE_CREATED`. All three are
+gone, and the reason is the same one in all three cases: they were a *second*
+storage vocabulary sitting beside the framework's own.
+
+- The scope store swap happened one level below the real seam, so a scope could
+  keep its job state in SQLite while the records describing it stayed on the
+  filesystem. A resumed run then found its steps and not its variables.
+- `StateBackend` and `ExecutionStore` were a backend-agnostic key-value
+  protocol, which can only offer the intersection of every backend — worth
+  least exactly where having a database is worth most. `contributor/adr/022`
+  records that argument so it is not re-proposed.
+
+What is left is one line of work: choose the substrate. Every store follows,
+because there is one place that decides and one object handed to all of them.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from functualize_state_sqlite.substrate import SQLiteSubstrate
+
+__all__ = ["SQLiteStatePlugin"]
+
+logger = logging.getLogger(__name__)
+
+#: Where the database goes when nothing configures it. Beside the project's
+#: other runtime state, so `func builtin data clear` and a `.gitignore` that
+#: already covers `.functualize/` keep working.
+DEFAULT_DB_NAME = "state.db"
+
+
+class SQLiteStatePlugin:
+    """Installs a :class:`SQLiteSubstrate` as the app's substrate at boot."""
+
+    name: str = "sqlite-state"
+    version: str = "0.2.0"
+    description: str = "Keeps this project's runtime state in SQLite"
+
+    def __init__(self) -> None:
+        self._substrate: SQLiteSubstrate | None = None
+
+    @property
+    def substrate(self) -> SQLiteSubstrate | None:
+        """The substrate this plugin installed, or None before APP_READY."""
+        return self._substrate
+
+    def __call__(self, app: Any) -> None:
+        from functualize._events.hooks import HookEvent
+
+        app.hook_registry.register_global(HookEvent.APP_READY, self._on_app_ready)
+
+    def _on_app_ready(self, app: Any) -> None:
+        """Choose the substrate, once, before anything has resolved one.
+
+        `APP_READY` is the right moment and not an arbitrary one: the engine
+        resolves its substrate lazily, on the first store access, which happens
+        during a run. Installing later is **refused** by the app rather than
+        allowed to half-apply — some of a run's documents in one backend and
+        some in the other is exactly the state this feature exists to make
+        unreachable.
+
+        A failure to install is logged and left alone. The app then uses the
+        filesystem default, which is a working program with a note in the log
+        rather than a boot that dies over a storage preference.
+        """
+        try:
+            self._substrate = SQLiteSubstrate(self._db_path(app))
+            app.substrate = self._substrate
+        except Exception:
+            logger.exception(
+                "sqlite-state could not install its substrate; this project "
+                "will use the filesystem default"
+            )
+            return
+        logger.debug("sqlite-state installed a substrate at %s", self._substrate.path)
+
+    def _db_path(self, app: Any) -> Path:
+        """``plugin.sqlite-state.db_path``, or beside the project's other state.
+
+        Resolved from :attr:`fresh_root` rather than the cwd, so a later
+        ``chdir`` cannot move a run's database out from under it — the same
+        rule the filesystem substrate follows.
+        """
+        configured = self._configured_path(app)
+        if configured:
+            return Path(configured)
+        return Path(app.fresh_root) / ".functualize" / DEFAULT_DB_NAME
+
+    @staticmethod
+    def _configured_path(app: Any) -> str | None:
+        try:
+            from pydantic import BaseModel, Field
+
+            class _SqliteConfig(BaseModel):
+                db_path: str | None = Field(
+                    default=None,
+                    description="Where this project's SQLite state lives.",
+                )
+
+            resolved = app.configuration.resolve_model(
+                "plugin.sqlite-state", _SqliteConfig
+            )
+            return resolved.db_path
+        except Exception:
+            return None

functualize_state_sqlite-0.3.0/src/functualize_state_sqlite/substrate.py

@@ -0,0 +1,225 @@
+"""A `StoreSubstrate` over SQLite. One table, six methods.
+
+`store-substrate`/T5.
+
+This plugin used to supply a **key-value store for one scope's job state**,
+swapped in through `WorkflowScope.replace_state_store`. That was a seam one
+level below the real one, and it is what made the split brain reachable: a
+scope could keep its job state in SQLite while the *records* describing that
+scope — which steps ran, where the walk stopped, what a human approved — stayed
+on the filesystem. A resumed run then found its steps and not its variables.
+
+So the plugin now supplies a **substrate**, and every store moves together or
+none does.
+
+## Why this is the interesting implementation
+
+`JsonFileSubstrate` is the baseline; it exists to change nothing. This one is
+the reason the port exists at all:
+
+- **It has no shared disk.** Two processes on different machines can reach the
+  same database, which is what makes a gate blocked on one runner resumable on
+  another (spec AC-3).
+- **`lock` is one lock.** A transaction covers every key it is given, so the
+  lock-order inversion an external review found between the scope lock and the
+  state lock is removed *by construction* rather than by asking callers to
+  acquire in a careful order. `JsonFileSubstrate` can only sort; this cannot
+  invert.
+- **`write(expect=)` is a real compare-and-swap**, done in SQL, so it does not
+  depend on the caller holding anything.
+
+## The revision
+
+A monotonically increasing integer per document, assigned by the write. Unlike
+`JsonFileSubstrate`'s content hash it does not survive rewriting the same
+content, and that is fine: a revision is an opaque token to compare, and the
+port says so.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from functualize._types.errors import SubstrateUnreadableError
+from functualize._types.protocols import Stored
+
+__all__ = ["SQLiteSubstrate"]
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS documents (
+    key      TEXT PRIMARY KEY,
+    payload  TEXT NOT NULL,
+    revision INTEGER NOT NULL
+);
+"""
+
+
+class SQLiteSubstrate:
+    """Documents in one SQLite table, reachable from any process."""
+
+    __slots__ = ("_local", "_path")
+
+    def __init__(self, path: Path | str) -> None:
+        self._path = Path(path)
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        #: One connection per thread. SQLite connections are not safe to share
+        #: across threads, and `invoke_parallel` runs workers on threads that
+        #: all reach the same substrate.
+        self._local = threading.local()
+        self._conn().executescript(_SCHEMA)
+
+    @property
+    def path(self) -> Path:
+        """The database file."""
+        return self._path
+
+    def _conn(self) -> sqlite3.Connection:
+        conn = getattr(self._local, "conn", None)
+        if conn is None:
+            conn = sqlite3.connect(str(self._path), isolation_level=None)
+            conn.execute("PRAGMA journal_mode=WAL")
+            conn.execute("PRAGMA busy_timeout=10000")
+            self._local.conn = conn
+            self._local.depth = 0
+        return conn
+
+    # ------------------------------------------------------------------
+    # The port
+    # ------------------------------------------------------------------
+
+    def read(self, key: str) -> Stored | None:
+        row = (
+            self._conn()
+            .execute("SELECT payload, revision FROM documents WHERE key = ?", (key,))
+            .fetchone()
+        )
+        if row is None:
+            return None
+        try:
+            data = json.loads(row[0])
+        except ValueError as exc:
+            raise SubstrateUnreadableError(key, str(exc)) from exc
+        if not isinstance(data, dict):
+            raise SubstrateUnreadableError(
+                key, f"expected an object, found {type(data).__name__}"
+            )
+        return Stored(data=data, revision=int(row[1]))
+
+    def write(
+        self, key: str, payload: dict[str, Any], *, expect: int | None = None
+    ) -> bool:
+        """Replace the document, refusing when ``expect`` no longer matches.
+
+        The compare and the write are **one statement**, so unlike the
+        filesystem implementation this does not need the caller to hold a lock
+        to be exact. That is the property a backend with no `flock` has to
+        provide instead.
+        """
+        blob = json.dumps(payload, indent=2, sort_keys=True)
+        conn = self._conn()
+        if expect is None:
+            conn.execute(
+                "INSERT INTO documents (key, payload, revision) VALUES (?, ?, 1) "
+                "ON CONFLICT(key) DO UPDATE SET payload = excluded.payload, "
+                "revision = documents.revision + 1",
+                (key, blob),
+            )
+            return True
+        cursor = conn.execute(
+            "UPDATE documents SET payload = ?, revision = revision + 1 "
+            "WHERE key = ? AND revision = ?",
+            (blob, key, expect),
+        )
+        return cursor.rowcount == 1
+
+    @contextmanager
+    def lock(self, *keys: str) -> Iterator[None]:
+        """**One** lock, covering every key — the whole point of the port.
+
+        A write transaction on the database excludes every other writer
+        regardless of which keys they named, so a caller that takes state then
+        scopes and a caller that takes scopes then state cannot deadlock
+        against each other. `JsonFileSubstrate` sorts its per-file locks, which
+        prevents a caller from inverting *within one call* and nothing more.
+
+        Re-entrant per thread, because a store takes the lock around a
+        read-modify-write that a wider batch may already hold.
+        """
+        conn = self._conn()
+        depth = getattr(self._local, "depth", 0)
+        self._local.depth = depth + 1
+        try:
+            if depth == 0:
+                conn.execute("BEGIN IMMEDIATE")
+                try:
+                    yield
+                except BaseException:
+                    conn.execute("ROLLBACK")
+                    raise
+                else:
+                    conn.execute("COMMIT")
+            else:
+                yield
+        finally:
+            self._local.depth = depth
+
+    def clear(self, key: str) -> str | None:
+        """Copy the document to a backup key and remove the original.
+
+        Never decodes it — the escape hatch has to work on exactly the content
+        :meth:`read` refuses.
+        """
+        conn = self._conn()
+        row = conn.execute(
+            "SELECT payload FROM documents WHERE key = ?", (key,)
+        ).fetchone()
+        if row is None:
+            return None
+        backup = f"{key}.bak"
+        index = 1
+        while conn.execute(
+            "SELECT 1 FROM documents WHERE key = ?", (backup,)
+        ).fetchone():
+            backup = f"{key}.bak.{index}"
+            index += 1
+        conn.execute(
+            "INSERT INTO documents (key, payload, revision) VALUES (?, ?, 1)",
+            (backup, row[0]),
+        )
+        conn.execute("DELETE FROM documents WHERE key = ?", (key,))
+        return f"{self._path}#{backup}"
+
+    def delete(self, key: str) -> bool:
+        cursor = self._conn().execute("DELETE FROM documents WHERE key = ?", (key,))
+        return cursor.rowcount > 0
+
+    def describe(self, key: str) -> str:
+        """The database, the key, and the payload size.
+
+        A namespace key (``"scope-state/"``) is described in aggregate, as the
+        port requires, because scope state is one document per run.
+        """
+        conn = self._conn()
+        if key.endswith("/"):
+            row = conn.execute(
+                "SELECT COUNT(*), COALESCE(SUM(LENGTH(payload)), 0) "
+                "FROM documents WHERE key LIKE ?",
+                (f"{key}%",),
+            ).fetchone()
+            count, total = int(row[0]), int(row[1])
+            if not count:
+                return "empty"
+            plural = "" if count == 1 else "s"
+            return f"{count} document{plural}, {total} B in {self._path}"
+        row = conn.execute(
+            "SELECT LENGTH(payload) FROM documents WHERE key = ?", (key,)
+        ).fetchone()
+        if row is None:
+            return f"{self._path}#{key} (absent)"
+        return f"{self._path}#{key} ({int(row[0])} B)"