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

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 {};

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

@@ -0,0 +1,76 @@
+import ts from 'typescript';
+import { admitDeclarationFacade } from './admission.js';
+/** Locate only TypeScript declaration module specifiers; returned edits preserve all other bytes. */
+export function declarationEdits(file, source, resolveFacade = declarationFacade) {
+    const document = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const edits = [];
+    visit(document);
+    return Object.freeze(edits);
+    function visit(node) {
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+            append(node.moduleSpecifier);
+        }
+        else if (ts.isExportDeclaration(node) &&
+            node.moduleSpecifier !== undefined &&
+            ts.isStringLiteral(node.moduleSpecifier)) {
+            append(node.moduleSpecifier);
+        }
+        else if (ts.isImportTypeNode(node) &&
+            ts.isLiteralTypeNode(node.argument) &&
+            ts.isStringLiteral(node.argument.literal)) {
+            append(node.argument.literal);
+        }
+        ts.forEachChild(node, visit);
+    }
+    function append(literal) {
+        const symbols = literal.text.startsWith(KERNEL_PREFIX) ? importedSymbols(literal) : [];
+        const replacement = resolveFacade(literal.text, symbols);
+        if (replacement === undefined || replacement === literal.text)
+            return;
+        const start = literal.getStart(document) + 1;
+        const end = literal.getEnd() - 1;
+        edits.push(Object.freeze({
+            start,
+            end,
+            replacement,
+        }));
+    }
+}
+function importedSymbols(literal) {
+    const owner = literal.parent;
+    if (ts.isImportDeclaration(owner)) {
+        const clause = owner.importClause;
+        if (!clause ||
+            clause.name ||
+            !clause.namedBindings ||
+            ts.isNamespaceImport(clause.namedBindings)) {
+            throw new TypeError(`Kernel declaration imports must use explicit named symbols: ${literal.text}.`);
+        }
+        return clause.namedBindings.elements.map((element) => (element.propertyName ?? element.name).text);
+    }
+    if (ts.isExportDeclaration(owner)) {
+        if (!owner.exportClause || ts.isNamespaceExport(owner.exportClause)) {
+            throw new TypeError(`Kernel declaration exports must use explicit named symbols: ${literal.text}.`);
+        }
+        return owner.exportClause.elements.map((element) => (element.propertyName ?? element.name).text);
+    }
+    if (ts.isLiteralTypeNode(owner) && ts.isImportTypeNode(owner.parent)) {
+        const qualifier = owner.parent.qualifier;
+        if (!qualifier) {
+            throw new TypeError(`Kernel declaration import types must select an explicit symbol: ${literal.text}.`);
+        }
+        let selected = qualifier;
+        while (ts.isQualifiedName(selected))
+            selected = selected.left;
+        return [selected.text];
+    }
+    throw new TypeError(`Unsupported Kernel declaration reference: ${literal.text}.`);
+}
+const KERNEL_PREFIX = '@astrale-os/kernel-';
+/** Canonical SDK facade for one Kernel module emitted into a Domain declaration. */
+export function declarationFacade(specifier, symbols) {
+    if (specifier.startsWith(KERNEL_PREFIX)) {
+        return admitDeclarationFacade({ source: specifier, symbols });
+    }
+    return undefined;
+}

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

