esoul-sdk 0.7.0 → 0.16.0

package/api-reference.md

@@ -0,0 +1,3291 @@
+# esoul-sdk — API reference (generated)
+
+Every export of every entry point, with its signature and the first paragraph of its doc comment,
+read from the TypeScript source by the compiler. The prose guide is llms-full.txt (docs/); this is
+the complete list it teaches from. In a Forge workbench the source itself is readable:
+`wb.read_platform("packages/esoul-sdk/src/<file>")` / `wb.search(name, scope="sdk")`.
+Regenerate: `npm run docs:api`.
+
+==============================================================================
+## `esoul-sdk` — 185 exports
+
+Manifest, events, tools, ops, bindings, contracts, charts, access words — what app.tsx and the shared modules import.
+
+### Functions and values (109)
+
+#### `ASSET_APP_MAX_BYTES` — const · src/assets.ts
+
+The most one app's assets may add up to (summed from its manifest).
+
+```ts
+const ASSET_APP_MAX_BYTES: number
+```
+
+#### `ASSET_INLINE_MAX_BYTES` — const · src/assets.ts
+
+Inline base64 in a tool argument stays small: a model cannot emit more reliably.
+
+```ts
+const ASSET_INLINE_MAX_BYTES: number
+```
+
+#### `ASSET_MAX_BYTES` — const · src/assets.ts
+
+A single asset may be a film; an app may be a small site's worth of them. Owner-billed storage.
+
+```ts
+const ASSET_MAX_BYTES: number
+```
+
+#### `ASSET_TYPES` — const · src/assets.ts
+
+What may be served as an asset — media and fonts, never scripts, never HTML.
+
+```ts
+const ASSET_TYPES: Readonly<Record<string, string>>
+```
+
+#### `assetExt` — function · src/assets.ts
+
+The extension of an asset name, lower-case, or null when the name is not an asset name.
+
+```ts
+function assetExt(name: string): string | null
+```
+
+#### `assetObject` — function · src/assets.ts
+
+The object an asset is stored and served as: `<sha256>.<ext>`.
+
+```ts
+function assetObject(sha256: string, ext: string): string
+```
+
+#### `assetPath` — function · src/assets.ts
+
+The public, immutable, same-origin address of an object.
+
+```ts
+function assetPath(pluginId: string, sha256: string, ext: string): string
+```
+
+#### `assetsTotalBytes` — function · src/assets.ts
+
+The bytes an app's assets add up to — what the per-app cap is measured against.
+
+```ts
+function assetsTotalBytes(assets: AssetsManifest | null | undefined): number
+```
+
+#### `assetUrl` — function · src/assets.ts
+
+The URL an app renders for one of its assets. NEVER throws (2026-09-24): an unknown name used to throw "a missing asset is a bug", and the homepage went down whole when a visitor opened an app whose film had not been recorded yet — a render-time throw takes the page with it. Now an unknown name logs once (the author sees it in the console and the Forge's journal) and returns an address that answers 404, so an `<img>` is simply empty and its `onError` fires. For an asset that may legitimately be absent, use `assetUrlOrNull` and render a fallback.
+
+```ts
+function assetUrl(assets: AssetsManifest, name: string): string
+```
+
+#### `assetUrlOrNull` — function · src/assets.ts
+
+Like `assetUrl` for an OPTIONAL asset: null instead of a throw.
+
+```ts
+function assetUrlOrNull(assets: AssetsManifest, name: string): string | null
+```
+
+#### `ATTR_TYPES` — const · src/db/custom-roles.ts
+
+The types a role attribute may declare in `roles.attributes`.
+
+```ts
+const ATTR_TYPES: readonly AttrType[]
+```
+
+#### `attrProblem` — function · src/db/custom-roles.ts
+
+Why a grant's attribute is refused, or null. For the owner who is typing it.
+
+```ts
+function attrProblem(types: Record<string, AttrType>, name: string, raw: unknown): string | null
+```
+
+#### `AudienceError` — class · src/audience.ts
+
+A publish aimed at viewers the topic's audience does not allow — refused with code `forbidden`.
+
+```ts
+class AudienceError extends Error { … }
+```
+
+#### `audienceOf` — function · src/audience.ts
+
+The audience a realtime topic declares — `"viewer"`, `"role:<name>"`, or `"all"` when it declares none.
+
+```ts
+function audienceOf(decl: TopicDecl | undefined): TopicAudience
+```
+
+#### `bindingEventName` — function · src/bindings.ts
+
+The event a consumer app records a binding on (`<applicationType>_binding_set`) — put it in your `events` when you declare `uses`.
+
+```ts
+function bindingEventName(applicationType: string): string
+```
+
+#### `bindingsOf` — function · src/bindings.ts
+
+The bindings an app currently holds, from its folded state.
+
+```ts
+function bindingsOf(state: BindingHolder | null | undefined): BindingMap
+```
+
+#### `callPluginOp` — function · src/helpers.ts
+
+Call one of your app's server ops from the UI or a tool: POSTs `{nodeId, args}` to the op's route (the installed app's `/api/plugins/<id>/op/<op>`, or the Forge preview's own route) with the session, the share and the VIEW AS persona the page carries, and returns the op's result — or throws the op's refusal with its code.
+
+```ts
+async function callPluginOp<T = unknown>( pluginId: string, op: string, nodeId: string, args?: unknown, ): Promise<T>
+```
+
+#### `channelName` — function · src/audience.ts
+
+The channel name for an instance and an audience — the one spelling, both sides.
+
+```ts
+function channelName(base: string, audience: ChannelAudience): string
+```
+
+#### `chartSvg` — function · src/chart.ts
+
+A chart as one SVG string from a spec (panels of series, markers, tones): the same picture for the app's screen (`dangerouslySetInnerHTML`) and, rendered with `renderChartImage` on the server, for a tool's answer. Text is drawn as glyph outlines, so it needs no fonts where it is rasterised.
+
+```ts
+function chartSvg(spec: ChartSpec): string
+```
+
+#### `checkBinding` — function · src/bindings.ts
+
+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.
+
+```ts
+function checkBinding(args: { wanted: string; contract: ContractDef | null; facts: ProviderFacts }): BindCheck
+```
+
+#### `coerceAttr` — function · src/db/custom-roles.ts
+
+One attribute value from what a person typed, or `undefined` when it is not one of that type.
+
+```ts
+function coerceAttr(type: AttrType, raw: unknown): AttrValue | undefined
+```
+
+#### `coerceAttrs` — function · src/db/custom-roles.ts
+
+Every declared attribute a grant carries, typed; an undeclared or ill-typed one is dropped (a missing attribute fails closed downstream).
+
+```ts
+function coerceAttrs(types: Record<string, AttrType>, raw: Record<string, unknown> | undefined | null): Record<string, AttrValue>
+```
+
+#### `compareFileNames` — function · src/files.ts
+
+Natural name order: "frame_2" before "frame_10".
+
+```ts
+function compareFileNames(a: string, b: string): number
+```
+
+#### `compileCustomRole` — function · src/db/custom-roles.ts
+
+Compile one composed role against the envelope and the vocabulary. Every refusal names the key and the allowed values — this runs where an OWNER is typing, and a precise sentence is the whole product.
+
+```ts
+function compileCustomRole(raw: CustomRoleDefinitionRaw, envelope: CustomRolesEnvelope | null, vocabulary: string[]): CompiledCustomRole
+```
+
+#### `compileEnvelope` — function · src/db/custom-roles.ts
+
+Validate the envelope against the models it names. `modelFields` maps a model name to its declared fields; `filterable` to the fields a query may name — a `where` on an unindexed field would be a table scan at a customer's scale, so it is refused at build time with the index to add.
+
+```ts
+function compileEnvelope( raw: CustomRolesEnvelopeRaw | undefined, models: Record<string, { fields: string[]; filterable: string[] }>, surfaces: string[], /** `roles.attributes` — every declared attribute may scope a composed role too. */ declared: Record<string, AttrType> = {}, ): CustomRolesEnvelope | null
+```
+
+#### `currentShareId` — function · src/helpers.ts
+
+The public share this page is being viewed through, or null.
+
+```ts
+function currentShareId(): string | null
+```
+
+#### `CustomRoleError` — class · src/db/custom-roles.ts
+
+A composed role (`roles.custom`) that does not compile — carries the path of the offending part (`….models.orders.read`) and what is wrong with it.
+
+```ts
+class CustomRoleError extends Error { … }
+```
+
+#### `decideDestination` — function · src/audience.ts
+
+Where one `notify` lands — one channel per addressee — or a refusal.
+
+```ts
+function decideDestination(args: { topic: string; decl: TopicDecl | undefined; viewer: AudienceViewer; to?: NotifyTarget; }): ChannelAudience[]
+```
+
+#### `decideReconcile` — function · src/editor-sync.ts
+
+What a mounted editor should do with the value the store now holds for the item it edits: echo, converged, stale-own, merge, wait-save, wait-idle or adopt (the rules above, in that order). Pure. `useRemoteReconcile` in esoul-sdk/react calls it for you; call it directly only to test your own adapter.
+
+```ts
+function decideReconcile<T>(args: { incoming: T; /** What the editor last knew the server to hold (its merge base). */ base: T | undefined; /** What the editor shows right now. */ current: T; equal: (a: T, b: T) => boolean; /** A local save is scheduled and not yet dispatched. */ pending: boolean; /** The user is in the middle of editing (focus, an open field). */ editing: boolean; /** isOlderOwnWrite(...) for the incoming state. */ olderOwn: boolean; /** The editor supplies a three-way merge. */ canMerge: boolean; /** May a merge be applied while the person is editing? Default true. An editor that can only apply by * replacing its whole surface (an input in progress would be lost) sets false: it merges once idle. */ mergeWhileEditing?: boolean; }): ReconcileDecision
+```
+
+#### `defineBindingEvent` — function · src/bindings.ts
+
+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.
+
+```ts
+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; }
+```
+
+#### `defineOps` — function · src/ops.ts
+
+Declare every op's input. Returns what it was given, typed, after refusing a name the manifest's grammar would refuse and a schema that is not an object.
+
+```ts
+function defineOps<T extends OpInputs>(inputs: T): T
+```
+
+#### `definePluginChannel` — function · src/index.ts
+
+Declare an app's realtime channel — one per instance. Inside the host this is the platform's real channel; outside it (tests, your editor) a descriptor of the same shape. Put it on the schema as `channel` and pass it to `usePluginRealtime`; a task publishes on it with `ctx.notify(topic, data)`.
+
+```ts
+function definePluginChannel<T extends Record<string, { schema: unknown }>>(args: { applicationType: string; topics: T })
+```
+
+#### `deterministicReducerId` — function · src/helpers.ts
+
+Refold-stable id from event payload — the ONLY way a processor may mint an id when the dataCreator didn't (never nanoid/Date.now in a reducer).
+
+```ts
+function deterministicReducerId(prefix: string, seed: unknown): string
+```
+
+#### `fenceMetaOf` — function · src/editor-sync.ts
+
+The fence record of `itemKey` in an app state (`__itemRevs`), if any.
+
+```ts
+function fenceMetaOf(state: unknown, itemKey: string): FenceItemMeta | undefined
+```
+
+#### `FILE_GRANT_DEFAULT_TTL_SECONDS` — const · src/files.ts
+
+How long a read grant lives when `ttlSeconds` is not given: one hour.
+
+```ts
+const FILE_GRANT_DEFAULT_TTL_SECONDS: number
+```
+
+#### `FILE_GRANT_MAX_TTL_SECONDS` — const · src/files.ts
+
+The longest a read grant lives (24 h); the default is one hour.
+
+```ts
+const FILE_GRANT_MAX_TTL_SECONDS: number
+```
+
+#### `FILE_LIST_ALL_MAX` — const · src/files.ts
+
+The most `listAll` gathers before it answers `truncated: true`.
+
+```ts
+const FILE_LIST_ALL_MAX: 20000
+```
+
+#### `FILE_LIST_PAGE_MAX` — const · src/files.ts
+
+The most one page of a listing holds.
+
+```ts
+const FILE_LIST_PAGE_MAX: 1000
+```
+
+#### `FILE_READ_CAP_BYTES` — const · src/files.ts
+
+The default most `FilesApi.read` returns (25 MB); pass `capBytes` to raise it.
+
+```ts
+const FILE_READ_CAP_BYTES: number
+```
+
+#### `FILE_READ_HARD_CAP_BYTES` — const · src/files.ts
+
+The ceiling `capBytes` may raise a read to (100 MB).
+
+```ts
+const FILE_READ_HARD_CAP_BYTES: number
+```
+
+#### `FILE_READ_MANY_MAX` — const · src/files.ts
+
+The most `readMany` reads in one call, in files and in bytes.
+
+```ts
+const FILE_READ_MANY_MAX: 200
+```
+
+#### `FILE_READ_MANY_TOTAL_BYTES` — const · src/files.ts
+
+…and the most bytes it gathers in one call (64 MB); past it the remaining rows answer `too_large`.
+
+```ts
+const FILE_READ_MANY_TOTAL_BYTES: number
+```
+
+#### `fileGrantUrl` — function · src/files.ts
+
+The URL of one file under a grant. `width` asks for a downsized image (a thumbnail), 16–2048 px.
+
+```ts
+function fileGrantUrl(grant: Pick<FileReadGrant, "urlBase">, ref: FileRef | string, opts?: { width?: number }): string
+```
+
+#### `FileSourceError` — class · src/files.ts
+
+A files call refused — `kind` says why: not_declared (the manifest has no `files` grant for it), source_unavailable, not_found, too_large, read_only, disabled, bad_ref.
+
+```ts
+class FileSourceError extends Error { … }
+```
+
+#### `fileStem` — function · src/labelme.ts
+
+`frame_001.JPG` → `frame_001` (the pairing key keeps its case; extensions do not count).
+
+```ts
+function fileStem(name: string): string
+```
+
+#### `formatContractId` — function · src/bindings.ts
+
+`{name: "stock", version: 1}` → `"stock/v1"`.
+
+```ts
+function formatContractId(c: ContractId): string
+```
+
+#### `formatValue` — function · src/chart.ts
+
+A number the way a person reads a measurement: few digits, no noise.
+
+```ts
+function formatValue(v: number): string
+```
+
+#### `handleOp` — function · src/ops.ts
+
+Wrap an op so it receives PARSED input and refuses what does not fit. A missing body is `{}`, so an op declared `z.object({})` is called with no arguments the way `callPluginOp(id, "browse", nodeId)` calls it.
+
+```ts
+function handleOp<T extends OpInputs, K extends keyof T & string, R>( ops: T, name: K, run: (ctx: PluginOpContext, input: z.infer<T[K]>) => Promise<R>, ): DeclaredOpHandler<T[K]>
+```
+
+#### `incompleteStateNotice` — function · src/helpers.ts
+
+`null` when the state is whole — the describer proceeds normally. Otherwise the block to return INSTEAD of a description. A missing collection is "state did not load", NEVER "empty" — flooring to [] tells the model something false and invites it to rebuild over real data.
+
+```ts
+function incompleteStateNotice(args: { title: string; instanceName?: unknown; shape: RequiredStateShape; }): string | null
+```
+
+#### `inputFields` — function · src/ops.ts
+
+The fields an input declares, for a refusal that says what WOULD have worked.
+
+```ts
+function inputFields(schema: OpInput): string[]
+```
+
+#### `isLabelImageName` — function · src/labelme.ts
+
+Is this file name an image a labeller opens (`LABEL_IMAGE_EXTS`, any case)?
+
+```ts
+function isLabelImageName(name: string): boolean
+```
+
+#### `isOlderOwnWrite` — function · src/editor-sync.ts
+
+Does the store hold a write of THIS session that is older than our last save? Then it is a fold that raced that save (a late poll, a collapse-merge read), not a remote change. Compared on this session's own clock only.
+
+```ts
+function isOlderOwnWrite( meta: FenceItemMeta | undefined, sessionId: string, lastOwnSaveAt: number | null | undefined, ): boolean
+```
+
+#### `isOpInputError` — function · src/ops.ts
+
+Duck-typed like `isZodObject`, for the same reason.
+
+```ts
+function isOpInputError(e: unknown): e is OpInputError
+```
+
+#### `jsonEqual` — function · src/editor-sync.ts
+
+Structural equality over JSON values, object key order ignored.
+
+```ts
+function jsonEqual(a: unknown, b: unknown): boolean
+```
+
+#### `kickPluginTask` — function · src/helpers.ts
+
+Kick one of your app's background tasks (docs/07) from the browser OR from a tool's `execute` on the server. The task must be listed in the manifest's `kickableTasks`; the platform's send-event route refuses the rest. `data` rides on `ctx.eventData` — keep it small and JSON. The kick is fire-and-forget: the task's result lands as events, or on the channel.
+
+```ts
+async function kickPluginTask(args: { applicationType: string; taskName: string; identifier: { workspaceId: string; nodeId: string; instanceName?: string }; data?: Record<string, unknown>; }): Promise<{ ok: boolean; status: number }>
+```
+
+#### `LABEL_IMAGE_EXTS` — const · src/labelme.ts
+
+The image kinds a labeller opens.
+
+```ts
+const LABEL_IMAGE_EXTS: readonly [".jpg", ".jpeg", ".png", ".bmp", ".webp", ".tif", ".tiff"]
+```
+
+#### `labelFileNameFor` — function · src/labelme.ts
+
+`photo.png` → `photo.json`.
+
+```ts
+function labelFileNameFor(imageName: string): string
+```
+
+#### `LABELME_VERSION` — const · src/labelme.ts
+
+The `version` written into a label file — the LabelMe release whose format this is.
+
+```ts
+const LABELME_VERSION: "5.5.0"
+```
+
+#### `listPageSize` — function · src/files.ts
+
+`pageSize` as a provider may use it: a whole number from 1 to FILE_LIST_PAGE_MAX, default 100.
+
+```ts
+function listPageSize(opts?: FileListOptions | null): number
+```
+
+#### `makeOpTool` — function · src/ops.ts
+
+`opTool`, bound to a caller. The package binds its own `callPluginOp`; the platform binds the one that carries the acting viewer and targets this deployment — same tool, different wire, decided once at the index.
+
+```ts
+function makeOpTool(call: CallOp)
+```
+
+#### `mapCaretThroughEdit` — function · src/editor-sync.ts
+
+Where a caret (or selection edge) belongs after the text it sat in was replaced by a merge: unchanged when the change is entirely after it, shifted by the length difference when the change is before it. Pure. Use it when your editor is a controlled textarea — otherwise React puts the caret at the end and the rest of the person's typing lands after the other writer's text.
+
+```ts
+function mapCaretThroughEdit(prev: string, next: string, pos: number): number
+```
+
+#### `matchesListOptions` — function · src/files.ts
+
+Does an entry pass these listing options? The one rule every provider's listing is held to.
+
+```ts
+function matchesListOptions(entry: Pick<FileEntry, "name" | "kind">, opts?: FileListOptions | null): boolean
+```
+
+#### `mergeFields` — function · src/editor-sync.ts
+
+Three-way merge of a flat record of fields (a form: to/cc/subject/body; a node's config). A field changed differently on both sides is a conflict → `null`.
+
+```ts
+function mergeFields<F extends Record<string, unknown>>( base: F, mine: F, theirs: F, equal: (a: unknown, b: unknown) => boolean = jsonEqual, ): F | null
+```
+
+#### `mergeLines` — function · src/editor-sync.ts
+
+Three-way merge of a text by lines. Keeps both sides when they touched different lines; any overlap (the same base line range changed on both sides) is a conflict → `null`.
+
+```ts
+function mergeLines(base: string, mine: string, theirs: string): string | null
+```
+
+#### `mergeRecordsById` — function · src/editor-sync.ts
+
+Three-way merge of a list of records addressed by id (blocks, pages, nodes, edges, tabs).
+
+```ts
+function mergeRecordsById<R>( base: readonly R[], mine: readonly R[], theirs: readonly R[], idOf: (r: R) => string | undefined, equal: (a: R, b: R) => boolean = jsonEqual, /** Both sides changed one record: merge the record itself (e.g. its text by lines); null = conflict. */ mergeRecord?: (base: R, mine: R, theirs: R) => R | null, ): R[] | null
+```
+
+#### `mergeSequences` — function · src/editor-sync.ts
+
+Three-way merge of any SEQUENCE (lines, paragraphs, list items without ids): the two sides' changed regions against the base are found by longest common subsequence on `keyOf`; regions that do not overlap are both applied (two inserts at the same point both stay, ordered by content so every side agrees), overlapping ones are a conflict → `null`. Long common heads and tails are trimmed first, so a large document with local edits stays cheap. Pure.
+
+```ts
+function mergeSequences<T>( base: readonly T[], mine: readonly T[], theirs: readonly T[], keyOf: (item: T) => string, unify?: (a: T, b: T) => T | null, ): T[] | null
+```
+
+#### `missingAssetMessage` — function · src/assets.ts
+
+Why a name has no asset, in words an author can act on.
+
+```ts
+function missingAssetMessage(assets: AssetsManifest | null | undefined, name: string): string
+```
+
+#### `missingStateKeys` — function · src/helpers.ts
+
+The genesis-seeded keys a state lacks — for `getStateDescription`: a MISSING list means the state did not load (say so), an EMPTY one is real. Never floor an absent key to `[]`.
+
+```ts
+function missingStateKeys(shape: RequiredStateShape): string[]
+```
+
+#### `naiveLabel` — function · src/chart.ts
+
+A naive-minutes value back to "MM-DD HH:MM" for a tick.
+
+```ts
+function naiveLabel(minutes: number, withDate = true): string
+```
+
+#### `naiveMinutes` — function · src/chart.ts
+
+Naive local timestamps ("2026-03-31T20:58:20" or with a space) as a number for an x axis — minutes since the epoch, WITHOUT a timezone. Stream times are wall-clock strings from a device; `new Date(s)` would shift them by the viewer's offset.
+
+```ts
+function naiveMinutes(ts: string): number
+```
+
+#### `naiveTicks` — function · src/chart.ts
+
+Evenly spaced ticks across a naive-minutes window, labelled for the span.
+
+```ts
+function naiveTicks(start: number, end: number, count = 6): { x: number; label: string }[]
+```
+
+#### `nanoid` — function · ../../node_modules/nanoid/index.d.ts
+
+Generate secure URL-friendly unique ID.
+
+```ts
+function nanoid<Type extends string>(size?: number): Type
+```
+
+#### `OpInputError` — class · src/ops.ts
+
+What a handler throws when the call does not fit the declared input. The platform's op routes answer it as `invalid` (400) — the same code the door uses for a malformed call — so a tool relays "add-product does not take imageUrl" rather than a 502 with a zod dump in it.
+
+```ts
+class OpInputError extends Error { … }
+```
+
+#### `opTool` — const · src/index.ts
+
+The agent tool for one op, declared once: `opTool(ops.play, { say })` in app.tsx gives a tool whose parameters ARE the op's zod input and whose call goes to `callPluginOp` — as the acting viewer on the platform, over the preview's own route in a Forge box. `say` turns the op's result into the words the model reads.
+
+```ts
+const opTool: <T extends OpInputs, K extends keyof T & string, R = unknown>(ops: T, name: K, cfg: OpToolConfig<T[K], R>) => DerivedTool
+```
+
+#### `ownChannelId` — function · src/audience.ts
+
+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.
+
+```ts
+function ownChannelId(viewer: AudienceViewer): string | null
+```
+
+#### `pairImagesWithLabels` — function · src/labelme.ts
+
+One folder's listing → its images, each with the label file beside it. Pairing is by STEM, case-sensitively first (what LabelMe and a trainer do), then case-insensitively. Two images sharing a stem (`a.jpg`, `a.png`) both pair with the one `a.json`. Order: natural name order.
+
+```ts
+function pairImagesWithLabels(entries: FileEntry[]): LabelledImage[]
+```
+
+#### `parseAssetObject` — function · src/assets.ts
+
+`<sha256>.<ext>` → its parts, or null for anything else (the serving route's only door).
+
+```ts
+function parseAssetObject(object: string): { sha256: string; ext: string; type: string } | null
+```
+
+#### `parseAssetsManifest` — function · src/assets.ts
+
+Parse `assets.json` text leniently: a missing or broken file is an empty manifest.
+
+```ts
+function parseAssetsManifest(text: string | null | undefined, pluginId: string): AssetsManifest
+```
+
+#### `parseContractId` — function · src/bindings.ts
+
+`"stock/v1"` → `{name: "stock", version: 1}`; anything else → null.
+
+```ts
+function parseContractId(raw: string): ContractId | null
+```
+
+#### `parseLabelMe` — function · src/labelme.ts
+
+A LabelMe document (parsed JSON, or its text) → shapes. Tolerant: anything that is not a polygon with numeric points is skipped, and garbage answers [] — a bad label file must never take the labeller down. `size` is the image size the file claims, when it claims one.
+
+```ts
+function parseLabelMe(json: unknown): { shapes: LabelShape[]; size: { width: number; height: number } | null }
+```
+
+#### `parseSourceId` — function · src/files.ts
+
+A file source id as its parts: the workspace, Google Drive, a local mount, or an app's own provider.
+
+```ts
+function parseSourceId(sourceId: string): ParsedSourceId
+```
+
+#### `PLATFORM_API_VERSION` — const · src/manifest.ts
+
+The plugin-contract version THIS SDK (and the matching host) speak. Manifests may pin `platformApi: {min, max?}`; the host refuses installs outside the range at sync time (fail loud at install, never at runtime). 1.1.0: fileSources consent + fileProviders contributions (additive).
+
+```ts
+const PLATFORM_API_VERSION: "1.1.0"
+```
+
+#### `PLUGIN_ACCESS_LEVELS` — const · src/manifest.ts
+
+WHO MAY REACH A SURFACE — the access level of one op, route or kickable task.
+
+```ts
+const PLUGIN_ACCESS_LEVELS: readonly ["write", "read", "public", "token", "roles"]
+```
+
+#### `PLUGIN_ID_RE` — const · src/assets.ts
+
+A plugin id as the serving route accepts it: lower-case, digits, dashes.
+
+```ts
+const PLUGIN_ID_RE: RegExp
+```
+
+#### `PLUGIN_MANIFEST_VERSION` — const · src/manifest.ts
+
+plugin.json — THE package contract. This file is the source of truth for the schema; the host imports it from here, and `schemas/plugin.schema.json` is generated from it at build time so non-TS tooling (and LLMs) can validate without executing anything.
+
+```ts
+const PLUGIN_MANIFEST_VERSION: 1
+```
+
+#### `PluginCallError` — class · src/helpers.ts
+
+What a failed op call throws. It CARRIES the platform's refusal code, so a UI can tell `login-required` (raise the sign-in wall) from `forbidden` (an error) — `useSignInWall().raise(err)` reads exactly this. A bare `Error` dropped the code, and the wall never rose (found by the first S6 drive).
+
+```ts
+class PluginCallError extends Error { … }
+```
+
+#### `PluginConnectionSchema` — const · src/manifest.ts
+
+The zod schema one entry of a manifest's `connections` must satisfy.
+
+```ts
+const PluginConnectionSchema: z.ZodEffects<z.ZodObject<{ key: z.ZodString; kind: z.ZodEnum<["oauth2", "apiKey"]>; label: z.ZodString; description: z.ZodOptional<z.ZodString>; authorizeUrl: z.ZodOptional<z.ZodString>; tokenUrl: z.ZodOptional<z.ZodString>; oauthScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; clientIdEnv: z.ZodOptional<z.ZodString>; clientSecretEnv: z.ZodOptional<z.ZodString>; headerNames: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }>, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }>
+```
+
+#### `PluginManifestSchema` — const · src/manifest.ts
+
+The zod schema `plugin.json` must satisfy — the sync and `check_app` refuse a manifest that fails it, with the path.
+
+```ts
+const PluginManifestSchema: z.ZodObject<{ manifestVersion: z.ZodLiteral<1>; id: z.ZodString; name: z.ZodString; version: z.ZodString; description: z.ZodString; applicationType: z.ZodString; entry: z.ZodString; icon: z.ZodOptional<z.ZodString>; author: z.ZodOptional<z.ZodObject<{ name: z.ZodString; email: z.ZodOptional<z.ZodString>; url: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { name?: string; email?: string; url?: string; }, { name?: string; email?: string; url?: string; }>>; kickableTasks: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodObject<{ access: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<["write", "read", "public", "token"]>, z.ZodArray<z.ZodString, "many">]>>>; requires: z.ZodOptional<z.ZodLiteral<"account">>; }, "strict", z.ZodTypeAny, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>>]>>>; webhooks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>; ops: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodObject<{ access: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<["write", "read", "public", "token"]>, z.ZodArray<z.ZodString, "many">]>>>; requires: z.ZodOptional<z.ZodLiteral<"account">>; }, "strict", z.ZodTypeAny, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>>]>>>; routes: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodObject<{ access: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<["write", "read", "public", "token"]>, z.ZodArray<z.ZodString, "many">]>>>; requires: z.ZodOptional<z.ZodLiteral<"account">>; }, "strict", z.ZodTypeAny, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>>]>>>; pollTasks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{ task: z.ZodString; everyMinutes: z.ZodNumber; }, "strip", z.ZodTypeAny, { task?: string; everyMinutes?: number; }, { task?: string; everyMinutes?: number; }>, "many">>>; platformApi: z.ZodOptional<z.ZodObject<{ min: z.ZodString; max: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { min?: string; max?: string; }, { min?: string; max?: string; }>>; scopes: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>; roles: z.ZodOptional<z.ZodEffects<z.ZodObject<{ vocabulary: z.ZodArray<z.ZodString, "many">; default: z.ZodDefault<z.ZodOptional<z.ZodObject<{ owner: z.ZodOptional<z.ZodString>; "member-edit": z.ZodOptional<z.ZodString>; "member-readonly": z.ZodOptional<z.ZodString>; visitor: z.ZodOptional<z.ZodString>; anonymous: z.ZodOptional<z.ZodString>; agent: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }, { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }>>>; describe: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>; attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<["string", "int", "boolean"]>>>; custom: z.ZodOptional<z.ZodObject<{ attributes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ where: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; hide: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; update: z.ZodOptional<z.ZodObject<{ fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; transitions: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { fields?: string[]; transitions?: string; }, { fields?: string[]; transitions?: string; }>>; }, "strict", z.ZodTypeAny, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>>>; ops: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }, { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }>>; }, "strict", z.ZodTypeAny, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }>, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }>>; workspaceTools: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>; connections: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{ key: z.ZodString; kind: z.ZodEnum<["oauth2", "apiKey"]>; label: z.ZodString; description: z.ZodOptional<z.ZodString>; authorizeUrl: z.ZodOptional<z.ZodString>; tokenUrl: z.ZodOptional<z.ZodString>; oauthScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; clientIdEnv: z.ZodOptional<z.ZodString>; clientSecretEnv: z.ZodOptional<z.ZodString>; headerNames: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }>, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }, { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }>, "many">>>; fileSources: z.ZodOptional<z.ZodEffects<z.ZodObject<{ workspace: z.ZodOptional<z.ZodEnum<["read", "readwrite"]>>; providers: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>; write: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }, { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }>, { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }, { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }>>; fileProviders: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{ key: z.ZodString; connectionKey: z.ZodString; label: z.ZodString; }, "strict", z.ZodTypeAny, { key?: string; label?: string; connectionKey?: string; }, { key?: string; label?: string; connectionKey?: string; }>, "many">>>; uses: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ contract: z.ZodString; label: z.ZodOptional<z.ZodString>; optional: z.ZodOptional<z.ZodBoolean>; }, "strict", z.ZodTypeAny, { label?: string; contract?: string; optional?: boolean; }, { label?: string; contract?: string; optional?: boolean; }>>>; provides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; events: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; models: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { models?: string[]; tools?: string[]; events?: string[]; }, { models?: string[]; tools?: string[]; events?: string[]; }>>>; channel: z.ZodOptional<z.ZodObject<{ topics: z.ZodRecord<z.ZodString, z.ZodObject<{ audience: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"all">, z.ZodLiteral<"viewer">, z.ZodString]>>; mayAddress: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; description: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { description?: string; audience?: string; mayAddress?: string[]; }, { description?: string; audience?: string; mayAddress?: string[]; }>>; }, "strict", z.ZodTypeAny, { topics?: Record<string, { description?: string; audience?: string; mayAddress?: string[]; }>; }, { topics?: Record<string, { description?: string; audience?: string; mayAddress?: string[]; }>; }>>; db: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ scope: z.ZodOptional<z.ZodEnum<["instance", "workspace", "user"]>>; owner: z.ZodOptional<z.ZodLiteral<"creator">>; fields: z.ZodRecord<z.ZodString, z.ZodString>; sealed: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; unique: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString, "many">, "many">>; indexes: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodObject<{ fields: z.ZodArray<z.ZodString, "many">; kind: z.ZodOptional<z.ZodEnum<["btree", "contains", "text"]>>; }, "strict", z.ZodTypeAny, { kind?: "btree" | "contains" | "text"; fields?: string[]; }, { kind?: "btree" | "contains" | "text"; fields?: string[]; }>]>, "many">>; rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strict", z.ZodTypeAny, { owner?: "creator"; fields?: Record<string, string>; scope?: "workspace" | "instance" | "user"; sealed?: string[]; unique?: string[][]; indexes?: (string[] | { kind?: "btree" | "contains" | "text"; fields?: string[]; })[]; rules?: Record<string, unknown>; }, { owner?: "creator"; fields?: Record<string, string>; scope?: "workspace" | "instance" | "user"; sealed?: string[]; unique?: string[][]; indexes?: (string[] | { kind?: "btree" | "contains" | "text"; fields?: string[]; })[]; rules?: Record<string, unknown>; }>>>; }, "strict", z.ZodTypeAny, { roles?: { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }; description?: string; manifestVersion?: 1; id?: string; name?: string; version?: string; applicationType?: string; entry?: string; icon?: string; author?: { name?: string; email?: string; url?: string; }; kickableTasks?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; webhooks?: string[]; ops?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; routes?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; pollTasks?: { task?: string; everyMinutes?: number; }[]; platformApi?: { min?: string; max?: string; }; scopes?: string[]; workspaceTools?: string[]; connections?: { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }[]; fileSources?: { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }; fileProviders?: { key?: string; label?: string; connectionKey?: string; }[]; uses?: Record<string, { label?: string; contract?: string; optional?: boolean; }>; provides?: Record<string, { models?: string[]; tools?: string[]; events?: string[]; }>; channel?: { topics?: Record<string, { description?: string; audience?: string; mayAddress?: string[]; }>; }; db?: Record<string, { owner?: "creator"; fields?: Record<string, string>; scope?: "workspace" | "instance" | "user"; sealed?: string[]; unique?: string[][]; indexes?: (string[] | { kind?: "btree" | "contains" | "text"; fields?: string[]; })[]; rules?: Record<string, unknown>; }>; }, { roles?: { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }; description?: string; manifestVersion?: 1; id?: string; name?: string; version?: string; applicationType?: string; entry?: string; icon?: string; author?: { name?: string; email?: string; url?: string; }; kickableTasks?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; webhooks?: string[]; ops?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; routes?: string[] | Record<string, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>; pollTasks?: { task?: string; everyMinutes?: number; }[]; platformApi?: { min?: string; max?: string; }; scopes?: string[]; workspaceTools?: string[]; connections?: { key?: string; kind?: "oauth2" | "apiKey"; label?: string; description?: string; authorizeUrl?: string; tokenUrl?: string; oauthScopes?: string[]; clientIdEnv?: string; clientSecretEnv?: string; headerNames?: string[]; }[]; fileSources?: { write?: string[]; workspace?: "read" | "readwrite"; providers?: string[]; }; fileProviders?: { key?: string; label?: string; connectionKey?: string; }[]; uses?: Record<string, { label?: string; contract?: string; optional?: boolean; }>; provides?: Record<string, { models?: string[]; tools?: string[]; events?: string[]; }>; channel?: { topics?: Record<string, { description?: string; audience?: string; mayAddress?: string[]; }>; }; db?: Record<string, { owner?: "creator"; fields?: Record<string, string>; scope?: "workspace" | "instance" | "user"; sealed?: string[]; unique?: string[][]; indexes?: (string[] | { kind?: "btree" | "contains" | "text"; fields?: string[]; })[]; rules?: Record<string, unknown>; }>; }>
+```
+
+#### `PluginRolesSchema` — const · src/manifest.ts
+
+WHAT THE APP CALLS ITS PEOPLE.
+
+```ts
+const PluginRolesSchema: z.ZodEffects<z.ZodObject<{ vocabulary: z.ZodArray<z.ZodString, "many">; default: z.ZodDefault<z.ZodOptional<z.ZodObject<{ owner: z.ZodOptional<z.ZodString>; "member-edit": z.ZodOptional<z.ZodString>; "member-readonly": z.ZodOptional<z.ZodString>; visitor: z.ZodOptional<z.ZodString>; anonymous: z.ZodOptional<z.ZodString>; agent: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }, { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }>>>; describe: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>; attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<["string", "int", "boolean"]>>>; custom: z.ZodOptional<z.ZodObject<{ attributes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{ where: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; hide: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; update: z.ZodOptional<z.ZodObject<{ fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; transitions: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { fields?: string[]; transitions?: string; }, { fields?: string[]; transitions?: string; }>>; }, "strict", z.ZodTypeAny, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>>>; ops: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }, { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }>>; }, "strict", z.ZodTypeAny, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }>, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }, { default?: { owner?: string; "member-edit"?: string; "member-readonly"?: string; visitor?: string; anonymous?: string; agent?: string; }; custom?: { ops?: string[]; attributes?: string[]; models?: Record<string, { where?: string[]; hide?: string[]; update?: { fields?: string[]; transitions?: string; }; }>; }; vocabulary?: string[]; describe?: Record<string, string>; attributes?: Record<string, "string" | "boolean" | "int">; }>
+```
+
+#### `pluginRouteUrl` — function · src/helpers.ts
+
+The URL of one of your server routes (docs/06) for one instance — what an `EventSource` or `fetch` in your UI opens. Same origin; the session rides along.
+
+```ts
+function pluginRouteUrl( pluginId: string, routeName: string, nodeId: string, params?: Record<string, string | number | boolean>, ): string
+```
+
+#### `PluginSurfaceEntrySchema` — const · src/manifest.ts
+
+`access` is a platform level — or a LIST OF THE APP'S OWN ROLE WORDS, which opens the surface to exactly those roles (the owner always passes) and to nobody else, whatever their workspace standing. A granted outsider who holds `staff` reaches `set-order-status` this way; a workspace editor the owner never named does not. A composed role reaches it only when it was handed the surface (`roles.custom.ops`).
+
+```ts
+const PluginSurfaceEntrySchema: z.ZodObject<{ access: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<["write", "read", "public", "token"]>, z.ZodArray<z.ZodString, "many">]>>>; requires: z.ZodOptional<z.ZodLiteral<"account">>; }, "strict", z.ZodTypeAny, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }, { access?: "write" | "read" | "public" | "token" | string[]; requires?: "account"; }>
+```
+
+#### `previewPersona` — function · src/helpers.ts
+
+VIEW AS, from the browser's side. In a Forge preview the board's switcher writes a persona onto the window; every call the app's UI makes then carries it, so the server sees the same pretend person the screen shows. Absent outside a preview: the platform never reads it, and the header is not sent.
+
+```ts
+function previewPersona(): string | null
+```
+
+#### `publicSurfaceNames` — function · src/manifest.ts
+
+Every name in this list that is reachable without a workspace session.
+
+```ts
+function publicSurfaceNames(list: unknown): string[]
+```
+
+#### `reduceBinding` — function · src/bindings.ts
+
+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.
+
+```ts
+function reduceBinding( current: BindingMap, event: { slot?: unknown; nodeId?: unknown; applicationType?: unknown; via?: unknown; at?: unknown }, knownSlots: readonly string[], ): BindingMap
+```
+
+#### `resolveAppRole` — function · src/roles.ts
+
+The app's word for this caller.
+
+```ts
+function resolveAppRole(args: { roles?: PluginRoleVocabulary | null; platformRole: string; key: RoleKindKey; }): string
+```
+
+#### `roleKeyFor` — function · src/roles.ts
+
+The key for a caller, given their kind and (for a member) their access.
+
+```ts
+function roleKeyFor( kind: "owner" | "member" | "visitor" | "anonymous" | "agent" | "internal", accessType?: "readonly" | "edit" | null, ): RoleKindKey
+```
+
+#### `serializeLabelMe` — function · src/labelme.ts
+
+Shapes → a LabelMe document. Polygons under three points are dropped: LabelMe refuses them and so does a trainer.
+
+```ts
+function serializeLabelMe(args: { shapes: LabelShape[]; imageName: string; width: number; height: number }): LabelMeDoc
+```
+
+#### `splitFilePath` — function · src/files.ts
+
+"sheets/quality_dataset/Type5" → its segments. Leading "/", a source's own label and empty parts are dropped.
+
+```ts
+function splitFilePath(path: string): string[]
+```
+
+#### `stableStringify` — function · src/helpers.ts
+
+Pure helpers — byte-for-byte vendored from the platform (a drift gate in the host asserts behavioural equality on every build).
+
+```ts
+function stableStringify(v: unknown): string
+```
+
+#### `strictInput` — function · src/ops.ts
+
+The strict twin of an input: an undeclared field is refused instead of dropped.
+
+```ts
+function strictInput<S extends OpInput>(schema: S): S
+```
+
+#### `subscriptionsFor` — function · src/audience.ts
+
+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.
+
+```ts
+function subscriptionsFor( topics: Record<string, TopicDecl | undefined>, viewer: AudienceViewer, ): { audience: ChannelAudience; topics: string[] }[]
+```
+
+#### `surfaceAccess` — function · src/manifest.ts
+
+The access a surface declares. Absent, unknown or array-form → `write`.
+
+```ts
+function surfaceAccess( list: unknown, name: string, ): { level: PluginAccessLevel; requiresAccount: boolean; roles: string[] | null }
+```
+
+#### `surfaceNames` — function · src/manifest.ts
+
+Normalised view of any surface list: every declared name, in order.
+
+```ts
+function surfaceNames(list: unknown): string[]
+```
+
+#### `textPath` — function · src/chart.ts
+
+A string as filled glyph outlines. `y` is the baseline.
+
+```ts
+function textPath(text: string, x: number, y: number, size: number, opts: { fill: string; anchor?: "start" | "middle" | "end"; maxWidth?: number } = { fill: "#000" }): string
+```
+
+#### `textWidth` — function · src/chart.ts
+
+The width of a string at a font size, in pixels.
+
+```ts
+function textWidth(text: string, size: number): number
+```
+
+#### `timingSafeEqual` — function · src/helpers.ts
+
+Constant-time string compare for webhook secrets/signatures. A plain `===` leaks length/prefix timing; use THIS in every webhook handler. Pure JS (no node:crypto) so it is safe in any runtime the SDK reaches.
+
+```ts
+function timingSafeEqual(a: string, b: string): boolean
+```
+
+#### `unfilledRequiredSlots` — function · src/bindings.ts
+
+The slots a manifest declares that nothing fills yet — the ones a seam refuses on.
+
+```ts
+function unfilledRequiredSlots(uses: Record<string, UsesDecl>, bindings: BindingMap): string[]
+```
+
+#### `withAsset` — function · src/assets.ts
+
+A manifest with one entry added or replaced. Pure.
+
+```ts
+function withAsset(assets: AssetsManifest | null | undefined, pluginId: string, name: string, entry: AssetEntry): AssetsManifest
+```
+
+#### `withoutAsset` — function · src/assets.ts
+
+A manifest with one entry removed (the bytes stay; they may be shared). Pure.
+
+```ts
+function withoutAsset(assets: AssetsManifest | null | undefined, pluginId: string, name: string): AssetsManifest
+```
+
+### Types (76)
+
+#### `AgentRunToolContext` — interface · src/types.ts
+
+MIRRORS the host. Present only when a tool runs inside an agent-builder run; absent for chat / voice / SDK calls.
+
+```ts
+interface AgentRunToolContext {
+  agentRunId: string;
+  agentBuilderNodeId: string;
+  currentAgentNodeId: string | null;
+  userId: string;
+  setWaitDirectiveCreatedThisStep: () => void;
+  isWaitDirectiveAlreadyCreatedThisStep: () => boolean;
+}
+```
+
+#### `ApplicationIdentifier` — interface · src/types.ts
+
+MIRRORS the host's `ApplicationIdentifier` (venus-sdk.ts) exactly.
+
+```ts
+interface ApplicationIdentifier {
+  workspaceId: string;
+  nodeId: string;
+  applicationType: string;
+  instanceName: string;
+  externalActor?: {
+    kind?: "external" | "sandbox";
+    userId: string;
+    email: string | null;
+    handle: string | null;
+    viaProfileId: string;
+    sessionId: string;
+    anonymous?: boolean;
+  };
+}
+```
+
+#### `ApplicationPort` — interface · src/types.ts
+
+MIRRORS the host's `ApplicationPort` (model/knowledge-workspace.ts). The two loosely-typed members are platform-internal shapes a plugin never constructs by hand; most plugins return `[]` from `getPorts`.
+
+```ts
+interface ApplicationPort {
+  id: string;
+  portType: any;
+  portName: string;
+  eventName: string;
+  eventDataSchema: any;
+  eventTargets: any[];
+}
+```
+
+#### `ApplicationSchema` — interface · src/types.ts
+
+THE schema — the one object a plugin's entry module exports as `pluginSchema`. Identical contract to every built-in app.
+
+```ts
+interface ApplicationSchema<StateType extends ApplicationIdentifier> {
+  applicationType: string;
+  description: string;
+  controlPlane?: true;
+  reactNode: ComponentType<{ state: StateType }>;
+  events: EventDefinition<StateType>[];
+  stateCreator: (identifier: ApplicationIdentifier, data: any) => StateType;
+  toolkitCreator: (
+    identifier: ApplicationIdentifier,
+    forChatId: string,
+    eventCallback: (event: any) => void,
+    chatMessageCallback: (message: any) => void,
+    runCtx?: AgentRunToolContext,
+  ) => Record<string, ApplicationTools>;
+  getPorts: () => ApplicationPort[];
+  tasks?: AppTaskDefinition<StateType>[];
+  channel?: (params: { workspaceId: string; nodeId: string }) => any;
+  getStateDescription: (applicationState: any) => string;
+  publicSharing?: PublicSharingPolicy<StateType>;
+  movable?: boolean;
+  reconstructStateFromEventLog?: boolean;
+  slimForBroadcast?: (state: StateType) => Partial<StateType> | undefined;
+}
+```
+
+#### `ApplicationTools` — interface · src/types.ts
+
+```ts
+interface ApplicationTools {
+  description: string;
+  parameters: z.ZodObject<Record<string, z.ZodTypeAny>>;
+  execute: (args: Record<string, any>) => Promise<ToolResult>;
+  onClient: (
+    args: Record<string, any>,
+  ) => void | ToolResult | Promise<void | ToolResult>;
+  background?: boolean;
+  realtimeWait?: {
+    channel: any;
+    topic: string;
+    isTerminal: (data: any) => boolean;
+    extractResult: (data: any) => string;
+  };
+}
+```
+
+#### `AppTaskContext` — interface · src/types.ts
+
+Durable-task context (Inngest under the hood). Everything you need is on ctx — a task handler imports NOTHING server-only.
+
+```ts
+interface AppTaskContext<TState extends ApplicationIdentifier> {
+  identifier: ApplicationIdentifier;
+  eventData: Record<string, any>;
+  step: any;
+  logger: any;
+  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, opts?: { to?: { viewerIds: string[] } | { role: string } }): Promise<void>;
+}
+```
+
+#### `AppTaskDefinition` — interface · src/types.ts
+
+```ts
+interface AppTaskDefinition<TState extends ApplicationIdentifier> {
+  taskName: string;
+  description?: string;
+  concurrency?: { limit: number; scope: "per-app" | "global" };
+  handler: (ctx: AppTaskContext<TState>) => Promise<void>;
+}
+```
+
+#### `AssetEntry` — interface · src/assets.ts
+
+APP ASSETS — images, films, fonts an app ships with (forge-assets-and-mcp-parity.md).
+
+```ts
+interface AssetEntry {
+  sha256: string;
+  bytes: number;
+  type: string;
+  at?: number;
+}
+```
+
+#### `AssetsManifest` — interface · src/assets.ts
+
+```ts
+interface AssetsManifest {
+  pluginId: string;
+  files: Record<string, AssetEntry>;
+}
+```
+
+#### `AttrType` — type · src/db/custom-roles.ts
+
+WHAT A GRANT MAY SAY ABOUT A PERSON, typed at the boundary. `roles.attributes` in the manifest declares `{ customer: "int" }`; a grant carries `"204"` as the owner typed it; the viewer carries `204`. A rule or a composed role may then scope a model by `viewer.customer`, and an int column compares to an int — not to a string that matches nothing (which fails closed and looks like a bug, which it was, 2026-09-15).
+
+```ts
+type AttrType = "string" | "int" | "boolean";
+```
+
+#### `AttrValue` — type · src/db/custom-roles.ts
+
+```ts
+type AttrValue = string | number | boolean;
+```
+
+#### `AudienceViewer` — interface · src/audience.ts
+
+The viewer facts this module needs — the shape `PluginViewer` already has.
+
+```ts
+interface AudienceViewer {
+  kind: string;
+  userId: string | null;
+  viewerIds: string[];
+  role: string;
+}
+```
+
+#### `BaseMerge` — interface · src/types.ts
+
+```ts
+interface BaseMerge<V = any> {
+  current: (state: any, eventData: any) => V | undefined;
+  incoming: (eventData: any) => V;
+  withValue: (eventData: any, value: V) => any;
+  merge: (base: V, mine: V, theirs: V) => V | null;
+  equal?: (a: V, b: V) => boolean;
+}
+```
+
+#### `BindCheck` — type · src/bindings.ts
+
+```ts
+type BindCheck =
+  | { ok: true; via: string; tools: string[]; events: string[]; models: string[] }
+  | { ok: false; reasons: string[] };
+```
+
+#### `Binding` — interface · src/bindings.ts
+
+```ts
+interface Binding {
+  nodeId: string;
+  applicationType: string;
+  via: string;
+  boundAt?: number;
+}
+```
+
+#### `BindingHolder` — interface · src/bindings.ts
+
+WHERE A BINDING LIVES: on the consumer app's own timeline, folded under `_bindings`.
+
+```ts
+interface BindingHolder {
+  _bindings?: BindingMap;
+}
+```
+
+#### `BindingMap` — type · src/bindings.ts
+
+slot → binding. The consumer app's own state holds this.
+
+```ts
+type BindingMap = Record<string, Binding>;
+```
+
+#### `CallOp` — type · src/ops.ts
+
+How the tool reaches the op: the package's caller on npm, the platform's own inside the host.
+
+```ts
+type CallOp = <T>(pluginId: string, op: string, nodeId: string, args?: unknown) => Promise<T>;
+```
+
+#### `ChannelAudience` — type · src/audience.ts
+
+```ts
+type ChannelAudience =
+  | { kind: "all" }
+  | { kind: "viewer"; viewerId: string }
+  | { kind: "role"; role: string };
+```
+
+#### `ChartMarker` — interface · src/chart.ts
+
+```ts
+interface ChartMarker {
+  x: number;
+  label?: string;
+  tone?: ChartTone;
+}
+```
+
+#### `ChartPanel` — interface · src/chart.ts
+
+```ts
+interface ChartPanel {
+  label: string;
+  unit?: string;
+  kind?: "line" | "step";
+  points: [number, number][];
+  band?: { min: number; max: number; label?: string };
+  levels?: [string, string];
+  impossible?: { below?: number; above?: number; label?: string };
+}
+```
+
+#### `ChartSpec` — interface · src/chart.ts
+
+```ts
+interface ChartSpec {
+  title?: string;
+  subtitle?: string;
+  width?: number;
+  panelHeight?: number;
+  xStart: number;
+  xEnd: number;
+  xTicks?: { x: number; label: string }[];
+  panels: ChartPanel[];
+  markers?: ChartMarker[];
+  now?: number;
+  gap?: number;
+  theme?: "light" | "dark";
+}
+```
+
+#### `ChartTone` — type · src/chart.ts
+
+```ts
+type ChartTone = "page" | "escalate" | "warn" | "note" | "info" | "ok";
+```
+
+#### `CollapsibleConfig` — interface · src/types.ts
+
+```ts
+interface CollapsibleConfig {
+  collapseKeyFn: (eventData: any, context: EventData<any>) => string;
+  collapseWindowMs: number;
+  delta?: boolean;
+}
+```
+
+#### `CompiledCustomRole` — interface · src/db/custom-roles.ts
+
+```ts
+interface CompiledCustomRole {
+  name: string;
+  base: string;
+  describe: string | null;
+  ops: string[];
+  models: Record<
+    string,
+    {
+      where: Record<string, WhereValue>;
+      hide: string[];
+      updateFields: string[] | null;
+      transitions: { field: string; moves: Record<string, string[]> } | null;
+    }
+  >;
+}
+```
+
+#### `ContractDef` — interface · src/bindings.ts
+
+What a contract REQUIRES of whoever claims it. The platform ships these; an app may publish its own.
+
+```ts
+interface ContractDef {
+  id: string;
+  describe?: string;
+  tools: string[];
+  events: string[];
+  models: string[];
+}
+```
+
+#### `ContractId` — interface · src/bindings.ts
+
+WHAT STANDS BEHIND A SLOT.
+
+```ts
+interface ContractId {
+  name: string;
+  version: number;
+}
+```
+
+#### `CustomRoleDefinitionRaw` — interface · src/db/custom-roles.ts
+
+What the owner wrote (the event's data, minus bookkeeping).
+
+```ts
+interface CustomRoleDefinitionRaw {
+  name: string;
+  base: string;
+  describe?: string;
+  ops?: string[];
+  models?: Record<
+    string,
+    {
+      where?: Record<string, WhereValue>;
+      hide?: string[];
+      update?: { fields?: string[]; transitions?: Record<string, string[]> };
+    }
+  >;
+}
+```
+
+#### `CustomRoleGrant` — interface · src/db/custom-roles.ts
+
+What a caller carries when they hold a composed role.
+
+```ts
+interface CustomRoleGrant {
+  role: CompiledCustomRole;
+  attrs: Record<string, AttrValue>;
+}
+```
+
+#### `CustomRolesEnvelope` — interface · src/db/custom-roles.ts
+
+```ts
+interface CustomRolesEnvelope {
+  attributes: string[];
+  models: Record<string, { where: string[]; hide: string[]; updateFields: string[]; transitions: string | null }>;
+  ops: string[];
+}
+```
+
+#### `CustomRolesEnvelopeRaw` — interface · src/db/custom-roles.ts
+
+`roles.custom` as it appears in plugin.json.
+
+```ts
+interface CustomRolesEnvelopeRaw {
+  attributes?: string[];
+  models?: Record<
+    string,
+    {
+      where?: string[];
+      hide?: string[];
+      update?: { fields?: string[]; transitions?: string };
+    }
+  >;
+  ops?: string[];
+}
+```
+
+#### `DeclaredOpHandler` — interface · src/ops.ts
+
+A handler that knows what it takes — the scanner reads `input` off it.
+
+```ts
+interface DeclaredOpHandler<S extends OpInput = OpInput> extends PluginOpHandler {
+  readonly input: S;
+  readonly opName: string;
+}
+```
+
+#### `DerivedTool` — interface · src/ops.ts
+
+A tool derived from an op — the scanner reads `op` and `opInput` off it.
+
+```ts
+interface DerivedTool extends ApplicationTools {
+  readonly op: string;
+  readonly opInput: OpInput;
+  readOnly?: boolean;
+  publicSafe?: boolean;
+}
+```
+
+#### `EventData` — interface · src/types.ts
+
+```ts
+interface EventData<T = unknown> {
+  eventName: string;
+  workspaceId: string;
+  applicationId: string | undefined;
+  instanceName: string | undefined;
+  chatIdSource: string | undefined;
+  eventData: T;
+  timestamp: number;
+}
+```
+
+#### `EventDefinition` — interface · src/types.ts
+
+```ts
+interface EventDefinition<StateType extends ApplicationIdentifier> {
+  eventName: string;
+  type: EventTypes;
+  dataCreator: (params: Record<string, any>) => EventData<any>;
+  processor: (state: StateType, eventData: any) => StateType;
+  collapseConfig?: CollapsibleConfig;
+  triggerMeta?: TriggerMeta;
+  sideEffect?: EventSideEffect;
+  permission?: "user_exclusive";
+  conflictPolicy?: "mark" | "silent";
+  conflictScope?: (eventData: any) => string[] | null | undefined;
+  merge?: MergeDescription;
+  baseMerge?: BaseMerge;
+}
+```
+
+#### `EventReversibility` — type · src/types.ts
+
+```ts
+type EventReversibility =
+  | "pure"
+  | "external-reversible"
+  | "external-irreversible";
+```
+
+#### `EventSideEffect` — interface · src/types.ts
+
+MIRRORS the host (event-spec.ts). This mirror used to declare `EventSideEffect` as the bare string union above, so an author writing `sideEffect: "external-irreversible"` type-checked against the SDK and was rejected by the platform — the drift gate exists for exactly this.
+
+```ts
+interface EventSideEffect {
+  reversibility: EventReversibility;
+  description?: string;
+  inverseEventName?: string;
+  buildInverseEventData?: (
+    forwardEventData: any,
+    parentEvent: EventData<any>,
+  ) => any;
+  criticality?: "status" | "normal";
+}
+```
+
+#### `EventTypes` — enum · src/types.ts
+
+```ts
+enum EventTypes {
+  Client = "Client",
+  Workflow = "Workflow",
+  Workspace = "Workspace",
+}
+```
+
+#### `FenceItemMeta` — interface · src/editor-sync.ts
+
+The write fence's per-item bookkeeping this module reads (apply-app-event.ts `ItemRevMeta`).
+
+```ts
+interface FenceItemMeta {
+  tip?: string;
+  ts?: number;
+  sess?: string;
+}
+```
+
+#### `FileEntry` — interface · src/files.ts
+
+```ts
+interface FileEntry {
+  ref: FileRef;
+  name: string;
+  kind: "file" | "folder";
+  sizeBytes?: number;
+  mimeType?: string;
+  modifiedAt?: number;
+  path?: string;
+}
+```
+
+#### `FileListOptions` — interface · src/files.ts
+
+Narrow a listing at the SOURCE — a folder of 5,000 files is filtered by Drive, not by your UI.
+
+```ts
+interface FileListOptions {
+  only?: "file" | "folder";
+  nameContains?: string;
+  orderBy?: "name" | "modified";
+  pageSize?: number;
+}
+```
+
+#### `FileReadGrant` — interface · src/files.ts
+
+A READ GRANT: a signed, expiring permission to fetch files of ONE source of ONE workspace by URL, with no session — for an `<img>` in a preview, and for a machine (the person's computer downloading a training set). Build each file's URL with `fileGrantUrl`. Treat it like a password until it expires.
+
+```ts
+interface FileReadGrant {
+  sourceId: FileSourceId;
+  urlBase: string;
+  expiresAt: number;
+}
+```
+
+#### `FileReadManyItem` — interface · src/files.ts
+
+One answer of `readMany` — flat: `ok` true carries the bytes, false carries `kind` and `error`.
+
+```ts
+interface FileReadManyItem {
+  ref: FileRef;
+  ok: boolean;
+  name?: string;
+  contentType?: string;
+  text?: string;
+  base64?: string;
+  kind?: FileSourceErrorKind;
+  error?: string;
+}
+```
+
+#### `FileRef` — interface · src/files.ts
+
+```ts
+interface FileRef {
+  sourceId: FileSourceId;
+  ref: string;
+}
+```
+
+#### `FileSource` — interface · src/files.ts
+
+```ts
+interface FileSource {
+  sourceId: FileSourceId;
+  providerKey: string;
+  label: string;
+  detail?: string;
+  caps: { write: boolean; watch: boolean; durable: boolean };
+  online: boolean;
+}
+```
+
+#### `FileSourceErrorKind` — type · src/files.ts
+
+```ts
+type FileSourceErrorKind =
+  | "not_declared"
+  | "source_unavailable"
+  | "not_found"
+  | "too_large"
+  | "read_only"
+  | "disabled"
+  | "bad_ref";
+```
+
+#### `FileSourceId` — type · src/files.ts
+
+File sources — the client-safe half of the files API (plugin-file-sources.md). PURE mirror of the host's src/lib/file-sources/types.ts; the sdk-drift gate keeps them in lockstep.
+
+```ts
+type FileSourceId = string;
+```
+
+#### `FileWriteResult` — interface · src/files.ts
+
+What `write` answers: the file as it now stands, and whether it was made or replaced.
+
+```ts
+interface FileWriteResult {
+  entry: FileEntry;
+  created: boolean;
+}
+```
+
+#### `InstalledPluginInfo` — interface · src/manifest.ts
+
+Data-only row the host codegen inlines into registry.gen.ts.
+
+```ts
+interface InstalledPluginInfo {
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+  applicationType: string;
+  workspaceTools?: string[];
+}
+```
+
+#### `LabelledImage` — interface · src/labelme.ts
+
+```ts
+interface LabelledImage {
+  image: FileEntry;
+  label: FileEntry | null;
+}
+```
+
+#### `LabelMeDoc` — interface · src/labelme.ts
+
+```ts
+interface LabelMeDoc {
+  version: string;
+  flags: Record<string, never>;
+  shapes: LabelMeShape[];
+  imagePath: string;
+  imageData: null;
+  imageHeight: number;
+  imageWidth: number;
+}
+```
+
+#### `LabelMeShape` — interface · src/labelme.ts
+
+```ts
+interface LabelMeShape {
+  label: string;
+  points: [number, number][];
+  group_id: number | null;
+  description: string;
+  shape_type: "polygon";
+  flags: Record<string, never>;
+}
+```
+
+#### `LabelPoint` — interface · src/labelme.ts
+
+```ts
+interface LabelPoint {
+  x: number;
+  y: number;
+}
+```
+
+#### `LabelShape` — interface · src/labelme.ts
+
+One polygon of a label file, as an app holds it.
+
+```ts
+interface LabelShape {
+  label: string;
+  points: LabelPoint[];
+  groupId?: number | null;
+  description?: string;
+}
+```
+
+#### `MergeDescription` — interface · src/types.ts
+
+```ts
+interface MergeDescription {
+  item: (
+    eventData: any,
+    context: { applicationId?: string | null; eventName: string },
+  ) => string | null | undefined;
+  scope?: (eventData: any) => string[] | null | undefined;
+  onConcurrent?: "mark" | "silent";
+  describe?: (eventData: any) => string;
+}
+```
+
+#### `NotifyTarget` — type · src/audience.ts
+
+What `notify`'s caller asked for. Absent = the topic's own audience, aimed at the caller.
+
+```ts
+type NotifyTarget = { viewerIds: string[] } | { role: string } | "apps";
+```
+
+#### `OpInput` — type · src/ops.ts
+
+An op's input is always an object: it is the wire body AND a tool's parameters.
+
+```ts
+type OpInput = z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny>;
+```
+
+#### `OpInputs` — type · src/ops.ts
+
+```ts
+type OpInputs = Record<string, OpInput>;
+```
+
+#### `OpToolConfig` — interface · src/ops.ts
+
+```ts
+interface OpToolConfig<S extends OpInput, R> {
+  pluginId: string;
+  nodeId: string;
+  description: string;
+  say: (result: R, input: z.infer<S>) => ToolResult;
+  then?: (result: R, input: z.infer<S>) => void | Promise<void>;
+  readOnly?: boolean;
+  publicSafe?: boolean;
+}
+```
+
+#### `ParsedSourceId` — type · src/files.ts
+
+```ts
+type ParsedSourceId =
+  | { kind: "workspace" }
+  | { kind: "google-drive" }
+  | { kind: "local"; mountId: string }
+  | { kind: "plugin"; providerKey: string; connectionId: string };
+```
+
+#### `PluginAccessLevel` — type · src/manifest.ts
+
+```ts
+type PluginAccessLevel = (typeof PLUGIN_ACCESS_LEVELS)[number];
+```
+
+#### `PluginConnectionDecl` — type · src/manifest.ts
+
+```ts
+type PluginConnectionDecl = z.infer<typeof PluginConnectionSchema>;
+```
+
+#### `PluginManifest` — type · src/manifest.ts
+
+```ts
+type PluginManifest = z.infer<typeof PluginManifestSchema>;
+```
+
+#### `PluginRoleVocabulary` — interface · src/roles.ts
+
+```ts
+interface PluginRoleVocabulary {
+  vocabulary: string[];
+  default: Partial<Record<RoleKindKey, string>>;
+}
+```
+
+#### `ProviderFacts` — interface · src/bindings.ts
+
+What a candidate app ACTUALLY has, read from its manifest and registry — never from its claims.
+
+```ts
+interface ProviderFacts {
+  applicationType: string;
+  tools: string[];
+  events: string[];
+  models: string[];
+  provides: Record<string, ProvidesDecl>;
+}
+```
+
+#### `ProvidesDecl` — interface · src/bindings.ts
+
+What one app says it offers for one contract.
+
+```ts
+interface ProvidesDecl {
+  tools?: string[];
+  events?: string[];
+  models?: string[];
+}
+```
+
+#### `PublicSharingContext` — interface · src/types.ts
+
+MIRRORS the host. What a redactor is told about who is looking.
+
+```ts
+interface PublicSharingContext {
+  viewerKind: "public" | "collaborator-readonly";
+  defaultRole: string;
+  appRoles: Record<string, string> | null;
+  viewerIds?: string[];
+}
+```
+
+#### `PublicSharingPolicy` — interface · src/types.ts
+
+```ts
+interface PublicSharingPolicy<StateType> {
+  policy?: "allowed" | "never";
+  redactState?: (state: StateType, ctx: PublicSharingContext) => StateType;
+}
+```
+
+#### `ReconcileDecision` — type · src/editor-sync.ts
+
+```ts
+type ReconcileDecision =
+  | { kind: "echo" }
+  | { kind: "converged" }
+  | { kind: "stale-own" }
+  | { kind: "wait-save" }
+  | { kind: "merge" }
+  | { kind: "wait-idle" }
+  | { kind: "adopt" };
+```
+
+#### `RequiredStateShape` — interface · src/helpers.ts
+
+Fields whose ABSENCE means "did not load" (they are seeded at genesis).
+
+```ts
+interface RequiredStateShape {
+  lists?: Record<string, unknown>;
+  maps?: Record<string, unknown>;
+}
+```
+
+#### `RoleKindKey` — type · src/roles.ts
+
+What the platform knows about a caller, as a key into an app's `default` map.
+
+```ts
+type RoleKindKey =
+  | "owner"
+  | "member-edit"
+  | "member-readonly"
+  | "visitor"
+  | "anonymous"
+  | "agent";
+```
+
+#### `ToolResult` — type · src/types.ts
+
+What a tool may return. MIRRORS the host's `ToolResult` (src/application-interfaces/venus-sdk.ts) exactly — the drift gate (src/lib/plugins/sdk-drift.test.ts) asserts a plugin authored against this package satisfies the platform, and this type used to be `unknown`: wider than the host's union, so `Promise<unknown>` was not assignable to `Promise<ToolResult>` and EVERY SDK-authored toolkit failed the forward assertion. A plugin author must learn the real contract here, not at install time.
+
+```ts
+type ToolResult =
+  | string
+  | { text: string; images?: string[]; imageUrls?: string[] };
+```
+
+#### `TopicAudience` — type · src/audience.ts
+
+`all` (default) · `viewer` · `role:<name>`.
+
+```ts
+type TopicAudience = "all" | "viewer" | `role:${string}`;
+```
+
+#### `TopicDecl` — interface · src/audience.ts
+
+```ts
+interface TopicDecl {
+  audience?: TopicAudience;
+  mayAddress?: string[];
+}
+```
+
+#### `TriggerMeta` — interface · src/types.ts
+
+```ts
+interface TriggerMeta {
+  displayName?: string;
+  description?: string;
+  sampleVariables?: string[];
+  payloadShape?: "single" | "batch";
+  batchAccessor?: string;
+}
+```
+
+#### `UsesDecl` — interface · src/bindings.ts
+
+A slot an app needs filled.
+
+```ts
+interface UsesDecl {
+  contract: string;
+  label?: string;
+  optional?: boolean;
+}
+```
+
+==============================================================================
+## `esoul-sdk/server` — 67 exports
+
+Server code only (server.ts, ops, routes, tasks): the viewer, the app's database, files, connections, machines, charts, route tokens.
+
+### Functions and values (27)
+
+#### `APPROVAL_WAIT` — const · src/computer.ts
+
+What an app tells a person when the machine waits for them.
+
+```ts
+const APPROVAL_WAIT: "Waiting for the owner to approve this command in the My Computer app (or set that app to Auto)."
+```
+
+#### `callWorkspaceTool` — function · src/server.ts
+
+Call another app's tool from the server half (an op, task or webhook) — how an app orchestrates a my_computer or writes a spreadsheet from a job. Gated by the manifest's `workspaceTools` grants, same-workspace only. HOST-ONLY.
+
+```ts
+function callWorkspaceTool(_a: CallWorkspaceToolArgs): Promise<{ ok: boolean; text: string; truncated?: boolean }>
+```
+
+#### `computer` — const · src/server.ts
+
+A paired machine (`my_computer` app) from server code: status, a shell command, a Claude Code task, a file — with the tool's JSON parsed, waits capped and the approval gate made visible (computer.ts). Gated by the manifest's `workspaceTools`; works installed and in a Forge box through the board's tab.
+
+```ts
+const computer: (ctx: { pluginId: string; nodeId: string; }, machineNodeId: string) => Computer
+```
+
+#### `defineAppRole` — function · src/server.ts
+
+COMPOSE A ROLE, as the owner: a name of its own, a base word from the vocabulary it stands on, and what it takes away — which rows (`where`), which fields (`hide`), which changes (`update.fields`, `update.transitions`), which surfaces it may call (`ops`). Everything must fit the manifest's `roles.custom` envelope; a refusal names the key and the allowed values. Stored on the app's own timeline; `setAppRole` may then hand it to a person.
+
+```ts
+function defineAppRole( _ctx: { pluginId: string; workspaceId: string; nodeId: string; viewer: PluginViewer }, _definition: CustomRoleDefinitionRaw, ): Promise<{ ok: boolean; name?: string; error?: string }>
+```
+
+#### `emitPluginAppEvent` — function · src/server.ts
+
+Cross-app events: dispatch the TARGET app's own events through the platform spine (target's dataCreator mints; triggers fire; every event is actor-stamped `{kind:"plugin", pluginId, sourceNodeId}`). Same-workspace only. HOST-ONLY.
+
+```ts
+function emitPluginAppEvent( _args: EmitPluginAppEventArgs, ): Promise<{ ok: true; targetNodeId: string; eventName: string }>
+```
+
+#### `filesForOp` — function · src/server.ts
+
+Bind the files API straight from an op/task context. HOST-ONLY.
+
+```ts
+function filesForOp(_ctx: { pluginId: string; workspaceId: string; nodeId?: string; origin?: string; }): Promise<FilesApi>
+```
+
+#### `generateAppImage` — function · src/server.ts
+
+A PICTURE FOR YOUR APP, FROM ONE CALL.
+
+```ts
+function generateAppImage( _ctx: { pluginId: string; nodeId: string }, _args: { name: string; prompt: string; style?: string; shape?: "square" | "wide" | "tall" }, ): Promise<GeneratedAppImage>
+```
+
+#### `getPluginConnectionCredentials` — function · src/server.ts
+
+Read the sealed credentials of a plugin-declared connection (auto- refreshes expiring OAuth tokens). HOST-ONLY.
+
+```ts
+function getPluginConnectionCredentials( _connectionId: string, _pluginId: string, ): Promise<PluginConnectionCredentials>
+```
+
+#### `isTerminal` — const · src/computer.ts
+
+Whether a command has finished for good (`done`, `failed`, `denied`) — anything else is worth waiting on.
+
+```ts
+const isTerminal: (s: CommandStatus) => boolean
+```
+
+#### `listAppRoles` — function · src/server.ts
+
+Everyone the owner has given a role in THIS instance, the words the app declared, the roles the owner COMPOSED (`custom`) and the envelope they may be composed inside. HOST-ONLY.
+
+```ts
+function listAppRoles( _ctx: { pluginId: string; workspaceId: string; nodeId: string; viewer: PluginViewer }, ): Promise<AppRolesListing>
+```
+
+#### `makeComputer` — function · src/computer.ts
+
+Bind the client to a side's `callWorkspaceTool`. Authors use `computer(...)`, never this.
+
+```ts
+function makeComputer(call: CallWorkspaceToolFn)
+```
+
+#### `MAX_TIMEOUT_SECONDS` — const · src/computer.ts
+
+The longest a machine command may run before the machine stops it.
+
+```ts
+const MAX_TIMEOUT_SECONDS: 900
+```
+
+#### `MAX_WAIT_SECONDS` — const · src/computer.ts
+
+The longest one call waits on a machine command before answering "still running" (a tool call's budget).
+
+```ts
+const MAX_WAIT_SECONDS: 55
+```
+
+#### `mintRouteToken` — function · src/server.ts
+
+A DOOR FOR A MACHINE. A route declared `"access": "token"` in plugin.json is reached with `Authorization: Bearer <token>` and nothing else — no session, no share. Only your own server code can mint the token, so put the mint behind an op the owner calls (the one that starts the machine's process, say) and hand the machine the `url` and the `token` together:
+
+```ts
+function mintRouteToken(_ctx: { pluginId: string; nodeId: string; origin?: string }, _args: { route: string; ttlSeconds?: number; label?: string }): Promise<RouteTokenGrant>
+```
+
+#### `OUTPUT_LIMIT` — const · src/computer.ts
+
+How much of a command's stdout the My Computer app keeps. Print less than this.
+
+```ts
+const OUTPUT_LIMIT: 8000
+```
+
+#### `parseClaudeOutcome` — function · src/computer.ts
+
+A Claude Code task's tool answer as fields: the command's outcome plus `answer`, `sessionId`, `costUsd`, `isError`.
+
+```ts
+function parseClaudeOutcome(r: { ok: boolean; text: string; truncated?: boolean }): ClaudeOutcome
+```
+
+#### `parseCommandOutcome` — function · src/computer.ts
+
+One command answer, from whatever the tool said.
+
+```ts
+function parseCommandOutcome(r: { ok: boolean; text: string; truncated?: boolean }): CommandOutcome
+```
+
+#### `parseStatus` — function · src/computer.ts
+
+The machine's status answer as fields: paired, online, hostname, os, autonomy, pending approvals.
+
+```ts
+function parseStatus(r: { ok: boolean; text: string }): ComputerStatus
+```
+
+#### `parseToolJson` — function · src/computer.ts
+
+The tool answers `JSON.stringify(json)`; a refusal from the platform is plain words.
+
+```ts
+function parseToolJson(text: string): Record<string, unknown> | null
+```
+
+#### `pluginDb` — function · src/server.ts
+
+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.
+
+```ts
+function pluginDb<T = unknown>( _ctx: { pluginId: string; workspaceId: string; nodeId: string; viewer: PluginViewer }, _reach?: { across?: "owned-instances" | "my-rows"; viaBinding?: boolean }, ): Promise<T>
+```
+
+#### `pluginFiles` — function · src/server.ts
+
+The consent-enforcing files API for plugin server code. Every call re-checks your manifest `fileSources` grant (explicit-only — no grant, no files); workspace writes re-check the kill switch; saves/imports append `workspace/file_added` with your plugin stamped as the actor. HOST-ONLY.
+
+```ts
+function pluginFiles(_ctx: PluginFilesCtx): Promise<FilesApi>
+```
+
+#### `readAppState` — function · src/server.ts
+
+Read one app's state folded to head, by nodeId — server truth for an op or a task. Null when no such app exists. HOST-ONLY.
+
+```ts
+function readAppState( _nodeId: string, ): Promise<{ nodeId: string; workspaceId: string; applicationType: string; foldedSeq: number; state: Record<string, unknown> } | null>
+```
+
+#### `removeAppRole` — function · src/server.ts
+
+Remove a composed role. People holding it lose it. HOST-ONLY. Owner only.
+
+```ts
+function removeAppRole( _ctx: { pluginId: string; workspaceId: string; nodeId: string; viewer: PluginViewer }, _name: string, ): Promise<{ ok: boolean; name?: string; error?: string }>
+```
+
+#### `renderChartImage` — function · src/server.ts
+
+A CHART, AS A PICTURE A PERSON AND A MODEL CAN SEE. Hand it the SVG `chartSvg` made; get back an https URL to put in a tool's answer as `imageUrls` (chat shows it, the model reads it). In a Forge box there is nowhere to store a file, so it answers `base64` instead — put that in `images`. HOST-ONLY.
+
+```ts
+function renderChartImage(_ctx: { pluginId: string; nodeId: string }, _args: { name: string; svg: string }): Promise<ChartImage>
+```
+
+#### `setAppRole` — function · src/server.ts
+
+WHO ELSE MAY USE THIS INSTANCE, AND AS WHAT.
+
+```ts
+function setAppRole( _ctx: { pluginId: string; workspaceId: string; nodeId: string; viewer: PluginViewer }, /** `attrs` are typed by `roles.attributes` — a number or its digits for an int; refused when they do not fit. */ _args: { email: string; role: string; attrs?: Record<string, AttrValue> }, ): Promise<AppRoleResult>
+```
+
+#### `sseStream` — function · src/server.ts
+
+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.
+
+```ts
+function sseStream( run: (send: (event: string, data: unknown) => void, signal: AbortSignal) => Promise<void>, opts?: { signal?: AbortSignal; heartbeatMs?: number }, ): Response
+```
+
+#### `viewerProfile` — function · src/server.ts
+
+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.
+
+```ts
+function viewerProfile(_viewer: PluginViewer): Promise<ViewerProfile | null>
+```
+
+### Types (40)
+
+#### `AppRolePerson` — interface · src/server.ts
+
+```ts
+interface AppRolePerson {
+  userId: string;
+  email: string | null;
+  role: string;
+  attrs?: Record<string, AttrValue>;
+  grantedAt?: number;
+}
+```
+
+#### `AppRoleResult` — interface · src/server.ts
+
+Flat, not a discriminated union: an app compiled with `strict: false` cannot narrow one.
+
+```ts
+interface AppRoleResult {
+  ok: boolean;
+  userId?: string;
+  email?: string;
+  role?: string;
+  error?: string;
+}
+```
+
+#### `AppRolesListing` — interface · src/server.ts
+
+```ts
+interface AppRolesListing {
+  people: AppRolePerson[];
+  roles: string[];
+  custom: CustomRoleDefinitionRaw[];
+  envelope: CustomRolesEnvelope | null;
+}
+```
+
+#### `AttrType` — type · src/db/custom-roles.ts
+
+WHAT A GRANT MAY SAY ABOUT A PERSON, typed at the boundary. `roles.attributes` in the manifest declares `{ customer: "int" }`; a grant carries `"204"` as the owner typed it; the viewer carries `204`. A rule or a composed role may then scope a model by `viewer.customer`, and an int column compares to an int — not to a string that matches nothing (which fails closed and looks like a bug, which it was, 2026-09-15).
+
+```ts
+type AttrType = "string" | "int" | "boolean";
+```
+
+#### `AttrValue` — type · src/db/custom-roles.ts
+
+```ts
+type AttrValue = string | number | boolean;
+```
+
+#### `CallWorkspaceToolArgs` — interface · src/server.ts
+
+```ts
+interface CallWorkspaceToolArgs {
+  pluginId: string;
+  nodeId: string;
+  tool: string;
+  args?: Record<string, unknown>;
+  appType?: string;
+  targetNodeId?: string;
+}
+```
+
+#### `CallWorkspaceToolFn` — type · src/computer.ts
+
+```ts
+type CallWorkspaceToolFn = (a: CallWorkspaceToolArgs) => Promise<{ ok: boolean; text: string; truncated?: boolean }>;
+```
+
+#### `ChartImage` — interface · src/server.ts
+
+Flat: `ok` with `url` (installed) or `base64` (a box); otherwise `error`.
+
+```ts
+interface ChartImage {
+  ok: boolean;
+  url?: string;
+  base64?: string;
+  bytes?: number;
+  error?: string;
+}
+```
+
+#### `ClaudeOptions` — interface · src/computer.ts
+
+```ts
+interface ClaudeOptions extends ToEndOptions {
+  sessionId?: string;
+  permissionMode?: "full" | "no_writes";
+}
+```
+
+#### `ClaudeOutcome` — interface · src/computer.ts
+
+```ts
+interface ClaudeOutcome extends CommandOutcome {
+  answer?: string;
+  sessionId?: string;
+  costUsd?: number;
+  isError?: boolean;
+}
+```
+
+#### `CommandOutcome` — interface · src/computer.ts
+
+What a command came back as. Flat: the repo an app compiles in may not narrow a union.
+
+```ts
+interface CommandOutcome {
+  ok: boolean;
+  status: CommandStatus;
+  commandId?: string;
+  command?: string;
+  exitCode?: number;
+  timedOut?: boolean;
+  durationMs?: number;
+  stdout?: string;
+  stderr?: string;
+  error?: string;
+  message?: string;
+  raw: string;
+  truncated?: boolean;
+}
+```
+
+#### `CommandStatus` — type · src/computer.ts
+
+```ts
+type CommandStatus = "pending_approval" | "approved" | "running" | "done" | "denied" | "failed" | "unknown";
+```
+
+#### `CompiledCustomRole` — interface · src/db/custom-roles.ts
+
+```ts
+interface CompiledCustomRole {
+  name: string;
+  base: string;
+  describe: string | null;
+  ops: string[];
+  models: Record<
+    string,
+    {
+      where: Record<string, WhereValue>;
+      hide: string[];
+      updateFields: string[] | null;
+      transitions: { field: string; moves: Record<string, string[]> } | null;
+    }
+  >;
+}
+```
+
+#### `Computer` — interface · src/computer.ts
+
+```ts
+interface Computer {
+  readonly machineNodeId: string;
+  status(): Promise<ComputerStatus>;
+  run(command: string, opts?: RunOptions): Promise<CommandOutcome>;
+  result(commandId: string, waitSeconds?: number): Promise<CommandOutcome>;
+  runToEnd(command: string, opts?: ToEndOptions): Promise<CommandOutcome>;
+  claude(prompt: string, opts?: ClaudeOptions): Promise<ClaudeOutcome>;
+  claudeToEnd(prompt: string, opts?: ClaudeOptions): Promise<ClaudeOutcome>;
+  readFile(path: string, opts?: { maxBytes?: number } & ToEndOptions): Promise<{ ok: boolean; text: string; error?: string }>;
+  fetchJson(url: string, opts?: { method?: "GET" | "POST"; body?: unknown; timeoutSeconds?: number } & ToEndOptions): Promise<{ ok: boolean; status?: number; json?: unknown; text: string; error?: string }>;
+  runJson<T = unknown>(command: string, opts?: ToEndOptions): Promise<JsonOutcome<T>>;
+  python<T = unknown>(script: string, opts?: { python?: string } & ToEndOptions): Promise<JsonOutcome<T>>;
+}
+```
+
+#### `ComputerStatus` — interface · src/computer.ts
+
+```ts
+interface ComputerStatus {
+  ok: boolean;
+  paired: boolean;
+  online: boolean;
+  hostname?: string;
+  os?: string;
+  autonomy?: "approve" | "auto";
+  pendingApproval?: number;
+  message?: string;
+  error?: string;
+  raw: string;
+}
+```
+
+#### `CustomRoleDefinitionRaw` — interface · src/db/custom-roles.ts
+
+What the owner wrote (the event's data, minus bookkeeping).
+
+```ts
+interface CustomRoleDefinitionRaw {
+  name: string;
+  base: string;
+  describe?: string;
+  ops?: string[];
+  models?: Record<
+    string,
+    {
+      where?: Record<string, WhereValue>;
+      hide?: string[];
+      update?: { fields?: string[]; transitions?: Record<string, string[]> };
+    }
+  >;
+}
+```
+
+#### `CustomRoleGrant` — interface · src/db/custom-roles.ts
+
+What a caller carries when they hold a composed role.
+
+```ts
+interface CustomRoleGrant {
+  role: CompiledCustomRole;
+  attrs: Record<string, AttrValue>;
+}
+```
+
+#### `CustomRolesEnvelope` — interface · src/db/custom-roles.ts
+
+```ts
+interface CustomRolesEnvelope {
+  attributes: string[];
+  models: Record<string, { where: string[]; hide: string[]; updateFields: string[]; transitions: string | null }>;
+  ops: string[];
+}
+```
+
+#### `EmitPluginAppEventArgs` — interface · src/server.ts
+
+```ts
+interface EmitPluginAppEventArgs {
+  source: {
+    pluginId: string;
+    workspaceId: string;
+    nodeId: string;
+    applicationType: string;
+  };
+  targetNodeId: string;
+  eventName: string;
+  eventData: Record<string, unknown>;
+}
+```
+
+#### `FileProviderContext` — interface · src/server.ts
+
+```ts
+interface FileProviderContext {
+  workspaceId: string;
+  userId: string;
+  connectionId?: string;
+  localMount?: { id: string; path: string; label?: string };
+}
+```
+
+#### `FileReadResult` — interface · src/server.ts
+
+```ts
+interface FileReadResult {
+  bytes: Buffer;
+  name: string;
+  contentType?: string;
+}
+```
+
+#### `FilesApi` — interface · src/server.ts
+
+```ts
+interface FilesApi {
+  sources(): Promise<FileSource[]>;
+  list(
+    sourceId: string,
+    folderRef?: string,
+    cursor?: string,
+    opts?: FileListOptions,
+  ): Promise<{ entries: FileEntry[]; next?: string }>;
+  listAll(
+    sourceId: string,
+    folderRef?: string,
+    opts?: FileListOptions & { max?: number },
+  ): Promise<{ entries: FileEntry[]; truncated: boolean }>;
+  resolvePath(
+    sourceId: string,
+    path: string,
+  ): Promise<{ found: boolean; entry: FileEntry | null; chain: FileEntry[]; missing?: string }>;
+  read(
+    ref: FileRef,
+    opts?: { capBytes?: number },
+  ): Promise<{ bytes: Buffer; name: string; contentType?: string }>;
+  readMany(
+    refs: FileRef[],
+    opts?: { capBytesEach?: number; as?: "text" | "base64" },
+  ): Promise<FileReadManyItem[]>;
+  getUrl(ref: FileRef): Promise<string | null>;
+  write(args: {
+    sourceId: string;
+    folderRef?: string;
+    name: string;
+    bytes: Buffer | Uint8Array | string;
+    contentType?: string;
+  }): Promise<FileWriteResult>;
+  readGrant(args: { sourceId: string; ttlSeconds?: number }): Promise<FileReadGrant>;
+  saveWorkspaceFile(args: {
+    name: string;
+    bytes: Buffer | Uint8Array | string;
+    contentType?: string;
+    folderPath?: string;
+  }): Promise<{ fileId: string; name: string; blobPath: string; deduped: boolean }>;
+  // … (see the source)
+}
+```
+
+#### `GeneratedAppImage` — interface · src/server.ts
+
+```ts
+interface GeneratedAppImage {
+  ok: boolean;
+  url?: string;
+  bytes?: number;
+  model?: string;
+  error?: string;
+}
+```
+
+#### `JsonOutcome` — interface · src/computer.ts
+
+Flat, like every outcome here. `ok` with `json`; otherwise `error` in words.
+
+```ts
+interface JsonOutcome<T = unknown> {
+  ok: boolean;
+  json?: T;
+  status: CommandStatus;
+  commandId?: string;
+  exitCode?: number;
+  stderr?: string;
+  error?: string;
+  message?: string;
+  truncated?: boolean;
+}
+```
+
+#### `PluginConnectionCredentials` — type · src/server.ts
+
+```ts
+type PluginConnectionCredentials =
+  | { kind: "oauth2"; accessToken: string }
+  | { kind: "apiKey"; apiKey?: string; headers?: Record<string, string> };
+```
+
+#### `PluginFileProviderImpl` — interface · src/server.ts
+
+A file provider your plugin CONTRIBUTES (manifest `fileProviders` + `pluginServer.fileProviders[key]`): the browse/read half of a mount backed by one of your declared connections. The host derives one mount per ACTIVE connection and calls you with `ctx.connectionId` set — resolve credentials yourself via `getPluginConnectionCredentials`. A backend that cannot answer must THROW FileSourceError("source_unavailable"), never return an empty listing; reads must respect `capBytes`.
+
+```ts
+interface PluginFileProviderImpl {
+  list(
+    ctx: FileProviderContext,
+    sourceId: string,
+    folderRef?: string,
+    cursor?: string,
+    opts?: FileListOptions,
+  ): Promise<{ entries: FileEntry[]; next?: string }>;
+  read(
+    ctx: FileProviderContext,
+    sourceId: string,
+    ref: string,
+    capBytes: number,
+  ): Promise<FileReadResult>;
+}
+```
+
+#### `PluginFilesCtx` — interface · src/server.ts
+
+```ts
+interface PluginFilesCtx {
+  pluginId: string;
+  workspaceId: string;
+  sourceNodeId?: string;
+  applicationType?: string;
+  origin?: string;
+}
+```
+
+#### `PluginOpContext` — interface · src/server.ts
+
+```ts
+interface PluginOpContext {
+  pluginId: string;
+  opName: string;
+  workspaceId: string;
+  nodeId: string;
+  instanceName: string;
+  cloudConnectionId: string | null;
+  viewer: PluginViewer;
+  args: unknown;
+  origin?: string;
+  notify(topic: string, data: unknown, opts?: { to?: { viewerIds: string[] } | { role: string } }): Promise<void>;
+  emit(eventName: string, eventData: Record<string, unknown>): Promise<void>;
+  apps: Record<string, {
+    nodeId: string;
+    applicationType: string;
+    via: string;
+    state(): Promise<Record<string, unknown>>;
+    call(tool: string, args?: Record<string, unknown>): Promise<{ ok: boolean; text: string }>;
+  }>;
+}
+```
+
+#### `PluginOpHandler` — type · src/server.ts
+
+```ts
+type PluginOpHandler = (ctx: PluginOpContext) => Promise<unknown>;
+```
+
+#### `PluginRouteContext` — interface · src/server.ts
+
+A server ROUTE the app brings with it: `GET|POST /api/plugins/<id>/route/<name>?nodeId=…` (declared in plugin.json `routes`). Unlike an op it owns the whole Response — it may stream (Server-Sent Events via `sseStream`), set headers, return bytes. The platform resolves the instance and the caller's access before the handler runs; the handler never sees an unauthenticated request. It runs where the platform's own API routes run (Fluid compute, minutes-long invocations allowed), so a clock, a poller or a long-poll can live here — for as long as ONE request lasts. Anything that must outlive a request is a task (docs/07).
+
+```ts
+interface PluginRouteContext {
+  pluginId: string;
+  routeName: string;
+  method: "GET" | "POST";
+  request: Request;
+  searchParams: URLSearchParams;
+  workspaceId: string;
+  nodeId: string;
+  instanceName: string;
+  applicationType: string;
+  cloudConnectionId: string | null;
+  canWrite: boolean;
+  viewer: PluginViewer;
+}
+```
+
+#### `PluginRouteHandler` — type · src/server.ts
+
+```ts
+type PluginRouteHandler = (ctx: PluginRouteContext) => Promise<Response>;
+```
+
+#### `PluginServerModule` — interface · src/server.ts
+
+```ts
+interface PluginServerModule {
+  webhooks?: Record<string, PluginWebhookHandler>;
+  ops?: Record<string, PluginOpHandler>;
+  routes?: Record<string, PluginRouteHandler>;
+}
+```
+
+#### `PluginViewer` — interface · src/server.ts
+
+```ts
+interface PluginViewer {
+  kind: PluginViewerKind;
+  userId: string | null;
+  viewerIds: string[];
+  role: string;
+  customRole?: string | null;
+  custom?: CustomRoleGrant | null;
+  attrs?: Record<string, AttrValue>;
+  canWrite: boolean;
+  shareId: string | null;
+  agent?: { runId?: string; onBehalfOf: Omit<PluginViewer, "agent"> };
+}
+```
+
+#### `PluginViewerKind` — type · src/server.ts
+
+WHO is calling. MIRRORS the host (src/lib/plugins/viewer.ts).
+
+```ts
+type PluginViewerKind =
+  | "owner"
+  | "member"
+  | "visitor"
+  | "anonymous"
+  | "agent"
+  | "internal";
+```
+
+#### `PluginWebhookContext` — interface · src/server.ts
+
+Server half of a plugin package (`server.ts` in your plugin folder). Runs ONLY inside the ExternalSoul host (imported by the generic webhook/op routes) — it may use prisma, node crypto, provider SDKs.
+
+```ts
+interface PluginWebhookContext {
+  request: Request;
+  secret: string | null;
+  method: string;
+  pluginId: string;
+  hookName: string;
+  sendInngestEvent(name: string, data: Record<string, unknown>): Promise<void>;
+}
+```
+
+#### `PluginWebhookHandler` — type · src/server.ts
+
+```ts
+type PluginWebhookHandler = (
+  ctx: PluginWebhookContext,
+) => Promise<Response>;
+```
+
+#### `RouteTokenGrant` — interface · src/server.ts
+
+```ts
+interface RouteTokenGrant {
+  token: string;
+  url: string;
+  expiresAt: number;
+}
+```
+
+#### `RunOptions` — interface · src/computer.ts
+
+```ts
+interface RunOptions {
+  cwd?: string;
+  timeoutSeconds?: number;
+  waitSeconds?: number;
+}
+```
+
+#### `ToEndOptions` — interface · src/computer.ts
+
+```ts
+interface ToEndOptions extends RunOptions {
+  deadlineMs?: number;
+  waitForApproval?: boolean;
+  onWait?: (o: CommandOutcome) => void | Promise<void>;
+}
+```
+
+#### `ViewerProfile` — interface · src/server.ts
+
+```ts
+interface ViewerProfile {
+  userId: string;
+  email: string | null;
+  name: string | null;
+  picture: string | null;
+}
+```
+
+==============================================================================
+## `esoul-sdk/react` — 46 exports
+
+The app's UI: hooks for the viewer, the app's state, realtime, workspace files and tools.
+
+### Functions and values (22)
+
+#### `FilesBrowseError` — class · src/react.ts
+
+A files call from the UI refused — `kind` is the FileSourceErrorKind when the source said why.
+
+```ts
+class FilesBrowseError extends Error { … }
+```
+
+#### `ImageLabeler` — function · src/react.ts
+
+A polygon labeller for one image — the Explorer's mask editor as a component: zoom to 64×, pan, draw, drag/insert/delete vertices, move a whole shape, stamp copies with rotate and scale, undo, a class rail with counts and hide, a shape list. It stores nothing: shapes go in as `initialShapes` and come out of `onSave`. Keys: D draw · E edit · Enter close · Delete remove · Ctrl+Z undo · Ctrl+S save · 1–9 class · [ ] previous/next. Give its parent a height (`display:flex`, `minHeight:0`).
+
+```ts
+function ImageLabeler(_props: ImageLabelerProps): any
+```
+
+#### `listFileEntries` — function · src/react.ts
+
+One page of a folder, as a plain call (no hook).
+
+```ts
+function listFileEntries(_workspaceId: string, _sourceId: string, _folderRef?: string, _opts?: FileListOptions, _cursor?: string): Promise<FilesPage>
+```
+
+#### `PolygonCanvas` — function · src/react.ts
+
+The bare polygon canvas under `ImageLabeler`, for an app that brings its own toolbar and state. Points are ORIGINAL IMAGE PIXELS.
+
+```ts
+function PolygonCanvas(_props: PolygonCanvasProps): any
+```
+
+#### `rankFolderSuggestions` — function · src/react.ts
+
+Folders matching what is being typed: names that START with it, then names that contain it. Pure.
+
+```ts
+function rankFolderSuggestions(entries: FileEntry[], partial: string, limit = 50): FileEntry[]
+```
+
+#### `resolveFilePath` — function · src/react.ts
+
+Walk "a/b/c" from the source's root by exact names, as a plain call.
+
+```ts
+function resolveFilePath(_workspaceId: string, _sourceId: string, _path: string): Promise<ResolvedFilePath>
+```
+
+#### `splitTypedPath` — function · src/react.ts
+
+"sheets/quality/Ty" → `{ parentPath: "sheets/quality", partial: "Ty" }`; a trailing "/" means "inside it". Pure.
+
+```ts
+function splitTypedPath(text: string): { parentPath: string; partial: string }
+```
+
+#### `useAppCanEdit` — function · src/react.ts
+
+True when the current viewer may mutate this workspace.
+
+```ts
+function useAppCanEdit(): boolean
+```
+
+#### `useFileSourceEntries` — function · src/react.ts
+
+One folder's listing; a failing source reports error/errorKind, never []. `opts` narrows AT THE SOURCE — `{ only: "folder" }`, `{ nameContains }`, `{ orderBy: "name", pageSize: 1000 }` — and `loadMore()` appends the next page.
+
+```ts
+function useFileSourceEntries( _workspaceId: string | null, _sourceId: string | null, _folderRef?: string, _opts?: FileListOptions, ): FileEntriesState
+```
+
+#### `useFileSources` — function · src/react.ts
+
+All mounts the signed-in user can see for this workspace. Works in a Forge preview.
+
+```ts
+function useFileSources(_workspaceId: string | null): FileSourcesState
+```
+
+#### `useFileUrls` — function · src/react.ts
+
+`urlOf(ref, { width })` for an `<img>` of a file of this source — installed it is a same-origin URL on the person's session; in a Forge preview it is built on a read grant, renewed before it ends. Never build these URLs by hand.
+
+```ts
+function useFileUrls(_workspaceId: string | null, _sourceId: string | null): FileUrlsState
+```
+
+#### `useFolderAutocomplete` — function · src/react.ts
+
+A folder box with autocomplete: give it the text being typed ("sheets/quality_dataset/Ty") and render `suggestions` under the input. The folder being typed INTO is resolved once and its subfolders cached, so a keystroke costs no request. Keep the chosen folder by its `ref`, not its path.
+
+```ts
+function useFolderAutocomplete(_workspaceId: string | null, _sourceId: string | null, _text: string): FolderAutocompleteState
+```
+
+#### `usePluginCurrentChatId` — function · src/react.ts
+
+Current open chat id, for `chatIdSource` attribution.
+
+```ts
+function usePluginCurrentChatId(): string
+```
+
+#### `usePluginEventDispatch` — function · src/react.ts
+
+Dispatch a workspace event from your UI — the ONLY sanctioned path. Respects read-only viewers (no-op when the viewer cannot edit).
+
+```ts
+function usePluginEventDispatch(): ( evt: EventData<any>, ) => EventData<any> | null
+```
+
+#### `usePluginFileUpload` — function · src/react.ts
+
+Upload a browser File into the workspace (blob → row → live list).
+
+```ts
+function usePluginFileUpload( _workspaceId: string, ): (file: File) => Promise<PluginWorkspaceFile>
+```
+
+#### `usePluginRealtime` — function · src/react.ts
+
+Subscribe to this instance's channel (the one you declared with `definePluginChannel` and put on the schema as `channel`). A task publishes with `ctx.notify(topic, data)`; each message arrives here as `{ topic, data }`. Realtime is a NUDGE, never the truth: anything that must survive a refresh goes on the timeline as an event as well.
+
+```ts
+function usePluginRealtime<T = unknown>(_args: { channel: (p: { workspaceId: string; nodeId: string }) => unknown; workspaceId: string; nodeId: string; topics: readonly string[]; enabled?: boolean; }): PluginRealtime<T>
+```
+
+#### `usePluginWorkspaceFiles` — function · src/react.ts
+
+The current workspace's file catalogue, live from the store.
+
+```ts
+function usePluginWorkspaceFiles(): PluginWorkspaceFile[]
+```
+
+#### `useRemoteReconcile` — function · src/react.ts
+
+The ONE way a mounted editor takes a change from another device, another tab or an agent while the person may be typing: merged into the editor when your data allows it, adopted when idle, held back (with your saves fenced so nothing is overwritten silently) when it cannot be merged. See docs/17-editing-and-merging.md.
+
+```ts
+function useRemoteReconcile<T>(_opts: RemoteReconcileOptions<T>): RemoteReconcile<T>
+```
+
+#### `useSignInWall` — function · src/react.ts
+
+The sign-in wall: raised by a `login-required` refusal, never by a guess.
+
+```ts
+function useSignInWall(): SignInWall
+```
+
+#### `useViewer` — function · src/react.ts
+
+The identity of the person looking at this instance, resolved by the platform.
+
+```ts
+function useViewer(): PluginViewerPublic
+```
+
+#### `useWorkspaceNav` — function · src/react.ts
+
+Where the app is being read, and the one move a page inside a desktop may offer: open the app picker. A website app shown on someone's desktop uses it instead of linking to the page it is already on.
+
+```ts
+function useWorkspaceNav(): WorkspaceNav
+```
+
+#### `useWorkspaceTools` — function · src/react.ts
+
+Invoke tools of OTHER apps in the workspace (append a spreadsheet row, add a calendar event…). Declare each as "<applicationType>:<tool>" in plugin.json `workspaceTools` — that list is the grant wall once installed. In the Forge's live preview the same call rides the board's tab to the owner's real workspace, so a plugin under construction already talks to its neighbours. Pass the app's identity from its state.
+
+```ts
+function useWorkspaceTools(_identity: { workspaceId: string; nodeId: string }): WorkspaceTools
+```
+
+### Types (24)
+
+#### `FileEntriesState` — interface · src/react.ts
+
+```ts
+interface FileEntriesState {
+  entries: FileEntry[];
+  next: string | null;
+  loading: boolean;
+  error: string | null;
+  errorKind: string | null;
+  reload: () => void;
+  hasMore: boolean;
+  loadMore: () => void;
+}
+```
+
+#### `FileSourcesState` — interface · src/react.ts
+
+```ts
+interface FileSourcesState {
+  sources: FileSource[];
+  loading: boolean;
+  error: string | null;
+  reload: () => void;
+}
+```
+
+#### `FilesPage` — interface · src/react.ts
+
+One page of a folder.
+
+```ts
+interface FilesPage {
+  entries: FileEntry[];
+  next?: string;
+}
+```
+
+#### `FileUrlOf` — type · src/react.ts
+
+A file of a source → a URL an `<img>` can load; `{ width }` asks for a thumbnail.
+
+```ts
+type FileUrlOf = (ref: FileRef | string, opts?: { width?: number }) => string;
+```
+
+#### `FileUrlsState` — interface · src/react.ts
+
+```ts
+interface FileUrlsState {
+  ready: boolean;
+  error: string | null;
+  urlOf: FileUrlOf;
+}
+```
+
+#### `FolderAutocompleteState` — interface · src/react.ts
+
+```ts
+interface FolderAutocompleteState {
+  suggestions: FileEntry[];
+  loading: boolean;
+  error: string | null;
+  chain: FileEntry[];
+  pathWith: (entry: FileEntry) => string;
+  resolve: () => Promise<{ entry: FileEntry; chain: FileEntry[]; path: string } | null>;
+}
+```
+
+#### `ImageLabelerProps` — interface · src/react.ts
+
+```ts
+interface ImageLabelerProps {
+  imageUrl: string;
+  imageName?: string;
+  classes: LabelClass[];
+  initialShapes: LabelShape[];
+  seedKey: string;
+  onSave?: (shapes: LabelShape[], size: { width: number; height: number }) => Promise<void> | void;
+  onChange?: (shapes: LabelShape[], info: { dirty: boolean }) => void;
+  onPrev?: () => void;
+  onNext?: () => void;
+  readOnly?: boolean;
+  loading?: boolean;
+  isDark?: boolean;
+  unknownClassColor?: string;
+  style?: Record<string, string | number>;
+}
+```
+
+#### `LabelClass` — interface · src/react.ts
+
+One class a shape may have. `name` is what is written to the label file, exactly.
+
+```ts
+interface LabelClass {
+  name: string;
+  color: string;
+  title?: string;
+}
+```
+
+#### `PluginRealtime` — interface · src/react.ts
+
+```ts
+interface PluginRealtime<T = unknown> {
+  data: PluginRealtimeMessage<T>[];
+  latestData: PluginRealtimeMessage<T> | null;
+  error: Error | null;
+  state: string;
+}
+```
+
+#### `PluginRealtimeMessage` — interface · src/react.ts
+
+```ts
+interface PluginRealtimeMessage<T = unknown> {
+  topic: string;
+  data: T;
+}
+```
+
+#### `PluginViewerKind` — type · src/server.ts
+
+WHO is calling. MIRRORS the host (src/lib/plugins/viewer.ts).
+
+```ts
+type PluginViewerKind =
+  | "owner"
+  | "member"
+  | "visitor"
+  | "anonymous"
+  | "agent"
+  | "internal";
+```
+
+#### `PluginViewerPublic` — interface · src/react.ts
+
+What the browser is allowed to know about the caller (never `viewerIds`).
+
+```ts
+interface PluginViewerPublic {
+  kind: PluginViewerKind;
+  userId: string | null;
+  role: string;
+  canEdit: boolean;
+  signedIn: boolean;
+  customRole?: string | null;
+  attrs?: Record<string, AttrValue>;
+  can?: { ops: string[]; models: Record<string, { hide: string[]; updateFields: string[] | null; moves: Record<string, string[]> | null }> } | null;
+}
+```
+
+#### `PluginWorkspaceFile` — interface · src/react.ts
+
+```ts
+interface PluginWorkspaceFile {
+  id: string;
+  name: string;
+  url: string;
+}
+```
+
+#### `PolygonCanvasProps` — interface · src/react.ts
+
+```ts
+interface PolygonCanvasProps {
+  imageUrl: string;
+  shapes: PolygonCanvasShape[];
+  activeShapeId: string | null;
+  classColors: Record<string, string>;
+  isDrawing: boolean;
+  onPointAdd: (p: LabelPoint) => void;
+  onPointMove: (shapeId: string, index: number, p: LabelPoint) => void;
+  onPointInsert: (shapeId: string, afterIndex: number, p: LabelPoint) => void;
+  onPointDelete?: (shapeId: string, index: number) => boolean;
+  onPolygonTranslate?: (shapeId: string, dx: number, dy: number) => void;
+  onEditEnd: () => void;
+  onSelectShape: (shapeId: string | null) => void;
+  onCloseActive?: () => void;
+  onImageSize?: (size: { width: number; height: number }) => void;
+  isDark?: boolean;
+  stampTemplate?: { points: LabelPoint[] } | null;
+  stampColor?: string;
+  onStampPlace?: (points: LabelPoint[]) => void;
+  onStampExit?: () => void;
+}
+```
+
+#### `PolygonCanvasShape` — interface · src/react.ts
+
+A shape as the bare canvas draws it.
+
+```ts
+interface PolygonCanvasShape {
+  id: string;
+  points: LabelPoint[];
+  className: string;
+  hidden?: boolean;
+}
+```
+
+#### `RemoteReconcile` — interface · src/react.ts
+
+```ts
+interface RemoteReconcile<T> {
+  noteOwnSave: (value: T, itemKey?: string) => void;
+  baseFor: (itemKey?: string) => T | undefined;
+  recheck: () => void;
+  lastDecision: () => "echo" | "converged" | "stale-own" | "wait-save" | "merge" | "wait-idle" | "adopt" | null;
+}
+```
+
+#### `RemoteReconcileOptions` — interface · src/react.ts
+
+```ts
+interface RemoteReconcileOptions<T> {
+  nodeId: string;
+  itemKey: string | null;
+  state: unknown;
+  incoming: T | undefined;
+  getCurrent: () => T;
+  equal?: (a: T, b: T) => boolean;
+  isPending: () => boolean;
+  isEditing?: () => boolean;
+  merge?: (base: T, mine: T, theirs: T) => T | null;
+  mergeWhileEditing?: boolean;
+  apply: (value: T, info: { reason: "adopt" | "merge"; needsSave: boolean; base?: T; theirs?: T }) => void;
+  onStaleOwn?: (base: T) => void;
+  tag?: string;
+  sessionId?: string;
+}
+```
+
+#### `ResolvedFilePath` — interface · src/react.ts
+
+A typed path, walked: `found` false names the `missing` segment; `chain` is what was there.
+
+```ts
+interface ResolvedFilePath {
+  found: boolean;
+  entry: FileEntry | null;
+  chain: FileEntry[];
+  missing?: string;
+}
+```
+
+#### `SignInWall` — interface · src/react.ts
+
+```ts
+interface SignInWall {
+  needed: boolean;
+  reason: string | null;
+  signIn: () => void;
+  raise: (err: unknown) => void;
+  ask: <T>(call: () => Promise<T>) => Promise<T | null>;
+  serverSays: null | "account" | "no-account";
+}
+```
+
+#### `WorkspaceAppSummary` — interface · src/react.ts
+
+```ts
+interface WorkspaceAppSummary {
+  nodeId: string;
+  applicationType: string;
+  instanceName: string;
+}
+```
+
+#### `WorkspaceNav` — interface · src/react.ts
+
+```ts
+interface WorkspaceNav {
+  inside: boolean;
+  openAppPicker: () => void;
+}
+```
+
+#### `WorkspaceToolCall` — interface · src/react.ts
+
+```ts
+interface WorkspaceToolCall {
+  appType?: string;
+  targetNodeId?: string;
+  tool: string;
+  args?: Record<string, unknown>;
+}
+```
+
+#### `WorkspaceToolResult` — interface · src/react.ts
+
+```ts
+interface WorkspaceToolResult {
+  ok: boolean;
+  text: string;
+}
+```
+
+#### `WorkspaceTools` — interface · src/react.ts
+
+```ts
+interface WorkspaceTools {
+  available: boolean;
+  workspaceName: string | null;
+  call: (c: WorkspaceToolCall) => Promise<WorkspaceToolResult>;
+  listApps: () => Promise<WorkspaceAppSummary[]>;
+}
+```
+
+==============================================================================
+## `esoul-sdk/testing` — 21 exports
+
+Tests: run an op as a persona, an in-memory database with the real rules, recorders.
+
+### Functions and values (8)
+
+#### `capture` — function · src/testing/ops.ts
+
+A call recorder, for anything `runOp` does not already capture.
+
+```ts
+function capture<A extends unknown[] = unknown[]>(): Recorder<A>
+```
+
+#### `fakeApps` — function · src/testing/ops.ts
+
+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.
+
+```ts
+function fakeApps(fixtures: Record<string, BoundAppFixture>): Record<string, unknown>
+```
+
+#### `fakeViewer` — function · src/testing/db.ts
+
+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`.
+
+```ts
+function fakeViewer( kind: ViewerKind, opts: { userId?: string | null; viewerIds?: string[]; role?: string; name?: string | null; email?: string | null; attrs?: Record<string, string | number | boolean> } = {}, ): RuleViewer
+```
+
+#### `memoryDb` — function · src/testing/db.ts
+
+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.
+
+```ts
+function memoryDb(manifest: TestManifest, options: MemoryDbOptions = {}): MemoryDbHandle
+```
+
+#### `memoryFiles` — function · src/testing/files.ts
+
+An in-memory `FilesApi` over a tree you write in the test: folders are objects, files are text or bytes. Same semantics as the platform's — narrowed listings, exact-name path walk, replace-by-name writes, typed errors.
+
+```ts
+function memoryFiles(sources: Record<string, MemoryFileTree>, opts?: { readOnly?: string[] }): MemoryFiles
+```
+
+#### `roleForKind` — function · src/testing/db.ts
+
+The app's own word for a kind of caller, read from the manifest's `roles`.
+
+```ts
+function roleForKind(manifest: TestManifest, kind: ViewerKind): string
+```
+
+#### `runOp` — function · src/testing/ops.ts
+
+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.
+
+```ts
+async function runOp<T = unknown>( server: ServerModuleLike, opName: string, options: RunOpOptions, ): Promise<RunOpResult<T>>
+```
+
+#### `startMockOAuth` — function · src/testing/index.ts
+
+A real (tiny) OAuth2 provider for exercising the plugin-connection flow: /authorize (PKCE challenge bound to a one-time code), /token (authorization_code with verifier check + refresh_token grant), and a Bearer-gated /api/items resource. Access tokens expire fast (default 20s) so refresh paths are exercised without waiting.
+
+```ts
+function startMockOAuth(opts?: { port?: number; clientId?: string; accessTtlMs?: number; }): Promise<MockOAuthServer>
+```
+
+### Types (13)
+
+#### `BoundAppFixture` — interface · src/testing/ops.ts
+
+```ts
+interface BoundAppFixture {
+  nodeId?: string;
+  applicationType?: string;
+  state?: Record<string, unknown>;
+  tools?: Record<string, (args?: Record<string, unknown>) => Promise<{ ok: boolean; text: string }> | { ok: boolean; text: string }>;
+  db?: MemoryDbHandle;
+}
+```
+
+#### `EmitCall` — interface · src/testing/ops.ts
+
+```ts
+interface EmitCall {
+  eventName: string;
+  eventData: Record<string, unknown>;
+}
+```
+
+#### `MemoryDbHandle` — interface · src/testing/db.ts
+
+```ts
+interface MemoryDbHandle extends MemoryDb {
+  as(viewer: RuleViewer | ViewerKind, opts?: Record<string, unknown>): MemoryDbHandle;
+  $rules: CompiledRules;
+}
+```
+
+#### `MemoryDbOptions` — interface · src/testing/db.ts
+
+```ts
+interface MemoryDbOptions {
+  viewer?: RuleViewer | ViewerKind;
+  workspaceId?: string;
+  nodeId?: string;
+  store?: MemoryStore;
+  viaBinding?: boolean;
+  across?: "owned-instances" | "my-rows";
+  ownedWorkspaceIds?: string[];
+}
+```
+
+#### `MemoryFiles` — interface · src/testing/files.ts
+
+```ts
+interface MemoryFiles extends FilesApi {
+  textAt(sourceId: string, path: string): string | null;
+  writes: { sourceId: string; folderRef?: string; name: string; created: boolean }[];
+  failNext(method: keyof FilesApi, error: Error): void;
+}
+```
+
+#### `MemoryFileTree` — interface · src/testing/files.ts
+
+A folder is an object; a file is its text, or its bytes.
+
+```ts
+interface MemoryFileTree {
+  [name: string]: string | Uint8Array | MemoryFileTree;
+}
+```
+
+#### `MockOAuthServer` — interface · src/testing/index.ts
+
+```ts
+interface MockOAuthServer {
+  port: number;
+  url: string;
+  close(): Promise<void>;
+}
+```
+
+#### `NotifyCall` — interface · src/testing/ops.ts
+
+```ts
+interface NotifyCall {
+  topic: string;
+  data: unknown;
+  to?: unknown;
+}
+```
+
+#### `Recorder` — interface · src/testing/ops.ts
+
+```ts
+interface Recorder<A extends unknown[]> {
+  fn: (...args: A) => Promise<void>;
+  calls: A[];
+}
+```
+
+#### `RunOpOptions` — interface · src/testing/ops.ts
+
+```ts
+interface RunOpOptions {
+  viewer: RuleViewer;
+  args?: unknown;
+  db?: MemoryDbHandle;
+  apps?: Record<string, unknown>;
+  pluginId?: string;
+  workspaceId?: string;
+  nodeId?: string;
+  instanceName?: string;
+  cloudConnectionId?: string | null;
+  notifyFails?: (topic: string, to: unknown) => unknown;
+}
+```
+
+#### `RunOpResult` — interface · src/testing/ops.ts
+
+```ts
+interface RunOpResult<T = unknown> {
+  result: T;
+  notified: NotifyCall[];
+  emitted: EmitCall[];
+}
+```
+
+#### `TestManifest` — interface · src/testing/db.ts
+
+The parts of a plugin.json these helpers read.
+
+```ts
+interface TestManifest {
+  id?: string;
+  db?: Record<string, never>;
+  roles?: { vocabulary?: string[]; default?: Record<string, string>; custom?: import("../db/custom-roles.js").CustomRolesEnvelopeRaw; attributes?: Record<string, string> };
+  ops?: unknown;
+  routes?: unknown;
+  kickableTasks?: unknown;
+}
+```
+
+#### `ViewerKind` — type · src/testing/db.ts
+
+```ts
+type ViewerKind = RuleViewer["kind"];
+```