esoul-sdk 0.4.0 → 0.7.0

package/dist/testing/db.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Prove your access rules in a unit test, in milliseconds, before anything is
+ * installed anywhere.
+ *
+ * The client these helpers hand you is not a mock of the platform's: it loads
+ * the rules compiled from your own `plugin.json` and applies them exactly as
+ * production does, down to refusing a filter on a column you forgot to index.
+ * So the test every shop should own —
+ *
+ *   expect(await db.as(bob).order.count()).toBe(0)
+ *
+ * — means the same thing here as it will mean on the real database, which is
+ * the point of the whole arrangement.
+ */
+import { type CompiledRules, type RuleViewer } from "../db/compile-rules.js";
+import { type MemoryDb, type MemoryStore } from "../db/memory-client.js";
+/** The parts of a plugin.json these helpers read. */
+export interface TestManifest {
+    id?: string;
+    db?: Record<string, never>;
+    roles?: {
+        vocabulary?: string[];
+        default?: Record<string, string>;
+    };
+}
+export type ViewerKind = RuleViewer["kind"];
+/**
+ * A caller to run something as. Give it a `role` when your app declares its own
+ * vocabulary, or let `memoryDb(manifest).as("visitor")` map it for you from the
+ * manifest's own `roles.default`.
+ */
+export declare function fakeViewer(kind: ViewerKind, opts?: {
+    userId?: string | null;
+    viewerIds?: string[];
+    role?: string;
+    name?: string | null;
+    email?: string | null;
+}): RuleViewer;
+/**
+ * The app's own word for a kind of caller, read from the manifest's `roles`.
+ *
+ * Delegates to `../roles`, which the PLATFORM also uses when it builds a real
+ * viewer. That is the whole point: a helper that mapped roles its own way would
+ * make a read-only member `staff` in an author's unit test and `viewer` in
+ * production, and every rule naming `staff` would change meaning between them.
+ *
+ * A `member` here is an EDIT member — the test helper's kinds are coarser than
+ * the platform's. Pass a `role` to `fakeViewer` for the read-only case.
+ */
+export declare function roleForKind(manifest: TestManifest, kind: ViewerKind): string;
+export interface MemoryDbHandle extends MemoryDb {
+    /** The same rows seen as somebody else — a kind name, or a full viewer. */
+    as(viewer: RuleViewer | ViewerKind, opts?: Record<string, unknown>): MemoryDbHandle;
+    /** The compiled rules, if you want to assert on them directly. */
+    $rules: CompiledRules;
+}
+export interface MemoryDbOptions {
+    viewer?: RuleViewer | ViewerKind;
+    workspaceId?: string;
+    nodeId?: string;
+    store?: MemoryStore;
+    viaBinding?: boolean;
+    across?: "owned-instances" | "my-rows";
+    ownedWorkspaceIds?: string[];
+}
+/**
+ * A database for your app, from your manifest. Starts as the app's own code
+ * (an `internal` caller) so a test can seed rows, then `.as(someone)` to check
+ * what each kind of person may actually see.
+ */
+export declare function memoryDb(manifest: TestManifest, options?: MemoryDbOptions): MemoryDbHandle;

package/dist/testing/db.js

