@onlineapps/conn-orch-validator 6.0.1 → 8.0.0

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

@@ -0,0 +1,290 @@
+# --- oa-ci v1
+# 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), that the installation document and
+# the migrations still agree, 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). 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.
+include:
+  - template: Jobs/Secret-Detection.gitlab-ci.yml
+
+workflow:
+  name: "$CI_PROJECT_NAME — $CI_COMMIT_BRANCH [$CI_PIPELINE_SOURCE]"
+
+stages:
+  - test
+  - build
+  - secret-detection
+  - deploy
+
+variables:
+  # R5: one commit-sha scheme across the platform — the FULL sha, the way infra
+  # tags. Two lengths would mean two schemes and the release manifest needs one.
+  IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+  IMAGE_LATEST: $CI_REGISTRY_IMAGE:latest
+
+verify-installation-contract:
+  stage: test
+  image: alpine:latest
+  script:
+    - sh scripts/verify-installation-docs-sql-contract.sh
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_BRANCH == "production"
+
+build:
+  stage: build
+  image: docker:24
+  services:
+    - docker:24-dind
+  script:
+    # A password on a command line stands in the runner's process table for the
+    # length of the build and in every trace that echoes the command. The deploy
+    # host's own login has read it from stdin since it was written; both ends of
+    # one login now agree.
+    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
+    - docker build --target production -t $IMAGE -t $IMAGE_LATEST .
+    - docker push $IMAGE
+    - docker push $IMAGE_LATEST
+    # R1: the deploy target is the digest, and it exists only after the push.
+    - |
+      # --format is not honoured by the buildx on the runner: it prints the whole
+      # descriptor (Name/MediaType/Digest), so the digest would be captured
+      # multi-line and build.env rejected as an invalid dotenv artifact. Parse
+      # the Digest field.
+      BIZ_IMAGE_DIGEST=$(docker buildx imagetools inspect "$IMAGE" | awk '/^Digest:/ { print $2; exit }')
+      if ! printf '%s' "$BIZ_IMAGE_DIGEST" | grep -qE '^sha256:[0-9a-f]{64}$'; then
+        echo "[build] FATAL: no valid digest resolved for $IMAGE - got '$BIZ_IMAGE_DIGEST', expected sha256:<64 hex>. The deploy would have no immutable target. Fix: confirm the push succeeded and that buildx can read $CI_REGISTRY." >&2
+        exit 1
+      fi
+      echo "[build] $IMAGE -> $BIZ_IMAGE_DIGEST"
+      echo "BIZ_IMAGE_DIGEST=$BIZ_IMAGE_DIGEST" > build.env
+  artifacts:
+    reports:
+      dotenv: build.env
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_BRANCH == "production"
+
+secret_detection:
+  stage: secret-detection
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+    - 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
+  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
+    # api/config/services.json carries and the contract files its target under.
+    DEPLOY_GATE_TARGETS: "biz:__REGISTRY_NAME__"
+  before_script:
+    # Preconditions first, before anything is installed or deployed
+    # (automation-gates.md §1 requirement 4). The post-deploy gate reads the
+    # heartbeat projection on the INFRA box as its own read-only account
+    # (confirmation deploy-gate-targets 003 point 3); without that identity this
+    # job could deploy a service and then not verify it, which is exactly the
+    # false guarantee §5 of the same rule names. So it refuses instead, and
+    # there is no branch on which the gate is skipped (§1 requirement 5).
+    - |
+      # gate-identity-check
+      missing=""
+      [ -n "${GATE_INFRA_HOST:-}" ] || missing="$missing GATE_INFRA_HOST"
+      [ -n "${GATE_INFRA_USER:-}" ] || missing="$missing GATE_INFRA_USER"
+      [ -n "${GATE_INFRA_SSH_PRIVATE_KEY:-}" ] || missing="$missing GATE_INFRA_SSH_PRIVATE_KEY"
+      if [ -n "$missing" ]; then
+        echo "[deploy] FATAL: the post-deploy gate has no identity on the infra box - missing CI variable(s):$missing. Expected: the group-level variables GATE_INFRA_HOST, GATE_INFRA_USER and GATE_INFRA_SSH_PRIVATE_KEY (base64 ed25519 private key of the gate-reader account). Fix: set them in GitLab > Group > Settings > CI/CD > Variables, and install the account on the infra box with api/scripts/provision/gate-reader-install.sh (confirmation deploy-gate-targets 003 point 3)." >&2
+        exit 1
+      fi
+      # end gate-identity-check
+    - |
+      # host-key-check
+      # An ssh that accepts whatever key answers on an address hands the deploy
+      # key, the registry password and the gate-reader key to whoever answered.
+      # Both boxes are therefore pinned from a CI variable, and a missing pin
+      # stops the job HERE, before anything is installed and before the first
+      # connection - never a fallback to accepting the unknown
+      # (automation-gates.md §1 requirements 4 and 5, §2).
+      if [ -z "${DEPLOY_HOST_KEY:-}" ]; then
+        echo "[deploy] Missing CI variable - DEPLOY_HOST_KEY is the ssh-keyscan line of the biz box DEPLOY_HOST ($DEPLOY_HOST), which this job deploys to over ssh. Fix: on a machine that already trusts that box run 'ssh-keyscan -t ed25519 $DEPLOY_HOST' and set its whole output line as DEPLOY_HOST_KEY in GitLab > Group > Settings > CI/CD > Variables." >&2
+        exit 1
+      fi
+      if [ -z "${GATE_INFRA_HOST_KEY:-}" ]; then
+        echo "[deploy] Missing CI variable - GATE_INFRA_HOST_KEY is the ssh-keyscan line of the infra box GATE_INFRA_HOST ($GATE_INFRA_HOST), which the post-deploy gate reads the heartbeat projection from. Fix: on a machine that already trusts that box run 'ssh-keyscan -t ed25519 $GATE_INFRA_HOST' and set its whole output line as GATE_INFRA_HOST_KEY in GitLab > Group > Settings > CI/CD > Variables." >&2
+        exit 1
+      fi
+      # end host-key-check
+    # openssh-client and git for the two SSH steps and the api checkout the
+    # uniform reads; bash, jq and curl for the post-deploy gate — it declares
+    # bash>=4 (declare -A), reads the contract with jq and submits a workflow
+    # smoke with curl. No docker: in remote mode every docker call is carried to
+    # the box that holds the fact, over ssh.
+    - apk add --no-cache openssh-client git bash jq curl
+    - mkdir -p ~/.ssh
+    - echo "$SSH_PRIVATE_KEY" | base64 -d > ~/.ssh/deploy_key
+    - chmod 600 ~/.ssh/deploy_key
+    - echo "$GATE_INFRA_SSH_PRIVATE_KEY" | base64 -d > ~/.ssh/gate_infra_key
+    - chmod 600 ~/.ssh/gate_infra_key
+    # The identity of the two boxes, pinned. Written before the config that
+    # demands it, so no ordering makes the demand unsatisfiable.
+    - echo "$DEPLOY_HOST_KEY" > ~/.ssh/known_hosts
+    - echo "$GATE_INFRA_HOST_KEY" >> ~/.ssh/known_hosts
+    - chmod 644 ~/.ssh/known_hosts
+    # Two boxes, two identities, and neither key is ever offered to the other
+    # box: the deploy key opens the biz box, the gate-reader key the infra box.
+    # ssh_config keeps the FIRST value it finds for a keyword, so the host
+    # blocks come before the catch-all and the catch-all carries only the
+    # host-key policy - which is where it belongs rather than on a command line:
+    # the post-deploy gate this job runs at the end (see its invocation below)
+    # opens its own ssh connections inside the script, and takes no ssh flags
+    # from here, so a policy written per-command would cover the deploy step and
+    # leave the gate connecting to anything that answered.
+    - |
+      {
+        echo "Host $DEPLOY_HOST"
+        echo "  IdentityFile ~/.ssh/deploy_key"
+        echo "  IdentitiesOnly yes"
+        echo "Host $GATE_INFRA_HOST"
+        echo "  IdentityFile ~/.ssh/gate_infra_key"
+        echo "  IdentitiesOnly yes"
+        echo "Host *"
+        echo "  StrictHostKeyChecking yes"
+        echo "  UserKnownHostsFile ~/.ssh/known_hosts"
+      } > ~/.ssh/config
+  dependencies:
+    - build
+  script:
+    # The uniform of this checkout, complete, BEFORE anything is deployed
+    # (confirmation biz-service-manifest 006 point 3, refined by 008): deploy is
+    # confirmation, never discovery. One blocking finding, or a run that could
+    # 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"
+    # R1: refuse to deploy without the immutable target the build stage published.
+    - |
+      if [ -z "${BIZ_IMAGE_DIGEST:-}" ]; then
+        echo "[deploy] FATAL: BIZ_IMAGE_DIGEST is empty - the build stage publishes it as a dotenv artifact. Refusing to deploy without an immutable image target." >&2
+        exit 1
+      fi
+    - echo "Deploying $BIZ_IMAGE_DIGEST to $DEPLOY_HOST ($CI_ENVIRONMENT_URL)"
+    # DEPLOY_PATH / DEPLOY_HOST / DEPLOY_USER are CI variables: the box decides
+    # where its checkout lives, and no path is baked into this file.
+    #
+    # The registry password travels on STDIN and nowhere else. As an argument of
+    # the remote `bash -s` it stood in the deploy host's process table for the
+    # whole deploy, readable by every account on that box, and in this runner's
+    # argv besides. So the stream the remote shell reads is the password's line
+    # first and the script after it: the remote reads that one line, exports it,
+    # and hands the rest of the stream to `bash -s` - ssh's stdin is a socket
+    # there, so `read` consumes exactly the line and no more.
+    - |
+      {
+        printf '%s\n' "$CI_REGISTRY_PASSWORD"
+        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'"
+      set -euo pipefail
+      DEPLOY_PATH="$1"
+      REGISTRY="$2"
+      REGISTRY_USER="$3"
+      PROJECT_SLUG="$4"
+      export BIZ_IMAGE_DIGEST="$5"
+      PROJECT_PATH="$6"
+      # REGISTRY_PASSWORD arrives in the environment, from the first line of this
+      # script's own stdin. Empty means the runner had no CI_REGISTRY_PASSWORD:
+      # the pull would fail later with an authentication error that names nothing.
+      if [ -z "${REGISTRY_PASSWORD:-}" ]; then
+        echo "[deploy] FATAL: REGISTRY_PASSWORD is empty - it is read from the first line of this script's own stdin, before bash -s. Expected: CI_REGISTRY_PASSWORD set on the runner. Fix: check the job's CI variables; refusing to deploy without a registry login." >&2
+        exit 1
+      fi
+      DOCKER_CONFIG_DIR="$HOME/.docker-ci/${PROJECT_SLUG}"
+
+      # Onboarding a new biz service must not require a step on the server —
+      # owner decision api/docs/governance/confirmations/server-topology.md 004.
+      # The first deploy therefore creates the checkout itself; the deploy user
+      # holds a read key for every biz repository.
+      if [ ! -d "$DEPLOY_PATH/.git" ]; then
+        echo "[deploy] $DEPLOY_PATH holds no checkout - cloning git@gitlab.com:${PROJECT_PATH}.git"
+        git clone "git@gitlab.com:${PROJECT_PATH}.git" "$DEPLOY_PATH"
+      fi
+
+      cd "$DEPLOY_PATH"
+      # 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
+      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
+      docker --config "$DOCKER_CONFIG_DIR" compose -f docker-compose.production.yml up -d
+      REMOTE
+    # The deploy is not finished until the platform's own post-deploy gate says
+    # the service is alive: the heartbeat projection is present, UP and fresh,
+    # and the container's RestartCount has not moved over the window
+    # (confirmations deploy-gate-targets 003, deploy-gate-restart-count 001).
+    # The two facts sit on two boxes and this runner is a third, so the gate
+    # runs in remote mode — same script, same contract, same verdicts as a local
+    # run, only reading over ssh.
+    - |
+      # The gate runs out of the read-only api clone the uniform step already
+      # made beside this checkout. Derived from CI_PROJECT_DIR rather than
+      # spelled out a second time: the layout is declared once, in
+      # GIT_CLONE_PATH, so the two cannot drift apart.
+      API_CHECKOUT="$(dirname "$(dirname "$CI_PROJECT_DIR")")/api"
+      bash "$API_CHECKOUT/scripts/run-post-deploy-gate.sh" \
+        --target "$DEPLOY_GATE_TARGETS" \
+        --biz-host "$DEPLOY_USER@$DEPLOY_HOST" \
+        --infra-host "$GATE_INFRA_USER@$GATE_INFRA_HOST" \
+        --contract "$API_CHECKOUT/config/deploy-smoke-contract.json"
+  environment:
+    name: production
+    url: https://api.onlineapps.cz
+  rules:
+    - if: $CI_COMMIT_BRANCH == "production"
+# --- end oa-ci v1
+
+test:
+  stage: test
+  image: node:24-alpine
+  variables:
+    RABBITMQ_URL: "amqp://localhost:5672"
+    REGISTRY_URL: "http://localhost:33100"
+    NODE_ENV: "test"
+  script:
+    - npm ci
+    - npm run test:ci
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_BRANCH == "production"

package/templates/business-service/Dockerfile

@@ -0,0 +1,27 @@
+# === 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").
+#
+# 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 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 .
+CMD ["node", "index.js"]
+
+# === Development stage (default) ===
+FROM node:24-alpine
+WORKDIR /app
+COPY package*.json ./
+CMD ["npm", "start"]

package/templates/business-service/README.md

@@ -0,0 +1,213 @@
+<!-- BEGIN GENERATED: biz-service-uniform — regenerate: npx oa-sync-template readme-uniform --target . -->
+Uniform: [biz-service](./node_modules/@onlineapps/conn-orch-validator/manifests/biz-service.manifest.json)
+
+Every `api_biz/*/package.json` that `api/config/services.json` lists wears it (`U-ORPHAN`, `U-IDENTITY`).
+
+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
+- `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
+- `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`)
+- `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/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
+- `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`)
+- `docs/80-setup/VALIDATION.md`: G-SETUP-VALIDATION (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/docs/80-setup/VALIDATION.md`)
+- `hooks/pre-commit`: X-HOOKS
+- `init.sh`: F-INIT (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/init.sh`)
+- `jest.config.js`: F-JEST (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/jest.config.js`)
+- `migrations/`: D-DB-PACKAGE, D-DB-NAMING, D-DB-HEADERS
+- `migrations/README.md`: D-DB-README
+- `scripts/`: S-SCRIPTS
+- `scripts/run-pre-validation.js`: X-PREVAL
+- `src/config/database.js`: X-DB-CONFIG
+<!-- END GENERATED: biz-service-uniform -->
+
+# __SERVICE_NAME__
+
+__SERVICE_DESCRIPTION__
+
+## Quick Start
+
+```bash
+# 1. Copy env templates
+cp config/env-templates/shared.env config/env-active/shared.env
+cp config/env-templates/service.env config/env-active/__SERVICE_NAME__.env
+
+# 2. Edit config/env-active/ files with actual values
+
+# 3. Start (dev)
+docker compose up -d --build
+
+# 4. Start (production) — the image is pinned by digest, so it is PULLED, never
+#    built here: `docker build` refuses a tag that carries a digest. CI publishes
+#    the value; a manual run has to name the digest it wants.
+BIZ_IMAGE_DIGEST=sha256:… docker compose -f docker-compose.production.yml pull
+BIZ_IMAGE_DIGEST=sha256:… docker compose -f docker-compose.production.yml up -d
+```
+
+On the production biz box the second env file the compose references is
+`../shared.env` — ONE host-level file per box, at
+`/var/www/html/oadrive/api_biz/shared.env`. It is rendered on the infra box by
+`api/scripts/provision/render-biz-shared-env.sh` and carried over by the
+operator; this compose references it and never copies it (owner decision
+`api/docs/governance/confirmations/server-topology.md` 004 and 005).
+The network there is the external `biz_network`, also created by role-biz. The
+dev arrangement above is a single host and keeps its own
+`config/env-active/shared.env`.
+
+## Structure
+
+```
+config/
+├── service/          # Service metadata (config.json, operations.json)
+├── env-templates/    # Versioned env templates
+└── env-active/       # Runtime env (gitignored)
+src/
+└── handlers/v3/      # One module per operation; the handler: field points here
+tests/
+├── unit/
+└── cookbooks/        # Tier-1 cookbooks, one per operation
+index.js              # Entry point (bootstrap)
+```
+
+There is **no** `src/app.js`, **no** `src/routes/` and no HTTP framework in
+`package.json`: a biz container binds no port, and an operation is reached
+through the `handler:` field in `operations.json` — ADR 0005,
+`api/docs/biz/80-decisions/0005-no-http-in-biz-containers.md`, with the testable
+form of it in `api/docs/biz/00-model/service-shape.md` § No-HTTP tests. Business
+logic goes into `src/handlers/v3/`, the layout `api_biz/hello-service/src/` uses
+— see `api/docs/biz/60-templates/service-template.md` § Expected Structure.
+(Paths are relative to the workspace root, because this README is copied into a
+sibling repository where a link relative to `api/` would not resolve.)
+
+## The example operation
+
+The template ships one working operation, `echo`, so a new service starts from a
+shape that already passes. Three files describe it, and replacing the operation
+means replacing all three together:
+
+| File | States |
+|---|---|
+| `config/service/operations.json` | the contract — `handler`, `bundle_scope`, `mutates`, `input`/`output` schemas |
+| `src/handlers/v3/echo.js` | the behaviour — `echo(input, ctx)`, returning a value |
+| `tests/cookbooks/echo.json` | the Tier-1 assertion — calls the operation and asserts the output BY VALUE |
+
+`echo` is deliberately total and deterministic, which is what lets the cookbook
+assert `length` equals `8` instead of merely asserting that something came back.
+Keep that property when you replace it: a cookbook that asserts only truthiness
+proves the dispatch worked and nothing about the result
+(`.claude/rules/architecture-principles.md` §10a).
+
+## Testing
+
+Suites run **in a container**, in the one-shot test runner this service ships
+beside itself (`__CONTAINER_NAME___tests` in `docker-compose.yml`). It has its
+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:all:container   # everything test:all chains, in the runner
+```
+
+Each wraps one command — `docker compose run --rm __CONTAINER_NAME___tests npm run <suite>`.
+
+**Rebuilding the runner takes the profile with it.** `profiles: [test]` keeps the
+runner out of a plain `docker compose up`, and out of a plain build for the same
+reason — measured 2026-09-14: `docker compose build --dry-run` builds one image,
+`docker compose --profile test build --dry-run` builds two. So after a change to
+the `Dockerfile` or to the dependencies:
+
+```bash
+docker compose --profile test build
+```
+
+Without it the next `npm run test: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.
+
+`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
+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.
+
+### Cookbooks (Tier-1)
+
+```bash
+npm run test:cookbooks:container   # in the runner, which has the env
+```
+
+It wraps `npm run test:cookbooks`, the library command
+(`oa-biz-ci-gate run-prevalidation`, manifest row `S-COOKBOOKS`), which is what
+runs inside the container. The cookbook run dispatches real handlers under the
+testing namespace, so it reads `TESTING_TENANT_ID` and `TESTING_WORKSPACE_ID`;
+the runner has both from `env_file`, and the run fails by name if they are
+missing. It writes `conn-runtime/validation-proof.json` — generated,
+gitignored, and **not** what the platform trusts: the proof that counts is the
+one ServiceWrapper writes on every boot
+(`api/docs/biz/50-lifecycle/validation-responsibilities.md` § Data Flow).
+
+This template ships **no** `tests/integration/`, and no script declaring one:
+there is no behaviour here to exercise, and a declaration with nothing behind it
+is the defect `.claude/rules/change-discipline.md` § "Removing something removes
+its declaration" describes. Add the directory together with the first real
+integration test — `.claude/rules/architecture-principles.md` §10a requires one
+for every behavioural change, so the first handler brings its own.
+
+## Contract gates
+
+A fresh scaffold passes `biz-ci-gate verify-contract` — deploy, installation,
+env, test coverage and the library pins — with nothing added by hand:
+
+```bash
+node node_modules/@onlineapps/conn-orch-validator/src/cli/biz-ci-gate.js verify-contract
+```
+
+Two files are what makes that true, and both are copied and substituted with the
+rest of the template: `config/service/integration-contract.json` (the connectors,
+the integration minimum, and — once a handler reads one — the `env` block), and
+`docs/80-setup/{INSTALL,PLATFORM_MATRIX,VALIDATION}.md`, the three installation
+documents the contract requires of every repository
+(`api/docs/standards/repository-installation-sql-contract.md`).
+
+## Memory limits
+
+Two numbers, and they measure different things — the platform norm, recorded in
+`api/docs/governance/confirmations/biz-memory-limits.md` 001:
+
+| Where | Key | Value | Covers |
+|---|---|---|---|
+| service, dev **and** production | `deploy.resources.limits.memory` | `512M` | the resident service process, nothing else |
+| test runner, dev/CI only | `mem_limit` | `1g` | one suite at a time (`--maxWorkers=1`) |
+
+They are prescribed values, not figures derived for this service. The split is
+the point: while one budget covered both, a test run was killed by the kernel
+and took the service down with it — so raising the service limit is never the
+fix for a suite that runs out of memory, and no suite may share the service's
+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.

package/templates/business-service/config/biz-docs-lint.tree.json

@@ -0,0 +1,10 @@
+{
+  "_note": "Tree-bound overlay for linting api_biz/__SERVICE_NAME__/docs with api/scripts/ci/lint-biz-docs.mjs. Run from api/: node scripts/ci/lint-biz-docs.mjs --root ../api_biz/__SERVICE_NAME__/docs --tree-config ../api_biz/__SERVICE_NAME__/config/biz-docs-lint.tree.json --skip-code-rules --format text. Only the tree-bound keys belong here; every other rule is a platform rule inherited from api/config/biz-docs-lint.json. Manifest row C-LINT requires the file: without it the lint refuses to run over the tree, and a tree nothing lints is a tree nothing checks.",
+  "canonical_facts": [],
+  "_canonical_facts_note": "Empty on purpose, and it stays empty until this service owns a cross-cutting fact of its own. canonical_facts names the node that OWNS such a fact; everything a new service says is owned by the platform tree api/docs/biz/** and this tree only links to it.",
+  "default_max_words": 3687,
+  "_default_max_words_note": "The platform per-node norm (api/config/biz-docs-lint.json). A service tree does not get a laxer node cap than the platform tree it hangs off.",
+  "tree_max_words": 4000,
+  "_tree_max_words_note": "The scaffolded tree measures 1666 words in five nodes (INSTALL 544, VALIDATION 524, PLATFORM_MATRIX 412, 80-setup/README 94, README 92), counted with node api/scripts/ci/lib/countWords.js on 2026-09-14 \u2014 the two maps joined with D-LINT, which reports the orphan nodes a tree without them leaves behind. The budget is deliberately larger than that measurement, because a new service writes its own nodes into an otherwise empty tree; RAISE IT WITH A MEASUREMENT once the tree is real, the way api_biz/converter and api_biz/pdfgen state theirs, and never to make a failing run pass.",
+  "max_words_overrides": {}
+}

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

@@ -0,0 +1,4 @@
+# __SERVICE_NAME__ environment
+# Copy to config/env-active/__SERVICE_NAME__.env and adjust values.
+
+SERVICE_NAME=__SERVICE_NAME__

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

@@ -0,0 +1,65 @@
+# GENERATED FILE - do not edit. Edit the manifest instead:
+# api/config/shared-env.json, then run `npx oa-sync-template shared-env --target <dir>`.
+
+# 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.
+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).
+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.
+SECRETS_MASTER_KEYS=CHANGE_ME
+
+# The address of the platform cache on the docker network; declared once because every service reaches the same instance. The instance demands a password (server-topology 004: Redis publishes on wg0 with authentication), so the URL carries it: the value is per-machine and lives only in config/env-active/shared.env, and it is the same password as NODE_CACHE_PASSWORD in config/env-active/compose-infra.env - one fact reaching the container that enforces it and the services that authenticate to it, the same two-delivery split MINIO_ACCESS_KEY and MINIO_SECRET_KEY already have.
+REDIS_URL=redis://:CHANGE_ME@api_node_cache:6379
+
+# The broker every service opens its MQ connection with; the credentials are per-machine and live only in config/env-active/shared.env - the platform account is oa_dev, declared by infra/api_services_queuer/definitions.json.
+RABBITMQ_URL=amqp://CHANGE_ME:CHANGE_ME@api_services_queuer:5672
+
+# HTTP address of the registry for administrative operations from the host - scripts/bump-infra-version.sh announces an infrastructure version bump through it. No service reads it: registration travels over MQ to registry.register and discovery reads the Redis projection (confirmation biz-discovery-redis 002).
+REGISTRY_URL=http://api_services_registry:33100
+
+# The host AWS SigV4 signatures are computed against - deliberately the loopback name, not the reachable one, because MinIO validates the Host header (infra/api_minio_proxy/README.md).
+MINIO_ENDPOINT=127.0.0.1
+
+# Where the bytes actually go once the signature is computed against MINIO_ENDPOINT; the other half of the host-header split (infra/api_minio_proxy/README.md).
+MINIO_ACTUAL_HOST=api_minio_proxy
+
+# The S3 API port of the object store, shared with the endpoint it belongs to.
+MINIO_PORT=9000
+
+# Whether the object-store client opens its connection with TLS. It is declared here because until d.411 it was declared nowhere and every reader carried its own default, so one platform value had as many owners as it had readers (.claude/rules/change-discipline.md - One rail per concern). The platform value is false: MinIO publishes its S3 port on the private wg0 overlay only and never on a public interface (docs/governance/confirmations/server-topology.md 002 and 004), so the hop that would carry TLS is an encrypted one already; a deployment that puts TLS in front of the object store changes this key, and no library.
+MINIO_USE_SSL=false
+
+# The object-store account every service reads and writes under; the same pair is also interpolated into compose for the MinIO container itself (config/env-templates/compose-infra.env), two delivery mechanisms that must carry one value.
+MINIO_ACCESS_KEY=CHANGE_ME
+
+# The secret of that same object-store account; shares the compose-interpolation note of MINIO_ACCESS_KEY.
+MINIO_SECRET_KEY=CHANGE_ME
+
+# How often (ms) a business service publishes its MQ heartbeat, and the ONE source of truth for how fresh that signal has to be: every staleness threshold is a multiple of this cadence (BIZ_HEARTBEAT_STALE_FACTOR), never a second duration set by hand - owner decision docs/governance/confirmations/biz-health-freshness.md 001, which supersedes the absolute INFRASTRUCTURE_HEALTH_BUSINESS_STALE_AFTER of batch 111a. It is shared because the publisher and the judge are different processes: the registry derives its monitor and janitor thresholds from it today, and @onlineapps/service-wrapper is to read it in place of the wrapper.registry.heartbeatInterval runtime default, so a cadence change cannot reach one side only.
+BIZ_HEARTBEAT_INTERVAL_MS=30000
+
+# How many heartbeat cadences a business service may stay silent before it is judged stale; the only knob on top of BIZ_HEARTBEAT_INTERVAL_MS, and the reason no threshold is written as a duration anywhere (owner decision docs/governance/confirmations/biz-health-freshness.md 001: the factor is config, not doctrine - changing it is an ordinary config change). May be fractional; the derived threshold is whole milliseconds.
+BIZ_HEARTBEAT_STALE_FACTOR=2.5
+
+# The tenant a validation or test run writes into; it is platform-wide and never overridden per service, because a service that picks its own namespace can pick a live one. The classes and their meaning are owned by docs/standards/tenant-allocation.md.
+TESTING_TENANT_ID=99
+
+# The workspace half of that same namespace; it travels with TESTING_TENANT_ID because a run that knows one without the other addresses a namespace it cannot name.
+TESTING_WORKSPACE_ID=200
+
+# Process locale. No code in the platform reads it; the same three values are also baked into every infra Dockerfile as ENV, so this declaration has no measured consumer of its own.
+LANG=en_US.UTF-8
+
+# Process locale. No code in the platform reads it; the same three values are also baked into every infra Dockerfile as ENV, so this declaration has no measured consumer of its own.
+LC_ALL=en_US.UTF-8
+
+# Process locale. No code in the platform reads it; the same three values are also baked into every infra Dockerfile as ENV, so this declaration has no measured consumer of its own.
+LANGUAGE=en_US.UTF-8
+
+# The timezone every container renders local time in, declared ONCE here and inherited by every bearer of shared.env rather than as a per-service key (owner decision docs/governance/confirmations/container-timezone.md 001, on the BIZ-invoicing finding of 2026-08-29 that a document issued after local midnight carried the PREVIOUS day's date, because every container ran UTC). Timestamps stored in databases and in message envelopes stay UTC; this key changes only what local-time rendering resolves to - an invoice date, a log line a human reads - and code that derives a business date must still say which zone it means. Node honours it from its own ICU data, so a container needs no tzdata package for Date/Intl; libc tools (date, shell) follow it only where the image ships tzdata.
+TZ=Europe/Prague

package/templates/business-service/config/service/config.json

@@ -0,0 +1,14 @@
+{
+  "service": {
+    "name": "__REGISTRY_NAME__",
+    "description": "__SERVICE_DESCRIPTION__",
+    "specificationEndpoint": "/specification",
+    "workspaceScoped": false
+  },
+  "wrapper": {
+    "mq": {
+      "url": "${RABBITMQ_URL}",
+      "prefetch": 10
+    }
+  }
+}

package/templates/business-service/config/service/integration-contract.json

@@ -0,0 +1,12 @@
+{
+  "serviceName": "__REGISTRY_NAME__",
+  "requiredConnectors": {
+    "db": false,
+    "redis": false,
+    "mq": true,
+    "minio": false
+  },
+  "integrationMinimum": {
+    "minTestFiles": 1
+  }
+}