@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/builder/codegen/generate.js

@@ -1,56 +1,145 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { subjectTableIssues } from '../../core/slot/company-metadata.js';
+import { compileSlotSchema } from '../../core/slot/compile-schema.js';
 import { withCompanyImportGraph } from '../company-import-graph.js';
-import { listSequenceIds, loadCompanySchema, loadSequenceSlots } from '../load.js';
-import { mergeEffectiveSchema } from '../merge.js';
-import { findTsModule, resolveTsModule } from '../paths.js';
-import { emitCaseContextSource, emitCaseContextStub, emitSlotsSource, emitSlotsStub } from './emit.js';
+import { assertNoSlotsModule, listSequenceIds, loadCompanySchema, loadSequenceDefinition, loadSessionSchema, } from '../load.js';
+import { findTsModule, requirePagePath, resolveTsModule } from '../paths.js';
+import { fatalSlotSchemaIssues } from '../slot-schema-validation.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) {
+    return {
+        tablesOutPath: path.join(repoRoot, '__gen', 'tables.type.ts'),
+        indexOutPath: path.join(repoRoot, '__gen', 'index.ts'),
+    };
+}
 function sequenceSlotsGenPath(repoRoot, sequenceId) {
     return path.join(repoRoot, 'sequences', sequenceId, '__gen', 'slots.type.ts');
 }
