@fairfox/polly 0.9.0 → 0.10.0

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

@@ -5446,17 +5446,21 @@ class HandlerExtractor {
     const handlers = [];
     const messageTypes = new Set;
     const invalidMessageTypes = new Set;
+    const stateConstraints = [];
     const sourceFiles = this.project.getSourceFiles();
     this.debugLogSourceFiles(sourceFiles);
     for (const sourceFile of sourceFiles) {
       const fileHandlers = this.extractFromFile(sourceFile);
       handlers.push(...fileHandlers);
       this.categorizeHandlerMessageTypes(fileHandlers, messageTypes, invalidMessageTypes);
+      const fileConstraints = this.extractStateConstraintsFromFile(sourceFile);
+      stateConstraints.push(...fileConstraints);
     }
     this.debugLogExtractionResults(handlers.length, invalidMessageTypes.size);
     return {
       handlers,
-      messageTypes
+      messageTypes,
+      stateConstraints
     };
   }
   debugLogSourceFiles(sourceFiles) {
@@ -6288,6 +6292,84 @@ class HandlerExtractor {
       mutations.push({ field, line, afterAwait });
     }
   }
+  extractStateConstraintsFromFile(sourceFile) {
+    const constraints = [];
+    const filePath = sourceFile.getFilePath();
+    sourceFile.forEachDescendant((node) => {
+      const nodeConstraints = this.recognizeStateConstraint(node, filePath);
+      constraints.push(...nodeConstraints);
+    });
+    return constraints;
+  }
+  recognizeStateConstraint(node, filePath) {
+    if (!Node4.isCallExpression(node)) {
+      return [];
+    }
+    const expression = node.getExpression();
+    if (!Node4.isIdentifier(expression)) {
+      return [];
+    }
+    const functionName = expression.getText();
+    if (functionName !== "$constraints") {
+      return [];
+    }
+    const args = node.getArguments();
+    if (args.length < 2) {
+      return [];
+    }
+    const fieldArg = args[0];
+    if (!Node4.isStringLiteral(fieldArg)) {
+      return [];
+    }
+    const field = fieldArg.getLiteralValue();
+    const constraintsArg = args[1];
+    if (!Node4.isObjectLiteralExpression(constraintsArg)) {
+      return [];
+    }
+    const results = [];
+    for (const property of constraintsArg.getProperties()) {
+      if (!Node4.isPropertyAssignment(property)) {
+        continue;
+      }
+      const messageType = property.getName();
+      const initializer = property.getInitializer();
+      if (!initializer || !Node4.isObjectLiteralExpression(initializer)) {
+        continue;
+      }
+      let requires;
+      let ensures;
+      let message;
+      for (const constraintProp of initializer.getProperties()) {
+        if (!Node4.isPropertyAssignment(constraintProp)) {
+          continue;
+        }
+        const propName = constraintProp.getName();
+        const propValue = constraintProp.getInitializer();
+        if (!propValue) {
+          continue;
+        }
+        if (propName === "requires" && Node4.isStringLiteral(propValue)) {
+          requires = propValue.getLiteralValue();
+        } else if (propName === "ensures" && Node4.isStringLiteral(propValue)) {
+          ensures = propValue.getLiteralValue();
+        } else if (propName === "message" && Node4.isStringLiteral(propValue)) {
+          message = propValue.getLiteralValue();
+        }
+      }
+      results.push({
+        field,
+        messageType,
+        requires,
+        ensures,
+        message,
+        location: {
+          file: filePath,
+          line: property.getStartLineNumber()
+        }
+      });
+    }
+    return results;
+  }
 }
 
 // tools/analysis/src/extract/integrations.ts
@@ -6906,7 +6988,8 @@ class TypeExtractor {
       stateType,
       messageTypes: validMessageTypes,
       fields,
-      handlers: validHandlers
+      handlers: validHandlers,
+      stateConstraints: handlerAnalysis.stateConstraints
     };
   }
   extractHandlerAnalysis() {
@@ -8723,6 +8806,7 @@ ${generateVerificationSection(context)}
 - **Architecture**: How contexts, handlers, and message flows work in their project
 - **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
 - **Performance**: How to optimize verification speed and state space exploration
 - **Debugging**: Interpreting counterexamples and fixing violations
 - **Configuration**: Understanding maxInFlight, bounds, and other verification parameters
@@ -8733,6 +8817,11 @@ ${generateVerificationSection(context)}
 - If asked about verification performance, consider the verification config and results
 - Provide actionable suggestions, not just general advice
 - If you don't know something specific about their project, say so clearly
+- **State-Level Constraints**: Explain that $constraints() allows declaring verification constraints alongside state:
+  - Constraints are automatically wired as preconditions in generated TLA+ handlers
+  - Example: \`$constraints("loggedIn", { USER_LOGOUT: { requires: "state.loggedIn === true" } })\`
+  - This eliminates duplication and creates a single source of truth for state invariants
+  - Parser extracts constraints and adds them to all relevant message handlers automatically
 
 Begin by understanding their question and providing a clear, precise answer based on their project context.`;
 }
@@ -8917,6 +9006,20 @@ messages: {
 ### 2. Symmetry Reduction
 Treat identical or commutative message types as interchangeable to reduce state space.
 
+**Example**: For multiple independent symmetry groups (e.g., workers and replicas):
+\`\`\`typescript
+messages: {
+  symmetry: [
+    ['worker1', 'worker2', 'worker3'],   // Workers are interchangeable
+    ['replica1', 'replica2'],            // Replicas are interchangeable
+  ],
+}
+\`\`\`
+
+Polly generates: \`Symmetry == Permutations(Set1) \\cup Permutations(Set2)\` which preserves
+independent group semantics (elements within each group are interchangeable, but not across groups).
+This is the standard TLA+ pattern used in Paxos and SimpleAllocator.
+
 ### 3. Message-Specific Bounds
 Different maxInFlight per message type - auth messages should be sequential (1),
 but data queries might allow concurrency (3).
@@ -9181,4 +9284,4 @@ Goodbye!`);
 }
 main();
 
-//# debugId=29E860FB6D1FD51164756E2164756E21
+//# debugId=8BD8EAFF3D45D43B64756E2164756E21