inter-hub/contracts/core/append-only-events-v1.md

Append-Only Events Contract

Name: append-only-events Version: 1.0 Date: 2026-03-31 Status: Active Layer: Core Immutable: Yes — this invariant is permanent and cannot be relaxed

---

Purpose

Interaction events and outcome signals are the primary observational record of the IHF. Their integrity as an append-only log is a foundational invariant: governance, traceability, and antifragility all depend on the fact that the historical record cannot be silently rewritten.

---

Invariant

The following tables are append-only:

Table	Trigger (no update)	Trigger (no delete)
interaction_events	interaction_events_no_update	interaction_events_no_delete
outcome_signals	outcome_signals_no_update	outcome_signals_no_delete

No row in either table may be modified or deleted after insertion. This invariant is enforced at the PostgreSQL level by BEFORE UPDATE and BEFORE DELETE triggers that raise exceptions. It cannot be bypassed by application code.

---

Enforcement

-- Implemented in Application/Schema.sql
CREATE TRIGGER interaction_events_no_update
    BEFORE UPDATE ON interaction_events
    FOR EACH ROW EXECUTE FUNCTION prevent_interaction_event_mutation();

CREATE TRIGGER interaction_events_no_delete
    BEFORE DELETE ON interaction_events
    FOR EACH ROW EXECUTE FUNCTION prevent_interaction_event_mutation();

-- Same pattern for outcome_signals

The trigger function raises:

"interaction_events is append-only: UPDATE and DELETE are not permitted"

---

Correction Policy

Erroneous events must not be corrected by modifying the original row. The correct approach is to insert a new event:

{
  "event_type": "retracted",
  "metadata": {
    "retracted_event_id": "<uuid of original event>",
    "reason": "incorrect actor attribution"
  }
}

The original event remains in the table. Downstream analysis should treat retracted events as markers that exclude the referenced event from calculations.

---

Failure Mode

Any attempt to UPDATE or DELETE a row in interaction_events or outcome_signals raises a PostgreSQL exception with SQLSTATE P0001. The calling transaction is aborted. No partial mutation is possible.

---

Scope

This contract applies only to interaction_events and outcome_signals.

Other append-oriented tables (triage_states, widget_ownerships, stewardship_roles) use the same conceptual pattern (soft expiry instead of update, no hard delete) but are not covered by DB-trigger enforcement. Their append semantics are enforced by application-layer controller conventions.

---

Phase 12 Addendum — Lineage Enrichment Trigger

Added in Phase 12 (IHUB-WP-0013 T06): outcome_signals now has an AFTER INSERT trigger trg_enrich_lineage that calls enrich_lineage_on_outcome().

This trigger:

• Is AFTER INSERT only — it never fires on UPDATE or DELETE.
• Does not modify outcome_signals — it only enriches upstream records (decision_records.outcome_summary, requirement_candidates.outcome_summary).
• Is consistent with the append-only invariant: the outcome_signals row itself remains immutable after insertion.

---

Implementation Reference

• Functions: prevent_interaction_event_mutation(), prevent_outcome_signal_mutation() in Application/Schema.sql
• Phase 12: enrich_lineage_on_outcome() — AFTER INSERT trigger on outcome_signals; enriches non-append-only columns on upstream tables only
• The architectural fitness function Test/Architecture/LayerBoundarySpec.hs (Test 1) verifies these trigger names are present in the schema