Partiality Governance
Govern missing values and failures so semantics stay explicit, core logic stays readable, and non-happy paths are deliberate.
Response Contract
- Deliverable: apply the requested changes to the target artifact.
- Chat output: no additional output beyond the deliverable.
Partiality Model
Definitions used to classify partiality and choose representations and placement.
Partiality Classes
Missing value
A value may be absent.
Expected failure
A caller-actionable outcome that is part of normal control flow.
Unexpected failure
An invariant violation or impossible state.
Boundaries
Leaf operations
Parsing, I/O, RPC, persistence. The origin of many Missing value and failure signals.
Boundary adapters
The layer that translates external partiality into domain-consumable forms and hosts policy decisions.
Core domain
Business rules and domain model where behavior should be expressed with minimal plumbing.
Representations
Optional
A representation for Missing value when absence is a valid domain state.
Result
An explicit outcome representation for normal control flow that includes success and Expected failure.
Crash
Termination of the current unit of work for Unexpected failure.
Governance Standards
Apply these standards throughout the change. Each standard is single-sourced here and referenced elsewhere by its ID.
optional.semantic_only — Optional means legitimate absence
Use Optional only for Missing value where absence is a valid domain state. If absence is invalid for the caller, treat it as Expected failure and represent it as Result.
result.expected_only — Result is for expected control flow
Use Result for normal control flow that includes Expected failure. Do not encode Unexpected failure as Result.
fail.unexpected_fast — Unexpected failures crash
Treat invariant violations and impossible states as Unexpected failure and Crash immediately. Do not convert them into defaults, fallbacks, or Expected failure.
fallback.no_silent — No silent fallback
Defaults, fallbacks, and degraded modes must be explicit in semantics and observable. Never “pretend success”.
context.preserve — Preserve diagnostic context
Preserve the original cause and relevant parameters when propagating or translating partiality.
catch.no_blanket — No blanket catch as control flow
Do not swallow failures. Handle only known Expected failure cases or translate at a Boundary adapter without changing semantics.
observability.required — Policy actions are observable
Fallbacks and degraded modes must emit structured signals suitable for debugging and alerting.
propagation.normalize — Normalize partiality before core domain
Translate Optional and Result at Boundary adapters so Core domain logic does not need pervasive Optional checks or Result plumbing. When partiality is semantically meaningful in the domain, represent it as an explicit domain state.
core.totality_prefer — Prefer total core logic
Keep Core domain code focused on domain behavior. Prefer explicit domain states over repeated guard clauses, Optional unwrapping, and Result branching.
Workflow
- Enumerate partiality points and label each as Missing value, Expected failure, or Unexpected failure.
- Choose one representation at the origin:
- Missing value with legitimate absence: Optional
- Expected failure: Result
- Unexpected failure: Crash
- Move policy decisions into Boundary adapters and remove leaf-level policy implementations. Apply
fallback.no_silent.
- Normalize Optional and Result at Boundary adapters so Core domain reads as domain behavior. Apply
propagation.normalize and core.totality_prefer.
- Remove silent defaults and blanket catching that hide semantics. Apply
fallback.no_silent, catch.no_blanket.
- Add diagnostics and policy visibility. Apply
context.preserve, observability.required.
- Run acceptance checks.
Acceptance Criteria
A revision is complete only if all checks pass.
- Response: Output satisfies the Response Contract.
- Standards satisfied:
optional.semantic_only, result.expected_only, fail.unexpected_fast, fallback.no_silent, context.preserve, catch.no_blanket, observability.required, propagation.normalize, core.totality_prefer.
1---2name: partiality-governance3description: Use when optional values, fallbacks, defaults, or failure paths materially influence behavior and need explicit governance. Goal: optionality and failure semantics are explicit, and non-happy paths remain deliberate.4---5
6# Partiality Governance
7
8Govern missing values and failures so semantics stay explicit, core logic stays readable, and non-happy paths are deliberate.
9
10## Response Contract
11
12- Deliverable: apply the requested changes to the target artifact.
13- Chat output: no additional output beyond the deliverable.
14
15## Partiality Model
16
17Definitions used to classify partiality and choose representations and placement.
18
19### Partiality Classes
20
21- **Missing value**
22 A value may be absent.
23
24- **Expected failure**
25 A caller-actionable outcome that is part of normal control flow.
26
27- **Unexpected failure**
28 An invariant violation or impossible state.
29
30### Boundaries
31
32- **Leaf operations**
33 Parsing, I/O, RPC, persistence. The origin of many Missing value and failure signals.
34
35- **Boundary adapters**
36 The layer that translates external partiality into domain-consumable forms and hosts policy decisions.
37
38- **Core domain**
39 Business rules and domain model where behavior should be expressed with minimal plumbing.
40
41### Representations
42
43- **Optional**
44 A representation for Missing value when absence is a valid domain state.
45
46- **Result**
47 An explicit outcome representation for normal control flow that includes success and Expected failure.
48
49- **Crash**
50 Termination of the current unit of work for Unexpected failure.
51
52## Governance Standards
53
54Apply these standards throughout the change. Each standard is single-sourced here and referenced elsewhere by its ID.
55
56- **optional.semantic_only — Optional means legitimate absence**
57 Use Optional only for Missing value where absence is a valid domain state. If absence is invalid for the caller, treat it as Expected failure and represent it as Result.
58
59- **result.expected_only — Result is for expected control flow**
60 Use Result for normal control flow that includes Expected failure. Do not encode Unexpected failure as Result.
61
62- **fail.unexpected_fast — Unexpected failures crash**
63 Treat invariant violations and impossible states as Unexpected failure and Crash immediately. Do not convert them into defaults, fallbacks, or Expected failure.
64
65- **fallback.no_silent — No silent fallback**
66 Defaults, fallbacks, and degraded modes must be explicit in semantics and observable. Never “pretend success”.
67
68- **context.preserve — Preserve diagnostic context**
69 Preserve the original cause and relevant parameters when propagating or translating partiality.
70
71- **catch.no_blanket — No blanket catch as control flow**
72 Do not swallow failures. Handle only known Expected failure cases or translate at a Boundary adapter without changing semantics.
73
74- **observability.required — Policy actions are observable**
75 Fallbacks and degraded modes must emit structured signals suitable for debugging and alerting.
76
77- **propagation.normalize — Normalize partiality before core domain**
78 Translate Optional and Result at Boundary adapters so Core domain logic does not need pervasive Optional checks or Result plumbing. When partiality is semantically meaningful in the domain, represent it as an explicit domain state.
79
80- **core.totality_prefer — Prefer total core logic**
81 Keep Core domain code focused on domain behavior. Prefer explicit domain states over repeated guard clauses, Optional unwrapping, and Result branching.
82
83## Workflow
84
851. Enumerate partiality points and label each as Missing value, Expected failure, or Unexpected failure.
862. Choose one representation at the origin:
87 - Missing value with legitimate absence: Optional
88 - Expected failure: Result
89 - Unexpected failure: Crash
903. Move policy decisions into Boundary adapters and remove leaf-level policy implementations. Apply `fallback.no_silent`.
914. Normalize Optional and Result at Boundary adapters so Core domain reads as domain behavior. Apply `propagation.normalize` and `core.totality_prefer`.
925. Remove silent defaults and blanket catching that hide semantics. Apply `fallback.no_silent`, `catch.no_blanket`.
936. Add diagnostics and policy visibility. Apply `context.preserve`, `observability.required`.
947. Run acceptance checks.
95
96## Acceptance Criteria
97
98A revision is complete only if all checks pass.
99
100- **Response**: Output satisfies the Response Contract.
101- **Standards satisfied**: `optional.semantic_only`, `result.expected_only`, `fail.unexpected_fast`, `fallback.no_silent`, `context.preserve`, `catch.no_blanket`, `observability.required`, `propagation.normalize`, `core.totality_prefer`.
majiayu000