@fairfox/polly 0.10.1 → 0.12.0

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

@@ -94,25 +94,30 @@ class ProjectDetector {
     };
   }
   detectBackgroundEntry(manifest, entryPoints) {
-    const background = manifest.background;
+    const background = manifest["background"];
     if (!background)
       return;
-    const file = background.service_worker || background.scripts?.[0] || background.page;
+    const file = background["service_worker"] || background["scripts"]?.[0] || background["page"];
     if (file) {
       entryPoints["background"] = this.findSourceFile(file);
     }
   }
   detectContentScriptEntry(manifest, entryPoints) {
-    const contentScripts = manifest.content_scripts;
+    const contentScripts = manifest["content_scripts"];
     if (!contentScripts || contentScripts.length === 0)
       return;
-    const firstScript = contentScripts[0].js?.[0];
+    const firstScriptObj = contentScripts[0];
+    if (!firstScriptObj)
+      return;
+    const firstScript = firstScriptObj["js"]?.[0];
     if (firstScript) {
       entryPoints["content"] = this.findSourceFile(firstScript);
     }
   }
   detectPopupEntry(manifest, entryPoints) {
-    const popup = manifest.action?.default_popup || manifest.browser_action?.default_popup;
+    const action = manifest["action"];
+    const browserAction = manifest["browser_action"];
+    const popup = action?.["default_popup"] || browserAction?.["default_popup"];
     if (!popup)
       return;
     const jsFile = this.findAssociatedJS(path4.join(this.projectRoot, popup));
@@ -121,7 +126,8 @@ class ProjectDetector {
     }
   }
   detectOptionsEntry(manifest, entryPoints) {
-    const options = manifest.options_ui?.page || manifest.options_page;
+    const optionsUi = manifest["options_ui"];
+    const options = optionsUi?.["page"] || manifest["options_page"];
     if (!options)
       return;
     const jsFile = this.findAssociatedJS(path4.join(this.projectRoot, options));
@@ -176,7 +182,7 @@ class ProjectDetector {
   detectElectron(packageJson) {
     const entryPoints = {};
     const mainCandidates = [
-      packageJson.main,
+      packageJson["main"],
       "src/main/index.ts",
       "src/electron/main.ts",
       "electron/main.ts",
@@ -210,9 +216,9 @@ class ProjectDetector {
         renderer: "Renderer Process"
       },
       metadata: {
-        name: packageJson.name,
-        version: packageJson.version,
-        description: packageJson.description
+        name: packageJson["name"],
+        version: packageJson["version"],
+        description: packageJson["description"]
       }
     };
   }
@@ -271,9 +277,9 @@ class ProjectDetector {
         client: "Client"
       },
       metadata: {
-        name: packageJson.name,
-        version: packageJson.version,
-        description: packageJson.description
+        name: packageJson["name"],
+        version: packageJson["version"],
+        description: packageJson["description"]
       }
     };
   }
