@fairfox/polly 0.14.0 → 0.15.0

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

@@ -5502,21 +5502,45 @@ class HandlerExtractor {
     const messageTypes = new Set;
     const invalidMessageTypes = new Set;
     const stateConstraints = [];
+    const verifiedStates = [];
     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);
+      this.analyzeFileAndImports(entryPoint, handlers, messageTypes, invalidMessageTypes, stateConstraints, verifiedStates);
+    }
+    if (verifiedStates.length > 0) {
+      if (process.env["POLLY_DEBUG"]) {
+        console.log(`[DEBUG] Found ${verifiedStates.length} verified state(s), scanning for mutating functions...`);
+      }
+      for (const filePath of this.analyzedFiles) {
+        const sourceFile = this.project.getSourceFile(filePath);
+        if (!sourceFile)
+          continue;
+        const mutatingHandlers = this.findStateMutatingFunctions(sourceFile, verifiedStates);
+        for (const handler of mutatingHandlers) {
+          const exists = handlers.some((h) => h.messageType === handler.messageType && h.location.file === handler.location.file);
+          if (!exists) {
+            handlers.push(handler);
+            if (this.isValidTLAIdentifier(handler.messageType)) {
+              messageTypes.add(handler.messageType);
+            } else {
+              invalidMessageTypes.add(handler.messageType);
+            }
+          }
+        }
+      }
     }
     this.debugLogExtractionResults(handlers.length, invalidMessageTypes.size);
     this.debugLogAnalysisStats(allSourceFiles.length, entryPoints.length);
     return {
       handlers,
       messageTypes,
-      stateConstraints
+      stateConstraints,
+      verifiedStates
     };
   }
