docs: define and freeze the v1 compatibility contract #116

Problem

session-peer now exposes several machine-consumed contracts: CLI JSON results, exit codes, session-peer://v1/reply URIs, MCP structured content, agent policy files, device state and backup manifests, and relay/control protocol schemas. Individual formats have tests and version fields, but the repository does not define which surfaces become stable at v1, which remain operational internals, or how additive and breaking changes are handled.

That ambiguity matters before #112 modularizes the core: “preserve existing behavior” needs a reviewable compatibility contract rather than only current implementation tests.

Proposed contract

Add a concise v1 compatibility document and link it from the CLI/reference, development and release documentation.

Classify at least these surfaces:

• CLI commands, options, exit-code meanings and human-output stability expectations;
• JSON result envelopes and optional/additive fields;
• versioned reply URIs and MCP structured content;
• policy, device state, backup manifest and operation-receipt schemas;
• endpoint E2EE framing and relay/control API versions;
• control public state, replay high-water state and deployment configuration;
• Python/Node/OS and Claude/Codex/Antigravity support levels.

For each surface state whether it is stable, additive-only, version-negotiated, operator-internal or experimental. Define the deprecation and migration rule for an incompatible change. Distinguish “supported”, “tested”, “best effort” and “experimental” so a successful one-time validation does not create an indefinite compatibility promise.

The Beta milestone freezes the proposed v1 contract. Stable v1 changes to a frozen surface must be additive or use its documented version/migration mechanism.

Acceptance criteria

• One English source document defines the compatibility tiers and all translated editions retain the same normative structure.
• Public stable JSON examples have golden fixtures that reject accidental field removal, type changes and exit-code changes while allowing documented additive fields.
• Reply URI, MCP, policy, device/backup and relay protocol fixtures round-trip through their production parsers.
• The support matrix names the Python floors for core/MCP/relay, supported OS boundaries and the agent versions actually exercised.
• Release notes identify contract additions, deprecations and migrations against this policy.
• refactor: modularize the core while preserving the standalone SSH artifact #112 references this contract and CI verifies that its generated standalone artifact preserves it.
• Internal control/replay storage is not accidentally promised as a user-editable public format.

Non-goals

• Freezing human prose or terminal layout byte-for-byte.
• Promising compatibility with undocumented third-party agent database schemas.
• Expanding supported platforms as part of documentation work; feat: support WSL relay receivers targeting native Windows Codex #110 owns the current WSL relay gap.
• Treating the hosted service's availability as part of the PyPI package compatibility promise.

This belongs in v1.0.0-beta and should land before the main implementation moves in #112.