capsule-engine 0.1.0__tar.gz → 0.2.0__tar.gz

{capsule_engine-0.1.0 → capsule_engine-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capsule-engine
-Version: 0.1.0
+Version: 0.2.0
 Summary: The thin single-node engine: guard, append-only fold compute, packs, policy activation, and the local console/report/bundle-viewer runtime for AI agent actions.
 Author: Action State Group
 License-Expression: Apache-2.0 AND MIT
@@ -39,7 +39,8 @@ console/report/bundle-viewer runtime.
 pip install capsule-engine
 ```
 
-It installs the `capsule_engine` package and the `capsule-engine` command. Its dependencies,
+It installs the `capsule_engine` package, the `capsule-engine` command and `capsulectl-engine`, a
+capsulectl plugin (`capsulectl engine check --ruleset FILE`). Its dependencies,
 `agent-action-capsule`, `checkpointed-local-log`, `capsule-emit`, `jsonschema` and `pyyaml`, come
 from PyPI.
 

{capsule_engine-0.1.0 → capsule_engine-0.2.0}/README.md

@@ -8,7 +8,8 @@ console/report/bundle-viewer runtime.
 pip install capsule-engine
 ```
 
-It installs the `capsule_engine` package and the `capsule-engine` command. Its dependencies,
+It installs the `capsule_engine` package, the `capsule-engine` command and `capsulectl-engine`, a
+capsulectl plugin (`capsulectl engine check --ruleset FILE`). Its dependencies,
 `agent-action-capsule`, `checkpointed-local-log`, `capsule-emit`, `jsonschema` and `pyyaml`, come
 from PyPI.
 

capsule_engine-0.2.0/capsule_engine/cli/engine_plugin.py

@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`capsulectl-engine`: the engine as a capsulectl plugin (cli-plugin/v1).
+
+On a trusted plugin root, capsulectl wires it up as `capsulectl engine`. On
+the reserved `cli-plugin-metadata` argument it prints the handshake object
+capsulectl checks (capsule-cli docs/PLUGINS.md). Its one subcommand,
+`check --ruleset FILE`, reads one external-check-input/v0 on stdin and prints
+one external-check-result/v0 (``rulesets/check.py``): exit 0 means a result
+was printed, whatever its verdict; any other exit is a refusal, named on
+stderr, with nothing on stdout. That is capsule-cli #137's rules-checker
+contract too, so the same launcher pins as a deal profile's
+`--rules-checker` with the command
+`["<root>/capsulectl-engine", "check", "--ruleset", "FILE"]`, FILE an
+absolute path (capsulectl does not set the checker's working directory).
+
+capsulectl pins this launcher's bytes, and the launcher is a console-script
+stub: the code it runs is the installed capsule-engine package, which the pin
+does not cover. So a check's name/version (``record_type_coverage/1``) is
+frozen once released, and a change to what it decides is a new version.
+
+Install: `capsulectl plugin install ./capsulectl-engine`, pointing at the
+console script the package installs.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .. import __version__
+from ..rulesets import Refusal, check, encode_result, load_ruleset
+
+__all__ = ["main"]
+
+# capsulectl's pluginAPI constant (capsule-cli internal/cli/plugin.go).
+PLUGIN_API = "cli-plugin/v1"
+METADATA_ARG = "cli-plugin-metadata"
+NAME = "engine"
+
+
+class _Parser(argparse.ArgumentParser):
+    """A usage error is one line: capsulectl keeps a refusing checker's first
+    stderr line as its reason, and a usage block would start with "usage:"."""
+
+    def error(self, message: str):
+        self.exit(2, f"{self.prog}: {message}\n")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = _Parser(prog=f"capsulectl {NAME}", description="Recompute a ruleset's clauses on a record.")
+    sub = parser.add_subparsers(dest="command", required=True, parser_class=_Parser)
+    c = sub.add_parser(
+        "check",
+        help="check one external-check-input/v0 (stdin) against a ruleset",
+        description="Read one external-check-input/v0 on stdin and print one external-check-result/v0, "
+        "tier recomputed, with a finding for every clause of the ruleset.",
+    )
+    c.add_argument("--ruleset", required=True, metavar="FILE", help="an engine-ruleset/v0 file (JSON)")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if args[:1] == [METADATA_ARG]:
+        handshake = {
+            "name": NAME,
+            "vendor": "capsule-engine (Action State Group)",
+            "version": __version__,
+            "plugin_api": PLUGIN_API,
+            "subcommands": ["check"],
+        }
+        sys.stdout.write(json.dumps(handshake) + "\n")
+        return 0
+    ns = _parser().parse_args(args)
+    try:
+        out = encode_result(check(load_ruleset(ns.ruleset), sys.stdin.buffer.read()))
+    except Refusal as exc:
+        print(f"capsulectl {NAME} check: {exc}", file=sys.stderr)
+        return 1
+    sys.stdout.buffer.write(out)
+    sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{capsule_engine-0.1.0 → capsule_engine-0.2.0}/capsule_engine/folds/record_type_coverage.py

@@ -47,7 +47,9 @@ def evaluate_record_type_coverage(
     seen: set[str] = set()
     for record in records:
         kind = get_path(record, kind_field, None)
-        if kind is not None:
+        # Only a string is a kind: a declared kind is one, and an object or
+        # list at the path (a foreign record) cannot be hashed into the set.
+        if isinstance(kind, str):
             seen.add(kind)
 
     present = frozenset(seen) & registered_kinds

{capsule_engine-0.1.0 → capsule_engine-0.2.0}/capsule_engine/guards/checks/caps.py

@@ -54,6 +54,13 @@ asks rather than allows (``CheckOutcome.asks_when_unevaluated``). A per-action
 limit the action exceeds still fails, and its evidence adds
 ``window_unreadable_count``.
 
+A live check's history ledger writes a copy of an act that seals no
+``spend_minor`` with no ``amount_minor``, and the stated amount beside it
+(``STATED_AMOUNT``). The window reads that copy at the stated amount, never
+below 0 (``_window_record``), so under a fold that reads the copy
+(``spend.weekly/3.0.0`` and ``1.0.0``) an accepted act is never dropped from
+the total (capsule-engine#214 hold A, ruling A).
+
 A live check's history ledger that is not known to hold every act writes an
 ``incomplete`` record (``guards/history_state.py``) under the checked
 record's operator. With one in the ledger the window total may leave out acts
@@ -77,7 +84,7 @@ from ...folds.engine import EvaluationTrace, ReversalSummary, evaluate_one
 from ..action import Action
 from ..capsule import ConstraintOutcome, not_applicable_evidence
 from ..classes import resolve
-from ..history_state import INCOMPLETE, WINDOW_HELD, history_state
+from ..history_state import INCOMPLETE, STATED_AMOUNT, WINDOW_HELD, history_state
 from .base import CheckOutcome
 
 __all__ = [
@@ -253,6 +260,20 @@ def counts_executed_acts(definition: FoldDefinition | None) -> bool:
     return False
 
 
+def _window_record(capsule: dict) -> dict:
+    """``capsule`` as the window reads it. A live history's copy of an act
+    that seals no ``spend_minor`` carries no ``amount_minor`` (its deal bridge
+    takes none), and a fold that reads that copy would skip it, leaving an
+    accepted act out of the total, where an under-count could allow. It is
+    read at the amount the act states (``STATED_AMOUNT``), never below 0
+    (capsule-engine#214 hold A, ruling A: under every fold, including the
+    frozen spend.weekly/3.0.0). Every other record is read as it is."""
+    payload = capsule.get("asg_payload")
+    if not isinstance(payload, dict) or "amount_minor" in payload or STATED_AMOUNT not in payload:
+        return capsule
+    return {**capsule, "asg_payload": {**payload, "amount_minor": max(payload[STATED_AMOUNT], 0)}}
+
+
 def _unreadable_in_window(definition: FoldDefinition, records: list[dict], key_value: str | None, as_of: str) -> int:
     """How many executed acts with a spend that could not be read fall in
     ``definition``'s window under ``key_value``: the same key, window and
@@ -357,7 +378,7 @@ def check_caps(
         )
 
     key_value, query = _fold_key(action, definition.key, since)
-    records = [r.capsule for r in ledger.scan(query)]
+    records = [_window_record(r.capsule) for r in ledger.scan(query)]
     anchor = as_of or action.resolved_timestamp()
     trace = evaluate_one(definition, records, key_value=key_value, as_of=anchor)
     unreadable = _unreadable_in_window(definition, records, key_value, anchor) if counts_executed_acts(definition) else 0

{capsule_engine-0.1.0 → capsule_engine-0.2.0}/capsule_engine/guards/engine.py

@@ -36,8 +36,8 @@ A check that could not be evaluated and asks (``CheckOutcome.asks_when_unevaluat
 is recorded ``n/a`` in scope, and an action that would be allowed is asked
 about instead, or refused when its class names no approver. It is never
 allowed on a total that is not known, and it is not refused for that alone.
-With no constraint failed its ``verdict`` is ``not_evaluable``
-(``GuardDecision.asked_unevaluated_checks``).
+With no constraint failed its ``verdict`` is the escalation when it asks, and
+``not_evaluable`` when it is refused (``GuardDecision.asked_unevaluated_checks``).
 """
 from __future__ import annotations
 
@@ -155,16 +155,18 @@ class GuardDecision:
     def verdict(self) -> str:
         """``outcome``, except that a decision refused only because its
         class-keyed checks were left unevaluated (``taxonomy_mismatch``), its
-        deal could not be read (``deal_id_conflict``) or a check that fails
-        closed could not be evaluated (``not_evaluated_checks``), or a decision
-        asked about because a check could not be evaluated
-        (``asked_unevaluated_checks``), with no
-        constraint failed, is ``not_evaluable``."""
-        unevaluated = (
-            self.taxonomy_mismatch is not None or self.deal_id_conflict is not None or bool(self.not_evaluated_checks)
-            or bool(self.asked_unevaluated_checks)
-        )
-        if unevaluated and not any(c.result == "fail" for c in self.constraints):
+        deal could not be read (``deal_id_conflict``), a check that fails
+        closed could not be evaluated (``not_evaluated_checks``) or a check
+        that asks could not be evaluated (``asked_unevaluated_checks``) and
+        its class names no approver, with no constraint failed, is
+        ``not_evaluable``. A decision asked about only because a check that
+        asks could not be evaluated keeps its outcome, ``escalate``: it asks
+        for approval (#217)."""
+        if any(c.result == "fail" for c in self.constraints):
+            return self.outcome
+        if self.taxonomy_mismatch is not None or self.deal_id_conflict is not None or self.not_evaluated_checks:
+            return NOT_EVALUABLE
+        if self.asked_unevaluated_checks and self.outcome != ESCALATE:
             return NOT_EVALUABLE
         return self.outcome
 

{capsule_engine-0.1.0 → capsule_engine-0.2.0}/capsule_engine/guards/history_state.py

@@ -48,6 +48,7 @@ __all__ = [
     "LIVE_HISTORY",
     "NO_DISPOSITION",
     "RULES_HISTORY_DAYS",
+    "STATED_AMOUNT",
     "STATEMENT",
     "CHECK_FP_ALGS",
     "COUNTERPARTY_KINDS",
@@ -69,6 +70,14 @@ STATEMENT = "statement"
 INCOMPLETE = "incomplete"
 WINDOW_HELD = "window_held"
 THREAD_COUNTERPARTY = "thread_counterparty"
+# The amount a history act states (its body's amount_minor) when it seals no
+# spend_minor: the history copy's own amount_minor is the spend its deal
+# bridge takes, so it has none, and a caps window that reads the copy counts
+# this in its place (caps.py, capsule-engine#214 hold A, ruling A: an
+# accepted act with no spend_minor counts at its stated amount under every
+# fold). Like THREAD_COUNTERPARTY it is this ledger's own state, never in
+# act_payload, so no decision seals it and dedupe never reads it.
+STATED_AMOUNT = "stated_amount_minor"
 # How far back a live check's history reaches: capsulectl sends the acts
 # sealed in the last 31 days (capsule-cli internal/cli RulesHistoryDays,
 # plugins/internal/plugin/rules_checker.go rulesHistory). A replay of a sale

{capsule_engine-0.1.0 → capsule_engine-0.2.0}/capsule_engine/report/live_history.py

@@ -41,6 +41,10 @@ history is missing, is not a list, is not declared complete, or holds an
 entry with no readable time or an ``item_ref`` in another shape, one
 ``incomplete`` record is written after the acts.
 
+An act that seals no ``spend_minor`` has no amount in its record, as its
+deal bridge takes none, so the record also carries the amount the act states
+(``STATED_AMOUNT``), which a caps window counts in its place (#214 hold A).
+
 Under a caps fold that counts executed acts (``spend.weekly/3.1.0``), each act
 is also written as the spend window's record of it (``ExecutedActs``), right
 after it: every history entry is an executed act, counted once. An entry
@@ -74,6 +78,7 @@ from ..guards.history_state import (
     INCOMPLETE,
     LIVE_HISTORY,
     NO_DISPOSITION,
+    STATED_AMOUNT,
     STATEMENT,
     THREAD_COUNTERPARTY,
     UNREAD,
@@ -246,6 +251,9 @@ def _act_record(entry: dict) -> _HistoryRecord:
             payload["item_ref"] = item_ref
     else:
         payload = history_act_payload(action, sealed_disposition=decision is not None)
+        stated = _stated_amount(entry) if "amount_minor" not in payload else None
+        if stated is not None:
+            payload[STATED_AMOUNT] = stated
     capsule_id = entry.get("capsule_id")
     record = _HistoryRecord(
         capsule_id=capsule_id if isinstance(capsule_id, str) and capsule_id else json_digest(entry),
@@ -261,6 +269,16 @@ def _act_record(entry: dict) -> _HistoryRecord:
     return record
 
 
+def _stated_amount(entry: dict) -> int | None:
+    """The ``amount_minor`` a history act's body states, an integer, or
+    ``None``: read where the act seals no ``spend_minor``, so its history
+    copy carries no amount, for a caps window to count in its place
+    (``STATED_AMOUNT``)."""
+    acted, unchecked = _act_member(bound_agent_input(entry))
+    amount = acted.get("amount_minor") if acted is not None and not unchecked else None
+    return amount if isinstance(amount, int) and not isinstance(amount, bool) else None
+
+
 def history_act_payload(action: Action, *, sealed_disposition: bool) -> dict[str, object]:
     """The ``asg_payload`` ``history_ledger`` writes for a history act it
     read: what a decision on ``action`` seals about the act (``act_payload``),

{capsule_engine-0.1.0 → capsule_engine-0.2.0}/capsule_engine/report/replay.py

@@ -61,6 +61,14 @@ profile-wide and capped at 1,000 acts, and past the cap it reads
 incomplete, so the acceptance is unknown. A share refused live for a
 truncated history may therefore pass on replay of a complete bundle.
 
+Live and replay can also differ by design under the frozen spend.weekly/3.0.0
+(everyday 0.3.4/0.3.5): the live guard also counted readable undecided and
+unchecked acts in the caps window, and replay follows the pinned text,
+accepted acts only, so a cap failed live may pass on replay. Anything that
+shows a user both must word that case as the live guard being stricter than
+the pinned rule, never as a mismatch or as replay finding an error
+(capsule-engine#214, Sherlock2's ruling, ops 3febd921).
+
 ``_bridge_transfer_funds`` is the other non-default action mapping, and it
 mirrors the pattern already established by ``tests/test_guard_dry_run.py``
 and ``tests/test_guard_eur150k_bridge.py``: ``transfer_funds`` capsules in
@@ -1326,17 +1334,23 @@ def _taken(shown: dict, *, every_record_is_an_act: bool) -> tuple[dict, bool] |
 def _executed_spend(body: dict, *, unchecked: bool, accepted: bool) -> int | None:
     """The spend the act ``body`` states took, or ``None`` when it cannot be
     read. Money moved in (``MONEY_IN``) is ``0``, decided or not, and a
-    disclosure moves none. An accepted act is counted at its
-    ``amount_minor``, as the fold counts an accepted decision. An act taken
+    disclosure moves none. An accepted act is counted at the larger of its
+    stated ``amount_minor`` and its ``spend_minor``, and at its
+    ``amount_minor``, never below 0, when it seals no ``spend_minor``
+    (capsule-engine#214 hold A, ruling A): a partial charge keeps its stated
+    amount, and a spend above it is never left out. An act taken
     without a check is sealed before its spend is classed, so its
     ``amount_minor`` stands in for a missing ``spend_minor``. Any other act
     is counted at its ``spend_minor``, which must be an integer of at least
     0."""
     if body.get("direction") == MONEY_IN or _DISCLOSED in body:
         return 0
-    if accepted:
-        return _minor(body.get("amount_minor"))
     spend = _minor(body.get("spend_minor"))
+    if accepted:
+        amount = _minor(body.get("amount_minor"))
+        if amount is None:
+            return None
+        return max(amount, 0) if spend is None else max(amount, spend)
     if unchecked:
         return spend if spend is not None else _minor(body.get("amount_minor"))
     return spend if spend is not None and spend >= 0 else None

{capsule_engine-0.1.0 → capsule_engine-0.2.0}/capsule_engine/report/result_from_folds.py

@@ -11,6 +11,12 @@ until a real, non-stub, offline-verified witness stamp lands, then
 that is the module's whole point -- "grade read from the bundle's
 witness/countersign state, never asserted".
 
+The ``finding_from_*`` adapters project the same fold outputs onto an
+external-check-result/v0 finding (``Finding``) instead, for
+``capsulectl engine check`` (``rulesets/``): met -> pass, not_met -> fail,
+not_evaluable -> not_evaluable, and an exclusion -> not_applicable. A
+finding's not_applicable is the exclusion only and never becomes a verdict.
+
 ``tier`` is always ``"recomputed"`` in this module: every fold in
 ``capsule_engine/folds/`` is a deterministic recomputation over sealed
 records (this repo's own report/build.py docstring: "nothing in this module
@@ -23,6 +29,7 @@ has one.
 from __future__ import annotations
 
 from dataclasses import dataclass
+from typing import Literal
 
 from agent_action_capsule import json_digest
 from capsule_emit.chain_segment import ChainSegment
@@ -32,9 +39,11 @@ from ..folds.retention_continuity import RetentionContinuityResult
 from .result import Claim, DigestRef, DisclosureCarrier, ProofRef
 
 __all__ = [
+    "Finding",
     "GuardProjection",
     "claim_from_guard_constraint",
     "claim_from_retention_continuity",
+    "finding_from_record_type_coverage",
     "is_excluded_not_applicable",
     "project_guard_constraint",
 ]
@@ -103,6 +112,47 @@ def is_excluded_not_applicable(result: RecordTypeCoverageResult) -> bool:
     return not result.applicable
 
 
+@dataclass(frozen=True)
+class Finding:
+    """One external-check-result/v0 finding, before ``rulesets.check`` names
+    it (id, check, disposition). ``limit_source`` and ``profile_digest`` are
+    capsule-cli#257's members: printed only once the vendored result schema
+    lists them (``rulesets/check.py``), since an older capsulectl refuses a
+    member its schema does not list."""
+
+    verdict: Literal["pass", "fail", "not_applicable", "not_evaluable"]
+    reason: str | None = None
+    limit: int | str | None = None
+    value: int | str | None = None
+    limit_source: str | None = None
+    profile_digest: str | None = None
+
+
+def finding_from_record_type_coverage(result: RecordTypeCoverageResult, *, complete: bool) -> Finding:
+    """Project one ``evaluate_record_type_coverage`` call into a finding.
+    ``complete`` is whether the records it read are all there were
+    (external-check-input/v0 ``history_scope.complete``). A kind seen is seen
+    whatever else is missing, so an incomplete history still passes when every
+    declared kind is in it; a kind not seen in an incomplete history may be in
+    the part left out, so that is not_evaluable, never a fail. ``limit`` is
+    the number of kinds declared and ``value`` the number seen."""
+    if is_excluded_not_applicable(result):
+        return Finding(verdict="not_applicable", reason="no record kinds are declared")
+    declared = len(result.present) + len(result.missing)
+    counts = {"limit": declared, "value": len(result.present)}
+    if result.verdict == "met":
+        return Finding(verdict="pass", **counts)
+    missing = ", ".join(sorted(result.missing))
+    if not complete:
+        return Finding(verdict="not_evaluable", reason=_clip(f"the history is incomplete and does not show: {missing}"), **counts)
+    return Finding(verdict="fail", reason=_clip(f"not in the history: {missing}"), **counts)
+
+
+def _clip(reason: str) -> str:
+    # external-check-result/v0 caps a reason at 1000 characters.
+    return reason if len(reason) <= 1000 else reason[:997] + "..."
+
+
 # A guard constraint record's result (pass | fail | n/a) projected onto the
 # registered (EvidenceStatus, Sufficiency, Verdict) triple, beside the fold
 # map above. pass/fail are settled; an n/a is read through the facts object

capsule_engine-0.2.0/capsule_engine/rulesets/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Rulesets for ``capsulectl engine check --ruleset FILE`` (capsule-engine#162).
+
+An ``engine-ruleset/v0`` file names the clauses the engine recomputes on one
+external-check-input/v0; ``check`` answers with one external-check-result/v0,
+tier ``recomputed``. The format is ``schemas/engine-ruleset-v0.json``; its
+``definition_digest`` is SHA-256 over the JCS bytes of the parsed document.
+"""
+from __future__ import annotations
+
+from .check import RULESET_FORMAT, Refusal, Ruleset, check, encode_result, load_ruleset
+
+__all__ = ["RULESET_FORMAT", "Refusal", "Ruleset", "check", "encode_result", "load_ruleset"]