lorebase-store 0.2.3__py3-none-any.whl

lorebase_store/_migrations/versions/0011_branch_scoped_search_index.py

@@ -0,0 +1,229 @@
+"""Search indexes scoped by Domain and branch (design 8.7; store schema notes).
+
+The GIN indexes of revision 0001 on `search` (`ix_mat_records_search`) and on `title`
+(trigrams, `ix_mat_records_title`) index that column alone, so each is shared by every Domain
+and branch of a hash partition: a search reads the matches of all of them and keeps its own
+when it rechecks the rows, and a search on an overlay branch does so once per half. This
+revision replaces them with `ix_mat_records_branch_search` on `(domain_id, branch, search)`
+and `ix_mat_records_branch_title` on `(domain_id, branch, title gin_trgm_ops)`; the
+`btree_gin` extension (contrib) provides the GIN operator classes for the two text columns,
+so a search's Domain and branch are index conditions and the bitmap holds the branch's
+matches only. The extension is created if missing and never dropped on downgrade, like the
+extensions of revision 0001.
+
+Building and swapping each index does not block writes for long:
+
+- `CREATE INDEX ... ON ONLY mat_records` makes the parent index (invalid, no partition yet);
+- outside the migration transaction, each partition gets its index with `CREATE INDEX
+  CONCURRENTLY` (an invalid leftover of an interrupted build is dropped and built again) and
+  is attached to the parent, which becomes valid when every partition is attached;
+- the old index is dropped only once the new one is valid; dropping a partitioned index takes
+  a short exclusive lock on `mat_records` (catalog work, no scan).
+
+Search on an overlay also stops probing the overlay's primary key once per base match: the
+anti-join of `lb_overlay_rows` gets the argument `p_probe` (default true: `OFFSET 0` keeps it a
+probe per base row, right for lookups by key and short pages); `lb_search_overlay` passes
+false and lets the planner hash the overlay's keys when the matches outnumber them. Its
+signature, checks, owner and grants stay those of revision 0010.
+
+Revision ID: 0011
+Revises: 0010
+Create Date: 2026-10-21 20:00:00.000000
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from collections.abc import Sequence
+from pathlib import Path
+from types import ModuleType
+from typing import NamedTuple
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0011"
+down_revision: str | Sequence[str] | None = "0010"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def _revision_module(filename: str) -> ModuleType:
+    """An earlier revision file of this directory, loaded for its SQL templates and checks."""
+    path = Path(__file__).with_name(filename)
+    spec = importlib.util.spec_from_file_location(f"_lorebase_revision_{path.stem}", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot load migration {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+_overlays = _revision_module("0010_overlay_branches.py")
+_checks = _overlays._checks
+_reads = _overlays._reads
+
+PARENT = "mat_records"
+
+
+class GinIndex(NamedTuple):
+    name: str
+    columns: str
+    suffix: str
+    """Partition indexes are named `<partition>_<suffix>`, as Postgres names those it creates
+    for an index on the parent."""
+
+
+SWAPS = (
+    (
+        GinIndex("ix_mat_records_search", "search", "search_idx"),
+        GinIndex(
+            "ix_mat_records_branch_search",
+            "domain_id, branch, search",
+            "domain_id_branch_search_idx",
+        ),
+    ),
+    (
+        GinIndex("ix_mat_records_title", "title gin_trgm_ops", "title_idx"),
+        GinIndex(
+            "ix_mat_records_branch_title",
+            "domain_id, branch, title gin_trgm_ops",
+            "domain_id_branch_title_idx",
+        ),
+    ),
+)
+"""(index of revision 0001, its branch-scoped replacement)."""
+
+OLD_HELPER = "lb_overlay_rows(text, text, text, text)"
+HELPER = "lb_overlay_rows(text, text, text, text, boolean)"
+SEARCH = _overlays.SIGNATURES[0]
+
+
+def _replaced(text: str, old: str, new: str) -> str:
+    if text.count(old) != 1:
+        raise RuntimeError(f"revision 0010 changed: {old!r} not found once")
+    return text.replace(old, new)
+
+
+LB_OVERLAY_ROWS = _replaced(
+    _replaced(
+        _replaced(
+            _overlays.LB_OVERLAY_ROWS,
+            "p_tail text DEFAULT NULL)",
+            "p_tail text DEFAULT NULL,\n    p_probe boolean DEFAULT true)",
+        ),
+        "AND %8$s OFFSET 0)',",
+        "AND %8$s%9$s)',",
+    ),
+    "v_from_base, p_table, p_domain, v_base, v_generation, p_branch, v_s, v_shadow);",
+    "v_from_base, p_table, p_domain, v_base, v_generation, p_branch, v_s, v_shadow,\n"
+    "        CASE WHEN p_probe THEN ' OFFSET 0' ELSE '' END);",
+)
+"""Revision 0010's helper with `p_probe`: false renders the anti-join without `OFFSET 0`."""
+
+_SEARCH_SOURCES = "v_records text;"
+_SEARCH_RESOLVE = """
+    v_records := coalesce(
+        lb_overlay_rows(p_domain, p_branch, 'mat_records', NULL, false), 'mat_records');
+"""
+"""Run after the checks of revision 0008, as in revision 0010; search reads no Links."""
+
+
+def _overlay_search(sources: str, resolve: str) -> None:
+    search_path = _reads._search_path()
+    options = _reads._OPTIONS.format(search_path=search_path).strip()
+    counts = _overlays.COUNTS[_overlays.LB_SEARCH_OVERLAY]
+    guards = _checks._guards(search_path, counts) + resolve
+    statement = _checks._create_or_replace(_overlays.LB_SEARCH_OVERLAY, guards)
+    op.execute(
+        statement.format(options=options, record_columns=_reads._RECORD_COLUMNS, sources=sources)
+    )
+    # CREATE OR REPLACE keeps the owner and the grants; restate them all the same.
+    op.execute(f"REVOKE ALL ON FUNCTION {SEARCH} FROM PUBLIC")
+    role = _reads._application_role()
+    if role is not None:
+        quoted = op.get_bind().execute(sa.text("SELECT quote_ident(:r)"), {"r": role}).scalar()
+        op.execute(f"GRANT EXECUTE ON FUNCTION {SEARCH} TO {quoted}")
+
+
+def _helper(drop: str, create: str, signature: str) -> None:
+    """Swap the helper; the read functions resolve it by name when they run."""
+    op.execute(f"DROP FUNCTION IF EXISTS {drop}")
+    op.execute(create.format(search_path=_reads._search_path()))
+    op.execute(f"REVOKE ALL ON FUNCTION {signature} FROM PUBLIC")
+
+
+def _partitions() -> list[str]:
+    found = op.get_bind().execute(
+        sa.text(
+            "SELECT c.relname FROM pg_inherits i JOIN pg_class c ON c.oid = i.inhrelid "
+            "WHERE i.inhparent = CAST(:parent AS regclass) ORDER BY c.relname"
+        ),
+        {"parent": PARENT},
+    )
+    return list(found.scalars())
+
+
+def _state(name: str) -> tuple[bool, bool] | None:
+    """`(valid, attached)` of an index, `None` when it does not exist."""
+    row = (
+        op.get_bind()
+        .execute(
+            sa.text(
+                "SELECT x.indisvalid, EXISTS (SELECT 1 FROM pg_inherits i "
+                "WHERE i.inhrelid = c.oid) FROM pg_class c JOIN pg_index x "
+                "ON x.indexrelid = c.oid WHERE c.relname = :name "
+                "AND c.relnamespace = (SELECT relnamespace FROM pg_class "
+                "WHERE oid = CAST(:parent AS regclass))"
+            ),
+            {"name": name, "parent": PARENT},
+        )
+        .first()
+    )
+    return None if row is None else (bool(row[0]), bool(row[1]))
+
+
+def _build(index: GinIndex) -> None:
+    """Build the GIN index on every partition without blocking writes."""
+    op.execute(
+        f"CREATE INDEX IF NOT EXISTS {index.name} ON ONLY {PARENT} USING gin ({index.columns})"
+    )
+    with op.get_context().autocommit_block():
+        for partition in _partitions():
+            name = f"{partition}_{index.suffix}"
+            state = _state(name)
+            if state is not None and not state[0]:
+                op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {name}")
+                state = None
+            if state is None:
+                op.execute(
+                    f"CREATE INDEX CONCURRENTLY {name} ON {partition} USING gin ({index.columns})"
+                )
+            if state is None or not state[1]:
+                op.execute(f"ALTER INDEX {index.name} ATTACH PARTITION {name}")
+    if _state(index.name) != (True, False):
+        raise RuntimeError(f"index {index.name} is not valid after attaching every partition")
+
+
+def _swap(old: GinIndex, new: GinIndex) -> None:
+    """Build `new`, then drop `old` once `new` is valid."""
+    _build(new)
+    op.execute(f"DROP INDEX IF EXISTS {old.name}")
+
+
+def upgrade() -> None:
+    role = _reads._application_role()
+    if role is not None:
+        _checks._refuse_writable_schemas(role)
+    op.execute("CREATE EXTENSION IF NOT EXISTS btree_gin")
+    _helper(OLD_HELPER, LB_OVERLAY_ROWS, HELPER)
+    _overlay_search(_SEARCH_SOURCES, _SEARCH_RESOLVE)
+    for old, new in SWAPS:
+        _swap(old, new)
+
+
+def downgrade() -> None:
+    for old, new in reversed(SWAPS):
+        _swap(new, old)
+    _helper(HELPER, _overlays.LB_OVERLAY_ROWS, OLD_HELPER)
+    _overlay_search(_overlays._SOURCES.strip(), _overlays._RESOLVE)

