texpkg 0.1.0__py3-none-any.whl

texpkg/_internal/payload.py

@@ -0,0 +1,118 @@
+"""A payload: the rendered `.sty` files and the assets a document needs, placed by a layout (A3, A6, P10, P11).
+
+It reads assets with `importlib.resources`, so a wheel, a zip and an editable install behave alike (P5); a file that is
+not a real one on disk (a zipped package) is copied out for as long as the write takes.
+"""
+
+import contextlib
+import dataclasses
+import importlib.resources
+import importlib.resources.abc
+import pathlib
+from collections.abc import Collection, Mapping, Sequence
+
+from texmodel import bundle, drift
+
+from ..assets import Resolved, Role
+from ..errors import DeclarationError, PayloadError
+from ..layout import Project
+
+
+@dataclasses.dataclass(frozen=True)
+class Placed:
+    """One asset at its place under the document directory."""
+
+    source: importlib.resources.abc.Traversable
+    dest: pathlib.PurePosixPath
+    why: str
+    origin: str  # the asset's declared path, for messages
+
+
+@dataclasses.dataclass(frozen=True)
+class Payload:
+    generated: Mapping[str, str]  # dest -> text: the rendered `.sty` files
+    assets: tuple[Placed, ...]
+
+    def absent(self) -> tuple[Placed, ...]:
+        return tuple(p for p in self.assets if not p.source.is_file())
+
+    def complete(self) -> None:
+        """Raise `PayloadError` unless every source file is there (A3)."""
+        if absent := self.absent():
+            names = ", ".join(str(p.dest) for p in absent)
+            raise PayloadError(
+                f"payload incomplete, missing sources for: {names}",
+                code="TP-A004",
+                hint="the package was built without them, or its files were removed",
+            )
+
+    def expected(self) -> dict[str, str | bytes]:
+        """Every file of the payload by destination, as bytes or text (A4 compares content, never time)."""
+        self.complete()
+        return {str(p.dest): p.source.read_bytes() for p in self.assets} | dict(self.generated)
+
+    def pending(self, root: pathlib.Path) -> tuple[str, ...]:
+        """The files `root` does not hold, byte for byte."""
+        return tuple(
+            dest
+            for dest, content in self.expected().items()
+            if not (root / dest).is_file()
+            or (root / dest).read_bytes() != (content if isinstance(content, bytes) else content.encode("utf-8"))
+        )
+
+    def check(self, root: pathlib.Path, owned: Sequence[str]) -> drift.Drift:
+        """What `root` holds against the payload: `stale`, `missing`, and `orphaned` (files under `owned` globs that no
+        payload file explains)."""
+        return drift.check_drift(self.expected(), root, owned)
+
+    def write(self, root: pathlib.Path) -> tuple[pathlib.Path, ...]:
+        """The files `root` does not hold already, byte for byte. Refuses the whole payload if one source is absent
+        (A3) and removes nothing."""
+        self.complete()
+        with contextlib.ExitStack() as stack:
+            items = [
+                bundle.Item(
+                    stack.enter_context(importlib.resources.as_file(p.source)), pathlib.Path(*p.dest.parts), p.why
+                )
+                for p in self.assets
+            ]
+            changed = {
+                dest: text
+                for dest, text in self.generated.items()
+                if not (root / dest).is_file() or (root / dest).read_text(encoding="utf-8") != text
+            }
+            return bundle.write(bundle.stale(items, root), root, changed)
+
+
+def build(
+    sty: Mapping[str, str], assets: Sequence[Resolved], layout: Project, kinds: Collection[str] | None = None
+) -> Payload:
+    """The payload of a document of `kinds` (a kind and the base kind a profile kind expands to; `None`: every kind, for
+    an export) in `layout`. An asset naming other kinds is left out
+    (A6). The same file twice is one (P10); two different files on one path are an error (P11)."""
+    placed: dict[pathlib.PurePosixPath, Placed] = {}
+    for resolved in assets:
+        asset = resolved.asset
+        if not asset.needed_by(kinds):
+            continue
+        dest = layout.place(asset.role, pathlib.PurePosixPath(asset.path))
+        earlier = placed.get(dest)
+        if earlier is not None:
+            if earlier.source.read_bytes() != resolved.source.read_bytes():
+                raise DeclarationError(
+                    f"two different files would be written to {dest}: {earlier.origin!r} and {asset.path!r}",
+                    code="TP-A002",
+                    path=asset.path,
+                    hint="rename one, or give one role/layout another place",
+                )
+            continue
+        placed[dest] = Placed(resolved.source, dest, asset.why, asset.path)
+    generated = {str(layout.place(Role.PACKAGE, pathlib.PurePosixPath(name))): text for name, text in sty.items()}
+    if clash := sorted(set(generated) & {str(d) for d in placed}):
+        raise DeclarationError(
+            f"{clash[0]} is both a generated .sty and an asset",
+            code="TP-A002",
+            path=clash[0],
+            hint="a package's name is the name of its rendered .sty",
+        )
+    return Payload(generated, tuple(placed.values()))

