@fairfox/polly 0.90.0 → 0.91.0

package/dist/tools/verify/src/config.d.ts

@@ -22,6 +22,34 @@ interface CustomTLAPath {
 }
 interface LegacyVerificationConfig {
     state: Record<string, unknown>;
+    /**
+     * polly#185: the contexts this project actually has, emitted as the `.cfg`'s
+     * `Contexts` set.
+     *
+     * Every generated model replicates application state across the set and
+     * quantifies each send over `|Contexts| * (2^|Contexts| - 1)` source/target
+     * pairs, so its size is the cheapest term in the state space to cut.
+     * Measured on a two-handler model at `maxInFlight: 1`: 38,464 distinct
+     * states at three contexts, 368 at one.
+     *
+     * Names become TLA+ model values, so each must sanitise to
+     * `[A-Za-z_][A-Za-z0-9_]*`. Omit the key to keep the browser-extension
+     * default `["background", "content", "popup"]`.
+     *
+     * A single context makes every send a self-send, and disables
+     * `PropagateMeshOp` (which requires two distinct contexts) — so a `mesh`
+     * block wants at least two.
+     *
+     * @example
+     * ```ts
+     * defineVerification({
+     *   contexts: ["server", "client"],
+     *   state: { ready: { type: "boolean" } },
+     *   messages: { maxInFlight: 1 },
+     * });
+     * ```
+     */
+    contexts?: string[];
     /**
      * polly#117: optional mesh-document declarations. When present, each
      * key names a `$meshState` document and its value declares the
@@ -114,6 +142,34 @@ interface LegacyVerificationConfig {
 interface AdapterVerificationConfig {
     adapter: unknown;
     state: Record<string, unknown>;
+    /**
+     * polly#185: the contexts this project actually has, emitted as the `.cfg`'s
+     * `Contexts` set.
+     *
+     * Every generated model replicates application state across the set and
+     * quantifies each send over `|Contexts| * (2^|Contexts| - 1)` source/target
+     * pairs, so its size is the cheapest term in the state space to cut.
+     * Measured on a two-handler model at `maxInFlight: 1`: 38,464 distinct
+     * states at three contexts, 368 at one.
+     *
+     * Names become TLA+ model values, so each must sanitise to
+     * `[A-Za-z_][A-Za-z0-9_]*`. Omit the key to keep the browser-extension
+     * default `["background", "content", "popup"]`.
+     *
+     * A single context makes every send a self-send, and disables
+     * `PropagateMeshOp` (which requires two distinct contexts) — so a `mesh`
+     * block wants at least two.
+     *
+     * @example
+     * ```ts
+     * defineVerification({
+     *   contexts: ["server", "client"],
+     *   state: { ready: { type: "boolean" } },
+     *   messages: { maxInFlight: 1 },
+     * });
+     * ```
+     */
+    contexts?: string[];
     bounds?: {
         maxInFlight?: number;
         [key: string]: unknown;

package/dist/tools/verify/src/config.js.map

@@ -3,9 +3,9 @@
   "sources": ["../tools/verify/src/primitives/index.ts", "../tools/verify/src/config.ts"],
   "sourcesContent": [
     "// Verification primitives for formal verification\n// These are runtime no-ops but extracted during verification\n\n/**\n * Assert a precondition that must be true when the handler executes.\n *\n * In production: No-op (compiled away)\n * In verification: Translated to TLA+ assertion\n *\n * @example\n * messageBus.on(\"USER_LOGIN\", (payload) => {\n *   requires(state.user.loggedIn === false, \"User must not be logged in\")\n *   state.user.loggedIn = true\n * })\n */\nexport function requires(condition: boolean, message?: string): void {\n  // Runtime no-op - only used during verification\n  // Condition and message are checked during static analysis only\n  void condition;\n  void message;\n}\n\n/**\n * Assert a postcondition that must be true after the handler completes.\n *\n * In production: No-op (compiled away)\n * In verification: Translated to TLA+ assertion\n *\n * @example\n * messageBus.on(\"USER_LOGIN\", (payload) => {\n *   state.user.loggedIn = true\n *   ensures(state.user.loggedIn === true, \"User must be logged in\")\n * })\n */\nexport function ensures(condition: boolean, message?: string): void {\n  // Runtime no-op - only used during verification\n  // Condition and message are checked during static analysis only\n  void condition;\n  void message;\n}\n\n/**\n * Define a global invariant that must always hold.\n *\n * In production: No-op (compiled away)\n * In verification: Translated to TLA+ invariant\n *\n * @example\n * invariant(\"UserIdConsistent\", () =>\n *   state.user.loggedIn === false || state.user.id !== null\n * )\n */\nexport function invariant(_name: string, condition: () => boolean): void {\n  // Runtime no-op - only used during verification\n  // Name and condition are checked during static analysis only\n  void condition;\n}\n\n/**\n * Assert that a value is within a valid range.\n *\n * @example\n * requires(inRange(todoCount, 0, 100), \"Todo count must be 0-100\")\n */\nexport function inRange(value: number, min: number, max: number): boolean {\n  return value >= min && value <= max;\n}\n\n/**\n * Assert that a value is one of the allowed values.\n *\n * @example\n * requires(oneOf(state.user.role, [\"admin\", \"user\"]), \"Role must be admin or user\")\n */\nexport function oneOf<T>(value: T, allowed: T[]): boolean {\n  return allowed.includes(value);\n}\n\n/**\n * Assert that an array has a specific length constraint.\n *\n * @example\n * requires(hasLength(state.todos, { max: 10 }), \"Too many todos\")\n */\nexport function hasLength(array: unknown[], constraint: { min?: number; max?: number }): boolean {\n  if (constraint.min !== undefined && array.length < constraint.min) return false;\n  if (constraint.max !== undefined && array.length > constraint.max) return false;\n  return true;\n}\n\n/**\n * Declare state-level constraints for verification and optional runtime checking.\n * Maps message types to preconditions on state fields.\n *\n * The parser automatically wires these constraints to handlers during verification.\n * Optionally, constraints can be enforced at runtime by passing `{ runtime: true }`.\n *\n * @example\n * // Verification only (TLA+ generation)\n * const state = { loggedIn: false };\n *\n * $constraints(\"loggedIn\", {\n *   USER_LOGOUT: { requires: \"state.loggedIn === true\", message: \"Must be logged in\" },\n *   BOOKMARK_ADD: { requires: \"state.loggedIn === true\", message: \"Must be logged in\" },\n * });\n *\n * @example\n * // Runtime enforcement (function predicates)\n * $constraints(\"loggedIn\", {\n *   USER_LOGOUT: {\n *     requires: (state) => state.loggedIn === true,\n *     message: \"Must be logged in to logout\"\n *   },\n * }, { runtime: true });\n */\nexport function $constraints(\n  stateField: string,\n  constraints: Record<\n    string,\n    {\n      requires?: string | ((state: unknown) => boolean);\n      ensures?: string | ((state: unknown) => boolean);\n      message?: string;\n    }\n  >,\n  options?: { runtime?: boolean }\n): void {\n  // Register constraints for runtime checking if enabled\n  if (options?.runtime) {\n    // Import dynamically to avoid circular dependencies\n    // This is safe because it only happens at runtime, not during static analysis\n    // @ts-expect-error - Dynamic import path resolves correctly at runtime\n    import(\"../../../src/shared/lib/constraints.js\")\n      .then(({ registerConstraints }) => {\n        registerConstraints(stateField, constraints);\n      })\n      .catch(() => {\n        // Silently ignore - constraints module may not be available during static analysis\n      });\n  }\n\n  // For verification: Still a no-op at runtime\n  // Parser extracts these and wires them to TLA+ handlers\n}\n\n/**\n * Declare a global state constraint that prunes structurally impossible states.\n *\n * In production: No-op (compiled away)\n * In verification: Translated to TLC CONSTRAINT clause, discarding states\n * that violate the predicate from the exploration queue entirely.\n *\n * Unlike `invariant()` (which checks but still explores), `stateConstraint()`\n * prevents the model checker from ever reaching the pruned states.\n *\n * @example\n * stateConstraint(\"LeaderRequiresConnection\", () =>\n *   !connectionState.value.isLeader || connectionState.value.status === \"connected\"\n * )\n */\nexport function stateConstraint(\n  name: string,\n  predicate: () => boolean,\n  options?: { message?: string }\n): void {\n  void name;\n  void predicate;\n  void options;\n}\n\n/**\n * Cross-peer universal quantifier for use inside `requires` and\n * `ensures` predicates. The runtime is a no-op that simply runs the\n * predicate against a single dummy context (so the assertion never\n * triggers at runtime); the verifier recognizes the wrapper in\n * predicate source and emits a `\\A peer \\in Contexts \\ {ctx} : (...)`\n * clause that asks TLC to check the inner predicate against every\n * other context.\n *\n * @example\n * ensures(\n *   forAllPeers(peer => peer.todos.value.length === todos.value.length),\n *   \"every peer agrees on todo count\"\n * );\n */\nexport function forAllPeers<TPeer>(predicate: (peer: TPeer) => boolean): boolean {\n  void predicate;\n  return true;\n}\n\n/**\n * Cross-peer existential quantifier for use inside `requires` and\n * `ensures` predicates. Runtime no-op; the verifier emits a\n * `\\E peer \\in Contexts \\ {ctx} : (...)` clause.\n *\n * @example\n * ensures(\n *   somePeer(peer => peer.user.value.loggedIn === true),\n *   \"at least one peer has a logged-in user\"\n * );\n */\nexport function somePeer<TPeer>(predicate: (peer: TPeer) => boolean): boolean {\n  void predicate;\n  return true;\n}\n\n// Re-export for convenience\nexport const verify = {\n  requires,\n  ensures,\n  invariant,\n  inRange,\n  oneOf,\n  hasLength,\n  $constraints,\n  stateConstraint,\n  forAllPeers,\n  somePeer,\n};\n",
-    "// Configuration Helper for @fairfox/polly/verify\n//\n// Lightweight entry point for user configuration files.\n// Does NOT include heavy dependencies (ts-morph, analysis, etc.)\n// which are only needed by the CLI tool.\n\n// Configuration Types (inlined to avoid heavy dependencies)\n\n// polly#160: a directional capability whose grant requires a precondition.\n// Desugars to a TLA+ safety invariant `(enabledBy) => (requires)`. enabledBy /\n// requires are TS boolean expressions in the requires()/ensures() dialect\n// referencing state via `state.` / signal `.value` form (e.g. \"state.authReady\").\n// Inlined here (like SubsystemConfig) so this authoring entry point stays\n// dependency-light; the canonical type is CapabilityConfig in config/types.ts.\ninterface CapabilityConfig {\n  name: string;\n  enabledBy: string;\n  requires: string;\n  message?: string;\n}\n\n// Subsystem configuration for compositional verification\ninterface SubsystemConfig {\n  state: string[]; // Field names from parent state config\n  handlers: string[]; // Message type names\n  // Per-subsystem message bounds; override messages.maxInFlight and merge\n  // into messages.perMessageBounds for this subsystem only.\n  bounds?: {\n    maxInFlight?: number;\n    perMessageBounds?: Record<string, number>;\n  };\n  /** polly#171: check message-resolution liveness for this subsystem only. */\n  liveness?: boolean;\n}\n\n// Point a subsystem's reachability witnesses at a hand-written TLA+ spec instead\n// of the generated UserApp_<subsystem>. Inlined here (like SubsystemConfig) to\n// keep this authoring entry point dependency-light; canonical type is\n// CustomTLAPath in config/types.ts.\ninterface CustomTLAPath {\n  tla: string; // path (relative to cwd) to the hand-written .tla the witness EXTENDS\n  cfg: string; // path (relative to cwd) to its .cfg\n  module?: string; // module to EXTEND; defaults to the MODULE name parsed from `tla`\n  fields?: Record<string, string>; // BDD field name → this spec's TLA+ variable name\n}\n\n// Legacy verification configuration\ninterface LegacyVerificationConfig {\n  state: Record<string, unknown>;\n  /**\n   * polly#117: optional mesh-document declarations. When present, each\n   * key names a `$meshState` document and its value declares the\n   * field-level state schema for that document. The verifier emits a\n   * separate slot in `contextStates[ctx].mesh[<docId>]` for these\n   * fields and adds a `PropagateMeshOp` action that allows the doc's\n   * value on one context to flow to another — modelling Automerge\n   * sync between peers. Mesh references inside `forAllPeers` quantifiers\n   * route through this slot so cross-peer convergence claims are\n   * actually checked.\n   *\n   * @example\n   * ```ts\n   * defineVerification({\n   *   state: { localCounter: { type: \"number\", min: 0, max: 3 } },\n   *   mesh: {\n   *     todos: {\n   *       entries: { type: \"enum\", values: [\"empty\", \"one\", \"many\"] },\n   *     },\n   *   },\n   *   messages: { maxInFlight: 2 },\n   * });\n   * ```\n   */\n  mesh?: Record<string, Record<string, unknown>>;\n  messages: {\n    // Basic bounds\n    maxInFlight?: number;\n    maxTabs?: number;\n    maxClients?: number;\n    maxRenderers?: number;\n    maxWorkers?: number;\n    maxContexts?: number;\n\n    // Tier 1 Optimizations (no precision loss)\n    include?: string[]; // Only verify these message types\n    exclude?: string[]; // Exclude these message types (mutually exclusive with include)\n    symmetry?: string[][]; // Groups of symmetric message types [[type1, type2], [type3, type4]]\n    perMessageBounds?: Record<string, number>; // Different maxInFlight per message type\n  };\n  onBuild?: \"warn\" | \"error\" | \"off\";\n  onRelease?: \"warn\" | \"error\" | \"off\";\n\n  // Verification engine options\n  verification?: {\n    timeout?: number; // Timeout in seconds (0 = no timeout)\n    workers?: number; // Number of TLC workers\n    /**\n     * polly#181: docker-style container memory ceiling for the TLC run, e.g.\n     * \"8g\". The JVM heap is sized under it, so a model too large for the\n     * ceiling ends with a TLC out-of-memory message instead of a silent kill.\n     * Unset uses a fixed default (4g), never unbounded.\n     */\n    memory?: string;\n  };\n\n  /**\n   * polly#171: check that nothing sent stays pending for ever.\n   *\n   * Off by default because it is expensive: it adds a temporal property and the\n   * routing fairness it needs, and TLC must then explore behaviours rather than\n   * only reachable states. Measured on an 11-subsystem consumer model, the full\n   * verify gate went from ~110s to ~512s.\n   *\n   * Every property the generator emits without this is a SAFETY property, and a\n   * safety property is true of a system that does nothing at all — so a spec in\n   * which routing has stopped verifies identically to one in which it works.\n   * Turn this on for the subsystems whose progress actually matters.\n   *\n   * LIMITATION, and it is Lamport's own warning (Specifying Systems 14.3.5):\n   * generated specs also declare a CONSTRAINT to bound the state space, and TLC\n   * prints \"Declaring state or action constraints during liveness checking is\n   * dangerous\" when both are present. A constraint truncates behaviours at its\n   * boundary, so a liveness violation reachable only beyond that boundary is not\n   * found. Treat a green liveness run as \"no wedge within the bounds\", not as a\n   * proof of progress — the same reading every bounded model-checking result\n   * deserves.\n   */\n  liveness?: boolean;\n\n  // Subsystem-scoped verification (compositional)\n  subsystems?: Record<string, SubsystemConfig>;\n\n  // Bind a subsystem's witnesses to a hand-written .tla/.cfg (read only by the\n  // --witness pass; a custom subsystem is skipped during generated-spec verify).\n  customTLAPaths?: Record<string, CustomTLAPath>;\n\n  // Tier 2 Optimizations (controlled approximations)\n  tier2?: {\n    // Temporal constraints: ordering requirements between messages\n    temporalConstraints?: Array<{\n      before: string; // Message type that must occur first\n      after: string; // Message type that must occur after\n      description?: string; // Human-readable description\n    }>;\n\n    // Bounded exploration: limit depth for specific scenarios\n    boundedExploration?: {\n      maxDepth?: number; // Maximum state depth to explore\n      criticalPaths?: string[][]; // Sequences of message types that must be fully explored\n    };\n  };\n\n  // polly#160: directional capability invariants + write-coupling lint groups\n  capabilities?: CapabilityConfig[];\n  coupledFields?: string[][];\n}\n\n// Adapter-based configuration (for future use)\ninterface AdapterVerificationConfig {\n  adapter: unknown; // Adapter interface not exported to avoid heavy deps\n  state: Record<string, unknown>;\n  bounds?: {\n    maxInFlight?: number;\n    [key: string]: unknown;\n  };\n  onBuild?: \"warn\" | \"error\" | \"off\";\n\n  // polly#160: directional capability invariants + write-coupling lint groups\n  capabilities?: CapabilityConfig[];\n  coupledFields?: string[][];\n}\n\n// Union type for both config formats\ntype UnifiedVerificationConfig = LegacyVerificationConfig | AdapterVerificationConfig;\n\n/**\n * Define verification configuration with type checking\n *\n * Used in generated verification.config.ts files.\n *\n * @example\n * ```typescript\n * import { defineVerification } from '@fairfox/polly/verify'\n *\n * export default defineVerification({\n *   state: {\n *     \"user.role\": { type: \"enum\", values: [\"admin\", \"user\", \"guest\"] },\n *   },\n *   messages: {\n *     maxInFlight: 6,\n *     maxTabs: 2,\n *   },\n * })\n * ```\n */\nexport function defineVerification<T extends UnifiedVerificationConfig>(config: T): T {\n  // Validate configuration structure\n  if (\"adapter\" in config) {\n    // New adapter-based format\n    if (!config.adapter) {\n      throw new Error(\"Configuration must include an adapter\");\n    }\n    if (!config.state) {\n      throw new Error(\"Configuration must include state bounds\");\n    }\n  } else if (\"messages\" in config) {\n    // Legacy format\n    if (!config.state) {\n      throw new Error(\"Configuration must include state bounds\");\n    }\n    if (!config.messages) {\n      throw new Error(\"Legacy configuration must include messages bounds\");\n    }\n  } else {\n    throw new Error(\n      \"Invalid configuration format. Must include either 'adapter' (new format) or 'messages' (legacy format)\"\n    );\n  }\n\n  return config;\n}\n\n// Re-export verification primitives for user code\nexport {\n  $constraints,\n  ensures,\n  forAllPeers,\n  hasLength,\n  inRange,\n  oneOf,\n  requires,\n  somePeer,\n  stateConstraint,\n} from \"./primitives/index.js\";\n"
+    "// Configuration Helper for @fairfox/polly/verify\n//\n// Lightweight entry point for user configuration files.\n// Does NOT include heavy dependencies (ts-morph, analysis, etc.)\n// which are only needed by the CLI tool.\n\n// Configuration Types (inlined to avoid heavy dependencies)\n\n// polly#160: a directional capability whose grant requires a precondition.\n// Desugars to a TLA+ safety invariant `(enabledBy) => (requires)`. enabledBy /\n// requires are TS boolean expressions in the requires()/ensures() dialect\n// referencing state via `state.` / signal `.value` form (e.g. \"state.authReady\").\n// Inlined here (like SubsystemConfig) so this authoring entry point stays\n// dependency-light; the canonical type is CapabilityConfig in config/types.ts.\ninterface CapabilityConfig {\n  name: string;\n  enabledBy: string;\n  requires: string;\n  message?: string;\n}\n\n// Subsystem configuration for compositional verification\ninterface SubsystemConfig {\n  state: string[]; // Field names from parent state config\n  handlers: string[]; // Message type names\n  // Per-subsystem message bounds; override messages.maxInFlight and merge\n  // into messages.perMessageBounds for this subsystem only.\n  bounds?: {\n    maxInFlight?: number;\n    perMessageBounds?: Record<string, number>;\n  };\n  /** polly#171: check message-resolution liveness for this subsystem only. */\n  liveness?: boolean;\n}\n\n// Point a subsystem's reachability witnesses at a hand-written TLA+ spec instead\n// of the generated UserApp_<subsystem>. Inlined here (like SubsystemConfig) to\n// keep this authoring entry point dependency-light; canonical type is\n// CustomTLAPath in config/types.ts.\ninterface CustomTLAPath {\n  tla: string; // path (relative to cwd) to the hand-written .tla the witness EXTENDS\n  cfg: string; // path (relative to cwd) to its .cfg\n  module?: string; // module to EXTEND; defaults to the MODULE name parsed from `tla`\n  fields?: Record<string, string>; // BDD field name → this spec's TLA+ variable name\n}\n\n// Legacy verification configuration\ninterface LegacyVerificationConfig {\n  state: Record<string, unknown>;\n  /**\n   * polly#185: the contexts this project actually has, emitted as the `.cfg`'s\n   * `Contexts` set.\n   *\n   * Every generated model replicates application state across the set and\n   * quantifies each send over `|Contexts| * (2^|Contexts| - 1)` source/target\n   * pairs, so its size is the cheapest term in the state space to cut.\n   * Measured on a two-handler model at `maxInFlight: 1`: 38,464 distinct\n   * states at three contexts, 368 at one.\n   *\n   * Names become TLA+ model values, so each must sanitise to\n   * `[A-Za-z_][A-Za-z0-9_]*`. Omit the key to keep the browser-extension\n   * default `[\"background\", \"content\", \"popup\"]`.\n   *\n   * A single context makes every send a self-send, and disables\n   * `PropagateMeshOp` (which requires two distinct contexts) — so a `mesh`\n   * block wants at least two.\n   *\n   * @example\n   * ```ts\n   * defineVerification({\n   *   contexts: [\"server\", \"client\"],\n   *   state: { ready: { type: \"boolean\" } },\n   *   messages: { maxInFlight: 1 },\n   * });\n   * ```\n   */\n  contexts?: string[];\n\n  /**\n   * polly#117: optional mesh-document declarations. When present, each\n   * key names a `$meshState` document and its value declares the\n   * field-level state schema for that document. The verifier emits a\n   * separate slot in `contextStates[ctx].mesh[<docId>]` for these\n   * fields and adds a `PropagateMeshOp` action that allows the doc's\n   * value on one context to flow to another — modelling Automerge\n   * sync between peers. Mesh references inside `forAllPeers` quantifiers\n   * route through this slot so cross-peer convergence claims are\n   * actually checked.\n   *\n   * @example\n   * ```ts\n   * defineVerification({\n   *   state: { localCounter: { type: \"number\", min: 0, max: 3 } },\n   *   mesh: {\n   *     todos: {\n   *       entries: { type: \"enum\", values: [\"empty\", \"one\", \"many\"] },\n   *     },\n   *   },\n   *   messages: { maxInFlight: 2 },\n   * });\n   * ```\n   */\n  mesh?: Record<string, Record<string, unknown>>;\n  messages: {\n    // Basic bounds\n    maxInFlight?: number;\n    maxTabs?: number;\n    maxClients?: number;\n    maxRenderers?: number;\n    maxWorkers?: number;\n    maxContexts?: number;\n\n    // Tier 1 Optimizations (no precision loss)\n    include?: string[]; // Only verify these message types\n    exclude?: string[]; // Exclude these message types (mutually exclusive with include)\n    symmetry?: string[][]; // Groups of symmetric message types [[type1, type2], [type3, type4]]\n    perMessageBounds?: Record<string, number>; // Different maxInFlight per message type\n  };\n  onBuild?: \"warn\" | \"error\" | \"off\";\n  onRelease?: \"warn\" | \"error\" | \"off\";\n\n  // Verification engine options\n  verification?: {\n    timeout?: number; // Timeout in seconds (0 = no timeout)\n    workers?: number; // Number of TLC workers\n    /**\n     * polly#181: docker-style container memory ceiling for the TLC run, e.g.\n     * \"8g\". The JVM heap is sized under it, so a model too large for the\n     * ceiling ends with a TLC out-of-memory message instead of a silent kill.\n     * Unset uses a fixed default (4g), never unbounded.\n     */\n    memory?: string;\n  };\n\n  /**\n   * polly#171: check that nothing sent stays pending for ever.\n   *\n   * Off by default because it is expensive: it adds a temporal property and the\n   * routing fairness it needs, and TLC must then explore behaviours rather than\n   * only reachable states. Measured on an 11-subsystem consumer model, the full\n   * verify gate went from ~110s to ~512s.\n   *\n   * Every property the generator emits without this is a SAFETY property, and a\n   * safety property is true of a system that does nothing at all — so a spec in\n   * which routing has stopped verifies identically to one in which it works.\n   * Turn this on for the subsystems whose progress actually matters.\n   *\n   * LIMITATION, and it is Lamport's own warning (Specifying Systems 14.3.5):\n   * generated specs also declare a CONSTRAINT to bound the state space, and TLC\n   * prints \"Declaring state or action constraints during liveness checking is\n   * dangerous\" when both are present. A constraint truncates behaviours at its\n   * boundary, so a liveness violation reachable only beyond that boundary is not\n   * found. Treat a green liveness run as \"no wedge within the bounds\", not as a\n   * proof of progress — the same reading every bounded model-checking result\n   * deserves.\n   */\n  liveness?: boolean;\n\n  // Subsystem-scoped verification (compositional)\n  subsystems?: Record<string, SubsystemConfig>;\n\n  // Bind a subsystem's witnesses to a hand-written .tla/.cfg (read only by the\n  // --witness pass; a custom subsystem is skipped during generated-spec verify).\n  customTLAPaths?: Record<string, CustomTLAPath>;\n\n  // Tier 2 Optimizations (controlled approximations)\n  tier2?: {\n    // Temporal constraints: ordering requirements between messages\n    temporalConstraints?: Array<{\n      before: string; // Message type that must occur first\n      after: string; // Message type that must occur after\n      description?: string; // Human-readable description\n    }>;\n\n    // Bounded exploration: limit depth for specific scenarios\n    boundedExploration?: {\n      maxDepth?: number; // Maximum state depth to explore\n      criticalPaths?: string[][]; // Sequences of message types that must be fully explored\n    };\n  };\n\n  // polly#160: directional capability invariants + write-coupling lint groups\n  capabilities?: CapabilityConfig[];\n  coupledFields?: string[][];\n}\n\n// Adapter-based configuration (for future use)\ninterface AdapterVerificationConfig {\n  adapter: unknown; // Adapter interface not exported to avoid heavy deps\n  state: Record<string, unknown>;\n  /**\n   * polly#185: the contexts this project actually has, emitted as the `.cfg`'s\n   * `Contexts` set.\n   *\n   * Every generated model replicates application state across the set and\n   * quantifies each send over `|Contexts| * (2^|Contexts| - 1)` source/target\n   * pairs, so its size is the cheapest term in the state space to cut.\n   * Measured on a two-handler model at `maxInFlight: 1`: 38,464 distinct\n   * states at three contexts, 368 at one.\n   *\n   * Names become TLA+ model values, so each must sanitise to\n   * `[A-Za-z_][A-Za-z0-9_]*`. Omit the key to keep the browser-extension\n   * default `[\"background\", \"content\", \"popup\"]`.\n   *\n   * A single context makes every send a self-send, and disables\n   * `PropagateMeshOp` (which requires two distinct contexts) — so a `mesh`\n   * block wants at least two.\n   *\n   * @example\n   * ```ts\n   * defineVerification({\n   *   contexts: [\"server\", \"client\"],\n   *   state: { ready: { type: \"boolean\" } },\n   *   messages: { maxInFlight: 1 },\n   * });\n   * ```\n   */\n  contexts?: string[];\n\n  bounds?: {\n    maxInFlight?: number;\n    [key: string]: unknown;\n  };\n  onBuild?: \"warn\" | \"error\" | \"off\";\n\n  // polly#160: directional capability invariants + write-coupling lint groups\n  capabilities?: CapabilityConfig[];\n  coupledFields?: string[][];\n}\n\n// Union type for both config formats\ntype UnifiedVerificationConfig = LegacyVerificationConfig | AdapterVerificationConfig;\n\n/**\n * Define verification configuration with type checking\n *\n * Used in generated verification.config.ts files.\n *\n * @example\n * ```typescript\n * import { defineVerification } from '@fairfox/polly/verify'\n *\n * export default defineVerification({\n *   state: {\n *     \"user.role\": { type: \"enum\", values: [\"admin\", \"user\", \"guest\"] },\n *   },\n *   messages: {\n *     maxInFlight: 6,\n *     maxTabs: 2,\n *   },\n * })\n * ```\n */\nexport function defineVerification<T extends UnifiedVerificationConfig>(config: T): T {\n  // Validate configuration structure\n  if (\"adapter\" in config) {\n    // New adapter-based format\n    if (!config.adapter) {\n      throw new Error(\"Configuration must include an adapter\");\n    }\n    if (!config.state) {\n      throw new Error(\"Configuration must include state bounds\");\n    }\n  } else if (\"messages\" in config) {\n    // Legacy format\n    if (!config.state) {\n      throw new Error(\"Configuration must include state bounds\");\n    }\n    if (!config.messages) {\n      throw new Error(\"Legacy configuration must include messages bounds\");\n    }\n  } else {\n    throw new Error(\n      \"Invalid configuration format. Must include either 'adapter' (new format) or 'messages' (legacy format)\"\n    );\n  }\n\n  return config;\n}\n\n// Re-export verification primitives for user code\nexport {\n  $constraints,\n  ensures,\n  forAllPeers,\n  hasLength,\n  inRange,\n  oneOf,\n  requires,\n  somePeer,\n  stateConstraint,\n} from \"./primitives/index.js\";\n"
   ],
-  "mappings": ";AAeO,SAAS,QAAQ,CAAC,WAAoB,SAAwB;AAmB9D,SAAS,OAAO,CAAC,WAAoB,SAAwB;AA8B7D,SAAS,OAAO,CAAC,OAAe,KAAa,KAAsB;AAAA,EACxE,OAAO,SAAS,OAAO,SAAS;AAAA;AAS3B,SAAS,KAAQ,CAAC,OAAU,SAAuB;AAAA,EACxD,OAAO,QAAQ,SAAS,KAAK;AAAA;AASxB,SAAS,SAAS,CAAC,OAAkB,YAAqD;AAAA,EAC/F,IAAI,WAAW,QAAQ,aAAa,MAAM,SAAS,WAAW;AAAA,IAAK,OAAO;AAAA,EAC1E,IAAI,WAAW,QAAQ,aAAa,MAAM,SAAS,WAAW;AAAA,IAAK,OAAO;AAAA,EAC1E,OAAO;AAAA;AA4BF,SAAS,YAAY,CAC1B,YACA,aAQA,SACM;AAAA,EAEN,IAAI,SAAS,SAAS;AAAA,IAIb,iDACJ,KAAK,GAAG,0BAA0B;AAAA,MACjC,oBAAoB,YAAY,WAAW;AAAA,KAC5C,EACA,MAAM,MAAM,EAEZ;AAAA,EACL;AAAA;AAqBK,SAAS,eAAe,CAC7B,MACA,WACA,SACM;AAqBD,SAAS,WAAkB,CAAC,WAA8C;AAAA,EAE/E,OAAO;AAAA;AAcF,SAAS,QAAe,CAAC,WAA8C;AAAA,EAE5E,OAAO;AAAA;;;ACRF,SAAS,kBAAuD,CAAC,QAAc;AAAA,EAEpF,IAAI,aAAa,QAAQ;AAAA,IAEvB,IAAI,CAAC,OAAO,SAAS;AAAA,MACnB,MAAM,IAAI,MAAM,uCAAuC;AAAA,IACzD;AAAA,IACA,IAAI,CAAC,OAAO,OAAO;AAAA,MACjB,MAAM,IAAI,MAAM,yCAAyC;AAAA,IAC3D;AAAA,EACF,EAAO,SAAI,cAAc,QAAQ;AAAA,IAE/B,IAAI,CAAC,OAAO,OAAO;AAAA,MACjB,MAAM,IAAI,MAAM,yCAAyC;AAAA,IAC3D;AAAA,IACA,IAAI,CAAC,OAAO,UAAU;AAAA,MACpB,MAAM,IAAI,MAAM,mDAAmD;AAAA,IACrE;AAAA,EACF,EAAO;AAAA,IACL,MAAM,IAAI,MACR,wGACF;AAAA;AAAA,EAGF,OAAO;AAAA;",
+  "mappings": ";AAeO,SAAS,QAAQ,CAAC,WAAoB,SAAwB;AAmB9D,SAAS,OAAO,CAAC,WAAoB,SAAwB;AA8B7D,SAAS,OAAO,CAAC,OAAe,KAAa,KAAsB;AAAA,EACxE,OAAO,SAAS,OAAO,SAAS;AAAA;AAS3B,SAAS,KAAQ,CAAC,OAAU,SAAuB;AAAA,EACxD,OAAO,QAAQ,SAAS,KAAK;AAAA;AASxB,SAAS,SAAS,CAAC,OAAkB,YAAqD;AAAA,EAC/F,IAAI,WAAW,QAAQ,aAAa,MAAM,SAAS,WAAW;AAAA,IAAK,OAAO;AAAA,EAC1E,IAAI,WAAW,QAAQ,aAAa,MAAM,SAAS,WAAW;AAAA,IAAK,OAAO;AAAA,EAC1E,OAAO;AAAA;AA4BF,SAAS,YAAY,CAC1B,YACA,aAQA,SACM;AAAA,EAEN,IAAI,SAAS,SAAS;AAAA,IAIb,iDACJ,KAAK,GAAG,0BAA0B;AAAA,MACjC,oBAAoB,YAAY,WAAW;AAAA,KAC5C,EACA,MAAM,MAAM,EAEZ;AAAA,EACL;AAAA;AAqBK,SAAS,eAAe,CAC7B,MACA,WACA,SACM;AAqBD,SAAS,WAAkB,CAAC,WAA8C;AAAA,EAE/E,OAAO;AAAA;AAcF,SAAS,QAAe,CAAC,WAA8C;AAAA,EAE5E,OAAO;AAAA;;;ACkDF,SAAS,kBAAuD,CAAC,QAAc;AAAA,EAEpF,IAAI,aAAa,QAAQ;AAAA,IAEvB,IAAI,CAAC,OAAO,SAAS;AAAA,MACnB,MAAM,IAAI,MAAM,uCAAuC;AAAA,IACzD;AAAA,IACA,IAAI,CAAC,OAAO,OAAO;AAAA,MACjB,MAAM,IAAI,MAAM,yCAAyC;AAAA,IAC3D;AAAA,EACF,EAAO,SAAI,cAAc,QAAQ;AAAA,IAE/B,IAAI,CAAC,OAAO,OAAO;AAAA,MACjB,MAAM,IAAI,MAAM,yCAAyC;AAAA,IAC3D;AAAA,IACA,IAAI,CAAC,OAAO,UAAU;AAAA,MACpB,MAAM,IAAI,MAAM,mDAAmD;AAAA,IACrE;AAAA,EACF,EAAO;AAAA,IACL,MAAM,IAAI,MACR,wGACF;AAAA;AAAA,EAGF,OAAO;AAAA;",
   "debugId": "EB2A6F997258A60464756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairfox/polly",
-  "version": "0.90.0",
+  "version": "0.91.0",
   "private": false,
   "type": "module",
   "description": "Multi-execution-context framework with reactive state and cross-context messaging for Chrome extensions, PWAs, and worker-based applications",
@@ -181,6 +181,8 @@
     "@biomejs/biome": "2.4.14",
     "@stryker-mutator/api": "9.6.1",
     "@elysiajs/eden": "1.4.9",
+    "@preact/signals": "2.9.0",
+    "@preact/signals-core": "1.14.2",
     "@types/bun": "1.3.13",
     "@types/chrome": "0.1.40",
     "@types/pixelmatch": "5.2.6",
@@ -192,6 +194,7 @@
     "marked": "18.0.3",
     "pixelmatch": "7.2.0",
     "pngjs": "7.0.0",
+    "preact": "10.29.1",
     "puppeteer": "24.42.0",
     "tweetnacl": "1.0.3",
     "typescript": "6.0.3"
@@ -202,15 +205,13 @@
   "dependencies": {
     "@cucumber/gherkin": "40.0.0",
     "@cucumber/messages": "33.0.2",
-    "@preact/signals": "2.9.0",
-    "@preact/signals-core": "1.14.2",
-    "preact": "10.29.1",
     "ts-morph": "28.0.0"
   },
   "peerDependencies": {
     "typescript": ">= 5.9.3",
     "preact": "^10.28.1",
     "@preact/signals": "^2.5.1",
+    "@preact/signals-core": "^1.14.0",
     "elysia": ">= 1.4.0",
     "@elysiajs/eden": ">= 1.2.0",
     "@automerge/automerge": ">= 3.2.0",