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:

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

and:

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:

small mandatory kernel
+
optional envelopes

3. Kernel

Conceptual kernel:

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

Only a minimal subset needs to be populated.

4. Frame envelope

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

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

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

Claims may carry:

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

world_model:
  variables:
  states:
  relationships:
  causal_model:
  scenarios:

The model should be capable of distinguishing prediction from intervention:

P(Y | X)

versus:

P(Y | do(X))

Multiple competing models may coexist.

8. Value envelope

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

Constraints and vetoes should not be forced into weighted objectives.

Example:

objectives:
  - minimize operating cost
  - maximize delivery speed

constraints:
  - customer data remains in approved jurisdictions

vetoes:
  - unacceptable safety risk

9. Analysis envelope

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

Multiple analyses may coexist.

10. Uncertainty envelope

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

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

This models investigation as a first-class decision option.

12. Governance envelope

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

Authority can be represented as:

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

13. Commitment

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

commitment:
  selected: scale-out

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

This bridges one-time decisions and reusable policy.

15. Execution envelope

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

The model distinguishes:

decided
executed
effective

16. Outcome envelope

outcome:
  observations:
  metrics:
  unintended_effects:
  stakeholder_effects:
  occurred_at:

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

17. Learning envelope

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

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:

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

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.