esoul-sdk 0.16.0 → 0.17.0

package/api-reference.md

@@ -2583,11 +2583,27 @@ interface ViewerProfile {
 ```
 
 ==============================================================================
-## `esoul-sdk/react` — 46 exports
+## `esoul-sdk/react` — 52 exports
 
 The app's UI: hooks for the viewer, the app's state, realtime, workspace files and tools.
 
-### Functions and values (22)
+### Functions and values (27)
+
+#### `describeFailure` — function · src/failed-requests.ts
+
+Words and retryability for a thrown request: `PluginCallError` carries status + code; a fetch that never reached the server throws a TypeError.
+
+```ts
+function describeFailure(error: unknown): { why: string; retryable: boolean }
+```
+
+#### `dismissFailedRequest` — function · src/failed-requests.ts
+
+Take a request off the banner — it landed after all, or the person dismissed it.
+
+```ts
+function dismissFailedRequest(key: string): void
+```
 
 #### `FilesBrowseError` — class · src/react.ts
 
@@ -2605,6 +2621,14 @@ A polygon labeller for one image — the Explorer's mask editor as a component:
 function ImageLabeler(_props: ImageLabelerProps): any
 ```
 
+#### `isRetryableFailure` — function · src/failed-requests.ts
+
+Is this failure worth a Try again? A lost connection, a timeout, a server error or a rate limit — yes. A refusal (the server read the request and said no, with a reason) — retrying sends the same no; the app shows the reason instead.
+
+```ts
+function isRetryableFailure(r: { reason?: string; status?: number }): boolean
+```
+
 #### `listFileEntries` — function · src/react.ts
 
 One page of a folder, as a plain call (no hook).
@@ -2629,6 +2653,14 @@ Folders matching what is being typed: names that START with it, then names that
 function rankFolderSuggestions(entries: FileEntry[], partial: string, limit = 50): FileEntry[]
 ```
 
+#### `reportFailedRequest` — function · src/failed-requests.ts
+
+Report a request that failed after the screen already showed it; the banner names it (and offers Try again when `retry` is given). The same `key` replaces, never stacks.
+
+```ts
+function reportFailedRequest(r: Omit<FailedRequest, "at" | "retrying"> & { at?: number }): void
+```
+
 #### `resolveFilePath` — function · src/react.ts
 
 Walk "a/b/c" from the source's root by exact names, as a plain call.
@@ -2637,6 +2669,14 @@ Walk "a/b/c" from the source's root by exact names, as a plain call.
 function resolveFilePath(_workspaceId: string, _sourceId: string, _path: string): Promise<ResolvedFilePath>
 ```
 
+#### `runOptimistic` — function · src/failed-requests.ts
+
+The optimistic-UI rule in one call. `apply` puts the result on screen at once; `send` does the work; on success any earlier failure of the same `key` clears. On failure `revert` puts the screen back and the request is reported: a connection loss, timeout or server error gets Try again (which runs the whole thing again, apply included), a refusal shows its reason only — retrying would send the same no.
+
+```ts
+async function runOptimistic<T>(r: { key: string; what: string; apply?: () => void; revert?: () => void; send: () => Promise<T>; }): Promise<{ ok: true; result: T } | { ok: false; error: unknown }>
+```
+
 #### `splitTypedPath` — function · src/react.ts
 
 "sheets/quality/Ty" → `{ parentPath: "sheets/quality", partial: "Ty" }`; a trailing "/" means "inside it". Pure.
@@ -2765,7 +2805,22 @@ Invoke tools of OTHER apps in the workspace (append a spreadsheet row, add a cal
 function useWorkspaceTools(_identity: { workspaceId: string; nodeId: string }): WorkspaceTools
 ```
 
-### Types (24)
+### Types (25)
+
+#### `FailedRequest` — interface · src/failed-requests.ts
+
+The platform's list of requests that failed after the UI already showed their result (the optimistic-UI rule, app-style-guide.md "Interaction"): an app updates the screen at once, and when the request behind it fails the app puts the screen back and reports here — `<FailedRequestBanner/>` then names the request and offers Try again, in the same place and style as the "new version is available" pill. Pure and framework-free, so any app (built-in or Forge) and any test can use it. A Forge app imports it from `esoul-sdk/react`; the platform's `src/lib/failed-requests.ts` re-exports this very module, so both reach one list.
+
+```ts
+interface FailedRequest {
+  key: string;
+  what: string;
+  why?: string;
+  retry?: () => Promise<boolean> | boolean;
+  at: number;
+  retrying?: boolean;
+}
+```
 
 #### `FileEntriesState` — interface · src/react.ts
 

package/dist/db/client-core.d.ts

@@ -92,9 +92,19 @@ export declare function assertFilterShape(c: Core, where: Record<string, unknown
 export declare function insensitiveContains(where: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
 export type OrderBy = Record<string, "asc" | "desc"> | Record<string, "asc" | "desc">[];
 export declare function orderTerms(c: Core, orderBy: OrderBy | undefined): Record<string, "asc" | "desc">[];
+/**
+ * The order a page is read in, made TOTAL: the author's terms, then `id`. A cursor
+ * names a row by id, so the rows after it are well defined only when no two rows
+ * tie — ordering by `date` alone let Postgres return rows sharing the cursor's date
+ * twice or not at all (Achievement Network's demo seed read an achievement twice on
+ * its second page, 2026-09-29). Without an orderBy and without a cursor the order is
+ * left alone (insertion order in memory, the database's own otherwise).
+ */
+export declare function totalOrder(terms: Record<string, "asc" | "desc">[], cursor: unknown): Record<string, "asc" | "desc">[];
 export declare function pageWindow(c: Core, args: {
     take?: number;
     skip?: number;
+    cursor?: unknown;
 } | undefined): {
     take: number;
     skip: number;

package/dist/db/client-core.js

@@ -142,6 +142,19 @@ export function orderTerms(c, orderBy) {
         assertFilterable(c, Object.keys(t), "orderBy");
     return terms;
 }
+/**
+ * The order a page is read in, made TOTAL: the author's terms, then `id`. A cursor
+ * names a row by id, so the rows after it are well defined only when no two rows
+ * tie — ordering by `date` alone let Postgres return rows sharing the cursor's date
+ * twice or not at all (Achievement Network's demo seed read an achievement twice on
+ * its second page, 2026-09-29). Without an orderBy and without a cursor the order is
+ * left alone (insertion order in memory, the database's own otherwise).
+ */
+export function totalOrder(terms, cursor) {
+    if (!terms.length && !cursor)
+        return terms;
+    return terms.some((t) => "id" in t) ? terms : [...terms, { id: "asc" }];
+}
 export function pageWindow(c, args) {
     const take = args?.take ?? DEFAULT_TAKE;
     if (take > MAX_TAKE)
@@ -151,6 +164,10 @@ export function pageWindow(c, args) {
     const skip = args?.skip ?? 0;
     if (skip < 0)
         bad(c, "skip must not be negative");
+    // Prisma's idiom is `cursor` + `skip: 1` (its cursor row is included); here the rows
+    // AFTER the cursor come back, so that `skip: 1` silently dropped a row per page.
+    if (args?.cursor && skip)
+        bad(c, "skip with cursor: the cursor's own row is already left out — drop skip");
     return { take, skip };
 }
 /** Seeing soft-deleted rows is the owner's (or the app's own task's). */

package/dist/db/compile-rules.d.ts

@@ -189,6 +189,13 @@ export interface ManifestDbModel {
 }
 export interface CompileInput {
     pluginId: string;
+    /**
+     * The app's `applicationType` — the prefix of every table it owns. Optional
+     * because an author's tests may compile a bare `db` block; when it is known,
+     * the compiler refuses a table name Postgres would truncate (and the
+     * generator, which always knows it, refuses the same).
+     */
+    applicationType?: string;
     db: Record<string, ManifestDbModel>;
     /** From `roles.vocabulary`; a rule may only name a role this app declares. */
     vocabulary?: string[];
@@ -216,6 +223,7 @@ export interface CompileInput {
  */
 export interface ManifestForRules {
     id?: string;
+    applicationType?: string;
     db?: Record<string, ManifestDbModel> | Record<string, never> | null;
     roles?: {
         vocabulary?: string[];
@@ -238,6 +246,29 @@ export declare class RuleCompileError extends Error {
     readonly keyPath: string;
     constructor(keyPath: string, message: string);
 }
+/**
+ * An app's tables, columns and indexes are Postgres identifiers in ONE shared
+ * schema. Postgres silently TRUNCATES an identifier past 63 bytes
+ * (NAMEDATALEN − 1) — so a table name past the limit would be created under a
+ * name nobody asked for, and every later lookup by the full name would miss it.
+ * Such names are refused here, at compile, with the model named; index and
+ * primary-key names are derived, so the generator caps those instead
+ * (`schema-gen.ts` `capIdentifier`).
+ */
+export declare const PG_IDENTIFIER_MAX = 63;
+/** A declared field (a column): camelCase, a-z first, then ASCII letters and digits. */
+export declare const FIELD_NAME_RE: RegExp;
+export declare function identifierBytes(s: string): number;
+/** `ShipAddress` → `ship_address`; `Order` → `order`. */
+export declare function snakeCase(name: string): string;
+/**
+ * The table names an app's models become, checked: no two models of one app
+ * on the same table (`HTTPLog` and `HttpLog` are both `http_log`), an
+ * application type whose tables cannot be mistaken for another app's (no `__`
+ * inside it, no trailing `_` — `plugin_x__y__order` must be `plugin_x__y`'s,
+ * never `plugin_x`'s), and no table name past 63 bytes.
+ */
+export declare function checkTableNames(modelNames: string[], applicationType?: string): void;
 export declare function camelKey(model: string): string;
 /**
  * Compile a manifest's `db` block. Throws `RuleCompileError` with the key path

package/dist/db/compile-rules.js

@@ -47,6 +47,7 @@ const surfaceNamesOf = (x) => (Array.isArray(x) ? x.map(String) : x && typeof x
 export function rulesInputFromManifest(m, pluginId) {
     return {
         pluginId: pluginId ?? m.id ?? "app",
+        applicationType: m.applicationType,
         db: (m.db ?? {}),
         vocabulary: m.roles?.vocabulary,
         ownerRole: m.roles?.default?.owner,
@@ -68,6 +69,65 @@ export class RuleCompileError extends Error {
         this.name = "RuleCompileError";
     }
 }
+/* ───────────────────────────── identifiers ───────────────────────────── */
+/**
+ * An app's tables, columns and indexes are Postgres identifiers in ONE shared
+ * schema. Postgres silently TRUNCATES an identifier past 63 bytes
+ * (NAMEDATALEN − 1) — so a table name past the limit would be created under a
+ * name nobody asked for, and every later lookup by the full name would miss it.
+ * Such names are refused here, at compile, with the model named; index and
+ * primary-key names are derived, so the generator caps those instead
+ * (`schema-gen.ts` `capIdentifier`).
+ */
+export const PG_IDENTIFIER_MAX = 63;
+/** A declared field (a column): camelCase, a-z first, then ASCII letters and digits. */
+export const FIELD_NAME_RE = /^[a-z][A-Za-z0-9]*$/;
+export function identifierBytes(s) {
+    let n = 0;
+    for (const ch of s) {
+        const c = ch.codePointAt(0);
+        n += c < 0x80 ? 1 : c < 0x800 ? 2 : c < 0x10000 ? 3 : 4;
+    }
+    return n;
+}
+/** `ShipAddress` → `ship_address`; `Order` → `order`. */
+export function snakeCase(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
+        .toLowerCase();
+}
+/**
+ * The table names an app's models become, checked: no two models of one app
+ * on the same table (`HTTPLog` and `HttpLog` are both `http_log`), an
+ * application type whose tables cannot be mistaken for another app's (no `__`
+ * inside it, no trailing `_` — `plugin_x__y__order` must be `plugin_x__y`'s,
+ * never `plugin_x`'s), and no table name past 63 bytes.
+ */
+export function checkTableNames(modelNames, applicationType) {
+    const seen = new Map();
+    for (const m of modelNames) {
+        const snake = snakeCase(m);
+        const prev = seen.get(snake);
+        if (prev !== undefined) {
+            throw new RuleCompileError(`db.${m}`, `models "${prev}" and "${m}" would both be the table "…__${snake}" — rename one of them`);
+        }
+        seen.set(snake, m);
+    }
+    if (applicationType === undefined || !modelNames.length)
+        return;
+    if (applicationType.includes("__") || applicationType.endsWith("_")) {
+        throw new RuleCompileError("applicationType", `"${applicationType}" has "__" in it or ends with "_" — an app with tables names them "<applicationType>__<model>", and that name must not be readable as another app's table. Use single underscores (e.g. plugin_my_app).`);
+    }
+    for (const m of modelNames) {
+        const table = `${applicationType}__${snakeCase(m)}`;
+        const n = identifierBytes(table);
+        if (n > PG_IDENTIFIER_MAX) {
+            const room = PG_IDENTIFIER_MAX - identifierBytes(applicationType) - 2;
+            throw new RuleCompileError(`db.${m}`, `the table "${table}" is ${n} bytes; Postgres names are at most ${PG_IDENTIFIER_MAX} — shorten the model name so "${snakeCase(m)}" is at most ${Math.max(room, 0)} characters (or shorten the applicationType)`);
+        }
+    }
+}
 const FIELD_TYPES = ["string", "text", "int", "float", "boolean", "datetime", "json"];
 // Positional groups, not named ones: the repo-wide tsc targets below ES2018.
 // [1] base type, [2] "[]" for a list, [3] "?" for optional, [4] the default.
