esoul-sdk 0.16.0 → 0.18.0

package/bin/esoul-device-exec.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// The process that OWNS one run. The runtime starts it detached, so it — and
+// the command under it — outlive a runtime restart or upgrade; the runtime
+// reattaches by reading the files it leaves in the run directory.
+//
+//   meta.json  (in)   { argv, cwd, env, timeoutSeconds }
+//   out.log    (out)  stdout and stderr, interleaved, appended as they come
+//   pid.json   (out)  { wrapperPid, childPid, startedAt, bootId }
+//   exit.json  (out)  { exitCode, signal, reason, startedAt, endedAt }
+//   cancel     (in)   present = stop: SIGTERM the command's group, SIGKILL after 10 s
+//
+// Plain JavaScript with no imports beyond node: — it must run from any copy
+// of the package, including the one the service runs, with nothing built.
+import { spawn } from "node:child_process";
+import { existsSync, openSync, readFileSync, writeFileSync, renameSync, watch } from "node:fs";
+import { join } from "node:path";
+
+const dir = process.argv[2];
+if (!dir) {
+  console.error("usage: esoul-device-exec <run-dir>");
+  process.exit(2);
+}
+const meta = JSON.parse(readFileSync(join(dir, "meta.json"), "utf8"));
+const write = (name, value) => {
+  const p = join(dir, name);
+  writeFileSync(`${p}.tmp`, JSON.stringify(value));
+  renameSync(`${p}.tmp`, p);
+};
+const bootId = () => {
+  try {
+    return readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+  } catch {
+    return null;
+  }
+};
+
+const out = openSync(join(dir, "out.log"), "a");
+const startedAt = Date.now();
+let child;
+try {
+  child = spawn(meta.argv[0], meta.argv.slice(1), {
+    cwd: meta.cwd || undefined,
+    env: meta.env,
+    stdio: ["ignore", out, out],
+    detached: true, // its own process group, so a stop reaches grandchildren too
+  });
+} catch (e) {
+  write("exit.json", { exitCode: null, signal: null, reason: `could not start: ${e.message}`, startedAt, endedAt: Date.now() });
+  process.exit(0);
+}
+
+let reason = null;
+let finished = false;
+child.on("error", (e) => {
+  if (finished) return;
+  finished = true;
+  write("exit.json", { exitCode: null, signal: null, reason: e.code === "ENOENT" ? `program not found: ${meta.argv[0]}` : `could not start: ${e.message}`, startedAt, endedAt: Date.now() });
+  process.exit(0);
+});
+child.on("spawn", () => write("pid.json", { wrapperPid: process.pid, childPid: child.pid, startedAt, bootId: bootId() }));
+
+const stop = (why) => {
+  if (reason || finished) return;
+  reason = why;
+  try {
+    process.kill(-child.pid, "SIGTERM");
+  } catch {}
+  setTimeout(() => {
+    try {
+      process.kill(-child.pid, "SIGKILL");
+    } catch {}
+  }, 10_000).unref();
+};
+
+if (meta.timeoutSeconds > 0) setTimeout(() => stop(`timed out after ${meta.timeoutSeconds} s`), meta.timeoutSeconds * 1000).unref();
+const cancelFile = join(dir, "cancel");
+// The cancel file's text is the reason ("cancelled", or "cancelled: <why>").
+const checkCancel = () => {
+  if (!existsSync(cancelFile)) return;
+  let why = "cancelled";
+  try {
+    why = readFileSync(cancelFile, "utf8").trim() || why;
+  } catch {}
+  stop(why);
+};
+checkCancel();
+try {
+  watch(dir, () => checkCancel()).unref();
+} catch {}
+const poll = setInterval(checkCancel, 1000);
+poll.unref();
+for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) process.on(sig, () => stop(`runtime sent ${sig}`));
+
+child.on("exit", (code, signal) => {
+  if (finished) return;
+  finished = true;
+  write("exit.json", { exitCode: code, signal, reason, startedAt, endedAt: Date.now() });
+  process.exit(0);
+});

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/device.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Types for `devices(ctx)` — parts of an app that run on the person's own
+ * computer (plugin-device-arm.md §10–§11). The functions live in server.ts
+ * (host-only); the hooks and <ConnectComputer/> in react.ts.
+ *
+ * The flow an app is built around:
+ *   1. its config page renders <ConnectComputer workspaceId nodeId /> — one
+ *      command to paste, a code to check, an Approve button;
+ *   2. its server code runs a DECLARED command (plugin.json `device.commands`):
+ *        const d = devices(ctx);
+ *        const { commandId } = await d.run("train", { epochs: 3 });
+ *   3. its UI shows the run live with useDeviceRun({ workspaceId, nodeId, commandId }).
+ */
+export type DeviceRunStatus = "queued" | "claimed" | "running" | "done" | "expired" | "cancelled" | "lost";
+/** What an app's agents may reach on a computer through the shared command line. */
+export type WorkspaceGrant = {
+    scope: "folder";
+    root: string;
+} | {
+    scope: "computer";
+};
+/**
+ * One line of the shared command line, answered (esoul-sdk/machine shell.ts):
+ * `text` is what a terminal would print (what an agent reads), `data` the same
+ * answer structured, `opId` the journal entry to `undo`.
+ */
+export interface ShellResult {
+    ok: boolean;
+    text: string;
+    data?: unknown;
+    exitCode?: number | null;
+    error?: string;
+    opId?: string;
+    cwd: string;
+}
+/** One computer connected to this app instance. */
+export interface DeviceSummary {
+    linkId: string;
+    status: "active" | "suspended";
+    reason: string | null;
+    /** The declared commands this computer will run (the ones the owner approved). */
+    commands: string[];
+    /** Commands an app update added or changed since approval; they wait for the owner. */
+    pendingApproval: {
+        added: string[];
+        changed: string[];
+    };
+    machine: {
+        machineId: string;
+        hostname: string;
+        os: string;
+        arch: string | null;
+        runtimeVersion: string | null;
+        lastSeenAt: number | null;
+        online: boolean;
+    } | null;
+    /** What this app's agents may reach on that computer (null = declared commands only). */
+    workspace?: WorkspaceGrant | null;
+}
+export interface DeviceRunStarted {
+    commandId: string;
+    status: DeviceRunStatus;
+    /** Whether the computer answered in the last minute. A run for an offline computer waits (until `expiresAt`). */
+    machineOnline: boolean;
+    expiresAt: number;
+}
+export interface DeviceRunView {
+    commandId: string;
+    linkId: string;
+    machineId: string;
+    /** "commands" (a declared command) or "workspace" (the shared command line). */
+    capability?: string;
+    /** The named agent, for workspace jobs. */
+    agent?: string | null;
+    name: string;
+    params: Record<string, unknown>;
+    argv: string[];
+    status: DeviceRunStatus;
+    exitCode: number | null;
+    signal: string | null;
+    /** Why it ended when it did not simply exit: "machine_restarted", "cancelled: …", "timed out after …", a refusal. */
+    reason: string | null;
+    /** The first 1 MB of output (stdout and stderr interleaved). */
+    output?: string;
+    /** When `truncated` (or the command keeps only the tail), the last 64 KB. */
+    tail?: string;
+    /** The command's parsed answer, when it declared `result: "json"` and ended well. */
+    result?: unknown;
+    /** Why `result` is missing: not JSON, or larger than the stored head. */
+    resultError?: string | null;
+    /** How its output travelled: live, batched or final (the command's `output.mode`). */
+    outputMode?: "live" | "batched" | "final";
+    outputBytes: number;
+    outputSeq: number;
+    truncated: boolean;
+    createdAt: number;
+    startedAt: number | null;
+    endedAt: number | null;
+    expiresAt: number;
+}
+export interface DeviceRunOptions {
+    /** Which computer. Optional when exactly one active computer is connected. */
+    linkId?: string;
+    /** How long the run may wait for an offline computer before it expires. Default 600 s. */
+    expiresInSeconds?: number;
+}
+export interface Devices {
+    list(): Promise<DeviceSummary[]>;
+    run(name: string, params?: Record<string, unknown>, opts?: DeviceRunOptions): Promise<DeviceRunStarted>;
+    get(commandId: string): Promise<DeviceRunView>;
+    /** Wait for a run to end, up to `timeoutSeconds` (≤ 55 in an op; use a task for longer). Returns the run as it is then. */
+    wait(commandId: string, opts?: {
+        timeoutSeconds?: number;
+    }): Promise<DeviceRunView>;
+    cancel(commandId: string): Promise<{
+        status: string;
+    }>;
+    /**
+     * One line of the shared command line on the computer, as a NAMED agent —
+     * `ls`, `tree`, `cat -n f --lines 10:40`, `write f` / `edit f` / `patch f`
+     * (content on `stdin`), `run npm test`, `term new dev npm run dev`, `undo <op>`
+     * (`help` lists them). Needs a workspace grant (a folder or the computer).
+     * Waits up to `waitSeconds` (default 30, ≤ 55) and returns the answer.
+     */
+    sh(line: string, opts: {
+        agent: string;
+        stdin?: string;
+        linkId?: string;
+        waitSeconds?: number;
+    }): Promise<ShellResult & {
+        commandId: string;
+        status: DeviceRunStatus;
+    }>;
+}
+/** The statuses a run ends in: done, expired, cancelled, lost. */
+export declare const DEVICE_RUN_TERMINAL: readonly DeviceRunStatus[];

package/dist/device.js

@@ -0,0 +1,15 @@
+/**
+ * Types for `devices(ctx)` — parts of an app that run on the person's own
+ * computer (plugin-device-arm.md §10–§11). The functions live in server.ts
+ * (host-only); the hooks and <ConnectComputer/> in react.ts.
+ *
+ * The flow an app is built around:
+ *   1. its config page renders <ConnectComputer workspaceId nodeId /> — one
+ *      command to paste, a code to check, an Approve button;
+ *   2. its server code runs a DECLARED command (plugin.json `device.commands`):
+ *        const d = devices(ctx);
+ *        const { commandId } = await d.run("train", { epochs: 3 });
+ *   3. its UI shows the run live with useDeviceRun({ workspaceId, nodeId, commandId }).
+ */
+/** The statuses a run ends in: done, expired, cancelled, lost. */
+export const DEVICE_RUN_TERMINAL = ["done", "expired", "cancelled", "lost"];