@onlineapps/conn-orch-validator 10.0.0 → 11.0.0

package/src/utils/stepReferences.js

@@ -0,0 +1,278 @@
+'use strict';
+
+const { resolveReferencesWith, resolveReferencePath } = require('@onlineapps/cookbook-core');
+
+/**
+ * The run context a Tier-1 cookbook resolves its `{{…}}` references against.
+ *
+ * WHY IT EXISTS. Until 2026-09-17 the runner executed every step independently:
+ * `stepResults` only counted, and nothing a step returned could reach the next
+ * one. A recipe therefore could not build the data it needs, so biz-converter's
+ * boot recipe depended on a row only a TEST_ONLY seed supplies — and on
+ * production Tier-1 answered `NOT_CONVERTIBLE`, the boot exited 1 after ~18
+ * minutes of backoff and the container restarted in a loop (measured
+ * 2026-09-16). The owner's decision was that the recipe stays as written and the
+ * RUNNER learns what the orchestrator already does
+ * (`api/docs/governance/confirmations/converter-boot-cookbook.md` 001).
+ *
+ * ONE RAIL, AND IT IS NOT THIS PACKAGE'S. The syntax, the type rule for a whole
+ * expression, the ban on addressing a step by position and the fate of an
+ * unresolved reference all belong to the cookbook format —
+ * `api/docs/biz/40-cookbooks/variable-references.md`. The traversal of the value
+ * and the walk of one path belong to `@onlineapps/cookbook-core`:
+ * `resolveReferencesWith()` and `resolveReferencePath()`, the same two functions
+ * `WorkflowOrchestrator._resolveInputReferencesAsync` /
+ * `_resolveTemplateExpression` call. This module writes no parser; it supplies
+ * the SCOPE, which is the only part Tier-1 owns.
+ *
+ * THE SCOPE IS THE ORCHESTRATOR'S, SPELLED THE SAME WAY. A completed entry is
+ * "the step definition unchanged, plus two added fields: `output` and
+ * `_execution`" — the section "Runtime context (`context.steps`)" of
+ * api/docs/biz/40-cookbooks/format.md — and a reference addresses it by
+ * `step_id`, which is what
+ * `WorkflowOrchestrator.referenceScope()` puts under the root `steps` (its
+ * `steps_by_id` map). A second spelling here, such as a bare `status` beside
+ * `output`, would resolve at boot and stay literal in production: precisely the
+ * divergence class that broke the converter's boot.
+ *
+ * WHAT TIER-1 DELIBERATELY DOES NOT CARRY. The orchestrator's context also holds
+ * `api_input`, `delivery` and the tenancy keys. A Tier-1 run has no workflow
+ * input and no delivery at all, so those roots are absent and a reference to
+ * them stays literal — the norm's documented outcome for an unresolvable
+ * reference, not a silent substitution.
+ *
+ * @see api/docs/biz/40-cookbooks/variable-references.md
+ * @see api/docs/biz/40-cookbooks/format.md
+ * @module utils/stepReferences
+ */
+
+/**
+ * The context one cookbook run starts from: no step has produced anything yet.
+ *
+ * It is per COOKBOOK, never per runner — `runCookbooks()` executes many
+ * cookbooks through one runner and a step of one must not see a step of
+ * another.
+ *
+ * @returns {{steps: Object}} the scope `resolveStepInput` resolves against
+ */
+function createRunContext() {
+  return { steps: {} };
+}
+
+/**
+ * Resolve the `{{…}}` references in ONE step's input.
+ *
+ * `input` is the only field expanded. The format names three expansion sites —
+ * `step.input`, a `foreach` iterator and a `switch` expression
+ * (`variable-references.md` § Limitations) — and a Tier-1 cookbook has only the
+ * first: `CookbookTestRunner.validateCookbook` requires `service` and
+ * `operation` of every step, so a `foreach` or `switch` step never reaches this
+ * runner. `expect` is not on that list and is therefore taken literally, the
+ * same as `service`, `operation` and `depends_on`.
+ *
+ * @param {Object} step - the cookbook step as written
+ * @param {{steps: Object}} runContext - what earlier steps produced
+ * @returns {Promise<*>} the input the handler is called with
+ */
+function resolveStepInput(step, runContext) {
+  return resolveReferencesWith(
+    step.input,
+    (expression) => resolveReferencePath(expression, runContext)
+  );
+}
+
+/**
+ * WHAT A TIER-1 RECIPE MAY WRITE IN `input`, checked before the run starts.
+ *
+ * Tier-1 is the service's own startup proof, so a recipe it passes must be a
+ * recipe production would accept. Two shapes broke that symmetry, both by going
+ * QUIET where production is loud:
+ *
+ *   1. a helper call — `{{webalizeString(…)}}`, `{{string2file(…)}}`. The
+ *      orchestrator resolves it through its helper registry and throws on a
+ *      name the registry does not carry
+ *      (`WorkflowOrchestrator._executeTemplateHelper`). This runner has no
+ *      registry — deliberately: a helper reaches its own runtime (ContentResolver,
+ *      files, storage), which is not what a boot probe may do. So the expression
+ *      resolved to nothing and survived as literal text, and the step ran with
+ *      `{{webalizeString(…)}}` where a value belonged.
+ *   2. a `{{steps.<id>}}` naming a step the recipe does not define. Production
+ *      refuses such a cookbook at submission with 400 `Invalid cookbook
+ *      references` (`infra/api_gateway/shared/cookbookReferences.js`,
+ *      `api/docs/governance/confirmations/cookbook-validation-placement.md` 001
+ *      — the receiver's own throw is the safety net for the paths that bypass
+ *      the gateway, and a Tier-1 boot run is exactly such a path). Here it was a
+ *      literal too.
+ *
+ * The literal outcome is right for a reference whose VALUE is missing at that
+ * moment — a step that has not run, or one that failed
+ * (`variable-references.md` § Unresolved references), and those two stay literal
+ * below. It is wrong for a name that does not exist in the recipe at all: no
+ * run can ever make it resolve.
+ *
+ * NO SECOND WALK. The traversal and the expression extraction are the same
+ * `resolveReferencesWith()` that resolves the input for real one moment later,
+ * so this check sees exactly the expressions the resolver will see. The
+ * evaluator returns `undefined` for everything: nothing is substituted here,
+ * only read.
+ *
+ * WHERE THE HELPER-CALL SHAPE OUGHT TO LIVE. `@onlineapps/cookbook-core` owns
+ * the format and exports the traversal and the path walk, but no definition of
+ * "this expression is a helper call" — the only one on the platform is the
+ * private regex in `WorkflowOrchestrator._resolveTemplateExpression`, and this
+ * module now holds a second copy of it. That is one concern on two rails
+ * (`.claude/rules/change-discipline.md` § One rail per concern) and it belongs
+ * beside `resolveReferencePath()` in cookbook-core, where both callers could
+ * read it. Recorded for the owner rather than fixed here: cookbook-core is
+ * another package's manifest.
+ *
+ * SCOPE. `input` only, which is the single expansion site a Tier-1 cookbook has
+ * (`resolveStepInput` above says why), plus `depends_on`, whose values are step
+ * names by definition.
+ *
+ * @see api/docs/biz/40-cookbooks/variable-references.md
+ * @see api/docs/governance/confirmations/cookbook-validation-placement.md
+ */
+
+/** `helperName(...)` — the shape `WorkflowOrchestrator` routes to its registry. */
+const HELPER_CALL = /^([a-zA-Z_][a-zA-Z0-9_]*)\(([\s\S]*)\)$/;
+
+/** Root of the step namespace; the only root whose names a recipe can be checked against. */
+const STEPS_ROOT = 'steps';
+
+function helperCallProblem(stepId, helperName, expression) {
+  return `Step ${stepId} input calls the template helper "${helperName}" - `
+    + `Tier-1 runs no helper registry, so "{{${expression}}}" would reach the handler as literal `
+    + 'text while the production orchestrator evaluates it (and throws when the helper name is '
+    + 'unknown). '
+    + 'Fix: remove the helper call from the step input; a Tier-1 recipe builds its values from '
+    + 'earlier steps (api/docs/biz/40-cookbooks/variable-references.md).';
+}
+
+function undefinedStepProblem(stepId, referencedId, expression, knownIds) {
+  return `Step ${stepId} references an undefined step - "{{${expression}}}" names "${referencedId}", `
+    + 'which is not a step_id of this cookbook. '
+    + `Expected one of: ${knownIds.join(', ')}. `
+    + 'Fix: correct the step_id in the reference, or add the missing step '
+    + '(api/docs/biz/40-cookbooks/variable-references.md § Unresolved references).';
+}
+
+function undefinedDependencyProblem(stepId, dependencyId, knownIds) {
+  return `Step ${stepId} depends on an undefined step - "depends_on" names "${dependencyId}", `
+    + 'which is not a step_id of this cookbook. '
+    + `Expected one of: ${knownIds.join(', ')}. `
+    + 'Fix: correct the step_id in "depends_on", or add the missing step '
+    + '(api/docs/biz/40-cookbooks/format.md § Step definition).';
+}
+
+/**
+ * What ONE expression is, measured against the names this cookbook defines.
+ *
+ * A path whose root is not `steps` — `api_input.…`, `context.…`, `current.…` —
+ * is left alone: its value comes into being at run time and a recipe says
+ * nothing about whether it will. The BRACKET form `steps[0]` is not a step
+ * reference either, in this runner or at the gateway; the dotted `steps.0` is,
+ * and it names a step no recipe can define.
+ *
+ * @returns {string|null} the problem, or `null` when the expression is fine
+ */
+function checkExpression(expression, stepId, known, knownIds) {
+  const helperCall = expression.match(HELPER_CALL);
+  if (helperCall) {
+    return helperCallProblem(stepId, helperCall[1], expression);
+  }
+
+  const parts = expression.split('.');
+  if (parts[0] !== STEPS_ROOT || parts.length < 2) return null;
+
+  const referencedId = parts[1];
+  if (known.has(referencedId)) return null;
+
+  return undefinedStepProblem(stepId, referencedId, expression, knownIds);
+}
+
+/**
+ * The problem this cookbook's step inputs carry, or `null` when they carry none.
+ *
+ * Returns the FIRST problem rather than throwing, the way
+ * `utils/cookbookFormat.checkCookbookFormatVersion` does: the caller owns the
+ * `[Context]` of the message it throws, and the caller here is the runner
+ * (`.claude/rules/architecture-principles.md` §5).
+ *
+ * @param {Array<Object>} steps - the cookbook's steps, already proved to be the array shape
+ * @returns {Promise<string|null>} the problem text without its context prefix
+ */
+async function checkStepInputExpressions(steps) {
+  const knownIds = steps
+    .map((step) => step && step.step_id)
+    .filter((stepId) => typeof stepId === 'string' && stepId.length > 0);
+  const known = new Set(knownIds);
+
+  for (const step of steps) {
+    const dependencies = Array.isArray(step.depends_on) ? step.depends_on : [];
+    for (const dependency of dependencies) {
+      if (typeof dependency !== 'string' || known.has(dependency)) continue;
+      return undefinedDependencyProblem(step.step_id, dependency, knownIds);
+    }
+
+    let problem = null;
+    await resolveReferencesWith(step.input, (expression) => {
+      if (problem === null) {
+        problem = checkExpression(expression, step.step_id, known, knownIds);
+      }
+      return undefined;
+    });
+    if (problem !== null) return problem;
+  }
+
+  return null;
+}
+
+/**
+ * Write one finished step into the run context, under its own name.
+ *
+ * `output` appears ONLY on a step that passed — "an entry carries `output` and
+ * `_execution` once it has completed, not before"
+ * (the same "Runtime context (`context.steps`)" section). A step that failed is
+ * recorded with its status and no output, so a reference into it resolves to
+ * nothing and survives as literal text: the cookbook author sees
+ * `{{steps.x.output.id}}` sitting in the failing step's input, which names the
+ * real cause.
+ *
+ * The `step_id` is REQUIRED here rather than assumed. `validateCookbook`
+ * already refuses a cookbook whose step has none, so in a run this cannot
+ * happen; the check is at the entry of this function because the alternative is
+ * a silent `steps[undefined]` — a nameless step that a later reference could
+ * never address on purpose (architecture-principles.md §4).
+ *
+ * @param {{steps: Object}} runContext - the context to write into
+ * @param {Object} step - the cookbook step as written
+ * @param {{passed: boolean, actual: *}} result - the step's result record
+ * @returns {void}
+ */
+function recordStepOutcome(runContext, step, result) {
+  if (typeof step.step_id !== 'string' || step.step_id.length === 0) {
+    throw new Error('[stepReferences] A step with no step_id cannot enter the run context - Expected a '
+      + 'non-empty "step_id"; a step is addressed by its name and never by its position '
+      + '(api/docs/biz/40-cookbooks/variable-references.md § Rules). '
+      + 'Fix: add "step_id" to the step.');
+  }
+
+  const entry = {
+    ...step,
+    _execution: { status: result.passed ? 'completed' : 'failed' }
+  };
+
+  if (result.passed) {
+    entry.output = result.actual;
+  }
+
+  runContext.steps[step.step_id] = entry;
+}
+
+module.exports = {
+  createRunContext,
+  resolveStepInput,
+  recordStepOutcome,
+  checkStepInputExpressions
+};

