zikaron 0.1.0__py3-none-any.whl

zikaron/core/retrieval/reads.py

@@ -0,0 +1,294 @@
+"""The two external read verbs: `search` (pull) and `surface` (push), each one transaction.
+
+`retrieval.md`'s two paths differ in three ways and share everything else. `surface` spends D12's
+five-gist budget on a user prompt and returns **ready-to-print text**, so the hook stays dumb;
+`search` is a deliberate act by the agent, returns structured rows, and is the only path allowed to
+widen eligibility to outright-retired rows. Neither reranks: D23's measured latency curve leaves
+exactly one affordable point on the push path, and reranking five candidates is operationally
+pointless.
+
+**Each call is one transaction**, and the instrumentation is inside it: both arms, the `chunk_count`
+the dense arm's coverage is compared against, the pool load, and the `event` rows. A read that
+writes its own instrumentation is a WAL snapshot upgrade, so a write committed by another process
+mid-call refuses the upgrade — which is `store_busy`, retryable, and exactly the stale-snapshot case
+`architecture.md` §Errors defines that code to cover. Any *other* driver failure has no Zikaron code
+and propagates: `index_failed` speaks of index maintenance and a rolled-back write, and a read
+performs neither.
+
+`search` mints **no receipt** and returns **no version**, which is the same fact twice. A row the
+agent has only seen as a gist is a row it may not write, and holding a version would imply a licence
+it has not earned — `architecture.md`: "`fetch` is the only way to license a write to a pre-existing
+row, absent an own-write or conflict response for that exact row in this session."
+"""
+
+import asyncio
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Final
+
+import aiosqlite
+
+from zikaron.core.errors import ErrorCode, RowState, ZikaronError
+from zikaron.core.events import (
+    ArmTermination,
+    QueryShape,
+    SearchDetail,
+    SurfaceCallDetail,
+    SurfaceDetail,
+)
+from zikaron.core.indexing.encoder import Encoder
+from zikaron.core.records import memory
+from zikaron.core.records.memory import CallParams, Tier
+from zikaron.core.retrieval import block, query
+from zikaron.core.retrieval.arms import ArmOutcome
+from zikaron.core.retrieval.eligibility import Consumer, Scope
+from zikaron.core.retrieval.query import ExternalQuery
+from zikaron.core.retrieval.ranking import RankedMemory
+from zikaron.core.retrieval.retrieve import RetrievalSettings, retrieve
+from zikaron.core.store import transactions
+
+#: `schema.md` §Bounds: the **output** budget, not retrieval depth. Per-arm depth is `fusion_depth`
+#: and lives in configuration precisely so that asking for a different number of results cannot
+#: change the ranking algorithm.
+LIMIT_MIN: Final = 1
+LIMIT_MAX: Final = 50
+LIMIT_DEFAULT: Final = 5
+
+
+@dataclass(frozen=True, slots=True)
+class ReadCall:
+    """What both read verbs hold constant: who is calling, the parameters, and the artifact.
+
+    The same bundling `IndexedCall` uses and for the same reason — every entry point needs all
+    three, none changes partway through a call, and keeping them apart invites a call site that
+    pairs one store's encoder with another's context.
+    """
+
+    ctx: CallParams
+    settings: RetrievalSettings
+    encoder: Encoder
+
+
+@dataclass(frozen=True, slots=True)
+class SearchHit:
+    """`zikaron_memory_search`'s per-row payload: exactly the seven fields the tool surface states.
+
+    `state` is here so triage can see a demoted row for what it is. `version` is not, and that is
+    the tool surface's own decision rather than an omission — see this module's docstring.
+    """
+
+    uuid: str
+    gist: str
+    tier: Tier
+    state: RowState
+    created_at: str
+    updated_at: str
+    superseded_by: str | None
+
+
+def _hit(ranked: RankedMemory) -> SearchHit:
+    row = ranked.row
+    return SearchHit(
+        uuid=row.uuid,
+        gist=row.gist,
+        tier=row.tier,
+        state=row.state,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+        superseded_by=row.superseded_by,
+    )
+
+
+def _reject_limit(limit: int) -> ZikaronError:
+    return ZikaronError(
+        ErrorCode.BOUNDS, field="limit", limit=f"{LIMIT_MIN}-{LIMIT_MAX}", actual=limit
+    )
+
+
+def _checked_limit(limit: int) -> int:
+    """`limit` if it is within `schema.md` §Bounds, else `bounds` — rung 1 of the ladder.
+
+    Checked here as well as at whatever boundary deserializes the request, for the reason
+    `EffectiveConfig` validates itself: "the only caller checks first" is a fact about today's call
+    sites rather than a property of this function, and an unchecked `limit` silently changes how
+    much of the pool a caller sees.
+    """
+    if not LIMIT_MIN <= limit <= LIMIT_MAX:
+        raise _reject_limit(limit)
+    return limit
+
+
+def _termination(dense: ArmOutcome, lexical: ArmOutcome) -> ArmTermination:
+    """Both arms' depth-and-reason pairs, as the one value the two read events share.
+
+    One function because the two kinds report the identical four fields in the identical way, and a
+    second transcription is how one kind's `dense_stop_reason` comes to mean something the other's
+    does not.
+    """
+    return ArmTermination(
+        dense_depth_reached=dense.depth_reached,
+        dense_stop_reason=dense.stop_reason,
+        lexical_depth_reached=lexical.depth_reached,
+        lexical_stop_reason=lexical.stop_reason,
+    )
+
+
+def _query_shape(external: ExternalQuery) -> QueryShape:
+    """What the query cost and whether either arm had to give something up to run it."""
+    return QueryShape(
+        query_tokens=external.query_tokens,
+        query_truncated=external.query_truncated,
+        lexical_skipped=external.prepared.lexical.skipped,
+    )
+
+
+async def _prepare(text: str, *, call: ReadCall) -> ExternalQuery:
+    """Build both arms of an external query, keeping the embedding off the event loop.
+
+    Outside any transaction, like the write path's own preflight and for the same reason: a cold
+    model load costs hundreds of milliseconds, and holding a transaction open across it would make
+    every concurrent writer's `busy_timeout` a function of model-load time.
+    """
+    return await asyncio.to_thread(
+        query.external_query,
+        text,
+        encoder=call.encoder,
+        prefix=call.settings.embed_prefix_query,
+        max_terms=call.settings.fts_query_max_terms,
+    )
+
+
+def _failure_map(verb: str) -> transactions.FailureMap:
+    """Name contention `store_busy` and propagate everything else, per `architecture.md` §Errors.
+
+    A read has no `index_failed`: that code's contract names index maintenance and a rolled-back
+    write, so reusing it here would be a lie in both halves, and inventing a `read_failed` would add
+    a code no client can act on differently.
+    """
+    return lambda error: (
+        ZikaronError(ErrorCode.STORE_BUSY, verb=verb) if transactions.is_contention(error) else None
+    )
+
+
+async def search(
+    db: aiosqlite.Connection,
+    *,
+    text: str,
+    call: ReadCall,
+    limit: int = LIMIT_DEFAULT,
+    include_retired: bool = False,
+) -> tuple[SearchHit, ...]:
+    """The pull path: fuse both arms over `text` and return the best `limit` memories.
+
+    `include_retired` widens eligibility to rows nobody replaced — the deliberate-archaeology case —
+    and they arrive demoted rather than ranked normally, because it widens *what may appear*, not
+    *what is currently true*. An empty store returns an empty tuple, which is an answer rather than
+    an error.
+
+    Emits exactly one `search` event, inside the same transaction as the read it describes.
+
+    Raises:
+        ZikaronError: `BOUNDS` if `limit` is outside 1-50; `STORE_BUSY` if the store was locked or
+            the read's snapshot went stale before its event could be written, which the caller may
+            retry; `BAD_SUPERSESSION` if the candidate pool's supersession edges are cyclic.
+    """
+    budget = _checked_limit(limit)
+    external = await _prepare(text, call=call)
+
+    async def work(connection: aiosqlite.Connection) -> tuple[SearchHit, ...]:
+        retrieved = await retrieve(
+            connection,
+            query=external.prepared,
+            scope=Scope(Consumer.SEARCH, include_retired=include_retired),
+            settings=call.settings,
+        )
+        returned = retrieved.pool[:budget]
+        await memory.log_event(
+            connection,
+            ctx=call.ctx,
+            detail=SearchDetail(
+                query_chars=len(text),
+                limit=budget,
+                fusion_depth=call.settings.fusion_depth,
+                arms=_termination(retrieved.dense, retrieved.lexical),
+                query=_query_shape(external),
+                include_retired=include_retired,
+                n_returned=len(returned),
+                uuids=tuple(ranked.row.uuid for ranked in returned),
+            ),
+            memory_uuid=None,
+        )
+        return tuple(_hit(ranked) for ranked in returned)
+
+    return await transactions.in_one_transaction(db, work, failure=_failure_map("search"))
+
+
+async def _log_surface(
+    db: aiosqlite.Connection, *, rows: Sequence[RankedMemory], call: ReadCall
+) -> None:
+    """One `surface` row per returned memory, after the call's own `surface_call` row.
+
+    Zero rows when nothing was eligible, which is why `surface_call` exists at all: without a
+    per-call row a quiet push and a push that never happened would be the same absence of evidence.
+    """
+    for position, ranked in enumerate(rows, start=1):
+        await memory.log_event(
+            db,
+            ctx=call.ctx,
+            detail=SurfaceDetail(
+                rank=position,
+                fused_score=ranked.fused_score,
+                demoted=ranked.demoted,
+                demotion=ranked.row.demotion,
+            ),
+            memory_uuid=ranked.row.uuid,
+        )
+
+
+async def surface(
+    db: aiosqlite.Connection, *, prompt: str, call: ReadCall, limit: int = LIMIT_DEFAULT
+) -> str:
+    """The push path: the block to inject for one user message, or the empty string.
+
+    Takes no `include_retired`: `schema.md` gives it to `search` alone, so push's predicate is the
+    base one — under which superseded rows are eligible and demoted, which is what D25's measurement
+    requires and what the block's label then explains.
+
+    Emits one `surface_call` event always, including when nothing was returned, followed by one
+    `surface` event per returned memory sharing its `op_id`.
+
+    Returns:
+        Ready-to-print text, or `""` when nothing was eligible — no header, no empty block.
+
+    Raises:
+        ZikaronError: as `search`, minus `include_retired`'s widening.
+    """
+    budget = _checked_limit(limit)
+    external = await _prepare(prompt, call=call)
+
+    async def work(connection: aiosqlite.Connection) -> str:
+        retrieved = await retrieve(
+            connection,
+            query=external.prepared,
+            scope=Scope(Consumer.SURFACE),
+            settings=call.settings,
+        )
+        returned = retrieved.pool[:budget]
+        await memory.log_event(
+            connection,
+            ctx=call.ctx,
+            detail=SurfaceCallDetail(
+                prompt_chars=len(prompt),
+                limit=budget,
+                fusion_depth=call.settings.fusion_depth,
+                arms=_termination(retrieved.dense, retrieved.lexical),
+                query=_query_shape(external),
+                n_returned=len(returned),
+                n_demoted=sum(1 for ranked in returned if ranked.demoted),
+            ),
+            memory_uuid=None,
+        )
+        await _log_surface(connection, rows=returned, call=call)
+        return block.render(returned)
+
+    return await transactions.in_one_transaction(db, work, failure=_failure_map("surface"))

