@nimiplatform/nimi-coding 0.3.1 → 0.4.0

package/cli/dev/check-product-conformance.mjs

@@ -0,0 +1,917 @@
+#!/usr/bin/env node
+// Exercises behavioural contract leaves against the CLI artifact. Structural
+// agreement alone cannot prove that a declared exit policy or budget is real.
+
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+import YAML from "yaml";
+
+const execFileAsync = promisify(execFile);
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+const PRODUCT_CONTRACTS = {
+  anchors: "authority-anchors.yaml",
+  consumers: "authority-consumers.yaml",
+  terms: "authority-terms.yaml",
+  "closed-sets": "authority-closed-sets.yaml",
+};
+const STATUS_NAMES = ["verified", "contradicted", "not_machine_checkable", "unmapped"];
+const NOT_MACHINE_CHECKABLE = new Map();
+const EMPTY_ARRAY_SENTINEL = Object.freeze({ collection: "array", empty: true });
+const EMPTY_OBJECT_SENTINEL = Object.freeze({ collection: "object", empty: true });
+
+async function execute(file, args, options = {}) {
+  try {
+    const result = await execFileAsync(file, args, { maxBuffer: 16 * 1024 * 1024, ...options });
+    return { code: 0, stdout: result.stdout, stderr: result.stderr };
+  } catch (error) {
+    return {
+      code: typeof error.code === "number" ? error.code : error.code ?? 1,
+      stdout: error.stdout ?? "",
+      stderr: error.stderr ?? error.message ?? "",
+    };
+  }
+}
+
+function npmCommand(args) {
+  if (process.platform !== "win32") return { file: "npm", args };
+  return {
+    file: process.env.ComSpec ?? "cmd.exe",
+    args: ["/d", "/s", "/c", "npm", ...args],
+  };
+}
+
+function nestedNpmEnvironment() {
+  // An outer `npm pack --dry-run` exports its mode to prepack hooks. The inner
+  // artifact build must create and extract a tarball rather than inherit that
+  // simulation and report an artifact it never wrote.
+  const environment = { ...process.env };
+  for (const key of Object.keys(environment)) {
+    if (["npm_config_dry_run", "npm_config_pack_destination"].includes(key.toLowerCase())) delete environment[key];
+  }
+  return environment;
+}
+
+function runCli(cliPath, cwd, args) {
+  return execute(process.execPath, [cliPath, ...args], {
+    cwd,
+    env: { ...process.env, NIMICODING_LANG: "en", NO_COLOR: "1" },
+  });
+}
+
+function runGit(root, args) {
+  return execute("git", args, { cwd: root, env: process.env });
+}
+
+function walkLeaves(value, prefix, visit) {
+  if (Array.isArray(value)) {
+    if (value.length === 0) visit(prefix, EMPTY_ARRAY_SENTINEL);
+    else value.forEach((entry, index) => walkLeaves(entry, `${prefix}[${index}]`, visit));
+    return;
+  }
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value);
+    if (entries.length === 0) visit(prefix, EMPTY_OBJECT_SENTINEL);
+    else for (const [key, entry] of entries) {
+      walkLeaves(entry, prefix.length === 0 ? key : `${prefix}.${key}`, visit);
+    }
+    return;
+  }
+  visit(prefix, value);
+}
+
+function valueAt(root, dottedPath) {
+  const parts = [...dottedPath.matchAll(/(?:^|\.)([^.[\]]+)|\[(\d+)\]/gu)]
+    .map((match) => match[1] ?? Number(match[2]));
+  let value = root;
+  for (const part of parts) value = value?.[part];
+  return value;
+}
+
+function parseJson(output) {
+  try {
+    return output.stdout.length > 0 ? JSON.parse(output.stdout) : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function createRepositoryFixture() {
+  const root = await mkdtemp(path.join(os.tmpdir(), "nimicoding-product-conformance-fixture-"));
+  const spec = path.join(root, ".nimi", "spec");
+  const source = path.join(spec, "fixture.authority.yaml");
+  const scopeBindings = path.join(root, "scope-bindings.yaml");
+  const externalOne = path.join(root, "external-one");
+  const externalTwo = path.join(root, "external-two");
+  await mkdir(spec, { recursive: true });
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await mkdir(path.join(root, "proto"), { recursive: true });
+  await mkdir(path.join(root, "config"), { recursive: true });
+  await mkdir(externalOne);
+  await mkdir(externalTwo);
+
+  const container = {
+    format: "nimicoding.authority/v2",
+    owner: "team.fixture",
+    units: [
+      {
+        id: "definition.fixture",
+        kind: "definition",
+        title: "Fixture concept",
+        meaning: "The standaloneTerm and secondTerm are canonical. Run pnpm install. The path token src/pathCamelCase is excluded. artifact=src/live.ts.old",
+      },
+      {
+        id: "definition.vocabulary",
+        kind: "definition",
+        title: "Fixture vocabulary",
+        meaning: "Supported kinds are IMAGE, VIDEO, AUDIO.",
+      },
+      {
+        id: "rule.fixture",
+        kind: "rule",
+        title: "Fixture rule",
+        modality: "must",
+        scope: ["api.fixture"],
+        statement: "Use standaloneTerm exactly.",
+        condition: "Always.",
+        failure: "Reject invalid input.",
+        relations: [{ type: "applies_to", target: "definition.fixture" }],
+      },
+    ],
+  };
+  await writeFile(source, YAML.stringify(container, { indent: 2, lineWidth: 0 }), "utf8");
+  await writeFile(scopeBindings, YAML.stringify({
+    format: "nimicoding.scope-bindings/v1",
+    scopes: [{ scope: "api.fixture", bindings: [{ kind: "path_glob", value: "src/*.ts" }] }],
+  }, { indent: 2, lineWidth: 0 }), "utf8");
+  await writeFile(path.join(root, "src", "live.ts"), "export const standaloneTerm = true; export const secondTerm = true;\n", "utf8");
+  await writeFile(
+    path.join(root, "src", "consumer.ts"),
+    [
+      "export const firstAuthority = '.nimi/spec/missing.authority.yaml';",
+      "export const secondAuthority = '.nimi/spec/other-missing.authority.yaml';",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  await writeFile(path.join(root, "proto", "kinds.proto"), [
+    "syntax = \"proto3\";",
+    "enum AssetKind {",
+    "  ASSET_KIND_IMAGE = 0;",
+    "  ASSET_KIND_VIDEO = 1;",
+    "  ASSET_KIND_EMBEDDING = 2;",
+    "}",
+    "",
+  ].join("\n"), "utf8");
+  await writeFile(path.join(root, "config", "kinds.yaml"), "values: [IMAGE, VIDEO, EMBEDDING]\n", "utf8");
+  await writeFile(path.join(root, "package.json"), `${JSON.stringify({
+    name: "product-conformance-fixture",
+    private: true,
+    scripts: { build: "node src/live.ts" },
+  }, null, 2)}\n`, "utf8");
+
+  const initialized = await runGit(root, ["init", "-q", "-b", "main"]);
+  if (initialized.code !== 0) throw new Error(`could not initialize fixture Git repository: ${initialized.stderr}`);
+  const added = await runGit(root, ["add", "--", "."]);
+  if (added.code !== 0) throw new Error(`could not populate fixture Git index: ${added.stderr}`);
+  return { root, spec, source, scopeBindings, externalOne, externalTwo };
+}
+
+export function requiredArgs(command, fixture, overrides = {}) {
+  const budgets = {
+    maxUnits: overrides.maxUnits ?? 100,
+    maxAnchors: overrides.maxAnchors ?? 100,
+    maxFiles: overrides.maxFiles ?? 100,
+    maxRefs: overrides.maxRefs ?? 100,
+    maxTerms: overrides.maxTerms ?? 1000,
+    maxSets: overrides.maxSets ?? 100,
+    maxBytes: overrides.maxBytes ?? 1000000,
+  };
+  const common = ["authority", command, fixture.root, "--spec", fixture.spec];
+  if (command === "anchors") return [...common, "--max-units", String(budgets.maxUnits), "--max-anchors", String(budgets.maxAnchors), "--max-bytes", String(budgets.maxBytes), "--json"];
+  if (command === "consumers") return [...common, "--max-files", String(budgets.maxFiles), "--max-refs", String(budgets.maxRefs), "--max-bytes", String(budgets.maxBytes), "--json"];
+  if (command === "terms") return [...common, "--max-units", String(budgets.maxUnits), "--max-terms", String(budgets.maxTerms), "--max-bytes", String(budgets.maxBytes), "--json"];
+  return [...common, "--max-units", String(budgets.maxUnits), "--max-sets", String(budgets.maxSets), "--max-bytes", String(budgets.maxBytes), "--json"];
+}
+
+export function allFlagArgs(command, fixture, contract) {
+  const args = ["authority", command, fixture.root];
+  const valueFor = {
+    spec: fixture.spec,
+    "scope-bindings": fixture.scopeBindings,
+    term: "standaloneTerm",
+  };
+  const integerValue = { "max-bytes": "1000000", "max-terms": "1000" };
+  for (const flag of contract.surface?.value_flags ?? []) args.push(`--${flag}`, valueFor[flag] ?? "fixture-value");
+  for (const flag of contract.surface?.integer_flags ?? []) args.push(`--${flag}`, integerValue[flag] ?? "100");
+  for (const flag of contract.surface?.repeatable_flags ?? []) {
+    if (flag === "external-root") {
+      args.push("--external-root", `peer=${fixture.externalOne}`, "--external-root", `other=${fixture.externalTwo}`);
+    } else args.push(`--${flag}`, "fixture-one", `--${flag}`, "fixture-two");
+  }
+  for (const flag of contract.surface?.boolean_flags ?? []) args.push(`--${flag}`);
+  return args;
+}
+
+function replaceFlagValue(args, flag, value) {
+  const result = [...args];
+  const index = result.indexOf(flag);
+  if (index === -1) throw new Error(`fixture invocation has no ${flag}`);
+  result[index + 1] = String(value);
+  return result;
+}
+
+function reportFormat(command, report) {
+  if (command === "anchors") return report?.format;
+  if (command === "consumers") return report?.consumers?.format;
+  if (command === "terms") return report?.terms?.format;
+  return report?.closed_sets?.format;
+}
+
+function noPartialPayload(command, report) {
+  if (report?.complete !== false || report?.partial !== false) return false;
+  if (command === "anchors") {
+    return report?.summary?.units === 0 && report?.summary?.anchorsChecked === 0;
+  }
+  if (command === "consumers") return report?.consumers === null;
+  if (command === "terms") return report?.terms === null;
+  return report?.closed_sets === null;
+}
+
+function hasFinding(command, report) {
+  if (command === "anchors") return (report?.diagnostics?.length ?? 0) > 0;
+  if (command === "consumers") return (report?.consumers?.specConsumption?.counts?.canonicalDead ?? 0) > 0;
+  if (command === "terms") return (report?.terms?.index?.length ?? 0) > 0;
+  return (report?.summary?.pairsWithDeltas ?? 0) > 0;
+}
+
+export async function addAnchorFinding(fixture) {
+  const container = YAML.parse(await readFile(fixture.source, "utf8"));
+  const definition = container.units.find((unit) => unit.id === "definition.fixture");
+  definition.meaning += " Run pnpm missing-script and pnpm another-missing-script";
+  await writeFile(fixture.source, YAML.stringify(container, { indent: 2, lineWidth: 0 }), "utf8");
+  const added = await runGit(fixture.root, ["add", "--", "."]);
+  if (added.code !== 0) throw new Error(`could not update fixture Git index: ${added.stderr}`);
+}
+
+async function addTrackedInventoryFile(fixture) {
+  await writeFile(path.join(fixture.root, "inventory-added.txt"), "tracked inventory change\n", "utf8");
+  const added = await runGit(fixture.root, ["add", "--", "inventory-added.txt"]);
+  if (added.code !== 0) throw new Error(`could not extend fixture Git inventory: ${added.stderr}`);
+}
+
+async function packedCli(root) {
+  const temporaryRoot = await mkdtemp(path.join(os.tmpdir(), "nimicoding-product-conformance-pack-"));
+  const packDirectory = path.join(temporaryRoot, "pack");
+  const consumer = path.join(temporaryRoot, "consumer");
+  await mkdir(packDirectory);
+  await mkdir(consumer);
+  await writeFile(path.join(consumer, "package.json"), '{"name":"product-conformance-packed-consumer","private":true}\n', "utf8");
+  const environment = nestedNpmEnvironment();
+  const pack = npmCommand(["pack", "--ignore-scripts", "--pack-destination", packDirectory]);
+  const packed = await execute(pack.file, pack.args, { cwd: root, env: environment });
+  if (packed.code !== 0) throw new Error(`npm pack failed: ${packed.stderr || packed.stdout}`);
+  const tarballName = packed.stdout.trim().split(/\r?\n/u).at(-1);
+  const install = npmCommand(["install", "--ignore-scripts", "--no-audit", "--no-fund", "--no-package-lock", path.join(packDirectory, tarballName)]);
+  const installed = await execute(install.file, install.args, { cwd: consumer, env: environment });
+  if (installed.code !== 0) throw new Error(`packed package extraction failed: ${installed.stderr || installed.stdout}`);
+  const installedPackageRoot = path.join(consumer, "node_modules", "@nimiplatform", "nimi-coding");
+  return {
+    cliPath: path.join(installedPackageRoot, "bin", "nimicoding.mjs"),
+    contractDirectory: path.join(installedPackageRoot, "spec"),
+    packageRoot: installedPackageRoot,
+    cleanup: () => rm(temporaryRoot, { recursive: true, force: true }),
+  };
+}
+
+function installBuiltinLeafPath(contract) {
+  const index = contract?.lexical_grammar?.class_B?.builtin_subcommands_excluded?.indexOf("install") ?? -1;
+  if (index === -1) throw new Error("anchors contract does not classify pnpm install as a builtin");
+  return `lexical_grammar.class_B.builtin_subcommands_excluded[${index}]`;
+}
+
+function createClassification(contracts) {
+  const leaves = new Map();
+  const add = (contract, leafPath, value) => {
+    const key = `${contract}:${leafPath}`;
+    if (!leaves.has(key)) leaves.set(key, { contract, path: leafPath, value, status: "unmapped", details: [] });
+  };
+  for (const [command, contract] of Object.entries(contracts)) {
+    for (const section of ["surface", "budgets", "result"]) {
+      walkLeaves(contract[section], section, (leafPath, value) => add(command, leafPath, value));
+    }
+    for (const key of ["boolean_flags", "value_flags", "integer_flags", "repeatable_flags"]) {
+      const leafPath = `surface.${key}`;
+      if (!Object.hasOwn(contract.surface ?? {}, key) || !Array.isArray(contract.surface[key])) {
+        add(command, leafPath, contract.surface?.[key]);
+        const leaf = leaves.get(`${command}:${leafPath}`);
+        leaf.status = "contradicted";
+        leaf.details.push("required surface collection is missing or is not an array");
+      }
+    }
+    add(command, "command", contract.command);
+  }
+  for (const [command, paths] of Object.entries({
+    anchors: [
+      installBuiltinLeafPath(contracts.anchors),
+      "lexical_grammar.class_B.resolution",
+      "lexical_grammar.class_C.shape",
+    ],
+    terms: ["inputs.term.required_for_code", "lexical_grammar.excluded"],
+  })) {
+    for (const leafPath of paths) add(command, leafPath, valueAt(contracts[command], leafPath));
+  }
+  for (const [key, reason] of NOT_MACHINE_CHECKABLE) {
+    const leaf = leaves.get(key);
+    if (!leaf) throw new Error(`not-machine-checkable declaration names no leaf: ${key}`);
+    leaf.status = "not_machine_checkable";
+    leaf.details.push(reason);
+  }
+  return leaves;
+}
+
+function addAuthoringClassification(leaves, authoring) {
+  const values = authoring?.commands?.check?.require_format?.admitted_values;
+  if (!Array.isArray(values) || values.length === 0) throw new Error("authoring contract declares no admitted check formats");
+  values.forEach((value, index) => leaves.set(`authoring:commands.check.require_format.admitted_values[${index}]`, {
+    contract: "authoring",
+    path: `commands.check.require_format.admitted_values[${index}]`,
+    value,
+    status: "unmapped",
+    details: [],
+  }));
+}
+
+function classify(leaves, contract, leafPath, matches, detail) {
+  const leaf = leaves.get(`${contract}:${leafPath}`);
+  if (!leaf) throw new Error(`behavioural check names no classified leaf: ${contract}:${leafPath}`);
+  leaf.details.push(detail);
+  if (!matches) leaf.status = "contradicted";
+  else if (leaf.status === "unmapped") leaf.status = "verified";
+}
+
+function flagPaths(contract) {
+  const paths = [];
+  for (const key of ["boolean_flags", "value_flags", "integer_flags", "repeatable_flags"]) {
+    const values = contract.surface?.[key];
+    if (Array.isArray(values) && values.length === 0) paths.push(`surface.${key}`);
+    else (values ?? []).forEach((_, index) => paths.push(`surface.${key}[${index}]`));
+  }
+  return paths;
+}
+
+function commandSequence(command) {
+  const sequence = [];
+  for (let raw of String(command).trim().split(/\s+/u).filter(Boolean)) {
+    while (raw.startsWith("[")) {
+      sequence.push("optional:start");
+      raw = raw.slice(1);
+    }
+    const repeatable = raw.endsWith("...");
+    if (repeatable) raw = raw.slice(0, -3);
+    let optionalEnds = 0;
+    while (raw.endsWith("]")) {
+      optionalEnds += 1;
+      raw = raw.slice(0, -1);
+    }
+    for (const token of raw.match(/<[^>]+>|--[a-z][a-z0-9-]*|[^<]+/gu) ?? []) {
+      if (/^<[^>]+>$/u.test(token)) sequence.push(`metavariable:${token.slice(1, -1)}`);
+      else if (/^--/u.test(token)) sequence.push(`flag:${token.slice(2)}`);
+      else sequence.push(`token:${token}`);
+    }
+    for (let index = 0; index < optionalEnds; index += 1) sequence.push("optional:end");
+    if (repeatable) sequence.push("repeatable");
+  }
+  return sequence;
+}
+
+function usageCommand(stderr, command) {
+  return String(stderr).split(/\r?\n/u).find((line) => line.startsWith(`nimicoding authority ${command} `)) ?? "";
+}
+
+async function exerciseParserSurface(cliPath, fixture, contracts, leaves) {
+  const validReports = {};
+  for (const [command, contract] of Object.entries(contracts)) {
+    const validArgs = allFlagArgs(command, fixture, contract);
+    const valid = await runCli(cliPath, fixture.root, validArgs);
+    const report = parseJson(valid);
+    validReports[command] = { output: valid, report, args: validArgs };
+
+    const unknown = await runCli(cliPath, fixture.root, [...requiredArgs(command, fixture), "--unknown-product-conformance-flag"]);
+    const repeat = await runCli(cliPath, fixture.root, [...requiredArgs(command, fixture), "--json"]);
+    const parserMatches = valid.code === 0
+      && unknown.code === 2 && unknown.stdout === ""
+      && repeat.code === 2 && repeat.stdout === "";
+    const usage = usageCommand(unknown.stderr, command);
+    const commandMatches = parserMatches
+      && JSON.stringify(commandSequence(contract.command)) === JSON.stringify(commandSequence(usage));
+    classify(
+      leaves,
+      command,
+      "command",
+      commandMatches,
+      `valid=${valid.code}; unknown=${unknown.code}; repeated=${repeat.code}; usage=${JSON.stringify(usage)}`,
+    );
+    for (const leafPath of flagPaths(contract)) {
+      classify(leaves, command, leafPath, parserMatches, `closed parser invocation: valid=${valid.code}; unknown=${unknown.code}; repeated=${repeat.code}`);
+    }
+    classify(
+      leaves,
+      command,
+      "surface.report_format",
+      valid.code === 0 && reportFormat(command, report) === contract.surface.report_format,
+      `JSON declared ${JSON.stringify(reportFormat(command, report))}`,
+    );
+  }
+  return validReports;
+}
+
+async function exerciseRequiredCombinations(cliPath, fixture, contracts, authoring, leaves) {
+  const codeWithoutTerm = await runCli(cliPath, fixture.root, [
+    ...requiredArgs("terms", fixture).filter((entry) => entry !== "--json"),
+    "--code", "--json",
+  ]);
+  const refusedCode = codeWithoutTerm.code === 2 && codeWithoutTerm.stdout === "";
+  classify(leaves, "terms", "inputs.term.required_for_code", refusedCode, `--code without --term exited ${codeWithoutTerm.code}`);
+  for (const leafPath of ["surface.boolean_flags[1]", "surface.value_flags[1]"]) {
+    classify(leaves, "terms", leafPath, refusedCode, `required --code/--term combination exited ${codeWithoutTerm.code}`);
+  }
+
+  const admitted = authoring.commands.check.require_format.admitted_values;
+  const invalidFormat = await runCli(cliPath, fixture.root, [
+    "authority", "check", fixture.spec, "--require-format", "nimicoding.authority/invalid", "--json",
+  ]);
+  const formatRefusal = invalidFormat.code === 2
+    && invalidFormat.stdout === ""
+    && admitted.every((format) => invalidFormat.stderr.includes(format));
+  admitted.forEach((_, index) => classify(
+    leaves,
+    "authoring",
+    `commands.check.require_format.admitted_values[${index}]`,
+    formatRefusal,
+    `invalid --require-format exited ${invalidFormat.code} and named admitted formats`,
+  ));
+}
+
+async function independentFixtureOracle(fixture) {
+  const bytes = async (relative) => Buffer.byteLength(await readFile(path.join(fixture.root, relative)));
+  const authorityBytes = await bytes(".nimi/spec/fixture.authority.yaml");
+  const nonCorpus = [
+    "config/kinds.yaml",
+    "package.json",
+    "proto/kinds.proto",
+    "scope-bindings.yaml",
+    "src/consumer.ts",
+    "src/live.ts",
+  ];
+  const nonCorpusBytes = (await Promise.all(nonCorpus.map(bytes))).reduce((total, value) => total + value, 0);
+  const implementationBytes = (await Promise.all([
+    "config/kinds.yaml",
+    "proto/kinds.proto",
+    "scope-bindings.yaml",
+  ].map(bytes))).reduce((total, value) => total + value, 0);
+  return {
+    units: 3,
+    files: 6,
+    refs: 2,
+    terms: 2,
+    sets: 2,
+    consumersInputBytes: nonCorpusBytes,
+    termsInputBytes: authorityBytes + nonCorpusBytes,
+    closedSetsInputBytes: authorityBytes + implementationBytes,
+    fixedBytesMatch: authorityBytes === 706
+      && nonCorpusBytes === 602
+      && authorityBytes + nonCorpusBytes === 1308
+      && authorityBytes + implementationBytes === 984,
+  };
+}
+
+async function budgetBoundary(cliPath, fixture, validArgs, flag, admittedValue) {
+  const admitted = await runCli(cliPath, fixture.root, replaceFlagValue(validArgs, flag, admittedValue));
+  const refused = await runCli(cliPath, fixture.root, replaceFlagValue(validArgs, flag, admittedValue - 1));
+  return {
+    admitted,
+    admittedReport: parseJson(admitted),
+    refused,
+    refusedReport: parseJson(refused),
+  };
+}
+
+async function exerciseCompleteAndBudgets(cliPath, fixture, contracts, leaves, validReports) {
+  const oracle = await independentFixtureOracle(fixture);
+  const budgetCases = {
+    anchors: [["budgets.max_units", "--max-units", oracle.units]],
+    consumers: [
+      ["budgets.max_files", "--max-files", oracle.files],
+      ["budgets.max_refs", "--max-refs", oracle.refs],
+      ["budgets.max_bytes", "--max-bytes", oracle.consumersInputBytes],
+    ],
+    terms: [
+      ["budgets.max_units", "--max-units", oracle.units],
+      ["budgets.max_terms", "--max-terms", oracle.terms],
+      ["budgets.max_bytes", "--max-bytes", oracle.termsInputBytes],
+    ],
+    "closed-sets": [
+      ["budgets.max_units", "--max-units", oracle.units],
+      ["budgets.max_sets", "--max-sets", oracle.sets],
+      ["budgets.max_bytes", "--max-bytes", oracle.closedSetsInputBytes],
+    ],
+  };
+
+  for (const command of Object.keys(contracts)) {
+    const valid = validReports[command];
+    const validComplete = valid.output.code === 0 && valid.report?.complete === true && valid.report?.partial === false;
+    if (command === "anchors") {
+      classify(leaves, command, "budgets.truncation_or_partial_result", validComplete, `valid report complete=${valid.report?.complete}; partial=${valid.report?.partial}`);
+    } else {
+      classify(leaves, command, "result.complete", validComplete, `valid report complete=${valid.report?.complete}`);
+      classify(leaves, command, "result.partial", validComplete, `valid report partial=${valid.report?.partial}`);
+    }
+
+    for (const [budgetPath, flag, expected] of budgetCases[command]) {
+      const boundary = await budgetBoundary(cliPath, fixture, valid.args, flag, expected);
+      const boundaryMatches = oracle.fixedBytesMatch
+        && boundary.admitted.code === 0
+        && boundary.refused.code === 1
+        && noPartialPayload(command, boundary.refusedReport);
+      classify(
+        leaves,
+        command,
+        budgetPath,
+        boundaryMatches,
+        `independent fixture N=${expected}; admitted=${boundary.admitted.code}; N-1=${boundary.refused.code}`,
+      );
+      const exceededPath = command === "anchors" ? "budgets.overflow" : "budgets.exceeded";
+      classify(leaves, command, exceededPath, boundaryMatches, `${flag} independent N/N-1 boundary`);
+      if (command === "anchors") {
+        classify(leaves, command, "budgets.N_and_N_minus_1", boundaryMatches, `${flag} independent symmetric boundary`);
+        classify(leaves, command, "budgets.truncation_or_partial_result", boundaryMatches, `${flag} refusal contained no partial product`);
+      } else {
+        classify(leaves, command, "result.complete", boundaryMatches, `${flag} refusal complete=${boundary.refusedReport?.complete}`);
+        classify(leaves, command, "result.partial", boundaryMatches, `${flag} refusal partial=${boundary.refusedReport?.partial}`);
+      }
+      if (budgetPath === "budgets.max_bytes" && command !== "consumers") {
+        classify(
+          leaves,
+          command,
+          "result.byte_counts.inputBytes",
+          boundaryMatches && boundary.admittedReport?.input_bytes === expected,
+          `independent decoded input bytes=${expected}; reported=${boundary.admittedReport?.input_bytes}`,
+        );
+      }
+    }
+  }
+}
+
+function trackedTextInventoryMatches(inventory) {
+  return Number.isSafeInteger(inventory?.trackedFiles)
+    && Number.isSafeInteger(inventory?.scannedFiles)
+    && inventory?.excludedByReason !== null
+    && typeof inventory?.excludedByReason === "object"
+    && Array.isArray(inventory?.excluded)
+    && inventory.trackedFiles === inventory.scannedFiles + inventory.excluded.length;
+}
+
+async function exerciseRepositoryInventory(cliPath, fixture, contracts, leaves, validReports) {
+  const commands = Object.keys(contracts);
+  const before = Object.fromEntries(commands.map((command) => [command, validReports[command].report?.trackedPathSetDigest]));
+  const sameBefore = new Set(Object.values(before)).size === 1;
+  const hexBefore = Object.values(before).every((digest) => /^[0-9a-f]{64}$/u.test(digest ?? ""));
+
+  const consumerInventory = validReports.consumers.report?.consumers?.fileInventory;
+  classify(
+    leaves,
+    "consumers",
+    "result.file_inventory",
+    contracts.consumers.result.file_inventory === "tracked_text_inventory_v1" && trackedTextInventoryMatches(consumerInventory),
+    `tracked=${consumerInventory?.trackedFiles}; scanned=${consumerInventory?.scannedFiles}; excluded=${consumerInventory?.excluded?.length}`,
+  );
+
+  await addTrackedInventoryFile(fixture);
+  const after = {};
+  for (const command of commands) {
+    const output = await runCli(cliPath, fixture.root, validReports[command].args);
+    const report = parseJson(output);
+    after[command] = report?.trackedPathSetDigest;
+  }
+  const sameAfter = new Set(Object.values(after)).size === 1;
+  const changedTogether = commands.every((command) => before[command] !== after[command]);
+  for (const command of commands) {
+    classify(
+      leaves,
+      command,
+      "result.trackedPathSetDigest",
+      hexBefore && sameBefore && sameAfter && changedTogether,
+      `before=${before[command]}; after=${after[command]}; same-before=${sameBefore}; same-after=${sameAfter}; changed-together=${changedTogether}`,
+    );
+  }
+}
+
+async function exerciseGrammar(cliPath, fixture, leaves, validReports) {
+  const anchors = validReports.anchors.report;
+  const rightBoundary = validReports.anchors.output.code === 0
+    && anchors?.summary?.anchorsChecked === 0
+    && (anchors?.diagnostics?.length ?? -1) === 0;
+  classify(leaves, "anchors", "lexical_grammar.class_C.shape", rightBoundary, `src/live.ts.old yielded ${anchors?.summary?.anchorsChecked} anchors`);
+
+  const termsOutput = await runCli(cliPath, fixture.root, requiredArgs("terms", fixture));
+  const terms = parseJson(termsOutput);
+  const indexed = terms?.terms?.index?.map((entry) => entry.term) ?? [];
+  const pathPartition = termsOutput.code === 0 && indexed.includes("standaloneTerm") && !indexed.includes("pathCamelCase");
+  classify(leaves, "terms", "lexical_grammar.excluded", pathPartition, `pathCamelCase indexed=${indexed.includes("pathCamelCase")}`);
+}
+
+async function findingsInvocation(cliPath, fixture, command) {
+  const output = await runCli(cliPath, fixture.root, requiredArgs(command, fixture));
+  return { output, report: parseJson(output) };
+}
+
+function classifyFinding(leaves, contracts, command, execution, label) {
+  const paths = ["surface.findings_change_exit_code"];
+  if (valueAt(contracts[command], "result.findings_change_exit_code") !== undefined) paths.push("result.findings_change_exit_code");
+  for (const leafPath of paths) {
+    const expectedExit = valueAt(contracts[command], leafPath) === true ? 1 : 0;
+    const matches = execution.output.code === expectedExit && hasFinding(command, execution.report);
+    classify(
+      leaves,
+      command,
+      leafPath,
+      matches,
+      `${label} finding exited ${execution.output.code}; expected ${expectedExit}; finding=${hasFinding(command, execution.report)}`,
+    );
+  }
+}
+
+async function exerciseFindings(cliPath, fixture, contracts, leaves, label) {
+  const results = {};
+  for (const command of Object.keys(contracts)) {
+    results[command] = await findingsInvocation(cliPath, fixture, command);
+    classifyFinding(leaves, contracts, command, results[command], label);
+  }
+  return results;
+}
+
+function classifyAnchorGrammar(leaves, contract, execution) {
+  const diagnostics = execution.report?.diagnostics ?? [];
+  const anchors = diagnostics.map((diagnostic) => diagnostic.anchor);
+  const partition = execution.output.code === 1
+    && execution.report?.summary?.anchorsChecked === 2
+    && anchors.includes("pnpm missing-script")
+    && !anchors.includes("pnpm install");
+  classify(leaves, "anchors", installBuiltinLeafPath(contract), partition, `pnpm install excluded=${!anchors.includes("pnpm install")}`);
+  classify(leaves, "anchors", "lexical_grammar.class_B.resolution", partition, `pnpm missing-script diagnosed=${anchors.includes("pnpm missing-script")}`);
+  classify(leaves, "anchors", "result.unresolved_anchor_or_glob", partition, `dead script report exited ${execution.output.code}`);
+}
+
+function classifyExpected(leaves, contract, leafPath, expectedValue, behaviourMatches, detail) {
+  const leaf = leaves.get(`${contract}:${leafPath}`);
+  const valueMatches = leaf !== undefined && JSON.stringify(leaf.value) === JSON.stringify(expectedValue);
+  classify(leaves, contract, leafPath, valueMatches && behaviourMatches, `${detail}; value=${JSON.stringify(leaf?.value)}`);
+}
+
+async function exerciseCoreClosure(cliPath, fixture, contracts, leaves, validReports, findings) {
+  const baselineMatches = {
+    anchors: validReports.anchors.report?.summary?.units === 3
+      && validReports.anchors.report?.summary?.anchorsChecked === 0
+      && validReports.anchors.report?.summary?.diagnostics === 0,
+    consumers: validReports.consumers.report?.summary?.filesScanned === 6
+      && validReports.consumers.report?.summary?.references === 2,
+    terms: validReports.terms.report?.summary?.units === 3
+      && validReports.terms.report?.summary?.distinctTerms === 2,
+    "closed-sets": validReports["closed-sets"].report?.summary?.sets?.total === 2,
+  };
+  for (const command of Object.keys(contracts)) {
+    classifyExpected(
+      leaves,
+      command,
+      "surface.corpus_root",
+      "repository_authority_corpus_only",
+      validReports[command].output.code === 0 && baselineMatches[command],
+      "canonical fixture corpus was admitted with fixed counts",
+    );
+  }
+
+  const anchorReport = findings.anchors.report;
+  const anchorArgs = requiredArgs("anchors", fixture);
+  const anchorCountBoundary = await budgetBoundary(cliPath, fixture, anchorArgs, "--max-anchors", 2);
+  const anchorCountMatches = anchorCountBoundary.admitted.code === 1
+    && anchorCountBoundary.admittedReport?.complete === true
+    && anchorCountBoundary.admittedReport?.summary?.anchorsChecked === 2
+    && anchorCountBoundary.refused.code === 1
+    && noPartialPayload("anchors", anchorCountBoundary.refusedReport);
+  classifyExpected(leaves, "anchors", "budgets.max_anchors", "complete_extracted_anchor_occurrence_count", anchorCountMatches, "fixed anchor count N=2/N-1=1");
+  classifyExpected(leaves, "anchors", "budgets.N_and_N_minus_1", "exact_symmetric_boundary", anchorCountMatches, "fixed anchor count symmetric boundary");
+  classifyExpected(leaves, "anchors", "budgets.overflow", "refused_exit_1_with_required_and_admitted_values", anchorCountMatches, "anchor count overflow refused without payload");
+  classifyExpected(leaves, "anchors", "budgets.truncation_or_partial_result", "forbidden", anchorCountMatches, "anchor count refusal was not partial");
+
+  const stdoutBytes = Buffer.byteLength(findings.anchors.output.stdout, "utf8");
+  const anchorByteBoundary = await budgetBoundary(cliPath, fixture, anchorArgs, "--max-bytes", stdoutBytes);
+  const anchorByteMatches = anchorByteBoundary.admitted.code === 1
+    && Buffer.byteLength(anchorByteBoundary.admitted.stdout, "utf8") === stdoutBytes
+    && anchorByteBoundary.admittedReport?.summary?.units === 3
+    && anchorByteBoundary.admittedReport?.summary?.anchorsChecked === 2
+    && anchorByteBoundary.admittedReport?.summary?.diagnostics === 2
+    && anchorByteBoundary.refused.code === 1
+    && noPartialPayload("anchors", anchorByteBoundary.refusedReport);
+  classifyExpected(leaves, "anchors", "budgets.max_bytes", "UTF-8_size_of_compact_format_complete_summary_and_diagnostics_product", anchorByteMatches, `actual stdout UTF-8 bytes N=${stdoutBytes}/N-1`);
+  classifyExpected(leaves, "anchors", "budgets.N_and_N_minus_1", "exact_symmetric_boundary", anchorByteMatches, "actual stdout byte symmetric boundary");
+
+  const diagnosticFields = ["unitId", "field", "anchor"];
+  const diagnostics = anchorReport?.diagnostics ?? [];
+  const expectedEndColumn = 207;
+  const locationsMatch = diagnostics.length === 2 && diagnostics.every((diagnostic) => (
+    diagnostic.unitId === "definition.fixture"
+    && diagnostic.field === "meaning"
+    && diagnostic.pointer === "/units/0/meaning"
+    && diagnostic.range?.start?.line === 7
+    && diagnostic.range?.start?.column === 14
+    && diagnostic.range?.end?.line === 7
+    && diagnostic.range?.end?.column === expectedEndColumn
+  ));
+  classifyExpected(leaves, "anchors", "result.diagnostic_location", "exact_unit_ID_field_SourceMap_range_and_source_pointer", locationsMatch, "fixed YAML SourceMap anchor locations");
+  for (const [index, field] of diagnosticFields.entries()) {
+    classifyExpected(leaves, "anchors", `result.anchor_diagnostic_fields[${index}]`, field, diagnostics.every((entry) => Object.hasOwn(entry, field)), `diagnostics expose ${field}`);
+  }
+  for (const [index, field] of ["units", "anchorsChecked", "diagnostics"].entries()) {
+    classifyExpected(leaves, "anchors", `result.summary_fields[${index}]`, field, Object.hasOwn(anchorReport?.summary ?? {}, field), `summary exposes ${field}`);
+  }
+  const anchorOrder = diagnostics.map((entry) => entry.anchor);
+  const orderingMatches = JSON.stringify(anchorOrder) === JSON.stringify(["pnpm another-missing-script", "pnpm missing-script"]);
+  for (const [index, value] of ["unit_ID", "anchor_text", "field", "class"].entries()) {
+    classifyExpected(leaves, "anchors", `result.ordering.anchors[${index}]`, value, orderingMatches, `fixed diagnostics order=${JSON.stringify(anchorOrder)}`);
+  }
+
+  const originalBindings = await readFile(fixture.scopeBindings, "utf8");
+  let scopeExecution;
+  try {
+    const bindings = YAML.parse(originalBindings);
+    bindings.scopes[0].bindings[0].value = "missing/**/*.ts";
+    await writeFile(fixture.scopeBindings, YAML.stringify(bindings, { indent: 2, lineWidth: 0 }), "utf8");
+    const scopeArgs = [...anchorArgs];
+    scopeArgs.splice(-1, 0, "--scope-bindings", fixture.scopeBindings);
+    scopeExecution = await runCli(cliPath, fixture.root, scopeArgs);
+  } finally {
+    await writeFile(fixture.scopeBindings, originalBindings, "utf8");
+  }
+  const scopeDiagnostics = (parseJson(scopeExecution)?.diagnostics ?? []).filter((entry) => entry.scope !== undefined);
+  const scopeMatches = scopeDiagnostics.length === 1
+    && scopeDiagnostics[0].scope === "api.fixture"
+    && scopeDiagnostics[0].glob === "missing/**/*.ts";
+  for (const [index, field] of ["scope", "glob"].entries()) {
+    classifyExpected(leaves, "anchors", `result.scope_diagnostic_fields[${index}]`, field, scopeMatches && Object.hasOwn(scopeDiagnostics[0], field), `fixed scope diagnostic exposes ${field}`);
+    classifyExpected(leaves, "anchors", `result.ordering.scope_globs[${index}]`, field, scopeMatches, "one fixed scope/glob row is deterministically ordered");
+  }
+
+  const anchorHuman = await runCli(cliPath, fixture.root, anchorArgs.filter((entry) => entry !== "--json"));
+  classifyExpected(
+    leaves,
+    "anchors",
+    "result.human_and_json",
+    "required",
+    anchorHuman.code === 1 && anchorHuman.stdout.includes("nimicoding authority anchors:") && anchorReport?.format === contracts.anchors.surface.report_format,
+    "fixed finding rendered in human and JSON modes",
+  );
+
+  const consumerCounts = validReports.consumers.report?.consumers?.specConsumption?.counts ?? {};
+  const countNames = ["total", "canonical", "canonicalDead", "externalAuthority", "externalDead", "externalUnresolved", "unresolved"];
+  for (const [index, field] of countNames.entries()) {
+    classifyExpected(leaves, "consumers", `result.counts[${index}]`, field, Object.hasOwn(consumerCounts, field) && consumerCounts.total === 2, `fixed reference count field ${field}`);
+  }
+
+  const termsIndex = await runCli(cliPath, fixture.root, requiredArgs("terms", fixture));
+  const termsIndexReport = parseJson(termsIndex);
+  const termsDetail = validReports.terms.report?.terms;
+  const modeMatches = termsIndexReport?.terms?.mode === "index" && termsDetail?.mode === "detail";
+  for (const [index, mode] of ["index", "detail"].entries()) {
+    classifyExpected(leaves, "terms", `result.modes[${index}]`, mode, modeMatches, "fixed index and detail invocations");
+  }
+  for (const [index, field] of ["term", "classes", "unitCount", "units", "code", "codeReferences", "codeInventory"].entries()) {
+    classifyExpected(leaves, "terms", `result.detail_fields[${index}]`, field, Object.hasOwn(termsDetail ?? {}, field), `detail report exposes ${field}`);
+  }
+
+  classifyExpected(leaves, "terms", "result.byte_counts.scannedBytes", "selected_normative_authority_fields_plus_optional_decoded_code_inputs", validReports.terms.report?.scanned_bytes === 879, `fixed selected bytes=${validReports.terms.report?.scanned_bytes}`);
+  classifyExpected(leaves, "closed-sets", "result.byte_counts.scannedBytes", "normative_authority_fields_plus_decoded_proto_and_YAML_extractor_inputs", validReports["closed-sets"].report?.scanned_bytes === 510, `fixed selected bytes=${validReports["closed-sets"].report?.scanned_bytes}`);
+
+  for (const command of ["consumers", "terms", "closed-sets"]) {
+    const first = await runCli(cliPath, fixture.root, validReports[command].args);
+    const second = await runCli(cliPath, fixture.root, validReports[command].args);
+    classifyExpected(
+      leaves,
+      command,
+      "result.determinism",
+      "identical_inputs_produce_byte_identical_output",
+      first.code === second.code && Buffer.from(first.stdout).equals(Buffer.from(second.stdout)) && Buffer.from(first.stderr).equals(Buffer.from(second.stderr)),
+      "two identical invocations were byte-identical",
+    );
+  }
+}
+
+function summarize(leaves) {
+  const contractNames = [...new Set([...leaves.values()].map((leaf) => leaf.contract))];
+  const contracts = contractNames.map((contract) => {
+    const selected = [...leaves.values()].filter((leaf) => leaf.contract === contract);
+    const counts = Object.fromEntries(STATUS_NAMES.map((status) => [status, selected.filter((leaf) => leaf.status === status).length]));
+    return { contract, counts, leaves: selected };
+  });
+  const core = [...leaves.values()].filter((leaf) => (
+    leaf.path === "command"
+    || leaf.path.startsWith("surface.")
+    || leaf.path.startsWith("budgets.")
+    || leaf.path.startsWith("result.")
+  ));
+  const contradictions = [...leaves.values()].filter((leaf) => leaf.status === "contradicted");
+  const unmapped = [...leaves.values()].filter((leaf) => leaf.status === "unmapped");
+  return {
+    contracts,
+    contradictions,
+    unmapped,
+    coverageComplete: unmapped.length === 0,
+    enforcedComplete: core.every((leaf) => leaf.status === "verified"),
+    coreFailures: core.filter((leaf) => leaf.status !== "verified"),
+  };
+}
+
+async function runConformanceLane({ contractDirectory, cliPath, lane }) {
+  const contracts = {};
+  for (const [command, file] of Object.entries(PRODUCT_CONTRACTS)) {
+    contracts[command] = YAML.parse(await readFile(path.join(contractDirectory, file), "utf8"));
+  }
+  const authoring = YAML.parse(await readFile(path.join(contractDirectory, "authority-authoring.yaml"), "utf8"));
+  const leaves = createClassification(contracts);
+  addAuthoringClassification(leaves, authoring);
+  const fixture = await createRepositoryFixture();
+  try {
+    const validReports = await exerciseParserSurface(cliPath, fixture, contracts, leaves);
+    await exerciseRequiredCombinations(cliPath, fixture, contracts, authoring, leaves);
+    await exerciseCompleteAndBudgets(cliPath, fixture, contracts, leaves, validReports);
+    await exerciseGrammar(cliPath, fixture, leaves, validReports);
+    await addAnchorFinding(fixture);
+    const findings = await exerciseFindings(cliPath, fixture, contracts, leaves, lane);
+    classifyAnchorGrammar(leaves, contracts.anchors, findings.anchors);
+    await exerciseCoreClosure(cliPath, fixture, contracts, leaves, validReports, findings);
+    await exerciseRepositoryInventory(cliPath, fixture, contracts, leaves, validReports);
+
+    return { ...summarize(leaves), lane };
+  } finally {
+    await rm(fixture.root, { recursive: true, force: true });
+  }
+}
+
+export async function checkProductConformanceLeaves({
+  contractDirectory = path.join(packageRoot, "spec"),
+  cliPath = path.join(packageRoot, "bin", "nimicoding.mjs"),
+} = {}) {
+  return runConformanceLane({ contractDirectory, cliPath, lane: "worktree" });
+}
+
+export async function checkPackedProductConformance({ packRoot = packageRoot } = {}) {
+  const packed = await packedCli(packRoot);
+  try {
+    return await runConformanceLane({
+      contractDirectory: packed.contractDirectory,
+      cliPath: packed.cliPath,
+      lane: "packed",
+    });
+  } finally {
+    await packed.cleanup();
+  }
+}
+
+export function formatProductConformance(result) {
+  const lines = [
+    `product-conformance: lane=${result.lane}; coverageComplete=${result.coverageComplete}; enforcedComplete=${result.enforcedComplete}`,
+    ...result.contracts.map(({ contract, counts }) => (
+      `product-conformance: ${contract} {verified: ${counts.verified}, contradicted: ${counts.contradicted}, not_machine_checkable: ${counts.not_machine_checkable}, unmapped: ${counts.unmapped}}`
+    )),
+  ];
+  for (const leaf of result.contradictions) {
+    lines.push(`contradicted: ${leaf.contract} ${leaf.path} (${leaf.details.at(-1)})`);
+  }
+  lines.push("not_machine_checkable:");
+  for (const { leaves } of result.contracts) {
+    for (const leaf of leaves.filter((entry) => entry.status === "not_machine_checkable")) {
+      lines.push(`  ${leaf.contract} ${leaf.path} (${leaf.details.at(-1)})`);
+    }
+  }
+  lines.push("unmapped:");
+  for (const leaf of result.unmapped) lines.push(`  ${leaf.contract} ${leaf.path} = ${JSON.stringify(leaf.value)}`);
+  return `${lines.join("\n")}\n`;
+}
+
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("check-product-conformance.mjs")) {
+  try {
+    const result = process.argv.includes("--packed")
+      ? await checkPackedProductConformance()
+      : await checkProductConformanceLeaves();
+    process.stdout.write(formatProductConformance(result));
+    if (!result.enforcedComplete) process.exitCode = 1;
+  } catch (error) {
+    process.stderr.write(`product-conformance: could not execute gate: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}