capsule-engine 0.1.0__py3-none-any.whl

capsule_engine/guards/wickets/catalog_defs/release_on_acceptance.seller.v1.1.yaml

@@ -0,0 +1,44 @@
+# seller.release_on_acceptance/1.1.0: 1.0.0 (release_on_acceptance.seller.yaml)
+# not applicable to a disclosure to a platform, the marketplace or relay a
+# sale is listed on: it reaches no buyer, so there is no acceptance to cite,
+# and seller.recipient_role/1.1.0 lets it carry the user's email only. 1.0.0
+# stays as it was for the records and packs that pin it.
+#
+# release_on_acceptance, configured for a seller (guards/checks/
+# release_on_acceptance.py). Personal data reaches a buyer only once that
+# buyer's acceptance of the sale is sealed. The rule itself is the
+# `semantics` field below: it is inside the digested body, so rewording it
+# moves the digest. A failure refuses; it never asks, and an approval does
+# not clear it.
+#
+# `release_classes` is the closed set of statement classes, the same list
+# promise_never/1.0.0 and promise_requires_approval/1.0.0 close over, so
+# every class a disclosure may declare is held back until acceptance and
+# any other class is refused. No class is released before acceptance. `acceptance_classes` are the classes whose accepted,
+# non-dry-run record seals the acceptance (the same reading as
+# seller.single_commitment). `action_classes` are the disclosures the rule
+# applies to.
+wicket_id: seller.release_on_acceptance/1.1.0
+check: release_on_acceptance
+semantics: >-
+  A disclosure in action_classes passes only when its representation_class
+  is in release_classes and it names its task_authority_ref, item_ref and
+  target, cites by cited_mandate_capsule_id the sale's acceptance, and that
+  acceptance re-verifies and was sealed for the same target. The sale's
+  acceptance is the first record in ledger order, among the operator's,
+  whose action_class is in acceptance_classes, whose decision was accept,
+  which was not a dry run, and which carries the same task_authority_ref and
+  item_ref. Every other such disclosure fails: no citation, another sale's
+  or another recipient's acceptance, a record that is not the sale's
+  acceptance, a missing reference, or a representation_class missing or
+  outside release_classes. An action whose action_class is missing or has no
+  row in the action taxonomy fails too, since it cannot be shown to be out
+  of scope. Any other known action class is not applicable, and so is a
+  disclosure whose recipient_role is in except_recipient_roles: it reaches
+  no buyer. A failure is refused and no approval clears it. The reason and
+  evidence carry no disclosed value, reference, counterparty or capsule id.
+config:
+  release_classes: [price, condition, features, authenticity, availability, delivery_date, service_scope, warranty, refund_terms, payment_methods, pickup, deadline, address, other]
+  acceptance_classes: [agreement.accept]
+  action_classes: [disclosure.personal]
+  except_recipient_roles: [platform]

capsule_engine/guards/wickets/catalog_defs/release_on_acceptance.seller.v1.2.yaml