zikaron/core/retrieval/retrieve.py

@@ -0,0 +1,158 @@
+"""The one retrieval algorithm, run by all five consumers, composable into a caller's transaction.
+
+`retrieval.md`: "Every read path — push, pull, write-time dedup, consolidation anchors, orphan edges
+— uses the same **base** predicate and the same algorithm, and adds at most one filter." This module
+is that algorithm: both arms, the pool load, and the ranking, in that order and nowhere else.
+
+It **neither begins nor commits a transaction**, for the same reason `records` and `indexing` split
+their verbs that way: D15's dedup search has to run inside the same transaction as the `remember` it
+reports on, since it queries the vectors that write has just inserted. `reads.py` owns the
+transaction for the two external verbs; the internal-query consumers own theirs.
+
+What the caller must guarantee is the one thing this module cannot check for itself: that a read
+transaction is already open. Both arms and the pool load then see one snapshot, which is what makes
+the dense arm's coverage comparison a statement about a single store rather than about two.
+"""
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Final, Self
+
+import aiosqlite
+
+from zikaron.core.config.resolution import EffectiveConfig
+from zikaron.core.records.memory import Tier
+from zikaron.core.retrieval import arms, ranking
+from zikaron.core.retrieval.arms import ArmOutcome
+from zikaron.core.retrieval.eligibility import Scope
+from zikaron.core.retrieval.query import PreparedQuery
+from zikaron.core.retrieval.ranking import Penalties, PoolRow, RankedMemory
+
+#: `memory`'s columns as the read path needs them, in the fixed order `_to_pool_row` unpacks. One
+#: constant rather than a literal per statement, so the row shape has one reader. `content` and
+#: `version` are absent by design — see `PoolRow`.
+_POOL_COLUMNS: Final = "uuid, tier, gist, active, superseded_by, created_at, updated_at"
+
+
+@dataclass(frozen=True, slots=True)
+class RetrievalSettings:
+    """Every configuration value the read algorithm consumes, resolved once.
+
+    Bundled because they travel together for the life of a store handle and because `event` rows
+    written by one call must all report the parameters that produced them — `architecture.md` reads
+    the config once at startup for exactly that reason, and a per-call re-read would let two events
+    of one run disagree about the ranking they describe.
+    """
+
+    fusion_depth: int
+    rrf_k: int
+    chunk_overfetch: int
+    penalties: Penalties
+    fts_query_max_terms: int
+    embed_prefix_query: str
+
+    @classmethod
+    def from_config(cls, config: EffectiveConfig) -> Self:
+        """Read the `[retrieval]` and `[embedding]` keys this algorithm is parameterized by."""
+        return cls(
+            fusion_depth=config.get_int("fusion_depth"),
+            rrf_k=config.get_int("rrf_k"),
+            chunk_overfetch=config.get_int("chunk_overfetch"),
+            penalties=Penalties(
+                superseded=config.get_float("supersession_penalty"),
+                retired=config.get_float("retired_penalty"),
+            ),
+            fts_query_max_terms=config.get_int("fts_query_max_terms"),
+            embed_prefix_query=config.get_str("embed_prefix_query"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Retrieved:
+    """The full ordered candidate pool, plus what each arm reported about how far it got.
+
+    **Not cut to any output budget.** The cut is the caller's last step, after the supersession
+    repair, which is what lets the repair promote a replacement into the returned set rather than
+    only reshuffling what already made it.
+    """
+
+    pool: tuple[RankedMemory, ...]
+    dense: ArmOutcome
+    lexical: ArmOutcome
+
+
+def _to_pool_row(row: Sequence[object]) -> PoolRow:
+    uuid, tier, gist, active, superseded_by, created_at, updated_at = row
+    return PoolRow(
+        uuid=str(uuid),
+        tier=Tier(str(tier)),
+        gist=str(gist),
+        active=bool(active),
+        superseded_by=None if superseded_by is None else str(superseded_by),
+        created_at=str(created_at),
+        updated_at=str(updated_at),
+    )
+
+
+async def _load_pool_rows(db: aiosqlite.Connection, uuids: Sequence[str]) -> Mapping[str, PoolRow]:
+    """The row facts for every uuid either arm returned, in one statement.
+
+    A lookup by uuid rather than a predicate path, so it adds no filter and is not one of the five
+    consumers: eligibility was already decided inside each arm's own query, against the same
+    snapshot this read sees.
+    """
+    if not uuids:
+        return {}
+    placeholders = ", ".join("?" for _ in uuids)
+    sql = f"SELECT {_POOL_COLUMNS} FROM memory WHERE uuid IN ({placeholders})"  # noqa: S608 — placeholders only; every uuid is a bound parameter.
+    rows = await db.execute_fetchall(sql, tuple(uuids))
+    loaded = [_to_pool_row(tuple(row)) for row in rows]
+    return {row.uuid: row for row in loaded}
+
+
+async def retrieve(
+    db: aiosqlite.Connection,
+    *,
+    query: PreparedQuery,
+    scope: Scope,
+    settings: RetrievalSettings,
+) -> Retrieved:
+    """Run both arms over `scope`, fuse them, and return the whole ordered pool.
+
+    Assumes an open transaction. The lexical arm is skipped — and says so, with both of its
+    instrumentation fields null — when the query yielded no surviving term; the dense arm always
+    runs, so a prompt of pure punctuation still gets an answer.
+
+    Raises:
+        ZikaronError: `BAD_SUPERSESSION` with `reason='cycle'` if the pool's supersession edges
+            cannot be topologically ordered, which invariant 6 makes impossible in a well-formed
+            store.
+    """
+    dense = await arms.dense_arm(
+        db,
+        vector=query.vector,
+        scope=scope,
+        fusion_depth=settings.fusion_depth,
+        chunk_overfetch=settings.chunk_overfetch,
+    )
+    expression = query.lexical.expression
+    lexical = (
+        ArmOutcome.skipped(fusion_depth=settings.fusion_depth)
+        if expression is None
+        else await arms.lexical_arm(
+            db, expression=expression, scope=scope, fusion_depth=settings.fusion_depth
+        )
+    )
+    seen: dict[str, None] = {}
+    for outcome in (dense, lexical):
+        for row in outcome.rows:
+            seen.setdefault(row.uuid, None)
+    rows = await _load_pool_rows(db, tuple(seen))
+    pool = ranking.rank(
+        dense=dense,
+        lexical=lexical,
+        rows=rows,
+        rrf_k=settings.rrf_k,
+        penalties=settings.penalties,
+    )
+    return Retrieved(pool=pool, dense=dense, lexical=lexical)

zikaron/core/retrieval/similarity.py

@@ -0,0 +1,87 @@
+"""`s(X → Y)`: the one directed score all three cosine cutoffs are defined over.
+
+`schema.md` §"Configuration keys" defines it once — **the best cosine between X's first chunk and
+any chunk of Y** — and three keys threshold it: `dedup_threshold` on `s(new row → candidate)`,
+`anchor_cutoff` on `s(entry → record)`, and `orphan_edge_cutoff` on the symmetrized
+`min(s(A → B), s(B → A))`. One definition, so one implementation: a second one that rounded
+differently would put a pair on opposite sides of a floor depending on which caller asked.
+
+**It is a mathematical fact about two rows' stored vectors, not a by-product of a search.** The
+fused pool decides *which* rows are candidates at all; this decides whether each clears its floor.
+A row the dense arm's overfetch loop placed within `fusion_depth` already carries its own exact
+minimum distance, because that loop finds the true nearest chunk among however many it probed and
+stops only once it has proven a surplus or covered the index — so that value needs no refining. A
+row the **lexical** arm alone surfaced carries none, and closing that gap is what the batched
+statement below is for. Leaving it open was a real defect once: it silently excluded every
+lexical-only candidate from a threshold test regardless of its true score.
+
+**The arithmetic is the pinned extension's, never ours.** `vec_distance_L2` is the same native
+function `vec0`'s KNN path evaluates, measured bit-identical on the same stored vectors. Decoding
+float32 coordinates into Python's binary64 and re-summing them by hand has different rounding
+characteristics, which is exactly how a pair sitting on a floor comes to clear it under one arm's
+scoring and not the other's. Nor the ranked `MATCH`/KNN operator: `vec0`'s `k` is a **global** rank
+cutoff, so aiming it at one named memory's chunks needs a `k` covering however much of the index
+ranks ahead of them, and can return nothing belonging to the memory it was aimed at.
+
+Every cosine here is exact **only for unit vectors**, which is why `query.QueryOrigin` exists: the
+write path L2-normalizes the corpus and an internal query reuses a stored chunk vector, so both
+sides are unit length. No external query is ever thresholded.
+"""
+
+from collections.abc import Mapping, Sequence
+
+import aiosqlite
+
+from zikaron.core.retrieval.arms import cosine_from_distance
+from zikaron.core.retrieval.query import PreparedQuery
+from zikaron.core.retrieval.ranking import RankedMemory
+
+
+async def exact_directed_cosines(
+    db: aiosqlite.Connection, memory_uuids: Sequence[str], *, query_vector: bytes
+) -> Mapping[str, float]:
+    """`s(query → Y)` for each of `memory_uuids`, over every one of that row's own stored chunks.
+
+    One statement, grouped by `memory_uuid`, over exactly the rows named — bounded by their own
+    chunk counts rather than by store size, and never one statement per row.
+
+    Assumes the caller's own open transaction, so the vectors read are the same snapshot the
+    caller's other reads saw.
+
+    Returns:
+        A cosine per uuid that has at least one stored vector. A uuid absent from the result had
+        none — unreachable for any active row, since invariant 12 pairs every one with a chunk, and
+        reported as absence rather than as an invented distance.
+    """
+    if not memory_uuids:
+        return {}
+    placeholders = ", ".join("?" for _ in memory_uuids)
+    sql = (
+        "SELECT c.memory_uuid, MIN(vec_distance_L2(v.embedding, ?)) "  # noqa: S608 — placeholders only; every uuid is a bound parameter.
+        "FROM memory_chunk c "
+        "JOIN memory_vec v ON v.rowid = c.chunk_id "
+        f"WHERE c.memory_uuid IN ({placeholders}) "
+        "GROUP BY c.memory_uuid"
+    )
+    rows = await db.execute_fetchall(sql, (query_vector, *memory_uuids))
+    return {str(uuid): cosine_from_distance(float(distance)) for uuid, distance in rows}
+
+
+async def directed_cosines(
+    db: aiosqlite.Connection, pool: Sequence[RankedMemory], *, query: PreparedQuery
+) -> Mapping[str, float]:
+    """`s(query → Y)` for every row of a fused pool, exact for all of them rather than for some.
+
+    Reuses the dense arm's own rolled-up minimum distance where it has one and batches a single
+    further statement for the rows only the lexical arm surfaced — one call for all of them, not
+    one each, because the cost of the missing case must not scale with how many rows are missing it.
+    """
+    cosines: dict[str, float] = {}
+    lexical_only: list[str] = []
+    for ranked in pool:
+        if ranked.best_distance is not None:
+            cosines[ranked.row.uuid] = cosine_from_distance(ranked.best_distance)
+        else:
+            lexical_only.append(ranked.row.uuid)
+    cosines.update(await exact_directed_cosines(db, lexical_only, query_vector=query.vector))
+    return cosines

zikaron/core/signals/__init__.py

@@ -0,0 +1,34 @@
+"""D30's six write-policy signals, each as executable SQL over the committed `event` log."""
+
+from zikaron.core.signals.contention import ConflictRate, conflict_rate
+from zikaron.core.signals.dedup import DedupOutcome, DedupResolution, dedup_resolution
+from zikaron.core.signals.repair import RepairCounts, amend_after_surface
+from zikaron.core.signals.retirement import RetireCount, retire_count
+from zikaron.core.signals.sessions import LinkCoverage, link_coverage, linked_session_ids
+from zikaron.core.signals.writes import (
+    SessionWrites,
+    WriteSizeDistribution,
+    WritesPerSession,
+    write_size_distribution,
+    writes_per_session,
+)
+
+__all__ = [
+    "ConflictRate",
+    "DedupOutcome",
+    "DedupResolution",
+    "LinkCoverage",
+    "RepairCounts",
+    "RetireCount",
+    "SessionWrites",
+    "WriteSizeDistribution",
+    "WritesPerSession",
+    "amend_after_surface",
+    "conflict_rate",
+    "dedup_resolution",
+    "link_coverage",
+    "linked_session_ids",
+    "retire_count",
+    "write_size_distribution",
+    "writes_per_session",
+]

zikaron/core/signals/contention.py

@@ -0,0 +1,106 @@
+"""Signal 6 — version-conflict and no-receipt rate, over observable receipt-gated mutation calls.
+
+`schema.md` §"D30's six signals, as queries", row 6: `count(DISTINCT op_id)` over
+`kind='version_conflict'`, and **separately** over `kind='no_receipt'` — never summed, because a
+conflict means "read something stale" and a missing receipt means "wrote without reading", and
+collapsing the two into one number would erase the distinction the design states as the whole
+reason for reporting them side by side. Both numerators dedup by `op_id` because a single rejected
+call can emit several rows of one kind (`schema.md`: "one row per conflicting uuid" / "one row per
+uuid lacking a receipt"), and a rate whose two sides use different units is not a rate at all — a
+three-row conflicting `merge` naively counted as 3 rows over a 1-call denominator would report 300%.
+
+The denominator is `count(DISTINCT op_id)` over three **disjoint** terms: committed calls of the
+five receipt-gated verbs (`amend`, `retire`, `merge`, `promote`, `discard`), plus conflicted calls,
+plus no-receipt calls. Disjoint because a call is rejected at the first rung holding any offender,
+and the version rung precedes the receipt rung in both ladders (invariant 9), so no call emits both
+kinds; and a rejected call commits no mutation, so no call is both committed and rejected.
+`remember` is excluded from every term **by construction, not filtered out**: it names no
+pre-existing row, so neither ladder rung applies to it and it cannot appear in either numerator —
+admitting it into the denominator would divide contention by write volume, which signal 1 already
+measures on purpose.
+"""
+
+from dataclasses import dataclass
+
+import aiosqlite
+
+from zikaron.core.events import EventKind
+
+#: The five verbs that name a pre-existing row at a version, and so are the only calls a version
+#: conflict or a missing receipt can be rejected from. `schema.md`'s own list, transcribed once.
+_RECEIPT_GATED_KINDS: tuple[EventKind, ...] = (
+    EventKind.AMEND,
+    EventKind.RETIRE,
+    EventKind.MERGE,
+    EventKind.PROMOTE,
+    EventKind.DISCARD,
+)
+
+_COUNT_DISTINCT_OP_IDS = "SELECT COUNT(DISTINCT op_id) FROM event WHERE kind IN ({placeholders})"
+
+
+@dataclass(frozen=True, slots=True)
+class ConflictRate:
+    """Both numerators and the shared denominator, each already a call count via `DISTINCT op_id`.
+
+    `n_version_conflict` and `n_no_receipt` are reported as a pair, never summed — matching the
+    design's own instruction not to collapse them.
+    """
+
+    n_version_conflict: int
+    n_no_receipt: int
+    n_committed: int
+
+    def __post_init__(self) -> None:
+        if self.n_version_conflict < 0 or self.n_no_receipt < 0 or self.n_committed < 0:
+            raise ValueError("call counts must be non-negative")
+
+    @property
+    def n_calls(self) -> int:
+        """The full denominator: committed plus both rejection populations, which are disjoint by
+        the ladder ordering the design states, so this sum double-counts nothing."""
+        return self.n_committed + self.n_version_conflict + self.n_no_receipt
+
+    @property
+    def version_conflict_rate(self) -> float | None:
+        """`n_version_conflict / n_calls`, or `None` over an empty denominator.
+
+        Bounded in `[0, 1]` by construction: `n_version_conflict` is one disjoint term the
+        denominator sums, so it can never exceed the sum it is one addend of.
+        """
+        if self.n_calls == 0:
+            return None
+        return self.n_version_conflict / self.n_calls
+
+    @property
+    def no_receipt_rate(self) -> float | None:
+        """`n_no_receipt / n_calls`, or `None` over an empty denominator. Bounded as above."""
+        if self.n_calls == 0:
+            return None
+        return self.n_no_receipt / self.n_calls
+
+
+async def conflict_rate(db: aiosqlite.Connection) -> ConflictRate:
+    """The version-conflict and no-receipt rates over every observable receipt-gated call.
+
+    Three independent `COUNT(DISTINCT op_id)` queries rather than one query with three `CASE`
+    branches, because each term counts distinct `op_id`s **within its own `kind` filter** — a call
+    that emitted three `version_conflict` rows must count once in that term and the committed term
+    must not see it at all, which a single shared `GROUP BY op_id` would make harder to state
+    correctly than three separate, disjoint-by-ladder-ordering counts.
+    """
+    committed_placeholders = ", ".join("?" for _ in _RECEIPT_GATED_KINDS)
+    committed_sql = _COUNT_DISTINCT_OP_IDS.format(placeholders=committed_placeholders)
+    committed_rows = list(
+        await db.execute_fetchall(committed_sql, tuple(kind.value for kind in _RECEIPT_GATED_KINDS))
+    )
+    conflict_sql = _COUNT_DISTINCT_OP_IDS.format(placeholders="?")
+    conflict_rows = list(
+        await db.execute_fetchall(conflict_sql, (EventKind.VERSION_CONFLICT.value,))
+    )
+    no_receipt_rows = list(await db.execute_fetchall(conflict_sql, (EventKind.NO_RECEIPT.value,)))
+    return ConflictRate(
+        n_version_conflict=int(conflict_rows[0][0]),
+        n_no_receipt=int(no_receipt_rows[0][0]),
+        n_committed=int(committed_rows[0][0]),
+    )