rcf-lite 0.23.0 → 0.25.0

package/rcf/user-stories/us-12101.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T01:41:59.208Z",
+  "updatedAt": "2026-09-08T01:42:32.309Z",
+  "usId": "US-12101",
+  "prdId": "PRD-001",
+  "reqId": "REQ-121",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-2 secrets flow via docker compose secrets file mounts (no plaintext literal in compose.yaml)",
+  "asA": "shelf consumer applying the platform-docker-compose-host v1.0.0 blueprint on a project with secret material bound to a container",
+  "iWant": "every secret to be declared under the compose secrets top-level key and mounted into the service via secrets: rather than inlined as an environment literal",
+  "soThat": "the compose file is safe to read at review time and the mounted file inherits 0o400 inside the container",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12101-1",
+      "description": "The fixture compose.yaml declares at least one secret under the top-level secrets key with a file: source, references it from the web service through the service-level secrets: array, and no plaintext value for that secret appears anywhere in compose.yaml (grep-refuses on the literal). The secret file mode is 0o400 inside the container.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-3902-platform-docker-compose-host-secrets-mount"
+  ]
+}

package/rcf/user-stories/us-12102.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T01:44:43.238Z",
+  "updatedAt": "2026-09-08T01:44:43.862Z",
+  "usId": "US-12102",
+  "prdId": "PRD-001",
+  "reqId": "REQ-121",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-2 cross-cutting secretsAreFiles: the source-tree scan refuses any plaintext secret literal in compose.yaml or a referenced service config",
+  "asA": "shelf consumer applying the platform-docker-compose-host v1.0.0 blueprint on a project with sensitive material",
+  "iWant": "the secrets-as-files probe to walk compose.yaml and every service config in the fixture and refuse on any plaintext secret literal, naming the file and line",
+  "soThat": "a secret accidentally inlined in a review is caught by the probe before docker compose up runs",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12102-1",
+      "description": "The secrets-as-files-scan probe walks compose.yaml plus every referenced service config file in the fixture and asserts (a) no line contains a plaintext token pattern (the applied literal name plus the applied literal value), (b) every declared secret in the compose secrets: key has a file: source, and (c) SIMULATE_PLAINTEXT_SECRET=true writes a plaintext literal into compose.yaml and the probe FAILS naming the file and the literal.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-3902-platform-docker-compose-host-secrets-mount"
+  ]
+}

package/rcf/user-stories/us-12201.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T01:42:40.956Z",
+  "updatedAt": "2026-09-08T01:42:41.556Z",
+  "usId": "US-12201",
+  "prdId": "PRD-001",
+  "reqId": "REQ-122",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-2 healthcheck contract: docker compose config refuses when an HTTP-terminating service is missing a healthcheck block",
+  "asA": "shelf consumer applying the platform-docker-compose-host v1.0.0 blueprint on a project that terminates HTTP inside a container",
+  "iWant": "the compose config lint to refuse at gate time on any HTTP-terminating service that is missing a healthcheck block, naming the service",
+  "soThat": "the stack never comes up with a service the container host cannot know is ready",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12201-1",
+      "description": "The compose-config-lint probe shells to docker compose config against the fixture compose.yaml, asserts exit 0, and additionally asserts every HTTP-terminating service declares a healthcheck: block. SIMULATE_MISSING_HEALTHCHECK=true strips the block from the web service and the probe FAILS naming the service.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-3903-platform-docker-compose-host-healthcheck-lint"
+  ]
+}

package/rcf/user-stories/us-12202.json

@@ -0,0 +1,24 @@
+{
+  "createdAt": "2026-09-08T01:42:41.742Z",
+  "updatedAt": "2026-09-08T01:42:42.341Z",
+  "usId": "US-12202",
+  "prdId": "PRD-001",
+  "reqId": "REQ-122",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-2 cross-cutting upClean: the stack comes up clean and every declared service reaches healthy",
+  "asA": "shelf consumer applying the platform-docker-compose-host v1.0.0 blueprint on a Hetzner cloudHost",
+  "iWant": "the real-account minimal-stack-up probe to scp the compose.yaml to the throwaway server, run docker compose up -d --wait, and assert every declared service reaches healthy inside the elicited timeout",
+  "soThat": "the composeStackReady claim is proven on real docker before the blueprint ships",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12202-1",
+      "description": "The real-account-minimal-stack-up probe, when CI_HAS_HETZNER_ACCOUNT is set, provisions the throwaway server, scps the compose.yaml, runs docker compose up -d --wait, asserts every declared service reaches healthy inside the elicited timeout, and tears down the stack plus the server in always(). Without CI_HAS_HETZNER_ACCOUNT the probe records accountBoundSkipped: true and the aggregate flips to pass.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-3901-platform-docker-compose-host-compose-layout",
+    "TAC-3903-platform-docker-compose-host-healthcheck-lint"
+  ]
+}

