Skip to content

Commit 567137d

Browse files
subtleGradientsubtleGradient
committed
++
1 parent e13e474 commit 567137d

16 files changed

+524
-13
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ target/
1616
.tmp
1717
.tmp
1818
zig-out/
19+
zig-out-*/
1920
zig/*.a
2021
zig/*.o
2122

‎.tasks/backlog/TASK-029-performance-hotspot-closure.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# TASK-029: Performance Hotspot Closure (schema/data version + persistent prepares)
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+
- Gap backlog: `research/zig-cr/92-gap-backlog.md` ("Remaining Gaps → Performance Optimizations")
18+
- Hotspot analysis: `research/zig-cr/11-performance-hotspots.md`
19+
- Likely code hotspots: `zig/src/stmt_cache.zig`, `zig/src/changes_vtab.zig`, `zig/src/ffi/api.zig`
20+
21+
## Description
22+
Close the remaining post-MVP performance gaps that are explicitly tracked but not yet implemented:
23+
24+
1) `PRAGMA schema_version` keyed invalidation caching (avoid unnecessary union rebuild / stmt recreation)
25+
2) `PRAGMA data_version` check amortization (avoid polling/pragma spam on hot loops)
26+
3) Prefer `sqlite3_prepare_v3(..., SQLITE_PREPARE_PERSISTENT)` for long-lived statements
27+
28+
This task is intentionally narrow: improve hot-path behavior without changing query semantics.
29+
30+
## Files to Modify
31+
- `zig/src/stmt_cache.zig`
32+
- `zig/src/changes_vtab.zig`
33+
- `zig/src/ffi/api.zig` (if prepare_v3 / flags wiring needed)
34+
- `research/zig-cr/92-gap-backlog.md` (check off items + add brief notes)
35+
36+
## Acceptance Criteria
37+
- [ ] `stmt_cache` exposes an explicit "schema version changed" signal that callers can use to invalidate cached derived artifacts.
38+
- [ ] `changes_vtab` avoids rebuilding or repreparing union statements when schema_version unchanged.
39+
- [ ] `PRAGMA data_version` checks are amortized (e.g. once per transaction / once per cursor scan loop) with no correctness regressions.
40+
- [ ] If supported by the SQLite target, long-lived statements are prepared using `sqlite3_prepare_v3` with `SQLITE_PREPARE_PERSISTENT`.
41+
- [ ] `make test-unit` and `make test-parity` pass.
42+
43+
## Progress Log
44+
### 2025-12-14
45+
- Task created during gap review; not yet started
46+
47+
## Completion Notes
48+
[fill in when done]

‎.tasks/backlog/TASK-030-windows-dll-build.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# TASK-030: Windows `.dll` Build + Loadability Recon
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+
- Gap backlog: `research/zig-cr/92-gap-backlog.md` ("Cross-platform Packaging & CI")
18+
- Build config: `zig/build.zig`
19+
- FFI/exports: `zig/src/ffi/init.zig`, `zig/src/ffi/root.zig`
20+
21+
## Description
22+
Make the Windows packaging story crisp and testable.
23+
24+
Goal is not "full Windows CI" in one go; it is to either:
25+
- produce a `.dll` artifact that exports `sqlite3_crsqlite_init` correctly, OR
26+
- decisively document why it is blocked (missing toolchain, missing zig target support in CI, missing import lib, etc.)
27+
28+
## Files to Modify
29+
- `zig/build.zig`
30+
- `zig/README.md` (if usage/testing instructions need update)
31+
- `research/zig-cr/92-gap-backlog.md` (status notes)
32+
- (optional) `.github/workflows/*` (only if extremely small matrix tweak is safe)
33+
34+
## Acceptance Criteria
35+
- [ ] `zig build -Dtarget=x86_64-windows-gnu` (or `-msvc` if chosen) produces `crsqlite.dll` (or documents why not).
36+
- [ ] Exported symbol `sqlite3_crsqlite_init` present (document the command used to verify, e.g. `llvm-objdump` / `dumpbin`).
37+
- [ ] `research/zig-cr/92-gap-backlog.md` updated with current Windows status and next concrete step.
38+
39+
## Progress Log
40+
### 2025-12-14
41+
- Task created during gap review; not yet started
42+
43+
## Completion Notes
44+
[fill in when done]

‎.tasks/backlog/TASK-031-web-service-worker-fallback.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# TASK-031: Web Phase-2 — Service Worker Fallback (No COOP/COEP)
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+
- Proposal: `research/zig-cr/96-proposal-multitab-wasm-sqlite-crsqlite.md` (SharedWorker primary, SW fallback)
18+
- Gap backlog: `research/zig-cr/92-gap-backlog.md` (Multi-tab Web Architecture)
19+
- Current impl: `zig/browser-test/src/coordinator/shared-worker.ts`, `zig/browser-test/src/client/db-client.ts`
20+
21+
## Constraint
22+
This work is likely TypeScript-heavy. Per `.wishes/stop-before-typescript.md`, do not implement without Tom explicitly opting-in.
23+
24+
If Tom has not opted-in, convert this task into a blocked task card with a short design note and a "Tom decision needed" checklist.
25+
26+
## Description
27+
Add a Service Worker fallback for environments where SharedWorker is unavailable.
28+
29+
Scope is only the coordinator/port-bridging fallback.
30+
Do not attempt to move OPFS access into the Service Worker.
31+
32+
## Files to Modify
33+
- `zig/browser-test/src/*` and/or `zig/browser-dist/*`
34+
- `research/zig-cr/92-gap-backlog.md` (status notes)
35+
36+
## Acceptance Criteria
37+
- [ ] In an environment without SharedWorker, multi-tab open still succeeds using SW fallback.
38+
- [ ] Existing Playwright tests extended or a new test added to cover the fallback path.
39+
- [ ] No regression in SharedWorker path.
40+
41+
## Progress Log
42+
### 2025-12-14
43+
- Task created during gap review; awaiting Tom opt-in due to TS constraint
44+
45+
## Completion Notes
46+
[fill in when done]

‎.tasks/backlog/TASK-032-web-reactive-subscriptions.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# TASK-032: Web Phase-2 — Reactive Subscriptions Surface
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+
- Proposal: `research/zig-cr/96-proposal-multitab-wasm-sqlite-crsqlite.md` ("Notifications / subscriptions")
18+
- Gap backlog: `research/zig-cr/92-gap-backlog.md` (Multi-tab Web Architecture)
19+
- Current impl: `zig/browser-test/src/client/db-client.ts`
20+
21+
## Constraint
22+
Likely TypeScript-heavy. Per `.wishes/stop-before-typescript.md`, do not implement without Tom explicitly opting-in.
23+
24+
If Tom has not opted-in, convert this task into a blocked task card with a short design note and a "Tom decision needed" checklist.
25+
26+
## Description
27+
Provide a narrow notification/subscription surface so tab B can react when tab A writes.
28+
29+
MVP can be a "db_version advanced" event broadcast; leave "observable queries" as optional.
30+
31+
## Files to Modify
32+
- `zig/browser-test/src/shared/rpc-types.ts`
33+
- `zig/browser-test/src/client/db-client.ts`
34+
- `zig/browser-test/src/coordinator/shared-worker.ts`
35+
- `research/zig-cr/92-gap-backlog.md` (status notes)
36+
37+
## Acceptance Criteria
38+
- [ ] Provider publishes a notification when `crsql_db_version()` advances.
39+
- [ ] Clients can subscribe/unsubscribe and receive events.
40+
- [ ] Playwright test proves cross-tab visibility within one notification round.
41+
42+
## Progress Log
43+
### 2025-12-14
44+
- Task created during gap review; awaiting Tom opt-in due to TS constraint
45+
46+
## Completion Notes
47+
[fill in when done]

‎.tasks/backlog/TASK-033-mobile-static-embedding-guide.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# TASK-033: Mobile Static Embedding Guide (iOS + Android)
2+
3+
## Status
4+
- [ ] Planned
5+
- [ ] Assigned
6+
- [ ] In Progress
7+
- [ ] Blocked (reason: ...)
8+
- [ ] Complete
9+
10+
## Priority
11+
low
12+
13+
## Assigned To
14+
subagent (general)
15+
16+
## Parent Docs / Cross-links
17+
- Gap backlog: `research/zig-cr/92-gap-backlog.md` (Cross-platform Packaging & CI)
18+
- Platform notes: `research/zig-cr/93-phased-execution-proposal.md` (static embedding for web/iOS/Android)
19+
- Zig build: `zig/build.zig` (static lib already built)
20+
21+
## Description
22+
Document and validate a minimal static-embedding path for mobile:
23+
24+
- iOS: link `libcrsql.a` into an app's SQLite build (or host SQLite) and call init symbol
25+
- Android: same idea, but NDK toolchain
26+
27+
Important: this is a guide + validation harness, not a full RN integration.
28+
29+
## Files to Modify
30+
- `zig/README.md` (optional section)
31+
- `research/zig-cr/*` (small focused guide doc; keep it close to code)
32+
- `research/zig-cr/92-gap-backlog.md` (status notes)
33+
34+
## Acceptance Criteria
35+
- [ ] Clear steps for building a static archive for target platforms.
36+
- [ ] Explicit note about why dynamic extension loading often fails on mobile.
37+
- [ ] A minimal "hello" validation strategy described (even if not runnable in CI).
38+
39+
## Progress Log
40+
### 2025-12-14
41+
- Task created during gap review; not yet started
42+
43+
## Completion Notes
44+
[fill in when done]

‎.tasks/backlog/TASK-034-npm-package-zig-native.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# TASK-034: npm Packaging for Zig-built Native Extensions
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+
- Gap backlog: `research/zig-cr/92-gap-backlog.md` ("Cross-platform Packaging & CI" / "Remaining Work for Production Release")
18+
- Existing JS package entry: `index.js`, `package.json`, `scripts/*`
19+
- Existing prebuilt artifacts: `lib/`
20+
- Zig build artifacts: `zig/zig-out*/lib/libcrsqlite.*`
21+
22+
## Description
23+
Package Zig-built native artifacts in the main npm package so users can install and load Zig `crsqlite` without building from source.
24+
25+
This repository already ships C/Rust prebuilt artifacts in `lib/`. Extend or parallel that mechanism for Zig builds.
26+
27+
Constraints:
28+
- Do not introduce a new TS project; stay within existing build tooling.
29+
- Prefer reproducible builds (Nix).
30+
31+
## Files to Modify
32+
- `package.json`
33+
- `scripts/*` (likely `scripts/build-production.ts` / `scripts/build-production.cjs`)
34+
- `index.js` (if selection logic changes)
35+
- `lib/*` (only if intentionally adding artifacts)
36+
- `research/zig-cr/92-gap-backlog.md` (status notes)
37+
38+
## Acceptance Criteria
39+
- [ ] Build pipeline produces Zig artifacts for at least one platform and places them in a deterministic location.
40+
- [ ] Runtime loader can select Zig artifacts deterministically (or explicitly documents why it can’t yet).
41+
- [ ] `dist.test.ts` (or equivalent existing packaging sanity tests) extended to assert Zig artifacts presence/selection.
42+
- [ ] No regression in existing C/Rust artifact selection.
43+
44+
## Progress Log
45+
### 2025-12-14
46+
- Task created during gap review; not yet started
47+
48+
## Completion Notes
49+
[fill in when done]

‎.tasks/backlog/TASK-035-hosted-wasm-proposal.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# TASK-035: Hosted Browser ESM Proposal (Multi-tab)
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/hosted-wasm.md`
18+
- Current browser dist: `zig/browser-dist/`
19+
- Multi-tab architecture proposal: `research/zig-cr/96-proposal-multitab-wasm-sqlite-crsqlite.md`
20+
21+
## Description
22+
Write a concrete proposal for the "hosted wasm" experience:
23+
24+
"I can just `import('https://.../crsqlite-multitab.mjs')` and it all Just Works."
25+
26+
Do not implement hosted distribution yet. Produce a tight checklist for:
27+
- what files need to be hosted
28+
- how versioning/cache busting works
29+
- what the public API looks like
30+
- what the minimal example looks like
31+
- what constraints (COOP/COEP, browser support) are required
32+
33+
Keep this proposal close to the code that will ship (prefer updating `zig/browser-dist/README.md` or a small `research/zig-cr/*` doc rather than new standalone docs elsewhere).
34+
35+
## Files to Modify
36+
- `zig/browser-dist/README.md` and/or `research/zig-cr/*`
37+
- `.wishes/hosted-wasm.md` (mark done + link to proposal)
38+
39+
## Acceptance Criteria
40+
- [ ] Proposal describes a minimal importable ESM surface.
41+
- [ ] Proposal describes where artifacts live and how they’re hosted.
42+
- [ ] Proposal calls out which parts are blocked on TS/publishing decisions.
43+
44+
## Progress Log
45+
### 2025-12-14
46+
- Task created during gap review; not yet started
47+
48+
## Completion Notes
49+
[fill in when done]

‎.tasks/backlog/TASK-036-release-planning-proposal.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# TASK-036: Release Planning Proposal (Where + How)
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/release-planning.md`
18+
- Current packages: `package.json`, `zig/browser-dist/package.json`
19+
- CI: `.github/workflows/*`
20+
21+
## Description
22+
Write a proposal for how/where to release the Zig work (native + browser):
23+
24+
- Which registries/channels: Nix, npm, GitHub releases, etc.
25+
- What versioning strategy: aligned with root package version or independent
26+
- What artifact matrix: darwin arm64/x64, linux x64/arm64, windows, wasm
27+
- What docs are needed and where they live (prefer in-repo, near code)
28+
29+
Do not publish anything. Output should be a checklist and a proposed staged rollout.
30+
31+
## Files to Modify
32+
- `research/zig-cr/*` (small proposal doc) or `README.md` (if appropriate)
33+
- `.wishes/release-planning.md` (mark done + link to proposal)
34+
35+
## Acceptance Criteria
36+
- [ ] Proposal enumerates channels + pros/cons.
37+
- [ ] Proposal has a staged plan (MVP web beta → linux → mac/windows, etc.).
38+
- [ ] Proposal lists concrete next engineering tasks and where they live in `.tasks/`.
39+
40+
## Progress Log
41+
### 2025-12-14
42+
- Task created during gap review; not yet started
43+
44+
## Completion Notes
45+
[fill in when done]

0 commit comments

Comments
 (0)