@astrale-os/sdk 0.5.0-beta.13 → 0.5.0-beta.131

package/dist/tooling/packaging/compile.js

@@ -0,0 +1,311 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import ts from 'typescript';
+/** Compile one package's admitted Schema contracts with SDK-owned emit policy. */
+export function compileDomainPackage(projectDir, entrypoints = ['schema/index.ts']) {
+    const project = resolve(projectDir);
+    const root = resolve(project, 'dist');
+    rmSync(root, { recursive: true, force: true });
+    const sources = [...new Set(entrypoints)].sort().map((entrypoint) => {
+        const source = resolve(project, entrypoint);
+        if (!existsSync(source)) {
+            throw new TypeError(`Domain contract entrypoint is absent: ${entrypoint}.`);
+        }
+        return source;
+    });
+    if (sources.length === 0)
+        throw new TypeError('Domain contract declares no entrypoint.');
+    const configurationPath = resolve(project, 'tsconfig.json');
+    const loaded = ts.readConfigFile(configurationPath, ts.sys.readFile);
+    if (loaded.error !== undefined)
+        failDiagnostics([loaded.error], project);
+    const parsed = ts.parseJsonConfigFileContent(loaded.config, ts.sys, project, undefined, configurationPath);
+    if (errors(parsed.errors).length > 0)
+        failDiagnostics(parsed.errors, project);
+    if (parsed.fileNames.length === 0)
+        throw new TypeError('tsconfig.json compiles no source files.');
+    const temporary = mkdtempSync(join(project, '.astrale-package-'));
+    const packageConfiguration = resolve(temporary, 'tsconfig.json');
+    writeFileSync(packageConfiguration, JSON.stringify({
+        extends: configurationPath,
+        compilerOptions: {
+            rootDir: project,
+            outDir: root,
+            noEmit: false,
+            declaration: true,
+            declarationMap: false,
+            sourceMap: false,
+            inlineSourceMap: false,
+            inlineSources: false,
+            allowImportingTsExtensions: false,
+            emitDeclarationOnly: false,
+            noEmitOnError: true,
+            composite: false,
+            incremental: false,
+        },
+        files: sources,
+        include: [],
+        exclude: [],
+    }));
+    try {
+        const closure = admitSchemaClosure(project, packageConfiguration);
+        runCompiler(project, ['-p', configurationPath, '--noEmit']);
+        runCompiler(project, ['-p', packageConfiguration]);
+        relocateTypeClosure(root, closure.typeClosure);
+        rewriteEmittedReferences(root, closure.emittedReferences);
+        return Object.freeze({
+            root,
+            typeClosure: closure.typeClosure,
+        });
+    }
+    catch (cause) {
+        rmSync(root, { recursive: true, force: true });
+        throw cause;
+    }
+    finally {
+        rmSync(temporary, { recursive: true, force: true });
+    }
+}
+function admitSchemaClosure(project, configuration) {
+    const loaded = ts.readConfigFile(configuration, ts.sys.readFile);
+    if (loaded.error !== undefined)
+        failDiagnostics([loaded.error], project);
+    const parsed = ts.parseJsonConfigFileContent(loaded.config, ts.sys, project, undefined, configuration);
+    if (errors(parsed.errors).length > 0)
+        failDiagnostics(parsed.errors, project);
+    const program = ts.createProgram(parsed.fileNames, parsed.options);
+    const local = new Map();
+    for (const document of program.getSourceFiles()) {
+        const path = relative(project, document.fileName);
+        if (path === '..' ||
+            path.startsWith(`..${sep}`) ||
+            isAbsolute(path) ||
+            path === 'node_modules' ||
+            path.startsWith(`node_modules${sep}`)) {
+            continue;
+        }
+        local.set(resolve(document.fileName), document);
+    }
+    const paths = new Map([...local.values()].map((document) => [
+        relative(project, document.fileName).replaceAll('\\', '/'),
+        document,
+    ]));
+    const emittedReferences = [];
+    const pending = [...paths.keys()].filter((path) => path.startsWith('schema/')).sort();
+    const visited = new Set();
+    while (pending.length > 0) {
+        const owner = pending.shift();
+        if (visited.has(owner))
+            continue;
+        visited.add(owner);
+        const document = paths.get(owner);
+        const visit = (node) => {
+            if (unsupportedModuleReference(node)) {
+                throw new TypeError(`Domain contract runtime ${owner} uses unsupported non-static dependency syntax.`);
+            }
+            const specifier = referencedModule(node);
+            if (specifier !== undefined) {
+                const resolved = ts.resolveModuleName(specifier, document.fileName, parsed.options, ts.sys)
+                    .resolvedModule?.resolvedFileName;
+                const dependencyDocument = resolved === undefined ? undefined : local.get(resolve(resolved));
+                if (dependencyDocument !== undefined) {
+                    const dependency = relative(project, dependencyDocument.fileName).replaceAll('\\', '/');
+                    const typeOnly = isTypeOnlyReference(node);
+                    if (!typeOnly && !dependency.startsWith('schema/')) {
+                        throw new TypeError(`Domain Schema contract imports non-Schema source: ${dependency}.`);
+                    }
+                    if (!typeOnly && specifier.startsWith('#')) {
+                        emittedReferences.push(Object.freeze({ owner, specifier, dependency }));
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(document);
+    }
+    const typeClosure = Object.freeze([...paths.keys()]
+        .filter((path) => !path.startsWith('schema/'))
+        .sort()
+        .map((source) => Object.freeze({
+        source,
+        target: `schema/.types/${source.replace(/\.(?:tsx?|mts|cts)$/u, '.js')}`,
+    })));
+    return Object.freeze({
+        typeClosure,
+        emittedReferences: Object.freeze(emittedReferences.sort((left, right) => left.owner.localeCompare(right.owner) ||
+            left.specifier.localeCompare(right.specifier) ||
+            left.dependency.localeCompare(right.dependency))),
+    });
+}
+function referencedModule(node) {
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+        node.moduleSpecifier !== undefined &&
+        ts.isStringLiteral(node.moduleSpecifier)) {
+        return node.moduleSpecifier.text;
+    }
+    if (ts.isImportTypeNode(node) &&
+        ts.isLiteralTypeNode(node.argument) &&
+        ts.isStringLiteral(node.argument.literal)) {
+        return node.argument.literal.text;
+    }
+    if (ts.isCallExpression(node) &&
+        node.arguments.length > 0 &&
+        ts.isStringLiteral(node.arguments[0]) &&
+        (node.expression.kind === ts.SyntaxKind.ImportKeyword ||
+            (ts.isIdentifier(node.expression) && node.expression.text === 'require'))) {
+        return node.arguments[0].text;
+    }
+    return undefined;
+}
+function unsupportedModuleReference(node) {
+    if (ts.isImportEqualsDeclaration(node))
+        return true;
+    if (!ts.isCallExpression(node))
+        return false;
+    const dynamicImport = node.expression.kind === ts.SyntaxKind.ImportKeyword;
+    const requireCall = ts.isIdentifier(node.expression) && node.expression.text === 'require';
+    return ((dynamicImport || requireCall) &&
+        (node.arguments.length !== 1 || !ts.isStringLiteral(node.arguments[0])));
+}
+function isTypeOnlyReference(node) {
+    if (ts.isImportTypeNode(node))
+        return true;
+    if (ts.isExportDeclaration(node))
+        return node.isTypeOnly;
+    if (!ts.isImportDeclaration(node))
+        return false;
+    const clause = node.importClause;
+    if (clause?.isTypeOnly)
+        return true;
+    if (clause?.name !== undefined || clause?.namedBindings === undefined)
+        return false;
+    return (ts.isNamedImports(clause.namedBindings) &&
+        clause.namedBindings.elements.length > 0 &&
+        clause.namedBindings.elements.every((element) => element.isTypeOnly));
+}
+function relocateTypeClosure(root, closure) {
+    for (const { source, target } of closure) {
+        const emitted = resolve(root, source.replace(/\.(?:tsx?|mts|cts)$/u, ''));
+        const declaration = `${emitted}.d.ts`;
+        if (!existsSync(declaration)) {
+            throw new TypeError(`Domain contract type closure declaration is absent: ${source}.`);
+        }
+        const destination = resolve(root, target.replace(/\.js$/u, '.d.ts'));
+        mkdirSync(dirname(destination), { recursive: true });
+        renameSync(declaration, destination);
+        for (const extension of ['.js', '.mjs', '.cjs', '.jsx']) {
+            rmSync(`${emitted}${extension}`, { force: true });
+        }
+    }
+}
+function rewriteEmittedReferences(root, references) {
+    const grouped = new Map();
+    for (const reference of references) {
+        const current = grouped.get(reference.owner) ?? [];
+        current.push(reference);
+        grouped.set(reference.owner, current);
+    }
+    for (const [owner, ownedReferences] of grouped) {
+        const ownerTarget = owner.replace(/\.(?:tsx?|mts|cts)$/u, '.js');
+        for (const extension of ['.js', '.d.ts']) {
+            const file = resolve(root, ownerTarget.replace(/\.js$/u, extension));
+            let source = readFileSync(file, 'utf8');
+            const document = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+            const edits = [];
+            const visit = (node) => {
+                const specifier = referencedModule(node);
+                if (specifier !== undefined) {
+                    const reference = ownedReferences.find((candidate) => candidate.specifier === specifier);
+                    if (reference !== undefined) {
+                        const dependencyTarget = reference.dependency.replace(/\.(?:tsx?|mts|cts)$/u, '.js');
+                        const path = relative(dirname(ownerTarget), dependencyTarget).replaceAll('\\', '/');
+                        const value = path.startsWith('./') || path.startsWith('../') ? path : `./${path}`;
+                        const literal = moduleLiteral(node);
+                        if (literal !== undefined) {
+                            edits.push({
+                                start: literal.getStart(document) + 1,
+                                end: literal.getEnd() - 1,
+                                value,
+                            });
+                        }
+                    }
+                }
+                ts.forEachChild(node, visit);
+            };
+            visit(document);
+            for (const edit of edits.sort((left, right) => right.start - left.start)) {
+                source = `${source.slice(0, edit.start)}${edit.value}${source.slice(edit.end)}`;
+            }
+            writeFileSync(file, source);
+        }
+    }
+}
+function moduleLiteral(node) {
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+        node.moduleSpecifier !== undefined &&
+        ts.isStringLiteral(node.moduleSpecifier)) {
+        return node.moduleSpecifier;
+    }
+    if (ts.isImportTypeNode(node) &&
+        ts.isLiteralTypeNode(node.argument) &&
+        ts.isStringLiteral(node.argument.literal)) {
+        return node.argument.literal;
+    }
+    if (ts.isCallExpression(node) &&
+        node.arguments.length > 0 &&
+        ts.isStringLiteral(node.arguments[0])) {
+        return node.arguments[0];
+    }
+    return undefined;
+}
+function runCompiler(project, arguments_) {
+    const compiler = resolveCompiler();
+    const result = spawnSync(process.execPath, [compiler, ...arguments_], {
+        cwd: project,
+        encoding: 'utf8',
+        env: process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.error !== undefined) {
+        throw new TypeError('Domain package compiler could not start.', { cause: result.error });
+    }
+    if (result.status !== 0) {
+        const detail = `${result.stdout}${result.stderr}`.trim();
+        throw new TypeError(`Domain package compilation failed.${detail.length === 0 ? '' : `\n${detail}`}`);
+    }
+}
+function resolveCompiler() {
+    const sdkRequire = createRequire(import.meta.url);
+    let manifestPath;
+    try {
+        manifestPath = sdkRequire.resolve('@typescript/native-preview/package.json');
+    }
+    catch (cause) {
+        throw new TypeError('Domain packaging requires the SDK-owned @typescript/native-preview compiler.', { cause });
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const target = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.tsgo;
+    if (target === undefined) {
+        throw new TypeError('@typescript/native-preview does not declare the tsgo executable.');
+    }
+    const root = dirname(manifestPath);
+    const compiler = resolve(root, target);
+    const path = relative(root, compiler);
+    if (path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path) || !existsSync(compiler)) {
+        throw new TypeError('@typescript/native-preview declares an invalid tsgo executable.');
+    }
+    return compiler;
+}
+function errors(diagnostics) {
+    return diagnostics.filter(({ category }) => category === ts.DiagnosticCategory.Error);
+}
+function failDiagnostics(diagnostics, project) {
+    const detail = ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+        getCanonicalFileName: (file) => file,
+        getCurrentDirectory: () => project,
+        getNewLine: () => '\n',
+    });
+    throw new TypeError(`Domain package compilation failed.\n${detail}`);
+}

package/dist/tooling/packaging/declarations/admission.d.ts

@@ -0,0 +1,7 @@
+interface DeclarationReference {
+    readonly source: string;
+    readonly symbols: readonly string[];
+}
+/** Select the one semantic SDK facade exporting every referenced symbol identically. */
+export declare function admitDeclarationFacade(reference: DeclarationReference, resolutionAnchor?: string): string;
+export {};

package/dist/tooling/packaging/declarations/admission.js

@@ -0,0 +1,56 @@
+import ts from 'typescript';
+import { declarationFacades, isDeclarationFacadeAncestor } from './ownership.js';
+/** Select the one semantic SDK facade exporting every referenced symbol identically. */
+export function admitDeclarationFacade(reference, resolutionAnchor = import.meta.filename) {
+    const options = compilerOptions();
+    const source = resolveModule(reference.source, resolutionAnchor, options);
+    const candidates = declarationFacades(resolutionAnchor).map((facade) => ({
+        facade,
+        file: resolveModule(facade, resolutionAnchor, options),
+    }));
+    const program = ts.createProgram([source, ...candidates.map(({ file }) => file)], options);
+    const checker = program.getTypeChecker();
+    const originals = reference.symbols.map((symbol) => canonical(checker, exported(checker, program, source, symbol)));
+    const admitted = candidates.filter(({ file }) => reference.symbols.every((symbol, index) => {
+        const candidate = optionalExport(checker, program, file, symbol);
+        return candidate !== undefined && canonical(checker, candidate) === originals[index];
+    }));
+    if (admitted.length === 0) {
+        throw new TypeError(`No semantic SDK declaration facade identically exports ${reference.symbols.join(', ')} from ${reference.source}.`);
+    }
+    // Aggregate facades intentionally re-export their descendants. Select the
+    // one leaf owner only when every broader match is its actual path ancestor.
+    const mostSpecific = admitted.filter(({ facade }) => !admitted.some((candidate) => candidate.facade !== facade && isDeclarationFacadeAncestor(facade, candidate.facade)));
+    if (mostSpecific.length > 1) {
+        throw new TypeError(`Several equally specific SDK declaration facades export ${reference.symbols.join(', ')} from ${reference.source}: ${mostSpecific.map(({ facade }) => facade).join(', ')}.`);
+    }
+    return mostSpecific[0].facade;
+}
+function compilerOptions() {
+    return {
+        module: ts.ModuleKind.NodeNext,
+        moduleResolution: ts.ModuleResolutionKind.NodeNext,
+        target: ts.ScriptTarget.ESNext,
+        skipLibCheck: false,
+    };
+}
+function resolveModule(specifier, anchor, options) {
+    const result = ts.resolveModuleName(specifier, anchor, options, ts.sys).resolvedModule;
+    if (!result)
+        throw new TypeError(`Cannot resolve declaration module ${specifier}.`);
+    return result.resolvedFileName;
+}
+function exported(checker, program, file, name) {
+    const symbol = optionalExport(checker, program, file, name);
+    if (!symbol)
+        throw new TypeError(`${file} does not export ${name}.`);
+    return symbol;
+}
+function optionalExport(checker, program, file, name) {
+    const source = program.getSourceFile(file);
+    const module = source && checker.getSymbolAtLocation(source);
+    return module && checker.getExportsOfModule(module).find((candidate) => candidate.name === name);
+}
+function canonical(checker, symbol) {
+    return symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+}

package/dist/tooling/packaging/declarations/admission.typecheck.d.ts

@@ -0,0 +1,7 @@
+import type { AuthoredMethodProjection, CallablePolicyBuilder, CallablePolicyContext, ClassIdentityProjection, ClassOwnerProjection, ClassReferenceProjection, DirectedEdgeClass, Function, Method, NodeClass, Policy, Property, ResolvedDomainOfInput, View } from '@astrale-os/kernel-dsl/v1/builder';
+import type { ClassKind, DirectedEdgeContract, EdgeClassPolicies, NodeClassDefinition, PolicyCheckObject, PropertyFacet, UndirectedEdgeContract } from '@astrale-os/kernel-dsl/v1/language';
+import type { AuthoredMethodProjection as FacadeAuthoredMethodProjection, CallablePolicyBuilder as FacadeCallablePolicyBuilder, CallablePolicyContext as FacadeCallablePolicyContext, ClassIdentityProjection as FacadeClassIdentityProjection, ClassOwnerProjection as FacadeClassOwnerProjection, ClassKind as FacadeClassKind, ClassReferenceProjection as FacadeClassReferenceProjection, DirectedEdgeContract as FacadeDirectedEdgeContract, DirectedEdgeClass as FacadeDirectedEdgeClass, EdgeClassPolicies as FacadeEdgeClassPolicies, Function as FacadeFunction, Method as FacadeMethod, NodeClass as FacadeNodeClass, NodeClassDefinition as FacadeNodeClassDefinition, Policy as FacadePolicy, PolicyCheckObject as FacadePolicyCheckObject, Property as FacadeProperty, PropertyFacet as FacadePropertyFacet, ResolvedDomainOfInput as FacadeResolvedDomainOfInput, View as FacadeView, UndirectedEdgeContract as FacadeUndirectedEdgeContract } from '../../../platform/schema/index.js';
+type Same<Left, Right> = [Left] extends [Right] ? ([Right] extends [Left] ? true : false) : false;
+type Assert<Value extends true> = Value;
+export type DeclarationFacadeChecks = Assert<Same<FacadeAuthoredMethodProjection, AuthoredMethodProjection>> | Assert<Same<FacadeCallablePolicyBuilder, CallablePolicyBuilder>> | Assert<Same<FacadeCallablePolicyContext, CallablePolicyContext>> | Assert<Same<FacadeClassIdentityProjection, ClassIdentityProjection>> | Assert<Same<FacadeClassOwnerProjection, ClassOwnerProjection>> | Assert<Same<FacadeClassKind, ClassKind>> | Assert<Same<FacadeClassReferenceProjection, ClassReferenceProjection>> | Assert<Same<FacadeDirectedEdgeContract, DirectedEdgeContract>> | Assert<Same<FacadeDirectedEdgeClass, DirectedEdgeClass>> | Assert<Same<FacadeEdgeClassPolicies, EdgeClassPolicies>> | Assert<Same<FacadeResolvedDomainOfInput<string, never>, ResolvedDomainOfInput<string, never>>> | Assert<Same<FacadeFunction, Function>> | Assert<Same<FacadeMethod, Method>> | Assert<Same<FacadeNodeClass, NodeClass>> | Assert<Same<FacadeNodeClassDefinition, NodeClassDefinition>> | Assert<Same<FacadePolicy, Policy>> | Assert<Same<FacadePolicyCheckObject, PolicyCheckObject>> | Assert<Same<FacadeProperty, Property>> | Assert<Same<FacadePropertyFacet, PropertyFacet>> | Assert<Same<FacadeUndirectedEdgeContract, UndirectedEdgeContract>> | Assert<Same<FacadeView, View>>;
+export {};

package/dist/tooling/packaging/declarations/admission.typecheck.js

@@ -0,0 +1 @@
+export {};

package/dist/tooling/packaging/declarations/imports.d.ts

@@ -0,0 +1,16 @@
+export type PackageImports = Readonly<Record<string, unknown>>;
+interface ImportMapping {
+    readonly key: string;
+    readonly prefix: string;
+    readonly suffix: string;
+    readonly target: string;
+    readonly pattern: boolean;
+}
+export interface AdmittedPackageImports {
+    readonly mappings: readonly ImportMapping[];
+}
+/** Fail closed on unsupported package-import constructs, including unused ones. */
+export declare function admitPackageImports(imports: PackageImports): AdmittedPackageImports;
+/** Resolve one internal declaration specifier using the admitted package-import grammar. */
+export declare function resolvePackageImport(specifier: string, imports: AdmittedPackageImports): string;
+export {};

package/dist/tooling/packaging/declarations/imports.js

@@ -0,0 +1,50 @@
+/** Fail closed on unsupported package-import constructs, including unused ones. */
+export function admitPackageImports(imports) {
+    return Object.freeze({
+        mappings: Object.freeze(Object.entries(imports).map(([key, target]) => admitMapping(key, target))),
+    });
+}
+/** Resolve one internal declaration specifier using the admitted package-import grammar. */
+export function resolvePackageImport(specifier, imports) {
+    const exact = imports.mappings.find(({ key, pattern }) => !pattern && key === specifier);
+    if (exact !== undefined)
+        return exact.target;
+    const matched = imports.mappings
+        .filter(({ pattern, prefix, suffix }) => pattern && specifier.startsWith(prefix) && specifier.endsWith(suffix))
+        .sort(compareSpecificity)[0];
+    if (matched === undefined) {
+        throw new TypeError(`No published declaration import owns ${specifier}.`);
+    }
+    const value = specifier.slice(matched.prefix.length, specifier.length - matched.suffix.length);
+    return matched.target.replace('*', value);
+}
+function admitMapping(key, target) {
+    if (!key.startsWith('#') || key === '#' || key.startsWith('#/')) {
+        throw new TypeError(`Published package import has an invalid internal specifier: ${key}.`);
+    }
+    if (typeof target !== 'string') {
+        throw new TypeError(`Published package import ${key} must have one string target.`);
+    }
+    if (!target.startsWith('./dist/') || target.split('/').includes('..')) {
+        throw new TypeError(`Published package import ${key} must target one file under the published dist directory.`);
+    }
+    const stars = [...key.matchAll(/\*/gu)].length;
+    const targetStars = [...target.matchAll(/\*/gu)].length;
+    if (stars > 1 || targetStars !== stars) {
+        throw new TypeError(`Published package import ${key} must use zero or one matching pattern.`);
+    }
+    const star = key.indexOf('*');
+    return Object.freeze({
+        key,
+        prefix: star < 0 ? key : key.slice(0, star),
+        suffix: star < 0 ? '' : key.slice(star + 1),
+        target,
+        pattern: star >= 0,
+    });
+}
+/** Node selects the longest base before considering the trailing pattern. */
+function compareSpecificity(left, right) {
+    return (right.prefix.length - left.prefix.length ||
+        right.suffix.length - left.suffix.length ||
+        left.key.localeCompare(right.key));
+}

package/dist/tooling/packaging/declarations/index.d.ts

@@ -0,0 +1,7 @@
+import type { DeclarationNormalizationInput, DeclarationNormalizationResult } from './normalize.js';
+import type { DeclarationPackageInput, DeclarationPackageResult } from './verify.js';
+export type { DeclarationNormalizationInput, DeclarationNormalizationResult } from './normalize.js';
+export type { DeclarationPackageInput, DeclarationPackageResult } from './verify.js';
+/** Keep the compiler API outside an imported tooling facade until package construction runs. */
+export declare function normalizeDeclarations(input: DeclarationNormalizationInput): Promise<DeclarationNormalizationResult>;
+export declare function verifyDeclarationPackage(input: DeclarationPackageInput): Promise<DeclarationPackageResult>;

package/dist/tooling/packaging/declarations/index.js

@@ -0,0 +1,9 @@
+/** Keep the compiler API outside an imported tooling facade until package construction runs. */
+export async function normalizeDeclarations(input) {
+    const owner = await import('./normalize.js');
+    return owner.normalizeDeclarations(input);
+}
+export async function verifyDeclarationPackage(input) {
+    const owner = await import('./verify.js');
+    return owner.verifyDeclarationPackage(input);
+}

package/dist/tooling/packaging/declarations/normalize.d.ts

@@ -0,0 +1,13 @@
+import { type PackageImports } from './imports.js';
+export interface DeclarationNormalizationInput {
+    readonly root: string;
+    readonly entrypoints?: readonly string[];
+    readonly imports?: PackageImports;
+}
+export interface DeclarationNormalizationResult {
+    readonly files: readonly string[];
+    readonly replacements: number;
+}
+/** Normalize emitted declarations without re-emitting or re-typechecking their source program. */
+export declare function normalizeDeclarations(input: DeclarationNormalizationInput): Promise<DeclarationNormalizationResult>;
+export declare function reachableDeclarations(root: string, requested?: readonly string[], imports?: PackageImports): string[];

package/dist/tooling/packaging/declarations/normalize.js

@@ -0,0 +1,135 @@
+import { existsSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { admitPackageImports, resolvePackageImport } from './imports.js';
+import { declarationReferences } from './references.js';
+import { declarationEdits, declarationFacade } from './transform.js';
+/** Normalize emitted declarations without re-emitting or re-typechecking their source program. */
+export async function normalizeDeclarations(input) {
+    const root = resolve(input.root);
+    const output = new Map();
+    const admittedFacades = new Map();
+    const admittedImports = admitPackageImports(input.imports ?? {});
+    let replacements = 0;
+    const files = reachableDeclarations(root, input.entrypoints, input.imports);
+    const unreachable = allDeclarations(root).filter((file) => !files.includes(file));
+    for (const file of files) {
+        const source = readFileSync(file, 'utf8');
+        const fileEdits = declarationEdits(file, source, (specifier, symbols) => {
+            if (specifier.startsWith('.')) {
+                return runtimeSpecifier(file, resolveLocal(file, specifier));
+            }
+            if (specifier.startsWith('#')) {
+                const target = resolvePackageImport(specifier, admittedImports);
+                return runtimeSpecifier(file, resolveImportTarget(root, target));
+            }
+            const key = JSON.stringify([specifier, symbols]);
+            if (admittedFacades.has(key))
+                return admittedFacades.get(key);
+            const facade = declarationFacade(specifier, symbols);
+            admittedFacades.set(key, facade);
+            return facade;
+        });
+        const normalized = stripSourceMapReference(apply(source, fileEdits));
+        if (normalized.includes('@astrale-os/kernel-')) {
+            throw new TypeError(`Domain declaration retains a Kernel package specifier: ${file}.`);
+        }
+        output.set(file, normalized);
+        replacements += fileEdits.length;
+    }
+    for (const [file, source] of output)
+        writeFileSync(file, source);
+    for (const file of files)
+        rmSync(`${file}.map`, { force: true });
+    for (const file of unreachable) {
+        rmSync(file);
+        rmSync(`${file}.map`, { force: true });
+    }
+    return Object.freeze({
+        files: Object.freeze(files),
+        replacements,
+    });
+}
+function allDeclarations(root) {
+    const files = [];
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory())
+                visit(path);
+            else if (/\.d\.(?:ts|mts|cts)$/u.test(path))
+                files.push(path);
+        }
+    };
+    visit(root);
+    return files.sort();
+}
+export function reachableDeclarations(root, requested, imports = {}) {
+    const admittedImports = admitPackageImports(imports);
+    const pending = (requested ?? ['index.d.ts']).map((entry) => confined(root, resolve(root, entry)));
+    const seen = new Set();
+    while (pending.length > 0) {
+        const file = pending.pop();
+        if (seen.has(file))
+            continue;
+        if (!existsSync(file))
+            throw new TypeError(`Declaration entrypoint does not exist: ${file}.`);
+        seen.add(file);
+        const source = readFileSync(file, 'utf8');
+        for (const reference of declarationReferences(file, source)) {
+            if (reference.kind === 'path' || reference.specifier.startsWith('.')) {
+                pending.push(confined(root, resolveLocal(file, reference.specifier)));
+            }
+            else if (reference.specifier.startsWith('#')) {
+                const target = resolvePackageImport(reference.specifier, admittedImports);
+                pending.push(confined(root, resolveImportTarget(root, target)));
+            }
+        }
+    }
+    return [...seen].sort();
+}
+function resolveImportTarget(root, target) {
+    return resolveLocal(join(root, 'entry.d.ts'), `./${target.slice('./dist/'.length)}`);
+}
+function resolveLocal(containing, specifier) {
+    const base = resolve(dirname(containing), specifier);
+    const candidates = [
+        base.endsWith('.mjs') ? base.replace(/\.mjs$/u, '.d.mts') : '',
+        base.endsWith('.cjs') ? base.replace(/\.cjs$/u, '.d.cts') : '',
+        base.endsWith('.js') ? base.replace(/\.js$/u, '.d.ts') : '',
+        /\.d\.(?:ts|mts|cts)$/u.test(base) ? base : '',
+        `${base}.d.ts`,
+        join(base, 'index.d.ts'),
+    ];
+    const file = candidates.find((candidate) => candidate && existsSync(candidate));
+    if (!file)
+        throw new TypeError(`Cannot resolve declaration reference ${specifier} from ${containing}.`);
+    return file;
+}
+/** Point a local declaration reference at the emitted ESM module that owns it. */
+function runtimeSpecifier(containing, declaration) {
+    const runtime = declaration
+        .replace(/\.d\.mts$/u, '.mjs')
+        .replace(/\.d\.cts$/u, '.cjs')
+        .replace(/\.d\.ts$/u, '.js');
+    const path = relative(dirname(containing), runtime).replaceAll('\\', '/');
+    return path.startsWith('./') || path.startsWith('../') ? path : `./${path}`;
+}
+function confined(root, file) {
+    const path = relative(realpathSync(root), realpathSync(file));
+    if (path === '..' ||
+        path.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) ||
+        isAbsolute(path)) {
+        throw new TypeError(`Declaration reference escapes package root: ${file}.`);
+    }
+    return file;
+}
+function apply(source, edits) {
+    let result = source;
+    for (const edit of [...edits].sort((left, right) => right.start - left.start)) {
+        result = `${result.slice(0, edit.start)}${edit.replacement}${result.slice(edit.end)}`;
+    }
+    return result;
+}
+function stripSourceMapReference(source) {
+    return source.replace(/^\/\/# sourceMappingURL=.*(?:\r?\n|$)/gmu, '');
+}

package/dist/tooling/packaging/declarations/ownership.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Return the explicit SDK facade registry after proving every owner is public.
+ *
+ * This small list records semantic ownership only. Kernel symbols remain
+ * discovered and identity-proven by the TypeScript checker at packaging time.
+ */
+export declare function declarationFacades(anchor?: string): readonly string[];
+/** Whether one eligible facade is semantically broader than another. */
+export declare function isDeclarationFacadeAncestor(ancestor: string, descendant: string): boolean;