@@ -0,0 +1,11 @@
+export interface DeclarationPackageInput {
+    readonly root: string;
+    readonly packageRoot: string;
+    readonly entrypoints?: readonly string[];
+}
+export interface DeclarationPackageResult {
+    readonly files: readonly string[];
+    readonly packages: readonly string[];
+}
+/** Verify the complete public declaration graph against one published package manifest. */
+export declare function verifyDeclarationPackage(input: DeclarationPackageInput): Promise<DeclarationPackageResult>;

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

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { admitSelfPackage, isSelfPackageReference, packageName } from '../self.js';
+import { reachableDeclarations } from './normalize.js';
+import { declarationReferences } from './references.js';
+/** Verify the complete public declaration graph against one published package manifest. */
+export async function verifyDeclarationPackage(input) {
+    const manifest = JSON.parse(readFileSync(resolve(input.packageRoot, 'package.json'), 'utf8'));
+    const files = reachableDeclarations(resolve(input.root), input.entrypoints, manifest.publishConfig?.imports ?? manifest.imports);
+    const self = manifest.name === undefined
+        ? undefined
+        : admitSelfPackage(manifest.name, exportSubpaths(manifest.exports));
+    const packages = new Set();
+    for (const file of files) {
+        for (const reference of declarationReferences(file, readFileSync(file, 'utf8'))) {
+            const specifier = reference.specifier;
+            if (reference.kind !== 'path' &&
+                !specifier.startsWith('.') &&
+                !specifier.startsWith('#') &&
+                !specifier.startsWith('node:') &&
+                !isSelfPackageReference(specifier, self)) {
+                packages.add(packageName(specifier));
+            }
+        }
+    }
+    const declared = new Set([
+        ...Object.keys(manifest.dependencies ?? {}),
+        ...Object.keys(manifest.optionalDependencies ?? {}),
+        ...Object.keys(manifest.peerDependencies ?? {}),
+    ]);
+    const missing = [...packages].filter((name) => !declared.has(name)).sort();
+    if (missing.length > 0) {
+        throw new TypeError(`Published declarations reference undeclared packages: ${missing.join(', ')}.`);
+    }
+    return Object.freeze({
+        files: Object.freeze(files),
+        packages: Object.freeze([...packages].sort()),
+    });
+}
+function exportSubpaths(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return [];
+    return Object.keys(value).filter((subpath) => subpath !== './package.json');
+}

package/dist/tooling/packaging/exports.d.ts

@@ -0,0 +1,11 @@
+interface PackageManifest {
+    readonly main?: string;
+    readonly exports?: unknown;
+    readonly publishConfig?: {
+        readonly main?: string;
+        readonly exports?: unknown;
+    };
+}
+/** Verify that every JavaScript target exposed by the published manifest was emitted. */
+export declare function verifyPublishedJavaScript(projectDir: string, manifest: PackageManifest): void;
+export {};

package/dist/tooling/packaging/exports.js

@@ -0,0 +1,61 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+/** Verify that every JavaScript target exposed by the published manifest was emitted. */
+export function verifyPublishedJavaScript(projectDir, manifest) {
+    const project = resolve(projectDir);
+    const targets = new Set();
+    collectJavaScriptTarget(manifest.publishConfig?.main ?? manifest.main, targets, false);
+    collectExports(manifest.publishConfig?.exports ?? manifest.exports, targets);
+    if (targets.size === 0) {
+        throw new TypeError('Published Domain contract declares no JavaScript export.');
+    }
+    for (const target of [...targets].sort()) {
+        if (!target.startsWith('./dist/') || !/\.(?:c|m)?js$/u.test(target)) {
+            throw new TypeError(`Published contract export must target emitted JavaScript under ./dist: ${target}.`);
+        }
+        const file = resolve(project, target);
+        const path = relative(project, file);
+        if (path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)) {
+            throw new TypeError(`Published JavaScript export target escapes the package: ${target}.`);
+        }
+        if (!existsSync(file)) {
+            throw new TypeError(`Published JavaScript export target is absent: ${target}.`);
+        }
+    }
+}
+function collectJavaScriptTarget(value, targets, types) {
+    if (typeof value === 'string') {
+        if (!types)
+            targets.add(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const nested of value)
+            collectJavaScriptTarget(nested, targets, types);
+        return;
+    }
+    if (value === null || typeof value !== 'object')
+        return;
+    for (const [condition, nested] of Object.entries(value)) {
+        collectJavaScriptTarget(nested, targets, types || condition === 'types');
+    }
+}
+function collectExports(value, targets) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        collectJavaScriptTarget(value, targets, false);
+        return;
+    }
+    const entries = Object.entries(value);
+    const subpaths = entries.filter(([key]) => key.startsWith('.'));
+    if (subpaths.length === 0) {
+        collectJavaScriptTarget(value, targets, false);
+        return;
+    }
+    if (subpaths.length !== entries.length) {
+        throw new TypeError('Published exports cannot mix package subpaths and runtime conditions.');
+    }
+    for (const [subpath, target] of subpaths) {
+        if (subpath !== './package.json')
+            collectJavaScriptTarget(target, targets, false);
+    }
+}

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

