@onlineapps/conn-orch-validator 8.1.0 → 10.0.0

package/src/manifest/checks/serviceFiles.js

@@ -27,9 +27,10 @@ const path = require('path');
 
 const { readReferencedFile, isPackageReference, referenceOwner } = require('../discovery');
 const { whereOf } = require('./libraryContext');
+const { describeWorkspaceFix } = require('../workspaceRoot');
 const { readComposeServices, scalarAt, declares, declarationOf } = require('./composeShape');
 const {
-  SHARED_DECLARATIONS, CONTAINER_PLACEHOLDER, SERVICE_PLACEHOLDER, normalizeRunnerBlock
+  SHARED_DECLARATIONS, renderRunnerIdentity, stripDeclarations
 } = require('./composeRunnerBlock');
 const { renderText, topLevelKeys } = require('../../sync/serviceTemplate');
 const { readIdentity, requireIdentity, IDENTITY_FILE } = require('../serviceIdentity');
@@ -51,7 +52,8 @@ const READS_ITS_REFERENCE_ONLY = Object.freeze({
   needsWorkspace: ({ row }) => !isPackageReference(row.from),
 
   describeNotRun({ row }) {
-    return `the workspace root is not reachable, so ${referenceOwner(row.from)} cannot be read`;
+    const owner = referenceOwner(row.from);
+    return `the workspace root is not reachable, so ${owner} cannot be read. ${describeWorkspaceFix(owner)}`;
   }
 });
 
