@fairfox/polly 0.72.0 → 0.73.0

package/dist/tools/verify/specs/tla/MeshSeed.cfg

@@ -0,0 +1,27 @@
+SPECIFICATION Spec
+
+\* Three peers. The concurrent-seed race needs only two seeders; the
+\* third costs nothing and gives margin. The state space is tiny — each
+\* peer's slot moves once, from Unseeded to seeded — so TLC exhausts it
+\* instantly.
+\*
+\* SeedDeterministic = TRUE models the polly#113 fix. The verify CLI
+\* rewrites this constant to FALSE when POLLY_113_DISABLE_FIX is set, to
+\* falsify the guard: under FALSE, TLC must report a SeedConvergence
+\* violation.
+CONSTANTS
+    Peers = {peer_a, peer_b, peer_c}
+    SeedDeterministic = TRUE
+
+\* MeshSeed is a terminating protocol: once every peer has seeded, no
+\* action is enabled. That terminal state is the goal, not a deadlock
+\* bug, so deadlock checking is disabled — EventuallySeeded is the
+\* property that asserts the protocol actually reaches it.
+CHECK_DEADLOCK FALSE
+
+INVARIANTS
+    TypeOK
+    SeedConvergence
+
+PROPERTIES
+    EventuallySeeded

package/dist/tools/verify/specs/tla/MeshSeed.tla