package/src/validators/ServiceStructureValidator.js

@@ -906,8 +906,14 @@ class ServiceStructureValidator {
       this.errors.push({
         type: 'MISSING_COOKBOOKS',
         path: 'tests/cookbooks',
+        // The problem only. The remedy is `fix`, and the printer composes the
+        // two — `formatResult` below writes a `Fix:` line of its own, the
+        // service wrapper composes `message (Fix: fix)` inline. A message that
+        // carries `Fix:` as well prints the remedy twice, which reads as two
+        // instructions; this was the only one of the validator's findings that
+        // did it (d.599).
         message: '[ServiceStructure] tests/cookbooks is missing or empty - Tier-1 boot '
-          + 'validates operations by these recipes. Fix: add tests/cookbooks/<op>.json',
+          + 'validates operations by these recipes.',
         fix: 'add tests/cookbooks/<op>.json'
       });
       return;

package/templates/business-service/.gitlab-ci.yml

@@ -288,6 +288,44 @@ deploy-production:
         # (api/docs/setup/INSTALL.md, applying a business schema).
         BIZ_DB_MIGRATIONS="$(dirname "$BIZ_DB_MIGRATIONS")"
       fi
+      # WHICH SEEDS, IF ANY. The declaration says which files the installer
+      # applies; the file's own `-- Dataset-Class:` header says what class each
+      # one is (api/docs/standards/repository-installation-sql-contract.md §4).
+      # Neither fact is copied here, and the box is handed the ANSWER: it parses
+      # no JSON, reads no header and decides no class.
+      #
+      # Only PRODUCTION_LIKE reaches a production database. A service may declare
+      # a TEST_ONLY seed in the same list - converter does - and applying the
+      # declaration verbatim would write synthetic fixtures into a live schema.
+      BIZ_DB_SEEDS=""
+      for seed in $(jq -r '.database.seeds // [] | .[]' "$CONTRACT"); do
+        seed_file="$CI_PROJECT_DIR/$seed"
+        if [ ! -f "$seed_file" ]; then
+          echo "[deploy] FATAL: $CONTRACT declares database.seeds \"$seed\" and this checkout does not carry it. Expected: the file, at that path. Fix: add it, or correct the declaration (uniform row D-DB-PACKAGE reports the same gap)." >&2
+          exit 1
+        fi
+        seed_class="$(sed -n 's/^-- Dataset-Class:[[:space:]]*\([^[:space:]]*\).*/\1/p' "$seed_file" | head -n 1)"
+        case "$seed_class" in
+          PRODUCTION_LIKE)
+            # This deploy applies every PRODUCTION_LIKE seed on EVERY run and
+            # keeps no tracker (see the step on the box for why). A file that
+            # does not converge on a replay would duplicate rows or fail, so the
+            # header that licenses the replay is a precondition of the deploy,
+            # not a comment in the file.
+            seed_idem="$(sed -n 's/^-- Idempotency:[[:space:]]*\([^[:space:]]*\).*/\1/p' "$seed_file" | head -n 1)"
+            if [ "$seed_idem" != "yes" ]; then
+              echo "[deploy] FATAL: $seed declares \"-- Idempotency: $seed_idem\" and this deploy applies every PRODUCTION_LIKE seed on every run, with no tracker. Expected: Idempotency: yes. Fix: make the seed converge on a replay (INSERT ... ON DUPLICATE KEY UPDATE), or move the part that does not into a migration." >&2
+              exit 1
+            fi
+            BIZ_DB_SEEDS="$BIZ_DB_SEEDS $seed" ;;
+          TEST_ONLY)
+            echo "[deploy] seed $seed NOT APPLIED (Dataset-Class: TEST_ONLY) - test fixtures never reach a production database." ;;
+          *)
+            echo "[deploy] FATAL: $seed declares \"-- Dataset-Class: $seed_class\" and database.seeds admits PRODUCTION_LIKE and TEST_ONLY only. Fix: correct the header (uniform row D-DB-HEADERS owns it), or remove the file from database.seeds." >&2
+            exit 1 ;;
+        esac
+      done
+      BIZ_DB_SEEDS="${BIZ_DB_SEEDS# }"
     # DEPLOY_PATH / DEPLOY_HOST / DEPLOY_USER are CI variables: the box decides
     # where its checkout lives, and no path is baked into this file.
     #
