lorebase-core 0.2.3__py3-none-any.whl

lorebase_core/infer/tables.py

@@ -0,0 +1,81 @@
+"""Per-table analysis: normalized names, column analyses and the key choice."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from lorebase_core.infer.columns import ColumnAnalysis, analyze_column
+from lorebase_core.infer.keys import KeyChoice, choose_key, is_minted
+from lorebase_core.infer.names import normalize, singular, strip_prefixes, strip_suffix
+from lorebase_core.infer.options import InferenceOptions
+from lorebase_core.infer.profile import DeclaredForeignKey, TableProfile
+
+
+@dataclass(frozen=True)
+class TableAnalysis:
+    """What inference knows about one table."""
+
+    name: str
+    snake: str
+    singular: str
+    columns: tuple[ColumnAnalysis, ...]
+    rows: int
+    values_read: int
+    key: KeyChoice | None
+    foreign_keys: tuple[DeclaredForeignKey, ...]
+    comment: str | None
+
+    @property
+    def sampled(self) -> bool:
+        return self.rows > self.values_read
+
+    @property
+    def key_column(self) -> ColumnAnalysis | None:
+        """The single key column (also for minted keys), or ``None``."""
+        if self.key is None or self.key.single is None:
+            return None
+        return self.columns[self.key.single]
+
+    def column(self, name: str) -> ColumnAnalysis | None:
+        return next((c for c in self.columns if c.name == name), None)
+
+
+def analyze_table(profile: TableProfile, options: InferenceOptions) -> TableAnalysis:
+    """Analyze every column of ``profile`` and choose its key."""
+    snake = strip_prefixes(normalize(profile.name), options.strip_table_prefixes)
+    single = singular(snake) if options.singular_kind_names else snake
+    columns = tuple(
+        analyze_column(column, index, options) for index, column in enumerate(profile.columns)
+    )
+    values_read = max((c.count for c in columns), default=0)
+    rows = max(profile.row_count or 0, values_read)
+    sampled = rows > values_read
+    reference_like = frozenset(
+        c.index for c in columns if strip_suffix(c.snake, options.foreign_key_suffixes) is not None
+    )
+    names = list(dict.fromkeys((snake, single)))
+    key = choose_key(
+        names, columns, profile.primary_key, options, sampled=sampled, reference_like=reference_like
+    )
+    if key is not None and not key.declared and is_minted(key, columns, options):
+        key = KeyChoice(
+            columns=key.columns,
+            confidence=key.confidence,
+            reasons=(
+                *key.reasons,
+                f"{columns[key.columns[0]].name!r} holds generated ids: Records use minted keys",
+            ),
+            candidates=key.candidates,
+            minted=True,
+        )
+    return TableAnalysis(
+        name=profile.name,
+        snake=snake,
+        singular=single,
+        columns=columns,
+        rows=rows,
+        values_read=values_read,
+        key=key,
+        foreign_keys=profile.foreign_keys,
+        comment=profile.comment,
+    )

lorebase_core/merge/__init__.py

@@ -0,0 +1,89 @@
+"""Three-way merge of Revisions (design 6.8 to 6.10): schema first, then data, then consistency."""
+
+from lorebase_core.merge.conflicts import (
+    CHOICES,
+    GROUPED_KINDS,
+    MACHINE_RESOLVABLE,
+    AutoResolution,
+    Conflict,
+    ConflictKind,
+    Resolution,
+    ResolutionChoice,
+    ResolutionError,
+    Side,
+    UnresolvedConflictsError,
+    conflict_fingerprint,
+)
+from lorebase_core.merge.engine import (
+    IndexViewFactory,
+    LineageLoader,
+    MergeAttempt,
+    MergedTree,
+    MergeInput,
+    MergeOutcome,
+    MergeResult,
+    ProvenanceLoader,
+    apply_resolutions,
+    merge,
+)
+from lorebase_core.merge.index import TreeIndexView
+from lorebase_core.merge.objects import (
+    DOMAIN_KEY,
+    InMemoryObjectStore,
+    MissingObjectError,
+    ObjectStore,
+    SchemaLoader,
+    load_schema,
+    put_schema,
+    schema_from_documents,
+    tree_schema_loader,
+)
+from lorebase_core.merge.policies import (
+    DEFAULT_ATOMIC_PROPERTIES,
+    ORIGIN_LABEL_PREFIXES,
+    ChangeStamp,
+    MergePolicy,
+    PolicyName,
+    origin_labels,
+)
+
+__all__ = [
+    "CHOICES",
+    "DEFAULT_ATOMIC_PROPERTIES",
+    "DOMAIN_KEY",
+    "GROUPED_KINDS",
+    "MACHINE_RESOLVABLE",
+    "ORIGIN_LABEL_PREFIXES",
+    "AutoResolution",
+    "ChangeStamp",
+    "Conflict",
+    "ConflictKind",
+    "InMemoryObjectStore",
+    "IndexViewFactory",
+    "LineageLoader",
+    "MergeAttempt",
+    "MergeInput",
+    "MergeOutcome",
+    "MergePolicy",
+    "MergeResult",
+    "MergedTree",
+    "MissingObjectError",
+    "ObjectStore",
+    "PolicyName",
+    "ProvenanceLoader",
+    "Resolution",
+    "ResolutionChoice",
+    "ResolutionError",
+    "SchemaLoader",
+    "Side",
+    "TreeIndexView",
+    "UnresolvedConflictsError",
+    "apply_resolutions",
+    "conflict_fingerprint",
+    "load_schema",
+    "merge",
+    "origin_labels",
+    "put_schema",
+    "schema_from_documents",
+    "tree_schema_loader",
+]

lorebase_core/merge/conflicts.py

@@ -0,0 +1,262 @@
+"""Conflict taxonomy, fingerprints and resolutions (design 6.9, 6.10).
+
+Every Conflict has a stable code (``DV1`` to ``XS11``) and a fingerprint computed from its
+code, location and the hashes of the three sides. Resolutions are matched to Conflicts by
+fingerprint, so a merge recomputed against a moved target re-applies the resolutions of the
+Conflicts that did not change.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable
+from enum import StrEnum
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue, model_validator
+
+from lorebase_core.canonical import canonical_bytes
+
+__all__ = [
+    "CHOICES",
+    "GROUPED_KINDS",
+    "MACHINE_RESOLVABLE",
+    "AutoResolution",
+    "Conflict",
+    "ConflictKind",
+    "Resolution",
+    "ResolutionChoice",
+    "ResolutionError",
+    "Side",
+    "UnresolvedConflictsError",
+    "conflict_fingerprint",
+]
+
+
+class ConflictKind(StrEnum):
+    """Stable Conflict codes (design 6.9). ``DV`` data, ``SC`` schema, ``XS`` cross-cutting."""
+
+    ATTRIBUTE_VALUE = "DV1"
+    DELETE_MODIFY = "DV2"
+    ADD_ADD = "DV3"
+    SCHEMA_PROPERTY = "SC1"
+    SCHEMA_DELETE_MODIFY = "SC2"
+    NAMING = "SC3"
+    ORPHANED_DATA = "XS1"
+    ORPHANED_VALUE = "XS2"
+    TYPE_COERCION = "XS3"
+    MISSING_VALUE = "XS4"
+    CONSTRAINT = "XS5"
+    CARDINALITY = "XS6"
+    REQUIRED_RELATION = "XS7"
+    UNIQUENESS = "XS8"
+    DANGLING_LINK = "XS9"
+    TRAIT_CONFORMANCE = "XS10"
+    BROKEN_REFERENCE = "XS11"
+
+
+class Side(StrEnum):
+    BASE = "base"
+    OURS = "ours"
+    THEIRS = "theirs"
+
+
+class ResolutionChoice(StrEnum):
+    """How a Conflict is resolved; the meaning per Conflict kind is listed in ``CHOICES``.
+
+    - ``ours``, ``theirs``, ``base``: take that side's value, element or state.
+    - ``custom``: a value given by the resolver (``Resolution.value`` or, for grouped
+      Conflicts, ``Resolution.values`` keyed by member key).
+    - ``drop``: drop the data that breaks the merged schema (orphaned data or values, Records
+      with uncastable values, Records without a required Link, dangling Links).
+    - ``restore``: restore what the other side removed (a Kind, Relation or Attribute, a type
+      before its change, a deleted Record, a referenced schema element).
+    - ``relax``: relax the schema rule that the data breaks (required, constraint,
+      cardinality, ``required_from``, uniqueness, Trait implementation).
+    """
+
+    OURS = "ours"
+    THEIRS = "theirs"
+    BASE = "base"
+    CUSTOM = "custom"
+    DROP = "drop"
+    RESTORE = "restore"
+    RELAX = "relax"
+
+
+_C = ResolutionChoice
+_PICK = (_C.OURS, _C.THEIRS, _C.BASE, _C.CUSTOM)
+
+#: Choices accepted per Conflict kind.
+CHOICES: dict[ConflictKind, tuple[ResolutionChoice, ...]] = {
+    ConflictKind.ATTRIBUTE_VALUE: _PICK,
+    ConflictKind.DELETE_MODIFY: _PICK,
+    ConflictKind.ADD_ADD: _PICK,
+    ConflictKind.SCHEMA_PROPERTY: _PICK,
+    ConflictKind.SCHEMA_DELETE_MODIFY: _PICK,
+    ConflictKind.NAMING: (_C.CUSTOM,),
+    ConflictKind.ORPHANED_DATA: (_C.DROP, _C.RESTORE),
+    ConflictKind.ORPHANED_VALUE: (_C.DROP, _C.RESTORE),
+    ConflictKind.TYPE_COERCION: (_C.CUSTOM, _C.DROP, _C.RESTORE),
+    ConflictKind.MISSING_VALUE: (_C.CUSTOM, _C.RELAX),
+    ConflictKind.CONSTRAINT: (_C.CUSTOM, _C.RELAX),
+    ConflictKind.CARDINALITY: (_C.CUSTOM, _C.RELAX),
+    ConflictKind.REQUIRED_RELATION: (_C.CUSTOM, _C.DROP, _C.RELAX),
+    ConflictKind.UNIQUENESS: (_C.CUSTOM, _C.RELAX),
+    ConflictKind.DANGLING_LINK: (_C.DROP, _C.RESTORE),
+    ConflictKind.TRAIT_CONFORMANCE: (_C.CUSTOM, _C.RELAX),
+    ConflictKind.BROKEN_REFERENCE: (_C.CUSTOM, _C.RESTORE),
+}
+
+#: Kinds a ``MergePolicy`` can resolve without a person (``prefer`` and ``cascade_dangling``;
+#: ``authority`` and ``newest_wins`` for the Attribute Conflicts ``DV1`` and ``DV3``).
+MACHINE_RESOLVABLE = frozenset(
+    {
+        ConflictKind.ATTRIBUTE_VALUE,
+        ConflictKind.DELETE_MODIFY,
+        ConflictKind.ADD_ADD,
+        ConflictKind.SCHEMA_PROPERTY,
+        ConflictKind.SCHEMA_DELETE_MODIFY,
+        ConflictKind.DANGLING_LINK,
+    }
+)
+
+#: Kinds reported as one Conflict over many members, with a count and a sample of keys.
+GROUPED_KINDS = frozenset(
+    {
+        ConflictKind.ORPHANED_DATA,
+        ConflictKind.ORPHANED_VALUE,
+        ConflictKind.TYPE_COERCION,
+        ConflictKind.MISSING_VALUE,
+        ConflictKind.CONSTRAINT,
+        ConflictKind.CARDINALITY,
+        ConflictKind.REQUIRED_RELATION,
+        ConflictKind.UNIQUENESS,
+        ConflictKind.DANGLING_LINK,
+    }
+)
+
+
+def conflict_fingerprint(
+    kind: ConflictKind,
+    partition: str,
+    key: str | None,
+    attribute: str | None,
+    hashes: tuple[bytes | None, bytes | None, bytes | None],
+    members: Iterable[str] = (),
+) -> str:
+    """``sha256(code, partition, key, attribute, base_hash, ours_hash, theirs_hash)``.
+
+    Grouped Conflicts also hash their sorted member keys, so a group that gains or loses
+    members is a different Conflict.
+    """
+    digest = hashlib.sha256()
+    head: list[JsonValue] = [
+        kind.value,
+        partition,
+        key,
+        attribute,
+        *(None if h is None else h.hex() for h in hashes),
+    ]
+    digest.update(canonical_bytes(head))
+    for member in sorted(members):
+        digest.update(b"\x00")
+        digest.update(member.encode("utf-8"))
+    return digest.hexdigest()
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class Conflict(_Frozen):
+    """One Conflict of a merge attempt.
+
+    ``partition`` and ``key`` locate the element (for schema Conflicts the partition is
+    ``schema`` and the key the element id); ``attribute`` is an Attribute id for data
+    Conflicts and a dotted property path for schema Conflicts. ``base``, ``ours`` and
+    ``theirs`` hold the competing values (``None`` means absent) and the ``*_hash`` fields the
+    hashes of the elements they come from. Grouped Conflicts carry ``count`` members and a
+    ``sample`` of their keys.
+    """
+
+    kind: ConflictKind
+    fingerprint: str
+    partition: str
+    key: str | None = None
+    attribute: str | None = None
+    base: JsonValue = None
+    ours: JsonValue = None
+    theirs: JsonValue = None
+    base_hash: str | None = None
+    ours_hash: str | None = None
+    theirs_hash: str | None = None
+    count: int = Field(default=1, ge=1)
+    sample: tuple[str, ...] = ()
+    message: str = ""
+    details: dict[str, JsonValue] = Field(default_factory=dict)
+    choices: tuple[ResolutionChoice, ...] = ()
+    machine_resolvable: bool = False
+
+    @property
+    def grouped(self) -> bool:
+        return self.kind in GROUPED_KINDS
+
+
+class Resolution(_Frozen):
+    """A resolver's decision for the Conflict with ``fingerprint``.
+
+    ``custom`` takes ``value`` (``None`` means absent), or ``values`` keyed by member key for
+    grouped Conflicts.
+    """
+
+    fingerprint: str
+    choice: ResolutionChoice
+    value: JsonValue = None
+    values: dict[str, JsonValue] | None = None
+    resolver: str = ""
+
+    @model_validator(mode="after")
+    def _check_custom(self) -> Self:
+        if self.choice is not ResolutionChoice.CUSTOM and (
+            self.value is not None or self.values is not None
+        ):
+            raise ValueError("only custom resolutions carry a value")
+        return self
+
+    def value_for(self, member: str | None) -> JsonValue:
+        """The custom value for ``member``: its entry in ``values``, else ``value``."""
+        if self.values is not None and member is not None and member in self.values:
+            return self.values[member]
+        return self.value
+
+
+class AutoResolution(_Frozen):
+    """A Conflict resolved by the engine or by a policy, recorded for Lineage and review.
+
+    ``details`` say why a Lineage-based policy decided: the origins matched by ``authority``,
+    the timestamps compared by ``newest_wins``, and the provenance entries they come from.
+    """
+
+    kind: ConflictKind
+    fingerprint: str
+    partition: str
+    key: str | None = None
+    attribute: str | None = None
+    choice: ResolutionChoice
+    resolver: str
+    count: int = Field(default=1, ge=1)
+    sample: tuple[str, ...] = ()
+    details: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class ResolutionError(ValueError):
+    """A resolution that does not fit the merge attempt."""
+
+
+class UnresolvedConflictsError(ResolutionError):
+    """Raised when resolutions leave Conflicts of the attempt open."""
+
+    def __init__(self, fingerprints: Iterable[str]) -> None:
+        self.fingerprints = tuple(sorted(fingerprints))
+        super().__init__(f"{len(self.fingerprints)} conflict(s) left unresolved")