rcf-lite 0.25.0 → 0.26.0

package/blueprints/messaging-queue-cloudflare/contributions/probes/real-account-concurrency-smoke.mjs

@@ -1,54 +1,209 @@
 /**
- * Real-account concurrency smoke.
+ * Real-account concurrency smoke for messaging-queue-cloudflare.
+ * v1.0.2.
  *
- * When CI_HAS_CLOUDFLARE_ACCOUNT is set, this probe opens the producer
- * against the shared HQ queue rcf-lite-ci-queue-smoke on Baz's Cloudflare
- * account (Q2 default per spec section 10), publishes 500 messages, and
- * asserts the consumer processes them concurrently up to the 250 push-
- * based invocation cap Cloudflare documents at
- * https://developers.cloudflare.com/queues/platform/limits/. Drains the
- * queue on exit.
+ * Self-provisioning: the fixture shim (packages/rcf-lite/test/fixtures/
+ * cf-platform/h2-cf-queue-real-account-shim.mjs) mints a scratch
+ * Cloudflare Queue under the throwaway prefix
+ * `h2-cf-probe-integrity-scratch-q-`, a scratch KV namespace for
+ * consumer telemetry under `h2-cf-probe-integrity-scratch-kv-tel-`,
+ * and a throwaway consumer Worker under `h2-cf-probe-integrity-
+ * scratch-w-` bound to the queue (consumer) with RCF_TEST_QUEUE
+ * (shipped queue producer binding name) + RCF_TEST_TELEMETRY_KV
+ * bindings. NO workers.dev subdomain is enabled (Dave ruling
+ * 376b4f30): the consumer is invoked BY THE QUEUE, not over HTTP.
  *
- * Without CI_HAS_CLOUDFLARE_ACCOUNT, records accountBoundSkipped:true
- * per spec section 3.5 and returns aggregateVerdict:pass so the shim
- * exits 0 in both paths.
+ * Driver:
+ *   1. Publishes 500 messages via the Cloudflare Queues REST publish
+ *      endpoint in 10 concurrent 50-message batches
+ *      (https://developers.cloudflare.com/api/operations/queue-publish-messages).
+ *   2. Polls the telemetry KV namespace via the KV REST list + get
+ *      endpoints until sum(batchSize) across records >= published
+ *      (drain cap 120s).
+ *   3. Computes maxConcurrent from an interval-overlap analysis on
+ *      the per-invocation (start, end) timestamps the Worker's
+ *      queue() handler recorded.
+ *   4. Asserts totalConsumed === published, maxConcurrent > 1, and
+ *      maxConcurrent <= 250 per Cloudflare's documented push-consumer
+ *      cap (https://developers.cloudflare.com/queues/platform/limits/).
+ *
+ * Local proof is a mock of Cloudflare's REST contract, not the wire.
+ * The local run exercises OUR lifecycle logic against a mock of
+ * Cloudflare's contract; the real-account gate is the only surface
+ * that proves the wire format (Dave ruling 376b4f30). This probe is
+ * therefore never described as "locally verified" - the local runs
+ * are our own lifecycle-logic proof; wire correctness is proven at
+ * the HQ real-account gate.
+ *
+ * Declared env (dispatch requirement 4):
+ *   CI_HAS_CLOUDFLARE_ACCOUNT   required to enter the driver path.
+ *   CF_ACCOUNT_ID               required (real-account only).
+ *   CF_API_TOKEN                required (real-account only).
+ *   CF_API_BASE_URL             optional test override (mock CF REST API).
+ *   CF_QUEUE_MESSAGE_COUNT      optional; defaults to 500.
+ *
+ * Without CI_HAS_CLOUDFLARE_ACCOUNT the probe returns pass-with-
+ * accountBoundSkipped per spec section 3.5; a pass is never reachable
+ * from credential presence alone.
  *
  * Anchors AC-29108-2.
  */
 
+import {
+  mintScratchQueueAndWorker, destroyScratchQueueAndWorker,
+  DECLARED_ENV, QUEUE_PREFIX, WORKER_PREFIX, TELEMETRY_KV_PREFIX,
+} from '../../../../packages/rcf-lite/test/fixtures/cf-platform/h2-cf-queue-real-account-shim.mjs';
+import { queuePublishBatch, kvListKeys, kvGet } from '../../../../packages/rcf-lite/test/fixtures/cf-platform/h2-cf-account-api.mjs';
+
+const DEFAULT_MESSAGE_COUNT = 500;
+const BATCH_SIZE = 50;
+const DRAIN_POLL_INTERVAL_MS = 500;
+const DRAIN_TIMEOUT_MS = 120000;
+const DOCUMENTED_PUSH_CAP = 250;
+
+export const anchorAcId = 'AC-29108-2';
 export const accountBound = true;
 
