@superpanel-sdk/runtime 0.5.0 → 0.7.0

package/dist/builder/compile/compile-sequence.d.ts

@@ -1,6 +1,5 @@
 import type { CompiledSlotSchema } from '../../core/slot/types.js';
-import type { CompiledCompanyMetadata } from '../../core/slot/schema.js';
-import type { CompanyPart, RuntimePackageSource, SequenceBuild } from '../types.js';
+import { type CompanyPart, type RuntimePackageSource, type SequenceBuild, type SourceMaps } from '../types.js';
 /** SequenceBuild cache key. Bump when compiled `code` shape changes. */
 export declare function runtimePackageVersion(): string;
 export declare function runtimePackageSource(repoRoot: string): RuntimePackageSource;
@@ -18,19 +17,19 @@ export type CompileSequenceResult = {
     build: SequenceBuild;
     /** The company schema the build runs against (28 §2): what the company part of the build carries. */
     schema: CompiledSlotSchema;
-    companyMetadata: CompiledCompanyMetadata;
+    /** Where the build's code came from in the company's files, by `functionKey`: kept apart from the build. */
+    sourceMaps: SourceMaps;
     wrote: boolean;
 };
-export type CompileSequenceBuildResult = Omit<CompileSequenceResult, 'companyMetadata'>;
-export declare function compileCompanyMetadataFromRepo(repoRoot: string): Promise<CompiledCompanyMetadata>;
 export declare function compileSequence(repoRoot: string, sequenceId: string, options?: CompileSequenceOptions): Promise<CompileSequenceResult>;
-export declare function compileSequenceBuild(repoRoot: string, sequenceId: string, options?: CompileSequenceOptions): Promise<CompileSequenceBuildResult>;
+export declare function compileSequenceBuild(repoRoot: string, sequenceId: string, options?: CompileSequenceOptions): Promise<CompileSequenceResult>;
 export declare function compileAll(repoRoot: string, options?: CompileSequenceOptions & {
     sequenceIds?: string[];
 }): Promise<CompileSequenceResult[]>;
 /**
  * The company part of the company build (22 §5): the root `resolve.ts` as `companyResolve`, the root
- * `webhook.ts` as `webhook.received`, the root `schedules.ts` as `schedule.<name>` (25 §6.4), and the
+ * `webhook.ts` as `webhook.received`, the root `schedules.ts` as `schedule.<name>` (25 §6.4), the root
+ * `errors.ts` as `onError` (67 §5), and the
  * company schema with no subject. An error in it fails the
  * whole compile.
  */
