drowse.ai 5.3.1__py3-none-any.whl

drowse/io/manifold_folder.py

@@ -0,0 +1,1854 @@
+"""On-disk format core for manifold-steering artifacts.
+
+The dataclasses (:class:`ManifoldFolder` / :class:`ManifoldSidecar`),
+integrity/sha256 helpers, ``manifold.json`` load/save, and the shared
+module-private validators + payload builders that the authoring and
+lifecycle layers both reuse.  This is the dependency root of the split —
+both :mod:`drowse.io.manifold_authoring` and
+:mod:`drowse.io.manifold_lifecycle` import from here.
+
+A *manifold* is a set of labeled nodes — each node a small corpus of
+responses — placed at authoring coordinates on a :class:`ManifoldDomain`
+(an n-dimensional intrinsic manifold of some topology: a box/disk, a
+cylinder, a torus, a sphere, or an explicit immersion).  Fitting a
+manifold against a model produces a per-model RBF artifact (see
+:mod:`drowse.core.manifold`).  Manifolds live under their own root,
+``~/.drowse/manifolds/<ns>/<name>/``. A manifold carries N labeled nodes on a
+domain; a two-node flat manifold is the bipolar-concept case.
+
+```
+~/.drowse/manifolds/<ns>/<name>/
+  manifold.json               # name, description, domain spec, nodes
+  nodes/NN_<label>.json       # one zero-padded file per node: a JSON list
+                              # of statement strings
+  <safe_model>.safetensors    # fitted per-model RBF (+ .json sidecar)
+  <safe_model>_sae-<rel>.safetensors   # SAE-feature-space variant
+```
+
+The user authors ``manifold.json`` (each node carries a ``label`` and its
+authoring ``coords``) and the ``nodes/*.json`` corpus files by hand;
+``drowse manifold fit`` produces the per-model tensors and
+back-fills the ``files`` integrity manifest.  Tensor save/load itself
+lives in :mod:`drowse.io.manifold_tensors` (``save_manifold`` / ``load_manifold``);
+this module owns folder discovery, the node corpus, and integrity.
+"""
+from __future__ import annotations
+
+from contextlib import ExitStack, contextmanager
+from collections.abc import Mapping
+import hashlib
+import json
+import math
+import re
+import warnings
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+import torch
+
+from drowse.core.errors import DrowseError
+from drowse.core.manifold import BoxDomain, domain_from_spec
+from drowse.core.role_templates import _ROLE_SLUG_RE
+from drowse.io.atomic import write_json_atomic
+from drowse.io.integrity import NAME_REGEX, hash_file, verify_integrity
+
+# Manifold node *labels* are stricter than the artifact ``NAME_REGEX``
+# (``io.packs``): they drop ``.`` because the dot is reserved as the
+# bipolar-pole separator (``deer.wolf``) and the steering-expr lexer
+# addresses a label via ``%label`` — a dotted label could neither be
+# typed unambiguously (``persona%a.b`` reads ``a`` dotted with pole ``b``)
+# nor resolved through the bare-name pipeline.  Labels are therefore the
+# grammar-addressable identifier subset of the name grammar: lowercase
+# start, then ``[a-z0-9_-]`` only, ≤64 chars.  The manifold *name*
+# itself keeps ``NAME_REGEX`` (it is never used as a ``%`` operand).
+_LABEL_REGEX = re.compile(r"^[a-z][a-z0-9_-]{0,63}$")
+
+# Discover-mode fit modes — set as ``manifold.json::fit_mode`` for
+# manifolds whose node coordinates are derived from the model's
+# activations rather than authored by hand.  Authored manifolds carry
+# ``fit_mode == "authored"``. Current manifests always carry the discriminator.
+# ``auto`` is a discover mode whose *resolved* geometry (flat ``pca`` vs curved
+# ``spectral``, plus periodic ``BoxDomain`` axes) is chosen per-model at fit
+# time by ``core.manifold.select_topology`` — the folder declares only the
+# corpus + hyperparams, exactly like ``pca``/``spectral``.
+_FIT_MODES_DISCOVER: frozenset[str] = frozenset({"pca", "spectral", "auto"})
+# A baked manifold is a pre-fitted, corpus-less artifact: its geometry is
+# frozen in the per-model tensor and it can never re-fit (no node corpus to
+# pool from).  Merge outputs and imported control vectors land this way — a
+# steering *direction* is the K=1 affine case (see
+# ``core/capture.fold_directions_to_subspace``).  It is deliberately NOT a
+# discover mode (``is_discover`` stays False — there are no per-model coords
+# to derive).
+_FIT_MODES_BAKED: frozenset[str] = frozenset({"baked"})
+_FIT_MODES_ALL: frozenset[str] = (
+    frozenset({"authored"}) | _FIT_MODES_DISCOVER | _FIT_MODES_BAKED
+)
+MERGE_BAKE_POLICY = "additive_union_v1"
+
+
+@contextmanager
+def _locked_manifest(folder: Path):
+    """Serialize cross-process manifest read-modify-write for one folder."""
+    from drowse.io.atomic import artifact_lock
+
+    with artifact_lock(folder.parent / f"{folder.name}.manifest"):
+        yield
+
+
+def manifold_pair_lock_path(tensor_path: Path) -> Path:
+    """Stable, bounded logical lock path for one fitted tensor pair.
+
+    The lock lives under the manifold namespace rather than inside the
+    removable manifold folder.  Consequently ``rm`` and stage-swap refreshes
+    cannot unlink the held lock inode and let a later process acquire a fresh
+    inode for the same logical pair.  The digest also bounds the filename for
+    long model/release-derived tensor names.
+    """
+
+    tensor_path = Path(tensor_path).expanduser().resolve(strict=False)
+    identity = f"{tensor_path.parent}\0{tensor_path.name}".encode()
+    digest = hashlib.sha256(identity).hexdigest()
+    return tensor_path.parent.parent / f".drowse-pair-{digest}"
+
+
+@contextmanager
+def manifold_pair_lock(tensor_path: Path):
+    """Lock a fitted tensor/sidecar pair using stable external identity."""
+
+    from drowse.io.atomic import artifact_lock
+
+    with artifact_lock(manifold_pair_lock_path(tensor_path)):
+        yield
+
+
+def manifold_folder_tensor_paths(folder: Path) -> list[Path]:
+    """Return canonical tensor paths for every fitted/orphan pair in ``folder``.
+
+    Destructive folder replacement cannot trust ``manifold.json::files``: the
+    operation is also the recovery path for an interrupted publication whose
+    tensor or sidecar never acquired a manifest proof.  Scan both halves and
+    canonicalize sidecars back to their tensor path so each logical pair is
+    locked exactly once.
+    """
+
+    from drowse.io.paths import parse_tensor_filename
+
+    folder = Path(folder)
+    candidates = list(folder.glob("*.safetensors")) + [
+        sidecar
+        for sidecar in folder.glob("*.json")
+        if sidecar.name != "manifold.json"
+    ]
+    tensors: set[Path] = set()
+    for candidate in candidates:
+        tensor = (
+            candidate.with_suffix(".safetensors")
+            if candidate.suffix == ".json" else candidate
+        )
+        if parse_tensor_filename(tensor.name) is not None:
+            tensors.add(tensor)
+    return sorted(tensors)
+
+
+@contextmanager
+def destructive_manifold_folder_transaction(folder: Path):
+    """Quiesce fitted readers before a whole-folder reset or stage swap.
+
+    Global mutation order is manifest then stable pair locks, with pair locks in
+    deterministic tensor-path order.  The pair locks live outside the removable
+    folder, so holding this context across ``rmtree``/rename/recreation prevents
+    a new inode from bypassing a reader that still owns the old logical pair.
+    The manifest lock is re-entrant, allowing authoring entry points that already
+    serialize their destination to use this one shared destructive seam.
+    """
+
+    folder = Path(folder)
+    with _locked_manifest(folder):
+        with ExitStack() as stack:
+            for tensor_path in manifold_folder_tensor_paths(folder):
+                stack.enter_context(manifold_pair_lock(tensor_path))
+            yield
+
+
+def reset_manifold_folder(folder: Path) -> None:
+    """Remove ``folder`` only after all extant fitted pairs are quiescent."""
+
+    import shutil
+
+    folder = Path(folder)
+    with destructive_manifold_folder_transaction(folder):
+        if folder.exists():
+            shutil.rmtree(folder)
+
+# Per-method hyperparameter whitelists.  Anything outside the whitelist
+# for a given fit_mode is dropped at folder-create time so a user
+# POSTing ``{fit_mode: "pca", hyperparams: {"k_nn": 5}}`` doesn't land
+# a foreign key that would then crash ``derive_pca_coords`` at fit
+# time with ``TypeError: unexpected keyword argument``.  ``max_dim``
+# is shared.  Coordinate derivation is layer-agnostic — the consensus
+# Gram averages every fit layer (``ManifoldExtractionPipeline.fit``), so
+# there is no reference-layer knob.
+# ``max_dim`` caps the derived intrinsic (layout) dim for both modes.  A
+# flat (``pca``) fit's per-layer steerable subspace *is* its k-dim layout
+# span, so ``max_dim`` is its only dim knob — there is no separate
+# ``max_subspace_dim`` for pca (the subspace dim equals the layout dim).
+# ``max_subspace_dim`` survives only for the curved (``spectral``) fit,
+# where the per-layer RBF subspace can carry off-surface dims beyond the
+# intrinsic coordinate count.  ``min_dim`` (spectral only) floors the
+# layout dim the eigenvalue-ratio cliff derives — for an authored-
+# dimensionality manifold (PAD's P×A×D) the cliff undershoots when one
+# mode dominates the spectrum, so the floor keeps the declared geometry
+# (set ``min_dim == max_dim`` to pin the dim exactly).  The steer-time
+# origin is always the projection of the per-model neutral mean onto the
+# subspace (the affine fit neutral-anchors the frame), so there is no
+# ``anchor_origin`` knob.
+_HYPERPARAMS_BY_MODE: dict[str, frozenset[str]] = {
+    "pca": frozenset({
+        "max_dim", "var_threshold",
+    }),
+    "spectral": frozenset({
+        "max_dim", "min_dim", "k_nn", "bandwidth", "max_subspace_dim",
+        "smoothing",
+    }),
+    # ``auto`` routes to ``select_topology`` (flat/curved by GCV + periodic by
+    # persistent homology); it accepts the union of the knobs its candidate
+    # fits consume — ``max_dim`` (layout dim cap), ``smoothing`` (curved-fit
+    # GCV λ), ``persistence_frac`` (H1 loop-significance threshold), plus the
+    # spectral graph knobs and ``max_subspace_dim`` for a resolved curved fit.
+    "auto": frozenset({
+        "max_dim", "var_threshold", "min_dim", "k_nn", "bandwidth",
+        "max_subspace_dim", "smoothing", "persistence_frac",
+    }),
+}
+
+
+def domain_label(spec: dict[str, Any]) -> str:
+    """Short ``type(Nd)`` label for a manifold domain spec dict."""
+    kind = spec.get("type", "?")
+    if kind == "klein":
+        return "Klein bottle (2D)"
+    if kind == "projective":
+        return "Projective plane / RP² (2D)"
+    if kind == "box":
+        n = len(spec.get("axes", []))
+    elif kind == "sphere":
+        n = int(spec.get("dim", 0))
+    elif kind == "custom":
+        n = int(spec.get("embed_dim", 0))
+    else:
+        n = 0
+    return f"{kind}({n}d)"
+
+
+def sanitize_hyperparams(
+    fit_mode: str, hyperparams: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Validate and return hyperparameters for one exact fit mode.
+
+    Single source of truth for the per-method whitelist; both the create
+    and the fit-override paths funnel through this so the folder
+    manifest never accepts a key that the selected dispatcher would ignore.
+    """
+    if hyperparams is None:
+        return {}
+    allowed = _HYPERPARAMS_BY_MODE.get(fit_mode)
+    if allowed is None:
+        raise ManifoldFormatError(f"unknown fit_mode {fit_mode!r}")
+    invalid = set(hyperparams) - allowed
+    if invalid:
+        names = ", ".join(sorted(invalid))
+        raise ManifoldFormatError(
+            f"fit_mode {fit_mode!r} does not accept hyperparameter(s): {names}"
+        )
+    int_keys = {"max_dim", "min_dim", "k_nn", "max_subspace_dim"}
+    float_keys = {"var_threshold", "bandwidth", "persistence_frac"}
+    for key, value in hyperparams.items():
+        valid = (
+            isinstance(value, int) and not isinstance(value, bool) and value > 0
+            if key in int_keys else
+            _finite_number(value)
+            if key in float_keys else
+            value == "auto" or _finite_number(value)
+            if key == "smoothing" else False
+        )
+        if not valid:
+            raise ManifoldFormatError(
+                f"fit_mode {fit_mode!r} hyperparameter {key!r} has invalid "
+                f"value {value!r}"
+            )
+    return dict(hyperparams)
+
+
+# Current manifold artifact format. v10 splits the fit's capture identity into
+# separately provable halves — ``capture_version`` + ``capture_render_sha256``
+# (the tokenizer render, reproducible from tokenizer + prompts + corpus alone)
+# alongside ``model_source_fingerprint`` (the pre-load-verifiable checkpoint
+# identity) and ``baseline_prompts_sha256`` — so a fit no-op can be *proven*
+# without loading weights (:func:`drowse.io.manifold_lifecycle.
+# preflight_manifold_fit_noop`).  A v9 sidecar carries none of them, so it
+# cannot be proven and reads as an ordinary cache miss.
+# v7 made manifest defaults and per-node provenance explicit, yielding one
+# canonical payload shape. v6 added an optional per-layer ``affine_map`` tensor
+# for flat fitted subspaces.  Ordinary fits omit it (identity);
+# rectangular/non-isometric cross-model transfers persist the exact
+# authoring-to-orthonormal-reduced reparameterization.  Old readers would
+# otherwise ignore that tensor and silently move manifold world points, so this
+# is a real format boundary.
+MANIFOLD_FORMAT_VERSION = 10
+
+MANIFOLD_SIDECAR_FIELDS = {
+    "format_version", "name", "method", "drowse_version", "domain",
+    "node_count", "node_labels", "feature_space", "fit_mode", "hyperparams",
+    "diagnostics", "node_spread_per_layer", "mahalanobis_share_per_layer",
+    "origin_per_layer", "nodes_sha256", "sae_release", "sae_revision",
+    "sae_fingerprint", "sae_ids_by_layer", "sae_full_coverage",
+    "model_fingerprint", "model_source_fingerprint", "capture_sha256",
+    "capture_version", "context_binding_sha256", "capture_render_sha256",
+    "baseline_prompts_sha256",
+    "fitted_layers",
+    "fit_policy_version", "share_metric", "subspace_metric",
+    "rbf_smoothing_per_layer", "sigma_field_per_layer", "resolved_fit_mode",
+    "topology_winner", "topology_candidates", "node_roles", "node_kinds",
+    "components", "bake_policy", "source_model_id",
+    "source_model_fingerprint", "transfer_quality_estimate",
+}
+
+MANIFOLD_METHOD_FIT_MODES: dict[str, frozenset[str]] = {
+    "manifold_pca": frozenset({"authored"}),
+    "manifold_sae": frozenset({"authored"}),
+    # Older monopolar sidecars inherited the writer's authored default because
+    # the early-return fit branch omitted its source-manifest provenance.
+    # Current writers correctly retain the one-node discover-pca identity.
+    "manifold_monopolar": frozenset({"authored", "pca"}),
+    "manifold_monopolar_sae": frozenset({"authored", "pca"}),
+    "manifold_discover_auto": frozenset({"auto"}),
+    "manifold_discover_pca": frozenset({"pca"}),
+    "manifold_discover_spectral": frozenset({"spectral"}),
+    "manifold_discover_sae": frozenset({"pca", "spectral", "auto"}),
+    "manifold_procrustes_transfer": frozenset(_FIT_MODES_ALL),
+    "merge": frozenset({"baked"}),
+    "folded_vector": frozenset({"baked"}),
+}
+
+
+def _is_sha256_digest(value: Any) -> bool:
+    """True for a canonical lowercase 64-hex sha256 digest."""
+    return (
+        isinstance(value, str)
+        and len(value) == 64
+        and all(char in "0123456789abcdef" for char in value)
+    )
+
+
+def _finite_number(value: Any) -> bool:
+    return (
+        not isinstance(value, bool)
+        and isinstance(value, (int, float))
+        and math.isfinite(float(value))
+    )
+
+
+def _validate_layer_map(
+    value: Any, *, location: str, field: str, fitted: set[int],
+    validate_value: Any, require_fitted: bool = True,
+) -> None:
+    if not isinstance(value, dict):
+        raise ManifoldFormatError(f"{location} field {field!r} must be an object")
+    for raw_layer, item in value.items():
+        if (
+            not isinstance(raw_layer, str)
+            or not raw_layer.isascii()
+            or not raw_layer.isdecimal()
+            or str(int(raw_layer)) != raw_layer
+            or require_fitted and int(raw_layer) not in fitted
+        ):
+            raise ManifoldFormatError(
+                f"{location} field {field!r} has invalid fitted-layer key {raw_layer!r}"
+            )
+        if not validate_value(item):
+            raise ManifoldFormatError(
+                f"{location} field {field!r} has invalid value for layer {raw_layer}"
+            )
+
+
+def _validate_hyperparams(data: dict[str, Any], *, location: str) -> None:
+    params = data["hyperparams"]
+    mode = data["fit_mode"]
+    if not isinstance(params, dict):
+        raise ManifoldFormatError(f"{location} hyperparams must be an object")
+    if mode in {"authored", "baked"}:
+        if params:
+            raise ManifoldFormatError(f"{location} {mode} fit cannot carry hyperparams")
+        return
+    sanitize_hyperparams(mode, params)
+    int_keys = {"max_dim", "min_dim", "k_nn", "max_subspace_dim"}
+    float_keys = {"var_threshold", "bandwidth", "persistence_frac"}
+    for key, value in params.items():
+        valid = (
+            isinstance(value, int) and not isinstance(value, bool) and value > 0
+            if key in int_keys else
+            _finite_number(value)
+            if key in float_keys else
+            value == "auto" or _finite_number(value)
+            if key == "smoothing" else False
+        )
+        if not valid:
+            raise ManifoldFormatError(
+                f"{location} hyperparameter {key!r} has invalid value {value!r}"
+            )
+
+
+def _validate_diagnostics(value: Any, *, location: str) -> None:
+    if not isinstance(value, dict):
+        raise ManifoldFormatError(f"{location} diagnostics must be an object")
+    allowed = {
+        "per_component_variance", "cumulative_variance", "eigenvalues",
+        "picked_k", "gap_index", "k_nn", "component_count", "heuristic_k",
+        "threshold", "gap_magnitude", "bandwidth", "pinned", "min_dim",
+    }
+    if set(value) - allowed:
+        raise ManifoldFormatError(f"{location} diagnostics has unknown fields")
+    list_keys = {"per_component_variance", "cumulative_variance", "eigenvalues"}
+    int_keys = {"picked_k", "gap_index", "k_nn", "component_count", "heuristic_k", "min_dim"}
+    for key, item in value.items():
+        valid = (
+            isinstance(item, list) and bool(item) and all(_finite_number(v) for v in item)
+            if key in list_keys else
+            isinstance(item, int) and not isinstance(item, bool) and item >= 0
+            if key in int_keys else
+            isinstance(item, bool)
+            if key == "pinned" else
+            _finite_number(item)
+        )
+        if not valid:
+            raise ManifoldFormatError(f"{location} diagnostics field {key!r} is invalid")
+
+
+def _validate_topology_candidates(value: Any, *, location: str) -> None:
+    if not isinstance(value, list):
+        raise ManifoldFormatError(f"{location} topology_candidates must be an array")
+    fields = {"name", "fit_mode", "intrinsic_dim", "score", "viable", "reason"}
+    for candidate in value:
+        if not isinstance(candidate, dict) or set(candidate) != fields:
+            raise ManifoldFormatError(f"{location} has invalid topology candidate schema")
+        if (
+            not isinstance(candidate["name"], str) or not candidate["name"]
+            or candidate["fit_mode"] not in {"pca", "spectral"}
+            or isinstance(candidate["intrinsic_dim"], bool)
+            or not isinstance(candidate["intrinsic_dim"], int)
+            or candidate["intrinsic_dim"] < 1
+            or candidate["score"] is not None and not _finite_number(candidate["score"])
+            or not isinstance(candidate["viable"], bool)
+            or candidate["reason"] is not None and not isinstance(candidate["reason"], str)
+        ):
+            raise ManifoldFormatError(f"{location} has invalid topology candidate values")
+
+
+def _validate_components(value: Any, *, location: str) -> None:
+    if value is None:
+        return
+    if not isinstance(value, dict) or not value:
+        raise ManifoldFormatError(f"{location} components must be null or non-empty object")
+    fields = {"selector", "alpha", "tensor_sha256"}
+    for coord, item in value.items():
+        if (
+            not isinstance(coord, str) or not coord
+            or not isinstance(item, dict) or set(item) != fields
+            or not isinstance(item["selector"], str) or not item["selector"]
+            or not _finite_number(item["alpha"])
+            or (
+                not isinstance(item["tensor_sha256"], str)
+                or len(item["tensor_sha256"]) != 64
+                or any(c not in "0123456789abcdef" for c in item["tensor_sha256"])
+            )
+        ):
+            raise ManifoldFormatError(f"{location} has invalid component provenance")
+
+
+def validate_manifold_sidecar_payload(
+    data: Any, *, location: str = "manifold sidecar",
+) -> dict[str, Any]:
+    """Validate every field of the exact current fitted-sidecar contract."""
+    from drowse.io.brand_migration import LEGACY_NAMES, migrate_legacy_record
+
+    legacy_brand = isinstance(data, dict) and any(
+        f"{name}_version" in data for name in LEGACY_NAMES
+    )
+    data = migrate_legacy_record(data)
+    if (
+        legacy_brand
+        and set(data) == MANIFOLD_SIDECAR_FIELDS - {"context_binding_sha256"}
+        and data["fit_mode"] == "baked"
+    ):
+        # Original baked artifacts cannot be refitted. An absent context-binding
+        # proof means unknown, never a verified context binding.
+        data["context_binding_sha256"] = None
+    if not isinstance(data, dict) or set(data) != MANIFOLD_SIDECAR_FIELDS:
+        raise ManifoldFormatError(f"{location} does not match the current exact schema")
+    validate_manifold_format_version(data["format_version"], location=location)
+    from drowse.core.manifold import validate_domain_spec
+
+    validate_domain_spec(data["domain"])
+    for key in ("name", "method", "drowse_version", "feature_space", "fit_mode"):
+        if not isinstance(data[key], str) or not data[key]:
+            raise ManifoldFormatError(f"{location} field {key!r} must be non-empty str")
+    if data["fit_mode"] not in _FIT_MODES_ALL:
+        raise ManifoldFormatError(f"{location} has invalid fit_mode")
+    allowed_fit_modes = MANIFOLD_METHOD_FIT_MODES.get(data["method"])
+    if allowed_fit_modes is None or data["fit_mode"] not in allowed_fit_modes:
+        raise ManifoldFormatError(
+            f"{location} has invalid method/fit_mode combination"
+        )
+    labels = data["node_labels"]
+    if (
+        isinstance(data["node_count"], bool)
+        or not isinstance(data["node_count"], int)
+        or not isinstance(labels, list)
+        or not labels
+        or data["node_count"] != len(labels)
+        or any(not isinstance(label, str) or not _LABEL_REGEX.match(label) for label in labels)
+        or len(set(labels)) != len(labels)
+    ):
+        raise ManifoldFormatError(f"{location} has invalid node identity")
+    _validate_hyperparams(data, location=location)
+    _validate_diagnostics(data["diagnostics"], location=location)
+    if not isinstance(data["sae_full_coverage"], bool):
+        raise ManifoldFormatError(f"{location} sae_full_coverage must be bool")
+    nullable_strings = (
+        "nodes_sha256", "sae_release", "sae_revision", "sae_fingerprint",
+        "model_fingerprint", "model_source_fingerprint", "capture_sha256",
+        "share_metric",
+        "subspace_metric", "resolved_fit_mode", "topology_winner",
+        "bake_policy", "source_model_id", "source_model_fingerprint",
+    )
+    if any(
+        data[key] is not None and (not isinstance(data[key], str) or not data[key])
+        for key in nullable_strings
+    ):
+        raise ManifoldFormatError(f"{location} has invalid nullable string metadata")
+    # The two preflight-provable digests are always writer-produced sha256, so
+    # they are held to the exact digest grammar rather than "non-empty string":
+    # a preflight that compares a recomputed digest against a malformed stored
+    # one must fail loudly at load, not quietly mismatch forever.
+    if any(
+        data[key] is not None and not _is_sha256_digest(data[key])
+        for key in (
+            "context_binding_sha256", "capture_render_sha256",
+            "baseline_prompts_sha256",
+        )
+    ):
+        raise ManifoldFormatError(f"{location} has invalid capture digest metadata")
+    if data["capture_version"] is not None and (
+        isinstance(data["capture_version"], bool)
+        or not isinstance(data["capture_version"], int)
+        or data["capture_version"] < 0
+    ):
+        raise ManifoldFormatError(f"{location} has invalid capture_version")
+    if data["fit_policy_version"] is not None and (
+        isinstance(data["fit_policy_version"], bool)
+        or not isinstance(data["fit_policy_version"], int)
+        or data["fit_policy_version"] < 0
+    ):
+        raise ManifoldFormatError(f"{location} has invalid fit_policy_version")
+    quality = data["transfer_quality_estimate"]
+    if quality is not None and (
+        isinstance(quality, bool)
+        or not isinstance(quality, (int, float))
+        or not math.isfinite(float(quality))
+    ):
+        raise ManifoldFormatError(f"{location} has invalid transfer quality")
+    fitted = data["fitted_layers"]
+    if (
+        not isinstance(fitted, list)
+        or any(isinstance(v, bool) or not isinstance(v, int) or v < 0 for v in fitted)
+        or fitted != sorted(set(fitted))
+    ):
+        raise ManifoldFormatError(f"{location} has invalid fitted_layers")
+    fitted_set = set(fitted)
+    # ``node_spread_per_layer`` is measured before DLS prunes axes/layers, so
+    # it records the complete *evaluated* layer roster.  Its keys may therefore
+    # be a strict superset of ``fitted_layers`` (the exact tensor roster).
+    # Keeping that distinction is what lets a cache prove that a dropped layer
+    # was evaluated rather than accidentally omitted.  Apply-time bakes remain
+    # tensor-bound and must use fitted-layer keys only.
+    _validate_layer_map(
+        data["node_spread_per_layer"], location=location,
+        field="node_spread_per_layer", fitted=fitted_set,
+        validate_value=lambda value: _finite_number(value) and float(value) >= 0,
+        require_fitted=False,
+    )
+    _validate_layer_map(
+        data["mahalanobis_share_per_layer"], location=location,
+        field="mahalanobis_share_per_layer", fitted=fitted_set,
+        validate_value=lambda value: _finite_number(value) and float(value) >= 0,
+    )
+    _validate_layer_map(
+        data["origin_per_layer"], location=location, field="origin_per_layer",
+        fitted=fitted_set,
+        validate_value=lambda value: (
+            isinstance(value, list) and bool(value)
+            and all(_finite_number(coord) for coord in value)
+        ),
+    )
+    _validate_layer_map(
+        data["sae_ids_by_layer"], location=location, field="sae_ids_by_layer",
+        fitted=fitted_set,
+        validate_value=lambda value: (
+            isinstance(value, str) and bool(value)
+        ),
+        require_fitted=False,
+    )
+    _validate_layer_map(
+        data["rbf_smoothing_per_layer"], location=location,
+        field="rbf_smoothing_per_layer", fitted=fitted_set,
+        validate_value=lambda value: (
+            isinstance(value, dict) and set(value) == {"lambda", "edf", "gcv"}
+            and all(_finite_number(item) for item in value.values())
+        ),
+    )
+    _validate_layer_map(
+        data["sigma_field_per_layer"], location=location,
+        field="sigma_field_per_layer", fitted=fitted_set,
+        validate_value=lambda value: (
+            isinstance(value, dict)
+            and set(value) == {"sigma_mean", "sigma_min", "sigma_max", "lambda"}
+            and all(_finite_number(item) and float(item) >= 0 for item in value.values())
+        ),
+    )
+    roles, kinds = data["node_roles"], data["node_kinds"]
+    if not isinstance(roles, list) or not isinstance(kinds, list) or len(roles) != len(labels) or len(kinds) != len(labels):
+        raise ManifoldFormatError(f"{location} node provenance is misaligned")
+    for label, role, kind in zip(labels, roles, kinds, strict=True):
+        _validate_node_role(data["name"], label, role)
+        _validate_node_kind(data["name"], label, kind)
+    _validate_topology_candidates(data["topology_candidates"], location=location)
+    _validate_components(data["components"], location=location)
+    is_auto = data["fit_mode"] == "auto"
+    if is_auto != bool(
+        data["resolved_fit_mode"] is not None
+        and data["topology_winner"] is not None
+        and data["topology_candidates"]
+    ):
+        raise ManifoldFormatError(f"{location} has inconsistent auto-topology provenance")
+    if not is_auto and any(
+        value is not None
+        for value in (data["resolved_fit_mode"], data["topology_winner"])
+    ) or not is_auto and data["topology_candidates"]:
+        raise ManifoldFormatError(f"{location} non-auto fit carries topology provenance")
+    is_merge = data["method"] == "merge"
+    if is_merge:
+        if data["fit_mode"] != "baked" or data["components"] is None or data["bake_policy"] != MERGE_BAKE_POLICY:
+            raise ManifoldFormatError(f"{location} has incomplete merge provenance")
+    elif data["components"] is not None or data["bake_policy"] is not None:
+        raise ManifoldFormatError(f"{location} non-merge fit carries merge provenance")
+    is_transfer = data["method"] == "manifold_procrustes_transfer"
+    transfer_values = (
+        data["source_model_id"], data["source_model_fingerprint"],
+        data["transfer_quality_estimate"],
+    )
+    if is_transfer:
+        if transfer_values[0] is None or transfer_values[1] is None:
+            raise ManifoldFormatError(f"{location} has incomplete transfer provenance")
+    elif any(value is not None for value in transfer_values):
+        raise ManifoldFormatError(f"{location} non-transfer fit carries transfer provenance")
+    sae_values = (
+        data["sae_release"], data["sae_revision"], data["sae_fingerprint"],
+    )
+    if data["feature_space"] == "raw":
+        if any(value is not None for value in sae_values) or data["sae_ids_by_layer"] or data["sae_full_coverage"]:
+            raise ManifoldFormatError(f"{location} raw fit carries SAE provenance")
+    elif (
+        not data["feature_space"].startswith("sae-")
+        or data["sae_release"] is None
+        or not data["sae_ids_by_layer"]
+    ):
+        raise ManifoldFormatError(f"{location} has incomplete SAE provenance")
+    return data
+
+
+def canonical_manifold_sidecar_payload(
+    *, name: str, method: str, drowse_version: str, domain: dict[str, Any],
+    node_labels: list[str], feature_space: str, fit_mode: str,
+    hyperparams: dict[str, Any] | None = None,
+    diagnostics: dict[str, Any] | None = None,
+    node_spread_per_layer: dict[str, Any] | None = None,
+    fitted_layers: list[int] | None = None,
+    semantic_metadata: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build the one exact current fitted-manifold sidecar shape."""
+    count = len(node_labels)
+    payload = {
+        "format_version": MANIFOLD_FORMAT_VERSION,
+        "name": name, "method": method, "drowse_version": drowse_version,
+        "domain": domain, "node_count": count, "node_labels": node_labels,
+        "feature_space": feature_space, "fit_mode": fit_mode,
+        "hyperparams": dict(hyperparams or {}),
+        "diagnostics": dict(diagnostics or {}),
+        "node_spread_per_layer": dict(node_spread_per_layer or {}),
+        "mahalanobis_share_per_layer": {}, "origin_per_layer": {},
+        "nodes_sha256": None, "sae_release": None, "sae_revision": None,
+        "sae_fingerprint": None, "sae_ids_by_layer": {},
+        "sae_full_coverage": False, "model_fingerprint": None,
+        "model_source_fingerprint": None,
+        "capture_sha256": None, "capture_version": None,
+        "context_binding_sha256": None, "capture_render_sha256": None,
+        "baseline_prompts_sha256": None,
+        "fitted_layers": list(fitted_layers or []),
+        "fit_policy_version": None, "share_metric": None,
+        "subspace_metric": None, "rbf_smoothing_per_layer": {},
+        "sigma_field_per_layer": {}, "resolved_fit_mode": None,
+        "topology_winner": None, "topology_candidates": [],
+        "node_roles": [None] * count, "node_kinds": [None] * count,
+        "components": None, "bake_policy": None, "source_model_id": None,
+        "source_model_fingerprint": None, "transfer_quality_estimate": None,
+    }
+    for key in (
+        "sae_release", "sae_revision", "sae_fingerprint", "sae_ids_by_layer",
+        "sae_full_coverage", "resolved_fit_mode", "topology_winner",
+        "topology_candidates", "components", "bake_policy", "source_model_id",
+        "source_model_fingerprint", "transfer_quality_estimate",
+        "context_binding_sha256",
+    ):
+        if semantic_metadata is not None and key in semantic_metadata:
+            payload[key] = semantic_metadata[key]
+    return validate_manifold_sidecar_payload(payload)
+
+
+def _validate_node_role(name: str, label: str, role: Any) -> str | None:
+    """Validate an optional per-node ``role`` field.
+
+    ``None`` means "use the standard assistant baseline". A non-empty string must match
+    :data:`drowse.core.role_templates._ROLE_SLUG_RE`
+    (``[a-z0-9._-]+``).  Family-unsupported (Mistral-3) is *not*
+    checked here — the folder is model-agnostic; the check fires when
+    :func:`drowse.core.role_templates.apply_with_role` runs at fit time.
+    """
+    if role is None:
+        return None
+    if not isinstance(role, str) or not _ROLE_SLUG_RE.match(role):
+        raise ManifoldFormatError(
+            f"manifold {name!r} node {label!r} role {role!r} invalid; "
+            f"must match {_ROLE_SLUG_RE.pattern}"
+        )
+    return role
+
+
+_NODE_KINDS = ("abstract", "concrete", "custom")
+
+
+def _validate_node_kind(name: str, label: str, kind: Any) -> str | None:
+    """Validate an optional per-node ``kind`` field.
+
+    ``None`` means "unspecified". A non-empty value must be one of
+    :data:`_NODE_KINDS` (``"abstract"`` / ``"concrete"`` / ``"custom"``).
+    Generation-time provenance only — it selects the system template and
+    elicitation role label when authoring a node's conversational corpus
+    (``custom`` = a caller-supplied system prompt, no role swap), and never
+    feeds the fit.
+    """
+    if kind is None:
+        return None
+    if not isinstance(kind, str) or kind not in _NODE_KINDS:
+        raise ManifoldFormatError(
+            f"manifold {name!r} node {label!r} kind {kind!r} invalid; "
+            f"must be one of {_NODE_KINDS}"
+        )
+    return kind
+
+
+class ManifoldFormatError(ValueError, DrowseError):
+    """Raised when a manifold folder is malformed or fails integrity."""
+
+
+def validate_manifold_format_version(
+    value: Any, *, location: str = "manifold",
+) -> int:
+    """Validate the shared readable/writable manifold format boundary."""
+    if (
+        not isinstance(value, int)
+        or isinstance(value, bool)
+        or value != MANIFOLD_FORMAT_VERSION
+    ):
+        raise ManifoldFormatError(
+            f"{location} has format_version={value!r}; "
+            f"need exactly {MANIFOLD_FORMAT_VERSION}. Regenerate or re-fit it "
+            "with the current drowse."
+        )
+    return value
+
+
+class BakedManifoldError(ValueError, DrowseError):
+    """Raised when an operation invalid for a corpus-less baked manifold runs.
+
+    A baked manifold (``fit_mode == "baked"``) has no node corpus and its
+    geometry lives only in the per-model tensor, so a re-fit is impossible.
+    Tensor-deleting lifecycle ops (``clear``, scoped ``refresh``) would
+    therefore destroy the only copy of the geometry irreversibly — they
+    refuse with this error and point the caller at ``manifold rm`` instead.
+    """
+
+
+def min_nodes(n: int) -> int:
+    """Minimum node count for an ``n``-dimensional manifold.
+
+    ``2*n + 1`` — one center node plus two extremes per authoring axis,
+    so every axis is sampled at three levels and curvature is fittable.
+    At ``n == 1`` this is 3, the historic floor.  This is *necessary* but
+    not *sufficient*: the nodes must also be poised (affinely span the
+    embedding), which :func:`drowse.core.manifold.fit_rbf_interpolant`
+    enforces.
+    """
+    return 2 * n + 1
+
+
+def _node_filename(index: int, label: str) -> str:
+    """Canonical zero-padded node corpus filename: ``NN_<label>.json``."""
+    return f"{index:02d}_{label}.json"
+
+
+def hash_manifold_files(folder: Path) -> dict[str, str]:
+    """Return ``{relative_posix_path: sha256}`` for a manifold's fitted files.
+
+    Covers the top-level fitted artifacts (the per-model ``.safetensors``
+    tensors and their ``.json`` sidecars); skips ``manifold.json`` itself
+    and the ``nodes/`` corpus.  The node corpus is user-authored and
+    *expected* to be edited — editing it is the re-fit trigger, tracked
+    by the per-tensor ``nodes_sha256`` sidecar field — so hashing it into
+    an integrity manifest would reject the normal workflow.  Used to
+    (re)populate ``manifold.json.files`` after a fit.
+    """
+    out: dict[str, str] = {}
+    for entry in sorted(folder.iterdir()):
+        if entry.is_file() and entry.name != "manifold.json":
+            out[entry.name] = hash_file(entry)
+    return out
+
+
+def _canonical_json(obj: Any) -> bytes:
+    """Stable canonical-JSON encoding for hashing."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+@dataclass
+class ManifoldSidecar:
+    """JSON sidecar beside a fitted per-model manifold tensor.
+
+    Discover-mode fits (``fit_mode != "authored"``) additionally carry
+    the derived ``coords``, the hyperparameters used, and the per-method
+    diagnostics block (PCA variance bars or spectral spectrum) so the
+    sidecar is self-describing for downstream inspection.
+    """
+
+    # ``manifold_pca`` / ``manifold_sae`` for authored fits;
+    # ``manifold_discover_pca`` / ``manifold_discover_spectral`` /
+    # ``manifold_discover_sae`` for discover-mode fits (the SAE label
+    # collapses across pca/spectral because the SAE reconstruction
+    # rides into both before the coord derivation runs).
+    method: str
+    drowse_version: str
+    domain: dict[str, Any]
+    node_count: int
+    node_labels: list[str]
+    feature_space: str = "raw"
+    nodes_sha256: Optional[str] = None
+    sae_release: Optional[str] = None
+    sae_revision: Optional[str] = None
+    sae_fingerprint: Optional[str] = None
+    sae_ids_by_layer: dict[str, str] = field(default_factory=dict)
+    sae_full_coverage: bool = False
+    model_fingerprint: Optional[str] = None
+    # The *pre-load-verifiable* checkpoint identity
+    # (:func:`drowse.core.model.model_source_fingerprint`): resolved Hub commit
+    # or exact local file hashes, plus the load representation.  Distinct from
+    # ``source_model_fingerprint``, which names the *other* model a cross-model
+    # Procrustes transfer came from.  This one exists so a fit no-op can be
+    # proven without instantiating the transformer.
+    model_source_fingerprint: Optional[str] = None
+    capture_sha256: Optional[str] = None
+    # The two provable halves of ``capture_sha256``.  ``capture_version`` is the
+    # capture-identity schema revision (:data:`drowse.core.extraction.
+    # MANIFOLD_CAPTURE_VERSION`); ``capture_render_sha256`` digests the
+    # tokenizer-render half alone — node partition plus every rendered row's
+    # token ids and pool index — which is exactly the part reproducible from
+    # tokenizer + baseline prompts + corpus with no weights loaded.  The
+    # remaining half (model class, config, commit, load representation) is
+    # covered by ``model_fingerprint`` + ``model_source_fingerprint``.
+    capture_version: Optional[int] = None
+    capture_render_sha256: Optional[str] = None
+    # Digest of the exact shared baseline prompts (or a templated manifold's
+    # resolved contexts) the corpus rows were paired against.  Redundant with
+    # ``capture_render_sha256`` by construction, and deliberately so: a
+    # baseline-prompt edit is the failure mode a weight-free preflight most
+    # needs to name, so it gets its own directly comparable channel.
+    baseline_prompts_sha256: Optional[str] = None
+    fitted_layers: list[int] = field(default_factory=list)
+    fit_policy_version: Optional[int] = None
+    # Discover-mode-only fields.  ``None`` on authored fits.
+    fit_mode: str = "authored"
+    hyperparams: dict[str, Any] = field(default_factory=dict)
+    diagnostics: dict[str, Any] = field(default_factory=dict)
+    # Per-layer whitened between-node spread ``{str(L): tr(G_L)}`` — the
+    # concept's signal-concentration profile across the stack, in
+    # background-σ² units (comparable across layers).  A diagnostic readout
+    # of "where does this concept live", distinct from the apply-time
+    # ``mahalanobis_share`` (which restricts the same whitened spread to the
+    # steerable subspace).  Empty when the current fit has no measurements.
+    node_spread_per_layer: dict[str, Any] = field(default_factory=dict)
+    # Merge provenance on a ``fit_mode="baked"`` manifold — the
+    # ``{coord: {alpha, tensor_sha256}}`` map written by
+    # :func:`drowse.io.bake.merge_into_manifold`.  ``None`` on every fit that
+    # isn't a merge (the common case).  Informational only — a baked
+    # manifold never re-fits, so nothing branches on it.
+    components: Optional[dict[str, Any]] = None
+    bake_policy: Optional[str] = None
+    # Per-node assistant-role substitution used at fit time, in
+    # ``node_labels`` index order.  ``None`` for a given node (and an
+    # empty list as a whole) = "standard assistant baseline" — the
+    # default. The same
+    # information rides ``ManifoldFolder.node_roles`` but the sidecar
+    # carries an independent copy so a downstream consumer
+    # (``manifold show``, the webui inspector) doesn't have to
+    # round-trip through the folder to know which role each node was
+    # pooled under.
+    node_roles: list[str | None] = field(default_factory=list)
+    # Per-node conceptual kind ("abstract"/"concrete"), ``node_labels`` order.
+    # Mirrors ``node_roles``' independent-copy rationale; generation provenance.
+    node_kinds: list[str | None] = field(default_factory=list)
+    # Metric labels: how the per-layer share was weighted and how the subspace
+    # basis was selected.  Both read ``"mahalanobis"`` on an ordinary fit; a
+    # monopolar fold labels its raw-δ̂ basis ``"euclidean"`` (a basis-selection
+    # label, not a metric fallback — ``concept − ν`` cancels common-mode by
+    # differencing, like DiM).
+    share_metric: Optional[str] = None
+    subspace_metric: Optional[str] = None
+    # Topology-selection evidence, stamped for ``fit_mode="auto"`` only (all
+    # three are ``None``/empty otherwise — the payload validator enforces that
+    # consistency).  ``resolved_fit_mode`` is the geometry ``select_topology``
+    # picked for *this* model (``pca`` flat / ``spectral`` curved),
+    # ``topology_winner`` names the winning candidate, and
+    # ``topology_candidates`` is the full ranked field — each
+    # ``{name, fit_mode, intrinsic_dim, score, viable, reason}`` — i.e. the GCV
+    # + persistent-homology evidence behind the flat-vs-curved-vs-periodic call.
+    resolved_fit_mode: Optional[str] = None
+    topology_winner: Optional[str] = None
+    topology_candidates: list[dict[str, Any]] = field(default_factory=list)
+    # Curved-fit per-layer summaries.  ``rbf_smoothing_per_layer``
+    # ``{L: {lambda, edf, gcv}}`` records the GCV-selected penalized-RBF
+    # smoothing; ``sigma_field_per_layer``
+    # ``{L: {sigma_mean, sigma_min, sigma_max, lambda}}`` summarizes the
+    # fuzzy-manifold tube thickness.  The σ-RBF tensors themselves ride the
+    # safetensors — these are the inspector summaries.  Empty on flat fits.
+    rbf_smoothing_per_layer: dict[str, Any] = field(default_factory=dict)
+    sigma_field_per_layer: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def evaluated_layers(self) -> list[int]:
+        """Layers evaluated by the fit before DLS pruning.
+
+        Multi-node activation fits always measure ``node_spread_per_layer``
+        before selecting the retained tensor layers.  Artifact kinds without
+        that diagnostic (for example baked and monopolar manifolds) evaluate
+        exactly their fitted tensor roster.
+        """
+        if self.node_spread_per_layer:
+            return sorted(int(layer) for layer in self.node_spread_per_layer)
+        return list(self.fitted_layers)
+
+    @classmethod
+    def load(cls, path: Path) -> "ManifoldSidecar":
+        data = load_manifold_sidecar_data(path)
+        return cls(
+            method=data["method"],
+            drowse_version=data["drowse_version"],
+            domain=data["domain"],
+            node_count=data["node_count"],
+            node_labels=data["node_labels"],
+            feature_space=data["feature_space"],
+            nodes_sha256=data["nodes_sha256"],
+            sae_release=data["sae_release"],
+            sae_revision=data["sae_revision"],
+            sae_fingerprint=data["sae_fingerprint"],
+            sae_ids_by_layer=dict(data["sae_ids_by_layer"]),
+            sae_full_coverage=data["sae_full_coverage"],
+            model_fingerprint=data["model_fingerprint"],
+            model_source_fingerprint=data["model_source_fingerprint"],
+            capture_sha256=data["capture_sha256"],
+            capture_version=data["capture_version"],
+            capture_render_sha256=data["capture_render_sha256"],
+            baseline_prompts_sha256=data["baseline_prompts_sha256"],
+            fitted_layers=list(data["fitted_layers"]),
+            fit_policy_version=data["fit_policy_version"],
+            fit_mode=data["fit_mode"],
+            hyperparams=dict(data["hyperparams"]),
+            diagnostics=dict(data["diagnostics"]),
+            node_spread_per_layer=dict(data["node_spread_per_layer"]),
+            node_roles=list(data["node_roles"]),
+            node_kinds=list(data["node_kinds"]),
+            components=data["components"],
+            bake_policy=data["bake_policy"],
+            share_metric=data["share_metric"],
+            subspace_metric=data["subspace_metric"],
+            resolved_fit_mode=data["resolved_fit_mode"],
+            topology_winner=data["topology_winner"],
+            topology_candidates=list(data["topology_candidates"]),
+            rbf_smoothing_per_layer=dict(data["rbf_smoothing_per_layer"]),
+            sigma_field_per_layer=dict(data["sigma_field_per_layer"]),
+        )
+
+
+def fitted_sidecar_is_current(path: Path) -> bool:
+    """Whether a fitted sidecar carries the current schema generation.
+
+    A cheap version peek, deliberately narrower than the full validator: only a
+    well-formed *older or newer* stamp counts as stale.  Unreadable bytes, a
+    non-object payload, and a missing or non-integer ``format_version`` all
+    return ``True`` so the strict loader still runs and reports what is actually
+    wrong — a format bump must invalidate fits, never launder corruption.
+
+    Early v10 writers predated the nullable ``context_binding_sha256`` proof.
+    That one exact predecessor field set is also stale: it is safe to refit from
+    the corpus, but it cannot prove that its capture used the current context.
+    Other same-version schema damage remains corruption and reaches the strict
+    loader below.
+    """
+    try:
+        with open(path) as handle:
+            payload = json.load(handle)
+            value = payload.get("format_version")
+    except (OSError, json.JSONDecodeError, AttributeError, TypeError):
+        return True
+    if isinstance(value, bool) or not isinstance(value, int):
+        return True
+    if value != MANIFOLD_FORMAT_VERSION:
+        return False
+    from drowse.io.brand_migration import migrate_legacy_record
+
+    payload = migrate_legacy_record(payload)
+    legacy_v10_fields = MANIFOLD_SIDECAR_FIELDS - {"context_binding_sha256"}
+    return set(payload) != legacy_v10_fields
+
+
+def load_manifold_sidecar_data(path: Path) -> dict[str, Any]:
+    """Read and validate the exact current fitted-manifold sidecar shape.
+
+    The reader half of :func:`validate_manifold_sidecar_payload` — one
+    validator gates writer and reader, so a sidecar that loads is exactly a
+    sidecar the writer could have produced.  Only the version check is hoisted
+    ahead of it: an artifact from an older format should say so rather than
+    report whichever field the current schema happens to miss first.
+    """
+    location = f"manifold sidecar {path}"
+    try:
+        with open(path) as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError) as exc:
+        raise ManifoldFormatError(f"{location} is unreadable: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ManifoldFormatError(f"{location} must be a JSON object")
+    validate_manifold_format_version(data.get("format_version"), location=location)
+    return validate_manifold_sidecar_payload(data, location=location)
+
+
+@dataclass
+class ManifoldFolder:
+    """A manifold artifact folder on disk.
+
+    Discovery + corpus + integrity only — the fitted RBF tensors are
+    loaded through :func:`drowse.io.manifold_tensors.load_manifold`.
+
+    Two folder shapes share this class via the ``fit_mode`` field:
+
+    - ``fit_mode == "authored"``: the
+      user supplied per-node ``coords`` on a declared ``domain``.  The
+      fit pipeline embeds the coords and runs straight into
+      ``fit_layer_subspace``.
+    - ``fit_mode in {"pca", "spectral"}`` (discover mode): nodes carry
+      ``{label}`` only — no coords, no top-level ``domain``.  The fit
+      pipeline pools per-node centroids, derives coords via
+      :func:`drowse.core.manifold.discover_coords` (per-model, since
+      different models embed the same heap differently), wraps them in
+      a ``CustomDomain(k)`` with identity embedding, and fits.
+
+    For authored folders ``domain`` is the tagged-union spec and
+    ``node_coords`` is the K×n list; for discover folders both are
+    empty placeholders (``{}`` and ``[]``) — the real geometry lives
+    in the per-model sidecar after the fit runs.  ``hyperparams``
+    captures the discover-mode knobs (``max_dim``, ``var_threshold``
+    for PCA; ``max_dim``, ``k_nn``, ``bandwidth`` for spectral) and is
+    empty for authored folders.
+    """
+
+    folder: Path
+    name: str
+    description: str
+    domain: dict[str, Any]
+    node_labels: list[str]
+    node_coords: list[list[float]]
+    files: dict[str, str]
+    fit_mode: str = "authored"
+    hyperparams: dict[str, Any] = field(default_factory=dict)
+    # Provenance tier.
+    # ``"local"`` (default) — hand-authored / generated under ``local/``;
+    # ``"bundled"`` — shipped under ``drowse/data/manifolds/`` and
+    # materialized into ``default/`` (set by namespace at refresh time,
+    # not stored); ``"hf://<owner>/<name>[@rev]"`` — pulled from the HF
+    # hub (stamped by :func:`drowse.io.hf_manifolds.pull_manifold`).  The
+    # ``refresh_manifold`` lifecycle reads it to decide where to re-pull:
+    # ``local`` is silently skipped (nothing upstream), ``hf://`` re-pulls.
+    source: str = "local"
+    # Per-node assistant-role substitution for role-augmented manifolds
+    # (e.g. a persona manifold where each node is a persona).  Aligned
+    # with ``node_labels`` index-by-index.  ``None`` for a given node =
+    # "use the standard assistant baseline". An all-``None`` list keeps the
+    # ordinary behavior — the centroid pooling
+    # just goes through the default chat-template branch.
+    node_roles: list[str | None] = field(default_factory=list)
+    # Per-node conceptual ``kind`` — ``"abstract"`` (trait) or ``"concrete"``
+    # (entity), aligned with ``node_labels`` index-by-index.  ``None`` =
+    # unspecified.  Generation-time only (system template + elicitation role
+    # label); never consumed by the fit.
+    node_kinds: list[str | None] = field(default_factory=list)
+    # Category tags carried so category-grouped probe bootstrap
+    # (``load_default_manifolds`` -> ``_bootstrap_manifold_probes``) keeps
+    # working once a steering vector lives as a 2-node ``pca`` manifold.
+    # Always explicit in the manifest; empty means uncategorized.
+    tags: list[str] = field(default_factory=list)
+    # Reference to a standalone template artifact
+    # (``drowse.io.templates.TemplateFolder``, ``<ns>/<name>`` or bare name).
+    # A *templated* discover manifold's node corpora are the slot-filled
+    # assistant turns derived from that template; the manifold stores the derived
+    # corpus in ``nodes/`` (like any discover folder) and keeps this reference so
+    # the fit can resolve the template's **multi-turn contexts** as the
+    # per-manifold elicitation prefixes (the template analogue of the shared
+    # baseline prompts). The template is the single authoring source; the corpus
+    # is its materialization. ``None`` marks every non-templated manifold. The resolved
+    # template's content hash folds into ``nodes_sha256`` (a context edit re-fits)
+    # and the ref is preserved across re-fits by ``write_metadata``.
+    template_ref: str | None = None
+    # tensor stem (``<safe_model>`` or ``<safe_model>_sae-<rel>``) -> sidecar.
+    _sidecars: dict[str, ManifoldSidecar] = field(default_factory=dict)
+
+    @property
+    def is_discover(self) -> bool:
+        """True when this folder's coords are derived per-model rather than authored."""
+        return self.fit_mode in _FIT_MODES_DISCOVER
+
+    @classmethod
+    def load(
+        cls, folder: Path, *, verify_manifest: bool = True,
+    ) -> "ManifoldFolder":
+        """Parse a manifold folder.
+
+        Runtime/install/push callers keep the default full integrity walk.
+        Metadata-only inventory, authoring, and lifecycle routing callers may set
+        ``verify_manifest=False``; fit callers do likewise, hashing the live
+        corpus into ``nodes_sha256`` and validating only the requested fitted
+        tensor.  This avoids rereading every historical model/SAE payload when no
+        payload is being consumed.  Structural checks and tensor/sidecar pairing
+        still run either way.
+        """
+        folder = Path(folder)
+        meta_path = folder / "manifold.json"
+        if not meta_path.exists():
+            raise ManifoldFormatError(f"no manifold.json in {folder}")
+        try:
+            with open(meta_path) as f:
+                data = json.load(f)
+        except (json.JSONDecodeError, OSError) as e:
+            # A malformed manifest must surface as ManifoldFormatError so
+            # callers (iter_manifold_folders, the HTTP routes) catch it
+            # rather than letting a bare JSONDecodeError become a 500.
+            raise ManifoldFormatError(
+                f"manifold.json in {folder} is unreadable: {e}"
+            ) from e
+        if not isinstance(data, dict):
+            raise ManifoldFormatError(
+                f"manifold.json in {folder} must be a JSON object"
+            )
+
+        validate_manifold_format_version(
+            data.get("format_version"),
+            location=f"manifold.json in {folder}",
+        )
+
+        common_fields = {
+            "format_version", "name", "description", "fit_mode", "nodes",
+            "files", "source", "tags", "artifact_id", "fit_epochs",
+            "template_ref",
+        }
+
+        name = data.get("name")
+        if not isinstance(name, str) or not NAME_REGEX.match(name):
+            raise ManifoldFormatError(
+                f"manifold name {name!r} invalid; must match {NAME_REGEX.pattern}"
+            )
+
+        # Authored manifolds carry ``domain`` + per-node ``coords``. Discover
+        # manifolds omit ``domain`` and derive coordinates per model at fit time.
+        fit_mode = data.get("fit_mode")
+        if fit_mode not in _FIT_MODES_ALL:
+            raise ManifoldFormatError(
+                f"manifold {name!r} fit_mode {fit_mode!r} invalid; "
+                f"expected one of {sorted(_FIT_MODES_ALL)}"
+            )
+        mode_fields = (
+            {"domain"} if fit_mode in {"authored", "baked"}
+            else {"hyperparams"}
+        )
+        unknown = set(data) - common_fields - mode_fields
+        if unknown:
+            raise ManifoldFormatError(
+                f"manifold {name!r} has unknown field(s): {sorted(unknown)}"
+            )
+        for key, expected in (
+            ("description", str), ("files", dict), ("source", str),
+            ("tags", list),
+        ):
+            if not isinstance(data.get(key), expected):
+                raise ManifoldFormatError(
+                    f"manifold {name!r} field {key!r} must be {expected.__name__}"
+                )
+        if not data["source"]:
+            raise ManifoldFormatError(
+                f"manifold {name!r} field 'source' must be non-empty"
+            )
+        if "artifact_id" in data and (
+            not isinstance(data["artifact_id"], str) or not data["artifact_id"]
+        ):
+            raise ManifoldFormatError(
+                f"manifold {name!r} field 'artifact_id' must be a non-empty str"
+            )
+        if "fit_epochs" in data and not isinstance(data["fit_epochs"], dict):
+            raise ManifoldFormatError(
+                f"manifold {name!r} field 'fit_epochs' must be dict"
+            )
+
+        nodes = data.get("nodes")
+        if not isinstance(nodes, list) or not nodes:
+            raise ManifoldFormatError(
+                f"manifold {name!r} needs a non-empty 'nodes' list"
+            )
+
+        node_labels: list[str] = []
+        node_coords: list[list[float]] = []
+        node_roles: list[str | None] = []
+        node_kinds: list[str | None] = []
+        hyperparams: dict[str, Any] = {}
+        domain_spec: dict[str, Any]
+
+        if fit_mode == "authored":
+            domain_spec_in: Any = data.get("domain") or {}
+            if not isinstance(domain_spec_in, dict) or not domain_spec_in:
+                raise ManifoldFormatError(
+                    f"authored manifold {name!r} needs a 'domain' object"
+                )
+            domain_spec = domain_spec_in
+            try:
+                domain = domain_from_spec(domain_spec)
+            except (ValueError, KeyError) as e:
+                raise ManifoldFormatError(
+                    f"manifold {name!r} has an invalid domain: {e}"
+                ) from e
+            n = domain.intrinsic_dim
+            floor = min_nodes(n)
+            if len(nodes) < floor:
+                raise ManifoldFormatError(
+                    f"manifold {name!r} ({n}-D domain) needs a 'nodes' "
+                    f"list of >= {floor} entries, got {len(nodes)}"
+                )
+            for entry in nodes:
+                if not isinstance(entry, dict):
+                    raise ManifoldFormatError(
+                        f"manifold {name!r} node {entry!r} must be an "
+                        f"object with 'label' and 'coords'"
+                    )
+                expected_node = {"label", "coords", "role", "kind"}
+                if set(entry) != expected_node:
+                    raise ManifoldFormatError(
+                        f"manifold {name!r} node fields must be "
+                        f"{sorted(expected_node)}"
+                    )
+                label = entry.get("label")
+                if not isinstance(label, str) or not _LABEL_REGEX.match(label):
+                    raise ManifoldFormatError(
+                        f"manifold {name!r} node label {label!r} invalid; "
+                        f"a node label is a grammar-addressable identifier "
+                        f"(no '.', reserved as the bipolar separator) — "
+                        f"must match {_LABEL_REGEX.pattern}"
+                    )
+                coords = entry.get("coords")
+                if (
+                    not isinstance(coords, list)
+                    or len(coords) != n
+                    or not all(_finite_number(c) for c in coords)
+                ):
+                    raise ManifoldFormatError(
+                        f"manifold {name!r} node {label!r} needs 'coords' "
+                        f"of {n} number(s), got {coords!r}"
+                    )
+                node_labels.append(label)
+                node_coords.append([float(c) for c in coords])
+                node_roles.append(_validate_node_role(name, label, entry.get("role")))
+                node_kinds.append(_validate_node_kind(name, label, entry.get("kind")))
+            _warn_authoring_quality(name, domain, node_coords)
+        elif fit_mode == "baked":
+            # Baked mode: a pre-fitted, corpus-less artifact (merge output /
+            # imported control vector).  Like authored it carries a display
+            # ``domain`` (the ``CustomDomain`` the fold produced) so the
+            # inspector/summary have geometry to report; like discover its
+            # nodes are label-only (no ``coords`` — the real per-layer node
+            # coords live baked in the tensor).  There is no corpus and no
+            # re-fit, so ``min_nodes`` and the authoring-quality advisory
+            # are both inapplicable.
+            domain_spec_in = data.get("domain") or {}
+            if not isinstance(domain_spec_in, dict) or not domain_spec_in:
+                raise ManifoldFormatError(
+                    f"baked manifold {name!r} needs a 'domain' object"
+                )
+            domain_spec = domain_spec_in
+            try:
+                domain_from_spec(domain_spec)
+            except (ValueError, KeyError) as e:
+                raise ManifoldFormatError(
+                    f"manifold {name!r} has an invalid domain: {e}"
+                ) from e
+            for entry in nodes:
+                if not isinstance(entry, dict):
+                    raise ManifoldFormatError(
+                        f"baked manifold {name!r} node {entry!r} must be an "
+                        f"object with 'label'"
+                    )
+                expected_node = {"label", "role", "kind"}
+                if set(entry) != expected_node:
+                    raise ManifoldFormatError(
+                        f"baked manifold {name!r} node fields must be "
+                        f"{sorted(expected_node)}"
+                    )
+                label = entry.get("label")
+                if not isinstance(label, str) or not _LABEL_REGEX.match(label):
+                    raise ManifoldFormatError(
+                        f"baked manifold {name!r} node label {label!r} "
+                        f"invalid; must match {_LABEL_REGEX.pattern}"
+                    )
+                if "coords" in entry:
+                    raise ManifoldFormatError(
+                        f"baked manifold {name!r} node {label!r} must not "
+                        f"carry 'coords' — baked geometry lives in the tensor"
+                    )
+                node_labels.append(label)
+                node_roles.append(_validate_node_role(name, label, entry.get("role")))
+                node_kinds.append(_validate_node_kind(name, label, entry.get("kind")))
+        else:
+            # Discover mode: no ``domain`` field, no per-node ``coords``.
+            # The fit pipeline derives coords per-model from the
+            # activations and wraps them in a ``CustomDomain(k)``.  We
+            # do not even know the intrinsic dimension until after the
+            # fit, so the ``min_nodes(k)`` floor is enforced at fit time
+            # (once ``k`` is picked) rather than here.
+            if data.get("domain"):
+                raise ManifoldFormatError(
+                    f"discover-mode manifold {name!r} must not carry a "
+                    f"'domain' field — coords are derived per-model at "
+                    f"fit time"
+                )
+            domain_spec = {}
+            raw_hyperparams = data.get("hyperparams")
+            if not isinstance(raw_hyperparams, dict):
+                raise ManifoldFormatError(
+                    f"discover manifold {name!r} field 'hyperparams' must be dict"
+                )
+            hyperparams = sanitize_hyperparams(fit_mode, raw_hyperparams)
+            for entry in nodes:
+                if not isinstance(entry, dict):
+                    raise ManifoldFormatError(
+                        f"discover manifold {name!r} node {entry!r} must "
+                        f"be an object with 'label'"
+                    )
+                expected_node = {"label", "role", "kind"}
+                if set(entry) != expected_node:
+                    raise ManifoldFormatError(
+                        f"discover manifold {name!r} node fields must be "
+                        f"{sorted(expected_node)}"
+                    )
+                label = entry.get("label")
+                if not isinstance(label, str) or not _LABEL_REGEX.match(label):
+                    raise ManifoldFormatError(
+                        f"discover manifold {name!r} node label "
+                        f"{label!r} invalid; a node label is a grammar-"
+                        f"addressable identifier (no '.', reserved as the "
+                        f"bipolar separator) — must match "
+                        f"{_LABEL_REGEX.pattern}"
+                    )
+                if "coords" in entry:
+                    raise ManifoldFormatError(
+                        f"discover manifold {name!r} node {label!r} "
+                        f"must not carry 'coords' — coords are derived "
+                        f"at fit time"
+                    )
+                node_labels.append(label)
+                node_roles.append(_validate_node_role(name, label, entry.get("role")))
+                node_kinds.append(_validate_node_kind(name, label, entry.get("kind")))
+
+        if len(set(node_labels)) != len(node_labels):
+            raise ManifoldFormatError(
+                f"manifold {name!r} has duplicate node labels"
+            )
+
+        files = data["files"]
+        if not isinstance(files, dict):
+            raise ManifoldFormatError(
+                f"manifold {name!r} 'files' must be an object"
+            )
+        # Verify only a populated manifest — a freshly hand-authored
+        # manifold has no hashes yet; `fit` back-fills them.
+        if files and verify_manifest:
+            ok, bad = verify_integrity(folder, files)
+            if not ok:
+                raise ManifoldFormatError(
+                    f"manifold integrity check failed in {folder}: "
+                    f"tampered/missing {bad}"
+                )
+
+        raw_tags = data["tags"]
+        if not isinstance(raw_tags, list) or not all(
+            isinstance(t, str) for t in raw_tags
+        ):
+            raise ManifoldFormatError(
+                f"manifold {name!r} 'tags' must be a list of strings"
+            )
+
+        # Optional reference to a standalone template artifact — present only on
+        # templated discover manifolds. The node corpora were derived from it at
+        # authoring time and live in ``nodes/`` like any discover folder; this
+        # ref lets the fit resolve the template's multi-turn contexts as the
+        # elicitation prefixes. Only discover folders may carry it.
+        if "template_ref" not in data:
+            raise ManifoldFormatError(
+                f"manifold {name!r} needs explicit 'template_ref'"
+            )
+        raw_template_ref = data["template_ref"]
+        template_ref: str | None = None
+        if raw_template_ref is not None:
+            if not isinstance(raw_template_ref, str) or not raw_template_ref:
+                raise ManifoldFormatError(
+                    f"manifold {name!r} 'template_ref' must be a non-empty string"
+                )
+            if fit_mode not in _FIT_MODES_DISCOVER:
+                raise ManifoldFormatError(
+                    f"manifold {name!r} carries a 'template_ref' but fit_mode is "
+                    f"{fit_mode!r}; templated corpora are a discover-mode feature "
+                    f"({sorted(_FIT_MODES_DISCOVER)})"
+                )
+            template_ref = raw_template_ref
+
+        inst = cls(
+            folder=folder,
+            name=name,
+            description=data["description"],
+            domain=domain_spec,
+            node_labels=node_labels,
+            node_coords=node_coords,
+            files=files,
+            fit_mode=fit_mode,
+            hyperparams=hyperparams,
+            source=data["source"],
+            node_roles=node_roles,
+            node_kinds=node_kinds,
+            tags=[str(t) for t in raw_tags],
+            template_ref=template_ref,
+        )
+
+        # Every node file must be present — except for a baked manifold,
+        # which has no ``nodes/`` corpus at all (its geometry is the tensor).
+        if fit_mode != "baked":
+            for idx, _label in enumerate(node_labels):
+                p = inst.node_path(idx)
+                if not p.exists():
+                    raise ManifoldFormatError(
+                        f"manifold {name!r} missing node corpus file {p}"
+                    )
+
+        for t in sorted(folder.glob("*.safetensors")):
+            sc_path = t.with_suffix(".json")
+            # Every fitted tensor must carry its ``.json`` sidecar. ``fit``
+            # always writes one via ``save_manifold``, so a missing
+            # sidecar means a genuinely-corrupt folder, not a legitimate
+            # shape — refuse rather than silently accept a sidecar-less
+            # tensor.
+            if not sc_path.exists():
+                raise ManifoldFormatError(
+                    f"manifold {name!r} tensor {t.name} has no sidecar "
+                    f"{sc_path.name}"
+                )
+            # A fit from an older format is **stale, not corrupt**: the folder's
+            # corpus and geometry are untouched, so the only thing that expired
+            # is one per-model tensor.  Leave its stem unregistered and the
+            # manifold reads as "not fitted for that model" — a clean cache miss
+            # the next fit overwrites.  Raising here instead would take the
+            # whole artifact out of the selector index on a format bump,
+            # unfitting its labels, probes, and steering along with it.  A
+            # corpus-less baked manifold has nothing to re-fit from, so it keeps
+            # the strict read (and the tensor-less check below then fires).
+            if fit_mode != "baked" and not fitted_sidecar_is_current(sc_path):
+                continue
+            inst._sidecars[t.stem] = ManifoldSidecar.load(sc_path)
+
+        # A baked manifold's tensor is its entire reason to exist (no corpus
+        # to re-fit from), so a tensor-less baked folder is corrupt, not a
+        # legitimate pre-fit shape the way a fresh authored/discover folder is.
+        if fit_mode == "baked" and not inst._sidecars:
+            raise ManifoldFormatError(
+                f"baked manifold {name!r} has no fitted tensor — a corpus-less "
+                f"manifold carries its geometry only in the per-model tensor"
+            )
+        return inst
+
+    # -- node corpus -------------------------------------------------------
+
+    def node_path(self, index: int) -> Path:
+        return self.folder / "nodes" / _node_filename(
+            index, self.node_labels[index],
+        )
+
+    def node_groups(self) -> list[tuple[str, list[str]]]:
+        """Return ``[(label, statements), ...]`` in node order."""
+        if self.fit_mode == "baked":
+            raise ManifoldFormatError(
+                f"baked manifold {self.name!r} has no node corpus to read"
+            )
+        groups: list[tuple[str, list[str]]] = []
+        for idx, label in enumerate(self.node_labels):
+            with open(self.node_path(idx)) as f:
+                statements = json.load(f)
+            if not isinstance(statements, list) or not statements:
+                raise ManifoldFormatError(
+                    f"manifold {self.name!r} node {label!r} must be a "
+                    f"non-empty JSON list of statements"
+                )
+            if not all(isinstance(s, str) for s in statements):
+                raise ManifoldFormatError(
+                    f"manifold {self.name!r} node {label!r} statements "
+                    f"must all be strings"
+                )
+            groups.append((label, list(statements)))
+        return groups
+
+    def nodes_sha256(
+        self, *, resolved_template_sha256: str | None = None,
+    ) -> str:
+        """Stable hash of the inputs that determine a fit's output.
+
+        The staleness key: a fitted tensor's sidecar records this, and a
+        re-fit is needed when it no longer matches.  For authored
+        manifolds the hash folds in the corpus, the domain spec, and
+        the authoring coordinates — any geometry edit (moving a node,
+        flipping an axis to periodic) triggers a re-fit alongside
+        corpus edits.  For discover manifolds the corresponding inputs
+        are the corpus plus the fit mode plus the hyperparameters
+        (``max_dim``, ``var_threshold`` for PCA; ``max_dim``,
+        ``k_nn``, ``bandwidth`` for spectral) — changing any of those
+        invalidates a cached fit.
+
+        The current hash covers the complete canonical fit input shape.
+        """
+        h = hashlib.sha256()
+        if self.fit_mode == "baked":
+            # No corpus and no re-fit: the key is provenance-only (the
+            # sidecar records it, and it always matches since baked never
+            # re-fits).  Hash the identity that distinguishes it.
+            h.update(_canonical_json({
+                "fit_mode": "baked",
+                "node_labels": list(self.node_labels),
+            }))
+            return h.hexdigest()
+        # Labels are part of the fitted artifact (steering-by-label, nearest
+        # reads, roles/kinds alignment).  Node filenames are index-based, so a
+        # rename can leave every corpus byte unchanged unless labels themselves
+        # participate in the staleness key.
+        h.update(_canonical_json(list(self.node_labels)))
+        for idx in range(len(self.node_labels)):
+            h.update(self.node_path(idx).read_bytes())
+        if self.fit_mode == "authored":
+            h.update(_canonical_json(self.domain))
+            h.update(_canonical_json(self.node_coords))
+        else:
+            h.update(_canonical_json({
+                "fit_mode": self.fit_mode,
+                "hyperparams": self.hyperparams,
+            }))
+        # Per-node roles are inputs that determine the fit's geometry
+        # (each node's centroid is pooled under its role's chat-template
+        # substitution), so a role edit must invalidate a cached fit.
+        h.update(_canonical_json(self.node_roles))
+        # Per-node kind selects the generation system template + elicitation
+        # role label, so it shapes the corpus a re-fit would pool — a kind edit
+        # must invalidate a cached fit.
+        h.update(_canonical_json(self.node_kinds))
+        # A templated manifold's elicitation prefixes are the referenced
+        # template's multi-turn contexts (a fit input that the node corpus files
+        # above don't capture — they're only the slotted assistant turns), so a
+        # context/value edit must invalidate a cached fit. Fold the resolved
+        # template's content hash; fall back to the ref string if it can't be
+        # resolved (best-effort — a missing template fails loudly at fit time).
+        # ``None`` (every non-templated manifold) hashes identically to a missing
+        # field.
+        if self.template_ref is not None:
+            if resolved_template_sha256 is not None:
+                h.update(resolved_template_sha256.encode())
+                return h.hexdigest()
+            from drowse.io.templates import (
+                AmbiguousTemplateError,
+                TemplateNotFoundError,
+                resolve_template,
+            )
+            try:
+                h.update(resolve_template(self.template_ref).sha256().encode())
+            except (TemplateNotFoundError, AmbiguousTemplateError):
+                # The template genuinely can't be resolved (missing / a
+                # cross-namespace collision); the ref string is the best
+                # available staleness key, and the fit fails loudly at fit
+                # time.  Any *other* error (a corrupt template, an IO fault)
+                # is a real bug — let it propagate rather than silently
+                # degrade the staleness key into a stale-but-passing hash.
+                h.update(_canonical_json({"template_ref": self.template_ref}))
+        return h.hexdigest()
+
+    # -- fitted tensors ----------------------------------------------------
+
+    def tensor_models(self) -> list[str]:
+        """Tensor stems present on disk (``<safe_model>[_sae-<rel>]``)."""
+        return sorted(self._sidecars)
+
+    def tensor_path(self, stem: str) -> Path:
+        return self.folder / f"{stem}.safetensors"
+
+    def sidecar(self, stem: str) -> ManifoldSidecar:
+        return self._sidecars[stem]
+
+    # -- manifest ----------------------------------------------------------
+
+    def write_metadata(self, *, files: Optional[dict[str, str]] = None) -> None:
+        """Rewrite authoring metadata while preserving trusted fitted hashes.
+
+        Fitted writers must call :meth:`update_file_hashes` with their exact
+        outputs. A metadata-only rewrite never scans and blesses unrelated
+        top-level files. The locked latest manifest supplies ``files`` when an
+        explicit trusted mapping is not provided.
+        """
+        with _locked_manifest(self.folder):
+            manifest_path = self.folder / "manifold.json"
+            try:
+                with open(manifest_path) as handle:
+                    latest_payload = json.load(handle)
+            except (OSError, json.JSONDecodeError) as exc:
+                raise ManifoldFormatError(
+                    f"cannot update unreadable manifest at {manifest_path}: {exc}"
+                ) from exc
+            if not isinstance(latest_payload, dict):
+                raise ManifoldFormatError(
+                    f"manifold manifest at {manifest_path} must be a JSON object"
+                )
+            validate_manifold_format_version(
+                latest_payload.get("format_version"), location=str(manifest_path),
+            )
+            if files is None:
+                latest = latest_payload.get("files", {})
+                if not isinstance(latest, dict):
+                    raise ManifoldFormatError(
+                        "manifold files manifest is not an object"
+                    )
+                files = dict(latest)
+            self.files = files
+            payload: dict[str, Any] = {
+                "format_version": MANIFOLD_FORMAT_VERSION,
+                "name": self.name,
+                "description": self.description,
+                "fit_mode": self.fit_mode,
+                "files": files,
+                "source": self.source or "local",
+                "tags": list(self.tags),
+                "template_ref": self.template_ref,
+            }
+            for key in ("artifact_id", "fit_epochs"):
+                if key in latest_payload:
+                    payload[key] = latest_payload[key]
+            if self.fit_mode == "authored":
+                payload["domain"] = self.domain
+                payload["nodes"] = [
+                    _node_payload_authored(label, coords, role, kind)
+                    for label, coords, role, kind in zip(
+                        self.node_labels, self.node_coords,
+                        self._roles_padded(), self._kinds_padded(),
+                        strict=True,
+                    )
+                ]
+            elif self.fit_mode == "baked":
+                # Display domain + label-only nodes (no coords, no hyperparams).
+                payload["domain"] = self.domain
+                payload["nodes"] = [
+                    _node_payload_discover(label, role, kind)
+                    for label, role, kind in zip(
+                        self.node_labels, self._roles_padded(),
+                        self._kinds_padded(), strict=True,
+                    )
+                ]
+            else:
+                payload["hyperparams"] = self.hyperparams
+                payload["nodes"] = [
+                    _node_payload_discover(label, role, kind)
+                    for label, role, kind in zip(
+                        self.node_labels, self._roles_padded(),
+                        self._kinds_padded(), strict=True,
+                    )
+                ]
+            write_json_atomic(self.folder / "manifold.json", payload)
+
+    def update_file_hashes(self, *paths: Path) -> None:
+        """Refresh only newly written fitted artifacts in the integrity manifest.
+
+        A fit replaces one tensor/sidecar pair.  Re-reading every historical
+        model and variant in the folder makes persistence scale with old
+        artifacts rather than the work just completed; the existing manifest
+        was already verified by :meth:`load`, so unchanged entries can be kept.
+        Starting from an empty manifest still records only the paths named by
+        the successful writer.  Unrelated pre-existing pairs remain untrusted;
+        implicitly hashing them here would launder an interrupted or tampered
+        artifact merely because another model was fitted.
+        """
+        resolved_paths = [Path(path) for path in paths]
+        for resolved in resolved_paths:
+            if resolved.parent != self.folder or not resolved.is_file():
+                raise ValueError(
+                    f"manifest update path must be a fitted file in {self.folder}: "
+                    f"{resolved}"
+                )
+        with _locked_manifest(self.folder):
+            manifest_path = self.folder / "manifold.json"
+            try:
+                with open(manifest_path) as handle:
+                    payload = json.load(handle)
+            except (OSError, json.JSONDecodeError) as exc:
+                raise ManifoldFormatError(
+                    f"cannot update unreadable manifest at {manifest_path}: {exc}"
+                ) from exc
+            if not isinstance(payload, dict):
+                raise ManifoldFormatError(
+                    f"manifold manifest at {manifest_path} must be a JSON object"
+                )
+            # Reject an unknown schema before interpreting even familiar fields:
+            # a future writer may have changed their shape or semantics.
+            validate_manifold_format_version(
+                payload.get("format_version"), location=str(manifest_path),
+            )
+            latest = payload.get("files", {})
+            if not isinstance(latest, dict):
+                raise ManifoldFormatError("manifold files manifest is not an object")
+            # A newly published pair is always written by the current tensor
+            # writer. Preserve the exact current format in the same locked CAS.
+            files = dict(latest)
+            for resolved in resolved_paths:
+                files[resolved.name] = hash_file(resolved)
+            payload["format_version"] = MANIFOLD_FORMAT_VERSION
+            payload["files"] = files
+            write_json_atomic(manifest_path, payload)
+            self.files = files
+
+    def _roles_padded(self) -> list[str | None]:
+        """Return ``node_roles`` padded to ``len(node_labels)`` with ``None``s.
+
+        ``ManifoldFolder`` constructed via :meth:`load` always carries a
+        full-length ``node_roles``, but in-memory mutations (e.g.
+        :func:`update_manifold_folder` swapping the node list) might
+        leave the roles list out of sync.  Padding here is defensive.
+        """
+        if len(self.node_roles) == len(self.node_labels):
+            return list(self.node_roles)
+        return [None] * len(self.node_labels)
+
+    def _kinds_padded(self) -> list[str | None]:
+        """Return ``node_kinds`` padded to ``len(node_labels)`` with ``None``s.
+
+        Defensive twin of :meth:`_roles_padded` — keeps the kind list aligned
+        with the labels under in-memory node-list mutations.
+        """
+        if len(self.node_kinds) == len(self.node_labels):
+            return list(self.node_kinds)
+        return [None] * len(self.node_labels)
+
+
+def _node_payload_authored(
+    label: str, coords: list[float], role: str | None, kind: str | None = None,
+) -> dict[str, Any]:
+    """Build one authored-mode node entry for ``manifold.json``.
+
+    ``role`` and ``kind`` are explicit, including ``None``.
+    """
+    return {
+        "label": label, "coords": [float(c) for c in coords],
+        "role": role, "kind": kind,
+    }
+
+
+def _node_payload_discover(
+    label: str, role: str | None, kind: str | None = None,
+) -> dict[str, Any]:
+    """Build one discover-mode node entry for ``manifold.json``."""
+    return {"label": label, "role": role, "kind": kind}
+
+
+def _warn_authoring_quality(
+    name: str, domain: Any, node_coords: list[list[float]],
+) -> None:
+    """Soft advisory warnings on node placement — never raises.
+
+    Poisedness (the embedded coordinates failing to affinely span the
+    embedding) is a hard error at fit time; flagging it here gives the
+    author the feedback before they run a fit.  A near-flat non-periodic
+    axis (fewer than three distinct values) cannot show curvature.
+    """
+    coords = torch.tensor(node_coords, dtype=torch.float32)
+    embedded = domain.embed(coords)
+    centered = embedded - embedded.mean(dim=0, keepdim=True)
+    rank = int(torch.linalg.matrix_rank(centered))
+    if rank != domain.embed_dim:
+        warnings.warn(
+            f"manifold {name!r}: node coordinates have affine rank {rank} "
+            f"but the embedding is {domain.embed_dim}-dimensional — the fit "
+            f"will fail as not poised; spread the nodes across every axis",
+            UserWarning,
+            stacklevel=3,
+        )
+    if isinstance(domain, BoxDomain):
+        for i, ax in enumerate(domain.axes):
+            if ax.periodic:
+                continue
+            distinct = {round(row[i], 9) for row in node_coords}
+            if len(distinct) < 3:
+                warnings.warn(
+                    f"manifold {name!r}: axis {ax.name!r} has only "
+                    f"{len(distinct)} distinct coordinate value(s) — "
+                    f"curvature along it cannot be fitted",
+                    UserWarning,
+                    stacklevel=3,
+                )
+
+
+@dataclass(frozen=True)
+class DiscoverGenerationPlan:
+    """Resume / extend plan for streaming discover-manifold generation.
+
+    Returned by :func:`drowse.io.manifold_authoring.plan_discover_generation`.
+    ``index_of`` maps each label to its on-disk node index (the ``NN_``
+    filename prefix); ``pending`` is the declared labels whose corpus file
+    is not yet on disk (the ones a run still needs to generate, in node
+    order); ``added`` is the labels appended to ``manifold.json`` this call
+    (the add-nodes case);
+    ``resumed`` is ``True`` when an existing ``manifold.json`` was found.
+    """
+
+    folder: Path
+    index_of: dict[str, int]
+    pending: tuple[str, ...]
+    added: tuple[str, ...]
+    resumed: bool