[Silthus]

Merge gate: passed. fleet proof gate passes on e7a3351 (live run, review at HEAD, CI green, judge fail accepted by standing rule). Layer 2 of 4 in the node-store attachment stack: #133482, this PR, #133495, then #131944. The stack merges from its top PR; #131567 is live in both regions and the env settings are merged.

Problem

• A developer sending files with a transactional email needs a place to upload them before the send names them (PostHog/michaelr-context#77).
• cdp-api has no route that hands out upload URLs.

Note

🟡 Merge risk: medium · two-way door

• A new cdp-api route; every team gets field_not_accepted while the allowlist stays empty.
• Switch-off: empty CDP_EMAIL_ATTACHMENTS_TEAMS; fix forward.

Changes

• POST /api/projects/{team_id}/transactional_email/attachments/uploads answers each file present or upload with a signed PUT.
• Order: scoped token with its own attachment_upload kind, allowlist, 1 to 10 files, the 40 MB message estimate, then the store.
• A team's upload bytes per UTC day are counted in Redis when the route issues upload URLs, not when files are stored; over the cap it gets 429 upload_quota_exceeded. Present files and refused requests do not count.
• A store or Redis outage answers 503 delivery_unavailable and logs a warning with the team and the error.
• Every request lands on cdp_email_attachments_upload_requests_total by outcome, including unauthorized and not_configured, so a token mismatch with Django shows up.

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 upload route, AttachmentUploads.prepare, in the upload span of the flow above.
• Before, cdp-api had no route that hands out upload URLs, so a send had no stored file to name.
• Now, the caller sends each file's sha256 and size, and cdp-api answers present or a PUT URL signed for that size and hash.
• The bucket key is the hash, and the bucket checks the hash on the PUT, so a send can name a file by hash alone.
• A file counts as present only with a day and 15 minutes left, longer than the 15 minutes an upload URL lives.
• One Redis script adds and checks a team's daily upload bytes, so concurrent requests cannot pass the cap.

How did you test this code?

• The tests run outside-in: the route over real HTTP, through the internal-auth exemption from feat(cdp): let the attachment upload route through without the internal api secret #133482, against the dev bucket and Redis, including the cross-team case. Seven mutation checks each fail a test.
• A cdp-api built from its settings answers uploads with the idempotency Redis as its counter, and 503 without it.
• A burst of concurrent requests near the daily cap lets the one that fits through and refuses the rest.
• Live run, real cdp-api over HTTP with the dev bucket and Redis: upload, present, another team, each refusal, the daily cap, and a 503 with its warning when object storage is unreachable. The request metric counts every outcome.
• Not run: a production read of the stored files and quota counters. Nothing writes either before this stack deploys, and the allowlist stays empty after it, so the post-deploy watch takes the first read.

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 token may ask for upload URLs?	Only one with kind attachment_upload	🤖 Agent	PostHog/michaelr-context#77
What if the upload counter cannot be read?	503 delivery_unavailable, so the cap holds	🤖 Agent	PostHog/michaelr-context#77
Deduplicate a charge replayed on reconnect?	No; a rare replay over-charges once and fails toward the cap	🤖 Agent	PostHog/michaelr-context#77
Bound how many uploads a team may prepare at once?	No; the store calls carry timeouts, the daily cap holds, and the Django route adds the team's throttles	🤖 Agent	PostHog/michaelr-context#77
Size a send by the declared or the stored file size?	The stored size, read from the store at send time	🤖 Agent	PostHog/michaelr-context#77
Read production storage before merge?	No; nothing writes it until this stack deploys, so the post-deploy watch reads it first	🤖 Agent	PostHog/michaelr-context#77

Involvement: 8 cross-model review rounds and 2 final reads (GPT-6.1 Sol panel, Opus fresh eyes), one full qa-swarm plus the stack-tip pass, PostHog Review on each head (no findings on the final head); live run captured. CodeRabbit is retired and skipped.

More context for AI agents

• Session: T3 stack thread for PostHog/michaelr-context#77, Claude Code.
• Decisions: the shared-secret exemption for this route moved down into feat(cdp): let the attachment upload route through without the internal api secret #133482, so the auth surface gets its own code-owner review.
• Follow-ups: the send with references (feat(cdp): let a caller bound hog and liquid rendering with a deadline #133495, feat(cdp): send transactional email files by reference #131944); the Django route that mints the upload token.
• Read closely: AttachmentUploads.answer and chargeDailyUploadBytes in attachment-uploads.ts.

🤖 Generated with Claude Code

[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.

✅ Comment density — 0% of added code lines are comments (0 of 453)

This section warns when comments are more than 3% of the code lines a PR adds, and alerts above 6%. Before agent-assisted PRs, the typical share was about 2%. Only full-line comments count. Docstrings, generated files, snapshots, migrations, and workflow files are left out.

Comments that restate the code, record how the change came about, or narrate the next line add noise for the next reader. Keep the comments that explain a reason the code cannot show, and remove the rest. See .agents/skills/writing-code-comments/SKILL.md for the house rules.

This check does not block merging. It updates on every push and clears when the share drops.

[trunk-io]

Merging to master in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[trunk-io]

This pull request is queued for merge as part of 131944, which will merge 133482, 131833, 133495, 131944.

[trunk-io]

This pull request was merged into master as part of stacked PR 131944.

[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.}