capsule-engine 0.1.0__py3-none-any.whl

capsule_engine/compiler/vocabulary.py

@@ -0,0 +1,253 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Closed vocabulary for the outcome compiler, and its display strings.
+
+Five closed sets, each shipping its plain-language rendering in this same
+module (design §3.6: "an enum without a display string is developer
+vocabulary leaking onto the auditor's desk"):
+
+- ``FORWARD_VERDICTS`` / ``BACKWARD_VERDICTS`` -- the verdict PAIR every
+  compiled statement carries (design §2.2). This is a schema *shape*
+  decision: two enums per statement, not one annotation. The judge is never
+  in the enforcement path, so ``MODEL-ASSISTED`` is a backward-only value --
+  it has no forward counterpart.
+- ``RESPONSE_CLASSES`` -- the offer/response denominator primitive (design
+  §4b gap 2): an offer was made, a response occurred, and the response is
+  recorded whether or not it was the one wanted. Named ``response_class``,
+  never ``consent`` -- that word imports one partner's domain vocabulary
+  into a shared format.
+- ``REFUSAL_REASON_CODES`` -- v0, closed, extended deliberately (same
+  "unregistered is a typo" doctrine as ``packs/schema.py``'s other closed
+  sets). Seeded with exactly the two refusals this wave's design work
+  demonstrated: an effect claim that assumes the agent caused a resolution
+  it can only be shown to have recommended, and a goal too unbounded to
+  decompose into windowed proxies.
+- ``RE_DERIVABILITY_GRADES`` -- design §2.3: whether a constraint's inputs
+  are sealed and its verdict independently re-derivable from a compiled
+  plan alone (``pure_replay`` -- e.g. containment), or whether re-deriving
+  it means possessing the ledger and adopting this repo's own fold
+  semantics over ledger state no capsule carries (``ledger_state_dependent``
+  -- e.g. caps). Labelled rather than hidden: "an asymmetry named is an
+  honesty feature; an asymmetry discovered is an embarrassment."
+
+**The reserved-verdict-word deny-list.** Per licensing law and design §3.6:
+publisher vocabulary may name things; only the verifier states verdicts.
+Seven words are reserved outright (they assert soundness properties this
+format does not make): *verified, certified, compliant, guaranteed, pass,
+approved, tamper-proof*. On top of that fixed list, ``check_display_string`` also refuses any
+display string that contains the raw enum token it is describing
+(case-insensitively) -- e.g. ``MODEL-ASSISTED``'s own rendering may not
+contain the substring "model-assisted". That second rule is what "the
+mappability labels" (build plan Phase 1 item 6) cashes out to
+structurally: self-referential, so it covers the verdict-pair and
+refusal/grade jargon without a second, driftable list to keep in sync.
+It does not apply to ``response_class`` -- ``accepted``/``declined``/
+``deferred``/``no_response`` are already plain English, and restating one
+is not the "developer vocabulary leaking onto the auditor's desk" failure
+this rule exists to catch.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+__all__ = [
+    "FORWARD_VERDICTS",
+    "BACKWARD_VERDICTS",
+    "RESPONSE_CLASSES",
+    "REFUSAL_REASON_CODES",
+    "RE_DERIVABILITY_GRADES",
+    "RESERVED_VERDICT_WORDS",
+    "VerdictPair",
+    "DisplayViolation",
+    "display_string",
+    "check_display_string",
+    "check_all_display_strings",
+    "assert_every_value_has_a_display_string",
+]
+
+# --- Verdict pair (design §2.2) --------------------------------------------
+FORWARD_VERDICTS = frozenset(
+    {"DETERMINISTIC", "UNAVAILABLE-MODEL-REQUIRED", "UNAVAILABLE-STATE-REQUIRED", "REFUSED"}
+)
+BACKWARD_VERDICTS = frozenset({"DETERMINISTIC", "MODEL-ASSISTED", "MANUAL", "WITH-INSTRUMENTATION", "REFUSED"})
+
+# --- offer/response denominator primitive (design §4b gap 2) ---------------
+RESPONSE_CLASSES = frozenset({"accepted", "declined", "deferred", "no_response"})
+
+# --- refusal reason codes, v0 -----------------------------------------------
+REFUSAL_REASON_CODES = frozenset(
+    {
+        # design §4b gap 1: the format is incoherent without this refusal --
+        # a causal claim about an advisory-only agent has no evidence that
+        # could confirm it, only correlation.
+        "agent_caused_resolution_undecomposable",
+        # design §3.4 / build plan Phase 1: an "eventually X" goal with no
+        # window cannot be compiled into a windowed proxy and must refuse
+        # rather than ship as an opaque score.
+        "unbounded_goal_unmonitorable",
+        # airline-engagement A8 ("the customer was satisfied"): a
+        # DIFFERENT refusal from unbounded_goal_unmonitorable above -- that
+        # one is about a missing time window (a windowed proxy would fix
+        # it); this one is not fixed by any window, because a person's
+        # felt state is never witnessed by a record, only their own
+        # statement about it, which is testimony, not detection. "We do
+        # not measure feelings" (agent-human-engagement thesis): a claim
+        # about satisfaction/trust/comfort inferred from conduct or words
+        # alone is the exact overclaim this format refuses to make.
+        "subjective_state_unattestable",
+    }
+)
+
+# --- re-derivability grade (design §2.3) ------------------------------------
+RE_DERIVABILITY_GRADES = frozenset({"pure_replay", "ledger_state_dependent"})
+
+RESERVED_VERDICT_WORDS = frozenset(
+    {"verified", "certified", "compliant", "guaranteed", "pass", "approved", "tamper-proof"}
+)
+
+_ALL_CLOSED_SETS: dict[str, frozenset[str]] = {
+    "forward_verdict": FORWARD_VERDICTS,
+    "backward_verdict": BACKWARD_VERDICTS,
+    "response_class": RESPONSE_CLASSES,
+    "refusal_reason_code": REFUSAL_REASON_CODES,
+    "re_derivability_grade": RE_DERIVABILITY_GRADES,
+}
+
+# ``response_class`` values (accepted/declined/deferred/no_response) are
+# already plain English -- restating one in its own display string is not
+# "developer vocabulary leaking onto the auditor's desk", the failure mode
+# the self-referential check exists to catch. That failure mode is real for
+# the SCREAMING-KEBAB and snake_case categories below (a verifier stating
+# raw "MODEL-ASSISTED" instead of a sentence), so the self-check applies
+# only to those.
+_SELF_TOKEN_CHECK_CATEGORIES = frozenset(
+    {"forward_verdict", "backward_verdict", "refusal_reason_code", "re_derivability_grade"}
+)
+
+
+@dataclass(frozen=True)
+class VerdictPair:
+    """A compiled statement's two verdicts. Both must come from their own
+    closed set -- ``MODEL-ASSISTED`` forward or ``UNAVAILABLE-MODEL-REQUIRED``
+    backward are both typos, not values, because the judge is never in the
+    enforcement path (design §2.2)."""
+
+    forward: str
+    backward: str
+
+    def __post_init__(self) -> None:
+        if self.forward not in FORWARD_VERDICTS:
+            raise ValueError(f"forward verdict must be one of {sorted(FORWARD_VERDICTS)}; got {self.forward!r}")
+        if self.backward not in BACKWARD_VERDICTS:
+            raise ValueError(f"backward verdict must be one of {sorted(BACKWARD_VERDICTS)}; got {self.backward!r}")
+
+
+# category -> {value -> display string}. Every value in every closed set
+# above MUST have an entry here -- enforced by
+# ``assert_every_value_has_a_display_string`` (run at import time, below,
+# and exercised directly by tests/test_compiler_vocabulary.py).
+DISPLAY_STRINGS: dict[str, dict[str, str]] = {
+    "forward_verdict": {
+        "DETERMINISTIC": "checked automatically before the action ran",
+        "UNAVAILABLE-MODEL-REQUIRED": "not checked before the action ran -- would need a live judgment call",
+        "UNAVAILABLE-STATE-REQUIRED": "not checked before the action ran -- the needed record did not exist yet",
+        "REFUSED": "no automatic check exists for this claim",
+    },
+    "backward_verdict": {
+        "DETERMINISTIC": "provable from the record alone",
+        "MODEL-ASSISTED": "provable with a reviewer's judgment over the record",
+        "MANUAL": "provable only by a person attesting to it directly",
+        "WITH-INSTRUMENTATION": "provable once a missing record is captured; not claimed today",
+        "REFUSED": "this claim cannot be decomposed into evidence that would prove it",
+    },
+    "response_class": {
+        "accepted": "the offer was accepted",
+        "declined": "the offer was declined",
+        "deferred": "a decision on the offer was put off",
+        "no_response": "no response to the offer was recorded",
+    },
+    "refusal_reason_code": {
+        "agent_caused_resolution_undecomposable": (
+            "the record can show a recommendation was made and a person acted, "
+            "but not that the recommendation is what made them act"
+        ),
+        "unbounded_goal_unmonitorable": "this goal has no time window, so no record could ever settle it",
+        "subjective_state_unattestable": (
+            "a person's own felt state cannot be read off a record -- only what they said or did"
+        ),
+    },
+    "re_derivability_grade": {
+        "pure_replay": "a stranger can recompute this verdict from the compiled plan alone",
+        "ledger_state_dependent": "recomputing this verdict requires the ledger, not just the compiled plan",
+    },
+}
+
+
+@dataclass(frozen=True)
+class DisplayViolation:
+    category: str
+    value: str
+    display_string: str
+    reserved_words: tuple[str, ...]
+
+
+def display_string(category: str, value: str) -> str:
+    """The plain-language rendering for ``value`` in the named closed set.
+    Raises ``KeyError`` for anything outside the closed set or missing a
+    rendering -- these are curated, closed vocabularies (unlike the open,
+    registry-resolved ``action_class`` conventions), so an unregistered
+    value here is a typo, not a legitimate degraded state."""
+    table = DISPLAY_STRINGS[category]
+    return table[value]
+
+
+def check_display_string(category: str, value: str, text: str) -> DisplayViolation | None:
+    """Return a ``DisplayViolation`` if ``text`` (the display string for
+    ``category``/``value``) carries a reserved verdict word, or the raw
+    token it is itself describing. ``None`` means clean."""
+    lowered = text.lower()
+    hits: list[str] = []
+    for word in RESERVED_VERDICT_WORDS:
+        if re.search(rf"\b{re.escape(word)}\b", lowered):
+            hits.append(word)
+    if category in _SELF_TOKEN_CHECK_CATEGORIES and value.lower() in lowered:
+        hits.append(value)
+    if hits:
+        return DisplayViolation(category=category, value=value, display_string=text, reserved_words=tuple(hits))
+    return None
+
+
+def check_all_display_strings(
+    table: dict[str, dict[str, str]] | None = None,
+) -> list[DisplayViolation]:
+    """Scan every entry in ``table`` (defaults to the real, shipped
+    ``DISPLAY_STRINGS``) and return every violation found. Used both as the
+    CI gate (``tests/test_compiler_vocabulary.py`` fails the build if this
+    is non-empty against the real table) and, with a deliberately-corrupted
+    ``table`` argument, as the RED-before-green mutant proof that the check
+    can fail at all."""
+    violations: list[DisplayViolation] = []
+    for category, entries in (table or DISPLAY_STRINGS).items():
+        for value, text in entries.items():
+            v = check_display_string(category, value, text)
+            if v is not None:
+                violations.append(v)
+    return violations
+
+
+def assert_every_value_has_a_display_string() -> None:
+    """Every value in every closed set above must render -- the P1
+    acceptance line ("every enum renders"). Raises ``AssertionError`` naming
+    exactly what's missing; run at import time so a schema addition that
+    forgets its display string fails immediately, not at first render."""
+    for category, values in _ALL_CLOSED_SETS.items():
+        table = DISPLAY_STRINGS.get(category, {})
+        missing = sorted(v for v in values if v not in table)
+        if missing:
+            raise AssertionError(f"{category}: missing display string for {missing}")
+        extra = sorted(v for v in table if v not in values)
+        if extra:
+            raise AssertionError(f"{category}: display string table carries unregistered value(s) {extra}")
+
+
+assert_every_value_has_a_display_string()

capsule_engine/console/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The local console: `capsule console`'s data layer (`api.py`), HTTP wiring
+(`server.py`), and the static UI it serves -- `tokens.css`/`components.css`
+(the shared component library), plus `console.css`/`console.js`/`console.html`
+(this screen's own layout and client logic). `gallery.html` next to these
+files is the component-library review page, not part of the served UI.
+
+LOCAL ONLY: this package serves localhost, reads a real ledger on disk, and
+makes no outbound network calls anywhere in what it renders.
+"""

capsule_engine/console/api.py

@@ -0,0 +1,251 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Data-shaping functions for the local console server (`capsule console`).
+
+Pure functions over a real :class:`~cll.ledger.api.LedgerAPI` -- no
+HTTP, no server state -- so they're exercisable directly in tests without a
+socket. ``server.py`` is the thin HTTP wiring on top of this module. Every
+field returned here comes straight off a real capsule, a real
+``store.verify()`` result, or a real fold replay -- nothing is invented for
+display.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from cll.ledger.api import LedgerAPI, ScanQuery
+from cll.ledger.records import LedgerRecord
+
+from ..cli.format import (
+    assurance_grade_parts,
+    build_echo,
+    format_coverage_footnote,
+    format_envelope_line,
+    format_staleness,
+    summarize_action,
+)
+from ..envcompat import env_get
+from ..folds import Catalog, FoldDeterminismError, evaluate_one
+from ..registry import describe_action_class
+
+__all__ = [
+    "checkpoint_status",
+    "list_records",
+    "record_detail",
+    "record_summary",
+]
+
+DEFAULT_CATALOG_DIR = Path(__file__).resolve().parent.parent / "folds" / "catalog_defs"
+
+
+def _fold_catalog_dir() -> Path:
+    env = env_get("CAPSULE_FOLD_DIR")
+    return Path(env) if env else DEFAULT_CATALOG_DIR
+
+
+def _fingerprint(capsule_id: str) -> str:
+    return capsule_id[:8] + "…" if capsule_id else ""
+
+
+def _withheld_payloads(capsule: dict) -> list[dict[str, Any]]:
+    """Every payload the capsule commits to by digest: the disposition reason
+    and each check's evidence. A capsule never carries the preimages, so each
+    one renders as withheld with its digest, never as a blank field."""
+    payloads = []
+    reason_digest = (capsule.get("disposition") or {}).get("reason_digest")
+    if reason_digest:
+        payloads.append({"label": "reason", "check_id": None, "digest": reason_digest, "state": "withheld"})
+    for c in capsule.get("constraints") or []:
+        if c.get("evidence_digest"):
+            payloads.append(
+                {"label": "evidence", "check_id": c.get("id"), "digest": c["evidence_digest"], "state": "withheld"}
+            )
+    return payloads
+
+
+def _action_class_info(capsule: dict) -> dict[str, Any] | None:
+    action_class = (capsule.get("asg_payload") or {}).get("action_class")
+    if not action_class:
+        return None
+    convention = describe_action_class(action_class)
+    return {"value": action_class, "label": convention.label, "registered": convention.registered}
+
+
+def _assurance_grade_info(assurance: dict) -> dict[str, Any]:
+    grade, badged = assurance_grade_parts(assurance)
+    return {"grade": grade, "badged": badged}
+
+
+def checkpoint_status(store: LedgerAPI) -> dict[str, Any]:
+    """The console's freshness status line: "checkpoint #N · as of <age> ·
+    verifies offline" -- always computed from a fresh re-scan, never cached,
+    so its own age is always ~0 (the same convention `capsule log`'s own
+    trailing status line already uses -- see `cli/log_cmd.py`)."""
+    total = sum(1 for _ in store.scan(ScanQuery()))
+    staleness_label = format_staleness(0)
+    return {
+        "checkpoint": total,
+        "staleness_label": staleness_label,
+        "line": f"checkpoint #{total} · as of {staleness_label} · verifies offline",
+    }
+
+
+def record_summary(record: LedgerRecord) -> dict[str, Any]:
+    capsule = record.capsule
+    assurance = capsule.get("assurance") or {}
+    return {
+        "capsule_id": record.capsule_id,
+        "fingerprint": _fingerprint(record.capsule_id),
+        "seq": record.seq,
+        "agent": capsule.get("developer", ""),
+        "operator": capsule.get("operator", ""),
+        "action": summarize_action(capsule),
+        "action_type": capsule.get("action_type", ""),
+        "action_class": _action_class_info(capsule),
+        "timestamp": capsule.get("timestamp", ""),
+        "disposition": capsule.get("disposition") or {},
+        "assurance": assurance,
+        "assurance_grade": _assurance_grade_info(assurance),
+    }
+
+
+def _echo_parts(filters: dict[str, Any]) -> list[tuple[str, object]]:
+    return [
+        ("--agent", filters.get("agent")),
+        ("--since", filters.get("since")),
+        ("--until", filters.get("until")),
+        ("--counterparty", filters.get("counterparty")),
+        ("--verdict", filters.get("verdict")),
+        ("--action-type", filters.get("action_type")),
+        ("--limit", filters.get("limit")),
+    ]
+
+
+def list_records(store: LedgerAPI, filters: dict[str, Any]) -> dict[str, Any]:
+    """The filtered record stream, plus the exact `capsule log` invocation
+    that reproduces this same filtered view -- the CLI-echo standing rule
+    applied to the console's own record stream/filters panel."""
+    query = ScanQuery(
+        agent=filters.get("agent"),
+        since=filters.get("since"),
+        until=filters.get("until"),
+        counterparty=filters.get("counterparty"),
+        verdict=filters.get("verdict"),
+        action_type=filters.get("action_type"),
+        limit=filters.get("limit"),
+    )
+    total = sum(1 for _ in store.scan(ScanQuery()))
+    records = [record_summary(r) for r in store.scan(query)]
+    gaps = store.find_gaps()
+    return {
+        "records": records,
+        "total": total,
+        "shown": len(records),
+        "gap_count": len(gaps),
+        "cli_echo": build_echo("log", flags=_echo_parts(filters)),
+    }
+
+
+def _fold_strip(store: LedgerAPI, developer: str) -> list[dict[str, Any]]:
+    """Live fold values for this record's agent -- the catalog's own
+    definitions, replayed over the real ledger. A rolling-window fold's
+    anchor is the ledger's own latest record timestamp (spec §3 rule 1:
+    never a wall-clock read), matching how `report/build.py` anchors its
+    own replay."""
+    records = [r.capsule for r in store.scan(ScanQuery())]
+    if not records:
+        return []
+    as_of = records[-1].get("timestamp")
+    catalog = Catalog(_fold_catalog_dir())
+    strip: list[dict[str, Any]] = []
+    for entry in catalog.list_entries():
+        definition = entry.definition
+        key_value = developer if definition.key else None
+        try:
+            trace = evaluate_one(definition, records, key_value=key_value, as_of=as_of)
+        except FoldDeterminismError:
+            continue
+        strip.append(
+            {
+                "fold_id": definition.fold_id,
+                "result": trace.result,
+                "envelope_line": format_envelope_line(trace.to_envelope()),
+                # T2R rev9(a): "a report cannot render a number without its
+                # coverage statement" -- this is the one place today that
+                # renders a fold's `result` for a human, so it never does so
+                # without the footnote beside it.
+                "coverage_footnote": format_coverage_footnote(trace.coverage_statement()),
+            }
+        )
+    return strip
+
+
+def record_detail(store: LedgerAPI, capsule_id: str) -> dict[str, Any] | None:
+    """Everything the inspector panel needs for one selected record:
+    identity fingerprint, sealed fields, verdict, which checks ran, the
+    chain in both directions (what this record cites, what cites it), a
+    real cryptographic verify() result, and its agent's live fold strip."""
+    record = store.fetch(capsule_id)
+    if record is None:
+        return None
+
+    capsule = record.capsule
+    chain = capsule.get("chain") or {}
+    constraints = capsule.get("constraints") or []
+    disposition = capsule.get("disposition") or {}
+
+    parent_id = chain.get("parent_capsule_id")
+    cites = None
+    if parent_id:
+        parent = store.fetch(parent_id)
+        cites = {
+            "capsule_id": parent_id,
+            "fingerprint": _fingerprint(parent_id),
+            "relation": chain.get("relation"),
+            "found": parent is not None,
+        }
+
+    cited_by = [
+        {
+            "capsule_id": other.capsule_id,
+            "fingerprint": _fingerprint(other.capsule_id),
+            "relation": (other.capsule.get("chain") or {}).get("relation"),
+        }
+        for other in store.scan(ScanQuery())
+        if (other.capsule.get("chain") or {}).get("parent_capsule_id") == record.capsule_id
+    ]
+
+    verify_result = store.verify(record.capsule_id)
+
+    return {
+        "capsule_id": record.capsule_id,
+        "fingerprint": _fingerprint(record.capsule_id),
+        "seq": record.seq,
+        "sealed": capsule,
+        "disposition": disposition,
+        "action_class": _action_class_info(capsule),
+        "assurance_grade": _assurance_grade_info(capsule.get("assurance") or {}),
+        "checks": [
+            {
+                "id": c.get("id"),
+                "result": c.get("result"),
+                "severity": c.get("severity"),
+                "check_type": c.get("check_type"),
+                "method": c.get("method"),
+                "evidence_digest": c.get("evidence_digest"),
+            }
+            for c in constraints
+        ],
+        "payloads": _withheld_payloads(capsule),
+        "chain": {"cites": cites, "cited_by": cited_by},
+        "verify": {
+            "ok": verify_result.ok if verify_result is not None else None,
+            "findings": (
+                [{"code": f.code, "detail": f.detail, "severity": f.severity} for f in verify_result.findings]
+                if verify_result is not None
+                else []
+            ),
+        },
+        "fold_strip": _fold_strip(store, capsule.get("developer", "")),
+        "cli_echo": build_echo("show", positional=record.capsule_id),
+    }