@@ -314,7 +352,7 @@ deploy-production:
         printf '%s\n' "set -euo pipefail"
         cat "$API_CHECKOUT/scripts/lib/mariadb-migrations.sh"
         cat
-      } <<'REMOTE' | ssh $DEPLOY_USER@$DEPLOY_HOST "IFS= read -r REGISTRY_PASSWORD; export REGISTRY_PASSWORD; bash -s -- '$DEPLOY_PATH' '$CI_REGISTRY' '$CI_REGISTRY_USER' '$CI_PROJECT_PATH_SLUG' '$BIZ_IMAGE_DIGEST' '$CI_PROJECT_PATH' '$BIZ_DB_SCHEMA' '$BIZ_DB_MIGRATIONS'"
+      } <<'REMOTE' | ssh $DEPLOY_USER@$DEPLOY_HOST "IFS= read -r REGISTRY_PASSWORD; export REGISTRY_PASSWORD; bash -s -- '$DEPLOY_PATH' '$CI_REGISTRY' '$CI_REGISTRY_USER' '$CI_PROJECT_PATH_SLUG' '$BIZ_IMAGE_DIGEST' '$CI_PROJECT_PATH' '$BIZ_DB_SCHEMA' '$BIZ_DB_MIGRATIONS' '$BIZ_DB_SEEDS' '$CI_COMMIT_SHA'"
       DEPLOY_PATH="$1"
       REGISTRY="$2"
       REGISTRY_USER="$3"
