esoul-sdk 0.4.0 → 0.7.0

package/llms-full.txt

@@ -4,65 +4,187 @@ Generated from README.md and docs/. Read it whole. Every rule carries the failur
 
 # esoul-sdk
 
-Build **ExternalSoul apps**: native apps for an event-sourced workspace where people and AI
-agents share one canvas. An app you write with this SDK is indistinguishable from the platform's
-own once it ships — the same events, the same timeline, the same durability, the same tools that
-chat, voice, agents and MCP call.
+Build a **full product** on ExternalSoul — not a widget. An app you write with this SDK gets its
+own database tables, its own server, its own background jobs, its own realtime, its own words for
+the people who use it, and the same agent tools that chat, voice and MCP already call. Once it
+ships it is indistinguishable from the platform's own apps.
 
 ```bash
 npm install --save-dev esoul-sdk
 ```
 
 Inside ExternalSoul the package name resolves to the platform's real implementations. Outside it
-(your editor, your tests) the package gives you the types, the manifest validator, and the test
-helpers; the server functions throw "host only" if called, because they run in the platform.
+(your editor, your tests) it gives you the types, the manifest validator, the rule compiler and
+the test helpers; the server functions throw "host only" if called, because they run in the
+platform.
+
+---
+
+## What you can build with it
+
+Take a help desk. Strangers may read the published articles. Someone signed in may raise a ticket
+and see their own. The people on duty see every ticket. The owner decides who is on duty. A
+confirmation must go out exactly once, even if the mail service is down for a minute. That is
+every hard thing at once, and it is the shape most real products have.
+
+An app like that, written with this SDK, contains **no access checks at all**. They are
+declarations, and the platform enforces them at the seam.
+
+| You want | You declare | You never write |
+|---|---|---|
+| Your own tables | `db` in the manifest | migrations, a Prisma schema, an ORM |
+| Per-person data | `owner: "creator"` + `rules` | a `WHERE userId = …` anywhere |
+| A public page | `"access": "public"` on an op | an auth check in the handler |
+| A sign-in wall | `"requires": "account"` | the difference between "sign in" and "never" |
+| Words for your people | `roles` | a permissions table |
+| One person's live updates | `"audience": "viewer"` on a topic | a filter on arrival |
+| Durable follow-up work | a `task` | a queue, retries, idempotency plumbing |
+| Another app's help | `uses` + a contract | an integration |
+
+---
+
+## The seven capabilities
+
+**1. Viewer — every seam knows who is calling.** Ops, routes, tasks, tools and the UI all receive
+a `viewer`: the owner, a member, a signed-in visitor, an anonymous one, an agent acting for
+someone, or your app's own server code. The platform resolves it; an app cannot supply, widen or
+forge one. `useViewer()` in the UI, `ctx.viewer` on the server. When you need the person's name
+or email — to address them, or to fill a form in — `viewerProfile(ctx.viewer)` reads the esoul
+account of the CALLER and nobody else, so people use your app with the account they already have.
+
+**2. Roles — your app's own vocabulary.** Declare `roles: { vocabulary: ["requester", "agent",
+"supervisor"] }` and a mapping from the platform's kinds. The workspace owner can then assign a role
+per app, per person, so an organisation sees the pages their job needs. A role is a WORD, never a
+permission: it decides what your rules mean, not what the platform allows.
+
+**3. Access levels — nothing opens by default.** Every op, route and task is `write` unless you
+say otherwise. `read` admits a read-only collaborator; `public` admits someone on a share link
+who has no workspace access at all; `public` + `requires: "account"` answers `login-required`
+instead of `forbidden`, which is the difference between showing a sign-in wall and showing an
+error. Every public door is listed on the install card before anyone installs your app.
+
+**4. The database — tables you declare, scoped by the platform.** A `db` block becomes real
+tables, generated typings, and rules compiled once and enforced everywhere. `pluginDb(ctx)` hands
+you a typed client whose every query is already scoped to this instance and filtered for this
+caller: one person's `findMany` returns their own rows, someone on duty gets the whole queue, and
+neither had to ask.
+Fields can be `sealed` (encrypted at rest, readable only by their owner). Migrations are
+additive-only and applied on install; a change that would drop or retype a column is refused with
+the column named.
+
+**5. Realtime with an audience.** A topic declares who hears it: everyone on the app, only the
+person it concerns, or only a role. The platform mints a token per channel, so one person is never
+handed another's messages — not filtered out on arrival, never issued. Aiming a message is a
+separate permission from hearing one.
+
+**6. Background tasks.** Durable work on the platform's own scheduler: retried, replay-safe,
+steps on the timeline. This is where the slow and failure-prone things go — sending the
+confirmation, calling somebody else's API — so the request that changed the record stays fast and
+honest.
+
+**7. Bindings.** Declare a SLOT and a CONTRACT (`uses: { rooms: { contract: "rooms/v1" } }`) and
+the owner picks which app fills it. The platform checks at bind time that the provider really has
+every tool, event and table the contract names. Your app reaches it through `ctx.apps.rooms` —
+the contract's tools only, with the caller's identity travelling along.
+
+---
 
 ## Where to start
 
 - **Build it in the Forge, not on your laptop.** Open a Forge board in your workspace and ask it
-  to open a workbench for your app. You get a cloud machine with the platform on it, a live
-  preview in your frame, your app's tools callable before it is installed, checks, and a submit
-  button. Read [docs/01-getting-started.md](docs/01-getting-started.md).
+  to open a workbench for your app: a cloud machine with the platform on it, a live preview in
+  your frame, your app's tools callable before it is installed, and **VIEW AS** — the switcher
+  that shows you your app as each kind of person who will use it, including the stranger. Read
+  [docs/01-getting-started.md](docs/01-getting-started.md).
 - **The contract, one page per part:**
   1. [Getting started](docs/01-getting-started.md) — the loop, the package layout
   2. [The manifest](docs/02-manifest.md) — `plugin.json`, every field
   3. [Events and state](docs/03-events-and-state.md) — the heart: dataCreator, processor, replay
   4. [Tools](docs/04-tools.md) — what agents call, on every surface
   5. [The UI](docs/05-ui.md) — React, hooks, theme, responsive rules
-  6. [The server half](docs/06-server.md) — ops, webhooks, reading state, calling other apps
+  6. [The server half](docs/06-server.md) — ops, routes, webhooks, calling other apps
   7. [Background tasks](docs/07-background-tasks.md) — durable work, polling, the replay model
   8. [Connections and OAuth](docs/08-connections.md) — tokens the platform holds for you
   9. [Files](docs/09-files.md) — workspace files, Drive, your own provider
-  10. [Testing](docs/10-testing.md) — the fold contract as tests
+  10. [Testing](docs/10-testing.md) — the fold contract, and your rules, as tests
   11. [Shipping](docs/11-shipping.md) — submit, review, release, install; the import wall
   12. [Rules and failures](docs/12-rules.md) — every rule with the failure that earned it
+  13. [People and access](docs/13-people-and-access.md) — viewer, roles, levels, the sign-in wall
+  14. [Your own tables](docs/14-database.md) — `db`, rules, scopes, sealed fields, migrations
+  15. [Realtime](docs/15-realtime.md) — topics, audiences, who may address whom
+  16. [Bindings](docs/16-bindings.md) — slots, contracts, reaching another app
 - **For a coding model:** `llms.txt` (short) and `llms-full.txt` (the whole contract in one file).
 
 ## The one rule that explains the others
 
-**Events are the truth.** Your app's state is the fold of its events, re-run on every replay,
-scrub and sync. So a reducer must be pure and idempotent, ids and timestamps are minted in the
-`dataCreator` (never in a reducer), whole-replace events carry a collapse key, and the agent-facing
-state description never claims something it could not read. Everything in the docs follows from
-that.
+**Events are the truth.** Your app's fold is its events re-run on every replay, scrub and sync. So
+a reducer is pure and idempotent, ids and timestamps are minted in the `dataCreator` (never in a
+reducer), whole-replace events carry a collapse key, and a state description never claims
+something it could not read.
+
+The second rule, for everything that is not in the fold: **the platform decides who sees what.**
+Your rules are declarations the platform enforces at the seam. An app that checks access in its
+own handler has two answers to one question, and one of them will be wrong.
 
 ## What is in the package
 
 | Entry | What it gives you |
 |---|---|
-| `esoul-sdk` | `ApplicationSchema`, `EventDefinition`, `EventTypes`, `ApplicationIdentifier`, `incompleteStateNotice`, `deterministicReducerId`, `stableStringify`, `timingSafeEqual`, `nanoid`, `callPluginOp`, the manifest schema |
-| `esoul-sdk/react` | `usePluginEventDispatch`, `useAppCanEdit`, `usePluginCurrentChatId`, `useWorkspaceTools`, `usePluginRealtime`, file hooks |
-| `esoul-sdk/server` | `PluginServerModule`, `readAppState`, `callWorkspaceTool`, `emitPluginAppEvent`, `getPluginConnectionCredentials`, file provider types |
-| `esoul-sdk/testing` | a mock OAuth server for connection tests |
+| `esoul-sdk` | `ApplicationSchema`, `EventDefinition`, `EventTypes`, `ApplicationIdentifier`, `definePluginChannel`, `defineBindingEvent`, `checkBinding`, `subscriptionsFor`, `resolveAppRole`, `incompleteStateNotice`, `deterministicReducerId`, `timingSafeEqual`, `nanoid`, `callPluginOp`, `kickPluginTask`, `pluginRouteUrl`, the manifest schema |
+| `esoul-sdk/react` | `useViewer`, `useSignInWall`, `useAppCanEdit`, `usePluginEventDispatch`, `usePluginRealtime`, `useWorkspaceTools`, file hooks |
+| `esoul-sdk/server` | `pluginDb`, `viewerProfile`, `PluginServerModule` (ops, routes, webhooks), `sseStream`, `readAppState`, `callWorkspaceTool`, `emitPluginAppEvent`, `getPluginConnectionCredentials`, file provider types |
+| `esoul-sdk/testing` | `memoryDb`, `fakeViewer`, `runOp`, `fakeApps`, `capture`, `startMockOAuth` — your rules run against the client the platform compiles from your own manifest |
 | `esoul-app validate <dir>` | validates a package folder against the manifest schema |
 
+## Testing your app
+
+The helpers run your REAL server code against an in-memory database built from your own
+`plugin.json`, with the same compiled rules the production client uses. What passes here is what
+the real database will do.
+
+```ts
+import { fakeViewer, memoryDb, runOp } from "esoul-sdk/testing";
+import manifest from "./plugin.json";
+import { pluginServer } from "./server";
+
+const ada = fakeViewer("visitor", { userId: "u_ada", role: "requester" });
+const lin = fakeViewer("visitor", { userId: "u_lin", role: "requester" });
+
+it("does not let the OTHER one see it", async () => {
+  const db = memoryDb(manifest);
+  await runOp(pluginServer, "raise-ticket", { viewer: ada, args: TICKET, db: db.as(ada) });
+  const { result } = await runOp(pluginServer, "my-tickets", { viewer: lin, args: {}, db: db.as(lin) });
+  expect(result).toEqual([]);
+});
+```
+
+`runOp` also records what your op NOTIFIED and who it addressed, and `notifyFails` makes
+notifying throw — the question worth asking of any op that tells somebody after it has written
+something: does the write survive?
+
 ## Versions
 
-- **0.3.0** — renamed from `@externalsoul/plugin-sdk` (still resolved as an alias inside the
-  platform). `readAppState`, `callWorkspaceTool`, `nanoid` on the index. The import wall: an app
-  reaches the platform only through this package. Docs rewritten for the Forge workbench loop.
+- **0.7.0** — what a catalogue-sized app needs. **Index kinds**: a plain group is a btree,
+  `{ fields: ["tags"], kind: "contains" }` answers `{ tags: { has: … } }` on a list, and
+  `{ fields: ["title"], kind: "text" }` answers `{ title: { contains: … } }` — so a department
+  and a search term are questions for the database, with `cursor` paging. `contains` ignores
+  case in both clients (a search box that misses "earl grey" is broken quietly). Asking a list a
+  scalar's question (or the reverse) is refused with the right one named. **`ctx.emit`** — an op
+  records on its OWN timeline, so a fact reaches the fold whether a person or an agent caused it.
+  A list field defaults to `[]` (it used to refuse every create), a rule-less model defaults to
+  the role your manifest calls the owner, and `viewerProfile` is a real export rather than a
+  declaration. Documented the client surface that was already there: `aggregate`, `groupBy`,
+  `$transaction`, the `*Many` writes.
+- **0.6.0** — the full-stack release. Your own tables (`db`, `pluginDb`, rules, scopes, sealed
+  fields, additive migrations applied on install). `viewer` on every seam, app `roles`, per-surface
+  access levels with the sign-in wall. Realtime audiences: a topic says who hears it and the mint
+  issues a token per channel. Bindings: `uses`/`provides`, contracts, `ctx.apps.<slot>`. A tool now
+  acts for the person who invoked it rather than for the platform. `viewerProfile` — the caller's
+  own esoul account, server-side only. Testing: `memoryDb`, `fakeViewer`, `runOp`.
+- 0.5.0 — server routes (`pluginServer.routes`), `sseStream`, plugin realtime.
+- 0.3.0 — renamed from `@externalsoul/plugin-sdk`. `readAppState`, `callWorkspaceTool`, `nanoid`
+  on the index. The import wall: an app reaches the platform only through this package.
 - 0.2.0 — file sources and providers.
-- 0.1.0 — the contract: manifest, schema, events, tools, tasks, webhooks, ops, connections.
 
 
 
@@ -401,8 +523,11 @@ could not do: an update to an id that is not on the wall says "No note X — not
 
 A tool that must read the real state (not the caller's cache) calls a **plugin op** through
 `callPluginOp(pluginId, op, nodeId, args)` — never `fetch("/api/v1/…")` itself (token-gated, it
-refuses the tool). Ops are yours to write (docs/06). In the workbench there is no database behind
-the preview, so such a tool is refused with a message naming `read_app_state`; that is expected.
+refuses the tool). Ops are yours to write (docs/06). In the workbench an op runs over the
+preview's own in-memory tables, so a tool that calls one works there too. A failed call throws a
+`PluginCallError` carrying the platform's `code` (`forbidden`, `login-required`, …): pass it to
+`useSignInWall().raise(err)` in the UI and a `login-required` becomes the sign-in wall instead of
+an error. Relay any other error's message; never swallow it.
 
 ## Calling other apps
 
@@ -608,6 +733,35 @@ Gated exactly like the UI: the manifest must declare `"my_computer:claude_task"`
 instance with `targetNodeId` instead of `appType`. This is how an app runs a `my_computer`
 (commands, Claude Code sessions, results), fills a spreadsheet from a job, or books a calendar.
 
+## `ctx.emit` — record on your OWN timeline
+
+Anything a person can cause through your UI, an agent can cause through a tool,
+and the server is the only place that sees both. So when a change belongs on the
+fold, the OP records it, not the screen:
+
+```ts
+async function addProduct(ctx: PluginOpContext) {
+  const p = await (await pluginDb<ShopDb>(ctx)).product.create({ data: … });
+  // Derive the change id. A retry — and the UI's own optimistic dispatch of the
+  // same fact — is then a no-op rather than a second bump.
+  await ctx.emit("plugin_shop_catalogue_changed", { changeId: `product:${p.id}`, tags: p.tags });
+  return { id: p.id };
+}
+```
+
+It is your own event (`eventName` from your schema), it goes through the
+platform's spine — your `dataCreator` mints, your reducer folds, triggers fire —
+and it lands on THIS instance.
+
+**The failure this exists to prevent.** An app offered its departments from the
+fold and recorded them only in the owner's add-product FORM. Stocked by its
+agent instead, it therefore had a full catalogue and no departments at all,
+live on a customer's site. If a fact belongs on the timeline, the op is where
+it is written — a screen is one of its callers, never the only one.
+
+Treat it as a courtesy around a completed write, like `notify`: catch a failure
+and report it, rather than letting it undo a product that exists.
+
 ## `emitPluginAppEvent`
 
 Emit ANOTHER app's own events (its `dataCreator` shape) into the same workspace, actor-stamped as
@@ -625,6 +779,55 @@ Only `esoul-sdk` / `esoul-sdk/server`, relative files, `server-only`, and npm pa
 platform already depends on. No `prisma`, no `node:*`, no `next`, no internals — the import wall
 (docs/11) refuses them, and a reviewer relies on that.
 
+## Routes — the backend your app brings with it
+
+An op answers one JSON question. A **route** owns the whole Response: it can stream, return
+bytes, set headers, and run for as long as one request lasts (minutes on Fluid compute). It is
+how a user app gets what a native app gets from its API routes — mounted on install at
+`GET|POST /api/plugins/<id>/route/<name>?nodeId=<instance>`.
+
+```json
+// plugin.json
+"routes": ["ticks"]
+```
+
+```ts
+// server.ts
+import { readAppState, sseStream, type PluginServerModule } from "esoul-sdk/server";
+
+export const pluginServer: PluginServerModule = {
+  routes: {
+    // A clock streamed straight from the server: one Node process, no scheduler hops.
+    ticks: async (ctx) =>
+      sseStream(async (send, signal) => {
+        while (!signal.aborted) {
+          const app = await readAppState(ctx.nodeId);           // the fold, ~0.3 s here
+          const cur = (app?.state as { current?: { runId: string; kickedAt: number } }).current;
+          if (cur) send("tick", { runId: cur.runId, elapsedMs: Date.now() - cur.kickedAt });
+          await new Promise((r) => setTimeout(r, 1000));
+        }
+      }, { signal: ctx.request.signal }),
+  },
+};
+```
+
+```tsx
+// ui — the session rides along; a public-share viewer can watch, not write.
+import { pluginRouteUrl } from "esoul-sdk";
+const es = new EventSource(pluginRouteUrl("stopwatch", "ticks", state.nodeId));
+es.addEventListener("tick", (e) => setTick(JSON.parse((e as MessageEvent).data)));
+```
+
+The platform resolves the instance, the enabled flag and the caller's access before your
+handler runs — READ to reach the route at all, and `ctx.canWrite` says whether the caller may
+mutate (check that one boolean before you `emitPluginAppEvent`). An internal caller
+(`INTERNAL_TOOL_SECRET`) is a writer.
+
+**Route or task?** A route lives exactly as long as a request: close the tab and the clock in
+the example stops streaming — nothing durable happened unless the handler wrote events. A
+task (docs/07) survives everything and costs seconds per hop. The stopwatch ships both and
+records which one drove each run; measure before you choose.
+
 
 
 ==============================================================================
@@ -677,12 +880,35 @@ replay; mint them inside. Step names are unique per logical operation; loops inc
   `kickPluginTask({ applicationType, taskName, identifier, data })` (from `esoul-sdk`; works in
   a component and in a tool's `execute`). The platform's send-event route allows only listed
   tasks and stamps nothing — `data` is exactly what `ctx.eventData` sees.
+- **In a Forge preview** the same call runs the task IN the preview's dev server, behind the
+  same `ctx` (steps, `getState`, `dispatchEvent`, `notify`), against an in-process store the
+  page mirrors — so you can press Start in the frame before the app is installed. What the
+  preview does not give you: durability across a process death, retries, a scheduler, and the
+  platform's `if` on `waitForEvent` (the preview matches the event name and your node).
 - **On a cadence**: `pollTasks: [{ task, everyMinutes }]` — one shared platform sweep kicks each
   live instance at 5-minute granularity (minimum 5). This is your cron. There are deliberately
   no per-app Inngest functions: function ids are fixed at module load, and the plan caps
   concurrency; a shared sweep costs nothing per app. Handlers must be idempotent anyway, because
   sweeps and pushes overlap by design.
 
+
+## Task or route? Measured (2026-09-10, the stopwatch)
+
+| | a server route (docs/06) | a durable task |
+|---|---|---|
+| kick → first tick | 0.2 s | 2–15 s |
+| stop landed → run finished | 0.8 s | 0.7–12 s |
+| tick cadence | 1 s | ~3 s |
+| a fold read | 60 ms | ~2.8 s |
+| survives the tab closing | no — nothing outlives the request | yes — everything |
+| survives a deploy / crash | no | yes |
+
+Every step of a task is a round trip through the scheduler into the platform's function.
+So: **the user's time is measured on the user's clock** (the two presses), the task is the
+durable witness, and the route is the live view. Ship both when the difference matters, and
+record which one drove each run — the timeline is the measurement. Never make a task keep
+sub-second time; never make a route keep a promise past its request.
+
 ## Concurrency
 
 `concurrency: { limit, scope: "per-app" | "global" }`. Keep the limit small; a parked wait holds
@@ -851,6 +1077,24 @@ platform) and commit `fold-corpus.json` + hashes. From then on the checks refuse
 alters what history MEANS — the strongest protection an app with data can have. Re-recording is
 declaring a migration; say so in the changelog.
 
+## What runs in a Forge preview (parity)
+
+Since 2026-09-10 a workbench keeps an in-process stand-in for the database, Inngest and the
+broker, so before the app is installed:
+
+| | in the preview | not in the preview |
+|---|---|---|
+| events, tools (`call_app_tool`), `read_app_state` | yes | |
+| tasks (`kickPluginTask`, from the UI or a tool) | yes — same `ctx`, in-process | durability, retries, a scheduler; `waitForEvent`'s `if` (name + node only) |
+| ops (`callPluginOp`, `readAppState`) | yes — on a preview-only route, over the preview's fold | a real database |
+| routes (`pluginRouteUrl` → a preview-only route) | yes — the caller is a writer | auth (the sandbox is single-tenant) |
+| realtime (`ctx.notify` → `usePluginRealtime`) | yes — polled from the store | the broker |
+| `emitPluginAppEvent` from a route or op | yes | cross-app targets outside the preview |
+
+The board is told which of these a box has: the preview announces `tasks`, `ops`, `routes`,
+`realtime` in its greeting once the store answers, and the frame reloads itself when the
+server side is a newer build than the bundle it runs.
+
 
 
 ==============================================================================
@@ -963,5 +1207,562 @@ platform it runs on.
 - "State reverts after reload" → `reconstructStateFromEventLog` unset, or a processor minted ids.
 - "check_app is red on registry" → the manifest failed validation or the import wall refused a
   file; the detail names it.
-- "My tool needs the database" → write an op; call it with `callPluginOp`; expect a refusal in
-  the workbench (no database behind a preview) and use `read_app_state` there.
+- "My tool needs the database" → declare the tables in the manifest's `db` and write an op over
+  `pluginDb(ctx)`; call it with `callPluginOp`. The workbench runs it over in-memory tables with
+  the same rules, so VIEW AS shows what each person may read.
+
+
+
+==============================================================================
+# 13 · People and access
+
+Your app will be used by people with different relationships to it: the person who installed it,
+the people they invited, and everyone else. This page is how the platform tells them apart, and
+how you say what each may do — without writing a single access check.
+
+## The viewer
+
+Every seam of your app receives a `viewer`. The UI reads it with `useViewer()`; the server gets
+`ctx.viewer` on an op, a route and a tool; a task carries `ctx.kickedBy` (who asked) and runs as
+your app's own code.
+
+```ts
+viewer.kind      // "owner" | "member" | "visitor" | "anonymous" | "agent" | "internal"
+viewer.userId    // the account, or null
+viewer.role      // YOUR app's word for them (see below)
+viewer.canWrite  // may they change the workspace at all
+```
+
+- **owner** — whose workspace this is.
+- **member** — someone the owner invited, with edit or read-only access.
+- **visitor** — signed in, but not in the workspace: someone on a share link.
+- **anonymous** — not signed in. Still has an identity (a cookie) so rows they create can be
+  theirs, and stay theirs after they sign in.
+- **agent** — a run acting for one of the above. It gains nothing: everything about what it may
+  see comes from the person it acts for.
+- **internal** — your own app's server code (a task, the install job). Rules do not apply to it;
+  scope still does.
+
+The platform resolves this. An app cannot supply, widen or forge one — the import wall keeps you
+from reading a cookie or a header to invent an identity.
+
+## Who they actually are
+
+A viewer is an identity, not a person's details. When your app needs the details — a name to put
+on a confirmation, an address to send one to — ask for the CALLER's own account:
+
+```ts
+import { viewerProfile } from "esoul-sdk/server";
+
+const me = await viewerProfile(ctx.viewer);   // { userId, email, name, picture } | null
+```
+
+Server only, one database read, and only ever about the caller: there is no argument for whose
+profile to read, so an app cannot look somebody up. It is null for anyone without an account,
+which is the same thing `requires: "account"` is about. Use it to pre-fill a form rather than
+asking a signed-in person to type what the platform already knows.
+
+In a test, `fakeViewer("visitor", { userId: "u_ada", role: "requester", name: "Ada", email: "ada@x.test" })`
+is what `viewerProfile` answers for that viewer; a fake viewer with no name or email answers null.
+No test ever reaches a database for it.
+
+## Roles — your app's own vocabulary
+
+The platform's words are about a workspace. Your app's words are about your app. A help desk has
+requesters and agents; a library has readers and librarians; a clinic has patients and staff.
+
+```json
+"roles": {
+  "vocabulary": ["requester", "agent", "supervisor"],
+  "default": {
+    "owner": "supervisor",
+    "member-edit": "agent",
+    "member-readonly": "agent",
+    "visitor": "requester",
+    "anonymous": "requester",
+    "agent": "inherit"
+  },
+  "describe": {
+    "requester": "raises tickets and sees their own",
+    "agent": "answers every ticket; never the billing notes",
+    "supervisor": "everything, including who handled what"
+  }
+}
+```
+
+`default` maps the platform's kinds onto your words. Two sentinels are the platform's, not yours:
+`inherit` (an agent takes the role of whoever it acts for) and `none` (this app has no word for
+that kind of caller, so no rule can match them — the right answer when a stranger has no business
+here at all).
+
+**The workspace owner can override it per person, per app.** In workspace sharing, an app that
+declares a vocabulary gets a picker showing your words and your descriptions. So one colleague is
+an `agent` in the help desk and another a `supervisor`, in the same workspace, and everyone
+outside is a `requester` whether or not they are signed in.
+
+A role is a WORD, never a permission. It decides what your rules mean. Whether someone may write
+the workspace at all is still the platform's answer: a read-only collaborator you call `agent`
+still cannot write.
+
+## Access levels — nothing opens by default
+
+Every op, route and task is `write` unless you say otherwise: the owner and editing members only.
+
+```json
+"ops": {
+  "list-public-articles": { "access": "public" },
+  "raise-ticket":         { "access": "public", "requires": "account" },
+  "my-tickets":           { "access": "public", "requires": "account" },
+  "close-ticket":         {}
+},
+"routes": { "queue-stream": { "access": "read" } },
+"kickableTasks": { "escalate": { "access": "write" } }
+```
+
+| level | who reaches it |
+|---|---|
+| `write` (default) | the owner and members who may edit |
+| `read` | anyone who can SEE the workspace, including read-only members |
+| `public` | anyone holding the app's share link, with no workspace access at all |
+| `public` + `requires: "account"` | the same, but they must be signed in |
+
+**`read` is not "outsiders".** It means workspace members. Someone on a share link is reached with
+`public`. Getting this wrong is the commonest mistake: an app that declares "my own records" as
+`read` refuses the very people it was written for.
+
+**`requires: "account"` is the sign-in wall.** Without it an anonymous caller gets `forbidden`,
+which a UI can only render as an error. With it they get `login-required` and a way back, and
+`useSignInWall()` turns it into a wall:
+
+```tsx
+const wall = useSignInWall();
+try { await op("raise-ticket", args); }
+catch (e) { wall.raise(e); }   // login-required → the wall; anything else rethrows
+```
+
+Every `public` door is listed on the install card, by name, before anyone installs your app.
+
+## What a refusal looks like
+
+One shape everywhere, with a code your UI can act on:
+
+| code | status | means |
+|---|---|---|
+| `forbidden` | 403 | the rules say no, and signing in would not change it |
+| `login-required` | 401 | sign in and try again; `signInPath` says where |
+| `not-bound` | 409 | a slot this app needs is not filled yet |
+| `rate-limited` | 429 | too many calls at a public door |
+| `invalid` | 400 | the call itself is malformed |
+
+In a workbench the refusal also carries `detail`, written for YOU: which rule refused and what to
+change. It is never returned in production, and never contains the caller's data.
+
+## Seeing it before anyone installs
+
+A workbench has **VIEW AS**: a switcher for the platform's kinds — owner, member, read-only
+member, two different visitors, anonymous, agent. Your app resolves each one through your own
+`roles`. Two visitors on purpose: the question worth asking is not "does a person see their own
+record" but "does the OTHER one see it".
+
+`look_at_app` takes the same personas, so you can photograph the screen each of them gets — the
+one screen an author can otherwise never see, because the author is always the owner.
+
+
+
+==============================================================================
+# 14 · Your own tables
+
+The fold (docs/03) is for what is shared, small and worth scrubbing. Records that belong to one
+person, that grow without limit, and that must never revert because somebody scrubbed a timeline
+are none of those. Those go in your app's own tables.
+
+You declare them. The platform generates the schema, the typings and the rules, applies the
+migration on install, and scopes every query. You never write a migration, an ORM, or a
+`WHERE userId = …`.
+
+## Declaring
+
+```json
+"db": {
+  "Article": {
+    "fields": { "title": "string", "body": "text", "published": "boolean=true" },
+    "unique": [["title"]],
+    "indexes": [["published"]],
+    "rules": { "read": ["anyone"], "write": ["supervisor"] }
+  },
+  "Ticket": {
+    "owner": "creator",
+    "fields": { "status": "string=open", "subject": "string", "detail": "text", "article": "ref:Article?" },
+    "indexes": [["status"], ["createdAt"]],
+    "rules": {
+      "read":   ["creator", "agent", "supervisor"],
+      "create": { "roles": ["requester", "agent"], "requires": "account" },
+      "update": { "roles": ["agent", "supervisor"], "creatorMay": ["detail"] },
+      "delete": ["supervisor"]
+    }
+  },
+  "ContactDetails": {
+    "scope": "user",
+    "sealed": ["phone"],
+    "fields": { "label": "string", "phone": "string" }
+  }
+}
+```
+
+**Field types.** `string`, `text`, `int`, `float`, `boolean`, `datetime`, `json`, `ref:Model`.
+A trailing `?` is optional; `=value` is a default; `[]` is a list. Platform columns (`id`,
+`workspaceId`, `nodeId`, `ownerId`, `createdBy`, `createdAt`, `updatedAt`, `deletedAt`) are added
+for you and may not be declared.
+
+**Scope** decides what "this app's rows" means:
+
+| scope | rows belong to | use it for |
+|---|---|---|
+| `instance` (default) | ONE app instance | this help desk's tickets |
+| `workspace` | every instance in the workspace | something shared between apps |
+| `user` | one person, across every instance | contact details that follow them |
+
+**`owner: "creator"`** makes each row belong to whoever made it, which is what `creator` in a rule
+matches against. It matches every id that person has acted under, so a record created before
+signing in is still theirs afterwards.
+
+**`sealed`** fields are encrypted at rest and readable only by the row's owner (and your app's own
+internal code, which is how a background job can still use one). Anyone else reading a sealed
+field gets null, not ciphertext.
+
+## Rules
+
+A rule names PRINCIPALS: `"anyone"`, `"creator"`, a role from your vocabulary, or `"apps"` (apps
+bound to yours — see docs/16). The long form adds `requires: "account"` and `creatorMay`, which
+lists the fields a row's creator may change even when they may not otherwise update it.
+
+Rules are compiled once, at build time, and the SAME compiled artefact drives the in-memory client
+your tests use, the Prisma client production uses, and the workbench. A rule that names a role
+your app does not declare fails the build, with the key path.
+
+## Using
+
+```ts
+import { pluginDb } from "esoul-sdk/server";
+import type { HelpdeskDb } from "./.esoul/db";   // generated from your manifest
+
+async function myTickets(ctx: PluginOpContext) {
+  const db = await pluginDb<HelpdeskDb>(ctx);
+  return db.ticket.findMany({ orderBy: { createdAt: "desc" }, take: 50 });
+}
+```
+
+That is the whole access story. The same call returns one person's own tickets and an agent's
+whole queue, because `ctx.viewer` is already in the client. There is no argument you could pass to
+read someone else's rows: `workspaceId`, `nodeId` and `ownerId` are injected, and naming one in a
+query is refused as `invalid` rather than quietly overridden.
+
+Ordering and filtering are limited to the fields you indexed — an unindexed `orderBy` is a compile
+error in your editor, not a slow query in production.
+
+### The whole surface
+
+Your generated type is the reference (open `.esoul/db.d.ts`), and this is all of it:
+
+| | |
+|---|---|
+| read | `findMany` · `findFirst` · `findUnique({ where: { id } })` · `count` |
+| summarise | `aggregate({ where?, _count, _sum, _avg, _min, _max })` · `groupBy({ by, … })` |
+| write | `create` · `createMany` · `update({ where: { id }, data })` · `updateMany` · `upsert` · `delete` · `deleteMany` |
+| together | `$transaction(fn)` |
+
+`findMany` takes `where`, `orderBy`, `take`, `skip`, `cursor: { id }`. Every `where` — including
+an `aggregate`'s — obeys the index wall above: a field you did not index is not a question, and
+asking it is refused as `invalid` rather than answered slowly. **Count and sum in the database**
+rather than paging rows to add them up in JavaScript; `groupBy` still returns only the rows this
+viewer may read, so a customer's own total is their own and an aggregate is never a way around a
+rule.
+
+### Transactions
+
+`$transaction` gives you the one guarantee a pair of writes cannot give itself: either both
+happened, or neither did.
+
+```ts
+const order = await db.$transaction(async (tx) => {
+  const written = await tx.order.create({ data: { totalCents, shipTo } });
+  for (const l of lines) await tx.orderLine.create({ data: { order: written.id, ...l } });
+  await tx.cartLine.deleteMany();   // the basket that made it
+  return written;
+});
+```
+
+Every gap between two writes is a real state somebody's session can end in. An order committed
+and a basket emptied a moment later is not a detail: the moment in between is "paid for, still in
+the basket", which is how a person buys the same thing twice. Put the writes that must be true
+together in one call, and let a throw undo all of them.
+
+Rules still apply inside, per statement, for the same viewer — a transaction is atomicity, never
+elevation.
+
+**What a transaction cannot hold.** A call into ANOTHER app (`ctx.apps.<slot>.call(…)`, an email,
+a payment) is outside it by construction: the other app's writes are its own. For those, hold →
+write → and **release on failure**, yourself:
+
+```ts
+const held = [];
+try {
+  for (const l of lines) { await stock.call("reserve_stock", l); held.push(l); }
+  return await db.$transaction(…);
+} catch (err) {
+  for (const h of held) await stock.call("release_stock", h);   // never throws out of here
+  throw err;
+}
+```
+
+A reservation no order ever used is worse than a refusal: nothing marks it stale, so the shelf
+reads empty while the goods sit there.
+
+## Indexes for a catalogue
+
+A plain group is a btree: equality, ranges, ordering. Two other kinds exist because a real
+catalogue asks two questions a btree cannot answer.
+
+```json
+"indexes": [
+  ["active", "createdAt"],
+  { "fields": ["tags"], "kind": "contains" },
+  { "fields": ["title"], "kind": "text" }
+]
+```
+
+| kind | the field | what it lets you ask |
+|---|---|---|
+| `btree` (a plain group) | any | `where: { active: true }`, `orderBy: { createdAt: "desc" }` |
+| `contains` | a LIST | `where: { tags: { has: "gifts" } }` |
+| `text` | a string or text | `where: { title: { contains: "grey" } }` — **regardless of case** |
+
+```ts
+// A department and a search term, both as a WHERE — with a cursor, so the
+// hundredth page costs what the first one did.
+db.product.findMany({
+  where: { active: true, tags: { has: dept }, title: { contains: term } },
+  orderBy: { createdAt: "asc" },
+  take: 24,
+  cursor: after ? { id: after } : undefined,
+});
+```
+
+`contains` ignores case in both clients (`ILIKE`, which a trigram index still serves), because a
+search box that finds "Earl Grey" and not "earl grey" is broken in the quietest possible way — the
+shopper just reads an empty shelf.
+
+**A list takes one question and a scalar takes the others.** `{ tags: { has: … } }` on a list,
+never a bare value and never `contains`; `{ title: { contains: … } }` on text, never `has`. Asking
+the wrong one is refused as `invalid` with the right one named, because an empty result would look
+like an empty shelf. (A refusal's `message` is the code; the sentence written for you is on
+`err.detail`.)
+
+Both of the new kinds become GIN indexes, and neither is led by the scope column — a GIN index
+cannot be, so the database combines it with the scope index instead. That is the right plan, and
+it is why `contains` and `text` cover exactly one field each.
+
+**Why this matters more than it looks.** Without them, a shop with 100 000 products can only
+return a page and filter it in the browser, so a department with nothing on the first page looks
+empty. The declaration is the whole difference between a catalogue and a list.
+
+## Migrations
+
+On install the platform computes what your declaration means for the live database and applies it
+in one transaction, recording it in a ledger. **Additive only.** Adding a table, a column or an
+index is applied; changing a column's type, or adding a required column with no default, is
+REFUSED with the column named, and the install does not proceed. A field you removed keeps its
+column and its data — dropping it is a separate, deliberate act.
+
+Uninstalling never drops a table. The rows are somebody's records.
+
+## Testing
+
+```ts
+import { fakeViewer, memoryDb, runOp } from "esoul-sdk/testing";
+
+const db = memoryDb(manifest);           // your rules, compiled from your own plugin.json
+const ada = fakeViewer("visitor", { userId: "u_ada", role: "requester" });
+const lin = fakeViewer("visitor", { userId: "u_lin", role: "requester" });
+
+await runOp(pluginServer, "raise-ticket", { viewer: ada, args: TICKET, db: db.as(ada) });
+expect(await db.as(lin).ticket.count()).toBe(0);
+```
+
+The in-memory client and the production one are proven equal by a differential test on every
+build, so a rule you prove here is a rule the database keeps.
+
+
+
+==============================================================================
+# 15 · Realtime, and who hears it
+
+Your app can push. A screen that is already open moves without anyone asking it to, which is the
+difference between an application and a form.
+
+Two declarations, both needed. The manifest says WHO hears each topic; the schema says what the
+topics are and what rides on them.
+
+```json
+"channel": {
+  "topics": {
+    "notice":        { "description": "something everyone watching should see" },
+    "ticket-status": { "audience": "viewer", "mayAddress": ["agent", "supervisor"] },
+    "new-ticket":    { "audience": "role:agent", "mayAddress": ["requester", "agent", "supervisor"] }
+  }
+}
+```
+
+```ts
+export const channel = definePluginChannel({
+  applicationType: APP_TYPE,
+  topics: {
+    notice: { schema: z.object({ what: z.string() }) },
+    "ticket-status": { schema: z.object({ ticketId: z.string(), status: z.string() }) },
+    "new-ticket": { schema: z.object({ ticketId: z.string(), subject: z.string() }) },
+  },
+});
+```
+
+## Audiences
+
+| `audience` | the channel |
+|---|---|
+| `all` (default) | one per instance — anyone watching the app |
+| `viewer` | one per person — "your ticket was answered" |
+| `role:<name>` | one per role — the queue everyone on duty watches |
+
+The platform mints a token PER CHANNEL, and the browser asks for a KIND of channel, never for an
+identifier. The server fills in whose channel that is from the viewer it resolved. So one person
+cannot ask for another's channel: the id is not theirs to supply, and a role's channel is simply
+not minted for someone outside that role. Nothing is filtered on arrival, because nothing wrong
+ever arrives.
+
+An app that declares no audiences keeps the single channel it always had.
+
+## Sending
+
+```ts
+await ctx.notify("ticket-status", { ticketId, status });                                   // the CALLER's own channel
+await ctx.notify("ticket-status", { ticketId, status }, { to: { viewerIds: [row.ownerId] } });
+await ctx.notify("new-ticket",    { ticketId, subject }, { to: { role: "agent" } });
+```
+
+Unaddressed, a message goes where the topic says. Addressed, **aiming is a separate permission
+from hearing**: a caller may address only ITSELF unless the topic's `mayAddress` names its role.
+Your app's own tasks always may, which is why a follow-up task can tell the person who waited.
+
+Two traps worth naming. Both cost the reference app a live drive, and both are easy to repeat:
+
+- **Everyone who may DO the thing must be allowed to announce it.** An app that let two roles
+  create a record but only one of them announce it refused the others their own action — by their
+  own announcement. List every role your `create` rule allows.
+- **A courtesy must not undo a completed write.** The record is already in the table when you
+  announce it. Catch a failed notify and report it; do not let it throw out of the op, or a person
+  is told "forbidden" about something that exists and tries again.
+
+## Listening
+
+```tsx
+const live = usePluginRealtime<{ ticketId?: string; status?: string }>({
+  channel,
+  workspaceId: state.workspaceId,
+  nodeId: state.nodeId,
+  topics: channel.topicNames,
+  enabled: !!state.nodeId && viewer.signedIn,
+});
+
+useEffect(() => {
+  if (live.latestData?.topic === "ticket-status") reload();
+}, [live.latestData, reload]);
+```
+
+**Treat a message as a nudge, not as data.** Re-read through your op, so the rules decide what
+comes back. A payload that carried the row would be a second way to learn about it, and only one
+of them is checked.
+
+In a workbench the preview shows a persona only what their channels would carry, so VIEW AS tells
+you the truth: switch to the other visitor and the message is not there.
+
+
+
+==============================================================================
+# 16 · Bindings — leaning on another app
+
+An app is an island until it can use another one. A booking app that wants real room availability
+either keeps its own counts and guesses, or names one particular rooms app and is married to it.
+Neither is what a person means by "use my room list for this".
+
+So you declare a SLOT and the CONTRACT that must stand in it. The owner picks which app fills it.
+
+## Declaring
+
+The consumer:
+
+```json
+"uses": { "rooms": { "contract": "rooms/v1", "label": "Rooms", "optional": true } }
+```
+
+The provider:
+
+```json
+"provides": {
+  "rooms/v1": { "tools": ["hold_room", "release_room"], "events": ["room_freed"], "models": ["Room"] }
+}
+```
+
+A consumer must also fold the binding event, because the owner's choice lives on your app's own
+timeline — a binding is CONSENT, and consent that is only a column cannot be scrubbed, explained
+or audited:
+
+```ts
+export const bindingSetEvent = defineBindingEvent<BookingData>({ applicationType: APP_TYPE, slots: ["rooms"] });
+// …and put it in the schema's `events`.
+```
+
+The build refuses an app that declares `uses` without it.
+
+## What the platform checks, and when
+
+At BIND time, once, loudly — never at call time in front of somebody using the app:
+
+- The provider must claim the same contract NAME at a version at least as high. **Versions grow by
+  adding**, so a `rooms/v2` provider fills a `rooms/v1` slot; the reverse is refused, because v1
+  never heard of what v2 added. That rule is what lets your app keep working while its provider
+  moves on.
+- The provider must really HAVE what it claims: the tools it actually mints, the events its schema
+  declares, the tables its `db` generates. A manifest is a claim, and a claim that is short is
+  refused with the missing part named.
+
+## Using
+
+```ts
+const rooms = ctx.apps?.rooms;          // absent when nothing is bound
+if (rooms) {
+  const held = await rooms.call("hold_room", { roomId, from, to });
+  if (!held.ok) throw new Error(`cannot take this booking: ${held.text}`);
+}
+```
+
+- **An unfilled slot is ABSENT**, not present and broken, so `ctx.apps.rooms?` reads as the
+  question it is. An optional slot means your app still works without one; a required slot that is
+  empty refuses at the seam with `not-bound`, which a UI should render as "connect one" rather
+  than as an error.
+- **A slot reaches the CONTRACT's tools, not the provider's toolkit.** A consumer bound through
+  `rooms/v1` may hold a room and release it; it may not call the rooms app's `retire_room`, though
+  it has one. The binding is consent to a contract.
+- **The caller travels.** The provider's rules meet the actual person, so a visitor reaching the
+  rooms app through your app sees what a visitor may see.
+- **Writes never cross directly.** The provider's own tools and ops are the only writers of its
+  tables, which is how a ledger keeps refusing to oversell no matter who asked.
+
+## Being a good provider
+
+A provider's whole value is usually one refusal: you cannot hold what is not free. Keep it in ONE
+place — the app's own server — so it holds however the hold was asked for: through a binding, a
+tool, or a person working in the app itself. That is what makes an app worth binding to. An app
+that counted the same thing in its own fold could not make the promise, because two people can
+read the same fold in the same instant.
+
+Say no in your own words, too. A refusal that reads `cannot hold 2: only 1 free (1 free, 1 already
+held)` reaches the consumer, and the consumer can put it in front of a person instead of a shrug.