Skip to content

Commit 962a523

Browse files
subtleGradientsubtleGradient
committed
++
1 parent c3bb254 commit 962a523

10 files changed

+348
-4
lines changed

‎.tasks/backlog/TASK-039-spec-global-mesh-package-map.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# TASK-039: Spec Phase 1 — Global Mesh Package Map (Effect Native)
2+
3+
## Status
4+
- [ ] Planned
5+
- [ ] Assigned
6+
- [ ] In Progress
7+
- [ ] Blocked (reason: ...)
8+
- [ ] Complete
9+
10+
## Priority
11+
high
12+
13+
## Assigned To
14+
subagent (general)
15+
16+
## Parent Docs / Cross-links
17+
- Wish: [`.wishes/effect-native.md`](../../.wishes/effect-native.md)
18+
- Proposal: [`research/zig-cr/102-proposal-crsqlite-global-mesh.md`](../../research/zig-cr/102-proposal-crsqlite-global-mesh.md)
19+
- TS workflow rules: [`effect-native/.specs/AGENTS.md`](../../effect-native/.specs/AGENTS.md)
20+
- Existing package (Effect SQL surface): [`effect-native/packages-native/crsql/`](../../effect-native/packages-native/crsql/)
21+
- Existing package (native binaries): [`effect-native/packages-native/libcrsql/`](../../effect-native/packages-native/libcrsql/)
22+
- Upstream Effect SQL packages:
23+
- [`./.refs/effect/packages/sql/`](../../.refs/effect/packages/sql/)
24+
- [`./.refs/effect/packages/sql-sqlite-bun/`](../../.refs/effect/packages/sql-sqlite-bun/)
25+
26+
## Description
27+
Create the Phase-1 `instructions.md` for the global mesh work, focused on *package boundaries*.
28+
29+
This deliverable defines:
30+
- the set of new atomic packages we intend to add (names + responsibilities)
31+
- which existing packages must change (and why)
32+
- which upstream Effect SQL packages we’re integrating with
33+
34+
This task must follow the spec-first workflow.
35+
36+
## Files to Create/Modify
37+
- `effect-native/.specs/crsqlite-global-mesh-packages/instructions.md`
38+
- `effect-native/.specs/README.md` (add a link to the new spec)
39+
40+
## Acceptance Criteria
41+
- [ ] `effect-native/.specs/crsqlite-global-mesh-packages/instructions.md` exists and follows Phase 1 rules.
42+
- [ ] The doc includes an explicit “Out of Scope” section.
43+
- [ ] The doc lists candidate packages as *names only* (no code, no pseudo-code).
44+
- [ ] The doc links back to `research/zig-cr/102-proposal-crsqlite-global-mesh.md`.
45+
- [ ] STOP after this document (do not proceed to Phase 2 without explicit approval).
46+
47+
## Progress Log
48+
### 2025-12-14
49+
- Task created to kick off TS mesh planning
50+
51+
## Completion Notes
52+
[fill in when done]

‎.tasks/backlog/TASK-040-spec-crsql-mesh-protocol.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# TASK-040: Spec Phase 1 — New Package: `@effect-native/crsql-mesh-protocol`
2+
3+
## Status
4+
- [ ] Planned
5+
- [ ] Assigned
6+
- [ ] In Progress
7+
- [ ] Blocked (reason: ...)
8+
- [ ] Complete
9+
10+
## Priority
11+
high
12+
13+
## Assigned To
14+
subagent (general)
15+
16+
## Parent Docs / Cross-links
17+
- Package-map spec (parent): [`effect-native/.specs/crsqlite-global-mesh-packages/instructions.md`](../../effect-native/.specs/crsqlite-global-mesh-packages/instructions.md)
18+
- Global mesh proposal: [`research/zig-cr/102-proposal-crsqlite-global-mesh.md`](../../research/zig-cr/102-proposal-crsqlite-global-mesh.md)
19+
20+
## Description
21+
Create Phase-1 `instructions.md` for a small, purely-data package that defines the mesh protocol surface.
22+
23+
This package is intended to be the shared vocabulary across runtimes:
24+
- message type names
25+
- message envelopes
26+
- version summary concepts (site_id, db_version)
27+
28+
No implementation in this task.
29+
30+
## Files to Create/Modify
31+
- `effect-native/.specs/crsql-mesh-protocol/instructions.md`
32+
33+
## Acceptance Criteria
34+
- [ ] `effect-native/.specs/crsql-mesh-protocol/instructions.md` exists and follows Phase 1 rules.
35+
- [ ] Doc states what the protocol does not cover (auth, encryption, membership, etc.).
36+
- [ ] STOP after this document (do not proceed to Phase 2 without explicit approval).
37+
38+
## Progress Log
39+
### 2025-12-14
40+
- Task created during TS planning
41+
42+
## Completion Notes
43+
[fill in when done]

