@superpanel-sdk/runtime 0.2.3 → 0.7.0

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

@@ -1,35 +1,65 @@
 import * as esbuild from 'esbuild';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
-const RUNTIME_SHIM_NAMESPACE = 'superpanel-runtime-shim';
-const RUNTIME_SHIM = `
-export function defineComputeFunc(main, options) {
-  return { kind: 'compute', main, ...options };
-}
-export function defineBoolComputeFunc(main, options) {
-  return { kind: 'boolCompute', main, ...options };
-}
-export function defineCustomFunc(main, options) {
-  return { kind: 'custom', main, ...options };
-}
-export function defineSystemFunc(main, options) {
-  return { kind: 'system', main, ...options };
+import { fileURLToPath } from 'node:url';
+import { companyRepoRoot } from '../company-import-graph.js';
+import { RUNTIME_PACKAGE, companyImportError, packageRootOf, realPath, resolvedIssue, specifierIssue, } from '../company-imports.js';
+/**
+ * A module of this runtime as a bundle takes it: `<name>.js` next to this module in the published
+ * package, `<name>.ts` in the source tree.
+ */
+function runtimeModule(name) {
+    const base = path.resolve(path.dirname(fileURLToPath(import.meta.url)), `../../${name}`);
+    return existsSync(`${base}.js`) ? `${base}.js` : `${base}.ts`;
 }
-export function defineCaseContext(main) {
-  return Object.assign(main, { kind: 'caseContextView', main });
+/** The bundle's entry: the compile's own code next to the company module, importing it. */
+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');
+/** 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);
+    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');
+    };
 }
-`;
-function runtimeShimPlugin() {
+/**
+ * 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-runtime-shim',
+        name: 'superpanel-company-imports',
         setup(build) {
-            build.onResolve({ filter: /^@superpanel-sdk\/runtime$/ }, () => ({
-                path: 'runtime',
-                namespace: RUNTIME_SHIM_NAMESPACE,
-            }));
-            build.onLoad({ filter: /.*/, namespace: RUNTIME_SHIM_NAMESPACE }, () => ({
-                contents: RUNTIME_SHIM,
-                loader: 'js',
-            }));
+            build.onResolve({ filter: /.*/ }, async (args) => {
+                if (args.pluginData === CHECKED || !isCompanyFile(args.importer))
+                    return undefined;
+                const refuse = (issue) => ({
+                    errors: [{ text: companyImportError(args.importer, repoRoot, issue).message }],
+                });
+                const issue = specifierIssue(args.path);
+                if (issue)
+                    return refuse(issue);
+                if (args.path === RUNTIME_PACKAGE)
+                    return { path: runtimeModule('index') };
+                const resolved = await build.resolve(args.path, {
+                    kind: args.kind,
+                    importer: args.importer,
+                    resolveDir: args.resolveDir,
+                    pluginData: CHECKED,
+                });
+                if (resolved.errors.length > 0)
+                    return { errors: resolved.errors };
+                const resolvedProblem = resolvedIssue(args.path, resolved.path, repoRoot);
+                if (resolvedProblem)
+                    return refuse(resolvedProblem);
+                return { path: resolved.path, namespace: resolved.namespace, sideEffects: resolved.sideEffects, suffix: resolved.suffix };
+            });
         },
     };
 }
@@ -47,13 +77,8 @@ export async function compileFunctionCode(fn) {
         logLevel: 'silent',
     });
     const text = result.code.trim();
-    if (text.includes('@superpanel-sdk/runtime') ||
-        text.includes('defineComputeFunc') ||
-        text.includes('defineCustomFunc') ||
-        text.includes('defineBoolComputeFunc') ||
-        text.includes('defineSystemFunc') ||
-        text.includes('defineCaseContext')) {
-        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) {
@@ -61,40 +86,93 @@ export async function compileFunctionCode(fn) {
     }
     return text.slice(m[0].length).replace(/;?\s*$/, '');
 }
