sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/audit_access.py

@@ -0,0 +1,245 @@
+"""Typed selected-bank views. The authenticated service remains authoritative."""
+from __future__ import annotations
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+import hashlib
+import json
+from typing import Any
+
+from .audit_contracts import BankRelease, ReviewEvent, ReviewTarget
+from .audit_requests import _DIGEST, _exact_identity, _identifier, _key, _positive_version
+from .evaluation_protocols import VersionedIdentity
+from .workflow_contracts import WorkflowContractError, _object, _thaw
+
+
+def _fields(value, schema, required):
+    if (not isinstance(value, Mapping) or value.get('schema_version') != schema
+            or set(value) != {'schema_version', *required}):
+        raise WorkflowContractError('invalid or unsupported audit response fields')
+    return {key: item for key, item in value.items() if key != 'schema_version'}
+
+
+def _common(bank, release, through):
+    _identifier(bank); _identifier(release); _positive_version(through)
+
+
+def _items(values, cls, maximum):
+    if not isinstance(values, (tuple, list)) or len(values) > maximum or any(not isinstance(x, cls) for x in values):
+        raise WorkflowContractError('invalid or oversized audit page items')
+    return tuple(values)
+
+
+def _protocol(value, identity):
+    value = _object(value, 'protected protocol')
+    if (set(value) != {'schema_version', 'protocol_id', 'version', 'implementation_id',
+                       'instructions', 'required_fields', 'allow_extra_fields'}
+            or value.get('schema_version') != 'sphynx.bank-review-protocol.v1'
+            or value.get('protocol_id') != identity.identity_id or value.get('version') != identity.version):
+        raise WorkflowContractError('review protocol identity differs')
+    instructions, required = value['instructions'], value['required_fields']
+    if (type(value['implementation_id']) is not str or not value['implementation_id'].strip()
+            or type(instructions) is not str or not instructions.strip() or len(instructions.encode('utf-8')) > 8192
+            or type(value['allow_extra_fields']) is not bool or not isinstance(required, Mapping)
+            or not 1 <= len(required) <= 64):
+        raise WorkflowContractError('review protocol manifest shape differs')
+    for name, kind in required.items():
+        _identifier(name)
+        if kind not in ('string', 'boolean', 'number', 'integer', 'object', 'array'):
+            raise WorkflowContractError('unsupported review protocol field kind')
+    # This exact manifest schema has only strings, booleans and objects. Match
+    # the service's sorted UTF-8 digest profile; do not generalize to float JSON
+    # or replace the separate legacy/public canonical digest contracts.
+    encoded = json.dumps({'profile': 'sphynx.private-audit-json.v1', 'value': _thaw(value)},
+                         ensure_ascii=False, sort_keys=True, separators=(',', ':'), allow_nan=False).encode('utf-8')
+    if 'sha256:' + hashlib.sha256(encoded).hexdigest() != identity.digest:
+        raise WorkflowContractError('review protocol manifest digest differs')
+    return value
+
+
+def _events(items, bank, release, through, next_after):
+    versions = [event.version for event in items]
+    if versions != sorted(set(versions)) or any(event.version > through or event.bank_id != bank
+            or event.release_id != release for event in items) or len({event.team_id for event in items}) > 1:
+        raise WorkflowContractError('audit history identity or ordering differs')
+    if next_after is not None and (type(next_after) is not int or not items or next_after != versions[-1]):
+        raise WorkflowContractError('audit history cursor does not bind the last event')
+
+
+def _page_dict(schema, page):
+    return {'schema_version': schema, 'bank_id': page.bank_id, 'release_id': page.release_id,
+            'through_version': page.through_version, 'items': [item.to_dict() for item in page.items],
+            'next_after': page.next_after}
+
+
+def _metadata(event):
+    allowed = {'release_digest', 'contribution_id', 'target_id', 'decision',
+               'supersedes_contribution_id', 'adjudication_id', 'contribution_set_digest'}
+    if set(event.details) - allowed or any(item is not None and type(item) is not str for item in event.details.values()):
+        raise WorkflowContractError('ordinary audit metadata contains unsupported detail')
+
+
+class _Readable:
+    def to_text(self) -> str:
+        raise NotImplementedError
+
+    def __str__(self) -> str:
+        return self.to_text()
+
+
+@dataclass(frozen=True)
+class ReviewTargetPage(_Readable):
+    bank_id: str
+    release_id: str
+    through_version: int
+    items: tuple[ReviewTarget, ...] = field(repr=False)
+    protocols_by_digest: Mapping[str, Mapping[str, Any]] = field(repr=False)
+    next_after: str | None = None
+
+    def __post_init__(self):
+        _common(self.bank_id, self.release_id, self.through_version)
+        items = _items(self.items, ReviewTarget, 20)
+        keys = [_identifier(item.target_id) for item in items]
+        if keys != sorted(set(keys)) or (self.next_after is not None and (not keys or self.next_after != keys[-1])):
+            raise WorkflowContractError('target page order or cursor differs')
+        if not isinstance(self.protocols_by_digest, Mapping) or set(self.protocols_by_digest) != {item.protocol.digest for item in items}:
+            raise WorkflowContractError('target page protocol set differs')
+        protocols = {}
+        for item in items:
+            _exact_identity(item.subject); _exact_identity(item.protocol)
+            protocols[item.protocol.digest] = _protocol(self.protocols_by_digest[item.protocol.digest], item.protocol)
+        object.__setattr__(self, 'items', items)
+        object.__setattr__(self, 'protocols_by_digest', _object(protocols, 'protected protocol manifests'))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {**_page_dict('sphynx.bank-review-targets.v1', self),
+                'protocols_by_digest': _thaw(self.protocols_by_digest)}
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ReviewTargetPage:
+        data = _fields(value, 'sphynx.bank-review-targets.v1',
+                       {'bank_id', 'release_id', 'through_version', 'items', 'protocols_by_digest', 'next_after'})
+        data['items'] = _decode_items(data['items'], ReviewTarget, 20)
+        return cls(**data)
+
+    def to_text(self) -> str:
+        return f'Review targets: {self.bank_id}/{self.release_id} at version {self.through_version}; {len(self.items)} protected items. Inspect authorized items explicitly.'
+
+
+def _decode_items(value, cls, maximum):
+    if not isinstance(value, (list, tuple)) or len(value) > maximum:
+        raise WorkflowContractError('invalid or oversized audit page items')
+    return tuple(cls.from_dict(item) for item in value)
+
+
+@dataclass(frozen=True)
+class ReviewHistoryPage(_Readable):
+    bank_id: str
+    release_id: str
+    through_version: int
+    items: tuple[ReviewEvent, ...] = field(repr=False)
+    next_after: int | None = None
+    protected: bool = False
+
+    def __post_init__(self):
+        _common(self.bank_id, self.release_id, self.through_version)
+        if type(self.protected) is not bool:
+            raise WorkflowContractError('protected history selection must be boolean')
+        items = _items(self.items, ReviewEvent, 10 if self.protected else 100)
+        _events(items, self.bank_id, self.release_id, self.through_version, self.next_after)
+        if not self.protected:
+            for item in items:
+                _metadata(item)
+        object.__setattr__(self, 'items', items)
+
+    def to_dict(self) -> dict[str, Any]:
+        schema = 'sphynx.bank-review-protected-history.v1' if self.protected else 'sphynx.bank-review-history.v1'
+        return _page_dict(schema, self)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ReviewHistoryPage:
+        protected = isinstance(value, Mapping) and value.get('schema_version') == 'sphynx.bank-review-protected-history.v1'
+        schema = 'sphynx.bank-review-protected-history.v1' if protected else 'sphynx.bank-review-history.v1'
+        data = _fields(value, schema, {'bank_id', 'release_id', 'through_version', 'items', 'next_after'})
+        data['items'] = _decode_items(data['items'], ReviewEvent, 10 if protected else 100)
+        return cls(**data, protected=protected)
+
+    def to_text(self) -> str:
+        return f'Review history: {self.bank_id}/{self.release_id} through version {self.through_version}; {len(self.items)} events; protected={self.protected}.'
+
+
+@dataclass(frozen=True)
+class TargetReviewPage(_Readable):
+    bank_id: str
+    release_id: str
+    target_id: str
+    through_version: int
+    subject: VersionedIdentity
+    protocol_identity: VersionedIdentity
+    protocol: Mapping[str, Any] = field(repr=False)
+    current_contribution_set_digest: str
+    items: tuple[ReviewEvent, ...] = field(repr=False)
+    next_after: int | None = None
+
+    def __post_init__(self):
+        _common(self.bank_id, self.release_id, self.through_version); _identifier(self.target_id)
+        _exact_identity(self.subject); _exact_identity(self.protocol_identity)
+        if type(self.current_contribution_set_digest) is not str or not _DIGEST.fullmatch(self.current_contribution_set_digest):
+            raise WorkflowContractError('review page requires an exact current-set digest')
+        items = _items(self.items, ReviewEvent, 10)
+        _events(items, self.bank_id, self.release_id, self.through_version, self.next_after)
+        if any(item.kind not in ('contribution', 'adjudication') or item.details.get('target_id') != self.target_id for item in items):
+            raise WorkflowContractError('review event belongs to another target or kind')
+        object.__setattr__(self, 'items', items)
+        object.__setattr__(self, 'protocol', _protocol(self.protocol, self.protocol_identity))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {**_page_dict('sphynx.bank-target-review-details.v1', self), 'target_id': self.target_id,
+                'subject': self.subject.to_dict(), 'protocol_identity': self.protocol_identity.to_dict(),
+                'protocol': _thaw(self.protocol), 'current_contribution_set_digest': self.current_contribution_set_digest}
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> TargetReviewPage:
+        data = _fields(value, 'sphynx.bank-target-review-details.v1', {'bank_id', 'release_id', 'target_id',
+            'through_version', 'subject', 'protocol_identity', 'protocol', 'current_contribution_set_digest', 'items', 'next_after'})
+        data['items'] = _decode_items(data['items'], ReviewEvent, 10)
+        for name in ('subject', 'protocol_identity'):
+            data[name] = VersionedIdentity.from_dict(data[name])
+        return cls(**data)
+
+    def to_text(self) -> str:
+        return f'Target reviews: {self.bank_id}/{self.release_id}/{self.target_id} through version {self.through_version}; {len(self.items)} protected events. Current authority is rechecked on each read.'
+
+
+@dataclass(frozen=True)
+class ReviewOperationReceipt(_Readable):
+    operation_key: str
+    event: ReviewEvent
+    release_snapshot: BankRelease = field(repr=False)
+    eligibility_authority: str = 'receipt_snapshot_requires_current_read'
+
+    def __post_init__(self):
+        _key(self.operation_key)
+        if not isinstance(self.event, ReviewEvent) or not isinstance(self.release_snapshot, BankRelease):
+            raise WorkflowContractError('invalid review receipt records')
+        event, release = self.event, self.release_snapshot
+        _metadata(event)
+        if (self.eligibility_authority != 'receipt_snapshot_requires_current_read'
+                or (event.bank_id, event.release_id, event.team_id, event.version) !=
+                   (release.bank_id, release.release_id, release.team_id, release.version)):
+            raise WorkflowContractError('review receipt identity or historical authority differs')
+
+    def to_dict(self) -> dict[str, Any]:
+        return {'schema_version': 'sphynx.bank-review-operation.v1', 'operation_key': self.operation_key,
+                'event': self.event.to_dict(), 'release_snapshot': self.release_snapshot.to_dict(),
+                'eligibility_authority': self.eligibility_authority}
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ReviewOperationReceipt:
+        data = _fields(value, 'sphynx.bank-review-operation.v1',
+                       {'operation_key', 'event', 'release_snapshot', 'eligibility_authority'})
+        data['event'] = ReviewEvent.from_dict(data['event'])
+        data['release_snapshot'] = BankRelease.from_dict(data['release_snapshot'])
+        return cls(**data)
+
+    def to_text(self) -> str:
+        return f'Historical review receipt: {self.event.bank_id}/{self.event.release_id} at version {self.event.version}. Read the current release before using eligibility.'