@@ -325,6 +363,14 @@ deploy-production:
       # only thing that turns the migration step below on or off.
       DB_SCHEMA="$7"
       DB_MIGRATIONS_DIR="$8"
+      # Space-separated, repo-relative, and already filtered to PRODUCTION_LIKE on
+      # the runner - the box parses no JSON and decides no class. Empty when the
+      # contract declares no seeds, or declares only ones no production database
+      # may see.
+      DB_SEEDS="$9"
+      # The commit the runner MEASURED the contract at. The box is moved to it
+      # below, so both sides read one declaration rather than two.
+      COMMIT_SHA="${10}"
       # This service's own env file on the box, the per-machine half of the two
       # the compose file names (../shared.env is the host's). It carries the
       # migration account - the SAME account the service connects as.
@@ -355,12 +401,39 @@ deploy-production:
       # R2: reset, never merge. A local modification on the server would turn a
       # merge into a conflict and abort the deploy halfway.
       git fetch origin production
-      git reset --hard origin/production
+      # ...and to the COMMIT THIS PIPELINE MEASURED, never to whatever
+      # origin/production points at by the time the ssh step opens. The runner
+      # read config/service/integration-contract.json at $CI_COMMIT_SHA and
+      # derived the migration directory and the seed list from it THERE; a push
+      # that lands while this job runs would otherwise leave the box applying a
+      # declaration nobody measured.
+      #
+      # It must still be ON the branch this box follows. A commit that is not is
+      # a pipeline for a different history, and resetting to it would put this
+      # box on code production never took.
+      if ! git merge-base --is-ancestor "$COMMIT_SHA" origin/production; then
+        echo "[deploy] FATAL: $COMMIT_SHA is not an ancestor of origin/production - this pipeline measured a commit that is not on the branch this box deploys, and resetting to it would put $PROJECT_PATH on a history production never took. Expected: the pipeline of a commit that is on production. Fix: re-run the pipeline of the current tip of production." >&2
+        exit 1
+      fi
+      git reset --hard "$COMMIT_SHA"
       mkdir -p "$DOCKER_CONFIG_DIR"
       echo "$REGISTRY_PASSWORD" | docker --config "$DOCKER_CONFIG_DIR" login -u "$REGISTRY_USER" --password-stdin "$REGISTRY"
       echo "[deploy] pulling $BIZ_IMAGE_DIGEST"
       docker --config "$DOCKER_CONFIG_DIR" compose -f docker-compose.production.yml pull
 