@@ -0,0 +1,63 @@
+# seller.release_on_acceptance/1.2.0: seller.release_on_acceptance/1.1.0
+# (release_on_acceptance.seller.v1.1.yaml) reading what a share gives and
+# binding the acceptance from the history (capsule-engine#179, #186).
+#
+# 1.1.0 keyed on representation_class, a statement class no share carries,
+# and needed a cited, re-verified acceptance no producer sends, so no share
+# to a buyer ever passed. 1.2.0 reads the share's classes of data
+# (disclosed_classes). release_classes are the contact classes of
+# DISCLOSED_CLASSES (guards/action.py); a credential, a verification code, a
+# payment card and an id document are left out, so they still refuse. The
+# listing's public pickup area (pre_acceptance_classes) goes to any buyer
+# before acceptance. Anything else needs the sale's acceptance, the same
+# record as before (the first accepted, non-dry-run agreement.accept of the
+# item), in the share's own deal and by the same buyer: the counterparty
+# fingerprint each check seals, compared on the per-person identity kinds,
+# or on the name and the domain together when neither side seals one (an
+# opening that named the buyer by name and domain only). binding selects this reading in the check (guards/checks/
+# release_on_acceptance.py); 1.0.0 and 1.1.0 have none and decide as they
+# always did. The rule itself is the `semantics` field below: it is inside
+# the digested body, so rewording it moves the digest. A failure refuses; it
+# never asks, and an approval does not clear it.
+wicket_id: seller.release_on_acceptance/1.2.0
+check: release_on_acceptance
+semantics: >-
+  A disclosure in action_classes passes only when it names at least one
+  class of data (disclosed_classes), every class it names is in
+  release_classes, and either every class it names is in
+  pre_acceptance_classes, or the sale has a known acceptance in the same
+  deal by the same buyer. The sale's acceptance is the first record in
+  ledger order, among the operator's, whose action_class is in
+  acceptance_classes, whose decision was accept, which was not a dry run,
+  and which carries the disclosure's item_ref; a history that may be missing
+  acts, an act of the sale that could not be read, an earlier act of an
+  acceptance class with no disposition, or an earlier accepted commitment in
+  the history that names no item leave it unknown, which is none. The
+  same deal is an equal deal_id, both set. The same buyer is the
+  counterparty the acceptance's check sealed, carried beside it in the
+  history, and the one the disclosure's check sealed, under the same
+  fingerprint algorithm, with at least one per-person identity (email,
+  phone, profile_id, relay_address) on both sides and every one on both
+  sides equal; or, when neither side has any per-person identity, with a
+  name and a domain on both sides and both equal. A payee is never
+  compared, and a name or a domain is compared only when neither side has a
+  per-person identity. A counterparty block on either side with any member
+  of another kind or shape, or another algorithm, is no buyer. Every other
+  such disclosure fails: no class or a class outside release_classes, no
+  item_ref, deal_id or counterparty fingerprint, no known acceptance, or one
+  in another deal or by another buyer. An action whose action_class is
+  missing or has no row in the action taxonomy fails too, since it cannot
+  be shown to be out of scope. Any other known action class is not
+  applicable, and so is a disclosure whose recipient_role is in
+  except_recipient_roles: it reaches no buyer. A failure is refused and no
+  approval clears it. The reason and evidence carry no disclosed value,
+  reference, deal, counterparty or capsule id: only the class names read,
+  whether the disclosure was bound to an acceptance, and a missing field's
+  name.
+config:
+  binding: same_deal_same_buyer
+  release_classes: [name, phone, email, home_address, address, pickup_location, other_contact, pickup_area]
+  pre_acceptance_classes: [pickup_area]
+  acceptance_classes: [agreement.accept]
+  action_classes: [disclosure.personal]
+  except_recipient_roles: [platform]

capsule_engine/guards/wickets/catalog_defs/release_on_acceptance.seller.yaml

@@ -0,0 +1,36 @@
+# release_on_acceptance wicket, configured for a seller (guards/checks/
+# release_on_acceptance.py). Personal data reaches a buyer only once that
+# buyer's acceptance of the sale is sealed. The rule itself is the
+# `semantics` field below: it is inside the digested body, so rewording it
+# moves the digest. A failure refuses; it never asks, and an approval does
+# not clear it.
+#
+# `release_classes` is the closed set of statement classes, the same list
+# promise_never/1.0.0 and promise_requires_approval/1.0.0 close over, so
+# every class a disclosure may declare is held back until acceptance and
+# any other class is refused. No class is released before acceptance. `acceptance_classes` are the classes whose accepted,
+# non-dry-run record seals the acceptance (the same reading as
+# seller.single_commitment). `action_classes` are the disclosures the rule
+# applies to.
+wicket_id: seller.release_on_acceptance/1.0.0
+check: release_on_acceptance
+semantics: >-
+  A disclosure in action_classes passes only when its representation_class
+  is in release_classes and it names its task_authority_ref, item_ref and
+  target, cites by cited_mandate_capsule_id the sale's acceptance, and that
+  acceptance re-verifies and was sealed for the same target. The sale's
+  acceptance is the first record in ledger order, among the operator's,
+  whose action_class is in acceptance_classes, whose decision was accept,
+  which was not a dry run, and which carries the same task_authority_ref and
+  item_ref. Every other such disclosure fails: no citation, another sale's
+  or another recipient's acceptance, a record that is not the sale's
+  acceptance, a missing reference, or a representation_class missing or
+  outside release_classes. An action whose action_class is missing or has no
+  row in the action taxonomy fails too, since it cannot be shown to be out
+  of scope. Any other known action class is not applicable. A failure is
+  refused and no approval clears it. The reason and evidence carry no
+  disclosed value, reference, counterparty or capsule id.
+config:
+  release_classes: [price, condition, features, authenticity, availability, delivery_date, service_scope, warranty, refund_terms, payment_methods, pickup, deadline, address, other]
+  acceptance_classes: [agreement.accept]
+  action_classes: [disclosure.personal]

