@nimiplatform/nimi-coding 0.3.1 → 0.5.0

package/cli/lib/authority/repository-corpus.mjs

@@ -0,0 +1,37 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+
+// The repository-bound report products -- anchors, consumers, terms and
+// closed-sets -- read a repository and the authority that governs it, then
+// report one against the other. Their guard used to be "somewhere inside this
+// Git repository", which let a fixture directory stand in as the canonical
+// corpus and still produce a report marked complete. The corpus for these
+// products is one exact location.
+//
+// This does not apply to fmt, check, diff, compile or impact: those accept an
+// arbitrary path on purpose, because they read history snapshots and migration
+// inputs that are not the working corpus.
+export const REPOSITORY_CORPUS_SEGMENTS = [".nimi", "spec"];
+export const REPOSITORY_CORPUS_RELATIVE = REPOSITORY_CORPUS_SEGMENTS.join("/");
+
+export async function resolveRepositoryCorpus(repositoryPath, specPath, label) {
+  const repository = await realpath(path.resolve(repositoryPath));
+  const absolute = path.resolve(specPath);
+  let metadata;
+  try {
+    metadata = await lstat(absolute);
+  } catch (error) {
+    throw new Error(`${label} corpus is not readable: ${error.message}`);
+  }
+  if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+    throw new Error(`${label} corpus must be one regular non-symlink directory`);
+  }
+  const resolved = await realpath(absolute);
+  const expected = path.join(repository, ...REPOSITORY_CORPUS_SEGMENTS);
+  if (resolved !== expected) {
+    throw new Error(
+      `${label} corpus must be the repository authority corpus at ${REPOSITORY_CORPUS_RELATIVE}`,
+    );
+  }
+  return { path: resolved, directory: true, relative: REPOSITORY_CORPUS_RELATIVE };
+}

package/cli/lib/authority/repository-inventory.mjs

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+
+import { compareText } from "./diagnostics.mjs";
+import { listGitTrackedFiles } from "./git-snapshot.mjs";
+
+const REPOSITORY_INVENTORY_FORMAT = "nimicoding.repository-inventory/v1";
+
+function trackedPathSetDigest(files) {
+  const ordered = [...new Set(files)].sort(compareText);
+  // The SHA-256 preimage is exactly the UTF-8 encoding of this compact JSON:
+  // {"format":"nimicoding.repository-inventory/v1","files":[<ordered paths>]}
+  // where paths are the unique Git-decoded tracked paths sorted by compareText.
+  // The repository root is intentionally absent: it locates the inventory but
+  // is not part of the state two reports compare.
+  //
+  // This digest covers the tracked path SET and nothing else - not blob
+  // contents, not the commit, not worktree cleanliness. Two commits whose
+  // files were all rewritten but none renamed produce the same digest. The
+  // name says so on purpose: a field called inventoryDigest would be read as
+  // "these reports describe the same repository state", which this value does
+  // not establish. Content identity is a separate, additive field.
+  const preimage = JSON.stringify({ format: REPOSITORY_INVENTORY_FORMAT, files: ordered });
+  return createHash("sha256").update(preimage, "utf8").digest("hex");
+}
+
+export async function repositoryInventory(repositoryPath) {
+  const inventory = await listGitTrackedFiles(repositoryPath);
+  return {
+    ...inventory,
+    trackedPathSetDigest: trackedPathSetDigest(inventory.files),
+  };
+}
+
+export { REPOSITORY_INVENTORY_FORMAT, trackedPathSetDigest };

package/cli/lib/authority/review.mjs