package/rcf/user-stories/us-12301.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T01:42:42.527Z",
+  "updatedAt": "2026-09-08T01:42:43.125Z",
+  "usId": "US-12301",
+  "prdId": "PRD-001",
+  "reqId": "REQ-123",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-2 restart discipline: unless-stopped on long-running, on-failure on jobs; unclassified value refuses at lint",
+  "asA": "shelf consumer applying the platform-docker-compose-host v1.0.0 blueprint",
+  "iWant": "the compose config lint to enforce a restart policy on every service and refuse on any value outside the two allowed policies (unless-stopped for long-running, on-failure for jobs)",
+  "soThat": "the operator sees a wrong or missing restart policy at gate time rather than as a stuck container",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12301-1",
+      "description": "The compose-config-lint probe asserts every service in the compose.yaml declares a restart policy AND every declared value is one of unless-stopped or on-failure. SIMULATE_UNCLASSIFIED_RESTART=true sets restart: always on the web service and the probe FAILS naming the service and the disallowed value.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-3903-platform-docker-compose-host-healthcheck-lint"
+  ]
+}

package/rcf/user-stories/us-12401.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T01:42:43.312Z",
+  "updatedAt": "2026-09-08T01:42:43.912Z",
+  "usId": "US-12401",
+  "prdId": "PRD-001",
+  "reqId": "REQ-124",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-2 reverse-proxy config as a first-class versioned artefact (caddy/Caddyfile) validated by the vendor validator",
+  "asA": "shelf consumer applying the platform-docker-compose-host v1.0.0 blueprint with reverseProxy=caddy",
+  "iWant": "a checked-in caddy/Caddyfile bind-mounted into the proxy service so the reload verb picks up an operator change, validated at gate time by caddy validate",
+  "soThat": "a broken Caddyfile is caught before the reload burst runs, and there is one place in the tree the operator edits to route hostnames",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12401-1",
+      "description": "The fixture ships caddy/Caddyfile at the fixture root under a caddy/ directory, the compose file bind-mounts it read-only into the caddy service, and the caddyfile-validate probe shells to caddy validate against the file and asserts exit 0. SIMULATE_INVALID_CADDYFILE=true writes an invalid directive into a scratch copy and the probe FAILS naming the line. Skipped when the applied reverseProxy is not caddy.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-3904-platform-docker-compose-host-reverse-proxy-artefact"
+  ]
+}

package/rcf/user-stories/us-12402.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T01:42:44.098Z",
+  "updatedAt": "2026-09-08T01:42:44.701Z",
+  "usId": "US-12402",
+  "prdId": "PRD-001",
+  "reqId": "REQ-124",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-2 cross-cutting zeroDowntimeReload: a client burst against the proxy during a config reload sees no non-2xx and no dropped connection inside the elicited window",
+  "asA": "shelf consumer applying the platform-docker-compose-host v1.0.0 blueprint",
+  "iWant": "the real-account reload-burst probe to fire an undici burst against the reverse proxy while docker compose exec caddy caddy reload runs and assert no non-2xx or dropped connection inside the elicited window",
+  "soThat": "the zero-downtime reload claim is proven on real docker before the blueprint ships",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12402-1",
+      "description": "The real-account-reload-burst probe, when CI_HAS_HETZNER_ACCOUNT is set, runs undici GETs against the proxy service on the throwaway server while docker compose exec caddy caddy reload runs, asserts every request returns a 2xx status inside the elicited window (10 s default), asserts no dropped connection, tears the stack down in always(). Without CI_HAS_HETZNER_ACCOUNT the probe records accountBoundSkipped: true and the aggregate flips to pass.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-3904-platform-docker-compose-host-reverse-proxy-artefact"
+  ]
+}

