lorebase-store 0.2.3__py3-none-any.whl

lorebase_store/materialize/verify.py

@@ -0,0 +1,321 @@
+"""Verification of a materialized head against its tree (design 6.11, invariant I4).
+
+Recomputes what the tree at the branch head says the materialized rows must be and compares:
+the schema partition hash, the set of `(key, object_hash)` of every Kind and Relation
+partition, and the per-partition counts. With `deep=True`, Record and Link values and Record
+titles are also recomputed from the stored objects. With `derived=True`, derived values are
+recomputed from the materialized Records and Links (`materialize.derived`, nothing written) and
+compared with the stored ones, and so are the Links of materialized path Derivations
+(`materialize.paths`), which the tree comparison leaves out.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from lorebase_core.model import Schema
+from lorebase_core.tree import PARTITION_SCHEMA, kind_partition, link_key, relation_partition
+from lorebase_store.commit.schema import load_compiled
+from lorebase_store.materialize.derived import DerivedValues
+from lorebase_store.materialize.paths import PathLinks
+from lorebase_store.materialize.rebuild import load_schema
+from lorebase_store.materialize.rows import (
+    PartitionType,
+    parse_partition,
+    record_title,
+)
+from lorebase_store.materialize.sensitivity import branch_tagged_schema
+from lorebase_store.nodestore import NodeRepository
+from lorebase_store.objectstore import PgObjectStore
+from lorebase_store.repositories.materialized import MaterializedRepository
+from lorebase_store.repositories.refs import RefRepository
+from lorebase_store.repositories.revisions import RevisionRepository
+from lorebase_store.repositories.scope import scope_to_domain
+from lorebase_store.runtime import StoreRuntime
+
+
+class DivergenceReason(StrEnum):
+    SCHEMA_MISSING = "schema_missing"
+    SCHEMA_MISMATCH = "schema_mismatch"
+    MISSING_ROW = "missing_row"
+    EXTRA_ROW = "extra_row"
+    HASH_MISMATCH = "hash_mismatch"
+    VALUES_MISMATCH = "values_mismatch"
+    COUNT_MISMATCH = "count_mismatch"
+    DERIVED_MISMATCH = "derived_mismatch"
+    SENSITIVITY_STALE = "sensitivity_stale"
+    """A title materialized before the default branch tagged the title Attribute: stale,
+    not corrupt; the next change of the Kind on the branch, or a rebuild, recomputes it."""
+
+
+@dataclass(frozen=True, slots=True)
+class Divergence:
+    """One difference between the tree-derived view and the materialized rows.
+
+    `expected` comes from the tree, `actual` from the materialized rows.
+    """
+
+    reason: DivergenceReason
+    partition: str
+    key: str | None = None
+    expected: Any = None
+    actual: Any = None
+
+
+@dataclass
+class VerifyReport:
+    domain_id: str
+    branch: str
+    head: bytes
+    partitions: int = 0
+    rows: int = 0
+    divergences: list[Divergence] = field(default_factory=list)
+    truncated: bool = False
+    _limit: int = 1000
+
+    @property
+    def ok(self) -> bool:
+        return not self.divergences
+
+    def add(self, divergence: Divergence) -> None:
+        if len(self.divergences) >= self._limit:
+            self.truncated = True
+            return
+        self.divergences.append(divergence)
+
+
+async def verify(
+    session: AsyncSession,
+    domain_id: str,
+    branch: str,
+    *,
+    runtime: StoreRuntime,
+    deep: bool = False,
+    derived: bool = False,
+) -> VerifyReport:
+    """Compare the materialized head of `branch` with the tree at its head (and, with
+    `derived`, its derived values with recomputed ones)."""
+    settings = runtime.settings
+    batch = settings.materialize.read_batch_rows
+    await scope_to_domain(session, domain_id)
+    ref = await RefRepository(session, domain_id).require(branch)
+    head = await RevisionRepository(session, domain_id).require(ref.head)
+    report = VerifyReport(
+        domain_id, branch, head.id, _limit=settings.materialize.verify_max_divergences
+    )
+    repository = MaterializedRepository(session, domain_id, branch, writes=settings.writes)
+    nodes = NodeRepository(
+        session, domain_id, writes=settings.writes, batch=settings.nodes.prefetch_batch
+    )
+    objects = PgObjectStore(session, domain_id, writes=settings.writes, batch=batch)
+    tree = await nodes.load_tree(head.root)
+
+    schema, schema_hash = await load_schema(session, domain_id, tree, runtime=runtime)
+    tagged = await branch_tagged_schema(session, domain_id, branch, schema, runtime=runtime)
+    stored_schema = await repository.schema()
+    if stored_schema is None:
+        report.add(Divergence(DivergenceReason.SCHEMA_MISSING, PARTITION_SCHEMA))
+    elif stored_schema.schema_hash != schema_hash or (
+        deep and load_compiled(stored_schema.compiled) != schema
+    ):
+        report.add(
+            Divergence(
+                DivergenceReason.SCHEMA_MISMATCH,
+                PARTITION_SCHEMA,
+                expected=schema_hash.hex(),
+                actual=stored_schema.schema_hash.hex(),
+            )
+        )
+
+    counts = {kind_partition(k): n for k, n in (await repository.record_counts()).items()}
+    counts.update({relation_partition(r): n for r, n in (await repository.link_counts()).items()})
+    partitions = {p: ref.count for p, ref in tree.partitions.items() if p != PARTITION_SCHEMA}
+    for partition in sorted(partitions.keys() | counts.keys()):
+        report.partitions += 1
+        expected_count = partitions.get(partition, 0)
+        actual_count = counts.get(partition, 0)
+        if expected_count != actual_count:
+            report.add(
+                Divergence(
+                    DivergenceReason.COUNT_MISMATCH,
+                    partition,
+                    expected=expected_count,
+                    actual=actual_count,
+                )
+            )
+        expected: dict[str, bytes] = {}
+        if partition in tree.partitions:
+            async for entries in nodes.scan(tree.partitions[partition].root):
+                expected.update(entries)
+        actual = await _materialized(repository, partition, batch=batch)
+        report.rows += len(actual)
+        _compare_hashes(report, partition, expected, {k: v[0] for k, v in actual.items()})
+        if deep:
+            await _compare_values(report, partition, expected, actual, objects, tagged, schema)
+    if derived:
+        await _compare_derived(report, repository, schema, runtime, head.created_at)
+        await _compare_paths(report, repository, schema, runtime)
+    return report
+
+
+async def _compare_derived(
+    report: VerifyReport,
+    repository: MaterializedRepository,
+    schema: Schema,
+    runtime: StoreRuntime,
+    at: Any,
+) -> None:
+    """Recompute every derived value without writing and compare with the stored ones."""
+    settings = runtime.settings.materialize
+    recomputed = DerivedValues(
+        repository,
+        schema,
+        limits=runtime.schema.expression_limits,
+        now=at,
+        batch=settings.read_batch_rows,
+        max_incremental=settings.derivation_max_incremental_records,
+        fanout=runtime.settings.traverse.path_fanout,
+        write=False,
+    )
+    await recomputed.recompute_all()
+    for kind_id in sorted(await repository.record_counts()):
+        async for rows in repository.stream_records(kind_id, batch=settings.read_batch_rows):
+            for row in rows:
+                want = recomputed.expected.get((kind_id, row.key), {})
+                if row.derived != want:
+                    report.add(
+                        Divergence(
+                            DivergenceReason.DERIVED_MISMATCH,
+                            kind_partition(kind_id),
+                            row.key,
+                            expected=want,
+                            actual=row.derived,
+                        )
+                    )
+
+
+async def _compare_paths(
+    report: VerifyReport, repository: MaterializedRepository, schema: Schema, runtime: StoreRuntime
+) -> None:
+    """Recompute the Links of every materialized path Derivation without writing and compare
+    them with the stored ones (and report Links of paths no longer materialized)."""
+    settings = runtime.settings
+    paths = PathLinks(
+        repository,
+        schema,
+        fanout=settings.traverse.path_fanout,
+        batch=settings.materialize.read_batch_rows,
+        max_incremental=settings.materialize.derivation_max_incremental_records,
+        write=False,
+    )
+    known = {path.id for path in paths.paths}
+    for path_id, count in sorted((await repository.link_counts(derived=True)).items()):
+        if path_id not in known:
+            report.add(
+                Divergence(
+                    DivergenceReason.DERIVED_MISMATCH,
+                    relation_partition(path_id),
+                    expected=0,
+                    actual=count,
+                )
+            )
+    for path in paths.paths:
+        await paths.compute_all(path)
+        want = paths.expected.get(path.id, set())
+        got = await paths.stored(path)
+        for from_key, to_key in sorted(want ^ got):
+            report.add(
+                Divergence(
+                    DivergenceReason.DERIVED_MISMATCH,
+                    relation_partition(path.id),
+                    link_key(from_key, to_key),
+                    expected=(from_key, to_key) in want,
+                    actual=(from_key, to_key) in got,
+                )
+            )
+
+
+async def _materialized(
+    repository: MaterializedRepository, partition: str, *, batch: int
+) -> dict[str, tuple[bytes, dict[str, Any] | None, str | None]]:
+    """`key -> (object_hash, values, title)` of a partition's materialized rows."""
+    parsed = parse_partition(partition)
+    rows: dict[str, tuple[bytes, dict[str, Any] | None, str | None]] = {}
+    if parsed.type is PartitionType.KIND:
+        async for records in repository.stream_records(parsed.element_id, batch=batch):
+            rows.update((r.key, (r.object_hash, r.values, r.title)) for r in records)
+    else:
+        async for links in repository.stream_links(parsed.element_id, batch=batch):
+            rows.update(
+                (link_key(r.from_key, r.to_key), (r.object_hash, r.values, None)) for r in links
+            )
+    return rows
+
+
+def _compare_hashes(
+    report: VerifyReport, partition: str, expected: Mapping[str, bytes], actual: Mapping[str, bytes]
+) -> None:
+    for key in sorted(expected.keys() | actual.keys()):
+        want, got = expected.get(key), actual.get(key)
+        if want == got:
+            continue
+        if got is None:
+            reason = DivergenceReason.MISSING_ROW
+        elif want is None:
+            reason = DivergenceReason.EXTRA_ROW
+        else:
+            reason = DivergenceReason.HASH_MISMATCH
+        report.add(
+            Divergence(
+                reason,
+                partition,
+                key,
+                expected=None if want is None else want.hex(),
+                actual=None if got is None else got.hex(),
+            )
+        )
+
+
+async def _compare_values(
+    report: VerifyReport,
+    partition: str,
+    expected: Mapping[str, bytes],
+    actual: Mapping[str, tuple[bytes, dict[str, Any] | None, str | None]],
+    objects: PgObjectStore,
+    schema: Schema,
+    own: Schema | None = None,
+) -> None:
+    """`schema` has the default branch's tags added; `own` is the branch's own schema, which
+    tells a stale title (`SENSITIVITY_STALE`) from a wrong one."""
+    common = sorted(expected.keys() & actual.keys())
+    bodies = await objects.get_many(expected[key] for key in common)
+    parsed = parse_partition(partition)
+    kind = schema.kinds.get(parsed.element_id) if parsed.type is PartitionType.KIND else None
+    for key in common:
+        body = bodies.get(expected[key])
+        want_values = {} if body is None else dict(body.body.get("values", {}))
+        _, got_values, got_title = actual[key]
+        want_title = record_title(kind, want_values) if kind is not None else None
+        if got_values != want_values or got_title != want_title:
+            own_kind = None if own is None else own.kinds.get(parsed.element_id)
+            stale = (
+                got_values == want_values
+                and own_kind is not None
+                and got_title == record_title(own_kind, want_values)
+            )
+            report.add(
+                Divergence(
+                    DivergenceReason.SENSITIVITY_STALE
+                    if stale
+                    else DivergenceReason.VALUES_MISMATCH,
+                    partition,
+                    key,
+                    expected={"values": want_values, "title": want_title},
+                    actual={"values": got_values, "title": got_title},
+                )
+            )

