Charon/docs/plans/current_spec.md

Active Plan: PR-0 Spec Correction Pass (Security Notifications Provider Events)

Date: 2026-02-20 Status: Active and authoritative (supersedes all prior appended sections in this file)

1) Scope and Intent

• This is a spec-only correction pass for compatibility, migration determinism, and rollout safety.
• Security notifications are provider-event subscriptions, not a single global destination.
• Notify-only runtime remains fail-closed; legacy fallback dispatch remains blocked.

2) Compatibility GET Aggregation Rules (Exact)

Compatibility endpoint in scope:

• GET /api/v1/notifications/settings/security

Aggregation source of truth:

• Active provider rows in notification_providers after filtering enabled=true and supported notify-only types.

Derived booleans (OR semantics):

• security_waf_enabled = OR(provider.notify_security_waf_blocks)
• security_acl_enabled = OR(provider.notify_security_acl_denies)
• security_rate_limit_enabled = OR(provider.notify_security_rate_limit_hits)

Deterministic conflict behavior when providers disagree:

• If any active provider has true for a category, compatibility GET returns true for that category.
• Returns false only when all active providers are false (or no active providers exist).
• Provider order never affects result.

Legacy destination reporting:

• If compatibility payload still includes destination, it is read-only compatibility metadata.
• destination is emitted only when exactly one active managed-legacy provider is in scope.
• If zero or more than one candidate exists, destination is returned as empty string and destination_ambiguous=true is set in compatibility metadata.

3) Compatibility PUT Translation Semantics (Exact)

Compatibility endpoint in scope:

• PUT /api/v1/notifications/settings/security

Deterministic target set:

• If one or more managed-legacy providers exist, target set is exactly that managed set.
• If none exist and request is valid, create one managed-legacy provider and use it as the target set.
• Non-managed providers are never mutated by compatibility PUT.

Translation mode: replace on managed set (not global merge)

• For each target provider, set security event booleans exactly to request values:
  • notify_security_waf_blocks = request.security_waf_enabled
  • notify_security_acl_denies = request.security_acl_enabled
  • notify_security_rate_limit_hits = request.security_rate_limit_enabled
• Existing non-security provider event booleans remain unchanged.
• Existing provider transport fields remain unchanged unless destination mapping applies (Section 5).

Idempotency:

• Repeating identical PUT payload produces no state drift and same compatibility GET output.
• Write timestamps may change only when effective values change.

Conflict handling:

• If target set cannot be resolved deterministically (for example data corruption with duplicate managed identity keys), return 409 Conflict and do not partially write.
• If request includes unsupported destination mapping shape, return 422 Unprocessable Entity and do not mutate providers.
• All compatibility PUT writes are transactional: all target providers updated or none.

4) Migration Marker Storage and Deterministic Re-Run

Marker storage:

• Table: settings
• Key: notifications.security_provider_events.migration.v1
• Value JSON schema:
  • version (string, fixed v1)
  • checksum (string, deterministic hash of legacy source fields used for migration)
  • last_completed_at (RFC3339 timestamp)
  • result (completed | completed_with_warnings)

Deterministic boot-time re-run behavior:

1. Read legacy source (notification_configs) and compute checksum.
2. Read migration marker.
3. If marker missing: run migration and write marker.
4. If marker exists with same checksum: skip mutation (no-op).
5. If marker exists but checksum differs: re-run migration in upsert mode, then replace marker.

Determinism constraints:

• Migration is pure over legacy source + managed provider key.
• Upsert key for managed provider is fixed identity managed_legacy_security=true plus name Migrated Security Notifications (Legacy).
• Re-run does not create duplicate managed providers.

5) Legacy Destination-to-Provider Mapping Rules

Supported destination mappings for compatibility PUT:

• webhook_url present:
  • map to provider type webhook, set endpoint URL from webhook_url.
• discord_webhook_url present:
  • map to provider type discord, set endpoint URL from discord_webhook_url.
• slack_webhook_url present:
  • map to provider type slack, set endpoint URL from slack_webhook_url.
• gotify_url + gotify_token present:
  • map to provider type gotify, set URL/token fields.

Unsupported/ambiguous destination handling (fail-safe):

• If multiple destination types are simultaneously present in one request, return 422.
• If destination type is unknown or incomplete for required fields, return 422.
• On 422, no provider rows are created/updated and compatibility state remains unchanged.

6) Feature Flag as Explicit Rollout Gate

Primary gate:

• feature.notifications.security_provider_events.enabled

Required defaults:

• Default in production: false
• Default in development/test: true

Behavior when flag is false:

• Provider-based security dispatch path is disabled.
• Compatibility GET/PUT remain available.
• Runtime dispatch uses compatibility translation path only.
• Managed migration may run in read-only dry-evaluate mode, but must not mutate providers.

Behavior when flag is true:

• Provider-based security dispatch is authoritative.
• Compatibility GET is derived projection from providers.
• Compatibility PUT writes managed set via translation semantics defined above.

Operational rule:

• This flag is mandatory for rollout and rollback; it is not optional/recommended.

7) Authoritative Plan Boundary and Cleanup

• This document is now the single authoritative plan for this scope.
• All previously appended certificate flaky-test and QA remediation sections are removed from active plan scope.
• Any future unrelated plan content must go to a separate plan file under docs/plans/.

8) PR Slicing Strategy

Decision: two PR slices.

• PR-0 (this pass): spec correction only in docs/plans/current_spec.md.
• PR-1: backend compatibility, migration marker, and feature-flag gate implementation.
• PR-2: frontend alignment and compatibility deprecation messaging.

9) Acceptance Criteria (Spec Pass)

1. Compatibility GET rules define exact OR aggregation and disagreement behavior.
2. Compatibility PUT defines deterministic target set, replace semantics, idempotency, and transaction/conflict behavior.
3. Migration marker key/storage and deterministic re-run logic are explicit.
4. Destination mapping rules cover supported non-webhook legacy forms and fail-safe unsupported behavior.
5. File contains one authoritative plan with stale duplicate trailing sections removed.
6. Feature flag is defined as explicit mandatory rollout gate with defaults and disable behavior.

10) Handoff

• Delegate PR-1 implementation to Supervisor using this plan as the sole baseline.