vona-core 5.1.41 → 5.1.44

package/dist/index.js

@@ -2,16 +2,18 @@ import '@cabloy/json5';
 import { combineApiPathControllerAndActionRaw, combineApiPathControllerAndAction, combineApiPath, combineResourceName, forEach, forEachSync, sleep, isUndefined, isClass, isNilOrEmptyString, evaluateExpressions, catchErrorSync, isEmptyObject, catchError, hashkey } from '@cabloy/utils';
 import { toLowerCaseFirstChar, splitWords } from '@cabloy/word-utils';
 import path from 'node:path';
+import fse from 'fs-extra';
+import crypto, { createHash as createHash$1, randomBytes, timingSafeEqual } from 'node:crypto';
+import fs, { lstatSync, constants } from 'node:fs';
 import { compose as compose$1 } from '@cabloy/compose';
 import { extend } from '@cabloy/extend';
-import fse from 'fs-extra';
-import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import * as uuid from 'uuid';
-import fs from 'node:fs';
 import { getPlatformArch as getPlatformArch$1 } from 'vona';
 import os from 'node:os';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { isDeepStrictEqual } from 'node:util';
 import { setLocaleErrors, setLocaleAdapter, translateError } from '@cabloy/zod-errors-custom';
 import { ZodMetadata } from '@cabloy/zod-openapi';
 import { setParseAdapter } from '@cabloy/zod-query';
@@ -20,11 +22,12 @@ import { parseModuleName as parseModuleName$1, parseModuleFile as parseModuleFil
 import * as localeutil from '@cabloy/localeutil';
 import { getOnionMetasMeta } from '@cabloy/module-info';
 import KoaApplication from 'koa';
-import { AsyncLocalStorage } from 'node:async_hooks';
 import chalk from 'chalk';
 import * as Winston from 'winston';
 import DailyRotateFile from 'winston-daily-rotate-file';
 import { MESSAGE, LEVEL } from 'triple-beam';
+import { mkdir, open, rename, unlink } from 'node:fs/promises';
+import { createServer } from 'node:http';
 import cluster from 'node:cluster';
 import React from 'react';
 import { extendZodWithOpenApi } from '@cabloy/zod-to-openapi';
@@ -48,6 +51,92 @@ class BeanSimple {
   }
 }
 
