--- id: e5-decision-support-layer title: Decision Support Layer module: GROW-S5 module_slug: grow-s5-sensor-fusion-data-ops cluster: Execution type: spec version: v0.1.0 status: Gate-reviewed tier: membership contract_role: "" canonical_url: "https://grow.goodcombinator.ai/library/registry/e5-decision-support-layer" download_url: "https://grow.goodcombinator.ai/library/registry/e5-decision-support-layer.md" license: CC-BY-4.0 (proposed — owner confirmation required) source: GROW by Good Combinator retrieved_at: 2026-05-29 --- # Decision Support Layer Spec The Decision Support Layer is the final translation stage between fused telemetry and agent or human action. It converts a `fused_record` from `e5-fusion-logic-map` plus fired alerts from `e5-alert-design-spec` into concrete recommendations, autonomous triggers, or escalation requests — and it preserves the full evidence chain in `s3-provenance-metadata-schema` so that every decision can be traced back to the sensor readings that caused it. Critically, this layer blocks action on weak signals: any recommendation derived from a fused record with `confidence_band: low` or `unknown` is quarantined until a human reviews it, using `s1-threshold-escalation-spec` as the gate authority. This prevents a degraded sensor network from silently driving consequential actions. --- ## 1. Layer Responsibilities 1. **Recommendation generation.** Translate a fused telemetry state into a structured recommendation for an agent or human operator. 2. **Signal-strength gate.** Block or quarantine recommendations when the underlying fused record falls below the declared confidence threshold for the decision class. 3. **Evidence preservation.** Write a provenance record to `s3-provenance-metadata-schema` for every recommendation, trigger, or blocked action. 4. **Action dispatch.** Route approved recommendations to the correct agent action or escalation channel. 5. **Audit surface.** Maintain a queryable log of all decisions, their confidence basis, and their outcomes for operator review and S2 evaluation. --- ## 2. Decision Classes A decision class is a named category of output this layer can produce. Each class has a declared minimum `confidence_band` required, a reversibility class, and an S1 gate requirement. | decision_class | Description | min_confidence_band | reversibility | S1 gate required | |---|---|---|---|---| | `monitoring-log` | Append observation to monitoring log; no operational action | `low` | reversible | None | | `status-update` | Update the operational dashboard or status page | `low` | reversible | None | | `operator-notify` | Push a structured notification to an operator queue | `medium` | reversible | Async post-hoc review | | `agent-trigger` | Initiate an autonomous agent task (e.g., schedule a sensor maintenance check) | `medium` | reversible | Async post-hoc review | | `escalation-request` | Route to human escalation tier per `s1-threshold-escalation-spec` | `medium` | reversible | HITL gate (Tier 1/2/3 per severity) | | `physical-action-recommendation` | Recommend a physical intervention requiring human authorization | `high` | irreversible | HITL gate mandatory | No `physical-action-recommendation` is ever dispatched autonomously. It is always staged as a human-readable proposal requiring explicit approval, consistent with the irreversible-impact boundary in `s1-fallback-architecture-blueprint`. --- ## 3. Signal-Strength Gate Every recommendation passes through a signal-strength gate before dispatch. The gate applies `s1-threshold-escalation-spec` logic to the fused record's `confidence_band`. ``` gate outcome = f(decision_class.min_confidence_band, fused_record.confidence_band) ``` | fused confidence_band | decision_class min = low | decision_class min = medium | decision_class min = high | |---|---|---|---| | `high` | PASS — dispatch | PASS — dispatch | PASS — dispatch | | `medium` | PASS — dispatch | PASS — dispatch | HOLD — quarantine for HITL | | `low` | PASS — dispatch | HOLD — quarantine for HITL | HOLD — quarantine for HITL | | `unknown` | HOLD — halt run | HOLD — halt run | HOLD — halt run | **HOLD** means the recommendation is written to the provenance store with `status: quarantined` and routed to the operator review queue. The agent does not invent a substitute decision and does not act autonomously. **HALT** (triggered by `confidence_band: unknown`) means the decision layer emits a `low-confidence-routing` failure mode event per `s1-failure-mode-register` and stops the current decision run. No recommendation is produced. The operational state is frozen at the last `non-unknown` fused view. --- ## 4. Recommendation Schema ```yaml recommendation: recommendation_id: decision_class: alert_id: fused_record_ref: measurement_type: fusion_window_end_utc: fused_value: unit: confidence_band: confidence_score: gate_outcome: gate_rule_applied: <"min-band-gate" | "unknown-halt"> recommended_action: suggested_fallback: decision_origin: sensor-triggered evidence_pointer: timestamp_utc: status: ``` `decision_origin: sensor-triggered` is the extended v0.2.0 glossary value locking this as a telemetry-initiated decision. S3 consumers that are base-enum-only treat it as `agent` per the backward-compatibility rule in `glossary`. --- ## 5. Evidence Preservation Every recommendation — whether dispatched, quarantined, or halted — generates a provenance record in `s3-provenance-metadata-schema`. This is non-negotiable. A dispatched recommendation without a provenance record is a gate-failing provenance violation. ### 5.1 Provenance record shape ```yaml provenance_record: record_id: timestamp_utc: agent_id: decision_origin: sensor-triggered evidence_pointer: rationale: > ``` The `evidence_pointer` resolves to a stored bundle containing: - The `fused_record` (from `e5-fusion-logic-map`) - The fired `alert` payload (from `e5-alert-design-spec`) - The C6 emission record - The gate outcome record - The normalized source records that contributed to the fused value Heavy payloads (full sensor records) use the `{ref, hash, field}` hash-and-ref pattern from C5/C3 — they are not inlined into the provenance record. ### 5.2 Quarantine provenance A HOLD outcome writes a quarantine record with `status: quarantined` and the reason (`min-band-gate`). When a human reviewer acts on a quarantined recommendation, their decision is recorded as a separate provenance record with `decision_origin: human-override` or `escalation`, linked to the quarantine record via a shared `correlation_id`. --- ## 6. Action Dispatch After a PASS gate outcome, the recommendation is dispatched to the appropriate channel: | decision_class | Dispatch target | |---|---| | `monitoring-log` | Append to the pipeline monitoring log store | | `status-update` | Write to the operational dashboard state store | | `operator-notify` | Push structured JSON to the operator notification queue | | `agent-trigger` | Emit a trigger event to the declared agent workflow endpoint | | `escalation-request` | Route to the S1 HITL review queue per tier; emit C6 payload | | `physical-action-recommendation` | Stage in the human-approval queue; never auto-dispatch | All dispatch actions are logged. A dispatch failure (queue unavailable, webhook timeout) applies the `s1-fallback-architecture-blueprint` retry policy and escalates if retries are exhausted. --- ## 7. Blocking Rules The following conditions block any dispatch regardless of gate outcome: 1. **`confidence_band: unknown` in the fused record.** Halt the decision run entirely. 2. **The recommendation carries `decision_class: physical-action-recommendation` and no human has pre-authorized it.** Stage only; never dispatch. 3. **The alert it references has `suppression_applied: true`.** A suppressed alert cannot drive a downstream dispatch. Log the attempted dispatch as a `suppression-bypass-blocked` event. 4. **The `fused_record.stale_sources` list contains the sole authoritative source for the measurement type.** Downgrade to `monitoring-log` class if the original class was `operator-notify` or higher; log the demotion. --- ## 8. Worked Example — Escalation from Rising Water Level (illustrative) **Inputs:** - `fused_record`: `measurement_type: water-level`, `fused_value: 1.03 m`, `confidence_band: medium`, `fusion_window_end_utc: 2026-05-29T19:33:00Z` - Fired alert: `rule_id: pond-level-high`, `severity: high`, `suggested_fallback: increase-monitoring-frequency` **Signal-strength gate:** - `decision_class: escalation-request`, `min_confidence_band: medium` - Fused band = `medium` → gate outcome = PASS **Recommendation produced:** ```yaml recommendation: recommendation_id: a4f2e1d3-0b9c-4a7f-8e6d-2c1b5a3f7e9d decision_class: escalation-request alert_id: fused_record_ref: measurement_type: water-level fusion_window_end_utc: "2026-05-29T19:33:00Z" fused_value: 1.03 unit: meters above NAVD88 confidence_band: medium confidence_score: 0.72 gate_outcome: pass gate_rule_applied: min-band-gate recommended_action: > Notify district clerk (Tier 2) that stormwater pond level has reached 1.03 m NAVD88, above the 1.00 m advisory threshold. Recommend initiating visual inspection of pond berm and downstream culvert capacity. suggested_fallback: increase-monitoring-frequency decision_origin: sensor-triggered evidence_pointer: "s3://provenance-store/sensor-fusion/2026-05-29/a4f2e1d3.json" timestamp_utc: "2026-05-29T19:33:05Z" status: dispatched ``` **Provenance record written to `s3-provenance-metadata-schema`:** ```yaml record_id: timestamp_utc: "2026-05-29T19:33:05Z" agent_id: ecoguardian-30a-fusion decision_origin: sensor-triggered evidence_pointer: "s3://provenance-store/sensor-fusion/2026-05-29/a4f2e1d3.json" rationale: > Fused water-level reading of 1.03 m (confidence: medium) crossed the pond-level-high threshold; Tier 2 operator escalation dispatched per s1-threshold-escalation-spec. ``` The district clerk receives the operator-notify. If the clerk confirms action is required, they record a `human-override` event. If they determine the reading is a sensor artifact and dismiss it, that dismissal is also a provenance record — the decision history is complete regardless of outcome. --- ## 9. Versioning Adding a new `decision_class` is MINOR. Changing the signal-strength gate thresholds (the PASS/HOLD table in §3) is MINOR but requires re-evaluation of the recommendation log for any decisions that would change outcome. Removing a decision class or changing the provenance record shape is MAJOR, governed by `interface-contracts` and coordinated with `s3-provenance-metadata-schema`.