@@ -267,6 +327,12 @@ export function compileRules(input) {
             throw new RuleCompileError(`${at}.fields`, "a model declares at least one field");
         const fields = {};
         for (const f of fieldNames) {
+            if (!FIELD_NAME_RE.test(f)) {
+                throw new RuleCompileError(`${at}.fields.${f}`, "a field name is camelCase: a lowercase letter a-z first, then ASCII letters and digits");
+            }
+            if (identifierBytes(f) > PG_IDENTIFIER_MAX) {
+                throw new RuleCompileError(`${at}.fields.${f}`, `a field name is a column name, at most ${PG_IDENTIFIER_MAX} characters — this one is ${identifierBytes(f)}`);
+            }
             if (PLATFORM_COLUMNS.includes(f)) {
                 throw new RuleCompileError(`${at}.fields.${f}`, `"${f}" is a column the platform owns and stamps — it may not be declared. Platform columns: ${PLATFORM_COLUMNS.join(", ")}`);
             }
@@ -373,6 +439,7 @@ export function compileRules(input) {
             rules,
         };
     }
+    checkTableNames(modelNames, input.applicationType);
     const custom = compileEnvelope(input.custom, Object.fromEntries(Object.entries(models).map(([name, m]) => [name, { fields: Object.keys(m.fields), filterable: m.filterable }])), input.surfaces ?? [], attributes);
     return { version: 1, pluginId: input.pluginId, models, custom, attributes };
 }