‎.tasks/backlog/TASK-041-spec-crsql-mesh-core.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# TASK-041: Spec Phase 1 — New Package: `@effect-native/crsql-mesh` (core sync engine)
2+
3+
## Status
4+
- [ ] Planned
5+
- [ ] Assigned
6+
- [ ] In Progress
7+
- [ ] Blocked (reason: ...)
8+
- [ ] Complete
9+
10+
## Priority
11+
high
12+
13+
## Assigned To
14+
subagent (general)
15+
16+
## Parent Docs / Cross-links
17+
- Package-map spec (parent): [`effect-native/.specs/crsqlite-global-mesh-packages/instructions.md`](../../effect-native/.specs/crsqlite-global-mesh-packages/instructions.md)
18+
- Protocol package spec: [`effect-native/.specs/crsql-mesh-protocol/instructions.md`](../../effect-native/.specs/crsql-mesh-protocol/instructions.md)
19+
- Global mesh proposal: [`research/zig-cr/102-proposal-crsqlite-global-mesh.md`](../../research/zig-cr/102-proposal-crsqlite-global-mesh.md)
20+
21+
## Description
22+
Create Phase-1 `instructions.md` for the core mesh sync engine package.
23+
24+
This package is the transport-agnostic engine that:
25+
- pulls changes from a local replica via the CR-SQLite surface
26+
- exchanges summaries / wants / batches
27+
- applies incoming changes transactionally
28+
29+
No implementation in this task.
30+
31+
## Files to Create/Modify
32+
- `effect-native/.specs/crsql-mesh/instructions.md`
33+
34+
## Acceptance Criteria
35+
- [ ] `effect-native/.specs/crsql-mesh/instructions.md` exists and follows Phase 1 rules.
36+
- [ ] Doc explicitly states what “eventual consistency” means for callers.
37+
- [ ] Doc explicitly excludes “global uniqueness” / “linearizable reads”.
38+
- [ ] STOP after this document (do not proceed to Phase 2 without explicit approval).
39+
40+
## Progress Log
41+
### 2025-12-14
42+
- Task created during TS planning
43+
44+
## Completion Notes
45+
[fill in when done]

‎.tasks/backlog/TASK-042-spec-crsql-mesh-transport.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# TASK-042: Spec Phase 1 — New Package: `@effect-native/crsql-mesh-transport`
2+
3+
## Status
4+
- [ ] Planned
5+
- [ ] Assigned
6+
- [ ] In Progress
7+
- [ ] Blocked (reason: ...)
8+
- [ ] Complete
9+
10+
## Priority
11+
high
12+
13+
## Assigned To
14+
subagent (general)
15+
16+
## Parent Docs / Cross-links
17+
- Package-map spec (parent): [`effect-native/.specs/crsqlite-global-mesh-packages/instructions.md`](../../effect-native/.specs/crsqlite-global-mesh-packages/instructions.md)
18+
- Protocol package spec: [`effect-native/.specs/crsql-mesh-protocol/instructions.md`](../../effect-native/.specs/crsql-mesh-protocol/instructions.md)
19+
- Global mesh proposal: [`research/zig-cr/102-proposal-crsqlite-global-mesh.md`](../../research/zig-cr/102-proposal-crsqlite-global-mesh.md)
20+
21+
## Description
22+
Create Phase-1 `instructions.md` for a small package that defines the transport adapter interface(s).
23+
24+
Goal: make transports pluggable without infecting the core sync engine.
25+
26+
No implementation in this task.
27+
28+
## Files to Create/Modify
29+
- `effect-native/.specs/crsql-mesh-transport/instructions.md`
30+
31+
## Acceptance Criteria
32+
- [ ] `effect-native/.specs/crsql-mesh-transport/instructions.md` exists and follows Phase 1 rules.
33+
- [ ] Doc names the kinds of transports we anticipate (same-process, browser BroadcastChannel, WS, WebRTC), without specifying libraries.
34+
- [ ] STOP after this document (do not proceed to Phase 2 without explicit approval).
35+
36+
## Progress Log
37+
### 2025-12-14
38+
- Task created during TS planning
39+
40+
## Completion Notes
41+
[fill in when done]

