@fairfox/polly 0.77.3 → 0.79.0

package/dist/tools/test/src/tiers/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Manifest types for the tiered test engine.
+ *
+ * The engine is deliberately pure: it knows how to *run* a plan of cases as
+ * isolated subprocesses, gate them on environment capabilities, time them, and
+ * report. It knows nothing about Polly's specific scripts — those are supplied
+ * as a {@link TierPlan} by a front-end (Polly's internal registry, or a
+ * consumer-discovery step behind `polly test`). This keeps the engine reusable
+ * and respects the repo's src → tools → cli → scripts import boundary.
+ */
+/** A capability a case needs from the host before it can run. */
+export type Need = "docker" | "browser" | "network";
+/** How a case is executed. Both forms run in their own subprocess. */
+export type CaseExec = {
+    /**
+     * A module that may `export async function run(ctx)`. The worker imports
+     * it; if `run` is exported it is called for a structured result,
+     * otherwise the module's import side-effect (legacy top-level `main()`)
+     * runs and its `process.exitCode` becomes the result. This is what lets
+     * converted and unconverted scripts coexist.
+     */
+    kind: "module";
+    modulePath: string;
+} | {
+    /** An arbitrary command; success is exit code 0. */
+    kind: "command";
+    argv: string[];
+    cwd?: string;
+};
+/** One runnable unit within a tier. */
+export interface CaseSpec {
+    /** Stable id, e.g. "mesh.blob-transfer". Used for --only matching. */
+    id: string;
+    /** Human label for reports; defaults to id. */
+    label?: string;
+    /** Free-form tags for --only filtering (e.g. "mesh", "revocation"). */
+    tags?: string[];
+    /** Host capabilities required; unmet → skipped with a logged reason. */
+    needs?: Need[];
+    /** Per-case timeout. Defaults to the engine's tier default. */
+    timeoutMs?: number;
+    exec: CaseExec;
+}
+/** An ordered group of cases sharing a realism level. */
+export interface Tier {
+    name: string;
+    /** One-line description shown by --list. */
+    description?: string;
+    /** Run cases in this tier concurrently up to this many at once. Default 1. */
+    concurrency?: number;
+    /** Default per-case timeout for this tier. */
+    timeoutMs?: number;
+    cases: CaseSpec[];
+}
+/** The full thing handed to the engine. Tiers run in array order. */
+export interface TierPlan {
+    tiers: Tier[];
+}
+export type CaseOutcome = "pass" | "fail" | "skip" | "timeout";
+export interface CaseReport {
+    tier: string;
+    id: string;
+    label: string;
+    outcome: CaseOutcome;
+    durationMs: number;
+    message?: string;
+    /** Reason a case was skipped (unmet need). */
+    skipReason?: string;
+}
+export interface RunReport {
+    cases: CaseReport[];
+    passed: number;
+    failed: number;
+    skipped: number;
+    durationMs: number;
+    ok: boolean;
+}
+/** Options controlling a single engine run. */
+export interface EngineOptions {
+    /** Only run these tiers (by name). Empty = all tiers in the plan. */
+    tiers?: string[];
+    /** Only run cases whose id/label/tags match one of these substrings. */
+    only?: string[];
+    /** Stop after the first tier that has a failure. */
+    bail?: boolean;
+    /** Treat unmet-need skips as failures (CI-strict). Default false. */
+    strictNeeds?: boolean;
+    /** Forwarded into each case's environment. */
+    env?: Record<string, string | undefined>;
+    /** Default working directory for cases that don't set their own. */
+    cwd?: string;
+    /** Sink for engine-level progress lines. Defaults to console.log. */
+    log?: (message: string) => void;
+}