@@ -4645,9 +4651,12 @@ class ContextAnalyzer {
     const leadingComments = firstStatement.getLeadingCommentRanges();
     if (leadingComments.length === 0)
       return;
-    const comment = leadingComments[0].getText();
+    const firstComment = leadingComments[0];
+    if (!firstComment)
+      return;
+    const comment = firstComment.getText();
     const descMatch = comment.match(/@description\s+(.+?)(?:\n|$)/s);
-    if (descMatch) {
+    if (descMatch?.[1]) {
       return descMatch[1].trim();
     }
     const lines = comment.split(`
@@ -4746,6 +4755,8 @@ class ContextAnalyzer {
     if (params.length === 0)
       return [];
     const propsParam = params[0];
+    if (!propsParam)
+      return [];
     const type = propsParam.getType();
     const props = [];
     for (const prop of type.getProperties()) {
@@ -4761,6 +4772,8 @@ class ContextAnalyzer {
     if (typeArgs.length === 0)
       return [];
     const propsType = typeArgs[0];
+    if (!propsType)
+      return [];
     const props = [];
     for (const prop of propsType.getProperties()) {
       props.push(prop.getName());
@@ -4768,10 +4781,15 @@ class ContextAnalyzer {
     return props;
   }
   extractJSDocDescription(node) {
+    if (!Node.isJSDocable(node))
+      return;
     const jsDocs = node.getJsDocs();
     if (jsDocs.length === 0)
       return;
-    const description = jsDocs[0].getDescription().trim();
+    const firstDoc = jsDocs[0];
+    if (!firstDoc)
+      return;
+    const description = firstDoc.getDescription().trim();
     return description || undefined;
   }
   isUIContext(contextType) {
@@ -4853,7 +4871,10 @@ class FlowAnalyzer {
     if (args.length === 0) {
       return;
     }
-    const msgType = this.extractMessageTypeFromArg(args[0]);
+    const firstArg = args[0];
+    if (!firstArg)
+      return;
+    const msgType = this.extractMessageTypeFromArg(firstArg);
     if (msgType === messageType) {
       senders.push({
         context,
@@ -4873,7 +4894,10 @@ class FlowAnalyzer {
     if (args.length === 0) {
       return;
     }
-    const msgType = this.extractMessageTypeFromArg(args[0]);
+    const firstArg = args[0];
+    if (!firstArg)
+      return;
+    const msgType = this.extractMessageTypeFromArg(firstArg);
     if (msgType === messageType) {
       senders.push({
         context,
@@ -4943,7 +4967,10 @@ class FlowAnalyzer {
     if (args.length === 0) {
       return;
     }
-    const messageType = this.extractMessageTypeFromArg(args[0]);
+    const firstArg = args[0];
+    if (!firstArg)
+      return;
+    const messageType = this.extractMessageTypeFromArg(firstArg);
     if (messageType) {
       sends.push({
         messageType,
@@ -4996,10 +5023,17 @@ class FlowAnalyzer {
     });
     if (!targetNode)
       return {};
-    const jsDocs = targetNode.getJsDocs?.() || [];
+    const nodeAny = targetNode;
+    if (!("getJsDocs" in nodeAny) || typeof nodeAny.getJsDocs !== "function") {
+      return {};
+    }
+    const jsDocs = nodeAny.getJsDocs();
     if (jsDocs.length === 0)
       return {};
-    const comment = jsDocs[0].getText();
+    const firstDoc = jsDocs[0];
+    if (!firstDoc)
+      return {};
+    const comment = firstDoc.getText();
     const flowMatch = comment.match(/@flow\s+([^\s]+)/);
     const flowName = flowMatch ? flowMatch[1] : undefined;
     const triggerMatch = comment.match(/@trigger\s+(.+?)(?:\n|$)/);
@@ -5435,40 +5469,116 @@ class HandlerExtractor {
   project;
   typeGuardCache;
   relationshipExtractor;
+  analyzedFiles;
+  packageRoot;
   constructor(tsConfigPath) {
     this.project = new Project3({
       tsConfigFilePath: tsConfigPath
     });
     this.typeGuardCache = new WeakMap;
     this.relationshipExtractor = new RelationshipExtractor;
+    this.analyzedFiles = new Set;
+    this.packageRoot = this.findPackageRoot(tsConfigPath);
+  }
+  findPackageRoot(tsConfigPath) {
+    let dir = tsConfigPath.substring(0, tsConfigPath.lastIndexOf("/"));
+    while (dir.length > 1) {
+      try {
+        const packageJsonPath = `${dir}/package.json`;
+        const file = Bun.file(packageJsonPath);
+        if (file.size > 0) {
+          return dir;
+        }
+      } catch {}
+      const parentDir = dir.substring(0, dir.lastIndexOf("/"));
+      if (parentDir === dir)
+        break;
+      dir = parentDir;
+    }
+    return tsConfigPath.substring(0, tsConfigPath.lastIndexOf("/"));
   }
   extractHandlers() {
     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);
+    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.debugLogExtractionResults(handlers.length, invalidMessageTypes.size);
+    this.debugLogAnalysisStats(allSourceFiles.length, entryPoints.length);
     return {
       handlers,
       messageTypes,
       stateConstraints
     };
   }
-  debugLogSourceFiles(sourceFiles) {
+  analyzeFileAndImports(sourceFile, handlers, messageTypes, invalidMessageTypes, stateConstraints) {
+    const filePath = sourceFile.getFilePath();
+    if (this.analyzedFiles.has(filePath)) {
+      return;
+    }
+    this.analyzedFiles.add(filePath);
+    if (process.env["POLLY_DEBUG"]) {
+      console.log(`[DEBUG] Analyzing: ${filePath}`);
+    }
+    const fileHandlers = this.extractFromFile(sourceFile);
+    handlers.push(...fileHandlers);
+    this.categorizeHandlerMessageTypes(fileHandlers, messageTypes, invalidMessageTypes);
+    const fileConstraints = this.extractStateConstraintsFromFile(sourceFile);
+    stateConstraints.push(...fileConstraints);
+    const importDeclarations = sourceFile.getImportDeclarations();
+    for (const importDecl of importDeclarations) {
+      const importedFile = importDecl.getModuleSpecifierSourceFile();
+      if (importedFile) {
+        const importedPath = importedFile.getFilePath();
+        if (!this.isWithinPackage(importedPath)) {
+          if (process.env["POLLY_DEBUG"]) {
+            console.log(`[DEBUG] Skipping external import: ${importedPath}`);
+          }
+          continue;
+        }
+        this.analyzeFileAndImports(importedFile, handlers, messageTypes, invalidMessageTypes, stateConstraints);
+      } else if (process.env["POLLY_DEBUG"]) {
+        const specifier = importDecl.getModuleSpecifierValue();
+        if (!specifier.startsWith("node:") && !this.isNodeModuleImport(specifier)) {
+          console.log(`[DEBUG] Could not resolve import: ${specifier} in ${filePath}`);
+        }
+      }
+    }
+  }
+  isWithinPackage(filePath) {
+    if (!filePath.startsWith(this.packageRoot)) {
+      return false;
+    }
+    if (filePath.includes("/node_modules/")) {
+      return false;
+    }
+    return true;
+  }
+  isNodeModuleImport(specifier) {
+    return !specifier.startsWith(".") && !specifier.startsWith("/");
+  }
+  debugLogAnalysisStats(totalSourceFiles, entryPointCount) {
+    if (!process.env["POLLY_DEBUG"])
+      return;
+    console.log(`[DEBUG] Analysis Statistics:`);
+    console.log(`[DEBUG]   Package root: ${this.packageRoot}`);
+    console.log(`[DEBUG]   Source files from tsconfig: ${totalSourceFiles}`);
+    console.log(`[DEBUG]   Entry points (in package): ${entryPointCount}`);
+    console.log(`[DEBUG]   Files analyzed (including imports): ${this.analyzedFiles.size}`);
+    console.log(`[DEBUG]   Additional files discovered: ${this.analyzedFiles.size - entryPointCount}`);
+  }
+  debugLogSourceFiles(allSourceFiles, entryPoints) {
     if (!process.env["POLLY_DEBUG"])
       return;
-    console.log(`[DEBUG] Loaded ${sourceFiles.length} source files`);
-    if (sourceFiles.length <= 20) {
-      for (const sf of sourceFiles) {
+    console.log(`[DEBUG] Loaded ${allSourceFiles.length} source files from tsconfig`);
+    console.log(`[DEBUG] Filtered to ${entryPoints.length} entry points within package`);
+    if (entryPoints.length <= 20) {
+      for (const sf of entryPoints) {
         console.log(`[DEBUG]   - ${sf.getFilePath()}`);
       }
     }
@@ -5726,7 +5836,10 @@ class HandlerExtractor {
     if (!body) {
       return;
     }
-    const firstAwaitPos = awaitExpressions[0].getStart();
+    const firstAwait = awaitExpressions[0];
+    if (!firstAwait)
+      return;
+    const firstAwaitPos = firstAwait.getStart();
     funcNode.forEachDescendant((node) => {
       if (Node4.isBinaryExpression(node)) {
         this.checkBinaryExpressionMutation(node, firstAwaitPos, mutations);
@@ -5777,6 +5890,8 @@ class HandlerExtractor {
       return null;
     }
     const conditionArg = args[0];
+    if (!conditionArg)
+      return null;
     const expression = conditionArg.getText();
     let message;
     if (args.length >= 2 && Node4.isStringLiteral(args[1])) {
@@ -6082,12 +6197,17 @@ class HandlerExtractor {
     return;
   }
   extractMessageTypeFromTypePredicateFunction(node, returnTypeNode) {
-    const typeNode = returnTypeNode.getTypeNode();
-    if (typeNode) {
-      const typeName = typeNode.getText();
-      const messageType = this.extractMessageTypeFromTypeName(typeName);
-      if (messageType) {
-        return messageType;
+    if (!Node4.isTypePredicate(returnTypeNode)) {
+      return null;
+    }
+    if ("getTypeNode" in returnTypeNode && typeof returnTypeNode.getTypeNode === "function") {
+      const typeNode = returnTypeNode.getTypeNode();
+      if (typeNode) {
+        const typeName = typeNode.getText();
+        const messageType = this.extractMessageTypeFromTypeName(typeName);
+        if (messageType) {
+          return messageType;
+        }
       }
     }
     return this.extractMessageTypeFromFunctionBodyText(node);
@@ -6419,7 +6539,10 @@ class IntegrationAnalyzer {
     if (args.length === 0) {
       return;
     }
-    const url = this.extractURLFromArg(args[0]);
+    const firstArg = args[0];
+    if (!firstArg)
+      return;
+    const url = this.extractURLFromArg(firstArg);
     if (!url) {
       return;
     }
@@ -6600,10 +6723,15 @@ class IntegrationAnalyzer {
     }
   }
   extractJSDocDescription(node) {
-    const jsDocs = node.getJsDocs?.() || [];
+    if (!Node5.isJSDocable(node))
+      return;
+    const jsDocs = node.getJsDocs();
     if (jsDocs.length === 0)
       return;
-    const comment = jsDocs[0].getDescription().trim();
+    const firstDoc = jsDocs[0];
+    if (!firstDoc)
+      return;
+    const comment = firstDoc.getDescription().trim();
     return comment || undefined;
   }
 }
@@ -6642,17 +6770,17 @@ class ManifestParser {
     }
     const manifest = this.manifestData;
     return {
-      name: manifest.name || "Unknown Extension",
-      version: manifest.version || "0.0.0",
-      description: manifest.description,
-      manifestVersion: manifest.manifest_version || 2,
+      name: manifest["name"] || "Unknown Extension",
+      version: manifest["version"] || "0.0.0",
+      description: manifest["description"],
+      manifestVersion: manifest["manifest_version"] || 2,
       background: this.parseBackground(),
       contentScripts: this.parseContentScripts(),
       popup: this.parsePopup(),
       options: this.parseOptions(),
       devtools: this.parseDevtools(),
-      permissions: manifest.permissions || [],
-      hostPermissions: manifest.host_permissions || []
+      permissions: manifest["permissions"] || [],
+      hostPermissions: manifest["host_permissions"] || []
     };
   }
   getContextEntryPoints() {
@@ -6718,25 +6846,25 @@ class ManifestParser {
   parseBackground() {
     if (!this.manifestData)
       return;
-    const bg = this.manifestData.background;
+    const bg = this.manifestData["background"];
     if (!bg)
       return;
-    if (bg.service_worker) {
+    if (bg["service_worker"]) {
       return {
         type: "service_worker",
-        files: [bg.service_worker]
+        files: [bg["service_worker"]]
       };
     }
-    if (bg.scripts) {
+    if (bg["scripts"]) {
       return {
         type: "script",
-        files: bg.scripts
+        files: bg["scripts"]
       };
     }
-    if (bg.page) {
+    if (bg["page"]) {
       return {
         type: "script",
-        files: [bg.page]
+        files: [bg["page"]]
       };
     }
     return;
@@ -6744,24 +6872,24 @@ class ManifestParser {
   parseContentScripts() {
     if (!this.manifestData)
       return;
-    const cs = this.manifestData.content_scripts;
+    const cs = this.manifestData["content_scripts"];
     if (!cs || !Array.isArray(cs))
       return;
     return cs.map((script) => ({
-      matches: script.matches || [],
-      js: script.js || [],
-      css: script.css
+      matches: script["matches"] || [],
+      js: script["js"] || [],
+      css: script["css"]
     }));
   }
   parsePopup() {
     if (!this.manifestData)
       return;
-    const action = this.manifestData.action || this.manifestData.browser_action;
+    const action = this.manifestData["action"] || this.manifestData["browser_action"];
     if (!action)
       return;
-    if (action.default_popup) {
+    if (action["default_popup"]) {
       return {
-        html: action.default_popup,
+        html: action["default_popup"],
         default: true
       };
     }
@@ -6770,7 +6898,7 @@ class ManifestParser {
   parseOptions() {
     if (!this.manifestData)
       return;
-    const options = this.manifestData.options_ui || this.manifestData.options_page;
+    const options = this.manifestData["options_ui"] || this.manifestData["options_page"];
     if (!options)
       return;
     if (typeof options === "string") {
@@ -6779,15 +6907,16 @@ class ManifestParser {
         openInTab: false
       };
     }
+    const optionsObj = options;
     return {
-      page: options.page,
-      openInTab: options.open_in_tab
+      page: optionsObj["page"],
+      openInTab: optionsObj["open_in_tab"]
     };
   }
   parseDevtools() {
     if (!this.manifestData)
       return;
-    const devtools = this.manifestData.devtools_page;
+    const devtools = this.manifestData["devtools_page"];
     if (!devtools)
       return;
     return {
@@ -6984,11 +7113,20 @@ class TypeExtractor {
     const handlerAnalysis = this.extractHandlerAnalysis();
     const validMessageTypes = this.filterAndLogMessageTypes(messageTypes, handlerAnalysis.messageTypes);
     const validHandlers = this.filterAndLogHandlers(handlerAnalysis.handlers);
+    const completeHandlers = validHandlers.map((h) => ({
+      messageType: h.messageType,
+      node: h.node || "unknown",
+      assignments: h.assignments || [],
+      preconditions: h.preconditions || [],
+      postconditions: h.postconditions || [],
+      location: h.location,
+      relationships: h.relationships
+    }));
     return {
       stateType,
       messageTypes: validMessageTypes,
       fields,
-      handlers: validHandlers,
+      handlers: completeHandlers,
       stateConstraints: handlerAnalysis.stateConstraints
     };
   }
@@ -7090,7 +7228,7 @@ class TypeExtractor {
     if (type.getAliasSymbol()) {
       return this.extractFromTypeAlias(type, typeName, sourceFile, warnings);
     }
-    if (type.isConditionalType?.()) {
+    if (typeof type.isConditionalType === "function" && type.isConditionalType()) {
       return this.extractFromConditionalType(type, warnings);
     }
     if (type.getText().includes("[K in ")) {
@@ -7155,7 +7293,10 @@ class TypeExtractor {
     if (parts.length < 2) {
       return messageTypes;
     }
-    const branches = parts[1].split(":");
+    const secondPart = parts[1];
+    if (!secondPart)
+      return messageTypes;
+    const branches = secondPart.split(":");
     for (const branch of branches) {
       const extracted = this.extractStringLiteralFromBranch(branch);
       if (extracted) {
@@ -7617,9 +7758,12 @@ class StructurizrDSLGenerator {
     }
     for (const [messageType, handlers2] of handlersByType) {
       const componentName = this.toComponentName(messageType);
-      const description = this.generateComponentDescription(messageType, handlers2[0]);
-      const tags = this.getComponentTags(messageType, handlers2[0]);
-      const properties = this.getComponentProperties(messageType, handlers2[0], contextType);
+      const firstHandler = handlers2[0];
+      if (!firstHandler)
+        continue;
+      const description = this.generateComponentDescription(messageType, firstHandler);
+      const tags = this.getComponentTags(messageType, firstHandler);
+      const properties = this.getComponentProperties(messageType, firstHandler, contextType);
       componentDefs.push({
         id: this.toId(componentName),
         name: componentName,
@@ -8150,7 +8294,8 @@ class StructurizrDSLGenerator {
     let stepCount = 0;
     for (const { handler, contextName: _contextName } of handlers2) {
       const handlerComponentId = this.toId(`${handler.messageType}_handler`);
-      for (const rel of handler.relationships) {
+      const relationships = handler.relationships || [];
+      for (const rel of relationships) {
         const toComponent = this.toId(rel.to);
         parts.push(`      ${handlerComponentId} -> ${toComponent} "${rel.description}"`);
         stepCount++;
@@ -8231,7 +8376,7 @@ class StructurizrDSLGenerator {
       state: "Application state synchronization",
       general: "Message flow through the system"
     };
-    return descriptions[domain] || descriptions.general;
+    return descriptions[domain] || descriptions["general"] || "Message flow through the system";
   }
   getUserAction(domain) {
     const actions = {
@@ -8240,7 +8385,7 @@ class StructurizrDSLGenerator {
       state: "Requests state",
       general: "Interacts"
     };
-    return actions[domain] || actions.general;
+    return actions[domain] || actions["general"] || "Interacts";
   }
   getMessageDescription(messageType) {
     const type = messageType.toLowerCase();
@@ -8479,11 +8624,13 @@ class StructurizrDSLGenerator {
     }
     if (this.options.perspectives?.[comp.id]) {
       const perspectives = this.options.perspectives[comp.id];
-      parts.push(`${indent}  perspectives {`);
-      for (const perspective of perspectives) {
-        parts.push(`${indent}    "${this.escape(perspective.name)}" "${this.escape(perspective.description)}"`);
+      if (perspectives) {
+        parts.push(`${indent}  perspectives {`);
+        for (const perspective of perspectives) {
+          parts.push(`${indent}    "${this.escape(perspective.name)}" "${this.escape(perspective.description)}"`);
+        }
+        parts.push(`${indent}  }`);
       }
-      parts.push(`${indent}  }`);
     }
     parts.push(`${indent}}`);
     return parts.join(`
@@ -8810,6 +8957,7 @@ ${generateVerificationSection(context)}
 - **Performance**: How to optimize verification speed and state space exploration
 - **Debugging**: Interpreting counterexamples and fixing violations
 - **Configuration**: Understanding maxInFlight, bounds, and other verification parameters
+- **Elysia Integration**: Using Polly with Elysia/Bun servers for full-stack distributed systems verification
 
 # Important Notes
 
@@ -8822,6 +8970,149 @@ ${generateVerificationSection(context)}
   - 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
+  - **File Organization**: Constraints can be organized in separate files (e.g., specs/constraints.ts)
+  - **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
+
+# Elysia/Bun Integration
+
+Polly now provides first-class support for Elysia (Bun-first web framework) with Eden type-safe client generation:
+
+## Server-Side Middleware (\`@fairfox/polly/elysia\`)
+
+The \`polly()\` middleware adds distributed systems semantics to Elysia apps:
+
+**Key Features:**
+- **State Management**: Define client and server state signals
+- **Client Effects**: Specify what should happen on the client after server operations
+- **Authorization**: Route-level authorization rules
+- **Offline Behavior**: Configure optimistic updates and queueing
+- **WebSocket Broadcast**: Real-time updates to connected clients
+- **TLA+ Generation**: Automatic formal specification generation from routes + config
+
+**Example:**
+\`\`\`typescript
+import { Elysia, t } from 'elysia';
+import { polly } from '@fairfox/polly/elysia';
+import { $syncedState, $serverState } from '@fairfox/polly';
+
+const app = new Elysia()
+  .use(polly({
+    state: {
+      client: {
+        todos: $syncedState('todos', []),
+        user: $syncedState('user', null),
+      },
+      server: {
+        db: $serverState('db', db),
+      },
+    },
+    effects: {
+      'POST /todos': {
+        client: ({ result, state }) => {
+          state.client.todos.value = [...state.client.todos.value, result];
+        },
+        broadcast: true,  // Send to all connected clients
+      },
+    },
+    authorization: {
+      'POST /todos': ({ state }) => state.client.user.value !== null,
+    },
+    offline: {
+      'POST /todos': {
+        queue: true,
+        optimistic: (body) => ({ id: -Date.now(), ...body }),
+      },
+    },
+  }))
+  .post('/todos', handler, { body: t.Object({ text: t.String() }) });
+\`\`\`
+
+**Route Pattern Matching:**
+- Exact: \`'POST /todos'\`
+- Params: \`'GET /todos/:id'\`
+- Wildcard: \`'/todos/*'\`
+
+**Production Behavior:**
+- In development: Adds metadata to responses for hot-reload and debugging
+- In production: Pass-through (minimal overhead) - client effects are bundled at build time
+- Authorization and broadcasts work in both modes
+
+## Client-Side Wrapper (\`@fairfox/polly/client\`)
+
+Enhances Eden treaty client with Polly features:
+
+**Example:**
+\`\`\`typescript
+import { createPollyClient } from '@fairfox/polly/client';
+import { $syncedState } from '@fairfox/polly';
+import type { app } from './server';
+
+const clientState = {
+  todos: $syncedState('todos', []),
+  user: $syncedState('user', null),
+};
+
+export const api = createPollyClient<typeof app>('http://localhost:3000', {
+  state: clientState,
+  websocket: true,  // Enable real-time updates
+});
+
+// Use it (types are automatically inferred from server!)
+await api.todos.post({ text: 'Buy milk' });
+
+// Access Polly features
+console.log(api.$polly.state.isOnline.value);        // true/false
+console.log(api.$polly.state.queuedRequests.value);  // Queued requests
+api.$polly.sync();  // Manually sync queued requests
+\`\`\`
+
+**Key Features:**
+- Offline queueing with automatic retry
+- WebSocket connection for real-time updates
+- Lamport clock synchronization
+- Type inference from server via Eden
+
+## Why This Matters for Distributed Systems
+
+SPAs/PWAs are distributed systems facing classic problems:
+- **CAP theorem**: Must choose consistency vs availability during partitions
+- **Network unreliability**: The first fallacy of distributed computing
+- **Cache invalidation**: "One of the two hard things in computer science"
+- **Eventual consistency**: State sync across client/server
+- **Conflict resolution**: When multiple devices edit offline
+
+The Elysia integration addresses this by:
+1. Making distributed concerns explicit (offline, authorization, effects)
+2. Leveraging Eden for zero-duplication type safety
+3. Supporting verification via TLA+ generation from middleware config
+4. Providing WebSocket broadcast for real-time consistency
+
+## Architecture Pattern
+
+\`\`\`
+Browser (Client)
+  ├── Eden Treaty Client (types from Elysia)
+  ├── Polly Wrapper (offline, sync, WebSocket)
+  └── Client State ($syncedState)
+        │
+        │ HTTP / WebSocket
+        │
+Server (Elysia + Bun)
+  ├── Elysia Routes (normal routes)
+  ├── Polly Middleware (effects, auth, broadcast)
+  └── Server State ($serverState)
+\`\`\`
+
+## Best Practices
+
+1. **Separate Elysia is the contract** - Don't define types twice. Elysia routes define the API, Eden generates client types.
+2. **Effects describe client behavior** - Keep effects pure and deterministic.
+3. **Authorization at route level** - Centralize security rules in middleware config.
+4. **Queue selectively** - Only queue idempotent operations when offline.
+5. **Broadcast with filters** - Use broadcastFilter to target specific clients.
+6. **Generate TLA+ for verification** - Enable tlaGeneration in dev to verify distributed properties.
 
 Begin by understanding their question and providing a clear, precise answer based on their project context.`;
 }
@@ -8968,6 +9259,10 @@ to reduce verification time while maintaining or improving verification precisio
 and available in the current version of Polly. You can recommend any of these optimizations with
 confidence that they will work when users apply them to their configuration.
 
+**Code Organization**: The analyzer uses transitive import following to discover all reachable code.
+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.
+
 # Communication Style
 
 - Direct and precise - no fluff
@@ -9284,4 +9579,4 @@ Goodbye!`);
 }
 main();
 
-//# debugId=8BD8EAFF3D45D43B64756E2164756E21
+//# debugId=770FFA3847E6590364756E2164756E21