reylo-effect 0.0.0-stage → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+## 0.5.0 — 2026-10-26
+
+### Breaking
+
+- `reylo-effect` depends on `effect` alone. The compiler host — the Node loader, the Vite and esbuild plugins, the TypeScript content mapper, `.reylo.yaml` resolution, PGlite, and YAML — is the new package `reylo-effect-tooling` (same version). Keep importing `reylo-effect/register`, `reylo-effect/vite`, `reylo-effect/esbuild`, and the `reylo-effect` content mapper: they forward to it and, when it is missing, fail naming `npm install -D reylo-effect-tooling@0.5.0`. Install it wherever `.sql` is compiled, including production `register` deployments.
+- The `@reylosql/sqlite`, `@reylosql/postgres`, and `@reylosql/mysql` engines are optional peers of `reylo-effect-tooling`, no longer installed for you: install your dialect's engine at exactly 0.5.0 (`npm install -D @reylosql/sqlite@0.5.0`). A missing or mismatched engine names the package and version.
+- `@effect/sql-pg`, `@effect/sql-mysql2`, `@effect/sql-sqlite-node`, `pg`, and `mysql2` are no longer dependencies. Install the Effect SQL adapter and driver your application executes against, for example `npm install @effect/sql-sqlite-node@4.0.6` or `npm install @effect/sql-pg@4.0.6 pg`.
+
+### Added
+
+- Cache-only analysis: `REYLO_OFFLINE=1` in the environment or `offline: true` in `.reylo.yaml` (the environment wins; `REYLO_OFFLINE=0` turns it off). The session never opens an analysis connection and answers from `.reylo/` alone; a statement missing there fails its import with a diagnostic naming the file. Use it for production `node --import reylo-effect/register` deployments that ship `.reylo/` analyzed in CI.
+- `query.pages(input, { pageSize })`: explicit limit/offset paging, on every driver.
+- `query.cursor(input)`: one execution streamed through the driver's native statement stream (`@effect/sql-pg`, `@effect/sql-mysql2`), never retried or cached.
+- `ReadRetry`: the read retry policy as a service. Provide `{ times, schedule }`, or `false` to run reads once and compose `Effect.retry` yourself.
+- `query.withCache(store | false)`: a result cache attached to one query, independent of the ambient `QueryCache`; `false` never caches.
+- The runtime dependency boundary is enforced: the `runtime` and `d1` builds fail on any import beyond `effect` (and `@effect/sql-d1` for `d1`), and tests check the build's metafile, both package manifests, and that every `src/` file is classified (`scripts/boundary.ts`).
+
+### Deprecated
+
+- `query.stream(input, { chunkSize })`: use `pages` (its `pageSize` is `chunkSize`) or `cursor`.
+
+### Changed
+
+- Tooling errors (`ReyloError`, `LexError`, `SchemaLoadError`, `SqlReadError`, `AnalysisClosed`, `UnsettledAnalysis`, and internal ones) are `Schema.TaggedError` classes; their `_tag`s are unchanged.
+- The content-mapper RPC envelope, D1 proxy messages, and `.reylo/` entry envelopes are decoded with Schema rather than cast; a malformed frame or entry is ignored.
+- Native JSON parameter descriptions use `effect/Cache` (bounded, deduplicating concurrent calls, never keeping connection failures) instead of a hand-rolled map.
+- Compiler operations and `migrate` run in named spans (`Effect.fn("…")`, `Effect.withSpan`).
+- Closing the Vite analysis owner no longer reports the interrupted file-event flush as a `REYLO_WATCH_ERROR` warning.
+- Contract lowering builds a structured Schema IR (`src/schema-ir.ts`) that is printed once at emission; repeated-predicate and native JSON checks compare schemas structurally rather than as text. Generated modules and contract hashes are unchanged.
+
+### Fixed
+
+- A `.sql` module that fails to compile under `reylo-effect/register` reports its file and diagnostics instead of an empty object.
+- Flaky Vite watch tests on macOS: fixtures use canonical temp paths and wait for the watcher to settle, so late file-system events for setup writes no longer reload modules mid-test.
+
+### Documentation
+
+- `SPEC.md` absorbs the Effect-native architecture: deployment modes, the runtime and tooling packages, cache-only production loading, and the runtime composition APIs. The emission target is `effect-sql/5`.
+
+## 0.4.1 — 2026-10-24 to 2026-10-26
+
+### Changed
+
+- Hosts the published Reylo engine protocol directly (`src/reylo-engine.ts`, `src/reylo-session.ts`, `src/sqlite-drivers.ts`, `src/rpc.ts`) and no longer depends on the `reylo` npm package. `@reylosql/sqlite`, `@reylosql/postgres`, and `@reylosql/mysql` move from 0.3.0 to 0.5.0, and an engine of another version is refused.
+
+### Added
+
+- Repeated PostgreSQL and SQLite predicates: `/* @repeat name:group AND|OR */` with `/* @case ... */` definitions generate a tagged-record input, each case checked against the schema.
+- Native PostgreSQL JSON-source arguments: `/* @pg-native-json ... */` and `/* @pg-in ... */` keep JSON values in native parameter slots, checked by schema-file analysis.
+
+### Fixed
+
+- Integration and review fixes across the content mapper, Vite plugin and owner, emission, and analysis sessions.
+
+## 0.4.0 — 2026-10-24
+
+### Changed
+
+- Idiomatic Effect refactor: the analyzer, schema-file sessions, and the Vite owner are Effect programs on one process-wide `ManagedRuntime` (`dist/host.js`) holding the Node platform services and the `EngineLock` semaphore.
+- `migrate(directory)` reads files through Effect's `FileSystem` and `Path` services; provide `NodeServices.layer`.
+- Analysis and Vite performance optimizations.
+
+### Added
+
+- `QueryCacheLayer({ capacity, timeToLive })`, a layer providing `QueryCache`.
+
+## 0.3.0 — 2026-10-24
+
+### Added
+
+- `batch` from `reylo-effect/d1`: atomic D1 requests from `query.batch(input)` calls, decoded as a typed tuple by each query's cardinality.
+- `query.stream(input, { chunkSize })` pages `many` reads; `QueryCacheStore` memoizes reads outside transactions.
+
+### Fixed
+
+- Review fixes; Node.js 24 or newer is required.
+
+## 0.2.1 — 2026-10-24
+
+### Fixed
+
+- `:payload::json` and `:events::rows(...)` bind one JSON text value on every dialect (`jsonb_to_recordset` on Postgres, `JSON_TABLE` on MySQL).
+- PostgreSQL `bytea` fields inside structured parameters use `PostgresBytea`.
+
+## 0.2.0 — 2026-10-23
+
+### Added
+
+- `reylo-effect/vite`: compiles `.sql` imports in Vite 8 for Node servers, SSR, and (with `serverEnvironments`) Cloudflare Worker environments; `nodeEnvironments` is its deprecated name.
+- Cloudflare Workers support: `reylo-effect/runtime` uses no Node built-ins; `integers: number` types D1 and Durable Object SQLite projects.
+
+## 0.1.0 — 2026-10-22
+
+- Initial import: `.sql` files as Effect queries checked against SQLite, Postgres, or MySQL with Reylo 0.3.0, a TypeScript content mapper, an esbuild plugin, the `node --import reylo-effect/register` loader, and `migrate`.