+function skipResult(detail) {
+  return [{
+    anchorAcId: 'AC-29108-2',
+    verdict: 'pass',
+    detail,
+    accountBoundSkipped: true,
+    envDeclared: Array.from(DECLARED_ENV),
+    throwawayPrefixes: { queue: QUEUE_PREFIX, worker: WORKER_PREFIX, telemetryKv: TELEMETRY_KV_PREFIX },
+  }];
+}
+
+// Interval-overlap analysis: given records [{start, end, batchSize, ...}]
+// compute the peak simultaneous in-flight invocation count using a
+// sweep line over the (start, +1) / (end, -1) event list.
+function computeMaxConcurrent(records) {
+  const events = [];
+  for (const r of records) {
+    events.push([r.start, +1]);
+    events.push([r.end, -1]);
+  }
+  // Sort by time; process starts before ends at the same instant so a
+  // batch that finishes exactly when another begins does not
+  // artificially deflate the concurrency count.
+  events.sort((a, b) => (a[0] - b[0]) || (b[1] - a[1]));
+  let cur = 0, max = 0;
+  for (const [, delta] of events) {
+    cur += delta;
+    if (cur > max) max = cur;
+  }
+  return max;
+}
+
+async function readTelemetryRecords({ namespaceId }) {
+  const keys = await kvListKeys({ namespaceId, prefix: 'telemetry-', limit: 1000 });
+  const records = await Promise.all(keys.map(async (k) => {
+    const g = await kvGet({ namespaceId, key: k.name });
+    if (!g.ok) return null;
+    try { return JSON.parse(g.text); } catch (_err) { return null; }
+  }));
+  return records.filter((r) => r && typeof r.start === 'number' && typeof r.end === 'number' && typeof r.batchSize === 'number');
+}
+
 export default async function runProbe() {
   const hasAccount = process.env.CI_HAS_CLOUDFLARE_ACCOUNT === '1' || process.env.CI_HAS_CLOUDFLARE_ACCOUNT === 'true';
   if (!hasAccount) {
+    return skipResult(`accountBoundSkipped: CI_HAS_CLOUDFLARE_ACCOUNT unset; a real-account run requires CI_HAS_CLOUDFLARE_ACCOUNT=true plus CF_ACCOUNT_ID and CF_API_TOKEN. The fixture mints its own throwaway Queue + consumer Worker + telemetry KV namespace under the H-2 prefixes; publishes via the CF Queues REST publish endpoint (no workers.dev subdomain enabled); reads telemetry via the KV REST list + get endpoints. Cap under test: ${DOCUMENTED_PUSH_CAP} concurrent invocations per push-consumer per https://developers.cloudflare.com/queues/platform/limits/. Message count: ${DEFAULT_MESSAGE_COUNT}.`);
+  }
+  if (!process.env.CF_ACCOUNT_ID || !process.env.CF_API_TOKEN) {
     return [{
       anchorAcId: 'AC-29108-2',
-      verdict: 'pass',
-      detail: 'accountBound: skipped (no CI_HAS_CLOUDFLARE_ACCOUNT)',
-      accountBoundSkipped: true,
+      verdict: 'fail',
+      detail: `CI_HAS_CLOUDFLARE_ACCOUNT=true but one of CF_ACCOUNT_ID / CF_API_TOKEN is missing: accountIdPresent=${!!process.env.CF_ACCOUNT_ID} tokenPresent=${!!process.env.CF_API_TOKEN}.`,
+      envDeclared: Array.from(DECLARED_ENV),
     }];
   }
-  // Live-account path. Requires:
-  //  - The shared HQ queue rcf-lite-ci-queue-smoke to exist on the
-  //    operator's Cloudflare account (Q2 default, spec section 10);
-  //    if it does not exist, the probe returns fail with a pointer to
-  //    the missing-queue CONCERN.
-  //  - Cloudflare credentials wired via security-secrets-management.
-  //
-  // The v1.0.0 shipped probe does not create the queue if missing (that
-  // decision belongs to Baz per the brief's escalation rule). A real-
-  // account run against a provisioned queue would publish 500 messages
-  // through the producer facade wired to a live Queues binding (via
-  // wrangler dev --remote is unsupported per the local-development doc,
-  // so a real-account run happens through a deployed Worker that binds
-  // the queue). The v1.0.0 probe stops short of driving deployment
-  // machinery from within a Node probe module; the account-bound test
-  // rides deploy-cloudflare-workers' surface at a later composition
-  // pass. This probe records the intent and the CONCERN inline.
-  return [{
-    anchorAcId: 'AC-29108-2',
-    verdict: 'pass',
-    detail: 'accountBound: pending real-account run (v1.0.0 ships the skipped-record shape; live-account run is a followup)',
-    accountBoundSkipped: true,
-  }];
+
+  const messageCount = Number.parseInt(process.env.CF_QUEUE_MESSAGE_COUNT ?? '', 10) || DEFAULT_MESSAGE_COUNT;
+  const runId = process.env.GITHUB_RUN_ID || `local-${Date.now()}`;
+
+  let mint = null;
+  try {
+    mint = await mintScratchQueueAndWorker({ runId });
+  } catch (err) {
+    return [{
+      anchorAcId: 'AC-29108-2',
+      verdict: 'fail',
+      detail: `mintScratchQueueAndWorker failed: ${err.message}`,
+      envDeclared: Array.from(DECLARED_ENV),
+    }];
+  }
+
+  try {
+    const started = Date.now();
+    const batches = [];
+    for (let i = 0; i < messageCount; i += BATCH_SIZE) {
+      const slice = [];
+      for (let j = 0; j < BATCH_SIZE && i + j < messageCount; j++) {
+        const seq = i + j;
+        slice.push({ body: { seq, ts: new Date().toISOString(), payload: `h2-smoke-${seq}` } });
+      }
+      batches.push(slice);
+    }
+
+    const publishResults = await Promise.all(batches.map((slice) =>
+      queuePublishBatch({ queueId: mint.queue.id, messages: slice })
+        .then((r) => ({ ok: true, ...r }))
+        .catch((err) => ({ ok: false, error: err.message, status: err.status || 0 })),
+    ));
+    const publishFail = publishResults.find((r) => !r.ok);
+    if (publishFail) {
+      return [{
+        anchorAcId: 'AC-29108-2',
+        verdict: 'fail',
+        detail: `queuePublishBatch failed: status=${publishFail.status} error=${publishFail.error}`,
+        envDeclared: Array.from(DECLARED_ENV),
+      }];
+    }
+    const publishedCount = publishResults.reduce((acc, r) => acc + (r.count ?? 0), 0);
+
+    let records = [];
+    let totalConsumed = 0;
+    const drainStart = Date.now();
+    while (Date.now() - drainStart < DRAIN_TIMEOUT_MS) {
+      records = await readTelemetryRecords({ namespaceId: mint.telemetryKv.id }).catch(() => []);
+      totalConsumed = records.reduce((a, r) => a + r.batchSize, 0);
+      if (totalConsumed >= publishedCount) break;
+      await new Promise((r) => setTimeout(r, DRAIN_POLL_INTERVAL_MS));
+    }
+
+    const elapsed = Date.now() - started;
+    const batchesConsumed = records.length;
+    const maxConcurrent = computeMaxConcurrent(records);
+    const drained = totalConsumed >= publishedCount;
+    const withinCap = maxConcurrent <= DOCUMENTED_PUSH_CAP;
+    const observedConcurrency = maxConcurrent > 1;
+    const allOk = drained && withinCap && observedConcurrency;
+
+    return [{
+      anchorAcId: 'AC-29108-2',
+      verdict: allOk ? 'pass' : 'fail',
+      detail: allOk
+        ? `queue=${mint.queue.name} (id=${mint.queue.id}) consumerWorker=${mint.worker.name} telemetryKv=${mint.telemetryKv.id}: published ${publishedCount} messages via ${batches.length} REST publish batches; consumer telemetry drawn from ${batchesConsumed} KV records in ${elapsed}ms elapsed: totalConsumed=${totalConsumed} batches=${batchesConsumed} maxConcurrent=${maxConcurrent} (>1 observed, <= ${DOCUMENTED_PUSH_CAP} documented push cap per https://developers.cloudflare.com/queues/platform/limits/); teardown removed worker, queue and telemetry KV namespace on exit.`
+        : `queue=${mint.queue.name} publishedCount=${publishedCount} totalConsumed=${totalConsumed} maxConcurrent=${maxConcurrent} batches=${batchesConsumed} elapsed=${elapsed}ms; drained=${drained} withinCap=${withinCap} observedConcurrency=${observedConcurrency}. Documented push cap: ${DOCUMENTED_PUSH_CAP} (https://developers.cloudflare.com/queues/platform/limits/).`,
+      queueName: mint.queue.name,
+      queueId: mint.queue.id,
+      workerName: mint.worker.name,
+      telemetryKvId: mint.telemetryKv.id,
+      publishedCount,
+      totalConsumed,
+      batches: batchesConsumed,
+      maxConcurrent,
+      elapsedMs: elapsed,
+      envDeclared: Array.from(DECLARED_ENV),
+      throwawayPrefixes: { queue: QUEUE_PREFIX, worker: WORKER_PREFIX, telemetryKv: TELEMETRY_KV_PREFIX },
+    }];
+  } finally {
+    try {
+      await destroyScratchQueueAndWorker(mint);
+    } catch (err) {
+      process.stderr.write(`h2-cf-queue probe: teardown failed for queue=${mint && mint.queue && mint.queue.id} worker=${mint && mint.worker && mint.worker.name} telemetryKv=${mint && mint.telemetryKv && mint.telemetryKv.id}: ${err.message}; sweepOrphans will collect on next run.\n`);
+    }
+  }
 }

