lorebase-store 0.2.3__py3-none-any.whl

lorebase_store/_migrations/versions/0030_path_fanout.py

@@ -0,0 +1,31 @@
+"""The fan-out of materialized path Derivations.
+
+`mat_schema.path_fanout` records the `store.traverse.path_fanout` a branch's materialized
+path Derivations were computed with. A commit, a rebuild or the job worker that finds another
+setting rewrites them (`lorebase_store.materialize.paths`). Existing rows start without one, so
+their materialized paths are rewritten once.
+
+Revision ID: 0030
+Revises: 0029
+Create Date: 2026-10-27 09:00:00.000000
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0030"
+down_revision: str | Sequence[str] | None = "0029"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column("mat_schema", sa.Column("path_fanout", sa.Integer(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("mat_schema", "path_fanout")

lorebase_store/_migrations/versions/0031_branch_builds.py

@@ -0,0 +1,91 @@
+"""Branch builds, copy retries and schema reconciliation.
+
+- `materialization` gains `building`: a branch whose rows a `store.materialize` job writes
+  from the tree of its head in batches (a copy of an overlay or of an older Revision, an
+  overlay detached from its base). Reads of its head and commits answer
+  `branch-materializing` until the job is done.
+- `branch_materializations.strategy`: `base` (copy the base rows an overlay reads, as before)
+  or `tree` (write the rows from the tree of the head).
+- `branch_materializations.failures`: failed jobs of the copy, for the retry backoff and the
+  fallback to a tree build.
+- `branch_materializations.reconcile`: the schema changes a branch got while it was copied
+  (`{"refresh_kinds": [...]}`); the job recomputes derived values, path Links, titles and
+  search vectors after the switch.
+- The `phase` check admits the phases of a tree build and of the reconciliation.
+
+Revision ID: 0031
+Revises: 0030
+Create Date: 2026-10-27 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 = "0031"
+down_revision: str | Sequence[str] | None = "0030"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+TABLE = "branch_materializations"
+PHASES = (
+    "records",
+    "links",
+    "history",
+    "clear",
+    "tree_history",
+    "tree_rows",
+    "switch",
+    "prune",
+    "derived",
+    "paths",
+    "search",
+    "done",
+)
+OLD_PHASES = ("records", "links", "history", "switch", "done")
+
+
+def _phase_check(phases: Sequence[str]) -> str:
+    return "phase IN (" + ", ".join(f"'{p}'" for p in phases) + ")"
+
+
+def upgrade() -> None:
+    op.execute("ALTER TYPE materialization ADD VALUE IF NOT EXISTS 'building'")
+    op.add_column(
+        TABLE, sa.Column("strategy", sa.Text(), server_default=sa.text("'base'"), nullable=False)
+    )
+    op.add_column(
+        TABLE, sa.Column("failures", sa.Integer(), server_default=sa.text("0"), nullable=False)
+    )
+    op.add_column(
+        TABLE, sa.Column("reconcile", postgresql.JSONB(astext_type=sa.Text()), nullable=True)
+    )
+    op.create_check_constraint(
+        op.f("ck_branch_materializations_strategy"), TABLE, "strategy IN ('base', 'tree')"
+    )
+    op.drop_constraint(op.f("ck_branch_materializations_phase"), TABLE, type_="check")
+    op.create_check_constraint(
+        op.f("ck_branch_materializations_phase"), TABLE, _phase_check(PHASES)
+    )
+
+
+def downgrade() -> None:
+    # A branch still building has no materialized head to fall back to: rebuild it first.
+    op.execute(
+        "DELETE FROM branch_materializations WHERE phase NOT IN ("
+        + ", ".join(f"'{p}'" for p in OLD_PHASES)
+        + ")"
+    )
+    op.drop_constraint(op.f("ck_branch_materializations_phase"), TABLE, type_="check")
+    op.create_check_constraint(
+        op.f("ck_branch_materializations_phase"), TABLE, _phase_check(OLD_PHASES)
+    )
+    op.drop_constraint(op.f("ck_branch_materializations_strategy"), TABLE, type_="check")
+    op.drop_column(TABLE, "reconcile")
+    op.drop_column(TABLE, "failures")
+    op.drop_column(TABLE, "strategy")
+    # Postgres cannot drop an enum value; `building` stays unused.

