[APPS-2792] Add: v3 to v4 migration guide entry

[tyffical]

Motivation

• Local Node execution for App Builder backend functions is landing across several already-merged PRs (in-process execution, npm run dev:verify, the runtime network/subprocess guard, build-time rejection of Node built-ins/raw network globals, Custom Credentials local resolution, and real-identity hydration for getInitiatingUser()/getExecutionUser()), with process.env scoping.
• This bundle of changes is breaking for existing apps and is intended to ship as the next major version bump — MIGRATIONS.md needs a ## v3 to v4 entry describing it before that bump goes out.
• This PR can be reviewed and merged now; the actual version bump (bump.yaml dispatch) should wait until all the implementation PRs land.

Changes

7 changes across MIGRATIONS.md, README.md

What changed	File
Added a ## v3 to v4 entry covering in-process local execution, npm run dev:verify, and the process.env allowlist, plus its Table of Contents entry	MIGRATIONS.md
Added subsections covering Custom Credentials local resolution (datadog-app.local.json) and real-identity hydration for getInitiatingUser()/getExecutionUser(), plus their Table of Contents entries	MIGRATIONS.md
Extended the entry with accuracy fixes: dynamic-import rejection alongside static, a runtime network/subprocess guard scoped to function-body execution (not a dependency's own import-time code), a module-top-level credential caveat, and a preview-identity caveat	MIGRATIONS.md
Corrected four further accuracy gaps: the dynamic-import check requires a literal string specifier, the build-time check already covers the whole app-local module graph, a CLI equivalent for a missing dev:verify script, and dev:verify can't simulate a real trigger's identity	MIGRATIONS.md
Corrected three more accuracy gaps: a documented dns.lookup() exception to the runtime guard, module-cached state now covering the backend file's own code (not just a dependency's), and a call-serialization caveat	MIGRATIONS.md
Documented the CLI's inline dev:verify nudge before draft/upload/publish — accepting runs the check and blocks on cancellation, declining just reminds and continues	MIGRATIONS.md
Linked the new v3 to v4 section from the Migrations list	README.md

QA Instructions

Docs-only change — no functional QA applies.

yarn cli integrity
# Regenerates the file's Table of Contents from its headings and runs the repo's install/format/typecheck/OSS-compliance checks
# Expected: exits 0; `git status --short` shows no changes ✅ VERIFIED

Every described behavior was cross-checked against the actual merged code, grouped by area:

• Execution & routing — in-process execution, dev-server cloud/local routing, and dev:verify/DEV_VERIFY_MODE — verified against local-execution.ts, dev-server.ts, constants.ts.
• Runtime guards — network/subprocess guard's dependency-wide coverage and its import-time gap, dynamic-import rejection (and its literal-specifier-only limit), and the static check's whole-module-graph coverage — verified against network-guard.ts, local-execution.ts, reject-node-builtin-imports.ts, backend-static-checks-plugin.ts.
• Env scoping & credentials — the process.env allowlist, its module-top-level-load gap, Custom Credentials resolution, and real-identity hydration — verified against env-guard.ts, local-execution.ts, custom-credentials-resolver.ts.
• dev:verify behavior — the CLI-flag equivalent for a missing package script, its preview-identity limitation, and the inline pre-publish nudge — verified against constants.ts, dev-server.ts, and the nudge's separate private-repo implementation directly.
• Completeness — confirmed no other customer-facing change exists by reading the full diffs of
  • [APPS-2791] Fix: set ssr:true when bundling backend functions #460
  • [APPS-2792] Add: reject Node built-in imports in backend files #476
  • [APPS-2792] Add: in-process local execution for backend functions #479
  • [APPS-2792] Add: harden the in-process local execution path #480
  • [APPS-2792] Add: wire local execution into the real dev server #481
  • [APPS-2792] Add: runtime network/subprocess guard for local execution #484
  • [APPS-2792] Add: dev:verify mode-aware routing for local execution (build-plugins half) #490
  • [APPS-2792] Add: local-execution resilience tests #496
  • [APPS] Fix broken getInitiatingUser() and getExecutionUser() during local dev #503
  • [APPS-2792] Add process.env scoping for local execution (Secret Store parity) #504
  • [APPS-2792] Fix: harden env-guard against bypass and reliability gaps #510
  • [APPS-2792] Add: local-file resolution for Custom Credentials #512

Blast Radius

• Documentation-only change (MIGRATIONS.md). Zero runtime risk.

Out of Scope / Follow-ups

2 items deferred

Item	Status	Next step
The actual major version bump (bump.yaml dispatch) this entry documents	blocked	Wait until the process.env scoping (Secret Store parity, #504) and env-guard hardening (#510) work merge, then dispatch the bump separately
The npm run dev:verify package.json script this entry tells users to run is defined in the create-apps template, not in this repo	Independent	Tracked in a separate private repo (dev:verify script + --verify CLI flag) — merge before the version bump ships so the documented script exists for new projects

[datadog-prod-us1-5]

⚠️ Warnings

⚠️ Your PR has warnings. Tests failed — unable to determine if these are from required jobs.

🧪 4 Tests failed in 1 job

Continuous Integration | unit-test — ❌ 4 tests failed

View more details · View in GitHub Actions

❌ Dev Server Middleware dynamic discovery Should not find stale function after re-transform (HMR) from ../plugins/apps/src/vite/dev-server.test.ts  

Exceeded timeout of 10000 ms for a test.
Add a timeout value to this test to increase the timeout, if this is a long-running test. See https://jestjs.io/docs/api#testname-fn-timeout.

❌ Dev Server Middleware executeAction handler (local) Should eventually time out and return a clear error when getAllowedConnectionIds never settles from ../plugins/apps/src/vite/dev-server.test.ts  

Exceeded timeout of 10000 ms for a test.
Add a timeout value to this test to increase the timeout, if this is a long-running test. See https://jestjs.io/docs/api#testname-fn-timeout.

❌ Dev Server Middleware executeAction handler (local) Should never let two concurrent requests for different cold functions race their priming loads from ../plugins/apps/src/vite/dev-server.test.ts  

expect(received).toEqual(expected) // deep equality

- Expected  - 0
+ Received  + 1

  Array [
    "greet-priming-start",
+   "greet-priming-start",
  ]

❌ Dev Server Middleware executeAction handler (local) Should never prime (evaluate) the entry when getAllowedConnectionIds rejects from ../plugins/apps/src/vite/dev-server.test.ts  

Exceeded timeout of 10000 ms for a test.
Add a timeout value to this test to increase the timeout, if this is a long-running test. See https://jestjs.io/docs/api#testname-fn-timeout.

ℹ️ Info

No other issues found (see more)

❄️ No new flaky tests detected

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 2fbb0ea | Docs | View more details | Give us feedback!}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-10T19:59:13.235328Z	85ca1c6	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[tyffical]

/merge

🤖 Posted by Claude Code

[gh-worker-devflow-routing-ef8351]

View all feedbacks in Devflow UI.

2026-09-11 20:45:29 UTC ℹ️ Start processing command `/merge

🤖 Posted by Claude Code`

---

2026-09-11 20:45:35 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in master is approximately 2m (p90).

---

2026-09-11 20:47:09 UTC ℹ️ MergeQueue: This merge request was merged