delegate round 35: unified mesh specs complete (TASK-056 through TASK-062)

Author: subtleGradient

.tasks/DELEGATE_WORK_HANDOFF.md

@@ -328,3 +328,53 @@ Running 18 tests using 2 workers
 **Known gaps / unverified claims**
 - TypeScript packages have type errors (visible in project diagnostics) — these are pre-existing from Round 32, not introduced by this round
 - No coverage captured
+
+---
+
+## Round 2025-12-16 (35) — Unified mesh specs complete
+
+**Tasks executed**
+- `.tasks/done/TASK-057-unify-mesh-requirements.md`
+- `.tasks/done/TASK-058-unify-mesh-design.md`
+- `.tasks/done/TASK-059-unify-mesh-plan.md`
+- `.tasks/done/TASK-060-redirect-protocol-spec.md`
+- `.tasks/done/TASK-061-redirect-transport-spec.md`
+- `.tasks/done/TASK-062-redirect-runtime-spec.md`
+
+**Commits**
+- `bf2400ced` (effect-native) — unify mesh specs: requirements, design, plan + redirect notices (Round 35)
+- `54fa767f` (root) — delegate round 35: unified mesh specs complete (TASK-056 through TASK-062)
+
+**Modified files (effect-native submodule)**
+- `.specs/crsql-mesh/requirements.md` (+328 lines) — unified product requirements including browser multi-tab
+- `.specs/crsql-mesh/design.md` (+126 lines) — unified product design including browser multi-tab sketch
+- `.specs/crsql-mesh/plan.md` (+96 lines) — unified RGRTDD plan including browser multi-tab slices
+- `.specs/crsql-mesh/instructions.md` (+21 lines) — minor updates
+- `.specs/crsql-mesh-protocol/instructions.md` (+6 lines) — redirect notice
+- `.specs/crsql-mesh-transport/instructions.md` (+6 lines) — redirect notice
+- `.specs/crsql-mesh-runtime/instructions.md` (+6 lines) — redirect notice
+- `.specs/README.md` (+6 lines) — cross-links
+
+**Environment**
+- OS: darwin (macOS ARM64)
+- Tooling: pnpm, nix
+
+**Commands run (exact)**
+- No tests run (spec-only changes, no code modified)
+
+**Work summary**
+1. TASK-057: Consolidated protocol, transport, runtime, and browser multi-tab requirements into `effect-native/.specs/crsql-mesh/requirements.md` using EARS notation
+2. TASK-058: Added browser multi-tab design sketch to `effect-native/.specs/crsql-mesh/design.md` (coordinator/provider/client responsibilities, OPFS invariant, Web Locks election, notifications)
+3. TASK-059: Added browser multi-tab RGRTDD slices (F1-F15) to `effect-native/.specs/crsql-mesh/plan.md`
+4. TASK-060/061/062: Added redirect notices to legacy spec directories pointing to unified spec
+
+**Reproduction steps (clean checkout)**
+1. `git clone <repo> && cd cr-sqlite`
+2. `cd effect-native && git diff --stat` — shows spec file changes
+3. Review `effect-native/.specs/crsql-mesh/requirements.md` for browser multi-tab EARS requirements
+4. Review `effect-native/.specs/crsql-mesh/design.md` for browser multi-tab design section
+5. Review `effect-native/.specs/crsql-mesh/plan.md` for Section F browser multi-tab slices
+
+**Known gaps / unverified claims**
+- No tests run (spec-only changes)
+- TypeScript packages not type-checked this round

.tasks/backlog/TASK-053-spec-browser-runtime-phase1.md

@@ -22,12 +22,15 @@ subagent (general)
 - Gap backlog: `research/zig-cr/92-gap-backlog.md`
 
 ## Description
-Create Phase 1 spec instructions for the browser multi-tab runtime so that Phase 2 requirements can be written and TS implementation can become unblocked.
+Create Phase 1 spec instructions for browser multi-tab (“crsqlite-web-multitab”) as part of the unified full mesh product spec.
 
