agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/registries/verbosityBudgetContract.js

@@ -0,0 +1,205 @@
+import path from "node:path";
+import { loadYamlMappingFile } from "../core/yaml.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { ARTIFACT_PROTOCOL_PATHS, normalizeArtifactProtocolId, } from "./artifactProtocolIds.js";
+export class VerbosityBudgetContractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VerbosityBudgetContractError";
+    }
+}
+export function verbosityBudgetAuthorityPath() {
+    return path.join(resolveSourceRoot(), "references", "artifacts", "verbosity-budget-authority.yaml");
+}
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function positiveNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function readMapping(filePath, label) {
+    try {
+        return loadYamlMappingFile(filePath);
+    }
+    catch (error) {
+        throw new VerbosityBudgetContractError(`${label} ${filePath} is unreadable or malformed: ${error.message}`);
+    }
+}
+function loadContract(contractPath) {
+    const contract = readMapping(contractPath, "verbosity budget authority");
+    if (contract.schema_version !== "agentera.verbosityBudgetAuthority.v1") {
+        throw new VerbosityBudgetContractError(`verbosity budget authority ${contractPath} has unsupported schema_version`);
+    }
+    const authority = mapping(contract.authority);
+    const scope = mapping(contract.scope);
+    const supported = scope?.supported_artifacts;
+    if (!authority || typeof authority.schema_directory !== "string" || !Array.isArray(supported)) {
+        throw new VerbosityBudgetContractError(`verbosity budget authority ${contractPath} must declare authority.schema_directory and scope.supported_artifacts`);
+    }
+    const schemaDirectory = path.resolve(path.dirname(contractPath), authority.schema_directory);
+    const owners = new Map();
+    for (const raw of supported) {
+        const entry = mapping(raw);
+        const artifactId = entry?.artifact_id;
+        const schema = entry?.schema;
+        if (typeof artifactId !== "string" || normalizeArtifactProtocolId(artifactId) !== artifactId) {
+            throw new VerbosityBudgetContractError(`verbosity budget authority ${contractPath} contains an invalid artifact_id`);
+        }
+        if (typeof schema !== "string" || !schema.endsWith(".yaml") || path.basename(schema) !== schema) {
+            throw new VerbosityBudgetContractError(`verbosity budget authority ${contractPath} contains an invalid schema owner for ${artifactId}`);
+        }
+        if (owners.has(artifactId)) {
+            throw new VerbosityBudgetContractError(`verbosity budget authority ${contractPath} declares ambiguous owners for ${artifactId}`);
+        }
+        owners.set(artifactId, {
+            artifactId,
+            authorityPath: contractPath,
+            schemaPath: path.join(schemaDirectory, schema),
+        });
+    }
+    if (owners.size === 0) {
+        throw new VerbosityBudgetContractError(`verbosity budget authority ${contractPath} declares no supported artifacts`);
+    }
+    return { contractPath, owners };
+}
+function protocolIdForOwner(input) {
+    const normalized = normalizeArtifactProtocolId(input);
+    if (normalized)
+        return normalized;
+    const comparable = input.trim().replaceAll("\\", "/").toLowerCase();
+    for (const [artifactId, artifactPath] of Object.entries(ARTIFACT_PROTOCOL_PATHS)) {
+        const canonicalPath = artifactPath.toLowerCase();
+        if (comparable === canonicalPath || comparable === path.posix.basename(canonicalPath)) {
+            return artifactId;
+        }
+    }
+    return null;
+}
+export function resolveVerbosityBudgetOwner(artifact, contractPath = verbosityBudgetAuthorityPath()) {
+    const contract = loadContract(contractPath);
+    const artifactId = protocolIdForOwner(artifact);
+    const owner = artifactId ? contract.owners.get(artifactId) : undefined;
+    if (!owner) {
+        throw new VerbosityBudgetContractError(`unsupported artifact ${JSON.stringify(artifact)} in verbosity budget authority; ` +
+            `valid artifact_id values: ${[...contract.owners.keys()].sort().join(", ")}`);
+    }
+    return owner;
+}
+function invalidDimension(scope, declarationId, error) {
+    return {
+        scope,
+        classification: "invalid_declaration",
+        unit: null,
+        limit: null,
+        declarationId,
+        error,
+    };
+}
+function classifyDeclaration(raw, index) {
+    const declaration = mapping(raw);
+    if (!declaration)
+        return invalidDimension(`<entry:${index}>`, null, "budget declaration must be a mapping");
+    const scope = typeof declaration.scope === "string" && declaration.scope.trim()
+        ? declaration.scope.trim()
+        : `<entry:${index}>`;
+    const declarationId = typeof declaration.id === "string" ? declaration.id : null;
+    if (scope.startsWith("<entry:")) {
+        return invalidDimension(scope, declarationId, "budget declaration must define a non-empty scope");
+    }
+    const hasWords = Object.hasOwn(declaration, "max_words");
+    const hasTokens = Object.hasOwn(declaration, "token_budget");
+    if (Number(hasWords) + Number(hasTokens) !== 1) {
+        return invalidDimension(scope, declarationId, "budget declaration must define exactly one of max_words or token_budget");
+    }
+    if (hasWords) {
+        if (declaration.max_words === null) {
+            return { scope, classification: "explicit_no_limit", unit: "words", limit: null, declarationId };
+        }
+        if (positiveNumber(declaration.max_words)) {
+            return {
+                scope,
+                classification: "numeric_limit",
+                unit: "words",
+                limit: declaration.max_words,
+                declarationId,
+            };
+        }
+        return invalidDimension(scope, declarationId, "max_words must be a positive number or null");
+    }
+    if (positiveNumber(declaration.token_budget)) {
+        return {
+            scope,
+            classification: "non_word_unit",
+            unit: "tokens",
+            limit: declaration.token_budget,
+            declarationId,
+        };
+    }
+    return invalidDimension(scope, declarationId, "token_budget must be a positive number");
+}
+function isNonVerbosityBudgetEntry(raw) {
+    const declaration = mapping(raw);
+    return Boolean(declaration &&
+        typeof declaration.rule === "string" &&
+        !Object.hasOwn(declaration, "max_words") &&
+        !Object.hasOwn(declaration, "token_budget"));
+}
+export function inspectArtifactVerbosityBudget(artifact, contractPath = verbosityBudgetAuthorityPath()) {
+    const owner = resolveVerbosityBudgetOwner(artifact, contractPath);
+    let schema;
+    try {
+        schema = readMapping(owner.schemaPath, `verbosity budget owner for ${owner.artifactId}`);
+    }
+    catch (error) {
+        return {
+            ...owner,
+            dimensions: [invalidDimension("<authority>", null, error.message)],
+        };
+    }
+    const budget = mapping(schema.BUDGET);
+    if (!budget || Object.keys(budget).length === 0) {
+        return {
+            ...owner,
+            dimensions: [invalidDimension("<authority>", null, "owning schema must define a non-empty BUDGET mapping")],
+        };
+    }
+    const dimensions = Object.entries(budget)
+        .filter(([, declaration]) => !isNonVerbosityBudgetEntry(declaration))
+        .map(([index, declaration]) => classifyDeclaration(declaration, index));
+    if (dimensions.length === 0) {
+        return {
+            ...owner,
+            dimensions: [invalidDimension("<authority>", null, "owning schema defines no verbosity budget declarations")],
+        };
+    }
+    const counts = new Map();
+    for (const dimension of dimensions)
+        counts.set(dimension.scope, (counts.get(dimension.scope) ?? 0) + 1);
+    return {
+        ...owner,
+        dimensions: dimensions.map((dimension) => (counts.get(dimension.scope) ?? 0) > 1
+            ? invalidDimension(dimension.scope, dimension.declarationId, `duplicate budget scope ${dimension.scope}`)
+            : dimension),
+    };
+}
+export function validateVerbosityBudgetContract(contractPath = verbosityBudgetAuthorityPath()) {
+    let contract;
+    try {
+        contract = loadContract(contractPath);
+    }
+    catch (error) {
+        return [error.message];
+    }
+    const errors = [];
+    for (const artifactId of contract.owners.keys()) {
+        const inspected = inspectArtifactVerbosityBudget(artifactId, contractPath);
+        for (const dimension of inspected.dimensions) {
+            if (dimension.classification === "invalid_declaration") {
+                errors.push(`${artifactId}:${dimension.scope}: ${dimension.error}`);
+            }
+        }
+    }
+    return errors;
+}

