decision-canon/reviews/kernel-proposal.md

# Kernel proposal

Proposal from `DECISION-WP-0003`. Evidence is [schema-pressure.md](schema-pressure.md) and the six examples under `examples/`. This note does not freeze the kernel. `DecisionObjectSchemaDraft.md` is unchanged. Nothing here is a schema edit.

## D1 minimum

`DEC-EX-001` is a valid decision object. A recorded decision must be able to carry these three fields and no others:

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

| Field | Role |
| --- | --- |
| `question` | What is being decided. A string is the question text. An object is allowed, and then `question.text` is that text. |
| `choice` | What was selected. Prose, as in `DEC-EX-001`, or an `alternatives[].id` when an `alternatives` envelope is present. |
| `reason` | Why, in the words available at decision time. This is the kernel home for what `UnifiedDecisionObject.md` calls `rationale`. |

`identity`, `kind`, `state`, and `commitment` are not required for this object to count. Adding them is what made the draft unable to hold `DEC-EX-001`.

A question with no `choice` is not yet a decision. The `choice` is the commitment. A separate `commitment` section is how a later envelope records who committed, when, and under what mode. `DEC-EX-003` needs that envelope. `DEC-EX-001` does not.

## Envelopes

Every other draft section is an optional envelope. Absence means the situation did not need it. It does not mean the field was considered and left blank.

| Envelope | D1 | First example that needed it |
| --- | --- | --- |
| `identity` | no | `DEC-EX-002`. Also required on any decision that another decision points at. |
| `kind` | no | `DEC-EX-002` (`choice`). `DEC-EX-004` uses `exception`, `DEC-EX-005` uses `policy`, `DEC-EX-006` uses `constitutional`. |
| `state` | no | `DEC-EX-002` |
| `frame` | no | `DEC-EX-002` |
| `alternatives` | no | `DEC-EX-002`, including the do-nothing alternative. `DEC-EX-003` adds wait. |
| `values` | no | `DEC-EX-002`. Objectives, constraints, and vetoes stay separate fields. |
| `analysis` | no | `DEC-EX-002`, which needed two results. |
| `world_model` | no | Not required even for `DEC-EX-002`. Competing causal stories live in `analysis`. |
| `commitment` | no | `DEC-EX-002` and `DEC-EX-003`, for who, when, mode, and reservations. |
| `governance` | no | `governance.owner` in `DEC-EX-002`. `authority` in `DEC-EX-004`, `DEC-EX-005`, and `DEC-EX-006`. |
| `uncertainty` | no | `DEC-EX-003` |
| `execution` | no | `DEC-EX-003` |
| `outcome` | no | `DEC-EX-003` |
| `learning` | no | `DEC-EX-003` |
| `temporal` | no | `DEC-EX-003`, so decision time and observation time stay distinct. |
| `effects` | no | `DEC-EX-004`, `DEC-EX-005`, and `DEC-EX-006`. |
| `relationships` | no | `DEC-EX-004` (`exception-to`). |
| `metadata` | no | `DEC-EX-004` (`formality_level`). |
| `evidence` | no | None of the six. The envelope stays available. |
| `information_options` | no | None of the six. The envelope stays available. |
| `optionality` | no | None of the six. Reversibility of a candidate stays on that alternative. |

`UnifiedDecisionObject.md` section 3 lists a larger conceptual kernel (`id`, `kind`, `state`, `context`, `owner`, `alternatives`, `commitment`, `created_at`). Those are envelopes in this proposal. The D1 minimum is the smaller set the probe could not remove.

## Homes kept

Where the pressure note found two homes for one fact, this proposal keeps one.

| Fact | Kept home | Other home, not used for this fact |
| --- | --- | --- |
| Question text | A string `question`, or `question.text` when `question` is an object | A second copy elsewhere |
| Trigger | `frame.trigger` | `question.trigger` |
| What was selected | `choice` | `commitment.selected` must match `choice` when both are present. It is not a second choice. |
| Why | `reason` | `analysis.recommendation` may name the same alternative. It is not the reason. `learning.lessons` is later. |
| Reversibility of a candidate | `alternatives[].reversibility` | Top-level `optionality`, unless it says something about the chosen alternative that the candidate entry does not |
| Who committed, when, and how | `commitment.by`, `commitment.at`, `commitment.mode` | Putting those facts into `choice` or `reason` |
| When the decision is in force | `temporal.effective_from` and `temporal.effective_until` | `commitment.conditions` for a pure end time. `effects[].effective_when` and `effects[].expires_when` only when that one effect starts or ends at a different time from the decision. |
| Current lifecycle | `state.lifecycle`, one current value | A history inside `state`. Times that must survive live in `temporal`. |
| Decision-time assumptions | `frame.assumptions`, sealed once `choice` is recorded | Editing that list after the fact. A later correction goes in `learning`. |
| Competing causal stories | `analysis.analyses[]` | A second `world_model`. If `world_model` is present, it is the model the choice relied on. |
| Confidence | A word is enough (`high`, `medium`, `low`) on the envelope that owns it | A required number |
| Policy | The decision, with `kind: policy`, plus one `effects` entry of type `policy` that holds the rule | Repeating the rule in `commitment.selected` or `commitment.conditions` |
| What a policy governs | A later decision's `relationships` entry `governed-by`, pointing at the policy id | An inverse list on the policy. `effects[].target` names the class in words. |
| Exception | `kind: exception`, an effect of type `authorization`, and `exception-to` | A second kind `authorization` that only repeats the effect |
| Constitutional character | `kind: constitutional` | An effect type `constitutional`. Effects stay `requirement` or `constraint`. |
| How this rule may be changed | `relationships` type `supersedes` on the later decision | A nested object inside the earlier decision. The earlier decision may state the requirement in an effect. |
| Authority source | `governance.authority.source` | A parallel field. Use a decision id when one exists (`DEC-EX-004` points at `DEC-EX-005`). A sentence is allowed when there is no prior decision (`DEC-EX-006`). |
| `can` / `may` / `must` | Strings on `governance.authority` | Booleans. `DEC-EX-006` needs the sentence. A boolean capability can be written as a sentence. |
| Effect target | `effects[].target` | A second target field in this proposal. The writer says whether the value is an id or a class. A later schema may split the field. This note does not. |
| Executable rule text | Prose in `effects[].value` until a rule language is chosen | A copy in `commitment.conditions`, and a new kernel field |

## Recommendations for a later schema revision

Not applied in this workplan:

1. Describe the D1 object (`question`, `choice`, `reason`) as valid, including a string `question`.
2. Add `choice` and `reason` to the draft's kernel story, and state the homes in the table above.
3. Say that `confidence` may be a word.
4. Say that `frame.assumptions` is not rewritten after `choice` is recorded, and that later facts go in `learning`.
5. Leave the executable rule language unspecified. `DEC-EX-005` does not justify a DMN or OPA field yet.

Still open, and not answered by another example of the same six shapes:

- The root of authority, when `authority.source` is a sentence rather than a decision id (`DEC-EX-006`).
- A structural bound on rules that change the rules for changing rules. This proposal keeps `kind`, effects, and `supersedes` on the successor. It does not add a depth counter.
- Which existing rule language to reuse, and where an executable body would sit.

## Situations not in the six

Hiring, procurement, investment, budget allocation, and public-style policy would not move this D1 minimum. Allocation, bet, and value-of-information would exercise envelopes the six left empty (`effects` type `allocation`, `kind: bet`, `information_options`). They are not a reason to write those examples before a schema revision adopts this cut. They are not a separate workplan.