@nimiplatform/nimi-coding 0.4.0 → 0.6.0

package/cli/lib/authority/impact.mjs

@@ -1,21 +1,11 @@
 import { Buffer } from "node:buffer";
-import { lstat, readFile, stat } from "node:fs/promises";
-import path from "node:path";
-import YAML from "yaml";
 
-import { compareText, makeDiagnostic, portablePath, sortDiagnostics } from "./diagnostics.mjs";
+import { compareText, makeDiagnostic } from "./diagnostics.mjs";
 import { diffAuthorityPaths } from "./diff.mjs";
 
-const contractUrl = new URL("../../../contracts/authority-impact-dispositions.schema.yaml", import.meta.url);
-const IMPACT_FORMAT = "nimicoding.authority-impact/v1";
+const IMPACT_FORMAT = "nimicoding.authority-impact/v2";
 const IMPACT_RELATIONS = new Set(["applies_to", "supersedes"]);
 
-async function rootFor(inputPath) {
-  const absolute = path.resolve(inputPath);
-  const info = await stat(absolute);
-  return info.isDirectory() ? absolute : path.dirname(absolute);
-}
-
 function impactBudgetDiagnostic(requiredBytes, maxBytes) {
   return makeDiagnostic({
     code: "AUTH_IMPACT_BUDGET",
@@ -44,84 +34,11 @@ function overBudget(diffResult, impact, maxBytes) {
       payloadBytes,
       diff: null,
       impact: null,
+      partial: false,
     },
   };
 }
 
-function invalidDisposition(file, reason) {
-  return makeDiagnostic({
-    code: "AUTH_IMPACT_DISPOSITION_INVALID",
-    file: path.basename(file),
-    range: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
-    pointer: "",
-    reason,
-    repair: "declare each exact impacted rule consumer and test disposition with addressed status and explicit evidence",
-  });
-}
-
-function exactObject(value, fields) {
-  return value !== null && typeof value === "object" && !Array.isArray(value)
-    && Object.keys(value).every((key) => fields.includes(key));
-}
-
-async function loadDispositions(file, label = file) {
-  const absolute = path.resolve(file);
-  let bytes;
-  try {
-    const info = await lstat(absolute);
-    if (info.isSymbolicLink() || !info.isFile()) {
-      return { ok: false, diagnostics: [invalidDisposition(label, "dispositions must be one regular non-symlink YAML file")] };
-    }
-    bytes = await readFile(absolute);
-  } catch (error) {
-    return { ok: false, diagnostics: [invalidDisposition(label, `disposition file is not readable: ${error.message}`)] };
-  }
-  const contractText = await readFile(contractUrl, "utf8");
-  let text;
-  try {
-    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-  } catch {
-    return { ok: false, diagnostics: [invalidDisposition(label, "disposition bytes are not valid UTF-8")] };
-  }
-  const document = YAML.parseDocument(text, { uniqueKeys: true, version: "1.2" });
-  if (document.errors.length > 0) return { ok: false, diagnostics: [invalidDisposition(label, document.errors[0].message)] };
-  let data;
-  try {
-    data = document.toJS({ maxAliasCount: 0 });
-  } catch (error) {
-    return { ok: false, diagnostics: [invalidDisposition(label, error.message)] };
-  }
-  const contract = YAML.parse(contractText);
-  if (!exactObject(data, contract.fields.top) || data.format !== contract.format || !Array.isArray(data.rules)) {
-    return { ok: false, diagnostics: [invalidDisposition(label, "dispositions require the exact format and rules list")] };
-  }
-  const entries = new Map();
-  const ruleIds = new Set();
-  const identifier = new RegExp(contract.identifier_pattern);
-  for (const rule of data.rules) {
-    if (!exactObject(rule, contract.fields.rule) || !identifier.test(rule.id) || !Array.isArray(rule.consumers) || !exactObject(rule.test, contract.fields.test)) {
-      return { ok: false, diagnostics: [invalidDisposition(label, "each rule requires exact id, consumers, and test fields")] };
-    }
-    if (ruleIds.has(rule.id)) return { ok: false, diagnostics: [invalidDisposition(label, `duplicate rule disposition: ${rule.id}`)] };
-    ruleIds.add(rule.id);
-    for (const consumer of rule.consumers) {
-      if (!exactObject(consumer, contract.fields.consumer) || !identifier.test(consumer.scope) || consumer.status !== contract.status || typeof consumer.evidence !== "string" || consumer.evidence.trim() !== consumer.evidence || consumer.evidence.length === 0) {
-        return { ok: false, diagnostics: [invalidDisposition(label, `invalid consumer disposition for ${rule.id}`)] };
-      }
-      const key = `${rule.id}\0consumer\0${consumer.scope}`;
-      if (entries.has(key)) return { ok: false, diagnostics: [invalidDisposition(label, `duplicate disposition for ${rule.id} consumer ${consumer.scope}`)] };
-      entries.set(key, { ruleId: rule.id, type: "consumer", target: consumer.scope, status: consumer.status, evidence: consumer.evidence });
-    }
-    if (rule.test.status !== contract.status || typeof rule.test.evidence !== "string" || rule.test.evidence.trim() !== rule.test.evidence || rule.test.evidence.length === 0) {
-      return { ok: false, diagnostics: [invalidDisposition(label, `invalid test disposition for ${rule.id}`)] };
-    }
-    const testKey = `${rule.id}\0test\0${rule.id}`;
-    if (entries.has(testKey)) return { ok: false, diagnostics: [invalidDisposition(label, `duplicate rule disposition: ${rule.id}`)] };
-    entries.set(testKey, { ruleId: rule.id, type: "test", target: rule.id, status: rule.test.status, evidence: rule.test.evidence });
-  }
-  return { ok: true, diagnostics: [], entries };
-}
-
 function allUnits(diffResult) {
   const units = new Map();
   for (const compiled of [diffResult.before, diffResult.after]) {
@@ -162,7 +79,7 @@ function impactedIds(diffResult) {
   return [...selected].sort(compareText);
 }
 
-function requiredObligations(diffResult, impacted) {
+function declaredObligations(diffResult, impacted) {
   const before = new Map(diffResult.before.ir.units.map((unit) => [unit.id, unit]));
   const after = new Map(diffResult.after.ir.units.map((unit) => [unit.id, unit]));
   const obligations = [];
@@ -176,77 +93,33 @@ function requiredObligations(diffResult, impacted) {
   return obligations;
 }
 
-async function unitLocation(diffResult, id) {
-  for (const [compiled, inputPath] of [[diffResult.after, diffResult.afterPath], [diffResult.before, diffResult.beforePath]]) {
-    const index = compiled.ir.units.findIndex((unit) => unit.id === id);
-    if (index < 0) continue;
-    const mapped = compiled.sourceMap.fields[`/units/${index}/id`];
-    return { ...mapped, file: portablePath(mapped.file, await rootFor(inputPath)) };
-  }
-  return { file: ".", range: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } }, sourcePointer: "/id" };
-}
-
-export async function impactAuthorityPaths(beforePath, afterPath, dispositionsPath, { maxBytes = null, dispositionLabel = null } = {}) {
-  const diffResult = await diffAuthorityPaths(beforePath, afterPath);
-  if (!diffResult.ok) return { ...diffResult, impact: null };
-  diffResult.beforePath = beforePath;
-  diffResult.afterPath = afterPath;
-  const parsed = await loadDispositions(dispositionsPath, dispositionLabel ?? dispositionsPath);
-  if (!parsed.ok) {
-    const budget = overBudget(diffResult, null, maxBytes);
-    if (budget.failure) return budget.failure;
-    return {
-      ok: false,
-      diagnostics: parsed.diagnostics,
-      fileCount: diffResult.fileCount,
-      unitCount: 0,
-      payloadBytes: budget.payloadBytes,
-      diff: diffResult.diff,
-      impact: null,
-    };
-  }
+export function impactAuthorityDiff(diffResult, { maxBytes = null } = {}) {
+  if (!diffResult.ok) return { ...diffResult, impact: null, partial: false };
   const impacted = impactedIds(diffResult);
   const units = allUnits(diffResult);
-  const required = requiredObligations(diffResult, impacted);
-  const requiredKeys = new Set(required.map((item) => `${item.ruleId}\0${item.type}\0${item.target}`));
-  const diagnostics = [];
-  for (const obligation of required) {
-    const key = `${obligation.ruleId}\0${obligation.type}\0${obligation.target}`;
-    if (parsed.entries.has(key)) continue;
-    const mapped = await unitLocation(diffResult, obligation.ruleId);
-    diagnostics.push(makeDiagnostic({
-      code: "AUTH_IMPACT_UNDISPOSED",
-      file: mapped.file,
-      range: mapped.range,
-      pointer: mapped.sourcePointer,
-      reason: `${obligation.type} obligation is not disposed for ${obligation.ruleId}: ${obligation.target}`,
-      repair: "add an addressed disposition with explicit evidence; do not infer completion",
-    }));
-  }
-  for (const [key, disposition] of parsed.entries) {
-    if (requiredKeys.has(key)) continue;
-    diagnostics.push(invalidDisposition(dispositionLabel ?? dispositionsPath, `disposition does not match a required impact obligation: ${disposition.ruleId} ${disposition.type} ${disposition.target}`));
-  }
-  const disposed = required.map((obligation) => ({
-    ...obligation,
-    disposition: parsed.entries.get(`${obligation.ruleId}\0${obligation.type}\0${obligation.target}`) ?? null,
-  }));
   const impact = {
     format: IMPACT_FORMAT,
+    analysisStatus: "completed",
     changedUnits: [...new Set(impactingChanges(diffResult).map((change) => change.unitId))].sort(compareText),
     impactedUnits: impacted.map((id) => ({ id, kind: units.get(id)?.kind ?? null })),
-    obligations: disposed,
-    complete: diagnostics.length === 0,
+    obligations: declaredObligations(diffResult, impacted),
   };
   const budget = overBudget(diffResult, impact, maxBytes);
   if (budget.failure) return budget.failure;
   return {
-    ok: diagnostics.length === 0,
-    diagnostics: sortDiagnostics(diagnostics),
+    ok: true,
+    diagnostics: [],
     fileCount: diffResult.fileCount,
     unitCount: impacted.length,
     payloadBytes: budget.payloadBytes,
     diff: diffResult.diff,
     impact,
+    partial: false,
   };
 }
+
+export async function impactAuthorityPaths(beforePath, afterPath, options = {}) {
+  return impactAuthorityDiff(await diffAuthorityPaths(beforePath, afterPath), options);
+}
+
+export { IMPACT_FORMAT };

package/cli/lib/authority/review.mjs

@@ -1,11 +1,12 @@
 import { Buffer } from "node:buffer";
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, realpath, writeFile } from "node:fs/promises";
 import path from "node:path";
 
-import { auditAuthorityPath } from "./audit.mjs";
+import { auditAuthoritySnapshot } from "./audit.mjs";
 import { compileAuthorityPath } from "./compile.mjs";
-import { makeDiagnostic, portablePath, sortDiagnostics } from "./diagnostics.mjs";
-import { diffAuthorityPaths } from "./diff.mjs";
+import { createCompiledAuthoritySnapshot } from "./compiled-snapshot.mjs";
+import { isPathWithin, makeDiagnostic, portablePath, sortDiagnostics } from "./diagnostics.mjs";
+import { diffAuthoritySnapshots } from "./diff.mjs";
 import { AuthorityInputError } from "./format.mjs";
 import {
   AuthorityReviewRefusal,
@@ -13,9 +14,9 @@ import {
   captureStableRegularFile,
   withGitAuthoritySnapshots,
 } from "./git-snapshot.mjs";
-import { impactAuthorityPaths } from "./impact.mjs";
+import { impactAuthorityDiff } from "./impact.mjs";
 
-const REVIEW_FORMAT = "nimicoding.authority-review/v1";
+const REVIEW_FORMAT = "nimicoding.authority-review/v2";
 
 function validBudget(value) {
   return Number.isSafeInteger(value) && value > 0;
@@ -39,8 +40,8 @@ function reviewBudgetDiagnostic(requiredBytes, maxBytes) {
     file: ".",
     range: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
     pointer: "",
-    reason: `complete authority review requires ${requiredBytes} UTF-8 bytes but max-bytes is ${maxBytes}`,
-    repair: "increase the explicit review byte budget; partial change review is forbidden",
+    reason: `complete authority review analysis requires ${requiredBytes} UTF-8 bytes but max-bytes is ${maxBytes}`,
+    repair: "increase the explicit review byte budget; partial change analysis is forbidden",
   });
 }
 
@@ -88,11 +89,12 @@ async function compileSnapshot(root, side) {
   }
 }
 
-function inputLabel(file, repository, fallback) {
-  const absolute = path.resolve(process.cwd(), file);
+async function inputLabel(file, repository, fallback) {
+  const requested = path.resolve(process.cwd(), file);
+  const absolute = await realpath(requested).catch(() => requested);
   const relative = path.relative(repository, absolute);
-  if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) return relative.split(path.sep).join(path.posix.sep);
-  return path.basename(absolute) || fallback;
+  if (relative && isPathWithin(repository, absolute)) return relative.split(path.sep).join(path.posix.sep);
+  return path.basename(requested) || fallback;
 }
 
 async function captureReviewInput(file, temporaryRoot, name, label) {
@@ -113,23 +115,13 @@ async function captureReviewInput(file, temporaryRoot, name, label) {
   return target;
 }
 
-function invalidDisposition(result) {
-  return result.diagnostics.some((diagnostic) => diagnostic.code === "AUTH_IMPACT_DISPOSITION_INVALID");
-}
-
 export function canonicalReviewBytes(review) {
   return Buffer.byteLength(JSON.stringify(review), "utf8");
 }
 
-function component(operationStatus, complete) {
-  return { operationStatus, complete };
-}
-
-async function composeReview(snapshot, bindingsPath, dispositionsPath, budgets) {
-  const bindingsLabel = inputLabel(bindingsPath, snapshot.repository, "bindings.yaml");
-  const dispositionsLabel = inputLabel(dispositionsPath, snapshot.repository, "dispositions.yaml");
+async function composeReview(snapshot, bindingsPath, budgets) {
+  const bindingsLabel = await inputLabel(bindingsPath, snapshot.repository, "bindings.yaml");
   const capturedBindings = await captureReviewInput(bindingsPath, snapshot.temporaryRoot, "bindings", bindingsLabel);
-  const capturedDispositions = await captureReviewInput(dispositionsPath, snapshot.temporaryRoot, "dispositions", dispositionsLabel);
   const [baseCompiled, worktreeCompiled] = await Promise.all([
     compileSnapshot(snapshot.base.root, "base"),
     compileSnapshot(snapshot.worktree.root, "worktree"),
@@ -140,26 +132,23 @@ async function composeReview(snapshot, bindingsPath, dispositionsPath, budgets)
     throw new Error("captured authority file counts do not match complete compiler admission");
   }
 
-  const [diffResult, impactResult, auditResult] = await Promise.all([
-    diffAuthorityPaths(snapshot.base.root, snapshot.worktree.root, { maxBytes: budgets.maxBytes }),
-    impactAuthorityPaths(snapshot.base.root, snapshot.worktree.root, capturedDispositions, { maxBytes: budgets.maxBytes, dispositionLabel: dispositionsLabel }),
-    auditAuthorityPath(snapshot.worktree.root, capturedBindings, { ...budgets, bindingLabel: bindingsLabel }),
-  ]);
+  const baseSnapshot = createCompiledAuthoritySnapshot(baseCompiled.result, snapshot.base.root);
+  const worktreeSnapshot = createCompiledAuthoritySnapshot(worktreeCompiled.result, snapshot.worktree.root);
+  const diffResult = diffAuthoritySnapshots(baseSnapshot, worktreeSnapshot, { maxBytes: budgets.maxBytes });
   if (!diffResult.ok || diffResult.diff === null) return refused(diffResult.diagnostics);
-  if (impactResult.impact === null || invalidDisposition(impactResult)) return refused(impactResult.diagnostics);
+  const impactResult = impactAuthorityDiff(diffResult, { maxBytes: budgets.maxBytes });
+  if (!impactResult.ok || impactResult.impact === null) return refused(impactResult.diagnostics);
+  const auditResult = await auditAuthoritySnapshot(worktreeSnapshot, capturedBindings, { ...budgets, bindingLabel: bindingsLabel });
   if (auditResult.audit === null) return refused(auditResult.diagnostics);
   if (JSON.stringify(diffResult.diff) !== JSON.stringify(impactResult.diff)) throw new Error("diff and impact oracles returned different semantic diffs for immutable snapshots");
 
-  const complete = impactResult.impact.complete && auditResult.audit.complete;
-  const policyStatus = auditResult.audit.policyStatus === "blocked"
-    ? "blocked"
-    : complete ? "passed" : "indeterminate";
   const review = {
     format: REVIEW_FORMAT,
     operationStatus: "completed",
-    policyStatus,
-    complete,
+    analysisComplete: true,
     partial: false,
+    businessSemanticStatus: "not_evaluated",
+    implementationConformanceStatus: "not_evaluated",
     snapshots: {
       base: {
         commitOid: snapshot.baseOid,
@@ -180,10 +169,11 @@ async function composeReview(snapshot, bindingsPath, dispositionsPath, budgets)
       },
     },
     components: {
-      snapshots: component("completed", true),
-      diff: component("completed", true),
-      impact: component("completed", impactResult.impact.complete),
-      audit: component(auditResult.audit.operationStatus, auditResult.audit.complete),
+      snapshotCapture: { status: "captured" },
+      corpusAdmission: { status: "admitted" },
+      semanticDiff: { status: "computed" },
+      declaredImpact: { status: "computed" },
+      configuredAudit: { status: "evaluated", blockingStatus: auditResult.audit.blockingStatus },
     },
     diff: diffResult.diff,
     impact: impactResult.impact,
@@ -194,7 +184,7 @@ async function composeReview(snapshot, bindingsPath, dispositionsPath, budgets)
   if (reviewBytes > budgets.maxBytes) return refused([reviewBudgetDiagnostic(reviewBytes, budgets.maxBytes)], reviewBytes);
   return {
     ok: true,
-    diagnostics: sortDiagnostics(impactResult.diagnostics),
+    diagnostics: [],
     fileCount: snapshot.base.fileCount + snapshot.worktree.fileCount,
     unitCount: worktreeCompiled.result.unitCount,
     reviewBytes,
@@ -203,7 +193,7 @@ async function composeReview(snapshot, bindingsPath, dispositionsPath, budgets)
   };
 }
 
-export async function reviewAuthorityRepository(repositoryPath, baseRef, bindingsPath, dispositionsPath, budgets, options = {}) {
+export async function reviewAuthorityRepository(repositoryPath, baseRef, bindingsPath, budgets, options = {}) {
   if (![budgets?.maxUnits, budgets?.maxEdges, budgets?.maxBytes].every(validBudget)) {
     return refused([reviewBudgetDiagnostic(1, budgets?.maxBytes ?? 0)]);
   }
@@ -212,7 +202,7 @@ export async function reviewAuthorityRepository(repositoryPath, baseRef, binding
       repositoryPath,
       baseRef,
       hooks: options.snapshotHooks ?? null,
-    }, (snapshot) => composeReview(snapshot, bindingsPath, dispositionsPath, budgets));
+    }, (snapshot) => composeReview(snapshot, bindingsPath, budgets));
   } catch (error) {
     if (error instanceof AuthorityReviewRefusal) return refused([authorityReviewRefusalDiagnostic(error)]);
     throw error;

package/cli/lib/authority/sarif.mjs

@@ -56,8 +56,6 @@ function relatedLocations(values = []) {
 }
 
 function itemLevel(kind, item) {
-  if (kind === "observation") return "note";
-  if (kind === "gap") return "error";
   return item.policy === "blocking" ? "error" : "warning";
 }
 
@@ -124,15 +122,12 @@ function invocationProperties(result) {
   if (!result.audit) {
     return {
       operationStatus: "refused",
-      policyStatus: "indeterminate",
-      complete: false,
     };
   }
   return {
     format: result.audit.format,
     operationStatus: result.audit.operationStatus,
-    policyStatus: result.audit.policyStatus,
-    complete: result.audit.complete,
+    blockingStatus: result.audit.blockingStatus,
     counts: copy(result.audit.counts),
     budgets: copy(result.audit.budgets),
   };
@@ -146,9 +141,7 @@ export function authorityAuditResultToSarif(result, { toolVersion }) {
 
   const results = result.audit
     ? [
-        ...(result.audit.observations ?? []).map((item) => auditItemResult("observation", item)),
         ...(result.audit.findings ?? []).map((item) => auditItemResult("finding", item)),
-        ...(result.audit.gaps ?? []).map((item) => auditItemResult("gap", item)),
       ]
     : (result.diagnostics ?? []).map(diagnosticResult);
   const rules = rulesFor(results);

package/cli/lib/authority/source-yaml.mjs

@@ -12,9 +12,6 @@ export async function loadAuthorityContract() {
   if (!contractPromise) {
     contractPromise = readFile(CONTRACT_PATH, "utf8").then((text) => {
       const value = YAML.parse(text);
-      // v2 is the current authoring contract; v1 remains readable as a
-      // migration input, which the contract itself records rather than the
-      // loader inferring it.
       if (value?.version !== 1 || value?.contract?.id !== "nimicoding.authority-source.v2") {
         throw new Error("installed authority source contract is invalid");
       }
@@ -193,7 +190,6 @@ export function parseRestrictedYaml(text, absolutePath, options = {}) {
   };
 }
 
-export const AUTHORITY_FORMAT_V1 = "nimicoding.authority/v1";
 export const AUTHORITY_FORMAT_V2 = "nimicoding.authority/v2";
 export const YAML_CONTAINER_KEY_ORDER = ["format", "owner", "scope", "units"];
 export const YAML_UNIT_KEY_ORDER = [

package/cli/lib/authority/surface.mjs

@@ -9,12 +9,21 @@
 // do not. Each contract states which it is rather than the name implying it.
 export const REPOSITORY_BOUND_COMMANDS = ["anchors", "consumers", "terms", "closed-sets"];
 
+// audit reads one complete authority input plus one explicit bindings file. It
+// is corpus-bound, not repository-bound, but its public parser/help/contract
+// surface is enforced by the same consistency gate.
+export const CORPUS_BOUND_COMMANDS = ["audit"];
+export const ENFORCED_AUTHORITY_COMMANDS = [
+  ...REPOSITORY_BOUND_COMMANDS,
+  ...CORPUS_BOUND_COMMANDS,
+];
+
 // fmt is not repository-bound, but its flags and the formats it admits are
 // exactly what the authoring contract promises, so it is compared too.
 export const AUTHORING_SURFACE = {
   fmt: {
     contract: "nimicoding.authority-authoring.v2",
-    booleanFlags: ["json", "check", "upgrade"],
+    booleanFlags: ["json", "check"],
     valueFlags: [],
     integerFlags: [],
     repeatableFlags: [],
@@ -22,6 +31,15 @@ export const AUTHORING_SURFACE = {
 };
 
 export const AUTHORITY_SURFACE = {
+  audit: {
+    contract: "nimicoding.authority-audit.v2",
+    reportFormat: "nimicoding.authority-audit/v2",
+    corpus: "authority-input",
+    booleanFlags: ["json", "sarif"],
+    valueFlags: ["bindings"],
+    integerFlags: ["max-units", "max-edges", "max-bytes"],
+    repeatableFlags: [],
+  },
   anchors: {
     contract: "nimicoding.authority-anchors.v1",
     reportFormat: "nimicoding.authority-anchors/v1",

package/cli/lib/authority/terms.mjs

@@ -15,12 +15,13 @@ import { classifyTrackedTextFiles, trackedTextInventory } from "./tracked-text.m
 // is decided by content, not by this list.
 const CODE_EXTENSION_SET = new Set(CODE_EXTENSIONS);
 const TERMS_FORMAT = "nimicoding.authority-terms/v1";
-const TERM_CLASS_ORDER = ["snake_case", "camelCase", "UPPER_SNAKE", "PascalCase", "dotted"];
+const TERM_CLASS_ORDER = ["snake_case", "camelCase", "UPPER_SNAKE", "ALL_CAPS", "PascalCase", "dotted"];
 const TERM_EXPRESSIONS = [
   ["snake_case", /[a-z][a-z0-9]*(?:_[a-z0-9]+)+/gu],
   ["camelCase", /[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)+/gu],
   ["UPPER_SNAKE", /[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+/gu],
-  ["PascalCase", /[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]*)+/gu],
+  ["ALL_CAPS", /[A-Z]{2,}/gu],
+  ["PascalCase", /(?:[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]*)+|[A-Z]{2,}[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*)/gu],
   ["dotted", /[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)+/gu],
 ];
 const AUTHORITY_FIELDS = ["title", "meaning", "statement", "condition", "failure"];
@@ -33,7 +34,8 @@ export const AUTHORITY_TERM_GRAMMAR_HELP = [
   "  snake_case: [a-z][a-z0-9]*(_[a-z0-9]+)+",
   "  camelCase: [a-z][a-z0-9]*([A-Z][a-z0-9]*)+",
   "  UPPER_SNAKE: [A-Z][A-Z0-9]*(_[A-Z0-9]+)+",
-  "  PascalCase: [A-Z][a-z0-9]+([A-Z][a-z0-9]*)+",
+  "  ALL_CAPS: [A-Z]{2,} (lexical shape only; no acronym inference)",
+  "  PascalCase: [A-Z][a-z0-9]+([A-Z][a-z0-9]*)+ or [A-Z]{2,}[a-z][a-z0-9]*([A-Z][a-z0-9]*)*",
   "  dotted: [A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)+, excluding final segments that are code extensions.",
   "Matches require ASCII identifier boundaries and are excluded from longer path-like tokens containing '/'.",
 ].join("\n");
@@ -85,11 +87,6 @@ function inputDiagnostic(code, reason, file = ".") {
   );
 }
 
-function isWithin(root, candidate) {
-  const relative = path.relative(root, candidate);
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
 function portableRelative(repository, candidate) {
   return path.relative(repository, candidate).split(path.sep).join(path.posix.sep);
 }
@@ -371,10 +368,14 @@ export async function termsAuthorityRepository(repositoryPath, specPath, { term
   let codeReferences = [];
   let codeInventory = null;
   if (code) {
+    const gitlinks = new Set(inventory.gitlinks);
     const classified = await classifyTrackedTextFiles(
       inventory.repository,
       inventory.files,
-      (file) => corpusFile(file, corpus) ? "authority-corpus" : null,
+      (file) => {
+        if (gitlinks.has(file)) return "gitlink";
+        return corpusFile(file, corpus) ? "authority-corpus" : null;
+      },
     );
     if (classified.error !== undefined) {
       return refused([inputDiagnostic("AUTH_TERMS_CODE_INPUT_INVALID", classified.error)], { fileCount: compiled.fileCount });

package/cli/lib/authority/validate.mjs

@@ -1,5 +1,5 @@
 import { compareText, makeDiagnostic, relatedLocation, REPAIRS, sortDiagnostics, sourcePointer } from "./diagnostics.mjs";
-import { AUTHORITY_FORMAT_V1, AUTHORITY_FORMAT_V2 } from "./source-yaml.mjs";
+import { AUTHORITY_FORMAT_V2 } from "./source-yaml.mjs";
 
 function isObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -49,12 +49,7 @@ function structuralDiagnostics(source, contract) {
     }
   }
   for (const [field, admitted] of [
-    // The authoring format plus whatever the contract records as a readable
-    // migration input, so fmt --upgrade and history diffs keep working without
-    // the loader inventing a compatibility list of its own.
-    ...(source.profile === "markdown"
-      ? [["format", [contract.format, ...(contract.migration_inputs?.format ? [contract.migration_inputs.format] : [])]]]
-      : []),
+    ...(source.profile === "markdown" ? [["format", [contract.format]]] : []),
     ["kind", contract.kinds],
     ["lifecycle", contract.lifecycles],
   ]) {
@@ -90,19 +85,16 @@ function documentStructuralDiagnostics(document, contract) {
   const diagnostics = [];
   const data = document.data;
   if (!isObject(data)) return diagnostics;
-  const v2 = data.format === AUTHORITY_FORMAT_V2;
   // Container field admission comes from the contract, so changing what a v2
   // container may carry is a contract edit that the source-contract gate sees,
   // not a constant edited here alone.
-  const allowed = new Set(v2 ? contract.fields.yaml_document : contract.fields.yaml_document_migration_input);
+  const allowed = new Set(contract.fields.yaml_document);
   for (const key of Object.keys(data)) {
-    if (!allowed.has(key)) add(diagnostics, document, "AUTH_UNKNOWN_FIELD", `/${key}`, `unknown authority document field: ${key}`, v2
-      ? "remove the field; v2 YAML authority documents contain only format, optional owner, optional scope, and units"
-      : "remove the field; v1 YAML authority documents contain only format and units");
+    if (!allowed.has(key)) add(diagnostics, document, "AUTH_UNKNOWN_FIELD", `/${key}`, `unknown authority document field: ${key}`, "remove the field; v2 YAML authority documents contain only format, optional owner, optional scope, and units");
   }
   if (!Object.hasOwn(data, "format")) add(diagnostics, document, "AUTH_FIELD_REQUIRED", "/format", "format is required before the formatter can select the YAML container profile", REPAIRS.required, { missing: true });
-  else if (![contract.format, contract.migration_inputs?.format].includes(data.format)) add(diagnostics, document, "AUTH_FIELD_INVALID", "/format", `format must be one of: ${contract.format}, ${contract.migration_inputs?.format}`, REPAIRS.invalid);
-  if (v2) {
+  else if (data.format !== contract.format) add(diagnostics, document, "AUTH_FIELD_INVALID", "/format", `format must be: ${contract.format}`, REPAIRS.invalid);
+  if (data.format === AUTHORITY_FORMAT_V2) {
     const identifier = new RegExp(contract.identifier_pattern);
     if (Object.hasOwn(data, "owner") && (typeof data.owner !== "string" || !identifier.test(data.owner))) {
       add(diagnostics, document, "AUTH_FIELD_INVALID", "/owner", "container owner must be a dot-separated lower-case identifier", REPAIRS.invalid);

package/cli/lib/code/authority-annotation-response.mjs

@@ -0,0 +1,43 @@
+import { Buffer } from "node:buffer";
+
+export const CODE_AUTHORITY_FORMAT = "nimicoding.code-authority-response/v1";
+export const MIN_CODE_AUTHORITY_BYTES = 512;
+
+const MAX_ERROR_MESSAGE_BYTES = 160;
+
+export function refusedCodeAuthorityResponse(code, message) {
+  if (Buffer.byteLength(message, "utf8") > MAX_ERROR_MESSAGE_BYTES) {
+    throw new Error("code authority error message exceeds its fixed protocol bound");
+  }
+  return {
+    format: CODE_AUTHORITY_FORMAT,
+    status: "refused",
+    complete: false,
+    operation: null,
+    scope: null,
+    result: null,
+    findings: null,
+    counts: null,
+    usage: null,
+    error: { code, message },
+  };
+}
+
+export function completedCodeAuthorityResponse(value) {
+  return {
+    format: CODE_AUTHORITY_FORMAT,
+    status: value.operation === "lifecycle-audit" && value.findings.length > 0 ? "findings" : "completed",
+    complete: true,
+    ...value,
+    error: null,
+  };
+}
+
+export function serializeCodeAuthorityResponse(response) {
+  return `${JSON.stringify(response)}\n`;
+}
+
+export function renderCodeAuthorityResponse(response, maxBytes) {
+  const text = serializeCodeAuthorityResponse(response);
+  return Buffer.byteLength(text, "utf8") <= maxBytes ? text : null;
+}