adopt-export 0.3.0__py3-none-any.whl

adopt_export/__init__.py

@@ -0,0 +1,62 @@
+"""Export bundle writer and reader — contracts §11, implementation spec §4.10.
+
+The portability promise in executable form: *export → import → export produces
+byte-identical table files*, and every identity in the second export resolves by
+URI alone with no ULID lookup. That property is gate **G0** and Build 0's
+definition of done, condition 2.
+
+Invariants this package holds:
+
+* **No network.** Nothing here opens a socket.
+* **Writes confined to the target directory.** The writer creates the bundle and
+  nothing else; the reader writes only through the `ImportRecords` port.
+* **Runtime-annex tables are excluded by construction**, not by a filter: they
+  are not in the canonical manifest, and the manifest is what the writer
+  iterates (contracts §12).
+* **No dialect.** This package declares its own storage ports and imports no
+  store, so `no-raw-sqlite` holds and a Postgres realization changes nothing
+  here.
+"""
+
+from adopt_export.bundle import (
+    BLOBS_DIRNAME,
+    MANIFEST_FILENAME,
+    SCHEMA_FILENAME,
+    TABLE_SUFFIX,
+    TABLES_DIRNAME,
+    BlobSummary,
+    BundleManifest,
+    BundleScope,
+    TableEntry,
+    canonical_json,
+    row_object,
+    sha256_of_bytes,
+    table_relative_path,
+)
+from adopt_export.ports import ExportRecords, ImportRecords
+from adopt_export.reader import apply_bundle, read_bundle
+from adopt_export.roundtrip import table_files, verify_roundtrip
+from adopt_export.writer import write_bundle
+
+__all__ = [
+    "BLOBS_DIRNAME",
+    "MANIFEST_FILENAME",
+    "SCHEMA_FILENAME",
+    "TABLES_DIRNAME",
+    "TABLE_SUFFIX",
+    "BlobSummary",
+    "BundleManifest",
+    "BundleScope",
+    "ExportRecords",
+    "ImportRecords",
+    "TableEntry",
+    "apply_bundle",
+    "canonical_json",
+    "read_bundle",
+    "row_object",
+    "sha256_of_bytes",
+    "table_files",
+    "table_relative_path",
+    "verify_roundtrip",
+    "write_bundle",
+]

adopt_export/bundle.py

