rcf-lite 0.12.0 → 0.14.0

package/blueprints/observability-probe-endpoints/guide/observability-probe-endpoints.md

@@ -0,0 +1,83 @@
+# Observability probe endpoints blueprint guide
+
+## What it is
+
+A default probe-surface blueprint for rcf-lite projects that must integrate with an EXTERNAL supervising system whose conventions drive the probe wire shape. The blueprint contributes the WHAT of a probe pattern: how the operator declares which external supervisor the service runs under (`kubernetes`, `loadBalancer`, `uptimeMonitor`, `systemd`, `dockerHealthcheck`, `reverseProxy`, or a project-authored `custom:<name>`), how each profile fixes the probe transport, path or command surface, response contract, and semantic distinction between liveness and readiness for that supervisor, how a fused-listener default coexists with a `probeListener.separatePort` opt-in for probe-traffic isolation, how the auth-exempt list stays scoped to the resolved probe path set exactly, and how switching supervising systems is a configuration change rather than a source-tree reshape.
+
+Concretely, the blueprint ships eight requirements, eight user stories (twenty-four acceptance criteria), four architecture components, and five architecture decision records. Two ADRs are `scope: global` on the topics `healthProbes` (the profile-elicited probe interface) and `readinessSemantics` (per-profile readiness aggregation); the other three are scope-local (Kubernetes default profile, separate-port option, external-response secrecy rule). The two global ADRs conflict with the observability-essentials sibling by design; see 'Boundary with observability-essentials' below.
+
+## What it is not
+
+Not an all-in-one observability floor. There is no public status page here, no notification outcome sink, no metrics-export surface, no distributed-tracing surface, no authenticated operator dashboard. observability-essentials is the blueprint for the self-supervised all-in-one case; this one exists for the case where the external supervising system's conventions come first.
+
+Not a readiness-check implementation. The blueprint fixes the SHAPE of the readiness predicate boundary (a synchronous function returning pass or fail, reading state a project-supplied evaluator maintains on its own cadence) and each profile's default aggregation rule. The per-dependency check code and the evaluator implementation are project-authored.
+
+Not a supervisor-specific SDK. The blueprint holds no SDK dependency on Kubernetes, no client library for a specific cloud load balancer, no wrapper around a specific uptime-monitor API. The profile contract shapes the wire surface; the project brings whichever integration bits it needs on the outside of the boundary.
+
+Not an auth middleware. The blueprint emits an exact-match exempt-path list the project's own auth middleware installer consumes. The middleware installer, the auth model itself, and the check code stay project-side; the exemption is a boundary contract, not a middleware implementation.
+
+Not a listener library. The topology component (TAC-1503) accepts a project-supplied `userTrafficListener` and a project-supplied `listenerFactory` for the separate-port case. The blueprint holds no opinion on the HTTP server library (Node HTTP, Express, Hono, Fastify, or the Worker-style edge platform's own router).
+
+## Boundary with observability-essentials
+
+observability-essentials and observability-probe-endpoints are BOTH `observability` category blueprints. They answer different questions:
+
+- **observability-essentials** targets the self-supervised, all-in-one case: the project owns its observability surface end to end, wires two HTTP JSON probes (`/healthz`, `/readyz`) on the request-traffic listener with a stable body shape, ships a public status page for external readers, and ships a notification outcome sink for durable notification records. The audience of the probe body is the operator inspecting the deployed service in triage. The identity is 'a default observability floor'.
+
+- **observability-probe-endpoints** targets the external-integration case: the service runs under a specific external supervising system (a Kubernetes kubelet, an application load balancer, an uptime monitor, a systemd unit, a Docker HEALTHCHECK invocation, a reverse-proxy upstream health check), and the wire shape of the probes follows that supervisor's conventions. The audience of the probe response IS the external supervisor; the response is minimal by construction so the surface never carries reconnaissance value to unintended readers. The identity is 'make your service correctly probeable by whatever external system supervises it'.
+
+Composing the two on one project fires two `globalAdrTopic` conflicts (on `healthProbes` and on `readinessSemantics`) on purpose. The four documented resolution paths per topic apply: adopt the incoming blueprint (remove the existing), keep the existing (do not add the incoming), author a project-level ADR that supersedes both, or declare the resolution on the add itself with `--resolve`. The right resolution is usually one of two shapes:
+
+- **Shape A (external supervisor wins):** the project runs under a supervisor whose conventions drive the wire shape; a project-level ADR fixes both topics against the probe-endpoints model and observability-essentials contributes the public status page and notification outcome sink through the compose while keeping its `statusPageContract` topic untouched.
+- **Shape B (self-supervised wins):** the project designs its own observability floor without a specific external supervisor's conventions in view; a project-level ADR fixes both topics against the essentials model and this blueprint is not applied.
+
+Explicit hybrids exist (an internal essentials-shaped surface for one audience and a profile-shaped external surface for the supervising system) and are legitimate; the project-level ADR names both surfaces with explicit boundaries and both blueprints compose.
+
+Composing with the `deploy-cloudflare-workers` blueprint is a separate concern: that blueprint mandates its own build-provenance probe (`/healthz` by convention) whose response body carries `{ versionSha, builtAt, ciRunUrl }` for the deploy verifier's reconciliation, which is incompatible with every profile's minimal response contract; the two surfaces coexist on distinct paths (this blueprint's profile-owned path stays minimal, the deploy blueprint's provenance path lives on a separate string), and the boundary is documented on the deploy side in `assets/verification/served-surface-probes.md`.
+
+## When to reach for it
+
+Reach for the observability-probe-endpoints blueprint when:
+
+- The service runs under a specific external supervising system (Kubernetes, cloud load balancer, uptime monitor, systemd unit under `Type=notify`, Docker HEALTHCHECK invocation, reverse-proxy upstream health check) whose conventions drive what a probe looks like and what the answer means.
+- The probe surface is reachable by parties beyond the intended supervisor (a fused-topology deployment where the public host resolves to the same port that answers probes), and the response contract must be minimal to keep reconnaissance value low.
+- Multi-environment deployments switch supervising systems across environments (a `dev` environment on Docker Compose with a load-balancer-shaped health check, a `live` environment on Kubernetes with liveness and readiness); a configuration change per environment is the intended migration path.
+- The probes are one integration surface among several the service exposes; other observability concerns (public status page, notification outcomes, metrics export, tracing) belong to other blueprints and stay out of scope here.
+
+## When it does not fit
+
+Do not reach for the observability-probe-endpoints blueprint when:
+
+- The project is a self-supervised all-in-one deployment where a single opinionated observability floor is the intended shape; observability-essentials is the right pick.
+- The service is not probed by an external supervisor at all (a batch job with no supervising loop, a one-shot script, an internal-only tool without a health-check consumer). The blueprint's elicitation surface has nothing to fix in that case.
+- The probes need to expose richer per-dependency state on the wire for a specific supervising system that reads it (an OpenTelemetry-agent-scrape shape, a gRPC-health-with-service-name shape). The blueprint's default profile set does not cover those; a `custom:<name>` profile is the mechanism escape, or a project-level ADR supersedes ADR-1501 and the project authors the richer surface directly.
+- The project already has a project-level `healthProbes` ADR the operator wants to keep; applying this blueprint would fire a conflict the operator does not want to resolve. Not applying the blueprint is a legitimate outcome.
+
+The round-2 shelf brief originally scoped this blueprint as a `kubernetes-service` deployment-shape blueprint, then reshaped it during review into `observability-probe-endpoints` (a probe-surface blueprint for any external supervising system, with Kubernetes as the shipped default). The reshape moves the identity from 'ship on Kubernetes' to 'be probeable by whichever supervisor probes you'; the boundary with observability-essentials (self-supervised all-in-one) came out of that reshape too. A future `deploy-kubernetes` blueprint in the `deploy` category may take on the deployment-manifest side of the original candidate; this one is the probe-surface side.
+
+## What a good outcome looks like
+
+A project applies the observability-probe-endpoints blueprint on a fresh tree, declares its `probeInterface.profile` value for each environment, wires the readiness predicate against its declared dependency evaluator, chooses fused topology or `probeListener.separatePort` per environment, realises TAC-1501 through TAC-1504 in project-authored FBSes, and lands on a deployed service where:
+
+- A Kubernetes-supervised pod on the shipped default answers HTTPGet `/live` and `/ready` on the container's request-traffic port; the standard `livenessProbe: { httpGet: { path: /live, port: <containerPort> } }` and `readinessProbe: { httpGet: { path: /ready, port: <containerPort> } }` on the podspec work without further wiring.
+- A load-balancer-supervised container on the `loadBalancer` profile answers one HTTP GET at the resolved `/health` path with the status code alone and an empty body; the LB target-group health check sees the status flip within its own health-check interval budget and pulls the target from rotation without ambiguity from a body it never read.
+- A systemd-supervised process on the `systemd` profile emits `sd_notify(READY=1)` after boot and `sd_notify(WATCHDOG=1)` on the configured watchdog cadence; the unit under `Type=notify` starts cleanly and stays healthy under the watchdog timeout.
+- A Docker HEALTHCHECK on the `dockerHealthcheck` profile exits 0 on pass and non-zero on fail from the exec entry point the profile exposes; the container's HEALTHCHECK status flips as `docker inspect` reports.
+- A separate-port Kubernetes deployment on `probeListener.separatePort: 9091` exposes only the traffic port on the Service; probes reach the pod on port 9091 from the kubelet on the pod network and never appear on the public interface.
+- An unauthenticated GET against `/live` or `/ready` on the auth-installed listener answers without a credential challenge; an unauthenticated GET against `/ready/next` (a path adjacent to the exempt entry but not exempt itself) returns the middleware's normal unauthenticated response; the exemption never expanded beyond the resolved probe path set.
+- A response body scan against every profile's response finds no dependency name, no environment identifier, no hostname, no replica id, no build hash, no commit sha; the pass or fail answer is the whole response surface.
+- Switching a service from Kubernetes to a Docker Compose deployment behind a load balancer is a change to `probeInterface.profile` in configuration; a source-tree diff between the two boots contains no non-configuration changes and no per-profile conditional appears outside the profile modules and the resolver call site.
+
+## Operator decisions that remain open after apply
+
+- Target integration profile (`kubernetes` default; `loadBalancer`, `uptimeMonitor`, `systemd`, `dockerHealthcheck`, `reverseProxy` supplied; `custom:<name>` slot for project-authored profiles). Blueprint owns the profile contract shape; project owns the per-environment selection.
+- Probe path defaults (`/live` and `/ready` for Kubernetes, `/health` for load balancer, per-profile defaults elsewhere). Blueprint owns the defaults; project overrides at boot for compliance with a particular supervisor convention or platform mandate.
+- Listener topology (fused user-traffic listener default, `probeListener.separatePort: <N>` opt-in). Blueprint owns the two shapes; project owns the per-environment choice.
+- Readiness predicate implementation (the per-dependency check code, the evaluator cadence, the timeout budgets). Blueprint owns the predicate boundary and each profile's default aggregation rule; project owns the checks and the cadence values.
+- Custom profile authoring (a project that authors `custom:<name>` supplies the profile object against the shipped contract). Blueprint owns the contract; project owns the profile.
+- Auth middleware installer (the project supplies the installer that consumes the exempt-path list the topology component emits). Blueprint owns the exempt-list shape; project owns the middleware and the installer.
+- systemd watchdog cadence, Docker HEALTHCHECK interval, TCP probe port. Blueprint owns the transport shape; project owns the cadence and interval values.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Every process pays the profile-resolver step at boot and one indirection through the frozen profile object at each probe binding site; the cost is small but real. A project that wants hot-reload of the profile selection restarts the process gracefully; the blueprint declines to support live rebinding. The separate-port topology opens a second HTTP listener when in effect; the extra port is a small memory cost and one more thing to think about in the deployment substrate. The profile-swap-is-config invariant costs the project a small amount of author discipline: per-profile branching in the boot path outside the resolver call site would defeat the invariant, and the AC scan catches the drift only if the project wires it into its own CI. The response-minimalism-by-construction rule costs the project any richer probe body it may have wanted for its own consumption (that surface belongs to observability-essentials, to an authenticated dashboard, or to a project-side triage endpoint outside the probe path set). The blueprint says nothing about the public status page, the notification outcome sink, metrics export, distributed tracing, or the auth model itself; a project that needs any of those spends its own build cycles on them and this blueprint does not save it any work there.

package/blueprints/persistence-data-d1/README.md

@@ -0,0 +1,50 @@
+# Persistence data D1 blueprint (v1.0.0)
+
+The ninth content blueprint on the rcf-build-lite blueprint mechanism. Scope: Cloudflare D1 as the project's primary durable store for Workers-deployed applications, accessed request-scoped through a Worker-side facade module that is the sole reader of the D1 binding, with numbered forward-only migrations owned by the wrangler CLI, a deploy pipeline gate ordering the migrations apply strictly before the Worker deploy, prepared-statement discipline that closes the SQL-injection surface by construction, batch atomicity for multi-statement writes, and a two-path recovery model (Time Travel plus a scheduled portable export). Targeted at small greenfield rcf-lite projects deployed on Workers; other engines behind the same facade contract on supersede.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/persistence-data-d1
+```
+
+Phase 1 resolves local path sources only; registry and git-ref resolution is a mechanism follow-up. Apply is idempotent; `rcf define blueprint list` shows the applied entry grouped under the `persistence` category; `rcf define blueprint remove persistence-data-d1` cleanly removes an unreferenced application.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, category `persistence`, and the 23 contributions with scope/topic on the two global ADRs |
+| Doc set | `contributions/` | 7 REQs, 7 USs (20 ACs), 4 TACs, 5 ADRs, all schema-valid and namespaced (`persistence-data-d1-REQ-001` prefix family; `ADR-1401-persistence-data-d1-store-model` suffix family) |
+| Wrangler D1 binding sample | `assets/wrangler-config/d1-binding-shape.md` | The exact shape of a `d1_databases[]` entry with `binding`, `database_name`, `database_id`, `migrations_dir`, `migrations_table`, and `migrations_pattern`, worked as one committable example with placeholders only |
+| Migration file shape sample | `assets/migration-shape/migration-file-shape.md` | The exact shape of a numbered migration file under the wrangler-configured directory, with a worked four-migration example |
+| Facade module shape sample | `assets/facade-shape/facade-module-shape.md` | The exact shape of the D1 store facade module (`createStore({ env, bindingName, onEvent })` factory, named verbs, prepared-statement discipline, batch atomicity) with a worked domain example |
+| Batch usage sample | `assets/batch-usage/batch-atomicity-example.md` | The exact shape of a multi-statement atomic write through `db.batch([...])`, with the mid-batch-failure rollback semantics called out |
+| Guide | `guide/persistence-data-d1.md` | Operator-facing: when to use it, when not, what stays your call, and the promotion signals for the sibling single-file SQLite blueprint and future Postgres or replication blueprints |
+| Coordination vocabulary | `docs/topics.md` | The two global-topic strings this blueprint contributes and the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, email-smtp-resend, persistence-data-sqlite, delivery-ci-workflows, observability-essentials, security-secrets-management, security-auth-clerk, persistence-data-d1) |
+
+The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
+
+## What it contributes, and what it deliberately does not
+
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+
+No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (the store facade contract, the wrangler-owned migration discipline, the deploy-pipeline gate contract, the prepared-statement and batch atomicity boundaries, the two-path recovery model, the metadata-only event log discipline); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
+
+Deliberately not contributed: the domain schema (the tables the project's own entities live in are project-authored, on top of the migration directory the project maintains; the blueprint governs the facade contract and the migration discipline, not the domain shape); an ORM or query builder above the D1 prepared-statement surface (the facade is a project-authored surface; how it internally implements its verbs above the vendor binding is not blueprint-owned, but the boundary discipline refuses raw-SQL passthrough on the public surface); a Worker deploy blueprint (a companion `deploy-cloudflare-workers` blueprint is the natural pair for the Worker deploy step the deploy-gate TAC assumes; until it ships, projects wire their own deploy step); a secrets management surface for the CI credential that runs `wrangler d1 migrations apply` and `wrangler deploy` (the credential storage and rotation posture are the concern of the `security-secrets-management` blueprint, not this one); a CI pipeline template (CI shape is the concern of the `delivery-ci-workflows` blueprint, not this one; this blueprint contributes the requirement that the migrations-apply step orders strictly before the deploy step, not the file that implements it); a replication or failover surface (D1's read-replica surface is a read-scaling primitive, not a failover primitive; a project needing failover supersedes ADR-1401 with an alternate engine); a logical schema-agnostic dump beyond the vendor's `wrangler d1 export` (out of scope; see ADR-1405's alternatives).
+
+## The two global decisions
+
+ADR-1401-persistence-data-d1-store-model ships `scope: global` on topic `persistenceStore`. This is the project's primary durable store engine choice: one Cloudflare D1 database bound into the Worker under a named binding, one entry point through the facade. A composing blueprint that holds a different engine opinion (the single-file SQLite blueprint on the same topic, a future Postgres blueprint, a KV-store blueprint) conflicts here by design and expects a project-level ADR resolution.
+
+ADR-1402-persistence-data-d1-migration-discipline ships `scope: global` on topic `migrationDiscipline`. This is the project's schema-evolution posture: numbered forward-only `.sql` files under the wrangler-configured directory, applied by the vendor CLI, gated in the deploy pipeline. A composing blueprint that holds an opinion on migration discipline (the SQLite blueprint's boot-time runner-at-open discipline on the same topic, a future event-sourced projection blueprint) conflicts here by design.
+
+See `docs/topics.md` for the exact strings, the expected resolutions, the delineation from the application-api-rest blueprint's `logging` topic (which governs the wire-log shape, not the store-event log shape), the deliberate-conflict statement against the persistence-data-sqlite blueprint (both blueprints ship the same two global topics with different vendor answers on purpose, mirroring the application-spa plus application-api-rest pairing on `errorEnvelope` and `authModel`), and the AC id band allocation (persistence-data-d1 owns 13101-13899, ADR/TAC suffix block 1401-1499).
+
+## Quality bar
+
+Single D1 database bound into the Worker under one named binding read by exactly one facade module; every read and write through the facade issued as `db.prepare(<static SQL literal>).bind(...)` with no consumer-supplied SQL and no `db.exec(<consumer string>)` on any path; multi-statement writes requiring atomicity through `db.batch([...])` with no partial-batch results surfaced; numbered forward-only `.sql` migration files under the wrangler-configured directory with the vendor CLI as the sole applier and the vendor bookkeeping table as the sole applied-state ledger; deploy pipeline that orders `wrangler d1 migrations apply` strictly before `wrangler deploy` per environment and refuses the deploy on any apply failure; two-path recovery (Time Travel point-in-time restore within the plan window and a scheduled `wrangler d1 export` to a portable off-vendor artifact) exercisable from the ops or CI surface without a Worker code change; structured event log at five defined moments (facadeReady, migrationsApplied, backupExported, timeTravelRestored, queryFailed) with metadata-only fields carrying no domain-row values. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+None at v1.0.0. Every AC on every story is bound to at least one TAC that the host project must realise, and every AC's `then` clause is runtime-observable in the deployed application (source-tree import-graph scans for the boundary properties, wrangler CLI exit-code checks for the migration and deploy-gate properties, D1 read round-trips for the row-preservation properties on export and restore, event-sink accumulation for the log-shape properties, targeted grep for the SQL-string discipline). The mechanism-reach principle from the authoring standard section 7 is satisfied at ship: a project that applies this blueprint and does not realise a TAC leaves an unresolved `tacIds` reference on the story that `rcf define validate` and `rcf audit coverage` refuse. The one operational surface a project must own on its own is the CI pipeline that wires the deploy gate (TAC-1403); that responsibility is stated as a TAC interface (`ciStep.migrationsApply`, `ciStep.deploy`) with an explicit ordering contract, not as a smuggled runtime probe. The recovery runner (TAC-1404) is similarly a project-owned ops surface; the blueprint contributes the shape and the event contract, not the ops file that invokes it.

package/blueprints/persistence-data-d1/assets/batch-usage/batch-atomicity-example.md

@@ -0,0 +1,72 @@
+# Batch atomicity in the D1 facade
+
+D1 does not expose explicit BEGIN / COMMIT to the Worker binding. `db.batch([...])` is the vendor's atomicity primitive for multi-statement writes: the vendor's contract states that a mid-batch failure aborts and rolls back the entire sequence. This asset shows the shape a facade verb takes when its domain contract requires two or more statements to land as one unit (AC-13105-1, AC-13105-2).
+
+## Verb shape
+
+```javascript
+// src/store/entityBVerbs.js
+// A verb whose domain contract requires insertA + insertB + auditEntry
+// to land as one unit, or none.
+
+export function entityBVerbs(db, onEvent) {
+  return {
+    async createEntityBWithAudit({
+      entityAId,
+      entityBId,
+      payload,
+      auditActor,
+      now,
+    }) {
+      const batch = [
+        db
+          .prepare(
+            'INSERT INTO entityB (id, entityAId, payload, createdAt) VALUES (?, ?, ?, ?)'
+          )
+          .bind(entityBId, entityAId, payload, now),
+        db
+          .prepare(
+            'UPDATE entityA SET updatedAt = ? WHERE id = ?'
+          )
+          .bind(now, entityAId),
+        db
+          .prepare(
+            'INSERT INTO auditEntry (id, actor, action, targetId, at) VALUES (?, ?, ?, ?, ?)'
+          )
+          .bind(crypto.randomUUID(), auditActor, 'entityBCreated', entityBId, now),
+      ];
+
+      try {
+        const results = await db.batch(batch);
+        return { entityBId };
+      } catch (err) {
+        onEvent({
+          event: 'queryFailed',
+          ts: new Date().toISOString(),
+          verb: 'createEntityBWithAudit',
+          code: err.cause?.code ?? 'unknown',
+        });
+        throw err;
+      }
+    },
+  };
+}
+```
+
+Notes:
+
+- Every statement in the batch is a prepared statement authored inside the verb. The static SQL literals live in the verb body; values reach D1 only through `bind`. The prepared-statement discipline holds inside the batch as it does for single-statement verbs.
+- The verb does not chain sequential `db.prepare(...).run()` calls under an application-side try-catch to fake atomicity. The vendor's batch primitive is the only shape that gives the atomicity guarantee. AC-13105-1 verifies this by inspection.
+- On any statement in the batch failing, D1 rolls the sequence back (the vendor's contract); the verb rethrows without surfacing any partial state to the caller. AC-13105-2 exercises this against a local D1 primed to violate a UNIQUE constraint on the second statement.
+
+## What batch is not
+
+Not a cross-verb transaction. `batch()` is atomic across the statements in one call. Two independent facade verbs called sequentially by a consumer are NOT one transaction; the facade does not expose a begin/commit primitive because D1 does not support one on the Worker binding. AC-13105-3 verifies this by inspection.
+
+Not a way to fake atomicity around a computed decision. A workflow that reads with `first()`, computes something, then writes-if-condition is not atomic; a concurrent Worker request can change the read's result between the read and the write. Push the condition into the SQL (an `INSERT ... WHERE NOT EXISTS`, an `UPDATE ... WHERE version = ?`, an optimistic-lock pattern) so the whole decision lands in one batched statement.
+
+Not the only shape for a single-statement write. Single-statement writes commit as their own transaction naturally (SQLite's default autocommit); use `db.prepare(...).run()` directly for those verbs. Batch is reserved for the multi-statement-atomic case; using batch for a one-statement write is harmless but adds a wrapper the verb does not need.
+
+## Query-count budget
+
+D1's queries-per-Worker-invocation limit (currently 1000 on Paid, 50 on Free per the vendor's currently published limits) counts statements inside batches as individual queries. A verb whose batch grows past a few dozen statements is a design smell; break the domain contract into smaller atomic units, or reconsider whether the contract truly needs cross-statement atomicity.

package/blueprints/persistence-data-d1/assets/facade-shape/facade-module-shape.md

@@ -0,0 +1,115 @@
+# D1 store facade module shape
+
+The facade (TAC-1401) is one module that reads the D1 binding from the Worker `env`, exposes named domain verbs, issues every statement as a parameterised prepared statement, uses `db.batch([...])` for multi-statement atomicity, and emits structured lifecycle events on the injected sink. This asset shows the exact shape with a worked domain example.
+
+## Module layout
+
+```
+src/store/
+  facade.js          // this file: createStore + named verbs
+  entityAVerbs.js    // named verbs partitioned by domain slice (optional)
+  entityBVerbs.js
+  sessionVerbs.js
+  auditVerbs.js
+```
+
+The `facade.js` module is the ONLY file in the source tree that reads `env[BINDING_NAME]`. Every domain slice imports helpers from `facade.js` (the request-scoped `db` handle, the event emitter) and exports its named verbs; `facade.js` re-exports them into the store's public surface. A grep of the source tree for `env.<BINDING_NAME>` (or `env["<BINDING_NAME>"]`) returns exactly one match, and it is inside `facade.js`. AC-13101-1 is verified by that grep.
+
+## `createStore` factory
+
+```javascript
+// src/store/facade.js
+// The ONE module that reads the D1 binding.
+
+let isolateFirstInvocation = true;
+
+export function createStore({ env, bindingName, onEvent }) {
+  const db = env[bindingName]; // The ONE binding read in the tree.
+  if (!db) {
+    throw new Error(`D1 binding '${bindingName}' not present on env`);
+  }
+
+  if (isolateFirstInvocation) {
+    isolateFirstInvocation = false;
+    onEvent({
+      event: 'facadeReady',
+      ts: new Date().toISOString(),
+      bindingName,
+      environment: env.ENVIRONMENT ?? 'unknown',
+    });
+  }
+
+  return {
+    // Named domain verbs (per AC-13101-2, no raw-query passthrough).
+    ...entityAVerbs(db, onEvent),
+    ...entityBVerbs(db, onEvent),
+    ...sessionVerbs(db, onEvent),
+    ...auditVerbs(db, onEvent),
+  };
+}
+```
+
+## Named domain verb (single-statement)
+
+```javascript
+// src/store/entityAVerbs.js
+// Every SQL literal is static and authored here.
+
+export function entityAVerbs(db, onEvent) {
+  return {
+    async findEntityAByName({ name }) {
+      try {
+        return await db
+          .prepare('SELECT id, name, createdAt, updatedAt FROM entityA WHERE name = ?')
+          .bind(name)
+          .first();
+      } catch (err) {
+        onEvent({
+          event: 'queryFailed',
+          ts: new Date().toISOString(),
+          verb: 'findEntityAByName',
+          code: err.cause?.code ?? 'unknown',
+        });
+        throw err;
+      }
+    },
+
+    async insertEntityA({ id, name, createdAt, updatedAt }) {
+      try {
+        return await db
+          .prepare(
+            'INSERT INTO entityA (id, name, createdAt, updatedAt) VALUES (?, ?, ?, ?)'
+          )
+          .bind(id, name, createdAt, updatedAt)
+          .run();
+      } catch (err) {
+        onEvent({
+          event: 'queryFailed',
+          ts: new Date().toISOString(),
+          verb: 'insertEntityA',
+          code: err.cause?.code ?? 'unknown',
+        });
+        throw err;
+      }
+    },
+  };
+}
+```
+
+Notes:
+
+- The SQL literal is a static string authored inside the verb. It does not embed values from consumer arguments; the values reach D1 only through `bind`. AC-13104-1 verifies this by grep.
+- The verb's typed parameter list names the fields the SQL literal binds. It does not accept a `sql` or `query` string parameter. AC-13104-2 verifies this by inspection of the exported surface.
+- The verb catches D1 errors, emits a `queryFailed` event carrying only metadata (the verb name, the D1 error code), and rethrows. The event payload never includes `name` or any bound value. ADR-1403's discipline is enforced at emit time.
+
+## Named domain verb (multi-statement atomic write via batch)
+
+See `assets/batch-usage/batch-atomicity-example.md` for the worked shape.
+
+## What this asset is not
+
+Not a runnable facade. The snippets above are the SHAPE; a project's own domain verbs are authored per the domain's actual tables. Types, error wrappers, and observability adapters are project decisions on top of the shape.
+
+Not an ORM. Projects that reach for Drizzle or Kysely wire it inside the verb bodies and preserve the outward verb surface. The prepared-statement discipline (static SQL literals inside the verb, values only through `bind`) survives an ORM: most ORMs emit static SQL from typed queries at build time, and the AC-13104-1 grep still lands on static literals.
+
+Not the delivery-ci-workflows gate. TAC-1403's deploy-gate is a CI file, not a facade responsibility; the two surfaces meet only through the shared event-record shape.

package/blueprints/persistence-data-d1/assets/migration-shape/migration-file-shape.md

@@ -0,0 +1,119 @@
+# Migration file shape
+
+Every migration in the wrangler-configured `migrations_dir` (default `migrations/`) is one `.sql` file (TAC-1402). The wrangler CLI is the applier and the D1 bookkeeping table (`migrations_table`, default `d1_migrations`) is the applied-state ledger. This asset shows the exact shape.
+
+## Filename shape
+
+The default wrangler pattern is `<zero-padded-integer>_<description>.sql`, generated by `wrangler d1 migrations create <database> <description>`:
+
+```
+migrations/
+  0001_initial_schema.sql
+  0002_soft_delete_column.sql
+  0003_boot_markers.sql
+  0004_notifier_schema.sql
+```
+
+The leading integer is monotonic across the directory; it anchors the applied-state ordering and the AC-13102-1 sequence check. The description is human-readable and appears in the file name and (by convention) the file header comment; it does not affect ordering.
+
+Projects that pin an ORM override `migrations_pattern` on the D1 binding to match the ORM's filename shape (Drizzle's `0000_name.sql`, Prisma's `<timestamp>_name/migration.sql`). The leading-integer monotonicity property still holds; the pattern controls what the CLI matches, not the ordering discipline.
+
+## File body shape
+
+Each file body is engine-native SQL: one or more statements separated by `;`, terminating in `;`. Comments (`--` line comments) are allowed. The wrangler CLI executes the statements against the D1 database and records the applied file in the bookkeeping table.
+
+Worked four-migration example (SQLite dialect, D1's native syntax):
+
+`migrations/0001_initial_schema.sql`:
+
+```sql
+-- Initial schema for the domain.
+-- Four tables: entityA, entityB, session, auditEntry.
+
+CREATE TABLE entityA (
+  id        TEXT PRIMARY KEY,
+  name      TEXT NOT NULL UNIQUE,
+  createdAt TEXT NOT NULL,
+  updatedAt TEXT NOT NULL
+);
+
+CREATE TABLE entityB (
+  id        TEXT PRIMARY KEY,
+  entityAId TEXT NOT NULL REFERENCES entityA(id),
+  payload   TEXT NOT NULL,
+  createdAt TEXT NOT NULL
+);
+
+CREATE TABLE session (
+  handle    TEXT PRIMARY KEY,
+  principal TEXT NOT NULL,
+  issuedAt  TEXT NOT NULL,
+  expiresAt TEXT NOT NULL
+);
+
+CREATE TABLE auditEntry (
+  id        TEXT PRIMARY KEY,
+  actor     TEXT NOT NULL,
+  action    TEXT NOT NULL,
+  targetId  TEXT NOT NULL,
+  at        TEXT NOT NULL
+);
+```
+
+`migrations/0002_soft_delete_column.sql`:
+
+```sql
+-- Soft-delete column on entityA for file-lane removal without eager history loss.
+ALTER TABLE entityA ADD COLUMN removedAt TEXT;
+```
+
+`migrations/0003_boot_markers.sql`:
+
+```sql
+-- Boot markers: audit trail of Worker isolate cold-starts.
+CREATE TABLE bootMarker (
+  bootAt TEXT PRIMARY KEY
+);
+```
+
+`migrations/0004_notifier_schema.sql`:
+
+```sql
+-- Notifier: per-entity channel routes and pending-delivery queue.
+CREATE TABLE entityChannelRoute (
+  entityId  TEXT NOT NULL,
+  channelId TEXT NOT NULL,
+  PRIMARY KEY (entityId, channelId)
+);
+
+CREATE TABLE channel (
+  id        TEXT PRIMARY KEY,
+  isDefault INTEGER NOT NULL DEFAULT 0
+);
+```
+
+## Applying migrations
+
+The wrangler CLI applies files in ascending leading-integer order:
+
+```
+# Local dev
+wrangler d1 migrations list  <database> --local
+wrangler d1 migrations apply <database> --local
+
+# Preview environment
+wrangler d1 migrations apply <database> --env preview
+
+# Live environment (typically run by the CI job before the Worker deploy)
+wrangler d1 migrations apply <database> --env live
+```
+
+The applied files land in the bookkeeping table (`d1_migrations` by default). A subsequent `list` reports zero unapplied migrations; a `SELECT * FROM d1_migrations` returns one row per applied file.
+
+## Rules a project must not break
+
+- **Leading integers are monotonic and unique across the directory.** A missing integer between shipped files, or a duplicate, breaks the ordering guarantee the wrangler CLI relies on. Two contributors landing overlapping integers is a merge conflict, not a runtime bug.
+- **A shipped migration is never edited.** Adding a statement to an already-applied file is a silent schema divergence between deployed databases at different apply cycles. Fixes ship as new numbered files, appended.
+- **The bookkeeping table is not the migration's concern.** A migration whose statements include an `INSERT INTO d1_migrations` corrupts the wrangler CLI's ordering; the CLI already handles that insert inside the same transaction as the migration's statements.
+- **Statements are D1-flavoured SQLite dialect.** D1 shares SQLite's SQL semantics; statements that assume Postgres-specific features (SERIAL, native JSONB, LATERAL) fail at apply. When switching engines under a superseding ADR-1401, plan for a dialect translation pass.
+- **Import from an existing SQLite dump requires stripping `BEGIN TRANSACTION` and `COMMIT`.** The vendor's guidance is explicit: D1's `wrangler d1 execute --file` refuses these statements. A migration file authored from a sqlite3 dump has them removed at authoring time.

package/blueprints/persistence-data-d1/assets/wrangler-config/d1-binding-shape.md

@@ -0,0 +1,93 @@
+# D1 binding shape in the wrangler config
+
+The Worker reads the D1 database through a binding declared on `d1_databases[]` in the project's wrangler config file (`wrangler.jsonc` or `wrangler.toml`). This asset shows the exact shape with placeholders only; substitute the project's actual identifiers at the time of writing.
+
+## Minimal shape (wrangler.jsonc)
+
+```jsonc
+{
+  "name": "<worker-name>",
+  "main": "src/worker.js",
+  "compatibility_date": "<yyyy-mm-dd>",
+  "d1_databases": [
+    {
+      "binding": "<BINDING_NAME>",
+      "database_name": "<database-name>",
+      "database_id": "<database-uuid>"
+    }
+  ]
+}
+```
+
+Field notes:
+
+- `binding` is the property name the Worker reads off `env`. Convention: uppercase snake or Pascal, one binding per named database per environment. The store facade module (TAC-1401) is the only place this name is read; every other module imports the facade.
+- `database_name` is the human-readable name from `wrangler d1 create` or `wrangler d1 list`. Used by wrangler CLI arguments (`wrangler d1 execute <database_name> ...`); not read by the Worker.
+- `database_id` is the vendor-assigned UUID from `wrangler d1 create` or `wrangler d1 info`. This is the durable identifier the vendor uses; substitute the value the project owns.
+
+## Full shape with migration overrides (wrangler.jsonc)
+
+```jsonc
+{
+  "d1_databases": [
+    {
+      "binding": "<BINDING_NAME>",
+      "database_name": "<database-name>",
+      "database_id": "<database-uuid>",
+      "migrations_dir": "migrations",
+      "migrations_table": "d1_migrations",
+      "migrations_pattern": "*.sql"
+    }
+  ]
+}
+```
+
+Field notes:
+
+- `migrations_dir` names the directory the migration files live in. Default: `migrations/` at the wrangler config's parent directory. TAC-1402 anchors the migration catalog to this value.
+- `migrations_table` names the D1-side bookkeeping table. Default: `d1_migrations`. TAC-1402 anchors the applied-state ledger to this value; AC-13102-3 reads this table for verification.
+- `migrations_pattern` is a glob selecting migration files under `migrations_dir`. Default: the wrangler-generated numbered form. Override for ORM compatibility (Drizzle's `0000_name.sql`, Prisma's `<timestamp>_name/migration.sql`).
+
+## Per-environment shape
+
+Environments (dev, preview, live) each get their own D1 database. The `env` block on the wrangler config binds them per environment:
+
+```jsonc
+{
+  "d1_databases": [
+    {
+      "binding": "<BINDING_NAME>",
+      "database_name": "<database-name>-dev",
+      "database_id": "<dev-database-uuid>"
+    }
+  ],
+  "env": {
+    "preview": {
+      "d1_databases": [
+        {
+          "binding": "<BINDING_NAME>",
+          "database_name": "<database-name>-preview",
+          "database_id": "<preview-database-uuid>"
+        }
+      ]
+    },
+    "live": {
+      "d1_databases": [
+        {
+          "binding": "<BINDING_NAME>",
+          "database_name": "<database-name>-live",
+          "database_id": "<live-database-uuid>"
+        }
+      ]
+    }
+  }
+}
+```
+
+TAC-1403's deploy-gate orders `wrangler d1 migrations apply <database-name> --env <target>` strictly before `wrangler deploy --env <target>` for each named environment. The binding name stays constant across environments so the facade module reads the same `env[BINDING_NAME]` regardless of target.
+
+## What this asset is not
+
+Not a wrangler config template the project copies verbatim. The shape above is the SHAPE of the binding block; the project fills in its own identifiers, compatibility date, and any other fields (routes, custom domains, Static Assets) its Worker needs. A future `deploy-cloudflare-workers` blueprint (round-2 sibling) is the natural owner of the wider wrangler config surface; this blueprint owns the D1 binding shape only.
+
+Not a credentials-storage guide. `CLOUDFLARE_API_TOKEN` and any deploy-specific secret the CI job uses are the concern of the `security-secrets-management` blueprint; store them there, not in this file.

package/blueprints/persistence-data-d1/blueprint.json

@@ -0,0 +1,42 @@
+{
+  "slug": "persistence-data-d1",
+  "version": "1.0.0",
+  "category": "persistence",
+  "contributions": [
+    { "id": "persistence-data-d1-REQ-001", "kind": "req", "path": "requirements/persistence-data-d1-req-001.json" },
+    { "id": "persistence-data-d1-REQ-002", "kind": "req", "path": "requirements/persistence-data-d1-req-002.json" },
+    { "id": "persistence-data-d1-REQ-003", "kind": "req", "path": "requirements/persistence-data-d1-req-003.json" },
+    { "id": "persistence-data-d1-REQ-004", "kind": "req", "path": "requirements/persistence-data-d1-req-004.json" },
+    { "id": "persistence-data-d1-REQ-005", "kind": "req", "path": "requirements/persistence-data-d1-req-005.json" },
+    { "id": "persistence-data-d1-REQ-006", "kind": "req", "path": "requirements/persistence-data-d1-req-006.json" },
+    { "id": "persistence-data-d1-REQ-007", "kind": "req", "path": "requirements/persistence-data-d1-req-007.json" },
+    { "id": "persistence-data-d1-US-13101", "kind": "us", "path": "user-stories/persistence-data-d1-us-13101.json" },
+    { "id": "persistence-data-d1-US-13102", "kind": "us", "path": "user-stories/persistence-data-d1-us-13102.json" },
+    { "id": "persistence-data-d1-US-13103", "kind": "us", "path": "user-stories/persistence-data-d1-us-13103.json" },
+    { "id": "persistence-data-d1-US-13104", "kind": "us", "path": "user-stories/persistence-data-d1-us-13104.json" },
+    { "id": "persistence-data-d1-US-13105", "kind": "us", "path": "user-stories/persistence-data-d1-us-13105.json" },
+    { "id": "persistence-data-d1-US-13106", "kind": "us", "path": "user-stories/persistence-data-d1-us-13106.json" },
+    { "id": "persistence-data-d1-US-13107", "kind": "us", "path": "user-stories/persistence-data-d1-us-13107.json" },
+    { "id": "TAC-1401-persistence-data-d1-facade", "kind": "tac", "path": "tacs/tac-1401-persistence-data-d1-facade.json" },
+    { "id": "TAC-1402-persistence-data-d1-migration-catalog", "kind": "tac", "path": "tacs/tac-1402-persistence-data-d1-migration-catalog.json" },
+    { "id": "TAC-1403-persistence-data-d1-deploy-gate", "kind": "tac", "path": "tacs/tac-1403-persistence-data-d1-deploy-gate.json" },
+    { "id": "TAC-1404-persistence-data-d1-recovery-runner", "kind": "tac", "path": "tacs/tac-1404-persistence-data-d1-recovery-runner.json" },
+    {
+      "id": "ADR-1401-persistence-data-d1-store-model",
+      "kind": "adr",
+      "path": "adrs/adr-1401-persistence-data-d1-store-model.json",
+      "scope": "global",
+      "topic": "persistenceStore"
+    },
+    {
+      "id": "ADR-1402-persistence-data-d1-migration-discipline",
+      "kind": "adr",
+      "path": "adrs/adr-1402-persistence-data-d1-migration-discipline.json",
+      "scope": "global",
+      "topic": "migrationDiscipline"
+    },
+    { "id": "ADR-1403-persistence-data-d1-event-secrecy", "kind": "adr", "path": "adrs/adr-1403-persistence-data-d1-event-secrecy.json" },
+    { "id": "ADR-1404-persistence-data-d1-store-boundary", "kind": "adr", "path": "adrs/adr-1404-persistence-data-d1-store-boundary.json" },
+    { "id": "ADR-1405-persistence-data-d1-recovery-model", "kind": "adr", "path": "adrs/adr-1405-persistence-data-d1-recovery-model.json" }
+  ]
+}

package/blueprints/persistence-data-d1/contributions/adrs/adr-1401-persistence-data-d1-store-model.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1401-persistence-data-d1-store-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Cloudflare D1 as the project's primary durable store, read through a Worker-side facade; other engines behind the same facade contract on supersede",
+  "context": "A project deployed on Cloudflare Workers has a natural persistence choice: D1, the vendor's managed serverless SQLite-semantics database, bound directly into the Worker's `env` and accessed request-scoped through a vendor-owned prepared-statement surface. The alternatives (a self-managed store fronted by a Worker adapter, an external Postgres reached from the Worker over HTTPS, an in-memory Workers KV substrate) each cost the project either an operator surface the Workers tier is supposed to eliminate or the relational semantics the domain expects. The rcf-lite Workers-tier target for this blueprint has one obvious answer.",
+  "decision": "The default primary durable store is one Cloudflare D1 database bound into the Worker under a named binding declared in `d1_databases[]`, accessed through the D1 store facade (TAC-1401) which is the only module that reads the binding. One binding per environment; the binding name and database identifier are project-configured; migrations are numbered forward-only `.sql` files under the wrangler-managed directory and applied by the vendor's own tooling (TAC-1402); the deploy pipeline is the gate that binds the applied set to the deployed Worker (TAC-1403); recovery is Time Travel plus a scheduled portable export (TAC-1404). Other engines behind the same store facade contract on supersede: a project that outgrows the D1 tier, or that has a workload D1 does not fit (relational semantics but scale beyond a single D1 database, non-Workers deploy target), supersedes this ADR with a project-level ADR selecting the alternate engine and replaces the facade's binding read with an engine-appropriate handle.",
+  "consequences": "The project inherits zero-infrastructure persistence at the Workers tier: no database server, no connection pool, no network round trip outside the vendor's own edge substrate. The binding is request-scoped inside the Worker; the facade is the one module the vendor surface lives in; migrations are a CI concern, not a boot-time runner; recovery is a wrangler command, not a hand-rolled backup daemon. The scale ceiling is the vendor's per-database size limit (a currently-published upper bound of 10 GB per D1 database on the Paid plan; 500 MB on the Free plan) plus the queries-per-Worker-invocation limit (currently 1000 on Paid, 50 on Free); a project whose steady-state working set outgrows either supersedes this ADR. Composing blueprints that hold an opinion on the store engine conflict on the `persistenceStore` topic; this blueprint's ADR is one of at least two shipped answers on the rcf-lite shelf (the other names a single-file local SQLite for non-Workers tiers), and the expected resolution is one project-level ADR that fixes the engine and states the tier reasoning.",
+  "alternativesConsidered": [
+    {
+      "name": "External Postgres reached from the Worker over HTTPS",
+      "summary": "Point the Worker at a hosted Postgres (Neon, Supabase, an operator-run cluster) reached via an HTTP-fronted client; the store facade wraps the HTTP client.",
+      "reasonNotChosen": "Wrong shape for the tier. A Workers-deployed application whose persistence is a network hop outside the vendor's edge substrate pays the round-trip on every request, gives up the vendor's built-in point-in-time recovery, and reintroduces the connection-pool sizing problem the Workers tier is supposed to remove. Projects whose scale genuinely needs Postgres supersede this ADR; the Workers tier is not where that supersede is default."
+    },
+    {
+      "name": "Cloudflare Workers KV as the substrate",
+      "summary": "Drop the relational shape and use KV as the persistence layer; the store facade wraps KV get/put.",
+      "reasonNotChosen": "The relational shape is what makes the query story sane for the domain the rcf-lite Workers-tier target typically ships. KV pushes the query problem into application code and gives up the constraint-checking safety net the SQL substrate provides for free. Projects whose domain is genuinely KV-shaped supersede this ADR and pick a KV blueprint when one ships."
+    },
+    {
+      "name": "Ship D1 and a second engine as co-contributed alternate TACs in one blueprint",
+      "summary": "Contribute D1 and Postgres store TACs side by side; the project picks one at apply time.",
+      "reasonNotChosen": "The rcf-lite blueprint mechanism (Phase 1) has no variant/profile selector. Two TACs contributed together are both applied, and both leave dangling tacIds references on their user stories if the project only realises one. The composable-vendor-siblings pattern (this blueprint plus the SQLite blueprint, each shipping its own opinion on `persistenceStore`, resolved at operator supersede time) is the shape the mechanism supports today; a mechanism-side variant concept is a future investment."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}