@@ -0,0 +1,103 @@
+/**
+ * Prove your access rules in a unit test, in milliseconds, before anything is
+ * installed anywhere.
+ *
+ * The client these helpers hand you is not a mock of the platform's: it loads
+ * the rules compiled from your own `plugin.json` and applies them exactly as
+ * production does, down to refusing a filter on a column you forgot to index.
+ * So the test every shop should own —
+ *
+ *   expect(await db.as(bob).order.count()).toBe(0)
+ *
+ * — means the same thing here as it will mean on the real database, which is
+ * the point of the whole arrangement.
+ */
+import { compileRules, } from "../db/compile-rules.js";
+import { createMemoryDb, createStore, } from "../db/memory-client.js";
+import { resolveAppRole, roleKeyFor } from "../roles.js";
+const PLATFORM_DEFAULT_ROLE = {
+    owner: "owner",
+    member: "editor",
+    visitor: "viewer",
+    anonymous: "viewer",
+    agent: "viewer",
+    internal: "owner",
+};
+const DEFAULT_IDS = {
+    owner: "u_owner",
+    member: "u_member",
+    visitor: "u_visitor",
+    anonymous: null,
+    agent: "u_agent",
+    internal: null,
+};
+/**
+ * A caller to run something as. Give it a `role` when your app declares its own
+ * vocabulary, or let `memoryDb(manifest).as("visitor")` map it for you from the
+ * manifest's own `roles.default`.
+ */
+export function fakeViewer(kind, opts = {}) {
+    const userId = opts.userId !== undefined ? opts.userId : DEFAULT_IDS[kind];
+    const viewerIds = opts.viewerIds ?? (userId ? [userId] : []);
+    // THE ACCOUNT BEHIND THE VIEWER, for `viewerProfile`. A test that names one
+    // gets it back from the op under test; a test that names none gets null —
+    // and never a database. Registered on globalThis because the host's
+    // `viewerProfile` is the one that answers, and this is how it learns that a
+    // test is asking (the same seam `runAsViewer` uses).
+    if (userId && (opts.name !== undefined || opts.email !== undefined)) {
+        const g = globalThis;
+        (g.__esoulFakeProfiles ??= {})[userId] = { userId, name: opts.name ?? null, email: opts.email ?? null, picture: null };
+    }
+    return { kind, userId, viewerIds, role: opts.role ?? PLATFORM_DEFAULT_ROLE[kind] };
+}
+/**
+ * The app's own word for a kind of caller, read from the manifest's `roles`.
+ *
+ * Delegates to `../roles`, which the PLATFORM also uses when it builds a real
+ * viewer. That is the whole point: a helper that mapped roles its own way would
+ * make a read-only member `staff` in an author's unit test and `viewer` in
+ * production, and every rule naming `staff` would change meaning between them.
+ *
+ * A `member` here is an EDIT member — the test helper's kinds are coarser than
+ * the platform's. Pass a `role` to `fakeViewer` for the read-only case.
+ */
+export function roleForKind(manifest, kind) {
+    return resolveAppRole({
+        roles: manifest.roles,
+        platformRole: PLATFORM_DEFAULT_ROLE[kind],
+        key: roleKeyFor(kind),
+    });
+}
+/**
+ * A database for your app, from your manifest. Starts as the app's own code
+ * (an `internal` caller) so a test can seed rows, then `.as(someone)` to check
+ * what each kind of person may actually see.
+ */
+export function memoryDb(manifest, options = {}) {
+    const rules = compileRules({
+        pluginId: manifest.id ?? "app",
+        db: manifest.db ?? {},
+        vocabulary: manifest.roles?.vocabulary,
+        ownerRole: manifest.roles?.default?.owner,
+    });
+    const store = options.store ?? createStore(rules);
+    const build = (viewer, extra = {}) => {
+        const v = typeof viewer === "string" ? fakeViewer(viewer, { role: roleForKind(manifest, viewer) }) : viewer;
+        const db = createMemoryDb({
+            rules,
+            viewer: v,
+            store,
+            scope: {
+                workspaceId: extra.workspaceId ?? options.workspaceId ?? "ws_test",
+                nodeId: extra.nodeId ?? options.nodeId ?? "app_1",
+            },
+            across: extra.across ?? options.across,
+            ownedWorkspaceIds: extra.ownedWorkspaceIds ?? options.ownedWorkspaceIds,
+            viaBinding: extra.viaBinding ?? options.viaBinding,
+        });
+        db.as = (other, o) => build(other, { ...extra, ...o });
+        db.$rules = rules;
+        return db;
+    };
+    return build(options.viewer ?? "internal");
+}

