# Outcome Summary Columns Contract

**Name:** outcome-summary-columns
**Version:** 1.0
**Date:** 2026-04-01
**Status:** Active
**Layer:** Core
**Workplan:** IHUB-WP-0013 T01 / T06

---

## Purpose

Phase 12 adds `outcome_summary JSONB NULL` to two core tables —
`decision_records` and `requirement_candidates` — to support retroactive
lineage enrichment and learning queries without deep joins.

---

## Schema

```sql
ALTER TABLE decision_records
    ADD COLUMN outcome_summary JSONB NULL;

ALTER TABLE requirement_candidates
    ADD COLUMN outcome_summary JSONB NULL;
```

---

## Semantics

`outcome_summary` is a **JSONB array** of outcome signal snapshots. Each
element has the shape:

```json
{
  "signal_type": "success | adoption | satisfaction | ...",
  "value": 0.85,
  "observed_at": "2026-04-01T12:00:00Z"
}
```

The column starts `NULL` and is populated by:

1. The `trg_enrich_lineage` AFTER INSERT trigger on `outcome_signals`
   (automatic, real-time).
2. `EnrichLineageAction { hubId }` in `Web/Controller/LineageEnrichment.hs`
   (on-demand batch backfill).

---

## Mutation Rules

- Elements are **appended** via `COALESCE(outcome_summary, '[]'::jsonb) || new_element`.
- No element is ever removed or modified.
- Application code must never overwrite the column with a truncated array.

---

## Contract Dependencies

- `append-only-events-v1.md` — `outcome_signals` trigger clause
- `decision_records` table (core, Phase 3)
- `requirement_candidates` table (core, Phase 2)