# Version contracts and documentation together

Keep operation identity, package releases and deployment revisions distinct when reviewing a change.

Source context: Source-guided
Source: https://github.com/lssm-tech/contractspec/blob/d58fa5b7de53a947811e5cc68346be028ce18528/packages/foundation/contracts-spec/src/versioning/refs.ts

## Know which version you mean

A contract's version identifies a particular declared behavior. A package version identifies a distribution artifact. A website or application revision identifies a deployment. Those numbers can change independently.

When reporting a problem, include the contract key and version plus the package versions or source commit. The documentation shell's version is not enough to identify the operation a consumer is executing.

| Identifier | Example of its role | Use it to |
| --- | --- | --- |
| Contract key + version | A specific operation definition | Resolve a referenced behavior |
| Package name + version | A published artifact | Reproduce dependencies and imports |
| Source commit | An immutable code snapshot | Inspect implementation and generated lineage |
| Deployment revision | A running application build | Correlate production behavior with release evidence |

## Use explicit references where reproducibility matters

The portable VersionedSpecRef model contains a key and version. OptionalVersionedSpecRef permits the version to be omitted, typically selecting the latest available definition through the owning resolver.

Use explicit versions in examples and compatibility tests that must be reproducible. If you intentionally use latest-version selection, test what happens when the registry receives a newer definition.

```typescript
export interface VersionedSpecRef {
  key: string;
  version: string;
}
```
Exact type shape from contracts-spec/src/versioning/refs.ts at d58fa5b7; comments omitted.

## Review the behavioral change

Compare inputs, outputs, named failures, policy requirements and effect expectations. Adding a required input can break an existing caller even when the handler remains unchanged. Tightening an approval rule can change which requests succeed.

Plan how old consumers transition: keep the old contract temporarily, provide an intentional mapping, or coordinate an upgrade. Do not silently repoint a stable example at a different behavioral contract.

## Publish the matching documentation

Pin source links and examples to the release they describe. Generate reference output from that same source and retain the provenance in the docs artifact. Update prose when an import path or execution guarantee changes.

When a source refactor preserves a compatibility facade, explain both the canonical owner and the supported historical import. Ownership moving between packages is not automatically a consumer migration.

## Related examples

- [Review an agent's migration proposal](https://lssm.co/examples/release-steward/): Follow a deterministic release migration through scoped subagents, digest-bound approval, and a draft PR receipt.