esoul-sdk 0.4.0 → 0.7.0

package/README.md

@@ -1,61 +1,183 @@
 # 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.

package/dist/audience.d.ts

@@ -0,0 +1,103 @@
+/**
+ * WHO HEARS A MESSAGE.
+ *
+ * An app's realtime channel is one per instance, and until now every viewer
+ * who could reach the app held a token for all of it: a shop publishing
+ * "order 91 is on its way" reached every customer watching, with the order id
+ * and whatever else the app put in the payload. The rules made the DATABASE
+ * private per customer and the transport stayed a loudspeaker.
+ *
+ * So a topic declares its AUDIENCE, and the audience decides the channel:
+ *
+ *   all            one channel for the instance — a catalogue change, a tick
+ *   viewer         one channel per person — "your order shipped"
+ *   role:<name>    one channel per role — "a new order arrived", for staff
+ *
+ * A token is minted per channel, so a customer is never handed the staff
+ * channel or another customer's: not filtered out on arrival, never issued.
+ *
+ * And ADDRESSING is a separate permission from hearing. `notify(topic, data,
+ * { to })` lets a caller aim a message; without a rule, a customer's op could
+ * aim one at another customer. So: a non-internal caller may address only
+ * ITSELF, unless the topic's `mayAddress` names its role. That is invariant
+ * S7 of the security pass, and `decideDestination` is where it lives.
+ *
+ * Pure — no transport, no platform. The mint calls `subscriptionsFor`, the
+ * server's `notify` calls `decideDestination`, and the workbench calls both,
+ * so a box shows an author exactly what an installed app will do.
+ */
+/** `all` (default) · `viewer` · `role:<name>`. */
+export type TopicAudience = "all" | "viewer" | `role:${string}`;
+export interface TopicDecl {
+    audience?: TopicAudience;
+    /**
+     * Roles that may address this topic AT SOMEONE ELSE (`to: { role }` or
+     * another viewer's ids). The app's own server code running internally
+     * always may; nobody else does unless named here.
+     */
+    mayAddress?: string[];
+}
+export type ChannelAudience = {
+    kind: "all";
+} | {
+    kind: "viewer";
+    viewerId: string;
+} | {
+    kind: "role";
+    role: string;
+};
+/** What `notify`'s caller asked for. Absent = the topic's own audience, aimed at the caller. */
+export type NotifyTarget = {
+    viewerIds: string[];
+} | {
+    role: string;
+} | "apps";
+export declare class AudienceError extends Error {
+    readonly code: "forbidden";
+    constructor(message: string);
+}
+/** The viewer facts this module needs — the shape `PluginViewer` already has. */
+export interface AudienceViewer {
+    kind: string;
+    userId: string | null;
+    viewerIds: string[];
+    role: string;
+}
+export declare function audienceOf(decl: TopicDecl | undefined): TopicAudience;
+/**
+ * The id a person's own channel is keyed on. A signed-in account first, so
+ * the channel survives a new browser and a new guest cookie; otherwise the
+ * first viewer id, which is the guest cookie.
+ *
+ * KNOWN LIMIT, on purpose: someone who ordered as a guest and then signed in
+ * listens on their ACCOUNT's channel, while a message addressed at the order's
+ * stored `ownerId` (the guest id) goes to the guest channel they no longer
+ * hold. They see the change when the list re-reads — the database is the
+ * truth and realtime is the nudge — and nobody else ever hears it either.
+ */
+export declare function ownChannelId(viewer: AudienceViewer): string | null;
+/**
+ * Every channel this viewer may hold a token for, with the topics to ask for
+ * on each. Topics whose audience no channel of this viewer can carry are
+ * simply absent — an anonymous viewer gets no `role:` channel, and a viewer
+ * with no id at all gets no personal one.
+ */
+export declare function subscriptionsFor(topics: Record<string, TopicDecl | undefined>, viewer: AudienceViewer): {
+    audience: ChannelAudience;
+    topics: string[];
+}[];
+/**
+ * Where one `notify` lands — one channel per addressee — or a refusal.
+ *
+ * Unaddressed, a message goes where the topic says: the instance channel for
+ * `all`, the CALLER's own channel for `viewer`, the topic's role for `role:`.
+ * Addressed, the caller must be allowed to aim it.
+ */
+export declare function decideDestination(args: {
+    topic: string;
+    decl: TopicDecl | undefined;
+    viewer: AudienceViewer;
+    to?: NotifyTarget;
+}): ChannelAudience[];
+/** The channel name for an instance and an audience — the one spelling, both sides. */
+export declare function channelName(base: string, audience: ChannelAudience): string;