@@ -0,0 +1,212 @@
+import { Buffer } from "node:buffer";
+import { mkdir, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { auditAuthoritySnapshot } from "./audit.mjs";
+import { compileAuthorityPath } from "./compile.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,
+  authorityReviewRefusalDiagnostic,
+  captureStableRegularFile,
+  withGitAuthoritySnapshots,
+} from "./git-snapshot.mjs";
+import { impactAuthorityDiff } from "./impact.mjs";
+
+const REVIEW_FORMAT = "nimicoding.authority-review/v2";
+
+function validBudget(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+
+function refused(diagnostics, reviewBytes = 0) {
+  return {
+    ok: false,
+    diagnostics: sortDiagnostics(diagnostics),
+    fileCount: 0,
+    unitCount: 0,
+    reviewBytes,
+    review: null,
+    partial: false,
+  };
+}
+
+function reviewBudgetDiagnostic(requiredBytes, maxBytes) {
+  return makeDiagnostic({
+    code: "AUTH_REVIEW_BUDGET",
+    file: ".",
+    range: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+    pointer: "",
+    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",
+  });
+}
+
+function normalizePath(file, root, side) {
+  const relative = portablePath(file, root);
+  const safe = path.isAbsolute(relative) ? path.basename(relative) : relative;
+  return path.posix.join(side, safe || ".");
+}
+
+function normalizeCompilerDiagnostics(diagnostics, root, side) {
+  return diagnostics.map((diagnostic) => ({
+    ...diagnostic,
+    path: normalizePath(diagnostic.path, root, side),
+    related: diagnostic.related.map((related) => ({
+      ...related,
+      path: normalizePath(related.path, root, side),
+    })),
+  }));
+}
+
+function corpusInputDiagnostic(error, root, side) {
+  const portableRoot = root.split(path.sep).join(path.posix.sep);
+  const reason = error.message
+    .split(root).join(side)
+    .split(portableRoot).join(side)
+    .split(path.sep).join(path.posix.sep);
+  return makeDiagnostic({
+    code: "AUTH_REVIEW_CORPUS_INVALID",
+    file: side,
+    range: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+    pointer: "",
+    reason,
+    repair: "provide one complete canonical authority corpus; unsupported or partial inputs are refused",
+  });
+}
+
+async function compileSnapshot(root, side) {
+  try {
+    const result = await compileAuthorityPath(root);
+    if (result.ok) return { result, diagnostics: [] };
+    return { result: null, diagnostics: normalizeCompilerDiagnostics(result.diagnostics, root, side) };
+  } catch (error) {
+    if (error instanceof AuthorityInputError) return { result: null, diagnostics: [corpusInputDiagnostic(error, root, side)] };
+    throw error;
+  }
+}
+
+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 && isPathWithin(repository, absolute)) return relative.split(path.sep).join(path.posix.sep);
+  return path.basename(requested) || fallback;
+}
+
+async function captureReviewInput(file, temporaryRoot, name, label) {
+  let bytes;
+  try {
+    bytes = await captureStableRegularFile(file, label);
+  } catch (error) {
+    if (error instanceof AuthorityReviewRefusal) {
+      if (error.code === "AUTH_REVIEW_CAPTURE_CHANGED") throw error;
+      throw new AuthorityReviewRefusal("AUTH_REVIEW_INPUT_INVALID", `${name} must be one readable regular non-symlink file`, label);
+    }
+    throw error;
+  }
+  const directory = path.join(temporaryRoot, "inputs");
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const target = path.join(directory, `${name}.yaml`);
+  await writeFile(target, bytes, { flag: "wx", mode: 0o600 });
+  return target;
+}
+
+export function canonicalReviewBytes(review) {
+  return Buffer.byteLength(JSON.stringify(review), "utf8");
+}
+
+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 [baseCompiled, worktreeCompiled] = await Promise.all([
+    compileSnapshot(snapshot.base.root, "base"),
+    compileSnapshot(snapshot.worktree.root, "worktree"),
+  ]);
+  const compilerDiagnostics = [...baseCompiled.diagnostics, ...worktreeCompiled.diagnostics];
+  if (compilerDiagnostics.length > 0) return refused(compilerDiagnostics);
+  if (baseCompiled.result.fileCount !== snapshot.base.fileCount || worktreeCompiled.result.fileCount !== snapshot.worktree.fileCount) {
+    throw new Error("captured authority file counts do not match complete compiler admission");
+  }
+
+  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);
+  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 review = {
+    format: REVIEW_FORMAT,
+    operationStatus: "completed",
+    analysisComplete: true,
+    partial: false,
+    businessSemanticStatus: "not_evaluated",
+    implementationConformanceStatus: "not_evaluated",
+    snapshots: {
+      base: {
+        commitOid: snapshot.baseOid,
+        contentIdentity: snapshot.base.contentIdentity,
+        counts: {
+          files: snapshot.base.fileCount,
+          units: baseCompiled.result.unitCount,
+          bytes: snapshot.base.byteCount,
+        },
+      },
+      worktree: {
+        contentIdentity: snapshot.worktree.contentIdentity,
+        counts: {
+          files: snapshot.worktree.fileCount,
+          units: worktreeCompiled.result.unitCount,
+          bytes: snapshot.worktree.byteCount,
+        },
+      },
+    },
+    components: {
+      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,
+    audit: auditResult.audit,
+    budgets,
+  };
+  const reviewBytes = canonicalReviewBytes(review);
+  if (reviewBytes > budgets.maxBytes) return refused([reviewBudgetDiagnostic(reviewBytes, budgets.maxBytes)], reviewBytes);
+  return {
+    ok: true,
+    diagnostics: [],
+    fileCount: snapshot.base.fileCount + snapshot.worktree.fileCount,
+    unitCount: worktreeCompiled.result.unitCount,
+    reviewBytes,
+    review,
+    partial: false,
+  };
+}
+
+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)]);
+  }
+  try {
+    return await withGitAuthoritySnapshots({
+      repositoryPath,
+      baseRef,
+      hooks: options.snapshotHooks ?? null,
+    }, (snapshot) => composeReview(snapshot, bindingsPath, budgets));
+  } catch (error) {
+    if (error instanceof AuthorityReviewRefusal) return refused([authorityReviewRefusalDiagnostic(error)]);
+    throw error;
+  }
+}
+
+export { REVIEW_FORMAT };

