lorebase-store 0.2.3__tar.gz → 0.3.0__tar.gz

{lorebase_store-0.2.3 → lorebase_store-0.3.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: lorebase-store
-Version: 0.2.3
+Version: 0.3.0
 Summary: Lorebase store: persistence, repositories, migrations and materializer
 Requires-Python: >=3.12
 Requires-Dist: alembic>=1.13
 Requires-Dist: asyncpg>=0.29
 Requires-Dist: cryptography>=42
-Requires-Dist: lorebase-core<0.3,>=0.2
-Requires-Dist: lorebase-platform<0.3,>=0.2
+Requires-Dist: lorebase-core<0.4,>=0.3
+Requires-Dist: lorebase-platform<0.4,>=0.3
 Requires-Dist: opentelemetry-api>=1.25
 Requires-Dist: pgvector>=0.3
 Requires-Dist: sqlalchemy[asyncio]>=2.0.30

{lorebase_store-0.2.3 → lorebase_store-0.3.0}/migrations/versions/0001_initial_schema.py

@@ -7,7 +7,8 @@ Besides the tables, this revision installs what model metadata cannot express:
 - native enum types, created once and shared by several tables;
 - `store.layout.hash_partitions` hash partitions on `domain_id`;
 - lz4 TOAST compression of `tree_nodes.body`;
-- the HNSW index of `embeddings` for `store.embeddings.dims`;
+- the HNSW index of `embeddings` for `store.embeddings.dims`, with the build parameters of
+  `store.storage` (`hnsw_m`, `hnsw_ef_construction`);
 - row-level security on `domain_id` keyed to the transaction setting `lorebase.domain_ids`
   (comma-separated Domain ids), bypassed when `lorebase.bypass_rls` is `on`.
 
@@ -100,6 +101,21 @@ def _settings() -> tuple[int, int]:
     return store.layout.hash_partitions, store.embeddings.dims
 
 
+def _hnsw_options() -> str:
+    """`WITH (...)` of the HNSW index from `store.storage.hnsw_m` and `hnsw_ef_construction`
+    (null: pgvector's default)."""
+    storage = op.get_context().config.attributes["store_settings"].storage
+    options = [
+        f"{name} = {value}"
+        for name, value in (
+            ("m", storage.hnsw_m),
+            ("ef_construction", storage.hnsw_ef_construction),
+        )
+        if value is not None
+    ]
+    return f" WITH ({', '.join(options)})" if options else ""
+
+
 def _create_partitions(partitions: int) -> None:
     for table in HASH_PARTITIONED:
         for remainder in range(partitions):
@@ -1024,7 +1040,8 @@ def upgrade() -> None:
     _compress(partitions)
     op.execute(
         f"CREATE INDEX embeddings_hnsw_{dims} ON embeddings "
-        f"USING hnsw ((embedding::vector({dims})) vector_cosine_ops) WHERE dims = {dims}"
+        f"USING hnsw ((embedding::vector({dims})) vector_cosine_ops){_hnsw_options()} "
+        f"WHERE dims = {dims}"
     )
     _enable_row_security(partitions)
 

lorebase_store-0.3.0/migrations/versions/0038_reconciliation_candidates.py

@@ -0,0 +1,131 @@
+"""Reconciliation candidates and validity periods on provenance (design 10.6).
+
+`provenance.valid_from` and `valid_to` hold the validity period of the values of a `valid_time`
+Attribute; existing entries read as "no period" (metadata-only change, no backfill).
+`reconciliation_candidates` holds contradictions between Sources awaiting a decision, one per
+`(domain_id, branch, fingerprint)`. Under the `domain_isolation` policy like every table with
+a `domain_id`.
+
+Revision ID: 0038
+Revises: 0037
+Create Date: 2026-10-29 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 = "0038"
+down_revision: str | Sequence[str] | None = "0037"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+CANDIDATES = "reconciliation_candidates"
+
+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:
+    for column in ("valid_from", "valid_to"):
+        op.add_column("provenance", sa.Column(column, sa.DateTime(timezone=True), nullable=True))
+    op.create_table(
+        CANDIDATES,
+        sa.Column("domain_id", sa.Text(), nullable=False),
+        sa.Column("id", sa.Text(), nullable=False),
+        sa.Column("branch", sa.Text(), nullable=False),
+        sa.Column("type", sa.Text(), nullable=False),
+        sa.Column("status", sa.Text(), server_default=sa.text("'open'"), nullable=False),
+        sa.Column("fingerprint", sa.LargeBinary(), nullable=False),
+        sa.Column("kind_id", sa.Text(), nullable=False),
+        sa.Column("keys", postgresql.JSONB(astext_type=sa.Text()), nullable=False),
+        sa.Column("attribute_id", sa.Text(), nullable=True),
+        sa.Column(
+            "claims",
+            postgresql.JSONB(astext_type=sa.Text()),
+            server_default=sa.text("'[]'::jsonb"),
+            nullable=False,
+        ),
+        sa.Column(
+            "signals",
+            postgresql.JSONB(astext_type=sa.Text()),
+            server_default=sa.text("'{}'::jsonb"),
+            nullable=False,
+        ),
+        sa.Column("claim_count", sa.Integer(), server_default=sa.text("0"), nullable=False),
+        sa.Column("proposal_id", sa.Text(), nullable=True),
+        sa.Column("decision", postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+        sa.Column("decided_by", sa.Text(), nullable=True),
+        sa.Column("decided_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.CheckConstraint(
+            "octet_length(fingerprint) = 32",
+            name=op.f("ck_reconciliation_candidates_fingerprint_h32"),
+        ),
+        sa.CheckConstraint(
+            "type IN ('duplicate', 'contradiction', 'superseded', 'stale')",
+            name=op.f("ck_reconciliation_candidates_type"),
+        ),
+        sa.CheckConstraint(
+            "status IN ('open', 'resolved', 'dismissed', 'obsolete')",
+            name=op.f("ck_reconciliation_candidates_status"),
+        ),
+        sa.ForeignKeyConstraint(
+            ["domain_id"],
+            ["domains.id"],
+            name=op.f("fk_reconciliation_candidates_domain_id_domains"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("domain_id", "id", name=op.f("pk_reconciliation_candidates")),
+        sa.UniqueConstraint(
+            "domain_id",
+            "branch",
+            "fingerprint",
+            name=op.f("uq_reconciliation_candidates_domain_id_branch_fingerprint"),
+        ),
+    )
+    op.create_index(
+        op.f("ix_reconciliation_candidates_domain_id_branch_status_type"),
+        CANDIDATES,
+        ["domain_id", "branch", "status", "type"],
+    )
+    op.create_index(
+        op.f("ix_reconciliation_candidates_domain_id_branch_kind_id_keys"),
+        CANDIDATES,
+        ["domain_id", "branch", "kind_id", "keys"],
+    )
+    op.execute(f"ALTER TABLE {CANDIDATES} ENABLE ROW LEVEL SECURITY")
+    op.execute(f"ALTER TABLE {CANDIDATES} FORCE ROW LEVEL SECURITY")
+    op.execute(
+        f"CREATE POLICY domain_isolation ON {CANDIDATES} "
+        f"USING ({DOMAIN_VISIBLE}) WITH CHECK ({DOMAIN_VISIBLE})"
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        op.f("ix_reconciliation_candidates_domain_id_branch_kind_id_keys"), table_name=CANDIDATES
+    )
+    op.drop_index(
+        op.f("ix_reconciliation_candidates_domain_id_branch_status_type"), table_name=CANDIDATES
+    )
+    op.drop_table(CANDIDATES)
+    for column in ("valid_to", "valid_from"):
+        op.drop_column("provenance", column)

lorebase_store-0.3.0/migrations/versions/0039_reconciliation_lookups.py

@@ -0,0 +1,42 @@
+"""Indexes of reconciliation candidate lookups (design 10.6).
+
+`(domain_id, proposal_id)` serves the `reconciliation` Proposal check and the settlement of a
+merged Proposal; a GIN index (`jsonb_path_ops`) on `keys` serves the containment test of the
+Record page (`keys @> '["key"]'`), which the btree index on `(domain_id, branch, kind_id,
+keys)` cannot answer.
+
+Revision ID: 0039
+Revises: 0038
+Create Date: 2026-10-29 18:00:00.000000
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "0039"
+down_revision: str | Sequence[str] | None = "0038"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+CANDIDATES = "reconciliation_candidates"
+BY_PROPOSAL = "ix_reconciliation_candidates_domain_id_proposal_id"
+BY_KEY = "ix_reconciliation_candidates_keys"
+
+
+def upgrade() -> None:
+    op.create_index(BY_PROPOSAL, CANDIDATES, ["domain_id", "proposal_id"])
+    op.create_index(
+        BY_KEY,
+        CANDIDATES,
+        ["keys"],
+        postgresql_using="gin",
+        postgresql_ops={"keys": "jsonb_path_ops"},
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(BY_KEY, table_name=CANDIDATES)
+    op.drop_index(BY_PROPOSAL, table_name=CANDIDATES)

lorebase_store-0.3.0/migrations/versions/0040_source_written.py

@@ -0,0 +1,148 @@
+"""Last-written state of Sources (design 9.1 "Corrections that stick").
+
+`source_written` holds, per Source, target branch, Kind or Relation and key, the hashes of the
+values the Source last wrote and the Source branch Revision that holds them;
+`source_written_pending` the state a run carries in its open Proposal, moved to
+`source_written` when the Proposal merges. Both are empty at first: Sources seed their state
+on their next run. Under the `domain_isolation` policy like every table with a `domain_id`.
+
+Revision ID: 0040
+Revises: 0039
+Create Date: 2026-10-29 20: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 = "0040"
+down_revision: str | Sequence[str] | None = "0039"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+WRITTEN = "source_written"
+PENDING = "source_written_pending"
+
+DOMAIN_VISIBLE = (
+    "current_setting('lorebase.bypass_rls', true) = 'on' "
+    "OR domain_id = ANY (string_to_array(current_setting('lorebase.domain_ids', true), ','))"
+)
+
+
+def _state_columns() -> list[sa.Column[object]]:
+    return [
+        sa.Column(
+            "written",
+            postgresql.JSONB(astext_type=sa.Text()),
+            server_default=sa.text("'{}'::jsonb"),
+            nullable=False,
+        ),
+        sa.Column("revision_id", sa.LargeBinary(), nullable=True),
+        sa.Column(
+            "value_revisions",
+            postgresql.JSONB(astext_type=sa.Text()),
+            server_default=sa.text("'{}'::jsonb"),
+            nullable=False,
+        ),
+        sa.Column("deleted", sa.Boolean(), server_default=sa.text("false"), nullable=False),
+    ]
+
+
+def _tail_columns() -> list[sa.Column[object]]:
+    return [
+        sa.Column("run_id", sa.Text(), nullable=False),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+    ]
+
+
+def _isolate(table: str) -> None:
+    op.execute(f"ALTER TABLE {table} ENABLE ROW LEVEL SECURITY")
+    op.execute(f"ALTER TABLE {table} FORCE ROW LEVEL SECURITY")
+    op.execute(
+        f"CREATE POLICY domain_isolation ON {table} "
+        f"USING ({DOMAIN_VISIBLE}) WITH CHECK ({DOMAIN_VISIBLE})"
+    )
+
+
+def upgrade() -> None:
+    op.create_table(
+        WRITTEN,
+        sa.Column("domain_id", sa.Text(), nullable=False),
+        sa.Column("source_id", sa.Text(), nullable=False),
+        sa.Column("target_branch", sa.Text(), nullable=False),
+        sa.Column("element", sa.Text(), nullable=False),
+        sa.Column("key", sa.Text(), nullable=False),
+        *_state_columns(),
+        *_tail_columns(),
+        sa.CheckConstraint(
+            "octet_length(revision_id) = 32", name=op.f("ck_source_written_revision_id_h32")
+        ),
+        sa.ForeignKeyConstraint(
+            ["domain_id"],
+            ["domains.id"],
+            name=op.f("fk_source_written_domain_id_domains"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint(
+            "domain_id",
+            "source_id",
+            "target_branch",
+            "element",
+            "key",
+            name=op.f("pk_source_written"),
+        ),
+    )
+    op.create_table(
+        PENDING,
+        sa.Column("domain_id", sa.Text(), nullable=False),
+        sa.Column("proposal_id", sa.Text(), nullable=False),
+        sa.Column("element", sa.Text(), nullable=False),
+        sa.Column("key", sa.Text(), nullable=False),
+        sa.Column("source_id", sa.Text(), nullable=False),
+        sa.Column("target_branch", sa.Text(), nullable=False),
+        *_state_columns(),
+        sa.Column(
+            "preserve",
+            postgresql.JSONB(astext_type=sa.Text()),
+            server_default=sa.text("'[]'::jsonb"),
+            nullable=False,
+        ),
+        *_tail_columns(),
+        sa.CheckConstraint(
+            "octet_length(revision_id) = 32",
+            name=op.f("ck_source_written_pending_revision_id_h32"),
+        ),
+        sa.ForeignKeyConstraint(
+            ["domain_id"],
+            ["domains.id"],
+            name=op.f("fk_source_written_pending_domain_id_domains"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint(
+            "domain_id", "proposal_id", "element", "key", name=op.f("pk_source_written_pending")
+        ),
+    )
+    op.create_index(
+        op.f("ix_source_written_pending_domain_id_source_id_target_branch"),
+        PENDING,
+        ["domain_id", "source_id", "target_branch"],
+    )
+    _isolate(WRITTEN)
+    _isolate(PENDING)
+
+
+def downgrade() -> None:
+    op.drop_index(
+        op.f("ix_source_written_pending_domain_id_source_id_target_branch"), table_name=PENDING
+    )
+    op.drop_table(PENDING)
+    op.drop_table(WRITTEN)

lorebase_store-0.3.0/migrations/versions/0041_document_versions.py

@@ -0,0 +1,121 @@
+"""Document versions and lifecycle (design 9.2 "Document versions and lifecycle", AC-35).
+
+`documents` gains `source_key` (a stable identity: path, URL or external id), `version`,
+`replaces` (the version a new one replaced), `status` (`active`, `superseded`, `retired`,
+`purged`) and who retired or purged it when. Existing rows read as keyless, version 1,
+`active`: the columns are added with defaults, no row is rewritten beyond that.
+
+Indexes: the unique `(domain_id, sha256)` index becomes partial (keyless rows that are not
+purged); keyed rows are unique by `(domain_id, source_key, version)`, at most one version of a
+key is `active` (so the bytes of the current version are unique per key), and
+`(domain_id, source_key, sha256)` finds a version by its bytes.
+
+`extraction_cache` gains `chunk_hash`, the chunk an answer was computed from, so that purging a
+document drops the cached answers of its chunks. Answers cached before keep it null.
+
+Revision ID: 0041
+Revises: 0040
+Create Date: 2026-10-30 09:00:00.000000
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0041"
+down_revision: str | Sequence[str] | None = "0040"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+TABLE = "documents"
+SHA = "ix_documents_domain_id_sha256"
+KEY_VERSION = "ix_documents_domain_id_source_key_version"
+KEY_ACTIVE = "ix_documents_domain_id_source_key_active"
+KEY_SHA = "ix_documents_domain_id_source_key_sha256"
+CACHE = "extraction_cache"
+
+
+def upgrade() -> None:
+    op.add_column(TABLE, sa.Column("source_key", sa.Text(), nullable=True))
+    op.add_column(
+        TABLE, sa.Column("version", sa.Integer(), server_default=sa.text("1"), nullable=False)
+    )
+    op.add_column(TABLE, sa.Column("replaces", sa.Text(), nullable=True))
+    op.add_column(
+        TABLE, sa.Column("status", sa.Text(), server_default=sa.text("'active'"), nullable=False)
+    )
+    for name in ("retired_at", "purged_at"):
+        op.add_column(TABLE, sa.Column(name, sa.DateTime(timezone=True), nullable=True))
+    for name in ("retired_by", "purged_by"):
+        op.add_column(TABLE, sa.Column(name, sa.Text(), nullable=True))
+    op.create_check_constraint(
+        op.f("ck_documents_status"),
+        TABLE,
+        "status IN ('active', 'superseded', 'retired', 'purged')",
+    )
+    op.create_check_constraint(op.f("ck_documents_version"), TABLE, "version >= 1")
+    op.drop_index(op.f(SHA), table_name=TABLE)
+    op.create_index(
+        op.f(SHA),
+        TABLE,
+        ["domain_id", "sha256"],
+        unique=True,
+        postgresql_where=sa.text("source_key IS NULL AND status <> 'purged'"),
+    )
+    op.create_index(
+        op.f(KEY_VERSION),
+        TABLE,
+        ["domain_id", "source_key", "version"],
+        unique=True,
+        postgresql_where=sa.text("source_key IS NOT NULL"),
+    )
+    op.create_index(
+        op.f(KEY_ACTIVE),
+        TABLE,
+        ["domain_id", "source_key"],
+        unique=True,
+        postgresql_where=sa.text("source_key IS NOT NULL AND status = 'active'"),
+    )
+    op.create_index(
+        op.f(KEY_SHA),
+        TABLE,
+        ["domain_id", "source_key", "sha256"],
+        postgresql_where=sa.text("source_key IS NOT NULL"),
+    )
+    op.add_column(CACHE, sa.Column("chunk_hash", sa.LargeBinary(), nullable=True))
+    op.create_check_constraint(
+        op.f("ck_extraction_cache_chunk_hash_h32"), CACHE, "octet_length(chunk_hash) = 32"
+    )
+    op.create_index(
+        op.f("ix_extraction_cache_chunk_hash"),
+        CACHE,
+        ["chunk_hash"],
+        postgresql_where=sa.text("chunk_hash IS NOT NULL"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_extraction_cache_chunk_hash"), table_name=CACHE)
+    op.drop_constraint(op.f("ck_extraction_cache_chunk_hash_h32"), CACHE, type_="check")
+    op.drop_column(CACHE, "chunk_hash")
+    op.drop_index(op.f(KEY_SHA), table_name=TABLE)
+    op.drop_index(op.f(KEY_ACTIVE), table_name=TABLE)
+    op.drop_index(op.f(KEY_VERSION), table_name=TABLE)
+    op.drop_index(op.f(SHA), table_name=TABLE)
+    # Keyed versions and purged rows may share bytes with other rows; nothing is deleted here:
+    # the downgrade stops instead, and the operator decides which rows to keep.
+    op.execute(
+        "DO $$ BEGIN IF EXISTS (SELECT 1 FROM documents GROUP BY domain_id, sha256 "
+        "HAVING count(*) > 1) THEN RAISE EXCEPTION 'documents share bytes (versions or purged "
+        "rows): remove the extra rows before downgrading below 0041'; END IF; END $$"
+    )
+    op.create_index(op.f(SHA), TABLE, ["domain_id", "sha256"], unique=True)
+    op.drop_constraint(op.f("ck_documents_version"), TABLE, type_="check")
+    op.drop_constraint(op.f("ck_documents_status"), TABLE, type_="check")
+    for name in ("purged_by", "retired_by", "purged_at", "retired_at"):
+        op.drop_column(TABLE, name)
+    for name in ("status", "replaces", "version", "source_key"):
+        op.drop_column(TABLE, name)

lorebase_store-0.3.0/migrations/versions/0042_proposal_kinds.py

@@ -0,0 +1,37 @@
+"""The Kinds a Proposal touches (design 10.7, stewards).
+
+`proposals.kinds` lists the ids of the Kinds whose Records or Links (either end) the
+Proposal's changes touch, refreshed with each merge attempt, so the steward roles of a
+Proposal are an index lookup. Existing rows read null ("not computed yet") until their next
+merge preview; a GIN index serves the containment test.
+
+Revision ID: 0042
+Revises: 0041
+Create Date: 2026-10-31 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 = "0042"
+down_revision: str | Sequence[str] | None = "0041"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+TABLE = "proposals"
+INDEX = "ix_proposals_kinds"
+
+
+def upgrade() -> None:
+    op.add_column(TABLE, sa.Column("kinds", postgresql.ARRAY(sa.Text()), nullable=True))
+    op.create_index(INDEX, TABLE, ["kinds"], postgresql_using="gin")
+
+
+def downgrade() -> None:
+    op.drop_index(INDEX, table_name=TABLE)
+    op.drop_column(TABLE, "kinds")

lorebase_store-0.3.0/migrations/versions/0043_source_last_seen.py

@@ -0,0 +1,36 @@
+"""When a Source last saw each element (design 9.1 "Incremental Sources").
+
+`source_written.last_seen_run` and `last_seen_at` name the run of an `incremental` Source that
+last read the element upstream, changed or not, and when. The reconciliation sweep raises a
+`stale` candidate (`source_unseen`) for Records no run has seen for longer than the Source's
+`stale_after`. Both are null on existing rows; readers fall back to `updated_at` (the last
+state advance) until the next run sees the element. Additive: no data is rewritten.
+
+Revision ID: 0043
+Revises: 0042
+Create Date: 2026-10-31 12:00:00.000000
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0043"
+down_revision: str | Sequence[str] | None = "0042"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+TABLE = "source_written"
+
+
+def upgrade() -> None:
+    op.add_column(TABLE, sa.Column("last_seen_run", sa.Text(), nullable=True))
+    op.add_column(TABLE, sa.Column("last_seen_at", sa.DateTime(timezone=True), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column(TABLE, "last_seen_at")
+    op.drop_column(TABLE, "last_seen_run")

lorebase_store-0.3.0/migrations/versions/0044_mat_records_object_hash_index.py

@@ -0,0 +1,85 @@
+"""Index `mat_records` on `(domain_id, branch, object_hash)` for semantic search.
+
+`embeddings` joins `mat_records` on `(domain_id, object_hash)` (design 8.8, filtered semantic
+search). Without an index on that side of the join the planner cannot drive the HNSW scan lazily
+under a nested loop: it hash-joins every vector of the model with the Records and sorts, a cost
+linear in the table (82 ms at 100,000 vectors, 270 ms at 300,000). With it the HNSW index is read
+and the Records are probed per candidate.
+
+The index is built per partition with `CREATE INDEX CONCURRENTLY` (writes are not blocked),
+attached to an index created `ON ONLY` the parent; an invalid leftover of an interrupted run is
+rebuilt, as in revisions 0011 and 0026. Re-running changes nothing.
+
+Revision ID: 0044
+Revises: 0043
+Create Date: 2026-10-31 15:00:00.000000
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0044"
+down_revision: str | Sequence[str] | None = "0043"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+PARENT = "mat_records"
+INDEX = "ix_mat_records_object_hash"
+DEFINITION = "(domain_id, branch, object_hash)"
+SUFFIX = "domain_id_branch_object_hash_idx"
+"""Partition indexes are named `<partition>_<suffix>`."""
+
+
+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 upgrade() -> None:
+    op.execute(f"CREATE INDEX IF NOT EXISTS {INDEX} ON ONLY {PARENT} {DEFINITION}")
+    with op.get_context().autocommit_block():
+        for partition in _partitions():
+            name = f"{partition}_{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} {DEFINITION}")
+            if state is None or not state[1]:
+                op.execute(f"ALTER INDEX {INDEX} ATTACH PARTITION {name}")
+    if _state(INDEX) != (True, False):
+        raise RuntimeError(f"index {INDEX} is not valid after attaching every partition")
+
+
+def downgrade() -> None:
+    op.execute(f"DROP INDEX IF EXISTS {INDEX}")