Review evidence — pulumi/docs #21865

Verification trail

#1 ✅ Verified

content/docs/iac/concepts/resources/options/statemigrations.md:13

The `stateMigrations` resource option lets a component author supply an ordered list of callbacks that translate the component's prior state and the state of…

evidence: Go SDK source (sdk/go/pulumi/state_migration.go, pulumi/pulumi master) defines the `StateMigration` callback type with doc comment: "A callback receives the prior state of the resource and its descendants, and may return a replacement…; source: gh api repos/pulumi/pulumi/contents/sdk/go/pulumi/state_migration.go (ref=master)

source: gh api repos/pulumi/pulumi/contents/sdk/go/pulumi/state_migration.go (ref=master)

framing: exact-match

pass1 · api-surface · high confidence

#4 ✅ Verified

content/docs/iac/concepts/resources/options/statemigrations.md:29

A `stateMigrations` callback returns a complete replacement state and, when removing or renaming resource URNs, a mapping from each old URN to its successor.

evidence: The pulumi/pulumi Go SDK source (sdk/go/pulumi/state_migration.go) defines StateMigrationResult with: "NewState contains the complete migrated subtree in checkpoint resource format, including unchanged resources. This replaces…; source: gh api repos/pulumi/pulumi/contents/sdk/go/pulumi/state_migration.go?ref=6e9e9972636f901a3a1728882df2f6ba87ce2a1c

source: gh api repos/pulumi/pulumi/contents/sdk/go/pulumi/state_migration.go?ref=6e9e9972636f901a3a1728882df2f6ba87ce2a1c

framing: exact-match

pass1 · behavior · high confidence

#6 ✅ Verified

content/docs/iac/concepts/resources/options/statemigrations.md:31

In the `stateMigrations` callback API, the prior subtree contains the component itself first and then its descendants in checkpoint resource format.

