rememberstack 0.1.0__py3-none-any.whl

rememberstack/spine/entity_registry.py

@@ -0,0 +1,205 @@
+"""T0 entity resolution over the alias registry (D17): exact match or mint.
+
+T0 is the cheapest cascade tier: an exact match on the normalized
+`llm_canonical` lemma. A miss mints a new canonical entity (the novelty path)
+with its alias, and every resolution — hit or mint — writes the immutable
+mention and an append-only resolution verdict. Higher tiers (T1-T4 blocking
+and adjudication) arrive with the truth-machinery phase.
+"""
+
+from typing import Final
+import unicodedata
+from uuid import UUID
+from uuid import uuid4
+
+from sqlalchemy import bindparam
+from sqlalchemy import JSON
+from sqlalchemy import text
+from sqlalchemy.engine import Engine
+
+from rememberstack.model import ClaimForNormalization
+from rememberstack.model import EntityRef
+from rememberstack.model import ResolvedEntity
+
+T0_RESOLVER_VERSION: Final = "e3-resolver-t0-2026.07"
+"""The T0-only resolver generation (walking skeleton; cascade tiers follow)."""
+
+
+def normalized_lemma(*, surface: str) -> str:
+    """The registry match key: accent-stripped, lowercased, whitespace-folded."""
+    decomposed = unicodedata.normalize("NFKD", surface)
+    stripped = "".join(char for char in decomposed if not unicodedata.combining(char))
+    return " ".join(stripped.lower().split())
+
+
+class EntityRegistry:
+    """Alias-registry resolution and mention/verdict writes for one deployment."""
+
+    def __init__(self, *, engine: Engine) -> None:
+        """Bind the registry to the spine database."""
+        self._engine = engine
+
+    def resolve_t0(
+        self, *, deployment_id: UUID, reference: EntityRef, claim: ClaimForNormalization
+    ) -> ResolvedEntity:
+        """Resolve one reference by exact lemma match, minting on a miss.
+
+        One transaction writes the mention, the entity + alias when minted,
+        and the append-only T0 verdict (D17: verdicts supersede, never edit).
+        """
+        lemma = normalized_lemma(surface=reference.name)
+        with self._engine.begin() as connection:
+            # serialize concurrent mints of one lemma (Codex review: without
+            # this, two workers each mint an entity and facts never collapse):
+            connection.execute(_LOCK_LEMMA, {"key": f"{deployment_id}:lemma:{lemma}"})
+            existing = (
+                connection.execute(
+                    _SELECT_BY_LEMMA, {"deployment_id": deployment_id, "lemma": lemma}
+                )
+                .mappings()
+                .one_or_none()
+            )
+            created = existing is None
+            entity_id = existing["entity_id"] if existing else uuid4()
+            entity_type = existing["type"] if existing else reference.type
+            if created:
+                connection.execute(
+                    _INSERT_ENTITY,
+                    {
+                        "entity_id": entity_id,
+                        "deployment_id": deployment_id,
+                        "type": reference.type,
+                        "canonical_name": reference.name,
+                        "normalized_name": lemma,
+                    },
+                )
+                connection.execute(
+                    _INSERT_ALIAS,
+                    {
+                        "alias_id": uuid4(),
+                        "deployment_id": deployment_id,
+                        "entity_id": entity_id,
+                        "alias_text": reference.name,
+                        "lemma": lemma,
+                    },
+                )
+            mention_id = uuid4()
+            connection.execute(
+                _INSERT_MENTION,
+                {
+                    "mention_id": mention_id,
+                    "deployment_id": deployment_id,
+                    "surface_form": reference.name,
+                    "lemma": lemma,
+                    "canonical_name_form": reference.name,
+                    "emitted_type": reference.type,
+                    "claim_id": claim.claim_id,
+                    "chunk_id": claim.chunk_id,
+                    "doc_id": claim.doc_id,
+                },
+            )
+            connection.execute(
+                _INSERT_DECISION,
+                {
+                    "decision_id": uuid4(),
+                    "deployment_id": deployment_id,
+                    "mention_id": mention_id,
+                    "entity_id": entity_id,
+                    "is_new_entity": created,
+                    "features": {"lemma": lemma},
+                    "resolver_version": T0_RESOLVER_VERSION,
+                },
+            )
+        return ResolvedEntity(
+            entity_id=entity_id, created=created, entity_type=entity_type
+        )
+
+    def claim_already_normalized(self, *, claim_id: UUID) -> bool:
+        """Whether the claim's facts already landed (evidence-backed replay).
+
+        The marker is fact evidence, not mentions — a crash between subject
+        resolution and the fact write must not strand the claim (Codex
+        review). A claim that yielded no facts leaves no marker; its re-run on
+        a crash-retry is bounded by the attempt limit and lands idempotently
+        (mentions/verdicts are append-only transcript rows either way).
+        """
+        return claim_id in self.normalized_claim_ids(claim_ids=(claim_id,))
+
+    def normalized_claim_ids(self, *, claim_ids: tuple[UUID, ...]) -> frozenset[UUID]:
+        """Return every evidence-backed replay marker in one bounded read."""
+        if not claim_ids:
+            return frozenset()
+        with self._engine.connect() as connection:
+            rows = connection.execute(
+                _SELECT_NORMALIZED_CLAIMS, {"claim_ids": list(claim_ids)}
+            ).scalars()
+            return frozenset(rows)
+
+
+_LOCK_LEMMA = text("SELECT pg_advisory_xact_lock(hashtextextended(:key, 0))")
+
+_SELECT_BY_LEMMA = text(
+    """
+    SELECT aliases.entity_id, entities.type FROM aliases
+    JOIN entities ON entities.deployment_id = aliases.deployment_id
+                 AND entities.entity_id = aliases.entity_id
+    WHERE aliases.deployment_id = :deployment_id
+      AND aliases.normalized_lemma = :lemma
+      AND entities.status = 'active'  -- merged/retired never become endpoints;
+                                      -- redirect-following arrives with merges
+    ORDER BY aliases.first_seen
+    LIMIT 1
+    """
+)
+
+_INSERT_ENTITY = text(
+    """
+    INSERT INTO entities (
+        entity_id, deployment_id, type, canonical_name, normalized_name
+    ) VALUES (
+        :entity_id, :deployment_id, :type, :canonical_name, :normalized_name
+    )
+    """
+)
+
+_INSERT_ALIAS = text(
+    """
+    INSERT INTO aliases (
+        alias_id, deployment_id, entity_id, alias_text, normalized_lemma, provenance
+    ) VALUES (
+        :alias_id, :deployment_id, :entity_id, :alias_text, :lemma, 'llm_canonical'
+    )
+    """
+)
+
+_INSERT_MENTION = text(
+    """
+    INSERT INTO mentions (
+        mention_id, deployment_id, surface_form, normalized_lemma,
+        canonical_name_form, emitted_type, claim_id, chunk_id, doc_id
+    ) VALUES (
+        :mention_id, :deployment_id, :surface_form, :lemma,
+        :canonical_name_form, :emitted_type, :claim_id, :chunk_id, :doc_id
+    )
+    """
+)
+
+_INSERT_DECISION = text(
+    """
+    INSERT INTO resolution_decisions (
+        decision_id, deployment_id, mention_id, entity_id, method,
+        confidence, is_new_entity, features, resolver_version
+    ) VALUES (
+        :decision_id, :deployment_id, :mention_id, :entity_id, 'T0',
+        1.0, :is_new_entity, :features, :resolver_version
+    )
+    """
+).bindparams(bindparam("features", type_=JSON))
+
+_SELECT_NORMALIZED_CLAIMS = text(
+    """
+    SELECT claim_id FROM relation_evidence WHERE claim_id = ANY(:claim_ids)
+    UNION
+    SELECT claim_id FROM observation_evidence WHERE claim_id = ANY(:claim_ids)
+    """
+)