package/dist/testing/index.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Test utilities that need NOTHING from the host.
+ *
+ * Two families:
+ *   - `memoryDb` / `fakeViewer` / `runOp` / `fakeApps` / `capture` — prove your
+ *     app's ACCESS RULES: who sees which rows, who is refused, who is told to
+ *     sign in. The client runs the rules compiled from your own plugin.json,
+ *     so what passes here is what the real database will do.
+ *   - `startMockOAuth` — a real tiny OAuth2 provider for the connection flow.
+ */
+export { fakeViewer, memoryDb, roleForKind } from "./db.js";
+export type { MemoryDbHandle, MemoryDbOptions, TestManifest, ViewerKind } from "./db.js";
+export { capture, fakeApps, runOp } from "./ops.js";
+export type { BoundAppFixture, EmitCall, NotifyCall, Recorder, RunOpOptions, RunOpResult } from "./ops.js";
 export interface MockOAuthServer {
     port: number;
     url: string;

package/dist/testing/index.js

@@ -1,6 +1,15 @@
 /**
  * Test utilities that need NOTHING from the host.
+ *
+ * Two families:
+ *   - `memoryDb` / `fakeViewer` / `runOp` / `fakeApps` / `capture` — prove your
+ *     app's ACCESS RULES: who sees which rows, who is refused, who is told to
+ *     sign in. The client runs the rules compiled from your own plugin.json,
+ *     so what passes here is what the real database will do.
+ *   - `startMockOAuth` — a real tiny OAuth2 provider for the connection flow.
  */
+export { fakeViewer, memoryDb, roleForKind } from "./db.js";
+export { capture, fakeApps, runOp } from "./ops.js";
 import http from "node:http";
 import crypto from "node:crypto";
 /**

package/dist/testing/ops.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Run one of your server ops the way the platform will, and see what it did.
+ *
+ * The platform hands an op a viewer, a database, a way to notify and a way to
+ * emit. `runOp` hands it the same things with the notifications and events
+ * recorded, so a test can assert the part that matters most and is hardest to
+ * see: WHO a message went to.
+ *
+ *   const { result, notified } = await runOp(pluginServer, "place-order", { db, viewer: alice, args });
+ *   expect(notified).toEqual([{ topic: "new-order", to: { role: "staff" }, data: { orderId: result.orderId } }]);
+ */
+import type { RuleViewer } from "../db/compile-rules.js";
+import type { MemoryDbHandle } from "./db.js";
+export interface NotifyCall {
+    topic: string;
+    data: unknown;
+    to?: unknown;
+}
+export interface EmitCall {
+    eventName: string;
+    eventData: Record<string, unknown>;
+}
+export interface BoundAppFixture {
+    nodeId?: string;
+    applicationType?: string;
+    /** The provider's state, as `ctx.apps.<slot>.state()` would return it. */
+    state?: Record<string, unknown>;
+    /** The provider's tools, as functions. */
+    tools?: Record<string, (args?: Record<string, unknown>) => Promise<{
+        ok: boolean;
+        text: string;
+    }> | {
+        ok: boolean;
+        text: string;
+    }>;
+    /** The provider's database, for the models it opened to bound apps. */
+    db?: MemoryDbHandle;
+}
+/**
+ * Fill a `uses` slot with a stand-in provider, so a consumer's op can be
+ * tested without the other app existing. Calls to a tool the fixture does not
+ * define come back as a refusal, which is what an unbound slot really does.
+ */
+export declare function fakeApps(fixtures: Record<string, BoundAppFixture>): Record<string, unknown>;
+export interface RunOpOptions {
+    viewer: RuleViewer;
+    args?: unknown;
+    db?: MemoryDbHandle;
+    apps?: Record<string, unknown>;
+    pluginId?: string;
+    workspaceId?: string;
+    nodeId?: string;
+    instanceName?: string;
+    cloudConnectionId?: string | null;
+    /**
+     * Make `ctx.notify` THROW, so a test can ask the question worth asking of
+     * any op that tells somebody after it has written something: does the write
+     * survive? A courtesy must never undo a completed order. Return the error
+     * the platform would throw — a refusal carries `code: "forbidden"`.
+     */
+    notifyFails?: (topic: string, to: unknown) => unknown;
+}
+export interface RunOpResult<T = unknown> {
+    result: T;
+    notified: NotifyCall[];
+    emitted: EmitCall[];
+}
+interface ServerModuleLike {
+    ops?: Record<string, (ctx: never) => Promise<unknown>>;
+}
+/**
+ * Call `pluginServer.ops[name]` with a context shaped like the platform's.
+ * Throws whatever your op throws — including the platform's refusals, so
+ * `await expect(runOp(...)).rejects.toMatchObject({ code: "login-required" })`
+ * is how you prove the sign-in wall appears for the right person.
+ */
+export declare function runOp<T = unknown>(server: ServerModuleLike, opName: string, options: RunOpOptions): Promise<RunOpResult<T>>;
+export interface Recorder<A extends unknown[]> {
+    fn: (...args: A) => Promise<void>;
+    calls: A[];
+}
+/** A call recorder, for anything `runOp` does not already capture. */
+export declare function capture<A extends unknown[] = unknown[]>(): Recorder<A>;
+export {};

package/dist/testing/ops.js

@@ -0,0 +1,76 @@
+/**
+ * Fill a `uses` slot with a stand-in provider, so a consumer's op can be
+ * tested without the other app existing. Calls to a tool the fixture does not
+ * define come back as a refusal, which is what an unbound slot really does.
+ */
+export function fakeApps(fixtures) {
+    const apps = {};
+    for (const [slot, f] of Object.entries(fixtures)) {
+        const calls = [];
+        apps[slot] = {
+            nodeId: f.nodeId ?? `${slot}_node`,
+            applicationType: f.applicationType ?? `plugin_${slot}`,
+            calls,
+            state: async () => f.state ?? {},
+            db: f.db,
+            emit: async () => undefined,
+            call: async (tool, args) => {
+                calls.push({ tool, args });
+                const impl = f.tools?.[tool];
+                if (!impl)
+                    return { ok: false, text: `${slot} has no tool "${tool}"` };
+                return impl(args);
+            },
+        };
+    }
+    return apps;
+}
+/**
+ * Call `pluginServer.ops[name]` with a context shaped like the platform's.
+ * Throws whatever your op throws — including the platform's refusals, so
+ * `await expect(runOp(...)).rejects.toMatchObject({ code: "login-required" })`
+ * is how you prove the sign-in wall appears for the right person.
+ */
+export async function runOp(server, opName, options) {
+    const handler = server.ops?.[opName];
+    if (!handler) {
+        throw new Error(`pluginServer.ops has no "${opName}" — declared ops: ${Object.keys(server.ops ?? {}).join(", ") || "(none)"}`);
+    }
+    const notified = [];
+    const emitted = [];
+    const ctx = {
+        pluginId: options.pluginId ?? "app",
+        opName,
+        workspaceId: options.workspaceId ?? "ws_test",
+        nodeId: options.nodeId ?? "app_1",
+        instanceName: options.instanceName ?? "App 1",
+        cloudConnectionId: options.cloudConnectionId ?? null,
+        viewer: options.viewer,
+        args: options.args,
+        db: options.db,
+        apps: options.apps ?? {},
+        notify: async (topic, data, opts) => {
+            notified.push({ topic, data, ...(opts?.to !== undefined ? { to: opts.to } : {}) });
+            // A test may make notifying FAIL. Worth asking of any op that tells
+            // somebody after it has written something: a courtesy must not undo a
+            // completed write, and the only way to know is to break it on purpose.
+            if (options.notifyFails)
+                throw options.notifyFails(topic, opts?.to);
+        },
+        emit: async (eventName, eventData) => {
+            emitted.push({ eventName, eventData });
+        },
+    };
+    const result = (await handler(ctx));
+    return { result, notified, emitted };
+}
+/** A call recorder, for anything `runOp` does not already capture. */
+export function capture() {
+    const calls = [];
+    return {
+        calls,
+        fn: async (...args) => {
+            calls.push(args);
+        },
+    };
+}

package/dist/types.d.ts

@@ -146,9 +146,30 @@ export interface AppTaskContext<TState extends ApplicationIdentifier> {
     /** Inngest step API. RULE: every side effect goes inside a step.run. */
     step: any;
     logger: any;
+    /** Diagnostics: the last `getState()` read's cost split (import of the fold module vs the fold). */
+    timing: {
+        lastGetState?: {
+            importMs: number;
+            foldMs: number;
+            pingMs?: number;
+            region?: string;
+            at: number;
+        };
+    };
     getState(): Promise<TState>;
     dispatchEvent(eventName: string, eventData: any): Promise<void>;
-    notify(topic: string, data: any): Promise<void>;
+    /**
+     * Publish on one of your channel's topics. The topic's `audience` in your
+     * manifest decides who hears it; `to` aims it at one person or one role,
+     * which your own task always may (S8).
+     */
+    notify(topic: string, data: any, opts?: {
+        to?: {
+            viewerIds: string[];
+        } | {
+            role: string;
+        };
+    }): Promise<void>;
 }
 export interface AppTaskDefinition<TState extends ApplicationIdentifier> {
     /** Becomes the Inngest event `<applicationType>/<taskName>`. */

package/docs/04-tools.md

@@ -62,8 +62,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
 

package/docs/06-server.md

@@ -60,6 +60,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
@@ -76,3 +105,52 @@ Same-workspace only.
 Only `esoul-sdk` / `esoul-sdk/server`, relative files, `server-only`, and npm packages the
 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.

package/docs/07-background-tasks.md

@@ -47,12 +47,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

package/docs/10-testing.md

@@ -60,3 +60,21 @@ Once an app has real history, record it (`scripts/plugins/record-fold-corpus.mjs
 platform) and commit `fold-corpus.json` + hashes. From then on the checks refuse a change that
 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.

package/docs/12-rules.md

@@ -33,5 +33,6 @@
 - "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.