garethpaul/poe-games-procedural-dungeons / .claude/skills/synced-store
synced-store
VerifiedBuild apps that USE synced-store for real-time multiplayer state. PROACTIVELY load when: designing a new Poe tile's state/schema (even before any file exists), discussing how to hide, gate, or restrict visibility of data to specific users or to the server, writing schema.ts/mutators/*.ts/client-config.ts/backend-config.ts for a Poe tile, using createPoeTileTestHarness, calling store.subscribe/store.mutate, or wiring entry.tsx with setupStore.
references/testing-race-conditions.md
View on GitHub<!-- owner: jyoung-q -->
# Testing: Race Conditions
Real networks deliver messages out of order. The test harness lets you reproduce these scenarios deterministically. See [testing-network-control.md](testing-network-control.md) for the base controlled-client setup.
## Poke Arrives Before Push Response
A classic race: the server broadcasts a poke (containing the result of our own mutation) before the client receives the push response acknowledging that mutation. Use `flushMatching` to deliver messages in a specific order:
```typescript
import { hasInboundType } from "poe-tiles-sdk/v1/test-utils.js";
test("poke arrives before push response", async () => {
const { store, transport } = await harness.createControlledClient();
await transport.flushUntil(store.waitForServerData());
transport.outbound.disableAutoFlush();
transport.inbound.disableAutoFlush();
const { confirmed } = await store.mutate.setValue({
key: "race",
value: "value",
});
// Send the push request to the server
await transport.outbound.flushNext();
// Deliver the poke BEFORE the push response
await transport.inbound.flushMatching(hasInboundType("poke"));
await transport.inbound.flushMatching(hasInboundType("push_response"));
await confirmed;
const value = await store.query((tx) => tx.table("data").get("race"));
expect(value).toBe("value");
expect(store.getPendingCount()).toBe(0);
harness.dispose();
});
```
`flushMatching` reorders the queue to deliver the first message matching the predicate, leaving other messages in place. This is the key tool for testing message reordering.
## Concurrent Mutations from Multiple Clients
Two clients mutating simultaneously must converge to the same final state:
```typescript
test("concurrent mutations from multiple clients", async () => {
const alice = await harness.createControlledClient({ userId: "alice" });
const bob = await harness.createControlledClient({ userId: "bob" });
// Initialize both clients
await Promise.all([
alice.transport.flushUntil(alice.store.waitForServerData()),
bob.transport.flushUntil(bob.store.waitForServerData()),
]);
// Both clients mutate before either flushes
await alice.store.mutate.increment({ key: "counter", amount: 1 });
await bob.store.mutate.increment({ key: "counter", amount: 1 });
// Step both clients through their network queues
await Promise.all([alice.transport.step(), bob.transport.step()]);
// Step again to deliver cross-client pokes
await Promise.all([alice.transport.step(), bob.transport.step()]);
const value = await alice.store.query((tx) => tx.table("data").get("counter"));
expect(value).toBe(2);
harness.dispose();
});
```
## Pattern
1. `disableAutoFlush()` on both directions.
2. Drive mutations from each client.
3. Use `flushMatching`, `flushNext`, or `step` to deliver messages in the order you want.
4. Assert convergence at the end.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |