esoul-sdk 0.6.0 → 0.7.0

package/README.md

@@ -160,6 +160,17 @@ something: does the write survive?
 
 ## Versions
 
+- **0.7.0** — what a catalogue-sized app needs. **Index kinds**: a plain group is a btree,
+  `{ fields: ["tags"], kind: "contains" }` answers `{ tags: { has: … } }` on a list, and
+  `{ fields: ["title"], kind: "text" }` answers `{ title: { contains: … } }` — so a department
+  and a search term are questions for the database, with `cursor` paging. `contains` ignores
+  case in both clients (a search box that misses "earl grey" is broken quietly). Asking a list a
+  scalar's question (or the reverse) is refused with the right one named. **`ctx.emit`** — an op
+  records on its OWN timeline, so a fact reaches the fold whether a person or an agent caused it.
+  A list field defaults to `[]` (it used to refuse every create), a rule-less model defaults to
+  the role your manifest calls the owner, and `viewerProfile` is a real export rather than a
+  declaration. Documented the client surface that was already there: `aggregate`, `groupBy`,
+  `$transaction`, the `*Many` writes.
 - **0.6.0** — the full-stack release. Your own tables (`db`, `pluginDb`, rules, scopes, sealed
   fields, additive migrations applied on install). `viewer` on every seam, app `roles`, per-surface
   access levels with the sign-in wall. Realtime audiences: a topic says who hears it and the mint

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

@@ -48,7 +48,9 @@ export interface Core {
 }
 export declare const DEFAULT_TAKE = 50;
 export declare const MAX_TAKE = 200;
-export declare const FILTER_OPS: readonly ["in", "notIn", "not", "gt", "gte", "lt", "lte", "contains"];
+export declare const FILTER_OPS: readonly ["in", "notIn", "not", "gt", "gte", "lt", "lte", "contains", "has"];
+/** The only operator a LIST field takes, and the only one a scalar does not. */
+export declare const LIST_ONLY_OPS: readonly ["has"];
 export type FilterOp = (typeof FILTER_OPS)[number];
 export declare function bad(c: Core, detail: string): never;
 /**
@@ -66,6 +68,19 @@ export declare function assertNoInjectedKeys(c: Core, obj: Record<string, unknow
 export declare function assertFilterable(c: Core, keys: string[], where: string): void;
 /** The filter operators a `where` value may use — the same list both evaluators implement. */
 export declare function assertFilterShape(c: Core, where: Record<string, unknown> | undefined): void;
