Tracing: always export error and slow traces, plus launch policy docs (#474)

[Depo-dev]

Carries #474 (always-export error/slow traces, API stability policy, launch checklist, rollback runbook) with test coverage added for the sampler.

#474 was merged onto this branch rather than straight into dev, matching how #469, #471 and #473 were handled.

What lands

Always-export error and slow traces (#457) — the substantive piece, and the design is right.

Head sampling decides at span start, before it can know a request will fail. A low fixed ratio therefore means the one failing trace you actually need is almost never the one kept. This fixes that in two halves:

• recordOnlySampler returns RecordOnly instead of Drop for spans the ratio sampler would discard, so the span is still recorded
• alwaysKeepExporter inspects each finished span and exports it if it errored or ran longer than 2s, discarding the rest

Net effect: every error and every slow request is exported regardless of ratio, while ordinary traffic still samples normally.

API stability policy (#458) — docs/API_STABILITY.md: what /v1/ promises, what may change freely, what forces a /v2/, how experimental endpoints are marked, and the deprecation mechanism.

Launch checklist (#459) and rollback runbook (#460) — both as documents.

Added on top (bf4ffa0)

#474 shipped the sampler with no tests, and this logic breaks silently: a Drop decision cannot be reconsidered at export time, so reverting RecordOnly to Drop would restore exactly the behaviour the change exists to prevent, with nothing failing.

Added coverage for both halves:

Test	Pins
TestAlwaysRecordSamplerNeverDrops	never returns Drop, checked at ratio 0 so a surviving span proves RecordOnly kept it
TestAlwaysKeepExporter...	errors kept, slow spans kept, fast successful spans discarded
boundary case	a span exactly at the threshold is discarded, so > cannot drift to >=

Both assertions were verified against deliberately broken copies of the sampler — switching RecordOnly back to Drop fails the first, relaxing the comparison fails the boundary case. A passing test that cannot fail is worth nothing, so this was checked rather than assumed.

Issue status

Closed #458 by hand — the policy covers every criterion. Auto-close does not fire when the base is not the default branch.

Left open with specifics recorded on each:

• launch: trace sampling tuned so incidents are debuggable and the bill is not surprising #457 — trace id is still not correlatable with the request id in logs, and indexer spans do not yet cover the poll cycle (RPC fetch → decode → DB write → Redis publish). Also unquantified: RecordOnly means every span is fully recorded in memory even when never exported, so memory cost is now paid on 100% of requests rather than the sampled fraction. Worth measuring under the soak test — it is the one real trade-off here.
• launch: full pre-launch verification checklist executed end to end #459 — the checklist is a template with every row blank. The issue asks for it to be executed, with evidence and sign-off per gate. Several rows depend on issues still open (launch: automated Postgres backups with a restore we have actually performed #431, launch: chaos testing for RPC, database, and Redis outages #439, launch: sustained soak test at projected launch load #440, launch: all five SDKs regenerated, tested, and published against the frozen spec #429).
• launch: rehearse the rollback before we need it #460 — the runbook is written but the rollback has not been rehearsed. The failure modes that matter (a migration that will not reverse, an image tag that no longer exists) only appear when you try.

Worth flagging from the rollback runbook

The author checked and found database/migrations/ has 25 forward migrations and zero .down.sql files — so no migration is reversible in any automated sense today, and a rollback across a schema change means hand-writing reverse SQL under incident pressure.

They flagged it rather than papering over it, and recommend requiring a .down.sql per migration plus expand/contract for anything not cleanly reversible. That is arguably its own issue and blocks #460.

Verification

go build, go vet, gofmt and go test ./... all pass.

Also cherry-picked the apk upgrade fix for CVE-2026-14456 from integration/launch-fixes, since this branch is off dev and would otherwise fail the same required trivy check.