Phase 2 -- Root Updates -- Analysis

Current-state assessment of the Root instance, the gap to the Phase 2 target, and the prioritised recommendations for closing it.

The Phase 2 target is described in specification.md; the requirements that Phase 2 must satisfy are listed in requirements.md. The downstream contracts Phase 2 produces are catalogued in exports.md.

Executive Summary

Phase 2 prepares the Root instance to host the ardamails.com mail-root zone and to serve as the assume-role target for cross-account NS-delegation writes from later phases. The work is a modification project: it renames an existing CDK app and stack (the apps/rootConfiguration/ folder and RootConfigurationStack class), preserves the published CloudFormation stack name, adds one new PublicHostedZone (ardamails.com) and a new declarative instances/Root/dns.ts configuration file, and re-exports the existing AllowCreatingNSRecordsRole so subsequent phases can consume it.

The gaps fall into four categories:

1. Mail-root zone absent. The ardamails.com zone (per DQ-009) does not yet exist as a CDK resource in the Root account. The domain is registered with Route53 in the platformRoot account; the hosted zone must be created and managed by CDK.
2. Naming alignment with Revision 1. The existing app folder (apps/rootConfiguration/), stack class (RootConfigurationStack), and stack file (stacks/root/root-configuration-stack.ts) pre-date the rev1 vocabulary that distinguishes “Root” as an instance group. The TS-side identifiers must be brought in line with the rev1 design without changing the deployed CloudFormation stack name.
3. Instance declaration absent. The new declarative instances/<InstanceGroup>/<asset>.ts convention (introduced for Corporate, partitions, etc.) has no instances/Root/ counterpart yet. Phase 2 establishes that file.
4. Exports surface missing the mail-root zone. Downstream phases (Corporate in Phase 3; partitions in Phase 4) need a stable export contract for the ardamails.com hosted zone ID and for the role ARN they will assume to write NS records upstream. The role ARN export already exists; the zone export does not.

Phase 2 is fully self-contained. It does not depend on, and is not deployed jointly with, any later phase. The cross-zone NS-delegation entries (e.g. for arda.ardamails.com) are written by the child zone owner (Corporate, partitions) into the parent zone, using the role Phase 2 exports. See DQ-R1-006.

Current-state vs. Phase 2 target — Comparison

Category 1: Significant Gaps (Resources Not in Place)

#	Gap	Current state	Phase 2 target
G-1	ardamails.com hosted zone	Domain registered with Route53 in platformRoot account; no CDK-managed PublicHostedZone exists.	RootDnsStack declares r53.PublicHostedZone(zoneName: "ardamails.com"). Zone ID exported as arda-ardamails-zone.
G-2	instances/Root/dns.ts declarative configuration	File does not exist. Existing root resources are declared inline in RootConfigurationStack / apps/rootConfiguration/r53-zones.ts.	New file instances/Root/dns.ts provides typed configuration values (zone name, expected exports) consumed by the Root app.
G-3	Mail-root zone export contract	No export carries ardamails.com zone ID. Downstream stacks have no stable handle for it.	Stack export arda-ardamails-zone (zone ID); zone-name constant published in platform/ari-configuration.ts if needed by downstream constants.

Category 2: Naming and Layout Misalignment with Revision 1

#	Misalignment	Current state	Phase 2 target
M-1	App folder name	src/main/cdk/apps/rootConfiguration/ (camelCase, conflicts with the rev1 PascalCase instance-group convention used for Corporate / Al1x).	src/main/cdk/apps/Root/ (PascalCase). Files inside (r53-zones.ts, live-url.ts) preserved verbatim except for any internal import rewrites.
M-2	Stack class and file name	RootConfigurationStack in stacks/root/root-configuration-stack.ts. The class name centres “Configuration” (a generic term) rather than the stack’s actual concern (DNS).	RootDnsStack in stacks/root/root-dns-stack.ts.
M-3	CDK App id argument	new RootConfigurationStack(app, "ROOT", "RootConfiguration", {...}) — id argument is "RootConfiguration". Must remain "RootConfiguration" to preserve the deployed CloudFormation stack name (per DQ-13’s lineage and the CFN stack-name immutability rule restated in ../phases.md § Phase 2).	new RootDnsStack(app, "ROOT", "RootConfiguration", {...}) (unchanged third argument) with an inline comment immediately above the call documenting the constraint.
M-4	Deploy-script path	deploy-root.sh line 56 references src/main/cdk/apps/rootConfiguration/r53-zones.ts.	Path updated to src/main/cdk/apps/Root/r53-zones.ts. No other script changes.