lorebase_store/_migrations/versions/0012_overlay_neighborhood_lookups.py

@@ -0,0 +1,185 @@
+"""One lookup per hop in the overlay neighborhood (store schema notes).
+
+`lb_neighborhood_overlay` (revision 0010) looked Links and Records up by key through the
+resolved rows of the overlay, `UNION ALL` of its rows and its base's: two index scans per
+lookup, a primary-key probe of the overlay per base row found, and a larger statement to
+plan for every hop and side. This revision adds `lb_overlay_lookup(domain, branch, table,
+where)`, which renders a lookup of the resolved rows matching `where` as one index scan over
+both branches (`branch IN (overlay, base)`, base rows up to the fork generation while the ref
+is still that overlay), where the overlay's row of an identity, tombstone included, wins over
+the base's (`DISTINCT ON`, overlay first); `lorebase_store.layout.BranchLayout.records_lookup`
+renders the same text. The function's stored Link hops, foreign-key hops out of a Record and
+final hydration use it; inbound foreign-key hops still read both halves through their
+per-Attribute indexes. Signature, checks, owner and grants are those of revision 0010.
+
+`where` is SQL text: only the read functions call the helper, with conditions they build
+from constants; EXECUTE is revoked from PUBLIC.
+
+Revision ID: 0012
+Revises: 0011
+Create Date: 2026-10-21 21:00:00.000000
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from collections.abc import Sequence
+from pathlib import Path
+from types import ModuleType
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0012"
+down_revision: str | Sequence[str] | None = "0011"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def _revision_module(filename: str) -> ModuleType:
+    """An earlier revision file of this directory, loaded for its SQL templates and checks."""
+    path = Path(__file__).with_name(filename)
+    spec = importlib.util.spec_from_file_location(f"_lorebase_revision_{path.stem}", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot load migration {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+_overlays = _revision_module("0010_overlay_branches.py")
+_checks = _overlays._checks
+_reads = _overlays._reads
+
+HELPER = "lb_overlay_lookup(text, text, text, text)"
+NEIGHBORHOOD = _overlays.SIGNATURES[2]
+
+LB_OVERLAY_LOOKUP = f"""
+CREATE FUNCTION lb_overlay_lookup(p_domain text, p_branch text, p_table text, p_where text)
+RETURNS text
+LANGUAGE plpgsql STABLE
+SET search_path = {{search_path}}
+AS $fn$
+DECLARE
+    v_columns text[];
+    v_key text[];
+    v_base text;
+    v_generation bigint;
+    v_select text;
+    v_identity text;
+BEGIN
+    IF p_table = 'mat_records' THEN
+        v_columns := {_overlays._array(_overlays._RECORD_COLUMNS)};
+        v_key := ARRAY['kind_id', 'key'];
+    ELSIF p_table = 'mat_links' THEN
+        v_columns := {_overlays._array(_overlays._LINK_COLUMNS)};
+        v_key := ARRAY['relation_id', 'from_key', 'to_key'];
+    ELSE
+        RAISE EXCEPTION 'unknown materialized table %', p_table USING ERRCODE = '22023';
+    END IF;
+    SELECT string_agg(
+               CASE WHEN c = 'branch' THEN format('CAST(%L AS text) AS branch', p_branch)
+                    ELSE 'x.' || quote_ident(c) END, ', ' ORDER BY n)
+    INTO v_select FROM unnest(v_columns) WITH ORDINALITY AS t(c, n);
+    SELECT r.base_branch, r.base_generation INTO v_base, v_generation
+    FROM refs r
+    WHERE r.domain_id = p_domain AND r.name = p_branch AND r.materialization = 'overlay';
+    IF v_base IS NULL THEN
+        -- Not (or no longer) an overlay: its own rows.
+        RETURN format('(SELECT %s FROM %I x WHERE x.domain_id = %L AND x.branch = %L AND %s)',
+                      v_select, p_table, p_domain, p_branch, p_where);
+    END IF;
+    SELECT string_agg('x.' || quote_ident(c), ', ' ORDER BY n) INTO v_identity
+    FROM unnest(v_key) WITH ORDINALITY AS t(c, n);
+    -- The rows of lorebase_store.layout.BranchLayout.records_lookup: the overlay's and the
+    -- base's (up to the fork, while the ref is still that overlay) in one scan, the
+    -- overlay's row of an identity first, tombstones dropped last.
+    RETURN format(
+        '(SELECT %1$s FROM (SELECT DISTINCT ON (%2$s) * FROM %3$I x '
+        'WHERE x.domain_id = %4$L AND x.branch IN (%5$L, %6$L) '
+        'AND (x.branch = %5$L OR (x.revision_generation <= %7$s '
+        'AND EXISTS (SELECT 1 FROM refs f WHERE f.domain_id = %4$L AND f.name = %5$L '
+        'AND f.base_branch = %6$L AND f.base_generation = %7$s OFFSET 0))) AND %8$s '
+        'ORDER BY %2$s, x.branch = %5$L DESC) x WHERE NOT x.deleted)',
+        v_select, v_identity, p_table, p_domain, p_branch, v_base, v_generation, p_where);
+END
+$fn$
+"""
+
+
+def _replaced(text: str, old: str, new: str) -> str:
+    if text.count(old) != 1:
+        raise RuntimeError(f"revision 0010 changed: {old!r} not found once")
+    return text.replace(old, new)
+
+
+_LINK_JOIN = """    v_join := format(
+        'CROSS JOIN LATERAL (SELECT * FROM %s l WHERE l.domain_id = %L AND l.branch = %L '
+        'AND l.relation_id = r.relation_id AND l.@near@ = w.key OFFSET 0) AS l',
+        v_links, p_domain, p_branch);"""
+_LINK_LOOKUP = """    v_join := 'CROSS JOIN LATERAL ' || lb_overlay_lookup(
+        p_domain, p_branch, 'mat_links', 'x.relation_id = r.relation_id AND x.@near@ = w.key')
+        || ' AS l';"""
+_RECORD_JOIN = """'CAST(NULL AS bytea) FROM fk_rels f JOIN %s m ON m.domain_id = %L '
+            'AND m.branch = %L AND m.kind_id = w.kind_id AND m.key = w.key '
+            'WHERE f.from_kind = w.kind_id AND m."values" ->> f.attribute IS NOT NULL '
+            'LIMIT $3', v_records, p_domain, p_branch);"""
+_RECORD_LOOKUP = """'CAST(NULL AS bytea) FROM fk_rels f CROSS JOIN LATERAL %s m '
+            'WHERE f.from_kind = w.kind_id AND m."values" ->> f.attribute IS NOT NULL '
+            'LIMIT $3', lb_overlay_lookup(p_domain, p_branch, 'mat_records',
+                                          'x.kind_id = w.kind_id AND x.key = w.key'));"""
+_HYDRATE_JOIN = """    CROSS JOIN LATERAL (
+        SELECT * FROM %5$s m WHERE m.domain_id = %3$L AND m.branch = %4$L
+                               AND m.kind_id = n.kind_id AND m.key = n.key LIMIT 1) AS m"""
+_HYDRATE_LOOKUP = "    CROSS JOIN LATERAL %6$s AS m"
+_FORMAT_ARGUMENTS = "$sql$, v_nulls, v_step, p_domain, p_branch, v_records)"
+_LOOKUP_ARGUMENTS = """$sql$, v_nulls, v_step, p_domain, p_branch, v_records,
+        lb_overlay_lookup(p_domain, p_branch, 'mat_records',
+                          'x.kind_id = n.kind_id AND x.key = n.key'))"""
+
+LB_NEIGHBORHOOD_OVERLAY = _overlays.LB_NEIGHBORHOOD_OVERLAY
+for _old, _new in (
+    (_LINK_JOIN, _LINK_LOOKUP),
+    (_RECORD_JOIN, _RECORD_LOOKUP),
+    (_HYDRATE_JOIN, _HYDRATE_LOOKUP),
+    (_FORMAT_ARGUMENTS, _LOOKUP_ARGUMENTS),
+):
+    LB_NEIGHBORHOOD_OVERLAY = _replaced(LB_NEIGHBORHOOD_OVERLAY, _old, _new)
+"""Revision 0010's function with the lookups; inbound foreign-key hops still read
+`v_records`, the resolved rows."""
+
+_SOURCES = "v_records text;"
+_RESOLVE = """
+    v_records := coalesce(lb_overlay_rows(p_domain, p_branch, 'mat_records'), 'mat_records');
+"""
+"""Run after the checks of revision 0008, as in revision 0010; Links are read by lookup."""
+
+
+def _neighborhood(template: str, sources: str, resolve: str) -> None:
+    search_path = _reads._search_path()
+    options = _reads._OPTIONS.format(search_path=search_path).strip()
+    guards = _checks._guards(search_path, _overlays.COUNTS[_overlays.LB_NEIGHBORHOOD_OVERLAY])
+    statement = _checks._create_or_replace(template, guards + resolve)
+    op.execute(
+        statement.format(options=options, record_columns=_reads._RECORD_COLUMNS, sources=sources)
+    )
+    # CREATE OR REPLACE keeps the owner and the grants; restate them all the same.
+    op.execute(f"REVOKE ALL ON FUNCTION {NEIGHBORHOOD} FROM PUBLIC")
+    role = _reads._application_role()
+    if role is not None:
+        quoted = op.get_bind().execute(sa.text("SELECT quote_ident(:r)"), {"r": role}).scalar()
+        op.execute(f"GRANT EXECUTE ON FUNCTION {NEIGHBORHOOD} TO {quoted}")
+
+
+def upgrade() -> None:
+    role = _reads._application_role()
+    if role is not None:
+        _checks._refuse_writable_schemas(role)
+    op.execute(LB_OVERLAY_LOOKUP.format(search_path=_reads._search_path()))
+    op.execute(f"REVOKE ALL ON FUNCTION {HELPER} FROM PUBLIC")
+    _neighborhood(LB_NEIGHBORHOOD_OVERLAY, _SOURCES, _RESOLVE)
+
+
+def downgrade() -> None:
+    _neighborhood(_overlays.LB_NEIGHBORHOOD_OVERLAY, _overlays._SOURCES.strip(), _overlays._RESOLVE)
+    op.execute(f"DROP FUNCTION IF EXISTS {HELPER}")

lorebase_store/_migrations/versions/0013_web_sessions.py

@@ -0,0 +1,72 @@
+"""Browser sessions of the web app, Keeper acting as backend-for-frontend (design 13.2).
+
+One row per signed-in session. The cookie carries an opaque id; the row is found by the
+SHA-256 of that id, which is never stored itself. `tokens` holds the provider's refresh and
+ID tokens, encrypted by Keeper with a key from its configuration. The table is
+installation-wide like `api_keys` (no `domain_id`, no policy); rows go with their principal.
+Created by the owner role like every table: the application role receives row rights through
+the owner's default privileges (deployment docs).
+
+Revision ID: 0013
+Revises: 0012
+Create Date: 2026-10-22 09:00:00.000000
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "0013"
+down_revision: str | Sequence[str] | None = "0012"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "web_sessions",
+        sa.Column("id_hash", sa.LargeBinary(), nullable=False),
+        sa.Column("principal_id", sa.Text(), nullable=False),
+        sa.Column("subject", sa.Text(), nullable=False),
+        sa.Column(
+            "external_groups",
+            postgresql.JSONB(astext_type=sa.Text()),
+            server_default=sa.text("'[]'::jsonb"),
+            nullable=False,
+        ),
+        sa.Column("tokens", sa.LargeBinary(), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column("last_seen_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("refresh_at", sa.DateTime(timezone=True), nullable=True),
+        sa.CheckConstraint("octet_length(id_hash) = 32", name=op.f("ck_web_sessions_id_hash_h32")),
+        sa.ForeignKeyConstraint(
+            ["principal_id"],
+            ["principals.id"],
+            name=op.f("fk_web_sessions_principal_id_principals"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id_hash", name=op.f("pk_web_sessions")),
+    )
+    op.create_index(
+        op.f("ix_web_sessions_principal_id"), "web_sessions", ["principal_id"], unique=False
+    )
+    op.create_index(
+        op.f("ix_web_sessions_last_seen_at"), "web_sessions", ["last_seen_at"], unique=False
+    )
+    op.create_index(
+        op.f("ix_web_sessions_expires_at"), "web_sessions", ["expires_at"], unique=False
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("web_sessions")

lorebase_store/_migrations/versions/0014_embedding_jobs.py

@@ -0,0 +1,70 @@
+"""Embedding jobs (design 9.3): text hashes of vectors and per-branch progress.
+
+- `embeddings.text_hash`: SHA-256 of the text a vector was computed from. A Record whose text
+  did not change keeps its vector, and an object whose text equals another's reuses that
+  vector without a model call (index on `(domain_id, model, text_hash)`). Null for vectors
+  written before this revision.
+- `embedding_cursors`: per branch and model, the head and the template fingerprints of the
+  last complete pass of the embedding job. Domain-scoped with row-level security like the
+  tables of 0001; rows go with their branch.
+
+Revision ID: 0014
+Revises: 0013
+Create Date: 2026-10-22 18:00:00.000000
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "0014"
+down_revision: str | Sequence[str] | None = "0013"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+DOMAIN_VISIBLE = (
+    "current_setting('lorebase.bypass_rls', true) = 'on' "
+    "OR domain_id = ANY (string_to_array(current_setting('lorebase.domain_ids', true), ','))"
+)
+
+
+def upgrade() -> None:
+    op.add_column("embeddings", sa.Column("text_hash", sa.LargeBinary(), nullable=True))
+    op.create_index(
+        op.f("ix_embeddings_domain_id_model_text_hash"),
+        "embeddings",
+        ["domain_id", "model", "text_hash"],
+        unique=False,
+    )
+    op.create_table(
+        "embedding_cursors",
+        sa.Column("domain_id", sa.Text(), nullable=False),
+        sa.Column("branch", sa.Text(), nullable=False),
+        sa.Column("model", sa.Text(), nullable=False),
+        sa.Column("head", sa.LargeBinary(), nullable=False),
+        sa.Column("fingerprints", postgresql.JSONB(astext_type=sa.Text()), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["domain_id", "branch"],
+            ["refs.domain_id", "refs.name"],
+            name=op.f("fk_embedding_cursors_domain_id_branch_refs"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("domain_id", "branch", "model", name=op.f("pk_embedding_cursors")),
+    )
+    op.execute("ALTER TABLE embedding_cursors ENABLE ROW LEVEL SECURITY")
+    op.execute("ALTER TABLE embedding_cursors FORCE ROW LEVEL SECURITY")
+    op.execute(
+        "CREATE POLICY domain_isolation ON embedding_cursors "
+        f"USING ({DOMAIN_VISIBLE}) WITH CHECK ({DOMAIN_VISIBLE})"
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("embedding_cursors")
+    op.drop_index(op.f("ix_embeddings_domain_id_model_text_hash"), table_name="embeddings")
+    op.drop_column("embeddings", "text_hash")

lorebase_store/_migrations/versions/0015_append_only_audit_log.py

@@ -0,0 +1,83 @@
+"""The audit log is append-only for every role but its owner.
+
+The application role received `SELECT, INSERT, UPDATE, DELETE` on `audit_log` like on every
+table (default privileges of the owner, deployment docs), though no code updates or deletes
+audit entries: the hash chains are only extended. With those rights a compromised service
+could rewrite or drop the newest entries of a chain without the verification noticing.
+
+`UPDATE`, `DELETE` and `TRUNCATE` (and `REFERENCES`, `TRIGGER`, which nothing needs) are
+revoked on `audit_log` from `PUBLIC`, from `database.application_role` when set and from
+every other role holding them except the table owner, which runs the migrations and the
+maintenance jobs. `SELECT` and `INSERT` stay. Nothing in Lorebase prunes the audit log; an
+operator who needs to (retention, erasure) does it as the owner.
+
+Revision ID: 0015
+Revises: 0014
+Create Date: 2026-10-23 09:00:00.000000
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0015"
+down_revision: str | Sequence[str] | None = "0014"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+TABLE = "audit_log"
+REVOKED = "UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER"
+RESTORED = "UPDATE, DELETE"
+"""What the downgrade gives back to the application role: its rights before this revision."""
+
+
+def _application_role() -> str | None:
+    config = op.get_context().config
+    if config is None or "database_settings" not in config.attributes:
+        raise RuntimeError("run this migration through the Lorebase Alembic environment")
+    role: str | None = config.attributes["database_settings"].application_role
+    return role
+
+
+def _quoted(role: str) -> str:
+    quoted: str = op.get_bind().execute(sa.text("SELECT quote_ident(:r)"), {"r": role}).scalar_one()
+    return quoted
+
+
+def _holders() -> list[str]:
+    """Roles other than the owner holding a revoked privilege on the table."""
+    return list(
+        op.get_bind()
+        .execute(
+            sa.text(
+                "SELECT DISTINCT quote_ident(r.rolname) FROM pg_class c "
+                "CROSS JOIN LATERAL aclexplode(c.relacl) a "
+                "JOIN pg_roles r ON r.oid = a.grantee "
+                "WHERE c.oid = to_regclass(:t) AND a.grantee <> c.relowner "
+                "AND a.privilege_type IN "
+                "('UPDATE', 'DELETE', 'TRUNCATE', 'REFERENCES', 'TRIGGER') ORDER BY 1"
+            ),
+            {"t": TABLE},
+        )
+        .scalars()
+        .all()
+    )
+
+
+def upgrade() -> None:
+    op.execute(f"REVOKE {REVOKED} ON TABLE {TABLE} FROM PUBLIC")
+    roles = set(_holders())
+    role = _application_role()
+    if role is not None:
+        roles.add(_quoted(role))
+    for quoted in sorted(roles):
+        op.execute(f"REVOKE {REVOKED} ON TABLE {TABLE} FROM {quoted}")
+
+
+def downgrade() -> None:
+    role = _application_role()
+    if role is not None:
+        op.execute(f"GRANT {RESTORED} ON TABLE {TABLE} TO {_quoted(role)}")