13.0.0

Jun 14, 2026 · 10 packages · 17 unique changes · 3 release entries

bundlesintegrationslibsBreaking changes

This release affects the contracts, integrations, sharedLibs, solutions familyies.

Run contractspec connect adoption resolve --family contracts to see how it impacts your project.

Release summaries

i18n-readiness-diagnostic-dx
Add the report-only missing_translation static diagnostic to contracts-spec and an optional locale-override argument to the design-system useI18n hook for the en/fr/es readiness program.
maintainer
Translation diagnostics gain a missing_translation code (non-en value identical to en) emitted at info level (report-only), with checkMissingTranslation and missingTranslationAllowlist options. useI18n accepts an optional localeOverride for per-component locale resolution.
integrator
Surfaces can detect untranslated English stubs per catalog group (with a brand/code/cognate allowlist) without failing CI, and pass a per-component locale into useI18n to drive locale-correct value formatting.
translation-catalog-sharding-ssr-additive
Add factory-stack SSR snapshot/hydration, loader shard scoping, RouteShardManifest, and parity diagnostics extensions for translation catalog sharding + SSR.
maintainer
BREAKING: createTranslationRuntime engine deleted from translation-runtime (subpaths ./runtime, ./registry, ./runtime-helpers removed; preference-override-layer construction dropped). createRuntimeTranslationResolver removed from design-system. Factory stack gains snapshot/hydration/load surface (I18nFactorySnapshot, I18nFactoryHydrationPayload, createI18nFactoryFromHydrationPayload, collectLocaleScopedCatalogs, resolveLocaleWithin). Parity diagnostics gain unsupported_locale_claim, manifest_spec_key_missing, validateManifestCatalogDrift, ManifestRouteEntry. Loader gains specKeys?, computeShardDelta, loadShardDelta. RouteShardManifest + defineRouteShardManifest authored in app layer. resolveTranslationPreferenceContext (context/precedence resolution) is preserved.
integrator
BREAKING: remove all createTranslationRuntime call sites; migrate to createI18nFactory + hydrationPayload() + createI18nFactoryFromHydrationPayload for SSR. Replace createRuntimeTranslationResolver with createTranslationResolver in design-system. Use loadShardDelta for route-level lazy loading. Use validateManifestCatalogDrift to catch manifest↔catalog drift in CI. RouteShardManifest defines route→specKey tier bindings in the app/bundle layer. Preference-override-layer construction has no replacement; drop it.
customer
Translation shards are now scoped per route for faster initial loads and incremental navigation fetches with no hydration mismatch.
unified-contractspec-database-runtime
Unified ContractSpec database runtime: createDatabaseRuntime() preset (pooling, zero-config observability, RLS tenant scoping, AuthOS principal carriage, governed resolvers) plus a typed N+1-safe relational read path, a spec-first generated Drizzle schema, and an SSR prefetch→hydrate bridge. Fully additive.
maintainer
New server-only runtime-managed/database subpath exports createDatabaseRuntime returning { provider (tenant-scoped), governedQuery, governedMutation, withTenant, close }. provider-database gains governed-relational-read (LEFT JOIN LATERAL + json_agg), governed-sql-guards, typed-read, and a generated Drizzle schema + manifest. contracts-spec adds database.query.relational@1.0.0, defineDatabaseTable + databaseTables, and database.query/database.mutation SignalSpecs; QueryState.pageInfo + CacheEntry.pageInfo are additive. providers-impls deprecates the raw createDatabaseProvider hatch (guard test added). database.query.readonly@2.0.0 and governed-read.ts are behaviorally unchanged.
integrator
Adopt createDatabaseRuntime() from @lssm-tech/integration.runtime-managed/database (server-only) for pooled, observability-bound, tenant-scoped data access with pre-bound governed resolvers. Use withTenant(tenantId) on known-tenant server paths (the top-level provider fails closed without a tenant). For SSR, prefetchGovernedQuery → dehydrateGovernedQuery → HydrationBoundary from @lssm-tech/lib.presentation-runtime-next/data, building the client engine over the same CacheStore via createDataEngine({ localOffline: 'offline-capable' }). useContractQuery now exposes hasNextPage + fetchNextPage() (cursor default; offset unchanged).
customer
Database-backed pages load faster: server-prefetched reads hydrate on the client with no second fetch, lists paginate by cursor, and every query is automatically tenant-isolated and observable.

Migration guide