capsule_engine/guards/wickets/catalog_defs/required_disclosure.v1.1.yaml

@@ -0,0 +1,36 @@
+# required_disclosure wicket, version 1.1: version 1.0 with one change. A
+# required class also counts as stated when the action's deal already holds
+# a statement of it: a claim the user's agent made to the counterparty in
+# that deal before the action (a capsulectl claim record sealing
+# source_kind agent and the class), counted by
+# disclosure.statement_seen/1.0.0. Under version 1.0 such a claim stated no
+# act, so no decision carried its class and every offer and commit after it
+# failed as if nothing had been said. Version 1.0
+# (required_disclosure.yaml) stays as it was for the packs that pin it.
+#
+# Both `fold_digest` and `statement_fold_digest` are the real
+# definition_digest() of their folds in folds/catalog_defs; the check refuses
+# to run when a catalog fold does not match.
+#
+# Declared disposition: ask.
+wicket_id: required_disclosure/1.1.0
+check: required_disclosure
+semantics: >-
+  For an action in action_classes, each class in required_classes must
+  already have been stated to the counterparty: by an accepted prior action
+  of the operator addressed to the action's target that carried that
+  representation_class, leaving dry runs out, or by a claim the operator's
+  agent made in the action's deal before the action with source_kind agent
+  and that class (a sealed delivery_promise reads as delivery_date). A class
+  with neither fails, and an approval never clears it. A class is never read
+  from a disclosure record's personal-data fields. An action naming neither
+  a target nor a deal is not applicable. Any other action class is out of
+  scope.
+config:
+  action_classes: [marketplace.offer, marketplace.sale, agreement.accept]
+  representation_classes: [price, condition, features, authenticity, availability, delivery_date, service_scope, warranty, refund_terms, payment_methods, pickup, deadline, address, other]
+  required_classes: [condition]
+  fold_id: disclosure.class_seen/1.0.0
+  fold_digest: 5b4d0280892db43c5209629137be8634be01c32d481ae79e005c4a1c6358c564
+  statement_fold_id: disclosure.statement_seen/1.0.0
+  statement_fold_digest: 925e7ccd2e29b3f1984f966e968bdef47d0d22d2b85b8e0205a39d6a5a7ff0be

capsule_engine/guards/wickets/catalog_defs/required_disclosure.v1.2.yaml

@@ -0,0 +1,42 @@
+# required_disclosure wicket, version 1.2: version 1.1 with one change. A
+# required class also counts as stated when the sale's listings in force
+# state it: the action's listing_classes, the rule input capsulectl seals on
+# each offer and commit check of a sale's thread (the classes every live
+# listing states, the intersection over the latest post per platform when
+# the check was made; capsule-engine#190). A listing is the agent's words to
+# every buyer, so a class it states is stated to this one too. Under version
+# 1.1 a listing counted for nothing, and an offer after a listing that stated
+# the condition asked for it again. The value is read from the check, never
+# recomputed: a later re-post changes later checks only. With no value (no
+# post) or an empty one, the class needs one of 1.1's two paths. Version 1.1
+# (required_disclosure.v1.1.yaml) stays as it was for the packs that pin it.
+#
+# Both `fold_digest` and `statement_fold_digest` are the real
+# definition_digest() of their folds in folds/catalog_defs; the check refuses
+# to run when a catalog fold does not match.
+#
+# Declared disposition: ask.
+wicket_id: required_disclosure/1.2.0
+check: required_disclosure
+semantics: >-
+  For an action in action_classes, each class in required_classes must
+  already have been stated to the counterparty: by an accepted prior action
+  of the operator addressed to the action's target that carried that
+  representation_class, leaving dry runs out; by a claim the operator's
+  agent made in the action's deal before the action with source_kind agent
+  and that class (a sealed delivery_promise reads as delivery_date); or by
+  the sale's listings in force, when the class is in the action's
+  listing_classes as its check sealed them. A class with none of the three
+  fails, and an approval never clears it. A class is never read from a
+  disclosure record's personal-data fields. An action naming neither a
+  target nor a deal is not applicable. Any other action class is out of
+  scope.
+config:
+  action_classes: [marketplace.offer, marketplace.sale, agreement.accept]
+  representation_classes: [price, condition, features, authenticity, availability, delivery_date, service_scope, warranty, refund_terms, payment_methods, pickup, deadline, address, other]
+  required_classes: [condition]
+  fold_id: disclosure.class_seen/1.0.0
+  fold_digest: 5b4d0280892db43c5209629137be8634be01c32d481ae79e005c4a1c6358c564
+  statement_fold_id: disclosure.statement_seen/1.0.0
+  statement_fold_digest: 925e7ccd2e29b3f1984f966e968bdef47d0d22d2b85b8e0205a39d6a5a7ff0be
+  count_listing_classes: true