package/rcf/user-stories/us-12501.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T01:42:44.888Z",
+  "updatedAt": "2026-09-08T01:42:45.499Z",
+  "usId": "US-12501",
+  "prdId": "PRD-001",
+  "reqId": "REQ-125",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-2 log shipping to the elicited observability-logging sink (journald default; loki opt-in)",
+  "asA": "shelf consumer applying the platform-docker-compose-host v1.0.0 blueprint on a project that may run Grafana or the estate default",
+  "iWant": "the elicited log driver to be wired into every service in the compose file (journald default, loki opt-in) and the choice recorded on the log-driver ADR",
+  "soThat": "the container stdout and stderr reach the applied observability sink without a per-service edit",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12501-1",
+      "description": "Every service in the fixture compose.yaml declares a logging: driver: block whose driver value matches the elicited log driver (default journald). The compose-config-lint probe asserts (a) every service declares logging: driver, (b) the value is one of journald or loki, and (c) SIMULATE_UNCLASSIFIED_LOG_DRIVER=true sets a disallowed driver and the probe FAILS naming the service and the disallowed value.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-3903-platform-docker-compose-host-healthcheck-lint"
+  ]
+}

package/rcf/user-stories/us-13001.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T03:21:16.415Z",
+  "updatedAt": "2026-09-08T03:21:16.415Z",
+  "usId": "US-13001",
+  "prdId": "PRD-001",
+  "reqId": "REQ-130",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-3 cloudflared connector install shape switches on applied containerHost (compose-service default; systemd-unit fallback for bare cloudHost)",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0 alongside deploy-hetzner-server (and optionally platform-docker-compose-host)",
+  "iWant": "the cloudflared connector to install as a compose service when the containerHost capability is applied and as a systemd unit when the host runs bare",
+  "soThat": "the runtime shape matches the applied platform rather than forcing a container onto a bare host or a bare service into a compose-managed stack",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13001-1",
+      "description": "The blueprint declares its connector runtime via ADR-4002 with elicited enum {compose-service, systemd-unit} and recommendedDefault compose-service. The shared fixture ships both variants under packages/rcf-lite/test/fixtures/hetzner-throwaway-server/cloudflared/{compose-service,systemd-unit}/; the compose-service variant defines a cloudflared service alongside the T-2 web and caddy services on the same web-net network with restart unless-stopped, no host ports and a healthcheck; the systemd-unit variant ships a cloudflared.service unit file per the vendor local-configuration-file docs.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4001-edge-cloudflare-tunnel-connector-shape"
+  ]
+}

package/rcf/user-stories/us-13002.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T03:21:16.655Z",
+  "updatedAt": "2026-09-08T03:21:16.655Z",
+  "usId": "US-13002",
+  "prdId": "PRD-001",
+  "reqId": "REQ-130",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-3 cloudflared connector reports healthy on boot (tunnelConnectorUp fires with connector id, region, version)",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0 on a cloudHost",
+  "iWant": "the connector to emit a tunnelConnectorUp event on boot with connector id, region and version metadata (metadata only)",
+  "soThat": "the observability sink proves the tunnel is up without a shell into the host",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13002-1",
+      "description": "real-account-connector-healthy probe declares accountBound true (on CI_HAS_CLOUDFLARE_ACCOUNT AND CI_HAS_HETZNER_ACCOUNT) and records accountBoundSkipped when either env var is unset. When both are set the probe drives cloudflared tunnel info against the fixture tunnel and asserts at least one healthy connector plus a tunnelConnectorUp event with connector id, region and version.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4001-edge-cloudflare-tunnel-connector-shape"
+  ]
+}

package/rcf/user-stories/us-13101.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T03:21:16.885Z",
+  "updatedAt": "2026-09-08T03:21:16.885Z",
+  "usId": "US-13101",
+  "prdId": "PRD-001",
+  "reqId": "REQ-131",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-3 tunnel manifest schema at cloudflare/tunnels/<name>.yaml validates on shape (tunnel id, credentials secretRef, ingress rules with catch-all 404)",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0",
+  "iWant": "the tunnel manifest at cloudflare/tunnels/<name>.yaml to validate against a shipped JSON schema (uuid-shaped tunnel id, secretRef credentials, ingress rules with a mandatory catch-all http_status 404)",
+  "soThat": "a mis-shaped manifest is caught at apply-time rather than at first inbound request",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13101-1",
+      "description": "manifest-schema-validate probe passes on the canonical fixture at cloudflared/*/cloudflare/tunnels/probe.yaml and fails when the fixture is mutated: SIMULATE_MANIFEST_INVALID_TUNNEL_ID rewrites the tunnel-id field to a non-uuid literal; SIMULATE_MANIFEST_CREDENTIALS_INLINE writes the credentials JSON body inline (bypassing the secretRef); SIMULATE_MANIFEST_MISSING_CATCHALL removes the catch-all rule. Each mutation FAILS naming the offending field.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4002-edge-cloudflare-tunnel-manifest-schema"
+  ]
+}

