capsule-engine 0.1.0__py3-none-any.whl

capsule_engine/cli/packs_cmds.py

@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``capsule-engine packs`` verbs -- the packs-runtime's own CLI surface.
+
+  propose -- the GENERIC, READ-ONLY "would this pack
+             work" measurability report for ANY pack: resolves/MISSING-
+             INSTRUMENT per outcome, from the pack's own tier/mode/
+             evidence_instrument fields, over a JSONL corpus. Ported from
+             capsule-ledger's ``capsule setup propose --pack`` (moved here
+             -- the packs runtime's home) --
+             this mode never touches ``.capsule-setup/`` and persists
+             nothing, so it carries no dependency on the setup/Candidate
+             machinery that stayed in capsule-compiler.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ..packs import PackDefinitionError, load_pack_dir
+from ..packs import measurability_report as pack_measurability_report
+
+__all__ = ["add_parser"]
+
+
+def _load_units_jsonl(path: str) -> list[dict]:
+    units = []
+    with open(path, encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if line:
+                units.append(json.loads(line))
+    return units
+
+
+def _cmd_packs_propose(args: argparse.Namespace) -> int:
+    """READ-ONLY: prints resolves/MISSING-INSTRUMENT per outcome, persists
+    nothing -- there are no T1 declarations to confirm afterward. Confirmable
+    persistence for a generic pack is a separate design decision (a
+    MeasurabilityRow is not a Candidate/ProposedOutcome), not built here."""
+    if args.corpus is None:
+        print("capsule-engine packs propose: --corpus is required", file=sys.stderr)
+        return 2
+    if args.entity_key is None:
+        print(
+            "capsule-engine packs propose: --entity-key is required (no default -- names the unit field "
+            "identifying a repeat entity for fold_counterparty/fold_cohort rows, e.g. task_id, session_id)",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        pack = load_pack_dir(Path(args.pack))
+    except PackDefinitionError as exc:
+        print(f"capsule-engine packs propose: pack failed to load ({exc.reason}): {exc}", file=sys.stderr)
+        return 1
+
+    units = _load_units_jsonl(args.corpus)
+    key = args.entity_key
+    try:
+        report = pack_measurability_report.build_measurability_report(
+            pack, units, entity_key=pack_measurability_report.entity_key_field(key)
+        )
+    except pack_measurability_report.MissingEntityKeyField as exc:
+        print(f"capsule-engine packs propose: {exc}", file=sys.stderr)
+        return 2
+
+    print(f"pack: {pack.pack_id}")
+    print(f"corpus: {args.corpus} ({len(units)} unit(s))")
+    print(f"entity_key: {key}")
+    print("READ-ONLY report -- no declarations persisted")
+    print()
+    print(pack_measurability_report.render_terminal(report), end="")
+    return 0
+
+
+def add_parser(sub: argparse._SubParsersAction) -> argparse.ArgumentParser:
+    packs = sub.add_parser("packs", help="packs-runtime verbs: propose (generic measurability report)")
+    packs_sub = packs.add_subparsers(dest="packs_command")
+    packs.set_defaults(packs_parser=packs)
+
+    p_propose = packs_sub.add_parser(
+        "propose",
+        help="GENERIC READ-ONLY measurability report for any pack over a JSONL corpus",
+    )
+    p_propose.add_argument("--pack", required=True, help="path to a pack directory (pack.yaml)")
+    p_propose.add_argument("--corpus", default=None, help="path to a JSONL file of units shaped {'messages': [...]}")
+    p_propose.add_argument(
+        "--entity-key",
+        default=None,
+        help="REQUIRED, no default: the unit field identifying a repeat entity for fold_counterparty/"
+        "fold_cohort rows (e.g. task_id, session_id)",
+    )
+    p_propose.set_defaults(func=_cmd_packs_propose)
+
+    return packs

capsule_engine/cli/telemetry_cmd.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`capsule telemetry`: disclosure/status, and the 6-metric funnel report
+generator -- a reporting tool over already-collected events, not the
+collection itself. See ``capsule_ledger/telemetry/`` for the instrumentation."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from importlib import resources
+from pathlib import Path
+
+__all__ = ["add_parser"]
+
+_SYNTHETIC_FIXTURE = "synthetic_events.jsonl"
+
+
+def _cmd_status(_args: argparse.Namespace) -> int:
+    from ..telemetry.consent import DISCLOSURE_TEXT, is_opted_in
+    from ..telemetry.state import state_path
+
+    print(DISCLOSURE_TEXT)
+    print(f"currently: {'ON' if is_opted_in() else 'OFF (default)'}")
+    if is_opted_in():
+        print(f"local state file: {state_path()}")
+    return 0
+
+
+def _load_events(path: str | None, *, use_fixture: bool) -> list[dict]:
+    if use_fixture:
+        text = resources.files("capsule_engine.telemetry").joinpath("fixtures", _SYNTHETIC_FIXTURE).read_text(
+            encoding="utf-8"
+        )
+    else:
+        text = Path(path).read_text(encoding="utf-8")
+    return [json.loads(line) for line in text.splitlines() if line.strip()]
+
+
+def _cmd_funnel(args: argparse.Namespace) -> int:
+    from ..telemetry.funnel import compute_funnel, render_funnel_report
+
+    if not args.dry_run and not args.events:
+        print("capsule telemetry funnel: --events PATH is required unless --dry-run is given", file=sys.stderr)
+        return 2
+
+    raw_events = _load_events(args.events, use_fixture=args.dry_run)
+    report = compute_funnel(raw_events)
+    text = render_funnel_report(report)
+
+    if args.dry_run:
+        text = "(dry run -- rendered against bundled synthetic fixture data, no real telemetry)\n\n" + text
+
+    if args.out:
+        Path(args.out).write_text(text, encoding="utf-8")
+        print(f"wrote {args.out}")
+    else:
+        print(text)
+    return 0
+
+
+def add_parser(sub: argparse._SubParsersAction) -> argparse.ArgumentParser:
+    telemetry = sub.add_parser("telemetry", help="telemetry disclosure/status, and the 6-metric funnel report")
+    telemetry_sub = telemetry.add_subparsers(dest="telemetry_command")
+    telemetry.set_defaults(telemetry_parser=telemetry)
+
+    p_status = telemetry_sub.add_parser("status", help="show the disclosure text and current opt-in state")
+    p_status.set_defaults(func=_cmd_status)
+
+    p_funnel = telemetry_sub.add_parser(
+        "funnel", help="render the 6-metric funnel report over collected telemetry (or synthetic fixture data)"
+    )
+    p_funnel.add_argument("--events", help="path to a JSONL file of collected telemetry events")
+    p_funnel.add_argument(
+        "--dry-run", action="store_true",
+        help="render against bundled synthetic/fixture data instead of --events (no real telemetry required)",
+    )
+    p_funnel.add_argument("--out", help="write the report to this path instead of stdout")
+    p_funnel.set_defaults(func=_cmd_funnel)
+
+    return telemetry

capsule_engine/cli/tenant_cmds.py

@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``capsule tenant`` verbs: provision/upgrade/list engine-instance-per-tenant
+deployments (``capsule_ledger.tenants``) -- the "run one whole engine
+instance per tenant" pattern for a caller embedding this package for many
+customers. See ``docs/tenant-provisioning.md`` for the layout and the
+isolation rationale.
+
+  init    -- provision a brand-new tenant: fresh ledger dir, this tenant's
+             own pinned manifest, first activation capsule. Refuses if the
+             tenant already has anything on disk.
+  upgrade -- re-materialize an existing tenant's manifest (e.g. after a
+             pack version bump) and record a new activation epoch, only if
+             the manifest actually changed. Refuses if the tenant was never
+             initialized.
+  list    -- print every provisioned tenant's id/manifest/key under a
+             tenants-root, from their own tenant.json files.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ..envcompat import env_get
+from ..packs import PackDefinitionError, load_pack_dir
+from ..tenants import TenantProvisionError, init_tenant, list_tenants, upgrade_tenant
+
+__all__ = ["add_parser"]
+
+BUILTIN_PACK_CATALOG_DIR = Path(__file__).resolve().parent.parent / "packs" / "catalog"
+
+_KEY_ID_ENV = "CAPSULE_MCP_SIGNING_KEY_ID"
+_SECRET_ENV = "CAPSULE_MCP_SIGNING_SECRET"
+
+
+def _available_packs(catalog_dir: Path) -> list[str]:
+    if not catalog_dir.is_dir():
+        return []
+    return sorted(p.name for p in catalog_dir.iterdir() if (p / "pack.yaml").is_file())
+
+
+def _load_pack(args: argparse.Namespace, *, verb: str):
+    """Shared ``--pack <name>`` resolution, same lookup ``capsule init``
+    uses -- returns ``None`` (default manifest) when ``--pack`` is omitted,
+    or a ``(pack, None)``/``(None, error_code)`` pair on failure."""
+    if not args.pack:
+        return None, None
+    catalog_dir = Path(args.pack_catalog_dir) if args.pack_catalog_dir else BUILTIN_PACK_CATALOG_DIR
+    pack_dir = catalog_dir / args.pack
+    if not (pack_dir / "pack.yaml").is_file():
+        available = _available_packs(catalog_dir)
+        print(f"capsule tenant {verb}: no pack named {args.pack!r} in {catalog_dir}", file=sys.stderr)
+        print(f"  available packs: {available or '<none>'}", file=sys.stderr)
+        return None, 2
+    try:
+        return load_pack_dir(pack_dir), None
+    except PackDefinitionError as exc:
+        print(f"capsule tenant {verb}: pack {args.pack!r} failed to load ({exc.reason}): {exc}", file=sys.stderr)
+        return None, 1
+
+
+def _cmd_tenant_init(args: argparse.Namespace) -> int:
+    pack, error_rc = _load_pack(args, verb="init")
+    if error_rc is not None:
+        return error_rc
+
+    key_id = args.key_id or env_get(_KEY_ID_ENV)
+    secret_text = args.secret or env_get(_SECRET_ENV)
+    secret = secret_text.encode("utf-8") if secret_text is not None else None
+
+    try:
+        result = init_tenant(
+            args.tenants_root,
+            args.tenant_id,
+            pack=pack,
+            key_id=key_id,
+            secret=secret,
+            operator=args.operator,
+            developer=args.developer,
+        )
+    except TenantProvisionError as exc:
+        print(f"capsule tenant init: {exc.reason}: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"provisioned tenant {args.tenant_id!r} at {result.layout.root}")
+    print(f"  ledger:          {result.layout.ledger_dir}")
+    print(f"  manifest:        {result.layout.manifest_path}")
+    print(f"  manifest id:     {result.manifest_id}")
+    print(f"  manifest digest: {result.manifest_digest}")
+    print(f"  activation:      {result.activation_capsule_id}")
+    print(f"  key id:          {result.key_id}")
+    if result.generated_secret:
+        print()
+        print(
+            "signing secret (shown once -- this command does not persist it anywhere; "
+            "store it in this tenant's own secret manager, not this repo or terminal history):"
+        )
+        print(f"  {result.secret.decode('utf-8')}")
+    return 0
+
+
+def _cmd_tenant_upgrade(args: argparse.Namespace) -> int:
+    pack, error_rc = _load_pack(args, verb="upgrade")
+    if error_rc is not None:
+        return error_rc
+
+    key_id = args.key_id or env_get(_KEY_ID_ENV)
+    secret_text = args.secret or env_get(_SECRET_ENV)
+    if not key_id or not secret_text:
+        print(
+            f"capsule tenant upgrade: --key-id/--secret are required (or set ${_KEY_ID_ENV}/${_SECRET_ENV}) -- "
+            "this must be the tenant's current live signing key, not a fresh one",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        result = upgrade_tenant(
+            args.tenants_root,
+            args.tenant_id,
+            pack=pack,
+            key_id=key_id,
+            secret=secret_text.encode("utf-8"),
+            operator=args.operator,
+            developer=args.developer,
+        )
+    except TenantProvisionError as exc:
+        print(f"capsule tenant upgrade: {exc.reason}: {exc}", file=sys.stderr)
+        return 1
+
+    if not result.changed:
+        print(f"tenant {args.tenant_id!r}: manifest unchanged ({result.manifest_digest}), nothing to activate")
+        return 0
+
+    print(f"upgraded tenant {args.tenant_id!r} at {result.layout.root}")
+    print(f"  manifest id:     {result.manifest_id}")
+    print(f"  manifest digest: {result.manifest_digest}")
+    print(f"  activation:      {result.activation_capsule_id}")
+    return 0
+
+
+def _cmd_tenant_list(args: argparse.Namespace) -> int:
+    tenants = list_tenants(args.tenants_root)
+    if not tenants:
+        print(f"no provisioned tenants under {args.tenants_root}")
+        return 0
+    for tenant in tenants:
+        print(
+            f"{tenant['tenant_id']}\t{tenant['manifest_id']}\t{tenant['manifest_digest'][:16]}…\t"
+            f"key={tenant['key_id']}"
+        )
+    return 0
+
+
+def _add_pack_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--pack", default=None, help="starter pack name to install for this tenant (default: none, built-in default manifest)"
+    )
+    p.add_argument(
+        "--pack-catalog-dir", default=None, help="override the built-in pack catalog directory (mainly for tests)"
+    )
+
+
+def add_parser(sub: argparse._SubParsersAction) -> argparse.ArgumentParser:
+    tenant = sub.add_parser(
+        "tenant", help="engine-instance-per-tenant provisioning: init/upgrade/list (see docs/tenant-provisioning.md)"
+    )
+    tenant_sub = tenant.add_subparsers(dest="tenant_command")
+    tenant.set_defaults(tenant_parser=tenant)
+
+    p_init = tenant_sub.add_parser(
+        "init", help="provision a brand-new tenant instance (ledger dir + manifest + first activation)"
+    )
+    p_init.add_argument("--tenants-root", required=True, help="directory holding one subdirectory per tenant")
+    p_init.add_argument("--tenant-id", required=True, help="this tenant's id (becomes a directory name -- lowercase, digits, hyphens)")
+    _add_pack_args(p_init)
+    p_init.add_argument("--operator", default="local", help="operator identity for the first activation capsule (default: 'local')")
+    p_init.add_argument("--developer", default="capsule-tenant-init", help="developer identity for the first activation capsule")
+    p_init.add_argument("--key-id", default=None, help=f"this tenant's signing key id (default: '<tenant-id>-signing-key', or ${_KEY_ID_ENV})")
+    p_init.add_argument("--secret", default=None, help=f"this tenant's signing key secret (default: ${_SECRET_ENV}, or freshly generated)")
+    p_init.set_defaults(func=_cmd_tenant_init)
+
+    p_upgrade = tenant_sub.add_parser(
+        "upgrade", help="re-materialize an existing tenant's manifest and record a new activation epoch if it changed"
+    )
+    p_upgrade.add_argument("--tenants-root", required=True, help="directory holding one subdirectory per tenant")
+    p_upgrade.add_argument("--tenant-id", required=True, help="this tenant's id")
+    _add_pack_args(p_upgrade)
+    p_upgrade.add_argument("--operator", default="local", help="operator identity for the new activation capsule (default: 'local')")
+    p_upgrade.add_argument("--developer", default="capsule-tenant-upgrade", help="developer identity for the new activation capsule")
+    p_upgrade.add_argument("--key-id", default=None, help=f"this tenant's CURRENT live signing key id (default: ${_KEY_ID_ENV}) -- required")
+    p_upgrade.add_argument("--secret", default=None, help=f"this tenant's CURRENT live signing key secret (default: ${_SECRET_ENV}) -- required")
+    p_upgrade.set_defaults(func=_cmd_tenant_upgrade)
+
+    p_list = tenant_sub.add_parser("list", help="list every provisioned tenant under a tenants-root")
+    p_list.add_argument("--tenants-root", required=True, help="directory holding one subdirectory per tenant")
+    p_list.set_defaults(func=_cmd_tenant_list)
+
+    return tenant

capsule_engine/cli/verify_cmd.py

@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`capsule verify`: verify one ledger record, or an entire bundle file offline.
+
+Exit codes (CI-friendly, and distinguished because "not found" and "found
+but tampered" are different failure modes a caller may want to branch on):
+  0  verified clean
+  1  verification failed (digest mismatch, chain gap, etc. -- ``result.ok`` is False)
+  2  usage error (no capsule_id/--bundle given, or the capsule/bundle wasn't found)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from agent_action_capsule import verify as verify_capsule
+from capsule_emit.ledger_io import open_ledger, require_ledger_path
+
+from .format import build_echo
+
+__all__ = ["add_parser", "run"]
+
+
+def add_parser(sub: argparse._SubParsersAction) -> argparse.ArgumentParser:
+    p = sub.add_parser("verify", help="verify one ledger record, or an entire bundle file")
+    p.add_argument("capsule_id", nargs="?", help="a capsule_id or an unambiguous prefix (omit with --bundle)")
+    p.add_argument("--ledger", help="ledger store directory or a JSONL fixture file (default: $CAPSULE_LEDGER)")
+    p.add_argument(
+        "--bundle", help="verify every record in a bundle file produced by `capsule bundle`, offline and self-contained"
+    )
+    p.add_argument("--json", action="store_true", help="print the raw verification result(s) as JSON")
+    p.set_defaults(func=run)
+    return p
+
+
+def _print_result(capsule_id: str, result) -> bool:
+    if result.ok:
+        print(f"✓ verifies · {capsule_id}")
+        return True
+    print(f"✗ verification failed · {capsule_id}")
+    for finding in result.findings:
+        print(f"  - {finding.code}: {finding.detail}")
+    return False
+
+
+def run(args: argparse.Namespace) -> int:
+    # ``verify`` only exists at all in the "full" packaging arm -- see
+    # ``cli/main.py`` -- so any use of it is M5's "verify run" fact.
+    from ..telemetry.record import record_evidence_touch
+
+    record_evidence_touch("full")
+
+    if args.bundle:
+        return _run_bundle(args)
+    if not args.capsule_id:
+        print("capsule verify: capsule_id is required unless --bundle is given", file=sys.stderr)
+        return 2
+
+    ledger_path = require_ledger_path("verify", args)
+    if ledger_path is None:
+        return 2
+
+    with open_ledger(ledger_path) as store:
+        record = store.fetch(args.capsule_id)
+        if record is None:
+            print(f"no such capsule {args.capsule_id!r} in ledger {ledger_path}", file=sys.stderr)
+            return 2
+        result = store.verify(record.capsule_id)
+        capsule_id = record.capsule_id
+
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "capsule_id": capsule_id,
+                    "ok": result.ok,
+                    "findings": [{"code": f.code, "detail": f.detail, "severity": f.severity} for f in result.findings],
+                },
+                indent=2,
+                sort_keys=True,
+            )
+        )
+        return 0 if result.ok else 1
+
+    ok = _print_result(capsule_id, result)
+    print()
+    print(build_echo("verify", positional=capsule_id))
+    return 0 if ok else 1
+
+
+def _run_bundle(args: argparse.Namespace) -> int:
+    try:
+        with open(args.bundle, encoding="utf-8") as fh:
+            bundle = json.load(fh)
+    except OSError as exc:
+        print(f"capsule verify: cannot read bundle {args.bundle!r}: {exc}", file=sys.stderr)
+        return 2
+
+    records = bundle.get("records", [])
+    ids = [r.get("capsule_id") for r in records]
+    all_ok = True
+    for capsule in records:
+        result = verify_capsule(capsule, store=ids)
+        ok = _print_result(capsule.get("capsule_id", "?"), result)
+        all_ok = all_ok and ok
+
+    print()
+    status = "verifies clean" if all_ok else "verification FAILED"
+    print(f"bundle {args.bundle}: {len(records)} record(s), {status}")
+    return 0 if all_ok else 1

capsule_engine/compiler/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared foundation for the outcome compiler: closed vocabulary and the
+advisory effect model.
+
+This subpackage holds ONLY the pure, dependency-free pieces of the outcome
+compiler that ``capsule_engine.packs.loader`` needs at pack-load time to
+validate ``outcomes[]`` entries. Neither module here touches
+``guards.capsule``/``guards.signing`` -- the sealed-capsule builders
+(compilation record, offer/response, refusal, scope census) stay in the
+separate ``capsule-compiler`` repo, which imports these two modules as
+``capsule_engine.compiler.vocabulary`` / ``capsule_engine.compiler.effect_model``.
+"""
+from __future__ import annotations

capsule_engine/compiler/effect_model.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The advisory effect model (design §4b gap 1): every effect model this
+codebase had before this wave assumed the agent caused the state change it
+observed. A read-only advisory deployment's agent cannot act at all -- a
+person acts on its recommendations manually -- so any field that quietly
+encodes agent-causation breaks visibly there instead of invisibly at a
+deployment that never falsifies it.
+
+Three claims, closed set. Two are legitimate near-misses; the third MUST be
+refused at compile time, and this module is where that refusal is
+mechanical rather than a reviewer's judgment call: ``compile_effect_claim``
+returns a verdict pair plus (for the refused claim) the reason code, and
+raises nothing -- refusing IS the successful, expected return for that
+claim, not an exceptional path. ``packs/loader.py`` is what turns an
+``EvidenceContract`` that gets this wrong into a load-time error (an outcome
+cannot declare ``effect_claim="agent.caused_resolution"`` with anything
+other than the verdict pair this module computes for it).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .vocabulary import VerdictPair
+
+__all__ = [
+    "ADMISSIBLE_EFFECT_CLAIMS",
+    "REFUSED_EFFECT_CLAIMS",
+    "EFFECT_CLAIMS",
+    "UnknownEffectClaim",
+    "EffectClaimCompilation",
+    "compile_effect_claim",
+]
+
+# The two legitimate near-misses (design §4b gap 1). Both are recordable
+# without asserting causation: a human's action can be cited by its own
+# capsule (``recommendation.acted_on``) or the ordering of a resolution
+# after an action can be cited without asserting the action produced it
+# (``resolution.followed_action``).
+ADMISSIBLE_EFFECT_CLAIMS = frozenset({"recommendation.acted_on", "resolution.followed_action"})
+
+# The undecomposable claim. A resolved ticket following a recommendation is
+# correlation, not causation -- the record can honestly attest the
+# recommendation was made, a human acted, the ticket resolved, and the
+# elapsed order of those, but never that the agent caused the resolution.
+REFUSED_EFFECT_CLAIMS = frozenset({"agent.caused_resolution"})
+
+EFFECT_CLAIMS = ADMISSIBLE_EFFECT_CLAIMS | REFUSED_EFFECT_CLAIMS
+
+
+class UnknownEffectClaim(ValueError):
+    """``effect_claim`` is not one of the closed ``EFFECT_CLAIMS`` set --
+    same "unregistered is a typo" doctrine as every other closed vocabulary
+    in this repo; this is not an open, registry-resolved vocabulary."""
+
+
+@dataclass(frozen=True)
+class EffectClaimCompilation:
+    effect_claim: str
+    verdict: VerdictPair
+    refusal_reason_code: str | None = None
+
+
+def compile_effect_claim(effect_claim: str) -> EffectClaimCompilation:
+    """Compile one effect claim into its verdict pair. The refused claim
+    compiles successfully -- to a REFUSED/REFUSED pair with its reason code
+    -- rather than raising, because the refusal itself is the correct,
+    recordable outcome (design §4: "a report that visibly refuses one claim
+    is a report whose other claims get believed")."""
+    if effect_claim in ADMISSIBLE_EFFECT_CLAIMS:
+        return EffectClaimCompilation(
+            effect_claim=effect_claim, verdict=VerdictPair(forward="DETERMINISTIC", backward="DETERMINISTIC")
+        )
+    if effect_claim in REFUSED_EFFECT_CLAIMS:
+        return EffectClaimCompilation(
+            effect_claim=effect_claim,
+            verdict=VerdictPair(forward="REFUSED", backward="REFUSED"),
+            refusal_reason_code="agent_caused_resolution_undecomposable",
+        )
+    raise UnknownEffectClaim(f"effect_claim must be one of {sorted(EFFECT_CLAIMS)}; got {effect_claim!r}")