package/dist/db/memory-client.d.ts

@@ -82,6 +82,8 @@ export interface PluginDbClient {
 export interface MemoryStore {
     rows: Record<string, Row[]>;
     seq: number;
+    /** Rows ever minted in this store — the ids' ordinal, shared by every client over it. */
+    minted?: number;
 }
 export declare function createStore(rules: CompiledRules): MemoryStore;
 export interface MemoryDbOptions {

package/dist/db/memory-client.js

@@ -1,5 +1,5 @@
 import { camelKey } from "./compile-rules.js";
-import { assertFilterShape, assertFilterable, assertIncludeDeleted, assertNoInjectedKeys, assertRefTargets, assertTransition, assertUnique, checkWritableData, hideFields, narrowMatches, withinScope, declaredValues, defaultRefuse, mayUnseal, orderTerms, ownerFilter, pageWindow, readPlan, scopeMatches, stampNewRow, writeGate, } from "./client-core.js";
+import { assertFilterShape, assertFilterable, assertIncludeDeleted, assertNoInjectedKeys, assertRefTargets, assertTransition, assertUnique, checkWritableData, hideFields, narrowMatches, withinScope, declaredValues, defaultRefuse, mayUnseal, orderTerms, totalOrder, ownerFilter, pageWindow, readPlan, scopeMatches, stampNewRow, writeGate, } from "./client-core.js";
 export function createStore(rules) {
     const rows = {};
     for (const name of Object.keys(rules.models))
@@ -11,8 +11,10 @@ export function createMemoryDb(options) {
     const { rules, viewer, scope, across, ownedWorkspaceIds = [], viaBinding = false, refuse = defaultRefuse, } = options;
     const store = options.store ?? createStore(rules);
     const now = options.now ?? (() => new Date());
-    let idSeq = 0;
-    const newId = options.newId ?? (() => `row_${++idSeq}_${Math.random().toString(36).slice(2, 8)}`);
+    // Zero-padded and counted on the STORE (every viewer's client shares it), so id order
+    // is insertion order: a page breaks ties by id (totalOrder).
+    const newId = options.newId ??
+        (() => `row_${String((store.minted = (store.minted ?? 0) + 1)).padStart(9, "0")}_${Math.random().toString(36).slice(2, 8)}`);
     const db = {};
     for (const model of Object.values(rules.models)) {
         db[model.key] = makeCollection(model);
@@ -126,8 +128,8 @@ export function createMemoryDb(options) {
             rows = rows.filter((r) => Object.entries(where).every(([k, v]) => matchOne(r[k], v)));
         return rows;
     }
-    function sortRows(c, rows, orderBy) {
-        const terms = orderTerms(c, orderBy);
+    function sortRows(c, rows, orderBy, cursor) {
+        const terms = totalOrder(orderTerms(c, orderBy), cursor);
         if (!terms.length)
             return rows;
         return [...rows].sort((a, b) => {
@@ -151,7 +153,7 @@ export function createMemoryDb(options) {
     }
     function page(c, rows, args) {
         const { take, skip } = pageWindow(c, args);
-        let out = sortRows(c, rows, args?.orderBy);
+        let out = sortRows(c, rows, args?.orderBy, args?.cursor);
         if (args?.cursor) {
             const at = out.findIndex((r) => r.id === args.cursor.id);
             out = at >= 0 ? out.slice(at + 1) : [];

package/dist/db/schema-gen.d.ts

@@ -35,8 +35,16 @@
  *   the platform actually runs.
  */
 import type { CompiledRules, IndexKind } from "./compile-rules.js";
-/** `ShipAddress` → `ship_address`; `Order` → `order`. */
-export declare function snakeCase(name: string): string;
+import { snakeCase } from "./compile-rules.js";
+export { snakeCase };
+/**
+ * A derived identifier (an index or a primary key) that fits Postgres's 63
+ * bytes. A name that already fits is returned UNCHANGED — every table, index
+ * and key already in production keeps its name. One that does not becomes
+ * `<first N chars>_<8-hex hash of the full name><suffix>`: deterministic, and
+ * two long names differing only past the cut still differ.
+ */
+export declare function capIdentifier(full: string, suffix: string): string;
 /** The Prisma model name: `plugin_shop_min__Order`. */
 export declare function prismaModelName(applicationType: string, model: string): string;
 /** The table it maps to: `plugin_shop_min__order`. */
@@ -96,8 +104,10 @@ export interface TableSpec {
     columns: TableColumn[];
     indexes: TableIndex[];
 }
-/** Prisma's index name: `<table>_<col>_<col>_idx`. */
+/** Prisma's index name, `<table>_<col>_<col>_idx` — capped (`capIdentifier`) only when it would pass 63 bytes. */
 export declare function indexName(table: string, columns: string[]): string;
+/** Prisma's primary-key name, `<table>_pkey` — capped only when it would pass 63 bytes. */
+export declare function pkeyName(table: string): string;
 /** Every table an app declares, as columns and indexes — the input to the planner and the emitter. */
 export declare function tableSpecs(rules: CompiledRules, opts: {
     applicationType: string;

package/dist/db/schema-gen.js

@@ -1,10 +1,37 @@
+import { checkTableNames, identifierBytes, PG_IDENTIFIER_MAX, snakeCase } from "./compile-rules.js";
 /* ───────────────────────────── naming ─────────────────────────────────── */
-/** `ShipAddress` → `ship_address`; `Order` → `order`. */
-export function snakeCase(name) {
-    return name
-        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
-        .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
-        .toLowerCase();
+// One implementation, in the compiler (which refuses colliding and over-long
+// table names at compile); re-exported so every caller of the generator keeps
+// its import.
+export { snakeCase };
+/** FNV-1a, 32 bits, as 8 hex digits — pure and stable, so a capped name is the same on every run. */
+function hash8(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h.toString(16).padStart(8, "0");
+}
+/**
+ * A derived identifier (an index or a primary key) that fits Postgres's 63
+ * bytes. A name that already fits is returned UNCHANGED — every table, index
+ * and key already in production keeps its name. One that does not becomes
+ * `<first N chars>_<8-hex hash of the full name><suffix>`: deterministic, and
+ * two long names differing only past the cut still differ.
+ */
+export function capIdentifier(full, suffix) {
+    if (identifierBytes(full) <= PG_IDENTIFIER_MAX)
+        return full;
+    const stem = full.endsWith(suffix) ? full.slice(0, full.length - suffix.length) : full;
+    const room = PG_IDENTIFIER_MAX - 1 - 8 - identifierBytes(suffix);
+    let cut = "";
+    for (const ch of stem) {
+        if (identifierBytes(cut + ch) > room)
+            break;
+        cut += ch;
+    }
+    return `${cut}_${hash8(full)}${suffix}`;
 }
 /** The Prisma model name: `plugin_shop_min__Order`. */
 export function prismaModelName(applicationType, model) {
@@ -116,8 +143,14 @@ function prismaIndexArgs(g) {
     return `[${g.fields.join(", ")}]`;
 }
 function renderModel(model, applicationType) {
+    const table = prismaTableName(applicationType, model.name);
+    const pkey = pkeyName(table);
+    // Prisma names a key `<table>_pkey` and an index `<table>_<cols>_idx`; only
+    // a name the cap CHANGED is spelled out with `map:`, so a fragment whose
+    // names fit is byte-for-byte what it always was.
+    const platform = platformColumns(model.scope).map((c) => c.name === "id" && pkey !== `${table}_pkey` ? { ...c, attrs: c.attrs.replace("@id", `@id(map: ${JSON.stringify(pkey)})`) } : c);
     const cols = [
-        ...platformColumns(model.scope),
+        ...platform,
         ...Object.keys(model.fields).map((name) => declaredColumn(name, model.fields[name], model.sealed.includes(name))),
     ];
     const nameW = Math.max(...cols.map((c) => c.name.length));
@@ -126,13 +159,17 @@ function renderModel(model, applicationType) {
         const head = `  ${c.name.padEnd(nameW)} ${c.type.padEnd(typeW)}`;
         return (c.attrs ? `${head} ${c.attrs}` : head).trimEnd();
     });
-    const idx = indexGroups(model).map((g) => `  @@index(${prismaIndexArgs(g)})`);
+    const idx = indexGroups(model).map((g) => {
+        const name = indexName(table, g.fields);
+        const map = name === `${table}_${g.fields.join("_")}_idx` ? "" : `, map: ${JSON.stringify(name)}`;
+        return `  @@index(${prismaIndexArgs(g)}${map})`;
+    });
     return [
         `model ${prismaModelName(applicationType, model.name)} {`,
         ...lines,
         "",
         ...idx,
-        `  @@map(${JSON.stringify(prismaTableName(applicationType, model.name))})`,
+        `  @@map(${JSON.stringify(table)})`,
         "}",
     ].join("\n");
 }
@@ -142,6 +179,7 @@ function renderModel(model, applicationType) {
  * generator: this is a FRAGMENT that joins the platform's schema folder.
  */
 export function prismaFragment(rules, opts) {
+    checkTableNames(Object.keys(rules.models), opts.applicationType);
     const models = Object.keys(rules.models).map((name) => rules.models[name]);
     const body = models.map((m) => renderModel(m, opts.applicationType)).join("\n\n");
     return [
@@ -314,12 +352,19 @@ function sqlColumn(c) {
     // or the planner would read a difference against the live table forever.
     return { name: c.name, type: list ? `${sql}[]` : sql, nullable: optional || list, default: def };
 }
-/** Prisma's index name: `<table>_<col>_<col>_idx`. */
+/** Prisma's index name, `<table>_<col>_<col>_idx` — capped (`capIdentifier`) only when it would pass 63 bytes. */
 export function indexName(table, columns) {
-    return `${table}_${columns.join("_")}_idx`;
+    return capIdentifier(`${table}_${columns.join("_")}_idx`, "_idx");
+}
+/** Prisma's primary-key name, `<table>_pkey` — capped only when it would pass 63 bytes. */
+export function pkeyName(table) {
+    return capIdentifier(`${table}_pkey`, "_pkey");
 }
 /** Every table an app declares, as columns and indexes — the input to the planner and the emitter. */
 export function tableSpecs(rules, opts) {
+    // A compiled artefact may come from a compile that did not know the type
+    // (an author's bare `db`): the generator always does, so it checks again.
+    checkTableNames(Object.keys(rules.models), opts.applicationType);
     return Object.keys(rules.models).map((name) => {
         const model = rules.models[name];
         const table = prismaTableName(opts.applicationType, model.name);
@@ -334,12 +379,13 @@ export function tableSpecs(rules, opts) {
         };
     });
 }
-const q = (ident) => `"${ident}"`;
+/** A quoted identifier; a `"` inside one is doubled, as SQL spells it. */
+const q = (ident) => `"${ident.replace(/"/g, '""')}"`;
 function columnDef(c) {
     return `${q(c.name)} ${c.type}${c.nullable ? "" : " NOT NULL"}${c.default !== null ? ` DEFAULT ${c.default}` : ""}`;
 }
 export function createTableSql(t) {
-    return [`CREATE TABLE ${q(t.name)} (`, ...t.columns.map((c) => `    ${columnDef(c)},`), "", `    CONSTRAINT ${q(`${t.name}_pkey`)} PRIMARY KEY ("id")`, ");"].join("\n");
+    return [`CREATE TABLE ${q(t.name)} (`, ...t.columns.map((c) => `    ${columnDef(c)},`), "", `    CONSTRAINT ${q(pkeyName(t.name))} PRIMARY KEY ("id")`, ");"].join("\n");
 }
 export function createIndexSql(table, idx) {
     if (idx.kind === "text")

package/dist/failed-requests.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The platform's list of requests that failed after the UI already showed their result
+ * (the optimistic-UI rule, app-style-guide.md "Interaction"): an app updates the screen at
+ * once, and when the request behind it fails the app puts the screen back and reports here —
+ * `<FailedRequestBanner/>` then names the request and offers Try again, in the same place and
+ * style as the "new version is available" pill. Pure and framework-free, so any app (built-in or
+ * Forge) and any test can use it. A Forge app imports it from `esoul-sdk/react`; the platform's
+ * `src/lib/failed-requests.ts` re-exports this very module, so both reach one list.
+ */
+export interface FailedRequest {
+    /** Stable per logical request: reporting the same key again replaces the entry, never stacks. */
+    key: string;
+    /** What the person did, in their words: "Accept the hint", "Grant more budget". */
+    what: string;
+    /** Why, when known and readable: "no connection", "the server refused: over the cap". */
+    why?: string;
+    /** Re-send the request. Resolve `true` when it landed; anything else keeps the entry. */
+    retry?: () => Promise<boolean> | boolean;
+    at: number;
+    /** Set while a retry is in flight. */
+    retrying?: boolean;
+}
+type Listener = () => void;
+/** Report a request that failed after the screen already showed it; the banner names it (and offers Try again when `retry` is given). The same `key` replaces, never stacks. */
+export declare function reportFailedRequest(r: Omit<FailedRequest, "at" | "retrying"> & {
+    at?: number;
+}): void;
+/** Take a request off the banner — it landed after all, or the person dismissed it. */
+export declare function dismissFailedRequest(key: string): void;
+/** Clear an entry because the same request later landed some other way (the person redid it). */
+export declare const resolveFailedRequest: typeof dismissFailedRequest;
+export declare function retryFailedRequest(key: string): Promise<boolean>;
+export declare function listFailedRequests(): FailedRequest[];
+export declare function subscribeFailedRequests(l: Listener): () => void;
+/** Test-only: start from nothing. */
+export declare function __resetFailedRequests(): void;
+/**
+ * Is this failure worth a Try again? A lost connection, a timeout, a server error or a
+ * rate limit — yes. A refusal (the server read the request and said no, with a reason) —
+ * retrying sends the same no; the app shows the reason instead.
+ */
+export declare function isRetryableFailure(r: {
+    reason?: string;
+    status?: number;
+}): boolean;
+/**
+ * The optimistic-UI rule in one call. `apply` puts the result on screen at once; `send` does the
+ * work; on success any earlier failure of the same `key` clears. On failure `revert` puts the
+ * screen back and the request is reported: a connection loss, timeout or server error gets
+ * Try again (which runs the whole thing again, apply included), a refusal shows its reason only —
+ * retrying would send the same no.
+ *
+ *   await runOptimistic({ key: `cheer:${id}`, what: "Cheer", apply: () => setCheered(true),
+ *     revert: () => setCheered(false), send: () => callPluginOp(PLUGIN_ID, "cheer", nodeId, { id }) });
+ *
+ * State that lives in the app's events needs none of this: `usePluginEventDispatch` already shows
+ * the event at once and delivers it durably. This is for work that needs the server (an op).
+ */
+export declare function runOptimistic<T>(r: {
+    key: string;
+    what: string;
+    apply?: () => void;
+    revert?: () => void;
+    send: () => Promise<T>;
+}): Promise<{
+    ok: true;
+    result: T;
+} | {
+    ok: false;
+    error: unknown;
+}>;
+/** Words and retryability for a thrown request: `PluginCallError` carries status + code; a fetch that never reached the server throws a TypeError. */
+export declare function describeFailure(error: unknown): {
+    why: string;
+    retryable: boolean;
+};
+export {};

package/dist/failed-requests.js

@@ -0,0 +1,127 @@
+/**
+ * The platform's list of requests that failed after the UI already showed their result
+ * (the optimistic-UI rule, app-style-guide.md "Interaction"): an app updates the screen at
+ * once, and when the request behind it fails the app puts the screen back and reports here —
+ * `<FailedRequestBanner/>` then names the request and offers Try again, in the same place and
+ * style as the "new version is available" pill. Pure and framework-free, so any app (built-in or
+ * Forge) and any test can use it. A Forge app imports it from `esoul-sdk/react`; the platform's
+ * `src/lib/failed-requests.ts` re-exports this very module, so both reach one list.
+ */
+const MAX = 5;
+let items = [];
+const listeners = new Set();
+function emit() {
+    for (const l of [...listeners]) {
+        try {
+            l();
+        }
+        catch {
+            /* a listener's throw must not stop the others */
+        }
+    }
+}
+/** Report a request that failed after the screen already showed it; the banner names it (and offers Try again when `retry` is given). The same `key` replaces, never stacks. */
+export function reportFailedRequest(r) {
+    const entry = { ...r, at: r.at ?? Date.now() };
+    items = [...items.filter((i) => i.key !== r.key), entry].slice(-MAX);
+    emit();
+}
+/** Take a request off the banner — it landed after all, or the person dismissed it. */
+export function dismissFailedRequest(key) {
+    const next = items.filter((i) => i.key !== key);
+    if (next.length === items.length)
+        return;
+    items = next;
+    emit();
+}
+/** Clear an entry because the same request later landed some other way (the person redid it). */
+export const resolveFailedRequest = dismissFailedRequest;
+export async function retryFailedRequest(key) {
+    const it = items.find((i) => i.key === key);
+    if (!it?.retry || it.retrying)
+        return false;
+    items = items.map((i) => (i.key === key ? { ...i, retrying: true } : i));
+    emit();
+    let ok = false;
+    try {
+        ok = (await it.retry()) === true;
+    }
+    catch {
+        ok = false;
+    }
+    items = ok ? items.filter((i) => i.key !== key) : items.map((i) => (i.key === key ? { ...i, retrying: false, at: Date.now() } : i));
+    emit();
+    return ok;
+}
+export function listFailedRequests() {
+    return items;
+}
+export function subscribeFailedRequests(l) {
+    listeners.add(l);
+    return () => {
+        listeners.delete(l);
+    };
+}
+/** Test-only: start from nothing. */
+export function __resetFailedRequests() {
+    items = [];
+    emit();
+}
+/**
+ * Is this failure worth a Try again? A lost connection, a timeout, a server error or a
+ * rate limit — yes. A refusal (the server read the request and said no, with a reason) —
+ * retrying sends the same no; the app shows the reason instead.
+ */
+export function isRetryableFailure(r) {
+    if (r.reason === "network" || r.reason === "timeout")
+        return true;
+    const s = r.status ?? 0;
+    return s === 0 || s === 408 || s === 429 || s >= 500;
+}
+/**
+ * The optimistic-UI rule in one call. `apply` puts the result on screen at once; `send` does the
+ * work; on success any earlier failure of the same `key` clears. On failure `revert` puts the
+ * screen back and the request is reported: a connection loss, timeout or server error gets
+ * Try again (which runs the whole thing again, apply included), a refusal shows its reason only —
+ * retrying would send the same no.
+ *
+ *   await runOptimistic({ key: `cheer:${id}`, what: "Cheer", apply: () => setCheered(true),
+ *     revert: () => setCheered(false), send: () => callPluginOp(PLUGIN_ID, "cheer", nodeId, { id }) });
+ *
+ * State that lives in the app's events needs none of this: `usePluginEventDispatch` already shows
+ * the event at once and delivers it durably. This is for work that needs the server (an op).
+ */
+export async function runOptimistic(r) {
+    r.apply?.();
+    try {
+        const result = await r.send();
+        dismissFailedRequest(r.key);
+        return { ok: true, result };
+    }
+    catch (error) {
+        try {
+            r.revert?.();
+        }
+        catch {
+            /* a revert that throws must not hide the failure */
+        }
+        const f = describeFailure(error);
+        reportFailedRequest({
+            key: r.key,
+            what: r.what,
+            why: f.why,
+            retry: f.retryable ? async () => (await runOptimistic(r)).ok : undefined,
+        });
+        return { ok: false, error };
+    }
+}
+/** Words and retryability for a thrown request: `PluginCallError` carries status + code; a fetch that never reached the server throws a TypeError. */
+export function describeFailure(error) {
+    const e = error;
+    if (!e || (e.name === "TypeError" && !e.status))
+        return { why: "no connection", retryable: true };
+    const status = typeof e.status === "number" ? e.status : 0;
+    if (isRetryableFailure({ status }))
+        return { why: status >= 500 ? "the server did not answer" : status === 429 ? "too many requests — wait a moment" : "no connection", retryable: true };
+    return { why: (e.message ?? "refused").slice(0, 160), retryable: false };
+}

package/dist/react.d.ts

@@ -388,3 +388,9 @@ export interface RemoteReconcile<T> {
  * docs/17-editing-and-merging.md.
  */
 export declare function useRemoteReconcile<T>(_opts: RemoteReconcileOptions<T>): RemoteReconcile<T>;
+/**
+ * The optimistic-UI rule (a click shows its result at once; a failed request puts the screen back
+ * and the platform's banner names it with Try again). Real code, not host-only: the list is pure,
+ * and in the host this module is the platform's own, so the banner shows what an app reports.
+ */
+export { runOptimistic, reportFailedRequest, dismissFailedRequest, isRetryableFailure, describeFailure, type FailedRequest, } from "./failed-requests.js";

package/dist/react.js

@@ -148,3 +148,9 @@ export function useSignInWall() {
 export function useRemoteReconcile(_opts) {
     return hostOnly("useRemoteReconcile");
 }
+/**
+ * The optimistic-UI rule (a click shows its result at once; a failed request puts the screen back
+ * and the platform's banner names it with Try again). Real code, not host-only: the list is pure,
+ * and in the host this module is the platform's own, so the banner shows what an app reports.
+ */
+export { runOptimistic, reportFailedRequest, dismissFailedRequest, isRetryableFailure, describeFailure, } from "./failed-requests.js";

package/docs/03-events-and-state.md

@@ -86,10 +86,15 @@ folded.
 Set it. It tells the platform your state IS the fold, which is what enables replay-on-load,
 snapshot baselines and the durability layers. Every shipped plugin and the scaffold set it.
 
-## Server-typed events
-
-`EventTypes.Server` marks events that only server code emits (a task, a webhook). The UI must
-not dispatch them, and the processor still obeys the three rules.
+## Events only the server emits
+
+There is no "server-only" event type: `EventTypes` has `Client` (what the UI and tools dispatch,
+and what a task's `dispatchEvent` or an op's `ctx.emit` writes through the same processors),
+`Workflow` and `Workspace` (the platform's own). An event that only a task or a webhook should
+produce is declared like any other; the guard is where its `dataCreator` is called — keep it out
+of the UI's reach and say so in a comment. (An earlier version of this page named
+`EventTypes.Server`, which does not exist: the Pantry's first type check in a box found it,
+2026-09-28.) The processor still obeys the three rules.
 
 ## Durability you get for free
 

package/docs/05-ui.md

@@ -20,6 +20,34 @@ export function StickyNotesUi({ state }: { state: StickyNotesData }) {
 - The schema module (`app.tsx`) is **never** `"use client"`; the UI module is. The schema imports
   the UI, not the other way around (it closes a module cycle).
 
+## A click shows its result at once
+
+The person never waits to see what they just did. Two cases, one rule:
+
+- **State in your events** — `dispatch(…)` IS the optimistic update: the fold shows it this frame
+  and the platform delivers the event durably (kept on the device, retried in order, never lost).
+  Prefer this for everything a person does to the app's own state.
+- **Work that needs the server** (an op: a table write, a check only the server can make) — wrap
+  it in `runOptimistic` from `esoul-sdk/react`:
+
+```tsx
+import { runOptimistic } from "esoul-sdk/react";
+
+await runOptimistic({
+  key: `cheer:${recordId}`,                 // one entry per logical request; a retry replaces it
+  what: "Cheer",                            // what the person did, in their words
+  apply: () => setCheered(true),            // the screen, now
+  revert: () => setCheered(false),          // the screen as it was, if it fails
+  send: () => callPluginOp(PLUGIN_ID, "cheer", nodeId, { recordId }),
+});
+```
+
+On failure the screen goes back and the platform's banner (bottom-centre, the same pill as "a new
+version is available") names it: *Cheer failed — no connection · Try again*. A lost connection, a
+timeout or a server error offers Try again, which runs the whole thing again, `apply` included; a
+refusal shows its reason and no retry, because retrying sends the same no. Do not draw your own
+failure banner — the one banner is where a person looks, in the box and installed alike.
+
 ## Editors: a local copy that someone else can change
 
 If your UI holds a local copy of what it edits (a draft, a canvas, a form) it MUST take remote changes

package/docs/14-database.md

@@ -105,7 +105,16 @@ Your generated type is the reference (open `.esoul/db.d.ts`), and this is all of
 | write | `create` · `createMany` · `update({ where: { id }, data })` · `updateMany` · `upsert` · `delete` · `deleteMany` |
 | together | `$transaction(fn)` |
 
-`findMany` takes `where`, `orderBy`, `take`, `skip`, `cursor: { id }`. Every `where` — including
+`findMany` takes `where`, `orderBy`, `take` (200 at most), `skip`, `cursor: { id }`.
+
+**Paging.** A page with `cursor` returns the rows AFTER that row — not Prisma's inclusive cursor,
+so never add `skip: 1` (the client refuses `skip` with `cursor` by name; it used to drop a row per
+page). Every ordered or cursored page ends in `id`, so rows that tie on your `orderBy` (a date, a
+status) come in one fixed order and a cursor names one place; without it Postgres returned tied
+rows twice or not at all. To read everything, loop `findMany({ …, take: 200, cursor })` until a
+page is shorter than 200 — or better, ask the database (`count`, `aggregate`, `groupBy`).
+
+Every `where` — including
 an `aggregate`'s — obeys the index wall above: a field you did not index is not a question, and
 asking it is refused as `invalid` rather than answered slowly. **Count and sum in the database**
 rather than paging rows to add them up in JavaScript; `groupBy` still returns only the rows this
@@ -223,5 +232,14 @@ await runOp(pluginServer, "raise-ticket", { viewer: ada, args: TICKET, db: db.as
 expect(await db.as(lin).ticket.count()).toBe(0);
 ```
 
-The in-memory client and the production one are proven equal by a differential test on every
-build, so a rule you prove here is a rule the database keeps.
+The in-memory client and Postgres share one rule compiler and one core, and a conformance suite
+runs against both — but the Postgres half needs a database (`DATABASE_URL_TEST`) and does not run
+in the box or on every build. So the box's tables are a faithful MODEL of production's, not the
+same thing. Where a model can hide a bug, test for it on purpose:
+
+- **Past one page.** Anything that reads a list: seed more than 200 rows and assert every row
+  comes back exactly once. A seed or import of "about a hundred" proves nothing about paging.
+- **Ties.** Order by a field many rows share and page through it.
+- **Twice, and half-way.** A long op (a seed, an import, a bulk issue) runs 10–30× slower installed
+  than in the box and can stop part-way. Run it twice in a test; make the second run finish or
+  refuse by name, never write duplicates.

package/llms-full.txt

@@ -875,10 +875,15 @@ folded.
 Set it. It tells the platform your state IS the fold, which is what enables replay-on-load,
 snapshot baselines and the durability layers. Every shipped plugin and the scaffold set it.
 
-## Server-typed events
+## Events only the server emits
 
-`EventTypes.Server` marks events that only server code emits (a task, a webhook). The UI must
-not dispatch them, and the processor still obeys the three rules.
+There is no "server-only" event type: `EventTypes` has `Client` (what the UI and tools dispatch,
+and what a task's `dispatchEvent` or an op's `ctx.emit` writes through the same processors),
+`Workflow` and `Workspace` (the platform's own). An event that only a task or a webhook should
+produce is declared like any other; the guard is where its `dataCreator` is called — keep it out
+of the UI's reach and say so in a comment. (An earlier version of this page named
+`EventTypes.Server`, which does not exist: the Pantry's first type check in a box found it,
+2026-09-28.) The processor still obeys the three rules.
 
 ## Durability you get for free
 
@@ -1037,6 +1042,34 @@ export function StickyNotesUi({ state }: { state: StickyNotesData }) {
 - The schema module (`app.tsx`) is **never** `"use client"`; the UI module is. The schema imports
   the UI, not the other way around (it closes a module cycle).
 
+## A click shows its result at once
+
+The person never waits to see what they just did. Two cases, one rule:
+
+- **State in your events** — `dispatch(…)` IS the optimistic update: the fold shows it this frame
+  and the platform delivers the event durably (kept on the device, retried in order, never lost).
+  Prefer this for everything a person does to the app's own state.
+- **Work that needs the server** (an op: a table write, a check only the server can make) — wrap
+  it in `runOptimistic` from `esoul-sdk/react`:
+
+```tsx
+import { runOptimistic } from "esoul-sdk/react";
+
+await runOptimistic({
+  key: `cheer:${recordId}`,                 // one entry per logical request; a retry replaces it
+  what: "Cheer",                            // what the person did, in their words
+  apply: () => setCheered(true),            // the screen, now
+  revert: () => setCheered(false),          // the screen as it was, if it fails
+  send: () => callPluginOp(PLUGIN_ID, "cheer", nodeId, { recordId }),
+});
+```
+
+On failure the screen goes back and the platform's banner (bottom-centre, the same pill as "a new
+version is available") names it: *Cheer failed — no connection · Try again*. A lost connection, a
+timeout or a server error offers Try again, which runs the whole thing again, `apply` included; a
+refusal shows its reason and no retry, because retrying sends the same no. Do not draw your own
+failure banner — the one banner is where a person looks, in the box and installed alike.
+
 ## Editors: a local copy that someone else can change
 
 If your UI holds a local copy of what it edits (a draft, a canvas, a form) it MUST take remote changes
@@ -2391,7 +2424,16 @@ Your generated type is the reference (open `.esoul/db.d.ts`), and this is all of
 | write | `create` · `createMany` · `update({ where: { id }, data })` · `updateMany` · `upsert` · `delete` · `deleteMany` |
 | together | `$transaction(fn)` |
 
-`findMany` takes `where`, `orderBy`, `take`, `skip`, `cursor: { id }`. Every `where` — including
+`findMany` takes `where`, `orderBy`, `take` (200 at most), `skip`, `cursor: { id }`.
+
+**Paging.** A page with `cursor` returns the rows AFTER that row — not Prisma's inclusive cursor,
+so never add `skip: 1` (the client refuses `skip` with `cursor` by name; it used to drop a row per
+page). Every ordered or cursored page ends in `id`, so rows that tie on your `orderBy` (a date, a
+status) come in one fixed order and a cursor names one place; without it Postgres returned tied
+rows twice or not at all. To read everything, loop `findMany({ …, take: 200, cursor })` until a
+page is shorter than 200 — or better, ask the database (`count`, `aggregate`, `groupBy`).
+
+Every `where` — including
 an `aggregate`'s — obeys the index wall above: a field you did not index is not a question, and
 asking it is refused as `invalid` rather than answered slowly. **Count and sum in the database**
 rather than paging rows to add them up in JavaScript; `groupBy` still returns only the rows this
@@ -2509,8 +2551,17 @@ await runOp(pluginServer, "raise-ticket", { viewer: ada, args: TICKET, db: db.as
 expect(await db.as(lin).ticket.count()).toBe(0);
 ```
 
-The in-memory client and the production one are proven equal by a differential test on every
-build, so a rule you prove here is a rule the database keeps.
+The in-memory client and Postgres share one rule compiler and one core, and a conformance suite
+runs against both — but the Postgres half needs a database (`DATABASE_URL_TEST`) and does not run
+in the box or on every build. So the box's tables are a faithful MODEL of production's, not the
+same thing. Where a model can hide a bug, test for it on purpose:
+
+- **Past one page.** Anything that reads a list: seed more than 200 rows and assert every row
+  comes back exactly once. A seed or import of "about a hundred" proves nothing about paging.
+- **Ties.** Order by a field many rows share and page through it.
+- **Twice, and half-way.** A long op (a seed, an import, a bulk issue) runs 10–30× slower installed
+  than in the box and can stop part-way. Run it twice in a test; make the second run finish or
+  refuse by name, never write duplicates.
 
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esoul-sdk",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Build a full product on ExternalSoul: your own tables with per-person rules, a viewer on every seam, app roles, access levels, realtime with audiences, durable tasks, and bindings to other apps.",
   "license": "UNLICENSED",
   "type": "module",