agent2learn 0.1.2__py3-none-any.whl

agent2learn/vault.py

@@ -0,0 +1,1134 @@
+"""Portable vault state, structured manifests, and revision-safe storage.
+
+The manifest is the source of truth for course identity and provenance.  It stores only
+vault-relative POSIX paths, and every path is resolved against the current vault root when it is
+used.  A filename or display title is never treated as a source identity.
+
+Revision preservation is deliberately a separate operation from installing a new source.  The
+caller verifies and preserves the old revision first, then performs its own atomic materialized
+file replacement and manifest update.  This keeps a failed history write from pretending that a
+revision was safely archived.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import stat
+import subprocess
+import sys
+import tempfile
+import unicodedata
+from collections.abc import Callable, Collection, Mapping
+from contextlib import suppress
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from hashlib import sha256
+from pathlib import Path, PurePosixPath
+from typing import Any, BinaryIO, cast
+
+from agent2learn import paths
+from agent2learn.errors import A2LError
+
+SCHEMA_VERSION = 1
+MIGRATIONS: dict[int, Callable[[Vault], None]] = {}
+
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+_WINDOWS_ABSOLUTE = re.compile(r"^[A-Za-z]:[\\/]")
+_KEY_PART = re.compile(r"^[^:\\/:\s]+$")
+_MANIFEST_KEYS = frozenset(
+    {"path", "sha256", "source_id", "etag", "last_modified", "size", "fetched_at", "derived"}
+)
+_DERIVED_REQUIRED_KEYS = frozenset(
+    {"path", "sha256", "source_sha256", "tool", "tool_version", "created_at"}
+)
+_DERIVED_OPTIONAL_KEYS = frozenset({"ocr_words_per_page", "page_coverage"})
+_DERIVED_KEYS = _DERIVED_REQUIRED_KEYS | _DERIVED_OPTIONAL_KEYS
+_GIT_CONFIRMATION = "I UNDERSTAND THIS VAULT IS IN A GIT WORKTREE"
+_COPY_CHUNK_SIZE = 1024 * 1024
+
+
+@dataclass(frozen=True)
+class DerivedArtifact:
+    """A generated artifact tied to one exact source revision."""
+
+    path: str
+    sha256: str
+    source_sha256: str
+    tool: str
+    tool_version: str
+    created_at: str
+    ocr_words_per_page: int | None = None
+    page_coverage: tuple[Mapping[str, object], ...] = ()
+
+
+@dataclass(frozen=True)
+class ManifestEntry:
+    """A structured record for one stable remote source identity."""
+
+    path: str
+    sha256: str
+    source_id: str
+    etag: str | None
+    last_modified: str | None
+    size: int
+    fetched_at: str
+    derived: Mapping[str, DerivedArtifact] = field(default_factory=dict)
+
+
+class Vault:
+    """Access a portable Agent2Learn vault rooted at ``root``."""
+
+    root: Path
+    _entries: dict[str, ManifestEntry]
+    _loaded: bool
+    _state_override: Path | None
+    _schema_migration_active: bool
+
+    def __init__(self, root: Path) -> None:
+        self.root = Path(root).expanduser().resolve()
+        self._entries = {}
+        self._loaded = False
+        self._state_override = None
+        self._schema_migration_active = False
+
+    def state(self) -> Path:
+        """Return the vault-scoped state directory."""
+
+        state = self._state_override if self._state_override is not None else self.root / ".a2l"
+        if paths.is_link(state):
+            raise A2LError("vault state directory must not be a symlink")
+        return state
+
+    def history_bucket(self, source_key: str) -> Path:
+        """Return and create the opaque history bucket for a canonical source key."""
+
+        _validate_source_key(source_key)
+        check_schema(self)
+        bucket = self.state() / "history" / sha256(source_key.encode("utf-8")).hexdigest()
+        paths.ensure_dir(bucket, root=self.root)
+        return bucket
+
+    def manifest(self) -> dict[str, ManifestEntry]:
+        """Load, validate, and return a copy of the structured manifest."""
+
+        check_schema(self)
+        if self._loaded:
+            return dict(self._entries)
+
+        destination = self.state() / "manifest.json"
+        if paths.is_link(destination):
+            raise A2LError("manifest must not be a symlink")
+        raw = _read_json_object(destination, "manifest")
+        if raw is None:
+            self._entries = {}
+            self._loaded = True
+            return {}
+        schema_version = raw.get("schema_version")
+        if isinstance(schema_version, bool) or not isinstance(schema_version, int):
+            raise A2LError("manifest schema_version must be an integer")
+        if schema_version != SCHEMA_VERSION:
+            raise A2LError(
+                f"manifest schema version {schema_version} does not match tool schema "
+                f"{SCHEMA_VERSION}"
+            )
+
+        entries_raw = raw.get("entries")
+        if not isinstance(entries_raw, dict):
+            raise A2LError("manifest entries must be an object")
+
+        entries: dict[str, ManifestEntry] = {}
+        for key, raw_entry in entries_raw.items():
+            if not isinstance(key, str):
+                raise A2LError("manifest entry keys must be canonical source keys")
+            entries[key] = _entry_from_json(key, raw_entry)
+
+        unknown = set(raw) - {"schema_version", "entries"}
+        if unknown:
+            raise A2LError(f"manifest contains unknown top-level fields: {sorted(unknown)!r}")
+
+        self._entries = entries
+        self._loaded = True
+        return dict(entries)
+
+    def entry(self, key: str) -> ManifestEntry | None:
+        """Return one manifest entry by canonical source key."""
+
+        _validate_source_key(key)
+        return self.manifest().get(key)
+
+    def materialized(self, entry: ManifestEntry) -> Path:
+        """Resolve a validated manifest path against this vault's current root."""
+
+        validated = _validate_entry(entry)
+        return self._materialized_path(validated.path)
+
+    def owns_derived_path(self, key: str, relative: str, *, name: str = "markdown") -> bool:
+        entries = self.manifest()
+        entry = entries.get(key)
+        artifact = entry.derived.get(name) if entry is not None else None
+        if artifact is None or artifact.path != relative:
+            return False
+        wanted = unicodedata.normalize("NFC", relative).casefold()
+        for source_key, source in entries.items():
+            if unicodedata.normalize("NFC", source.path).casefold() == wanted:
+                return False
+            for artifact_name, other in source.derived.items():
+                if (source_key, artifact_name) != (key, name) and (
+                    unicodedata.normalize("NFC", other.path).casefold() == wanted
+                ):
+                    return False
+        return True
+
+    def derived_destination(self, key: str, preferred: Path, *, name: str = "markdown") -> Path:
+        _validate_source_key(key)
+        entries = self.manifest()
+        entry = entries.get(key)
+        artifact = entry.derived.get(name) if entry is not None else None
+        if artifact is not None and self.owns_derived_path(key, artifact.path, name=name):
+            return self._materialized_path(artifact.path)
+        if paths.has_link_component(preferred.parent, root=self.root):
+            raise A2LError("derived destination is outside the trusted vault")
+        return paths.unique_path(preferred, reserved=self.claimed_paths())
+
+    def claimed_paths(self) -> tuple[Path, ...]:
+        return tuple(
+            self.root / PurePosixPath(relative)
+            for source in self.manifest().values()
+            for relative in (source.path, *(value.path for value in source.derived.values()))
+        )
+
+    def mark(self, key: str, entry: ManifestEntry) -> None:
+        """Validate and stage a manifest entry for the next atomic save."""
+
+        _validate_source_key(key)
+        if not self._loaded:
+            self.manifest()
+        checked = _validate_entry(entry)
+        _validate_source_id(key, checked.source_id)
+        self._entries[key] = checked
+
+    def preserve_revision(self, key: str, *, changed_at: datetime) -> Path | None:
+        """Atomically preserve the verified current source before replacing its bytes.
+
+        ``None`` means the source is not materialized yet.  A materialized source whose bytes no
+        longer match the manifest raises an integrity gap instead of inventing a revision from
+        untrusted local data.
+        """
+
+        _validate_source_key(key)
+        changed_utc = _utc_datetime(changed_at, "changed_at")
+        current = self.entry(key)
+        if current is None:
+            return None
+
+        source = self.materialized(current)
+        revision_source = _allocate_revision_directory(
+            self.history_bucket(key), changed_utc.strftime("%Y%m%dT%H%M%SZ"), root=self.root
+        )
+        try:
+            saved_source = revision_source / PurePosixPath(current.path).name
+            if not _copy_verified(
+                source,
+                saved_source,
+                root=self.root,
+                expected_sha256=current.sha256,
+                expected_size=current.size,
+            ):
+                paths.remove_tree(revision_source)
+                return None
+
+            derived_metadata: dict[str, dict[str, object]] = {}
+            for name, artifact in current.derived.items():
+                artifact_path = self._materialized_path(artifact.path)
+                artifact_destination = (
+                    revision_source / "derived" / PurePosixPath(artifact.path).name
+                )
+                if not _copy_verified(
+                    artifact_path,
+                    artifact_destination,
+                    root=self.root,
+                    expected_sha256=None,
+                    expected_size=None,
+                ):
+                    derived_metadata[name] = {
+                        "path": artifact.path,
+                        "sha256": artifact.sha256,
+                        "source_sha256": artifact.source_sha256,
+                        "tool": artifact.tool,
+                        "tool_version": artifact.tool_version,
+                        "created_at": artifact.created_at,
+                        "ocr_words_per_page": artifact.ocr_words_per_page,
+                        "page_coverage": [dict(page) for page in artifact.page_coverage],
+                        "status": "missing",
+                    }
+                    continue
+
+                actual_sha256, actual_size = _hash_file(artifact_path)
+                derived_metadata[name] = {
+                    "path": artifact.path,
+                    "sha256": artifact.sha256,
+                    "source_sha256": artifact.source_sha256,
+                    "tool": artifact.tool,
+                    "tool_version": artifact.tool_version,
+                    "created_at": artifact.created_at,
+                    "ocr_words_per_page": artifact.ocr_words_per_page,
+                    "page_coverage": [dict(page) for page in artifact.page_coverage],
+                    "actual_sha256": actual_sha256,
+                    "size": actual_size,
+                    "status": (
+                        "verified" if actual_sha256 == artifact.sha256 else "local-modification"
+                    ),
+                }
+
+            metadata = {
+                "canonical_key": key,
+                "fetched_at": current.fetched_at,
+                "new_sha256": None,
+                "old_sha256": current.sha256,
+                "path": current.path,
+                "preserved_at": changed_utc.isoformat().replace("+00:00", "Z"),
+                "size": current.size,
+                "source_key": key,
+                "derived": derived_metadata,
+            }
+            paths.atomic_write_text(
+                revision_source / "revision.json", _canonical_json(metadata), root=self.root
+            )
+            return saved_source
+        except BaseException:
+            paths.remove_tree(revision_source, ignore_errors=True)
+            raise
+
+    def save_manifest(self) -> None:
+        """Atomically save the canonical manifest and current schema marker."""
+
+        check_schema(self)
+        if not self._loaded:
+            self.manifest()
+
+        payload = {
+            "entries": {
+                key: _entry_to_json(_validate_source_entry(key, entry))
+                for key, entry in sorted(self._entries.items(), key=lambda item: item[0])
+            },
+            "schema_version": SCHEMA_VERSION,
+        }
+        paths.atomic_write_text(
+            self.state() / "manifest.json", _canonical_json(payload), root=self.root
+        )
+
+    def semesters(self) -> list[Path]:
+        """Return direct child term directories that carry semester metadata."""
+
+        if not paths.long_path(self.root).is_dir():
+            return []
+        children: list[Path] = []
+        with os.scandir(os.fspath(paths.long_path(self.root))) as iterator:
+            for entry in iterator:
+                child = self.root / entry.name
+                if entry.is_dir(follow_symlinks=False) and _regular_file_exists(
+                    child / "_SEMESTER_METADATA.json", "semester metadata"
+                ):
+                    children.append(child)
+        return sorted(children, key=lambda path: path.name)
+
+    @staticmethod
+    def is_vault(p: Path) -> bool:
+        """Return whether ``p`` has an Agent2Learn marker."""
+
+        candidate = Path(p)
+        state = candidate / ".a2l"
+        if paths.is_link(state):
+            return False
+        if paths.long_path(state).is_dir():
+            return True
+        try:
+            return _regular_file_exists(candidate / "_SEMESTER_METADATA.json", "semester metadata")
+        except A2LError:
+            return False
+
+    @classmethod
+    def claim(cls, p: Path, *, allow_suffix: bool = True) -> Path:
+        """Claim a vault root without adopting an unrelated directory.
+
+        ``allow_suffix=False`` is used by consentful onboarding after it has previewed a path.
+        A race that occupies that exact path must fail safely instead of silently moving the
+        user's approval to a newly allocated sibling.
+        """
+
+        if not isinstance(allow_suffix, bool):
+            raise ValueError("allow_suffix must be a boolean")
+
+        requested = Path(p).expanduser().resolve()
+        _refuse_agent2learn_checkout(requested)
+        _require_git_confirmation_if_needed(requested)
+
+        candidate = requested
+        suffix = 2
+        while True:
+            if cls.is_vault(candidate):
+                return candidate
+            if not _occupied(candidate):
+                try:
+                    paths.long_path(candidate).mkdir(parents=True, exist_ok=False)
+                except FileExistsError:
+                    if not allow_suffix:
+                        raise A2LError("vault path became occupied after confirmation") from None
+                    candidate = requested.with_name(f"{requested.name}-{suffix}")
+                    suffix += 1
+                    continue
+                _write_vault_gitignore(candidate)
+                paths.ensure_dir(candidate / ".a2l", root=candidate)
+                check_schema(cls(candidate))
+                return candidate
+            if not allow_suffix:
+                raise A2LError("vault path became occupied after confirmation")
+            candidate = requested.with_name(f"{requested.name}-{suffix}")
+            suffix += 1
+
+    def _materialized_path(self, relative: str) -> Path:
+        _validate_relative_posix(relative, field="path")
+        # Preserve the lexical path until the filesystem boundary.  Resolving first would erase
+        # an intermediate symlink and make a manifest entry capable of redirecting a managed
+        # writer outside the trusted vault (or into a linked directory within it).
+        candidate = self.root / Path(*PurePosixPath(relative).parts)
+        if paths.has_link_component(candidate, root=self.root):
+            raise A2LError("manifest path contains a link component")
+        try:
+            candidate.relative_to(self.root)
+        except ValueError as exc:
+            raise A2LError("manifest path escapes the vault root") from exc
+        return candidate
+
+
+def check_schema(v: Vault) -> None:
+    """Check or migrate a vault schema, refusing to write newer vaults."""
+
+    if v._schema_migration_active:
+        return
+
+    state = v.state()
+    paths.ensure_dir(state, root=v.root)
+    version_path = state / "VERSION"
+    if not _regular_file_exists(version_path, "vault VERSION"):
+        try:
+            with os.scandir(os.fspath(paths.long_path(state))) as iterator:
+                has_other_state = any(entry.name != "VERSION" for entry in iterator)
+        except OSError as exc:
+            raise A2LError("vault VERSION is unreadable") from exc
+        if has_other_state:
+            raise A2LError("vault VERSION is missing from an existing vault state")
+        paths.atomic_write_text(version_path, f"{SCHEMA_VERSION}\n", root=v.root)
+        return
+
+    raw_version = _read_text(version_path).strip()
+    try:
+        version = int(raw_version)
+    except ValueError as exc:
+        raise A2LError("vault VERSION must contain one integer") from exc
+    if version < 0 or str(version) != raw_version:
+        raise A2LError("vault VERSION must contain one non-negative integer")
+    if version == SCHEMA_VERSION:
+        return
+    if version > SCHEMA_VERSION:
+        raise A2LError(
+            f"vault schema {version} is newer than this tool's schema {SCHEMA_VERSION}; "
+            "run a2l upgrade"
+        )
+
+    backup = _backup_state(state, version, root=v.root)
+    staging_root = paths.plain_path(
+        Path(
+            tempfile.mkdtemp(
+                prefix=".a2l-migration-",
+                dir=os.fspath(paths.long_path(state.parent)),
+            )
+        )
+    )
+    staged_state = staging_root / ".a2l"
+    try:
+        _copy_tree(state, staged_state, root=v.root)
+        staged_vault = Vault(v.root)
+        staged_vault._state_override = staged_state
+        staged_vault._schema_migration_active = True
+
+        current = version
+        while current < SCHEMA_VERSION:
+            migration = MIGRATIONS.get(current)
+            if migration is None:
+                raise A2LError(
+                    f"vault schema {version} is older than {SCHEMA_VERSION} and has no "
+                    f"registered migration from {current}"
+                )
+            migration(staged_vault)
+            current += 1
+
+        paths.atomic_write_text(staged_state / "VERSION", f"{SCHEMA_VERSION}\n", root=v.root)
+        _install_migrated_state(state, staged_state, backup, root=v.root)
+    finally:
+        paths.remove_tree(staging_root, ignore_errors=True)
+
+
+def _entry_from_json(key: str, raw: object) -> ManifestEntry:
+    _validate_source_key(key)
+    if not isinstance(raw, dict):
+        raise A2LError(f"manifest entry for {key!r} must be an object")
+    unknown = set(raw) - _MANIFEST_KEYS
+    if unknown:
+        raise A2LError(f"manifest entry for {key!r} has unknown fields: {sorted(unknown)!r}")
+
+    required = _required_fields(raw, _MANIFEST_KEYS - {"derived"}, f"entry {key!r}")
+    source_id = _as_str(required["source_id"], "source_id")
+    _validate_source_id(key, source_id)
+
+    derived_raw = raw.get("derived", {})
+    if not isinstance(derived_raw, dict):
+        raise A2LError(f"derived artifacts for {key!r} must be an object")
+    derived: dict[str, DerivedArtifact] = {}
+    for name, artifact in derived_raw.items():
+        if not isinstance(name, str) or not name or "/" in name or "\\" in name:
+            raise A2LError("derived artifact names must be simple non-empty strings")
+        derived[name] = _artifact_from_json(name, artifact, required["sha256"])
+
+    return _validate_entry(
+        ManifestEntry(
+            path=_as_str(required["path"], "path"),
+            sha256=_as_str(required["sha256"], "sha256"),
+            source_id=source_id,
+            etag=_as_optional_str(required["etag"], "etag"),
+            last_modified=_as_optional_str(required["last_modified"], "last_modified"),
+            size=_as_nonnegative_int(required["size"], "size"),
+            fetched_at=_as_str(required["fetched_at"], "fetched_at"),
+            derived=derived,
+        )
+    )
+
+
+def _artifact_from_json(name: str, raw: object, source_sha256: object) -> DerivedArtifact:
+    if not isinstance(raw, dict):
+        raise A2LError(f"derived artifact {name!r} must be an object")
+    unknown = set(raw) - _DERIVED_KEYS
+    if unknown:
+        raise A2LError(f"derived artifact {name!r} has unknown fields: {sorted(unknown)!r}")
+    required = _required_fields(raw, _DERIVED_REQUIRED_KEYS, f"derived artifact {name!r}")
+    if required["source_sha256"] != source_sha256:
+        raise A2LError(f"derived artifact {name!r} source_sha256 does not match parent")
+    return _validate_artifact(
+        DerivedArtifact(
+            path=_as_str(required["path"], "derived path"),
+            sha256=_as_str(required["sha256"], "derived sha256"),
+            source_sha256=_as_str(required["source_sha256"], "source_sha256"),
+            tool=_as_str(required["tool"], "tool"),
+            tool_version=_as_str(required["tool_version"], "tool_version"),
+            created_at=_as_str(required["created_at"], "created_at"),
+            ocr_words_per_page=_as_optional_positive_int(
+                raw.get("ocr_words_per_page"), "ocr_words_per_page"
+            ),
+            page_coverage=_as_page_coverage(raw.get("page_coverage", ())),
+        )
+    )
+
+
+def _validate_entry(entry: ManifestEntry) -> ManifestEntry:
+    if not isinstance(entry, ManifestEntry):
+        raise A2LError("manifest entries must be ManifestEntry values")
+    _validate_relative_posix(entry.path, field="relative POSIX path")
+    _validate_hash(entry.sha256, "sha256")
+    if not isinstance(entry.source_id, str) or not entry.source_id:
+        raise A2LError("source_id must be a non-empty string")
+    if entry.etag is not None and not isinstance(entry.etag, str):
+        raise A2LError("etag must be a string or null")
+    if entry.last_modified is not None and not isinstance(entry.last_modified, str):
+        raise A2LError("last_modified must be a string or null")
+    if isinstance(entry.size, bool) or not isinstance(entry.size, int) or entry.size < 0:
+        raise A2LError("size must be a non-negative integer")
+    fetched_at = _manifest_timestamp(entry.fetched_at, "fetched_at")
+    derived: dict[str, DerivedArtifact] = {}
+    if not isinstance(entry.derived, Mapping):
+        raise A2LError("derived artifacts must be a mapping")
+    derived_paths: set[str] = set()
+    for name, artifact in entry.derived.items():
+        if not isinstance(name, str) or not name or "/" in name or "\\" in name:
+            raise A2LError("derived artifact names must be simple non-empty strings")
+        checked = _validate_artifact(artifact)
+        if checked.source_sha256 != entry.sha256:
+            raise A2LError(f"derived artifact {name!r} source_sha256 does not match parent")
+        if checked.path == entry.path:
+            raise A2LError(f"derived artifact {name!r} path must differ from source path")
+        if checked.path in derived_paths:
+            raise A2LError(f"derived artifact {name!r} duplicates another artifact path")
+        derived_paths.add(checked.path)
+        derived[name] = checked
+    return ManifestEntry(
+        path=entry.path,
+        sha256=entry.sha256,
+        source_id=entry.source_id,
+        etag=entry.etag,
+        last_modified=entry.last_modified,
+        size=entry.size,
+        fetched_at=fetched_at,
+        derived=derived,
+    )
+
+
+def _validate_source_entry(key: str, entry: ManifestEntry) -> ManifestEntry:
+    _validate_source_key(key)
+    checked = _validate_entry(entry)
+    _validate_source_id(key, checked.source_id)
+    return checked
+
+
+def _validate_source_id(key: str, source_id: str) -> None:
+    if source_id != key.rsplit(":", 1)[1]:
+        raise A2LError(f"source_id for {key!r} does not match its canonical entity ID")
+
+
+def _validate_artifact(artifact: DerivedArtifact) -> DerivedArtifact:
+    if not isinstance(artifact, DerivedArtifact):
+        raise A2LError("derived artifacts must be DerivedArtifact values")
+    _validate_relative_posix(artifact.path, field="derived relative POSIX path")
+    _validate_hash(artifact.sha256, "derived sha256")
+    _validate_hash(artifact.source_sha256, "source_sha256")
+    for field_name in ("tool", "tool_version"):
+        value = getattr(artifact, field_name)
+        if not isinstance(value, str) or not value:
+            raise A2LError(f"{field_name} must be a non-empty string")
+    ocr_words_per_page = _as_optional_positive_int(
+        artifact.ocr_words_per_page, "ocr_words_per_page"
+    )
+    page_coverage = _as_page_coverage(artifact.page_coverage)
+    return DerivedArtifact(
+        path=artifact.path,
+        sha256=artifact.sha256,
+        source_sha256=artifact.source_sha256,
+        tool=artifact.tool,
+        tool_version=artifact.tool_version,
+        created_at=_manifest_timestamp(artifact.created_at, "created_at"),
+        ocr_words_per_page=ocr_words_per_page,
+        page_coverage=page_coverage,
+    )
+
+
+def _entry_to_json(entry: ManifestEntry) -> dict[str, object]:
+    checked = _validate_entry(entry)
+    return {
+        "derived": {
+            name: {
+                "created_at": artifact.created_at,
+                "path": artifact.path,
+                "sha256": artifact.sha256,
+                "source_sha256": artifact.source_sha256,
+                "tool": artifact.tool,
+                "tool_version": artifact.tool_version,
+                **(
+                    {"ocr_words_per_page": artifact.ocr_words_per_page}
+                    if artifact.ocr_words_per_page is not None
+                    else {}
+                ),
+                **(
+                    {"page_coverage": [dict(page) for page in artifact.page_coverage]}
+                    if artifact.page_coverage
+                    else {}
+                ),
+            }
+            for name, artifact in sorted(checked.derived.items(), key=lambda item: item[0])
+        },
+        "etag": checked.etag,
+        "fetched_at": checked.fetched_at,
+        "last_modified": checked.last_modified,
+        "path": checked.path,
+        "sha256": checked.sha256,
+        "size": checked.size,
+        "source_id": checked.source_id,
+    }
+
+
+def _validate_source_key(key: str) -> None:
+    if not isinstance(key, str):
+        raise A2LError("canonical source key must be a string")
+    parts = key.split(":")
+    if len(parts) != 4 or any(not _KEY_PART.fullmatch(part) for part in parts):
+        raise A2LError("canonical source key must be school:course_org_unit:entity_kind:entity_id")
+
+
+def _validate_relative_posix(value: object, *, field: str) -> None:
+    if not isinstance(value, str) or not value:
+        raise A2LError(f"{field} must be a non-empty relative POSIX path")
+    if "\\" in value or value.startswith("/") or _WINDOWS_ABSOLUTE.match(value):
+        raise A2LError(f"{field} must be relative POSIX")
+    pure = PurePosixPath(value)
+    if pure.is_absolute() or any(part in {"", ".", ".."} for part in pure.parts):
+        raise A2LError(f"{field} must be relative POSIX and cannot escape the root")
+    if pure.as_posix() != value:
+        raise A2LError(f"{field} must be normalized relative POSIX")
+
+
+def _validate_hash(value: object, field: str) -> None:
+    if not isinstance(value, str) or _SHA256.fullmatch(value) is None:
+        raise A2LError(f"{field} must be a lowercase 64-character SHA-256")
+
+
+def _manifest_timestamp(value: object, field: str) -> str:
+    if not isinstance(value, str):
+        raise A2LError(f"{field} must be a timezone-aware ISO 8601 UTC timestamp")
+    parsed = _parse_timestamp(value, field)
+    if parsed.utcoffset() != timedelta(0):
+        raise A2LError(f"{field} must be a timezone-aware ISO 8601 UTC timestamp")
+    return parsed.astimezone(UTC).isoformat().replace("+00:00", "Z")
+
+
+def _parse_timestamp(value: str, field: str) -> datetime:
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise A2LError(f"{field} must be a timezone-aware ISO 8601 UTC timestamp") from exc
+    if parsed.tzinfo is None or parsed.utcoffset() is None:
+        raise A2LError(f"{field} must be timezone-aware")
+    return parsed
+
+
+def _utc_datetime(value: datetime, field: str) -> datetime:
+    if not isinstance(value, datetime) or value.tzinfo is None or value.utcoffset() is None:
+        raise A2LError(f"{field} must be timezone-aware UTC")
+    return value.astimezone(UTC)
+
+
+def _required_fields(
+    raw: Mapping[str, object], fields: Collection[str], context: str
+) -> dict[str, object]:
+    missing = set(fields) - raw.keys()
+    if missing:
+        raise A2LError(f"{context} is missing fields: {sorted(missing)!r}")
+    return {key: raw[key] for key in fields}
+
+
+def _as_str(value: object, field: str) -> str:
+    if not isinstance(value, str):
+        raise A2LError(f"{field} must be a string")
+    return value
+
+
+def _as_optional_str(value: object, field: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise A2LError(f"{field} must be a string or null")
+    return value
+
+
+def _as_nonnegative_int(value: object, field: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise A2LError(f"{field} must be a non-negative integer")
+    return value
+
+
+def _as_optional_positive_int(value: object, field: str) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise A2LError(f"{field} must be a positive integer or null")
+    return value
+
+
+def _as_page_coverage(value: object) -> tuple[Mapping[str, object], ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, (list, tuple)):
+        raise A2LError("page_coverage must be an array")
+    normalized: list[Mapping[str, object]] = []
+    for index, raw_page in enumerate(value, start=1):
+        if not isinstance(raw_page, Mapping):
+            raise A2LError(f"page_coverage item {index} must be an object")
+        page = raw_page.get("page")
+        mode = raw_page.get("mode")
+        words = raw_page.get("words")
+        warning = raw_page.get("warning")
+        if isinstance(page, bool) or not isinstance(page, int) or page <= 0:
+            raise A2LError(f"page_coverage item {index} page must be a positive integer")
+        if not isinstance(mode, str) or not mode:
+            raise A2LError(f"page_coverage item {index} mode must be a non-empty string")
+        if isinstance(words, bool) or not isinstance(words, int) or words < 0:
+            raise A2LError(f"page_coverage item {index} words must be a non-negative integer")
+        if warning is not None and not isinstance(warning, str):
+            raise A2LError(f"page_coverage item {index} warning must be a string or null")
+        normalized.append({"page": page, "mode": mode, "words": words, "warning": warning})
+    return tuple(normalized)
+
+
+def _read_json_object(destination: Path, label: str) -> dict[str, object] | None:
+    try:
+        with open(os.fspath(paths.long_path(destination)), encoding="utf-8", newline="") as handle:
+            raw: Any = json.load(handle)
+    except FileNotFoundError:
+        return None
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        message = (
+            f"{label} is unreadable" if isinstance(exc, OSError) else f"{label} is not valid JSON"
+        )
+        raise A2LError(message) from exc
+    if not isinstance(raw, dict):
+        raise A2LError(f"{label} root must be an object")
+    return cast(dict[str, object], raw)
+
+
+def _read_text(destination: Path) -> str:
+    try:
+        with open(os.fspath(paths.long_path(destination)), encoding="utf-8", newline="") as handle:
+            return handle.read()
+    except (OSError, UnicodeError) as exc:
+        raise A2LError("vault VERSION is unreadable") from exc
+
+
+def _regular_file_exists(path: Path, label: str) -> bool:
+    try:
+        file_stat = os.lstat(os.fspath(paths.long_path(path)))
+    except FileNotFoundError:
+        return False
+    except OSError as exc:
+        raise A2LError(f"{label} is unreadable") from exc
+    if paths.is_link(path) or stat.S_ISLNK(file_stat.st_mode):
+        raise A2LError(f"{label} must not be a symlink")
+    if not stat.S_ISREG(file_stat.st_mode):
+        raise A2LError(f"{label} must be a regular file")
+    return True
+
+
+def _canonical_json(payload: object) -> str:
+    return (
+        json.dumps(payload, ensure_ascii=False, sort_keys=True, indent=2, separators=(",", ": "))
+        + "\n"
+    )
+
+
+def _hash_file(source: Path) -> tuple[str, int]:
+    digest = sha256()
+    size = 0
+    try:
+        with open(os.fspath(paths.long_path(source)), "rb") as handle:
+            while chunk := handle.read(_COPY_CHUNK_SIZE):
+                digest.update(chunk)
+                size += len(chunk)
+    except (FileNotFoundError, IsADirectoryError):
+        return "", -1
+    return digest.hexdigest(), size
+
+
+def _copy_verified(
+    source: Path,
+    destination: Path,
+    *,
+    root: Path | None = None,
+    expected_sha256: str | None,
+    expected_size: int | None,
+) -> bool:
+    """Stream a source into a sibling ``.part`` and atomically install it if valid."""
+
+    paths.ensure_dir(destination.parent, root=root)
+    if root is not None and paths.has_link_component(destination.parent, root=root):
+        raise A2LError("history destination parent contains a link component")
+    file_descriptor, raw_temporary = tempfile.mkstemp(
+        prefix=f".{destination.name}.",
+        suffix=".part",
+        dir=os.fspath(paths.long_path(destination.parent)),
+    )
+    temporary = paths.plain_path(Path(raw_temporary))
+    digest = sha256()
+    size = 0
+    descriptor_open = True
+    try:
+        # The temporary reservation happens after the destination-parent check.  Revalidate the
+        # reserved path before opening it so a swapped parent cannot redirect a history copy.
+        if root is not None and paths.has_link_component(temporary, root=root):
+            raise A2LError("history temporary path contains a link component")
+        with (
+            open(os.fspath(paths.long_path(source)), "rb") as input_handle,
+            os.fdopen(file_descriptor, "wb") as output_handle,
+        ):
+            descriptor_open = False
+            while chunk := input_handle.read(_COPY_CHUNK_SIZE):
+                digest.update(chunk)
+                size += len(chunk)
+                output_handle.write(chunk)
+            output_handle.flush()
+            os.fsync(output_handle.fileno())
+        actual_sha256 = digest.hexdigest()
+        if expected_sha256 is not None and (
+            actual_sha256 != expected_sha256
+            or (expected_size is not None and size != expected_size)
+        ):
+            raise A2LError("manifest source hash mismatch: integrity gap")
+        paths.atomic_install_temp(destination, temporary, root=root)
+        return True
+    except (FileNotFoundError, IsADirectoryError):
+        return False
+    finally:
+        # This temporary is a generated local backup copy and is cheap to recreate; unlike an
+        # ingest download .part, cleanup after an install failure is intentional here.
+        if descriptor_open:
+            with suppress(OSError):
+                os.close(file_descriptor)
+        with suppress(OSError):
+            os.unlink(os.fspath(paths.long_path(temporary)))
+
+
+def _allocate_revision_directory(bucket: Path, timestamp: str, *, root: Path | None = None) -> Path:
+    for number in range(1, 100_000):
+        suffix = "" if number == 1 else f"_{number}"
+        candidate = bucket / f"{timestamp}{suffix}"
+        if root is not None and paths.has_link_component(candidate, root=root):
+            raise A2LError("revision path contains a link component")
+        try:
+            paths.long_path(candidate).mkdir(parents=False, exist_ok=False)
+        except FileExistsError:
+            continue
+        if root is not None and paths.has_link_component(candidate, root=root):
+            raise A2LError("revision path contains a link component")
+        return candidate
+    raise A2LError("could not allocate a collision-safe revision directory")
+
+
+def _copy_tree(source: Path, destination: Path, *, root: Path | None = None) -> None:
+    """Copy a tree while applying the long-path boundary to each individual operation."""
+    if paths.is_link(source):
+        raise A2LError("schema state cannot contain symlinks")
+    if paths.is_link(destination):
+        raise A2LError("schema staging destination cannot be a symlink")
+    paths.ensure_dir(destination, root=root)
+    for candidate in paths.walk(source):
+        relative = candidate.relative_to(source)
+        target = destination / relative
+        if paths.is_link(candidate):
+            raise A2LError("schema state cannot contain symlinks")
+        if paths.long_path(candidate).is_dir():
+            paths.ensure_dir(target, root=root)
+            continue
+        if not paths.long_path(candidate).is_file():
+            raise A2LError("schema state contains an unsupported filesystem entry")
+        paths.ensure_dir(target.parent, root=root)
+        with (
+            open(os.fspath(paths.long_path(candidate)), "rb") as source_handle,
+            _open_private_copy_target(target, root=root) as destination_handle,
+        ):
+            while chunk := source_handle.read(_COPY_CHUNK_SIZE):
+                destination_handle.write(chunk)
+
+
+def _open_private_copy_target(path: Path, *, root: Path | None = None) -> BinaryIO:
+    """Create a new state-copy file without following a replacement link."""
+
+    if root is not None and paths.has_link_component(path, root=root):
+        raise A2LError("schema state copy path contains a link component")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    file_descriptor = os.open(os.fspath(paths.long_path(path)), flags, 0o600)
+    try:
+        file_stat = os.fstat(file_descriptor)
+        if not stat.S_ISREG(file_stat.st_mode) or getattr(file_stat, "st_nlink", 1) != 1:
+            raise A2LError("schema state copy must be a private regular file")
+        handle = os.fdopen(file_descriptor, "wb")
+        file_descriptor = -1
+        return handle
+    except BaseException:
+        if file_descriptor >= 0:
+            os.close(file_descriptor)
+        raise
+
+
+def _backup_state(state: Path, version: int, *, root: Path | None = None) -> Path:
+    base = state.parent / f".a2l-backup-v{version}"
+    candidate = base
+    number = 2
+    while _occupied(candidate):
+        candidate = state.parent / f".a2l-backup-v{version}-{number}"
+        number += 1
+    try:
+        _copy_tree(state, candidate, root=root)
+    except BaseException:
+        paths.remove_tree(candidate, ignore_errors=True)
+        raise
+    return candidate
+
+
+def _install_migrated_state(
+    state: Path, staged_state: Path, backup: Path, *, root: Path | None = None
+) -> None:
+    """Commit staged schema state, restoring the backup if installation fails."""
+
+    try:
+        _synchronize_state(staged_state, state, root=root)
+    except BaseException:
+        try:
+            _synchronize_state(backup, state, root=root)
+        except BaseException as restore_error:
+            raise A2LError("schema migration failed and rollback also failed") from restore_error
+        raise
+
+
+def _synchronize_state(source: Path, destination: Path, *, root: Path | None = None) -> None:
+    """Synchronize one state tree into another with VERSION installed last."""
+
+    source_files, source_directories = _state_tree(source)
+    destination_files, destination_directories = _state_tree(destination)
+
+    obsolete = (destination_files - source_files) | (destination_directories - source_directories)
+    for relative in sorted(obsolete, key=_deepest_first):
+        _remove_state_path(destination / _relative_path(relative), root=root)
+
+    for relative in sorted(source_directories, key=_shallowest_first):
+        directory = destination / _relative_path(relative)
+        paths.ensure_dir(directory, root=root)
+
+    for relative in sorted(source_files - {"VERSION"}):
+        source_file = source / _relative_path(relative)
+        destination_file = destination / _relative_path(relative)
+        if not _same_file(source_file, destination_file):
+            paths.atomic_write_bytes(destination_file, _read_bytes(source_file), root=root)
+
+    version_source = source / "VERSION"
+    if "VERSION" not in source_files:
+        raise A2LError("staged schema state is missing VERSION")
+    paths.atomic_write_bytes(destination / "VERSION", _read_bytes(version_source), root=root)
+
+
+def _state_tree(root: Path) -> tuple[set[str], set[str]]:
+    files: set[str] = set()
+    directories: set[str] = set()
+    for candidate in paths.walk(root):
+        if paths.is_link(candidate):
+            raise A2LError("schema state cannot contain symlinks")
+        relative = candidate.relative_to(root).as_posix()
+        if paths.long_path(candidate).is_file():
+            files.add(relative)
+        elif paths.long_path(candidate).is_dir():
+            directories.add(relative)
+        else:
+            raise A2LError("schema state contains an unsupported filesystem entry")
+    return files, directories
+
+
+def _relative_path(relative: str) -> Path:
+    return Path(*PurePosixPath(relative).parts)
+
+
+def _deepest_first(relative: str) -> tuple[int, str]:
+    return (-len(PurePosixPath(relative).parts), relative)
+
+
+def _shallowest_first(relative: str) -> tuple[int, str]:
+    return (len(PurePosixPath(relative).parts), relative)
+
+
+def _remove_state_path(path: Path, *, root: Path | None = None) -> None:
+    if root is not None and paths.has_link_component(path, root=root):
+        raise A2LError("schema state path contains a link component")
+    if paths.long_path(path).is_dir() and not paths.is_link(path):
+        paths.remove_tree(path)
+    else:
+        os.unlink(os.fspath(paths.long_path(path)))
+
+
+def _same_file(first: Path, second: Path) -> bool:
+    if not paths.long_path(first).is_file() or not paths.long_path(second).is_file():
+        return False
+    return _hash_file(first) == _hash_file(second)
+
+
+def _read_bytes(source: Path) -> bytes:
+    with open(os.fspath(paths.long_path(source)), "rb") as handle:
+        return handle.read()
+
+
+def _occupied(path: Path) -> bool:
+    return paths.long_path(path).exists() or paths.is_link(path)
+
+
+def _write_vault_gitignore(root: Path) -> None:
+    paths.atomic_write_text(
+        root / ".gitignore",
+        ".a2l/\n**/_meta/my_grades.json\n**/discussions/\n**/.a2l/submissions/\n",
+        root=root,
+    )
+
+
+def _refuse_agent2learn_checkout(path: Path) -> None:
+    source_root = _agent2learn_source_root()
+    if source_root is None:
+        return
+    try:
+        path.relative_to(source_root)
+    except ValueError:
+        return
+    raise A2LError("refusing to place a vault inside the Agent2Learn source checkout")
+
+
+def _require_git_confirmation_if_needed(path: Path) -> None:
+    repository_root = _git_root(path)
+    if repository_root is None:
+        return
+    if not sys.stdin.isatty():
+        raise A2LError(
+            f"selected vault is inside Git worktree {repository_root}; explicit TTY confirmation "
+            "is required"
+        )
+    try:
+        answer = input(
+            f"Selected vault is inside Git worktree {repository_root}. "
+            f"Type {_GIT_CONFIRMATION!r} to continue: "
+        )
+    except EOFError as exc:
+        raise A2LError("vault claim cancelled: no TTY confirmation") from exc
+    if answer.strip() != _GIT_CONFIRMATION:
+        raise A2LError("vault claim cancelled: explicit Git worktree confirmation did not match")
+
+
+def _agent2learn_source_root() -> Path | None:
+    package_root = Path(__file__).resolve().parents[2]
+    repository_root = _git_root(package_root)
+    if repository_root is None:
+        return None
+    if (
+        paths.long_path(repository_root / "pyproject.toml").is_file()
+        and paths.long_path(repository_root / "src" / "agent2learn").is_dir()
+    ):
+        return repository_root
+    return None
+
+
+def _git_root(path: Path) -> Path | None:
+    probe = path if paths.long_path(path).is_dir() else path.parent
+    try:
+        result = subprocess.run(
+            [
+                "git",
+                "-C",
+                os.fspath(paths.long_path(probe)),
+                "rev-parse",
+                "--show-toplevel",
+            ],
+            check=False,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        raise A2LError("could not establish Git worktree status") from exc
+    if result.returncode != 0 or not result.stdout.strip():
+        stderr = getattr(result, "stderr", "")
+        if isinstance(stderr, str) and "not a git repository" in stderr.casefold():
+            return None
+        raise A2LError("could not establish Git worktree status")
+    try:
+        return Path(result.stdout.strip()).resolve()
+    except (OSError, RuntimeError, ValueError) as exc:
+        raise A2LError("could not establish Git worktree status") from exc
+
+
+__all__ = [
+    "MIGRATIONS",
+    "SCHEMA_VERSION",
+    "DerivedArtifact",
+    "ManifestEntry",
+    "Vault",
+    "check_schema",
+]