docs: propose deployment environment ordering fix

[sampolahtinen]

Linked issue

N/A — design proposal for discussion.

Summary

Proposes making Composer wait for environment-variable updates before creating a deployment, so the deployment captures the intended configuration. The Console incident received a 51-field input document instead of the required 57-field document because creation raced the configuration update.

Changes

• Adds a design brief with numbered before/after examples tracing input bindings, JSON serialization, the Management API PATCH, and the deployment snapshot.
• Specifies whole-resource dependencies in place of stable variable IDs, preserving existing deployment replacement triggers.
• Defines a persisted-state lifecycle regression and preview acceptance criteria.

Why

The existing variable ID can resolve while its value update is pending. Depending on resource completion preserves the required ordering without changing the public API or waiting for application-readiness support.

Scope: Documentation only: .drive/projects/deployment-environment-ordering/spec.md. Implementation and application readiness are separate work.

Testing performed

• pnpm format — passed; no fixes required.
• pnpm typecheck with repository-pinned Node 24.16.0 — passed, 78 build/type-check tasks.
• Checked local links, code fences, JSON examples, and git diff --check.
• No deployment or production changes performed; lifecycle regression tests are proposed, not implemented by this PR.

Checklist

• All commits are signed off (git commit -s).
• Read CONTRIBUTING.md; scoped to one logical concern.
• Conventional commit PR title.
• Tests: N/A — documentation only, no behavioral change.

Notes for the reviewer

Review the proposed dependency placement and whether the delayed-update lifecycle test captures the original failure. This draft requests design feedback before implementation.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}