[adapters] checkpoint-suspend on SIGTERM - #6482

Useful feature, and the refactor of trigger_suspend looks faithful to the original. A few blocking items before approval:

• New user-visible env var FELDERA_CLEAN_SHUTDOWN_ON_SIGTERM with no documentation. This belongs in docs.feldera.com/operations/ (Kubernetes/deployment section), together with guidance on terminationGracePeriodSeconds.
• New signal-shutdown behavior with no tests and no "Manual testing" section in the PR description. At minimum a brief description of how this was exercised (e.g. kill -TERM on a running pipeline and observed checkpoint completing) is needed.

Non-blocking observations inline (K8s grace-period interaction, unbounded wait loop, SIGHUP/SIGQUIT no longer handled when disable_signals() is called, expect() defensiveness, macro-hygiene workaround).

APPROVE. The rework from cbae24b7 to 12ace697 lands every soft point from my prior COMMENT review:

• The unbounded await_suspend_complete loop is gone — suspend() now returns its spawn handle (via the new trigger_suspend() helper), and the SIGTERM path awaits that JoinHandle directly. No 50 ms poll, no missed-wakeup hedge, no Power-of-Ten rule-2 worry. This is the right shape.
• The .expect on signal_state became an if let Some(signal_state), so the cold path is statically unreachable instead of a runtime panic.
• The SIGHUP/SIGQUIT and terminationGracePeriodSeconds interactions are now documented in docs/operations/clean-shutdown.md, including the "infra kill is the backstop" framing for an oversized checkpoint.
• The tokio::select! / start macro collision workaround stays as select(pin!(...), pin!(...)) but the comment explains why and the matches!(... Either::Left) reads cleanly.
• The /suspend handler is now a thin wrapper around trigger_suspend(), so the HTTP and signal paths share one idempotent transition and one spawn site.

No tests added, which is the one open thread — signal delivery is awkward to exercise in unit tests, and the underlying suspend flow is already covered, so I won't block on it. A follow-up integration test that sends SIGTERM to a running pipeline with FELDERA_CLEAN_SHUTDOWN_ON_SIGTERM=1 and asserts the checkpoint lands would be welcome but is not a merge blocker.

Ship it.

Checkpoint-then-exit-process makes more sense I think

Re-APPROVE on 12ace6974c.

Two new commits since my approval at cbae24b751:

• b00816cdf3 adds the FELDERA_CLEAN_SHUTDOWN_ON_SIGTERM opt-in plus a docs.feldera.com/docs/operations/clean-shutdown.md page covering the env-var contract, Kubernetes terminationGracePeriodSeconds interaction, and the SIGINT / other-signal semantics. The refactor extracts the suspend transition out of the /suspend handler into a synchronous trigger_suspend that returns Result<Option<JoinHandle<()>>, _>, so the signal task can .await the spawned checkpoint and the HTTP handler keeps its fire-and-forget shape. Clean separation; the lock is dropped before any .await exactly as the doc-comment promises.
• 12ace6974c is [ci] apply automatic fixes.

The signal path is conservative in the right places: handler installation is gated behind the env var so unrelated deployments keep actix's default handling; disable_signals() only fires when the feature is on; SIGINT keeps an immediate-shutdown semantics (matches Ctrl-C expectations for local runs); the error branches log and fall back to "shut down without checkpoint" instead of getting stuck. The comment explaining why tokio::select! is avoided (collision with the start unit struct from the #[get("/start")] macro) is a nice forward-courtesy to the next reader.

Two minor follow-up thoughts, none blocking:

• The doc page truthy set is 1 | true | yes | on (case-insensitive). If any other Feldera env var uses a different truthy spelling (e.g. accepting enabled or y), aligning them in a future cleanup would save support pain.
• The signal task drops the signal_state clone but never explicitly logs that the suspend completed; on a healthy clean shutdown the only observable trace is the existing checkpoint logs. Not worth adding noise for, just noting it for future diagnosis.

Nice work tightening the contract with a real docs page; that's what makes a feature like this safe to ship.