docs: truth batch — rewrite architecture.md from source, real sql-translation.md, README fixes; 0.2.0 scaffolding - #33
Merged
Conversation
…x README; 0.2.0 release scaffolding Documentation-truth batch. docs/architecture.md was a pre-implementation design doc presented as current architecture; every claim is now backed by a file in the repo: - removed baton-based Hrana sessions (no baton.rs exists; http.rs returns baton: None -- stateless), optional JWT validation (no auth code exists in litewire-hrana), batch/sequence request types (only execute/close are implemented), and the backend-libsql feature (does not exist) - removed the sqld-clustered ePHPm integration section (ePHPm removed sqld in its v0.7.0; litewire is standalone -- ePHPm is described as one consumer, correctly) - removed the phantom repo tree (tests/ files and module names that do not exist), the litewire:latest docker/CI example, the implementation-phases plan, and the speculative etcd/RESP/Mongo sections - fixed the default-feature table: defaults are mysql, hrana, backend-rusqlite; postgres/tds/hrana-client/turso/cli are opt-in - new docs/sql-translation.md: the real translation reference written from litewire-translate/litewire-session source -- rewrites, metadata emulation, FOUND_ROWS handling, error-code mapping, and what is rejected README: the as-a-library snippet claimed a crates.io version that is not published -- replaced with the git-dependency form (compile-verified in a scratch project); the CLI quick start now says the binary needs --features cli; Hrana subset limitations stated; libsql-SDK and embedded-replica overclaims removed. The multi-tenant section is untouched. Release scaffolding: CHANGELOG.md reconstructed from the merged PR history, CONTRIBUTING.md codifying the build/test/lint gates and the wire-level regression-test convention, an msrv CI job, and a workspace version bump to 0.2.0. rust-version corrected 1.85 -> 1.88: the declared 1.85 was never true with the locked graph (turso -> aristo requires rustc 1.88); the new CI job is what keeps the declaration honest.
Clippy toolchain drift: collapsible_if and manual_is_multiple_of now fire on pre-existing nested `if let` / `if` blocks across the workspace, so `clippy --all-targets -- -D warnings` fails on main as well as this branch. Fixed mechanically with `cargo clippy --fix` (both feature sets) plus rustfmt; every change is a semantics-preserving collapse -- the let-chains short-circuit in the same order, so side-effecting guards (`select.top.take()`, `name.0.pop()`, `pool.take()`) still run exactly when they did. Files: litewire-translate (common.rs, lib.rs, metadata.rs, mysql.rs, tds.rs), litewire-backend/rusqlite_backend.rs, litewire-mysql/handler.rs, litewire-tds/handler.rs (`% 2 != 0` -> `!is_multiple_of(2)`), litewire-turso/cdc.rs, and litewire/src/main.rs (the CLI binary, only reachable under --all-features).
luthermonson
force-pushed
the
docs/truth-batch-and-0.2.0-scaffolding
branch
from
August 16, 2026 17:11
f71a78c to
09e0a1a
Compare
luthermonson
added a commit
that referenced
this pull request
Sep 1, 2026
…nslation.md, README fixes; 0.2.0 scaffolding (#33) * docs: rewrite architecture.md from source, add sql-translation.md, fix README; 0.2.0 release scaffolding Documentation-truth batch. docs/architecture.md was a pre-implementation design doc presented as current architecture; every claim is now backed by a file in the repo: - removed baton-based Hrana sessions (no baton.rs exists; http.rs returns baton: None -- stateless), optional JWT validation (no auth code exists in litewire-hrana), batch/sequence request types (only execute/close are implemented), and the backend-libsql feature (does not exist) - removed the sqld-clustered ePHPm integration section (ePHPm removed sqld in its v0.7.0; litewire is standalone -- ePHPm is described as one consumer, correctly) - removed the phantom repo tree (tests/ files and module names that do not exist), the litewire:latest docker/CI example, the implementation-phases plan, and the speculative etcd/RESP/Mongo sections - fixed the default-feature table: defaults are mysql, hrana, backend-rusqlite; postgres/tds/hrana-client/turso/cli are opt-in - new docs/sql-translation.md: the real translation reference written from litewire-translate/litewire-session source -- rewrites, metadata emulation, FOUND_ROWS handling, error-code mapping, and what is rejected README: the as-a-library snippet claimed a crates.io version that is not published -- replaced with the git-dependency form (compile-verified in a scratch project); the CLI quick start now says the binary needs --features cli; Hrana subset limitations stated; libsql-SDK and embedded-replica overclaims removed. The multi-tenant section is untouched. Release scaffolding: CHANGELOG.md reconstructed from the merged PR history, CONTRIBUTING.md codifying the build/test/lint gates and the wire-level regression-test convention, an msrv CI job, and a workspace version bump to 0.2.0. rust-version corrected 1.85 -> 1.88: the declared 1.85 was never true with the locked graph (turso -> aristo requires rustc 1.88); the new CI job is what keeps the declaration honest. * style: collapse nested if-lets into let-chains (clippy collapsible_if) Clippy toolchain drift: collapsible_if and manual_is_multiple_of now fire on pre-existing nested `if let` / `if` blocks across the workspace, so `clippy --all-targets -- -D warnings` fails on main as well as this branch. Fixed mechanically with `cargo clippy --fix` (both feature sets) plus rustfmt; every change is a semantics-preserving collapse -- the let-chains short-circuit in the same order, so side-effecting guards (`select.top.take()`, `name.0.pop()`, `pool.take()`) still run exactly when they did. Files: litewire-translate (common.rs, lib.rs, metadata.rs, mysql.rs, tds.rs), litewire-backend/rusqlite_backend.rs, litewire-mysql/handler.rs, litewire-tds/handler.rs (`% 2 != 0` -> `!is_multiple_of(2)`), litewire-turso/cdc.rs, and litewire/src/main.rs (the CLI binary, only reachable under --all-features).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation-truth batch at rev cb707ab, plus 0.2.0 release scaffolding. Every claim in the rewritten docs is backed by a file in this repo.
Phantom claims removed (with evidence)
baton.rsdoes not exist;litewire-hrana/src/http.rsreturnsbaton: None // Stateless for now. The doc and README now say what the frontend is: a stateless subset (/v2/pipelinewithexecute/close, plus/healthand/version).litewire-hrana. Removed; the Hrana frontend is documented as unauthenticated.batch/sequencerequest types — onlyexecuteandcloseare implemented (http.rs::pipeline_handler). Removed.backend-libsqlfeature — does not exist in any Cargo.toml. The real optional backend isbackend-hrana-client(litewire-backend/src/hrana_client.rs).mysql, hrana, backend-rusqlite(crates/litewire/Cargo.toml); postgres/tds/hrana-client/turso/cli are opt-in, and the binary requires--features cli(required-featureson the[[bin]]).tests/mysql_compat.rs,pg_compat.rs,tds_compat.rs,wordpress.rs,laravel.rs,litewire-backend/src/rusqlite.rs,libsql.rs,hrana/src/baton.rs: none exist. Tree now matchesfind.docs/sql-translation.mdreferenced but missing — now written for real from thelitewire-translate/litewire-sessionsource: the pipeline, transaction rewrites, no-ops, all metadata emulation, the shared/MySQL/PG/T-SQL rewrite tables (incl. the PR fix(translate): MySQL LIKE patterns get their implicit ESCAPE '\' on SQLite #25 LIKE-escape, feat(mysql): translate REGEXP and YEAR/MONTH/DAYOFMONTH #29 REGEXP/date-part, fix(session): emulate SQL_CALC_FOUND_ROWS / FOUND_ROWS(), stop dropping plain LIMIT #26 FOUND_ROWS work), error-code mapping, and an explicit "what does not work" section.image: litewire:latestCI example (no image is published), the implementation-phases plan, and the speculative etcd/RESP/Mongo sections.README fixes
litewire = { version = "0.1", ... }— the crate is not on crates.io. Replaced with the git-dependency form; the exact snippet was compile-verified in a scratch project against this repo (cargo checkclean).--features cliand shows the install/build commands.Release scaffolding
rust-version = "1.85"was never true with the locked graph:turso → aristorequires rustc 1.88 (icu crates need 1.86). Corrected to 1.88 and the job pins it; noted in the changelog.version = "0.1.0"pin inlitewire-turso's dependency onlitewire-backend, which broke resolution otherwise). Proposed procedure: tagv0.2.0on the merge commit of this PR. Publishing to crates.io remains an option (the README snippet would then switch to a version requirement) — owner's call, not done here.Verification
cargo check --workspace --all-features— cleancargo test --workspace(38 suites) andcargo test --workspace --all-features— 930 passed, 0 failedcargo +1.88 check --workspace --all-features --all-targets— clean (the new CI job, run locally)