-  analyzeFileAndImports(sourceFile, handlers, messageTypes, invalidMessageTypes, stateConstraints) {
+  analyzeFileAndImports(sourceFile, handlers, messageTypes, invalidMessageTypes, stateConstraints, verifiedStates) {
     const filePath = sourceFile.getFilePath();
     if (this.analyzedFiles.has(filePath)) {
       return;
@@ -5530,6 +5554,8 @@ class HandlerExtractor {
     this.categorizeHandlerMessageTypes(fileHandlers, messageTypes, invalidMessageTypes);
     const fileConstraints = this.extractStateConstraintsFromFile(sourceFile);
     stateConstraints.push(...fileConstraints);
+    const fileVerifiedStates = this.extractVerifiedStatesFromFile(sourceFile);
+    verifiedStates.push(...fileVerifiedStates);
     const importDeclarations = sourceFile.getImportDeclarations();
     for (const importDecl of importDeclarations) {
       const importedFile = importDecl.getModuleSpecifierSourceFile();
@@ -5541,7 +5567,7 @@ class HandlerExtractor {
           }
           continue;
         }
-        this.analyzeFileAndImports(importedFile, handlers, messageTypes, invalidMessageTypes, stateConstraints);
+        this.analyzeFileAndImports(importedFile, handlers, messageTypes, invalidMessageTypes, stateConstraints, verifiedStates);
       } else if (process.env["POLLY_DEBUG"]) {
         const specifier = importDecl.getModuleSpecifierValue();
         if (!specifier.startsWith("node:") && !this.isNodeModuleImport(specifier)) {
@@ -5750,7 +5776,7 @@ class HandlerExtractor {
       return;
     }
     const valueMatch = fieldPath.match(/\.value\.(.+)$/);
-    if (valueMatch && valueMatch[1]) {
+    if (valueMatch?.[1]) {
       const field = valueMatch[1];
       const value = this.extractValue(right);
       if (value !== undefined) {
@@ -5808,7 +5834,7 @@ class HandlerExtractor {
       return fieldPath.substring(6);
     }
     const valueMatch = fieldPath.match(/\.value\.(.+)$/);
-    if (valueMatch && valueMatch[1]) {
+    if (valueMatch?.[1]) {
       return valueMatch[1];
     }
     return null;
@@ -6616,6 +6642,205 @@ class HandlerExtractor {
     }
     return results;
   }
+  extractVerifiedStatesFromFile(sourceFile) {
+    const verifiedStates = [];
+    const filePath = sourceFile.getFilePath();
+    sourceFile.forEachDescendant((node) => {
+      if (!Node4.isCallExpression(node))
+        return;
+      const stateInfo = this.recognizeVerifiedStateCall(node, filePath);
+      if (stateInfo) {
+        verifiedStates.push(stateInfo);
+      }
+    });
+    return verifiedStates;
+  }
+  recognizeVerifiedStateCall(node, filePath) {
+    if (!Node4.isCallExpression(node))
+      return null;
+    const expression = node.getExpression();
+    if (!Node4.isIdentifier(expression))
+      return null;
+    const funcName = expression.getText();
+    if (!["$sharedState", "$syncedState", "$persistedState"].includes(funcName)) {
+      return null;
+    }
+    const args = node.getArguments();
+    if (args.length < 2)
+      return null;
+    const optionsArg = args[2];
+    if (!optionsArg || !this.hasVerifyTrue(optionsArg))
+      return null;
+    const keyArg = args[0];
+    if (!keyArg || !Node4.isStringLiteral(keyArg))
+      return null;
+    const key = keyArg.getLiteralValue();
+    const variableName = this.getVariableNameFromParent(node) || key;
+    const initialValueArg = args[1];
+    const fields = initialValueArg ? this.extractFieldNames(initialValueArg) : [];
+    if (process.env["POLLY_DEBUG"]) {
+      console.log(`[DEBUG] Found verified state: ${variableName} (key: "${key}") with fields: [${fields.join(", ")}]`);
+    }
+    return {
+      key,
+      variableName,
+      filePath,
+      line: node.getStartLineNumber(),
+      fields
+    };
+  }
+  hasVerifyTrue(optionsNode) {
+    if (!Node4.isObjectLiteralExpression(optionsNode))
+      return false;
+    for (const prop of optionsNode.getProperties()) {
+      if (!Node4.isPropertyAssignment(prop))
+        continue;
+      const name = prop.getName();
+      if (name !== "verify")
+        continue;
+      const initializer = prop.getInitializer();
+      if (initializer && initializer.getKind() === SyntaxKind.TrueKeyword) {
+        return true;
+      }
+    }
+    return false;
+  }
+  getVariableNameFromParent(node) {
+    const parent = node.getParent();
+    if (Node4.isVariableDeclaration(parent)) {
+      return parent.getName();
+    }
+    return null;
+  }
+  extractFieldNames(node) {
+    const fields = [];
+    if (Node4.isObjectLiteralExpression(node)) {
+      for (const prop of node.getProperties()) {
+        if (Node4.isPropertyAssignment(prop) || Node4.isShorthandPropertyAssignment(prop)) {
+          fields.push(prop.getName());
+        }
+      }
+    } else if (Node4.isIdentifier(node)) {
+      const definitions = node.getDefinitionNodes();
+      for (const def of definitions) {
+        if (Node4.isVariableDeclaration(def)) {
+          const initializer = def.getInitializer();
+          if (initializer && Node4.isObjectLiteralExpression(initializer)) {
+            return this.extractFieldNames(initializer);
+          }
+        }
+      }
+    }
+    return fields;
+  }
+  findStateMutatingFunctions(sourceFile, verifiedStates) {
+    const handlers = [];
+    const stateVarNames = new Set(verifiedStates.map((s) => s.variableName));
+    const filePath = sourceFile.getFilePath();
+    const context = this.inferContext(filePath);
+    for (const func of sourceFile.getFunctions()) {
+      if (!func.isExported())
+        continue;
+      const funcName = func.getName();
+      if (!funcName)
+        continue;
+      const assignments = this.findStateMutationsInFunction(func, stateVarNames);
+      if (assignments.length === 0)
+        continue;
+      const preconditions = [];
+      const postconditions = [];
+      this.extractVerificationConditions(func, preconditions, postconditions);
+      const messageType = this.functionNameToMessageType(funcName);
+      if (process.env["POLLY_DEBUG"]) {
+        console.log(`[DEBUG] Found state-mutating function: ${funcName} → ${messageType} ` + `(${assignments.length} assignments, ${preconditions.length} preconditions, ${postconditions.length} postconditions)`);
+      }
+      handlers.push({
+        messageType,
+        node: context,
+        assignments,
+        preconditions,
+        postconditions,
+        location: {
+          file: filePath,
+          line: func.getStartLineNumber()
+        }
+      });
+    }
+    for (const varStmt of sourceFile.getVariableStatements()) {
+      if (!varStmt.isExported())
+        continue;
+      for (const decl of varStmt.getDeclarations()) {
+        const initializer = decl.getInitializer();
+        if (!initializer)
+          continue;
+        if (!Node4.isArrowFunction(initializer) && !Node4.isFunctionExpression(initializer))
+          continue;
+        const funcName = decl.getName();
+        if (!funcName)
+          continue;
+        const assignments = this.findStateMutationsInFunction(initializer, stateVarNames);
+        if (assignments.length === 0)
+          continue;
+        const preconditions = [];
+        const postconditions = [];
+        this.extractVerificationConditions(initializer, preconditions, postconditions);
+        const messageType = this.functionNameToMessageType(funcName);
+        if (process.env["POLLY_DEBUG"]) {
+          console.log(`[DEBUG] Found state-mutating arrow function: ${funcName} → ${messageType}`);
+        }
+        handlers.push({
+          messageType,
+          node: context,
+          assignments,
+          preconditions,
+          postconditions,
+          location: {
+            file: filePath,
+            line: decl.getStartLineNumber()
+          }
+        });
+      }
+    }
+    return handlers;
+  }
+  findStateMutationsInFunction(func, stateVarNames) {
+    const mutations = [];
+    func.forEachDescendant((node) => {
+      if (!Node4.isBinaryExpression(node))
+        return;
+      const operator = node.getOperatorToken().getText();
+      if (operator !== "=")
+        return;
+      const left = node.getLeft();
+      if (!Node4.isPropertyAccessExpression(left))
+        return;
+      const path3 = this.getPropertyPath(left);
+      for (const varName of stateVarNames) {
+        if (path3 === `${varName}.value`) {
+          const right = node.getRight();
+          if (Node4.isObjectLiteralExpression(right)) {
+            this.extractObjectLiteralAssignments(right, mutations);
+          }
+          break;
+        }
+        const fieldPrefix = `${varName}.value.`;
+        if (path3.startsWith(fieldPrefix)) {
+          const field = path3.substring(fieldPrefix.length);
+          const value = this.extractValue(node.getRight());
+          mutations.push({ field, value: value ?? "@" });
+          break;
+        }
+      }
+    });
+    return mutations;
+  }
+  functionNameToMessageType(funcName) {
+    let name = funcName.replace(/^handle/, "").replace(/^on/, "").replace(/^set/, "Set").replace(/^update/, "Update").replace(/^do/, "");
+    if (name.length > 0) {
+      name = name.charAt(0).toUpperCase() + name.slice(1);
+    }
+    return name || funcName;
+  }
 }
 
 // tools/analysis/src/extract/integrations.ts
@@ -9080,9 +9305,11 @@ ${generateVerificationSection(context)}
 - **Translation**: How TypeScript code becomes TLA+ specifications
 - **Verification**: What properties are being verified and what they mean
 - **State-Level Constraints**: Using $constraints() to declare verification constraints alongside state
+- **Verified State Discovery**: Using \`{ verify: true }\` on $sharedState to enable automatic handler discovery
 - **Performance**: How to optimize verification speed and state space exploration
 - **Debugging**: Interpreting counterexamples and fixing violations
 - **Configuration**: Understanding maxInFlight, bounds, and other verification parameters
+- **Universal State Management**: Using the same state code in Chrome extensions, web apps, and Node.js
 - **Elysia Integration**: Using Polly with Elysia/Bun servers for full-stack distributed systems verification
 - **Testing & Adapters**: Using mock adapters for testing and verification in Node.js environments
 
@@ -9101,6 +9328,49 @@ ${generateVerificationSection(context)}
   - **Transitive Discovery**: The analyzer uses transitive import following to discover constraints
   - Files outside src/ are automatically found if imported from handler files
   - This enables clean separation of verification code from runtime code
+- **Verified State Discovery**: When \`{ verify: true }\` is set on $sharedState/$syncedState/$persistedState:
+  - The analyzer automatically discovers exported functions that modify that state signal
+  - Functions with \`requires()\` and \`ensures()\` annotations get those extracted as pre/postconditions
+  - State assignments like \`authState.value = { ... }\` or \`authState.value.field = x\` are detected
+  - Message types are derived from function names: \`handleAuthSuccess\` → \`AuthSuccess\`
+  - This enables verification for applications that don't use \`messageBus.on()\` handlers
+  - Ideal for: multi-tab PWAs, WebSocket apps, reactive effect-driven architectures
+  - Example:
+    \`\`\`typescript
+    export const authState = $sharedState('auth', { isAuthenticated: false }, { verify: true });
+
+    export function handleLogin(): void {
+      requires(!authState.value.isAuthenticated);
+      authState.value = { ...authState.value, isAuthenticated: true };
+      ensures(authState.value.isAuthenticated);
+    }
+    \`\`\`
+
+# Verification Parameters Explained
+
+When explaining verification configuration, help users understand what each parameter controls:
+
+**maxDepth**: Maximum number of **sequential** message deliveries to check
+- Depth 4 = check sequences up to 4 messages delivered one after another
+- Depth 8 = check sequences up to 8 messages delivered one after another
+- Question to ask: "What's the longest sequence of messages that could expose a bug in my app?"
+- Most authentication/state machine bugs appear in shallow sequences (depth 2-4)
+
+**maxInFlight**: Maximum number of **concurrent** messages in the system at once
+- 2 = check scenarios with up to 2 messages pending simultaneously
+- 3 = check scenarios with up to 3 messages pending simultaneously
+- Question: "How many concurrent messages can actually happen in my app?"
+- Consider different bounds per message type (auth should be 1, queries could be higher)
+
+**maxTabs**: Number of concurrent contexts (tabs, workers, etc.)
+- Question: "How many concurrent contexts do I need to verify for race conditions?"
+- Most single-tab apps only need 1; multi-tab/worker apps need 2+
+
+**Practical Guidance**:
+- Start conservative: maxDepth: 3-4, maxInFlight: 2, maxTabs: 1
+- Use timeouts (5-10 minutes) to prevent runaway verification
+- Don't arbitrarily exclude message types to speed up verification - tune the bounds instead
+- If verification takes hours, bounds are likely too high for regular development workflows
 
 # Elysia/Bun Integration
 
@@ -9150,6 +9420,8 @@ const app = new Elysia()
       'POST /todos': {
         queue: true,
         optimistic: (body) => ({ id: -Date.now(), ...body }),
+        merge: 'replace',  // 'replace' | custom merge function
+        conflictResolution: 'last-write-wins',  // 'last-write-wins' | 'server-wins' | custom function
       },
     },
   }))
@@ -9166,6 +9438,30 @@ const app = new Elysia()
 - In production: Pass-through (minimal overhead) - client effects are bundled at build time
 - Authorization and broadcasts work in both modes
 
+**Offline Behavior Configuration:**
+
+The \`offline\` config enables Progressive Web App capabilities:
+
+\`\`\`typescript
+offline: {
+  'POST /todos': {
+    queue: true,                          // Queue request when offline
+    optimistic: (body) => TResult,        // Immediate UI update with predicted result
+    merge: 'replace' | mergeFn,           // How to merge optimistic with server result
+    conflictResolution: 'last-write-wins' | 'server-wins' | resolveFn,
+  },
+}
+\`\`\`
+
+**Merge Strategies:**
+- \`'replace'\`: Replace optimistic result with server result (default)
+- \`(optimistic, server) => TResult\`: Custom merge logic
+
+**Conflict Resolution** (when multiple devices edit offline):
+- \`'last-write-wins'\`: Lamport clock determines winner
+- \`'server-wins'\`: Server state always takes precedence
+- \`(client, server) => TResult\`: Custom conflict resolution
+
 ## Client-Side Wrapper (\`@fairfox/polly/client\`)
 
 Enhances Eden treaty client with Polly features:
@@ -9382,6 +9678,126 @@ All context creation functions now follow the adapter pattern:
 - \`getMessageBus(context, adapters?)\` ✓
 - \`new MessageBus(context, adapters?)\` ✓
 
+# Universal State Management
+
+Polly's state primitives (\`$sharedState\`, \`$syncedState\`, \`$persistedState\`, \`$state\`) now work universally across Chrome extensions, web applications/PWAs, and Node.js environments using an **adapter pattern**.
+
+## The Adapter System
+
+State management is decoupled into two independent concerns via adapters:
+
+1. **Storage Adapter** - Where state persists (chrome.storage, IndexedDB, or in-memory)
+2. **Sync Adapter** - How state synchronizes across contexts (chrome.runtime, BroadcastChannel, or NoOp)
+
+## Automatic Environment Detection
+
+The framework automatically detects the environment and selects appropriate adapters:
+
+| Environment | Storage | Sync Transport | Use Case |
+|------------|---------|----------------|----------|
+| **Chrome Extension** | \`chrome.storage.local\` | \`chrome.runtime\` messaging | Multi-context extensions |
+| **Web App / PWA** | IndexedDB | BroadcastChannel | Multi-tab web applications |
+| **Single-Tab Web App** | IndexedDB | None (NoOp) | Single-tab applications |
+| **Node.js / Testing** | In-memory Map | None (NoOp) | Verification & unit tests |
+
+**Example:**
+\`\`\`typescript
+// Same code works everywhere!
+import { $sharedState } from '@fairfox/polly/state';
+
+const settings = $sharedState('settings', { theme: 'dark' });
+
+// In Chrome extension:
+//   → Uses chrome.storage.local + chrome.runtime messaging
+// In web app:
+//   → Uses IndexedDB + BroadcastChannel
+// In Node.js test:
+//   → Uses in-memory Map + NoOp sync
+\`\`\`
+
+## Why BroadcastChannel for Web Apps?
+
+**Architecture Decision**: BroadcastChannel was chosen over SharedWorker for web app sync because:
+- Simpler API with no lifecycle management complexity
+- Decentralized (aligns with local-first/offline-first architecture)
+- Better browser support (especially Safari and mobile)
+- Perfect for message-passing with Lamport clock conflict resolution
+- No single point of failure
+
+SharedWorker could be added as an optional adapter in the future for use cases requiring:
+- Central coordination point for complex multi-tab workflows
+- Shared WebSocket connections (one connection for all tabs)
+- Heavy computation done once and shared across tabs
+- Persistent background work when tabs are closed
+
+See \`src/shared/lib/sync-adapter.ts\` for detailed architectural rationale.
+
+## Available Adapters
+
+### Storage Adapters
+- \`ChromeStorageAdapter\` - Uses \`chrome.storage.local\` (auto-detected in extensions)
+- \`IndexedDBAdapter\` - Uses IndexedDB (auto-detected in web apps)
+- \`MemoryStorageAdapter\` - Uses in-memory Map (auto-detected in Node.js)
+
+### Sync Adapters
+- \`ChromeRuntimeSyncAdapter\` - Uses \`chrome.runtime.sendMessage\` (auto-detected in extensions)
+- \`BroadcastChannelSyncAdapter\` - Uses BroadcastChannel API (auto-detected in web apps)
+- \`NoOpSyncAdapter\` - No synchronization (auto-detected for single-context scenarios)
+
+## Custom Adapters
+
+Users can provide custom adapters for specialized scenarios:
+
+\`\`\`typescript
+import { $sharedState } from '@fairfox/polly/state';
+import { IndexedDBAdapter, BroadcastChannelSyncAdapter } from '@fairfox/polly/adapters';
+
+const settings = $sharedState('settings', defaultSettings, {
+  storage: new IndexedDBAdapter('custom-db-name'),
+  sync: new BroadcastChannelSyncAdapter('custom-channel'),
+});
+\`\`\`
+
+## Key Features
+
+- **Write once, run anywhere**: Same state code works in extensions, web apps, and Node.js
+- **Environment-optimized**: Uses the best available APIs for each platform
+- **No conditional logic**: Framework handles detection and selection
+- **Testable**: Mock adapters enable testing without Chrome APIs
+- **Extensible**: Custom adapters for specialized use cases
+
+## Common Use Cases
+
+### Multi-Tab Web Application
+\`\`\`typescript
+// State automatically syncs across tabs using BroadcastChannel
+const todos = $sharedState('todos', []);
+\`\`\`
+
+### Chrome Extension
+\`\`\`typescript
+// State syncs across extension contexts using chrome.runtime
+const settings = $sharedState('settings', { theme: 'dark' });
+\`\`\`
+
+### Single-Tab Web App (PWA)
+\`\`\`typescript
+// State persists to IndexedDB but doesn't sync (no other tabs)
+const user = $sharedState('user', null, {
+  sync: new NoOpSyncAdapter() // Explicitly disable sync
+});
+\`\`\`
+
+### Node.js Testing
+\`\`\`typescript
+// State uses in-memory storage, no persistence or sync
+const mockState = $sharedState('test-state', defaultValue);
+\`\`\`
+
+## Migration from Chrome-Only
+
+Existing Chrome extension code requires **no changes** - the framework is backward compatible. Web apps can now use the same primitives that previously only worked in extensions.
+
 Begin by understanding their question and providing a clear, precise answer based on their project context.`;
 }
 function generateProjectSection(context, contexts2, handlers2, flows2) {
@@ -9531,6 +9947,11 @@ confidence that they will work when users apply them to their configuration.
 Constraints and type guards can be organized in separate files (e.g., specs/constraints.ts) and will
 be automatically discovered via imports. Files outside src/ are fully supported.
 
+**Verified State Discovery**: When \`{ verify: true }\` is set on $sharedState/$syncedState/$persistedState,
+the analyzer automatically discovers exported functions that modify that state and extracts their
+\`requires()\`/\`ensures()\` annotations. This enables verification for apps that don't use \`messageBus.on()\`
+handlers, such as multi-tab PWAs or WebSocket applications with reactive effect-driven state changes.
+
 # Communication Style
 
 - Direct and precise - no fluff
@@ -9544,6 +9965,32 @@ ${generateProjectSection(context, contexts2, allHandlers, messageFlows)}
 
 ${generateVerificationSection(context)}
 
+# Understanding Verification Parameters
+
+Before suggesting optimizations, understand what each parameter actually controls:
+
+**maxDepth**: Maximum number of **sequential** message deliveries to check
+- Depth 4 = check sequences up to 4 messages delivered one after another
+- Depth 8 = check sequences up to 8 messages delivered one after another
+- Question to ask: "What's the longest sequence of messages that could expose a bug in my app?"
+- Most authentication/state machine bugs appear in shallow sequences (depth 2-4)
+
+**maxInFlight**: Maximum number of **concurrent** messages in the system at once
+- 2 = check scenarios with up to 2 messages pending simultaneously
+- 3 = check scenarios with up to 3 messages pending simultaneously
+- Question: "How many concurrent messages can actually happen in my app?"
+- Consider different bounds per message type (auth should be 1, queries could be higher)
+
+**maxTabs**: Number of concurrent contexts (tabs, workers, etc.)
+- Question: "How many concurrent contexts do I need to verify for race conditions?"
+- Most single-tab apps only need 1; multi-tab/worker apps need 2+
+
+**Practical Approach**:
+- Start conservative: maxDepth: 3-4, maxInFlight: 2, maxTabs: 1
+- Use timeouts (5-10 minutes) to prevent runaway verification
+- Don't arbitrarily exclude message types - tune the bounds instead
+- If verification takes hours, bounds are likely too high for regular development
+
 # Your Expertise: Optimization Tiers
 
 ## Tier 1: Safe Optimizations (ZERO precision loss)
@@ -9847,4 +10294,4 @@ Goodbye!`);
 }
 main();
 
-//# debugId=20A98BE870D3CEDD64756E2164756E21
+//# debugId=4FDE5BCEB24CA52B64756E2164756E21