@junejs/juno 0.0.13 → 0.0.15

package/README.md

@@ -1,27 +1,68 @@
 # @junejs/juno
 
-June's ergonomic data layer — a typed table API over the pure `JuneDb` contract
-(`@junejs/core/resources`), so it runs over sqlite / D1 / Postgres alike. Juno
-depends only on `@junejs/core` (inward); `@junejs/core` never imports Juno.
+June's ergonomic data layer — a typed table API over the `JuneDb` contract, so it
+runs over sqlite / D1 / Postgres alike. **Optional Tier 3:** a minimal app just uses
+the raw `db` resource (`db.query(sql, params)`); declare Juno to get the magic
+(auto-batch, auto-invalidation, compile-once). Depends on `@junejs/core` +
+`@junejs/db` (inward); the framework never imports Juno.
+
+## Use it
+
+Opt in once, in `june.config.ts`:
+
+```ts
+import { defineJune } from "@junejs/core/config";
+import { sqlite } from "@junejs/server";
+import { junoDataLayer } from "@junejs/juno";
+
+export default defineJune({ resources: { db: sqlite() }, dataLayer: junoDataLayer() });
+```
+
+Then, ambiently — no handle to thread, `ctx` stays identity-only; use inside a
+request (a loader/view/action):
 
 ```ts
-import { juno } from "@junejs/juno";
+import { table } from "@junejs/juno";
+import { db } from "@junejs/server"; // the one canonical handle
 
-const db = juno(ctx.db); // ctx.db is the injected `db` resource
-await db.table("users").all();
-await db.table("users").findBy({ email: "ada@x.dev" });
-await db.table("users").insert({ name: "Ada" });
-await db.table("users").update({ id: 1 }, { name: "Ada Lovelace" });
+await table("users").findBy({ email: "ada@x.dev" });         // point read (auto-batches)
+await table("posts").all(
+  { user_id: 7, created_at: { gte: cutoff }, title: { like: "%june%" } },
+  { orderBy: { created_at: "desc" }, limit: 20, offset: 0 },
+);
+await table("users").upsert({ email: "ada@x.dev", name: "Ada" }, { onConflict: "email" });
+await db.query("select * from users where age > ?", [18]);   // raw escape hatch (auto-tags)
 ```
 
-## The magic is opt-in, not load-bearing
+## Non-obvious facts (the easy-to-get-wrong bits)
+
+The API shape is self-explanatory; these are the things models and humans get
+backwards. High-signal on purpose — read these, skip re-deriving the obvious.
+
+- **Write the naive thing — the automatic layer makes it fast/correct.** Don't
+  hand-roll caching or batching loops on top; that's what Juno is for.
+- **`findBy` / `all` by a single column auto-batch per request.** Naive per-component
+  reads coalesce into one `where col in (...)` — do NOT manually collect ids to batch.
+- **Use `upsert(values, { onConflict })`** — atomic, one round trip, returns the row.
+  NOT `findBy`-then-`insert` (an extra round trip and a race).
+- **Auto-invalidation fires at the ACTION boundary, not on a write.** A mutation must
+  be a `defineAction`; a direct `insert`/`update` outside an action invalidates no
+  `cache()`. Don't expect a bare write to refresh a cached read.
+- **On D1 / edge, round trips dominate — not the engine.** Auto-batch kills
+  *sequential* N+1 (the catastrophe). Versus *concurrent* reads the win is modest —
+  concurrency already hides latency. Never go sequential; don't over-credit
+  batch-vs-concurrent.
+- **OR and joins → the raw `db` escape hatch.** `all()` covers AND-of-operators
+  (`eq/ne/gt/gte/lt/lte/in/like`) + order / limit / offset; raw SQL is first-class
+  for the rest, and the canonical `db` auto-tags it (so a raw read inside `cache()`
+  is invalidated by a write, not silently stale).
+
+## Tiers (Juno is optional)
 
