arkparser 0.8.0__tar.gz → 0.9.0__tar.gz

{arkparser-0.8.0 → arkparser-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparser
-Version: 0.8.0
+Version: 0.9.0
 Summary: Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files
 Author: Vertyco
 License-Expression: MIT
@@ -133,6 +133,27 @@ print(f"Parse errors: {save.parse_error_count}")
 print(f"Is ASA: {save.is_asa}")
 ```
 
+### Player/tribe data packed in the save (ASA)
+
+Some ASA servers (Nitrado observed) write no `.arkprofile` / `.arktribe` files.
+The same files are packed inside the `.ark` instead. Read them and attach them
+the same way you would attach sidecar files:
+
+```python
+from arkparser import WorldSave, export_all
+
+save = WorldSave.load("path/to/Ragnarok_WP.ark", lazy_properties=True)
+store = save.read_embedded_store()
+save.profiles, save.tribes = store.profiles, store.tribes
+data = export_all(save)
+```
+
+`EmbeddedStore` holds `profiles`, `tribes`, `superseded_profiles` /
+`superseded_tribes` (old copies the game leaves behind, skipped), and
+`errors` (one line per skipped entry; a bad entry never fails the load). Saves
+from servers that write sidecar files return an empty store. Not run by
+`load()`, so it costs nothing unless called.
+
 ### Low-memory parsing (large saves)
 
 By default every object's property block is parsed up front, which on a busy
@@ -577,6 +598,7 @@ Key methods:
 | `get_object_by_guid(guid)` | `GameObject \| None` | Lookup by GUID (ASA) |
 | `get_actor_location(guid)` | `LocationData \| None` | Actor location by GUID (ASA) |
 | `iter_cryopod_creatures()` | `Iterator[(GameObject, CryopodCreature)]` | Walk filled cryopods |
+| `read_embedded_store()` | `EmbeddedStore` | Player and tribe files packed inside an ASA save (servers that write no `.arkprofile` / `.arktribe`); see "Player/tribe data packed in the save" |
 
 ### Game Objects
 

{arkparser-0.8.0 → arkparser-0.9.0}/README.md

@@ -99,6 +99,27 @@ print(f"Parse errors: {save.parse_error_count}")
 print(f"Is ASA: {save.is_asa}")
 ```
 
+### Player/tribe data packed in the save (ASA)
+
+Some ASA servers (Nitrado observed) write no `.arkprofile` / `.arktribe` files.
+The same files are packed inside the `.ark` instead. Read them and attach them
+the same way you would attach sidecar files:
+
+```python
+from arkparser import WorldSave, export_all
+
+save = WorldSave.load("path/to/Ragnarok_WP.ark", lazy_properties=True)
+store = save.read_embedded_store()
+save.profiles, save.tribes = store.profiles, store.tribes
+data = export_all(save)
+```
+
+`EmbeddedStore` holds `profiles`, `tribes`, `superseded_profiles` /
+`superseded_tribes` (old copies the game leaves behind, skipped), and
+`errors` (one line per skipped entry; a bad entry never fails the load). Saves
+from servers that write sidecar files return an empty store. Not run by
+`load()`, so it costs nothing unless called.
+
 ### Low-memory parsing (large saves)
 
 By default every object's property block is parsed up front, which on a busy
@@ -543,6 +564,7 @@ Key methods:
 | `get_object_by_guid(guid)` | `GameObject \| None` | Lookup by GUID (ASA) |
 | `get_actor_location(guid)` | `LocationData \| None` | Actor location by GUID (ASA) |
 | `iter_cryopod_creatures()` | `Iterator[(GameObject, CryopodCreature)]` | Walk filled cryopods |
+| `read_embedded_store()` | `EmbeddedStore` | Player and tribe files packed inside an ASA save (servers that write no `.arkprofile` / `.arktribe`); see "Player/tribe data packed in the save" |
 
 ### Game Objects
 

{arkparser-0.8.0 → arkparser-0.9.0}/arkparser/__init__.py

@@ -48,7 +48,7 @@ from arkparser.export import (
     export_tribes,
     export_wild,
 )
-from arkparser.files import CloudInventory, Profile, Tribe, WorldSave
+from arkparser.files import CloudInventory, EmbeddedStore, Profile, Tribe, WorldSave
 from arkparser.game_objects import GameObject, GameObjectContainer, LocationData
 
 # Convenience alias - users may know this as "Obelisk" from the game
@@ -61,6 +61,7 @@ __all__ = [
     "CloudInventory",
     "Obelisk",
     "WorldSave",
+    "EmbeddedStore",
     # Cloud-inventory data models
     "UploadedCreature",
     "UploadedItem",
@@ -95,4 +96,4 @@ __all__ = [
     "ArkParseError",
 ]
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"

{arkparser-0.8.0 → arkparser-0.9.0}/arkparser/files/__init__.py

@@ -12,6 +12,7 @@ All parsers support both ASE and ASA formats with automatic detection.
 
 from .base import ArkFile
 from .cloud_inventory import CloudInventory
+from .embedded_store import EmbeddedStore
 from .profile import Profile
 from .tribe import Tribe
 from .world_save import WorldSave
@@ -22,4 +23,5 @@ __all__ = [
     "Tribe",
     "CloudInventory",
     "WorldSave",
+    "EmbeddedStore",
 ]

arkparser-0.9.0/arkparser/files/embedded_store.py

@@ -0,0 +1,261 @@
+"""
+Player and tribe store packed inside an ASA world save.
+
+Some ASA servers (Nitrado observed) never write ``.arkprofile`` / ``.arktribe``
+files. The same files are packed into the save's ``custom`` table under the
+``GameModeCustomBytes`` key instead. Servers that do write the files leave that
+row at a few dozen bytes.
+
+Blob layout (int32 little-endian)::
+
+    Int32  format                     # 1
+    repeat (tribes, then profiles):
+      Int32  section_size             # bytes of packed files that follow
+      Int32  count                    # size 0 + count 0 = terminator, ends the blob
+      Bytes  files[section_size]      # complete .arktribe / .arkprofile files
+      count x { Bytes(8) key, Int32 offset, Int32 size }
+
+The store is append-style: each save writes a fresh copy of a changed tribe or
+profile and zeroes the old copy's key. Only entries with a non-zero key are
+current. Each packed file is byte-identical in format to a sidecar file, so it
+loads with ``Tribe.load(bytes)`` / ``Profile.load(bytes)`` unchanged.
+
+Pieces are read with ``substr()`` slices so a large store never sits in memory
+whole: the index first, then one current file at a time.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import struct
+import typing as t
+from dataclasses import dataclass, field
+
+from ..common.exceptions import CorruptDataError
+from ..game_objects.game_object import MAX_OBJECT_COUNT
+from .profile import Profile
+from .tribe import Tribe
+
+logger = logging.getLogger(__name__)
+
+STORE_KEY = "GameModeCustomBytes"
+STORE_FORMAT = 1
+NO_STORE_FORMAT = 0
+# Tribes + profiles + one spare for a future section type.
+MAX_SECTIONS = 3
+INDEX_ENTRY = struct.Struct("<8sii")
+ZERO_KEY = b"\x00" * 8
+# Where the class-name string sits in a v7 packed file: version, two header
+# ints, object count, then the first object's 16-byte GUID.
+CLASS_NAME_OFFSET = 32
+MAX_CLASS_NAME = 256
+
+_SIZE_SQL = "SELECT length(value) FROM custom WHERE key = ?"
+_SLICE_SQL = "SELECT substr(value, ?, ?) FROM custom WHERE key = ?"
+
+
+@dataclass
+class EmbeddedStore:
+    """Current profiles and tribes read out of a save's packed store.
+
+    Attributes:
+        profiles: One ``Profile`` per player (latest copy).
+        tribes: One ``Tribe`` per tribe (latest copy).
+        superseded_profiles: Old profile copies skipped (zero key).
+        superseded_tribes: Old tribe copies skipped (zero key).
+        errors: Problems found, one line each. A bad entry is skipped and the
+            rest still load; a bad layout empties the result.
+    """
+
+    profiles: list[Profile] = field(default_factory=list)
+    tribes: list[Tribe] = field(default_factory=list)
+    superseded_profiles: int = 0
+    superseded_tribes: int = 0
+    errors: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class StoreSection:
+    """One section's location in the blob plus its raw index entries."""
+
+    data_start: int
+    data_size: int
+    entries: list[tuple[bytes, int, int]]
+
+
+class BlobSlicer:
+    """Reads byte ranges of the store row without loading the whole value."""
+
+    def __init__(self, conn: sqlite3.Connection, size: int) -> None:
+        assert size >= 0, "negative blob size"
+        self.conn = conn
+        self.size = size
+
+    def read(self, offset: int, length: int) -> bytes:
+        """Return ``length`` bytes at 0-based ``offset``, or raise if out of range."""
+        if offset < 0 or length < 0 or offset + length > self.size:
+            raise CorruptDataError(
+                f"store read {offset}+{length} past blob end {self.size}"
+            )
+        if length == 0:
+            return b""
+        row = self.conn.execute(_SLICE_SQL, (offset + 1, length, STORE_KEY)).fetchone()
+        data = bytes(row[0]) if row is not None and row[0] is not None else b""
+        if len(data) != length:
+            raise CorruptDataError(f"store read {offset}+{length} returned {len(data)} bytes")
+        return data
+
+    def read_int32_pair(self, offset: int) -> tuple[int, int]:
+        """Read two little-endian int32 values at ``offset``."""
+        first, second = struct.unpack("<2i", self.read(offset, 8))
+        return first, second
+
+
+def load_embedded_store(conn: sqlite3.Connection) -> EmbeddedStore:
+    """Read the packed profile/tribe store from an open ASA save connection.
+
+    Pre: ``conn`` is an open connection to an ASA save (has a ``custom``
+    table). Post: returns the current entries; an absent or near-empty store
+    returns an empty result with no errors, and a malformed layout returns an
+    empty result with one error line. Never raises for bad store data.
+    """
+    assert conn is not None, "connection required"
+    row = conn.execute(_SIZE_SQL, (STORE_KEY,)).fetchone()
+    size = int(row[0]) if row is not None and row[0] is not None else 0
+    store = EmbeddedStore()
+    if size <= 8:
+        return store
+    slicer = BlobSlicer(conn, size)
+    # Servers that write sidecar files leave this row all zeros (20-28 bytes
+    # observed), so format 0 means "no store", not a malformed one.
+    if struct.unpack("<i", slicer.read(0, 4))[0] == NO_STORE_FORMAT:
+        return store
+    try:
+        sections = read_sections(slicer)
+    except CorruptDataError as exc:
+        store.errors.append(f"store layout: {exc}")
+        return store
+    for number, section in enumerate(sections):
+        load_section(slicer, section, number, store)
+    assert len(store.profiles) + len(store.tribes) <= MAX_OBJECT_COUNT, "store overflow"
+    return store
+
+
+def read_sections(slicer: BlobSlicer) -> list[StoreSection]:
+    """Walk the blob's section headers and index tables.
+
+    Pre: blob is longer than 8 bytes. Post: returns every section up to the
+    terminator, with bounds checked; raises ``CorruptDataError`` on any
+    impossible count, size, or a missing terminator.
+    """
+    assert slicer.size > 8, "store too small to hold a section"
+    fmt = struct.unpack("<i", slicer.read(0, 4))[0]
+    if fmt != STORE_FORMAT:
+        raise CorruptDataError(f"unknown store format {fmt}")
+    sections: list[StoreSection] = []
+    pos = 4
+    for _ in range(MAX_SECTIONS + 1):
+        data_size, count = slicer.read_int32_pair(pos)
+        pos += 8
+        if data_size == 0 and count == 0:
+            assert pos <= slicer.size, "terminator past blob end"
+            return sections
+        if data_size < 0 or not 0 <= count <= MAX_OBJECT_COUNT:
+            raise CorruptDataError(f"section size {data_size} / count {count} out of range")
+        if len(sections) == MAX_SECTIONS:
+            raise CorruptDataError(f"more than {MAX_SECTIONS} sections")
+        index_start = pos + data_size
+        raw_index = slicer.read(index_start, count * INDEX_ENTRY.size)
+        entries = [tuple(e) for e in INDEX_ENTRY.iter_unpack(raw_index)]
+        sections.append(StoreSection(pos, data_size, t.cast(list[tuple[bytes, int, int]], entries)))
+        pos = index_start + count * INDEX_ENTRY.size
+    raise CorruptDataError("no section terminator")
+
+
+def entry_in_bounds(section: StoreSection, offset: int, size: int) -> bool:
+    """True when an index entry's file lies inside its section's data."""
+    assert section.data_size >= 0, "negative section size"
+    return 0 <= offset and 0 < size and offset + size <= section.data_size
+
+
+def section_kind(slicer: BlobSlicer, section: StoreSection) -> type[Profile] | type[Tribe] | None:
+    """Classify a section by the class name in its first in-bounds file.
+
+    Pre: section bounds already validated. Post: ``Tribe``, ``Profile``, or
+    ``None`` when no entry names a known class.
+    """
+    assert section.entries is not None, "section has no index"
+    for _, offset, size in section.entries:
+        if not entry_in_bounds(section, offset, size) or size < CLASS_NAME_OFFSET + 4:
+            continue
+        head = slicer.read(section.data_start + offset, min(size, CLASS_NAME_OFFSET + 4 + MAX_CLASS_NAME))
+        length = struct.unpack_from("<i", head, CLASS_NAME_OFFSET)[0]
+        name = head[CLASS_NAME_OFFSET + 4 : CLASS_NAME_OFFSET + 4 + max(0, length)]
+        if Tribe.MAIN_CLASS_NAME.encode() in name:
+            return Tribe
+        if Profile.MAIN_CLASS_NAME.encode() in name:
+            return Profile
+        return None
+    return None
+
+
+def load_section(slicer: BlobSlicer, section: StoreSection, number: int, store: EmbeddedStore) -> None:
+    """Load the current entries of one section into ``store``.
+
+    Pre: ``section`` came from :func:`read_sections`. Post: current files are
+    parsed and de-duplicated by id (latest in index order wins); superseded
+    copies are counted; per-entry failures are recorded, never raised.
+    """
+    assert number >= 0, "negative section number"
+    kind = section_kind(slicer, section)
+    if kind is None:
+        store.errors.append(f"section {number}: unknown content, skipped")
+        return
+    label = "tribe" if kind is Tribe else "profile"
+    latest: dict[int, Profile | Tribe] = {}
+    superseded = 0
+    for i, (key, offset, size) in enumerate(section.entries):
+        if key == ZERO_KEY:
+            superseded += 1
+            continue
+        loaded = load_entry(slicer, section, kind, offset, size)
+        if isinstance(loaded, str):
+            store.errors.append(f"{label} #{i}: {loaded}")
+            continue
+        ident = loaded.tribe_id if isinstance(loaded, Tribe) else loaded.player_id
+        latest[ident if isinstance(ident, int) else -1 - i] = loaded
+    if kind is Tribe:
+        store.tribes.extend(t.cast(list[Tribe], list(latest.values())))
+        store.superseded_tribes += superseded
+    else:
+        store.profiles.extend(t.cast(list[Profile], list(latest.values())))
+        store.superseded_profiles += superseded
+    assert superseded <= len(section.entries), "superseded count exceeds entries"
+
+
+def load_entry(
+    slicer: BlobSlicer,
+    section: StoreSection,
+    kind: type[Profile] | type[Tribe],
+    offset: int,
+    size: int,
+) -> Profile | Tribe | str:
+    """Parse one packed file; return the object or an error string.
+
+    Pre: ``kind`` is ``Profile`` or ``Tribe``. Post: never raises for bad
+    entry data; out-of-bounds entries, unknown versions, and parse failures
+    come back as a one-line reason.
+    """
+    assert kind in (Profile, Tribe), "unsupported entry kind"
+    if not entry_in_bounds(section, offset, size) or size < 4:
+        return f"offset {offset} size {size} outside section of {section.data_size} bytes"
+    raw = slicer.read(section.data_start + offset, size)
+    version = struct.unpack_from("<i", raw, 0)[0]
+    if version not in kind.VALID_VERSIONS:
+        return f"unsupported file version {version}"
+    try:
+        return kind.load(raw)
+    except Exception as exc:  # noqa: BLE001 - one bad entry must not sink the store
+        logger.debug("Embedded %s entry failed to parse", kind.__name__, exc_info=True)
+        return f"{type(exc).__name__}: {exc}"

{arkparser-0.8.0 → arkparser-0.9.0}/arkparser/files/world_save.py

@@ -40,6 +40,7 @@ from ..game_objects.container import GameObjectContainer
 from ..game_objects.game_object import MAX_OBJECT_COUNT, GameObject
 from ..game_objects.location import LocationData
 from ..properties.registry import read_properties, read_properties_partial
+from .embedded_store import EmbeddedStore, load_embedded_store
 
 logger = logging.getLogger(__name__)
 
@@ -171,6 +172,9 @@ class WorldSave:
     # matching the legacy ContentContainer.GetApproxDateTimeOf formula:
     # real = file_mtime + (object_time - game_time).
     file_mtime: dt.datetime | None = None
+    # Path the save was loaded from (None when loaded from bytes). Lets
+    # read_embedded_store reopen an eagerly loaded ASA save's database.
+    source_path: Path | None = None
 
     # ASE-specific
     embedded_data: list[EmbeddedData] = field(default_factory=list)
@@ -324,6 +328,7 @@ class WorldSave:
                 reader = BinaryReader.from_file(path)
             save = cls._parse_ase(reader, load_properties, lazy_properties)
         save.file_mtime = mtime
+        save.source_path = path
         return save
 
     # ------------------------------------------------------------------
@@ -499,6 +504,33 @@ class WorldSave:
             if cryo is not None:
                 yield obj, cryo
 
+    def read_embedded_store(self) -> EmbeddedStore:
+        """Read the player/tribe files packed inside an ASA save.
+
+        Some ASA servers write no ``.arkprofile`` / ``.arktribe`` files and
+        pack them into the save instead (see ``embedded_store``). Not run by
+        :meth:`load`; callers that want the data ask for it, so load cost is
+        unchanged for everyone else.
+
+        Pre: the save was loaded from a path (ASA) or is ASE. Post: returns
+        the current profiles and tribes; ASE saves and saves without a store
+        return an empty :class:`EmbeddedStore`. Reuses the lazy connection
+        when present, otherwise opens and closes a read-only one.
+        """
+        if not self.is_asa:
+            return EmbeddedStore()
+        if self._lazy_conn is not None:
+            return load_embedded_store(self._lazy_conn)
+        assert self.source_path is not None, "ASA saves always load from a path"
+        uri = self.source_path.resolve().as_uri() + "?mode=ro"
+        conn = sqlite3.connect(uri, uri=True)
+        try:
+            store = load_embedded_store(conn)
+        finally:
+            conn.close()
+        assert isinstance(store, EmbeddedStore), "store loader returned wrong type"
+        return store
+
     # ------------------------------------------------------------------
     # Properties
     # ------------------------------------------------------------------

{arkparser-0.8.0 → arkparser-0.9.0}/arkparser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkparser
-Version: 0.8.0
+Version: 0.9.0
 Summary: Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files
 Author: Vertyco
 License-Expression: MIT
@@ -133,6 +133,27 @@ print(f"Parse errors: {save.parse_error_count}")
 print(f"Is ASA: {save.is_asa}")
 ```
 
+### Player/tribe data packed in the save (ASA)
+
+Some ASA servers (Nitrado observed) write no `.arkprofile` / `.arktribe` files.
+The same files are packed inside the `.ark` instead. Read them and attach them
+the same way you would attach sidecar files:
+
+```python
+from arkparser import WorldSave, export_all
+
+save = WorldSave.load("path/to/Ragnarok_WP.ark", lazy_properties=True)
+store = save.read_embedded_store()
+save.profiles, save.tribes = store.profiles, store.tribes
+data = export_all(save)
+```
+
+`EmbeddedStore` holds `profiles`, `tribes`, `superseded_profiles` /
+`superseded_tribes` (old copies the game leaves behind, skipped), and
+`errors` (one line per skipped entry; a bad entry never fails the load). Saves
+from servers that write sidecar files return an empty store. Not run by
+`load()`, so it costs nothing unless called.
+
 ### Low-memory parsing (large saves)
 
 By default every object's property block is parsed up front, which on a busy
@@ -577,6 +598,7 @@ Key methods:
 | `get_object_by_guid(guid)` | `GameObject \| None` | Lookup by GUID (ASA) |
 | `get_actor_location(guid)` | `LocationData \| None` | Actor location by GUID (ASA) |
 | `iter_cryopod_creatures()` | `Iterator[(GameObject, CryopodCreature)]` | Walk filled cryopods |
+| `read_embedded_store()` | `EmbeddedStore` | Player and tribe files packed inside an ASA save (servers that write no `.arkprofile` / `.arktribe`); see "Player/tribe data packed in the save" |
 
 ### Game Objects
 

{arkparser-0.8.0 → arkparser-0.9.0}/arkparser.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ arkparser/common/version_detection.py
 arkparser/files/__init__.py
 arkparser/files/base.py
 arkparser/files/cloud_inventory.py
+arkparser/files/embedded_store.py
 arkparser/files/profile.py
 arkparser/files/tribe.py
 arkparser/files/world_save.py
@@ -50,6 +51,7 @@ tests/test_cloud_inventory.py
 tests/test_cryopod_export.py
 tests/test_current_stats.py
 tests/test_data_models.py
+tests/test_embedded_store.py
 tests/test_export.py
 tests/test_game_objects.py
 tests/test_golden_exports.py

{arkparser-0.8.0 → arkparser-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arkparser"
-version = "0.8.0"
+version = "0.9.0"
 description = "Pure Python parser for ARK: Survival Evolved and ARK: Survival Ascended save files"
 readme = "README.md"
 license = "MIT"

arkparser-0.9.0/tests/test_embedded_store.py

@@ -0,0 +1,197 @@
+"""Tests for the player/tribe store packed inside ASA world saves.
+
+Layout tests build stores in an in-memory SQLite database and need no files.
+Content tests pack real sidecar files from the ScorchedEarth reference bundle
+(skipped when absent). The real Nitrado sample is local-only and never
+committed: it holds a third party's player data.
+"""
+
+import shutil
+import sqlite3
+import struct
+from pathlib import Path
+
+import pytest
+
+from arkparser import EmbeddedStore, Profile, Tribe, WorldSave, export_all
+from arkparser.files.embedded_store import STORE_KEY, load_embedded_store
+
+ASA_SAVES = Path(__file__).parent.parent / "references" / "local_saves" / "survival_ascended"
+SCORCHED_DIR = ASA_SAVES / "scorchedearth_wp"
+# Outside survival_ascended/ so the golden suite never discovers it.
+NITRADO_SAMPLE = ASA_SAVES.parent / "third_party" / "nitrado_store_ragnarok" / "Ragnarok_WP.ark"
+
+Entry = tuple[bytes, bytes]  # (8-byte key, packed file bytes)
+
+
+def pack_section(entries: list[Entry]) -> bytes:
+    """One section: size, count, files back to back, then the index."""
+    files = b"".join(data for _, data in entries)
+    index = b""
+    offset = 0
+    for key, data in entries:
+        index += struct.pack("<8sii", key, offset, len(data))
+        offset += len(data)
+    return struct.pack("<2i", len(files), len(entries)) + files + index
+
+
+def pack_store(*sections: bytes, fmt: int = 1, terminator: bool = True) -> bytes:
+    return struct.pack("<i", fmt) + b"".join(sections) + (b"\x00" * 8 if terminator else b"")
+
+
+def store_db(blob: bytes | None) -> sqlite3.Connection:
+    conn = sqlite3.connect(":memory:")
+    conn.execute("CREATE TABLE custom (key VARCHAR(64) primary key not null, value blob not null)")
+    if blob is not None:
+        conn.execute("INSERT INTO custom VALUES (?, ?)", (STORE_KEY, blob))
+    return conn
+
+
+def key(n: int) -> bytes:
+    return struct.pack("<q", n)
+
+
+# ---------------------------------------------------------------- layout
+
+
+@pytest.mark.parametrize("blob", [None, b"\x00" * 20, b"\x00" * 28, b"\x01" * 8])
+def test_missing_or_tiny_store_is_empty(blob: bytes | None) -> None:
+    store = load_embedded_store(store_db(blob))
+    assert (store.profiles, store.tribes, store.errors) == ([], [], [])
+
+
+def test_unknown_format_reports_one_error() -> None:
+    store = load_embedded_store(store_db(pack_store(pack_section([]), fmt=2)))
+    assert store.tribes == [] and len(store.errors) == 1
+    assert "format 2" in store.errors[0]
+
+
+def test_truncated_index_reports_one_error() -> None:
+    blob = pack_store(pack_section([(key(1), b"x" * 40)]), terminator=False)[:-8]
+    store = load_embedded_store(store_db(blob))
+    assert store.tribes == [] and len(store.errors) == 1
+
+
+def test_missing_terminator_reports_one_error() -> None:
+    blob = pack_store(pack_section([(key(1), b"z" * 40)]), terminator=False)
+    store = load_embedded_store(store_db(blob))
+    assert len(store.errors) == 1
+
+
+def test_too_many_sections_reports_one_error() -> None:
+    section = pack_section([(key(1), b"y" * 40)])
+    store = load_embedded_store(store_db(pack_store(section, section, section, section)))
+    assert store.tribes == [] and len(store.errors) == 1
+    assert "sections" in store.errors[0]
+
+
+def test_unknown_section_content_is_skipped() -> None:
+    junk = b"\x07\x00\x00\x00" + b"\x00" * 28 + struct.pack("<i", 8) + b"Unknown\x00"
+    store = load_embedded_store(store_db(pack_store(pack_section([(key(1), junk)]))))
+    assert store.tribes == [] and store.profiles == []
+    assert store.errors == ["section 0: unknown content, skipped"]
+
+
+def test_ase_save_has_no_store() -> None:
+    assert WorldSave().read_embedded_store() == EmbeddedStore()
+
+
+# ---------------------------------------------------------------- content
+
+
+@pytest.fixture
+def scorched_sidecars() -> tuple[list[bytes], list[bytes]]:
+    if not SCORCHED_DIR.exists():
+        pytest.skip(f"Fixture not available: {SCORCHED_DIR}")
+    tribes = [p.read_bytes() for p in sorted(SCORCHED_DIR.glob("*.arktribe"))[:2]]
+    profiles = [p.read_bytes() for p in sorted(SCORCHED_DIR.glob("*.arkprofile"))[:3]]
+    assert len(tribes) == 2 and len(profiles) == 3
+    return tribes, profiles
+
+
+def build_blob(tribes: list[bytes], profiles: list[bytes]) -> bytes:
+    """Store with one stale (zero-key) copy per section ahead of the live ones."""
+    zero = b"\x00" * 8
+    tribe_entries = [(zero, tribes[0])] + [(key(i + 1), data) for i, data in enumerate(tribes)]
+    profile_entries = [(zero, profiles[0])] + [(key(i + 10), data) for i, data in enumerate(profiles)]
+    return pack_store(pack_section(tribe_entries), pack_section(profile_entries))
+
+
+def test_current_entries_load(scorched_sidecars: tuple[list[bytes], list[bytes]]) -> None:
+    tribes, profiles = scorched_sidecars
+    store = load_embedded_store(store_db(build_blob(tribes, profiles)))
+    assert store.errors == []
+    assert (len(store.tribes), len(store.profiles)) == (2, 3)
+    assert (store.superseded_tribes, store.superseded_profiles) == (1, 1)
+    assert {t.tribe_id for t in store.tribes} == {Tribe.load(b).tribe_id for b in tribes}
+    assert {p.unique_id for p in store.profiles} == {Profile.load(b).unique_id for b in profiles}
+    assert all(p.source_path is None for p in store.profiles)
+
+
+def test_duplicate_live_entries_keep_the_last(scorched_sidecars: tuple[list[bytes], list[bytes]]) -> None:
+    tribes = scorched_sidecars[0]
+    section = pack_section([(key(1), tribes[0]), (key(2), tribes[0])])
+    store = load_embedded_store(store_db(pack_store(section)))
+    assert len(store.tribes) == 1 and store.errors == []
+
+
+def test_bad_entry_is_skipped_rest_load(scorched_sidecars: tuple[list[bytes], list[bytes]]) -> None:
+    tribes = scorched_sidecars[0]
+    good = pack_section([(key(1), tribes[0]), (key(2), tribes[1])])
+    # Point the second index entry past the end of the section's data.
+    bad_offset = len(good) - 8
+    broken = good[:bad_offset] + struct.pack("<ii", 10_000_000, 64)
+    store = load_embedded_store(store_db(pack_store(broken)))
+    assert len(store.tribes) == 1
+    assert len(store.errors) == 1 and store.errors[0].startswith("tribe #1:")
+
+
+def minimal_save(tmp_path: Path, blob: bytes) -> Path:
+    """An ASA save with a real SaveHeader, no objects, and the given store."""
+    src = next(SCORCHED_DIR.glob("*_WP.ark"))
+    with sqlite3.connect(f"file:{src.as_posix()}?mode=ro", uri=True) as ref:
+        header = ref.execute("SELECT value FROM custom WHERE key = 'SaveHeader'").fetchone()[0]
+    path = tmp_path / "Store_WP.ark"
+    conn = sqlite3.connect(path)
+    conn.execute("CREATE TABLE game (key BLOB primary key not null, value blob not null)")
+    conn.execute("CREATE TABLE custom (key VARCHAR(64) primary key not null, value blob not null)")
+    conn.executemany("INSERT INTO custom VALUES (?, ?)", [("SaveHeader", header), (STORE_KEY, blob)])
+    conn.commit()
+    conn.close()
+    return path
+
+
+@pytest.mark.parametrize("lazy", [False, True])
+def test_world_save_reads_store_and_exports(
+    tmp_path: Path, scorched_sidecars: tuple[list[bytes], list[bytes]], lazy: bool
+) -> None:
+    tribes, profiles = scorched_sidecars
+    save = WorldSave.load(minimal_save(tmp_path, build_blob(tribes, profiles)), lazy_properties=lazy)
+    store = save.read_embedded_store()
+    assert (len(store.tribes), len(store.profiles), store.errors) == (2, 3, [])
+    save.tribes, save.profiles = store.tribes, store.profiles
+    data = export_all(save)
+    # Tribe members without a profile also get player rows, so check inclusion.
+    exported_ids = {str(r["playerid"]) for r in data["ASV_Players"]}
+    assert {str(p.player_id) for p in store.profiles} <= exported_ids
+    assert {r["tribeid"] for r in data["ASV_Tribes"]} >= {t.tribe_id for t in store.tribes}
+    if save._lazy_conn is not None:
+        save._lazy_conn.close()
+
+
+# ---------------------------------------------------------------- real sample
+
+
+def test_nitrado_sample(tmp_path: Path) -> None:
+    if not NITRADO_SAMPLE.exists():
+        pytest.skip(f"Local-only sample not available: {NITRADO_SAMPLE}")
+    copy = Path(shutil.copy2(NITRADO_SAMPLE, tmp_path / NITRADO_SAMPLE.name))
+    save = WorldSave.load(copy, lazy_properties=True)
+    store = save.read_embedded_store()
+    assert (len(store.tribes), len(store.profiles)) == (6, 8)
+    assert (store.superseded_tribes, store.superseded_profiles) == (13, 14)
+    save.tribes, save.profiles = store.tribes, store.profiles
+    logs = export_all(save)["ASV_TribeLogs"]
+    assert sum(len(r.get("logs") or []) for r in logs) == 835
+    assert save._lazy_conn is not None
+    save._lazy_conn.close()