@fairfox/polly 0.83.0 → 0.85.0

package/dist/tools/verify/src/cli.js

@@ -258,12 +258,35 @@ __export(exports_model_coverage, {
 function norm(field) {
   return field.replace(/_/g, ".");
 }
-function computeModelCoverage(stateFields, handlers) {
+function foldOffSurface(offSurface, rawByKey) {
+  const offSurfaceByField = new Map;
+  const offSurfaceMutations = [];
+  for (const m of offSurface) {
+    const key = norm(m.field);
+    const raw = rawByKey.get(key);
+    if (raw === undefined)
+      continue;
+    offSurfaceMutations.push({
+      field: raw,
+      signalVariable: m.signalVariable,
+      function: m.functionName,
+      file: m.filePath,
+      line: m.line,
+      declared: true
+    });
+    const list = offSurfaceByField.get(key) ?? [];
+    list.push({ function: m.functionName, file: m.filePath, line: m.line });
+    offSurfaceByField.set(key, list);
+  }
+  return { offSurfaceByField, offSurfaceMutations };
+}
+function computeModelCoverage(stateFields, handlers, offSurface = []) {
   const writersByField = new Map;
   for (const field of stateFields) {
     writersByField.set(norm(field), new Set);
   }
   const declaredOrder = stateFields.map((f) => ({ raw: f, key: norm(f) }));
+  const rawByKey = new Map(declaredOrder.map((d) => [d.key, d.raw]));
   for (const handler of handlers) {
     for (const assignment of handler.assignments) {
       const key = norm(assignment.field);
@@ -272,10 +295,15 @@ function computeModelCoverage(stateFields, handlers) {
         writers.add(handler.messageType);
     }
   }
-  const fieldCoverage = declaredOrder.map(({ raw, key }) => ({
-    field: raw,
-    writers: Array.from(writersByField.get(key) ?? []).sort()
-  }));
+  const { offSurfaceByField, offSurfaceMutations } = foldOffSurface(offSurface, rawByKey);
+  const fieldCoverage = declaredOrder.map(({ raw, key }) => {
+    const offSurfaceWriters = offSurfaceByField.get(key);
+    return {
+      field: raw,
+      writers: Array.from(writersByField.get(key) ?? []).sort(),
+      ...offSurfaceWriters && offSurfaceWriters.length > 0 ? { offSurfaceWriters } : {}
+    };
+  });
   const unwrittenFields = fieldCoverage.filter((f) => f.writers.length === 0).map((f) => f.field);
   const declaredKeys = new Set(declaredOrder.map((d) => d.key));
   const unconstrainedMutators = [];
@@ -291,18 +319,24 @@ function computeModelCoverage(stateFields, handlers) {
       });
     }
   }
+  const hasDeclaredOffSurface = offSurfaceMutations.some((m) => m.declared);
   return {
     fieldCoverage,
     unwrittenFields,
     unconstrainedMutators,
-    hasStrictViolation: unwrittenFields.length > 0
+    offSurfaceMutations,
+    hasStrictViolation: unwrittenFields.length > 0 || hasDeclaredOffSurface
   };
 }
 function strictCoverageReasons(report, meshFindingCount) {
   const reasons = [];
-  if (report.hasStrictViolation) {
+  if (report.unwrittenFields.length > 0) {
     reasons.push(`${report.unwrittenFields.length} declared state field(s) written by no modelled handler`);
   }
+  const declaredOffSurface = (report.offSurfaceMutations ?? []).filter((m) => m.declared);
+  if (declaredOffSurface.length > 0) {
+    reasons.push(`${declaredOffSurface.length} declared state field write(s) outside any modelled transition (polly#163)`);
+  }
   if (meshFindingCount > 0) {
     reasons.push(`${meshFindingCount} unverified $meshState/$peerState predicate(s)`);
   }
@@ -3356,18 +3390,45 @@ var init_witness = __esm(() => {
 // tools/verify/src/codegen/witness.ts
 var exports_witness2 = {};
 __export(exports_witness2, {
+  witnessVerdict: () => witnessVerdict,
+  witnessSpecLocation: () => witnessSpecLocation,
+  witnessPolarity: () => witnessPolarity,
   routeWitness: () => routeWitness,
+  parseModuleName: () => parseModuleName,
   buildWitnessModule: () => buildWitnessModule,
+  buildWitnessInvariantBare: () => buildWitnessInvariantBare,
   buildWitnessInvariant: () => buildWitnessInvariant,
   buildWitnessCfg: () => buildWitnessCfg,
   bddPredicateToTLA: () => bddPredicateToTLA,
+  bareFieldRenderer: () => bareFieldRenderer,
   WitnessTranslationError: () => WitnessTranslationError,
   WITNESS_INVARIANT: () => WITNESS_INVARIANT
 });
-function flattenField(path3) {
-  return path3.split(".").join("_");
+import * as path3 from "node:path";
+function witnessPolarity(tags) {
+  return tags.includes("forbidden") ? "forbidden" : "positive";
+}
+function witnessVerdict(polarity, reachable) {
+  if (polarity === "forbidden") {
+    return reachable ? {
+      status: "violated",
+      ok: false,
+      message: "the forbidden state is REACHABLE — a defect; the counterexample is the path to it"
+    } : { status: "excluded", ok: true, message: "the model proves this state unreachable" };
+  }
+  return reachable ? { status: "reachable", ok: true, message: "the model reaches this outcome" } : {
+    status: "unreachable",
+    ok: false,
+    message: "the model proves this outcome impossible (the scenario lies)"
+  };
+}
+function flattenField(path4) {
+  return path4.split(".").join("_");
 }
-function translateOperand(raw) {
+function bareFieldRenderer(fields = {}) {
+  return (fieldPath) => fields[fieldPath] ?? flattenField(fieldPath);
+}
+function translateOperand(raw, render) {
   const op = raw.trim();
   if (op === "true")
     return "TRUE";
@@ -3383,11 +3444,11 @@ function translateOperand(raw) {
     throw new WitnessTranslationError(`unsupported operand "${raw}" in witness predicate`);
   }
   if (op.endsWith(".length")) {
-    return `Len(contextStates[ctx].${flattenField(op.slice(0, -".length".length))})`;
+    return `Len(${render(op.slice(0, -".length".length))})`;
   }
-  return `contextStates[ctx].${flattenField(op)}`;
+  return render(op);
 }
-function translateConjunct(conjunct) {
+function translateConjunct(conjunct, render) {
   const text = conjunct.trim();
   for (const [js, tla] of COMPARATORS) {
     const at = text.indexOf(js);
@@ -3395,31 +3456,59 @@ function translateConjunct(conjunct) {
       continue;
     const lhs = text.slice(0, at);
     const rhs = text.slice(at + js.length);
-    return `${translateOperand(lhs)} ${tla} ${translateOperand(rhs)}`;
+    return `${translateOperand(lhs, render)} ${tla} ${translateOperand(rhs, render)}`;
   }
   throw new WitnessTranslationError(`no comparison operator in witness conjunct "${conjunct}"`);
 }
-function bddPredicateToTLA(predicate) {
+function bddPredicateToTLA(predicate, render = contextFieldRenderer) {
   const conjuncts = predicate.split("&&").map((c) => c.trim()).filter(Boolean);
   if (conjuncts.length === 0) {
     throw new WitnessTranslationError("empty witness predicate");
   }
-  return conjuncts.map(translateConjunct).join(" /\\ ");
+  return conjuncts.map((c) => translateConjunct(c, render)).join(" /\\ ");
 }
 function buildWitnessInvariant(tlaPredicate) {
   return `${WITNESS_INVARIANT} == ~(\\E ctx \\in Contexts : ${tlaPredicate})`;
 }
-function buildWitnessModule(moduleName, subsystemModule, tlaPredicate) {
+function buildWitnessInvariantBare(tlaPredicate) {
+  return `${WITNESS_INVARIANT} == ~(${tlaPredicate})`;
+}
+function buildWitnessModule(moduleName, baseModule, tlaPredicate, options = {}) {
+  const invariant = options.bare ? buildWitnessInvariantBare(tlaPredicate) : buildWitnessInvariant(tlaPredicate);
   return [
     `---- MODULE ${moduleName} ----`,
-    `EXTENDS ${subsystemModule}`,
+    `EXTENDS ${baseModule}`,
     "",
-    buildWitnessInvariant(tlaPredicate),
+    invariant,
     "====",
     ""
   ].join(`
 `);
 }
+function parseModuleName(tlaText) {
+  const m = /^-+\s*MODULE\s+([A-Za-z_]\w*)/m.exec(tlaText);
+  return m?.[1] ?? null;
+}
+function witnessSpecLocation(cwd, subsystem, custom, customModule) {
+  if (custom) {
+    const tlaPath = path3.resolve(cwd, custom.tla);
+    return {
+      dir: path3.dirname(tlaPath),
+      tlaPath,
+      cfgPath: path3.resolve(cwd, custom.cfg),
+      module: customModule,
+      custom: true
+    };
+  }
+  const dir = path3.join(cwd, "specs", "tla", "generated", subsystem);
+  return {
+    dir,
+    tlaPath: path3.join(dir, `UserApp_${subsystem}.tla`),
+    cfgPath: path3.join(dir, `UserApp_${subsystem}.cfg`),
+    module: `UserApp_${subsystem}`,
+    custom: false
+  };
+}
 function sectionBody(cfg, header) {
   const body = [];
   let inSection = false;
@@ -3448,11 +3537,22 @@ function headerLine(cfg, header) {
   return null;
 }
 function buildWitnessCfg(baseCfg) {
-  const spec = headerLine(baseCfg, "SPECIFICATION") ?? "SPECIFICATION UserSpec";
+  const spec = headerLine(baseCfg, "SPECIFICATION");
+  const init = headerLine(baseCfg, "INIT");
+  const next = headerLine(baseCfg, "NEXT");
+  const behaviour = spec ? [spec] : init && next ? [init, next] : ["SPECIFICATION UserSpec"];
   const constants = sectionBody(baseCfg, "CONSTANTS");
   const constraint = sectionBody(baseCfg, "CONSTRAINT");
   const symmetry = sectionBody(baseCfg, "SYMMETRY");
-  const out = [spec, "", "CONSTANTS", ...constants, "", "INVARIANTS", `  ${WITNESS_INVARIANT}`];
+  const out = [
+    ...behaviour,
+    "",
+    "CONSTANTS",
+    ...constants,
+    "",
+    "INVARIANTS",
+    `  ${WITNESS_INVARIANT}`
+  ];
   if (constraint.length > 0)
     out.push("", "CONSTRAINT", ...constraint);
   if (symmetry.length > 0)
@@ -3471,7 +3571,7 @@ function routeWitness(fields, subsystems) {
   const only = owners.length === 1 ? owners[0] : undefined;
   return only ? only[0] : null;
 }
-var WITNESS_INVARIANT = "WitnessReachable", WitnessTranslationError, COMPARATORS;
+var WITNESS_INVARIANT = "WitnessReachable", WitnessTranslationError, COMPARATORS, contextFieldRenderer = (fieldPath) => `contextStates[ctx].${flattenField(fieldPath)}`;
 var init_witness2 = __esm(() => {
   WitnessTranslationError = class WitnessTranslationError extends Error {
   };
@@ -3494,11 +3594,11 @@ __export(exports_docker, {
 });
 import { spawn } from "node:child_process";
 import * as fs3 from "node:fs";
-import * as path3 from "node:path";
+import * as path4 from "node:path";
 
 class DockerRunner {
   IMAGE_NAME = "polly-tla:latest";
-  DOCKERFILE_PATH = path3.join(__dirname, "../../Dockerfile");
+  DOCKERFILE_PATH = path4.join(__dirname, "../../Dockerfile");
   async isDockerAvailable() {
     try {
       const result = await this.runCommand("docker", ["info"], {
@@ -3526,7 +3626,7 @@ class DockerRunner {
     }
   }
   async buildImage(onProgress) {
-    const dockerfileDir = path3.dirname(this.DOCKERFILE_PATH);
+    const dockerfileDir = path4.dirname(this.DOCKERFILE_PATH);
     await this.runCommandStreaming("docker", ["build", "-f", this.DOCKERFILE_PATH, "-t", this.IMAGE_NAME, dockerfileDir], onProgress, 300000);
   }
   async pullImage(onProgress) {
@@ -3536,13 +3636,13 @@ class DockerRunner {
     if (!fs3.existsSync(specPath)) {
       throw new Error(`Spec file not found: ${specPath}`);
     }
-    const specDir = path3.dirname(specPath);
-    const specName = path3.basename(specPath, ".tla");
-    const cfgPath = path3.join(specDir, `${specName}.cfg`);
+    const specDir = path4.dirname(specPath);
+    const specName = path4.basename(specPath, ".tla");
+    const cfgPath = path4.join(specDir, `${specName}.cfg`);
     if (!fs3.existsSync(cfgPath)) {
       throw new Error(`Config file not found: ${cfgPath}`);
     }
-    const statesDir = path3.join(specDir, "states");
+    const statesDir = path4.join(specDir, "states");
     if (fs3.existsSync(statesDir)) {
       fs3.rmSync(statesDir, { recursive: true, force: true });
     }
@@ -3635,7 +3735,7 @@ class DockerRunner {
     return "Unknown error occurred during model checking";
   }
   runCommand(command, args, options) {
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const proc = spawn(command, args);
       let stdout = "";
       let stderr = "";
@@ -3653,7 +3753,7 @@ class DockerRunner {
       proc.on("close", (exitCode) => {
         if (timeout)
           clearTimeout(timeout);
-        resolve2({
+        resolve3({
           exitCode: exitCode || 0,
           stdout,
           stderr
@@ -3667,7 +3767,7 @@ class DockerRunner {
     });
   }
   runCommandStreaming(command, args, onOutput, timeout) {
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const proc = spawn(command, args);
       const timeoutHandle = timeout && timeout > 0 ? setTimeout(() => {
         proc.kill();
@@ -3699,7 +3799,7 @@ class DockerRunner {
         if (timeoutHandle)
           clearTimeout(timeoutHandle);
         if (exitCode === 0) {
-          resolve2();
+          resolve3();
         } else {
           reject(new Error(`Command failed with exit code ${exitCode}`));
         }
@@ -3718,7 +3818,7 @@ var init_docker = () => {};
 // tools/verify/src/cli.ts
 init_expression_validator();
 import * as fs4 from "node:fs";
-import * as path4 from "node:path";
+import * as path5 from "node:path";
 
 // tools/verify/src/analysis/mesh-signal-warnings.ts
 function computeMeshOrPeerSignalFindings(analysis, declaredMeshDocs) {
@@ -5445,6 +5545,7 @@ class HandlerExtractor {
   warnings;
   currentFunctionParams = [];
   contextOverrides;
+  onSurfaceSpans = [];
   constructor(tsConfigPath, contextOverrides) {
     this.project = new Project({
       tsConfigFilePath: tsConfigPath
@@ -5504,6 +5605,7 @@ class HandlerExtractor {
     const meshOrPeerSignals = [];
     const resources = [];
     this.warnings = [];
+    this.onSurfaceSpans = [];
     const allSourceFiles = this.project.getSourceFiles();
     const entryPoints = allSourceFiles.filter((f) => this.isWithinPackage(f.getFilePath()));
     this.debugLogSourceFiles(allSourceFiles, entryPoints);
@@ -5538,6 +5640,30 @@ class HandlerExtractor {
         continue;
       meshOrPeerSignals.push(...this.extractMeshOrPeerSignalsFromFile(sourceFile));
     }
+    const stateSignalNames = new Set;
+    for (const filePath of this.analyzedFiles) {
+      const sourceFile = this.project.getSourceFile(filePath);
+      if (!sourceFile)
+        continue;
+      for (const name of this.extractStateSignalVariableNames(sourceFile)) {
+        stateSignalNames.add(name);
+      }
+    }
+    for (const v of verifiedStates)
+      stateSignalNames.add(v.variableName);
+    for (const m of meshOrPeerSignals)
+      stateSignalNames.add(m.variableName);
+    const offSurfaceMutations = [];
+    if (stateSignalNames.size > 0) {
+      for (const filePath of this.analyzedFiles) {
+        if (!this.isOffSurfaceScannable(filePath))
+          continue;
+        const sourceFile = this.project.getSourceFile(filePath);
+        if (!sourceFile)
+          continue;
+        offSurfaceMutations.push(...this.findOffSurfaceMutations(sourceFile, stateSignalNames));
+      }
+    }
     this.debugLogExtractionResults(handlers.length, invalidMessageTypes.size);
     this.debugLogAnalysisStats(allSourceFiles.length, entryPoints.length);
     return {
@@ -5548,6 +5674,7 @@ class HandlerExtractor {
       verifiedStates,
       meshOrPeerSignals,
       resources,
+      offSurfaceMutations,
       warnings: this.warnings
     };
   }
@@ -5958,6 +6085,7 @@ class HandlerExtractor {
     return false;
   }
   extractAssignments(funcNode, assignments) {
+    this.recordOnSurfaceSpan(funcNode);
     funcNode.forEachDescendant((node) => {
       if (Node2.isBinaryExpression(node)) {
         this.extractBinaryExpressionAssignment(node, assignments);
@@ -7544,6 +7672,7 @@ class HandlerExtractor {
   }
   findStateMutationsInFunction(func, stateVarNames) {
     const mutations = [];
+    this.recordOnSurfaceSpan(func);
     func.forEachDescendant((node) => {
       if (!Node2.isBinaryExpression(node))
         return;
@@ -7573,6 +7702,140 @@ class HandlerExtractor {
     });
     return mutations;
   }
+  isOffSurfaceScannable(filePath) {
+    return !/(?:\.(?:test|spec|stories)\.[cm]?[jt]sx?$)|(?:\/(?:__tests__|tests|test|features|e2e|stories|__mocks__)\/)/i.test(filePath);
+  }
+  static STATE_SIGNAL_FACTORIES = new Set([
+    "$state",
+    "$sharedState",
+    "$syncedState",
+    "$persistedState",
+    "$meshState",
+    "$peerState"
+  ]);
+  extractStateSignalVariableNames(sourceFile) {
+    const names = [];
+    sourceFile.forEachDescendant((node) => {
+      if (!Node2.isCallExpression(node))
+        return;
+      const expr = node.getExpression();
+      if (!Node2.isIdentifier(expr))
+        return;
+      if (!HandlerExtractor.STATE_SIGNAL_FACTORIES.has(expr.getText()))
+        return;
+      const varName = this.getVariableNameFromParent(node);
+      if (varName)
+        names.push(varName);
+    });
+    return names;
+  }
+  recordOnSurfaceSpan(node) {
+    this.onSurfaceSpans.push({
+      file: node.getSourceFile().getFilePath(),
+      start: node.getStart(),
+      end: node.getEnd()
+    });
+  }
+  isWithinOnSurfaceSpan(file, pos) {
+    for (const span of this.onSurfaceSpans) {
+      if (span.file === file && pos >= span.start && pos <= span.end)
+        return true;
+    }
+    return false;
+  }
+  findOffSurfaceMutations(sourceFile, stateVarNames) {
+    const out = [];
+    const filePath = sourceFile.getFilePath();
+    sourceFile.forEachDescendant((node) => {
+      if (Node2.isBinaryExpression(node)) {
+        out.push(...this.offSurfaceWritesAt(node, stateVarNames, filePath));
+      }
+    });
+    return out;
+  }
+  offSurfaceWritesAt(node, stateVarNames, filePath) {
+    if (node.getOperatorToken().getText() !== "=")
+      return [];
+    const left = node.getLeft();
+    if (!Node2.isPropertyAccessExpression(left))
+      return [];
+    const match = this.matchVerifiedStateWrite(this.getPropertyPath(left), stateVarNames);
+    if (!match)
+      return [];
+    if (this.isWithinOnSurfaceSpan(filePath, left.getStart()))
+      return [];
+    const base = {
+      signalVariable: match.signal,
+      functionName: this.enclosingFunctionName(node),
+      filePath,
+      line: node.getStartLineNumber()
+    };
+    if (match.field !== undefined) {
+      return [{ field: `${match.signal}_${match.field}`, ...base }];
+    }
+    const fields = this.objectLiteralFieldNames(node.getRight());
+    if (fields.length === 0)
+      return [{ field: match.signal, ...base }];
+    return fields.map((f) => ({ field: `${match.signal}_${f}`, ...base }));
+  }
+  matchVerifiedStateWrite(path2, stateVarNames) {
+    for (const varName of stateVarNames) {
+      if (path2 === `${varName}.value`)
+        return { signal: varName };
+      const prefix = `${varName}.value.`;
+      if (path2.startsWith(prefix))
+        return { signal: varName, field: path2.substring(prefix.length) };
+    }
+    return null;
+  }
+  objectLiteralFieldNames(right) {
+    if (!Node2.isObjectLiteralExpression(right))
+      return [];
+    const names = [];
+    for (const prop of right.getProperties()) {
+      if (Node2.isPropertyAssignment(prop) || Node2.isShorthandPropertyAssignment(prop)) {
+        names.push(prop.getName());
+      }
+    }
+    return names;
+  }
+  enclosingFunctionName(node) {
+    let current = node.getParent();
+    while (current) {
+      const name = this.namedScope(current);
+      if (name !== null)
+        return name;
+      current = current.getParent();
+    }
+    return "<module>";
+  }
+  namedScope(node) {
+    if (Node2.isFunctionDeclaration(node)) {
+      return node.getName() ?? "<anonymous function>";
+    }
+    if (Node2.isMethodDeclaration(node)) {
+      const clsName = node.getFirstAncestorByKind(SyntaxKind.ClassDeclaration)?.getName();
+      const methodName = node.getName();
+      return clsName ? `${clsName}.${methodName}` : methodName;
+    }
+    if (Node2.isGetAccessorDeclaration(node) || Node2.isSetAccessorDeclaration(node)) {
+      return node.getName();
+    }
+    if (Node2.isArrowFunction(node) || Node2.isFunctionExpression(node)) {
+      return this.boundFunctionName(node) ?? null;
+    }
+    return null;
+  }
+  boundFunctionName(fn) {
+    const parent = fn.getParent();
+    if (!parent)
+      return;
+    if (Node2.isVariableDeclaration(parent))
+      return parent.getName();
+    if (Node2.isPropertyAssignment(parent))
+      return parent.getName();
+    return;
+  }
   functionNameToMessageType(funcName) {
     let name = funcName.replace(/^handle/, "").replace(/^on/, "").replace(/^set/, "Set").replace(/^update/, "Update").replace(/^do/, "");
     if (name.length > 0) {
@@ -7737,7 +8000,8 @@ class TypeExtractor {
       globalStateConstraints: handlerAnalysis.globalStateConstraints,
       verifiedStates: handlerAnalysis.verifiedStates,
       meshOrPeerSignals: handlerAnalysis.meshOrPeerSignals,
-      resources: handlerAnalysis.resources
+      resources: handlerAnalysis.resources,
+      offSurfaceMutations: handlerAnalysis.offSurfaceMutations
     };
   }
   extractHandlerAnalysis() {
@@ -8208,7 +8472,7 @@ async function setupCommand() {
     displayAnalysisResults(analysis);
     displayAnalysisSummary(analysis);
     const configContent = generateConfig(analysis);
-    const configPath = path4.join(process.cwd(), "specs", "verification.config.ts");
+    const configPath = path5.join(process.cwd(), "specs", "verification.config.ts");
     writeConfigFile(configPath, configContent);
     displaySetupSuccess(configPath);
   } catch (_error) {
@@ -8256,7 +8520,7 @@ function getFieldStatus(confidence) {
   return color("⚠ Manual config", COLORS.red);
 }
 function writeConfigFile(configPath, configContent) {
-  const configDir = path4.dirname(configPath);
+  const configDir = path5.dirname(configPath);
   if (!fs4.existsSync(configDir)) {
     fs4.mkdirSync(configDir, { recursive: true });
   }
@@ -8279,7 +8543,7 @@ function displaySetupSuccess(configPath) {
   console.log();
 }
 async function validateCommand() {
-  const configPath = path4.join(process.cwd(), "specs", "verification.config.ts");
+  const configPath = path5.join(process.cwd(), "specs", "verification.config.ts");
   console.log(color(`
 \uD83D\uDD0D Validating configuration...
 `, COLORS.blue));
@@ -8300,7 +8564,7 @@ async function validateCommand() {
   process.exit(1);
 }
 async function estimateCommand() {
-  const configPath = path4.join(process.cwd(), "specs", "verification.config.ts");
+  const configPath = path5.join(process.cwd(), "specs", "verification.config.ts");
   console.log(color(`
 \uD83D\uDCCA Estimating state space...
 `, COLORS.blue));
@@ -8443,8 +8707,8 @@ function isWitnessMode() {
   return process.argv.includes("--witness");
 }
 function displayModelCoverage(report) {
-  const { unwrittenFields, unconstrainedMutators, fieldCoverage } = report;
-  if (unwrittenFields.length === 0 && unconstrainedMutators.length === 0) {
+  const { unwrittenFields, unconstrainedMutators, fieldCoverage, offSurfaceMutations } = report;
+  if (unwrittenFields.length === 0 && unconstrainedMutators.length === 0 && offSurfaceMutations.length === 0) {
     console.log(color(`✓ Model coverage: all ${fieldCoverage.length} declared field(s) written by a modelled handler`, COLORS.green));
     console.log();
     return;
@@ -8468,11 +8732,24 @@ function displayModelCoverage(report) {
     console.log(color("   The checker explores these transitions but asserts nothing about their effect.", COLORS.gray));
     console.log();
   }
+  if (offSurfaceMutations.length > 0) {
+    console.log(color(`
+⚠️  ${offSurfaceMutations.length} declared state field write(s) outside any modelled transition (polly#163):`, COLORS.yellow));
+    for (const m of offSurfaceMutations) {
+      console.log(color(`   • ${m.field} mutated in ${m.function}() — ${m.file}:${m.line}`, COLORS.yellow));
+    }
+    console.log(color("   A non-dispatched path (a method, a non-exported function, a closure) writes", COLORS.gray));
+    console.log(color("   verified state the checker never explores — the register() shape (#160). Even", COLORS.gray));
+    console.log(color("   when a handler also writes the field, model coverage cannot see this writer.", COLORS.gray));
+    console.log(color("   Route the change through a dispatched handler, or drop the field from the", COLORS.gray));
+    console.log(color("   verified surface. See tools/verify/OFF-SURFACE-MUTATORS.md.", COLORS.gray));
+    console.log();
+  }
 }
 async function runModelCoverage(typedConfig, typedAnalysis, meshFindingCount) {
   const { computeModelCoverage: computeModelCoverage2, strictCoverageReasons: strictCoverageReasons2 } = await Promise.resolve().then(() => exports_model_coverage);
   const stateFields = Object.keys(typedConfig.state ?? {});
-  const coverage = computeModelCoverage2(stateFields, typedAnalysis.handlers);
+  const coverage = computeModelCoverage2(stateFields, typedAnalysis.handlers, typedAnalysis.offSurfaceMutations ?? []);
   displayModelCoverage(coverage);
   if (!isStrictMode())
     return;
@@ -8494,7 +8771,7 @@ async function runModelCoverage(typedConfig, typedAnalysis, meshFindingCount) {
   process.exit(1);
 }
 async function verifyCommand() {
-  const configPath = path4.join(process.cwd(), "specs", "verification.config.ts");
+  const configPath = path5.join(process.cwd(), "specs", "verification.config.ts");
   console.log(color(`
 \uD83D\uDD0D Running verification...
 `, COLORS.blue));
@@ -8560,6 +8837,12 @@ function getMaxDepth(config) {
   }
   return;
 }
+function getCustomTLAPaths(config) {
+  if ("messages" in config && config.customTLAPaths) {
+    return config.customTLAPaths;
+  }
+  return {};
+}
 async function runCoupledFieldsLint(config, analysis) {
   const groups = config.coupledFields ?? [];
   if (groups.length === 0)
@@ -8707,18 +8990,23 @@ async function runSubsystemVerification(config, analysis) {
   const maxDepth = getMaxDepth(config);
   const { generateSubsystemTLA: generateSubsystemTLA2 } = await Promise.resolve().then(() => (init_tla(), exports_tla));
   const results = [];
+  const customTLAPaths = getCustomTLAPaths(config);
   for (const name of subsystemNames) {
     const sub = subsystems[name];
     const startTime = Date.now();
+    if (customTLAPaths[name]) {
+      console.log(color(`⏭  ${name}: hand-written spec (customTLAPaths) — witnessed, not generated`, COLORS.gray));
+      continue;
+    }
     console.log(color(`⚙️  Verifying subsystem: ${name}...`, COLORS.blue));
     const { spec, cfg } = await generateSubsystemTLA2(name, sub, config, analysis);
     const ensuresCount = (spec.match(/^EnsuresAfter_\w+ ==/gm) ?? []).length;
-    const specDir = path4.join(process.cwd(), "specs", "tla", "generated", name);
+    const specDir = path5.join(process.cwd(), "specs", "tla", "generated", name);
     if (!fs4.existsSync(specDir)) {
       fs4.mkdirSync(specDir, { recursive: true });
     }
-    const specPath = path4.join(specDir, `UserApp_${name}.tla`);
-    const cfgPath = path4.join(specDir, `UserApp_${name}.cfg`);
+    const specPath = path5.join(specDir, `UserApp_${name}.tla`);
+    const cfgPath = path5.join(specDir, `UserApp_${name}.cfg`);
     fs4.writeFileSync(specPath, spec);
     fs4.writeFileSync(cfgPath, cfg);
     findAndCopyBaseSpec(specDir);
@@ -8747,7 +9035,7 @@ async function runSubsystemVerification(config, analysis) {
       } else if (result.error) {
         console.log(color(`     Error: ${result.error}`, COLORS.red));
       }
-      fs4.writeFileSync(path4.join(specDir, "tlc-output.log"), result.output);
+      fs4.writeFileSync(path5.join(specDir, "tlc-output.log"), result.output);
     }
   }
   console.log();
@@ -8779,13 +9067,19 @@ async function runWitnessVerification(config) {
   }
   const { extractWitnesses: extractWitnesses2 } = await Promise.resolve().then(() => (init_witness(), exports_witness));
   const {
+    bareFieldRenderer: bareFieldRenderer2,
     bddPredicateToTLA: bddPredicateToTLA2,
     buildWitnessCfg: buildWitnessCfg2,
     buildWitnessModule: buildWitnessModule2,
+    parseModuleName: parseModuleName2,
     routeWitness: routeWitness2,
+    witnessPolarity: witnessPolarity2,
+    witnessSpecLocation: witnessSpecLocation2,
+    witnessVerdict: witnessVerdict2,
     WITNESS_INVARIANT: WITNESS_INVARIANT2
   } = await Promise.resolve().then(() => (init_witness2(), exports_witness2));
   const subsystems = config.subsystems;
+  const customTLAPaths = getCustomTLAPaths(config);
   const witnesses = await extractWitnesses2(featureFiles, stepFiles);
   const docker = await setupDocker();
   const timeoutSeconds = getTimeout(config);
@@ -8795,8 +9089,14 @@ async function runWitnessVerification(config) {
   let idx = 0;
   for (const w of witnesses) {
     const id = `${w.feature} › ${w.scenario}`;
+    const polarity = witnessPolarity2(w.tags);
     if (!w.predicate) {
-      results.push({ id, status: "skipped", note: "no state-observable Then to witness" });
+      results.push({
+        id,
+        status: "skipped",
+        ok: true,
+        note: "no state-observable Then to witness"
+      });
       continue;
     }
     const subsystem = routeWitness2(w.fields, subsystems);
@@ -8804,89 +9104,128 @@ async function runWitnessVerification(config) {
       results.push({
         id,
         status: "skipped",
+        ok: true,
         note: `fields [${w.fields.join(", ")}] not owned by a single subsystem`
       });
       continue;
     }
-    const specDir = path4.join(cwd, "specs", "tla", "generated", subsystem);
-    const subsystemCfg = path4.join(specDir, `UserApp_${subsystem}.cfg`);
-    if (!fs4.existsSync(path4.join(specDir, `UserApp_${subsystem}.tla`)) || !fs4.existsSync(subsystemCfg)) {
-      results.push({
-        id,
-        status: "error",
-        subsystem,
-        note: `subsystem spec missing: ${subsystem}`
-      });
-      continue;
+    const custom = customTLAPaths[subsystem];
+    let location;
+    if (custom) {
+      const tlaAbs = path5.resolve(cwd, custom.tla);
+      const cfgAbs = path5.resolve(cwd, custom.cfg);
+      if (!fs4.existsSync(tlaAbs) || !fs4.existsSync(cfgAbs)) {
+        results.push({
+          id,
+          status: "error",
+          ok: false,
+          subsystem,
+          note: `custom spec missing: ${custom.tla} / ${custom.cfg}`
+        });
+        continue;
+      }
+      const module = custom.module ?? parseModuleName2(fs4.readFileSync(tlaAbs, "utf8"));
+      if (!module) {
+        results.push({
+          id,
+          status: "error",
+          ok: false,
+          subsystem,
+          note: `cannot read MODULE name from ${custom.tla}; set customTLAPaths.${subsystem}.module`
+        });
+        continue;
+      }
+      location = witnessSpecLocation2(cwd, subsystem, custom, module);
+    } else {
+      location = witnessSpecLocation2(cwd, subsystem, undefined, "");
+      if (!fs4.existsSync(location.tlaPath) || !fs4.existsSync(location.cfgPath)) {
+        results.push({
+          id,
+          status: "error",
+          ok: false,
+          subsystem,
+          note: `subsystem spec missing: ${subsystem}`
+        });
+        continue;
+      }
     }
     let tlaPredicate;
     try {
-      tlaPredicate = bddPredicateToTLA2(w.predicate);
+      tlaPredicate = location.custom ? bddPredicateToTLA2(w.predicate, bareFieldRenderer2(custom?.fields)) : bddPredicateToTLA2(w.predicate);
     } catch (err) {
       results.push({
         id,
         status: "error",
+        ok: false,
         subsystem,
         note: err instanceof Error ? err.message : String(err)
       });
       continue;
     }
     const moduleName = `Witness_${subsystem}_${idx++}`;
-    const witnessTla = path4.join(specDir, `${moduleName}.tla`);
-    fs4.writeFileSync(witnessTla, buildWitnessModule2(moduleName, `UserApp_${subsystem}`, tlaPredicate));
-    fs4.writeFileSync(path4.join(specDir, `${moduleName}.cfg`), buildWitnessCfg2(fs4.readFileSync(subsystemCfg, "utf8")));
-    console.log(color(`⚙️  ${id}`, COLORS.blue));
+    const witnessTla = path5.join(location.dir, `${moduleName}.tla`);
+    fs4.writeFileSync(witnessTla, buildWitnessModule2(moduleName, location.module, tlaPredicate, { bare: location.custom }));
+    fs4.writeFileSync(path5.join(location.dir, `${moduleName}.cfg`), buildWitnessCfg2(fs4.readFileSync(location.cfgPath, "utf8")));
+    const polarityTag = polarity === "forbidden" ? color("  [forbidden — must be unreachable]", COLORS.gray) : "";
+    console.log(color(`⚙️  ${id}`, COLORS.blue) + polarityTag);
     console.log(color(`     ${subsystem} ⊨ ${w.predicate}`, COLORS.gray));
     let tlc;
     try {
       tlc = await docker.runTLC(witnessTla, { workers, timeout });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      results.push({ id, status: "inconclusive", subsystem, predicate: w.predicate, note: msg });
-      console.log(color("     ⚠ inconclusive — TLC did not finish (raise the config timeout)", COLORS.yellow));
-      continue;
-    }
-    if (!tlc.success && tlc.violation?.name === WITNESS_INVARIANT2) {
-      results.push({ id, status: "reachable", subsystem, predicate: w.predicate });
-      console.log(color("     ✓ reachable — the model reaches this outcome", COLORS.green));
-    } else if (tlc.success) {
       results.push({
         id,
-        status: "unreachable",
+        status: "inconclusive",
+        ok: true,
         subsystem,
         predicate: w.predicate,
-        note: `${tlc.stats?.distinctStates ?? 0} distinct states, no path`
+        note: msg
       });
-      console.log(color("     ✗ UNREACHABLE — the model proves this outcome impossible (the scenario lies)", COLORS.red));
-      fs4.writeFileSync(path4.join(specDir, `${moduleName}.tlc-output.log`), tlc.output);
-    } else {
+      console.log(color("     ⚠ inconclusive — TLC did not finish (raise the config timeout)", COLORS.yellow));
+      continue;
+    }
+    const reachable = !tlc.success && tlc.violation?.name === WITNESS_INVARIANT2;
+    if (!tlc.success && !reachable) {
       results.push({
         id,
         status: "error",
+        ok: false,
         subsystem,
         predicate: w.predicate,
         note: tlc.error ?? tlc.violation?.name ?? "TLC error"
       });
       console.log(color(`     ! error — ${tlc.error ?? "see log"}`, COLORS.yellow));
-      fs4.writeFileSync(path4.join(specDir, `${moduleName}.tlc-output.log`), tlc.output);
+      fs4.writeFileSync(path5.join(location.dir, `${moduleName}.tlc-output.log`), tlc.output);
+      continue;
     }
+    const verdict = witnessVerdict2(polarity, reachable);
+    const note = reachable ? undefined : `${tlc.stats?.distinctStates ?? 0} distinct states explored`;
+    results.push({
+      id,
+      status: verdict.status,
+      ok: verdict.ok,
+      subsystem,
+      predicate: w.predicate,
+      note
+    });
+    console.log(color(`     ${verdict.ok ? "✓" : "✗"} ${verdict.status} — ${verdict.message}`, verdict.ok ? COLORS.green : COLORS.red));
+    if (!verdict.ok)
+      fs4.writeFileSync(path5.join(location.dir, `${moduleName}.tlc-output.log`), tlc.output);
   }
   displayWitnessReport(results);
 }
 function displayWitnessReport(results) {
   const count = (s) => results.filter((r) => r.status === s).length;
-  const reachable = count("reachable");
-  const unreachable = count("unreachable");
-  const inconclusive = count("inconclusive");
-  const errors = count("error");
-  const skipped = count("skipped");
   console.log();
   console.log(color(`Witness results:
 `, COLORS.blue));
   for (const r of results) {
     const mark = {
       reachable: color("✓", COLORS.green),
+      excluded: color("✓", COLORS.green),
       unreachable: color("✗", COLORS.red),
+      violated: color("✗", COLORS.red),
       inconclusive: color("⚠", COLORS.yellow),
       error: color("!", COLORS.yellow),
       skipped: color("·", COLORS.gray)
@@ -8894,17 +9233,27 @@ function displayWitnessReport(results) {
     const note = r.note ? color(`  (${r.note})`, COLORS.gray) : "";
     console.log(`  ${mark} ${r.status.padEnd(12)} ${r.id}${note}`);
   }
+  const tally = [
+    "reachable",
+    "excluded",
+    "unreachable",
+    "violated",
+    "inconclusive",
+    "error",
+    "skipped"
+  ].map((s) => `${count(s)} ${s}`).join(", ");
   console.log();
-  console.log(color(`  ${reachable} reachable, ${unreachable} unreachable, ${inconclusive} inconclusive, ${errors} error, ${skipped} skipped`, COLORS.gray));
+  console.log(color(`  ${tally}`, COLORS.gray));
   console.log();
-  if (unreachable > 0 || errors > 0) {
+  const failures = results.filter((r) => !r.ok);
+  if (failures.length > 0) {
     console.log(color("Witness result: ✗ FAIL", COLORS.red));
-    console.log(color("  A scenario the exhaustive model cannot reach describes an impossible outcome.", COLORS.gray));
+    console.log(color("  An outcome a scenario claims is unreachable, or a forbidden state the model can reach.", COLORS.gray));
     console.log();
     process.exit(1);
   }
   console.log(color("Witness result: ✓ PASS", COLORS.green));
-  console.log(color("  Every witnessable scenario's outcome is reachable in the model.", COLORS.gray));
+  console.log(color("  Every claimed outcome is reachable; every forbidden state is proven unreachable.", COLORS.gray));
   console.log();
 }
 function displayEnsuresSummary(results) {
@@ -8954,7 +9303,7 @@ function displayCompositionalReport(results, nonInterferenceValid) {
   console.log();
 }
 async function loadVerificationConfig(configPath) {
-  const resolvedPath = path4.resolve(configPath);
+  const resolvedPath = path5.resolve(configPath);
   const configModule = await import(`file://${resolvedPath}?t=${Date.now()}`);
   return configModule.verificationConfig || configModule.default;
 }
@@ -8976,23 +9325,23 @@ async function generateAndWriteTLASpecs(config, analysis) {
   const { generateTLA: generateTLA2 } = await Promise.resolve().then(() => (init_tla(), exports_tla));
   console.log(color("\uD83D\uDCDD Generating TLA+ specification...", COLORS.blue));
   const { spec, cfg } = await generateTLA2(config, analysis);
-  const specDir = path4.join(process.cwd(), "specs", "tla", "generated");
+  const specDir = path5.join(process.cwd(), "specs", "tla", "generated");
   if (!fs4.existsSync(specDir)) {
     fs4.mkdirSync(specDir, { recursive: true });
   }
-  const specPath = path4.join(specDir, "UserApp.tla");
-  const cfgPath = path4.join(specDir, "UserApp.cfg");
+  const specPath = path5.join(specDir, "UserApp.tla");
+  const cfgPath = path5.join(specDir, "UserApp.cfg");
   fs4.writeFileSync(specPath, spec);
   fs4.writeFileSync(cfgPath, cfg);
   return { specPath, specDir };
 }
 function findAndCopyBaseSpec(specDir) {
   const possiblePaths = [
-    path4.join(process.cwd(), "specs", "tla", "MessageRouter.tla"),
-    path4.join(__dirname, "..", "specs", "tla", "MessageRouter.tla"),
-    path4.join(__dirname, "..", "..", "specs", "tla", "MessageRouter.tla"),
-    path4.join(process.cwd(), "external", "polly", "packages", "verify", "specs", "tla", "MessageRouter.tla"),
-    path4.join(process.cwd(), "node_modules", "@fairfox", "polly-verify", "specs", "tla", "MessageRouter.tla")
+    path5.join(process.cwd(), "specs", "tla", "MessageRouter.tla"),
+    path5.join(__dirname, "..", "specs", "tla", "MessageRouter.tla"),
+    path5.join(__dirname, "..", "..", "specs", "tla", "MessageRouter.tla"),
+    path5.join(process.cwd(), "external", "polly", "packages", "verify", "specs", "tla", "MessageRouter.tla"),
+    path5.join(process.cwd(), "node_modules", "@fairfox", "polly-verify", "specs", "tla", "MessageRouter.tla")
   ];
   let baseSpecPath = null;
   for (const candidatePath of possiblePaths) {
@@ -9002,7 +9351,7 @@ function findAndCopyBaseSpec(specDir) {
     }
   }
   if (baseSpecPath) {
-    const destSpecPath = path4.join(specDir, "MessageRouter.tla");
+    const destSpecPath = path5.join(specDir, "MessageRouter.tla");
     fs4.copyFileSync(baseSpecPath, destSpecPath);
     console.log(color("✓ Copied MessageRouter.tla", COLORS.green));
   } else {
@@ -9015,13 +9364,13 @@ function findAndCopyBaseSpec(specDir) {
 }
 function findMeshSeedSpecDir() {
   const candidates = [
-    path4.join(process.cwd(), "specs", "tla"),
-    path4.join(__dirname, "..", "specs", "tla"),
-    path4.join(__dirname, "..", "..", "specs", "tla"),
-    path4.join(process.cwd(), "node_modules", "@fairfox", "polly-verify", "specs", "tla")
+    path5.join(process.cwd(), "specs", "tla"),
+    path5.join(__dirname, "..", "specs", "tla"),
+    path5.join(__dirname, "..", "..", "specs", "tla"),
+    path5.join(process.cwd(), "node_modules", "@fairfox", "polly-verify", "specs", "tla")
   ];
   for (const dir of candidates) {
-    if (fs4.existsSync(path4.join(dir, "MeshSeed.tla")))
+    if (fs4.existsSync(path5.join(dir, "MeshSeed.tla")))
       return dir;
   }
   return null;
@@ -9035,11 +9384,11 @@ async function runMeshSeedGuard(docker, specDir, config) {
     return;
   }
   const fixDisabled = isSeedFixDisabled();
-  fs4.copyFileSync(path4.join(sourceDir, "MeshSeed.tla"), path4.join(specDir, "MeshSeed.tla"));
-  const baseCfg = fs4.readFileSync(path4.join(sourceDir, "MeshSeed.cfg"), "utf8");
-  fs4.writeFileSync(path4.join(specDir, "MeshSeed.cfg"), meshSeedCfg(baseCfg, { disableFix: fixDisabled }));
+  fs4.copyFileSync(path5.join(sourceDir, "MeshSeed.tla"), path5.join(specDir, "MeshSeed.tla"));
+  const baseCfg = fs4.readFileSync(path5.join(sourceDir, "MeshSeed.cfg"), "utf8");
+  fs4.writeFileSync(path5.join(specDir, "MeshSeed.cfg"), meshSeedCfg(baseCfg, { disableFix: fixDisabled }));
   console.log(color(`⚙️  Running mesh seed-race guard (MeshSeed.tla, SeedDeterministic = ${fixDisabled ? "FALSE" : "TRUE"})...`, COLORS.blue));
-  return docker.runTLC(path4.join(specDir, "MeshSeed.tla"), { workers: 1 });
+  return docker.runTLC(path5.join(specDir, "MeshSeed.tla"), { workers: 1 });
 }
 async function setupDocker() {
   const { DockerRunner: DockerRunner2 } = await Promise.resolve().then(() => (init_docker(), exports_docker));
@@ -9121,8 +9470,8 @@ function displayVerificationResults(result, specDir) {
   }
   console.log();
   console.log(color("Full output saved to:", COLORS.gray));
-  console.log(color(`  ${path4.join(specDir, "tlc-output.log")}`, COLORS.gray));
-  fs4.writeFileSync(path4.join(specDir, "tlc-output.log"), result.output);
+  console.log(color(`  ${path5.join(specDir, "tlc-output.log")}`, COLORS.gray));
+  fs4.writeFileSync(path5.join(specDir, "tlc-output.log"), result.output);
   process.exit(1);
 }
 function showHelp() {
@@ -9185,8 +9534,8 @@ ${color("Learn More:", COLORS.blue)}
 }
 function findTsConfig() {
   const locations = [
-    path4.join(process.cwd(), "tsconfig.json"),
-    path4.join(process.cwd(), "packages", "web-ext", "tsconfig.json")
+    path5.join(process.cwd(), "tsconfig.json"),
+    path5.join(process.cwd(), "packages", "web-ext", "tsconfig.json")
   ];
   for (const loc of locations) {
     if (fs4.existsSync(loc)) {
@@ -9197,9 +9546,9 @@ function findTsConfig() {
 }
 function findStateFile() {
   const locations = [
-    path4.join(process.cwd(), "types", "state.ts"),
-    path4.join(process.cwd(), "src", "types", "state.ts"),
-    path4.join(process.cwd(), "packages", "web-ext", "src", "shared", "state", "app-state.ts")
+    path5.join(process.cwd(), "types", "state.ts"),
+    path5.join(process.cwd(), "src", "types", "state.ts"),
+    path5.join(process.cwd(), "packages", "web-ext", "src", "shared", "state", "app-state.ts")
   ];
   for (const loc of locations) {
     if (fs4.existsSync(loc)) {
@@ -9213,4 +9562,4 @@ main().catch((error) => {
   process.exit(1);
 });
 
-//# debugId=006B6ED4C6E5114F64756E2164756E21
+//# debugId=0E6C5C2B308F1EA464756E2164756E21