‎.tasks/backlog/TASK-043-spec-crsql-mesh-integration.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# TASK-043: Spec Phase 1 — Changes to Existing Package: `@effect-native/crsql`
2+
3+
## Status
4+
- [ ] Planned
5+
- [ ] Assigned
6+
- [ ] In Progress
7+
- [ ] Blocked (reason: ...)
8+
- [ ] Complete
9+
10+
## Priority
11+
high
12+
13+
## Assigned To
14+
subagent (general)
15+
16+
## Parent Docs / Cross-links
17+
- Package-map spec (parent): [`effect-native/.specs/crsqlite-global-mesh-packages/instructions.md`](../../effect-native/.specs/crsqlite-global-mesh-packages/instructions.md)
18+
- Existing package: [`effect-native/packages-native/crsql/README.md`](../../effect-native/packages-native/crsql/README.md)
19+
- Upstream Effect SQL:
20+
- [`./.refs/effect/packages/sql/`](../../.refs/effect/packages/sql/)
21+
- [`./.refs/effect/packages/sql-sqlite-bun/`](../../.refs/effect/packages/sql-sqlite-bun/)
22+
23+
## Description
24+
Create Phase-1 `instructions.md` for the *mesh-related changes* we expect in `@effect-native/crsql`.
25+
26+
Examples of the kind of integration this spec should cover (as intent, not implementation):
27+
- a typed way to pull ordered rows from `crsql_changes`
28+
- a typed way to apply rows into `crsql_changes`
29+
- helpers that compose cleanly with `@effect/sql` clients
30+
31+
No implementation in this task.
32+
33+
## Files to Create/Modify
34+
- `effect-native/.specs/crsql-mesh-integration/instructions.md`
35+
36+
## Acceptance Criteria
37+
- [ ] `effect-native/.specs/crsql-mesh-integration/instructions.md` exists and follows Phase 1 rules.
38+
- [ ] Doc explains what part belongs in `@effect-native/crsql` vs `@effect-native/crsql-mesh`.
39+
- [ ] STOP after this document (do not proceed to Phase 2 without explicit approval).
40+
41+
## Progress Log
42+
### 2025-12-14
43+
- Task created during TS planning
44+
45+
## Completion Notes
46+
[fill in when done]

‎.tasks/backlog/TASK-044-spec-libcrsql-next.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# TASK-044: Spec Phase 1 — Changes to Existing Package: `@effect-native/libcrsql`
2+
3+
## Status
4+
- [ ] Planned
5+
- [ ] Assigned
6+
- [ ] In Progress
7+
- [ ] Blocked (reason: ...)
8+
- [ ] Complete
9+
10+
## Priority
11+
medium
12+
13+
## Assigned To
14+
subagent (general)
15+
16+
## Parent Docs / Cross-links
17+
- Wish: [`.wishes/effect-native.md`](../../.wishes/effect-native.md)
18+
- Existing package: [`effect-native/packages-native/libcrsql/README.md`](../../effect-native/packages-native/libcrsql/README.md)
19+
- Zig packaging gap task (repo-level): [`./.tasks/backlog/TASK-034-npm-package-zig-native.md`](./TASK-034-npm-package-zig-native.md)
20+
21+
## Description
22+
Create Phase-1 `instructions.md` for what must change in `@effect-native/libcrsql` to support the next stage of the project.
23+
24+
This is likely about *distribution and selection* (native + wasm artifacts), not sync semantics.
25+
26+
No implementation in this task.
27+
28+
## Files to Create/Modify
29+
- `effect-native/.specs/libcrsql-next/instructions.md`
30+
31+
## Acceptance Criteria
32+
- [ ] `effect-native/.specs/libcrsql-next/instructions.md` exists and follows Phase 1 rules.
33+
- [ ] Doc calls out which changes depend on Zig artifacts vs pure JS packaging.
34+
- [ ] STOP after this document (do not proceed to Phase 2 without explicit approval).
35+
36+
## Progress Log
37+
### 2025-12-14
38+
- Task created during TS planning
39+
40+
## Completion Notes
41+
[fill in when done]

