RFC 0009 — Decision v1

Purpose

Make “Decision” a first-class, named object for Hub narratives and indexing. A Decision points at an approved bundle digest and carries minimal fields for list/filter/export.

This is an index + story layer only (no execution changes).

Fields (decision_v1)

schema: "helix.decision.v1"
canonicalization_id: "json.c14n.v1" (optional but recommended)

decision_id: string
workspace_id: string
project_id: string
decision_kind: string
subject: JSON

state: "proposed" | "approved" | "rejected" | "superseded"
created_at_utc: RFC3339
created_by: string

proposed_bundle_digest: "sha256:…"
policy_digest: "sha256:…"
backend_fingerprint_digest: "sha256:…"

approval: null | {
  approval_surface_digest: "sha256:…"
  approval_receipt_digests: ["sha256:…", ...]
  approved_at_utc: RFC3339
  approved_by: [string, ...]
}

approved_bundle_digest: null | "sha256:…"

supersedes_decision_id: string (optional)
superseded_by_decision_id: string (optional; required when state="superseded")
rejection_reason: string (optional)

decision_digest: "sha256:…"

State machine

proposed: proposed_bundle_digest set, approval=null, approved_bundle_digest=null
approved: approval present, approved_bundle_digest set
rejected: approval=null, approved_bundle_digest=null, optional rejection_reason
superseded: superseded_by_decision_id set (and typically retains approval + approved bundle digest)

Deterministic decision digest

decision_digest is computed as:

sha256(canonical_json(decision_without_decision_digest))

Canonical JSON is defined by RFC 0002.

Reference schema

schemas/hub/decision_v1.schema.json
src/helix/schema/hub/decision_v1.schema.json