package/dist/release/releaseMetadata.js

@@ -0,0 +1,385 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { isDeepStrictEqual } from "node:util";
+import { resolvePath } from "../core/paths.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { loadYamlMappingFile } from "../core/yaml.js";
+export const RELEASE_METADATA_AUTHORITY_FILES = [
+    "registry.json",
+    "packages/cli/package.json",
+    "references/cli/update-channels.yaml",
+];
+export const RELEASE_METADATA_ADVISORY_FILES = [
+    "packages/cli/bundle/.agentera-npx-bundle.json",
+];
+export const RELEASE_PROVENANCE_PATHS = [
+    "packages/cli/src",
+    "packages/cli/scripts",
+    "packages/cli/README.md",
+    "packages/cli/tsconfig.json",
+    "skills",
+    "references",
+    "README.md",
+    "UPGRADE.md",
+    "CHANGELOG.md",
+    "DESIGN.md",
+    "LICENSE",
+    "registry.json",
+    "fixtures/routing/hybrid-corpus.yaml",
+];
+export const RELEASE_PROVENANCE_EXCLUSIONS = [
+    "packages/cli/src/release/releaseMetadata.ts",
+    "references/adapters/package-surface-characterization.md",
+];
+export const STABLE_SHIM_PROVENANCE_PATHS = [
+    "packages/cli/shim/bin",
+    "packages/cli/shim/lib",
+    "packages/cli/shim/README.md",
+    "packages/cli/shim/LICENSE",
+];
+const SEMVER_CORE_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const SEMVER_STRICT_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const PRE_RELEASE_RE = /-(.+)$/;
+const GIT_REF_HEX_RE = /^[0-9a-f]{40}$/i;
+function rootDefault() {
+    return resolveSourceRoot();
+}
+function readJson(pathname) {
+    try {
+        return JSON.parse(fs.readFileSync(pathname, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function runGit(root, args) {
+    return spawnSync("git", ["-C", root, ...args], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+}
+function normalizedPackageMetadata(value) {
+    const normalized = structuredClone(value);
+    delete normalized.version;
+    if (normalized.agentera && typeof normalized.agentera === "object" && !Array.isArray(normalized.agentera)) {
+        delete normalized.agentera.gitRef;
+    }
+    return normalized;
+}
+function validateGitRefProvenance(root, gitRef) {
+    const inside = runGit(root, ["rev-parse", "--is-inside-work-tree"]);
+    if (inside.status !== 0 || String(inside.stdout).trim() !== "true")
+        return [];
+    const commit = runGit(root, ["cat-file", "-e", `${gitRef}^{commit}`]);
+    if (commit.status !== 0) {
+        return [`packages/cli/package.json: agentera.gitRef ${JSON.stringify(gitRef)} is not a commit in the local repository`];
+    }
+    const pathspec = [
+        ...RELEASE_PROVENANCE_PATHS,
+        ...RELEASE_PROVENANCE_EXCLUSIONS.map((entry) => `:(exclude)${entry}`),
+    ];
+    const diff = runGit(root, ["diff", "--quiet", gitRef, "--", ...pathspec]);
+    if (diff.status !== 0) {
+        if (diff.status === 1) {
+            return [
+                `packages/cli/package.json: agentera.gitRef ${JSON.stringify(gitRef)} does not match the governed package source tree; ` +
+                    "select the last substantive package-source commit, excluding approved release metadata",
+            ];
+        }
+        return [`packages/cli/package.json: unable to compare agentera.gitRef ${JSON.stringify(gitRef)} with the governed package source tree`];
+    }
+    const status = runGit(root, ["status", "--porcelain=v1", "--untracked-files=all", "--", ...pathspec]);
+    if (status.status !== 0 || String(status.stdout).trim() !== "") {
+        return [
+            "packages/cli/package.json: governed package source has uncommitted or untracked changes outside approved release metadata",
+        ];
+    }
+    const selectedPackage = runGit(root, ["show", `${gitRef}:packages/cli/package.json`]);
+    const currentPackage = readPackageJson(root);
+    try {
+        const selected = JSON.parse(String(selectedPackage.stdout));
+        if (selectedPackage.status !== 0 ||
+            currentPackage === null ||
+            !isDeepStrictEqual(normalizedPackageMetadata(selected), normalizedPackageMetadata(currentPackage))) {
+            return [
+                `packages/cli/package.json: package contract differs from agentera.gitRef ${JSON.stringify(gitRef)} ` +
+                    "outside the permitted version and gitRef fields",
+            ];
+        }
+    }
+    catch {
+        return [`packages/cli/package.json: unable to read package contract from agentera.gitRef ${JSON.stringify(gitRef)}`];
+    }
+    return [];
+}
+export function validateStableShimGitRefProvenance(root, gitRef) {
+    const manifestPath = "packages/cli/shim/package.json";
+    const inside = runGit(root, ["rev-parse", "--is-inside-work-tree"]);
+    if (inside.status !== 0 || String(inside.stdout).trim() !== "true")
+        return [];
+    const commit = runGit(root, ["cat-file", "-e", `${gitRef}^{commit}`]);
+    if (commit.status !== 0) {
+        return [`${manifestPath}: agentera.gitRef ${JSON.stringify(gitRef)} is not a commit in the local repository`];
+    }
+    const diff = runGit(root, ["diff", "--quiet", gitRef, "--", ...STABLE_SHIM_PROVENANCE_PATHS]);
+    if (diff.status !== 0) {
+        return [
+            `${manifestPath}: agentera.gitRef ${JSON.stringify(gitRef)} does not match the stable shim packaged inputs; ` +
+                "select the last substantive shim-source commit",
+        ];
+    }
+    const status = runGit(root, [
+        "status",
+        "--porcelain=v1",
+        "--untracked-files=all",
+        "--",
+        manifestPath,
+        ...STABLE_SHIM_PROVENANCE_PATHS,
+    ]);
+    if (status.status !== 0 || String(status.stdout).trim() !== "") {
+        return [
+            `${manifestPath}: stable shim packaged inputs have uncommitted or untracked changes outside approved release metadata`,
+        ];
+    }
+    const selected = runGit(root, ["show", `${gitRef}:${manifestPath}`]);
+    const current = readJson(path.join(root, manifestPath));
+    try {
+        const selectedManifest = JSON.parse(String(selected.stdout));
+        if (selected.status !== 0 ||
+            current === null ||
+            !isDeepStrictEqual(normalizedPackageMetadata(selectedManifest), normalizedPackageMetadata(current))) {
+            return [
+                `${manifestPath}: package contract differs from agentera.gitRef ${JSON.stringify(gitRef)} ` +
+                    "outside the permitted version and gitRef fields",
+            ];
+        }
+    }
+    catch {
+        return [`${manifestPath}: unable to read package contract from agentera.gitRef ${JSON.stringify(gitRef)}`];
+    }
+    return [];
+}
+function readRegistryVersion(root) {
+    const source = "registry.json";
+    const data = readJson(path.join(root, source));
+    if (data === null) {
+        return { version: null, source };
+    }
+    const skills = data.skills;
+    if (!Array.isArray(skills) || skills.length === 0) {
+        return { version: null, source };
+    }
+    const first = skills[0];
+    if (!first || typeof first !== "object") {
+        return { version: null, source };
+    }
+    const version = first.version;
+    return { version: typeof version === "string" ? version : null, source };
+}
+function readPackageJson(root) {
+    const candidate = path.join(root, "packages/cli/package.json");
+    if (!fs.existsSync(candidate)) {
+        return null;
+    }
+    return readJson(candidate);
+}
+function readUpdateChannels(root) {
+    const candidate = path.join(root, "references/cli/update-channels.yaml");
+    if (!fs.existsSync(candidate)) {
+        return null;
+    }
+    try {
+        return loadYamlMappingFile(candidate); // cast: YAML parse IO boundary
+    }
+    catch {
+        return null;
+    }
+}
+function readBundleSentinel(root) {
+    const source = "packages/cli/bundle/.agentera-npx-bundle.json";
+    const candidate = path.join(root, source);
+    if (!fs.existsSync(candidate)) {
+        return { version: null, source };
+    }
+    const data = readJson(candidate);
+    if (data === null) {
+        return { version: null, source };
+    }
+    const version = data.suiteVersion;
+    return { version: typeof version === "string" ? version : null, source };
+}
+/** Parse `X.Y.Z` core (ignore pre-release and build metadata). */
+export function parseSemverCore(version) {
+    const match = SEMVER_CORE_RE.exec(version);
+    if (!match) {
+        return null;
+    }
+    const core = `${match[1]}.${match[2]}.${match[3]}`;
+    const preMatch = PRE_RELEASE_RE.exec(version);
+    return { core, preRelease: preMatch ? preMatch[1] : null };
+}
+function pickChannelDefaults(authority) {
+    if (authority === null) {
+        return { development: null, stable: null };
+    }
+    const versionResolution = authority.version_resolution;
+    const latestOnChannel = versionResolution?.latest_on_channel;
+    const defaults = (latestOnChannel?.offline_defaults ?? {});
+    return {
+        development: typeof defaults.development === "string" ? defaults.development : null,
+        stable: typeof defaults.stable === "string" ? defaults.stable : null,
+    };
+}
+export function readReleaseMetadata(root = rootDefault()) {
+    const resolved = resolvePath(root);
+    const registry = readRegistryVersion(resolved);
+    const pkg = readPackageJson(resolved);
+    const channels = readUpdateChannels(resolved);
+    const bundle = readBundleSentinel(resolved);
+    const topVersion = pkg && typeof pkg.version === "string" ? pkg.version : null;
+    const agenteraBlock = pkg && typeof pkg.agentera === "object" && pkg.agentera !== null
+        ? pkg.agentera
+        : null;
+    const suiteVersion = agenteraBlock && typeof agenteraBlock.suiteVersion === "string"
+        ? agenteraBlock.suiteVersion
+        : null;
+    const gitRef = agenteraBlock && typeof agenteraBlock.gitRef === "string"
+        ? agenteraBlock.gitRef
+        : null;
+    const { development, stable } = pickChannelDefaults(channels);
+    return {
+        authoritativeVersion: registry.version,
+        authoritativeSource: registry.source,
+        packageVersion: topVersion,
+        packageSuiteVersion: suiteVersion,
+        packageGitRef: gitRef,
+        developmentChannelDefault: development,
+        stableChannelDefault: stable,
+        bundleSuiteVersion: bundle.version,
+    };
+}
+/**
+ * Validate release-metadata coherence. Returns an empty array when the
+ * source-tree version surfaces agree on a single release train.
+ */
+export function validateReleaseMetadata(root = rootDefault(), adapter = "development") {
+    if (adapter === "stable") {
+        const manifestPath = "packages/cli/shim/package.json";
+        const shim = readJson(path.join(resolvePath(root), manifestPath));
+        if (shim === null)
+            return [`${manifestPath}: missing or unreadable; cannot validate release-metadata`];
+        const agentera = shim.agentera;
+        const gitRef = agentera && typeof agentera === "object" && !Array.isArray(agentera)
+            ? agentera.gitRef
+            : null;
+        if (typeof gitRef !== "string" || !GIT_REF_HEX_RE.test(gitRef)) {
+            return [`${manifestPath}: agentera.gitRef must be a 40-character hex SHA for stable shim provenance`];
+        }
+        return validateStableShimGitRefProvenance(resolvePath(root), gitRef);
+    }
+    const errors = [];
+    const snap = readReleaseMetadata(root);
+    const rootLabel = path.basename(resolvePath(root)) || "repo root";
+    // 1. registry.json must publish a valid semver `skills[0].version`.
+    if (snap.authoritativeVersion === null) {
+        errors.push("registry.json: skills[0].version is required for release-metadata validation");
+    }
+    else {
+        const parsed = parseSemverCore(snap.authoritativeVersion);
+        if (parsed === null) {
+            errors.push(`registry.json: skills[0].version ${JSON.stringify(snap.authoritativeVersion)} is not a valid semver`);
+        }
+        else if (parsed.preRelease !== null) {
+            // registry.json is the suite authority and stays on the released core;
+            // pre-release suffixes belong only to packages/cli/package.json.
+            errors.push(`registry.json: skills[0].version must be a released core version (no pre-release suffix); got ${JSON.stringify(snap.authoritativeVersion)}`);
+        }
+    }
+    // 2. packages/cli/package.json must exist and parse.
+    if (snap.packageVersion === null && snap.packageSuiteVersion === null && snap.packageGitRef === null) {
+        errors.push("packages/cli/package.json: missing or unreadable; cannot validate release-metadata");
+    }
+    else {
+        // 2a. top-level `version` must be valid semver and share its core with registry.
+        if (snap.packageVersion === null) {
+            errors.push("packages/cli/package.json: top-level `version` is required");
+        }
+        else {
+            const parsed = parseSemverCore(snap.packageVersion);
+            if (parsed === null) {
+                errors.push(`packages/cli/package.json: top-level version ${JSON.stringify(snap.packageVersion)} is not a valid semver`);
+            }
+            else if (snap.authoritativeVersion !== null &&
+                parseSemverCore(snap.authoritativeVersion)?.core !== parsed.core) {
+                errors.push(`release-metadata divergence: registry.json skills[0].version core is ${JSON.stringify(parseSemverCore(snap.authoritativeVersion)?.core)} ` +
+                    `but packages/cli/package.json top-level version core is ${JSON.stringify(parsed.core)}; ` +
+                    `the npm package version must share its major.minor.patch with the registry suite version`);
+            }
+        }
+        // 2b. `agentera.suiteVersion` must match registry exactly.
+        if (snap.packageSuiteVersion === null) {
+            errors.push("packages/cli/package.json: `agentera.suiteVersion` is required");
+        }
+        else if (snap.authoritativeVersion !== null &&
+            snap.packageSuiteVersion !== snap.authoritativeVersion) {
+            errors.push(`release-metadata divergence: registry.json skills[0].version is ${JSON.stringify(snap.authoritativeVersion)} ` +
+                `but packages/cli/package.json agentera.suiteVersion is ${JSON.stringify(snap.packageSuiteVersion)}; ` +
+                `the agentera.suiteVersion mirror must equal the registry version exactly`);
+        }
+        else if (!SEMVER_STRICT_RE.test(snap.packageSuiteVersion)) {
+            errors.push(`packages/cli/package.json: agentera.suiteVersion ${JSON.stringify(snap.packageSuiteVersion)} is not a released core semver`);
+        }
+        // 2c. `agentera.gitRef` must identify the governed package source tree.
+        if (snap.packageGitRef === null || snap.packageGitRef === "") {
+            errors.push("packages/cli/package.json: `agentera.gitRef` is required for release-metadata validation");
+        }
+        else if (!GIT_REF_HEX_RE.test(snap.packageGitRef)) {
+            errors.push(`packages/cli/package.json: agentera.gitRef ${JSON.stringify(snap.packageGitRef)} must be a 40-character hex SHA; ` +
+                `short SHAs and branch names are not reproducible release references`);
+        }
+        else {
+            errors.push(...validateGitRefProvenance(resolvePath(root), snap.packageGitRef));
+        }
+    }
+    // 3. update-channels.yaml development default must equal the registry version.
+    if (snap.developmentChannelDefault === null) {
+        errors.push("references/cli/update-channels.yaml: version_resolution.latest_on_channel.offline_defaults.development is required");
+    }
+    else if (snap.authoritativeVersion !== null &&
+        snap.developmentChannelDefault !== snap.authoritativeVersion) {
+        errors.push(`release-metadata divergence: registry.json skills[0].version is ${JSON.stringify(snap.authoritativeVersion)} ` +
+            `but update-channels.yaml offline_defaults.development is ${JSON.stringify(snap.developmentChannelDefault)}; ` +
+            `the development channel default must match the registry version exactly`);
+    }
+    // 4. Stable channel default is informational on the @next branch; the
+    // validator surfaces it so maintainers can confirm the stable line still
+    // resolves to its declared 2.x version. A drift on the stable channel
+    // alone is not an error here — that lane is owned by the `main` branch
+    // compatibility boundary per `references/cli/update-channels.yaml`.
+    void snap.stableChannelDefault;
+    // 5. Advisory check on the local bundle sentinel.
+    if (snap.bundleSuiteVersion !== null) {
+        if (snap.authoritativeVersion !== null &&
+            snap.bundleSuiteVersion !== snap.authoritativeVersion) {
+            errors.push(`release-metadata drift (advisory): packages/cli/bundle/.agentera-npx-bundle.json suiteVersion is ${JSON.stringify(snap.bundleSuiteVersion)} ` +
+                `but registry.json skills[0].version is ${JSON.stringify(snap.authoritativeVersion)}; ` +
+                `run \`npm run bundle:data\` (or \`pnpm -C packages/cli run bundle:data\`) at ${rootLabel} to refresh the local bundle copy before publishing`);
+        }
+    }
+    return errors;
+}
+export function releaseMetadataMain(opts = {}) {
+    const root = resolvePath(opts.root ?? rootDefault());
+    const out = opts.out ?? ((line) => process.stdout.write(line + "\n"));
+    const err = opts.err ?? ((line) => process.stderr.write(line + "\n"));
+    const errors = validateReleaseMetadata(root, opts.adapter);
+    if (errors.length > 0) {
+        out("release-metadata validation failed:");
+        for (const message of errors)
+            out(`- ${message}`);
+        return 1;
+    }
+    out("release-metadata ok");
+    return 0;
+}