@superpanel-sdk/runtime 0.5.0 → 0.7.0

package/README.md

@@ -1,11 +1,11 @@
 # @superpanel-sdk/runtime
 
-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.
+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 `>=22.15`.

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

@@ -4,18 +4,14 @@ import type { CompiledSlotSchema } from '../../core/slot/types.js';
  * `__gen/tables.type.ts`, the one copy every sequence shares; only the subject is the sequence's.
  */
 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).
+ * 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): string;
+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
@@ -23,7 +19,7 @@ export declare function emitGenIndexSource(functionsImport: string | null, varia
  */
 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
+ * 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;
@@ -31,5 +27,4 @@ export declare function emitCompanyGenIndexSource(): string;
 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

@@ -126,37 +126,20 @@ export function emitSlotsSource(subject) {
 // 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';
+export type { 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).
+ * 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) {
+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. */
@@ -167,41 +150,67 @@ export type InstanceVariables = VariablesOf<Record<never, never>>;`;
         ? `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: define helpers bound to this sequence's case and tables, plus generated types
+// Sequence entry: page helpers and function types bound to this sequence's 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,
+  page as runtimePageFn,
+  field as runtimeFieldFn,
+  refField as runtimeRefFieldFn,
+  createRow as runtimeCreateRow,
+  run as runtimeRun,
   deleteRow as runtimeDeleteRow,
-  field as runtimeField,
-  refField as runtimeRefField,
-  runFunction as runtimeRunFunction,
-  schemaField as runtimeSchemaField,
+  functionHandles as runtimeFunctionHandles,
+  actionHandles as runtimeActionHandles,
+  type ActionHandles,
+  type FunctionHandles,
+  type TypedPageFns,
+  type Ctx as RuntimeCtx,
   type CaseOrchestrator as RuntimeCaseOrchestrator,
-  type CaseOrchestratorContacts as RuntimeCaseOrchestratorContacts,
+  type EventHandlers,
   type Resolve as RuntimeResolve,
-  type Schedules,
   type VariablesOf,
   type RowOf,
   type TypedDb,
   type PageChannel,
+  type TypedActionContext,
   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';
+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 { CaseInput, CaseOrchestratorInput } from './case-context.type.ts';
 export type { PageTables, RefTargets, Rows, SubjectTable } from './slots.type.ts';
-export type { Id } from '@superpanel-sdk/runtime';
+export type { ContactSchedule, Email, Id, IsoDate, IsoDateTime, Phone, TimeOfDay } from '@superpanel-sdk/runtime';
 
 type PageModule = TypedPageModule<PageTables, SubjectTable>;
 /**
@@ -212,40 +221,39 @@ export type PageContext<C extends PageChannel = PageChannel> = TypedPageContext<
 /**
  * \`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.
+ * \`db\` takes 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).
+ * 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 const defineAction = runtimeDefineAction as unknown as PageModule['defineAction'];
+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>;
 /**
- * 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.
+ * 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 runFunction = runtimeRunFunction as unknown as (
-  name: keyof Functions & string,
-  options?: Parameters<typeof runtimeRunFunction>[1],
-) => ReturnType<typeof runtimeRunFunction>;
+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. */
@@ -254,30 +262,32 @@ export type Db = TypedDb<PageTables>;
 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>();
+/**
+ * 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 (c, ctx) => …\`;
- * \`ctx.api.db\` take the company's tables and fields.
+ * \`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<CaseOrchestratorInput, PageTables>;
-/** \`orchestrator.ts\`: \`export const contacts: CaseOrchestratorContacts = async (c, ctx) => contactIds\`. */
-export type CaseOrchestratorContacts = RuntimeCaseOrchestratorContacts<CaseOrchestratorInput, PageTables>;
+export type CaseOrchestrator = RuntimeCaseOrchestrator<PageTables, SubjectTable>;
 
-/** \`resolve.ts\`: \`export const resolve: Resolve = async (ctx) => …\`; \`ctx.api.db\` take the company's tables. */
+/** \`resolve.ts\`: \`export const resolve: Resolve = async (ctx, conversation) => …\`; \`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>;
 `;
 }
 /**
@@ -295,18 +305,6 @@ import type { CellBinding, ContactSchedule, Id, RowRef } from '@superpanel-sdk/r
 
 export type FieldState = "empty" | "filled" | "asked_unknown" | "declined";
 
-export type FieldHistoryEntry = {
-  value: string | number | boolean | string[] | ContactSchedule | null;
-  state: FieldState;
-  at: number;
-  by:
-    | "slot-filling"
-    | "function"
-    | "human"
-    | "import"
-    | "platform";
-};
-
 export type FieldValueBase = {
   reason: string | null;
   state: FieldState;
@@ -317,7 +315,6 @@ export type FieldValueBase = {
     | "human"
     | "import"
     | "platform";
-  history: FieldHistoryEntry[];
 };
 
 /** One row of each table, as a view receives it. */
@@ -328,23 +325,24 @@ ${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\`). */
+/** 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))};
 `;
 }
 /**
- * The repository root's `__gen/index.ts`: what `resolve.ts`, `webhook.ts` and `schedules.ts` import to get
+ * 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 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
+// 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 {
   defineSchedules as runtimeDefineSchedules,
-  defineWebhook as runtimeDefineWebhook,
   type CompanyResolve as RuntimeCompanyResolve,
+  type OnError as RuntimeOnError,
+  type Ctx as RuntimeCtx,
   type RowOf,
   type Schedules,
   type TypedDb,
@@ -354,16 +352,24 @@ import type { PageTables } from './tables.type.ts';
 
 export type { PageTables } from './tables.type.ts';
 export type { Id } from '@superpanel-sdk/runtime';
+export type { CodeErrorEvent } from '@superpanel-sdk/runtime';
 
-/** \`resolve.ts\`: \`export const resolve: CompanyResolve = async (ctx) => …\`; \`ctx.api.db\` takes the company's tables. */
+/** 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 = defineWebhook(async (ctx) => …)\`; \`ctx.api.db\` takes the company's tables. */
-export const defineWebhook = runtimeDefineWebhook as (handler: WebhookHandler<PageTables>) => WebhookHandler<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) => … } })\`.
+ * \`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. */
@@ -376,7 +382,6 @@ export function emitCompanyTablesStub() {
 // Stub — run: superpanel-sdk-runtime type:gen
 
 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>>;
@@ -389,7 +394,6 @@ export function emitSlotsStub() {
 // Stub — run: superpanel-sdk-runtime type:gen
 
 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>>;
@@ -397,14 +401,4 @@ 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 { CaseInput as RuntimeCaseInput } from '@superpanel-sdk/runtime';
-
-export type CaseInput = RuntimeCaseInput;
-export type CaseOrchestratorInput = CaseInput;
-`;
-}
 //# sourceMappingURL=emit.js.map

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

