@astrale-os/sdk 0.5.0-beta.2 → 0.5.0-beta.21

package/dist/tooling/packaging/compile.js

@@ -0,0 +1,150 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, 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 Domain's public runtime package from its dedicated package config. */
+export function compileDomainPackage(projectDir, input) {
+    const project = resolve(projectDir);
+    const configuration = 'tsconfig.package.json';
+    const configurationPath = resolve(project, configuration);
+    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);
+    const root = parsed.options.outDir && resolve(parsed.options.outDir);
+    if (root !== undefined)
+        confineOutput(project, root);
+    if (errors(parsed.errors).length > 0)
+        failDiagnostics(parsed.errors, project);
+    if (root === undefined)
+        throw new TypeError(`${configuration} must declare compilerOptions.outDir.`);
+    if (parsed.options.noEmit || !parsed.options.declaration || parsed.options.emitDeclarationOnly) {
+        throw new TypeError(`${configuration} must emit both JavaScript and declarations.`);
+    }
+    if (parsed.options.declarationDir !== undefined &&
+        resolve(parsed.options.declarationDir) !== root) {
+        throw new TypeError(`${configuration} must emit JavaScript and declarations into one outDir.`);
+    }
+    if (parsed.fileNames.length === 0)
+        throw new TypeError(`${configuration} compiles no source files.`);
+    if (root !== resolve(project, 'dist')) {
+        throw new TypeError('Domain package output must be the project dist directory.');
+    }
+    const declarationFiles = input.declarations.map((entrypoint) => declarationSource(project, root, parsed.options.rootDir, entrypoint));
+    const temporary = mkdtempSync(join(project, '.astrale-package-'));
+    const declarationConfiguration = resolve(temporary, 'tsconfig.json');
+    writeFileSync(declarationConfiguration, JSON.stringify({
+        extends: configurationPath,
+        compilerOptions: {
+            noEmit: false,
+            declaration: true,
+            declarationMap: false,
+            sourceMap: false,
+            emitDeclarationOnly: true,
+        },
+        files: declarationFiles,
+        include: [],
+    }));
+    try {
+        runCompiler(project, ['-p', resolve(project, 'tsconfig.json'), '--noEmit']);
+        runCompiler(project, ['-p', configurationPath, '--noEmit']);
+        rmSync(root, { recursive: true, force: true });
+        runCompiler(project, [
+            '-p',
+            configurationPath,
+            '--noEmit',
+            'false',
+            '--declaration',
+            'false',
+            '--declarationMap',
+            'false',
+            '--sourceMap',
+            'false',
+            '--emitDeclarationOnly',
+            'false',
+        ]);
+        runCompiler(project, ['-p', declarationConfiguration]);
+    }
+    catch (cause) {
+        rmSync(root, { recursive: true, force: true });
+        throw cause;
+    }
+    finally {
+        rmSync(temporary, { recursive: true, force: true });
+    }
+    return Object.freeze({ root });
+}
+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 declarationSource(project, output, rootDir, entrypoint) {
+    const emitted = relative(output, resolve(project, entrypoint));
+    if (emitted === '..' || emitted.startsWith(`..${sep}`) || isAbsolute(emitted)) {
+        throw new TypeError(`Published declaration entrypoint escapes package output: ${entrypoint}.`);
+    }
+    const source = emitted
+        .replace(/\.d\.mts$/u, '.mts')
+        .replace(/\.d\.cts$/u, '.cts')
+        .replace(/\.d\.ts$/u, '.ts');
+    if (source === emitted) {
+        throw new TypeError(`Published declaration entrypoint is not a declaration: ${entrypoint}.`);
+    }
+    const file = resolve(rootDir === undefined ? project : rootDir, source);
+    if (!existsSync(file)) {
+        throw new TypeError(`Published declaration source is absent: ${source}.`);
+    }
+    return file;
+}
+function confineOutput(project, output) {
+    const path = relative(project, output);
+    if (path === '' || path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)) {
+        throw new TypeError('Domain package output must be a child of the project root.');
+    }
+}
+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 { CallablePolicyContext, DirectedEdgeClass, DomainOfInput, Function, Method, NodeClass, Policy, Property, View } from '@astrale-os/kernel-dsl/v1/builder';
+import type { NodeClassDefinition, PolicyCheckObject } from '@astrale-os/kernel-dsl/v1/language';
+import type { CallablePolicyContext as FacadeCallablePolicyContext, DirectedEdgeClass as FacadeDirectedEdgeClass, DomainOfInput as FacadeDomainOfInput, Function as FacadeFunction, Method as FacadeMethod, NodeClass as FacadeNodeClass, NodeClassDefinition as FacadeNodeClassDefinition, Policy as FacadePolicy, PolicyCheckObject as FacadePolicyCheckObject, Property as FacadeProperty, View as FacadeView } 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<FacadeCallablePolicyContext, CallablePolicyContext>> | Assert<Same<FacadeDirectedEdgeClass, DirectedEdgeClass>> | Assert<Same<FacadeDomainOfInput<string, never>, DomainOfInput<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<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,118 @@
+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();
+    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) => {
+            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;
+}
+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;

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

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+/** Stable semantic owners eligible to appear in a product Domain declaration. */
+const semanticFacades = Object.freeze([
+    '@astrale-os/sdk/auth',
+    '@astrale-os/sdk/auth/exchange',
+    '@astrale-os/sdk/client',
+    '@astrale-os/sdk/client/schema',
+    '@astrale-os/sdk/client/session',
+    '@astrale-os/sdk/client/store',
+    '@astrale-os/sdk/graph',
+    '@astrale-os/sdk/graph/class',
+    '@astrale-os/sdk/graph/document',
+    '@astrale-os/sdk/graph/edge',
+    '@astrale-os/sdk/graph/node',
+    '@astrale-os/sdk/graph/path',
+    '@astrale-os/sdk/graph/properties',
+    '@astrale-os/sdk/invocation',
+    '@astrale-os/sdk/publication',
+    '@astrale-os/sdk/schema',
+    '@astrale-os/sdk/value',
+]);
+/** Broad authoring aggregates yield to an exact semantic facade exporting the same symbol. */
+const aggregateFacades = new Set(['@astrale-os/sdk/schema']);
+/**
+ * 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 function declarationFacades(anchor = import.meta.filename) {
+    const root = sdkRoot(anchor);
+    const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    if (manifest.name !== '@astrale-os/sdk') {
+        throw new TypeError(`Declaration packaging resolved a non-SDK package at ${root}.`);
+    }
+    const exports = sourceTree(anchor, root)
+        ? manifest.exports
+        : (manifest.publishConfig?.exports ?? manifest.exports);
+    if (exports === undefined)
+        throw new TypeError('SDK package declares no public exports.');
+    for (const facade of semanticFacades) {
+        const key = `./${facade.slice('@astrale-os/sdk/'.length)}`;
+        const entry = exports[key];
+        if (entry === undefined ||
+            typeof entry === 'string' ||
+            typeof entry.types !== 'string' ||
+            !platformTarget(entry.types)) {
+            throw new TypeError(`SDK semantic declaration facade is not publicly exported: ${facade}.`);
+        }
+    }
+    return semanticFacades;
+}
+/** Whether one eligible facade is semantically broader than another. */
+export function isDeclarationFacadeAncestor(ancestor, descendant) {
+    return descendant.startsWith(`${ancestor}/`) || aggregateFacades.has(ancestor);
+}
+function sdkRoot(anchor) {
+    let directory = dirname(anchor);
+    for (;;) {
+        const manifest = join(directory, 'package.json');
+        if (existsSync(manifest)) {
+            try {
+                const parsed = JSON.parse(readFileSync(manifest, 'utf8'));
+                if (parsed.name === '@astrale-os/sdk')
+                    return directory;
+            }
+            catch {
+                // A nearer malformed or unrelated manifest is not the SDK package.
+            }
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    throw new TypeError(`Cannot locate @astrale-os/sdk from ${anchor}.`);
+}
+function sourceTree(anchor, root) {
+    const path = relative(resolve(root, 'src'), resolve(anchor));
+    return path === '' || (path !== '..' && !path.startsWith(`..${sep}`));
+}
+function platformTarget(target) {
+    return /^\.\/(?:src|dist)\/platform\//u.test(target);
+}

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

@@ -0,0 +1,5 @@
+export interface DeclarationReference {
+    readonly kind: 'module' | 'path' | 'types';
+    readonly specifier: string;
+}
+export declare function declarationReferences(file: string, source: string): readonly DeclarationReference[];

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

@@ -0,0 +1,38 @@
+import ts from 'typescript';
+export function declarationReferences(file, source) {
+    const document = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+    const references = [
+        ...document.referencedFiles.map(({ fileName }) => ({
+            kind: 'path',
+            specifier: fileName,
+        })),
+        ...document.typeReferenceDirectives.map(({ fileName }) => ({
+            kind: 'types',
+            specifier: fileName,
+        })),
+    ];
+    const visit = (node) => {
+        let literal;
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier))
+            literal = node.moduleSpecifier;
+        else if (ts.isExportDeclaration(node) &&
+            node.moduleSpecifier &&
+            ts.isStringLiteral(node.moduleSpecifier))
+            literal = node.moduleSpecifier;
+        else if (ts.isImportTypeNode(node) &&
+            ts.isLiteralTypeNode(node.argument) &&
+            ts.isStringLiteral(node.argument.literal))
+            literal = node.argument.literal;
+        else if (ts.isImportEqualsDeclaration(node) &&
+            ts.isExternalModuleReference(node.moduleReference)) {
+            const expression = node.moduleReference.expression;
+            if (expression && ts.isStringLiteral(expression))
+                literal = expression;
+        }
+        if (literal)
+            references.push({ kind: 'module', specifier: literal.text });
+        ts.forEachChild(node, visit);
+    };
+    visit(document);
+    return Object.freeze(references);
+}

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

@@ -0,0 +1,11 @@
+export interface DeclarationEdit {
+    readonly start: number;
+    readonly end: number;
+    readonly replacement: string;
+}
+type ResolveDeclarationFacade = (specifier: string, symbols: readonly string[]) => string | undefined;
+/** Locate only TypeScript declaration module specifiers; returned edits preserve all other bytes. */
+export declare function declarationEdits(file: string, source: string, resolveFacade?: ResolveDeclarationFacade): readonly DeclarationEdit[];
+/** Canonical SDK facade for one Kernel module emitted into a Domain declaration. */
+export declare function declarationFacade(specifier: string, symbols: readonly string[]): string | undefined;
+export {};