lorebase_store/merging/__init__.py

@@ -0,0 +1,39 @@
+"""Merging Proposals over the store: merge attempts, Conflicts, resolutions, merge commits."""
+
+from lorebase_store.merging.attempts import (
+    AttemptComputation,
+    ConflictState,
+    Decision,
+    check_resolution,
+    complete_provenance,
+    compute_attempt,
+    decisions_of,
+    taken_provenance,
+)
+from lorebase_store.merging.lineage import BranchLineage
+from lorebase_store.merging.service import (
+    MERGE_ORIGIN,
+    MERGE_REASON,
+    AttemptResult,
+    MergeRequest,
+    MergeService,
+    ProposalBranchMissingError,
+)
+
+__all__ = [
+    "MERGE_ORIGIN",
+    "MERGE_REASON",
+    "AttemptComputation",
+    "AttemptResult",
+    "BranchLineage",
+    "ConflictState",
+    "Decision",
+    "MergeRequest",
+    "MergeService",
+    "ProposalBranchMissingError",
+    "check_resolution",
+    "complete_provenance",
+    "compute_attempt",
+    "decisions_of",
+    "taken_provenance",
+]

lorebase_store/merging/attempts.py

@@ -0,0 +1,334 @@
+"""Merge attempts computed from stored resolutions (design 6.10), independent of storage.
+
+`compute_attempt` runs the core merge with the resolutions of a Proposal. Resolutions are
+stored by fingerprint and may outnumber the Conflicts of the current run: a Conflict can
+appear only once another one is resolved (a custom value that breaks uniqueness), and a
+resolution can lose its Conflict when a head moves. The merge is therefore re-run with the
+resolutions that matched so far until no new one matches; every Conflict seen on the way is
+reported as open (in the final run) or resolved (its resolution was applied), and resolutions
+that never matched are returned as unmatched.
+
+`complete_provenance` attributes every change of a merge Revision: values taken from the
+source keep their provenance, values decided by a resolution get the provenance entry of that
+resolution (`merge_resolution`, design 6.10) and the rest the merge's own entry. Only the
+Attributes a change sets are attributed (`taken_provenance`): an element taken whole from the
+source brings the source's whole Lineage, and its unchanged values keep the Revision that last
+changed them on the target.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, replace
+from typing import Any
+
+from lorebase_core.merge import (
+    CHOICES,
+    AutoResolution,
+    Conflict,
+    ConflictKind,
+    MergeAttempt,
+    MergedTree,
+    MergeInput,
+    MergeOutcome,
+    ObjectStore,
+    Resolution,
+    ResolutionChoice,
+    ResolutionError,
+    merge,
+)
+from lorebase_core.model import looks_like_reference
+from lorebase_core.revision import ChangesetEntry
+from lorebase_core.tree import PARTITION_SCHEMA
+from lorebase_store.materialize.rows import ELEMENT_PROVENANCE_KEY, changed_attributes
+
+__all__ = [
+    "AttemptComputation",
+    "ConflictState",
+    "Decision",
+    "check_resolution",
+    "complete_provenance",
+    "compute_attempt",
+    "decisions_of",
+    "taken_provenance",
+]
+
+#: Grouped kinds whose custom resolution may give values for some members only.
+_PARTIAL_CUSTOM = frozenset({ConflictKind.UNIQUENESS, ConflictKind.REQUIRED_RELATION})
+
+
+@dataclass(frozen=True)
+class ConflictState:
+    """A Conflict of an attempt with its full member keys and its state.
+
+    `resolution` is the stored resolution that applies to it. An open Conflict with a
+    resolution was `rejected`: the merge reported it again after applying the resolution.
+    """
+
+    conflict: Conflict
+    members: tuple[str, ...]
+    open: bool
+    resolution: Resolution | None = None
+
+    @property
+    def rejected(self) -> bool:
+        return self.open and self.resolution is not None
+
+
+@dataclass(frozen=True)
+class AttemptComputation:
+    """Outcome of a merge with stored resolutions applied."""
+
+    outcome: MergeOutcome
+    conflicts: tuple[ConflictState, ...]
+    applied: tuple[Resolution, ...]
+    unmatched: tuple[str, ...]
+
+    @property
+    def clean(self) -> bool:
+        return isinstance(self.outcome, MergedTree)
+
+    @property
+    def open_count(self) -> int:
+        return sum(1 for state in self.conflicts if state.open)
+
+    @property
+    def resolved_count(self) -> int:
+        return sum(1 for state in self.conflicts if not state.open)
+
+
+def compute_attempt(
+    merge_input: MergeInput, resolutions: Iterable[Resolution]
+) -> AttemptComputation:
+    """Merge `merge_input` with the stored `resolutions` (see the module docstring).
+
+    Raises `ResolutionError` when a stored resolution does not fit its Conflict.
+    """
+    stored = {r.fingerprint: r for r in resolutions}
+    applied: dict[str, Resolution] = {}
+    seen: dict[str, tuple[Conflict, tuple[str, ...]]] = {}
+    outcome: MergeOutcome | None = None
+    for _ in range(len(stored) + 1):
+        outcome = merge(replace(merge_input, resolutions=tuple(applied.values())))
+        if isinstance(outcome, MergeAttempt):
+            for conflict in outcome.conflicts:
+                if conflict.fingerprint not in seen:
+                    members = tuple(outcome.members.get(conflict.fingerprint, ()))
+                    seen[conflict.fingerprint] = (conflict, members)
+        matched = {fp: r for fp, r in stored.items() if fp in seen and fp not in applied}
+        if not matched:
+            break
+        applied.update(matched)
+    assert outcome is not None
+    open_now = (
+        {c.fingerprint: c for c in outcome.conflicts} if isinstance(outcome, MergeAttempt) else {}
+    )
+    states: list[ConflictState] = []
+    for fingerprint, (conflict, members) in seen.items():
+        if fingerprint in open_now:
+            states.append(
+                ConflictState(
+                    open_now[fingerprint], members, open=True, resolution=applied.get(fingerprint)
+                )
+            )
+        elif fingerprint in applied:
+            states.append(
+                ConflictState(conflict, members, open=False, resolution=applied[fingerprint])
+            )
+    return AttemptComputation(
+        outcome=outcome,
+        conflicts=tuple(states),
+        applied=tuple(applied.values()),
+        unmatched=tuple(fp for fp in stored if fp not in applied),
+    )
+
+
+def check_resolution(conflict: Conflict, members: Sequence[str], resolution: Resolution) -> None:
+    """Raise `ResolutionError` unless `resolution` is acceptable for `conflict`.
+
+    The choice must be one of the Conflict kind's choices; a custom resolution of a grouped
+    Conflict given per member must cover every member unless it also has a default `value`
+    (uniqueness and required relation Conflicts accept values for some members only).
+    """
+    if resolution.fingerprint != conflict.fingerprint:
+        raise ResolutionError("the resolution names another Conflict")
+    if resolution.choice not in CHOICES[conflict.kind]:
+        allowed = ", ".join(c.value for c in CHOICES[conflict.kind])
+        raise ResolutionError(
+            f"{resolution.choice.value} does not resolve a {conflict.kind.value} Conflict "
+            f"(accepted: {allowed})"
+        )
+    if resolution.choice is ResolutionChoice.CUSTOM and (
+        _holds_reference((conflict.base, conflict.ours, conflict.theirs))
+        or _holds_reference((resolution.value, resolution.values))
+    ):
+        # A custom value would bypass the vault (design 13.5), and a reference would copy
+        # another Record's value: vault values are resolved by picking a side.
+        raise ResolutionError(
+            "a Conflict over vault values takes one of its sides, not a custom value"
+        )
+    if (
+        resolution.choice is ResolutionChoice.CUSTOM
+        and resolution.values is not None
+        and resolution.value is None
+        and conflict.kind not in _PARTIAL_CUSTOM
+    ):
+        missing = [m for m in members if m not in resolution.values]
+        if missing:
+            raise ResolutionError(
+                f"custom values miss {len(missing)} member(s), for example {missing[0]!r}"
+            )
+
+
+def _holds_reference(value: Any) -> bool:
+    """Whether a vault reference appears anywhere in `value`."""
+    if looks_like_reference(value):
+        return True
+    if isinstance(value, Mapping):
+        return any(_holds_reference(item) for item in value.values())
+    if isinstance(value, list | tuple):
+        return any(_holds_reference(item) for item in value)
+    return False
+
+
+# Provenance -------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Decision:
+    """A resolution or automatic resolution, located for attribution."""
+
+    fingerprint: str
+    resolver: str
+    choice: ResolutionChoice
+    partition: str
+    key: str | None
+    attribute: str | None
+    members: tuple[str, ...] = ()
+
+
+def decisions_of(
+    computation: AttemptComputation, auto: Sequence[AutoResolution] = ()
+) -> list[Decision]:
+    """Decisions of a clean merge: applied resolutions, then automatic resolutions."""
+    found: list[Decision] = []
+    for state in computation.conflicts:
+        if state.resolution is None or state.open:
+            continue
+        conflict = state.conflict
+        found.append(
+            Decision(
+                fingerprint=conflict.fingerprint,
+                resolver=state.resolution.resolver,
+                choice=state.resolution.choice,
+                partition=conflict.partition,
+                key=conflict.key,
+                attribute=conflict.attribute,
+                members=state.members or conflict.sample,
+            )
+        )
+    for item in auto:
+        found.append(
+            Decision(
+                fingerprint=item.fingerprint,
+                resolver=item.resolver,
+                choice=item.choice,
+                partition=item.partition,
+                key=item.key,
+                attribute=item.attribute,
+                members=item.sample,
+            )
+        )
+    return found
+
+
+def _index(decisions: Sequence[Decision]) -> dict[tuple[str, str, str | None], Decision]:
+    """Decisions by `(partition, key, attribute)`; schema decisions by element only."""
+    index: dict[tuple[str, str, str | None], Decision] = {}
+    for decision in decisions:
+        attribute = None if decision.partition == PARTITION_SCHEMA else decision.attribute
+        keys = [decision.key] if decision.key is not None else []
+        keys.extend(decision.members)
+        for key in keys:
+            index.setdefault((decision.partition, key, attribute), decision)
+    return index
+
+
+def _values(objects: ObjectStore, digest: bytes | None) -> Mapping[str, Any] | None:
+    if digest is None:
+        return None
+    body = objects.get(digest)
+    if not isinstance(body, dict):
+        return None
+    values = body.get("values")
+    return values if isinstance(values, dict) else {}
+
+
+def _changed(entry: ChangesetEntry, objects: ObjectStore) -> list[str] | None:
+    """Attributes whose value the change sets; None for schema elements and deletions."""
+    if entry.partition == PARTITION_SCHEMA or entry.new_hash is None:
+        return None
+    return changed_attributes(
+        _values(objects, entry.old_hash), _values(objects, entry.new_hash) or {}
+    )
+
+
+def _restricted(entry: ChangesetEntry, changed: list[str] | None) -> dict[str, str]:
+    if changed is None:
+        return dict(entry.provenance)
+    kept = {*changed, ELEMENT_PROVENANCE_KEY}
+    return {a: p for a, p in entry.provenance.items() if a in kept}
+
+
+def taken_provenance(
+    entries: Sequence[ChangesetEntry], objects: ObjectStore
+) -> list[ChangesetEntry]:
+    """Entries whose provenance names only the Attributes they change (and the element key);
+    schema elements and deletions are kept as they are."""
+    return [
+        replace(entry, provenance=_restricted(entry, _changed(entry, objects))) for entry in entries
+    ]
+
+
+def complete_provenance(
+    entries: Sequence[ChangesetEntry],
+    objects: ObjectStore,
+    decisions: Sequence[Decision],
+    decision_ids: Mapping[str, str],
+    fallback: str,
+) -> tuple[list[ChangesetEntry], set[str]]:
+    """Entries whose provenance covers every changed Attribute; returns the decisions used.
+
+    `decision_ids` maps decision fingerprints to provenance entry ids; `fallback` is the id
+    used for changes that neither the source nor a decision accounts for. Provenance of
+    Attributes a change leaves as they are is dropped (`taken_provenance`).
+    """
+    index = _index(decisions)
+    used: set[str] = set()
+
+    def decided(partition: str, key: str, attribute: str | None) -> str | None:
+        decision = index.get((partition, key, attribute))
+        if decision is None and attribute is not None:
+            decision = index.get((partition, key, None))
+        if decision is None or decision.fingerprint not in decision_ids:
+            return None
+        used.add(decision.fingerprint)
+        return decision_ids[decision.fingerprint]
+
+    completed: list[ChangesetEntry] = []
+    for entry in entries:
+        found = _changed(entry, objects)
+        provenance = _restricted(entry, found)
+        changed = found or []
+        for attribute in changed:
+            chosen = decided(entry.partition, entry.key, attribute)
+            if chosen is not None:
+                provenance[attribute] = chosen
+            elif attribute not in provenance:
+                provenance[attribute] = fallback
+        if not changed:
+            chosen = decided(entry.partition, entry.key, None)
+            if chosen is not None or not provenance:
+                provenance = {ELEMENT_PROVENANCE_KEY: chosen or fallback}
+        completed.append(replace(entry, provenance=provenance))
+    return completed, used