contrib: add canary npm dist-tag rollout for pre-1.0 releases

[arandomogg]

Summary

Adds a self-contained reference under contrib/examples/issue-283-canary-dist-tag-rollout/ for a canary npm dist-tag stage for pre-1.0 releases, so an early-adopter consumer can validate a release before it becomes the default install for everyone.

Scoped entirely to contrib/ per CONTRIBUTING.md and contrib/README.md.

The problem

.github/workflows/publish.yml runs npm publish --provenance --access public with no --tag, so every tag pushed publishes straight to the latest dist-tag — the one every plain npm install vellar-sdk resolves to. There is no canary stage in between.

The rule

A semver prerelease tag (v0.7.0-canary.0, v1.0.0-rc.0) publishes to next; a plain release tag (v0.7.0) publishes to latest. This follows ordinary semver prerelease convention rather than inventing a bespoke "canary" grammar.

dist-tag	Who gets it
next	Nobody by default — only npm install vellar-sdk@next
latest	Everyone running plain npm install vellar-sdk

Promotion moves latest onto an already-published version via npm dist-tag add — it does not rebuild or republish, so what lands on latest is byte-for-byte the artifact that was validated as the canary.

Files

File	What it is
ROLLOUT.md	The process: the publish.yml change, a separate manual-dispatch promotion workflow, cutting a canary, the consumer-validation checklist, promoting, and real-registry verification.
canary-dist-tag-rollout.ts	The pure decision logic (distTagFor) plus a registry model (publish, promoteToLatest) making the flow testable. Runnable main() demo.
canary-dist-tag-rollout.test.ts	15 tests.
README.md	Orientation.

Keeping distTagFor in its own module rather than inline in a YAML run: block is deliberate — it's exactly the kind of one-line regex that's easy to get subtly wrong with shell quoting and impossible to unit-test in place. The repo already does this for release-affecting logic in scripts/verify-merged.mjs.

Every existing gate in publish.yml (npm audit, typecheck, test, build, provenance, and the tag/version verify step) is untouched and runs identically for a canary or a release, so a canary carries the same supply-chain guarantees as latest (security audit V-8).

Requirements checklist

• A next/canary dist-tag publishing step for the release workflow
• Promotion process from canary to latest documented (ROLLOUT.md)
• Checklist step for consumer validation before promotion (ROLLOUT.md)
• The full canary publish and promote flow tested end to end — as an automated test rather than only prose, pinning the key property that publishing a canary does not move latest. ROLLOUT.md additionally documents a one-time real-registry verification for a maintainer, since that can't safely run unattended in CI.

Test plan

npx vitest run contrib/examples/issue-283-canary-dist-tag-rollout

15 tests, all passing — including the end-to-end case walking publish canary → assert latest unmoved → reject a mistyped promotion → promote → assert latest moved and nothing new was published → plain release.

closes #283

[vercel]

@arandomogg is attempting to deploy a commit to the david's projects Team on Vercel.

A member of the Team first needs to authorize it.