esoul-sdk 0.3.0 → 0.6.0

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.

package/docs/13-people-and-access.md

@@ -0,0 +1,148 @@
+# 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.
+
+## 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.

package/docs/14-database.md

@@ -0,0 +1,115 @@
+# 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.
+
+## 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.

package/docs/15-realtime.md

@@ -0,0 +1,88 @@
+# 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.

package/docs/16-bindings.md

@@ -0,0 +1,79 @@
+# 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.