-This task produces only `instructions.md` (Phase 1) in a new spec directory under `effect-native/.specs/`.
+Per Tom (2025-12-16), defer package boundaries and npm names until they block progress (Thing Golf / minimize new Things). This task updates Phase 1 content in the unified spec and ensures it carries the web multi-tab constraints needed to write Phase 2 requirements later.
 
 ## Files to Modify
-- `effect-native/.specs/<new-browser-runtime-spec>/instructions.md`
+- `effect-native/.specs/crsql-mesh/instructions.md`
+- `effect-native/.specs/crsql-mesh/requirements.md`
+- `effect-native/.specs/crsql-mesh/design.md`
+- `effect-native/.specs/crsql-mesh/plan.md`
 - `effect-native/.specs/README.md` (add cross-link, if applicable)
 - `research/zig-cr/92-gap-backlog.md` (link to spec)
 

.tasks/backlog/TASK-054-spec-browser-runtime-phase2.md

@@ -22,15 +22,18 @@ subagent (general)
 - Gap backlog: `research/zig-cr/92-gap-backlog.md`
 
 ## Description
-Write Phase 2 requirements (EARS) for the browser multi-tab runtime.
+Write Phase 2 requirements (EARS) for browser multi-tab (“crsqlite-web-multitab”) as part of the unified full mesh product spec.
 
 Goal: unblock implementation tasks by creating a testable, unambiguous requirement set for:
 - SharedWorker coordinator primary path
 - Service Worker fallback path
 - minimal “db_version advanced” subscription surface
 
+Per Tom (2025-12-16), package boundaries and npm names are deferred until they block progress (Thing Golf / minimize new Things).
+
 ## Files to Modify
-- `effect-native/.specs/<new-browser-runtime-spec>/requirements.md`
+- `effect-native/.specs/crsql-mesh/requirements.md`
+- `effect-native/.specs/crsql-mesh/design.md` (if required for clarification)
 - `research/zig-cr/92-gap-backlog.md` (link to spec)
 
 ## Acceptance Criteria

…klog/TASK-056-tom-browser-spec-naming.md …done/TASK-056-tom-browser-spec-naming.md.tasks/backlog/TASK-056-tom-browser-spec-naming.md renamed to .tasks/done/TASK-056-tom-browser-spec-naming.md .tasks/backlog/TASK-056-tom-browser-spec-naming.md renamed to .tasks/done/TASK-056-tom-browser-spec-naming.md

@@ -2,10 +2,10 @@
 
 ## Status
 - [x] Planned
-- [ ] Assigned
+- [x] Assigned
 - [ ] In Progress
 - [ ] Blocked (reason: ...)
-- [ ] Complete
+- [x] Complete
 
 ## Priority
 medium
@@ -25,16 +25,19 @@ Before writing browser runtime specs, we need a crisp naming + boundary decision
 
 ## Files to Modify
 - `.tasks/backlog/TASK-053-spec-browser-runtime-phase1.md`
+- `.tasks/backlog/TASK-054-spec-browser-runtime-phase2.md`
 
 ## Acceptance Criteria
-- [ ] Update `.tasks/backlog/TASK-053-spec-browser-runtime-phase1.md` with:
-  - The chosen spec directory name under `effect-native/.specs/` (e.g., `crsqlite-web-multitab` vs `crsql-mesh-runtime-web`)
-  - The intended npm package name(s) (one package vs split coordinator/client/provider)
-  - One-sentence boundary statement for each package (“owns coordination”, “owns provider worker”, etc.)
+- [x] Decision recorded in `.tasks/backlog/TASK-053-spec-browser-runtime-phase1.md`:
+  - Browser multi-tab concept name: `crsqlite-web-multitab`
+  - Spec source of truth: unify under `effect-native/.specs/crsql-mesh/` as the single full product spec
+  - Package boundaries and npm names: deferred until they block progress (Thing Golf rule)
+- [x] `.tasks/backlog/TASK-054-spec-browser-runtime-phase2.md` aligned to write Phase 2 requirements into the unified mesh spec
 
 ## Progress Log
 ### 2025-12-15
 - Task created to prevent mis-scoped browser spec work.
 
 ## Completion Notes
