Cross-instance sync coverage

The hardest noggin bugs are the ones where two views of the same noggin disagree. They live at the intersection of two axes:

• Provider — where the bytes live (file://, memory://, localstorage://, future sqlite:// / http://).
• Topology — how many handles observe the same target, and what process boundary separates them.

This page maps every (provider × topology) cell to the test that pins its behaviour. A cell marked — with a reason isn't a gap: it's a combination that's structurally impossible (e.g. there's no "two processes" case for memory://, because each process has its own in-memory store).

When you add a new provider or change a notification mechanism, update this table along with the code. CI doesn't enforce it yet, but a stale row here is a strong signal that something in the contract has drifted.

Matrix

Contract tests that span all providers

Beyond the cells above, these tests pin the contract that every provider must honour:

Edge-case tests

These are narrower than the matrix cells — each pins a specific failure mode that doesn't fit neatly into "(provider, topology)" but has bitten us or could bite us:

Notes on the topology axis

• "Two handles, one process" is what openNoggin(url) × 2 must produce: two distinct handles backed by the same provider instance, with full convergence. The engine wrapper at createSharedHandle is what makes this work; pass { shared: false } to opt out.
• "Two handles via RPC" is two RemoteNoggin clients against one RpcServer against one underlying provider. The fan-out happens at the server: every subscription gets its own noggin.changed stream. This is the desktop renderer ↔ main, the extension webview ↔ host.
• "Two processes, one machine" is independent OS processes sharing a backing store. For file:// we rely on proper-lockfile for writes and fs.watch for reads.
• "Two browser tabs" is two same-origin browser windows sharing a localStorage slot. The DOM storage event delivers cross-tab, but never to the writing tab. Within one tab, two LocalStorageNoggin instances are kept coherent by the engine's openNoggin dedupe (covered by the "two handles, one process" cell).

When a new provider lands

1. Add a row of cells for the new scheme in the Matrix above.
2. Add the provider to provider-parity.test.mjs's FACTORIES array so the same-handle baseline runs.
3. Decide which topologies are structurally applicable. Skip the ones that aren't and document the reason in the cell. Don't leave a cell empty without a reason — empty cells look like gaps.
4. Add multi-instance and dispose coverage to multi-instance.test.mjs and dispose-semantics.test.mjs.
5. If the provider supports a notification mechanism (file watching, pub/sub, etc.), add an external-mutation test to external-change-cause.test.mjs.

The matrix is descriptive, not generative — there's no single test file that loops over every cell. Each cell links to where the relevant test actually lives. The reason is pragmatic: the test runners differ (node:test, vitest, Playwright) and the fixtures differ too. Forcing one uniform shape over all of them costs more than the visibility benefit returns. See the adversarial critique in the session log for the full reasoning.