@@ -56,6 +55,8 @@ export type CompileRepoEvent = {
 export type CompileRepoSequenceResult = {
     ok: true;
     build: SequenceBuild;
+    /** Where its code came from in the company's files, by `functionKey` (kept apart from the build). */
+    sourceMaps: SourceMaps;
 } | {
     ok: false;
     error: string;
@@ -68,13 +69,14 @@ export type CompileRepoOptions = {
     onEvent?: (event: CompileRepoEvent) => void;
 };
 /**
- * Compile company metadata once, then every named sequence in this process, then type-check the
- * repository. A sequence error is collected; a company schema error or a type error rejects the whole
- * call, a type error with the tsc output as its message.
+ * Compile the company part (its schema first) once, then every named sequence in this process, then
+ * type-check the repository. A sequence error is collected; a company schema error or a type error
+ * rejects the whole call, a type error with the tsc output as its message.
  */
 export declare function compileRepo(repoRoot: string, options: CompileRepoOptions): Promise<{
-    companyMetadata: CompiledCompanyMetadata;
     company: CompanyPart;
+    /** The company functions' source maps, by `functionKey` (kept apart from the build). */
+    companySourceMaps: SourceMaps;
     sequences: Record<string, CompileRepoSequenceResult>;
 }>;
 //# sourceMappingURL=compile-sequence.d.ts.map

package/dist/builder/compile/compile-sequence.js

@@ -2,19 +2,24 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { compileSlotSchema } from '../../core/slot/compile-schema.js';
-import { compileCompanyMetadata, subjectTableIssues } from '../../core/slot/company-metadata.js';
+import { subjectTableIssues } from '../../core/slot/company-metadata.js';
 import { ensureCompanyStub, ensureStub } from '../codegen/generate.js';
 import { withCompanyImportGraph } from '../company-import-graph.js';
-import { ORCHESTRATOR_CONTACTS_FUNCTION, ORCHESTRATOR_FUNCTION, } from '../../core/case-orchestrator/types.js';
+import { ORCHESTRATOR_FUNCTION, } from '../../core/case-orchestrator/types.js';
 import { COMPANY_RESOLVE_FUNCTION, RESOLVE_FUNCTION, RESOLVE_MODULE } from '../../core/party/types.js';
 import { compileVariables } from '../../core/sequence/index.js';
 import { WEBHOOK_RECEIVED_FUNCTION } from '../../core/functions/events.js';
-import { isPlatformName, listSequenceIds, loadCompanySchema, loadCompanyWebhook, WEBHOOK_MODULE, loadOfficeHours, loadSequenceCaseOrchestrator, loadSequenceEvents, loadSequenceFunctions, loadSequenceDefinition, loadCompanyResolver, loadSequenceResolver, loadSequenceVariables, loadPageChannels, loadSessionSchema, assertNoSlotsModule, assertNoChannelsModule, } from '../load.js';
-import { findTsModule, requireCompanyResolveModule, requireResolveModule, resolveTsModule } from '../paths.js';
+import { SCHEDULES_MODULE } from '../../core/functions/schedules.js';
+import { isPlatformName, listSequenceIds, loadCompanySchema, loadCompanyWebhook, WEBHOOK_MODULE, loadOfficeHours, loadSequenceCaseOrchestrator, loadSequenceEvents, loadSequenceFunctions, loadSequenceDefinition, loadCompanyResolver, loadSequenceResolver, loadSequenceVariables, loadPageModule, loadSessionSchema, assertNoSlotsModule, assertNoChannelsModule, } from '../load.js';
+import { findTsModule, requireCompanyResolveModule, requirePagePath, requireResolveModule, resolveTsModule } from '../paths.js';
 import { fatalSlotSchemaIssues } from '../slot-schema-validation.js';
+import { readFunctionParameters } from '../function-params.js';
 import { typecheckRepo } from '../typecheck.js';
+import { COMPANY_SCOPE, CONTEXT_PAGE_FUNCTION, functionKey, } from '../types.js';
 import { compileExportModuleCode, compilePageModuleCode } from './function-code.js';
-import { assertNoScheduleNames, loadSchedules, scheduleRegistry } from '../schedules.js';
+import { loadSchedules, scheduleRegistry } from '../schedules.js';
+import { loadOnError } from '../errors.js';
+import { ERRORS_MODULE, ON_ERROR_FUNCTION } from '../../core/functions/errors.js';
 import { toEventRegistry, toFunctionRegistry } from './registry.js';
 /** SequenceBuild cache key. Bump when compiled `code` shape changes. */
 export function runtimePackageVersion() {
@@ -41,23 +46,20 @@ async function loadCompanySchemas(repoRoot) {
     const schemaPath = resolveTsModule(repoRoot, 'schema', `No company schema found. Expected schema.ts or schema/index.ts under ${repoRoot}`);
     return { company: await loadCompanySchema(schemaPath), session: await loadSessionSchema(repoRoot) };
 }
-function compileMetadata({ company, session }) {
-    const result = compileCompanyMetadata(company, session);
-    if (!result.validation.ok || !result.metadata) {
-        throw new Error(result.validation.ok
-            ? 'invalid company metadata'
-            : result.validation.issues.map((issue) => issue.message).join('; '));
+/** The company schema, compiled; a schema error throws, with every issue in the message. */
+function compileCompanySlotSchema({ company, session }) {
+    const { schema, validation } = compileSlotSchema(company, { session });
+    if (!validation.ok) {
+        const fatal = fatalSlotSchemaIssues(validation.issues);
+        if (fatal.length > 0)
+            throw new Error(fatal.map((issue) => issue.message).join('; '));
     }
-    return result.metadata;
-}
-export async function compileCompanyMetadataFromRepo(repoRoot) {
-    return withCompanyImportGraph(repoRoot, async () => compileMetadata(await loadCompanySchemas(repoRoot)));
+    return schema;
 }
 export async function compileSequence(repoRoot, sequenceId, options = {}) {
     return withCompanyImportGraph(repoRoot, async () => {
-        const result = await compileSequenceInGraph(repoRoot, sequenceId, options);
-        const { schemas, ...build } = result;
-        return { ...build, companyMetadata: compileMetadata(schemas) };
+        const { schemas: _, ...result } = await compileSequenceInGraph(repoRoot, sequenceId, options);
+        return result;
     });
 }
 export async function compileSequenceBuild(repoRoot, sequenceId, options = {}) {
@@ -73,17 +75,15 @@ async function compileSequenceInGraph(repoRoot, sequenceId, options) {
     }
     const sequenceDir = path.join(repoRoot, 'sequences', sequenceId);
     assertNoSlotsModule(sequenceDir, sequenceId);
+    // `functions/index.ts` (or `functions.ts`) is optional: without it the sequence has no functions (76 §5.5).
     const functionsPath = findTsModule(sequenceDir, 'functions');
-    if (!functionsPath) {
-        throw new Error(`No sequence functions found. Expected sequences/${sequenceId}/functions.ts or sequences/${sequenceId}/functions/index.ts`);
-    }
     // `__gen/` is gitignored in company repos, so a fresh checkout (server-side compile from a git
     // archive) has no `__gen/index.ts` — which functions.ts / events.ts import at runtime. Write the
     // missing generated files first; existing ones are left untouched.
     ensureStub(repoRoot, sequenceId);
     const schemas = await loadCompanySchemas(repoRoot);
     const { company, session } = schemas;
-    const authored = await loadSequenceFunctions(functionsPath);
+    const authored = functionsPath ? await loadSequenceFunctions(functionsPath) : {};
     // The conversation follows the page (17b): what to do next is worked out from it, not from an agenda.
     for (const removed of ['agenda', 'agendas']) {
         if (findTsModule(sequenceDir, removed)) {
@@ -91,19 +91,26 @@ async function compileSequenceInGraph(repoRoot, sequenceId, options) {
         }
     }
     const caseOrchestratorPath = findTsModule(sequenceDir, 'orchestrator');
-    for (const reserved of [ORCHESTRATOR_FUNCTION, ORCHESTRATOR_CONTACTS_FUNCTION]) {
-        if (Object.hasOwn(authored, reserved)) {
-            throw new Error(`functions must not define '${reserved}'; it is the Case Orchestrator's, from orchestrator.ts`);
-        }
+    if (Object.hasOwn(authored, ORCHESTRATOR_FUNCTION)) {
+        throw new Error(`functions must not define '${ORCHESTRATOR_FUNCTION}'; it is the Case Orchestrator's, from orchestrator.ts`);
     }
     for (const reserved of [RESOLVE_FUNCTION, COMPANY_RESOLVE_FUNCTION]) {
         if (Object.hasOwn(authored, reserved)) {
             throw new Error(`functions must not define '${reserved}'; it is a resolver in ${RESOLVE_MODULE}.ts`);
         }
     }
-    assertNoScheduleNames(Object.keys(authored), `sequences/${sequenceId}/functions`);
-    // The sequence's recurring jobs (25 §6.4): `schedule.<name>` functions, timed by `schedules`.
-    const schedules = await loadSchedules(sequenceDir, `sequences/${sequenceId}/schedules.ts`);
+    // The page script is known by this name among the sequence's functions (`functionKey`).
+    if (Object.hasOwn(authored, CONTEXT_PAGE_FUNCTION)) {
+        throw new Error(`functions must not define '${CONTEXT_PAGE_FUNCTION}'; it is the page script's name (context.page.ts)`);
+    }
+    // Recurring jobs are the company's only (25 §6.4): the repository root's schedules.ts.
+    if (findTsModule(sequenceDir, SCHEDULES_MODULE)) {
+        throw new Error(`sequences/${sequenceId}/${SCHEDULES_MODULE}.ts is not supported: recurring jobs go in the repository root's ${SCHEDULES_MODULE}.ts (import the sequence's functions from there) (25 §6.4)`);
+    }
+    // onError is the company's only (67 §5): the repository root's errors.ts.
+    if (findTsModule(sequenceDir, ERRORS_MODULE)) {
+        throw new Error(`sequences/${sequenceId}/${ERRORS_MODULE}.ts is not supported: onError goes in the repository root's ${ERRORS_MODULE}.ts (67 §5)`);
+    }
     if (findTsModule(sequenceDir, 'party')) {
         throw new Error(`sequences/${sequenceId}/party.ts is no longer supported: export ${RESOLVE_FUNCTION} from sequences/${sequenceId}/${RESOLVE_MODULE}.ts`);
     }
@@ -113,12 +120,7 @@ async function compileSequenceInGraph(repoRoot, sequenceId, options) {
     const functions = {
         ...authored,
         [RESOLVE_FUNCTION]: resolver,
-        ...(caseOrchestratorFn
-            ? {
-                [ORCHESTRATOR_FUNCTION]: { kind: 'orchestrator', main: caseOrchestratorFn.orchestrator },
-                [ORCHESTRATOR_CONTACTS_FUNCTION]: { kind: 'orchestrator', main: caseOrchestratorFn.contacts },
-            }
-            : {}),
+        ...(caseOrchestratorFn ? { [ORCHESTRATOR_FUNCTION]: caseOrchestratorFn } : {}),
     };
     const eventsPath = findTsModule(sequenceDir, 'events');
     const events = eventsPath ? await loadSequenceEvents(eventsPath) : {};
@@ -131,10 +133,9 @@ async function compileSequenceInGraph(repoRoot, sequenceId, options) {
         throw new Error(`sequences/${sequenceId}/view.ts is no longer supported: the Orchestrator reads with ctx.api.db, and names who a Run may contact with contacts in orchestrator.ts`);
     }
     // The conversation's page is the page script, always (15 §10.2): no default page.
-    const pagePath = findTsModule(sequenceDir, 'context.page');
-    if (!pagePath) {
-        throw new Error(`sequences/${sequenceId}: context.page.ts is required (the conversation's page, 15 §10.2)`);
-    }
+    const pagePath = requirePagePath(sequenceDir, sequenceId);
+    // The page's actions (76 §2.11): `actions.ts`, optional, like `functions/`.
+    const actionsPath = findTsModule(sequenceDir, 'actions') ?? null;
     // The FAQ is the page's (24 §7): `faq` in definePage, called when the conversation starts.
     if (findTsModule(sequenceDir, 'knowledge')) {
         throw new Error(`sequences/${sequenceId}/knowledge.ts is no longer supported: return the FAQ from definePage({ faq: (ctx) => [...] }) in context.page.ts (24 §7)`);
@@ -160,22 +161,22 @@ async function compileSequenceInGraph(repoRoot, sequenceId, options) {
     if (findTsModule(sequenceDir, 'load')) {
         throw new Error(`sequences/${sequenceId}/load.ts: declarative load is no longer supported; read with db in context.page.ts`);
     }
-    const orchestrator = caseOrchestratorFn
-        ? { fn: ORCHESTRATOR_FUNCTION, contactsFn: ORCHESTRATOR_CONTACTS_FUNCTION }
-        : null;
+    const orchestrator = caseOrchestratorFn ? { fn: ORCHESTRATOR_FUNCTION } : null;
     const includeCode = options.includeCode ?? true;
-    const [functionsRegistry, resolveCode, caseOrchestratorCode, caseOrchestratorContactsCode, eventsRegistry, pageCode, schedulesRegistry,] = await Promise.all([
-        toFunctionRegistry(authored, { includeCode, modulePath: functionsPath }),
+    const functionMaps = {};
+    const [functionsRegistry, resolveCompiled, caseOrchestratorCompiled, eventsRegistry, page,] = await Promise.all([
+        toFunctionRegistry(authored, { includeCode, ...(functionsPath ? { modulePath: functionsPath } : {}), sourceMaps: functionMaps }),
         includeCode ? compileExportModuleCode(resolvePath, RESOLVE_FUNCTION) : Promise.resolve(undefined),
         caseOrchestratorPath && includeCode
             ? compileExportModuleCode(caseOrchestratorPath, ORCHESTRATOR_FUNCTION)
             : Promise.resolve(undefined),
-        caseOrchestratorPath && includeCode ? compileExportModuleCode(caseOrchestratorPath, 'contacts') : Promise.resolve(undefined),
-        toEventRegistry(events, { includeCode, modulePath: eventsPath }),
-        compilePageModuleCode(pagePath),
-        schedules ? scheduleRegistry(schedules, includeCode) : Promise.resolve({}),
+        toEventRegistry(events, { includeCode, modulePath: eventsPath, sourceMaps: functionMaps }),
+        compilePageModuleCode(pagePath, actionsPath),
     ]);
-    const channels = loadPageChannels(pageCode, sequenceId);
+    const resolveCode = codeKeepingMap(RESOLVE_FUNCTION, resolveCompiled, functionMaps);
+    const caseOrchestratorCode = codeKeepingMap(ORCHESTRATOR_FUNCTION, caseOrchestratorCompiled, functionMaps);
+    const pageCode = page.code;
+    const { channels, actions: actionNames } = loadPageModule(pageCode, sequenceId);
     const runtimeVersion = runtimePackageVersion();
     const build = {
         sequenceId,
@@ -188,31 +189,39 @@ async function compileSequenceInGraph(repoRoot, sequenceId, options) {
         experiments: variables.experiments,
         functions: {
             ...functionsRegistry,
-            [RESOLVE_FUNCTION]: resolveCode === undefined ? { kind: 'noCase' } : { kind: 'noCase', code: resolveCode },
-            ...(caseOrchestratorPath
-                ? {
-                    [ORCHESTRATOR_FUNCTION]: caseOrchestratorCode === undefined
-                        ? { kind: 'orchestrator' }
-                        : { kind: 'orchestrator', code: caseOrchestratorCode },
-                    [ORCHESTRATOR_CONTACTS_FUNCTION]: caseOrchestratorContactsCode === undefined
-                        ? { kind: 'orchestrator' }
-                        : { kind: 'orchestrator', code: caseOrchestratorContactsCode },
-                }
-                : {}),
-            ...schedulesRegistry,
+            [RESOLVE_FUNCTION]: resolveCode === undefined ? {} : { code: resolveCode },
+            ...(caseOrchestratorPath ? { [ORCHESTRATOR_FUNCTION]: caseOrchestratorCode === undefined ? {} : { code: caseOrchestratorCode } } : {}),
         },
         events: eventsRegistry,
         officeHours: await loadOfficeHours(sequenceDir),
         orchestrator,
-        contextPage: { code: pageCode, channels },
-        ...(schedules ? { schedules: schedules.manifest } : {}),
+        contextPage: { code: pageCode, channels, ...functionParameters(authored, functionsPath), ...actionParameters(actionsPath, actionNames, sequenceId) },
     };
     const outPath = sequenceBuildPath(repoRoot, sequenceId);
     if (!options.dryRun) {
         mkdirSync(path.dirname(outPath), { recursive: true });
         writeFileSync(outPath, `${JSON.stringify(build, null, 2)}\n`, 'utf8');
     }
-    return { sequenceId, outPath, build, schema, schemas, wrote: !options.dryRun };
+    return {
+        sequenceId,
+        outPath,
+        build,
+        schema,
+        schemas,
+        sourceMaps: keyedMaps(sequenceId, { ...functionMaps, [CONTEXT_PAGE_FUNCTION]: page.map }),
+        wrote: !options.dryRun,
+    };
+}
+/** Maps by name in `scope`, keyed as the platform knows the code: its {@link functionKey}. */
+function keyedMaps(scope, byName) {
+    return Object.fromEntries(Object.entries(byName).map(([name, map]) => [functionKey(scope, name), map]));
+}
+/** A compiled function's code, its map kept in `maps` by the function's name; nothing when not compiled. */
+function codeKeepingMap(name, compiled, maps) {
+    if (!compiled)
+        return undefined;
+    maps[name] = compiled.map;
+    return compiled.code;
 }
 export async function compileAll(repoRoot, options = {}) {
     return withCompanyImportGraph(repoRoot, async () => {
@@ -220,52 +229,65 @@ export async function compileAll(repoRoot, options = {}) {
         if (ids.length === 0) {
             throw new Error(`No sequences found under ${path.join(repoRoot, 'sequences')} (a sequence is a directory with index.ts)`);
         }
-        const companyMetadata = compileMetadata(await loadCompanySchemas(repoRoot));
+        compileCompanySlotSchema(await loadCompanySchemas(repoRoot));
         const results = [];
         for (const sequenceId of ids) {
             const { schemas: _, ...result } = await compileSequenceInGraph(repoRoot, sequenceId, options);
-            results.push({ ...result, companyMetadata });
+            results.push(result);
         }
         return results;
     });
 }
 /**
  * The company part of the company build (22 §5): the root `resolve.ts` as `companyResolve`, the root
- * `webhook.ts` as `webhook.received`, the root `schedules.ts` as `schedule.<name>` (25 §6.4), and the
+ * `webhook.ts` as `webhook.received`, the root `schedules.ts` as `schedule.<name>` (25 §6.4), the root
+ * `errors.ts` as `onError` (67 §5), and the
  * company schema with no subject. An error in it fails the
  * whole compile.
  */
 export async function compileCompanyPart(repoRoot, options = {}) {
+    return (await compileCompanyPartWithMaps(repoRoot, options)).part;
+}
+/** {@link compileCompanyPart}, with the source maps of its functions by `functionKey` (kept apart from the build). */
+async function compileCompanyPartWithMaps(repoRoot, options) {
     return withCompanyImportGraph(repoRoot, async () => {
         const includeCode = options.includeCode ?? true;
         // `resolve.ts` and `webhook.ts` import the root `__gen/`, which a fresh checkout does not have.
         ensureCompanyStub(repoRoot);
-        const { company, session } = await loadCompanySchemas(repoRoot);
+        // The schema first: an error in it fails the compile before any company code loads.
+        const schema = compileCompanySlotSchema(await loadCompanySchemas(repoRoot));
         const companyResolvePath = requireCompanyResolveModule(repoRoot);
         await loadCompanyResolver(companyResolvePath);
         assertNoChannelsModule(repoRoot);
         const webhookPath = findTsModule(repoRoot, WEBHOOK_MODULE);
         if (webhookPath)
             await loadCompanyWebhook(webhookPath);
-        const schedules = await loadSchedules(repoRoot, 'schedules.ts');
-        const [resolveCode, webhookCode, schedulesRegistry] = await Promise.all([
+        const schedules = await loadSchedules(repoRoot);
+        const onError = await loadOnError(repoRoot);
+        const sourceMaps = {};
+        const [resolveCompiled, webhookCompiled, schedulesRegistry, onErrorCompiled] = await Promise.all([
             includeCode ? compileExportModuleCode(companyResolvePath, RESOLVE_FUNCTION) : Promise.resolve(undefined),
             includeCode && webhookPath ? compileExportModuleCode(webhookPath, 'received') : Promise.resolve(undefined),
-            schedules ? scheduleRegistry(schedules, includeCode) : Promise.resolve({}),
+            schedules ? scheduleRegistry(schedules, includeCode, sourceMaps) : Promise.resolve({}),
+            includeCode && onError ? compileExportModuleCode(onError.path, ON_ERROR_FUNCTION) : Promise.resolve(undefined),
         ]);
-        const entry = (code) => (code === undefined ? { kind: 'noCase' } : { kind: 'noCase', code });
-        const { schema } = compileSlotSchema(company, { session });
-        return {
+        const entry = (name, compiled) => {
+            const code = codeKeepingMap(name, compiled, sourceMaps);
+            return code === undefined ? {} : { code };
+        };
+        const part = {
             functions: {
-                [COMPANY_RESOLVE_FUNCTION]: entry(resolveCode),
-                ...(webhookPath ? { [WEBHOOK_RECEIVED_FUNCTION]: entry(webhookCode) } : {}),
+                [COMPANY_RESOLVE_FUNCTION]: entry(COMPANY_RESOLVE_FUNCTION, resolveCompiled),
+                ...(webhookPath ? { [WEBHOOK_RECEIVED_FUNCTION]: entry(WEBHOOK_RECEIVED_FUNCTION, webhookCompiled) } : {}),
                 ...schedulesRegistry,
+                ...(onError ? { [ON_ERROR_FUNCTION]: entry(ON_ERROR_FUNCTION, onErrorCompiled) } : {}),
             },
             ...(schedules ? { schedules: schedules.manifest } : {}),
             schema,
             runtimeVersion: runtimePackageVersion(),
             runtimeSource: options.runtimeSource ?? runtimePackageSource(repoRoot),
         };
+        return { part, sourceMaps: keyedMaps(COMPANY_SCOPE, sourceMaps) };
     });
 }
 export const COMPILE_CONCURRENCY = 4;
@@ -298,15 +320,17 @@ async function mapPool(items, limit, run) {
     await Promise.all(workers);
 }
 /**
- * Compile company metadata once, then every named sequence in this process, then type-check the
- * repository. A sequence error is collected; a company schema error or a type error rejects the whole
- * call, a type error with the tsc output as its message.
+ * Compile the company part (its schema first) once, then every named sequence in this process, then
+ * type-check the repository. A sequence error is collected; a company schema error or a type error
+ * rejects the whole call, a type error with the tsc output as its message.
  */
 export async function compileRepo(repoRoot, options) {
     return withCompanyImportGraph(repoRoot, async () => {
-        const companyMetadata = compileMetadata(await loadCompanySchemas(repoRoot));
         const runtimeSource = options.runtimeSource ?? runtimePackageSource(repoRoot);
-        const company = await compileCompanyPart(repoRoot, { includeCode: true, runtimeSource });
+        const { part: company, sourceMaps: companySourceMaps } = await compileCompanyPartWithMaps(repoRoot, {
+            includeCode: true,
+            runtimeSource,
+        });
         options.onEvent?.({
             type: 'log',
             text: `Repo build runtime: ${runtimePackageVersion()} (${runtimeSource})`,
@@ -322,7 +346,7 @@ export async function compileRepo(repoRoot, options) {
                     runtimeSource,
                     includeCode: true,
                 }), timeoutMs, `compile timed out after ${Math.round(timeoutMs / 60_000)} minutes`);
-                sequences[sequenceId] = { ok: true, build: result.build };
+                sequences[sequenceId] = { ok: true, build: result.build, sourceMaps: result.sourceMaps };
                 options.onEvent?.({ type: 'log', sequence: sequenceId, text: `Compiled ${sequenceId}` });
                 options.onEvent?.({ type: 'sequence-finished', sequence: sequenceId, ok: true });
             }
@@ -336,7 +360,35 @@ export async function compileRepo(repoRoot, options) {
         if (Object.values(sequences).every((outcome) => outcome.ok)) {
             await typecheckRepo(repoRoot, (text) => options.onEvent?.({ type: 'log', text }));
         }
-        return { companyMetadata, company, sequences };
+        return { company, companySourceMaps, sequences };
     });
 }
+/** The page actions' parameters, from their `args` types (76 §2.11): `actions` of `actions.ts`, as functions' are read; nothing without. */
+function actionParameters(actionsPath, names, sequenceId) {
+    if (!actionsPath || names.length === 0)
+        return {};
+    const typed = readFunctionParameters(actionsPath, 'actions');
+    const out = {};
+    for (const name of names) {
+        const parameters = Object.hasOwn(typed, name) ? typed[name] : undefined;
+        if (!parameters)
+            throw new Error(`sequences/${sequenceId}/${path.basename(actionsPath)}: actions.${name}: the type checker does not see it as a function`);
+        out[name] = { parameters };
+    }
+    return { actions: out };
+}
+/** The functions' parameters, from their `args` types (38 §2.4), for the page's function buttons; nothing without functions. */
+function functionParameters(functions, functionsPath) {
+    if (!functionsPath || Object.keys(functions).length === 0)
+        return {};
+    const typed = readFunctionParameters(functionsPath, 'functions');
+    const out = {};
+    for (const name of Object.keys(functions)) {
+        const parameters = Object.hasOwn(typed, name) ? typed[name] : undefined;
+        if (!parameters)
+            throw new Error(`${functionsPath}: functions.${name}: the type checker does not see it as a function`);
+        out[name] = { parameters };
+    }
+    return { functions: out };
+}
 //# sourceMappingURL=compile-sequence.js.map

package/dist/builder/compile/function-code.d.ts

@@ -1,20 +1,26 @@
+import type { FunctionSourceMap } from '../types.js';
 /**
  * Compile a single function implementation to a standalone JS expression string
  * suitable for QuickJS `eval` / registry `code` fields (minified).
  */
 export declare function compileFunctionCode(fn: (...args: never[]) => unknown): Promise<string>;
+/** A function's or page script's compiled code, and where its positions were in the company's files. */
+export type CompiledModule = {
+    code: string;
+    map: FunctionSourceMap;
+};
 /** Bundle one registered function with module-local helpers and constants. */
-export declare function compileFunctionModuleCode(modulePath: string, functionName: string): Promise<string>;
+export declare function compileFunctionModuleCode(modulePath: string, functionName: string): Promise<CompiledModule>;
 /** Bundle one event handler (a plain function under the `events` export) with module-local helpers. */
-export declare function compileEventModuleCode(modulePath: string, eventName: string): Promise<string>;
+export declare function compileEventModuleCode(modulePath: string, eventName: string): Promise<CompiledModule>;
 /** Bundle one job's `run` of a `schedules.ts` (25 §6.4) with module-local helpers. */
-export declare function compileScheduleModuleCode(modulePath: string, scheduleName: string): Promise<string>;
-/** Bundle a module's named export (a plain function, or a `define*` result's `main`) with its helpers. */
-export declare function compileExportModuleCode(modulePath: string, exportName: string): Promise<string>;
+export declare function compileScheduleModuleCode(modulePath: string, scheduleName: string): Promise<CompiledModule>;
+/** Bundle a module's named export (a function) with its helpers. */
+export declare function compileExportModuleCode(modulePath: string, exportName: string): Promise<CompiledModule>;
 /**
- * Bundle a sequence's page script (`context.page.ts`, 15 §10.2) with its helpers and the page module:
- * the result evaluates to `pageEntry(module)`, which renders the page or runs one of its actions
- * (`core/page/define.ts`).
+ * Bundle a sequence's page script (`context.page.ts`, 15 §10.2) with its helpers, and its page actions
+ * (`actions.ts`, 76 §2.11) when it has them: the result evaluates to `pageEntry(module, actions)`, which
+ * renders the page or runs one of its actions (`core/page/define.ts`).
  */
-export declare function compilePageModuleCode(modulePath: string): Promise<string>;
+export declare function compilePageModuleCode(modulePath: string, actionsPath?: string | null): Promise<CompiledModule>;
 //# sourceMappingURL=function-code.d.ts.map

package/dist/builder/compile/function-code.js

@@ -16,20 +16,23 @@ function runtimeModule(name) {
 const ENTRY_FILE = 'superpanel-function-entry.ts';
 /** Marks a resolve the plugin asked for itself, so it does not check its own request. */
 const CHECKED = Symbol('company import checked');
-/**
- * Checks every import a company file makes (company-imports.ts) and bundles `@superpanel-sdk/runtime` as
- * this runtime's own company API (`src/index.ts`): a code string carries the helpers of the runtime that
- * compiled it, whichever copy the repository would resolve, and keeps of them only what it uses.
- */
-function companyImportsPlugin(repoRoot, entryFile) {
+/** Whether `file` is the company's own code: in the repository, outside its dependencies, not the compile's entry. */
+function companyFileCheck(repoRoot, entryFile) {
     const root = realPath(repoRoot);
-    const isCompanyFile = (file) => {
+    return (file) => {
         // The entry is the compile's own (it picks the export and the page's `pageEntry`), not the company's.
         if (!path.isAbsolute(file) || file === entryFile)
             return false;
         const relative = path.relative(root, realPath(file));
         return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative) && !relative.split(path.sep).includes('node_modules');
     };
+}
+/**
+ * Checks every import a company file makes (company-imports.ts) and bundles `@superpanel-sdk/runtime` as
+ * this runtime's own company API (`src/index.ts`): a code string carries the helpers of the runtime that
+ * compiled it, whichever copy the repository would resolve, and keeps of them only what it uses.
+ */
+function companyImportsPlugin(repoRoot, isCompanyFile) {
     return {
         name: 'superpanel-company-imports',
         setup(build) {
@@ -74,12 +77,8 @@ export async function compileFunctionCode(fn) {
         logLevel: 'silent',
     });
     const text = result.code.trim();
-    if (text.includes('@superpanel-sdk/runtime') ||
-        text.includes('defineCaseFunc') ||
-        text.includes('defineNoCaseFunc') ||
-        text.includes('defineEvents') ||
-        text.includes('bindDefines')) {
-        throw new Error('compiled function code still references define* / @superpanel-sdk/runtime');
+    if (text.includes('@superpanel-sdk/runtime')) {
+        throw new Error('compiled function code still references @superpanel-sdk/runtime');
     }
     const m = /^export\s+default\s*/.exec(text);
     if (!m) {
@@ -87,40 +86,68 @@ export async function compileFunctionCode(fn) {
     }
     return text.slice(m[0].length).replace(/;?\s*$/, '');
 }
+/** The wrapper around the bundle: the code is one expression, and starts on line 2 (an evaluator's `(` shifts no frame). */
+const BUNDLE_HEAD = '(()=>{';
+const BUNDLE_TAIL = ';return __superpanel_function.default})()';
 async function compileModuleSelection(modulePath, selection, imports = '') {
     // The compile bundles inside its import graph; a caller outside one (a test) bundles within the module's package.
-    const repoRoot = companyRepoRoot() ?? packageRootOf(modulePath);
-    const entryFile = path.join(path.dirname(modulePath), ENTRY_FILE);
+    // Its real path: the map's sources are relative to it, as esbuild resolves files through symlinks.
+    const repoRoot = realPath(companyRepoRoot() ?? packageRootOf(modulePath));
+    const entryFile = path.join(realPath(path.dirname(modulePath)), ENTRY_FILE);
+    const isCompanyFile = companyFileCheck(repoRoot, entryFile);
     const result = await esbuild.build({
         stdin: {
             contents: `import * as mod from ${JSON.stringify(modulePath)};
 ${imports}
 const selected = ${selection};
 export default selected;`,
-            resolveDir: path.dirname(modulePath),
+            resolveDir: path.dirname(entryFile),
             sourcefile: ENTRY_FILE,
             loader: 'ts',
         },
+        absWorkingDir: repoRoot,
         bundle: true,
         write: false,
+        outfile: 'superpanel-function.js',
         platform: 'neutral',
         format: 'iife',
         globalName: '__superpanel_function',
         target: 'es2022',
         minify: true,
+        // Functions keep their own names: a stack frame's name is the running function's, which a source
+        // map cannot give back (its `names` say what each renamed identifier was, not which function a
+        // position is in). The company Worker's own bundle keeps them too (`keep_names`).
+        keepNames: true,
         logLevel: 'silent',
-        plugins: [companyImportsPlugin(repoRoot, entryFile)],
+        banner: { js: BUNDLE_HEAD },
+        footer: { js: BUNDLE_TAIL },
+        sourcemap: 'external',
+        sourcesContent: false,
+        plugins: [companyImportsPlugin(repoRoot, isCompanyFile)],
     });
-    const output = result.outputFiles[0]?.text.trim();
-    if (!output) {
+    const code = result.outputFiles.find((file) => file.path.endsWith('.js'))?.text.trim();
+    const map = result.outputFiles.find((file) => file.path.endsWith('.js.map'))?.text;
+    if (!code || !map) {
         throw new Error(`Failed to compile function module ${modulePath}`);
     }
-    return `(()=>{${output};return __superpanel_function.default})()`;
+    return { code, map: companySourceMap(JSON.parse(map), repoRoot, isCompanyFile) };
+}
+/**
+ * The map as the platform keeps it: the company's files by their path from the repository root, every
+ * other source `null` (no platform paths, and smaller), and only what a stack lookup reads.
+ */
+function companySourceMap(map, repoRoot, isCompanyFile) {
+    return {
+        version: 3,
+        sources: map.sources.map((source) => (source !== null && isCompanyFile(path.resolve(repoRoot, source)) ? source : null)),
+        names: map.names,
+        mappings: map.mappings,
+    };
 }
 /** Bundle one registered function with module-local helpers and constants. */
 export function compileFunctionModuleCode(modulePath, functionName) {
     const registry = `(mod.functions ?? mod.default?.functions ?? mod.default)`;
-    return compileModuleSelection(modulePath, `${registry}[${JSON.stringify(functionName)}].main`);
+    return compileModuleSelection(modulePath, `${registry}[${JSON.stringify(functionName)}]`);
 }
 /** Bundle one event handler (a plain function under the `events` export) with module-local helpers. */
 export function compileEventModuleCode(modulePath, eventName) {
@@ -132,17 +159,20 @@ export function compileScheduleModuleCode(modulePath, scheduleName) {
     const registry = `(mod.schedules ?? mod.default?.schedules ?? mod.default)`;
     return compileModuleSelection(modulePath, `${registry}[${JSON.stringify(scheduleName)}].run`);
 }
-/** Bundle a module's named export (a plain function, or a `define*` result's `main`) with its helpers. */
+/** Bundle a module's named export (a function) with its helpers. */
 export function compileExportModuleCode(modulePath, exportName) {
-    const entry = `(mod[${JSON.stringify(exportName)}] ?? mod.default)`;
-    return compileModuleSelection(modulePath, `(${entry}.main ?? ${entry})`);
+    return compileModuleSelection(modulePath, `(mod[${JSON.stringify(exportName)}] ?? mod.default)`);
 }
 /**
- * Bundle a sequence's page script (`context.page.ts`, 15 §10.2) with its helpers and the page module:
- * the result evaluates to `pageEntry(module)`, which renders the page or runs one of its actions
- * (`core/page/define.ts`).
+ * Bundle a sequence's page script (`context.page.ts`, 15 §10.2) with its helpers, and its page actions
+ * (`actions.ts`, 76 §2.11) when it has them: the result evaluates to `pageEntry(module, actions)`, which
+ * renders the page or runs one of its actions (`core/page/define.ts`).
  */
-export function compilePageModuleCode(modulePath) {
-    return compileModuleSelection(modulePath, 'pageEntry(mod)', `import { pageEntry } from ${JSON.stringify(runtimeModule('core/page/define'))};`);
+export function compilePageModuleCode(modulePath, actionsPath = null) {
+    const imports = [
+        `import { pageEntry } from ${JSON.stringify(runtimeModule('core/page/define'))};`,
+        ...(actionsPath ? [`import * as actionsModule from ${JSON.stringify(actionsPath)};`] : []),
+    ].join('\n');
+    return compileModuleSelection(modulePath, actionsPath ? 'pageEntry(mod, actionsModule)' : 'pageEntry(mod, null)', imports);
 }
 //# sourceMappingURL=function-code.js.map