aetos-verify 0.3.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (148) hide show
  1. aetos/__init__.py +43 -0
  2. aetos/application/__init__.py +9 -0
  3. aetos/application/agent/__init__.py +1 -0
  4. aetos/application/agent/action_gate.py +174 -0
  5. aetos/application/agent/action_policy.py +213 -0
  6. aetos/application/agent/agent_service.py +558 -0
  7. aetos/application/agent/orchestrator.py +395 -0
  8. aetos/application/assemblers/__init__.py +0 -0
  9. aetos/application/assemblers/audit.py +26 -0
  10. aetos/application/assemblers/decision_report.py +62 -0
  11. aetos/application/assemblers/human_report.py +95 -0
  12. aetos/application/assemblers/policy_verdict.py +112 -0
  13. aetos/application/audit.py +153 -0
  14. aetos/application/boundary/__init__.py +25 -0
  15. aetos/application/boundary/gate.py +202 -0
  16. aetos/application/boundary/scorer.py +294 -0
  17. aetos/application/boundary/tone.py +82 -0
  18. aetos/application/dto/__init__.py +0 -0
  19. aetos/application/dto/audit.py +28 -0
  20. aetos/application/dto/decision_report.py +50 -0
  21. aetos/application/dto/human_report.py +41 -0
  22. aetos/application/dto/policy_verdict.py +56 -0
  23. aetos/application/dto/verdict_snapshot.py +140 -0
  24. aetos/application/extraction/__init__.py +56 -0
  25. aetos/application/extraction/candidate.py +54 -0
  26. aetos/application/extraction/confidence.py +54 -0
  27. aetos/application/extraction/detectors/__init__.py +76 -0
  28. aetos/application/extraction/detectors/blast_radius.py +92 -0
  29. aetos/application/extraction/detectors/common.py +124 -0
  30. aetos/application/extraction/detectors/criticality.py +110 -0
  31. aetos/application/extraction/detectors/evidence_count.py +277 -0
  32. aetos/application/extraction/detectors/exit_criteria.py +91 -0
  33. aetos/application/extraction/detectors/owner.py +139 -0
  34. aetos/application/extraction/detectors/precedent.py +49 -0
  35. aetos/application/extraction/detectors/reversibility.py +303 -0
  36. aetos/application/extraction/detectors/rollback.py +88 -0
  37. aetos/application/extraction/detectors/time_pressure.py +202 -0
  38. aetos/application/extraction/evidence.py +548 -0
  39. aetos/application/extraction/review.py +133 -0
  40. aetos/application/extraction/span_evidence.py +229 -0
  41. aetos/application/extraction/validation.py +164 -0
  42. aetos/application/facts/__init__.py +5 -0
  43. aetos/application/facts/assembler.py +164 -0
  44. aetos/application/grounding/__init__.py +64 -0
  45. aetos/application/grounding/challenge.py +91 -0
  46. aetos/application/grounding/detector.py +376 -0
  47. aetos/application/grounding/gate.py +116 -0
  48. aetos/application/grounding/mode.py +113 -0
  49. aetos/application/grounding/prompts.py +72 -0
  50. aetos/application/grounding/service.py +334 -0
  51. aetos/application/policy/__init__.py +33 -0
  52. aetos/application/policy/evaluator.py +114 -0
  53. aetos/application/policy/opinion.py +85 -0
  54. aetos/application/policy/rule.py +117 -0
  55. aetos/application/policy/rules/__init__.py +13 -0
  56. aetos/application/policy/rules/criticality_rule.py +50 -0
  57. aetos/application/policy/rules/exit_criteria_rule.py +74 -0
  58. aetos/application/policy/rules/no_owner_rule.py +81 -0
  59. aetos/application/policy/rules/no_rollback.py +120 -0
  60. aetos/application/policy/verdict.py +102 -0
  61. aetos/application/ports.py +233 -0
  62. aetos/application/provider.py +46 -0
  63. aetos/application/services/__init__.py +33 -0
  64. aetos/application/services/answer_service.py +159 -0
  65. aetos/application/services/claim_check.py +55 -0
  66. aetos/application/services/dialogue.py +295 -0
  67. aetos/application/services/evaluate_decision.py +98 -0
  68. aetos/application/services/evaluation_service.py +166 -0
  69. aetos/application/services/extraction_service.py +57 -0
  70. aetos/application/services/fact_validation_service.py +118 -0
  71. aetos/application/services/human_assertion.py +85 -0
  72. aetos/application/services/qa_loop.py +242 -0
  73. aetos/application/services/question_phraser.py +138 -0
  74. aetos/application/services/smart_colleague.py +210 -0
  75. aetos/application/verdict_state.py +138 -0
  76. aetos/domain/__init__.py +0 -0
  77. aetos/domain/agent.py +538 -0
  78. aetos/domain/chain_subject.py +70 -0
  79. aetos/domain/entities/__init__.py +18 -0
  80. aetos/domain/entities/contradiction.py +54 -0
  81. aetos/domain/entities/decision.py +379 -0
  82. aetos/domain/facts/__init__.py +28 -0
  83. aetos/domain/facts/decision_facts.py +68 -0
  84. aetos/domain/facts/fact.py +65 -0
  85. aetos/domain/facts/source.py +23 -0
  86. aetos/domain/facts/vocabulary.py +95 -0
  87. aetos/domain/ports/__init__.py +11 -0
  88. aetos/domain/ports/clock.py +19 -0
  89. aetos/domain/ports/id_generator.py +19 -0
  90. aetos/domain/values/__init__.py +83 -0
  91. aetos/domain/values/_identity.py +120 -0
  92. aetos/domain/values/_numeric.py +84 -0
  93. aetos/domain/values/_reliability.py +21 -0
  94. aetos/domain/values/_timestamp.py +67 -0
  95. aetos/domain/values/_validation.py +19 -0
  96. aetos/domain/values/actor.py +34 -0
  97. aetos/domain/values/confidence.py +61 -0
  98. aetos/domain/values/evidence.py +34 -0
  99. aetos/domain/values/human_response.py +40 -0
  100. aetos/domain/values/provenance.py +40 -0
  101. aetos/domain/values/recommendation.py +39 -0
  102. aetos/guard.py +215 -0
  103. aetos/infrastructure/__init__.py +0 -0
  104. aetos/infrastructure/adapters/__init__.py +105 -0
  105. aetos/infrastructure/adapters/chat_anthropic.py +101 -0
  106. aetos/infrastructure/adapters/chat_ollama.py +105 -0
  107. aetos/infrastructure/adapters/chat_openai.py +102 -0
  108. aetos/infrastructure/adapters/decision_repository.py +596 -0
  109. aetos/infrastructure/adapters/ecc_p256_signer.py +92 -0
  110. aetos/infrastructure/adapters/ed25519_signer.py +143 -0
  111. aetos/infrastructure/adapters/ollama_fact_extractor.py +492 -0
  112. aetos/infrastructure/adapters/ollama_phraser.py +102 -0
  113. aetos/infrastructure/adapters/system_clock.py +72 -0
  114. aetos/infrastructure/adapters/system_id_generator.py +61 -0
  115. aetos/infrastructure/hashing.py +15 -0
  116. aetos/infrastructure/migrations.py +247 -0
  117. aetos/interfaces/__init__.py +0 -0
  118. aetos/interfaces/api/__init__.py +5 -0
  119. aetos/interfaces/api/app.py +131 -0
  120. aetos/interfaces/api/auth.py +100 -0
  121. aetos/interfaces/api/colleague_demo.py +383 -0
  122. aetos/interfaces/api/composition.py +268 -0
  123. aetos/interfaces/api/demo_page.py +350 -0
  124. aetos/interfaces/api/grounding_routes.py +84 -0
  125. aetos/interfaces/api/provider_factory.py +247 -0
  126. aetos/interfaces/api/routes.py +851 -0
  127. aetos/interfaces/api/schemas.py +368 -0
  128. aetos/interfaces/cli/__init__.py +0 -0
  129. aetos/interfaces/cli/demo.py +142 -0
  130. aetos/interfaces/exporter/__init__.py +0 -0
  131. aetos/interfaces/verifier/__init__.py +0 -0
  132. aetos/interfaces/verifier/body_attestation.py +524 -0
  133. aetos/interfaces/verifier/build_pack.py +703 -0
  134. aetos/interfaces/verifier/chain_verifier.py +174 -0
  135. aetos/interfaces/verifier/cli.py +272 -0
  136. aetos/interfaces/verifier/pack_schema.py +796 -0
  137. aetos/interfaces/verifier/report.py +117 -0
  138. aetos/interfaces/verifier/signature_verifier.py +252 -0
  139. aetos/interfaces/verifier/trust_anchor.py +144 -0
  140. aetos/interfaces/verifier/verify_pack.py +275 -0
  141. aetos/interfaces/verify_portal.py +282 -0
  142. aetos/py.typed +0 -0
  143. aetos_verify-0.3.3.dist-info/METADATA +323 -0
  144. aetos_verify-0.3.3.dist-info/RECORD +148 -0
  145. aetos_verify-0.3.3.dist-info/WHEEL +5 -0
  146. aetos_verify-0.3.3.dist-info/entry_points.txt +2 -0
  147. aetos_verify-0.3.3.dist-info/licenses/LICENSE +201 -0
  148. aetos_verify-0.3.3.dist-info/top_level.txt +1 -0
