Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

Pack Approval Notification Integration — Requirements

Overview

Task Runner now produces pack plans with explicit approval and policy-gate metadata. The Notifications service must ingest those events, persist their state, and fan out actionable alerts (approvals requested, policy holds, resumptions). This document captures the requirements for the first Notifications sprint dedicated to the Task Runner bridge.

Deliverables feed Sprint 37 tasks (NOTIFY-SVC-37-00x) and unblock Task Runner sprint 43 (TASKRUN-43-001).

Implementation Status (2026-04-15)

The current ingestion endpoint is POST /api/v1/notify/pack-approvals in StellaOps.Notifier.WebService.
Approval state now persists durably in notify.pack_approvals, with ingest/ack idempotency coordinated through durable notify.locks.
Pack-approval ingest writes through the shared Notify audit/repository path rather than host-local in-memory stores.
Restart-survival proof now exists in StellaOps.Notifier.Tests.Integration.NotifierDurableRuntimeProofTests: it boots real Postgres + Redis, submits a pack-approval event, restarts the web host, leases/processes the queued event through the live NotifierEventProcessor, and reads the durable delivery back through /api/v2/notify/deliveries.
The proof harness uncovered and closed a real persistence bug in LockRepository (notify.locks first-acquire semantics), which is now covered by StellaOps.Notify.Persistence.Postgres.Tests.LockRepositoryTests.

Functional Requirements

1. Approval Event Contract

Define a canonical schema for PackApprovalRequested and PackApprovalUpdated events.
Fields must include runId, approvalId, tenant context, plan hash, required grants, step identifiers, message template, and resume callback metadata.
Provide an OpenAPI fragment and x-go/x-cs models for Task Runner and CLI compatibility.
Document error/acknowledgement semantics (success, retryable failure, validation failure).

2. Ingestion & Persistence

Expose a secure Notifications API endpoint (POST /notifications/pack-approvals) receiving Task Runner events.
Validate scope (packs.approve, Notifier.Events:Write) and tenant match.
Persist approval state transitions in PostgreSQL (notify.pack_approvals table) with indexes on run/approval/tenant.
Store outbound notification audit records with correlation IDs to support Task Runner resume flow.

3. Notification Routing

Derive recipients from new rule predicates (event.kind == "pack.approval").
Render approval templates (email + webhook JSON) including plan metadata and approval links (resume token).
Emit policy gate notifications as “hold” incidents with context (parameters, messages).
Support localization fallback and redaction of secrets (never ship approval tokens unencrypted).

4. Resume & Ack Handshake

Provide an approval ack endpoint (POST /notifications/pack-approvals/{runId}/{approvalId}/ack) that records decision metadata and forwards to Task Runner resume hook (HTTP callback + message bus placeholder).
Return structured responses with resume token / status for CLI integration.
Ensure idempotent updates (dedupe by runId + approvalId + decisionHash).

5. Observability & Security

Emit metrics for approval notifications queued/sent, outstanding approvals, and acknowledgement latency.
Log audit trail events (pack.approval.requested, pack.approval.acknowledged, pack.policy.hold).
Enforce HMAC or mTLS for Task Runner -> Notifier ingestion; support configurable IP allowlist.
Provide chaos-test plan for notification failure modes (channel outage, storage failure).

Non-Functional Requirements

Deterministic processing: identical approval events lead to identical outbound notifications (idempotent).
Timeouts: ingestion endpoint must respond < 500 ms under nominal load.
Retry strategy: Task Runner expects 5xx/429 for transient errors; document backoff guidance.
Data retention: approval records retained 90 days, purge job tracked under ops runbook.

Sprint 37 Task Mapping

Task ID	Scope
NOTIFY-SVC-37-001	Author this contract doc, OpenAPI fragment, and schema references. Coordinate with Task Runner/Authority guilds.
NOTIFY-SVC-37-002	Implement secure ingestion endpoint, PostgreSQL persistence, and audit hooks. Provide integration tests with sample events.
NOTIFY-SVC-37-003	Build approval/policy notification templates, routing rules, and channel dispatch (email + webhook).
NOTIFY-SVC-37-004	Ship acknowledgement endpoint + Task Runner callback client, resume token handling, and metrics/dashboards.

Open Questions

Who owns approval resume callback (Task Runner Worker vs Orchestrator)? Resolve before NOTIFY-SVC-37-004.
Should approvals generate incidents in existing incident schema or dedicated table? Decision impacts PostgreSQL schema design.
Authority scopes for approval ingestion/ack — reuse packs.approve or introduce packs.approve:notify? Coordinate with Authority team.