@onlineapps/conn-orch-validator 12.2.0 → 13.0.0

package/src/cli/oa-sync-template.js

@@ -8,20 +8,36 @@
  *
  * Four runs, one template:
  *
- *   * bare paths - the uniform sync of confirmation 001 §3.2. It writes the
- *     files of the manifest classes `identical` and `generated` from the very
- *     `from:` reference those rows already point the conformance CHECK at, and
- *     never touches a file of the `own` class. A row that names no `from:`
- *     reference is not a row of this run — it is a requirement about the
- *     repository, and `npx oa-validate` is what answers it (d.507).
+ *   * bare paths - the uniform sync of confirmation 001 §3.2, and since d.710
+ *     the WHOLE of it: over a service root with no path named it writes every
+ *     row the manifest declares in a syncable class - `identical`, `generated`,
+ *     `contains` - from the very `from:` reference those rows already point the
+ *     conformance CHECK at, and never touches a file of the `own` class. That
+ *     is one run for "bring this service into line with everything oa-validate
+ *     measures as generated", `config/env-templates/shared.env` included. A row
+ *     that names no `from:` reference is not a row of this run — it is a
+ *     requirement about the repository, and `npx oa-validate` is what answers
+ *     it (d.507).
  *   * `--new <name>` - the whole service tree, from the template that ships
  *     inside this package (001 §2). It is what `api/scripts/add-service.sh
  *     --scaffold` runs; that script keeps the platform facts (the registry
  *     entry, the port), because those are not the shape of a service.
  *   * `shared-env` - `config/env-templates/shared.env` from
  *     `api/config/shared-env.json`, the one owner of the shared key set (003 §18).
+ *     It stays, because its bearer is not always a service: `api/` itself and
+ *     the business-service template carry that file too, and neither is a
+ *     service root the bare run could be pointed at. Both of those paths are
+ *     READ OFF the manifest row (`sharedEnvRow()` below) rather than written
+ *     here, so this command and the row cannot disagree about one file.
  *   * `readme-uniform` - the generated uniform pointer of a README, for a
- *     library or for a biz service; the kind is read from the target (005).
+ *     library or for a biz service; the kind is read from the target (005). It
+ *     stays for the LIBRARY, which wears no service uniform; for a service the
+ *     bare run covers the same region through row `G-README`.
+ *
+ * `template` and `docs-region` are deliberately NOT part of the bare run: their
+ * bearer is not a service. One renders `api/templates/business-service`, the
+ * other a region of the `api/docs/**` tree — two directories a service
+ * repository does not have and does not own.
  *
  * There is no flag that points the run at another manifest: the shape has one
  * owner beside the SSOT (004), and a `--manifest` flag would be a second one
@@ -57,8 +73,8 @@ const {
   declaredCategory,
   KINDS
 } = require('../sync/readmePointer');