package/dist/tools/test/src/tiers/worker.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/tools/test/src/tiers/worker.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// tools/test/src/e2e-shared/contract.ts
+function standaloneContext() {
+  return {
+    log: (message) => console.log(message),
+    env: process.env
+  };
+}
+
+// tools/test/src/tiers/protocol.ts
+var SENTINEL = "__TIER_RESULT__";
+
+// tools/test/src/tiers/worker.ts
+function emit(result) {
+  process.stdout.write(`
+${SENTINEL}${JSON.stringify(result)}
+`);
+}
+async function runWorker() {
+  const modulePath = process.argv[2];
+  if (!modulePath) {
+    emit({ pass: false, message: "worker: no module path given" });
+    return;
+  }
+  try {
+    const mod = await import(modulePath);
+    if (typeof mod.run === "function") {
+      const result = await mod.run(standaloneContext());
+      emit({ pass: Boolean(result?.pass), message: result?.message, detail: result?.detail });
+    } else {
+      emit({ pass: (process.exitCode ?? 0) === 0 });
+    }
+  } catch (err) {
+    emit({ pass: false, message: err instanceof Error ? err.message : String(err) });
+  }
+}
+if (__require.main == __require.module) {
+  await runWorker();
+  process.exit(0);
+}
+
+//# debugId=0FA2FEFC484C1D5964756E2164756E21