‎.tasks/backlog/TASK-045-spec-crsql-mesh-runtime.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# TASK-045: Spec Phase 1 — New Package: `@effect-native/crsql-mesh-runtime-*` (platform adapters)
2+
3+
## Status
4+
- [ ] Planned
5+
- [ ] Assigned
6+
- [ ] In Progress
7+
- [ ] Blocked (reason: ...)
8+
- [ ] Complete
9+
10+
## Priority
11+
medium
12+
13+
## Assigned To
14+
subagent (general)
15+
16+
## Parent Docs / Cross-links
17+
- Package-map spec (parent): [`effect-native/.specs/crsqlite-global-mesh-packages/instructions.md`](../../effect-native/.specs/crsqlite-global-mesh-packages/instructions.md)
18+
- Global mesh proposal: [`research/zig-cr/102-proposal-crsqlite-global-mesh.md`](../../research/zig-cr/102-proposal-crsqlite-global-mesh.md)
19+
20+
## Description
21+
Create Phase-1 `instructions.md` for the platform-specific runtime packages that provide:
22+
- concrete transports (browser tabs, node processes, etc.)
23+
- persistence details (OPFS vs filesystem)
24+
25+
This task is specifically about scoping and naming the packages (e.g. `...-browser`, `...-node`, `...-react-native`).
26+
27+
No implementation in this task.
28+
29+
## Files to Create/Modify
30+
- `effect-native/.specs/crsql-mesh-runtime/instructions.md`
31+
32+
## Acceptance Criteria
33+
- [ ] `effect-native/.specs/crsql-mesh-runtime/instructions.md` exists and follows Phase 1 rules.
34+
- [ ] Doc has a clear rationale for each runtime package (why separate).
35+
- [ ] STOP after this document (do not proceed to Phase 2 without explicit approval).
36+
37+
## Progress Log
38+
### 2025-12-14
39+
- Task created during TS planning
40+
41+
## Completion Notes
42+
[fill in when done]

‎.wishes/effect-native.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,13 @@ we follow the spec-first workflow defined in effect-native/.specs/AGENTS.md
1212

1313
let's start planning a set of new packages for all this stuff
1414
especially research/zig-cr/102-proposal-crsqlite-global-mesh.md
15+
16+
Tracking:
17+
- Submodules + TS-work rule: [`.tasks/backlog/TASK-038-add-effect-native-submodules.md`](../.tasks/backlog/TASK-038-add-effect-native-submodules.md)
18+
- Global mesh package-map spec (Phase 1): [`.tasks/backlog/TASK-039-spec-global-mesh-package-map.md`](../.tasks/backlog/TASK-039-spec-global-mesh-package-map.md)
19+
- Protocol spec: [`.tasks/backlog/TASK-040-spec-crsql-mesh-protocol.md`](../.tasks/backlog/TASK-040-spec-crsql-mesh-protocol.md)
20+
- Core engine spec: [`.tasks/backlog/TASK-041-spec-crsql-mesh-core.md`](../.tasks/backlog/TASK-041-spec-crsql-mesh-core.md)
21+
- Transport interface spec: [`.tasks/backlog/TASK-042-spec-crsql-mesh-transport.md`](../.tasks/backlog/TASK-042-spec-crsql-mesh-transport.md)
22+
- `@effect-native/crsql` integration spec: [`.tasks/backlog/TASK-043-spec-crsql-mesh-integration.md`](../.tasks/backlog/TASK-043-spec-crsql-mesh-integration.md)
23+
- `@effect-native/libcrsql` changes spec: [`.tasks/backlog/TASK-044-spec-libcrsql-next.md`](../.tasks/backlog/TASK-044-spec-libcrsql-next.md)
24+
- Runtime adapters spec: [`.tasks/backlog/TASK-045-spec-crsql-mesh-runtime.md`](../.tasks/backlog/TASK-045-spec-crsql-mesh-runtime.md)

‎research/zig-cr/102-proposal-crsqlite-global-mesh.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -303,6 +303,21 @@ Pass:
303303

304304
## Deliverable shape (fits the existing “universal” plan)
305305

