release blockers

Author: subtleGradient

.tasks/backlog/TASK-209-release-0.16.300-preview.md

@@ -20,38 +20,49 @@ The release is considered ready when:
 
 ## Blockers (must be cleared)
 
+This list is intended to be exhaustive. Each blocker must have an owning task card.
+
 ### Tom sign-off (explicit gate)
 - [ ] **Tom release sign-off recorded**: `.wishes/blocked-on-tom/release-readiness-decision.md`
 
-### Required build artifacts
-- [ ] **WASM build works on current Zig toolchain** (prior CI notes mention Zig 0.14 incompatibility)
-  - Related: `.tasks/backlog/TASK-207-reenable-ci-for-release.md`
-- [ ] **Browser bundle uses local CR-SQLite WASM** (not CDN sql.js)
+### Versioning + tag semantics
+- [ ] **Define the canonical version string and tag shape** (`0.16.300-preview` + `v0.16.300-preview`) and ensure all release automation keys off it.
+  - Task: `.tasks/backlog/TASK-210-release-versioning-and-tags.md`
+
+### Required build artifacts (scope = Native + WASM + Browser)
+- [ ] **Native Zig extension release artifacts exist and are verifiable** (darwin + linux at minimum).
+  - Task: `.tasks/backlog/TASK-211-release-native-zig-artifacts.md`
+- [ ] **WASM build works on current Zig toolchain and is reproducible in CI**.
+  - Task: `.tasks/backlog/TASK-212-fix-wasm-build-for-release.md`
+- [ ] **Browser bundle uses local CR-SQLite WASM (not CDN sql.js)**.
   - Evidence of prior gap: `.tasks/done/TASK-069-wire-scratchpads.md`
+  - Task: `.tasks/backlog/TASK-213-browser-provider-loads-crsqlite-wasm.md`
 
 ### CI / validation
-- [ ] **CI re-enabled and passing** on Linux + macOS, including WASM
+- [ ] **CI re-enabled and passing** on Linux + macOS, including WASM + browser tests.
   - Task: `.tasks/backlog/TASK-207-reenable-ci-for-release.md`
-- [ ] **Oracle-dependent tests have a CI strategy**
+- [ ] **Oracle-dependent tests have a CI strategy**.
   - Either provide Rust/C oracle binaries in CI OR explicitly skip oracle-dependent jobs.
   - Evidence of issue: `.tasks/done/TASK-206-disable-ci-temporarily.md`
+  - Task: `.tasks/backlog/TASK-214-ci-oracle-strategy.md`
 
-### Packaging / distribution wiring
-- [ ] **npm release path defined and implemented in `effect-native/`** (OIDC publish)
-  - Note: TypeScript changes must be spec-gated under `effect-native/.specs/`.
-- [ ] **GitHub Release artifact matrix defined + produced** (at minimum darwin + linux)
-- [ ] **nix packaging hooks validated via tag** (flake / fetch-from-git tag flow)
+### Distribution wiring
+- [ ] **GitHub Release workflow ships Zig artifacts** (not the legacy `core/` Rust/C publish flow).
+  - Task: `.tasks/backlog/TASK-215-github-release-zig-artifacts.md`
+- [ ] **nix packaging uses Zig artifacts and matches `0.16.300-preview`** (tags → nix).
+  - Task: `.tasks/backlog/TASK-216-nix-release-uses-zig.md`
+- [ ] **npm publish path exists in `effect-native/`** (OIDC provenance publish).
+  - Task: `.tasks/backlog/TASK-217-effect-native-oidc-npm-release.md`
 
 ### Backwards-compat surface verification
-- [ ] **Required upstream surface areas confirmed** for `0.16.3`-compat
-  - This is a checklist task: enumerate what “backwards compatible” means for this release (functions, tables, wire behavior).
-  - The goal is to avoid accidentally shipping a preview missing required pieces.
+- [ ] **Backwards-compat checklist for upstream `0.16.3` is explicit and checked off** (functions, tables, browser runtime expectations).
+  - Task: `.tasks/backlog/TASK-218-compat-checklist-0.16.3.md`
 
 ## Files to Modify
 - `.tasks/backlog/TASK-209-release-0.16.300-preview.md` (this file)
 
 ## Acceptance Criteria
-1. [ ] Every blocker above has an owning `.tasks/**/TASK-*.md` card (or explicit rationale why not)
+1. [ ] Every blocker above has an owning `.tasks/**/TASK-*.md` card
 2. [ ] Each blocker has a clear verification command or observable proof
 3. [ ] Blockers list stays current as new gaps are discovered
 