-Juno is the **default** that ships at Tier 3: every read calls `recordTableRead`
-and every write `recordTableWrite` (@junejs/core's public trace contract). That is
-what makes `cache()` auto-tag by table and a mutation **auto-invalidate** the
-cache (and push live RSC) with zero manual `revalidate()`.
+The framework works fully without Juno. **Tier 1** = bring your own (Prisma/Drizzle),
+untouched. **Tier 2** = your ORM over the ambient `db` resource. **Tier 3** = Juno
+(or any thin shim emitting `recordTableRead`/`recordTableWrite`) for the
+auto-invalidate / auto-batch / live-RSC magic. See `docs/data-layer-boundary.md`.
 
-This is a property of emitting the trace signals, **not** of using Juno. The
-framework depends on the contract, never on Juno — so Prisma/Drizzle stay
-first-class (Tier 1 = bring your own, untouched; Tier 2 = your ORM over `ctx.db`;
-Tier 3 = the same magic via a thin shim). See `docs/data-layer-boundary.md`.
+For tests or bring-your-own wiring, the explicit handle still works:
+`const j = juno(someDb); await j.table("users").all()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/juno",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Juno — June's ergonomic data layer over the JuneDb contract. The default that ships with the agent-native magic (Tier 3).",
   "type": "module",
   "license": "MIT",
@@ -16,10 +16,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@junejs/core": "0.0.13"
+    "@junejs/core": "0.0.15",
+    "@junejs/db": "0.0.15"
   },
   "devDependencies": {
-    "@junejs/server": "0.0.13"
+    "@junejs/server": "0.0.15"
   },
   "repository": {
     "type": "git",

package/src/ast.ts

@@ -0,0 +1,57 @@
+// Operation-node AST — the immutable shape a query compiles from. Stage 1 covers
+// exactly what the table API emits today (select with equality `where` + optional
+// limit, insert, update, delete, upsert); Stage 2 grows where-operators / joins /
+// order. Nodes carry SHAPE only (table + column names), never parameter values —
+// so a node IS its own structural cache key for compile-once. A dialect compiler
+// (compiler.ts) walks these; placeholders/quoting/upsert syntax vary by subclass.
+
+export type Node = SelectNode | InsertNode | UpdateNode | DeleteNode | UpsertNode;
+
+// Comparison operators a WHERE predicate can use (Stage 2). `in` is variadic — its
+// placeholder count is the value array's length, so it carries `arity` (which makes
+// the SQL shape, hence the compile-once key, depend on the list length).
+export type CmpOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "like";
+export type Predicate = { col: string; op: CmpOp } | { col: string; op: "in"; arity: number };
+export type OrderTerm = { col: string; dir: "asc" | "desc" };
+
+// `select * from <from> [where <pred> and ...] [order by ...] [limit ?] [offset ?]`.
+// Predicates are AND-joined (OR → the raw escape hatch). `limit` is a literal number
+// (findBy's `limit 1`) or "param" (bound, so all limits share one compiled SQL);
+// `offset` is always bound.
+export type SelectNode = {
+  kind: "select";
+  from: string;
+  where: Predicate[];
+  orderBy?: OrderTerm[];
+  limit?: number | "param";
+  offset?: "param";
+};
+
+export type InsertNode = {
+  kind: "insert";
+  into: string;
+  columns: string[];
+};
+
+export type UpdateNode = {
+  kind: "update";
+  table: string;
+  set: string[];
+  where: string[];
+};
+
+export type DeleteNode = {
+  kind: "delete";
+  from: string;
+  where: string[];
+};
+
+// `insert into <into> (cols) values (?) on conflict (conflict) do update set
+// <update[i]> = excluded.<update[i]> returning *`.
+export type UpsertNode = {
+  kind: "upsert";
+  into: string;
+  columns: string[];
+  conflict: string[];
+  update: string[];
+};

package/src/batch.ts

@@ -71,3 +71,72 @@ export function tableLoader<V extends Row = Row>(
     (row) => (row as Row)[key] as string | number,
   );
 }