package/rcf/user-stories/us-13102.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T03:21:17.114Z",
+  "updatedAt": "2026-09-08T03:21:17.114Z",
+  "usId": "US-13102",
+  "prdId": "PRD-001",
+  "reqId": "REQ-131",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-3 ingress rules route the public hostname to an internal service URL and cloudflared config lint exits 0",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0 with a compose service listening on an internal port",
+  "iWant": "the ingress rule mapping the public hostname to the internal service URL (e.g. http://web:8080) to pass cloudflared tunnel ingress validate cleanly",
+  "soThat": "a rule that would fail at boot fails at gate instead",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13102-1",
+      "description": "cloudflared-config-lint probe runs cloudflared tunnel ingress validate through the cloudflare/cloudflared container image (when the binary is not on PATH) against the fixture manifest and exits 0 on the canonical fixture; SIMULATE_INGRESS_INVALID rewrites the ingress rule service URL to an unresolvable scheme and the probe FAILS naming the offending line.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4002-edge-cloudflare-tunnel-manifest-schema"
+  ]
+}

package/rcf/user-stories/us-13201.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T03:21:17.345Z",
+  "updatedAt": "2026-09-08T03:21:17.345Z",
+  "usId": "US-13201",
+  "prdId": "PRD-001",
+  "reqId": "REQ-132",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-3 no public origin ports on the host (firewall stays 22 plus 80/443-only-when-reverse-proxy; manifest refuses an origin-port request)",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0 without a reverse proxy",
+  "iWant": "the host firewall to stay closed on 80/443 and the manifest schema to refuse any ingress rule that binds to a host public port rather than an internal address",
+  "soThat": "the tunnel remains the only path from the edge to the origin",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13201-1",
+      "description": "manifest-schema-validate refuses ingress rules whose service URL binds to a host public interface. SIMULATE_ORIGIN_PORT_OPEN rewrites the ingress rule service URL to http://0.0.0.0:80 (or a host-relative port); the probe FAILS naming the leak. The T-1 firewall on the ci-throwaway manifest stays 22 open plus 80/443 open only when a reverse proxy is applied; a T-3-only project declares no 80/443 rule.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4002-edge-cloudflare-tunnel-manifest-schema"
+  ]
+}

package/rcf/user-stories/us-13301.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T03:21:17.575Z",
+  "updatedAt": "2026-09-08T03:21:17.575Z",
+  "usId": "US-13301",
+  "prdId": "PRD-001",
+  "reqId": "REQ-133",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-3 Access-gated composition: when zeroTrustGate is applied, ingress rules attach originRequest.access.aud",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0 alongside edge-cloudflare-access v1.0.0",
+  "iWant": "every ingress rule to attach an originRequest.access block naming the Access AUD",
+  "soThat": "cloudflared refuses at the edge any request that arrives without a valid Access JWT for that AUD",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13301-1",
+      "description": "aud-presence-check probe passes on BOTH fixture variants: on the access-gated variant every ingress rule attaches originRequest.access.aud read from the sidecar rcf/blueprints/edge-cloudflare-tunnel.applied.json (appliedCapabilities includes zeroTrustGate); on the public-hostname variant the originRequest.access block is absent from every rule (appliedCapabilities excludes zeroTrustGate). The shape flip is a pure function of the sidecar contents.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4003-edge-cloudflare-tunnel-access-binding"
+  ]
+}

