@onlineapps/conn-orch-validator 8.1.0 → 10.0.0

package/templates/business-service/.dockerignore

@@ -1,7 +1,12 @@
 # --- oa-dockerignore v1
 # Derived from templates/business-service/gitignore, the declaration .gitignore reads too —
 # what a LOCAL production build must not copy into the image (being ignored by git
-# excludes nothing from COPY . .). Everything above this block is this repository's own.
+# excludes nothing from COPY . .), PLUS the test tree: tests stay in the repository
+# and out of the artefact that runs, the same decision the library uniform makes as
+# L-PACK-TESTS. The one exception is tests/cookbooks, which is not a test but a
+# declaration the runtime reads — Tier-1 of the boot runs those cookbooks at phase
+# 0.2, and an image without them refuses its own validation proof as NO_TESTS.
+# Everything above this block is this repository's own.
 node_modules
 **/node_modules
 config/runtime
@@ -38,5 +43,8 @@ Thumbs.db
 **/Thumbs.db
 .oa_drive_deps_hash
 **/.oa_drive_deps_hash
+tests
+**/tests
+!tests/cookbooks
 .git
 # --- end oa-dockerignore v1

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

@@ -2,18 +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), 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.
+# 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
 
@@ -32,14 +42,71 @@ variables:
   IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
   IMAGE_LATEST: $CI_REGISTRY_IMAGE:latest
 
-verify-installation-contract:
+# 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
-  image: alpine:latest
+  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:
-    - sh scripts/verify-installation-docs-sql-contract.sh
+    # 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:
@@ -81,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
@@ -190,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
@@ -357,9 +414,20 @@ deploy-production:
         # format the runbook writes in phase 1, so a schema already carried
         # forward is skipped rather than applied twice (confirmation 001:
         # "fáze 2 nesmí změnit sémantiku trackeru").
-        mkdir -p config/runtime
+        #
+        # Its EXISTENCE is the precondition, and the step never creates it.
+        # Confirmation 001 splits the work in two: phase 1 - schema, account and
+        # the first run of this same runner - is an operator's step in the
+        # runbook, and phase 2 is this job carrying that state forward. On a box
+        # phase 1 never touched there is no tracker, and a job that created one
+        # would apply the WHOLE series unattended on the first deploy, which is
+        # precisely the phase the owner kept manual. So a missing tracker stops
+        # the deploy and names the runbook, exactly as a missing schema does.
         TRACKER="config/runtime/applied-migrations-${DB_SCHEMA}.txt"
-        touch "$TRACKER"
+        if [ ! -f "$TRACKER" ]; then
+          echo "[deploy] Migrations tracker $DEPLOY_PATH/$TRACKER missing - phase 1 (the migrations of $DB_SCHEMA applied by hand with the same runner) has not run on this box. Expected: the flat tracker phase 1 leaves behind, carried forward by this deploy. Fix: run the business-schema migrations step of api/docs/setup/INSTALL.md for $DB_SCHEMA, then re-run this deploy. This step never creates the tracker: a deploy that did would apply the whole series unattended on a box nobody had provisioned." >&2
+          exit 1
+        fi
         apply_mariadb_migrations_over_tcp "$DB_MIGRATIONS_DIR" "$TRACKER" "$DB_HOST" "$DB_PORT" "$DB_SCHEMA"
         # The runner logs each file it applies; what this line adds is the state
         # that outlives the deploy. The runner's own counter of files it passed
@@ -398,7 +466,6 @@ test:
   image: node:24-alpine
   variables:
     RABBITMQ_URL: "amqp://localhost:5672"
-    REGISTRY_URL: "http://localhost:33100"
     NODE_ENV: "test"
   script:
     - npm ci

package/templates/business-service/README.md

