esoul-sdk 0.3.0 → 0.6.0

package/dist/server.js

@@ -8,6 +8,18 @@
  * Inside the host, `esoul-sdk/server` is aliased to the real
  * implementations.
  */
+/**
+ * WHO IS THIS, IN WORDS. The caller's own name and email, for an app with a
+ * reason to ask — a receipt, an address form they should not retype.
+ *
+ * SERVER ONLY, and only ever about the CALLER: there is no argument for whose
+ * profile to read, so an app cannot look up a person who is not talking to it.
+ * Null for anyone without an account. One database read: call it where you
+ * need it, not on every request.
+ */
+export function viewerProfile(_viewer) {
+    return hostOnly("viewerProfile");
+}
 const hostOnly = (name) => {
     throw new Error(`${name} runs only inside the ExternalSoul host (the app aliases esoul-sdk to its real implementations). In unit tests, mock this module.`);
 };
@@ -18,6 +30,22 @@ const hostOnly = (name) => {
 export function getPluginConnectionCredentials(_connectionId, _pluginId) {
     return hostOnly("getPluginConnectionCredentials");
 }
+/**
+ * The client for the tables YOUR manifest declared (`db`). Hand it any server
+ * context — an op's, a route's, a task's — and get back a client whose reads
+ * are already scoped to this instance and this caller, and whose writes refuse
+ * what the rules refuse. You write no access checks; you cannot forget one.
+ *
+ *   const db = await pluginDb<ShopDb>(ctx);          // ShopDb from ./.esoul/db
+ *   const mine = await db.order.findMany({ orderBy: { createdAt: "desc" } });
+ *
+ * `across: "owned-instances"` (the owner, across their shops) and `across:
+ * "my-rows"` (an account, across every instance) are read-only reaches.
+ * HOST-ONLY: in a unit test use `memoryDb(manifest)` from `esoul-sdk/testing`.
+ */
+export function pluginDb(_ctx, _reach) {
+    return hostOnly("pluginDb");
+}
 /**
  * Cross-app events: dispatch the TARGET app's own events through the
  * platform spine (target's dataCreator mints; triggers fire; every event is
@@ -56,3 +84,55 @@ export function pluginFiles(_ctx) {
 export function filesForOp(_ctx) {
     return hostOnly("filesForOp");
 }
+/**
+ * A Server-Sent Events response. `run` gets `send(event, data)` and the request's
+ * abort signal; return when done (or when the signal fires — the client left). A
+ * heartbeat comment every 15 s keeps proxies from closing an idle stream. Real code,
+ * not host-provided: streaming is the web platform's.
+ */
+export function sseStream(run, opts) {
+    const enc = new TextEncoder();
+    const ac = new AbortController();
+    opts?.signal?.addEventListener("abort", () => ac.abort(), { once: true });
+    const stream = new ReadableStream({
+        start(controller) {
+            let closed = false;
+            const write = (chunk) => {
+                if (closed)
+                    return;
+                try {
+                    controller.enqueue(enc.encode(chunk));
+                }
+                catch {
+                    closed = true;
+                }
+            };
+            const send = (event, data) => write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+            const beat = setInterval(() => write(": keep-alive\n\n"), Math.max(1_000, opts?.heartbeatMs ?? 15_000));
+            const finish = () => {
+                clearInterval(beat);
+                if (closed)
+                    return;
+                closed = true;
+                try {
+                    controller.close();
+                }
+                catch {
+                    /* already closed */
+                }
+            };
+            ac.signal.addEventListener("abort", finish, { once: true });
+            write(": open\n\n");
+            run(send, ac.signal).then(finish, (err) => {
+                send("error", { message: err instanceof Error ? err.message : String(err) });
+                finish();
+            });
+        },
+        cancel() {
+            ac.abort();
+        },
+    });
+    return new Response(stream, {
+        headers: { "Content-Type": "text/event-stream; charset=utf-8", "Cache-Control": "no-cache, no-transform", Connection: "keep-alive", "X-Accel-Buffering": "no" },
+    });
+}

package/dist/testing/db.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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;
+}): 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,94 @@
+/**
+ * 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] : []);
+    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/05-ui.md

@@ -63,6 +63,36 @@ The app renders inside the platform frame at any size: a desktop window, a maxim
 `look_at_app` in the workbench screenshots desktop-light, desktop-dark and phone-light. Open the
 images; a phone shot with a horizontal scrollbar is a bug.
 
+## Live data from a background task
+
+```tsx
+import { usePluginRealtime } from "esoul-sdk/react";
+import { kickPluginTask } from "esoul-sdk";
+import { stopwatchChannel } from "./channel";
+
+const live = usePluginRealtime<{ runId: string; elapsedMs: number; serverNow: number }>({
+  channel: stopwatchChannel,
+  workspaceId: state.workspaceId,
+  nodeId: state.nodeId,
+  topics: stopwatchChannel.topicNames,
+});
+// live.latestData → { topic: "tick", data: {...} } — the newest message, or null.
+// live.data       → everything received this mount, oldest first.
+
+const start = () =>
+  kickPluginTask({
+    applicationType: "plugin_stopwatch",
+    taskName: "tick",
+    identifier: state,
+    data: { runId, kickedAt: Date.now() },
+  });
+```
+
+The subscription is per instance and read-only; the token the platform mints for it carries only
+the topics your schema declares. Treat messages as nudges: what the UI must still show after a
+refresh comes from state, so a task that changes anything durable dispatches an event as well
+(docs/07 has the whole loop, including the stop).
+
 ## Cross-app from the UI
 
 ```ts

package/docs/06-server.md

@@ -76,3 +76,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

@@ -28,7 +28,8 @@ tasks: [
 - `ctx.getState()` — the app's state, fresh.
 - `ctx.dispatchEvent(eventName, eventData)` — through the full pipeline (append, fold, watermark),
   using YOUR processors, so a task's mutation is identical to a tap's.
-- `ctx.notify(topic, data)` — a realtime nudge to the app's channel; the UI refetches.
+- `ctx.notify(topic, data)` — publish on the app's realtime channel (see *Live tasks* below). A
+  nudge, never the truth: the UI hears it while mounted; a refresh only sees the timeline.
 - `ctx.logger`.
 
 ## The replay model — read this twice
@@ -42,14 +43,39 @@ replay; mint them inside. Step names are unique per logical operation; loops inc
 ## How a task gets kicked
 
 - **From a webhook**: `ctx.sendInngestEvent("<applicationType>/<task>", payload)` (docs/06).
-- **From the browser**: list the task in `kickableTasks`; the UI posts the event through the
-  platform's send-event route, which allows only listed tasks.
+- **From the browser or a tool**: list the task in `kickableTasks`, then
+  `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.