package/dist/audience.js

@@ -0,0 +1,142 @@
+/**
+ * WHO HEARS A MESSAGE.
+ *
+ * An app's realtime channel is one per instance, and until now every viewer
+ * who could reach the app held a token for all of it: a shop publishing
+ * "order 91 is on its way" reached every customer watching, with the order id
+ * and whatever else the app put in the payload. The rules made the DATABASE
+ * private per customer and the transport stayed a loudspeaker.
+ *
+ * So a topic declares its AUDIENCE, and the audience decides the channel:
+ *
+ *   all            one channel for the instance — a catalogue change, a tick
+ *   viewer         one channel per person — "your order shipped"
+ *   role:<name>    one channel per role — "a new order arrived", for staff
+ *
+ * A token is minted per channel, so a customer is never handed the staff
+ * channel or another customer's: not filtered out on arrival, never issued.
+ *
+ * And ADDRESSING is a separate permission from hearing. `notify(topic, data,
+ * { to })` lets a caller aim a message; without a rule, a customer's op could
+ * aim one at another customer. So: a non-internal caller may address only
+ * ITSELF, unless the topic's `mayAddress` names its role. That is invariant
+ * S7 of the security pass, and `decideDestination` is where it lives.
+ *
+ * Pure — no transport, no platform. The mint calls `subscriptionsFor`, the
+ * server's `notify` calls `decideDestination`, and the workbench calls both,
+ * so a box shows an author exactly what an installed app will do.
+ */
+export class AudienceError extends Error {
+    code = "forbidden";
+    constructor(message) {
+        super(message);
+        this.name = "AudienceError";
+    }
+}
+export function audienceOf(decl) {
+    const a = decl?.audience;
+    if (a === "viewer")
+        return "viewer";
+    if (typeof a === "string" && a.startsWith("role:") && a.length > 5)
+        return a;
+    return "all";
+}
+/**
+ * The id a person's own channel is keyed on. A signed-in account first, so
+ * the channel survives a new browser and a new guest cookie; otherwise the
+ * first viewer id, which is the guest cookie.
+ *
+ * KNOWN LIMIT, on purpose: someone who ordered as a guest and then signed in
+ * listens on their ACCOUNT's channel, while a message addressed at the order's
+ * stored `ownerId` (the guest id) goes to the guest channel they no longer
+ * hold. They see the change when the list re-reads — the database is the
+ * truth and realtime is the nudge — and nobody else ever hears it either.
+ */
+export function ownChannelId(viewer) {
+    return viewer.userId ?? viewer.viewerIds[0] ?? null;
+}
+/**
+ * Every channel this viewer may hold a token for, with the topics to ask for
+ * on each. Topics whose audience no channel of this viewer can carry are
+ * simply absent — an anonymous viewer gets no `role:` channel, and a viewer
+ * with no id at all gets no personal one.
+ */
+export function subscriptionsFor(topics, viewer) {
+    const all = [];
+    const own = [];
+    const byRole = [];
+    for (const name of Object.keys(topics)) {
+        const a = audienceOf(topics[name]);
+        if (a === "all")
+            all.push(name);
+        else if (a === "viewer")
+            own.push(name);
+        else if (a === `role:${viewer.role}`)
+            byRole.push(name);
+    }
+    const out = [];
+    if (all.length)
+        out.push({ audience: { kind: "all" }, topics: all });
+    const id = ownChannelId(viewer);
+    if (own.length && id)
+        out.push({ audience: { kind: "viewer", viewerId: id }, topics: own });
+    if (byRole.length)
+        out.push({ audience: { kind: "role", role: viewer.role }, topics: byRole });
+    return out;
+}
+/**
+ * Where one `notify` lands — one channel per addressee — or a refusal.
+ *
+ * Unaddressed, a message goes where the topic says: the instance channel for
+ * `all`, the CALLER's own channel for `viewer`, the topic's role for `role:`.
+ * Addressed, the caller must be allowed to aim it.
+ */
+export function decideDestination(args) {
+    const { topic, decl, viewer, to } = args;
+    const audience = audienceOf(decl);
+    const internal = viewer.kind === "internal";
+    const mayAddressOthers = internal || (decl?.mayAddress ?? []).includes(viewer.role);
+    if (to === "apps") {
+        // Reserved for S9's bindings; nothing consumes it yet, and a caller that
+        // asks for it now should hear so rather than have it quietly ignored.
+        throw new AudienceError(`\`to: "apps"\` needs bindings (S9); topic "${topic}" cannot address other apps yet`);
+    }
+    if (!to) {
+        if (audience === "all")
+            return [{ kind: "all" }];
+        if (audience === "viewer") {
+            const id = ownChannelId(viewer);
+            if (!id)
+                throw new AudienceError(`topic "${topic}" is per-viewer and this caller has no identity to address`);
+            return [{ kind: "viewer", viewerId: id }];
+        }
+        return [{ kind: "role", role: audience.slice("role:".length) }];
+    }
+    if ("role" in to) {
+        if (!mayAddressOthers) {
+            throw new AudienceError(`${viewer.role} may not address the "${to.role}" desk on topic "${topic}" — list it in channel.topics["${topic}"].mayAddress`);
+        }
+        return [{ kind: "role", role: to.role }];
+    }
+    const ids = [...new Set(to.viewerIds.filter(Boolean))];
+    if (!ids.length)
+        throw new AudienceError(`topic "${topic}" was addressed at nobody`);
+    if (!mayAddressOthers) {
+        // The one case a plain caller may address: itself. Anything else is how a
+        // customer would push a message into another customer's channel.
+        const mine = new Set(viewer.viewerIds);
+        const strangers = ids.filter((id) => !mine.has(id));
+        if (strangers.length) {
+            throw new AudienceError(`${viewer.role} may address only itself on topic "${topic}" — list the role in channel.topics["${topic}"].mayAddress to let it address others`);
+        }
+    }
+    return ids.map((viewerId) => ({ kind: "viewer", viewerId }));
+}
+/** The channel name for an instance and an audience — the one spelling, both sides. */
+export function channelName(base, audience) {
+    if (audience.kind === "all")
+        return base;
+    if (audience.kind === "viewer")
+        return `${base}:v:${audience.viewerId}`;
+    return `${base}:r:${audience.role}`;
+}

