Package versioning

@azohra/meteo.briefing (currently 0.6.2) versions the read side: contract guards, derivations, analysis, comparison, transport, history, scene graph, SVG renderer, tokens, and the scene-derived key. The package version is independent of every document’s schemaVersion. Compatibility lists the document families and explains how to read across their versions.

The package aims to follow semantic versioning. While it is below 1.0:

• patch releases within one minor line are backwards-compatible corrections;
• a minor release may change a public TypeScript or JavaScript API, and the changelog and the TypeScript docs describe the change; and
• a deprecation names the replacement and the release at which the old export may be removed.

Pin an npm range that suits your tolerance for change, validate every external document, and test both deterministic and ensemble examples. Branch on the shape of the scalar values and on the declared capabilities. Code that hard-codes a model name breaks on the next catalogue entry.

Finding vocabularies

Three sets of finding kinds are versioned separately from the package and from each other:

Constant	Current value	Defined in	What it versions
ANALYZE_VOCABULARY_VERSION	5	briefing/src/analyze/vocabulary.ts	The single-profile finding kinds
COMPARE_VOCABULARY_VERSION	3	briefing/src/compare.ts	The cross-model comparison kinds
RUN_COMPARISON_VOCABULARY_VERSION	2	briefing/src/history/compare-runs.ts	The run-comparison kinds

The current release publishes site-forecast documents at schemaVersion: 2. Its analysis and comparison envelopes use the profile contract’s Mps suffix for speeds (wstarMinMps, peakThermalVelocityMps, meanWindMps, directionFloorMps, and the rest). Envelopes serialized under earlier vocabularies keep the old bare Ms field names, and the runtime version check catches the mismatch.

Release tags are snapshot boundaries

Treat each package release tag as a snapshot of the API and the SVG output, and still validate each document’s own schemaVersion. The scene guide defines the current presentation options and scene fields. The SVG guide defines rendering, tokens, and the scene-derived key. The package changelog records what changed between releases.