sphynx/audit_contracts.py

@@ -0,0 +1,204 @@
+"""Neutral private audit records; construction never grants review authority.
+
+Only an authenticated service can stamp an actor or decide eligibility. These
+classes validate permitted wire records. Protected target/judgment payloads are
+hidden from repr, and become explicit only through authorized reads/to_dict().
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field, fields
+from datetime import datetime, timedelta
+import re
+from types import MappingProxyType
+from typing import Any, ClassVar
+
+from .evaluation_protocols import VersionedIdentity, _envelope
+from .workflow_contracts import WorkflowContractError, _object, _optional_text, _text, _texts, _thaw
+
+_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z")
+_OPERATION = re.compile(r"[A-Za-z0-9._:-]{16,100}\Z")
+_TARGETS = ("bank_curation", "output_judgment", "evaluator_audit")
+
+
+def _version(value):
+    if type(value) is not int or value < 1:
+        raise WorkflowContractError("audit version must be a positive integer")
+
+
+def _identity(value):
+    if not isinstance(value, VersionedIdentity) or value.digest is None:
+        raise WorkflowContractError("audit identity requires an exact version and digest")
+    return value
+
+
+def _wire(value):
+    if isinstance(value, VersionedIdentity):
+        return value.to_dict()
+    if isinstance(value, Mapping):
+        return {key: _wire(item) for key, item in value.items()}
+    return _thaw(value)
+
+
+def _construct(cls, values):
+    try:
+        return cls(**values)
+    except TypeError as exc:
+        raise WorkflowContractError("invalid " + cls.__name__ + " fields") from exc
+
+
+class _AuditWire:
+    _SCHEMA: ClassVar[str]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema_version": self._SCHEMA,
+                **{item.name: _wire(getattr(self, item.name)) for item in fields(self)}}
+
+
+@dataclass(frozen=True)
+class BankRelease(_AuditWire):
+    """A selected-bank summary, with separate use/ranking/acceptance eligibility."""
+
+    _SCHEMA: ClassVar[str] = "sphynx.bank-release.v1"
+    bank_id: str
+    release_id: str
+    team_id: str
+    release_digest: str
+    version: int
+    review_status: str
+    state: str
+    bindings: Mapping[str, VersionedIdentity]
+    eligibility: Mapping[str, Any]
+    parent_release_id: str | None = None
+    counts: Mapping[str, int] = field(default_factory=dict)
+
+    def __post_init__(self):
+        for name in ("bank_id", "release_id", "team_id"):
+            _text(getattr(self, name), name)
+        if type(self.release_digest) is not str or not _DIGEST.fullmatch(self.release_digest):
+            raise WorkflowContractError("release_digest must be canonical SHA-256")
+        _version(self.version)
+        if self.review_status not in ("pending", "provisional", "reviewed", "disputed", "needs_changes"):
+            raise WorkflowContractError("invalid bank review status")
+        if self.state not in ("active", "held", "withdrawn"):
+            raise WorkflowContractError("invalid bank release state")
+        _optional_text(self.parent_release_id, "parent_release_id")
+        if self.parent_release_id == self.release_id:
+            raise WorkflowContractError("release cannot be its own parent")
+        if not isinstance(self.bindings, Mapping) or not {"bank", "review_protocol", "review_policy"} <= set(self.bindings):
+            raise WorkflowContractError("release requires bank, review_protocol and review_policy identities")
+        bindings = {_text(key, "binding role"): _identity(value) for key, value in self.bindings.items()}
+        object.__setattr__(self, "bindings", MappingProxyType(bindings))
+        eligibility = _object(self.eligibility, "eligibility")
+        if set(eligibility) != {"development", "ranking", "acceptance"}:
+            raise WorkflowContractError("eligibility requires separate development, ranking and acceptance")
+        for value in eligibility.values():
+            if not isinstance(value, Mapping) or set(value) != {"eligible", "reasons"} or type(value["eligible"]) is not bool:
+                raise WorkflowContractError("eligibility requires an explicit boolean and reason list")
+            _texts(value["reasons"], "eligibility reasons")
+            if (not value["eligible"] and not value["reasons"]) or (self.state != "active" and value["eligible"]):
+                raise WorkflowContractError("ineligible/held release needs explicit truthful eligibility")
+        object.__setattr__(self, "eligibility", eligibility)
+        counts = _object(self.counts, "review counts")
+        if any(type(value) is not int or value < 0 for value in counts.values()):
+            raise WorkflowContractError("review counts must be nonnegative integers")
+        object.__setattr__(self, "counts", counts)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> BankRelease:
+        values = _envelope(value, cls._SCHEMA, cls)
+        bindings = values.get("bindings")
+        if not isinstance(bindings, Mapping):
+            raise WorkflowContractError("release bindings must be an object")
+        values["bindings"] = {key: VersionedIdentity.from_dict(item) for key, item in bindings.items()}
+        return _construct(cls, values)
+
+
+@dataclass(frozen=True)
+class ReviewTarget(_AuditWire):
+    """An authorized private review target, without domain-specific fields."""
+
+    _SCHEMA: ClassVar[str] = "sphynx.review-target.v1"
+    target_id: str
+    kind: str
+    subject: VersionedIdentity
+    protocol: VersionedIdentity
+    display: Mapping[str, Any] = field(repr=False)
+    required_for_curation: bool = False
+
+    def __post_init__(self):
+        _text(self.target_id, "target_id")
+        if self.kind not in _TARGETS:
+            raise WorkflowContractError("invalid review target kind")
+        _identity(self.subject); _identity(self.protocol)
+        if type(self.required_for_curation) is not bool or (self.required_for_curation and self.kind != "bank_curation"):
+            raise WorkflowContractError("only bank curation targets can be required for bank review")
+        object.__setattr__(self, "display", _object(self.display, "private review display"))
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ReviewTarget:
+        values = _envelope(value, cls._SCHEMA, cls)
+        for key in ("subject", "protocol"):
+            values[key] = VersionedIdentity.from_dict(values.get(key))
+        return _construct(cls, values)
+
+
+@dataclass(frozen=True)
+class ReviewContribution(_AuditWire):
+    """A write request. Actor, team, trust and timestamp are server-owned."""
+
+    _SCHEMA: ClassVar[str] = "sphynx.review-contribution-request.v1"
+    target_id: str
+    decision: str
+    expected_version: int
+    idempotency_key: str
+    judgment: Mapping[str, Any] = field(repr=False)
+    supersedes_contribution_id: str | None = None
+
+    def __post_init__(self):
+        _text(self.target_id, "target_id")
+        if self.decision not in ("approve", "reject", "abstain"):
+            raise WorkflowContractError("review decision must be approve, reject or abstain")
+        _version(self.expected_version)
+        if type(self.idempotency_key) is not str or not _OPERATION.fullmatch(self.idempotency_key):
+            raise WorkflowContractError("idempotency_key requires 16-100 ASCII identifier characters")
+        _optional_text(self.supersedes_contribution_id, "supersedes_contribution_id")
+        object.__setattr__(self, "judgment", _object(self.judgment, "private review judgment"))
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ReviewContribution:
+        return _construct(cls, _envelope(value, cls._SCHEMA, cls))
+
+
+@dataclass(frozen=True)
+class ReviewEvent(_AuditWire):
+    """An append-only service receipt. It cannot authenticate itself."""
+
+    _SCHEMA: ClassVar[str] = "sphynx.bank-review-event.v1"
+    event_id: str
+    bank_id: str
+    release_id: str
+    team_id: str
+    version: int
+    actor_id: str
+    created_at: str
+    kind: str
+    details: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    def __post_init__(self):
+        for name in ("event_id", "bank_id", "release_id", "team_id", "actor_id", "created_at"):
+            _text(getattr(self, name), name)
+        _version(self.version)
+        if self.kind not in ("release_created", "contribution", "adjudication", "hold", "resume", "withdraw"):
+            raise WorkflowContractError("invalid bank review event kind")
+        try:
+            timestamp = datetime.fromisoformat(self.created_at.replace("Z", "+00:00"))
+        except ValueError as exc:
+            raise WorkflowContractError("created_at must be an ISO UTC timestamp") from exc
+        if timestamp.utcoffset() != timedelta(0):
+            raise WorkflowContractError("created_at must include UTC timezone")
+        object.__setattr__(self, "details", _object(self.details, "permitted event details"))
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ReviewEvent:
+        return _construct(cls, _envelope(value, cls._SCHEMA, cls))

sphynx/audit_requests.py

@@ -0,0 +1,180 @@
+"""Immutable neutral private-audit requests; the service owns authorization."""
+from __future__ import annotations
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+import json
+import math
+import re
+import unicodedata
+from types import MappingProxyType
+from typing import Any, ClassVar
+
+from .audit_contracts import ReviewTarget, _AuditWire, _construct, _identity
+from .evaluation_protocols import VersionedIdentity, _envelope
+from .workflow_contracts import WorkflowContractError
+
+_ID = re.compile(r'[A-Za-z0-9._:-]{1,128}\Z')
+_KEY = re.compile(r'[A-Za-z0-9._:-]{16,100}\Z')
+_DIGEST = re.compile(r'sha256:[0-9a-f]{64}\Z')
+
+
+def _identifier(value: Any) -> str:
+    if type(value) is not str or not _ID.fullmatch(value) or value in ('.', '..'):
+        raise WorkflowContractError('audit path identity requires 1-128 ASCII identifier characters')
+    return value
+
+
+def _positive_version(value: Any) -> int:
+    if type(value) is not int or not 1 <= value <= 2**63 - 1:
+        raise WorkflowContractError('audit version must be a positive signed 64-bit integer')
+    return value
+
+
+def _key(value: Any) -> str:
+    if type(value) is not str or not _KEY.fullmatch(value):
+        raise WorkflowContractError('audit key requires 16-100 ASCII identifier characters')
+    return value
+
+
+def _bounded(value: Any, maximum: int) -> None:
+    nodes = 0
+    def walk(item, depth):
+        nonlocal nodes
+        nodes += 1
+        if depth > 20 or nodes > 4096:
+            raise WorkflowContractError('audit JSON exceeds structure limits')
+        if isinstance(item, Mapping):
+            if len(item) > 128 or any(type(key) is not str for key in item):
+                raise WorkflowContractError('audit JSON has invalid object fields')
+            for child in item.values():
+                walk(child, depth + 1)
+        elif isinstance(item, (tuple, list)):
+            for child in item:
+                walk(child, depth + 1)
+        elif type(item) is int:
+            if not -(2**63) <= item <= 2**64 - 1:
+                raise WorkflowContractError('audit integer exceeds exact service JSON range')
+        elif type(item) is float:
+            if not math.isfinite(item):
+                raise WorkflowContractError('audit number must be finite')
+        elif item is not None and type(item) not in (str, bool):
+            raise WorkflowContractError('audit payload must contain JSON values')
+    walk(value, 0)
+    try:
+        size = len(json.dumps(value, ensure_ascii=False, allow_nan=False, separators=(',', ':')).encode('utf-8'))
+    except (ValueError, TypeError, UnicodeError, RecursionError) as exc:
+        raise WorkflowContractError('invalid audit JSON') from exc
+    if size > maximum:
+        raise WorkflowContractError('audit JSON exceeds byte limit')
+
+
+def _exact_identity(value: VersionedIdentity) -> VersionedIdentity:
+    _identity(value)
+    for text, maximum in ((value.identity_id, 512), (value.version, 128)):
+        if len(text.encode('utf-8')) > maximum or any(unicodedata.category(char) == 'Cc' for char in text):
+            raise WorkflowContractError('audit identity exceeds service text limits')
+    return value
+
+
+def _reason(value: Any) -> str:
+    if type(value) is not str or not value.strip():
+        raise WorkflowContractError('audit reason requires 1-8192 UTF-8 bytes')
+    try:
+        size = len(value.encode('utf-8'))
+    except UnicodeEncodeError as exc:
+        raise WorkflowContractError('audit reason requires valid UTF-8') from exc
+    if size > 8192:
+        raise WorkflowContractError('audit reason requires 1-8192 UTF-8 bytes')
+    return value
+
+
+@dataclass(frozen=True)
+class BankReleaseDeclaration:
+    """Operator request. Contains identities/targets, no executable policy."""
+    release_id: str
+    bindings: Mapping[str, VersionedIdentity]
+    targets: tuple[ReviewTarget, ...] = field(repr=False)
+    idempotency_key: str
+    parent_release_id: str | None = None
+    _SCHEMA: ClassVar[str] = 'sphynx.bank-release-declaration.v1'
+
+    def __post_init__(self):
+        _identifier(self.release_id); _key(self.idempotency_key)
+        if self.parent_release_id is not None:
+            _identifier(self.parent_release_id)
+            if self.parent_release_id == self.release_id:
+                raise WorkflowContractError('release cannot be its own parent')
+        if (not isinstance(self.bindings, Mapping) or len(self.bindings) > 32 or
+                not {'bank', 'review_protocol', 'review_policy'} <= self.bindings.keys()):
+            raise WorkflowContractError('release needs exact bank/protocol/policy bindings')
+        bindings = {_identifier(key): _exact_identity(item) for key, item in self.bindings.items()}
+        if not isinstance(self.targets, (tuple, list)) or not 1 <= len(self.targets) <= 256:
+            raise WorkflowContractError('release needs 1-256 explicit targets')
+        if any(not isinstance(item, ReviewTarget) for item in self.targets):
+            raise WorkflowContractError('release targets must be ReviewTarget values')
+        if len({item.target_id for item in self.targets}) != len(self.targets):
+            raise WorkflowContractError('release has duplicate target identities')
+        for item in self.targets:
+            _identifier(item.target_id); _exact_identity(item.subject); _exact_identity(item.protocol)
+            _bounded(item.to_dict()['display'], 65536)
+        object.__setattr__(self, 'bindings', MappingProxyType(bindings))
+        object.__setattr__(self, 'targets', tuple(self.targets))
+        _bounded(self.to_dict(), 262144)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {'schema_version': self._SCHEMA, 'release_id': self.release_id,
+                'parent_release_id': self.parent_release_id,
+                'bindings': {key: item.to_dict() for key, item in self.bindings.items()},
+                'targets': [item.to_dict() for item in self.targets], 'idempotency_key': self.idempotency_key}
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> BankReleaseDeclaration:
+        values = _envelope(value, cls._SCHEMA, cls)
+        bindings, targets = values.get('bindings'), values.get('targets')
+        if not isinstance(bindings, Mapping) or not isinstance(targets, (tuple, list)):
+            raise WorkflowContractError('invalid release bindings/targets')
+        values['bindings'] = {key: VersionedIdentity.from_dict(item) for key, item in bindings.items()}
+        values['targets'] = tuple(ReviewTarget.from_dict(item) for item in targets)
+        return _construct(cls, values)
+
+
+@dataclass(frozen=True)
+class ReviewAdjudication(_AuditWire):
+    target_id: str
+    decision: str
+    expected_version: int
+    idempotency_key: str
+    contribution_set_digest: str
+    rationale: str = field(repr=False)
+    _SCHEMA: ClassVar[str] = 'sphynx.review-adjudication-request.v1'
+
+    def __post_init__(self):
+        _identifier(self.target_id); _positive_version(self.expected_version); _key(self.idempotency_key)
+        if self.decision not in ('approve', 'reject'):
+            raise WorkflowContractError('adjudication requires approve or reject')
+        if type(self.contribution_set_digest) is not str or not _DIGEST.fullmatch(self.contribution_set_digest):
+            raise WorkflowContractError('adjudication needs the exact current contribution-set digest')
+        _reason(self.rationale); _bounded(self.to_dict(), 16384)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ReviewAdjudication:
+        return _construct(cls, _envelope(value, cls._SCHEMA, cls))
+
+
+@dataclass(frozen=True)
+class BankReleaseTransition(_AuditWire):
+    action: str
+    expected_version: int
+    idempotency_key: str
+    reason: str = field(repr=False)
+    _SCHEMA: ClassVar[str] = 'sphynx.bank-release-transition.v1'
+
+    def __post_init__(self):
+        if self.action not in ('hold', 'resume', 'withdraw'):
+            raise WorkflowContractError('unknown release transition')
+        _positive_version(self.expected_version); _key(self.idempotency_key); _reason(self.reason)
+        _bounded(self.to_dict(), 16384)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> BankReleaseTransition:
+        return _construct(cls, _envelope(value, cls._SCHEMA, cls))