+      # Both env files, for EVERY service, BEFORE anything branches on a database.
+      # docker-compose.production.yml names them, so a missing one is fatal whether
+      # or not this service has a schema - and a service without one (pdfgen, hello)
+      # used to learn it from compose alone, as `env file ... not found`: a line that
+      # names no runbook and no owner. Neither file is committed, and neither is
+      # created by a script; the runbook step below is what puts them on the box.
+      for env_file in "$HOST_ENV" "$SERVICE_ENV"; do
+        if [ ! -f "$env_file" ]; then
+          echo "[deploy] Missing env file - $DEPLOY_PATH/$env_file does not exist on this box, and docker-compose.production.yml names it: the service could not start without it. Expected: both env files that compose names, on every box - the host-level $HOST_ENV and this service's own $SERVICE_ENV. Fix: place it on the box (both are per-machine and never committed) - api/docs/operations/production-box-provisioning.md § 3 The biz box, step 3." >&2
+          exit 1
+        fi
+      done
+
       # ─── Migrations: after the pull, before the switch ───────────────
       # Owner decision api/docs/governance/confirmations/db-migrations-first-deploy.md
       # 001, phase 2. The ordering IS the safety: at this point the new image is
@@ -380,16 +453,14 @@ deploy-production:
       if [ -z "$DB_SCHEMA" ]; then
         echo "[deploy] migrations NOT APPLICABLE (no database block) - config/service/integration-contract.json declares no database, so this service has no schema to migrate."
       else
-        # The two env files the compose names, in the order it names them: the
-        # host-level one first, this service's own second, so the same value wins
-        # here that wins inside the container. Reading only one of them would
+        # The two env files the compose names, READ in the order it names them:
+        # the host-level one first, this service's own second, so the same value
+        # wins here that wins inside the container. Reading only one of them would
         # make this step disagree with the service it migrates for, depending on
-        # which file the box happens to carry DB_HOST in.
+        # which file the box happens to carry DB_HOST in. That both exist was
+        # settled above, for every service - checking it twice would be two rails
+        # over one fact (.claude/rules/change-discipline.md § One rail per concern).
         for env_file in "$HOST_ENV" "$SERVICE_ENV"; do
-          if [ ! -f "$env_file" ]; then
-            echo "[deploy] Missing env file - $env_file does not exist on this box, and docker-compose.production.yml names it: between the two of them they carry the endpoint and the migration account of $DB_SCHEMA. Fix: place it on the box (both are per-machine and never committed), then re-run this deploy." >&2
-            exit 1
-          fi
           set -a
           . "$env_file"
           set +a
@@ -403,6 +474,15 @@ deploy-production:
           echo "[deploy] Missing environment variable -$missing in $DEPLOY_PATH/$SERVICE_ENV. Expected: the migration account of $DB_SCHEMA (the same account as DB_USER, granted on that schema only) and the endpoint it is reached at. Fix: add the keys to that file on this box; config/env-templates/ declares each of them with the reason it exists." >&2
           exit 1
         fi
+        # The runner is carried from the api clone at API_UNIFORM_REF, so a ref
+        # older than the seed entry point would reach `command not found` here -
+        # after the migrations and before the switch, in a production deploy and
+        # nowhere else. Checked before the first statement instead
+        # (automation-gates.md §1 requirement 4).
+        if [ -n "$DB_SEEDS" ] && ! declare -F apply_mariadb_seeds_over_tcp > /dev/null 2>&1; then
+          echo "[deploy] FATAL: the migration runner carried from the api clone has no apply_mariadb_seeds_over_tcp, and $DB_SCHEMA declares PRODUCTION_LIKE seeds this deploy has to apply. Expected: that entry point in api/scripts/lib/mariadb-migrations.sh. Fix: move API_UNIFORM_REF to an api commit that carries it, and re-run this deploy." >&2
+          exit 1
+        fi
         # The precondition confirmation 001 demands before any migration: the
         # account opens the schema, or this deploy stops and names the runbook.
         if ! mariadb_migrations_can_open_over_tcp "$DB_HOST" "$DB_PORT" "$DB_SCHEMA"; then
