Phase 2 -- Root Updates -- Requirements

Numbered requirements that Phase 2 must satisfy. Each requirement is traceable to verification tests in verification.md and to tasks in specification.md.

Requirement-ID conventions:

• REQ-ROOT-NNN — direct deliverables of the Root instance (zones, exports).
• REQ-IAC-NNN — IaC-side hygiene (folder/class/script renames, CFN-name preservation).
• REQ-OPS-NNN — operational concerns (deploy-script update, etc.).
• REQ-DOC-NNN — documentation deliverables.

REQ-ROOT-001: ardamails.com hosted zone exists in the Root account

The Root CDK app declares a Route53 PublicHostedZone with zoneName: "ardamails.com". After deploy, cdk synth for apps/Root/ includes a AWS::Route53::HostedZone resource for ardamails.com..

Verifies: V-ROOT-001

REQ-ROOT-002: ardamails.com zone ID is exported

The Root stack publishes a CloudFormation export named arda-ardamails-zone whose value is the hosted zone ID of the ardamails.com zone. Downstream stacks (Corporate in Phase 3, partitions in Phase 4) reference this export to instantiate WriteNSRecordsToUpstreamDns against the parent zone.

Verifies: V-ROOT-002

REQ-ROOT-003: Existing Root zones and exports preserved

The four arda.cards family zones (app.arda.cards, io.arda.cards, auth.arda.cards, assets.arda.cards) and the AllowCreatingNSRecordsRole are unchanged in the synthesised template after the Phase 2 rename. The exports arda-app-zone, arda-io-zone, arda-auth-zone, arda-assets-zone, and arda-allow-create-ns-record-role are present with values matching the pre-rename state (modulo CDK-assigned logical IDs, which may change).

Verifies: V-ROOT-003

REQ-IAC-001: App folder renamed to apps/Root/

The CDK App’s source folder is renamed from src/main/cdk/apps/rootConfiguration/ to src/main/cdk/apps/Root/. The two files inside (r53-zones.ts and live-url.ts) are preserved with content unchanged except for any internal import paths that reference siblings via the renamed folder.

Verifies: V-IAC-001

REQ-IAC-002: Stack class and file renamed to RootDnsStack / root-dns-stack.ts

The class RootConfigurationStack is renamed to RootDnsStack. The file src/main/cdk/stacks/root/root-configuration-stack.ts is renamed to src/main/cdk/stacks/root/root-dns-stack.ts. All in-repo imports of the old class / path are rewritten.

Verifies: V-IAC-002

REQ-IAC-003: CloudFormation stack name "RootConfiguration" is preserved

The third positional argument to the RootDnsStack constructor (the CDK id parameter that becomes the CloudFormation stack name) must remain the literal string "RootConfiguration". An inline source-code comment immediately above the constructor call documents this constraint.

Why this matters. Changing the CDK id argument forces CloudFormation to delete and recreate the stack, destroying every resource it owns (production hosted zones, the IAM role used by every partition’s NS-delegation pattern, etc.). The CFN stack-name immutability rule is restated in ../phases.md § Phase 2.

Verifies: V-IAC-003

REQ-IAC-004: instances/Root/dns.ts declarative configuration is added

A new file src/main/cdk/instances/Root/dns.ts is added. It exports the typed configuration values consumed by apps/Root/r53-zones.ts: the zone-name strings (arda.cards family + ardamails.com) and any export-key constants. This file follows the rev1 instances/<InstanceGroup>/<asset>.ts convention used for Corporate, Alpha001, Alpha002, etc.

Verifies: V-IAC-004

REQ-OPS-001: deploy-root.sh references the renamed app folder

deploy-root.sh line 56 (the --app argument to cdk deploy) references src/main/cdk/apps/Root/r53-zones.ts. No other changes to the script are made.

Verifies: V-OPS-001

REQ-DOC-001: Phase 2 planning artefacts published

The five planning artefacts (this file plus analysis.md, specification.md, verification.md, exports.md) exist under roadmap/in-progress/email-integration/2-root-updates/. They are linked from phases.md and from the project-level project-checkpoint.md.

Verifies: V-DOC-001

REQ-DOC-002: Phase 2 / Phase 3 ownership of NS-delegation is documented

A decision-log entry (DQ-R1-006) records the locus-of-NS-delegation decision: child zone owner writes upstream; Root only owns the assume-role target. phases.md Phase 2 and Phase 3 sections are patched to reflect the ownership split.

Verifies: V-DOC-002

Out of scope of Phase 2

These items are either deferred to later phases or are explicit non-goals.

• NS-delegation entry for arda.ardamails.com — written by the child Corporate stack in Phase 3, using WriteNSRecordsToUpstreamDns against the ardamails.com parent zone. Phase 2 only ensures the role and zone exist.
• Reserving arda in the ardamails.com reserved-words list — belongs to Phase 3 per phases.md.
• Per-partition mail sub-zones (prod.ardamails.com, dev.ardamails.com, …) — created in Phase 4 by each partition’s stack, which writes its own NS record into ardamails.com using the same role-and-construct pair.
• Tightening AllowCreatingNSRecordsRole.allowedParentHostedZoneIds from * to a specific zone-ID list — out of scope of this project; current value preserved.
• Extraction of AllowCreatingNSRecordsRole to a RootSecurityStack — settled by DQ-013; role stays in RootDnsStack.
• Postmark Console / 1Password operator steps — Phase 1 territory; no new operator action is required by Phase 2.

Acceptance criteria summary

Phase 2 is complete when:

1. cdk diff of apps/Root/ against the deployed Root CloudFormation stack shows only the additive ardamails.com zone (and its associated exports), plus any non-functional logical-ID renames CDK assigns.
2. The CloudFormation stack name remains RootConfiguration (verified by Template assertion + grep for the inline preservation comment).
3. apps/Root/ synthesises and npm run lint / npm run build / npm test pass on the infrastructure repo.
4. The five planning artefacts in 2-root-updates/ are merged on the documentation side; phases.md and decision-log.md are patched.
5. Stack exports are present and stable: arda-allow-create-ns-record-role (preserved), arda-ardamails-zone (new), and the four arda.cards family zone exports (preserved).

References

• analysis.md — gap analysis.
• specification.md — task contract.
• verification.md — test catalogue.
• exports.md — downstream contracts.
• ../phases.md — phase plan; Phase 2 section is patched in this round.
• ../decision-log.md — decisions including new DQ-R1-006.