@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/manifest/checks/serviceIdentityRows.js

@@ -0,0 +1,351 @@
+'use strict';
+
+/**
+ * ONE service, ONE name.
+ *
+ * `api/docs/biz/60-templates/naming.md` is normative and derives every spelling
+ * of a biz service from a single short name: `service.name` is `biz-<shortname>`,
+ * the npm package is `biz-<shortname>`, the container is
+ * `api_service_<shortname>`, the env template is `<shortname>.env`, the database
+ * is `oagen_<shortname>`, the directory is `<shortname>` and the git repository
+ * ends in `biz-<shortname>`. The document says why the last of those matters in
+ * a way no other node does: `service_code` in the entitlement data and the
+ * service name in a cookbook step are compared by the gateway CHARACTER BY
+ * CHARACTER, so a second spelling of one service is not untidiness — it is a
+ * request that is refused.
+ *
+ * Measured 2026-09-10 over the eight live services: seven wear one name each,
+ * and `hello-service` wears four — directory `hello-service`, repository
+ * `biz-hello-service`, env template `hello-service.env`, everything else
+ * `hello`. Nothing said a word about it, and the standard's own § Current State
+ * recorded the divergence as a fact rather than as a defect.
+ *
+ * Two rows, because they answer to two different owners:
+ *
+ *   - **`C-IDENTITY`** compares the spellings INSIDE the repository against the
+ *     short name that repository declares. It needs nothing but its own root, so
+ *     it answers in a container and in the service's own CI too.
+ *   - **`U-IDENTITY`** compares the SSOT's row for this service — `directory`,
+ *     `repo`, `container` in `api/config/services.json` — against the same short
+ *     name. Those three are facts of the workspace, so the row is only ever
+ *     asked where the workspace is.
+ *
+ * The short name is read the one way this package reads it, from
+ * `config/service/config.json` → `service.name` (`serviceIdentity.js`); the
+ * directory name is never the source, because inside the image every service
+ * lies in `/app`.
+ *
+ * @see api/docs/biz/60-templates/naming.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { whereOf } = require('./libraryContext');
+const { readComposeServices } = require('./composeShape');
+const { readIdentity, IDENTITY_FILE } = require('../serviceIdentity');
+const { PLACEHOLDERS } = require('../../sync/serviceTemplate');
+const { resolveFromMap } = require('../discovery');
+
+/** Where a service declares the name npm knows it by. */
+const PACKAGE_FILE = 'package.json';
+
+/**
+ * Where a service declares its own name to the platform gates and its database,
+ * if it has one. `C-CONTRACT` owns the FILE — whether each declaration is there
+ * and well-formed; this row owns only whether the two names it carries are this
+ * service's.
+ */
+const CONTRACT_FILE = 'config/service/integration-contract.json';
+
+/** The directory every per-service env template lies in. */
+const ENV_TEMPLATE_DIR = 'config/env-templates';
+
+/** The env template every service shares; it is named after the platform, not the service. */
+const SHARED_ENV = 'shared.env';
+
+/** The prefix `naming.md` gives every biz database. */
+const DATABASE_PREFIX = 'oagen_';
+
+/** The profile marking the one-shot test runner, which declares no container name. */
+const TEST_PROFILE = 'test';
+
+/**
+ * Read a file of the repository under check.
+ *
+ * @param {string} serviceRoot repository root
+ * @param {string} relative repository-relative path, `/`-separated
+ * @returns {string|null} null when it is not there
+ */
+function readOrNull(serviceRoot, relative) {
+  const target = path.join(serviceRoot, ...relative.split('/'));
+  return fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
+}
+
+/**
+ * A JSON file of the repository, or null when it is absent or unreadable. A
+ * broken file is somebody else's row (`C-SERVICE`, `C-CONTRACT`), and this row
+ * saying so a second time would be a second owner of one defect.
+ *
+ * @param {string} serviceRoot repository root
+ * @param {string} relative repository-relative path
+ * @returns {object|null}
+ */
+function readJson(serviceRoot, relative) {
+  const text = readOrNull(serviceRoot, relative);
+  if (text === null) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The env templates a repository carries, the shared one excluded — it is named
+ * after the platform and every service has the same copy (`G-SHARED-ENV`).
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {string[]|null} file names, or null when the directory is absent
+ */
+function envTemplates(serviceRoot) {
+  const dir = path.join(serviceRoot, ...ENV_TEMPLATE_DIR.split('/'));
+  if (!fs.existsSync(dir)) return null;
+  return fs.readdirSync(dir).filter((name) => name !== SHARED_ENV).sort();
+}
+
+/**
+ * Every `env_file` entry of every service block of a compose file, as written.
+ *
+ * @param {string} text the compose file
+ * @returns {string[]}
+ */
+function envFileEntries(text) {
+  return [...readComposeServices(text).values()]
+    .flatMap((node) => node.sequences.get('env_file') || [])
+    .map((entry) => entry.trim());
+}
+
+/**
+ * The container names a compose file declares, the one-shot runner excluded: it
+ * declares none on purpose, and `F-RUNNER` owns that block.
+ *
+ * @param {string} text the compose file
+ * @returns {Array<[string, string]>} `[compose service, container_name]`
+ */
+function containerNames(text) {
+  return [...readComposeServices(text).entries()]
+    .filter(([, node]) => !(node.sequences.get('profiles') || []).includes(TEST_PROFILE))
+    .map(([name, node]) => [name, node.scalars.get('container_name')])
+    .filter(([, container]) => typeof container === 'string' && container !== '');
+}
+
+const serviceIdentity = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['path', 'production_path']),
+
+  // Nothing outside this repository is read, so the row answers wherever the
+  // repository is — in the container and in the service's own CI included.
+  needsWorkspace: () => false,
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const identity = readIdentity(serviceRoot);
+    const at = (relative) => whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative });
+
+    if (identity.problem !== undefined) {
+      if (identity.undecided === null) return [];
+      return [{ where: at(IDENTITY_FILE), what: `the spellings could not be compared — ${identity.undecided}` }];
+    }
+
+    const { service_name: shortName, container_name: container } = identity.params;
+    const findings = [];
+
+    // The npm name is compared against what `config/service/config.json`
+    // DECLARES, character for character — naming.md gives the two the same
+    // spelling, so one name is the whole question. Comparing it against the
+    // derived `biz-<shortname>` instead would smuggle in a rule about
+    // `service.name` itself that no row owns (`serviceIdentity.js` § REGISTERED_NAME
+    // says so in as many words); that is a change to the rules, not a side
+    // effect of this one (`truth-over-agreement.md` §6).
+    const declaredName = (readJson(serviceRoot, IDENTITY_FILE) || {}).service.name;
+    const pkg = readJson(serviceRoot, PACKAGE_FILE);
+    if (pkg !== null && pkg.name !== declaredName) {
+      findings.push({
+        where: at(PACKAGE_FILE),
+        what: `npm name is ${JSON.stringify(pkg.name)}, `
+          + `and ${IDENTITY_FILE} declares ${JSON.stringify(declaredName)}`
+      });
+    }
+
+    // The SIXTH spelling, and the one this row missed until d.218: the
+    // integration contract opens with `serviceName`, and it is the first file
+    // every platform gate reads. Compared against what `config/service/config.json`
+    // DECLARES, character for character, for the same reason the npm name is:
+    // whether `service.name` itself has to read `biz-<name>` is a question no row
+    // owns, and this one is not the place a rule appears as a side effect
+    // (`truth-over-agreement.md` §6). A contract that declares nothing here, or
+    // none at all, is `C-CONTRACT`'s finding — it calls the validator owning
+    // every rule of that file, and one defect has one owner
+    // (`change-discipline.md` § One rail per concern).
+    const contractName = (readJson(serviceRoot, CONTRACT_FILE) || {}).serviceName;
+    if (typeof contractName === 'string' && contractName !== declaredName) {
+      findings.push({
+        where: at(CONTRACT_FILE),
+        what: `serviceName is ${JSON.stringify(contractName)}, `
+          + `and ${IDENTITY_FILE} declares ${JSON.stringify(declaredName)}`
+      });
+    }
+
+    for (const relative of [row.path, row.production_path]) {
+      const text = readOrNull(serviceRoot, relative);
+      if (text === null) continue;
+
+      for (const [composeService, declared] of containerNames(text)) {
+        if (declared === container) continue;
+        findings.push({
+          where: at(relative),
+          what: `service ${composeService} is called ${JSON.stringify(declared)}, `
+            + `and the name derived from ${IDENTITY_FILE} is ${JSON.stringify(container)}`
+        });
+      }
+    }
+
+    const expectedEnv = `${shortName}.env`;
+    const templates = envTemplates(serviceRoot);
+    if (templates !== null && !templates.includes(expectedEnv)) {
+      findings.push({
+        where: at(ENV_TEMPLATE_DIR),
+        what: templates.length === 0
+          ? `carries no env template of its own — ${expectedEnv} is the one this service is named after`
+          : `carries ${templates.join(', ')}, and this service's env template is ${expectedEnv}`
+      });
+    }
+
+    for (const relative of [row.path, row.production_path]) {
+      const text = readOrNull(serviceRoot, relative);
+      if (text === null) continue;
+
+      for (const entry of envFileEntries(text)) {
+        const name = entry.split('/').pop();
+        if (name === SHARED_ENV || name === expectedEnv) continue;
+        findings.push({
+          where: at(relative),
+          what: `env_file loads ${JSON.stringify(entry)}, and this service's env template is ${expectedEnv}`
+        });
+      }
+    }
+
+    // Only where the repository DECLARES a database. A stateless service
+    // declares none, and demanding one would be this row inventing a rule
+    // `naming.md` does not state (`pdfgen` is the measured case).
+    const contract = readJson(serviceRoot, CONTRACT_FILE);
+    const schema = contract === null || contract.database === undefined || contract.database === null
+      ? null
+      : contract.database.schema;
+    if (typeof schema === 'string' && schema !== `${DATABASE_PREFIX}${shortName}`) {
+      findings.push({
+        where: at(CONTRACT_FILE),
+        what: `database.schema is ${JSON.stringify(schema)}, and the name derived from ${IDENTITY_FILE} `
+          + `is ${JSON.stringify(`${DATABASE_PREFIX}${shortName}`)}`
+      });
+    }
+
+    return findings;
+  }
+});
+
+/**
+ * The three fields of the SSOT row that spell this service's name, and what each
+ * has to read. `container` is the same derivation `C-IDENTITY` holds the compose
+ * files to, which is the point: the SSOT and the repository are two places
+ * saying one thing.
+ */
+const SSOT_FIELDS = Object.freeze([
+  { field: 'directory', of: (params) => params.service_name, says: 'the directory this service lies in' },
+  { field: 'repo', of: (params) => params.repo_name, says: 'the last segment of the git repository path', last: true },
+  { field: 'container', of: (params) => params.container_name, says: 'the container this service runs as' }
+]);
+
+const ssotIdentity = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze([]),
+
+  describeNotRun({ block }) {
+    return `the workspace root is not reachable, so ${block.from.path} cannot be read`;
+  },
+
+  run({ block, serviceRoot, workspaceRoot }) {
+    const identity = readIdentity(serviceRoot);
+    const at = (relative) => whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative });
+
+    if (identity.problem !== undefined) {
+      if (identity.undecided === null) return [];
+      return [{ where: at(IDENTITY_FILE), what: `the SSOT row could not be found — ${identity.undecided}` }];
+    }
+
+    const registered = identity.params.registry_name;
+
+    // The TEMPLATE is a bearer of every FILE row and of none of the SSOT ones:
+    // it declares its identity as the placeholder (`serviceIdentity.js`), and
+    // `api/config/services.json` lists services, of which the template is not
+    // one — it is the shape they are made from. The question this row asks does
+    // not apply to it, the same way `appliesTo` decides a library duty by
+    // category. Not a silence about a service: a service always declares a name
+    // of its own, and the case below reports one the SSOT does not know.
+    if (registered === PLACEHOLDERS.registry_name) return [];
+
+    const entries = resolveFromMap({ from: block.from, workspaceRoot });
+    const rows = Array.isArray(entries) ? entries : [];
+    const declared = rows.filter((entry) => entry.name === registered);
+
+    if (declared.length === 0) {
+      // A bearer the SSOT knows under NO name and under NO directory is
+      // `U-ORPHAN`'s finding, and saying it twice would give one defect two
+      // owners (`change-discipline.md` § One rail per concern). What reaches
+      // here is the other case: the SSOT declares this directory, and calls the
+      // service living in it something else.
+      const directory = path.basename(path.resolve(serviceRoot));
+      if (!rows.some((entry) => entry[block.from.key] === directory)) return [];
+
+      return [{
+        where: block.from.path,
+        what: `declares directory ${JSON.stringify(directory)} under another name, and no `
+          + `${JSON.stringify(block.from.list)} entry is named ${JSON.stringify(registered)} — `
+          + `which is what ${IDENTITY_FILE} calls this service`
+      }];
+    }
+
+    const findings = [];
+    for (const entry of declared) {
+      for (const { field, of, says, last } of SSOT_FIELDS) {
+        const value = entry[field];
+        if (typeof value !== 'string' || value === '') {
+          findings.push({
+            where: block.from.path,
+            what: `${JSON.stringify(registered)} declares no ${JSON.stringify(field)} — it names ${says}`
+          });
+          continue;
+        }
+        const compared = last === true ? value.split('/').pop() : value;
+        const expected = of(identity.params);
+        if (compared === expected) continue;
+        findings.push({
+          where: block.from.path,
+          what: `${JSON.stringify(registered)} declares ${field} ${JSON.stringify(value)}, and the name `
+            + `derived from ${IDENTITY_FILE} is ${JSON.stringify(expected)} — it names ${says}`
+        });
+      }
+    }
+    return findings;
+  }
+});
+
+module.exports = {
+  checks: [
+    { name: 'service-identity', check: serviceIdentity },
+    { name: 'ssot-identity', check: ssotIdentity }
+  ],
+  DATABASE_PREFIX,
+  envFileEntries,
+  containerNames
+};