texpkg/_internal/provenance_tex.py

@@ -0,0 +1,65 @@
+"""The TeX of provenance (V2, V34): written to move into texmodel (N5, V9), so it imports nothing of texpkg.
+
+A package declares `\\<prefix>ProvenanceInfo`, which says what it is and, once a provenance file has been written beside
+the document, which stamp and time it was materialised with. The file renews two macros and adds the same text to the
+PDF's Info dictionary when PDF management is active.
+"""
+
+import re
+import textwrap
+
+STAMP = re.compile(r"[A-Za-z0-9.+:/@ -]*")  # text that is the same in TeX, in a PDF string and on the page
+TIME = re.compile(r"\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ")
+
+
+def file_name(package: str) -> str:
+    return f"{package}-provenance.sty"
+
+
+def info(package: str, version: str, stamp: str, time: str) -> str:
+    """The text `\\<prefix>ProvenanceInfo` prints, parts that are empty left out."""
+    return f"{package} {version}" + (f", stamp {stamp}" if stamp else "") + (f", materialised {time}" if time else "")
+
+
+def declarations(prefix: str, package: str, version: str) -> str:
+    """The block a package's `.sty` carries: both parts empty, the command that composes them, the file read if there.
+    Declared with `\\def`, not `\\newcommand`, which makes a `\\long` macro: `\\ifx` against `\\@empty` never holds."""
+    return textwrap.dedent(
+        rf"""
+        \makeatletter
+        \def\{prefix}ProvenanceStamp{{}}
+        \def\{prefix}ProvenanceTime{{}}
+        \newcommand{{\{prefix}ProvenanceInfo}}{{%
+          {package} {version}%
+          \ifx\{prefix}ProvenanceStamp\@empty\else, stamp \{prefix}ProvenanceStamp\fi
+          \ifx\{prefix}ProvenanceTime\@empty\else, materialised \{prefix}ProvenanceTime\fi}}
+        \InputIfFileExists{{{file_name(package)}}}{{}}{{}}
+        \makeatother
+        """
+    ).strip()
+
+
+def companion(prefix: str, package: str, version: str, stamp: str, time: str) -> str:
+    """The provenance file: it renews the stamp and the time, and adds the text to the PDF's Info dictionary as
+    `/<Prefix>Provenance` when PDF management is active (without it the entry is skipped)."""
+    text = info(package, version, stamp, time)
+    key = prefix.capitalize() + "Provenance"
+    return textwrap.dedent(
+        rf"""
+        % {package}: what this directory was materialised from. Generated; do not edit.
+        \def\{prefix}ProvenanceStamp{{{stamp}}}
+        \def\{prefix}ProvenanceTime{{{time}}}
+        \ifdefined\IfPDFManagementActiveTF
+          \IfPDFManagementActiveTF
+            {{\csname pdfmanagement_add:nnn\endcsname{{Info}}{{{key}}}{{(\detokenize{{{text}}})}}}}
+            {{}}
+        \fi
+        """
+    ).lstrip("\n")
+
+
+def read(text: str, prefix: str) -> tuple[str, str]:
+    """The stamp and the time a provenance file holds, or two empty strings if it holds none."""
+    stamp = re.search(rf"^\\def\\{prefix}ProvenanceStamp\{{(.*)\}}$", text, re.MULTILINE)
+    time = re.search(rf"^\\def\\{prefix}ProvenanceTime\{{(.*)\}}$", text, re.MULTILINE)
+    return (stamp[1] if stamp else "", time[1] if time else "")

texpkg/_internal/release.py