-[fill in when done]
+- 2025-12-16: Tom picked `crsqlite-web-multitab` for the browser multi-tab concept name.
+- 2025-12-16: Tom requested a single unified “full mesh product” spec, deferring package boundaries and names until they block progress (Thing Golf / minimize new Things).

.tasks/done/TASK-057-unify-mesh-requirements.md

@@ -0,0 +1,60 @@
+# TASK-057: Unify mesh requirements into one place
+
+## Status
+- [x] Planned
+- [x] Assigned
+- [x] In Progress
+- [ ] Blocked (reason: ...)
+- [x] Complete
+
+## Priority
+high
+
+## Assigned To
+subagent (general)
+
+## Parent Docs / Cross-links
+- Thing Golf: `research/thing-golf.md`
+- Unified product spec entrypoint: `effect-native/.specs/crsql-mesh/instructions.md`
+- Existing split specs (to reference, not to extend):
+  - `effect-native/.specs/crsql-mesh-protocol/requirements.md`
+  - `effect-native/.specs/crsql-mesh-transport/requirements.md`
+  - `effect-native/.specs/crsql-mesh-runtime/requirements.md`
+- Web multi-tab proposal: `research/zig-cr/96-proposal-multitab-wasm-sqlite-crsqlite.md`
+- Gap backlog: `research/zig-cr/92-gap-backlog.md`
+
+## Description
+We want a single, full-product requirements document for the mesh.
+
+Per Tom (2025-12-16): smooth all mesh specs together first; defer package boundaries and npm names until they block progress (Thing Golf: minimize new Things).
+
+## Files to Modify
+- `effect-native/.specs/crsql-mesh/requirements.md`
+
+## Acceptance Criteria
+- [x] `effect-native/.specs/crsql-mesh/requirements.md` reads as a unified product requirements doc.
+- [x] Requirements include (at minimum):
+  - Mesh engine anti-entropy requirements (already exists)
+  - Protocol requirements (message envelope + diff vocabulary)
+  - Transport requirements (opaque bytes + peer routing expectations)
+  - Runtime adapter requirements (platform wiring expectations)
+  - Browser multi-tab ("crsqlite-web-multitab") requirements written in EARS notation:
+    - SharedWorker preferred, Service Worker fallback
+    - No COOP/COEP requirement
+    - Provider tab dedicated worker owns OPFS
+    - Provider death and re-election semantics at MVP level
+    - Minimal db_version advanced notifications
+- [x] Requirements avoid premature package/module boundaries.
+
+## Progress Log
+### 2025-12-16
+- Task created to enable parallel spec work with disjoint files.
+
+## Completion Notes
+- 2025-12-16: Completed in Round 35 delegate session
+- Added Protocol requirements (FR-PROTO-001 through FR-PROTO-007)
+- Added Transport requirements (FR-TRANS-001 through FR-TRANS-007)
+- Added Runtime Adapter requirements (FR-RUNTIME-001 through FR-RUNTIME-006)
+- Added Browser Multi-Tab requirements (FR-MULTITAB-001 through FR-MULTITAB-012) with EARS notation
+- Unified non-functional requirements and constraints
+- Removed all package boundary references

.tasks/done/TASK-058-unify-mesh-design.md

