@onlineapps/conn-orch-validator 9.0.0 → 11.0.0

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

@@ -2,19 +2,28 @@
 # Written by @onlineapps/conn-orch-validator (row G-CI of
 # manifests/biz-service.manifest.json). The PLATFORM half of this pipeline: which
 # pipelines run at all, how a service is built, how its image is identified (R5),
-# how the digest reaches the deploy (R1/R2), the uniform gate that runs before
-# the SSH step (confirmation biz-service-manifest 008) and the post-deploy gate
-# that runs after it (confirmation deploy-gate-targets 003). The installation
-# contract is checked by that uniform gate, in the manifest rows G-SETUP,
-# D-DB-PACKAGE and D-DB-HEADERS, and no longer by a job of its own (d.470).
-# npx oa-sync-template .gitlab-ci.yml --target . rewrites everything between
-# these two markers and nothing outside them.
+# how the digest reaches the deploy (R1/R2), the uniform gate that runs on every
+# pipeline (job validate-uniform, confirmation biz-service-manifest 010) and
+# again before the SSH step as the binding instance (008), and the post-deploy
+# gate that runs after it (confirmation deploy-gate-targets 003). The
+# installation contract is checked by that uniform gate, in the manifest rows
+# G-SETUP, D-DB-PACKAGE and D-DB-HEADERS, and no longer by a job of its own
+# (d.470). npx oa-sync-template .gitlab-ci.yml --target . rewrites everything
+# between these two markers and nothing outside them.
 #
 # Outside them is this repository's own: its test job - which database, which
 # ci:gate:* steps and which artefacts its integration needs is a fact about the
 # service - and whatever else it runs. The stages this block declares (test,
 # build, secret-detection, deploy) cover those jobs too; measured over the eight
 # biz repositories on 2026-09-11, none declares a fifth stage.
+#
+# One thing the platform can only RECOMMEND about that half, because it does not
+# own it: give the service's own jobs the `devel` branch as well. The post-commit
+# mirror pushes every commit there, and a `rules:` list naming only main,
+# production and merge requests is why that branch produced no pipeline at all
+# (010 point 2). The block does its side of it - validate-uniform and
+# secret_detection run on devel; whether a service's own test job should too is
+# the service's call.
 include:
   - template: Jobs/Secret-Detection.gitlab-ci.yml
 
@@ -33,6 +42,73 @@ variables:
   IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
   IMAGE_LATEST: $CI_REGISTRY_IMAGE:latest
 
+# The layout and the runtime every uniform run needs, declared ONCE for the two
+# jobs that run it: the continuous check below and the binding one in
+# deploy-production (confirmations biz-service-manifest 008 and 010). A hidden
+# key is a declaration and never a job - GitLab runs nothing whose name starts
+# with a dot - so this adds no gate, it gives the two that exist one source.
+.oa-uniform:
+  # The uniform runs in these jobs, so they need the runtime the pinned engine
+  # declares - the same major the test stage and the Dockerfile carry, which is
+  # what R3 of the deploy contract compares.
+  image: node:24-alpine
+  variables:
+    # The engine answers the rows that read the platform SSOT only for a service
+    # lying at <root>/api_biz/<service> beside <root>/api. GitLab decides where a
+    # project is checked out, so the job ASKS for the one place that IS that
+    # layout - no symlink (api rule: No Symlinks) and no second copy of this
+    # repository, which would leave two trees and no way to tell which one the
+    # verdict was about. Needs [runners.custom_build_dir] enabled on the runner.
+    #
+    # $CI_CONCURRENT_ID is the runner's slot number, and it is what keeps two
+    # pipelines of this project off each other's tree. Since 010 the uniform runs
+    # on EVERY pipeline, so two of them on one runner is the ordinary case: with
+    # one shared path the second run either refuses on an api clone it did not
+    # make, or measures the one the first run is still replacing. The slot sits
+    # ABOVE api_biz, so the sibling api/ still lands beside this checkout, which
+    # is the layout verify-deploy-uniform.sh checks.
+    GIT_CLONE_PATH: $CI_BUILDS_DIR/oa-uniform/$CI_CONCURRENT_ID/api_biz/__SERVICE_NAME__
+    # Where the platform SSOT is read from, and which state of it a run is
+    # measured against. Read access is granted by the api project's CI job-token
+    # allowlist - the owner's step, outside any repository (confirmation
+    # biz-service-manifest 008 point 2).
+    API_PROJECT_PATH: onlineapps/oadrive/infra-mono
+    API_UNIFORM_REF: production
+
+# The uniform of THIS commit, on every pipeline - confirmation
+# biz-service-manifest 010. Entry 008 places the BINDING run before the SSH step
+# of a production deploy; it never said that is the only place it runs, and read
+# that way it left a service unmeasured between two deploys. Measured on
+# biz-converter 2026-09-16: no job ran the uniform outside the deploy job, the
+# post-commit mirror pushed every commit to origin/devel and pipelines?ref=devel
+# answered 0, and the last pipeline on main was 13 days old. So the same gate,
+# the same bytes and the same arguments run here too, on a merge request, on
+# main, on the devel mirror and on production - and the deploy job keeps its own
+# run as the last, binding instance.
+validate-uniform:
+  stage: test
+  extends: .oa-uniform
+  before_script:
+    # git: the gate clones api read-only beside this checkout. npm ci: the gate
+    # and the engine it runs are BOTH the ones this repository pinned, so the
+    # version measured is the version this service proved - never a floating
+    # download.
+    - apk add --no-cache git
+    - npm ci
+  script:
+    # The same invocation deploy-production makes. The script is not this
+    # repository's own file: no biz repository carries it (measured over all
+    # eight, 2026-09-16), and a copy generated into eight of them would be a
+    # second place to keep in step (change-discipline.md - One rail per
+    # concern). It comes from the package this repository pins, beside the
+    # engine it runs.
+    - sh node_modules/@onlineapps/conn-orch-validator/templates/business-service/scripts/verify-deploy-uniform.sh "$CI_PROJECT_DIR" "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/${API_PROJECT_PATH}.git" "$API_UNIFORM_REF"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_BRANCH == "devel"
+    - if: $CI_COMMIT_BRANCH == "production"
+
 build:
   stage: build
   image: docker:24
@@ -72,28 +148,18 @@ secret_detection:
   rules:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
     - if: $CI_COMMIT_BRANCH == "main"
+    # The mirror branch too (010 point 2): a secret pushed there is pushed.
+    - if: $CI_COMMIT_BRANCH == "devel"
     - if: $CI_COMMIT_BRANCH == "production"
 
 deploy-production:
   stage: deploy
-  # The uniform runs here (confirmation biz-service-manifest 008), so the job
-  # needs the runtime the pinned engine declares — the same major the test stage
-  # and the Dockerfile carry, which is what R3 of the deploy contract compares.
-  image: node:24-alpine
+  # The BINDING uniform run happens here, before the SSH step (confirmation
+  # biz-service-manifest 008). The runtime it needs and the layout it is
+  # measured in are the shared declaration above - the same one validate-uniform
+  # reads, so the two runs cannot be measuring different things.
+  extends: .oa-uniform
   variables:
-    # The engine answers the rows that read the platform SSOT only for a service
-    # lying at <root>/api_biz/<service> beside <root>/api. GitLab decides where a
-    # project is checked out, so the job ASKS for the one place that IS that
-    # layout — no symlink (api rule: No Symlinks) and no second copy of this
-    # repository, which would leave two trees and no way to tell which one the
-    # verdict was about. Needs [runners.custom_build_dir] enabled on the runner.
-    GIT_CLONE_PATH: $CI_BUILDS_DIR/oa-uniform/api_biz/__SERVICE_NAME__
-    # Where the platform SSOT is read from, and which state of it a production
-    # deploy is measured against. Read access is granted by the api project's CI
-    # job-token allowlist — the owner's step, outside any repository
-    # (confirmation biz-service-manifest 008 point 2).
-    API_PROJECT_PATH: onlineapps/oadrive/infra-mono
-    API_UNIFORM_REF: production
     # Which checks judge this deploy. The gate has no default target: the job
     # declares what it is measured by (confirmation deploy-gate-targets 002),
     # and the name is the service's registry identity — the one
@@ -181,7 +247,7 @@ deploy-production:
     # not look everywhere, and nothing reaches the box. There is no flag and no
     # variable that turns this off (automation-gates.md §1 requirement 5).
     - npm ci
-    - scripts/verify-deploy-uniform.sh "$CI_PROJECT_DIR" "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/${API_PROJECT_PATH}.git" "$API_UNIFORM_REF"
+    - sh node_modules/@onlineapps/conn-orch-validator/templates/business-service/scripts/verify-deploy-uniform.sh "$CI_PROJECT_DIR" "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/${API_PROJECT_PATH}.git" "$API_UNIFORM_REF"
     # R1: refuse to deploy without the immutable target the build stage published.
     - |
       if [ -z "${BIZ_IMAGE_DIGEST:-}" ]; then
@@ -222,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.
     #
@@ -248,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"
@@ -259,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.
@@ -289,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
@@ -314,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
@@ -337,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
@@ -369,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

@@ -6,27 +6,27 @@ Every `api_biz/*/package.json` that `api/config/services.json` lists wears it (`
 Duty sections that apply:
 
 - `files`: F-INIT, F-JEST, F-RUNNER, F-GITIGNORE, F-DOCKERIGNORE, G-PROD, G-CI, G-PROD-IMAGE, G-README, G-SETUP, G-SETUP-INSTALL, G-SETUP-MATRIX, G-SETUP-VALIDATION, X-IGNORED, X-HOOKS, X-PREVAL, X-DB-CONFIG
-- `scripts`: S-TEST, S-ALL-C, S-INT-C, S-COOKBOOKS, S-HOST, S-HOOKS
+- `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
-- `config/env-templates/shared.env`: G-SHARED-ENV (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/config/env-templates/shared.env`)
+- `config/env-templates/shared.env`: G-SHARED-ENV (from `api/config/shared-env.json`)
 - `config/service/config.json`: C-SERVICE
 - `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`)
@@ -125,7 +125,7 @@ own memory budget, so a heavy suite can no longer be killed together with the
 service, and the `test` profile keeps it out of a plain `docker compose up`.
 
 ```bash
-npm run test:container       # unit suite, in the runner
+npm run test:unit:container  # unit suite, in the runner
 npm run test:all:container   # everything test:all chains, in the runner
 ```
 
@@ -141,14 +141,23 @@ the `Dockerfile` or to the dependencies:
 docker compose --profile test build
 ```
 
-Without it the next `npm run test:container` runs the image the runner was last
+Without it the next `npm run test:unit:container` runs the image the runner was last
 built from, and a suite then passes or fails on code that is no longer in this
 repository — a green run that says nothing about what is committed.
 
+`jest.config.js` is held byte for byte by row `F-JEST`, so a local
+`setupFiles` entry pointing at a `tests/setup-env.js` of your own does not
+survive a sync — and does not need to. What a suite needs from the environment it
+gets from the runner's `env_file`, the same files the service itself loads, which
+is why the runner exists at all; a setup file that put those names into
+`process.env` would be a second, quieter source for them
+(`.claude/rules/change-discipline.md` § One rail per concern). A suite that needs
+a value nothing declares says so by failing on the name, which is the point.
+
 `npm test` and `npm run test:unit` are what runs INSIDE that container; the
 runner is the one rail a suite runs on (owner decision
 `api/docs/governance/confirmations/biz-test-container.md` 001, and manifest rows
-`S-ALL-C` and `S-HOST`). Running them on the host is not a second, quicker way
+`S-UNIT-C`, `S-ALL-C`, `S-COOK-C` and `S-HOST`). Running them on the host is not a second, quicker way
 to the same answer: the host has neither the service's `env_file` nor its
 network, so what fails there says nothing about the service — which is why no
 `test:host` script exists and why the uniform forbids one.
@@ -211,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/__SERVICE_NAME__.env

@@ -1,7 +1,12 @@
 # __SERVICE_NAME__ environment
 # Copy to config/env-active/__SERVICE_NAME__.env and adjust values.
-
-SERVICE_NAME=__SERVICE_NAME__
+#
+# The service's own name is NOT here. config/service/config.json declares it and
+# ServiceWrapper._serviceName() reads it there, passing it on to monitoring and
+# to the MQ client; an env key repeating it would be a second bearer of one fact,
+# and the copies measured on 2026-09-16 had already drifted from it (the template
+# rendered the short name, every live file the registry name). Row C-IDENTITY
+# holds every spelling in this repository to config/service/config.json.
 
 # Schema migrations at deploy time. The deploy job (block `oa-ci v1` of
 # .gitlab-ci.yml) runs api/scripts/lib/mariadb-migrations.sh between `compose
@@ -15,8 +20,15 @@ SERVICE_NAME=__SERVICE_NAME__
 #
 # Commented out because this scaffold has no database: its
 # config/service/integration-contract.json declares no `database` block, the
-# deploy step prints NOT APPLICABLE and reads neither name. A service that
-# declares that block uncomments both here and fills the values in
-# config/env-active/ only - per machine, never in git.
+# deploy step prints NOT APPLICABLE and reads neither name.
+#
+# Where the values live is the host contract, not a choice: the deploy job reads
+# config/env-active/<service>.env ON THE BOX, so a service that declares a
+# `database` block uncomments both names HERE (the template, in git, values
+# empty) and fills them in config/env-active/ on each machine - never in git. The
+# account itself is not created by any of this: on a first deployment the owner
+# of the box creates the schema and the service account by hand from the runbook,
+# and the migration runner then runs under that account (db-migrations-first-deploy
+# 001, phase 1).
 # MARIADB_MIGRATION_USER=
 # MARIADB_MIGRATION_PASSWORD=

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

@@ -4,10 +4,16 @@
 # The runtime environment name every platform library resolves through its own runtime-config schema; without it a library cannot say which environment it is reporting from.
 NODE_ENV=development
 
-# The log level an infra service's config/logging.json resolves through ${LOG_LEVEL}; one platform value so a stack does not log at four different levels.
+# The log level an infrastructure service's config/logging.json resolves through ${LOG_LEVEL}; one platform value so a stack does not log at a different level in every service. In the business chain the key is carried, not read: no library in the business chain reads it - @onlineapps/monitoring-core reads no environment variable at all (principle 1) and takes its level from the config the service hands it - so setting it on a business service changes nothing. 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.
 LOG_LEVEL=info
 
-# 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).
+# How large one log file may grow before @onlineapps/monitoring-core rotates it (src/logger.js REQUIRED_FILE_BOUNDS, src/config.js logMaxSize). From monitoring-core 3.0.0 the bound has no default in code, so a service that declares it nowhere fails at logger construction by design, and the value has to be declared - it is shared because the ceiling is a property of the box every service writes onto, not a preference of one service: the age bound LOG_MAX_DAYS alone let a single day's file fill the disk (hello wrote 2.4 GB/day before d.383). The platform value is 50 MB, the same in dev and production (owner decision docs/governance/confirmations/log-file-bounds.md 001).
+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). 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:

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

@@ -80,6 +80,23 @@ services:
     mem_limit: 1g
     volumes:
       - .:/app
+      # The runner's OWN conn-runtime, and the reason it is a volume rather than
+      # a second bind mount. `conn-runtime/validation-proof.json` is an assertion
+      # about ONE running instance
+      # (docs/biz/50-lifecycle/validation-responsibilities.md § Data Flow), and
+      # with `.:/app` alone the runner writes it into the directory the SERVICE
+      # reads — measured in api_biz/converter on 2026-09-16, where a proof
+      # produced by a probe schema stood in the place of the service's own.
+      #
+      # ANONYMOUS on purpose: F-RUNNER holds this block and
+      # `oa-sync-template docker-compose.yml` writes this block and nothing else,
+      # so a named volume would reach every service without the top-level
+      # `volumes:` key that declares it and `docker compose config` would refuse
+      # the document. Docker seeds the volume from the IMAGE at that path, which
+      # is why the Dockerfile's development stage creates /app/conn-runtime and
+      # gives it to uid 1000 — without that, docker creates it root-owned and the
+      # runner cannot write it at all.
+      - /app/conn-runtime
     env_file:
       - ./config/env-active/shared.env
       - ./config/env-active/__SERVICE_NAME__.env

package/templates/business-service/docs/80-setup/PLATFORM_MATRIX.md

@@ -24,7 +24,7 @@ the service.
 
   ```bash
   docker compose up -d --build
-  npm run test:container
+  npm run test:unit:container
   npm run test:cookbooks:container
   ```