Stability And Versioning

Page outline

Versioning From 1.0

All publishable Palamedes packages ship in lockstep.

Published packages declare Node.js >=22.0.0 unless a package has a specific runtime reason to require a higher Node floor. @palamedes/waku, @palamedes/tanstack, and @palamedes/react-router-rsc require >=22.22.0; server-first @palamedes/remix requires >=24.3.0. The @palamedes/cli-* platform shells intentionally leave Node compatibility to their @palamedes/cli wrapper and therefore omit an engine declaration; the @palamedes/core-node-* native addons are loaded directly by Node and declare >=22.0.0. The repository development and CI floor is stricter: contributors should use Node.js >=22.22, matching the root package.json, README badge, and contribution guide.

From 1.0 onward:

• major releases may include breaking changes to Stable surfaces
• minor releases add compatible behavior to Stable surfaces
• patch releases are compatible bug fixes

Preview, Internal, and Reserved surfaces are not SemVer-stable adoption contracts. They should still receive migration notes when practical, but they may change faster than Stable surfaces.

Stability Tiers

• Stable: app-facing surface covered by SemVer.
• Preview: usable, but still allowed to change as real adoption clarifies the API shape.
• Internal: implementation detail. Apps should not import or depend on it directly.
• Reserved: package name or surface intentionally held for future work, with no supported adoption path yet.

Surface	Tier	Notes
@palamedes/core runtime API	Stable	createI18n, message descriptors, locale activation, and source-message fallback behavior are app-facing.
@palamedes/runtime	Stable	getI18n, setClientI18n, and the server runtime contract are the public transform target.
@palamedes/react and @palamedes/solid	Stable	Runtime components and macro entry points are public app APIs.
@palamedes/vite-plugin and @palamedes/next-plugin	Stable	Plugin options and .po loading behavior are public integration APIs.
@palamedes/waku	Preview	ESM-only Waku handler interceptor and request resolver contract; Waku currently exposes the required APIs as unstable.
@palamedes/tanstack	Stable	TanStack Start server-function middleware and its request resolver contract are public integration APIs.
@palamedes/remix	Preview	Server-first Remix v3 adapter; its Node >=24.3.0 floor reflects the supported Remix runtime.
@palamedes/react-router-rsc	Preview	Opt-in React Router RSC Framework Mode request scope; the upstream RSC contract remains experimental.
@palamedes/config	Stable	Config file names, defineConfig, and the config schema are public.
@palamedes/cli	Stable	Documented commands and flags are public. New commands may appear in minors.
@palamedes/eslint-plugin	Preview	Thin ESLint/Oxlint facades over native diagnostics; Oxlint's JavaScript plugin API is still alpha.
@palamedes/extractor and @palamedes/transform	Preview	Published advanced-tooling APIs; their integration boundaries may evolve before promotion.
pmds binary plugin protocol	Preview	Protocol v1 is version-negotiated; native package resolution and capabilities may evolve before promotion.
Source-string-first PO catalogs	Stable	Message identity is message + context. Catalog files remain user-owned.
FCL catalog storage	Preview	Supported through config, CLI, and native catalog APIs; app-facing framework imports remain PO-loader based for now.
Macro syntax	Stable	Supported macros remain the authoring model. Unsupported explicit IDs are not a compatibility target.
@palamedes/core-node	Preview	It is usable directly, but primarily exists as the JS boundary to the Rust core. Generated type details may change in minors.
@palamedes/core-node-* platform packages	Internal	Optional dependency carriers for native Node addons; apps should not import them directly.
@palamedes/cli-* platform packages	Internal	Optional dependency carriers for native CLI executables; apps should not import them directly.
palamedes and create-palamedes	Reserved	Placeholder top-level packages exist, but there is no supported first-run entry yet.
Compiled catalog artifact internals	Preview	Public loaders can consume them; the internal representation may evolve in minors.
crates/* Rust APIs	Preview	The Rust crates support the Node toolchain today. They are not yet a separately promised public Rust SDK.

Stable Surfaces

Palamedes treats these as stable adoption surfaces:

• palamedes.yaml schema and config discovery
• source-string-first PO catalogs using message + context identity
• documented FCL storage configuration and conversion workflows
• documented pmds commands and flags
• Vite and Next plugin options documented in package READMEs
• Waku server-action interceptor documented in @palamedes/waku (Preview while Waku's interceptor API is unstable)
• TanStack Start server-function middleware documented in @palamedes/tanstack
• runtime access through getI18n()
• createI18n(options?) and descriptor-based lookup behavior
• React and Solid runtime components and macro package names

If one of these must change after 1.0, the release should include:

• a changelog entry calling out the break
• a migration note or replacement path
• a deprecation period when both old and new paths can reasonably coexist

Surfaces That May Still Move

These areas are allowed to change faster while the project learns from real adoption:

• generated native binding type details
• compiled artifact internals
• FCL import support in framework adapters
• package layout for new native platform targets
• benchmark fixture shape and reporting fields
• internal package boundaries between plugins and transform/core-node helpers
• optional Palamedes+ workflow bridges
• binary plugin host capabilities beyond protocol v1

Deprecation Policy

When a stable surface needs to change, prefer this path:

1. Add the replacement.
2. Document the replacement in the release notes.
3. Keep the old path working for at least one minor release when practical.
4. Emit a clear diagnostic or runtime warning if the old path can be detected.
5. Remove it in a later major release.

Security fixes, broken behavior, and unsupported preview/internal surfaces may skip the full deprecation window when keeping compatibility would be misleading or unsafe.

What 1.0 Means

The 1.0 release means:

• app-facing packages follow standard SemVer
• config, CLI, macro syntax, catalog identity, and runtime APIs are stable
• platform support is documented in one place
• preview/internal surfaces are clearly labeled or promoted with tests and docs

See Migrating to Palamedes 1.0 for the breaking catalog-format and metadata changes that were handled in the stabilization release.