@onlineapps/conn-orch-validator 10.0.0 → 12.0.0

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

@@ -68,12 +68,24 @@ variables:
     # 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).
+    # WHERE the platform SSOT is read from. 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 STATE of that SSOT a run is measured against - two facts, two names
+    # (confirmation biz-service-manifest 012; 010 for the continuous run, 008
+    # point 3 for the binding one).
+    #
+    # The continuous gate judges the commit in front of it, so it measures
+    # against the branch the platform develops on - the same one the libraries
+    # SSOT is read from. api production moves only at the END of a production
+    # path, and pushing it deploys infra, so a continuous gate pointed there
+    # measures a months-old ref and goes red for a reason outside this
+    # repository (automation-gates.md §5).
+    API_UNIFORM_REF_CONTINUOUS: main
+    # The deploy confirms against what is being deployed, and the migration
+    # runner this job carries onto the box comes from that same clone.
+    API_UNIFORM_REF_DEPLOY: production
 
 # The uniform of THIS commit, on every pipeline - confirmation
 # biz-service-manifest 010. Entry 008 places the BINDING run before the SSH step
@@ -102,7 +114,7 @@ validate-uniform:
     # 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"
+    - 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_CONTINUOUS"
   rules:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
     - if: $CI_COMMIT_BRANCH == "main"
@@ -247,7 +259,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
-    - 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"
+    - 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_DEPLOY"
     # R1: refuse to deploy without the immutable target the build stage published.
     - |
       if [ -z "${BIZ_IMAGE_DIGEST:-}" ]; then
@@ -288,6 +300,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 +364,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 +375,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 +413,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 +465,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 +486,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_DEPLOY, 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_DEPLOY 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 +527,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:

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/scripts/verify-deploy-uniform.sh

@@ -32,7 +32,8 @@
 # WHY THREE ARGUMENTS AND NOTHING FROM THE ENVIRONMENT. The script knows what to
 # measure, never where the pieces come from (`architecture-principles.md` §1):
 # the job passes the checkout GitLab made, the api repository URL carrying its
-# job token, and the api ref that production follows. Nothing here reads
+# job token, and the api ref THAT job measures against (the continuous job and
+# the deploy job name different ones - confirmation biz-service-manifest 012). Nothing here reads
 # `process.env`, so the same invocation is reproducible outside CI.
 #
 # THE LAYOUT IT NEEDS, AND WHY THE JOB HAS TO ASK FOR IT. The engine answers the
@@ -69,7 +70,7 @@ API_URL="$2"
 API_REF="$3"
 
 [ -n "$API_URL" ] || die "The api repository URL is empty - the uniform reads the platform SSOT from that checkout, and this script does not guess where it lives. Expected: the URL the job builds from CI_JOB_TOKEN. Fix: pass it as the second argument." 2
-[ -n "$API_REF" ] || die "The api ref is empty - which state of the platform this deploy is measured against is a decision, not a default. Expected: the branch production follows. Fix: pass it as the third argument." 2
+[ -n "$API_REF" ] || die "The api ref is empty - which state of the platform this deploy is measured against is a decision, not a default. Expected: the ref the calling job declares (API_UNIFORM_REF_CONTINUOUS for validate-uniform, API_UNIFORM_REF_DEPLOY for deploy-production). Fix: pass it as the third argument." 2
 [ -d "$SERVICE_ROOT" ] || die "Service root not found - '$SERVICE_ROOT' is not an existing directory. Expected: the checkout being deployed. Fix: pass \$CI_PROJECT_DIR." 2
 
 SERVICE_ROOT=$(cd "$SERVICE_ROOT" && pwd)