@ankhorage/devtools 1.14.8 → 1.15.1

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/agents/index.js

@@ -11,6 +11,13 @@ async function renderAgentsFile(targetDirectory) {
     const manifest = await readPackageManifest(targetDirectory);
     const packageName = readNonEmptyString(manifest.name) ?? 'Package name not declared';
     const description = readNonEmptyString(manifest.description) ?? 'No package description is declared.';
+    const sections = [
+        renderCurrentArchitectureInstructions(),
+        renderRequiredRepositoryInstructions(),
+        renderDocumentationInstructions(),
+        renderPullRequestInstructions(),
+        renderSkillScriptInstructions(),
+    ].join('');
     return `# AGENTS.md
 
 <!-- This file is managed by @ankhorage/devtools. -->
@@ -21,7 +28,11 @@ Package: \`${escapeInlineCode(packageName)}\`
 
 ${description}
 
-## Current architecture only
+${sections}`;
+}
+/*** Render the current-architecture policy shared by every managed repository. */
+function renderCurrentArchitectureInstructions() {
+    return `## Current architecture only
 
 Only the current Ankhorage architecture is valid. Do not add or retain deprecated APIs,
 compatibility aliases, shims, dual old/new paths, historical-state fallbacks, or migrations whose
@@ -34,27 +45,47 @@ published public APIs and declared dependencies, never sibling source files.
 Current-runtime error handling and canonical database or infrastructure migrations remain valid
 when they support states that the current architecture can intentionally produce.
 
-## Required repository instructions
+`;
+}
+/*** Render contextual repository skill-selection requirements. */
+function renderRequiredRepositoryInstructions() {
+    return `## Required repository instructions
 
 Before changing any file, read this \`AGENTS.md\` completely and inspect \`.agents/skills/\`.
-For every change, load and follow both baseline repository skills before making changes:
+Treat skill selection as a mandatory precondition to editing, then follow every selected skill
+through validation and delivery.
+
+- Load \`.agents/skills/ankhorage-coding-rules/SKILL.md\` for implementation, refactoring, testing,
+  review, or pull-request delivery work.
+- Load \`.agents/skills/ankhorage-project-structure/SKILL.md\` when the task changes or reviews
+  directory ownership, package boundaries, public entrypoints, cross-repository ownership, type or
+  utility placement, or source architecture.
+- Load every additional repository-local skill whose description or requirements match the task,
+  including skills required by any selected skill. These rules define mandatory minimums, not an
+  allow-list; do not skip a useful relevant skill merely because it is not named here.
+
+Do not load unrelated skills merely because they are installed. If the task scope expands, inspect
+\`.agents/skills/\` again and load the newly relevant skills before continuing. Do not substitute
+remembered, globally installed, or generic guidance for the repository-local versions.
 
-1. \`.agents/skills/ankhorage-coding-rules/SKILL.md\`
-2. \`.agents/skills/ankhorage-project-structure/SKILL.md\`
-
-Load and follow every additional repository-local skill relevant to the task, including skills
-required by either baseline skill. Continue to follow these instructions and skills through
-validation and delivery; do not substitute remembered, globally installed, or generic guidance for
-the repository-local versions.
-
-## Documentation
+`;
+}
+/*** Render the release-owned generated documentation policy. */
+function renderDocumentationInstructions() {
+    return `## Documentation
 
-\`README.md\` and the \`paradox/\` documentation tree are generated by \`@ankhorage/paradox\`.
-Never edit generated documentation directly. Update the owning Paradox \`/*** ... */\` comments in
-\`src\`, including \`@readme\` tags where the content belongs in the README, then run \`bun docs\`
-and commit the regenerated artifacts.
+\`README.md\` and the configured Paradox output are generated release artifacts. Never edit them
+manually, and do not regenerate or commit them in ordinary feature pull requests. Update the owning
+Paradox \`/*** ... */\` comments in \`src\` and leading \`@usage\` comments in real
+\`examples/<example>/...\` source files, plus any repository-owned manual documentation outside the
+generated output. The managed release workflow runs \`bun run docs\` after the package version bump
+and commits the regenerated artifacts in the release commit.
 
-## Pull requests
+`;
+}
+/*** Render canonical pull-request validation commands. */
+function renderPullRequestInstructions() {
+    return `## Pull requests
 
 Before creating a pull request, run all of these commands in this order and resolve every failure:
 
@@ -67,13 +98,18 @@ bun run changeset
 bun run format
 \`\`\`
 
-## Skill scripts
+`;
+}
+/*** Render the repository rule for executable Agent Skill scripts. */
+function renderSkillScriptInstructions() {
+    return `## Skill scripts
 
 Scripts inside an Agent Skill must always be TypeScript files with the \`.ts\` extension.
 JavaScript skill scripts using \`.js\`, \`.mjs\`, or \`.cjs\` are not allowed. Run TypeScript
 skill scripts with Bun.
 `;
 }