@@ -6,7 +6,7 @@ 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
@@ -21,7 +21,7 @@ Paths a duty owns:
 - `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
@@ -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.

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,9 +4,15 @@
 # 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
 
+# 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).
 JWT_SECRET=CHANGE_ME
 

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

@@ -99,7 +99,7 @@ if it is missing, so onboarding a new service needs no manual step there.
 Between that `pull` and that `up` the deploy job applies this service's pending
 MariaDB migrations — the ordering is the safety: the new image is already on the
 box, the previous container is still serving, and a migration that fails stops
-the deploy before the switch. Two facts decide what happens:
+the deploy before the switch. Three facts decide what happens:
 
 - `config/service/integration-contract.json` → `database`. This scaffold declares
   no such block, so the step prints `NOT APPLICABLE (no database block)` and the
@@ -109,11 +109,18 @@ the deploy before the switch. Two facts decide what happens:
   `MARIADB_MIGRATION_PASSWORD`, the service's own account. The step creates
   neither the schema nor the account and refuses the deploy when that account
   cannot open the schema, naming the runbook instead.
-
-Who creates them, with which grants and which collation, is the runbook's step
-and is not repeated here: `api/docs/setup/INSTALL.md`, the business-schema step.
-The decision behind both halves — two phases, the service account as the
-isolation guard, one runner and one tracker across them — is owner confirmation
+- `config/runtime/applied-migrations-<schema>.txt` on the box — the tracker.
+  **It must already be there**, and this job never creates it. The file is what
+  phase 1 leaves behind: the operator who created the schema and the account also
+  ran the first pass of the same runner by hand, from the runbook. A deploy onto a
+  box phase 1 never touched therefore stops with `Migrations tracker … missing`
+  rather than applying the whole series unattended.
+
+Who creates the schema, the account and that first tracker — with which grants and
+which collation — is the runbook's step and is not repeated here:
+`api/docs/setup/INSTALL.md`, the business-schema step. The decision behind both
+halves — two phases, the service account as the isolation guard, one runner and
+one tracker across them — is owner confirmation
 `api/docs/governance/confirmations/db-migrations-first-deploy.md` 001.
 
 ## Status

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
   ```
 

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

@@ -23,7 +23,7 @@ Every command runs from the repository root (`api_biz/__SERVICE_NAME__/`).
 node node_modules/@onlineapps/conn-orch-validator/src/cli/biz-ci-gate.js verify-contract
 
 # 2 — unit suite, in the one-shot runner beside the service
-npm run test:container
+npm run test:unit:container
 
 # 3 — cookbooks, in the same runner (it has the env files)
 npm run test:cookbooks:container

package/templates/business-service/jest.config.js

@@ -1,6 +1,14 @@
 module.exports = {
   testEnvironment: 'node',
   testMatch: ['**/tests/**/*.test.js'],
-  testTimeout: 30000,
+  // 120 s, because the limit is there to catch a test that HANGS and not a
+  // queue for the processor: on the shared dev machine (load average 47-94,
+  // the runners of several services at once) five integration suites failed in
+  // beforeAll at the previous 30 s while each of them passed when run alone,
+  // and the whole run passed at 180 s (BIZ-converter, d.580). The number is the
+  // platform's, not a service's - row F-JEST holds this file byte for byte.
+  testTimeout: 120000,
+  // One suite at a time, which is what the runner's memory norm assumes
+  // (api/docs/governance/confirmations/biz-memory-limits.md 001).
   maxWorkers: 1
 };

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

@@ -13,7 +13,7 @@
     "test:ci": "jest",
     "test:unit": "jest tests/unit",
     "test:all": "npm run test:unit",
-    "test:container": "docker compose run --rm __CONTAINER_NAME___tests npm run test:unit",
+    "test:unit:container": "docker compose run --rm __CONTAINER_NAME___tests npm run test:unit",
     "test:all:container": "docker compose run --rm __CONTAINER_NAME___tests npm run test:all",
     "test:coverage": "jest --coverage",
     "test:cookbooks": "node node_modules/@onlineapps/conn-orch-validator/src/cli/biz-ci-gate.js run-prevalidation",

package/src/mocks/MockStorage.js

