@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/README.md

@@ -1,14 +1,14 @@
 # @superpanel-sdk/runtime
 
-Slot + Stage runtime used by company repos and the platform: schema, writes, derived recompute, agenda compile/walk/simulate, and company-repo CLI.
+Slot + Stage runtime used by company repos and the platform: schema, writes, the page contract (`definePage`: persona, FAQ, per-channel page functions, channel actions), and company-repo CLI.
 
-This package is currently published as an **internal prerelease**. Install a tagged build, not `latest`:
+Each prod deploy of the platform publishes the runtime it runs as `latest`:
 
 ```bash
-npm i @superpanel-sdk/runtime@next
+npm i @superpanel-sdk/runtime
 ```
 
-Requires Node.js `>=20.12`.
+Requires Node.js `>=22.15`.
 
 ## CLI
 
@@ -18,18 +18,38 @@ npx superpanel-sdk-runtime type:gen --watch
 npx superpanel-sdk-runtime type:gen --check
 npx superpanel-sdk-runtime compile
 npx superpanel-sdk-runtime compile --sequence <id>
+npx superpanel-sdk-runtime login
+npx superpanel-sdk-runtime whoami
+npx superpanel-sdk-runtime logout
 npx superpanel-sdk-runtime serve
+npx superpanel-sdk-runtime serve --no-open
+npx superpanel-sdk-runtime serve --environment <environment-id>
 ```
 
-`serve` reads `.env` from the current working directory:
+`login` authorizes the current user and company in the browser (device authorization flow) and caches the resulting short-lived serve credential in `~/.superpanel/credentials.json`, scoped per backend URL. `serve` first reuses a cached, unexpired credential or opens the browser to log in, then prompts for the environment. A serve takes over the whole environment: every function there runs from the local repository. Pass `--no-open` to copy a fresh authorization URL to the system clipboard instead of opening the browser automatically. Passing `--environment` skips the prompt. `whoami` prints the cached login (email, company, expiry) without touching the network; `logout` clears it.
 
-- `SUPERPANEL_SDK_COMPANY_ID` / `--company`
-- `SUPERPANEL_SDK_API_KEY` / `--api-key`
-- `SUPERPANEL_SDK_BACKEND_URL` / `--url`
+The Backend URL belongs to the company repo, not to the runtime package. Provisioning writes the
+public control-plane URL to `.superpanel/config.json`; no deployment URL is baked into registry,
+tarball, or local-directory installations of this package. At run time, resolution order is:
+
+1. `--url <backend-url>`
+2. `SUPERPANEL_SDK_BACKEND_URL` (environment variable, checked at run time)
+3. `.superpanel/config.json` in the company repo
+
+If none of those resolve to a valid, non-empty URL, the CLI exits with an error instead of guessing a backend.
+
+`--environment` accepts only an environment **ID** (not a name) and must not resolve to `prod`. In an interactive terminal it may be omitted and selected after login; non-interactive invocations must pass both `--environment` and at least one `--sequence`.
 
 ## Imports
 
+Company code imports the company API, and only that: `import { … } from '@superpanel-sdk/runtime'`. The
+compile refuses any other import of this package (`docs/impl/09-runtime-compat.md` §6).
+
+The platform's entries resolve only under the `superpanel-platform` condition (`customConditions` in
+tsconfig, `node --conditions=superpanel-platform`, `WRANGLER_BUILD_CONDITIONS` for wrangler):
+
 ```ts
