@fairfox/polly 0.14.0 → 0.14.1

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

@@ -9102,6 +9102,32 @@ ${generateVerificationSection(context)}
   - Files outside src/ are automatically found if imported from handler files
   - This enables clean separation of verification code from runtime code
 
+# 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
 
 Polly now provides first-class support for Elysia (Bun-first web framework) with Eden type-safe client generation:
@@ -9150,6 +9176,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 +9194,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:
@@ -9544,6 +9596,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 +9925,4 @@ Goodbye!`);
 }
 main();
 
-//# debugId=20A98BE870D3CEDD64756E2164756E21
+//# debugId=0C5B6EFE146F7BE464756E2164756E21