Versioning and changelog

Both SDKs ship under SemVer. @humyn/nyra and humyn-nyra move in lockstep at the minor version: a 0.4.x TypeScript release expects a 0.4.x Python release, and the function-call schemas, evidence-map shape, error names, and audit canonicalization match byte-for-byte. Patch versions can drift across languages for language-specific bug fixes.

What counts as breaking

A change is breaking if any of these are true:

• A function-call tool is removed, renamed, or has a required parameter added.
• The evidence-map shape loses a field, renames a field, or changes a field's type.
• A typed error class is renamed or has a field removed.
• A scope constant is renamed.
• The audit canonical-payload field order changes.
• The webhook envelope shape loses or renames a field.
• A Severity band, a signal ID, or an instrument version constant changes meaning.

A change is not breaking if it adds a new optional field, adds a new tool, adds a new error subclass, or adds a new event type. Consumers that ignore unknown fields keep working.

Deprecation window

The SDK never silently removes surface. A removal goes through a one-minor-cycle deprecation:

1. 0.N: the field, tool, or class still works. The SDK emits a console warning on first use per process: "[Nyra] X is deprecated and will be removed in 0.(N+1). See: ...". The TypeScript types add /** @deprecated */. The Python types raise DeprecationWarning.
2. 0.(N+1): the surface is gone. The SDK raises a typed RemovedSurfaceError with a one-line migration hint and a link to the changelog entry.

A breaking change without a deprecation cycle ships only on a major (1.0, 2.0). v1 is still pre-1.0; the deprecation window is the practical contract today, and it has held for every change so far.

Where to read the changelog

Audience	Location
Product changes	nyra.us.com/changelog (release notes for the whole product)
SDK changes (TS)	@humyn/nyra package CHANGELOG.md
SDK changes (Python)	humyn-nyra package CHANGELOG.md
Schema changes	@humyn/nyra schemas/CHANGELOG.md (JSON Schema diffs, version-tagged)

Schema changes always reference the marketing-spec section they implement. If a schema diff cannot point to a spec section, it does not ship.

How to pin

Pin to a minor in production. Patch updates are safe to take automatically; minor updates need a quick read of the deprecation list.

{
  "dependencies": {
    "@humyn/nyra": "~0.4.0"
  }
}

[project]
dependencies = [
  "humyn-nyra ~= 0.4.0",
]

Both SDKs publish typed version constants so an agent can refuse to start against an unexpected runtime:

import { SDK_VERSION, SCHEMA_VERSION } from "@humyn/nyra";

if (!SDK_VERSION.startsWith("0.4.")) {
  throw new Error(`This agent expects @humyn/nyra 0.4.x, got ${SDK_VERSION}`);
}

from humyn_nyra import SDK_VERSION, SCHEMA_VERSION

assert SDK_VERSION.startswith("0.4."), f"expected 0.4.x, got {SDK_VERSION}"

SCHEMA_VERSION tracks the function-call and evidence-map schemas independently of the package version. An SDK patch can ship without a schema bump.

v2

v2 is in design. The shape of the change is on record: a stable, signed function-call schema baseline that backs onto a live auth server, with the same shape the v1 mock exposes today. There is no shipped date. When a date exists, it will land in the product changelog and in this page's updatedAt, not in a marketing tweet.

Until then, every v1 release is forwards-compatible with v2 at the shape level. Code written against the v1 mock will run against the v2 transport with no shape changes; the transport itself is the swap.