@fabrika/builder 0.2.0

package/decisions/patterns/lib-publish.md

@@ -0,0 +1,46 @@
+---
+id: lib-publish
+kind: pattern
+title: Lib publish — tag → npm publish with OIDC trusted publishing + provenance
+slot: null
+provides: [npm-publish, oidc-trusted-publish, provenance]
+requires: []
+recommends: [bun, monorepo]
+conflicts: []
+status: stable
+sources:
+  - where: "oblaka / lopata / buzola / pletivo — .github/workflows/release.yml (tag-triggered publish)"
+    read: "The `on: push: tags: ['v*']` trigger, `permissions: id-token: write`, and `npm publish --provenance --access public` with no NPM_TOKEN."
+  - where: "opice — .github/workflows/release.yml (monorepo: version rewrite + per-package publish); roj — .github/workflows/publish.yml + scripts/npm-publish/"
+    read: "Multi-package coordination: rewrite versions + resolve workspace:* refs at publish time."
+---
+
+# Lib publish (npm, OIDC trusted publishing)
+
+## What it is
+
+A library publishes on a **git tag `v*`** via GitHub Actions using **OIDC trusted
+publishing** — `permissions: id-token: write`, then **`npm publish --provenance
+--access public`** with **no long-lived `NPM_TOKEN`** (GitHub's OIDC token is
+exchanged by npm for short-lived registry auth, and `--provenance` attaches SLSA
+build attestation). Requires **npm ≥ 11.5.1** (some workflows `npm i -g npm@latest`
+first). Version bumps are explicit (`package.json` → tag), no changeset tooling.
+
+## When & why to use
+
+- Publishing any `@scope/*` package (our libs: oblaka, lopata, opice, buzola, pletivo, @roj-ai/*) — secure, tokenless, provenance-stamped.
+
+## When NOT to use
+
+- Private/unpublished packages, or apps (apps **deploy**, see `app-deploy`).
+
+## Gotchas
+
+- **`id-token: write` is mandatory** — without it the OIDC exchange fails; there's no token fallback by design.
+- **npm ≥ 11.5.1** for OIDC trusted publishing; pin Node/npm in the runner.
+- **Trusted publishing must be configured on the npm package** (the repo/workflow is registered as a trusted publisher) before the first run.
+- **Monorepo multi-package**: rewrite each `package.json` version from the tag **and resolve `workspace:*`** refs to the concrete version before publishing each package.
+
+## Relationships — why
+
+- A CI pattern (no runtime tech deps). **recommends `bun`** (build/pack) and **`monorepo`** (multi-package publish coordination). The lib-side counterpart of `app-deploy`.

package/decisions/patterns/monorepo.md

@@ -0,0 +1,47 @@
+---
+id: monorepo
+kind: pattern
+title: Monorepo (Bun workspaces + flat catalog + project references)
+slot: null
+provides: [monorepo, workspaces, shared-packages]
+requires: [bun]
+recommends: [deptective]
+conflicts: []
+status: stable
+sources:
+  - where: "Bun workspaces documentation"
+    read: "Workspace manifests, dependency ranges, and filtered scripts."
+  - where: "roj — root package.json + packages/* (the same Bun-workspaces shape for @roj-ai/*)"
+    read: "A second real Bun-workspaces monorepo to cross-check conventions."
+---
+
+# Monorepo
+
+## What it is
+
+A **Bun workspaces** monorepo: `packages/*`, scoped `@app/<kebab>` package names,
+cross-package deps via **`workspace:*`** (resolved to symlinks at install), a **single
+flat `catalog`** in the root `package.json` as the one source of truth for transitive
+versions, and **`tsc --build` project references** for type-checking. One linter +
+one formatter across the tree (e.g. oxlint + dprint).
+
+## When & why to use
+
+- A backend + multiple frontends (web/mobile/worker) that **share domain types + logic** (a `shared` package of Zod schemas, a `lib` of cross-cutting utilities).
+- You want one lock file, cross-package tests, and no npm round-trip during dev.
+
+## When NOT to use
+
+- Packages need **independent release schedules** → separate repos + npm.
+- Fundamentally different build systems per package.
+
+## Gotchas
+
+- **`workspace:*` = symlinks, not copies** — import from the package root (`import '@app/lib'`), never reach into `node_modules`.
+- The **root `workspaces` list is the source of truth** — add a package dir _and_ run `bun install` or it isn't discovered.
+- **One flat `catalog`**, no `catalogs.*` groups; bump versions in one place.
+- **`tsc --build` needs `composite: true`** per package + a `references` list in the root tsconfig, or the build breaks.
+
+## Relationships — why
+
+- **requires `bun`** — Bun workspaces + the catalog are the mechanism. **recommends `deptective`** — keep cross-package deps honest (missing/unused, project-reference drift).

package/decisions/patterns/named-seeds.md

@@ -0,0 +1,45 @@
+---
+id: named-seeds
+kind: pattern
+title: Named idempotent seeds (vs self-provisioning)
+slot: seed-strategy
+provides: [seed-strategy, foundation-manifest]
+requires: [d1]
+recommends: [opice]
+conflicts: []
+npm: []
+status: stable
+sources:
+  - where: "Pattern. Reference: opice skeleton metadata `seeds: [...]` + fabrika `induce`."
+    read: "How the union of `seeds` across skeletons induces a foundation 'seed infra' issue."
+---
+
+# Named idempotent seeds
+
+## What it is
+
+The seed strategy fabrika prefers: **one SQL file per named seed** (`seeds/<name>.sql`,
+filename = opice `seeds: ['<name>']`), purely **idempotent** (`INSERT OR IGNORE` /
+`ON CONFLICT DO NOTHING`, keyed on stable ids), applied before a test. The
+alternative is **self-provisioning** (register through the UI with `Date.now()`
+markers, `seeds: []`).
+
+## When & why to use
+
+- You want "seeds = foundation manifest": fabrika induces a foundation data issue from the **union of `seeds`** across skeletons. Named seeds make that induction strong.
+- Data that pre-exists for a flow (catalog, members, projects, mixed issues).
+
+## When NOT to use (fallback)
+
+- Flows where a seed makes no sense (**signup**) → `seeds: []` + **self-provisioning** with `Date.now()` markers. This is the explicit fallback, not a competing slot.
+
+## Impacts & gotchas
+
+- **Idempotent or it breaks the verify loop** — the app stays up between iterations and reseeding must tolerate repeats.
+- Some seeds also stage non-D1 fixtures (R2 object, KV key) via a small `seeds/<name>.ts`.
+- Apply: `lopata d1 execute DB --file seeds/<name>.sql` (local-first) or `wrangler d1 execute DB --local --file …`.
+
+## Relationships — why
+
+- **requires `d1`** — seeds are SQL into the relational store.
+- **recommends `opice`** — the filename↔metadata link (`seeds: ['<name>']`) is the contract that drives induction.

package/decisions/patterns/observability.md

@@ -0,0 +1,45 @@
+---
+id: observability
+kind: pattern
+title: Observability on Workers (logs + metrics via Analytics Engine + traces)
+slot: null
+provides: [observability, tracing, metrics]
+requires: []
+recommends: [analytics-engine, structured-logging, sentry]
+conflicts: []
+status: stable
+sources:
+  - where: "Cloudflare Analytics Engine docs"
+    read: "writeDataPoint, SQL queries, sampling behavior, and binding limits."
+  - where: "Cloudflare docs (Workers observability logs/traces, Analytics Engine) + oblaka's AE resource and `observability: { enabled: true }`"
+    read: "How logs/traces are enabled in wrangler/oblaka, the AE writeDataPoint limits, and tail workers."
+---
+
+# Observability on Workers
+
+## What it is
+
+The three pillars, the way they fit Cloudflare Workers:
+
+- **Logs** — `structured-logging` to stdout, with `observability: { logs: { enabled: true } }` in wrangler/oblaka so CF ingests them (CF **samples** under load → keep a durable handler for complete audit).
+- **Metrics** — **Analytics Engine** via `writeDataPoint`, hidden behind an **`AnalyticsSink` port** with a **typed event union**; the AE adapter in prod, a capturing sink in tests (see `count-store` for the same local/AE split).
+- **Traces** — W3C `traceparent` + AsyncLocalStorage span context; `observability: { traces }` + Workers tail workers. **No heavy OpenTelemetry SDK** — ports/adapters + structured spans cover it.
+
+## When & why to use
+
+- Any production Worker — you want correlation (requestId/traceId across hops), metrics that survive bursts (AE append, not D1 UPDATE), and a path to debug incidents.
+
+## When NOT to use
+
+- A throwaway/local-only app — structured logs alone suffice; skip AE wiring.
+
+## Gotchas
+
+- **AE cardinality limits**: ≤1 index (≤96 B), ≤20 doubles, ≤20 blobs (~16 KB/row) — **no free-form strings as blobs**; use stable enums + ids.
+- **CF samples logs** under load — don't rely on stdout logs for a complete audit trail; add a durable (DO) handler if you need every line.
+- **Propagate `traceparent`** on outbound requests — CF doesn't auto-propagate across service bindings.
+- **Sample at the source** if event volume is high (AE has no built-in sampling in the sink).
+
+## Relationships — why
+
+- **recommends `analytics-engine`** (metrics backend, behind `count-store`/an AnalyticsSink), **`structured-logging`** (the logs pillar), **`sentry`** (errors → traces). A pattern, composes over whatever stack is present.

package/decisions/patterns/single-worker-spa.md

@@ -0,0 +1,74 @@
+---
+id: single-worker-spa
+kind: pattern
+title: Single-Worker SPA in production, split frontend/backend in development
+slot: app-delivery-shape
+provides: [spa-hosting, worker-api, local-dev-split, single-deployable]
+requires: [cloudflare, vite, buzola]
+recommends: [lopata, vozka]
+conflicts: []
+status: stable
+sources:
+  - where: "Cloudflare Workers Static Assets docs"
+    read: "API-first Worker routing, the ASSETS binding, SPA fallback, and run_worker_first behavior."
+  - where: "Cloudflare Workers Static Assets docs"
+    read: "The current assets binding, run_worker_first and not_found_handling semantics."
+---
+
+# Single-Worker SPA, two-process local dev
+
+## What it is
+
+A Buzola SPA and a Worker API are separate processes during development but one
+deployable Worker in production:
+
+- **development:** Vite serves the SPA with HMR (normally `:5173`), lopata serves
+  the Worker and local bindings (normally `:8787`), and Vite proxies only the API
+  namespaces to lopata;
+- **production:** Vite builds static assets, the Worker's `ASSETS` binding serves
+  them, and the same Worker handles API routes before falling back to the SPA.
+
+## When & why to use
+
+- Internal dashboards/admin apps where SSR has no product value.
+- You want fast frontend HMR and local CF bindings without deploying two services.
+- Client routes need deep-link fallback while API paths remain real 404s.
+
+## Integration contract
+
+1. Vite emits the SPA to the directory declared by the Worker's assets binding.
+2. `vite.config.ts` proxies explicit namespaces such as `/rpc`, `/api` and
+   `/internal` to the local lopata Worker.
+3. Static assets use `not_found_handling: 'single-page-application'`.
+4. Prefer selective `run_worker_first` patterns for `/rpc`, `/api/*` and
+   `/internal/*`, so non-API assets/navigation skip the Worker entirely.
+5. The Worker handles the matched API routes; an unhandled path _inside an API
+   namespace_ returns 404 and never falls through to `index.html`.
+6. If whole-page middleware truly requires `run_worker_first: true`, the Worker
+   must explicitly forward every non-API request with `env.ASSETS.fetch(request)`.
+
+## Load-bearing gotchas
+
+- **Do not proxy `/` in development.** Vite owns page/navigation requests; only
+  API namespaces go to lopata.
+- **Do not let unknown API paths render the SPA shell.** Keep an explicit API
+  prefix guard before the assets fallback.
+- New scaffolds should prefer
+  the supported route-array form unless they need middleware on every page/asset
+  request. It avoids unnecessary billed Worker invocations.
+- `ASSETS` may be absent locally. Type it as optional and return a real 404 after
+  API handling in the two-process dev flow.
+- Browser requests need cookies on same-origin production calls. In development,
+  use Vite's proxy so the SPA still calls relative URLs and auth behavior does not
+  fork by environment.
+- Buzola is client-only; there is no Worker SSR entry in this pattern.
+- Verify selective routing against the installed Wrangler schema (route arrays
+  require a sufficiently recent Wrangler); never guess glob support.
+
+## Relationships — why
+
+- **requires `buzola` + `vite`** — this is specifically a client-rendered Buzola
+  bundle served by Vite locally and built as Worker assets.
+- **requires `cloudflare`** — production delivery uses a Worker assets binding.
+- **recommends `lopata`** for the local Worker and **`vozka`** for the single
+  production deployable.

package/decisions/patterns/structured-logging.md

@@ -0,0 +1,49 @@
+---
+id: structured-logging
+kind: pattern
+title: Structured logging (handlers + child context + span/trace)
+slot: null
+provides: [structured-logging, log-correlation, leveled-logging]
+requires: []
+recommends: [observability]
+conflicts: []
+status: stable
+sources:
+  - where: "OpenTelemetry semantic conventions and W3C Trace Context"
+    read: "Stable field names, trace propagation, span context, and structured errors."
+  - where: "Sentry structured logs documentation"
+    read: "Level filtering, contextual fields, and error forwarding."
+---
+
+# Structured logging
+
+## What it is
+
+A `Logger` built from **composable handlers** (`createLogger([handlers], baseAttrs)`),
+with leveled, **structured** entries (`logger.info("event", { fields })`), `.child({
+requestId, userId })` to attach correlation context at a boundary, and **span/trace
+context** (AsyncLocalStorage + W3C `traceparent`) so logs correlate across RPC/DO
+hops. Injected via the DI container — **never raw `console.log`** in app code.
+
+## When & why to use
+
+- Always, in a Worker/backend — searchable, correlatable logs (by requestId/traceId) instead of stringly console output that CF samples and drops.
+
+## Anti-patterns (avoid these)
+
+1. **`console.log` spam** — unstructured, no context, dropped under CF log sampling. → `logger.info("feature.event", { id })`.
+2. **Logging secrets / PII / tokens** — leaks to Sentry, CF logs, DO logs (unredacted). → log ids + safe enums only; redact at the boundary.
+3. **Logging in hot loops** — cardinality blowup + ring-buffer thrash. → log once with a `count`, not per item.
+4. **Stringly-typed messages** (`"User " + id + " failed"`) — unsearchable, unaggregatable. → kebab event + structured attrs: `logger.warn("auth.login.failed", { userId })`.
+5. **No requestId propagation** — logs fragment across services/DOs. → `.child({ requestId })` at the RPC boundary + propagate `traceparent`.
+6. **Swallowing errors** (`catch { logger.warn("failed") }` without the error) — stack lost, Sentry blind. → `logger.error("op.failed", err, { ctx })`.
+
+## Best practices
+
+- One logger built in the DI container; `.child()` per request with `requestId`/`userId`.
+- Kebab `feature.scope.event` message names + structured attrs; levels mean what they say.
+- For complete (un-sampled) audit logs, add a durable handler (e.g. a DO ring-buffer), not just stdout.
+
+## Relationships — why
+
+- A pattern (no tech deps). **recommends `observability`** — structured logs are one of its three pillars; the Sentry handler ties into `sentry`.

package/decisions/patterns/typed-worker-rpc.md

@@ -0,0 +1,87 @@
+---
+id: typed-worker-rpc
+kind: pattern
+title: Typed SPA-to-Worker RPC boundary
+slot: client-worker-api
+provides: [typed-rpc, client-worker-api, validated-input, centralized-auth]
+requires: [cloudflare, buzola]
+recommends: [propustka]
+conflicts: []
+status: stable
+sources:
+  - where: "Cloudflare Workers RPC documentation"
+    read: "Typed method boundaries, input validation, response envelopes, and centralized authentication."
+---
+
+# Typed SPA-to-Worker RPC
+
+## What it is
+
+A small application-owned RPC boundary between a Buzola SPA and its Worker. The
+Worker composes a method map; each method owns an input parser and a handler. A
+type-only projection of that map gives the browser client fully inferred method
+names, inputs and outputs without shipping Worker implementation code.
+
+This is a pattern, not a framework dependency. It keeps the client-rendered stack
+small while preserving end-to-end types and one authentication boundary.
+
+## Contract
+
+```ts
+interface RpcMethod<Input, Output> {
+	input: { parse(value: unknown): Input }
+	handle(
+		input: Input,
+		auth: AuthContext,
+		request: Request,
+	): Output | Promise<Output>
+}
+
+type InferRpcMethods<M> = {
+	[K in keyof M]: M[K] extends RpcMethod<infer I, infer O>
+		? { input: I; output: Awaited<O> }
+		: never
+}
+```
+
+- The SPA posts `{ method, input }` to one relative endpoint such as `/rpc`.
+- The Worker parses JSON, rejects an unknown method, validates input, invokes the
+  registered handler and returns either `{ result }` or a typed `{ error }`.
+- The client imports the combined method-map type with **`import type`** and
+  exposes `callRpc(method, input)` for Buzola loaders plus a stable hook for
+  component mutations.
+- The Worker authenticates once at the RPC boundary and passes `AuthContext` to
+  the selected method. Each method still performs its own `auth.can(...)` check.
+
+## Load-bearing gotchas
+
+- **The client/server bridge must be type-only.** A value import from the Worker
+  method registry can pull Cloudflare-only modules and secrets into the browser
+  bundle.
+- Validate both the envelope and every method input. A TypeScript type is not
+  runtime validation; reject malformed JSON/input with 400.
+- Method names are an explicit allow-list. Never dispatch an arbitrary property
+  path or instantiate a handler from user input.
+- Normalize known failures (validation 400, unauthorized 401, forbidden 403,
+  not found 404); log unexpected errors server-side and return a safe 500.
+- With Propustka, preserve `loginUrl` in the 401 envelope and attach a returned
+  `setCookie` to the final RPC response. The SPA redirects a human miss to login
+  and guards against redirect loops.
+- Use relative `/rpc` URLs. The Vite proxy owns the local backend origin; this
+  keeps cookie and request code identical in development and production.
+
+## Feature composition
+
+Keep each feature's methods in a factory/class with constructor-injected ports
+(D1 store, queue, provider, clock). Merge their method maps in one
+`buildRpcMethods(env, ctx)` composition root and export only the inferred map
+type. Unit-test method factories directly with an in-memory/fake AuthContext;
+exercise the envelope/auth seam in a smaller set of integration tests.
+
+## Relationships — why
+
+- **requires `cloudflare`** — the server side is the app Worker.
+- **requires `buzola`** — the client surface is designed for loaders + SPA
+  mutations, not SSR actions.
+- **recommends `propustka`** — central boundary authentication plus per-method
+  capability checks is the intended secure shape.

package/decisions/patterns/vozka-app-deploy.md

@@ -0,0 +1,74 @@
+---
+id: vozka-app-deploy
+kind: pattern
+title: App deploy — Vozka-managed Cloudflare lifecycle
+slot: null
+provides: [ci-deploy, cf-deploy, infra-provisioning, schema-reconciliation, secret-sync]
+requires: [vozka, propustka, oblaka, wrangler]
+recommends: []
+conflicts: [app-deploy]
+status: wip
+sources:
+  - where: "vozka — MIGRATION.md + packages/core/src/{plan,deploy}.ts"
+    read: "Registry fields, trigger routing, deploy locks, step order, state continuity and migration/cut-over rules."
+  - where: "vozka examples"
+    read: "A native-Propustka app shape with one resource graph plus its schema, build, and secrets pipeline."
+---
+
+# Vozka-managed app deploy
+
+## What it is
+
+The application repository declares its complete deploy surface in
+`vozka.config.ts`; the account's Vozka control plane owns GitHub triggers/manual
+runs, deploy credentials, per-app/per-env locking, logs and execution. The app no
+longer maintains a workflow that manually sequences oblaka, wrangler, Propustka
+and secrets.
+
+## Scaffold contract
+
+- Commit `vozka.config.ts` with a stable app `id`, environment-neutral
+  `resources(ctx)`, optional Propustka `schema`, and `pipeline`.
+- Export the resource builder for the local `oblaka.ts` shim so the graph does
+  not drift between lopata and production.
+- Read the production hostname from `ctx.domain`.
+- Bind `IAM: ServiceReference('propustka-worker')` only off-local; set a single
+  explicit local-dev flag for the app's deterministic auth context.
+- Declare third-party runtime secrets in `pipeline.secrets`. Vozka platform
+  Cloudflare credentials and the Propustka provisioning key are not app secrets.
+- Register repository, environment, domain, trigger ref and secret values in
+  the target account's Vozka. That external registration is an operator step,
+  not committed application config.
+
+## Deploy order (owned by Vozka)
+
+1. run `pipeline.build`,
+2. provision/materialize the oblaka resource graph into `wrangler.jsonc`,
+3. apply every declared D1 migration remotely,
+4. run `wrangler deploy`,
+5. reconcile the Propustka authz schema,
+6. sync declared Worker secrets.
+
+The exact plan comes from the installed Vozka engine. Do not reproduce this
+sequence in a parallel GitHub Actions workflow.
+
+## Migration/cut-over gotchas
+
+- Preserve `<app-id>-state`; dry-run and verify that the first Vozka deploy sees
+  existing resources instead of creating replacements.
+- The first schema reconcile should be a no-op. Diff committed actions/scopes/
+  roles against live Propustka before cut-over.
+- A multi-account app is registered in multiple independent Vozka instances;
+  branch/ref routing decides which account acts on a push.
+- During migration, only one deploy path may own a target. Delete the old
+  workflow after a real Vozka deploy is green, not before.
+- Vozka is 0.x: verify current dry-run credential/network requirements instead
+  of assuming a dry-run is offline.
+
+## Relationships — why
+
+- **requires `vozka`**, which orchestrates **`oblaka` + `wrangler`**.
+- **requires `propustka`** because schema reconciliation and the ecosystem's
+  control-plane authentication are part of this lifecycle.
+- **conflicts `app-deploy`** — that pattern is the direct per-repo workflow
+  alternative. One target must not deploy through both.

package/decisions/patterns/write-split.md

@@ -0,0 +1,47 @@
+---
+id: write-split
+kind: pattern
+title: Three-store write split (AE counts / Queue→R2 payloads / D1 state)
+slot: null
+provides: [ingest-architecture]
+requires: [analytics-engine, queue, r2, d1]
+recommends: [count-store]
+conflicts: []
+npm: []
+status: stable
+sources:
+  - where: "Pattern. Reference: the cf-fat stack (ingest route + queue consumer)."
+    read: "How an error-tracker-style bursty write workload is split across primitives."
+---
+
+# Three-store write split
+
+## What it is
+
+An ingest architecture for **bursty write workloads** (error trackers, event
+pipelines): split each write by shape —
+
+- **counts → Analytics Engine** (append via `count-store`, no UPDATE),
+- **full payloads → Queue → R2** (202 fast, consumer batches puts),
+- **mutable state → D1** (only human-driven rows: issues, projects, config),
+- **keys / dedup / session → KV**.
+
+## When & why to use
+
+- Per-event `UPDATE count` on a D1 row would be hot-row contention an error storm kills.
+- High-volume ingest where the request path must stay fast and writes must absorb bursts.
+
+## When NOT to use
+
+- Low write volume / no spikes — a single `d1` store is simpler and correct.
+
+## Impacts & gotchas
+
+- Ingest route returns **202** and enqueues; it does **NOT** write D1 synchronously per event.
+- The `queue` consumer does R2 payload write + D1 upsert + `count-store.record`.
+- Frozen as a tech-gate decision when chosen — it shapes the whole data flow.
+
+## Relationships — why
+
+- **requires `analytics-engine` + `queue` + `r2` + `d1`** — it is precisely the composition of all four.
+- **recommends `count-store`** — the counts arm goes through it so dev/test stay account-free.

package/decisions/technologies/analytics-engine.md

@@ -0,0 +1,44 @@
+---
+id: analytics-engine
+kind: technology
+title: Cloudflare Analytics Engine (counts / time-series)
+slot: null
+provides: [timeseries-counts, metrics]
+requires: [cloudflare, count-store]
+recommends: [d1]
+conflicts: []
+npm: []
+status: stable
+sources:
+  - where: "developers.cloudflare.com/analytics/analytics-engine (writeDataPoint, SQL API, _sample_interval)"
+    read: "writeDataPoint limits (≤20 blobs/doubles, 1 index), the SQL HTTP query endpoint, and SUM(_sample_interval) sampling."
+---
+
+# Cloudflare Analytics Engine
+
+## What it is
+
+High-cardinality, append-only time-series counts. You `env.AE.writeDataPoint(...)`
+on the write path (no UPDATE, no hot row) and query aggregates over the **SQL HTTP
+API** with `SUM(_sample_interval)`. The right home for "how many of X, grouped by
+Y, over time" at error-storm volume.
+
+## When & why to use
+
+- Event counts / trends / grouping where per-row UPDATE in D1 would be hot-row contention (e.g. error-tracker issue counts).
+- Append-only metrics you read as aggregates, not individual rows.
+
+## When NOT to use
+
+- Mutable state or exact read-after-write → `d1` / `durable-objects`.
+- Anything you need locally without an account, **unless** abstracted (see below).
+
+## Impacts & gotchas — the load-bearing one
+
+- **No local runtime.** `writeDataPoint` is a no-op locally and queries hit the account HTTP SQL API (needs a CF token). So **counts MUST go behind `count-store`** (local/in-memory/D1 impl for dev+tests, AE impl for prod) — otherwise build/opice tests need a CF account.
+- `writeDataPoint`: ≤20 blobs + ≤20 doubles + **1 index**; queries use `SUM(_sample_interval)` to account for sampling.
+
+## Relationships — why
+
+- **requires `cloudflare`** (binding) **and `count-store`** (the abstraction that keeps dev/test account-free).
+- **recommends `d1`** — the local/test `count-store` impl typically aggregates from a D1 table.

package/decisions/technologies/bindx.md

@@ -0,0 +1,55 @@
+---
+id: bindx
+kind: technology
+title: Bindx — typed React data binding for Contember
+slot: data-binding
+provides: [react-data-binding, form-state, persistence, schema-codegen, undo-redo]
+requires: [contember, react]
+recommends: []
+conflicts: []
+npm: ["@contember/bindx@^0.1.41", "@contember/bindx-react@^0.1.41", "@contember/bindx-generator@^0.1.41", "@contember/bindx-client@^0.1.41"]
+status: wip
+sources:
+  - where: "bindx/packages/example/ (article-view.tsx, article-editor.tsx, App.tsx, generated/index.ts)"
+    read: "Real usage: Entity/Field/HasOne/HasMany components, usePersist, and the generated schema the app imports."
+  - where: "bindx/packages/bindx-react/src/index.ts"
+    read: "The hook + component surface (useEntity, useEntityList, usePersist, useUndo; Entity, Field, HasOne, HasMany, If, Show; ContemberBindxProvider)."
+  - where: "bindx/packages/bindx-generator/src/generate.ts"
+    read: "How `bun run generate:schema` turns a Contember Model (+ optional ACL) into typed entities + a schema object."
+---
+
+# Bindx
+
+## What it is
+
+A **typed, schema-bound React data-binding layer** over a Contember GraphQL API.
+You define the model in Contember, the generator emits TypeScript entity types + a
+schema object, and bindx gives you live data access, form state, dirty tracking,
+persistence, undo/redo, and field events — fully typed. Instead of
+`useState` + manual GraphQL + a form lib, you get `useEntity` / `useEntityList` +
+`<Entity>`/`<Field>`/`<HasMany>` and a single `usePersist()` that builds and posts
+the Contember mutations.
+
+## When & why to use
+
+- You have a **Contember** backend and are building a **React admin/CRUD/editor** that needs form state + binding.
+- You want **strict typing**: a model change breaks TypeScript immediately.
+- You want **persistence as one call** + free **undo/redo** + fine-grained field subscriptions.
+
+## When NOT to use
+
+- **Not using Contember** — bindx assumes Contember's GraphQL/mutation shape (core is adapter-pluggable, but the generator + ecosystem are Contember-shaped).
+- Lightweight client-only form state with no backend → `react-hook-form` + a store.
+
+## Impacts & gotchas
+
+- Requires a **live Contember API** + a **codegen step** (`generate:schema`) you run before TypeScript sees the entity types; commit the generated files.
+- **Selection is collected implicitly from JSX** — nesting unused relations over-fetches. Use `SelectionScope` / `debugSelection()`.
+- **Role-aware generation (ACL)** produces per-role entity types (PublicArticle/EditorArticle/…), which adds type complexity but enforces security.
+- **Undo is local-snapshot**, not a server transaction — a half-failed `persistAll()` undoes locally only; recover by refetching.
+
+## Relationships — why
+
+- **requires `contember`** — it is a binding layer over a Contember GraphQL API; no Contember, no bindx.
+- **requires `react`** — `@contember/bindx-react` ships React hooks/components (React 18+).
+- **slot `data-binding`** — orthogonal to the router; it composes with the rest of the stack.