@@ -0,0 +1,257 @@
+"""A distribution bound to a release: what a built module's functions call (P7).
+
+texpkg adds no document logic of its own: rendering is texmodel's `Package.plan`, given the kind's settings and the
+layout's preamble lines.
+"""
+
+import dataclasses
+import datetime
+import importlib.resources.abc
+import json
+import pathlib
+from collections.abc import Mapping, Sequence
+from typing import Any, cast
+
+from texmodel.components import AnyValue, Command, Environment, Node
+from texmodel.package import setting_line
+from texmodel.plan import Plan
+
+from .. import provenance
+from ..assets import Role
+from ..contracts import Changes, Contracts
+from ..declaration import Distribution, Kind
+from ..document import Document
+from ..errors import (
+    DeclarationError,
+    DocumentExistsError,
+    KindMismatchError,
+    NewerDataError,
+    NotADocumentError,
+)
+from ..migration import DefaultChange, Migration
+from . import directory, export, payload, snapshots, state
+from .adopt import adopt
+from .envelope import Envelope, dumps
+
+
+@dataclasses.dataclass(frozen=True)
+class Release:
+    """A distribution at the release it was built as. `sty` holds the `.sty` of every package in the chain, as the build
+    rendered them (P4): what is shipped is what `save` writes. `bases` are the releases embedded in it (P13)."""
+
+    dist: Distribution
+    version: str
+    contracts: Contracts
+    sty: Mapping[str, str]
+    bases: tuple["Release", ...] = ()
+    snapshots: importlib.resources.abc.Traversable | None = None  # `_contracts`: the frozen snapshots a wheel carries
+
+    def releases(self) -> tuple["Release", ...]:
+        """This release and the ones embedded in it, this one first."""
+        return (self, *(r for base in self.bases for r in base.releases()))
+
+    def stack(self) -> list[dict[str, Any]]:
+        """The packages a document is rendered through, this one first (V18)."""
+        return [
+            {"package": r.dist.name, "release": r.version, "output": list(dataclasses.astuple(r.contracts.output))}
+            for r in self.releases()
+        ]
+
+    def layout_path(self, name: str) -> str:
+        """Where the layout puts the package file `name` in a document directory."""
+        return str(self.dist.layout.place(Role.PACKAGE, pathlib.PurePosixPath(name)))
+
+    def settings(self, kind: Kind, variant: str | None) -> tuple[AnyValue, ...]:
+        """What a document of `kind` is written with (L8): for a profile kind, the base kind's presets first, then
+        its own locks, then the variant's."""
+        base = self.dist.base_kind(kind)
+        return (*(base.presets if base else ()), *kind.settings(variant))
+
+    def plan(self, kind: Kind, tree: Node, variant: str | None) -> Plan:
+        """The `.tex` of `tree` as lines with provenance: the kind's presets, then the variant's settings (L8).
+
+        An exposed base kind is written by the base's package; the directory's layout is this distribution's."""
+        body = tree if kind.expand is None else kind.expand(tree)
+        package = self.dist.owner(kind.name).package
+        return package.plan(body, settings=self.settings(kind, variant), preamble=self.dist.layout.preamble())
+
+    def export(
+        self, destination: pathlib.Path | str, now: datetime.datetime | None, stamp: str | None
+    ) -> tuple[pathlib.Path, ...]:
+        """Write the whole payload in the layout, the provenance files, and a template and a README per kind (E1).
+        Refused whole if a file is missing (A3)."""
+        root = pathlib.Path(destination)
+        wanted = provenance.stamp_of(stamp, self)
+        files = provenance.files(self, wanted, provenance.time_of(now))
+        everything = payload.build({**self.sty, **files}, tuple(self.dist.resolved_assets()), self.dist.layout, None)
+        everything.complete()
+        names = sorted(everything.expected())
+        texts: dict[str, str] = {}
+        for kind in self.dist.kinds_offered():
+            texts[export.template_name(kind)] = self.plan(kind, kind.example(), None).text
+        listing = [*names, *texts, *(export.readme_name(k) for k in self.dist.kinds_offered())]
+        for kind in self.dist.kinds_offered():
+            texts[export.readme_name(kind)] = export.readme(self.dist, kind, self.version, sorted(listing))
+        everything.write(root)
+        directory.write(root, directory.differing(root, texts))
+        return tuple(root / name for name in sorted(listing))
+
+    def payload(self, kind: Kind, provenance: Mapping[str, str] | None = None) -> payload.Payload:
+        """The payload of a document of `kind`: the `.sty` files, the provenance files if given, the assets."""
+        kinds = (kind.name, *([kind.over] if kind.over else []))
+        files = {**self.sty, **(provenance or {})}
+        return payload.build(files, tuple(self.dist.resolved_assets()), self.dist.layout, kinds)
+
+    def rendered(self, kind: Kind, tree: Node) -> dict[str, str]:
+        """Every `.tex` of the kind with the plan of it that `save` keeps (D7), by path in the directory."""
+        files: dict[str, str] = {}
+        for variant, name in kind.documents():
+            plan = self.plan(kind, tree, variant)
+            files |= {name: plan.text, directory.plan_file(variant): plan.to_json()}
+        return files
+
+    def template(self, kind: Kind) -> dict[str, Any]:
+        """The package as a document of `kind` meets it (D6): the settings each `.tex` is written with, the defaults the
+        kind's classes have, the `.sty` by hash, and the stack (V18). Not the design file."""
+        c = self.contracts
+        return {
+            "package": self.dist.name,
+            "release": self.version,
+            "contracts": {
+                "data": [c.data.current, c.data.revision, c.data.age],
+                "interface": [c.interface.current, c.interface.revision, c.interface.age],
+                "output": [c.output.current, c.output.revision],
+            },
+            "settings": {
+                name: {type(v).__name__: setting_line(v) for v in self.settings(kind, variant)}
+                for variant, name in kind.documents()
+            },
+            "defaults": state.defaults_table(kind.model),
+            "sty": state.sty_hashes(self.sty),
+            "stack": self.stack(),
+        }
+
+    def states(self, kind: Kind, tree: Node) -> dict[str, str]:
+        """The pair of states `save` and `create` write (D1)."""
+        envelope = Envelope(self.dist.name, kind.name, self.contracts.data.current, state.tree_state(tree))
+        return {directory.STATE: envelope.to_text(), directory.TEMPLATE: dumps(self.template(kind))}
+
+    def read(self, path: pathlib.Path) -> Envelope:
+        """The envelope of the document in `path`, refused if it is another package's or not readable (K3)."""
+        text = directory.read(path, directory.STATE)
+        if text is None:
+            raise NotADocumentError(
+                f"{path}: no document here (no {directory.STATE})",
+                code="TP-D001",
+                path=str(path),
+                hint="create one with a kind's create, or point at the directory that holds it",
+            )
+        envelope = Envelope.parse(text, str(path / directory.STATE))
+        if envelope.package != self.dist.name:
+            raise KindMismatchError(
+                f"{path} holds a document of package {envelope.package!r}, not {self.dist.name!r}",
+                found=f"{envelope.package}:{envelope.kind}",
+                expected=self.dist.name,
+                path=str(path),
+            )
+        current = self.contracts.data.current
+        if envelope.data > current:
+            raise NewerDataError(
+                f"{path} was written for `data` version {envelope.data}, this release reads {current}",
+                code="TP-D004",
+                path=str(path),
+                hint="install the release that wrote it, or a newer one",
+            )
+        return envelope
+
+    def load(
+        self,
+        path: pathlib.Path | str,
+        migrations: Sequence[Migration] = (),
+        default_changes: DefaultChange | Mapping[str, DefaultChange] = DefaultChange.FOLLOW,
+    ) -> "Document[Any]":
+        """The document in `path`, whatever its kind (the generic `load`, P26)."""
+        envelope = self.read(pathlib.Path(path))
+        return self.kind_of(envelope).load(path, migrations, default_changes)
+
+    def kind_of(self, envelope: Envelope) -> "KindApi[Any]":
+        kind = self.dist.kind(envelope.kind)
+        return KindApi(self, kind, kind.model)
+
+    def kind[T: Command | Environment](self, name: str, model: type[T]) -> "KindApi[T]":
+        return KindApi(self, self.dist.kind(name), model)
+
+
+class KindApi[T: Command | Environment]:
+    """What a kind module's functions call."""
+
+    def __init__(self, release: Release, kind: Kind, model: type[T]) -> None:
+        if kind.model is not model:
+            raise DeclarationError(
+                f"kind {kind.name}: the module was generated for {model.__name__}, "
+                f"the declaration has {kind.model.__name__}",
+                code="TP-B001",
+                path=kind.name,
+                hint="build the package again",
+            )
+        self.release, self.kind = release, kind
+
+    def create(self, path: pathlib.Path | str, tree: T) -> Document[T]:
+        """A document in `path` (made if need be) with both states written; refuses a directory that holds one."""
+        path = pathlib.Path(path)
+        if (path / directory.STATE).exists():
+            raise DocumentExistsError(
+                f"{path} already holds a document",
+                code="TP-D002",
+                path=str(path),
+                hint="load it, or choose another directory",
+            )
+        if problems := tree.violations():
+            raise ExceptionGroup("invalid document", [v.error() for v in problems])
+        directory.write(path, self.release.states(self.kind, tree))
+        return Document(tree, path, self.release, self.kind)
+
+    def load(
+        self,
+        path: pathlib.Path | str,
+        migrations: Sequence[Migration] = (),
+        default_changes: DefaultChange | Mapping[str, DefaultChange] = DefaultChange.FOLLOW,
+    ) -> Document[T]:
+        """The document in `path`, adopted whole or not at all; writes nothing (D3). Refuses another kind's.
+
+        Older data runs through the kind's migrations and the consumer's `migrations` (V32); `default_changes` says what
+        happens to a value still marked as a default whose default this release changed (V23)."""
+        path = pathlib.Path(path)
+        envelope = self.release.read(path)
+        if envelope.kind != self.kind.name:
+            raise KindMismatchError(
+                f"{path} holds a {envelope.kind!r} document, not a {self.kind.name!r} one",
+                found=envelope.kind,
+                expected=self.kind.name,
+                path=str(path),
+            )
+        saved = directory.read(path, directory.TEMPLATE)
+        template: dict[str, Any] = json.loads(saved) if saved else {}
+        tree = adopt(
+            kind=self.kind,
+            envelope=envelope,
+            current=self.release.contracts.data.current,
+            age=self.release.contracts.data.age,
+            consumer=migrations,
+            policy=default_changes,
+            saved_defaults=template.get("defaults"),
+            base_data=dict(self.release.contracts.base_data) if self.kind.name in self.release.dist.expose else None,
+        )
+        return Document(cast("T", tree), path, self.release, self.kind)
+
+    def schema(self, mode: state.Mode) -> dict[str, Any]:
+        return state.schema(self.kind.model, mode)
+
+    def example(self) -> T:
+        return cast("T", self.kind.example())
+
+    def variants(self) -> tuple[str, ...]:
+        return tuple(v.name for v in self.kind.variants)
+
+    def changes(self, old: int, new: int) -> Changes:
+        return snapshots.changes(self.release.snapshots, self.kind.name, old, new)

texpkg/_internal/snapshots.py

@@ -0,0 +1,61 @@
+"""The contract snapshots a wheel ships (V11, V33, V37), read at run time: what changed between two `data` versions."""
+
+import importlib.resources.abc
+import json
+import re
+
+from ..contracts import Changes
+from . import classify
+from .versions import Versions
+
+_RELEASE = re.compile(r"\d+\.\d+\.\d+")
+VERSIONS = "versions.toml"
+
+
+def releases(root: importlib.resources.abc.Traversable | None) -> list[str]:
+    """The frozen releases a wheel carries, oldest first."""
+    found = (
+        [p.name for p in root.iterdir() if p.is_dir() and _RELEASE.fullmatch(p.name)] if root and root.is_dir() else []
+    )
+    return sorted(found, key=classify.parse_version)
+
+
+def changes(root: importlib.resources.abc.Traversable | None, kind: str, old: int, new: int) -> Changes:
+    """What changed in `kind` between `data` versions `old` and `new`: fields added, removed and tightened, the author's
+    notes and the release of each version crossed (V33), read from the shipped snapshots. Empty where there are none."""
+    held = releases(root)
+    if root is None or not held:
+        return Changes()
+    latest = Versions.parse(root.joinpath(held[-1], VERSIONS).read_text(encoding="utf-8"))
+    crossed = range(old + 1, new + 1)
+    out = Changes(
+        notes=tuple(latest.notes[v] for v in crossed if latest.notes.get(v)),
+        releases={v: latest.releases[v] for v in crossed if v in latest.releases},
+    )
+    first, last = latest.releases.get(old), latest.releases.get(new)
+    name = f"kinds/{kind}.input.schema.json"
+    if (
+        not first
+        or not last
+        or first == last
+        or not (root.joinpath(first, *name.split("/")).is_file() and root.joinpath(last, *name.split("/")).is_file())
+    ):
+        return out
+    before = json.loads(root.joinpath(first, *name.split("/")).read_text(encoding="utf-8"))
+    after = json.loads(root.joinpath(last, *name.split("/")).read_text(encoding="utf-8"))
+    found = classify.schema_changes(before, after)
+    gone = {"removed", "no longer part of the kind"}
+    added = [c.where for c in found if c.what.startswith("added") or c.what.endswith("added to the kind")]
+    removed = [c.where for c in found if c.what in gone]
+    tightened = [
+        c.where
+        for c in found
+        if c.level is classify.Level.BREAKING and c.what not in gone and not c.what.startswith("added")
+    ]
+    return Changes(
+        added=tuple(dict.fromkeys(added)),
+        removed=tuple(dict.fromkeys(removed)),
+        tightened=tuple(dict.fromkeys(tightened)),
+        notes=out.notes,
+        releases=out.releases,
+    )