Migrate from raw createDatabaseProvider to createDatabaseRuntime
Required
Replace raw provider construction with the runtime preset to get automatic RLS tenant scoping, observability, and governed resolvers.
Remove createTranslationRuntime engine usage
Required
@lssm-tech/lib.translation-runtime no longer exports the deprecated runtime engine subpaths or preference override-layer construction helpers; consumers must migrate active render paths to the factory stack.
When: When importing @lssm-tech/lib.translation-runtime/runtime, ./registry, ./runtime-helpers, or using createTranslationRuntime and related preference runtime builders.
1. Remove imports from @lssm-tech/lib.translation-runtime/runtime, ./registry, and ./runtime-helpers.
2. Replace active SSR/render usage with createI18nFactory on the server.
3. Transfer factory.hydrationPayload(...) to the client and reconstruct with createI18nFactoryFromHydrationPayload.
4. Drop preference override-layer runtime construction; keep resolveTranslationPreferenceContext for context resolution.
Replace createRuntimeTranslationResolver in design-system consumers
Required
@lssm-tech/lib.design-system removed createRuntimeTranslationResolver; use the registry-backed createTranslationResolver instead.
When: When importing or calling createRuntimeTranslationResolver from @lssm-tech/lib.design-system.
1. Replace createRuntimeTranslationResolver imports with createTranslationResolver.
2. Update call sites to pass the registry-backed resolver inputs expected by createTranslationResolver.

Upgrade steps

