cabloy 5.1.205 → 5.1.207

package/.cabloy-version

@@ -1 +1 @@
-5.1.205
+5.1.207

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 5.1.207
+
+### Features
+
+- Add update functionality.
+
+### Bug Fixes
+
+- Fix database reset behavior.
+
+### Improvements
+
+- Enhance and refactor database reset functionality.
+
+## 5.1.206
+
+### Features
+
+- Update functionality (details unspecified).
+
+### Improvements
+
+- Update the pnpm dependency lockfile.
+
 ## 5.1.205
 
 ### Features

package/package.json

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

package/repo-agent-governance/managed-assets.json

@@ -683,7 +683,7 @@
     {
       "adapter": "cursor",
       "category": "policy",
-      "sha256": "539fa24fc49fa8402ea0d9ab89c058762c441d5b3ed87af34a16235d1f8251a0",
+      "sha256": "e2784a08d355455da0da0cfb7c83ff1df4db69566012a1b4a33a5d591764f730",
       "source": "policies/repository.md",
       "target": ".cursor/rules/cabloy-governance.mdc"
     },
@@ -1005,14 +1005,14 @@
     {
       "adapter": "codex",
       "category": "policy",
-      "sha256": "f8172d4e80dc8b84bf99a0e926184eb78af5bd1fdfcdeebe63b02160f459afce",
+      "sha256": "d5f4d8fb331147baa92aa68d8579ac604d2a34bf872efc594393ff1e52e8cd79",
       "source": "policies/repository.md",
       "target": "AGENTS.md"
     },
     {
       "adapter": "claude",
       "category": "policy",
-      "sha256": "f8172d4e80dc8b84bf99a0e926184eb78af5bd1fdfcdeebe63b02160f459afce",
+      "sha256": "d5f4d8fb331147baa92aa68d8579ac604d2a34bf872efc594393ff1e52e8cd79",
       "source": "policies/repository.md",
       "target": "CLAUDE.md"
     }

package/repo-agent-governance/policies/repository.md

@@ -96,7 +96,7 @@ Before inventing a custom implementation path:
 - Do not set `TEST_CONCURRENCY=false` for normal `npm run test` or CI runs: an unset value defaults to concurrent execution. For stateful `node:test` suites, declare `{ concurrency: false }` explicitly. Prove business contention by explicitly launching competing operations and asserting their combined durable outcome, never through runner parallelism or scheduling.
 - Unit tests must not temporarily mutate process-global origin or proxy configuration, including `app.config.server.serve.protocol`, `app.config.server.serve.host`, and `app.proxy`. Model request-origin cases with an explicit `req` fixture, and use the established `AppUtil` loopback fallback for requestless local URLs. Do not introduce a broad origin lock to serialize such tests; retain narrowly scoped locks only for genuinely shared domain state.
 - Unit tests must delete every test-owned persisted resource in `finally`, using precise owned identities and reverse dependency order.
-- Shared durable test or local-development fixtures must be created through the owning module's `meta.version.ts` `seed()` hook and treated as read-only by tests; seeds run on isolated test-mode startup or after an explicit dev-mode `npm run db:reset` against a newly recreated disposable database, not on ordinary dev startup or repeatedly against one database.
+- Shared durable test or local-development fixtures must be created through the owning module's `meta.version.ts` `seed()` hook and treated as read-only by tests; seeds run on isolated test-mode startup or after an explicit dev-mode `npm run db:reset` against newly recreated disposable databases. In Cabloy Basic and Cabloy Start, `npm run dev` and `npm run dev:one` only reuse existing managed disposable databases; any missing required shared or static isolate target must fail promptly with an instruction to run `npm run db:reset`, without database creation, creation-time Redis cleanup, or seeding. Reset is explicitly destructive: one process clears validated application-owned Redis prefixes, drops/recreates managed databases, migrates, initializes, and seeds. Failures remain visible; investigate and explicitly rerun reset, with no preparation journal or automatic recovery. There is no file-based preparation lock; concurrent dev/dev or dev/reset against the same database and Redis namespace is unsupported. Do not run reset without explicit user approval; never seed repeatedly against one database.
 
 ## Verification expectations
 