@@ -0,0 +1,58 @@
+# TASK-058: Unify mesh design into one place
+
+## Status
+- [x] Planned
+- [x] Assigned
+- [x] In Progress
+- [ ] Blocked (reason: ...)
+- [x] Complete
+
+## Priority
+high
+
+## Assigned To
+subagent (general)
+
+## Parent Docs / Cross-links
+- Thing Golf: `research/thing-golf.md`
+- Unified product spec entrypoint: `effect-native/.specs/crsql-mesh/instructions.md`
+- Requirements (target): `effect-native/.specs/crsql-mesh/requirements.md`
+- Existing split designs (to consult):
+  - `effect-native/.specs/crsql-mesh-protocol/design.md`
+  - `effect-native/.specs/crsql-mesh-transport/design.md`
+  - `effect-native/.specs/crsql-mesh-runtime/design.md`
+- Web multi-tab proposal: `research/zig-cr/96-proposal-multitab-wasm-sqlite-crsqlite.md`
+
+## Description
+Create a single, full-product design for mesh that describes how protocol, transport, engine, and runtime adapters compose.
+
+This is not a package design exercise. Per Tom (2025-12-16), we defer package boundaries until they block progress.
+
+## Files to Modify
+- `effect-native/.specs/crsql-mesh/design.md`
+
+## Acceptance Criteria
+- [x] `effect-native/.specs/crsql-mesh/design.md` includes:
+  - A product-level module/concern map (protocol / transport / engine / runtime adapters)
+  - Clear responsibilities and dependency directions between those concerns
+  - A browser multi-tab ("crsqlite-web-multitab") design sketch:
+    - coordinator vs provider vs clients responsibilities
+    - the "only provider touches OPFS" invariant
+    - liveness and provider election strategy at MVP level
+    - notification pathway for db_version advanced
+- [x] The design stays prose-only (no copy/pasteable TS) per `effect-native/.specs/AGENTS.md`.
+
+## Progress Log
+### 2025-12-16
+- Task created to enable parallel spec work with disjoint files.
+
+## Completion Notes
+- 2025-12-16: Completed in Round 35 delegate session
+- Added Product-Level Module Map at top of design
+- Added "Browser Multi-Tab Design (crsqlite-web-multitab)" section with:
+  - Architectural Roles table (coordinator/provider/clients)
+  - "Only Provider Touches OPFS" invariant
+  - Provider Election Strategy using Web Locks
+  - Liveness and Death Detection
+  - Notification Pathway for db_version advances
+  - Migration Safety section

.tasks/done/TASK-059-unify-mesh-plan.md

@@ -0,0 +1,54 @@
+# TASK-059: Unify mesh RGRTDD plan into one place
+
+## Status
+- [x] Planned
+- [x] Assigned
+- [x] In Progress
+- [ ] Blocked (reason: ...)
+- [x] Complete
+
+## Priority
+medium
+
+## Assigned To
+subagent (general)
+
+## Parent Docs / Cross-links
+- Thing Golf: `research/thing-golf.md`
+- Spec workflow: `effect-native/.specs/AGENTS.md`
+- Unified product plan target: `effect-native/.specs/crsql-mesh/plan.md`
+- Existing split plans (to consult):
+  - `effect-native/.specs/crsql-mesh-protocol/plan.md`
+  - `effect-native/.specs/crsql-mesh-transport/plan.md`
+  - `effect-native/.specs/crsql-mesh-runtime/plan.md`
+- Browser multi-tab proposal: `research/zig-cr/96-proposal-multitab-wasm-sqlite-crsqlite.md`
+
+## Description
+The repo currently has multiple “mesh” plans spread across spec directories. We want one top-level RGRTDD plan that sequences the full product and makes it easy to delegate.
+
+Per Tom (2025-12-16), do not finalize package boundaries until blocked.
+
+## Files to Modify
+- `effect-native/.specs/crsql-mesh/plan.md`
+
+## Acceptance Criteria
+- [x] `effect-native/.specs/crsql-mesh/plan.md` becomes the single product-level plan.
+- [x] Plan includes explicit delegation-friendly slices with verification commands.
+- [x] Plan includes browser multi-tab ("crsqlite-web-multitab") slices:
+  - spec phases (Phase 1/2/3/4 artifacts)
+  - then implementation slices (Phase 5) explicitly blocked until approval
+
+## Progress Log
+### 2025-12-16
+- Task created to enable parallel spec work with disjoint files.
+- Added Section F "Browser Multi-Tab (crsqlite-web-multitab)" to plan.md
+
+## Completion Notes
+- Modified: `effect-native/.specs/crsql-mesh/plan.md`
+- Added Section F with:
+  - Architecture summary referencing `research/zig-cr/96-proposal-multitab-wasm-sqlite-crsqlite.md`
+  - Spec phases F1-F4 (instructions, requirements, design, plan refinement)
+  - Implementation slices F5-F15 (RED/GREEN/REFACTOR for coordinator, provider, notifications, Service Worker fallback, provider migration)
+  - All slices include verification commands
+  - Implementation slices explicitly blocked until spec approval
+- File grew from 106 to 199 lines