+
+export type ListLoader<K, V> = {
+  load(key: K): Promise<V[]>;
+};
+
+// Like createLoader, but resolves ALL rows for a key — the list shape (e.g. a
+// user's posts), where `where key in (...)` returns many rows per key.
+export function createGroupLoader<K, V>(
+  batchFn: (keys: K[]) => Promise<V[]>,
+  keyOf: (value: V) => K,
+): ListLoader<K, V> {
+  let queue: { key: K; resolve: (v: V[]) => void; reject: (e: unknown) => void }[] = [];
+  let scheduled = false;
+
+  function flush() {
+    const batch = queue;
+    queue = [];
+    scheduled = false;
+    const keys = [...new Set(batch.map((b) => b.key))];
+    batchFn(keys).then(
+      (values) => {
+        const byKey = new Map<K, V[]>();
+        for (const v of values) {
+          const k = keyOf(v);
+          const list = byKey.get(k);
+          if (list) list.push(v);
+          else byKey.set(k, [v]);
+        }
+        for (const b of batch) b.resolve(byKey.get(b.key) ?? []);
+      },
+      (err) => {
+        for (const b of batch) b.reject(err);
+      },
+    );
+  }
+
+  return {
+    load(key: K) {
+      return new Promise<V[]>((resolve, reject) => {
+        queue.push({ key, resolve, reject });
+        if (!scheduled) {
+          scheduled = true;
+          queueMicrotask(flush);
+        }
+      });
+    },
+  };
+}
+
+// A by-key LIST loader over a JuneDb table: `loader.load(userId)` calls coalesce
+// into one `select * from <table> where <key> in (...)`, each resolving to that
+// key's rows. The list analog of tableLoader. Build one per request.
+export function tableListLoader<V extends Row = Row>(
+  db: JuneDb,
+  table: string,
+  key = "id",
+): ListLoader<string | number, V> {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+    throw new Error(`unsafe SQL identifier: ${table}.${key}`);
+  }
+  return createGroupLoader<string | number, V>(
+    async (keys) => {
+      recordTableRead(table);
+      const placeholders = keys.map(() => "?").join(", ");
+      return db.query<V>(`select * from ${table} where ${key} in (${placeholders})`, keys);
+    },
+    (row) => (row as Row)[key] as string | number,
+  );
+}

package/src/compiler.ts

