create-stitchkit 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -12,6 +12,89 @@ step is overwritten by the next release.
 
 ## [Unreleased]
 
+## [0.6.0] — 2026-09-02
+
+The generated project stops being an empty frame with a to-do at the bottom of
+the page. It ships **one vertical feature**, from schema to transport to UI —
+and it was chosen so that every live primitive Stitchkit gained in 0.75–0.76 is
+there because the feature needs it, not to demonstrate anything.
+
+The demonstration is the second browser tab: post from it, and the first one
+updates without asking. Nothing on that page polls, and nothing refetches after
+a write.
+
+### Added
+
+- **A live board.** `board.list` is a watched read and `board.post` writes to it.
+  Together they use, and only where they are needed:
+  - `defineEvents` — one topic, `board.changed`, declared in `shared` because the
+    server announces it and the browser subscribes to it;
+  - `defineKeyspace` / `openKeyspace` over SQLite — notes are authoritative in
+    memory and durable behind it, so a read in a handler needs no `await` and a
+    restart loses nothing;
+  - `createWatchHub` / `createWatchClient` — every browser asking the same
+    question is **one read** on the server, re-run when the topic says the answer
+    may have changed;
+  - `createTrustFence` — installed on **both** lanes when `TRUSTED_HOSTS` is set,
+    because the Socket.IO lane never reaches a lifecycle hook.
+
+  The comments say which of these to reach for and, more usefully, when not to:
+  a keyspace is for a small bounded set the process wants synchronously, and the
+  moment a thing wants queries, relations or unbounded growth it is a database
+  row and Prisma is already there for it.
+
+- **Two environment variables**, both declared in the one place the project
+  declares variables: `BOARD_STORE_PATH` (defaulted, and the directory is created
+  by the application rather than by whoever deploys it) and `TRUSTED_HOSTS`
+  (unset means no fence, which is honest for a laptop and wrong for anything a
+  network can reach — a fence cannot invent the names it should answer to).
+
+### Changed
+
+- The template now targets `stitchkit` `^0.76.1`, up from `^0.71.0`.
+
+## [0.5.1] — 2026-09-01
+
+Three findings from someone setting up a new application on the starter from
+scratch, as a consumer who had never seen it. All of them live between "the
+scaffold is green" and "my first feature renders".
+
+### Fixed
+
+- **The generated `.env` no longer looks ready when it is not.** `local-env.ts`
+  rendered the database name and left `USER:PASSWORD` literal, in a file a
+  generator had just written — and a generated file reads as finished.
+  `assertUsableEnvironment` now names the file, the line and the variable, and
+  covers `ACCEPTANCE_DATABASE_URL` as well as `DATABASE_URL`. It runs before the
+  supervisor check, so an unusable environment is reported instead of a pm2
+  error, and on every run rather than only the one that created the file.
+  Rendering still succeeds: a generator that refuses to generate would break
+  `--no-install` scaffolding.
+
+- **`CREATEDB` is named where `DATABASE_URL` is named.** `prisma migrate dev`
+  creates a shadow database, so a least-privilege role — the sensible default
+  on a shared server — fails `db:migrate` with `P3014`. Neither the README nor
+  `_env.example` mentioned it.
+
+- **`check:authored` no longer refuses `as const`.** The gate exists to catch a
+  cast that can *launder* a type; a const-assertion only narrows, introduces no
+  name and cannot widen. Five of the first fifteen findings on a real adoption
+  were this false positive. Findings now also name the sanctioned alternative
+  instead of only the sin.
+
+- **`ADDING_A_FEATURE.md` no longer points at files the scaffold lacks.** Steps
+  4 and 5 referenced `lib/api/client.ts` and a "shared realtime source" that a
+  generated project does not contain, phrased as "the same pattern used by the
+  application's other contracts" — of which there were none. Both steps now
+  create what they need, with the transport file given in full.
+
+### Added
+
+- **`check:guides`**, part of `check`: every repository path a guide names must
+  exist, unless the guide declares it with `(created in this step)`. The guide
+  had five such references and three of them were legitimate; only a gate tells
+  those apart reliably.
+
 ## [0.5.0] — 2026-09-01
 
 ### ⚠️ Breaking changes