@@ -435,6 +515,24 @@ deploy-production:
         # anywhere in a deploy job, and the gate that keeps this job free of one
         # judges by the word, not by the intent.
         echo "[deploy] migrations $DB_SCHEMA: $MARIADB_MIGRATIONS_APPLIED applied now, $(wc -l < "$TRACKER" | tr -d " ") recorded in $DEPLOY_PATH/$TRACKER"
+        # Seeds: after the migrations, before the switch, for the same reason the
+        # migrations are there - the schema they write into is the one the step
+        # above just brought up to date, and the old container is still serving.
+        #
+        # They are NOT tracked. The tracker answers "has this file ever been
+        # applied", and a PRODUCTION_LIKE seed is a regenerated reference set
+        # whose name never changes and whose content does - converter's system
+        # catalogue is written by a generator in its own repository. Tracking it
+        # would pin production to the first catalogue ever installed, which is the
+        # drift this step exists to close. What licenses the replay is the file's own
+        # `-- Idempotency: yes`, and the runner side refused this deploy if it did
+        # not say so.
+        if [ -z "$DB_SEEDS" ]; then
+          echo "[deploy] seeds NOT APPLICABLE - config/service/integration-contract.json declares no PRODUCTION_LIKE seed for $DB_SCHEMA."
+        else
+          apply_mariadb_seeds_over_tcp "$DB_HOST" "$DB_PORT" "$DB_SCHEMA" $DB_SEEDS
+          echo "[deploy] seeds $DB_SCHEMA: $MARIADB_SEEDS_APPLIED applied (every deploy, no tracker)"
+        fi
       fi
 
       docker --config "$DOCKER_CONFIG_DIR" compose -f docker-compose.production.yml up -d

package/templates/business-service/Dockerfile

@@ -1,27 +1,60 @@
 # === Production stage (build with: --target production) ===
 FROM node:24-alpine AS production
 WORKDIR /app
-COPY package*.json ./
-RUN npm ci --omit=dev
-COPY . .
-# The manifest conformance check, inside the image that would be deployed
-# (confirmation biz-service-manifest 001 §3.1: "The same check runs in the
-# Dockerfile production stage, so an image with a finding is never built").
+# The identity the PROCESS runs as, and it is the same one in every environment:
+# "production is dev in the rights of the process". Until d.588 this stage
+# declared no USER at all, so a deployed service ran as root while its dev
+# container ran as 1000:1000 — measured 2026-09-17 on an image built from this
+# template, `docker run --rm <image> id` → uid=0(root) gid=0(root). Nobody had
+# decided that difference; it was what the file happened to say.
+#
+# `node` is the account node:24-alpine ships at uid 1000, gid 1000 (measured the
+# same day: `docker run --rm node:24-alpine id node` → uid=1000(node)
+# gid=1000(node)), so USER node here and `user: "1000:1000"` in both compose
+# files are two spellings of ONE identity, not two decisions.
 #
-# It is the CLI of @onlineapps/conn-orch-validator, which every service declares
-# under `dependencies` — measured across all eight biz repositories on
-# 2026-09-09 — so `npm ci --omit=dev` above installs it and this line needs
-# nothing the image does not already carry.
+# The line below runs while /app is still root's, because WORKDIR created it so,
+# and it does two things at once for that reason:
+#   * logs/ and conn-runtime/ are written at RUNTIME — @onlineapps/monitoring-core
+#     writes logs/app.<date>.log (its fileDirectory default) and ServiceWrapper
+#     writes conn-runtime/validation-proof.json on every boot. Both are excluded
+#     from the build context by .dockerignore, and in production /app is the
+#     image rather than a bind mount, so they exist only because this line
+#     creates them;
+#   * the handover of /app itself, after which every COPY carries --chown and
+#     nothing in the image belongs to uid 0.
+RUN mkdir -p /app/logs /app/conn-runtime && chown -R node:node /app
+USER node
+COPY --chown=node:node package*.json ./
+RUN npm ci --omit=dev
+COPY --chown=node:node . .
+# No conformance check here. From d.215b the stage ran `oa-validate`, on the
+# sentence of confirmation biz-service-manifest 001 §3.1 ("an image with a
+# finding is never built"); three later decisions took that away. 006 point 2
+# calls the run inside an image "information, never a gate" — which a non-zero
+# exit is not; 010 made the job `validate-uniform` run the COMPLETE uniform over
+# a real checkout in every pipeline, and again before the deploy; 011 settled
+# that a tree which is not a git checkout reports NOT RUN, never a verdict.
 #