.tasks/backlog/TASK-210-release-versioning-and-tags.md

@@ -0,0 +1,38 @@
+# TASK-210 — Release Versioning + Tags (0.16.300-preview)
+
+## Goal
+Make `0.16.300-preview` a first-class, consistent version across:
+- git tags
+- npm publish (effect-native OIDC)
+- GitHub Releases (native artifacts)
+- nix (tags)
+
+## Status
+- State: backlog
+- Priority: HIGH
+- Created: 2025-12-25
+
+## Required Decisions / Clarifications
+- Canonical git tag name: `v0.16.300-preview` (assumed)
+- Root repo `package.json` currently uses `0.16.3-1`; decide whether it becomes `0.16.300-preview` or remains separate from release version.
+
+## Files to Modify
+- `package.json` (root) (version)
+- `flake.nix` (version strings printed + derivation version)
+- `scripts/sync-version.ts` (version sync semantics)
+- Any release scripts that assume `0.16.3`
+
+## Acceptance Criteria
+1. [ ] A single canonical version string is defined: `0.16.300-preview`
+2. [ ] A single canonical git tag format is defined and used: `v0.16.300-preview`
+3. [ ] Root `package.json`, `flake.nix`, and any version reporters agree (or explicitly document divergence)
+4. [ ] `npm run sync-version` does not clobber preview versions back to `0.16.3-1`
+
+## Parent Docs / Cross-links
+- Release tracker: `.tasks/backlog/TASK-209-release-0.16.300-preview.md`
+
+## Progress Log
+- 2025-12-25: Created from release planning.
+
+## Completion Notes
+(Empty until done.)

.tasks/backlog/TASK-211-release-native-zig-artifacts.md

@@ -0,0 +1,35 @@
+# TASK-211 — Release Native Zig Artifacts (darwin + linux)
+
+## Goal
+Produce and verify the native Zig loadable extension artifacts for `0.16.300-preview`.
+
+## Status
+- State: backlog
+- Priority: HIGH
+- Created: 2025-12-25
+
+## Scope
+Minimum required for release:
+- macOS (arm64 + x86_64) `.dylib` (universal acceptable)
+- Linux x86_64 `.so`
+
+## Files to Modify
+- `zig/` build outputs are generated, but the task should modify only build scripts / CI packaging:
+  - `scripts/build-zig.sh`
+  - `scripts/build-production.ts` (if used for bundling)
+  - `.github/workflows/zig-tests.yaml` (if needed for artifact upload)
+
+## Acceptance Criteria
+1. [ ] `nix run nixpkgs#zig -- build -Doptimize=ReleaseFast` succeeds
+2. [ ] Built artifacts exist with deterministic names under `zig/zig-out/lib/`
+3. [ ] Artifacts can be loaded by sqlite on their target platforms
+4. [ ] Artifact naming + layout matches the GitHub Release upload plan
+
+## Parent Docs / Cross-links
+- Release tracker: `.tasks/backlog/TASK-209-release-0.16.300-preview.md`
+
+## Progress Log
+- 2025-12-25: Created from release planning.
+
+## Completion Notes
+(Empty until done.)

.tasks/backlog/TASK-212-fix-wasm-build-for-release.md

@@ -0,0 +1,33 @@
+# TASK-212 — Fix WASM Build for Release (current Zig toolchain)
+
+## Goal
+Make the CR-SQLite WASM build reproducible and CI-friendly for `0.16.300-preview`.
+
+## Status
+- State: backlog
+- Priority: HIGH
+- Created: 2025-12-25
+
+## Context / Evidence
+- CI was disabled partly because “WASM build requires Zig 0.14 compatibility”:
+  - `.tasks/done/TASK-206-disable-ci-temporarily.md`
+  - `.github/workflows/zig-tests.yaml`
+
+## Files to Modify
+- `zig/wasm-build/build-sqlite-wasm.sh`
+- `zig/build.zig` / `zig/build.zig.zon` (if needed)
+- `.github/workflows/zig-tests.yaml`
+
+## Acceptance Criteria
+1. [ ] `nix run nixpkgs#zig -- build wasm` succeeds in CI-like environment
+2. [ ] `make -C zig test-browser` passes using the built artifacts
+3. [ ] No network fetches are required at build time OR they are explicitly allowed and cached (e.g. sqlite amalgamation, sqlite-vec)
+
+## Parent Docs / Cross-links
+- Release tracker: `.tasks/backlog/TASK-209-release-0.16.300-preview.md`
+
+## Progress Log
+- 2025-12-25: Created from release planning.
+
+## Completion Notes
+(Empty until done.)

