[Silthus]

Merge gate: passed. fleet proof gate passes on 6be27df (live run, prod shape, cross-version, shadow diff, review at HEAD, CI green, judge fail accepted by standing rule). Layer 4 of 4 in the node-store attachment stack: #133482, #131833, #133495, then this PR. The stack merges from its top PR; #131567 is live in both regions and the env settings (PostHog/michaelr-context#76) are merged.

Problem

• A developer sending a transactional email from code cannot attach the files they uploaded (PostHog/michaelr-context#77).
• The upload route (feat(cdp): add the upload route for transactional email files #131833) stores files, but the code-send route has no way to name them, size the message, or refuse one that SES would reject.

Note

🟡 Merge risk: medium · two-way door

• The code-send route in cdp-api; every send with files is refused with field_not_accepted while the allowlist stays empty. Sends without files queue the same state as before.
• A keyed send also stores attachment_count and attachment_bytes on its idempotency record, which expires after 24 hours; an older pod ignores both on replay.
• Switch-off: empty CDP_EMAIL_ATTACHMENTS_TEAMS; fix forward.

Changes

• A code send takes attachments as references (sha256, filename, optional content_type and content_id) to files the team uploaded.
• A team off the allowlist gets 400 field_not_accepted before its idempotency key is reserved.
• A send with files must use a workflow of trigger, one transactional email step, then exit. Any other shape gets 400 workflow_shape_not_supported; an email step the frequency cap can hold, or a workflow under a sending rate limit, gets 400 workflow_can_wait. Both name the step and the fix.
• A reference SES would refuse gets 400 invalid_request naming the field: a filename over 255 characters, a content_type or content_id outside 1 to 78, or a file type on the SES unsupported list.
• Each file is verified under the caller's team and kept for 7 days. A missing one gets 400 attachment_not_uploaded with its sha256.
• The 40 MB estimate counts the files, the bodies and the subject: the send's content, or the email step rendered with the recipient's person and the event's groups, the way the worker renders it. Over the limit: 400 message_too_large with the byte totals. The email worker checks the same estimate before SES.
• An email step with a custom UTM value over 1,000 characters gets 400 utm_value_too_long. One with more than 10,000 Liquid tags across its templated fields gets 400 email_body_too_many_tags. Both are refused before anything parses the value, because LiquidJS parse time grows with the square of the tag count. Sends without files are not checked.
• A template that goes over the render limits gets 400 email_render_limit_exceeded. A store outage, or a failed person or template lookup, answers 503 delivery_unavailable.
• File checks and sizing share one deadline, half the Django facade's 10 s timeout. Past it: 503 and nothing queued. No Hog or Liquid input renders after the answer, even one waiting for its turn on the event loop; the render deadline itself comes from feat(cdp): let a caller bound hog and liquid rendering with a deadline #133495.
• A keyed retry of a send that queued replays its 202 before the workflow's shape is checked, so a workflow changed since does not report an accepted email as failed.
• Every refusal after the reservation releases the key, so a retry with the same key can send.
• The queued run carries each file's metadata, no bytes. The 202 of both send routes answers attachment_count and attachment_bytes.

How it works

---
title: Upload, then send
---
sequenceDiagram
    participant C as caller
    participant A as cdp-api
    participant B as bucket
    participant W as email worker
    rect rgba(9, 105, 218, 0.15)
    Note over C,B: upload #35;131833
    C->>A: sends the sha256 and size of each file
    A->>B: HEADs team/<id>/<sha256>
    A-->>C: answers present, or a PUT URL signed for that size and hash
    C->>B: PUTs the bytes
    end
    rect rgba(26, 127, 55, 0.15)
    Note over C,B: send #35;131944
    C->>A: sends, naming each file by its sha256
    A->>B: HEADs each file, copies any with under 7 days left
    A-->>C: answers 202 and queues a job without bytes
    end
    W->>B: GETs each file by sha256, at most 6 days later

Loading

• This PR acts on cdp-api's code-send handler in cdp-api.ts and on AttachmentUploads.acceptForSend, in the send span of the flow above.
• Before, the code-send schema had no attachments field, so a send that named files got 400 invalid_request.
• Now, a send names uploaded files by sha256. cdp-api HEADs each file, sizes the message, and queues a job that holds file metadata and no bytes.
• acceptForSend copies any file with under 7 days left, so a file's expiry only moves later.
• The worker gives up on a send after 6 days of waiting for room, so the files outlive the job.
• File checks and sizing share one 5 s deadline. A refusal after the idempotency key is reserved releases the key.

How did you test this code?

• The tests run outside-in over real HTTP against the dev bucket and Redis, and cover every refusal, key release, a replay after the workflow changed, the rendered and person-dependent estimate, and the deadline, including a person lookup that outlasts it and a Hog render that waits past it. Each mutation check fails a test.
• End to end at the stack tip, Django → cdp-api → email queue → email worker → maildev, with Django's facade from feat(messaging): attach uploaded files to key sends by their hash #131763 forwarding content_type and content_id: sends with files deliver with their files intact, an inline image keeps its cid: reference and Content-ID, and each refusal answers synchronously through Django's facade with nothing queued, a rate-limited workflow included.
• Shadow diff against feat(cdp): add the upload route for transactional email files #131833 for sends without files: queued rows identical; the only differences are the two new 202 fields and attachments: [] now accepted.
• Cross-version: an older email worker fails a job with files as attachments_missing before SES, so no email goes out without its files. An older cdp-api refuses attachments with 400 invalid_request, even on a retry of a key this head stored, so the allowlist stays empty until every pod runs this head. Idempotency keys replay across versions for sends without files.
• Live run over real HTTP: a 700,000-character UTM value and a body or subject of 100,000 tags are refused in milliseconds without blocking the event loop. A send without files with the same body queues, and tags in the editor's design state are not counted.
• Production shape, US and EU: read-only counts of the workflows and person references this head reads at accept. No stored email step comes near either new cap.
• The proof captures stay in a private proof store, because they hold production counts. This section summarizes them.

Release status

• No feature flag controls this change

Docs update

• None.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Agent: Claude Code, Claude Opus 5.5

Skills: /writing-tests, /writing-code-comments, /writing-pr-descriptions, /stacking-prs

Question	Answer	Who	Where
Which workflows may carry files?	Trigger, one transactional email step, exit; every other shape, a frequency cap that can hold the email, and a sending rate limit are refused at accept, so nothing can delay or reshape the email	🤖 Agent	PostHog/michaelr-context#77
Whose data renders the body for sizing?	The recipient's person and the event's groups, resolved at accept the way the worker resolves them	🤖 Agent	PostHog/michaelr-context#77
Where does the allowlist gate run?	Right after validation, before the team load and the key reservation	🤖 Agent	PostHog/michaelr-context#77
When is the workflow's shape checked?	After the idempotency replay, so a retry of a queued send replays even when the workflow changed since; a refusal releases the key	🤖 Agent	PostHog/michaelr-context#77
An email step that fails to render at accept?	Over a template limit: 400 email_render_limit_exceeded. Any other render error counts as no body and queues; the worker fails it the same way	🤖 Agent	PostHog/michaelr-context#77
How long may accept check files?	Half the Django facade's 10 s timeout, then 503 with nothing queued and no render started after the answer	🤖 Agent	PostHog/michaelr-context#77
Does message_too_large name a file?	No, the whole send is too large; it carries the byte totals	🤖 Agent	PostHog/michaelr-context#77
The same file referenced twice?	Counted twice, because the message carries it twice	🤖 Agent	PostHog/michaelr-context#77

Involvement: 4 cross-model review rounds and 24 final reads (GPT-6.1 Sol, Opus fresh eyes), one full qa-swarm plus the stack-tip pass, PostHog Review on each head; live run, end-to-end, shadow-diff, cross-version and production-shape proofs captured. CodeRabbit is retired and skipped.

More context for AI agents

• Session: T3 stack thread for PostHog/michaelr-context#77, Claude Code.
• Decisions: the render deadline plumbing moved down into feat(cdp): let a caller bound hog and liquid rendering with a deadline #133495 to keep each layer under the review size limit; this PR holds its callers.
• Follow-ups: scheduled-send expiry (waits for feat(cdp): park a transactional send until its scheduled_at #128881 and feat(cdp): cancel or move a scheduled send before a worker claims it #128929); the Django facade consumes the byte totals and maps each refusal code.
• Read closely: the attachments block of the code-send handler and messageBodyBytes in cdp-api.ts, files-workflow-shape.ts, hogflow-person.ts, and acceptSend in attachment-uploads.ts.

🤖 Generated with Claude Code

[Silthus]

@PostHog review

[posthog]

@Silthus PostHog Review is reviewing this pull request.

[github-actions]

🤖 CI report

✅ Trunk lane — non-backend lane

This PR is assigned to the non-backend lane. It does not run backend Python tests and may merge in parallel with PRs in other lanes.

✅ Duplication (Python) — clean

New Python code duplication introduced by this branch. Fails at 70+ tokens in app code, or 150+ tokens when both copies live in test files. Advisory while the gate proves itself: extract a shared helper instead of copying.

✅ Duplication (TypeScript) — clean

New TypeScript code duplication introduced by this branch. Fails at 70+ tokens in app code, or 150+ tokens when both copies live in test files. Advisory while the gate proves itself: extract a shared helper instead of copying.

[posthog]

PostHog Review · Standard · reviewed 941f437: 2 Should fix.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

[Silthus]

@PostHog review

[posthog]

@Silthus PostHog Review is reviewing this pull request.

[posthog]

PostHog Review · Standard · reviewed 9048e0e: 2 Should fix.

[Silthus]

@PostHog review

[posthog]

@Silthus PostHog Review is reviewing this pull request.

[posthog]

PostHog Review · Standard · reviewed 08e2006: 1 Should fix.

This is review round 3 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

[Silthus]

@PostHog review

[Silthus]

@PostHog review

[Silthus]

@PostHog review

New commits were pushed — dismissing the stamphog approval from an earlier head. Re-add the trigger label to request a fresh review.

[posthog]

PostHog Review · Standard · reviewed 6be27df: 1 Must fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

This is review round 18 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

[posthog]

PostHog Review · Standard · reviewed 65c95f5: 1 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

This is review round 19 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

[Silthus]

/trunk merge

[trunk-io]

😎 Stack merged successfully - details.

[deployment-status-posthog]

Deploy status

Environment	Status	Deployed At	Workflow
dev	✅ Deployed	2026-11-11 16:27 UTC	Run
prod-us	✅ Deployed	2026-11-11 18:14 UTC	Run
prod-eu	✅ Deployed	2026-11-11 17:23 UTC	Run

_{This table shows the posthog release only. Hogstation shows every service that this PR reaches, Kargo services included.}