package/rcf/user-stories/us-13302.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T03:21:17.805Z",
+  "updatedAt": "2026-09-08T03:21:17.805Z",
+  "usId": "US-13302",
+  "prdId": "PRD-001",
+  "reqId": "REQ-133",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-3 shape does not silently degrade to open ingress when zeroTrustGate drifts absent on a project that intended the gated shape (aud-presence-check refuses)",
+  "asA": "shelf consumer who applied edge-cloudflare-tunnel v1.0.0 with zeroTrustGate on",
+  "iWant": "a probe that asserts the ingress rule keeps its originRequest.access.aud block on every reapply and refuses if the block drifts absent",
+  "soThat": "a silent config drift to open ingress is caught at gate rather than at first probing",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13302-1",
+      "description": "aud-presence-check refuses when the gated variant drifts to open ingress. SIMULATE_AUD_DROP rewrites the gated fixture ingress to remove the originRequest.access block; the probe FAILS with a defensive-against-silent-degradation finding naming the affected rule and the missing AUD value.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4003-edge-cloudflare-tunnel-access-binding"
+  ]
+}

package/rcf/user-stories/us-13401.json

@@ -0,0 +1,23 @@
+{
+  "createdAt": "2026-09-08T03:21:18.038Z",
+  "updatedAt": "2026-09-08T03:21:18.038Z",
+  "usId": "US-13401",
+  "prdId": "PRD-001",
+  "reqId": "REQ-134",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-3 credentials-file discipline (JSON at mode 0o400, referenced via secretRef, not committed, grep-refuses on the literal, no leak in event bodies)",
+  "asA": "shelf consumer applying edge-cloudflare-tunnel v1.0.0 on a cloudHost",
+  "iWant": "the tunnel credentials file to land at mode 0o400 on the host, be referenced from the manifest as a secretRef, never be committed to the applying project tree (grep-refuse on the tunnel id and account tag literals), and never appear in any lifecycle event body",
+  "soThat": "a leaked credentials file cannot happen through a review-time miss",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13401-1",
+      "description": "The fixture credentials placeholder at cloudflared/credentials/probe.json.example carries a note that a real credentials file must land at mode 0o400 on the host; the manifest references it via a secretRef; the grep-refuse pattern is documented in the guide; every cloudflaredReady, tunnelConnectorUp and ingressRuleReloaded event body captured by the in-process facade carries metadata only, and SIMULATE_EVENT_SECRECY_LEAK inserts the credentials literal into a lifecycle event body and the scan FAILS naming the leaked field.",
+      "testable": true
+    }
+  ],
+  "tacIds": [
+    "TAC-4002-edge-cloudflare-tunnel-manifest-schema"
+  ]
+}

package/rcf/user-stories/us-5001.json

@@ -0,0 +1,27 @@
+{
+  "createdAt": "2026-09-07T10:18:40.349Z",
+  "updatedAt": "2026-09-07T10:20:10.276Z",
+  "usId": "US-5001",
+  "prdId": "PRD-001",
+  "reqId": "REQ-050",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-1 KV facade opens against the elicited KV binding on boot and emits facadeReady",
+  "asA": "shelf consumer applying the platform-cloudflare-kv v1.0.0 blueprint on a Workers project using the cf-platform fixture",
+  "iWant": "one KV facade module (src/kv-facade.mjs) that opens against the elicited KV binding on process boot and emits a facadeReady lifecycle event with a metadata-only payload",
+  "soThat": "boot ordering is observable, the ready-check seam is a single call site, and the applied project can compose its own bootstrapping around one predictable event",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5001-1",
+      "description": "On process boot, the facade opens against the elicited KV binding (env.CACHE on the fixture) with a bounded list(limit:1) ready-check; once the ready-check resolves, a facadeReady event fires on the injected event sink with a payload of exactly {event, key, size, ttl, timestamp} where key is null, size is 0 and ttl is null. The facade exposes typed named domain verbs (get, getWithMetadata, put, delete, list) and does NOT re-export the raw KV binding.",
+      "given": "a Node or Worker process with the facade module imported and its factory invoked with the elicited binding",
+      "when": "the process boots and the facade ready() call resolves",
+      "then": "a facadeReady event fires on the injected event sink with the metadata-only payload; the facade exposes named domain verbs only; the raw binding is not re-exported",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tags": [
+    "blueprint:platform-cloudflare-kv"
+  ]
+}

package/rcf/user-stories/us-5002.json

