problem-frame-gate 0.3.0__py3-none-any.whl

problem_frame_gate/records.py

@@ -0,0 +1,210 @@
+"""Finite proof-carrying records from the audit calculus."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .digest import digest_json
+from .model import Envelope, Horizon
+from .result import CheckBuilder, CheckResult
+from .verifier import EnvelopeVerifier, canonical_order, digest_log
+
+
+@dataclass(frozen=True, slots=True)
+class SwapCover:
+    """Finite set of adjacent pairs certified as component-preserving."""
+
+    independent_pairs: tuple[tuple[str, str], ...] = ()
+    component_equalities: tuple[str, ...] = ()
+
+    def permits(self, left: str, right: str) -> bool:
+        return (left, right) in self.independent_pairs or (right, left) in self.independent_pairs
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "independent_pairs": [list(pair) for pair in self.independent_pairs],
+            "component_equalities": list(self.component_equalities),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ReplayCertificate:
+    """Certificate that a non-canonical replay word reaches the canonical word."""
+
+    word: tuple[str, ...]
+    swaps: tuple[tuple[int, str, str], ...]
+    cover: SwapCover
+    target_digest: str
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "word": list(self.word),
+            "swaps": [[index, left, right] for index, left, right in self.swaps],
+            "cover": self.cover.to_json(),
+            "target_digest": self.target_digest,
+        }
+
+
+def check_replay_certificate(
+    horizon: Horizon, envelopes: tuple[Envelope, ...], certificate: ReplayCertificate
+) -> CheckResult:
+    builder = CheckBuilder(footprint={"TraceChecker", "FoldKernel", "EnvelopeVerifier"})
+    legal = EnvelopeVerifier().verify(horizon, envelopes)
+    if not legal.ok:
+        return legal.merge(builder.result())
+
+    id_set = {env.eid for env in envelopes}
+    if set(certificate.word) != id_set or len(certificate.word) != len(id_set):
+        builder.error("replay-word", "replay word must be a permutation of the log envelope ids")
+        return builder.result(digest=digest_log(envelopes), transcript_digest=digest_json(certificate.to_json()))
+    if certificate.target_digest != digest_log(envelopes):
+        builder.error("replay-target-digest", "replay certificate target digest does not match the log")
+
+    current = list(certificate.word)
+    for step, (index, left, right) in enumerate(certificate.swaps):
+        if index < 0 or index + 1 >= len(current):
+            builder.error("replay-swap-index", "swap index is outside the replay word", details={"step": step})
+            continue
+        if current[index] != left or current[index + 1] != right:
+            builder.error(
+                "replay-swap-pair",
+                "swap row does not match the current adjacent pair",
+                details={"step": step, "expected": [current[index], current[index + 1]], "actual": [left, right]},
+            )
+            continue
+        if not certificate.cover.permits(left, right):
+            builder.error(
+                "replay-swap-cover",
+                "adjacent swap is not covered by an independence certificate",
+                details={"step": step, "pair": [left, right]},
+            )
+        current[index], current[index + 1] = current[index + 1], current[index]
+
+    canonical = [env.eid for env in canonical_order(horizon, envelopes)]
+    if current != canonical:
+        builder.error(
+            "replay-not-canonical",
+            "certified swap trace does not reach the canonical replay word",
+            details={"actual": current, "canonical": canonical},
+        )
+    return builder.result(digest=digest_log(envelopes), transcript_digest=digest_json(certificate.to_json()))
+
+
+@dataclass(frozen=True, slots=True)
+class SourceCut:
+    """Finite consistent-cut record for a source prefix."""
+
+    cut_id: str
+    source_time: int
+    included_eids: tuple[str, ...]
+    excluded_frontier_eids: tuple[str, ...]
+    digest: str
+    clock_rows: tuple[str, ...] = ()
+    watermark_rows: tuple[str, ...] = ()
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "cut_id": self.cut_id,
+            "source_time": self.source_time,
+            "included_eids": list(self.included_eids),
+            "excluded_frontier_eids": list(self.excluded_frontier_eids),
+            "digest": self.digest,
+            "clock_rows": list(self.clock_rows),
+            "watermark_rows": list(self.watermark_rows),
+        }
+
+
+def check_source_cut(horizon: Horizon, envelopes: tuple[Envelope, ...], cut: SourceCut) -> CheckResult:
+    builder = CheckBuilder(footprint={"ClockWatermark", "EnvelopeVerifier"})
+    legal = EnvelopeVerifier().verify(horizon, envelopes)
+    if not legal.ok:
+        return legal.merge(builder.result())
+
+    by_id = {env.eid: env for env in envelopes}
+    expected_included = tuple(sorted(env.eid for env in envelopes if env.commit_time <= cut.source_time))
+    expected_frontier = tuple(sorted(env.eid for env in envelopes if env.commit_time > cut.source_time))
+    if tuple(sorted(cut.included_eids)) != expected_included:
+        builder.error(
+            "source-cut-included",
+            "source cut included set does not match commit-time prefix",
+            details={"expected": list(expected_included), "actual": sorted(cut.included_eids)},
+        )
+    if tuple(sorted(cut.excluded_frontier_eids)) != expected_frontier:
+        builder.error(
+            "source-cut-frontier",
+            "source cut frontier must list all later envelopes in the finite log",
+            details={"expected": list(expected_frontier), "actual": sorted(cut.excluded_frontier_eids)},
+        )
+
+    included = tuple(by_id[eid] for eid in cut.included_eids if eid in by_id)
+    if cut.digest != digest_log(included):
+        builder.error("source-cut-digest", "source cut digest does not match included envelopes")
+
+    included_ids = set(cut.included_eids)
+    for env in included:
+        for dep in env.dependencies:
+            if dep.eid is not None and dep.eid not in included_ids:
+                builder.error(
+                    "source-cut-dependency",
+                    "source cut is not closed under dependencies",
+                    location=env.eid,
+                    details=dep.to_json(),
+                )
+        if env.commit_group:
+            group_ids = {row.eid for row in envelopes if row.commit_group == env.commit_group}
+            if not group_ids.issubset(included_ids):
+                builder.error(
+                    "source-cut-commit-group",
+                    "source cut is not closed under commit groups",
+                    location=env.commit_group,
+                )
+    return builder.result(digest=cut.digest, transcript_digest=digest_json(cut.to_json()))
+
+
+@dataclass(frozen=True, slots=True)
+class TransitionRecord:
+    source_digest: str
+    target_digest: str
+    kind: str
+    transcript_digest: str
+    capacity_class: str = "normal"
+
+    def to_json(self) -> dict[str, str]:
+        return {
+            "source_digest": self.source_digest,
+            "target_digest": self.target_digest,
+            "kind": self.kind,
+            "transcript_digest": self.transcript_digest,
+            "capacity_class": self.capacity_class,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ReachabilityTranscript:
+    transitions: tuple[TransitionRecord, ...]
+    assumptions: tuple[str, ...] = field(default_factory=tuple)
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "transitions": [transition.to_json() for transition in self.transitions],
+            "assumptions": list(self.assumptions),
+        }
+
+
+def check_reachability(transcript: ReachabilityTranscript) -> CheckResult:
+    builder = CheckBuilder(footprint={"ReachTranscript"})
+    previous_target: str | None = None
+    for index, transition in enumerate(transcript.transitions):
+        if not transition.source_digest or not transition.target_digest or not transition.transcript_digest:
+            builder.error("reach-record", "transition record must bind source, target, and premise transcript")
+        if previous_target is not None and transition.source_digest != previous_target:
+            builder.error(
+                "reach-chain",
+                "transition source digest must match previous target digest",
+                details={"index": index, "expected": previous_target, "actual": transition.source_digest},
+            )
+        previous_target = transition.target_digest
+    for assumption in transcript.assumptions:
+        builder.add_assumption(assumption)
+    return builder.result(transcript_digest=digest_json(transcript.to_json()))

problem_frame_gate/result.py

@@ -0,0 +1,148 @@
+"""Small result objects shared by all checkers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from typing import Any, Literal
+
+Severity = Literal["error", "warning"]
+
+
+@dataclass(frozen=True, slots=True)
+class Issue:
+    """One checker finding."""
+
+    code: str
+    message: str
+    location: str = ""
+    severity: Severity = "error"
+    details: Mapping[str, Any] = field(default_factory=dict)
+
+    def to_json(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "code": self.code,
+            "message": self.message,
+            "severity": self.severity,
+        }
+        if self.location:
+            data["location"] = self.location
+        if self.details:
+            data["details"] = dict(self.details)
+        return data
+
+
+@dataclass(frozen=True, slots=True)
+class CheckResult:
+    """A finite checker result with an explicit trusted-footprint label set."""
+
+    ok: bool
+    issues: tuple[Issue, ...] = ()
+    footprint: frozenset[str] = frozenset()
+    digest: str | None = None
+    transcript_digest: str | None = None
+    assumptions: tuple[str, ...] = ()
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+    @classmethod
+    def success(
+        cls,
+        *,
+        footprint: set[str] | frozenset[str] | None = None,
+        digest: str | None = None,
+        transcript_digest: str | None = None,
+        assumptions: tuple[str, ...] = (),
+    ) -> CheckResult:
+        return cls(True, (), frozenset(footprint or ()), digest, transcript_digest, assumptions)
+
+    @classmethod
+    def fail(
+        cls,
+        *issues: Issue,
+        footprint: set[str] | frozenset[str] | None = None,
+        digest: str | None = None,
+        transcript_digest: str | None = None,
+        assumptions: tuple[str, ...] = (),
+    ) -> CheckResult:
+        return cls(False, tuple(issues), frozenset(footprint or ()), digest, transcript_digest, assumptions)
+
+    def with_digest(self, digest: str) -> CheckResult:
+        return replace(self, digest=digest)
+
+    def with_transcript_digest(self, transcript_digest: str) -> CheckResult:
+        return replace(self, transcript_digest=transcript_digest)
+
+    def merge(self, *others: CheckResult) -> CheckResult:
+        ok = self.ok and all(other.ok for other in others)
+        issues = self.issues + tuple(issue for other in others for issue in other.issues)
+        footprint = set(self.footprint)
+        assumptions = list(self.assumptions)
+        for other in others:
+            footprint.update(other.footprint)
+            assumptions.extend(item for item in other.assumptions if item not in assumptions)
+        transcript_digest = self.transcript_digest
+        if transcript_digest is None:
+            transcript_digest = next((other.transcript_digest for other in others if other.transcript_digest), None)
+        return CheckResult(ok, issues, frozenset(footprint), self.digest, transcript_digest, tuple(assumptions))
+
+    def to_json(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "ok": self.ok,
+            "issues": [issue.to_json() for issue in self.issues],
+            "footprint": sorted(self.footprint),
+        }
+        if self.digest:
+            data["digest"] = self.digest
+        if self.transcript_digest:
+            data["transcript_digest"] = self.transcript_digest
+        if self.assumptions:
+            data["assumptions"] = list(self.assumptions)
+        return data
+
+
+class CheckBuilder:
+    """Mutable helper for deterministic finite checkers."""
+
+    def __init__(self, *, footprint: set[str] | None = None) -> None:
+        self._issues: list[Issue] = []
+        self._footprint = set(footprint or ())
+        self._assumptions: list[str] = []
+
+    def error(
+        self,
+        code: str,
+        message: str,
+        *,
+        location: str = "",
+        details: Mapping[str, Any] | None = None,
+    ) -> None:
+        self._issues.append(Issue(code, message, location=location, severity="error", details=details or {}))
+
+    def warning(
+        self,
+        code: str,
+        message: str,
+        *,
+        location: str = "",
+        details: Mapping[str, Any] | None = None,
+    ) -> None:
+        self._issues.append(Issue(code, message, location=location, severity="warning", details=details or {}))
+
+    def add_footprint(self, *labels: str) -> None:
+        self._footprint.update(labels)
+
+    def add_assumption(self, *labels: str) -> None:
+        self._assumptions.extend(label for label in labels if label not in self._assumptions)
+
+    def result(self, *, digest: str | None = None, transcript_digest: str | None = None) -> CheckResult:
+        ok = not any(issue.severity == "error" for issue in self._issues)
+        return CheckResult(
+            ok,
+            tuple(self._issues),
+            frozenset(self._footprint),
+            digest,
+            transcript_digest,
+            tuple(self._assumptions),
+        )

