@fairfox/polly 0.84.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)`);
   }
@@ -3357,15 +3391,20 @@ var init_witness = __esm(() => {
 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
 });
+import * as path3 from "node:path";
 function witnessPolarity(tags) {
   return tags.includes("forbidden") ? "forbidden" : "positive";
 }
@@ -3383,10 +3422,13 @@ function witnessVerdict(polarity, reachable) {
     message: "the model proves this outcome impossible (the scenario lies)"
   };
 }
-function flattenField(path3) {
-  return path3.split(".").join("_");
+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";
@@ -3402,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);
@@ -3414,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;
@@ -3467,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)
@@ -3490,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 {
   };
@@ -3513,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"], {
@@ -3545,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) {
@@ -3555,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 });
     }
@@ -3654,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 = "";
@@ -3672,7 +3753,7 @@ class DockerRunner {
       proc.on("close", (exitCode) => {
         if (timeout)
           clearTimeout(timeout);
-        resolve2({
+        resolve3({
           exitCode: exitCode || 0,
           stdout,
           stderr
@@ -3686,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();
@@ -3718,7 +3799,7 @@ class DockerRunner {
         if (timeoutHandle)
           clearTimeout(timeoutHandle);
         if (exitCode === 0) {
-          resolve2();
+          resolve3();
         } else {
           reject(new Error(`Command failed with exit code ${exitCode}`));
         }
@@ -3737,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) {
@@ -5464,6 +5545,7 @@ class HandlerExtractor {
   warnings;
   currentFunctionParams = [];
   contextOverrides;
+  onSurfaceSpans = [];
   constructor(tsConfigPath, contextOverrides) {
     this.project = new Project({
       tsConfigFilePath: tsConfigPath
@@ -5523,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);
@@ -5557,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 {
@@ -5567,6 +5674,7 @@ class HandlerExtractor {
       verifiedStates,
       meshOrPeerSignals,
       resources,
+      offSurfaceMutations,
       warnings: this.warnings
     };
   }
@@ -5977,6 +6085,7 @@ class HandlerExtractor {
     return false;
   }
   extractAssignments(funcNode, assignments) {
+    this.recordOnSurfaceSpan(funcNode);
     funcNode.forEachDescendant((node) => {
       if (Node2.isBinaryExpression(node)) {
         this.extractBinaryExpressionAssignment(node, assignments);
@@ -7563,6 +7672,7 @@ class HandlerExtractor {
   }
   findStateMutationsInFunction(func, stateVarNames) {
     const mutations = [];
+    this.recordOnSurfaceSpan(func);
     func.forEachDescendant((node) => {
       if (!Node2.isBinaryExpression(node))
         return;
@@ -7592,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) {
@@ -7756,7 +8000,8 @@ class TypeExtractor {
       globalStateConstraints: handlerAnalysis.globalStateConstraints,
       verifiedStates: handlerAnalysis.verifiedStates,
       meshOrPeerSignals: handlerAnalysis.meshOrPeerSignals,
-      resources: handlerAnalysis.resources
+      resources: handlerAnalysis.resources,
+      offSurfaceMutations: handlerAnalysis.offSurfaceMutations
     };
   }
   extractHandlerAnalysis() {
@@ -8227,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) {
@@ -8275,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 });
   }
@@ -8298,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));
@@ -8319,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));
@@ -8462,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;
@@ -8487,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;
@@ -8513,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));
@@ -8579,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)
@@ -8726,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);
@@ -8766,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();
@@ -8798,15 +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);
@@ -8836,21 +9109,49 @@ async function runWitnessVerification(config) {
       });
       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",
-        ok: false,
-        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,
@@ -8862,9 +9163,9 @@ async function runWitnessVerification(config) {
       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")));
+    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));
@@ -8895,7 +9196,7 @@ async function runWitnessVerification(config) {
         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);
@@ -8910,7 +9211,7 @@ async function runWitnessVerification(config) {
     });
     console.log(color(`     ${verdict.ok ? "✓" : "✗"} ${verdict.status} — ${verdict.message}`, verdict.ok ? COLORS.green : COLORS.red));
     if (!verdict.ok)
-      fs4.writeFileSync(path4.join(specDir, `${moduleName}.tlc-output.log`), tlc.output);
+      fs4.writeFileSync(path5.join(location.dir, `${moduleName}.tlc-output.log`), tlc.output);
   }
   displayWitnessReport(results);
 }
@@ -9002,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;
 }
@@ -9024,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) {
@@ -9050,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 {
@@ -9063,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;
@@ -9083,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));
@@ -9169,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() {
@@ -9233,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)) {
@@ -9245,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)) {
@@ -9261,4 +9562,4 @@ main().catch((error) => {
   process.exit(1);
 });
 
-//# debugId=F9E0214A7A9A110B64756E2164756E21
+//# debugId=0E6C5C2B308F1EA464756E2164756E21