@nimiplatform/nimi-coding 0.5.0 → 0.6.0

package/cli/constants.mjs

@@ -1,5 +1,6 @@
-export const VERSION = "0.5.0";
+export const VERSION = "0.6.0";
 export const PACKAGE_NAME = "@nimiplatform/nimi-coding";
+export const PROJECT_LOCAL_CLI_INVOCATION = "pnpm exec nimicoding";
 export const LOCAL_GITIGNORE_ENTRIES = [".nimi/local/"];
 export const AUTHORITY_GITATTRIBUTES_ENTRIES = [
   "*.authority.yaml text eol=lf",

package/cli/dev/run-cli-smoke.mjs

@@ -1,9 +1,11 @@
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 const cliPath = path.join(repoRoot, "bin", "nimicoding.mjs");
+const packageVersion = JSON.parse(readFileSync(path.join(repoRoot, "package.json"), "utf8")).version;
 
 for (const args of [["--help"], ["--version"]]) {
   const result = spawnSync(process.execPath, [cliPath, ...args], {
@@ -21,4 +23,8 @@ for (const args of [["--help"], ["--version"]]) {
     process.stderr.write(`${args.join(" ")} smoke exited with ${result.status ?? "unknown"}\n`);
     process.exit(result.status ?? 1);
   }
+  if (args[0] === "--version" && result.stdout !== `${packageVersion}\n`) {
+    process.stderr.write(`--version returned ${JSON.stringify(result.stdout)}; expected ${JSON.stringify(`${packageVersion}\n`)}\n`);
+    process.exit(1);
+  }
 }

package/cli/help.mjs

@@ -1,6 +1,7 @@
 import { VERSION } from "./constants.mjs";
 import { AUTHORITY_ANCHOR_GRAMMAR_HELP } from "./lib/authority/anchors.mjs";
 import { AUTHORITY_COMMAND_USAGE } from "./commands/authority.mjs";
+import { CODE_COMMAND_USAGE } from "./commands/code.mjs";
 import { localize, styleCommand, styleHeading, styleMuted } from "./lib/ui.mjs";
 
 export function helpText() {
@@ -8,11 +9,11 @@ export function helpText() {
     // The authority list comes from the command module itself so help and the
     // parser cannot describe different surfaces.
     ...AUTHORITY_COMMAND_USAGE,
+    ...CODE_COMMAND_USAGE,
     "nimicoding start [--yes]",
     "nimicoding sync [--apply|--check|--dry-run] [--json]",
     "nimicoding clear [--yes]",
     "nimicoding doctor [--verbose|--json]",
-    "nimicoding validate-ai-governance --profile <profile-id> --scope <all|agents-freshness|context-budget|structure-budget|high-risk-doc-metadata>  # optional L3 repository governance",
   ];
   return [
     styleHeading(`nimicoding ${VERSION}`),
@@ -25,8 +26,12 @@ export function helpText() {
     AUTHORITY_ANCHOR_GRAMMAR_HELP,
     "",
     styleMuted(localize(
-      "Nimi Coding provides canonical authority methodology, formatting, compiler primitives, and deterministic gates. The optional L3 repository-governance command is not authority admission. AI task planning and execution belong to the host.",
-      "Nimi Coding 提供 canonical authority 方法论、格式化、编译器原语与确定性 gate。可选 L3 repository-governance 命令不属于 authority admission；AI 任务规划与执行由宿主负责。",
+      "Nimi Coding provides canonical authority products, bounded read-only TypeScript context, and explicit code-authority marker lookup. AI task planning, editing, verification, and execution belong to the host.",
+      "Nimi Coding 提供 canonical authority 产品、有界只读的 TypeScript context，以及显式 code-authority marker 查询。AI 任务规划、编辑、验证与执行由宿主负责。",
+    )),
+    styleMuted(localize(
+      "Code queries read tracked current-filesystem source; unsaved editor buffers, conformance claims, and unannotated implementation semantics are outside v1.",
+      "Code 查询读取 Git tracked 的当前文件系统源码；未保存的编辑器 buffer、conformance 声明和未标注实现语义不属于 v1。",
     )),
     "",
   ].join("\n");

package/cli/index.mjs

@@ -1,9 +1,9 @@
 import { runAuthority } from "./commands/authority.mjs";
 import { runClear } from "./commands/clear.mjs";
+import { classifyCodeInvocation, runCodeInvocation } from "./commands/code.mjs";
 import { runDoctor } from "./commands/doctor.mjs";
 import { runStart } from "./commands/start.mjs";
 import { runSync } from "./commands/sync.mjs";
-import { runValidateAiGovernance } from "./commands/validate-ai-governance.mjs";
 import { helpText } from "./help.mjs";
 import { VERSION } from "./constants.mjs";
 import { configureCliUi, localize, parseGlobalUiOptions } from "./lib/ui.mjs";
@@ -14,10 +14,11 @@ const COMMANDS = {
   sync: runSync,
   clear: runClear,
   doctor: runDoctor,
-  "validate-ai-governance": runValidateAiGovernance,
 };
 
 export async function runCli(args) {
+  const codeCommandIndex = classifyCodeInvocation(args);
+  if (codeCommandIndex !== null) return runCodeInvocation(args, codeCommandIndex);
   const parsedUi = parseGlobalUiOptions(args);
   if (!parsedUi.ok) {
     process.stderr.write(parsedUi.error);

package/cli/lib/authority/diagnostics.mjs

@@ -1,5 +1,7 @@
 import path from "node:path";
 
+import { PROJECT_LOCAL_CLI_INVOCATION } from "../../constants.mjs";
+
 export function compareText(left, right) {
   const a = String(left);
   const b = String(right);
@@ -89,5 +91,5 @@ export const REPAIRS = {
   invalid: "replace the value with one admitted by the authoring contract",
   relation: "repair the explicit relation using product authority; do not infer a target",
   duplicate: "keep one declaration chosen from product authority and remove the duplicate",
-  format: "run `nimicoding authority fmt` on this file",
+  format: `run \`${PROJECT_LOCAL_CLI_INVOCATION} authority fmt\` on this file`,
 };

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;
+}

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

@@ -0,0 +1,162 @@
+import { Buffer } from "node:buffer";
+
+import ts from "typescript";
+
+import { compareText, createLocator } from "../authority/diagnostics.mjs";
+
+const EXACT_MARKER = /^\/\/ nimi-(authority|deprecated): ([^\s]+)$/u;
+const MARKER_CANDIDATE = /^\/\/[ \t]*nimi-(?:authority|deprecated)\b/u;
+const PHYSICAL_CANDIDATE = /^[ \t]*\/\/[ \t]*nimi-(?:authority|deprecated)\b/mu;
+const NEARBY_SOURCE_BYTES = 512;
+
+function comparePosition(left, right) {
+  return left.line - right.line || left.column - right.column;
+}
+
+function utf8Prefix(text, maxBytes) {
+  let value = "";
+  let bytes = 0;
+  for (const character of text) {
+    const size = Buffer.byteLength(character, "utf8");
+    if (bytes + size > maxBytes) break;
+    value += character;
+    bytes += size;
+  }
+  return value;
+}
+
+function nearbySource(path, text, locator, markerEnd) {
+  const start = markerEnd < text.length && text[markerEnd] === "\r" ? markerEnd + 1 : markerEnd;
+  const contentStart = start < text.length && text[start] === "\n" ? start + 1 : start;
+  const candidate = text.slice(contentStart);
+  const value = utf8Prefix(candidate, NEARBY_SOURCE_BYTES);
+  return {
+    location: { path, range: locator.range(contentStart, contentStart + value.length) },
+    text: value,
+    truncated: value.length < candidate.length,
+  };
+}
+
+function parseComment(path, text, locator, start, end, identifier) {
+  const lineStart = text.lastIndexOf("\n", start - 1) + 1;
+  if (text.slice(lineStart, start).trim().length > 0) return { occurrence: null, finding: null };
+  const raw = text.slice(start, end).replace(/\r$/u, "");
+  if (!MARKER_CANDIDATE.test(raw)) return { occurrence: null, finding: null };
+  const location = { path, range: locator.range(start, end) };
+  const match = EXACT_MARKER.exec(raw);
+  if (match === null || !identifier.test(match[2])) {
+    return {
+      occurrence: null,
+      finding: {
+        kind: "invalid-annotation",
+        source_path: path,
+        annotation_location: location,
+        reason: "annotation must match the exact standalone exact-ID-only line grammar",
+      },
+    };
+  }
+  return {
+    occurrence: {
+      annotation_kind: match[1],
+      authority_id: match[2],
+      source_path: path,
+      annotation_location: location,
+      nearby_source: nearbySource(path, text, locator, end),
+    },
+    finding: null,
+  };
+}
+
+function typeScriptLineComments(path, text) {
+  const scriptKind = path.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  const sourceFile = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, scriptKind);
+  const comments = new Map();
+  const jsxTextRanges = [];
+  function add(ranges) {
+    for (const range of ranges ?? []) {
+      if (range.kind === ts.SyntaxKind.SingleLineCommentTrivia) {
+        comments.set(`${range.pos}:${range.end}`, { start: range.pos, end: range.end });
+      }
+    }
+  }
+  const pending = [sourceFile];
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (ts.isJsxText(node)) jsxTextRanges.push({ start: node.pos, end: node.end });
+    add(ts.getLeadingCommentRanges(text, node.pos));
+    add(ts.getTrailingCommentRanges(text, node.end));
+    pending.push(...node.getChildren(sourceFile));
+  }
+  return [...comments.values()]
+    .filter((comment) => !jsxTextRanges.some((range) => comment.start >= range.start && comment.end <= range.end))
+    .sort((left, right) => left.start - right.start || left.end - right.end);
+}
+
+function goLineComments(text) {
+  const comments = [];
+  let index = 0;
+  while (index < text.length) {
+    const character = text[index];
+    if (character === "/" && text[index + 1] === "/") {
+      const start = index;
+      index += 2;
+      while (index < text.length && text[index] !== "\n") index += 1;
+      comments.push({ start, end: index });
+      continue;
+    }
+    if (character === "/" && text[index + 1] === "*") {
+      const close = text.indexOf("*/", index + 2);
+      index = close < 0 ? text.length : close + 2;
+      continue;
+    }
+    if (character === "`" || character === "\"" || character === "'") {
+      const quote = character;
+      index += 1;
+      while (index < text.length) {
+        if (quote !== "`" && text[index] === "\\") {
+          index += Math.min(2, text.length - index);
+          continue;
+        }
+        if (text[index] === quote) {
+          index += 1;
+          break;
+        }
+        index += 1;
+      }
+      continue;
+    }
+    index += 1;
+  }
+  return comments;
+}
+
+export function scanAuthorityAnnotations(path, text, identifierPattern) {
+  if (!PHYSICAL_CANDIDATE.test(text)) return { occurrences: [], findings: [] };
+  const locator = createLocator(text);
+  const identifier = new RegExp(identifierPattern, "u");
+  const comments = path.endsWith(".go") ? goLineComments(text) : typeScriptLineComments(path, text);
+  const occurrences = [];
+  const findings = [];
+  for (const comment of comments) {
+    const parsed = parseComment(path, text, locator, comment.start, comment.end, identifier);
+    if (parsed.occurrence !== null) occurrences.push(parsed.occurrence);
+    if (parsed.finding !== null) findings.push(parsed.finding);
+  }
+  occurrences.sort(compareOccurrences);
+  findings.sort(compareAnnotationFindings);
+  return { occurrences, findings };
+}
+
+export function compareOccurrences(left, right) {
+  return compareText(left.source_path, right.source_path)
+    || comparePosition(left.annotation_location.range.start, right.annotation_location.range.start)
+    || compareText(left.annotation_kind, right.annotation_kind)
+    || compareText(left.authority_id, right.authority_id);
+}
+
+export function compareAnnotationFindings(left, right) {
+  return compareText(left.source_path, right.source_path)
+    || comparePosition(left.annotation_location.range.start, right.annotation_location.range.start)
+    || compareText(left.kind, right.kind)
+    || compareText(left.reason, right.reason);
+}

package/cli/lib/code/authority-annotations.mjs

@@ -0,0 +1,293 @@
+import { Buffer } from "node:buffer";
+import path from "node:path";
+
+import { compileAuthorityPath } from "../authority/compile.mjs";
+import { compareText } from "../authority/diagnostics.mjs";
+import { captureStableRegularFile } from "../authority/git-snapshot.mjs";
+import { buildAuthorityGraphSnapshot } from "../authority/graph.mjs";
+import { repositoryInventory } from "../authority/repository-inventory.mjs";
+import { resolveRepositoryCorpus } from "../authority/repository-corpus.mjs";
+import { loadAuthorityContract } from "../authority/source-yaml.mjs";
+import {
+  compareAnnotationFindings,
+  compareOccurrences,
+  scanAuthorityAnnotations,
+} from "./authority-annotation-scan.mjs";
+
+const SUPPORTED_SOURCE = /(?:\.d)?\.tsx?$|\.go$/u;
+const UTF8 = new TextDecoder("utf-8", { fatal: true });
+const CLASSIFICATION_ORDER = new Map([
+  ["active-reference", 0],
+  ["removed-reference", 1],
+  ["superseded-reference", 2],
+  ["missing-reference", 3],
+  ["explicit-deprecated", 4],
+]);
+
+export class CodeAuthorityFailure extends Error {
+  constructor(code, message, exitCode = 2) {
+    super(message);
+    this.name = "CodeAuthorityFailure";
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+
+function fail(code, message, exitCode = 2) {
+  throw new CodeAuthorityFailure(code, message, exitCode);
+}
+
+function compareLocation(left, right) {
+  return left.range.start.line - right.range.start.line
+    || left.range.start.column - right.range.start.column;
+}
+
+function compareClassifications(left, right) {
+  return (CLASSIFICATION_ORDER.get(left) ?? 99) - (CLASSIFICATION_ORDER.get(right) ?? 99)
+    || compareText(left, right);
+}
+
+function directRelations(graph, id) {
+  return {
+    authored_successors: (graph.incoming.get(id) ?? []).map((edge) => ({
+      id: edge.source,
+      authority_location: edge.sourceLocation,
+      relation_location: edge.relationLocation,
+    })),
+    authored_supersedes: (graph.outgoing.get(id) ?? []).map((edge) => ({
+      id: edge.target,
+      authority_location: edge.targetLocation,
+      relation_location: edge.relationLocation,
+    })),
+  };
+}
+
+function authorityDescriptor(graph, id) {
+  const entry = graph.byId.get(id);
+  if (entry === undefined) {
+    return {
+      id,
+      resolution: "missing",
+      lifecycle: null,
+      authority_location: null,
+      authored_successors: [],
+      authored_supersedes: [],
+    };
+  }
+  return {
+    id,
+    resolution: "resolved",
+    lifecycle: entry.node.lifecycle,
+    authority_location: entry.node.location,
+    ...directRelations(graph, id),
+  };
+}
+
+function classifyOccurrence(graph, occurrence) {
+  const descriptor = authorityDescriptor(graph, occurrence.authority_id);
+  const classifications = [];
+  if (descriptor.resolution === "missing") classifications.push("missing-reference");
+  else if (descriptor.lifecycle === "removed") classifications.push("removed-reference");
+  else classifications.push("active-reference");
+  if (descriptor.authored_successors.length > 0) classifications.push("superseded-reference");
+  if (occurrence.annotation_kind === "deprecated") classifications.push("explicit-deprecated");
+  return {
+    ...occurrence,
+    classifications: classifications.sort(compareClassifications),
+    authority: descriptor,
+    pairing: occurrence.annotation_kind === "deprecated" ? "not_evaluated" : null,
+  };
+}
+
+function findingFromOccurrence(occurrence, kind) {
+  return {
+    kind,
+    source_path: occurrence.source_path,
+    annotation_kind: occurrence.annotation_kind,
+    authority_id: occurrence.authority_id,
+    annotation_location: occurrence.annotation_location,
+    authority_location: occurrence.authority.authority_location,
+    authored_successors: occurrence.authority.authored_successors,
+  };
+}
+
+function compareFindings(left, right) {
+  return compareText(left.source_path, right.source_path)
+    || compareLocation(left.annotation_location, right.annotation_location)
+    || compareText(left.kind, right.kind)
+    || compareText(left.authority_id ?? "", right.authority_id ?? "");
+}
+
+function auditFindings(occurrences, invalidFindings) {
+  const findings = [...invalidFindings];
+  for (const occurrence of occurrences) {
+    for (const kind of occurrence.classifications) {
+      if (kind !== "active-reference") findings.push(findingFromOccurrence(occurrence, kind));
+    }
+  }
+  return findings.sort(compareFindings);
+}
+
+function countsFor(occurrences, invalidFindings) {
+  const counts = {
+    annotations: occurrences.length,
+    "active-reference": 0,
+    "explicit-deprecated": 0,
+    "removed-reference": 0,
+    "superseded-reference": 0,
+    "missing-reference": 0,
+    "invalid-annotation": invalidFindings.length,
+  };
+  for (const occurrence of occurrences) {
+    for (const classification of occurrence.classifications) counts[classification] += 1;
+  }
+  return counts;
+}
+
+function normalizeSourceSelector(source) {
+  if (
+    typeof source !== "string"
+    || source.length === 0
+    || source.includes("\\")
+    || source.startsWith("/")
+    || source.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+  ) return null;
+  return source;
+}
+
+async function readCurrentSource(repository, source, remainingBytes) {
+  const absolute = path.join(repository, ...source.split("/"));
+  let bytes;
+  try {
+    bytes = await captureStableRegularFile(absolute, source, repository, remainingBytes);
+  } catch (error) {
+    if (error?.code === "AUTH_REVIEW_INPUT_BUDGET") {
+      fail("CODE_AUTHORITY_INPUT_BUDGET", "max-bytes cannot contain the complete authority and source input", 1);
+    }
+    fail("CODE_AUTHORITY_SOURCE_INVALID", "tracked current source is not one stable repository-contained regular file");
+  }
+  let text;
+  try {
+    text = UTF8.decode(bytes);
+  } catch {
+    fail("CODE_AUTHORITY_SOURCE_INVALID", "tracked current source is not valid UTF-8");
+  }
+  return { bytes: bytes.length, text };
+}
+
+export async function queryCodeAuthority({ repository: repositoryPath, selector, maxFiles, maxBytes }) {
+  let inventory;
+  try {
+    inventory = await repositoryInventory(repositoryPath);
+  } catch {
+    fail("CODE_AUTHORITY_REPOSITORY_INVALID", "repo must name one exact readable Git worktree root");
+  }
+  let corpus;
+  try {
+    corpus = await resolveRepositoryCorpus(
+      inventory.repository,
+      path.join(inventory.repository, ".nimi", "spec"),
+      "code authority",
+    );
+  } catch {
+    fail("CODE_AUTHORITY_CORPUS_INVALID", "repository canonical authority corpus is not readable");
+  }
+  let compiled;
+  try {
+    compiled = await compileAuthorityPath(corpus.path);
+  } catch {
+    fail("CODE_AUTHORITY_CORPUS_INVALID", "canonical authority corpus cannot be compiled");
+  }
+  if (!compiled.ok) fail("CODE_AUTHORITY_CORPUS_INVALID", "canonical authority corpus does not compile");
+  if (compiled.inputBytes > maxBytes) {
+    fail("CODE_AUTHORITY_INPUT_BUDGET", "max-bytes cannot contain the complete authority and source input", 1);
+  }
+  const contract = await loadAuthorityContract();
+  const identifier = new RegExp(contract.identifier_pattern, "u");
+  if (selector.kind === "authority" && !identifier.test(selector.id)) {
+    fail("CODE_USAGE", "authority selector must be one exact canonical authority ID");
+  }
+
+  const tracked = new Set(inventory.files);
+  const gitlinks = new Set(inventory.gitlinks);
+  let sourcePaths;
+  if (selector.kind === "source") {
+    const normalized = normalizeSourceSelector(selector.path);
+    if (normalized === null || !SUPPORTED_SOURCE.test(normalized) || !tracked.has(normalized) || gitlinks.has(normalized)) {
+      fail("CODE_AUTHORITY_SOURCE_INVALID", "source selector must name one tracked .ts, .tsx, or .go file");
+    }
+    sourcePaths = [normalized];
+  } else {
+    sourcePaths = inventory.files.filter((source) => SUPPORTED_SOURCE.test(source) && !gitlinks.has(source));
+  }
+
+  const requiredFiles = compiled.fileCount + sourcePaths.length;
+  if (requiredFiles > maxFiles) {
+    fail("CODE_AUTHORITY_FILES_BUDGET", "max-files cannot contain the complete authority and source file set", 1);
+  }
+  const graph = buildAuthorityGraphSnapshot(compiled, inventory.repository, ["supersedes"]);
+  const occurrences = [];
+  const invalidFindings = [];
+  let inputBytes = compiled.inputBytes;
+  for (const source of sourcePaths) {
+    const current = await readCurrentSource(inventory.repository, source, maxBytes - inputBytes);
+    inputBytes += current.bytes;
+    const scanned = scanAuthorityAnnotations(source, current.text, contract.identifier_pattern);
+    occurrences.push(...scanned.occurrences.map((occurrence) => classifyOccurrence(graph, occurrence)));
+    invalidFindings.push(...scanned.findings);
+  }
+  occurrences.sort(compareOccurrences);
+  invalidFindings.sort(compareAnnotationFindings);
+  const findings = auditFindings(occurrences, invalidFindings);
+  const counts = countsFor(occurrences, invalidFindings);
+  const usage = {
+    authority_files: compiled.fileCount,
+    source_files: sourcePaths.length,
+    input_bytes: inputBytes,
+    max_files: maxFiles,
+    max_bytes: maxBytes,
+  };
+
+  if (selector.kind === "authority") {
+    const selectedOccurrences = occurrences.filter((occurrence) => occurrence.authority_id === selector.id);
+    const selectedFindings = findings.filter((finding) => finding.authority_id === selector.id);
+    return {
+      operation: "authority-to-code",
+      scope: { repository: ".", authority_id: selector.id },
+      result: {
+        authority: authorityDescriptor(graph, selector.id),
+        occurrences: selectedOccurrences,
+      },
+      findings: selectedFindings,
+      counts: countsFor(selectedOccurrences, []),
+      usage,
+    };
+  }
+  if (selector.kind === "source") {
+    return {
+      operation: "code-to-authority",
+      scope: { repository: ".", source_path: selector.path },
+      result: {
+        source_path: selector.path,
+        occurrences,
+        unannotated_semantics: "not_evaluated",
+      },
+      findings,
+      counts,
+      usage,
+    };
+  }
+  return {
+    operation: "lifecycle-audit",
+    scope: { repository: ".", source_languages: ["go", "typescript", "tsx"] },
+    result: {
+      conclusion: findings.length === 0
+        ? "annotated implementation surface has no deterministic authority lifecycle residue"
+        : "annotated implementation surface contains deterministic authority lifecycle residue",
+      unannotated_semantics: "not_evaluated",
+    },
+    findings,
+    counts,
+    usage,
+  };
+}