capsule_engine/guards/wickets/catalog_defs/required_disclosure.yaml

@@ -0,0 +1,25 @@
+# required_disclosure wicket: classes of statement that must have been made
+# to the counterparty before the action (guards/checks/
+# required_disclosure.py). For each class in `required_classes`, the
+# disclosure.class_seen/1.0.0 fold counts this operator's accepted prior
+# actions addressed to Action.target that carried that
+# representation_class; a zero fails the check. It checks that a statement
+# of the class was recorded, never what it said or whether it was true.
+# A failure means: make the disclosure first, or change the task
+# authority. An approval never waives it.
+#
+# `representation_classes` is the closed set a class must come from;
+# `required_classes` outside it is refused when the check runs.
+# `fold_digest` is the real definition_digest() of
+# folds/catalog_defs/disclosure.class_seen.yaml; the check refuses to run
+# when the catalog fold does not match it.
+#
+# Declared disposition: ask.
+wicket_id: required_disclosure/1.0.0
+check: required_disclosure
+config:
+  action_classes: [marketplace.offer, marketplace.sale, agreement.accept]
+  representation_classes: [price, condition, features, authenticity, availability, delivery_date, service_scope, warranty, refund_terms, payment_methods, pickup, deadline, address, other]
+  required_classes: [condition]
+  fold_id: disclosure.class_seen/1.0.0
+  fold_digest: 5b4d0280892db43c5209629137be8634be01c32d481ae79e005c4a1c6358c564

capsule_engine/guards/wickets/catalog_defs/single_commitment.seller.yaml

@@ -0,0 +1,14 @@
+# single_commitment wicket, configured for a seller (guards/checks/
+# single_commitment.py). One sale, several buyer threads: once an acceptance
+# is sealed for a task_authority_ref and an item_ref, a commitment for the
+# same pair fails unless it cites that acceptance and is addressed to the
+# counterparty that accepted. A failure refuses; it never asks.
+#
+# `acceptance_classes` are the classes whose accepted, non-dry-run record
+# seals the acceptance. `commit_classes` are the commitments the rule
+# applies to; anything else (a message, a disclosure) is n/a.
+wicket_id: seller.single_commitment/1.0.0
+check: single_commitment
+config:
+  acceptance_classes: [agreement.accept]
+  commit_classes: [agreement.accept, marketplace.offer, marketplace.sale, external_commitment.other]

capsule_engine/guards/wickets/catalog_defs/task_authority.v1.1.yaml

@@ -0,0 +1,20 @@
+# task_authority wicket, version 1.1: task_authority/1.0.0's config with
+# marketplace.sale added to action_classes (guards/checks/task_authority.py).
+# The rule itself is the `semantics` field below: it is inside the digested
+# body, so rewording it moves the digest. task_authority/1.0.0
+# (task_authority.yaml) stays as it was for the packs that pin it.
+wicket_id: task_authority/1.1.0
+check: task_authority
+semantics: >-
+  For an action in action_classes, Action.task_authority_ref is the SHA-256
+  over the JCS bytes of the whole task-authority record the action cites. The
+  record supplied with the decision is read only when its digest equals that
+  reference, and the plan at its body, in guards/plan.py's shape, decides by
+  plan containment: an action inside the plan passes, one outside it fails.
+  It is not applicable, naming task_authority_ref, when the action carries
+  none, and naming task_authority_record when no record is supplied, the
+  supplied record is not the one the reference names or has no digest, or
+  the record carries no plan that parses. marketplace.sale is in scope. Any
+  other action class is out of scope.
+config:
+  action_classes: [money.purchase, money.transfer, money.subscription, booking.create, booking.modify, agreement.accept, marketplace.offer, external_commitment.other, marketplace.sale]