package/UPGRADING.md

@@ -60,6 +60,49 @@ the first scaffolder release with a migration channel of its own.
 
 ---
 
+## Released migration: 0.6.0
+
+The scaffolder gained a vertical feature. Adopting it in a project you already
+own is optional — nothing breaks if you skip it — but two things are **operator
+steps**, and skipping those with the feature adopted means the API will not
+start.
+
+### 1. The store directory has to be writable
+
+`BOARD_STORE_PATH` defaults to `.data/board.sqlite`, relative to the API role's
+working directory. The application creates the directory itself; what it cannot
+do is make a read-only volume writable.
+
+```bash
+# on the machine, as the user the API runs as
+test -w "$(dirname "${BOARD_STORE_PATH:-.data/board.sqlite}")" || echo "not writable"
+```
+
+If the role runs from a read-only image, point `BOARD_STORE_PATH` at a mounted
+volume instead.
+
+### 2. Decide about the trust fence, on purpose
+
+`TRUSTED_HOSTS` is unset by default, and unset means **no fence**. That is
+correct on a laptop and wrong on anything a network reaches — but a fence cannot
+guess which names your deployment answers to, so it refuses to invent them.
+
+```bash
+# every authority this deployment answers on, comma separated
+TRUSTED_HOSTS=app.internal,app.internal:5181
+```
+
+Set it and the fence is installed on both lanes: HTTP before routing, and the
+realtime handshake, which never reaches a lifecycle hook on either runtime. If
+your browser lives on another origin you already declared it as `CORS_ORIGIN`,
+and the fence reads that one rather than asking you a second time.
+
+### 3. Nothing else
+
+The rest of the feature is code you either copy or do not. The framework range
+moved to `^0.76.1`; if you upgrade the dependency without taking the feature,
+[the framework's own guide](../../docs/guide/upgrading.md) is the one to follow.
+
 ## Released migration: 0.5.0
 
 ### the approval policy names a tool that no longer exists

package/examples/repository/packages/backend/src/surface.snapshot.json

@@ -1,4 +1,36 @@
 [
+  {
+    "service": "board",
+    "action": "list",
+    "scope": "public",
+    "hasInput": false,
+    "hasOutput": true,
+    "inputShape": null,
+    "outputShape": "ce49fe198eb3412f",
+    "http": [
+      {
+        "method": "GET",
+        "path": "/api/board"
+      }
+    ],
+    "tools": {}
+  },
+  {
+    "service": "board",
+    "action": "post",
+    "scope": "public",
+    "hasInput": true,
+    "hasOutput": true,
+    "inputShape": "b1d8eb61c62cafed",
+    "outputShape": "ce49fe198eb3412f",
+    "http": [
+      {
+        "method": "POST",
+        "path": "/api/board"
+      }
+    ],
+    "tools": {}
+  },
   {
     "service": "repository",
     "action": "read",

package/examples/repository/packages/backend/src/surface.ts

@@ -1,16 +1,63 @@
 import { env } from '@app/config';
 import { repositoryRealtimeContract } from '@app/shared';
-import { bindRealtimeServer, createSocketIOServer } from 'stitchkit/server';
+import type { TrustFence } from 'stitchkit/server';
+import { bindRealtimeServer, createSocketIOServer, createTrustFence } from 'stitchkit/server';
+import { type BoardRuntime, openBoard } from './lib/board';
+import { bindLive } from './lib/live';
+import { createBoardService } from './transport/board-service';
 import { createRepositoryService } from './transport/repository-service';
 import { createSystemService } from './transport/system-service';
 
+/**
+ * The fence this deployment answers behind, or nothing.
+ *
+ * `trustedHosts` has no default and cannot have one: a fence compares the
+ * authority a request addressed against a list, and it cannot invent the list.
+ * Unset means no fence — honest for a checkout on a laptop, wrong for anything
+ * a network can reach.
+ */
+function createFence(): TrustFence | undefined {
+  if (!env.TRUSTED_HOSTS) return undefined;
+  const browserOrigin = env.CORS_ORIGIN ? [new URL(env.CORS_ORIGIN).host] : [];
+  return createTrustFence({
+    trustedHosts: env.TRUSTED_HOSTS.split(',').map((entry) => entry.trim()),
+    ...(browserOrigin.length > 0 && { trustedOrigins: browserOrigin }),
+    onRefused: (refusal) => {
+      console.warn(
+        `Refused a ${refusal.lane} request: ${refusal.reason} (host ${refusal.host ?? 'absent'})`,
+      );
+    },
+  });
+}
+
 export async function createSurface() {
+  const board: BoardRuntime = await openBoard();
+  const fence = createFence();
+
   const socket = await createSocketIOServer({
     cors: { origin: env.CORS_ORIGIN ?? [] },
+    // The socket's own admission point. `/socket.io/*` never reaches a lifecycle
+    // hook on either runtime, so a fence installed only in `hooks` would leave
+    // open the lane this app pushes its live data over.
+    ...(fence && { allowRequest: fence.allowRequest }),
   });
+
+  // Two bindings over one socket, deliberately. This example's own contract and
+  // the live one are separate declarations with separate event names, and
+  // merging them into a single registry here would mean editing the merge every
+  // time either side gains a topic.
   const realtime = bindRealtimeServer(repositoryRealtimeContract, socket);
+  const live = bindLive(board, socket);
+
   const repositoryService = createRepositoryService((snapshot) =>
     realtime.emit('repository:refreshed', snapshot),
   );
-  return { socket, services: [createSystemService(), repositoryService] };
+
+  return {
+    socket,
+    fence,
+    board,
+    hub: live.hub,
+    services: [createSystemService(), createBoardService(board), repositoryService],
+  };
 }

package/examples/repository/packages/frontend/src/app/[locale]/starter-page.tsx

@@ -4,6 +4,7 @@ import { BrandMark } from '@/components/brand-mark';
 import { RepositorySummary } from '@/components/repository-summary';
 import { LanguageSwitcher, ThemeToggle } from '@/components/system-controls';
 import { buttonVariants } from '@/components/ui';
+import { BoardPanel } from '@/features/board/board-panel';
 import type { AppLocale } from '@/i18n/locales';
 import { Link } from '@/i18n/navigation';
 import { absoluteSiteUrl } from '@/lib/seo/metadata';
@@ -15,6 +16,7 @@ interface StarterPageProps {
   applicationDescription: string;
   heroTitle: string;
   catalogueLabel: string;
+  realtimeOrigin?: string;
   locale: AppLocale;
 }
 
@@ -62,6 +64,7 @@ export async function StarterPage({
   applicationDescription,
   heroTitle,
   catalogueLabel,
+  realtimeOrigin,
   locale,
 }: StarterPageProps) {
   const homeSeo = getSeoPage('home', locale);
@@ -140,6 +143,10 @@ export async function StarterPage({
               </div>
             </div>
 
+            <div className='mt-6 w-full max-w-xl'>
+              <BoardPanel realtimeOrigin={realtimeOrigin} />
+            </div>
+
             <div className='mt-5 w-full'>
               <RepositorySummary />
             </div>

package/examples/repository/packages/shared/src/index.ts

@@ -1,5 +1,8 @@
+export * from './contracts/board';
+export * from './contracts/live';
 export * from './contracts/repository';
 export * from './contracts/system';
 export * from './realtime/repository';
+export * from './schemas/board';
 export * from './schemas/repository';
 export * from './schemas/system';

package/examples/repository/project.json

@@ -105,6 +105,11 @@
         "shape": "string",
         "required": false
       },
+      {
+        "name": "BOARD_STORE_PATH",
+        "shape": "string",
+        "required": false
+      },
       {
         "name": "CORS_ORIGIN",
         "shape": "url",
@@ -179,6 +184,11 @@
         "shape": "url",
         "required": false
       },
+      {
+        "name": "TRUSTED_HOSTS",
+        "shape": "string",
+        "required": false
+      },
       {
         "name": "WEB_PORT",
         "shape": "integer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",

package/template/README.md

@@ -29,6 +29,17 @@ Point `DATABASE_URL` in `.env` at an existing PostgreSQL database, then run:
 bun run dev
 ```
 
+`.env` is generated on first run with the database name filled in and the
+credentials left as `USER:PASSWORD`. Replace them: `dev` refuses to start while
+the placeholder is there, naming the file and the line, rather than letting the
+driver fail on the first request.
+
+**The role that runs `bun run db:migrate` needs `CREATEDB`.** `prisma migrate
+dev` creates a throwaway shadow database to diff against, so a least-privilege
+role — the sensible default for a shared server — fails with `P3014: could not
+create the shadow database`. Grant `CREATEDB` to the development role, or point
+Prisma at a shadow database you create yourself.
+
 The command validates the environment, generates the Prisma client, applies any
 database migrations you add and launches:
 

package/template/_env.example

@@ -1,4 +1,7 @@
 NODE_ENV=development
+# Replace USER:PASSWORD before the first `bun run dev` — it refuses to start
+# while they are here. The role also needs CREATEDB if it will run
+# `db:migrate`: `prisma migrate dev` creates a shadow database to diff against.
 DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter
 # The throwaway database `bun run acceptance:local` creates and writes to. The
 # runtime gates WRITE, so they get one of their own: the harness refuses to

package/template/bun.lock

@@ -139,7 +139,7 @@
     },
   },
   "catalog": {
-    "stitchkit": "^0.71.0",
+    "stitchkit": "^0.76.1",
   },
   "packages": {
     "@ai-sdk/gateway": ["@ai-sdk/gateway@4.0.63", "", { "dependencies": { "@ai-sdk/provider": "4.0.7", "@ai-sdk/provider-utils": "5.0.29", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-D7BogSRg61QfTdr7AEcYn9h0I/e4QHvFXwIV1RW+DZZGJu1wSiX2cH06szZSYyKi7Eat50V4s4J8vggZUEs7eg=="],
@@ -1118,7 +1118,7 @@
 
     "std-env": ["std-env@3.10.0", "", {}, "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg=="],
 
-    "stitchkit": ["stitchkit@0.71.0", "", { "dependencies": { "ky": "^2.0.2" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2", "@modelcontextprotocol/server": "^2.0.0", "@openrouter/ai-sdk-provider": "^3.0.0", "@opentelemetry/api": "^1.9.0", "@socket.io/bun-engine": "^0.1.1", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.3.14", "ai": "^7.0.0", "grammy": "^1.45.1", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5", "zod": "^4.4.3" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@openrouter/ai-sdk-provider", "@opentelemetry/api", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "grammy", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"] }, "sha512-HXqTD1Sv534rWt+KKJV1Gp535NTRzbGFxNMuRAvo9TzuU0kZxBDF18gu+WexF9O8Z4jkhlfvTjXeRy/oQrnHwA=="],
+    "stitchkit": ["stitchkit@0.76.1", "", { "dependencies": { "ky": "^2.0.2" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2", "@modelcontextprotocol/server": "^2.0.0", "@openrouter/ai-sdk-provider": "^3.0.0", "@opentelemetry/api": "^1.9.0", "@socket.io/bun-engine": "^0.1.1", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.3.14", "ai": "^7.0.0", "grammy": "^1.45.1", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5", "zod": "^4.4.3" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@openrouter/ai-sdk-provider", "@opentelemetry/api", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "grammy", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"] }, "sha512-+Qmm4CdyWUJJP0MLEQX3M2Ltf0WX5Wi5rEHdZGfWmyIn4SW//x+llQgm516sCyMyJthr9HOaYzxIIP27mBnCmQ=="],
 
     "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
 
@@ -1190,9 +1190,6 @@
 
     "zwitch": ["zwitch@2.0.4", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
 
-
-
-
     "@prisma/adapter-pg/@types/pg": ["@types/pg@8.21.0", "", { "dependencies": { "@types/node": "*", "pg-protocol": "*", "pg-types": "^2.2.0" } }, "sha512-AYdtudzabjLZgVgRZmAnU8bAnVUXzuJX2IYHeSIiIHm68olD+LgQYCGWdtcNYnP0uq9c4S4NibVG3Ni7VbKW7Q=="],
 
     "@prisma/adapter-pg/pg": ["pg@8.22.0", "", { "dependencies": { "pg-connection-string": "^2.14.0", "pg-pool": "^3.14.0", "pg-protocol": "^1.15.0", "pg-types": "2.2.0", "pgpass": "1.0.5" }, "optionalDependencies": { "pg-cloudflare": "^1.4.0" }, "peerDependencies": { "pg-native": ">=3.0.1" }, "optionalPeers": ["pg-native"] }, "sha512-8wih1vVIBMxoUM2oB4soJsD9tDnDpLv4OXBJ+EJzFsvycD+lfyIreC2gGHq78f8jbLLt+bvlPTFdFZfJkOuzAA=="],

package/template/docs/ADDING_A_FEATURE.md

@@ -7,7 +7,7 @@ same files beside it.
 
 ## 1. Define the wire data
 
-Create `packages/shared/src/schemas/status.ts`:
+Create `packages/shared/src/schemas/status.ts` (created in this step):
 
 ```ts
 import { z } from 'zod'
@@ -21,7 +21,7 @@ Export it from the shared package. Do not introduce a second handwritten DTO.
 
 ## 2. Define the HTTP/tool contract separately
 
-Create `packages/shared/src/contracts/status.ts` and import the named schemas:
+Create `packages/shared/src/contracts/status.ts` (created in this step) and import the named schemas:
 
 ```ts
 import { defineContract } from 'stitchkit'
@@ -44,7 +44,7 @@ The contract owns transport identity. Do not add a raw route or duplicate path.
 
 ## 3. Implement and register the service
 
-Create `packages/backend/src/transport/status-service.ts` with `implement()`.
+Create `packages/backend/src/transport/status-service.ts` (created in this step) with `implement()`.
 Keep persistence and business rules in a domain/service module; the contract
 handler calls that module once. Add the returned service to the `services` array
 in `packages/backend/src/surface.ts`. That one registration drives HTTP,
@@ -52,20 +52,44 @@ OpenAPI, MCP, agent tools and CLI discovery.
 
 ## 4. Add typed browser access
 
-Export `statusContract` from `packages/shared/src/index.ts`. In
-`packages/frontend/src/lib/api/client.ts`, create `statusApi` with the same
-`createClient(statusContract, http)` pattern used by the application's other
-contracts. Create the query key and react-query-kit query/mutation hooks in
-`packages/frontend/src/lib/api/status.ts`. On mutation success, update or
-invalidate that canonical key.
+Export `statusContract` from `packages/shared/src/index.ts`.
+
+The scaffold ships no browser transport layer, and that is the first thing this
+step builds. It also makes one decision for you, because the starter already
+made it: **no address is compiled into the artifact.** `packages/frontend/src/env.ts`
+declares no `client` block on purpose — a `NEXT_PUBLIC_` variable is substituted
+at build time, which freezes a value of the place into the bundle. So the client
+is a factory over an origin the server reads per request, never a module-level
+constant.
+
+Create `packages/frontend/src/lib/api/client.ts` (created in this step):
+
+```ts
+import { createClient, createHttpClient } from 'stitchkit'
+import { statusContract } from '@app/shared'
+
+/** One origin per request, supplied by the server — never read from the bundle. */
+export function createStatusApi(origin: string) {
+  return createClient(statusContract, createHttpClient({ prefixUrl: origin }))
+}
+```
+
+Create `packages/frontend/src/lib/api/status.ts` (created in this step) for the
+query key and the react-query-kit hooks, and keep the key canonical — one key
+per resource, updated or invalidated on mutation success.
+
+A server component reads `env.PUBLIC_API_ORIGIN` and hands it down as a prop;
+the client component calls `createStatusApi(origin)`. That is the whole reason
+`PUBLIC_API_ORIGIN` is a server variable rather than a public one.
 
 Render the hook from a feature component. Pages compose features; they do not
 call `fetch`, construct `/api/status` or decode error bodies themselves.
 
 ## 5. Add realtime only when another client must observe the change
 
-Declare the event in the shared realtime source and use a named Zod schema for
-its tuple. The server emits after the domain change succeeds; the frontend cache
+Create `packages/shared/src/realtime.ts` (created in this step) and declare the
+event there with a named Zod schema for its tuple — the scaffold ships no
+realtime module, so this step introduces it rather than assuming it. The server emits after the domain change succeeds; the frontend cache
 bridge reacts by updating or invalidating the status query. Keep handshake auth,
 authorization and room membership in the application. Socket.IO delivery,
 reconnection, retained subscriptions and validation belong to Stitchkit.

package/template/package.json

@@ -7,12 +7,13 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.71.0"
+    "stitchkit": "^0.76.1"
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",
-    "check": "bun run db:generate && bun run check:authored && bun x tsc -p tsconfig.json --noEmit && bun run --filter '*' check",
+    "check": "bun run db:generate && bun run check:authored && bun run check:guides && bun x tsc -p tsconfig.json --noEmit && bun run --filter '*' check",
     "check:authored": "bun scripts/check-authored.ts",
+    "check:guides": "bun scripts/guide-paths.ts",
     "test": "bun test scripts && bun run --filter '*' test",
     "build": "bun scripts/build-inputs.ts && bun run db:generate && bun --filter @app/backend build && bun --filter @app/frontend build && bun scripts/build-stamp.ts",
     "start:api": "bun --filter @app/backend start",

package/template/packages/backend/src/index.ts

@@ -3,6 +3,7 @@ import { apiRole, appDeclaration } from '@app/config/declaration';
 import { wrapInRequestContext } from 'stitchkit/observability';
 import {
   bindProcessSignals,
+  composeLifecycleHooks,
   createServer,
   generateOpenApiDocument,
   openApiRoute,
@@ -14,7 +15,7 @@ import { createSurface } from './surface';
 import { onError } from './transport/errors';
 
 async function main(): Promise<void> {
-  const { services, socket } = await createSurface();
+  const { services, socket, fence, board, hub } = await createSurface();
   const mcp = createMcpHandler({
     serverInfo: {
       name: appDeclaration.identity.slug,
@@ -36,7 +37,10 @@ async function main(): Promise<void> {
     port: env.API_PORT,
     hostname: env.BIND_HOST,
     cors: env.CORS_ORIGIN ? { origin: env.CORS_ORIGIN } : undefined,
-    hooks: { onError },
+    // The fence FIRST: hook composition stops at the first hook that answers,
+    // so a fence behind anything that can respond is a fence that sometimes
+    // does not run.
+    hooks: fence ? composeLifecycleHooks(fence.hooks, { onError }) : { onError },
     logging: { format: env.LOG_FORMAT },
     socket,
     rawRoutes: [
@@ -66,6 +70,10 @@ async function main(): Promise<void> {
       // SIGKILL — the one ending that runs no cleanup at all.
       const cleanup = await closeWithinBudget([
         { name: 'MCP', close: () => mcp.close() },
+        // Stops re-reading for browsers that are already gone, then lets the
+        // board finish the writes it accepted and say how many it could not.
+        { name: 'watch hub', close: async () => hub.close() },
+        { name: 'board', close: () => board.close() },
         { name: 'database', close: () => prisma.$disconnect() },
       ]);
       // Say how the drain ended. Without this an operator sees a process that

package/template/packages/backend/src/lib/board.ts

@@ -0,0 +1,99 @@
+import { Database } from 'bun:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { env } from '@app/config';
+import { type Board, boardEvents, type Note, NoteSchema, type PostNote } from '@app/shared';
+import {
+  defineKeyspace,
+  type OpenedKeyspace,
+  openKeyspace,
+  sqliteKeyspaceBackend,
+} from 'stitchkit/application';
+import type { EventPayloads } from 'stitchkit/live';
+import { createEventBus, type EventBus } from 'stitchkit/server';
+
+/**
+ * The board's notes: authoritative in memory, durable behind it.
+ *
+ * A keyspace and not a Prisma model, deliberately, and the boundary is worth
+ * knowing rather than guessing. A keyspace is for a **small, bounded set the
+ * whole process wants synchronously** — read it in a handler without awaiting,
+ * write it and know the write survived. The moment a thing wants queries,
+ * relations, pagination or unbounded growth, it is a database row and this is
+ * the wrong home for it.
+ */
+const notes = defineKeyspace('notes', {
+  schema: NoteSchema,
+  key: (note: Note) => note.id,
+});
+
+/** The board, and the lifecycle its owner drives. */
+export interface BoardRuntime {
+  /** Every announcement this role makes. Subscribed by the watch hub. */
+  readonly events: EventBus<EventPayloads<typeof boardEvents>>;
+  /** Synchronous, from memory. This is what makes a watched read cheap. */
+  read(): Board;
+  post(input: PostNote): Promise<Board>;
+  close(): Promise<void>;
+}
+
+const MOST_RECENT = 50;
+
+export async function openBoard(): Promise<BoardRuntime> {
+  // Closed by the declaration: an undeclared topic is refused rather than
+  // delivered to nobody, and a topic can only be announced by the verb its
+  // declaration chose.
+  const events = createEventBus<EventPayloads<typeof boardEvents>>({
+    topics: boardEvents.topics,
+    onListenerError: (error, event) => {
+      console.error(`Listener for ${event} failed`, error);
+    },
+  });
+
+  // The directory too, not only the file. A starter that requires an operator to
+  // create a folder before it will boot is a starter that fails on the first run
+  // with an error about SQLite rather than about what is missing.
+  mkdirSync(dirname(env.BOARD_STORE_PATH), { recursive: true });
+  const database = new Database(env.BOARD_STORE_PATH, { create: true });
+
+  // Opened directly rather than declared to a kernel, because this role owns
+  // its own lifecycle: it binds its signals and closes what it holds in the
+  // order `cleanup.ts` lists. An application built on `createApplication` would
+  // declare `keyspaceResource(notes, …)` instead and let the graph order it.
+  const opened: OpenedKeyspace<Note> = await openKeyspace(notes, {
+    backend: sqliteKeyspaceBackend(notes, { database }),
+    // After durability and after memory — never before either. A subscriber
+    // woken by this reads immediately, and an announcement that arrived first
+    // would be a wake-up to the previous value.
+    onChanged: (change) => events.emit('board.changed', { noteId: change.key }),
+  });
+
+  function read(): Board {
+    const all = [...opened.keyspace.list()].sort((left, right) =>
+      right.postedAt.localeCompare(left.postedAt),
+    );
+    return { notes: all.slice(0, MOST_RECENT), total: all.length };
+  }
+
+  return {
+    events,
+    read,
+    async post(input) {
+      await opened.keyspace.put({
+        id: crypto.randomUUID(),
+        body: input.body,
+        postedAt: new Date().toISOString(),
+      });
+      // The write resolved, so it is durable and in memory; this read cannot
+      // miss it. The watchers hear about it through the announcement above.
+      return read();
+    },
+    async close() {
+      opened.stopAdmission();
+      await opened.drain();
+      await opened.close();
+      database.close();
+      events.clear();
+    },
+  };
+}