@cassiomc1/forgeloop 1.8.1 → 1.9.0

package/src/core/phase.js

@@ -26,6 +26,7 @@ import {
   buildInformationGainProjection,
   evaluateStructuredDiagnosticStall,
 } from "./information-gain-projection.js";
+import { assertStructuralQualityExecutionReady } from "./structural-quality/service.js";
 
 function phaseError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -134,9 +135,16 @@ async function assertPhasePrerequisites(target, state, toPhase, packageRoot, aut
       throw phaseError("E_PHASE_PREREQUISITE_MISSING", `Phase ${toPhase} requires ${routeRel}: ${error.message}`, [routeRel]);
     }
   }
+  if (toPhase === "EXECUTING" && scopedTaskId) {
+    try {
+      await assertStructuralQualityExecutionReady({ target, packageRoot, taskId: scopedTaskId, runtimeContext });
+    } catch (error) {
+      throw phaseError(error.code, error.message, error.artifacts);
+    }
+  }
   if (hasExecutionStarted(toPhase)) {
     try {
-      await assertExecutionPrerequisites({ target, state, packageRoot, ...options, taskId: scopedTaskId });
+      await assertExecutionPrerequisites({ target, state, packageRoot, ...options, taskId: scopedTaskId, runtimeContext });
     } catch (error) {
       throw phaseError(error.code, error.message, error.artifacts);
     }

package/src/core/preflight.js

@@ -28,6 +28,7 @@ import { PROFILE_PATH } from "./target-layout.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { validateEventLedger } from "./events.js";
 import { PROJECT_ARTIFACT_PATHS, taskArtifactPath } from "./task-paths.js";
+import { normalizeStructuralQualityConfig } from "./structural-quality/policy.js";
 
 const PREVIEW_DECISION_LIMIT = 10;
 const PREVIEW_DECISION_MAX_LENGTH = 240;
@@ -42,6 +43,17 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
   const contract = await loadContract(target, packageRoot, errors, { taskId, contractPath });
   const route = await loadRoute(target, packageRoot, errors, { taskId, routePath });
   const config = await optionalConfig(target, packageRoot, errors);
+  if (config.structuralQuality !== undefined) {
+    try {
+      normalizeStructuralQualityConfig(config.structuralQuality);
+    } catch (error) {
+      errors.push(issue(
+        error.code ?? "E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID",
+        error.message,
+        [PROJECT_ARTIFACT_PATHS.config],
+      ));
+    }
+  }
   const effectiveStrict = strict || config.complianceMode === "strict";
   if (effectiveStrict && profile.status !== "verified") {
     errors.push(issue("E_PROFILE_UNVERIFIED", "Strict preflight requires a verified project profile", [PROFILE_PATH]));
@@ -111,6 +123,26 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
 
   const sortedErrors = sortIssues(errors);
   const effectiveTaskId = taskId ?? contract?.value?.taskId ?? state?.taskId ?? "unknown";
+  let structuralQuality = {
+    mode: config.structuralQuality?.mode ?? "off",
+    provider: config.structuralQuality?.mode && config.structuralQuality.mode !== "off"
+      ? config.structuralQuality.provider ?? "sentrux"
+      : null,
+    baseline: { status: config.structuralQuality?.mode && config.structuralQuality.mode !== "off" ? "MISSING" : "NOT_REQUESTED" },
+    current: { status: "NOT_OBSERVED" },
+    comparable: null,
+    completionRequired: config.structuralQuality?.mode === "gate",
+    reasonCodes: [],
+    next: config.structuralQuality?.mode === "gate" ? "CAPTURE_STRUCTURAL_QUALITY_BASELINE" : null,
+  };
+  if (effectiveTaskId !== "unknown") {
+    try {
+      const { projectStructuralQualityStatus } = await import("./structural-quality/service.js");
+      structuralQuality = await projectStructuralQualityStatus({ target, packageRoot, taskId: effectiveTaskId });
+    } catch (error) {
+      structuralQuality.reasonCodes = [error.code ?? "E_STRUCTURAL_QUALITY_EVIDENCE_STALE"];
+    }
+  }
   return {
     schemaVersion: 1,
     protocolVersion: 1,
@@ -140,6 +172,7 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
       },
     } : {}),
     ...(sources ? { sources: { status: "valid", fingerprint: null } } : {}),
+    structuralQuality,
   };
 }
 

package/src/core/protocol-info.js

@@ -83,6 +83,21 @@ export function protocolInfo({ packageVersion = null } = {}) {
         informationGainV2: true,
         strategyOscillationDetection: true,
       },
+      structuralQuality: {
+        version: 1,
+        supported: true,
+        schemaVersion: 1,
+        modes: ["off", "observe", "gate"],
+        builtInProviders: ["sentrux"],
+        commands: ["quality-baseline", "quality-verify", "quality-status"],
+        resource: "task/structural-quality",
+        providerNeutral: true,
+        defaultProvider: "sentrux",
+        transport: "mcp-stdio",
+        rootCauses: ["modularity", "acyclicity", "depth", "equality", "redundancy"],
+        baselineImmutableAfterExecution: true,
+        optimizationMaxExtraEvaluations: 2,
+      },
       durableActions: {
         version: 1,
         supported: true,

package/src/core/runtime-context.js

@@ -3,6 +3,7 @@ import {
   isVerificationExecutionAdapter,
   normalizeVerificationExecutionPolicy,
 } from "./verification-execution.js";
+import { STRUCTURAL_QUALITY_PROVIDER_ID_PATTERN } from "./structural-quality/constants.js";
 
 export const AUTHORITY_TRUST_MODES = Object.freeze(["NONE", "HOST_ATTESTED"]);
 
@@ -105,5 +106,31 @@ export function createForgeLoopContext(options = {}) {
     }
     context.usageProvider = options.usageProvider;
   }
+  if (options?.structuralQualityProviders !== undefined) {
+    const configured = options.structuralQualityProviders instanceof Map
+      ? Object.fromEntries(options.structuralQualityProviders.entries())
+      : options.structuralQualityProviders;
+    if (!configured || typeof configured !== "object" || Array.isArray(configured)) {
+      const error = new Error("structuralQualityProviders must be an object or Map");
+      error.code = "E_STRUCTURAL_QUALITY_PROVIDER_INVALID";
+      throw error;
+    }
+    const providers = {};
+    for (const [id, provider] of Object.entries(configured)) {
+      if (!STRUCTURAL_QUALITY_PROVIDER_ID_PATTERN.test(id) || id === "sentrux") {
+        const error = new Error(`Invalid or reserved structural-quality provider ID: ${id}`);
+        error.code = "E_STRUCTURAL_QUALITY_PROVIDER_INVALID";
+        throw error;
+      }
+      if (typeof provider !== "function"
+        && (!provider || typeof provider !== "object" || Array.isArray(provider))) {
+        const error = new Error(`Structural-quality provider ${id} must be an object or factory`);
+        error.code = "E_STRUCTURAL_QUALITY_PROVIDER_INVALID";
+        throw error;
+      }
+      providers[id] = provider;
+    }
+    context.structuralQualityProviders = Object.freeze(providers);
+  }
   return Object.freeze(context);
 }

package/src/core/schema-validation.js

@@ -54,6 +54,7 @@ export const SHIPPED_SCHEMA_NAMES = Object.freeze([
   "execution-profile-benchmark-scenario",
   "execution-profile-benchmark-run",
   "execution-profile-benchmark-aggregate",
+  "structural-quality",
 ]);
 
 export class SchemaValidationError extends Error {

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