@@ -1,188 +0,0 @@
-'use strict';
-
-/**
- * MockStorage - Simulates MinIO/S3 storage for testing
- */
-class MockStorage {
-  constructor() {
-    this.buckets = {};
-    this.metadata = {};
-  }
-
-  /**
-   * Create bucket
-   */
-  async createBucket(bucketName) {
-    if (!this.buckets[bucketName]) {
-      this.buckets[bucketName] = {};
-    }
-    return { success: true };
-  }
-
-  /**
-   * Put object
-   */
-  async put(bucket, key, content, options = {}) {
-    if (!this.buckets[bucket]) {
-      await this.createBucket(bucket);
-    }
-
-    const data = typeof content === 'object' ? JSON.stringify(content) : content;
-
-    this.buckets[bucket][key] = {
-      content: data,
-      contentType: options.contentType || 'application/json',
-      metadata: options.metadata || {},
-      timestamp: Date.now(),
-      size: data.length
-    };
-
-    // Store metadata separately for querying
-    if (!this.metadata[bucket]) {
-      this.metadata[bucket] = {};
-    }
-    this.metadata[bucket][key] = {
-      size: data.length,
-      lastModified: Date.now(),
-      contentType: options.contentType || 'application/json'
-    };
-
-    return {
-      success: true,
-      etag: `mock-etag-${Date.now()}`,
-      location: `${bucket}/${key}`
-    };
-  }
-
-  /**
-   * Get object
-   */
-  async get(bucket, key) {
-    if (!this.buckets[bucket] || !this.buckets[bucket][key]) {
-      throw new Error(`[MockStorage] Object not found: ${bucket}/${key} - Expected the object to have `
-        + 'been stored first. Fix: put(bucket, key, content) in the test setup before reading it.');
-    }
-
-    const obj = this.buckets[bucket][key];
-    let content = obj.content;
-
-    // Try to parse JSON if content type suggests it
-    if (obj.contentType === 'application/json' && typeof content === 'string') {
-      try {
-        content = JSON.parse(content);
-      } catch (e) {
-        // Keep as string if parsing fails
-      }
-    }
-
-    return {
-      content,
-      metadata: obj.metadata,
-      contentType: obj.contentType,
-      size: obj.size,
-      lastModified: obj.timestamp
-    };
-  }
-
-  /**
-   * Delete object
-   */
-  async delete(bucket, key) {
-    if (this.buckets[bucket]) {
-      delete this.buckets[bucket][key];
-      if (this.metadata[bucket]) {
-        delete this.metadata[bucket][key];
-      }
-    }
-    return { success: true };
-  }
-
-  /**
-   * List objects in bucket
-   */
-  async list(bucket, prefix = '', limit = 1000) {
-    if (!this.buckets[bucket]) {
-      return { objects: [] };
-    }
-
-    const objects = Object.keys(this.buckets[bucket])
-      .filter(key => key.startsWith(prefix))
-      .slice(0, limit)
-      .map(key => ({
-        key,
-        size: this.buckets[bucket][key].size,
-        lastModified: this.buckets[bucket][key].timestamp
-      }));
-
-    return { objects };
-  }
-
-  /**
-   * Check if object exists
-   */
-  async exists(bucket, key) {
-    return !!(this.buckets[bucket] && this.buckets[bucket][key]);
-  }
-
-  /**
-   * Get object metadata
-   */
-  async getMetadata(bucket, key) {
-    if (!this.metadata[bucket] || !this.metadata[bucket][key]) {
-      throw new Error(`[MockStorage] Metadata not found: ${bucket}/${key} - Expected metadata written `
-        + 'by put(). Fix: store the object with put(bucket, key, content) before reading its metadata.');
-    }
-    return this.metadata[bucket][key];
-  }
-
-  /**
-   * Generate presigned URL (mock)
-   */
-  async getPresignedUrl(bucket, key, expiresIn = 3600) {
-    return {
-      url: `http://mock-storage/${bucket}/${key}?token=mock-token-${Date.now()}`,
-      expiresAt: Date.now() + (expiresIn * 1000)
-    };
-  }
-
-  /**
-   * Clear all data
-   */
-  clear() {
-    this.buckets = {};
-    this.metadata = {};
-  }
-
-  /**
-   * Get storage stats
-   */
-  getStats() {
-    const stats = {
-      bucketCount: Object.keys(this.buckets).length,
-      totalObjects: 0,
-      totalSize: 0
-    };
-
-    Object.values(this.buckets).forEach(bucket => {
-      Object.values(bucket).forEach(obj => {
-        stats.totalObjects++;
-        stats.totalSize += obj.size;
-      });
-    });
-
-    return stats;
-  }
-
-  /**
-   * Copy object
-   */
-  async copy(sourceBucket, sourceKey, destBucket, destKey) {
-    const source = await this.get(sourceBucket, sourceKey);
-    return await this.put(destBucket, destKey, source.content, {
-      contentType: source.contentType,
-      metadata: source.metadata
-    });
-  }
-}
-
-module.exports = MockStorage;