package/cli/lib/authority/sarif.mjs

@@ -0,0 +1,174 @@
+const SARIF_SCHEMA =
+  "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json";
+const SARIF_VERSION = "2.1.0";
+const TOOL_NAME = "@nimiplatform/nimi-coding";
+const FINGERPRINT_KEY = "nimicoding.semanticFingerprint/v1";
+
+function copy(value) {
+  return value === undefined ? undefined : structuredClone(value);
+}
+
+function portableUri(file) {
+  return String(file)
+    .replaceAll("\\", "/")
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+function physicalLocation(location) {
+  const file = location?.file ?? location?.path;
+  if (typeof file !== "string" || !location?.range) return null;
+  const value = {
+    artifactLocation: { uri: portableUri(file) },
+    region: {
+      startLine: location.range.start.line,
+      startColumn: location.range.start.column,
+      endLine: location.range.end.line,
+      endColumn: location.range.end.column,
+    },
+  };
+  const sourcePointer = location.sourcePointer ?? location.pointer;
+  if (typeof sourcePointer === "string") value.properties = { sourcePointer };
+  return value;
+}
+
+function primaryLocation(location) {
+  const physical = physicalLocation(location);
+  return physical ? [{ physicalLocation: physical }] : [];
+}
+
+function relatedLocations(values = []) {
+  return values.flatMap((entry, index) => {
+    const physical = physicalLocation(entry.location ?? entry);
+    if (!physical) return [];
+    const role = entry.role ?? entry.location?.role;
+    const related = {
+      id: index + 1,
+      physicalLocation: physical,
+    };
+    if (typeof role === "string") {
+      related.message = { text: role };
+      related.properties = { role };
+    }
+    return [related];
+  });
+}
+
+function itemLevel(kind, item) {
+  return item.policy === "blocking" ? "error" : "warning";
+}
+
+function auditItemResult(kind, item) {
+  const result = {
+    ruleId: item.code,
+    level: itemLevel(kind, item),
+    message: { text: item.message },
+    locations: primaryLocation(item.primaryLocation),
+    relatedLocations: relatedLocations(item.relatedLocations),
+    partialFingerprints: { [FINGERPRINT_KEY]: item.fingerprint },
+    properties: {
+      kind,
+      code: item.code,
+      fingerprint: item.fingerprint,
+      detector: item.detector,
+      binding: item.binding,
+      premise: item.premise,
+      basis: item.basis,
+      policy: item.policy,
+      authorityRefs: copy(item.authorityRefs),
+      witness: copy(item.witness),
+    },
+  };
+  if (typeof item.target === "string") result.properties.target = item.target;
+  if (result.locations.length === 0) delete result.locations;
+  if (result.relatedLocations.length === 0) delete result.relatedLocations;
+  return result;
+}
+
+function diagnosticResult(diagnostic) {
+  const result = {
+    ruleId: diagnostic.code,
+    level: "error",
+    message: { text: diagnostic.reason },
+    locations: primaryLocation({
+      path: diagnostic.path,
+      range: diagnostic.range,
+      pointer: diagnostic.pointer,
+    }),
+    relatedLocations: relatedLocations(diagnostic.related),
+    properties: {
+      kind: "diagnostic",
+      code: diagnostic.code,
+      severity: diagnostic.severity,
+      pointer: diagnostic.pointer,
+      repair: diagnostic.repair,
+    },
+  };
+  if (result.locations.length === 0) delete result.locations;
+  if (result.relatedLocations.length === 0) delete result.relatedLocations;
+  return result;
+}
+
+function rulesFor(results) {
+  const codes = [...new Set(results.map((result) => result.ruleId))].sort();
+  return codes.map((code) => ({
+    id: code,
+    shortDescription: { text: code },
+  }));
+}
+
+function invocationProperties(result) {
+  if (!result.audit) {
+    return {
+      operationStatus: "refused",
+    };
+  }
+  return {
+    format: result.audit.format,
+    operationStatus: result.audit.operationStatus,
+    blockingStatus: result.audit.blockingStatus,
+    counts: copy(result.audit.counts),
+    budgets: copy(result.audit.budgets),
+  };
+}
+
+export function authorityAuditResultToSarif(result, { toolVersion }) {
+  if (!result || typeof result !== "object")
+    throw new TypeError("authority audit result must be an object");
+  if (typeof toolVersion !== "string" || toolVersion.length === 0)
+    throw new TypeError("toolVersion must be a non-empty string");
+
+  const results = result.audit
+    ? [
+        ...(result.audit.findings ?? []).map((item) => auditItemResult("finding", item)),
+      ]
+    : (result.diagnostics ?? []).map(diagnosticResult);
+  const rules = rulesFor(results);
+  const ruleIndexes = new Map(rules.map((rule, index) => [rule.id, index]));
+  for (const entry of results) entry.ruleIndex = ruleIndexes.get(entry.ruleId);
+
+  return {
+    $schema: SARIF_SCHEMA,
+    version: SARIF_VERSION,
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: TOOL_NAME,
+            version: toolVersion,
+            rules,
+          },
+        },
+        columnKind: "unicodeCodePoints",
+        invocations: [
+          {
+            executionSuccessful: result.ok === true,
+            properties: invocationProperties(result),
+          },
+        ],
+        results,
+      },
+    ],
+  };
+}