-function sequenceCaseContextGenPath(repoRoot, sequenceId) {
+/** Generated for `slots.ts`, which was removed (15 §10.17 第 1 条); type:gen deletes a leftover one. */
+function legacySlotsConfigGenPath(repoRoot, sequenceId) {
+    return path.join(repoRoot, 'sequences', sequenceId, '__gen', 'slots-config.type.ts');
+}
+/** `__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. */
+function legacyLoadGenPath(repoRoot, sequenceId) {
+    return path.join(repoRoot, 'sequences', sequenceId, '__gen', 'load.type.ts');
+}
+function sequenceGenIndexPath(repoRoot, sequenceId) {
+    return path.join(repoRoot, 'sequences', sequenceId, '__gen', 'index.ts');
+}
+/** The sequence's `functions` module as `__gen/index.ts` imports it, or `null` when it has none. */
+function functionsImportFor(repoRoot, sequenceId) {
+    return moduleImportFor(repoRoot, sequenceId, 'functions');
+}
+/** 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);
+    if (!found)
+        return null;
+    return path.relative(path.join(sequenceDir, '__gen'), found).split(path.sep).join('/');
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function throwGenerationFailures(failures) {
+    const errors = failures.map(({ sequenceId, error }) => new Error(`Sequence ${sequenceId}: ${errorMessage(error)}`, { cause: error }));
+    throw new AggregateError(errors, errors.map((error) => error.message).join('\n'));
+}
 export async function generateSequence(repoRoot, sequenceId, options = {}) {
-    return withCompanyImportGraph(repoRoot, () => generateSequenceInGraph(repoRoot, sequenceId, options));
+    return withCompanyImportGraph(repoRoot, async () => generateSequenceInGraph(repoRoot, sequenceId, options, await loadCompanySchemas(repoRoot)));
 }
-async function generateSequenceInGraph(repoRoot, sequenceId, options) {
+/** The company's tables (`schema/index.ts`) and session fields (`schema/session.ts`). */
+async function loadCompanySchemas(repoRoot) {
     const schemaPath = resolveTsModule(repoRoot, 'schema', `No company schema found. Expected schema.ts or schema/index.ts under ${repoRoot}`);
-    const slotsPath = resolveTsModule(path.join(repoRoot, 'sequences', sequenceId), 'slots', `No sequence slots found. Expected sequences/${sequenceId}/slots.ts or sequences/${sequenceId}/slots/index.ts`);
-    const company = await loadCompanySchema(schemaPath);
-    const slots = await loadSequenceSlots(slotsPath);
-    const effective = mergeEffectiveSchema(company, slots);
+    return { company: await loadCompanySchema(schemaPath), session: await loadSessionSchema(repoRoot) };
+}
+/** The root `__gen/` texts: the company's tables with no subject, as the company part compiles them. */
+function companyGenSources({ 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 { tablesSource: emitCompanyTablesSource(schema), indexSource: emitCompanyGenIndexSource() };
+}
+function writeCompanyGen(repoRoot, schemas) {
+    const { tablesOutPath, indexOutPath } = companyGenPaths(repoRoot);
+    const { tablesSource, indexSource } = companyGenSources(schemas);
+    mkdirSync(path.dirname(tablesOutPath), { recursive: true });
+    writeFileSync(tablesOutPath, tablesSource, 'utf8');
+    writeFileSync(indexOutPath, indexSource, 'utf8');
+}
+async function generateSequenceInGraph(repoRoot, sequenceId, options, { company, session }) {
     const sequenceDir = path.join(repoRoot, 'sequences', sequenceId);
-    const hasCaseContextView = findTsModule(sequenceDir, 'view') !== undefined;
-    const source = emitSlotsSource(effective);
-    const caseContextSource = emitCaseContextSource({ hasCaseContextView });
+    assertNoSlotsModule(sequenceDir, sequenceId);
+    if (!options.dryRun)
+        ensureStub(repoRoot, sequenceId);
+    // The table types are the company's (root `__gen`); the sequence only names its subject (28 §2.2).
+    const { subject } = await loadSequenceDefinition(sequenceDir);
+    const subjectIssues = subjectTableIssues(company, subject);
+    if (subjectIssues.length > 0)
+        throw new Error(subjectIssues.map((issue) => issue.message).join('; '));
+    // The company schema is checked either way; a real run also writes the root `__gen` the sequence's types import.
+    const { tablesSource } = companyGenSources({ company, session });
+    if (!options.dryRun)
+        writeCompanyGen(repoRoot, { company, session });
+    // Every sequence has a page script (15 §10.2): the generated page types read it.
+    requirePagePath(sequenceDir, sequenceId);
+    const source = emitSlotsSource(subject);
+    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/` 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 generateAll(repoRoot, options = {}) {
     return withCompanyImportGraph(repoRoot, async () => {
         const ids = options.sequenceIds ?? listSequenceIds(repoRoot);
-        if (ids.length === 0) {
-            throw new Error(`No sequences with slots found under ${path.join(repoRoot, 'sequences')} (expected slots.ts or slots/index.ts)`);
-        }
+        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)
+            writeCompanyGen(repoRoot, schemas);
+        // Keeps going after failures so valid sequences still regenerate and the caller receives every
+        // sequence error in one AggregateError.
+        const failures = [];
         const results = [];
         for (const sequenceId of ids) {
-            results.push(await generateSequence(repoRoot, sequenceId, options));
+            try {
+                results.push(await generateSequenceInGraph(repoRoot, sequenceId, options, schemas));
+            }
+            catch (error) {
+                failures.push({ sequenceId, error });
+            }
         }
+        if (failures.length > 0)
+            throwGenerationFailures(failures);
         return results;
     });
 }
@@ -67,30 +156,54 @@ function assertFileMatches(outPath, next, repoRoot) {
     }
 }
 export async function checkSequence(repoRoot, sequenceId) {
-    const { outPath, caseContextOutPath, source, caseContextSource } = 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. */
+export async function checkCompany(repoRoot) {
+    const { tablesSource, indexSource } = await withCompanyImportGraph(repoRoot, async () => companyGenSources(await loadCompanySchemas(repoRoot)));
+    const { tablesOutPath, indexOutPath } = companyGenPaths(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 with slots found under ${path.join(repoRoot, 'sequences')} (expected slots.ts or slots/index.ts)`);
-    }
+    await checkCompany(repoRoot);
+    const failures = [];
     for (const sequenceId of ids) {
-        await checkSequence(repoRoot, sequenceId);
+        try {
+            await checkSequence(repoRoot, sequenceId);
+        }
+        catch (error) {
+            failures.push({ sequenceId, error });
+        }
     }
+    if (failures.length > 0)
+        throwGenerationFailures(failures);
 }
 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'), moduleImportFor(repoRoot, sequenceId, 'actions')), 'utf8');
     }
 }
+/**
+ * Writes the root `__gen/` files that are missing (a fresh checkout has none: `__gen/` is gitignored),
+ * so `resolve.ts` and `webhook.ts` can import it; existing ones are left untouched.
+ */
+export function ensureCompanyStub(repoRoot) {
+    const { tablesOutPath, indexOutPath } = companyGenPaths(repoRoot);
+    mkdirSync(path.dirname(tablesOutPath), { recursive: true });
+    if (!existsSync(tablesOutPath))
+        writeFileSync(tablesOutPath, emitCompanyTablesStub(), 'utf8');
+    if (!existsSync(indexOutPath))
+        writeFileSync(indexOutPath, emitCompanyGenIndexSource(), 'utf8');
+}
 //# sourceMappingURL=generate.js.map