problem_frame_gate/risk.py

@@ -0,0 +1,203 @@
+"""Finite risk-ledger helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from fractions import Fraction
+from typing import Any
+
+from .certificates import check_certificate_live
+from .fold import FoldState
+from .model import Horizon
+from .result import CheckBuilder, CheckResult
+
+
+@dataclass(frozen=True, slots=True)
+class RiskLedgerSummary:
+    total_spend: Fraction
+    spend_ids: tuple[str, ...]
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "total_spend": f"{self.total_spend.numerator}/{self.total_spend.denominator}",
+            "spend_ids": list(self.spend_ids),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class RiskClaimRecord:
+    """Finite risk-claim record used by the risk theorem."""
+
+    claim_id: str
+    risk_id: str
+    hypothesis_id: str
+    mode: str
+    cert_id: str
+    eta: str
+    event_id: str
+    standardized_event_id: str
+    selection_event_id: str | None = None
+    stopping_time_id: str | None = None
+    selection_time: int | None = None
+    ledger_digest: str | None = None
+    route_check: bool = True
+    assumption: str = "StatisticalModel"
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "claim_id": self.claim_id,
+            "risk_id": self.risk_id,
+            "hypothesis_id": self.hypothesis_id,
+            "mode": self.mode,
+            "cert_id": self.cert_id,
+            "eta": self.eta,
+            "event_id": self.event_id,
+            "standardized_event_id": self.standardized_event_id,
+            "selection_event_id": self.selection_event_id,
+            "stopping_time_id": self.stopping_time_id,
+            "selection_time": self.selection_time,
+            "ledger_digest": self.ledger_digest,
+            "route_check": self.route_check,
+            "assumption": self.assumption,
+        }
+
+
+def summarize_risk_ledger(state: FoldState) -> RiskLedgerSummary:
+    spends: dict[str, dict[str, Any]] = state.component("risk").get("spends", {})
+    total = sum((Fraction(str(spend.get("eta", "0"))) for spend in spends.values()), start=Fraction(0))
+    return RiskLedgerSummary(total, tuple(sorted(spends)))
+
+
+def check_risk_ledger(state: FoldState, *, alpha: Fraction | str | None = None) -> CheckResult:
+    """Check finite spend accounting and an optional global risk bound."""
+
+    builder = CheckBuilder(footprint={"RiskLedger", "RiskTranscript"})
+    risk = state.component("risk")
+    reserves: dict[str, dict[str, Any]] = risk.get("reserves", {})
+    spends: dict[str, dict[str, Any]] = risk.get("spends", {})
+
+    for risk_id, spend in spends.items():
+        reserve = reserves.get(risk_id)
+        if reserve is None:
+            builder.error("risk-spend-without-reserve", "risk spend has no reserve", location=risk_id)
+            continue
+        if int(reserve.get("reserved_at", 0)) > int(spend.get("spent_at", 0)):
+            builder.error("risk-order", "risk spend precedes its reserve", location=risk_id)
+        if Fraction(str(spend.get("eta", "0"))) < 0:
+            builder.error("negative-risk-spend", "risk spend must be non-negative", location=risk_id)
+
+    summary = summarize_risk_ledger(state)
+    if alpha is not None and summary.total_spend > Fraction(str(alpha)):
+        builder.error(
+            "risk-bound-exceeded",
+            "finite risk spend exceeds the declared bound",
+            details={"total": str(summary.total_spend), "alpha": str(alpha)},
+        )
+    return builder.result()
+
+
+def check_risk_spend_live(
+    state: FoldState,
+    *,
+    risk_id: str,
+    hypothesis_id: str,
+    mode: str,
+    cert_id: str,
+    at_time: int,
+    ledger_digest: str | None = None,
+    horizon: Horizon | None = None,
+) -> CheckResult:
+    """Before-use check for one risk spend."""
+
+    builder = CheckBuilder(footprint={"RiskLedger", "RiskTranscript", "ClockWatermark"})
+    risk = state.component("risk")
+    spend = risk.get("spends", {}).get(risk_id)
+    if spend is None:
+        builder.error("risk-spend-missing", "risk spend is not installed", location=risk_id)
+        return builder.result()
+    if spend.get("hypothesis_id") != hypothesis_id:
+        builder.error("risk-hypothesis-mismatch", "risk spend cites a different hypothesis", location=risk_id)
+    if spend.get("mode") != mode:
+        builder.error("risk-mode-mismatch", "risk spend cites a different statistical mode", location=risk_id)
+    if horizon is not None and mode not in horizon.risk_modes:
+        builder.error("risk-mode-undeclared", "risk mode is not declared by the manifest", location=risk_id)
+    if spend.get("cert_id") != cert_id:
+        builder.error("risk-cert-mismatch", "risk spend cites a different certificate", location=risk_id)
+    if ledger_digest is not None and spend.get("ledger_digest") != ledger_digest:
+        builder.error("risk-ledger-mismatch", "risk spend cites a different ledger digest", location=risk_id)
+    if int(spend.get("spent_at", 0)) > at_time:
+        builder.error("risk-spend-after-use", "risk spend is committed after use", location=risk_id)
+    closed_at = spend.get("closed_at")
+    if closed_at is not None and int(closed_at) <= at_time:
+        builder.error("risk-spend-closed", "risk spend is already closed at use time", location=risk_id)
+    return builder.result().merge(check_certificate_live(state, cert_id, at_time, horizon=horizon))
+
+
+def check_risk_claims(
+    state: FoldState,
+    records: tuple[RiskClaimRecord, ...],
+    *,
+    alpha: Fraction | str,
+    at_time: int,
+    horizon: Horizon,
+) -> CheckResult:
+    """Check finite installed risk claims and their union-bound spend."""
+
+    builder = CheckBuilder(footprint={"RiskLedger", "RiskTranscript"})
+    seen_risks: set[str] = set()
+    total = Fraction(0)
+    for record in records:
+        if record.risk_id in seen_risks:
+            builder.error("risk-claim-duplicate", "risk id appears in more than one claim", location=record.risk_id)
+        seen_risks.add(record.risk_id)
+        total += Fraction(record.eta)
+        spend = check_risk_spend_live(
+            state,
+            risk_id=record.risk_id,
+            hypothesis_id=record.hypothesis_id,
+            mode=record.mode,
+            cert_id=record.cert_id,
+            at_time=at_time,
+            ledger_digest=record.ledger_digest,
+            horizon=horizon,
+        )
+        if not spend.ok:
+            for issue in spend.issues:
+                builder.error(issue.code, issue.message, location=issue.location, details=issue.details)
+        if record.mode == "fixed" and not record.event_id:
+            builder.error("risk-fixed-event", "fixed mode requires a failure event", location=record.claim_id)
+        if record.mode == "selectedEvent" and not record.selection_event_id:
+            builder.error(
+                "risk-selection-event",
+                "selected-event mode requires a selection event",
+                location=record.claim_id,
+            )
+        if record.mode == "conditionalSelective" and not record.route_check:
+            builder.error(
+                "risk-conditional-route",
+                "conditional-selective mode requires an accepted route check",
+                location=record.claim_id,
+            )
+        if record.mode == "anytime" and not record.stopping_time_id:
+            builder.error(
+                "risk-stopping-time",
+                "anytime mode requires a certified stopping time",
+                location=record.claim_id,
+            )
+        if record.selection_time is not None:
+            reserve = state.component("risk").get("reserves", {}).get(record.risk_id, {})
+            if int(reserve.get("reserved_at", at_time + 1)) >= record.selection_time:
+                builder.error(
+                    "risk-post-selection-reserve",
+                    "risk reserve must precede the selection or stopping decision",
+                    location=record.claim_id,
+                )
+        if record.assumption:
+            builder.add_assumption(record.assumption)
+    if total > Fraction(str(alpha)):
+        builder.error(
+            "risk-alpha-bound",
+            "finite risk spend exceeds the declared alpha bound",
+            details={"total": str(total), "alpha": str(alpha)},
+        )
+    return builder.result()

problem_frame_gate/security.py

@@ -0,0 +1,88 @@
+"""Sensitive-data guardrails for audit-log payloads."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+SECRET_KEY_NAME = re.compile(
+    r"(?i)(api[_-]?key|access[_-]?key|secret|private[_-]?key|password|credential|client[_-]?secret)"
+)
+
+SECRET_VALUE_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("aws access key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    ("GitHub token", re.compile(r"\bgh[pousr]_[A-Za-z0-9_]{30,}\b")),
+    ("OpenAI API key", re.compile(r"\bsk-[A-Za-z0-9_\-]{20,}\b")),
+    ("private key block", re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----")),
+    (
+        "JWT-like token",
+        re.compile(r"\beyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\b"),
+    ),
+)
+
+LOCAL_PATH_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("Windows user path", re.compile(r"(?i)\b[A-Z]:\\Users\\[^\\\s]+")),
+    ("Unix home path", re.compile(r"(?i)(^|\s)/home/[^/\s]+")),
+    ("SSH material path", re.compile(r"(?i)(^|[/\\])\.ssh([/\\]|$)")),
+    ("cloud credentials path", re.compile(r"(?i)(^|[/\\])\.(aws|config/gcloud)([/\\]|$)")),
+)
+
+
+@dataclass(frozen=True, slots=True)
+class SensitiveDataIssue:
+    path: str
+    reason: str
+    preview: str
+
+    def to_json(self) -> dict[str, str]:
+        return {"path": self.path, "reason": self.reason, "preview": self.preview}
+
+
+def scan_for_sensitive_data(value: Any, *, allow_local_paths: bool = False) -> tuple[SensitiveDataIssue, ...]:
+    """Find common secrets and machine-local paths in a JSON-like value."""
+
+    issues: list[SensitiveDataIssue] = []
+    _walk(value, "$", issues, allow_local_paths=allow_local_paths)
+    return tuple(issues)
+
+
+def _walk(value: Any, path: str, issues: list[SensitiveDataIssue], *, allow_local_paths: bool) -> None:
+    if isinstance(value, Mapping):
+        for key, child in value.items():
+            key_text = str(key)
+            child_path = f"{path}.{key_text}"
+            if SECRET_KEY_NAME.search(key_text) and _non_empty_scalar(child):
+                issues.append(SensitiveDataIssue(child_path, "secret-looking field name", _preview(child)))
+            _walk(child, child_path, issues, allow_local_paths=allow_local_paths)
+        return
+
+    if isinstance(value, tuple | list):
+        for index, child in enumerate(value):
+            _walk(child, f"{path}[{index}]", issues, allow_local_paths=allow_local_paths)
+        return
+
+    if not isinstance(value, str):
+        return
+
+    for reason, pattern in SECRET_VALUE_PATTERNS:
+        if pattern.search(value):
+            issues.append(SensitiveDataIssue(path, reason, _preview(value)))
+    if not allow_local_paths:
+        for reason, pattern in LOCAL_PATH_PATTERNS:
+            if pattern.search(value):
+                issues.append(SensitiveDataIssue(path, reason, _preview(value)))
+
+
+def _non_empty_scalar(value: Any) -> bool:
+    if isinstance(value, str):
+        return bool(value.strip())
+    return value is not None and not isinstance(value, Mapping | list | tuple)
+
+
+def _preview(value: Any) -> str:
+    text = str(value).replace("\n", "\\n")
+    if len(text) <= 16:
+        return "***"
+    return f"{text[:4]}...{text[-4:]}"