rememberstack/spine/extension_packs.py

@@ -0,0 +1,220 @@
+"""Extension-pack installation (registries §4/§7, D15): enable a pack as a unit.
+
+Installing writes the pack's registry rows for one deployment — entity types,
+predicates, and domain/range signatures, all `tier='extension'` with the pack
+id — after verifying every anchor exists (extend-never-fork: an extension
+type MUST declare a registered parent; a pack that forks is refused whole).
+Idempotent: enabling twice is a no-op.
+"""
+
+from uuid import UUID
+
+from sqlalchemy import text
+from sqlalchemy.engine import Connection
+from sqlalchemy.engine import Engine
+
+from rememberstack.core.extension_packs import ExtensionPack
+
+
+class PackAnchorError(Exception):
+    """A pack type's parent is not registered — extend-never-fork refused it."""
+
+
+class PackConflictError(Exception):
+    """A pack name collides with an existing, differently-defined registry row."""
+
+
+def install_pack(*, engine: Engine, deployment_id: UUID, pack: ExtensionPack) -> None:
+    """Enable one pack for one deployment in a single transaction."""
+    with engine.begin() as connection:
+        _require_anchors(connection=connection, deployment_id=deployment_id, pack=pack)
+        _refuse_conflicts(connection=connection, deployment_id=deployment_id, pack=pack)
+        connection.execute(
+            _UPSERT_PACK,
+            {
+                "pack_id": pack.pack_id,
+                "name": pack.name,
+                "description": pack.description,
+            },
+        )
+        connection.execute(
+            _ENABLE_PACK, {"deployment_id": deployment_id, "pack_id": pack.pack_id}
+        )
+        for entity_type in pack.entity_types:
+            connection.execute(
+                _INSERT_TYPE,
+                {
+                    "deployment_id": deployment_id,
+                    "type": entity_type.type,
+                    "parent_type": entity_type.parent_type,
+                    "description": entity_type.description,
+                    "examples": list(entity_type.examples),
+                    "pack_id": pack.pack_id,
+                },
+            )
+        for predicate in pack.predicates:
+            connection.execute(
+                _INSERT_PREDICATE,
+                {
+                    "deployment_id": deployment_id,
+                    "predicate": predicate.predicate,
+                    "description": predicate.description,
+                    "synonyms": list(predicate.synonyms),
+                    "is_change_prone": predicate.is_change_prone,
+                    "pack_id": pack.pack_id,
+                },
+            )
+            for subject_type, object_type in predicate.signatures:
+                connection.execute(
+                    _INSERT_SIGNATURE,
+                    {
+                        "deployment_id": deployment_id,
+                        "predicate": predicate.predicate,
+                        "subject_type": subject_type,
+                        "object_type": object_type,
+                    },
+                )
+
+
+def _require_anchors(
+    *, connection: Connection, deployment_id: UUID, pack: ExtensionPack
+) -> None:
+    """Refuse the whole pack if any anchor is not ALREADY registered (D15).
+
+    Extend-never-fork means every pack type declares a parent that exists in
+    the deployment registry BEFORE the pack installs — a pack-local chain
+    (Child anchored to another type from the same pack) is refused too
+    (Codex review): the DDL's contract is a registered core-side parent.
+    Signatures may reference pack types (they install together).
+    """
+    pack_types = {entity_type.type for entity_type in pack.entity_types}
+    registered = {
+        row[0]
+        for row in connection.execute(_SELECT_TYPES, {"deployment_id": deployment_id})
+    }
+    for entity_type in pack.entity_types:
+        if entity_type.parent_type not in registered:
+            raise PackAnchorError(
+                f"pack {pack.pack_id!r} type {entity_type.type!r} anchors to "
+                f"{entity_type.parent_type!r}, which is not already registered "
+                "(extend-never-fork, D15: pack-local anchors are refused)"
+            )
+    signature_types = {
+        entity_type
+        for predicate in pack.predicates
+        for pair in predicate.signatures
+        for entity_type in pair
+    }
+    unknown = signature_types - (registered | pack_types)
+    if unknown:
+        raise PackAnchorError(
+            f"pack {pack.pack_id!r} signatures reference unregistered "
+            f"types {sorted(unknown)!r}"
+        )
+
+
+def _refuse_conflicts(
+    *, connection: Connection, deployment_id: UUID, pack: ExtensionPack
+) -> None:
+    """Unit installation (Codex review): an existing row under a pack name
+    must BE this pack's row (same pack_id and parent) — anything else fails
+    the whole install rather than silently blending registries."""
+    type_rows = {
+        row[0]: (row[1], row[2])
+        for row in connection.execute(
+            _SELECT_TYPE_DEFS, {"deployment_id": deployment_id}
+        )
+    }
+    for entity_type in pack.entity_types:
+        existing = type_rows.get(entity_type.type)
+        if existing is not None and existing != (entity_type.parent_type, pack.pack_id):
+            raise PackConflictError(
+                f"type {entity_type.type!r} already registered with "
+                f"(parent, pack) = {existing!r}; pack {pack.pack_id!r} "
+                "cannot install over it"
+            )
+    predicate_rows = {
+        row[0]: row[1]
+        for row in connection.execute(
+            _SELECT_PREDICATE_DEFS, {"deployment_id": deployment_id}
+        )
+    }
+    for predicate in pack.predicates:
+        existing_pack = predicate_rows.get(predicate.predicate)
+        if existing_pack is not None and existing_pack != pack.pack_id:
+            raise PackConflictError(
+                f"predicate {predicate.predicate!r} already registered by "
+                f"pack {existing_pack!r}; pack {pack.pack_id!r} cannot "
+                "install over it"
+            )
+
+
+_SELECT_TYPES = text(
+    "SELECT type FROM entity_types WHERE deployment_id = :deployment_id"
+)
+
+_UPSERT_PACK = text(
+    """
+    INSERT INTO extension_packs (pack_id, name, description)
+    VALUES (:pack_id, :name, :description)
+    ON CONFLICT (pack_id) DO NOTHING
+    """
+)
+
+_ENABLE_PACK = text(
+    """
+    INSERT INTO deployment_extension_packs (deployment_id, pack_id)
+    VALUES (:deployment_id, :pack_id)
+    ON CONFLICT (deployment_id, pack_id) DO NOTHING
+    """
+)
+
+_INSERT_TYPE = text(
+    """
+    INSERT INTO entity_types (
+        deployment_id, type, parent_type, description, examples, tier, pack_id
+    ) VALUES (
+        :deployment_id, :type, :parent_type, :description, :examples,
+        'extension', :pack_id
+    )
+    ON CONFLICT (deployment_id, type) DO NOTHING
+    """
+)
+
+_INSERT_PREDICATE = text(
+    """
+    INSERT INTO predicates (
+        deployment_id, predicate, parent_predicate, description, synonyms,
+        is_change_prone, tier, pack_id
+    ) VALUES (
+        :deployment_id, :predicate, 'related_to', :description, :synonyms,
+        :is_change_prone, 'extension', :pack_id
+    )
+    ON CONFLICT (deployment_id, predicate) DO NOTHING
+    """
+)
+
+_INSERT_SIGNATURE = text(
+    """
+    INSERT INTO predicate_signatures (
+        deployment_id, predicate, subject_type, object_type
+    ) VALUES (
+        :deployment_id, :predicate, :subject_type, :object_type
+    )
+    ON CONFLICT (deployment_id, predicate, subject_type, object_type) DO NOTHING
+    """
+)
+
+_SELECT_TYPE_DEFS = text(
+    """
+    SELECT type, parent_type, pack_id FROM entity_types
+    WHERE deployment_id = :deployment_id
+    """
+)
+
+_SELECT_PREDICATE_DEFS = text(
+    """
+    SELECT predicate, pack_id FROM predicates
+    WHERE deployment_id = :deployment_id
+    """
+)