decision-canon/reviews/kernel-proposal.md

Kernel proposal

Proposal from DECISION-WP-0003. Evidence is 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:

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.