texpkg/_internal/state.py

@@ -0,0 +1,113 @@
+"""The stored form of a document: its schemas (V26).
+
+Two schemas per kind, from pydantic's two modes: the input one (a field with a default is optional) and the stored one
+(every field is written, V21, so every field is required, and a node lists the fields that hold defaults in
+`$defaults`).
+"""
+
+import copy
+import hashlib
+from collections.abc import Mapping
+from typing import Any, Literal
+
+from texmodel import spec
+from texmodel.body import Comment
+from texmodel.components import Command, Environment, Node, Passthrough
+
+from ..declaration import Model
+from ..errors import DeclarationError
+
+type Mode = Literal["validation", "serialization"]
+
+DEFAULTS = "$defaults"  # V24: the fields of a node that hold the package's defaults
+
+
+def stored(validation: dict[str, Any]) -> dict[str, Any]:
+    """The stored schema of an input schema: every property required, `$defaults` limited to the node's own defaulted
+    fields (V27)."""
+    out = copy.deepcopy(validation)
+    for node in (out, *out.get("$defs", {}).values()):
+        properties: dict[str, Any] | None = node.get("properties")
+        if not properties:
+            continue
+        defaulted = sorted(name for name, schema in properties.items() if "default" in schema)
+        node["required"] = sorted(properties)
+        properties[DEFAULTS] = (
+            {"type": "array", "items": {"enum": defaulted}, "uniqueItems": True}
+            if defaulted
+            else {"type": "array", "maxItems": 0}
+        )
+    return out
+
+
+def schema(model: Model, mode: Mode) -> dict[str, Any]:
+    """The JSON Schema of the data a kind's `model` takes (`validation`) or stores (`serialization`)."""
+    if mode not in ("validation", "serialization"):
+        raise DeclarationError(
+            f"schema mode {mode!r}", code="TP-K008", hint='use "validation" (the input) or "serialization" (the stored)'
+        )
+    validation = spec.json_schema(model)
+    return validation if mode == "validation" else stored(validation)
+
+
+def _fields(node: Command | Environment | Passthrough) -> dict[str, Any]:
+    return node.model_dump(mode="json", exclude={"content"})
+
+
+def tree_state(node: Node) -> dict[str, Any]:
+    """The state of a tree: every value written (V21), and for each node the fields that hold the package's defaults in
+    `$defaults` (V24), known from `model_fields_set`, which says what the caller passed (V25)."""
+    if isinstance(node, Comment):
+        return {"type": type(node).__name__} | {f: getattr(node, f) for f in node.__tm_fields__}
+    if isinstance(node, Passthrough):
+        return {"type": "Passthrough"} | _fields(node)
+    fields = _fields(node)
+    out: dict[str, Any] = {"type": type(node).__name__} | fields
+    if defaulted := [name for name in fields if name not in node.model_fields_set]:
+        out[DEFAULTS] = defaulted
+    if isinstance(node, Environment):
+        out["content"] = [tree_state(child) for child in node.content]
+    return out
+
+
+def given(state: dict[str, Any]) -> dict[str, Any]:
+    """`state` as the caller would have passed it: the fields marked as defaults left out, so the model fills them with
+    its current defaults and `model_fields_set` is what the author set (V27)."""
+    out = {k: v for k, v in state.items() if k not in (DEFAULTS, *state.get(DEFAULTS, ()))}
+    if "content" in out:
+        out["content"] = [given(child) for child in out["content"]]
+    return out
+
+
+def tree_from_state(model: Model, state: dict[str, Any]) -> Node:
+    """The tree a stored state describes; raises an `ExceptionGroup` of texmodel `ValidationError` for one that does not
+    fit the model."""
+    return spec.from_dict(model, given(state))
+
+
+def default_paths(node: Node, path: str = "") -> tuple[str, ...]:
+    """The data paths of the fields that hold defaults (`/content/1/accent`), in document order."""
+    if isinstance(node, Comment):
+        return ()
+    own = tuple(f"{path}/{name}" for name in _fields(node) if name not in node.model_fields_set)
+    if isinstance(node, Environment):
+        return own + tuple(
+            p for i, child in enumerate(node.content) for p in default_paths(child, f"{path}/content/{i}")
+        )
+    return own
+
+
+def defaults_table(model: Model) -> dict[str, Any]:
+    """The defaults of the classes a kind's trees are made of, by `Class.field`: what the package would fill in."""
+    validation = spec.json_schema(model)
+    table: dict[str, Any] = {}
+    for node in (validation, *validation.get("$defs", {}).values()):
+        for name, schema in node.get("properties", {}).items():
+            if "default" in schema:
+                table[f"{node['title']}.{name}"] = schema["default"]
+    return dict(sorted(table.items()))
+
+
+def sty_hashes(sty: Mapping[str, str]) -> dict[str, str]:
+    """The `.sty` files the template state records by hash, not by value (D6)."""
+    return {name: hashlib.sha256(text.encode("utf-8")).hexdigest() for name, text in sorted(sty.items())}