-# The rows that read a platform file (the template, api/config/shared-env.json,
-# api/.nvmrc) report NOT RUN here and say so by name: an image has no workspace
-# above it. What runs is every row the repository itself answers, and one
-# finding of severity boot or deploy exits non-zero and fails the build.
-RUN node node_modules/@onlineapps/conn-orch-validator/src/cli/oa-validate.js .
+# What was left was a gate over a tree where the uniform cannot be answered: an
+# image has no workspace above it, no `.git`, and — once `.dockerignore` does its
+# job — no `README.md` and no `docker-compose*.yml` either. Measured 2026-09-17
+# over exactly that shape: NOT DEPLOYABLE, 10 findings, every one of them
+# "absent", exit 1. The deployability verdict is CI's; this stage builds.
 CMD ["node", "index.js"]
 
 # === Development stage (default) ===
 FROM node:24-alpine
 WORKDIR /app
-COPY package*.json ./
+# The same identity as the production stage — and here the directory is load
+# bearing for a second reason. docker-compose.yml gives the one-shot test runner
+# an anonymous volume at /app/conn-runtime so its validation proof never lands in
+# the file the running service reads, and docker seeds such a volume from the
+# IMAGE at that path. Measured 2026-09-17 with the path absent: docker created it
+# root:root and the runner's write failed with "Permission denied"; with the
+# directory present and owned by node, the volume inherits that ownership and the
+# write succeeds.
+RUN mkdir -p /app/logs /app/conn-runtime && chown -R node:node /app
+USER node
+COPY --chown=node:node package*.json ./
 CMD ["npm", "start"]

package/templates/business-service/README.md

@@ -9,15 +9,15 @@ Duty sections that apply:
 - `scripts`: S-TEST, S-ALL-C, S-INT-C, S-UNIT-C, S-COOKBOOKS, S-COOK-C, S-HOST, S-HOOKS
 - `tooling`: S-SCRIPTS
 - `config`: C-IDENTITY, C-SERVICE, C-OPS, C-CONTRACT, C-CONNECTORS, C-SERVICE-DEAD, C-ENV, G-SHARED-ENV, C-ENV-READS
-- `runtime`: R-NODE, R-MEM, R-PID1, R-PORTS-DEV, R-PORTS
-- `db`: D-DB-CONSISTENT, D-DB-COLLATION, D-DB-PACKAGE, D-DB-NAMING, D-DB-README, D-DB-ACCOUNT, D-DB-HEADERS
+- `runtime`: R-NODE, R-MEM, R-PID1, R-USER, R-PORTS-DEV, R-PORTS
+- `db`: D-DB-CONSISTENT, D-DB-COLLATION, D-DB-PACKAGE, D-DB-NAMING, D-DB-README, D-DB-ACCOUNT, D-DB-CI-ACCOUNT, D-DB-HEADERS
 - `docs`: C-LINT, D-PORT, D-NPM, D-SCRIPT, D-RETIRED, D-HEADER, D-LINT
 
 Paths a duty owns:
 
 - `.dockerignore`: F-DOCKERIGNORE (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/gitignore`)
 - `.gitignore`: F-GITIGNORE (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/gitignore`)
-- `.gitlab-ci.yml`: G-CI (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/.gitlab-ci.yml`)
+- `.gitlab-ci.yml`: G-CI (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/.gitlab-ci.yml`), D-DB-CI-ACCOUNT
 - `README.md`: G-README (from `./node_modules/@onlineapps/conn-orch-validator/manifests/biz-service.manifest.json`)
 - `config/biz-docs-lint.tree.json`: C-LINT
 - `config/env-templates`: C-ENV, D-DB-ACCOUNT
