Office365-REST-Python-Client 3.2.0__py3-none-any.whl → 3.3.1__py3-none-any.whl

office365/migration/sharepoint/adapters.py

@@ -10,81 +10,726 @@ Lazy imports keep the migration core client-agnostic.
 
 from __future__ import annotations
 
-import hashlib
 import io
-from collections.abc import Callable
-from datetime import timezone
-from typing import TYPE_CHECKING, cast
-
-from office365.migration.adapters import MigrationProgress
-from office365.migration.base import MigrationItem, PermissionEntry
+from collections.abc import Callable, Iterable
+from enum import Enum
+from typing import TYPE_CHECKING, Any, cast
+
+from typing_extensions import TypeAlias
+
+from office365.migration.adapters import MigrationProgress, checksum
+from office365.migration.base import (
+    MigrationItem,
+    PermissionEntry,
+    Principal,
+    conflict_to_on_conflict,
+    normalize_puid,
+)
+from office365.migration.sharepoint.structure import ListStructure, provision_list_structure
 from office365.migration.sharepoint.transfer import Failure
-from office365.runtime.converters.json_file import record_to_json
-from office365.runtime.converters.scalars import iso_or_none, parse_datetime, parse_int
+from office365.runtime.converters.records import records_from_items
+from office365.runtime.converters.scalars import (
+    iso_or_none,
+    iso_z,
+    normalize_guid,
+    parse_datetime,
+    parse_int,
+    wall_clock_text,
+)
+from office365.runtime.converters.value import values_of
 from office365.runtime.limits import DEFAULT_BATCH_SIZE
+from office365.runtime.odata.comparable import digest
 from office365.runtime.operations import emit_progress
+from office365.runtime.schema import TypeSchema
+from office365.runtime.types.odata_property import AUTHORSHIP, MODERATION, PERMISSIONS
+from office365.sharepoint.exceptions import SPFieldValidationException
 from office365.sharepoint.fields.builtin_field_name import SYSTEM_FIELD_NAMES
+from office365.sharepoint.fields.lookup import FieldLookup
+from office365.sharepoint.listitems.listitem import ListItem
+from office365.sharepoint.listitems.moderation_status import SPModerationStatusType
+from office365.sharepoint.permissions import SiteLevel, site_access
+from office365.sharepoint.permissions.securable_object import SecurableObject
+from office365.sharepoint.principal.type import PrincipalType
+from office365.sharepoint.taxonomy.field import TaxonomyField
+from office365.sharepoint.taxonomy.field_value import TaxonomyFieldValue
+from office365.sharepoint.taxonomy.field_value_col import TaxonomyFieldValueCollection
 
 if TYPE_CHECKING:
+    from office365.migration.map import ContentTypeMap
+    from office365.sharepoint.fields.field import Field
     from office365.sharepoint.files.file import File
     from office365.sharepoint.folders.folder import Folder
     from office365.sharepoint.lists.list import List as SPList
     from office365.sharepoint.permissions.roles.definitions.definition import RoleDefinition
+    from office365.sharepoint.principal.users.user import User
+    from office365.sharepoint.webs.web import Web
+
+_LIST_ITEM = TypeSchema.of(ListItem)
+_SECURABLE = TypeSchema.of(SecurableObject)
+
+
+def _cloned_context(obj):
+    """A fresh ``ClientContext`` clone for ``obj`` (same auth + transport, own queue)."""
+    ctx = obj.context
+    return ctx.clone(ctx.base_url)
+
+
+def _cloned_list(sp_list: "SPList", context=None) -> "SPList":
+    """The same list, addressed by id and loaded on ``context`` (or a clone of it)."""
+    list_id = sp_list.id
+    if not list_id:
+        raise ValueError("cannot rebind a list that was never loaded")
+    ctx = context if context is not None else _cloned_context(sp_list)
+    return ctx.web.lists.get_by_id(list_id).get().execute_query()
+
+
+def _cloned_folder(folder: "Folder", context=None) -> "Folder":
+    """The same folder, addressed by server-relative path and loaded on ``context``."""
+    server_relative_url = folder.server_relative_url
+    if not server_relative_url:
+        raise ValueError("cannot rebind a folder that was never loaded")
+    ctx = context if context is not None else _cloned_context(folder)
+    return ctx.web.get_folder_by_server_relative_path(server_relative_url).get().execute_query()
+
+
+#: The target's typed columns: ``(lookup: name -> referenced list id, user names,
+#: multi-lookup: name -> referenced list id, multi-user names, taxonomy:
+#: name -> (allows many, hidden note field internal name), multi-choice names)``.
+_TypedColumns: TypeAlias = (
+    "tuple[dict[str, str], set[str], dict[str, str], set[str], dict[str, tuple[bool, str | None]], set[str]]"
+)
+
+#: Always-projected system metadata: the author/editor ids an item is restored from and
+#: the unique-ACL flag. ``*`` omits them, so they are asked for by the role they play.
+_METADATA_SELECT = [*_LIST_ITEM.columns_of_facet(AUTHORSHIP), *_LIST_ITEM.columns_of_facet(PERMISSIONS)]
+
+#: Marker column added to a migrated list recording each item's source id. It makes
+#: a re-run idempotent and lets post-run verification pair source and target items.
+DEFAULT_LIST_IDENTITY_FIELD = "MigrationSourceId"
+# Authorship has its own fidelity path (``apply_authorship``); the ``Author``/``Editor``
+# columns are the payload companions of the authorship ids, so they are neither content
+# nor Person values to remap.
+_PERSON_EXCLUDED = frozenset(
+    name[: -len("Id")] for name in _LIST_ITEM.columns_of_facet(AUTHORSHIP) if name.endswith("Id")
+)
+
+#: Moderation columns of a list item. They only exist on a list whose
+#: ``EnableModeration`` is on, so selecting them unconditionally fails outright.
+#: They are ordinary record content: a list item takes a moderation change in the same
+#: system update as its timestamps (a document refuses it — see ``apply_item_state``),
+#: so captured state rides in that one write and no version is created.
+_MODERATION_FIELDS = _LIST_ITEM.columns_of_facet(MODERATION)
+
+#: The moderation column carrying the approval status; its sibling carries the comment.
+_MODERATION_STATUS = _LIST_ITEM.name_of("moderation_status")
+
+#: How many paths a per-run warning names before it summarizes the rest.
+_WARNING_SAMPLE = 5
+
+
+def _scalar_mapping(value: Any) -> dict | None:
+    """A value object as a plain mapping with scalar members, or ``None``.
+
+    Only a shallow mapping of scalars is accepted, so a navigation property (a
+    ``ClientObject``) or a typed payload carrying a nested ``__metadata`` is never
+    mistaken for a column value.
+    """
+    if not isinstance(value, dict) or not value:
+        return None
+    if any(item is not None and not isinstance(item, (str, int, float, bool)) for item in value.values()):
+        return None
+    return dict(value)
+
+
+#: Record columns a faithful copy does not compare: what ``ListItem`` declares
+#: server-assigned or reachable by ``$expand``. What remains is the item's *content*,
+#: which a faithful copy preserves.
+#:
+#: A deny-list, not ``ListItem._schema.content_columns``: a record carries the site columns
+#: the tenant defines, which the CSDL does not declare, and a set built from declared names
+#: would drop exactly the columns a faithful copy exists to carry.
+_CONTENT_EXCLUDED = frozenset(ListItem._schema.readonly) | frozenset(ListItem._schema.navigations)
+
+
+def _folder_value_columns(fields: list[Any]) -> set[str]:
+    """The columns a folder's own metadata can live in (writable, non-system).
+
+    A read of a folder also returns computed and read-only columns (link filenames,
+    compliance flags, version labels); writing those is rejected and comparing them
+    would only echo the folder's own name back.
+    """
+    return {
+        field.internal_name
+        for field in fields
+        if field.internal_name
+        # An underscore-prefixed internal name is SharePoint's own storage column; it
+        # is not reliably projectable (the same rule the safe fallback projection uses).
+        and not field.internal_name.startswith("_")
+        and not field.hidden
+        and not field.read_only_field
+        and not field.field_type_kind.is_server_assigned
+        and field.internal_name not in _FOLDER_RECORD_EXCLUDED
+    }
+
+
+#: What a folder record never travels to the target with, or never compares by: the
+#: columns the model declares server-assigned or as navigations -- minus the content
+#: type, because a document set's content type is part of what makes the folder what it
+#: is. A library's sort/stream bookkeeping columns are hidden read-only ones the field
+#: scan already skips, and ``FileLeafRef`` is a ``FieldType.File`` column the type
+#: declares server-assigned, so neither needs naming here.
+_FOLDER_RECORD_EXCLUDED = _CONTENT_EXCLUDED - {"ContentTypeId"}
+
+
+def _content_checksum(record: dict, extra_excluded: "frozenset[str]" = frozenset()) -> str:
+    """MD5 of an item's content columns in a stable, order-independent form.
+
+    The list source and target both use this so record content can be reconciled:
+    only scalar, multi-value and value-object columns are hashed (navigation
+    properties and excluded keys are dropped) and keys are sorted, so the two sides
+    agree regardless of property iteration order. A null column is treated as
+    absent: the source drops an empty multi-value column while the target reads it
+    back as ``None``, and both mean "no value".
+    """
+    content = {}
+    for key, value in record.items():
+        if key in _CONTENT_EXCLUDED or key in extra_excluded or value is None:
+            continue
+        if isinstance(value, (str, int, float, bool, list, tuple)):
+            content[key] = value
+            continue
+        mapping = _scalar_mapping(value)
+        if mapping is not None:
+            content[key] = mapping
+    return digest(content)
+
+
+def _folder_record_values(record: dict) -> dict:
+    """The column values of a folder item that travel to (or compare with) the target.
+
+    The projection already narrows the read to the folder's own writable columns; here
+    only the identity/system columns are dropped, and an empty value is treated as
+    absent on both sides — a source read reports ``""`` where a target read reports
+    ``None``, and both mean "no value".
+    """
+    return {
+        key: value for key, value in record.items() if key not in _FOLDER_RECORD_EXCLUDED and value not in (None, "")
+    }
 
-_TAXONOMY_FIELD_TYPES = {"TaxonomyFieldType", "TaxonomyFieldTypeMulti"}
 
-# Always-projected system metadata (reliable author/editor identity).
-_METADATA_SELECT = ["AuthorId", "EditorId"]
+def _typed_keys(names: Iterable[str]) -> set[str]:
+    """The companions a Lookup/Person column's value is carried in, for each column."""
+    return {key for name in names for key in (ListItem.value_column(name), ListItem.string_value_column(name))}
 
 
-def _sp_timestamp(value: str | None) -> str | None:
-    """Normalize an ISO-8601 timestamp to the ``...Z`` UTC form SharePoint expects.
+def _taxonomy_terms(value: Any) -> list[dict[str, str]]:
+    """A taxonomy cell as portable ``{"TermGuid": ...}`` terms.
 
