@xenosystem/agent-cli 0.5.17

package/ownership/audit.mjs

@@ -0,0 +1,727 @@
+#!/usr/bin/env node
+
+// Keep this package-local file byte-identical in SDK and CLI release artifacts.
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import { builtinModules } from "node:module";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const CLASSIFICATIONS = new Set([
+  "xeno-owned",
+  "platform-api",
+  "external-runtime",
+  "build-only",
+  "test-oracle",
+  "temporary-runtime",
+  "forbidden",
+]);
+const LEVELS = ["pre-P1", "P1", "P2", "P3", "P4"];
+const SOURCE_EXTENSIONS = new Set([".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx"]);
+const NATIVE_EXTENSIONS = new Set([".node", ".dll", ".so", ".dylib", ".exe"]);
+const SOURCE_SKIP_DIRECTORIES = new Set([".git", "coverage", "dist", "node_modules", "release"]);
+const LEGACY_NODE_BUILTINS = new Set(builtinModules.map((name) => name.replace(/^node:/, "")));
+
+function parseJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function requireString(value, label, errors) {
+  if (typeof value !== "string" || value.trim().length === 0) errors.push(`${label} must be a non-empty string`);
+}
+
+function requireStringArray(value, label, errors) {
+  if (!Array.isArray(value) || value.length === 0 || value.some((entry) => typeof entry !== "string" || entry.length === 0)) {
+    errors.push(`${label} must be a non-empty string array`);
+  }
+}
+
+export function validateOwnershipPolicy(policy) {
+  const errors = [];
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) return ["policy must be an object"];
+  if (policy.schemaVersion !== 1) errors.push("schemaVersion must be 1");
+  requireString(policy.policyId, "policyId", errors);
+  if (!Number.isInteger(policy.policyRevision) || policy.policyRevision < 1) errors.push("policyRevision must be a positive integer");
+  requireString(policy.canonicalLocation, "canonicalLocation", errors);
+  if (!LEVELS.includes(policy.enforcedLevel)) errors.push(`unsupported enforcedLevel: ${policy.enforcedLevel}`);
+  if (!LEVELS.includes(policy.targetLevel) || policy.targetLevel === "pre-P1") errors.push(`unsupported targetLevel: ${policy.targetLevel}`);
+  requireStringArray(policy.xenoPackagePrefixes, "xenoPackagePrefixes", errors);
+  if (!policy.repositories || typeof policy.repositories !== "object") {
+    errors.push("repositories must be an object");
+  } else {
+    for (const [id, repository] of Object.entries(policy.repositories)) {
+      requireString(repository?.label, `repositories.${id}.label`, errors);
+      requireStringArray(repository?.manifestPaths, `repositories.${id}.manifestPaths`, errors);
+      requireStringArray(repository?.sourceRoots, `repositories.${id}.sourceRoots`, errors);
+      if (repository?.additionalOwnedSourceRoots !== undefined) {
+        requireStringArray(repository.additionalOwnedSourceRoots, `repositories.${id}.additionalOwnedSourceRoots`, errors);
+      }
+      requireString(repository?.reportDirectory, `repositories.${id}.reportDirectory`, errors);
+    }
+  }
+  for (const field of ["runtimeComponents", "builtinComponents", "platformBoundaries", "testOracles", "capabilityGates", "forbiddenPackages"]) {
+    if (!Array.isArray(policy[field])) errors.push(`${field} must be an array`);
+  }
+  for (const field of ["runtimeComponents", "builtinComponents", "platformBoundaries", "testOracles"]) {
+    for (const [index, component] of (policy[field] ?? []).entries()) {
+      requireString(component?.name, `${field}[${index}].name`, errors);
+      if (!CLASSIFICATIONS.has(component?.classification)) errors.push(`${field}[${index}] has an invalid classification`);
+      requireStringArray(component?.usedBy, `${field}[${index}].usedBy`, errors);
+      requireString(component?.replacement, `${field}[${index}].replacement`, errors);
+      requireString(component?.expiresAtMilestone, `${field}[${index}].expiresAtMilestone`, errors);
+      if (component?.artifactPathPrefixes !== undefined) {
+        requireStringArray(component.artifactPathPrefixes, `${field}[${index}].artifactPathPrefixes`, errors);
+      }
+    }
+  }
+  if (policy.developmentPolicy?.classification !== "build-only") {
+    errors.push("developmentPolicy.classification must be build-only");
+  }
+  for (const field of ["guide", "implementationRecordTemplate", "provenanceReviewTemplate"]) {
+    requireString(policy.cleanRoomProtocol?.[field], `cleanRoomProtocol.${field}`, errors);
+  }
+  if (!["engineering-draft", "counsel-approved"].includes(policy.cleanRoomProtocol?.status)) {
+    errors.push("cleanRoomProtocol.status must be engineering-draft or counsel-approved");
+  }
+  if (typeof policy.cleanRoomProtocol?.counselApprovalRequired !== "boolean") {
+    errors.push("cleanRoomProtocol.counselApprovalRequired must be boolean");
+  }
+  for (const [index, gate] of (policy.capabilityGates ?? []).entries()) {
+    requireString(gate?.id, `capabilityGates[${index}].id`, errors);
+    if (!LEVELS.includes(gate?.requiredFor) || gate.requiredFor === "pre-P1") {
+      errors.push(`capabilityGates[${index}] has an invalid requiredFor level`);
+    }
+    if (typeof gate?.achieved !== "boolean") errors.push(`capabilityGates[${index}].achieved must be boolean`);
+    requireString(gate?.evidence, `capabilityGates[${index}].evidence`, errors);
+  }
+  return errors;
+}
+
+function packageNameFromLockPath(lockPath, entry) {
+  if (typeof entry.name === "string" && entry.name.length > 0) return entry.name;
+  const normalized = lockPath.replace(/\\/g, "/");
+  const marker = "/node_modules/";
+  const last = normalized.includes(marker)
+    ? normalized.slice(normalized.lastIndexOf(marker) + marker.length)
+    : normalized.startsWith("node_modules/")
+      ? normalized.slice("node_modules/".length)
+      : "";
+  if (!last) return undefined;
+  const segments = last.split("/");
+  return segments[0]?.startsWith("@") ? `${segments[0]}/${segments[1]}` : segments[0];
+}
+
+function packageNameFromSpecifier(specifier) {
+  if (specifier.startsWith("node:")) return specifier;
+  if (specifier.startsWith("@")) return specifier.split("/").slice(0, 2).join("/");
+  return specifier.split("/")[0];
+}
+
+function isBareSpecifier(specifier) {
+  return !specifier.startsWith(".") && !specifier.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(specifier);
+}
+
+function walkSourceFiles(root, output) {
+  if (!existsSync(root)) return;
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!SOURCE_SKIP_DIRECTORIES.has(entry.name)) walkSourceFiles(join(root, entry.name), output);
+      continue;
+    }
+    if (entry.isFile() && SOURCE_EXTENSIONS.has(extname(entry.name))) output.push(join(root, entry.name));
+  }
+}
+
+function walkArtifactFiles(root, output) {
+  if (!existsSync(root)) return;
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) {
+      walkArtifactFiles(path, output);
+      continue;
+    }
+    if (entry.isFile()) output.push(path);
+  }
+}
+
+function isWithin(candidate, parent) {
+  const path = relative(parent, candidate);
+  return path === "" || (!path.startsWith("..") && !isAbsolute(path));
+}
+
+function packageRootForInstallation(root, label) {
+  const segments = label.split("/");
+  return join(root, "node_modules", ...segments);
+}
+
+function artifactDistRoots(root, repositoryId, repository, installation) {
+  if (installation) return [join(packageRootForInstallation(root, repository.label), "dist")];
+  return repositoryId === "cli"
+    ? [join(root, "apps", "xeno-agent-cli", "dist")]
+    : [join(root, "dist")];
+}
+
+function ownedBundleInput(root, repository, input) {
+  const candidate = resolve(root, input);
+  return [...repository.sourceRoots, ...(repository.additionalOwnedSourceRoots ?? [])]
+    .some((sourceRoot) => isWithin(candidate, resolve(root, sourceRoot)));
+}
+
+function bundleOutputsByInput(metafile) {
+  const outputs = new Map();
+  for (const [outputPath, output] of Object.entries(metafile.outputs ?? {})) {
+    for (const [inputPath, contribution] of Object.entries(output.inputs ?? {})) {
+      const current = outputs.get(inputPath) ?? [];
+      current.push({ path: outputPath, bytesInOutput: contribution.bytesInOutput ?? 0 });
+      outputs.set(inputPath, current);
+    }
+  }
+  return outputs;
+}
+
+function collectArtifactComponents(root, repositoryId, repository, policy, installation) {
+  const components = [];
+  const violations = [];
+  const distRoots = artifactDistRoots(root, repositoryId, repository, installation);
+  const bundleFiles = [];
+  for (const distRoot of distRoots) {
+    const files = [];
+    walkArtifactFiles(distRoot, files);
+    bundleFiles.push(...files.filter((path) => /^metafile-(?:esm|cjs|iife)\.json$/i.test(path.split(/[\\/]/).at(-1) ?? "")));
+  }
+  if (bundleFiles.length === 0) {
+    violations.push("artifact audit found no esbuild metafile; build with bundle provenance enabled before auditing");
+  }
+
+  for (const metafilePath of bundleFiles) {
+    let metafile;
+    try {
+      metafile = parseJson(metafilePath);
+    } catch (error) {
+      violations.push(`invalid bundle metafile ${relative(root, metafilePath)}: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    const outputs = bundleOutputsByInput(metafile);
+    for (const [inputPath, input] of Object.entries(metafile.inputs ?? {})) {
+      const packageName = packageNameFromLockPath(inputPath, {});
+      const result = packageName
+        ? classify(policy, packageName, "bundle-input")
+        : ownedBundleInput(root, repository, inputPath)
+          ? { classification: "xeno-owned", policy: undefined }
+          : { classification: "unclassified", policy: undefined };
+      components.push({
+        id: `bundle:${relative(root, metafilePath).replace(/\\/g, "/")}:${inputPath}`,
+        name: packageName ?? inputPath,
+        scope: "bundle-input",
+        classification: result.classification,
+        path: inputPath,
+        evidencePath: relative(root, metafilePath).replace(/\\/g, "/"),
+        sourceBytes: input.bytes,
+        outputs: outputs.get(inputPath) ?? [],
+        replacement: result.policy?.replacement,
+        expiresAtMilestone: result.policy?.expiresAtMilestone,
+      });
+      if (result.classification === "unclassified" || result.classification === "forbidden") {
+        violations.push(`${inputPath} is ${result.classification} in production bundle evidence`);
+      }
+    }
+  }
+
+  const ownPackageRoot = installation
+    ? packageRootForInstallation(root, repository.label)
+    : repositoryId === "cli"
+      ? join(root, "apps", "xeno-agent-cli")
+      : root;
+  const nativeRoots = installation
+    ? [join(root, "node_modules")]
+    : repositoryId === "cli"
+      ? [...distRoots, join(root, "apps", "xeno-agent-cli", "native")]
+      : [...distRoots, join(root, "native")];
+  const nativeFiles = [];
+  for (const nativeRoot of nativeRoots) {
+    const files = [];
+    walkArtifactFiles(nativeRoot, files);
+    nativeFiles.push(...files.filter((path) =>
+      NATIVE_EXTENSIONS.has(extname(path).toLowerCase())
+      || artifactComponentPolicy(policy, relative(ownPackageRoot, path)),
+    ));
+  }
+  for (const nativePath of nativeFiles) {
+    const relativePath = relative(root, nativePath).replace(/\\/g, "/");
+    const artifactPolicy = artifactComponentPolicy(policy, relative(ownPackageRoot, nativePath));
+    const packageName = packageNameFromLockPath(relativePath, {});
+    const result = artifactPolicy
+      ? { classification: artifactPolicy.classification, policy: artifactPolicy }
+      : packageName
+      ? classify(policy, packageName, "native-artifact")
+      : isWithin(nativePath, ownPackageRoot)
+        ? { classification: "xeno-owned", policy: undefined }
+        : { classification: "unclassified", policy: undefined };
+    components.push({
+      id: `native:${relativePath}`,
+      name: artifactPolicy?.name ?? packageName ?? relativePath,
+      scope: "native-artifact",
+      classification: result.classification,
+      path: relativePath,
+      sha256: sha256(readFileSync(nativePath)),
+      replacement: result.policy?.replacement,
+      expiresAtMilestone: result.policy?.expiresAtMilestone,
+    });
+    if (result.classification === "unclassified" || result.classification === "forbidden") {
+      violations.push(`${relativePath} is ${result.classification} as a native artifact`);
+    }
+  }
+  return { components, violations, bundleMetafiles: bundleFiles.length, nativeArtifacts: nativeFiles.length };
+}
+
+function collectSourceSpecifiers(root, sourceRoots) {
+  const files = [];
+  for (const sourceRoot of sourceRoots) walkSourceFiles(join(root, sourceRoot), files);
+  const findings = [];
+  const patterns = [
+    /^\s*(?:import|export)\s+(?:type\s+)?(?:[^;\n]*?\s+from\s+)?["']([^"']+)["']/gm,
+    /^[^"'`\/]*\bimport\s*\(\s*["']([^"']+)["']\s*\)/gm,
+    /^[^"'`\/]*\brequire\s*\(\s*["']([^"']+)["']\s*\)/gm,
+  ];
+  for (const path of files) {
+    const text = readFileSync(path, "utf8");
+    for (const pattern of patterns) {
+      pattern.lastIndex = 0;
+      for (let match = pattern.exec(text); match; match = pattern.exec(text)) {
+        const specifier = match[1];
+        if (!specifier || !isBareSpecifier(specifier)) continue;
+        findings.push({
+          specifier,
+          name: packageNameFromSpecifier(specifier),
+          path: relative(root, path).replace(/\\/g, "/"),
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+function componentPolicy(policy, name) {
+  return [...policy.runtimeComponents, ...policy.builtinComponents, ...(policy.testOracles ?? [])]
+    .find((component) => component.name === name);
+}
+
+function artifactComponentPolicy(policy, path) {
+  const normalized = path.replace(/\\/g, "/");
+  return [...policy.runtimeComponents, ...policy.builtinComponents]
+    .find((component) => (component.artifactPathPrefixes ?? []).some((prefix) => {
+      const normalizedPrefix = prefix.replace(/^\/+|\/+$/g, "");
+      return normalized === normalizedPrefix
+        || normalized.startsWith(`${normalizedPrefix}/`)
+        || normalized.includes(`/${normalizedPrefix}/`);
+    }));
+}
+
+function isForbidden(policy, name) {
+  return policy.forbiddenPackages.some((forbidden) => name === forbidden || name.startsWith(`${forbidden}-`));
+}
+
+function classify(policy, name, scope) {
+  if (isForbidden(policy, name)) return { classification: "forbidden", policy: undefined };
+  if (policy.xenoPackagePrefixes.some((prefix) => name.startsWith(prefix))) {
+    return { classification: "xeno-owned", policy: undefined };
+  }
+  if ((name.startsWith("node:") || LEGACY_NODE_BUILTINS.has(name)) && !componentPolicy(policy, name)) {
+    return { classification: "external-runtime", policy: { replacement: "standalone-runtime-decision", expiresAtMilestone: "PROPRIETARY-RUNTIME-1" } };
+  }
+  if (scope === "development") return { classification: policy.developmentPolicy.classification, policy: undefined };
+  const matched = componentPolicy(policy, name);
+  return matched
+    ? { classification: matched.classification, policy: matched }
+    : { classification: "unclassified", policy: undefined };
+}
+
+function directDeclarations(root, repository) {
+  const declarations = [];
+  for (const manifestPath of repository.manifestPaths) {
+    const absolute = join(root, manifestPath);
+    if (!existsSync(absolute)) continue;
+    const manifest = parseJson(absolute);
+    for (const [field, scope] of [
+      ["dependencies", "runtime"],
+      ["optionalDependencies", "runtime-optional"],
+      ["peerDependencies", "peer"],
+      ["devDependencies", "development"],
+    ]) {
+      for (const [name, requested] of Object.entries(manifest[field] ?? {})) {
+        declarations.push({ name, requested, scope, manifestPath, field });
+      }
+    }
+  }
+  return declarations;
+}
+
+function determineAchievedLevel(policy, components, violations) {
+  if (violations.length > 0 || components.some((component) => component.classification === "temporary-runtime" || component.classification === "forbidden")) {
+    return "pre-P1";
+  }
+  const levels = ["P1", "P2", "P3", "P4"];
+  let achieved = "pre-P1";
+  for (const level of levels) {
+    const required = policy.capabilityGates.filter((gate) => LEVELS.indexOf(gate.requiredFor) <= LEVELS.indexOf(level));
+    if (required.every((gate) => gate.achieved)) achieved = level;
+    else break;
+  }
+  return achieved;
+}
+
+function summarizeCounts(components, key) {
+  const counts = {};
+  for (const component of components) counts[component[key]] = (counts[component[key]] ?? 0) + 1;
+  return Object.fromEntries(Object.entries(counts).sort(([left], [right]) => left.localeCompare(right)));
+}
+
+function renderMarkdown(report) {
+  const runtimeExceptions = report.components.filter((component) =>
+    ["runtime", "runtime-optional", "peer", "source-import", "builtin"].includes(component.scope) &&
+    !["xeno-owned", "platform-api"].includes(component.classification),
+  );
+  const lines = [
+    "# Ownership Inventory",
+    "",
+    `Generated: ${report.generatedAt}`,
+    "",
+    `Repository: \`${report.repository.label}\``,
+    "",
+    `Policy: \`${report.policy.id}\` revision ${report.policy.revision} (SHA-256 \`${report.policy.sha256}\`)`,
+    "",
+    `Achieved level: **${report.achievedLevel}**`,
+    "",
+    `Target level: **${report.policy.targetLevel}**`,
+    "",
+    "## Scope Summary",
+    "",
+    "| Scope | Count |",
+    "| --- | ---: |",
+    ...Object.entries(report.countsByScope).map(([scope, count]) => `| ${scope} | ${count} |`),
+    "",
+    "## Classification Summary",
+    "",
+    "| Classification | Count |",
+    "| --- | ---: |",
+    ...Object.entries(report.countsByClassification).map(([classification, count]) => `| ${classification} | ${count} |`),
+    "",
+    "## Non-Xeno Runtime Boundaries",
+    "",
+    ...(runtimeExceptions.length === 0
+      ? ["None."]
+      : [
+          "| Component | Scope | Classification | Version/request | Replacement milestone |",
+          "| --- | --- | --- | --- | --- |",
+          ...runtimeExceptions.map((component) =>
+            `| \`${component.name}\` | ${component.scope} | ${component.classification} | ${component.version ?? component.requested ?? "-"} | ${component.expiresAtMilestone ?? "-"} |`,
+          ),
+        ]),
+    "",
+    "## Violations",
+    "",
+    ...(report.violations.length === 0 ? ["None."] : report.violations.map((violation) => `- ${violation}`)),
+    "",
+  ];
+  return lines.join("\n");
+}
+
+const REPORT_PARTITIONS = [
+  {
+    id: "runtime",
+    title: "Runtime ownership",
+    include: (component) => ["runtime", "runtime-optional", "peer", "source-import", "builtin"].includes(component.scope),
+  },
+  {
+    id: "development",
+    title: "Development ownership",
+    include: (component) => component.scope === "development",
+  },
+  {
+    id: "test-oracles",
+    title: "Test-oracle ownership",
+    include: (component) => component.scope === "test-oracle" || component.classification === "test-oracle",
+  },
+  {
+    id: "platform",
+    title: "Platform boundaries",
+    include: (component) => component.scope === "platform",
+  },
+  {
+    id: "artifacts",
+    title: "Bundle and native artifacts",
+    include: (component) => component.scope === "bundle-input" || component.scope === "native-artifact",
+  },
+];
+
+function partitionReport(report, partition) {
+  const components = report.components.filter(partition.include);
+  return {
+    generatedAt: report.generatedAt,
+    partition: partition.id,
+    title: partition.title,
+    repository: report.repository,
+    policy: report.policy,
+    achievedLevel: report.achievedLevel,
+    componentCount: components.length,
+    countsByScope: summarizeCounts(components, "scope"),
+    countsByClassification: summarizeCounts(components, "classification"),
+    components,
+  };
+}
+
+function renderPartitionMarkdown(partition) {
+  const lines = [
+    `# ${partition.title}`,
+    "",
+    `Generated: ${partition.generatedAt}`,
+    "",
+    `Repository: \`${partition.repository.label}\``,
+    "",
+    `Policy: \`${partition.policy.id}\` revision ${partition.policy.revision}`,
+    "",
+    `Achieved level: **${partition.achievedLevel}**`,
+    "",
+    `Component count: **${partition.componentCount}**`,
+    "",
+    "| Component | Scope | Classification | Version/request | Evidence |",
+    "| --- | --- | --- | --- | --- |",
+    ...partition.components.map((component) =>
+      `| \`${component.name}\` | ${component.scope} | ${component.classification} | ${component.version ?? component.requested ?? "-"} | \`${component.evidencePath ?? component.path ?? "-"}\` |`,
+    ),
+    "",
+  ];
+  return lines.join("\n");
+}
+
+export function auditOwnership(options) {
+  const root = resolve(options.root);
+  const policyPath = resolve(options.policyPath);
+  const policyText = readFileSync(policyPath, "utf8");
+  const policy = JSON.parse(policyText);
+  const policyErrors = validateOwnershipPolicy(policy);
+  if (policyErrors.length > 0) throw new Error(`Ownership policy validation failed:\n- ${policyErrors.join("\n- ")}`);
+  const repository = policy.repositories[options.repositoryId];
+  if (!repository) throw new Error(`Ownership policy does not define repository ${options.repositoryId}`);
+  const lockPath = join(root, "package-lock.json");
+  if (!existsSync(lockPath)) throw new Error(`Ownership audit requires ${lockPath}`);
+  const lock = parseJson(lockPath);
+  if (lock.lockfileVersion !== 3 || !lock.packages || typeof lock.packages !== "object") {
+    throw new Error("Ownership audit requires an npm lockfileVersion 3 packages map");
+  }
+
+  const components = [];
+  const violations = [];
+  const evidenceRoot = options.installation
+    ? packageRootForInstallation(root, repository.label)
+    : options.repositoryId === "cli"
+      ? join(root, "apps", "xeno-agent-cli")
+      : root;
+  for (const path of [
+    policy.cleanRoomProtocol.guide,
+    policy.cleanRoomProtocol.implementationRecordTemplate,
+    policy.cleanRoomProtocol.provenanceReviewTemplate,
+  ]) {
+    if (!existsSync(join(evidenceRoot, path))) violations.push(`required clean-room evidence file is missing: ${path}`);
+  }
+  const seenDeclarations = new Set();
+  for (const [lockEntryPath, entry] of Object.entries(lock.packages)) {
+    if (entry.link === true) continue;
+    const name = packageNameFromLockPath(lockEntryPath, entry);
+    if (!name) continue;
+    if (options.installation && lockEntryPath === "") continue;
+    const scope = entry.dev === true ? "development" : entry.optional === true ? "runtime-optional" : "runtime";
+    const result = classify(policy, name, scope);
+    const component = {
+      id: `lock:${lockEntryPath || "."}`,
+      name,
+      version: entry.version,
+      license: entry.license,
+      scope,
+      classification: result.classification,
+      path: lockEntryPath || ".",
+      installed: lockEntryPath === "" ? true : existsSync(join(root, lockEntryPath)),
+      replacement: result.policy?.replacement,
+      expiresAtMilestone: result.policy?.expiresAtMilestone,
+    };
+    components.push(component);
+    seenDeclarations.add(`${scope}:${name}`);
+    if (component.classification === "unclassified" || component.classification === "forbidden") {
+      violations.push(`${name}${component.version ? `@${component.version}` : ""} is ${component.classification} in ${scope}`);
+    }
+  }
+
+  if (!options.installation) {
+    for (const declaration of directDeclarations(root, repository)) {
+      const effectiveScope = declaration.scope === "peer" ? "peer" : declaration.scope;
+      if (seenDeclarations.has(`${effectiveScope}:${declaration.name}`)) continue;
+      const result = classify(policy, declaration.name, effectiveScope);
+      components.push({
+        id: `manifest:${declaration.manifestPath}:${declaration.field}:${declaration.name}`,
+        name: declaration.name,
+        requested: declaration.requested,
+        scope: effectiveScope,
+        classification: result.classification,
+        path: declaration.manifestPath,
+        installed: false,
+        replacement: result.policy?.replacement,
+        expiresAtMilestone: result.policy?.expiresAtMilestone,
+      });
+      if (result.classification === "unclassified" || result.classification === "forbidden") {
+        violations.push(`${declaration.name}@${declaration.requested} is ${result.classification} in ${effectiveScope}`);
+      }
+    }
+
+    const sourceSeen = new Set();
+    for (const finding of collectSourceSpecifiers(root, repository.sourceRoots)) {
+      const key = `${finding.name}:${finding.path}`;
+      if (sourceSeen.has(key)) continue;
+      sourceSeen.add(key);
+      const result = classify(policy, finding.name, "source-import");
+      components.push({
+        id: `source:${finding.path}:${finding.name}`,
+        name: finding.name,
+        specifier: finding.specifier,
+        scope: "source-import",
+        classification: result.classification,
+        path: finding.path,
+        installed: undefined,
+        replacement: result.policy?.replacement,
+        expiresAtMilestone: result.policy?.expiresAtMilestone,
+      });
+      if (result.classification === "unclassified" || result.classification === "forbidden") {
+        violations.push(`${finding.specifier} is ${result.classification} in source ${finding.path}`);
+      }
+    }
+  }
+
+  let artifactEvidence = { enabled: false, bundleMetafiles: 0, nativeArtifacts: 0 };
+  if (options.artifacts) {
+    const artifacts = collectArtifactComponents(root, options.repositoryId, repository, policy, options.installation);
+    components.push(...artifacts.components);
+    violations.push(...artifacts.violations);
+    artifactEvidence = {
+      enabled: true,
+      bundleMetafiles: artifacts.bundleMetafiles,
+      nativeArtifacts: artifacts.nativeArtifacts,
+    };
+  }
+
+  for (const builtin of policy.builtinComponents) {
+    if (!builtin.usedBy.includes(options.repositoryId)) continue;
+    components.push({
+      id: `builtin:${builtin.name}`,
+      name: builtin.name,
+      scope: "builtin",
+      classification: builtin.classification,
+      replacement: builtin.replacement,
+      expiresAtMilestone: builtin.expiresAtMilestone,
+    });
+  }
+  for (const boundary of policy.platformBoundaries) {
+    if (!boundary.usedBy.includes(options.repositoryId)) continue;
+    components.push({
+      id: `platform:${boundary.name}`,
+      name: boundary.name,
+      scope: "platform",
+      classification: boundary.classification,
+      replacement: boundary.replacement,
+      expiresAtMilestone: boundary.expiresAtMilestone,
+    });
+  }
+
+  const uniqueViolations = [...new Set(violations)].sort();
+  const achievedLevel = determineAchievedLevel(policy, components, uniqueViolations);
+  if (LEVELS.indexOf(achievedLevel) < LEVELS.indexOf(policy.enforcedLevel)) {
+    uniqueViolations.push(`achieved level ${achievedLevel} is below enforced level ${policy.enforcedLevel}`);
+  }
+  const report = {
+    generatedAt: new Date().toISOString(),
+    repository: { id: options.repositoryId, label: repository.label, root },
+    policy: {
+      id: policy.policyId,
+      revision: policy.policyRevision,
+      sha256: sha256(policyText),
+      canonicalLocation: policy.canonicalLocation,
+      enforcedLevel: policy.enforcedLevel,
+      targetLevel: policy.targetLevel,
+    },
+    achievedLevel,
+    countsByScope: summarizeCounts(components, "scope"),
+    countsByClassification: summarizeCounts(components, "classification"),
+    violations: uniqueViolations,
+    capabilityGates: policy.capabilityGates,
+    artifactEvidence,
+    components: components.sort((left, right) => left.scope.localeCompare(right.scope) || left.name.localeCompare(right.name) || left.id.localeCompare(right.id)),
+  };
+
+  if (options.write) {
+    const reportDirectory = join(root, repository.reportDirectory);
+    mkdirSync(reportDirectory, { recursive: true });
+    writeFileSync(join(reportDirectory, "ownership-inventory.json"), `${JSON.stringify(report, null, 2)}\n`, "utf8");
+    writeFileSync(join(reportDirectory, "ownership-inventory.md"), renderMarkdown(report), "utf8");
+    for (const definition of REPORT_PARTITIONS) {
+      const partition = partitionReport(report, definition);
+      writeFileSync(join(reportDirectory, `ownership-${definition.id}.json`), `${JSON.stringify(partition, null, 2)}\n`, "utf8");
+      writeFileSync(join(reportDirectory, `ownership-${definition.id}.md`), renderPartitionMarkdown(partition), "utf8");
+    }
+  }
+  return report;
+}
+
+function parseArguments(argv) {
+  const options = {
+    root: process.cwd(),
+    repositoryId: undefined,
+    policyPath: join(dirname(fileURLToPath(import.meta.url)), "ownership-policy.json"),
+    write: false,
+    installation: false,
+    json: false,
+    artifacts: false,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--repo") options.repositoryId = argv[++index];
+    else if (arg === "--root") options.root = argv[++index];
+    else if (arg === "--policy") options.policyPath = argv[++index];
+    else if (arg === "--write") options.write = true;
+    else if (arg === "--installation") options.installation = true;
+    else if (arg === "--json") options.json = true;
+    else if (arg === "--artifacts") options.artifacts = true;
+    else throw new Error(`Unknown ownership audit argument: ${arg}`);
+  }
+  if (!options.repositoryId) throw new Error("Usage: node ownership/audit.mjs --repo <sdk|cli> [--root path] [--write] [--installation] [--artifacts] [--json]");
+  return options;
+}
+
+async function main() {
+  const options = parseArguments(process.argv.slice(2));
+  const report = auditOwnership(options);
+  if (options.json) process.stdout.write(`${JSON.stringify(report)}\n`);
+  else {
+    console.log(
+      `Ownership audit: ${report.repository.label} achieved ${report.achievedLevel}; ` +
+      `target ${report.policy.targetLevel}; ${report.components.length} component records; ` +
+      `${report.violations.length} violation(s).`,
+    );
+  }
+  if (report.violations.length > 0) process.exitCode = 1;
+}
+
+const invokedPath = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : undefined;
+if (invokedPath === import.meta.url) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}