@ankhorage/devtools 1.14.8 → 1.15.0

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/devtools
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v1.14.7](././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.14.8](././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
 
@@ -68,6 +68,8 @@ Synchronization ensures `@ankhorage/devtools` is declared using the version of t
 
 The package is discovered under the `devtools` category and exposes these capabilities:
 
+- `devtools.apm.sync`
+- `devtools.apm.validate`
 - `devtools.lint`
 - `devtools.changeset`
 - `devtools.format`
@@ -385,6 +387,59 @@ A new concern should:
 5. include dry-run, status, and idempotence coverage
 6. document its central ownership and repository-owned extension points
 
+## Package-owned APM release gates
+
+A package opts in through `ankh.apm` in its `package.json`:
+
+```json
+{
+  "ankh": {
+    "apm": { "protocolVersion": 1, "descriptor": "./apm/update.json" }
+  }
+}
+```
+
+Include the descriptor in `files` and expose any executable extension with an explicit public
+`exports` subpath. Use the released APM descriptor and extension types from `@ankhorage/apm/types`;
+Devtools does not own or duplicate the protocol. Add `test:apm` to run the owner's deterministic
+source-to-target fixtures, including skipped versions, unsupported old states, idempotency and
+interruption recovery. A no-migration release still declares supported history explicitly and
+can pass without an extension. Absence of metadata is reported as inapplicable, not migration-safe.
+
+```sh
+ankh devtools apm sync .
+ankh devtools apm validate . --allow-owner-code --artifact /tmp/reviewed-owner.tgz
+```
+
+The standalone `ankhorage-apm-release sync|validate` binary runs the same operations. The public
+`@ankhorage/devtools/apm-release` entrypoint exports `synchronizeApmReleaseDescriptorAsync`,
+`validatePackedApmReleaseAsync` and `validateApmReleaseCandidate`; types are available from
+`@ankhorage/devtools/types`. Programmatic callers can supply `previousDescriptors` to enforce
+unchanged migration checksums and `relatedDescriptors` for cross-owner prerequisites. Owners
+must include historical descriptors in their `test:apm` fixtures where their migrations require them.
+
+Validation packs with lifecycle scripts disabled, reads only the packed descriptor, checks owner
+identity, protocol/schema, migration/projection IDs, prerequisite graphs and public extension
+capabilities using APM's canonical validators. Invalid metadata is a failure, not an opt-out.
+`--allow-owner-code` is explicit permission to import the packed extension in a bounded child
+process. The child is **not a security sandbox**; run only trusted owner code. Registry metadata
+alone never grants this permission. Installed dependency resolution uses the repository's
+frozen dependency graph; the package's own code is loaded through native public export resolution
+from the extracted archive, never from the source checkout.
+
+`--artifact` creates a new file containing exactly the validated bytes and refuses an existing
+output. The JSON result includes SHA-512 integrity; `--expected-integrity` refuses a different
+archive. Keep the retained archive immutable. The managed release workflow versions with
+Changesets, synchronizes descriptor identity, rebuilds, runs `test:apm`, validates a fresh archive,
+and publishes that same archive using `npm publish --ignore-scripts`, without repacking.
+Authentication and network errors are not treated as an unpublished version. Packages without
+APM metadata retain their existing Changesets publication path.
+
+Producer order is: released APM protocol, validated owner package release, then consumer rollout.
+Never declare an unpublished owner version. Project migration recovery is owned by APM and the
+package's declared handlers; passing this release gate does not execute migrations against user
+projects, deploy production services, or prove compatibility with shipped native binaries.
+
 ## CLI
 
 Run and synchronize the shared development toolchain through the Ankh CLI.
@@ -404,7 +459,17 @@ Fresh repositories can bootstrap the standard setup with `ankh devtools sync .`
 `@ankhorage/devtools`. Existing ESLint configuration is preserved during first migration as a
 local extension before the canonical auto-detecting wrapper is installed.
 
+APM owner releases opt in through `ankh.apm`. `ankh devtools apm sync .` binds a valid
+descriptor to the selected Changesets version. `ankh devtools apm validate .` checks a
+script-free tarball; `--allow-owner-code` explicitly permits the isolated executable probe.
+`--artifact <path>` retains the exact accepted tarball and `--expected-integrity <SRI>`
+rejects changed bytes. Owners provide `test:apm` for source-to-target and recovery fixtures.
+CI runs that owner suite and the packed check. Release rebuilds after versioning, validates,
+then publishes the retained archive with scripts disabled through the existing release job.
+Packages without metadata keep their existing Changesets publish path unchanged.
+
 ```bash
+bunx @ankhorage/devtools ankhorage-apm-release
 bunx @ankhorage/devtools ankhorage-changeset
 bunx @ankhorage/devtools ankhorage-eslint
 bunx @ankhorage/devtools ankhorage-knip
@@ -420,3 +485,50 @@ bunx @ankhorage/devtools ankhorage-prettier
 - [Module relationships](././paradox/diagrams/module-relationships.mmd)
 - [Export graph](././paradox/diagrams/export-graph.mmd)
 - [createKnipMonorepoConfig sequence](././paradox/diagrams/sequences/create-knip-monorepo-config.mmd)
+
+## Public API
+
+### Utilities
+
+<details>
+<summary>validateApmReleaseCandidate</summary>
+
+```ts
+validateApmReleaseCandidate(candidate: ApmPackedReleaseCandidate, options?: ApmReleaseValidationOptions) => ApmReleaseValidationResult
+```
+
+Validate packed owner evidence using the released APM protocol, never a copied schema.
+Opt-in packages declare ankh.apm with protocolVersion and a package-relative descriptor.
+No metadata means not applicable, not a claim that no migration is needed. The descriptor
+declares supported no-migration, required migration, or unsupported/manual history explicitly.
+Previous descriptors enforce immutable migration checksums and related descriptors validate
+cross-owner prerequisites. Package-owned source-to-target tests must also cover skipped versions,
+idempotency, interruption/recovery, and unsupported historical states.
+
+Module: `src/features/apm-release-validation/application/validateApmReleaseCandidate.ts`
+Source: `src/features/apm-release-validation/application/validateApmReleaseCandidate.ts:31:1`
+Related symbols: `ApmPackedReleaseCandidate`, `ApmReleaseValidationOptions`, `ApmReleaseValidationResult`
+
+</details>
+
+<details>
+<summary>validatePackedApmReleaseAsync</summary>
+
+```ts
+validatePackedApmReleaseAsync(targetDirectory: string, options?: ApmReleaseValidationOptions) => Promise<ApmReleaseValidationResult>
+```
+
+Validate script-free publish bytes and optionally retain that exact accepted archive.
+Release order is APM protocol, package-owner metadata/code, then consuming applications.
+Build after Changesets versioning and descriptor synchronization. Execute package-owned
+acceptance tests, then validate with explicit owner-code consent. The child probe uses the
+packed package's native public export resolution and installed dependencies, not omitted source.
+Consent permits trusted executable code; a child process is not a security sandbox.
+An artifactPath retains accepted bytes exclusively, so publication need not repack or rerun
+lifecycle scripts. expectedIntegrity rejects a stale candidate before any owner code loads.
+
+Module: `src/features/apm-release-validation/composition/validatePackedApmReleaseAsync.ts`
+Source: `src/features/apm-release-validation/composition/validatePackedApmReleaseAsync.ts:17:1`
+Related symbols: `ApmReleaseValidationOptions`, `ApmReleaseValidationResult`
+
+</details>

package/dist/apmRelease.d.ts

@@ -0,0 +1,4 @@
+export { validateApmReleaseCandidate } from './features/apm-release-validation/application/validateApmReleaseCandidate.js';
+export { synchronizeApmReleaseDescriptorAsync } from './features/apm-release-validation/composition/synchronizeApmReleaseDescriptorAsync.js';
+export { validatePackedApmReleaseAsync } from './features/apm-release-validation/composition/validatePackedApmReleaseAsync.js';
+export type { ApmPackedReleaseCandidate, ApmReleaseValidationOptions, ApmReleaseValidationResult, } from './types/apm-release-validation.js';

package/dist/apmRelease.js

@@ -0,0 +1,3 @@
+export { validateApmReleaseCandidate } from './features/apm-release-validation/application/validateApmReleaseCandidate.js';
+export { synchronizeApmReleaseDescriptorAsync } from './features/apm-release-validation/composition/synchronizeApmReleaseDescriptorAsync.js';
+export { validatePackedApmReleaseAsync } from './features/apm-release-validation/composition/validatePackedApmReleaseAsync.js';

package/dist/cli/bin/apm-release.d.ts

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

package/dist/cli/bin/apm-release.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { runApmReleaseCommandAsync } from '../../features/apm-release-validation/adapters/inbound/runApmReleaseCommandAsync.js';
+const [operation, ...argv] = process.argv.slice(2);
+if (operation !== 'sync' && operation !== 'validate') {
+    console.error('Usage: ankhorage-apm-release <sync|validate> [directory] [--allow-owner-code] [--artifact path] [--expected-integrity value]');
+    process.exitCode = 1;
+}
+else {
+    const result = await runApmReleaseCommandAsync(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/apm/sync.d.ts

@@ -0,0 +1,5 @@
+import type { DevtoolsProviderCommandContext } from '../../runProviderCommand.js';
+/*** Adapt the public APM release sync command to the shared release boundary. */
+export declare function sync(argv: readonly string[], context: DevtoolsProviderCommandContext): Promise<{
+    readonly exitCode: number;
+}>;

package/dist/cli/commands/apm/sync.js

@@ -0,0 +1,5 @@
+import { runApmReleaseCommandAsync } from '../../../features/apm-release-validation/adapters/inbound/runApmReleaseCommandAsync.js';
+/*** Adapt the public APM release sync command to the shared release boundary. */
+export async function sync(argv, context) {
+    return runApmReleaseCommandAsync('sync', argv, context);
+}

package/dist/cli/commands/apm/validate.d.ts

@@ -0,0 +1,5 @@
+import type { DevtoolsProviderCommandContext } from '../../runProviderCommand.js';
+/*** Adapt the public APM release validate command to the shared release boundary. */
+export declare function validate(argv: readonly string[], context: DevtoolsProviderCommandContext): Promise<{
+    readonly exitCode: number;
+}>;

package/dist/cli/commands/apm/validate.js

@@ -0,0 +1,5 @@
+import { runApmReleaseCommandAsync } from '../../../features/apm-release-validation/adapters/inbound/runApmReleaseCommandAsync.js';
+/*** Adapt the public APM release validate command to the shared release boundary. */
+export async function validate(argv, context) {
+    return runApmReleaseCommandAsync('validate', 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.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.vscode.status' | 'devtools.vscode.sync' | 'devtools.workflows.status' | 'devtools.workflows.sync';
 interface DevtoolsCommandBase {
     readonly path: readonly [string, ...string[]];
     readonly capability: DevtoolsCapability;
@@ -18,7 +18,11 @@ export interface DevtoolsRepositoryCommandDefinition extends DevtoolsCommandBase
     readonly scope: DevtoolsManagedScope;
     readonly operation: DevtoolsManagedOperation;
 }
-export type DevtoolsCommandDefinition = DevtoolsExternalCommandDefinition | DevtoolsRepositoryCommandDefinition;
+interface DevtoolsApmReleaseCommandDefinition extends DevtoolsCommandBase {
+    readonly kind: 'apm-release';
+    readonly operation: 'sync' | 'validate';
+}
+export type DevtoolsCommandDefinition = DevtoolsExternalCommandDefinition | DevtoolsRepositoryCommandDefinition | DevtoolsApmReleaseCommandDefinition;
 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

@@ -1,4 +1,18 @@
 const DEVTOOLS_COMMANDS = [
+    {
+        kind: 'apm-release',
+        operation: 'sync',
+        path: ['apm', 'sync'],
+        capability: 'devtools.apm.sync',
+        summary: 'Bind owner metadata to the Changesets release version.',
+    },
+    {
+        kind: 'apm-release',
+        operation: 'validate',
+        path: ['apm', 'validate'],
+        capability: 'devtools.apm.validate',
+        summary: 'Validate the exact packed APM release artifact.',
+    },
     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'),
@@ -27,7 +41,7 @@ export function getDevtoolsCommands() {
 }
 export function findDevtoolsCommandByPath(path) {
     return (DEVTOOLS_COMMANDS.find((command) => command.path.length === path.length &&
-        command.path.every((segment, index) => segment === path[index])) ?? null);
+        command.path.every((segment, index) => segment === path.at(index))) ?? null);
 }
 export function getDevtoolsToolCommand(toolName) {
     for (const command of DEVTOOLS_COMMANDS) {

package/dist/cli/index.d.ts

@@ -2,10 +2,10 @@ declare const provider: {
     id: string;
     category: string;
     version: string;
-    capabilities: ("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.vscode.status" | "devtools.vscode.sync" | "devtools.workflows.status" | "devtools.workflows.sync")[];
     commands: {
         path: string[];
-        capability: "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.vscode.status" | "devtools.vscode.sync" | "devtools.workflows.status" | "devtools.workflows.sync";
         summary: string;
     }[];
     handlers: {

package/dist/cli/index.js

@@ -16,6 +16,15 @@
  * `@ankhorage/devtools`. Existing ESLint configuration is preserved during first migration as a
  * local extension before the canonical auto-detecting wrapper is installed.
  *
+ * APM owner releases opt in through `ankh.apm`. `ankh devtools apm sync .` binds a valid
+ * descriptor to the selected Changesets version. `ankh devtools apm validate .` checks a
+ * script-free tarball; `--allow-owner-code` explicitly permits the isolated executable probe.
+ * `--artifact <path>` retains the exact accepted tarball and `--expected-integrity <SRI>`
+ * rejects changed bytes. Owners provide `test:apm` for source-to-target and recovery fixtures.
+ * CI runs that owner suite and the packed check. Release rebuilds after versioning, validates,
+ * then publishes the retained archive with scripts disabled through the existing release job.
+ * Packages without metadata keep their existing Changesets publish path unchanged.
+ *
  * @readme
  */
 import { readFileSync } from 'node:fs';

package/dist/cli/runProviderCommand.js

@@ -1,6 +1,11 @@
+import { sync } from './commands/apm/sync.js';
+import { validate } from './commands/apm/validate.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 === 'external') {
         return await runExternalTool(command, argv, {
             cwd: context.cwd,

package/dist/features/apm-release-validation/adapters/inbound/runApmReleaseCommandAsync.d.ts

@@ -0,0 +1,10 @@
+/*** Parse release CLI input and report the same structured validation result on every entrypoint. */
+export declare function runApmReleaseCommandAsync(operation: 'sync' | 'validate', argv: readonly string[], context: CommandContext): Promise<{
+    readonly exitCode: number;
+}>;
+interface CommandContext {
+    readonly cwd: string;
+    readonly writeStdout: (text: string) => void;
+    readonly writeStderr: (text: string) => void;
+}
+export {};

package/dist/features/apm-release-validation/adapters/inbound/runApmReleaseCommandAsync.js

@@ -0,0 +1,51 @@
+import { resolve } from 'node:path';
+import { synchronizeApmReleaseDescriptorAsync } from '../../composition/synchronizeApmReleaseDescriptorAsync.js';
+import { validatePackedApmReleaseAsync } from '../../composition/validatePackedApmReleaseAsync.js';
+/*** Parse release CLI input and report the same structured validation result on every entrypoint. */
+export async function runApmReleaseCommandAsync(operation, argv, context) {
+    try {
+        const { target, options } = parseArguments(operation, argv, context.cwd);
+        if (operation === 'sync') {
+            context.writeStdout(`${JSON.stringify({ changed: await synchronizeApmReleaseDescriptorAsync(target) })}\n`);
+            return { exitCode: 0 };
+        }
+        const result = await validatePackedApmReleaseAsync(target, options);
+        context.writeStdout(`${JSON.stringify(result)}\n`);
+        return { exitCode: result.valid ? 0 : 1 };
+    }
+    catch (error) {
+        context.writeStderr(`${error instanceof Error ? error.message : 'APM release validation failed.'}\n`);
+        return { exitCode: 1 };
+    }
+}
+/*** Separate release argument validation from execution; reject duplicates and incomplete flags. */
+function parseArguments(operation, argv, cwd) {
+    if (operation === 'sync' && argv.some((value) => value.startsWith('--')))
+        throw new Error('APM sync does not accept validation options.');
+    const artifactIndex = optionIndex(argv, '--artifact');
+    const integrityIndex = optionIndex(argv, '--expected-integrity');
+    const ignored = [artifactIndex, integrityIndex].flatMap((index) => index < 0 ? [] : [index, index + 1]);
+    const remaining = argv.filter((value, index) => !ignored.includes(index) && value !== '--allow-owner-code');
+    if (remaining.length > 1 || remaining.some((value) => value.startsWith('-')))
+        throw new Error('Expected one target directory and supported release options.');
+    const artifact = artifactIndex < 0 ? undefined : argv.at(artifactIndex + 1);
+    const integrity = integrityIndex < 0 ? undefined : argv.at(integrityIndex + 1);
+    return {
+        target: resolve(cwd, remaining.at(0) ?? '.'),
+        options: {
+            allowOwnerCode: argv.includes('--allow-owner-code'),
+            ...(artifact === undefined ? {} : { artifactPath: resolve(cwd, artifact) }),
+            ...(integrity === undefined ? {} : { expectedIntegrity: integrity }),
+        },
+    };
+}
+/*** Require a single option occurrence followed by a value. */
+function optionIndex(argv, option) {
+    const index = argv.indexOf(option);
+    if (index < 0)
+        return index;
+    const value = argv.at(index + 1);
+    if (argv.lastIndexOf(option) !== index || value === undefined || value.startsWith('--'))
+        throw new Error(`Invalid value for ${option}.`);
+    return index;
+}

package/dist/features/apm-release-validation/adapters/outbound/createApmReleaseDescriptorPort.d.ts

@@ -0,0 +1,3 @@
+import type { ApmReleaseDescriptorPort } from '../../../../types/apm-release-validation.js';
+/*** Supply bounded owner-document reads and idempotent writes for release synchronization. */
+export declare function createApmReleaseDescriptorPort(targetDirectory: string): ApmReleaseDescriptorPort;

package/dist/features/apm-release-validation/adapters/outbound/createApmReleaseDescriptorPort.js

@@ -0,0 +1,31 @@
+import { readFile, realpath, writeFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { resolvePathWithinRoot } from '@ankhorage/utility/node/path';
+import { format } from 'prettier';
+import { readApmReleaseManifestAsync } from './readApmReleaseManifestAsync.js';
+/*** Supply bounded owner-document reads and idempotent writes for release synchronization. */
+export function createApmReleaseDescriptorPort(targetDirectory) {
+    return {
+        readPackageAsync: () => readApmReleaseManifestAsync(resolve(targetDirectory, 'package.json')),
+        readDescriptorAsync: async (subpath) => readApmReleaseManifestAsync(await descriptorPathAsync(targetDirectory, subpath)),
+        writeDescriptorAsync: async (subpath, descriptor) => {
+            const path = await descriptorPathAsync(targetDirectory, subpath);
+            const before = await readFile(path, 'utf8');
+            const after = await format(JSON.stringify(descriptor), {
+                parser: 'json',
+                printWidth: 100,
+                tabWidth: 2,
+            });
+            if (before === after)
+                return false;
+            await writeFile(path, after, 'utf8');
+            return true;
+        },
+    };
+}
+/*** Prevent descriptor reads and writes from following paths or symlinks outside the owner root. */
+async function descriptorPathAsync(target, subpath) {
+    const root = await realpath(target);
+    const resolved = await realpath(resolvePathWithinRoot(root, subpath));
+    return resolvePathWithinRoot(root, relative(root, resolved));
+}

package/dist/features/apm-release-validation/adapters/outbound/inspectPackedApmReleaseCandidateAsync.d.ts

@@ -0,0 +1,3 @@
+import type { ApmReleaseValidationOptions, ApmReleaseValidationResult } from '../../../../types/apm-release-validation.js';
+/*** Validate the actual script-free packed candidate outside the checkout, retaining only accepted bytes. */
+export declare function inspectPackedApmReleaseCandidateAsync(targetDirectory: string, options?: ApmReleaseValidationOptions): Promise<ApmReleaseValidationResult>;

package/dist/features/apm-release-validation/adapters/outbound/inspectPackedApmReleaseCandidateAsync.js

@@ -0,0 +1,84 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { copyFile, mkdir, mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { relative, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { validatePackageUpdateMetadata, validateUpdateDescriptor } from '@ankhorage/apm';
+import { resolvePathWithinRoot } from '@ankhorage/utility/node/path';
+import { validateApmReleaseCandidate } from '../../application/validateApmReleaseCandidate.js';
+import { readApmReleaseMetadata } from '../../utils/readApmReleaseMetadata.js';
+import { probePackedApmExtensionAsync } from './probePackedApmExtensionAsync.js';
+import { readApmReleaseManifestAsync } from './readApmReleaseManifestAsync.js';
+/*** Validate the actual script-free packed candidate outside the checkout, retaining only accepted bytes. */
+export async function inspectPackedApmReleaseCandidateAsync(targetDirectory, options = {}) {
+    const root = await realpath(targetDirectory);
+    const temporaryRoot = await mkdtemp(resolve(tmpdir(), 'ankh-apm-release-'));
+    try {
+        const archive = resolve(temporaryRoot, 'candidate.tgz');
+        const packageRoot = resolve(temporaryRoot, 'package');
+        await packCandidateAsync(root, temporaryRoot, archive);
+        const candidate = await readPackedCandidateAsync(packageRoot, archive);
+        const result = await validatePackedCandidateAsync(candidate, packageRoot, root, options);
+        if (!result.valid || options.artifactPath === undefined)
+            return result;
+        const artifactPath = resolve(options.artifactPath);
+        if (artifactPath === archive)
+            throw new Error('Artifact output must survive temporary validation cleanup.');
+        await mkdir(resolve(artifactPath, '..'), { recursive: true });
+        await copyFile(archive, artifactPath, constants.COPYFILE_EXCL);
+        return { ...result, artifactPath };
+    }
+    finally {
+        await rm(temporaryRoot, { recursive: true, force: true });
+    }
+}
+/*** Build and extract only a script-free local package archive under a separate temporary root. */
+async function packCandidateAsync(root, temporaryRoot, archive) {
+    await execFileAsync('bun', ['pm', 'pack', '--filename', archive, '--ignore-scripts', '--quiet'], {
+        cwd: root,
+        ...PROCESS_LIMITS,
+    });
+    const { stdout } = await execFileAsync('tar', ['-tzf', archive], PROCESS_LIMITS);
+    for (const entry of stdout.trim().split('\n')) {
+        if (!entry.startsWith('package/'))
+            throw new Error('Packed file is outside the package prefix.');
+        resolvePathWithinRoot(temporaryRoot, entry);
+    }
+    await execFileAsync('tar', ['-xzf', archive, '-C', temporaryRoot, '--no-same-owner', '--no-same-permissions'], PROCESS_LIMITS);
+}
+/*** Read owner metadata strictly from the archive, not the source-tree descriptor. */
+async function readPackedCandidateAsync(packageRoot, archive) {
+    const integrity = `sha512-${createHash('sha512')
+        .update(await readFile(archive))
+        .digest('base64')}`;
+    const packageJson = await readApmReleaseManifestAsync(resolve(packageRoot, 'package.json'));
+    const discovery = validatePackageUpdateMetadata(readApmReleaseMetadata(packageJson));
+    if (!discovery.valid || discovery.metadata === undefined) {
+        return { packageJson, integrity, descriptor: undefined, descriptorSource: '' };
+    }
+    const descriptorPath = await realpath(resolvePathWithinRoot(packageRoot, discovery.metadata.descriptor));
+    resolvePathWithinRoot(packageRoot, relative(packageRoot, descriptorPath));
+    const descriptorSource = await readFile(descriptorPath, 'utf8');
+    const descriptor = JSON.parse(descriptorSource);
+    return { packageJson, descriptor, descriptorSource, integrity };
+}
+/*** Require valid static evidence before optionally loading the exact packed owner extension. */
+async function validatePackedCandidateAsync(candidate, packageRoot, root, options) {
+    const validation = validateUpdateDescriptor({ descriptor: candidate.descriptor });
+    const staticResult = validateApmReleaseCandidate(candidate, options);
+    const onlyExtensionMissing = staticResult.blockers.every((blocker) => blocker.startsWith('protocol.extension-binding-mismatch:'));
+    const extension = validation.descriptor?.extension;
+    return extension !== undefined && validation.valid && onlyExtensionMissing
+        ? probePackedApmExtensionAsync({
+            candidate,
+            packageRoot,
+            dependencyRoot: resolve(root, 'node_modules'),
+            subpath: extension.export,
+            options,
+        })
+        : staticResult;
+}
+const execFileAsync = promisify(execFile);
+const PROCESS_LIMITS = { timeout: 60_000, maxBuffer: 4 * 1024 * 1024 };

package/dist/features/apm-release-validation/adapters/outbound/probePackedApmExtensionAsync.d.ts

@@ -0,0 +1,11 @@
+import type { ApmPackedReleaseCandidate, ApmReleaseValidationOptions, ApmReleaseValidationResult } from '../../../../types/apm-release-validation.js';
+/*** Load the native public ESM export in a bounded child process only after explicit owner-code consent. */
+export declare function probePackedApmExtensionAsync(input: ProbeInput): Promise<ApmReleaseValidationResult>;
+interface ProbeInput {
+    readonly candidate: ApmPackedReleaseCandidate;
+    readonly packageRoot: string;
+    readonly dependencyRoot: string;
+    readonly subpath: string;
+    readonly options: ApmReleaseValidationOptions;
+}
+export {};

package/dist/features/apm-release-validation/adapters/outbound/probePackedApmExtensionAsync.js

@@ -0,0 +1,82 @@
+import { execFile } from 'node:child_process';
+import { readFile, symlink, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { isRecord } from '@ankhorage/utility/object';
+/*** Load the native public ESM export in a bounded child process only after explicit owner-code consent. */
+export async function probePackedApmExtensionAsync(input) {
+    if (input.options.allowOwnerCode !== true) {
+        return {
+            applicable: true,
+            valid: false,
+            integrity: input.candidate.integrity,
+            blockers: [
+                'release.owner-code-consent: Executable owner validation requires --allow-owner-code.',
+            ],
+        };
+    }
+    const { probePath, resultPath } = await prepareProbeAsync(input);
+    try {
+        await execFileAsync(process.execPath, [probePath], {
+            cwd: input.packageRoot,
+            timeout: 30_000,
+            maxBuffer: 1024 * 1024,
+            env: {
+                PATH: process.env.PATH,
+                SYSTEMROOT: process.env.SYSTEMROOT,
+                HOME: input.packageRoot,
+                TMPDIR: input.packageRoot,
+            },
+        });
+        return await readProbeResultAsync(input.candidate, resultPath);
+    }
+    catch {
+        return {
+            applicable: true,
+            valid: false,
+            integrity: input.candidate.integrity,
+            blockers: [
+                'release.extension-load: Packed public export failed to load or validate in the owner probe.',
+            ],
+        };
+    }
+}
+/*** Materialize a probe that uses native self-reference export resolution in the extracted package. */
+async function prepareProbeAsync(input) {
+    const requestPath = resolve(input.packageRoot, '.apm-release-request.json');
+    const resultPath = resolve(input.packageRoot, '.apm-release-result.json');
+    const probePath = resolve(input.packageRoot, '.apm-release-probe.mjs');
+    const specifier = `${String(input.candidate.packageJson.name)}${input.subpath.slice(1)}`;
+    await symlink(input.dependencyRoot, resolve(input.packageRoot, 'node_modules'), 'dir');
+    await writeFile(requestPath, JSON.stringify({ candidate: input.candidate, options: input.options }));
+    const validatorUrl = new URL('../../application/validateApmReleaseCandidate.js', import.meta.url)
+        .href;
+    await writeFile(probePath, [
+        "import { readFile, writeFile } from 'node:fs/promises';",
+        `import { validateApmReleaseCandidate } from ${JSON.stringify(validatorUrl)};`,
+        `const request = JSON.parse(await readFile(${JSON.stringify(requestPath)}, 'utf8'));`,
+        `const loaded = await import(${JSON.stringify(specifier)});`,
+        'const result = validateApmReleaseCandidate({ ...request.candidate, extension: loaded.default }, request.options);',
+        `await writeFile(${JSON.stringify(resultPath)}, JSON.stringify(result));`,
+    ].join('\n'));
+    return { probePath, resultPath };
+}
+/*** Validate child-process response data before exposing a structured report. */
+async function readProbeResultAsync(candidate, resultPath) {
+    const result = JSON.parse(await readFile(resultPath, 'utf8'));
+    if (!isRecord(result) ||
+        typeof result.valid !== 'boolean' ||
+        !Array.isArray(result.blockers) ||
+        !result.blockers.every((value) => typeof value === 'string')) {
+        throw new Error('Invalid owner probe response.');
+    }
+    return {
+        applicable: true,
+        valid: result.valid,
+        integrity: candidate.integrity,
+        packageName: String(candidate.packageJson.name),
+        packageVersion: String(candidate.packageJson.version),
+        blockers: result.blockers,
+    };
+}
+const execFileAsync = promisify(execFile);

package/dist/features/apm-release-validation/adapters/outbound/readApmReleaseManifestAsync.d.ts

@@ -0,0 +1,2 @@
+/*** Read a release-owned JSON object while rejecting malformed documents. */
+export declare function readApmReleaseManifestAsync(filePath: string): Promise<Readonly<Record<string, unknown>>>;

package/dist/features/apm-release-validation/adapters/outbound/readApmReleaseManifestAsync.js

@@ -0,0 +1,9 @@
+import { readFile } from 'node:fs/promises';
+import { isRecord } from '@ankhorage/utility/object';
+/*** Read a release-owned JSON object while rejecting malformed documents. */
+export async function readApmReleaseManifestAsync(filePath) {
+    const value = JSON.parse(await readFile(filePath, 'utf8'));
+    if (!isRecord(value))
+        throw new Error('APM release document must contain a JSON object.');
+    return value;
+}

package/dist/features/apm-release-validation/adapters/outbound/resolveApmReleaseCommandAsync.d.ts

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

package/dist/features/apm-release-validation/adapters/outbound/resolveApmReleaseCommandAsync.js

@@ -0,0 +1,18 @@
+import { resolve } from 'node:path';
+import { readApmReleaseManifestAsync } from './readApmReleaseManifestAsync.js';
+/*** Use Devtools' own built CLI for self-validation and the installed dependency binary in consumers. */
+export async function resolveApmReleaseCommandAsync(targetDirectory) {
+    try {
+        const manifest = await readApmReleaseManifestAsync(resolve(targetDirectory, 'package.json'));
+        return manifest.name === '@ankhorage/devtools'
+            ? 'node ./dist/cli/bin/apm-release.js'
+            : CONSUMER_COMMAND;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return CONSUMER_COMMAND;
+        }
+        throw error;
+    }
+}
+const CONSUMER_COMMAND = './node_modules/.bin/ankhorage-apm-release';

package/dist/features/apm-release-validation/application/synchronizeApmReleaseMetadataAsync.d.ts

@@ -0,0 +1,3 @@
+import type { ApmReleaseDescriptorPort } from '../../../types/apm-release-validation.js';
+/*** Bind valid owner metadata to the selected candidate version; never silently skip malformed opt-in. */
+export declare function synchronizeApmReleaseMetadataAsync(port: ApmReleaseDescriptorPort): Promise<boolean>;

package/dist/features/apm-release-validation/application/synchronizeApmReleaseMetadataAsync.js

@@ -0,0 +1,29 @@
+import { validatePackageUpdateMetadata, validateUpdateDescriptor } from '@ankhorage/apm';
+import { isRecord } from '@ankhorage/utility/object';
+import { readApmReleaseMetadata } from '../utils/readApmReleaseMetadata.js';
+/*** Bind valid owner metadata to the selected candidate version; never silently skip malformed opt-in. */
+export async function synchronizeApmReleaseMetadataAsync(port) {
+    const manifest = await port.readPackageAsync();
+    const metadata = readApmReleaseMetadata(manifest);
+    if (metadata === undefined)
+        return false;
+    const discovery = validatePackageUpdateMetadata(metadata);
+    if (!discovery.valid || discovery.metadata === undefined)
+        throw new Error('Invalid APM discovery metadata.');
+    const descriptor = await port.readDescriptorAsync(discovery.metadata.descriptor);
+    const { name, version } = manifest;
+    if (typeof name !== 'string' ||
+        typeof version !== 'string' ||
+        !isRecord(descriptor.owner) ||
+        descriptor.owner.name !== name) {
+        throw new Error('APM release descriptor must belong to the package being versioned.');
+    }
+    const synchronized = { ...descriptor, owner: { ...descriptor.owner, version } };
+    const validation = validateUpdateDescriptor({
+        descriptor: synchronized,
+        expectedOwner: { name, version },
+    });
+    if (!validation.valid)
+        throw new Error(validation.blockers.map(({ code, reason }) => `${code}: ${reason}`).join('\n'));
+    return port.writeDescriptorAsync(discovery.metadata.descriptor, synchronized);
+}

package/dist/features/apm-release-validation/application/validateApmReleaseCandidate.d.ts

@@ -0,0 +1,11 @@
+import type { ApmPackedReleaseCandidate, ApmReleaseValidationOptions, ApmReleaseValidationResult } from '../../../types/apm-release-validation.js';
+/*** Validate packed owner evidence using the released APM protocol, never a copied schema.
+ * Opt-in packages declare ankh.apm with protocolVersion and a package-relative descriptor.
+ * No metadata means not applicable, not a claim that no migration is needed. The descriptor
+ * declares supported no-migration, required migration, or unsupported/manual history explicitly.
+ * Previous descriptors enforce immutable migration checksums and related descriptors validate
+ * cross-owner prerequisites. Package-owned source-to-target tests must also cover skipped versions,
+ * idempotency, interruption/recovery, and unsupported historical states.
+ * @readme
+ */
+export declare function validateApmReleaseCandidate(candidate: ApmPackedReleaseCandidate, options?: ApmReleaseValidationOptions): ApmReleaseValidationResult;

package/dist/features/apm-release-validation/application/validateApmReleaseCandidate.js

@@ -0,0 +1,76 @@
+import { createHash } from 'node:crypto';
+import { validatePackageUpdateMetadata, validateUpdateDescriptor, validateUpdateExtensionBinding, validateUpdateExtensionCapabilities, } from '@ankhorage/apm';
+import { readApmReleaseMetadata } from '../utils/readApmReleaseMetadata.js';
+/*** Validate packed owner evidence using the released APM protocol, never a copied schema.
+ * Opt-in packages declare ankh.apm with protocolVersion and a package-relative descriptor.
+ * No metadata means not applicable, not a claim that no migration is needed. The descriptor
+ * declares supported no-migration, required migration, or unsupported/manual history explicitly.
+ * Previous descriptors enforce immutable migration checksums and related descriptors validate
+ * cross-owner prerequisites. Package-owned source-to-target tests must also cover skipped versions,
+ * idempotency, interruption/recovery, and unsupported historical states.
+ * @readme
+ */
+export function validateApmReleaseCandidate(candidate, options = {}) {
+    const { name, version } = candidate.packageJson;
+    const identity = {
+        ...(typeof name === 'string' ? { packageName: name } : {}),
+        ...(typeof version === 'string' ? { packageVersion: version } : {}),
+        integrity: candidate.integrity,
+    };
+    const metadata = readApmReleaseMetadata(candidate.packageJson);
+    const integrityBlockers = options.expectedIntegrity !== undefined && options.expectedIntegrity !== candidate.integrity
+        ? ['release.integrity-mismatch: Packed bytes differ from the selected release artifact.']
+        : [];
+    if (metadata === undefined) {
+        return {
+            ...identity,
+            applicable: false,
+            valid: integrityBlockers.length === 0,
+            blockers: integrityBlockers,
+        };
+    }
+    const metadataValidation = validatePackageUpdateMetadata(metadata);
+    if (typeof name !== 'string' || !name || typeof version !== 'string' || !version) {
+        return result(identity, ['release.identity: Package must define name and exact version.']);
+    }
+    if (!metadataValidation.valid)
+        return result(identity, [...integrityBlockers, ...messages(metadataValidation.blockers)]);
+    const validation = validateUpdateDescriptor({
+        descriptor: candidate.descriptor,
+        expectedOwner: { name, version },
+        previousDescriptors: options.previousDescriptors,
+        relatedDescriptors: options.relatedDescriptors,
+    });
+    if (!validation.valid || validation.descriptor === undefined || integrityBlockers.length > 0) {
+        return result(identity, [...integrityBlockers, ...messages(validation.blockers)]);
+    }
+    return result(identity, extensionBlockers(candidate, validation.descriptor));
+}
+/*** Validate executable binding and required handlers after static metadata has passed. */
+function extensionBlockers(candidate, descriptor) {
+    if (descriptor.extension === undefined)
+        return [];
+    const artifact = {
+        role: 'target',
+        packageName: descriptor.owner.name,
+        version: descriptor.owner.version,
+        integrity: candidate.integrity,
+        descriptorDigest: createHash('sha256').update(candidate.descriptorSource).digest('hex'),
+    };
+    if (!isBoundExtension(artifact, candidate.extension)) {
+        return messages(validateUpdateExtensionBinding(artifact, candidate.extension));
+    }
+    return messages(validateUpdateExtensionCapabilities(descriptor, artifact, candidate.extension));
+}
+/*** Narrow unknown executable evidence only after the canonical runtime validator accepts it. */
+function isBoundExtension(artifact, value) {
+    return validateUpdateExtensionBinding(artifact, value).length === 0;
+}
+/*** Preserve structured candidate identity and canonical blocker reasons. */
+function result(identity, blockers) {
+    return { ...identity, applicable: true, valid: blockers.length === 0, blockers };
+}
+/*** Render the protocol's own diagnostics without reinterpreting their semantics. */
+function messages(blockers) {
+    return blockers.map(({ code, reason }) => `${code}: ${reason}`);
+}

package/dist/features/apm-release-validation/composition/synchronizeApmReleaseDescriptorAsync.d.ts

@@ -0,0 +1,2 @@
+/*** Compose descriptor version synchronization with the bounded Node filesystem adapter. */
+export declare function synchronizeApmReleaseDescriptorAsync(targetDirectory: string): Promise<boolean>;

package/dist/features/apm-release-validation/composition/synchronizeApmReleaseDescriptorAsync.js

@@ -0,0 +1,6 @@
+import { createApmReleaseDescriptorPort } from '../adapters/outbound/createApmReleaseDescriptorPort.js';
+import { synchronizeApmReleaseMetadataAsync } from '../application/synchronizeApmReleaseMetadataAsync.js';
+/*** Compose descriptor version synchronization with the bounded Node filesystem adapter. */
+export async function synchronizeApmReleaseDescriptorAsync(targetDirectory) {
+    return synchronizeApmReleaseMetadataAsync(createApmReleaseDescriptorPort(targetDirectory));
+}

package/dist/features/apm-release-validation/composition/validatePackedApmReleaseAsync.d.ts

@@ -0,0 +1,12 @@
+import type { ApmReleaseValidationOptions, ApmReleaseValidationResult } from '../../../types/apm-release-validation.js';
+/*** Validate script-free publish bytes and optionally retain that exact accepted archive.
+ * Release order is APM protocol, package-owner metadata/code, then consuming applications.
+ * Build after Changesets versioning and descriptor synchronization. Execute package-owned
+ * acceptance tests, then validate with explicit owner-code consent. The child probe uses the
+ * packed package's native public export resolution and installed dependencies, not omitted source.
+ * Consent permits trusted executable code; a child process is not a security sandbox.
+ * An artifactPath retains accepted bytes exclusively, so publication need not repack or rerun
+ * lifecycle scripts. expectedIntegrity rejects a stale candidate before any owner code loads.
+ * @readme
+ */
+export declare function validatePackedApmReleaseAsync(targetDirectory: string, options?: ApmReleaseValidationOptions): Promise<ApmReleaseValidationResult>;

package/dist/features/apm-release-validation/composition/validatePackedApmReleaseAsync.js

@@ -0,0 +1,14 @@
+import { inspectPackedApmReleaseCandidateAsync } from '../adapters/outbound/inspectPackedApmReleaseCandidateAsync.js';
+/*** Validate script-free publish bytes and optionally retain that exact accepted archive.
+ * Release order is APM protocol, package-owner metadata/code, then consuming applications.
+ * Build after Changesets versioning and descriptor synchronization. Execute package-owned
+ * acceptance tests, then validate with explicit owner-code consent. The child probe uses the
+ * packed package's native public export resolution and installed dependencies, not omitted source.
+ * Consent permits trusted executable code; a child process is not a security sandbox.
+ * An artifactPath retains accepted bytes exclusively, so publication need not repack or rerun
+ * lifecycle scripts. expectedIntegrity rejects a stale candidate before any owner code loads.
+ * @readme
+ */
+export async function validatePackedApmReleaseAsync(targetDirectory, options = {}) {
+    return inspectPackedApmReleaseCandidateAsync(targetDirectory, options);
+}

package/dist/features/apm-release-validation/utils/readApmReleaseMetadata.d.ts

@@ -0,0 +1,2 @@
+/*** Read opt-in owner metadata without copying the APM discovery schema. */
+export declare function readApmReleaseMetadata(manifest: Readonly<Record<string, unknown>>): unknown;

package/dist/features/apm-release-validation/utils/readApmReleaseMetadata.js

@@ -0,0 +1,6 @@
+import { isRecord, readOwnProperty } from '@ankhorage/utility/object';
+/*** Read opt-in owner metadata without copying the APM discovery schema. */
+export function readApmReleaseMetadata(manifest) {
+    const ankh = readOwnProperty(manifest, 'ankh');
+    return isRecord(ankh) ? readOwnProperty(ankh, 'apm') : undefined;
+}

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

@@ -41,6 +41,13 @@ jobs:
             echo "No build script found; skipping."
           fi
 
+      - name: Validate opted-in APM owner release
+        run: |
+          if node -e "const p=require('./package.json'); process.exit(p.ankh?.apm === undefined ? 1 : 0)"; then
+            bun run test:apm
+            __ANKH_APM_RELEASE_COMMAND__ validate . --allow-owner-code
+          fi
+
       - name: Validate Ankhorage repository
         run: bunx @ankhorage/ankh doctor validate .
 

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

@@ -73,6 +73,9 @@ jobs:
 
           before_version="$(node -p "require('./package.json').version")"
           __ANKH_CHANGESETS_VERSION_COMMAND__
+          if node -e "const p=require('./package.json'); process.exit(p.ankh?.apm === undefined ? 1 : 0)"; then
+            __ANKH_APM_RELEASE_COMMAND__ sync .
+          fi
           after_version="$(node -p "require('./package.json').version")"
 
           if git diff --quiet; then
@@ -100,7 +103,30 @@ jobs:
 
       - name: Publish unpublished packages
         if: hashFiles('.changeset/config.json') != ''
-        run: __ANKH_CHANGESETS_PUBLISH_COMMAND__
+        run: |
+          if ! node -e "const p=require('./package.json'); process.exit(p.ankh?.apm === undefined ? 1 : 0)"; then
+            __ANKH_CHANGESETS_PUBLISH_COMMAND__
+            exit 0
+          fi
+
+          package_name="$(node -p "require('./package.json').name")"
+          package_version="$(node -p "require('./package.json').version")"
+          registry_evidence="${RUNNER_TEMP}/apm-registry.json"
+          if npm view "${package_name}@${package_version}" version --json > "$registry_evidence"; then
+            echo "Exact APM owner version is already published."
+          else
+            # Authentication/network errors must never be treated as an unpublished version.
+            node -e "const p=require(process.argv[1]); if(p.error?.code !== 'E404') process.exit(1)" "$registry_evidence"
+            bun install --frozen-lockfile --ignore-scripts
+            bun run build
+            bun run test:apm
+            artifact="$(mktemp -d "${RUNNER_TEMP}/apm-publish.XXXXXX")/candidate.tgz"
+            __ANKH_APM_RELEASE_COMMAND__ validate . --allow-owner-code --artifact "$artifact"
+            npm publish "$artifact" --ignore-scripts
+          fi
+          if ! git rev-parse -q --verify "refs/tags/v${package_version}" >/dev/null; then
+            git tag "v${package_version}"
+          fi
 
       - name: Finalize Changesets v3 tags and GitHub releases
         if: hashFiles('.changeset/config.json') != ''

package/dist/tools/workflows/index.js

@@ -1,5 +1,6 @@
 import { access } from 'node:fs/promises';
 import { join } from 'node:path';
+import { resolveApmReleaseCommandAsync } from '../../features/apm-release-validation/adapters/outbound/resolveApmReleaseCommandAsync.js';
 import { bunRuntimePolicy, nodeRuntimePolicy } from '../../policy/bunRuntimePolicy.js';
 import { renderRenovateWorkflowAsync } from './renderRenovateWorkflowAsync.js';
 import { renderWorkflowAsync } from './renderWorkflowAsync.js';
@@ -30,7 +31,8 @@ function createWorkflowDefinition(relativePath, sourcePath) {
     const sourceUrl = new URL(sourcePath, import.meta.url);
     return {
         relativePath,
-        render: async () => await renderWorkflowAsync(sourceUrl, {
+        render: async (targetDirectory) => await renderWorkflowAsync(sourceUrl, {
+            apmReleaseCommand: await resolveApmReleaseCommandAsync(targetDirectory),
             bunVersion: bunRuntimePolicy.version,
             nodeVersion: nodeRuntimePolicy.setupVersion,
         }),
@@ -42,6 +44,7 @@ function createRenovateWorkflowDefinition() {
     return {
         relativePath: '.github/workflows/renovate.yml',
         render: async (targetDirectory) => await renderRenovateWorkflowAsync(sourceUrl, targetDirectory, {
+            apmReleaseCommand: await resolveApmReleaseCommandAsync(targetDirectory),
             bunVersion: bunRuntimePolicy.version,
             nodeVersion: nodeRuntimePolicy.setupVersion,
         }),

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

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

package/dist/tools/workflows/renderWorkflowAsync.js

@@ -8,6 +8,7 @@ export async function renderWorkflowAsync(sourceUrl, policy) {
         .replaceAll(CHANGESETS_PUBLISH_COMMAND_TOKEN, changesetsPolicy.workflowCommands.publish)
         .replaceAll(CHANGESETS_STATUS_COMMAND_TOKEN, changesetsPolicy.workflowCommands.status)
         .replaceAll(CHANGESETS_VERSION_COMMAND_TOKEN, changesetsPolicy.workflowCommands.version)
+        .replaceAll('__ANKH_APM_RELEASE_COMMAND__', policy.apmReleaseCommand ?? './node_modules/.bin/ankhorage-apm-release')
         .replaceAll(NODE_VERSION_TOKEN, policy.nodeVersion);
 }
 const BUN_VERSION_TOKEN = '__ANKH_BUN_VERSION__';

package/dist/types/apm-release-validation.d.ts

@@ -0,0 +1,33 @@
+import type { ApmUpdateDescriptor } from '@ankhorage/apm/types';
+/*** Packed bytes and loaded owner evidence supplied to the canonical APM validators. */
+export interface ApmPackedReleaseCandidate {
+    readonly packageJson: Readonly<Record<string, unknown>>;
+    readonly descriptor: unknown;
+    readonly descriptorSource: string;
+    readonly integrity: string;
+    readonly extension?: unknown;
+}
+/*** Explicit release-validation inputs; owner code is never trusted by default. */
+export interface ApmReleaseValidationOptions {
+    readonly allowOwnerCode?: boolean;
+    readonly artifactPath?: string;
+    readonly expectedIntegrity?: string;
+    readonly previousDescriptors?: readonly ApmUpdateDescriptor[];
+    readonly relatedDescriptors?: readonly ApmUpdateDescriptor[];
+}
+/*** Evidence for one exact packed release; inapplicable never means migration-safe. */
+export interface ApmReleaseValidationResult {
+    readonly applicable: boolean;
+    readonly valid: boolean;
+    readonly packageName?: string;
+    readonly packageVersion?: string;
+    readonly integrity?: string;
+    readonly artifactPath?: string;
+    readonly blockers: readonly string[];
+}
+/*** Filesystem capabilities required by descriptor synchronization, independent of transport. */
+export interface ApmReleaseDescriptorPort {
+    readonly readPackageAsync: () => Promise<Readonly<Record<string, unknown>>>;
+    readonly readDescriptorAsync: (subpath: string) => Promise<Readonly<Record<string, unknown>>>;
+    readonly writeDescriptorAsync: (subpath: string, descriptor: Readonly<Record<string, unknown>>) => Promise<boolean>;
+}

package/dist/types/apm-release-validation.js

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

package/dist/types/public.d.ts

@@ -0,0 +1 @@
+export type { ApmPackedReleaseCandidate, ApmReleaseValidationOptions, ApmReleaseValidationResult, } from './apm-release-validation.js';

package/dist/types/public.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.14.8",
+  "version": "1.15.0",
   "description": "Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -19,6 +19,8 @@
     "category": "devtools",
     "provider": "./dist/cli/index.js",
     "capabilities": [
+      "devtools.apm.sync",
+      "devtools.apm.validate",
       "devtools.changeset",
       "devtools.lint",
       "devtools.format",
@@ -60,7 +62,8 @@
     "ankhorage-changeset": "./dist/cli/bin/changeset.js",
     "ankhorage-eslint": "./dist/cli/bin/eslint.js",
     "ankhorage-knip": "./dist/cli/bin/knip.js",
-    "ankhorage-prettier": "./dist/cli/bin/prettier.js"
+    "ankhorage-prettier": "./dist/cli/bin/prettier.js",
+    "ankhorage-apm-release": "./dist/cli/bin/apm-release.js"
   },
   "exports": {
     "./cli": {
@@ -83,6 +86,14 @@
       "import": "./dist/tools/prettier/index.cjs",
       "require": "./dist/tools/prettier/index.cjs",
       "default": "./dist/tools/prettier/index.cjs"
+    },
+    "./apm-release": {
+      "types": "./dist/apmRelease.d.ts",
+      "import": "./dist/apmRelease.js"
+    },
+    "./types": {
+      "types": "./dist/types/public.d.ts",
+      "import": "./dist/types/public.js"
     }
   },
   "files": [
@@ -93,7 +104,7 @@
   ],
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc && mkdir -p dist/tools/prettier dist/tools/workflows dist/tools/vscode dist/tools/skills && cp src/tools/prettier/index.cjs dist/tools/prettier/index.cjs && cp -R src/tools/workflows/files dist/tools/workflows/files && cp -R src/tools/vscode/files dist/tools/vscode/files && cp -R src/tools/skills/assets dist/tools/skills/assets",
-    "typecheck": "bun x tsc --noEmit -p tsconfig.test.json",
+    "typecheck": "bun run check-types",
     "doctor": "ankhorage-doctor validate .",
     "knip:check": "knip",
     "lint": "eslint .",
@@ -105,9 +116,11 @@
     "test": "bun test",
     "changeset": "bun src/cli/bin/changeset.ts",
     "changeset:status": "bun src/cli/bin/changeset.ts status --since=origin/main",
-    "version-packages": "bun src/cli/bin/changeset.ts version"
+    "version-packages": "bun src/cli/bin/changeset.ts version",
+    "check-types": "bun x tsc --noEmit -p tsconfig.test.json"
   },
   "dependencies": {
+    "@ankhorage/apm": "^0.6.0",
     "@ankhorage/project-detector": "^0.1.0",
     "@ankhorage/utility": "^0.5.1",
     "@changesets/cli": "^3.0.2",