@@ -0,0 +1,179 @@
+-------------------------- MODULE MeshSeed --------------------------
+(*
+  Formal specification of Polly's $meshState concurrent first-time seed.
+
+  This spec exists to close the polly#114 gap: the polly#113 concurrent-
+  seed race lived entirely outside the verify and visualise pipelines, so
+  "all green" told a mesh-using consumer nothing about it. MeshSeed makes
+  the seed path a first-class, model-checked property.
+
+  The race
+  --------
+
+  When a device first reads a $meshState document it materialises the
+  document against empty local storage — the loadOrSeed path in
+  mesh-state.ts. If two devices do this concurrently for the same logical
+  key, each writes its own copy of the initial document.
+
+  - Pre-fix, loadOrSeed used `Automerge.from(initialDoc)`, which stamps
+    the seed change with a fresh random actorId and a `Date.now()`
+    timestamp. Two devices therefore produce two *distinct* Automerge
+    documents — same logical content, different identity. They have no
+    common ancestor, so a later sync cannot reconcile them: the two
+    seeds coexist as a permanent fork.
+
+  - The polly#113 fix switched loadOrSeed to
+    `Automerge.init({ actor: deriveSeedActor(docId) })` plus
+    `Automerge.change(doc, { time: 0 }, …)`. The actor is derived from
+    the docId and the change time is fixed, so every device seeding the
+    same key produces byte-identical content — literally the same
+    document. There is nothing to reconcile.
+
+  Model
+  -----
+
+  `SeedDeterministic` is the spec's single knob. TRUE models the
+  polly#113 fix; FALSE restores the pre-fix behaviour — the same toggle
+  the `POLLY_113_DISABLE_FIX` environment variable exposes in
+  seedDocumentBytes. The verify CLI flips this constant when the
+  environment variable is set, so a regression in the seed path is
+  caught here as a TLC counterexample rather than only by a hand-written
+  unit test.
+
+  - `doc[p]` is peer p's copy of the document, or `Unseeded` before it
+    has materialised one.
+
+  - `SeedValue(p)` is the content peer p writes when it seeds. Under the
+    fix it is a single shared constant (all peers agree); pre-fix it is
+    tagged by the seeding peer (every peer differs). The pre-fix model
+    treats every peer's seed as distinct: a specification must withstand
+    what is *possible*, and pre-fix divergence is possible, so the worst
+    case is the honest one. A nondeterministic seed choice would only
+    multiply states without adding insight — the divergent branch is
+    what matters and TLC explores it either way.
+
+  - `Sync` delivers a seeded document to a peer that holds none. A peer
+    that has already seeded independently is never overwritten: its
+    document and the remote one have no common ancestor, so no merge
+    reconciles them. Modelling the fork this way is sound for the safety
+    property below — `SeedConvergence` is violated the moment two peers
+    hold distinct documents, and no later step can un-violate a safety
+    invariant TLC has already reported.
+
+  One document is enough
+  ----------------------
+
+  The polly#113 race is per-docId. Distinct $meshState documents seed
+  through independent loadOrSeed calls, hold independent storage entries,
+  and never share state — there is no action by which one document's
+  seed influences another's. A model of one document is therefore a
+  sound representative of any number of them: the reachable seed/sync
+  interleavings of N independent documents are exactly the product of
+  N copies of this model, and a safety invariant that holds on one copy
+  holds on the product. Modelling one document keeps the state space
+  minimal without weakening the result.
+
+  Properties verified
+  -------------------
+
+  1. TypeOK — type safety across every transition.
+
+  2. SeedConvergence — every peer that holds the document holds the same
+     one. Under the fix this is invariant. Pre-fix, the trace
+     `Seed(p)` then `Seed(q)` reaches a state where p and q hold
+     distinct documents and the invariant fails — that failure is the
+     polly#113 race, surfaced by model checking.
+
+  3. EventuallySeeded (liveness) — every peer eventually materialises
+     the document. Holds under both settings of SeedDeterministic; it
+     is the property that earns the WF_vars(Next) fairness conjunct.
+     Weak fairness on the whole next-state relation suffices because the
+     model is monotone: every step moves one peer from Unseeded to
+     seeded and none ever back, so no step can be starved of progress.
+*)
+
+CONSTANTS
+    Peers,              \* Set of mesh peer identifiers
+    SeedDeterministic   \* TRUE = polly#113 fix; FALSE = pre-fix seed race
+
+VARIABLES
+    doc                 \* [Peers -> SeedValues \cup {Unseeded}]
+
+vars == <<doc>>
+
+\* A peer that has not yet materialised the document.
+Unseeded == "unseeded"
+
+\* The content a peer writes when it first seeds the document. Under the
+\* fix every peer produces the same bytes, so the value is one shared
+\* constant; pre-fix each peer produces a distinct document, modelled as
+\* a value tagged by the seeding peer.
+SeedValue(p) == IF SeedDeterministic THEN "seed" ELSE p
+
+\* The set of all possible seeded values, for the type invariant.
+SeedValues == IF SeedDeterministic THEN {"seed"} ELSE Peers
+
+-----------------------------------------------------------------------------
+
+(* Initial state: no peer has materialised the document. *)
+
+Init ==
+    doc = [p \in Peers |-> Unseeded]
+
+-----------------------------------------------------------------------------
+
+(* Actions *)
+
+(* A peer materialises the document for the first time against empty
+   local storage — Polly's $meshState loadOrSeed path. *)
+Seed(p) ==
+    /\ doc[p] = Unseeded
+    /\ doc' = [doc EXCEPT ![p] = SeedValue(p)]
+
+(* Sync delivers a seeded peer's document to a peer that holds none.
+   A peer that has already seeded independently is never overwritten —
+   see the header note on why that is sound for SeedConvergence. *)
+Sync(src, dst) ==
+    /\ src # dst
+    /\ doc[src] # Unseeded
+    /\ doc[dst] = Unseeded
+    /\ doc' = [doc EXCEPT ![dst] = doc[src]]
+
+-----------------------------------------------------------------------------
+
+(* Next-state relation *)
+
+Next ==
+    \/ \E p \in Peers : Seed(p)
+    \/ \E src, dst \in Peers : Sync(src, dst)
+
+Spec == Init /\ [][Next]_vars /\ WF_vars(Next)
+
+-----------------------------------------------------------------------------
+
+(* Invariants *)
+
+(* Type safety: every peer's slot is Unseeded or a valid seeded value. *)
+TypeOK ==
+    doc \in [Peers -> SeedValues \cup {Unseeded}]
+
+(* Seed convergence: every peer that holds the document holds the same
+   one. Under the polly#113 fix (SeedDeterministic = TRUE) this is
+   invariant. Pre-fix (FALSE) the trace Seed(p) ; Seed(q) reaches a
+   state where p and q hold distinct documents and TLC reports the
+   violation — that is the polly#113 race. *)
+SeedConvergence ==
+    \A p, q \in Peers :
+        (doc[p] # Unseeded /\ doc[q] # Unseeded) => doc[p] = doc[q]
+
+-----------------------------------------------------------------------------
+
+(* Liveness *)
+
+(* Every peer eventually materialises the document. Holds under both
+   settings of SeedDeterministic — see the header note on why weak
+   fairness on Next suffices for this monotone model. *)
+EventuallySeeded ==
+    <>(\A p \in Peers : doc[p] # Unseeded)
+
+=============================================================================

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

@@ -1,7 +1,7 @@
 # TLA+ Formal Specifications for Polly
 
 This directory contains formal specifications for Polly's distributed
-protocols using TLA+ (Temporal Logic of Actions). There are three specs:
+protocols using TLA+ (Temporal Logic of Actions). There are four specs:
 
 - **MessageRouter.tla** — the original message-routing spec for the web
   extension's cross-context message bus. Single-writer, routing-focused,
@@ -21,6 +21,16 @@ protocols using TLA+ (Temporal Logic of Actions). There are three specs:
   peer is revoked, honest peers drop its future ops), and no-fabrication
   (every op in any replica has a known producer).
 
+- **MeshSeed.tla** — the `$meshState` concurrent first-time seed
+  (polly#114). Model-checks the polly#113 race: two devices materialising
+  the same document concurrently against empty storage. Its single
+  `SeedDeterministic` constant is TRUE for the shipped fix and FALSE for
+  the pre-fix seed; under FALSE, TLC reports a `SeedConvergence`
+  violation. The verify CLI runs this spec whenever a project declares
+  `mesh:` documents and flips the constant when `POLLY_113_DISABLE_FIX`
+  is set, so a regression in `seedDocumentBytes` cannot land green.
+  `scripts/e2e-verify-mesh-seed.ts` runs both directions through TLC.
+
 Each spec has a companion `.cfg` file with the small bounded constants
 TLC uses when model-checking the spec exhaustively.
 

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

@@ -7535,6 +7535,20 @@ async function analyzeCodebase(options) {
   const extractor = new TypeExtractor(options.tsConfigPath);
   return extractor.analyzeCodebase(options.stateFilePath);
 }
+// tools/verify/src/runner/mesh-seed.ts
+function meshSeedCfg(baseCfg, opts) {
+  if (!opts.disableFix)
+    return baseCfg;
+  const declaration = /^([ \t]*)SeedDeterministic = TRUE[ \t]*$/m;
+  if (!declaration.test(baseCfg)) {
+    throw new Error("MeshSeed.cfg no longer declares `SeedDeterministic = TRUE` on its own line — the polly#114 seed-race guard cannot be falsified. Update tools/verify/src/runner/mesh-seed.ts.");
+  }
+  return baseCfg.replace(declaration, "$1SeedDeterministic = FALSE");
+}
+function isSeedFixDisabled(env = process.env) {
+  return env["POLLY_113_DISABLE_FIX"] === "1";
+}
+
 // tools/verify/src/cli.ts
 var __dirname = "/Users/AJT/projects/polly/packages/polly/tools/verify/src";
 var COLORS = {
@@ -7921,6 +7935,17 @@ async function runMonolithicVerification(config, analysis) {
     timeout: timeoutSeconds > 0 ? timeoutSeconds * 1000 : undefined,
     maxDepth
   });
+  const meshSeed = await runMeshSeedGuard(docker, specDir, config);
+  if (meshSeed && !meshSeed.success) {
+    console.log(color(`
+❌ Mesh seed-race guard failed (polly#113 / polly#114)
+`, COLORS.red));
+    displayVerificationResults(meshSeed, specDir);
+  }
+  if (meshSeed) {
+    console.log(color(`✓ Mesh seed-race guard passed (MeshSeed.tla)
+`, COLORS.green));
+  }
   displayVerificationResults(result, specDir);
 }
 async function runSubsystemVerification(config, analysis) {
@@ -8131,6 +8156,35 @@ function findAndCopyBaseSpec(specDir) {
     }
   }
 }
+function findMeshSeedSpecDir() {
+  const candidates = [
+    path4.join(process.cwd(), "specs", "tla"),
+    path4.join(__dirname, "..", "specs", "tla"),
+    path4.join(__dirname, "..", "..", "specs", "tla"),
+    path4.join(process.cwd(), "node_modules", "@fairfox", "polly-verify", "specs", "tla")
+  ];
+  for (const dir of candidates) {
+    if (fs4.existsSync(path4.join(dir, "MeshSeed.tla")))
+      return dir;
+  }
+  return null;
+}
+async function runMeshSeedGuard(docker, specDir, config) {
+  const mesh = config.mesh;
+  if (!mesh || Object.keys(mesh).length === 0)
+    return;
+  const sourceDir = findMeshSeedSpecDir();
+  if (!sourceDir) {
+    console.log(color("⚠️  MeshSeed.tla not found — skipping seed-race guard", COLORS.yellow));
+    return;
+  }
+  const fixDisabled = isSeedFixDisabled();
+  fs4.copyFileSync(path4.join(sourceDir, "MeshSeed.tla"), path4.join(specDir, "MeshSeed.tla"));
+  const baseCfg = fs4.readFileSync(path4.join(sourceDir, "MeshSeed.cfg"), "utf8");
+  fs4.writeFileSync(path4.join(specDir, "MeshSeed.cfg"), meshSeedCfg(baseCfg, { disableFix: fixDisabled }));
+  console.log(color(`⚙️  Running mesh seed-race guard (MeshSeed.tla, SeedDeterministic = ${fixDisabled ? "FALSE" : "TRUE"})...`, COLORS.blue));
+  return docker.runTLC(path4.join(specDir, "MeshSeed.tla"), { workers: 1 });
+}
 async function setupDocker() {
   const { DockerRunner: DockerRunner2 } = await Promise.resolve().then(() => (init_docker(), exports_docker));
   console.log(color("\uD83D\uDC33 Checking Docker...", COLORS.blue));
@@ -8287,4 +8341,4 @@ main().catch((error) => {
   process.exit(1);
 });
 
-//# debugId=15266168B7768F5064756E2164756E21
+//# debugId=30F069FEDCAB85F764756E2164756E21