@verdeect/kit 0.0.0-stage → 1.0.0-rc.2

package/dist/testing/tenant-isolation.js

@@ -0,0 +1,205 @@
+// assertAppRoleIsNotOwner, assertStrictTenantIsolation (prd.md §3.8, AC-4.6, AC-4.8). Проверки — по каталогу PostgreSQL
+// под ролью приложения; pg не импортируется: db — объект с query. E5: политика outbox по OUTBOX_POLICY_SQL
+// (createOutboxTable), имена — internal/outbox-policy (/testing не грузит /messaging).
+import { OUTBOX_POLICY, OUTBOX_TABLE } from '../internal/outbox-policy.js';
+const USER_SCHEMAS = `nspname not in ('pg_catalog', 'information_schema') and nspname not like 'pg\\_toast%' and nspname not like 'pg\\_temp%'`;
+async function rows(db, text) {
+    return (await db.query(text)).rows;
+}
+/**
+ * Роль соединения — роль приложения, а не владелец (AC-4.6): не суперпользователь, без `BYPASSRLS`, не владеет
+ * схемами и таблицами, без `CREATE` на базе и схемах (KT-19 п. 1).
+ * @throws {Error} «assertAppRoleIsNotOwner: <роль>: <нарушения через «; »>».
+ */
+export async function assertAppRoleIsNotOwner(db) {
+    const violations = [];
+    const [role] = await rows(db, 'select rolname, rolsuper, rolbypassrls from pg_roles where rolname = current_user');
+    if (role?.rolsuper === true) {
+        violations.push('суперпользователь');
+    }
+    if (role?.rolbypassrls === true) {
+        violations.push('BYPASSRLS');
+    }
+    const owner = '(select oid from pg_roles where rolname = current_user)';
+    const schemas = await rows(db, `select nspname from pg_namespace where nspowner = ${owner} and ${USER_SCHEMAS} order by nspname`);
+    if (schemas.length > 0) {
+        violations.push(`владеет схемами ${schemas.map((row) => row.nspname).join(', ')}`);
+    }
+    const tables = await rows(db, `select n.nspname || '.' || c.relname as name from pg_class c
+         join pg_namespace n on n.oid = c.relnamespace
+         where c.relowner = ${owner} and ${USER_SCHEMAS.replaceAll('nspname', 'n.nspname')}
+         order by 1`);
+    if (tables.length > 0) {
+        violations.push(`владеет объектами ${tables.map((row) => row.name).join(', ')}`);
+    }
+    const [database] = await rows(db, `select current_database() as name, has_database_privilege(current_user, current_database(), 'CREATE') as create`);
+    if (database?.create === true) {
+        violations.push(`CREATE на базе ${database.name}`);
+    }
+    const creatable = await rows(db, `select nspname from pg_namespace where ${USER_SCHEMAS} and has_schema_privilege(current_user, oid, 'CREATE') order by nspname`);
+    for (const schema of creatable) {
+        violations.push(`CREATE на схеме ${schema.nspname}`);
+    }
+    if (violations.length > 0) {
+        throw new Error(`assertAppRoleIsNotOwner: ${role?.rolname ?? 'неизвестная роль'}: ${violations.join('; ')}`);
+    }
+}
+/** Формы политик PostgreSQL 17 (`pg_policies.qual`) для `tenantPolicy` и `createIdempotencyTable`. */
+const TENANT_POLICY = "(tenant = current_setting('app.tenant'::text, true))";
+const IDEMPOTENCY_POLICY = "(NOT (tenant IS DISTINCT FROM NULLIF(current_setting('app.tenant'::text, true), ''::text)))";
+const IDEMPOTENCY_TABLE = 'idempotency_key';
+/** Печатная форма PostgreSQL 17 выражения OUTBOX_POLICY_SQL (`createOutboxTable`). */
+const OUTBOX_POLICY_PG = "((COALESCE(current_setting('app.tenant'::text, true), ''::text) = ''::text) OR (tenant = current_setting('app.tenant'::text, true)))";
+/** Без внешних скобок и пробелов, в нижнем регистре. */
+function normalize(expression) {
+    let text = (expression ?? '').replace(/\s+/g, '').toLowerCase();
+    while (text.startsWith('(') && text.endsWith(')') && balanced(text.slice(1, -1))) {
+        text = text.slice(1, -1);
+    }
+    return text;
+}
+function balanced(text) {
+    let depth = 0;
+    for (const char of text) {
+        depth += char === '(' ? 1 : char === ')' ? -1 : 0;
+        if (depth < 0) {
+            return false;
+        }
+    }
+    return depth === 0;
+}
+function quote(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/** Соединение для транзакции: клиент пула (`pg.Pool` — `connect` и `totalCount`) или само соединение. */
+async function withConnection(db, work) {
+    const pool = db;
+    if (typeof pool.connect !== 'function' || !('totalCount' in db)) {
+        return work(db);
+    }
+    const client = await pool.connect();
+    try {
+        return await work(client);
+    }
+    finally {
+        client.release();
+    }
+}
+async function policyViolations(db, schema, table) {
+    const policies = (await db.query('select policyname, roles, permissive, cmd, qual, with_check from pg_policies where schemaname = $1 and tablename = $2', [schema, table])).rows;
+    if (policies.length === 0) {
+        return [`${table}: нет политики`];
+    }
+    if (table === OUTBOX_TABLE) {
+        return outboxPolicyViolations(policies);
+    }
+    const expected = normalize(table === IDEMPOTENCY_TABLE ? IDEMPOTENCY_POLICY : TENANT_POLICY);
+    return policies
+        .filter((policy) => policy.permissive !== 'PERMISSIVE' ||
+        policy.cmd !== 'ALL' ||
+        normalize(policy.qual) !== expected ||
+        normalize(policy.with_check) !== expected)
+        .map((policy) => `${table}.${policy.policyname}: нестрогая политика`);
+}
+/** Исключение строгой модели — ровно политика `createOutboxTable`: другое выражение не проходит. */
+function outboxPolicyViolations(policies) {
+    const expected = normalize(OUTBOX_POLICY_PG);
+    const [policy] = policies;
+    const roles = Array.isArray(policy?.roles)
+        ? policy.roles.join(',')
+        : String(policy?.roles ?? '');
+    const valid = policies.length === 1 &&
+        policy?.policyname === OUTBOX_POLICY &&
+        policy.permissive === 'PERMISSIVE' &&
+        policy.cmd === 'ALL' &&
+        roles.replace(/[{}]/g, '') === 'public' &&
+        normalize(policy.qual) === expected &&
+        normalize(policy.with_check) === expected;
+    return valid ? [] : [`${OUTBOX_TABLE}: политика не по createOutboxTable (${OUTBOX_POLICY})`];
+}
+async function visibleRows(db, schema, table) {
+    const filter = table === IDEMPOTENCY_TABLE ? ' where tenant is not null' : '';
+    return withConnection(db, async (connection) => {
+        await connection.query('begin');
+        try {
+            await connection.query("select set_config('app.tenant', '', true)");
+            const { rows } = await connection.query(`select count(*)::int as count from ${quote(schema)}.${quote(table)}${filter}`);
+            const count = rows[0]?.count ?? 0;
+            return count > 0
+                ? [`${table}: под ролью приложения с пустым тенантом видно ${count} строк`]
+                : [];
+        }
+        catch (error) {
+            if (error.code === '42501') {
+                return [`${table}: у роли приложения нет SELECT`];
+            }
+            throw error;
+        }
+        finally {
+            await connection.query('rollback');
+        }
+    });
+}
+/** Функция очистки — по точной сигнатуре `idempotency_purge(integer)`; другая перегрузка — «функции нет» (KT-22 п. 7). */
+async function purgeViolations(db, schema) {
+    const name = `${schema}.idempotency_purge`;
+    const [fn] = (await db.query(`select p.prosecdef, pg_get_userbyid(p.proowner) as owner, p.proconfig,
+                    has_function_privilege('public', p.oid, 'EXECUTE') as public_execute
+             from pg_proc p
+             where p.oid = to_regprocedure($1)`, [`${quote(schema)}.idempotency_purge(integer)`])).rows;
+    if (fn === undefined) {
+        return [`нет функции ${name} (idempotencyPurgeSql)`];
+    }
+    const violations = [];
+    if (!fn.prosecdef) {
+        violations.push(`${name}: не SECURITY DEFINER`);
+    }
+    if (fn.owner !== `${schema}_directory`) {
+        violations.push(`${name}: владелец ${fn.owner}, нужен ${schema}_directory`);
+    }
+    if (!(fn.proconfig ?? []).some((item) => item.startsWith('search_path='))) {
+        violations.push(`${name}: search_path не задан`);
+    }
+    if (fn.public_execute) {
+        violations.push(`${name}: EXECUTE у PUBLIC`);
+    }
+    return violations;
+}
+/**
+ * Строгий RLS схемы сервиса (§3.8, AC-4.8) — соединение **роли приложения**: каждая таблица с колонкой `tenant` — RLS,
+ * `FORCE`, строгая политика (`tenantPolicy`; `idempotency_key` — `createIdempotencyTable`); `outbox` — исключение строгой
+ * модели: политика `createOutboxTable` (пустой тенант — все строки), RLS и FORCE обязательны; под пустым тенантом 0 строк (вызывать после вставки данных фабриками); при таблице идемпотентности —
+ * функция `idempotency_purge` `SECURITY DEFINER`, владелец `<svc>_directory`, `search_path`, без `EXECUTE` у `PUBLIC`.
+ * @throws {Error} «assertStrictTenantIsolation(<схема>): <нарушения через «; »>».
+ */
+export async function assertStrictTenantIsolation(db, options) {
+    const { schema } = options;
+    const except = new Set(options.except ?? []);
+    const tables = (await db.query(`select c.relname, c.relrowsecurity, c.relforcerowsecurity
+             from pg_class c join pg_namespace n on n.oid = c.relnamespace
+             join pg_attribute a on a.attrelid = c.oid and a.attname = 'tenant' and not a.attisdropped
+             where n.nspname = $1 and c.relkind in ('r', 'p') order by c.relname collate "C"`, [schema])).rows;
+    const violations = [];
+    if (tables.length === 0) {
+        violations.push('в схеме нет таблиц с колонкой tenant');
+    }
+    for (const table of tables.filter((item) => !except.has(item.relname))) {
+        const name = table.relname;
+        if (!table.relrowsecurity) {
+            violations.push(`${name}: RLS не включён`);
+        }
+        if (!table.relforcerowsecurity) {
+            violations.push(`${name}: нет FORCE ROW LEVEL SECURITY`);
+        }
+        violations.push(...(await policyViolations(db, schema, name)));
+        if (name !== OUTBOX_TABLE) {
+            violations.push(...(await visibleRows(db, schema, name)));
+        }
+    }
+    if (tables.some((item) => item.relname === IDEMPOTENCY_TABLE && !except.has(item.relname))) {
+        violations.push(...(await purgeViolations(db, schema)));
+    }
+    if (violations.length > 0) {
+        throw new Error(`assertStrictTenantIsolation(${schema}): ${violations.join('; ')}`);
+    }
+}

package/dist/testing/test-events.d.ts

@@ -0,0 +1,37 @@
+import type { z } from 'zod';
+import type { KitEvent } from '../messaging/define-event.js';
+import { type Envelope } from '../messaging/envelope.js';
+/** Опции `publishTestEvent`. */
+export interface KitPublishTestEventOptions {
+    /** id события; по умолчанию `evt_` + ULID. */
+    readonly id?: string;
+    /** Тенант; по умолчанию `workerScope().tenant` для `'required'`, `null` для `'none'`; может нарушать признак. */
+    readonly tenant?: string | null;
+    /** id субъекта; по умолчанию `tst_` + ULID. */
+    readonly subjectId?: string;
+    /** Время события; по умолчанию — сейчас. */
+    readonly occurredAt?: Date;
+    /** Актор; по умолчанию `{channel: 'system'}`. */
+    readonly actor?: Record<string, unknown> | null;
+    /** traceId; по умолчанию `null`. */
+    readonly traceId?: string | null;
+}
+/** @internal Адрес вместо `adminUrl` воркера (тест пакета: обрыв через tcpProxy); `undefined` — сброс. */
+export declare function setTestEventsUrl(url: string | undefined): void;
+/** @internal Закрытие текущего соединения `publishTestEvent` (сигнал теста пакета); нет соединения — `undefined`. */
+export declare function testEventsClosed(): Promise<void> | undefined;
+/**
+ * Публикует конверт `01` §7.1 в `verdeect.events` от имени администратора vhost воркера — как relay другого сервиса;
+ * ждёт подтверждения брокера.
+ * @returns опубликованный конверт.
+ * @throws {ZodError} `data` не по схеме события.
+ */
+export declare function publishTestEvent<E extends KitEvent>(event: E, data: z.input<E['data']>, opts?: KitPublishTestEventOptions): Promise<Envelope<E>>;
+/**
+ * Ждёт строку `id` в `<svc>.inbox` (обработка подписчиком с `dedupe: 'inbox'`) с шагом 20 мс до
+ * `timeoutMs × TEST_TIMEOUT_SCALE` — без `sleep` в тесте. Для `dedupe: 'none'` ждать побочный эффект обработчика.
+ * @throws {Error} срок вышел — «waitForInbox: событие <id> не обработано за <timeoutMs> мс».
+ */
+export declare function waitForInbox(id: string, options: {
+    readonly timeoutMs: number;
+}): Promise<void>;

package/dist/testing/test-events.js

@@ -0,0 +1,150 @@
+import { newId } from '../internal/ids.js';
+import { loadPeer } from '../internal/peer.js';
+import { EVENTS_EXCHANGE } from '../internal/rabbitmq-definitions.js';
+import { quoteIdentifier } from '../internal/sql-identifier.js';
+import { EnvelopeSchema } from '../messaging/envelope.js';
+import { TEST_TIMEOUT_SCALE } from './timeout-scale.js';
+import { workerScope } from './worker-scope.js';
+import { INBOX_TABLE } from '../internal/outbox-policy.js';
+let channel;
+let closed;
+let model;
+let urlOverride;
+/** @internal Адрес вместо `adminUrl` воркера (тест пакета: обрыв через tcpProxy); `undefined` — сброс. */
+export function setTestEventsUrl(url) {
+    urlOverride = url;
+    // Другой адрес — другое соединение: прежнее закрывается, следующий вызов откроет новое.
+    channel = undefined;
+    void model?.close().catch(() => undefined);
+    model = undefined;
+}
+/** @internal Закрытие текущего соединения `publishTestEvent` (сигнал теста пакета); нет соединения — `undefined`. */
+export function testEventsClosed() {
+    return closed;
+}
+async function adminUrl() {
+    if (urlOverride !== undefined) {
+        return urlOverride;
+    }
+    const { inject } = await loadPeer('vitest', 'testing');
+    const pool = Number(process.env.VITEST_POOL_ID ?? '1');
+    const worker = inject('kitRabbitmqWorkers')?.[pool - 1];
+    if (worker === undefined) {
+        throw new TypeError('publishTestEvent: startTestStack запущен без rabbitmq: true');
+    }
+    return worker.adminUrl;
+}
+async function openChannel() {
+    const amqp = await loadPeer('amqplib', 'testing');
+    const connection = await amqp.connect(await adminUrl());
+    let created;
+    try {
+        created = await connection.createConfirmChannel();
+    }
+    catch (error) {
+        // Канал не открылся — соединение закрывается: повторные вызовы не копят открытые соединения.
+        await connection.close().catch(() => undefined);
+        throw error;
+    }
+    model = connection;
+    const current = channel;
+    // Обрыв соединения или закрытие канала — следующий вызов открывает новое соединение.
+    const forget = () => {
+        if (channel === current) {
+            channel = undefined;
+        }
+    };
+    closed = new Promise((resolve) => {
+        connection.once('close', () => {
+            forget();
+            resolve();
+        });
+    });
+    connection.on('error', forget);
+    created.on('error', forget);
+    created.once('close', forget);
+    return created;
+}
+/** Confirm-канал администратора vhost воркера, один на воркер; после обрыва пересоздаётся при следующем вызове. */
+function workerChannel() {
+    if (channel === undefined) {
+        const opening = openChannel();
+        channel = opening;
+        // Неудачное подключение не запоминается: следующий вызов пробует снова.
+        opening.catch(() => {
+            if (channel === opening) {
+                channel = undefined;
+            }
+        });
+    }
+    return channel;
+}
+/**
+ * Публикует конверт `01` §7.1 в `verdeect.events` от имени администратора vhost воркера — как relay другого сервиса;
+ * ждёт подтверждения брокера.
+ * @returns опубликованный конверт.
+ * @throws {ZodError} `data` не по схеме события.
+ */
+export async function publishTestEvent(event, data, opts = {}) {
+    const parsed = event.data.parse(data);
+    const tenant = opts.tenant !== undefined
+        ? opts.tenant
+        : event.tenant === 'required'
+            ? workerScope().tenant
+            : null;
+    const occurredAt = opts.occurredAt ?? new Date();
+    const envelope = EnvelopeSchema.parse({
+        id: opts.id ?? newId('evt'),
+        type: event.type,
+        version: event.version,
+        occurredAt: occurredAt.toISOString(),
+        tenant,
+        actor: opts.actor === undefined ? { channel: 'system' } : opts.actor,
+        subject: { kind: event.subject, id: opts.subjectId ?? newId('tst') },
+        data: parsed,
+        traceId: opts.traceId ?? null,
+    });
+    const confirm = await workerChannel();
+    confirm.publish(EVENTS_EXCHANGE, event.type, Buffer.from(JSON.stringify(envelope)), {
+        persistent: true,
+        messageId: envelope.id,
+        type: event.type,
+        contentType: 'application/json',
+        timestamp: Math.floor(occurredAt.getTime() / 1000),
+    });
+    await confirm.waitForConfirms();
+    return envelope;
+}
+/**
+ * Ждёт строку `id` в `<svc>.inbox` (обработка подписчиком с `dedupe: 'inbox'`) с шагом 20 мс до
+ * `timeoutMs × TEST_TIMEOUT_SCALE` — без `sleep` в тесте. Для `dedupe: 'none'` ждать побочный эффект обработчика.
+ * @throws {Error} срок вышел — «waitForInbox: событие <id> не обработано за <timeoutMs> мс».
+ */
+export async function waitForInbox(id, options) {
+    const { inject } = await loadPeer('vitest', 'testing');
+    const schema = inject('kitDatabaseService');
+    const url = inject('kitDatabaseUrl');
+    if (schema === undefined || url === undefined) {
+        throw new TypeError('waitForInbox: startTestStack запущен без postgres');
+    }
+    const pg = (await loadPeer('pg', 'testing')).default;
+    const client = new pg.Client({ connectionString: url });
+    client.on('error', () => undefined);
+    await client.connect();
+    const text = `select 1 from ${quoteIdentifier(schema)}.${quoteIdentifier(INBOX_TABLE)} where id = $1`;
+    const deadline = Date.now() + options.timeoutMs * TEST_TIMEOUT_SCALE;
+    try {
+        for (;;) {
+            if ((await client.query(text, [id])).rowCount !== 0) {
+                return;
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`waitForInbox: событие ${id} не обработано за ${options.timeoutMs} мс (нет строки в ${schema}.${INBOX_TABLE})`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        }
+    }
+    finally {
+        await client.end();
+    }
+}

package/dist/testing/timeout-scale.d.ts

@@ -0,0 +1,4 @@
+/** Множитель testTimeout/hookTimeout из TEST_TIMEOUT_SCALE; пусто — 1. */
+export declare function readTimeoutScale(env: Readonly<Record<string, string | undefined>>): number;
+/** Множитель тайм-аутов тестов текущего процесса (§3.8). */
+export declare const TEST_TIMEOUT_SCALE: number;

package/dist/testing/timeout-scale.js

@@ -0,0 +1,17 @@
+// Множитель тайм-аутов тестов (prd.md §3.8, E1); эталон — verdeect-platform-client test/support/timeout-scale.ts.
+// По умолчанию 1. Задаётся вручную на загруженной машине (load average > числа ядер — 2–3).
+// Сообщение в консоль из O (scripts/timeout-scale.mjs) не перенесено: NFR-8.
+/** Множитель testTimeout/hookTimeout из TEST_TIMEOUT_SCALE; пусто — 1. */
+export function readTimeoutScale(env) {
+    const raw = env.TEST_TIMEOUT_SCALE?.trim() ?? '';
+    if (raw === '') {
+        return 1;
+    }
+    const scale = Number(raw);
+    if (!Number.isFinite(scale) || scale <= 0) {
+        throw new Error(`TEST_TIMEOUT_SCALE=${raw}: нужно число > 0`);
+    }
+    return scale;
+}
+/** Множитель тайм-аутов тестов текущего процесса (§3.8). */
+export const TEST_TIMEOUT_SCALE = readTimeoutScale(process.env);

package/dist/testing/timing-guard.d.ts

@@ -0,0 +1,22 @@
+/** Зависимости runTimingGuard (подменяются в тестах). */
+export interface TimingGuardDeps {
+    /** Load average за минуту. */
+    readonly load: () => number;
+    /** Число ядер. */
+    readonly cores: () => number;
+    /** Имена compose-проектов запущенных контейнеров; null — docker недоступен. */
+    readonly composeProjects: () => Promise<readonly string[] | null>;
+    /** Вывод строки (stderr). */
+    readonly write: (line: string) => void;
+}
+/** Запуск внешней команды: stdout. */
+type Exec = (file: string, args: readonly string[]) => Promise<{
+    stdout: string;
+}>;
+/** Compose-проекты через `docker ps`; любая неудача (нет CLI, демон остановлен, нет прав) → null. */
+export declare function defaultComposeProjects(exec: Exec): Promise<readonly string[] | null>;
+/** Внутренняя логика timingGuard; экспорт для тестов, не из index.ts. */
+export declare function runTimingGuard(deps: TimingGuardDeps): Promise<void>;
+/** globalSetup уровня T: нагрузка, ядра, запрет при запущенном e2e-контуре verdeect-*-e2e (§3.8). */
+export declare function timingGuard(): Promise<void>;
+export {};

package/dist/testing/timing-guard.js

@@ -0,0 +1,54 @@
+// Сторож замеров времени для globalSetup уровня T (prd.md §3.8, E1); эталон — O test/support/timing-guard.ts (029c25c).
+// Единственные строки пакета в stderr в E1: назначение функции — сообщать о среде (process.stderr, не console — NFR-8).
+// Vite теряет текст ошибок globalSetup, поэтому сообщение пишется в stderr до throw.
+import { execFile } from 'node:child_process';
+import { availableParallelism, loadavg } from 'node:os';
+import { promisify } from 'node:util';
+const E2E_PROJECT = /^verdeect-.*-e2e$/;
+/** Compose-проекты через `docker ps`; любая неудача (нет CLI, демон остановлен, нет прав) → null. */
+export async function defaultComposeProjects(exec) {
+    try {
+        const { stdout } = await exec('docker', [
+            'ps',
+            '--format',
+            '{{.Label "com.docker.compose.project"}}',
+        ]);
+        const names = stdout.split('\n').map((line) => line.trim());
+        return [...new Set(names.filter((name) => name !== ''))];
+    }
+    catch {
+        return null;
+    }
+}
+/** Внутренняя логика timingGuard; экспорт для тестов, не из index.ts. */
+export async function runTimingGuard(deps) {
+    const load = deps.load();
+    const cores = deps.cores();
+    deps.write(`[timingGuard] load=${load.toFixed(2)} cores=${cores}\n`);
+    if (load > cores) {
+        deps.write('[timingGuard] WARN: нагрузка выше числа ядер — замеры времени ненадёжны\n');
+    }
+    const projects = await deps.composeProjects();
+    if (projects === null) {
+        deps.write('[timingGuard] docker недоступен — проверка e2e-контура пропущена\n');
+        return;
+    }
+    const running = projects.filter((name) => E2E_PROJECT.test(name));
+    if (running.length > 0) {
+        const message = `[timingGuard] запущен e2e-контур ${running.join(', ')} — остановите его перед замерами времени`;
+        deps.write(`${message}\n`);
+        throw new Error(message);
+    }
+}
+/** globalSetup уровня T: нагрузка, ядра, запрет при запущенном e2e-контуре verdeect-*-e2e (§3.8). */
+export function timingGuard() {
+    const exec = promisify(execFile);
+    return runTimingGuard({
+        load: () => loadavg()[0] ?? 0,
+        cores: () => availableParallelism(),
+        composeProjects: () => defaultComposeProjects((file, args) => exec(file, [...args])),
+        write: (line) => {
+            process.stderr.write(line);
+        },
+    });
+}

package/dist/testing/worker-scope.d.ts

@@ -0,0 +1,31 @@
+import type { KitRabbitWorker } from './rabbitmq-admin.js';
+/** Область воркера Vitest (§3.8). */
+export interface KitWorkerScope {
+    /**
+     * Слаг компании воркера `w<VITEST_POOL_ID>-<8 hex>` — значение `DbContext.tenant` и claim `tenant` токена. Строку
+     * компании, если нужна, создаёт фабрика сервиса; `tenantId` — фабрика сервиса.
+     */
+    readonly tenant: string;
+    /**
+     * vhost воркера с пользователем по правам M3 сервиса из `startTestStack({rabbitmq: true})`: `url` — значение
+     * `RABBITMQ_URL` тестов. Удаляется в teardown прогона (AC-5.18).
+     * @throws {TypeError} стек без `rabbitmq: true` или нет записи для воркера (при обращении).
+     */
+    readonly rabbitmq: {
+        readonly vhost: string;
+        readonly url: string;
+    };
+    /**
+     * Префикс ключей и каналов Redis воркера `<svc>:w<VITEST_POOL_ID>:` — лежит внутри прав ACL сервиса
+     * (`startTestStack({redis: true})`, AC-8.5); подставляется в приложение через `redisWorkerOverride()`.
+     * @throws {TypeError} стек без `redis: true` (при обращении).
+     */
+    readonly redisPrefix: string;
+}
+type ReadWorkers = () => readonly KitRabbitWorker[] | undefined;
+type ReadRedisService = () => string | undefined;
+/** `workerScope` с источниками vhost и имени сервиса Redis (внутренняя: тесты подменяют `inject`). */
+export declare function workerScopeWith(readWorkers: ReadWorkers, readRedisService?: ReadRedisService): KitWorkerScope;
+/** Область текущего воркера: одно значение на воркер, разные воркеры — разные. */
+export declare function workerScope(): KitWorkerScope;
+export {};

package/dist/testing/worker-scope.js

@@ -0,0 +1,68 @@
+// workerScope (prd.md §3.8 v1.14, UC-14): E4 — tenant; E5 — rabbitmq (vhost воркера из startTestStack, AC-5.18);
+// E8 — redisPrefix <svc>:w<N>: (AC-8.5). Записей в таблицы не создаёт (N2, CE-4).
+import { randomBytes } from 'node:crypto';
+import { missingPeerMessage } from '../internal/peer.js';
+// Без vitest /testing импортируется; геттер rabbitmq синхронный и не может ждать loadPeer.
+const vitest = await import('vitest').catch(() => undefined);
+/** Слаг компании: формат claim `tenant` (01 §5.2; TENANT_SLUG O без ведущего `_` служебных компаний). */
+const TENANT_SLUG = /^[a-z0-9][a-z0-9-]{0,48}$/;
+let scope;
+function readProvided() {
+    if (vitest === undefined) {
+        throw new Error(missingPeerMessage('vitest', 'testing'));
+    }
+    return vitest.inject('kitRabbitmqWorkers');
+}
+function readProvidedRedisService() {
+    if (vitest === undefined) {
+        throw new Error(missingPeerMessage('vitest', 'testing'));
+    }
+    return vitest.inject('kitRedisService');
+}
+/** `workerScope` с источниками vhost и имени сервиса Redis (внутренняя: тесты подменяют `inject`). */
+export function workerScopeWith(readWorkers, readRedisService = readProvidedRedisService) {
+    const tenant = `w${process.env.VITEST_POOL_ID ?? '0'}-${randomBytes(4).toString('hex')}`;
+    if (!TENANT_SLUG.test(tenant)) {
+        throw new Error(`workerScope: tenant «${tenant}» вне формата ${TENANT_SLUG.source}`);
+    }
+    let rabbitmq;
+    const result = { tenant };
+    Object.defineProperty(result, 'rabbitmq', {
+        enumerable: true,
+        get: () => {
+            rabbitmq ??= rabbitmqOf(readWorkers());
+            return rabbitmq;
+        },
+    });
+    let redisPrefix;
+    Object.defineProperty(result, 'redisPrefix', {
+        enumerable: true,
+        get: () => {
+            redisPrefix ??= redisPrefixOf(readRedisService());
+            return redisPrefix;
+        },
+    });
+    return result;
+}
+function rabbitmqOf(workers) {
+    if (workers === undefined) {
+        throw new TypeError('workerScope().rabbitmq: startTestStack запущен без rabbitmq: true');
+    }
+    const pool = Number(process.env.VITEST_POOL_ID ?? '1');
+    const worker = workers[pool - 1];
+    if (worker === undefined) {
+        throw new TypeError(`workerScope().rabbitmq: нет vhost для воркера ${pool} (vhost в стеке: ${workers.length})`);
+    }
+    return { vhost: worker.vhost, url: worker.url };
+}
+function redisPrefixOf(service) {
+    if (service === undefined) {
+        throw new TypeError('workerScope().redisPrefix: startTestStack запущен без redis: true');
+    }
+    return `${service}:w${process.env.VITEST_POOL_ID ?? '1'}:`;
+}
+/** Область текущего воркера: одно значение на воркер, разные воркеры — разные. */
+export function workerScope() {
+    scope ??= workerScopeWith(readProvided);
+    return scope;
+}