aisc-cli 0.1.0__py3-none-any.whl

aisc/domain/cc_switch_release.py

@@ -0,0 +1,303 @@
+"""cc-switch release selection — pure domain logic (Stage 8, CS-01/CS-02).
+
+Operates on GitHub Releases API dicts (already fetched; this module never
+performs I/O). Encodes the asset contract proven by the 8a black-box probe
+(``docs/plans/aisc-next-followup/stage-8-cc-switch-provider-ui/8a-discovery-report.md``):
+
+- asset names: ``cc-switch-cli-{tag}-linux-{x64|arm64}-{musl|glibc}.tar.gz``
+  (versioned, preferred) and the unversioned twin inside the SAME release;
+  the arch token is ``x64`` — NOT ``amd64``;
+- every release asset carries an authoritative ``digest`` (``sha256:<hex>``)
+  from the Releases API — a missing digest fails closed;
+- only releases with ``prerelease=false, draft=false`` and a semver ``vX.Y.Z``
+  tag are eligible for the ``stable`` channel.
+
+Fail-closed everywhere: an ambiguous or unverifiable release is rejected,
+never guessed.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+RESOLVED_SCHEMA = "aisc.cc-switch-resolved/v1"
+UPSTREAM_REPO = "saladday/cc-switch-cli"
+
+# Stable error codes (never change the string; diagnostics rely on them).
+CC_SWITCH_ERROR_INVALID_CHANNEL = "AISC_ERR_CC_SWITCH_INVALID_CHANNEL"
+CC_SWITCH_ERROR_INVALID_TAG = "AISC_ERR_CC_SWITCH_INVALID_TAG"
+CC_SWITCH_ERROR_NO_STABLE_RELEASE = "AISC_ERR_CC_SWITCH_NO_STABLE_RELEASE"
+CC_SWITCH_ERROR_VERSION_NOT_FOUND = "AISC_ERR_CC_SWITCH_VERSION_NOT_FOUND"
+CC_SWITCH_ERROR_NO_MATCHING_ASSET = "AISC_ERR_CC_SWITCH_NO_MATCHING_ASSET"
+CC_SWITCH_ERROR_MISSING_DIGEST = "AISC_ERR_CC_SWITCH_MISSING_DIGEST"
+CC_SWITCH_ERROR_BAD_MANIFEST = "AISC_ERR_CC_SWITCH_BAD_MANIFEST"
+CC_SWITCH_ERROR_MANIFEST_MISMATCH = "AISC_ERR_CC_SWITCH_MANIFEST_MISMATCH"
+CC_SWITCH_ERROR_NETWORK = "AISC_ERR_CC_SWITCH_NETWORK"
+CC_SWITCH_ERROR_RATE_LIMITED = "AISC_ERR_CC_SWITCH_RATE_LIMITED"
+
+SEMVER_TAG_RE = re.compile(r"^v\d+\.\d+\.\d+$")
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+# Arch tokens upstream uses in asset names (map your platform's uname arch
+# through this before calling select_release).
+ASSET_ARCHS = ("x64", "arm64")
+ASSET_LIBCS = ("musl", "glibc")
+
+# Where a resolution came from — surfaced in the manifest so a cached or
+# file-supplied resolution is never mistaken for a live one (fail-visible).
+SOURCE_API = "api"
+SOURCE_CACHE = "cache"
+SOURCE_MANIFEST = "manifest"
+
+
+class ResolveError(Exception):
+    """Release selection failure with a stable code (fail closed)."""
+
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def normalize_arch(platform_arch: str) -> str:
+    """Map a platform arch (``amd64``/``x86_64``/``arm64``/``aarch64``) to the
+    upstream asset token (``x64``/``arm64``). Unknown arches fail closed."""
+    a = platform_arch.strip().lower()
+    if a in ("amd64", "x86_64", "x64"):
+        return "x64"
+    if a in ("arm64", "aarch64"):
+        return "arm64"
+    raise ResolveError(
+        CC_SWITCH_ERROR_NO_MATCHING_ASSET,
+        f"unsupported platform arch for cc-switch assets: {platform_arch!r}",
+    )
+
+
+def _asset_names(tag: str, arch: str, libc: str) -> Tuple[str, str]:
+    """(versioned, unversioned) asset names for a release tag."""
+    return (
+        f"cc-switch-cli-{tag}-linux-{arch}-{libc}.tar.gz",
+        f"cc-switch-cli-linux-{arch}-{libc}.tar.gz",
+    )
+
+
+def _usable_asset(release: Dict[str, Any], tag: str, arch: str, libc: str) -> Optional[Dict[str, Any]]:
+    """Pick the asset for this release matching the arch/libc contract, with a
+    trustworthy sha256 digest. Versioned name wins; the unversioned twin in
+    the same release is the same file. Missing/invalid digest -> not usable."""
+    versioned, unversioned = _asset_names(tag, arch, libc)
+    assets = {a.get("name", ""): a for a in release.get("assets", [])}
+    chosen = assets.get(versioned) or assets.get(unversioned)
+    if chosen is None:
+        return None
+    digest = str(chosen.get("digest") or "")
+    sha = digest.split(":", 1)[1] if digest.startswith("sha256:") else ""
+    if not _SHA256_RE.match(sha):
+        return None
+    return chosen
+
+
+def _eligible(release: Dict[str, Any]) -> bool:
+    if release.get("draft") or release.get("prerelease"):
+        return False
+    return bool(SEMVER_TAG_RE.match(str(release.get("tag_name") or "")))
+
+
+def select_release(
+    releases: List[Dict[str, Any]],
+    *,
+    channel: str = "stable",
+    version: str = "latest",
+    arch: str = "x64",
+    libc: str = "musl",
+) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """Pure selection: (release, asset) for the channel/version/arch/libc.
+
+    ``version="latest"`` takes the newest eligible release that HAS a usable
+    asset (skipping empty releases); an explicit ``vX.Y.Z`` must exist and
+    have the asset (fail closed otherwise).
+    """
+    if channel != "stable":
+        raise ResolveError(
+            CC_SWITCH_ERROR_INVALID_CHANNEL,
+            f"unsupported cc-switch channel {channel!r} (only 'stable')",
+        )
+    if arch not in ASSET_ARCHS or libc not in ASSET_LIBCS:
+        raise ResolveError(
+            CC_SWITCH_ERROR_NO_MATCHING_ASSET,
+            f"unsupported asset target linux-{arch}-{libc}",
+        )
+
+    want_explicit = version != "latest"
+    if want_explicit and not SEMVER_TAG_RE.match(version):
+        raise ResolveError(
+            CC_SWITCH_ERROR_INVALID_TAG,
+            f"cc-switch version must be 'latest' or vX.Y.Z, got {version!r}",
+        )
+
+    ordered = sorted(
+        (r for r in releases if _eligible(r)),
+        key=lambda r: str(r.get("published_at") or r.get("created_at") or ""),
+        reverse=True,
+    )
+
+    if want_explicit:
+        candidates = [r for r in ordered if r.get("tag_name") == version]
+        if not candidates:
+            raise ResolveError(
+                CC_SWITCH_ERROR_VERSION_NOT_FOUND,
+                f"cc-switch {version} not found in the stable channel",
+            )
+    else:
+        candidates = ordered
+
+    for release in candidates:
+        asset = _usable_asset(release, str(release["tag_name"]), arch, libc)
+        if asset is not None:
+            return release, asset
+
+    if want_explicit:
+        raise ResolveError(
+            CC_SWITCH_ERROR_NO_MATCHING_ASSET,
+            f"cc-switch {version} has no linux-{arch}-{libc}.tar.gz asset with a sha256 digest",
+        )
+    raise ResolveError(
+        CC_SWITCH_ERROR_NO_STABLE_RELEASE,
+        f"no stable cc-switch release with a usable linux-{arch}-{libc} asset",
+    )
+
+
+@dataclass(frozen=True)
+class ResolvedRelease:
+    """The frozen resolution result consumed by the build and baked into the
+    image labels / manifest (02-domain-contract.md §Build input)."""
+
+    channel: str
+    tag: str
+    release_id: int
+    commit: str
+    published_at: str
+    asset_name: str
+    asset_url: str
+    asset_sha256: str
+    asset_size: int
+    arch: str
+    libc: str
+    source: str  # api | cache | manifest
+
+    def to_manifest(self, *, resolved_at: str = "") -> Dict[str, Any]:
+        return {
+            "schema": RESOLVED_SCHEMA,
+            "channel": self.channel,
+            "version": self.tag,
+            "release_id": self.release_id,
+            "commit": self.commit,
+            "published_at": self.published_at,
+            "asset_name": self.asset_name,
+            "asset_url": self.asset_url,
+            "asset_sha256": self.asset_sha256,
+            "asset_size": self.asset_size,
+            "arch": self.arch,
+            "libc": self.libc,
+            "source": self.source,
+            "resolved_at": resolved_at,
+        }
+
+    @classmethod
+    def from_manifest(cls, data: Dict[str, Any]) -> "ResolvedRelease":
+        """Strict load for ``--cc-switch-manifest`` (offline/reproducible
+        builds). Unknown extra keys are ignored; missing/invalid fields fail
+        closed — a partial manifest must never enter a build."""
+        try:
+            schema = data["schema"]
+            obj = cls(
+                channel=str(data["channel"]),
+                tag=str(data["version"]),
+                release_id=int(data["release_id"]),
+                commit=str(data["commit"]),
+                published_at=str(data["published_at"]),
+                asset_name=str(data["asset_name"]),
+                asset_url=str(data["asset_url"]),
+                asset_sha256=str(data["asset_sha256"]),
+                asset_size=int(data["asset_size"]),
+                arch=str(data["arch"]),
+                libc=str(data["libc"]),
+                source=str(data.get("source") or SOURCE_MANIFEST),
+            )
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ResolveError(
+                CC_SWITCH_ERROR_BAD_MANIFEST,
+                f"cc-switch manifest is missing/invalid fields: {exc}",
+            ) from exc
+        if schema != RESOLVED_SCHEMA:
+            raise ResolveError(
+                CC_SWITCH_ERROR_BAD_MANIFEST,
+                f"cc-switch manifest schema {schema!r} != {RESOLVED_SCHEMA!r}",
+            )
+        if not SEMVER_TAG_RE.match(obj.tag):
+            raise ResolveError(
+                CC_SWITCH_ERROR_BAD_MANIFEST,
+                f"cc-switch manifest version {obj.tag!r} is not vX.Y.Z",
+            )
+        if not _SHA256_RE.match(obj.asset_sha256):
+            raise ResolveError(
+                CC_SWITCH_ERROR_BAD_MANIFEST,
+                "cc-switch manifest asset_sha256 is not a bare sha256 hex digest",
+            )
+        if obj.asset_name != _asset_names(obj.tag, obj.arch, obj.libc)[0] and \
+                obj.asset_name != _asset_names(obj.tag, obj.arch, obj.libc)[1]:
+            raise ResolveError(
+                CC_SWITCH_ERROR_BAD_MANIFEST,
+                f"cc-switch manifest asset_name {obj.asset_name!r} does not match "
+                f"linux-{obj.arch}-{obj.libc} for {obj.tag}",
+            )
+        if obj.source not in (SOURCE_API, SOURCE_CACHE, SOURCE_MANIFEST):
+            raise ResolveError(
+                CC_SWITCH_ERROR_BAD_MANIFEST,
+                f"cc-switch manifest source {obj.source!r} is unknown",
+            )
+        return obj
+
+    def check_matches_request(self, channel: str, version: str) -> None:
+        """Cross-check a loaded manifest against the requested channel/version
+        (both explicit) — a mismatch fails closed instead of building the
+        wrong thing."""
+        if channel != self.channel:
+            raise ResolveError(
+                CC_SWITCH_ERROR_MANIFEST_MISMATCH,
+                f"manifest channel {self.channel!r} != requested {channel!r}",
+            )
+        if version != "latest" and version != self.tag:
+            raise ResolveError(
+                CC_SWITCH_ERROR_MANIFEST_MISMATCH,
+                f"manifest version {self.tag!r} != requested {version!r}",
+            )
+
+
+def resolved_from_release(
+    release: Dict[str, Any],
+    asset: Dict[str, Any],
+    *,
+    channel: str,
+    arch: str,
+    libc: str,
+    source: str,
+) -> ResolvedRelease:
+    """Build a ResolvedRelease from an API release+asset pair."""
+    tag = str(release["tag_name"])
+    return ResolvedRelease(
+        channel=channel,
+        tag=tag,
+        release_id=int(release.get("id") or 0),
+        commit=str(release.get("target_commitish") or ""),
+        published_at=str(release.get("published_at") or ""),
+        asset_name=str(asset["name"]),
+        asset_url=str(asset.get("browser_download_url") or ""),
+        asset_sha256=str(asset.get("digest") or "").split(":", 1)[-1],
+        asset_size=int(asset.get("size") or 0),
+        arch=arch,
+        libc=libc,
+        source=source,
+    )

aisc/domain/config.py

@@ -0,0 +1,64 @@
+"""Pure domain models for AISC profile and network configuration."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class PlatformPathConfig:
+    """Platform-specific AISC config root."""
+
+    config_dir: str
+    state_dir: str
+
+
+def _validate_absolute_root(name: str, value: Optional[str]) -> Optional[str]:
+    if value is None:
+        return None
+    if value.strip() != value:
+        raise ValueError(f"{name} has leading/trailing whitespace")
+    if not value:
+        raise ValueError(f"{name} must not be empty")
+    if not os.path.isabs(value):
+        raise ValueError(f"{name} must be an absolute path")
+    return value
+
+
+@dataclass(frozen=True)
+class PathPolicy:
+    """Validated roots used while reading AISC configuration."""
+
+    platform: PlatformPathConfig
+    workspace: Optional[str] = None
+    aisc_root: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "workspace", _validate_absolute_root("workspace", self.workspace)
+        )
+        object.__setattr__(
+            self, "aisc_root", _validate_absolute_root("aisc_root", self.aisc_root)
+        )
+
+
+class IssueSeverity(str, Enum):
+    ERROR = "error"
+    WARNING = "warning"
+
+
+@dataclass
+class SchemaIssue:
+    severity: IssueSeverity
+    path: str = ""
+    reason_code: str = ""
+    message: str = ""
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.severity.value.upper()}: {self.path} "
+            f"[{self.reason_code}] — {self.message}"
+        )

