rcf-lite 0.20.0 → 0.22.0

package/blueprints/object-storage-s3/contributions/probes/run-r2-real-account-smoke.mjs

@@ -0,0 +1,4 @@
+import runProbe from './r2-real-account-smoke.mjs';
+import { runShim } from './probe-utils.mjs';
+const engine = { kind: 's3', image: 'cloudflare-r2', healthy: true };
+runShim('r2-real-account-smoke', engine, runProbe);

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "object-storage-s3-REQ-001",
+  "prdId": "PRD-001",
+  "title": "One facade module is the sole reader of the S3 client and opens on boot",
+  "description": "The application accesses object storage through a single facade module in the project's source tree that is the ONLY module in the tree that imports the S3 client (either @aws-sdk/client-s3 on Node targets or aws4fetch on Workers targets per ADR-2901). Every other module that touches object storage imports the facade and calls its named domain verbs; no other module holds the raw S3 client, an S3Client instance, or an aws4fetch AwsClient instance. On process boot, the facade opens the client against the elicited endpoint URL and bucket name, and once the first successful ready-check completes, emits a facadeReady lifecycle event carrying endpoint host and bucket name. The endpoint URL (a Cloudflare R2 URL, an AWS S3 URL, a MinIO URL, or any S3-compatible remote) and the bucket name are elicited at apply time.",
+  "category": "functional",
+  "domain": "object-storage",
+  "priority": "must",
+  "rationale": "A single facade is what turns the raw S3 client surface into an application-side surface with domain-shaped verbs. Multiple call sites reaching into the client directly produces a codebase where the endpoint, the credential-pair discipline, the event-emission discipline, and the multipart-threshold posture are all diffused across the tree. One facade means one place to test, one place to swap adapters (the Workers-side aws4fetch adapter slots in here without moving any AC), and one place where the object-storage code paths are discoverable.",
+  "tags": [
+    "blueprint:object-storage-s3",
+    "category:01-facade"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "object-storage-s3-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Put, get, delete, list contract on typed keys",
+  "description": "The facade exposes named domain verbs (putObject, getObject, deleteObject, listObjects) that take a typed key (a project-defined key namespace, not a raw string on the public surface where a typed alternative fits), a content-type string on put, and return either the object body (get), a boolean success (put, delete), or a paginated key listing (list). Every read and write goes through the S3 client's public request surface; no facade verb accepts a raw request object or a general-purpose passthrough from consumer code. The put verb emits objectPut with key, size, contentType, timestamp; the delete verb emits objectDeleted with key, timestamp.",
+  "category": "functional",
+  "domain": "object-storage",
+  "priority": "must",
+  "rationale": "Typed named domain verbs make the object-storage boundary auditable: consumer call sites are enumerable, and swapping the underlying adapter or endpoint has one place to change. A raw-request-passthrough on the public surface defeats the sole-reader discipline REQ-001 pins.",
+  "tags": [
+    "blueprint:object-storage-s3",
+    "category:02-put-get-delete-list"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "object-storage-s3-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Presigned-URL contract with bounded TTL",
+  "description": "The facade exposes a presignGetUrl verb that issues a presigned URL for GET against an existing key with a bounded TTL: default 15 minutes per ADR-2902, floor 1 minute, ceiling elicited by the operator with no shipped default. A presignedIssued lifecycle event fires with key, ttl (seconds), and timestamp on every issue. The URL is signed at the client edge with the applied credentials; a fetch of the URL within TTL returns the object body, and a fetch after TTL returns 403 or the storage-side 403-equivalent (MinIO returns 403 with an XML AccessDenied body; the R2 shape matches). No presigned PUT is shipped on the v1.0.0 surface; the multipart-upload path (REQ-004) is the shipped write-side above the threshold.",
+  "category": "functional",
+  "domain": "object-storage",
+  "priority": "must",
+  "rationale": "A presigned URL is the standard mechanism for delegating read access to an object without handing out credentials. A bounded TTL is generic enterprise practice: too-short and legitimate readers miss the window, too-long and a leaked URL is a persistent breach. 15 minutes as the default matches the AWS SDK default; the 1-minute floor is a defensive against copy-paste ADRs.",
+  "tags": [
+    "blueprint:object-storage-s3",
+    "category:03-presigned-url"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "object-storage-s3-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Multipart-upload contract above an elicited threshold",
+  "description": "For payloads above the elicited threshold (default 8 MiB per ADR-2903), the facade's put path switches transparently to multipart-upload: initiate multipart upload, part-upload each chunk with a stable part number and returned ETag, complete-multipart-upload with the ordered part list. A part-upload failure aborts the in-flight upload (AbortMultipartUpload) before propagating the error; leaving an incomplete multipart upload behind is not the shipped path. On completion the objectPut lifecycle event fires with the final total size. Multipart re-upload semantics (per the R2 doc, a re-upload to the same part number replaces the previous with loss-on-fail) is a documented gotcha named in the README; the multipart-upload probe asserts an end-to-end round-trip of at least 10 MiB.",
+  "category": "functional",
+  "domain": "object-storage",
+  "priority": "must",
+  "rationale": "S3-shape storage caps single-put at 5 GiB; multipart is the required path for larger objects and the pragmatic path above ~8 MiB where the AWS SDK's own multi-part-transferer switches by default. Shipping the multipart-upload as a facade concern (not a consumer concern) keeps consumer code shape-stable across payload sizes.",
+  "tags": [
+    "blueprint:object-storage-s3",
+    "category:04-multipart"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "object-storage-s3-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Lifecycle events at four moments with metadata-only fields",
+  "description": "The facade emits four lifecycle events on the injected event sink: facadeReady (endpoint host, bucket name, timestamp), objectPut (key, size, contentType, timestamp), objectDeleted (key, timestamp), presignedIssued (key, ttl, timestamp). No event record carries object body bytes, no body checksum, no user id fields beyond what appears in the key itself, no PII drawn from the object body, and no adapter internal state. The event sink is a synchronous callback the operator wires; the facade never invokes it with domain-row values or authentication tokens. TAC-2903 realises the event-sink contract; the event-secrecy probe asserts field-level whitelist compliance against a PII fixture.",
+  "category": "functional",
+  "domain": "object-storage",
+  "priority": "must",
+  "rationale": "The event sink is the observability seam the applied logger and error-handling companions bind to. A leak of object body or PII through the event sink defeats every downstream redaction the logger applies. The metadata-only rule is the field-level whitelist the event-secrecy probe enforces.",
+  "tags": [
+    "blueprint:object-storage-s3",
+    "category:05-lifecycle-events"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "object-storage-s3-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Credential-pair discipline via security-secrets-management; refuses composition without",
+  "description": "The credential pair (accessKeyId, secretAccessKey) required to sign S3 requests is a secretRef value delegated to security-secrets-management: an opaque string agreed between object-storage-s3 and security-secrets-management naming the secret entry, never the credential value itself. The apply verb refuses composition on a project that has NOT applied security-secrets-management with exit code 3 and the stable message id object-storage-s3-no-secrets on stderr, per infra round 5 spec section 5.2 (Baz decision 6). The refusal names the required predecessor blueprint (security-secrets-management) and the override flag (--allow-no-secrets-yet). The override records a note on the applied blueprint's source.notes so rcf define validate can later flag the surface as not-yet-activated. The compose-test path checks the pair through the applied secrets facade before the object-store facade opens.",
+  "category": "security",
+  "domain": "object-storage",
+  "priority": "must",
+  "rationale": "A project that skips secrets-management and hardcodes the credential pair defeats the discipline; the compose-time refusal is the mechanism that makes the discipline reach through the mechanism-reach principle. The override records a note, not a bypass, so the operator later reconciles.",
+  "tags": [
+    "blueprint:object-storage-s3",
+    "category:06-credentials"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/tacs/tac-2901-object-storage-s3-facade.json

@@ -0,0 +1,57 @@
+{
+  "tacId": "TAC-2901-object-storage-s3-facade",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Object-storage S3 facade",
+  "purpose": "The single project-side module that imports the S3 client (either @aws-sdk/client-s3 on Node targets or aws4fetch on Workers targets per ADR-2901), exposes narrow named domain verbs to consumer code (putObject, getObject, deleteObject, listObjects, presignGetUrl), delegates payloads above the ADR-2903 threshold to the multipart-uploader (TAC-2902), and emits structured lifecycle events to the event sink (TAC-2903). Consumers never destructure the S3 client outside this module; the facade is the one place the vendor surface lives. The adapter reference is opaque at this boundary so a Workers-side aws4fetch adapter or a future adapter (a GCS shim, an Azure Blob shim) slots in without a facade re-shape.",
+  "responsibilities": [
+    "Open the S3 client on boot against the elicited endpoint URL and bucket name; hold no other reference to the S3 vendor surface; export no symbol that leaks the raw client (AC-28101-1, AC-28101-2).",
+    "Expose named domain verbs (putObject, getObject, deleteObject, listObjects, presignGetUrl) as named exports with typed parameters; refuse a raw-request passthrough on the public surface (AC-28102-1, AC-28102-2, AC-28102-3).",
+    "Route payloads above the elicited ADR-2903 threshold through the multipart uploader (TAC-2902); on part-upload failure, AbortMultipartUpload before propagating the error (AC-28104-1, AC-28104-2).",
+    "Issue presigned GET URLs with a bounded TTL (floor 1 minute, default 15 minutes per ADR-2902, ceiling elicited); emit presignedIssued on the sink (AC-28103-1).",
+    "Emit facadeReady exactly once per facade instance on the injected event sink with endpointHost and bucketName; serialise pre-ready consumer verbs behind the ready-check (AC-28101-1).",
+    "Consume the credential pair as an opaque secretRef through the applied security-secrets-management surface; never accept a plain-value credential on the public surface (AC-28106-1, AC-28106-2)."
+  ],
+  "internalStructure": "One module exporting a createObjectStore({ endpointUrl, bucket, credentialsRef, adapter, multipartThresholdBytes, defaultPresignTtlSeconds, onEvent }) factory returning an ObjectStore whose methods are the named domain verbs. The S3 client import lives at the top of this module; the factory captures a client instance keyed to the elicited endpoint and bucket, wires the sink, and hands back closures. Consumers destructure the verbs they need at their top level and hold the facade reference for the process lifetime.",
+  "interfaces": [
+    {
+      "name": "createObjectStore",
+      "kind": "factory",
+      "description": "createObjectStore({ endpointUrl, bucket, credentialsRef, adapter, multipartThresholdBytes, defaultPresignTtlSeconds, onEvent }) -> ObjectStore. The sole entry point every consumer calls. Opens the S3 client against endpointUrl and bucket; wires the sink; hands back an ObjectStore whose methods are the named domain verbs."
+    },
+    {
+      "name": "onEvent",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with { event, ts, ... } for facadeReady, objectPut, objectDeleted, presignedIssued events. Never invoked with object body values or credential material."
+    },
+    {
+      "name": "store.verbs",
+      "kind": "read-write-api",
+      "description": "The named domain verbs the facade exposes: putObject(key, contentType, body), getObject(key), deleteObject(key), listObjects(prefix, continuationToken), presignGetUrl(key, ttlSeconds)."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Multipart uploader",
+      "kind": "tac",
+      "tacId": "TAC-2902-object-storage-s3-multipart-uploader",
+      "description": "The helper the facade delegates to for payloads above the ADR-2903 threshold; handles initiate, part-upload, complete-multipart-upload, abort-on-error."
+    },
+    {
+      "name": "Event sink",
+      "kind": "tac",
+      "tacId": "TAC-2903-object-storage-s3-event-sink",
+      "description": "The lifecycle-event sink contract the facade emits through with metadata-only field discipline."
+    },
+    {
+      "name": "Credential pair via security-secrets-management",
+      "kind": "external",
+      "description": "The applied security-secrets-management blueprint supplies the credential pair as an opaque secretRef the facade dereferences at boot; the compose-test path refuses composition when the predecessor is not applied."
+    }
+  ],
+  "tradeoffs": "The facade holds a single client instance per bucket at v1.0.0; a project needing multiple buckets creates multiple facade instances. The adapter reference is opaque at ADR-2901 so a future aws4fetch adapter or GCS/Azure shim slots in as a per-target module swap; the outward interface stays unchanged.",
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/tacs/tac-2902-object-storage-s3-multipart-uploader.json

@@ -0,0 +1,36 @@
+{
+  "tacId": "TAC-2902-object-storage-s3-multipart-uploader",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Multipart uploader",
+  "purpose": "The helper the facade delegates to for payloads above the ADR-2903 threshold. Wraps CreateMultipartUpload, UploadPart (one per chunk), CompleteMultipartUpload, and AbortMultipartUpload on error into a single put verb the facade calls. Holds the multipart-upload id and part list in memory for the duration of the upload; guarantees an Abort on any thrown error before propagating the rejection, so no orphan in-flight upload remains on the bucket.",
+  "responsibilities": [
+    "Chunk the payload into fixed-size parts sized to the ADR-2903 threshold (default 8 MiB) with a final smaller-tail part if applicable (AC-28104-1).",
+    "Issue CreateMultipartUpload against the bucket and key; capture the returned UploadId (AC-28104-1).",
+    "Issue UploadPart for each chunk with a stable one-based PartNumber and stream the ETag responses into the part list (AC-28104-1).",
+    "On any UploadPart failure, issue AbortMultipartUpload with the captured UploadId before propagating the error to the caller; the abort is best-effort but is always attempted (AC-28104-2).",
+    "On successful upload of every part, issue CompleteMultipartUpload with the ordered part list; the get after complete returns the payload at full size (AC-28104-1).",
+    "Emit no lifecycle events itself; the outer facade owns event emission on completion (AC-28104-1)."
+  ],
+  "internalStructure": "One module exporting a putMultipart({ client, bucket, key, contentType, body, partSizeBytes }) async function. The function iterates the payload in partSizeBytes chunks, awaits UploadPart per chunk, and awaits CompleteMultipartUpload on success or AbortMultipartUpload on any thrown error. The UploadId and part-etag list are held in local scope; no state escapes across concurrent uploads.",
+  "interfaces": [
+    {
+      "name": "putMultipart",
+      "kind": "function",
+      "description": "putMultipart({ client, bucket, key, contentType, body, partSizeBytes }) -> Promise<{size, etag}>. Throws on any part-upload failure after AbortMultipartUpload attempts to clean up."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Facade",
+      "kind": "tac",
+      "tacId": "TAC-2901-object-storage-s3-facade",
+      "description": "The facade owns the S3 client instance and the elicited bucket; it passes both to the multipart uploader on invocation and owns event emission after completion."
+    }
+  ],
+  "tradeoffs": "The uploader holds the full payload in memory chunk-by-chunk at v1.0.0; a streaming-source variant lands as a v1.1 minor when a project needs it. The abort on part-upload failure is best-effort per the R2 doc semantics (re-uploads to the same part number replace the previous with loss-on-fail); the README names the gotcha.",
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/tacs/tac-2903-object-storage-s3-event-sink.json

@@ -0,0 +1,36 @@
+{
+  "tacId": "TAC-2903-object-storage-s3-event-sink",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Lifecycle event sink",
+  "purpose": "The lifecycle-event sink contract the facade emits through, with a fixed metadata-only field discipline. Consumers wire the sink as a synchronous callback; the facade never invokes the sink with object body values, credential material, or PII fields drawn from the object body. The event-secrecy probe (AC-28105-1) asserts the whitelist against a PII fixture.",
+  "responsibilities": [
+    "Emit facadeReady exactly once per facade instance with { event, ts, endpointHost, bucketName } (AC-28101-1).",
+    "Emit objectPut on every successful put (single-part or multipart) with { event, ts, key, size, contentType } (AC-28102-1, AC-28104-1).",
+    "Emit objectDeleted on every successful delete with { event, ts, key } (AC-28102-2).",
+    "Emit presignedIssued on every presign with { event, ts, key, ttl } (AC-28103-1).",
+    "Never carry a body bytes field, a body checksum field, a userId field, a ssn field, an email field, or any string drawn from the object body itself (AC-28105-1).",
+    "Be synchronous and idempotent from the sink caller side; the facade does not await the sink return value."
+  ],
+  "internalStructure": "A callback function type onEvent(record) invoked by the facade with a minimum-shape record. Records are plain objects with only the whitelisted fields; the facade never spreads an S3 client response or an internal buffer into a record. The event-secrecy probe walks every field name and every field value on every emitted record.",
+  "interfaces": [
+    {
+      "name": "onEvent",
+      "kind": "callback",
+      "description": "onEvent(record: {event: 'facadeReady' | 'objectPut' | 'objectDeleted' | 'presignedIssued', ts: number, [k: string]: any}) -> void. Consumers pass the callback to createObjectStore; the facade calls it synchronously at the moment of the event."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Facade",
+      "kind": "tac",
+      "tacId": "TAC-2901-object-storage-s3-facade",
+      "description": "The facade owns the sink invocation; the sink itself is a caller-supplied callback with no dependencies of its own."
+    }
+  ],
+  "tradeoffs": "The whitelist is defined in prose and enforced by probe rather than by a schema, at v1.0.0. A rcf-schemas minor may promote the event-record shape into a shared schema; the round-2 amendment posture (deferred to two-consumer agreement) applies.",
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/user-stories/object-storage-s3-us-28101.json

@@ -0,0 +1,34 @@
+{
+  "usId": "object-storage-s3-US-28101",
+  "prdId": "PRD-001",
+  "reqId": "object-storage-s3-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "One facade module opens the S3 client on boot and emits facadeReady with endpoint host and bucket name",
+  "asA": "developer whose service needs S3-shape object storage behind a swappable boundary",
+  "iWant": "one facade module to hold the S3 client and expose named domain verbs, with a facadeReady lifecycle event on the first successful ready-check",
+  "soThat": "the boundary between my domain and the S3 vendor surface is the only place that has to move when the adapter changes, and boot ordering is observable via the event",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-28101-1",
+      "description": "On process boot, the facade opens an S3 client against the elicited endpoint URL and bucket name; once the first successful ready-check (a HeadBucket or equivalent metadata call) returns, a facadeReady event fires on the injected event sink with a payload containing endpoint host and bucket name.",
+      "given": "a Node process with the facade module imported and its factory invoked",
+      "when": "the process boots and the facade's ready-check returns",
+      "then": "a facadeReady event fires on the injected event sink with a payload containing endpointHost and bucketName, and the client is ready to accept verbs; the facade exposes named domain verbs and does not re-export the raw S3 client",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-28101-2",
+      "description": "Exactly one source-tree module inside the facade directory imports the S3 client (@aws-sdk/client-s3 or aws4fetch per ADR-2901); every other module that touches object storage imports the facade and calls its named domain verbs, verified by a targeted grep on the applied fixture.",
+      "given": "the applied project's source tree after apply",
+      "when": "grep 'from \\'@aws-sdk/client-s3\\'' or 'from \\'aws4fetch\\'' walks the tree outside the facade directory",
+      "then": "no match is found outside the facade directory; the facade's public surface exports named domain verbs only, no raw S3 client reference",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2901-object-storage-s3-facade"],
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/user-stories/object-storage-s3-us-28102.json

@@ -0,0 +1,43 @@
+{
+  "usId": "object-storage-s3-US-28102",
+  "prdId": "PRD-001",
+  "reqId": "object-storage-s3-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The facade puts, gets, deletes and lists on typed keys with byte-equal round-trip",
+  "asA": "developer storing user uploads and generated artefacts as S3-shape objects",
+  "iWant": "put, get, delete, list verbs on the facade that round-trip bytes without corruption and emit lifecycle events",
+  "soThat": "my consumer code stays vendor-neutral above the facade and observability wires cleanly",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-28102-1",
+      "description": "Given a putObject through the facade for a known key, a stable content-type, and a 1 KiB payload, when a subsequent getObject reads the key, then the returned bytes equal the put bytes and the content-type header matches; an objectPut lifecycle event fires with key, size=1024, contentType, timestamp.",
+      "given": "the facade opened against a running S3-compatible engine and a bucket that exists",
+      "when": "putObject(key, contentType='application/octet-stream', body=<1 KiB Buffer>) then getObject(key)",
+      "then": "the returned body's byte length equals 1024 and the returned content-type equals application/octet-stream; the events list captured on the sink contains an objectPut record with matching key, size 1024, contentType, timestamp; no body bytes appear in any event record",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-28102-2",
+      "description": "Given a deleteObject through the facade for a known key that exists, when the delete returns, then a getObject on the same key returns a not-found error (S3 NoSuchKey or the storage-side 404-equivalent); an objectDeleted event fires with the key and timestamp.",
+      "given": "an object previously put through the facade",
+      "when": "deleteObject(key) followed by getObject(key)",
+      "then": "the getObject rejects with a not-found shape (NoSuchKey on S3/R2/MinIO); an objectDeleted event fires on the sink with matching key and timestamp",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-28102-3",
+      "description": "Given at least three objects put under a common key prefix, when listObjects(prefix) is called, then the returned page contains every put key at or under the prefix and a boolean isTruncated indicating whether more pages exist.",
+      "given": "three keys previously put under prefix probe/list/",
+      "when": "listObjects(prefix='probe/list/')",
+      "then": "the returned keys include every put key with matching prefix, and the paginated envelope carries an isTruncated boolean",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2901-object-storage-s3-facade"],
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/user-stories/object-storage-s3-us-28103.json

@@ -0,0 +1,25 @@
+{
+  "usId": "object-storage-s3-US-28103",
+  "prdId": "PRD-001",
+  "reqId": "object-storage-s3-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The facade issues presigned GET URLs with bounded TTL; a fetch within TTL returns 200 and after TTL returns 403",
+  "asA": "developer handing delegated read access to a browser client",
+  "iWant": "presignGetUrl on the facade with a bounded TTL and a lifecycle event on issue",
+  "soThat": "the browser fetches the object directly from the storage endpoint without holding my credentials, and my logs can bind to the issue event",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-28103-1",
+      "description": "Given a presignGetUrl call with ttl=60 seconds for a known key, when the returned URL is fetched with Node built-in fetch within TTL, then the response status is 200 and the body bytes equal the object bytes; when the same URL is fetched after ttl+2 seconds, the response status is 403 (S3-shape AccessDenied) or the storage-side 403-equivalent; a presignedIssued event fires on the sink with key, ttl=60, timestamp.",
+      "given": "an object previously put through the facade and the facade opened",
+      "when": "presignGetUrl(key, ttl=60) then fetch(url) immediately, then wait ttl+2 seconds and fetch(url) again",
+      "then": "first fetch returns 200 with body bytes equal to the put payload; second fetch returns 403; the events list contains a presignedIssued record with key, ttl=60, timestamp; no URL or credential material appears in any event record",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2901-object-storage-s3-facade"],
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/user-stories/object-storage-s3-us-28104.json

@@ -0,0 +1,34 @@
+{
+  "usId": "object-storage-s3-US-28104",
+  "prdId": "PRD-001",
+  "reqId": "object-storage-s3-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The facade multipart-uploads payloads above the elicited threshold and rounds-trip byte-equal",
+  "asA": "developer uploading large payloads (attachments, generated reports, backups)",
+  "iWant": "the facade to switch to multipart upload above the elicited threshold, and to abort in-flight multipart on failure",
+  "soThat": "my consumer code stays shape-stable across sizes and I do not leave orphan multipart uploads behind",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-28104-1",
+      "description": "Given the elicited multipart threshold at 8 MiB (ADR-2903 default), when putObject is called with a 10 MiB payload, then the facade switches to multipart-upload (initiate, part-upload, complete), the get returns byte-equal 10485760 bytes back, and an objectPut event fires with size 10485760 and timestamp.",
+      "given": "the facade opened against a running S3-compatible engine, threshold=8 MiB",
+      "when": "putObject(key, contentType, body=<10 MiB Buffer>) then getObject(key)",
+      "then": "the getObject returns a body of exact size 10485760 with byte equality to the put payload; the events list contains one objectPut record with size=10485760; no ListMultipartUploads on the bucket surfaces an in-flight upload after completion",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-28104-2",
+      "description": "Given a simulated part-upload failure mid-multipart (SIMULATE_PART_UPLOAD_FAIL fixture switch), when putObject is called with a 10 MiB payload, then the facade issues AbortMultipartUpload before propagating the error, and a subsequent ListMultipartUploads on the bucket surfaces zero in-flight uploads for the key.",
+      "given": "the facade opened, threshold=8 MiB, SIMULATE_PART_UPLOAD_FAIL=true",
+      "when": "putObject(key, contentType, body=<10 MiB Buffer>) rejects mid-upload",
+      "then": "the rejection propagates to the caller; a probe-side ListMultipartUploads(prefix=key) returns zero uploads; no completed object appears at key",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2902-object-storage-s3-multipart-uploader"],
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/user-stories/object-storage-s3-us-28105.json

@@ -0,0 +1,25 @@
+{
+  "usId": "object-storage-s3-US-28105",
+  "prdId": "PRD-001",
+  "reqId": "object-storage-s3-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Lifecycle event records carry metadata only; no body, no user id, no PII",
+  "asA": "operator wiring the logger and error-handling companions to the object-storage facade",
+  "iWant": "every lifecycle event record to carry a fixed metadata-only shape",
+  "soThat": "downstream loggers cannot leak object body bytes, user ids, or PII drawn from the object body",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-28105-1",
+      "description": "Given a lifecycle-event spy attached to the sink, when put, get, delete, and presign verbs run against a PII fixture (key users/1234/passport.jpg, body carrying the PII fixture text), then every event record on the sink carries only fields from the whitelist {event, key, size, contentType, ttl, timestamp, endpointHost, bucketName}; no field name matches userId or ssn or dob or email; no field value contains the PII fixture body text; no field value contains any part of the object body bytes.",
+      "given": "the facade opened, a spy on the event sink, a PII fixture body PII-FIXTURE-DO-NOT-LOG",
+      "when": "putObject(users/1234/passport.jpg, image/jpeg, <body containing PII-FIXTURE-DO-NOT-LOG>), then getObject, then presignGetUrl, then deleteObject",
+      "then": "every event record on the sink has keys drawn from the whitelist above; no event value contains the string PII-FIXTURE-DO-NOT-LOG; no event value contains a userId, ssn, dob, or email field; the key users/1234/passport.jpg appears on records as the key field only (not decomposed into userId)",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2903-object-storage-s3-event-sink"],
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/user-stories/object-storage-s3-us-28106.json

@@ -0,0 +1,34 @@
+{
+  "usId": "object-storage-s3-US-28106",
+  "prdId": "PRD-001",
+  "reqId": "object-storage-s3-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Apply-time refusal on a project without security-secrets-management, with a stable message id and an override flag",
+  "asA": "operator preventing hardcoded credential pairs on a new project",
+  "iWant": "rcf define blueprint add object-storage-s3 to refuse composition when security-secrets-management is not applied",
+  "soThat": "credential storage is disciplined by default and the override is an explicit note the operator later reconciles",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-28106-1",
+      "description": "Given a fresh scratch project with no security-secrets-management applied, when rcf define blueprint add ./blueprints/object-storage-s3 runs, then the command exits 3 and stderr contains the stable message id object-storage-s3-no-secrets, the required predecessor blueprint name security-secrets-management, and the override flag --allow-no-secrets-yet; the scratch project's rcf tree does not carry object-storage-s3 contributions after the refusal.",
+      "given": "a fresh rcf init scratch project with no security-secrets-management applied",
+      "when": "rcf define blueprint add ./blueprints/object-storage-s3 runs against the scratch project",
+      "then": "the command exits 3; stderr contains the string object-storage-s3-no-secrets; stderr names security-secrets-management and the --allow-no-secrets-yet flag; the scratch tree has zero object-storage-s3 requirements after the refusal",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-28106-2",
+      "description": "Given the same fresh scratch project, when rcf define blueprint add ./blueprints/object-storage-s3 --allow-no-secrets-yet runs, then the command exits 0, the contributions land on the scratch tree, and the applied manifest records a source.notes entry naming the missing predecessor for later reconciliation.",
+      "given": "a fresh rcf init scratch project with no security-secrets-management applied",
+      "when": "rcf define blueprint add ./blueprints/object-storage-s3 --allow-no-secrets-yet runs against the scratch project",
+      "then": "the command exits 0; the applied manifest entry for object-storage-s3 carries a source.notes string naming the security-secrets-management predecessor and the --allow-no-secrets-yet override; the contributions land on disk",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2901-object-storage-s3-facade"],
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/user-stories/object-storage-s3-us-28107.json

@@ -0,0 +1,34 @@
+{
+  "usId": "object-storage-s3-US-28107",
+  "prdId": "PRD-001",
+  "reqId": "object-storage-s3-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Round-trip against MinIO in the shared sample-app fixture; five local probes pass end-to-end",
+  "asA": "gate reviewer running the ship gate for object-storage-s3 in CI",
+  "iWant": "the five local Node-only probes to pass against a real MinIO container brought up from the shared infra-s3-and-queue fixture",
+  "soThat": "every runtime-observable AC has a live-engine verdict on file at ship time",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-28107-1",
+      "description": "Given docker compose up -d minio from packages/rcf-lite/test/fixtures/infra-s3-and-queue/, when each of the five run-<probe>.mjs shims runs in sequence (facade-round-trip, put-get-round-trip, presigned-url, multipart-upload, event-secrecy), then each shim exits 0 and writes .rcf/reports/blueprints/object-storage-s3/<probe>.json with aggregateVerdict pass; every result carries an anchorAcId matching a contributed AC id on the blueprint.",
+      "given": "the shared fixture with docker compose up -d minio running and MinIO healthy on port 9000",
+      "when": "run-facade-round-trip.mjs, run-put-get-round-trip.mjs, run-presigned-url.mjs, run-multipart-upload.mjs, run-event-secrecy.mjs run in sequence",
+      "then": "each shim exits 0; each per-blueprint report at .rcf/reports/blueprints/object-storage-s3/<probe>.json carries aggregateVerdict pass; every result carries an anchorAcId matching a contributed AC id",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-28107-2",
+      "description": "Given the shared fixture, when each of the four wired induced-failure switches is set (SIMULATE_MINIO_DOWN, SIMULATE_403_ON_GET, SIMULATE_PART_UPLOAD_FAIL, SIMULATE_PRESIGN_MALFORMED) and the paired probe runs, then that probe's aggregate verdict flips from pass to fail on the AC anchored to the observation the switch corrupts.",
+      "given": "the shared fixture with MinIO running",
+      "when": "each induced-failure switch is set in turn and the paired probe runs",
+      "then": "the paired probe exits non-zero and the aggregate verdict lands as fail on the anchored AC; the fixture README documents the paired switch and probe for each of the four wired switches",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2901-object-storage-s3-facade", "TAC-2902-object-storage-s3-multipart-uploader", "TAC-2903-object-storage-s3-event-sink"],
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/user-stories/object-storage-s3-us-28108.json

@@ -0,0 +1,34 @@
+{
+  "usId": "object-storage-s3-US-28108",
+  "prdId": "PRD-001",
+  "reqId": "object-storage-s3-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "R2 real-account smoke as an accountBound probe that skips cleanly without CI_HAS_CLOUDFLARE_ACCOUNT",
+  "asA": "gate reviewer running the ship gate without a Cloudflare-account CI secret",
+  "iWant": "r2-real-account-smoke to record accountBoundSkipped:true with verdict pass when CI_HAS_CLOUDFLARE_ACCOUNT is unset, and to run a real round-trip against R2 when it is set",
+  "soThat": "the gate stays green on contributors without a Cloudflare account and still proves the R2 adapter on a bound runner",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-28108-1",
+      "description": "Given CI_HAS_CLOUDFLARE_ACCOUNT is unset, when the r2-real-account-smoke.mjs shim runs, then the shim exits 0 and writes a per-blueprint report with one result carrying verdict pass, detail accountBound: skipped (no CI_HAS_CLOUDFLARE_ACCOUNT), and accountBoundSkipped: true; aggregateVerdict is pass.",
+      "given": "the environment with CI_HAS_CLOUDFLARE_ACCOUNT unset",
+      "when": "node blueprints/object-storage-s3/contributions/probes/run-r2-real-account-smoke.mjs runs",
+      "then": "the shim exits 0; the report at .rcf/reports/blueprints/object-storage-s3/r2-real-account-smoke.json carries aggregateVerdict pass and a single result with accountBoundSkipped true",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-28108-2",
+      "description": "Given CI_HAS_CLOUDFLARE_ACCOUNT set alongside a real R2 endpoint URL, bucket name, and credential pair (all from security-secrets-management), when the r2-real-account-smoke.mjs shim runs, then the facade opens against the R2 bucket, puts a 1 KiB payload, gets it back byte-equal, deletes the temporary object on exit, and the report carries aggregateVerdict pass with accountBoundSkipped absent or false.",
+      "given": "the environment with CI_HAS_CLOUDFLARE_ACCOUNT set and R2 credentials wired via security-secrets-management",
+      "when": "node blueprints/object-storage-s3/contributions/probes/run-r2-real-account-smoke.mjs runs",
+      "then": "the shim exits 0; the temporary object is deleted after the round-trip; the report carries aggregateVerdict pass and no accountBoundSkipped:true field",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2901-object-storage-s3-facade"],
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/docs/topics.md

@@ -0,0 +1,62 @@
+# object-storage-s3 blueprint coordination vocabulary
+
+This file is the object-storage-s3 half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | object-storage-s3 contribution | Origin | Composition note |
+|---|---|---|---|
+| `objectStorageContract` | ADR-2904-object-storage-s3-contract | Minted by this blueprint. Names the wire-shape contract for object storage; the shipped answer is the AWS S3 API (per https://developers.cloudflare.com/r2/api/s3/api/ Cloudflare R2 is S3-compatible and per https://docs.min.io/community/minio-object-store/administration/object-management/object-lifecycle-management.html MinIO derives from the same shape). | The one project-wide decision on the wire-shape contract for object storage. A future non-S3-shape sibling (`object-storage-native-gcs`, `object-storage-native-azure`) would contribute the same topic string with a different answer, forcing a DELIBERATE conflict the operator resolves with a project-level ADR |
+
+The object-storage-s3 blueprint claims one global topic. Every other contribution is scope-local (ADR-2901 adapter, ADR-2902 presigned TTL floor, ADR-2903 multipart threshold do not contribute global topics; a composing blueprint that holds an opinion on any of them authors its own project-level ADR).
+
+Rules for new topics: lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer.
+
+## Id number bands (registry bootstrap)
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
+| observability-essentials | 7101-7899 | 8xx | shipped v2.0.0 | `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.1 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| observability-logging | 15101-15899 | 16xx | shipped v1.0.0 | `logging` |
+| application-error-handling | 16101-16899 | 17xx | shipped v1.0.0 | `errorHandling` |
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
+| application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
+| application-admin-console | 21101-21899 | 22xx | shipped v1.0.0 | none |
+| application-empty-error-states | 22101-22899 | 23xx | shipped v1.0.0 | none |
+| application-forms-wizard | 24101-24899 | 25xx | shipped v1.0.0 | none |
+| application-account-settings | 25101-25899 | 26xx | shipped v1.0.0 | none |
+| application-onboarding-tour | 26101-26899 | 27xx | 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` |
+
+US 28101-28108 sit at the LOW end of the 28101-28899 band on purpose (watchpost run-4 lesson). A project-side story mechanically derived from an object-storage-s3 REQ id into the number 28110 would collide against a shipped US-28110; band headroom (28109-28899) leaves that space.
+
+ADR/TAC suffixes for this blueprint use the 2901-2999 block, continuing the shelf pattern.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `objectStorageContract` exactly as spelled here when your blueprint holds an opinion on the wire-shape contract for object storage; contribute your own scope:global ADR on that string and let composition surface the pairing.
+- A future `object-storage-native-gcs` or `object-storage-native-azure` sibling mints on demand; it composes on `security-secrets-management` for its own credential pair (same discipline as this blueprint) and conflicts by design on `objectStorageContract`.
+- Consumer blueprints storing large binary payloads (uploads, attachments, generated reports) read the `objectStorage` capability declared on `blueprint.json` per section 6a of `blueprint-authoring.md`.
+
+## Deliberate-conflict statement
+
+This blueprint's ADR-2904 on `objectStorageContract` is a first shipped answer to a topic that will conflict, by design, with future non-S3-shape siblings. Applying `object-storage-s3` alongside a hypothetical `object-storage-native-gcs` raises one `globalAdrTopic` conflict the operator resolves via one of the four documented resolutions per topic (adopt one, keep the existing one, author a project-level supersede ADR, or `--resolve <topic>=project:<ADR-id>` on the add).