.tasks/backlog/TASK-213-browser-provider-loads-crsqlite-wasm.md

@@ -0,0 +1,38 @@
+# TASK-213 — Browser Provider Loads Local CR-SQLite WASM (no CDN sql.js)
+
+## Goal
+Ensure the browser provider uses the local bundled CR-SQLite WASM (`zig/browser-dist/sql-wasm.js` + `sql-wasm.wasm`) instead of loading `sql.js` from cdnjs.
+
+## Status
+- State: backlog
+- Priority: HIGH
+- Created: 2025-12-25
+
+## Evidence
+- Current `provider.js` loads from cdnjs:
+  - `zig/browser-dist/provider.js`
+  - `zig/browser-test/fixtures/provider.js`
+  - `zig/browser-test/src/provider/worker.ts`
+- Scratchpad note flags this as pending:
+  - `.tasks/done/TASK-069-wire-scratchpads.md`
+
+## Files to Modify
+- `zig/browser-test/src/provider/worker.ts`
+- `zig/browser-test/fixtures/provider.js` (rebuilt output)
+- `zig/browser-dist/provider.js` (rebuilt output)
+- Potentially `zig/browser-dist/README.md` (if it documents the old behavior)
+
+## Acceptance Criteria
+1. [ ] No `https://cdnjs.cloudflare.com/ajax/libs/sql.js/...` references remain in provider artifacts
+2. [ ] Provider successfully initializes from `sql-wasm.js` and locates sibling `sql-wasm.wasm`
+3. [ ] `make -C zig test-browser` passes
+4. [ ] `bun --hot scratch/browser-scratchpad/src/index.ts` works with no external CDN dependency
+
+## Parent Docs / Cross-links
+- Release tracker: `.tasks/backlog/TASK-209-release-0.16.300-preview.md`
+
+## Progress Log
+- 2025-12-25: Created from release planning.
+
+## Completion Notes
+(Empty until done.)

.tasks/backlog/TASK-214-ci-oracle-strategy.md

@@ -0,0 +1,37 @@
+# TASK-214 — CI Oracle Strategy (Rust/C availability)
+
+## Goal
+Decide and implement a CI strategy for tests that currently rely on the Rust/C oracle.
+
+## Status
+- State: backlog
+- Priority: HIGH
+- Created: 2025-12-25
+
+## Context / Evidence
+- CI was disabled partly due to oracle-dependent tests:
+  - `.tasks/done/TASK-206-disable-ci-temporarily.md`
+  - `.tasks/backlog/TASK-207-reenable-ci-for-release.md`
+
+## Options
+- Provide oracle binaries in CI (build `core/` or download prebuilt)
+- Split CI: always run Zig-only tests; run oracle parity on a best-effort job
+- Remove oracle dependency for release gate (only for preview) and rely on Zig-only suites
+
+## Files to Modify
+- `.github/workflows/zig-tests.yaml`
+- Potentially add CI scripts under `zig/harness/` for "zig-only" vs "oracle" grouping
+
+## Acceptance Criteria
+1. [ ] CI config clearly separates oracle-dependent and zig-only test jobs
+2. [ ] Release gating jobs do not silently pass by skipping too much
+3. [ ] Document which jobs are required for `0.16.300-preview`
+
+## Parent Docs / Cross-links
+- Release tracker: `.tasks/backlog/TASK-209-release-0.16.300-preview.md`
+
+## Progress Log
+- 2025-12-25: Created from release planning.
+
+## Completion Notes
+(Empty until done.)

.tasks/backlog/TASK-215-github-release-zig-artifacts.md

@@ -0,0 +1,30 @@
+# TASK-215 — GitHub Release Ships Zig Artifacts
+
+## Goal
+Update GitHub release automation to ship Zig-built artifacts for `0.16.300-preview`.
+
+## Status
+- State: backlog
+- Priority: HIGH
+- Created: 2025-12-25
+
+## Context / Evidence
+- Existing `.github/workflows/publish.yaml` currently builds from `core/` (Rust/C) and uses apt/rustup.
+
+## Files to Modify
+- `.github/workflows/publish.yaml`
+- Potentially add Zig build + upload steps (or call existing scripts)
+
+## Acceptance Criteria
+1. [ ] Tag push `v0.16.300-preview` produces a GitHub Release with Zig artifacts attached
+2. [ ] Artifacts are clearly named per platform (darwin x86_64/aarch64 or universal; linux x86_64/aarch64)
+3. [ ] No `core/` build is required for the Zig release pipeline (unless explicitly chosen)
+
+## Parent Docs / Cross-links
+- Release tracker: `.tasks/backlog/TASK-209-release-0.16.300-preview.md`
+
+## Progress Log
+- 2025-12-25: Created from release planning.
+
+## Completion Notes
+(Empty until done.)