@@ -26,7 +26,7 @@ Paths a duty owns:
 - `config/service/integration-contract.json`: C-CONTRACT, D-DB-COLLATION
 - `config/service/operations.json`: C-OPS
 - `docker-compose.production.yml`: G-PROD (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/docker-compose.production.yml`), G-PROD-IMAGE, R-PORTS
-- `docker-compose.yml`: F-RUNNER (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/docker-compose.yml`), C-IDENTITY, R-MEM, R-PID1, R-PORTS-DEV
+- `docker-compose.yml`: F-RUNNER (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/docker-compose.yml`), C-IDENTITY, R-MEM, R-PID1, R-USER, R-PORTS-DEV
 - `docs/80-setup/`: G-SETUP
 - `docs/80-setup/INSTALL.md`: G-SETUP-INSTALL (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/docs/80-setup/INSTALL.md`)
 - `docs/80-setup/PLATFORM_MATRIX.md`: G-SETUP-MATRIX (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/docs/80-setup/PLATFORM_MATRIX.md`)
@@ -220,3 +220,41 @@ cgroup.
 Revise the service limit when this service exceeds 60% of it in operation,
 measured the way the norm was: cgroup `memory.stat:anon`, sampled inside the
 running container.
+
+## Process identity
+
+One identity, in every environment: the service process is **uid 1000, gid
+1000** — the `node` account of `node:24-alpine` — and it is never root.
+
+| Where | What says it |
+|---|---|
+| the image, both stages | `USER node` in `Dockerfile` |
+| dev container and test runner | `user: "1000:1000"` in `docker-compose.yml` |
+| production container | `user: "1000:1000"` in `docker-compose.production.yml` |
+
+Row `R-USER` of the uniform holds the two halves nothing else reaches — the
+production stage of the `Dockerfile` and the service node of `docker-compose.yml`.
+The runner line is inside the block `F-RUNNER` holds, and the production compose is
+`G-PROD`'s whole-file render, so neither is measured twice.
+
+Both halves are stated on purpose. The `Dockerfile` decides what the IMAGE is,
+the compose file decides what THIS deployment runs, and a rebuild that lost the
+`USER` would otherwise reach the box unnoticed. Until 2026-09-17 neither half
+existed for production: a `docker run --rm <image> id` on an image built from
+this template answered `uid=0(root)`, while the dev container beside it ran as
+1000 — a difference nobody had decided.
+
+The two directories the process writes at runtime, `logs/` (the log files
+`@onlineapps/monitoring-core` rotates) and `conn-runtime/` (the validation
+proof), are created in the image and belong to that account. In dev they are
+covered by the bind mount and belong to whoever owns the checkout; in production
+`/app` IS the image, so a directory nothing created is a directory nothing can
+write.
+
+The one-shot test runner gets a `conn-runtime/` of its own — an anonymous volume
+at `/app/conn-runtime` in its compose node. A validation proof is an assertion
+about ONE running instance, and with the plain `.:/app` mount the runner wrote
+its proof into the file the live service reads (measured in `api_biz/converter`,
+2026-09-16). Nothing else is separated: the runner keeps the same build, the
+same `env_file` and the same networks as the service, because that is what makes
+a suite measure what the service sees.

package/templates/business-service/config/env-templates/shared.env

@@ -13,7 +13,7 @@ LOG_MAX_SIZE_BYTES=52428800
 # How many rotated files of one log row the directory keeps - the other half of the size bound, and equally without a default in @onlineapps/monitoring-core 3.0.0 (src/logger.js REQUIRED_FILE_BOUNDS, src/config.js logMaxFiles). Ten files of LOG_MAX_SIZE_BYTES is the 500 MB per service the platform declares as its ceiling, so the two keys are read together and travel together (owner decision docs/governance/confirmations/log-file-bounds.md 001).
 LOG_MAX_FILES=10
 
-# The HMAC-SHA256 secret the gateway and auth sign and verify access tokens with; it is shared because both ends of one token must hold the same value (docs/standards/JWT_AUTH.md).
+# The HMAC-SHA256 secret the gateway and auth sign and verify access tokens with; it is shared because both ends of one token must hold the same value (docs/standards/JWT_AUTH.md). Four infrastructure services read the name, each at boot: api_gateway (infra/api_gateway/config/jwtSecret.js, assertJwtSecret), api_auth (infra/api_auth/config/bootEnv.js, assertJwtSecret), api_meta_reader and api_delivery_endpoint (both requireEnv('JWT_SECRET', ...) in src/config.js). In the business chain the key is carried, not read: no business service reads the name, and @onlineapps/service-common 3.0.0 takes the secret as an INPUT of verifyAccessToken(token, secret) and createJwtValidator({ secret }) and reads no environment variable at all (principle 1, CHANGELOG 3.0.0), so a business service could not use the value even if it were filled in. It reaches every bearer because the shared key set is ONE file whose every copy is byte-identical to the platform template (confirmation biz-service-manifest 003 §18), never because each bearer reads every key - which is why CHANGE_ME here is a real placeholder only on an infrastructure target.
 JWT_SECRET=CHANGE_ME
 
 # The ordered list of SecretBox master keys every process that resolves a secret reference decrypts with - entries of <key_id>:<base64 32-byte key> separated by commas, newest FIRST: the first entry seals every new write, every entry opens what it sealed (selected by the blob's own key_id), and a blob naming a key outside the list is refused rather than guessed at (owner decision docs/governance/confirmations/secretbox-master-keys.md 001). It is shared because one keyring has to reach every bearer at once - a rotation is a switch of this one list, and a service left on yesterday's list stops reading what its neighbour has already re-encrypted; the measured cost of the single key it replaces is six of ten rows of oagen_meta.secret unreadable for two weeks after the August 2026 rotation. The value is per-machine and lives only in config/env-active/shared.env. @onlineapps/conn-infra-secrets owns the name and the format and never reads the environment itself (principle 1): the bearer reads this key and hands the string to the connector.

package/templates/business-service/docker-compose.production.yml

@@ -33,6 +33,15 @@ services:
     # carries a digest, and an image built here would in any case not be the one
     # CI proved. Build locally through docker-compose.yml instead.
     container_name: __CONTAINER_NAME__
+    # The same uid:gid the dev compose pins, and the Dockerfile's production
+    # stage declares the same identity as USER node (node:24-alpine ships that
+    # account at uid 1000, gid 1000). Until d.588 neither file said anything
+    # here, so the deployed process was the one on the platform running as root
+    # — measured 2026-09-17, `docker run --rm <image> id` → uid=0(root).
+    # Both halves are stated on purpose: the Dockerfile decides what the image
+    # is, this line decides what THIS deployment runs, and a rebuild that lost
+    # the USER would otherwise reach the box unnoticed.
+    user: "1000:1000"
     deploy:
       resources:
         limits: