zikaron 0.1.0__py3-none-any.whl

zikaron/core/store/store.py

@@ -0,0 +1,408 @@
+"""Schema creation, open/close, and the checks each of those two paths is required to run.
+
+`schema.md` §"Creating the dense index" fixes creation's order because `vec0` fixes a column's
+width forever at `CREATE` time: validate the effective `embed_dim`, check the configured
+embedder's actual output width against it, *then* create tables — in that order, so a
+mismatched model name never produces a store whose every future write fails at insert time
+pointing at the wrong culprit. Open re-validates `meta` on every call, per the same document's
+"validation happens twice" rule, and refuses to proceed through a `reindexing` sentinel left by
+a process that died mid-reindex, or through a `schema_version` this build does not support.
+"""
+
+import asyncio
+import re
+import uuid
+from pathlib import Path
+from types import TracebackType
+from typing import Final, Self
+
+import aiosqlite
+
+from zikaron.core.config.resolution import EffectiveConfig
+from zikaron.core.errors import BadConfigSource, ErrorCode, ZikaronError
+from zikaron.core.store import ddl, meta, permissions
+from zikaron.core.store.connection import open_connection
+from zikaron.core.store.embedder import Embedder
+
+#: The schema version every table and invariant in this build implements. Sourced from nowhere
+#: else: `zikaron.core.errors.ERROR_SPECS[ErrorCode.SCHEMA_INCOMPATIBLE]`'s payload fixes
+#: `supported` to the same integer, and a test asserts the two agree rather than one restating
+#: the other: one declaration, checked from two directions, rather than two that agree today.
+SUPPORTED_SCHEMA_VERSION: Final = 1
+
+_DB_FILENAME: Final = "memory.db"
+
+#: `vec0` has no introspection function for a column's declared width; the only place it is
+#: recorded is the literal `CREATE VIRTUAL TABLE` text `sqlite_master` stores verbatim. Matched
+#: as the **whole** value, not a substring search — `sqlite_master.sql` holds exactly one
+#: statement per row, so a genuine `vec0` table's row is entirely this shape and nothing else,
+#: and searching for the shape *inside* an arbitrary string would accept a table that merely
+#: quotes the phrase as data (a `CHECK` constraint's string literal, for instance) without ever
+#: being `vec0` at all. `fullmatch` after collapsing whitespace is what makes "the entire
+#: recorded statement is this shape" the actual test, rather than "this shape occurs somewhere
+#: in the recorded statement."
+_VEC0_WIDTH_PATTERN: Final = re.compile(
+    r"CREATE\s+VIRTUAL\s+TABLE\s+memory_vec\s+USING\s+vec0\s*\(\s*embedding\s+float\[(\d+)\]\s*\)",
+    re.IGNORECASE,
+)
+
+
+async def _physical_vec0_width(db: aiosqlite.Connection) -> int:
+    """The width `memory_vec.embedding` was actually created at, read back from its own DDL.
+
+    `meta.embed_dim` records what the store's `meta` row *says* the width is; this reads what
+    the column *is*, so invariant 11's check on open cannot be satisfied by a `meta` row that
+    agrees with the effective config while the physical column disagrees with both — nor by an
+    object merely *named* `memory_vec` that is not a `vec0` virtual table at all. Matching the
+    *whole* recorded statement, not searching for the shape somewhere inside it, is what rules
+    that second case out: a table whose `CHECK` constraint merely quotes the expected phrase as
+    string data would satisfy a substring search without being `vec0` at all, since the phrase
+    would then simply be present somewhere in a longer string that is not, as a whole, that
+    statement.
+    """
+    rows = await db.execute_fetchall("SELECT sql FROM sqlite_master WHERE name = 'memory_vec'")
+    matches = list(rows)
+    if len(matches) != 1:
+        raise ZikaronError(
+            ErrorCode.BAD_CONFIG,
+            source=BadConfigSource.META,
+            key="memory_vec",
+            value=f"{len(matches)} matching tables",
+            expected="exactly one memory_vec table",
+        )
+    (sql,) = matches[0]
+    collapsed = re.sub(r"\s+", " ", str(sql)).strip()
+    found = _VEC0_WIDTH_PATTERN.fullmatch(collapsed)
+    if found is None:
+        raise ZikaronError(
+            ErrorCode.BAD_CONFIG,
+            source=BadConfigSource.META,
+            key="memory_vec",
+            value=str(sql),
+            expected="CREATE VIRTUAL TABLE memory_vec USING vec0 (embedding float[<n>])",
+        )
+    return int(found.group(1))
+
+
+async def _read_meta_table(db: aiosqlite.Connection) -> dict[str, str]:
+    """Every `meta` row's text value, or an empty mapping if `meta` itself does not exist.
+
+    `existing_only=True` on `open_connection` stops `Store.open` from *creating* a missing
+    store, but it does nothing about an existing `memory.db` whose `meta` table is itself
+    absent — dropped by hand, or left behind by a process that failed between creating the
+    file and running its DDL. That case must still fail at the Zikaron boundary as
+    `bad_config`, not as a raw `sqlite3.OperationalError` bubbling straight out of a driver
+    call. Returning an empty mapping rather than raising here reuses `parse_and_validate`'s own
+    existing "first required key found missing" reporting — a store with no `meta` table is a
+    store missing all five required keys, which is exactly true, and reporting it that way
+    costs no second error path.
+    """
+    try:
+        rows = await db.execute_fetchall("SELECT key, value FROM meta")
+    except aiosqlite.Error:
+        return {}
+    return {str(key): str(value) for key, value in rows}
+
+
+def _store_not_created(db_path: Path) -> ZikaronError:
+    """What a failed connect to an existing-only `memory.db` means to the memory store.
+
+    Scoped to the connect rather than to the whole open, because a database that connected and
+    then refused a pragma has been created — saying it has not would send an operator looking for
+    a missing file that is right there.
+    """
+    return ZikaronError(
+        ErrorCode.BAD_CONFIG,
+        source=BadConfigSource.DERIVED,
+        key="store_dir",
+        value=str(db_path),
+        expected="an existing, openable memory.db — this store has not been created",
+    )
+
+
+def _dimension_mismatch(
+    config: EffectiveConfig, embed_dim: int, embedder: Embedder
+) -> ZikaronError:
+    return ZikaronError(
+        ErrorCode.BAD_CONFIG,
+        source=BadConfigSource.FILE,
+        file=str(config.source_of("embed_dim") or "<default>"),
+        key="embedding.embed_dim",
+        value=str(embed_dim),
+        expected=f"the configured embedder ({embedder.model_name}) actually emits "
+        f"{embedder.dim}-dimensional vectors",
+    )
+
+
+def _model_name_mismatch(config: EffectiveConfig, embedder: Embedder) -> ZikaronError:
+    configured = config.get_str("embed_model")
+    return ZikaronError(
+        ErrorCode.BAD_CONFIG,
+        source=BadConfigSource.FILE,
+        file=str(config.source_of("embed_model") or "<default>"),
+        key="embedding.embed_model",
+        value=configured,
+        expected=f"the embedder passed to create() reports model_name={embedder.model_name!r}, "
+        "which must match the configured embed_model — meta seeds from this call's embedder, "
+        "not from the config text alone",
+    )
+
+
+def _reindexing_in_progress(since: str) -> ZikaronError:
+    return ZikaronError(ErrorCode.REINDEXING, since=since)
+
+
+def _schema_too_new(found: int) -> ZikaronError:
+    return ZikaronError(
+        ErrorCode.SCHEMA_INCOMPATIBLE, found=found, supported=SUPPORTED_SCHEMA_VERSION
+    )
+
+
+def _embed_settings_disagree(
+    current: meta.StoreMeta, configured_model: str, configured_dim: int
+) -> ZikaronError:
+    return ZikaronError(
+        ErrorCode.BAD_CONFIG,
+        source=BadConfigSource.META,
+        key="embed_model/embed_dim",
+        value=f"{configured_model}/{configured_dim}",
+        expected=f"{current.embed_model}/{current.embed_dim} (the values this store was "
+        "created with — invariant 11 requires a forced reindex, never a silent continue, "
+        "on disagreement)",
+    )
+
+
+def _physical_width_disagrees(recorded_dim: int, physical_width: int) -> ZikaronError:
+    return ZikaronError(
+        ErrorCode.BAD_CONFIG,
+        source=BadConfigSource.META,
+        key="embed_dim",
+        value=str(recorded_dim),
+        expected=f"{physical_width} (the width memory_vec's own column was actually created "
+        "at — meta.embed_dim must agree with the physical column, not only with the config, "
+        "or a corrupted meta row could silently outlive the vec0 table it describes)",
+    )
+
+
+class Store:
+    """An open connection to one Zikaron store, plus the `meta` it was opened with.
+
+    Construct only through `create` or `open`, never directly: both classmethods run the
+    validation their path requires before a `Store` exists to hand back, so holding one is
+    holding a store already known to satisfy invariants 1, 3 and 11 for this open.
+
+    `opened_inode` is `db_path`'s own inode, captured by `open_connection` immediately after
+    its own `aiosqlite.connect()` returned, with no `await` in between — the tightest available
+    capture short of a materially larger VFS-level integration a deliberate, human-authorized
+    decision declined to pursue (see `open_connection`'s own docstring for the full reasoning
+    and the narrow, accepted gap this leaves). It is *not* re-derivable later from
+    `self.path.stat()`: that would read whatever file currently sits at the path, which is
+    precisely the question this field exists to answer independently of.
+    """
+
+    def __init__(
+        self,
+        db: aiosqlite.Connection,
+        db_path: Path,
+        current_meta: meta.StoreMeta,
+        opened_inode: int,
+    ) -> None:
+        self._db: Final = db
+        self.path: Final = db_path
+        self.meta: Final = current_meta
+        self.opened_inode: Final = opened_inode
+
+    @property
+    def connection(self) -> aiosqlite.Connection:
+        """The underlying `aiosqlite` connection, for a caller that needs to run its own SQL.
+
+        Exposed rather than wrapped with per-statement methods: this module owns schema creation
+        and the open path, and no record behaviour lives here for a method to wrap.
+        """
+        return self._db
+
+    async def close(self) -> None:
+        """Close the underlying connection. Safe to call once; not idempotent."""
+        await self._db.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    @classmethod
+    async def create(cls, store_dir: Path, config: EffectiveConfig, embedder: Embedder) -> Self:
+        """Create a fresh store at `store_dir/memory.db`, or raise before touching any table.
+
+        Order is the contract, not an implementation choice (`schema.md` §"Creating the dense
+        index"): the effective `embed_dim` is validated, then the embedder's *actual* reported
+        width is checked against it, and only once both hold does any `CREATE` statement run.
+        A mismatch is `bad_config` naming both values, with **no database file yet on disk** —
+        `store_dir` is created, but `memory.db` is opened only after the check passes, so a
+        typo'd model name never produces a store to clean up.
+
+        Args:
+            store_dir: the `.zikaron` directory this store lives in. Created at `0700` if
+                absent; tightened to it if it exists wider.
+            config: the effective configuration to seed `meta` from. Its `embed_dim` and
+                `embed_model` become this store's dual-homed `meta` values, authoritative from
+                this point on.
+            embedder: the configured embedder. Consulted only for `.dim` and `.model_name` —
+                creation embeds nothing.
+
+        Raises:
+            ZikaronError: `BAD_CONFIG`, naming `embed_dim` and the embedder's actual width, if
+                the effective config's `embed_dim` does not equal what `embedder.dim` reports;
+                or naming `embed_model`, if `embedder.model_name` disagrees with the configured
+                `embed_model` — the config states which model to seed `meta` with, and the
+                embedder that actually produced the width check must be that model, not merely
+                one of the right dimension.
+        """
+        embed_dim = config.get_int("embed_dim")
+        embed_model = config.get_str("embed_model")
+        if embedder.dim != embed_dim:
+            raise _dimension_mismatch(config, embed_dim, embedder)
+        if embedder.model_name != embed_model:
+            raise _model_name_mismatch(config, embedder)
+
+        await asyncio.to_thread(permissions.ensure_store_dir, store_dir)
+        db_path = store_dir / _DB_FILENAME
+        chunk_max_tokens = config.get_int("chunk_max_tokens")
+
+        # A pre-existing `memory.db` — left behind by an earlier failed attempt, or widened by
+        # an operator's own `chmod` — must be tightened before anything fallible runs, not only
+        # after this call succeeds. `enforce_store_file_mode` after a successful create closes
+        # the gap for files *this* call creates; it says nothing about a file that was already
+        # here and wide before this call started, and a failure partway through must not leave
+        # that file exactly as wide as it found it.
+        for path in permissions.database_files(db_path):
+            await asyncio.to_thread(permissions.enforce_store_file_mode, path)
+
+        with permissions.restrictive_umask():
+            db, opened_inode = await open_connection(db_path, pragmas=ddl.PRAGMAS)
+            try:
+                defaults = await cls._create_tables_and_meta(
+                    db, embed_dim, embed_model, chunk_max_tokens
+                )
+            except BaseException:
+                await db.close()
+                raise
+
+        for path in permissions.database_files(db_path):
+            await asyncio.to_thread(permissions.enforce_store_file_mode, path)
+
+        current_meta = meta.parse_and_validate(defaults)
+        return cls(db, db_path, current_meta, opened_inode)
+
+    @staticmethod
+    async def _create_tables_and_meta(
+        db: aiosqlite.Connection, embed_dim: int, embed_model: str, chunk_max_tokens: int
+    ) -> dict[str, str]:
+        """Run every `CREATE` statement plus the `meta` defaults insert, in one transaction.
+
+        Split out of `create` so that method's own control flow stays about ordering and error
+        handling, while this one is purely "what SQL runs" — the two concerns `TRY301` otherwise
+        conflates by wanting every raise abstracted out of a `try` block that has no raise of
+        its own to abstract.
+        """
+        await db.execute("BEGIN")
+        for statement in ddl.FIXED_STATEMENTS:
+            await db.execute(statement)
+        await db.execute(ddl.memory_vec_statement(embed_dim))
+        store_id = str(uuid.uuid4())
+        defaults = dict(
+            meta.defaults_at_creation(
+                schema_version=SUPPORTED_SCHEMA_VERSION,
+                store_id=store_id,
+                embed_model=embed_model,
+                embed_dim=embed_dim,
+                chunk_max_tokens=chunk_max_tokens,
+            )
+        )
+        for key, value in defaults.items():
+            await db.execute("INSERT INTO meta (key, value) VALUES (?, ?)", (key, value))
+        await db.commit()
+        return defaults
+
+    @classmethod
+    async def open(cls, store_dir: Path, config: EffectiveConfig) -> Self:
+        """Open an existing store at `store_dir/memory.db`, validating on every call.
+
+        Runs, in order: permission enforcement and the symlink refusal (tightening a store left
+        wider than `0700`/`0600` by an older build or an operator's own `chmod`), the
+        `reindexing` sentinel check (invariant 3 — a process that died mid-reindex must not be
+        read through), all five required `meta` keys (`schema.md`'s "validation happens
+        twice"), the `schema_version` gate, invariant 11's physical `memory_vec` width check
+        (against `meta`, not only against the config — `meta` can drift from the table it
+        describes even when it agrees with the file), and finally invariant 11's
+        `embed_model`/`embed_dim` comparison against the effective config.
+
+        Args:
+            store_dir: the `.zikaron` directory holding `memory.db`.
+            config: the effective configuration this open is running under, compared against
+                `meta`'s dual-homed values rather than trusted silently.
+
+        Raises:
+            ZikaronError: `BAD_CONFIG` if `store_dir` is a symlink; `REINDEXING` if the sentinel
+                is present; `BAD_CONFIG` (`source='meta'`) if a required key is missing,
+                unparseable, or out of range, if the physical `memory_vec` column's width
+                disagrees with `meta.embed_dim`, or if `embed_model`/`embed_dim` disagrees with
+                the effective config (invariant 11); `SCHEMA_INCOMPATIBLE` if
+                `meta.schema_version` exceeds `SUPPORTED_SCHEMA_VERSION`.
+        """
+        # `enforce_existing_store_permissions` is itself synchronous filesystem I/O (symlink
+        # checks, `stat`, a possible `chmod` per ancestor and per store file) — run through
+        # `asyncio.to_thread` rather than called directly, so this coroutine's first blocking
+        # step does not hold the event loop of a caller that shares one across many concurrent
+        # requests, exactly as every other blocking call this `open` path makes already does
+        # (`open_connection`'s own `aiosqlite.connect`, `_validate_on_open`'s SQL). A caller with
+        # no such sharing to protect (a short-lived script, one request at a time) pays this
+        # cost identically either way; only a caller like `zikaron-mcp` — one long-running
+        # process holding many concurrent tool calls on one loop — depends on it.
+        await asyncio.to_thread(permissions.enforce_existing_store_permissions, store_dir)
+        db_path = store_dir / _DB_FILENAME
+        db, opened_inode = await open_connection(
+            db_path,
+            pragmas=ddl.PRAGMAS,
+            existing_only=True,
+            connect_failure=lambda _: _store_not_created(db_path),
+        )
+        try:
+            current_meta = await cls._validate_on_open(db, config)
+        except BaseException:
+            await db.close()
+            raise
+        return cls(db, db_path, current_meta, opened_inode)
+
+    @staticmethod
+    async def _validate_on_open(
+        db: aiosqlite.Connection, config: EffectiveConfig
+    ) -> meta.StoreMeta:
+        """Every check `open` must run before handing back a `Store`, in the required order."""
+        raw = await _read_meta_table(db)
+
+        since = raw.get(meta.REINDEXING_KEY)
+        if since is not None:
+            raise _reindexing_in_progress(since)
+
+        current_meta = meta.parse_and_validate(raw)
+
+        if current_meta.schema_version > SUPPORTED_SCHEMA_VERSION:
+            raise _schema_too_new(current_meta.schema_version)
+
+        physical_width = await _physical_vec0_width(db)
+        if physical_width != current_meta.embed_dim:
+            raise _physical_width_disagrees(current_meta.embed_dim, physical_width)
+
+        configured_model = config.get_str("embed_model")
+        configured_dim = config.get_int("embed_dim")
+        if current_meta.embed_model != configured_model or current_meta.embed_dim != configured_dim:
+            raise _embed_settings_disagree(current_meta, configured_model, configured_dim)
+
+        return current_meta

zikaron/core/store/transactions.py

@@ -0,0 +1,181 @@
+"""How a transaction ends, in one place, for every layer that opens one.
+
+`schema.md` invariant 2 makes "exactly one SQLite transaction" a property of every logical
+mutation, and `retrieval.md` makes it a property of a read too, because a probe and the
+`chunk_count` it is compared against have to see one snapshot. Every layer therefore needs the
+same three things — `BEGIN`, the work, and a finalization that leaves the connection out of a
+transaction whatever happened — and the third is where the difficulty is: a `COMMIT` can fail, a
+failed `COMMIT` can leave the transaction open, and a `ROLLBACK` can fail too. A second copy of
+that ladder is precisely how a write already reported as failed comes to be committed by whatever
+runs next, so there is one.
+
+This sits in `store/` because everything here is a property of SQLite rather than of records,
+indexing or retrieval: which result codes mean *locked*, and what has to be true of a connection
+when a caller lets go of it.
+
+**What varies between callers is only how a driver-level failure is named**, so that is the one
+parameter: a function from the driver's exception to the wire error it should become, or to `None`
+for a failure that has no Zikaron code and should propagate as itself. `architecture.md` §Errors
+fixes both halves — a write names contention `store_busy` and everything else `index_failed`,
+while a read names contention and propagates the rest, since `index_failed`'s contract speaks of
+index maintenance and a rolled-back write.
+"""
+
+import contextlib
+import sqlite3
+from collections.abc import Awaitable, Callable
+from typing import Final, NoReturn
+
+import aiosqlite
+
+from zikaron.core.errors import ErrorCode, ZikaronError
+
+#: One caller's work inside an already-open transaction.
+type Work[T] = Callable[[aiosqlite.Connection], Awaitable[T]]
+
+#: How a caller names a driver-level failure: the wire error it becomes, or `None` to propagate
+#: the driver's own exception because no Zikaron code describes it.
+type FailureMap = Callable[[aiosqlite.Error], Exception | None]
+
+#: The SQLite **primary** result codes that mean *the store was locked, try again* rather than
+#: *the operation failed*. `store_busy` is the one error the design tells a caller it may retry,
+#: so collapsing contention into anything terminal would take a retryable answer and make it look
+#: final. Primary codes rather than names, because SQLite reports *extended* results — a WAL
+#: reader whose snapshot went stale before it tried to write gets `SQLITE_BUSY_SNAPSHOT`, which is
+#: contention by every meaning that matters and matches no exact-name test for `SQLITE_BUSY`.
+_CONTENTION: Final = frozenset({sqlite3.SQLITE_BUSY, sqlite3.SQLITE_LOCKED})
+
+#: SQLite packs an extended result as the primary code in its low byte plus a subcode above it.
+_PRIMARY_RESULT_MASK: Final = 0xFF
+
+#: The two codes invariant 10's rejection carve-out applies to: a rejected call that still commits
+#: its audit event and, for a version conflict, the receipt for the record it returned. Every other
+#: `ZikaronError` a mutation can raise has written nothing at the point it raises, so it rolls back
+#: the ordinary way.
+_CARVE_OUT_CODES: Final = (ErrorCode.VERSION_CONFLICT, ErrorCode.NO_READ_RECEIPT)
+
+
+def propagate(_error: aiosqlite.Error) -> None:
+    """The `FailureMap` for work no wire error code describes: raise the driver's own exception.
+
+    Returning `None` has to be a deliberate choice rather than a default, because a raw driver
+    exception escaping unnamed leaves whoever serializes a response with no code to send. This is
+    that choice, made once, for every caller whose work is genuinely outside the wire contract —
+    the knowledge-base registry and each knowledge base's own tables, neither of which any RPC
+    returns a code about. A caller inside the contract names its failures instead.
+    """
+
+
+def is_contention(error: aiosqlite.Error) -> bool:
+    """Whether this driver failure means the store was locked rather than the work failed.
+
+    Read off the exception's own SQLite result code rather than its message text: the message is
+    prose that varies between builds, while the code is the contract SQLite itself publishes. An
+    exception carrying no result code — one constructed rather than raised by the driver — is not
+    contention by definition.
+    """
+    code = getattr(error, "sqlite_errorcode", None)
+    return isinstance(code, int) and (code & _PRIMARY_RESULT_MASK) in _CONTENTION
+
+
+async def commit_or_roll_back(db: aiosqlite.Connection, error: BaseException | None) -> None:
+    """Commit on success or on a carve-out rejection; roll back on anything else.
+
+    This is the one place that decides which of invariant 10's two outcomes applies, and it belongs
+    to the transaction-*owning* caller — never to a neutral `<verb>_within_transaction` core that
+    something else may have composed into a wider transaction. Only the owner structurally knows
+    that authorization ran with nothing else staged ahead of it, which is what makes committing a
+    rejection safe; a neutral core cannot see what its caller staged before calling it, so it must
+    never touch the transaction on any path.
+
+    The decision is made from the raised error's own **code**, not from where it was raised: a
+    `version_conflict` or `no_read_receipt` has deliberately written an audit event, and for the
+    conflict a receipt for the record it returned, so those two commit while the domain mutation
+    they rejected does not exist to commit.
+    """
+    if error is None or (isinstance(error, ZikaronError) and error.code in _CARVE_OUT_CODES):
+        await db.commit()
+    else:
+        await db.rollback()
+
+
+def _raise_mapped(error: aiosqlite.Error, failure: FailureMap) -> NoReturn:
+    """Raise the wire error this driver failure maps to, or re-raise the driver's own.
+
+    Annotated `NoReturn` because it is what lets the callers below be written without a trailing
+    `raise` that can never run: the type checker knows the branch terminates here, so there is no
+    unreachable statement to keep honest.
+    """
+    mapped = failure(error)
+    if mapped is None:
+        raise error
+    raise mapped from error
+
+
+async def finalize(
+    db: aiosqlite.Connection, error: BaseException | None, *, failure: FailureMap
+) -> None:
+    """Commit or roll back per invariant 10, leaving the connection out of a transaction either way.
+
+    Two obligations, and the second is the one easy to miss. A `COMMIT` that fails means the write
+    did not happen, so it must be reported rather than merely logged — and it can leave the
+    transaction *open*, with every staged row still visible on this connection. Reporting the
+    failure without also rolling back would leave a write already announced as failed sitting there
+    to be committed by whatever runs next, and would make the following call's `BEGIN` fail as a
+    nested one. So a failed finalization always attempts the rollback before raising.
+
+    **If that rollback also fails, the connection is closed.** At that point the transaction state
+    could not be repaired, so every later use of this connection risks committing the very write
+    this call has just reported as failed — a durable, silent wrong answer. Closing it makes the
+    next use of it fail loudly instead, which is the trade this whole layer is built on: one noisy
+    failure in preference to one quiet corruption. It does mean disrupting another holder of a
+    connection this function only borrows, and that is accepted rather than overlooked — the holder
+    gets an error it can act on, where the alternative is a memory the store claims not to have.
+
+    When this fires while another error is already propagating, the raise replaces it and keeps it
+    as the new error's context: the transaction's own outcome is the more useful answer, and
+    preserving only the first fault would leave the caller told nothing about the work's fate.
+    """
+    try:
+        await commit_or_roll_back(db, error)
+    except aiosqlite.Error as caught:
+        # Unconditional, because rolling back a connection that holds no transaction is a no-op and
+        # asking first would only add a branch that means nothing.
+        try:
+            await db.rollback()
+        except aiosqlite.Error:
+            with contextlib.suppress(Exception):
+                await db.close()
+        _raise_mapped(caught, failure)
+
+
+async def in_one_transaction[T](
+    db: aiosqlite.Connection, work: Work[T], *, failure: FailureMap
+) -> T:
+    """Run `work` inside one transaction, then commit or roll back per invariant 10.
+
+    Every driver-level failure goes through `failure`, and all three places one can occur are
+    covered: opening the transaction, the work itself, and finalizing. A raw `sqlite3` exception
+    escaping *unnamed* would leave whoever serializes the response with no code to send — which is
+    why `failure` returning `None` has to be a deliberate choice by that caller rather than the
+    default.
+
+    A `ZikaronError` raised by `work` passes through untouched, so a rejection keeps its own code —
+    and, for invariant 10's two carve-out codes, its committed audit trail.
+    """
+    try:
+        await db.execute("BEGIN")
+    except aiosqlite.Error as caught:
+        _raise_mapped(caught, failure)
+    error: BaseException | None = None
+    try:
+        result = await work(db)
+    except aiosqlite.Error as caught:
+        error = caught
+        _raise_mapped(caught, failure)
+    except BaseException as caught:
+        error = caught
+        raise
+    finally:
+        await finalize(db, error, failure=failure)
+    return result

zikaron/core/write/__init__.py

@@ -0,0 +1,33 @@
+"""The tool-facing write path: the remember, amend and retire verbs."""
+
+from zikaron.core.write.dedup import DedupPolicy, NearDuplicate, offer
+from zikaron.core.write.tools import (
+    Amended,
+    AmendOutcome,
+    Conflict,
+    Remembered,
+    RememberOutcome,
+    Retired,
+    RetireOutcome,
+    WriteCall,
+    amend,
+    remember,
+    retire,
+)
+
+__all__ = [
+    "AmendOutcome",
+    "Amended",
+    "Conflict",
+    "DedupPolicy",
+    "NearDuplicate",
+    "RememberOutcome",
+    "Remembered",
+    "RetireOutcome",
+    "Retired",
+    "WriteCall",
+    "amend",
+    "offer",
+    "remember",
+    "retire",
+]