-    ``ValidateUpdateListItem`` (``datesInUTC=True``) rejects the ``+00:00`` offset
-    form the migration items carry, so convert to a naive UTC ``Z`` string.
+    Only ``TermGuid`` is carried: a per-site ``WssId`` is meaningless elsewhere and
+    ``Label`` is not authoritative (a read may return the WssId string, and the
+    server resolves a write by term id regardless of the label).
     """
-    if not value:
+    terms: list[dict[str, str]] = []
+    for item in values_of(value) or []:
+        guid = item.get("TermGuid") if isinstance(item, dict) else getattr(item, "TermGuid", None)
+        if guid:
+            terms.append({"TermGuid": str(guid)})
+    return terms
+
+
+def _is_taxonomy_value(value: Any) -> bool:
+    """Whether a projected value is a taxonomy term (single value or a collection)."""
+    return bool(_taxonomy_terms(value))
+
+
+def _taxonomy_guids(value: Any) -> list[str]:
+    return [term["TermGuid"] for term in _taxonomy_terms(value)]
+
+
+def _canonicalize_taxonomy_record(record: dict) -> dict:
+    """Replace taxonomy values with a sorted list of term ids for comparison.
+
+    ``Label`` is cosmetic and ``WssId`` is site-local, so neither belongs in the
+    content checksum; the term id is the portable identity. Sorting also keeps the
+    checksum independent of the order a read happens to return the terms in.
+    """
+    if not any(_is_taxonomy_value(value) for value in record.values()):
+        return record
+    canonical = dict(record)
+    for key, value in record.items():
+        if _is_taxonomy_value(value):
+            canonical[key] = sorted(_taxonomy_guids(value))
+    return canonical
+
+
+def _collection_payload(values: list) -> dict:
+    """The JSON shape SharePoint accepts for a multi-value column.
+
+    Live-probed on both writes and every multi-value kind (Choice, Lookup, User,
+    LookupMulti, UserMulti): a bare array is refused on create *and* on MERGE
+    (``InvalidClientQueryException``: a ``StartArray`` where a property value was
+    read) while ``{"results": [...]}`` is accepted by both.
+    """
+    return {"results": values}
+
+
+def _report_rejected_fields(result, warnings: list[str], label: str) -> None:
+    """Warn about ``ValidateUpdateListItem`` fields the server rejected.
+
+    A rejected field does not raise over HTTP — the response carries a per-field
+    ``HasException``/``ErrorMessage`` — and worse, SharePoint rolls the whole batch
+    back, so a sibling ``Created``/``Modified`` write is discarded too. Surfacing it
+    keeps that invisible loss honest (and testable).
+    """
+    values = getattr(result, "value", None) or []
+    for value in values:
+        if getattr(value, "HasException", False):
+            warnings.append(f"{label}: {value.FieldName} rejected ({value.ErrorMessage})")
+
+
+def _wire_value(value: Any) -> Any:
+    """A value as the wire spells it: a declared enum is the number it carries."""
+    return value.value if isinstance(value, Enum) else value
+
+
+def _web_local_texts(web: "Web", *values: Any) -> list[str | None]:
+    """The wall-clock texts a document's item form parses, one per instant given.
+
+    A document's ``ValidateUpdateListItem`` ignores ``datesInUTC``, parses the web's
+    locale and refuses a trailing ``Z`` (live-verified on a file and on a folder), so an
+    instant has to reach it as the web's own wall clock. That conversion runs server-side
+    (``TimeZone.UTCToLocalTime``) so DST is right, and one request converts every value.
+    A value that is not an instant is passed on as given, so the service rejection names
+    what the caller held instead of this layer having dropped it.
+    """
+    zone = web.regional_settings.time_zone
+    instants = {index: parse_datetime(iso_z(value)) for index, value in enumerate(values) if value}
+    converted = {index: zone.utc_to_local_time(instant) for index, instant in instants.items() if instant is not None}
+    if converted:
+        web.context.execute_query()
+    return [
+        wall_clock_text(converted[index].value) if index in converted else (str(value) if value else None)
+        for index, value in enumerate(values)
+    ]
+
+
+def _moderation_state(properties: dict) -> dict:
+    """The approval fields a list item carries; a blank comment is not one of them.
+
+    A hydrated model hands out enum members (``SPModerationStatusType``); the state is a
+    payload to write back, so it carries the numbers the column stores.
+    """
+    return {name: _wire_value(properties[name]) for name in _MODERATION_FIELDS if properties.get(name) not in (None, "")}
+
+
+#: SiteAssets is the one library that also holds per-site infrastructure — the
+#: site icon and the auto-provisioned OneNote folder.
+_SITE_ASSETS_URL_SUFFIX = "/SiteAssets"
+
+
+def _site_assets_scaffolding(folder) -> tuple[str, ...]:
+    """SiteAssets-only SharePoint-owned entries for this web (empty otherwise).
+
+    The notebook carries the *web's* title and the site icon is site branding, so both
+    differ on the target; each side skips its own.
+    """
+    url = (folder.server_relative_url or "").rstrip("/")
+    if not url.endswith(_SITE_ASSETS_URL_SUFFIX):
+        return ()
+    web = folder.context.web
+    if not web.properties.get("Title"):
+        web.ensure_properties(["Title"]).execute_query()
+    title = web.title
+    names = ["__siteIcon__.png"]
+    if title:
+        names.append(f"{title} Notebook")
+    return tuple(names)
+
+
+# How far a group's owner chain is followed (a group owned by a group owned by a
+# user is the normal depth for the default site groups).
+_MAX_GROUP_OWNER_DEPTH = 4
+
+
+def _principal_kind(member: Any) -> str | None:
+    """What ``UserGroup.xml`` can express for this role-assignment member: a user by PUID
+    (``"user"``) or a site group by title (``"group"``); a distribution or security group
+    and an unprojected ``PrincipalType`` are ``None``."""
+    ptype = getattr(member, "principal_type", None)
+    if ptype == PrincipalType.User:
+        return "user"
+    if ptype == PrincipalType.SharePointGroup:
+        return "group"
+    return None
+
+
+#: The flag that says whether a securable object owns its ACL, spelled by its declaration.
+_UNIQUE_PERMISSIONS = _SECURABLE.name_of("has_unique_role_assignments")
+
+
+def _principal_of(user: "User", key: int) -> Principal:
+    """A site user as the plan spells a principal, read from the model's own fields.
+
+    The PUID is ``UserInfo.UserId.NameId`` — one member of one nested value — so the
+    model answers it (`UserIdInfo.name_id`), not a wire name spelled here.
+    """
+    return Principal(
+        login_name=user.login_name or "",
+        system_id=normalize_puid(user.user_id.name_id),
+        display_name=user.title,
+        email=user.email,
+        user_id=key,
+    )
+
+
+def _has_unique_role_assignments(securable, *, refresh: bool = False) -> bool:
+    """Whether a securable has unique (broken-inheritance) role assignments.
+
+    SharePoint REST returns *inherited* role assignments too, so reading them verbatim
+    would break inheritance on every item and replicate the parent ACL. Only items with
+    unique assignments are read/applied (and compared by the verifier); inherited items
+    stay inherited on the target.
+
+    A plain entity read does not return the flag, so an object loaded *before* its ACL
+    changed keeps a stale value. The target side passes ``refresh=True``: this value
+    decides whether an ACL is applied or compared at all, so a stale ``False`` would
+    break inheritance on an item that is already unique (wiping the assignments it was
+    supposed to keep) and a stale ``False`` read back after a write would report a
+    permission mismatch for an ACL that did land.
+    """
+    unique = getattr(securable, "has_unique_role_assignments", None)
+    if unique is not None and not refresh:
+        return bool(unique)
+    try:
+        securable.ensure_properties([_UNIQUE_PERMISSIONS], refresh=refresh).execute_query()
+    except Exception:  # an unreadable flag is treated as "not unique"
+        return False
+    return bool(securable.properties.get(_UNIQUE_PERMISSIONS))
+
+
+def _replay_role_assignments(
+    securable,
+    principals: "_TargetPrincipals",
+    permissions: list[PermissionEntry],
+    warnings: list[str],
+    label: str,
+) -> None:
+    """Replay an item's unique ACLs onto a target item: additive, never destructive.
+
+    Every principal is resolved on the target first (users via ``EnsureUser``,
+    groups by name, default groups by role kind). Inheritance is broken only when
+    the target item still inherits *and* at least one assignment resolved: an item
+    whose every principal is unresolvable (a cross-tenant account, an app
+    principal) would otherwise end up with an **empty** ACL — inheritance broken,
+    nobody granted — which is worse than leaving it inheriting, so that case is
+    reported and the item is left alone.
+
+    A re-run therefore adds only what is missing and never removes an assignment
+    the source does not grant. The caller executes the queued requests.
+    """
+    resolved: list[tuple[Any, Any]] = []
+    for entry in permissions:
+        principal = principals.principal(entry.principal_name)
+        if principal is None:
+            continue
+        for role_name in entry.roles:
+            role = principals.role(role_name)
+            if role is None:
+                warnings.append(f"permissions {label}: could not resolve role {role_name!r}")
+                continue
+            resolved.append((principal, role))
+    if not resolved:
+        warnings.append(
+            f"permissions for {label!r} were not restored: no assignment could be resolved on the "
+            "target, and breaking inheritance would leave the item with an empty ACL — it still inherits"
+        )
+        return
+    if not _has_unique_role_assignments(securable, refresh=True):
+        securable.break_role_inheritance(copy_role_assignments=False, clear_sub_scopes=False)
+    for principal, role in resolved:
+        securable.add_role_assignment(principal, role)
+
+
+def _user_login(web, user_id: Any, cache: dict[int, str | None]) -> str | None:
+    """Resolve a target user id to its login name, cached."""
+    key = parse_int(user_id)
+    if key is None:
         return None
-    parsed = parse_datetime(value)
-    if parsed is None:
-        return value
-    if parsed.tzinfo is not None:
-        parsed = parsed.astimezone(timezone.utc).replace(tzinfo=None)
-    return parsed.strftime("%Y-%m-%dT%H:%M:%SZ")
+    if key in cache:
+        return cache[key]
+    login: str | None = None
+    try:
+        user = web.site_users.get_by_id(key).get().execute_query()
+        login = user.login_name or None
+    except Exception:  # noqa: BLE001 — an unresolvable id yields no login
+        login = None
+    cache[key] = login
+    return login
+
+
+class _DefaultGroups:
+    """Maps a web's associated default groups (Owners/Members/Visitors).
+
+    Default groups are titled after the site (``team Owners``), so a source and
+    target in the same tenant rarely share the exact name. These groups are used
+    both to resolve a source name onto the target *and* to normalize the name to a
+    canonical ``default:<Kind>`` token so the permission diff compares like with
+    like (a renamed site still verifies as preserved). Loaded once, lazily.
+    """
 
+    ATTRS = (
+        ("Owners", "associated_owner_group"),
+        ("Members", "associated_member_group"),
+        ("Visitors", "associated_visitor_group"),
+    )
 
-def is_taxonomy_validation(exc: Exception) -> bool:
-    """True when a request failed because a Managed Metadata (taxonomy) column
-    references a term set / term that no longer exists.
+    def __init__(self, web) -> None:
+        self._web = web
+        self._by_kind: dict[str, Any] | None = None
+        self._by_title: dict[str, str] = {}
 
