@fairfox/polly 0.16.0 → 0.17.0

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

@@ -61,4 +61,4 @@ type UnifiedVerificationConfig = LegacyVerificationConfig | AdapterVerificationC
  * ```
  */
 export declare function defineVerification<T extends UnifiedVerificationConfig>(config: T): T;
-export { $constraints, ensures, hasLength, inRange, oneOf, requires } from "./primitives/index.js";
+export { $constraints, ensures, hasLength, inRange, oneOf, requires, stateConstraint, } from "./primitives/index.js";

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

@@ -57,6 +57,7 @@ function $constraints(stateField, constraints, options) {
     }).catch(() => {});
   }
 }
+function stateConstraint(name, predicate, options) {}
 
 // tools/verify/src/config.ts
 function defineVerification(config) {
@@ -80,6 +81,7 @@ function defineVerification(config) {
   return config;
 }
 export {
+  stateConstraint,
   requires,
   oneOf,
   inRange,
@@ -89,4 +91,4 @@ export {
   $constraints
 };
 
-//# debugId=C9D97C5927FA335964756E2164756E21
+//# debugId=465F57F5AB1A6BBD64756E2164756E21

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

@@ -2,10 +2,10 @@
   "version": 3,
   "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// Re-export for convenience\nexport const verify = {\n  requires,\n  ensures,\n  invariant,\n  inRange,\n  oneOf,\n  hasLength,\n  $constraints,\n};\n",
-    "// ═══════════════════════════════════════════════════════════════\n// Configuration Helper for @fairfox/polly/verify\n// ═══════════════════════════════════════════════════════════════\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// ─────────────────────────────────────────────────────────────────\n// Configuration Types (inlined to avoid heavy dependencies)\n// ─────────────────────────────────────────────────────────────────\n\n// Legacy verification configuration\ninterface LegacyVerificationConfig {\n  state: 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\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\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\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 { $constraints, ensures, hasLength, inRange, oneOf, requires } from \"./primitives/index.js\";\n"
+    "// 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// Re-export for convenience\nexport const verify = {\n  requires,\n  ensures,\n  invariant,\n  inRange,\n  oneOf,\n  hasLength,\n  $constraints,\n  stateConstraint,\n};\n",
+    "// ═══════════════════════════════════════════════════════════════\n// Configuration Helper for @fairfox/polly/verify\n// ═══════════════════════════════════════════════════════════════\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// ─────────────────────────────────────────────────────────────────\n// Configuration Types (inlined to avoid heavy dependencies)\n// ─────────────────────────────────────────────────────────────────\n\n// Legacy verification configuration\ninterface LegacyVerificationConfig {\n  state: 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\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\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\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  hasLength,\n  inRange,\n  oneOf,\n  requires,\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;;;ACjDK,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": "C9D97C5927FA335964756E2164756E21",
+  "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;;;AC1ED,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": "465F57F5AB1A6BBD64756E2164756E21",
   "names": []
 }

package/dist/tools/verify/src/primitives/index.d.ts

@@ -92,6 +92,24 @@ export declare function $constraints(stateField: string, constraints: Record<str
 }>, options?: {
     runtime?: boolean;
 }): void;
+/**
+ * Declare a global state constraint that prunes structurally impossible states.
+ *
+ * In production: No-op (compiled away)
+ * In verification: Translated to TLC CONSTRAINT clause, discarding states
+ * that violate the predicate from the exploration queue entirely.
+ *
+ * Unlike `invariant()` (which checks but still explores), `stateConstraint()`
+ * prevents the model checker from ever reaching the pruned states.
+ *
+ * @example
+ * stateConstraint("LeaderRequiresConnection", () =>
+ *   !connectionState.value.isLeader || connectionState.value.status === "connected"
+ * )
+ */
+export declare function stateConstraint(name: string, predicate: () => boolean, options?: {
+    message?: string;
+}): void;
 export declare const verify: {
     requires: typeof requires;
     ensures: typeof ensures;
@@ -100,4 +118,5 @@ export declare const verify: {
     oneOf: typeof oneOf;
     hasLength: typeof hasLength;
     $constraints: typeof $constraints;
+    stateConstraint: typeof stateConstraint;
 };

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

@@ -1638,13 +1638,14 @@ class HandlerExtractor {
     const messageTypes = new Set;
     const invalidMessageTypes = new Set;
     const stateConstraints = [];
+    const globalStateConstraints = [];
     const verifiedStates = [];
     this.warnings = [];
     const allSourceFiles = this.project.getSourceFiles();
     const entryPoints = allSourceFiles.filter((f) => this.isWithinPackage(f.getFilePath()));
     this.debugLogSourceFiles(allSourceFiles, entryPoints);
     for (const entryPoint of entryPoints) {
-      this.analyzeFileAndImports(entryPoint, handlers, messageTypes, invalidMessageTypes, stateConstraints, verifiedStates);
+      this.analyzeFileAndImports(entryPoint, handlers, messageTypes, invalidMessageTypes, stateConstraints, globalStateConstraints, verifiedStates);
     }
     if (verifiedStates.length > 0) {
       if (process.env["POLLY_DEBUG"]) {
@@ -1674,11 +1675,12 @@ class HandlerExtractor {
       handlers,
       messageTypes,
       stateConstraints,
+      globalStateConstraints,
       verifiedStates,
       warnings: this.warnings
     };
   }
-  analyzeFileAndImports(sourceFile, handlers, messageTypes, invalidMessageTypes, stateConstraints, verifiedStates) {
+  analyzeFileAndImports(sourceFile, handlers, messageTypes, invalidMessageTypes, stateConstraints, globalStateConstraints, verifiedStates) {
     const filePath = sourceFile.getFilePath();
     if (this.analyzedFiles.has(filePath)) {
       return;
@@ -1692,6 +1694,8 @@ class HandlerExtractor {
     this.categorizeHandlerMessageTypes(fileHandlers, messageTypes, invalidMessageTypes);
     const fileConstraints = this.extractStateConstraintsFromFile(sourceFile);
     stateConstraints.push(...fileConstraints);
+    const fileGlobalConstraints = this.extractGlobalStateConstraintsFromFile(sourceFile);
+    globalStateConstraints.push(...fileGlobalConstraints);
     const fileVerifiedStates = this.extractVerifiedStatesFromFile(sourceFile);
     verifiedStates.push(...fileVerifiedStates);
     const importDeclarations = sourceFile.getImportDeclarations();
@@ -1705,7 +1709,7 @@ class HandlerExtractor {
           }
           continue;
         }
-        this.analyzeFileAndImports(importedFile, handlers, messageTypes, invalidMessageTypes, stateConstraints, verifiedStates);
+        this.analyzeFileAndImports(importedFile, handlers, messageTypes, invalidMessageTypes, stateConstraints, globalStateConstraints, verifiedStates);
       } else if (process.env["POLLY_DEBUG"]) {
         const specifier = importDecl.getModuleSpecifierValue();
         if (!specifier.startsWith("node:") && !this.isNodeModuleImport(specifier)) {
@@ -3040,6 +3044,81 @@ class HandlerExtractor {
     });
     return constraints;
   }
+  extractGlobalStateConstraintsFromFile(sourceFile) {
+    const constraints = [];
+    const filePath = sourceFile.getFilePath();
+    sourceFile.forEachDescendant((node) => {
+      const constraint = this.recognizeGlobalStateConstraint(node, filePath);
+      if (constraint) {
+        constraints.push(constraint);
+      }
+    });
+    return constraints;
+  }
+  recognizeGlobalStateConstraint(node, filePath) {
+    if (!Node4.isCallExpression(node)) {
+      return null;
+    }
+    const expression = node.getExpression();
+    if (!Node4.isIdentifier(expression)) {
+      return null;
+    }
+    const functionName = expression.getText();
+    if (functionName !== "stateConstraint") {
+      return null;
+    }
+    const args = node.getArguments();
+    if (args.length < 2) {
+      return null;
+    }
+    const nameArg = args[0];
+    if (!Node4.isStringLiteral(nameArg)) {
+      return null;
+    }
+    const name = nameArg.getLiteralValue();
+    const predicateArg = args[1];
+    if (!Node4.isArrowFunction(predicateArg)) {
+      return null;
+    }
+    const body = predicateArg.getBody();
+    let expressionText;
+    if (Node4.isBlock(body)) {
+      const returnStatement = body.getStatements().find((s) => Node4.isReturnStatement(s));
+      if (!returnStatement || !Node4.isReturnStatement(returnStatement)) {
+        return null;
+      }
+      const returnExpr = returnStatement.getExpression();
+      if (!returnExpr) {
+        return null;
+      }
+      expressionText = returnExpr.getText();
+    } else {
+      expressionText = body.getText();
+    }
+    let message;
+    if (args.length >= 3) {
+      const optionsArg = args[2];
+      if (Node4.isObjectLiteralExpression(optionsArg)) {
+        for (const prop of optionsArg.getProperties()) {
+          if (Node4.isPropertyAssignment(prop) && prop.getName() === "message") {
+            const value = prop.getInitializer();
+            if (value && Node4.isStringLiteral(value)) {
+              message = value.getLiteralValue();
+            }
+          }
+        }
+      }
+    }
+    return {
+      name,
+      expression: expressionText,
+      message,
+      location: {
+        file: filePath,
+        line: node.getStartLineNumber()
+      }
+    };
+  }
   recognizeStateConstraint(node, filePath) {
     if (!Node4.isCallExpression(node)) {
       return [];
@@ -5639,4 +5718,4 @@ main().catch((_error) => {
   process.exit(1);
 });
 
-//# debugId=E7AAE0901ACF898964756E2164756E21
+//# debugId=6E19C4E7D7F05D9564756E2164756E21