@@ -0,0 +1,61 @@
+"""Load existing OSW User items so the sync can update in place.
+
+Matches are keyed on the ``username`` field, so accounts already stored under a
+different uuid are updated rather than duplicated.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from .config import USER_CATEGORY
+
+
+@dataclass
+class ExistingUsers:
+    """Existing User items indexed by their MediaWiki username."""
+
+    by_username: Dict[str, Any] = field(default_factory=dict)
+
+    def get(self, username: str) -> Optional[Any]:
+        return self.by_username.get(username)
+
+
+def _as_entity_list(result: Any) -> List[Any]:
+    """Normalize load_entity output (single, list, or LoadEntityResult)."""
+    if result is None:
+        return []
+    entities = getattr(result, "entities", None)
+    if entities is not None:
+        return list(entities)
+    if isinstance(result, list):
+        return result
+    return [result]
+
+
+def load_existing_users(
+    osw: Any,
+    category: str = USER_CATEGORY,
+    limit: Optional[int] = None,
+) -> ExistingUsers:
+    """Query and load all existing User items, indexed by username.
+
+    Args:
+        osw: An authenticated OSW connection exposing ``query_instances`` and
+            ``load_entity``.
+        category: The User category page title.
+        limit: Load at most this many items (for testing).
+    """
+    titles = osw.query_instances(category=category)
+    if limit is not None:
+        titles = titles[:limit]
+    if not titles:
+        return ExistingUsers()
+    entities = _as_entity_list(osw.load_entity(titles))
+    by_username: Dict[str, Any] = {}
+    for entity in entities:
+        username = getattr(entity, "username", None)
+        if username:
+            by_username[username] = entity
+    return ExistingUsers(by_username=by_username)
@@ -0,0 +1,146 @@
+"""Map MediaWiki accounts and ORCID profiles to proposed OSW items.
+
+These functions are pure: they compute the field values and deterministic ids of
+the items to store, without instantiating the pydantic models (which requires an
+open OSW connection) or touching the network. The store step builds the actual
+``User`` / ``Organization`` entities from these proposals.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+from osw.data.import_utility import uuid_to_full_page_title
+
+from .config import ORGANIZATION_CATEGORY, USER_CATEGORY
+from .sources import MwUser, OrcidAffiliation, OrcidProfile
+
+
+def _category_namespace(category: str) -> uuid.UUID:
+    """Derive the uuid5 namespace of a category from its page title."""
+    return uuid.UUID(category.split("OSW")[-1])
+
+
+USER_NAMESPACE = _category_namespace(USER_CATEGORY)
+ORGANIZATION_NAMESPACE = _category_namespace(ORGANIZATION_CATEGORY)
+
+
+@dataclass
+class ProposedOrganization:
+    """An Organization item derived from an ORCID affiliation."""
+
+    uuid: uuid.UUID
+    name: str
+    ror_id: Optional[str] = None
+
+    @property
+    def full_page_title(self) -> str:
+        return uuid_to_full_page_title(self.uuid)
+
+
+@dataclass
+class ProposedUser:
+    """A User item derived from a MediaWiki account and optional ORCID data."""
+
+    uuid: uuid.UUID
+    username: str
+    first_name: str
+    surname: str
+    label: str
+    orcid: Optional[str] = None
+    emails: List[str] = field(default_factory=list)
+    websites: List[str] = field(default_factory=list)
+    organizations: List[str] = field(default_factory=list)
+    placeholder_name: bool = False
+
+    @property
+    def full_page_title(self) -> str:
+        return uuid_to_full_page_title(self.uuid)
+
+
+def normalize_org_name(name: str) -> str:
+    """Collapse whitespace and lowercase, for a stable org identity key."""
+    return " ".join(name.lower().split())
+
+
+def user_uuid(mw_user: MwUser) -> uuid.UUID:
+    """Deterministic uuid5: keyed on ORCID iD for ORCID users, else username."""
+    key = mw_user.orcid_id or mw_user.name
+    return uuid.uuid5(USER_NAMESPACE, key)
+
+
+def organization_uuid(affiliation: OrcidAffiliation) -> uuid.UUID:
+    """Deterministic uuid5: keyed on ROR id when present, else the org name."""
+    key = affiliation.ror_id or normalize_org_name(affiliation.organization)
+    return uuid.uuid5(ORGANIZATION_NAMESPACE, key)
+
+
+def map_organization(affiliation: OrcidAffiliation) -> ProposedOrganization:
+    return ProposedOrganization(
+        uuid=organization_uuid(affiliation),
+        name=affiliation.organization,
+        ror_id=affiliation.ror_id,
+    )
+
+
+def _derive_names(
+    profile: Optional[OrcidProfile], username: str
+) -> Tuple[str, str, str, bool]:
+    """Return (first_name, surname, label, is_placeholder).
+
+    Prefers ORCID given/family names, then a split of the display name, then a
+    username-based placeholder when no name information is available.
+    """
+    given = profile.given_names if profile else None
+    family = profile.family_name if profile else None
+    display = profile.display_name if profile else None
+    if given and family:
+        return given, family, display or f"{given} {family}", False
+    if display:
+        parts = display.split()
+        first = given or parts[0]
+        surname = family or (parts[-1] if len(parts) > 1 else parts[0])
+        return first, surname, display, False
+    if given or family:
+        first = given or family
+        surname = family or given
+        return first, surname, f"{first} {surname}", False
+    return username, username, username, True
+
+
+def map_user(
+    mw_user: MwUser,
+    profile: Optional[OrcidProfile] = None,
+    link_organizations: bool = True,
+) -> Tuple[ProposedUser, List[ProposedOrganization]]:
+    """Build a ProposedUser (and any linked organizations) from the sources."""
+    orcid_uri = f"https://orcid.org/{mw_user.orcid_id}" if mw_user.orcid_id else None
+    first, surname, label, placeholder = _derive_names(profile, mw_user.name)
+
+    organizations: List[ProposedOrganization] = []
+    org_titles: List[str] = []
+    if link_organizations and profile:
+        seen = set()
+        for affiliation in profile.affiliations:
+            org = map_organization(affiliation)
+            if org.uuid in seen:
+                continue
+            seen.add(org.uuid)
+            organizations.append(org)
+            org_titles.append(org.full_page_title)
+
+    proposed = ProposedUser(
+        uuid=user_uuid(mw_user),
+        username=mw_user.name,
+        first_name=first,
+        surname=surname,
+        label=label,
+        orcid=orcid_uri,
+        emails=list(profile.emails) if profile else [],
+        websites=list(profile.urls) if profile else [],
+        organizations=org_titles,
+        placeholder_name=placeholder,
+    )
+    return proposed, organizations
@@ -0,0 +1,59 @@
+"""Unit tests for loading and indexing existing User items."""
+
+from types import SimpleNamespace
+
+from osw.tools.user_sync.existing import load_existing_users
+
+
+class FakeOsw:
+    def __init__(self, titles, entities):
+        self._titles = titles
+        self._entities = entities
+        self.loaded = None
+
+    def query_instances(self, category):
+        assert category.startswith("Category:OSW")
+        return list(self._titles)
+
+    def load_entity(self, titles):
+        self.loaded = list(titles)
+        return [self._entities[t] for t in titles]
+
+
+def test_load_indexes_by_username():
+    entities = {
+        "Item:OSW1": SimpleNamespace(username="0000-0002-6374-9831"),
+        "Item:OSW2": SimpleNamespace(username="Alice"),
+    }
+    osw = FakeOsw(["Item:OSW1", "Item:OSW2"], entities)
+    existing = load_existing_users(osw)
+    assert set(existing.by_username) == {"0000-0002-6374-9831", "Alice"}
+    assert existing.get("Alice") is entities["Item:OSW2"]
+    assert existing.get("missing") is None
+
+
+def test_load_empty():
+    osw = FakeOsw([], {})
+    existing = load_existing_users(osw)
+    assert existing.by_username == {}
+
+
+def test_load_skips_entities_without_username():
+    entities = {
+        "Item:OSW1": SimpleNamespace(username=None),
+        "Item:OSW2": SimpleNamespace(username="Bob"),
+    }
+    osw = FakeOsw(["Item:OSW1", "Item:OSW2"], entities)
+    existing = load_existing_users(osw)
+    assert set(existing.by_username) == {"Bob"}
+
+
+def test_load_respects_limit():
+    entities = {
+        "Item:OSW1": SimpleNamespace(username="A"),
+        "Item:OSW2": SimpleNamespace(username="B"),
+    }
+    osw = FakeOsw(["Item:OSW1", "Item:OSW2"], entities)
+    existing = load_existing_users(osw, limit=1)
+    assert osw.loaded == ["Item:OSW1"]
+    assert set(existing.by_username) == {"A"}
@@ -0,0 +1,112 @@
+"""Unit tests for mapping sources to proposed User/Organization items."""
+
+import uuid
+
+from osw.tools.user_sync import mapping
+from osw.tools.user_sync.mapping import (
+    ProposedUser,
+    map_organization,
+    map_user,
+    normalize_org_name,
+    organization_uuid,
+    user_uuid,
+)
+from osw.tools.user_sync.sources import MwUser, OrcidAffiliation, OrcidProfile
+
+ORCID = "0000-0002-6374-9831"
+
+
+def _profile(**kw):
+    base = dict(orcid_id=ORCID, given_names="Lukas", family_name="Koschmieder")
+    base.update(kw)
+    return OrcidProfile(**base)
+
+
+def test_map_orcid_user_full_profile():
+    mw = MwUser(name=ORCID)
+    profile = _profile(
+        emails=["l@example.org"],
+        urls=["https://example.org"],
+        affiliations=[OrcidAffiliation(organization="Example University")],
+    )
+    proposed, orgs = map_user(mw, profile)
+    assert isinstance(proposed, ProposedUser)
+    assert proposed.username == ORCID
+    assert proposed.orcid == f"https://orcid.org/{ORCID}"
+    assert proposed.first_name == "Lukas"
+    assert proposed.surname == "Koschmieder"
+    assert proposed.label == "Lukas Koschmieder"
+    assert proposed.emails == ["l@example.org"]
+    assert proposed.websites == ["https://example.org"]
+    assert proposed.placeholder_name is False
+    assert len(orgs) == 1
+    assert proposed.organizations == [orgs[0].full_page_title]
+    assert proposed.full_page_title.startswith("Item:OSW")
+
+
+def test_map_orcid_user_without_profile_uses_placeholder_names():
+    mw = MwUser(name=ORCID)
+    proposed, orgs = map_user(mw, None)
+    assert proposed.orcid == f"https://orcid.org/{ORCID}"
+    assert proposed.first_name == ORCID
+    assert proposed.surname == ORCID
+    assert proposed.placeholder_name is True
+    assert orgs == []
+
+
+def test_map_non_orcid_user():
+    mw = MwUser(name="Alice")
+    proposed, _orgs = map_user(mw, None)
+    assert proposed.orcid is None
+    assert proposed.placeholder_name is True
+    assert proposed.uuid == uuid.uuid5(mapping.USER_NAMESPACE, "Alice")
+
+
+def test_user_uuid_is_deterministic_and_orcid_keyed():
+    mw = MwUser(name=ORCID)
+    expected = uuid.uuid5(mapping.USER_NAMESPACE, ORCID)
+    assert user_uuid(mw) == expected
+    assert user_uuid(mw) == user_uuid(MwUser(name=ORCID))
+
+
+def test_credit_name_split_when_no_given_family():
+    mw = MwUser(name=ORCID)
+    profile = OrcidProfile(
+        orcid_id=ORCID, given_names=None, family_name=None, credit_name="Jane A. Doe"
+    )
+    proposed, _ = map_user(mw, profile)
+    assert proposed.first_name == "Jane"
+    assert proposed.surname == "Doe"
+    assert proposed.label == "Jane A. Doe"
+    assert proposed.placeholder_name is False
+
+
+def test_organization_uuid_prefers_ror_over_name():
+    ror = OrcidAffiliation(organization="Example U", ror_id="https://ror.org/01")
+    named = OrcidAffiliation(organization="Example U")
+    assert organization_uuid(ror) != organization_uuid(named)
+    assert organization_uuid(named) == uuid.uuid5(
+        mapping.ORGANIZATION_NAMESPACE, normalize_org_name("Example U")
+    )
+    assert map_organization(ror).ror_id == "https://ror.org/01"
+
+
+def test_duplicate_affiliations_deduped():
+    mw = MwUser(name=ORCID)
+    profile = _profile(
+        affiliations=[
+            OrcidAffiliation(organization="Example University"),
+            OrcidAffiliation(organization="example   university"),
+        ]
+    )
+    proposed, orgs = map_user(mw, profile)
+    assert len(orgs) == 1
+    assert len(proposed.organizations) == 1
+
+
+def test_link_organizations_disabled():
+    mw = MwUser(name=ORCID)
+    profile = _profile(affiliations=[OrcidAffiliation(organization="Example U")])
+    proposed, orgs = map_user(mw, profile, link_organizations=False)
+    assert orgs == []
+    assert proposed.organizations == []