@fairfox/polly 0.83.0 → 0.85.0

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

@@ -12,6 +12,12 @@ interface SubsystemConfig {
         perMessageBounds?: Record<string, number>;
     };
 }
+interface CustomTLAPath {
+    tla: string;
+    cfg: string;
+    module?: string;
+    fields?: Record<string, string>;
+}
 interface LegacyVerificationConfig {
     state: Record<string, unknown>;
     /**
@@ -58,6 +64,7 @@ interface LegacyVerificationConfig {
         workers?: number;
     };
     subsystems?: Record<string, SubsystemConfig>;
+    customTLAPaths?: Record<string, CustomTLAPath>;
     tier2?: {
         temporalConstraints?: Array<{
             before: string;

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}\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\n  // Subsystem-scoped verification (compositional)\n  subsystems?: Record<string, SubsystemConfig>;\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}\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\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"
   ],
-  "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;;;ACxDF,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;;;ACzCF,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": "D9257AB1F243F69864756E2164756E21",
   "names": []
 }

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

@@ -1732,6 +1732,7 @@ class HandlerExtractor {
   warnings;
   currentFunctionParams = [];
   contextOverrides;
+  onSurfaceSpans = [];
   constructor(tsConfigPath, contextOverrides) {
     this.project = new Project3({
       tsConfigFilePath: tsConfigPath
@@ -1791,6 +1792,7 @@ class HandlerExtractor {
     const meshOrPeerSignals = [];
     const resources = [];
     this.warnings = [];
+    this.onSurfaceSpans = [];
     const allSourceFiles = this.project.getSourceFiles();
     const entryPoints = allSourceFiles.filter((f) => this.isWithinPackage(f.getFilePath()));
     this.debugLogSourceFiles(allSourceFiles, entryPoints);
@@ -1825,6 +1827,30 @@ class HandlerExtractor {
         continue;
       meshOrPeerSignals.push(...this.extractMeshOrPeerSignalsFromFile(sourceFile));
     }
+    const stateSignalNames = new Set;
+    for (const filePath of this.analyzedFiles) {
+      const sourceFile = this.project.getSourceFile(filePath);
+      if (!sourceFile)
+        continue;
+      for (const name of this.extractStateSignalVariableNames(sourceFile)) {
+        stateSignalNames.add(name);
+      }
+    }
+    for (const v of verifiedStates)
+      stateSignalNames.add(v.variableName);
+    for (const m of meshOrPeerSignals)
+      stateSignalNames.add(m.variableName);
+    const offSurfaceMutations = [];
+    if (stateSignalNames.size > 0) {
+      for (const filePath of this.analyzedFiles) {
+        if (!this.isOffSurfaceScannable(filePath))
+          continue;
+        const sourceFile = this.project.getSourceFile(filePath);
+        if (!sourceFile)
+          continue;
+        offSurfaceMutations.push(...this.findOffSurfaceMutations(sourceFile, stateSignalNames));
+      }
+    }
     this.debugLogExtractionResults(handlers.length, invalidMessageTypes.size);
     this.debugLogAnalysisStats(allSourceFiles.length, entryPoints.length);
     return {
@@ -1835,6 +1861,7 @@ class HandlerExtractor {
       verifiedStates,
       meshOrPeerSignals,
       resources,
+      offSurfaceMutations,
       warnings: this.warnings
     };
   }
@@ -2245,6 +2272,7 @@ class HandlerExtractor {
     return false;
   }
   extractAssignments(funcNode, assignments) {
+    this.recordOnSurfaceSpan(funcNode);
     funcNode.forEachDescendant((node) => {
       if (Node4.isBinaryExpression(node)) {
         this.extractBinaryExpressionAssignment(node, assignments);
@@ -3831,6 +3859,7 @@ class HandlerExtractor {
   }
   findStateMutationsInFunction(func, stateVarNames) {
     const mutations = [];
+    this.recordOnSurfaceSpan(func);
     func.forEachDescendant((node) => {
       if (!Node4.isBinaryExpression(node))
         return;
@@ -3860,6 +3889,140 @@ class HandlerExtractor {
     });
     return mutations;
   }
+  isOffSurfaceScannable(filePath) {
+    return !/(?:\.(?:test|spec|stories)\.[cm]?[jt]sx?$)|(?:\/(?:__tests__|tests|test|features|e2e|stories|__mocks__)\/)/i.test(filePath);
+  }
+  static STATE_SIGNAL_FACTORIES = new Set([
+    "$state",
+    "$sharedState",
+    "$syncedState",
+    "$persistedState",
+    "$meshState",
+    "$peerState"
+  ]);
+  extractStateSignalVariableNames(sourceFile) {
+    const names = [];
+    sourceFile.forEachDescendant((node) => {
+      if (!Node4.isCallExpression(node))
+        return;
+      const expr = node.getExpression();
+      if (!Node4.isIdentifier(expr))
+        return;
+      if (!HandlerExtractor.STATE_SIGNAL_FACTORIES.has(expr.getText()))
+        return;
+      const varName = this.getVariableNameFromParent(node);
+      if (varName)
+        names.push(varName);
+    });
+    return names;
+  }
+  recordOnSurfaceSpan(node) {
+    this.onSurfaceSpans.push({
+      file: node.getSourceFile().getFilePath(),
+      start: node.getStart(),
+      end: node.getEnd()
+    });
+  }
+  isWithinOnSurfaceSpan(file, pos) {
+    for (const span of this.onSurfaceSpans) {
+      if (span.file === file && pos >= span.start && pos <= span.end)
+        return true;
+    }
+    return false;
+  }
+  findOffSurfaceMutations(sourceFile, stateVarNames) {
+    const out = [];
+    const filePath = sourceFile.getFilePath();
+    sourceFile.forEachDescendant((node) => {
+      if (Node4.isBinaryExpression(node)) {
+        out.push(...this.offSurfaceWritesAt(node, stateVarNames, filePath));
+      }
+    });
+    return out;
+  }
+  offSurfaceWritesAt(node, stateVarNames, filePath) {
+    if (node.getOperatorToken().getText() !== "=")
+      return [];
+    const left = node.getLeft();
+    if (!Node4.isPropertyAccessExpression(left))
+      return [];
+    const match = this.matchVerifiedStateWrite(this.getPropertyPath(left), stateVarNames);
+    if (!match)
+      return [];
+    if (this.isWithinOnSurfaceSpan(filePath, left.getStart()))
+      return [];
+    const base = {
+      signalVariable: match.signal,
+      functionName: this.enclosingFunctionName(node),
+      filePath,
+      line: node.getStartLineNumber()
+    };
+    if (match.field !== undefined) {
+      return [{ field: `${match.signal}_${match.field}`, ...base }];
+    }
+    const fields = this.objectLiteralFieldNames(node.getRight());
+    if (fields.length === 0)
+      return [{ field: match.signal, ...base }];
+    return fields.map((f) => ({ field: `${match.signal}_${f}`, ...base }));
+  }
+  matchVerifiedStateWrite(path2, stateVarNames) {
+    for (const varName of stateVarNames) {
+      if (path2 === `${varName}.value`)
+        return { signal: varName };
+      const prefix = `${varName}.value.`;
+      if (path2.startsWith(prefix))
+        return { signal: varName, field: path2.substring(prefix.length) };
+    }
+    return null;
+  }
+  objectLiteralFieldNames(right) {
+    if (!Node4.isObjectLiteralExpression(right))
+      return [];
+    const names = [];
+    for (const prop of right.getProperties()) {
+      if (Node4.isPropertyAssignment(prop) || Node4.isShorthandPropertyAssignment(prop)) {
+        names.push(prop.getName());
+      }
+    }
+    return names;
+  }
+  enclosingFunctionName(node) {
+    let current = node.getParent();
+    while (current) {
+      const name = this.namedScope(current);
+      if (name !== null)
+        return name;
+      current = current.getParent();
+    }
+    return "<module>";
+  }
+  namedScope(node) {
+    if (Node4.isFunctionDeclaration(node)) {
+      return node.getName() ?? "<anonymous function>";
+    }
+    if (Node4.isMethodDeclaration(node)) {
+      const clsName = node.getFirstAncestorByKind(SyntaxKind.ClassDeclaration)?.getName();
+      const methodName = node.getName();
+      return clsName ? `${clsName}.${methodName}` : methodName;
+    }
+    if (Node4.isGetAccessorDeclaration(node) || Node4.isSetAccessorDeclaration(node)) {
+      return node.getName();
+    }
+    if (Node4.isArrowFunction(node) || Node4.isFunctionExpression(node)) {
+      return this.boundFunctionName(node) ?? null;
+    }
+    return null;
+  }
+  boundFunctionName(fn) {
+    const parent = fn.getParent();
+    if (!parent)
+      return;
+    if (Node4.isVariableDeclaration(parent))
+      return parent.getName();
+    if (Node4.isPropertyAssignment(parent))
+      return parent.getName();
+    return;
+  }
   functionNameToMessageType(funcName) {
     let name = funcName.replace(/^handle/, "").replace(/^on/, "").replace(/^set/, "Set").replace(/^update/, "Update").replace(/^do/, "");
     if (name.length > 0) {
@@ -6826,4 +6989,4 @@ main().catch((_error) => {
   process.exit(1);
 });
 
-//# debugId=FB3F999DCFFB1CAD64756E2164756E21
+//# debugId=4CA1C5520447E2E464756E2164756E21