-import { makeCtx, applyWrites, createAppRouter } from '@superpanel-sdk/runtime';
-import { createFakeApiHost } from '@superpanel-sdk/runtime/fn-context';
+import { createAppRouter, makeCtx } from '@superpanel-sdk/runtime/platform'; // the whole runtime: platform services, tests and scripts
+import { buildActionContext } from '@superpanel-sdk/runtime/worker'; // the user Worker's shell
+import { compileRepo } from '@superpanel-sdk/runtime/compiler'; // what the compile child loads
 ```

package/dist/builder/codegen/emit.d.ts

@@ -1,17 +1,30 @@
-import type { EffectiveSchema } from '../../core/slot/schema.js';
-/** Emit `__gen/slots.type.ts` — Slots only (no CaseContext; avoids cycle with view.ts). */
-export declare function emitSlotsSource(schema: EffectiveSchema): string;
+import type { CompiledSlotSchema } from '../../core/slot/types.js';
 /**
- * Emit `__gen/case-context.type.ts`.
- * Separate from slots.type.ts so dependencies stay one-way:
- *   view.ts → slots.type.ts
- *   case-context.type.ts → view.ts | slots.type.ts
- *   functions → case-context.type.ts
+ * Emit a sequence's `__gen/slots.type.ts` (28 §2.2): the company's table types come from the root
+ * `__gen/tables.type.ts`, the one copy every sequence shares; only the subject is the sequence's.
  */
-export declare function emitCaseContextSource(options: {
-    hasCaseContextView: boolean;
-}): string;
+export declare function emitSlotsSource(subject: string): string;
+/**
+ * `__gen/index.ts`: the one import a sequence's page, functions and events need. Re-exports the
+ * generated types, the page helpers bound to the company's tables (17b, 28 §2), and the types of its
+ * functions and entries (`Ctx`, `Events`, `CaseOrchestrator`, `Resolve`, 38). `functionsImport` is relative to `__gen/` (`null` without a functions module),
+ * `actionsImport` likewise for the page actions (`actions.ts`, 76 §2.11).
+ * Schema-independent, so the same text serves as the stub.
+ */
+export declare function emitGenIndexSource(functionsImport: string | null, variablesImport?: string | null, actionsImport?: string | null): string;
+/**
+ * Emit the repository root's `__gen/tables.type.ts`: the company's tables, as the code at the root
+ * (`resolve.ts`, `webhook.ts`) reads and writes them with `ctx.api.db`, and as every sequence's
+ * `__gen` re-exports them (28 §2.2).
+ */
+export declare function emitCompanyTablesSource(schema: CompiledSlotSchema): string;
+/**
+ * The repository root's `__gen/index.ts`: what `resolve.ts`, `webhook.ts`, `schedules.ts` and `errors.ts` import to get
+ * `ctx.api.db` bound to the company's tables. Schema-independent, so the same text serves as the stub.
+ */
+export declare function emitCompanyGenIndexSource(): string;
+/** Stub written when the repository root has no gen file yet. */
+export declare function emitCompanyTablesStub(): string;
 /** Stub written when a sequence has no gen file yet. */
 export declare function emitSlotsStub(): string;
-export declare function emitCaseContextStub(): string;
 //# sourceMappingURL=emit.d.ts.map

package/dist/builder/codegen/emit.js

@@ -1,77 +1,309 @@
+import { compiledTableEntries, relationsOf } from '../../core/slot/compile-schema.js';
 import { slotFieldEntries } from '../../core/slot/row.js';
-function quoteLiteral(v) {
-    return typeof v === 'number' ? String(v) : JSON.stringify(v);
+/** A table or field name as a property key: bare when it is an identifier, else quoted (13-data-model-v1 §23.6). */
+function propKey(name) {
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
 }
 function dataTypeToTs(dataType) {
     switch (dataType) {
         case 'string':
+        case 'text':
+        case 'phone':
+        case 'email':
         case 'date':
         case 'datetime':
+        case 'time':
+        case 'select':
             return 'string';
+        case 'multi_select':
+            return 'string[]';
         case 'number':
             return 'number';
         case 'boolean':
             return 'boolean';
+        case 'contact_schedule':
+            return 'ContactSchedule';
     }
 }
+/** A field's value type: a `select` one of its options, a `multi_select` a list of them. */
+function baseTypeExpr(field) {
+    if (!field.options?.length)
+        return dataTypeToTs(field.dataType);
+    const one = field.options.map((v) => JSON.stringify(v)).join(' | ');
+    return field.dataType === 'multi_select' ? `Array<${one}>` : one;
+}
 function valueTypeExpr(field) {
-    let base;
-    if (field.enum && field.enum.length > 0) {
-        base = field.enum.map(quoteLiteral).join(' | ');
-    }
-    else {
-        base = dataTypeToTs(field.dataType);
-    }
     // Runtime envelopes always allow null on value (empty / declined / no conclusion).
-    if (field.nullable) {
-        return `${base} | null`;
-    }
-    return `${base} | null`;
+    return `${baseTypeExpr(field)} | null`;
 }
-function emitRowFields(fields) {
+/**
+ * A cell's mode on a page (19-page-writable-cells): `'rw'` when a page may open it with `field(...)`
+ * (not the row id, not the parent), `'ro'` when it never can.
+ */
+function cellMode(fieldName, field) {
+    return fieldName !== 'id' && field.ref?.kind !== 'parent' ? 'rw' : 'ro';
+}
+/**
+ * An `@deprecated` tag above a deprecated field in the generated `Rows` / `PageTables` types. Rows
+ * read and written through `db` do not carry it (typed.ts maps over its own key sets). The flag is
+ * only a compat-check marker and the data stays (01-slot-db §2.3): pages and functions stop using
+ * the field.
+ */
+function deprecatedTag(field, indent) {
+    return field.deprecated ? [`${indent}/** @deprecated */`] : [];
+}
+function emitRowFields(tableName, fields) {
     const fieldLines = [];
     for (const [fieldName, field] of slotFieldEntries(fields)) {
         const valueTs = valueTypeExpr(field);
-        fieldLines.push(`      ${fieldName}: FieldValueBase & { value: ${valueTs} };`);
+        // A ref field (another row's id) is marked so a region cannot list it (13 §20.3.1).
+        const kind = field.ref ? 'ref' : 'value';
+        const binding = `CellBinding<${JSON.stringify(tableName)}, ${JSON.stringify(fieldName)}, '${cellMode(fieldName, field)}', '${kind}'>`;
+        fieldLines.push(...deprecatedTag(field, '      '));
+        fieldLines.push(`      ${propKey(fieldName)}: FieldValueBase & { value: ${valueTs} } & ${binding};`);
     }
     return fieldLines;
 }
-function emitTableType(tableName, rows, fields) {
-    const fieldLines = emitRowFields(fields);
-    const rowBody = `      id: string;\n${fieldLines.join('\n')}`;
-    if (rows === 'multi') {
-        return `    ${tableName}: {
-${rowBody}
-    }[];`;
-    }
-    return `    ${tableName}: {
-${rowBody}
+/** The conversation's contact row is marked `$current`. */
+const PARTY_TABLES = new Set(['contact']);
+/** One row of a table as a view receives it (`Rows[table]`). */
+function emitRowType(tableName, fields) {
+    const meta = [
+        '      id: string;',
+        `      $ref: RowRef<${JSON.stringify(tableName)}>;`,
+        ...(PARTY_TABLES.has(tableName) ? ['      $current?: true;'] : []),
+    ];
+    return `    ${propKey(tableName)}: {
+${[...meta, ...emitRowFields(tableName, fields)].join('\n')}
     };`;
 }
-/** Emit `__gen/slots.type.ts` — Slots only (no CaseContext; avoids cycle with view.ts). */
-export function emitSlotsSource(schema) {
-    const tableBlocks = [];
-    for (const [tableName, table] of Object.entries(schema)) {
-        tableBlocks.push(emitTableType(tableName, table.rows, table.fields));
+/**
+ * `PageTables` (15 §10.15): table → field → its value type, for a ref the table it points at and
+ * whether it is the parent; and the table's ways back under `$relations` (13-data-model-v1 §23.4). What the page module's types
+ * (`TypedPageModule`) are bound to.
+ */
+function emitPageTables(schema) {
+    const lines = [];
+    for (const [tableName, table] of compiledTableEntries(schema)) {
+        const fields = slotFieldEntries(table.fields).flatMap(([fieldName, field]) => {
+            const tag = deprecatedTag(field, '    ');
+            if (field.ref) {
+                const target = JSON.stringify(field.ref.table);
+                const parent = field.ref.kind === 'parent' ? '; parent: true' : '';
+                return [...tag, `    ${propKey(fieldName)}: { value: Id<${target}>; ref: ${target}${parent} };`];
+            }
+            return [...tag, `    ${propKey(fieldName)}: { value: ${baseTypeExpr(field)} };`];
+        });
+        // Ways back (13-data-model-v1 §23.4): `$relations`, apart from the fields (no field starts with `$`).
+        const relations = relationsOf(schema, tableName).map((relation) => `${propKey(relation.name)}: { table: ${JSON.stringify(relation.table)}; field: ${JSON.stringify(relation.field)} }`);
+        if (relations.length > 0)
+            fields.push(`    $relations: { ${relations.join('; ')} };`);
+        lines.push(`  ${propKey(tableName)}: ${fields.length > 0 ? `{\n${fields.join('\n')}\n  }` : '{}'};`);
+    }
+    return lines;
+}
+/** `RefTargets`: table → ref field → the table it points at. */
+function emitRefTargets(schema) {
+    const lines = [];
+    for (const [tableName, table] of compiledTableEntries(schema)) {
+        const refs = slotFieldEntries(table.fields)
+            .filter(([, field]) => field.ref)
+            .map(([fieldName, field]) => `${propKey(fieldName)}: ${JSON.stringify(field.ref.table)}`);
+        lines.push(`  ${propKey(tableName)}: { ${refs.join('; ')}${refs.length > 0 ? ' ' : ''}};`);
     }
+    return lines;
+}
+/** An object type from member lines; `{}` when there are none. */
+function objectType(lines) {
+    return lines.length > 0 ? `{\n${lines.join('\n')}\n}` : '{}';
+}
+/**
+ * Emit a sequence's `__gen/slots.type.ts` (28 §2.2): the company's table types come from the root
+ * `__gen/tables.type.ts`, the one copy every sequence shares; only the subject is the sequence's.
+ */
+export function emitSlotsSource(subject) {
     return `// GENERATED — do not edit
-// Source: company schema + sequence slots → effective schema
+// Source: the company's tables (root __gen) and this sequence's subject
 // Regenerate: superpanel-sdk-runtime type:gen
 
-export type FieldState = "empty" | "filled" | "asked_unknown" | "declined";
+export type { FieldState, FieldValueBase, PageTables, RefTargets, Rows } from '../../../__gen/tables.type.ts';
 
-export type FieldHistoryEntry = {
-  value: string | number | boolean | null;
-  state: FieldState;
-  at: number;
-  by:
-    | "slot-filling"
-    | "derived"
-    | "function"
-    | "human"
-    | "import"
-    | "platform";
-};
+/** The table this sequence's runs are about (\`defineSequence({ subject })\`). */
+export type SubjectTable = ${JSON.stringify(subject)};
+`;
+}
+/**
+ * `__gen/index.ts`: the one import a sequence's page, functions and events need. Re-exports the
+ * generated types, the page helpers bound to the company's tables (17b, 28 §2), and the types of its
+ * functions and entries (`Ctx`, `Events`, `CaseOrchestrator`, `Resolve`, 38). `functionsImport` is relative to `__gen/` (`null` without a functions module),
+ * `actionsImport` likewise for the page actions (`actions.ts`, 76 §2.11).
+ * Schema-independent, so the same text serves as the stub.
+ */
+export function emitGenIndexSource(functionsImport, variablesImport = null, actionsImport = null) {
+    const variablesType = variablesImport
+        ? `type VariablesModule = typeof import(${JSON.stringify(variablesImport)});
+/** This sequence's run variables (\`variables.ts\`), as \`ctx.api.instances.get\` returns them. */
+export type InstanceVariables = VariablesOf<VariablesModule extends { variables: infer V } ? V : Record<never, never>>;`
+        : `/** This sequence's run variables: none without \`variables.ts\`. */
+export type InstanceVariables = VariablesOf<Record<never, never>>;`;
+    const functionsType = functionsImport
+        ? `type FunctionsModule = typeof import(${JSON.stringify(functionsImport)});
+type Functions = FunctionsModule extends { functions: infer F } ? F : FunctionsModule extends { default: infer F } ? F : Record<never, never>;`
+        : `type Functions = Record<never, never>;`;
+    const actionsType = actionsImport
+        ? `type ActionsModule = typeof import(${JSON.stringify(actionsImport)});
+type Actions = ActionsModule extends { actions: infer A } ? A : Record<never, never>;`
+        : `type Actions = Record<never, never>;`;
+    return `// GENERATED — do not edit
+// Sequence entry: page helpers and function types bound to this sequence's tables, plus generated types
+// Regenerate: superpanel-sdk-runtime type:gen
+
+import {
+  choose as runtimeChoose,
+  definePage as runtimeDefinePage,
+  page as runtimePageFn,
+  field as runtimeFieldFn,
+  refField as runtimeRefFieldFn,
+  createRow as runtimeCreateRow,
+  run as runtimeRun,
+  deleteRow as runtimeDeleteRow,
+  functionHandles as runtimeFunctionHandles,
+  actionHandles as runtimeActionHandles,
+  type ActionHandles,
+  type FunctionHandles,
+  type TypedPageFns,
+  type Ctx as RuntimeCtx,
+  type CaseOrchestrator as RuntimeCaseOrchestrator,
+  type EventHandlers,
+  type Resolve as RuntimeResolve,
+  type VariablesOf,
+  type RowOf,
+  type TypedDb,
+  type PageChannel,
+  type TypedActionContext,
+  type TypedPageContext,
+  type TypedPageModule,
+  type TypedReadDb,
+} from '@superpanel-sdk/runtime';
+export { lastActionRun, tried } from '@superpanel-sdk/runtime';
+// The page in functions (76): the ones not bound to this sequence's tables, as they are.
+export {
+  announce,
+  backgroundTransfer,
+  block,
+  button,
+  cancelFollowUp,
+  coldTransfer,
+  convertTime,
+  data,
+  doNow,
+  end,
+  keypad,
+  list,
+  pressKeypad,
+  scheduleFollowUp,
+  text,
+  toolbox,
+  voicemail,
+  warmTransfer,
+} from '@superpanel-sdk/runtime';
+import type { PageTables, SubjectTable } from './slots.type.ts';
+
+export type { PageTables, RefTargets, Rows, SubjectTable } from './slots.type.ts';
+export type { ContactSchedule, Email, Id, IsoDate, IsoDateTime, Phone, TimeOfDay } from '@superpanel-sdk/runtime';
+
+type PageModule = TypedPageModule<PageTables, SubjectTable>;
+/**
+ * A page function's context: \`PageContext<'sms'>\` one channel's (with \`ctx.sms\`), \`PageContext\` any
+ * channel's (what a helper shared by several pages takes; call actions are on \`ctx.call\`).
+ */
+export type PageContext<C extends PageChannel = PageChannel> = TypedPageContext<PageTables, SubjectTable, C>;
+/**
+ * \`context.page.ts\` (17b §9.1): \`export default definePage({ persona: (ctx) => '…', faq: (ctx) => [...], call: async (ctx) => page, sms: …, email: … })\`.
+ * \`persona\` and \`faq\` are called once, when the conversation starts (24 §4).
+ * \`db\` takes the company's tables and fields.
+ */
+export const definePage = runtimeDefinePage as unknown as PageModule['definePage'];
+/**
+ * The rows a row parameter is chosen among (25 §10): \`cancel({ appointment: choose(appointments, (a) => a.date.value) })\`.
+ * The candidates are exactly these rows; with none the button is left off the page.
+ */
+export const choose = runtimeChoose as unknown as PageModule['choose'];
+/**
+ * A page action's \`ctx\` (76 §2.11), in \`actions.ts\`: \`export const actions = { verifyPin: async (ctx: ActionCtx, args: { pin: string }) => { … } }\`.
+ * It runs next to the database, in one transaction; \`db\` takes the company's tables and fields.
+ */
+export type ActionCtx = TypedActionContext<PageTables, SubjectTable>;
+type Fns = TypedPageFns<PageTables, SubjectTable, Functions>;
+/** The page (76 §2.7): \`page({ guide, voice, extraction }, { …content by name })\`; returned by a page function unless it returns \`doNow()\`. */
+export const page = runtimePageFn as unknown as Fns['page'];
+/** A field the AI may write, or read only: \`field(m.incident_date, { expand: true })\`. A ref field is \`refField()\`. */
+export const field = runtimeFieldFn as unknown as Fns['field'];
+/** A ref field: writable, the rows it may be set to (\`options: choose(rows, label)\`); read-only, who its value is (\`label\`). */
+export const refField = runtimeRefFieldFn as unknown as Fns['refField'];
+/** Add a row of this sequence's tables: \`createRow('injury', { fields: ['body_part'], prefill: { case: c.id } })\`. */
+export const createRow = runtimeCreateRow as unknown as Fns['createRow'];
+/** Run a company function (\`fn.x\`) or a page action: \`run(fn.cancelOrder, { prefill: { order: o.id }, args: { reason: 'In their words' } })\`. */
+export const run = runtimeRun as unknown as Fns['run'];
+/** Delete a row and everything under it: \`deleteRow(injury)\`. */
+export const deleteRow = runtimeDeleteRow as unknown as Fns['deleteRow'];
+/** This sequence's company functions (\`functions/\`), by name, for \`run(fn.x, { … })\` (76 §2.15). */
+export const fn = runtimeFunctionHandles() as unknown as FunctionHandles<Functions>;
+/**
+ * This sequence's page actions (\`actions.ts\`), by name, for \`run(act.verifyPin, { … })\` (76 §2.11). An action runs
+ * next to the database, in one transaction.
+ */
+export const act = runtimeActionHandles() as unknown as ActionHandles<Actions, PageTables, SubjectTable>;
+/** A row of \`T\` as \`db\` returns it; \`Inc\` what was \`include\`d (\`Row<'case_contact', { contact: true }>\`). */
+export type Row<T extends keyof PageTables, Inc = undefined> = RowOf<PageTables, T, Inc>;
+/** \`ctx.api.db\` (and an action's \`db\`): the company's tables, reads and writes. */
+export type Db = TypedDb<PageTables>;
+/** \`db\` with the read methods only (a page render): a helper typed with it can only read. */
+export type ReadDb = TypedReadDb<PageTables>;
+
+
+/**
+ * A function's \`ctx\` (38 §2.3): \`export async function cancel(ctx: Ctx, args: { appointment: Id<'appointment'>; reason: string })\`;
+ * \`ctx.api.db\` takes the company's tables and fields.
+ */
+export type Ctx = RuntimeCtx<PageTables>;
+
+/**
+ * \`events.ts\` (38 §2.2): \`export const events: Events = { 'call.ended': async (ctx, { event, subject, instanceId }) => … }\`.
+ */
+export type Events = EventHandlers<PageTables, SubjectTable>;
+
+${functionsType}
+${actionsType}
+${variablesType}
+/** This sequence's functions (\`functions\` module), by name. */
+export type FunctionsOf = Functions;
+
+/**
+ * \`orchestrator.ts\`: \`export const orchestrator: CaseOrchestrator = async (ctx, args) => …\`; \`args.subject\` is
+ * a row of this sequence's subject table, \`ctx.api.db\` takes the company's tables and fields.
+ */
+export type CaseOrchestrator = RuntimeCaseOrchestrator<PageTables, SubjectTable>;
+
+/** \`resolve.ts\`: \`export const resolve: Resolve = async (ctx, conversation) => …\`; \`ctx.api.db\` take the company's tables. */
+export type Resolve = RuntimeResolve<PageTables>;
+
+`;
+}
+/**
+ * Emit the repository root's `__gen/tables.type.ts`: the company's tables, as the code at the root
+ * (`resolve.ts`, `webhook.ts`) reads and writes them with `ctx.api.db`, and as every sequence's
+ * `__gen` re-exports them (28 §2.2).
+ */
+export function emitCompanyTablesSource(schema) {
+    const rowBlocks = compiledTableEntries(schema).map(([tableName, table]) => emitRowType(tableName, table.fields));
+    return `// GENERATED — do not edit
+// Source: company schema (schema/)
+// Regenerate: superpanel-sdk-runtime type:gen
+
+import type { CellBinding, ContactSchedule, Id, RowRef } from '@superpanel-sdk/runtime';
+
+export type FieldState = "empty" | "filled" | "asked_unknown" | "declined";
 
 export type FieldValueBase = {
   reason: string | null;
@@ -79,65 +311,94 @@ export type FieldValueBase = {
   updatedAt: number;
   updatedBy:
     | "slot-filling"
-    | "derived"
     | "function"
     | "human"
     | "import"
     | "platform";
-  history: FieldHistoryEntry[];
 };
 
-export type Slots = {
-  current: {
-    contactId: string;
-    caseContactId: string;
-    caseFileId: string;
-    sessionId: string | null;
-  };
-${tableBlocks.join('\n')}
+/** One row of each table, as a view receives it. */
+export type Rows = {
+${rowBlocks.join('\n')}
 };
+
+/** Each table's ref fields and the table each points at (\`q.rows(table).where(field, node)\`, \`node.follow(field)\`). */
+export type RefTargets = ${objectType(emitRefTargets(schema))};
+
+/** The company's tables as code reads and writes them (\`ctx.api.db\`, a page's and its actions' \`db\`). */
+export type PageTables = ${objectType(emitPageTables(schema))};
 `;
 }
 /**
- * Emit `__gen/case-context.type.ts`.
- * Separate from slots.type.ts so dependencies stay one-way:
- *   view.ts → slots.type.ts
- *   case-context.type.ts → view.ts | slots.type.ts
- *   functions → case-context.type.ts
+ * The repository root's `__gen/index.ts`: what `resolve.ts`, `webhook.ts`, `schedules.ts` and `errors.ts` import to get
+ * `ctx.api.db` bound to the company's tables. Schema-independent, so the same text serves as the stub.
  */
-export function emitCaseContextSource(options) {
-    if (options.hasCaseContextView) {
-        return `// GENERATED — do not edit
-// CaseContext from sequence view.ts
-// Regenerate: superpanel-sdk-runtime type:gen
-
-export type { CaseContext } from '../view.ts';
-`;
-    }
+export function emitCompanyGenIndexSource() {
     return `// GENERATED — do not edit
-// No view.ts — CaseContext is identity with Slots
+// Company entry: types for the code at the repository root (resolve.ts, webhook.ts, schedules.ts, errors.ts), bound to the company's tables
 // Regenerate: superpanel-sdk-runtime type:gen
 
-import type { Slots } from './slots.type.ts';
+import {
+  defineSchedules as runtimeDefineSchedules,
+  type CompanyResolve as RuntimeCompanyResolve,
+  type OnError as RuntimeOnError,
+  type Ctx as RuntimeCtx,
+  type RowOf,
+  type Schedules,
+  type TypedDb,
+  type WebhookHandler,
+} from '@superpanel-sdk/runtime';
+import type { PageTables } from './tables.type.ts';
 
-export type CaseContext = Slots;
+export type { PageTables } from './tables.type.ts';
+export type { Id } from '@superpanel-sdk/runtime';
+export type { CodeErrorEvent } from '@superpanel-sdk/runtime';
+
+/** A function's \`ctx\` (38 §2.3): \`ctx.api.db\` takes the company's tables. */
+export type Ctx = RuntimeCtx<PageTables>;
+/** \`resolve.ts\`: \`export const resolve: CompanyResolve = async (ctx, conversation) => …\`; \`ctx.api.db\` takes the company's tables. */
+export type CompanyResolve = RuntimeCompanyResolve<PageTables>;
+/** \`webhook.ts\`: \`export const received: Webhook = async (ctx, { event }) => …\`; \`ctx.api.db\` takes the company's tables. */
+export type Webhook = WebhookHandler<PageTables>;
+/**
+ * \`schedules.ts\` (25 §6.4): \`export const schedules = defineSchedules({ nightlySync: { cron: '0 2 * * *', timezone: 'UTC', run: async (ctx, { schedule }) => … } })\`.
+ * No case: \`ctx.api.db\` takes the company's tables; start or notify any sequence's instances with \`ctx.api.instances\`.
+ */
+export const defineSchedules = runtimeDefineSchedules as (schedules: Schedules<PageTables>) => Schedules<PageTables>;
+/**
+ * \`errors.ts\` (67 §5): \`export const onError: OnError = async (ctx, { error }) => …\`. Run once for each failure your code
+ * did not catch, and each text or email conversation the AI marked stuck; with no case.
+ */
+export type OnError = RuntimeOnError<PageTables>;
+/** A row of \`T\` as \`db\` returns it; \`Inc\` what was \`include\`d. */
+export type Row<T extends keyof PageTables, Inc = undefined> = RowOf<PageTables, T, Inc>;
+/** \`ctx.api.db\` of the code at the root: the company's tables, reads and writes. */
+export type Db = TypedDb<PageTables>;
 `;
 }
-/** Stub written when a sequence has no gen file yet. */
-export function emitSlotsStub() {
+/** Stub written when the repository root has no gen file yet. */
+export function emitCompanyTablesStub() {
     return `// GENERATED — do not edit
 // Stub — run: superpanel-sdk-runtime type:gen
 
-export type Slots = Record<string, unknown>;
+export type FieldState = "empty" | "filled" | "asked_unknown" | "declined";
+export type FieldValueBase = Record<string, unknown>;
+export type Rows = Record<string, Record<string, unknown>>;
+export type RefTargets = Record<string, Record<string, string>>;
+export type PageTables = Record<string, Record<string, { value: unknown; ref?: string; parent?: true } | Record<string, { table: string; field: string }>>>;
 `;
 }
-export function emitCaseContextStub() {
+/** Stub written when a sequence has no gen file yet. */
+export function emitSlotsStub() {
     return `// GENERATED — do not edit
 // Stub — run: superpanel-sdk-runtime type:gen
 
-import type { Slots } from './slots.type.ts';
-
-export type CaseContext = Slots;
+export type FieldState = "empty" | "filled" | "asked_unknown" | "declined";
+export type FieldValueBase = Record<string, unknown>;
+export type Rows = Record<string, Record<string, unknown>>;
+export type RefTargets = Record<string, Record<string, string>>;
+export type SubjectTable = string;
+export type PageTables = Record<string, Record<string, { value: unknown; ref?: string; parent?: true } | Record<string, { table: string; field: string }>>>;
 `;
 }
 //# sourceMappingURL=emit.js.map

package/dist/builder/codegen/generate.d.ts

@@ -3,19 +3,38 @@ export { listSequenceIds };
 export type GenerateResult = {
     sequenceId: string;
     outPath: string;
-    caseContextOutPath: string;
+    indexOutPath: string;
     source: string;
-    caseContextSource: string;
+    indexSource: string;
+    /** The root `__gen/tables.type.ts` the sequence's types re-export (28 §2.2). */
+    tablesSource: string;
     wrote: boolean;
 };
+/** The repository root's `__gen/`: types for `resolve.ts` and `webhook.ts`, bound to the company's tables. */
+export declare function companyGenPaths(repoRoot: string): {
+    tablesOutPath: string;
+    indexOutPath: string;
+};
 export declare function generateSequence(repoRoot: string, sequenceId: string, options?: {
     dryRun?: boolean;
 }): Promise<GenerateResult>;
+/**
+ * The root `__gen/` and every sequence's (or only `sequenceIds`'). A repository with no sequence gets the
+ * root's alone, as the release type check does (22 §11), so `type:gen` and `typecheck` pass on it locally too.
+ */
 export declare function generateAll(repoRoot: string, options?: {
     dryRun?: boolean;
     sequenceIds?: string[];
 }): Promise<GenerateResult[]>;
 export declare function checkSequence(repoRoot: string, sequenceId: string): Promise<void>;
+/** The root `__gen/` matches the company schema. */
+export declare function checkCompany(repoRoot: string): Promise<void>;
+/** The root `__gen/` and every sequence's are up to date; with no sequence, the root's alone. */
 export declare function checkAll(repoRoot: string): Promise<void>;
 export declare function ensureStub(repoRoot: string, sequenceId: string): void;
+/**
+ * Writes the root `__gen/` files that are missing (a fresh checkout has none: `__gen/` is gitignored),
+ * so `resolve.ts` and `webhook.ts` can import it; existing ones are left untouched.
+ */
+export declare function ensureCompanyStub(repoRoot: string): void;
 //# sourceMappingURL=generate.d.ts.map