Summary

The Shell State Provider integration guide depends on ShellState.runtime.lastSnapshot and ShellState.social.lastFailure, but the approved design contract in docs/shell-state-provider-design.md only documents runtime fields (step, events, backPressure) and social pending requests. The missing fields create drift between the design contract and the integration guidance.

Impact

• Contributors following the design doc cannot rely on lastSnapshot or lastFailure, creating uncertainty about whether the provider contract supports these values.
• The migration guide now references behaviour that is effectively "undocumented" in the design source of truth, weakening our guardrails for future changes.

Proposal

• Update §6.2 (APIs & Contracts) in docs/shell-state-provider-design.md to explicitly include the runtime.lastSnapshot snapshot pointer and the social.lastFailure metadata entry.
• Confirm any reducer defaults or telemetry expectations tied to these fields are also captured in the design (e.g., when lastFailure is reset).
• Cross-check the migration guide once the design is updated to ensure the references remain accurate.

References

• Guide usage: docs/shell-state-provider-guide.md lines 82-104 and 99-101.
• Current contract: docs/shell-state-provider-design.md §6.2 Data & Schemas / APIs & Contracts.