@@ -0,0 +1,27 @@
+{
+  "createdAt": "2026-09-07T10:18:40.551Z",
+  "updatedAt": "2026-09-07T10:20:10.276Z",
+  "usId": "US-5002",
+  "prdId": "PRD-001",
+  "reqId": "REQ-050",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-1 KV facade module is the sole reader of the KV binding grep-verified on the applied fixture tree",
+  "asA": "shelf consumer applying platform-cloudflare-kv v1.0.0",
+  "iWant": "the KV binding reference (env.CACHE) to appear in exactly one source module (src/kv-facade.mjs)",
+  "soThat": "the vendor surface is diffused across zero call sites outside the facade, and a future adapter swap lands without moving any AC",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5002-1",
+      "description": "A grep for env.CACHE in the applied fixture src/ tree returns exactly one file: src/kv-facade.mjs. No other module dereferences the raw KV binding. The public surface of src/kv-facade.mjs exports the createKvFacade factory only; the raw env.CACHE reference never crosses the module boundary.",
+      "given": "the applied project source tree after apply",
+      "when": "grep -rn env.CACHE walks the src/ tree",
+      "then": "the search returns one file src/kv-facade.mjs and no other match",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tags": [
+    "blueprint:platform-cloudflare-kv"
+  ]
+}

package/rcf/user-stories/us-5101.json

@@ -0,0 +1,36 @@
+{
+  "createdAt": "2026-09-07T10:18:40.753Z",
+  "updatedAt": "2026-09-07T10:20:10.276Z",
+  "usId": "US-5101",
+  "prdId": "PRD-001",
+  "reqId": "REQ-051",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-1 typed put get delete round-trip against the KV driver realises the Workers KV binding shape",
+  "asA": "shelf consumer applying platform-cloudflare-kv v1.0.0",
+  "iWant": "typed put and get verbs that round-trip a value through the KV driver realising the Workers KV binding shape",
+  "soThat": "the applied project can persist a small piece of state and read it back deterministically, in the same shape the real Workers KV binding would present",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5101-1",
+      "description": "facade.put(key, value) writes a value; facade.get(key) returns the same bytes; both operations emit their paired lifecycle events (kvWrite on put, kvHit on get). The round-trip works against the in-memory KV driver in the fixture (kv-driver.mjs) whose binding shape matches the real Workers KV binding contract per https://developers.cloudflare.com/kv/api/.",
+      "given": "the facade wired to the in-memory KV driver in the cf-platform fixture",
+      "when": "the facade-round-trip probe puts a fixture key/value and reads it back",
+      "then": "the read returns the same bytes; the event sink records one kvWrite and one kvHit; the probe report aggregates to pass",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5101-2",
+      "description": "facade.delete(key) removes a value; a subsequent facade.get(key) returns null and emits kvMiss.",
+      "given": "a key previously put via the facade",
+      "when": "facade.delete(key) then facade.get(key)",
+      "then": "the delete emits kvWrite; the get returns null and emits kvMiss",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tags": [
+    "blueprint:platform-cloudflare-kv"
+  ]
+}

package/rcf/user-stories/us-5102.json

@@ -0,0 +1,27 @@
+{
+  "createdAt": "2026-09-07T10:18:40.958Z",
+  "updatedAt": "2026-09-07T10:20:10.276Z",
+  "usId": "US-5102",
+  "prdId": "PRD-001",
+  "reqId": "REQ-051",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-1 list with prefix returns every key under the prefix with metadata shape intact",
+  "asA": "shelf consumer applying platform-cloudflare-kv v1.0.0",
+  "iWant": "facade.list({prefix}) to return every key under a prefix with the metadata shape intact",
+  "soThat": "the applied project can enumerate feature flags, sessions, or any prefix-scoped collection through one seam",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5102-1",
+      "description": "The list-with-prefix probe puts 10 keys under the prefix flags/ (each with a metadata blob) and calls facade.list({prefix: flags/}). The result returns all 10 keys, each entry carrying {name, metadata}, and every name preserves the domain-visible key (without the fixture keyPrefix if one was set).",
+      "given": "10 keys put under a shared prefix through the facade",
+      "when": "facade.list({prefix: flags/}) runs",
+      "then": "the result carries 10 entries with correct name and metadata fields; the aggregate probe verdict is pass",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tags": [
+    "blueprint:platform-cloudflare-kv"
+  ]
+}

package/rcf/user-stories/us-5201.json