package/dist/builder/company-import-graph.d.ts

@@ -1,3 +1,5 @@
+/** The repository the current company import graph loads, or null outside one. */
+export declare function companyRepoRoot(): string | null;
 /** Stamp a company-repo entry URL, or return it unchanged outside a graph. */
 export declare function companyImportGraphHref(fileHref: string): string;
 /**

package/dist/builder/company-import-graph.js

@@ -3,6 +3,7 @@ import { realpathSync } from 'node:fs';
 import { registerHooks } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { COMMONJS_ISSUE, companyImportError, resolvedIssue, specifierIssue } from './company-imports.js';
 const COMPANY_GRAPH_GEN_QUERY = 'spgen';
 const COMPANY_GRAPH_ROOT_QUERY = 'sproot';
 const graph = new AsyncLocalStorage();
@@ -34,16 +35,23 @@ function inNodeModules(filePath, url) {
         filePath.includes(`${path.sep}node_modules${path.sep}`));
 }
 function stampCompanyResolve(specifier, context, nextResolve) {
-    const result = nextResolve(specifier, context);
-    if (!result.url.startsWith('file:'))
-        return result;
-    const resolved = new URL(result.url);
-    if (resolved.searchParams.has(COMPANY_GRAPH_GEN_QUERY))
-        return result;
     const parent = context.parentURL ? new URL(context.parentURL) : null;
     const graphGeneration = parent?.searchParams.get(COMPANY_GRAPH_GEN_QUERY);
     const repoRoot = parent?.searchParams.get(COMPANY_GRAPH_ROOT_QUERY);
-    if (!graphGeneration || !repoRoot)
+    // A company file's import is checked before it loads: what company code may import (company-imports.ts).
+    const importer = parent && graphGeneration && repoRoot ? filePathFromUrl(parent.href) : null;
+    if (importer && repoRoot) {
+        const issue = specifierIssue(specifier);
+        if (issue)
+            throw companyImportError(importer, repoRoot, issue);
+    }
+    const result = nextResolve(specifier, context);
+    if (!result.url.startsWith('file:')) {
+        if (importer && repoRoot)
+            throw companyImportError(importer, repoRoot, `'${specifier}' is not a file of the repository`);
+        return result;
+    }
+    if (!importer || !graphGeneration || !repoRoot)
         return result;
     let resolvedFile;
     try {
@@ -52,6 +60,12 @@ function stampCompanyResolve(specifier, context, nextResolve) {
     catch {
         return result;
     }
+    const issue = resolvedIssue(specifier, resolvedFile, repoRoot);
+    if (issue)
+        throw companyImportError(importer, repoRoot, issue);
+    const resolved = new URL(result.url);
+    if (resolved.searchParams.has(COMPANY_GRAPH_GEN_QUERY))
+        return result;
     if (inNodeModules(resolvedFile, result.url))
         return result;
     if (!underRoot(resolvedFile, repoRoot))
@@ -60,11 +74,29 @@ function stampCompanyResolve(specifier, context, nextResolve) {
     resolved.searchParams.set(COMPANY_GRAPH_ROOT_QUERY, repoRoot);
     return { ...result, url: resolved.href };
 }
+/**
+ * A company file Node loads as CommonJS (a `.ts` under a `"type": "commonjs"` package.json; `.cts` and
+ * `.cjs` are refused when imported) is refused: its `require` calls would go unchecked.
+ */
+const refuseCommonJs = (url, context, nextLoad) => {
+    const result = nextLoad(url, context);
+    if (result.format !== 'commonjs' && result.format !== 'commonjs-typescript')
+        return result;
+    const loaded = new URL(url);
+    const repoRoot = loaded.searchParams.get(COMPANY_GRAPH_ROOT_QUERY);
+    if (!repoRoot || !loaded.searchParams.has(COMPANY_GRAPH_GEN_QUERY))
+        return result;
+    throw companyImportError(filePathFromUrl(url), repoRoot, COMMONJS_ISSUE);
+};
 function ensureHookRegistered() {
     if (registered)
         return;
     registered = true;
-    registerHooks({ resolve: stampCompanyResolve });
+    registerHooks({ resolve: stampCompanyResolve, load: refuseCommonJs });
+}
+/** The repository the current company import graph loads, or null outside one. */
+export function companyRepoRoot() {
+    return graph.getStore()?.repoRoot ?? null;
 }
 /** Stamp a company-repo entry URL, or return it unchanged outside a graph. */
 export function companyImportGraphHref(fileHref) {

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

@@ -0,0 +1,29 @@
+/**
+ * What company code may import (09-runtime-compat §6): the company API, `@superpanel-sdk/runtime`, and
+ * the repository's own files. No other package, no Node module, no other runtime entry and no file of
+ * the runtime's own. The compile checks every import of a company file against this twice: in Node,
+ * as it loads the repo (`company-import-graph.ts`), and in esbuild, as it bundles a code string
+ * (`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;
+/** Whether `file` is a runtime package's company API: `dist/index.js`, its types, or `src/index.ts`. */
+export declare function isCompanyApiFile(file: string): boolean;
+/**
+ * Why company code may not import `specifier`, known before resolving it; null when only the resolved
+ * file can tell (a path, a `#…` import, or the company API).
+ */
+export declare function specifierIssue(specifier: string): string | null;
+/** Why `specifier`, resolved to `file`, may not be imported by a file of the company repo at `repoRoot`; null when it may. */
+export declare function resolvedIssue(specifier: string, file: string, repoRoot: string): string | null;
+export declare const COMMONJS_ISSUE = "is CommonJS (.cts, .cjs, or \"type\": \"commonjs\"): company code is ES modules";
+/** The message a refused import fails the compile with: which file, what it imported, and why not. */
+export declare function companyImportError(importer: string, repoRoot: string, issue: string): Error;
+//# sourceMappingURL=company-imports.d.ts.map

package/dist/builder/company-imports.js

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { isBuiltin } from 'node:module';
+import path from 'node:path';
+/**
+ * What company code may import (09-runtime-compat §6): the company API, `@superpanel-sdk/runtime`, and
+ * the repository's own files. No other package, no Node module, no other runtime entry and no file of
+ * the runtime's own. The compile checks every import of a company file against this twice: in Node,
+ * as it loads the repo (`company-import-graph.ts`), and in esbuild, as it bundles a code string
+ * (`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(['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 {
+        return realpathSync(filePath);
+    }
+    catch {
+        return path.resolve(filePath);
+    }
+}
+/** The directory of the nearest `package.json` above `file`, else the file's own directory. */
+export function packageRootOf(file) {
+    for (let dir = path.dirname(path.resolve(file));; dir = path.dirname(dir)) {
+        if (existsSync(path.join(dir, 'package.json')))
+            return dir;
+        if (path.dirname(dir) === dir)
+            return path.dirname(path.resolve(file));
+    }
+}
+/** The directory and name of the package that holds `file`: the nearest `package.json` above it. */
+function owningPackage(file) {
+    let dir = path.dirname(file);
+    for (;;) {
+        let name = packageNames.get(dir);
+        if (name === undefined) {
+            try {
+                const pkg = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
+                name = typeof pkg.name === 'string' ? pkg.name : null;
+            }
+            catch {
+                name = null;
+            }
+            packageNames.set(dir, name);
+        }
+        if (name !== null)
+            return { dir, name };
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Whether `file` is a runtime package's company API: `dist/index.js`, its types, or `src/index.ts`. */
+export function isCompanyApiFile(file) {
+    const resolved = realPath(file);
+    const owner = owningPackage(resolved);
+    return owner?.name === RUNTIME_PACKAGE && COMPANY_API_FILES.has(path.relative(owner.dir, resolved));
+}
+/**
+ * A package name or a Node module, as opposed to a path (`./x`, `/x`), a URL (`file:`, `node:`) or a
+ * `#…` import the repo's package.json maps (which the resolved file decides, like a path).
+ */
+function isBareSpecifier(specifier) {
+    return (!specifier.startsWith('.') &&
+        !specifier.startsWith('/') &&
+        !specifier.startsWith('#') &&
+        !/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(specifier));
+}
+/**
+ * Why company code may not import `specifier`, known before resolving it; null when only the resolved
+ * file can tell (a path, a `#…` import, or the company API).
+ */
+export function specifierIssue(specifier) {
+    if (isBuiltin(specifier)) {
+        return `'${specifier}' is a Node module: company code is bundled into self-contained code that cannot import one, and the page's sandbox has no Node`;
+    }
+    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`;
+}
+/** Why `specifier`, resolved to `file`, may not be imported by a file of the company repo at `repoRoot`; null when it may. */
+export function resolvedIssue(specifier, file, repoRoot) {
+    if (specifier === RUNTIME_PACKAGE) {
+        return isCompanyApiFile(file) ? null : `'${specifier}' resolves to ${file}, not the runtime's company API`;
+    }
+    const resolved = realPath(file);
+    const relative = path.relative(realPath(repoRoot), resolved);
+    const inRepo = relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+    if (!inRepo || relative.split(path.sep).includes('node_modules')) {
+        return `'${specifier}' resolves to ${inRepo ? relative : resolved}, outside the repository's own files`;
+    }
+    if (COMMONJS_EXTENSIONS.has(path.extname(resolved)))
+        return `'${specifier}' ${COMMONJS_ISSUE}`;
+    return null;
+}
+/**
+ * Company code is ES modules. A CommonJS file's `require` calls reach Node's resolve hook without the
+ * import graph's stamp, so nothing would check what it loads: the compile refuses the file instead.
+ */
+const COMMONJS_EXTENSIONS = new Set(['.cjs', '.cts']);
+export const COMMONJS_ISSUE = 'is CommonJS (.cts, .cjs, or "type": "commonjs"): company code is ES modules';
+/** The message a refused import fails the compile with: which file, what it imported, and why not. */
+export function companyImportError(importer, repoRoot, issue) {
+    const where = path.relative(realPath(repoRoot), realPath(importer)) || importer;
+    return new Error(`${where}: ${issue} (AGENTS.md, "Imports")`);
+}
+//# sourceMappingURL=company-imports.js.map

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

@@ -1,18 +1,13 @@
-import type { FuncMap } from '../../core/functions/types.js';
-import type { CompanySchema } from '../../core/slot/schema.js';
-import type { RuntimePackageSource, SequenceBuild } from '../types.js';
-/** SequenceBuild / SequenceConfigBuild cache key. Bump when compiled `code` shape changes. */
+import type { CompiledSlotSchema } from '../../core/slot/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;
-/** Deep-clone company schema with derived computeFn normalized to string names. */
-export declare function snapshotCompanySchema(company: CompanySchema, functions?: FuncMap): CompanySchema;
 export declare function sequenceBuildPath(repoRoot: string, sequenceId: string): string;
 export type CompileSequenceOptions = {
     dryRun?: boolean;
     /** When false, skip esbuild and omit registry `code` (local serve overlay). Default true. */
     includeCode?: boolean;
-    /** Persist on SequenceBuild.sha. Defaults to `local`. */
-    sha?: string;
     /** Dependency source captured before deployment rewrites package.json. */
     runtimeSource?: RuntimePackageSource;
 };
@@ -20,10 +15,68 @@ export type CompileSequenceResult = {
     sequenceId: string;
     outPath: string;
     build: SequenceBuild;
+    /** The company schema the build runs against (28 §2): what the company part of the build carries. */
+    schema: CompiledSlotSchema;
+    /** Where the build's code came from in the company's files, by `functionKey`: kept apart from the build. */
+    sourceMaps: SourceMaps;
     wrote: boolean;
 };
 export declare function compileSequence(repoRoot: string, sequenceId: string, options?: CompileSequenceOptions): Promise<CompileSequenceResult>;
+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), the root
+ * `errors.ts` as `onError` (67 §5), and the
+ * company schema with no subject. An error in it fails the
+ * whole compile.
+ */
+export declare function compileCompanyPart(repoRoot: string, options?: {
+    includeCode?: boolean;
+    runtimeSource?: RuntimePackageSource;
+}): Promise<CompanyPart>;
+export declare const COMPILE_CONCURRENCY = 4;
+export declare const COMPILE_SEQUENCE_TIMEOUT_MS: number;
+export type CompileRepoEvent = {
+    type: 'log';
+    sequence?: string;
+    text: string;
+} | {
+    type: 'sequence-started';
+    sequence: string;
+} | {
+    type: 'sequence-finished';
+    sequence: string;
+    ok: boolean;
+    error?: string;
+};
+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;
+};
+export type CompileRepoOptions = {
+    sequences: string[];
+    runtimeSource?: RuntimePackageSource;
+    concurrency?: number;
+    sequenceTimeoutMs?: number;
+    onEvent?: (event: CompileRepoEvent) => void;
+};
+/**
+ * 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<{
+    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