@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/utils/testNamespace.js

@@ -23,7 +23,23 @@
  * rather than guessing: a test that does not know which namespace it owns must
  * not write anywhere at all.
  *
- * Enforced by deploy-contract requirement R8 (see utils/deployContract.js).
+ * Two namespaces come out of it: getTestNamespace() is the one the test owns and
+ * writes into, getForeignTestNamespace() the one it must not see rows from when
+ * it proves a handler filters on tenant AND workspace. Both are read from the
+ * same env and constrained to the same allowed classes.
+ *
+ * assertAllowedTenant() is the same boundary asked about an id the caller
+ * already holds — an operational script is handed a tenant on the command line
+ * and must know whether it may touch it at all. It exists because the whitelist
+ * had exactly one consumer inside this file, so a script that needed the answer
+ * kept its own guard instead: biz-property refused one declared live id and let
+ * every customer tenant from 101 up through (api/shared/TODO.md, "Od
+ * BIZ-PROPERTY (2026-09-11)"). The list itself is NOT exported — a copy of the
+ * boundary is a second boundary — and the refusal names the allowed classes so
+ * a caller never has to enumerate them.
+ *
+ * Enforced by deploy-contract requirement R8 (see utils/deployContract.js), which
+ * accepts a call to either namespace helper and nothing else.
  */
 
 /**
@@ -50,50 +66,214 @@
  */
 const ALLOWED_TENANT_CLASSES = Object.freeze([
   96, // CI
-  97, // TESTING
   98, // DEVEL
   99 //  VALIDATION
 ]);
 
-function readNamespaceId(key) {
-  const raw = process.env[key];
-  if (raw === undefined || raw === null || String(raw).trim() === '') {
-    throw new Error(`[TestNamespace] Missing environment variable - ${key} is required. `
-      + 'Fix: set it in config/env-active/shared.env (the platform default is the '
-      + 'non-production namespace). An integration test may not pick a namespace itself.');
+/**
+ * Where the platform's own namespace values are set — the `setBy` half of every
+ * message this module raises for itself.
+ *
+ * It is a property of the ENV reader, not of the boundary: a script told to
+ * correct `config/env-active/shared.env` because it was handed `--to-tenant 101`
+ * would be sent to a file that has nothing to do with the value it typed. So the
+ * caller says where its own value comes from, and the boundary says the rest.
+ */
+const ENV_SET_BY = 'locally in config/env-active/shared.env, in CI in the pipeline variables';
+
+/**
+ * Both halves of the caller's origin are required, and each is named when it is
+ * missing: they are printed in the refusal, so a wrong one misdirects an
+ * operator who is being stopped from touching real data.
+ */
+function requireOriginText(value, key) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`[TestNamespace] Missing required argument - assertAllowedTenant(id, { purpose, setBy }) `
+      + `has no "${key}". Fix: pass a non-empty string - "purpose" is the name the caller knows the id by `
+      + '(a CLI flag such as "--to-tenant", an env key such as "TESTING_TENANT_ID"), "setBy" says where that '
+      + 'name is given a value ("on the command line"); both are printed in the refusal so the operator '
+      + 'knows what to change.');
   }
-  const value = Number(String(raw).trim());
+}
+
+/** No value at all: absent, null, or whitespace. One condition, two callers. */
+function isBlank(raw) {
+  return raw === undefined || raw === null || String(raw).trim() === '';
+}
+
+/**
+ * The one rail from a raw value to an integer namespace id. Every id this module
+ * accepts — the env pair and the argument assertAllowedTenant() is handed —
+ * comes through here, so "what is a valid id" is stated once.
+ *
+ * The ABSENCE message is the one thing the env reader keeps for itself: a
+ * missing environment variable and an omitted argument are different failures
+ * with different fixes, and pointing a script operator at an env file it never
+ * touched would misdirect the person being stopped from reaching real data.
+ *
+ * @param {number|string} raw
+ * @param {{purpose: string, setBy: string}} origin
+ * @returns {number}
+ */
+function normalizeNamespaceId(raw, { purpose, setBy }) {
+  if (isBlank(raw)) {
+    throw new Error(`[TestNamespace] Missing namespace id - ${purpose} is required. `
+      + `Fix: set it ${setBy} - see api/docs/standards/tenant-allocation.md § Env variables. `
+      + 'A run that does not know which namespace it owns may not write anywhere at all.');
+  }
+  // A number or a string holding one, and nothing else. `[99]` stringifies to
+  // "99" and would pass the Number() rail below; an id that arrives as an array
+  // or an object is a caller defect, and a guard whose whole job is to refuse
+  // must not guess past one.
+  const value = (typeof raw === 'number' || typeof raw === 'string')
+    ? Number(String(raw).trim())
+    : Number.NaN;
   if (!Number.isInteger(value)) {
-    throw new Error(`[TestNamespace] Invalid ${key}="${raw}" - Expected an integer id. `
-      + 'Fix: correct the value in config/env-active/shared.env.');
+    throw new Error(`[TestNamespace] Invalid ${purpose}="${raw}" - Expected an integer id. `
+      + `Fix: correct the value ${setBy} - see api/docs/standards/tenant-allocation.md § Env variables.`);
+  }
+  return value;
+}
+
+/**
+ * The refusal — one sentence, one place.
+ *
+ * It was written inline in getTestNamespace() while the whitelist had a single
+ * consumer. A second consumer copying it would be the drift that let 97 survive
+ * in the list months after the allocation retired it: the list and the sentence
+ * naming it must move together, so they are rendered from the same function.
+ */
+function refuseTenant(value, { purpose, setBy }) {
+  return new Error(`[TestNamespace] ${purpose}=${value} is not an allowed `
+    + 'environment class - test and validation runs may never write into production data '
+    + '(100 = LIVE, 101+ = CUSTOMER tenants, both refused). Expected one of 96 (CI), '
+    + `98 (DEVEL), 99 (VALIDATION). Fix: set ${purpose} to one of those classes - `
+    + `${setBy} - and seed that namespace from migrations/ - see `
+    + 'api/docs/standards/tenant-allocation.md § The allocation and § Env variables.');
+}
+
+/**
+ * May this tenant id be written into at all?
+ *
+ * The question a script asks about an id it was handed, as opposed to
+ * getTestNamespace(), which asks which namespace the platform env gives a test.
+ * Same whitelist, same refusal; only the name the value carries differs, and the
+ * caller supplies it so the message tells the operator what THEY must change.
+ *
+ * Named for what it enforces (`ALLOWED_TENANT_CLASSES`) the way getTestNamespace
+ * is named for what it returns. `assert`, not `is`: a boolean can be ignored by
+ * the caller that most needs it, and the value coming back normalized means the
+ * check cannot be done and then bypassed with the unchecked original.
+ *
+ * @param {number|string} tenantId the id to check — an integer, or a string
+ *        holding one (what `Number(argv[i])` and a config file respectively hand
+ *        over); no other shape is coerced.
+ * @param {{purpose: string, setBy: string}} options
+ *        `purpose` — the name the caller knows the id by ("--to-tenant");
+ *        `setBy` — where that name is given a value ("on the command line").
+ * @returns {number} the normalized id, safe to use as the namespace.
+ * @throws {Error} when the id is absent, not an integer, or not an allowed
+ *         environment class.
+ */
+function assertAllowedTenant(tenantId, options) {
+  if (options === null || typeof options !== 'object') {
+    requireOriginText(undefined, 'purpose');
+  }
+  const { purpose, setBy } = options;
+  requireOriginText(purpose, 'purpose');
+  requireOriginText(setBy, 'setBy');
+
+  const value = normalizeNamespaceId(tenantId, { purpose, setBy });
+  if (!ALLOWED_TENANT_CLASSES.includes(value)) {
+    throw refuseTenant(value, { purpose, setBy });
   }
   return value;
 }
 