+const TEST_RUN_ID_ENV = 'VONA_TEST_RUN_ID';
+const TEST_RUN_OWNER_FILE = '.vona-test-owner';
+const DATABASE_NAME_MAX_BYTES = 63;
+const APP_NAME_MAX_BYTES = 13;
+const HASH_LENGTH = 10;
+const TIMESTAMP_LENGTH = 15;
+function getDatabaseTestPrefix(appName, scope) {
+  const readablePrefix = scope === 'share' ? `vona-test-${appName}-s-` : `vona-test-${appName}-i-${scope.slice('isolate-'.length)}-`;
+  if (Buffer.byteLength(readablePrefix, 'utf8') + TIMESTAMP_LENGTH <= DATABASE_NAME_MAX_BYTES) {
+    return readablePrefix;
+  }
+  let appHead = '';
+  for (const char of appName) {
+    if (Buffer.byteLength(`${appHead}${char}`, 'utf8') > APP_NAME_MAX_BYTES) break;
+    appHead += char;
+  }
+  const scopeKind = scope === 'share' ? 's' : 'i';
+  const namespaceHash = createHash$1('sha256').update(`${appName}\0${scope}`).digest('base64url').slice(0, HASH_LENGTH);
+  return `vona-test-${appHead}-${scopeKind}-${namespaceHash}-`;
+}
+function assertDisposableDatabaseName(databaseName, databasePrefix) {
+  if (typeof databaseName !== 'string' || !databaseName.startsWith(databasePrefix) || !/^\d{8}-\d{6}$/.test(databaseName.slice(databasePrefix.length)) || Buffer.byteLength(databaseName, 'utf8') > DATABASE_NAME_MAX_BYTES) {
+    throw new Error(`Database is outside the disposable namespace: ${databaseName}`);
+  }
+}
+function resolveTestRunId(mode, runId = process.env[TEST_RUN_ID_ENV]) {
+  if (runId === undefined) return undefined;
+  const match = /^(\d{14})-[a-f0-9]{8}$/.exec(runId);
+  const timestamp = match?.[1];
+  const date = timestamp ? new Date(`${timestamp.slice(0, 4)}-${timestamp.slice(4, 6)}-${timestamp.slice(6, 8)}T${timestamp.slice(8, 10)}:${timestamp.slice(10, 12)}:${timestamp.slice(12, 14)}Z`) : undefined;
+  if (mode !== 'test' || !timestamp || !date || Number.isNaN(date.getTime()) || date.toISOString().slice(0, 19).replace(/[-:T]/g, '') !== timestamp) {
+    throw new Error(`${TEST_RUN_ID_ENV} requires test mode and a UTC timestamp plus eight hex digits`);
+  }
+  return runId;
+}
+function getTestAppName(runId) {
+  resolveTestRunId('test', runId);
+  return `cabtest${runId}`;
+}
+function assertTestAppIdentity(mode, runId, appName) {
+  const id = resolveTestRunId(mode, runId);
+  if (id && appName !== getTestAppName(id)) {
+    throw new Error('Isolated test APP_NAME does not match its run ID');
+  }
+  return id;
+}
+function getTestRunIdFromEnv(env) {
+  return resolveTestRunId(env.META_MODE, env[TEST_RUN_ID_ENV]);
+}
+function assertTestRunOwner(root, runId) {
+  resolveTestRunId('test', runId);
+  let current = path.resolve(root);
+  while (true) {
+    try {
+      if (lstatSync(current).isSymbolicLink()) {
+        throw new Error(`Isolated test path traverses a symlink: ${current}`);
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  const marker = path.join(root, TEST_RUN_OWNER_FILE);
+  if (!fse.lstatSync(marker).isFile() || fse.readFileSync(marker, 'utf8') !== `${runId}\n`) {
+    throw new Error(`Isolated test directory has no matching owner: ${root}`);
+  }
+}
+function resolveVonaLocalPaths(projectPath, mode, runId = process.env[TEST_RUN_ID_ENV]) {
+  const id = resolveTestRunId(mode, runId);
+  const generatedDir = id ? `.vona-test-${id}` : '.vona';
+  const dataDir = id ? `.app-test-${id}` : '.app';
+  return {
+    runId: id,
+    generatedDir,
+    dataDir,
+    generatedRoot: path.join(projectPath, generatedDir),
+    dataRoot: path.join(projectPath, dataDir),
+    publicRoot: path.join(projectPath, dataDir, 'public'),
+    runtimeRoot: path.join(projectPath, dataDir, 'runtime'),
+    logsRoot: path.join(projectPath, dataDir, 'logs'),
+    sqliteRoot: path.join(projectPath, dataDir, 'sqlite3')
+  };
+}
+
 const EnumAppEvent = {
   AppStarted: 'eb:event:appStarted',
   AppStartError: 'eb:event:appStartError'
@@ -91,6 +180,183 @@ function _matchSharpLibvipsFileName(fileName) {
   return /\.so(?:\..+)?$/.test(fileName);
 }
 
+const databaseDiscovery = new AsyncLocalStorage();
+async function withIsolatedTestDatabaseDiscovery(app, clientName, client, fn) {
+  if (!app.meta.env.VONA_TEST_RUN_ID) return fn();
+  if (app.meta.appReady) throw new Error('Isolated test cannot discover databases after startup');
+  const config = app.config;
+  const instanceClients = Object.values(config.instance.instances).flatMap(instance => instance && instance.isolate && instance.isolateClient ? [instance.isolateClient] : []);
+  if (!client || clientName !== config.database.defaultClient && !instanceClients.includes(clientName) || config.database.clients[clientName]?.client !== client.client || !isDeepStrictEqual(client.connection, config.database.clients[clientName].connection) || !client.connection || typeof client.connection !== 'object' || Array.isArray(client.connection)) {
+    throw new Error(`Isolated test cannot discover an unconfigured database client: ${clientName}`);
+  }
+  return databaseDiscovery.run({
+    app,
+    clientName,
+    client
+  }, async () => {
+    assertIsolatedTestDatabaseClient(app, clientName, client);
+    return await fn();
+  });
+}
+function assertIsolatedTestDatabaseClient(app, clientName, client) {
+  const id = assertTestAppIdentity(app.meta.env.META_MODE, app.meta.env.VONA_TEST_RUN_ID, app.name);
+  if (!id) return;
+  const paths = resolveVonaLocalPaths(app.projectPath, 'test', id);
+  assertTestRunOwner(paths.dataRoot, id);
+  if (client.connectionPool !== undefined) {
+    throw new Error(`Isolated test database cannot use an external pool: ${clientName}`);
+  }
+  if (!client.connection || typeof client.connection !== 'object' || Array.isArray(client.connection)) {
+    throw new Error(`Isolated test database requires an explicit connection target: ${clientName}`);
+  }
+  const connection = client.connection;
+  if (connection.connectionString !== undefined || connection.uri !== undefined) {
+    throw new Error(`Isolated test database cannot use a connection URL: ${clientName}`);
+  }
+  if (!['better-sqlite3', 'pg', 'mysql', 'mysql2'].includes(client.client)) {
+    throw new Error(`Isolated test database client is unsupported: ${clientName}`);
+  }
+  if (client.client === 'better-sqlite3' ? connection.database !== undefined : connection.filename !== undefined) {
+    throw new Error(`Isolated test database has conflicting connection targets: ${clientName}`);
+  }
+  const config = app.config;
+  const configured = config.database;
+  const discovering = databaseDiscovery.getStore();
+  const target = client.client === 'better-sqlite3' ? connection.filename : connection.database;
+  if (discovering?.app === app && discovering.clientName === clientName && !app.meta.appReady && configured.clients[clientName]?.client === client.client && client.client === discovering.client.client && isDeepStrictEqual(connection, discovering.client.connection) && isDeepStrictEqual(connection, configured.clients[clientName].connection)) {
+    const discoveryTarget = client.client === 'better-sqlite3' ? '' : client.client === 'pg' ? 'postgres' : 'mysql';
+    if (target === discoveryTarget || client.client === 'better-sqlite3' && target === ':memory:') {
+      return;
+    }
+  }
+  const scopes = new Set(['share']);
+  for (const [instanceName, instance] of Object.entries(config.instance.instances)) {
+    if (instance && instance.isolate && instance.isolateClient) {
+      scopes.add(`isolate-${instanceName}`);
+    }
+  }
+  if (typeof target !== 'string') {
+    throw new TypeError(`Isolated test database requires a disposable target: ${clientName}`);
+  }
+  let matched = false;
+  for (const scope of scopes) {
+    const prefix = getDatabaseTestPrefix(app.name, scope);
+    const databaseName = client.client === 'better-sqlite3' ? path.basename(target, '.db') : target;
+    try {
+      assertDisposableDatabaseName(databaseName, prefix);
+      matched = true;
+      break;
+    } catch {
+      // Try the next owned namespace.
+    }
+  }
+  if (!matched) throw new Error(`Isolated test database is outside its namespace: ${clientName}`);
+  if (client.client === 'better-sqlite3') {
+    if (!path.isAbsolute(target) || path.extname(target) !== '.db') {
+      throw new Error(`Isolated test SQLite target must be an owned .db file: ${clientName}`);
+    }
+    assertIsolatedTestPath(target, path.join(paths.sqliteRoot, path.basename(target)));
+  }
+}
+function assertIsolatedTestPath(actual, expected) {
+  if (path.resolve(actual) !== path.resolve(expected)) {
+    throw new Error(`Isolated test path escapes its owned root: ${actual}`);
+  }
+  let current = path.resolve(actual);
+  while (true) {
+    try {
+      if (lstatSync(current).isSymbolicLink()) {
+        throw new Error(`Isolated test path traverses a symlink: ${current}`);
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+}
+function assertIsolatedTestConfig(app) {
+  const env = app.meta.env;
+  const id = assertTestAppIdentity(env.META_MODE, env.VONA_TEST_RUN_ID, app.name);
+  if (!id) return;
+  const paths = resolveVonaLocalPaths(app.projectPath, env.META_MODE, id);
+  assertTestRunOwner(paths.dataRoot, id);
+  assertTestRunOwner(paths.generatedRoot, id);
+  assertIsolatedTestPath(app.config.server.publicDir, paths.publicRoot);
+  assertIsolatedTestPath(app.config.logger.baseDir, paths.logsRoot);
+  assertIsolatedTestPath(paths.runtimeRoot, paths.runtimeRoot);
+  assertIsolatedTestPath(paths.sqliteRoot, paths.sqliteRoot);
+  if (app.config.server.workers !== 1) throw new Error('Isolated test requires one Vona worker');
+  const config = app.config;
+  if (process.env.VONA_DB_RESET !== undefined) {
+    throw new Error('Isolated test cannot run a development database reset');
+  }
+  if (!config.database.testDatabase) {
+    throw new Error('Isolated test requires disposable test database configuration');
+  }
+  if (typeof config.database.defaultClient !== 'string') {
+    throw new TypeError('Isolated test requires a static default database client');
+  }
+  if (config.database.base.connection !== undefined || config.database.base.connectionPool !== undefined) {
+    throw new Error('Isolated test cannot inherit a database base connection target or pool');
+  }
+  const clientNames = new Set([config.database.defaultClient]);
+  const instances = config.instance.instances;
+  for (const instance of Object.values(instances)) {
+    if (!instance || !instance.isolate) continue;
+    if (!instance.isolateClient) throw new Error('Isolated test instance requires an isolateClient');
+    clientNames.add(instance.isolateClient);
+  }
+  for (const clientName of clientNames) {
+    if (!config.database.clients[clientName]) {
+      throw new Error(`Isolated test has no configured database client: ${clientName}`);
+    }
+  }
+  for (const [clientName, client] of Object.entries(config.database.clients)) {
+    if (client.connectionPool !== undefined) {
+      throw new Error(`Isolated test database client has an external target or pool: ${clientName}`);
+    }
+    // Optional, unused clients may intentionally remain empty in local configuration.
+    // Any configured connection is still validated, even when that client is not selected.
+    if (client.connection === undefined && !clientNames.has(clientName)) continue;
+    if (typeof client.connection !== 'object' || client.connection === null || Array.isArray(client.connection) || client.connection.connectionString !== undefined || client.connection.uri !== undefined) {
+      throw new Error(`Isolated test database client has an external target or pool: ${clientName}`);
+    }
+    if (!clientNames.has(clientName)) continue;
+    if (!['better-sqlite3', 'pg', 'mysql', 'mysql2'].includes(client.client)) {
+      throw new Error(`Isolated test has an unsupported database client: ${clientName}`);
+    }
+    const connection = client.connection;
+    const expected = client.client === 'better-sqlite3' ? '' : client.client === 'pg' ? 'postgres' : 'mysql';
+    const target = client.client === 'better-sqlite3' ? connection.filename : connection.database;
+    if (target !== expected && !(client.client === 'better-sqlite3' && target === ':memory:')) {
+      throw new Error(`Isolated test requires an administrative discovery connection: ${clientName}`);
+    }
+    if (client.client === 'better-sqlite3' ? connection.database !== undefined : connection.filename !== undefined) {
+      throw new Error(`Isolated test discovery connection has conflicting targets: ${clientName}`);
+    }
+  }
+  const redis = config.redis;
+  if (redis.base.keyPrefix !== undefined) {
+    throw new Error('Isolated test cannot inherit a Redis base keyPrefix');
+  }
+  for (const [clientName, client] of Object.entries(redis.clients)) {
+    const special = ['queue', 'broadcast'].includes(clientName) || clientName.startsWith('redlock');
+    if (client.sentinels || client.nodes) {
+      throw new Error(`Isolated test cannot use a Redis sentinel or cluster client: ${clientName}`);
+    }
+    if (special ? client.keyPrefix !== undefined : client.keyPrefix !== true) {
+      throw new Error(`Isolated test requires a framework-managed Redis prefix: ${clientName}`);
+    }
+  }
+  const expectedPort = Number(env.SERVER_LISTEN_PORT);
+  const requiresServerOrigin = process.env.VONA_TEST_SERVER_ORIGIN === 'true';
+  if (!Number.isInteger(expectedPort) || expectedPort <= 0 || expectedPort > 65535 || app.config.server.listen.port !== expectedPort || app.config.server.listen.hostname !== '127.0.0.1' || requiresServerOrigin && (app.config.server.serve.protocol !== 'http' || app.config.server.serve.host !== `127.0.0.1:${expectedPort}`)) {
+    throw new Error(requiresServerOrigin ? 'Isolated test listener and server origin must match the assigned loopback port' : 'Isolated test listener must match the assigned loopback port');
+  }
+}
+
 async function combineConfigDefault(app, configDefault, configDev, configProd, configTest) {
   let config = await configDefault(app);
   const mode = app.meta.env.META_MODE;
@@ -107,35 +373,50 @@ function getLoggerPathPhysicalRoot(app) {
   const mode = app.meta.env.META_MODE;
   let loggerDir;
   if (mode === 'test' || mode === 'dev') {
-    loggerDir = path.join(app.projectPath, '.app/logs');
+    loggerDir = resolveVonaLocalPaths(app.projectPath, mode, app.meta.env.VONA_TEST_RUN_ID).logsRoot;
   } else {
     loggerDir = path.join(getHomeVonaAppDir(app), 'logs');
   }
-  fse.ensureDirSync(loggerDir);
+  if (!app.options.configResolutionOnly) {
+    assertOwnedLocalPath(app, loggerDir, 'logsRoot');
+    fse.ensureDirSync(loggerDir);
+  }
   return loggerDir;
 }
 function getPublicPathPhysicalRoot(app) {
   const mode = app.meta.env.META_MODE;
   let publicDir;
   if (mode === 'test' || mode === 'dev') {
-    publicDir = path.join(app.projectPath, '.app/public');
+    publicDir = resolveVonaLocalPaths(app.projectPath, mode, app.meta.env.VONA_TEST_RUN_ID).publicRoot;
   } else {
     publicDir = path.join(getHomeVonaAppDir(app), 'public');
   }
-  fse.ensureDirSync(publicDir);
+  if (!app.options.configResolutionOnly) {
+    assertOwnedLocalPath(app, publicDir, 'publicRoot');
+    fse.ensureDirSync(publicDir);
+  }
   return publicDir;
 }
 function getRuntimePathPhysicalRoot(app) {
   const mode = app.meta.env.META_MODE;
   let runtimeDir;
   if (mode === 'test' || mode === 'dev') {
-    runtimeDir = path.join(app.options.projectPath, '.app/runtime');
+    runtimeDir = resolveVonaLocalPaths(app.options.projectPath, mode, app.meta.env.VONA_TEST_RUN_ID).runtimeRoot;
   } else {
     runtimeDir = path.join(getHomeVonaAppDir(app), 'runtime');
   }
-  fse.ensureDirSync(runtimeDir);
+  if (!app.options.configResolutionOnly) {
+    assertOwnedLocalPath(app, runtimeDir, 'runtimeRoot');
+    fse.ensureDirSync(runtimeDir);
+  }
   return runtimeDir;
 }
+function assertOwnedLocalPath(app, actual, leaf) {
+  const paths = resolveVonaLocalPaths(app.projectPath, app.meta.env.META_MODE, app.meta.env.VONA_TEST_RUN_ID);
+  if (!paths.runId) return;
+  assertTestRunOwner(paths.dataRoot, paths.runId);
+  assertIsolatedTestPath(actual, paths[leaf]);
+}
 function getHomeVonaAppDir(app) {
   return path.join(os.homedir(), '.vona', app.name);
 }
@@ -144,7 +425,7 @@ function getSqlite3DatabaseNameDefault(app) {
   const mode = app.meta.env.META_MODE;
   if (mode !== 'prod') return '';
   const dbPath = path.join(getHomeVonaAppDir(app), 'sqlite3');
-  fse.ensureDirSync(dbPath);
+  if (!app.options.configResolutionOnly) fse.ensureDirSync(dbPath);
   return path.join(dbPath, `${app.name}.db`);
 }
 function resolverSqlite3(projectPath) {
@@ -234,11 +515,16 @@ class AppUtil extends BeanSimple {
   }
   get protocol() {
     const config = this.ctx ? this.ctx.config : this.app.config;
-    return config.server.serve.protocol || this.ctx?.protocol;
+    return config.server.serve.protocol || this.ctx?.protocol || 'http';
   }
   get host() {
     const config = this.ctx ? this.ctx.config : this.app.config;
-    return config.server.serve.host || this.ctx?.host;
+    let host = config.server.serve.host || this.ctx?.host;
+    if (!host) {
+      const port = this.app.meta.env.SERVER_LISTEN_PORT;
+      host = port ? `localhost:${port}` : 'localhost';
+    }
+    return host;
   }
   getAbsoluteUrl(path) {
     const prefix = this.host ? `${this.protocol}://${this.host}` : '';
@@ -529,7 +815,7 @@ async function createGeneralApp(projectPath, envRuntime) {
     const testInstance = await import(pathToHref(testFile));
     return await testInstance.appBootstrap;
   } else {
-    const testFile = path.join(projectPath, '.vona/app.ts');
+    const testFile = path.join(resolveVonaLocalPaths(projectPath, process.env.META_MODE).generatedRoot, 'app.ts');
     const testInstance = await import(pathToHref(testFile));
     return await testInstance.createSingleApp();
   }
@@ -1915,7 +2201,7 @@ function $makeLocaleMagic(str, ...args) {
 }
 
 // not use : ILocaleMagic
-function text(strings, ...expressions) {
+function text$1(strings, ...expressions) {
   return {
     toString() {
       let result = '';
@@ -2678,10 +2964,9 @@ class VonaApplication extends KoaApplication {
     if (req) {
       request = req;
     } else {
-      const port = this.config?.server.listen.port ?? this.meta.env.SERVER_LISTEN_PORT;
-      const hostFallback = port ? `localhost:${port}` : 'localhost';
-      const protocol = (this.config ? this.util.protocol : undefined) || 'http';
-      const host = (this.config ? this.util.host : undefined) || hostFallback;
+      const protocol = 'http';
+      const port = this.meta.env.SERVER_LISTEN_PORT;
+      const host = port ? `localhost:${port}` : 'localhost';
       const hostname = new URL(`${protocol}://${host}`).hostname;
       request = {
         headers: {
@@ -2695,12 +2980,12 @@ class VonaApplication extends KoaApplication {
         host,
         hostname,
         protocol,
-        secure: protocol === 'https',
+        secure: false,
         method: 'POST',
         url: '',
         path: '',
         socket: {
-          encrypted: protocol === 'https',
+          encrypted: false,
           remoteAddress: '127.0.0.1',
           remotePort: 7001
         }
@@ -2891,6 +3176,717 @@ function __formatLoggerFilterCheckInfo(info) {
   return info;
 }
 
+const TEST_CLAIM_URL_ENV = 'VONA_TEST_CLAIM_URL';
+const TEST_CLAIM_TOKEN_ENV = 'VONA_TEST_CLAIM_TOKEN';
+const TEST_CLAIM_DIRECTORY = '.vona-test-claim';
+function getTestClaimPaths(projectPath, runId) {
+  resolveTestRunId('test', runId);
+  const project = path.resolve(projectPath);
+  const local = resolveVonaLocalPaths(project, 'test', runId);
+  const claimDirectory = path.join(project, TEST_CLAIM_DIRECTORY);
+  return {
+    ...local,
+    claimDirectory,
+    claimPath: path.join(claimDirectory, `${runId}.json`)
+  };
+}
+function getTestClaimCreatedAt(runId) {
+  resolveTestRunId('test', runId);
+  const s = runId.slice(0, 14);
+  return `${s.slice(0, 4)}-${s.slice(4, 6)}-${s.slice(6, 8)}T${s.slice(8, 10)}:${s.slice(10, 12)}:${s.slice(12, 14)}.000Z`;
+}
+function assertTestClaimSafePath(file, allowMissing = true) {
+  let current = path.resolve(file);
+  while (true) {
+    try {
+      const stat = lstatSync(current);
+      if (stat.isSymbolicLink() || current !== path.resolve(file) && !stat.isDirectory()) {
+        throw new Error('Unsafe test claim path');
+      }
+    } catch (error) {
+      if (!allowMissing || error.code !== 'ENOENT') throw error;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+}
+function record(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid test claim object');
+}
+function keys(value, allowed) {
+  record(value);
+  if (Object.keys(value).some(key => !allowed.includes(key))) throw new Error('Unknown test claim field');
+}
+function text(value) {
+  if (typeof value !== 'string' || !value || value.length > 4096 || [...value].some(char => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127)) {
+    throw new Error('Invalid test claim text');
+  }
+}
+function label(value) {
+  text(value);
+  if (!/^[\w.-]+$/.test(value)) throw new Error('Invalid test claim label');
+}
+function integer(value, min, max = Number.MAX_SAFE_INTEGER) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error('Invalid test claim integer');
+}
+function oneOf(value, values) {
+  if (!values.includes(value)) throw new Error('Invalid test claim state');
+}
+function bool(value) {
+  if (typeof value !== 'boolean') throw new Error('Invalid test claim boolean');
+}
+function array(value) {
+  if (!Array.isArray(value) || value.length > 10000) throw new Error('Invalid test claim array');
+}
+function unique(values) {
+  if (new Set(values).size !== values.length) throw new Error('Duplicate test claim resource');
+}
+function validateEndpoint(value, redis) {
+  keys(value, redis ? ['transport', 'host', 'port', 'socketPath', 'tls', 'db'] : ['dialect', 'transport', 'host', 'port', 'socketPath', 'tls', 'adminDatabase']);
+  const endpoint = value;
+  bool(endpoint.tls);
+  oneOf(endpoint.transport, redis ? ['tcp', 'socket'] : ['tcp', 'socket', 'file']);
+  if (redis) integer(endpoint.db, 0);else oneOf(endpoint.dialect, ['pg', 'mysql', 'mysql2', 'better-sqlite3']);
+  if (endpoint.transport === 'tcp') {
+    text(endpoint.host);
+    if (/[\s/@?#\\]/.test(endpoint.host)) throw new Error('Invalid test claim host');
+    integer(endpoint.port, 1, 65535);
+    if (endpoint.socketPath !== undefined) throw new Error('Conflicting test claim endpoint');
+  } else {
+    text(endpoint.socketPath);
+    if (!path.isAbsolute(endpoint.socketPath) || path.resolve(endpoint.socketPath) !== endpoint.socketPath || endpoint.host !== undefined) {
+      throw new Error('Invalid test claim socket');
+    }
+    if (!redis && endpoint.dialect === 'pg' && endpoint.transport === 'socket') integer(endpoint.port, 1, 65535);else if (endpoint.port !== undefined) throw new Error('Invalid test claim socket port');
+  }
+  if (!redis) {
+    if (endpoint.dialect === 'better-sqlite3') {
+      if (endpoint.transport !== 'file' || endpoint.tls || endpoint.adminDatabase !== undefined) throw new Error('Invalid SQLite claim endpoint');
+    } else if (endpoint.transport === 'file' || endpoint.adminDatabase !== (endpoint.dialect === 'pg' ? 'postgres' : 'mysql')) {
+      throw new Error('Invalid database administration endpoint');
+    }
+  }
+}
+function validateTestClaim(value, claimPath) {
+  keys(value, ['version', 'runId', 'createdAt', 'projectPath', 'kind', 'owner', 'status', 'locals', 'databases', 'redis', 'processes', 'cleanup']);
+  const m = value;
+  if (m.version !== 1) throw new Error('Unsupported test claim version');
+  resolveTestRunId('test', m.runId);
+  if (m.createdAt !== getTestClaimCreatedAt(m.runId)) throw new Error('Invalid test claim creation time');
+  text(m.projectPath);
+  if (!path.isAbsolute(m.projectPath) || path.resolve(m.projectPath) !== m.projectPath) throw new Error('Invalid test claim checkout');
+  const p = getTestClaimPaths(m.projectPath, m.runId);
+  if (claimPath && path.resolve(claimPath) !== p.claimPath) throw new Error('Test claim filename or checkout mismatch');
+  oneOf(m.kind, ['unit', 'cov', 'e2e']);
+  keys(m.owner, ['pid', 'startTime', 'host']);
+  integer(m.owner.pid, 1);
+  text(m.owner.startTime);
+  text(m.owner.host);
+  oneOf(m.status, ['allocated', 'running', 'failed', 'cleaning']);
+  array(m.locals);
+  unique(m.locals.map(item => item.kind));
+  for (const item of m.locals) {
+    keys(item, ['kind', 'path', 'stage']);
+    oneOf(item.kind, ['generated', 'data']);
+    oneOf(item.stage, ['intent', 'created', 'owned', 'released']);
+    const expected = item.kind === 'generated' ? p.generatedRoot : p.dataRoot;
+    if (item.path !== expected) throw new Error('Invalid test claim local root');
+  }
+  if (m.locals.length !== 2 || !m.locals.some(item => item.kind === 'data') || !m.locals.some(item => item.kind === 'generated')) {
+    throw new Error('Missing test claim local roots');
+  }
+  array(m.databases);
+  unique(m.databases.map(item => `${item.clientName}\0${item.scope}`));
+  for (const db of m.databases) {
+    keys(db, ['clientName', 'scope', 'prefix', 'endpoint', 'creations']);
+    label(db.clientName);
+    text(db.scope);
+    if (db.scope !== 'share' && !/^isolate-[\w-]+$/.test(db.scope)) throw new Error('Invalid test claim database scope');
+    if (db.prefix !== getDatabaseTestPrefix(getTestAppName(m.runId), db.scope)) throw new Error('Invalid test claim database prefix');
+    validateEndpoint(db.endpoint, false);
+    if (db.endpoint.dialect === 'better-sqlite3' && db.endpoint.socketPath !== p.sqliteRoot) throw new Error('Invalid test claim SQLite root');
+    array(db.creations);
+    unique(db.creations.map(item => item.name));
+    for (const creation of db.creations) {
+      keys(creation, ['name', 'stage']);
+      oneOf(creation.stage, ['intent', 'created', 'released']);
+      text(creation.name);
+      let name = creation.name;
+      if (db.endpoint.dialect === 'better-sqlite3') {
+        if (name !== path.join(p.sqliteRoot, path.basename(name)) || path.extname(name) !== '.db') throw new Error('Invalid test claim SQLite target');
+        name = path.basename(name, '.db');
+      }
+      assertDisposableDatabaseName(name, db.prefix);
+    }
+  }
+  array(m.redis);
+  unique(m.redis.map(item => item.clientName));
+  for (const item of m.redis) {
+    keys(item, ['clientName', 'kind', 'prefix', 'endpoint', 'released']);
+    label(item.clientName);
+    oneOf(item.kind, ['client', 'queue', 'redlock']);
+    const expected = getTestClaimRedisPrefix(m.runId, item.clientName);
+    if (!expected || item.kind !== expected.kind || item.prefix !== expected.prefix) throw new Error('Invalid test claim Redis prefix');
+    validateEndpoint(item.endpoint, true);
+    bool(item.released);
+  }
+  array(m.processes);
+  unique(m.processes.map(item => item.id));
+  for (const proc of m.processes) {
+    keys(proc, ['id', 'role', 'stage', 'pid', 'pgid', 'startTime', 'host', 'profilePath']);
+    label(proc.id);
+    oneOf(proc.role, ['guardian', 'browser', 'cleanup']);
+    if (proc.host !== undefined) text(proc.host);
+    oneOf(proc.stage, ['pending', 'registered', 'drained']);
+    const hasIdentity = proc.pid !== undefined || proc.pgid !== undefined || proc.startTime !== undefined;
+    if (hasIdentity || proc.stage !== 'pending') {
+      integer(proc.pid, 1);
+      integer(proc.pgid, 1);
+      text(proc.startTime);
+    }
+    if (proc.profilePath !== undefined) {
+      text(proc.profilePath);
+      if (path.resolve(proc.profilePath) !== proc.profilePath || !proc.profilePath.startsWith(`${p.dataRoot}${path.sep}`)) {
+        throw new Error('Invalid test claim process profile');
+      }
+    }
+  }
+  keys(m.cleanup, ['processes', 'databases', 'redis', 'locals']);
+  for (const key of ['processes', 'databases', 'redis', 'locals']) bool(m.cleanup[key]);
+  return m;
+}
+function assertPrivateFile(file) {
+  assertTestClaimSafePath(file, false);
+  const stat = lstatSync(file);
+  if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o077) !== 0 || process.getuid && stat.uid !== process.getuid()) {
+    throw new Error('Unsafe test claim file');
+  }
+}
+async function loadTestClaim(claimPath) {
+  assertPrivateFile(claimPath);
+  const handle = await open(claimPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > 4 * 1024 * 1024) throw new Error('Invalid test claim file');
+    return validateTestClaim(parseTestClaimJson(await handle.readFile('utf8')), claimPath);
+  } finally {
+    await handle.close();
+  }
+}
+function parseTestClaimJson(source) {
+  // Claim identities stay literal even when @cabloy/json5 revives ISO strings.
+  return JSON.parse(source, function (key) {
+    return this[key];
+  });
+}
+async function syncDirectory(directory) {
+  const handle = await open(directory, constants.O_RDONLY);
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+async function createTestClaim(projectPath, runId, kind, owner) {
+  const p = getTestClaimPaths(projectPath, runId);
+  assertTestClaimSafePath(p.claimDirectory);
+  await mkdir(p.claimDirectory, {
+    mode: 0o700
+  }).catch(error => {
+    if (error.code !== 'EEXIST') throw error;
+  });
+  // The directory is shared across runs; an existing directory is valid, never an existing claim.
+  return createClaimFile(p, runId, kind, owner);
+}
+async function createClaimFile(p, runId, kind, owner) {
+  assertTestClaimSafePath(p.claimDirectory, false);
+  const directoryStat = lstatSync(p.claimDirectory);
+  if (!directoryStat.isDirectory() || (directoryStat.mode & 0o077) !== 0 || process.getuid && directoryStat.uid !== process.getuid()) {
+    throw new Error('Unsafe shared test claim directory');
+  }
+  const manifest = {
+    version: 1,
+    runId,
+    createdAt: getTestClaimCreatedAt(runId),
+    projectPath: path.dirname(p.claimDirectory),
+    kind,
+    owner,
+    status: 'allocated',
+    locals: [{
+      kind: 'generated',
+      path: p.generatedRoot,
+      stage: 'intent'
+    }, {
+      kind: 'data',
+      path: p.dataRoot,
+      stage: 'intent'
+    }],
+    databases: [],
+    redis: [],
+    processes: [],
+    cleanup: {
+      processes: false,
+      databases: false,
+      redis: false,
+      locals: false
+    }
+  };
+  validateTestClaim(manifest, p.claimPath);
+  const handle = await open(p.claimPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try {
+    await handle.writeFile(`${JSON.stringify(manifest, null, 2)}\n`);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await syncDirectory(p.claimDirectory);
+  return {
+    claimPath: p.claimPath,
+    manifest
+  };
+}
+
+// Only the live broker or a cleanup editor holding the exclusive cleanup lock may call this.
+async function writeTestClaim(claimPath, manifest) {
+  validateTestClaim(manifest, claimPath);
+  const previous = await loadTestClaim(claimPath);
+  for (const key of ['version', 'runId', 'createdAt', 'projectPath', 'kind', 'owner']) {
+    if (!isDeepStrictEqual(previous[key], manifest[key])) throw new Error('Test claim identity is immutable');
+  }
+  const temp = `${claimPath}.${randomBytes(12).toString('hex')}.tmp`;
+  const handle = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try {
+    try {
+      await handle.writeFile(`${JSON.stringify(manifest, null, 2)}\n`);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    assertPrivateFile(claimPath);
+    await rename(temp, claimPath);
+    await syncDirectory(path.dirname(claimPath));
+  } finally {
+    await unlink(temp).catch(error => {
+      if (error.code !== 'ENOENT') throw error;
+    });
+  }
+}
+function applyEvent(m, event) {
+  record(event);
+  switch (event.type) {
+    case 'local':
+      {
+        keys(event, ['type', 'kind', 'stage']);
+        const local = m.locals.find(item => item.kind === event.kind);
+        if (!local) throw new Error('Unplanned test claim local root');
+        const stages = ['intent', 'created', 'owned', 'released'];
+        if (stages.indexOf(event.stage) < stages.indexOf(local.stage)) throw new Error('Test claim local stage regression');
+        local.stage = event.stage;
+        break;
+      }
+    case 'status':
+      keys(event, ['type', 'status']);
+      m.status = event.status;
+      break;
+    case 'process':
+      {
+        keys(event, ['type', 'process']);
+        const old = m.processes.find(item => item.id === event.process.id);
+        if (!old) {
+          if (event.process.stage !== 'pending') throw new Error('Process needs a write-ahead intent');
+          m.processes.push(event.process);
+        } else {
+          if (old.role !== event.process.role) throw new Error('Test claim process identity changed');
+          if (event.process.profilePath !== undefined && old.profilePath !== event.process.profilePath) {
+            if (old.stage !== 'pending' || event.process.stage !== 'registered' || !old.profilePath || !event.process.profilePath.startsWith(`${old.profilePath}${path.sep}`)) {
+              throw new Error('Test claim process profile changed');
+            }
+          }
+          if (old.stage === 'drained' && event.process.stage !== 'drained' || old.stage === 'registered' && event.process.stage === 'pending') {
+            throw new Error('Test claim process stage regression');
+          }
+          if (old.stage === 'pending' && event.process.stage === 'drained') throw new Error('Pending process cannot establish drainage');
+          for (const key of ['pid', 'pgid', 'startTime', 'host']) {
+            if (old[key] !== undefined && event.process[key] !== undefined && old[key] !== event.process[key]) {
+              throw new Error('Test claim process identity changed');
+            }
+          }
+          Object.assign(old, event.process);
+        }
+        break;
+      }
+    case 'inventory':
+      {
+        keys(event, ['type', 'databases', 'redis']);
+        for (const plan of event.databases) {
+          keys(plan, ['clientName', 'scope', 'prefix', 'endpoint']);
+          const old = m.databases.find(item => item.clientName === plan.clientName && item.scope === plan.scope);
+          if (old) {
+            const {
+              creations: _,
+              ...oldPlan
+            } = old;
+            if (!isDeepStrictEqual(oldPlan, plan)) throw new Error('Database inventory drift');
+          } else {
+            m.databases.push({
+              ...plan,
+              creations: []
+            });
+          }
+        }
+        for (const resource of event.redis) {
+          const old = m.redis.find(item => item.clientName === resource.clientName);
+          if (old && !isDeepStrictEqual(old, resource)) throw new Error('Redis inventory drift');
+          if (!old) m.redis.push(resource);
+        }
+        break;
+      }
+    case 'database':
+      {
+        keys(event, ['type', 'database', 'name', 'stage']);
+        keys(event.database, ['clientName', 'scope', 'prefix', 'endpoint']);
+        const db = m.databases.find(item => item.clientName === event.database.clientName && item.scope === event.database.scope);
+        if (!db) throw new Error('Unplanned database creation');
+        const {
+          creations: _,
+          ...plan
+        } = db;
+        if (!isDeepStrictEqual(plan, event.database)) throw new Error('Database creation endpoint drift');
+        const old = db.creations.find(item => item.name === event.name);
+        if (!old) {
+          if (event.stage !== 'intent') throw new Error('Database needs a write-ahead intent');
+          db.creations.push({
+            name: event.name,
+            stage: event.stage
+          });
+        } else {
+          if (['intent', 'created', 'released'].indexOf(event.stage) < ['intent', 'created', 'released'].indexOf(old.stage)) {
+            throw new Error('Database creation stage regression');
+          }
+          old.stage = event.stage;
+        }
+        break;
+      }
+    case 'cleanup':
+      keys(event, ['type', 'resource', 'complete']);
+      if (!(event.resource in m.cleanup)) throw new Error('Unknown cleanup resource');
+      m.cleanup[event.resource] = event.complete;
+      break;
+    default:
+      throw new Error('Unknown test claim event');
+  }
+  validateTestClaim(m);
+}
+async function startTestClaimBroker(claimPath) {
+  await loadTestClaim(claimPath);
+  const token = randomBytes(32).toString('hex');
+  let queue = Promise.resolve();
+  let closing = false;
+  const update = event => {
+    if (closing) return Promise.reject(new Error('Test claim broker is closed'));
+    const result = queue.then(async () => {
+      const manifest = await loadTestClaim(claimPath);
+      applyEvent(manifest, event);
+      await writeTestClaim(claimPath, manifest);
+    });
+    queue = result.catch(() => {});
+    return result;
+  };
+  const server = createServer(async (req, res) => {
+    const auth = req.headers.authorization;
+    const expected = `Bearer ${token}`;
+    if (req.method !== 'POST' || req.url !== '/event' || typeof auth !== 'string' || Buffer.byteLength(auth) !== Buffer.byteLength(expected) || !timingSafeEqual(Buffer.from(auth), Buffer.from(expected))) {
+      res.writeHead(403).end();
+      req.resume();
+      return;
+    }
+    try {
+      let body = '';
+      for await (const chunk of req) {
+        body += chunk.toString('utf8');
+        if (Buffer.byteLength(body) > 1024 * 1024) throw new Error('Test claim event too large');
+      }
+      await update(parseTestClaimJson(body));
+      res.writeHead(204).end();
+    } catch {
+      res.writeHead(409).end('Test claim registration rejected');
+    }
+  });
+  server.requestTimeout = 10000;
+  server.headersTimeout = 10000;
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string') throw new Error('Cannot bind test claim broker');
+  return {
+    env: {
+      [TEST_CLAIM_URL_ENV]: `http://127.0.0.1:${address.port}/event`,
+      [TEST_CLAIM_TOKEN_ENV]: token
+    },
+    update,
+    async close() {
+      closing = true;
+      await new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
+      await queue;
+    }
+  };
+}
+function hasTestClaimTransport(env = process.env) {
+  const url = env[TEST_CLAIM_URL_ENV];
+  const token = env[TEST_CLAIM_TOKEN_ENV];
+  if (url === undefined && token === undefined) return false;
+  if (!url || !token) throw new Error('Incomplete managed test claim transport');
+  if (!resolveTestRunId(env.META_MODE, env.VONA_TEST_RUN_ID)) throw new Error('Managed test claim transport requires test identity');
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error('Invalid managed test claim transport');
+  }
+  if (parsed.protocol !== 'http:' || parsed.hostname !== '127.0.0.1' || !parsed.port || parsed.pathname !== '/event' || parsed.username || parsed.password || parsed.search || parsed.hash || !/^[a-f0-9]{64}$/.test(token)) {
+    throw new Error('Invalid managed test claim transport');
+  }
+  return true;
+}
+async function sendTestClaimEvent(env, event) {
+  if (!hasTestClaimTransport(env)) return;
+  try {
+    const response = await fetch(env[TEST_CLAIM_URL_ENV], {
+      method: 'POST',
+      headers: {
+        'authorization': `Bearer ${env[TEST_CLAIM_TOKEN_ENV]}`,
+        'content-type': 'application/json'
+      },
+      body: JSON.stringify(event),
+      signal: AbortSignal.timeout(10000),
+      redirect: 'error'
+    });
+    if (response.status !== 204) throw new Error('Registration rejected');
+  } catch {
+    throw new Error('Managed test allocation registration failed');
+  }
+}
+function getTestClaimRedisPrefix(runId, clientName) {
+  const appName = getTestAppName(runId);
+  if (clientName === 'broadcast') return undefined;
+  if (clientName === 'queue') return {
+    kind: 'queue',
+    prefix: `bull_${appName}_local:queue:`
+  };
+  if (clientName.startsWith('redlock')) return {
+    kind: 'redlock',
+    prefix: `redlock_${appName}_local:`
+  };
+  return {
+    kind: 'client',
+    prefix: `${clientName}_${appName}_local:`
+  };
+}
+function assertNoTlsTargetOverrides(tls) {
+  if (!tls) return;
+  if (typeof tls === 'string') throw new Error('Unsupported managed TLS profile');
+  if (typeof tls === 'object') {
+    for (const key of ['host', 'port', 'path', 'socketPath', 'socket', 'stream', 'lookup', 'createConnection', 'servername']) {
+      if (tls[key] !== undefined) throw new Error('Unsupported managed TLS target override');
+    }
+  }
+}
+// Only explicit connection fields are projected. Credentials, URLs and option snapshots never enter the journal.
+function normalizeTestClaimDatabaseEndpoint(client, projectPath, runId) {
+  const dialect = client.client;
+  record(client.connection);
+  const c = client.connection;
+  assertNoTlsTargetOverrides(c.ssl);
+  if (c.connectionString !== undefined || c.uri !== undefined || client.connectionPool !== undefined || c.stream !== undefined || c.lookup !== undefined || client.driver !== undefined || client.dialect !== undefined || c.beforeConnect !== undefined) {
+    throw new Error('Unsupported managed database target');
+  }
+  let endpoint;
+  if (dialect === 'better-sqlite3') {
+    endpoint = {
+      dialect,
+      transport: 'file',
+      socketPath: getTestClaimPaths(projectPath, runId).sqliteRoot,
+      tls: false
+    };
+  } else {
+    if (!['pg', 'mysql', 'mysql2'].includes(dialect)) throw new Error('Unsupported managed database dialect');
+    const socket = c.socketPath ?? (dialect === 'pg' && typeof c.host === 'string' && c.host.startsWith('/') ? c.host : undefined);
+    const adminDatabase = dialect === 'pg' ? 'postgres' : 'mysql';
+    if (socket !== undefined) {
+      endpoint = {
+        dialect,
+        transport: 'socket',
+        socketPath: socket,
+        ...(dialect === 'pg' ? {
+          port: Number(c.port)
+        } : {}),
+        tls: Boolean(c.ssl),
+        adminDatabase
+      };
+    } else {
+      // pg otherwise consults mutable PGHOST/PGPORT environment defaults: fail closed.
+      if (dialect === 'pg' && (c.host === undefined || c.port === undefined)) throw new Error('Managed PostgreSQL requires explicit host and port');
+      endpoint = {
+        dialect,
+        transport: 'tcp',
+        host: c.host ?? 'localhost',
+        port: Number(c.port ?? 3306),
+        tls: Boolean(c.ssl),
+        adminDatabase
+      };
+    }
+  }
+  validateEndpoint(endpoint, false);
+  return endpoint;
+}
+function mergeClaimOptions(...sources) {
+  const result = {};
+  for (const source of sources) {
+    for (const [key, value] of Object.entries(source ?? {})) {
+      if (['__proto__', 'constructor', 'prototype'].includes(key)) throw new Error('Unsupported managed option field');
+      if (value === undefined) continue;
+      if (value && Object.getPrototypeOf(value) === Object.prototype) {
+        const previous = result[key];
+        result[key] = mergeClaimOptions(previous && Object.getPrototypeOf(previous) === Object.prototype ? previous : {}, value);
+      } else {
+        result[key] = value;
+      }
+    }
+  }
+  return result;
+}
+function mergeTestClaimDatabaseOptions(base, dialect, client) {
+  return mergeClaimOptions(base, dialect ?? {}, client);
+}
+function mergeTestClaimRedisOptions(base, client) {
+  // Match extend(true, ...) for connection/TLS objects and undefined values without importing runtime code.
+  return mergeClaimOptions(base, client);
+}
+function normalizeTestClaimRedisEndpoint(options) {
+  assertNoTlsTargetOverrides(options.tls);
+  if (options.sentinels || options.nodes || options.url || options.connectionString || options.Connector !== undefined || options.connector !== undefined || options.stream !== undefined || options.dnsLookup !== undefined || options.natMap !== undefined) {
+    throw new Error('Unsupported managed Redis target');
+  }
+  const endpoint = options.path !== undefined ? {
+    transport: 'socket',
+    socketPath: options.path,
+    tls: Boolean(options.tls),
+    db: Number(options.db ?? 0)
+  } : {
+    transport: 'tcp',
+    host: options.host ?? 'localhost',
+    port: Number(options.port ?? 6379),
+    tls: Boolean(options.tls),
+    db: Number(options.db ?? 0)
+  };
+  validateEndpoint(endpoint, true);
+  return endpoint;
+}
+function buildTestClaimResourceInventory(app) {
+  const id = resolveTestRunId(app.meta.env.META_MODE, app.meta.env.VONA_TEST_RUN_ID);
+  if (!id || app.name !== getTestAppName(id)) throw new Error('Managed resource inventory requires test identity');
+  const database = app.config.database;
+  const scopes = [['share', database.defaultClient]];
+  for (const [name, instance] of Object.entries(app.config.instance.instances)) {
+    const item = instance;
+    if (item && item.isolate) scopes.push([`isolate-${name}`, item.isolateClient]);
+  }
+  const databases = scopes.map(([scope, clientName]) => {
+    const client = database.clients[clientName];
+    if (!client) throw new Error('Managed database client is missing');
+    const options = mergeTestClaimDatabaseOptions(database.base, undefined, client);
+    return {
+      clientName,
+      scope,
+      prefix: getDatabaseTestPrefix(app.name, scope),
+      endpoint: normalizeTestClaimDatabaseEndpoint(options, app.projectPath, id)
+    };
+  });
+  const redis = [];
+  for (const [clientName, client] of Object.entries(app.config.redis.clients)) {
+    const prefix = getTestClaimRedisPrefix(id, clientName);
+    if (!prefix) continue;
+    const options = mergeTestClaimRedisOptions(app.config.redis.base, client);
+    redis.push({
+      clientName,
+      ...prefix,
+      endpoint: normalizeTestClaimRedisEndpoint(options),
+      released: false
+    });
+  }
+  return {
+    databases,
+    redis
+  };
+}
+const appInventories = new WeakMap();
+const appDatabaseIntents = new WeakMap();
+async function registerTestClaimResourceInventory(app) {
+  if (!hasTestClaimTransport()) return;
+  const inventory = buildTestClaimResourceInventory(app);
+  await sendTestClaimEvent(process.env, {
+    type: 'inventory',
+    ...inventory
+  });
+  appInventories.set(app, inventory);
+  appDatabaseIntents.set(app, new Set());
+}
+function assertTestClaimDatabaseClient(app, clientName, config) {
+  if (!hasTestClaimTransport()) return;
+  const inventory = appInventories.get(app);
+  const id = resolveTestRunId(app.meta.env.META_MODE, app.meta.env.VONA_TEST_RUN_ID);
+  const endpoint = normalizeTestClaimDatabaseEndpoint(config, app.projectPath, id);
+  const matches = inventory?.databases.filter(item => isDeepStrictEqual(item.endpoint, endpoint));
+  if (!matches?.length) throw new Error('Unregistered managed database endpoint');
+  const target = config.connection[endpoint.dialect === 'better-sqlite3' ? 'filename' : 'database'];
+  const admin = endpoint.dialect === 'better-sqlite3' ? ['', ':memory:'].includes(target) : target === endpoint.adminDatabase;
+  if (admin) {
+    if (!matches.some(item => item.clientName === clientName)) throw new Error('Unregistered managed database endpoint');
+  } else if (!matches.some(item => appDatabaseIntents.get(app)?.has(`${item.clientName}\0${target}`))) {
+    throw new Error('Unregistered managed database allocation');
+  }
+}
+async function registerTestClaimDatabaseCreation(app, config, databaseName, stage) {
+  if (!hasTestClaimTransport()) return;
+  const id = resolveTestRunId(app.meta.env.META_MODE, app.meta.env.VONA_TEST_RUN_ID);
+  const endpoint = normalizeTestClaimDatabaseEndpoint(config, app.projectPath, id);
+  const plan = appInventories.get(app)?.databases.find(item => {
+    if (!isDeepStrictEqual(item.endpoint, endpoint)) return false;
+    try {
+      assertDisposableDatabaseName(databaseName, item.prefix);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  if (!plan) throw new Error('Unregistered managed database creation endpoint');
+  const name = endpoint.dialect === 'better-sqlite3' ? path.join(getTestClaimPaths(app.projectPath, id).sqliteRoot, `${databaseName}.db`) : databaseName;
+  await sendTestClaimEvent(process.env, {
+    type: 'database',
+    database: plan,
+    name,
+    stage
+  });
+  appDatabaseIntents.get(app).add(`${plan.clientName}\0${name}`);
+}
+function assertTestClaimRedisClient(app, clientName, options) {
+  if (!hasTestClaimTransport()) return;
+  // Broadcast carries subscriptions only, but may not drift to an unregistered endpoint either.
+  const inventory = appInventories.get(app);
+  const endpoint = normalizeTestClaimRedisEndpoint(options);
+  const plan = inventory?.redis.find(item => item.clientName === clientName);
+  if (clientName === 'broadcast') {
+    const current = normalizeTestClaimRedisEndpoint(mergeTestClaimRedisOptions(app.config.redis.base, app.config.redis.clients.broadcast));
+    if (!inventory || !isDeepStrictEqual(current, endpoint)) throw new Error('Unregistered managed Redis broadcast endpoint');
+    return;
+  }
+  if (!plan || !isDeepStrictEqual(plan.endpoint, endpoint)) throw new Error('Unregistered managed Redis endpoint');
+  if (plan.kind === 'client' ? options.keyPrefix !== plan.prefix : options.keyPrefix !== undefined) throw new Error('Unregistered managed Redis key prefix');
+}
+
 function jsxEnhance() {
   const createElementOriginal = React.createElement;
   React.createElement = function (...args) {
@@ -3154,6 +4150,8 @@ class Start {
     // config
     const appConfig = await __prepareConfig(app);
     this.app.config = appConfig;
+    assertIsolatedTestConfig(app);
+    await registerTestClaimResourceInventory(app);
     this.app.keys = appConfig.server.keys;
     this.app.proxy = appConfig.proxy.enable;
     this.app.subdomainOffset = appConfig.server.subdomainOffset;
@@ -3237,6 +4235,7 @@ function __createApp({
   jsxEnhance();
   // env
   const env2 = prepareEnv(env);
+  assertTestAppIdentity(env2.META_MODE, env2.VONA_TEST_RUN_ID, env2.APP_NAME ?? '');
   // appInfo
   const appInfo = prepareAppInfo(env2);
   // options
@@ -3486,5 +4485,5 @@ async function retry(options, fn) {
 
 zodExtendOpenApi();
 
-export { $Class, $localeScope, $makeLocaleMagic, $protocolKey, AppHmr, AppHmrDeps, AppLocale, AppLogger, AppMeta, AppMetadata, AppResource, AppUtil, BeanAopBase, BeanAopMethodBase, BeanBase, BeanBaseSimple, BeanContainer, BeanInfo, BeanScopeBase, BeanScopeContainer, BeanScopeError, BeanScopeErrorImpl, BeanScopeLocale, BeanScopeScene, BeanScopeUtil, BeanSimple, EnumAppEvent, ErrorClass, Global, LocaleModuleNameSeparator, PickClassInner, ProxyDisable, SymbolBeanContainerInstances, SymbolBeanFullName, SymbolBeanInstanceKey, SymbolBeanInstancePropsLazy, SymbolCacheAopChains, SymbolCacheAopChainsKey, SymbolDecoratorBeanFullName, SymbolDecoratorBeanInfo, SymbolDecoratorGlobal, SymbolDecoratorProxyDisable, SymbolDecoratorUse, SymbolDecoratorVirtual, SymbolHmrStateLoad, SymbolHmrStateSave, SymbolMappedClassMetadataKeys, SymbolModuleBelong, SymbolModuleName, Use, Virtual, VonaApplication, __prepareInjectSelectorInfo, appHmrDeps, appMetadata, appResource, beanFullNameFromOnionName, bootstrap, cast, closeApp, combineConfigDefault, combineFilePathSafe, compose, copyAddon, copyMetadataOfClasses, copyProperties, copyPropertiesOfClasses, createApp, createAppMaster, createBeanDecorator, createGeneralApp, createHash, deepExtend, disposeInstance, errorsInternal, filterHeaders, formatLoggerAxiosError, formatLoggerConsole, formatLoggerCtx, formatLoggerDummy, formatLoggerErrors, formatLoggerFilter, functionNoop, getHomeVonaAppDir, getLoggerPathPhysicalRoot, getMappedClassMetadataKeys, getPlatformArch, getPublicPathPhysicalRoot, getRuntimePathPhysicalRoot, getSqlite3DatabaseNameDefault, instanceDesp, isLocaleMagic, loadJSONFile, onionNameFromBeanFullName, pathToHref, polyfillDispose, prepareEnv, registerMappedClassMetadataKey, requireAddon, requireDynamic, resolveAddon, resolverSharp, resolverSharpLibvips, resolverSqlite3, retry, saveJSONFile, setMappedClassMetadataKeys, text, useApp, usePrepareArg, usePrepareArgs, uuidv4 };
+export { $Class, $localeScope, $makeLocaleMagic, $protocolKey, AppHmr, AppHmrDeps, AppLocale, AppLogger, AppMeta, AppMetadata, AppResource, AppUtil, BeanAopBase, BeanAopMethodBase, BeanBase, BeanBaseSimple, BeanContainer, BeanInfo, BeanScopeBase, BeanScopeContainer, BeanScopeError, BeanScopeErrorImpl, BeanScopeLocale, BeanScopeScene, BeanScopeUtil, BeanSimple, EnumAppEvent, ErrorClass, Global, LocaleModuleNameSeparator, PickClassInner, ProxyDisable, SymbolBeanContainerInstances, SymbolBeanFullName, SymbolBeanInstanceKey, SymbolBeanInstancePropsLazy, SymbolCacheAopChains, SymbolCacheAopChainsKey, SymbolDecoratorBeanFullName, SymbolDecoratorBeanInfo, SymbolDecoratorGlobal, SymbolDecoratorProxyDisable, SymbolDecoratorUse, SymbolDecoratorVirtual, SymbolHmrStateLoad, SymbolHmrStateSave, SymbolMappedClassMetadataKeys, SymbolModuleBelong, SymbolModuleName, TEST_CLAIM_DIRECTORY, TEST_CLAIM_TOKEN_ENV, TEST_CLAIM_URL_ENV, TEST_RUN_ID_ENV, TEST_RUN_OWNER_FILE, Use, Virtual, VonaApplication, __prepareInjectSelectorInfo, appHmrDeps, appMetadata, appResource, assertDisposableDatabaseName, assertIsolatedTestConfig, assertIsolatedTestDatabaseClient, assertIsolatedTestPath, assertTestAppIdentity, assertTestClaimDatabaseClient, assertTestClaimRedisClient, assertTestClaimSafePath, assertTestRunOwner, beanFullNameFromOnionName, bootstrap, buildTestClaimResourceInventory, cast, closeApp, combineConfigDefault, combineFilePathSafe, compose, copyAddon, copyMetadataOfClasses, copyProperties, copyPropertiesOfClasses, createApp, createAppMaster, createBeanDecorator, createGeneralApp, createHash, createTestClaim, deepExtend, disposeInstance, errorsInternal, filterHeaders, formatLoggerAxiosError, formatLoggerConsole, formatLoggerCtx, formatLoggerDummy, formatLoggerErrors, formatLoggerFilter, functionNoop, getDatabaseTestPrefix, getHomeVonaAppDir, getLoggerPathPhysicalRoot, getMappedClassMetadataKeys, getPlatformArch, getPublicPathPhysicalRoot, getRuntimePathPhysicalRoot, getSqlite3DatabaseNameDefault, getTestAppName, getTestClaimCreatedAt, getTestClaimPaths, getTestClaimRedisPrefix, getTestRunIdFromEnv, hasTestClaimTransport, instanceDesp, isLocaleMagic, loadJSONFile, loadTestClaim, mergeTestClaimDatabaseOptions, mergeTestClaimRedisOptions, normalizeTestClaimDatabaseEndpoint, normalizeTestClaimRedisEndpoint, onionNameFromBeanFullName, pathToHref, polyfillDispose, prepareEnv, registerMappedClassMetadataKey, registerTestClaimDatabaseCreation, registerTestClaimResourceInventory, requireAddon, requireDynamic, resolveAddon, resolveTestRunId, resolveVonaLocalPaths, resolverSharp, resolverSharpLibvips, resolverSqlite3, retry, saveJSONFile, sendTestClaimEvent, setMappedClassMetadataKeys, startTestClaimBroker, text$1 as text, useApp, usePrepareArg, usePrepareArgs, uuidv4, validateTestClaim, withIsolatedTestDatabaseDiscovery, writeTestClaim };
 //# sourceMappingURL=index.js.map