@@ -0,0 +1,2 @@
+export type { PackageDomainInput, PackageDomainResult } from './packaging.js';
+export { packageDomain } from './packaging.js';

package/dist/tooling/packaging/index.js

@@ -0,0 +1 @@
+export { packageDomain } from './packaging.js';

package/dist/tooling/packaging/javascript.d.ts

@@ -0,0 +1,3 @@
+import { type SelfPackage } from './self.js';
+/** Verify emitted Schema JavaScript and return its complete external package set. */
+export declare function verifyContractJavaScript(root: string, self?: SelfPackage): readonly string[];

package/dist/tooling/packaging/javascript.js

@@ -0,0 +1,71 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import ts from 'typescript';
+import { isSelfPackageReference, packageName } from './self.js';
+/** Verify emitted Schema JavaScript and return its complete external package set. */
+export function verifyContractJavaScript(root, self) {
+    const packages = new Set();
+    for (const file of javascriptFiles(root)) {
+        const source = readFileSync(file, 'utf8');
+        const document = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+        visit(document);
+        function visit(node) {
+            const specifier = moduleSpecifier(node);
+            if (specifier?.startsWith('@astrale-os/kernel-')) {
+                throw new TypeError(`Domain contract imports a Kernel package directly: ${specifier} in ${file}.`);
+            }
+            if (specifier?.startsWith('#')) {
+                throw new TypeError(`Domain contract retains a private package import: ${specifier} in ${file}.`);
+            }
+            if (unsupportedModuleReference(node)) {
+                throw new TypeError(`Domain contract retains unsupported non-static dependency syntax in ${file}.`);
+            }
+            if (specifier !== undefined &&
+                !specifier.startsWith('.') &&
+                !specifier.startsWith('#') &&
+                !specifier.startsWith('node:') &&
+                !isSelfPackageReference(specifier, self)) {
+                packages.add(packageName(specifier));
+            }
+            ts.forEachChild(node, visit);
+        }
+    }
+    return Object.freeze([...packages].sort());
+}
+function unsupportedModuleReference(node) {
+    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 javascriptFiles(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 (/\.(?:js|mjs|cjs)$/u.test(entry.name))
+                files.push(path);
+        }
+    };
+    visit(root);
+    return files.sort();
+}
+function moduleSpecifier(node) {
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+        node.moduleSpecifier &&
+        ts.isStringLiteral(node.moduleSpecifier)) {
+        return node.moduleSpecifier.text;
+    }
+    if (!ts.isCallExpression(node) || node.arguments.length === 0)
+        return undefined;
+    const dynamicImport = node.expression.kind === ts.SyntaxKind.ImportKeyword;
+    const requireCall = ts.isIdentifier(node.expression) && node.expression.text === 'require';
+    const argument = node.arguments[0];
+    return (dynamicImport || requireCall) && argument && ts.isStringLiteral(argument)
+        ? argument.text
+        : undefined;
+}

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

@@ -0,0 +1,10 @@
+export interface PackageDomainInput {
+    readonly projectDir: string;
+}
+export interface PackageDomainResult {
+    readonly declarations: number;
+    readonly replacements: number;
+    readonly packages: readonly string[];
+}
+/** Compile, normalize, and verify every public Schema contract in one Domain package. */
+export declare function packageDomain(input: PackageDomainInput): Promise<PackageDomainResult>;

package/dist/tooling/packaging/packaging.js

