Skip to content

test: lock v1 wire shapes and public API; document deferred surface#159

Merged
joshua-temple merged 2 commits into
mainfrom
feat/v1-freeze-prep
Jun 14, 2026
Merged

test: lock v1 wire shapes and public API; document deferred surface#159
joshua-temple merged 2 commits into
mainfrom
feat/v1-freeze-prep

Conversation

@joshua-temple

Copy link
Copy Markdown
Collaborator

What this change does

Prepares the state 1.0 stability contract:

  • Wire + API freeze test. Extends the freeze tests beyond the five host interfaces they pinned, locking the serialized shapes and the core public signatures the 1.0 promise rests on. TestWireShape_Frozen reflects over the 10 serialized types (IR, State, Transition, Region, Invocation, Ref, ContextSchema, Descriptor, ParamSpec, BindingSpec) and pins their exported field names and json: tags (81 fields); compile-time assertions pin 10 load-bearing signatures (Forge, ForgeFor, Quench, Cast, Fire, LoadFromJSON, ToJSON, Registry.Palette, ToMermaid, ToDOT), each ending in its option tail so additive options need no edit. A rename or retag breaks the test; an additive field is a deliberate, documented test update.
  • Deferred-surface docs. Records, in the changelog and godoc, the features deliberately left for post-1.0 as additive (non-breaking) work — payload-carrying Raise, multi-target transitions, context.Context on the non-Fire entry points, relaxing the non-quiesced snapshot refusal, finer Inspector cadence, and a metrics Meter seam — each with the additive mechanism it will arrive through. This marks them as intentional boundaries, not oversights.

Why

Freezing a contract is only safe if a test catches accidental breaks and the deliberate boundaries are written down. This makes the 1.0 wire/API shape enforceable in CI and the deferred surface honest.

Relates to: 1.0 stability hardening

Checklist

  • Commits are signed off (git commit -s) per the DCO
  • Conventional commit messages (type: subject)
  • mage check passes locally — state passes lint, race tests, and govulncheck; the only mage check failure is the pre-existing telemetry/datadog stdlib vulnerability, unrelated to this change.
  • Tests added/updated for the change
  • Public API changes documented (godoc) and noted for the changelog

@joshua-temple joshua-temple force-pushed the feat/palette-completeness branch from 9a26432 to 0567672 Compare June 14, 2026 02:13
Base automatically changed from feat/palette-completeness to main June 14, 2026 02:13
Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
@joshua-temple joshua-temple merged commit d3269ef into main Jun 14, 2026
@joshua-temple joshua-temple deleted the feat/v1-freeze-prep branch June 14, 2026 02:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant