@superpanel-sdk/runtime 0.2.3 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @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, derived recompute, the page contract (`definePage`: persona, per-channel page functions, regions and todos, channel actions), and company-repo CLI.
 
 This package is currently published as an **internal prerelease**. Install a tagged build, not `latest`:
 
@@ -8,7 +8,7 @@ This package is currently published as an **internal prerelease**. Install a tag
 npm i @superpanel-sdk/runtime@next
 ```
 
-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,16 +1,34 @@
-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;
+/**
+ * Emit `__gen/case-context.type.ts`: what code working on a case receives as `c` — functions, event
+ * handlers, the Orchestrator: the instance and its business root's id (the page is the conversation's).
+ */
+export declare function emitCaseContextSource(): 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 define helpers bound
+ * to its case (`CaseInput`). `functionsImport` is relative to `__gen/` (`null` without a functions module).
+ * Schema-independent, so the same text serves as the stub.
+ */
+export declare function emitGenIndexSource(functionsImport: string | null, variablesImport?: 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` and `schedules.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;

package/dist/builder/codegen/emit.js

@@ -1,72 +1,306 @@
+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 { FieldHistoryEntry, FieldState, FieldValueBase, PageTables, RefTargets, Rows } from '../../../__gen/tables.type.ts';
+
+/** The table this sequence's runs are about (\`defineSequence({ subject })\`). */
+export type SubjectTable = ${JSON.stringify(subject)};
+`;
+}
+/**
+ * Emit `__gen/case-context.type.ts`: what code working on a case receives as `c` — functions, event
+ * handlers, the Orchestrator: the instance and its business root's id (the page is the conversation's).
+ */
+export function emitCaseContextSource() {
+    return `// GENERATED — do not edit
+// CaseInput: what functions, event handlers and the Orchestrator receive as c (the instance and its business root)
+// Regenerate: superpanel-sdk-runtime type:gen
+
+import type { CaseInput as RuntimeCaseInput } from '@superpanel-sdk/runtime';
+import type { SubjectTable } from './slots.type.ts';
+
+/** What functions, event handlers, orchestrator and contacts receive as \`c\`: the instance, and its business root's id. */
+export type CaseInput = RuntimeCaseInput<SubjectTable>;
+/** What orchestrator and contacts receive as \`c\` (the same as \`CaseInput\`). */
+export type CaseOrchestratorInput = CaseInput;
+`;
+}
+/**
+ * `__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 define helpers bound
+ * to its case (`CaseInput`). `functionsImport` is relative to `__gen/` (`null` without a functions module).
+ * Schema-independent, so the same text serves as the stub.
+ */
+export function emitGenIndexSource(functionsImport, variablesImport = 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>;`;
+    return `// GENERATED — do not edit
+// Sequence entry: define helpers bound to this sequence's case and tables, plus generated types
+// Regenerate: superpanel-sdk-runtime type:gen
+
+import {
+  bindDefines,
+  defineSchedules as runtimeDefineSchedules,
+  choose as runtimeChoose,
+  createRow as runtimeCreateRow,
+  defineAction as runtimeDefineAction,
+  definePage as runtimeDefinePage,
+  deleteRow as runtimeDeleteRow,
+  field as runtimeField,
+  refField as runtimeRefField,
+  runFunction as runtimeRunFunction,
+  schemaField as runtimeSchemaField,
+  type CaseOrchestrator as RuntimeCaseOrchestrator,
+  type CaseOrchestratorContacts as RuntimeCaseOrchestratorContacts,
+  type Resolve as RuntimeResolve,
+  type Schedules,
+  type VariablesOf,
+  type RowOf,
+  type TypedDb,
+  type PageChannel,
+  type TypedPageContext,
+  type TypedPageModule,
+  type TypedReadDb,
+} from '@superpanel-sdk/runtime';
+export { end, lastActionRun, perform, tried } from '@superpanel-sdk/runtime';
+import type { CaseInput, CaseOrchestratorInput } from './case-context.type.ts';
+import type { PageTables, SubjectTable } from './slots.type.ts';
+
+export type { CaseInput, CaseOrchestratorInput } from './case-context.type.ts';
+export type { PageTables, RefTargets, Rows, SubjectTable } from './slots.type.ts';
+export type { Id } 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\` and \`schemaField\` take the company's tables and fields.
+ */
+export const definePage = runtimeDefinePage as unknown as PageModule['definePage'];
+/** A cell the AI may write: \`field(slot, { readOnly, expand })\` (a slot placed as is is read-only). How to fill a field on this page: the page's \`$extraction: { 'table.field': '…' }\`. */
+export const field = runtimeField as unknown as PageModule['field'];
+/**
+ * A ref field (26 §16.2 #7): \`refField(job.referred_by, { options: choose(regulars, (c) => c.first_name.value ?? '') })\`,
+ * the rows the AI may set it to, each with its label; \`{ readOnly: true, options: [...] }\` shows who the current one is.
+ */
+export const refField = runtimeRefField as unknown as PageModule['refField'];
+/** An action parameter taken from the schema: \`schemaField('providers.name')\`, \`schemaField('injuries.id')\` (a row). */
+export const schemaField = runtimeSchemaField as unknown as PageModule['schemaField'];
+/** The built-in action that adds a row: \`createRow('injuries', { fields })\`, called to preset values. */
+export const createRow = runtimeCreateRow as unknown as PageModule['createRow'];
+/** The built-in action that deletes a row (and everything under it): \`deleteRow(row.id)\`. */
+export const deleteRow = runtimeDeleteRow as unknown as PageModule['deleteRow'];
+/**
+ * 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 custom action, declared like an LLM function call (\`parameters\`). Place it called: a row argument
+ * prefilled (\`markError({ injury: i.id })\`) or offered with \`choose(...)\` (25 §10).
+ */
+export const defineAction = runtimeDefineAction as unknown as PageModule['defineAction'];
+/**
+ * A company function (\`functions/\`) as a button, or returned by the page function to run now (20 §6.2):
+ * \`runFunction('importOrders', { label, say, parameters })\`. The name must be one of this sequence's functions.
+ */
+export const runFunction = runtimeRunFunction as unknown as (
+  name: keyof Functions & string,
+  options?: Parameters<typeof runtimeRunFunction>[1],
+) => ReturnType<typeof runtimeRunFunction>;
+/** 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>;
+
+
+/** Functions and event handlers get \`c\`: CaseInput; their \`ctx.api.db\` takes the company's tables and fields. */
+export const { defineCaseFunc, defineNoCaseFunc, defineEvents } = bindDefines<PageTables, CaseInput>();
+
+${functionsType}
+${variablesType}
+/** This sequence's functions (\`functions\` module), by name. */
+export type FunctionsOf = Functions;
+
+/**
+ * \`orchestrator.ts\`: \`export const orchestrator: CaseOrchestrator = async (c, ctx) => …\`;
+ * \`ctx.api.db\` take the company's tables and fields.
+ */
+export type CaseOrchestrator = RuntimeCaseOrchestrator<CaseOrchestratorInput, PageTables>;
+/** \`orchestrator.ts\`: \`export const contacts: CaseOrchestratorContacts = async (c, ctx) => contactIds\`. */
+export type CaseOrchestratorContacts = RuntimeCaseOrchestratorContacts<CaseOrchestratorInput, PageTables>;
+
+/** \`resolve.ts\`: \`export const resolve: Resolve = async (ctx) => …\`; \`ctx.api.db\` take the company's tables. */
+export type Resolve = RuntimeResolve<PageTables>;
+
+/**
+ * \`schedules.ts\` (25 §6.4): \`export const schedules = defineSchedules({ dailyRecall: { cron: '0 8 * * 1-5', timezone: 'America/Phoenix', run: async (ctx) => … } })\`.
+ * No case: \`ctx.api.db\` takes the company's tables; start or notify its instances with \`ctx.api.instances\`.
+ */
+export const defineSchedules = runtimeDefineSchedules as (schedules: Schedules<PageTables>) => Schedules<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 FieldHistoryEntry = {
-  value: string | number | boolean | null;
+  value: string | number | boolean | string[] | ContactSchedule | null;
   state: FieldState;
   at: number;
   by:
     | "slot-filling"
-    | "derived"
     | "function"
     | "human"
     | "import"
@@ -79,7 +313,6 @@ export type FieldValueBase = {
   updatedAt: number;
   updatedBy:
     | "slot-filling"
-    | "derived"
     | "function"
     | "human"
     | "import"
@@ -87,40 +320,67 @@ export type FieldValueBase = {
   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 \`db\`, actions' \`schemaField\`). */
+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` and `schedules.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
+export function emitCompanyGenIndexSource() {
+    return `// GENERATED — do not edit
+// Company entry: types for the code at the repository root (resolve.ts, webhook.ts, schedules.ts), bound to the company's tables
 // Regenerate: superpanel-sdk-runtime type:gen
 
-export type { CaseContext } from '../view.ts';
+import {
+  defineSchedules as runtimeDefineSchedules,
+  defineWebhook as runtimeDefineWebhook,
+  type CompanyResolve as RuntimeCompanyResolve,
+  type RowOf,
+  type Schedules,
+  type TypedDb,
+  type WebhookHandler,
+} from '@superpanel-sdk/runtime';
+import type { PageTables } from './tables.type.ts';
+
+export type { PageTables } from './tables.type.ts';
+export type { Id } from '@superpanel-sdk/runtime';
+
+/** \`resolve.ts\`: \`export const resolve: CompanyResolve = async (ctx) => …\`; \`ctx.api.db\` takes the company's tables. */
+export type CompanyResolve = RuntimeCompanyResolve<PageTables>;
+/** \`webhook.ts\`: \`export const received = defineWebhook(async (ctx) => …)\`; \`ctx.api.db\` takes the company's tables. */
+export const defineWebhook = runtimeDefineWebhook as (handler: WebhookHandler<PageTables>) => WebhookHandler<PageTables>;
+/**
+ * \`schedules.ts\` (25 §6.4): \`export const schedules = defineSchedules({ nightlySync: { cron: '0 2 * * *', timezone: 'UTC', run: async (ctx) => … } })\`.
+ * 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>;
+/** 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 the repository root has no gen file yet. */
+export function emitCompanyTablesStub() {
     return `// GENERATED — do not edit
-// No view.ts — CaseContext is identity with Slots
-// Regenerate: superpanel-sdk-runtime type:gen
-
-import type { Slots } from './slots.type.ts';
+// Stub — run: superpanel-sdk-runtime type:gen
 
-export type CaseContext = Slots;
+export type FieldState = "empty" | "filled" | "asked_unknown" | "declined";
+export type FieldHistoryEntry = Record<string, unknown>;
+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 }>>>;
 `;
 }
 /** Stub written when a sequence has no gen file yet. */
@@ -128,16 +388,23 @@ export function emitSlotsStub() {
     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 FieldHistoryEntry = Record<string, unknown>;
+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 }>>>;
 `;
 }
 export function emitCaseContextStub() {
     return `// GENERATED — do not edit
 // Stub — run: superpanel-sdk-runtime type:gen
 
-import type { Slots } from './slots.type.ts';
+import type { CaseInput as RuntimeCaseInput } from '@superpanel-sdk/runtime';
 
-export type CaseContext = Slots;
+export type CaseInput = RuntimeCaseInput;
+export type CaseOrchestratorInput = CaseInput;
 `;
 }
 //# sourceMappingURL=emit.js.map

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

@@ -4,18 +4,39 @@ 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/` alone, from the company schema: what the root code of a repository with no
+ * sequence is typed by (22 §11). `generateAll` writes it too, with the sequences.
+ */
+export declare function generateCompany(repoRoot: string): Promise<void>;
 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>;
 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