texpkg/_internal/versions.py

@@ -0,0 +1,61 @@
+"""The versions file of a contract snapshot (V36): the triples, the release they are for, the author's statements
+and the version maps. A snapshot ships in the wheel, so the run time reads it too."""
+
+import dataclasses
+import json
+import tomllib
+from collections.abc import Mapping
+from typing import Any
+
+from ..contracts import Contracts, Pair, Triple
+
+
+@dataclasses.dataclass(frozen=True)
+class Versions:
+    """The versions file (V36): the triples, the release they are for, the author's statements and the version maps."""
+
+    release: str
+    data: Triple = Triple(1)
+    interface: Triple = Triple(1)
+    output: Pair = Pair(1)
+    output_change: str = ""  # the author's `current` or `revision` for an output change (V12)
+    notes: Mapping[int, str] = dataclasses.field(default_factory=dict[int, str])  # one line per `data` version (V33)
+    releases: Mapping[int, str] = dataclasses.field(default_factory=dict[int, str])  # the release of each (V33)
+    base_data: Mapping[int, int] = dataclasses.field(default_factory=dict[int, int])  # own `data` -> the base's (P30)
+    base_interface: int = 0  # the base `interface` current relied on (V17); 0 without a base
+
+    def contracts(self) -> Contracts:
+        return Contracts(self.data, self.interface, self.output, tuple(sorted(self.base_data.items())))
+
+    def to_text(self) -> str:
+        def table(name: str, values: Mapping[int, Any]) -> str:
+            return f"\n[{name}]\n" + "".join(f'"{k}" = {json.dumps(v)}\n' for k, v in sorted(values.items()))
+
+        return (
+            f'release = "{self.release}"\n'
+            f"\n[data]\ncurrent = {self.data.current}\nrevision = {self.data.revision}\nage = {self.data.age}\n"
+            f"\n[interface]\ncurrent = {self.interface.current}\nrevision = {self.interface.revision}\n"
+            f"age = {self.interface.age}\n"
+            f"\n[output]\ncurrent = {self.output.current}\nrevision = {self.output.revision}\n"
+            f'change = "{self.output_change}"\n'
+            + table("notes", self.notes)
+            + table("releases", self.releases)
+            + f"\n[base]\ninterface = {self.base_interface}\n"
+            + table("base.data", self.base_data)
+        )
+
+    @classmethod
+    def parse(cls, text: str) -> "Versions":
+        found = tomllib.loads(text)
+        data, interface, output = found["data"], found["interface"], found["output"]
+        return cls(
+            found["release"],
+            Triple(data["current"], data["revision"], data["age"]),
+            Triple(interface["current"], interface["revision"], interface["age"]),
+            Pair(output["current"], output["revision"]),
+            output.get("change", ""),
+            {int(k): v for k, v in found.get("notes", {}).items()},
+            {int(k): v for k, v in found.get("releases", {}).items()},
+            {int(k): v for k, v in found.get("base", {}).get("data", {}).items()},
+            found.get("base", {}).get("interface", 0),
+        )