package/README.md

@@ -1,3 +1,484 @@
-# Temporary Holding Version
+# reylo-effect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Import `.sql` files as [Effect](https://effect.website) queries checked against SQLite, Postgres, or MySQL.
+
+SQL is analyzed during typechecking, bundling, or Node module loading and emitted as plain JavaScript. Queries use the caller's Effect SQL client and join its transactions; production bundles do not load the analyzer, and `reylo-effect/runtime` depends on `effect` alone.
+
+[Quick start](#quick-start-sqlite) · [Project setup](#project) · [Queries](#queries) · [Vite](#vite) · [Workers](#cloudflare-workers)
+
+## Requirements
+
+- Node.js 24+ for analysis, builds, and the Node loader.
+- Effect and your SQL client on **4.0.6**. Keep one copy of `effect` so service tags match.
+- Your Effect SQL adapter and database driver, installed by your application: `@effect/sql-sqlite-node`, `@effect/sql-pg` (with `pg`), `@effect/sql-mysql2` (with `mysql2`), or `@effect/sql-d1`. Since 0.5.0 `reylo-effect` no longer installs them.
+- Vite **8.x** if using the Vite plugin.
+- Where `.sql` is compiled (development, CI, builds, and `register` deployments): `reylo-effect-tooling` **0.5.0** and your dialect's engine, `@reylosql/sqlite`, `@reylosql/postgres`, or `@reylosql/mysql` at exactly **0.5.0**.
+
+`reylo-effect` itself depends only on `effect`. The compiler host — the Node loader, the Vite and esbuild plugins, the content mapper, PGlite, and YAML — is the separate `reylo-effect-tooling` package; `reylo-effect/register`, `reylo-effect/vite`, `reylo-effect/esbuild`, and the `reylo-effect` content mapper forward to it, and name it when it is missing. Generated queries never load it. Generated queries also run on [Cloudflare Workers](#cloudflare-workers). See [SPEC.md](SPEC.md) for the full contract.
+
+## Quick start (SQLite)
+
+Install the package and the matching Effect client in a Node.js 24+ project:
+
+```sh
+npm install reylo-effect effect@4.0.6 @effect/platform-node@4.0.6 @effect/sql-sqlite-node@4.0.6
+npm install -D reylo-effect-tooling@0.5.0 @reylosql/sqlite@0.5.0
+```
+
+A deployment that only runs bundled output needs the first line alone; `node --import reylo-effect/register` in production also needs the tooling and engine at runtime, so install them as dependencies there.
+
+Create `migrations/1_create_accounts.sql`:
+
+```sql
+create table accounts (
+  id integer primary key,
+  name text not null
+);
+```
+
+Create `.reylo.yaml`. Analysis uses the schema file, so `dev.db` does not need to exist yet:
+
+```yaml
+schema:
+  - migrations/1_create_accounts.sql
+direct_url: file:./dev.db
+```
+
+Create `find_account.sql`. Named parameters become properties of the query's input:
+
+```sql
+select id, name from accounts where id = :id
+```
+
+Create `app.ts`:
+
+```ts
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import { SqliteClient } from "@effect/sql-sqlite-node"
+import { Effect, Layer } from "effect"
+import { migrate } from "reylo-effect"
+import findAccount from "./find_account.sql"
+
+const DatabaseLive = SqliteClient.layer({ filename: "./dev.db" })
+
+const program = Effect.gen(function* () {
+  yield* migrate("./migrations")
+  const account = yield* findAccount({ id: 1n })
+  console.log(account) // Option.none() until an account with this id exists
+})
+
+await Effect.runPromise(
+  program.pipe(Effect.provide(Layer.mergeAll(DatabaseLive, NodeServices.layer))),
+)
+```
+
+Run it from the project directory:
+
+```sh
+node --import reylo-effect/register app.ts
+```
+
+Schema-file analysis does not apply migrations to the application database; the explicit `migrate` call does. SQLite integers default to `bigint`, hence `1n`. For TypeScript checking and production bundles, see [Project](#project) and [Vite](#vite). For D1's number-based contract, see [Cloudflare Workers](#cloudflare-workers).
+
+## Project
+
+### Analysis database
+
+Set `direct_url` in `.reylo.yaml` to the database used for analysis:
+
+| Dialect | Example `direct_url` |
+| --- | --- |
+| SQLite | `file:./dev.db` |
+| Postgres | `postgres://localhost/app` |
+| MySQL | `mysql://user:pass@localhost:3306/app` |
+
+For SQLite or Postgres, add `schema` files or globs to analyze without a live database. The URL still selects the dialect but is not opened. MySQL requires a live MySQL 8.4+ server and does not support `schema` files.
+
+```yaml
+schema:
+  - schema.sql
+direct_url: postgres://localhost/app
+```
+
+Analysis results are cached in `.reylo/` and refreshed when SQL or schema changes. Analysis never migrates the application database.
+
+### Migrations
+
+`migrate(directory)` from `reylo-effect` applies pending `N_name.sql` files in numeric order and records them in `reylo_migrations`. Provide the SQL client and `NodeServices.layer`, as in the quick start.
+
+The migrator manages transactions: omit `BEGIN`, `COMMIT`, and `ROLLBACK` from migration files. Savepoints are allowed. See [migration semantics](SPEC.md#7-transactions-and-migrations) for details.
+
+### TypeScript
+
+Register the content mapper in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "module": "nodenext",
+    "moduleResolution": "nodenext"
+  },
+  "contentMappers": [
+    { "package": "reylo-effect", "extensions": [".sql"] }
+  ]
+}
+```
+
+```sh
+tsc --runExternalCode
+```
+
+Use a TypeScript compiler with content-mapper support (this repository uses `@effect/tsgo` via `effect-tsgo patch --typescript`). Settings belong in `.reylo.yaml`; `contentMappers[].options` is not supported. Bundlers do not run this typecheck for you.
+
+### Node loader
+
+For unbundled applications, analyze `.sql` imports as they load:
+
+```sh
+node --import reylo-effect/register app.ts
+```
+
+The loader is a supported production deployment mode: no build or materialization step, and the emitted modules use the same runtime contract as bundled output. The process then also contains the compiler: the dialect's engine must be installed, an import can include analysis time (engine load, cache lookup), Postgres schema files need PGlite, and live analysis needs network access to the analysis database.
+
+In production, run the loader **cache-only** so it never contacts a database for analysis:
+
+1. In CI, analyze against a dedicated analysis database (typecheck, build, or tests), which populates `.reylo/`.
+2. Ship `.reylo/` with the deployment.
+3. Start the process with `REYLO_OFFLINE=1` (or set `offline: true` in `.reylo.yaml`):
+
+```sh
+REYLO_OFFLINE=1 node --import reylo-effect/register app.ts
+```
+
+Cache-only analysis opens no connection, not even to read the schema fingerprint, and answers from `.reylo/` alone; a statement missing there fails its import with a diagnostic naming the file. `REYLO_OFFLINE` overrides the file, so `REYLO_OFFLINE=0` turns it off in CI. Without cache-only mode, the loader analyzes against `direct_url`, else `DATABASE_URL` — usually the production database — on every cold import. If you want live analysis in production, point `direct_url` at a dedicated analysis database.
+
+### esbuild
+
+Replace `.sql` imports at build time (also supported by Bun builds using this plugin shape):
+
+```ts
+import reyloEffect from "reylo-effect/esbuild"
+import * as esbuild from "esbuild"
+
+await esbuild.build({
+  entryPoints: ["src/app.ts"],
+  bundle: true,
+  platform: "node",
+  outfile: "dist/app.js",
+  plugins: [reyloEffect()],
+})
+```
+
+## Vite
+
+Use `reylo-effect/vite` with Vite 8 for server-side SQL imports:
+
+```ts
+import reyloEffect from "reylo-effect/vite"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+  plugins: [reyloEffect()],
+  build: { ssr: "src/server.ts" },
+})
+```
+
+The default environment is `ssr`. Use `serverEnvironments` to replace it with selected Node or Worker environments:
+
+```ts
+plugins: [reyloEffect({ serverEnvironments: ["ssr", "api"] })]
+```
+
+Names must be unique, nonempty, and configured as server environments. Bare `.sql` imports fail in browser code and unselected environments. `.sql?raw` and `.sql?url` remain assets; other user query modes are unsupported. `nodeEnvironments` is a deprecated alias; do not set both options.
+
+- **Development:** use `ssrLoadModule` or the environment's `runner.import`, including in middleware mode. Query, schema-file, and config changes trigger recompilation, including new schema-glob matches.
+- **Live databases:** SQLite schema changes are watched. Restart Vite after Postgres or MySQL DDL; those servers are not polled.
+- **Production:** `vite build --ssr` emits JavaScript requiring only the runtime packages (`effect`, `reylo-effect`, and your client), not the loader, SQL sources, config, schema files, or analysis cache. Build watch also recompiles on changes.
+
+If a dependency contains bare `.sql` imports, opt it into bundling:
+
+```ts
+export default defineConfig({
+  plugins: [reyloEffect()],
+  ssr: { noExternal: ["sql-pkg"] },
+})
+```
+
+For custom environments, use their `resolve.noExternal`. Run `tsc --runExternalCode` separately to check query types.
+
+## Cloudflare Workers
+
+Analysis runs in Node at build time; generated queries use the Node-free `reylo-effect/runtime`. Use that entry for runtime helpers in Workers and provide a compatible client:
+
+| Database | Client | Notes |
+| --- | --- | --- |
+| D1 | `@effect/sql-d1` 4.0.6, `D1Client.layer({ db: env.DB })` | Set `integers: number`. No `nodejs_compat`. D1 has no interactive transactions, so `withTransaction` dies. |
+| Durable Object SQLite | `@effect/sql-sqlite-do` 4.0.6 | Set `integers: number`. |
+| Postgres via Hyperdrive | `@effect/sql-pg`, `PgClient.layer({ url: Redacted.make(env.HYPERDRIVE.connectionString) })` | Needs `nodejs_compat`. |
+| MySQL via Hyperdrive | `@effect/sql-mysql2` | Needs `nodejs_compat`. Not covered by tests. |
+
+D1 and Durable Object SQLite return INTEGER as a number and reject bigint parameters. Type those projects with the number contract:
+
+```yaml
+schema:
+  - schema.sql
+direct_url: file:./dev.db
+integers: number
+```
+
+Pass `{ id: 1 }`, not `{ id: 1n }`. Integers outside JavaScript's safe range fail decoding; BLOBs decode to `Uint8Array`. This setting is SQLite-only. To analyze Wrangler's local D1 database instead, point `direct_url` at its SQLite file under `.wrangler/state`.
+
+### D1 batches
+
+Install `@effect/sql-d1@4.0.6` and use `batch` for an atomic request. `.batch(input)` queues a typed call without executing it:
+
+```ts
+import { D1Client } from "@effect/sql-d1"
+import { Effect } from "effect"
+import { batch } from "reylo-effect/d1"
+import insertAccount from "./insert_account.sql"
+import findAccount from "./find_account.sql"
+
+const program = batch([
+  insertAccount.batch({ id: 1, name: "Ada" }),
+  findAccount.batch({ id: 1 }),
+])
+
+// A typed tuple: [void, Option<Account>] for these query cardinalities.
+const [inserted, account] = await Effect.runPromise(
+  program.pipe(Effect.provide(D1Client.layer({ db: env.DB }))),
+)
+```
+
+- Requires SQLite queries with `integers: number`; other contracts fail with `D1BatchError`.
+- Inputs must be known and encoded before submission. Statements run in order; SQL failures roll back the batch.
+- Results use each query's cardinality and codecs. **Decoding happens after commit**: schema or cardinality failures cannot roll back writes.
+- No retries or query caching. Invalidate cached reads after writes. Drift checks run before the batch, outside its transaction.
+- D1 does not support interactive `withTransaction`; use SQL for dependencies between batch statements.
+
+### Building for Workers
+
+With Vite, select the Worker's environment (its name with dashes replaced by underscores):
+
+```ts
+import { cloudflare } from "@cloudflare/vite-plugin"
+import reyloEffect from "reylo-effect/vite"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+  plugins: [cloudflare(), reyloEffect({ serverEnvironments: ["my_worker"] })],
+})
+```
+
+`vite dev` recompiles edited queries in workerd. Use `?raw` when you want SQL text rather than a query.
+
+Wrangler's bundler does not accept plugins. Bundle with `reylo-effect/esbuild` first, then deploy the output with `no_bundle = true`. You can automate this through Wrangler's `[build] command`:
+
+```ts
+await esbuild.build({
+  entryPoints: ["src/worker.ts"],
+  bundle: true,
+  format: "esm",
+  platform: "neutral",
+  conditions: ["workerd", "worker", "browser"],
+  mainFields: ["module", "main"],
+  outfile: "dist/worker.js",
+  plugins: [reyloEffect()],
+})
+```
+
+## Queries
+
+```ts
+import { SqliteClient } from "@effect/sql-sqlite-node"
+import { Config, Effect } from "effect"
+import findUser from "./find_user.sql"
+
+const DatabaseLive = SqliteClient.layerConfig({
+  filename: Config.String("DATABASE_PATH"),
+})
+
+const program = findUser({ id: 1n }).pipe(Effect.provide(DatabaseLive))
+```
+
+For Postgres or MySQL, provide `PgClient.layerConfig({ url: Config.Redacted("DATABASE_URL") })` or `MysqlClient.layerConfig({ url: Config.Redacted("DATABASE_URL") })` instead.
+
+Use named SQL parameters such as `:id` for input properties. Each module exports a default query function plus `Input` and `Row` schemas. Queries without parameters take `{}`. The analyzer infers the result cardinality:
+
+| Cardinality | Result | Check |
+| --- | --- | --- |
+| `many` | `ReadonlyArray<Row>` | Decode every row |
+| `maybeOne` | `Option<Row>` | At most one row |
+| `one` | `Row` | Exactly one row |
+| `none` | `void` | Discard the result, whatever the affected-row count |
+
+Nullable columns remain nullable inside `Option`. Unexpected row counts fail with `CardinalityError`; invalid values fail with `SchemaError`. Driver `SqlError`s pass through unchanged.
+
+### Values and parameters
+
+- **SQLite:** `INTEGER` defaults to `bigint` (`1n`); use `integers: number` for safe-integer numbers. `REAL` is a number.
+- **Postgres:** `int2`/`int4` are numbers, `int8` is bigint, `date` is `YYYY-MM-DD` text, and `time` is microseconds as bigint.
+- **MySQL:** `bigint` results are numbers when safe, otherwise decimal strings; inputs bind as decimal strings. Date/timestamp values are `Date`.
+- Cast ambiguous parameters, e.g. `:id::integer` or `:flag::boolean`. JSON and row-set parameters use `:payload::json` and `:events::rows(...)`.
+- MySQL `::row`/`::rows` inserts with optional fields are unsupported; use an explicit INSERT column list.
+
+See the [value contract](SPEC.md#5-value-contract) for complete mappings, JSON behavior, and date/boolean edge cases.
+
+### Streaming and codecs
+
+Two ways to stream a `many` read:
+
+- `query.pages(input, { pageSize })` runs one statement per page with a generated limit/offset (default page size: 64). It works on every driver, including SQLite and D1. Use an explicit `ORDER BY` for predictable paging; each page is its own statement, so concurrent writes can shift rows between pages.
+- `query.cursor(input)` runs the statement once and streams the driver's rows (`Statement.stream`): one snapshot, the SQL as written. It needs a driver with native cursors (`@effect/sql-pg`, `@effect/sql-mysql2`); `@effect/sql-sqlite-node` and `@effect/sql-d1` do not implement it. It is never retried or cached.
+
+Returning mutations, including mutations in a CTE, execute once and stream their rows. Other cardinalities execute once and retain their row-count checks. Streams bypass the query cache. `query.stream(input, { chunkSize })` is the deprecated name of `pages`.
+
+`query.withCodecs({ input, row })` keeps the SQL and cardinality and replaces either schema or both. Calls, streams, and batches retain input encoding and row decoding service requirements.
+
+### Schema drift
+
+Drift checking is off by default. Enable `CheckSchemaDrift` to re-read the recorded catalog snapshot before execution, including on cache hits:
+
+```ts
+import { CheckSchemaDrift } from "reylo-effect/runtime"
+
+const checked = findUser({ id: 1n }).pipe(
+  Effect.provideService(CheckSchemaDrift, true),
+)
+```
+
+A mismatch fails with `SchemaDriftError`. This checks the catalog, not whether cached row data is still current.
+
+### Query cache
+
+Compose `QueryCacheLayer` beside the client layer to memoize successful non-streaming reads outside transactions:
+
+```ts
+import { Layer } from "effect"
+import { QueryCacheLayer } from "reylo-effect/runtime"
+
+const ServicesLive = Layer.mergeAll(
+  DatabaseLive,
+  QueryCacheLayer({ capacity: 1024, timeToLive: "30 seconds" }),
+)
+
+const cached = findUser({ id: 1n }).pipe(Effect.provide(ServicesLive))
+```
+
+Reuse the provided layer in a shared application scope to share its cache across calls. Alternatively, create a store with `QueryCacheStore.make({ capacity, timeToLive })` and provide it as `QueryCache`, or attach it to one query explicitly:
+
+```ts
+const store = yield* QueryCacheStore.make({ timeToLive: "1 minute" })
+const cachedFindUser = findUser.withCache(store) // this store, whatever QueryCache provides
+const uncachedFindUser = findUser.withCache(false) // never cached
+```
+
+- Defaults: 1024 entries, with no time-based expiry.
+- Concurrent identical calls share one database execution; entries are isolated by client and query contract/codecs.
+- Writes, streams, and all queries inside transactions bypass the cache. Writes **do not invalidate** cached reads; run `store.invalidateAll` after mutations they depend on.
+- SQL failures are not retained. Decoding and cardinality checks run for every caller, even on cache hits.
+
+### Retries and transactions
+
+A retryable `SqlError` from a read outside a transaction is retried three more times, 5 milliseconds apart. Writes and statements inside a transaction run once. Schema and cardinality failures are not retried.
+
+The policy is the `ReadRetry` service. Provide your own, or `false` to run every read once and compose `Effect.retry` yourself:
+
+```ts
+import { ReadRetry } from "reylo-effect/runtime"
+
+findUser({ id: 1n }).pipe(Effect.provideService(ReadRetry, { times: 5, schedule: Schedule.exponential("10 millis") }))
+findUser({ id: 1n }).pipe(Effect.retry({ times: 2 }), Effect.provideService(ReadRetry, false))
+```
+
+`retry_reads: false` in `.reylo.yaml` turns the built-in retry off for a project's generated queries.
+
+Generated queries disable name transforms and set integer handling for their contract without changing your other queries.
+
+Obtain `sql` from `SqlClient` inside an Effect program and wrap related queries in its transaction:
+
+```ts
+import * as SqlClient from "effect/sql/SqlClient"
+
+// Inside Effect.gen:
+const sql = yield* SqlClient.SqlClient
+
+yield* sql.withTransaction(Effect.gen(function* () {
+  yield* insertAccount({ id: 1n, name: "Ada" })
+  return yield* findUser({ id: 1n })
+}))
+```
+
+Decoding and cardinality failures roll back writes only inside a transaction. Connection lifetime and timeouts remain the SQL client's responsibility.
+
+## Development
+
+From this repository:
+
+```sh
+npm install
+npm run build
+npm test
+npm run typecheck
+npm run lint
+npm run fmt
+npm run fmt:check
+```
+
+Installation patches TypeScript to use `@effect/tsgo` and links the `tooling/` workspace (`reylo-effect-tooling`). One source tree builds both packages: `dist/` for `reylo-effect` and `tooling/dist/` for `reylo-effect-tooling`; publish both at the same version. Tests and typechecking build first. `scripts/boundary.ts` classifies every source file; the build fails if the runtime reaches anything but `effect`. Linting runs Oxlint and Effect diagnostics; formatting uses Oxfmt.
+
+SQLite and Postgres schema-file tests run locally. For live integration tests, set `REYLO_TEST_PG` and/or `REYLO_TEST_MYSQL` to test database URLs containing an `accounts` table with an `id` column. MySQL requires 8.4+. Worker tests use Miniflare; Hyperdrive tests also require a password in `REYLO_TEST_PG`.
+
+### Repeated PostgreSQL and SQLite predicates
+
+A SQL module can declare repeated, tagged boolean expressions without accepting SQL text from callers:
+
+```sql
+select id from items where /* @repeat filters:predicates AND */;
+/* @case predicates.label */ label = :value /* @endcase */
+/* @case predicates.minimum */ score >= :value /* @endcase */
+```
+
+The generated input contains a `filters` array of tagged records, such as
+`{ _tag: "label", value: "Ada" }` or `{ _tag: "minimum", value: 2 }`.
+Parameters inside a case belong to that record; root parameters belong to the
+query input. Cases can contain another `@repeat name:group OR` or `AND` directive.
+Empty AND lists are true; empty OR lists are false. Groups must be finite and
+acyclic, and definitions must follow the single query as shown above.
+
+Every case is checked against the schema in its query context, including boolean
+composition and empty lists. Scalar parameter types must agree across uses.
+SQL requiring native structural parameter lowering is refused in repeated modules.
+Every analyzed parameter must originate from an authored `:name` binding;
+untracked positional parameter syntax is rejected.
+SQLite programs bind positional `?` parameters, including native D1 batches; PostgreSQL
+programs bind numbered parameters. MySQL repeated programs are not supported.
+The runtime only expands authored, checked cases and binds encoded values; it never
+accepts caller-supplied SQL. Replacement codecs must still encode the original
+input contract. Query caches distinguish expanded SQL shapes, and streams use the
+actual expanded binding count. Other dialects currently refuse these directives.
+
+### Native PostgreSQL JSON-source arguments
+
+Explicit declarations preserve an existing JSON-to-native-driver boundary without
+changing ordinary `Text` inputs:
+
+```sql
+/* @pg-native-json title description */
+INSERT INTO products(id,title,description) VALUES(:id,:title,:description)
+```
+
+Declared fields generate `NativePgJsonArgument`: missing/undefined, null, boolean,
+number, string, or recursively nested JSON arrays/records. Values retain their
+native parameter slots, including nonfinite JSON numeric overflow; they are not
+stringified. This does not guarantee every value executes successfully: original
+driver inference errors and checked server-rejected argument families still fail.
+
+For independent native `IN` slots, declare `/* @pg-native-json handles[] */` and
+use `/* @pg-in handle :handles */` in the predicate. Empty lists become `1=0`.
+Schema-file PostgreSQL analysis checks the finite native OID families and result
+contracts. Only direct TEXT setters in a single-row INSERT/UPDATE, or a plain
+column SELECT with an isolated IN predicate, are supported. Expressions,
+aggregates, additional rows, boolean repeats and unsupported contexts fail
+compilation. The runtime never accepts SQL clauses or identifiers from callers.