Story 1503: document_ingest_outbox — transactional outbox + relay (FN-OUTBOX)

Why this exists (the catastrophe it prevents). When a lawyer finalizes an upload, two things must happen: the document's status changes to uploaded, and the ingestion pipeline (scan → extract → classify, EPIC-009) must be told to start. The naive way — write the status change, commit, then call SQS — has a fatal gap: if the process dies between the commit and the enqueue, the document is forever uploaded with no job. The file sits in S3, the register shows it, and nothing ever processes it. The inverse (enqueue first, then write the row) is just as bad: a job for a document whose status never committed. A dropped document in a litigation matter is evidence that silently never enters the case. This story closes the gap with a transactional outbox: the job ticket is written in the same database transaction as the status change, so the two commit or roll back together — never one without the other.

The shape: one row in the same txn, one relay to the queue

A new operational table ops.document_ingest_outbox holds one ticket per ingest request. DocumentService.finalize_upload inserts the ticket on the caller's open session, right after the status transition to uploaded. A separate relay Lambda later drains undispatched tickets to the ingest queue and stamps each row dispatched_at.

finalize_upload (ONE transaction):
    Document.status = 'uploaded'                    # the status change
    record_status_transition('pending' -> 'uploaded')
    insert_document_ingest_event(...)               # the outbox ticket
    emit('document.uploaded')                        # audit row
    -- commit: all four, or none --

relay (later, separate Lambda):
    SELECT ... WHERE dispatched_at IS NULL FOR UPDATE SKIP LOCKED
    client.enqueue(pointer envelope)  ->  SQS
    UPDATE SET dispatched_at = now()

The queue message is a pointer, never bytes: {document_id, firm_id, matter_id, object_key, content_type}. The worker fetches the S3 object itself and computes checksum_sha256 at the stored transition (EPIC-009). SQS's 256 KB limit is irrelevant to file size because the file never rides the queue.

Crash-safety invariant

Idempotent transitions

Two layers make re-runs safe. The insert uses ON CONFLICT (firm_id, idempotency_key) DO NOTHING and returns the existing row, so a redelivered finalize never enqueues a second job. The relay marks dispatch with UPDATE ... WHERE event_id = :id AND dispatched_at IS NULL and counts a success only when rowcount == 1, so two relays racing the same row (or a redelivered SQS message) converge on one dispatch. On a FIFO queue the envelope's idempotency_key is also the MessageDeduplicationId.

Tenancy & tamper-evidence

RLS mirrors ops.projection_outbox (0064): firm_isolation_policy (firm members touch only their firm's rows) plus relay SELECT/UPDATE policies gated on app.is_staff_or_false(). The app role is granted SELECT, INSERT, UPDATE with DELETE revoked — the outbox is a ledger, not a scratchpad. The new firm-scoped table is registered in the support-confidentiality allowlist so on-duty support (config scope, no content grant) sees zero rows.

Observability (pramaan-docs ADR-124)

The enqueue and the relay batch are genuine queue boundaries, so each gets a registry-approved manual span — functions.document_ingest_outbox.enqueue (PRODUCER) and functions.document_ingest_relay.batch (CONSUMER) — added to the closed ManualSpanName registry beside the projection-outbox pair they mirror. Span attributes are metadata only (firm_id, matter_id, batch count) — never object content. The relay links each batch span to the stored traceparent of the rows it drains, and emits pramaan.document_ingest_relay.duration with a non-fatal failure boundary. No raw tracer calls.

Acceptance evidence