@@ -0,0 +1,150 @@
+"""The bundle layout, its manifest shape, and the canonical rendering rules.
+
+Contracts §11. Everything here exists to make one sentence true --
+*export → import → export produces byte-identical table files* -- and that
+sentence is only true if every rendering decision is made in exactly one place.
+
+**One JSON rule, at every nesting level:** no ASCII escaping, no spaces, keys
+sorted. Sorting applies to the row object and to anything nested inside a `json`
+column alike, because a rule with an exception is a rule someone applies to the
+outer object and forgets on the inner one -- and the inner one is
+`permitted_outbound_categories`, the only `json` column schema version 3 has.
+
+**Timestamps are rendered here, not by pydantic.** `model_dump(mode="json")`
+would emit whatever the library's default happens to be; contracts §1.2 requires
+millisecond precision with a `Z` suffix, and a bundle written before a pydantic
+upgrade must equal one written after it.
+
+**There is no `blobs/` directory at schema version 3.** No exportable table
+declares a blob reference -- the only one in the pack is `agent_run.output_ref`,
+which lives in the runtime annex (§12) and is never exported. The manifest still
+carries the `blobs` block, reporting zero, which is what §11's *"present only
+when referenced"* means for this version. Inventing a collection mechanism for a
+source that does not exist would be inventing its bugs too.
+"""
+
+import datetime as _dt
+import hashlib
+import json as _json
+from pathlib import Path
+from typing import Any, Final
+
+from pydantic import BaseModel, ConfigDict
+
+from adopt_obs import format_timestamp
+
+__all__ = [
+    "BLOBS_DIRNAME",
+    "MANIFEST_FILENAME",
+    "SCHEMA_FILENAME",
+    "TABLES_DIRNAME",
+    "TABLE_SUFFIX",
+    "BlobSummary",
+    "BundleManifest",
+    "BundleScope",
+    "TableEntry",
+    "canonical_json",
+    "read_text",
+    "row_object",
+    "sha256_of_bytes",
+    "table_relative_path",
+]
+
+MANIFEST_FILENAME: Final[str] = "manifest.json"
+SCHEMA_FILENAME: Final[str] = "export.schema.json"
+TABLES_DIRNAME: Final[str] = "tables"
+BLOBS_DIRNAME: Final[str] = "blobs"
+TABLE_SUFFIX: Final[str] = ".ndjson"
+
+#: NDJSON is line-delimited by definition, and the delimiter is pinned to `\n`
+#: so a Windows checkout and a Linux runner produce the same bytes -- the same
+#: reason `adopt_schema.generate` opens its targets with `newline="\n"`.
+LINE_SEPARATOR: Final[str] = "\n"
+ENCODING: Final[str] = "utf-8"
+
+
+def canonical_json(value: object) -> str:
+    """The one rendering. Sorted keys, no spaces, no ASCII escaping."""
+    return _json.dumps(value, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
+
+
+def sha256_of_bytes(payload: bytes) -> str:
+    return hashlib.sha256(payload).hexdigest()
+
+
+def table_relative_path(table: str) -> str:
+    """`tables/<table>.ndjson`, as it appears in the manifest and on disk."""
+    return f"{TABLES_DIRNAME}/{table}{TABLE_SUFFIX}"
+
+
+def row_object(model: BaseModel) -> dict[str, Any]:
+    """One validated row as the JSON object a bundle line carries.
+
+    Dumped **by alias**, because the alias is the canonical column name: one
+    column is called `class`, a Python keyword, whose field is therefore
+    `class_`. A bundle carrying `class_` would not validate against
+    `export.schema.json`, which is generated from the manifest and names columns.
+    """
+    return {
+        name: format_timestamp(value) if isinstance(value, _dt.datetime) else value
+        for name, value in model.model_dump(by_alias=True).items()
+    }
+
+
+class _Strict(BaseModel):
+    """Closed by construction: an unknown key in a bundle manifest is a defect."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class BundleScope(_Strict):
+    """The scope a bundle belongs to, **as slugs** so it resolves without ULIDs."""
+
+    firm: str
+    engagement: str
+
+
+class TableEntry(_Strict):
+    name: str
+    rows: int
+    sha256: str
+    #: Columns the manifest has retired at this schema version. Present and empty
+    #: rather than omitted, because §11 requires the field to distinguish
+    #: "absent" from "null for every row" -- and an absent list says neither.
+    omitted_columns: list[str]
+
+
+class BlobSummary(_Strict):
+    count: int
+    total_bytes: int
+
+
+class BundleManifest(_Strict):
+    """`manifest.json`, exactly the §11 keys and no others."""
+
+    export_version: int
+    schema_version: int
+    scope: BundleScope
+    written_by: str
+    #: A string, not a datetime: it is rendered once by the writer and compared
+    #: as text thereafter. Re-parsing it into a datetime only to render it again
+    #: would put a second timestamp format in the round trip.
+    written_at: str
+    tables: list[TableEntry]
+    blobs: BlobSummary
+
+    def entry_for(self, table: str) -> TableEntry | None:
+        return next((entry for entry in self.tables if entry.name == table), None)
+
+    def to_bytes(self) -> bytes:
+        return (canonical_json(self.model_dump()) + LINE_SEPARATOR).encode(ENCODING)
+
+
+def read_text(path: Path) -> str:
+    """Read a bundle file as text without letting the platform rewrite newlines.
+
+    Decoded from bytes rather than read as text: `Path.read_text` opens in text
+    mode, and text mode on Windows turns a `\\r\\n` in a bundle into a `\\n` on
+    the way in. A bundle's bytes are the contract, so they are never translated.
+    """
+    return path.read_bytes().decode(ENCODING)

adopt_export/ports.py

@@ -0,0 +1,82 @@
+"""The two storage ports the bundle writer and reader run on.
+
+Declared here rather than imported from `adopt_store`, following the precedent
+`adopt_scope.records` set and CR-34 extended to coverage and freshness:
+`no-raw-sqlite` names `adopt_export` as a source module and import-linter follows
+the chain, so a dependency on `adopt_store` would reach `sqlite3` transitively
+and break the contract. A structural protocol costs one file and keeps this
+package free of any dialect -- which is what makes "the same bundle whichever
+store answered" a property of the writer rather than a coincidence.
+
+**The ports fetch and apply rows; they never decide.** Row order, the scope
+refusal, digest verification and the all-or-nothing boundary are all the
+writer's and the reader's. Pushing any of them into a realization would mean the
+byte-identical round-trip was a property of whichever store ran, and the
+round-trip property test would be comparing two callers of one query.
+
+**`insert_rows` takes whole validated models, never a column subset.** That is
+deliberate and load-bearing: `identity.covered_cache` is an exportable column,
+and a port that could write *some* columns of `identity` would be the general
+setter `no-covered-cache-write` exists to forbid. Import restores rows exactly as
+a bundle recorded them, into an empty store, or it refuses.
+"""
+
+from collections.abc import Sequence
+from contextlib import AbstractContextManager
+from typing import Protocol
+
+from pydantic import BaseModel
+
+__all__ = ["ExportRecords", "ImportRecords"]
+
+
+class ExportRecords(Protocol):
+    """Read-only. No SQL, connection or cursor crosses this boundary."""
+
+    def firm_slugs(self) -> Sequence[str]:
+        """Every `firm.slug` in the store, and the writer decides what to do.
+
+        Reported rather than resolved because `manifest.json` names **one** firm
+        (contracts §11) and refusing is the writer's judgement. A port that
+        returned "the" firm slug would have to pick one, and picking one for a
+        store holding two produces a bundle labelled with a scope half its rows
+        do not belong to -- which nothing downstream can detect.
+        """
+        ...
+
+    def engagement_slugs(self) -> Sequence[str]:
+        """Every `engagement.slug` in the store. Same argument as `firm_slugs`."""
+        ...
+
+    def table_rows[TModel: BaseModel](
+        self, table: str, model_type: type[TModel]
+    ) -> Sequence[TModel]:
+        """Every row of one table, validated against its generated model.
+
+        Unordered by contract. The writer sorts by the manifest's primary key,
+        so the emitted order is a pure function of (manifest, rows) and identical
+        whichever realization answered.
+        """
+        ...
+
+
+class ImportRecords(Protocol):
+    """Write side. Whole rows only, inside the caller's transaction."""
+
+    def row_count(self, table: str) -> int:
+        """How many rows one table already holds.
+
+        The reader sums this across every exportable table to decide
+        `EXPORT_TARGET_NOT_EMPTY`, and names the first non-empty table in the
+        message -- "the store is not empty" sends an operator looking, and
+        "`firm` already holds 1 row" tells them what they are about to lose.
+        """
+        ...
+
+    def insert_rows(self, table: str, models: Sequence[BaseModel]) -> None:
+        """Append whole rows. The model is the column authority, as everywhere else."""
+        ...
+
+    def transaction(self) -> AbstractContextManager[None]:
+        """The one boundary the whole import commits or rolls back inside."""
+        ...

adopt_export/reader.py

@@ -0,0 +1,238 @@
+"""`read_bundle` and `apply_bundle` — the import half of contracts §11.
+
+The order of the checks is the contract, not an implementation detail:
+
+1. **Version negotiation first.** An `export_version` outside the supported range
+   is refused **naming the range**, because "unsupported" without the range sends
+   an integrator to the source and the whole point of pinning `export_version`
+   (§1.6, owner decision 12) is that they should not have to go there.
+2. **Every digest, before any row.** §11 says verified *before any row is
+   applied*, and F9.5 says all or nothing. Verifying per table as it is applied
+   would satisfy neither: the first table would already be in the store when the
+   fourth file turned out to be corrupt.
+3. **Then the rows**, all inside one transaction against an empty store.
+
+**Rows are applied verbatim, not through the facades.** A facade generates ids;
+import must preserve them, because a re-export whose ULIDs differ is not
+byte-identical and every URI in the bundle would resolve to a different row. That
+is also why the applier takes whole validated models: it restores what a bundle
+recorded and computes nothing.
+"""
+
+import json as _json
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, Final
+
+from pydantic import BaseModel, ValidationError
+
+from adopt_const import (
+    EXPORT_NDJSON_MAX_LINE_BYTES,
+    MAX_SUPPORTED_EXPORT_VERSION,
+    MIN_SUPPORTED_EXPORT_VERSION,
+)
+from adopt_export.bundle import (
+    ENCODING,
+    MANIFEST_FILENAME,
+    BundleManifest,
+    read_text,
+    sha256_of_bytes,
+    table_relative_path,
+)
+from adopt_export.ports import ImportRecords
+from adopt_model import MODEL_FOR_TABLE
+from adopt_obs import AdoptError, ErrorCode, get_logger
+from adopt_schema.manifest import Manifest, canonical_path, load_manifest
+
+__all__ = ["EXPORT_COMPAT_FILENAME", "apply_bundle", "read_bundle"]
+
+_LOGGER: Final = get_logger("adopt_export")
+
+#: Which `schema_version` each `export_version` implies. The two are versioned
+#: independently (§1.6), so the mapping is data rather than an equality anyone
+#: could assume from the fact that both happen to start at 3 (CR-13).
+EXPORT_COMPAT_FILENAME: Final[str] = "export_compat.json"
+
+
+def _malformed(message: str, hint: str) -> AdoptError:
+    return AdoptError(ErrorCode.EXPORT_BUNDLE_MALFORMED, message=message, hint=hint)
+
+
+def _load_compat(path: Path | None = None) -> dict[str, dict[str, int]]:
+    source = path if path is not None else canonical_path().parent / EXPORT_COMPAT_FILENAME
+    parsed: Any = _json.loads(source.read_text(encoding=ENCODING))
+    return {str(key): dict(value) for key, value in parsed.items()}
+
+
+def read_bundle(source: Path, *, compat_path: Path | None = None) -> BundleManifest:
+    """Parse and validate `manifest.json`, negotiate the version, verify nothing else.
+
+    Raises:
+        AdoptError: ``EXPORT_BUNDLE_MALFORMED`` when the manifest is missing or
+            does not match §11. ``EXPORT_VERSION_UNSUPPORTED`` when the bundle's
+            `export_version` is outside the supported range or its declared
+            `schema_version` is not the one that version implies.
+    """
+    manifest_path = source / MANIFEST_FILENAME
+    if not manifest_path.is_file():
+        raise _malformed(
+            f"no {MANIFEST_FILENAME} at {source}",
+            "A bundle is a directory whose manifest names every file in it. Point "
+            "import at the bundle directory, not at its `tables/` subdirectory.",
+        )
+
+    try:
+        bundle = BundleManifest.model_validate_json(read_text(manifest_path))
+    except ValidationError as error:
+        raise _malformed(
+            f"{manifest_path} does not match the contracts §11 manifest shape: {error}",
+            "The manifest is closed: every key is declared in §11, and an unknown one "
+            "is a bundle from a different format rather than a newer version of this one.",
+        ) from error
+
+    if not MIN_SUPPORTED_EXPORT_VERSION <= bundle.export_version <= MAX_SUPPORTED_EXPORT_VERSION:
+        raise AdoptError(
+            ErrorCode.EXPORT_VERSION_UNSUPPORTED,
+            message=f"bundle export_version {bundle.export_version} is outside the supported "
+            f"range {MIN_SUPPORTED_EXPORT_VERSION}-{MAX_SUPPORTED_EXPORT_VERSION}",
+            hint="Integrators pin `export_version` (contracts §1.6). Read the bundle with "
+            "a binary whose supported range includes it; nothing has been applied.",
+        )
+
+    implied = _load_compat(compat_path).get(str(bundle.export_version))
+    if implied is not None and implied.get("schema_version") != bundle.schema_version:
+        raise AdoptError(
+            ErrorCode.EXPORT_VERSION_UNSUPPORTED,
+            message=f"export_version {bundle.export_version} implies schema_version "
+            f"{implied.get('schema_version')}, and the bundle declares {bundle.schema_version}",
+            hint="`schema/export_compat.json` records which schema version each export "
+            "version carries. A bundle disagreeing with it was assembled by hand or by "
+            "a build that is not this one.",
+        )
+    return bundle
+
+
+def _verify_digests(source: Path, bundle: BundleManifest, manifest: Manifest) -> dict[str, bytes]:
+    """Every table file, read and digest-checked. Returns the verified bytes.
+
+    Read once and kept, rather than read now and re-read while applying: a file
+    that changed between the two reads would pass the digest check and apply
+    something else, which is precisely the substitution the digest exists to
+    prevent.
+    """
+    expected = {name for name, _ in manifest.exportable_tables()}
+    declared = {entry.name for entry in bundle.tables}
+
+    if declared != expected:
+        missing = sorted(expected - declared)
+        unexpected = sorted(declared - expected)
+        raise _malformed(
+            "the manifest's table set does not match schema version "
+            f"{manifest.schema_version}: missing {missing}, unexpected {unexpected}",
+            "Every exportable table produces a file, even when empty (§11), so a missing "
+            "entry is a truncated bundle rather than an empty table. An unexpected entry "
+            "is a table this schema version does not declare.",
+        )
+
+    verified: dict[str, bytes] = {}
+    for entry in bundle.tables:
+        path = source / table_relative_path(entry.name)
+        if not path.is_file():
+            raise _malformed(
+                f"the manifest names {entry.name} but {path} does not exist",
+                "Every table the manifest lists is present as a file, empty or not.",
+            )
+        payload = path.read_bytes()
+        actual = sha256_of_bytes(payload)
+        if actual != entry.sha256:
+            raise AdoptError(
+                ErrorCode.EXPORT_DIGEST_MISMATCH,
+                message=f"{table_relative_path(entry.name)} digests to {actual}, and the "
+                f"manifest records {entry.sha256}",
+                hint="Nothing has been applied. The bundle is corrupt or was edited after "
+                "it was written; re-export rather than repairing the file.",
+            )
+        verified[entry.name] = payload
+    return verified
+
+
+def _parse_rows(table: str, payload: bytes) -> Sequence[BaseModel]:
+    model_type = MODEL_FOR_TABLE[table]
+    models: list[BaseModel] = []
+    for number, raw in enumerate(payload.decode(ENCODING).split("\n"), 1):
+        if not raw:
+            continue
+        if len(raw.encode(ENCODING)) > EXPORT_NDJSON_MAX_LINE_BYTES:
+            raise _malformed(
+                f"{table} line {number} is over the {EXPORT_NDJSON_MAX_LINE_BYTES}-byte limit",
+                "A line this long is not a row this format can carry. The bundle was not "
+                "written by this version.",
+            )
+        try:
+            models.append(model_type.model_validate_json(raw))
+        except ValidationError as error:
+            raise _malformed(
+                f"{table} line {number} does not validate against its generated model: {error}",
+                "The generated models are the only validators (contracts §1.4) and they are "
+                "closed, so an unknown column is a row from a different schema rather than a "
+                "richer version of this one.",
+            ) from error
+    return models
+
+
+def apply_bundle(
+    records: ImportRecords,
+    source: Path,
+    *,
+    bundle: BundleManifest | None = None,
+    manifest: Manifest | None = None,
+    compat_path: Path | None = None,
+) -> BundleManifest:
+    """Verify a bundle whole, then apply every row in one transaction.
+
+    Args:
+        records: The write port, over a store already at the current schema version.
+        source: The bundle directory.
+        bundle: A manifest already read by `read_bundle`; read here if absent.
+        manifest: The canonical manifest. Loaded if not supplied.
+        compat_path: Override for `schema/export_compat.json`.
+
+    Raises:
+        AdoptError: ``EXPORT_VERSION_UNSUPPORTED``, ``EXPORT_DIGEST_MISMATCH``,
+            ``EXPORT_BUNDLE_MALFORMED`` or ``EXPORT_TARGET_NOT_EMPTY``. In every
+            case no row has been applied.
+    """
+    loaded = manifest if manifest is not None else load_manifest()
+    read = bundle if bundle is not None else read_bundle(source, compat_path=compat_path)
+
+    verified = _verify_digests(source, read, loaded)
+
+    for table_name, _ in loaded.exportable_tables():
+        held = records.row_count(table_name)
+        if held:
+            raise AdoptError(
+                ErrorCode.EXPORT_TARGET_NOT_EMPTY,
+                message=f"the target store already holds {held} row(s) in {table_name}",
+                hint="Import restores a bundle into an empty store and is never a merge: "
+                "the bundle carries the ids it was written with, so applying it over "
+                "existing rows would collide or silently interleave two histories.",
+            )
+
+    # Parsed before the transaction opens, so a malformed row fails without ever
+    # having started a write -- and the store is untouched rather than rolled back.
+    parsed = {name: _parse_rows(name, payload) for name, payload in verified.items()}
+
+    with records.transaction():
+        # Foreign-key topological order: `exportable_tables()` is already sorted
+        # by it, so a child never lands before its parent.
+        for table_name, _ in loaded.exportable_tables():
+            records.insert_rows(table_name, parsed[table_name])
+
+    _LOGGER.info(
+        "export.bundle_applied",
+        tables=len(read.tables),
+        rows=sum(entry.rows for entry in read.tables),
+        export_version=read.export_version,
+        schema_version=read.schema_version,
+    )
+    return read

adopt_export/roundtrip.py

@@ -0,0 +1,69 @@
+"""`verify_roundtrip` — the G0 comparison, and where `EXPORT_ROUNDTRIP_UNSTABLE` lives.
+
+The comparison is here rather than inside the test for two reasons. It is a
+product statement, not a test convenience: contracts §13 registers
+`EXPORT_ROUNDTRIP_UNSTABLE` as an error the programme raises, and an error code
+whose only caller is an assertion is a code that means nothing to anyone
+receiving it. And a comparison written inline in a test is a comparison nobody
+ever watches fail, which is the same objection the planted-violation discipline
+makes of every other gate here.
+
+**Table files only.** `manifest.json` carries `written_at`, which differs
+between two exports by design (PRD F9.2). Comparing it would make G0 fail on
+every run for the one reason that is not a defect.
+"""
+
+from pathlib import Path
+from typing import Final
+
+from adopt_export.bundle import TABLES_DIRNAME
+from adopt_obs import AdoptError, ErrorCode
+
+__all__ = ["table_files", "verify_roundtrip"]
+
+_FIRST: Final[str] = "first"
+_SECOND: Final[str] = "second"
+
+
+def table_files(bundle: Path) -> dict[str, bytes]:
+    """Every `tables/*.ndjson` in a bundle, by file name, as raw bytes."""
+    directory = bundle / TABLES_DIRNAME
+    if not directory.is_dir():
+        return {}
+    return {path.name: path.read_bytes() for path in sorted(directory.iterdir())}
+
+
+def verify_roundtrip(first: Path, second: Path) -> None:
+    """Raise unless two bundles' table files are byte-identical.
+
+    Args:
+        first: The bundle exported from the original store.
+        second: The bundle exported from the store the first was imported into.
+
+    Raises:
+        AdoptError: ``EXPORT_ROUNDTRIP_UNSTABLE``, naming the files that differ
+            and how -- present in one bundle only, or present in both with
+            different bytes.
+    """
+    left = table_files(first)
+    right = table_files(second)
+
+    differences: list[str] = []
+    for name in sorted(set(left) | set(right)):
+        if name not in right:
+            differences.append(f"{name}: in the {_FIRST} bundle only")
+        elif name not in left:
+            differences.append(f"{name}: in the {_SECOND} bundle only")
+        elif left[name] != right[name]:
+            differences.append(
+                f"{name}: {len(left[name])} bytes then {len(right[name])} bytes, and they differ"
+            )
+
+    if differences:
+        raise AdoptError(
+            ErrorCode.EXPORT_ROUNDTRIP_UNSTABLE,
+            message="re-export is not byte-identical: " + "; ".join(differences),
+            hint="The bundle a client keeps must survive a round trip unchanged. Look for "
+            "a rendering that depends on something other than the rows -- a key order, a "
+            "timestamp format, a collation -- rather than for a difference in the data.",
+        )

adopt_export/writer.py

@@ -0,0 +1,227 @@
+"""`write_bundle` — the export half of contracts §11.
+
+Three decisions live here rather than in whichever store answered, and each is
+the reason the byte-identical round trip is testable at all:
+
+* **Row order.** The writer sorts by the manifest's primary key over the
+  *rendered* values, so the order is byte-wise ascending as §11 requires and is a
+  pure function of (manifest, rows). Pushing `ORDER BY` into the realization
+  would make the emitted bytes depend on a collation, and the Postgres
+  realization would have to reproduce SQLite's exactly, unwritten and untested.
+* **The scope refusal.** `manifest.json` names one firm and one engagement. A
+  store holding two is refused before anything is created, because a bundle
+  labelled with a scope half its rows do not belong to is not a wrong answer, it
+  is a *different referent* -- and nothing downstream can detect it (CR-37).
+* **What counts as exportable.** The writer iterates
+  `Manifest.exportable_tables()`. Runtime-annex tables are excluded **by
+  construction**: they are not in the canonical manifest at all, so there is no
+  filter to forget (contracts §12).
+
+The writer opens no socket and writes nothing outside `target`.
+"""
+
+import datetime as _dt
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, Final
+
+from adopt_const import EXPORT_NDJSON_MAX_LINE_BYTES, EXPORT_VERSION, SCHEMA_VERSION
+from adopt_export.bundle import (
+    ENCODING,
+    LINE_SEPARATOR,
+    MANIFEST_FILENAME,
+    SCHEMA_FILENAME,
+    TABLES_DIRNAME,
+    BlobSummary,
+    BundleManifest,
+    BundleScope,
+    TableEntry,
+    canonical_json,
+    row_object,
+    sha256_of_bytes,
+    table_relative_path,
+)
+from adopt_export.ports import ExportRecords
+from adopt_model import MODEL_FOR_TABLE
+from adopt_obs import AdoptError, Clock, ErrorCode, SystemClock, format_timestamp, get_logger
+from adopt_schema.manifest import Manifest, Table, canonical_path, load_manifest
+
+__all__ = ["default_schema_source", "write_bundle"]
+
+_LOGGER: Final = get_logger("adopt_export")
+
+#: No exportable table at schema version 3 references a blob, so the block is
+#: reported as empty rather than assembled. See `bundle` for the full argument.
+_NO_BLOBS: Final[BlobSummary] = BlobSummary(count=0, total_bytes=0)
+
+
+def default_schema_source() -> Path:
+    """Where `export.schema.json` is read from, beside the manifest it came from.
+
+    Resolved through `canonical_path()` so the `ADOPT_SCHEMA_MANIFEST` override
+    moves both together. A bundle carrying a schema from one checkout and rows
+    from another is a bundle that validates against the wrong contract.
+    """
+    return canonical_path().parent / SCHEMA_FILENAME
+
+
+def _sole_slug(kind: str, slugs: Sequence[str]) -> str:
+    distinct = sorted(set(slugs))
+    if len(distinct) == 1:
+        return distinct[0]
+    if not distinct:
+        raise AdoptError(
+            ErrorCode.EXPORT_SCOPE_AMBIGUOUS,
+            message=f"the store holds no {kind}, and a bundle names one",
+            hint="Create the scope before exporting. An empty store has no scope to "
+            "record, and a bundle whose scope is guessed is a bundle nothing can trust.",
+        )
+    raise AdoptError(
+        ErrorCode.EXPORT_SCOPE_AMBIGUOUS,
+        message=f"the store holds {len(distinct)} {kind}s ({', '.join(distinct)}) "
+        f"and contracts §11 names one",
+        hint="Export one scope per bundle. Labelling a bundle with one of several "
+        "scopes is not a wrong answer but a different referent, and no consumer of "
+        "the bundle can detect it.",
+    )
+
+
+def _omitted_columns(table: Table) -> list[str]:
+    """Columns the manifest has retired at or below the current schema version.
+
+    Empty at version 3, and computed rather than hard-coded so it stops being
+    empty by itself the first time a column is retired -- which is the only way
+    §11's "absent versus null for every row" distinction stays true.
+    """
+    return sorted(
+        column.name
+        for column in table.columns
+        if column.retired_in_version is not None and column.retired_in_version <= SCHEMA_VERSION
+    )
+
+
+def _sort_key(row: dict[str, Any], primary_key: Sequence[str]) -> tuple[str, ...]:
+    """Byte-wise ascending over the rendered primary key (§11).
+
+    Rendered, not raw: the values compared are the ones about to be written, so
+    the file's order and the file's bytes cannot disagree. Every canonical
+    primary-key column is a `id`, `slug`, `text` or `ts`, all of which render as
+    strings, so this is a total order rather than a best effort.
+    """
+    return tuple(str(row[column]) for column in primary_key)
+
+
+def _render_table(table_name: str, table: Table, records: ExportRecords) -> tuple[bytes, int]:
+    """One table's file content and its row count. Empty tables render empty."""
+    models = records.table_rows(table_name, MODEL_FOR_TABLE[table_name])
+    rows = sorted(
+        (row_object(model) for model in models),
+        key=lambda row: _sort_key(row, table.primary_key),
+    )
+
+    lines: list[str] = []
+    for index, row in enumerate(rows):
+        line = canonical_json(row)
+        encoded = line.encode(ENCODING)
+        if len(encoded) > EXPORT_NDJSON_MAX_LINE_BYTES:
+            raise AdoptError(
+                ErrorCode.EXPORT_BUNDLE_MALFORMED,
+                message=f"{table_name} row {index} renders to {len(encoded)} bytes, over the "
+                f"{EXPORT_NDJSON_MAX_LINE_BYTES}-byte line limit",
+                hint="The reader refuses a line this long, so writing one would produce a "
+                "bundle this version cannot import. The row is too large for the format.",
+            )
+        lines.append(line)
+
+    content = "".join(line + LINE_SEPARATOR for line in lines)
+    return content.encode(ENCODING), len(rows)
+
+
+def write_bundle(
+    records: ExportRecords,
+    target: Path,
+    *,
+    written_by: str,
+    manifest: Manifest | None = None,
+    clock: Clock | None = None,
+    schema_source: Path | None = None,
+) -> BundleManifest:
+    """Write a bundle to ``target`` and return the manifest it recorded.
+
+    Args:
+        records: The read port. Never written through.
+        target: The bundle directory. Created if absent; refused if non-empty.
+        written_by: Provenance for `manifest.json`, e.g. ``adopt-core/0.3.0``.
+        manifest: The canonical manifest. Loaded if not supplied.
+        clock: Injected clock; tests pass `ManualClock`.
+        schema_source: Where to copy `export.schema.json` from.
+
+    Raises:
+        AdoptError: ``EXPORT_SCOPE_AMBIGUOUS`` when the store does not hold
+            exactly one firm and one engagement. ``EXPORT_TARGET_NOT_EMPTY``
+            when ``target`` already holds anything. ``EXPORT_BUNDLE_MALFORMED``
+            when a row would render past the line limit.
+    """
+    loaded = manifest if manifest is not None else load_manifest()
+    ticking = clock if clock is not None else SystemClock()
+
+    # Scope first, before anything exists on disk: a refusal that has already
+    # created half a bundle leaves a directory an operator has to reason about.
+    scope = BundleScope(
+        firm=_sole_slug("firm", records.firm_slugs()),
+        engagement=_sole_slug("engagement", records.engagement_slugs()),
+    )
+
+    if target.exists() and any(target.iterdir()):
+        raise AdoptError(
+            ErrorCode.EXPORT_TARGET_NOT_EMPTY,
+            message=f"{target} is not empty",
+            hint="Export writes a whole bundle or none of one. Point it at a new "
+            "directory rather than merging into an existing bundle, whose manifest "
+            "would then describe files it did not write.",
+        )
+
+    tables_dir = target / TABLES_DIRNAME
+    tables_dir.mkdir(parents=True, exist_ok=True)
+
+    entries: list[TableEntry] = []
+    for table_name, table in loaded.exportable_tables():
+        content, count = _render_table(table_name, table, records)
+        (target / table_relative_path(table_name)).write_bytes(content)
+        entries.append(
+            TableEntry(
+                name=table_name,
+                rows=count,
+                sha256=sha256_of_bytes(content),
+                omitted_columns=_omitted_columns(table),
+            )
+        )
+
+    source = schema_source if schema_source is not None else default_schema_source()
+    (target / SCHEMA_FILENAME).write_bytes(source.read_bytes())
+
+    bundle_manifest = BundleManifest(
+        export_version=EXPORT_VERSION,
+        schema_version=loaded.schema_version,
+        scope=scope,
+        written_by=written_by,
+        written_at=format_timestamp(_as_utc(ticking.now())),
+        tables=entries,
+        blobs=_NO_BLOBS,
+    )
+    # Written last: a manifest present means every file it names is present too,
+    # so a reader never has to distinguish a finished bundle from an abandoned one.
+    (target / MANIFEST_FILENAME).write_bytes(bundle_manifest.to_bytes())
+
+    _LOGGER.info(
+        "export.bundle_written",
+        tables=len(entries),
+        rows=sum(entry.rows for entry in entries),
+        export_version=EXPORT_VERSION,
+        schema_version=loaded.schema_version,
+    )
+    return bundle_manifest
+
+
+def _as_utc(moment: _dt.datetime) -> _dt.datetime:
+    return moment.astimezone(_dt.UTC)

adopt_export-0.3.0.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.5
+Name: adopt-export
+Version: 0.3.0
+Summary: Export bundle writer and reader; the byte-stable round trip.
+Project-URL: Homepage, https://github.com/onboardux/onboard-core
+Project-URL: Source, https://github.com/onboardux/onboard-core
+Project-URL: Issues, https://github.com/onboardux/onboard-core/issues
+Author: The Adopt Authors
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.12
+Requires-Dist: adopt-const
+Requires-Dist: adopt-model
+Requires-Dist: adopt-obs
+Requires-Dist: adopt-schema

adopt_export-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+adopt_export/__init__.py,sha256=OEGKN-xXE8QE36WbJX5VowpcuojAVjJMyF6fZJXlGSQ,1892
+adopt_export/bundle.py,sha256=bpCdWoOgiWmMHP3Hqle33zZTLGFmga1MqnyoxZvDYP8,5410
+adopt_export/ports.py,sha256=E5Gbzwx26j1TcT2LJNwonAfC89T6q3X5gMFV01GKn9U,3593
+adopt_export/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+adopt_export/reader.py,sha256=-_tFiTktRDOzgLrUsn6wu-Ks8kPVVDTmgCuPJQx-2Fs,10770
+adopt_export/roundtrip.py,sha256=83524fEU0z0FL44aFhXgLJ10xRZaeTubD6YssxUPgvo,2808
+adopt_export/writer.py,sha256=2yJxsJbGLyqfHW2NIje3RCB0w7RCSpdoinXVp-bEQ4I,9275
+adopt_export-0.3.0.dist-info/METADATA,sha256=aXniGusAXx7N7MSNTQ8Ngw-K0VTvvqhySs03QK_ztOs,555
+adopt_export-0.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+adopt_export-0.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+adopt_export-0.3.0.dist-info/licenses/NOTICE,sha256=2_mgo6v6IM9fAn52L5-wXFpISnC6PVU_geTutoRhbWk,1897
+adopt_export-0.3.0.dist-info/RECORD,,

adopt_export-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

adopt_export-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

adopt_export-0.3.0.dist-info/licenses/NOTICE

@@ -0,0 +1,39 @@
+Adopt — Adoption-Phase Platform, shared substrate (`adopt-core`)
+Copyright 2026 The Adopt Authors
+
+This product includes software developed by The Adopt Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+--------------------------------------------------------------------------------
+Attribution note
+--------------------------------------------------------------------------------
+
+The copyright holder is recorded here as "The Adopt Authors" pending the legal
+entity name. The owner must settle that attribution before the 0.3.0 tag,
+because published package metadata cannot be changed retroactively for a
+release that has already left the machine. The product name itself is settled:
+handoff-index CR-50 keeps `Adopt` distinct from the `onboard` URI namespace.
+
+--------------------------------------------------------------------------------
+Third-party dependencies
+--------------------------------------------------------------------------------
+
+Every third-party dependency linked into this distribution is permissively
+licensed. The complete list, with licence hash, security status, usage mode,
+owner and re-verification date, is maintained in `licence-verifications.md` and
+enforced by `scripts/licence_gate.py`.
+
+Copyleft-licensed tools are invoked as subprocesses only and are never linked
+into this distribution. They are declared in `subprocess-deps.toml` together
+with their invocation sites.