feat(core): add versioned graph checkpoint migrations

[shahryar (shahrryyar)]

Summary

This PR adds versioned graph checkpoint migrations so persisted graphs can evolve safely when their state schema changes.

It also addresses the reviewer feedback on duplicate migration registration: registering the same migration more than once now throws instead of silently returning. This makes incorrect configuration visible immediately and avoids hiding a bug in application setup.

What changed

• Added graph versioning and state migration options to graph compilation.
• Migrated checkpoints, pending writes, history, and manual state updates consistently.
• Added strict version validation, mutation isolation, checkpoint identity protection, and fail-closed handling for unsupported cases.
• Added tests, persistence documentation, and a changeset.

Verification

• pnpm lint passed.
• pnpm format:check passed.
• pnpm build passed: 25/25 tasks.
• Exact CI unit command passed with CI=1.
• LangGraph core: 80 test files, 1,648 passed, 4 skipped, no type errors.
• API tests: 210 passed, 1 skipped.
• Checkpoint validation: 3,138 passed, 6 skipped.
• git diff --check passed.

Thank you for the review and for pointing out the need to fail fast on incorrect migration configuration.

[changeset-bot]

🦋 Changeset detected

Latest commit: 8e02bf5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@langchain/langgraph	Minor
@langchain/langgraph-checkpoint	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@langchain/langgraph-checkpoint

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint@2608

@langchain/langgraph-checkpoint-mongodb

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-mongodb@2608

@langchain/langgraph-checkpoint-postgres

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-postgres@2608

@langchain/langgraph-checkpoint-redis

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-redis@2608

@langchain/langgraph-checkpoint-sqlite

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-sqlite@2608

@langchain/langgraph-checkpoint-validation

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-validation@2608

create-langgraph

npm i https://pkg.pr.new/langchain-ai/langgraphjs/create-langgraph@2608

@langchain/langgraph-api

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-api@2608

@langchain/langgraph-cli

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-cli@2608

@langchain/langgraph

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph@2608

@langchain/langgraph-cua

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-cua@2608

@langchain/langgraph-supervisor

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-supervisor@2608

@langchain/langgraph-swarm

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-swarm@2608

@langchain/langgraph-ui

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-ui@2608

@langchain/langgraph-sdk

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-sdk@2608

@langchain/angular

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/angular@2608

@langchain/react

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/react@2608

@langchain/svelte

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/svelte@2608

@langchain/vue

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/vue@2608

commit: 8e02bf5