+/**
+ * A `contains` MATCHES REGARDLESS OF CASE, in both clients.
+ *
+ * A search box that answers nothing to "earl grey" and something to "Earl Grey"
+ * is broken, and it breaks quietly: the shopper reads an empty shelf. Postgres
+ * `LIKE` is case-sensitive and `String.includes` is too, so each client had to
+ * be told — the memory one lowercases both sides, and this turns the condition
+ * into the `mode: "insensitive"` Prisma needs (ILIKE, which a `gin_trgm_ops`
+ * index still serves, so the declaration keeps its meaning).
+ *
+ * One decision, two consumers, which is why it lives here beside `FILTER_OPS`.
+ */
+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">[];
 export declare function pageWindow(c: Core, args: {

package/dist/db/client-core.js

@@ -31,7 +31,9 @@ export const defaultRefuse = (code, message, detail) => {
 };
 export const DEFAULT_TAKE = 50;
 export const MAX_TAKE = 200;
-export const FILTER_OPS = ["in", "notIn", "not", "gt", "gte", "lt", "lte", "contains"];
+export const FILTER_OPS = ["in", "notIn", "not", "gt", "gte", "lt", "lte", "contains", "has"];
+/** The only operator a LIST field takes, and the only one a scalar does not. */
+export const LIST_ONLY_OPS = ["has"];
 /* ───────────────────────── argument validation ────────────────────────── */
 export function bad(c, detail) {
     return c.refuse("invalid", "invalid", detail);
@@ -74,14 +76,54 @@ export function assertFilterShape(c, where) {
     if (!where)
         return;
     for (const [key, cond] of Object.entries(where)) {
+        const list = !!c.model.fields[key]?.list;
         if (cond !== null && typeof cond === "object" && !(cond instanceof Date) && !Array.isArray(cond)) {
             for (const op of Object.keys(cond)) {
                 if (!FILTER_OPS.includes(op)) {
                     bad(c, `${c.model.name}.where.${key}: unknown filter "${op}" — allowed: ${FILTER_OPS.join(", ")}`);
                 }
+                // A list and a scalar take different questions, and asking the wrong
+                // one is an author's mistake worth naming rather than an empty result.
+                if (list && !LIST_ONLY_OPS.includes(op)) {
+                    bad(c, `${c.model.name}.where.${key}: "${key}" is a list — ask { has: … }, not { ${op}: … }`);
+                }
+                if (!list && LIST_ONLY_OPS.includes(op)) {
+                    bad(c, `${c.model.name}.where.${key}: "has" is for a list field; "${key}" is not one`);
+                }
             }
         }
+        else if (list) {
+            bad(c, `${c.model.name}.where.${key}: "${key}" is a list — ask { has: … } rather than a bare value`);
+        }
+    }
+}
+/**
+ * A `contains` MATCHES REGARDLESS OF CASE, in both clients.
+ *
+ * A search box that answers nothing to "earl grey" and something to "Earl Grey"
+ * is broken, and it breaks quietly: the shopper reads an empty shelf. Postgres
+ * `LIKE` is case-sensitive and `String.includes` is too, so each client had to
+ * be told — the memory one lowercases both sides, and this turns the condition
+ * into the `mode: "insensitive"` Prisma needs (ILIKE, which a `gin_trgm_ops`
+ * index still serves, so the declaration keeps its meaning).
+ *
+ * One decision, two consumers, which is why it lives here beside `FILTER_OPS`.
+ */
+export function insensitiveContains(where) {
+    if (!where)
+        return where;
+    let changed = false;
+    const out = {};
+    for (const [key, cond] of Object.entries(where)) {
+        if (cond !== null && typeof cond === "object" && !Array.isArray(cond) && !(cond instanceof Date) && "contains" in cond) {
+            out[key] = { ...cond, mode: "insensitive" };
+            changed = true;
+        }
+        else {
+            out[key] = cond;
+        }
     }
+    return changed ? out : where;
 }
 export function orderTerms(c, orderBy) {
     if (!orderBy)

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

@@ -94,6 +94,28 @@ export interface CompiledRule {
     /** When set, the only fields this rule permits writing at all. */
     fields: string[] | null;
 }
+/**
+ * HOW an index is built, named by what the author wants to DO with it rather
+ * than by the mechanism:
+ *
+ * - `btree` (a plain `["a","b"]` group) — equality, ranges, ordering. Led by
+ *   the scope column, because every query the platform issues narrows to an
+ *   instance first.
+ * - `contains` — a LIST field, so `where: { tags: { has: "gifts" } }` is an
+ *   index lookup instead of a scan. Becomes a GIN index.
+ * - `text` — a string or text field, so `where: { name: { contains: "grey" } }`
+ *   is an index lookup. Becomes a GIN trigram index, which is the only kind
+ *   that can serve a substring search; a btree cannot.
+ *
+ * The last two are single-column and NOT scope-led: without `btree_gin` a GIN
+ * index cannot lead with the scope column, so Postgres combines it with the
+ * scope index instead. That is the right plan and it is worth knowing.
+ */
+export type IndexKind = "btree" | "contains" | "text";
+export interface CompiledIndex {
+    fields: string[];
+    kind: IndexKind;
+}
 export interface CompiledModel {
     /** As declared: `Order`. */
     name: string;
@@ -105,7 +127,7 @@ export interface CompiledModel {
     fields: Record<string, CompiledField>;
     sealed: string[];
     unique: string[][];
-    indexes: string[][];
+    indexes: CompiledIndex[];
     /**
      * Every field a `where` or `orderBy` may name. An unindexed filter is a
      * table scan waiting to happen at a customer's scale, so it is refused with
@@ -133,7 +155,15 @@ export interface ManifestDbModel {
     fields: Record<string, string>;
     sealed?: string[];
     unique?: string[][];
-    indexes?: string[][];
+    /**
+     * A plain group (`["active","createdAt"]`) is a btree. An object names a
+     * kind: `{ fields: ["tags"], kind: "contains" }` for a list, or
+     * `{ fields: ["title"], kind: "text" }` for substring search.
+     */
+    indexes?: (string[] | {
+        fields: string[];
+        kind?: "btree" | "contains" | "text";
+    })[];
     rules?: Record<string, unknown>;
 }
 export interface CompileInput {

package/dist/db/compile-rules.js

@@ -205,7 +205,43 @@ export function compileRules(input) {
             return groups.map((g) => [...g]);
         };
         const unique = checkColumns(raw.unique, "unique");
-        const indexes = checkColumns(raw.indexes, "indexes");
+        /**
+         * `indexes` takes a plain group (`["active","createdAt"]`) or a kind
+         * (`{ "fields": ["tags"], "kind": "contains" }`). A kind is refused when
+         * the field cannot support it, by name — an author who indexed a list for
+         * text search would otherwise get a working build and a sequential scan
+         * at their customers' expense.
+         */
+        const indexes = (raw.indexes ?? []).map((entry, i) => {
+            const where = `${at}.indexes[${i}]`;
+            if (Array.isArray(entry))
+                return { fields: checkColumns([entry], "indexes")[0], kind: "btree" };
+            if (!entry || typeof entry !== "object") {
+                throw new RuleCompileError(where, 'an index is a list of columns (["a","b"]) or { "fields": [...], "kind": "contains" | "text" }');
+            }
+            const e = entry;
+            if (!Array.isArray(e.fields) || !e.fields.length)
+                throw new RuleCompileError(`${where}.fields`, "name at least one field");
+            const flds = checkColumns([e.fields.map(String)], "indexes")[0];
+            const kind = e.kind === undefined ? "btree" : String(e.kind);
+            if (kind !== "btree" && kind !== "contains" && kind !== "text") {
+                throw new RuleCompileError(`${where}.kind`, `unknown kind "${kind}" — allowed: btree, contains, text`);
+            }
+            if (kind !== "btree") {
+                if (flds.length !== 1)
+                    throw new RuleCompileError(`${where}.fields`, `a "${kind}" index covers exactly one field`);
+                const f = fields[flds[0]];
+                if (!f)
+                    throw new RuleCompileError(`${where}.fields`, `"${flds[0]}" is a platform column; a "${kind}" index covers one of your own fields`);
+                if (kind === "contains" && !f.list) {
+                    throw new RuleCompileError(`${where}`, `"${flds[0]}" is not a list — a "contains" index is for a list field (e.g. "tags": "string[]"). For substring search on text use "kind": "text".`);
+                }
+                if (kind === "text" && (f.list || (f.type !== "string" && f.type !== "text"))) {
+                    throw new RuleCompileError(`${where}`, `"${flds[0]}" is ${f.list ? "a list" : `a ${f.type}`} — a "text" index is for a single string or text field.`);
+                }
+            }
+            return { fields: flds, kind };
+        });
         const sealed = raw.sealed ?? [];
         for (const f of sealed) {
             if (!fieldNames.includes(f)) {
@@ -235,7 +271,7 @@ export function compileRules(input) {
             ...new Set([
                 ...PLATFORM_FILTERABLE,
                 ...unique.flat(),
-                ...indexes.flat(),
+                ...indexes.flatMap((i) => i.fields),
             ]),
         ].sort();
         models[name] = {

package/dist/db/memory-client.js

@@ -86,7 +86,16 @@ export function createMemoryDb(options) {
                             return false;
                         break;
                     case "contains":
-                        if (typeof value !== "string" || !value.includes(String(operand)))
+                        // Regardless of case, matching the Prisma arm's ILIKE — a search
+                        // box that answers "Earl Grey" and not "earl grey" is broken, and
+                        // it breaks by showing an empty shelf.
+                        if (typeof value !== "string" || !value.toLowerCase().includes(String(operand).toLowerCase()))
+                            return false;
+                        break;
+                    case "has":
+                        // A LIST field holds this value. The one question a list takes,
+                        // and the one a GIN index answers.
+                        if (!Array.isArray(value) || !value.some((x) => x === operand))
                             return false;
                         break;
                     default:

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

@@ -34,13 +34,17 @@
  *   start with the scope column is one the planner cannot use for the query
  *   the platform actually runs.
  */
-import type { CompiledRules } from "./compile-rules.js";
+import type { CompiledRules, IndexKind } from "./compile-rules.js";
 /** `ShipAddress` → `ship_address`; `Order` → `order`. */
 export declare function snakeCase(name: 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`. */
 export declare function prismaTableName(applicationType: string, model: string): string;
+export interface IndexSpec {
+    fields: string[];
+    kind: IndexKind;
+}
 /**
  * The Prisma schema fragment for one app — every model, platform columns
  * first, scope-led indexes, mapped to a prefixed table. No datasource and no
@@ -84,6 +88,8 @@ export interface TableColumn {
 export interface TableIndex {
     name: string;
     columns: string[];
+    /** Absent on an index read back from a live database (see `introspect`). */
+    kind?: IndexKind;
 }
 export interface TableSpec {
     name: string;

package/dist/db/schema-gen.js

@@ -71,12 +71,12 @@ function indexGroups(model) {
     const lead = scopeColumn(model.scope);
     const out = [];
     const seen = new Set();
-    const push = (cols) => {
-        const key = cols.join(",");
+    const push = (fields, kind = "btree") => {
+        const key = `${kind}:${fields.join(",")}`;
         if (seen.has(key))
             return;
         seen.add(key);
-        out.push(cols);
+        out.push({ fields, kind });
     };
     // The scope index every query starts from.
     push(model.scope === "instance" ? ["workspaceId", "nodeId"] : [lead]);
@@ -84,11 +84,37 @@ function indexGroups(model) {
         push(["ownerId"]);
     // Declared groups, `unique` first then `indexes`, each led by the scope
     // column. A group that already names the lead column is not doubled.
-    for (const group of [...model.unique, ...model.indexes]) {
+    for (const group of model.unique)
         push([lead, ...group.filter((c) => c !== lead)]);
+    for (const idx of model.indexes) {
+        // A GIN index (a list or a trigram search) is single-column and NOT
+        // scope-led: without `btree_gin` it cannot lead with the scope column, so
+        // Postgres bitmap-ANDs it with the scope index instead.
+        if (idx.kind === "btree")
+            push([lead, ...idx.fields.filter((c) => c !== lead)]);
+        else
+            push([...idx.fields], idx.kind);
     }
     return out;
 }
+/**
+ * One `@@index(...)` argument list. A trigram index needs the operator class
+ * spelled out (`gin_trgm_ops`) — that is what makes `contains` an index lookup
+ * rather than a scan — and Prisma emits both forms as the SQL we emit below,
+ * which is what keeps the fragment and the DDL in step.
+ */
+function prismaIndexArgs(g) {
+    // QUALIFIED. `pg_trgm` installs its operator class in `public`, and DDL that
+    // runs with a different search_path (the db-test harness makes a throwaway
+    // schema and does exactly that) cannot resolve a bare `gin_trgm_ops`:
+    // `operator class "gin_trgm_ops" does not exist for access method "gin"`.
+    // Measured 2026-09-12 against the real database.
+    if (g.kind === "text")
+        return `[${g.fields[0]}(ops: raw("public.gin_trgm_ops"))], type: Gin`;
+    if (g.kind === "contains")
+        return `[${g.fields.join(", ")}], type: Gin`;
+    return `[${g.fields.join(", ")}]`;
+}
 function renderModel(model, applicationType) {
     const cols = [
         ...platformColumns(model.scope),
@@ -100,7 +126,7 @@ 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([${g.join(", ")}])`);
+    const idx = indexGroups(model).map((g) => `  @@index(${prismaIndexArgs(g)})`);
     return [
         `model ${prismaModelName(applicationType, model.name)} {`,
         ...lines,
@@ -202,8 +228,12 @@ export function dbTypings(rules, opts) {
         "  | { lt: V }",
         "  | { lte: V }",
         "  | { contains: string };",
+        "/** A LIST field takes one question: does it hold this? (a `contains` index answers it) */",
+        "export type ListFilter<V> = { has: V };",
         "/** Only INDEXED fields may be filtered — the generator emits the union per model. */",
-        "export type Where<T, K extends keyof T> = { [P in K]?: T[P] extends Scalar ? Filter<T[P]> : never };",
+        "export type Where<T, K extends keyof T> = {",
+        "  [P in K]?: T[P] extends readonly (infer E)[] ? ListFilter<E> : T[P] extends Scalar ? Filter<T[P]> : never;",
+        "};",
         "export type OrderBy<K extends string> = { [P in K]?: \"asc\" | \"desc\" };",
         "",
         "export interface FindManyArgs<T, K extends keyof T & string> {",
@@ -306,7 +336,7 @@ export function tableSpecs(rules, opts) {
         return {
             name: table,
             columns: cols.map(sqlColumn),
-            indexes: indexGroups(model).map((g) => ({ name: indexName(table, g), columns: g })),
+            indexes: indexGroups(model).map((g) => ({ name: indexName(table, g.fields), columns: g.fields, kind: g.kind })),
         };
     });
 }
@@ -318,6 +348,10 @@ 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");
 }
 export function createIndexSql(table, idx) {
+    if (idx.kind === "text")
+        return `CREATE INDEX ${q(idx.name)} ON ${q(table)} USING GIN (${q(idx.columns[0])} public.gin_trgm_ops);`;
+    if (idx.kind === "contains")
+        return `CREATE INDEX ${q(idx.name)} ON ${q(table)} USING GIN (${idx.columns.map(q).join(", ")});`;
     return `CREATE INDEX ${q(idx.name)} ON ${q(table)}(${idx.columns.map(q).join(", ")});`;
 }
 export function addColumnSql(table, c) {

package/dist/helpers.d.ts

@@ -40,8 +40,13 @@ export declare function incompleteStateNotice(args: {
  * from the URL rather than plumbed through the app, because the URL is the one
  * thing that is true on every surface without the app having to care.
  *
- * (A share reached through a custom domain or `/u/<handle>` resolves its share
- * server-side and is not in the path; pass `shareId` yourself there.)
+ * A share reached through `/u/<handle>` or a custom domain resolves its share
+ * server-side and is NOT in the path. The platform tells the page which share
+ * it is standing on (`window.__esoulShareId`, written by the frame that
+ * renders the app), and that is read first. The day this was left to the app
+ * ("pass `shareId` yourself there") a shop published as a homepage answered
+ * `forbidden` to every visitor (2026-09-12): an app cannot know a thing only
+ * the platform resolved.
  */
 export declare function currentShareId(): string | null;
 /**

package/dist/helpers.js

@@ -66,12 +66,20 @@ export function incompleteStateNotice(args) {
  * from the URL rather than plumbed through the app, because the URL is the one
  * thing that is true on every surface without the app having to care.
  *
- * (A share reached through a custom domain or `/u/<handle>` resolves its share
- * server-side and is not in the path; pass `shareId` yourself there.)
+ * A share reached through `/u/<handle>` or a custom domain resolves its share
+ * server-side and is NOT in the path. The platform tells the page which share
+ * it is standing on (`window.__esoulShareId`, written by the frame that
+ * renders the app), and that is read first. The day this was left to the app
+ * ("pass `shareId` yourself there") a shop published as a homepage answered
+ * `forbidden` to every visitor (2026-09-12): an app cannot know a thing only
+ * the platform resolved.
  */
 export function currentShareId() {
     if (typeof window === "undefined")
         return null;
+    const told = window.__esoulShareId;
+    if (typeof told === "string" && told)
+        return told;
     const m = /^\/share\/([^/?#]+)/.exec(window.location.pathname);
     return m ? decodeURIComponent(m[1]) : null;
 }

package/dist/manifest.d.ts

@@ -565,7 +565,16 @@ export declare const PluginManifestSchema: z.ZodObject<{
         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.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, {
+            fields: string[];
+            kind?: "btree" | "contains" | "text" | undefined;
+        }, {
+            fields: string[];
+            kind?: "btree" | "contains" | "text" | undefined;
+        }>]>, "many">>;
         rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strict", z.ZodTypeAny, {
         fields: Record<string, string>;
@@ -573,7 +582,10 @@ export declare const PluginManifestSchema: z.ZodObject<{
         scope?: "workspace" | "instance" | "user" | undefined;
         sealed?: string[] | undefined;
         unique?: string[][] | undefined;
-        indexes?: string[][] | undefined;
+        indexes?: (string[] | {
+            fields: string[];
+            kind?: "btree" | "contains" | "text" | undefined;
+        })[] | undefined;
         rules?: Record<string, unknown> | undefined;
     }, {
         fields: Record<string, string>;
@@ -581,7 +593,10 @@ export declare const PluginManifestSchema: z.ZodObject<{
         scope?: "workspace" | "instance" | "user" | undefined;
         sealed?: string[] | undefined;
         unique?: string[][] | undefined;
-        indexes?: string[][] | undefined;
+        indexes?: (string[] | {
+            fields: string[];
+            kind?: "btree" | "contains" | "text" | undefined;
+        })[] | undefined;
         rules?: Record<string, unknown> | undefined;
     }>>>;
 }, "strict", z.ZodTypeAny, {
@@ -677,7 +692,10 @@ export declare const PluginManifestSchema: z.ZodObject<{
         scope?: "workspace" | "instance" | "user" | undefined;
         sealed?: string[] | undefined;
         unique?: string[][] | undefined;
-        indexes?: string[][] | undefined;
+        indexes?: (string[] | {
+            fields: string[];
+            kind?: "btree" | "contains" | "text" | undefined;
+        })[] | undefined;
         rules?: Record<string, unknown> | undefined;
     }> | undefined;
 }, {
@@ -773,7 +791,10 @@ export declare const PluginManifestSchema: z.ZodObject<{
         scope?: "workspace" | "instance" | "user" | undefined;
         sealed?: string[] | undefined;
         unique?: string[][] | undefined;
-        indexes?: string[][] | undefined;
+        indexes?: (string[] | {
+            fields: string[];
+            kind?: "btree" | "contains" | "text" | undefined;
+        })[] | undefined;
         rules?: Record<string, unknown> | undefined;
     }> | undefined;
 }>;

package/dist/manifest.js

@@ -331,7 +331,14 @@ export const PluginManifestSchema = z.object({
         fields: z.record(z.string().regex(/^[a-z][A-Za-z0-9]*$/), z.string()),
         sealed: z.array(z.string()).optional(),
         unique: z.array(z.array(z.string())).optional(),
-        indexes: z.array(z.array(z.string())).optional(),
+        // A plain group is a btree; an object names a kind — `contains` for
+        // a list field, `text` for substring search (docs/14).
+        indexes: z
+            .array(z.union([
+            z.array(z.string()),
+            z.object({ fields: z.array(z.string()).min(1), kind: z.enum(["btree", "contains", "text"]).optional() }).strict(),
+        ]))
+            .optional(),
         rules: z.record(z.string(), z.unknown()).optional(),
     })
         .strict())

package/dist/server.d.ts

@@ -98,6 +98,23 @@ export interface PluginOpContext {
             role: string;
         };
     }): Promise<void>;
+    /**
+     * RECORD SOMETHING ON YOUR OWN TIMELINE, from the server half.
+     *
+     * The fold is for what is shared, small and worth scrubbing. Until this
+     * existed, only the UI could put anything there — so a shop whose products
+     * were added by its AGENT had a catalogue and no departments, because the
+     * departments were only recorded by the owner's form (2026-09-12). Anything
+     * a person can cause through your UI, an agent can cause through a tool, and
+     * the server is the only place that sees both.
+     *
+     * The event is your own (`eventName` from your schema), it goes through the
+     * platform's spine — your `dataCreator` mints, your reducer folds, triggers
+     * fire — and it is recorded against THIS instance. Give it a change id you
+     * can derive again (`product:<id>`, never a random one) so a retry, or the
+     * UI's own optimistic dispatch of the same fact, is a no-op.
+     */
+    emit(eventName: string, eventData: Record<string, unknown>): Promise<void>;
     /**
      * The apps standing in this app's SLOTS (manifest `uses`), by slot name
      * (S9). A slot the owner has not filled is ABSENT — `ctx.apps.stock?.call(…)`

package/dist/testing/db.d.ts

@@ -33,6 +33,8 @@ export declare function fakeViewer(kind: ViewerKind, opts?: {
     userId?: string | null;
     viewerIds?: string[];
     role?: string;
+    name?: string | null;
+    email?: string | null;
 }): RuleViewer;
 /**
  * The app's own word for a kind of caller, read from the manifest's `roles`.

package/dist/testing/db.js

@@ -39,6 +39,15 @@ const DEFAULT_IDS = {
 export function fakeViewer(kind, opts = {}) {
     const userId = opts.userId !== undefined ? opts.userId : DEFAULT_IDS[kind];
     const viewerIds = opts.viewerIds ?? (userId ? [userId] : []);
+    // THE ACCOUNT BEHIND THE VIEWER, for `viewerProfile`. A test that names one
+    // gets it back from the op under test; a test that names none gets null —
+    // and never a database. Registered on globalThis because the host's
+    // `viewerProfile` is the one that answers, and this is how it learns that a
+    // test is asking (the same seam `runAsViewer` uses).
+    if (userId && (opts.name !== undefined || opts.email !== undefined)) {
+        const g = globalThis;
+        (g.__esoulFakeProfiles ??= {})[userId] = { userId, name: opts.name ?? null, email: opts.email ?? null, picture: null };
+    }
     return { kind, userId, viewerIds, role: opts.role ?? PLATFORM_DEFAULT_ROLE[kind] };
 }
 /**

package/docs/06-server.md

@@ -60,6 +60,35 @@ Gated exactly like the UI: the manifest must declare `"my_computer:claude_task"`
 instance with `targetNodeId` instead of `appType`. This is how an app runs a `my_computer`
 (commands, Claude Code sessions, results), fills a spreadsheet from a job, or books a calendar.
 
+## `ctx.emit` — record on your OWN timeline
+
+Anything a person can cause through your UI, an agent can cause through a tool,
+and the server is the only place that sees both. So when a change belongs on the
+fold, the OP records it, not the screen:
+
+```ts
+async function addProduct(ctx: PluginOpContext) {
+  const p = await (await pluginDb<ShopDb>(ctx)).product.create({ data: … });
+  // Derive the change id. A retry — and the UI's own optimistic dispatch of the
+  // same fact — is then a no-op rather than a second bump.
+  await ctx.emit("plugin_shop_catalogue_changed", { changeId: `product:${p.id}`, tags: p.tags });
+  return { id: p.id };
+}
+```
+
+It is your own event (`eventName` from your schema), it goes through the
+platform's spine — your `dataCreator` mints, your reducer folds, triggers fire —
+and it lands on THIS instance.
+
+**The failure this exists to prevent.** An app offered its departments from the
+fold and recorded them only in the owner's add-product FORM. Stocked by its
+agent instead, it therefore had a full catalogue and no departments at all,
+live on a customer's site. If a fact belongs on the timeline, the op is where
+it is written — a screen is one of its callers, never the only one.
+
+Treat it as a courtesy around a completed write, like `notify`: catch a failure
+and report it, rather than letting it undo a product that exists.
+
 ## `emitPluginAppEvent`
 
 Emit ANOTHER app's own events (its `dataCreator` shape) into the same workspace, actor-stamped as

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

@@ -46,6 +46,10 @@ profile to read, so an app cannot look somebody up. It is null for anyone withou
 which is the same thing `requires: "account"` is about. Use it to pre-fill a form rather than
 asking a signed-in person to type what the platform already knows.
 
+In a test, `fakeViewer("visitor", { userId: "u_ada", role: "requester", name: "Ada", email: "ada@x.test" })`
+is what `viewerProfile` answers for that viewer; a fake viewer with no name or email answers null.
+No test ever reaches a database for it.
+
 ## Roles — your app's own vocabulary
 
 The platform's words are about a workspace. Your app's words are about your app. A help desk has

package/docs/14-database.md

@@ -88,6 +88,112 @@ query is refused as `invalid` rather than quietly overridden.
 Ordering and filtering are limited to the fields you indexed — an unindexed `orderBy` is a compile
 error in your editor, not a slow query in production.
 
+### The whole surface
+
+Your generated type is the reference (open `.esoul/db.d.ts`), and this is all of it:
+
+| | |
+|---|---|
+| read | `findMany` · `findFirst` · `findUnique({ where: { id } })` · `count` |
+| summarise | `aggregate({ where?, _count, _sum, _avg, _min, _max })` · `groupBy({ by, … })` |
+| 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
+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
+viewer may read, so a customer's own total is their own and an aggregate is never a way around a
+rule.
+
+### Transactions
+
+`$transaction` gives you the one guarantee a pair of writes cannot give itself: either both
+happened, or neither did.
+
+```ts
+const order = await db.$transaction(async (tx) => {
+  const written = await tx.order.create({ data: { totalCents, shipTo } });
+  for (const l of lines) await tx.orderLine.create({ data: { order: written.id, ...l } });
+  await tx.cartLine.deleteMany();   // the basket that made it
+  return written;
+});
+```
+
+Every gap between two writes is a real state somebody's session can end in. An order committed
+and a basket emptied a moment later is not a detail: the moment in between is "paid for, still in
+the basket", which is how a person buys the same thing twice. Put the writes that must be true
+together in one call, and let a throw undo all of them.
+
+Rules still apply inside, per statement, for the same viewer — a transaction is atomicity, never
+elevation.
+
+**What a transaction cannot hold.** A call into ANOTHER app (`ctx.apps.<slot>.call(…)`, an email,
+a payment) is outside it by construction: the other app's writes are its own. For those, hold →
+write → and **release on failure**, yourself:
+
+```ts
+const held = [];
+try {
+  for (const l of lines) { await stock.call("reserve_stock", l); held.push(l); }
+  return await db.$transaction(…);
+} catch (err) {
+  for (const h of held) await stock.call("release_stock", h);   // never throws out of here
+  throw err;
+}
+```
+
+A reservation no order ever used is worse than a refusal: nothing marks it stale, so the shelf
+reads empty while the goods sit there.
+
+## Indexes for a catalogue
+
+A plain group is a btree: equality, ranges, ordering. Two other kinds exist because a real
+catalogue asks two questions a btree cannot answer.
+
+```json
+"indexes": [
+  ["active", "createdAt"],
+  { "fields": ["tags"], "kind": "contains" },
+  { "fields": ["title"], "kind": "text" }
+]
+```
+
+| kind | the field | what it lets you ask |
+|---|---|---|
+| `btree` (a plain group) | any | `where: { active: true }`, `orderBy: { createdAt: "desc" }` |
+| `contains` | a LIST | `where: { tags: { has: "gifts" } }` |
+| `text` | a string or text | `where: { title: { contains: "grey" } }` — **regardless of case** |
+
+```ts
+// A department and a search term, both as a WHERE — with a cursor, so the
+// hundredth page costs what the first one did.
+db.product.findMany({
+  where: { active: true, tags: { has: dept }, title: { contains: term } },
+  orderBy: { createdAt: "asc" },
+  take: 24,
+  cursor: after ? { id: after } : undefined,
+});
+```
+
+`contains` ignores case in both clients (`ILIKE`, which a trigram index still serves), because a
+search box that finds "Earl Grey" and not "earl grey" is broken in the quietest possible way — the
+shopper just reads an empty shelf.
+
+**A list takes one question and a scalar takes the others.** `{ tags: { has: … } }` on a list,
+never a bare value and never `contains`; `{ title: { contains: … } }` on text, never `has`. Asking
+the wrong one is refused as `invalid` with the right one named, because an empty result would look
+like an empty shelf. (A refusal's `message` is the code; the sentence written for you is on
+`err.detail`.)
+
+Both of the new kinds become GIN indexes, and neither is led by the scope column — a GIN index
+cannot be, so the database combines it with the scope index instead. That is the right plan, and
+it is why `contains` and `text` cover exactly one field each.
+
+**Why this matters more than it looks.** Without them, a shop with 100 000 products can only
+return a page and filter it in the browser, so a department with nothing on the first page looks
+empty. The declaration is the whole difference between a catalogue and a list.
+
 ## Migrations
 
 On install the platform computes what your declaration means for the live database and applies it

package/llms-full.txt

@@ -164,6 +164,17 @@ something: does the write survive?
 
 ## Versions
 
+- **0.7.0** — what a catalogue-sized app needs. **Index kinds**: a plain group is a btree,
+  `{ fields: ["tags"], kind: "contains" }` answers `{ tags: { has: … } }` on a list, and
+  `{ fields: ["title"], kind: "text" }` answers `{ title: { contains: … } }` — so a department
+  and a search term are questions for the database, with `cursor` paging. `contains` ignores
+  case in both clients (a search box that misses "earl grey" is broken quietly). Asking a list a
+  scalar's question (or the reverse) is refused with the right one named. **`ctx.emit`** — an op
+  records on its OWN timeline, so a fact reaches the fold whether a person or an agent caused it.
+  A list field defaults to `[]` (it used to refuse every create), a rule-less model defaults to
+  the role your manifest calls the owner, and `viewerProfile` is a real export rather than a
+  declaration. Documented the client surface that was already there: `aggregate`, `groupBy`,
+  `$transaction`, the `*Many` writes.
 - **0.6.0** — the full-stack release. Your own tables (`db`, `pluginDb`, rules, scopes, sealed
   fields, additive migrations applied on install). `viewer` on every seam, app `roles`, per-surface
   access levels with the sign-in wall. Realtime audiences: a topic says who hears it and the mint
@@ -722,6 +733,35 @@ Gated exactly like the UI: the manifest must declare `"my_computer:claude_task"`
 instance with `targetNodeId` instead of `appType`. This is how an app runs a `my_computer`
 (commands, Claude Code sessions, results), fills a spreadsheet from a job, or books a calendar.
 
+## `ctx.emit` — record on your OWN timeline
+
+Anything a person can cause through your UI, an agent can cause through a tool,
+and the server is the only place that sees both. So when a change belongs on the
+fold, the OP records it, not the screen:
+
+```ts
+async function addProduct(ctx: PluginOpContext) {
+  const p = await (await pluginDb<ShopDb>(ctx)).product.create({ data: … });
+  // Derive the change id. A retry — and the UI's own optimistic dispatch of the
+  // same fact — is then a no-op rather than a second bump.
+  await ctx.emit("plugin_shop_catalogue_changed", { changeId: `product:${p.id}`, tags: p.tags });
+  return { id: p.id };
+}
+```
+
+It is your own event (`eventName` from your schema), it goes through the
+platform's spine — your `dataCreator` mints, your reducer folds, triggers fire —
+and it lands on THIS instance.
+
+**The failure this exists to prevent.** An app offered its departments from the
+fold and recorded them only in the owner's add-product FORM. Stocked by its
+agent instead, it therefore had a full catalogue and no departments at all,
+live on a customer's site. If a fact belongs on the timeline, the op is where
+it is written — a screen is one of its callers, never the only one.
+
+Treat it as a courtesy around a completed write, like `notify`: catch a failure
+and report it, rather than letting it undo a product that exists.
+
 ## `emitPluginAppEvent`
 
 Emit ANOTHER app's own events (its `dataCreator` shape) into the same workspace, actor-stamped as
@@ -1222,6 +1262,10 @@ profile to read, so an app cannot look somebody up. It is null for anyone withou
 which is the same thing `requires: "account"` is about. Use it to pre-fill a form rather than
 asking a signed-in person to type what the platform already knows.
 
+In a test, `fakeViewer("visitor", { userId: "u_ada", role: "requester", name: "Ada", email: "ada@x.test" })`
+is what `viewerProfile` answers for that viewer; a fake viewer with no name or email answers null.
+No test ever reaches a database for it.
+
 ## Roles — your app's own vocabulary
 
 The platform's words are about a workspace. Your app's words are about your app. A help desk has
@@ -1416,6 +1460,112 @@ query is refused as `invalid` rather than quietly overridden.
 Ordering and filtering are limited to the fields you indexed — an unindexed `orderBy` is a compile
 error in your editor, not a slow query in production.
 
+### The whole surface
+
+Your generated type is the reference (open `.esoul/db.d.ts`), and this is all of it:
+
+| | |
+|---|---|
+| read | `findMany` · `findFirst` · `findUnique({ where: { id } })` · `count` |
+| summarise | `aggregate({ where?, _count, _sum, _avg, _min, _max })` · `groupBy({ by, … })` |
+| 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
+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
+viewer may read, so a customer's own total is their own and an aggregate is never a way around a
+rule.
+
+### Transactions
+
+`$transaction` gives you the one guarantee a pair of writes cannot give itself: either both
+happened, or neither did.
+
+```ts
+const order = await db.$transaction(async (tx) => {
+  const written = await tx.order.create({ data: { totalCents, shipTo } });
+  for (const l of lines) await tx.orderLine.create({ data: { order: written.id, ...l } });
+  await tx.cartLine.deleteMany();   // the basket that made it
+  return written;
+});
+```
+
+Every gap between two writes is a real state somebody's session can end in. An order committed
+and a basket emptied a moment later is not a detail: the moment in between is "paid for, still in
+the basket", which is how a person buys the same thing twice. Put the writes that must be true
+together in one call, and let a throw undo all of them.
+
+Rules still apply inside, per statement, for the same viewer — a transaction is atomicity, never
+elevation.
+
+**What a transaction cannot hold.** A call into ANOTHER app (`ctx.apps.<slot>.call(…)`, an email,
+a payment) is outside it by construction: the other app's writes are its own. For those, hold →
+write → and **release on failure**, yourself:
+
+```ts
+const held = [];
+try {
+  for (const l of lines) { await stock.call("reserve_stock", l); held.push(l); }
+  return await db.$transaction(…);
+} catch (err) {
+  for (const h of held) await stock.call("release_stock", h);   // never throws out of here
+  throw err;
+}
+```
+
+A reservation no order ever used is worse than a refusal: nothing marks it stale, so the shelf
+reads empty while the goods sit there.
+
+## Indexes for a catalogue
+
+A plain group is a btree: equality, ranges, ordering. Two other kinds exist because a real
+catalogue asks two questions a btree cannot answer.
+
+```json
+"indexes": [
+  ["active", "createdAt"],
+  { "fields": ["tags"], "kind": "contains" },
+  { "fields": ["title"], "kind": "text" }
+]
+```
+
+| kind | the field | what it lets you ask |
+|---|---|---|
+| `btree` (a plain group) | any | `where: { active: true }`, `orderBy: { createdAt: "desc" }` |
+| `contains` | a LIST | `where: { tags: { has: "gifts" } }` |
+| `text` | a string or text | `where: { title: { contains: "grey" } }` — **regardless of case** |
+
+```ts
+// A department and a search term, both as a WHERE — with a cursor, so the
+// hundredth page costs what the first one did.
+db.product.findMany({
+  where: { active: true, tags: { has: dept }, title: { contains: term } },
+  orderBy: { createdAt: "asc" },
+  take: 24,
+  cursor: after ? { id: after } : undefined,
+});
+```
+
+`contains` ignores case in both clients (`ILIKE`, which a trigram index still serves), because a
+search box that finds "Earl Grey" and not "earl grey" is broken in the quietest possible way — the
+shopper just reads an empty shelf.
+
+**A list takes one question and a scalar takes the others.** `{ tags: { has: … } }` on a list,
+never a bare value and never `contains`; `{ title: { contains: … } }` on text, never `has`. Asking
+the wrong one is refused as `invalid` with the right one named, because an empty result would look
+like an empty shelf. (A refusal's `message` is the code; the sentence written for you is on
+`err.detail`.)
+
+Both of the new kinds become GIN indexes, and neither is led by the scope column — a GIN index
+cannot be, so the database combines it with the scope index instead. That is the right plan, and
+it is why `contains` and `text` cover exactly one field each.
+
+**Why this matters more than it looks.** Without them, a shop with 100 000 products can only
+return a page and filter it in the browser, so a department with nothing on the first page looks
+empty. The declaration is the whole difference between a catalogue and a list.
+
 ## Migrations
 
 On install the platform computes what your declaration means for the live database and applies it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esoul-sdk",
-  "version": "0.6.0",
+  "version": "0.7.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",

package/schemas/plugin.schema.json

@@ -540,10 +540,38 @@
               "indexes": {
                 "type": "array",
                 "items": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
+                  "anyOf": [
+                    {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "fields": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          },
+                          "minItems": 1
+                        },
+                        "kind": {
+                          "type": "string",
+                          "enum": [
+                            "btree",
+                            "contains",
+                            "text"
+                          ]
+                        }
+                      },
+                      "required": [
+                        "fields"
+                      ],
+                      "additionalProperties": false
+                    }
+                  ]
                 }
               },
               "rules": {