+const { README_FILE } = require('../sync/readmeFile');
 const {
-  README_FILE,
   PACKAGE_ROOT,
   SERVICE_MANIFEST_IN_PACKAGE,
   LIBRARY_MANIFEST_IN_PACKAGE,
@@ -67,27 +83,30 @@ const {
   libraryRegion
 } = require('../sync/readmeLocation');
 const docsRegion = require('../sync/docsRegion');
-const { resolveWorkspaceRoot, canonicalRoot, WORKSPACE_MARKER } = require('../manifest/workspaceRoot');
+const {
+  resolveWorkspaceRoot, resolveWorkspacePath, canonicalRoot, WORKSPACE_MARKER
+} = require('../manifest/workspaceRoot');
 const { loadManifest: loadLibraryManifest, LIBRARY_MANIFEST_PATH } = require('../manifest/loadManifest');
-const { discoverBearers } = require('../manifest/discovery');
+const { discoverBearers, resolveFromDocument } = require('../manifest/discovery');
 
 /** Exit code for a run that could not start at all — distinct from a finding. */
 const USAGE_EXIT = 2;
 
 /**
- * The manifest lives beside the SSOT the workspace marker names, so "where is
- * the workspace" is asked once and answered in one place (004: platform-level
- * facts live in `api/config/*.json` beside the SSOT).
+ * The row that owns `shared.env`, found by the CHECK that decides it.
+ *
+ * By the check and not by the id, because that is already this package's
+ * vocabulary for "which rule renders this row" (`../sync/uniformFiles.js` §
+ * `RENDERERS` is keyed the same way). A list of ids in a runner is the thing
+ * that module refuses to keep: a row is renderable because its rule says how,
+ * never because a caller recognised its name.
  */
-const MANIFEST_RELATIVE = path.join(path.dirname(WORKSPACE_MARKER), 'shared-env.json');
-
-/** Where a bearer keeps the file this subcommand generates. */
-const SHARED_ENV_RELATIVE = path.join('config', 'env-templates', 'shared.env');
-
-/** The same file as a tree key, which is always '/'-separated. */
-const SHARED_ENV_POSIX = 'config/env-templates/shared.env';
+const SHARED_ENV_CHECK = 'shared-env-generated';
 
-/** The platform SSOT of library versions, relative to the workspace root. */
+/**
+ * The platform SSOT of library versions, in the same convention as the manifest
+ * above and resolved the same way.
+ */
 const LIBRARIES_RELATIVE = path.join(path.dirname(WORKSPACE_MARKER), 'libraries.json');
 
 /** The scope prefix whose versions the SSOT owns. */
@@ -108,21 +127,31 @@ Usage:
   is: generated output, committed for reading (001 §5). --check is the gate.
 
   With bare paths (or none, meaning all of them) the run rewrites the files the
-  manifest declares in the classes "identical" and "generated" that name a
-  "from" reference, from that same reference the conformance check reads. Files
-  of the "own" class - src/**, tests/**, the content of docs/** - are never
-  written. A row naming no reference is a requirement about the repository
+  manifest declares in the classes "identical", "generated" and "contains" that
+  name a "from" reference, from that same reference the conformance check reads.
+  Files of the "own" class - src/**, tests/**, the content of docs/** - are
+  never written. A row naming no reference is a requirement about the repository
   rather than a file, and npx oa-validate <serviceRoot> is what answers it.
 
+  WHAT ONE BARE RUN COVERS: every generated row of the SERVICE uniform, which
+  since d.710 includes config/env-templates/shared.env and the README region -
+  so "sync everything that is generated" is npx oa-sync-template --target .,
+  one command, not a sequence each repository assembles for itself. WHAT IT
+  DOES NOT: template and docs-region, whose bearer is not a service -
+  api/templates/business-service and the api/docs/** tree have their own owners.
+
   --new <name>        create a service tree from the packaged template
   --into <dir>        where that tree is written; it must not exist yet
   --description <s>   what the service is for; without it the template's
                       __SERVICE_DESCRIPTION__ is LEFT standing and the files
                       carrying it are listed
 
-  Writes <dir>/config/env-templates/shared.env from the platform env manifest
-  api/config/shared-env.json — the one owner of the shared key set. A service
-  adds keys of its own in service.env, never here.
+  shared-env writes <dir>/config/env-templates/shared.env from the platform env
+  manifest api/config/shared-env.json — the one owner of the shared key set. A
+  service adds keys of its own in service.env, never here. For a SERVICE the
+  bare run writes the same file from the same manifest (row G-SHARED-ENV); this
+  subcommand is how the other two bearers get it — api/ itself and the
+  business-service template, neither of which is a service root.
 
   --target <dir>      the bearer: a service root, api/ itself, or the business
                       service template
@@ -131,7 +160,7 @@ Usage:
   --check             write nothing; exit 1 with a diff when the file on disk is
                       not what the manifest renders
 
-  readme-uniform writes the generated region of a repository's README.md from
+  readme-uniform writes the generated region of a repository's ${README_FILE} from
   the manifest that ships with this package. --target reads the kind from the
   disk: a root carrying config/service/operations.json is a SERVICE and gets
   "Uniform: [biz-service](<link>)", the sections of the biz-service manifest and
@@ -257,18 +286,30 @@ function parseArgs(argv) {
   return options;
 }
 
-function loadManifest(workspaceRoot) {
-  const manifestPath = path.join(workspaceRoot, MANIFEST_RELATIVE);
-  if (!fs.existsSync(manifestPath)) {
-    throw new Error(`[oa-sync-template] Missing platform env manifest - ${manifestPath} does not exist. `
-      + 'Fix: the shared key set is declared there and nowhere else.');
-  }
-
-  try {
-    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-  } catch (error) {
-    throw new Error(`[oa-sync-template] Invalid platform env manifest - ${manifestPath}: ${error.message}`);
+/**
+ * The manifest row that owns `shared.env`: where a bearer keeps the file
+ * (`row.path`) and which file owns its content (`row.from`).
+ *
+ * BOTH facts come from the row, and that is the whole point of this function.
+ * Until d.710c this command carried its own pair — a `MANIFEST_RELATIVE` built
+ * from the workspace marker and a `SHARED_ENV_RELATIVE` literal — beside the
+ * row that says the same two things to `oa-validate` and, since d.710, to the
+ * bare run. One file, two declarations of where it lives: the day the row's
+ * `from.path` moves, the subcommand keeps reading the old place and the two
+ * halves of one uniform disagree in silence
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * @returns {object} the row
+ */
+function sharedEnvRow() {
+  const manifest = loadUniformManifest(DEFAULT_MANIFEST_PATH);
+  const row = uniformRows(manifest).find((candidate) => candidate.check === SHARED_ENV_CHECK);
+  if (row === undefined) {
+    throw new Error(`[oa-sync-template] No manifest row is decided by "${SHARED_ENV_CHECK}" - this run writes `
+      + 'the file that row declares, and knows no path of its own. '
+      + `Fix: restore the row in ${DEFAULT_MANIFEST_PATH}.`);
   }
+  return row;
 }
 
 /**
@@ -287,8 +328,9 @@ function runSharedEnv(options) {
       + 'Fix: pass --workspace <root> pointing at the directory that holds api/ and api_biz/.');
   }
 
-  const manifest = loadManifest(workspaceRoot);
-  const file = path.join(target, SHARED_ENV_RELATIVE);
+  const row = sharedEnvRow();
+  const manifest = resolveFromDocument({ from: row.from, workspaceRoot });
+  const file = path.join(target, ...row.path.split('/'));
 
   if (options.check) {
     if (!fs.existsSync(file)) {
@@ -765,7 +807,14 @@ function runSync(options) {
   let blocked = 0;
 
   for (const entry of entries) {
-    const where = `${entry.id} ${entry.path}`;
+    // WHAT THE LINE IS ABOUT, not merely which file it touched. A block row
+    // compares and writes the markers alone, so a line naming the path only
+    // reads as a claim about a file whose other half was never looked at —
+    // `.claude/rules/automation-gates.md` §5. `planRow` decides the scope, by
+    // the manifest row's own `block`; this loop only prints it.
+    const where = entry.block === undefined
+      ? `${entry.id} ${entry.path}`
+      : `${entry.id} ${entry.path} (block "${entry.block}")`;
     if (entry.outcome === 'not-run') {
       process.stdout.write(`[oa-sync-template] NOT RUN ${where} - ${entry.reason}\n`);
     } else if (entry.outcome === 'blocked') {
@@ -797,7 +846,7 @@ function runSync(options) {
  * @returns {object} the parsed `libraries` map
  */
 function loadLibraries(workspaceRoot) {
-  const file = path.join(workspaceRoot, LIBRARIES_RELATIVE);
+  const file = resolveWorkspacePath(workspaceRoot, LIBRARIES_RELATIVE);
   if (!fs.existsSync(file)) {
     throw new Error(`[oa-sync-template] Missing library SSOT - ${file} does not exist. `
       + 'Fix: a new service pins every @onlineapps dependency to the platform SSOT, which is that file.');
@@ -899,7 +948,8 @@ function runNew(options) {
   }
 
   const workspaceRoot = requireWorkspaceRoot({ explicit: options.workspace, startDir: path.dirname(into) });
-  const envManifest = loadManifest(workspaceRoot);
+  const sharedEnv = sharedEnvRow();
+  const envManifest = resolveFromDocument({ from: sharedEnv.from, workspaceRoot });
   const libraries = loadLibraries(workspaceRoot);
 
   const tree = renderTree({ params });
@@ -908,7 +958,7 @@ function runNew(options) {
   tree.delete(ENV_TEMPLATE_SOURCE);
   tree.set(envTemplateTarget(params.service_name), envTemplate);
 
-  tree.set(SHARED_ENV_POSIX, renderSharedEnv(envManifest));
+  tree.set(sharedEnv.path, renderSharedEnv(envManifest));
   tree.set('package.json', pinLibraries(tree.get('package.json'), libraries));
 
   for (const [relative, text] of tree) writeServiceFile(into, relative, text);
@@ -1032,4 +1082,4 @@ if (require.main === module) {
   process.exitCode = main(process.argv.slice(2));
 }
 
-module.exports = { main, parseArgs, USAGE_EXIT, MANIFEST_RELATIVE, SHARED_ENV_RELATIVE, README_FILE };
+module.exports = { main, parseArgs, USAGE_EXIT };

package/src/cli/oa-validate.js

@@ -30,9 +30,9 @@ const fs = require('fs');
 const path = require('path');
 
 const { loadManifest, DEFAULT_MANIFEST_PATH, LIBRARY_MANIFEST_PATH } = require('../manifest/loadManifest');
-const { runManifest } = require('../manifest/runManifest');
+const { runManifest, isTargetVersion } = require('../manifest/runManifest');
 const {
-  resolveWorkspaceRoot, canonicalRoot, API_MARKER, PACKAGE_ROOT
+  resolveWorkspaceRoot, requirePackageInApiCheckout, canonicalRoot, API_MARKER, PACKAGE_ROOT
 } = require('../manifest/workspaceRoot');
 const {
   renderReport, renderJson, exitCodeFor, blockingOf, verdictOf, describeClearOutcome
@@ -83,7 +83,7 @@ const USAGE = `
 Usage:
   oa-validate [serviceRoot] [--workspace <root>] [--json]
   oa-validate --workspace <root> [--json]
-  oa-validate --library <packageDir> [--workspace <root>] [--json]
+  oa-validate --library <packageDir> [--workspace <root>] [--as-version <X.Y.Z>] [--json]
   oa-validate --library --all [--workspace <root>] [--json]
   oa-validate --env-reads [<serviceRoot>]
 
@@ -121,6 +121,11 @@ Options:
                            No such checkout (an installed copy, a service container)
                            → the rows that need it are reported NOT RUN, never as
                            passing.
+  --as-version <X.Y.Z>     With --library <packageDir>: judge the package AS the version
+                           being published, not the one package.json still carries —
+                           what a publish dry run asks before the wave bumps the file.
+                           The rows that judge a version (L-CHANGELOG) read it; the
+                           finding names it and the package.json version beside it.
   --json                   Print the run as JSON instead of the table.
   --env-reads              Print the environment names this service reads — one per
                            line, sorted, nothing else — and exit 0. No table, no
@@ -148,7 +153,8 @@ Exit codes:
 
 function parseArgs(argv) {
   const parsed = {
-    serviceRoot: null, workspace: null, json: false, help: false, library: false, all: false, envReads: false
+    serviceRoot: null, workspace: null, json: false, help: false, library: false, all: false, envReads: false,
+    asVersion: null
   };
   const args = [...argv];
 
@@ -171,6 +177,17 @@ function parseArgs(argv) {
           + 'api/ and api_biz/. Fix: oa-validate [serviceRoot] --workspace <root>');
       }
       parsed.workspace = value;
+    } else if (token === '--as-version') {
+      const value = args.shift();
+      if (!value || value.startsWith('--')) {
+        throw new Error('[oa-validate] Option --as-version has no value - it names the version being '
+          + 'published. Fix: oa-validate --library <packageDir> --as-version <X.Y.Z>');
+      }
+      if (!isTargetVersion(value)) {
+        throw new Error(`[oa-validate] Option --as-version is not a version - ${JSON.stringify(value)} is not `
+          + 'X.Y.Z or X.Y.Z-<prerelease>. Fix: pass the bare version, e.g. --as-version 1.2.4');
+      }
+      parsed.asVersion = value;
     } else if (token.startsWith('--')) {
       throw new Error(`[oa-validate] Unknown option - ${token}. Fix: run oa-validate --help for the options.`);
     } else if (parsed.serviceRoot === null) {
@@ -192,7 +209,8 @@ function parseArgs(argv) {
       parsed.json ? '--json' : null,
       parsed.library ? '--library' : null,
       parsed.all ? '--all' : null,
-      parsed.workspace !== null ? '--workspace' : null
+      parsed.workspace !== null ? '--workspace' : null,
+      parsed.asVersion !== null ? '--as-version' : null
     ].filter((token) => token !== null);
 
     if (combined.length > 0) {
@@ -202,6 +220,17 @@ function parseArgs(argv) {
     }
   }
 
+  // A version belongs to ONE package, and only the library uniform judges one: an
+  // option no row of the run reads would declare nothing (`automation-gates.md` §1).
+  if (parsed.asVersion !== null && !parsed.library && !parsed.envReads) {
+    throw new Error('[oa-validate] --as-version needs --library - only the library uniform judges the version '
+      + 'being published. Fix: oa-validate --library <packageDir> --as-version <X.Y.Z>');
+  }
+  if (parsed.asVersion !== null && parsed.all) {
+    throw new Error('[oa-validate] --as-version judges ONE package - --all measures every package, and each has '
+      + 'its own version. Fix: oa-validate --library <packageDir> --as-version <X.Y.Z>');
+  }
+
   if (parsed.all && !parsed.library) {
     throw new Error('[oa-validate] Option --all needs --library - a service is checked one repository at a time. '
       + 'Fix: oa-validate --library --all');
@@ -247,11 +276,12 @@ function packageRelativeRowIds(manifest) {
  * against this package alone, and a `workspace` row's answer is filtered down to
  * what lies under this package's root. Nothing is filtered here.
  *
- * @param {{ manifest: object, packageRoot: string, workspaceRoot: string|null }} params
+ * @param {{ manifest: object, packageRoot: string, workspaceRoot: string|null,
+ *           asVersion: string|null }} params — `asVersion` is `--as-version`, null for an audit
  * @returns {{ findings: Array<object>, notRun: Array<object> }}
  */
-function checkOnePackage({ manifest, packageRoot, workspaceRoot }) {
-  const result = runManifest({ manifest, serviceRoot: packageRoot, workspaceRoot });
+function checkOnePackage({ manifest, packageRoot, workspaceRoot, asVersion }) {
+  const result = runManifest({ manifest, serviceRoot: packageRoot, workspaceRoot, asVersion });
   const category = declaredCategory(readPackage(packageRoot).json) || NO_CATEGORY;
 
   return {
@@ -299,7 +329,7 @@ function checkEveryPackage({ manifest, workspaceRoot }) {
   };
 
   for (const bearer of bearers) {
-    const one = checkOnePackage({ manifest, packageRoot: bearer.dir, workspaceRoot });
+    const one = checkOnePackage({ manifest, packageRoot: bearer.dir, workspaceRoot, asVersion: null });
     for (const finding of one.findings) {
       const where = packageRelative.has(finding.id)
         ? `${bearer.relativeDir}/${finding.where}`
@@ -424,7 +454,11 @@ function runLibrary(options) {
   const packageRoot = canonicalRoot(given);
 
   const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace });
-  const run = checkOnePackage({ manifest, packageRoot, workspaceRoot });
+  // A package outside the checkout this run speaks for is judged against the
+  // wrong tree; with no workspace there is no such checkout, and the run says
+  // NOT RESOLVED instead (d.940, `workspaceRoot.js` § requirePackageInApiCheckout).
+  if (workspaceRoot !== null) requirePackageInApiCheckout(workspaceRoot, packageRoot);
+  const run = checkOnePackage({ manifest, packageRoot, workspaceRoot, asVersion: options.asVersion });
   const report = {
     uniform: manifest.uniform,
     blockingSeverities: manifest.blocking_severities,

package/src/helpers/README.md

@@ -52,7 +52,7 @@ createServiceReadinessTests(__dirname, {
 
 `logger` defaults to `console` on purpose — in a bootstrap suite stdout is the
 report the developer reads. See
-[FALLBACKS_INVENTORY.md](/docs/standards/FALLBACKS_INVENTORY.md) §5.6.
+`api/docs/standards/FALLBACKS_INVENTORY.md` §5.6.
 
 **Score Breakdown** (owned by `ServiceReadinessValidator`):
 - operations: 80 points (required)
@@ -104,7 +104,7 @@ If validation fails, clear error messages are shown:
    ✗ Service configuration missing: config/service/config.json
      Type: MISSING_CONFIG
      File: config/service/config.json
-     Fix: Create config.json with service metadata. See: /docs/biz/60-templates/service-template.md
+     Fix: Create config.json with service metadata. See: api/docs/biz/60-templates/service-template.md
 
 ⚠️  WARNINGS (1):
 
@@ -193,7 +193,7 @@ module.exports = { createMyTests };
 
 ## Related Documentation
 
-- [/docs/standards/TESTING.md](/docs/standards/TESTING.md) - Testing standards
-- [/tests/TESTING.md](/tests/TESTING.md) - SPOT principles
-- [/shared/connector/conn-orch-validator/README.md](/shared/connector/conn-orch-validator/README.md) - Package documentation
-- [/shared/connector/conn-orch-validator/docs/DESIGN.md](/shared/connector/conn-orch-validator/docs/DESIGN.md) - Design principles
+- `api/docs/standards/TESTING.md` - Testing standards
+- `api/tests/TESTING.md` - SPOT principles
+- [the package README](../../README.md) - Package documentation
+- [DESIGN.md](../../docs/DESIGN.md) - Design principles

package/src/helpers/createServiceReadinessTests.js

@@ -19,9 +19,9 @@
  *   createServiceReadinessTests(__dirname);  // Pass tests/bootstrap directory
  *
  * Related:
- * - /docs/biz/80-decisions/0005-no-http-in-biz-containers.md
- * - /docs/biz/00-model/service-shape.md (zero-HTTP canonical shape)
- * - /shared/connector/conn-orch-validator/README.md - Package documentation
+ * - api/docs/biz/80-decisions/0005-no-http-in-biz-containers.md
+ * - api/docs/biz/00-model/service-shape.md (zero-HTTP canonical shape)
+ * - api/shared/connector/conn-orch-validator/README.md - Package documentation
  */
 
 'use strict';
@@ -32,7 +32,9 @@ const ServiceReadinessValidator = require('../ServiceReadinessValidator');
 const MockRegistry = require('../mocks/MockRegistry');
 const { ServiceStructureValidator } = require('../validators/ServiceStructureValidator');
 const { MIN_COOKBOOK_FORMAT_VERSION } = require('../utils/cookbookFormat');
-const { HANDLER_REF_PATTERN, parseHandlerRef, resolveHandlerModule } = require('../utils/handlerRef');
+const { parseHandlerRef, resolveHandlerModule } = require('../utils/handlerRef');
+const { operationsRuleSentences } = require('../utils/operationsRules');
+const { operationsDocumentFindings } = require('../utils/operationsDocumentRules');
 
 /**
  * Resolve every handler an `operations.json` declares, the way the runtime does.
@@ -75,13 +77,61 @@ function resolveDeclaredHandlers(serviceRoot, operationsFlat) {
   return resolved;
 }
 
+/**
+ * The cookbook the readiness check validates: one `task` step per operation.
+ *
+ * It must be a cookbook `@onlineapps/cookbook-core` `validateCookbook` accepts,
+ * because that is what `CookbookTestUtils.validateCookbook` runs first (d.984);
+ * otherwise this helper rejects its own output. The format's `step_id` pattern
+ * is `^[a-zA-Z0-9_]+$` (api/docs/biz/40-cookbooks/format.md § Step definition),
+ * and operation names carry dashes, so every other character becomes `_`.
+ * Two operations that land on one `step_id` are refused by name — a step id
+ * addresses one step, and silently keeping either would test half the catalogue.
+ *
+ * @param {string} serviceName - the service the steps dispatch to
+ * @param {Object} operationsFlat - the flat `{ name: spec }` map of operations.json
+ * @returns {{version: string, steps: Object[]}} the synthesised cookbook
+ * @throws {Error} when two operation names map to the same step_id
+ */
+function buildReadinessCookbook(serviceName, operationsFlat) {
+  const operationByStepId = new Map();
+  const steps = Object.entries(operationsFlat).map(([name, op]) => {
+    const stepId = `test_${name.replace(/[^a-zA-Z0-9_]/g, '_')}`;
+    if (operationByStepId.has(stepId)) {
+      throw new Error(
+        `[createServiceReadinessTests] Operations "${operationByStepId.get(stepId)}" and "${name}" map to `
+        + `the same step_id "${stepId}" - Expected: names that differ after replacing non-[a-zA-Z0-9_] `
+        + 'with "_". Fix: rename one operation in operations.json.'
+      );
+    }
+    operationByStepId.set(stepId, name);
+    return {
+      step_id: stepId,
+      type: 'task',
+      service: serviceName,
+      operation: name,
+      input: generateMockInput(op.input),
+      output: {}
+    };
+  });
+
+  return {
+    // Cookbook FORMAT version (api/docs/biz/40-cookbooks/format.md § Required fields).
+    version: MIN_COOKBOOK_FORMAT_VERSION,
+    steps
+  };
+}
+
 /**
  * Create service readiness integration test suite
  *
  * @param {string} testsDir - Path to tests/bootstrap directory (use __dirname)
  * @param {Object} [options] - Optional configuration
  * @param {boolean} [options.includeOptionalChecks=true] - Include cookbook & registry checks
- * @param {number} [options.timeout=15000] - Test timeout in ms
+ * @param {number} [options.timeout=15000] - The budget, in milliseconds, that
+ *   EVERY test this helper registers runs under. A positive whole number;
+ *   anything else is refused when the option is read. Omit it to take 15000 —
+ *   the helper's own default, never jest's.
  * @param {Object} [options.logger=console] - Logger handed to
  *   ServiceReadinessValidator (info/warn/error/debug). Defaults to `console`,
  *   which is the report channel of a jest bootstrap suite — see the comment at
@@ -102,6 +152,20 @@ function createServiceReadinessTests(testsDir, options = {}) {
     timeout = 15000
   } = options;
 
+  // Read where it is declared, refused where it is read (§4 Fail-Fast). A
+  // budget that is not a positive whole number of milliseconds cannot be one:
+  // jest reads `0` as "no budget at all", which is the opposite of what a
+  // caller asking for a budget means, and a string or a fraction would reach
+  // three `test()` calls and decide nothing there.
+  if (!Number.isInteger(timeout) || timeout <= 0) {
+    throw new Error(
+      '[createServiceReadinessTests] options.timeout is not a positive whole number of '
+      + `milliseconds - received ${String(timeout)}. Expected: the budget every test this helper `
+      + 'registers runs under, e.g. 15000. Fix: pass a positive integer as options.timeout, or '
+      + 'omit it to take the default 15000.'
+    );
+  }
+
   // Validate service structure FIRST
   console.log('\n🔍 Validating service structure...\n');
   const structureValidator = new ServiceStructureValidator(serviceRoot);
@@ -132,7 +196,7 @@ function createServiceReadinessTests(testsDir, options = {}) {
   // The version comes from package.json, never from config.json — the same
   // single source of truth the runtime uses:
   //
-  //   shared/connector/service-wrapper/src/ConfigLoader.js:239
+  //   shared/connector/service-wrapper/src/ConfigLoader.js, `loadServiceConfig()`:
   //     config.service.version = this.loadPackageVersion(basePath);
   //
   // That assignment is unconditional and happens BEFORE `${VAR}` placeholders
@@ -154,20 +218,7 @@ function createServiceReadinessTests(testsDir, options = {}) {
 
       if (includeOptionalChecks) {
         mockRegistry = new MockRegistry();
-        testCookbook = {
-          // Cookbook FORMAT version — the synthesised cookbook must satisfy the
-          // same rule the Tier-1 gate enforces (api/docs/biz/40-cookbooks/format.md
-          // § Required fields), otherwise this helper rejects its own output.
-          version: MIN_COOKBOOK_FORMAT_VERSION,
-          steps: Object.entries(operationsFlat).map(([name, op]) => ({
-            step_id: `test-${name}`,
-            type: 'task',
-            service: serviceName,
-            operation: name,
-            input: generateMockInput(op.input),
-            output: {}
-          }))
-        };
+        testCookbook = buildReadinessCookbook(serviceName, operationsFlat);
       }
 
       // `console` is the intended logger here, not a stand-in for one that is
@@ -228,19 +279,22 @@ function createServiceReadinessTests(testsDir, options = {}) {
 
       const operationsFlat = operations.operations || operations;
       expect(typeof operationsFlat).toBe('object');
-      expect(Object.keys(operationsFlat).length).toBeGreaterThan(0);
 
-      const validScopes = ['platform', 'tenant', 'workspace'];
+      // `schema_version`, and a dispatch table with nothing in it: the two
+      // document rules, asked of the one definition that owns them. The
+      // `toBeGreaterThan(0)` that used to stand here was the fifth answer to
+      // the second of them (d.465b).
+      expect(operationsDocumentFindings(operations)).toEqual([]);
 
-      for (const [, operationSpec] of Object.entries(operationsFlat)) {
-        expect(operationSpec).toHaveProperty('handler');
-        expect(operationSpec).toHaveProperty('bundle_scope');
-        expect(operationSpec.handler).toMatch(HANDLER_REF_PATTERN);
-        expect(validScopes).toContain(operationSpec.bundle_scope);
-        expect(operationSpec).not.toHaveProperty('endpoint');
-        expect(operationSpec).not.toHaveProperty('method');
-      }
-    });
+      // The rules are the Registry's, asked of the one definition that owns
+      // them. Restating them here was the fourth copy, and — like the other
+      // three — it did not know `mutates`, `resource_type` or the kebab-case
+      // key rule, so this suite went green on declarations the Registry
+      // refuses on registration.
+      const verdict = operationsRuleSentences(operationsFlat);
+      expect(verdict.sentences).toEqual([]);
+      expect(verdict.valid).toBe(true);
+    }, timeout);
 
     test('every declared handler resolves to an exported function', () => {
       // The shape of the ref says nothing about whether the module is in the
@@ -254,7 +308,7 @@ function createServiceReadinessTests(testsDir, options = {}) {
       for (const entry of resolved) {
         expect(typeof entry.handler).toBe('function');
       }
-    });
+    }, timeout);
   });
 }
 
@@ -287,4 +341,4 @@ function generateMockInput(inputSchema) {
   return mockData;
 }
 
-module.exports = { createServiceReadinessTests, resolveDeclaredHandlers };
+module.exports = { createServiceReadinessTests, resolveDeclaredHandlers, buildReadinessCookbook };

package/src/index.js

@@ -7,9 +7,9 @@
  * Production entry point: {@link ValidationOrchestrator} (7-step pre-validation
  * driven by operations.json — OpenAPI path iteration is NOT supported).
  *
- * @see /api/docs/biz/30-operations/registration-wire.md §3 (operations.json)
- * @see /api/docs/biz/40-cookbooks/test-runner-flow.md (validation probes)
- * @see /api/docs/architecture/validator.md (validator architecture)
+ * @see api/docs/biz/30-operations/registration-wire.md §3 (operations.json)
+ * @see api/docs/biz/40-cookbooks/test-runner-flow.md (validation probes)
+ * @see api/docs/architecture/validator.md (validator architecture)
  */
 
 const CookbookTestUtils = require('./CookbookTestUtils');
@@ -79,7 +79,6 @@ module.exports = {
   // the rule it implements today (containment, require, export is a function),
   // while the stricter declared form stays in `parseHandlerRef`, so adopting it
   // narrows nothing the wrapper accepts.
-  get HANDLER_REF_PATTERN() { return require('./utils/handlerRef').HANDLER_REF_PATTERN; },
   get parseHandlerRef() { return require('./utils/handlerRef').parseHandlerRef; },
   get resolveHandlerModule() { return require('./utils/handlerRef').resolveHandlerModule; },
 
@@ -96,5 +95,15 @@ module.exports = {
 
   get createServiceReadinessTests() { return createServiceReadinessTests; },
   get BizCiGateContract() { return BizCiGateContract; },
-  get IntegrationRun() { return require('./utils/integrationRun'); }
+  get IntegrationRun() { return require('./utils/integrationRun'); },
+
+  // The deploy contract (R1-R5, R7-R8) over one biz repository. It is exported
+  // for the same reason `resolveMigrationPlan` above is: the one consumer
+  // outside this package — `api/scripts/verify-biz-deploy-contract.sh` — reached
+  // it as `…/src/utils/deployContract.js`, and a path inside the package is not
+  // a contract. With the `exports` map (d.812) that path stops resolving at all,
+  // so the capability moves here, where it is named and kept.
+  get verifyDeployContract() { return require('./utils/deployContract').verifyDeployContract; },
+  get DEPLOY_CONTRACT_REQUIREMENTS() { return require('./utils/deployContract').DEPLOY_CONTRACT_REQUIREMENTS; },
+  get DEPLOY_CONTRACT_SCOPE() { return require('./utils/deployContract').DEPLOY_CONTRACT_SCOPE; }
 };