306+
## Work Tracking
307+
308+
This proposal’s TypeScript follow-through is tracked via spec-first task cards in `.tasks/backlog/`:
309+
310+
- Phase 1 package map: [`.tasks/backlog/TASK-039-spec-global-mesh-package-map.md`](../../.tasks/backlog/TASK-039-spec-global-mesh-package-map.md)
311+
- Protocol package spec: [`.tasks/backlog/TASK-040-spec-crsql-mesh-protocol.md`](../../.tasks/backlog/TASK-040-spec-crsql-mesh-protocol.md)
312+
- Core engine spec: [`.tasks/backlog/TASK-041-spec-crsql-mesh-core.md`](../../.tasks/backlog/TASK-041-spec-crsql-mesh-core.md)
313+
- Transport interface spec: [`.tasks/backlog/TASK-042-spec-crsql-mesh-transport.md`](../../.tasks/backlog/TASK-042-spec-crsql-mesh-transport.md)
314+
- Integration into `@effect-native/crsql`: [`.tasks/backlog/TASK-043-spec-crsql-mesh-integration.md`](../../.tasks/backlog/TASK-043-spec-crsql-mesh-integration.md)
315+
- `@effect-native/libcrsql` changes: [`.tasks/backlog/TASK-044-spec-libcrsql-next.md`](../../.tasks/backlog/TASK-044-spec-libcrsql-next.md)
316+
- Runtime adapter package scoping: [`.tasks/backlog/TASK-045-spec-crsql-mesh-runtime.md`](../../.tasks/backlog/TASK-045-spec-crsql-mesh-runtime.md)
317+
318+
All TS implementation work must happen in `effect-native/` and follow `effect-native/.specs/AGENTS.md`.
319+
320+
306321
This proposal is not a separate product; it’s the “full mesh” target for the universal package from:
307322

308323
- [`101-proposal-universal-crsqlite-mt-js.md`](./101-proposal-universal-crsqlite-mt-js.md)

‎research/zig-cr/92-gap-backlog.md‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,22 @@
1111
- Wishes blocked on Tom: `.wishes/blocked-on-tom/`
1212

1313
**Task map (what to run in parallel next)**:
14-
- Perf hotspots: `.tasks/backlog/TASK-029-performance-hotspot-closure.md`
14+
- Perf hotspots: ✅ COMPLETE (see `.tasks/done/TASK-029-performance-hotspot-closure.md`)
1515
- Windows `.dll`: ✅ COMPLETE (see `.tasks/done/TASK-030-windows-dll-build.md`)
16+
- Hosted web ESM proposal: ✅ COMPLETE (see `.tasks/done/TASK-035-hosted-wasm-proposal.md`)
17+
- Effect submodules + TS-work rule: ✅ COMPLETE (see `.tasks/done/TASK-038-add-effect-native-submodules.md`)
1618
- npm native packaging (Zig artifacts): `.tasks/backlog/TASK-034-npm-package-zig-native.md`
17-
- Web phase-2 (TS-gated): `.tasks/backlog/TASK-031-web-service-worker-fallback.md`, `.tasks/backlog/TASK-032-web-reactive-subscriptions.md`
18-
- Mobile embedding guide: `.tasks/backlog/TASK-033-mobile-static-embedding-guide.md`
19-
- Hosted web ESM proposal: `.tasks/backlog/TASK-035-hosted-wasm-proposal.md`
2019
- Release-planning proposal: `.tasks/backlog/TASK-036-release-planning-proposal.md`
20+
- Web phase-2 (now TS-in-`effect-native/`): `.tasks/backlog/TASK-031-web-service-worker-fallback.md`, `.tasks/backlog/TASK-032-web-reactive-subscriptions.md`
21+
- Global mesh spec-first planning:
22+
- `.tasks/backlog/TASK-039-spec-global-mesh-package-map.md`
23+
- `.tasks/backlog/TASK-040-spec-crsql-mesh-protocol.md`
24+
- `.tasks/backlog/TASK-041-spec-crsql-mesh-core.md`
25+
- `.tasks/backlog/TASK-042-spec-crsql-mesh-transport.md`
26+
- `.tasks/backlog/TASK-043-spec-crsql-mesh-integration.md`
27+
- `.tasks/backlog/TASK-044-spec-libcrsql-next.md`
28+
- `.tasks/backlog/TASK-045-spec-crsql-mesh-runtime.md`
29+
- Mobile embedding guide: `.tasks/backlog/TASK-033-mobile-static-embedding-guide.md`
2130
- zig-sqlite upstream feedback capture (blocked): `.tasks/backlog/TASK-037-zig-sqlite-upstream-feedback-blocked.md`
2231

2332
**MVP COMPLETE** — All core replication functionality implemented and tested:

0 commit comments

Comments
 (0)