furu 0.0.6__py3-none-any.whl → 0.0.7__py3-none-any.whl

furu/migration.py

@@ -1,594 +1,389 @@
 from __future__ import annotations
 
 import datetime as _dt
-import importlib
-import json
-import shutil
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Literal, TypeAlias, cast, overload
+from typing import Literal, Protocol, cast
 
 import chz
 from chz.util import MISSING as CHZ_MISSING, MISSING_TYPE
-from chz.validators import for_all_fields, typecheck
 
+from .aliases import collect_aliases
 from .config import FURU_CONFIG
-from .core.furu import Furu
-from .runtime.logging import get_logger
+from .schema import (
+    schema_key_from_cls,
+    schema_key_from_furu_obj,
+    schema_key_from_metadata_raw,
+)
 from .serialization import FuruSerializer
 from .serialization.serializer import JsonValue
 from .storage import MetadataManager, MigrationManager, MigrationRecord, StateManager
-from .storage.state import _StateAttemptRunning, _StateResultMigrated
+from .storage.migration import RootKind
+from .storage.state import _StateResultMigrated
 
 
-Primitive: TypeAlias = str | int | float | bool | None
-MigrationValue: TypeAlias = (
-    Primitive | Furu | tuple["MigrationValue", ...] | dict[str, "MigrationValue"]
-)
+class _FuruClass(Protocol):
+    version_controlled: bool
 
+    @classmethod
+    def _namespace(cls) -> Path: ...
 
-@dataclass(frozen=True)
-class NamespacePair:
-    from_namespace: str
-    to_namespace: str
+
+MigrationConflict = Literal["throw", "skip"]
 
 
 @dataclass(frozen=True)
 class FuruRef:
     namespace: str
     furu_hash: str
-    root: Literal["data", "git"]
+    root: RootKind
     directory: Path
 
 
-@dataclass(frozen=True)
-class MigrationCandidate:
-    from_ref: FuruRef
-    to_ref: FuruRef
-    to_namespace: str
-    to_config: dict[str, JsonValue]
-    defaults_applied: dict[str, MigrationValue]
-    fields_dropped: list[str]
-    missing_fields: list[str]
-    extra_fields: list[str]
-
-    def with_default_values(
-        self, values: Mapping[str, MigrationValue]
-    ) -> "MigrationCandidate":
-        if not values:
-            return self
-        updated_defaults = dict(self.defaults_applied)
-        updated_defaults.update(values)
-        return _rebuild_candidate_with_defaults(self, dict(values), updated_defaults)
-
-
 @dataclass(frozen=True)
 class MigrationSkip:
-    candidate: MigrationCandidate
+    source: FuruRef
     reason: str
 
 
-def _rebuild_candidate_with_defaults(
-    candidate: MigrationCandidate,
-    new_defaults: dict[str, MigrationValue],
-    defaults_applied: dict[str, MigrationValue],
-) -> MigrationCandidate:
-    target_class = _resolve_target_class(candidate.to_namespace)
-    updated_config = _typed_config(dict(candidate.to_config))
+@dataclass(frozen=True)
+class MigrationReport:
+    records: list[MigrationRecord]
+    skips: list[MigrationSkip]
 
-    target_fields = _target_field_names(target_class)
-    config_keys = set(updated_config.keys()) - {"__class__"}
-    conflicts = set(new_defaults) & config_keys
-    if conflicts:
-        raise ValueError(
-            "migration: default_values provided for existing fields: "
-            f"{_format_fields(conflicts)}"
-        )
-    unknown = set(new_defaults) - set(target_fields)
-    if unknown:
-        raise ValueError(
-            "migration: default_values contains fields not in target schema: "
-            f"{_format_fields(unknown)}"
-        )
 
-    for field, value in new_defaults.items():
-        updated_config[field] = _serialize_value(value)
+@dataclass(frozen=True)
+class _Source:
+    ref: FuruRef
+    furu_obj: dict[str, JsonValue]
+    migration: MigrationRecord | None
 
-    updated_config["__class__"] = candidate.to_namespace
-    _typecheck_config(updated_config)
 