Surface untranslated English stubs per catalog group
assisted
Run analyzeTranslationCatalogGroup(s) and inspect missing_translation info issues; pass a missingTranslationAllowlist for English-by-design terms and cognates.
Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/lib.design-system
1. Read missing_translation issues from the diagnostics report (info level, never fails CI).
2. Allowlist brand names, codes, and genuine cross-locale cognates per surface.
3. Optionally pass a localeOverride to useI18n where a per-component locale prop exists.
Adopt the unified database runtime
assisted
Bind pooling + observability + RLS tenant scoping + AuthOS principal + governed resolvers via a single createDatabaseRuntime() handle.
Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/integration.provider-database, @lssm-tech/integration.runtime-managed, @lssm-tech/lib.presentation-runtime-next, @lssm-tech/lib.contracts-runtime-core, @lssm-tech/lib.contracts-runtime-client-react, @lssm-tech/tool.contractspec-drizzle-gen, @lssm-tech/integration.providers-impls, @lssm-tech/bundle.library
1. Import from the server-only @lssm-tech/integration.runtime-managed/database subpath (never the root barrel).
2. Pass an Instrumentation instance to auto-emit database.query / database.mutation spans + metrics.
3. Choose a pooler mode (transaction for pgBouncer/Supabase → prepare:false).
Adopt the SSR prefetch → hydrate bridge
assisted
Prefetch governed reads in a Server Component and hydrate the client data engine with zero second fetch.
Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/integration.provider-database, @lssm-tech/integration.runtime-managed, @lssm-tech/lib.presentation-runtime-next, @lssm-tech/lib.contracts-runtime-core, @lssm-tech/lib.contracts-runtime-client-react, @lssm-tech/tool.contractspec-drizzle-gen, @lssm-tech/integration.providers-impls, @lssm-tech/bundle.library
1. In an RSC, call prefetchGovernedQuery(resolver, envelope, ctx) then dehydrateGovernedQuery(result, envelope).
2. Wrap the client island in HydrationBoundary and build its DataEngine over the same CacheStore (localOffline 'offline-capable').
3. Render through QueryStateView for loading/empty/error/success states.
Adopt cursor pagination in useContractQuery
auto
Use hasNextPage + fetchNextPage() to advance cursor pages; offset callers are unchanged.
Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/integration.provider-database, @lssm-tech/integration.runtime-managed, @lssm-tech/lib.presentation-runtime-next, @lssm-tech/lib.contracts-runtime-core, @lssm-tech/lib.contracts-runtime-client-react, @lssm-tech/tool.contractspec-drizzle-gen, @lssm-tech/integration.providers-impls, @lssm-tech/bundle.library
1. Read pageInfo / hasNextPage from the hook result and call fetchNextPage() to load the next page.
BREAKING: remove createTranslationRuntime and engine call sites
manual
The ./runtime, ./registry, and ./runtime-helpers subpaths are deleted. Remove all createTranslationRuntime, RuntimeTranslationRegistry, runtimeConfigFromSnapshot, buildFallbackChainForSpec, collectSpecKeys, handleMissing, and related call sites. Preference-override-layer construction (buildOverrideLayersFromPreferenceCatalogs, mapPreferenceSourceToOverrideScope, createTranslationRuntimeFromPreferences, createTranslationRuntimeConfigFromPreferences) has no replacement and must be dropped. resolveTranslationPreferenceContext is preserved.
Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/lib.translation-runtime, @lssm-tech/lib.design-system
1. Remove imports from @lssm-tech/lib.translation-runtime/runtime, ./registry, and ./runtime-helpers — these subpaths no longer exist.
2. Remove all createTranslationRuntime call sites from the active render path.
3. Remove buildOverrideLayersFromPreferenceCatalogs and createTranslationRuntimeFromPreferences call sites — no factory equivalent exists.
4. Replace with createI18nFactory + hydrationPayload() on the server and createI18nFactoryFromHydrationPayload on the client (see adopt-factory-snapshot-ssr step).
5. resolveTranslationPreferenceContext from ./preferences is still available for context and precedence resolution.
BREAKING: replace createRuntimeTranslationResolver in design-system
manual
createRuntimeTranslationResolver is removed from @lssm-tech/lib.design-system. Use the registry-based createTranslationResolver instead.
Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/lib.translation-runtime, @lssm-tech/lib.design-system
1. Replace all createRuntimeTranslationResolver imports and call sites with createTranslationResolver from @lssm-tech/lib.design-system.
Adopt factory-stack SSR snapshot/hydration
assisted
Replace createTranslationRuntime with createI18nFactory + hydrationPayload() on the server, and createI18nFactoryFromHydrationPayload on the client.
Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/lib.translation-runtime, @lssm-tech/lib.design-system
1. Import createI18nFactory from @lssm-tech/lib.contracts-spec/translations.
2. Call factory.hydrationPayload(undefined, requestLocale) on the server.
3. Transfer the payload to the client (inline script, RSC stream, etc.).
4. Import createI18nFactoryFromHydrationPayload and call it with the received payload.
5. Remove createTranslationRuntime call sites from the active SSR render path.
Adopt loader shard scoping for route-level lazy loading
assisted
Use loadShardDelta to fetch only the incremental specKeys needed on navigation, reusing already-loaded shared shards.
Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/lib.translation-runtime, @lssm-tech/lib.design-system
1. Author a RouteShardManifest per route with defineRouteShardManifest in your app/bundle layer.
2. On navigation, call loadShardDelta with the loaded and required specKey sets.
3. Pass the returned catalogs to your factory or bundle loader.
Adopt slim inline hydration payload (O2+O3, −60–61% per request)
assisted
Reduce the per-request inline <script> hydration payload by ~60% by stripping spec metadata (O2) and enabling value-pool dedup (O3). Catalogs remain bundled and cached in JS — this is a per-request inline-HTML reduction, not a total-transferred-bytes reduction. O3 adds only ~2% over O2 (disjoint key namespaces; value-pool captures ~53 repeated value strings).
Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/lib.translation-runtime, @lssm-tech/lib.design-system
1. Enable the slim payload mode on your scoped hydration builder (strip spec metadata before serialization; retain full-spec form server-side for diagnostics).
2. Enable value-pool dedup to fold repeated value strings into a values[] pool.
3. Verify CI budget gates pass (single-locale ≤ 64 KB, with-fallback ≤ 128 KB).
4. Confirm AC1 no-flash is preserved by running the no-flash test suite.
Adopt precompiled-ICU fast-path for formatter-path latency (O4)
manual
Use @lssm-tech/lib.translation-runtime/precompile at build time to emit FormatJS IR AST alongside each ICU message. createIntlMessageFormatter skips re-parsing when precompiled AST is present. Additive opt-in; no payload size change. Benefit applies to integrations using ICU plural/select messages; factory proof routes use simple {placeholder} interpolation and are unaffected.
Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/lib.translation-runtime, @lssm-tech/lib.design-system
1. At bundle build time, call buildPrecompiledIcuCatalogFromSpecs(specs) from @lssm-tech/lib.translation-runtime/precompile over your TranslationSpec[] set.
2. Serialize the resulting PrecompiledIcuCatalog with serializePrecompiledIcuCatalog and ship as a build asset alongside (or instead of) the plain catalog.
3. At runtime, parsePrecompiledIcuCatalog + createPrecompiledIcuLookup(catalog), then pass the lookup as the precompiled option to createIntlMessageFormatter.
4. The fast-path activates automatically for any message with a precompiled entry; messages without one fall back to the standard parser; no other call-site changes needed.
Note — dead-key pruning is a CI audit tool under Model A (O5/#17)
auto
@lssm-tech/tool.i18n-prune ships as a CI audit tool reporting dead keys per route against a RouteShardManifest. It does not drive the runtime payload under Model A (catalogs bundled+cached; synchronous fallback). The intersectScopedI18nHydration mechanism is wired and fail-safe but currently no-op; it auto-activates if a precise reachability map ships in a future Model B follow-up. No action required.
Packages: @lssm-tech/lib.contracts-spec, @lssm-tech/lib.translation-runtime, @lssm-tech/lib.design-system
1. Add @lssm-tech/tool.i18n-prune to your CI pipeline to audit dead keys.
2. No runtime wiring changes needed under Model A.

Unique release changes

- Bind pooling + observability + RLS tenant scoping + AuthOS principal + governed resolvers via a single createDatabaseRuntime() handle.
8 packages · 8 occurrences
- Prefetch governed reads in a Server Component and hydrate the client data engine with zero second fetch.
8 packages · 8 occurrences
- Replace raw provider construction with the runtime preset to get automatic RLS tenant scoping, observability, and governed resolvers.
8 packages · 8 occurrences
- Unified ContractSpec database runtime: createDatabaseRuntime() preset (pooling, zero-config observability, RLS tenant scoping, AuthOS principal carriage, governed resolvers) plus a typed N+1-safe relational read path, a spec-first generated Drizzle schema, and an SSR prefetch→hydrate bridge. Fully additive.
8 packages · 8 occurrences
- Use hasNextPage + fetchNextPage() to advance cursor pages; offset callers are unchanged.
8 packages · 8 occurrences
- @lssm-tech/lib.design-system removed createRuntimeTranslationResolver; use the registry-backed createTranslationResolver instead.
3 packages · 3 occurrences
- @lssm-tech/lib.translation-runtime no longer exports the deprecated runtime engine subpaths or preference override-layer construction helpers; consumers must migrate active render paths to the factory stack.
3 packages · 3 occurrences
- @lssm-tech/tool.i18n-prune ships as a CI audit tool reporting dead keys per route against a RouteShardManifest. It does not drive the runtime payload under Model A (catalogs bundled+cached; synchronous fallback). The intersectScopedI18nHydration mechanism is wired and fail-safe but currently no-op; it auto-activates if a precise reachability map ships in a future Model B follow-up. No action required.
3 packages · 3 occurrences
- Add factory-stack SSR snapshot/hydration, loader shard scoping, RouteShardManifest, and parity diagnostics extensions for translation catalog sharding + SSR.
3 packages · 3 occurrences
- createRuntimeTranslationResolver is removed from @lssm-tech/lib.design-system. Use the registry-based createTranslationResolver instead.
3 packages · 3 occurrences
- Reduce the per-request inline <script> hydration payload by ~60% by stripping spec metadata (O2) and enabling value-pool dedup (O3). Catalogs remain bundled and cached in JS — this is a per-request inline-HTML reduction, not a total-transferred-bytes reduction. O3 adds only ~2% over O2 (disjoint key namespaces; value-pool captures ~53 repeated value strings).
3 packages · 3 occurrences
- Replace createTranslationRuntime with createI18nFactory + hydrationPayload() on the server, and createI18nFactoryFromHydrationPayload on the client.
3 packages · 3 occurrences
- The ./runtime, ./registry, and ./runtime-helpers subpaths are deleted. Remove all createTranslationRuntime, RuntimeTranslationRegistry, runtimeConfigFromSnapshot, buildFallbackChainForSpec, collectSpecKeys, handleMissing, and related call sites. Preference-override-layer construction (buildOverrideLayersFromPreferenceCatalogs, mapPreferenceSourceToOverrideScope, createTranslationRuntimeFromPreferences, createTranslationRuntimeConfigFromPreferences) has no replacement and must be dropped. resolveTranslationPreferenceContext is preserved.
3 packages · 3 occurrences
- Use @lssm-tech/lib.translation-runtime/precompile at build time to emit FormatJS IR AST alongside each ICU message. createIntlMessageFormatter skips re-parsing when precompiled AST is present. Additive opt-in; no payload size change. Benefit applies to integrations using ICU plural/select messages; factory proof routes use simple {placeholder} interpolation and are unaffected.
3 packages · 3 occurrences
- Use loadShardDelta to fetch only the incremental specKeys needed on navigation, reusing already-loaded shared shards.
3 packages · 3 occurrences
- Add the report-only missing_translation static diagnostic to contracts-spec and an optional locale-override argument to the design-system useI18n hook for the en/fr/es readiness program.
2 packages · 2 occurrences
- Run analyzeTranslationCatalogGroup(s) and inspect missing_translation info issues; pass a missingTranslationAllowlist for English-by-design terms and cognates.
2 packages · 2 occurrences

Impacted packages

@lssm-tech/bundle.library
Layer: bundles · 5 changes
@lssm-tech/integration.provider-database
Layer: integrations · 5 changes
@lssm-tech/integration.providers-impls
Layer: integrations · 5 changes
@lssm-tech/integration.runtime-managed
Layer: integrations · 5 changes
@lssm-tech/lib.contracts-runtime-client-react
Layer: libs · 5 changes
@lssm-tech/lib.contracts-runtime-core
Layer: libs · 5 changes
@lssm-tech/lib.contracts-spec
Layer: libs · 10 changes
@lssm-tech/lib.design-system
Layer: libs · 10 changes
@lssm-tech/lib.presentation-runtime-next
Layer: libs · 5 changes
@lssm-tech/lib.translation-runtime
Layer: libs · 10 changes