package/repo-docs/backend/migration-and-changes.md

@@ -94,11 +94,11 @@ export class MetaVersion extends BeanBase {}
 
 Three migration scenarios are defined:
 
-| Scenario | Purpose                                             |
-| -------- | --------------------------------------------------- |
-| `update` | schema evolution such as tables and fields          |
-| `init`   | instance- or tenant-specific initialization data    |
-| `seed`   | baseline data for test runs and explicit dev resets |
+| Scenario | Purpose                                                      |
+| -------- | ------------------------------------------------------------ |
+| `update` | schema evolution such as tables and fields                   |
+| `init`   | instance- or tenant-specific initialization data             |
+| `seed`   | baseline data for test runs and newly prepared dev databases |
 
 This split is one of the most important Vona migration ideas because it separates:
 
@@ -110,7 +110,7 @@ A practical generated-thread interpretation is:
 
 - `update` follows schema and entity/model evolution
 - `init` follows instance-aware initialization needs introduced by the backend feature
-- `seed` provides shared baseline data during test-mode startup or an explicit development database reset
+- `seed` provides shared baseline data during test-mode startup or an explicit development database reset; ordinary dev startup never seeds (see the shared lifecycle below)
 
 ## Update: schema migration
 
@@ -153,7 +153,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionInit {
 
 The important point is that initialization can run per instance or tenant, which keeps tenant data isolated.
 
-## Seed: test and reset baseline data
+## Seed: test and development baseline data
 
 Representative pattern:
 
@@ -171,7 +171,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionSeed {
 
 This is valuable because shared baseline data becomes part of the structured version lifecycle instead of being scattered across unrelated setup code.
 
-Vona invokes `seed()` while the application starts in test mode (`npm run test` or managed E2E), and during an explicit `npm run db:reset` in dev mode. Ordinary development startup and framework upgrades do not seed or reset development data automatically. Use `seed()` for durable baseline fixtures shared by tests or for freshly prepared local development data. Both paths seed after instance initialization on a newly recreated disposable database; `seed()` is not a repeatable, same-database data-import mechanism.
+Vona invokes `seed()` while the application starts in test mode (`npm run test` or managed E2E), and during an explicit `npm run db:reset` in dev mode. In **Cabloy Basic and Cabloy Start**, ordinary `npm run dev` and `npm run dev:one` only reuse existing managed disposable databases and never seed; a missing required database makes startup fail with an instruction to run `npm run db:reset`. Framework upgrades do not reset existing development data or repeat its seeds. Use `seed()` for durable baseline fixtures shared by tests or for freshly prepared local development data. Seeding follows instance initialization on a newly created or recreated disposable database; `seed()` is not a repeatable, same-database data-import mechanism. See [Managed development database preparation](#managed-development-database-preparation) for the explicit reset lifecycle.
 
 Treat shared `seed()` records as read-only in ordinary tests. A scenario that needs different state must create independent, test-owned data and clean it up in `finally`; it must not mutate or delete the shared baseline. `seed()` remains distinct from `init()`: use `init()` for instance-aware initialization data and reserve `seed()` for baseline data in test runs or explicit development resets.
 
@@ -208,6 +208,25 @@ A practical decision rule is:
 - `db:reset` requires `database.testDatabase: true` in dev config and a connection outside the disposable database; it refuses to reset a configured non-disposable database
 - use `test` when you need **test-mode** verification of migration, controller behavior, and the broader generated contract thread; E2E also remains test-mode
 
+### Managed development database preparation
+
+**Cabloy Basic and Cabloy Start** share this explicit preparation lifecycle for framework-managed disposable development databases.
+
+When `database.testDatabase: true` enables framework-managed disposable dev databases, `npm run dev` and `npm run dev:one` only reuse existing databases:
+
+1. **Check every required target:** both shared and statically configured isolate database targets must exist. If any required target is missing, startup fails promptly with an instruction to run `npm run db:reset`; it does not create the target, perform creation-time Redis cleanup, or seed as a fallback.
+2. **Reuse existing databases:** keep their data without database creation, creation-time Redis cleanup, or module seeding. Ordinary startup is not a fixture refresh, an implicit reset, or recovery for a partial reset. Non-disposable databases are outside this managed reset path.
+
+An explicit `npm run db:reset` owns preparation in a single process. It requires `database.testDatabase: true` and a connection outside the disposable database. It clears validated application-owned Redis state with `clearAllData()`, drops and recreates the managed disposable dev databases, runs migrations and instance initialization, then invokes the owning modules' `seed()` hooks.
+
+**Stop the development server and any other processes using the same database and Redis namespace first.** There is no file-based preparation lock; concurrent dev/dev and dev/reset against the same database and Redis namespace are unsupported. The reset command disables its own listener, but that does not protect a concurrently running server or queue worker. Never reset development data you need to keep.
+
+If reset fails, the failure remains visible. There is no preparation journal or automatic recovery: investigate and resolve the cause, then explicitly rerun `npm run db:reset`. Database existence alone does not prove migrations, initialization, or seeding completed after an interruption. A subsequent dev startup must not be used to repair or complete the failed preparation.
+
+The Redis cleanup is prefix-scoped, not a Redis-wide flush: `clearAllData()` validates application-owned prefixes and deletes matching Bull queue, redlock, worker, and cache keys. It does not use `FLUSHDB` or `FLUSHALL`, delete unrelated namespaces, or clear broadcast subscriptions. Only explicit reset performs this destructive preparation cleanup; ordinary dev startup does not. Prefix scoping is not permission to clear a live shared namespace manually.
+
+See [Development database preparation](/reference/repo-scripts#development-database-preparation) for the root-command summary.
+
 ## Implementation checks for migration-sensitive changes
 
 When changing backend schema or module initialization behavior, do not only edit entities and models.

package/repo-docs/reference/repo-scripts.md

@@ -67,7 +67,7 @@ Builds, generated artifacts, dependency installation/generation, and other share
 
 For Vona integrated SSR, the allocated E2E origin is supplied to Zova at runtime as server `SSR_API_BASE_URL` and browser `API_BASE_URL`. Do not edit Zova `.env` files or rebuild solely to match the test port. The current root `npm run test:e2e` consumes prebuilt frontend artifacts; refresh affected SSR/REST output and synchronize dependencies when their inputs change. See [Runtime API origins in Vona integrated SSR](/fullstack/ssr-entry-modes#runtime-api-origins-in-vona-integrated-ssr) for configuration overrides and scope.
 
-For a deliberate **dev-mode** database recreation, `npm run db:reset` is a separate, destructive command: it drops matching disposable development databases, reruns migrations and instance initialization, then runs module `seed()` hooks. It requires `database.testDatabase: true` in the dev configuration and a connection outside the disposable database. Ordinary `npm run dev` does not seed or reset; never run `db:reset` against development data you need to retain. Upgrades no longer initialize development test data automatically. See [Migration and Changes](/backend/migration-and-changes#local-development-workflow).
+For deliberate **dev-mode** database preparation, `npm run db:reset` is a separate, destructive command: in a single process, it clears validated application-owned Redis keys, drops and recreates managed disposable development databases, reruns migrations and instance initialization, then runs module `seed()` hooks. It requires `database.testDatabase: true` in the dev configuration and a connection outside the disposable database. Ordinary `npm run dev` and `npm run dev:one` only reuse existing managed databases; if any required target is missing, startup fails promptly with an instruction to run `npm run db:reset`. They do not create databases, perform creation-time Redis cleanup, or seed. Never run `db:reset` against development data you need to retain. Upgrades do not reset existing development data or repeat its seeds. See [Development database preparation](#development-database-preparation) and [Migration and Changes](/backend/migration-and-changes#local-development-workflow).
 
 ## Specification planning and derived charts
 
@@ -140,6 +140,25 @@ Cabloy Start exposes the equivalent Start repository surface:
 
 Cabloy Start does not expose Basic Commerce or root documentation wrappers.
 
+## Development database preparation
+
+**Cabloy Basic and Cabloy Start** share this explicit development-preparation lifecycle. Use the active repository's commands and configuration; sharing the lifecycle does not make the editions' flavors or frontend outputs interchangeable.
+
+With `database.testDatabase: true`, `npm run dev` and `npm run dev:one` only reuse existing framework-managed disposable development databases:
+
+- **All required databases exist:** startup reuses them without database creation, creation-time Redis cleanup, or module seeding. Ordinary startup is not a reset or a repeatable fixture-import path.
+- **Any required database is missing:** startup fails promptly with an instruction to run `npm run db:reset`. This check covers both shared and statically configured isolate database targets; the presence of the shared database alone is not sufficient. Startup does not create the missing target or clear Redis or seed as a fallback.
+
+`npm run db:reset` is the explicit, destructive preparation command. It requires `database.testDatabase: true` and a connection outside the disposable database. In a single process, it clears validated application-owned Redis state with `clearAllData()`, drops and recreates the managed disposable dev databases, then runs migrations, instance initialization, and module `seed()` hooks.
+
+**Stop the development server and any other processes using the same database and Redis namespace before running reset.** There is no file-based preparation lock: concurrent dev/dev and dev/reset processes against the same database and Redis namespace are unsupported. Disabling the reset command's own listener does not make reset safe alongside a live server or queue worker. Do not reset data you need to retain.
+
+Reset failures remain visible. There is no preparation journal or automatic recovery; investigate and resolve the failure, then explicitly rerun `npm run db:reset`. Do not use ordinary dev startup to repair or finish a partial reset.
+
+Here, `clearAllData()` deletes only keys in the validated application-owned Redis prefixes, covering Bull queue, redlock, worker, and cache keys. It does not use `FLUSHDB` or `FLUSHALL`, clear unrelated namespaces, or treat broadcast subscriptions as cleanup keys. Prefix scoping still makes reset destructive to the application's own Redis state; it is not permission to clean a shared live namespace manually.
+
+See [Managed development database preparation](/backend/migration-and-changes#managed-development-database-preparation) for the seed lifecycle and safety boundary.
+
 ## Upgrade
 
 Run `npm run upgrade:dry-run` before `npm run upgrade` to inspect framework files and root manifest entries that an upgrade would synchronize. The upgrader replaces the framework-owned `repo-agent-governance/` source, reconciles only its named package scripts, and uses ownership-aware adapter adoption. It preserves locally modified or legacy adapter outputs as conflicts for explicit review instead of blindly overwriting root Claude, Codex, or Cursor files.

package/scripts/init.ts

@@ -310,3 +310,18 @@ initRepoDocs();
 writeVersionMarker();
 // eslint-disable-next-line
 console.log('[init] Done!');
+// eslint-disable-next-line
+console.log(
+  [
+    '',
+    '=== Before your first development startup ===',
+    'Prepare the development database before running npm run dev:',
+    '',
+    '  npm run db:reset',
+    '',
+    'Warning: db:reset deletes managed development data and application-owned Redis state.',
+    'Stop processes using the same database and Redis namespace before running it.',
+    'If your development database is already prepared, skip reset to keep existing data.',
+    '',
+  ].join('\n'),
+);

package/scripts/runIsolatedTest.test.ts

@@ -32,6 +32,7 @@ import {
   createTestRunId,
   getUnitTestCommands,
   reserveTestRun,
+  resolveCabloyEdition,
   ROOT_DIR,
   runIsolatedProcess,
   runIsolatedTest,
@@ -79,6 +80,26 @@ test('public test scripts delegate to the isolated runner without recursion', ()
   ]);
 });
 
+test('accepts either Cabloy edition and rejects ambiguous or missing markers', () => {
+  const root = mkdtempSync(join(tmpdir(), 'cabloy-run-edition-'));
+  const basicMarker = join(root, '__CABLOY_BASIC__');
+  const startMarker = join(root, '__CABLOY_START__');
+  try {
+    assert.throws(() => resolveCabloyEdition(root), /Not a Cabloy project/);
+
+    writeFileSync(basicMarker, '');
+    assert.equal(resolveCabloyEdition(root), 'basic');
+
+    writeFileSync(startMarker, '');
+    assert.throws(() => resolveCabloyEdition(root), /Ambiguous Cabloy edition/);
+
+    rmSync(basicMarker);
+    assert.equal(resolveCabloyEdition(root), 'start');
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test('creates a UTC timestamp and eight random hex digits for one run identity', () => {
   const date = new Date('2026-10-14T01:02:03.456Z');
   assert.match(createTestRunId(date), /^20261014010203-[a-f0-9]{8}$/);

package/scripts/runIsolatedTest.ts

@@ -313,13 +313,21 @@ export function getUnitTestCommands(args: string[]) {
   ];
 }
 
-export async function runIsolatedTest(kind: 'unit' | 'e2e', args: string[]) {
-  if (
-    !existsSync(resolve(ROOT_DIR, '__CABLOY_BASIC__')) ||
-    existsSync(resolve(ROOT_DIR, '__CABLOY_START__'))
-  ) {
-    throw new Error('This isolated test runner requires an unambiguous Cabloy Basic checkout');
+export function resolveCabloyEdition(rootDir = ROOT_DIR): 'basic' | 'start' {
+  const hasBasic = existsSync(resolve(rootDir, '__CABLOY_BASIC__'));
+  const hasStart = existsSync(resolve(rootDir, '__CABLOY_START__'));
+  if (hasBasic === hasStart) {
+    throw new Error(
+      hasBasic
+        ? 'Ambiguous Cabloy edition: both __CABLOY_BASIC__ and __CABLOY_START__ markers are present'
+        : 'Not a Cabloy project: no __CABLOY_BASIC__ or __CABLOY_START__ marker found',
+    );
   }
+  return hasBasic ? 'basic' : 'start';
+}
+
+export async function runIsolatedTest(kind: 'unit' | 'e2e', args: string[]) {
+  resolveCabloyEdition();
   if (process.env.E2E_BASE_URL !== undefined) {
     throw new Error(
       'E2E_BASE_URL is unsupported; the E2E runner manages a local test-mode target.',

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

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.160",
+  "version": "1.1.161",
   "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.158",
+  "version": "1.1.159",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [

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

@@ -97,7 +97,8 @@ export class CliBinDev extends BeanCliBase {
 
   async _run(projectPath: string, _modulesMeta: Awaited<ReturnType<typeof glob>>) {
     let closed = false;
-    return new Promise((resolve, _reject) => {
+    let crashError: Error | undefined;
+    return new Promise((resolve, reject) => {
       (nodemon as any)({
         script: '.vona/bootstrap.ts',
         cwd: projectPath,
@@ -127,9 +128,23 @@ export class CliBinDev extends BeanCliBase {
         ],
       });
       nodemon
+        .on('crash', () => {
+          if (closed) return;
+          closed = true;
+          // nodemon emits crash without an error payload; the child already logged the cause.
+          crashError = new Error('Development server crashed; see the startup error above');
+          // Let nodemon finish processing the child exit before stopping its watchers.
+          setImmediate(() => nodemon.emit('quit'));
+        })
         .on('quit', () => {
           closed = true;
-          resolve(undefined);
+          if (crashError) {
+            // The programmatic quit event does not close watchers; reset before propagating
+            // the failure to the CLI's error handler, which exits the process immediately.
+            nodemon.reset(() => reject(crashError));
+          } else {
+            resolve(undefined);
+          }
         })
         .on('restart', files => {
           if (closed) {

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

@@ -0,0 +1,100 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { test } from 'node:test';
+
+const devUrl = new URL('../src/lib/bean/cli.bin.dev.ts', import.meta.url).href;
+const source = `
+  import assert from 'node:assert/strict';
+  import { EventEmitter } from 'node:events';
+  import { registerHooks } from 'node:module';
+  import { setImmediate as nextTurn } from 'node:timers/promises';
+  const devUrl = ${JSON.stringify(devUrl)};
+  const events = new EventEmitter();
+  let options;
+  let resetCount = 0;
+  let watchersActive = true;
+  const nodemon = globalThis.nodemonMock = opts => { options = opts; };
+  nodemon.reset = done => {
+    resetCount++;
+    watchersActive = false;
+    events.removeAllListeners();
+    done();
+  };
+  nodemon.on = (event, handler) => { events.on(event, handler); return nodemon; };
+  nodemon.emit = (event, ...args) => { events.emit(event, ...args); return nodemon; };
+  const mocks = {
+    '@cabloy/cli': 'export class BeanCliBase {}',
+    'nodemon': 'export default globalThis.nodemonMock;',
+    'rimraf': 'export function rimraf() { throw new Error("Unexpected cleanup"); }',
+    'vona-core': 'export function resolveVonaLocalPaths() { throw new Error("Unexpected app access"); }',
+    '../utils.ts': 'export function getImportEsm() { return "--import=./.vona/register.js"; }',
+    './toolsBin/generateVonaMeta.ts': 'export function generateVonaMeta() { throw new Error("Unexpected generation"); }',
+  };
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      if (context.parentURL === devUrl && mocks[specifier]) {
+        return { url: 'data:text/javascript,' + encodeURIComponent(mocks[specifier]), shortCircuit: true };
+      }
+      return nextResolve(specifier, context);
+    },
+  });
+  const { CliBinDev } = await import(devUrl);
+  const cli = Object.create(CliBinDev.prototype);
+  let settled = false;
+  const result = cli._run('/mock-project', {});
+  result.then(() => { settled = true; }, () => {
+    assert.equal(watchersActive, false, 'close watchers before propagating failure');
+    settled = true;
+  });
+  assert.equal(options.cwd, '/mock-project');
+  assert.equal(options.script, '.vona/bootstrap.ts');
+  // Leave nodemon's default stdout/stderr forwarding intact, including the original failure log.
+  assert.equal(options.stdout, undefined);
+  assert.equal(options.stderr, undefined);
+  const scenario = process.argv[1];
+  let quits = 0;
+  events.on('quit', () => { quits++; });
+  if (scenario === 'crash') {
+    console.error('Database cabloy_dev is missing. Create the disposable database first.');
+    nodemon.emit('crash'); // nodemon provides no crash payload
+    // Duplicate crashes must not request duplicate shutdowns.
+    nodemon.emit('crash');
+    await assert.rejects(result, /Development server crashed; see the startup error above/);
+    await nextTurn();
+    assert.equal(quits, 1);
+    assert.equal(settled, true);
+    assert.equal(resetCount, 1);
+    assert.equal(watchersActive, false);
+  } else {
+    nodemon.emit('start');
+    nodemon.emit('restart', ['src/example.ts']);
+    nodemon.emit('exit');
+    await nextTurn();
+    assert.equal(settled, false, 'ordinary restart/clean exit must keep supervision running');
+    assert.equal(quits, 0);
+    assert.equal(resetCount, 0);
+    assert.equal(watchersActive, true);
+    nodemon.emit('quit');
+    assert.equal(await result, undefined);
+    assert.equal(quits, 1);
+  }
+  console.log('verified');
+`;
+
+for (const scenario of ['crash', 'restart-and-quit']) {
+  test(`dev nodemon lifecycle: ${scenario}`, () => {
+    const result = spawnSync(
+      process.execPath,
+      ['--input-type=module', '--eval', source, scenario],
+      {
+        encoding: 'utf8',
+        timeout: 3_000,
+      },
+    );
+    assert.ifError(result.error);
+    assert.equal(result.signal, null, result.stderr);
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /verified/);
+    if (scenario === 'crash') assert.match(result.stderr, /Database cabloy_dev is missing/);
+  });
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.105",
+  "version": "5.1.106",
   "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.44",
+  "version": "5.1.45",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona",
   "keywords": [

package/vona/packages-vona/vona-core/src/lib/framework/cluster.ts

@@ -8,8 +8,8 @@ import { handleProcessWork } from './processWorker.ts';
 
 export async function startCluster(workers: number, bootstrapOptions: BootstrapOptions) {
   if (cluster.isPrimary) {
+    await createAppMaster(bootstrapOptions);
     handleProcessMaster(workers);
-    createAppMaster(bootstrapOptions);
   } else {
     await startWorker(bootstrapOptions);
   }

package/vona/packages-vona/vona-core/src/lib/framework/processMaster.test.ts

@@ -0,0 +1,185 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { test } from 'node:test';
+
+const masterUrl = new URL('./processMaster.ts', import.meta.url).href;
+const clusterUrl = new URL('./cluster.ts', import.meta.url).href;
+
+// Import only the real master handler into a subprocess. Cluster workers and useApp are mocks;
+// process.exit and the shutdown timeout remain real, without loading an app or opening listeners.
+const masterSource = `
+  import assert from 'node:assert/strict';
+  import { EventEmitter } from 'node:events';
+  import { registerHooks } from 'node:module';
+  const masterUrl = ${JSON.stringify(masterUrl)};
+  const cluster = globalThis.clusterMock = new EventEmitter();
+  cluster.workers = {};
+  let forks = 0;
+  const kills = [];
+  const exited = [];
+  function exit(worker, code, signal = null) {
+    delete cluster.workers[worker.id];
+    exited.push({ id: worker.id, code, signal });
+    cluster.emit('exit', worker, code, signal);
+  }
+  cluster.fork = () => {
+    assert.equal(cluster.listenerCount('message'), 1, 'message handler must precede fork');
+    assert.equal(cluster.listenerCount('exit'), 1, 'exit handler must precede fork');
+    assert.ok(process.listenerCount('SIGINT'));
+    assert.ok(process.listenerCount('SIGUSR2'));
+    const worker = { id: ++forks, process: { kill(signal) {
+      kills.push({ id: worker.id, signal });
+      // Synchronous exit also proves reload intent is recorded before kill.
+      exit(worker, globalThis.reloadFailure ? 1 : null, globalThis.reloadFailure ? null : signal);
+    } } };
+    cluster.workers[worker.id] = worker;
+    return worker;
+  };
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      if (context.parentURL === masterUrl) {
+        const source = {
+          'node:cluster': 'export default globalThis.clusterMock;',
+          'chalk': 'export default { cyan: message => message };',
+          './useApp.ts': 'export function useApp() { return { meta: { env: { LOGGER_DUMMY: "true" } } }; }',
+        }[specifier];
+        if (source) return { url: 'data:text/javascript,' + encodeURIComponent(source), shortCircuit: true };
+      }
+      return nextResolve(specifier, context);
+    },
+  });
+  process.on('exit', code => console.log(JSON.stringify({ code, forks, kills, exited })));
+  const { handleProcessMaster } = await import(masterUrl);
+  handleProcessMaster(2);
+  const [first, second] = Object.values(cluster.workers);
+  const scenario = process.argv[1];
+  switch (scenario) {
+    case 'all-clean':
+      exit(first, 0);
+      assert.equal(Object.keys(cluster.workers).length, 1);
+      exit(second, 0);
+      break;
+    case 'failure-then-clean':
+      exit(first, 7);
+      assert.equal(Object.keys(cluster.workers).length, 1);
+      exit(second, 0);
+      break;
+    case 'unexpected-signal':
+      exit(first, null, 'SIGTERM');
+      exit(second, 0);
+      break;
+    case 'shutdown-SIGINT':
+    case 'shutdown-SIGUSR2': {
+      const signal = scenario.slice('shutdown-'.length);
+      process.emit(signal);
+      exit(first, null, signal);
+      exit(second, 0);
+      break;
+    }
+    case 'reload':
+    case 'reload-failure': {
+      globalThis.reloadFailure = scenario === 'reload-failure';
+      cluster.emit('message', first, 'reload-worker');
+      assert.equal(forks, 3);
+      const replacement = cluster.workers[3];
+      assert.ok(replacement);
+      exit(second, 0);
+      exit(replacement, 0);
+      break;
+    }
+    case 'reload-during-shutdown':
+      process.emit('SIGUSR2');
+      cluster.emit('message', first, 'reload-worker');
+      assert.equal(forks, 2, 'shutdown must not create a replacement');
+      exit(second, 0);
+      break;
+    case 'failure-then-shutdown':
+      exit(first, 1);
+      process.emit('SIGINT');
+      exit(second, null, 'SIGINT');
+      break;
+    case 'failure-during-shutdown':
+      process.emit('SIGINT');
+      exit(first, 1);
+      exit(second, 0);
+      break;
+    case 'unexpected-signal-during-shutdown':
+      process.emit('SIGINT');
+      exit(first, null, 'SIGKILL');
+      exit(second, 0);
+      break;
+    default:
+      throw new Error('Unknown scenario: ' + scenario);
+  }
+  throw new Error('Final worker exit must terminate the master');
+`;
+
+test('cluster creates the master app before installing handlers and forking workers', () => {
+  const source = `
+    import assert from 'node:assert/strict';
+    import { registerHooks } from 'node:module';
+    const clusterUrl = ${JSON.stringify(clusterUrl)};
+    const calls = globalThis.calls = [];
+    const mocks = {
+      'node:cluster': 'export default { isPrimary: true };',
+      './createApp.ts': 'export async function createAppMaster(options) { globalThis.calls.push("create"); await Promise.resolve(); globalThis.masterOptions = options; } export function createApp() { throw new Error("Unexpected worker"); }',
+      './processMaster.ts': 'export function handleProcessMaster(workers) { if (!globalThis.masterOptions) throw new Error("Master app not ready"); globalThis.calls.push(["handle", workers]); }',
+      './processWorker.ts': 'export function handleProcessWork() { throw new Error("Unexpected worker"); }',
+    };
+    registerHooks({
+      resolve(specifier, context, nextResolve) {
+        if (context.parentURL === clusterUrl && mocks[specifier]) {
+          return { url: 'data:text/javascript,' + encodeURIComponent(mocks[specifier]), shortCircuit: true };
+        }
+        return nextResolve(specifier, context);
+      },
+    });
+    const { startCluster } = await import(clusterUrl);
+    const options = {};
+    await startCluster(2, options);
+    assert.equal(globalThis.masterOptions, options);
+    assert.deepEqual(calls, ['create', ['handle', 2]]);
+  `;
+  const result = spawnSync(process.execPath, ['--input-type=module', '--eval', source], {
+    encoding: 'utf8',
+    timeout: 3_000,
+  });
+  assert.ifError(result.error);
+  assert.equal(result.signal, null, result.stderr);
+  assert.equal(result.status, 0, result.stderr);
+});
+
+const scenarios = [
+  { name: 'all-clean', code: 0 },
+  { name: 'failure-then-clean', code: 1 },
+  { name: 'unexpected-signal', code: 1 },
+  { name: 'shutdown-SIGINT', code: 0 },
+  { name: 'shutdown-SIGUSR2', code: 0 },
+  { name: 'reload', code: 0, reload: true },
+  { name: 'reload-failure', code: 1, reload: true },
+  { name: 'reload-during-shutdown', code: 0 },
+  { name: 'failure-then-shutdown', code: 1 },
+  { name: 'failure-during-shutdown', code: 1 },
+  { name: 'unexpected-signal-during-shutdown', code: 1 },
+];
+
+for (const scenario of scenarios) {
+  test(`process master: ${scenario.name}`, () => {
+    const result = spawnSync(
+      process.execPath,
+      ['--input-type=module', '--eval', masterSource, scenario.name],
+      { encoding: 'utf8', timeout: 3_000 },
+    );
+    assert.ifError(result.error);
+    assert.equal(result.signal, null, result.stderr);
+    assert.equal(result.status, scenario.code, result.stderr);
+    const summary = JSON.parse(result.stdout);
+    assert.equal(summary.code, scenario.code);
+    assert.equal(summary.forks, scenario.reload ? 3 : 2);
+    assert.equal(summary.exited.length, summary.forks);
+    assert.deepEqual(
+      summary.kills,
+      scenario.name.startsWith('reload') ? [{ id: 1, signal: 'SIGTERM' }] : [],
+    );
+  });
+}