aisc/domain/data_migration.py

@@ -0,0 +1,259 @@
+"""Legacy-layout migration contract (Stage 7, 7c, DATA-02/D7-03).
+
+Pure tables and schema for migrating the pre-Stage-7 workspace layout (see
+the measured fresh-init inventory in stage-7/02-domain-contract.md) into the
+data root. The walker lives in ``application/legacy_scan.py``; execution
+(prepare/commit/rollback/quarantine) is 7d.
+
+Classification (D7-03 — protect user files, migrate only the known):
+- ``owned``     allowlisted AISC/agent state → migratable, hashed, mapped;
+- ``transient`` locks, pid files, live-SQLite sidecars' init locks, daemon
+                logs — coordination/bounded artifacts, left in place, never
+                migrated (cc-switch.db itself IS owned; -shm/-wal migrate as
+                a set with it so an un-checkpointed WAL loses nothing);
+- ``unknown``   inside an AISC namespace but not allowlisted (likely the
+                user's own file) → quarantine candidate, never deleted;
+- ``conflict``  owned but the target already exists with a different hash
+                → fail closed, user decision;
+- namespace ``foreign``: e.g. a user's own ``.claude`` predating AISC — no
+  AISC-init marker anywhere → reported, not migrated.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Tuple
+
+MIGRATION_PROTOCOL = "aisc.data-migration/v1"
+MIGRATION_SCHEMA_VERSION = 1
+
+# Manifest lifecycle states (closed set, 02-domain-contract.md).
+STATE_PREPARED = "prepared"
+STATE_COMMITTED = "committed"
+STATE_ROLLED_BACK = "rolled_back"
+STATE_QUARANTINED = "quarantined"
+MANIFEST_STATES = (STATE_PREPARED, STATE_COMMITTED, STATE_ROLLED_BACK, STATE_QUARANTINED)
+
+ENTRY_OWNED = "owned"
+ENTRY_TRANSIENT = "transient"
+ENTRY_UNKNOWN = "unknown"
+ENTRY_CONFLICT = "conflict"
+ENTRY_CLASSIFICATIONS = (ENTRY_OWNED, ENTRY_TRANSIENT, ENTRY_UNKNOWN, ENTRY_CONFLICT)
+
+# Per-entry migration status (7d sets these; scan drafts stay "pending").
+STATUS_PENDING = "pending"
+STATUS_COPIED = "copied"
+STATUS_SKIPPED = "skipped"
+STATUS_QUARANTINED = "quarantined"
+
+NAMESPACE_FOREIGN = "foreign"
+NAMESPACE_AISC = "aisc"
+
+# Namespace redirect marker left after a namespace fully migrates (risk
+# table: old entries must find a read-only redirect/diagnostic, not a
+# silently diverging copy). Content: JSON with schema/workspace_hash/root.
+MARKER_NAME = ".aisc-migrated"
+
+# Execution error codes (7d) — exit mapping stays with the CLI layer.
+ERR_CONFLICT = "AISC_ERR_DATA_MIGRATION_CONFLICT"
+ERR_UNKNOWN_PENDING = "AISC_ERR_DATA_MIGRATION_UNKNOWN_PENDING"
+ERR_SOURCE_CHANGED = "AISC_ERR_DATA_MIGRATION_SOURCE_CHANGED"
+ERR_INSUFFICIENT_SPACE = "AISC_ERR_DATA_MIGRATION_INSUFFICIENT_SPACE"
+ERR_CORRUPT_COPY = "AISC_ERR_DATA_MIGRATION_CORRUPT_COPY"
+
+# -- allowlist ---------------------------------------------------------------
+# Keys are workspace-relative namespaces; values: (exact_files, dir_prefixes,
+# transient_files, transient_prefixes). Everything else inside the namespace
+# classifies as ``unknown`` (quarantine candidate, never deleted).
+
+ALLOWLIST: Dict[str, Tuple[Tuple[str, ...], Tuple[str, ...], Tuple[str, ...], Tuple[str, ...]]] = {
+    ".aisc": (
+        # containers.json/state.env → runtime/; config.json → workspace config
+        ("containers.json", "state.env", "config.json"),
+        (),
+        (".containers.lock", MARKER_NAME),
+        ("workspace-locks/",),
+    ),
+    ".claude": (
+        # .claude.json (agent runtime config) and .factory-version (factory
+        # marker) are hidden dotfiles found by the real-workspace scan.
+        ("CLAUDE.md", "config.json", "settings.json", "settings.local.json",
+         ".claude.json", ".factory-version"),
+        ("backups/", "commands/", "plugins/", "projects/", "sessions/", "skills/"),
+        (MARKER_NAME,),
+        (),
+    ),
+    ".codex": (
+        ("config.toml", "AGENTS.md", ".factory-version"),
+        ("skills/",),
+        (MARKER_NAME,),
+        (),
+    ),
+    ".cc-switch": (
+        # db migrates together with -shm/-wal (un-checkpointed WAL safety).
+        ("cc-switch.db", "cc-switch.db-shm", "cc-switch.db-wal", "settings.json",
+         "session-scan-cache.db", ".aisc-bundled-skills.sha256",
+         ".aisc-preset-providers-claude.sha256", ".aisc-preset-providers-codex.sha256"),
+        ("skills/",),
+        ("cc-switch.db.init.lock", "state-mutation.lock", ".aisc-bundled-skills.lock",
+         MARKER_NAME),
+        (),
+    ),
+    # daemon runtime only: logs/pids are transient, anything else → unknown
+    ".local": ((), (), (), ("state/cc-switch/",)),
+}
+
+# Namespace → target layout under workspaces/<hash>/ ("" = file at the
+# workspace-dir root). Only used for ``owned`` entries.
+TARGET_DIRS: Dict[str, str] = {
+    ".claude": "claude",
+    ".codex": "codex",
+    ".cc-switch": "cc-switch",
+}
+TARGET_FILES: Dict[str, str] = {
+    ".aisc/containers.json": "runtime/containers.json",
+    ".aisc/state.env": "runtime/state.env",
+    ".aisc/config.json": "config.json",
+}
+
+# A workspace is "AISC-initialized" when at least one of these exists; a
+# namespace dir without any marker classifies as the user's own (foreign).
+AISC_INIT_MARKERS: Tuple[str, ...] = (
+    ".aisc",
+    ".codex/.factory-version",
+    ".cc-switch/.aisc-bundled-skills.sha256",
+    ".cc-switch/.aisc-preset-providers-claude.sha256",
+)
+
+
+def classify(namespace: str, rel: str) -> Tuple[str, str]:
+    """Pure classification of one namespace-relative file →
+    ``(classification, target_rel_under_workspace_dir)``.
+
+    ``rel`` is POSIX-style, relative to the namespace root (e.g.
+    ``skills/caveman/SKILL.md``); for ``.local`` it carries the ``state/…``
+    tail (e.g. ``state/cc-switch/cc-switchd.log``).
+    """
+    files, prefixes, transient_files, transient_prefixes = ALLOWLIST[namespace]
+    name = rel.rsplit("/", 1)[-1]
+
+    if name in transient_files or any(rel.startswith(p) for p in transient_prefixes):
+        return ENTRY_TRANSIENT, ""
+
+    if namespace == ".local":
+        # Only the cc-switch daemon subtree is in scope; its allowlist is all
+        # transient, so anything else here is unknown.
+        return ENTRY_UNKNOWN, ""
+
+    if namespace == ".aisc":
+        # Explicit file map only (state → runtime/, config → ws-dir root).
+        exact = TARGET_FILES.get(f".aisc/{rel}", "")
+        if exact:
+            return ENTRY_OWNED, exact
+        return ENTRY_UNKNOWN, ""
+
+    # Agent namespaces (.claude/.codex/.cc-switch): exact root files plus
+    # allowlisted subtrees map under workspaces/<hash>/<namespace-dir>/.
+    target_dir = TARGET_DIRS.get(namespace, "")
+    if not target_dir:
+        return ENTRY_UNKNOWN, ""
+    if (name in files and "/" not in rel) or any(rel.startswith(p) for p in prefixes):
+        return ENTRY_OWNED, f"{target_dir}/{rel}"
+    return ENTRY_UNKNOWN, ""
+
+
+@dataclass
+class MigrationEntry:
+    """One classified file (scan draft) / migrated file (7d status update).
+
+    Deliberately mutable (unlike the resolver results): the migration
+    journal advances ``status`` as prepare/copy/commit/rollback proceed.
+    """
+
+    relative: str            # workspace-relative POSIX path, e.g. ".cc-switch/settings.json"
+    classification: str      # ENTRY_*
+    sha256: str = ""
+    size: int = 0
+    target: str = ""         # rel path under workspaces/<hash>/ ("" = not migrated)
+    status: str = STATUS_PENDING
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            "relative": self.relative,
+            "classification": self.classification,
+            "size": self.size,
+            "status": self.status,
+        }
+        if self.sha256:
+            d["sha256"] = self.sha256
+        if self.target:
+            d["target"] = self.target
+        return d
+
+    @classmethod
+    def from_dict(cls, raw: Dict[str, Any]) -> "MigrationEntry":
+        if not isinstance(raw, dict):
+            raise ValueError("migration entry must be a JSON object")
+        classification = raw.get("classification", "")
+        if classification not in ENTRY_CLASSIFICATIONS:
+            raise ValueError(f"unsupported entry classification: {classification!r}")
+        return cls(
+            relative=raw.get("relative", ""),
+            classification=classification,
+            sha256=raw.get("sha256", ""),
+            size=int(raw.get("size", 0)),
+            target=raw.get("target", ""),
+            status=raw.get("status", STATUS_PENDING),
+        )
+
+
+@dataclass
+class MigrationManifest:
+    """``aisc.data-migration/v1`` — the migration boundary: rollback only
+    touches what this manifest lists; unknown fields fail closed."""
+
+    schema: str = MIGRATION_PROTOCOL
+    schema_version: int = MIGRATION_SCHEMA_VERSION
+    workspace_hash: str = ""
+    source: str = ""         # legacy workspace root (abs)
+    target: str = ""         # data-root workspaces/<hash>/ (abs)
+    entries: List[MigrationEntry] = field(default_factory=list)
+    # Namespace dirs where this migration wrote a redirect marker (rollback
+    # removes them). Dataclass field ordering: keep after entries.
+    markers: List[str] = field(default_factory=list)
+    state: str = STATE_PREPARED
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "schema": self.schema,
+            "schema_version": self.schema_version,
+            "workspace_hash": self.workspace_hash,
+            "source": self.source,
+            "target": self.target,
+            "entries": [e.to_dict() for e in self.entries],
+            "markers": list(self.markers),
+            "state": self.state,
+        }
+
+    @classmethod
+    def from_dict(cls, raw: Dict[str, Any]) -> "MigrationManifest":
+        if not isinstance(raw, dict):
+            raise ValueError("migration manifest must be a JSON object")
+        if raw.get("schema") != MIGRATION_PROTOCOL:
+            raise ValueError(f"unsupported manifest schema: {raw.get('schema')!r}")
+        version = raw.get("schema_version", MIGRATION_SCHEMA_VERSION)
+        if version != MIGRATION_SCHEMA_VERSION:
+            raise ValueError(f"unsupported schema_version: {version}")
+        state = raw.get("state", STATE_PREPARED)
+        if state not in MANIFEST_STATES:
+            raise ValueError(f"unsupported manifest state: {state!r}")
+        return cls(
+            schema=MIGRATION_PROTOCOL,
+            schema_version=version,
+            workspace_hash=raw.get("workspace_hash", ""),
+            source=raw.get("source", ""),
+            target=raw.get("target", ""),
+            entries=[MigrationEntry.from_dict(e) for e in raw.get("entries", [])],
+            markers=list(raw.get("markers", [])),
+            state=state,
+        )