Stability Policy

This is a customer-facing commitment, not an internal note. It is the direct answer to "open-source packages are unstable."

It applies to every package that ships an ./ops surface, and to @runstamp/contract itself. The conformance matrix is the evidence: it is generated from real gate runs against built artifacts, and its known gaps are listed rather than hidden.

1. Error codes are semver-major

A code is never removed or repurposed within a major version. Adding one is a minor. Branch on code, never on message text.

2. Messages are not contractual

Any message may be reworded in any release. If your code parses a message string, it will break, and that break is not a regression on our side.

3. Locator strings are stable

A locator addressing the same logical position in the same bytes produces the same string, across processes and platforms, for the lifetime of a major version. Locators carry the artifact hash, so a locator from one version of a document never silently resolves against another.

4. Determinism is a guarantee, not best-effort

Same input, same options, same version ⇒ byte-identical output, and a receipt that says so. A determinism regression is a P0.

deterministic: true in a receipt is a falsifiable claim: gate C7 re-runs the operation in a clean process and compares the output hash, and C8 fails the build if a receipt asserts determinism that C7 disproves. This is not decorative — the docx→PDF path shipped claiming determinism while stamping a wall-clock timestamp into every file, and C8 is what caught it.

5. Deprecation window

A minimum of two minor versions carrying a runtime notice before anything is removed. Breaking changes land only at a major, with a migration guide.

Exports currently inside that window are visible as warn on gate C13 in the conformance matrix.

6. The contract version is independent

CONTRACT_VERSION appears in every receipt and moves independently of package versions, so you can pin behavior across package upgrades and detect a contract change without diffing release notes.

7. The conformance matrix is public and continuously updated

Per package, per gate, with known losses and known gaps listed. A gate that passes vacuously is reported as a warning rather than a pass — a formality that always succeeds is worse than no gate, because it converts an unknown into a false assurance.

It is published at /docs/references/conformance and regenerated from ga/conformance.json, which is itself the output of pnpm contract:verify. If the page and the command disagree, the command is right and the page is a bug.

8. What experimental means, and how an operation leaves it

Every operation carries a stability field, visible in the operations reference and returned by GET /v1. Most of the catalog is experimental today, and until now the policy did not say what that meant or how anything escaped it — which made the label a permanent state rather than a stage.

experimental — the operation's contract may change within a major version. Its error codes, input schema and value schema are not yet covered by sections 1 and 3 above. Everything else in this policy still applies: it is gated, deterministic where it claims to be, and it will not silently lose data.

stable — fully covered by this policy. Changing its codes or schemas requires a major version and a migration guide.

An operation is promoted from experimental to stable when all five hold:

1. Two minor releases have shipped with its contract unchanged.
2. Every applicable conformance gate passes for its package — not skipped, not warned.
3. Its error codes and loss codes are complete: gate C5 confirms every code it can emit is declared, and C11 confirms it declares every loss it can cause.
4. It is exercised by a fixture in the conformance corpus, including at least one hostile and one boundary case (gate C18 checks the operation is covered; the corpus records the kinds).
5. Where it produces an Office or PDF artifact, that artifact has been opened in the real target application, not only validated structurally.

One-time initial-GA certification

For the first frozen 1.0.0 catalog only, committed initial-GA evidence may substitute for the two-shipped-minor history in criterion 1. This exception applies exactly once and only to the operations frozen into that catalog. It cannot be reused for later additions or promotions.

The evidence binds every operation's descriptor, schemas, executable implementation and loss declarations to deterministic hashes; requires all applicable conformance gates to pass with no warning or skip; requires nominal, hostile and boundary fixtures for the exact operation identity; requires three complete 120-document judge runs with every run and every format aggregate at or above 3.6/5; requires one explicit release-owner approval over a hash-bound 12-module HTML review bundle covering all 79 operations and all 120 rendered documents; and binds current real-application results for Office and PDF artifacts. Human approval is a veto rather than a score override. The repository verifier rejects missing operations, experimental labels, stale hashes, incomplete fixtures, warned or skipped gates, stale application evidence, a stale review bundle, or missing/non-owner approval. After 1.0.0, the ordinary two-shipped-minor rule applies without exception.

Demotion is possible and is not a breaking change: an operation may move from stable back to experimental only at a major version, because the promise attached to stable is what a caller relied on.

What is not gated by payment

Every rendering capability ships in the open-source packages: font embedding, complex-script shaping, validation, repair, accessibility auditing, template assembly, formula evaluation, PDF/A, tagging and digital signatures.

Correctness is not a paid feature. Until 2026-08-12 some of it was, and the consequence was concrete: the published PDF package could not embed a fallback font, so every character outside Latin-1 became ? — and the validation and repair APIs a caller would have needed to detect that damage were themselves behind the same paywall. A conformance matrix would have needed a tier axis, which would have meant the contract guaranteed nothing on its own.

Paid tiers buy hosted operation, agent actions, and governance — audit trails, provenance receipts and policy gates.