esoul-sdk 0.3.0

package/docs/10-testing.md

@@ -0,0 +1,62 @@
+# 10. Testing — the fold contract as tests
+
+The workbench runs your tests with jest (`test_app`, seconds; `check_app` adds the platform's
+suites and a type check). Write the contract the reviewer wants to trust:
+
+```ts
+import { noteAddedEvent, noteTextSetEvent, pluginSchema, type StickyNotesData } from "./app";
+
+const IDENT = { workspaceId: "ws1", nodeId: "node1", applicationType: "plugin_sticky_notes", instanceName: "My wall" };
+const fresh = (): StickyNotesData => pluginSchema.stateCreator(IDENT as any, {} as any);
+const apply = (def: any, s: StickyNotesData, args: Record<string, any> = {}) => def.processor(s, def.dataCreator({ ...IDENT, ...args }));
+
+it("starts empty, adds exactly what it says, and a replay is a no-op", () => {
+  expect(fresh().notes).toEqual([]);
+  const once = apply(noteAddedEvent, fresh(), { noteId: "n1", text: "milk" });
+  const ev = noteAddedEvent.dataCreator({ ...IDENT, noteId: "n1", text: "milk" });
+  const twice = noteAddedEvent.processor(noteAddedEvent.processor(fresh(), ev), ev);
+  expect(once.notes.map((n) => n.id)).toEqual(["n1"]);
+  expect(twice).toEqual(noteAddedEvent.processor(fresh(), ev));
+});
+
+it("refuses a payload it cannot trust, and ignores an unknown id", () => {
+  expect(noteAddedEvent.processor(fresh(), { eventData: { noteId: 42 } } as any)).toEqual(fresh());
+  expect(apply(noteTextSetEvent, fresh(), { noteId: "ghost", text: "x" })).toEqual(fresh());
+});
+
+it("no processor mints an id or a time: two folds of one log are identical", () => {
+  const log = [noteAddedEvent.dataCreator({ ...IDENT, noteId: "n1", text: "a" }), noteTextSetEvent.dataCreator({ ...IDENT, noteId: "n1", text: "b" })];
+  const fold = () => log.reduce((s, e) => (e.eventName === noteAddedEvent.eventName ? noteAddedEvent : noteTextSetEvent).processor(s, e as any), fresh());
+  expect(fold()).toEqual(fold());
+});
+
+it("the description never claims an emptiness it could not read", () => {
+  expect(pluginSchema.getStateDescription({ ...IDENT } as any)).toMatch(/not loaded|incomplete/i);
+  expect(pluginSchema.getStateDescription(fresh())).toContain("No notes yet");
+});
+```
+
+A UI test renders once with a fixed state and checks the visible chrome and the empty state.
+Keep suites fast; they run beside the live preview on the same machine.
+
+## Tools
+
+Call `execute` with a recording `eventCallback` and assert the events it emitted and the text it
+returned — including the refusal text for a bad id.
+
+## Tasks
+
+Fake the context: `step.run` that calls its function, a recording `dispatchEvent`. Run the
+handler twice with the same `eventData`; the second run must not add a second item.
+
+## Connections
+
+`esoul-sdk/testing` ships `startMockOAuth()` — a local OAuth server that issues, refreshes and
+revokes tokens, so a connection-backed op can be tested end to end without a real provider.
+
+## The fold corpus
+
+Once an app has real history, record it (`scripts/plugins/record-fold-corpus.mjs` in the
+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.

package/docs/11-shipping.md

@@ -0,0 +1,70 @@
+# 11. Shipping — submit, review, release, install
+
+## The path
+
+1. **Build and test in the Forge workbench** (docs/01). No repository access is needed: the
+   platform clones with its own installation for the app arm.
+2. **Submit** with `ship_app`. It refuses unless every check is green, commits, pushes the app's
+   branch and opens (or updates) a pull request labelled `user-app` and `submitted-by:<you>`.
+   The board shows "submitted — awaiting review". An app id already on the base branch under
+   another author is refused before a pull request exists — pick another id.
+3. **The owner reviews** the diff on GitHub and approves.
+4. **One script releases it**: checks the pull request out cleanly, runs the import wall, the
+   sync, your tests and the type check, merges any dependencies you declared onto your branch so
+   the reviewer sees them, squash-merges, waits for the production deploy, grants you the
+   entitlement, and tells your board "released — add it to a workspace".
+5. **Add it** in any of your workspaces from the app picker, by chat (`add_app`), or over MCP.
+   Its tools are live in chat, voice, agents and MCP; its events ride the timeline.
+
+## The import wall
+
+Review is the security boundary — your server code will run with the platform's credentials.
+Review is only tractable if nothing can reach around the SDK, so the wall refuses at check time,
+at sync and at release:
+
+- allowed: `esoul-sdk` (and `/server`, `/react`, `/testing`), relative files in your folder,
+  `server-only`, npm packages the platform already depends on;
+- refused: `@/…` platform internals, `node:*` and the node built-ins, `prisma`, `next`,
+  `inngest`, the Vercel SDKs, and any package not in the platform's `package.json`.
+
+Need something the SDK lacks? Ask for it in the SDK — that is the review's pressure valve. Need
+an npm package? Declare it (below); it becomes a visible line in the pull request.
+
+## Declaring npm dependencies
+
+Put a `package.json` in your app folder with only `dependencies`:
+
+```json
+{ "dependencies": { "date-fns": "^4.1.0" } }
+```
+
+The release script merges them into the platform's `package.json`, updates the lockfile on your
+branch, and pushes that commit onto your pull request before merging. In the workbench the
+package is not yet installed until that happens; a later platform version merges declared
+dependencies at `open`.
+
+## Entitlement — your app on your instance
+
+A released app is available to **its submitter** and to no one else until the owner grants
+everyone (`--public`). A plugin that predates entitlements stays public. The picker only offers
+what you may add; the add path enforces it.
+
+## Versions and upgrades
+
+Bump `version` on every submission. Events are forever: a change that alters what an existing
+event MEANS rewrites every workspace's history on the next fold — record a fold corpus (docs/10)
+so the checks catch it, and treat such a change as a migration with its own events.
+
+## Dev and deployed are symmetric
+
+In the workbench your app can already call other apps (through the board's tab) and its own
+tools can be called (`call_app_tool`) before install. Installed, the same calls go through the
+manifest's grants, and the platform mints your tools natively. Exposing an in-development app's
+tools to the whole workspace — so chat could call them before install — is the next step on
+the platform's side (the board minting proxy tools per app under construction).
+
+## Cost and lifetime
+
+A workbench dies ten minutes after the last touch (a tool call, or a board tab watching it).
+`close_workbench` stops it at once. Files and commits persist; reopening resumes and updates the
+platform it runs on.

package/docs/12-rules.md

@@ -0,0 +1,37 @@
+# 12. Rules and failures — every rule with the failure that earned it
+
+| Rule | The failure it prevents |
+|---|---|
+| Processors are pure and idempotent | a replay duplicated items; a scrub showed a state that never existed |
+| Ids and timestamps are minted in `dataCreator`, never in a processor | two folds of one log disagreed; snapshots diverged from replay |
+| A processor refuses a bad payload instead of throwing | one malformed webhook took a whole workspace view down |
+| Whole-replace and burst events carry a collapse key per entity and field | fifty timeline rows per sentence; two notes edited together merged into one |
+| `reconstructStateFromEventLog: true` | an app hydrated from a stale column and lost its last edits |
+| `getStateDescription` uses `incompleteStateNotice`; missing ≠ empty | an agent "saw" an empty list, invited a duplicate, and the notebook crashed on a throw |
+| Every tool has a real `onClient` (`= execute`) | the voice agent said "added the note" while nothing ran — an empty stub reads as success |
+| Tool results say what was DONE, refuse what was not | "updated" for an id that did not exist |
+| Server truth through a plugin op, never `fetch("/api/v1/…")` | the token-gated route refused the tool with "not readable" |
+| Cross-app calls only through `useWorkspaceTools` / `callWorkspaceTool` with manifest grants | an app could act on any app in the workspace unseen |
+| Server code reaches the platform only through `esoul-sdk/server` (the import wall) | a demo plugin read the database directly; a reviewer would have had to read every line |
+| Webhooks verify, validate, kick a task, ACK; idempotent by the sender's key | a retried push duplicated an item; a slow webhook timed out mid-work |
+| Every task side effect lives in a `step.run` | a dispatch fired four times, once per replay |
+| No per-app crons; `pollTasks` at 5-minute granularity | Inngest function ids and the plan's concurrency cap |
+| Secrets are env-variable NAMES in the manifest, never values | a client secret in a package that becomes public |
+| The schema module is never `"use client"` | the schema became a server proxy and every processor vanished at build |
+| The UI never imports the store or the registry, only `esoul-sdk/react` | a module cycle that crashed the client on load |
+| Root fills the frame, `overflow:hidden`, content `flex:1 minHeight:0` | the whole app scrolled sideways on a phone |
+| Measure the visible scroller, not the canvas | a 2400 px canvas laid new notes off the right edge |
+| Observe `.dark` at runtime | wrong colours until the person clicked something |
+| Bound every collection and string | an app that could no longer be folded |
+| Bump the manifest version; record a fold corpus once there is data | a "small" event change rewrote every workspace's history |
+
+## Symptom → rule
+
+- "It works in the preview and nothing changes after install" → the tool only had `onClient`, or
+  the event was `Server`-typed and dispatched from the UI.
+- "The timeline has hundreds of rows for one edit" → no collapse key.
+- "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.