4.2 KiB
4.2 KiB
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).
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 Mongo (
notifications.pack_approvals) 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, Mongo 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 collection? Decision impacts Mongo design.
- Authority scopes for approval ingestion/ack — reuse
Packs.Approveor introducePacks.Approve:notify? Coordinate with Authority team.