decision-canon/UnifiedDecisionObject.md

# Unified Decision Object v0.1

## 1. Intent

A Decision Object is a persistent representation of an intentional commitment made by an actor or decision system in response to a decision situation.

It must scale from lightweight informal decisions to deeply governed policy and constitutional decisions.

## 2. Progressive formalization

The same semantic object should support:

```yaml
question: Which database should we use?
choice: PostgreSQL
reason: It is sufficient and already operationally familiar.
```

and:

```yaml
id: DEC-ROOT-SEC-001
kind: constitutional
state: effective

question: >
  How shall security authority be delegated across the platform?

commitment:
  selected: progressive-risk-based-delegation

effects:
  - type: policy
    ...
```

The goal is therefore not a single huge mandatory schema.

The object should consist of:

```text
small mandatory kernel
+
optional envelopes
```

## 3. Kernel

Conceptual kernel:

```yaml
decision:
  id:
  question:
  kind:
  state:
  context:
  owner:
  alternatives:
  commitment:
  rationale:
  created_at:
```

Only a minimal subset needs to be populated.

## 4. Frame envelope

```yaml
frame:
  situation:
  trigger:
  scope:
  horizon:
  boundaries:
  assumptions:
  exclusions:
  stakeholders:
  dependencies:
```

The frame answers:

> What problem do we believe we are deciding?

The frame must itself remain challengeable.

## 5. Alternatives / interventions

```yaml
alternatives:
  - id:
    action:
    description:
    prerequisites:
    reversibility:
    reversal_cost:
```

Canonical alternatives may include:

- act,
- do nothing,
- wait,
- delegate,
- investigate,
- experiment,
- combine alternatives.

## 6. Evidence / belief envelope

```yaml
evidence:
  observations: []
  claims: []
  sources: []
  assumptions: []
  models: []
  uncertainties: []
```

Claims may carry:

```yaml
claim:
  statement:
  status: observed | estimated | assumed | inferred
  confidence:
  source:
  valid_at:
```

The system should preserve what was known at decision time.

## 7. World / causal model

```yaml
world_model:
  variables:
  states:
  relationships:
  causal_model:
  scenarios:
```

The model should be capable of distinguishing prediction from intervention:

```text
P(Y | X)
```

versus:

```text
P(Y | do(X))
```

Multiple competing models may coexist.

## 8. Value envelope

```yaml
values:
  objectives:
  constraints:
  preferences:
  thresholds:
  vetoes:
  tradeoffs:
```

Constraints and vetoes should not be forced into weighted objectives.

Example:

```yaml
objectives:
  - minimize operating cost
  - maximize delivery speed

constraints:
  - customer data remains in approved jurisdictions

vetoes:
  - unacceptable safety risk
```

## 9. Analysis envelope

```yaml
analysis:
  methods:
  models:
  results:
  sensitivity:
  robustness:
  recommendation:
  confidence:
```

Multiple analyses may coexist.

## 10. Uncertainty envelope

```yaml
uncertainty:
  known_unknowns:
  model_uncertainty:
  outcome_uncertainty:
  ambiguity:
  reducible:
  irreducible:
  decision_relevance:
```

The key practical question is:

> Could resolving this uncertainty change the decision?

## 11. Information acquisition

```yaml
information_options:
  - question:
    method:
    cost:
    delay:
    expected_information_value:
```

This models investigation as a first-class decision option.

## 12. Governance envelope

```yaml
governance:
  authority:
  decision_owner:
  advisors:
  approvers:
  challengers:
  affected_parties:
  delegation:
  escalation:
  oversight:
```

Authority can be represented as:

```yaml
authority:
  can: true
  may: true
  scope: tenant
  source: POLICY-SEC-004
```

## 13. Commitment

```yaml
commitment:
  selected:
  by:
  at:
  mode:
  confidence:
  conditions:
  reservations:
```

Modes may include:

- `decided`
- `approved`
- `accepted`
- `consented`
- `voted`
- `ordered`
- `delegated`
- `automatically-selected`

A recommendation is not yet a decision.

A decision exists when an authorized commitment occurs.

## 14. Conditional decisions

```yaml
commitment:
  selected: scale-out

  effective_when:
    - cpu_utilization > 80%
    - duration > 15m
```

This bridges one-time decisions and reusable policy.

## 15. Execution envelope

```yaml
execution:
  intended_actions:
  responsible:
  status:
  started_at:
  completed_at:
  evidence:
```

The model distinguishes:

```text
decided
executed
effective
```

## 16. Outcome envelope

```yaml
outcome:
  observations:
  metrics:
  unintended_effects:
  stakeholder_effects:
  occurred_at:
```

Outcome observations should not overwrite the original decision-time model.

## 17. Learning envelope

```yaml
learning:
  expected:
  observed:
  deviations:
  hypothesis_updates:
  calibration:
  lessons:
  followup_decisions:
```

This allows post-decision questions such as:

- Which assumptions failed?
- Was confidence calibrated?
- Did the causal model hold?
- Was the decision method appropriate?
- Should policy change?

## 18. Optionality

```yaml
optionality:
  reversible:
  reversal_cost:
  reversal_delay:
  locks_in:
  options_created:
  options_destroyed:
```

## 19. Temporal model

The object should distinguish:

- decision time,
- execution time,
- observation time,
- current time.

The system must not rewrite historical epistemic state with later knowledge.

## 20. Effects

Decision effects may target:

- world state,
- resources,
- permissions,
- delegations,
- policies,
- constraints,
- defaults,
- incentives,
- future decision rules.

A policy decision may therefore produce:

```yaml
effects:
  - type: policy
    policy:
      scope: production-deployment

      permit:
        - autonomous deployment at low risk

      require:
        - human approval at high risk

      prohibit:
        - autonomous platform-root changes
```

## 21. Policy recursion

```text
Operational decision
    ↓
changes world state

Policy decision
    ↓
changes future decision state space

Constitutional decision
    ↓
changes how policy and authority may change
```

This recursion is a foundational capability of the model.

## 22. Decision graph

Decision Objects should be linkable through typed relationships.

This forms a Decision Graph capable of representing authority and causal lineage through an ecosystem.