## Summary

Ports Python PR
[langchain-ai/langgraph#7274](langchain-ai/langgraph#7274)
("allow graph to graceful shutdown/drain by request") to LangGraphJS.
Adds cooperative, between-superstep draining so a run can be asked to
stop at the next superstep boundary, persist its checkpoint, and surface
a resumable terminal error.

This is the JS PR for the **Graph draining / graceful shutdown** parity
unit.

## What's added

- **`RunControl`** (new `pregel/runtime.ts`, exported from
`@langchain/langgraph`): a run-scoped handle with `requestDrain(reason =
"shutdown")` and read-only `drainRequested` / `drainReason`.
- **`GraphDrained`** (`errors.ts`): a `GraphBubbleUp` subclass carrying
`reason`, thrown when a run exits early due to drain. Plus an
`isGraphDrained` guard.
- **`control` option** on `invoke` / `stream` / `streamEvents` /
`invoke`'s functional-API equivalents. It is surfaced on
`runtime.control` (nodes can read it or call `requestDrain()`), and
propagated into subgraphs. A fresh `RunControl` is provided per run when
none is passed.

## Semantics (cooperative, between-superstep)

`requestDrain()` flips a flag. The Pregel loop checks it at the top of
each `tick()`, **after** the previous superstep's writes have been
applied and checkpointed and the next tasks have been prepared. It never
preempts work that is already running.

| Scenario | Behavior |
|---|---|
| Node mid-execution | Runs to completion; drain takes effect at the
next superstep. |
| Graph naturally finishes on the same tick where drain was requested |
Returns normally (status `done`). No `GraphDrained`. Caller can inspect
`control.drainRequested`. |
| More tasks remain | Saves the last completed superstep's checkpoint
(also under `durability: "exit"`) and throws `GraphDrained(reason)`.
Resume with `invoke(null, config)`. |
| Subgraph requests drain | `GraphDrained` bubbles up through the parent
loop and stops it at its own next boundary; the parent's checkpoint is
saved and resumable. |

Draining does **not** cancel async work. Pair it with an `AbortSignal`
if you need a hard upper bound (see the `drain then cancel after a
graceful timeout` test).

## Files

- `errors.ts` — `GraphDrained` + `isGraphDrained`
- `pregel/runtime.ts` — `RunControl`
- `pregel/runnable_types.ts` — `control?: RunControl` on `Runtime`
- `pregel/types.ts` — `control` on `PregelOptions`
- `pregel/utils/config.ts`, `constants.ts` — config-key wiring
- `pregel/loop.ts` — `"draining"` status + drain check at the tick
boundary
- `pregel/index.ts` — option wiring + raising `GraphDrained`
- `pregel/runner.ts` — subgraph drain bubble-up handling

## Tests

`libs/langgraph-core/src/tests/run_control.test.ts` (14 tests, all sync
+ async where applicable):
drain stops the next step (sync/async), terminal-step drain finishes
normally, exit- and default-durability resume, pre-drained control,
subgraph → parent bubble + resume, external concurrent drain,
drain-then-cancel via `AbortSignal`, reading/`requestDrain()` via
`runtime.control`, `stream()` accepts control, and functional-API
in-flight `task` futures still resolve. Full package suite passes (1358
+ 14, 0 failures); lint and format are clean.

## Notable divergence from Python

Python added `"drained"` to a local `SubgraphStatus` literal. The JS v3
stream lifecycle uses `AgentStatus` from the external
`@langchain/protocol` package, which has no `"drained"` member, so
`GraphDrained` propagates through streams as the terminal error rather
than as a new lifecycle status. The parity-relevant signal — the
`GraphDrained` exception — is what consumers catch. Noted in the
changeset.

## Source

- Python PR: langchain-ai/langgraph#7274
- Parity plan section: Graph draining / graceful shutdown