package/src/manifest/checks/serviceRuntime.js

@@ -0,0 +1,295 @@
+'use strict';
+
+/**
+ * What a service is allowed to BE at run time: which Node major it runs, how
+ * much memory it may hold, which process it runs AS, and the ports it may not
+ * publish.
+ *
+ * Every row here is a measured gap the existing gates leave open, not a second
+ * copy of them (004 point 4):
+ *
+ *   - `R3` of the deploy contract compares CI, Dockerfile and `engines.node`
+ *     against EACH OTHER. Five of the eight services are internally consistent
+ *     on an older major while the platform has moved, so R3 is green and the
+ *     drift is invisible. `R-NODE` compares them against the platform major, and
+ *     is the one row this uniform fills by itself.
+ *   - `R4` refuses published ports in the PRODUCTION compose. `R-PORTS-DEV` is
+ *     the dev compose, which R4 never reads.
+ *   - the memory norm has no gate at all today: `biz-memory-limits.md` 001 is
+ *     prose, and two services sit at 384M in dev and in production.
+ *   - `biz-compose-pid1` 001 was prose too, and 002 says where it belongs: in
+ *     the uniform. `R-PID1` is the row, and until it existed the decision
+ *     travelled by being remembered.
+ *
+ * The Node major is REFERENCED, never restated. Until d.238 the reference was
+ * `api/.nvmrc`, the file that owns it — and that made the row unanswerable in
+ * the two places a service is actually built: inside its container and in its
+ * own CI checkout, neither of which has a workspace. It now reads the
+ * `engines.node` of THIS package, which the library uniform's `L-ENGINES` fails
+ * any package for disagreeing with `api/.nvmrc`. So it is the same fact, one
+ * checked hop further along, and it travels with the pin (confirmation
+ * `biz-service-manifest` 006 point 2).
+ *
+ * The two memory values are carried by the row, because no machine-readable
+ * owner for them exists yet and a row's `doc` naming the owner's decision is the
+ * honest second best.
+ *
+ * @see api/docs/governance/confirmations/biz-memory-limits.md
+ * @see api/docs/governance/confirmations/biz-compose-pid1.md
+ * @see api/docs/governance/confirmations/biz-service-manifest.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { resolveFromValue, isPackageReference, referenceOwner } = require('../discovery');
+const { whereOf } = require('./libraryContext');
+const { readComposeServices, scalarAt, declares, declarationOf } = require('./composeShape');
+
+/** Where a service block states its own budget, in both compose files. */
+const SERVICE_MEMORY_PATH = 'deploy.resources.limits.memory';
+
+/** The profile that marks the test runner — its budget is F-RUNNER's row, not R-MEM's. */
+const TEST_PROFILE = 'test';
+
+const readOrNull = (serviceRoot, relative) => {
+  const target = path.join(serviceRoot, ...relative.split('/'));
+  return fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
+};
+
+/** The major of a Node version however it is written: `24`, `24-alpine`, `>=24.0.0 <25`. */
+function majorOf(text) {
+  const match = /(\d+)/.exec(String(text));
+  return match === null ? null : Number(match[1]);
+}
+
+/** The services of a compose file that are not the one-shot test runner. */
+const runtimeServices = (text) => [...readComposeServices(text).entries()]
+  .filter(([, node]) => !(node.sequences.get('profiles') || []).includes(TEST_PROFILE));
+
+/**
+ * The range the referenced `package.json` declares in `engines.node`.
+ *
+ * The reference names the FILE; which field carries the major is this check's
+ * business, and it is the same field the check compares every service against —
+ * one concept, asked twice (`change-discipline.md` § One rail per concern).
+ *
+ * @param {{ row: object, workspaceRoot: string|null }} params
+ * @returns {string} the range as the file writes it
+ */
+function platformRange({ row, workspaceRoot }) {
+  const raw = resolveFromValue({ from: row.from, workspaceRoot });
+  const owner = referenceOwner(row.from);
+
+  let document;
+  try {
+    document = JSON.parse(raw);
+  } catch (cause) {
+    throw new Error(`[ManifestRuntime] Platform Node major unreadable - ${owner} is not valid JSON. `
+      + 'Fix: repair the file; its engines.node is the major every service is measured against.', { cause });
+  }
+
+  const declared = (document.engines || {}).node;
+  if (typeof declared !== 'string' || declared.length === 0) {
+    throw new Error(`[ManifestRuntime] Platform Node major unreadable - ${owner} declares no engines.node. `
+      + 'Fix: declare it; the library uniform\'s L-ENGINES keeps it equal to api/.nvmrc, and this row reads it.');
+  }
+  return declared;
+}
+
+const nodeMajor = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['from']),
+
+  // A reference into this package travels with the pin, so the row answers in a
+  // container and in the service's own CI too (d.229 § describeFromProblem).
+  needsWorkspace: ({ row }) => !isPackageReference(row.from),
+
+  describeNotRun({ row }) {
+    return `the workspace root is not reachable, so ${referenceOwner(row.from)} cannot be read`;
+  },
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const range = platformRange({ row, workspaceRoot });
+    const platform = majorOf(range);
+    if (platform === null) {
+      throw new Error('[ManifestRuntime] Platform Node major unreadable - '
+        + `${referenceOwner(row.from)} declares engines.node as ${JSON.stringify(range)}, which carries no number. `
+        + 'Fix: repair the file; it is what every service is measured against.');
+    }
+
+    const findings = [];
+    const dockerfile = readOrNull(serviceRoot, 'Dockerfile');
+    if (dockerfile === null) {
+      findings.push({
+        where: whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: 'Dockerfile' }),
+        what: 'absent — the image this service runs as is built from it'
+      });
+    } else {
+      const from = /^FROM\s+node:(\S+)/m.exec(dockerfile);
+      const major = from === null ? null : majorOf(from[1]);
+      if (major !== platform) {
+        findings.push({
+          where: whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: 'Dockerfile' }),
+          what: from === null
+            ? `does not build on a node: image, and the platform major is ${platform}`
+            : `builds on node:${from[1].split('-')[0]}, and the platform major is ${platform}`
+        });
+      }
+    }
+
+    const pkg = readOrNull(serviceRoot, 'package.json');
+    const declared = pkg === null ? null : (JSON.parse(pkg).engines || {}).node;
+    if (typeof declared !== 'string' || declared.length === 0) {
+      findings.push({
+        where: whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: 'package.json' }),
+        what: `declares no engines.node, and the platform major is ${platform}`
+      });
+    } else if (majorOf(declared) !== platform) {
+      findings.push({
+        where: whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: 'package.json' }),
+        what: `engines.node is ${JSON.stringify(declared)}, whose major is ${majorOf(declared)}, `
+          + `and the platform major is ${platform}`
+      });
+    }
+
+    return findings;
+  }
+});
+
+const memoryLimit = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path', 'production_path', 'service_memory']),
+
+  /**
+   * The same number in both files, because the norm names dev AND production
+   * together — production is not the place to discover a different limit.
+   */
+  run({ row, serviceRoot }) {
+    const findings = [];
+
+    for (const relative of [row.path, row.production_path]) {
+      const text = readOrNull(serviceRoot, relative);
+      if (text === null) {
+        findings.push({ where: relative, what: 'absent — the service is run from it' });
+        continue;
+      }
+
+      for (const [name, node] of runtimeServices(text)) {
+        const declared = scalarAt(node, SERVICE_MEMORY_PATH);
+        if (declared === row.service_memory) continue;
+        findings.push({
+          where: relative,
+          what: declared === null
+            ? `service ${name} declares no ${SERVICE_MEMORY_PATH} — the platform norm is ${row.service_memory}`
+            : `the service declares ${declared}, the platform norm is ${row.service_memory}`
+        });
+      }
+    }
+
+    return findings;
+  }
+});
+
+/**
+ * The argv a `command:` declaration means, whichever of the two shapes compose
+ * accepts it is written in — `["node", "index.js"]` or `node index.js`. Two
+ * spellings of one decision, and a row grading the spelling would report a
+ * service that is already right.
+ *
+ * @param {string} declared the declaration verbatim
+ * @returns {string[]|null} null when there is nothing there, or when the
+ *   bracket form is not readable — an unreadable command is a finding, not a pass
+ */
+function argvOf(declared) {
+  const text = String(declared).trim();
+  if (text === '') return null;
+  if (!text.startsWith('[')) return text.split(/\s+/);
+
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  return Array.isArray(parsed) ? parsed.map(String) : null;
+}
+
+/**
+ * `R-PID1` — the process the container runs AS.
+ *
+ * `command: ["npm","start"]` makes npm process 1, and npm does not forward
+ * SIGTERM: the stop is a ten-second wait followed by SIGKILL, so a service never
+ * gets to close its channels. Confirmation `biz-compose-pid1` 001 settled the
+ * substance ("Ano, srovnat na node") and 002 settled where it belongs: not a
+ * per-repo choice any more but part of the uniform biz service shape, which is
+ * this row.
+ *
+ * The one-shot test runner is left alone on purpose — it declares no command
+ * because `docker compose run` supplies one, and its shape is F-RUNNER's row.
+ *
+ * @see api/docs/governance/confirmations/biz-compose-pid1.md
+ */
+const composeCommand = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path', 'service_command']),
+
+  run({ row, serviceRoot }) {
+    // The row states the command the way a person writes it; which of the two
+    // compose spellings a service happens to use is not the row's business.
+    const expected = argvOf(row.service_command);
+    if (expected === null) {
+      throw new Error('[ManifestRuntime] Platform command unreadable - row '
+        + `${row.id} declares service_command as ${JSON.stringify(row.service_command)}, which names no command. `
+        + 'Fix: state it as the argv a container runs, e.g. "node index.js".');
+    }
+    const wanted = JSON.stringify(expected);
+    const why = `the platform shape is ${wanted}, so PID 1 is node and a SIGTERM reaches it`;
+
+    const text = readOrNull(serviceRoot, row.path);
+    if (text === null) return [{ where: row.path, what: 'absent — the service is run from it' }];
+
+    const findings = [];
+    for (const [name, node] of runtimeServices(text)) {
+      const declared = declarationOf(node, 'command');
+      const argv = argvOf(declared);
+
+      if (argv === null && declared.trim() === '') {
+        findings.push({ where: row.path, what: `service ${name} declares no command — ${why}` });
+        continue;
+      }
+      if (argv !== null && argv.length === expected.length && argv.every((word, i) => word === expected[i])) continue;
+
+      findings.push({ where: row.path, what: `service ${name} runs as ${declared.trim()} — ${why}` });
+    }
+
+    return findings;
+  }
+});
+
+const composeNoPorts = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path']),
+
+  run({ row, serviceRoot }) {
+    const text = readOrNull(serviceRoot, row.path);
+    if (text === null) return [];
+
+    return [...readComposeServices(text).entries()]
+      .filter(([, node]) => declares(node, 'ports'))
+      .map(([name]) => ({
+        where: row.path,
+        what: `service ${name} publishes a port — a biz service binds nothing, and work arrives over MQ`
+      }));
+  }
+});
+
+module.exports = {
+  checks: [
+    { name: 'node-major', check: nodeMajor },
+    { name: 'memory-limit', check: memoryLimit },
+    { name: 'compose-command', check: composeCommand },
+    { name: 'compose-no-ports', check: composeNoPorts }
+  ],
+  majorOf
+};