+/*** Read the target package manifest used to personalize managed repository instructions. */
 async function readPackageManifest(targetDirectory) {
     try {
         const contents = await readFile(resolve(targetDirectory, 'package.json'), 'utf8');
@@ -90,15 +126,19 @@ async function readPackageManifest(targetDirectory) {
         throw error;
     }
 }
+/*** Escape inline-code delimiters before interpolating repository metadata into Markdown. */
 function escapeInlineCode(value) {
     return value.replaceAll('`', '\\`');
 }
+/*** Check whether an unknown failure carries a Node.js error code. */
 function isNodeError(error) {
     return error instanceof Error && 'code' in error;
 }
+/*** Check whether an unknown value is a plain record-shaped object. */
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/*** Read and trim a non-empty string value from package metadata. */
 function readNonEmptyString(value) {
     return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
 }

package/dist/tools/gitignore/index.d.ts

@@ -0,0 +1,10 @@
+export declare const gitignoreManagedFiles: readonly [{
+    readonly relativePath: ".gitignore";
+    readonly render: typeof renderGitignore;
+    readonly isApplicable: typeof isGitignorePresent;
+}];
+/*** Preserve repository-owned ignore rules while keeping documentation directories trackable. */
+declare function renderGitignore(targetDirectory: string): Promise<string>;
+/*** Report whether a repository already owns a `.gitignore` file that can be normalized. */
+declare function isGitignorePresent(targetDirectory: string): Promise<boolean>;
+export {};

package/dist/tools/gitignore/index.js

@@ -0,0 +1,43 @@
+import { access, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+const TRACKED_DOCUMENTATION_PATTERNS = new Set([
+    'docs',
+    'docs/',
+    '/docs',
+    '/docs/',
+    'paradox',
+    'paradox/',
+    '/paradox',
+    '/paradox/',
+]);
+export const gitignoreManagedFiles = [
+    {
+        relativePath: '.gitignore',
+        render: renderGitignore,
+        isApplicable: isGitignorePresent,
+    },
+];
+/*** Preserve repository-owned ignore rules while keeping documentation directories trackable. */
+async function renderGitignore(targetDirectory) {
+    const contents = await readFile(resolve(targetDirectory, '.gitignore'), 'utf8');
+    return contents
+        .split('\n')
+        .filter((line) => !TRACKED_DOCUMENTATION_PATTERNS.has(line.trim()))
+        .join('\n');
+}
+/*** Report whether a repository already owns a `.gitignore` file that can be normalized. */
+async function isGitignorePresent(targetDirectory) {
+    try {
+        await access(resolve(targetDirectory, '.gitignore'));
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/*** Check whether an unknown failure carries a Node.js error code. */
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}

package/dist/tools/skills/assets/ankhorage-coding-rules/SKILL.md

@@ -45,6 +45,31 @@ exceptions or replaced by generic preferences from this skill.
 - Keep one canonical implementation. Do not add compatibility aliases, dual paths, historical-state
   fallbacks, or sibling-source imports.
 
+## Comments and Paradox documentation
+
+- Give every named production function under `src` a concise Paradox `/*** ... */` comment,
+  including exported functions and internal named helpers. Inline callbacks are exempt.
+- Use ordinary inline comments when they explain non-obvious intent, invariants, constraints, or the
+  reason behind a decision. Do not narrate self-explanatory code or duplicate what names and types
+  already express.
+- Paradox documentation metadata belongs only inside `/*** ... */` comments. Use only supported
+  Paradox tags: `@readme`, `@config`, `@example`, and `@usage`. Do not use JSDoc-only tags such as
+  `@param` or `@returns` as Paradox metadata.
+- Add a supported Paradox tag only when it changes or usefully enriches generated documentation;
+  plain function descriptions do not need tags.
+- README usage documentation must come from a real repository-root `examples/<example>/...` source
+  file. Put `@usage` in that example file's leading `/*** ... */` comment so Paradox promotes the
+  runnable example into the README Usage section. Do not create dedicated `readme-usage`,
+  `usage-readme`, `readmeUsage`, or equivalent source modules whose only purpose is feeding README
+  usage text.
+- Update documentation sources in the pull request, including repository-owned manual documentation
+  outside the configured generated output. Never hand-edit generated README or Paradox artifacts.
+- Generated documentation is release-owned. Ordinary feature pull requests must not regenerate or
+  commit `README.md` or the configured Paradox output. The managed release workflow runs
+  `bun run docs` after the package version bump and commits the result in the release commit.
+- Run `bun run docs` locally only when the task explicitly changes or validates Paradox generation;
+  do not commit that generated diff from an ordinary feature pull request.
+
 ## Testing
 
 - Test observable behavior at the owning boundary. Keep tests deterministic and independent of
@@ -60,15 +85,6 @@ exceptions or replaced by generic preferences from this skill.
   full reruns without a substantive code or configuration change, stop cycling, inspect logs and
   artifacts, and report the blocker.
 
-## Paradox documentation
-
-- Give every named production function under `src` a concise Paradox `/*** ... */` description,
-  including internal helpers. Inline callbacks are exempt.
-- Add `@param`, `@returns`, `@example`, or `@readme` to public APIs only when the tag adds useful
-  information.
-- Update documentation sources and regenerate tracked Paradox output. Never hand-edit generated
-  README or Paradox artifacts.
-
 ## Public API and release quality
 
 - Export public symbols intentionally from canonical entrypoints and exercise those exports in
@@ -77,7 +93,8 @@ exceptions or replaced by generic preferences from this skill.
   public API changes.
 - Justify new dependencies and keep generated artifacts, lockfiles, and package metadata aligned
   with the repository's owning workflows.
-- Review the final diff, then run the applicable build, lint, test, typecheck, Knip, format, docs,
-  changeset-status, and packaging checks.
+- Review the final diff, then run the applicable build, lint, test, typecheck, Knip, format,
+  changeset-status, and packaging checks. Run documentation generation only when explicitly needed
+  to validate documentation tooling behavior.
 - Report the exact commands run and any omissions or failures. Do not imply a fully green handoff
   when a required check did not run or pass.

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,8 +73,19 @@ 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 [ "$before_version" != "$after_version" ]; then
+            if node -e "const p=require('./package.json'); process.exit(p.scripts?.docs ? 0 : 1)"; then
+              bun run docs
+            else
+              echo "No docs script found; skipping."
+            fi
+          fi
+
           if git diff --quiet; then
             echo "versioned=false" >> "$GITHUB_OUTPUT"
             exit 0
@@ -100,7 +111,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 {};