@@ -0,0 +1,195 @@
+import { readFile } from 'node:fs/promises';
+import { rm } from 'node:fs/promises';
+import { posix, resolve } from 'node:path';
+import { admitDomainPackage } from './admission.js';
+import { compileDomainPackage } from './compile.js';
+import { normalizeDeclarations, verifyDeclarationPackage } from './declarations/index.js';
+import { verifyPublishedJavaScript } from './exports.js';
+import { verifyContractJavaScript } from './javascript.js';
+import { admitSelfPackage } from './self.js';
+/** Compile, normalize, and verify every public Schema contract in one Domain package. */
+export async function packageDomain(input) {
+    const projectDir = resolve(input.projectDir);
+    const root = resolve(projectDir, 'dist');
+    await rm(root, { recursive: true, force: true });
+    try {
+        const manifest = JSON.parse(await readFile(resolve(projectDir, 'package.json'), 'utf8'));
+        admitDomainPackage(projectDir, manifest);
+        const contracts = admitContractManifest(manifest);
+        const self = admitSelfPackage(manifest.name, contracts.map(({ subpath }) => subpath));
+        const { typeClosure } = compileDomainPackage(projectDir, contracts.map(({ source }) => source));
+        const entrypoints = contracts.map(({ declaration }) => declaration);
+        const declarationEntrypoints = entrypoints;
+        verifyPublishedJavaScript(projectDir, manifest);
+        const javascriptPackages = verifyContractJavaScript(root, self);
+        const normalized = await normalizeDeclarations({
+            root,
+            imports: declarationImports(manifest, typeClosure),
+            entrypoints: declarationEntrypoints,
+        });
+        const verified = await verifyDeclarationPackage({
+            root,
+            packageRoot: projectDir,
+            entrypoints: declarationEntrypoints,
+        });
+        const packages = Object.freeze([...new Set([...javascriptPackages, ...verified.packages])].sort());
+        verifyDependencies(manifest, packages);
+        return Object.freeze({
+            declarations: verified.files.length,
+            replacements: normalized.replacements,
+            packages,
+        });
+    }
+    catch (cause) {
+        await rm(root, { recursive: true, force: true });
+        throw cause;
+    }
+}
+function declarationImports(manifest, closure) {
+    const imports = { ...manifest.publishConfig?.imports };
+    for (const { source, target } of closure) {
+        const specifier = packageImportForSource(manifest.imports ?? {}, source);
+        if (specifier === undefined) {
+            throw new TypeError(`Domain contract type closure has no package import: ${source}.`);
+        }
+        imports[specifier] = `./dist/${target}`;
+    }
+    return Object.keys(imports).length === 0 ? undefined : imports;
+}
+function packageImportForSource(imports, source) {
+    for (const [specifier, target] of Object.entries(imports).sort(([left], [right]) => left.localeCompare(right))) {
+        if (typeof target !== 'string')
+            continue;
+        const normalized = target.replace(/^\.\//u, '');
+        const wildcard = normalized.indexOf('*');
+        if (wildcard === -1) {
+            if (normalized === source)
+                return specifier;
+            continue;
+        }
+        const prefix = normalized.slice(0, wildcard);
+        const suffix = normalized.slice(wildcard + 1);
+        if (!source.startsWith(prefix) || !source.endsWith(suffix))
+            continue;
+        const value = source.slice(prefix.length, source.length - suffix.length);
+        return specifier.replace('*', value);
+    }
+    return undefined;
+}
+function admitContractManifest(manifest) {
+    if (manifest.files?.length !== 1 || manifest.files[0] !== 'dist') {
+        throw new TypeError('Domain contract package files must be exactly ["dist"].');
+    }
+    const published = manifest.publishConfig;
+    const sourceExports = admitExports(manifest.exports, 'source');
+    const publishedExports = admitExports(published?.exports, 'published');
+    const sourceSubpaths = [...sourceExports.keys()].sort();
+    const publishedSubpaths = [...publishedExports.keys()].sort();
+    if (sourceSubpaths.join('\n') !== publishedSubpaths.join('\n')) {
+        throw new TypeError('Domain contract source and published export subpaths must match.');
+    }
+    const contracts = sourceSubpaths.map((subpath) => {
+        const source = sourceExports.get(subpath);
+        const output = publishedExports.get(subpath);
+        const expected = publishedTargets(source.types);
+        if (output.types !== expected.types || output.import !== expected.import) {
+            throw new TypeError(`Published Domain contract export ${subpath} is invalid.`);
+        }
+        return Object.freeze({
+            subpath,
+            source: source.types.slice(2),
+            declaration: expected.types.slice('./dist/'.length),
+        });
+    });
+    if (new Set(contracts.map(({ source }) => source)).size !== contracts.length) {
+        throw new TypeError('Domain contract source entrypoints must be unique.');
+    }
+    const root = contracts.find(({ subpath }) => subpath === '.');
+    if (root === undefined) {
+        if (manifest.main !== undefined ||
+            manifest.types !== undefined ||
+            published?.main !== undefined ||
+            published?.types !== undefined) {
+            throw new TypeError('A subpath-only Domain contract package must not declare main or types.');
+        }
+    }
+    else {
+        if (root.source !== 'schema/index.ts') {
+            throw new TypeError('Domain contract source entrypoint must be ./schema/index.ts.');
+        }
+        const source = `./${root.source}`;
+        const output = publishedTargets(source);
+        if (manifest.main !== source || manifest.types !== source) {
+            throw new TypeError(`Domain contract root entrypoint must be ${source}.`);
+        }
+        if (published?.main !== output.import || published.types !== output.types) {
+            throw new TypeError(`Published Domain contract root entrypoint must be ${output.import}.`);
+        }
+    }
+    return Object.freeze(contracts);
+}
+function admitExports(exports, label) {
+    if (exports === null || typeof exports !== 'object' || Array.isArray(exports)) {
+        throw new TypeError(`Domain contract ${label} exports must be an object.`);
+    }
+    const record = exports;
+    if (record['./package.json'] !== './package.json') {
+        throw new TypeError(`Domain contract ${label} package metadata export is invalid.`);
+    }
+    const contracts = new Map();
+    for (const [subpath, value] of Object.entries(record).sort(([left], [right]) => left.localeCompare(right))) {
+        if (subpath === './package.json')
+            continue;
+        if (subpath !== '.' &&
+            (!/^\.\/[a-z0-9][a-z0-9._/-]*$/u.test(subpath) ||
+                `./${posix.normalize(subpath.slice(2))}` !== subpath)) {
+            throw new TypeError(`Domain contract ${label} export subpath is invalid: ${subpath}.`);
+        }
+        const contract = value;
+        if (contract === undefined ||
+            contract === null ||
+            typeof contract !== 'object' ||
+            Array.isArray(contract) ||
+            Object.keys(contract).sort().join(',') !== 'import,types' ||
+            typeof contract.types !== 'string' ||
+            typeof contract.import !== 'string' ||
+            (label === 'source' && contract.types !== contract.import)) {
+            throw new TypeError(`Domain contract ${label} export ${subpath} is invalid.`);
+        }
+        if (label === 'source' &&
+            (!contract.types.startsWith('./schema/') ||
+                !contract.types.endsWith('.ts') ||
+                contract.types.endsWith('.d.ts') ||
+                `./${posix.normalize(contract.types.slice(2))}` !== contract.types)) {
+            throw new TypeError(`Domain contract source export ${subpath} must target TypeScript under ./schema.`);
+        }
+        contracts.set(subpath, Object.freeze({ types: contract.types, import: contract.import }));
+    }
+    if (contracts.size === 0) {
+        throw new TypeError(`Domain contract ${label} exports declare no Schema contract.`);
+    }
+    return contracts;
+}
+function publishedTargets(source) {
+    const stem = source.slice(2, -'.ts'.length);
+    return Object.freeze({
+        types: `./dist/${stem}.d.ts`,
+        import: `./dist/${stem}.js`,
+    });
+}
+function verifyDependencies(manifest, packages) {
+    const declared = new Set([
+        ...Object.keys(manifest.dependencies ?? {}),
+        ...Object.keys(manifest.optionalDependencies ?? {}),
+        ...Object.keys(manifest.peerDependencies ?? {}),
+    ]);
+    const used = new Set(packages);
+    const missing = packages.filter((name) => !declared.has(name));
+    if (missing.length > 0) {
+        throw new TypeError(`Published Domain contract references undeclared packages: ${missing.join(', ')}.`);
+    }
+    const unused = [...declared].filter((name) => !used.has(name)).sort();
+    if (unused.length > 0) {
+        throw new TypeError(`Domain contract declares unused production packages: ${unused.join(', ')}.`);
+    }
+}

package/dist/tooling/packaging/self.d.ts

@@ -0,0 +1,9 @@
+export interface SelfPackage {
+    readonly name: string;
+    readonly specifiers: ReadonlySet<string>;
+}
+/** Admit one package identity and the exact public specifiers it may use internally. */
+export declare function admitSelfPackage(name: unknown, subpaths: readonly string[]): SelfPackage;
+/** Return whether an external specifier is an admitted self-reference, rejecting impostors. */
+export declare function isSelfPackageReference(specifier: string, self?: SelfPackage): boolean;
+export declare function packageName(specifier: string): string;