@fairfox/polly 0.89.1 → 0.91.0

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

@@ -245,6 +245,80 @@ var init_expression_validator = __esm(() => {
   WEAK_NEGATION = /([a-zA-Z_][\w.]*(?:\.value\.[\w.]+|\.value\b|))?\s*!==?\s*("[^"]*"|'[^']*'|\d+|true|false|null)/;
 });
 
+// tools/verify/src/codegen/model-constants.ts
+function sanitizeContextName(name) {
+  return name.replace(/[^A-Za-z0-9_]/g, "_");
+}
+function hasDeclaredContexts(config) {
+  const declared = config?.contexts;
+  return Array.isArray(declared) && declared.length > 0;
+}
+function resolveContexts(config) {
+  if (!hasDeclaredContexts(config))
+    return [...DEFAULT_CONTEXTS];
+  return (config?.contexts).map(sanitizeContextName);
+}
+function targetSetCount(contexts) {
+  return 2 ** contexts.length - 1;
+}
+function hasProjectConstant(messages) {
+  return messages.maxWorkers !== undefined || messages.maxRenderers !== undefined || messages.maxContexts !== undefined || messages.maxClients !== undefined;
+}
+function generatedTabValues(messages) {
+  if (messages.tabSymmetry) {
+    const maxTabs = messages.maxTabs ?? 1;
+    return Array.from({ length: maxTabs + 1 }, (_, i) => `Tab${i}`);
+  }
+  if (messages.maxTabs !== undefined && messages.maxTabs !== null) {
+    return Array.from({ length: messages.maxTabs + 1 }, (_, i) => String(i));
+  }
+  return hasProjectConstant(messages) ? ["0"] : ["0", "1"];
+}
+function generatedTabCount(messages) {
+  return generatedTabValues(messages).length;
+}
+function sendBranchingFactor(handlerCount, tabCount, contexts) {
+  return contexts.length * targetSetCount(contexts) * tabCount * handlerCount;
+}
+var DEFAULT_CONTEXTS, CONTEXT_NAME_PATTERN;
+var init_model_constants = __esm(() => {
+  DEFAULT_CONTEXTS = ["background", "content", "popup"];
+  CONTEXT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+});
+
+// tools/verify/src/runner/memory.ts
+function parseMemoryBytes(spec) {
+  const match = /^(\d+)\s*([bkmg])?$/i.exec(spec.trim());
+  if (!match?.[1])
+    return null;
+  const value = Number.parseInt(match[1], 10);
+  if (value <= 0)
+    return null;
+  const unit = (match[2] ?? "b").toLowerCase();
+  const multiplier = UNIT_BYTES[unit];
+  if (multiplier === undefined)
+    return null;
+  return value * multiplier;
+}
+function jvmHeapArg(memoryBytes) {
+  const megabytes = Math.max(64, Math.floor(memoryBytes * JVM_HEAP_FRACTION / MEGABYTE));
+  return `${megabytes}m`;
+}
+function javaToolOptions(memoryBytes) {
+  return `-Xmx${jvmHeapArg(memoryBytes)} -XX:+UseParallelGC`;
+}
+var DEFAULT_TLC_MEMORY = "4g", MIN_TLC_MEMORY = "512m", JVM_HEAP_FRACTION = 0.75, MEGABYTE, UNIT_BYTES, MIN_TLC_MEMORY_BYTES;
+var init_memory = __esm(() => {
+  MEGABYTE = 1024 ** 2;
+  UNIT_BYTES = {
+    b: 1,
+    k: 1024,
+    m: MEGABYTE,
+    g: 1024 ** 3
+  };
+  MIN_TLC_MEMORY_BYTES = parseMemoryBytes(MIN_TLC_MEMORY) ?? 512 * 1024 ** 2;
+});
+
 // tools/verify/src/analysis/model-coverage.ts
 function norm(field) {
   return field.replace(/_/g, ".");
@@ -751,6 +825,7 @@ async function generateSubsystemTLA(_subsystemName, subsystem, config, analysis)
 }
 var TLAValidationError, TLAGenerator;
 var init_tla = __esm(() => {
+  init_model_constants();
   init_temporal();
   TLAValidationError = class TLAValidationError extends Error {
     report;
@@ -770,7 +845,6 @@ var init_tla = __esm(() => {
     symmetrySets = [];
     resolvedActionNames = new Map;
     paramDomains = new Map;
-    tabSymmetryEnabled = false;
     tabCount = 0;
     moduleName = "UserApp";
     currentConfig;
@@ -981,7 +1055,7 @@ var init_tla = __esm(() => {
       lines.push("CONSTANTS");
     }
     addBasicConstants(lines, config) {
-      lines.push("  Contexts = {background, content, popup}");
+      lines.push(`  Contexts = {${resolveContexts(config).join(", ")}}`);
       lines.push(`  MaxMessages = ${config.messages.maxInFlight || 3}`);
       lines.push("  NULL = NULL");
       if (config.messages.perMessageBounds) {
@@ -1002,27 +1076,18 @@ var init_tla = __esm(() => {
         hasProjectConstant = true;
       }
       if ("maxContexts" in messages && messages.maxContexts !== undefined) {
-        lines.push(`  MaxContexts = ${messages.maxContexts}`);
         hasProjectConstant = true;
       }
       if ("maxClients" in messages && messages.maxClients !== undefined && !hasProjectConstant) {
         lines.push(`  MaxClients = ${messages.maxClients}`);
-        hasProjectConstant = true;
       }
-      if (this.tabSymmetryEnabled) {
-        for (let i = 0;i < this.tabCount; i++) {
-          lines.push(`  Tab${i} = Tab${i}`);
-        }
-        const tabValues = Array.from({ length: this.tabCount }, (_, i) => `Tab${i}`).join(", ");
-        lines.push(`  Tabs = {${tabValues}}`);
-      } else if ("maxTabs" in messages && messages.maxTabs !== undefined && messages.maxTabs !== null) {
-        const tabValues = Array.from({ length: messages.maxTabs + 1 }, (_, i) => i).join(", ");
-        lines.push(`  Tabs = {${tabValues}}`);
-      } else if (hasProjectConstant) {
-        lines.push("  Tabs = {0}");
-      } else {
-        lines.push("  Tabs = {0, 1}");
+      const tabValues = generatedTabValues(messages);
+      if (messages.tabSymmetry) {
+        for (const tab of tabValues) {
+          lines.push(`  ${tab} = ${tab}`);
+        }
       }
+      lines.push(`  Tabs = {${tabValues.join(", ")}}`);
       lines.push("  TimeoutLimit = 3");
     }
     addStateBoundsConstants(lines, state) {
@@ -1442,7 +1507,6 @@ var init_tla = __esm(() => {
       }
       const maxTabs = config.messages.maxTabs ?? 1;
       this.tabCount = maxTabs + 1;
-      this.tabSymmetryEnabled = true;
       this.line("\\* Tab symmetry constants for state space reduction (Tier 1 optimization)");
       this.line("CONSTANTS");
       this.indent++;
@@ -3562,11 +3626,20 @@ class DockerRunner {
     }
     const containerName = mintContainerName("tlc");
     sweepOrphanedContainersOnce();
+    const memory = options?.memory ?? DEFAULT_TLC_MEMORY;
+    const memoryBytes = parseMemoryBytes(memory);
+    if (memoryBytes === null) {
+      throw new Error(`Invalid verification.memory: "${memory}". Use a docker-style size such as "512m" or "8g".`);
+    }
     const args = [
       "run",
       "--rm",
       "--name",
       containerName,
+      "--memory",
+      memory,
+      "-e",
+      `JAVA_TOOL_OPTIONS=${javaToolOptions(memoryBytes)}`,
       "-v",
       `${specDir}:/work`,
       this.IMAGE_NAME,
@@ -3585,9 +3658,9 @@ class DockerRunner {
       timeout: options?.timeout,
       containerName
     });
-    return this.parseTLCOutput(result);
+    return this.parseTLCOutput(result, memory);
   }
-  parseTLCOutput(result) {
+  parseTLCOutput(result, memory) {
     const output = result.stdout + result.stderr;
     const violationMatch = output.match(/Error: Invariant (.*?) is violated/);
     if (violationMatch) {
@@ -3604,18 +3677,13 @@ class DockerRunner {
     if (result.exitCode !== 0 || output.includes("Error:")) {
       return {
         success: false,
-        error: this.extractError(output),
+        error: this.extractError(output, result.exitCode, memory),
         output
       };
     }
-    const statesMatch = output.match(/(\d+) states generated/);
-    const distinctMatch = output.match(/(\d+) distinct states/);
     return {
       success: true,
-      stats: {
-        statesGenerated: statesMatch?.[1] ? Number.parseInt(statesMatch[1], 10) : 0,
-        distinctStates: distinctMatch?.[1] ? Number.parseInt(distinctMatch[1], 10) : 0
-      },
+      ...parseTLCStats(output) ?? {},
       output
     };
   }
@@ -3637,7 +3705,14 @@ class DockerRunner {
     }
     return trace;
   }
-  extractError(output) {
+  extractError(output, exitCode, memory) {
+    const cap = memory ? ` (--memory ${memory})` : "";
+    if (/java\.lang\.OutOfMemoryError/.test(output)) {
+      return `TLC ran out of heap${cap}. The model is too large for this ceiling — raise verification.memory, lower messages.maxInFlight, or split the subsystem.`;
+    }
+    if (exitCode === 137) {
+      return `TLC was killed for exceeding the container memory limit${cap}. Raise verification.memory, lower messages.maxInFlight, or split the subsystem.`;
+    }
     if (/StatePool\w*\.run/.test(output) && /states\/.*No such file or directory/.test(output)) {
       return "TLC state-pool IO failure (states/.../<n>: No such file or directory). This is a Docker filesystem flake, not a spec error — re-run the verification. See issue #152.";
     }
@@ -3734,8 +3809,36 @@ class DockerRunner {
     });
   }
 }
-var __dirname = "/Users/AJT/projects/polly/packages/polly/tools/verify/src/runner", swept = false;
-var init_docker = () => {};
+function parseTLCStats(output) {
+  const summary = TLC_SUMMARY.exec(output);
+  if (!summary?.[1] || !summary[2] || !summary[3])
+    return;
+  const statesGenerated = Number.parseInt(summary[1], 10);
+  const distinctStates = Number.parseInt(summary[2], 10);
+  const statesLeftOnQueue = Number.parseInt(summary[3], 10);
+  const initial = TLC_INITIAL_STATES.exec(output)?.[1];
+  const initialStates = initial === undefined ? undefined : Number.parseInt(initial, 10);
+  const depth = TLC_SEARCH_DEPTH.exec(output)?.[1];
+  const searchDepth = depth === undefined ? undefined : Number.parseInt(depth, 10);
+  return {
+    stats: {
+      statesGenerated,
+      distinctStates,
+      statesLeftOnQueue,
+      ...initialStates === undefined ? {} : { initialStates },
+      ...searchDepth === undefined ? {} : { searchDepth },
+      exhaustive: statesLeftOnQueue === 0,
+      noActionEnabled: initialStates !== undefined && distinctStates === initialStates
+    }
+  };
+}
+var __dirname = "/Users/AJT/projects/polly/packages/polly/tools/verify/src/runner", swept = false, TLC_SUMMARY, TLC_INITIAL_STATES, TLC_SEARCH_DEPTH;
+var init_docker = __esm(() => {
+  init_memory();
+  TLC_SUMMARY = /^(\d+) states generated, (\d+) distinct states found, (\d+) states left on queue/m;
+  TLC_INITIAL_STATES = /Finished computing initial states: (\d+) distinct states generated/;
+  TLC_SEARCH_DEPTH = /The depth of the complete state graph search is (\d+)/;
+});
 
 // tools/verify/src/cli.ts
 init_expression_validator();
@@ -3778,6 +3881,9 @@ function computeMeshOrPeerSignalFindings(analysis, declaredMeshDocs) {
   return findings;
 }
 
+// tools/verify/src/analysis/state-space-estimator.ts
+init_model_constants();
+
 // tools/verify/src/config/types.ts
 function isAdapterConfig(config) {
   return "adapter" in config;
@@ -3790,17 +3896,20 @@ function isLegacyConfig(config) {
 function typedFieldCardinality(name, obj) {
   if (!("type" in obj))
     return null;
-  switch (obj.type) {
+  const values = obj["values"];
+  const min = obj["min"];
+  const max = obj["max"];
+  switch (obj["type"]) {
     case "boolean":
       return { name, cardinality: 2, kind: "boolean" };
     case "enum":
-      if (Array.isArray(obj.values)) {
-        return { name, cardinality: obj.values.length, kind: "enum" };
+      if (Array.isArray(values)) {
+        return { name, cardinality: values.length, kind: "enum" };
       }
       return { name, cardinality: "unbounded", kind: "enum" };
     case "number":
-      if (typeof obj.min === "number" && typeof obj.max === "number") {
-        return { name, cardinality: obj.max - obj.min + 1, kind: "number" };
+      if (typeof min === "number" && typeof max === "number") {
+        return { name, cardinality: max - min + 1, kind: "number" };
       }
       return { name, cardinality: "unbounded", kind: "number" };
     case "array":
@@ -3812,20 +3921,23 @@ function typedFieldCardinality(name, obj) {
   }
 }
 function legacyFieldCardinality(name, obj) {
-  if ("values" in obj && Array.isArray(obj.values)) {
-    const base = obj.values.length;
-    const extra = obj.abstract === true ? 1 : 0;
+  const values = obj["values"];
+  const abstract = obj["abstract"];
+  const min = obj["min"];
+  const max = obj["max"];
+  if (Array.isArray(values)) {
+    const extra = abstract === true ? 1 : 0;
     return {
       name,
-      cardinality: base + extra,
-      kind: obj.abstract ? "enum (abstract)" : "enum (values)"
+      cardinality: values.length + extra,
+      kind: abstract === true ? "enum (abstract)" : "enum (values)"
     };
   }
   if ("maxLength" in obj && !("type" in obj)) {
     return { name, cardinality: "unbounded", kind: "array" };
   }
-  if ("min" in obj && "max" in obj && typeof obj.min === "number" && typeof obj.max === "number" && !("type" in obj)) {
-    return { name, cardinality: obj.max - obj.min + 1, kind: "number" };
+  if (typeof min === "number" && typeof max === "number" && !("type" in obj)) {
+    return { name, cardinality: max - min + 1, kind: "number" };
   }
   return null;
 }
@@ -3839,15 +3951,6 @@ function fieldCardinality(name, value) {
   const obj = value;
   return typedFieldCardinality(name, obj) ?? legacyFieldCardinality(name, obj) ?? { name, cardinality: "unbounded", kind: "unknown" };
 }
-function permutations(n, k) {
-  if (k > n)
-    return 1;
-  let result = 1;
-  for (let i = 0;i < k; i++) {
-    result *= n - i;
-  }
-  return result;
-}
 function getHandlerCount(config, analysis) {
   if (isLegacyConfig(config)) {
     const msgs = config.messages;
@@ -3869,11 +3972,14 @@ function getMaxInFlight(config) {
   }
   return 1;
 }
-function getMaxTabs(config) {
+function getTabSetInput(config) {
   if (isLegacyConfig(config)) {
-    return config.messages.maxTabs ?? 1;
+    return config.messages;
   }
-  return 1;
+  return {};
+}
+function getContextSetInput(config) {
+  return config;
 }
 function getFeasibility(states) {
   if (states < 1e5)
@@ -3896,12 +4002,35 @@ function feasibilityLabel(f) {
       return "infeasible (likely won't terminate)";
   }
 }
-function estimateStateSpace(config, analysis) {
+var OMITTED_VARIABLES = "ports, status, deliveredTo, time and payload";
+function dominantTerm(e) {
+  const log10 = (n) => n > 0 ? Math.log10(n) : 0;
+  const topology = e.contextCount * e.targetSets * e.tabCount;
+  const terms = [
+    {
+      label: `state fields (${e.fieldProduct} combinations across ${e.contextCount} contexts)`,
+      decades: e.contextCount * log10(e.fieldProduct)
+    },
+    {
+      label: `handler count (${e.handlerCount} handlers at maxInFlight ${e.maxInFlight})`,
+      decades: e.maxInFlight * log10(e.handlerCount)
+    },
+    {
+      label: `send topology (${e.contextCount} sources x ${e.targetSets} target sets x ${e.tabCount} tabs)`,
+      decades: e.maxInFlight * log10(topology)
+    }
+  ];
+  return terms.reduce((a, b) => b.decades > a.decades ? b : a);
+}
+function estimateForScope(config, scope) {
   const state = config.state;
   const fields = [];
   const warnings = [];
   const suggestions = [];
+  const included = scope.stateFields ? new Set(scope.stateFields) : undefined;
   for (const [name, value] of Object.entries(state)) {
+    if (included && !included.has(name))
+      continue;
     fields.push(fieldCardinality(name, value));
   }
   const unboundedFields = fields.filter((f) => f.cardinality === "unbounded");
@@ -3911,33 +4040,56 @@ function estimateStateSpace(config, analysis) {
     warnings.push(`${unboundedFields.length} field(s) have unbounded domains: ${unboundedFields.map((f) => f.name).join(", ")}`);
     suggestions.push(`Fields ${unboundedFields.map((f) => f.name).join(", ")} have unbounded domains — their actual impact depends on handler logic`);
   }
-  const handlerCount = getHandlerCount(config, analysis);
-  const maxInFlight = getMaxInFlight(config);
-  const maxTabs = getMaxTabs(config);
-  const contextCount = maxTabs + 1;
+  const { handlerCount, maxInFlight } = scope;
+  const tabSetInput = getTabSetInput(config);
+  const tabCount = generatedTabCount(tabSetInput);
+  const contextSetInput = getContextSetInput(config);
+  const contexts = resolveContexts(contextSetInput);
+  const contextsDeclared = hasDeclaredContexts(contextSetInput);
+  const contextCount = contexts.length;
   const totalStateSpace = fieldProduct ** contextCount;
-  const interleavingFactor = permutations(handlerCount, maxInFlight);
+  const sendBranching = sendBranchingFactor(handlerCount, tabCount, contexts);
+  const interleavingFactor = sendBranching ** maxInFlight;
   const estimatedStates = totalStateSpace * interleavingFactor;
   const feasibility = getFeasibility(estimatedStates);
+  warnings.push(`Lower bound: the generated spec also carries ${OMITTED_VARIABLES}, none of which this figure models.`);
+  if (tabSetInput.tabSymmetry) {
+    warnings.push("tabSymmetry is enabled — TLC's symmetry reduction cuts the reachable set, so this is an upper bound on the tab dimension.");
+  }
+  const dominant = dominantTerm({
+    fieldProduct,
+    handlerCount,
+    contextCount,
+    targetSets: targetSetCount(contexts),
+    tabCount,
+    maxInFlight
+  });
+  suggestions.push(`Dominant term: ${dominant.label} — ~10^${dominant.decades.toFixed(1)} of ~10^${Math.log10(Math.max(estimatedStates, 1)).toFixed(1)}`);
+  if (maxInFlight > 1) {
+    suggestions.push(`maxInFlight ${maxInFlight} → ${maxInFlight - 1} divides the estimate by ${sendBranching.toLocaleString()}x (one fewer send to branch over)`);
+  }
+  if (!contextsDeclared) {
+    suggestions.push(`Contexts is the default {${contexts.join(", ")}} — no \`contexts\` key is declared. ` + `Declaring the ones this project has divides state replication by fieldProduct^(${contextCount} - n) ` + "and send branching by the drop in |Contexts| * (2^|Contexts| - 1) (polly#185)");
+  }
   if (handlerCount > 15) {
-    suggestions.push("Consider splitting into subsystems");
+    suggestions.push(`${handlerCount} handlers enter the estimate as ${handlerCount}^${maxInFlight} — splitting into subsystems is the cheapest cut`);
   }
   for (const f of boundedFields) {
     if (f.cardinality > 50) {
-      suggestions.push(`Consider reducing bounds for field "${f.name}" (${f.cardinality} values)`);
+      suggestions.push(`Field "${f.name}" (${f.cardinality} values) is raised to the power of ${contextCount} contexts — reducing its bounds compounds`);
     }
   }
-  if (maxInFlight > 2) {
-    const reducedInterleaving = permutations(handlerCount, 2);
-    const reduction = reducedInterleaving > 0 ? Math.round(interleavingFactor / reducedInterleaving) : 1;
-    suggestions.push(`Reducing maxInFlight from ${maxInFlight} to 2 would reduce interleaving by ~${reduction}x`);
-  }
   return {
+    ...scope.name === undefined ? {} : { subsystem: scope.name },
     fields,
     fieldProduct,
     handlerCount,
     maxInFlight,
     contextCount,
+    contexts,
+    contextsDeclared,
+    tabCount,
+    sendBranching,
     totalStateSpace,
     interleavingFactor,
     estimatedStates,
@@ -3946,6 +4098,24 @@ function estimateStateSpace(config, analysis) {
     suggestions
   };
 }
+function estimateStateSpace(config, analysis) {
+  return estimateForScope(config, {
+    handlerCount: getHandlerCount(config, analysis),
+    maxInFlight: getMaxInFlight(config)
+  });
+}
+function estimateSubsystems(config) {
+  const subsystems = config.subsystems;
+  if (!subsystems)
+    return [];
+  const topLevelMaxInFlight = getMaxInFlight(config);
+  return Object.entries(subsystems).map(([name, sub]) => estimateForScope(config, {
+    name,
+    stateFields: sub.state,
+    handlerCount: sub.handlers.length,
+    maxInFlight: sub.bounds?.maxInFlight ?? topLevelMaxInFlight
+  }));
+}
 
 // tools/verify/src/codegen/config.ts
 class ConfigGenerator {
@@ -3959,6 +4129,7 @@ class ConfigGenerator {
     this.addHeader();
     this.addImports();
     this.addExport();
+    this.addContextsConfig(analysis);
     this.addStateConfig(analysis.fields, analysis.resources);
     this.addMessagesConfig();
     this.addBehaviorConfig();
@@ -4194,6 +4365,53 @@ class ConfigGenerator {
     }
     return "{ min: /* CONFIGURE */ null, max: /* CONFIGURE */ null }";
   }
+  addContextsConfig(analysis) {
+    const inferred = [];
+    for (const handler of analysis.handlers ?? []) {
+      const node = handler.node;
+      if (node === undefined || node === "unknown")
+        continue;
+      if (!inferred.includes(node))
+        inferred.push(node);
+    }
+    this.line("// ─────────────────────────────────────────────────────────");
+    this.line("// Contexts — the processes/actors messages are routed between");
+    this.line("// ─────────────────────────────────────────────────────────");
+    this.line("// This is the cheapest term in the state space to cut. The model");
+    this.line("// replicates state across the set and quantifies every send over");
+    this.line("// |Contexts| x (2^|Contexts| - 1) source/target pairs.");
+    this.line("//");
+    this.line("// Measured on a two-handler model, one message in flight, one tab:");
+    this.line("//   • 3 contexts: 38,464 distinct states");
+    this.line("//   • 2 contexts:  4,896 distinct states");
+    this.line("//   • 1 context:     368 distinct states");
+    this.line("//");
+    const source = inferred.length > 0 ? inferred : this.projectTypeContexts();
+    if (source.length > 0) {
+      this.line(inferred.length > 0 ? "// ✓ Auto-configured from the file paths of the handlers" : `// ✓ Auto-configured from the project type (${this.projectType})`);
+      this.line(`contexts: /* REVIEW */ [${source.map((c) => `'${c}'`).join(", ")}],`);
+    } else {
+      this.line("// No context could be inferred from the handler file paths.");
+      this.line("// Omitting the key models the browser-extension default:");
+      this.line("//   ['background', 'content', 'popup']");
+      this.line("// contexts: /* CONFIGURE */ ['server'],");
+    }
+    this.line("");
+  }
+  projectTypeContexts() {
+    switch (this.projectType) {
+      case "websocket-app":
+        return ["server", "client"];
+      case "pwa":
+        return ["ServiceWorker", "Window"];
+      case "electron":
+        return ["main", "renderer"];
+      case "chrome-extension":
+        return ["background", "content", "popup"];
+      default:
+        return [];
+    }
+  }
   addMessagesConfig() {
     this.line("messages: {");
     this.indent++;
@@ -4263,13 +4481,6 @@ class ConfigGenerator {
         this.line("maxTabs: 1,");
         break;
       case "generic":
-        this.line("// Maximum contexts/actors to model.");
-        this.line("//");
-        this.line("// Recommended:");
-        this.line("//   • 2-3: Simple message passing");
-        this.line("//   • 4-5: Complex coordination");
-        this.line("//");
-        this.line("maxContexts: 3,");
         break;
     }
     this.line("");
@@ -4401,7 +4612,12 @@ function generateConfig(analysis, projectType = "chrome-extension") {
   return generator.generate(analysis, projectType);
 }
 
+// tools/verify/src/cli.ts
+init_model_constants();
+
 // tools/verify/src/config/parser.ts
+init_model_constants();
+init_memory();
 import * as fs from "node:fs";
 import * as path from "node:path";
 
@@ -4483,6 +4699,45 @@ function validateCoupledFields(coupledFields, stateConfig) {
 }
 
 // tools/verify/src/config/parser.ts
+var RESERVED_CONTEXT_NAMES = new Set([
+  "Contexts",
+  "MaxMessages",
+  "NULL",
+  "Tabs",
+  "TimeoutLimit",
+  "MaxWorkers",
+  "MaxRenderers",
+  "MaxClients",
+  "NoTarget",
+  "MeshDocs",
+  "ASSUME",
+  "BOOLEAN",
+  "CASE",
+  "CHOOSE",
+  "CONSTANT",
+  "CONSTANTS",
+  "DOMAIN",
+  "ELSE",
+  "ENABLED",
+  "EXCEPT",
+  "EXTENDS",
+  "FALSE",
+  "IF",
+  "IN",
+  "INSTANCE",
+  "LET",
+  "MODULE",
+  "OTHER",
+  "SUBSET",
+  "THEN",
+  "TRUE",
+  "UNCHANGED",
+  "UNION",
+  "VARIABLE",
+  "VARIABLES",
+  "WITH"
+]);
+
 class ConfigValidator {
   issues = [];
   validate(configPath) {
@@ -4596,6 +4851,7 @@ class ConfigValidator {
     this.findNullPlaceholders(config.messages, "messages");
     this.validateBounds(config);
     this.validateTier1Optimizations(config.messages);
+    this.validateContexts(config);
     if (config.verification) {
       this.validateVerificationOptions(config.verification);
     }
@@ -4875,6 +5131,140 @@ class ConfigValidator {
         });
       }
     }
+    this.validateMemory(verification.memory);
+  }
+  validateContexts(config) {
+    this.warnOnDeadMaxContexts(config);
+    const contexts = config.contexts;
+    if (contexts === undefined)
+      return;
+    if (!Array.isArray(contexts)) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "contexts",
+        message: "contexts must be an array of context names",
+        suggestion: `Use an array, e.g. ["server"], or omit the key for the default {${DEFAULT_CONTEXTS.join(", ")}}`
+      });
+      return;
+    }
+    if (contexts.length === 0) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "contexts",
+        message: "contexts is empty; the model needs at least one context",
+        suggestion: `Name at least one context, e.g. ["server"], or omit the key for the default {${DEFAULT_CONTEXTS.join(", ")}}`
+      });
+      return;
+    }
+    const seen = new Map;
+    for (const name of contexts) {
+      this.validateContextName(name, seen);
+    }
+    this.warnOnSingleContextMesh(config, contexts.length);
+  }
+  validateContextName(name, seen) {
+    if (typeof name !== "string") {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "contexts",
+        message: `Context name ${JSON.stringify(name)} is not a string`,
+        suggestion: "Every entry must be a string naming one context"
+      });
+      return;
+    }
+    const emitted = sanitizeContextName(name);
+    if (!CONTEXT_NAME_PATTERN.test(emitted)) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "contexts",
+        message: `Context "${name}" is not a TLA+ model value (emits as "${emitted}")`,
+        suggestion: "Start with a letter or underscore, then letters, digits or underscores"
+      });
+      return;
+    }
+    if (RESERVED_CONTEXT_NAMES.has(emitted)) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "contexts",
+        message: `Context "${name}" collides with a TLA+ keyword or a constant the .cfg already declares`,
+        suggestion: `Pick a name outside {${[...RESERVED_CONTEXT_NAMES].sort().join(", ")}}`
+      });
+      return;
+    }
+    const collidesWith = seen.get(emitted);
+    if (collidesWith !== undefined) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "contexts",
+        message: collidesWith === name ? `Context "${name}" is declared twice` : `Contexts "${collidesWith}" and "${name}" both emit as "${emitted}"`,
+        suggestion: "Each context must emit a distinct TLA+ model value"
+      });
+      return;
+    }
+    seen.set(emitted, name);
+    if (emitted !== name) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "warning",
+        field: "contexts",
+        message: `Context "${name}" is emitted as the model value "${emitted}"`,
+        suggestion: "Name it that way in the config so the spec and the config read alike"
+      });
+    }
+  }
+  warnOnDeadMaxContexts(config) {
+    if (config.messages?.maxContexts === undefined)
+      return;
+    this.issues.push({
+      type: "invalid_value",
+      severity: "warning",
+      field: "messages.maxContexts",
+      message: "messages.maxContexts does not size the Contexts set and never did",
+      suggestion: 'Declare the set instead, e.g. contexts: ["server", "client"]'
+    });
+  }
+  warnOnSingleContextMesh(config, contextCount) {
+    if (contextCount > 1)
+      return;
+    if (!config.mesh || Object.keys(config.mesh).length === 0)
+      return;
+    this.issues.push({
+      type: "invalid_value",
+      severity: "warning",
+      field: "contexts",
+      message: "one context with a `mesh` block: PropagateMeshOp needs two distinct contexts, so mesh propagation is never enabled",
+      suggestion: "Declare at least two contexts, or drop the mesh block from this model"
+    });
+  }
+  validateMemory(memory) {
+    if (memory === undefined)
+      return;
+    const bytes = parseMemoryBytes(memory);
+    if (bytes === null) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "verification.memory",
+        message: `"${memory}" is not a docker-style memory size`,
+        suggestion: 'Use a number with an optional b/k/m/g suffix, e.g. "8g"'
+      });
+      return;
+    }
+    if (bytes < MIN_TLC_MEMORY_BYTES) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "verification.memory",
+        message: `${memory} is below the ${MIN_TLC_MEMORY} minimum TLC can run in`,
+        suggestion: `Use ${MIN_TLC_MEMORY} or more`
+      });
+    }
   }
   validateTier2Optimizations(tier2) {
     if (tier2.temporalConstraints) {
@@ -8427,6 +8817,9 @@ async function analyzeCodebase(options) {
   const extractor = new TypeExtractor(options.tsConfigPath);
   return extractor.analyzeCodebase(options.stateFilePath);
 }
+// tools/verify/src/cli.ts
+init_memory();
+
 // tools/verify/src/runner/mesh-seed.ts
 function meshSeedCfg(baseCfg, opts) {
   if (!opts.disableFix)
@@ -8612,11 +9005,30 @@ async function estimateCommand() {
   if (exprValidation.warnings.length > 0) {
     displayExpressionWarnings(exprValidation);
   }
-  const estimate = estimateStateSpace(typedConfig, typedAnalysis);
-  displayEstimate(estimate);
+  const perSubsystem = estimateSubsystems(typedConfig);
+  if (perSubsystem.length > 0) {
+    for (const estimate of perSubsystem) {
+      displayEstimate(estimate);
+    }
+    displaySubsystemEstimateSummary(perSubsystem);
+    return;
+  }
+  displayEstimate(estimateStateSpace(typedConfig, typedAnalysis));
+}
+function displaySubsystemEstimateSummary(estimates) {
+  console.log(color(`Per-subsystem summary:
+`, COLORS.blue));
+  for (const e of estimates) {
+    const name = (e.subsystem ?? "?").padEnd(20);
+    const states = `~${e.estimatedStates.toLocaleString()}`.padEnd(20);
+    const feasColor = e.feasibility === "trivial" || e.feasibility === "feasible" ? COLORS.green : e.feasibility === "slow" ? COLORS.yellow : COLORS.red;
+    console.log(`  ${name} ${states} ${color(e.feasibility, feasColor)}`);
+  }
+  console.log();
 }
 function displayEstimate(estimate) {
-  console.log(color(`State space estimate:
+  const heading = estimate.subsystem ? `State space estimate — subsystem ${estimate.subsystem}:` : "State space estimate:";
+  console.log(color(`${heading}
 `, COLORS.blue));
   console.log(color("  Fields:", COLORS.blue));
   for (const field of estimate.fields) {
@@ -8629,8 +9041,11 @@ function displayEstimate(estimate) {
   console.log(`  Field combinations:     ${color(String(estimate.fieldProduct), COLORS.green)}`);
   console.log(`  Handlers:               ${estimate.handlerCount}`);
   console.log(`  Max in-flight:          ${estimate.maxInFlight}`);
-  console.log(`  Contexts:               ${estimate.contextCount} (${estimate.contextCount - 1} tab${estimate.contextCount - 1 === 1 ? "" : "s"} + background)`);
-  console.log(`  Interleaving factor:    ${estimate.interleavingFactor}`);
+  const contextSource = estimate.contextsDeclared ? "declared" : "the default — no `contexts` key";
+  console.log(`  Contexts:               ${estimate.contextCount} — ${estimate.contexts.join(", ")} (${contextSource})`);
+  console.log(`  Tabs:                   ${estimate.tabCount}`);
+  console.log(`  State across contexts:  ${estimate.fieldProduct}^${estimate.contextCount} = ${estimate.totalStateSpace.toLocaleString()}`);
+  console.log(`  Send branching:         ${estimate.sendBranching.toLocaleString()} per message (^${estimate.maxInFlight} = ${estimate.interleavingFactor.toLocaleString()})`);
   console.log();
   console.log(`  Estimated states:       ${color(`~${estimate.estimatedStates.toLocaleString()}`, COLORS.green)}`);
   const feasColor = estimate.feasibility === "trivial" || estimate.feasibility === "feasible" ? COLORS.green : estimate.feasibility === "slow" ? COLORS.yellow : COLORS.red;
@@ -8854,6 +9269,9 @@ function getTimeout(config) {
 function getWorkers(config) {
   return config.verification?.workers ?? 1;
 }
+function getMemory(config) {
+  return config.verification?.memory;
+}
 function getMaxDepth(config) {
   if ("tier2" in config && config.tier2?.boundedExploration?.maxDepth) {
     return config.tier2.boundedExploration.maxDepth;
@@ -8888,6 +9306,55 @@ async function runCoupledFieldsLint(config, analysis) {
   console.log(color("   the relationship with a `capabilities` invariant.", COLORS.yellow));
   console.log();
 }
+function describeContextSet(config) {
+  const contexts = resolveContexts(config);
+  const source = hasDeclaredContexts(config) ? "declared" : "default";
+  return `${contexts.join(", ")} (${contexts.length}, ${source})`;
+}
+function inferredContexts(analysis) {
+  const seen = [];
+  for (const handler of analysis.handlers) {
+    const node = handler.node;
+    if (node === undefined || node === "unknown")
+      continue;
+    if (!seen.includes(node))
+      seen.push(node);
+  }
+  return seen;
+}
+function displayContextDiagnostics(config, analysis) {
+  const declared = hasDeclaredContexts(config);
+  const contexts = new Set(resolveContexts(config));
+  const inferred = inferredContexts(analysis);
+  if (!declared) {
+    console.log(color(`ℹ️  No \`contexts\` key — modelling the default {${DEFAULT_CONTEXTS.join(", ")}}`, COLORS.gray));
+    if (inferred.length > 0) {
+      console.log(color(`   polly infers from the handler paths: ${inferred.join(", ")}`, COLORS.gray));
+      console.log(color(`   Declaring \`contexts: [${inferred.map((c) => `"${c}"`).join(", ")}]\` shrinks the model to the contexts you have.`, COLORS.gray));
+    }
+    console.log();
+    return;
+  }
+  const outside = analysis.handlers.filter((h) => {
+    const node = h.node;
+    return node !== undefined && node !== "unknown" && !contexts.has(sanitizeContextName(node));
+  });
+  if (outside.length === 0)
+    return;
+  console.log(color(`⚠️  ${outside.length} handler(s) run in a context \`contexts\` does not declare:`, COLORS.yellow));
+  for (const h of outside.slice(0, 10)) {
+    const node = h.node;
+    console.log(color(`   • ${h.messageType} → ${node} (${h.location.file})`, COLORS.yellow));
+  }
+  if (outside.length > 10) {
+    console.log(color(`   ... and ${outside.length - 10} more`, COLORS.yellow));
+  }
+  console.log();
+  console.log(color(`   The model quantifies sends over {${[...contexts].join(", ")}} only, so these handlers`, COLORS.yellow));
+  console.log(color("   are modelled from a source they are not in. Add the missing contexts, or correct the", COLORS.yellow));
+  console.log(color("   file paths polly infers them from.", COLORS.yellow));
+  console.log();
+}
 async function runFullVerification(configPath) {
   const config = await loadVerificationConfig(configPath);
   const analysis = await runCodebaseAnalysis();
@@ -8902,6 +9369,7 @@ async function runFullVerification(configPath) {
   const meshFindingCount = displayMeshOrPeerSignalWarnings(typedAnalysis, declaredMeshDocs);
   await runCoupledFieldsLint(typedConfig, typedAnalysis);
   await runModelCoverage(typedConfig, typedAnalysis, meshFindingCount);
+  displayContextDiagnostics(typedConfig, typedAnalysis);
   if (typedConfig.subsystems && Object.keys(typedConfig.subsystems).length > 0) {
     await runSubsystemVerification(typedConfig, typedAnalysis);
     if (isWitnessMode()) {
@@ -8927,6 +9395,7 @@ async function runMonolithicVerification(config, analysis) {
   const timeoutSeconds = getTimeout(typedConfig);
   const workers = getWorkers(typedConfig);
   const maxDepth = getMaxDepth(typedConfig);
+  const memory = getMemory(typedConfig);
   console.log(color("⚙️  Running TLC model checker...", COLORS.blue));
   if (timeoutSeconds === 0) {
     console.log(color("   No timeout set - will run until completion", COLORS.gray));
@@ -8938,13 +9407,16 @@ async function runMonolithicVerification(config, analysis) {
   if (maxDepth !== undefined) {
     console.log(color(`   Max depth: ${maxDepth}`, COLORS.gray));
   }
+  console.log(color(`   Memory: ${memory ?? DEFAULT_TLC_MEMORY}`, COLORS.gray));
+  console.log(color(`   Contexts: ${describeContextSet(typedConfig)}`, COLORS.gray));
   console.log();
   const result = await docker.runTLC(specPath, {
     workers,
     timeout: timeoutSeconds > 0 ? timeoutSeconds * 1000 : undefined,
-    maxDepth
+    maxDepth,
+    memory
   });
-  const meshSeed = await runMeshSeedGuard(docker, specDir, config);
+  const meshSeed = await runMeshSeedGuard(docker, specDir, config, memory);
   if (meshSeed && !meshSeed.success) {
     console.log(color(`
 ❌ Mesh seed-race guard failed (polly#113 / polly#114)
@@ -9011,6 +9483,9 @@ async function runSubsystemVerification(config, analysis) {
   const timeoutSeconds = getTimeout(config);
   const workers = getWorkers(config);
   const maxDepth = getMaxDepth(config);
+  const memory = getMemory(config);
+  console.log(color(`⚙️  Contexts: ${describeContextSet(config)}`, COLORS.gray));
+  console.log();
   await Promise.resolve().then(() => init_tla());
   const results = [];
   const customTLAPaths = getCustomTLAPaths(config);
@@ -9036,7 +9511,8 @@ async function runSubsystemVerification(config, analysis) {
     const result = await docker.runTLC(specPath, {
       workers,
       timeout: timeoutSeconds > 0 ? timeoutSeconds * 1000 : undefined,
-      maxDepth
+      maxDepth,
+      memory
     });
     const elapsed = (Date.now() - startTime) / 1000;
     results.push({
@@ -9044,9 +9520,8 @@ async function runSubsystemVerification(config, analysis) {
       success: result.success,
       handlerCount: sub.handlers.length,
       ensuresCount,
-      stateCount: result.stats?.distinctStates ?? 0,
       elapsed,
-      stats: result.stats,
+      ...result.stats === undefined ? {} : { stats: result.stats },
       error: result.error
     });
     if (result.success) {
@@ -9065,6 +9540,14 @@ async function runSubsystemVerification(config, analysis) {
   displayCompositionalReport(results, interference.valid);
 }
 var DEFAULT_WITNESS_TIMEOUT_MS = 180000;
+function witnessExplorationNote(stats) {
+  if (!stats)
+    return "TLC printed no summary line — exploration incomplete, verdict unsound";
+  if (!stats.exhaustive) {
+    return `${stats.distinctStates} distinct states explored, ${stats.statesLeftOnQueue} left on queue — not exhaustive`;
+  }
+  return `${stats.distinctStates} distinct states explored`;
+}
 async function globAbsolute(cwd, pattern) {
   const out = [];
   for await (const f of new Bun.Glob(pattern).scan({ cwd, absolute: true, onlyFiles: true })) {
@@ -9097,6 +9580,7 @@ async function runWitnessVerification(config) {
   const timeoutSeconds = getTimeout(config);
   const timeout = timeoutSeconds > 0 ? timeoutSeconds * 1000 : DEFAULT_WITNESS_TIMEOUT_MS;
   const workers = getWorkers(config);
+  const memory = getMemory(config);
   const results = [];
   let idx = 0;
   for (const w of witnesses) {
@@ -9183,7 +9667,7 @@ async function runWitnessVerification(config) {
     console.log(color(`     ${subsystem} ⊨ ${w.predicate}`, COLORS.gray));
     let tlc;
     try {
-      tlc = await docker.runTLC(witnessTla, { workers, timeout });
+      tlc = await docker.runTLC(witnessTla, { workers, timeout, memory });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       results.push({
@@ -9212,7 +9696,7 @@ async function runWitnessVerification(config) {
       continue;
     }
     const verdict = witnessVerdict(polarity, reachable);
-    const note = reachable ? undefined : `${tlc.stats?.distinctStates ?? 0} distinct states explored`;
+    const note = reachable ? undefined : witnessExplorationNote(tlc.stats);
     results.push({
       id,
       status: verdict.status,
@@ -9278,6 +9762,53 @@ function displayEnsuresSummary(results) {
   console.log(color("  A property only fires at states where its handler is enabled — raise", COLORS.gray));
   console.log(color("  bounds.maxInFlight on a subsystem to reach multi-step-reachable handlers.", COLORS.gray));
 }
+function stateColumn(stats) {
+  if (!stats)
+    return "? states";
+  if (!stats.exhaustive)
+    return `${stats.distinctStates}+ states`;
+  return `${stats.distinctStates} states`;
+}
+function displayTLCStats(stats) {
+  if (!stats) {
+    console.log(color("   States explored: unknown (TLC printed no summary line)", COLORS.yellow));
+    return;
+  }
+  console.log(color(`   States explored: ${stats.statesGenerated}`, COLORS.gray));
+  console.log(color(`   Distinct states: ${stats.distinctStates}`, COLORS.gray));
+  if (stats.searchDepth !== undefined) {
+    console.log(color(`   Search depth:    ${stats.searchDepth}`, COLORS.gray));
+  }
+  if (!stats.exhaustive) {
+    console.log(color(`   ⚠ incomplete: ${stats.statesLeftOnQueue} states left on queue — the model was not exhausted`, COLORS.yellow));
+  }
+  if (stats.noActionEnabled) {
+    console.log(color(`   ⚠ no action was ever enabled: distinct states equal the ${stats.initialStates} initial states`, COLORS.yellow));
+  }
+}
+function displayIncompleteSubsystems(results) {
+  const notes = [];
+  for (const r of results) {
+    if (!r.success)
+      continue;
+    if (!r.stats) {
+      notes.push(`${r.name}: TLC printed no summary line — state count unknown`);
+      continue;
+    }
+    if (!r.stats.exhaustive) {
+      notes.push(`${r.name}: ${r.stats.statesLeftOnQueue} states left on queue — not exhausted`);
+    }
+    if (r.stats.noActionEnabled) {
+      notes.push(`${r.name}: no action was ever enabled — the ${r.stats.initialStates} states explored are the initial states`);
+    }
+  }
+  if (notes.length === 0)
+    return;
+  console.log();
+  for (const note of notes) {
+    console.log(color(`  ⚠ ${note}`, COLORS.yellow));
+  }
+}
 function displayCompositionalReport(results, nonInterferenceValid) {
   console.log(color(`Subsystem verification results:
 `, COLORS.blue));
@@ -9286,10 +9817,11 @@ function displayCompositionalReport(results, nonInterferenceValid) {
     const name = r.name.padEnd(20);
     const handlers = `${r.handlerCount} handler${r.handlerCount === 1 ? "" : "s"}`;
     const ensures = `${r.ensuresCount} ensures`;
-    const states = `${r.stateCount} states`;
+    const states = stateColumn(r.stats);
     const time = `${r.elapsed.toFixed(1)}s`;
     console.log(`  ${status} ${name} ${handlers.padEnd(14)} ${ensures.padEnd(12)} ${states.padEnd(14)} ${time}`);
   }
+  displayIncompleteSubsystems(results);
   displayEnsuresSummary(results);
   console.log();
   const nonIntLabel = nonInterferenceValid ? color("✓ verified (no cross-subsystem state writes)", COLORS.green) : color("⚠ violations detected", COLORS.yellow);
@@ -9387,7 +9919,7 @@ function findMeshSeedSpecDir() {
   }
   return null;
 }
-async function runMeshSeedGuard(docker, specDir, config) {
+async function runMeshSeedGuard(docker, specDir, config, memory) {
   if (getMeshDocIds(config).length === 0)
     return;
   const sourceDir = findMeshSeedSpecDir();
@@ -9400,7 +9932,7 @@ async function runMeshSeedGuard(docker, specDir, config) {
   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(path5.join(specDir, "MeshSeed.tla"), { workers: 1 });
+  return docker.runTLC(path5.join(specDir, "MeshSeed.tla"), { workers: 1, memory });
 }
 async function setupDocker() {
   await Promise.resolve().then(() => init_docker());
@@ -9460,8 +9992,7 @@ function displayVerificationResults(result, specDir) {
     console.log(color(`✅ Verification passed!
 `, COLORS.green));
     console.log(color("Statistics:", COLORS.blue));
-    console.log(color(`   States explored: ${result.stats?.statesGenerated || 0}`, COLORS.gray));
-    console.log(color(`   Distinct states: ${result.stats?.distinctStates || 0}`, COLORS.gray));
+    displayTLCStats(result.stats);
     console.log();
     return;
   }
@@ -9574,4 +10105,4 @@ main().catch((error) => {
   process.exit(1);
 });
 
-//# debugId=92CAFBFCF98F237564756E2164756E21
+//# debugId=3AB21B8DB351312E64756E2164756E21