Phase 4 — Run 2: dev Partition Rollout (G-B+C+D)

Overview

Branch / PR: jmpicnic/email-integration-phase-4-run-2 (infra), based on jmpicnic/email-integration-phase-4 (Run-1 / PR #455). When Run-1 merges, this branch rebases onto main and the PR retargets. Stacked-PR base pattern. Group(s): G-B + G-C + G-D for dev. Tasks: T-I4 (partition-email stack), T-I5-dev (dev instance config), T-I6 (apps extension), T-I8 (pre-deploy entry script), T-I10 (amm.sh step), T-D1 (verification entries — see § Exit criteria for the precise V-check set this run adds), T-D8 (infra CHANGELOG), T-O1-dev (pre-flight), T-O3 (deploy dev), T-O4 (arda-nonprod Postmark Compliance reply). Working directory: /Users/jmp/code/arda/projects/email-integration-worktrees/phase-4/infrastructure-run-2. AWS impact: Resource-touching in Alpha002 (creates dev.ardamails.com zone + NS delegation + SPF + DMARC + DKIM + Return-Path records + two SM secrets + two IAM roles). Resource-touching on Postmark side (Sender Signature registration on PostmarkNonProd). Personas: devops-engineer for T-I*; user as operator for T-O1, T-O3, T-O4.

Run-2 lands once for the whole phase: the CDK code, instance config, app extension, Phase A script, and amm.sh step are all authored here. Runs 3-5 only add their partition’s instance config + invoke amm.sh against that partition.

Entry criteria

Run-1 PR merged to Arda-cards/infrastructure main.
T-O2 (Root no-drift verification) passed and recorded.
Operator pre-flight (T-O1-dev) green:
- op read "$(npx ts-node -e 'console.log(require(\"./platform/postmark-service\").postmarkCredentialOpReference(\"dev\"))')" returns a non-empty token.
- aws sts get-caller-identity --profile Alpha002-Admin returns the Alpha002 account ID.
- dmarc-reports@arda.cards mailbox is healthy (T-O1 one-time-per-rollout check).

Tasks

Task	Description	Files touched	Persona
T-I4	Author `PartitionEmailStack` (three-interface pattern, validateProps, six `-API-` exports). Includes the cross-account NS-delegation seam: the stack writes its zone’s NS records into PlatformRoot’s `ardamails.com` via `WriteNSRecordsToUpstreamDns`, consuming the Run-1 generalised `AllowCreatingDnsRecordsRole` in `stsAssumeRole` mode. CFN stack id is the literal `${infrastructure}-${purpose.toLowerCase()}-Email`.	`src/main/cdk/stacks/purpose/partition-email.ts` + test	`devops-engineer`
T-I5-dev	Per-partition instance config for `dev`	`src/main/cdk/instances/Alpha002/dev.ts`	`devops-engineer`
T-I6	Extend `apps/Al1x/partition.ts` to instantiate `PartitionEmailStack` per active partition (+ `.publish()` from App, never from constructor)	`src/main/cdk/apps/Al1x/partition.ts`	`devops-engineer`
T-I8	Author `tools/register-partition-mail-signature.ts` with two-arg positional CLI + usage output. Sender Signature only — must not create a Postmark Server (Servers are created at system Runtime by Tenant, per the design).	`tools/register-partition-mail-signature.ts` + test	`devops-engineer`
T-I10	Extend `amm.sh` with partition-mail step. Canonical positional interface: `./amm.sh <infrastructure> [<partition>]` (matches the existing `partitionSecrets` step’s positional convention; no `--partition` flag). Sequence: `op read` → `::add-mask::` → pre-deploy script → `cdk deploy`.	`amm.sh`	`devops-engineer`
T-D1	Verification entries — only the new dev-specific V-checks: `V-PART-001..006`, `V-PART-008..020` (dev-specific rows; `V-PART-007` was completed in Run-1), `V-IAC-004..006`, `V-IAC-008` (`V-IAC-001`, `V-IAC-002`, `V-IAC-007` completed in Run-1; `V-IAC-003` pre-existing from Phase 2), `V-CLI-001`, `V-CLI-002`, `V-CLI-004`, `V-CLI-005` (`V-CLI-003` completed in Run-1). Cross-reference `design/verification.md` directly to confirm scope before authoring.	`documentation` worktree → `4-runtime-platform-updates/design/verification.md`	`devops-engineer`
T-D8	Infra `CHANGELOG.md` entry	`CHANGELOG.md`	`devops-engineer`
T-O1-dev (moved to Run-3 cascade)	Pre-flight checks for `dev` (op-read returns non-empty token; AWS profile resolves to Alpha002; `dmarc-reports@arda.cards` mailbox health verified per `specification.md` T-O1). Per DQ-R1-026, all T-O* operator tasks moved into the Run-3 operator cascade — Run-2 closes when PR #462 merges, with no deploy actions of its own.	none (operator-driven)	(Run-3)
T-O3 (moved to Run-3 cascade)	Operator runs `./amm.sh Alpha002 dev`. Now the first cascade entry of Run-3. See `runs/run-3-operator-cascade/project-plan.md`.	none (operator-driven)	(Run-3)
T-O4 (moved to Run-3 cascade)	Operator replies to Postmark Compliance ticket #11236089 with verified-domain evidence. Now sits between the `dev` and `stage` cascade entries in Run-3.	none (email thread)	(Run-3)

Run-1 outputs consumed

This run depends on the workspace refactors merged via PR #455. Inherited surface:

PartitionId (type) from platform/postmark-service.ts — discriminates dev | stage | demo | prod.
postmarkCredentialOpReference(partition) accessor — consumed by the pre-deploy script (T-I8).
AllowCreatingDnsRecordsRole construct + TRUST_PRINCIPAL_KIND const (stsAssumeRole mode) — instantiated by PartitionEmailStack for the per-partition DNS-records role.
MAIL_RESERVED_SLUGS_AT_MAIL_ROOT registry extension — partition names already guaranteed reserved.
tools/lib/postmark-client.ts + tools/lib/op-resolver.ts + tools/lib/logger.ts — used by register-partition-mail-signature.ts.

Downstream consumers

Run-2 lands the reusable Phase 4 surface that Runs #3 (stage), #4 (demo), and #5 (prod) inherit. Those later runs add only the per-partition instance config and re-invoke amm.sh with the partition’s name. They do not re-author the stack class, the entry script, or the amm.sh step.

Artefact landed by Run-2	What Runs #3 / #4 / #5 do with it
`PartitionEmailStack` class (`partition-email.ts`)	Reused unchanged.
`apps/Al1x/partition.ts` extension	Already instantiates for every active partition; no change needed when Runs 3/4/5 add their instance config.
`tools/register-partition-mail-signature.ts`	Reused unchanged.
`amm.sh` partition-mail step	Reused; called with the per-partition `<infrastructure> <partition>` args.
Six `-API-` CFN exports (per partition; published by deploy)	Phase 5b’s operations Helm chart reads them via `aws cloudformation list-exports`.

Worktree strategy

Single working directory: /Users/jmp/code/arda/projects/email-integration-worktrees/phase-4/infrastructure-run-2. T-D1 edits the documentation worktree (phase-4/documentation) directly. Read-only cdk diff against the PR branch is the canonical pre-merge confidence check; amm.sh is post-merge by default (operator may override per specification.md T-O3).

Validation

validate-exit.sh covers all code-side exit criteria. Operator-driven gates (T-O1, T-O3, T-O4) record outcomes in the verification.md sign-off table.

Exit criteria

npm run build && npm run lint && npm test exit 0.
cdk synth --app apps/Al1x/partition --context partition=dev produces a valid template; CFN stack name is Alpha002-dev-Email (partition lowercased per specification.md T-I4).
partition-email.test.ts passes including: stack-name assertion (matches ${infrastructure}-${purpose.toLowerCase()}-Email for at least two partition fixtures); findOutputs("*", {Export: {Name: ...}}) checks for all six -API- exports (V-PART-002, 012, 015, 018, 020); CFN_IO_MARKER witness output also asserted; route53:GetChange negative test passes.
register-partition-mail-signature.test.ts covers happy path, no-args (usage output), unknown <infrastructure>, partition/infrastructure mismatch, Postmark API failure, 1P resolution failure, and asserts no POST /servers call is made (Sender Signature only — Postmark Servers are out of scope for Phase 4).
amm.sh dry-run emits the three calls in order (op read, npx ts-node tools/register-partition-mail-signature.ts Alpha002 dev, cdk deploy Alpha002-dev-Email --parameters PostmarkAccountToken=...) with ::add-mask:: applied. Argument shape is positional: ./amm.sh Alpha002 dev.
PR opened; checks green; reviewer approval received.
Post-merge operator: ./amm.sh Alpha002 dev runs end-to-end. All dig checks pass for dev.ardamails.com. Postmark Console shows the dev.ardamails.com Sender Signature with DKIM and Return-Path verified. T-O4 reply sent. Sign-off row populated.

References

../../choreography.md — sequencing + operator gates.
../../../design/specification.md — T-I4, T-I5, T-I6, T-I8, T-I10, T-O1, T-O3, T-O4.
../../../design/verification.md — V-PART-001..020, V-IAC-003..008, V-CLI-001..005.
../../../design/exports.md § 1 — the six -API- exports.