Electric Circuits: rename, dynamic-first docs, benchmark reset

[balegas]

Summary

Turns the electric-ivm repository into the public Electric Circuits project: a full mechanical rename, deletion + rewrite of the docs (dynamic-first messaging), a restored-and-rewritten tutorial series, a repo-wide benchmark-number reset (to be re-measured before launch), and a set of pipeline-explorer improvements that make subquery move-in/out (the query-back path) legible. Engine logic is unchanged — every .rs/.ts change is the mechanical rename, a comment edit, or viz code.

User-visible impact: one product identity (electric-circuits), one public vocabulary (three nouns — Streams, Circuits, Live queries — no "shapes" in public docs), a coherent docs + tutorial set telling the dynamic-first story, and a visualizer that faithfully animates how a membership change fetches and joins rows.

Reviewer guidance

Approach — landed in phases (see the commit history):

1. Mechanical rename electric-ivm → electric-circuits — three literal substitutions across packages, the Rust crate/binary, env vars, Docker image paths, and imports. Upstream electric-sql/electricsql and the electric-conformance/ directory name are guarded; the conformance harness's references to our own symbols were renamed as required (two oracle .exs files git mv'd so run.sh resolves).
2. Deletions + doc rewrites — removed tutorials/ (old), pipeline-authoring docs; new README.md front door, getting-started.md, shapes-and-subqueries-guide.md → live-queries-guide.md, and a new docs/how-queries-become-live.md. Serving-tier detail preserved into docs/ivm-engine-internals.md.
3. Benchmark-number reset — deleted the docs/bench/ output tree and stripped measured figures from prose, code comments, and the bench report template. Fresh numbers to be taken before launch.
4. Tutorial series restored + rewritten — the old episodes taught engine features that no longer exist (config-driven cohort arrangements, checkpoint/reseed, fallback→promotion). New 4-episode series on a self-contained docker stack + a small dedicated seed: first live query → inside the circuit → cross-table subqueries → aggregations. The tutorial stack was boot-verified (all 5 services build + run; episode commands checked live).
5. Pipeline explorer — renamed to "Circuit visualizer" and made the query-back path legible: a subquery move-in/out is derived (rooted at the membership table, not the outer table's own stream), so the outer source→change edge correctly doesn't pulse. Instead: an amber query-back bounce on the source↔Δ edge (move-in only — a move-out deletes from the feed set, no fetch), the fetched rows then flow Δ→JOIN carrying the weight, join nodes gate their two inputs before emitting, and the Δ node carries a ⟲ via query-back / ↤ via membership tag. All viz-only; verified live via browser automation.

Key invariants (verified):

• git grep -E 'electric-ivm|electric_ivm|ELECTRIC_IVM_' → 0.
• Public docs + tutorials use only the three nouns; "shape" survives only as code references with a bridge sentence.
• No benchmark figures remain in any doc.
• LinearLite demo + the tutorial docker stack both boot; cargo build -p electric-circuits-engine green; engine tests green after the rename (186 passing) with only comment-level .rs edits after.

⚠️ Please confirm in review — .beads/ untracked. Going public, the internal beads issue-tracker directory was added to .gitignore and git rm --cached (local files preserved; issue sync is via Dolt refs/dolt/data, not these files). If the team wants it tracked, drop the chore: untrack .beads… commit.

Non-goals: the blog post (separate track); any engine logic change (incl. unifying counts to be fully dynamic); CDN caching / persistence as doc topics.

Manual handoff: rename the GitHub remote balegas/electric-ivm → electric-circuits and publish images under ghcr.io/balegas/electric-circuits/*. All in-repo references already point at the new names.

Verification

git grep -nE 'electric-ivm|electric_ivm|ELECTRIC_IVM_' -- ':!.beads'   # → nothing
cargo build -p electric-circuits-engine && pnpm engine:test
scripts/linearlite.sh stop; scripts/linearlite.sh start medium         # curl https://localhost:8443/ → 200
(cd tutorials && docker compose up --build)                            # the tutorial stack

Files changed

• Rename: every package.json, apps/engine/Cargo.toml + .rs, scripts, docker/*, CI, doc tokens.
• Docs: README.md, docs/getting-started.md, docs/live-queries-guide.md (renamed), docs/how-queries-become-live.md (new); deleted docs/bench/, old tutorials/, pipeline-authoring docs; .beads/ untracked.
• Tutorials: tutorials/ restored + rewritten (README, 4 episodes, compose, seeds).
• Visualizer (apps/pipeline-viz/src/*): Circuit rename, query-back derived visuals (bounce, fetched-rows flow, join gating, move-in/out tags).

🤖 Generated with Claude Code

https://claude.ai/code/session_01RtY9SSsR7vndAxDqtbhSM4