capsule_engine/guards/wickets/catalog_defs/task_authority.yaml

@@ -0,0 +1,8 @@
+# task_authority wicket: the action is inside the task authority it cites
+# (guards/checks/task_authority.py). The whole cited record is read only
+# when the engine's own digest of it equals the action's task_authority_ref;
+# the plan inside it is in guards/plan.py's shape, and plan_containment decides.
+wicket_id: task_authority/1.0.0
+check: task_authority
+config:
+  action_classes: [money.purchase, money.transfer, money.subscription, booking.create, booking.modify, agreement.accept, marketplace.offer, external_commitment.other]

capsule_engine/guards/wickets/catalog_defs/upfront_amount.v1.1.yaml

@@ -0,0 +1,19 @@
+# upfront_amount wicket, version 1.1: upfront_amount/1.0.0's config with
+# marketplace.sale added to action_classes (guards/checks/upfront_amount.py).
+# The rule itself is the `semantics` field below: it is inside the digested
+# body, so rewording it moves the digest. upfront_amount/1.0.0
+# (upfront_amount.yaml) stays as it was for the packs that pin it.
+wicket_id: upfront_amount/1.1.0
+check: upfront_amount
+semantics: >-
+  For an action in action_classes, Action.upfront_amount_minor (the part of
+  the total stated as due before delivery) fails when it is above
+  upfront_max_minor, or when upfront_amount_minor * 10000 is above
+  Action.amount_minor * upfront_max_bps; otherwise it passes. Without an
+  amount_minor only upfront_max_minor is compared. It is not applicable,
+  naming the field, when the action carries no upfront_amount_minor.
+  marketplace.sale is in scope. Any other action class is out of scope.
+config:
+  action_classes: [money.purchase, money.transfer, money.subscription, booking.create, booking.modify, agreement.accept, marketplace.offer, external_commitment.other, marketplace.sale]
+  upfront_max_minor: 10000
+  upfront_max_bps: 2500

capsule_engine/guards/wickets/catalog_defs/upfront_amount.yaml

@@ -0,0 +1,11 @@
+# upfront_amount wicket: the deposit a payment states, read as
+# Action.upfront_amount_minor
+# (guards/checks/upfront_amount.py). Fails above `upfront_max_minor`, or
+# above `upfront_max_bps` basis points of the total. Default limits:
+# 100.00 and 25%, in the action's own minor units.
+wicket_id: upfront_amount/1.0.0
+check: upfront_amount
+config:
+  action_classes: [money.purchase, money.transfer, money.subscription, booking.create, booking.modify, agreement.accept, marketplace.offer, external_commitment.other]
+  upfront_max_minor: 10000
+  upfront_max_bps: 2500

capsule_engine/guards/wickets/catalog_defs/verify_before_dispatch.yaml

@@ -0,0 +1,9 @@
+# verify_before_dispatch wicket: the cited mandate capsule must exist in the
+# ledger and independently re-verify (guards/checks/verify_before_dispatch.py).
+# This check takes no per-deployment tuning parameters -- `config` is empty
+# on purpose, not omitted, so the digest still pins "this check, unconfigured"
+# distinctly from "this wicket_id was never declared at all".
+wicket_id: verify_before_dispatch/1.0.0
+check: verify_before_dispatch
+config:
+  method: agent_action_capsule.verify

capsule_engine/guards/wickets/definition.py

