@ankhorage/devtools 1.14.7 → 1.15.0

package/README.md

@@ -1,4 +1,13 @@
-# devtools
+<!-- markdownlint-disable MD013 MD033 -->
+<!-- This file is generated by Paradox. Do not edit manually. -->
+
+# @ankhorage/devtools
+
+![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
+
+## Usage
 
 Shared development tools and repository standards for Ankhorage TypeScript projects.
 
@@ -59,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`
@@ -204,7 +215,7 @@ Agent Skill scripts are always TypeScript files with a `.ts` extension and run w
 
 `createConfig()` defaults to `profile: 'auto'`.
 
-Automatic detection reads the consuming repository's `package.json` and delegates project trait detection to `@ankhorage/utility/project`. Dependency signals are considered across `dependencies`, `devDependencies`, and `peerDependencies`.
+Automatic detection reads the consuming repository's `package.json` and delegates project trait detection to `@ankhorage/project-detector`. Dependency signals are considered across `dependencies`, `devDependencies`, and `peerDependencies`.
 
 Profile precedence is:
 
@@ -375,3 +386,149 @@ A new concern should:
 4. add provider commands under `ankh devtools`
 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.
+
+`ankh devtools changeset`, `ankh devtools lint`, `ankh devtools format`, and
+`ankh devtools knip` execute the bundled Changesets, ESLint, Prettier, and Knip versions.
+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.
+
+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,
+unrelated repository-local skills and create-only local extension files remain repository-owned,
+and package metadata is merge-updated without replacing unrelated fields.
+
+Fresh repositories can bootstrap the standard setup with `ankh devtools sync .` after adding
+`@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
+bunx @ankhorage/devtools ankhorage-prettier
+```
+
+## Generated documentation
+
+- [Interactive documentation app](././paradox/index.html)
+- [Public API reference](././paradox/exports.md)
+- [Component registry](././paradox/components.md)
+- [Architecture overview](././paradox/diagrams/architecture-overview.mmd)
+- [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>>>;