okengine 0.8.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -50,6 +50,7 @@
     "lint": "oxlint --quiet",
     "lint:fix": "oxlint --fix",
     "fmt": "oxfmt",
+    "format": "oxfmt",
     "fmt:check": "oxfmt --check",
     "test": "bun test --pass-with-no-tests",
     "test:coverage": "bun test --coverage --pass-with-no-tests",
@@ -73,7 +74,7 @@
     "ajv-formats": "^3.0.1",
     "intl-messageformat": "^11.2.13",
     "oxc-parser": "^0.142.0",
-    "sently": "1.2.0"
+    "sently": "1.2.1"
   },
   "devDependencies": {
     "@base-ui/react": "^1.6.0",

package/site/content/docs/deployment/docker-swarm.mdx

@@ -0,0 +1,228 @@
+---
+title: Docker Swarm
+description: Deploy the generated compose stack with docker stack deploy — PgDog, HEALTHCHECK readiness, graceful SIGTERM, known multi-instance limits, and optional Caddy or Traefik.
+icon: Ship
+source: README.md
+---
+
+Swarm consumes the same files `oke docker --prod` already writes. It adds
+built-in orchestration (scale, rolling updates, routing mesh) with a lower
+learning curve than Kubernetes. Scale replaceable replicas; share durable drivers.
+
+<Callout title="The one rule">
+  Deploy with `docker stack deploy`. Docker’s single `HEALTHCHECK` targets `GET /_/ready`. Treat
+  every task as replaceable — shared Postgres / Redis / S3, SIGTERM via `stop_grace_period`, honest
+  Signal/Channel process-local limits.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Derive the prod compose layers
+
+```bash
+oke docker --prod
+```
+
+Emits `Dockerfile`, per-role layers, `compose.prod.yml` (`HEALTHCHECK` →
+`/_/ready`, `deploy.*`, `stop_grace_period: 30s`), and **`compose.all.yml`**
+(layers 1–3 merged). `compose.override.yml` is yours (never written by oke).
+
+</Step>
+
+<Step>
+### Build the app image, init Swarm, deploy
+
+`docker stack deploy` ignores `build` — tag first (name matches `compose.yml`).
+Prefer the single merged file:
+
+```bash
+docker build -t oke-<app>:latest -f docker/Dockerfile .
+docker swarm init
+cd docker
+docker stack deploy -c compose.all.yml myapp
+```
+
+Optional: `-c compose.override.yml` after that for local tweaks. Create
+`secrets:` names via `docker secret create`, or drop those keys in
+`compose.override.yml` while using `.env.docker`.
+
+</Step>
+
+<Step>
+### Scale and roll
+
+```bash
+docker service scale myapp_app=3
+docker service update --image oke-<app>:latest myapp_app
+```
+
+Prod overlay: `update_config` (`parallelism: 1`, `order: start-first`,
+`failure_action: rollback`) and `restart_policy.condition: on-failure`.
+Tweak in `compose.override.yml`.
+
+</Step>
+
+</Steps>
+
+## Share backing services
+
+Pin docker/prod drivers to shared stores:
+
+| Concern                       | Driver                       | Shared backend                                    |
+| ----------------------------- | ---------------------------- | ------------------------------------------------- |
+| SQL / durable journal / clock | `postgres`                   | Postgres (optionally via PgDog)                   |
+| Gate rate counters            | `redis` (`drivers.store.kv`) | Redis / Valkey / Dragonfly (`images["store.kv"]`) |
+| Files                         | `s3`                         | S3-compatible object store                        |
+| Signal                        | see known limits below       | —                                                 |
+
+## PgDog pooling
+
+Bun.SQL defaults to **10** connections per process — fine for one replica.
+Scale the Swarm service and `N × pool` can exceed Postgres `max_connections`.
+
+When both `store.sql` and `pgdog` are pinned (docker/prod default in templates),
+`DATABASE_URL` points at PgDog on port `6432` — transaction pooling, wire-protocol
+transparent to Bun.SQL / Drizzle. No app code changes.
+
+**Why PgDog.** Transaction pooling fixes the connection math. Naive poolers can
+leak session state (`SET`, RLS vars, `LISTEN`/`NOTIFY`) across clients; PgDog
+re-applies those under transaction mode.
+
+Read-replica routing (`BEGIN READ ONLY` → replica) is documented readiness —
+not configured in the generated stack yet.
+
+## Redis-protocol images (Redis · Valkey · Dragonfly)
+
+`images["store.kv"]` defaults to Redis (most mature). Pin Valkey or Dragonfly
+the same way — driver id stays `redis`, same `REDIS_URL`. Image table + one-line
+licenses: [Store · KV](/docs/elements/store#kv).
+
+## HEALTHCHECK (not two probes)
+
+Swarm has one Docker `HEALTHCHECK` — no separate readiness/liveness.
+
+| Endpoint       | Role in OKE                                            | Swarm                                                                                |
+| -------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `GET /_/ready` | Kernel readiness (`booting` → `orphan_scan` → `ready`) | **Use this** — mesh + rolling updates wait; `start_period: 60s` covers orphan resume |
+| `GET /health`  | App liveness (create-oke)                              | External monitors only — not a second native probe                                   |
+
+`/_/ready` returns `200 { ready: true }` only after boot and the durable orphan
+scan finish. While booting or scanning it returns
+`503 { ready: false, reason: "booting" | "orphan_scan" }`.
+
+**Consequence:** orphan scan delays “healthy” (and traffic) on purpose. After
+`start_period`, failing `/_/ready` can mark the task unhealthy and hit
+`restart_policy` — Swarm cannot drain traffic without also counting toward restart.
+
+## Graceful shutdown
+
+On `SIGTERM` / `SIGINT`, `installGracefulShutdown` (wired by `oke dev`’s app
+runner; call it next to `createBunRuntime().serve` in custom entries):
+
+1. Stops accepting new connections
+2. Releases **Clock** cron leases and **Journal** run leases held by this instance
+3. Closes element runtimes and exits
+
+Swarm sends SIGTERM on service update and scale-down the same way.
+
+Signal message leases have no proactive release today — survivors reclaim after
+the visibility TTL (default 30s). `compose.prod.yml` sets `stop_grace_period: 30s`
+(peer of K8s `terminationGracePeriodSeconds`) so release can finish.
+
+## Reverse proxy
+
+Swarm's routing mesh reaches tasks; it does **not** issue TLS certificates.
+For HTTPS on the same files, opt in to `images.proxy`:
+
+| Choice                       | Best for                                   | How routing works                                                  |
+| ---------------------------- | ------------------------------------------ | ------------------------------------------------------------------ |
+| **Caddy** (`caddy:2-alpine`) | Single instance, simplest automatic HTTPS  | Generated `Caddyfile` → `reverse_proxy app:6530`                   |
+| **Traefik** (`traefik:v3.3`) | Horizontally scaled compose / Swarm stacks | Docker labels on `app`; replicas auto-discovered and load-balanced |
+
+```typescript title="oke.config.ts"
+images: {
+  // …
+  proxy: "caddy:2-alpine", // or "traefik:v3.3"
+},
+```
+
+```bash title="docker/.env.docker"
+OKE_PROXY_HOST=app.example.com
+OKE_PROXY_ACME_EMAIL=admin@example.com
+```
+
+Include `compose.proxy.yml` in the `-c` list. Edge publishes `80`/`443`.
+Set `allowedHosts` to your public hostname ([Security](/docs/reference/security)).
+
+Traefik never mounts raw `docker.sock` — only a filtered
+`tecnativa/docker-socket-proxy` on the internal network. Full custom-domain,
+Let's Encrypt, and socket-proxy rationale → [Reverse proxy](/docs/deployment/reverse-proxy).
+
+## Known multi-instance limits
+
+| Surface                                  | Multi-instance today                                                                                       |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Clock (`postgres` / shared `file`)       | Shared leader election                                                                                     |
+| Journal (`postgres` / shared `file`)     | Shared durable runs + orphan resume                                                                        |
+| Gate rates (`drivers.store.kv: redis`)   | Shared counters                                                                                            |
+| Store SQL / KV redis / files `s3`        | Shared                                                                                                     |
+| Store files `fs`                         | **Per-instance filesystem** — boot warns; use `s3` when scaled                                             |
+| Signal `redis`                           | Emit relays to Redis; **consume / `live` / `drain` are process-local outbox** until Streams consume ships  |
+| Channel suppression / consent / receipts | **Default stores are process-local** — opt-out on replica A is invisible to B until a durable driver ships |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Stack deploy ignores my Dockerfile build">
+
+Build and tag first (`docker build -t oke-<app>:latest …`). Swarm runs the
+`image:` tag only — never compose `build:`.
+
+</Accordion>
+<Accordion title="New replica gets traffic before orphan scan finishes">
+
+Confirm `compose.prod.yml` is in the `-c` list and the task health-checks
+`/_/ready`. Without that HEALTHCHECK, Swarm treats “container started” as ready.
+
+</Accordion>
+<Accordion title="Rate limits look twice as high after scaling to 2">
+
+`drivers.store.kv` must be `redis` with `REDIS_URL` set. A missing URL **fails
+boot** (no silent memory fallback). Declaring `memory` for local is fine;
+docker/prod should stay on redis.
+
+</Accordion>
+<Accordion title="Files uploaded on task A are missing on task B">
+
+`drivers.store.files: "fs"` is single-host. Switch docker/prod to `s3`
+(create-oke templates already do).
+
+</Accordion>
+<Accordion title="Multi-node workers cannot reach store-sql">
+
+Generated `networks.oke.driver` is `bridge` (fine for single-node `swarm init`).
+Multi-node: set `driver: overlay` in `compose.override.yml`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Deployment](/docs/deployment) — choose compose, Swarm, or Kubernetes
+- [Docker](/docs/deployment/docker) — plain compose without Swarm
+- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik in full
+- [Kubernetes](/docs/deployment/kubernetes) — Deployment, probes, Ingress
+- [CLI](/docs/reference/cli) — `oke docker --prod`, `oke start`
+- [Store](/docs/elements/store) — PgDog and facets
+- [Flow](/docs/elements/flow) — durable journal
+
+## Next
+
+<Cards>
+  <Card title="Deployment" href="/docs/deployment" />
+  <Card title="Docker" href="/docs/deployment/docker" />
+  <Card title="Kubernetes" href="/docs/deployment/kubernetes" />
+</Cards>

package/site/content/docs/deployment/docker.mdx

@@ -0,0 +1,212 @@
+---
+title: Docker
+description: Deploy with plain docker compose — shared drivers, PgDog, readiness, graceful SIGTERM, and opt-in Caddy or Traefik when you need TLS without an orchestrator.
+icon: Package
+source: README.md
+---
+
+Plain `docker compose` is the simplest production shape: single or few app
+instances on one host (or a small set you manage yourself). Derive with
+`oke docker --prod`; opt into a proxy only when you need HTTPS at the edge.
+
+<Callout title="The one rule">
+  Treat every app container as replaceable. Put durable state in Postgres / Redis / S3, wait on `GET
+  /_/ready`, give SIGTERM time to release leases, and leave `images.proxy` unset until you need TLS
+  or `--scale app=N`.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Derive compose
+
+```bash
+oke docker --prod
+```
+
+Writes `Dockerfile`, `compose.yml`, per-role layers, and `compose.prod.yml`.
+Also emits **`compose.all.yml`** (same layers merged) — optional single file.
+Without a proxy, the app still publishes port `6530`.
+
+</Step>
+
+<Step>
+### Share backing services
+
+Pin docker/prod drivers to shared stores (create-oke templates already do):
+
+| Concern                       | Driver                       | Shared backend                                    |
+| ----------------------------- | ---------------------------- | ------------------------------------------------- |
+| SQL / durable journal / clock | `postgres`                   | Postgres (optionally via PgDog)                   |
+| Gate rate counters            | `redis` (`drivers.store.kv`) | Redis / Valkey / Dragonfly (`images["store.kv"]`) |
+| Files                         | `s3`                         | S3-compatible object store                        |
+| Signal                        | see known limits below       | —                                                 |
+
+</Step>
+
+<Step>
+### Bring the stack up
+
+Default — organized per-role files (`oke docker` prints the `-f` order):
+
+```bash
+cd docker
+docker compose -f compose.yml -f compose.store.sql.yml \
+  -f compose.pgdog.yml -f compose.prod.yml up -d
+```
+
+Pass every `-f` file listed. For TLS at the edge, see
+[Reverse proxy](#reverse-proxy), then include `compose.proxy.yml`.
+
+Single-file alternative: `docker compose -f compose.all.yml up -d`
+(add `-f compose.override.yml` if you use one).
+
+</Step>
+
+</Steps>
+
+## PgDog pooling
+
+Bun.SQL defaults to **10** connections per process — fine for one instance.
+Scale out and `N × pool` can exceed Postgres `max_connections`.
+
+When both `store.sql` and `pgdog` are pinned (docker/prod default in templates),
+`DATABASE_URL` points at PgDog on port `6432` — transaction pooling, wire-protocol
+transparent to Bun.SQL / Drizzle. No app code changes.
+
+**Why PgDog.** Transaction pooling fixes the connection math. Naive poolers can
+leak session state (`SET`, RLS vars, `LISTEN`/`NOTIFY`) across clients; PgDog
+re-applies those under transaction mode.
+
+Read-replica routing (`BEGIN READ ONLY` → replica) is documented readiness —
+not configured in the generated stack yet.
+
+## Redis-protocol images (Redis · Valkey · Dragonfly)
+
+`images["store.kv"]` defaults to Redis (most mature). Pin Valkey or Dragonfly
+the same way — driver id stays `redis`, same `REDIS_URL`. Image table + one-line
+licenses: [Store · KV](/docs/elements/store#kv).
+
+## Readiness and liveness
+
+| Endpoint       | Role                                                        | On plain compose                                           |
+| -------------- | ----------------------------------------------------------- | ---------------------------------------------------------- |
+| `GET /_/ready` | Kernel readiness (`booting` → `orphan_scan` → `ready`)      | `compose.prod.yml` HEALTHCHECK; load balancers should wait |
+| `GET /health`  | App liveness (create-oke ships one) — cheap “process alive” | External monitors only — not orphan-scan aware             |
+
+`/_/ready` returns `200 { ready: true }` only after boot and the durable orphan
+scan finish. While booting or scanning it returns
+`503 { ready: false, reason: "booting" | "orphan_scan" }`.
+
+**Consequence:** orphan scan delays “healthy” (and traffic) on purpose so a
+new replica is not hit mid-takeover.
+
+## Graceful shutdown
+
+On `SIGTERM` / `SIGINT`, `installGracefulShutdown` (wired by `oke dev`’s app
+runner; call it next to `createBunRuntime().serve` in custom entries):
+
+1. Stops accepting new connections
+2. Releases **Clock** cron leases and **Journal** run leases held by this instance
+3. Closes element runtimes and exits
+
+Signal message leases have no proactive release today — survivors reclaim after
+the visibility TTL (default 30s). `compose.prod.yml` sets `stop_grace_period: 30s`
+so the release path can finish (≥ typical Clock / Journal / Signal lease TTL).
+
+## Reverse proxy
+
+Omit `images.proxy` until you need HTTPS or horizontal scale without fighting a
+host port bind. Then pick one:
+
+| Choice                       | Best for                                  | How routing works                                                  |
+| ---------------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
+| **Caddy** (`caddy:2-alpine`) | Single instance, simplest automatic HTTPS | Generated `Caddyfile` → `reverse_proxy app:6530`                   |
+| **Traefik** (`traefik:v3.3`) | `docker compose up --scale app=N`         | Docker labels on `app`; replicas auto-discovered and load-balanced |
+
+```typescript title="oke.config.ts"
+images: {
+  // …
+  proxy: "caddy:2-alpine", // or "traefik:v3.3"
+},
+```
+
+```bash title="docker/.env.docker"
+OKE_PROXY_HOST=app.example.com
+OKE_PROXY_ACME_EMAIL=admin@example.com
+```
+
+Re-run `oke docker --prod`. Edge publishes `80`/`443`; `app` stays internal.
+Set `allowedHosts` to your public hostname ([Security](/docs/reference/security)).
+
+Traefik never mounts raw `docker.sock` — only a filtered
+`tecnativa/docker-socket-proxy` on the internal network. Full custom-domain,
+Let's Encrypt, and socket-proxy rationale → [Reverse proxy](/docs/deployment/reverse-proxy).
+
+## Known multi-instance limits
+
+| Surface                                  | Multi-instance today                                                                                       |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Clock (`postgres` / shared `file`)       | Shared leader election                                                                                     |
+| Journal (`postgres` / shared `file`)     | Shared durable runs + orphan resume                                                                        |
+| Gate rates (`drivers.store.kv: redis`)   | Shared counters                                                                                            |
+| Store SQL / KV redis / files `s3`        | Shared                                                                                                     |
+| Store files `fs`                         | **Per-instance filesystem** — boot warns; use `s3` when scaled                                             |
+| Signal `redis`                           | Emit relays to Redis; **consume / `live` / `drain` are process-local outbox** until Streams consume ships  |
+| Channel suppression / consent / receipts | **Default stores are process-local** — opt-out on replica A is invisible to B until a durable driver ships |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="compose up --scale app=N fails with port already allocated">
+
+You still have `6530:6530` on `app`. Confirm `images.proxy` is set and
+`compose.proxy.yml` is in the `-f` list so derivation omitted the host bind.
+
+</Accordion>
+<Accordion title="New replica gets traffic before orphan scan finishes">
+
+Confirm `compose.prod.yml` is in the `-f` list and the healthcheck hits
+`/_/ready`. Without it, compose treats “container started” as ready.
+
+</Accordion>
+<Accordion title="Rate limits look twice as high after scaling to 2">
+
+`drivers.store.kv` must be `redis` with `REDIS_URL` set. A missing URL **fails
+boot** (no silent memory fallback). Declaring `memory` for local is fine;
+docker/prod should stay on redis.
+
+</Accordion>
+<Accordion title="Files uploaded on instance A are missing on B">
+
+`drivers.store.files: "fs"` is single-host. Switch docker/prod to `s3`
+(create-oke templates already do).
+
+</Accordion>
+<Accordion title="Host header rejected (403)">
+
+Serve validates `Host`. Add your public hostname to `allowedHosts`
+([Security](/docs/reference/security)).
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Deployment](/docs/deployment) — choose compose, Swarm, or Kubernetes
+- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik in full
+- [Docker Swarm](/docs/deployment/docker-swarm) — `docker stack deploy` on the same files
+- [Kubernetes](/docs/deployment/kubernetes) — Deployment, probes, Ingress
+- [CLI](/docs/reference/cli) — `oke docker`, `oke docker --prod`
+- [Store](/docs/elements/store) — PgDog and facets
+- [Security](/docs/reference/security) — `allowedHosts`
+
+## Next
+
+<Cards>
+  <Card title="Deployment" href="/docs/deployment" />
+  <Card title="Reverse proxy" href="/docs/deployment/reverse-proxy" />
+  <Card title="Docker Swarm" href="/docs/deployment/docker-swarm" />
+</Cards>

package/site/content/docs/deployment/index.mdx

@@ -0,0 +1,83 @@
+---
+title: Deployment
+description: Choose plain docker compose, Docker Swarm, or Kubernetes — then follow that path's complete page for PgDog, probes, graceful shutdown, and TLS.
+icon: Server
+source: README.md
+---
+
+OKE apps are process-stateless when shared drivers back Store, Clock, Journal,
+and Gate. Pick an orchestrator (or none) first; each path page below is
+self-contained after you choose.
+
+<Callout title="The one rule">
+  Decide the deploy shape here, then open **one** path page and follow it end to end. Do not mix
+  recipes across pages — Docker proxy compose ≠ Kubernetes Ingress.
+</Callout>
+
+## Which path?
+
+| Path                                          | Best for                                     | Trade-off                                            |
+| --------------------------------------------- | -------------------------------------------- | ---------------------------------------------------- |
+| [Docker](/docs/deployment/docker) (compose)   | Simplest — single or few instances           | You run scale / restart / TLS yourself (or opt in)   |
+| [Docker Swarm](/docs/deployment/docker-swarm) | Built-in orchestration, lower learning curve | Smaller ecosystem than Kubernetes; mesh ≠ certs      |
+| [Kubernetes](/docs/deployment/kubernetes)     | Full orchestration, largest ecosystem        | Highest operational surface (Ingress, probes, RBAC…) |
+
+**Consequence:** start with plain compose until you need Swarm's service mesh /
+rolling updates or Kubernetes' cluster ecosystem. Same multi-instance contract
+on every path — shared Postgres/Redis/S3, not sticky pod identity.
+
+## Capabilities (every path)
+
+These already ship. Each path page explains them in full in that page's words:
+
+| Capability                        | What it guarantees                                                                     | Deep dive                                        |
+| --------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| **PgDog pooling**                 | docker/prod SQL goes through transaction pooler (`DATABASE_URL` → `:6432`) when pinned | Path pages · [Store](/docs/elements/store)       |
+| **Graceful SIGTERM**              | `installGracefulShutdown` releases Clock + Journal leases, then drains                 | Path pages                                       |
+| **Readiness vs liveness**         | `GET /_/ready` (kernel) vs app `GET /health`                                           | Path pages                                       |
+| **Horizontal proof**              | Two-process integration test against live Postgres + Redis                             | Changelog / CI (`OKE_TEST_POSTGRES_URL` + Redis) |
+| **Reverse proxy (compose/Swarm)** | Opt-in Caddy or Traefik (`images.proxy`)                                               | [Reverse proxy](/docs/deployment/reverse-proxy)  |
+| **Ingress (Kubernetes)**          | Cluster-native Ingress / Gateway API                                                   | [Kubernetes](/docs/deployment/kubernetes)        |
+
+Honesty notes (Signal consume / Channel suppression still process-local) live
+on each path page — not papered over here.
+
+## Pick a path
+
+<Cards>
+  <Card
+    title="Docker"
+    description="Plain compose — simplest single or few-instance deploy."
+    href="/docs/deployment/docker"
+  />
+  <Card
+    title="Docker Swarm"
+    description="stack deploy on the generated compose layers."
+    href="/docs/deployment/docker-swarm"
+  />
+  <Card
+    title="Kubernetes"
+    description="Deployment, probes, shared drivers, Ingress."
+    href="/docs/deployment/kubernetes"
+  />
+  <Card
+    title="Reverse proxy"
+    description="Caddy vs Traefik — TLS, domains, socket-proxy why."
+    href="/docs/deployment/reverse-proxy"
+  />
+</Cards>
+
+## Learn more
+
+- [Installation](/docs/get-started/installation) — scaffold and `oke dev --docker`
+- [CLI](/docs/reference/cli) — `oke docker --prod`, `oke start`
+- [Configuration](/docs/reference/configuration) — `images` and drivers
+- [Store](/docs/elements/store) — PgDog and facets
+
+## Next
+
+<Cards>
+  <Card title="Docker" href="/docs/deployment/docker" />
+  <Card title="Docker Swarm" href="/docs/deployment/docker-swarm" />
+  <Card title="Kubernetes" href="/docs/deployment/kubernetes" />
+</Cards>