@@ -433,9 +435,14 @@ const composeRunner = Object.freeze({
       return findings;
     }
 
+    // The reference is rendered for THIS repository and compared with the file
+    // as it stands — the direction the generator writes in, and the only one
+    // that is exact (`composeRunnerBlock.js` § renderRunnerIdentity, d.531).
+    // The three shared declarations come off both sides, because the rows above
+    // compare those against the service this runner tests.
     const difference = firstDifference(
-      normalizeRunnerBlock({ lines: mine, containerName, serviceName }),
-      normalizeRunnerBlock({ lines: reference, containerName: CONTAINER_PLACEHOLDER, serviceName: SERVICE_PLACEHOLDER })
+      stripDeclarations(mine, SHARED_DECLARATIONS),
+      stripDeclarations(renderRunnerIdentity({ lines: reference, containerName, serviceName }), SHARED_DECLARATIONS)
     );
     if (difference !== null) {
       say(`the "${row.block}" block differs from the template at block line ${difference.line}: `
@@ -600,6 +607,25 @@ const DOCKERIGNORE_BLOCK = 'oa-dockerignore v1';
  */
 const DOCKER_IMPLICIT = Object.freeze(['.git']);
 
+/**
+ * The test tree, which `.gitignore` must NOT declare and the image must not
+ * carry: tests live in the repository and never in the artefact that runs. It is
+ * the same decision the library uniform makes one row over as `L-PACK-TESTS`,
+ * applied to an image instead of a tarball — the reason is one, so the sentence
+ * is one (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * The exception is the reason this is a list and not a line. `tests/cookbooks`
+ * is NOT a test: it is a declaration the RUNTIME reads. Tier-1 of the boot runs
+ * those cookbooks at phase 0.2, and an image without the directory measures zero
+ * of them, so `ValidationProofGenerator` refuses the proof as NO_TESTS
+ * (`src/validators/ValidationProofGenerator.js`) and the service never starts.
+ * Measured on 2026-09-16 against the wrapper's boot path.
+ *
+ * Order carries the meaning: in a `.dockerignore` a later line wins, so the
+ * re-inclusion stands AFTER the two exclusions and never before them.
+ */
+const DOCKER_TEST_TREE = Object.freeze(['tests', '**/tests', '!tests/cookbooks']);
+
 /**
  * The exclusions a `.dockerignore` must carry, DERIVED from the very declaration
  * the `.gitignore` row reads. One list, two consumers
@@ -619,9 +645,9 @@ const DOCKER_IMPLICIT = Object.freeze(['.git']);
  * A negation keeps its `!` in front of the pattern rather than inside it, and
  * keeps its place in the order — in both formats a later line wins.
  *
- * What the derivation does NOT do is exclude anything `.gitignore` does not:
- * `tests/` is the measured trap on that side, because Tier-1 of the boot reads
- * `tests/cookbooks` and an image without it fails at phase 0.2.
+ * What the derivation adds to the declaration is the test tree, and exactly one
+ * exception inside it — see `DOCKER_TEST_TREE` above. Nothing else: an entry the
+ * `.gitignore` does not declare has no business being invented here.
  *
  * @param {string} gitignoreText the declaration both rows read
  * @returns {string[]}
@@ -640,6 +666,7 @@ function dockerignoreEntries(gitignoreText) {
     if (!pattern.includes('/')) add(mark(`**/${pattern}`));
   }
 
+  for (const entry of DOCKER_TEST_TREE) add(entry);
   for (const entry of DOCKER_IMPLICIT) add(entry);
   return entries;
 }

package/src/manifest/checks/serviceIdentityRows.js

@@ -46,6 +46,7 @@ const { readComposeServices } = require('./composeShape');
 const { readIdentity, IDENTITY_FILE } = require('../serviceIdentity');
 const { PLACEHOLDERS } = require('../../sync/serviceTemplate');
 const { resolveFromMap } = require('../discovery');
+const { describeWorkspaceFix } = require('../workspaceRoot');
 
 /** Where a service declares the name npm knows it by. */
 const PACKAGE_FILE = 'package.json';
@@ -271,7 +272,8 @@ const ssotIdentity = Object.freeze({
   requires: Object.freeze([]),
 
   describeNotRun({ block }) {
-    return `the workspace root is not reachable, so ${block.from.path} cannot be read`;
+    return `the workspace root is not reachable, so ${block.from.path} cannot be read. `
+      + describeWorkspaceFix(block.from.path);
   },
 
   run({ block, serviceRoot, workspaceRoot }) {

package/src/manifest/checks/serviceRuntime.js

@@ -44,6 +44,7 @@ const path = require('path');
 
 const { resolveFromValue, isPackageReference, referenceOwner } = require('../discovery');
 const { whereOf } = require('./libraryContext');
+const { describeWorkspaceFix } = require('../workspaceRoot');
 const { readComposeServices, scalarAt, declares, declarationOf } = require('./composeShape');
 
 /** Where a service block states its own budget, in both compose files. */
@@ -106,7 +107,8 @@ const nodeMajor = Object.freeze({
   needsWorkspace: ({ row }) => !isPackageReference(row.from),
 
   describeNotRun({ row }) {
-    return `the workspace root is not reachable, so ${referenceOwner(row.from)} cannot be read`;
+    const owner = referenceOwner(row.from);
+    return `the workspace root is not reachable, so ${owner} cannot be read. ${describeWorkspaceFix(owner)}`;
   },
 
   run({ row, serviceRoot, workspaceRoot }) {

package/src/manifest/discovery.js

@@ -237,21 +237,38 @@ function resolveFromValue({ from, workspaceRoot }) {
 }
 
 /**
- * The node a `from.list` path points at, as the owner file writes it.
+ * The whole referenced file as the document it is: `{ path, text: true }` over a
+ * JSON SSOT, for a row that does not take a value out of it but hands it to the
+ * module that owns its shape (`G-SHARED-ENV` renders `api/config/shared-env.json`
+ * through `src/sync/sharedEnv.js`).
  *
- * @param {{ from: {path: string, list: string}, workspaceRoot: string }} params
- * @returns {Array|object} the array or the object map the reference names
+ * It is the same read and the same refusal `resolveFromMap` makes, said once:
+ * a broken SSOT is reported as a broken SSOT wherever a row reads it, and the
+ * second call site is the one that would have written its own sentence
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * @param {{ from: {path: string}, workspaceRoot: string }} params
+ * @returns {object|Array} the parsed document
  */
-function resolveFromMap({ from, workspaceRoot }) {
+function resolveFromDocument({ from, workspaceRoot }) {
   const raw = readReferencedFile({ from, workspaceRoot });
 
-  let document;
   try {
-    document = JSON.parse(raw);
+    return JSON.parse(raw);
   } catch (cause) {
-    throw new Error(`[ManifestDiscovery] Referenced file is not valid JSON - ${from.path}. `
+    throw new Error(`[ManifestDiscovery] Referenced file is not valid JSON - ${referenceOwner(from)}. `
       + 'Fix: repair the file; it is the SSOT this row reads.', { cause });
   }
+}
+
+/**
+ * The node a `from.list` path points at, as the owner file writes it.
+ *
+ * @param {{ from: {path: string, list: string}, workspaceRoot: string }} params
+ * @returns {Array|object} the array or the object map the reference names
+ */
+function resolveFromMap({ from, workspaceRoot }) {
+  const document = resolveFromDocument({ from, workspaceRoot });
 
   const node = from.list.split('.').reduce((current, key) => (current == null ? undefined : current[key]), document);
   if (node === null || node === undefined || typeof node !== 'object') {
@@ -378,6 +395,7 @@ module.exports = {
   resolveFromValue,
   resolveFromMap,
   readReferencedFile,
+  resolveFromDocument,
   expandPattern,
   rootOfPattern,
   containerOf,

package/src/manifest/runManifest.js

@@ -19,7 +19,7 @@ const path = require('path');
 const { verifyManifestShape, rowNeedsWorkspace } = require('./manifestShape');
 const { collectRows } = require('./walk');
 const { discoverBearers, rootOfPattern } = require('./discovery');
-const { resolveWorkspacePath, canonicalRoot } = require('./workspaceRoot');
+const { resolveWorkspacePath, canonicalRoot, describeWorkspaceFix } = require('./workspaceRoot');
 const { CHECK_REGISTRY } = require('./checks');
 
 /** The three scopes, by the name the runner branches on. */
@@ -164,22 +164,45 @@ function runManifest({ manifest, serviceRoot = null, workspaceRoot = null, check
     const check = checkRegistry[row.check];
     const needsWorkspace = rowNeedsWorkspace({ check, row, block });
 
+    // The sentence a row is reported NOT RUN with belongs to the CHECK, because
+    // only the check knows what it could not read. Until d.518 a check that
+    // declared none borrowed `the workspace root is not reachable` from here —
+    // a sentence about a row this file knows nothing about, with no fix in it,
+    // which nothing reached: every registered workspace-dependent check owns
+    // one, and `service-identity` declares `needsWorkspace: () => false` and
+    // cannot arrive here at all. A default nobody reaches is the false
+    // guarantee `.claude/rules/automation-gates.md` §5 calls a defect, so the
+    // duty is stated rather than covered for — and stated on EVERY run, not
+    // only on the ones without a workspace, which is where it would otherwise
+    // be discovered (`architecture-principles.md` §4, fail-fast).
+    if (needsWorkspace && typeof check.describeNotRun !== 'function') {
+      throw new Error(`[Manifest] Check "${row.check}" owns no NOT RUN sentence - row ${row.id} needs the `
+        + 'workspace, so a run without one has to say why this row was not answered and how to answer it. '
+        + 'Fix: add describeNotRun({ row, block }) to the check, ending it with '
+        + 'workspaceRoot.js § describeWorkspaceFix.');
+    }
+
     if (needsWorkspace && workspace === null) {
       notRun.push({
         id: row.id,
         severity: row.severity,
-        reason: check.describeNotRun
-          ? check.describeNotRun({ row, block })
-          : 'the workspace root is not reachable'
+        reason: check.describeNotRun({ row, block })
       });
       continue;
     }
 
     if (needsWorkspace && outsideWorkspace) {
+      // A state sentence is not a remedy. This one said where the repository
+      // is NOT, and stopped — the same half-answer d.518 removed from the
+      // checks' own sentences, in the branch that reports it for them. The
+      // command comes from the one owner of it, and what the checkout has to
+      // carry is the repository under check (d.523).
       notRun.push({
         id: row.id,
         severity: row.severity,
-        reason: `service root is outside the workspace root ${workspace}`
+        reason: `service root is outside the workspace root ${workspace} `
+          + '- a row about the workspace cannot be answered about a repository that is not in it. '
+          + describeWorkspaceFix(root)
       });
       continue;
     }
@@ -320,13 +343,41 @@ function missingRoots({ roots, workspaceRoot }) {
 }
 
 /**
+ * The NOT RUN reason for a row whose sibling root is not there, naming every
+ * missing one AND what to do about it.
+ *
+ * The fix half is not decoration. This line is read where the reader has no
+ * workspace to look at — a service's own CI log, a container — and until d.511
+ * it stopped at "is not present in this checkout": true, and nothing anybody
+ * could act on. Measured 2026-09-15 over a `git archive` export of
+ * `api_biz/hello-service` placed beside an api clone with no `api_biz/` around
+ * them: the run printed `NOT RUN  U-ORPHAN — sibling root api_biz is not
+ * present in this checkout` and, because the report's own incomplete-run
+ * sentence carries its fix only on a CLEAR verdict (`report.js`
+ * § describeClearOutcome), a run that also had findings named no fix at all.
+ * `automation-gates.md` §1 requirement 4 asks for the exact command, and the
+ * sync half of this package already gives it (`src/sync/uniformFiles.js`
+ * § planRow).
+ *
+ * The command is DERIVED from the missing roots rather than written beside
+ * them, so a row that starts reading a new sibling needs no second edit here.
+ * It is also not written HERE: the sentence belongs to `workspaceRoot.js`
+ * § describeWorkspaceFix, because the bridge to the documentation lint reports
+ * the same absence through the linter's own NOT RUN channel and must offer the
+ * same remedy (d.516, `.claude/rules/change-discipline.md` § One rail per
+ * concern). This function still owns what is missing; the helper owns what to
+ * do about it.
+ *
  * @param {string[]} missing the roots that are not there
- * @returns {string} the NOT RUN reason, naming every one of them
+ * @returns {string} the NOT RUN reason, naming every one of them and the fix
  */
 function describeMissingRoots(missing) {
-  return missing.length === 1
+  const found = missing.length === 1
     ? `sibling root ${missing[0]} is not present in this checkout`
     : `sibling roots ${missing.join(', ')} are not present in this checkout`;
+
+  return `${found} - an absent directory is not an empty one, so this row is not answered. `
+    + describeWorkspaceFix(missing.join(', '));
 }
 
 /**

package/src/manifest/workspaceRoot.js

@@ -37,10 +37,34 @@
  * `startDir` and get the workspace THAT TREE belongs to. It is a different
  * question, asked explicitly, never a fallback of the other one.
  *
+ * ## The service a run is ABOUT (d.540)
+ *
+ * A run over a service repository asks a third question, and it is as
+ * deterministic as the other two: the workspace is the nearest ancestor OF THE
+ * SERVICE ROOT that carries an api checkout — the root the caller named, never
+ * the directory the shell happens to stand in. `oa-validate` passes it as
+ * `serviceRoot`.
+ *
+ * It exists because the package question answers about the PACKAGE, and the copy
+ * a service runs is the one it installed: `oa-validate .` inside
+ * `<workspace>/api_biz/<service>` printed `Workspace root: NOT RESOLVED` and
+ * reported every `U-*` and `D-*` row NOT RUN, for a service lying in a complete
+ * workspace two directories up (measured 2026-09-16, BIZ-hello). The run knew
+ * where the service was and refused to look there.
+ *
+ * The three questions are asked in a stated order, and none of them reads
+ * ambient state: an explicit `--workspace` wins, then the tree the run is about
+ * (`startDir`, or `serviceRoot`), then the checkout this package is part of.
+ * The last one is what answers for a run whose subject lies in NO workspace —
+ * the service root is then reported as outside the workspace it names, which is
+ * true and actionable — and when neither question finds a checkout the run says
+ * NOT RESOLVED, exactly as before.
+ *
  * An INSTALLED copy (`<service>/node_modules/@onlineapps/conn-orch-validator`)
- * lies in no checkout, so it resolves nothing and the rows that need the SSOT
- * are reported NOT RUN — loudly, never as a pass (`automation-gates.md` §5).
- * That is what a service container has, and it is unchanged by this rule.
+ * lies in no checkout, so it speaks for none: the rows that read the platform
+ * SSOT are answered from the workspace the SERVICE lies in, or reported NOT RUN
+ * — loudly, never as a pass (`automation-gates.md` §5). A service container,
+ * whose image carries no workspace above `/app`, is unchanged by this rule.
  */
 
 const fs = require('fs');
@@ -201,11 +225,19 @@ function workspaceAbove(startDir) {
 }
 
 /**
- * @param {{ explicit?: string|null, startDir?: string|null }} params
+ * The three questions, in the order the header states them: the root the caller
+ * NAMED, then the tree the run is about, then the checkout this package is part
+ * of. `startDir` and `serviceRoot` are both "the tree this run is about" and
+ * differ in what happens when that tree lies in no workspace — a run that WRITES
+ * into a tree stops there (there is nowhere to write from), a run that MEASURES
+ * one lets the package answer, so the report can say which workspace the service
+ * root is outside of.
+ *
+ * @param {{ explicit?: string|null, startDir?: string|null, serviceRoot?: string|null }} params
  * @returns {string|null} absolute workspace root, or null when neither the named
  *   tree nor this package lies in one
  */
-function resolveWorkspaceRoot({ explicit = null, startDir = null } = {}) {
+function resolveWorkspaceRoot({ explicit = null, startDir = null, serviceRoot = null } = {}) {
   if (explicit !== null && explicit !== undefined) {
     const resolved = path.resolve(explicit);
     if (apiCheckoutOf(resolved) === null) {
@@ -226,17 +258,71 @@ function resolveWorkspaceRoot({ explicit = null, startDir = null } = {}) {
     return above === null ? null : canonicalRoot(above);
   }
 
+  if (serviceRoot !== null && serviceRoot !== undefined) {
+    if (typeof serviceRoot !== 'string' || serviceRoot.length === 0) {
+      throw new Error('[ManifestWorkspace] Service root is required - resolveWorkspaceRoot({ serviceRoot }) got '
+        + `${JSON.stringify(serviceRoot)}. Fix: pass the repository the run is about, or omit it to use this `
+        + 'package\'s own checkout.');
+    }
+    const above = workspaceAbove(serviceRoot);
+    if (above !== null) return canonicalRoot(above);
+  }
+
   return API_CHECKOUT_ROOT === null ? null : canonicalRoot(path.dirname(API_CHECKOUT_ROOT));
 }
 
+/**
+ * The command that turns "this run had no such checkout" into a run that does —
+ * one sentence, one owner, wherever a row is reported NOT RUN because the tree
+ * it needed was not under the workspace.
+ *
+ * It exists as a function because there are two such places and they were
+ * drifting apart. `runManifest.js` § describeMissingRoots gained it in d.511,
+ * from the roots a row declares; the bridge to the documentation lint
+ * (`checks/docsLintBridge.js`) reports the same absence through the linter's own
+ * NOT RUN channel and, until d.516, ended at "the probe could not be evaluated"
+ * — true, and nothing anybody could act on (`.claude/rules/automation-gates.md`
+ * §1 requirement 4). Two sentences for one remedy is the second rail
+ * `.claude/rules/change-discipline.md` § One rail per concern names.
+ *
+ * What the checkout must CARRY is the caller's, because only the caller knows
+ * it: a row declares its roots and names them, while the bridge is handed a
+ * reason written by the linter — which names the probe target itself, and which
+ * this package neither writes nor parses (the bridge cites the lint, it does not
+ * restate it).
+ *
+ * @param {string} carries what a workspace has to hold for the row to be
+ *   answered — the missing roots when the caller resolved them, otherwise the
+ *   thing the reason in front of this sentence already named
+ * @returns {string} the `Fix:` sentence, ending in a full stop
+ */
+function describeWorkspaceFix(carries) {
+  if (typeof carries !== 'string' || carries.length === 0) {
+    throw new Error('[ManifestWorkspace] Fix subject is required - describeWorkspaceFix() got '
+      + `${JSON.stringify(carries)}, so the sentence would tell the reader to carry nothing. `
+      + 'Fix: pass the missing roots, or the phrase naming what the reason before it points at.');
+  }
+  return `Fix: run with --workspace pointing at a checkout that carries ${carries}.`;
+}
+
+/**
+ * What the bridge to a delegated checker passes as `carries`: the absent thing
+ * is named by the checker's own reason, which sits immediately before this
+ * sentence, so the fix points back at it instead of repeating it in this
+ * package's words.
+ */
+const AS_THE_REASON_NAMES = 'what this reason names';
+
 module.exports = {
   resolveWorkspaceRoot,
   canonicalRoot,
   workspaceAbove,
   resolveWorkspacePath,
+  describeWorkspaceFix,
   apiCheckoutOf,
   API_CHECKOUT_ROOT,
   API_MARKER,
+  AS_THE_REASON_NAMES,
   PACKAGE_ROOT,
   WORKSPACE_MARKER
 };

package/src/sync/serviceTemplate.js

@@ -124,13 +124,33 @@ const PACKED_NAMES = Object.freeze({
 /**
  * The files a service is expected to EXECUTE, so the ones written executable.
  *
- * `init.sh` is the file a service is started through. `scripts/verify-deploy-uniform.sh`
- * is invoked by name from the `deploy-production` job of the rendered
- * `.gitlab-ci.yml`, so a copy without the bit fails that job with "permission
- * denied" instead of measuring the uniform — and a gate that cannot run is the
- * false guarantee `automation-gates.md` §5 names.
+ * `init.sh` is the file a service is started through — and since d.555 it is the
+ * only one: the deploy gate is no longer rendered into a service (see
+ * `PACKAGE_ONLY` below), so there is no copy of it in a repository to give a bit
+ * to.
  */
-const EXECUTABLE_FILES = Object.freeze(['init.sh', 'scripts/verify-deploy-uniform.sh']);
+const EXECUTABLE_FILES = Object.freeze(['init.sh']);
+
+/**
+ * Files this package carries INSIDE the template directory that are not part of
+ * the scaffold — the package's own, reached by the path a pin installs.
+ *
+ * `scripts/verify-deploy-uniform.sh` is the uniform gate. Until d.529 the
+ * rendered `.gitlab-ci.yml` ran the copy in the service repository; since then
+ * BOTH callers — the `validate-uniform` job and `deploy-production` — invoke
+ * `node_modules/@onlineapps/conn-orch-validator/templates/business-service/scripts/verify-deploy-uniform.sh`,
+ * the pinned one. So the rendered copy is read by nothing, and the four
+ * questions `change-discipline.md` § "Removing something removes its
+ * declaration" asks answer cleanly: it came to exist with the deploy job of
+ * d.421, it carried gate 008, nothing reads it because the callers moved to the
+ * pin, and what replaces it is MORE conceptual — one pin, one gate, versioned
+ * with the manifest it measures against, instead of eight copies that drift the
+ * day one of them is edited.
+ *
+ * It stays in the package rather than moving elsewhere in it: the path is what
+ * the rendered CI file names, and the file lives where that path points.
+ */
+const PACKAGE_ONLY = Object.freeze(['scripts/verify-deploy-uniform.sh']);
 
 /**
  * The env template's name in the template, and the name it is written under.
@@ -340,7 +360,7 @@ function listTemplateFiles(root) {
     }
   };
   walk(root, '');
-  return collected.sort();
+  return collected.filter((relative) => !PACKAGE_ONLY.includes(relative)).sort();
 }
 
 /**
@@ -483,6 +503,53 @@ function insertBlockUnder({ text, key, replacement }) {
   return [...lines.slice(0, at + 1), ...replacement, '', ...lines.slice(at + 1)].join('\n');
 }
 
+/**
+ * A file with a delimited block INSERTED after a shell function's closing brace,
+ * and every other line of it left exactly as it was.
+ *
+ * The sibling of `insertBlockUnder`, for the file that is not a mapping. Both
+ * answer the same question — where does a block that is not there yet go? — and
+ * both answer it from something the FILE declares rather than from a judgement
+ * about the service. In a compose file that is the `services:` key; in an
+ * `init.sh` it is the end of the function the block's own text refers to
+ * ("A service's own install steps belong in oa_npm_install() above, everything
+ * else it needs goes below"), which the row names as its anchor.
+ *
+ * Measured 2026-09-16 in api_biz/invoicing: the sync refused this state with
+ * "paste the block from the template once", a message telling a human to
+ * hand-copy generated content, which is what `automation-gates.md` §1.4 calls a
+ * defect — the run knows the bytes and, with the anchor, the place.
+ *
+ * Without the anchor the refusal STAYS a refusal, and names the anchor rather
+ * than the block: where a service's own install steps end is that service's
+ * decision, and a generator guessing it would write the block above or below
+ * code that has to run on the other side.
+ *
+ * @param {{text: string, fn: string, replacement: string[]}} args the file, the
+ *   shell function the block belongs after, and the block's lines
+ * @returns {string}
+ */
+function insertBlockAfterFunction({ text, fn, replacement }) {
+  const lines = text.split('\n');
+  const opens = new RegExp(`^${fn}\\s*\\(\\)\\s*\\{`);
+
+  const start = lines.findIndex((line) => opens.test(line.trimEnd()));
+  if (start === -1) {
+    throw new Error(`[ServiceTemplate] No ${fn}() to insert the block after - the file declares no line `
+      + `opening "${fn}() {", so where this service's own install steps end is undefined and the block `
+      + `has no unambiguous place. Fix: wrap this file's install command in a ${fn}() function, then run `
+      + 'the sync again.');
+  }
+
+  const end = lines.findIndex((line, index) => index > start && line.trimEnd() === '}');
+  if (end === -1) {
+    throw new Error(`[ServiceTemplate] The ${fn}() function never closes - "${fn}() {" is there, its "}" `
+      + 'is not, so the end of the install steps is undefined. Fix: close the function, then run the sync again.');
+  }
+
+  return [...lines.slice(0, end + 1), '', ...replacement, ...lines.slice(end + 1)].join('\n');
+}
+
 /** A top-level mapping key: a line that starts in column 0 and ends its key with a colon. */
 const TOP_LEVEL_KEY = /^([A-Za-z_][A-Za-z0-9_.-]*):/;
 
@@ -565,6 +632,7 @@ module.exports = {
   SSOT_PIN,
   PACKED_NAMES,
   EXECUTABLE_FILES,
+  PACKAGE_ONLY,
   ENV_TEMPLATE_SOURCE,
   envTemplateTarget,
   deriveParams,
@@ -577,6 +645,7 @@ module.exports = {
   renderText,
   renderTree,
   spliceBlock,
+  insertBlockAfterFunction,
   topLevelKeys,
   replaceTopLevelKeys,
   insertBlockUnder

package/src/sync/sharedEnv.js

@@ -66,10 +66,17 @@ function assertManifest(manifest) {
  * nothing that varies between two runs - the same manifest always renders the
  * same bytes, which is what makes `--check` a gate rather than a diff of noise.
  *
- * `consumers` is deliberately NOT rendered: who reads a key is a fact the code
- * owns and a check measures, and a hand-maintained copy of it inside every
- * service's env file would rot the moment a reader moved
- * (`.claude/rules/doc-code-binding.md` §1).
+ * `consumers` is deliberately NOT rendered: a hand-maintained copy of who reads
+ * a key, inside every service's env file, would rot the moment a reader moved
+ * (`.claude/rules/doc-code-binding.md` §1). That half is measured - the CONTROL
+ * case in `tests/unit/sharedEnv.test.js` moves the field and asserts the
+ * rendered text does not move with it. The field's own content is held by
+ * REVIEW: no code in this package reads it, and no gate elsewhere does either
+ * (`api/config/shared-env.json`, `_consumers`). The machine answer to "who
+ * reads this name" is per service, not per platform: the `env-contract` check
+ * (row `C-ENV-READS` of `manifests/biz-service.manifest.json`) measures the
+ * names a service's code reads against what its
+ * `config/service/integration-contract.json` declares.
  *
  * @param {{keys: Array<{name: string, value: string, why: string}>}} manifest
  * @returns {string}