package/blueprints/messaging-queue-cloudflare/docs/topics.md

@@ -43,7 +43,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | application-empty-error-states | 22101-22899 | 23xx | shipped v1.0.0 | none |
 | application-file-upload | 23101-23899 | 24xx | shipped v1.0.0 | none |
 | persistence-data-postgres | 27101-27899 | 28xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
-| object-storage-s3 | 28101-28899 | 29xx | shipped v1.0.0 | `objectStorageContract` |
+| object-storage-s3 | 28101-28899 | 29xx | shipped v1.1.0 | `objectStorageContract` |
 | messaging-queue-cloudflare | 29101-29899 | 30xx | shipped v1.0.0 | `deliverySemantics` |
 | jobs-background | 30101-30899 | 31xx | shipped v1.0.0 | `backgroundJobModel` |
 | platform-cloudflare-kv | 31101-31899 | 32xx | shipped v1.0.0 | `keyValueStoreContract` |

package/blueprints/object-storage-s3/CHANGELOG.md

@@ -1,5 +1,16 @@
 # object-storage-s3 changelog
 
+## 1.1.0 - 2026-09-08
+
+Follow-up adapter minor bump adding the Hetzner Object Storage provider value under the shipped v1.0.0 S3-API facade contract. Landed via the hetzner-round-7-spec-2026-09-07 section 5.4 follow-up (ratified 2026-09-07T10:15Z on Baz's 09:50Z ruling "round 7 - agreee to all") as a sequential PR post round 7. Additive only: every existing v1.0.0 contribution id is byte-identical; the shipped Cloudflare R2 real-account smoke, the MinIO local emulator round-trip and the five shipped Node-only probes continue to pass byte-identical on the extended fixture. rcf-lite package version does NOT bump for this follow-up (spec section 8).
+
+- 4 delta contributions on the blueprint side (25 total, up from 21): 1 REQ (`object-storage-s3-REQ-101`, endpoint-shape contract), 1 US (`object-storage-s3-US-28110` with `AC-28110-1` labelled `AC-hetznerObjectStorage-endpointRoundTrip`), 1 TAC (`TAC-2904-object-storage-s3-hetzner-endpoint-helper`, sole composer of `<bucket>.<location>.your-objectstorage.com`), 1 ADR (`ADR-2905-object-storage-s3-hetzner-object-storage-provider`, scope local, `standardsTraceClause: Hetzner Object Storage S3 compatibility documented endpoint shape`).
+- One new Node-only probe `hetzner-object-storage-round-trip.mjs` under `contributions/probes/`, `accountBound: true`, gated on `CI_HAS_HETZNER_OBJECT_STORAGE` alongside `HETZNER_OBJECT_STORAGE_ACCESS_KEY_ID`, `HETZNER_OBJECT_STORAGE_SECRET_ACCESS_KEY`, `HETZNER_OBJECT_STORAGE_BUCKET`, `HETZNER_OBJECT_STORAGE_LOCATION`; without the gate env var the probe records `accountBoundSkipped: true` per spec section 3.5. The round-5 T-2 R2 real-account smoke is unaffected and stays gated on `CI_HAS_CLOUDFLARE_ACCOUNT`.
+- Extended the shared `packages/rcf-lite/test/fixtures/infra-s3-and-queue/` fixture (no second fixture directory) with `src/hetzner-endpoint.mjs` (endpoint helper plus two fixture-side mutation switches per the 2026-09-08 mutation-purity discipline: `SIMULATE_HETZNER_ENDPOINT_MISSHAPEN` drops the vendor subdomain, `SIMULATE_HETZNER_EVENT_LEAK` appends fixture-labelled credential fields to event records) and a fixture-root shim `run-hetzner-object-storage-round-trip.mjs`. The probe module reads no `SIMULATE_` variable.
+- Vendor endpoint pattern and location codes verbatim from https://docs.hetzner.com/storage/object-storage/overview (`<bucket>.<location>.your-objectstorage.com`; locations `fsn1` Falkenstein, `hel1` Helsinki, `nbg1` Nuremberg). Composition helper refuses any location outside the enum.
+- Blueprint README extended with a Hetzner Object Storage sub-section under the provider-choice section; `guide/object-storage-s3.md` extended with a Hetzner section including the when-to-reach-for guidance; shelf-wide sweep on every blueprint's `docs/topics.md` updates the object-storage-s3 row from `shipped v1.0.0` to `shipped v1.1.0` per the round-6 admin-console 1.1.0 precedent (PR #169).
+- `capabilities: ["objectStorage"]`, `suggestedCompanions: [{role: "logging"}, {role: "errorHandling"}]`, `providesRoles` absent, `requiresAppliedCapabilities` unchanged.
+
 ## 1.0.0 - 2026-09-06
 
 Initial release. Contract for S3-shape object storage on any S3-compatible endpoint (Cloudflare R2 first, MinIO for local dev, AWS S3, Backblaze B2, Wasabi, self-hosted). Accessed through a store facade that is the sole reader of the S3 client (`@aws-sdk/client-s3` on Node targets or `aws4fetch` on Workers targets). Landed via the infra round 5 spec (ratified 2026-09-06) as track T-2.

package/blueprints/object-storage-s3/README.md

@@ -19,12 +19,14 @@ Object storage on the S3 API, accessed through a store facade that is the sole r
 | REQ-004 | Multipart-upload above the ADR-2903 threshold (default 8 MiB); abort-on-failure with no orphan in-flight uploads. |
 | REQ-005 | Four lifecycle events with metadata-only fields; event-secrecy probe asserts against a PII fixture. |
 | REQ-006 | Credential-pair discipline via `security-secrets-management`; refuses composition without with stable message id `object-storage-s3-no-secrets`. |
+| REQ-101 (v1.1.0) | Hetzner Object Storage adapter: endpoint-shape helper composes `<bucket>.<location>.your-objectstorage.com` from an elicited bucket and location; MinIO and R2 paths unchanged. |
 
 ## The three TACs
 
 - **TAC-2901 facade**: the object-storage S3 facade module.
 - **TAC-2902 multipart uploader**: initiate/part-upload/complete with abort-on-failure.
 - **TAC-2903 event sink**: metadata-only lifecycle event contract.
+- **TAC-2904 Hetzner endpoint helper (v1.1.0)**: sole composer of `<bucket>.<location>.your-objectstorage.com`; enum-refuses unknown location codes.
 
 ## The four ADRs
 
@@ -32,10 +34,19 @@ Object storage on the S3 API, accessed through a store facade that is the sole r
 - **ADR-2902 presigned URL TTL**: default 15 minutes, floor 1 minute; elicited ceiling. Standards trace clause: generic enterprise practice.
 - **ADR-2903 multipart threshold**: default 8 MiB, elicited. Standards trace clause: generic enterprise practice.
 - **ADR-2904 object storage contract** (scope: global, topic `objectStorageContract`): S3 API as the shipped shape; conflicts by design with future non-S3-shape siblings. Standards trace clause: AWS S3 API and R2 S3-compatibility notes.
+- **ADR-2905 Hetzner Object Storage provider (v1.1.0)**: recognises `hetznerObjectStorage` as a shipped provider value under the shipped S3-API facade; endpoint pattern `<bucket>.<location>.your-objectstorage.com` composed via TAC-2904; MinIO and R2 paths unchanged. Standards trace clause: Hetzner Object Storage S3 compatibility documented endpoint shape.
 
 ## Elicited parameters
 
-Endpoint URL (R2 `https://<account-id>.r2.cloudflarestorage.com`, AWS S3 `https://s3.<region>.amazonaws.com`, MinIO `http://localhost:9000`, any S3-compatible remote); bucket name; credential-pair reference via `security-secrets-management` (never value); adapter (`awsSdk` or `aws4fetch`); presigned-URL default TTL (default 15 minutes); presigned-URL ceiling (elicited, no shipped default, S3 API 7-day outer bound); multipart-upload threshold (default 8 MiB); force path style (`true` for MinIO, `false` for AWS/R2 with virtual-hosted style); server-side encryption default (`sseNone` on R2 per the R2 compatibility notes; `sseS3` on AWS S3 when the operator elicits it).
+Endpoint URL (R2 `https://<account-id>.r2.cloudflarestorage.com`, AWS S3 `https://s3.<region>.amazonaws.com`, MinIO `http://localhost:9000`, Hetzner Object Storage `https://<bucket>.<location>.your-objectstorage.com` composed from a bucket and location via the v1.1.0 helper, any S3-compatible remote); bucket name; credential-pair reference via `security-secrets-management` (never value); adapter (`awsSdk` or `aws4fetch`); presigned-URL default TTL (default 15 minutes); presigned-URL ceiling (elicited, no shipped default, S3 API 7-day outer bound); multipart-upload threshold (default 8 MiB); force path style (`true` for MinIO, `false` for AWS/R2 and Hetzner Object Storage with virtual-hosted style); server-side encryption default (`sseNone` on R2 per the R2 compatibility notes; `sseS3` on AWS S3 when the operator elicits it).
+
+## Hetzner Object Storage adapter (v1.1.0)
+
+Since v1.1.0 the blueprint recognises `hetznerObjectStorage` as a shipped provider value under the existing S3-API facade contract. Hetzner Object Storage is S3-compatible per https://docs.hetzner.com/storage/object-storage/overview; the endpoint follows the vendor-documented pattern `<bucket>.<location>.your-objectstorage.com`. Three location codes are shipped: `fsn1` (Falkenstein), `hel1` (Helsinki), `nbg1` (Nuremberg), matching the same page. A project applying the blueprint with the Hetzner provider elicits the bucket and location; a small helper (`composeHetznerEndpoint`, TAC-2904) composes the https endpoint URL and hands it to the shipped facade unchanged. `region` defaults to `auto` (matching the R2 shape); `forcePathStyle` defaults to `false` (virtual-hosted-style, matching R2 and AWS S3). The Cloudflare R2 real-account smoke stays gated on `CI_HAS_CLOUDFLARE_ACCOUNT` and does not read the new env vars; the MinIO local emulator flow stays byte-identical. Reach for Hetzner over R2 for a European storage region with a different egress-pricing profile; reach for R2 for the zero-egress-fee posture; reach for MinIO for local dev without any account.
+
+Runtime dependency: none added. The shipped `@aws-sdk/client-s3` client signs and speaks the S3 wire protocol against the composed Hetzner endpoint unchanged.
+
+A new Node-only probe `hetzner-object-storage-round-trip.mjs` binds AC-28110-1: with `CI_HAS_HETZNER_OBJECT_STORAGE` set (plus `HETZNER_OBJECT_STORAGE_ACCESS_KEY_ID`, `HETZNER_OBJECT_STORAGE_SECRET_ACCESS_KEY`, `HETZNER_OBJECT_STORAGE_BUCKET`, `HETZNER_OBJECT_STORAGE_LOCATION`) it round-trips a byte-equal 1 KiB payload against a real Hetzner Object Storage bucket; without the env var it records `accountBoundSkipped: true` per spec section 3.5.
 
 ## Companions
 
@@ -58,6 +69,7 @@ Each probe is a Node module under `contributions/probes/` exporting the round-5
 | `multipart-upload` | AC-28104-1, AC-28104-2 | 10 MiB payload above the 8 MiB threshold round-trips byte-equal via multipart; no orphan in-flight uploads after complete; abort-on-failure with `SIMULATE_PART_UPLOAD_FAIL=true`. | false |
 | `event-secrecy` | AC-28105-1 | Every event record carries only whitelisted metadata fields; no PII fixture text; no forbidden field name. | false |
 | `r2-real-account-smoke` | AC-28108-1 | Real R2 round-trip when `CI_HAS_CLOUDFLARE_ACCOUNT` is set; records `accountBoundSkipped: true` when it is not. | true |
+| `hetzner-object-storage-round-trip` (v1.1.0) | AC-28110-1 | Composes `<bucket>.<location>.your-objectstorage.com` via `composeHetznerEndpoint`; real Hetzner Object Storage round-trip when `CI_HAS_HETZNER_OBJECT_STORAGE` is set; records `accountBoundSkipped: true` when it is not. | true |
 
 ## How to run the probes locally
 
@@ -73,6 +85,7 @@ node ../../../../blueprints/object-storage-s3/contributions/probes/run-presigned
 node ../../../../blueprints/object-storage-s3/contributions/probes/run-multipart-upload.mjs
 node ../../../../blueprints/object-storage-s3/contributions/probes/run-event-secrecy.mjs
 node ../../../../blueprints/object-storage-s3/contributions/probes/run-r2-real-account-smoke.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-hetzner-object-storage-round-trip.mjs
 docker compose down -v
 ```
 

package/blueprints/object-storage-s3/blueprint.json

@@ -1,6 +1,6 @@
 {
   "slug": "object-storage-s3",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "category": "object-storage",
   "capabilities": ["objectStorage"],
   "requiresAppliedCapabilities": {
@@ -67,6 +67,17 @@
       "scope": "global",
       "topic": "objectStorageContract",
       "standardsTraceClause": "AWS S3 API and Cloudflare R2 S3-compatibility notes"
+    },
+    { "id": "object-storage-s3-REQ-101", "kind": "req", "path": "requirements/object-storage-s3-req-101.json" },
+    { "id": "object-storage-s3-US-28110", "kind": "us", "path": "user-stories/object-storage-s3-us-28110.json" },
+    { "id": "TAC-2904-object-storage-s3-hetzner-endpoint-helper", "kind": "tac", "path": "tacs/tac-2904-object-storage-s3-hetzner-endpoint-helper.json" },
+    {
+      "id": "ADR-2905-object-storage-s3-hetzner-object-storage-provider",
+      "kind": "adr",
+      "path": "adrs/adr-2905-object-storage-s3-hetzner-object-storage-provider.json",
+      "recommendedDefault": false,
+      "elicited": true,
+      "standardsTraceClause": "Hetzner Object Storage S3 compatibility documented endpoint shape"
     }
   ]
 }

package/blueprints/object-storage-s3/contributions/adrs/adr-2905-object-storage-s3-hetzner-object-storage-provider.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-2905-object-storage-s3-hetzner-object-storage-provider",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.1.0",
+  "status": "accepted",
+  "title": "Hetzner Object Storage as a shipped provider value under the object-storage-s3 v1.0.0 facade; endpoint pattern <bucket>.<location>.your-objectstorage.com per the Hetzner storage overview; MinIO and R2 paths unchanged",
+  "context": "The object-storage-s3 v1.0.0 blueprint shipped Cloudflare R2 (production first-target on the shipped adapter shape), AWS S3 (interop first-class through the same wire protocol), MinIO (local emulator for dev), and any other S3-compatible endpoint (Backblaze B2 in S3-compat mode, Wasabi, self-hosted) as providers a project can point at by pasting an endpoint URL into the elicited endpointUrl parameter on the facade. Hetzner Object Storage is S3-compatible per https://docs.hetzner.com/storage/object-storage/overview (fetched 2026-09-08 200) and reads through the shipped facade without a client change, but its endpoint URL is derived from two elicited values (a bucket name and a location code in {fsn1, hel1, nbg1}) rather than pasted in whole; the vendor pattern is <bucket>.<location>.your-objectstorage.com per the same page. A follow-up minor bump adds the Hetzner Object Storage provider value by shipping an endpoint-shape helper (TAC-2904) that composes the vendor pattern from those two elicited values and hands the composed https URL to the facade unchanged. No topic conflict is raised because the objectStorageContract topic (ADR-2904, scope global) names the wire-shape contract as the S3 API, and Hetzner Object Storage speaks that contract per the overview.",
+  "decision": "The shipped v1.1.0 object-storage-s3 blueprint recognises hetznerObjectStorage as a shipped provider value alongside R2, AWS, MinIO. A project applying object-storage-s3 with the Hetzner provider elicits a bucket name and a location code in {fsn1, hel1, nbg1}, and the shipped endpoint-shape helper (TAC-2904, composeHetznerEndpoint) composes https://<bucket>.<location>.your-objectstorage.com verbatim per https://docs.hetzner.com/storage/object-storage/overview. The composed URL feeds the shipped facade (TAC-2901) through the existing endpointUrl parameter; no facade shape moves, no runtime dependency lands in the applying project, no re-signing surface is added (the S3 client's SigV4 signing works unchanged against the composed endpoint). Region defaults to auto (matching the R2 shape); forcePathStyle defaults to false (matching R2 and AWS S3 with virtual-hosted-style buckets). A new Node-only probe hetzner-object-storage-round-trip.mjs binds to AC-28110-1: with CI_HAS_HETZNER_OBJECT_STORAGE the probe round-trips a byte-equal 1 KiB payload against a real bucket, without it the probe records accountBoundSkipped true per spec section 3.5. The MinIO local emulator and R2 real-account smoke stay byte-identical and keep their v1.0.0 acceptance shape.",
+  "consequences": "A project that outgrows the MinIO local emulator or wants a European storage location with lower egress costs than R2 or AWS S3 picks hetznerObjectStorage at apply time and the shipped facade routes through the composed endpoint unchanged. Standards trace clause: Hetzner Object Storage S3 compatibility documented endpoint shape (https://docs.hetzner.com/storage/object-storage/overview) enumerates the endpoint pattern and the three location codes fsn1, hel1, nbg1. The provider list is not exhaustive; a future v1.2.0 minor could add another S3-compatible provider under the same shape by shipping another endpoint helper. The shipped R2 real-account smoke stays gated on CI_HAS_CLOUDFLARE_ACCOUNT and does not read CI_HAS_HETZNER_OBJECT_STORAGE; the two smokes skip independently. rcf-lite package version does NOT bump for this follow-up (spec section 8): the blueprint bumps 1.0.0 -> 1.1.0 and ships as its own sequential PR post-round-7.",
+  "alternativesConsidered": [
+    {
+      "name": "Extend ADR-2901 alternativesConsidered instead of shipping a sibling ADR",
+      "summary": "Mutate the shipped v1.0.0 ADR-2901 body to enumerate Hetzner Object Storage as a fourth alternative under the SDK-adapter axis.",
+      "reasonNotChosen": "ADR-2901's alternativesConsidered axis is client-choice (AWS SDK v3 vs aws4fetch vs hand-rolled SigV4), not provider-choice. Hetzner Object Storage is a provider under the shipped AWS SDK v3 adapter; mutating ADR-2901 would mis-scope the alternative. The additive-only discipline of a minor bump prefers a sibling ADR that references ADR-2901 by id over a mutation of the shipped body."
+    },
+    {
+      "name": "Ship the Hetzner Object Storage endpoint as a documented example on the freeform endpointUrl only, without a helper module",
+      "summary": "Document the endpoint pattern in the guide and let the applying project paste https://<bucket>.<location>.your-objectstorage.com into endpointUrl by hand.",
+      "reasonNotChosen": "A hand-composed endpoint is a shape a project can mis-key silently (a missing dot before your-objectstorage.com, a bucket-shaped hostname prefix that a linter cannot flag). The endpoint-shape helper turns the vendor convention into a mechanical composition with an enum-checked location code and a probe that asserts the composed value against the vendor pattern. The helper is 20 lines of code and lives inside the applying project; the trade-off is one small module for a mechanically-checked correctness gain."
+    },
+    {
+      "name": "Mint a separate object-storage-hetzner blueprint slug",
+      "summary": "Ship a fresh blueprint object-storage-hetzner v1.0.0 with the Hetzner-shaped facade instead of extending object-storage-s3.",
+      "reasonNotChosen": "Hetzner Object Storage speaks the S3 wire protocol per the vendor overview; a separate slug would duplicate the whole object-storage-s3 facade contract and split the shelf on a provider axis rather than a contract axis. The objectStorageContract global-ADR topic already names the wire-shape contract as the S3 API; adding a provider value under that contract stays additive."
+    }
+  ],
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/probes/hetzner-object-storage-round-trip.mjs

@@ -0,0 +1,136 @@
+/**
+ * Hetzner Object Storage round-trip probe.
+ *
+ * Composes the vendor-documented endpoint pattern
+ * <bucket>.<location>.your-objectstorage.com through the fixture-side
+ * hetzner-endpoint helper (TAC-2904; sole composer of the pattern),
+ * opens the shipped v1.0.0 facade (TAC-2901 over @aws-sdk/client-s3
+ * per ADR-2901) against the composed endpoint, puts a 1 KiB payload,
+ * gets it back byte-equal, deletes the scratch object, and asserts
+ * every lifecycle event record carries only whitelisted metadata
+ * fields per the fixture-side whitelist.
+ *
+ * accountBound: true. Skipped in CI without CI_HAS_HETZNER_OBJECT_STORAGE
+ * per hetzner-round-7-spec-2026-09-07 section 3.5 and section 5.4.
+ *
+ * Dependency-load discipline: the fixture-side facade module
+ * `object-store.mjs` imports `@aws-sdk/client-s3`, which is a
+ * fixture-scoped dependency installed by `npm install` inside the
+ * fixture directory (documented in the fixture README). To keep the
+ * accountBoundSkipped path loadable without that fixture install
+ * (surface inspection under `node --test`, tools that walk the probe
+ * module for its `accountBound` flag), the SDK-touching imports are
+ * DYNAMIC and gated on the CI_HAS_HETZNER_OBJECT_STORAGE env var.
+ *
+ * Mutation-purity discipline (per HQ hard gate row 2026-09-08): this
+ * module reads NO SIMULATE_ variable. Every fixture-side mutation
+ * hook (SIMULATE_HETZNER_ENDPOINT_MISSHAPEN,
+ * SIMULATE_HETZNER_EVENT_LEAK) lives in
+ * packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/hetzner-endpoint.mjs
+ * and alters the INPUT the probe assembles (the composed URL or the
+ * event-record payload).
+ *
+ * Anchors AC-28110-1 (label AC-hetznerObjectStorage-endpointRoundTrip).
+ */
+
+import { probeKey } from './probe-utils.mjs';
+
+export const accountBound = true;
+
+const VENDOR_PATTERN = /^https:\/\/[^./]+\.(fsn1|hel1|nbg1)\.your-objectstorage\.com$/;
+
+export default async function runProbe() {
+  if (!process.env.CI_HAS_HETZNER_OBJECT_STORAGE) {
+    return [{
+      anchorAcId: 'AC-28110-1',
+      verdict: 'pass',
+      detail: 'accountBound: skipped (no CI_HAS_HETZNER_OBJECT_STORAGE)',
+      accountBoundSkipped: true,
+    }];
+  }
+
+  // Dynamic imports so the accountBoundSkipped path above loads
+  // without the fixture-scoped @aws-sdk/client-s3 dependency.
+  const {
+    composeHetznerEndpoint,
+    hetznerCredentialsFromEnv,
+    makeHetznerEventDecorator,
+    assertMetadataOnlyEventRecords,
+    HETZNER_EVENT_WHITELIST,
+  } = await import('../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/hetzner-endpoint.mjs');
+  const { createObjectStore } = await import('../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/object-store.mjs');
+
+  const { accessKeyId, secretAccessKey, bucket, location } = hetznerCredentialsFromEnv();
+  if (!accessKeyId || !secretAccessKey || !bucket || !location) {
+    return [{
+      anchorAcId: 'AC-28110-1',
+      verdict: 'fail',
+      detail: 'CI_HAS_HETZNER_OBJECT_STORAGE set but one or more required env vars missing (HETZNER_OBJECT_STORAGE_ACCESS_KEY_ID, HETZNER_OBJECT_STORAGE_SECRET_ACCESS_KEY, HETZNER_OBJECT_STORAGE_BUCKET, HETZNER_OBJECT_STORAGE_LOCATION)',
+    }];
+  }
+
+  const results = [];
+  let endpoint;
+  try {
+    endpoint = composeHetznerEndpoint({ bucket, location });
+  } catch (err) {
+    return [{
+      anchorAcId: 'AC-28110-1',
+      verdict: 'fail',
+      detail: `endpoint composition threw on field ${err.field || 'unknown'}: ${err.message}`,
+    }];
+  }
+  if (!VENDOR_PATTERN.test(endpoint)) {
+    return [{
+      anchorAcId: 'AC-28110-1',
+      verdict: 'fail',
+      detail: `composed endpoint does not match vendor pattern <bucket>.<location>.your-objectstorage.com; got ${endpoint}; missing subdomain: your-objectstorage.com`,
+    }];
+  }
+
+  const events = [];
+  const store = createObjectStore({
+    endpointUrl: endpoint,
+    bucket,
+    credentialsRef: { accessKeyId, secretAccessKey },
+    region: 'auto',
+    forcePathStyle: false,
+    onEvent: (e) => events.push(makeHetznerEventDecorator({
+      event: e.event,
+      ts: e.ts,
+      endpointHost: e.endpointHost,
+      bucketName: e.bucketName,
+      location,
+      key: e.key,
+      size: e.size,
+      contentType: e.contentType,
+    })),
+  });
+  const key = probeKey('probe/hetzner-smoke');
+  const body = Buffer.alloc(1024, 0x48);
+  try {
+    await store.ready();
+    await store.putObject(key, 'application/octet-stream', body);
+    const got = await store.getObject(key);
+    const roundTripEqual = got.body.length === 1024 && got.body.equals(body);
+    results.push({
+      anchorAcId: 'AC-28110-1',
+      verdict: roundTripEqual ? 'pass' : 'fail',
+      detail: roundTripEqual
+        ? `Hetzner Object Storage round-trip byte-equal against ${endpoint} bucket=${bucket} location=${location}`
+        : `Hetzner Object Storage round-trip failed byte equality; expected 1024 bytes got ${got.body.length}`,
+    });
+    const evAssertion = assertMetadataOnlyEventRecords(events);
+    results.push({
+      anchorAcId: 'AC-28110-1',
+      verdict: evAssertion.pass ? 'pass' : 'fail',
+      detail: evAssertion.pass
+        ? `every lifecycle event carries only whitelisted fields (${[...HETZNER_EVENT_WHITELIST].join(',')})`
+        : `event-secrecy leak: forbidden fields present ${evAssertion.leaked.join(',')}`,
+    });
+  } finally {
+    try { await store.deleteObject(key); } catch { /* teardown best effort */ }
+    await store.close();
+  }
+  return results;
+}

package/blueprints/object-storage-s3/contributions/probes/run-hetzner-object-storage-round-trip.mjs

@@ -0,0 +1,11 @@
+/**
+ * Shim: run hetzner-object-storage-round-trip against the extended
+ * infra-s3-and-queue fixture and write
+ * .rcf/reports/blueprints/object-storage-s3/hetzner-object-storage-round-trip.json.
+ */
+
+import runProbe from './hetzner-object-storage-round-trip.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 's3', image: 'hetzner-object-storage-cloud', healthy: true };
+runShim('hetzner-object-storage-round-trip', engine, runProbe);

package/blueprints/object-storage-s3/contributions/requirements/object-storage-s3-req-101.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "object-storage-s3-REQ-101",
+  "prdId": "PRD-001",
+  "title": "Hetzner Object Storage adapter: endpoint-shape helper composes <bucket>.<location>.your-objectstorage.com from an elicited bucket and location code",
+  "description": "The object-storage-s3 v1.1.0 minor bump adds a Hetzner Object Storage provider value under the shipped S3-API facade contract without changing the outward facade shape. The Hetzner Object Storage endpoint follows the vendor-documented pattern <bucket>.<location>.your-objectstorage.com per https://docs.hetzner.com/storage/object-storage/overview; a project applying the blueprint elicits a bucket name and a location code (fsn1 for Falkenstein, hel1 for Helsinki, nbg1 for Nuremberg per the same overview page) and the adapter composes the https endpoint URL through a single helper module. The helper is the sole composer of the vendor pattern for this provider so a project cannot accidentally construct an invalid endpoint by hand-concatenating the parts; the composed endpoint feeds the shipped S3 client (@aws-sdk/client-s3 on Node targets per ADR-2901) unchanged. The v1.0.0 Cloudflare R2, AWS S3 and MinIO paths stay byte-identical: the endpoint URL parameter on the facade remains freeform, and only projects that elicit hetznerObjectStorage as the provider consume the helper.",
+  "category": "functional",
+  "domain": "object-storage",
+  "priority": "must",
+  "rationale": "A single helper module for the Hetzner Object Storage endpoint pattern turns a documented vendor convention into a mechanical composition that the applied project cannot mis-shape by editing a config file. Reading the endpoint pattern from bucket plus location, in code, makes the composition observable to the probe (which asserts the composed value against the vendor pattern) and gives the mutation-purity switch a fixture-side seam (SIMULATE_HETZNER_ENDPOINT_MISSHAPEN alters the composed bucket segment on the INPUT side; the probe module never reads a SIMULATE_ variable and the composition module always composes correctly). The Cloudflare R2, AWS S3 and MinIO providers keep their v1.0.0 shape because their endpoint URLs are already documented on their own pages and each project applying those providers pastes the endpoint URL through the elicited freeform parameter; Hetzner Object Storage differs only in that the endpoint is derived from two elicited values rather than one pasted URL.",
+  "tags": [
+    "blueprint:object-storage-s3",
+    "category:07-hetzner-object-storage-adapter"
+  ],
+  "version": "1.1.0",
+  "status": "approved",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/tacs/tac-2904-object-storage-s3-hetzner-endpoint-helper.json

@@ -0,0 +1,34 @@
+{
+  "tacId": "TAC-2904-object-storage-s3-hetzner-endpoint-helper",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.1.0",
+  "status": "approved",
+  "name": "Hetzner Object Storage endpoint-shape helper",
+  "purpose": "The single project-side module that composes the Hetzner Object Storage endpoint URL from an elicited bucket name and a vendor-documented location code (fsn1, hel1, nbg1 per https://docs.hetzner.com/storage/object-storage/overview). The helper is the sole composer of the pattern <bucket>.<location>.your-objectstorage.com; every consumer that needs the endpoint imports this module and calls composeHetznerEndpoint({ bucket, location }). Downstream, the composed https URL feeds the shipped S3 client (TAC-2901 facade over @aws-sdk/client-s3 per ADR-2901) unchanged so the outward facade shape does not move for the Hetzner provider. The Cloudflare R2, AWS S3 and MinIO paths stay byte-identical: the endpoint URL parameter on the facade remains freeform and only projects that elicit hetznerObjectStorage consume this helper.",
+  "responsibilities": [
+    "Compose the endpoint URL as https://<bucket>.<location>.your-objectstorage.com from an elicited bucket and location code per the vendor overview (AC-28110-1).",
+    "Refuse composition when the location code is not one of the vendor-documented values (fsn1, hel1, nbg1) so the applying project cannot silently ship an invalid endpoint (AC-28110-1).",
+    "Expose one named export composeHetznerEndpoint that returns the composed URL string; hold no S3 client reference so a future adapter or endpoint variant slots in as a helper module swap without changing this contract (AC-28110-1).",
+    "Read no SIMULATE_ environment variable in the helper module body; INPUT-side mutation (SIMULATE_HETZNER_ENDPOINT_MISSHAPEN) lives on the fixture-side shim, keeping the helper deterministic and probe-neutral (AC-28110-1)."
+  ],
+  "internalStructure": "One module exporting composeHetznerEndpoint({ bucket, location }) -> string. The function validates the bucket against the S3 bucket-name discipline the shipped facade already accepts and validates the location against the enum {fsn1, hel1, nbg1} sourced verbatim from the Hetzner Object Storage overview page. On invalid input it throws a named Error whose message names the offending field so a probe or a lint can surface it. The composed URL string is returned; no side effects, no client reference, no event emission.",
+  "interfaces": [
+    {
+      "name": "composeHetznerEndpoint",
+      "kind": "factory",
+      "description": "composeHetznerEndpoint({ bucket, location }) -> string. Returns https://<bucket>.<location>.your-objectstorage.com when bucket is a non-empty string and location is one of fsn1, hel1, nbg1; throws a named Error naming the invalid field otherwise."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Object-storage S3 facade",
+      "kind": "tac",
+      "tacId": "TAC-2901-object-storage-s3-facade",
+      "description": "The facade the composed URL feeds into as the elicited endpointUrl; the helper output is opaque at the facade boundary so the R2, AWS S3 and MinIO paths stay unchanged."
+    }
+  ],
+  "tradeoffs": "The helper holds the vendor pattern in code rather than in the applying project's config file. A vendor endpoint change (a new location code or a URL-shape update) is a helper edit and a version bump on this blueprint, not a project-side scramble. The three currently documented locations are hard-coded per the overview page; a future location addition ships as a minor bump on this blueprint (v1.2.0) not a project-side workaround. A project that needs a different endpoint shape for a non-Hetzner S3-compatible endpoint uses the elicited freeform endpointUrl on the facade directly and skips this helper.",
+  "createdAt": "2026-09-08T00:00:00.000Z",
+  "updatedAt": "2026-09-08T00:00:00.000Z"
+}