zikaron 0.1.0__py3-none-any.whl

zikaron/core/store/meta.py

@@ -0,0 +1,152 @@
+"""`meta`'s five required keys, and the `reindexing` sentinel that is deliberately not one of them.
+
+`schema.md` §"`meta` — the store-coupled values, and the initialization contract" is normative.
+Two facts from it drive this module's shape: validation happens **twice** — written at creation,
+parsed and range-checked on **every** open — and a required key that is missing, unparseable or
+out of range on open is a fatal `bad_config`, never a silent fall-back to a default. `reindexing`
+is a transient key whose *absence* is normal, so it is exempt from that required-key validation
+and handled by its own present/absent check instead.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Final
+from uuid import UUID
+
+from zikaron.core.errors import BadConfigSource, ErrorCode, ZikaronError
+
+#: The `meta` row key naming the schema this build's tables and invariants implement. Compared
+#: against `zikaron.core.errors.ERROR_SPECS[SCHEMA_INCOMPATIBLE].data_fields`'s fixed `supported`
+#: value by a test, so this module's schema version is never a second, driftable statement of it.
+SCHEMA_VERSION_KEY: Final = "schema_version"
+STORE_ID_KEY: Final = "store_id"
+EMBED_MODEL_KEY: Final = "embed_model"
+EMBED_DIM_KEY: Final = "embed_dim"
+CHUNK_MAX_TOKENS_KEY: Final = "chunk_max_tokens"
+
+#: The transient sentinel `schema.md` explicitly excludes from required-key validation: normal
+#: absence, abnormal presence. Its value is the ISO-8601 instant the unavailable window opened.
+REINDEXING_KEY: Final = "reindexing"
+
+#: The five keys required on every open, in the order this module reads and validates them.
+REQUIRED_KEYS: Final[tuple[str, ...]] = (
+    SCHEMA_VERSION_KEY,
+    STORE_ID_KEY,
+    EMBED_MODEL_KEY,
+    EMBED_DIM_KEY,
+    CHUNK_MAX_TOKENS_KEY,
+)
+
+_CHUNK_MAX_TOKENS_MIN: Final = 64
+_CHUNK_MAX_TOKENS_MAX: Final = 8192
+_UUID4_STRING_LENGTH: Final = 36
+_UUID_VERSION_4: Final = 4
+
+
+@dataclass(frozen=True, slots=True)
+class StoreMeta:
+    """The five required `meta` values, parsed and range-checked.
+
+    Constructing one *is* passing validation: every field has already been read as its typed
+    value and shown to lie in its stated range, so a caller holding a `StoreMeta` need not
+    re-check any of them.
+    """
+
+    schema_version: int
+    store_id: str
+    embed_model: str
+    embed_dim: int
+    chunk_max_tokens: int
+
+
+def _bad_meta(key: str, value: str, expected: str) -> ZikaronError:
+    return ZikaronError(
+        ErrorCode.BAD_CONFIG,
+        source=BadConfigSource.META,
+        key=key,
+        value=value,
+        expected=expected,
+    )
+
+
+def _require_int(raw: Mapping[str, str], key: str, expected: str) -> int:
+    if key not in raw:
+        raise _bad_meta(key, "<missing>", expected)
+    text = raw[key]
+    try:
+        return int(text)
+    except ValueError as error:
+        raise _bad_meta(key, text, expected) from error
+
+
+def _require_string(raw: Mapping[str, str], key: str, expected: str) -> str:
+    if key not in raw:
+        raise _bad_meta(key, "<missing>", expected)
+    return raw[key]
+
+
+def parse_and_validate(raw: Mapping[str, str]) -> StoreMeta:
+    """Turn every `meta` row's text value into `StoreMeta`, or raise naming the first bad key.
+
+    Args:
+        raw: every `meta` row's text value, keyed by `key`. Extra keys (an unknown setting a
+            newer writer left behind) are tolerated silently, per `schema.md`'s forward-
+            compatibility rule for a *supported* schema version.
+
+    Raises:
+        ZikaronError: `BAD_CONFIG` with `source='meta'`, naming the first required key found
+            missing, unparseable, or out of its stated range. There is no partial `StoreMeta` to
+            return on failure, per `schema.md`'s "fatal store error, not a fall-back" rule.
+    """
+    schema_version = _require_int(raw, SCHEMA_VERSION_KEY, "int >= 1")
+    if schema_version < 1:
+        raise _bad_meta(SCHEMA_VERSION_KEY, str(schema_version), "int >= 1")
+    store_id = _require_string(raw, STORE_ID_KEY, "uuid4 string, 36 chars")
+    if len(store_id) != _UUID4_STRING_LENGTH:
+        raise _bad_meta(STORE_ID_KEY, store_id, "uuid4 string, 36 chars")
+    try:
+        parsed_store_id = UUID(store_id)
+    except ValueError as error:
+        raise _bad_meta(STORE_ID_KEY, store_id, "uuid4 string, 36 chars") from error
+    if parsed_store_id.version != _UUID_VERSION_4:
+        raise _bad_meta(STORE_ID_KEY, store_id, "uuid4 string, 36 chars")
+    embed_model = _require_string(raw, EMBED_MODEL_KEY, "non-empty string")
+    if embed_model == "":
+        raise _bad_meta(EMBED_MODEL_KEY, embed_model, "non-empty string")
+    embed_dim = _require_int(raw, EMBED_DIM_KEY, "int >= 1")
+    if embed_dim < 1:
+        raise _bad_meta(EMBED_DIM_KEY, str(embed_dim), "int >= 1")
+    chunk_max_tokens = _require_int(
+        raw, CHUNK_MAX_TOKENS_KEY, f"int {_CHUNK_MAX_TOKENS_MIN}-{_CHUNK_MAX_TOKENS_MAX}"
+    )
+    if not (_CHUNK_MAX_TOKENS_MIN <= chunk_max_tokens <= _CHUNK_MAX_TOKENS_MAX):
+        raise _bad_meta(
+            CHUNK_MAX_TOKENS_KEY,
+            str(chunk_max_tokens),
+            f"int {_CHUNK_MAX_TOKENS_MIN}-{_CHUNK_MAX_TOKENS_MAX}",
+        )
+    return StoreMeta(
+        schema_version=schema_version,
+        store_id=store_id,
+        embed_model=embed_model,
+        embed_dim=embed_dim,
+        chunk_max_tokens=chunk_max_tokens,
+    )
+
+
+def defaults_at_creation(
+    schema_version: int, store_id: str, embed_model: str, embed_dim: int, chunk_max_tokens: int
+) -> Mapping[str, str]:
+    """Every required `meta` row's text value at store creation, in `REQUIRED_KEYS` order.
+
+    `schema.md` requires a fresh store to be "fully described" so nothing on open reads a
+    missing key — this is the write side of that promise, called once by `Store.create` after
+    every value it takes has already been validated by whoever assembled them.
+    """
+    return {
+        SCHEMA_VERSION_KEY: str(schema_version),
+        STORE_ID_KEY: store_id,
+        EMBED_MODEL_KEY: embed_model,
+        EMBED_DIM_KEY: str(embed_dim),
+        CHUNK_MAX_TOKENS_KEY: str(chunk_max_tokens),
+    }

zikaron/core/store/permissions.py

@@ -0,0 +1,160 @@
+"""`0700`/`0600` enforcement for the store directory and the files inside it.
+
+`architecture.md` §"Filesystem security" is normative: `.zikaron/` and `.zikaron/knowledge/` are
+mode `0700`, and `memory.db`, every `knowledge/<uuid4>.db`, and all their `-wal`/`-shm` siblings
+are `0600`, created with an explicit umask rather
+than inherited — SQLite creates the WAL/SHM files itself and will otherwise pick up whatever
+umask the process happened to have. A directory found wider than `0700` is tightened rather than
+refused, per the same table.
+
+`core/knowledge/database.py` imports this module so a knowledge base gets the same modes, which
+matters at least as much there: a corpus holds the verbatim text of every file indexed into it.
+"""
+
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from zikaron.core.errors import BadConfigSource, ErrorCode, ZikaronError
+
+_STORE_DIR_MODE = 0o700
+_STORE_FILE_MODE = 0o600
+_STORE_FILE_UMASK = 0o077
+
+
+def _reject_symlinked_store_dir(store_dir: Path) -> None:
+    """Refuse a store reached through a symlink anywhere in `store_dir`'s own path.
+
+    `architecture.md` §"Filesystem security": "`realpath` the store directory and require the
+    resolved parent to be the **scope directory** (D17 as amended — under Claude Code deliberately
+    not the spawning process's cwd)." *This quoted the pre-amendment wording — "the cwd" — which
+    D17 replaced, and then glossed the word the amendment had removed. One side of a two-way
+    pointer was updated and the other kept quoting the superseded text; the pointer guard cannot
+    see it, because the section name it resolves is intact.* That sentence states the rule from
+    `zikaron-service`'s own point of view, where the store path is *derived* from the caller's
+    scope directory in the first place (D17: the harness's own project directory where it names
+    one, else the working directory; the vetting below is unaffected either way, since it never
+    compares against an ambient cwd) — deriving `store_dir` is that caller's job, not this
+    function's, since `Store.create`/`Store.open` take `store_dir` as an explicit parameter and
+    have no way to know whether the caller's own cwd is the concept the caller meant by it. A
+    caller that resolved `store_dir` from somewhere other than its own cwd — a test, a tool
+    walking several stores — would be wrongly refused by comparing against the *ambient*
+    process cwd here, which is a fact about this function's environment rather than about the
+    path it was actually asked to open.
+
+    What this function *can* check, and what carries the rule's real security content
+    regardless of who derived the path: whether `store_dir` is reached through a symlink at
+    all, anywhere along its own length — `store_dir` itself, or any directory between it and
+    the filesystem root. A bare `store_dir.is_symlink()` check misses the case a symlinked
+    *ancestor* creates, e.g. `some-symlinked-parent/.zikaron`, where `.zikaron` itself is a
+    genuine directory but the path leading to it is not what it appears to be.
+    """
+    current = store_dir if store_dir.is_absolute() else Path.cwd() / store_dir
+    while True:
+        if current.is_symlink():
+            raise ZikaronError(
+                ErrorCode.BAD_CONFIG,
+                source=BadConfigSource.DERIVED,
+                key="store_dir",
+                value=str(store_dir),
+                expected=f"no symlink anywhere in the path to it (found one at {current})",
+            )
+        parent = current.parent
+        if parent == current:
+            return
+        current = parent
+
+
+def ensure_store_dir(path: Path) -> None:
+    """Create `path` at `0700` if absent, or tighten it to `0700` if it exists wider.
+
+    Explicit `mkdir(mode=...)` rather than a bare `mkdir()` followed by `chmod`, because a
+    process umask can otherwise narrow the mode `mkdir` was asked for and leave a gap between
+    what this function requested and what actually landed on disk.
+
+    Raises:
+        ZikaronError: `BAD_CONFIG` if `path`, once resolved, is not reached through the current
+            directory alone — `architecture.md` §"Filesystem security" requires a store reached
+            through a symlinked `.zikaron`, or through a symlinked ancestor of it, to be
+            refused rather than followed, since the store's own `0700`/`0600` modes protect the
+            directory they are set on, not whatever a symlink happens to point at.
+    """
+    _reject_symlinked_store_dir(path)
+    if path.is_dir():
+        current = path.stat().st_mode & 0o777
+        if current != _STORE_DIR_MODE:
+            path.chmod(_STORE_DIR_MODE)
+        return
+    path.mkdir(mode=_STORE_DIR_MODE, parents=True)
+    path.chmod(_STORE_DIR_MODE)
+
+
+@contextmanager
+def restrictive_umask() -> Iterator[None]:
+    """Force every file created in this block to land at `0600`, regardless of the process umask.
+
+    SQLite creates `memory.db`'s `-wal` and `-shm` siblings itself, outside any `open()` call
+    this module makes, so a umask set only around an explicit file creation would not reach
+    them. Wrapping the whole store-creation sequence in this umask is what does.
+    """
+    previous = os.umask(_STORE_FILE_UMASK)
+    try:
+        yield
+    finally:
+        os.umask(previous)
+
+
+def database_files(db_path: Path) -> tuple[Path, Path, Path]:
+    """`db_path` and its two WAL siblings — the three files one open database actually is.
+
+    In WAL mode a database at rest is one file and a database in use is three, and every operation
+    that moves, removes or re-permissions one has to handle all of them. Enumerating them in one
+    place rather than at each call site is what keeps a caller from tightening `memory.db` while
+    leaving its `-wal` world-readable, or from unlinking a knowledge base and leaving its journal
+    behind for the next create at that path to inherit.
+
+    Returned in a fixed order — database, `-wal`, `-shm` — so a caller that unlinks them does so
+    in an order a reader can reason about, and named by suffix rather than by a hardcoded
+    `memory.db` so a knowledge-base database is the same three files by the same rule.
+    """
+    return (
+        db_path,
+        db_path.with_name(db_path.name + "-wal"),
+        db_path.with_name(db_path.name + "-shm"),
+    )
+
+
+def enforce_store_file_mode(path: Path) -> None:
+    """Tighten an existing store file to `0600` if it was created wider than that.
+
+    Called after store creation as a belt-and-suspenders check: `restrictive_umask` is what
+    should have produced `0600` in the first place, and this is what makes a wider mode a
+    correction rather than a silent gap if some code path ever creates the file outside it.
+    """
+    if path.is_file():
+        current = path.stat().st_mode & 0o777
+        if current != _STORE_FILE_MODE:
+            path.chmod(_STORE_FILE_MODE)
+
+
+def enforce_existing_store_permissions(store_dir: Path) -> None:
+    """Tighten a pre-existing store's directory and database files, without creating anything.
+
+    `Store.open` calls this before touching the connection, so a store whose directory was left
+    at a wider mode by an older build — or by an operator's own `chmod` — is corrected on the
+    very next open rather than only ever being corrected at creation time, which is the one
+    moment `Store.create`'s own checks previously ran.
+
+    Raises:
+        ZikaronError: `BAD_CONFIG` if `store_dir`, once resolved, is not reached through the
+            current directory alone, for the same reason `ensure_store_dir` refuses that shape
+            at creation.
+    """
+    _reject_symlinked_store_dir(store_dir)
+    if store_dir.is_dir():
+        current = store_dir.stat().st_mode & 0o777
+        if current != _STORE_DIR_MODE:
+            store_dir.chmod(_STORE_DIR_MODE)
+    for path in database_files(store_dir / "memory.db"):
+        enforce_store_file_mode(path)