040-decision-explanation

Decision explanation API and `rustev explain` (amends 004 and 006)

Lifecycle approvedImplementation completeVerification unknownQualification unknown

An amendment of approved specs 004 and 006 (R-16), for #76 child D2. A pure function over recorded evidence (a delivered `rustev.run/1` record, or a `rustev.replay/1` bundle, with the plan document when supplied) answers seven structured questions: why an item was selected, why one was excluded, why one item precedes another, why the outcome is what it is, where text came from, which models answered at what cost, and where two decisions first diverge. Answers are written as a versioned `rustev.explanation/1` document in which every fact cites the evidence path it was copied from and carries the derivation class and lineage its source records; a fact the evidence does not hold, or holds only as a digest, or that a supplied redaction policy withholds, is `not_available` with a typed reason, never a guess. Nothing is re-executed, compiled or dispatched and no model is called. Adds a deterministic Markdown rendering, `rustev explain` in the CLI, and the binding surface for the Node and WebAssembly packages and the service. No existing document, identity or CLI output changes. Approved (A-37); implementation is pending.

Read the full pinned specification ↗

Relationships

depends on

amends

Claimed units

extends

{
  "nature": "additive",
  "spec": "002-decision-contract-and-pure-core",
  "unit": {
    "kind": "directory",
    "path": "crates/rustev-contract/"
  }
}

extends

{
  "nature": "amending",
  "spec": "004-evaluation-and-replay",
  "unit": {
    "kind": "directory",
    "path": "crates/rustev-eval/"
  }
}

extends

{
  "nature": "amending",
  "spec": "006-cli-surface",
  "unit": {
    "kind": "directory",
    "path": "crates/rustev-cli/"
  }
}

extends

{
  "nature": "additive",
  "spec": "027-node-and-wasm-bindings",
  "unit": {
    "kind": "directory",
    "path": "crates/rustev-surface/"
  }
}

extends

{
  "nature": "additive",
  "spec": "027-node-and-wasm-bindings",
  "unit": {
    "kind": "directory",
    "path": "integrations/rustev-node/"
  }
}

extends

{
  "nature": "additive",
  "spec": "027-node-and-wasm-bindings",
  "unit": {
    "kind": "directory",
    "path": "integrations/rustev-wasm/"
  }
}

extends

{
  "nature": "additive",
  "spec": "027-node-and-wasm-bindings",
  "unit": {
    "kind": "directory",
    "path": "tools/rustev-conformance/"
  }
}

extends

{
  "nature": "additive",
  "spec": "001-boundaries-and-authority",
  "unit": {
    "kind": "file",
    "path": "Makefile"
  }
}

extends

{
  "nature": "additive",
  "spec": "001-boundaries-and-authority",
  "unit": {
    "kind": "directory",
    "path": "scripts/acceptance/"
  }
}

extends

{
  "nature": "additive",
  "spec": "031-public-api-and-release-family",
  "unit": {
    "kind": "directory",
    "path": "tools/rustev-release/"
  }
}

Source headings

040: Decision explanation API and `rustev explain` (amends 004 and 006)
1. Purpose
2. Territory
2.1 Binding principles of #76
3. Behavior
3.1 Evidence sets
3.2 Evidence paths
3.3 The explanation document, `rustev.explanation/1`
3.4 The explainer
3.5 Facts, availability, derivation and lineage
3.6 `why_selected(item)`
3.7 `why_excluded(item)` and `why_order(a, b)`
3.8 `why_outcome()`
3.9 `text_origin()`
3.10 `models()`
3.11 `diff()`
3.12 Facets supplied by later specs
3.13 Redaction
3.14 Markdown rendering
3.15 Library surface, bindings and service
3.16 CLI surface (amends spec 006)
3.17 Exit codes and refusal codes
3.18 Compatibility
4. Out of scope
5. Observable negative cases
Acceptance
Verification
Implementation record
Decisions at approval

Frozen anchors

No frozen anchors declared.