[skip-tag:sdk] feat(sdk/engine): optional Resumer + LoadAndResume helper (3/4)

[lIang70]

Summary

Part 3 of 4 in the v0.2.x additive SDK batch. Tagging suppressed via
[skip-tag:sdk]; cumulative sdk/v0.2.9 tag will be cut on PR 4/4.

Adds a host-side helper to drive durable resume against any engine, and an
optional capability interface engines can implement to participate.

Surface

• Resumer optional interface — CanResume(Checkpoint) error. Engines that
  implement it get a chance to reject incompatible checkpoints (schema drift,
  expired runs, mismatched topology) before the resume is dispatched.
• IsResumable(Engine) bool / AsResumer(Engine) (Resumer, bool) — capability
  probes for callers that need to branch.
• ResumeContext (value-type) — per-attempt metadata: ExecID, AttemptID,
  StartedAt, Reason. Plumbed via WithResumeContext /
  ResumeContextFromContext using the standard context-key idiom.
• LoadAndResume(ctx, eng, host, store, run, board, opts...) — orchestrates
  the canonical host-side flow:
  1. Load checkpoint (if any) from CheckpointStore.
  2. Validate via Resumer.CanResume when the engine opts in.
  3. Hydrate Board from checkpoint state.
  4. Dispatch into Engine.Run with ResumeContext attached.
  • AllowFreshStart(bool) / OnMissing(handler) options control behaviour
    when no checkpoint is found.

Out of scope (deliberately)

• Engine.Engine / Run contracts are unchanged. Engines that don't implement
  Resumer still work — they simply get fresh-start semantics.
• Persistence backends are not touched.

sdk/engine/doc.go adds a worked example of the resume flow.

Test plan

• go vet ./engine/...
• go test ./engine/... -count=1
• New test file sdk/engine/resume_test.go covers:
  • Fresh start when no checkpoint and AllowFreshStart=true.
  • Disallowed fresh start returns the expected error.
  • Resume path hydrates board and propagates ResumeContext.
  • ExecID mismatch is rejected.
  • Resumer.CanResume rejection short-circuits before dispatch.

Release notes

Additive only; tag deferred to PR 4/4.

Made with Cursor