lorebase_store/_migrations/versions/0032_lineage_revisions.py

@@ -0,0 +1,35 @@
+"""Revisions behind the lineage of materialized Records.
+
+`mat_records.lineage_revisions` maps each Attribute of `lineage` to the Revision of its last
+change and `$created` to the Revision that last created the Record, kept by the materializer
+in the commit transaction. Rows written before this revision hold null and their readers
+fall back to the branch history (`mat_history`); a rebuild fills them.
+
+Revision ID: 0032
+Revises: 0031
+Create Date: 2026-10-27 12: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 = "0032"
+down_revision: str | Sequence[str] | None = "0031"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "mat_records",
+        sa.Column("lineage_revisions", postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("mat_records", "lineage_revisions")

lorebase_store/_migrations/versions/0033_vault_moved_tokens.py

@@ -0,0 +1,30 @@
+"""Vault rows remember the key change that took their value over (design 13.5).
+
+`vault.moved_to` is the Record key a key change stored the row's value again under. A moved
+token can be taken over by no other key change and claimed again by no Record, so one value is
+never copied to more than one new key, whichever branch the later attempt is made on.
+
+Revision ID: 0033
+Revises: 0032
+Create Date: 2026-10-28 09:00:00.000000
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0033"
+down_revision: str | Sequence[str] | None = "0032"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column("vault", sa.Column("moved_to", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("vault", "moved_to")

lorebase_store/_migrations/versions/0034_inference_endpoint_modes.py

@@ -0,0 +1,73 @@
+"""Structured output modes learned per chat endpoint.
+
+`inference_endpoint_modes` remembers the mode (`json_schema`, `json_mode` or `prompt`) that a
+chat endpoint was found to need after it rejected a stronger one, so a restarted process does
+not retry the stronger ones; `updated_at` lets readers expire an entry. Keyed by a keyed digest
+of the endpoint, model and output settings; no Domain data. The application role may read,
+insert, update and delete rows, nothing else. The downgrade drops the table: the modes are
+learned again from the next rejections.
+
+Revision ID: 0034
+Revises: 0033
+Create Date: 2026-10-28 09:00:00.000000
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0034"
+down_revision: str | Sequence[str] | None = "0033"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+MODES = "inference_endpoint_modes"
+REVOKED = "TRUNCATE, REFERENCES, TRIGGER"
+GRANTED = "SELECT, INSERT, UPDATE, DELETE"
+
+
+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 upgrade() -> None:
+    op.create_table(
+        MODES,
+        sa.Column("key", sa.LargeBinary(), nullable=False),
+        sa.Column("mode_index", sa.Integer(), nullable=False),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.CheckConstraint(
+            "octet_length(key) = 32", name=op.f("ck_inference_endpoint_modes_key_h32")
+        ),
+        sa.CheckConstraint(
+            "mode_index BETWEEN 0 AND 2", name=op.f("ck_inference_endpoint_modes_mode_index")
+        ),
+        sa.PrimaryKeyConstraint("key", name=op.f("pk_inference_endpoint_modes")),
+    )
+    op.execute(f"REVOKE ALL ON TABLE {MODES} FROM PUBLIC")
+    role = _application_role()
+    if role is not None:
+        quoted = _quoted(role)
+        op.execute(f"REVOKE {REVOKED} ON TABLE {MODES} FROM {quoted}")
+        op.execute(f"GRANT {GRANTED} ON TABLE {MODES} TO {quoted}")
+
+
+def downgrade() -> None:
+    op.drop_table(MODES)

lorebase_store/_migrations/versions/0035_search_truncation.py

@@ -0,0 +1,104 @@
+"""Full-text search that says when its candidate cap cut the ranking (design 8.4; store schema
+notes).
+
+Search ranks at most `p_candidates` matches, taken from the GIN index in physical order. The
+functions of revision 0018 do not say whether the cap was reached, so a caller cannot tell an
+exact ranking from one over a sample of the matches. This revision adds
+`lb_search_bounded(...)` and `lb_search_bounded_overlay(...)`: the arguments, statements and
+checks of `lb_search_corrected` and `lb_search_corrected_overlay`, with one more column,
+`truncated`, true on every row when the candidates of the query as written, or those found
+only through a correction, filled `p_candidates` (a window count over the candidates, which
+are read anyway to be ranked). The store chooses `p_candidates` from the word lexicon's
+counts (`lorebase_store.reads.CommonTerms`): enough for an exact ranking when a term of the
+query is rare enough, a bounded sample when every term is very common.
+
+The functions of revision 0018 stay for processes that still call them. Options, checks and
+grants as in revision 0018.
+
+Revision ID: 0035
+Revises: 0034
+Create Date: 2026-10-29 09:00:00.000000
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from collections.abc import Sequence
+from pathlib import Path
+from types import ModuleType
+
+from alembic import op
+
+revision: str = "0035"
+down_revision: str | Sequence[str] | None = "0034"
+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
+
+
+_lexicon = _revision_module("0018_search_lexicon.py")
+_checks = _lexicon._checks
+_reads = _lexicon._reads
+
+
+def _replaced(text: str, old: str, new: str) -> str:
+    if text.count(old) != 1:
+        raise RuntimeError(f"revision 0018 changed: {old!r} not found once")
+    return text.replace(old, new)
+
+
+LB_SEARCH_BOUNDED = _lexicon.LB_SEARCH_CORRECTED
+for _old, _new in (
+    (
+        "RETURNS TABLE (kind_id text, key text, title text, score real, exact boolean)",
+        "RETURNS TABLE (kind_id text, key text, title text, score real, exact boolean,\n"
+        "               truncated boolean)",
+    ),
+    (
+        "'c.exact FROM (' || v_rows || ') AS c '",
+        "'c.exact, count(*) OVER () >= $6 AS truncated FROM (' || v_rows || ') AS c '",
+    ),
+    (
+        "'AS score, c.exact FROM ((' || v_rows",
+        "'AS score, c.exact, (count(*) FILTER (WHERE c.exact) OVER () >= $6 '\n"
+        "        'OR count(*) FILTER (WHERE NOT c.exact) OVER () >= $6) AS truncated '\n"
+        "        'FROM ((' || v_rows",
+    ),
+):
+    LB_SEARCH_BOUNDED = _replaced(LB_SEARCH_BOUNDED, _old, _new)
+"""Revision 0018's search with the `truncated` column."""
+
+SEARCH = tuple(
+    (name.replace("lb_search_corrected", "lb_search_bounded"), sources, resolve)
+    for name, sources, resolve in _lexicon.SEARCH
+)
+SIGNATURES = tuple(f"{name}{_lexicon._CORRECTED_ARGUMENTS}" for name, _, _ in SEARCH)
+
+
+def upgrade() -> None:
+    role = _reads._application_role()
+    if role is not None:
+        _checks._refuse_writable_schemas(role)
+    search_path = _reads._search_path()
+    options = _reads._OPTIONS.format(search_path=search_path).strip()
+    for name, sources, resolve in SEARCH:
+        guards = _checks._guards(search_path, ("p_candidates", "p_limit")) + resolve
+        template = LB_SEARCH_BOUNDED.format(name=name)
+        statement = _checks._create_or_replace(template, guards)
+        op.execute(statement.format(options=options, sources=sources))
+    _lexicon._grant(SIGNATURES)
+
+
+def downgrade() -> None:
+    for signature in reversed(SIGNATURES):
+        op.execute(f"DROP FUNCTION IF EXISTS {signature}")