@ankhorage/devtools 1.17.2 → 1.18.1

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/devtools
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v1.17.2](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v1.18.1](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects
 
@@ -452,6 +452,8 @@ Run and synchronize the shared development toolchain through the Ankh CLI.
 Repository synchronization is available through
 `ankh devtools sync` and `ankh devtools status`, with focused `agents`, `skills`, `eslint`,
 `prettier`, `knip`, `package`, `workflows`, and `vscode` sync/status subcommands.
+Owner packages can opt into deterministic structural metadata with
+`ankh devtools structure build` and verify committed evidence with `ankh devtools structure check`.
 
 Sync commands accept an optional target directory and `--dry-run`. Aggregate sync is
 deterministic and idempotent: canonical managed files and skill trees are created or updated,
@@ -477,6 +479,7 @@ bunx @ankhorage/devtools ankhorage-changeset
 bunx @ankhorage/devtools ankhorage-eslint
 bunx @ankhorage/devtools ankhorage-knip
 bunx @ankhorage/devtools ankhorage-prettier
+bunx @ankhorage/devtools ankhorage-structure
 ```
 
 ## Generated documentation

package/dist/cli/bin/structure.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/bin/structure.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { runStructureGenerationCommandAsync } from '../../features/structure-descriptor-generation/adapters/inbound/runStructureGenerationCommandAsync.js';
+const [operation, ...argv] = process.argv.slice(2);
+if (operation !== 'build' && operation !== 'check') {
+    console.error('Usage: ankhorage-structure <build|check> [directory]');
+    process.exitCode = 1;
+}
+else {
+    const result = await runStructureGenerationCommandAsync(operation, argv, {
+        cwd: process.cwd(),
+        writeStdout: (text) => process.stdout.write(text),
+        writeStderr: (text) => process.stderr.write(text),
+    });
+    process.exitCode = result.exitCode;
+}

package/dist/cli/commands/structure/build.d.ts

@@ -0,0 +1,5 @@
+import type { DevtoolsProviderCommandContext } from '../../runProviderCommand.js';
+/*** Adapt the public structure build command to deterministic owner artifact generation. */
+export declare function build(argv: readonly string[], context: DevtoolsProviderCommandContext): Promise<{
+    readonly exitCode: number;
+}>;

package/dist/cli/commands/structure/build.js

@@ -0,0 +1,5 @@
+import { runStructureGenerationCommandAsync } from '../../../features/structure-descriptor-generation/adapters/inbound/runStructureGenerationCommandAsync.js';
+/*** Adapt the public structure build command to deterministic owner artifact generation. */
+export async function build(argv, context) {
+    return runStructureGenerationCommandAsync('build', argv, context);
+}

package/dist/cli/commands/structure/check.d.ts

@@ -0,0 +1,5 @@
+import type { DevtoolsProviderCommandContext } from '../../runProviderCommand.js';
+/*** Adapt the public structure check command to deterministic owner artifact verification. */
+export declare function check(argv: readonly string[], context: DevtoolsProviderCommandContext): Promise<{
+    readonly exitCode: number;
+}>;

package/dist/cli/commands/structure/check.js

@@ -0,0 +1,5 @@
+import { runStructureGenerationCommandAsync } from '../../../features/structure-descriptor-generation/adapters/inbound/runStructureGenerationCommandAsync.js';
+/*** Adapt the public structure check command to deterministic owner artifact verification. */
+export async function check(argv, context) {
+    return runStructureGenerationCommandAsync('check', argv, context);
+}

package/dist/cli/commands.d.ts

@@ -1,7 +1,7 @@
 export type DevtoolsToolName = 'changeset' | 'format' | 'knip' | 'lint';
 type DevtoolsManagedScope = 'agents' | 'all' | 'eslint' | 'knip' | 'package' | 'prettier' | 'skills' | 'vscode' | 'workflows';
 type DevtoolsManagedOperation = 'status' | 'sync';
-type DevtoolsCapability = 'devtools.apm.sync' | 'devtools.apm.validate' | 'devtools.changeset' | 'devtools.format' | 'devtools.knip' | 'devtools.lint' | 'devtools.status' | 'devtools.sync' | 'devtools.agents.status' | 'devtools.agents.sync' | 'devtools.eslint.status' | 'devtools.eslint.sync' | 'devtools.knip.status' | 'devtools.knip.sync' | 'devtools.package.status' | 'devtools.package.sync' | 'devtools.prettier.status' | 'devtools.prettier.sync' | 'devtools.skills.status' | 'devtools.skills.sync' | 'devtools.vscode.status' | 'devtools.vscode.sync' | 'devtools.workflows.status' | 'devtools.workflows.sync';
+type DevtoolsCapability = 'devtools.apm.sync' | 'devtools.apm.validate' | 'devtools.changeset' | 'devtools.format' | 'devtools.knip' | 'devtools.lint' | 'devtools.status' | 'devtools.sync' | 'devtools.agents.status' | 'devtools.agents.sync' | 'devtools.eslint.status' | 'devtools.eslint.sync' | 'devtools.knip.status' | 'devtools.knip.sync' | 'devtools.package.status' | 'devtools.package.sync' | 'devtools.prettier.status' | 'devtools.prettier.sync' | 'devtools.skills.status' | 'devtools.skills.sync' | 'devtools.structure.build' | 'devtools.structure.check' | 'devtools.vscode.status' | 'devtools.vscode.sync' | 'devtools.workflows.status' | 'devtools.workflows.sync';
 interface DevtoolsCommandBase {
     readonly path: readonly [string, ...string[]];
     readonly capability: DevtoolsCapability;
@@ -22,7 +22,11 @@ interface DevtoolsApmReleaseCommandDefinition extends DevtoolsCommandBase {
     readonly kind: 'apm-release';
     readonly operation: 'sync' | 'validate';
 }
-export type DevtoolsCommandDefinition = DevtoolsExternalCommandDefinition | DevtoolsRepositoryCommandDefinition | DevtoolsApmReleaseCommandDefinition;
+interface DevtoolsStructureCommandDefinition extends DevtoolsCommandBase {
+    readonly kind: 'structure';
+    readonly operation: 'build' | 'check';
+}
+export type DevtoolsCommandDefinition = DevtoolsExternalCommandDefinition | DevtoolsRepositoryCommandDefinition | DevtoolsApmReleaseCommandDefinition | DevtoolsStructureCommandDefinition;
 export declare function getDevtoolsCommands(): readonly DevtoolsCommandDefinition[];
 export declare function findDevtoolsCommandByPath(path: readonly string[]): DevtoolsCommandDefinition | null;
 export declare function getDevtoolsToolCommand(toolName: DevtoolsToolName): DevtoolsExternalCommandDefinition;

package/dist/cli/commands.js

@@ -13,6 +13,20 @@ const DEVTOOLS_COMMANDS = [
         capability: 'devtools.apm.validate',
         summary: 'Validate the exact packed APM release artifact.',
     },
+    {
+        kind: 'structure',
+        operation: 'build',
+        path: ['structure', 'build'],
+        capability: 'devtools.structure.build',
+        summary: 'Generate deterministic structural descriptor evidence.',
+    },
+    {
+        kind: 'structure',
+        operation: 'check',
+        path: ['structure', 'check'],
+        capability: 'devtools.structure.check',
+        summary: 'Verify structural descriptor evidence is current.',
+    },
     externalCommand('changeset', 'devtools.changeset', 'Run the shared Changesets toolchain.', '@changesets/cli', 'changeset'),
     externalCommand('lint', 'devtools.lint', 'Run the shared ESLint toolchain.', 'eslint', 'eslint'),
     externalCommand('format', 'devtools.format', 'Run the shared Prettier toolchain.', 'prettier', 'prettier'),

package/dist/cli/index.d.ts

@@ -2,10 +2,10 @@ declare const provider: {
     id: string;
     category: string;
     version: string;
-    capabilities: ("devtools.apm.sync" | "devtools.apm.validate" | "devtools.changeset" | "devtools.format" | "devtools.knip" | "devtools.lint" | "devtools.status" | "devtools.sync" | "devtools.agents.status" | "devtools.agents.sync" | "devtools.eslint.status" | "devtools.eslint.sync" | "devtools.knip.status" | "devtools.knip.sync" | "devtools.package.status" | "devtools.package.sync" | "devtools.prettier.status" | "devtools.prettier.sync" | "devtools.skills.status" | "devtools.skills.sync" | "devtools.vscode.status" | "devtools.vscode.sync" | "devtools.workflows.status" | "devtools.workflows.sync")[];
+    capabilities: ("devtools.apm.sync" | "devtools.apm.validate" | "devtools.changeset" | "devtools.format" | "devtools.knip" | "devtools.lint" | "devtools.status" | "devtools.sync" | "devtools.agents.status" | "devtools.agents.sync" | "devtools.eslint.status" | "devtools.eslint.sync" | "devtools.knip.status" | "devtools.knip.sync" | "devtools.package.status" | "devtools.package.sync" | "devtools.prettier.status" | "devtools.prettier.sync" | "devtools.skills.status" | "devtools.skills.sync" | "devtools.structure.build" | "devtools.structure.check" | "devtools.vscode.status" | "devtools.vscode.sync" | "devtools.workflows.status" | "devtools.workflows.sync")[];
     commands: {
         path: string[];
-        capability: "devtools.apm.sync" | "devtools.apm.validate" | "devtools.changeset" | "devtools.format" | "devtools.knip" | "devtools.lint" | "devtools.status" | "devtools.sync" | "devtools.agents.status" | "devtools.agents.sync" | "devtools.eslint.status" | "devtools.eslint.sync" | "devtools.knip.status" | "devtools.knip.sync" | "devtools.package.status" | "devtools.package.sync" | "devtools.prettier.status" | "devtools.prettier.sync" | "devtools.skills.status" | "devtools.skills.sync" | "devtools.vscode.status" | "devtools.vscode.sync" | "devtools.workflows.status" | "devtools.workflows.sync";
+        capability: "devtools.apm.sync" | "devtools.apm.validate" | "devtools.changeset" | "devtools.format" | "devtools.knip" | "devtools.lint" | "devtools.status" | "devtools.sync" | "devtools.agents.status" | "devtools.agents.sync" | "devtools.eslint.status" | "devtools.eslint.sync" | "devtools.knip.status" | "devtools.knip.sync" | "devtools.package.status" | "devtools.package.sync" | "devtools.prettier.status" | "devtools.prettier.sync" | "devtools.skills.status" | "devtools.skills.sync" | "devtools.structure.build" | "devtools.structure.check" | "devtools.vscode.status" | "devtools.vscode.sync" | "devtools.workflows.status" | "devtools.workflows.sync";
         summary: string;
     }[];
     handlers: {

package/dist/cli/index.js

@@ -6,6 +6,8 @@
  * Repository synchronization is available through
  * `ankh devtools sync` and `ankh devtools status`, with focused `agents`, `skills`, `eslint`,
  * `prettier`, `knip`, `package`, `workflows`, and `vscode` sync/status subcommands.
+ * Owner packages can opt into deterministic structural metadata with
+ * `ankh devtools structure build` and verify committed evidence with `ankh devtools structure check`.
  *
  * Sync commands accept an optional target directory and `--dry-run`. Aggregate sync is
  * deterministic and idempotent: canonical managed files and skill trees are created or updated,

package/dist/cli/runProviderCommand.js

@@ -1,11 +1,16 @@
 import { sync } from './commands/apm/sync.js';
 import { validate } from './commands/apm/validate.js';
+import { build } from './commands/structure/build.js';
+import { check } from './commands/structure/check.js';
 import { runExternalTool } from './runExternalTool.js';
 import { runRepositoryCommand, } from './runRepositoryCommand.js';
 export async function runProviderCommand(command, argv, context) {
     if (command.kind === 'apm-release') {
         return command.operation === 'sync' ? sync(argv, context) : validate(argv, context);
     }
+    if (command.kind === 'structure') {
+        return command.operation === 'build' ? build(argv, context) : check(argv, context);
+    }
     if (command.kind === 'external') {
         return await runExternalTool(command, argv, {
             cwd: context.cwd,

package/dist/features/structure-descriptor-generation/adapters/inbound/runStructureGenerationCommandAsync.d.ts

@@ -0,0 +1,10 @@
+/*** Parse structure build/check CLI input and emit one machine-readable result. */
+export declare function runStructureGenerationCommandAsync(operation: 'build' | 'check', argv: readonly string[], context: StructureGenerationCommandContext): Promise<{
+    readonly exitCode: number;
+}>;
+interface StructureGenerationCommandContext {
+    readonly cwd: string;
+    readonly writeStdout: (text: string) => void;
+    readonly writeStderr: (text: string) => void;
+}
+export {};

package/dist/features/structure-descriptor-generation/adapters/inbound/runStructureGenerationCommandAsync.js

@@ -0,0 +1,22 @@
+import { resolve } from 'node:path';
+import { synchronizeStructureArtifactForDirectoryAsync } from '../../composition/synchronizeStructureArtifactForDirectoryAsync.js';
+/*** Parse structure build/check CLI input and emit one machine-readable result. */
+export async function runStructureGenerationCommandAsync(operation, argv, context) {
+    try {
+        const target = parseTarget(argv, context.cwd);
+        const result = await synchronizeStructureArtifactForDirectoryAsync(operation, target);
+        context.writeStdout(`${JSON.stringify(result)}\n`);
+        return { exitCode: operation === 'check' && result.applicable && !result.current ? 1 : 0 };
+    }
+    catch (error) {
+        context.writeStderr(`${error instanceof Error ? error.message : 'Structure generation failed.'}\n`);
+        return { exitCode: 1 };
+    }
+}
+/*** Resolve the optional target directory and reject unsupported flags/extra operands. */
+function parseTarget(argv, cwd) {
+    if (argv.length > 1 || argv.some((value) => value.startsWith('-'))) {
+        throw new Error('Expected at most one structure-generation target directory.');
+    }
+    return resolve(cwd, argv.at(0) ?? '.');
+}

package/dist/features/structure-descriptor-generation/adapters/outbound/createStructureGenerationWorkspacePort.d.ts

@@ -0,0 +1,3 @@
+import type { StructureGenerationWorkspacePort } from '../../../../types/structure-generation.js';
+/*** Create the bounded filesystem/compiler adapter used by structure build and check commands. */
+export declare function createStructureGenerationWorkspacePort(targetDirectory: string): StructureGenerationWorkspacePort;

package/dist/features/structure-descriptor-generation/adapters/outbound/createStructureGenerationWorkspacePort.js

@@ -0,0 +1,92 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { isRecord } from '@ankhorage/utility/object';
+import { generateStructureArtifactFromTypescriptAsync } from './generateStructureArtifactFromTypescriptAsync.js';
+/*** Create the bounded filesystem/compiler adapter used by structure build and check commands. */
+export function createStructureGenerationWorkspacePort(targetDirectory) {
+    return {
+        readPackageAsync: async () => readStructurePackageAsync(targetDirectory),
+        generateArtifactAsync: (packageConfig) => Promise.resolve(generateStructureArtifactFromTypescriptAsync(targetDirectory, packageConfig)),
+        readOutputAsync: async (relativePath) => readOptionalFileAsync(targetDirectory, relativePath),
+        writeOutputAsync: async (relativePath, source) => writeGeneratedFileAsync(targetDirectory, relativePath, source),
+    };
+}
+/*** Read and validate the package-owned structure generation declaration. */
+async function readStructurePackageAsync(targetDirectory) {
+    const packagePath = resolve(targetDirectory, 'package.json');
+    const raw = JSON.parse(await readFile(packagePath, 'utf8'));
+    if (!isRecord(raw))
+        throw new Error('package.json must contain one JSON object.');
+    const { ankh, name, version } = raw;
+    if (typeof name !== 'string' || name.trim() === '') {
+        throw new Error('package.json needs a package name.');
+    }
+    if (typeof version !== 'string' || version.trim() === '') {
+        throw new Error('package.json needs a package version.');
+    }
+    if (!isRecord(ankh) || ankh.structure === undefined)
+        return null;
+    return { name, version, config: parseStructureConfig(ankh.structure, targetDirectory) };
+}
+/*** Parse explicit structure roots and one generated output path without accepting path escapes. */
+function parseStructureConfig(value, targetDirectory) {
+    if (!isRecord(value))
+        throw new Error('ankh.structure must define output and roots.');
+    const { output: configuredOutput, roots: configuredRoots } = value;
+    if (typeof configuredOutput !== 'string' || !isRecord(configuredRoots)) {
+        throw new Error('ankh.structure must define output and roots.');
+    }
+    const output = validateRelativePath(configuredOutput, targetDirectory, 'ankh.structure.output');
+    const roots = Object.fromEntries(Object.entries(configuredRoots)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, root]) => [name, parseRoot(name, root, targetDirectory)]));
+    if (Object.keys(roots).length === 0)
+        throw new Error('ankh.structure.roots must not be empty.');
+    return { output, roots };
+}
+/*** Parse one explicit root source/export declaration. */
+function parseRoot(name, value, targetDirectory) {
+    if (name.trim() === '' ||
+        !isRecord(value) ||
+        typeof value.source !== 'string' ||
+        typeof value.export !== 'string' ||
+        value.export.trim() === '') {
+        throw new Error(`Invalid structural root "${name}".`);
+    }
+    return {
+        source: validateRelativePath(value.source, targetDirectory, `structure root ${name}`),
+        export: value.export,
+    };
+}
+/*** Require repository-relative paths that resolve inside the selected package root. */
+function validateRelativePath(value, targetDirectory, label) {
+    if (value.trim() === '' || isAbsolute(value))
+        throw new Error(`${label} must be relative.`);
+    const absolute = resolve(targetDirectory, value);
+    const resolved = relative(targetDirectory, absolute);
+    if (resolved === '..' || resolved.startsWith('../') || resolved.startsWith('..\\')) {
+        throw new Error(`${label} must stay inside the package root.`);
+    }
+    return value.replaceAll('\\', '/');
+}
+/*** Read an optional generated artifact without treating absence as a filesystem error. */
+async function readOptionalFileAsync(targetDirectory, relativePath) {
+    try {
+        return await readFile(resolve(targetDirectory, relativePath), 'utf8');
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+/*** Write one generated artifact after ensuring its owning directory exists. */
+async function writeGeneratedFileAsync(targetDirectory, relativePath, source) {
+    const output = resolve(targetDirectory, relativePath);
+    await mkdir(dirname(output), { recursive: true });
+    await writeFile(output, source, 'utf8');
+}
+/*** Narrow Node filesystem failures without unsafe error casts. */
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}

package/dist/features/structure-descriptor-generation/adapters/outbound/generateStructureArtifactFromTypescriptAsync.d.ts

@@ -0,0 +1,3 @@
+import type { StructureGenerationArtifact, StructureGenerationPackage } from '../../../../types/structure-generation.js';
+/*** Generate one deterministic structural descriptor artifact from explicit public type roots. */
+export declare function generateStructureArtifactFromTypescriptAsync(targetDirectory: string, packageConfig: StructureGenerationPackage): StructureGenerationArtifact;

package/dist/features/structure-descriptor-generation/adapters/outbound/generateStructureArtifactFromTypescriptAsync.js

@@ -0,0 +1,142 @@
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { isStructureDescriptorDocument } from '@ankhorage/contracts/structure';
+import ts from 'typescript';
+import { resolveSemanticStructureWrapperNode } from '../../utils/resolveSemanticStructureWrapper.js';
+import { resolveStructureType } from '../../utils/resolveStructureType.js';
+/*** Generate one deterministic structural descriptor artifact from explicit public type roots. */
+export function generateStructureArtifactFromTypescriptAsync(targetDirectory, packageConfig) {
+    const { program, checker } = createCompiler(targetDirectory, packageConfig);
+    assertProgramDiagnostics(program, targetDirectory);
+    const context = {
+        checker,
+        program,
+        targetDirectory,
+        packageName: packageConfig.name,
+        definitions: new Map(),
+        definitionSymbols: new Map(),
+        resolving: new Set(),
+    };
+    const roots = resolveRoots(packageConfig, context);
+    const document = {
+        protocolVersion: 1,
+        packageName: packageConfig.name,
+        packageVersion: packageConfig.version,
+        roots,
+        descriptors: Object.fromEntries([...context.definitions.entries()].sort(([left], [right]) => left.localeCompare(right))),
+    };
+    if (!isStructureDescriptorDocument(document)) {
+        throw new Error('Generated structural descriptor document failed canonical Contracts validation.');
+    }
+    const serialized = JSON.stringify(document, null, 2);
+    const compilerVersion = ts.version;
+    const fingerprintSource = JSON.stringify({ compilerVersion, document });
+    const fingerprint = `sha256:${createHash('sha256').update(fingerprintSource).digest('hex')}`;
+    return {
+        document,
+        fingerprint,
+        source: renderArtifactSource(serialized, fingerprint, compilerVersion),
+    };
+}
+/*** Build a TypeScript program containing the target project plus every explicit structure root source. */
+function createCompiler(targetDirectory, packageConfig) {
+    const configPath = ts.findConfigFile(targetDirectory, (fileName) => ts.sys.fileExists(fileName), 'tsconfig.json');
+    if (!configPath)
+        throw new Error('Structure generation requires a project tsconfig.json.');
+    const loaded = ts.readConfigFile(configPath, (fileName) => ts.sys.readFile(fileName));
+    if (loaded.error)
+        throw new Error(formatDiagnostic(loaded.error, targetDirectory));
+    const parsed = ts.parseJsonConfigFileContent(loaded.config, ts.sys, targetDirectory);
+    const rootSources = Object.values(packageConfig.config.roots).map((root) => resolve(targetDirectory, root.source));
+    const rootNames = [...new Set([...parsed.fileNames, ...rootSources])].sort();
+    const program = ts.createProgram({ rootNames, options: parsed.options });
+    return { program, checker: program.getTypeChecker() };
+}
+/*** Fail closed when target compilation contains an error diagnostic. */
+function assertProgramDiagnostics(program, targetDirectory) {
+    const errors = ts
+        .getPreEmitDiagnostics(program)
+        .filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+    if (errors.length === 0)
+        return;
+    throw new Error(errors
+        .slice(0, 10)
+        .map((diagnostic) => formatDiagnostic(diagnostic, targetDirectory))
+        .join('\n'));
+}
+/*** Resolve every opted-in export to a stable local descriptor definition. */
+function resolveRoots(packageConfig, context) {
+    return Object.fromEntries(Object.entries(packageConfig.config.roots)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([rootName, root]) => [rootName, resolveRoot(rootName, root, context)]));
+}
+/*** Resolve one configured public export and materialize its root definition. */
+function resolveRoot(rootName, root, context) {
+    const sourcePath = resolve(context.targetDirectory, root.source);
+    const sourceFile = context.program.getSourceFile(sourcePath);
+    if (!sourceFile) {
+        throw new Error(`Structure root "${rootName}" source is not part of the TypeScript program.`);
+    }
+    const moduleSymbol = context.checker.getSymbolAtLocation(sourceFile);
+    if (!moduleSymbol) {
+        throw new Error(`Structure root "${rootName}" source has no module symbol.`);
+    }
+    const exported = context.checker
+        .getExportsOfModule(moduleSymbol)
+        .find((symbol) => symbol.getName() === root.export);
+    if (!exported) {
+        throw new Error(`Structure root "${rootName}" cannot find exported type "${root.export}".`);
+    }
+    const symbol = (exported.flags & ts.SymbolFlags.Alias) !== 0
+        ? context.checker.getAliasedSymbol(exported)
+        : exported;
+    const id = symbol.getName();
+    materializeRootDefinition(id, symbol, context);
+    return id;
+}
+/*** Materialize a configured root inline while nested named types remain references. */
+function materializeRootDefinition(id, symbol, context) {
+    const previous = context.definitionSymbols.get(id);
+    if (previous && previous !== symbol) {
+        throw new Error(`Duplicate structural descriptor id "${id}".`);
+    }
+    if (context.definitions.has(id))
+        return;
+    const type = context.checker.getDeclaredTypeOfSymbol(symbol);
+    const aliasDeclaration = symbol.declarations?.find(ts.isTypeAliasDeclaration);
+    const declaredDescriptor = aliasDeclaration
+        ? resolveSemanticStructureWrapperNode(aliasDeclaration.type, context, (value) => resolveStructureType(value, context))
+        : null;
+    context.definitionSymbols.set(id, symbol);
+    context.resolving.add(id);
+    context.definitions.set(id, {
+        id,
+        descriptor: declaredDescriptor ?? resolveStructureType(type, context, symbol),
+    });
+    context.resolving.delete(id);
+}
+/*** Render a generated source module containing the canonical document and its content fingerprint. */
+function renderArtifactSource(serialized, fingerprint, compilerVersion) {
+    return [
+        '/* This file is generated by @ankhorage/devtools. Do not edit manually. */',
+        "import type { StructureDescriptorDocument } from '@ankhorage/contracts/structure';",
+        '',
+        `export const STRUCTURE_DESCRIPTOR_COMPILER_VERSION = '${compilerVersion}';`,
+        `export const STRUCTURE_DESCRIPTOR_FINGERPRINT = '${fingerprint}';`,
+        '',
+        'export const STRUCTURE_DESCRIPTOR = ' +
+            serialized +
+            ' as const satisfies StructureDescriptorDocument;',
+        '',
+    ].join('\n');
+}
+/*** Render one compiler diagnostic without leaking absolute source paths. */
+function formatDiagnostic(diagnostic, targetDirectory) {
+    const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
+    if (!diagnostic.file)
+        return message;
+    const relative = diagnostic.file.fileName.startsWith(targetDirectory)
+        ? diagnostic.file.fileName.slice(targetDirectory.length).replace(/^[/\\]+/u, '')
+        : diagnostic.file.fileName.split(/[/\\]/u).at(-1);
+    return relative ? `${relative}: ${message}` : message;
+}

package/dist/features/structure-descriptor-generation/adapters/outbound/resolveStructureReleaseCommandAsync.d.ts

@@ -0,0 +1,2 @@
+/*** Use Devtools' built structure CLI for self-release and the installed binary in consumers. */
+export declare function resolveStructureReleaseCommandAsync(targetDirectory: string): Promise<string>;

package/dist/features/structure-descriptor-generation/adapters/outbound/resolveStructureReleaseCommandAsync.js

@@ -0,0 +1,21 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+/*** Use Devtools' built structure CLI for self-release and the installed binary in consumers. */
+export async function resolveStructureReleaseCommandAsync(targetDirectory) {
+    try {
+        const packageJson = JSON.parse(await readFile(resolve(targetDirectory, 'package.json'), 'utf8'));
+        return isPackageNamed(packageJson, '@ankhorage/devtools') ? SELF_COMMAND : CONSUMER_COMMAND;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return CONSUMER_COMMAND;
+        }
+        throw error;
+    }
+}
+/*** Narrow a package manifest by its canonical package name. */
+function isPackageNamed(value, expectedName) {
+    return (typeof value === 'object' && value !== null && 'name' in value && value.name === expectedName);
+}
+const SELF_COMMAND = 'node ./dist/cli/bin/structure.js';
+const CONSUMER_COMMAND = './node_modules/.bin/ankhorage-structure';

package/dist/features/structure-descriptor-generation/application/use-cases/synchronizeStructureArtifactAsync.d.ts

@@ -0,0 +1,3 @@
+import type { StructureGenerationResult, StructureGenerationWorkspacePort } from '../../../../types/structure-generation.js';
+/*** Build or check the deterministic structural descriptor artifact for one opted-in owner package. */
+export declare function synchronizeStructureArtifactAsync(operation: 'build' | 'check', port: StructureGenerationWorkspacePort): Promise<StructureGenerationResult>;

package/dist/features/structure-descriptor-generation/application/use-cases/synchronizeStructureArtifactAsync.js

@@ -0,0 +1,20 @@
+/*** Build or check the deterministic structural descriptor artifact for one opted-in owner package. */
+export async function synchronizeStructureArtifactAsync(operation, port) {
+    const packageConfig = await port.readPackageAsync();
+    if (!packageConfig) {
+        return { applicable: false, changed: false, current: true };
+    }
+    const artifact = await port.generateArtifactAsync(packageConfig);
+    const current = await port.readOutputAsync(packageConfig.config.output);
+    const matches = current === artifact.source;
+    if (operation === 'build' && !matches) {
+        await port.writeOutputAsync(packageConfig.config.output, artifact.source);
+    }
+    return {
+        applicable: true,
+        changed: operation === 'build' && !matches,
+        current: matches,
+        outputPath: packageConfig.config.output,
+        fingerprint: artifact.fingerprint,
+    };
+}

package/dist/features/structure-descriptor-generation/composition/synchronizeStructureArtifactForDirectoryAsync.d.ts

@@ -0,0 +1,3 @@
+import type { StructureGenerationResult } from '../../../types/structure-generation.js';
+/*** Compose structure artifact generation with the Node workspace adapter for one package root. */
+export declare function synchronizeStructureArtifactForDirectoryAsync(operation: 'build' | 'check', targetDirectory: string): Promise<StructureGenerationResult>;

package/dist/features/structure-descriptor-generation/composition/synchronizeStructureArtifactForDirectoryAsync.js

@@ -0,0 +1,6 @@
+import { createStructureGenerationWorkspacePort } from '../adapters/outbound/createStructureGenerationWorkspacePort.js';
+import { synchronizeStructureArtifactAsync } from '../application/use-cases/synchronizeStructureArtifactAsync.js';
+/*** Compose structure artifact generation with the Node workspace adapter for one package root. */
+export async function synchronizeStructureArtifactForDirectoryAsync(operation, targetDirectory) {
+    return synchronizeStructureArtifactAsync(operation, createStructureGenerationWorkspacePort(targetDirectory));
+}

package/dist/features/structure-descriptor-generation/utils/resolveSemanticStructureWrapper.d.ts

@@ -0,0 +1,9 @@
+import type { StructureDescriptor } from '@ankhorage/contracts/structure';
+import ts from 'typescript';
+import type { StructureCompilerContext } from '../../../types/structure-generation.js';
+type ResolveType = (type: ts.Type) => StructureDescriptor;
+/*** Resolve canonical Contracts collection wrappers before generic TypeScript object expansion. */
+export declare function resolveSemanticStructureWrapper(type: ts.Type, context: StructureCompilerContext, resolveType: ResolveType): StructureDescriptor | null;
+/*** Resolve canonical collection semantics from a declared TypeScript type node before normalization. */
+export declare function resolveSemanticStructureWrapperNode(node: ts.TypeNode, context: StructureCompilerContext, resolveType: ResolveType): StructureDescriptor | null;
+export {};

package/dist/features/structure-descriptor-generation/utils/resolveSemanticStructureWrapper.js

@@ -0,0 +1,150 @@
+import ts from 'typescript';
+import { resolveStructureSymbolPackage } from './resolveStructureSymbolPackage.js';
+/*** Resolve canonical Contracts collection wrappers before generic TypeScript object expansion. */
+export function resolveSemanticStructureWrapper(type, context, resolveType) {
+    const match = resolveWrapperMatch(type, context, new Set());
+    return match ? buildWrapperDescriptor(match.name, match.arguments, context, resolveType) : null;
+}
+/*** Resolve canonical collection semantics from a declared TypeScript type node before normalization. */
+export function resolveSemanticStructureWrapperNode(node, context, resolveType) {
+    const match = resolveWrapperNodeMatch(node, context, new Set());
+    return match ? buildWrapperDescriptor(match.name, match.arguments, context, resolveType) : null;
+}
+/*** Follow declared type-reference aliases until a canonical Contracts wrapper symbol is reached. */
+function resolveWrapperNodeMatch(node, context, visited) {
+    if (!ts.isTypeReferenceNode(node))
+        return null;
+    const rawSymbol = context.checker.getSymbolAtLocation(node.typeName);
+    if (!rawSymbol)
+        return null;
+    const canonicalName = resolveCanonicalWrapperName(rawSymbol, context);
+    if (canonicalName) {
+        return {
+            name: canonicalName,
+            arguments: node.typeArguments?.map((argument) => context.checker.getTypeFromTypeNode(argument)) ?? [],
+        };
+    }
+    const symbol = resolveAliasedSymbol(rawSymbol, context.checker);
+    if (visited.has(symbol))
+        return null;
+    const declaration = symbol.declarations?.find(ts.isTypeAliasDeclaration);
+    if (!declaration)
+        return null;
+    const nextVisited = new Set(visited);
+    nextVisited.add(symbol);
+    return resolveWrapperNodeMatch(declaration.type, context, nextVisited);
+}
+/*** Follow source alias declarations until the exact canonical Contracts wrapper is reached. */
+function resolveWrapperMatch(type, context, visited) {
+    const direct = resolveDirectWrapper(type, context);
+    if (direct)
+        return direct;
+    const { aliasSymbol } = type;
+    if (!aliasSymbol || visited.has(aliasSymbol))
+        return null;
+    const nextVisited = new Set(visited);
+    nextVisited.add(aliasSymbol);
+    const declaration = aliasSymbol.declarations?.find(ts.isTypeAliasDeclaration);
+    if (!declaration)
+        return null;
+    const targetType = context.checker.getTypeFromTypeNode(declaration.type);
+    const nested = targetType === type ? null : resolveWrapperMatch(targetType, context, nextVisited);
+    if (nested)
+        return nested;
+    return ts.isTypeReferenceNode(declaration.type)
+        ? resolveWrapperFromReferenceNode(declaration.type, context)
+        : null;
+}
+/*** Resolve one source-level type reference against the canonical owner API identity. */
+function resolveWrapperFromReferenceNode(reference, context) {
+    const rawSymbol = context.checker.getSymbolAtLocation(reference.typeName);
+    if (!rawSymbol)
+        return null;
+    const name = resolveCanonicalWrapperName(rawSymbol, context);
+    if (!name)
+        return null;
+    return {
+        name,
+        arguments: reference.typeArguments?.map((argument) => context.checker.getTypeFromTypeNode(argument)) ??
+            [],
+    };
+}
+/*** Resolve an exact canonical wrapper through package ownership or its public structure import. */
+function resolveCanonicalWrapperName(rawSymbol, context) {
+    const importedName = resolveStructureImportName(rawSymbol);
+    if (importedName && WRAPPER_NAMES.has(importedName))
+        return importedName;
+    const symbol = resolveAliasedSymbol(rawSymbol, context.checker);
+    if (resolveStructureSymbolPackage(symbol, context) !== '@ankhorage/contracts')
+        return null;
+    const name = symbol.getName();
+    return WRAPPER_NAMES.has(name) ? name : null;
+}
+/*** Recognize a named type imported from the exact Contracts structure owner subpath. */
+function resolveStructureImportName(symbol) {
+    for (const declaration of symbol.declarations ?? []) {
+        if (!ts.isImportSpecifier(declaration))
+            continue;
+        const importDeclaration = declaration.parent.parent.parent;
+        if (!ts.isImportDeclaration(importDeclaration) ||
+            !ts.isStringLiteral(importDeclaration.moduleSpecifier) ||
+            importDeclaration.moduleSpecifier.text !== '@ankhorage/contracts/structure') {
+            continue;
+        }
+        return (declaration.propertyName ?? declaration.name).text;
+    }
+    return null;
+}
+/*** Resolve TypeScript import/re-export alias chains to their final declaration symbol. */
+function resolveAliasedSymbol(symbol, checker, visited = new Set()) {
+    if ((symbol.flags & ts.SymbolFlags.Alias) === 0 || visited.has(symbol))
+        return symbol;
+    const next = checker.getAliasedSymbol(symbol);
+    if (next === symbol || next.getName() === 'unknown')
+        return symbol;
+    const nextVisited = new Set(visited);
+    nextVisited.add(symbol);
+    return resolveAliasedSymbol(next, checker, nextVisited);
+}
+/*** Match a direct instantiation of one canonical collection wrapper. */
+function resolveDirectWrapper(type, context) {
+    const rawSymbol = type.aliasSymbol;
+    if (!rawSymbol)
+        return null;
+    const name = resolveCanonicalWrapperName(rawSymbol, context);
+    return name ? { name, arguments: type.aliasTypeArguments ?? [] } : null;
+}
+/*** Convert one canonical wrapper instantiation to its portable descriptor kind. */
+function buildWrapperDescriptor(name, arguments_, context, resolveType) {
+    if (name === 'SerializableSet') {
+        return {
+            kind: 'set',
+            member: resolveType(arguments_.at(0) ?? context.checker.getStringType()),
+        };
+    }
+    const key = arguments_.at(0);
+    const value = arguments_.at(1);
+    if (!key || !value)
+        throw new Error(`${name} requires key and value type arguments.`);
+    if (name === 'ValueMap') {
+        return {
+            kind: 'value-map',
+            key: resolveType(key),
+            value: resolveType(value),
+        };
+    }
+    const identity = arguments_.at(2);
+    return {
+        kind: 'entity-registry',
+        key: resolveType(key),
+        value: resolveType(value),
+        ...resolveIdentityField(identity),
+    };
+}
+/*** Resolve an EntityRegistry identity-field marker from a string literal type argument. */
+function resolveIdentityField(type) {
+    if (!type || (type.flags & ts.TypeFlags.Never) !== 0)
+        return {};
+    return type.isStringLiteral() ? { identityField: type.value } : {};
+}
+const WRAPPER_NAMES = new Set(['EntityRegistry', 'SerializableSet', 'ValueMap']);

package/dist/features/structure-descriptor-generation/utils/resolveStructureSymbolPackage.d.ts

@@ -0,0 +1,4 @@
+import type ts from 'typescript';
+import type { StructureCompilerContext } from '../../../types/structure-generation.js';
+/*** Resolve the owning npm package for a TypeScript symbol without exposing source paths in artifacts. */
+export declare function resolveStructureSymbolPackage(symbol: ts.Symbol, context: StructureCompilerContext): string | null;

package/dist/features/structure-descriptor-generation/utils/resolveStructureSymbolPackage.js

@@ -0,0 +1,33 @@
+import { relative, sep } from 'node:path';
+/*** Resolve the owning npm package for a TypeScript symbol without exposing source paths in artifacts. */
+export function resolveStructureSymbolPackage(symbol, context) {
+    const declaration = symbol.declarations?.at(0);
+    if (!declaration)
+        return null;
+    const { fileName } = declaration.getSourceFile();
+    const nodeModulePackage = resolveNodeModulePackage(fileName);
+    if (nodeModulePackage)
+        return nodeModulePackage;
+    const relativePath = relative(context.targetDirectory, fileName);
+    if (relativePath !== '..' &&
+        !relativePath.startsWith(`..${sep}`) &&
+        !relativePath.startsWith('..')) {
+        return context.packageName;
+    }
+    return null;
+}
+/*** Resolve npm package ownership before classifying source paths as local project files. */
+function resolveNodeModulePackage(fileName) {
+    const normalized = fileName.replaceAll('\\', '/');
+    const marker = '/node_modules/';
+    const markerIndex = normalized.lastIndexOf(marker);
+    if (markerIndex < 0)
+        return null;
+    const packagePath = normalized.slice(markerIndex + marker.length);
+    const [first, second] = packagePath.split('/');
+    if (!first)
+        return null;
+    if (!first.startsWith('@'))
+        return first;
+    return second ? `${first}/${second}` : null;
+}

package/dist/features/structure-descriptor-generation/utils/resolveStructureType.d.ts

@@ -0,0 +1,5 @@
+import type { StructureDescriptor } from '@ankhorage/contracts/structure';
+import ts from 'typescript';
+import type { StructureCompilerContext } from '../../../types/structure-generation.js';
+/*** Resolve one TypeScript type into the canonical structural descriptor graph. */
+export declare function resolveStructureType(type: ts.Type, context: StructureCompilerContext, inlineSymbol?: ts.Symbol): StructureDescriptor;

package/dist/features/structure-descriptor-generation/utils/resolveStructureType.js

@@ -0,0 +1,210 @@
+import ts from 'typescript';
+import { resolveSemanticStructureWrapper, resolveSemanticStructureWrapperNode, } from './resolveSemanticStructureWrapper.js';
+import { resolveStructureSymbolPackage } from './resolveStructureSymbolPackage.js';
+/*** Resolve one TypeScript type into the canonical structural descriptor graph. */
+export function resolveStructureType(type, context, inlineSymbol) {
+    const wrapper = resolveSemanticStructureWrapper(type, context, (value) => resolveStructureType(value, context));
+    if (wrapper)
+        return wrapper;
+    const symbol = resolveNamedSymbol(type);
+    if (symbol && symbol !== inlineSymbol)
+        return resolveNamedType(symbol, type, context);
+    return resolveTypeBody(type, context);
+}
+/*** Resolve a named local type by reference or preserve an external owner reference. */
+function resolveNamedType(symbol, type, context) {
+    const owner = resolveStructureSymbolPackage(symbol, context);
+    const id = stableSymbolName(symbol);
+    if (owner && owner !== context.packageName)
+        return { kind: 'ref', packageName: owner, id };
+    ensureStructureDefinition(symbol, type, context);
+    return { kind: 'ref', id };
+}
+/*** Materialize one local named descriptor exactly once while supporting recursive references. */
+function ensureStructureDefinition(symbol, type, context) {
+    const id = stableSymbolName(symbol);
+    const previous = context.definitionSymbols.get(id);
+    if (previous && previous !== symbol) {
+        throw new Error(`Duplicate structural descriptor id "${id}" in ${context.packageName}.`);
+    }
+    if (context.definitions.has(id) || context.resolving.has(id))
+        return;
+    context.definitionSymbols.set(id, symbol);
+    context.resolving.add(id);
+    const descriptor = resolveStructureType(type, context, symbol);
+    context.definitions.set(id, { id, descriptor });
+    context.resolving.delete(id);
+}
+/*** Resolve primitives, literals, arrays, unions, and fixed object shapes. */
+function resolveTypeBody(type, context) {
+    const primitive = resolvePrimitive(type);
+    if (primitive)
+        return primitive;
+    const literal = resolveLiteral(type, context.checker);
+    if (literal !== undefined)
+        return { kind: 'enum', values: [literal] };
+    if (type.isUnion())
+        return resolveUnion(type, context);
+    const arrayItem = resolveArrayItem(type, context.checker);
+    if (arrayItem) {
+        return { kind: 'ordered-list', item: resolveStructureType(arrayItem, context) };
+    }
+    if ((type.flags & ts.TypeFlags.Object) !== 0)
+        return resolveObject(type, context);
+    throw unsupportedType(type, context, 'unsupported TypeScript type');
+}
+/*** Resolve JSON-safe scalar primitives. */
+function resolvePrimitive(type) {
+    if ((type.flags & ts.TypeFlags.String) !== 0)
+        return { kind: 'scalar', type: 'string' };
+    if ((type.flags & ts.TypeFlags.Number) !== 0)
+        return { kind: 'scalar', type: 'number' };
+    if ((type.flags & ts.TypeFlags.Boolean) !== 0)
+        return { kind: 'scalar', type: 'boolean' };
+    if ((type.flags & ts.TypeFlags.Null) !== 0)
+        return { kind: 'scalar', type: 'null' };
+    return null;
+}
+/*** Resolve one scalar literal while leaving non-literal types untouched. */
+function resolveLiteral(type, checker) {
+    if (type.isStringLiteral())
+        return type.value;
+    if (type.isNumberLiteral())
+        return type.value;
+    if ((type.flags & ts.TypeFlags.BooleanLiteral) !== 0) {
+        return checker.typeToString(type) === 'true';
+    }
+    if ((type.flags & ts.TypeFlags.Null) !== 0)
+        return null;
+    return undefined;
+}
+/*** Resolve finite literal unions or a deterministic general union descriptor. */
+function resolveUnion(type, context) {
+    const effective = type.types.filter((entry) => (entry.flags & ts.TypeFlags.Undefined) === 0);
+    if (effective.length === 0)
+        throw unsupportedType(type, context, 'undefined-only union');
+    if (effective.length === 1)
+        return resolveStructureType(effective[0], context);
+    const literals = effective.map((entry) => resolveLiteral(entry, context.checker));
+    if (literals.every(isDefinedLiteral)) {
+        return { kind: 'enum', values: sortLiterals(literals) };
+    }
+    const variants = effective.map((entry) => resolveStructureType(entry, context));
+    variants.sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+    const discriminator = resolveUnionDiscriminator(effective, context.checker);
+    return { kind: 'union', variants, ...(discriminator ? { discriminator } : {}) };
+}
+/*** Narrow an optional scalar literal after union projection. */
+function isDefinedLiteral(value) {
+    return value !== undefined;
+}
+/*** Resolve a homogeneous Array/ReadonlyArray element type while rejecting tuples. */
+function resolveArrayItem(type, checker) {
+    if (checker.isTupleType(type)) {
+        throw new Error('Tuple types are not supported by structural descriptor generation.');
+    }
+    if (checker.isArrayType(type)) {
+        return checker.getTypeArguments(type).at(0) ?? null;
+    }
+    if ((type.flags & ts.TypeFlags.Object) === 0)
+        return null;
+    const symbolName = type.getSymbol()?.getName();
+    if (symbolName !== 'ReadonlyArray')
+        return null;
+    return checker.getTypeArguments(type).at(0) ?? null;
+}
+/*** Resolve a fixed object shape and reject unmarked records or executable objects. */
+function resolveObject(type, context) {
+    if (type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0) {
+        throw unsupportedType(type, context, 'callable/class-like object');
+    }
+    if (context.checker.getIndexTypeOfType(type, ts.IndexKind.String)) {
+        throw unsupportedType(type, context, 'unmarked string-indexed record');
+    }
+    const fields = Object.fromEntries(type
+        .getProperties()
+        .map((property) => resolveObjectField(property, context))
+        .sort(([left], [right]) => left.localeCompare(right)));
+    return { kind: 'object', fields };
+}
+/*** Resolve one object property including optionality while rejecting methods. */
+function resolveObjectField(property, context) {
+    const declaration = property.valueDeclaration ?? property.declarations?.at(0);
+    if (!declaration)
+        throw new Error(`Property "${property.getName()}" has no source declaration.`);
+    if (ts.isMethodDeclaration(declaration) || ts.isMethodSignature(declaration)) {
+        throw new Error(`Method "${property.getName()}" is not a serializable structural field.`);
+    }
+    const propertyType = context.checker.getTypeOfSymbolAtLocation(property, declaration);
+    try {
+        const declaredType = hasDeclaredTypeNode(declaration)
+            ? resolveSemanticStructureWrapperNode(declaration.type, context, (value) => resolveStructureType(value, context))
+            : null;
+        return [
+            property.getName(),
+            {
+                value: declaredType ?? resolveStructureType(propertyType, context),
+                ...((property.flags & ts.SymbolFlags.Optional) !== 0 ? { optional: true } : {}),
+            },
+        ];
+    }
+    catch (error) {
+        throw new Error(`Cannot generate field "${property.getName()}": ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+/*** Narrow property declarations that carry a source-level type node. */
+function hasDeclaredTypeNode(declaration) {
+    return ((ts.isPropertyDeclaration(declaration) || ts.isPropertySignature(declaration)) &&
+        declaration.type !== undefined);
+}
+/*** Resolve a stable discriminator shared by every object-like union variant. */
+function resolveUnionDiscriminator(variants, checker) {
+    const [first] = variants;
+    const candidates = first
+        .getProperties()
+        .map((property) => property.getName())
+        .sort();
+    for (const name of candidates) {
+        const values = variants.map((variant) => resolveDiscriminatorValue(variant, name, checker));
+        if (values.every((value) => value !== null) && new Set(values).size === values.length) {
+            return name;
+        }
+    }
+    return null;
+}
+/*** Resolve one string/number literal discriminator value from an object variant. */
+function resolveDiscriminatorValue(type, name, checker) {
+    const property = type.getProperty(name);
+    if (!property)
+        return null;
+    const declaration = property.valueDeclaration ?? property.declarations?.at(0);
+    if (!declaration)
+        return null;
+    const value = checker.getTypeOfSymbolAtLocation(property, declaration);
+    if (value.isStringLiteral() || value.isNumberLiteral())
+        return value.value;
+    return null;
+}
+/*** Return the meaningful alias/interface symbol for reference identity. */
+function resolveNamedSymbol(type) {
+    const symbol = type.aliasSymbol ?? type.getSymbol();
+    if (!symbol)
+        return null;
+    const name = symbol.getName();
+    return name.startsWith('__') || name === 'Array' || name === 'ReadonlyArray' ? null : symbol;
+}
+/*** Require one stable source-level symbol name independent of declaration file paths. */
+function stableSymbolName(symbol) {
+    const name = symbol.getName();
+    if (name.startsWith('__'))
+        throw new Error('Structural descriptor symbols need stable names.');
+    return name;
+}
+/*** Sort finite scalar values deterministically without changing scalar identity. */
+function sortLiterals(values) {
+    return [...values].sort((left, right) => `${typeof left}:${String(left)}`.localeCompare(`${typeof right}:${String(right)}`));
+}
+/*** Create one actionable unsupported-type error without exposing source paths. */
+function unsupportedType(type, context, reason) {
+    return new Error(`Cannot generate structure for ${context.checker.typeToString(type)}: ${reason}.`);
+}

package/dist/tools/workflows/files/release.yml

@@ -114,6 +114,9 @@ jobs:
           after_version="$(node -p "require('./package.json').version")"
 
           if [ "$before_version" != "$after_version" ]; then
+            if node -e "const p=require('./package.json'); process.exit(p.ankh?.structure === undefined ? 1 : 0)"; then
+              __ANKH_STRUCTURE_RELEASE_COMMAND__ build .
+            fi
             if node -e "const p=require('./package.json'); process.exit(p.scripts?.docs ? 0 : 1)"; then
               bun run docs
             else

package/dist/tools/workflows/index.js

@@ -1,6 +1,7 @@
 import { access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { resolveApmReleaseCommandAsync } from '../../features/apm-release-validation/adapters/outbound/resolveApmReleaseCommandAsync.js';
+import { resolveStructureReleaseCommandAsync } from '../../features/structure-descriptor-generation/adapters/outbound/resolveStructureReleaseCommandAsync.js';
 import { bunRuntimePolicy, nodeRuntimePolicy } from '../../policy/bunRuntimePolicy.js';
 import { readCurrentDoctorVersion } from './readCurrentDoctorVersion.js';
 import { renderRenovateWorkflowAsync } from './renderRenovateWorkflowAsync.js';
@@ -35,6 +36,7 @@ function createWorkflowDefinition(relativePath, sourcePath) {
         relativePath,
         render: async (targetDirectory) => await renderWorkflowAsync(sourceUrl, {
             apmReleaseCommand: await resolveApmReleaseCommandAsync(targetDirectory),
+            structureReleaseCommand: await resolveStructureReleaseCommandAsync(targetDirectory),
             bunVersion: bunRuntimePolicy.version,
             doctorVersion: readCurrentDoctorVersion(),
             nodeVersion: nodeRuntimePolicy.setupVersion,
@@ -48,6 +50,7 @@ function createRenovateWorkflowDefinition() {
         relativePath: '.github/workflows/renovate.yml',
         render: async (targetDirectory) => await renderRenovateWorkflowAsync(sourceUrl, targetDirectory, {
             apmReleaseCommand: await resolveApmReleaseCommandAsync(targetDirectory),
+            structureReleaseCommand: await resolveStructureReleaseCommandAsync(targetDirectory),
             bunVersion: bunRuntimePolicy.version,
             doctorVersion: readCurrentDoctorVersion(),
             nodeVersion: nodeRuntimePolicy.setupVersion,

package/dist/tools/workflows/renderWorkflowAsync.d.ts

@@ -3,6 +3,7 @@ export interface WorkflowPolicy {
     readonly doctorVersion: string;
     readonly nodeVersion: string;
     readonly apmReleaseCommand?: string;
+    readonly structureReleaseCommand?: string;
 }
 /*** Renders one workflow template with the canonical runtime, Doctor, and Changesets policy. */
 export declare function renderWorkflowAsync(sourceUrl: URL, policy: WorkflowPolicy): Promise<string>;

package/dist/tools/workflows/renderWorkflowAsync.js

@@ -10,6 +10,7 @@ export async function renderWorkflowAsync(sourceUrl, policy) {
         .replaceAll(CHANGESETS_VERSION_COMMAND_TOKEN, changesetsPolicy.workflowCommands.version)
         .replaceAll(DOCTOR_VERSION_TOKEN, policy.doctorVersion)
         .replaceAll('__ANKH_APM_RELEASE_COMMAND__', policy.apmReleaseCommand ?? './node_modules/.bin/ankhorage-apm-release')
+        .replaceAll('__ANKH_STRUCTURE_RELEASE_COMMAND__', policy.structureReleaseCommand ?? './node_modules/.bin/ankhorage-structure')
         .replaceAll(NODE_VERSION_TOKEN, policy.nodeVersion);
 }
 const BUN_VERSION_TOKEN = '__ANKH_BUN_VERSION__';

package/dist/types/structure-generation.d.ts

@@ -0,0 +1,42 @@
+import type { StructureDescriptorDefinition, StructureDescriptorDocument } from '@ankhorage/contracts/structure';
+import type ts from 'typescript';
+export interface StructureGenerationRoot {
+    readonly source: string;
+    readonly export: string;
+}
+export interface StructureGenerationConfig {
+    readonly output: string;
+    readonly roots: Readonly<Record<string, StructureGenerationRoot>>;
+}
+export interface StructureGenerationPackage {
+    readonly name: string;
+    readonly version: string;
+    readonly config: StructureGenerationConfig;
+}
+export interface StructureGenerationArtifact {
+    readonly document: StructureDescriptorDocument;
+    readonly fingerprint: string;
+    readonly source: string;
+}
+export interface StructureGenerationResult {
+    readonly applicable: boolean;
+    readonly changed: boolean;
+    readonly current: boolean;
+    readonly outputPath?: string;
+    readonly fingerprint?: string;
+}
+export interface StructureGenerationWorkspacePort {
+    readonly readPackageAsync: () => Promise<StructureGenerationPackage | null>;
+    readonly generateArtifactAsync: (packageConfig: StructureGenerationPackage) => Promise<StructureGenerationArtifact>;
+    readonly readOutputAsync: (relativePath: string) => Promise<string | null>;
+    readonly writeOutputAsync: (relativePath: string, source: string) => Promise<void>;
+}
+export interface StructureCompilerContext {
+    readonly checker: ts.TypeChecker;
+    readonly program: ts.Program;
+    readonly targetDirectory: string;
+    readonly packageName: string;
+    readonly definitions: Map<string, StructureDescriptorDefinition>;
+    readonly definitionSymbols: Map<string, ts.Symbol>;
+    readonly resolving: Set<string>;
+}

package/dist/types/structure-generation.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.17.2",
+  "version": "1.18.1",
   "description": "Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -21,6 +21,8 @@
     "capabilities": [
       "devtools.apm.sync",
       "devtools.apm.validate",
+      "devtools.structure.build",
+      "devtools.structure.check",
       "devtools.changeset",
       "devtools.lint",
       "devtools.format",
@@ -64,7 +66,8 @@
     "ankhorage-eslint": "./dist/cli/bin/eslint.js",
     "ankhorage-knip": "./dist/cli/bin/knip.js",
     "ankhorage-prettier": "./dist/cli/bin/prettier.js",
-    "ankhorage-apm-release": "./dist/cli/bin/apm-release.js"
+    "ankhorage-apm-release": "./dist/cli/bin/apm-release.js",
+    "ankhorage-structure": "./dist/cli/bin/structure.js"
   },
   "exports": {
     "./cli": {
@@ -140,7 +143,8 @@
     "eslint-plugin-unused-imports": "^4.4.1",
     "knip": "^6.34.0",
     "prettier": "^3.9.6",
-    "typescript-eslint": "^8.69.0"
+    "typescript-eslint": "^8.69.0",
+    "@ankhorage/contracts": "^22.1.1"
   },
   "devDependencies": {
     "@ankhorage/paradox": "^0.1.26",
@@ -152,5 +156,8 @@
     "sharp": "^0.35.4",
     "typescript": "~6.0.3"
   },
-  "packageManager": "bun@1.4.2"
+  "packageManager": "bun@1.4.2",
+  "peerDependencies": {
+    "typescript": ">=5.9.3 <7"
+  }
 }