Category 3: Out of Scope of Phase 2 (Scoped to Other Phases)

#	Concern	Where it belongs	Reasoning
O-1	NS-delegation entry for arda.ardamails.com written into ardamails.com	Phase 3 (Corporate). The Corporate stack creates the arda.ardamails.com zone and instantiates WriteNSRecordsToUpstreamDns with nameServers = arda.hostedZoneNameServers.	Matches the existing per-partition arda.cards family pattern. The child zone owns the upstream NS write. See DQ-R1-006.
O-2	Reserving arda in the ardamails.com reserved-words list	Phase 3 (Corporate).	Already located in Phase 3 in ../phases.md § Phase 3; kept there.
O-3	Per-partition mail sub-zones (prod.ardamails.com, dev.ardamails.com, …) and their NS delegations	Phase 4 (Runtime Platform Updates).	Each partition creates its own zone and writes its own NS record into ardamails.com using the same construct pair.
O-4	Tightening AllowCreatingNSRecordsRole allowedParentHostedZoneIds from * to specific zone IDs	Out of scope of this project.	Resolved by user direction; current scope * is preserved. The role’s permissions can be tightened independently in a later refactor.
O-5	Extracting AllowCreatingNSRecordsRole to a separate RootSecurityStack	Out of scope; settled by DQ-013.	Role stays in RootDnsStack (formerly RootConfigurationStack).

Category 4: No Action Needed (Already in Place)

#	Already in place	Source
K-1	AllowCreatingNSRecordsRole IAM role (org-wide trust, Route53 permissions).	src/main/cdk/constructs/oam/allow-creating-ns-records-role.ts; instantiated in RootConfigurationStack. Carries over unchanged through the rename.
K-2	WriteNSRecordsToUpstreamDns construct — the lambda + custom resource that child stacks instantiate to write their NS records into a parent zone.	src/main/cdk/constructs/xgress/write-ns-records-to-upstream-dns.ts + src/main/cdk/constructs/inline-lambdas/write-platform-root-ns-record.ts. Used today by partition IngressStacks. Phase 2 leaves this untouched; Phase 3 / Phase 4 instantiate it.
K-3	Existing zones owned by Root: app.arda.cards, io.arda.cards, auth.arda.cards, assets.arda.cards.	RootConfigurationStack. Carry over unchanged through the rename.
K-4	Stack export arda-allow-create-ns-record-role.	RootConfigurationStack.publish(). Preserved verbatim through the rename.
K-5	apps/rootConfiguration/live-url.ts — secondary entry point.	Carried over to apps/Root/live-url.ts with no edits beyond any path-relative imports (none expected).

Prioritised Recommendations

1. Land the renames first, with the CFN-stack-name preservation comment in place. This is the highest-risk part of Phase 2 (a wrong id argument deletes the production root stack and recreates it). Running cdk diff against the deployed Root stack after the rename is the first verification gate.
2. Add the ardamails.com PublicHostedZone and its export in the same PR. This is additive; CDK’s Route53 PublicHostedZone construct creates a new hosted zone with assigned NS values, no impact on existing resources.
3. Add instances/Root/dns.ts with the typed configuration consumed by the renamed app. This crystallises the rev1 declarative pattern for the Root instance group.
4. Update deploy-root.sh path-only.
5. Verification is purely CDK Template-matcher unit tests + a grep/AST assertion for the inline CFN-name preservation comment. No live dig or operator walkthrough — those belong to Phase 3 (which writes the actual NS record).

References

• requirements.md — numbered requirements.
• specification.md — task contract with STOP points.
• verification.md — test catalogue.
• exports.md — cross-phase contracts produced.
• ../goal.md — project intent.
• ../architecture-overview.md — system structure.
• ../phases.md — full phase plan (Phase 2 section is patched in this round).
• ../decision-log.md — existing decisions including the new DQ-R1-006.