feat(queue): atomically enqueue audits with idempotency

[alirezasafaei-dev]

Scope

Implements Issue #78 Workstream A: one canonical, transactional path for creating new audit runs.

Canonical enqueue service

• creates AuditRun, ReportShare, durable Job, optional lead link, and optional UsageLedger in one Serializable Prisma transaction
• validates project/organization ownership inside the transaction
• rechecks monthly audit limits inside the transaction
• retries PostgreSQL serialization conflicts
• derives scoped, hashed idempotency keys
• stores source, fingerprint, run ID, and optional idempotency key in the durable job payload
• reuses a fully committed request and rejects reuse of the same key with different request material
• keeps committed enqueue success independent of non-critical funnel telemetry

Callers migrated

• public audit API
• authenticated project audit API
• admin lead start-audit route
• scheduled audit runner
• sample enqueue script

Migrations

1. 20260730_atomic_audit_enqueue
   • adds a partial unique PostgreSQL expression index for AUDIT_RUN jobs containing payload.idempotencyKey
   • existing jobs and retry jobs without an idempotency key are unaffected
2. 20260730_reconcile_organization_brand_columns
   • reconciles four nullable Organization branding fields present in Prisma schema/application code but absent from migration history
   • uses additive ADD COLUMN IF NOT EXISTS statements so clean databases and previously hand-reconciled environments converge safely

Regression and integration coverage

• one-transaction creation contract
• committed replay without writes
• idempotency conflict
• quota rejection before writes
• lead-link race and rollback
• transactional write-failure short circuit
• Serializable retry and usage exactly once
• deterministic source/scope key derivation
• lead route atomic/reuse/race behavior and non-critical telemetry failure
• real PostgreSQL concurrent identical enqueue: one run/share/job/usage
• real PostgreSQL concurrent different keys at quota boundary: exactly one accepted
• real PostgreSQL tenant mismatch with no side effects
• real PostgreSQL public run with no organization usage
• clean prisma migrate deploy plus explicit index verification

Validation evidence

Final head: e5c4398a4f2c9ef367d2c16e20b4d2567ff50175

• atomic-enqueue-postgres run 30545370750: success
  • clean PostgreSQL service
  • all migrations applied
  • idempotency index verified
  • 5/5 PostgreSQL integration tests passed
• main-gate run 30545370769: success
  • frozen install
  • tracked-source secret scan
  • pinned Actions verification
  • database-dump guard
  • release backup/rollback safety
  • automation hard gate (typecheck, lint, full tests, production build, automation/preflight)
  • /asdev and readiness smoke

Explicit non-scope

• no production deployment or migration execution
• queue lease fencing/heartbeat is implemented separately in the stacked Workstream B branch
• scheduler claim/lease, month-end recurrence policy, and schedule error state remain a separate P0/P1: Complete production hardening after runtime and nightly fixes #78 workstream
• admin retry of an existing failed run intentionally creates a new queue job without an idempotency key

Migration rollback

DROP INDEX IF EXISTS "Job_audit_enqueue_idempotency_key";
ALTER TABLE "Organization" DROP COLUMN IF EXISTS "secondaryColor";
ALTER TABLE "Organization" DROP COLUMN IF EXISTS "primaryColor";
ALTER TABLE "Organization" DROP COLUMN IF EXISTS "brandLogoBase64";
ALTER TABLE "Organization" DROP COLUMN IF EXISTS "brandName";

The Organization rollback is only safe after confirming those columns did not predate this migration in the target environment; production migration/rollback requires separate exact-SHA approval.

[alirezasafaei-dev]

Final validation completed for head e5c4398a4f2c9ef367d2c16e20b4d2567ff50175.

• PostgreSQL integration run 30545370750: success; clean migrate deploy, index verification, 5/5 transaction/concurrency tests.
• Main gate run 30545370769: success; secret scan, pinned Actions, dump guard, rollback safety, typecheck, lint, full tests, production build, automation/preflight, and local smoke.

No production migration or deployment was performed.