[Silthus]

Problem

• Developers who move from Resend schedule an email up to 30 days ahead with scheduledAt. PostHog's transactional email send has no way to wait, so they need a timer of their own (Silthus/personal#303, spec Silthus/personal#302).

Note

🔵 Merge risk: low · two-way door until Django exposes scheduled_at to customers

• Sends without scheduled_at, in US and EU, go out as before: the live run and the N2 worker cross-version run cover them, with and without files.
• Only a caller that sets scheduled_at changes, and none does until Django's flagged stack ships. No stored job carries the new key (prod-shape, both regions).
• Switch-off: none: live on deploy, fix forward.

Merge first: #127745, which adds the recipient to status rows, then #128871 and #128868.

Landing: #129915 merges alone and its migration runs in US and EU first. #127745 merges next. Then one /trunk merge on #128929 lands N1 to N4.

Changes

• Both cdp-api send routes take an optional scheduled_at with an offset. No caller sends it until Django's stack ships behind a flag.
• A future time parks the job on the fast email lane and answers 202 { status: "scheduled", scheduled_at }.
• A past time sends now, with scheduled_at: null.
• A time over 30 days after the message's creation answers 400 invalid_scheduled_at, reason too_far, and frees the idempotency key.
• The fingerprint and stored key change only when scheduled_at is set, so the deployed version reads every key.
• A replay of a scheduled send answers scheduled again. It writes no status row, so a later move or cancel stays the latest row.
• The idempotency key of a scheduled send lives until 24 hours after the send is due, not 24 hours after it is accepted. A retry while the send waits replays it instead of queuing a second copy.
• scheduled takes status rank 0, beside queued.
• The scheduled row in email_status_events names the recipient, the workflow and the due time (scheduled_at, from #129915). The waiting-sends list reads it. email_status and GET emails/{id} need no change.
• A scheduled send keeps its files until a week after it is due. Accept renews a file that would expire sooner, so files attached today still go out with a send due in 30 days.
• The email queue wait metric starts at the scheduled time. The job state keeps that time, because a throttled retry moves the due time.

How did you test this code?

• Serial API tests cover each time rule on both routes, offsets, a key reused with another time, and the freed key.
• A latency row in email.service.test.ts fails if the wait starts at the insert.
• A live run at 71598b4 on this branch's worker and the base branch's worker:

Live run and cross-version results at e351094

Real cdp-api, queue, email worker, maildev and S3 store. The base is N2 at a2dd902.

Scenario	Result
A scheduled send	Held until its time, then one mail within one worker poll; job completed.
A send now, or a past time	Sent at once, scheduled_at: null.
Keyed replay	Same id and time, replayed: true; another time 422 idempotency_key_reused; one job.
Over 30 days, or a malformed time	400; the key is freed.
Scheduled send with an older file	The store copies it at accept; the mail at its time carries the file. A file that outlives due + 7 days is not copied.
This PR schedules, the base worker sends	Held, then sent at its time, with its file.
The base accepts, this PR's worker sends	Sent, with its file.

Not run: a rolling deploy on real infrastructure. The base answers a scheduled_at by sending at once; no caller sets it until Django's stack ships.

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-pr-descriptions, /writing-tests, /writing-code-comments

More context for AI agents

• Session: T3 Code stack thread for Silthus/personal#303, Claude Code.
• Decisions: the cdp-api answer always carries scheduled_at, null for a send now. Django reads only invocation_id and replayed today, so the field is additive. The outcome metric keeps queued for a scheduled send, because alerts key on it. The per-item comments are dropped at the author's request; the CI report's comment density is 0%.
• Follow-ups: N4 adds cancel and reschedule of jobs no worker has claimed. Its reschedule rewrites state.scheduledAt with the cyclotron scheduled column. The Django stack must change three readers before any caller can schedule: EmailDeliveryStatus gains scheduled, so the status read stops answering 404 while a send waits; the email log also picks scheduled rows, not only queued ones; and the status read's age gate moves from 30 to 60 days, so a send scheduled 30 days ahead stays readable after it goes out.
• Read closely: the time rules in TransactionalSends.accept and the stored key shape in idempotency-keys.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 (1 of 381)

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.

Files with the most added comment lines:

File	Comment lines	Added lines
nodejs/src/cdp/cdp-api.serial.test.ts	1	178

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

[posthog]

PostHog Review · Standard · reviewed 42f9b66: 3 Should fix.

This is the only automatic review while this pull request is a draft. Comment @posthog review to review new changes sooner. Otherwise, a review of the new changes runs when you mark it ready for review.

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.

[parameterai]

Risk: No findings

This increment only deletes five explanatory comments from the scheduled_at schema, the status-rank table, and the invocation-context type; no code, validation, or behavior changes. No security-relevant surface is added or altered.

_{Sentinel reviewed e20bb3f · Review settings}

[posthog]

PostHog Review · Standard · reviewed a6b5ebc: 2 Should fix.

[veria-ai]

Reviews

• e20bb3f — No new issues
• e351094 — No new issues
• 3f81e28 — No new issues

[posthog]

PostHog Review · Standard · reviewed d01f5a1: 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.

[posthog]

PostHog Review · Standard · reviewed 427cfb0: 1 Should fix.

This is review round 4 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.

[stamphog]

Not approved — this change needs a human reviewer.

Re-add the stamphog label to request another review once you have addressed this.

Owning-team authorship and strong familiarity provide assurance for the risky changes, but substantive reviewer concerns remain unresolved in the checkout. Address the listed comments or obtain independent acceptance from @PostHog/team-workflows; Harley Alexander and Daniel Marchuk are suggested reviewers.

• Author wrote 82% of the modified lines and has 21 merged PRs in these paths (familiarity STRONG).
• @PostHog on nodejs/src/cdp/services/hogflows/transactional-sends.ts: status retention remains limited to 30 days in products/messaging/backend/models/email_status_sql.py and transactional_email_status.py, so sends due near the scheduling limit become unreadable at delivery. Address the retention concern before re-requesting.
• @PostHog on nodejs/src/cdp/services/hogflows/transactional-sends.ts: the Django delivery-status enum still excludes scheduled, and get_email_status rejects unknown statuses. The author's proposed later stack does not fix the reviewed checkout; update the reader or obtain independent acceptance of this sequencing before re-requesting.
• @PostHog on nodejs/src/cdp/services/messaging/email-status.service.ts: the checked-out ClickHouse status schemas and event-view projection do not retain the emitted due time. Land and verify the prerequisite schema migration, or obtain independent acceptance of that dependency, before re-requesting.

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	181L, 10F substantive, 467L/15F incl. docs/generated/snapshots — within ceiling
tier	✓	T1-agent / T1d-complex (467L, 15F, single-area, feat)
stamphog 2.8.0		.stamphog/policy.yml @ e20bb3f · reviewed head e20bb3f

[trunk-io]

This pull request is queued for merge as part of 128929, which will merge 128868, 128871, 128881, 128929.

[trunk-io]

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

[deployment-status-posthog]

Deploy status

Environment	Status	Deployed At	Workflow
dev	✅ Deployed	2026-11-12 10:34 UTC	Run
prod-us	✅ Deployed	2026-11-12 10:56 UTC	Run
prod-eu	✅ Deployed	2026-11-12 11:07 UTC	Run

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