-    SharePoint raises ``SPFieldValidationException`` ("the given guid does not
-    exist in the term store") while composing the item payload — the exact case
-    that makes a plain list-items read fail.
+    def _load(self) -> None:
+        if self._by_kind is not None:
+            return
+        self._by_kind = {}
+        for kind, attr in self.ATTRS:
+            group = getattr(self._web, attr, None)
+            if group is None:
+                continue
+            try:
+                group.get().execute_query()
+            except Exception:  # noqa: BLE001 — an unreadable group is skipped
+                continue
+            self._by_kind[kind] = group
+            title = getattr(group, "title", None) or getattr(group, "login_name", None)
+            if title:
+                self._by_title[title] = kind
+
+    def group(self, kind: str):
+        self._load()
+        return self._by_kind.get(kind) if self._by_kind else None
+
+    def normalize(self, name: str) -> str:
+        self._load()
+        kind = self._by_title.get(name)
+        return f"default:{kind}" if kind else name
+
+
+class _TargetPrincipals:
+    """Resolve source principals and role definitions on a target web (cached).
+
+    Users are ensured on the site (``EnsureUser``) so their numeric id can be used
+    for authorship and role assignments; groups are matched by name, and the
+    default SharePoint groups (Owners/Members/Visitors) fall back to the target
+    web's associated groups so a renamed site (``team`` -> ``team_out``) still
+    maps its role assignments. Anything that cannot be resolved is skipped with a
+    warning (same-tenant, best-effort).
     """
-    text = f"{getattr(exc, 'code', '') or ''} {getattr(exc, 'message', '') or ''} {exc}".lower()
-    return "spfieldvalidationexception" in text and "term store" in text
 
+    def __init__(self, web, warnings: list[str]) -> None:
+        self._web = web
+        self._warnings = warnings
+        self._users: dict[str, Any] = {}
+        self._roles: "dict[str, RoleDefinition] | None" = None
+        self._defaults = _DefaultGroups(web)
+
+    @staticmethod
+    def _strip_claims(name: str) -> str:
+        return name.rsplit("|", 1)[-1] if name.startswith("i:0#") else name
+
+    def normalize(self, name: str) -> str:
+        """Canonical principal name (default groups collapse to ``default:<Kind>``)."""
+        return self._defaults.normalize(name)
+
+    @site_access(SiteLevel.MANAGE)
+    def user(self, login: str | None):
+        """Ensure a user login on the target site and return its ``User`` object."""
+        if not login:
+            return None
+        login = self._strip_claims(login)
+        if login in self._users:
+            return self._users[login]
+        obj = None
+        try:
+            obj = self._web.ensure_user(login).execute_query()
+        except Exception as e:  # noqa: BLE001 — an unresolvable principal is skipped
+            self._warnings.append(f"could not ensure target user {login!r}: {e}")
+        self._users[login] = obj
+        return obj
+
+    @site_access(SiteLevel.MANAGE)
+    def principal(self, name: str):
+        """Resolve a source principal (user or group) to a target principal object."""
+        if not name:
+            return None
+        login = self._strip_claims(name)
+        if login.startswith("default:"):
+            return self._defaults.group(login.split(":", 1)[1])
+        if "@" in login:
+            return self.user(login)
+        group = None
+        try:
+            group = self._web.site_groups.get_by_name(login).get().execute_query()
+        except Exception:  # noqa: BLE001 — fall back to the default groups below
+            group = None
+        if group is None:
+            kind = login.rsplit(" ", 1)[-1]
+            if kind in {"Owners", "Members", "Visitors"}:
+                group = self._defaults.group(kind)
+        if group is not None:
+            return group
+        self._warnings.append(f"could not resolve principal {name!r} on the target")
+        return None
 
-def taxonomy_internal_names(fields) -> list[str]:
-    """Internal names of Managed Metadata columns in a loaded field set."""
-    names: list[str] = []
-    for field in fields:
-        type_name = getattr(field, "type_as_string", None) or ""
-        schema = getattr(field, "schema_xml", None) or ""
-        if type_name in _TAXONOMY_FIELD_TYPES or "TermSetId=" in schema:
-            internal_name = getattr(field, "internal_name", None)
-            if internal_name:
-                names.append(internal_name)
-    return list(dict.fromkeys(names))
+    @site_access(SiteLevel.MANAGE)
+    def role(self, name: str) -> "RoleDefinition | None":
+        """Resolve (and cache) a target role definition by name."""
+        if self._roles is None:
+            loaded = self._web.role_definitions.get().execute_query()
+            self._roles = {rd.name: rd for rd in loaded if rd.name}
+        return self._roles.get(name)
+
+
+def _resolve_group_ownership(
+    web: Any,
+    title: str,
+    resolve: Callable[[Any], "Principal | None"] | None,
+) -> tuple["Principal | None", list[str]]:
+    """A site group's owner chain: a user with a PUID, plus the groups on the way up.
+
+    ``UserGroup.xml`` requires an ``Owner`` on every ``<Group>`` — live-verified: a
+    group emitted without one fails the whole ingestion job with ``The required
+    attribute 'Owner' is missing`` — and an owner may itself be a group (a team
+    site's ``Visitors`` group is owned by its ``Owners`` group, which owns itself;
+    both live-verified). The returned titles are **nearest first**; the last one is
+    owned by the returned user, or owns itself when the chain closes on itself or
+    leaves the tenant (a group created by the migration app is owned by the app,
+    which has no PUID).
+    """
+    groups: list[str] = []
+    seen: set[str] = {title.casefold()}
+    current = title
+    for _ in range(_MAX_GROUP_OWNER_DEPTH):
+        try:
+            group = web.site_groups.get_by_name(current).get().execute_query()
+            owner = group.owner.get().execute_query()
+        except Exception:  # noqa: BLE001 - best-effort: a title the site does not have ends the chain
+            break
+        if _principal_kind(owner) == "user":
+            principal = resolve(getattr(owner, "id", None)) if resolve is not None else None
+            return principal, groups
+        owner_title = getattr(owner, "title", None)
+        if not owner_title:
+            break
+        groups.append(owner_title)
+        if owner_title.casefold() in seen:
+            break
+        seen.add(owner_title.casefold())
+        current = owner_title
+    return None, groups
+
+
+def _attach_group_owners(
+    entries: list[PermissionEntry],
+    web: Any,
+    resolve: Callable[[Any], "Principal | None"] | None,
+    cache: dict[str, tuple["Principal | None", list[str]]],
+) -> None:
+    """Fill ``PermissionEntry.owner``/``owner_groups`` for group entries (per title)."""
+    for entry in entries:
+        if entry.principal_type != "group":
+            continue
+        title = entry.display_name or entry.principal_name
+        if title not in cache:
+            cache[title] = _resolve_group_ownership(web, title, resolve)
+        entry.owner, entry.owner_groups = cache[title]
+
+
+def _read_role_assignments(
+    securable,
+    resolve: Callable[[Any], "Principal | None"] | None = None,
+    normalize: Callable[[str], str] | None = None,
+) -> list[PermissionEntry]:
+    """Read a securable object's role assignments into ``PermissionEntry``s.
+
+    One entry per principal (user or group), keyed by login name; the target uses
+    the same shape so the permission diff compares like with like. ``normalize``
+    (when supplied) canonicalizes a principal name — default groups collapse to
+    ``default:<Kind>`` so a renamed site still compares as preserved. Role names are
+    paired with their decimal ``PermMask`` (``role_masks``), the principal kind is
+    recorded in ``principal_type``, and — when ``resolve`` is supplied — a user
+    principal is enriched with its PUID/display name/email so the server-side
+    package target can emit a faithful ``UserGroup.xml`` entry. A SharePoint group
+    keeps its **title** in ``display_name`` (the normalized name would not match on
+    the target).
+    """
+    assignments = securable.get_role_assignments().execute_query()
+    result: list[PermissionEntry] = []
+    for assignment in assignments:
+        member = assignment.member
+        name = member.login_name or member.user_principal_name
+        if not name:
+            continue
+        roles: list[str] = []
+        role_masks: dict[str, str] = {}
+        for role in assignment.role_definition_bindings:
+            if not role.name:
+                continue
+            roles.append(role.name)
+            mask = role.perm_mask
+            if mask is not None:
+                role_masks[role.name] = mask
+        entry = PermissionEntry(
+            principal_name=normalize(name) if normalize is not None else name,
+            roles=roles,
+            role_masks=role_masks,
+            principal_type=_principal_kind(member),
+        )
+        if entry.principal_type == "group":
+            entry.display_name = member.title or name
+        if resolve is not None and entry.principal_type == "user":
+            principal = resolve(getattr(member, "id", None))
+            if principal is not None:
+                entry.system_id = principal.system_id
+                entry.display_name = principal.display_name
+                entry.email = principal.email
+        result.append(entry)
+    return result
 
 
 class SharePointListSource:
     """Enumerates a SharePoint list's items into record migration items."""
 
+    # Marks this source as emitting list-item attachments as extra items (see DataSource).
+    supports_attachments = True
+
+    # Marks this source as annotating Person columns with a portable login name so the
+    # target can resolve them (see ``_annotate_person_logins``).
+    supports_typed_values = True
+
+    def rebind(self) -> "SharePointListSource":
+        """This source on its own cloned context, so another thread can drive it.
+
+        A context owns one pending-query queue: two adapters sharing it interleave
+        their deferred queries. Re-addressing the same list (by id) on a ``clone``
+        — which shares the authenticated transport — lets a session run several
+        list jobs in parallel over one connection pool. Read caches are per-run and
+        deliberately not carried over.
+        """
+        return SharePointListSource(_cloned_list(self._list), self._select)
+
     def __init__(self, source_list: "SPList", select: list[str] | None = None) -> None:
         self._list = source_list
         self._select = select
         self._records: dict[str, dict] = {}
+        self._items: dict[str, Any] = {}
+        self._attachments: dict[str, Any] = {}
+        self._users: dict[int, Principal | None] = {}
+        # Group title -> (owner user, owner group chain); a ``<Group>`` needs both.
+        self._group_owners: dict[str, tuple[Principal | None, list[str]]] = {}
+        self._default_groups: _DefaultGroups | None = None
+        self._source_fields_cache: list[Field] | None = None
+        self._folder_records_cache: dict[str, dict] | None = None
         self.warnings: list[str] = []
 
     def label(self) -> str:
@@ -93,11 +738,11 @@ class SharePointListSource:
     def list_items(self, progress: MigrationProgress = None) -> list[MigrationItem]:
         try:
             loaded = self._load_items(self._select)
-        except Exception as e:  # noqa: BLE001 — see the taxonomy fallback below
-            # A full read of a list with an orphaned Managed Metadata column
-            # fails server-side; re-enumerate excluding those columns instead
-            # of aborting the export. An explicit --select is honored as-is.
-            if not is_taxonomy_validation(e) or self._select:
+        except SPFieldValidationException as e:
+            # A full read of a list with an orphaned Managed Metadata column fails
+            # server-side; re-enumerate without those columns. An explicit --select
+            # is honored as-is.
+            if not e.is_missing_term or self._select:
                 raise
             self.warnings.append(
                 "Full item read failed — a Managed Metadata column references a missing term set; "
@@ -112,12 +757,29 @@ class SharePointListSource:
                 loaded = self._load_items(["Id", "Title"])
         return self._project(loaded, progress)
 
-    def _load_items(self, select: list[str] | None):
+    def _load_items(self, select: list[str] | None, folder_only: bool = False):
         items = self._list.items
         # A full read projects ``*`` plus the system metadata so author/editor ids
-        # are captured reliably; an explicit/safe projection is honored as-is.
-        columns = ["*", *_METADATA_SELECT] if select is None else select
-        return items.select(columns).get_all().execute_query()
+        # and the unique-ACL flag are captured in one query (``*`` omits them);
+        # an explicit/safe projection is honored as-is.
+        if select is None:
+            columns = ["*", *_METADATA_SELECT]
+            # A ``*`` projection also omits multi-value Lookup ids (and returns
+            # multi-person ids only inconsistently); select each ``<name>Id``
+            # explicitly so the values are not silently lost.
+            for name in self._multi_columns():
+                key = ListItem.value_column(name)
+                if key not in columns:
+                    columns.append(key)
+            # Expand attachments so they can be migrated alongside their item.
+            query = items.select(columns).expand(["AttachmentFiles"])
+            if folder_only:
+                query = query.filter("FSObjType eq 1")
+            return query.get_all().execute_query()
+        query = items.select(select)
+        if folder_only:
+            query = query.filter("FSObjType eq 1")
+        return query.get_all().execute_query()
 
     def _safe_select(self) -> list[str]:
         """Fallback projection: visible, non-system columns minus Managed Metadata.
@@ -127,7 +789,7 @@ class SharePointListSource:
         stays on the list's user columns only.
         """
         fields = self._list.fields.get().execute_query()
-        taxonomy = taxonomy_internal_names(fields)
+        taxonomy = list(dict.fromkeys(f.internal_name for f in fields if f.internal_name and f.is_taxonomy))
         self.warnings.append(f"excluded Managed Metadata column(s): {', '.join(sorted(taxonomy)) or 'none'}")
         columns = ["Id"]
         for field in fields:
@@ -142,34 +804,450 @@ class SharePointListSource:
         return columns
 
     def _project(self, loaded, progress: MigrationProgress) -> list[MigrationItem]:
-        from office365.runtime.converters.records import iter_records
-
-        # Reuse the shared record projection (raw values, no JSON coercion) so the
-        # migration payload matches the data pipeline's.
-        records = iter_records(loaded, raw=True)
+        records = self._project_records(loaded)
         result: list[MigrationItem] = []
+        pending_attachments: list[tuple[str, Any]] = []
         for item, record in zip(loaded, records):
-            self._records[str(item.id)] = record
+            item_id = str(item.id)
+            self._records[item_id] = record
+            self._items[item_id] = item
+            author_id = parse_int(record.get("AuthorId"))
+            editor_id = parse_int(record.get("EditorId"))
+            planned = MigrationItem(
+                source_path=f"{self._list.title}/{item_id}",
+                dest_path=item_id,
+                item_type="record",
+                modified=iso_or_none(record.get("Modified")),
+                created=iso_or_none(record.get("Created")),
+            )
+            # Resolve the source author/editor once so an authorship-preserving
+            # target can restore them by login name (ids are tenant-local).
+            planned.author = self._principal_for(author_id)
+            planned.editor = self._principal_for(editor_id)
+            result.append(planned)
+            for attachment in item.properties.get("AttachmentFiles") or []:
+                pending_attachments.append((item_id, attachment))
+            emit_progress(progress, done=len(result), stage="planning", items=[item])
+        # Attachments come after every record so the target can create all parent
+        # items before it resolves and uploads their attachments.
+        for item_id, attachment in pending_attachments:
+            name = getattr(attachment, "file_name", None)
+            if not name:
+                self.warnings.append(f"skipped an attachment without a file name on item {item_id}")
+                continue
+            dest_path = f"{item_id}/{name}"
+            self._attachments[dest_path] = attachment
             result.append(
                 MigrationItem(
-                    source_path=f"{self._list.title}/{item.id}",
-                    dest_path=str(item.id),
-                    item_type="record",
-                    modified=iso_or_none(record.get("Modified")),
-                    created=iso_or_none(record.get("Created")),
-                    author_id=parse_int(record.get("AuthorId")),
-                    editor_id=parse_int(record.get("EditorId")),
+                    source_path=f"{self._list.title}/{dest_path}",
+                    dest_path=dest_path,
+                    item_type="attachment",
                 )
             )
-            emit_progress(progress, done=len(result), stage="planning", items=[item])
+            emit_progress(progress, done=len(result), stage="planning", items=[attachment])
         return result
 
-    def read(self, item: MigrationItem) -> dict:
+    def _project_records(self, loaded, report_skipped: bool = True) -> list[dict]:
+        # Project every loaded property — not the collection's literal ``select``.
+        # Passing ``["*", ...]`` straight through emitted ``{"*": None, ...}``, so
+        # migrated records carried no field values at all. ``AttachmentFiles`` is a
+        # navigation property (objects, not a scalar column) and is excluded; the
+        # target writes attachments separately.
+        select = sorted(
+            {key for item in loaded for key in item.properties if key != "AttachmentFiles"} - ListItem._schema.readonly
+        )
+        records = records_from_items(list(loaded), select, set(), raw=True)
+        # A REST item create accepts scalar column values only. A full read also
+        # returns navigation properties (``ParentList``) and typed values
+        # (lookups/persons, e.g. ``PredecessorsId`` / ``AssignedTo``) whose JSON
+        # objects carry no ``__metadata.type`` here, so the create batch is
+        # rejected with ``InvalidClientQueryException``. Typed-value remapping is
+        # not supported yet, so drop them and say so rather than fail the run. The
+        # item's own links (``ParentList``, ``FieldValuesAsHtml``) carry no scalar content
+        # either, and are dropped silently: they are the navigations the model declares.
+        dropped: set[str] = set()
+        navigations: set[str] = {name for item in loaded for name in type(item)._schema.navigations}
+        multi = self._multi_columns()
+        multi_keys = _typed_keys(multi)
+        choices = self._multi_choice_columns()
+        taxonomy = self._taxonomy_columns()
+        value_objects = self._value_object_columns()
+        for record in records:
+            for key, value in list(record.items()):
+                if key in multi_keys:
+                    continue  # handled by ``_normalize_multi_values``
+                if key in choices:
+                    continue  # handled by ``_normalize_multi_choice_values``
+                if key in taxonomy:
+                    continue  # handled by ``_project_taxonomy_values``
+                if key in value_objects and _scalar_mapping(value) is not None:
+                    record[key] = _scalar_mapping(value)
+                    continue  # a value object (``{"Url", "Description"}``) is writable as-is
+                if value is not None and not isinstance(value, (str, int, float, bool)):
+                    record.pop(key)
+                    if key not in navigations:
+                        dropped.add(key)
+        if dropped:
+            self.warnings.append(
+                f"skipped non-scalar column(s) with no typed-value mapping: {', '.join(sorted(dropped))}"
+            )
+        # Structure provisioning skips hidden columns, so their typed values (and
+        # the text companion) have nowhere to land on the target; drop both rather
+        # than fail the create on an unknown column.
+        skipped = self._skipped_columns()
+        if skipped:
+            skipped_keys = _typed_keys(skipped)
+            for record in records:
+                for key in skipped_keys:
+                    record.pop(key, None)
+            if report_skipped:
+                self.warnings.append(
+                    f"skipped hidden typed column(s) not replicated by structure provisioning: "
+                    f"{', '.join(sorted(skipped))}"
+                )
+        self._project_taxonomy_values(records)
+        self._normalize_multi_values(records)
+        self._normalize_multi_choice_values(records)
+        self._annotate_person_logins(records)
+        return records
+
+    def folder_records(self) -> dict[str, dict]:
+        """Column values of this list's folders, keyed by their server-relative URL.
+
+        A document library's folders are list items too: a document set or a managed
+        folder carries its own column values, so a target that only created the empty
+        folder would silently lose them. The values go through the same projection as
+        an item's (typed values normalized, system and navigation columns dropped), so
+        the target can write them onto the folder's underlying item. The read is
+        narrowed to the folder's writable columns (see :meth:`folder_projection`): a
+        ``*`` read also returns system and computed columns (compliance flags, link
+        filenames, version labels) that an update would reject and that carry no
+        portable value.
+        """
+        if self._folder_records_cache is None:
+            records: dict[str, dict] = {}
+            try:
+                loaded = self._load_items(self.folder_projection(), folder_only=True)
+            except Exception as e:  # noqa: BLE001 — folder values are best-effort
+                self.warnings.append(f"folder column values could not be read: {e}")
+                loaded = []
+            # The folder projection already excluded the columns an item record would
+            # report as unmigratable, so those messages would describe nothing.
+            for record in self._project_records(loaded, report_skipped=False) if loaded else []:
+                url = record.get("FileRef")
+                if not isinstance(url, str) or not url:
+                    continue
+                values = _folder_record_values(record)
+                if values:
+                    records[url.rstrip("/")] = values
+            self._folder_records_cache = records
+        return self._folder_records_cache
+
+    def folder_projection(self) -> list[str]:
+        """The columns that carry a folder's own metadata, plus what typed values need.
+
+        A folder has no separate create payload: its values are read back as a record,
+        written onto the folder's item and compared the same way — so the projection
+        must include the companions the typed-value normalization reads (``<name>Id``
+        for Lookup/Person values, the hidden note of a Managed Metadata column).
+        """
+        writable = _folder_value_columns(self._source_fields())
+        # ``FileRef`` keys the record (it is the folder's identity, not a value).
+        columns = ["ContentTypeId", "FileRef", *sorted(writable)]
+        # Lookup and Person values are carried as item ids / logins under
+        # ``<name>Id``; the column itself is carried in the record too.
+        single_lookups = {
+            field.internal_name
+            for field in self._source_fields()
+            if field.internal_name and field.is_lookup and not field.is_multi_valued
+        }
+        for name in sorted((single_lookups | self._user_columns() | set(self._multi_columns())) & writable):
+            key = ListItem.value_column(name)
+            if key not in columns:
+                columns.append(key)
+        for note in self._taxonomy_note_columns():
+            if note not in columns:
+                columns.append(note)
+        return columns
+
+    def _source_fields(self) -> list[Field]:
+        """The source list's field definitions, read once and shared by every scan.
+
+        The projection is the columns of every typed column class, so the read does not
+        depend on whatever ``$select`` a previous caller left on the shared ``fields``
+        collection -- ``List.fields`` survives a ``capture_list_structure`` read, which
+        selects a narrower set.
+        """
+        if self._source_fields_cache is None:
+            try:
+                self._source_fields_cache = list(self._list.fields.select(Field.scan_columns()).get().execute_query())
+            except Exception as e:  # noqa: BLE001 — values stay un-remapped, never fatal
+                self.warnings.append(f"could not read the list's columns for typed-value remapping: {e}")
+                self._source_fields_cache = []
+        return self._source_fields_cache
+
+    def _taxonomy_columns(self) -> dict[str, bool]:
+        """The source's Managed Metadata columns (internal name -> holds many values)."""
+        return {
+            field.internal_name: field.is_multi_valued
+            for field in self._source_fields()
+            if field.internal_name and field.is_taxonomy
+        }
+
+    def _taxonomy_note_columns(self) -> set[str]:
+        """The hidden note companions of the source's taxonomy columns.
+
+        The note column is what the target's write payload becomes for a multi-value
+        column, and its name is chosen by the service; each taxonomy column names its own
+        note, so it is answered from the column set (no request per value).
+        """
+        notes: set[str] = set()
+        for field in self._source_fields():
+            if field.is_taxonomy:
+                note_name = cast(TaxonomyField, field).text_field_name
+                if note_name:
+                    notes.add(note_name)
+        return notes
+
+    def _project_taxonomy_values(self, records: list[dict]) -> None:
+        """Project taxonomy columns as bare ``[{"TermGuid": ...}]`` term lists.
+
+        The target recreates the column against the same term set and rebuilds the
+        write payload, so only the portable term id travels. The hidden note
+        companion (if a projection happens to include it) is dropped.
+        """
+        columns = self._taxonomy_columns()
+        if not columns:
+            return
+        notes = self._taxonomy_note_columns()
+        for record in records:
+            for note in notes:
+                record.pop(note, None)
+            for name in columns:
+                terms = _taxonomy_terms(record.get(name))
+                if terms:
+                    record[name] = terms
+                else:
+                    record.pop(name, None)
+
+    def _typed_columns(self) -> tuple[set[str], dict[str, str], set[str]]:
+        """The source's Person and multi-value columns.
+
+        Returns ``(single-value User columns, {multi-value column: field type},
+        hidden typed columns)``. The field type tells a multi-lookup (remapped by
+        item id) from a multi-person (remapped by login). Hidden typed columns are
+        reported separately because structure provisioning does not replicate them.
+        """
+        users: set[str] = set()
+        multi: dict[str, str] = {}
+        skipped: set[str] = set()
+        for field in self._source_fields():
+            internal_name = field.internal_name
+            if not internal_name or internal_name in _PERSON_EXCLUDED:
+                continue
+            if not (field.is_person or field.is_lookup):
+                continue
+            if field.hidden is True:
+                # Structure replay skips hidden columns, so the target never gets
+                # them; projecting their values would fail the write.
+                skipped.add(internal_name)
+            elif field.is_person:
+                if field.is_multi_valued:
+                    multi[internal_name] = "UserMulti"
+                else:
+                    users.add(internal_name)
+            elif field.is_multi_valued:
+                multi[internal_name] = "LookupMulti"
+        return users, multi, skipped
+
+    def _user_columns(self) -> set[str]:
+        """The source's single-value Person columns (internal names)."""
+        return self._typed_columns()[0]
+
+    def _multi_columns(self) -> dict[str, str]:
+        """The source's multi-value Lookup/Person columns (internal name -> field type)."""
+        return self._typed_columns()[1]
+
+    def _skipped_columns(self) -> set[str]:
+        """The source's hidden Person/multi-value columns (not replicated on the target)."""
+        return self._typed_columns()[2]
+
+    def _multi_choice_columns(self) -> set[str]:
+        """The source's multi-choice columns (internal names)."""
+        return {field.internal_name for field in self._source_fields() if field.internal_name and field.is_multi_choice}
+
+    def _value_object_columns(self) -> set[str]:
+        """The source's columns that hold a REST value object (e.g. a hyperlink)."""
+        return {field.internal_name for field in self._source_fields() if field.internal_name and field.is_value_object}
+
+    def _annotate_person_logins(self, records: list[dict]) -> None:
+        """Replace each Person column's site-user id with the user's login name.
+
+        A site-user id is only meaningful inside its own site collection, so it is
+        meaningless on the target. The login *is* portable, and the target resolves
+        it back to (a possibly different) target site-user id with ``EnsureUser``.
+        A person the source cannot resolve is dropped and reported rather than
+        copied as a wrong id.
+        """
+        columns = self._user_columns()
+        if not columns:
+            return
+        for record in records:
+            for name in columns:
+                # ``<name>StringId`` is a read-only text companion holding the user
+                # id; leaving it in the payload makes REST ignore the remapped
+                # ``<name>Id`` and keep the source id.
+                record.pop(ListItem.string_value_column(name), None)
+                key = ListItem.value_column(name)
+                user_id = parse_int(record.get(key))
+                if user_id is None:
+                    continue
+                principal = self._principal_for(user_id)
+                login = principal.login_name if principal else None
+                if login:
+                    record[key] = login
+                else:
+                    record.pop(key, None)
+                    self.warnings.append(
+                        f"person column '{name}' value {user_id} could not be resolved to a login; left empty"
+                    )
+
+    def _normalize_multi_values(self, records: list[dict]) -> None:
+        """Project each multi-value column's ids as a plain list the target can remap.
+
+        A multi-person column additionally carries the portable login names instead
+        of the site-local ids, matching the single-value Person handling.
+        """
+        multi = self._multi_columns()
+        if not multi:
+            return
+        for record in records:
+            for name, field_type in multi.items():
+                record.pop(ListItem.string_value_column(name), None)
+                key = ListItem.value_column(name)
+                ids = values_of(record.get(key))
+                parsed: list[int] = []
+                for value in ids or []:
+                    user_id = parse_int(value)
+                    if user_id is None:
+                        parsed = []
+                        break
+                    parsed.append(user_id)
+                if not parsed:
+                    record.pop(key, None)
+                    continue
+                if field_type == "UserMulti":
+                    logins: list[str] = []
+                    for user_id in parsed:
+                        principal = self._principal_for(user_id)
+                        login = principal.login_name if principal else None
+                        if login:
+                            logins.append(login)
+                        else:
+                            self.warnings.append(
+                                f"multi-person column '{name}' value {user_id} could not be resolved "
+                                "to a login; the value was left out"
+                            )
+                    if logins:
+                        record[key] = logins
+                    else:
+                        record.pop(key, None)
+                else:
+                    record[key] = parsed
+
+    def _normalize_multi_choice_values(self, records: list[dict]) -> None:
+        """Project each multi-choice column as a plain list of its selected values.
+
+        A live read returns the collection as a positional mapping
+        (``{0: "red", 1: "green"}``); the source records it as a bare list, which is
+        what the checksum compares and what the target wraps for a create. An empty
+        selection is dropped so the column reads back empty rather than as an empty
+        collection.
+        """
+        names = self._multi_choice_columns()
+        if not names:
+            return
+        for record in records:
+            for name in names:
+                if name not in record:
+                    continue
+                values = values_of(record.get(name))
+                if values:
+                    record[name] = values
+                else:
+                    record.pop(name, None)
+
+    def read(self, item: MigrationItem) -> object:
+        if item.item_type == "attachment":
+            return self._attachment_content(item)
         return self._records.get(item.dest_path, {})
 
+    def _attachment_content(self, item: MigrationItem) -> bytes:
+        attachment = self._attachments.get(item.dest_path)
+        if attachment is None:
+            raise FileNotFoundError(item.source_path)
+        return cast(bytes, attachment.get_content().execute_query().value)
+
     def checksum(self, item: MigrationItem) -> str:
-        payload = record_to_json(self._records.get(item.dest_path, {}))
-        return hashlib.md5(payload.encode("utf-8")).hexdigest()
+        if item.item_type == "attachment":
+            return checksum(self._attachment_content(item))
+        return _content_checksum(_canonicalize_taxonomy_record(self._records.get(item.dest_path, {})))
+
+    def read_metadata(self, item: MigrationItem) -> dict | None:
+        """Comparable attributes of the source item (for the post-run metadata diff)."""
+        source_item = self._items.get(item.dest_path)
+        if source_item is None:
+            return None
+        return {
+            "created": iso_or_none(source_item.created),
+            "modified": iso_or_none(source_item.modified),
+        }
+
+    def read_authorship(self, item: MigrationItem) -> tuple[str | None, str | None]:
+        """The source author/editor login names (for the authorship diff)."""
+        return (
+            item.author.login_name if item.author else None,
+            item.editor.login_name if item.editor else None,
+        )
+
+    def _normalize_name(self, name: str) -> str:
+        """Canonicalize a principal name (default groups -> ``default:<Kind>``)."""
+        context = getattr(self._list, "context", None)
+        web = getattr(context, "web", None) if context is not None else None
+        if web is None:
+            return name
+        if self._default_groups is None:
+            self._default_groups = _DefaultGroups(web)
+        return self._default_groups.normalize(name)
+
+    def read_permissions(self, item: MigrationItem) -> list[PermissionEntry]:
+        """Read the item's *unique* role assignments (best-effort ACL preservation).
+
+        Inherited items return ``[]`` — REST would otherwise report the parent's
+        ACL, and copying it would break inheritance on every item.
+        """
+        source_item = self._items.get(item.dest_path)
+        if source_item is None or not _has_unique_role_assignments(source_item):
+            return []
+        entries = _read_role_assignments(source_item, resolve=self._principal_for, normalize=self._normalize_name)
+        _attach_group_owners(entries, self._list.context.web, self._principal_for, self._group_owners)
+        return entries
+
+    def _principal_for(self, user_id: Any) -> "Principal | None":
+        """Resolve a site-user id to a :class:`Principal` (login + PUID), cached."""
+        key = parse_int(user_id)
+        if key is None:
+            return None
+        if key in self._users:
+            return self._users[key]
+        principal: "Principal | None" = None
+        try:
+            user = self._list.context.web.site_users.get_by_id(cast("str", key)).get().execute_query()
+            principal = _principal_of(user, key)
+        except Exception as e:  # noqa: BLE001 — a missing user degrades to no authorship
+            self.warnings.append(f"user {key} could not be resolved: {e}")
+        self._users[key] = principal
+        return principal
 
     def close(self) -> None:
         pass
@@ -180,34 +1258,171 @@ class SharePointListTarget:
 
     Pass ``key`` (one or more natural-key columns) to make the target idempotent:
     a hash of those columns is stored in ``key_field`` and each payload is created
-    or (``on_conflict="upsert"``) updated, so re-runs never duplicate. Without a
+    or (``on_conflict="update"``) updated, so re-runs never duplicate. Without a
     key, records are appended and idempotency relies on the checkpoint/manifest.
+
+    ``on_conflict`` may be passed explicitly; otherwise it is derived from
+    ``MigrationOptions.conflict_resolution`` by :meth:`configure` (the runner calls
+    it before writes): ``OVERWRITE`` → ``"update"``, anything else → ``"skip"``.
+
+    Every migrated item also gets a source-id marker (``identity_field``, default
+    ``MigrationSourceId``): the default ``SKIP`` policy then recognizes items already
+    on the target (so re-runs do not duplicate) and :meth:`list_paths` pairs source
+    and target items for verification. Pass ``identity_field=None`` to opt out.
+    List-item attachments are written after their parent records are flushed.
+
+    Pass ``content_type_map`` (a :class:`~office365.migration.map.ContentTypeMap`)
+    when the target list's content types were recreated with fresh identifiers:
+    every record's ``ContentTypeId`` is rewritten to the target id so items land
+    under the recreated content type instead of the wrong (or a missing) one.
+
+    Pass ``structure`` (a :class:`~office365.migration.sharepoint.structure.ListStructure`
+    from :func:`~office365.migration.sharepoint.structure.load_list_structure`) to
+    replay a captured list shape onto this target before the first record is written —
+    what importing an export bundle needs, since the bundle's payload is records and
+    its columns/content types/views travel in the sidecar, not in each item.
     """
 
+    # Marks this target as accepting list-item attachments as extra items (see DataTarget).
+    supports_attachments = True
+
+    # Marks this target as remapping Lookup values across migrated lists and Person
+    # values by login (see ``_remap_typed_values``).
+    supports_typed_values = True
+
+    # Marks this target as replaying a list item's approval state (its moderation status
+    # and comment) in the metadata write, which is the only write a list item takes it in.
+    # Check-out and draft-version state are still not carried.
+    supports_item_state = True
+
+    #: The single-item :meth:`write` only queues a create; a chunk must be flushed
+    #: before it is durable. The runner therefore routes this target through the
+    #: chunked path even at ``concurrency == 1``, so checkpoints never record
+    #: ``DONE`` ahead of the actual write.
+    deferred_writes = True
+
+    def rebind(self) -> "SharePointListTarget":
+        """This target on its own cloned context (see :meth:`SharePointListSource.rebind`)."""
+        return SharePointListTarget(
+            _cloned_list(self._list),
+            key=list(self._key_columns) or None,
+            key_field=self._key_field,
+            on_conflict=self._on_conflict_override,
+            identity_field=self._identity_field,
+            content_type_map=self._content_type_map,
+            structure=self._structure,
+        )
+
     def __init__(
         self,
         target_list: "SPList",
         key: str | list[str] | None = None,
         key_field: str = "MigrationKey",
-        on_conflict: str = "skip",
+        on_conflict: str | None = None,
+        identity_field: str | None = DEFAULT_LIST_IDENTITY_FIELD,
+        content_type_map: "ContentTypeMap | None" = None,
+        structure: "ListStructure | None" = None,
     ) -> None:
         self._list = target_list
+        self._structure = structure
+        self._structure_applied = False
         self._key_columns = [key] if isinstance(key, str) else (list(key) if key else [])
         self._key_field = key_field
-        self._on_conflict = on_conflict
+        self._on_conflict_override = on_conflict
+        self._on_conflict = on_conflict or "skip"
         self._target = None
         self._existing: dict = {}
+        self._identity_field = identity_field
+        self._identity_ensured = False
+        self._identity_index: dict | None = None
+        self._identity_index_stale = False
+        self._identity_index_max_id = 0
+        self._attachment_path_cache: set[str] | None = None
+        self._content_type_map = content_type_map
+        self._login_cache: dict[int, str | None] = {}
+        # Author/Editor values already written by ``apply_authorship`` but pending a
+        # shared final write (see ``apply_timestamps``); avoids the ValidateUpdateListItem
+        # call that restores timestamps silently resetting ``Editor`` to the caller.
+        self._pending_authorship: dict[str, dict] = {}
+        # Approval state read from the payload, replayed in the metadata write (a
+        # system update approves the item); same pending-then-pop lifecycle as above.
+        self._pending_approval: dict[str, dict[str, str]] = {}
+        self.warnings: list[str] = []
+        self._principals_cache: _TargetPrincipals | None = None
+        # Lookup and Person columns carry an id that is only meaningful on the
+        # source (list-local item id / site-user id). The target remaps each to its
+        # own value on write and back to the source value on verification.
+        self._columns_cache: _TypedColumns | None = None
+        self._lookup_indexes: dict[str, tuple[dict[int, int], dict[int, int]]] = {}
+        self._unresolved_lookups: set[tuple[str, int]] = set()
+        self._unresolved_users: set[tuple[str, str]] = set()
+        self._user_logins: dict[int, str] | None = None
+        # Verification reads the same written item through four hooks (checksum,
+        # metadata, authorship, permissions). Memoizing the fresh read keeps that
+        # to one request per item; anything that writes to the target clears it.
+        self._fresh_reads: dict[str, "ListItem | None"] = {}
+
+    @property
+    def on_conflict(self) -> str:
+        """The active record conflict policy (``"skip"`` or ``"update"``)."""
+        return self._on_conflict
+
+    def configure(self, options) -> None:
+        """Derive ``on_conflict`` from ``MigrationOptions.conflict_resolution``.
+
+        Called by :class:`MigrationRunner` before the run, so a single
+        ``conflict_resolution`` drives both file and record targets. An
+        ``on_conflict`` passed to the constructor is honored as-is.
+        """
+        if self._on_conflict_override is None:
+            self._on_conflict = conflict_to_on_conflict(options.conflict_resolution)
+        # A run boundary: verification reads memoized by the previous run are stale.
+        self._fresh_reads.clear()
+        self.apply_structure()
+
+    def apply_structure(self) -> list[str]:
+        """Replay the captured list structure onto the target list (once, idempotent).
+
+        A bundle carries its list shape in a sidecar, not in each record, so the
+        columns (and views) must exist before the first record lands — otherwise a
+        value whose column is missing is dropped by the server. Idempotent
+        (``on_conflict="skip"``), and a no-op when no snapshot was passed.
+
+        Returns:
+            The warnings from this call (empty when there is no snapshot, or when it
+            has already been applied).
+        """
+        if self._structure is None or self._structure_applied:
+            return []
+        self._structure_applied = True
+        # Filling the caller's map in place is what lets a bundle's records land
+        # under the recreated content type instead of being coerced to the default.
+        entries = self._content_type_map.entries if self._content_type_map is not None else None
+        warnings = provision_list_structure(self._list, self._structure, content_type_map=entries)
+        self.warnings.extend(warnings)
+        return warnings
 
     def label(self) -> str:
         return f"list:{self._list.title}"
 
     def exists(self, item: MigrationItem) -> bool:
-        # Keyed dedup happens in _queue (the key is derived from the payload, which
-        # exists() doesn't receive); without a key, records are appended.
-        return False
+        # With the identity marker, both records and attachments are recognized on a
+        # re-run, so the default ``SKIP`` policy is genuinely idempotent. Without it
+        # (``identity_field=None``) nothing is recognized and records append.
+        if not self._identity_field:
+            return False
+        self._ensure_identity()
+        if not self._identity_field:
+            return False
+        if item.item_type == "attachment":
+            return str(item.dest_path) in set(self._attachment_paths())
+        return self._find_by_identity(item.dest_path) is not None
 
     def write(self, item: MigrationItem, payload: object) -> None:
-        self._queue([cast(dict, payload)])
+        if item.item_type == "attachment":
+            self._write_attachment(item, payload)
+            return
+        self._queue([self._record_for(item, payload)])
 
     def write_many(
         self,
@@ -219,16 +1434,68 @@ class SharePointListTarget:
 
         Flushing per chunk (instead of only at :meth:`commit`) keeps a large list
         migration memory-bounded — the queued creates never accumulate for the
-        whole run.
+        whole run. Attachments in the chunk are written after its records are
+        flushed, so their parent items already exist.
 
         Returns:
             No failures (a batch failure raises; there are no partial successes).
         """
-        self._queue([cast(dict, payload) for payload in payloads])
-        self._flush(len(payloads), concurrency)
+        records: list[dict] = []
+        attachments: list[tuple[MigrationItem, object]] = []
+        for item, payload in zip(items, payloads):
+            if item.item_type == "attachment":
+                attachments.append((item, payload))
+            else:
+                records.append(self._record_for(item, payload))
+        if records:
+            self._queue(records)
+            self._flush(len(records), concurrency)
+        for item, payload in attachments:
+            self._write_attachment(item, payload)
         return []
 
+    def _record_for(self, item: MigrationItem, payload: object) -> dict:
+        """The payload with the target content-type id and source-id marker applied."""
+        if not isinstance(payload, dict):
+            # Without this the cast fails as ``TypeError: object is not iterable``, which
+            # names neither the item nor the reason: a file's bytes have no record shape.
+            raise ValueError(
+                f"{item.dest_path!r} is a {item.item_type!r} with a {type(payload).__name__} payload: this target "
+                "writes list records, and a file has no record shape — migrate files into a document library"
+            )
+        record = dict(cast(dict, payload))
+        if self._content_type_map:
+            content_type_id = record.get("ContentTypeId")
+            record["ContentTypeId"] = self._content_type_map.resolve(content_type_id)
+        if self._identity_field:
+            record[self._identity_field] = item.dest_path
+        approval = {name: record[name] for name in _MODERATION_FIELDS if record.get(name) is not None}
+        if approval:
+            self._pending_approval[item.dest_path] = approval
+        return record
+
+    def translate_record(self, record: dict) -> dict:
+        """A source record mapped onto this list without writing it.
+
+        A document library folder is a list item that already exists on the target,
+        so its column values cannot go through the create queue: the record is mapped
+        here (target content-type id, Lookup ids, Person logins, multi-value shapes)
+        and applied with an update instead.
+        """
+        mapped = dict(record)
+        if self._content_type_map:
+            resolved = self._content_type_map.resolve(mapped.get("ContentTypeId"))
+            if resolved:
+                mapped["ContentTypeId"] = resolved
+            else:
+                mapped.pop("ContentTypeId", None)
+        self._remap_typed_values([mapped])
+        return self._multi_value_payload(mapped)
+
     def _queue(self, records: list[dict]) -> None:
+        self._ensure_identity()
+        self._remap_typed_values(records)
+        records = [self._multi_value_payload(record) for record in records]
         if not self._key_columns:
             for record in records:
                 self._list.items.queue_records([record])
@@ -252,23 +1519,682 @@ class SharePointListTarget:
             on_conflict=self._on_conflict,
         )
 
+    def _multi_id_keys(self) -> set[str]:
+        """The ``...Id`` record keys of the multi-value Lookup/Person columns."""
+        names = (*self._multi_lookup_columns(), *self._multi_user_columns())
+        return {ListItem.value_column(name) for name in names}
+
+    def _multi_value_payload(self, record: dict) -> dict:
+        """Reshape multi-value columns for the wire (``{"results": [...]}``).
+
+        A bare list is the semantic value the source records and the checksum work
+        with; the wire wants every multi-value cell wrapped, on create and on MERGE
+        alike (see :func:`_collection_payload`). A record without multi-value
+        columns is passed through untouched.
+        """
+        keys = self._multi_id_keys() | self._multi_choice_columns()
+        if not keys:
+            return record
+        wrapped = dict(record)
+        for key in keys:
+            values = values_of(wrapped.get(key))
+            if values is not None:
+                wrapped[key] = _collection_payload(values)
+        return wrapped
+
+    def _ensure_identity(self) -> None:
+        """Create the source-id marker column (once), best-effort."""
+        if self._identity_ensured or not self._identity_field:
+            return
+        self._identity_ensured = True
+        name = self._identity_field
+        from office365.sharepoint.fields.creation_information import FieldCreationInformation
+        from office365.sharepoint.fields.type import FieldType
+
+        try:
+            self._list.fields.ensure(FieldCreationInformation(name, FieldType.Text)).execute_query()
+        except Exception as e:  # noqa: BLE001 — identity is best-effort; content still migrates
+            self._identity_field = None
+            self.warnings.append(f"could not create the {name!r} identity column: {e}")
+
+    def _columns(self) -> _TypedColumns:
+        """The target's typed columns.
+
+        Returns ``(lookup: name -> referenced list id, user names, multi-lookup:
+        name -> referenced list id, multi-user names, taxonomy: name -> (allows
+        many, hidden note field internal name), multi-choice names)``.
+        """
+        if self._columns_cache is None:
+            self._columns_cache = self._load_columns()
+        return self._columns_cache
+
+    def _lookup_columns(self) -> dict[str, str]:
+        return self._columns()[0]
+
+    def _user_columns(self) -> set[str]:
+        return self._columns()[1]
+
+    def _multi_lookup_columns(self) -> dict[str, str]:
+        return self._columns()[2]
+
+    def _multi_user_columns(self) -> set[str]:
+        return self._columns()[3]
+
+    def _taxonomy_columns(self) -> dict[str, tuple[bool, str | None]]:
+        return self._columns()[4]
+
+    def _multi_choice_columns(self) -> set[str]:
+        return self._columns()[5]
+
+    def _load_columns(self) -> _TypedColumns:
+        lookups: dict[str, str] = {}
+        users: set[str] = set()
+        multi_lookups: dict[str, str] = {}
+        multi_users: set[str] = set()
+        taxonomy: dict[str, tuple[bool, str | None]] = {}
+        multi_choices: set[str] = set()
+        try:
+            fields = self._list.fields.select(Field.scan_columns()).get().execute_query()
+        except Exception as e:  # noqa: BLE001 — without columns we cannot remap; content still migrates
+            self.warnings.append(f"could not read target columns for typed-value remapping: {e}")
+            return lookups, users, multi_lookups, multi_users, taxonomy, multi_choices
+        for field in fields:
+            internal_name = field.internal_name
+            if not internal_name or internal_name in _PERSON_EXCLUDED:
+                continue
+            if field.is_taxonomy:
+                # The companion note column that carries the write payload has a name
+                # the service chooses; the column itself resolves it from ``TextField``.
+                taxonomy[internal_name] = (field.is_multi_valued, cast(TaxonomyField, field).text_field_name)
+            elif field.is_person or field.is_lookup:
+                multiple = field.is_multi_valued
+                if field.is_person:
+                    if multiple:
+                        multi_users.add(internal_name)
+                    else:
+                        users.add(internal_name)
+                else:
+                    list_id = normalize_guid(cast(FieldLookup, field).lookup_list)
+                    if not list_id:
+                        continue
+                    if multiple:
+                        multi_lookups[internal_name] = list_id
+                    else:
+                        lookups[internal_name] = list_id
+            elif field.is_multi_choice:
+                multi_choices.add(internal_name)
+        return lookups, users, multi_lookups, multi_users, taxonomy, multi_choices
+
+    def _lookup_index(self, target_list_id: str) -> tuple[dict[int, int], dict[int, int]]:
+        """``(source id -> target id, target id -> source id)`` for a referenced list."""
+        cached = self._lookup_indexes.get(target_list_id)
+        if cached is not None:
+            return cached
+        forward: dict[int, int] = {}
+        backward: dict[int, int] = {}
+        self._flush_pending()
+        try:
+            referenced = self._list.context.web.lists.get_by_id(target_list_id)
+            items = referenced.items.select(["Id", DEFAULT_LIST_IDENTITY_FIELD]).get_all().execute_query()
+        except Exception as e:  # noqa: BLE001 — an unreadable referenced list is reported, not fatal
+            self.warnings.append(f"lookup target list {target_list_id} could not be read: {e}")
+            items = []
+        for referenced_item in items:
+            source_id = parse_int(referenced_item.properties.get(DEFAULT_LIST_IDENTITY_FIELD))
+            target_id = parse_int(referenced_item.id)
+            if source_id is None or target_id is None:
+                continue
+            forward[source_id] = target_id
+            backward[target_id] = source_id
+        self._lookup_indexes[target_list_id] = (forward, backward)
+        return forward, backward
+
+    def _remap_typed_values(self, records: list[dict]) -> None:
+        """Translate each record's source lookup/person ids into target values.
+
+        A lookup references another migrated list (matched on its items' source-id
+        marker); a person carries the *login name* the source annotated, resolved
+        here with ``EnsureUser``. Either value with no match is dropped and reported
+        once rather than written as a wrong id.
+        """
+        self._remap_lookups(records)
+        self._remap_users(records)
+        self._remap_multi_lookups(records)
+        self._remap_multi_users(records)
+        self._remap_taxonomies(records)
+
+    def _remap_lookups(self, records: list[dict]) -> None:
+        columns = self._lookup_columns()
+        if not columns:
+            return
+        for record in records:
+            for internal_name, target_list_id in columns.items():
+                key = ListItem.value_column(internal_name)
+                source_id = parse_int(record.get(key))
+                if source_id is None:
+                    continue
+                forward, _ = self._lookup_index(target_list_id)
+                target_id = forward.get(source_id)
+                if target_id is None:
+                    record.pop(key, None)
+                    self._report_unresolved_lookup(internal_name, source_id)
+                    continue
+                record[key] = target_id
+
+    def _remap_users(self, records: list[dict]) -> None:
+        columns = self._user_columns()
+        if not columns:
+            return
+        for record in records:
+            for internal_name in columns:
+                key = ListItem.value_column(internal_name)
+                login = record.get(key)
+                if not isinstance(login, str) or not login:
+                    continue
+                user = self._principals().user(login)
+                if user is None or getattr(user, "id", None) is None:
+                    record.pop(key, None)
+                    self._report_unresolved_user(internal_name, login)
+                    continue
+                record[key] = user.id
+
+    def _remap_multi_lookups(self, records: list[dict]) -> None:
+        columns = self._multi_lookup_columns()
+        if not columns:
+            return
+        for record in records:
+            for internal_name, target_list_id in columns.items():
+                key = ListItem.value_column(internal_name)
+                source_ids = values_of(record.get(key))
+                if not source_ids:
+                    continue
+                forward, _ = self._lookup_index(target_list_id)
+                target_ids: list[int] = []
+                for value in source_ids:
+                    source_id = parse_int(value)
+                    target_id = forward.get(source_id) if source_id is not None else None
+                    if target_id is None:
+                        if source_id is not None:
+                            self._report_unresolved_lookup(internal_name, source_id)
+                        continue
+                    target_ids.append(target_id)
+                if target_ids:
+                    record[key] = target_ids
+                else:
+                    record.pop(key, None)
+
+    def _remap_multi_users(self, records: list[dict]) -> None:
+        columns = self._multi_user_columns()
+        if not columns:
+            return
+        for record in records:
+            for internal_name in columns:
+                key = ListItem.value_column(internal_name)
+                logins = record.get(key)
+                if not isinstance(logins, (list, tuple)) or not logins:
+                    continue
+                target_ids: list[int] = []
+                for login in logins:
+                    user = self._principals().user(login) if isinstance(login, str) and login else None
+                    user_id = getattr(user, "id", None)
+                    if user is None or user_id is None:
+                        self._report_unresolved_user(internal_name, str(login))
+                        continue
+                    target_ids.append(user_id)
+                if target_ids:
+                    record[key] = target_ids
+                else:
+                    record.pop(key, None)
+
+    def _remap_taxonomies(self, records: list[dict]) -> None:
+        """Write taxonomy terms in the form SharePoint accepts on the target.
+
+        A single-value column takes :class:`TaxonomyFieldValue` itself — the library
+        type, not a dictionary spelled like one — so its declared type name and
+        ``WssId = -1`` default are answered by the value. A multi-value column only
+        accepts the hidden note companion's text form ``-1;#Label|guid;#...``
+        (typed-collection JSON is rejected server-side). The term id is authoritative,
+        so the label is left unset. A column with no target counterpart is dropped and
+        reported rather than sent as an unknown property.
+        """
+        columns = self._taxonomy_columns()
+        unresolved: set[str] = set()
+        for record in records:
+            for internal_name, value in list(record.items()):
+                if not _is_taxonomy_value(value):
+                    continue
+                guids = _taxonomy_guids(value)
+                column = columns.get(internal_name)
+                if column is None:
+                    record.pop(internal_name, None)
+                    unresolved.add(internal_name)
+                    continue
+                allow_many, note_name = column
+                if not guids:
+                    record.pop(internal_name, None)
+                    continue
+                if allow_many and note_name:
+                    record.pop(internal_name, None)
+                    values = [TaxonomyFieldValue(TermGuid=g) for g in guids]
+                    record[note_name] = str(TaxonomyFieldValueCollection(values))
+                elif allow_many:
+                    record.pop(internal_name, None)
+                    unresolved.add(internal_name)
+                else:
+                    record[internal_name] = TaxonomyFieldValue(TermGuid=guids[0])
+        if unresolved:
+            self.warnings.append(
+                f"taxonomy column(s) not available on the target, values left empty: {', '.join(sorted(unresolved))}"
+            )
+
+    def _report_unresolved_user(self, internal_name: str, login: str) -> None:
+        marker = (internal_name, login)
+        if marker in self._unresolved_users:
+            return
+        self._unresolved_users.add(marker)
+        self.warnings.append(
+            f"person column '{internal_name}' login {login!r} could not be resolved on the target; "
+            "the value was left empty"
+        )
+
+    def _target_user_logins(self) -> dict[int, str]:
+        """The target web's ``{site-user id: login name}`` map (cached)."""
+        if self._user_logins is None:
+            mapping: dict[int, str] = {}
+            try:
+                for site_user in self._list.context.web.site_users.get().execute_query():
+                    user_id = parse_int(site_user.id)
+                    if user_id is not None and site_user.login_name:
+                        mapping[user_id] = site_user.login_name
+            except Exception as e:  # noqa: BLE001 — without the map persons are left as ids
+                self.warnings.append(f"could not read target site users for person verification: {e}")
+            self._user_logins = mapping
+        return self._user_logins
+
+    def _report_unresolved_lookup(self, internal_name: str, source_id: int) -> None:
+        marker = (internal_name, source_id)
+        if marker in self._unresolved_lookups:
+            return
+        self._unresolved_lookups.add(marker)
+        self.warnings.append(
+            f"lookup column '{internal_name}' value {source_id} could not be mapped to a target item "
+            "(the referenced list's items were not migrated first); the value was left empty"
+        )
+
+    def _canonicalize_lookups(self, properties: dict) -> None:
+        """Rewrite target lookup ids back to the source ids (symmetric to the write).
+
+        The source checksum holds the source item id; the target's fresh item holds
+        the target id. Mapping the latter back lets the content spot-check compare
+        the two like for like instead of reporting a false mismatch.
+        """
+        for internal_name, target_list_id in self._lookup_columns().items():
+            key = ListItem.value_column(internal_name)
+            target_id = parse_int(properties.get(key))
+            if target_id is None:
+                continue
+            _, backward = self._lookup_index(target_list_id)
+            source_id = backward.get(target_id)
+            if source_id is not None:
+                properties[key] = source_id
+        for internal_name, target_list_id in self._multi_lookup_columns().items():
+            key = ListItem.value_column(internal_name)
+            target_ids = values_of(properties.get(key))
+            if not target_ids:
+                continue
+            _, backward = self._lookup_index(target_list_id)
+            mapped: list[Any] = []
+            for value in target_ids:
+                target_id = parse_int(value)
+                mapped.append(backward.get(target_id, value) if target_id is not None else value)
+            properties[key] = mapped
+
+    def _canonicalize_users(self, properties: dict) -> None:
+        """Rewrite target person ids back to the login names the source recorded."""
+        columns = self._user_columns()
+        logins = self._target_user_logins() if columns or self._multi_user_columns() else {}
+        for internal_name in columns:
+            key = ListItem.value_column(internal_name)
+            user_id = parse_int(properties.get(key))
+            if user_id is None:
+                continue
+            login = logins.get(user_id)
+            if login is not None:
+                properties[key] = login
+        for internal_name in self._multi_user_columns():
+            key = ListItem.value_column(internal_name)
+            user_ids = values_of(properties.get(key))
+            if not user_ids:
+                continue
+            mapped_logins: list[Any] = []
+            for value in user_ids:
+                user_id = parse_int(value)
+                mapped_logins.append(logins.get(user_id, value) if user_id is not None else value)
+            properties[key] = mapped_logins
+
+    def _canonicalize_multi_choices(self, properties: dict) -> None:
+        """Reduce a read-back multi-choice cell to the bare list the source records.
+
+        A live read returns the selected values as a positional mapping
+        (``{0: "red", 1: "green"}``); the source checksum holds a bare list, so the
+        two are only comparable after the same projection.
+        """
+        for internal_name in self._multi_choice_columns():
+            if internal_name not in properties:
+                continue
+            values = values_of(properties.get(internal_name))
+            if values:
+                properties[internal_name] = values
+            else:
+                properties.pop(internal_name, None)
+
+    def _write_attachment(self, item: MigrationItem, payload: object) -> None:
+        if not self._identity_field:
+            raise NotImplementedError("attachments need the identity column, which could not be created")
+        parent_id, _, filename = str(item.dest_path).partition("/")
+        if not filename:
+            raise ValueError(f"invalid attachment destination {item.dest_path!r}")
+        self._flush_pending()
+        parent = self._find_by_identity(parent_id)
+        if parent is None:
+            raise ValueError(f"no target item for source id {parent_id!r}; cannot attach {filename!r}")
+        content = payload if isinstance(payload, bytes) else str(payload).encode("utf-8")
+        parent.attachment_files.add({"filename": filename, "content": content}).execute_query()
+        if self._attachment_path_cache is not None:
+            self._attachment_path_cache.add(str(item.dest_path))
+
+    def _flush_pending(self) -> None:
+        if self._list.context.has_pending_request:
+            self._flush(DEFAULT_BATCH_SIZE, 1)
+
+    def _find_by_identity(self, source_id: str):
+        if self._identity_index is None or self._identity_index_stale:
+            self._refresh_identity_index()
+        return self._identity_index.get(str(source_id)) if self._identity_index else None
+
+    def _refresh_identity_index(self) -> None:
+        """Load, or incrementally extend, the source-id -> target item map.
+
+        After a chunk is flushed only the newly created items are re-read
+        (``Id gt <max>``) instead of re-scanning the whole list, so refreshing the
+        index per chunk stays linear rather than O(n²).
+        """
+        if not self._identity_field:
+            self._identity_index = {}
+            return
+        if self._identity_index is not None and self._identity_index_max_id > 0:
+            self._index_identity_items(self._query_identity_items(f"Id gt {self._identity_index_max_id}"))
+            return
+        self._identity_index = {}
+        self._identity_index_max_id = 0
+        self._index_identity_items(self._query_identity_items())
+
+    def _query_identity_items(self, filter_expr: str | None = None):
+        # A read query would implicitly flush any queued writes on this context;
+        # flush them explicitly first so the cached index stays consistent.
+        self._flush_pending()
+        columns = ["Id", self._identity_field, "Created", "Modified", *_LIST_ITEM.columns_of_facet(AUTHORSHIP)]
+        query = self._list.items.select(columns)
+        if filter_expr:
+            query = query.filter(filter_expr)
+        return query.get_all().execute_query()
+
+    def _index_identity_items(self, items) -> None:
+        if self._identity_index is None:
+            self._identity_index = {}
+        for target_item in items:
+            value = target_item.properties.get(self._identity_field)
+            if value is None:
+                continue
+            self._identity_index[str(value)] = target_item
+            item_id = parse_int(getattr(target_item, "id", None))
+            if item_id is not None and item_id > self._identity_index_max_id:
+                self._identity_index_max_id = item_id
+        self._identity_index_stale = False
+
+    def _attachment_paths(self) -> list[str]:
+        if not self._identity_field:
+            return []
+        if self._attachment_path_cache is None:
+            self._attachment_path_cache = set(self._query_attachment_paths())
+        return list(self._attachment_path_cache)
+
+    def _query_attachment_paths(self) -> list[str]:
+        if not self._identity_field:
+            return []
+        self._flush_pending()
+        items = (
+            self._list.items.select(["Id", self._identity_field]).expand(["AttachmentFiles"]).get_all().execute_query()
+        )
+        paths: list[str] = []
+        for target_item in items:
+            value = target_item.properties.get(self._identity_field)
+            if value is None:
+                continue
+            for attachment in target_item.properties.get("AttachmentFiles") or []:
+                name = getattr(attachment, "file_name", None)
+                if name:
+                    paths.append(f"{value}/{name}")
+        return paths
+
+    @site_access(SiteLevel.READ)
     def list_paths(self) -> list[str]:
-        return [str(i.id) for i in self._list.items.get().execute_query()]
+        if not self._identity_field:
+            return [str(i.id) for i in self._list.items.get().execute_query()]
+        # An empty source list never queues a write, so the marker column was not
+        # created during migration; ensure it before verification queries it.
+        self._ensure_identity()
+        if not self._identity_field:
+            return [str(i.id) for i in self._list.items.get().execute_query()]
+        if self._identity_index is None or self._identity_index_stale:
+            self._refresh_identity_index()
+        index = self._identity_index or {}
+        return list(index.keys()) + self._attachment_paths()
 
     def checksum(self, item: MigrationItem) -> str:
-        return ""
+        if item.item_type == "attachment":
+            return self._attachment_checksum(item)
+        target_item = self._fresh_target_item(item)
+        if target_item is None:
+            return ""
+        return self.content_checksum(dict(target_item.properties))
+
+    def content_checksum(self, properties: dict) -> str:
+        """The comparable content hash of an item's read-back properties.
+
+        Used for both a written record and a folder's item, so a library folder's
+        column values can be reconciled against the source record that produced them.
+        """
+        properties = _canonicalize_taxonomy_record(dict(properties))
+        self._canonicalize_lookups(properties)
+        self._canonicalize_users(properties)
+        self._canonicalize_multi_choices(properties)
+        extra = {self._identity_field} if self._identity_field else set()
+        # The hidden taxonomy note companion is not part of the source's portable
+        # content; it is verified through the term ids on the column itself.
+        extra.update(note for _, note in self._taxonomy_columns().values() if note)
+        # The target derives its own ``<name>StringId`` companion; it is not part of
+        # the source's canonical content.
+        extra.update(ListItem.string_value_column(name) for name in self._user_columns())
+        extra.update(ListItem.string_value_column(name) for name in self._multi_user_columns())
+        return _content_checksum(properties, frozenset(extra))
+
+    def _attachment_checksum(self, item: MigrationItem) -> str:
+        parent_id, _, filename = str(item.dest_path).partition("/")
+        parent = self._find_by_identity(parent_id)
+        if parent is None:
+            return ""
+        try:
+            data = parent.attachment_files.get_by_filename(filename).get_content().execute_query().value
+        except Exception:  # noqa: BLE001 — a missing/unreadable attachment is unverifiable
+            return ""
+        return checksum(data) if data else ""
 
     def commit(self, options=None) -> None:
         """Flush any remaining queued record writes through an OData batch."""
         batch_size = getattr(options, "batch_size", None) or DEFAULT_BATCH_SIZE
         concurrency = getattr(options, "concurrency", None) or 1
         self._flush(batch_size, concurrency)
+        self._pending_authorship.clear()
+        self._pending_approval.clear()
 
     def _flush(self, batch_size: int, concurrency: int) -> None:
         if not self._list.context.has_pending_request:
             return
         self._list.context.execute_batch(items_per_batch=batch_size, concurrency=concurrency)
+        self._fresh_reads.clear()
         self._list.items.clear()
+        # Records were just created/updated, so the cached source-id index needs an
+        # incremental refresh (new items only) before the next lookup.
+        if self._identity_index is not None:
+            self._identity_index_stale = True
+
+    def _principals(self) -> _TargetPrincipals:
+        """The (lazily built) target principal/role resolver."""
+        if self._principals_cache is None:
+            self._principals_cache = _TargetPrincipals(self._list.context.web, self.warnings)
+        return self._principals_cache
+
+    def _target_item(self, item: MigrationItem):
+        """The written target item for a record (``None`` for attachments/folders)."""
+        if item.item_type == "attachment":
+            return None
+        return self._find_by_identity(item.dest_path)
+
+    @site_access(SiteLevel.WRITE)
+    def apply_timestamps(self, item: MigrationItem) -> None:
+        """Best-effort: restore ``Created``/``Modified`` on the written item.
+
+        Authorship and approval state resolved for the same item are folded in, so all of
+        them land atomically in one system update.
+        """
+        self._restore_fidelity(item, timestamps=True)
+
+    def _restore_fidelity(self, item: MigrationItem, timestamps: bool) -> None:
+        """One system update carrying every fidelity value this item has.
+
+        ``timestamps=False`` is the write :meth:`finalize_fidelity` makes when the item's
+        dates are not preserved: the values are already absent, so what is left is the
+        authorship and approval state, and they still cost one request rather than two.
+        """
+        target_item = self._target_item(item)
+        if target_item is None:
+            return
+        authorship = self._pending_authorship.pop(item.dest_path, {})
+        approval = self._pending_approval.pop(item.dest_path, {})
+        created = iso_z(item.created) if timestamps else None
+        modified = iso_z(item.modified) if timestamps else None
+        if not (created or modified or authorship or approval):
+            return
+        self._fresh_reads.pop(str(item.dest_path), None)
+        result = target_item.restore_fidelity(
+            created=created,
+            modified=modified,
+            author=authorship.get("Author"),
+            editor=authorship.get("Editor"),
+            approval=approval,
+            new_document_update=True,
+        ).execute_query()
+        _report_rejected_fields(result, self.warnings, f"timestamps {item.dest_path}")
+
+    def apply_authorship(self, item: MigrationItem) -> None:
+        """Best-effort: resolve ``Author``/``Editor`` and cache them for one write.
+
+        A principal is applied only when its login name resolves to a target user
+        (``EnsureUser``); unresolved principals are skipped (same-tenant only).
+
+        Nothing is sent here. ``ValidateUpdateListItem`` is one request per call, so a
+        separate authorship write followed by the timestamps write would cost every
+        preserved item two system updates. The resolved principals are cached and
+        written by :meth:`apply_timestamps`, or by :meth:`finalize_fidelity` when
+        timestamps are not preserved.
+        """
+        target_item = self._target_item(item)
+        if target_item is None:
+            return
+        author = self._principals().user(item.author.login_name if item.author else None)
+        editor = self._principals().user(item.editor.login_name if item.editor else None)
+        if author is not None and author.is_service_account:
+            author = None
+        if editor is not None and editor.is_service_account:
+            editor = None
+        if author is None and editor is None:
+            return
+        self._pending_authorship[item.dest_path] = {
+            "Author": author,
+            "Editor": editor,
+        }
+
+    @site_access(SiteLevel.WRITE)
+    def finalize_fidelity(self, item: MigrationItem) -> None:
+        """Write the fidelity values that were only cached for this item.
+
+        The last hook wins the write: with timestamps preserved that is
+        :meth:`apply_timestamps`; without them it is this method, so the item still
+        gets one system update instead of one per property group.
+        """
+        self._restore_fidelity(item, timestamps=False)
+
+    @site_access(SiteLevel.MANAGE)
+    def apply_permissions(self, item: MigrationItem, permissions: list[PermissionEntry]) -> None:
+        """Best-effort: replay the source item's unique ACLs onto the target item.
+
+        Same-tenant only — cross-tenant identity mapping is out of scope. See
+        :func:`_replay_role_assignments` for what happens to principals, roles and
+        inheritance that cannot be resolved.
+        """
+        target_item = self._target_item(item)
+        if target_item is None:
+            return
+        self._fresh_reads.pop(str(item.dest_path), None)
+        _replay_role_assignments(target_item, self._principals(), permissions, self.warnings, item.dest_path)
+        self._list.context.execute_query()
+
+    def _fresh_target_item(self, item: MigrationItem):
+        """The written target item with freshly-read properties (verification hooks).
+
+        The cached identity-index object predates the fidelity writes
+        (``apply_timestamps``/``apply_authorship``), so re-read it before diffing.
+        The read is memoized per destination path: verification asks for the same
+        item through :meth:`checksum`, :meth:`read_metadata`,
+        :meth:`read_authorship` and :meth:`read_permissions`, and four reads of an
+        unchanged item are three requests too many. Every write clears the memo.
+        """
+        key = str(item.dest_path)
+        if key in self._fresh_reads:
+            return self._fresh_reads[key]
+        target_item = self._target_item(item)
+        if target_item is not None:
+            target_item.get().execute_query()
+        self._fresh_reads[key] = target_item
+        return target_item
+
+    def read_metadata(self, item: MigrationItem) -> dict | None:
+        """Comparable attributes of the written item (for the metadata diff)."""
+        target_item = self._fresh_target_item(item)
+        if target_item is None:
+            return None
+        return {
+            "created": iso_or_none(target_item.created),
+            "modified": iso_or_none(target_item.modified),
+        }
+
+    def read_authorship(self, item: MigrationItem) -> tuple[str | None, str | None]:
+        """The written item's author/editor login names (for the authorship diff)."""
+        target_item = self._fresh_target_item(item)
+        if target_item is None:
+            return (None, None)
+        return (
+            _user_login(self._list.context.web, target_item.author_id, self._login_cache),
+            _user_login(self._list.context.web, target_item.editor_id, self._login_cache),
+        )
+
+    def read_permissions(self, item: MigrationItem) -> list[PermissionEntry]:
+        """Read the written item's *unique* role assignments (for the permission diff)."""
+        target_item = self._fresh_target_item(item)
+        if target_item is None or not _has_unique_role_assignments(target_item, refresh=True):
+            return []
+        return _read_role_assignments(target_item, normalize=self._principals().normalize)
 
     def close(self) -> None:
         pass
@@ -278,22 +2204,55 @@ class SharePointLibrarySource:
     """Enumerates a document library's files and folders (recursively) for migration.
 
     Folder entries (``item_type="folder"``, trailing ``/`` on the destination)
-    preserve the folder structure — including **empty** folders — on the target.
+    preserve the folder structure — including **empty** folders — on the target, and
+    carry the folder's own column values (a document set's metadata, a managed
+    folder's department) as their payload when the parent list is known.
     """
 
+    def rebind(self) -> "SharePointLibrarySource":
+        """This source on its own cloned context (see :meth:`SharePointListSource.rebind`)."""
+        context = _cloned_context(self._folder)
+        sp_list = _cloned_list(self._sp_list, context) if self._sp_list is not None else None
+        return SharePointLibrarySource(_cloned_folder(self._folder, context), self.on_bytes, sp_list=sp_list)
+
     def __init__(
         self,
         library_folder: "Folder",
         on_bytes: Callable[[int, int | None], None] | None = None,
+        sp_list: "SPList | None" = None,
     ) -> None:
         self._folder = library_folder
+        # The parent list, when known — author/editor ids (``AuthorId``/``EditorId``)
+        # are not exposed on the ``File`` resource and must be read from its items.
+        self._sp_list = sp_list
+        # Folder column values come from the list's items and are projected exactly
+        # like a record's (typed values normalized), so that code is reused here.
+        self._list_source = SharePointListSource(sp_list) if sp_list is not None else None
+        self._folder_payloads: dict[str, dict] | None = None
         self._files: dict[str, "File"] = {}
+        # Folder resources by library-relative path, so their own system metadata
+        # (``TimeCreated``/``TimeLastModified``) can be diffed after the run.
+        self._folders: dict[str, "Folder"] = {}
+        self._users: dict[int, "Principal | None"] = {}
+        # Group title -> (owner user, owner group chain); a ``<Group>`` needs both.
+        self._group_owners: dict[str, tuple["Principal | None", list[str]]] = {}
+        self._default_groups: _DefaultGroups | None = None
+        self._item_authors: dict[str, tuple[int | None, int | None]] | None = None
+        self._item_unique: dict[str, bool] | None = None
+        # Content-approval state by file URL, read alongside the author ids (only
+        # when the library moderates).
+        self._item_moderation: dict[str, dict] | None = None
+        # Server-relative URLs of checked-out files, read alongside the author ids.
+        self._item_checkout: set[str] | None = None
+        self._moderation_on: bool | None = None
+        self.warnings: list[str] = []
         # Optional hook invoked while a file downloads: (bytes_read, file_size)
         self.on_bytes = on_bytes
 
     def label(self) -> str:
         return f"library:{self._folder.server_relative_url}"
 
+    @site_access(SiteLevel.READ)
     def list_items(self, progress: MigrationProgress = None) -> list[MigrationItem]:
         # The root folder's URL may not be loaded yet (e.g. via
         # ``list.root_folder``); fetch it so destinations stay library-relative
@@ -303,8 +2262,10 @@ class SharePointLibrarySource:
             self._folder.ensure_properties(["ServerRelativeUrl"]).execute_query()
             root = self._folder.server_relative_url or ""
         root = root.rstrip("/")
+        extra = _site_assets_scaffolding(self._folder)
         loaded_folders = self._folder.get_folders(recursive=True).execute_query()
         loaded = self._folder.get_files(recursive=True).execute_query()
+        authors = self._file_authors()
 
         def _rel(url: str) -> str:
             return url[len(root) :].lstrip("/") if root else url.lstrip("/")
@@ -314,33 +2275,107 @@ class SharePointLibrarySource:
         for folder in loaded_folders:
             url = folder.server_relative_url or ""
             rel = _rel(url)
-            if not rel or rel in seen:
+            if not rel or rel in seen or self._folder.is_system_path(rel, extra):
                 continue
             seen.add(rel)
-            result.append(MigrationItem(source_path=url, dest_path=f"{rel}/", item_type="folder"))
+            self._folders[rel] = folder
+            author_id, editor_id = authors.get(url, (None, None))
+            folder_item = MigrationItem(
+                source_path=url,
+                dest_path=f"{rel}/",
+                item_type="folder",
+                modified=iso_or_none(folder.time_last_modified),
+                created=iso_or_none(folder.time_created),
+            )
+            folder_item.author = self._principal_for(author_id)
+            folder_item.editor = self._principal_for(editor_id)
+            result.append(folder_item)
             emit_progress(progress, done=len(result), stage="planning", items=[folder])
         for file in loaded:
             url = file.server_relative_url or ""
             rel = _rel(url)
+            if self._folder.is_system_path(rel, extra):
+                continue
             self._files[rel] = file
-            result.append(
-                MigrationItem(
-                    source_path=url,
-                    dest_path=rel,
-                    size_bytes=file.length or 0,
-                    item_type="file",
-                    modified=iso_or_none(file.time_last_modified),
-                    created=iso_or_none(file.time_created),
-                    author_id=parse_int(file.author.id),
-                    editor_id=parse_int(file.modified_by.id),
-                )
+            author_id = parse_int(file.author.id)
+            editor_id = parse_int(file.modified_by.id)
+            if author_id is None and editor_id is None:
+                author_id, editor_id = authors.get(url, (None, None))
+            item = MigrationItem(
+                source_path=url,
+                dest_path=rel,
+                size_bytes=file.length or 0,
+                item_type="file",
+                modified=iso_or_none(file.time_last_modified),
+                created=iso_or_none(file.time_created),
+                source_id=str(file.unique_id) if file.unique_id else None,
+                version_label=file.ui_version_label,
             )
+            item.author = self._principal_for(author_id)
+            item.editor = self._principal_for(editor_id)
+            result.append(item)
             emit_progress(progress, done=len(result), stage="planning", items=[file])
+        self._report_checkouts(result)
+        self._report_drafts(result)
         return result
 
-    def read(self, item: MigrationItem) -> bytes:
+    def _report_checkouts(self, items: list[MigrationItem]) -> None:
+        """Warn about files whose in-progress edits REST cannot see.
+
+        A checked-out file exposes its last **checked-in** content, so the copy is
+        faithful to what the source returns while the author's pending edits stay
+        behind. Verification cannot catch that — it compares the same read — so the
+        loss is reported here instead of passing silently.
+        """
+        checkout = self._item_checkout or set()
+        checked = sorted(item.dest_path for item in items if item.item_type != "folder" and item.source_path in checkout)
+        if not checked:
+            return
+        shown = ", ".join(checked[:_WARNING_SAMPLE])
+        if len(checked) > _WARNING_SAMPLE:
+            shown = f"{shown} and {len(checked) - _WARNING_SAMPLE} more"
+        self.warnings.append(
+            f"{len(checked)} checked-out file(s) were copied from their last checked-in version "
+            f"(in-progress edits are not visible over REST): {shown}"
+        )
+
+    def _report_drafts(self, items: list[MigrationItem]) -> None:
+        """Warn about files whose current version is an un-published (minor) draft.
+
+        REST returns the *draft* content, so the copy is faithful to the version the
+        source reports — but version history is not preserved, so the published
+        version a draft supersedes never reaches the target and the copy keeps the
+        draft alone. Verification compares the same read and cannot see the
+        difference, so the loss is reported here instead of passing silently.
+
+        The signal rides the file listing (``MinorVersion``), so this costs no extra
+        request: a published file is ``x.0``, a draft ``x.n`` with ``n > 0``.
+        """
+        drafts: list[str] = []
+        for item in items:
+            if item.item_type == "folder":
+                continue
+            file = self._files.get(item.dest_path)
+            if file is None or not file.minor_version:
+                continue
+            drafts.append(item.dest_path)
+        if not drafts:
+            return
+        drafts.sort()
+        shown = ", ".join(drafts[:_WARNING_SAMPLE])
+        if len(drafts) > _WARNING_SAMPLE:
+            shown = f"{shown} and {len(drafts) - _WARNING_SAMPLE} more"
+        self.warnings.append(
+            f"{len(drafts)} file(s) are on an un-published (minor) version: the draft content "
+            f"is copied, the published version it supersedes is not (version history is not "
+            f"preserved): {shown}"
+        )
+
+    @site_access(SiteLevel.READ)
+    def read(self, item: MigrationItem) -> object:
         if item.item_type == "folder":
-            return b""
+            # A folder's payload is its column values (empty when it carries none).
+            return self._folder_values(item) or b""
         file = self._files.get(item.dest_path)
         if file is None:
             raise FileNotFoundError(item.source_path)
@@ -354,10 +2389,53 @@ class SharePointLibrarySource:
         file.download_session(buffer, chunk_downloaded=_chunk_downloaded).execute_query()
         return buffer.getvalue()
 
+    @site_access(SiteLevel.READ)
+    def read_version_history(self, item: MigrationItem) -> tuple[str | None, list[tuple[str, bytes]]]:
+        """Read the file's current version label and its older versions.
+
+        Returns ``(current_label, older)`` where ``older`` is oldest-first and
+        excludes the current version (which :meth:`read` already supplies). The
+        current label comes from ``UIVersionLabel``; older content is streamed
+        from each ``File.Versions`` entry. Folders have no version history.
+        """
+        if item.item_type == "folder":
+            return None, []
+        file = self._files.get(item.dest_path)
+        if file is None:
+            raise FileNotFoundError(item.source_path)
+        if file.ui_version_label is None:
+            file.ensure_property("UIVersionLabel").execute_query()
+        older: list[tuple[str, bytes]] = []
+        for version in sorted(file.versions.get().execute_query(), key=lambda v: v.sort_key):
+            label = version.version_label
+            if label and not version.is_current_version:
+                older.append((label, version.open_binary_stream().execute_query().value or b""))
+        return file.ui_version_label, older
+
+    @property
+    def supports_folder_records(self) -> bool:
+        """Whether a folder's column values are migrated *and* comparable."""
+        return self._list_source is not None
+
     def checksum(self, item: MigrationItem) -> str:
         if item.item_type == "folder":
-            return hashlib.md5(b"").hexdigest()
-        return hashlib.md5(self.read(item)).hexdigest()
+            return _content_checksum(_canonicalize_taxonomy_record(self._folder_values(item)))
+        return checksum(cast(bytes, self.read(item)))
+
+    def _folder_values(self, item: MigrationItem) -> dict:
+        """The source folder's column values (empty when it carries none)."""
+        if self._folder_payloads is None:
+            payloads: dict[str, dict] = {}
+            if self._sp_list is None or self._list_source is None:
+                self.warnings.append(
+                    "folder column values were not read: the parent library is unknown "
+                    "(pass sp_list to SharePointLibrarySource)"
+                )
+            else:
+                payloads.update(self._list_source.folder_records())
+                self.warnings.extend(self._list_source.warnings)
+            self._folder_payloads = payloads
+        return self._folder_payloads.get(str(item.source_path).rstrip("/"), {})
 
     def read_permissions(self, item: MigrationItem) -> list[PermissionEntry]:
         """Read the item's role assignments (for best-effort ACL preservation).
@@ -368,16 +2446,59 @@ class SharePointLibrarySource:
         securable = self._securable(item)
         if securable is None:
             return []
-        assignments = securable.role_assignments.expand(["Member", "RoleDefinitionBindings"]).get().execute_query()
-        result: list[PermissionEntry] = []
-        for assignment in assignments:
-            member = assignment.member
-            name = member.login_name or member.user_principal_name
-            if not name:
-                continue
-            roles = [r.name for r in assignment.role_definition_bindings if r.name]
-            result.append(PermissionEntry(principal_name=name, roles=roles))
-        return result
+        # Files: reuse the unique-ACL flag read with the authorship pass (the
+        # ``File``/``ListItem`` resources do not expose it without an extra GET).
+        if item.item_type != "folder" and self._item_unique is not None:
+            unique = self._item_unique.get(item.source_path)
+            if unique is not None:
+                securable.properties["HasUniqueRoleAssignments"] = unique
+        if not _has_unique_role_assignments(securable):
+            return []
+        entries = _read_role_assignments(securable, resolve=self._principal_for, normalize=self._normalize_name)
+        _attach_group_owners(entries, self._folder.context.web, self._principal_for, self._group_owners)
+        return entries
+
+    def _normalize_name(self, name: str) -> str:
+        """Canonicalize a principal name (default groups -> ``default:<Kind>``)."""
+        context = getattr(self._folder, "context", None)
+        web = getattr(context, "web", None) if context is not None else None
+        if web is None:
+            return name
+        if self._default_groups is None:
+            self._default_groups = _DefaultGroups(web)
+        return self._default_groups.normalize(name)
+
+    def read_metadata(self, item: MigrationItem) -> dict | None:
+        """Comparable attributes of the source item (for the post-run metadata diff)."""
+        if item.item_type == "folder":
+            folder = self._folders.get(str(item.dest_path).rstrip("/"))
+            if folder is None:
+                return None
+            return {
+                "created": iso_or_none(folder.time_created),
+                "modified": iso_or_none(folder.time_last_modified),
+            }
+        file = self._files.get(item.dest_path)
+        if file is None:
+            return None
+        metadata = {
+            "created": iso_or_none(file.time_created),
+            "modified": iso_or_none(file.time_last_modified),
+            "size_bytes": file.length or 0,
+        }
+        self._file_authors()
+        state = (self._item_moderation or {}).get(item.source_path)
+        if state:
+            status = state.get(_MODERATION_STATUS)
+            metadata["moderation_status"] = None if status is None else str(status)
+        return metadata
+
+    def read_authorship(self, item: MigrationItem) -> tuple[str | None, str | None]:
+        """The source author/editor login names (for the authorship diff)."""
+        return (
+            item.author.login_name if item.author else None,
+            item.editor.login_name if item.editor else None,
+        )
 
     def _securable(self, item: MigrationItem):
         if item.item_type == "folder":
@@ -385,6 +2506,105 @@ class SharePointLibrarySource:
         file = self._files.get(item.dest_path)
         return file.listItemAllFields if file is not None else None
 
+    def _principal_for(self, user_id: Any) -> "Principal | None":
+        """Resolve a site-user id to a :class:`Principal` (login + PUID), cached."""
+        key = parse_int(user_id)
+        if key is None:
+            return None
+        if key in self._users:
+            return self._users[key]
+        principal: "Principal | None" = None
+        try:
+            user = self._folder.context.web.site_users.get_by_id(cast("str", key)).get().execute_query()
+            principal = _principal_of(user, key)
+            if user.user_id.name_id and principal.system_id is None:
+                # e.g. the app principal, whose ``UserId.NameId`` is not a PUID.
+                # Emitting it would fail the whole ingestion job, so drop it.
+                self.warnings.append(
+                    f"user {key} ({user.login_name!r}) has no usable PUID ({user.user_id.name_id!r}); "
+                    "it is omitted from the server-side user map"
+                )
+        except Exception as e:  # noqa: BLE001 — a missing user degrades to no authorship
+            self.warnings.append(f"user {key} could not be resolved: {e}")
+        self._users[key] = principal
+        return principal
+
+    def _file_authors(self) -> dict[str, tuple[int | None, int | None]]:
+        """Author/editor ids by server-relative file URL (one list-items read).
+
+        ``File.Author``/``ModifiedBy`` is a non-expandable navigation on the File
+        resource, so the ids come from the parent library's list items.
+        """
+        if self._item_authors is not None:
+            return self._item_authors
+        authors: dict[str, tuple[int | None, int | None]] = {}
+        unique: dict[str, bool] = {}
+        moderation: dict[str, dict] = {}
+        checkout: set[str] = set()
+        moderates = self._moderation_enabled()
+        if self._sp_list is not None:
+            try:
+                # ``CheckoutUser`` is a user field: it only projects when its
+                # sub-properties are selected *and* the field is expanded — a bare
+                # ``$select=CheckoutUser`` is rejected by the server.
+                select = ["FileRef", *_METADATA_SELECT, "CheckoutUser/Id", "CheckoutUser/Title"]
+                if moderates:
+                    select.extend(_MODERATION_FIELDS)
+                items = self._sp_list.items.select(select).expand(["CheckoutUser"]).get_all().execute_query()
+                for item in items:
+                    ref = item.file_ref
+                    if ref:
+                        authors[ref] = (item.author_id, item.editor_id)
+                        unique[ref] = bool(item.has_unique_role_assignments)
+                        if item.properties.get("CheckoutUser"):
+                            checkout.add(ref)
+                        if moderates:
+                            state = _moderation_state(item.properties)
+                            if state:
+                                moderation[ref] = state
+            except Exception as e:  # noqa: BLE001 — authorship is best-effort
+                self.warnings.append(f"author/editor read failed: {e}")
+        self._item_authors = authors
+        self._item_unique = unique
+        self._item_moderation = moderation
+        self._item_checkout = checkout
+        return authors
+
+    def _moderation_enabled(self) -> bool:
+        """Whether the parent library enables content approval (read once)."""
+        if self._moderation_on is None:
+            self._moderation_on = False
+            if self._sp_list is not None:
+                try:
+                    self._sp_list.ensure_properties(["EnableModeration"]).get().execute_query()
+                    self._moderation_on = bool(self._sp_list.properties.get("EnableModeration"))
+                except Exception as e:  # noqa: BLE001 — approval state is best-effort
+                    self.warnings.append(f"moderation setting read failed: {e}")
+        return self._moderation_on
+
+    @property
+    def supports_item_state(self) -> bool:
+        """Whether approval state can be read (needs the parent library)."""
+        return self._list_source is not None
+
+    def read_item_state(self, item: MigrationItem) -> dict | None:
+        """Approval state that a fresh upload would not reproduce.
+
+        A copy arrives approved on a list without moderation and pending on one with it,
+        so a pending source says nothing the copy does not already say; a draft, rejected
+        or scheduled one does, together with its approval comments.
+        """
+        if item.item_type == "folder" or self._list_source is None:
+            return None
+        self._file_authors()
+        state = (self._item_moderation or {}).get(item.source_path)
+        if not state:
+            return None
+        status = state.get(_MODERATION_STATUS)
+        if status is None or status == SPModerationStatusType.Pending.value:
+            return None
+        return state
+
     def close(self) -> None:
         pass
 
@@ -394,30 +2614,170 @@ class SharePointLibraryTarget:
 
     Uses the simple upload for files up to ~4MB; ``write_many`` (parallel,
     ``concurrency > 1``) uses ``create_upload_session`` for larger files.
+
+    Pass ``sp_list`` (the target library) to also replay a folder's column values: a
+    folder is a list item, so a document set's metadata or a managed folder's
+    department is written onto the created folder's item. ``content_type_map``
+    rewrites the folder's content type id to its target counterpart, exactly as it
+    does for an item record.
+
+    Pass ``structure`` (a :class:`~office365.migration.sharepoint.structure.ListStructure`
+    from :func:`~office365.migration.sharepoint.structure.load_list_structure`) to
+    replay a captured shape onto the library before the first file is uploaded — the
+    columns, content types, views and container settings of a bundle travel in its
+    sidecar, not in each file.
     """
 
-    def __init__(self, library_folder: "Folder", concurrency: int = 1) -> None:
+    #: Files carry content-approval state (``apply_item_state``). Documents refuse a
+    #: moderation change combined with other property writes, so it is a write of its
+    #: own, applied after the timestamps that would otherwise re-approve the file.
+    supports_item_state = True
+
+    def rebind(self) -> "SharePointLibraryTarget":
+        """This target on its own cloned context (see :meth:`SharePointListSource.rebind`)."""
+        context = _cloned_context(self._folder)
+        sp_list = _cloned_list(self._sp_list, context) if self._sp_list is not None else None
+        return SharePointLibraryTarget(
+            _cloned_folder(self._folder, context),
+            concurrency=self._concurrency,
+            sp_list=sp_list,
+            content_type_map=self._content_type_map,
+            structure=self._structure,
+        )
+
+    def __init__(
+        self,
+        library_folder: "Folder",
+        concurrency: int = 1,
+        sp_list: "SPList | None" = None,
+        content_type_map: "ContentTypeMap | None" = None,
+        structure: "ListStructure | None" = None,
+    ) -> None:
+        if structure is not None and sp_list is None:
+            raise ValueError("a structure snapshot needs the target list (sp_list) to be applied to")
+        self._structure = structure
+        self._structure_applied = False
         self._folder = library_folder
         self._concurrency = concurrency
-        self._role_definitions: dict[str, RoleDefinition] | None = None
+        # The folder-record mapping is the record mapping: reuse the list target so a
+        # folder's Lookup/Person/taxonomy/choice values resolve the same way.
+        self._sp_list = sp_list
+        self._list_target = (
+            SharePointListTarget(sp_list, content_type_map=content_type_map) if sp_list is not None else None
+        )
+        self._content_type_map = content_type_map
+        self.warnings: list[str] = []
+        self._login_cache: dict[int, str | None] = {}
+        self._principals_cache: _TargetPrincipals | None = None
+        # Author/Editor values resolved by ``apply_authorship`` and folded into the
+        # final timestamp write so ``Editor`` isn't reset by the latter.
+        self._pending_authorship: dict[str, dict] = {}
+        self._field_scan: SharePointListSource | None = None
+
+    def _principals(self) -> _TargetPrincipals:
+        """The (lazily built) target principal/role resolver."""
+        if self._principals_cache is None:
+            self._principals_cache = _TargetPrincipals(self._folder.context.web, self.warnings)
+        return self._principals_cache
+
+    def configure(self, options) -> None:
+        """Replay the captured structure onto the library before the first upload.
+
+        Called by :class:`MigrationRunner` before the run. A bundle carries the
+        library's columns, content types, views and container settings in a sidecar,
+        not in each file, so they have to exist before the files land — a file
+        uploaded into a bare library stores no column values of its own.
+        """
+        self.apply_structure()
+
+    def apply_structure(self) -> list[str]:
+        """Provision the snapshot passed as ``structure`` (once, idempotent)."""
+        if self._structure is None or self._structure_applied or self._sp_list is None:
+            return []
+        self._structure_applied = True
+        entries = self._content_type_map.entries if self._content_type_map is not None else None
+        warnings = provision_list_structure(self._sp_list, self._structure, content_type_map=entries)
+        self.warnings.extend(warnings)
+        return warnings
 
     def label(self) -> str:
         return f"library:{self._folder.server_relative_url}"
 
     def _url(self, item: MigrationItem) -> str:
-        return f"{(self._folder.server_relative_url or '').rstrip('/')}/{item.dest_path}"
+        return f"{(self._folder.server_relative_url or '').rstrip('/')}/{str(item.dest_path).strip('/')}"
 
+    @site_access(SiteLevel.READ)
     def exists(self, item: MigrationItem) -> bool:
+        url = self._url(item)
         try:
-            self._folder.context.web.get_file_by_server_relative_url(self._url(item)).get().execute_query()
+            if item.item_type == "folder":
+                self._folder.context.web.get_folder_by_server_relative_url(url).get().execute_query()
+            else:
+                self._folder.context.web.get_file_by_server_relative_url(url).get().execute_query()
             return True
-        except Exception:  # noqa: BLE001 — a missing file surfaces as a request error
+        except Exception:  # noqa: BLE001 — a missing item surfaces as a request error
             return False
 
+    def _ensure_folders(self, items: list[MigrationItem]) -> None:
+        """Create folder items (deduplicated to deepest paths) in one round-trip."""
+        paths = [str(item.dest_path).strip("/") for item in items]
+        paths = [path for path in paths if path]
+        if not paths:
+            return
+        self._folder.ensure_folders(paths)
+        self._folder.context.execute_query()
+
+    @site_access(SiteLevel.WRITE)
     def write(self, item: MigrationItem, payload: object) -> None:
+        if item.item_type == "folder":
+            self._ensure_folders([item])
+            if isinstance(payload, dict):
+                self._apply_folder_values(item, payload)
+            return
+        if isinstance(payload, dict):
+            # ``str(payload).encode()`` below would write the record's ``repr`` into a file
+            # nobody asked for, and report it as a success: refuse instead.
+            raise ValueError(
+                f"{item.dest_path!r} is a {item.item_type!r} with a dict payload: this target writes files, and a "
+                "list record is not a file body — migrate records into a list"
+            )
         content = payload if isinstance(payload, bytes) else str(payload).encode("utf-8")
         self._folder.upload_file(item.dest_path, content).execute_query()
 
+    @property
+    def supports_folder_records(self) -> bool:
+        """Whether a folder's column values are migrated *and* comparable."""
+        return self._list_target is not None
+
+    def _apply_folder_values(self, item: MigrationItem, record: dict) -> None:
+        """Write a folder's column values onto the folder's underlying list item."""
+        assert self._list_target is not None
+        values = _folder_record_values(record)
+        if not values:
+            return
+        values = self._list_target.translate_record(values)
+        folder_item = self._securable(item)
+        for key, value in values.items():
+            folder_item.set_property(key, value)
+        try:
+            folder_item.update().execute_query()
+        except Exception as e:  # noqa: BLE001 — a folder's structure is worth more than its values
+            self.warnings.append(f"folder column values for {item.dest_path!r} could not be written: {e}")
+
+    def _folder_projection(self) -> list[str]:
+        """The target's folder columns (read once) — the set the source projected."""
+        if self._sp_list is None:
+            return []
+        if self._field_scan is None:
+            # Field definitions are read by the same code on both sides: structure
+            # provisioning keeps the internal names, so the projections line up.
+            self._field_scan = SharePointListSource(self._sp_list)
+        try:
+            return self._field_scan.folder_projection()
+        except Exception as e:  # noqa: BLE001 — without a projection no folder values move
+            self.warnings.append(f"could not read the target columns for folder values: {e}")
+            return []
+
     def write_many(
         self,
         items: list[MigrationItem],
@@ -431,90 +2791,270 @@ class SharePointLibraryTarget:
         """
         from office365.migration.sharepoint.transfer import _transfer_files_parallel
 
+        failures: list[Failure] = []
+        folders = [item for item in items if item.item_type == "folder"]
+        if folders:
+            try:
+                self._ensure_folders(folders)
+            except Exception:  # noqa: BLE001 — fall back to per-folder to attribute errors
+                for folder in folders:
+                    try:
+                        self._ensure_folders([folder])
+                    except Exception as e:  # noqa: BLE001
+                        failures.append((folder.dest_path, str(e)))
+        # A folder's column values can only be written once its item exists, so they
+        # follow the (batched) folder creation.
+        for item, payload in zip(items, payloads):
+            if item.item_type == "folder" and isinstance(payload, dict):
+                self._apply_folder_values(item, payload)
         files = [
             (item.dest_path, payload if isinstance(payload, bytes) else str(payload).encode("utf-8"))
             for item, payload in zip(items, payloads)
+            if item.item_type != "folder"
         ]
-        return _transfer_files_parallel(
-            self._folder,
-            files,
-            concurrency=concurrency or self._concurrency or 1,
-        )
+        if files:
+            failures.extend(
+                _transfer_files_parallel(
+                    self._folder,
+                    files,
+                    concurrency=concurrency or self._concurrency or 1,
+                )
+            )
+        return failures
 
+    @site_access(SiteLevel.READ)
     def list_paths(self) -> list[str]:
         root = (self._folder.server_relative_url or "").rstrip("/")
-        loaded = self._folder.get_files(recursive=True).execute_query()
-        return [(f.server_relative_url or "")[len(root) :].lstrip("/") for f in loaded]
-
-    def checksum(self, item: MigrationItem) -> str:
+        extra = _site_assets_scaffolding(self._folder)
+        loaded_files = self._folder.get_files(recursive=True).execute_query()
+        loaded_folders = self._folder.get_folders(recursive=True).execute_query()
+        paths = [(f.server_relative_url or "")[len(root) :].lstrip("/") for f in loaded_files]
+        paths += [f"{(f.server_relative_url or '')[len(root) :].lstrip('/')}/" for f in loaded_folders]
+        # Mirror the source projection: SharePoint-owned scaffolding (``Forms/``,
+        # ``desktop.ini``, and on SiteAssets the site icon + auto-provisioned
+        # notebook) is recreated server-side, never migrated, so it must not be
+        # reported as target-only content during verification. Source folder paths
+        # carry a trailing slash; target folder paths mirror that.
+        return [p for p in paths if p != "/" and not self._folder.is_system_path(p, extra)]
+
+    @site_access(SiteLevel.READ)
+    def read(self, item: MigrationItem) -> bytes:
+        """Download the written item's bytes (used by verification for Office files)."""
+        if item.item_type == "folder":
+            return b""
         file = self._folder.context.web.get_file_by_server_relative_url(self._url(item)).get().execute_query()
         buffer = io.BytesIO()
         file.download(buffer).execute_query()
-        return hashlib.md5(buffer.getvalue()).hexdigest()
+        return buffer.getvalue()
 
+    def checksum(self, item: MigrationItem) -> str:
+        if item.item_type == "folder":
+            values = self._target_folder_values(item)
+            if values is None or self._list_target is None:
+                return ""
+            return self._list_target.content_checksum(values)
+        return checksum(self.read(item))
+
+    def _target_folder_values(self, item: MigrationItem) -> dict | None:
+        """The target folder's column values as they read back (``None`` if unknown)."""
+        columns = self._folder_projection()
+        if not columns:
+            return None
+        list_item = self._securable(item).select(columns).get().execute_query()
+        return _folder_record_values(dict(list_item.properties))
+
+    @site_access(SiteLevel.READ)
     def modified(self, item: MigrationItem) -> str:
         """Last-modified of the target file (for incremental migration)."""
+        if item.item_type == "folder":
+            return ""
         file = self._folder.context.web.get_file_by_server_relative_url(self._url(item)).get().execute_query()
         return iso_or_none(file.time_last_modified) or ""
 
+    @site_access(SiteLevel.WRITE)
     def apply_timestamps(self, item: MigrationItem) -> None:
         """Best-effort: restore ``Created``/``Modified`` on the written item.
 
-        Uses ``ValidateUpdateListItem`` (the same mechanism as
-        ``ListItem.system_update``), which is the only REST path that can set these
-        system fields. ``preserve_versions`` still needs the server-side API.
+        ``ValidateUpdateListItem`` is the only REST path that can set these system
+        fields. For files it runs as a system update (``bNewDocumentUpdate=True``, the
+        CSOM ``UpdateOverwriteVersion`` path) so the metadata lands without creating a
+        new version; folders have no version history. ``preserve_versions`` still needs
+        the server-side API. Authorship values resolved for the same item ride along in
+        this write.
+        """
+        self._restore_fidelity(item, timestamps=True)
+
+    def _restore_fidelity(self, item: MigrationItem, timestamps: bool) -> None:
+        """One system update carrying every fidelity value this item has.
+
+        A document's item form reads its dates in the web's locale rather than the UTC
+        a caller holds, so the timestamps are converted first (see
+        :func:`_web_local_texts`); the approval state is a write of its own and stays
+        last — see :meth:`apply_item_state`.
         """
-        form_values: dict[str, str] = {}
-        created = _sp_timestamp(item.created)
-        modified = _sp_timestamp(item.modified)
-        if created:
-            form_values["Created"] = created
-        if modified:
-            form_values["Modified"] = modified
-        if not form_values:
-            return
         securable = self._securable(item)
         if securable is None:
             return
-        securable.validate_update_list_item(
-            form_values,
-            dates_in_utc=True,
+        created = modified = None
+        if timestamps:
+            created, modified = _web_local_texts(self._folder.context.web, item.created, item.modified)
+        authorship = self._pending_authorship.pop(item.dest_path, {})
+        if not (created or modified or authorship):
+            return
+        result = securable.restore_fidelity(
+            created=created,
+            modified=modified,
+            author=authorship.get("Author"),
+            editor=authorship.get("Editor"),
             new_document_update=item.item_type != "folder",
+            web_local_dates=True,
         ).execute_query()
+        _report_rejected_fields(result, self.warnings, f"timestamps {item.dest_path}")
+
+    def apply_authorship(self, item: MigrationItem) -> None:
+        """Best-effort: resolve ``Author``/``Editor`` and cache them for one write.
+
+        A principal is applied only when its login name resolves to a target user
+        (``EnsureUser``); unresolved principals are skipped (same-tenant only).
+
+        Nothing is sent here: a separate write per item doubled the cost of a
+        preserved run, and a system update re-approves a document, so the cached
+        values are better folded into the timestamps write (or in
+        :meth:`finalize_fidelity` when timestamps are not preserved).
+        """
+        securable = self._securable(item)
+        if securable is None:
+            return
+        author = self._principals().user(item.author.login_name if item.author else None)
+        editor = self._principals().user(item.editor.login_name if item.editor else None)
+        if author is not None and author.is_service_account:
+            author = None
+        if editor is not None and editor.is_service_account:
+            editor = None
+        if author is None and editor is None:
+            return
+        self._pending_authorship[item.dest_path] = {"Author": author, "Editor": editor}
+
+    @site_access(SiteLevel.WRITE)
+    def finalize_fidelity(self, item: MigrationItem) -> None:
+        """Write the fidelity values that were only cached for this item.
 
+        The last hook wins the write: with timestamps preserved that is
+        :meth:`apply_timestamps`; without them it is this method, so an item costs
+        one system update instead of one per property group. Runs before the
+        approval write, which must stay last.
+        """
+        self._restore_fidelity(item, timestamps=False)
+
+    @site_access(SiteLevel.MANAGE)
     def apply_permissions(self, item: MigrationItem, permissions: list[PermissionEntry]) -> None:
-        """Best-effort: break inheritance and recreate the source role assignments.
+        """Best-effort: replay a file's or folder's unique ACLs onto the target item.
 
-        Principals are resolved by login name on the target; roles that don't exist
-        there are skipped. This is a same-tenant copy — cross-tenant identity
-        mapping is out of scope.
+        Same-tenant only — cross-tenant identity mapping is out of scope. See
+        :func:`_replay_role_assignments` for what happens to principals, roles and
+        inheritance that cannot be resolved.
         """
         securable = self._securable(item)
         if securable is None:
             return
-        securable.break_role_inheritance(copy_role_assignments=False, clear_sub_scopes=False)
-        for entry in permissions:
-            for role_name in entry.roles:
-                role = self._role_definition(role_name)
-                if role is not None:
-                    securable.add_role_assignment(entry.principal_name, role)
+        _replay_role_assignments(securable, self._principals(), permissions, self.warnings, item.dest_path)
         securable.context.execute_query()
 
+    @site_access(SiteLevel.WRITE)
+    def apply_item_state(self, item: MigrationItem, state: dict) -> None:
+        """Best-effort: restore a migrated file's content-approval state.
+
+        A fresh document is pending on a moderated library and approved on one without
+        it, so a draft or rejected source file would otherwise silently become visible.
+        Documents reject a moderation change combined with other properties (``You
+        cannot change moderation status and set other item properties at that same
+        time.``), which is why a list item carries its state in its other system update
+        and a file needs this write of its own, applied last. A library without
+        moderation enabled has no such fields: the write fails and is reported, never
+        fatal.
+        """
+        if item.item_type == "folder" or not state:
+            return
+        securable = self._securable(item)
+        if securable is None:
+            return
+        try:
+            result = securable.restore_fidelity(approval=dict(state), new_document_update=True).execute_query()
+        except Exception as e:  # noqa: BLE001 — approval state is best-effort
+            self.warnings.append(f"approval state for {item.dest_path!r} could not be restored: {e}")
+            return
+        _report_rejected_fields(result, self.warnings, f"approval state {item.dest_path}")
+
+    @site_access(SiteLevel.READ)
+    def read_metadata(self, item: MigrationItem) -> dict | None:
+        """Comparable attributes of the written item (for the metadata diff)."""
+        if item.item_type == "folder":
+            # A folder is an item too: the timestamp system update lands on its list
+            # item, and the folder resource reflects it (same read as for a file).
+            folder = (
+                self._folder.context.web.get_folder_by_server_relative_path(self._url(item).rstrip("/"))
+                .get()
+                .execute_query()
+            )
+            return {
+                "created": iso_or_none(folder.time_created),
+                "modified": iso_or_none(folder.time_last_modified),
+            }
+        file = self._folder.context.web.get_file_by_server_relative_url(self._url(item)).get().execute_query()
+        metadata = {
+            "created": iso_or_none(file.time_created),
+            "modified": iso_or_none(file.time_last_modified),
+            "size_bytes": file.length or 0,
+        }
+        status = self._target_moderation_status(item)
+        if status is not None:
+            metadata["moderation_status"] = status
+        return metadata
+
+    def _target_moderation_status(self, item: MigrationItem) -> str | None:
+        """The written file's approval status, or ``None`` when not readable."""
+        securable = self._securable(item)
+        if securable is None:
+            return None
+        try:
+            securable.select([_MODERATION_STATUS]).get().execute_query()
+        except Exception:  # noqa: BLE001 — a library without moderation has no such column
+            return None
+        status = securable.moderation_status
+        return None if status is None else str(status.value)
+
+    def read_permissions(self, item: MigrationItem) -> list[PermissionEntry]:
+        """Read the written item's *unique* role assignments (for the permission diff)."""
+        securable = self._securable(item)
+        if securable is None or not _has_unique_role_assignments(securable, refresh=True):
+            return []
+        return _read_role_assignments(securable, normalize=self._principals().normalize)
+
+    def _fresh_securable(self, item: MigrationItem):
+        """Re-read the written item so its properties reflect what was applied."""
+        securable = self._securable(item)
+        if securable is not None:
+            securable.get().execute_query()
+        return securable
+
+    def read_authorship(self, item: MigrationItem) -> tuple[str | None, str | None]:
+        """The written item's author/editor login names (for the authorship diff)."""
+        securable = self._fresh_securable(item)
+        if securable is None:
+            return (None, None)
+        return (
+            _user_login(self._folder.context.web, securable.author_id, self._login_cache),
+            _user_login(self._folder.context.web, securable.editor_id, self._login_cache),
+        )
+
     def _securable(self, item: MigrationItem):
         url = self._url(item).rstrip("/")
         if item.item_type == "folder":
             return self._folder.context.web.get_folder_by_server_relative_path(url).list_item_all_fields
         return self._folder.context.web.get_file_by_server_relative_url(url).listItemAllFields
 
-    def _role_definition(self, name: str) -> "RoleDefinition | None":
-        """Resolve (and cache) a target role definition by name."""
-        if self._role_definitions is None:
-            loaded = self._folder.context.web.role_definitions.get().execute_query()
-            self._role_definitions = {rd.name: rd for rd in loaded if rd.name}
-        return self._role_definitions.get(name)
-
     def commit(self, options=None) -> None:
-        pass
+        self._pending_authorship.clear()
 
     def close(self) -> None:
         pass