-    config_keys = set(updated_config.keys()) - {"__class__"}
-    missing_fields = sorted(set(target_fields) - config_keys)
-    if missing_fields:
-        raise ValueError(
-            "migration: missing required fields for target class: "
-            f"{_format_fields(missing_fields)}"
+def migrate(
+    cls: _FuruClass,
+    *,
+    from_schema: Iterable[str] | None = None,
+    from_drop: Iterable[str] | None = None,
+    from_add: Iterable[str] | None = None,
+    from_hash: str | None = None,
+    from_furu_obj: dict[str, JsonValue] | None = None,
+    from_namespace: str | None = None,
+    default_field: Iterable[str] | None = None,
+    set_field: Mapping[str, JsonValue] | None = None,
+    drop_field: Iterable[str] | None = None,
+    rename_field: Mapping[str, str] | None = None,
+    include_alias_sources: bool = False,
+    conflict: MigrationConflict = "throw",
+    origin: str | None = None,
+    note: str | None = None,
+) -> MigrationReport:
+    """
+    Migrate stored objects to the current schema via alias-only records.
+
+    Notes:
+        set_field only adds fields that are not already present. To replace a
+        field, drop it first and then set it.
+    """
+    selector_count = sum(
+        1
+        for value in (
+            from_schema is not None,
+            from_hash is not None,
+            from_furu_obj is not None,
+            from_drop is not None or from_add is not None,
         )
-    extra_fields = sorted(config_keys - set(target_fields))
-    if extra_fields:
+        if value
+    )
+    if selector_count == 0:
         raise ValueError(
-            "migration: extra fields present; use drop_fields to remove: "
-            f"{_format_fields(extra_fields)}"
+            "migration: provide one of from_schema, from_hash, from_furu_obj, or from_drop/from_add"
         )
+    if selector_count > 1:
+        raise ValueError("migration: source selection is ambiguous")
 
-    to_hash = FuruSerializer.compute_hash(updated_config)
-    to_ref = _build_target_ref(target_class, candidate.to_namespace, to_hash)
-    return MigrationCandidate(
-        from_ref=candidate.from_ref,
-        to_ref=to_ref,
-        to_namespace=candidate.to_namespace,
-        to_config=updated_config,
-        defaults_applied=defaults_applied,
-        fields_dropped=candidate.fields_dropped,
-        missing_fields=missing_fields,
-        extra_fields=extra_fields,
-    )
-
-
-MigrationPolicy = Literal["alias", "move", "copy"]
-MigrationConflict = Literal["throw", "skip", "overwrite"]
-
-
-@overload
-def find_migration_candidates(
-    *,
-    namespace: str,
-    to_obj: type[Furu],
-    default_values: Mapping[str, MigrationValue] | None = None,
-    default_fields: Iterable[str] | None = None,
-    drop_fields: Iterable[str] | None = None,
-) -> list[MigrationCandidate]: ...
-
+    namespace = from_namespace or _namespace_str(cls)
 
-@overload
-def find_migration_candidates(
-    *,
-    namespace: NamespacePair,
-    to_obj: None = None,
-    default_values: Mapping[str, MigrationValue] | None = None,
-    default_fields: Iterable[str] | None = None,
-    drop_fields: Iterable[str] | None = None,
-) -> list[MigrationCandidate]: ...
-
-
-def find_migration_candidates(
-    *,
-    namespace: str | NamespacePair,
-    to_obj: type[Furu] | None = None,
-    default_values: Mapping[str, MigrationValue] | None = None,
-    default_fields: Iterable[str] | None = None,
-    drop_fields: Iterable[str] | None = None,
-) -> list[MigrationCandidate]:
-    if namespace is None:
-        raise ValueError("migration: namespace is required")
-    if isinstance(namespace, NamespacePair):
-        if to_obj is not None:
-            raise ValueError("migration: to_obj cannot be used with NamespacePair")
-        from_namespace = namespace.from_namespace
-        to_namespace = namespace.to_namespace
-        target_class = _resolve_target_class(to_namespace)
-    elif isinstance(namespace, str):
-        if not _is_furu_class(to_obj):
-            raise ValueError(
-                "migration: to_obj must be a class (use find_migration_candidates_initialized_target for instances)"
+    if from_schema is not None:
+        from_schema_key = _normalize_schema(from_schema)
+        sources = _sources_from_schema(
+            namespace,
+            from_schema_key,
+            include_alias_sources=include_alias_sources,
+        )
+    elif from_hash is not None:
+        sources = [
+            _source_from_hash(
+                namespace,
+                from_hash,
+                include_alias_sources=include_alias_sources,
             )
-        from_namespace = namespace
-        target_class = to_obj
-        if target_class is None:
-            raise ValueError(
-                "migration: to_obj must be a class (use find_migration_candidates_initialized_target for instances)"
+        ]
+    elif from_furu_obj is not None:
+        sources = [
+            _source_from_furu_obj(
+                namespace,
+                from_furu_obj,
+                include_alias_sources=include_alias_sources,
             )
-        to_namespace = _namespace_str(target_class)
+        ]
     else:
-        raise ValueError("migration: namespace must be str or NamespacePair")
-
-    candidates: list[MigrationCandidate] = []
-    for from_ref, config in _iter_source_configs(from_namespace):
-        candidate = _build_candidate(
-            from_ref,
-            config,
-            to_namespace=to_namespace,
-            target_class=target_class,
-            default_values=default_values,
-            default_fields=default_fields,
-            drop_fields=drop_fields,
-            default_source=None,
+        from_schema_key = _schema_from_drop_add(cls, from_drop, from_add)
+        sources = _sources_from_schema(
+            namespace,
+            from_schema_key,
+            include_alias_sources=include_alias_sources,
         )
-        candidates.append(candidate)
-    return candidates
 
-
-def find_migration_candidates_initialized_target(
-    *,
-    to_obj: Furu,
-    from_namespace: str | None = None,
-    default_fields: Iterable[str] | None = None,
-    drop_fields: Iterable[str] | None = None,
-) -> list[MigrationCandidate]:
-    if isinstance(to_obj, type):
-        raise ValueError(
-            "migration: to_obj must be an instance (use find_migration_candidates for classes)"
-        )
-    if not isinstance(to_obj, Furu):
-        raise ValueError(
-            "migration: to_obj must be an instance (use find_migration_candidates for classes)"
+    if not sources:
+        return MigrationReport(records=[], skips=[])
+
+    alias_index = collect_aliases(include_inactive=True)
+    alias_schema_cache: dict[Path, tuple[str, ...]] = {}
+    seen_alias_schema: set[tuple[tuple[str, str, RootKind], tuple[str, ...]]] = set()
+
+    rename_map = dict(rename_field) if rename_field is not None else {}
+    drop_list = list(drop_field) if drop_field is not None else []
+    default_list = list(default_field) if default_field is not None else []
+    set_map = dict(set_field) if set_field is not None else {}
+
+    records: list[MigrationRecord] = []
+    skips: list[MigrationSkip] = []
+
+    for source in sources:
+        original_ref = resolve_original_ref(source.ref)
+        _ensure_original_success(original_ref)
+
+        target_fields = schema_key_from_cls(cast(type, cls))
+        updated_fields = _apply_transforms(
+            source.furu_obj,
+            target_fields=target_fields,
+            rename_field=rename_map,
+            drop_field=drop_list,
+            default_field=default_list,
+            set_field=set_map,
+            target_class=cls,
         )
 
-    target_class = to_obj.__class__
-    to_namespace = _namespace_str(target_class)
-    source_namespace = from_namespace or to_namespace
-
-    target_config = FuruSerializer.to_dict(to_obj)
-    if not isinstance(target_config, dict):
-        raise TypeError("migration: to_obj must serialize to a dict")
-    target_config = _typed_config(target_config)
-    target_config["__class__"] = to_namespace
-    _typecheck_config(target_config)
-
-    candidates: list[MigrationCandidate] = []
-    for from_ref, config in _iter_source_configs(source_namespace):
-        candidate = _build_candidate(
-            from_ref,
-            config,
-            to_namespace=to_namespace,
-            target_class=target_class,
-            default_values=None,
-            default_fields=default_fields,
-            drop_fields=drop_fields,
-            default_source=to_obj,
-        )
-        aligned = _align_candidate_to_target(candidate, target_config)
-        if aligned is not None:
-            candidates.append(aligned)
-    return candidates
+        target_namespace = _namespace_str(cls)
+        target_obj = dict(updated_fields)
+        target_obj["__class__"] = target_namespace
 
+        obj = FuruSerializer.from_dict(target_obj)
+        target_hash = FuruSerializer.compute_hash(obj)
+        target_ref = _target_ref(cls, target_hash)
+        target_schema_key = schema_key_from_furu_obj(FuruSerializer.to_dict(obj))
 
-@overload
-def apply_migration(
-    candidate: MigrationCandidate,
-    *,
-    policy: MigrationPolicy = "alias",
-    cascade: bool = True,
-    origin: str | None = None,
-    note: str | None = None,
-    conflict: Literal["throw", "overwrite"] = "throw",
-) -> list[MigrationRecord]: ...
+        alias_key = (original_ref.namespace, original_ref.furu_hash, original_ref.root)
+        if (alias_key, target_schema_key) in seen_alias_schema:
+            reason = "migration: alias schema already created in this run"
+            if conflict == "skip":
+                skips.append(MigrationSkip(source=source.ref, reason=reason))
+                continue
+            raise ValueError(reason)
 
+        if _alias_schema_conflict(
+            alias_index,
+            alias_schema_cache,
+            alias_key,
+            target_schema_key,
+        ):
+            reason = "migration: alias schema already exists for original"
+            if conflict == "skip":
+                skips.append(MigrationSkip(source=source.ref, reason=reason))
+                continue
+            raise ValueError(reason)
+
+        record = _write_alias(
+            target_obj=obj,
+            original_ref=original_ref,
+            target_ref=target_ref,
+            source_ref=source.ref,
+            skips=skips,
+            conflict=conflict,
+            origin=origin,
+            note=note,
+        )
+        if record is None:
+            continue
+        records.append(record)
+        seen_alias_schema.add((alias_key, target_schema_key))
 
-@overload
-def apply_migration(
-    candidate: MigrationCandidate,
-    *,
-    policy: MigrationPolicy = "alias",
-    cascade: bool = True,
-    origin: str | None = None,
-    note: str | None = None,
-    conflict: Literal["skip"],
-) -> list[MigrationRecord | MigrationSkip]: ...
+    return MigrationReport(records=records, skips=skips)
 
 
-def apply_migration(
-    candidate: MigrationCandidate,
+def migrate_one(
+    cls: _FuruClass,
     *,
-    policy: MigrationPolicy = "alias",
-    cascade: bool = True,
+    from_hash: str,
+    from_namespace: str | None = None,
+    default_field: Iterable[str] | None = None,
+    set_field: Mapping[str, JsonValue] | None = None,
+    drop_field: Iterable[str] | None = None,
+    rename_field: Mapping[str, str] | None = None,
+    include_alias_sources: bool = False,
+    conflict: MigrationConflict = "throw",
     origin: str | None = None,
     note: str | None = None,
-    conflict: MigrationConflict = "throw",
-) -> list[MigrationRecord | MigrationSkip]:
-    if policy not in {"alias", "move", "copy"}:
-        raise ValueError(f"Unsupported migration policy: {policy}")
-
-    if not cascade:
-        get_logger().warning(
-            "migration: cascade disabled; dependents will not be migrated"
-        )
-
-    cascade_nodes = (
-        _build_cascade_candidates(candidate)
-        if cascade
-        else [_CascadeNode(candidate=candidate, parent=None)]
+) -> MigrationRecord | None:
+    report = migrate(
+        cls,
+        from_hash=from_hash,
+        from_namespace=from_namespace,
+        default_field=default_field,
+        set_field=set_field,
+        drop_field=drop_field,
+        rename_field=rename_field,
+        include_alias_sources=include_alias_sources,
+        conflict=conflict,
+        origin=origin,
+        note=note,
     )
-    parent_map = {node.key: node.parent for node in cascade_nodes}
+    if report.records:
+        return report.records[0]
+    return None
 
-    conflict_statuses: dict[_CandidateKey, str] = {}
-    for node in cascade_nodes:
-        status = _target_status(node.candidate)
-        if status is not None:
-            conflict_statuses[node.key] = status
 
-    if conflict == "throw" and conflict_statuses:
-        status = next(iter(conflict_statuses.values()))
-        raise ValueError(
-            f"migration: target exists with status {status}; pass conflict='overwrite' or conflict='skip'"
-        )
+def current(
+    cls: _FuruClass,
+    *,
+    namespace: str | None = None,
+) -> list[FuruRef]:
+    target_schema = schema_key_from_cls(cast(type, cls))
+    return _refs_by_schema(namespace or _namespace_str(cls), target_schema, match=True)
 
-    skip_keys: set[_CandidateKey] = set()
-    if conflict == "skip" and conflict_statuses:
-        skip_keys = _expand_skip_keys(conflict_statuses.keys(), parent_map)
-        for key in conflict_statuses:
-            status = conflict_statuses[key]
-            get_logger().warning(
-                "migration: skipping candidate due to target status %s",
-                status,
-            )
 
-    results: list[MigrationRecord | MigrationSkip] = []
-    for node in cascade_nodes:
-        if node.key in skip_keys:
-            reason = "migration: skipping candidate due to skipped dependency"
-            if node.key in conflict_statuses:
-                status = conflict_statuses[node.key]
-                reason = f"migration: skipping candidate due to target status {status}"
-            results.append(MigrationSkip(candidate=node.candidate, reason=reason))
-            continue
-        record = _apply_single_migration(
-            node.candidate,
-            policy=policy,
-            origin=origin,
-            note=note,
-            conflict=conflict,
-            conflict_status=conflict_statuses.get(node.key),
+def stale(
+    cls: _FuruClass,
+    *,
+    namespace: str | None = None,
+) -> list[FuruRef]:
+    target_schema = schema_key_from_cls(cast(type, cls))
+    return _refs_by_schema(namespace or _namespace_str(cls), target_schema, match=False)
+
+
+def resolve_original_ref(ref: FuruRef) -> FuruRef:
+    current = ref
+    seen: set[tuple[str, str, RootKind]] = set()
+    while True:
+        record = MigrationManager.read_migration(current.directory)
+        if record is None or record.kind != "alias":
+            return current
+        key = (record.from_namespace, record.from_hash, record.from_root)
+        if key in seen:
+            raise ValueError("migration: alias loop detected")
+        seen.add(key)
+        directory = MigrationManager.resolve_dir(record, target="from")
+        current = FuruRef(
+            namespace=record.from_namespace,
+            furu_hash=record.from_hash,
+            root=record.from_root,
+            directory=directory,
         )
-        results.append(record)
-    return results
-
 
-@dataclass(frozen=True)
-class _CascadeNode:
-    candidate: MigrationCandidate
-    parent: _CandidateKey | None
 
-    @property
-    def key(self) -> "_CandidateKey":
-        return _candidate_key(self.candidate)
+def _schema_from_drop_add(
+    cls: _FuruClass,
+    from_drop: Iterable[str] | None,
+    from_add: Iterable[str] | None,
+) -> tuple[str, ...]:
+    current = set(schema_key_from_cls(cast(type, cls)))
 
+    if from_drop is not None:
+        drop_fields = _normalize_schema(from_drop)
+        missing = set(drop_fields) - current
+        if missing:
+            raise ValueError(
+                f"migration: from_drop fields not in current schema: {_format_fields(missing)}"
+            )
+        current -= set(drop_fields)
 
-_CandidateKey: TypeAlias = tuple[str, str, str]
+    if from_add is not None:
+        add_fields = _normalize_schema(from_add)
+        overlap = set(add_fields) & current
+        if overlap:
+            raise ValueError(
+                f"migration: from_add fields already in current schema: {_format_fields(overlap)}"
+            )
+        current |= set(add_fields)
 
+    return tuple(sorted(current))
 
-def _candidate_key(candidate: MigrationCandidate) -> _CandidateKey:
-    return (
-        candidate.from_ref.namespace,
-        candidate.from_ref.furu_hash,
-        candidate.from_ref.root,
-    )
 
+def _normalize_schema(values: Iterable[str]) -> tuple[str, ...]:
+    keys: set[str] = set()
+    for value in values:
+        if not isinstance(value, str):
+            raise TypeError("migration: schema fields must be strings")
+        if value.startswith("_"):
+            raise ValueError("migration: schema fields cannot start with '_'")
+        keys.add(value)
+    return tuple(sorted(keys))
 
-def _build_cascade_candidates(root: MigrationCandidate) -> list[_CascadeNode]:
-    nodes: list[_CascadeNode] = []
-    queue: list[_CascadeNode] = [_CascadeNode(candidate=root, parent=None)]
-    seen: set[_CandidateKey] = {_candidate_key(root)}
 
-    while queue:
-        node = queue.pop(0)
-        nodes.append(node)
-        for dependent in _find_dependents(node.candidate):
-            key = _candidate_key(dependent)
-            if key in seen:
-                continue
-            seen.add(key)
-            queue.append(_CascadeNode(candidate=dependent, parent=node.key))
-    return nodes
+def _sources_from_schema(
+    namespace: str,
+    schema_key: tuple[str, ...],
+    *,
+    include_alias_sources: bool,
+) -> list[_Source]:
+    sources: list[_Source] = []
+    for ref, metadata in _iter_namespace_metadata(
+        namespace,
+        include_alias_sources=include_alias_sources,
+    ):
+        if schema_key_from_metadata_raw(metadata) != schema_key:
+            continue
+        furu_obj = metadata.get("furu_obj")
+        if not isinstance(furu_obj, dict):
+            raise TypeError("migration: metadata furu_obj must be a dict")
+        migration = MigrationManager.read_migration(ref.directory)
+        sources.append(_Source(ref=ref, furu_obj=furu_obj, migration=migration))
+    return sources
 
 
-def _find_dependents(candidate: MigrationCandidate) -> list[MigrationCandidate]:
-    metadata = MetadataManager.read_metadata_raw(candidate.from_ref.directory)
+def _source_from_hash(
+    namespace: str,
+    furu_hash: str,
+    *,
+    include_alias_sources: bool,
+) -> _Source:
+    ref = _find_ref_by_hash(namespace, furu_hash)
+    metadata = MetadataManager.read_metadata_raw(ref.directory)
     if metadata is None:
-        return []
+        raise FileNotFoundError(f"migration: metadata not found for {ref.directory}")
     furu_obj = metadata.get("furu_obj")
     if not isinstance(furu_obj, dict):
-        return []
-
-    from_hash = candidate.from_ref.furu_hash
-    dependents: list[MigrationCandidate] = []
-
-    for ref, config in _iter_all_configs():
-        updated_config, changed = _replace_dependency(
-            config, from_hash, candidate.to_config
-        )
-        if not changed:
-            continue
-        dependent_namespace = _extract_namespace(updated_config)
-        target_class = _resolve_target_class(dependent_namespace)
-        dependent_candidate = _build_candidate(
-            ref,
-            updated_config,
-            to_namespace=dependent_namespace,
-            target_class=target_class,
-            default_values=None,
-            default_fields=None,
-            drop_fields=None,
-            default_source=None,
+        raise TypeError("migration: metadata furu_obj must be a dict")
+    migration = MigrationManager.read_migration(ref.directory)
+    if not _alias_source_allowed(
+        migration,
+        include_alias_sources=include_alias_sources,
+    ):
+        raise ValueError(
+            "migration: source is an alias; set include_alias_sources=True"
         )
-        if (
-            dependent_candidate.to_ref.furu_hash
-            == dependent_candidate.from_ref.furu_hash
-        ):
-            continue
-        dependents.append(dependent_candidate)
-    return dependents
+    return _Source(ref=ref, furu_obj=furu_obj, migration=migration)
 
 
-def _replace_dependency(
-    value: JsonValue,
-    from_hash: str,
-    to_config: dict[str, JsonValue],
-) -> tuple[JsonValue, bool]:
-    if isinstance(value, dict):
-        if "__class__" in value:
-            if FuruSerializer.compute_hash(value) == from_hash:
-                return dict(to_config), True
-        changed = False
-        updated: dict[str, JsonValue] = {}
-        for key, item in value.items():
-            new_value, was_changed = _replace_dependency(item, from_hash, to_config)
-            if was_changed:
-                changed = True
-            updated[key] = new_value
-        return updated, changed
-    if isinstance(value, list):
-        updated_list: list[JsonValue] = []
-        changed = False
-        for item in value:
-            new_value, was_changed = _replace_dependency(item, from_hash, to_config)
-            if was_changed:
-                changed = True
-            updated_list.append(new_value)
-        return updated_list, changed
-    return value, False
-
-
-def _apply_single_migration(
-    candidate: MigrationCandidate,
+def _source_from_furu_obj(
+    namespace: str,
+    furu_obj: dict[str, JsonValue],
     *,
-    policy: MigrationPolicy,
-    origin: str | None,
-    note: str | None,
-    conflict: MigrationConflict,
-    conflict_status: str | None,
-) -> MigrationRecord:
-    from_dir = candidate.from_ref.directory
-    to_dir = candidate.to_ref.directory
-
-    if conflict == "overwrite" and to_dir.exists():
-        shutil.rmtree(to_dir)
-
-    to_dir.mkdir(parents=True, exist_ok=True)
-    StateManager.ensure_internal_dir(to_dir)
-    now = _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds")
-
-    if policy in {"move", "copy"}:
-        _transfer_payload(from_dir, to_dir, policy)
-        _copy_state(from_dir, to_dir, clear_source=policy == "move")
-    else:
-        _write_migrated_state(to_dir)
-
-    to_obj = FuruSerializer.from_dict(candidate.to_config)
-    metadata = MetadataManager.create_metadata(to_obj, to_dir, ignore_diff=True)
-    MetadataManager.write_metadata(metadata, to_dir)
-
-    default_values = _serialize_default_values(candidate.defaults_applied)
-    record = MigrationRecord(
-        kind=_kind_for_policy(policy),
-        policy=policy,
-        from_namespace=candidate.from_ref.namespace,
-        from_hash=candidate.from_ref.furu_hash,
-        from_root=candidate.from_ref.root,
-        to_namespace=candidate.to_ref.namespace,
-        to_hash=candidate.to_ref.furu_hash,
-        to_root=candidate.to_ref.root,
-        migrated_at=now,
-        overwritten_at=None,
-        default_values=default_values,
-        origin=origin,
-        note=note,
+    include_alias_sources: bool,
+) -> _Source:
+    furu_hash = FuruSerializer.compute_hash(furu_obj)
+    return _source_from_hash(
+        namespace,
+        furu_hash,
+        include_alias_sources=include_alias_sources,
     )
-    MigrationManager.write_migration(record, to_dir)
-
-    if policy != "copy":
-        from_record = MigrationRecord(
-            kind="migrated",
-            policy=policy,
-            from_namespace=candidate.from_ref.namespace,
-            from_hash=candidate.from_ref.furu_hash,
-            from_root=candidate.from_ref.root,
-            to_namespace=candidate.to_ref.namespace,
-            to_hash=candidate.to_ref.furu_hash,
-            to_root=candidate.to_ref.root,
-            migrated_at=now,
-            overwritten_at=None,
-            default_values=default_values,
-            origin=origin,
-            note=note,
-        )
-        MigrationManager.write_migration(from_record, from_dir)
-
-    event: dict[str, str | int] = {
-        "type": "migrated",
-        "policy": policy,
-        "from_namespace": candidate.from_ref.namespace,
-        "from_hash": candidate.from_ref.furu_hash,
-        "to_namespace": candidate.to_ref.namespace,
-        "to_hash": candidate.to_ref.furu_hash,
-    }
-    if default_values is not None:
-        event["default_values"] = json.dumps(default_values, sort_keys=True)
-    StateManager.append_event(to_dir, event)
-    StateManager.append_event(from_dir, event.copy())
-
-    if conflict == "overwrite" and conflict_status is not None:
-        overwrite_event = {
-            "type": "migration_overwrite",
-            "policy": policy,
-            "from_namespace": candidate.from_ref.namespace,
-            "from_hash": candidate.from_ref.furu_hash,
-            "to_namespace": candidate.to_ref.namespace,
-            "to_hash": candidate.to_ref.furu_hash,
-            "reason": "force_overwrite",
-        }
-        StateManager.append_event(to_dir, overwrite_event)
-        StateManager.append_event(from_dir, overwrite_event.copy())
-
-    get_logger().info(
-        "migration: %s -> %s (%s)",
-        from_dir,
-        to_dir,
-        policy,
-    )
-    return record
-
-
-def _transfer_payload(from_dir: Path, to_dir: Path, policy: MigrationPolicy) -> None:
-    for item in from_dir.iterdir():
-        if item.name == StateManager.INTERNAL_DIR:
-            continue
-        destination = to_dir / item.name
-        if policy == "move":
-            shutil.move(str(item), destination)
-            continue
-        if item.is_dir():
-            shutil.copytree(item, destination, dirs_exist_ok=True)
-        else:
-            shutil.copy2(item, destination)
-
-
-def _copy_state(from_dir: Path, to_dir: Path, *, clear_source: bool) -> None:
-    src_internal = from_dir / StateManager.INTERNAL_DIR
-    if not src_internal.exists():
-        return
-    state_path = StateManager.get_state_path(from_dir)
-    if state_path.is_file():
-        shutil.copy2(state_path, StateManager.get_state_path(to_dir))
-    success_marker = StateManager.get_success_marker_path(from_dir)
-    if success_marker.is_file():
-        shutil.copy2(success_marker, StateManager.get_success_marker_path(to_dir))
-    if clear_source:
-        _write_migrated_state(from_dir)
-        StateManager.get_success_marker_path(from_dir).unlink(missing_ok=True)
-
-
-def _write_migrated_state(directory: Path) -> None:
-    def mutate(state) -> None:
-        state.result = _StateResultMigrated(status="migrated")
-        state.attempt = None
-
-    StateManager.update_state(directory, mutate)
 
 
-def _kind_for_policy(policy: MigrationPolicy) -> Literal["alias", "moved", "copied"]:
-    if policy == "alias":
-        return "alias"
-    if policy == "move":
-        return "moved"
-    if policy == "copy":
-        return "copied"
-    raise ValueError(f"Unsupported migration policy: {policy}")
-
-
-def _iter_source_configs(
+def _iter_namespace_metadata(
     namespace: str,
+    *,
+    include_alias_sources: bool,
 ) -> Iterable[tuple[FuruRef, dict[str, JsonValue]]]:
     namespace_path = Path(*namespace.split("."))
     for version_controlled in (False, True):
@@ -602,254 +397,254 @@ def _iter_source_configs(
             metadata = MetadataManager.read_metadata_raw(entry)
             if metadata is None:
                 continue
-            furu_obj = metadata.get("furu_obj")
-            if not isinstance(furu_obj, dict):
+            migration = MigrationManager.read_migration(entry)
+            if not _alias_source_allowed(
+                migration,
+                include_alias_sources=include_alias_sources,
+            ):
                 continue
-            root_kind: str = "git" if version_controlled else "data"
+            root_kind: RootKind = "git" if version_controlled else "data"
             ref = FuruRef(
                 namespace=namespace,
                 furu_hash=entry.name,
                 root=root_kind,
                 directory=entry,
             )
-            yield ref, _typed_config(furu_obj)
+            yield ref, metadata
 
 
-def _iter_all_configs() -> Iterable[tuple[FuruRef, dict[str, JsonValue]]]:
+def _alias_source_allowed(
+    migration: MigrationRecord | None,
+    *,
+    include_alias_sources: bool,
+) -> bool:
+    if migration is None:
+        return True
+    if migration.kind != "alias":
+        return True
+    return include_alias_sources
+
+
+def _find_ref_by_hash(namespace: str, furu_hash: str) -> FuruRef:
+    namespace_path = Path(*namespace.split("."))
+    matches: list[FuruRef] = []
     for version_controlled in (False, True):
         root = FURU_CONFIG.get_root(version_controlled=version_controlled)
-        if not root.exists():
+        directory = root / namespace_path / furu_hash
+        if not directory.is_dir():
             continue
-        for namespace_dir in root.rglob("*"):
-            if not namespace_dir.is_dir():
-                continue
-            state_path = StateManager.get_state_path(namespace_dir)
-            if not state_path.is_file():
-                continue
-            metadata = MetadataManager.read_metadata_raw(namespace_dir)
-            if metadata is None:
-                continue
-            furu_obj = metadata.get("furu_obj")
-            if not isinstance(furu_obj, dict):
-                continue
-            namespace = ".".join(namespace_dir.relative_to(root).parts[:-1])
-            root_kind: str = "git" if version_controlled else "data"
-            ref = FuruRef(
+        root_kind: RootKind = "git" if version_controlled else "data"
+        matches.append(
+            FuruRef(
                 namespace=namespace,
-                furu_hash=namespace_dir.name,
+                furu_hash=furu_hash,
                 root=root_kind,
-                directory=namespace_dir,
+                directory=directory,
             )
-            yield ref, _typed_config(furu_obj)
-
-
-def _build_candidate(
-    from_ref: FuruRef,
-    source_config: dict[str, JsonValue],
-    *,
-    to_namespace: str,
-    target_class: type[Furu],
-    default_values: Mapping[str, MigrationValue] | None,
-    default_fields: Iterable[str] | None,
-    drop_fields: Iterable[str] | None,
-    default_source: Furu | None,
-) -> MigrationCandidate:
-    config = dict(source_config)
-    defaults_applied: dict[str, MigrationValue] = {}
-
-    fields_dropped = _drop_fields(config, drop_fields)
-    target_fields = _target_field_names(target_class)
-
-    default_values_map = dict(default_values) if default_values is not None else {}
-    default_fields_list = list(default_fields) if default_fields is not None else []
-
-    overlap = set(default_values_map) & set(default_fields_list)
-    if overlap:
+        )
+    if not matches:
+        raise FileNotFoundError(
+            f"migration: source not found for namespace={namespace} hash={furu_hash}"
+        )
+    if len(matches) > 1:
         raise ValueError(
-            f"migration: default_fields and default_values overlap: {_format_fields(overlap)}"
+            f"migration: multiple sources found for namespace={namespace} hash={furu_hash}"
         )
+    return matches[0]
+
 
-    existing_fields = set(config.keys()) - {"__class__"}
-    remaining_fields = existing_fields - set(fields_dropped)
-    if default_values_map:
-        conflicts = set(default_values_map) & remaining_fields
-        if conflicts:
+def _apply_transforms(
+    source_obj: dict[str, JsonValue],
+    *,
+    target_fields: tuple[str, ...],
+    rename_field: Mapping[str, str],
+    drop_field: Iterable[str],
+    default_field: Iterable[str],
+    set_field: Mapping[str, JsonValue],
+    target_class: _FuruClass,
+) -> dict[str, JsonValue]:
+    fields = {k: v for k, v in source_obj.items() if k != "__class__"}
+    target_field_set = set(target_fields)
+
+    for old, new in rename_field.items():
+        if old not in fields:
             raise ValueError(
-                f"migration: default_values provided for existing fields: {_format_fields(conflicts)}"
+                f"migration: rename_field missing source field: {_format_fields([old])}"
             )
-        unknown = set(default_values_map) - set(target_fields)
-        if unknown:
+        if new in fields:
             raise ValueError(
-                f"migration: default_values contains fields not in target schema: {_format_fields(unknown)}"
+                f"migration: rename_field target already exists: {_format_fields([new])}"
             )
-
-    if default_fields_list:
-        conflicts = set(default_fields_list) & remaining_fields
-        if conflicts:
+        if new not in target_field_set:
             raise ValueError(
-                f"migration: default_fields provided for existing fields: {_format_fields(conflicts)}"
+                f"migration: rename_field target not in schema: {_format_fields([new])}"
             )
-        unknown = set(default_fields_list) - set(target_fields)
-        if unknown:
+        fields[new] = fields.pop(old)
+
+    for name in drop_field:
+        if name not in fields:
             raise ValueError(
-                f"migration: default_fields contains fields not in target schema: {_format_fields(unknown)}"
+                f"migration: drop_field missing source field: {_format_fields([name])}"
             )
+        fields.pop(name)
 
-    if default_fields_list and default_source is None:
-        missing_defaults = _missing_class_defaults(target_class, default_fields_list)
-        if missing_defaults:
+    for name in default_field:
+        if name not in target_field_set:
             raise ValueError(
-                f"migration: default_fields missing defaults for fields: {_format_fields(missing_defaults)}"
+                f"migration: default_field not in schema: {_format_fields([name])}"
             )
+        if name in fields:
+            continue
+        fields[name] = _serialize_value(_default_value_for_field(target_class, name))
 
-    for field, value in default_values_map.items():
-        defaults_applied[field] = value
-        config[field] = _serialize_value(value)
-
-    for field in default_fields_list:
-        value = _default_value_for_field(target_class, default_source, field)
-        defaults_applied[field] = value
-        config[field] = _serialize_value(value)
-
-    config_keys = set(config.keys()) - {"__class__"}
-    missing_fields = sorted(set(target_fields) - config_keys)
-    if missing_fields:
-        raise ValueError(
-            f"migration: missing required fields for target class: {_format_fields(missing_fields)}"
-        )
-    extra_fields = sorted(config_keys - set(target_fields))
-    if extra_fields:
-        raise ValueError(
-            f"migration: extra fields present; use drop_fields to remove: {_format_fields(extra_fields)}"
-        )
-
-    config["__class__"] = to_namespace
-    to_config = _typed_config(config)
-    _typecheck_config(to_config)
-
-    to_hash = FuruSerializer.compute_hash(to_config)
-    to_ref = _build_target_ref(target_class, to_namespace, to_hash)
-
-    return MigrationCandidate(
-        from_ref=from_ref,
-        to_ref=to_ref,
-        to_namespace=to_namespace,
-        to_config=to_config,
-        defaults_applied=defaults_applied,
-        fields_dropped=fields_dropped,
-        missing_fields=missing_fields,
-        extra_fields=extra_fields,
-    )
-
+    for name, value in set_field.items():
+        if name not in target_field_set:
+            raise ValueError(
+                f"migration: set_field not in schema: {_format_fields([name])}"
+            )
+        if name in fields:
+            raise ValueError(
+                f"migration: set_field already set: {_format_fields([name])}"
+            )
+        fields[name] = _serialize_value(value)
 
-def _drop_fields(
-    config: dict[str, JsonValue], drop_fields: Iterable[str] | None
-) -> list[str]:
-    if drop_fields is None:
-        return []
-    fields = list(drop_fields)
-    unknown = [field for field in fields if field not in config]
-    if unknown:
-        raise ValueError(
-            f"migration: drop_fields contains unknown fields: {_format_fields(unknown)}"
-        )
-    for field in fields:
-        config.pop(field, None)
     return fields
 
 
-def _target_field_names(target_class: type[Furu]) -> list[str]:
-    return [field.logical_name for field in chz.chz_fields(target_class).values()]
-
-
-def _missing_class_defaults(
-    target_class: type[Furu],
-    default_fields: list[str],
-) -> list[str]:
-    fields = chz.chz_fields(target_class)
-    missing: list[str] = []
-    for name in default_fields:
-        field = fields[name]
-        if field._default is not CHZ_MISSING:
-            continue
-        if not isinstance(field._default_factory, MISSING_TYPE):
-            continue
-        missing.append(name)
-    return missing
-
-
-def _default_value_for_field(
-    target_class: type[Furu],
-    default_source: Furu | None,
-    field_name: str,
-) -> MigrationValue:
-    if default_source is not None:
-        return getattr(default_source, field_name)
+def _default_value_for_field(target_class: _FuruClass, name: str) -> JsonValue:
     fields = chz.chz_fields(target_class)
-    field = fields[field_name]
+    fields_by_logical = {field.logical_name: field for field in fields.values()}
+    field = fields_by_logical.get(name)
+    if field is None:
+        raise ValueError(
+            f"migration: default_field missing defaults for fields: {_format_fields([name])}"
+        )
     if field._default is not CHZ_MISSING:
         return field._default
     if not isinstance(field._default_factory, MISSING_TYPE):
         return field._default_factory()
     raise ValueError(
-        f"migration: default_fields missing defaults for fields: {_format_fields([field_name])}"
+        f"migration: default_field missing defaults for fields: {_format_fields([name])}"
     )
 
 
-def _serialize_default_values(
-    values: Mapping[str, MigrationValue],
-) -> dict[str, JsonValue] | None:
-    if not values:
-        return None
-    return {key: _serialize_value(value) for key, value in values.items()}
-
-
-def _serialize_value(value: MigrationValue) -> JsonValue:
+def _serialize_value(value: JsonValue) -> JsonValue:
     result = FuruSerializer.to_dict(value)
     if result is None:
         return result
     if isinstance(result, (str, int, float, bool, list, dict)):
         return result
-    raise TypeError(f"Unsupported migration value type: {type(result)}")
+    raise TypeError(f"migration: unsupported value type {type(result)}")
 
 
-def _align_candidate_to_target(
-    candidate: MigrationCandidate,
-    target_config: dict[str, JsonValue],
-) -> MigrationCandidate | None:
-    if candidate.to_config != target_config:
-        return None
-    return candidate
+def _write_alias(
+    *,
+    target_obj: JsonValue,
+    original_ref: FuruRef,
+    target_ref: FuruRef,
+    source_ref: FuruRef,
+    skips: list[MigrationSkip],
+    conflict: MigrationConflict,
+    origin: str | None,
+    note: str | None,
+) -> MigrationRecord | None:
+    try:
+        target_ref.directory.mkdir(parents=True, exist_ok=False)
+    except FileExistsError:
+        reason = "migration: target already exists"
+        if conflict == "skip":
+            skips.append(MigrationSkip(source=source_ref, reason=reason))
+            return None
+        raise ValueError(reason) from None
+    StateManager.ensure_internal_dir(target_ref.directory)
+    _write_migrated_state(target_ref.directory)
+
+    metadata = MetadataManager.create_metadata(
+        target_obj, target_ref.directory, ignore_diff=True
+    )
+    MetadataManager.write_metadata(metadata, target_ref.directory)
 
+    now = _dt.datetime.now(_dt.UTC).isoformat(timespec="seconds")
+    record = MigrationRecord(
+        kind="alias",
+        policy="alias",
+        from_namespace=original_ref.namespace,
+        from_hash=original_ref.furu_hash,
+        from_root=original_ref.root,
+        to_namespace=target_ref.namespace,
+        to_hash=target_ref.furu_hash,
+        to_root=target_ref.root,
+        migrated_at=now,
+        overwritten_at=None,
+        default_values=None,
+        origin=origin,
+        note=note,
+    )
+    MigrationManager.write_migration(record, target_ref.directory)
+    return record
 
-def _typecheck_config(config: dict[str, JsonValue]) -> None:
-    obj = FuruSerializer.from_dict(config)
-    obj = _normalize_tuple_fields(obj)
-    for_all_fields(typecheck)(obj)
+
+def _write_migrated_state(directory: Path) -> None:
+    def mutate(state) -> None:
+        state.result = _StateResultMigrated(status="migrated")
+        state.attempt = None
+
+    StateManager.update_state(directory, mutate)
 
 
-def _normalize_tuple_fields(obj: Furu) -> Furu:
-    changes: dict[str, object] = {}
-    for field in chz.chz_fields(obj).values():
-        field_type = field.final_type
-        origin = getattr(field_type, "__origin__", None)
-        if field_type is tuple or origin is tuple:
-            value = getattr(obj, field.logical_name)
-            if isinstance(value, list):
-                changes[field.logical_name] = tuple(value)
-    if not changes:
-        return obj
-    return chz.replace(obj, **changes)
+def _ensure_original_success(original_ref: FuruRef) -> None:
+    if not StateManager.success_marker_exists(original_ref.directory):
+        raise ValueError("migration: original artifact is not successful")
+
+
+def _alias_schema_conflict(
+    alias_index: dict[tuple[str, str, RootKind], list[MigrationRecord]],
+    alias_schema_cache: dict[Path, tuple[str, ...]],
+    alias_key: tuple[str, str, RootKind],
+    target_schema_key: tuple[str, ...],
+) -> bool:
+    records = alias_index.get(alias_key, [])
+    for record in records:
+        alias_dir = MigrationManager.resolve_dir(record, target="to")
+        if alias_dir not in alias_schema_cache:
+            metadata = MetadataManager.read_metadata_raw(alias_dir)
+            if metadata is None:
+                raise FileNotFoundError(
+                    f"migration: metadata not found for alias {alias_dir}"
+                )
+            alias_schema_cache[alias_dir] = schema_key_from_metadata_raw(metadata)
+        if alias_schema_cache[alias_dir] == target_schema_key:
+            return True
+    return False
 
 
-def _build_target_ref(
-    target_class: type[Furu],
+def _refs_by_schema(
     namespace: str,
-    furu_hash: str,
-) -> FuruRef:
-    root_kind: str = "git" if target_class.version_controlled else "data"
-    root = FURU_CONFIG.get_root(version_controlled=target_class.version_controlled)
+    schema_key: tuple[str, ...],
+    *,
+    match: bool,
+) -> list[FuruRef]:
+    refs: list[FuruRef] = []
+    for ref, metadata in _iter_namespace_metadata(
+        namespace,
+        include_alias_sources=True,
+    ):
+        current_key = schema_key_from_metadata_raw(metadata)
+        if (current_key == schema_key) == match:
+            refs.append(ref)
+    refs.sort(key=lambda item: item.furu_hash)
+    return refs
+
+
+def _namespace_str(cls: _FuruClass) -> str:
+    return ".".join(cls._namespace().parts)
+
+
+def _target_ref(cls: _FuruClass, furu_hash: str) -> FuruRef:
+    root = FURU_CONFIG.get_root(version_controlled=cls.version_controlled)
+    namespace = _namespace_str(cls)
     directory = root / Path(*namespace.split(".")) / furu_hash
+    root_kind: RootKind = "git" if cls.version_controlled else "data"
     return FuruRef(
         namespace=namespace,
         furu_hash=furu_hash,
@@ -858,72 +653,5 @@ def _build_target_ref(
     )
 
 
-def _resolve_target_class(namespace: str) -> type[Furu]:
-    module_path, _, class_name = namespace.rpartition(".")
-    if not module_path:
-        raise ValueError(f"migration: unable to resolve target class: {namespace}")
-    try:
-        module = importlib.import_module(module_path)
-    except Exception as exc:  # pragma: no cover - import errors
-        raise ValueError(
-            f"migration: unable to resolve target class: {namespace}"
-        ) from exc
-    obj = getattr(module, class_name, None)
-    if obj is None:
-        raise ValueError(f"migration: unable to resolve target class: {namespace}")
-    if not _is_furu_class(obj):
-        raise ValueError(f"migration: unable to resolve target class: {namespace}")
-    return cast(type[Furu], obj)
-
-
-def _is_furu_class(value: object) -> bool:
-    return isinstance(value, type) and issubclass(value, Furu)
-
-
-def _namespace_str(target_class: type[Furu]) -> str:
-    return ".".join(target_class._namespace().parts)
-
-
-def _extract_namespace(config: dict[str, JsonValue]) -> str:
-    class_name = config.get("__class__")
-    if isinstance(class_name, str):
-        return class_name
-    raise ValueError("migration: unable to resolve target class: <unknown>")
-
-
-def _target_status(candidate: MigrationCandidate) -> str | None:
-    to_obj = FuruSerializer.from_dict(candidate.to_config)
-    state = to_obj.get_state(candidate.to_ref.directory)
-    if isinstance(state.result, _StateResultMigrated):
-        return None
-    if state.result.status == "success":
-        return "success"
-    attempt = state.attempt
-    if isinstance(attempt, _StateAttemptRunning):
-        return "running"
-    return None
-
-
-def _expand_skip_keys(
-    conflicts: Iterable[_CandidateKey],
-    parent_map: dict[_CandidateKey, _CandidateKey | None],
-) -> set[_CandidateKey]:
-    skipped = set(conflicts)
-    changed = True
-    while changed:
-        changed = False
-        for key, parent in parent_map.items():
-            if parent is None:
-                continue
-            if parent in skipped and key not in skipped:
-                skipped.add(key)
-                changed = True
-    return skipped
-
-
 def _format_fields(fields: Iterable[str]) -> str:
     return ", ".join(sorted(fields))
-
-
-def _typed_config(config: dict[str, JsonValue]) -> dict[str, JsonValue]:
-    return {str(key): value for key, value in config.items()}