@@ -0,0 +1,36 @@
+{
+  "createdAt": "2026-09-07T10:18:41.162Z",
+  "updatedAt": "2026-09-07T10:20:10.276Z",
+  "usId": "US-5201",
+  "prdId": "PRD-001",
+  "reqId": "REQ-052",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-1 cache-aside helper: hit-then-miss with a fake clock proves one origin call within TTL and a second past TTL",
+  "asA": "shelf consumer applying platform-cloudflare-kv v1.0.0",
+  "iWant": "the cache-aside helper to read from KV first and fall back to origin on miss, writing back with the elicited TTL",
+  "soThat": "the origin surface (a database, a downstream service) is spared one call per cached hit within TTL",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5201-1",
+      "description": "On first call, cache-aside.getOr(key, originFn) finds nothing in the facade, invokes originFn once, writes back with the elicited TTL, and returns the fresh value with source origin. On second call within TTL, the read is served from the facade (source cache) and originFn is NOT invoked (the invocation counter stays at 1).",
+      "given": "a fresh key and an origin function that increments a counter each call",
+      "when": "getOr(key, originFn) runs twice within TTL",
+      "then": "the invocation counter reaches 1; both calls return the same value; the second read reports source cache",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5201-2",
+      "description": "After the TTL elapses (in-memory driver clock advances past the expiration), cache-aside.getOr(key, originFn) finds nothing and invokes originFn a second time. The invocation counter reaches 2.",
+      "given": "a key past its TTL",
+      "when": "getOr(key, originFn) runs after clock advance past TTL",
+      "then": "the invocation counter reaches 2; the returned value comes from origin",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tags": [
+    "blueprint:platform-cloudflare-kv"
+  ]
+}

package/rcf/user-stories/us-5301.json

@@ -0,0 +1,27 @@
+{
+  "createdAt": "2026-09-07T10:18:41.367Z",
+  "updatedAt": "2026-09-07T10:20:10.276Z",
+  "usId": "US-5301",
+  "prdId": "PRD-001",
+  "reqId": "REQ-053",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-1 lifecycle events fire on facadeReady kvHit kvMiss kvWrite with metadata-only payload",
+  "asA": "shelf consumer applying platform-cloudflare-kv v1.0.0",
+  "iWant": "the facade to emit facadeReady kvHit kvMiss kvWrite events with metadata-only payload on the injected sink",
+  "soThat": "the applied logging companion can render KV activity without ever writing a body byte to the log stream",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5301-1",
+      "description": "Each lifecycle event emitted by the facade carries EXACTLY the whitelist {event, key, size, ttl, timestamp}. No body value, no metadata blob, no additional field ever appears on the record the sink receives.",
+      "given": "the facade wired to a spy event sink, with a mix of put/get/delete/list operations",
+      "when": "the operations run",
+      "then": "the sink records each event with only the whitelist keys; any extra key trips the probe",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tags": [
+    "blueprint:platform-cloudflare-kv"
+  ]
+}

package/rcf/user-stories/us-5302.json

@@ -0,0 +1,27 @@
+{
+  "createdAt": "2026-09-07T10:18:41.585Z",
+  "updatedAt": "2026-09-07T10:20:10.276Z",
+  "usId": "US-5302",
+  "prdId": "PRD-001",
+  "reqId": "REQ-053",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "T-1 event secrecy: no body bytes no PII no user id beyond the key ever reach the event sink",
+  "asA": "shelf consumer applying platform-cloudflare-kv v1.0.0",
+  "iWant": "the event-secrecy probe to prove no body bytes or PII ever reach the event sink",
+  "soThat": "the operator can trust that a KV that holds a PII fixture (users/1234/profile with SSN) never leaks the body to the log stream even under a mutation-run",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5302-1",
+      "description": "The event-secrecy probe puts, gets and deletes a PII fixture (key users/1234/profile, body {ssn: REDACTED-fixture}); every event record on the sink carries only the whitelist and no substring of the SSN, no substring of the user id beyond the key itself, and no substring of the body. A mutation-run turning on SIMULATE_PII_LEAK flips the probe to fail with the leaked field named.",
+      "given": "the facade wired to a spy sink with a PII fixture",
+      "when": "put/get/delete operations run on the PII key",
+      "then": "the recorded events contain only the whitelist; PII-substring scan returns zero hits; the mutation-run under SIMULATE_PII_LEAK trips the probe to fail",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tags": [
+    "blueprint:platform-cloudflare-kv"
+  ]
+}