package/cli/lib/authority/scope-bindings.mjs

@@ -0,0 +1,225 @@
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import YAML, { isMap, isScalar, isSeq } from "yaml";
+
+import { compareText, createLocator, makeDiagnostic, portablePath, sortDiagnostics, sourcePointer } from "./diagnostics.mjs";
+
+const SCOPE_BINDINGS_FORMAT = "nimicoding.scope-bindings/v1";
+const contractPath = fileURLToPath(new URL("../../../contracts/authority-scope-bindings.schema.yaml", import.meta.url));
+const LINE_BREAK = /[\u000A\u000B\u000C\u000D\u0085\u2028\u2029]/u;
+
+let contractPromise = null;
+
+function exactObject(value, fields) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).length === fields.length
+    && Object.keys(value).every((key) => fields.includes(key));
+}
+
+function pointerToken(value) {
+  return String(value).replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+function nodeRange(node, locator) {
+  const range = node?.range;
+  if (!Array.isArray(range)) return locator.range(0);
+  return locator.range(range[0], range[1] ?? range[0]);
+}
+
+function collectLocations(node, locator, pointer, locations) {
+  if (!node) return;
+  locations.set(pointer, nodeRange(node, locator));
+  if (isMap(node)) {
+    for (const pair of node.items) {
+      const key = isScalar(pair.key) ? String(pair.key.value) : "";
+      const childPointer = `${pointer}/${pointerToken(key)}`;
+      locations.set(childPointer, nodeRange(pair.value ?? pair.key, locator));
+      collectLocations(pair.value, locator, childPointer, locations);
+    }
+  } else if (isSeq(node)) {
+    node.items.forEach((item, index) => collectLocations(item, locator, `${pointer}/${index}`, locations));
+  }
+}
+
+async function loadContract() {
+  if (!contractPromise) contractPromise = readFile(contractPath, "utf8").then((text) => {
+    const contract = YAML.parse(text);
+    if (contract?.version !== 1 || contract?.contract?.id !== "nimicoding.scope-bindings.v1") {
+      throw new Error("installed scope binding contract is invalid");
+    }
+    return contract;
+  });
+  return contractPromise;
+}
+
+function scopeBindingDiagnostic(file, reason, location = null, code = "AUTH_SCOPE_BINDING_INVALID", repair = "declare the exact closed scope registry without inferring repository anchors") {
+  return makeDiagnostic({
+    code,
+    file,
+    range: location?.range ?? { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+    pointer: location?.sourcePointer ?? "",
+    reason,
+    repair,
+  });
+}
+
+function parsedLocation(parsed, pointer) {
+  return {
+    file: parsed.file,
+    range: parsed.locations.get(pointer) ?? parsed.locations.get("") ?? { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+    sourcePointer: pointer,
+  };
+}
+
+function syntaxLocation(error, file, locator) {
+  const positions = Array.isArray(error?.pos) ? error.pos : [0, 0];
+  return {
+    file,
+    range: locator.range(positions[0] ?? 0, positions[1] ?? positions[0] ?? 0),
+    sourcePointer: "",
+  };
+}
+
+function validText(value) {
+  return typeof value === "string"
+    && value.length > 0
+    && value.isWellFormed()
+    && !LINE_BREAK.test(value);
+}
+
+async function loadScopeBindings(file) {
+  const absolute = path.resolve(file);
+  const label = portablePath(absolute);
+  let bytes;
+  try {
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink() || !info.isFile()) {
+      return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "scope bindings must be one regular non-symlink YAML file")] };
+    }
+    bytes = await readFile(absolute);
+  } catch (error) {
+    return { ok: false, diagnostics: [scopeBindingDiagnostic(label, `scope binding file is not readable: ${error.message}`)] };
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "scope binding bytes are not valid UTF-8")] };
+  }
+  const locator = createLocator(text);
+  const documents = YAML.parseAllDocuments(text, {
+    keepSourceTokens: true,
+    prettyErrors: false,
+    strict: true,
+    uniqueKeys: true,
+    version: "1.2",
+  });
+  if (documents.length !== 1 || documents[0].errors.length > 0 || !isMap(documents[0].contents)) {
+    const error = documents[0]?.errors?.[0];
+    const location = syntaxLocation(error, label, locator);
+    const reason = documents.length !== 1
+      ? "scope bindings must contain exactly one YAML document"
+      : error ? `invalid scope binding YAML: ${error.message.split(" at line")[0]}` : "scope bindings require one top-level mapping";
+    return { ok: false, diagnostics: [scopeBindingDiagnostic(label, reason, location)] };
+  }
+  let data;
+  try {
+    data = documents[0].toJS({ maxAliasCount: 0 });
+  } catch (error) {
+    return { ok: false, diagnostics: [scopeBindingDiagnostic(label, `invalid scope binding YAML: ${error.message}`)] };
+  }
+  const locations = new Map();
+  collectLocations(documents[0].contents, locator, "", locations);
+  const parsed = { file: label, locations, data };
+  const contract = await loadContract();
+  if (!exactObject(data, contract.fields.top)
+    || data.format !== SCOPE_BINDINGS_FORMAT
+    || !Array.isArray(data.scopes)
+    || data.scopes.length === 0) {
+    return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "scope bindings require exact format and one non-empty scopes sequence", parsedLocation(parsed, ""))] };
+  }
+  const scopes = [];
+  const seenScopes = new Set();
+  for (let index = 0; index < data.scopes.length; index += 1) {
+    const value = data.scopes[index];
+    const pointer = `/scopes/${index}`;
+    if (!exactObject(value, contract.fields.scope)) {
+      return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "each scope entry requires exact scope and bindings fields", parsedLocation(parsed, pointer))] };
+    }
+    if (!validText(value.scope)) {
+      return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "scope must be one non-empty text line", parsedLocation(parsed, `${pointer}/scope`))] };
+    }
+    if (seenScopes.has(value.scope)) {
+      return { ok: false, diagnostics: [scopeBindingDiagnostic(label, `duplicate registered scope: ${value.scope}`, parsedLocation(parsed, `${pointer}/scope`))] };
+    }
+    seenScopes.add(value.scope);
+    if (!Array.isArray(value.bindings) || value.bindings.length === 0) {
+      return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "scope bindings must be a non-empty sequence", parsedLocation(parsed, `${pointer}/bindings`))] };
+    }
+    const bindings = [];
+    for (let bindingIndex = 0; bindingIndex < value.bindings.length; bindingIndex += 1) {
+      const binding = value.bindings[bindingIndex];
+      const bindingPointer = `${pointer}/bindings/${bindingIndex}`;
+      if (!exactObject(binding, contract.fields.binding)) {
+        return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "each scope binding requires exact kind and value fields", parsedLocation(parsed, bindingPointer))] };
+      }
+      if (!contract.binding_kinds.includes(binding.kind)) {
+        return { ok: false, diagnostics: [scopeBindingDiagnostic(label, `scope binding kind must be one of: ${contract.binding_kinds.join(", ")}`, parsedLocation(parsed, `${bindingPointer}/kind`))] };
+      }
+      if (!validText(binding.value)) {
+        return { ok: false, diagnostics: [scopeBindingDiagnostic(label, "scope binding value must be one non-empty text line", parsedLocation(parsed, `${bindingPointer}/value`))] };
+      }
+      bindings.push({
+        kind: binding.kind,
+        value: binding.value,
+        location: parsedLocation(parsed, `${bindingPointer}/value`),
+      });
+    }
+    scopes.push({ scope: value.scope, location: parsedLocation(parsed, `${pointer}/scope`), bindings });
+  }
+  scopes.sort((left, right) => compareText(left.scope, right.scope));
+  return { ok: true, diagnostics: [], scopes };
+}
+
+function sourceRange(source, pointer) {
+  return source.locations.get(pointer) ?? source.locations.get("") ?? source.locator.range(0);
+}
+
+export async function validateAuthorityScopeBindings(sources, bindingsPath) {
+  const parsed = await loadScopeBindings(bindingsPath);
+  if (!parsed.ok) return parsed;
+  const registered = new Set(parsed.scopes.map((entry) => entry.scope));
+  const used = new Set();
+  const diagnostics = [];
+  for (const source of sources) {
+    if (source.data.kind !== "rule" || source.data.lifecycle !== "active") continue;
+    source.data.scope.forEach((scope, index) => {
+      used.add(scope);
+      if (registered.has(scope)) return;
+      const pointer = `/scope/${index}`;
+      diagnostics.push(makeDiagnostic({
+        code: "AUTH_SCOPE_UNREGISTERED",
+        file: source.file,
+        range: sourceRange(source, pointer),
+        pointer: sourcePointer(source, pointer),
+        reason: `active rule ${source.data.id} uses unregistered scope: ${scope}`,
+        repair: "register the exact scope and its declared bindings; repository anchor resolution is not performed by check",
+      }));
+    });
+  }
+  for (const entry of parsed.scopes) {
+    if (used.has(entry.scope)) continue;
+    diagnostics.push(scopeBindingDiagnostic(
+      entry.location.file,
+      `registered scope has no active rule use: ${entry.scope}`,
+      entry.location,
+      "AUTH_SCOPE_BINDING_UNUSED",
+      "remove the dead registration or declare an active rule use only from product authority",
+    ));
+  }
+  return { ok: diagnostics.length === 0, diagnostics: sortDiagnostics(diagnostics) };
+}
+
+export { loadScopeBindings, SCOPE_BINDINGS_FORMAT };