aetos/__init__.py ADDED
@@ -0,0 +1,43 @@
1
+ """AETOS — tamper-evident, offline-verifiable receipts for AI-assisted decisions.
2
+
3
+ The **distribution** name is ``aetos-verify``; the **import package** is
4
+ ``aetos``. See ``docs/adr/0034-v1-0-scope-and-naming.md``.
5
+
6
+ The version lives in exactly one place — ``pyproject.toml`` — and is read back
7
+ from the installed distribution metadata here. Nothing under ``src/`` may write
8
+ it as a literal. The reason is not tidiness: the value is embedded in every
9
+ exported pack (``metadata.aetos_version``), so a literal that drifts makes the
10
+ artefact a buyer receives misreport the version that produced it.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from importlib.metadata import PackageNotFoundError
16
+ from importlib.metadata import version as _distribution_version
17
+
18
+ DISTRIBUTION = "aetos-verify"
19
+ UNKNOWN_VERSION = "0.0.0+unknown"
20
+
21
+
22
+ def resolve_version(
23
+ distribution: str = DISTRIBUTION,
24
+ fallback: str = UNKNOWN_VERSION,
25
+ ) -> str:
26
+ """Return the installed version of ``distribution``, else ``fallback``.
27
+
28
+ ``fallback`` covers a source checkout that was never installed. Reporting
29
+ ``0.0.0+unknown`` is honest; reporting a stale literal is not — which is
30
+ what happened here. ``build_pack.py`` carried ``_AETOS_VERSION = "0.2.0"``
31
+ while the manifest said ``0.3.0``, so both shipped demo packs recorded
32
+ ``aetos_version: "0.2.0"``, and no test referenced the literal, so nothing
33
+ could notice.
34
+ """
35
+ try:
36
+ return _distribution_version(distribution)
37
+ except PackageNotFoundError:
38
+ return fallback
39
+
40
+
41
+ __version__ = resolve_version()
42
+
43
+ __all__ = ["DISTRIBUTION", "UNKNOWN_VERSION", "__version__", "resolve_version"]
@@ -0,0 +1,9 @@
1
+ """Application layer: service orchestration and policy logic.
2
+
3
+ This package deliberately performs no eager re-exports: importing it — or
4
+ any of its submodules — must not pull the whole service layer, and in
5
+ particular must not transitively load the human-assertion path (ADR-011
6
+ I-6 / ADR-013 condition 7: ``EvidenceGuard`` stays unaware of human
7
+ authority). Import concrete submodules directly, e.g. ``from
8
+ aetos.application.services import EvaluationService``.
9
+ """
@@ -0,0 +1 @@
1
+ # Agent application layer
@@ -0,0 +1,174 @@
1
+ """ActionGate: the application-layer decision point for agent actions (ADR-013, Day 2).
2
+
3
+ ActionGate answers one question: may this proposed action proceed, and on
4
+ whose authority? It composes the domain primitives into the application
5
+ boundary (``PROPOSAL != EXECUTION``):
6
+
7
+ - The ordered :class:`ActionPolicy` is always evaluated first, so its
8
+ triggered rules travel with every decision as audit context.
9
+ - A sealed :class:`HumanActionOverride`, when present, takes precedence
10
+ over the policy — the human is the ultimate authority and their record
11
+ is the authority itself (``HUMAN_OVERRIDE != SYSTEM_ENDORSEMENT``). A
12
+ human may veto an allowed action, break glass on a **soft deny**, or
13
+ resolve a ``NEED_HUMAN``; the decision then carries ``HUMAN_OVERRIDE``
14
+ provenance (``ALLOW != HUMAN_ENDORSEMENT``).
15
+ - A **hard deny** (policy verdict ``DENY`` with ``overridable=False``) is
16
+ absolute: it encodes a safety-critical prohibition and no human override
17
+ may lift it — the gate returns the policy's deny unchanged. Soft denies
18
+ (``overridable=True``, the default) are the ones a human may override.
19
+ - ``NEED_HUMAN`` is a first-class rule outcome: a rule may actively demand
20
+ human approval for an action class (e.g. production deploys) instead of
21
+ letting the gate fall back to it. The distinction is visible in
22
+ ``triggered_rules`` — an active need carries the rule id, a fallback
23
+ (no rule decided) carries none. ``NEED_HUMAN`` never carries an
24
+ authorization, so no ``EXECUTED`` receipt can be built from it
25
+ (``NO_AUTHORIZATION -> NO_EXECUTED_RECEIPT``).
26
+
27
+ The gate never mutates state and never executes anything — it only
28
+ produces an immutable :class:`GateDecision`.
29
+ """
30
+
31
+ from __future__ import annotations
32
+
33
+ from dataclasses import dataclass
34
+ from enum import Enum, unique
35
+
36
+ from aetos.application.agent.action_policy import ActionPolicy
37
+ from aetos.domain.agent import (
38
+ ActionProposal,
39
+ ActionVerdict,
40
+ AuthorizationKind,
41
+ AuthorizationRecord,
42
+ HumanActionOverride,
43
+ )
44
+ from aetos.domain.values import Timestamp, require_instance
45
+
46
+ __all__ = [
47
+ "ActionGate",
48
+ "DecisionSource",
49
+ "GateDecision",
50
+ ]
51
+
52
+
53
+ @unique
54
+ class DecisionSource(Enum):
55
+ """Whose authority produced the gate's decision."""
56
+
57
+ POLICY = "policy"
58
+ HUMAN_OVERRIDE = "human_override"
59
+
60
+
61
+ @dataclass(frozen=True, slots=True)
62
+ class GateDecision:
63
+ """The gate's immutable decision on a proposed action.
64
+
65
+ ``authorization`` is present exactly when the verdict is ``ALLOW`` or
66
+ ``DENY``; its provenance kind always matches the decision source
67
+ (``SYSTEM_POLICY`` for a policy decision, ``HUMAN_OVERRIDE`` for a
68
+ sealed human override).
69
+
70
+ ``overridable`` says whether a human override may still change this
71
+ decision. Only a ``DENY`` can be non-overridable: a hard policy deny
72
+ is absolute, while soft denies, allows and need-human states remain
73
+ open to human authority.
74
+ """
75
+
76
+ verdict: ActionVerdict
77
+ authorization: AuthorizationRecord | None
78
+ source: DecisionSource
79
+ triggered_rules: tuple[str, ...]
80
+ overridable: bool = True
81
+
82
+ def __post_init__(self) -> None:
83
+ require_instance(self.verdict, ActionVerdict, "GateDecision.verdict")
84
+ if self.authorization is not None:
85
+ require_instance(
86
+ self.authorization,
87
+ AuthorizationRecord,
88
+ "GateDecision.authorization",
89
+ )
90
+ require_instance(self.source, DecisionSource, "GateDecision.source")
91
+ for index, rule_id in enumerate(self.triggered_rules):
92
+ require_instance(rule_id, str, f"GateDecision.triggered_rules[{index}]")
93
+ require_instance(self.overridable, bool, "GateDecision.overridable")
94
+ if self.verdict is ActionVerdict.NEED_HUMAN and self.authorization is not None:
95
+ raise ValueError(
96
+ "a NEED_HUMAN verdict must not carry an authorization: "
97
+ "NEED_HUMAN is a gate state, not an authorization"
98
+ )
99
+ if self.verdict is not ActionVerdict.NEED_HUMAN and self.authorization is None:
100
+ raise ValueError("an ALLOW or DENY verdict must carry an authorization")
101
+ if not self.overridable and self.verdict is not ActionVerdict.DENY:
102
+ raise ValueError(
103
+ "only a DENY decision may be non-overridable; "
104
+ f"got verdict {self.verdict.value!r}"
105
+ )
106
+ if self.authorization is not None:
107
+ expected = (
108
+ AuthorizationKind.HUMAN_OVERRIDE
109
+ if self.source is DecisionSource.HUMAN_OVERRIDE
110
+ else AuthorizationKind.SYSTEM_POLICY
111
+ )
112
+ if self.authorization.kind is not expected:
113
+ raise ValueError(
114
+ "GateDecision.authorization provenance must match the "
115
+ "decision source: "
116
+ f"{self.source.value} requires {expected.value}, "
117
+ f"got {self.authorization.kind.value}"
118
+ )
119
+
120
+
121
+ class ActionGate:
122
+ """Decide whether a proposed agent action may proceed.
123
+
124
+ Authority flows from the human, then the policy:
125
+
126
+ - A sealed :class:`HumanActionOverride`, when present, takes
127
+ precedence over the policy — the human is the ultimate authority and
128
+ their record is the authority itself (``HUMAN_OVERRIDE !=
129
+ SYSTEM_ENDORSEMENT``). A human may veto an allowed action, break
130
+ glass on a soft deny, or resolve a ``NEED_HUMAN``.
131
+ - A **hard deny** (policy verdict ``DENY`` with ``overridable=False``)
132
+ is absolute: it encodes a safety-critical prohibition and no human
133
+ override may lift it. The gate returns the policy's deny unchanged.
134
+ - Without an override the ordered policy decides, and the gate fails
135
+ closed to ``NEED_HUMAN`` when no rule decides.
136
+ """
137
+
138
+ def __init__(self, policy: ActionPolicy) -> None:
139
+ self._policy: ActionPolicy = policy
140
+
141
+ def evaluate(
142
+ self,
143
+ proposal: ActionProposal,
144
+ *,
145
+ override: HumanActionOverride | None = None,
146
+ timestamp: Timestamp | None = None,
147
+ ) -> GateDecision:
148
+ """Decide whether the proposed action may proceed.
149
+
150
+ ``override`` is the sealed human override for this proposal, when
151
+ one exists. ``timestamp`` overrides the authorization time used by
152
+ the policy (defaults to the proposal's own timestamp).
153
+
154
+ The policy is always evaluated first: its triggered rules travel
155
+ with the decision as audit context even when a human override
156
+ decides. An override is ignored only when the policy issued a hard
157
+ deny (``DENY`` with ``overridable=False``).
158
+ """
159
+ verdict = self._policy.evaluate(proposal, timestamp=timestamp)
160
+ hard_deny = verdict.verdict is ActionVerdict.DENY and not verdict.overridable
161
+ if override is not None and not hard_deny:
162
+ return GateDecision(
163
+ verdict=override.verdict,
164
+ authorization=override.to_authorization(),
165
+ source=DecisionSource.HUMAN_OVERRIDE,
166
+ triggered_rules=verdict.triggered_rules,
167
+ )
168
+ return GateDecision(
169
+ verdict=verdict.verdict,
170
+ authorization=verdict.authorization,
171
+ source=DecisionSource.POLICY,
172
+ triggered_rules=verdict.triggered_rules,
173
+ overridable=verdict.overridable,
174
+ )
@@ -0,0 +1,213 @@
1
+ """ActionPolicy: deterministic authorization for agent actions (ADR-013, Day 2).
2
+
3
+ The first application-layer piece of ActionGate (``PROPOSAL != EXECUTION``):
4
+ a policy is an ordered list of rules, and each rule independently evaluates
5
+ a single :class:`ActionProposal`. The first rule that produces a terminal
6
+ verdict (``ALLOW``, ``DENY`` or ``NEED_HUMAN``) decides the action; rules
7
+ that do not apply return ``PASS`` and are skipped.
8
+
9
+ - ``ALLOW`` / ``DENY`` produce an :class:`AuthorizationRecord` with
10
+ :attr:`AuthorizationKind.SYSTEM_POLICY` provenance (``ALLOW !=
11
+ HUMAN_ENDORSEMENT``, ADR-013); the record's reference points at the rule
12
+ that fired.
13
+ - ``NEED_HUMAN`` is a first-class rule outcome: a rule may actively demand
14
+ human approval for an action class (e.g. production deploys). It is a
15
+ gate state, never an authorization — no ``AuthorizationRecord`` is
16
+ produced, so no ``EXECUTED`` receipt can ever be built from it
17
+ (``NO_AUTHORIZATION -> NO_EXECUTED_RECEIPT``).
18
+ - Overridability: a ``DENY`` declares whether a human override may lift it
19
+ (``overridable``, default ``True`` = soft deny). A safety-critical rule
20
+ sets ``overridable=False`` to make its deny absolute. Only a ``DENY``
21
+ may be non-overridable.
22
+ - With no rules, or when every rule passes, the policy fails closed to
23
+ ``NEED_HUMAN`` — a silent allow is impossible.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ from collections.abc import Sequence
29
+ from dataclasses import dataclass
30
+ from enum import Enum, unique
31
+ from typing import Protocol, runtime_checkable
32
+
33
+ from aetos.domain.agent import (
34
+ ActionProposal,
35
+ ActionVerdict,
36
+ AuthorizationKind,
37
+ AuthorizationRecord,
38
+ )
39
+ from aetos.domain.values import Timestamp, require_instance
40
+
41
+
42
+ @unique
43
+ class RuleVerdict(Enum):
44
+ """The verdict a single rule may return."""
45
+
46
+ ALLOW = "allow"
47
+ DENY = "deny"
48
+ NEED_HUMAN = "need_human"
49
+ PASS = "pass" # noqa: S105 - enum member, not a credential; rule does not apply.
50
+
51
+
52
+ @dataclass(frozen=True, slots=True)
53
+ class RuleOutcome:
54
+ """The result of evaluating a single rule against a proposal.
55
+
56
+ ``overridable`` declares whether a human override may change this
57
+ outcome. It only matters for a ``DENY``: the default is a soft deny
58
+ that a human override may lift (break glass), while a safety-critical
59
+ rule sets ``overridable=False`` to make its deny absolute. Only a
60
+ ``DENY`` may declare itself non-overridable.
61
+ """
62
+
63
+ verdict: RuleVerdict
64
+ rule_id: str
65
+ reason: str
66
+ overridable: bool = True
67
+
68
+ def __post_init__(self) -> None:
69
+ require_instance(self.verdict, RuleVerdict, "RuleOutcome.verdict")
70
+ require_instance(self.rule_id, str, "RuleOutcome.rule_id")
71
+ require_instance(self.reason, str, "RuleOutcome.reason")
72
+ require_instance(self.overridable, bool, "RuleOutcome.overridable")
73
+ if not self.overridable and self.verdict is not RuleVerdict.DENY:
74
+ raise ValueError(
75
+ "only a DENY outcome may be non-overridable; "
76
+ f"got verdict {self.verdict.value!r}"
77
+ )
78
+
79
+
80
+ @runtime_checkable
81
+ class ActionRule(Protocol):
82
+ """A single, self-contained authorization rule.
83
+
84
+ A rule only evaluates a proposal; it never mutates state, never
85
+ persists and never executes the action (``PROPOSAL != EXECUTION``).
86
+ """
87
+
88
+ @property
89
+ def rule_id(self) -> str:
90
+ """Stable identifier of this rule."""
91
+ ... # pragma: no cover - protocol body, never executed
92
+
93
+ def evaluate(self, proposal: ActionProposal) -> RuleOutcome:
94
+ """Evaluate the rule against an immutable action proposal."""
95
+ ... # pragma: no cover - protocol body, never executed
96
+
97
+
98
+ @dataclass(frozen=True, slots=True)
99
+ class PolicyVerdict:
100
+ """The immutable result of evaluating a proposal against a policy.
101
+
102
+ ``authorization`` is present exactly when the verdict is ``ALLOW`` or
103
+ ``DENY``. A ``NEED_HUMAN`` verdict never carries an authorization —
104
+ it is a gate state, not an authorization.
105
+
106
+ ``overridable`` tells the gate whether a human override may change the
107
+ outcome. Only a ``DENY`` may be non-overridable: a hard deny (e.g. a
108
+ safety-critical prohibition) is absolute and cannot be lifted by a
109
+ human override.
110
+ """
111
+
112
+ verdict: ActionVerdict
113
+ authorization: AuthorizationRecord | None
114
+ triggered_rules: tuple[str, ...]
115
+ overridable: bool = True
116
+
117
+ def __post_init__(self) -> None:
118
+ require_instance(self.verdict, ActionVerdict, "PolicyVerdict.verdict")
119
+ if self.authorization is not None:
120
+ require_instance(
121
+ self.authorization,
122
+ AuthorizationRecord,
123
+ "PolicyVerdict.authorization",
124
+ )
125
+ for index, rule_id in enumerate(self.triggered_rules):
126
+ require_instance(rule_id, str, f"PolicyVerdict.triggered_rules[{index}]")
127
+ require_instance(self.overridable, bool, "PolicyVerdict.overridable")
128
+ if self.verdict is ActionVerdict.NEED_HUMAN and self.authorization is not None:
129
+ raise ValueError(
130
+ "a NEED_HUMAN verdict must not carry an authorization: "
131
+ "NEED_HUMAN is a gate state, not an authorization"
132
+ )
133
+ if self.verdict is not ActionVerdict.NEED_HUMAN and self.authorization is None:
134
+ raise ValueError("an ALLOW or DENY verdict must carry an authorization")
135
+ if not self.overridable and self.verdict is not ActionVerdict.DENY:
136
+ raise ValueError(
137
+ "only a DENY verdict may be non-overridable; "
138
+ f"got verdict {self.verdict.value!r}"
139
+ )
140
+
141
+
142
+ class ActionPolicy:
143
+ """Authorize or deny agent actions based on an ordered set of rules.
144
+
145
+ Rules are evaluated in order; the first rule that does not ``PASS``
146
+ decides the verdict. When no rule decides (no rules configured, or
147
+ every rule passes) the policy fails closed to ``NEED_HUMAN``.
148
+ """
149
+
150
+ def __init__(self, *, rules: Sequence[ActionRule] = ()) -> None:
151
+ self._rules: tuple[ActionRule, ...] = tuple(rules)
152
+
153
+ def evaluate(
154
+ self,
155
+ proposal: ActionProposal,
156
+ *,
157
+ timestamp: Timestamp | None = None,
158
+ ) -> PolicyVerdict:
159
+ """Evaluate a proposal and return an immutable policy verdict.
160
+
161
+ ``timestamp`` overrides the authorization time; it defaults to the
162
+ proposal's own timestamp.
163
+ """
164
+ authorized_at = proposal.proposed_at if timestamp is None else timestamp
165
+ triggered: list[str] = []
166
+ for rule in self._rules:
167
+ outcome = rule.evaluate(proposal)
168
+ if outcome.verdict is RuleVerdict.PASS:
169
+ continue
170
+ triggered.append(outcome.rule_id)
171
+ if outcome.verdict is RuleVerdict.ALLOW:
172
+ return PolicyVerdict(
173
+ verdict=ActionVerdict.ALLOW,
174
+ authorization=self._authorization(
175
+ ActionVerdict.ALLOW, outcome.rule_id, authorized_at
176
+ ),
177
+ triggered_rules=tuple(triggered),
178
+ )
179
+ if outcome.verdict is RuleVerdict.DENY:
180
+ return PolicyVerdict(
181
+ verdict=ActionVerdict.DENY,
182
+ authorization=self._authorization(
183
+ ActionVerdict.DENY, outcome.rule_id, authorized_at
184
+ ),
185
+ triggered_rules=tuple(triggered),
186
+ overridable=outcome.overridable,
187
+ )
188
+ # RuleVerdict.NEED_HUMAN — terminal, but never an authorization.
189
+ return PolicyVerdict(
190
+ verdict=ActionVerdict.NEED_HUMAN,
191
+ authorization=None,
192
+ triggered_rules=tuple(triggered),
193
+ )
194
+ # No rule decided (no rules, or all PASS) — fail closed.
195
+ return PolicyVerdict(
196
+ verdict=ActionVerdict.NEED_HUMAN,
197
+ authorization=None,
198
+ triggered_rules=(),
199
+ )
200
+
201
+ @staticmethod
202
+ def _authorization(
203
+ verdict: ActionVerdict,
204
+ reference: str,
205
+ authorized_at: Timestamp,
206
+ ) -> AuthorizationRecord:
207
+ """Build the SYSTEM_POLICY authorization for an ALLOW/DENY verdict."""
208
+ return AuthorizationRecord(
209
+ kind=AuthorizationKind.SYSTEM_POLICY,
210
+ verdict=verdict,
211
+ reference=reference,
212
+ authorized_at=authorized_at,
213
+ )