67 lines
1.5 KiB
Markdown
67 lines
1.5 KiB
Markdown
|
# 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)
|