package/dist/tools/test/src/tiers/worker.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../tools/test/src/e2e-shared/contract.ts", "../tools/test/src/tiers/protocol.ts", "../tools/test/src/tiers/worker.ts"],
+  "sourcesContent": [
+    "/**\n * The contract every tiered test case speaks.\n *\n * An e2e script is \"tier-aware\" when it exports an async `run(ctx)` that\n * returns a {@link TierResult} instead of signalling success through\n * `process.exitCode`. The engine prefers this export so it can collect a\n * structured result; scripts that do not export it still run (the engine\n * falls back to executing the file and reading its exit code), so the\n * migration is incremental and never breaks the suite.\n *\n * Standalone execution is preserved: a converted script keeps a\n * `if (import.meta.main) selfRun(run)` footer so `bun scripts/e2e-foo.ts`\n * behaves exactly as before.\n */\n\n/** Logger handed to a case so its output can be captured/prefixed by the engine. */\nexport type TierLog = (message: string) => void;\n\n/** Context passed to a case's `run()`. Kept small and forward-compatible. */\nexport interface TierContext {\n  /** Emit a progress line. Defaults to `console.log` when run standalone. */\n  log: TierLog;\n  /** Extra environment the engine wants the case to honour (e.g. SIGNALING_URL). */\n  env: Record<string, string | undefined>;\n}\n\n/** What a case reports back. `pass: false` with a `message` is a clean failure. */\nexport interface TierResult {\n  pass: boolean;\n  /** Human-readable failure reason; omitted on success. */\n  message?: string;\n  /** Optional structured detail surfaced in `--json` output. */\n  detail?: Record<string, unknown>;\n}\n\nexport type TierRun = (ctx: TierContext) => Promise<TierResult>;\n\n/** Build a default context for standalone (`import.meta.main`) execution. */\nexport function standaloneContext(): TierContext {\n  return {\n    log: (message: string) => console.log(message),\n    env: process.env,\n  };\n}\n\n/**\n * Footer helper for converted scripts: runs the case standalone, prints a\n * PASS/FAIL line in the historical `[e2e] <capability>: PASS` format, and sets\n * the process exit code. Keeps the file runnable on its own.\n */\nexport async function selfRun(capability: string, run: TierRun): Promise<void> {\n  const ctx = standaloneContext();\n  try {\n    const result = await run(ctx);\n    if (result.pass) {\n      ctx.log(`[e2e] ${capability}: PASS`);\n    } else {\n      ctx.log(`[e2e] ${capability}: FAIL — ${result.message ?? \"no reason given\"}`);\n      process.exitCode = 1;\n    }\n  } catch (err) {\n    ctx.log(`[e2e] ${capability}: FAIL — ${err instanceof Error ? err.message : String(err)}`);\n    process.exitCode = 1;\n  }\n}\n",
+    "/**\n * The one shared constant between the engine and its subprocess worker.\n *\n * It lives in its own leaf module so the engine never has to *import* the\n * worker (only spawn it by path). If the engine imported the worker, a\n * `splitting: false` bundle would inline the worker's `import.meta.main`\n * self-exec block into the CLI bundle and run it on startup. Keeping the\n * sentinel here avoids that.\n */\nexport const SENTINEL = \"__TIER_RESULT__\";\n",
+    "#!/usr/bin/env bun\n/**\n * Subprocess entry for a single \"module\" case.\n *\n * Spawned by the engine as `bun worker.ts <modulePath> <id>`. Running each case\n * in its own process is deliberate: the e2e scripts mutate globals (happy-dom),\n * bind ephemeral ports, and drive Puppeteer — they were written assuming\n * process isolation, and the engine preserves it.\n *\n * Protocol: the worker prints exactly one sentinel line\n *   __TIER_RESULT__{\"pass\":true,...}\n * to stdout. Everything else on stdout is the case's own logging, forwarded by\n * the parent. If the case hard-exits (legacy `process.exit(1)`) before the\n * sentinel, the parent falls back to the worker's exit code.\n */\nimport { standaloneContext, type TierResult } from \"../e2e-shared/contract\";\nimport { SENTINEL } from \"./protocol\";\n\nfunction emit(result: TierResult): void {\n  process.stdout.write(`\\n${SENTINEL}${JSON.stringify(result)}\\n`);\n}\n\nasync function runWorker(): Promise<void> {\n  const modulePath = process.argv[2];\n  if (!modulePath) {\n    emit({ pass: false, message: \"worker: no module path given\" });\n    return;\n  }\n\n  try {\n    // Importing a converted script is side-effect-free (its self-run footer is\n    // guarded by import.meta.main). Importing a legacy script runs its top-level\n    // main() now, which sets process.exitCode.\n    const mod: { run?: (ctx: unknown) => Promise<TierResult> } = await import(modulePath);\n\n    if (typeof mod.run === \"function\") {\n      const result = await mod.run(standaloneContext());\n      emit({ pass: Boolean(result?.pass), message: result?.message, detail: result?.detail });\n    } else {\n      // Legacy: the import side-effect already ran the test; trust its exit code.\n      emit({ pass: (process.exitCode ?? 0) === 0 });\n    }\n  } catch (err) {\n    emit({ pass: false, message: err instanceof Error ? err.message : String(err) });\n  }\n}\n\n// Only execute when invoked directly; the engine also imports SENTINEL from here.\nif (import.meta.main) {\n  await runWorker();\n  // Force exit so an open Puppeteer/server handle can't keep the worker alive;\n  // the result has already been emitted and captured by the parent.\n  process.exit(0);\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAsCO,SAAS,iBAAiB,GAAgB;AAAA,EAC/C,OAAO;AAAA,IACL,KAAK,CAAC,YAAoB,QAAQ,IAAI,OAAO;AAAA,IAC7C,KAAK,QAAQ;AAAA,EACf;AAAA;;;ACjCK,IAAM,WAAW;;;ACSxB,SAAS,IAAI,CAAC,QAA0B;AAAA,EACtC,QAAQ,OAAO,MAAM;AAAA,EAAK,WAAW,KAAK,UAAU,MAAM;AAAA,CAAK;AAAA;AAGjE,eAAe,SAAS,GAAkB;AAAA,EACxC,MAAM,aAAa,QAAQ,KAAK;AAAA,EAChC,IAAI,CAAC,YAAY;AAAA,IACf,KAAK,EAAE,MAAM,OAAO,SAAS,+BAA+B,CAAC;AAAA,IAC7D;AAAA,EACF;AAAA,EAEA,IAAI;AAAA,IAIF,MAAM,MAAuD,MAAa;AAAA,IAE1E,IAAI,OAAO,IAAI,QAAQ,YAAY;AAAA,MACjC,MAAM,SAAS,MAAM,IAAI,IAAI,kBAAkB,CAAC;AAAA,MAChD,KAAK,EAAE,MAAM,QAAQ,QAAQ,IAAI,GAAG,SAAS,QAAQ,SAAS,QAAQ,QAAQ,OAAO,CAAC;AAAA,IACxF,EAAO;AAAA,MAEL,KAAK,EAAE,OAAO,QAAQ,YAAY,OAAO,EAAE,CAAC;AAAA;AAAA,IAE9C,OAAO,KAAK;AAAA,IACZ,KAAK,EAAE,MAAM,OAAO,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,EAAE,CAAC;AAAA;AAAA;AAKnF,IAAI,oCAAkB;AAAA,EACpB,MAAM,UAAU;AAAA,EAGhB,QAAQ,KAAK,CAAC;AAChB;",
+  "debugId": "0FA2FEFC484C1D5964756E2164756E21",
+  "names": []
+}

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