.tasks/backlog/TASK-216-nix-release-uses-zig.md

@@ -0,0 +1,30 @@
+# TASK-216 — Nix Release Uses Zig Artifacts + Matches Preview Version
+
+## Goal
+Ensure nix packaging for this repo produces the Zig artifacts and reports version `0.16.300-preview`.
+
+## Status
+- State: backlog
+- Priority: HIGH
+- Created: 2025-12-25
+
+## Context / Evidence
+- `flake.nix` currently builds `core/` Rust/C and has `version = "0.16.3"` and `print-version` returns `0.16.3`.
+
+## Files to Modify
+- `flake.nix`
+- Any nix scripts referenced by release pipeline
+
+## Acceptance Criteria
+1. [ ] `nix build` produces Zig extension artifacts (not Rust/C)
+2. [ ] `nix run .#print-version` returns `0.16.300-preview`
+3. [ ] Tag-based fetch / nix usage works for released tag
+
+## Parent Docs / Cross-links
+- Release tracker: `.tasks/backlog/TASK-209-release-0.16.300-preview.md`
+
+## Progress Log
+- 2025-12-25: Created from release planning.
+
+## Completion Notes
+(Empty until done.)

.tasks/backlog/TASK-217-effect-native-oidc-npm-release.md

@@ -0,0 +1,32 @@
+# TASK-217 — effect-native OIDC npm Release Path
+
+## Goal
+Implement the npm publish path for `0.16.300-preview` via the `effect-native/` repo using OIDC provenance.
+
+## Status
+- State: backlog
+- Priority: HIGH
+- Created: 2025-12-25
+
+## Constraints
+- All TypeScript work happens in `effect-native/`.
+- Spec-gated: must follow `effect-native/.specs/AGENTS.md`.
+
+## Files to Modify
+- `effect-native/.specs/**` (as needed to pass spec gates)
+- `effect-native/packages-native/**` (implementation)
+- `effect-native/.github/workflows/**` (publish workflow, if required)
+
+## Acceptance Criteria
+1. [ ] A publishable package (or set of packages) exists for the artifacts required by this release
+2. [ ] OIDC provenance publish is configured and works in CI
+3. [ ] Package version aligns to `0.16.300-preview` (or explicitly documents mapping)
+
+## Parent Docs / Cross-links
+- Release tracker: `.tasks/backlog/TASK-209-release-0.16.300-preview.md`
+
+## Progress Log
+- 2025-12-25: Created from release planning.
+
+## Completion Notes
+(Empty until done.)

.tasks/backlog/TASK-218-compat-checklist-0.16.3.md

@@ -0,0 +1,34 @@
+# TASK-218 — Backwards-Compat Checklist (Upstream 0.16.3)
+
+## Goal
+Define what “backwards compatible with upstream cr-sqlite v0.16.3” means for `0.16.300-preview`, and verify it.
+
+## Status
+- State: backlog
+- Priority: HIGH
+- Created: 2025-12-25
+
+## Checklist Areas
+- SQL function surface (presence + basic behavior)
+- Table / vtab surface (`crsql_changes`, `crsql_master`, `crsql_site_id`, `crsql_tracked_peers` semantics)
+- Wire format / sync invariants (cross-open, multinode, resurrection, sentinel, etc.)
+- Browser bundle expectations (WASM availability, multitab components present)
+
+## Files to Modify
+- `research/zig-cr/01-extension-surface.md` (if used as the canonical surface list)
+- `zig/harness/test-api-surface.sh` (or add a new checklist test)
+- This task card
+
+## Acceptance Criteria
+1. [ ] Compatibility checklist is explicit and reviewable
+2. [ ] Each checklist item has a verification command or test
+3. [ ] Any intentional incompatibility is documented and explicitly accepted for preview
+
+## Parent Docs / Cross-links
+- Release tracker: `.tasks/backlog/TASK-209-release-0.16.300-preview.md`
+
+## Progress Log
+- 2025-12-25: Created from release planning.
+
+## Completion Notes
+(Empty until done.)