Upgrade Expectations

The package is now on its stable line. That means the documented public surface should not drift casually, and any breaking change should be exceptional, explicit, and easy to understand.

What The Project Tries To Preserve

The project already tries to preserve some boundaries by default.

The most important ones are:

documented user-facing entrypoints
documented default option posture
confidence labels and their meaning
anomaly categories that users are told to rely on
package-facing examples and recommended workflow shape
published runtime floor for the npm package

If any of those change, you should expect release wording and matching docs updates rather than a quiet drift.

What May Still Change More Freely

These areas can still move more freely than the core public contract:

internal implementation structure
maintainer-only docs
repository organization
website presentation details
additive helper surface that does not silently narrow or reinterpret existing behavior

That means an upgrade may still rearrange internals or presentation, but it should not casually rewrite the package-facing contract without saying so.

What Should Make You Read Release Notes Carefully

Treat an upgrade as more than routine if it changes:

exported names or preferred import paths
default strictness or anomaly posture
confidence semantics
anomaly semantics
translation policy behavior
runtime support policy
recommended workflow shape in the guides or README

Those are the places where careful users are building assumptions.

Safe Upgrade Workflow

If you are upgrading across release lines, use a simple check path:

read CHANGELOG.md
read the matching release notes if the line is larger than a patch
re-run the guide or example closest to your real usage shape
re-check focused imports if you use subpath entrypoints
re-check translation-policy and anomaly-handling expectations if you rely on them operationally
confirm your runtime still matches the published Node.js support floor

If your workflow depends heavily on:

strict rejection
anomaly names
translation-policy posture
stream finality or reconciliation behavior

then your upgrade review should be more deliberate than just "tests still pass."

Stable EntryPoint Expectations

The package already distinguishes between:

primary names that new code should prefer
compatibility aliases that still exist so older code does not break abruptly

The stable direction is now:

primary names stay stable and remain the documented first path
compatibility aliases stop looking equally canonical
focused subpaths already tighten around the primary public names instead of preserving every older alias forever
the root import and focused subpaths should tell the same primary API story

If you are writing new code today, prefer the documented primary names directly.

Today, that specifically means:

compareByHlc() is the supported direct HLC comparison helper
orderValidatedEvents() now means the narrowed public validated-events-plus-options path rather than the older repo-coupled internal coordination shape

So if you still rely on older compatibility-era usage shapes, treat 1.0.0 as the line where the documented primary path became the only supported current path.

What To Expect From Patch Releases

Patch releases should usually feel narrow.

You should mainly expect:

docs cleanup
website polish
metadata or release-process fixes
narrowly scoped bug fixes

If a patch release affects public behavior in a meaningful way, the release wording should make that obvious.

What To Expect From The Stable Line

Stable does not mean "nothing can ever change." It means:

the documented public surface is treated as preserved unless a release explicitly says otherwise
internal organization, maintainer-only notes, and additive polish can still evolve
compatibility direction should be explicit rather than hidden inside incidental code churn

So the right expectation is:

upgrades can still require attention
surprise should be avoided
silent contract drift is the thing the project is trying hardest not to do

If You Need Very Strict Upgrade Guarantees

If your environment needs minimal change risk:

pin exact versions instead of floating broadly
read the changelog before bumping
validate against your real replay, stream, or anomaly-handling workflow
prefer documented primary entrypoints and names over older compatibility aliases

That approach remains the safest way to evaluate changes against a real workload even on a stable line.

Practical Rule

Use this rule when upgrading:

trust the current documented surface, read the release wording when that surface changes, and do not rely on undocumented behavior just because it happened to work once.

That is the safest way to benefit from the package while keeping upgrade risk explicit and manageable.