capsule-engine 0.1.0__py3-none-any.whl

capsule_engine/policy/limits.py

@@ -0,0 +1,287 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Which ``caps`` limit is in force for a decision, and where it came from.
+
+A user's limit lives in a policy profile (``profile.py``) that an activation
+record binds (``activation.py``): the record carries the profile's values and
+digest and is appended, signed, to the ledger. ``ResolvedManifest`` lays the
+profile over the wicket's defaults as soon as it is installed; this module
+adds the one rule that depends on *when* a value was activated:
+
+* a value at or below the limit in force when it was activated takes effect
+  at that activation's timestamp;
+* a value above it takes effect ``COOLING_OFF`` (12 hours) after that
+  timestamp, and until then the earlier limit stays in force;
+* each activation supersedes any raise an earlier one left pending.
+
+"Earlier limit" starts at the wicket's default, so a first profile that sets
+a limit above the pack's default waits too, and so does removing a profile
+whose limit was below it. Lower is tighter and higher is looser, as
+``packs/contract_diff.py`` classifies a profile limit; that diff reports a
+class set on only one side as ``changed`` because it does not read the pack
+default, and here the default is known, so every change has a direction.
+
+Which records count. The history is every activation in the ledger, in
+append order, and it is read only when a profile is involved -- the install
+pins one, or some activation carries one; otherwise every limit is the
+wicket's default. When it is read:
+
+* every record must verify under the engine's own signer
+  (``events.event_signature_valid``), so a record appended by anything that
+  does not hold the node's key is refused, not ignored;
+* timestamps must not decrease in append order, so a record cannot be
+  backdated ahead of one already appended;
+* the latest record must cite the installed manifest and the profile digest
+  that manifest pins.
+
+A class a record's profile does not set reads the *installed* wicket's
+default, including for records made under an earlier wicket. A pack upgrade
+that changes a default is therefore not itself put through the cooling-off;
+a value the operator set is, across any upgrade.
+
+``CapsLimits.in_force`` is asked at two times -- the action's own timestamp
+and the engine's clock -- and returns the lower of the two limits, so a
+caller cannot reach a raise early by stamping its action later, or escape a
+lowering by stamping it earlier. The value comes with its provenance --
+``operator_profile`` with the digest of the profile that set it, or
+``definition_default`` -- plus any activated raise still waiting out the
+cooling-off. The caps check seals that provenance in its evidence
+(``guards/checks/caps.py``'s ``limit_sources``).
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from itertools import pairwise
+
+from cll.ledger.api import LedgerAPI, ScanQuery
+
+from ..events.capsule import event_signature_valid
+from ..guards.checks.caps import (
+    LIMIT_SOURCE_DEFAULT,
+    LIMIT_SOURCE_PROFILE,
+    LimitSource,
+    PendingRaise,
+    cap_for,
+)
+from ..guards.classes import resolve
+from ..guards.signing import Signer
+from .activation import EVENT_MANIFEST_ACTIVATED
+from .errors import (
+    ACTIVATION_OUT_OF_ORDER,
+    ACTIVATION_UNVERIFIED,
+    PROFILE_DIGEST_DRIFT,
+    PROFILE_UNBOUND,
+    PolicyManifestError,
+)
+from .profile import parse_profile
+from .resolve import ResolvedManifest
+
+__all__ = [
+    "COOLING_OFF",
+    "ActivationRecord",
+    "CapsLimits",
+    "LimitInForce",
+    "activation_records",
+    "caps_limits",
+    "read_caps_limits",
+]
+
+COOLING_OFF = timedelta(hours=12)
+
+# The caps config keys a profile may set (``profile.CONFIGURABLE["caps"]``).
+_KEYS = ("caps_minor", "per_action_minor")
+
+
+@dataclass(frozen=True)
+class ActivationRecord:
+    """One ``policy_manifest_activated`` capsule, as appended."""
+
+    capsule: Mapping
+
+    @property
+    def timestamp(self) -> str:
+        return self.capsule["timestamp"]
+
+    @property
+    def detail(self) -> Mapping:
+        return self.capsule["asg_payload"]["detail"]
+
+
+@dataclass(frozen=True)
+class LimitInForce:
+    value_minor: int
+    source: LimitSource
+
+
+@dataclass(frozen=True)
+class _Step:
+    # Both ``None`` for the wicket's default before any activation.
+    activated_at: datetime | None
+    effective_at: datetime | None
+    value_minor: int
+    # ``None``: the wicket's default.
+    profile_digest: str | None
+
+
+def _parse_ts(ts: str) -> datetime:
+    """An ISO-8601 timestamp; one with no UTC offset is read as UTC, the
+    engine's convention for every timestamp it writes."""
+    dt = datetime.fromisoformat(ts[:-1] + "+00:00" if ts.endswith("Z") else ts)
+    return dt if dt.tzinfo is not None else dt.replace(tzinfo=timezone.utc)
+
+
+def _format_ts(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _canonical(action_class: str) -> str:
+    ac = resolve(action_class)
+    return ac.name if ac is not None else action_class
+
+
+def _source_name(step: _Step) -> str:
+    return LIMIT_SOURCE_DEFAULT if step.profile_digest is None else LIMIT_SOURCE_PROFILE
+
+
+def _at(steps: tuple[_Step, ...], when: datetime) -> LimitInForce:
+    """The limit in force at ``when``, and the raise pending then, if any:
+    one activated by ``when`` that takes effect after it."""
+    current = steps[0]
+    pending: _Step | None = None
+    for step in steps:
+        if step.effective_at is None or step.effective_at <= when:
+            current = step
+        elif step.activated_at is not None and step.activated_at <= when:
+            pending = step
+    source = LimitSource(limit_source=_source_name(current))
+    if current.profile_digest is not None:
+        source["profile_digest"] = current.profile_digest
+    if pending is not None and pending.effective_at is not None and pending.value_minor > current.value_minor:
+        raise_ = PendingRaise(
+            value_minor=pending.value_minor,
+            effective_at=_format_ts(pending.effective_at),
+            limit_source=_source_name(pending),
+        )
+        if pending.profile_digest is not None:
+            raise_["profile_digest"] = pending.profile_digest
+        source["pending_raise"] = raise_
+    return LimitInForce(value_minor=current.value_minor, source=source)
+
+
+@dataclass(frozen=True)
+class CapsLimits:
+    """Per caps key (``caps_minor`` / ``per_action_minor``), per canonical
+    action class, the limit's steps in activation order. ``effective_at`` is
+    non-decreasing along each tuple."""
+
+    steps: Mapping[str, Mapping[str, tuple[_Step, ...]]]
+
+    def in_force(self, key: str, action_class: str | None, *, at: str, now: str) -> LimitInForce | None:
+        """The ``key`` limit for ``action_class``: the lower of the limits in
+        force at ``at`` (the action's timestamp) and ``now`` (the engine's
+        clock), the one at ``at`` on a tie. ``None`` when the installed wicket
+        sets no such limit for the class."""
+        by_class = self.steps.get(key, {})
+        if action_class is None or cap_for(dict.fromkeys(by_class, 0), action_class) is None:
+            return None
+        steps = by_class[_canonical(action_class)]
+        at_action = _at(steps, _parse_ts(at))
+        at_clock = _at(steps, _parse_ts(now))
+        return at_clock if at_clock.value_minor < at_action.value_minor else at_action
+
+
+def activation_records(ledger: LedgerAPI) -> list[ActivationRecord]:
+    """Every ``policy_manifest_activated`` record in ``ledger``, in append order."""
+    return [
+        ActivationRecord(capsule=record.capsule)
+        for record in ledger.scan(ScanQuery(action_type="fyi"))
+        if (record.capsule.get("asg_payload") or {}).get("event") == EVENT_MANIFEST_ACTIVATED
+    ]
+
+
+def _profile_values(detail: Mapping, pack_names: set[str]) -> tuple[str | None, dict[str, dict[str, int]]]:
+    """The profile digest an activation cites and the caps values it sets,
+    key -> class -> value. The values are re-digested: a record whose values
+    do not digest to the digest it cites is refused."""
+    profile = detail.get("profile")
+    if profile is None:
+        return None, {}
+    parsed = parse_profile(profile["values"])
+    if parsed.profile_digest() != profile["profile_digest"]:
+        raise PolicyManifestError(
+            PROFILE_DIGEST_DRIFT,
+            f"activation cites profile {profile['profile_digest']}, but its values digest to {parsed.profile_digest()}",
+        )
+    values: dict[str, dict[str, int]] = {}
+    for entry in parsed.packs:
+        if entry.pack in pack_names:
+            for key, by_class in entry.parameters.get("caps", {}).items():
+                values.setdefault(key, {}).update(by_class)
+    return profile["profile_digest"], values
+
+
+def _check_history(resolved: ResolvedManifest, activations: Sequence[ActivationRecord], signer: Signer) -> None:
+    """Refuse a history this module cannot read limits from (module docstring)."""
+    for record in activations:
+        if not event_signature_valid(record.capsule, signer):
+            raise PolicyManifestError(
+                ACTIVATION_UNVERIFIED,
+                f"activation {record.capsule.get('capsule_id')} does not verify under key {signer.key_id!r}",
+            )
+    for earlier, later in pairwise(activations):
+        if _parse_ts(later.timestamp) < _parse_ts(earlier.timestamp):
+            raise PolicyManifestError(
+                ACTIVATION_OUT_OF_ORDER,
+                f"activation {later.capsule.get('capsule_id')} at {later.timestamp} is appended after one at "
+                f"{earlier.timestamp}",
+            )
+    latest = activations[-1].detail if activations else None
+    cited = (latest.get("profile") or {}).get("profile_digest") if latest is not None else None
+    if latest is None or latest.get("manifest_digest") != resolved.manifest_digest or cited != resolved.manifest.profile_digest:
+        raise PolicyManifestError(
+            PROFILE_UNBOUND,
+            f"installed manifest {resolved.manifest_digest} (profile {resolved.manifest.profile_digest}) is not the "
+            f"one the latest activation binds ({latest.get('manifest_digest') if latest else 'none recorded'}, "
+            f"profile {cited}); a profile's limits apply only once an activation binds them",
+        )
+
+
+def caps_limits(resolved: ResolvedManifest, activations: Sequence[ActivationRecord], signer: Signer) -> CapsLimits:
+    """The caps limits of ``resolved`` over time, from the ledger's activation
+    records (``activation_records``), each verified under ``signer``. Raises
+    ``PolicyManifestError`` when a profile is involved and the history cannot
+    be read (module docstring)."""
+    defaults = resolved.wicket_config("caps")
+    pack_names = {p.pack_id.rsplit("/", 1)[0] for p in resolved.manifest.packs}
+    involved = resolved.profile is not None or any(r.detail.get("profile") is not None for r in activations)
+    history: list[tuple[datetime, str | None, dict[str, dict[str, int]]]] = []
+    if involved:
+        _check_history(resolved, activations, signer)
+        history = [(_parse_ts(r.timestamp), *_profile_values(r.detail, pack_names)) for r in activations]
+
+    steps: dict[str, dict[str, tuple[_Step, ...]]] = {}
+    for key in _KEYS:
+        for action_class, default in (defaults.get(key) or {}).items():
+            schedule = [_Step(activated_at=None, effective_at=None, value_minor=default, profile_digest=None)]
+            for activated_at, digest, values in history:
+                set_by_profile = action_class in values.get(key, {})
+                value = values[key][action_class] if set_by_profile else default
+                # Drop any raise not yet in force: this activation supersedes it.
+                schedule = [s for s in schedule if s.effective_at is None or s.effective_at <= activated_at]
+                effective_at = activated_at if value <= schedule[-1].value_minor else activated_at + COOLING_OFF
+                schedule.append(
+                    _Step(
+                        activated_at=activated_at,
+                        effective_at=effective_at,
+                        value_minor=value,
+                        profile_digest=digest if set_by_profile else None,
+                    )
+                )
+            steps.setdefault(key, {})[_canonical(action_class)] = tuple(schedule)
+    return CapsLimits(steps=steps)
+
+
+def read_caps_limits(resolved: ResolvedManifest, ledger: LedgerAPI, signer: Signer) -> CapsLimits:
+    """``caps_limits`` over ``ledger``'s activation records as they stand now."""
+    return caps_limits(resolved, activation_records(ledger), signer)

capsule_engine/policy/loader.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+"""YAML front door for policy manifests: YAML text/file -> validated Manifest."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from .errors import MALFORMED_MANIFEST, PolicyManifestError
+from .manifest import Manifest, parse_manifest
+
+__all__ = ["load_manifest_text", "load_manifest_file"]
+
+
+def load_manifest_text(text: str) -> Manifest:
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise PolicyManifestError(MALFORMED_MANIFEST, f"invalid YAML: {exc}") from exc
+    if data is None:
+        raise PolicyManifestError(MALFORMED_MANIFEST, "empty manifest document")
+    return parse_manifest(data)
+
+
+def load_manifest_file(path: str | Path) -> Manifest:
+    return load_manifest_text(Path(path).read_text())

capsule_engine/policy/manifest.py

@@ -0,0 +1,289 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The policy manifest: one canonical, digestible file listing the active
+fold and wicket (guard-constraint) definitions, *by digest*.
+
+This is the declare-attest-verify piece (in-toto/SLSA pattern) for guard
+policy: a manifest is a lockfile, not a copy. Each entry cites a fold_id or
+wicket_id plus that definition's own already-real ``definition_digest()``
+(``folds/definition.py`` / ``guards/wickets/definition.py``) -- never the
+definition body itself, mirroring the same "definitions-by-digest, never
+definitions-by-copy" rule fold *results* already follow when they cite
+``fold_digest`` on a ledger record rather than embedding the fold. Because a
+manifest is itself just declarative data, it gets a digest the exact same
+way: SHA-256 over the JCS-canonical bytes of its own canonical form (see
+``manifest_digest()``), via the same ``agent_action_capsule.canonical.
+json_digest`` every other digest in this codebase uses.
+
+Whether a manifest's pinned digests actually match what's sitting in the
+fold/wicket catalogs *right now* is not this module's job -- see
+``resolve.py`` for that cross-check. This module only parses and digests the
+manifest as declared.
+
+Design notes -- ``engine``:
+
+Every entry also carries an ``engine`` string (``"fold/1"`` for folds,
+``"wicket/1"`` for wickets today) identifying which evaluator resolves that
+entry's semantics, separately from the digest identifying *which
+definition*. Right now there is exactly one legal value per entry kind --
+this repo's own built-in fold/wicket evaluator, kept as the shipped default
+-- so the field looks decorative. It isn't: it participates in
+``canonical_dict()`` (an entry that changes evaluation engine is a manifest
+change, same as a changed digest) and ``resolve.py`` fails closed on any
+engine value it doesn't recognize. The reasoning mirrors
+``agent_action_capsule``'s own ``digest_alg`` field on capsule refs (see
+``verify_composition.py``): ``"SHA-256"`` is the only legal value today, but
+the field exists so a future algorithm can land as a new recognized value
+rather than a wire-format break. Same trade here -- our evidentiary claims
+("evaluated under manifest <digest>", byte-exact CI replay, mutant-tested
+determinism) are cheap to defend precisely because the wicket/fold set is
+closed and tiny; adopting a general declarative engine (OPA/Rego) would
+trade that for a large language surface and an engine-version-pinning
+burden, so it isn't the launch engine. If one is ever adopted, Cedar is the
+better fit (declarative, formally analyzed, deterministic, no I/O by
+design, Apache-2.0) -- but Cedar decides authorization over entities with
+no concept of aggregates, so this repo would still own the fold half
+regardless. This field is what keeps that door open as a new registry
+entry later instead of a manifest-format break now: "any vendor's gate" is
+the intended story, since the durable value this repo provides is the
+recording/envelope layer, not the constraint language.
+
+Design notes -- prior art considered, not adopted (2026-08-05, concept-only;
+no external code was read or copied as part of building this module, and no
+external project names belong in this public repo, so pointers to the
+private inventory of that comparison live in this project's own non-public
+tracking, not here):
+
+- A content-hash + lifecycle-state registry pattern from prior internal
+  tooling was flagged as a closer analog to this manifest than what was
+  originally scoped for this task. This module was written clean-room
+  against public interfaces only; the pointer for whoever does that
+  comparison next is tracked privately.
+- A three-way clearance taxonomy (deterministic / operator-approval /
+  evidence-first) from separate prior internal tooling is worth evaluating
+  against this manifest's wicket-clearance model -- not inherited wholesale
+  here.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from agent_action_capsule.canonical import json_digest
+from agent_action_capsule.contracts import is_hex64
+
+from .errors import (
+    DUPLICATE_FOLD_REF,
+    DUPLICATE_PACK_REF,
+    DUPLICATE_WICKET_REF,
+    INVALID_DIGEST,
+    INVALID_MANIFEST_ID,
+    INVALID_PACK_MODE,
+    MALFORMED_MANIFEST,
+    PolicyManifestError,
+)
+
+__all__ = ["MANIFEST_ID_RE", "PACK_MODES", "FoldRef", "WicketRef", "PackRef", "Manifest", "parse_manifest"]
+
+# manifest_id: same "human name + semver" shape as fold_id/wicket_id.
+MANIFEST_ID_RE = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*/\d+\.\d+\.\d+$")
+
+# A pack ref's lifecycle state (starter-packs plan: "observe mode: records,
+# no enforcement" -> "enforce: thresholds accepted by a human, gate goes
+# live"). Closed set, same discipline as ``engine`` below -- an unrecognized
+# mode is a typo, never silently accepted as data.
+PACK_MODES = frozenset({"observe", "enforce"})
+
+
+@dataclass(frozen=True)
+class FoldRef:
+    fold_id: str
+    engine: str
+    digest: str
+
+
+@dataclass(frozen=True)
+class WicketRef:
+    wicket_id: str
+    engine: str
+    digest: str
+
+
+@dataclass(frozen=True)
+class PackRef:
+    """One installed starter pack, cited by digest like a fold/wicket ref.
+
+    ``digest`` is the pack's own ``definition_digest()`` (``packs/schema.py``
+    -- SHA-256 over the JCS-canonical bytes of its obligations/action-semantics/
+    constraint-and-fold-ref declaration), not a copy of the pack content --
+    same "definitions-by-digest, never definitions-by-copy" rule every other
+    entry in this manifest follows. ``mode`` is which lifecycle state this
+    pack is installed in *as of this manifest* -- flipping observe -> enforce
+    is itself a new manifest (a new ``PackRef.mode``), so "what was in force"
+    stays provable at every point in time, not just today.
+    """
+
+    pack_id: str
+    engine: str
+    digest: str
+    mode: str
+
+
+@dataclass(frozen=True)
+class Manifest:
+    manifest_id: str
+    folds: tuple[FoldRef, ...] = ()
+    wickets: tuple[WicketRef, ...] = ()
+    packs: tuple[PackRef, ...] = ()
+    # The digest of the user's policy profile (``profile.py``), pinned like
+    # every fold and wicket: a changed limit is a changed manifest, while the
+    # wicket and pack it configures keep their digests.
+    profile_digest: str | None = None
+
+    def canonical_dict(self) -> dict:
+        """The JCS-canonicalizable form of this manifest -- drives manifest_digest().
+
+        List order is preserved (not sorted) and is part of what gets
+        digested, same as a fold definition's ``reads`` list -- editing the
+        manifest file (even just reordering entries) is a manifest change."""
+        out: dict[str, Any] = {
+            "manifest_id": self.manifest_id,
+            "folds": [{"fold_id": f.fold_id, "engine": f.engine, "digest": f.digest} for f in self.folds],
+            "wickets": [{"wicket_id": w.wicket_id, "engine": w.engine, "digest": w.digest} for w in self.wickets],
+        }
+        # Omitted entirely (not an empty list) when no pack is installed, so
+        # a pre-pack manifest's canonical_dict -- and therefore its digest --
+        # is byte-identical to what it was before this field existed.
+        if self.packs:
+            out["packs"] = [
+                {"pack_id": p.pack_id, "engine": p.engine, "digest": p.digest, "mode": p.mode} for p in self.packs
+            ]
+        # Omitted when no profile is pinned, by the same rule as ``packs``.
+        if self.profile_digest is not None:
+            out["profile_digest"] = self.profile_digest
+        return out
+
+    def manifest_digest(self) -> str:
+        """SHA-256 over the JCS bytes of the canonical manifest.
+
+        Every field in ``canonical_dict()`` is a string (ids and hex
+        digests), so unlike ``FoldDefinition.definition_digest()`` there is
+        no float/unsafe-integer failure mode to guard here -- ``json_digest``
+        cannot raise on an all-string payload."""
+        return json_digest(self.canonical_dict())
+
+
+def _check_digest(value: Any, context: str) -> str:
+    if not isinstance(value, str) or not is_hex64(value):
+        raise PolicyManifestError(INVALID_DIGEST, f"{context} must be a 64-hex-char digest string, got {value!r}")
+    return value
+
+
+def parse_manifest(data: Any) -> Manifest:
+    """Validate a plain dict (as loaded from YAML) into a ``Manifest``."""
+    if not isinstance(data, dict):
+        raise PolicyManifestError(MALFORMED_MANIFEST, "manifest must be a mapping")
+
+    manifest_id = data.get("manifest_id")
+    if not isinstance(manifest_id, str) or not MANIFEST_ID_RE.match(manifest_id):
+        raise PolicyManifestError(
+            INVALID_MANIFEST_ID,
+            f"manifest_id {manifest_id!r} must match '<namespace>[.<namespace>...]/<major>.<minor>.<patch>' "
+            "(e.g. 'default/1.0.0')",
+        )
+
+    raw_folds = data.get("folds") or []
+    if not isinstance(raw_folds, list):
+        raise PolicyManifestError(MALFORMED_MANIFEST, "folds must be a list")
+    folds: list[FoldRef] = []
+    seen_fold_ids: set[str] = set()
+    for entry in raw_folds:
+        if not isinstance(entry, dict) or "fold_id" not in entry or "digest" not in entry or "engine" not in entry:
+            raise PolicyManifestError(
+                MALFORMED_MANIFEST, f"each folds entry needs 'fold_id', 'engine', and 'digest': {entry!r}"
+            )
+        fold_id = entry["fold_id"]
+        if not isinstance(fold_id, str) or not fold_id:
+            raise PolicyManifestError(MALFORMED_MANIFEST, f"folds[].fold_id must be a non-empty string: {entry!r}")
+        if fold_id in seen_fold_ids:
+            raise PolicyManifestError(DUPLICATE_FOLD_REF, f"fold_id {fold_id!r} declared more than once")
+        seen_fold_ids.add(fold_id)
+        engine = entry["engine"]
+        if not isinstance(engine, str) or not engine:
+            raise PolicyManifestError(
+                MALFORMED_MANIFEST, f"folds[{fold_id!r}].engine must be a non-empty string: {entry!r}"
+            )
+        digest = _check_digest(entry["digest"], f"folds[{fold_id!r}].digest")
+        folds.append(FoldRef(fold_id=fold_id, engine=engine, digest=digest))
+
+    raw_wickets = data.get("wickets") or []
+    if not isinstance(raw_wickets, list):
+        raise PolicyManifestError(MALFORMED_MANIFEST, "wickets must be a list")
+    wickets: list[WicketRef] = []
+    seen_wicket_ids: set[str] = set()
+    for entry in raw_wickets:
+        if not isinstance(entry, dict) or "wicket_id" not in entry or "digest" not in entry or "engine" not in entry:
+            raise PolicyManifestError(
+                MALFORMED_MANIFEST, f"each wickets entry needs 'wicket_id', 'engine', and 'digest': {entry!r}"
+            )
+        wicket_id = entry["wicket_id"]
+        if not isinstance(wicket_id, str) or not wicket_id:
+            raise PolicyManifestError(MALFORMED_MANIFEST, f"wickets[].wicket_id must be a non-empty string: {entry!r}")
+        if wicket_id in seen_wicket_ids:
+            raise PolicyManifestError(DUPLICATE_WICKET_REF, f"wicket_id {wicket_id!r} declared more than once")
+        seen_wicket_ids.add(wicket_id)
+        engine = entry["engine"]
+        if not isinstance(engine, str) or not engine:
+            raise PolicyManifestError(
+                MALFORMED_MANIFEST, f"wickets[{wicket_id!r}].engine must be a non-empty string: {entry!r}"
+            )
+        digest = _check_digest(entry["digest"], f"wickets[{wicket_id!r}].digest")
+        wickets.append(WicketRef(wicket_id=wicket_id, engine=engine, digest=digest))
+
+    raw_packs = data.get("packs") or []
+    if not isinstance(raw_packs, list):
+        raise PolicyManifestError(MALFORMED_MANIFEST, "packs must be a list")
+    packs: list[PackRef] = []
+    seen_pack_ids: set[str] = set()
+    for entry in raw_packs:
+        if (
+            not isinstance(entry, dict)
+            or "pack_id" not in entry
+            or "digest" not in entry
+            or "engine" not in entry
+            or "mode" not in entry
+        ):
+            raise PolicyManifestError(
+                MALFORMED_MANIFEST,
+                f"each packs entry needs 'pack_id', 'engine', 'digest', and 'mode': {entry!r}",
+            )
+        pack_id = entry["pack_id"]
+        if not isinstance(pack_id, str) or not pack_id:
+            raise PolicyManifestError(MALFORMED_MANIFEST, f"packs[].pack_id must be a non-empty string: {entry!r}")
+        if pack_id in seen_pack_ids:
+            raise PolicyManifestError(DUPLICATE_PACK_REF, f"pack_id {pack_id!r} declared more than once")
+        seen_pack_ids.add(pack_id)
+        engine = entry["engine"]
+        if not isinstance(engine, str) or not engine:
+            raise PolicyManifestError(
+                MALFORMED_MANIFEST, f"packs[{pack_id!r}].engine must be a non-empty string: {entry!r}"
+            )
+        mode = entry["mode"]
+        if mode not in PACK_MODES:
+            raise PolicyManifestError(
+                INVALID_PACK_MODE, f"packs[{pack_id!r}].mode must be one of {sorted(PACK_MODES)}, got {mode!r}"
+            )
+        digest = _check_digest(entry["digest"], f"packs[{pack_id!r}].digest")
+        packs.append(PackRef(pack_id=pack_id, engine=engine, digest=digest, mode=mode))
+
+    profile_digest = data.get("profile_digest")
+    if profile_digest is not None:
+        _check_digest(profile_digest, "profile_digest")
+
+    return Manifest(
+        manifest_id=manifest_id,
+        folds=tuple(folds),
+        wickets=tuple(wickets),
+        packs=tuple(packs),
+        profile_digest=profile_digest,
+    )