@fairfox/polly 0.2.0 → 0.3.0

package/dist/vendor/verify/specs/Dockerfile

@@ -0,0 +1,13 @@
+FROM tlaplus/tla:latest
+
+# Install additional tools for better DX
+RUN apk add --no-cache \
+    bash \
+    vim \
+    less \
+    tree
+
+WORKDIR /specs
+
+# Default command: keep container alive for exec commands
+CMD ["tail", "-f", "/dev/null"]

package/dist/vendor/verify/specs/README.md

@@ -0,0 +1,37 @@
+# Verification Specifications
+
+This directory contains formal specifications and verification configurations for the `@fairfox/polly-verify` package.
+
+## Contents
+
+### `verification.config.ts`
+Example verification configuration demonstrating how to use the verify package with web extensions.
+
+### `tla/`
+TLA+ specifications for formal verification:
+- `MessageRouter.tla` - TLA+ specification of the message routing system
+- `MessageRouter.cfg` - TLC model checker configuration
+- `README.md` - Documentation for running TLA+ verification
+
+### Docker Setup
+- `Dockerfile` - Container setup for TLA+ toolchain
+- `docker-compose.yml` - Docker Compose configuration for running verification
+
+## Running Verification
+
+### With Docker (Recommended)
+```bash
+cd packages/verify/specs
+docker-compose up
+```
+
+### With TLC Directly
+```bash
+cd packages/verify/specs/tla
+tlc MessageRouter.tla -config MessageRouter.cfg
+```
+
+## See Also
+- [Verify Package Documentation](../README.md)
+- [WebSocket Example](../examples/websocket-app/README.md)
+- [TLA+ Specifications](./tla/README.md)

package/dist/vendor/verify/specs/docker-compose.yml

@@ -0,0 +1,9 @@
+services:
+  tla:
+    build: .
+    container_name: web-ext-tla
+    volumes:
+      - ./tla:/specs
+    working_dir: /specs
+    stdin_open: true
+    tty: true

package/dist/vendor/verify/specs/tla/MessageRouter.cfg

@@ -0,0 +1,24 @@
+SPECIFICATION Spec
+
+\* Constants
+CONSTANTS
+    Contexts = {background, content, popup}
+    MaxMessages = 4
+    MaxTabId = 2
+    TimeoutLimit = 3
+
+\* Invariants to check
+INVARIANTS
+    TypeOK
+    NoRoutingLoops
+    DeliveredWerePending
+    NoOrphanedRequests
+
+\* Properties to check
+PROPERTIES
+    EventualResolution
+    ConnectedEventuallyDelivers
+
+\* State constraint (keep state space manageable)
+CONSTRAINT
+    Len(messages) <= MaxMessages

package/dist/vendor/verify/specs/tla/MessageRouter.tla

