CultLib/docs/semver-policy.md

Semantic Versioning Policy

Operator ruling, 2026-09-17: semantic versioning is policy for every package CultLib publishes, strictly. A release that removes or changes public surface incompatibly is a major bump, full stop — not a judgment call left to the person cutting the release.

This document says what "breaking" means for each kind of surface this repo actually ships, and how a release is checked against it. See docs/nuget-packaging.md for how the managed/Unity packaging mechanics work; this document is the versioning contract those mechanics must satisfy.

The scar

org.gamecult.cultlib 1.0.60 removed CultInspectorAssetPath — public API — and shipped as a patch bump. Its own changelog entry is titled "Breaking"; the version number said otherwise. A reviewer relying on the number alone would have missed it. This is recorded as history, not fixed by renumbering: 1.0.60 stays 1.0.60. This policy, and the check below, exist so the next one is caught before it ships instead of written up afterward.

Packages in scope

Package	Kind	Published by
org.gamecult.cultlib	Unity UPM	scripts/build-unity-package.ps1, consumed by git tag
org.gamecult.caching.unity	Unity UPM	tagged directly (no build script; see "Coverage gaps")
org.gamecult.cultmath	Unity UPM	packages/cultmath/scripts/build-unity-package.ps1, consumed by git tag
@gamecult/cultcache-ts	npm	.github/workflows/publish-packages.yml
cultcache-py	PyPI	.github/workflows/publish-packages.yml
cultnet-py	PyPI	.github/workflows/publish-packages.yml
cultmesh-py	PyPI	.github/workflows/publish-packages.yml

Each package's tag prefix, changelog path and, for the packages that ship assemblies, the directory of tracked DLLs are declared in scripts/release-packages.mjs, the one copy. The check reads them by package name; no release script or workflow passes one.

