@cassiomc1/forgeloop 1.8.1 → 1.10.0

package/src/core/structural-quality/artifacts.js

@@ -0,0 +1,329 @@
+import { readdir } from "node:fs/promises";
+
+import {
+  canonicalFingerprint,
+  readJsonArtifact,
+  writeJsonArtifact,
+} from "../artifacts.js";
+import { fileExists, ensureWithin, assertSafePath } from "../filesystem.js";
+import {
+  E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH,
+  E_STRUCTURAL_QUALITY_BASELINE_EXISTS,
+  E_STRUCTURAL_QUALITY_BASELINE_PHASE_INVALID,
+  E_STRUCTURAL_QUALITY_EVIDENCE_STALE,
+} from "../error-codes.js";
+import { getPackageRoot } from "../templates.js";
+import {
+  taskStructuralQualityBaselinePath,
+  taskStructuralQualityDirectory,
+  taskStructuralQualityEvaluationPath,
+  taskStructuralQualityEvaluationsDirectory,
+} from "../task-paths.js";
+import { STRUCTURAL_QUALITY_ROOT_CAUSES, structuralQualityError } from "./constants.js";
+import { normalizeStructuralQualityDetection, normalizeStructuralQualitySnapshot } from "./provider.js";
+
+const PRE_EXECUTION_PHASES = new Set([
+  "RECEIVED",
+  "DISCOVERING",
+  "CONTRACT_READY",
+  "ROUTED",
+  "DESIGNING",
+  "PLANNED",
+]);
+
+function qualityArtifactError(code, message, artifacts = []) {
+  return structuralQualityError(code, message, artifacts);
+}
+
+function normalizeCycle(value, label) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} must be a positive integer`);
+  }
+  return value;
+}
+
+function normalizeAttempt(value) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, "structural-quality attempt must be a positive integer");
+  }
+  return value;
+}
+
+function readFailure(error, relativePath, missingCode) {
+  if (error?.code === "ARTIFACT_MISSING") {
+    return qualityArtifactError(missingCode, `Structural-quality artifact is missing: ${relativePath}`, [relativePath]);
+  }
+  if (error?.code?.startsWith("E_STRUCTURAL_QUALITY")) return error;
+  return qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `Structural-quality artifact is invalid: ${error.message}`, [relativePath]);
+}
+
+export function validateStructuralQualityArtifact(value, label = "structural-quality artifact") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} must be an object`);
+  }
+  if (value.role === "BASELINE") {
+    if (value.verificationCycle !== null) throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} baseline verificationCycle must be null`);
+    if (value.status !== "PASS") throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} baseline status must be PASS`);
+    if (value.bindings?.baselineFingerprint !== undefined && value.bindings.baselineFingerprint !== null) {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH, `${label} baselineFingerprint must be null`);
+    }
+  } else if (value.role === "EVALUATION") {
+    if (!Number.isInteger(value.verificationCycle) || value.verificationCycle < 1) {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} evaluation verificationCycle must be positive`);
+    }
+    if (!Number.isInteger(value.attempt) || value.attempt < 1) {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} evaluation attempt must be positive`);
+    }
+    if (!Array.isArray(value.reasonCodes) || (value.status !== "PASS" && value.reasonCodes.length === 0)) {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} non-PASS evaluations require a reason code`);
+    }
+    if (!value.comparison || typeof value.comparison !== "object") {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} evaluation comparison is required`);
+    }
+    const comparisonStatus = value.comparison.status;
+    if (value.status === "PASS" && comparisonStatus !== "PASS") {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} PASS status requires a PASS comparison`);
+    }
+    if (value.status === "FAIL" && comparisonStatus !== "FAIL") {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} FAIL status requires a FAIL comparison`);
+    }
+    if (["BLOCKED", "NOT_OBSERVED"].includes(value.status) && comparisonStatus === "PASS") {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} unavailable evaluation cannot contain a PASS comparison`);
+    }
+  } else {
+    throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} role must be BASELINE or EVALUATION`);
+  }
+  const observed = value.role === "BASELINE" || ["PASS", "FAIL"].includes(value.status);
+  const sourceFingerprint = value.bindings?.sourceMaterialFingerprint;
+  if (observed) {
+    if (typeof sourceFingerprint !== "string" || !/^[a-f0-9]{64}$/u.test(sourceFingerprint)) {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} observed evidence requires sourceMaterialFingerprint`);
+    }
+    if (!value.sourceObservation || value.sourceObservation.stable !== true) {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} observed evidence requires a stable sourceObservation`);
+    }
+  }
+  if (!value.detection || typeof value.detection !== "object" || Array.isArray(value.detection)) {
+    throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} detection metadata is required`);
+  }
+  if (value.provider?.id !== value.detection?.providerId) {
+    throw qualityArtifactError(E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH, `${label} provider and detection IDs differ`);
+  }
+  if (value.sourceObservation !== undefined && value.sourceObservation !== null) {
+    if (typeof value.sourceObservation !== "object" || Array.isArray(value.sourceObservation)) {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} sourceObservation must be an object`);
+    }
+    if (typeof value.sourceObservation.beforeFingerprint !== "string"
+      || typeof value.sourceObservation.afterFingerprint !== "string"
+      || typeof value.sourceObservation.stable !== "boolean") {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} sourceObservation requires beforeFingerprint, afterFingerprint, and stable`);
+    }
+    if (value.sourceObservation.stable === true
+      && (value.sourceObservation.beforeFingerprint !== value.sourceObservation.afterFingerprint
+        || (typeof sourceFingerprint === "string" && value.sourceObservation.beforeFingerprint !== sourceFingerprint))) {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} stable sourceObservation does not match its source binding`);
+    }
+    if (!value.sourceObservation.stable && ["PASS", "FAIL"].includes(value.status)) {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} unstable sourceObservation cannot produce observed evidence`);
+    }
+  }
+  normalizeStructuralQualityDetection(value.detection, {
+    providerId: value.provider?.id,
+    version: value.provider?.version,
+    transport: value.provider?.transport,
+    measurementModel: value.provider?.measurementModel,
+    compatibilityKey: value.provider?.compatibilityKey,
+  });
+  if (value.snapshot !== undefined) normalizeStructuralQualitySnapshot(value.snapshot);
+  if (["PASS", "FAIL"].includes(value.status) && value.snapshot === undefined) {
+    throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `${label} observed status requires a normalized snapshot`);
+  }
+  return value;
+}
+
+export function structuralQualityArtifactRef(taskId, relativePath) {
+  const expectedRoot = taskStructuralQualityDirectory(taskId).replaceAll("\\", "/");
+  const portable = String(relativePath).replaceAll("\\", "/");
+  if (portable.startsWith("/")
+    || portable.split("/").some((part) => part === "..")
+    || (portable !== expectedRoot && !portable.startsWith(`${expectedRoot}/`))) {
+    throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `Artifact reference escapes the structural-quality directory: ${relativePath}`, [portable]);
+  }
+  return portable;
+}
+
+export async function readStructuralQualityBaseline(target, taskId, packageRoot = getPackageRoot()) {
+  const relativePath = taskStructuralQualityBaselinePath(taskId);
+  try {
+    const artifact = await readJsonArtifact(target, relativePath, "structural-quality", packageRoot);
+    validateStructuralQualityArtifact(artifact.value, relativePath);
+    return artifact;
+  } catch (error) {
+    if (error?.code === "ARTIFACT_MISSING") return null;
+    throw readFailure(error, relativePath, E_STRUCTURAL_QUALITY_EVIDENCE_STALE);
+  }
+}
+
+export async function writeStructuralQualityBaseline(
+  target,
+  taskId,
+  value,
+  packageRoot = getPackageRoot(),
+  { phase = "PLANNED", replace = false, taskId: transactionTaskId = taskId } = {},
+) {
+  const relativePath = taskStructuralQualityBaselinePath(taskId);
+  if (!PRE_EXECUTION_PHASES.has(phase)) {
+    throw qualityArtifactError(
+      E_STRUCTURAL_QUALITY_BASELINE_PHASE_INVALID,
+      `Structural-quality baselines cannot be written or replaced in ${phase}`,
+      [relativePath],
+    );
+  }
+  const existing = await readStructuralQualityBaseline(target, taskId, packageRoot);
+  const fingerprint = canonicalFingerprint(value);
+  if (existing) {
+    if (existing.fingerprint === fingerprint) {
+      return { ...existing, existing: true, identical: true };
+    }
+    if (!replace) {
+      throw qualityArtifactError(
+        E_STRUCTURAL_QUALITY_BASELINE_EXISTS,
+        "The structural-quality baseline already exists and is immutable without --replace before EXECUTING",
+        [relativePath],
+      );
+    }
+  }
+  const written = await writeJsonArtifact(
+    target,
+    relativePath,
+    value,
+    "structural-quality",
+    packageRoot,
+    { taskId: transactionTaskId, operation: "structural-quality-baseline" },
+  );
+  return { ...written, existing: Boolean(existing), identical: false };
+}
+
+export async function listStructuralQualityEvaluations(target, taskId, packageRoot = getPackageRoot()) {
+  const relativeDirectory = taskStructuralQualityEvaluationsDirectory(taskId);
+  await assertSafePath(target, relativeDirectory);
+  const absoluteDirectory = ensureWithin(target, relativeDirectory);
+  if (!(await fileExists(absoluteDirectory))) return [];
+  let entries;
+  try {
+    entries = await readdir(absoluteDirectory, { withFileTypes: true });
+  } catch (error) {
+    throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `Unable to list structural-quality evaluations: ${error.message}`, [relativeDirectory]);
+  }
+  const candidates = entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => {
+      const match = /^cycle-(\d+)-attempt-(\d+)\.json$/u.exec(entry.name);
+      return match ? { name: entry.name, verificationCycle: Number(match[1]), attempt: Number(match[2]) } : null;
+    })
+    .filter(Boolean)
+    .filter((item) => item.verificationCycle >= 1 && item.attempt >= 1)
+    .sort((left, right) => left.verificationCycle - right.verificationCycle || left.attempt - right.attempt);
+  const result = [];
+  for (const item of candidates) {
+    const relativePath = taskStructuralQualityEvaluationPath(taskId, item.verificationCycle, item.attempt);
+    try {
+      const artifact = await readJsonArtifact(target, relativePath, "structural-quality", packageRoot);
+      validateStructuralQualityArtifact(artifact.value, relativePath);
+      if (artifact.value.role !== "EVALUATION"
+        || artifact.value.verificationCycle !== item.verificationCycle
+        || artifact.value.attempt !== item.attempt) {
+        throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `Evaluation filename does not match its typed cycle/attempt: ${relativePath}`, [relativePath]);
+      }
+      result.push(artifact);
+    } catch (error) {
+      throw readFailure(error, relativePath, E_STRUCTURAL_QUALITY_EVIDENCE_STALE);
+    }
+  }
+  return result;
+}
+
+export async function readStructuralQualityEvaluation(target, taskId, verificationCycle, attempt, packageRoot = getPackageRoot()) {
+  const relativePath = taskStructuralQualityEvaluationPath(taskId, normalizeCycle(verificationCycle, "verificationCycle"), normalizeAttempt(attempt));
+  try {
+    const artifact = await readJsonArtifact(target, relativePath, "structural-quality", packageRoot);
+    validateStructuralQualityArtifact(artifact.value, relativePath);
+    if (artifact.value.role !== "EVALUATION"
+      || artifact.value.verificationCycle !== verificationCycle
+      || artifact.value.attempt !== attempt) {
+      throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `Evaluation identity does not match ${relativePath}`, [relativePath]);
+    }
+    return artifact;
+  } catch (error) {
+    throw readFailure(error, relativePath, E_STRUCTURAL_QUALITY_EVIDENCE_STALE);
+  }
+}
+
+export async function writeStructuralQualityEvaluation(target, taskId, verificationCycle, attempt, value, packageRoot = getPackageRoot(), { transactionTaskId = taskId } = {}) {
+  const cycle = normalizeCycle(verificationCycle, "verificationCycle");
+  const normalizedAttempt = normalizeAttempt(attempt);
+  const relativePath = taskStructuralQualityEvaluationPath(taskId, cycle, normalizedAttempt);
+  if (value.role !== "EVALUATION" || value.verificationCycle !== cycle || value.attempt !== normalizedAttempt) {
+    throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `Evaluation identity does not match ${relativePath}`, [relativePath]);
+  }
+  validateStructuralQualityArtifact(value, relativePath);
+  const existing = await fileExists(ensureWithin(target, relativePath));
+  if (existing) {
+    const current = await readStructuralQualityEvaluation(target, taskId, cycle, normalizedAttempt, packageRoot);
+    if (current.fingerprint === canonicalFingerprint(value)) return { ...current, existing: true, identical: true };
+    throw qualityArtifactError(E_STRUCTURAL_QUALITY_EVIDENCE_STALE, `Evaluation attempt is immutable: ${relativePath}`, [relativePath]);
+  }
+  const written = await writeJsonArtifact(
+    target,
+    relativePath,
+    value,
+    "structural-quality",
+    packageRoot,
+    { taskId: transactionTaskId, operation: "structural-quality-evaluation" },
+  );
+  return { ...written, existing: false, identical: false };
+}
+
+export function validateStructuralQualityBindings(value, expected = {}) {
+  const errors = [];
+  const bindings = value?.bindings ?? {};
+  const fields = ["contractFingerprint", "routeFingerprint", "policyFingerprint", "scopeFingerprint"];
+  for (const field of fields) {
+    if (expected[field] !== undefined && bindings[field] !== expected[field]) {
+      errors.push({
+        code: E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH,
+        message: `Structural-quality ${field} does not match the active task binding`,
+      });
+    }
+  }
+  if (expected.providerId !== undefined && value.provider?.id !== expected.providerId) {
+    errors.push({ code: E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH, message: "Structural-quality provider ID does not match the active policy" });
+  }
+  if (expected.providerVersion !== undefined && expected.providerVersion !== null && value.provider?.version !== expected.providerVersion) {
+    errors.push({ code: E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH, message: "Structural-quality provider version does not match the baseline" });
+  }
+  if (expected.baselineFingerprint !== undefined && bindings.baselineFingerprint !== expected.baselineFingerprint) {
+    errors.push({ code: E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH, message: "Structural-quality evaluation does not bind the active baseline" });
+  }
+  if (expected.verificationCycle !== undefined && value.verificationCycle !== expected.verificationCycle) {
+    errors.push({ code: E_STRUCTURAL_QUALITY_EVIDENCE_STALE, message: "Structural-quality evidence belongs to a different verification cycle" });
+  }
+  return errors;
+}
+
+export function assertStructuralQualityBindings(value, expected = {}) {
+  const errors = validateStructuralQualityBindings(value, expected);
+  if (errors.length > 0) {
+    const artifactRef = expected.artifactRef ?? null;
+    throw qualityArtifactError(
+      errors[0].code,
+      errors[0].message,
+      artifactRef ? [structuralQualityArtifactRef(expected.taskId ?? value.taskId, artifactRef)] : [],
+    );
+  }
+  return value;
+}
+
+export function structuralQualityRootCauseNames() {
+  return [...STRUCTURAL_QUALITY_ROOT_CAUSES];
+}

package/src/core/structural-quality/constants.js

@@ -0,0 +1,67 @@
+import { E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID } from "../error-codes.js";
+
+export const STRUCTURAL_QUALITY_ROOT_CAUSES = Object.freeze([
+  "modularity",
+  "acyclicity",
+  "depth",
+  "equality",
+  "redundancy",
+]);
+
+export const STRUCTURAL_QUALITY_MODES = Object.freeze(["off", "observe", "gate"]);
+export const STRUCTURAL_QUALITY_STATUSES = Object.freeze(["PASS", "FAIL", "BLOCKED", "NOT_OBSERVED"]);
+export const STRUCTURAL_QUALITY_CHECK_ID = "structural-quality";
+export const STRUCTURAL_QUALITY_REQUIREMENT = "Structural quality must not regress beyond the configured budget";
+export const STRUCTURAL_QUALITY_PROVIDER_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/u;
+export const STRUCTURAL_QUALITY_SENTRUX_MIN_VERSION = "0.5.5";
+// Kept as an alias for early callers that used the misspelled constant before
+// the public provider name was finalized.
+export const STRUCTURAL_QUALITY_SENTRYX_MIN_VERSION = STRUCTURAL_QUALITY_SENTRUX_MIN_VERSION;
+export const STRUCTURAL_QUALITY_DEFAULT_TIMEOUT_MS = 120_000;
+export const STRUCTURAL_QUALITY_MAX_TIMEOUT_MS = 300_000;
+export const STRUCTURAL_QUALITY_MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+export const STRUCTURAL_QUALITY_MAX_DIAGNOSTICS = 50;
+export const STRUCTURAL_QUALITY_MAX_DIAGNOSTIC_STRING = 4096;
+export const STRUCTURAL_QUALITY_MAX_EXTRA_EVALUATIONS = 2;
+
+export const STRUCTURAL_QUALITY_MEASUREMENT_MODEL = "structural-root-causes-v1";
+export const STRUCTURAL_QUALITY_SENTRUX_COMPATIBILITY_KEY = "sentrux-structural-root-causes-v1";
+export const STRUCTURAL_QUALITY_SENTRUX_VERIFIED_VERSIONS = Object.freeze(["0.5.5", "0.5.6", "0.5.7"]);
+
+export const STRUCTURAL_QUALITY_DEFAULT_DIMENSION_BUDGETS = Object.freeze(
+  Object.fromEntries(STRUCTURAL_QUALITY_ROOT_CAUSES.map((cause) => [cause, null])),
+);
+
+export const STRUCTURAL_QUALITY_DEFAULT_OPTIMIZATION = Object.freeze({
+  mode: "off",
+  maxExtraEvaluations: STRUCTURAL_QUALITY_MAX_EXTRA_EVALUATIONS,
+  minGainPoints: 25,
+});
+
+export const STRUCTURAL_QUALITY_DEFAULT_GATE_POLICY = Object.freeze({
+  mode: "gate",
+  provider: "sentrux",
+  maxRegressionPoints: 0,
+  dimensionBudgets: STRUCTURAL_QUALITY_DEFAULT_DIMENSION_BUDGETS,
+  forbidNewCycles: true,
+  minQualitySignal: null,
+  minimums: Object.freeze({}),
+  optimization: STRUCTURAL_QUALITY_DEFAULT_OPTIMIZATION,
+});
+
+export function structuralQualityError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+export function assertStructuralQualityMode(mode) {
+  if (!STRUCTURAL_QUALITY_MODES.includes(mode)) {
+    throw structuralQualityError(
+      E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID,
+      `structuralQuality.mode must be one of ${STRUCTURAL_QUALITY_MODES.join(", ")}`,
+    );
+  }
+  return mode;
+}

package/src/core/structural-quality/policy.js

@@ -0,0 +1,227 @@
+import { canonicalFingerprint } from "../artifacts.js";
+import {
+  E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID,
+} from "../error-codes.js";
+import {
+  STRUCTURAL_QUALITY_DEFAULT_DIMENSION_BUDGETS,
+  STRUCTURAL_QUALITY_DEFAULT_OPTIMIZATION,
+  STRUCTURAL_QUALITY_MODES,
+  STRUCTURAL_QUALITY_ROOT_CAUSES,
+  STRUCTURAL_QUALITY_PROVIDER_ID_PATTERN,
+  structuralQualityError,
+} from "./constants.js";
+import { structuralQualityProviderCompatibility } from "./provider.js";
+
+const POLICY_KEYS = new Set([
+  "mode",
+  "provider",
+  "maxRegressionPoints",
+  "dimensionBudgets",
+  "forbidNewCycles",
+  "minQualitySignal",
+  "minimums",
+  "optimization",
+]);
+
+function plainObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw structuralQualityError(E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID, `${label} must be an object`);
+  }
+  return value;
+}
+
+function integer(value, label, { min = 0, max = 10_000 } = {}) {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw structuralQualityError(
+      E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID,
+      `${label} must be an integer between ${min} and ${max}`,
+    );
+  }
+  return value;
+}
+
+function normalizeBudgets(value, label) {
+  const source = value === undefined ? {} : plainObject(value, label);
+  const unknown = Object.keys(source).find((key) => !STRUCTURAL_QUALITY_ROOT_CAUSES.includes(key));
+  if (unknown) {
+    throw structuralQualityError(E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID, `${label} contains unknown root cause: ${unknown}`);
+  }
+  return Object.fromEntries(STRUCTURAL_QUALITY_ROOT_CAUSES.map((cause) => {
+    const raw = source[cause];
+    if (raw === null || raw === undefined) {
+      return [cause, STRUCTURAL_QUALITY_DEFAULT_DIMENSION_BUDGETS[cause] ?? null];
+    }
+    return [cause, integer(raw, `${label}.${cause}`)];
+  }));
+}
+
+function normalizeMinimums(value) {
+  const source = value === undefined ? {} : plainObject(value, "structuralQuality.minimums");
+  const unknown = Object.keys(source).find((key) => !STRUCTURAL_QUALITY_ROOT_CAUSES.includes(key));
+  if (unknown) {
+    throw structuralQualityError(E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID, `structuralQuality.minimums contains unknown root cause: ${unknown}`);
+  }
+  return Object.fromEntries(Object.entries(source).map(([cause, minimum]) => [
+    cause,
+    integer(minimum, `structuralQuality.minimums.${cause}`),
+  ]));
+}
+
+function normalizeOptimization(value) {
+  const source = value === undefined ? {} : plainObject(value, "structuralQuality.optimization");
+  const unknown = Object.keys(source).find((key) => !["mode", "maxExtraEvaluations", "minGainPoints"].includes(key));
+  if (unknown) {
+    throw structuralQualityError(E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID, `structuralQuality.optimization contains unknown property: ${unknown}`);
+  }
+  const mode = source.mode ?? STRUCTURAL_QUALITY_DEFAULT_OPTIMIZATION.mode;
+  if (!["off", "bounded"].includes(mode)) {
+    throw structuralQualityError(E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID, "structuralQuality.optimization.mode must be off or bounded");
+  }
+  const maxExtraEvaluations = source.maxExtraEvaluations ?? STRUCTURAL_QUALITY_DEFAULT_OPTIMIZATION.maxExtraEvaluations;
+  integer(maxExtraEvaluations, "structuralQuality.optimization.maxExtraEvaluations", { min: 0, max: 2 });
+  const minGainPoints = source.minGainPoints ?? STRUCTURAL_QUALITY_DEFAULT_OPTIMIZATION.minGainPoints;
+  integer(minGainPoints, "structuralQuality.optimization.minGainPoints", { min: 1, max: 10_000 });
+  return { mode, maxExtraEvaluations, minGainPoints };
+}
+
+export function normalizeStructuralQualityConfig(input) {
+  if (input === undefined || input === null) return undefined;
+  const source = plainObject(input, "structuralQuality");
+  const unknown = Object.keys(source).find((key) => !POLICY_KEYS.has(key));
+  if (unknown) {
+    throw structuralQualityError(E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID, `structuralQuality contains unknown property: ${unknown}`);
+  }
+  const mode = source.mode ?? "observe";
+  if (!STRUCTURAL_QUALITY_MODES.includes(mode)) {
+    throw structuralQualityError(E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID, `Unknown structural quality mode: ${mode}`);
+  }
+  const provider = source.provider ?? "sentrux";
+  if (typeof provider !== "string" || !STRUCTURAL_QUALITY_PROVIDER_ID_PATTERN.test(provider)) {
+    throw structuralQualityError(E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID, "structuralQuality.provider must be a lower-case provider ID");
+  }
+  const maxRegressionPoints = source.maxRegressionPoints ?? 0;
+  integer(maxRegressionPoints, "structuralQuality.maxRegressionPoints");
+  const minQualitySignal = source.minQualitySignal === null || source.minQualitySignal === undefined
+    ? null
+    : integer(source.minQualitySignal, "structuralQuality.minQualitySignal");
+  if (source.forbidNewCycles !== undefined && typeof source.forbidNewCycles !== "boolean") {
+    throw structuralQualityError(E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID, "structuralQuality.forbidNewCycles must be boolean");
+  }
+  const policy = {
+    mode,
+    provider,
+    maxRegressionPoints,
+    dimensionBudgets: normalizeBudgets(source.dimensionBudgets, "structuralQuality.dimensionBudgets"),
+    forbidNewCycles: source.forbidNewCycles ?? true,
+    minQualitySignal,
+    minimums: normalizeMinimums(source.minimums),
+    optimization: normalizeOptimization(source.optimization),
+  };
+  return Object.freeze({
+    ...policy,
+    dimensionBudgets: Object.freeze(policy.dimensionBudgets),
+    minimums: Object.freeze(policy.minimums),
+    optimization: Object.freeze(policy.optimization),
+  });
+}
+
+function snapshotOf(value) {
+  return value?.snapshot && typeof value.snapshot === "object" ? value.snapshot : value;
+}
+
+function assertComparableInputs(baseline, current) {
+  const reasons = [];
+  const baselineProvider = baseline?.provider;
+  const currentProvider = current?.provider;
+  const baselineScope = baseline?.scope;
+  const currentScope = current?.scope;
+  for (const provider of [baselineProvider, currentProvider]) {
+    if (provider?.id === "sentrux" && provider?.version !== undefined && provider?.version !== null) {
+      const compatibility = structuralQualityProviderCompatibility(provider);
+      if (!compatibility.supported) reasons.push("PROVIDER_VERSION_UNSUPPORTED");
+    }
+  }
+  if (baselineProvider?.id !== undefined && currentProvider?.id !== undefined
+    && baselineProvider.id !== currentProvider.id) reasons.push("PROVIDER_ID_CHANGED");
+  if (baselineProvider?.measurementModel !== undefined && currentProvider?.measurementModel !== undefined
+    && baselineProvider.measurementModel !== currentProvider.measurementModel) reasons.push("MEASUREMENT_MODEL_MISMATCH");
+  if (baselineProvider?.compatibilityKey !== undefined && currentProvider?.compatibilityKey !== undefined
+    && baselineProvider.compatibilityKey !== currentProvider.compatibilityKey) reasons.push("COMPATIBILITY_KEY_CHANGED");
+  if (baselineProvider?.version !== undefined && currentProvider?.version !== undefined
+    && baselineProvider.version !== currentProvider.version) {
+    const sameCompat = baselineProvider?.compatibilityKey && currentProvider?.compatibilityKey
+      && baselineProvider.compatibilityKey === currentProvider.compatibilityKey;
+    if (!sameCompat) {
+      reasons.push("PROVIDER_VERSION_CHANGED");
+    }
+  }
+  if (baselineScope?.providerConfigFingerprint !== undefined && currentScope?.providerConfigFingerprint !== undefined
+    && baselineScope.providerConfigFingerprint !== currentScope.providerConfigFingerprint) reasons.push("PROVIDER_CONFIG_CHANGED");
+  if (baseline?.bindings?.policyFingerprint && current?.bindings?.policyFingerprint
+    && baseline.bindings.policyFingerprint !== current.bindings.policyFingerprint) reasons.push("POLICY_CHANGED");
+  if (baseline?.bindings?.scopeFingerprint && current?.bindings?.scopeFingerprint
+    && baseline.bindings.scopeFingerprint !== current.bindings.scopeFingerprint) reasons.push("SCOPE_CHANGED");
+  return reasons;
+}
+
+export function compareStructuralQuality({ baseline, current, policy } = {}) {
+  const normalizedPolicy = normalizeStructuralQualityConfig(policy ?? { mode: "gate", provider: "sentrux" });
+  const baselineSnapshot = snapshotOf(baseline);
+  const currentSnapshot = snapshotOf(current);
+  const incompatibilities = assertComparableInputs(baseline, current);
+  const rootCauseDeltas = Object.fromEntries(STRUCTURAL_QUALITY_ROOT_CAUSES.map((cause) => [
+    cause,
+    Number.isInteger(currentSnapshot?.rootCauses?.[cause]?.score) && Number.isInteger(baselineSnapshot?.rootCauses?.[cause]?.score)
+      ? currentSnapshot.rootCauses[cause].score - baselineSnapshot.rootCauses[cause].score
+      : null,
+  ]));
+  const qualityDelta = Number.isInteger(currentSnapshot?.qualitySignal) && Number.isInteger(baselineSnapshot?.qualitySignal)
+    ? currentSnapshot.qualitySignal - baselineSnapshot.qualitySignal
+    : null;
+  const failedConditions = [];
+  const reasonCodes = [...incompatibilities];
+  if (incompatibilities.length === 0) {
+    if (qualityDelta === null || qualityDelta < -normalizedPolicy.maxRegressionPoints) {
+      failedConditions.push("qualitySignal");
+    }
+    for (const cause of STRUCTURAL_QUALITY_ROOT_CAUSES) {
+      const budget = normalizedPolicy.dimensionBudgets[cause];
+      if (budget !== null && budget !== undefined) {
+        const delta = rootCauseDeltas[cause];
+        if (delta === null || delta < -budget) failedConditions.push(cause);
+      }
+      const minimum = normalizedPolicy.minimums[cause];
+      if (minimum > 0 && (!Number.isInteger(currentSnapshot?.rootCauses?.[cause]?.score)
+        || currentSnapshot.rootCauses[cause].score < minimum)) failedConditions.push(`${cause}:minimum`);
+    }
+    if (normalizedPolicy.minQualitySignal !== null
+      && (!Number.isInteger(currentSnapshot?.qualitySignal) || currentSnapshot.qualitySignal < normalizedPolicy.minQualitySignal)) {
+      failedConditions.push("qualitySignal:minimum");
+    }
+    if (normalizedPolicy.forbidNewCycles
+      && Number.isFinite(baselineSnapshot?.rootCauses?.acyclicity?.raw)
+      && Number.isFinite(currentSnapshot?.rootCauses?.acyclicity?.raw)
+      && currentSnapshot.rootCauses.acyclicity.raw > baselineSnapshot.rootCauses.acyclicity.raw) {
+      failedConditions.push("acyclicity:new-cycles");
+    }
+    if (failedConditions.length > 0) reasonCodes.push("E_STRUCTURAL_QUALITY_REGRESSION");
+  } else {
+    if (incompatibilities.includes("MEASUREMENT_MODEL_MISMATCH")) {
+      reasonCodes.push("E_STRUCTURAL_QUALITY_MEASUREMENT_MODEL_MISMATCH");
+    }
+    reasonCodes.push("E_STRUCTURAL_QUALITY_EVALUATION_INCOMPARABLE");
+  }
+  const sortedReasons = [...new Set(reasonCodes)].sort();
+  return {
+    comparable: incompatibilities.length === 0,
+    qualityDelta,
+    rootCauseDeltas,
+    failedConditions: [...new Set(failedConditions)].sort(),
+    status: incompatibilities.length > 0 ? "NOT_OBSERVED" : failedConditions.length > 0 ? "FAIL" : "PASS",
+    reasonCodes: sortedReasons,
+  };
+}
+
+export function structuralQualityPolicyFingerprint(policy) {
+  return canonicalFingerprint(normalizeStructuralQualityConfig(policy));
+}