@@ -0,0 +1,221 @@
+------------------------- MODULE MessageRouter -------------------------
+(*
+  Formal specification of the web extension MessageRouter.
+
+  This spec models the core message routing behavior across extension contexts:
+  - Background service worker (central hub)
+  - Content scripts (one per tab)
+  - DevTools, Popup, Options (UI contexts)
+
+  Key properties verified:
+  1. No routing loops
+  2. Messages eventually deliver (if port connected)
+  3. All pending requests eventually resolve (success/timeout/disconnect)
+  4. Port cleanup is complete
+*)
+
+EXTENDS Integers, Sequences, FiniteSets, TLC
+
+CONSTANTS
+    Contexts,           \* Set of all contexts: {"background", "content", "popup", ...}
+    MaxMessages,        \* Bound on number of messages (for model checking)
+    MaxTabId,           \* Maximum tab ID
+    TimeoutLimit        \* Message timeout threshold
+
+VARIABLES
+    ports,              \* Port state: [context -> "connected" | "disconnected"]
+    messages,           \* Sequence of messages in flight
+    pendingRequests,    \* Map: messageId -> {sender, target, timestamp}
+    delivered,          \* Set of delivered message IDs
+    routingDepth,       \* Current routing depth (for loop detection)
+    time                \* Logical clock
+
+vars == <<ports, messages, pendingRequests, delivered, routingDepth, time>>
+
+-----------------------------------------------------------------------------
+
+(* Type definitions *)
+
+ContextType == {"background", "content", "popup", "devtools", "options", "offscreen"}
+PortState == {"connected", "disconnected"}
+MessageStatus == {"pending", "routing", "delivered", "failed", "timeout"}
+
+Message == [
+    id: Nat,
+    source: ContextType,
+    targets: SUBSET ContextType,  \* Set of target contexts (can be multiple)
+    tabId: Nat,
+    msgType: STRING,  \* Message type for handler dispatch
+    status: MessageStatus,
+    timestamp: Nat
+]
+
+-----------------------------------------------------------------------------
+
+(* Initial state *)
+
+Init ==
+    /\ ports = [c \in Contexts |-> "disconnected"]
+    /\ messages = <<>>
+    /\ pendingRequests = [id \in {} |-> {}]
+    /\ delivered = {}
+    /\ routingDepth = 0
+    /\ time = 0
+
+-----------------------------------------------------------------------------
+
+(* Actions *)
+
+(* A context connects a port *)
+ConnectPort(context) ==
+    /\ ports[context] = "disconnected"
+    /\ ports' = [ports EXCEPT ![context] = "connected"]
+    /\ UNCHANGED <<messages, pendingRequests, delivered, routingDepth, time>>
+
+(* A context disconnects *)
+DisconnectPort(context) ==
+    /\ ports[context] = "connected"
+    /\ ports' = [ports EXCEPT ![context] = "disconnected"]
+    \* Clean up pending requests that target this context
+    /\ LET failedRequests == {id \in DOMAIN pendingRequests :
+                               context \in pendingRequests[id].targets}
+       IN pendingRequests' = [id \in DOMAIN pendingRequests \ failedRequests |->
+                               pendingRequests[id]]
+    /\ UNCHANGED <<messages, delivered, routingDepth, time>>
+
+(* Send a message from source to one or more targets *)
+SendMessage(source, targetSet, tabId, messageType) ==
+    /\ ports[source] = "connected"
+    /\ Len(messages) < MaxMessages
+    /\ routingDepth = 0  \* Only send at top level (no recursive sends)
+    /\ targetSet # {}    \* Must have at least one target
+    /\ LET newId == Len(messages) + 1
+           newMsg == [
+               id |-> newId,
+               source |-> source,
+               targets |-> targetSet,
+               tabId |-> tabId,
+               msgType |-> messageType,
+               status |-> "pending",
+               timestamp |-> time
+           ]
+       IN /\ messages' = Append(messages, newMsg)
+          /\ pendingRequests' = pendingRequests @@
+                                (newId :> [sender |-> source,
+                                          targets |-> targetSet,
+                                          timestamp |-> time])
+          /\ time' = time + 1
+          /\ UNCHANGED <<ports, delivered, routingDepth>>
+
+(* Route a message to one of its targets *)
+RouteMessage(msgIndex) ==
+    /\ msgIndex \in 1..Len(messages)
+    /\ LET msg == messages[msgIndex]
+       IN /\ msg.status = "pending"
+          /\ routingDepth' = routingDepth + 1
+          /\ routingDepth < 5  \* Safety bound: detect loops
+          /\ \* Non-deterministically choose a target from the targets set
+             \E target \in msg.targets :
+                /\ IF target \in Contexts /\ ports[target] = "connected"
+                   THEN \* Successful delivery to this target
+                        /\ messages' = [messages EXCEPT ![msgIndex].status = "delivered"]
+                        /\ delivered' = delivered \union {msg.id}
+                        /\ pendingRequests' = [id \in DOMAIN pendingRequests \ {msg.id} |->
+                                               pendingRequests[id]]
+                        /\ time' = time + 1
+                   ELSE \* Port not connected or invalid target, message fails
+                        /\ messages' = [messages EXCEPT ![msgIndex].status = "failed"]
+                        /\ pendingRequests' = [id \in DOMAIN pendingRequests \ {msg.id} |->
+                                               pendingRequests[id]]
+                        /\ time' = time + 1
+                        /\ UNCHANGED delivered
+          /\ UNCHANGED ports
+
+(* Complete routing (reset depth) *)
+CompleteRouting ==
+    /\ routingDepth > 0
+    /\ routingDepth' = 0
+    /\ UNCHANGED <<ports, messages, pendingRequests, delivered, time>>
+
+(* Handle message timeout *)
+TimeoutMessage(msgIndex) ==
+    /\ msgIndex \in 1..Len(messages)
+    /\ LET msg == messages[msgIndex]
+       IN /\ msg.status = "pending"
+          /\ time - msg.timestamp > TimeoutLimit
+          /\ messages' = [messages EXCEPT ![msgIndex].status = "timeout"]
+          /\ pendingRequests' = [id \in DOMAIN pendingRequests \ {msg.id} |->
+                                 pendingRequests[id]]
+          /\ time' = time + 1
+          /\ UNCHANGED <<ports, delivered, routingDepth>>
+
+-----------------------------------------------------------------------------
+
+(* Next state relation *)
+
+Next ==
+    \/ \E c \in Contexts : ConnectPort(c)
+    \/ \E c \in Contexts : DisconnectPort(c)
+    \/ \E src \in Contexts : \E targetSet \in (SUBSET Contexts \ {{}}) : \E tab \in 0..MaxTabId : \E msgType \in {"msg1", "msg2"} : SendMessage(src, targetSet, tab, msgType)
+    \/ \E i \in 1..Len(messages) : RouteMessage(i)
+    \/ CompleteRouting
+    \/ \E i \in 1..Len(messages) : TimeoutMessage(i)
+
+Spec == Init /\ [][Next]_vars /\ WF_vars(Next)
+
+-----------------------------------------------------------------------------
+
+(* Invariants *)
+
+(* CRITICAL: No infinite routing loops *)
+NoRoutingLoops ==
+    routingDepth < 3
+
+(* All delivered messages were actually pending *)
+DeliveredWerePending ==
+    \A msgId \in delivered :
+        \E i \in 1..Len(messages) : messages[i].id = msgId
+
+(* No orphaned pending requests - every pending request has a corresponding message *)
+NoOrphanedRequests ==
+    \A reqId \in DOMAIN pendingRequests :
+        \E i \in 1..Len(messages) :
+            /\ messages[i].id = reqId
+            /\ messages[i].status \in {"pending", "routing"}
+
+(* Messages to disconnected ports eventually fail *)
+DisconnectedPortsFail ==
+    \A i \in 1..Len(messages) :
+        LET msg == messages[i]
+        IN (msg.status = "pending" /\ \A target \in msg.targets : ports[target] = "disconnected")
+           => (time - msg.timestamp > TimeoutLimit => msg.status \in {"failed", "timeout"})
+
+(* Type invariant *)
+TypeOK ==
+    /\ ports \in [Contexts -> PortState]
+    /\ \A i \in 1..Len(messages) :
+        /\ messages[i].source \in Contexts
+        /\ messages[i].targets \subseteq Contexts
+        /\ messages[i].targets # {}
+        /\ messages[i].status \in MessageStatus
+    /\ routingDepth >= 0
+    /\ time >= 0
+
+-----------------------------------------------------------------------------
+
+(* Temporal properties *)
+
+(* Eventually, all messages resolve (deliver, fail, or timeout) *)
+EventualResolution ==
+    \A i \in 1..Len(messages) :
+        messages[i].status = "pending"
+        ~> messages[i].status \in {"delivered", "failed", "timeout"}
+
+(* If ports are connected and message is sent to them, message eventually delivers *)
+ConnectedEventuallyDelivers ==
+    \A i \in 1..Len(messages) :
+        LET msg == messages[i]
+        IN (msg.status = "pending" /\ \A target \in msg.targets : ports[target] = "connected")
+           ~> (msg.status = "delivered")
+
+=============================================================================