@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Wicket definitions: parsing, validation, and the definition_digest.
+
+A "wicket" is this workspace's name for a guard
+constraint -- caps / dedupe / verify_before_dispatch (``guards/checks/*.py``).
+Unlike a fold, a wicket's CHECK LOGIC is Python code, not declarative data --
+there is no YAML that fully describes "how caps computes weekly spend". What
+*is* declarative, and varies per deployment, is the wicket's own
+*configuration*: which check it invokes and the parameters that check runs
+with (caps' per-class minor-unit limits, dedupe's window). A ``WicketDefinition``
+captures exactly that slice -- ``wicket_id``, ``check``, ``config`` -- the same
+way ``folds/definition.py``'s ``FoldDefinition`` captures a fold. Its digest
+(SHA-256 over the JCS-canonical bytes, via the same
+``agent_action_capsule.canonical.json_digest`` the fold definitions and the
+capsule format itself use) identifies "this configuration of this check", not
+the Python source file the check lives in -- a source-code change with no
+config change is invisible to this digest, and that is intentional: this is a
+policy-configuration digest, not a code-integrity digest.
+
+Because the digest cannot see the check's code, a definition may also carry
+``semantics``: a short normative statement of what passes, what fails and
+what is not applicable. It is data inside the digested body, never a YAML
+comment, so rewording the rule moves the digest. A definition without it
+digests exactly as before (the key is left out of the canonical form). A
+definition whose meaning moved under an unchanged digest is retired
+(``retired.py``) and refused here at parse time.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from agent_action_capsule.canonical import FloatInDigestError, UnsafeIntegerError, json_digest
+
+from .errors import (
+    FLOAT_IN_DEFINITION,
+    INVALID_WICKET_ID,
+    MALFORMED_DEFINITION,
+    RETIRED_DEFINITION,
+    UNKNOWN_CHECK,
+    UNSAFE_INTEGER_IN_DEFINITION,
+    WicketDefinitionError,
+)
+from .retired import RETIRED_IDS, retired_entry
+
+__all__ = ["WICKET_ID_RE", "KNOWN_CHECKS", "WicketDefinition", "parse_definition"]
+
+# wicket_id: same "human name + semver" shape as fold_id (folds/definition.py).
+WICKET_ID_RE = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*/\d+\.\d+\.\d+$")
+
+# The closed, registered set of checks a wicket may configure -- the three
+# reference checks ``guards/engine.py`` evaluates and ``cli/constraints_cmd.
+# py``'s ``CHECKS`` catalog lists, plus ``hold_reconcile`` (``holds/engine.
+# py``'s tolerance check for planned-vs-executed reconciliation, capsule-emit
+# #53), plus ``plan_containment`` (``guards/checks/plan_containment.py`` --
+# forward-compiled-plan containment), plus the configured checks a
+# pack can add to a decision (``destination_rail``,
+# ``counterparty_identity_change``, ``counterparty_seen_before``,
+# ``credential_pattern``, ``recurring_charge``, ``action_class_gate``,
+# ``counterparty_list``, ``recipient_role``, ``refundability``,
+# ``material_fields_changed``, ``offer_fields_changed``,
+# ``recipient_seen_before``, ``channel_change``, ``upfront_amount``,
+# ``task_authority``, and the seller-side ``price_floor``,
+# ``required_disclosure``, ``promise_requires_approval``, ``promise_never``,
+# ``offer_expiry``, ``single_commitment``, ``release_on_acceptance`` --
+# ``guards/checks/__init__.py``'s ``RUNNABLE_CHECKS``). Closed for
+# the same reason ``folds/definition.py``'s ``KNOWN_REDUCERS`` is: an
+# unregistered name is a typo or a not-yet-built check, never silently
+# accepted as data.
+KNOWN_CHECKS = frozenset(
+    {
+        "dedupe",
+        "caps",
+        "verify_before_dispatch",
+        "hold_reconcile",
+        "plan_containment",
+        "destination_rail",
+        "counterparty_identity_change",
+        "counterparty_seen_before",
+        "credential_pattern",
+        "recurring_charge",
+        "action_class_gate",
+        "counterparty_list",
+        "recipient_role",
+        "refundability",
+        "material_fields_changed",
+        "offer_fields_changed",
+        "recipient_seen_before",
+        "channel_change",
+        "upfront_amount",
+        "task_authority",
+        "price_floor",
+        "required_disclosure",
+        "promise_requires_approval",
+        "promise_never",
+        "offer_expiry",
+        "single_commitment",
+        "release_on_acceptance",
+    }
+)
+
+
+@dataclass(frozen=True)
+class WicketDefinition:
+    wicket_id: str
+    check: str
+    config: dict[str, Any] = field(default_factory=dict)
+    semantics: str | None = None
+
+    def canonical_dict(self) -> dict:
+        """The JCS-canonicalizable form of this definition -- drives definition_digest."""
+        # Left out when not stated, so a definition without it keeps its digest.
+        semantics = {} if self.semantics is None else {"semantics": self.semantics}
+        return {"wicket_id": self.wicket_id, "check": self.check, "config": self.config, **semantics}
+
+    def definition_digest(self) -> str:
+        """SHA-256 over the JCS bytes of the canonical definition."""
+        try:
+            return json_digest(self.canonical_dict())
+        except FloatInDigestError as exc:
+            raise WicketDefinitionError(FLOAT_IN_DEFINITION, str(exc)) from exc
+        except UnsafeIntegerError as exc:
+            raise WicketDefinitionError(UNSAFE_INTEGER_IN_DEFINITION, str(exc)) from exc
+
+
+def parse_definition(data: Any) -> WicketDefinition:
+    """Validate a plain dict (as loaded from YAML) into a ``WicketDefinition``."""
+    if not isinstance(data, dict):
+        raise WicketDefinitionError(MALFORMED_DEFINITION, "definition must be a mapping")
+
+    wicket_id = data.get("wicket_id")
+    if not isinstance(wicket_id, str) or not WICKET_ID_RE.match(wicket_id):
+        raise WicketDefinitionError(
+            INVALID_WICKET_ID,
+            f"wicket_id {wicket_id!r} must match '<namespace>[.<namespace>...]/<major>.<minor>.<patch>' "
+            "(e.g. 'caps/1.0.0')",
+        )
+
+    check = data.get("check")
+    if check not in KNOWN_CHECKS:
+        raise WicketDefinitionError(
+            UNKNOWN_CHECK, f"check {check!r} is not in the closed registered set {sorted(KNOWN_CHECKS)}"
+        )
+
+    config = data.get("config") if "config" in data else {}
+    if not isinstance(config, dict):
+        raise WicketDefinitionError(MALFORMED_DEFINITION, "config must be a mapping")
+
+    semantics = data.get("semantics")
+    if semantics is not None and (not isinstance(semantics, str) or not semantics.strip()):
+        raise WicketDefinitionError(MALFORMED_DEFINITION, "semantics must be a non-empty string")
+
+    definition = WicketDefinition(wicket_id=wicket_id, check=check, config=config, semantics=semantics)
+    # Only a retired id pays for a digest here, so a float or unsafe integer
+    # in any other definition still surfaces at definition_digest(), as before.
+    if wicket_id in RETIRED_IDS:
+        retired = retired_entry(wicket_id, definition.definition_digest())
+        if retired is not None:
+            raise WicketDefinitionError(
+                RETIRED_DEFINITION,
+                f"{wicket_id} at digest {retired.digest} is retired: {retired.reason}; use {retired.replaced_by}",
+            )
+    return definition

capsule_engine/guards/wickets/errors.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Named-reason errors for wicket definitions (mirrors ``folds/errors.py``)."""
+from __future__ import annotations
+
+INVALID_WICKET_ID = "invalid_wicket_id_namespace"
+UNKNOWN_CHECK = "unknown_check"
+MALFORMED_DEFINITION = "malformed_definition"
+FLOAT_IN_DEFINITION = "float_in_definition"
+UNSAFE_INTEGER_IN_DEFINITION = "unsafe_integer_in_definition"
+RETIRED_DEFINITION = "retired_definition"
+
+
+class WicketDefinitionError(ValueError):
+    """A wicket definition fails to parse or validate. Carries a stable reason code."""
+
+    def __init__(self, reason: str, message: str) -> None:
+        self.reason = reason
+        super().__init__(f"{reason}: {message}")

capsule_engine/guards/wickets/loader.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+"""YAML front door for wicket definitions: YAML text/file -> validated WicketDefinition."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from .definition import WicketDefinition, parse_definition
+from .errors import MALFORMED_DEFINITION, WicketDefinitionError
+
+__all__ = ["load_definition_text", "load_definition_file"]
+
+
+def load_definition_text(text: str) -> WicketDefinition:
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise WicketDefinitionError(MALFORMED_DEFINITION, f"invalid YAML: {exc}") from exc
+    if data is None:
+        raise WicketDefinitionError(MALFORMED_DEFINITION, "empty definition document")
+    return parse_definition(data)
+
+
+def load_definition_file(path: str | Path) -> WicketDefinition:
+    return load_definition_text(Path(path).read_text())

capsule_engine/guards/wickets/retired.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Retired wicket definitions: an (id, digest) pair that must not load.
+
+A definition is retired when its meaning moved without its digest moving, so
+the pin no longer tells a reader which verdicts it produces. The bytes stay
+recomputable (the digest is listed here verbatim); what changes is that the
+loader, the catalog and a pack citing the pair all refuse it, naming the
+replacement. A retirement is permanent: a row is never removed.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["RetiredDefinition", "RETIRED", "RETIRED_IDS", "retired_entry"]
+
+
+@dataclass(frozen=True)
+class RetiredDefinition:
+    wicket_id: str
+    digest: str
+    reason: str
+    replaced_by: str
+
+
+RETIRED: tuple[RetiredDefinition, ...] = (
+    RetiredDefinition(
+        wicket_id="offer_expiry/1.0.0",
+        digest="7b1072fc6997b07e7f08941a723e60d53fd3a54dbccfda6fa7391124ec2702ee",
+        reason=(
+            "its check changed meaning under this digest (an expired or unverifiable proposal went from "
+            "not applicable to fail) because the digest covered config only"
+        ),
+        replaced_by="offer_expiry/1.0.1",
+    ),
+    RetiredDefinition(
+        wicket_id="price_floor/1.0.0",
+        digest="a7eb755a71cf9dabaf04fbd740fc9ceaad5f0ba883795adad6fd9038796dffa9",
+        reason=(
+            "its check changed meaning under this digest (the floor moved from min_total_minor in clear on "
+            "the task-authority record to a private commercial-bounds document the record commits to) "
+            "because the digest covered config only"
+        ),
+        replaced_by="price_floor/2.0.1",
+    ),
+    RetiredDefinition(
+        wicket_id="price_floor/2.0.0",
+        digest="52fd588ea62ce467ad5ee59cef4347a4a0fbb0836d20ebfe783923805230bc9b",
+        reason=(
+            "its check changed meaning under this digest (a task-authority record that seals no "
+            "bounds_commitment went from in scope and not evaluable to out of scope)"
+        ),
+        replaced_by="price_floor/2.0.1",
+    ),
+)
+
+_BY_PAIR = {(r.wicket_id, r.digest): r for r in RETIRED}
+RETIRED_IDS = frozenset(r.wicket_id for r in RETIRED)
+
+
+def retired_entry(wicket_id: str, digest: str) -> RetiredDefinition | None:
+    """The retirement row for this exact (id, digest) pair, if there is one."""
+    return _BY_PAIR.get((wicket_id, digest))

capsule_engine/holds/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Reservation-as-capsule semantics: ``hold.reserve``/``release``/``expire``/
+``reconcile`` record types, atomic evaluate-and-reserve, expiry-terminal +
+resume, and planned-vs-executed reconciliation (capsule-emit #51/#52/#53).
+
+Ledger-side only: the distributed sequencer across processes/nodes is
+capsule-emit's Dapr-side integration, not this package's.
+"""
+from .capsules import (
+    build_hold_expire_capsule,
+    build_hold_reconcile_capsule,
+    build_hold_release_capsule,
+    build_hold_reserve_capsule,
+    check_integer_amount,
+)
+from .engine import HoldDecision, HoldEngine, HoldStatus
+from .errors import HoldError
+from .policy import HoldPolicy, resolve_hold_policy
+from .scope import ScopeKey, ScopeLocks
+
+__all__ = [
+    "build_hold_reserve_capsule",
+    "build_hold_release_capsule",
+    "build_hold_expire_capsule",
+    "build_hold_reconcile_capsule",
+    "check_integer_amount",
+    "HoldDecision",
+    "HoldEngine",
+    "HoldStatus",
+    "HoldError",
+    "HoldPolicy",
+    "resolve_hold_policy",
+    "ScopeKey",
+    "ScopeLocks",
+]