docs: publish the support matrix, durability contract, and operator runbook

[smiggleworth]

Summary

Replace scattered implementation-oriented notes with a truthful, test-linked operator and adopter documentation set: support status, durability semantics, recovery, cloud setup/preflight, performance sizing, migration/rollback, and incident troubleshooting.

Evidence

Audited baselines:

• Pants: 28585a10551d9c636f2c945ec39d4f21aab6f1f3 (origin/main)
• Midge: 115bf31a62886e74f4226fe59c97af6e2c3e6c14 (origin/main)

Pants currently documents architecture, performance, dependency injection, testing, and an outdated Midge qualification procedure. It does not have a single current support matrix, transaction/durability contract, operator runbook, release/stability policy, or migration/rollback guide. Current Midge provides those adoption boundaries explicitly.

This gap matters for the first real-world all-US-address workload: operators need to know what is bounded, what is durable, which provider modes are qualified, how timeouts should be interpreted, and how to recover without inventing procedures during an incident.

Requirements

Create or consolidate documentation under docs/ for:

Support and stability matrix

• Target frameworks, operating systems/filesystems, architectures, storage modes, cloud providers, compression/checksum modes, and dependency-injection package.
• A status vocabulary such as implemented, tested, qualified, experimental, deferred, and unsupported, with objective evidence links.
• Explicit distinction between API availability, simulated/provider-shaped testing, and live-provider production qualification.
• FORMAT/WAL/SST/manifest/lease compatibility baseline and the pinned Midge revision.

Public durability and transaction contract

• Commit acknowledgment points by durability/storage mode.
• Snapshot/isolation/conflict behavior, TTL/expiry, range deletes, column families, and reopen/recovery expectations.
• Admission timeout, runtime response timeout, provider timeout, cancellation, and outcome-unknown semantics.
• Writer epoch, lease fencing, and which operations are safe or unsafe to retry.

Operator runbook

• Capacity planning for memory pools, block cache, memtables, disk, WAL, SSTs, compaction headroom, file descriptors, and cloud request budgets.
• Open/startup, normal shutdown, forced termination, reopen, strict versus salvage recovery, backup/restore, and evidence-preserving incident steps.
• Symptoms and response for lease loss, stalled flush/compaction, cloud authorization/endpoint failures, corruption diagnostics, disk full, memory pressure, and timeout/late completion.
• Exact observable metrics/log fields and alert suggestions without claiming unsupported SLOs.
• Safe collection of diagnostic evidence with credential/key/value redaction.

Cloud setup and preflight

• Provider-specific configuration for AWS S3, S3-compatible, Azure Blob, GCS, and OCI at their actually supported status.
• Least-privilege capability guidance and clear separation between structural validation, read-only preflight, provider-shaped tests, and destructive qualification.
• Endpoint/TLS, path-style, namespace/container/bucket/prefix, credential-source, and lease topology guidance.

Adoption, migration, and rollback

• Minimal async quick start for core and Pants.DependencyInjection using the current public API.
• Migration from a compatible Midge-created database and rollback/reopen by the pinned Midge baseline.
• Release/stability policy for public APIs, persisted formats, configuration defaults, and NuGet package versions.
• Upgrade checklist with backup, compatibility qualification, rollout, observation, and rollback steps.

Acceptance criteria

• A root documentation index links every operator/adopter document and contains no dead paths or commands.
• Every support-matrix claim links to an automated test/workflow, a specific qualification record, or is labeled unqualified/experimental.
• Durability documentation states the acknowledgment point and timeout/cancellation outcome for each mode.
• The runbook gives evidence-preserving procedures for crash recovery, corruption, disk/memory pressure, cloud failure, and lease loss.
• Cloud guidance contains no secrets and is reviewed against each public configuration type.
• Quick-start samples compile against locally packed packages and use idiomatic async disposal/options.
• Migration and rollback are exercised by the bidirectional compatibility lane from compatibility: restore executable bidirectional Midge qualification and refresh the baseline #224.
• No document calls Pants production-ready or OCI-qualified without matching evidence.
• No user-facing CLI is documented unless separately approved and implemented.
• Documentation link/command/sample checks run in CI, and formatting plus Release tests pass.

Suggested sequence

1. Inventory every current claim, command, and public option; remove or label stale claims.
2. Write the support/status vocabulary and matrix first.
3. Derive the durability contract from tests and implementation evidence.
4. Build the runbook and provider setup around verified failure modes.
5. Compile/test quick starts and exercise migration/rollback through compatibility: restore executable bidirectional Midge qualification and refresh the baseline #224.
6. Add CI checks for links, commands, and samples.

Dependencies and non-goals

• Documentation can begin immediately, but final timeout/cloud/compatibility text depends on runtime: bound synchronous command responses and expose abandoned/late outcomes #220, cloud: preserve durability and fencing obligations across runtime deadlines #221, cloud: add typed validation, read-only preflight, and first-class OCI configuration #222, lease: make the primary lease TTL configurable and honor it end to end #223, and compatibility: restore executable bidirectional Midge qualification and refresh the baseline #224.
• This issue documents measured/qualified behavior; it does not create unsupported guarantees or replace implementation tests.
• It does not add a CLI, dashboard, hosted documentation service, or marketing site.