Implement durable event ingestion service

workplans/AUDIT-WP-0003-user-engine-event-ingestion-service.md

@@ -0,0 +1,98 @@
+---
+id: AUDIT-WP-0003
+type: workplan
+title: "Provide durable user-engine event ingestion"
+domain: infotech
+repo: audit-core
+status: active
+owner: codex
+topic_slug: netkingdom
+created: "2026-08-08"
+updated: "2026-08-08"
+depends_on:
+  - NK-WP-0024
+state_hub_workstream_id: "d2726f51-2beb-4c6b-96c4-98d29d11a93f"
+---
+
+# AUDIT-WP-0003 - user-engine event ingestion service
+
+Provide the authenticated, durable cluster event receiver for user-engine's
+transactional outbox. Reuse audit-core's intended POST /v1/events boundary;
+do not turn user-engine into an audit-retention service.
+
+## T01 - Finalize the ingestion contract
+
+```task
+id: AUDIT-WP-0003-T01
+status: done
+priority: high
+state_hub_task_id: "620a6910-60d6-4ef0-b82b-37eacb2fcf1d"
+```
+
+Map the user-engine envelope fields (id, type, source, subject, tenant,
+correlation_id, occurred_at, data) into the normalized audit-core event
+schema. Define validation, redaction, size limits, tenant isolation,
+Idempotency-Key behavior, and stable HTTP error semantics.
+
+Done when valid events preserve correlation and duplicate event IDs are
+accepted idempotently without duplicate custody records.
+
+Done 2026-08-09: the normalized contract preserves event, tenant, correlation,
+occurrence, source, subject, type, and redacted data; request size, timestamp,
+source, secret-shaped fields, and Idempotency-Key are validated.
+
+## T02 - Implement authenticated durable ingestion
+
+```task
+id: AUDIT-WP-0003-T02
+status: done
+priority: high
+state_hub_task_id: "a6fce44e-8977-47f0-8a75-9ce431cc27a6"
+```
+
+Implement POST /v1/events with scoped workload authentication, schema
+validation, idempotency storage, bounded request handling, and durable backend
+write acknowledgment. Reject missing/invalid credentials, cross-tenant
+claims, secret-shaped fields, oversized payloads, and malformed timestamps.
+
+Done when a successful response means the event is durably accepted and
+retryable failures do not lose or duplicate evidence.
+
+Done 2026-08-09: `POST /v1/events` requires a constant-time bearer check and
+stores normalized records plus payload hashes in SQLite. Exact duplicates
+return 200 without a second record; conflicting IDs and malformed events fail.
+All 15 repository tests pass.
+
+## T03 - Deploy the single-cluster receiver
+
+```task
+id: AUDIT-WP-0003-T03
+status: progress
+priority: high
+state_hub_task_id: "fc0b5850-1954-448c-8729-ffe93d7b530f"
+```
+
+Publish an immutable image and deploy audit-core API plus durable backend on
+railiance01. Provide Service discovery, health probes, resource/security
+controls, default-deny NetworkPolicy, backup/restore, retention, and rollback.
+Deliver the user-engine sender credential through the approved OpenBao lane.
+
+Done when only the user-engine workload can use its sender identity and the
+receiver survives pod restart without losing idempotency state.
+
+## T04 - Prove delivery, retry, and replay
+
+```task
+id: AUDIT-WP-0003-T04
+status: todo
+priority: high
+state_hub_task_id: "8d1624de-3e71-41c9-80ac-ab522313a0da"
+```
+
+Exercise successful delivery, receiver timeout/unavailability, bounded
+user-engine retry, dead-letter visibility, operator replay, duplicate replay,
+redaction, and correlation lookup through the deployed path. Hand non-secret
+evidence back to NK-WP-0024.
+
+Done when one source outbox event produces exactly one durable normalized
+event across retries and replay.