package/dist/bindings.d.ts

@@ -0,0 +1,164 @@
+/**
+ * WHAT STANDS BEHIND A SLOT.
+ *
+ * An app is an island until it can lean on another one. A storefront that
+ * wants real stock either keeps its own products table and guesses, or names
+ * a specific inventory app and is married to it forever. Neither is what a
+ * person means when they say "use my warehouse for this shop".
+ *
+ * So an app declares a SLOT and the CONTRACT it needs:
+ *
+ *   "uses": { "stock": { "contract": "stock/v1", "label": "Stock" } }
+ *
+ * and any app that can do the job declares that it does:
+ *
+ *   "provides": { "stock/v1": { "tools": ["reserve_stock"], "events": ["stock_low"], "models": ["Product"] } }
+ *
+ * The owner picks which app fills the slot, and the platform checks — at BIND
+ * time, once, loudly — that the provider really has every tool, event and
+ * table the contract names. Not at call time, where a missing tool is an
+ * error in front of a customer.
+ *
+ * Versions grow by ADDING. A provider on `stock/v2` satisfies a consumer
+ * asking for `stock/v1`, because v2 still has everything v1 named; the
+ * reverse is refused, because v1 has never heard of what v2 added. That one
+ * rule is what lets a storefront keep working while its provider moves on.
+ *
+ * Pure: no platform, no transport. The bind-time check, the workbench picker
+ * and the author's own tests all read this.
+ */
+export interface ContractId {
+    /** `stock` in `stock/v1`. */
+    name: string;
+    /** `1` in `stock/v1`. */
+    version: number;
+}
+/** What a contract REQUIRES of whoever claims it. The platform ships these; an app may publish its own. */
+export interface ContractDef {
+    id: string;
+    /** One line, shown in the picker. */
+    describe?: string;
+    tools: string[];
+    events: string[];
+    models: string[];
+}
+/** What one app says it offers for one contract. */
+export interface ProvidesDecl {
+    tools?: string[];
+    events?: string[];
+    models?: string[];
+}
+/** A slot an app needs filled. */
+export interface UsesDecl {
+    contract: string;
+    label?: string;
+    /** An unfilled required slot is a refusal at the seam (`not-bound`); an optional one is simply absent. */
+    optional?: boolean;
+}
+/** What a candidate app ACTUALLY has, read from its manifest and registry — never from its claims. */
+export interface ProviderFacts {
+    applicationType: string;
+    /** Tool VERBS the app mints (`reserve_stock`, not `reserve_stock_<instance>`). */
+    tools: string[];
+    /** Event names the app declares. */
+    events: string[];
+    /** Table names in the app's `db`. */
+    models: string[];
+    /** The `provides` block from its manifest. */
+    provides: Record<string, ProvidesDecl>;
+}
+export declare function parseContractId(raw: string): ContractId | null;
+export declare function formatContractId(c: ContractId): string;
+export type BindCheck = {
+    ok: true;
+    via: string;
+    tools: string[];
+    events: string[];
+    models: string[];
+} | {
+    ok: false;
+    reasons: string[];
+};
+/**
+ * May this app fill this slot? Every reason it may not, in the author's
+ * words — a picker shows them, and a bind refuses on any of them.
+ *
+ * `contract` is the DEFINITION (what the contract requires). `facts` is what
+ * the candidate app really has. A provider's own `provides` block is a claim,
+ * and a claim is checked against both.
+ */
+export declare function checkBinding(args: {
+    wanted: string;
+    contract: ContractDef | null;
+    facts: ProviderFacts;
+}): BindCheck;
+export interface Binding {
+    /** The provider instance. */
+    nodeId: string;
+    applicationType: string;
+    /** The contract id it was bound through — what the consumer may reach. */
+    via: string;
+    boundAt?: number;
+}
+/** slot → binding. The consumer app's own state holds this. */
+export type BindingMap = Record<string, Binding>;
+/**
+ * The reducer behind `plugin/binding_set`. Deterministic: setting a slot
+ * replaces it, binding an empty nodeId clears it, and an unknown slot is
+ * ignored rather than invented — the slots are the manifest's, not the
+ * event's.
+ */
+export declare function reduceBinding(current: BindingMap, event: {
+    slot?: unknown;
+    nodeId?: unknown;
+    applicationType?: unknown;
+    via?: unknown;
+    at?: unknown;
+}, knownSlots: readonly string[]): BindingMap;
+/** The slots a manifest declares that nothing fills yet — the ones a seam refuses on. */
+export declare function unfilledRequiredSlots(uses: Record<string, UsesDecl>, bindings: BindingMap): string[];
+/**
+ * WHERE A BINDING LIVES: on the consumer app's own timeline, folded under
+ * `_bindings`.
+ *
+ * It could have been a column. It is an event because a binding is the
+ * OWNER'S CONSENT — "this shop may reach that warehouse" — and consent that
+ * is only a column cannot be scrubbed, explained or audited. On the timeline
+ * it can: who bound it, when, through which contract, and what it replaced.
+ *
+ * An app that declares `uses` must put this in its `events`; the sync refuses
+ * one that does not, because a slot nothing can fill is a promise the app
+ * cannot keep.
+ */
+export interface BindingHolder {
+    _bindings?: BindingMap;
+}
+export declare function bindingEventName(applicationType: string): string;
+/**
+ * The event definition for one app's slots. `knownSlots` comes from the
+ * manifest, so an event naming a slot the app never declared is ignored
+ * rather than inventing one.
+ *
+ * Typed loosely on purpose: the SDK's `EventDefinition` lives in `types.ts`
+ * and this module stays free of it, so the same file can be read by the
+ * platform, the workbench and an author's tests without dragging the schema
+ * types along.
+ */
+export declare function defineBindingEvent<S extends BindingHolder>(args: {
+    applicationType: string;
+    slots: readonly string[];
+}): {
+    eventName: string;
+    type: "Client";
+    triggerMeta: {
+        displayName: string;
+        description: string;
+        sampleVariables: string[];
+    };
+    dataCreator: (a: Record<string, unknown>) => Record<string, unknown>;
+    processor: (state: S, event: {
+        eventData?: Record<string, unknown>;
+    }) => S;
+};
+/** The bindings an app currently holds, from its folded state. */
+export declare function bindingsOf(state: BindingHolder | null | undefined): BindingMap;