.tasks/done/TASK-060-redirect-protocol-spec.md

@@ -0,0 +1,39 @@
+# TASK-060: Redirect mesh protocol spec to unified product spec
+
+## Status
+- [x] Planned
+- [x] Assigned
+- [x] In Progress
+- [ ] Blocked (reason: ...)
+- [x] Complete
+
+## Priority
+low
+
+## Assigned To
+subagent (general)
+
+## Parent Docs / Cross-links
+- Unified product spec entrypoint: `effect-native/.specs/crsql-mesh/instructions.md`
+- Protocol spec directory: `effect-native/.specs/crsql-mesh-protocol/`
+- Thing Golf: `research/thing-golf.md`
+
+## Description
+Make it obvious that protocol is now specified primarily in the unified mesh product spec, with this directory treated as legacy/reference until we decide final boundaries.
+
+## Files to Modify
+- `effect-native/.specs/crsql-mesh-protocol/instructions.md`
+
+## Acceptance Criteria
+- [x] `effect-native/.specs/crsql-mesh-protocol/instructions.md` starts with a short note:
+  - points to `effect-native/.specs/crsql-mesh/`
+  - states "package boundaries deferred until blocked"
+  - clarifies this directory is reference material for now
+
+## Progress Log
+### 2025-12-16
+- Task created to reduce confusion while specs are unified.
+
+## Completion Notes
+- 2025-12-16: Completed in Round 35 delegate session
+- Added redirect notice to `effect-native/.specs/crsql-mesh-protocol/instructions.md`

.tasks/done/TASK-061-redirect-transport-spec.md

@@ -0,0 +1,39 @@
+# TASK-061: Redirect mesh transport spec to unified product spec
+
+## Status
+- [x] Planned
+- [x] Assigned
+- [x] In Progress
+- [ ] Blocked (reason: ...)
+- [x] Complete
+
+## Priority
+low
+
+## Assigned To
+subagent (general)
+
+## Parent Docs / Cross-links
+- Unified product spec entrypoint: `effect-native/.specs/crsql-mesh/instructions.md`
+- Transport spec directory: `effect-native/.specs/crsql-mesh-transport/`
+- Thing Golf: `research/thing-golf.md`
+
+## Description
+Make it obvious that transport is now specified primarily in the unified mesh product spec, with this directory treated as legacy/reference until we decide final boundaries.
+
+## Files to Modify
+- `effect-native/.specs/crsql-mesh-transport/instructions.md`
+
+## Acceptance Criteria
+- [x] `effect-native/.specs/crsql-mesh-transport/instructions.md` starts with a short note:
+  - points to `effect-native/.specs/crsql-mesh/`
+  - states "package boundaries deferred until blocked"
+  - clarifies this directory is reference material for now
+
+## Progress Log
+### 2025-12-16
+- Task created to reduce confusion while specs are unified.
+
+## Completion Notes
+- 2025-12-16: Completed in Round 35 delegate session
+- Added redirect notice to `effect-native/.specs/crsql-mesh-transport/instructions.md`