@@ -0,0 +1,134 @@
+// The dialect compiler — walks an operation-node AST (ast.ts) into a SQL string.
+// A `Dialect` is the seam multi-dialect lands on: subclasses override placeholder
+// style / quoting / upsert syntax. SqliteDialect (sqlite + D1) is the default; a
+// PostgresDialect (`$n` placeholders) slots in later as another subclass.
+//
+// Compile-once: `compile()` memoizes by the node's structural key. Nodes hold
+// shape only (no parameter values), so the same query shape compiles ONCE and
+// every later call reuses the string — what Kysely-style builders don't do (they
+// recompile per execute). Param VALUES are bound by the caller, never cached.
+
+import type { CmpOp, Node, Predicate } from "./ast";
+
+const SYM: Record<CmpOp, string> = {
+  eq: "=",
+  ne: "!=",
+  gt: ">",
+  gte: ">=",
+  lt: "<",
+  lte: "<=",
+  like: "like",
+};
+
+// Emit one WHERE predicate. `ph()` yields the next placeholder (and advances the
+// dialect's counter), so `in` can consume `arity` of them in order.
+function predicate(p: Predicate, ph: () => string): string {
+  if (p.op === "in") {
+    return `${ident(p.col)} in (${Array.from({ length: p.arity }, ph).join(", ")})`;
+  }
+  return `${ident(p.col)} ${SYM[p.op]} ${ph()}`;
+}
+
+// Guard table/column names — identifiers can't be parameterized. Values always go
+// through bound placeholders, so they are injection-safe by construction.
+export function ident(name: string): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`unsafe SQL identifier: ${name}`);
+  return name;
+}
+
+// A compact structural key: kind + table + column/clause shape. Excludes values
+// (nodes carry none), so structurally-equal queries share one compiled string.
+function keyOf(node: Node): string {
+  switch (node.kind) {
+    case "select":
+      return (
+        `s|${node.from}|` +
+        node.where.map((p) => (p.op === "in" ? `${p.col}:in${p.arity}` : `${p.col}:${p.op}`)).join("&") +
+        `|${(node.orderBy ?? []).map((o) => `${o.col} ${o.dir}`).join(",")}` +
+        `|${node.limit ?? ""}|${node.offset ?? ""}`
+      );
+    case "insert":
+      return `i|${node.into}|${node.columns.join(",")}`;
+    case "update":
+      return `u|${node.table}|${node.set.join(",")}|${node.where.join(",")}`;
+    case "delete":
+      return `d|${node.from}|${node.where.join(",")}`;
+    case "upsert":
+      return `x|${node.into}|${node.columns.join(",")}|${node.conflict.join(",")}|${node.update.join(",")}`;
+  }
+}
+
+export abstract class Dialect {
+  // Process-level (a SqliteDialect singleton is shared across requests): the
+  // compiled SQL is data-free, so caching it across requests is safe and is the
+  // whole point of compile-once.
+  private readonly cache = new Map<string, string>();
+
+  compile(node: Node): string {
+    const key = keyOf(node);
+    let sql = this.cache.get(key);
+    if (sql === undefined) {
+      sql = this.emit(node); // throws on a bad identifier before caching
+      this.cache.set(key, sql);
+    }
+    return sql;
+  }
+
+  // The i-th bound placeholder (1-based). Sqlite ignores i (`?`); Postgres uses `$i`.
+  protected abstract placeholder(i: number): string;
+
+  protected emit(node: Node): string {
+    switch (node.kind) {
+      case "select": {
+        let i = 0;
+        const ph = () => this.placeholder(++i);
+        const where = node.where.length
+          ? ` where ${node.where.map((p) => predicate(p, ph)).join(" and ")}`
+          : "";
+        const order = node.orderBy?.length
+          ? ` order by ${node.orderBy.map((o) => `${ident(o.col)} ${o.dir === "desc" ? "desc" : "asc"}`).join(", ")}`
+          : "";
+        const limit = node.limit === "param" ? ` limit ${ph()}` : node.limit != null ? ` limit ${node.limit}` : "";
+        const offset = node.offset === "param" ? ` offset ${ph()}` : "";
+        return `select * from ${ident(node.from)}${where}${order}${limit}${offset}`;
+      }
+      case "insert": {
+        let i = 0;
+        const cols = node.columns.map(ident);
+        const vals = node.columns.map(() => this.placeholder(++i));
+        return `insert into ${ident(node.into)} (${cols.join(", ")}) values (${vals.join(", ")})`;
+      }
+      case "update": {
+        let i = 0;
+        const set = node.set.map((c) => `${ident(c)} = ${this.placeholder(++i)}`).join(", ");
+        const where = node.where.map((c) => `${ident(c)} = ${this.placeholder(++i)}`).join(" and ");
+        return `update ${ident(node.table)} set ${set} where ${where}`;
+      }
+      case "delete": {
+        let i = 0;
+        const where = node.where.map((c) => `${ident(c)} = ${this.placeholder(++i)}`).join(" and ");
+        return `delete from ${ident(node.from)} where ${where}`;
+      }
+      case "upsert": {
+        let i = 0;
+        const cols = node.columns.map(ident);
+        const vals = node.columns.map(() => this.placeholder(++i));
+        const set = node.update.map((c) => `${ident(c)} = excluded.${ident(c)}`).join(", ");
+        return (
+          `insert into ${ident(node.into)} (${cols.join(", ")}) values (${vals.join(", ")}) ` +
+          `on conflict (${node.conflict.map(ident).join(", ")}) do update set ${set} returning *`
+        );
+      }
+    }
+  }
+}
+
+export class SqliteDialect extends Dialect {
+  protected placeholder(): string {
+    return "?";
+  }
+}
+
+// The default dialect (sqlite + D1). A shared singleton so its compile-once cache
+// is process-level. Postgres adds a sibling subclass later.
+export const sqlite = new SqliteDialect();

package/src/index.ts

@@ -11,19 +11,41 @@
 import type { JuneDb, RunResult } from "@junejs/core/resources";
 import { recordTableRead, recordTableWrite } from "@junejs/core/instrumentation";
 
-import { tableLoader, type Loader } from "./batch";
-import { taggingDb } from "./tag";
+import type { DataLayer } from "@junejs/core/config";
+import { db as ambientDb, requestLocal, registerSqlTagger } from "@junejs/db";
 
-export { createLoader, tableLoader, type Loader } from "./batch";
+import type { Predicate, SelectNode } from "./ast";
+import { tableLoader, tableListLoader, type Loader, type ListLoader } from "./batch";
+import { sqlite } from "./compiler";
+import { taggingDb, tagSql } from "./tag";
+
+export { createLoader, createGroupLoader, tableLoader, tableListLoader, type Loader, type ListLoader } from "./batch";
 export { tablesFromSql, tagSql, taggingDb, type SqlTouch } from "./tag";
+export { Dialect, SqliteDialect, sqlite, ident } from "./compiler";
+export type { Node, SelectNode, InsertNode, UpdateNode, DeleteNode, UpsertNode } from "./ast";
 
 export type Row = Record<string, unknown>;
 