Rust crates are consumed as pinned git revisions (see publish-packages.yml's own header comment) and are out of scope for tagged-release semver policing; a Cargo.toml version still exists and should follow this policy by convention, but nothing in this repo checks it mechanically today.

Releases are tags named <tagPrefix>-v<version>, with the prefix declared in scripts/release-packages.mjs. The check refuses a declaration in which two packages share a prefix or an entry lacks a string prefix or changelog.

What counts as breaking

Semver's ordinary rule — additive is minor or patch, anything a consumer's existing code or data can no longer rely on is major — applies per surface as follows.

Managed public API (org.gamecult.cultlib, NuGet packages, cultmath)

Breaking: removing or renaming a public type/member, changing a public member's signature or observable behavior in an incompatible way, tightening a public contract (new required parameter, narrowed accepted input), or moving a type across assemblies/namespaces without a compatible forwarder.

Not breaking: adding a new public member, type, or overload; widening an accepted type; deprecating (marking obsolete) without removing.

Unity package inspector attributes (org.gamecult.cultlib,

org.gamecult.caching.unity)

These ship as ordinary public API by the rule above, but get their own callout because they are easy to mistake for "just editor tooling": an attribute class, its constructor shape, and the serialized value shape it reads/writes are all public surface a consumer's [CultInspectorX(...)] usage and serialized scene/prefab data depend on. Removing or renaming an attribute, or changing what it expects a annotated member's persisted value to look like (as CultInspectorAssetPath to CultInspectorAssetGuid did in 1.0.60) is breaking.

Persisted wire format / store compatibility (CultCache)

Governed by src/GameCult.Caching/Contracts/cultcache-schema-compatibility.md and cultcache-persistence-format.md — read those for the authoritative rules. In semver terms: anything those documents classify as hard rejection (type change, reference/value change, one-vs-many change, target schema change, name/index lookup semantics change, a persisted schema with no compatible local candidate) is breaking for any package that reads or writes the format. Anything classified as soft-migratable drift (compatible schema id drift, an ignorable missing slot, a defaultable missing slot) is not breaking on its own, but changing what counts as soft-migratable — loosening or tightening the drift rules themselves — is breaking for whichever package owns that classification logic.

CultNet protocol surface

Breaking: a wire-incompatible change to a CultNet message, frame, or handshake shape; removing or repurposing a message type or field that another runtime's implementation depends on; changing routing, authority, or trust semantics such that a peer built against the previous protocol version misbehaves rather than cleanly failing. Additive, backward-compatible framing changes (a new optional field a receiver may ignore) are not breaking.

Native bridge exported functions (GameCult.Mesh.Quic.Native)

Breaking: removing or changing the signature/ABI of a CULTMESH_API (extern "C") exported function, or changing an exported function's behavior such that the existing managed P/Invoke caller (GameCult.Mesh.Quic.Native's C# side) or Rust caller (cultmath-core's equivalent #[no_mangle] extern "C" surface) no longer gets what it asked for. Swapping the underlying TLS/QUIC implementation (as 1.0.60 did, Schannel to OpenSSL MsQuic) is not breaking by itself as long as the exported v1 functions keep their signatures and behavior — 1.0.60's actual breaking change was the inspector attribute removal, not the bridge swap, and its changelog correctly filed the bridge swap under "Changed" rather than "Breaking".

Pre-1.0 packages

A package at 0.y.z (currently org.gamecult.cultmath, at 0.5.x) uses the standard pre-1.0 convention: MAJOR stays 0 during initial development, so MINOR carries what MAJOR means once the package reaches 1.0.0. Concretely:

• a breaking change bumps MINOR (and resets PATCH to 0);
• a non-breaking change bumps PATCH.

Leaving 0.y.z for 1.0.0 is a deliberate, separate decision (the API is now considered stable), not something the checker infers on its own.

What a release changelog entry must contain

Every published package keeps a CHANGELOG.md beside its manifest (unity/org.gamecult.cultlib/CHANGELOG.md and src/GameCult.Unity/Assets/Caching/CHANGELOG.md are the existing precedent). Each release adds a ## [<version>] section (the check also reads ## <version>, and either form followed by Keep a Changelog's - YYYY-MM-DD date, such as ## [0.4.0] - 2026-10-03) containing:

• a category subsection per change (### Added, ### Changed, ### Fixed, etc., following Keep a Changelog style);
• ### Breaking — this exact heading, this exact spelling — for any change that meets the "what counts as breaking" rules above. This heading is not decorative: the CI check below greps for it by name.
• enough detail that a consumer can tell what to change, in the style of the 1.0.60 entry (name the removed/changed symbol and its replacement).

A version with no changelog entry at all fails the check below, the same as a mislabelled one — an undocumented release is not a smaller sin than a mislabelled one.

First release of a package

A package with no CHANGELOG.md yet cannot release: the check refuses with "changelog not found". Its first release writes the file at the declared path, packages/<package>/CHANGELOG.md, with one section for the version being released. That version must still be exactly the next one after the package's nearest ancestor tag. As of 2026-10-03 the valid next versions are:

• cultcache-ts, after cultcache-ts-v0.14.0: 0.14.1, 0.15.0 or 1.0.0;
• cultcache-py, after cultcache-py-v0.3.0: 0.3.1, 0.4.0 or 1.0.0;
• cultnet-py and cultmesh-py, which have no tags: 0.1.0, their manifest version, as a first release. Run it from a clone with the tags fetched, or the check cannot tell a first release from a missing record.

On 0.y.z a ### Breaking section needs at least a minor bump.

Enforcement

scripts/check-changelog-semver.mjs is the mechanical check. Given a package name and the version being released, it reads the package's declaration from scripts/release-packages.mjs in --cwd (an unknown package or a missing declaration refuses), and:

1. derives the release record from git tag -l in --cwd. A same-prefix tag is one that starts <prefix>-v; one that is not <prefix>-vMAJOR.MINOR.PATCH refuses, naming the tag, and is never skipped. The previous release is the newest same-prefix tag strictly older than the version being released, by version order, that is also an ancestor of the commit being checked: a backport tagged later on another branch is not part of that history, so it never moves a rebuild's predecessor. A tag equal to the version does not exempt it and does not count as a previous release: there is no "already published" skip, so a rebuild or a CI re-run at a tagged version is measured against that version's predecessor, exactly as at release, and gets the same verdict. With no older tag, a newer one refuses (the version is older than every release), and a repository that holds no tag other than the version's own refuses, because a first release cannot be told from a missing record. Older tags of which none is an ancestor leave the predecessor unknown and refuse. Otherwise it is a first release, which no caller declares. A package that declares an assemblies directory is a first release only when no tag in the repository, under any prefix, tracks a managed assembly under that directory: such a tag means the package has shipped, so the declared prefix is wrong and the check refuses, naming the tag and the assembly. A tag snapshots the whole tree of this monorepo, so a tag tracking a package's directory proves nothing; only a managed assembly in the declared directory does. This is read from git, never from the changelog's prose. The version's own tag does not count, so a first release can be rebuilt. Only the declared directory counts: a package whose directory moved after its releases has none of its old path's tags counted, so its release under a misspelled prefix reads as new, and the move itself is caught only under the right prefix, where the declared directory holds no managed assembly at the previous tag. A package that declares no assemblies directory (the Python and TypeScript packages and the Caching Unity package) has no such proof: with no tag of its own prefix it is a first release. The suite test that pins every declared prefix guards it: each prefix is declared once, each workflow tag trigger must be a declared prefix, and each such package's prefix must be a workflow trigger or, for the Caching Unity package the workflow does not build, the prefix of tags that hold its own manifest at the tag's own version, so a typo or a copied prefix fails the suite. Nothing releases without the suite passing; see below for how each release path runs it. Releases run from a full clone with every tag (fetch-depth: 0 in CI), the recorded partial-tags-first-release. Tags that cannot be read (a --cwd that is not a git repository, or a tag whose tree cannot be listed) refuse;
2. requires a ## [<version>] changelog entry to exist at all;
3. classifies the version bump (major/minor/patch) against the previous version, refusing anything that is not exactly the next version in some lane — a skip, a reversal, or a repeat are all refused, not just wrong bump sizes;
4. when the release script supplies built assemblies (below), treats the release as breaking if the public API measurably lost or changed a member against the previous tag, whether or not the changelog says so; a measured break with no ### Breaking section is refused, naming the count, the first diagnostics, and the heading that must declare them;
5. if the release is breaking (a ### Breaking section, a measured break, or both), requires the bump to be at least major (or, pre-1.0, at least minor); a ### Breaking section with nothing measured is valid, because behavioural breaks are invisible to a signature comparison;
6. fails loudly, naming the package, the previous and new version, and (when relevant) the changelog heading or the measured diagnostics that triggered the requirement.

Additions are never a rule: adding a public member is not breaking (see above), and the check neither refuses nor demands a bump for one.

Measured input

A package whose declaration names an assemblies directory is measured, and the release must hand over one --api-built <dll> per assembly it built (plus --api-refs <dir> for directories that hold the built assemblies' dependencies). A package with no such directory takes no --api-built, and one that has it cannot omit it. The measured set is every managed assembly tracked under that directory, at any depth, at the previous tag, read as git blobs (no worktree, no network, unaffected by what the working tree tracks now) and keyed by file name. A DLL is managed when its PE header carries a CLI header; a native DLL has none and is not measured, and a tracked .dll that is not a PE image refuses. Two managed assemblies with one name refuse. The checker compares each built assembly with its namesake using Microsoft.DotNet.ApiCompat.Tool; each CPnnnn diagnostic is one measured break. Every managed assembly the previous tag tracked that the build no longer hands over is itself a measured break, whatever its name or place, so a release script passes every assembly it ships. A built assembly with no namesake at the tag is an addition and is not examined.

Measuring nothing is a refusal, never a pass. The check refuses, naming what is missing, when the previous tag tracks no managed assembly under the declared directory (a wrong or moved directory, or a tag that predates it); when git cannot read the tracked assemblies; and when the tool fails to measure (not installed, an unreadable assembly, a crash: a non-zero exit with no diagnostic line). A first release measures nothing.

The tool and the NETStandard.Library.Ref 2.1.0 reference assemblies are pinned in scripts/api-gate/ (.config/dotnet-tools.json and ApiRefs.csproj) and restored there by the check itself, so a release does not depend on any other tool in the repository's manifest. NuGet is needed until both are cached under scripts/api-gate. Both sides of every comparison resolve netstandard types through those reference assemblies, and the new side also through the built DLL's own directory and every --api-refs directory. No suppression file is kept: a suppression would be a second, silent declaration of a break, so a break is declared only under ### Breaking.

A passing measured run prints that unmeasured changes still need declaring.

Unmeasured changes

ApiCompat does not report these changes to a public member, and the check therefore passes them. Each is a breaking change under the rules above and is declared under ### Breaking, as behavioural breaks are:

• a member gaining or losing static;
• a parameter gaining or losing ref, out or in;
• a const field's value changing;
• an enum member's underlying value changing;
• a field gaining or losing readonly;
• a default parameter value changing.

The release scripts run the check once the assemblies under judgement exist, after the build and before anything is copied into the package.

Run it directly: node scripts/check-changelog-semver.mjs --package <name> --version <x.y.z> [--cwd <dir>] [--api-built <dll>... [--api-refs <dir>...]]. Any other option is a usage error (exit 2). Its own tests live in scripts/check-changelog-semver.test.mjs (node --test scripts/check-changelog-semver.test.mjs).

It is wired into:

• .github/workflows/publish-packages.yml, through scripts/release-after-suite.mjs, for cultcache-ts, cultcache-py, cultnet-py, and cultmesh-py, with fetch-depth: 0 so the checkout holds the tags;
• scripts/build-unity-package.ps1, for org.gamecult.cultlib;
• packages/cultmath/scripts/build-unity-package.ps1, for org.gamecult.cultmath;
• scripts/verify-caching-unity-release.ps1, for org.gamecult.caching.unity.

Each of those runs the check's own tests before it releases. The Unity release scripts run them before they call the check, and the tests pin that order. In publish-packages.yml the release step runs scripts/release-after-suite.mjs with the run's git ref. From one process it checks that a tag ref is the package's declared prefix and manifest version, runs these tests, runs this check for the tagged version, runs the package's own tests (npm test, or the Python package's unit tests), and only then the release action: npm publish for cultcache-ts, which it refuses on any ref but a release tag, and for the Python packages the sdist and wheel build, whose output is all the PyPI upload step uploads. The checks run with the known test-runner and token variables removed (NODE_OPTIONS, NODE_TEST_CONTEXT, any other NODE_TEST_* variable, and NODE_AUTH_TOKEN), so none of those can make the tests run nothing and pass, and only the release action receives the token. That list names known variables; it does not prove that no other inherited variable can affect a check. The npm Publish step and the Python sdist and wheel build step start the guard under env -u NODE_OPTIONS, so a NODE_OPTIONS preload set in the workflow's or job's env: cannot run code inside the guard before its first line. The gate is that call, not a step condition, so no if: or continue-on-error can release what a check refused. The tests compare each job's release steps with their expected text exactly, less the steps' if: lines. Removing the call is still possible, but only as a visible edit to those steps and to the tests.

The guard and that pin stop accidental workflow edits. They do not stop a deliberate one: an extra step that publishes, a workflow-level defaults: or env:, or a fake node on $GITHUB_PATH all pass them. Deliberate edits are review's job, as ruled in suite-gate-structural-not-parsed, and the pin does not try to parse the workflow for them. For the same reason it has no ban on shell or defaults: such a ban defends only against a deliberate edit, and it also refused harmless settings such as defaults.run.working-directory. A step-level shell: on a release step still fails the exact comparison. A recommendation for the operator, not something this repository can set: the Python job already runs in the pypi GitHub environment, as PyPI trusted publishing expects. Putting the npm job in an environment with required reviewers would make every npm release wait for a person's approval. That is a GitHub settings change.

org.gamecult.cultlib compiles CultMath from source and ships beside org.gamecult.cultmath, so its build refuses unless it declares exactly the CultMath package's version and every CultMath.dll it built equals the one that package tracks, byte for byte. Any CultMath source change therefore means: release org.gamecult.cultmath, declare its new version in org.gamecult.cultlib, then release org.gamecult.cultlib. The bytes also depend on the checkout and the toolchain. .gitattributes pins CultMath source to CRLF on every checkout, because the tracked DLL was built from CRLF source and line endings reach the DLL through the pdb's document checksums; a clone checked out before that rule may still hold LF files (git ls-files --eol packages/cultmath/src shows w/lf) until they are checked out again. The build needs a git checkout, and refuses up front without .git: the repo root maps to /_/ through git, so an archive or source zip would write its own path into the DLL. No global.json pins the .NET SDK, so the same refusal at unchanged source and CRLF checkout means this SDK or host differs from the one that built the tracked DLL.

Coverage gaps

publish-packages.yml only triggers on cultcache-ts-v*, cultcache-py-v*, cultnet-py-v*, and cultmesh-py-v* tag pushes — it does not build or gate the Unity UPM packages at all; those are consumed directly by git tag (unity/org.gamecult.cultlib, packages/cultmath/unity/org.gamecult.cultmath, src/GameCult.Unity/Assets/Caching), so a workflow trigger on their tags cannot be added to that file without also giving it a reason to check out and build Unity content it currently has no job for. The check is instead wired into the scripts that already run at Unity-package release time: build-unity-package.ps1 and packages/cultmath/scripts/build-unity-package.ps1 already verify version consistency between the built assembly and package.json, so the semver check runs alongside that as one more release gate. org.gamecult.caching.unity has no build script at all today — it is pure C# source tagged directly with no compile step — so scripts/verify-caching-unity-release.ps1 exists solely to run this check before that package is tagged; it is not a build script and does not become one.

None of this is enforced by a git hook or branch protection rule: it runs when someone remembers to run the Unity release scripts, the same way the existing assembly-version check does. A tag pushed by hand without running the release script bypasses both checks equally; closing that gap is a CI trigger on tag push for the Unity packages, not something this change adds.

What stays unmeasured: behaviour behind an unchanged signature, wire formats, native exports of the QUIC bridge, and the Caching Unity package's source (it has no assembly). Those rest on the ### Breaking declaration.

Rust crates (consumed as pinned git revisions, not tagged releases in the usual sense) and the CultNet protocol surface itself (no automated wire compatibility test currently gates a release) are policy by convention only — described above, not mechanically checked. Extending the checker to a Rust crate's Cargo.toml/CHANGELOG.md or to an automated CultNet interop compatibility gate is future work, not part of this change.

@gamecult/cultcache-ts, cultcache-py, cultnet-py, and cultmesh-py currently have no CHANGELOG.md file at all; the check refuses their next tagged release ("changelog not found at ") until each package's file exists. A release with no changelog is not a smaller problem than a mislabelled one. The next release of each creates its file: packages/cultcache-ts/CHANGELOG.md arrives with the document-variants work (hands/variants-c2a), and whoever cuts the next release of cultcache-py, cultnet-py or cultmesh-py creates that package's file. Backfilling changelog content for past releases would mean inventing release-note prose for history nobody here knows first-hand, so the gap stays named.