agentera 3.0.0-dev.7 → 3.0.0-dev.74

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

@@ -1,5 +1,7 @@
 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";
@@ -11,6 +13,31 @@ export const RELEASE_METADATA_AUTHORITY_FILES = [
 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 = /-(.+)$/;
@@ -26,6 +53,113 @@ function readJson(pathname) {
         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));
@@ -76,7 +210,7 @@ function readBundleSentinel(root) {
     return { version: typeof version === "string" ? version : null, source };
 }
 /** Parse `X.Y.Z` core (ignore pre-release and build metadata). */
-function parseSemverCore(version) {
+export function parseSemverCore(version) {
     const match = SEMVER_CORE_RE.exec(version);
     if (!match) {
         return null;
@@ -97,22 +231,22 @@ function pickChannelDefaults(authority) {
         stable: typeof defaults.stable === "string" ? defaults.stable : null,
     };
 }
-export function readReleaseMetadata(root = rootDefault()) {
+export function readReleaseMetadata(root = rootDefault(), packageOverride) {
     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 topVersion = packageOverride?.version ?? (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"
+    const gitRef = packageOverride?.gitRef ?? (agenteraBlock && typeof agenteraBlock.gitRef === "string"
         ? agenteraBlock.gitRef
-        : null;
+        : null);
     const { development, stable } = pickChannelDefaults(channels);
     return {
         authoritativeVersion: registry.version,
@@ -129,9 +263,23 @@ export function readReleaseMetadata(root = rootDefault()) {
  * 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()) {
+export function validateReleaseMetadata(root = rootDefault(), adapter = "development", packageOverride) {
+    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 snap = readReleaseMetadata(root, packageOverride);
     const rootLabel = path.basename(resolvePath(root)) || "repo root";
     // 1. registry.json must publish a valid semver `skills[0].version`.
     if (snap.authoritativeVersion === null) {
@@ -182,7 +330,7 @@ export function validateReleaseMetadata(root = rootDefault()) {
         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 be a 40-character hex SHA.
+        // 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");
         }
@@ -190,6 +338,9 @@ export function validateReleaseMetadata(root = rootDefault()) {
             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) {
@@ -222,7 +373,14 @@ 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);
+    const overrideVersion = process.env.AGENTERA_RELEASE_PACKAGE_VERSION;
+    const overrideGitRef = process.env.AGENTERA_RELEASE_GIT_REF;
+    if ((overrideVersion === undefined) !== (overrideGitRef === undefined)) {
+        out("release-metadata validation failed:");
+        out("- AGENTERA_RELEASE_PACKAGE_VERSION and AGENTERA_RELEASE_GIT_REF must be supplied together");
+        return 1;
+    }
+    const errors = validateReleaseMetadata(root, opts.adapter, overrideVersion === undefined ? undefined : { version: overrideVersion, gitRef: overrideGitRef });
     if (errors.length > 0) {
         out("release-metadata validation failed:");
         for (const message of errors)
@@ -232,4 +390,3 @@ export function releaseMetadataMain(opts = {}) {
     out("release-metadata ok");
     return 0;
 }
-//# sourceMappingURL=releaseMetadata.js.map