+/**
+ * The same rail for a WORKSPACE id that did not come from the environment.
+ *
+ * A Tier-1 cookbook declares the workspace its steps run in
+ * (`defaults.workspace_id`, and the per-step override —
+ * `.claude/rules/workspace-architecture.md`), so that value reaches ctx without
+ * passing `readNamespaceId()`. It goes through this function instead, for one
+ * reason: a declared value that is not an id must be REFUSED, naming the key
+ * that carries it, and must never slide back to the environment value. A
+ * fallback there would hide exactly the misconfiguration the boundary exists to
+ * surface (architecture-principles.md §3).
+ *
+ * There is deliberately NO class allowlist here, and that is not an omission:
+ *
+ *   - `api/docs/standards/tenant-allocation.md` allocates environment classes to
+ *     TENANTS ("Tenants are environment classes; that is the whole scheme"), and
+ *     its § Adding a class says a new purpose gets a **workspace inside** the
+ *     class — so a workspace id is a purpose, with no allocated range to check;
+ *   - the platform's own default is `TESTING_WORKSPACE_ID=200`, which is not a
+ *     member of `ALLOWED_TENANT_CLASSES` — applying the tenant list to a
+ *     workspace would refuse the value the standard itself prescribes;
+ *   - the boundary the guard has to hold is reachability of production data, and
+ *     that is held by the tenant, which a cookbook cannot influence at all
+ *     (`getTestNamespace()` remains the only source of `tenant_id` at Tier-1).
+ *     Every workspace inside an allowed class is inside the test namespace.
+ *
+ * @param {number|string} workspaceId the declared id — an integer, or a string
+ *        holding one; no other shape is coerced.
+ * @param {{purpose: string, setBy: string}} options as for assertAllowedTenant:
+ *        `purpose` is the name the caller knows the id by (here, the cookbook key
+ *        that carries it), `setBy` where that name is given a value.
+ * @returns {number} the normalized id.
+ * @throws {Error} when the id is absent or not an integer.
+ */
+function assertWorkspaceId(workspaceId, options) {
+  if (options === null || typeof options !== 'object') {
+    requireOriginText(undefined, 'purpose');
+  }
+  const { purpose, setBy } = options;
+  requireOriginText(purpose, 'purpose');
+  requireOriginText(setBy, 'setBy');
+
+  return normalizeNamespaceId(workspaceId, { purpose, setBy });
+}
+
+/**
+ * The env half of the boundary. The absence message says what an absent
+ * environment variable means and where that variable belongs; the rest of the
+ * rail — the integer check and, for the tenant, the whitelist — is the shared
+ * one. Six suites in this package assert this sentence verbatim, because it is
+ * what a service prints when its namespace is not configured at all.
+ */
+function readNamespaceId(key) {
+  const raw = process.env[key];
+  if (isBlank(raw)) {
+    throw new Error(`[TestNamespace] Missing environment variable - ${key} is required. `
+      + 'Fix: set it locally in config/env-active/shared.env (the platform default is the '
+      + 'non-production namespace); in CI it comes from the pipeline variables, not from '
+      + 'a file in the repository - see api/docs/standards/tenant-allocation.md § Env variables. '
+      + 'An integration test may not pick a namespace itself.');
+  }
+  return normalizeNamespaceId(raw, { purpose: key, setBy: ENV_SET_BY });
+}
+
 /**
  * @returns {{tenant_id: number, workspace_id: number}} ctx-shaped, so it can be
  *          spread straight into a handler call.
  */
 function getTestNamespace() {
-  const tenantId = readNamespaceId('TESTING_TENANT_ID');
-
   // The runtime half of the protection, and the reason the tenant is decided
   // before anything else is read. R8 rejects a per-service override before it
   // ships; this refuses the accident that ships anyway, so a startup probe can
-  // never reach real data even if the configuration is wrong.
+  // never reach real data even if the configuration is wrong. The check itself
+  // is assertAllowedTenant() — the env is one caller of the boundary, not its
+  // owner.
   //
   // The workspace id is deliberately NOT class-checked: tenant-allocation.md
   // allocates environment classes to TENANTS, and calls a workspace "the purpose
   // within the class" without naming any range for it. A restriction here would
   // be one this library invented.
-  if (!ALLOWED_TENANT_CLASSES.includes(tenantId)) {
-    throw new Error(`[TestNamespace] TESTING_TENANT_ID=${tenantId} is not an allowed `
-      + 'environment class - test and validation runs may never write into production data '
-      + '(100 = LIVE, 101+ = CUSTOMER tenants, both refused). Expected one of 96 (CI), '
-      + '97 (TESTING), 98 (DEVEL), 99 (VALIDATION). Fix: set TESTING_TENANT_ID to one of '
-      + 'those classes in config/env-active/shared.env and seed that namespace from '
-      + 'migrations/ - see api/docs/standards/tenant-allocation.md.');
-  }
+  const tenantId = assertAllowedTenant(readNamespaceId('TESTING_TENANT_ID'), {
+    purpose: 'TESTING_TENANT_ID',
+    setBy: ENV_SET_BY
+  });
 
   return {
     tenant_id: tenantId,
@@ -101,4 +281,48 @@ function getTestNamespace() {
   };
 }
 
-module.exports = { getTestNamespace };
+/**
+ * A namespace an integration test may write into that is NOT its own.
+ *
+ * The isolation half of the same boundary: a handler filters on tenant_id AND
+ * workspace_id, so proving it filters at all takes a second namespace whose rows
+ * must stay invisible. Two ways of getting one are banned, and both were in use:
+ *
+ *   a literal — biz-hello asserted against tenant 101, a live CUSTOMER tenant
+ *   (Meditest), so the isolation test wrote into real data;
+ *
+ *   arithmetic — `TESTING_TENANT_ID + 1` reads as harmless until the platform
+ *   default 99 makes it 100, the LIVE tenant, which is the accident this module
+ *   exists to prevent.
+ *
+ * So the foreign tenant is another member of ALLOWED_TENANT_CLASSES, picked by
+ * POSITION in that list and wrapping at its end. Every value it can return is
+ * therefore a class the standard allocated to a non-production environment, and
+ * adding or retiring a class moves this helper with it — one list, one owner.
+ *
+ * The workspace is the caller's own: tenant-allocation.md allocates environment
+ * classes to TENANTS and names no range for a workspace, so a second workspace
+ * would be a value this library invented. The pair already differs, because the
+ * tenant does.
+ *
+ * Deterministic: same environment, same answer, so a fixture seeded for the
+ * foreign namespace in one run is the one the next run queries.
+ *
+ * @returns {{tenant_id: number, workspace_id: number}} ctx-shaped, like
+ *          getTestNamespace(), and never equal to it.
+ */
+function getForeignTestNamespace() {
+  // Reuses getTestNamespace() rather than reading the env a second time: the
+  // whitelist refusal, the missing-variable message and the integer check are
+  // one rail, and a foreign namespace is never chosen for an own value that is
+  // itself refused.
+  const own = getTestNamespace();
+  const next = (ALLOWED_TENANT_CLASSES.indexOf(own.tenant_id) + 1) % ALLOWED_TENANT_CLASSES.length;
+
+  return {
+    tenant_id: ALLOWED_TENANT_CLASSES[next],
+    workspace_id: own.workspace_id
+  };
+}
+
+module.exports = { getTestNamespace, getForeignTestNamespace, assertAllowedTenant, assertWorkspaceId };

package/src/utils/throwawaySchema.js

@@ -0,0 +1,207 @@
+'use strict';
+
+/**
+ * The one throwaway schema an integration test builds.
+ *
+ * WHY IT LIVES IN THIS PACKAGE. Every DB-owning biz service has integration
+ * suites that need a schema of their own — built from the service's migrations,
+ * written into, and dropped at the end. Each repository solved that for itself:
+ * biz-meta has `tests/helpers/schemaFixture.js` (three suites use it), and the
+ * shape before that was one baseline-only copy per test file. A second
+ * implementation of one concern is a defect by default
+ * (`change-discipline.md` § One rail per concern), and the concern here is not
+ * service-specific at all: the service declares WHAT its database is in
+ * `config/service/integration-contract.json`, and HOW a schema gets built from
+ * that declaration is uniform (`docs/biz/00-model/uniformity-principle.md`).
+ *
+ * WHAT IT SHARES WITH THE CI BUILD. Everything except one decision. The
+ * migration set and its order (`resolveMigrationPlan`, `migrationOrder.js`), the
+ * collation requirement (`requireCollation`), the `CREATE DATABASE … COLLATE`
+ * statement (`createDatabaseSql`) and the client invocation (`defaultExec`) all
+ * come from `setupDatabase.js`. The one difference is deliberate and is the
+ * whole point of the two names:
+ *
+ *   `buildSchema`            builds the service's REAL schema in CI, so it
+ *                            refuses a target it did not create — non-empty, or
+ *                            carrying another collation.
+ *   `createThrowawaySchema`  builds a schema the test owns, so it DROPS and
+ *                            recreates it, and refuses only one name: the one
+ *                            the service declares.
+ *
+ * WHAT IT IS TO DEPLOY-CONTRACT R8. R8 asks an integration test where its
+ * namespace comes from, because an integration test writes into a real
+ * database. A test that builds its own throwaway targets no shared namespace,
+ * and until now it earned its permit by containing the string `CREATE DATABASE`
+ * plus a `DB_NAME` redirect — a text heuristic that says nothing about where the
+ * statements actually land. Using this helper says it by construction: the
+ * schema is created here, every statement is executed against it by name, a
+ * `USE` line inside a migration cannot redirect them (§ below), and the declared
+ * schema is refused outright. So R8 reads the import instead of the string.
+ *
+ * THE SCHEMA IS CHOSEN BY THE CALLER, NEVER BY THE FILE. A migration written
+ * for the install runner commonly opens with `USE \`oagen_<service>\`;` — the
+ * production schema by name. Applied verbatim against a throwaway, that one line
+ * sends the whole file into the live schema instead. Those lines are therefore
+ * stripped, and a schema select that survives the strip stops the build rather
+ * than being applied.
+ *
+ * @see src/utils/setupDatabase.js — the CI build, and the shared decisions
+ * @see src/utils/deployContract.js — R8, which permits a file that imports this
+ * @see api/docs/standards/tenant-allocation.md § Enforcement
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  resolveMigrationPlan,
+  requireCollation,
+  createDatabaseSql,
+  defaultExec
+} = require('./setupDatabase');
+
+/** `USE \`x\`;` at the start of a line — the install runner's schema select. */
+const LEADING_SCHEMA_SELECT = /^\s*USE\s+/i;
+/** A schema select that survived the strip: at the start of a line, or after a `;`. */
+const SURVIVING_SCHEMA_SELECT = /(?:^|;)\s*USE\s+/i;
+/** An SQL comment line — prose cannot select a schema. */
+const SQL_COMMENT = /^\s*(?:--|#|\/\*|\*)/;
+
+function require_(value, name, fix) {
+  if (value === undefined || value === null || value === '') {
+    throw new Error(`[ThrowawaySchema] Missing ${name} - Expected a value. Fix: ${fix}`);
+  }
+  return value;
+}
+
+/**
+ * The SQL of one migration, with the install runner's schema select removed.
+ *
+ * @param {string} file absolute path to the .sql file
+ * @returns {string}
+ */
+function sqlWithoutSchemaSelect(file) {
+  const stripped = fs.readFileSync(file, 'utf8')
+    .split('\n')
+    .map((line) => (LEADING_SCHEMA_SELECT.test(line) ? '' : line))
+    .join('\n');
+
+  const selects = stripped.split('\n')
+    .some((line) => !SQL_COMMENT.test(line) && SURVIVING_SCHEMA_SELECT.test(line));
+
+  if (selects) {
+    throw new Error(`[ThrowawaySchema] ${path.basename(file)} still selects a schema after the leading `
+      + 'USE lines were stripped - refusing to apply it.\n'
+      + '       A throwaway schema is chosen by the test; a USE inside the file would send its statements '
+      + 'somewhere else, and that somewhere is the live schema in every migration written for the install '
+      + 'runner.\n'
+      + '       Fix: put the schema select on a line of its own, or remove it — the runner selects the '
+      + 'schema for the file.');
+  }
+
+  return stripped;
+}
+
+/**
+ * Build a throwaway schema from the service's declared migrations.
+ *
+ * @param {object} options
+ * @param {string} options.serviceRoot repository root of the service
+ * @param {object} options.database the `database` block of the integration contract
+ * @param {string} options.schema the throwaway name; never `database.schema`
+ * @param {object} options.connection `{host, port, user, password}`
+ * @param {Function} [options.exec] the SQL executor; defaults to the mysql/mariadb CLI,
+ *   the same one the CI build uses. May be async — a service whose test image carries
+ *   no client injects an executor over its own driver connection.
+ * @param {string|null} [options.before] apply only the migrations that precede this
+ *   file name, which is the state that migration is applied to
+ * @param {boolean} [options.seeds] also apply the declared seeds, after the migrations
+ * @returns {Promise<{schema: string, migrationsApplied: number, seedsApplied: number,
+ *   migrations: string[], readMigration: Function, applyMigration: Function, dispose: Function}>}
+ */
+async function createThrowawaySchema({
+  serviceRoot, database, schema, connection, exec = defaultExec, before = null, seeds = false
+}) {
+  require_(serviceRoot, 'serviceRoot', 'pass the repository root of the service under test.');
+  require_(database, 'database', 'pass the "database" block of config/service/integration-contract.json.');
+  require_(schema, 'schema', 'pass the throwaway schema name this suite owns.');
+  require_(connection?.host, 'connection.host', 'pass DB_HOST.');
+  require_(connection?.user, 'connection.user', 'pass DB_USER.');
+
+  if (schema === database.schema) {
+    throw new Error(`[ThrowawaySchema] Refusing to build ${schema} - that is the schema the service `
+      + 'declares, and this build DROPS the schema it is given.\n'
+      + '       Fix: pass a name of this suite\'s own, derived from the declared one '
+      + `(e.g. "${database.schema}_<suite>test").`);
+  }
+
+  const conn = { ...connection, port: connection.port ?? 3306 };
+  const collation = requireCollation(database);
+  const plan = resolveMigrationPlan(serviceRoot, database);
+
+  const fileOf = (name) => {
+    const found = plan.migrations.find((file) => path.basename(file) === name);
+    if (found === undefined) {
+      throw new Error(`[ThrowawaySchema] No migration named "${name}" in ${plan.dir}.\n`
+        + '       Fix: name a file the declaration carries; the directory contents are the set, and '
+        + 'nothing here keeps a list of them.');
+    }
+    return found;
+  };
+
+  let toApply = plan.migrations;
+  if (before !== null) {
+    const stop = plan.migrations.indexOf(fileOf(before));
+    if (stop === 0) {
+      throw new Error(`[ThrowawaySchema] Nothing is applied before "${before}" - refusing to call an empty `
+        + 'schema built.\n'
+        + '       Fix: name a migration that has predecessors in the declared set.');
+    }
+    toApply = plan.migrations.slice(0, stop);
+  }
+
+  const run = async (sql) => {
+    const result = await exec({ connection: conn, sql });
+    if (result.status !== 0) {
+      throw new Error(`[ThrowawaySchema] ${sql} failed:\n${result.stderr}\n`
+        + `       Fix: the account must be allowed to create and drop ${schema} on `
+        + `${conn.host}:${conn.port}; point DB_HOST at the throwaway database, never at a live server.`);
+    }
+  };
+
+  const apply = async (file, kind) => {
+    const result = await exec({
+      connection: conn, schema, file, sql: sqlWithoutSchemaSelect(file)
+    });
+    if (result.status !== 0) {
+      throw new Error(`[ThrowawaySchema] ${kind} ${path.basename(file)} failed:\n${result.stderr}\n`
+        + '       Fix: the set must apply to an empty schema in file order. Either the SQL is wrong, or '
+        + 'the file is numbered before something it depends on.');
+    }
+  };
+
+  const dropSql = `DROP DATABASE IF EXISTS \`${schema}\`;`;
+
+  // Dropped first, not "if absent": a suite that died mid-run left its schema
+  // behind, and a build onto those leftovers would prove the migration set
+  // against a shape it never produced.
+  await run(dropSql);
+  await run(createDatabaseSql(schema, collation));
+
+  for (const file of toApply) await apply(file, 'Migration');
+
+  const seedFiles = seeds === true ? plan.seeds : [];
+  for (const file of seedFiles) await apply(file, 'Seed');
+
+  return {
+    schema,
+    migrationsApplied: toApply.length,
+    seedsApplied: seedFiles.length,
+    migrations: [...plan.migrations],
+    readMigration: (name) => sqlWithoutSchemaSelect(fileOf(name)),
+    applyMigration: async (name) => apply(fileOf(name), 'Migration'),
+    dispose: async () => run(dropSql)
+  };
+}
+
+module.exports = { createThrowawaySchema, sqlWithoutSchemaSelect };

package/src/validators/ServiceStructureValidator.js

@@ -17,6 +17,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { HANDLER_REF_PATTERN } = require('../utils/handlerRef');
 
 /**
  * Read a configuration file from the ONE place a service may keep it:
@@ -704,7 +705,7 @@ class ServiceStructureValidator {
       }
     }
 
-    if (spec.handler && !/^handlers\/[a-zA-Z0-9_\/-]+#[a-zA-Z_][a-zA-Z0-9_]*$/.test(spec.handler)) {
+    if (spec.handler && !HANDLER_REF_PATTERN.test(spec.handler)) {
       this.errors.push({
         type: 'INVALID_HANDLER_REF',
         path: 'config/service/operations.json',

package/templates/business-service/.dockerignore

@@ -0,0 +1,42 @@
+# --- oa-dockerignore v1
+# Derived from templates/business-service/gitignore, the declaration .gitignore reads too —
+# what a LOCAL production build must not copy into the image (being ignored by git
+# excludes nothing from COPY . .). Everything above this block is this repository's own.
+node_modules
+**/node_modules
+config/runtime
+config/env-active
+conn-runtime
+**/conn-runtime
+ci
+**/ci
+logs
+**/logs
+*.log
+**/*.log
+npm-debug.log*
+**/npm-debug.log*
+coverage
+**/coverage
+.env
+**/.env
+.env.local
+**/.env.local
+.vscode
+**/.vscode
+.idea
+**/.idea
+*.swp
+**/*.swp
+*.swo
+**/*.swo
+*~
+**/*~
+.DS_Store
+**/.DS_Store
+Thumbs.db
+**/Thumbs.db
+.oa_drive_deps_hash
+**/.oa_drive_deps_hash
+.git
+# --- end oa-dockerignore v1