package/dist/vendor/verify/specs/tla/README.md

@@ -0,0 +1,179 @@
+# TLA+ Formal Specification for MessageRouter
+
+This directory contains formal specifications for the web extension's message routing system using TLA+ (Temporal Logic of Actions).
+
+## What is This?
+
+TLA+ is a formal specification language for concurrent and distributed systems. It allows us to:
+- **Model** the message routing logic mathematically
+- **Verify** properties like "no routing loops" or "messages eventually deliver"
+- **Find edge cases** that are hard to catch with traditional testing
+- **Document** the system behavior precisely
+
+## What We're Verifying
+
+### Core Properties
+
+1. **NoRoutingLoops** - Messages never create infinite routing cycles
+2. **EventualResolution** - Every message eventually resolves (delivers, fails, or times out)
+3. **ConnectedEventuallyDelivers** - Messages to connected ports eventually deliver
+4. **NoOrphanedRequests** - Pending requests always have corresponding messages
+5. **TypeOK** - All data structures maintain correct types
+
+### System Model
+
+The spec models:
+- **Contexts**: background, content, popup, devtools, options, offscreen
+- **Port lifecycle**: disconnected ⇒ connected ⇒ disconnected
+- **Message states**: pending → routing → delivered/failed/timeout
+- **Routing depth tracking** (for loop detection)
+- **Timeout handling**
+- **Broadcast semantics**
+
+## Running the Model Checker
+
+### Prerequisites
+
+Docker must be running. The TLA+ toolchain runs in a container.
+
+### Quick Start
+
+```bash
+# From project root
+bun run tla:up       # Start container
+bun run tla:check    # Run model checker
+bun run tla:down     # Stop container
+```
+
+### Manual Commands
+
+```bash
+# Start the TLA+ container
+docker-compose -f specs/docker-compose.yml up -d
+
+# Run the model checker
+docker-compose -f specs/docker-compose.yml exec tla tlc MessageRouter.tla
+
+# Interactive shell (for exploring)
+docker-compose -f specs/docker-compose.yml exec tla sh
+
+# Stop the container
+docker-compose -f specs/docker-compose.yml down
+```
+
+## Understanding the Output
+
+### Success
+```
+TLC2 Version X.X.X
+...
+Model checking completed. No error has been found.
+  Estimates of the probability that TLC did not check all reachable states
+  because two distinct states had the same fingerprint:
+  calculated (optimistic):  val = X.X%
+...
+Finished in XXms at (YYYY-MM-DD HH:MM:SS)
+```
+
+### Violation Found
+TLC will print:
+- **Which invariant was violated**
+- **The execution trace** (sequence of states) leading to the violation
+- Each state shows the values of all variables
+
+Example:
+```
+Error: Invariant NoRoutingLoops is violated.
+
+State 1: <Initial State>
+/\ ports = ...
+/\ routingDepth = 0
+...
+
+State 2: <ConnectPort("background")>
+/\ ports = [background |-> "connected", ...]
+...
+
+State 3: <SendMessage("background", "content", 1)>
+...
+```
+
+## Editing the Spec
+
+### Files
+
+- **MessageRouter.tla** - Main specification (edit this)
+- **MessageRouter.cfg** - Model configuration (constants, invariants to check)
+
+### Workflow
+
+1. Edit `.tla` file locally (syntax highlighting via VSCode TLA+ extension)
+2. Save changes (files are volume-mounted into container)
+3. Run `bun run tla:check`
+4. Iterate on violations
+
+### Expanding the Model
+
+Current model is intentionally simple (3 contexts, 4 messages max). To expand:
+
+1. **Add more contexts**: Edit `MessageRouter.cfg`:
+   ```
+   Contexts = {background, content, popup, devtools, options}
+   ```
+
+2. **Increase message limit**: (Warning: state space grows exponentially!)
+   ```
+   MaxMessages = 6
+   ```
+
+3. **Add new properties**: Define in `.tla`, add to `.cfg` under `INVARIANTS` or `PROPERTIES`
+
+4. **Model request/response pairing**: Extend `Message` type with response IDs
+
+## Performance Notes
+
+Model checking explores **all possible states**. State space grows exponentially with:
+- Number of contexts
+- Number of messages
+- Number of tabs
+
+Current settings (3 contexts, 4 messages) check ~10,000 states in <1 second.
+
+Increasing to 5 contexts + 6 messages = ~1 million states = ~10 seconds.
+
+## Relationship to Code
+
+The spec is **not** the implementation - it's a mathematical model.
+
+**Code → Spec mapping:**
+- `MessageRouter.routeMessage()` → `RouteMessage` action
+- `port.onDisconnect()` → `DisconnectPort` action
+- `pendingRequests` Map → `pendingRequests` variable
+- "no loops" tests → `NoRoutingLoops` invariant
+
+**Use TLA+ to:**
+1. Find edge cases → Add as unit tests
+2. Verify design before implementing
+3. Document complex concurrent behavior
+
+**Don't use TLA+ for:**
+- Testing implementation details (use bun test)
+- Performance testing
+- Browser API quirks
+
+## Learning Resources
+
+- [TLA+ Home](https://lamport.azurewebsites.net/tla/tla.html)
+- [Learn TLA+](https://learntla.com/)
+- [Practical TLA+](https://www.apress.com/gp/book/9781484238288) (book)
+- [TLA+ Video Course](https://lamport.azurewebsites.net/video/videos.html)
+
+## Next Steps
+
+Potential expansions:
+- [ ] Model request/response pairing with IDs
+- [ ] Model port reconnection scenarios
+- [ ] Add tabId-specific routing
+- [ ] Model MessageBus interaction
+- [ ] Verify broadcast reaches all ports exactly once
+- [ ] Model race conditions during port disconnect

package/dist/vendor/verify/specs/verification.config.ts

@@ -0,0 +1,61 @@
+// ═══════════════════════════════════════════════════════════════
+// Verification Configuration
+// ═══════════════════════════════════════════════════════════════
+//
+// This file configures TLA+ verification for your extension.
+// Some values are auto-configured, others need your input.
+//
+// Look for:
+//   • /* CONFIGURE */ - Replace with your value
+//   • /* REVIEW */ - Check the auto-generated value
+//   • null - Must be replaced with a concrete value
+//
+// Run 'bun verify' to check for incomplete configuration.
+// Run 'bun verify --setup' for interactive help.
+//
+
+import { defineVerification } from '../src/index'
+
+export default defineVerification({
+  state: {
+  },
+
+  messages: {
+    // Maximum messages in flight simultaneously across all contexts.
+    // Higher = more realistic concurrency, but exponentially slower.
+    //
+    // Recommended values:
+    //   • 2-3: Fast verification (< 10 seconds)
+    //   • 4-6: Balanced (10-60 seconds)
+    //   • 8+: Thorough but slow (minutes)
+    //
+    // WARNING: State space grows exponentially! Start small.
+    maxInFlight: 3,
+
+    // Maximum tab IDs to model (content scripts are per-tab).
+    //
+    // Recommended:
+    //   • 0-1: Most extensions (single tab or tab-agnostic)
+    //   • 2-3: Multi-tab coordination
+    //
+    // Start with 0 or 1 for faster verification.
+    maxTabs: 1,
+  },
+
+  // Verification behavior
+  // ─────────────────────
+  //
+  // onBuild: What to do during development builds
+  //   • 'warn' - Show warnings but don't fail (recommended)
+  //   • 'error' - Fail the build on violations
+  //   • 'off' - Skip verification
+  //
+  onBuild: 'warn',
+
+  // onRelease: What to do during production builds
+  //   • 'error' - Fail the build on violations (recommended)
+  //   • 'warn' - Show warnings but don't fail
+  //   • 'off' - Skip verification
+  //
+  onRelease: 'error',
+})