@@ -249,6 +249,110 @@ var init_expression_validator = __esm(() => {
   WEAK_NEGATION = /([a-zA-Z_][\w.]*(?:\.value\.[\w.]+|\.value\b|))?\s*!==?\s*("[^"]*"|'[^']*'|\d+|true|false|null)/;
 });
 
+// tools/verify/src/analysis/model-coverage.ts
+var exports_model_coverage = {};
+__export(exports_model_coverage, {
+  strictCoverageReasons: () => strictCoverageReasons,
+  computeModelCoverage: () => computeModelCoverage
+});
+function norm(field) {
+  return field.replace(/_/g, ".");
+}
+function computeModelCoverage(stateFields, handlers) {
+  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) }));
+  for (const handler of handlers) {
+    for (const assignment of handler.assignments) {
+      const key = norm(assignment.field);
+      const writers = writersByField.get(key);
+      if (writers)
+        writers.add(handler.messageType);
+    }
+  }
+  const fieldCoverage = declaredOrder.map(({ raw, key }) => ({
+    field: raw,
+    writers: Array.from(writersByField.get(key) ?? []).sort()
+  }));
+  const unwrittenFields = fieldCoverage.filter((f) => f.writers.length === 0).map((f) => f.field);
+  const declaredKeys = new Set(declaredOrder.map((d) => d.key));
+  const unconstrainedMutators = [];
+  for (const handler of handlers) {
+    if (handler.postconditions.length > 0)
+      continue;
+    const fields = Array.from(new Set(handler.assignments.map((a) => norm(a.field)).filter((f) => declaredKeys.has(f)))).sort();
+    if (fields.length > 0) {
+      unconstrainedMutators.push({
+        handler: handler.messageType,
+        fields,
+        location: handler.location
+      });
+    }
+  }
+  return {
+    fieldCoverage,
+    unwrittenFields,
+    unconstrainedMutators,
+    hasStrictViolation: unwrittenFields.length > 0
+  };
+}
+function strictCoverageReasons(report, meshFindingCount) {
+  const reasons = [];
+  if (report.hasStrictViolation) {
+    reasons.push(`${report.unwrittenFields.length} declared state field(s) written by no modelled handler`);
+  }
+  if (meshFindingCount > 0) {
+    reasons.push(`${meshFindingCount} unverified $meshState/$peerState predicate(s)`);
+  }
+  return reasons;
+}
+
+// tools/verify/src/analysis/coupled-fields.ts
+var exports_coupled_fields = {};
+__export(exports_coupled_fields, {
+  checkCoupledFields: () => checkCoupledFields
+});
+function norm2(field) {
+  return field.replace(/_/g, ".");
+}
+function checkCoupledFields(coupledFields, handlers) {
+  const violations = [];
+  for (const rawGroup of coupledFields) {
+    const group = rawGroup.map(norm2);
+    const groupSet = new Set(group);
+    if (groupSet.size < 2)
+      continue;
+    for (const handler of handlers) {
+      const violation = subsetViolation(group, groupSet, handler);
+      if (violation)
+        violations.push(violation);
+    }
+  }
+  return { valid: violations.length === 0, violations };
+}
+function writtenFields(group, handler) {
+  const written = new Set;
+  for (const assignment of handler.assignments) {
+    const field = norm2(assignment.field);
+    if (group.has(field))
+      written.add(field);
+  }
+  return written;
+}
+function subsetViolation(group, groupSet, handler) {
+  const written = writtenFields(groupSet, handler);
+  if (written.size === 0 || written.size === groupSet.size)
+    return null;
+  return {
+    group,
+    handler: handler.messageType,
+    written: group.filter((f) => written.has(f)),
+    missing: group.filter((f) => !written.has(f))
+  };
+}
+
 // tools/verify/src/analysis/non-interference.ts
 var exports_non_interference = {};
 __export(exports_non_interference, {
@@ -1253,28 +1357,35 @@ var init_tla = __esm(() => {
       return key.replace(/[^A-Za-z0-9_]/g, "_");
     }
     fieldConfigInitialValue(_path, fieldConfig, _config) {
-      const fc = fieldConfig;
-      if (fc["type"] === "boolean")
-        return "FALSE";
-      if (fc["type"] === "number") {
-        const min = typeof fc["min"] === "number" ? fc["min"] : 0;
-        return String(min);
-      }
-      if (fc["type"] === "enum" && Array.isArray(fc["values"]) && fc["values"].length > 0) {
-        return `"${String(fc["values"][0])}"`;
-      }
-      if (fc["type"] === "string") {
-        return typeof fc["initial"] === "string" ? `"${fc["initial"]}"` : '""';
-      }
-      if (fc["type"] === "array") {
-        return "<<>>";
-      }
-      if (Array.isArray(fc.values)) {
-        const values = fc.values;
-        if (values.length > 0)
-          return `"${values[0]}"`;
+      return this.typedFieldInitialValue(fieldConfig) ?? this.legacyValuesInitialValue(fieldConfig) ?? '"v1"';
+    }
+    typedFieldInitialValue(fieldConfig) {
+      if (!("type" in fieldConfig))
+        return;
+      switch (fieldConfig.type) {
+        case "boolean":
+          return "FALSE";
+        case "number":
+          return String(typeof fieldConfig.min === "number" ? fieldConfig.min : 0);
+        case "enum": {
+          const values = fieldConfig.values;
+          if (Array.isArray(values) && values.length > 0)
+            return `"${String(values[0])}"`;
+          return;
+        }
+        case "string":
+          return typeof fieldConfig.initial === "string" ? `"${fieldConfig.initial}"` : '""';
+        case "array":
+          return "<<>>";
+        default:
+          return;
       }
-      return '"v1"';
+    }
+    legacyValuesInitialValue(fieldConfig) {
+      if (!("values" in fieldConfig) || !Array.isArray(fieldConfig.values))
+        return;
+      const [first] = fieldConfig.values;
+      return first === undefined ? undefined : `"${first}"`;
     }
     defineValueTypes() {
       this.line("\\* Generic value type for sequences and maps");
@@ -2678,6 +2789,9 @@ var init_tla = __esm(() => {
       this.indent--;
       this.indent--;
       this.line("");
+      if (config.capabilities && config.capabilities.length > 0) {
+        this.addCapabilityInvariants(config.capabilities);
+      }
       if (this.extractedInvariants.length > 0) {
         this.line("\\* Extracted invariants from code annotations");
         this.line("");
@@ -2694,6 +2808,15 @@ var init_tla = __esm(() => {
       this.line("\\* State constraint to bound state space");
       this.addStateConstraint(config, _analysis);
     }
+    addCapabilityInvariants(capabilities) {
+      for (const cap of capabilities) {
+        this.extractedInvariants.push({
+          name: `Capability_${cap.name}`,
+          description: cap.message ? `polly#160 capability: ${cap.message}` : `polly#160 capability: ${cap.name} requires its precondition`,
+          expression: `(!(${cap.enabledBy})) || (${cap.requires})`
+        });
+      }
+    }
     addTemporalConstraints(constraints) {
       this.line("\\* Tier 2: Temporal constraint invariants");
       this.line("\\* Enforce ordering requirements between message types");
@@ -3910,6 +4033,85 @@ function generateConfig(analysis, projectType = "chrome-extension") {
 // tools/verify/src/config/parser.ts
 import * as fs from "node:fs";
 import * as path from "node:path";
+
+// tools/verify/src/config/capability-validation.ts
+init_expression_validator();
+function validateCapabilities(capabilities, stateConfig) {
+  if (!capabilities || capabilities.length === 0)
+    return [];
+  const issues = [];
+  const configKeys = new Set(Object.keys(stateConfig));
+  for (const cap of capabilities) {
+    const name = cap.name?.trim();
+    if (!name) {
+      issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "capabilities",
+        message: "Capability is missing a name.",
+        suggestion: "Give each capability a unique name; it becomes the TLA+ invariant identifier."
+      });
+      continue;
+    }
+    issues.push(...validateExpression(name, "enabledBy", cap.enabledBy, configKeys, stateConfig), ...validateExpression(name, "requires", cap.requires, configKeys, stateConfig));
+  }
+  return issues;
+}
+function validateExpression(name, slot, expr, configKeys, stateConfig) {
+  const field = `capabilities.${name}.${slot}`;
+  if (!expr?.trim()) {
+    return [
+      {
+        type: "capability_empty_expression",
+        severity: "error",
+        field,
+        message: `Capability "${name}" has an empty ${slot} expression.`,
+        suggestion: `Provide a state expression for ${slot}, e.g. "state.authenticated".`
+      }
+    ];
+  }
+  const refs = extractFieldRefs(expr);
+  if (refs.length === 0) {
+    return [
+      {
+        type: "capability_empty_expression",
+        severity: "error",
+        field,
+        message: `Capability "${name}" ${slot} expression "${expr}" references no state field.`,
+        suggestion: 'Reference state via the state./.value form (e.g. "state.authReady"); a bare identifier produces a silently-vacuous invariant.'
+      }
+    ];
+  }
+  return refs.filter((ref) => !fieldInConfig(ref, configKeys, stateConfig)).map((ref) => ({
+    type: "capability_unknown_field",
+    severity: "error",
+    field,
+    message: `Capability "${name}" ${slot} references "${ref}", which is not in the state config.`,
+    suggestion: `Add "${ref}" to state, or correct the expression. Known fields: ${[...configKeys].join(", ")}`
+  }));
+}
+function validateCoupledFields(coupledFields, stateConfig) {
+  if (!coupledFields || coupledFields.length === 0)
+    return [];
+  const issues = [];
+  const configKeys = new Set(Object.keys(stateConfig));
+  coupledFields.forEach((group, i) => {
+    for (const field of group) {
+      if (!fieldInConfig(field, configKeys, stateConfig)) {
+        issues.push({
+          type: "coupled_unknown_field",
+          severity: "error",
+          field: `coupledFields[${i}]`,
+          message: `Coupled field "${field}" is not in the state config.`,
+          suggestion: `Use a declared state field. Known fields: ${[...configKeys].join(", ")}`
+        });
+      }
+    }
+  });
+  return issues;
+}
+
+// tools/verify/src/config/parser.ts
 class ConfigValidator {
   issues = [];
   validate(configPath) {
@@ -4032,6 +4234,8 @@ class ConfigValidator {
     if (config.subsystems) {
       this.validateSubsystems(config.subsystems, config.state, config.messages);
     }
+    this.issues.push(...validateCapabilities(config.capabilities, config.state));
+    this.issues.push(...validateCoupledFields(config.coupledFields, config.state));
   }
   findNullPlaceholders(obj, path2) {
     if (obj === null || obj === undefined) {
@@ -7858,7 +8062,7 @@ function displayExpressionWarnings(result) {
 function displayMeshOrPeerSignalWarnings(analysis, declaredMeshDocs) {
   const findings = computeMeshOrPeerSignalFindings(analysis, declaredMeshDocs);
   if (findings.length === 0)
-    return;
+    return 0;
   const hasUndeclaredMesh = findings.some((f) => f.signalKind === "mesh");
   const hasPeer = findings.some((f) => f.signalKind === "peer");
   console.log(color(`
@@ -7881,6 +8085,61 @@ function displayMeshOrPeerSignalWarnings(analysis, declaredMeshDocs) {
     console.log(color(`      at ${f.location.file}:${f.location.line}`, COLORS.gray));
     console.log();
   }
+  return findings.length;
+}
+function isStrictMode() {
+  return process.argv.includes("--strict") || process.env.POLLY_VERIFY_STRICT === "1";
+}
+function displayModelCoverage(report) {
+  const { unwrittenFields, unconstrainedMutators, fieldCoverage } = report;
+  if (unwrittenFields.length === 0 && unconstrainedMutators.length === 0) {
+    console.log(color(`✓ Model coverage: all ${fieldCoverage.length} declared field(s) written by a modelled handler`, COLORS.green));
+    console.log();
+    return;
+  }
+  if (unwrittenFields.length > 0) {
+    console.log(color(`
+⚠️  ${unwrittenFields.length} declared state field(s) written by NO modelled handler (polly#160):`, COLORS.yellow));
+    for (const f of unwrittenFields) {
+      console.log(color(`   • ${f}`, COLORS.yellow));
+    }
+    console.log(color("   The model carries a variable no transition can change. Either it is dead", COLORS.gray));
+    console.log(color("   state (drop it from the verified surface) or its mutating path was never", COLORS.gray));
+    console.log(color("   modelled — the omission class both TLC and mutation testing miss.", COLORS.gray));
+    console.log();
+  }
+  if (unconstrainedMutators.length > 0) {
+    console.log(color(`ℹ️  ${unconstrainedMutators.length} handler(s) mutate declared state with no ensures() postcondition:`, COLORS.gray));
+    for (const m of unconstrainedMutators) {
+      console.log(color(`   • ${m.handler} writes {${m.fields.join(", ")}} — ${m.location.file}:${m.location.line}`, COLORS.gray));
+    }
+    console.log(color("   The checker explores these transitions but asserts nothing about their effect.", 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);
+  displayModelCoverage(coverage);
+  if (!isStrictMode())
+    return;
+  const reasons = strictCoverageReasons2(coverage, meshFindingCount);
+  if (reasons.length === 0) {
+    console.log(color("✓ Strict mode: model coverage complete", COLORS.green));
+    console.log();
+    return;
+  }
+  console.log(color(`❌ Strict mode: model coverage incomplete
+`, COLORS.red));
+  for (const reason of reasons) {
+    console.log(color(`   • ${reason}`, COLORS.red));
+  }
+  console.log();
+  console.log(color("   --strict fails closed on these so an unmodelled path cannot pass with a", COLORS.gray));
+  console.log(color("   green check. Re-run without --strict to treat them as warnings.", COLORS.gray));
+  console.log();
+  process.exit(1);
 }
 async function verifyCommand() {
   const configPath = path4.join(process.cwd(), "specs", "verification.config.ts");
@@ -7929,6 +8188,14 @@ Stack trace:`, COLORS.gray));
     process.exit(1);
   }
 }
+function getMeshDocIds(config) {
+  if (typeof config !== "object" || config === null || !("mesh" in config))
+    return [];
+  const mesh = config.mesh;
+  if (typeof mesh !== "object" || mesh === null)
+    return [];
+  return Object.keys(mesh);
+}
 function getTimeout(config) {
   return config.verification?.timeout ?? 0;
 }
@@ -7941,6 +8208,28 @@ function getMaxDepth(config) {
   }
   return;
 }
+async function runCoupledFieldsLint(config, analysis) {
+  const groups = config.coupledFields ?? [];
+  if (groups.length === 0)
+    return;
+  const { checkCoupledFields: checkCoupledFields2 } = await Promise.resolve().then(() => exports_coupled_fields);
+  const result = checkCoupledFields2(groups, analysis.handlers);
+  if (result.valid) {
+    console.log(color("✓ Coupled fields: verified (no partial-subset writes)", COLORS.green));
+    console.log();
+    return;
+  }
+  console.log(color(`⚠️  Coupled-field violations detected:
+`, COLORS.yellow));
+  for (const v of result.violations) {
+    console.log(color(`   • Handler "${v.handler}" writes {${v.written.join(", ")}} but not {${v.missing.join(", ")}} of coupled group {${v.group.join(", ")}}`, COLORS.yellow));
+  }
+  console.log();
+  console.log(color("   These fields are declared to move together; a capability granted without its", COLORS.yellow));
+  console.log(color("   precondition is a likely cause. Co-write the full group in each handler, or model", COLORS.yellow));
+  console.log(color("   the relationship with a `capabilities` invariant.", COLORS.yellow));
+  console.log();
+}
 async function runFullVerification(configPath) {
   const config = await loadVerificationConfig(configPath);
   const analysis = await runCodebaseAnalysis();
@@ -7951,8 +8240,10 @@ async function runFullVerification(configPath) {
   if (exprValidation.warnings.length > 0) {
     displayExpressionWarnings(exprValidation);
   }
-  const declaredMeshDocs = new Set(Object.keys(typedConfig.mesh ?? {}));
-  displayMeshOrPeerSignalWarnings(typedAnalysis, declaredMeshDocs);
+  const declaredMeshDocs = new Set(getMeshDocIds(typedConfig));
+  const meshFindingCount = displayMeshOrPeerSignalWarnings(typedAnalysis, declaredMeshDocs);
+  await runCoupledFieldsLint(typedConfig, typedAnalysis);
+  await runModelCoverage(typedConfig, typedAnalysis, meshFindingCount);
   if (typedConfig.subsystems && Object.keys(typedConfig.subsystems).length > 0) {
     await runSubsystemVerification(typedConfig, typedAnalysis);
     return;
@@ -8222,8 +8513,7 @@ function findMeshSeedSpecDir() {
   return null;
 }
 async function runMeshSeedGuard(docker, specDir, config) {
-  const mesh = config.mesh;
-  if (!mesh || Object.keys(mesh).length === 0)
+  if (getMeshDocIds(config).length === 0)
     return;
   const sourceDir = findMeshSeedSpecDir();
   if (!sourceDir) {
@@ -8330,6 +8620,11 @@ ${color("Commands:", COLORS.blue)}
   ${color("bun verify", COLORS.green)}
     Run verification (validates config, generates specs, runs TLC)
 
+  ${color("bun verify --strict", COLORS.green)}
+    Fail closed (non-zero exit) on model-coverage gaps: a declared state
+    field no handler writes, or an unverified $meshState/$peerState predicate.
+    Also via ${color("POLLY_VERIFY_STRICT=1", COLORS.yellow)}.
+
   ${color("bun verify --setup", COLORS.green)}
     Analyze codebase and generate configuration file
 
@@ -8393,4 +8688,4 @@ main().catch((error) => {
   process.exit(1);
 });
 
-//# debugId=A59978709BAED66964756E2164756E21
+//# debugId=9530CFE43867B27164756E2164756E21