cabloy 5.1.241 → 5.1.243

package/.cabloy-version

@@ -1 +1 @@
-5.1.241
+5.1.243

package/.github/workflows/vona-test-sqlite3.yml

@@ -94,7 +94,7 @@ jobs:
         run: npm run init
       - name: run isolated test infrastructure gate
         # Bound concurrent PowerShell/Add-Type cold starts on Windows runners.
-        run: node --test ${{ runner.os == 'Windows' && '--test-concurrency=2' || '' }} scripts/testClaimProcesses.test.ts scripts/runIsolatedTest.test.ts scripts/testClaimCleanup.test.ts scripts/testProcessGuardianWindows.test.ts vona/packages-vona/vona-core/src/lib/core/testClaim.test.ts vona/packages-vona/vona-core/src/lib/core/testClaimFilesystem.test.ts vona/packages-vona/vona-core/src/lib/framework/bootstrap.test.ts vona/packages-vona/vona-core/src/lib/framework/useApp.test.ts vona/packages-cli/cli-set-api/test/binBuildEntries.test.ts vona/packages-cli/cli-set-api/test/binTestPatterns.test.ts
+        run: node --test ${{ runner.os == 'Windows' && '--test-concurrency=2' || '' }} scripts/testClaimProcesses.test.ts scripts/runIsolatedTest.test.ts scripts/testClaimCleanup.test.ts scripts/testProcessGuardianWindows.test.ts vona/packages-vona/vona-core/src/lib/core/testClaim.test.ts vona/packages-vona/vona-core/src/lib/core/testClaimFilesystem.test.ts vona/packages-vona/vona-core/src/lib/framework/bootstrap.test.ts vona/packages-vona/vona-core/src/lib/framework/useApp.test.ts vona/packages-cli/cli-set-api/test/binBuildEntries.test.ts vona/packages-cli/cli-set-api/test/binBuildFreshInputs.test.ts vona/packages-cli/cli-set-api/test/binTestPatterns.test.ts
       - name: run A-Pay focused gate
         run: npm run test -- test-pay/test/paymentSession.test.ts test-pay/test/payMock.test.ts test-pay/test/paypalProvider.test.ts test-pay/test/paypalLifecycle.test.ts test-pay/test/stripeProvider.test.ts test-pay/test/stripeLifecycle.test.ts test-pay/test/outbox.test.ts test-pay/test/webhook.test.ts
         working-directory: vona

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 5.1.243
+
+### Bug Fixes
+
+- Fix warning logging.
+- Fix logout in demonstration mode.
+- Fix Rollup build caching.
+
+### Improvements
+
+- Update the demonstration mode guide.
+
+## 5.1.242
+
+### Bug Fixes
+
+- Correct test failures.
+
+### Improvements
+
+- Enhance CAPTCHA functionality and expand test coverage.
+- Clarify locale provider examples and metadata commands in the documentation.
+- Update dependency lockfile.
+
 ## 5.1.241
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.241",
+  "version": "5.1.243",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/repo-docs/backend/demonstration-mode-guide.md

@@ -80,10 +80,13 @@ The Guard depends on Passport-resolved account state, so it makes this decision
 
 ## Exempt authentication routes
 
-Demonstration Mode deliberately does not apply to the standard authentication and OAuth routes below. This keeps sign-in, sign-out, registration, account association and migration, OAuth callbacks, and token flows available while the write policy is active.
+Demonstration Mode deliberately does not apply to the standard authentication and OAuth routes below. This keeps sign-in, registration, account association and migration, OAuth callbacks, and token flows available while the write policy is active.
+
+In Cabloy Basic, and Cabloy Start, `POST /home/user/passport/logout` is **not exempt**. While Demonstration Mode is enabled, only authenticated, active, non-anonymous whitelisted users may log out; other users receive `403` with `demo-demonstration:1001`.
+
+This prevents ordinary visitors sharing a demo account from revoking other visitors' logins. Whitelisted users remain able to log out. The underlying logout semantics are unchanged: logout revokes the shared login state for the current account and authentication record, not just the current browser session. When Demonstration Mode is disabled, this Guard does not restrict logout.
 
 ```text
-/home/user/passport/logout
 /home/user/passport/register
 /home/user/passport/login
 /home/user/passport/login/:module/:providerName/:clientName?

package/repo-docs/backend/i18n-guide.md

@@ -28,7 +28,51 @@ Representative files include:
 - `src/suite/a-training/modules/training-student/src/config/locale/en-us.ts`
 - `src/suite/a-training/modules/training-student/src/config/locale/zh-cn.ts`
 
-This makes localization part of the module model rather than a single global string table.
+This makes localization part of the module model rather than a single global string table. Ordinary dictionaries are exported through `resource.locales`; metadata generation continues to read `src/config/locale`.
+
+### Cross-module language providers
+
+A language provider supplies translations for existing target modules without taking ownership of their message keys. The framework supports provider modules on both Vona and Zova; the Japanese (`ja-jp`) resources below illustrate an application-authored provider, not a bundled language pack. Author or install the providers your application needs. Installing a provider supplies resources; it does **not** enable that language in application policy.
+
+A Vona provider declares `vonaModule.capabilities.locale: true` in its `package.json` and authors a separate export:
+
+```typescript
+// src/locales/ja-jp.ts
+export default {
+  modules: {
+    'training-student': {
+      StudentName: '受講生氏名',
+    },
+  },
+};
+```
+
+```typescript
+// src/locales/index.ts
+import jaJP from './ja-jp.ts';
+
+export const localesProvider = {
+  'ja-jp': jaJP,
+};
+```
+
+The module's `src/index.ts` re-exports `localesProvider` from `./locales/index.ts`. Larger dictionaries can compose authored helper files such as `src/lib/locales/training-student.ts`.
+
+The `modules` envelope is structural: its keys identify target modules, not a new business scope owned by the provider. Only targets present in effective module metadata receive contributions. Optional top-level **string** entries are global messages; `modules` itself is never a text key. Providers need no blanket dependencies on translated targets and must not import those targets merely to contribute text.
+
+For a target's scoped key, registration precedence is **project target override → provider contribution → ordinary target dictionary**. Global collisions retain stable first-registration-wins behavior; scoped lookup takes priority over global lookup. Avoid relying on collisions between independent providers as a product customization mechanism.
+
+### Generation and reload boundaries
+
+From the repository root, refresh metadata for an existing module, replacing `<module>` with its relative module name:
+
+```bash
+npm run vona :tools:metadata <module>
+```
+
+Metadata generation still handles ordinary `src/config/locale` resources; it neither discovers nor generates the provider's `src/locales` map. Keep `localesProvider` and its entrypoint export authored. Do not add dummy provider `en-us` files or expect English-base key/scope inference for provider-owned resources. `:init:locale` initializes **ordinary** locale resources, not a provider scaffold. Do not hand-edit generated consumers to add provider dictionaries.
+
+Provider files and imported helper edits/deletions take effect through the existing development reload/restart and application reinitialization path, not a new live registry API. Vona retains its `moduleLoading` → configuration/locales → `moduleLoaded` lifecycle; do not assume provider translations are available in an earlier `moduleLoading` hook. Frontend early registration and lazy-target behavior are described in [System Startup Guide](/frontend/system-startup-guide).
 
 ## Accessing locale resources
 
@@ -86,28 +130,57 @@ this.ctx.locale = 'en-us';
 ### Get default locale
 
 ```typescript
-const localeDefault = this.$scope.locale.config.locale.defaultLocale;
+const localeDefault = this.app.config.locale.default;
 ```
 
 ## Locale configuration and resolution order
 
-The `a-locale` module exposes locale settings such as:
+The root application configuration owns the enabled languages and the sole configured default. For example, inside the existing root config factory in `vona/src/backend/config/config/config.ts`:
 
-- `defaultLocale`
-- `queryField`
-- `headerField`
-- `cookieField`
+```typescript
+config.locale = {
+  items: {
+    'en-us': 'LanguageEnglish',
+    'zh-cn': 'LanguageChinese',
+    'ja-jp': 'LanguageJapanese',
+    'zh-tw': 'LanguageTraditionalChinese',
+  },
+  default: 'en-us',
+};
+```
+
+This is an explicit four-language policy example, not the ordinary Basic default: Basic enables `en-us`/`zh-cn` by default. Keep the matching frontend root policy aligned as described in [Environment and Config Guide](/frontend/environment-config-guide). Adding dictionaries or extending `ILocaleRecord` alone does not enable a language.
+
+A later configuration layer's `locale.items` **replaces** the earlier enabled set; it does not add languages to it. The final map must be nonempty, have canonical lowercase hyphenated locale keys and string label values, and contain `locale.default` as an own key. Invalid policy fails validation rather than silently inventing a language set.
+
+The `a-locale` module retains transport settings such as `queryField`, `headerField`, `cookieField`, cookie-write options and `localeAlias`. It is not the owner of enabled/default policy.
 
-The current locale is resolved in this order:
+### Migrating the old default setting
+
+Remove obsolete `a-locale` `locale.defaultLocale` configuration and replace it with root `config.locale.default`; explicitly define the enabled `config.locale.items` set and align the frontend policy. Change reads of `this.$scope.locale.config.locale.defaultLocale` to `this.app.config.locale.default`. The old module setting is not a second default or a compatibility override. Existing transport and timezone settings remain under `a-locale`.
+
+### Active selection versus message fallback
+
+The current locale takes the first nonempty input in this order:
 
 - query field
 - header field
 - cookie field
 - user locale
-- `Accept-Language`
-- default locale
+- `Accept-Language` (the first supported candidate)
+- configured root default
+
+Selection normalizes input by trimming, replacing underscores with hyphens, and lowercasing. Aliases are resolved against the enabled own keys; an alias cannot enable a disabled language. Unknown or disabled input resolves to the configured default. In particular, an explicit but disabled query/header/cookie value does not bypass policy by falling through to another language source. Assigning `ctx.locale` uses the same enabled-policy boundary.
+
+An explicit low-level lookup such as `StudentName.locale('ja-jp')` is different: it can read installed resources without activating Japanese for requests or language menus. Missing-message lookup follows this sequence:
+
+1. requested-locale target dictionary;
+2. requested-locale global dictionary;
+3. `en-us` target dictionary;
+4. `en-us` global dictionary;
+5. the original message key.
 
-This is important because locale is not guessed from only one source.
+The configured default controls **active-language selection**, not this missing-text fallback. There is no implicit `zh-tw` → `zh-cn` fallback. Keep missing text, disabled selection and uninstalled resources distinct when diagnosing a result.
 
 ## Adding a new language
 
@@ -218,6 +291,31 @@ this.scope.locale.NameApples_.locale('en-us', 'Mike', 2);
 
 This is exact numeric-value selection, not automatic `Intl.PluralRules` or CLDR plural-category resolution. It makes common plural handling part of the localization model while allowing each locale to define its own wording.
 
+## Text, formatting, and validation boundaries
+
+A language pack provides text, not a general date/number/currency formatting redesign. The printf placeholders and exact numeric suffixes above do not supply locale-aware decimal separators, currency rules or calendar formatting. Use the application's existing formatter (for example, `Intl.NumberFormat` or a date library) with deliberate locale/timezone options where those semantics are required. Request timezone and active language are related inputs, not interchangeable values.
+
+Cabloy Basic keeps its existing `home-base` Zod registrations for `en-us` → `en` and `zh-cn` → `zhCN`; installing Japanese or Traditional Chinese dictionaries does not add Zod error locales. In a real business application, import and register the Zod resources corresponding to the languages that application enables, on both backend and frontend.
+
+For example, if the business application enables all four languages, extend its existing `home-base` adapters with:
+
+```typescript
+import { en, ja, zhCN, zhTW } from 'zod/locales';
+
+const localeErrors = {
+  'en-us': en,
+  'zh-cn': zhCN,
+  'ja-jp': ja,
+  'zh-tw': zhTW,
+};
+```
+
+In the backend adapter's `moduleLoaded`, register the map with `this.app.util.setLocaleErrors(localeErrors, this.app.config.locale.default)`. In the frontend adapter, keep registration inside the existing `if (process.env.CLIENT)` boundary and call `this.app.util.setLocaleErrors(localeErrors, this.sys.config.locale.default)`. Import only the resources the business application's enabled policy requires; this example is not a request to change Basic's default registrations.
+
+Dictionary text and Zod error text come from different owners; do not duplicate vendor validation messages inside a provider. Frontend registration is client-only, so this mapping alone does not promise identical SSR validation execution. See [Validation Guide](/backend/validation-guide) and [Zod Guide](/frontend/zod-guide).
+
+Localized OpenAPI metadata remains backend contract truth. Frontend `$apiSchema` and `ModelResource` projections are locale-scoped reactive state: reacquire the current facade or derived schema after a locale change instead of retaining a snapshot from the previous locale. Compatible ordinary dirty fields can survive schema refresh, while an opaque custom renderer with translated options may reset to its server baseline; do not promise universal input preservation. See [API Schema Guide](/frontend/api-schema-guide) and [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern).
+
 ## Timezone support
 
 Vona also tracks timezone in the request context.

package/repo-docs/frontend/environment-config-guide.md

@@ -99,6 +99,49 @@ A representative SSR admin development stack looks like:
 
 The config side follows the same merge pattern with `config.ts`, `config.[meta].ts`, and `.local` variants.
 
+## Locale enablement and defaults
+
+Installed dictionaries, enabled languages, and the default language are separate concerns. Authoring or installing a language provider makes its translation resources available; it does not add a language choice or change the default. The Japanese and Traditional Chinese entries below illustrate application policy, not bundled language packs. Configure application policy explicitly in the frontend root config, `zova/src/front/config/config/config.ts`, or an applicable config layer:
+
+```typescript
+import type { ZovaConfigOptional, ZovaSys } from 'zova';
+
+export default function (_sys: ZovaSys) {
+  const config: ZovaConfigOptional = {};
+
+  config.locale = {
+    default: 'ja-jp',
+    storeKey: 'locale',
+    items: {
+      'en-us': 'LanguageEnglish',
+      'ja-jp': 'LanguageJapanese',
+      'zh-cn': 'LanguageChinese',
+      'zh-tw': 'LanguageTraditionalChinese',
+    },
+  };
+
+  return config;
+}
+```
+
+This is a locale-policy example, not a replacement for the other settings in an existing config file. Additional locale IDs need reachable `ILocaleRecord` declarations, supplied by installed modules or authored interface merging. A type declaration alone neither supplies translations nor enables a language.
+
+- `items` is the enabled locale-code-to-label-key map. The values are message keys used by language selectors, not dictionaries or package names. A configured subset is valid; it need not contain every language declared in `ILocaleRecord`.
+- `default` is the application default and must be an own key of the nonempty `items` map. Invalid policy fails validation rather than being repaired from installed providers.
+- `storeKey` is the frontend locale cookie key. Keep it deliberate when changing preference compatibility; it does not determine which languages are enabled. SSR cookie access still follows the effective SSR profile.
+
+Locale IDs in policy use lowercase, hyphenated form such as `ja-jp` and `zh-tw`. Active-locale input is normalized, so `JA_JP` can resolve to enabled `ja-jp`. Missing, unknown, or disabled selections fall back to `config.locale.default`, including stale saved preferences. Route-specific language menus can narrow the root enabled set, not expand it. This policy governs active-language selection, not an explicit low-level translation lookup such as `this.scope.locale.Name.locale('en-us')`.
+
+Unlike ordinary additive config merging, **each config layer that supplies `locale.items` replaces the entire enabled map**. For example, a later layer with only `items: { 'ja-jp': 'LanguageJapanese' }` removes earlier English and Chinese choices. It must also leave `default` valid, either by retaining an already enabled default or setting `default: 'ja-jp'`. To add one language while preserving others, specify the complete desired map in that layer.
+
+An enabled language may have no installed provider; missing text then uses the normal `en-us` / original-key fallback. Conversely, an installed but disabled language remains unavailable for active selection. Neither case is proof of translation completeness. The configured default does not change missing-message fallback; see [Module Scope](/frontend/module-scope#override-precedence-and-missing-message-fallback).
+
+### Configure frontend and backend roots separately
+
+For a paired application, also configure Vona's root `config.locale.items` and `config.locale.default` in `vona/src/backend/config/config/config.ts` or its applicable config layer. Keep the deployed frontend and backend policies aligned deliberately: neither stack automatically synchronizes its enabled set or default to the other. `APP_LOCALE_DEFAULT` supplies the frontend default only where the frontend config reads it; it does not enable the language or configure the backend root.
+
+The backend default belongs to root `config.locale.default`, not the former module-level `a-locale` `defaultLocale`. Backend negotiation, aliases, cookie/protocol settings, and migration details are covered in [I18n Guide](/backend/i18n-guide). Providers contain shared static text, while the selected language remains app/request-scoped; language policy is not an authorization or tenant boundary.
+
 ## Flavor-aware capability differences
 
 Different SSR flavors can intentionally expose different runtime capabilities rather than behaving identically.

package/repo-docs/frontend/module-scope.md

@@ -85,6 +85,94 @@ const message2 = this.scope.locale.HelloWorld.locale('en-us');
 
 Project-level locale resources can override module-level locale values, which is one of the key reasons scope stays useful even when the final app wants customized wording.
 
+### Ordinary dictionaries and language providers
+
+Frontend locale resources have two distinct authoring paths:
+
+| Resource                   | Authored source                                      | Module resource export     | Purpose                                                  |
+| -------------------------- | ---------------------------------------------------- | -------------------------- | -------------------------------------------------------- |
+| Ordinary module dictionary | `src/config/locale/<locale>.ts`                      | Generated `locales`        | Define the module's own message keys and default wording |
+| Language provider          | `src/locales/<locale>.ts` and `src/locales/index.ts` | Authored `localesProvider` | Supply translations for multiple target modules          |
+
+For example, `training-student` retains ownership of keys such as `Name` and their business meaning. An application-authored Japanese provider translates those keys; it does not acquire the student module's business ownership or generate its own `scope.locale.Name()`. The provider below is an authoring example, not a bundled language pack.
+
+A provider declares its capability in the module's `package.json`:
+
+```json
+{
+  "zovaModule": {
+    "capabilities": {
+      "locale": true
+    }
+  }
+}
+```
+
+Provider resources use a `modules` envelope containing flat dictionaries keyed by target-module relative names:
+
+```typescript
+// Provider src/locales/ja-jp.ts
+export default {
+  modules: {
+    'training-student': {
+      Name: '名前',
+    },
+  },
+};
+```
+
+Author the locale-code map explicitly and re-export it from the module entrypoint:
+
+```typescript
+// Provider src/locales/index.ts
+import jaJp from './ja-jp.ts';
+
+export const localesProvider = {
+  'ja-jp': jaJp,
+};
+```
+
+```typescript
+// Provider src/index.ts; retain other existing exports
+export { localesProvider } from './locales/index.ts';
+```
+
+`modules` is resource structure, not a translatable message key. The runtime registers this example under `training-student`, not under the provider's own scope. Providers can also contribute top-level global strings, but global resources and scoped dictionaries occupy different lookup levels; a same-named global key is not a universal override of every module.
+
+Larger providers can compose per-target files from `src/lib/locales/<target-module>.ts`, importing them into `src/locales/ja-jp.ts` with the actual `.ts` source suffix. Helper filenames are not locale IDs. Author or install the provider modules your application needs; framework support alone does not supply Japanese or Traditional Chinese dictionaries. Installing a provider does not enable its language; see [Locale enablement and defaults](/frontend/environment-config-guide#locale-enablement-and-defaults).
+
+### Override precedence and missing-message fallback
+
+For the same target module, language, and message key, precedence is:
+
+```text
+Project target-module override > provider > ordinary target dictionary
+```
+
+Author project overrides in `zova/src/front/config/locale/<locale>.ts`, again using `modules: { 'training-student': { ... } }`, and include the locale in `zova/src/front/config/locales.ts`. Override only the messages the application needs to customize, rather than copying a whole provider. When providers contribute the same key, the first registration in stable module order wins; use project overrides for application-specific wording instead of relying on provider collisions.
+
+Override precedence is separate from missing-message lookup. Ordinary text lookup tries:
+
+```text
+Target current language → global current language → target en-us → global en-us → original key
+```
+
+`config.locale.default` selects the active language when a selection is absent or invalid. It **does not replace `en-us` as the missing-message fallback**. For example, choosing `ja-jp` as the default does not make a missing `zh-tw` message fall back to Japanese, nor is there an implicit `zh-tw` to `zh-cn` fallback.
+
+### CLI and metadata boundaries
+
+From the repository root, `npm run zova :init:locale <module>` initializes ordinary `src/config/locale/` resources and refreshes module metadata by default. It is not a generator for the provider layout above.
+
+`npm run zova :tools:metadata <module>` scans only `src/config/locale/*.ts` for ordinary locale generation, producing `src/.metadata/locales.ts` and the target module's scope types. It does not scan provider `src/locales/` or `src/lib/locales/`, or infer provider-owned message keys from a `modules` envelope. The provider locale map and entrypoint `localesProvider` export remain authored source, preserved by normal metadata refresh. A single-language provider needs no dummy `en-us.ts` for type generation.
+
+When adding an ordinary message key, update the target module's ordinary dictionaries first and refresh that target's metadata. Do not hand-edit generated files or bypass missing keys with type assertions. For language type declarations, placeholders, and numeric variants, see [I18n Guide](/backend/i18n-guide). Frontend declarations extend `ILocaleRecord` in `zova` and must remain reachable through the module's authored type exports.
+
+### Text translation and formatting limits
+
+Providers supply static text translations, not automatic translation of hard-coded strings or complete date, number, and currency localization. Text placeholders and exact numeric variants share the backend conventions described in [Formatting locale text](/backend/i18n-guide#formatting-locale-text); frontend code does not need another message-format system.
+
+The existing `basic-date` utility uses Luxon `format` / `preset` options, and `basic-currency` uses separate `CurrencyOptions`. These utilities do not uniformly receive locale policy from `app.meta.locale.current`. Inspect the specific component and formatter when regional date, number, currency, or timezone presentation is required. Installing a provider or setting a default language alone does not complete that formatting work.
+
 ### Diagnose locale typing at its source
 
 Use `this.scope.locale.SomeKey()` directly. Its type is generated from the module locale source and module metadata; do not add a local type assertion, compatibility helper, or cast merely to silence a missing-key error.

package/repo-docs/frontend/system-startup-guide.md

@@ -139,6 +139,37 @@ A representative lifecycle interpretation is:
 - `sysReady` for long-lived runtime behavior that depends on the system being fully operational
 - `sysClose` for teardown of system-level resources
 
+## Locale providers during system startup
+
+Locale providers are static module resources registered at the Sys level, not dictionaries appended separately in each SSR request or app instance. The relevant initialization order is:
+
+1. Initialize project locale overrides from the frontend locale map.
+2. Merge and validate the root config, including enabled languages and the default.
+3. Load startup module resources, including modules with `zovaModule.capabilities.locale: true`.
+4. Install locale providers and register their `localesProvider` resources **before installing the first preload module**.
+5. Continue with preload, monkey, and sync installation; on the server, install the remaining modules through the existing SSR path.
+6. Run `sysInitialize`, `sysInitialized`, and `sysReady` after module initialization.
+
+Resource import and module installation are different stages. Startup resources may already be imported together, but provider installation completes before preload installation begins. This makes provider text available at the preload consumer's supported initialization boundary without requiring page code or an app-level provider hook to register it again.
+
+### Translation targets remain metadata-filtered
+
+A provider's `modules` envelope names translation targets, not dependencies to import. Registration checks target membership in the active module metadata map:
+
+- A target absent from that map, including a project-disabled module, is skipped.
+- A target present in the map can receive translations even if it has not been imported or installed yet.
+- Registering that dictionary does not import or install the target. Client-side lazy targets remain lazy; their later ordinary dictionaries cannot replace earlier provider values.
+
+This does not mean all SSR modules are lazy: the existing server startup path imports and installs remaining modules independently of provider registration. Do not add blanket target dependencies or eager target imports merely to contribute translations. Providers themselves are selected by the locale capability and do not need `preload: true` just to register text.
+
+Project overrides therefore precede providers, which precede ordinary target dictionaries. For the authoring layout, ownership rules, and exact fallback order, see [Module Scope](/frontend/module-scope#ordinary-dictionaries-and-language-providers). For language enablement, see [Environment and Config Guide](/frontend/environment-config-guide#locale-enablement-and-defaults). Resource registration does not enable a language or change the configured default.
+
+### Development reload and reinitialization
+
+Frontend provider changes use the existing full-reload / Sys-reinitialization path, including changes to imported per-target helper files and removal of contributions. Closing the Sys disposes its locale maps; initialization starts again with project overrides, providers, and ordinary dictionaries. This avoids retaining deleted keys through append-only merges.
+
+Do not treat `localesProvider` as a live dynamic-registration API or mutate shared locale maps in app/request hooks. Changing source resources requires the normal reload or rebuild/restart lifecycle for the running mode. Switching the active language is a separate app-scoped operation over registered resources; it does not install new providers. Backend reload behavior and the shared resource conventions are described in [I18n Guide](/backend/i18n-guide).
+
 ## When to use system startup
 
 Use system startup when:

package/vona/packages-cli/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.173",
+  "version": "1.1.174",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [

package/vona/packages-cli/cli-set-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli-set-api",
-  "version": "1.1.171",
+  "version": "1.1.172",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [

package/vona/packages-cli/cli-set-api/src/lib/bean/cli.bin.build.ts

@@ -203,6 +203,13 @@ export class CliBinBuild extends BeanCliBase {
 
     const sourceMap = process.env.BUILD_SOURCEMAP === 'true';
 
+    // Explicit roots bypass the application's .vona exclusion and prevent stale emit-cache fallback.
+    const tsconfig = path.join(projectPath, '.vona/tsconfig.build.json');
+    await fse.writeJson(tsconfig, {
+      extends: '../tsconfig.json',
+      files: ['./bootstrap.ts', './app.ts', './env.ts', './config.ts', './modules-meta.ts'],
+    });
+
     const replaceValues = generateConfigDefine(env, ['NODE_ENV', 'META_MODE', 'META_FLAVOR']);
     for (const relativeName in modulesMeta.modules) {
       const module = modulesMeta.modules[relativeName];
@@ -265,11 +272,15 @@ export class CliBinBuild extends BeanCliBase {
       json(),
       commonjs(),
       typescript({
+        tsconfig,
         module: 'nodenext',
         compilerOptions: {
           noCheck: true,
+          noEmit: false,
           declaration: false,
+          declarationMap: false,
           composite: false,
+          incremental: false,
           sourceMap,
         },
         outputToFilesystem: false,

package/vona/packages-cli/cli-set-api/test/binBuildFreshInputs.test.ts

@@ -0,0 +1,152 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const buildUrl = new URL('../src/lib/bean/cli.bin.build.ts', import.meta.url).href;
+
+// Keep the actual bundler and transpilers; only isolate CLI initialization.
+const source = `
+  import assert from 'node:assert/strict';
+  import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+  import { registerHooks } from 'node:module';
+  import { join } from 'node:path';
+  import { pathToFileURL } from 'node:url';
+  const buildUrl = ${JSON.stringify(buildUrl)};
+  const projectPath = process.argv[1];
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      if (context.parentURL === buildUrl) {
+        const mock = specifier === '@cabloy/cli'
+          ? 'export class BeanCliBase {}'
+          : specifier === './toolsBin/generateVonaMeta.ts'
+            ? 'export function generateVonaMeta() { throw new Error("Unexpected generation"); }'
+            : undefined;
+        if (mock) return { url: 'data:text/javascript,' + encodeURIComponent(mock), shortCircuit: true };
+      }
+      return nextResolve(specifier, context);
+    },
+  });
+  const { CliBinBuild } = await import(buildUrl);
+  const cli = Object.create(CliBinBuild.prototype);
+  const cachePath = process.argv[2];
+  const poisoned = readFileSync(cachePath, 'utf8');
+  for (const [index, flavor] of ['normal', 'ci', 'normal'].entries()) {
+    const env = {
+      META_MODE: 'prod',
+      META_FLAVOR: flavor,
+      SERVER_LISTEN_DISABLE: flavor === 'ci' ? 'true' : '',
+      generation: index,
+    };
+    writeFileSync(join(projectPath, '.vona/env.ts'),
+      'export default ' + JSON.stringify(env) + ' as const;');
+    writeFileSync(join(projectPath, '.vona/config.ts'),
+      'export default { generation: ' + index + ' };');
+    const outDir = join(projectPath, 'dist/build-' + index);
+    await cli._rollup(projectPath, env, { modules: {} }, outDir);
+    const app = await import(pathToFileURL(join(outDir, 'app.js')).href);
+    assert.deepEqual(app.env, env, 'must compile current generated environment, not cached CI output');
+    assert.deepEqual(await app.config(), { generation: index });
+    assert.equal(app.view, 'fresh-view', 'must retain inherited JSX and legacy decorator compilation');
+    assert.equal(readFileSync(cachePath, 'utf8'), poisoned, 'legacy cache must remain in place');
+    if (process.env.BUILD_SOURCEMAP === 'true') {
+      const maps = readdirSync(outDir).filter(name => name.endsWith('.js.map'));
+      assert.ok(maps.length > 0);
+      assert.ok(maps.some(name =>
+        JSON.parse(readFileSync(join(outDir, name), 'utf8')).sources
+          .some(source => source.endsWith('/.vona/env.ts'))));
+    }
+  }
+`;
+
+for (const sourceMap of [false, true]) {
+  test(`production build uses fresh generated inputs despite CI cache (sourceMap=${sourceMap})`, () => {
+    const projectPath = realpathSync(mkdtempSync(join(tmpdir(), 'vona-bin-build-fresh-')));
+    try {
+      mkdirSync(join(projectPath, '.vona'));
+      mkdirSync(join(projectPath, 'src/backend'), { recursive: true });
+      symlinkSync(
+        fileURLToPath(new URL('../../../node_modules', import.meta.url)),
+        join(projectPath, 'node_modules'),
+        process.platform === 'win32' ? 'junction' : 'dir',
+      );
+      writeFileSync(join(projectPath, 'package.json'), JSON.stringify({ type: 'module' }));
+      writeFileSync(
+        join(projectPath, 'tsconfig.base.json'),
+        JSON.stringify({
+          compilerOptions: {
+            target: 'ES2020',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            incremental: true,
+            composite: true,
+            declaration: true,
+            declarationMap: false,
+            jsx: 'react',
+            jsxFactory: 'h',
+            experimentalDecorators: true,
+            emitDecoratorMetadata: true,
+            skipLibCheck: true,
+          },
+        }),
+      );
+      writeFileSync(
+        join(projectPath, 'tsconfig.json'),
+        JSON.stringify({
+          extends: './tsconfig.base.json',
+          compilerOptions: { noEmit: true, composite: false, declaration: false },
+          exclude: ['.vona', 'dist', 'node_modules'],
+        }),
+      );
+      writeFileSync(
+        join(projectPath, 'src/backend/view.tsx'),
+        `function h(tag: string) { return tag; }
+function mark(target: any) { target.value = 'fresh-view'; }
+@mark
+class View { static value: string; }
+export const view = <fixture /> === 'fixture' ? View.value : 'invalid';`,
+      );
+      writeFileSync(
+        join(projectPath, '.vona/app.ts'),
+        `export { default as env } from './env.ts';
+export { view } from '../src/backend/view.tsx';
+export async function config() { return (await import('./config.ts')).default; }`,
+      );
+      writeFileSync(join(projectPath, '.vona/bootstrap.ts'), "export { env } from './app.ts';");
+      writeFileSync(join(projectPath, '.vona/modules-meta.ts'), 'export default {};');
+      const cachePath = join(
+        projectPath,
+        '.rollup.cache',
+        join(projectPath, '.vona/env.js').replace(/^([a-z]+):/i, '$1'),
+      );
+      mkdirSync(dirname(cachePath), { recursive: true });
+      writeFileSync(
+        cachePath,
+        'export default { META_MODE: "prod", META_FLAVOR: "ci", SERVER_LISTEN_DISABLE: "true", generation: "poisoned" };',
+      );
+      const result = spawnSync(
+        process.execPath,
+        ['--input-type=module', '--eval', source, projectPath, cachePath],
+        {
+          cwd: projectPath,
+          encoding: 'utf8',
+          timeout: 60_000,
+          env: {
+            ...process.env,
+            BUILD_MINIFY: 'false',
+            BUILD_SOURCEMAP: String(sourceMap),
+          },
+        },
+      );
+      assert.ifError(result.error);
+      assert.equal(result.signal, null, result.stderr);
+      assert.equal(result.status, 0, result.stderr);
+      assert.doesNotMatch(result.stderr, /\[plugin typescript\]/i, result.stderr);
+    } finally {
+      rmSync(projectPath, { recursive: true, force: true });
+    }
+  });
+}

package/vona/packages-vona/vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.120",
+  "version": "5.1.122",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "Vona is an intuitive, elegant and powerful Node.js framework for rapidly developing enterprise applications of any size",
   "keywords": [

package/vona/packages-vona/vona-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-core",
-  "version": "5.1.52",
+  "version": "5.1.53",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona",
   "keywords": [