-async function compileModuleSelection(modulePath, selection) {
+/** 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.
+    // 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),
-            sourcefile: 'superpanel-function-entry.ts',
+            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: [runtimeShimPlugin()],
+        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) {
+    const registry = `(mod.events ?? mod.default?.events ?? mod.default)`;
+    return compileModuleSelection(modulePath, `${registry}[${JSON.stringify(eventName)}]`);
 }
-/** Bundle caseContextView with module-local helpers and constants. */
-export function compileCaseContextViewModuleCode(modulePath) {
-    const view = `(mod.caseContextView ?? mod.default?.caseContextView ?? mod.default)`;
-    return compileModuleSelection(modulePath, `(${view}.main ?? ${view})`);
+/** Bundle one job's `run` of a `schedules.ts` (25 §6.4) with module-local helpers. */
+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 function) with its helpers. */
+export function compileExportModuleCode(modulePath, exportName) {
+    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 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, 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

package/dist/builder/compile/registry.d.ts

@@ -1,15 +1,19 @@
-import type { CaseContextViewRegistryEntry, FuncMap, FunctionRegistry } from '../../core/functions/types.js';
+import { type AnyEventHandlers } from '../../core/functions/events.js';
+import type { FuncMap, FunctionRegistry } from '../../core/functions/types.js';
+import type { FunctionSourceMap } from '../types.js';
 export type BuildRegistryOptions = {
     /** When false, skip esbuild and omit `code` (local serve overlay). Default true. */
     includeCode?: boolean;
     /** Source module used to bundle module-local helpers and constants. */
     modulePath?: string;
+    /** Receives each function's source map by name (a module's bundle only): kept out of the registry. */
+    sourceMaps?: Record<string, FunctionSourceMap>;
 };
 /**
  * Project author FuncMap → JSON-safe registry.
  * Published builds include per-function compiled `code`; overlay omits it.
  */
 export declare function toFunctionRegistry(functions: FuncMap, options?: BuildRegistryOptions): Promise<FunctionRegistry>;
-/** Compile optional caseContextView to registry entry. */
-export declare function toCaseContextViewRegistry(view: unknown, options?: BuildRegistryOptions): Promise<CaseContextViewRegistryEntry | null>;
+/** Project the company `events` export → JSON-safe registry: each handler by its event's name. */
+export declare function toEventRegistry(events: AnyEventHandlers, options?: BuildRegistryOptions): Promise<FunctionRegistry>;
 //# sourceMappingURL=registry.d.ts.map

package/dist/builder/compile/registry.js

@@ -1,5 +1,11 @@
-import { resolveCaseContextViewFn } from '../../core/functions/define/case-context.js';
-import { compileCaseContextViewModuleCode, compileFunctionCode, compileFunctionModuleCode, } from './function-code.js';
+import { isSystemEventName } from '../../core/functions/events.js';
+import { compileEventModuleCode, compileFunctionCode, compileFunctionModuleCode } from './function-code.js';
+/** The bundle's code; its map goes to `sourceMaps`. */
+function keepMap(name, compiled, sourceMaps) {
+    if (sourceMaps)
+        sourceMaps[name] = compiled.map;
+    return compiled.code;
+}
 function withCode(entry, code) {
     if (code === undefined)
         return entry;
@@ -12,37 +18,34 @@ function withCode(entry, code) {
 export async function toFunctionRegistry(functions, options = {}) {
     const includeCode = options.includeCode ?? true;
     const out = {};
-    for (const [name, def] of Object.entries(functions)) {
+    for (const [name, fn] of Object.entries(functions)) {
         const code = includeCode
             ? options.modulePath
-                ? await compileFunctionModuleCode(options.modulePath, name)
-                : await compileFunctionCode(def.main)
+                ? keepMap(name, await compileFunctionModuleCode(options.modulePath, name), options.sourceMaps)
+                : await compileFunctionCode(fn)
             : undefined;
-        let entry;
-        if (def.kind === 'custom') {
-            entry = withCode({ kind: 'custom', writes: [] }, code);
-        }
-        else if (def.kind === 'system') {
-            entry = withCode({ kind: 'system' }, code);
-        }
-        else {
-            entry = withCode({ kind: def.kind }, code);
-        }
-        out[name] = entry;
+        out[name] = withCode({}, code);
     }
     return out;
 }
-/** Compile optional caseContextView to registry entry. */
-export async function toCaseContextViewRegistry(view, options = {}) {
-    const fn = resolveCaseContextViewFn(view);
-    if (!fn)
-        return null;
-    if (!(options.includeCode ?? true)) {
-        return { kind: 'caseContextView' };
+/** Project the company `events` export → JSON-safe registry: each handler by its event's name. */
+export async function toEventRegistry(events, options = {}) {
+    const includeCode = options.includeCode ?? true;
+    const out = {};
+    for (const [name, handler] of Object.entries(events)) {
+        if (!isSystemEventName(name)) {
+            throw new Error(`events: '${name}' is not a platform event`);
+        }
+        if (typeof handler !== 'function') {
+            throw new Error(`events: handler for '${name}' must be a function`);
+        }
+        const code = includeCode
+            ? options.modulePath
+                ? keepMap(name, await compileEventModuleCode(options.modulePath, name), options.sourceMaps)
+                : await compileFunctionCode(handler)
+            : undefined;
+        out[name] = withCode({}, code);
     }
-    const code = options.modulePath
-        ? await compileCaseContextViewModuleCode(options.modulePath)
-        : await compileFunctionCode(fn);
-    return { kind: 'caseContextView', code };
+    return out;
 }
 //# sourceMappingURL=registry.js.map

package/dist/builder/errors.d.ts

@@ -0,0 +1,9 @@
+import type { FuncMap } from '../core/functions/types.js';
+/** The repository root's `errors.ts`, loaded: its `onError`, what serve runs. `null` without the file. */
+export type LoadedOnError = {
+    path: string;
+    functions: FuncMap;
+};
+/** Load and check the repository root's `errors.ts` (67 §5): it exports `onError`, a function. */
+export declare function loadOnError(repoRoot: string): Promise<LoadedOnError | null>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/builder/errors.js

@@ -0,0 +1,17 @@
+import { pathToFileURL } from 'node:url';
+import { ERRORS_MODULE, ON_ERROR_FUNCTION } from '../core/functions/errors.js';
+import { companyImportGraphHref } from './company-import-graph.js';
+import { findTsModule } from './paths.js';
+/** Load and check the repository root's `errors.ts` (67 §5): it exports `onError`, a function. */
+export async function loadOnError(repoRoot) {
+    const modulePath = findTsModule(repoRoot, ERRORS_MODULE);
+    if (!modulePath)
+        return null;
+    const mod = (await import(companyImportGraphHref(pathToFileURL(modulePath).href)));
+    const onError = mod[ON_ERROR_FUNCTION] ?? mod.default;
+    if (typeof onError !== 'function') {
+        throw new Error(`${ERRORS_MODULE}.ts: export const ${ON_ERROR_FUNCTION}: OnError = async (ctx, { error }) => { … } (67 §5)`);
+    }
+    return { path: modulePath, functions: { [ON_ERROR_FUNCTION]: onError } };
+}
+//# sourceMappingURL=errors.js.map

package/dist/builder/function-params.d.ts

@@ -0,0 +1,10 @@
+import type { ActionParameters } from '../core/page/define.js';
+export declare class FunctionParamsError extends Error {
+}
+/**
+ * The parameters of every function in `exportName` of `modulePath`, by its key. A function with no
+ * second parameter takes none (`{ type: 'object', properties: {} }`). A `define*` result (no call
+ * signature) is left out: it declares its own.
+ */
+export declare function readFunctionParameters(modulePath: string, exportName: string): Record<string, ActionParameters>;
+//# sourceMappingURL=function-params.d.ts.map

package/dist/builder/function-params.js

@@ -0,0 +1,203 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { API, SignatureKind, SymbolFlags, TypeFlags, } from 'typescript/unstable/sync';
+/**
+ * A function's parameters from its TypeScript type (38 §2.4): the builder reads the second parameter of
+ * each function in a registry export (`functions`, `actions` of `actions.ts`) as the pinned TypeScript's checker
+ * sees it, expanded, and writes what the AI sees of it. Whatever falls outside the types below is the
+ * author's mistake, said with the type to use instead.
+ */
+/** The marks `Id<T>` and the format types carry (`core/page/typed.ts`), as the checker names them. */
+const ID_MARK = /^__@ID_BRAND@/;
+const FORMAT_MARK = /^__@FORMAT_BRAND@/;
+const FORMATS = new Set(['date', 'datetime', 'time', 'phone', 'email']);
+const PARAMETER_TYPES = "string, number, boolean, literals ('a' | 'b'), Id<'table'>, IsoDate, IsoDateTime, TimeOfDay, Phone, Email, ContactSchedule, a list or an object";
+export class FunctionParamsError extends Error {
+}
+/** The repository's `tsconfig.json`: the nearest one above the module. */
+function tsconfigOf(modulePath) {
+    for (let dir = path.dirname(modulePath);; dir = path.dirname(dir)) {
+        const candidate = path.join(dir, 'tsconfig.json');
+        if (existsSync(candidate))
+            return candidate;
+        if (path.dirname(dir) === dir)
+            throw new FunctionParamsError(`${modulePath}: no tsconfig.json above it`);
+    }
+}
+/**
+ * The parameters of every function in `exportName` of `modulePath`, by its key. A function with no
+ * second parameter takes none (`{ type: 'object', properties: {} }`). A `define*` result (no call
+ * signature) is left out: it declares its own.
+ */
+export function readFunctionParameters(modulePath, exportName) {
+    const tsconfig = tsconfigOf(modulePath);
+    const api = new API({ cwd: path.dirname(tsconfig) });
+    try {
+        const snapshot = api.updateSnapshot({ openProjects: [tsconfig] });
+        const project = snapshot.getDefaultProjectForFile(modulePath) ?? snapshot.getProject(tsconfig);
+        const source = project?.program.getSourceFile(modulePath);
+        if (!project || !source)
+            throw new FunctionParamsError(`${modulePath}: not part of ${tsconfig}'s program`);
+        const { checker } = project;
+        const moduleSymbol = checker.getSymbolAtLocation(source);
+        const exported = moduleSymbol
+            ? checker.getExportsOfModule(moduleSymbol).find((s) => s.name === exportName)
+            : undefined;
+        if (!exported)
+            return {};
+        const registry = checker.getTypeOfSymbol(exported);
+        if (!registry)
+            return {};
+        const where = path.basename(modulePath);
+        const out = {};
+        for (const entry of checker.getPropertiesOfType(registry)) {
+            // JavaScript keeps this name for an object's prototype: as a key it is easily not the object's own.
+            if (entry.name === '__proto__')
+                throw new FunctionParamsError(`${path.basename(modulePath)}: ${exportName}.__proto__: pick another name`);
+            const type = checker.getTypeOfSymbol(entry);
+            if (!type)
+                continue;
+            const signatures = checker.getSignaturesOfType(type, SignatureKind.Call);
+            if (signatures.length === 0)
+                continue;
+            const label = `${where}: ${exportName}.${entry.name}`;
+            if (signatures.length > 1)
+                throw new FunctionParamsError(`${label} is overloaded: a function has one signature, (ctx, args)`);
+            const signature = signatures[0];
+            // `(...args)` hides how many it takes and which is args: the builder could not show the AI what to fill.
+            if (signature.hasRestParameter)
+                throw new FunctionParamsError(`${label} takes a rest parameter: a function takes (ctx, args), args one object`);
+            const params = signature.getParameters();
+            if (params.length > 2)
+                throw new FunctionParamsError(`${label} takes ${params.length} parameters: a function takes (ctx, args), args one object`);
+            if (params.length < 2) {
+                out[entry.name] = { type: 'object', properties: {} };
+                continue;
+            }
+            const argsType = checker.getParameterType(signature, 1);
+            if (!argsType)
+                throw new FunctionParamsError(`${label}: the type checker cannot read its args`);
+            const optional = params[1].flags & SymbolFlags.Optional ||
+                (argsType.isUnionType() && argsType.getTypes().some((t) => t.flags & TypeFlags.Undefined));
+            if (optional)
+                throw new FunctionParamsError(`${label}: args must be one object parameter, not optional`);
+            const top = objectParam(checker, argsType, `${label}(args)`);
+            out[entry.name] = {
+                type: 'object',
+                properties: top.properties,
+                ...(top.required?.length ? { required: top.required } : {}),
+            };
+        }
+        return out;
+    }
+    finally {
+        api.close();
+    }
+}
+/** A union's members without `undefined` (an optional parameter's); any other type alone. */
+function withoutUndefined(type) {
+    return (type.isUnionType() ? type.getTypes() : [type]).filter((t) => !(t.flags & TypeFlags.Undefined));
+}
+function isPlainObject(checker, type) {
+    return (type.isObjectType() &&
+        !checker.isArrayType(type) &&
+        checker.getSignaturesOfType(type, SignatureKind.Call).length === 0);
+}
+function objectParam(checker, type, where) {
+    if (!isPlainObject(checker, type) &&
+        !(type.isIntersectionType() && type.getTypes().every((t) => isPlainObject(checker, t)))) {
+        throw new FunctionParamsError(`${where}: not an object of named parameters`);
+    }
+    if (checker.getIndexInfosOfType(type).length > 0)
+        throw new FunctionParamsError(`${where} has an index signature (Record<string, …>): name each parameter`);
+    const properties = {};
+    const required = [];
+    for (const prop of checker.getPropertiesOfType(type)) {
+        const propType = checker.getTypeOfSymbol(prop);
+        if (!propType)
+            throw new FunctionParamsError(`${where}.${prop.name}: the type checker cannot read it`);
+        // A row inside an object or a list is the page's to prefill: the page refuses it where the AI would choose (35 §2).
+        const optional = (prop.flags & SymbolFlags.Optional) !== 0;
+        // One way to say optional, the one the AI reads (76 §2.14): `name?: T`. `name: T | undefined` is
+        // optional to the type checker and required here; the page's `doNow()` check and the AI would disagree.
+        if (!optional && (propType.isUnionType() ? propType.getTypes() : [propType]).some((t) => t.flags & TypeFlags.Undefined)) {
+            throw new FunctionParamsError(`${where}.${prop.name}: T | undefined: write an optional parameter as ${prop.name}?: T`);
+        }
+        properties[prop.name] = valueParam(checker, propType, `${where}.${prop.name}`);
+        if (!optional)
+            required.push(prop.name);
+    }
+    return { type: 'object', properties, ...(required.length ? { required } : {}) };
+}
+function valueParam(checker, type, where) {
+    const members = withoutUndefined(type);
+    if (members.some((t) => t.flags & TypeFlags.Null))
+        throw new FunctionParamsError(`${where}: null is not a value the AI fills: make the parameter optional (name?: T)`);
+    if (members.length === 0)
+        throw new FunctionParamsError(`${where}: no type`);
+    // A union of literals: what the AI may choose among; `boolean` is `true | false`.
+    if (members.length > 1 || members[0].isLiteralType()) {
+        if (members.every((t) => t.flags & TypeFlags.BooleanLiteral))
+            return { type: 'boolean' };
+        if (members.every((t) => t.isStringLiteralType()))
+            return { type: 'string', enum: members.map((t) => t.value) };
+        if (members.every((t) => t.isNumberLiteralType()))
+            return { type: 'number', enum: members.map((t) => t.value) };
+        if (members.length > 1)
+            throw new FunctionParamsError(`${where} mixes types: use one of ${PARAMETER_TYPES}`);
+    }
+    const only = members[0];
+    // A contact's hours (25 §3): the runtime's `ContactSchedule`, checked as the field's value is.
+    if (only.getAliasSymbol()?.name === 'ContactSchedule')
+        return { type: 'contact_schedule' };
+    if (only.flags & (TypeFlags.Any | TypeFlags.Unknown))
+        throw new FunctionParamsError(`${where}: any / unknown says nothing: use one of ${PARAMETER_TYPES}`);
+    if (only.flags & TypeFlags.String)
+        return { type: 'string' };
+    if (only.flags & TypeFlags.Number)
+        return { type: 'number' };
+    if (only.flags & TypeFlags.Boolean)
+        return { type: 'boolean' };
+    if (only.isIntersectionType()) {
+        const marked = markOf(checker, only);
+        if (marked)
+            return marked;
+        if (only.getTypes().every((t) => isPlainObject(checker, t)))
+            return objectParam(checker, only, where);
+        throw new FunctionParamsError(`${where} is not a parameter type: use one of ${PARAMETER_TYPES}`);
+    }
+    if (checker.isArrayType(only)) {
+        const item = only.isTypeReference() ? checker.getTypeArguments(only)[0] : undefined;
+        if (!item)
+            throw new FunctionParamsError(`${where}: a list of what?`);
+        return { type: 'array', items: valueParam(checker, item, `${where}[]`) };
+    }
+    if (only.isObjectType()) {
+        if (checker.getSignaturesOfType(only, SignatureKind.Call).length > 0)
+            throw new FunctionParamsError(`${where}: a function is not a value the AI fills`);
+        return objectParam(checker, only, where);
+    }
+    throw new FunctionParamsError(`${where} is not a parameter type: use one of ${PARAMETER_TYPES}`);
+}
+/** `Id<'table'>` → a row of `table`; a format type → its format. Null when the intersection carries neither mark. */
+function markOf(checker, type) {
+    if (!type.getTypes().some((t) => t.flags & TypeFlags.String))
+        return null;
+    for (const prop of checker.getPropertiesOfType(type)) {
+        const name = String(prop.escapedName);
+        const isId = ID_MARK.test(name);
+        if (!isId && !FORMAT_MARK.test(name))
+            continue;
+        const value = literalOf(checker, prop);
+        if (isId)
+            return value ? { type: 'ref', table: value } : null;
+        return value && FORMATS.has(value) ? { type: value } : null;
+    }
+    return null;
+}
+function literalOf(checker, prop) {
+    const type = checker.getTypeOfSymbol(prop);
+    const literal = type ? withoutUndefined(type).find((t) => t.isStringLiteralType()) : undefined;
+    return literal ? literal.value : null;
+}
+//# sourceMappingURL=function-params.js.map

package/dist/builder/load.d.ts

@@ -1,22 +1,82 @@
-import { type CaseContextViewFn } from '../core/functions/define/case-context.js';
-import type { FuncMap } from '../core/functions/types.js';
-import type { CompanySchema, SequenceSlots } from '../core/slot/schema.js';
-/** Sequence ids that have a slots.ts / slots/index.ts module. */
+import { type CompanyResolve, type Resolve } from '../core/party/types.js';
+import { type AnyEventHandlers, type WebhookHandler } from '../core/functions/events.js';
+import type { FuncMap, PlainFn } from '../core/functions/types.js';
+import { type OfficeHours } from '../core/office-hours/index.js';
+import { type CompanySchema, type SessionSchema } from '../core/slot/schema.js';
+/**
+ * A sequence's leftover `slots.ts` (or `slots/index.ts`): the sequence layer has no schema any more
+ * (15 §10.17 第 1 条). Its tables and fields are the company's; how a cell is filled is the page's
+ * `$extraction`.
+ */
+export declare function assertNoSlotsModule(sequenceDir: string, sequenceId: string): void;
+/** Sequence ids: the directories under `sequences/` with an `index.ts` (`defineSequence`). */
 export declare function listSequenceIds(repoRoot: string): string[];
 export declare function loadCompanySchema(schemaPath: string): Promise<CompanySchema>;
-export declare function loadSequenceSlots(slotsPath: string): Promise<SequenceSlots>;
+/**
+ * The company's session fields from `schema/session.ts` (or `schema/session/index.ts`), its
+ * `sessionSchema` export (11-remove-sequence-schema §3.1). No file: sessions have no fields.
+ */
+export declare function loadSessionSchema(repoRoot: string): Promise<SessionSchema>;
+/**
+ * Sequence office hours from `sequences/<id>/office-hours.ts`. Missing file is `null` (always open).
+ * A present file that does not export a valid `officeHours` fails compile.
+ */
+export declare function loadOfficeHours(sequenceDir: string): Promise<OfficeHours | null>;
 /**
  * Load sequence `functions` map from functions.ts or functions/index.ts.
  * Accepts named `functions` or default export FuncMap.
  */
 export declare function loadSequenceFunctions(functionsPath: string): Promise<FuncMap>;
 /**
- * Load optional `caseContextView` from view.ts / view/index.ts.
+ * Load optional sequence `events` map from events.ts / events/index.ts.
+ * Keys must be platform event names; values are plain handler functions.
+ */
+export declare function loadSequenceEvents(eventsPath: string): Promise<AnyEventHandlers>;
+/**
+ * The channels `context.page.ts` has a page function for (17b §9.1). Read from the compiled page code in
+ * a context of its own, as the platform runs it: importing the page module here would register its
+ * actions in this process, and a second compile would find them named twice. `persona` and `faq` are
+ * called when a conversation starts (24 §4), not here.
+ */
+export declare function loadPageChannels(pageCode: string, sequenceId: string): string[];
+/**
+ * What the compiled page code says of itself as it loads: its channels, and the page actions it
+ * registered (76 §2.11), read in a context of its own as `loadPageChannels` does.
+ */
+export declare function loadPageModule(pageCode: string, sequenceId: string): {
+    channels: string[];
+    actions: string[];
+};
+/** The Case Orchestrator from orchestrator.ts / orchestrator/index.ts: `orchestrator`, or the default export. */
+export declare function loadSequenceCaseOrchestrator(caseOrchestratorPath: string): Promise<PlainFn>;
+/** A sequence's `resolve`: `(ctx, conversation)`. */
+export declare function loadSequenceResolver(resolvePath: string): Promise<Resolve>;
+/** The company `resolve` (§18.2), a function of the company part (22 §5): `(ctx, conversation)`. */
+export declare function loadCompanyResolver(resolvePath: string): Promise<CompanyResolve>;
+/** The module of the company's webhooks (22 §9) at the repository root. */
+export declare const WEBHOOK_MODULE = "webhook";
+/** `received` of `webhook.ts`, a function of the company part: `(ctx, { event })`. */
+export declare function loadCompanyWebhook(webhookPath: string): Promise<WebhookHandler>;
+export declare function isPlatformName(name: string): boolean;
+/**
+ * A leftover root `channels.ts` (or `channels/index.ts`): webhook URLs are made and named on the
+ * Webhooks page now, like phone numbers, and code refers to them by name only.
+ */
+export declare function assertNoChannelsModule(repoRoot: string): void;
+/**
+ * `sequences/<id>/index.ts` default export (`defineSequence({ subject })`): the sequence's business
+ * root. Without the file or the declaration, `subject` is undefined and the compile reports it.
  */
-export declare function loadSequenceCaseContextView(viewPath: string): Promise<CaseContextViewFn>;
+export declare function loadSequenceDefinition(sequenceDir: string): Promise<{
+    subject: unknown;
+    label: unknown;
+}>;
 /**
- * Load optional sequence agendas from agendas.ts / agendas/index.ts.
- * Missing module → null (compile produces an empty agendas map).
+ * `sequences/<id>/variables.ts` (14-sequence-instance §4.4): `variables` (from `defineVariables`) and
+ * the optional `experiments`. Both undefined without the file.
  */
-export declare function loadSequenceAgendas(agendasPath: string): Promise<unknown>;
+export declare function loadSequenceVariables(sequenceDir: string): Promise<{
+    variables: unknown;
+    experiments: unknown;
+}>;
 //# sourceMappingURL=load.d.ts.map