@@ -3,10 +3,8 @@ 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;
@@ -21,10 +19,9 @@ export declare function generateSequence(repoRoot: string, sequenceId: string, o
     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.
+ * 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 generateCompany(repoRoot: string): Promise<void>;
 export declare function generateAll(repoRoot: string, options?: {
     dryRun?: boolean;
     sequenceIds?: string[];
@@ -32,6 +29,7 @@ export declare function generateAll(repoRoot: string, options?: {
 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;
 /**

package/dist/builder/codegen/generate.js

@@ -4,9 +4,9 @@ import { subjectTableIssues } from '../../core/slot/company-metadata.js';
 import { compileSlotSchema } from '../../core/slot/compile-schema.js';
 import { withCompanyImportGraph } from '../company-import-graph.js';
 import { assertNoSlotsModule, listSequenceIds, loadCompanySchema, loadSequenceDefinition, loadSessionSchema, } from '../load.js';
-import { findTsModule, resolveTsModule } from '../paths.js';
+import { findTsModule, requirePagePath, resolveTsModule } from '../paths.js';
 import { fatalSlotSchemaIssues } from '../slot-schema-validation.js';
-import { emitCaseContextSource, emitCaseContextStub, emitCompanyGenIndexSource, emitCompanyTablesSource, emitCompanyTablesStub, emitGenIndexSource, emitSlotsSource, emitSlotsStub, } from './emit.js';
+import { emitCompanyGenIndexSource, emitCompanyTablesSource, emitCompanyTablesStub, emitGenIndexSource, emitSlotsSource, emitSlotsStub, } from './emit.js';
 export { listSequenceIds };
 /** The repository root's `__gen/`: types for `resolve.ts` and `webhook.ts`, bound to the company's tables. */
 export function companyGenPaths(repoRoot) {
@@ -22,7 +22,8 @@ function sequenceSlotsGenPath(repoRoot, sequenceId) {
 function legacySlotsConfigGenPath(repoRoot, sequenceId) {
     return path.join(repoRoot, 'sequences', sequenceId, '__gen', 'slots-config.type.ts');
 }
-function sequenceCaseContextGenPath(repoRoot, sequenceId) {
+/** `__gen/case-context.type.ts` (`CaseInput`, the old `c`): no entry gets a `c` any more (38 §2.2). */
+function legacyCaseContextGenPath(repoRoot, sequenceId) {
     return path.join(repoRoot, 'sequences', sequenceId, '__gen', 'case-context.type.ts');
 }
 /** Generated for the declarative load, which was removed (15 §10.15); type:gen deletes a leftover one. */
@@ -36,7 +37,7 @@ function sequenceGenIndexPath(repoRoot, sequenceId) {
 function functionsImportFor(repoRoot, sequenceId) {
     return moduleImportFor(repoRoot, sequenceId, 'functions');
 }
-/** A module of the sequence (`functions`, `variables`) as `__gen/index.ts` imports it; null when absent. */
+/** A module of the sequence (`functions`, `variables`, `actions`) as `__gen/index.ts` imports it; null when absent. */
 function moduleImportFor(repoRoot, sequenceId, name) {
     const sequenceDir = path.join(repoRoot, 'sequences', sequenceId);
     const found = findTsModule(sequenceDir, name);
@@ -91,48 +92,36 @@ async function generateSequenceInGraph(repoRoot, sequenceId, options, { company,
     if (!options.dryRun)
         writeCompanyGen(repoRoot, { company, session });
     // Every sequence has a page script (15 §10.2): the generated page types read it.
-    if (findTsModule(sequenceDir, 'context.page') === undefined) {
-        throw new Error(`sequences/${sequenceId}: context.page.ts is required (the conversation's page, 15 §10.2)`);
-    }
+    requirePagePath(sequenceDir, sequenceId);
     const source = emitSlotsSource(subject);
-    const caseContextSource = emitCaseContextSource();
-    const indexSource = emitGenIndexSource(functionsImportFor(repoRoot, sequenceId), moduleImportFor(repoRoot, sequenceId, 'variables'));
+    const indexSource = emitGenIndexSource(functionsImportFor(repoRoot, sequenceId), moduleImportFor(repoRoot, sequenceId, 'variables'), moduleImportFor(repoRoot, sequenceId, 'actions'));
     const outPath = sequenceSlotsGenPath(repoRoot, sequenceId);
-    const caseContextOutPath = sequenceCaseContextGenPath(repoRoot, sequenceId);
     const indexOutPath = sequenceGenIndexPath(repoRoot, sequenceId);
     if (!options.dryRun) {
         mkdirSync(path.dirname(outPath), { recursive: true });
         writeFileSync(outPath, source, 'utf8');
-        writeFileSync(caseContextOutPath, caseContextSource, 'utf8');
         writeFileSync(indexOutPath, indexSource, 'utf8');
         rmSync(legacyLoadGenPath(repoRoot, sequenceId), { force: true });
+        rmSync(legacyCaseContextGenPath(repoRoot, sequenceId), { force: true });
         rmSync(legacySlotsConfigGenPath(repoRoot, sequenceId), { force: true });
     }
     return {
         sequenceId,
         outPath,
-        caseContextOutPath,
         indexOutPath,
         source,
-        caseContextSource,
         indexSource,
         tablesSource,
         wrote: !options.dryRun,
     };
 }
 /**
- * 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.
+ * 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 async function generateCompany(repoRoot) {
-    return withCompanyImportGraph(repoRoot, async () => writeCompanyGen(repoRoot, await loadCompanySchemas(repoRoot)));
-}
 export async function generateAll(repoRoot, options = {}) {
     return withCompanyImportGraph(repoRoot, async () => {
         const ids = options.sequenceIds ?? listSequenceIds(repoRoot);
-        if (ids.length === 0) {
-            throw new Error(NO_SEQUENCES(repoRoot));
-        }
         const schemas = await loadCompanySchemas(repoRoot);
         // The root's types depend on the schema only: written with every full run (a schema change is one).
         if (!options.dryRun && !options.sequenceIds)
@@ -154,7 +143,6 @@ export async function generateAll(repoRoot, options = {}) {
         return results;
     });
 }
-const NO_SEQUENCES = (repoRoot) => `No sequences found under ${path.join(repoRoot, 'sequences')} (a sequence is a directory with index.ts)`;
 function assertFileMatches(outPath, next, repoRoot) {
     let current = '';
     try {
@@ -168,9 +156,8 @@ function assertFileMatches(outPath, next, repoRoot) {
     }
 }
 export async function checkSequence(repoRoot, sequenceId) {
-    const { outPath, caseContextOutPath, indexOutPath, source, caseContextSource, indexSource } = await generateSequence(repoRoot, sequenceId, { dryRun: true });
+    const { outPath, indexOutPath, source, indexSource } = await generateSequence(repoRoot, sequenceId, { dryRun: true });
     assertFileMatches(outPath, source, repoRoot);
-    assertFileMatches(caseContextOutPath, caseContextSource, repoRoot);
     assertFileMatches(indexOutPath, indexSource, repoRoot);
 }
 /** The root `__gen/` matches the company schema. */
@@ -180,11 +167,9 @@ export async function checkCompany(repoRoot) {
     assertFileMatches(tablesOutPath, tablesSource, repoRoot);
     assertFileMatches(indexOutPath, indexSource, repoRoot);
 }
+/** The root `__gen/` and every sequence's are up to date; with no sequence, the root's alone. */
 export async function checkAll(repoRoot) {
     const ids = listSequenceIds(repoRoot);
-    if (ids.length === 0) {
-        throw new Error(NO_SEQUENCES(repoRoot));
-    }
     await checkCompany(repoRoot);
     const failures = [];
     for (const sequenceId of ids) {
@@ -200,17 +185,13 @@ export async function checkAll(repoRoot) {
 }
 export function ensureStub(repoRoot, sequenceId) {
     const slotsPath = sequenceSlotsGenPath(repoRoot, sequenceId);
-    const caseContextPath = sequenceCaseContextGenPath(repoRoot, sequenceId);
     mkdirSync(path.dirname(slotsPath), { recursive: true });
     if (!existsSync(slotsPath)) {
         writeFileSync(slotsPath, emitSlotsStub(), 'utf8');
     }
-    if (!existsSync(caseContextPath)) {
-        writeFileSync(caseContextPath, emitCaseContextStub(), 'utf8');
-    }
     const indexPath = sequenceGenIndexPath(repoRoot, sequenceId);
     if (!existsSync(indexPath)) {
-        writeFileSync(indexPath, emitGenIndexSource(functionsImportFor(repoRoot, sequenceId), moduleImportFor(repoRoot, sequenceId, 'variables')), 'utf8');
+        writeFileSync(indexPath, emitGenIndexSource(functionsImportFor(repoRoot, sequenceId), moduleImportFor(repoRoot, sequenceId, 'variables'), moduleImportFor(repoRoot, sequenceId, 'actions')), 'utf8');
     }
 }
 /**

package/dist/builder/company-imports.d.ts

@@ -6,6 +6,11 @@
  * (`function-code.ts`). Both use this one rule, so serve, `compile` and a release agree.
  */
 export declare const RUNTIME_PACKAGE = "@superpanel-sdk/runtime";
+/**
+ * The runtime's test helpers (`testing.ts`): a test file's import. The compile never loads a test file
+ * (it loads a repository from its entries), and refuses this entry in every file it does load.
+ */
+export declare const RUNTIME_TESTING_ENTRY = "@superpanel-sdk/runtime/testing";
 export declare function realPath(filePath: string): string;
 /** The directory of the nearest `package.json` above `file`, else the file's own directory. */
 export declare function packageRootOf(file: string): string;

package/dist/builder/company-imports.js

@@ -9,11 +9,16 @@ import path from 'node:path';
  * (`function-code.ts`). Both use this one rule, so serve, `compile` and a release agree.
  */
 export const RUNTIME_PACKAGE = '@superpanel-sdk/runtime';
+/**
+ * The runtime's test helpers (`testing.ts`): a test file's import. The compile never loads a test file
+ * (it loads a repository from its entries), and refuses this entry in every file it does load.
+ */
+export const RUNTIME_TESTING_ENTRY = `${RUNTIME_PACKAGE}/testing`;
 /**
  * The company API's files in a runtime package: built (with its types, which a tsconfig `paths` may
  * name), or the source the runtime's own tests run.
  */
-const COMPANY_API_FILES = new Set([path.join('dist', 'index.js'), path.join('dist', 'index.d.ts'), path.join('src', 'index.ts')]);
+const COMPANY_API_FILES = new Set(['index'].flatMap((name) => [path.join('dist', `${name}.js`), path.join('dist', `${name}.d.ts`), path.join('src', `${name}.ts`)]));
 const packageNames = new Map();
 export function realPath(filePath) {
     try {
@@ -81,6 +86,9 @@ export function specifierIssue(specifier) {
     }
     if (!isBareSpecifier(specifier) || specifier === RUNTIME_PACKAGE)
         return null;
+    if (specifier === RUNTIME_TESTING_ENTRY) {
+        return `'${specifier}' is for test files only (sequences/<id>/tests/*.test.ts); code a sequence runs imports '${RUNTIME_PACKAGE}'`;
+    }
     if (specifier.startsWith(`${RUNTIME_PACKAGE}/`))
         return `'${specifier}' is the platform's; company code imports '${RUNTIME_PACKAGE}'`;
     return `'${specifier}' is a package; company code imports only '${RUNTIME_PACKAGE}' and the repository's own files`;