-// Guard table/column names (identifiers can't be parameterized). Values always
-// go through bound `?` placeholders, so they are injection-safe by construction.
-function ident(name: string): string {
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`unsafe SQL identifier: ${name}`);
-  return name;
+// A WHERE value is either an equality value or an operator object (Stage 2).
+// `{ age: { gte: 18 }, name: { like: "%a%" }, id: { in: [1, 2] } }` — AND-joined.
+export type Operators = {
+  eq?: unknown;
+  ne?: unknown;
+  gt?: unknown;
+  gte?: unknown;
+  lt?: unknown;
+  lte?: unknown;
+  in?: unknown[];
+  like?: string;
+};
+export type Where<T> = { [K in keyof T]?: T[K] | Operators };
+export type OrderBy<T> = { [K in keyof T]?: "asc" | "desc" };
+
+const OPS = new Set(["eq", "ne", "gt", "gte", "lt", "lte", "in", "like"]);
+// An operator object is a non-array object (sqlite values are primitives, so a
+// non-array object in a WHERE position means operators, not a bound value).
+function isOperators(v: unknown): v is Operators {
+  return v != null && typeof v === "object" && !Array.isArray(v);
 }
 
 export class Table<T extends Row = Row> {
@@ -31,14 +53,67 @@ export class Table<T extends Row = Row> {
     private readonly db: JuneDb,
     private readonly name: string,
     // Per-request ambient-loader registry, shared across the juno() handle's
-    // .table() calls so concurrent findBy coalesce. Optional/defaulted so a
-    // standalone `new Table(db, name)` still works (it just batches alone).
-    private readonly loaders: Map<string, Loader<string | number, Row>> = new Map(),
+    // .table() calls so concurrent findBy/all coalesce. Holds both point and list
+    // loaders (keyed apart). Optional/defaulted so a standalone `new Table(db,
+    // name)` still works (it just batches alone).
+    private readonly loaders: Map<string, unknown> = new Map(),
   ) {}
 
-  async all(): Promise<T[]> {
+  // No `where` → every row. With a `where`, the list of rows matching it (the list
+  // counterpart of findBy, same where syntax). A single-column filter ambient-
+  // batches like findBy — concurrent `all({user_id})` across components coalesce
+  // into one `where user_id in (...)` grouped by key (list N+1 → 1).
+  async all(
+    where?: Where<T>,
+    opts?: { orderBy?: OrderBy<T>; limit?: number; offset?: number },
+  ): Promise<T[]> {
     recordTableRead(this.name); // auto-tag: a cache() around this gets table:<name>
-    return this.db.query<T>(`select * from ${ident(this.name)}`);
+    const w = (where ?? {}) as Row;
+    const keys = Object.keys(w);
+    const [col] = keys;
+    // Ambient batch only for a single-column EQUALITY filter with no opts —
+    // operators / multi-column / order / limit fall through to a direct query.
+    if (!opts && keys.length === 1 && col !== undefined && !isOperators(w[col])) {
+      return this.ambientListLoader(col).load(w[col] as string | number) as Promise<T[]>;
+    }
+
+    const predicates: Predicate[] = [];
+    const params: unknown[] = [];
+    for (const c of keys) {
+      const v = w[c];
+      if (isOperators(v)) {
+        for (const op of Object.keys(v)) {
+          if (!OPS.has(op)) throw new Error(`unknown operator: ${op}`);
+          const operand = (v as Record<string, unknown>)[op];
+          if (op === "in") {
+            const arr = operand as unknown[];
+            predicates.push({ col: c, op: "in", arity: arr.length });
+            params.push(...arr);
+          } else {
+            predicates.push({ col: c, op: op as Exclude<keyof Operators, "in"> });
+            params.push(operand);
+          }
+        }
+      } else {
+        predicates.push({ col: c, op: "eq" });
+        params.push(v);
+      }
+    }
+
+    const orderBy = opts?.orderBy
+      ? (Object.entries(opts.orderBy) as [string, "asc" | "desc"][]).map(([c, dir]) => ({ col: c, dir }))
+      : undefined;
+    const node: SelectNode = {
+      kind: "select",
+      from: this.name,
+      where: predicates,
+      orderBy,
+      limit: opts?.limit != null ? "param" : undefined,
+      offset: opts?.offset != null ? "param" : undefined,
+    };
+    if (opts?.limit != null) params.push(opts.limit);
+    if (opts?.offset != null) params.push(opts.offset);
+    return this.db.query<T>(sqlite.compile(node), params);
   }
 
   async findBy(where: Partial<T>): Promise<T | undefined> {
@@ -54,9 +129,9 @@ export class Table<T extends Row = Row> {
       const hit = await this.ambientLoader(col).load((where as Row)[col] as string | number);
       return (hit ?? undefined) as T | undefined;
     }
-    const cols = keys.map(ident);
-    const clause = cols.length ? ` where ${cols.map((k) => `${k} = ?`).join(" and ")}` : "";
-    return this.db.get<T>(`select * from ${ident(this.name)}${clause} limit 1`, Object.values(where));
+    const where2: Predicate[] = keys.map((k) => ({ col: k, op: "eq" }));
+    const sql = sqlite.compile({ kind: "select", from: this.name, where: where2, limit: 1 });
+    return this.db.get<T>(sql, Object.values(where));
   }
 
   // get-or-create the per-request ambient loader for (table, column). tableLoader
@@ -71,30 +146,55 @@ export class Table<T extends Row = Row> {
     return loader as Loader<string | number, T>;
   }
 
+  // get-or-create the per-request ambient LIST loader for (table, column). Keyed
+  // apart from the point loader (`list:` prefix) — they coalesce different shapes.
+  private ambientListLoader(col: string): ListLoader<string | number, T> {
+    const key = `list:${this.name}::${col}`;
+    let loader = this.loaders.get(key);
+    if (!loader) {
+      loader = tableListLoader<Row>(this.db, this.name, col);
+      this.loaders.set(key, loader);
+    }
+    return loader as ListLoader<string | number, T>;
+  }
+
   async insert(values: Partial<T>): Promise<RunResult> {
     recordTableWrite(this.name); // auto-invalidate: invokeAction drops table:<name>
-    const cols = Object.keys(values).map(ident);
-    const placeholders = cols.map(() => "?").join(", ");
-    return this.db.run(
-      `insert into ${ident(this.name)} (${cols.join(", ")}) values (${placeholders})`,
-      Object.values(values),
-    );
+    const sql = sqlite.compile({ kind: "insert", into: this.name, columns: Object.keys(values) });
+    return this.db.run(sql, Object.values(values));
+  }
+
+  // Atomic insert-or-update: insert `values`; on a conflict of the `onConflict`
+  // column(s), update the other provided columns to the new values. Returns the
+  // upserted row (via RETURNING) in ONE round trip — the primitive that removes
+  // the findBy-then-insert footgun (eval A2/A3). If every provided column is a
+  // conflict key, it no-ops the update so RETURNING still yields the existing row
+  // (a get-or-create).
+  async upsert(values: Partial<T>, opts: { onConflict: string | string[] }): Promise<T | undefined> {
+    recordTableWrite(this.name);
+    const columns = Object.keys(values);
+    const conflict = Array.isArray(opts.onConflict) ? opts.onConflict : [opts.onConflict];
+    const updates = columns.filter((c) => !conflict.includes(c));
+    const update = updates.length ? updates : conflict;
+    const sql = sqlite.compile({ kind: "upsert", into: this.name, columns, conflict, update });
+    return this.db.get<T>(sql, Object.values(values));
   }
 
   async update(where: Partial<T>, values: Partial<T>): Promise<RunResult> {
     recordTableWrite(this.name);
-    const set = Object.keys(values).map((k) => `${ident(k)} = ?`).join(", ");
-    const cond = Object.keys(where).map((k) => `${ident(k)} = ?`).join(" and ");
-    return this.db.run(
-      `update ${ident(this.name)} set ${set} where ${cond}`,
-      [...Object.values(values), ...Object.values(where)],
-    );
+    const sql = sqlite.compile({
+      kind: "update",
+      table: this.name,
+      set: Object.keys(values),
+      where: Object.keys(where),
+    });
+    return this.db.run(sql, [...Object.values(values), ...Object.values(where)]);
   }
 
   async delete(where: Partial<T>): Promise<RunResult> {
     recordTableWrite(this.name);
-    const cond = Object.keys(where).map((k) => `${ident(k)} = ?`).join(" and ");
-    return this.db.run(`delete from ${ident(this.name)} where ${cond}`, Object.values(where));
+    const sql = sqlite.compile({ kind: "delete", from: this.name, where: Object.keys(where) });
+    return this.db.run(sql, Object.values(where));
   }
 
   // A per-request by-key loader: concurrent .load(key) calls during one render
@@ -124,7 +224,7 @@ export type Juno = {
 // findBy across components coalesce — and scoping it to the per-request handle
 // is what keeps keys from leaking across requests.
 export function juno(db: JuneDb): Juno {
-  const loaders = new Map<string, Loader<string | number, Row>>();
+  const loaders = new Map<string, unknown>();
   return {
     // Table API uses the raw db and tags explicitly (precise, parser-independent);
     // the exposed handle wraps it so the raw escape hatch auto-tags too.
@@ -140,3 +240,43 @@ export function juno(db: JuneDb): Juno {
     },
   };
 }
+
+// --- Ambient surface (the framework-native way) --------------------------------
+// Matches June's ambient resources (`import { db } from "@junejs/db"`): no handle
+// to thread or mis-scope. `table()` reads the ambient `db` resource and a
+// per-request loader registry kept in the request scope, so batching is
+// STRUCTURALLY per-request and unstashable — the leak A3 found can't happen.
+// Use inside a request scope (a loader/view/action); throws otherwise, like `db`.
+const LOADERS = Symbol.for("junejs.juno.loaders");
+
+// The boot wiring: register Juno's SQL tagger so the canonical ambient `db`
+// auto-tags raw queries. `june build` imports THIS by name into the worker.
+export function installDataLayer(): void {
+  registerSqlTagger(tagSql);
+}
+
+// Declare Juno as the app's data layer in june.config.ts: `dataLayer: junoDataLayer()`.
+// The dev host calls install() at boot; `june build` emits installDataLayer() into
+// the worker (via `module`). Explicit (config-declared), NOT an import-time global
+// side-effect — and the framework still never imports Juno (the user's config does).
+export function junoDataLayer(): DataLayer {
+  return { install: installDataLayer, module: "@junejs/juno" };
+}
+
+export function table<T extends Row = Row>(name: string): Table<T> {
+  const loaders = requestLocal(LOADERS, () => new Map<string, unknown>());
+  return new Table<T>(ambientDb, name, loaders);
+}
+
+// No separate ambient `db` export: the canonical `db` from `@junejs/db` (and
+// re-exported by `@junejs/server`) auto-tags once Juno is imported (above), so
+// there is exactly one `db` to import. `taggingDb` remains for the explicit
+// `juno(handle)` path, where it wraps a caller-supplied handle.
+
+// Explicit tag/invalidate hatch, ambiently (no handle needed — they only record).
+export function reads(...tables: string[]): void {
+  for (const t of tables) recordTableRead(t);
+}
+export function writes(...tables: string[]): void {
+  for (const t of tables) recordTableWrite(t);
+}

package/src/tag.ts

@@ -64,20 +64,21 @@ export function tagSql(sql: string): void {
 // table API keeps tagging explicitly (precise, parser-independent); this covers
 // the raw escape hatch so `cache(() => db.query("select ... from posts"))` is
 // invalidated by a posts write instead of going silently stale.
+//
+// A PROXY, not a spread: the ambient `db` resource is itself a Proxy whose methods
+// come from a get-trap, so `{ ...db }` would drop exec/transaction/close. The
+// Proxy forwards everything to the underlying handle and only wraps query/get/run.
 export function taggingDb(db: JuneDb): JuneDb {
-  return {
-    ...db,
-    query<T = unknown>(sql: string, params?: unknown[]) {
-      tagSql(sql);
-      return db.query<T>(sql, params);
+  const query = <T = unknown>(sql: string, params?: unknown[]) => (tagSql(sql), db.query<T>(sql, params));
+  const get = <T = unknown>(sql: string, params?: unknown[]) => (tagSql(sql), db.get<T>(sql, params));
+  const run = (sql: string, params?: unknown[]) => (tagSql(sql), db.run(sql, params));
+  return new Proxy(db, {
+    get(target, prop, receiver) {
+      if (prop === "query") return query;
+      if (prop === "get") return get;
+      if (prop === "run") return run;
+      const value = Reflect.get(target, prop, receiver);
+      return typeof value === "function" ? value.bind(target) : value;
     },
-    get<T = unknown>(sql: string, params?: unknown[]) {
-      tagSql(sql);
-      return db.get<T>(sql, params);
-    },
-    run(sql: string, params?: unknown[]) {
-      tagSql(sql);
-      return db.run(sql, params);
-    },
-  };
+  });
 }