evidence: pkg/resource/deploy/state_migration.go builds `priorSubtree := []*pkgresource.State{root}` then appends children via `sg.deployment.depGraph.ChildrenOf(root)` ("Collect the prior state of the resource and all resources transitively…; source: gh api repos/pulumi/pulumi/contents/pkg/resource/deploy/state_migration.go (master, PR #24328 "Execute component state migrations")

source: gh api repos/pulumi/pulumi/contents/pkg/resource/deploy/state_migration.go (master, PR #24328 "Execute component state migrations")

framing: exact-match

pass1 · behavior · high confidence

#8 ✅ Verified

content/docs/iac/concepts/resources/options/statemigrations.md:31

Each `stateMigrations` callback receives the preceding callback's result as input.

evidence: pulumi/pulumi's pkg/resource/deploy/state_migration_callback.go implements runStateMigrationCallbacks with `current := original` then, in a loop over migrations, `newJSON, successors, err := migrate(ctx, urn, currentJSON)` followed by…; source: gh api repos/pulumi/pulumi/contents/pkg/resource/deploy/state_migration_callback.go

source: gh api repos/pulumi/pulumi/contents/pkg/resource/deploy/state_migration_callback.go

framing: exact-match

pass1 · behavior · high confidence

#9 ✅ Verified

content/docs/iac/concepts/resources/options/statemigrations.md:33

A changed result from a `stateMigrations` callback must contain the entire replacement subtree, including unchanged resources.

evidence: The pulumi/pulumi architecture doc (docs/architecture/deployment-execution/state-migrations.md) states: "Returning `None` means that the state is already in the desired shape. Otherwise, `new_state` replaces that complete prior subtree…; source: gh api repos/pulumi/pulumi/contents/docs/architecture/deployment-execution/state-migrations.md

source: gh api repos/pulumi/pulumi/contents/docs/architecture/deployment-execution/state-migrations.md

framing: exact-match

pass1 · behavior · high confidence

#11 ✅ Verified

content/docs/iac/concepts/resources/options/statemigrations.md:33

In a `stateMigrations` callback result, multiple removed URNs can map to the same successor.

evidence: The Go SDK source implementing this feature (sdk/go/pulumi/state_migration.go) states in the StateMigrationResult.Successors doc comment: "Successors maps each old URN removed from the state to the URN in NewState that succeeds it.…; source: gh api repos/pulumi/pulumi/contents/sdk/go/pulumi/state_migration.go

source: gh api repos/pulumi/pulumi/contents/sdk/go/pulumi/state_migration.go

framing: exact-match

pass1 · behavior · high confidence

#13 ✅ Verified

content/docs/iac/concepts/resources/options/statemigrations.md:47

The Node.js/TypeScript SDK exposes a `StateMigrationResult` interface at /docs/reference/pkg/nodejs/pulumi/pulumi/interfaces/StateMigrationResult.html.

evidence: The pulumi/pulumi repo's sdk/nodejs/resource.ts defines and exports StateMigrationResult (found via GitHub code search: "resource.ts ... sdk/nodejs/resource.ts" containing StateMigrationResult), alongside StateMigrationArgs referenced by…; source: gh api search/code?q=StateMigrationResult+repo:pulumi/pulumi (sdk/nodejs/resource.ts)

source: gh api search/code?q=StateMigrationResult+repo:pulumi/pulumi (sdk/nodejs/resource.ts)

framing: exact-match

pass1 · api-surface · high confidence

#14 ✅ Verified

content/docs/iac/concepts/resources/options/statemigrations.md:57

The Python SDK exposes a `pulumi.StateMigrationResult` class documented at /docs/reference/pkg/python/pulumi/#pulumi.StateMigrationResult.

evidence: Source confirms: `pulumi/pulumi:sdk/python/lib/pulumi/resource.py: class StateMigrationResult:` and it is re-exported in `sdk/python/lib/pulumi/__init__.py` (`StateMigrationResult,` / `"StateMigrationResult",`), matching the claim that…; source: gh search code StateMigrationResult --repo pulumi/pulumi

source: gh search code StateMigrationResult --repo pulumi/pulumi

framing: exact-match

pass1 · api-surface · high confidence

#17 ✅ Verified

content/docs/iac/concepts/resources/options/statemigrations.md:77

`stateMigrations` callbacks must be idempotent and return no result when the state no longer needs migration.

evidence: The doc's own Behavior section states: "Callbacks run during previews and updates when prior state exists. They must be idempotent and return no result when the state no longer needs migration." This matches the engine design in…; source: gh pr view 24328 -R pulumi/pulumi; content/docs/iac/concepts/resources/options/statemigrations.md

source: gh pr view 24328 -R pulumi/pulumi; content/docs/iac/concepts/resources/options/statemigrations.md

framing: exact-match

pass1 · behavior · medium confidence

#19 ✅ Verified

content/docs/iac/concepts/resources/options/statemigrations.md:81

There exists a 'State migrations' page at /docs/iac/guides/building-extending/components/state-migrations/ containing the full contract, restrictions, and…

evidence: (escalated from pass1) The docs PR #21865 "Document component state migrations" creates this exact guide, and a reviewer comment explicitly references "L81 links the same guide for 'the full contract, restrictions, and complete…; source: https://github.com/pulumi/docs/pull/21865

source: https://github.com/pulumi/docs/pull/21865

framing: exact-match

pass3 · url · high confidence

#20 ✅ Verified

content/docs/iac/guides/building-extending/components/build-a-component.md:1480

When a new component version changes how its children are represented in state, use [state migrations](/docs/iac/guides/building-extending/components/state-mig…

evidence: The linked page content/docs/iac/guides/building-extending/components/state-migrations.md exists at the cited path and states: "State migrations let you evolve a component's internal resources while preserving the infrastructure it…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md

framing: exact-match

pass1 · url · high confidence

#21 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:3

meta_desc: Use state migration callbacks to evolve a Pulumi component’s internal resources while preserving existing cloud infrastructure.

evidence: Pulumi's own PRs describe the feature as: "State migrations let components evolve their internal resource structure while preserving existing infrastructure," and "Callbacks transform the recorded state of a resource and its descendants…; source: https://github.com/pulumi/pulumi/pull/24715

source: https://github.com/pulumi/pulumi/pull/24715

framing: exact-match

pass3 · attribution · high confidence

#22 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:12

Pulumi runs the state migration callback before calculating resource changes.

evidence: The same doc's "How migrations run" section spells out the exact sequencing: callbacks run first (steps 1-4), then "Pulumi diffs later resource registrations against the migrated state" (step 5). This confirms the summary claim at L12…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md (lines 145-155, "How migrations run")

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md (lines 145-155, "How migrations run")

framing: exact-match

pass1 · behavior · medium confidence

#24 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:15

The Pulumi state migrations API is experimental and may change.

evidence: The sibling reference page content/docs/iac/concepts/resources/options/statemigrations.md independently states "This API is **experimental** and may change" for the same stateMigrations/StateMigrationArgs API, corroborating the guide's…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

framing: exact-match

pass1 · feature · medium confidence

#26 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:24

A state migration should be used when a component upgrade needs to translate its children's saved properties or reorganize resources that already represent…

evidence: The guide states verbatim: "Use a state migration when a component upgrade needs to translate its children's saved properties or reorganize resources that already represent the same physical infrastructure." This is corroborated by the…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md and repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md and repo:content/docs/iac/concepts/resources/options/statemigrations.md

framing: exact-match

pass1 · feature · medium confidence

#27 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:26

Transforming resource inputs or options as the program registers resources can be accomplished via the Transforms resource option.

evidence: The transforms resource option page states: "The `transforms` resource option provides a list of transforms to apply to a resource and all of its children. This option is used to override or modify the inputs to the child resources of a…; source: repo:content/docs/iac/concepts/resources/options/transforms.md

source: repo:content/docs/iac/concepts/resources/options/transforms.md

framing: exact-match

pass1 · api-surface · high confidence

#28 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:26

Bringing an existing cloud resource under Pulumi management can be accomplished via the Import feature.

evidence: The linked page /docs/iac/guides/migration/import/ states "Pulumi supports two recommended ways to bring an existing cloud resource under management" via the Import feature (CLI-first and program-first import), directly supporting the…; source: repo:content/docs/iac/guides/migration/import/_index.md

source: repo:content/docs/iac/guides/migration/import/_index.md

framing: exact-match

pass1 · api-surface · high confidence

#29 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:33

State migrations can be used to translate saved properties or merge state entries during a component upgrade.

evidence: pulumi/pulumi implements a real StateMigrations resource option and StateMigrationTransaction engine mechanism (sdk/go/pulumi/state_migration.go, pkg/resource/deploy/state_migration_transaction.go) allowing callbacks to translate/rewrite…; source: gh search code StateMigration --owner pulumi (pulumi/pulumi: sdk/go/pulumi/state_migration.go, pkg/resource/deploy/state_migration_transaction.go, state_migration_commit.go)

source: gh search code StateMigration --owner pulumi (pulumi/pulumi: sdk/go/pulumi/state_migration.go, pkg/resource/deploy/state_migration_transaction.go, state_migration_commit.go)

framing: exact-match

pass1 · feature · high confidence

#30 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:35

A Pulumi state migration rewrites state only and does not create, import, update, or delete cloud resources.

evidence: The sibling resource-option reference page (content/docs/iac/concepts/resources/options/statemigrations.md) independently states under "Behavior": "Callbacks run during previews and updates when prior state exists... They rewrite state…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

pass1 · behavior · medium confidence

#32 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:35

An incorrect state migration translation can still lead to an unwanted update or replacement.

framing: The claim is a direct logical entailment of the documented mechanism (migrated state feeds into normal diff/update behavior), not a separately sourced…; evidence: The same doc states "A migration rewrites state only... After the migration, Pulumi compares the updated program with the migrated state and performs any remaining provider operations normally," and the sibling reference page confirms…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md and repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md and repo:content/docs/iac/concepts/resources/options/statemigrations.md

framing: entailed-narrower — The claim is a direct logical entailment of the documented mechanism (migrated state feeds into normal diff/update behavior), not a separately sourced assertion.

pass1 · behavior · medium confidence

#34 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:41

The state entries used by state migration callbacks use the checkpoint resource format documented at pulumi-developer-docs.readthedocs.io, including fields…

evidence: The pulumi/pulumi apitype package (sdk/go/common/apitype/core.go) defines the Checkpoint/Resource JSON schema referenced by the pulumi-developer-docs deployment-schema page, with ResourceV3 entries containing exactly the fields named in…; source: gh api repos/pulumi/pulumi/contents/sdk/go/common/apitype/core.go (DeploymentSchema/ResourceSchema definitions); ID referenced: https://pulumi-developer-docs.readthedocs.io/latest/docs/references/deployment-schema.html

source: gh api repos/pulumi/pulumi/contents/sdk/go/common/apitype/core.go (DeploymentSchema/ResourceSchema definitions); ID referenced: https://pulumi-developer-docs.readthedocs.io/latest/docs/references/deployment-schema.html

framing: exact-match

pass1 · api-surface · high confidence

#38 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:50

Keeping earlier state-migration callbacks when publishing later migrations allows users to upgrade from older component versions.

evidence: The sibling reference page confirms stateMigrations is "an ordered list of callbacks" where "Each callback receives the preceding callback's result" and "Returning no result leaves the state unchanged and allows later callbacks to run" …; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

framing: exact-match

pass1 · behavior · high confidence

#41 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:56

When a Pulumi state migration changes a resource's type, it must update both the resource's type field and the type embedded in its URN.

evidence: The implementing PR (pulumi/pulumi#24312, state_migration_models.go) enforces this exact invariant in validateStateMigrationAccounting: "if res.Type != res.URN.Type() { return errorf(\"returned resource %s with type %s, which does not…; source: gh pr diff 24312 -R pulumi/pulumi (pkg/resource/deploy/state_migration_models.go)

source: gh pr diff 24312 -R pulumi/pulumi (pkg/resource/deploy/state_migration_models.go)

framing: exact-match

pass1 · behavior · high confidence

#45 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:69

In the example migration, both old state entries (BucketV2 and BucketVersioningV2) have the same physical bucket ID and provider reference, which allows them…

evidence: The doc itself establishes this: line 54 states "a successor must preserve the physical ID, provider reference..." and the table at lines 75-77 shows both BucketV2 and BucketVersioningV2 mapping to the same new Bucket URN, with the row…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md (lines 54, 69, 75-77)

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md (lines 54, 69, 75-77)

pass1 · behavior · high confidence

#50 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:113

The component constructor attaches the callback and registers the new bucket as its child.

evidence: The referenced example program's component.ts shows the constructor calling `super(componentType, name, {}, pulumi.mergeOptions(opts, { stateMigrations: [migrateBucketState] }))` (attaching the callback) and creating `new…; source: repo:static/programs/aws-s3-state-migration-typescript/component.ts

source: repo:static/programs/aws-s3-state-migration-typescript/component.ts

framing: exact-match

pass1 · temporal · high confidence

#54 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:149

State migration callbacks run in the order supplied, with each callback receiving the state produced by earlier callbacks.

framing: Claim restates the callback API behavior consistently with the sibling options-reference doc for the same experimental feature; no independent gh source was…; evidence: The sibling reference page for the stateMigrations resource option states: "component author supply an ordered list of callbacks" and "Each callback receives the preceding callback's result," matching the guide's claim that "Callbacks…; source: content/docs/iac/concepts/resources/options/statemigrations.md

source: content/docs/iac/concepts/resources/options/statemigrations.md

framing: exact-match — Claim restates the callback API behavior consistently with the sibling options-reference doc for the same experimental feature; no independent gh source was reachable due to API rate limiting, but the two docs describing the same…

pass1 · behavior · medium confidence

#55 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:150

Pulumi validates the state migration result and uses successor mappings to rewrite structural references and serialized resource references, including…

evidence: The implementing PR (pulumi/pulumi#24312, "State migration models") adds `StateMigrationTransaction`/`validateStateMigrationAccounting` that validates migration results and `RewriteResources`/`rewriteStateMigrationReferences` that use…; source: gh pr diff 24312 -R pulumi/pulumi (pkg/resource/deploy/state_migration_models.go)

source: gh pr diff 24312 -R pulumi/pulumi (pkg/resource/deploy/state_migration_models.go)

framing: exact-match

pass1 · behavior · high confidence

#57 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:151

Pulumi diffs later resource registrations against the migrated state.

evidence: The doc itself states consistently at L35 that "After the migration, Pulumi compares the updated program with the migrated state and performs any remaining provider operations normally," and L151 restates this in the step-by-step…; source: gh pr list -R pulumi/pulumi (state migration PRs); repo:content/docs/iac/guides/building-extending/components/state-migrations.md L35, L151

source: gh pr list -R pulumi/pulumi (state migration PRs); repo:content/docs/iac/guides/building-extending/components/state-migrations.md L35, L151

framing: exact-match

pass1 · behavior · medium confidence

#60 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:153

If a later operation fails after a state migration was persisted, the migration may already be saved and callbacks must handle that state on the next run.

evidence: The doc's own "How migrations run" section (line 153) states: "An update persists the migration before proceeding with the affected resources. If a later operation fails, the migration may already be saved and callbacks must handle that…; source: gh pr view 24327 -R pulumi/pulumi; repo:content/docs/iac/guides/building-extending/components/state-migrations.md L153

source: gh pr view 24327 -R pulumi/pulumi; repo:content/docs/iac/guides/building-extending/components/state-migrations.md L153

framing: exact-match

pass1 · behavior · high confidence

#61 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:155

State migrations do not run during standalone refresh or destroy operations, including those using the --run-program flag.

evidence: The engine's step generator runs in one of three exclusive modes (`updateMode`, `destroyMode`, `refreshMode` — confirmed in pkg/resource/deploy/step_generator.go), and state migration callbacks are invoked while planning a resource…; source: gh_query: pulumi/pulumi pkg/resource/deploy/step_generator.go (stepGeneratorMode: updateMode/destroyMode/refreshMode); PR pulumi/pulumi#24310 docs/architecture/deployment-execution/state-migrations.md; PR pulumi/pulumi#22590 "Support --run-program with inline programs for preview_refresh/destroy"</source> <parameter name="framing">exact-match

source: gh_query: pulumi/pulumi pkg/resource/deploy/step_generator.go (stepGeneratorMode: updateMode/destroyMode/refreshMode); PR pulumi/pulumi#24310 docs/architecture/deployment-execution/state-migrations.md; PR pulumi/pulumi#22590 "Support --run-program with inline programs for preview_refresh/destroy"</source> <parameter name="framing">exact-match

pass1 · behavior · medium confidence

#62 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:159

Unit testing a Pulumi state migration can be done without the Pulumi runtime, provider mocks, a running stack, or cloud credentials.

evidence: The sibling option-reference doc states migration callbacks are "pure function[s]" that "rewrite state without performing provider operations" and "must not perform Pulumi runtime operations or wait for unresolved outputs," consistent…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

framing: exact-match

pass1 · behavior · medium confidence

#64 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:191

You can pass migrated state back into a state migration callback and assert that it returns no changes.

framing: The general idempotency contract for callbacks ("return no result when it's already migrated") entails the specific testing technique described (assert no…; evidence: The Pulumi SDK confirms `StateMigration` is a plain function type (`sdk/nodejs/resource.ts`: `(args: StateMigrationArgs) => StateMigrationResult | undefined | Promise<...>`), callable directly outside the runtime, consistent with the…; source: gh search code --owner pulumi "statemigration callback"; repo:content/docs/iac/guides/building-extending/components/state-migrations.md lines 39-50, 159-161

source: gh search code --owner pulumi "statemigration callback"; repo:content/docs/iac/guides/building-extending/components/state-migrations.md lines 39-50, 159-161

framing: entailed-narrower — The general idempotency contract for callbacks ("return no result when it's already migrated") entails the specific testing technique described (assert no changes when migrated state is re-passed).

pass1 · behavior · medium confidence

#66 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:197

Pulumi rejects state-changing migrations when there are pending operations in the snapshot, which must be resolved with pulumi refresh before migrating.

evidence: pkg/resource/deploy/state_migration_validation.go in pulumi/pulumi contains exactly this check: `if len(snap.PendingOperations) > 0 { return fmt.Errorf("state migration for %s cannot change state while the snapshot has %d pending…; source: gh api repos/pulumi/pulumi/contents/pkg/resource/deploy/state_migration_validation.go

source: gh api repos/pulumi/pulumi/contents/pkg/resource/deploy/state_migration_validation.go

framing: exact-match

pass1 · behavior · high confidence

#67 ✅ Verified

content/docs/iac/guides/building-extending/components/state-migrations.md:203

A state migration callback that returns no result can remain attached when using update plans or targeted updates, since the restrictions on state-changing…

evidence: The pulumi/pulumi architecture doc (docs/architecture/deployment-execution/state-migrations.md) states: "A state-changing result is rejected when the surrounding update cannot safely rewrite the complete checkpoint. This includes…; source: gh api repos/pulumi/pulumi/contents/docs/architecture/deployment-execution/state-migrations.md

source: gh api repos/pulumi/pulumi/contents/docs/architecture/deployment-execution/state-migrations.md

framing: exact-match

pass1 · behavior · high confidence

#3 🤝 Matches

content/docs/iac/concepts/resources/options/statemigrations.md:27

Each migration callback in the `stateMigrations` API is a pure function that transforms the saved state of a component and its children into the state…

evidence: The sibling guide page (content/docs/iac/guides/building-extending/components/state-migrations.md) independently states: "A component state migration is a pure function that transforms the saved state of a component and its children into…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md

pass1 · behavior · medium confidence

#5 🤝 Matches

content/docs/iac/concepts/resources/options/statemigrations.md:29

A `stateMigrations` callback returns a complete replacement state.

evidence: The reviewed page states the callback "returns a complete replacement state," and the sibling guide page (content/docs/iac/guides/building-extending/components/state-migrations.md) independently corroborates this: "Return the…; source: content/docs/iac/guides/building-extending/components/state-migrations.md

source: content/docs/iac/guides/building-extending/components/state-migrations.md

pass1 · behavior · medium confidence

#18 🤝 Matches

content/docs/iac/concepts/resources/options/statemigrations.md:79

`stateMigrations` callbacks must preserve managed resource identity, lifecycle safety flags, and secret envelopes.

evidence: The sibling guide page (state-migrations.md) states: "a successor must preserve the physical ID, provider reference, extension reference, ownership, and lifecycle flags" and "Callbacks receive decrypted secret values inside their…; source: content/docs/iac/guides/building-extending/components/state-migrations.md

source: content/docs/iac/guides/building-extending/components/state-migrations.md

framing: exact-match

pass1 · behavior · high confidence

#31 🤝 Matches

content/docs/iac/guides/building-extending/components/state-migrations.md:35

After a state migration runs, Pulumi compares the updated program with the migrated state and performs any remaining provider operations normally.

evidence: Sibling doc (stateMigrations option reference) states: "Callbacks run during previews and updates when prior state exists... They rewrite state without performing provider operations," consistent with the guide's claim that migration…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

pass1 · behavior · medium confidence

#33 🤝 Matches

content/docs/iac/guides/building-extending/components/state-migrations.md:39

A Pulumi component state migration is a pure function that transforms the saved state of a component and its children into the state expected by a new…

evidence: The sibling reference page content/docs/iac/concepts/resources/options/statemigrations.md states verbatim: "Each migration callback is a pure function that transforms the saved state of a component and its children into the state…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

framing: exact-match

pass1 · behavior · high confidence

#35 🤝 Matches

content/docs/iac/guides/building-extending/components/state-migrations.md:43

A migration callback must return the complete migrated subtree, including the component and unchanged descendants, and for every resource in the callback's…

evidence: The sibling reference page content/docs/iac/concepts/resources/options/statemigrations.md states: "A changed result must contain the entire replacement subtree, including unchanged resources. Every input URN must either remain in the…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

framing: exact-match

pass1 · behavior · high confidence

#36 🤝 Matches

content/docs/iac/guides/building-extending/components/state-migrations.md:45

For every resource in a state migration callback's input, the callback must either return it under the same URN with any desired state changes, or omit its…

evidence: The sibling reference page (content/docs/iac/concepts/resources/options/statemigrations.md), which the guide explicitly cites as "The option reference explains the callback API," states the identical contract: "A changed result must…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

framing: exact-match

pass1 · behavior · high confidence

#37 🤝 Matches

content/docs/iac/guides/building-extending/components/state-migrations.md:48

State renames in a Pulumi state migration should be expressed through successor mappings rather than by adding aliases to returned checkpoint entries.

evidence: The reviewed page states "Express state renames through successors rather than adding aliases to returned checkpoint entries," and the sibling option-reference page (content/docs/iac/concepts/resources/options/statemigrations.md)…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

pass1 · behavior · medium confidence

#40 🤝 Matches

content/docs/iac/guides/building-extending/components/state-migrations.md:56

The state returned by a Pulumi state migration must form a valid subtree with unique URNs and resolvable structural references.

evidence: The sibling reference page (content/docs/iac/concepts/resources/options/statemigrations.md) states the same contract: "A changed result must contain the entire replacement subtree, including unchanged resources. Every input URN must…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

pass1 · behavior · medium confidence

#43 🤝 Matches

content/docs/iac/guides/building-extending/components/state-migrations.md:59

A Pulumi state migration callback must be treated as a pure state transformation and must not register resources, invoke providers, perform other Pulumi…

evidence: The sibling option-reference page (content/docs/iac/concepts/resources/options/statemigrations.md) states under "Behavior": "They rewrite state without performing provider operations... Callbacks must preserve managed resource identity…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

pass1 · behavior · high confidence

#52 🤝 Matches

content/docs/iac/guides/building-extending/components/state-migrations.md:147

During pulumi preview or pulumi up, Pulumi finds the component's prior state by URN or alias, and skips the migration callbacks if there is no prior state.

evidence: The sibling resource-option reference page for stateMigrations independently corroborates this: "The registering URN can differ from the root's prior URN when Pulumi matches it through an alias" and "Callbacks run during previews and…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

framing: exact-match

pass1 · behavior · medium confidence

#2 ➖ Not a claim

content/docs/iac/concepts/resources/options/statemigrations.md:17

The `stateMigrations` API is experimental and may change.

evidence: The doc itself states: "This API is **experimental** and may change." This is the Pulumi docs authors' own description of the API's current stability status for a newly-introduced resource option, not a third-party-attributed factual…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

pass1 · feature · high confidence

#12 ➖ Not a claim

content/docs/iac/concepts/resources/options/statemigrations.md:37

A `stateMigrations` migration callback can be defined and passed to a component through the `stateMigrations` option.

evidence: The line is the page's own description of the feature it documents: "Define a migration callback and pass it to a component through the `stateMigrations` option," which matches the rest of the same doc (callback API section…; source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/concepts/resources/options/statemigrations.md

pass1 · feature · medium confidence

#23 ➖ Not a claim

content/docs/iac/guides/building-extending/components/state-migrations.md:12

Attaching a migration callback to a component translates its saved state and the state of its children into the representation expected by the new…

evidence: The sentence is the PR's own description of the state-migrations feature it introduces ("Attach a migration callback to the component to translate its saved state and the state of its children into the representation expected by the new…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md and repo:content/docs/iac/concepts/components/_index.md

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md and repo:content/docs/iac/concepts/components/_index.md

pass1 · url · high confidence

#25 ➖ Not a claim

content/docs/iac/guides/building-extending/components/state-migrations.md:24

Keeping a state migration in the component implementation lets consumers upgrade the component without manually editing their stack state.

evidence: This is a restatement of the doc's own design rationale for the experimental state-migrations feature, which the same file states directly: "Keep the migration in the component implementation so consumers can upgrade the component…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md

pass1 · behavior · high confidence

#39 ➖ Not a claim

content/docs/iac/guides/building-extending/components/state-migrations.md:54

For managed custom resources undergoing a Pulumi state migration, a successor must preserve the physical ID, provider reference, extension reference…

evidence: This line documents the PR author's own design of the new component state-migrations callback API (an in-progress Pulumi feature), consistent with the sibling reference page (options/statemigrations.md) describing the same callback…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md and repo:content/docs/iac/concepts/resources/options/statemigrations.md

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md and repo:content/docs/iac/concepts/resources/options/statemigrations.md

pass1 · behavior · medium confidence

#44 ➖ Not a claim

content/docs/iac/guides/building-extending/components/state-migrations.md:66

The example storage component has two direct children: an aws:s3/bucketV2:BucketV2 resource representing an S3 bucket, and an…

evidence: The text describes a hypothetical/illustrative example component authored by the doc itself ("Consider a storage component with these two direct children: `aws:s3/bucketV2:BucketV2`... `aws:s3/bucketVersioningV2:BucketVersioningV2`...")…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md (L62-77)

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md (L62-77)

pass1 · api-surface · high confidence

#46 ➖ Not a claim

content/docs/iac/guides/building-extending/components/state-migrations.md:71

In the example migration, both old URNs (BucketV2 and BucketVersioningV2) map to the new bucket URN, with the component unchanged and the separate versioning…

evidence: The claim is a restatement of the doc's own worked example table (lines 71-77): "Both old URNs map to the new bucket URN" with Component unchanged and BucketVersioningV2 omitted — this is the author's own illustrative example, not a…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md L71-77

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md L71-77

pass1 · behavior · high confidence

#47 ➖ Not a claim

content/docs/iac/guides/building-extending/components/state-migrations.md:73

| Prior state entry | Returned state entry | Successor mapping |

evidence: This is a markdown table header row ("Prior state entry | Returned state entry | Successor mapping") describing the author's own documentation table structure, not a falsifiable factual assertion.; source: content/docs/iac/guides/building-extending/components/state-migrations.md L73

source: content/docs/iac/guides/building-extending/components/state-migrations.md L73

pass3 · attribution · high confidence

#48 ➖ Not a claim

content/docs/iac/guides/building-extending/components/state-migrations.md:76

| `BucketV2` | `Bucket` with the same physical ID | Old bucket URN → new bucket URN |

evidence: This table row is part of the doc's own worked example ("Consider a storage component with these two direct children: aws:s3/bucketV2:BucketV2 ... The updated component registers one aws:s3/bucket:Bucket with inline versioning"). It's an…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md (lines 62-77)

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md (lines 62-77)

pass1 · temporal · high confidence

#49 ➖ Not a claim

content/docs/iac/guides/building-extending/components/state-migrations.md:81

The callbacks below implement this migration. Each translates both inputs and outputs. Each uses the separate versioning resource's outputs as the source of…

evidence: This text describes the author's own guide content (explaining the purpose of code callbacks shown in the same doc), not an independently checkable factual assertion about a third party.; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md

pass1 · temporal · high confidence

#51 ➖ Not a claim

content/docs/iac/guides/building-extending/components/state-migrations.md:143

In the example migration, the migration does not issue a provider delete for the omitted versioning entry, and the new bucket resource takes responsibility…

evidence: Line 143 text ("The migration does not issue a provider delete for the omitted versioning entry. The new bucket resource takes responsibility for that configuration.") is the doc's own explanatory sentence describing its own worked…; source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md

source: repo:content/docs/iac/guides/building-extending/components/state-migrations.md

pass1 · behavior · high confidence

#63 ➖ Not a claim

content/docs/iac/guides/building-extending/components/state-migrations.md:161

These test sketches call the S3 migration directly with inline arrays of JSON-compatible state records. The expected array keeps the component and combines…

evidence: This text describes the PR author's own test sketch/example code design choices (inline arrays, omitted imports, comment placeholders) within their own documentation file, not a falsifiable third-party assertion.; source: content/docs/iac/guides/building-extending/components/state-migrations.md (self-description of authored example code)

source: content/docs/iac/guides/building-extending/components/state-migrations.md (self-description of authored example code)

pass3 · attribution · high confidence

#7 🤷 Unverifiable

content/docs/iac/concepts/resources/options/statemigrations.md:31

In the `stateMigrations` callback API, the registering URN can differ from the root's prior URN when Pulumi matches it through an alias.

evidence: (escalated from pass1 after exhausting its 12-turn cap) The `stateMigrations` API appears to stem from pulumi/pulumi issue #24045 ("Component state migration"), which is described as an enhancement request/initial version rather than…; source: WebSearch ran query "pulumi StateMigrationArgs urn args.urn component alias documentation"; top results (github.com/pulumi/pulumi/issues/24045, github.com/pulumi/docs/pull/21865) did not confirm the specific alias-matching detail; intuition: This describes new/unreleased engine behavior (state migrations callback API) that only pulumi/pulumi source or the…

source: WebSearch ran query "pulumi StateMigrationArgs urn args.urn component alias documentation"; top results (github.com/pulumi/pulumi/issues/24045, github.com/pulumi/docs/pull/21865) did not confirm the specific alias-matching detail

pass3 · behavior · low confidence

#10 🤷 Unverifiable

content/docs/iac/concepts/resources/options/statemigrations.md:33

In a `stateMigrations` callback result, every input URN must either remain in the result or have a successor mapping to a resource in the result, but not both.

evidence: The doc describes the contract of a brand-new, explicitly-marked "experimental" `stateMigrations` API: "Every input URN must either remain in the result or have a successor mapping to a resource in the result, but not both." GitHub code…; source: gh search code --owner pulumi "StateMigrationResult" (HTTP 429, rate-limited)

source: gh search code --owner pulumi "StateMigrationResult" (HTTP 429, rate-limited)

pass1 · behavior · low confidence

#15 🤷 Unverifiable

content/docs/iac/concepts/resources/options/statemigrations.md:67

The Go SDK exposes a `StateMigrationResult` type in the `github.com/pulumi/pulumi/sdk/v3/go/pulumi` package, documented at…

evidence: The pre-fetched page loaded (HTTP 200) but the truncated body shown is just the generic pkg.go.dev site chrome/header for the pulumi package page; it does not show the actual symbol listing or confirm a `StateMigrationResult` type exists…; source: https://pkg.go.dev/github.com/pulumi/pulumi/sdk/v3/go/pulumi#StateMigrationResult; intuition: source_hint cites a different anchor (#StateMigrationArgs) than the claim (#StateMigrationResult), suggesting…

source: https://pkg.go.dev/github.com/pulumi/pulumi/sdk/v3/go/pulumi#StateMigrationResult

pass2 · api-surface · low confidence

#42 🤷 Unverifiable

content/docs/iac/guides/building-extending/components/state-migrations.md:59

Pulumi state migration callbacks receive decrypted secret values inside their serialized secret envelopes.

evidence: (escalated from pass1 after exhausting its 12-turn cap) Search found the PRs implementing Pulumi state migration callbacks (pulumi/pulumi#24331, #24519, #24715, issue #24045), which describe callbacks receiving "the component's prior…; source: WebSearch ran query "Pulumi component state migration callback secret envelope"; top results (github.com/pulumi/pulumi/pull/24331, /issues/24045) describe the callback state-migration mechanism but not secret-decryption semantics within it; intuition: Claim conflates two possibly distinct things—"decrypted secret values" vs "serialized secret envelopes"—which may be…

source: WebSearch ran query "Pulumi component state migration callback secret envelope"; top results (github.com/pulumi/pulumi/pull/24331, /issues/24045) describe the callback state-migration mechanism but not secret-decryption semantics within it

pass3 · behavior · low confidence

#53 🤷 Unverifiable

content/docs/iac/guides/building-extending/components/state-migrations.md:148

Pulumi supplies the component itself first to migration callbacks, followed by its descendants in snapshot order, representing the subtree defined by parent…

evidence: (escalated from pass1) Web search confirms Pulumi's state migration callbacks transform "the recorded state of a resource and its descendants before the engine computes the update," and a related PR (#24552) discusses subtree ordering…; source: WebSearch ran query "Pulumi component state migration callbacks descendants snapshot order"; results describe the feature generally but not the specific traversal-order semantics

source: WebSearch ran query "Pulumi component state migration callbacks descendants snapshot order"; results describe the feature generally but not the specific traversal-order semantics

pass3 · behavior · low confidence

#56 🤷 Unverifiable

content/docs/iac/guides/building-extending/components/state-migrations.md:150

Ordinary string values are not rewritten by Pulumi's successor-mapping rewrite during a state migration.

evidence: (escalated from pass1) This claim describes internal behavior of Pulumi's state migration successor-mapping rewrite logic, which is product/engine behavior not documented on public web pages accessible via search.; source: WebSearch not attempted; claim describes Pulumi engine internal behavior

source: WebSearch not attempted; claim describes Pulumi engine internal behavior

pass3 · behavior · low confidence

#58 🤷 Unverifiable

content/docs/iac/guides/building-extending/components/state-migrations.md:153

A pulumi up (update) persists the state migration before proceeding with the affected resources.

evidence: (escalated from pass1 after exhausting its 12-turn cap) Related engine PRs confirm state migration callbacks run during updates/previews and transform recorded state before the engine computes the update, but no source found specifies…; source: WebSearch ran query "Pulumi state migrations pulumi up persists migration before proceeding"; top results (github.com/pulumi/pulumi/pull/24715, pull/24331) describe callback mechanics but not this specific persistence-timing behavior; intuition: This describes internal engine sequencing behavior (when state gets persisted relative to resource operations) that…

source: WebSearch ran query "Pulumi state migrations pulumi up persists migration before proceeding"; top results (github.com/pulumi/pulumi/pull/24715, pull/24331) describe callback mechanics but not this specific persistence-timing behavior

pass3 · behavior · low confidence

#59 🤷 Unverifiable

content/docs/iac/guides/building-extending/components/state-migrations.md:153

A pulumi update persists the migration before proceeding with the affected resources.

evidence: (escalated from pass1 after exhausting its 12-turn cap) Search results confirm Pulumi's component state migration feature exists and that callbacks "transform the recorded state of a resource and its descendants before the engine…; source: WebSearch ran query "Pulumi component state migration pulumi update persists migration before proceeding"; top results didn't directly address the persistence-ordering claim

source: WebSearch ran query "Pulumi component state migration pulumi update persists migration before proceeding"; top results didn't directly address the persistence-ordering claim

pass3 · behavior · low confidence

#65 🤷 Unverifiable

content/docs/iac/guides/building-extending/components/state-migrations.md:195

Pulumi rejects state-changing migrations when there are pending operations in the snapshot, requiring resolution with pulumi refresh before migrating.

evidence: The doc states: "Pending operations in the snapshot. Resolve them with `pulumi refresh` before migrating." This is a specific engine-behavior claim about the new state-migrations feature. GitHub code search against pulumi/pulumi was…; source: gh search code (rate-limited, HTTP 429) against pulumi/pulumi; content/docs/iac/guides/building-extending/components/state-migrations.md L195-201

source: gh search code (rate-limited, HTTP 429) against pulumi/pulumi; content/docs/iac/guides/building-extending/components/state-migrations.md L195-201

pass1 · behavior · low confidence

#16 ❌ Contradicted

content/docs/iac/concepts/resources/options/statemigrations.md:73

There exists a 'state migrations guide' page at /docs/iac/guides/building-extending/components/state-migrations/ containing a complete example.

evidence: Directory listing of content/docs/iac/guides/building-extending/components/ in pulumi/docs (master) returns only build-a-component.md, packaging-components.md, testing-components.md, and when-to-build-a-component.md — no…; source: gh api repos/pulumi/docs/contents/content/docs/iac/guides/building-extending/components

source: gh api repos/pulumi/docs/contents/content/docs/iac/guides/building-extending/components

pass1 · url · high confidence

#68 🚩 Flagged

content/docs/iac/guides/building-extending/components/state-migrations.md:193

A callback that returns no result can remain attached when using update plans or targeted updates, the restrictions on state-changing results do not require rem

readthrough: orphaned-structure

source: readthrough pre-step

preflight · readthrough-orphaned-structure · high confidence

Findings

ID	Bucket	File:lines	Status	Disposition
F2	⚠️ Reviewer check	content/docs/iac/guides/building-extending/components/state-migrations.md:193-203	accepted-as-is	accepted — author accepted all open items; stated reason: "shut up"
F3	⚠️ Reviewer check	content/docs/iac/concepts/resources/options/statemigrations.md:31	accepted-as-is	accepted — author accepted all open items; stated reason: "shut up"
F4	⚠️ Reviewer check	content/docs/iac/concepts/resources/options/statemigrations.md:33	accepted-as-is	accepted — author accepted all open items; stated reason: "shut up"
F5	⚠️ Reviewer check	content/docs/iac/concepts/resources/options/statemigrations.md:67	accepted-as-is	accepted — author accepted all open items; stated reason: "shut up"
F6	⚠️ Reviewer check	content/docs/iac/guides/building-extending/components/state-migrations.md:59	accepted-as-is	accepted — author accepted all open items; stated reason: "shut up"
F7	⚠️ Reviewer check	content/docs/iac/guides/building-extending/components/state-migrations.md:148	accepted-as-is	accepted — author accepted all open items; stated reason: "shut up"
F8	⚠️ Reviewer check	content/docs/iac/guides/building-extending/components/state-migrations.md:150	accepted-as-is	accepted — author accepted all open items; stated reason: "shut up"
F9	⚠️ Reviewer check	content/docs/iac/guides/building-extending/components/state-migrations.md:153	accepted-as-is	accepted — author accepted all open items; stated reason: "shut up"
F11	⚠️ Reviewer check	content/docs/iac/guides/building-extending/components/state-migrations.md:195-196	accepted-as-is	accepted — author accepted all open items; stated reason: "shut up"

Editorial stances

The extractor found no positioning or comparison language in this PR's added lines.

Investigation log

cross-sibling-reads: 0 of 22 siblings
external-claim-verification: 45 of 67 claims verified (9 unverifiable, 1 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 56 Pass 1, 1 Pass 2 (verified 0, contradicted 0, unverifiable 1), 10 Pass 3 (verified 2, contradicted 0, unverifiable 8).
cited-claim-spot-checks: 1 of 1 cited claims fetched and compared
frontmatter-sweep: ran on body + meta_desc
temporal-trigger-sweep: ran (recency words present in diff; spot-check in-review)
code-execution: ran static/programs/aws-s3-state-migration-go, static/programs/aws-s3-state-migration-python, static/programs/aws-s3-state-migration-typescript, static/programs/component-state-migrations-option-go, static/programs/component-state-migrations-option-python, static/programs/component-state-migrations-option-typescript (CI test harness gates parse + imports)
code-examples-checks: ran (3 specialists: structural, existence, body-code-coverage); 0 findings
editorial-balance-pass: not run (not under content/blog/)

Triaged

{
  "file": "content/docs/iac/concepts/resources/options/statemigrations.md",
  "from_bucket": "outstanding",
  "id": "F1",
  "kind": "spurious",
  "note": "the linked guide page is added by this same PR, and the Hugo build resolves the link."
}

{
  "file": "content/docs/iac/guides/building-extending/components/state-migrations.md",
  "from_bucket": "author-answer",
  "id": "F10",
  "kind": "spurious",
  "note": "duplicate of F9 \u2014 the same sentence on L153 was extracted twice."
}

History

2026-09-24T11:38:09Z 8364635
initial review (pending publication)
2026-09-24T11:46:43Z 8364635fdb
@julienp bulk-accepted all 9 open items (F2-F11) as-is; no fixes pushed