Define public API stability and deprecation policy for the 0.3.x line

[parthdongre]

Summary

Define which FrameVitals APIs and result schemas are considered public, how breaking changes are introduced, and how deprecations are communicated during the 0.x series.

Why

The public surface has grown significantly across analysis, contracts, gates, snapshots, planning, inspection, and structured result objects. Clear stability rules will make the project safer for real users and easier for contributors to evolve.

Scope

• Inventory supported top-level public APIs and result/config objects.
• Document what is stable, provisional, or internal.
• Define a deprecation window and warning strategy for renamed/removed APIs.
• Define compatibility expectations for serialized contracts and snapshots.
• Add regression tests for the most important public signatures/exports.

Acceptance criteria

• A documented public API policy exists.
• Public exports are clearly distinguished from internal modules.
• Deprecations use warnings before removal where practical.
• Snapshot/contract compatibility expectations are documented.
• Release notes have a standard section for breaking/deprecated behavior.
• Core public exports have regression coverage.

Priority: P1 — API design / release maturity
Suggested labels: api, documentation, compatibility