zikaron 0.1.0__py3-none-any.whl

zikaron/core/signals/writes.py

@@ -0,0 +1,200 @@
+"""Signals 1 and 5 — writes per session and the zero-write rate; the write size distribution.
+
+**Signal 1.** `schema.md` §"D30's six signals, as queries", row 1: per `session_id`,
+`count(kind='remember')` and `count(kind='amend')` reported separately and summed, over a
+denominator of `count(DISTINCT session_id)` restricted to **linked** sessions (`signals.sessions`) —
+every session the service saw through both clients, whether or not it wrote. A linked session with a
+`surface_call` and no `remember`/`amend` is a zero-write session; an unlinked one is excluded rather
+than counted as zero-write, because an unlinked *writing* session would otherwise be miscounted as
+one — the exact failure `write-policy.md` §3 names as the one to engineer against, since it biases
+the rate in the direction that would confirm the under-writing prior this signal exists to test.
+
+Reports **both halves of D11's loop from the write side**: `remember` volume alone answers "is the
+agent recording at all", and the retire signal (`signals.retirement`) answers the repair half this
+one does not — a session with plenty of `remember` and no `amend` is not yet evidence that repair
+never fires, since a surfaced memory repaired by outright `retire` is legitimate under D11 and D16
+and belongs to a different signal.
+
+**Signal 5**, kept in this module rather than a separate one: both signals aggregate the same
+authored-write events (`remember`, `amend`, and the authoring rows of `merge`/`promote`), and a
+write's size is one further fact about the same write population signal 1 already counts — not a
+fact about a different event population.
+"""
+
+from dataclasses import dataclass
+
+import aiosqlite
+
+from zikaron.core.events import EventKind
+from zikaron.core.signals.sessions import LinkCoverage, link_coverage, linked_session_ids
+
+_PER_SESSION_COUNTS = """
+SELECT session_id,
+       SUM(CASE WHEN kind = ? THEN 1 ELSE 0 END) AS n_remember,
+       SUM(CASE WHEN kind = ? THEN 1 ELSE 0 END) AS n_amend
+FROM event
+WHERE session_id IN ({placeholders})
+  AND kind IN (?, ?)
+GROUP BY session_id
+"""
+#: The two `AS` labels above are documentation, not a wire the row is read through:
+#: `writes_per_session` below unpacks each row positionally (`session_id, n_remember, n_amend`),
+#: so which count is `n_remember` is decided by which `?` value binds to the first `CASE WHEN` at
+#: parameter-construction time, never by the label text. Stated here because that makes the label
+#: itself unable to cause or catch a defect, which a mutation on it would otherwise look like.
+
+
+@dataclass(frozen=True, slots=True)
+class SessionWrites:
+    """One linked session's write counts. A session absent from the per-session query made
+    neither call, so both counts are `0` for it — the zero-write case this signal exists to find."""
+
+    session_id: str
+    n_remember: int
+    n_amend: int
+
+    @property
+    def n_writes(self) -> int:
+        """`remember` and `amend` summed, per the design's "reported separately and summed"."""
+        return self.n_remember + self.n_amend
+
+    @property
+    def wrote_nothing(self) -> bool:
+        return self.n_writes == 0
+
+
+@dataclass(frozen=True, slots=True)
+class WritesPerSession:
+    """The full signal: every linked session's write counts, plus the coverage the cross-client
+    join depends on.
+
+    `n_linked_sessions` is the rate's own denominator, restated on the type rather than left to be
+    recomputed from `len(sessions)` — `sessions` already omits nothing, so the two do agree, but a
+    caller reading only this field should not have to know that to trust it names the denominator.
+    """
+
+    sessions: tuple[SessionWrites, ...]
+    link: LinkCoverage
+
+    @property
+    def n_linked_sessions(self) -> int:
+        return len(self.sessions)
+
+    @property
+    def n_zero_write_sessions(self) -> int:
+        return sum(1 for session in self.sessions if session.wrote_nothing)
+
+    @property
+    def zero_write_rate(self) -> float | None:
+        """`n_zero_write_sessions / n_linked_sessions`, or `None` over an empty denominator.
+
+        Bounded in `[0, 1]` by construction: the numerator counts a subset of the exact rows the
+        denominator counts (a session cannot be zero-write and also outside `sessions`, since every
+        linked session appears in `sessions` whether or not it wrote), so it can never exceed the
+        denominator it is drawn from.
+        """
+        if self.n_linked_sessions == 0:
+            return None
+        return self.n_zero_write_sessions / self.n_linked_sessions
+
+    @property
+    def total_remember(self) -> int:
+        return sum(session.n_remember for session in self.sessions)
+
+    @property
+    def total_amend(self) -> int:
+        return sum(session.n_amend for session in self.sessions)
+
+
+async def writes_per_session(db: aiosqlite.Connection) -> WritesPerSession:
+    """Every linked session's `remember`/`amend` counts, with link coverage.
+
+    A linked session that made no `remember` and no `amend` call is absent from the SQL result
+    (`GROUP BY` produces no row for a group with nothing to group), so it is added back explicitly
+    with both counts `0` — the join must not silently drop the case this whole signal is for.
+    """
+    linked = await linked_session_ids(db)
+    counted: dict[str, SessionWrites] = {}
+    if linked:
+        placeholders = ", ".join("?" for _ in linked)
+        sql = _PER_SESSION_COUNTS.format(placeholders=placeholders)
+        params = (
+            EventKind.REMEMBER.value,
+            EventKind.AMEND.value,
+            *linked,
+            EventKind.REMEMBER.value,
+            EventKind.AMEND.value,
+        )
+        rows = await db.execute_fetchall(sql, params)
+        for session_id, n_remember, n_amend in rows:
+            counted[str(session_id)] = SessionWrites(
+                session_id=str(session_id), n_remember=int(n_remember), n_amend=int(n_amend)
+            )
+    sessions = tuple(
+        counted.get(session_id, SessionWrites(session_id=session_id, n_remember=0, n_amend=0))
+        for session_id in sorted(linked)
+    )
+    return WritesPerSession(sessions=sessions, link=await link_coverage(db))
+
+
+# ---------------------------------------------------------------------------
+# Signal 5 — write size distribution
+# ---------------------------------------------------------------------------
+#
+# Kept in this module rather than a separate one: both signals aggregate the same authored-write
+# events (`remember`, `amend`, and the authoring rows of `merge`/`promote`), and a write's size is
+# one further fact about the same write count 1 already found — not a fact about a different event
+# population.
+
+_AUTHORED_SIZES = """
+SELECT id, json_extract(detail, '$.token_count') AS token_count
+FROM event
+WHERE kind IN (?, ?)
+UNION ALL
+SELECT id, json_extract(detail, '$.token_count') AS token_count
+FROM event
+WHERE kind = ? AND json_extract(detail, '$.role') = 'target'
+UNION ALL
+SELECT id, json_extract(detail, '$.token_count') AS token_count
+FROM event
+WHERE kind = ? AND json_extract(detail, '$.role') IN ('created', 'flipped')
+ORDER BY id
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class WriteSizeDistribution:
+    """`token_count` from every write that authored prose, in `event.id` order.
+
+    A distribution, not a rate (`schema.md`: "n/a (a distribution, not a rate)"), so this carries
+    the raw values rather than a summary statistic — histogramming, percentiles or a mean are a
+    caller's choice, and baking one in would answer a question about the shape of the data with a
+    single number chosen before the shape was known. Ordered by the underlying `event.id` (the
+    query's own `ORDER BY`, applied over the whole three-branch `UNION`) so two reads of one store
+    return byte-identical results, matching every other signal's own determinism guarantee rather
+    than leaving `UNION ALL`'s branch order to be assumed.
+    """
+
+    values: tuple[int, ...]
+
+
+async def write_size_distribution(db: aiosqlite.Connection) -> WriteSizeDistribution:
+    """`token_count` from every write that authored prose: `remember`, `amend`, a merge's `target`
+    row, and a promotion's `created`/`flipped` row.
+
+    An absorbed `merge` row and every non-`created`/`flipped` `promote` row authored no prose, so
+    the design states their `token_count` as null (`schema.md`'s nullability table) rather than
+    absent — filtering by `role` here is what a query over `token_count IS NOT NULL` would do
+    implicitly, made explicit because the role is the actual reason those rows are excluded, not an
+    incidental correlate of it.
+    """
+    rows = await db.execute_fetchall(
+        _AUTHORED_SIZES,
+        (
+            EventKind.REMEMBER.value,
+            EventKind.AMEND.value,
+            EventKind.MERGE.value,
+            EventKind.PROMOTE.value,
+        ),
+    )
+    return WriteSizeDistribution(values=tuple(int(token_count) for _id, token_count in rows))

zikaron/core/store/__init__.py

@@ -0,0 +1 @@
+"""Schema creation, open/close, migration posture, and file permissions."""

zikaron/core/store/connection.py

@@ -0,0 +1,202 @@
+"""How Zikaron opens a SQLite database, for every database it owns.
+
+Two live today — the memory store and one file per knowledge base — and they differ in their
+schemas, not in how a connection is established: both need `sqlite-vec` loaded, both need their own
+pragmas applied, and both need a failure between connecting and finishing that setup to close the
+connection rather than abandon it. Keeping one implementation is what stops the second database
+growing a subtly different opener; the alternative was already measured to be expensive in this
+project, where an unclosed `aiosqlite` connection keeps its process alive with nothing printed.
+
+**Two things vary between callers, and both are parameters rather than assumptions.**
+
+- **How a failed *connect* is named** — the same split `transactions.FailureMap` makes, for the same
+  reason. A memory store that will not open is a configuration error naming the store directory; a
+  knowledge-base database that will not open is a reportable state of one corpus, and not an error
+  at all when the file is simply absent.
+- **Which pragmas to apply.** The two schemas do not want the same set, and the difference is
+  load-bearing rather than cosmetic: the knowledge schema declares no foreign key anywhere, so
+  `PRAGMA foreign_keys = ON` there would advertise a cascade that does not exist — which is the
+  precise wrong mental model its design spends a paragraph refusing. The set is therefore supplied
+  by whoever owns the schema, and there is deliberately **no default**: a caller that did not say
+  would get whichever set this module happened to import, which is exactly how a connection came to
+  carry a pragma its own design forbids.
+
+Everything *after* the connect — the extension, the pragmas — raises the driver's own error for
+every caller, because a database that opened and then refused a pragma is the same fault whoever
+asked for it.
+"""
+
+import asyncio
+import threading
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Final
+from urllib.parse import quote
+
+import aiosqlite
+import sqlite_vec
+
+#: How a caller names a failed connect. Takes the driver's error and returns the exception to
+#: raise in its place, with the original kept as the cause.
+type ConnectFailure = Callable[[aiosqlite.Error], Exception]
+
+
+#: How long to wait for the worker thread of a *failed* connect to finish. It is draining a single
+#: queued sentinel, which takes microseconds; this bound exists so a wedged thread cannot hang a
+#: caller rather than as a duration anything is expected to spend.
+_ABANDONED_WORKER_JOIN_SECONDS: Final = 5.0
+
+
+async def join_abandoned_worker(connector: aiosqlite.Connection) -> None:
+    """Wait for the worker thread of a connect that failed, so it cannot outlive this event loop.
+
+    **Why this is needed, reproduced before it was written.** `aiosqlite.connect()` starts a worker
+    thread, and a failed connect leaves it mid-shutdown: the library's own failure path calls
+    `stop()`, which *queues* a sentinel and returns without waiting. If the event loop closes before
+    the thread drains that sentinel — which is exactly what happens when a caller catches the error
+    and returns, the situation every caller of this function is in — the thread tries to deliver the
+    sentinel's result through `call_soon_threadsafe` on a dead loop, raises `RuntimeError: Event
+    loop is closed`, fails identically while trying to report that, and dies with the exception
+    unhandled. A test run surfaces it as `PytestUnhandledThreadExceptionWarning`.
+
+    **What that loses is the thread, and nothing else.** A connect that *failed* never produced a
+    `sqlite3.Connection` for anybody to drop — the driver raised instead of returning one, and the
+    stop the library queues behind it therefore finds no handle to close either. So this path
+    cannot leave a database open, and an `unclosed database` warning seen near it has a different
+    cause. *Superseded, in place: this docstring previously said the dropped connection "surfaces
+    separately as `ResourceWarning: unclosed database`", and the surrounding record called it one
+    bug with two symptoms. It is one symptom; the warnings counted alongside it came from raw
+    `sqlite3` connections in test helpers and were fixed separately.*
+
+    The number this is worth is in `test_store_connection.py`, which keeps the measurement as a
+    test because nothing else in the gate can tell the two states apart: coverage sees both
+    branches execute either way, and the matrix's warning filter errors only on deprecations.
+
+    The join runs off the event loop, so a thread that never exits costs this bound rather than
+    blocking the loop. `_thread` is private, and deliberately so — the library exposes no other way
+    to wait for a worker it has already told to stop, and `stop()`'s own return value is a future on
+    the loop that is about to close, which is the thing that cannot be relied on here.
+
+    **Absence is tolerated for a substitute only, and the type is what draws that line.** A test
+    that replaces `aiosqlite.connect` gets a plain coroutine with no worker behind it, and there is
+    genuinely nothing to wait for; the first version of this assumed the attribute and broke such a
+    test, which is how the tolerance was arrived at. A real `aiosqlite.Connection` that stopped
+    keeping its thread here is the opposite case — the wait would quietly become a no-op and the
+    defect would come back with nothing to announce it — so the check is on the type rather than on
+    mere presence, and `test_store_connection.py` pins the attribute against the installed library
+    so a version that moves it turns the matrix red instead of disabling this.
+    """
+    worker = getattr(connector, "_thread", None)
+    if not isinstance(worker, threading.Thread):
+        return
+    await asyncio.to_thread(worker.join, _ABANDONED_WORKER_JOIN_SECONDS)
+
+
+async def _load_sqlite_vec(db: aiosqlite.Connection) -> None:
+    """Load the `sqlite-vec` extension on this connection, through `aiosqlite`'s own method.
+
+    `aiosqlite.Connection.load_extension` is the sanctioned path: the wrapped `sqlite3`
+    connection lives on `aiosqlite`'s own dedicated worker thread, so reaching into it directly
+    to call `sqlite_vec.load()` raises from the caller's thread instead.
+    """
+    await db.enable_load_extension(True)
+    try:
+        await db.load_extension(sqlite_vec.loadable_path())
+    finally:
+        await db.enable_load_extension(False)
+
+
+async def open_connection(
+    db_path: Path,
+    *,
+    pragmas: Sequence[str],
+    existing_only: bool = False,
+    connect_failure: ConnectFailure | None = None,
+) -> tuple[aiosqlite.Connection, int]:
+    """Open `db_path` through `aiosqlite`, with the extension loaded and `pragmas` applied.
+
+    Returns the connection **and** the inode `db_path` resolved to at the moment this call's own
+    `aiosqlite.connect()` returned — needed so a caller can hand it onward to whatever later needs
+    to detect this exact file being replaced out from under an already-open connection
+    (`zikaron.service.lifecycle`'s inode-drift self-stop).
+
+    Never bare `sqlite3`: a handler that called it directly could hold the single-threaded event
+    loop for as long as SQLite's own `busy_timeout` retries, which is a genuine, previously
+    reproduced self-inflicted deadlock rather than a style concern. `aiosqlite` closes that
+    structurally by running the connection on its own thread.
+
+    A failure loading the extension or applying a pragma closes the connection before
+    propagating: `aiosqlite.connect` succeeding is not this function succeeding, and a caller
+    that only wraps its *own* work in `try`/`except` would otherwise be handed nothing to close
+    when the failure happened here instead.
+
+    **A known, deliberately accepted gap, settled on human authority rather than closed by
+    further engineering — read this before "improving" the capture below.** Several attempts
+    were made to close a much narrower race than the one this baseline actually needs to defend
+    against: a replacement landing in the specific, sub-millisecond window inside `aiosqlite`'s
+    own cross-thread connect handoff, between SQLite binding to a file on its worker thread and
+    this coroutine resuming to read the path. Pinning a file descriptor and connecting through
+    its own `/proc/self/fd/<n>` path — reasoned to sidestep pathname resolution entirely — was
+    measured, empirically, to *not* actually do so: `PRAGMA database_list` shows SQLite
+    canonicalizes that magic-symlink path back to the ordinary pathname internally, and a file
+    replaced at the path while an existing connection is live can make even an *already
+    established* connection fail on its next statement — meaning the assumption the whole
+    mechanism rested on was false, not merely incompletely implemented. Closing this properly
+    would require controlling SQLite's own VFS-level file handle directly (a custom VFS or
+    file-control integration), which is a materially larger undertaking than the value warrants
+    for a race with this shape: it requires an adversarial replacement to land inside a
+    sub-millisecond window at process startup, not the ordinary case this mechanism exists for
+    (a store deleted and recreated while the service has been sitting open and idle, which the
+    lifecycle poll closes completely). **The operator's own explicit direction is to accept this
+    narrow gap rather than pursue that undertaking**, and to keep the capture simple: read
+    `db_path.stat()` once, immediately after `await aiosqlite.connect()` returns, with no
+    `await` between the connect and the read — not provably instantaneous with SQLite's own
+    internal bind, but the tightest capture available without the VFS-level work this decision
+    declines, and correct for every case except the one named above.
+
+    Args:
+        db_path: the database file to open.
+        pragmas: the pragmas this database's own schema requires, applied in order. Required, not
+            defaulted: the two schemas want different sets, and a default is how one of them comes
+            to be opened under the other's.
+        existing_only: refuse to create `db_path` if it is absent, by opening it through a
+            `file:…?mode=rw` URI. The caller is left to say what absence means: for the memory
+            store it is a store that was never created, and for a knowledge base it is an empty
+            corpus, which is not an error at all.
+        connect_failure: what to raise when the connect itself fails. Omitted, the driver's own
+            error propagates. It is scoped to the connect deliberately — a caller naming a
+            missing store cannot also name a failed pragma, which describes a different fault.
+
+    Raises:
+        Exception: whatever `connect_failure` returns, if the connect failed and one was given.
+        aiosqlite.Error: the connect failed with no `connect_failure` given, or the extension
+            load or a pragma failed.
+        OSError: `db_path` could not be `stat`ed once the connection was established.
+    """
+    if existing_only:
+        connector = aiosqlite.connect(f"file:{quote(str(db_path))}?mode=rw", uri=True)
+    else:
+        connector = aiosqlite.connect(db_path)
+    try:
+        db = await connector
+    except aiosqlite.Error as error:
+        await join_abandoned_worker(connector)
+        if connect_failure is None:
+            raise
+        raise connect_failure(error) from error
+    try:
+        # The very first statement inside this `try`, with no `await` before it — a failure here
+        # (a permission error, the path having become unstatable) must close the just-established
+        # `db` exactly like a pragma failure a few lines below does; reading it *outside* this
+        # block would abandon a real, worker-thread-backed connection with nothing left to close
+        # it, which is a genuine resource leak this project's own history has already paid for
+        # once: a suite whose tests all completed in 0.76 s then hung indefinitely with an empty
+        # output pipe, because a non-daemon worker thread is joined before any `atexit` handler.
+        opened_inode = db_path.stat().st_ino
+        await _load_sqlite_vec(db)
+        for pragma in pragmas:
+            await db.execute(pragma)
+    except BaseException:
+        await db.close()
+        raise
+    return db, opened_inode

zikaron/core/store/ddl.py

@@ -0,0 +1,215 @@
+"""The schema, as data: every `CREATE` statement `schema.md` §Tables specifies.
+
+One statement per table or index, in creation order, so a schema change touches this module and
+nothing that executes it. Foreign keys point forward in this list — `memory_chunk` before
+`memory`, for instance, would fail — so the order here **is** the order the store must execute
+them in, and `applier` functions elsewhere must not parallelize or reorder it.
+
+Every literal here is a transcription of `schema.md`'s own DDL block; a test reads that block at
+test time and compares, so drift between the design and this module fails a test rather than
+surfacing as a table that silently does not match its own specification.
+"""
+
+from typing import Final
+
+#: The three pragmas `schema.md`'s DDL block opens with, applied to every connection this store
+#: opens — creation and every later open alike, since a connection that skipped them would not
+#: see concurrent readers correctly or retry under contention as the design requires.
+PRAGMAS: Final[tuple[str, ...]] = (
+    "PRAGMA journal_mode = WAL",
+    "PRAGMA busy_timeout = 5000",
+    "PRAGMA foreign_keys = ON",
+)
+
+_MEMORY: Final = """
+CREATE TABLE memory (
+  rowid          INTEGER PRIMARY KEY,
+  uuid           TEXT    NOT NULL UNIQUE,
+  tier           TEXT    NOT NULL DEFAULT 'journal'
+                         CHECK (tier IN ('journal', 'long_term')),
+  gist           TEXT    NOT NULL,
+  content        TEXT    NOT NULL,
+  active         INTEGER NOT NULL DEFAULT 1    CHECK (active IN (0, 1)),
+  superseded_by  TEXT             REFERENCES memory(uuid) ON DELETE RESTRICT,
+  version        INTEGER NOT NULL DEFAULT 1    CHECK (version >= 1),
+  created_at     TEXT    NOT NULL,
+  updated_at     TEXT    NOT NULL,
+  session_id     TEXT,
+  token_count    INTEGER NOT NULL DEFAULT 0,
+
+  CHECK (length(trim(gist))    > 0),
+  CHECK (length(trim(content)) > 0),
+  CHECK (superseded_by IS NULL OR superseded_by <> uuid),
+  CHECK (superseded_by IS NULL OR active = 0)
+)
+"""
+
+_MEMORY_INDEXES: Final[tuple[str, ...]] = (
+    "CREATE INDEX idx_memory_unconsolidated ON memory(tier, active, created_at)",
+    "CREATE INDEX idx_memory_eligible ON memory(active, superseded_by)",
+    "CREATE INDEX idx_memory_superseded ON memory(superseded_by)",
+    "CREATE INDEX idx_memory_session ON memory(session_id)",
+)
+
+_MEMORY_FTS: Final = """
+CREATE VIRTUAL TABLE memory_fts USING fts5 (
+  gist, content,
+  content      = 'memory',
+  content_rowid= 'rowid',
+  tokenize     = 'unicode61'
+)
+"""
+
+_MEMORY_CHUNK: Final = """
+CREATE TABLE memory_chunk (
+  chunk_id     INTEGER PRIMARY KEY,
+  memory_uuid  TEXT    NOT NULL REFERENCES memory(uuid) ON DELETE CASCADE,
+  part_index   INTEGER NOT NULL,
+  token_count  INTEGER NOT NULL,
+  truncated    INTEGER NOT NULL DEFAULT 0 CHECK (truncated IN (0, 1)),
+  embed_model  TEXT    NOT NULL,
+  embed_dim    INTEGER NOT NULL,
+  UNIQUE (memory_uuid, part_index)
+)
+"""
+
+_MEMORY_CHUNK_INDEX: Final = "CREATE INDEX idx_chunk_memory ON memory_chunk(memory_uuid)"
+
+_EVENT: Final = """
+CREATE TABLE event (
+  id          INTEGER PRIMARY KEY,
+  at          TEXT NOT NULL,
+  session_id  TEXT,
+  client_kind TEXT NOT NULL CHECK (client_kind IN ('hook', 'mcp', 'consolidator')),
+  op_id       TEXT NOT NULL,
+  kind        TEXT NOT NULL CHECK (kind IN (
+                'surface_call', 'surface', 'search', 'fetch', 'remember', 'amend', 'retire',
+                'merge', 'promote', 'discard', 'dedup_offered', 'version_conflict',
+                'no_receipt', 'group_served', 'consolidate_run'
+              )),
+  memory_uuid TEXT,
+  detail      TEXT
+)
+"""
+
+_EVENT_INDEXES: Final[tuple[str, ...]] = (
+    "CREATE INDEX idx_event_kind_at ON event(kind, at)",
+    "CREATE INDEX idx_event_session ON event(session_id)",
+    "CREATE INDEX idx_event_session_kind ON event(session_id, client_kind)",
+    "CREATE INDEX idx_event_op ON event(op_id)",
+    "CREATE INDEX idx_event_uuid_at ON event(memory_uuid, at)",
+)
+
+_READ_RECEIPT: Final = """
+CREATE TABLE read_receipt (
+  session_id   TEXT    NOT NULL,
+  client_kind  TEXT    NOT NULL,
+  memory_uuid  TEXT    NOT NULL REFERENCES memory(uuid) ON DELETE CASCADE,
+  version      INTEGER NOT NULL,
+  at           TEXT    NOT NULL,
+  source       TEXT    NOT NULL CHECK (source IN ('fetch', 'group', 'conflict', 'own_write')),
+  PRIMARY KEY (session_id, client_kind, memory_uuid, version)
+) WITHOUT ROWID
+"""
+
+_CONSOLIDATION_RUN: Final = """
+CREATE TABLE consolidation_run (
+  run_id      TEXT PRIMARY KEY,
+  session_id  TEXT    NOT NULL,
+  pid         INTEGER NOT NULL,
+  started_at  TEXT NOT NULL,
+  expires_at  TEXT NOT NULL,
+  status      TEXT NOT NULL CHECK (status IN ('active', 'complete', 'expired', 'abandoned',
+                                               'taken_over'))
+)
+"""
+
+_CONSOLIDATION_GROUP: Final = """
+CREATE TABLE consolidation_group (
+  group_id    TEXT PRIMARY KEY,
+  run_id      TEXT NOT NULL REFERENCES consolidation_run(run_id) ON DELETE CASCADE,
+  anchor_uuid TEXT             REFERENCES memory(uuid) ON DELETE RESTRICT,
+  order_key   TEXT NOT NULL,
+  shard_index INTEGER NOT NULL DEFAULT 1,
+  shard_count INTEGER NOT NULL DEFAULT 1,
+  status      TEXT NOT NULL CHECK (status IN ('pending', 'served', 'complete', 'deferred')),
+  serve_count INTEGER NOT NULL DEFAULT 0,
+  served_at   TEXT,
+  CHECK (shard_count >= 1),
+  CHECK (shard_index BETWEEN 1 AND shard_count),
+  CHECK (serve_count >= 0)
+)
+"""
+
+_CONSOLIDATION_GROUP_INDEX: Final = (
+    "CREATE INDEX idx_group_run_order "
+    "ON consolidation_group(run_id, status, order_key, shard_index)"
+)
+
+_CONSOLIDATION_GROUP_MEMBER: Final = """
+CREATE TABLE consolidation_group_member (
+  group_id     TEXT    NOT NULL REFERENCES consolidation_group(group_id) ON DELETE CASCADE,
+  memory_uuid  TEXT    NOT NULL REFERENCES memory(uuid) ON DELETE RESTRICT,
+  version_seen INTEGER NOT NULL,
+  version_served INTEGER,
+  disposition  TEXT             CHECK (disposition IN
+                 ('merged', 'promoted', 'discarded', 'vacated')),
+  disposed_at  TEXT,
+  PRIMARY KEY (group_id, memory_uuid)
+) WITHOUT ROWID
+"""
+
+_CONSOLIDATION_GROUP_MEMBER_INDEX: Final = (
+    "CREATE INDEX idx_group_member_open ON consolidation_group_member(group_id, disposition)"
+)
+
+_CONSOLIDATION_GROUP_CANDIDATE: Final = """
+CREATE TABLE consolidation_group_candidate (
+  group_id       TEXT    NOT NULL REFERENCES consolidation_group(group_id) ON DELETE CASCADE,
+  memory_uuid    TEXT    NOT NULL REFERENCES memory(uuid) ON DELETE RESTRICT,
+  role           TEXT    NOT NULL CHECK (role IN ('anchor', 'candidate')),
+  version_served INTEGER NOT NULL,
+  rank           INTEGER NOT NULL,
+  PRIMARY KEY (group_id, memory_uuid)
+) WITHOUT ROWID
+"""
+
+_META: Final = "CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)"
+
+#: Every statement that creates something with **no** dependency on the validated `embed_dim`,
+#: in the exact order `schema.md`'s DDL block presents them — which is also a valid dependency
+#: order, since every `REFERENCES` in this list names a table created earlier in it.
+FIXED_STATEMENTS: Final[tuple[str, ...]] = (
+    _MEMORY,
+    *_MEMORY_INDEXES,
+    _MEMORY_FTS,
+    _MEMORY_CHUNK,
+    _MEMORY_CHUNK_INDEX,
+    _EVENT,
+    *_EVENT_INDEXES,
+    _READ_RECEIPT,
+    _CONSOLIDATION_RUN,
+    _CONSOLIDATION_GROUP,
+    _CONSOLIDATION_GROUP_INDEX,
+    _CONSOLIDATION_GROUP_MEMBER,
+    _CONSOLIDATION_GROUP_MEMBER_INDEX,
+    _CONSOLIDATION_GROUP_CANDIDATE,
+    _META,
+)
+
+
+def memory_vec_statement(embed_dim: int) -> str:
+    """The one DDL statement `vec0` fixes a width into, at the validated effective `embed_dim`.
+
+    `schema.md` §"Creating the dense index" requires this width to be validated — and the
+    embedder that will fill the column checked against it — before this statement ever runs,
+    which is why it is a function rather than a member of `FIXED_STATEMENTS`: nothing may call it
+    with an unvalidated value.
+
+    Args:
+        embed_dim: the effective config's `embed_dim`, already checked to be `>= 1` and to equal
+            the width the configured embedder actually reports.
+    """
+    if embed_dim < 1:
+        raise ValueError(f"embed_dim must be >= 1, got {embed_dim}")
+    return f"CREATE VIRTUAL TABLE memory_vec USING vec0 (embedding float[{embed_dim}])"

zikaron/core/store/embedder.py

@@ -0,0 +1,45 @@
+"""The one thing the store needs from an embedder: its width, and the model name it reports.
+
+The store's dimension check must run before `memory_vec` is created, and creating a store embeds
+nothing — so this is deliberately the *narrowest* thing an embedder can be asked for. `fastembed`
+is a dependency of `zikaron-core` as a whole, not of this module: the indexing layer's `Encoder`
+extends this protocol with the tokenizer and embedding calls a write path needs, and the store is
+written against this narrow form so it never depends on them.
+"""
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Embedder(Protocol):
+    """What the store needs to check before it fixes a `vec0` column's width forever.
+
+    `vec0` fixes a column's width at `CREATE` time (`schema.md` §"Creating the dense index"), so
+    the store must know the width a configured model actually emits before any table exists. A
+    real implementation loads the model named by `model_name`; this protocol says nothing about
+    *how* `dim` is produced; only that it is available without embedding anything.
+    """
+
+    @property
+    def model_name(self) -> str:
+        """The model identifier this embedder reports, for comparison against `meta.embed_model`."""
+        ...
+
+    @property
+    def dim(self) -> int:
+        """The width of every vector this embedder would produce."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class FakeEmbedder:
+    """An `Embedder` that reports a width without loading anything.
+
+    The store's own tests use this to exercise the width check deterministically and without
+    `fastembed`'s cold-start cost; nothing about the store's creation or open path can tell it
+    apart from a real one, since both are used purely through the protocol above.
+    """
+
+    model_name: str
+    dim: int