@lunora/hyperdrive 1.0.0-alpha.8 → 1.0.0-alpha.80

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/dist/global.d.mts

@@ -1,46 +1,71 @@
-import { DatabaseWriterLike } from '@lunora/do';
+import { DatabaseWriterLike } from '@lunora/shard-engine';
 import { SqlExec, SqlDialect, SqlCtxDbOptions } from '@lunora/sql-store';
-/** Minimal row-returning client (e.g. `@lunora/hyperdrive`'s `fromPostgresJs`/`fromNodePg` result). */
-interface RowClient {
-  query: <Row = Record<string, unknown>>(text: string, params?: ReadonlyArray<unknown>) => Promise<Row[]>;
-}
-/** Minimal `mysql2/promise` connection/pool surface — `execute` resolves to `[rows | ResultSetHeader, fields]`. */
-interface Mysql2Execute {
-  execute: (text: string, params?: ReadonlyArray<unknown>) => Promise<[unknown, unknown]>;
-}
+import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-DE1NYxyA.mjs";
+/**
+ * Minimal row-returning client (e.g. `@lunora/hyperdrive`'s `fromPostgresJs`/`fromNodePg`
+ * result). Aliases {@link SqlClient} — the exec-facing name is kept so call sites read
+ * intent, but the shape is the single source of truth in `./types` (no drift).
+ */
+type RowClient = SqlClient;
+/**
+ * Minimal `mysql2/promise` connection/pool surface — `execute` resolves to
+ * `[rows | ResultSetHeader, fields]`. Aliases {@link Mysql2Like} so the /global entry's
+ * driver surface can never drift from the main entry's.
+ */
+type Mysql2Execute = Mysql2Like;
 /**
-* Wrap a Postgres row-client (from `@lunora/hyperdrive`'s `fromPostgresJs` /
-* `fromNodePg`) as a {@link SqlExec}. The core already renders `$N` placeholders
-* for Postgres, so `all`/`run` forward verbatim. Postgres uses `RETURNING` for
-* OCC (read via `all`), so `run` reports no affected-row count.
-*/
+ * Wrap a Postgres row-client (from `@lunora/hyperdrive`'s `fromPostgresJs` /
+ * `fromNodePg`) as a {@link SqlExec}. The core already renders `$N` placeholders
+ * for Postgres, so `all`/`run` forward verbatim. Postgres uses `RETURNING` for
+ * OCC (read via `all`), so `run` reports no affected-row count.
+ *
+ * `batch` dispatches every statement concurrently (`Promise.all`) over `client`
+ * rather than awaiting each `query` call in turn — `RowClient` only exposes a
+ * single-statement `query`, so there is no wire-level multi-statement command
+ * to reach for. When `client` is backed by a pool (the common production
+ * shape), this genuinely spreads the statements across multiple physical
+ * connections instead of serializing one full round trip at a time; against a
+ * single connection it still removes the sequential *await*, though the
+ * underlying driver may itself queue the sends. Either way it stays
+ * non-atomic, at-least-once, and unordered between elements, same as the
+ * sequential fallback minus the ordering — safe only for statements whose
+ * effects don't depend on each other, which is what every current caller
+ * batches (distinct-keyed companion rows).
+ */
 declare const buildPgExec: (client: RowClient) => SqlExec;
 /**
-* Wrap a `mysql2/promise` connection/pool as a {@link SqlExec}. The core already
-* renders backtick identifiers and `?` placeholders for MySQL, so `all`/`run`
-* forward verbatim. MySQL has no `RETURNING`, so `run` surfaces `affectedRows`
-* for the store's affected-rows OCC guard.
-*
-* **The connection MUST be created with the `CLIENT_FOUND_ROWS` flag**
-* (mysql2: `createPool({ flags: ["FOUND_ROWS"] })`). Without it, `affectedRows`
-* counts *changed* rows, so an idempotent `patch`/`replace` that re-writes the
-* same values reports 0 and the OCC guard raises a spurious conflict.
-*/
+ * Wrap a `mysql2/promise` connection/pool as a {@link SqlExec}. The core already
+ * renders backtick identifiers and `?` placeholders for MySQL, so `all`/`run`
+ * forward verbatim. MySQL has no `RETURNING`, so `run` surfaces `affectedRows`
+ * for the store's affected-rows OCC guard.
+ *
+ * **The connection MUST be created with the `CLIENT_FOUND_ROWS` flag**
+ * (mysql2: `createPool({ flags: ["FOUND_ROWS"] })`). Without it, `affectedRows`
+ * counts *changed* rows, so an idempotent `patch`/`replace` that re-writes the
+ * same values reports 0 and the OCC guard raises a spurious conflict.
+ *
+ * `batch` dispatches every statement concurrently (`Promise.all`), same
+ * rationale as {@link buildPgExec}'s `batch` — `Mysql2Like` only exposes a
+ * single-statement `execute`, so this is "spread across a pool's connections"
+ * rather than one wire-level multi-statement command; still non-atomic,
+ * at-least-once, and unordered between elements, safe only for statements
+ * with no cross-effect (what every current caller batches).
+ */
 declare const buildMysqlExec: (connection: Mysql2Execute) => SqlExec;
 /**
-* **Postgres** dialect. Differs from SQLite only in column types
-* (`DOUBLE PRECISION`/`BYTEA`/`BIGSERIAL`), the `information_schema` catalog
-* probe, and unique-violation detection (SQLSTATE `23505`).
-*/
+ * **Postgres** dialect. Differs from SQLite only in column types
+ * (`DOUBLE PRECISION`/`BYTEA`/`BIGSERIAL`), the `information_schema` catalog
+ * probe, and unique-violation detection (SQLSTATE `23505`).
+ */
 declare const postgresDialect: SqlDialect;
 /**
-* **MySQL** dialect. Diverges in: **no `RETURNING`** (the store's OCC falls back
-* to affected-rows — which requires the connection's `CLIENT_FOUND_ROWS` flag so
-* a no-op update still reports a matched row, see `buildMysqlExec`); bounded
-* `VARCHAR` keys (TEXT can't be a primary key / unindexed); a TEXT/BLOB index key
-* prefix; and `ER_DUP_ENTRY` (errno 1062) unique violations. (Drizzle's MySQL
-* dialect supplies the backtick identifiers + `ON DUPLICATE KEY` upserts.)
-*/
+ * **MySQL** dialect. Diverges in: **no `RETURNING`** (the store's OCC falls back
+ * to affected-rows — which requires the connection's `CLIENT_FOUND_ROWS` flag so
+ * a no-op update still reports a matched row, see `buildMysqlExec`); bounded
+ * `VARCHAR` keys (TEXT can't be a primary key / unindexed); a TEXT/BLOB index key
+ * prefix; and `ER_DUP_ENTRY` (errno 1062) unique violations. (Drizzle's MySQL
+ * dialect supplies the backtick identifiers + `ON DUPLICATE KEY` upserts.)
+ */
 declare const mysqlDialect: SqlDialect;
 /** Which engine a Hyperdrive-backed `.global()` store targets. */
 type HyperdriveEngine = "mysql" | "postgres";
@@ -52,16 +77,12 @@ interface CreateHyperdriveGlobalCtxDbOptions extends Omit<SqlCtxDbOptions, "dial
   exec: SqlExec;
 }
 /**
-* Build a reactive `.global()` writer backed by a Hyperdrive-reachable
-* Postgres/MySQL database. Pass a built {@link SqlExec} (via {@link buildPgExec}/
-* {@link buildMysqlExec}) and the matching `engine`; everything else mirrors the
-* D1 store options.
-*/
-declare const createHyperdriveGlobalCtxDb: ({
-  engine,
-  exec,
-  ...rest
-}: CreateHyperdriveGlobalCtxDbOptions) => DatabaseWriterLike;
+ * Build a reactive `.global()` writer backed by a Hyperdrive-reachable
+ * Postgres/MySQL database. Pass a built {@link SqlExec} (via {@link buildPgExec}/
+ * {@link buildMysqlExec}) and the matching `engine`; everything else mirrors the
+ * D1 store options.
+ */
+declare const createHyperdriveGlobalCtxDb: ({ engine, exec, ...rest }: CreateHyperdriveGlobalCtxDbOptions) => DatabaseWriterLike;
 /** Convenience: a **Postgres** `.global()` writer from a row-client (postgres.js/pg over Hyperdrive). */
 declare const createPostgresGlobalCtxDb: (client: RowClient, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
 /** Convenience: a **MySQL** `.global()` writer from a `mysql2/promise` connection/pool (created with `flags: ["FOUND_ROWS"]`). */

package/dist/global.d.ts

@@ -1,46 +1,71 @@
-import { DatabaseWriterLike } from '@lunora/do';
+import { DatabaseWriterLike } from '@lunora/shard-engine';
 import { SqlExec, SqlDialect, SqlCtxDbOptions } from '@lunora/sql-store';
-/** Minimal row-returning client (e.g. `@lunora/hyperdrive`'s `fromPostgresJs`/`fromNodePg` result). */
-interface RowClient {
-  query: <Row = Record<string, unknown>>(text: string, params?: ReadonlyArray<unknown>) => Promise<Row[]>;
-}
-/** Minimal `mysql2/promise` connection/pool surface — `execute` resolves to `[rows | ResultSetHeader, fields]`. */
-interface Mysql2Execute {
-  execute: (text: string, params?: ReadonlyArray<unknown>) => Promise<[unknown, unknown]>;
-}
+import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-DE1NYxyA.js";
+/**
+ * Minimal row-returning client (e.g. `@lunora/hyperdrive`'s `fromPostgresJs`/`fromNodePg`
+ * result). Aliases {@link SqlClient} — the exec-facing name is kept so call sites read
+ * intent, but the shape is the single source of truth in `./types` (no drift).
+ */
+type RowClient = SqlClient;
+/**
+ * Minimal `mysql2/promise` connection/pool surface — `execute` resolves to
+ * `[rows | ResultSetHeader, fields]`. Aliases {@link Mysql2Like} so the /global entry's
+ * driver surface can never drift from the main entry's.
+ */
+type Mysql2Execute = Mysql2Like;
 /**
-* Wrap a Postgres row-client (from `@lunora/hyperdrive`'s `fromPostgresJs` /
-* `fromNodePg`) as a {@link SqlExec}. The core already renders `$N` placeholders
-* for Postgres, so `all`/`run` forward verbatim. Postgres uses `RETURNING` for
-* OCC (read via `all`), so `run` reports no affected-row count.
-*/
+ * Wrap a Postgres row-client (from `@lunora/hyperdrive`'s `fromPostgresJs` /
+ * `fromNodePg`) as a {@link SqlExec}. The core already renders `$N` placeholders
+ * for Postgres, so `all`/`run` forward verbatim. Postgres uses `RETURNING` for
+ * OCC (read via `all`), so `run` reports no affected-row count.
+ *
+ * `batch` dispatches every statement concurrently (`Promise.all`) over `client`
+ * rather than awaiting each `query` call in turn — `RowClient` only exposes a
+ * single-statement `query`, so there is no wire-level multi-statement command
+ * to reach for. When `client` is backed by a pool (the common production
+ * shape), this genuinely spreads the statements across multiple physical
+ * connections instead of serializing one full round trip at a time; against a
+ * single connection it still removes the sequential *await*, though the
+ * underlying driver may itself queue the sends. Either way it stays
+ * non-atomic, at-least-once, and unordered between elements, same as the
+ * sequential fallback minus the ordering — safe only for statements whose
+ * effects don't depend on each other, which is what every current caller
+ * batches (distinct-keyed companion rows).
+ */
 declare const buildPgExec: (client: RowClient) => SqlExec;
 /**
-* Wrap a `mysql2/promise` connection/pool as a {@link SqlExec}. The core already
-* renders backtick identifiers and `?` placeholders for MySQL, so `all`/`run`
-* forward verbatim. MySQL has no `RETURNING`, so `run` surfaces `affectedRows`
-* for the store's affected-rows OCC guard.
-*
-* **The connection MUST be created with the `CLIENT_FOUND_ROWS` flag**
-* (mysql2: `createPool({ flags: ["FOUND_ROWS"] })`). Without it, `affectedRows`
-* counts *changed* rows, so an idempotent `patch`/`replace` that re-writes the
-* same values reports 0 and the OCC guard raises a spurious conflict.
-*/
+ * Wrap a `mysql2/promise` connection/pool as a {@link SqlExec}. The core already
+ * renders backtick identifiers and `?` placeholders for MySQL, so `all`/`run`
+ * forward verbatim. MySQL has no `RETURNING`, so `run` surfaces `affectedRows`
+ * for the store's affected-rows OCC guard.
+ *
+ * **The connection MUST be created with the `CLIENT_FOUND_ROWS` flag**
+ * (mysql2: `createPool({ flags: ["FOUND_ROWS"] })`). Without it, `affectedRows`
+ * counts *changed* rows, so an idempotent `patch`/`replace` that re-writes the
+ * same values reports 0 and the OCC guard raises a spurious conflict.
+ *
+ * `batch` dispatches every statement concurrently (`Promise.all`), same
+ * rationale as {@link buildPgExec}'s `batch` — `Mysql2Like` only exposes a
+ * single-statement `execute`, so this is "spread across a pool's connections"
+ * rather than one wire-level multi-statement command; still non-atomic,
+ * at-least-once, and unordered between elements, safe only for statements
+ * with no cross-effect (what every current caller batches).
+ */
 declare const buildMysqlExec: (connection: Mysql2Execute) => SqlExec;
 /**
-* **Postgres** dialect. Differs from SQLite only in column types
-* (`DOUBLE PRECISION`/`BYTEA`/`BIGSERIAL`), the `information_schema` catalog
-* probe, and unique-violation detection (SQLSTATE `23505`).
-*/
+ * **Postgres** dialect. Differs from SQLite only in column types
+ * (`DOUBLE PRECISION`/`BYTEA`/`BIGSERIAL`), the `information_schema` catalog
+ * probe, and unique-violation detection (SQLSTATE `23505`).
+ */
 declare const postgresDialect: SqlDialect;
 /**
-* **MySQL** dialect. Diverges in: **no `RETURNING`** (the store's OCC falls back
-* to affected-rows — which requires the connection's `CLIENT_FOUND_ROWS` flag so
-* a no-op update still reports a matched row, see `buildMysqlExec`); bounded
-* `VARCHAR` keys (TEXT can't be a primary key / unindexed); a TEXT/BLOB index key
-* prefix; and `ER_DUP_ENTRY` (errno 1062) unique violations. (Drizzle's MySQL
-* dialect supplies the backtick identifiers + `ON DUPLICATE KEY` upserts.)
-*/
+ * **MySQL** dialect. Diverges in: **no `RETURNING`** (the store's OCC falls back
+ * to affected-rows — which requires the connection's `CLIENT_FOUND_ROWS` flag so
+ * a no-op update still reports a matched row, see `buildMysqlExec`); bounded
+ * `VARCHAR` keys (TEXT can't be a primary key / unindexed); a TEXT/BLOB index key
+ * prefix; and `ER_DUP_ENTRY` (errno 1062) unique violations. (Drizzle's MySQL
+ * dialect supplies the backtick identifiers + `ON DUPLICATE KEY` upserts.)
+ */
 declare const mysqlDialect: SqlDialect;
 /** Which engine a Hyperdrive-backed `.global()` store targets. */
 type HyperdriveEngine = "mysql" | "postgres";
@@ -52,16 +77,12 @@ interface CreateHyperdriveGlobalCtxDbOptions extends Omit<SqlCtxDbOptions, "dial
   exec: SqlExec;
 }
 /**
-* Build a reactive `.global()` writer backed by a Hyperdrive-reachable
-* Postgres/MySQL database. Pass a built {@link SqlExec} (via {@link buildPgExec}/
-* {@link buildMysqlExec}) and the matching `engine`; everything else mirrors the
-* D1 store options.
-*/
-declare const createHyperdriveGlobalCtxDb: ({
-  engine,
-  exec,
-  ...rest
-}: CreateHyperdriveGlobalCtxDbOptions) => DatabaseWriterLike;
+ * Build a reactive `.global()` writer backed by a Hyperdrive-reachable
+ * Postgres/MySQL database. Pass a built {@link SqlExec} (via {@link buildPgExec}/
+ * {@link buildMysqlExec}) and the matching `engine`; everything else mirrors the
+ * D1 store options.
+ */
+declare const createHyperdriveGlobalCtxDb: ({ engine, exec, ...rest }: CreateHyperdriveGlobalCtxDbOptions) => DatabaseWriterLike;
 /** Convenience: a **Postgres** `.global()` writer from a row-client (postgres.js/pg over Hyperdrive). */
 declare const createPostgresGlobalCtxDb: (client: RowClient, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
 /** Convenience: a **MySQL** `.global()` writer from a `mysql2/promise` connection/pool (created with `flags: ["FOUND_ROWS"]`). */

package/dist/global.mjs

@@ -1,9 +1 @@
-import { createSqlCtxDb } from '@lunora/sql-store';
-import { postgresDialect, mysqlDialect } from './packem_shared/mysqlDialect-oNhZ58s8.mjs';
-import { buildMysqlExec, buildPgExec } from './packem_shared/buildMysqlExec-DBbCjyq3.mjs';
-
-const createHyperdriveGlobalCtxDb = ({ engine, exec, ...rest }) => createSqlCtxDb({ ...rest, dialect: engine === "postgres" ? postgresDialect : mysqlDialect, exec });
-const createPostgresGlobalCtxDb = (client, options) => createHyperdriveGlobalCtxDb({ ...options, engine: "postgres", exec: buildPgExec(client) });
-const createMysqlGlobalCtxDb = (connection, options) => createHyperdriveGlobalCtxDb({ ...options, engine: "mysql", exec: buildMysqlExec(connection) });
-
-export { buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createMysqlGlobalCtxDb, createPostgresGlobalCtxDb, mysqlDialect, postgresDialect };
+import{createSqlCtxDb as l}from"@lunora/sql-store";import{postgresDialect as s,mysqlDialect as c}from"./packem_shared/mysqlDialect-DitNAlpV.mjs";import{buildMysqlExec as i,buildPgExec as a}from"./packem_shared/buildMysqlExec-DriYb1l9.mjs";const o=({engine:e,exec:t,...r})=>l({...r,dialect:e==="postgres"?s:c,exec:t}),p=(e,t)=>o({...t,engine:"postgres",exec:a(e)}),g=(e,t)=>o({...t,engine:"mysql",exec:i(e)});export{i as buildMysqlExec,a as buildPgExec,o as createHyperdriveGlobalCtxDb,g as createMysqlGlobalCtxDb,p as createPostgresGlobalCtxDb,c as mysqlDialect,s as postgresDialect};

package/dist/index.d.mts

@@ -1,165 +1,148 @@
+import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as SqlClient, N as NodePgLike, P as PostgresJsLike } from "./packem_shared/types.d-DE1NYxyA.mjs";
 /**
-* Public types for `@lunora/hyperdrive`.
-*
-* Hyperdrive points at a database **Lunora does not own**. Everything here is
-* deliberately structural (no hard dependency on `@cloudflare/workers-types` or
-* any SQL driver) so unit tests can pass plain-object doubles, exactly like the
-* `D1DatabaseLike` projection in `@lunora/d1`.
-*
-* The hard constraint, restated wherever this surface is used: Hyperdrive
-* queries are **non-deterministic** (forbidden in `query`/`mutation`, allowed
-* only in `action`s — see the `hyperdrive_outside_action` advisor lint), and
-* external writes are **invisible to Lunora live queries** — a subscription will
-* NOT re-run when an external Postgres/MySQL row changes.
-*/
-/**
-* Structural projection of the Cloudflare `Hyperdrive` binding (`env.HYPERDRIVE`).
-*
-* Mirrors the fields of the real `Hyperdrive` from `@cloudflare/workers-types`
-* but stays structural so a unit test can pass a plain object. At runtime only
-* `connectionString` is needed to construct a driver; the discrete connection
-* parts are surfaced for drivers that prefer a config object over a DSN.
-*/
-interface HyperdriveLike {
-  /** A connection string Hyperdrive routes through its pooled, cached edge connection. */
+ * Surface a Cloudflare Hyperdrive binding as a connection ready to feed a
+ * user-supplied SQL driver.
+ *
+ * `@lunora/hyperdrive` deliberately **bundles no driver** — `postgres`, `pg` and
+ * `mysql2` are heavy and the choice is the user's (they are `optional`
+ * `peerDependencies`, never `dependencies`). This factory's only job is to lift
+ * the binding's connection details out; the user constructs their own driver
+ * from `connectionString` and wraps it with one of the {@link fromPostgresJs} /
+ * {@link fromNodePg} / {@link fromMysql2} adapters to get a {@link SqlClient}.
+ * @example
+ * ```ts
+ * import { createHyperdrive, fromPostgresJs } from "@lunora/hyperdrive";
+ * import postgres from "postgres";
+ *
+ * // inside an action (never a query/mutation):
+ * const { connectionString } = createHyperdrive(env.HYPERDRIVE);
+ * ctx.sql = fromPostgresJs(postgres(connectionString));
+ * const rows = await ctx.sql.query("select id from users where org = $1", [orgId]);
+ * ```
+ * @remarks
+ * Hyperdrive talks to an **external** database Lunora has no visibility into.
+ * Queries through `ctx.sql` are non-deterministic (action-only — enforced by the
+ * `hyperdrive_outside_action` advisor lint) and external writes are NOT tracked
+ * by Lunora live queries: subscriptions will not re-run when external rows
+ * change. Use Hyperdrive to *integrate* an existing DB from an action; if you
+ * want that data to be reactive, write a projection of it into a `defineSchema`
+ * DO/D1 table.
+ * @param binding The `env.HYPERDRIVE` binding (or a structural double).
+ * @returns The raw `connectionString` plus the discrete connection parts.
+ */
+declare const createHyperdrive: (binding: HyperdriveLike) => {
+  config: HyperdriveConnection;
   connectionString: string;
-  /** Database name component of the connection. */
-  database: string;
-  /** Host Hyperdrive presents to the driver (the local proxy, not your origin DB). */
-  host: string;
-  /** Password component of the connection. */
-  password: string;
-  /** Port Hyperdrive presents to the driver. */
-  port: number;
-  /** User component of the connection. */
-  user: string;
-}
+};
 /**
-* The connection config surfaced by {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive}: the raw
-* `connectionString` plus the discrete parts, ready to hand to a driver.
-*/
-interface HyperdriveConnection {
-  /** Database name. */
-  database: string;
-  /** Host (Hyperdrive's local proxy). */
-  host: string;
-  /** Password. */
-  password: string;
-  /** Port. */
-  port: number;
-  /** User. */
-  user: string;
-}
+ * Wrap a `postgres` (postgres.js) client as a {@link SqlClient}.
+ *
+ * Uses the driver's `.unsafe(text, params)` escape hatch so the caller supplies
+ * a plain SQL string with `$1, $2, …` placeholders and a positional params
+ * array. postgres.js's `.unsafe` resolves to a row array.
+ */
+declare const fromPostgresJs: (client: PostgresJsLike) => SqlClient;
+/**
+ * Wrap a `pg` (node-postgres) `Client` or `Pool` as a {@link SqlClient}.
+ *
+ * node-postgres returns a result object whose `rows` field holds the row array.
+ */
+declare const fromNodePg: (client: NodePgLike) => SqlClient;
 /**
-* The driver-agnostic SQL surface bound to `ctx.sql` on **`ActionCtx` only**.
-*
-* This is the exact type the generated ctx imports as
-* `import("@lunora/hyperdrive").SqlClient`. Keep the name and shape stable — the
-* codegen ctx wiring (Phase 1) depends on it.
-*
-* It is intentionally minimal — a single parameterised `query` — so it maps onto
-* `postgres` (postgres.js), `pg` (node-postgres) and `mysql2` alike via the
-* {@link import("./create-hyperdrive").fromPostgresJs | fromPostgresJs} /
-* {@link import("./create-hyperdrive").fromNodePg | fromNodePg} /
-* {@link import("./create-hyperdrive").fromMysql2 | fromMysql2} adapters. Use
-* positional placeholders that match your driver (`$1, $2` for Postgres, `?` for
-* MySQL); the package does not rewrite SQL.
-*
-* Reminder (also on the emitted JSDoc): non-deterministic, action-only,
-* non-reactive — writes here are not tracked by Lunora live queries.
-*/
-interface SqlClient {
+ * Wrap a `mysql2/promise` connection or pool as a {@link SqlClient}.
+ *
+ * Use `?` placeholders (MySQL positional syntax). `mysql2`'s `execute` resolves
+ * to a `[rows, fields]` tuple; the adapter returns the first element. For a
+ * non-`SELECT` (DML), `mysql2` yields a `ResultSetHeader` object rather than a
+ * row array, so the adapter normalises that to `[]` — matching the empty-array
+ * contract the postgres.js / node-postgres adapters already honour.
+ */
+declare const fromMysql2: (connection: Mysql2Like) => SqlClient;
+/** How an external row maps to a Lunora document. */
+interface ProjectOptions {
+  /**
+   * Column whose value becomes the Lunora `_id` (stringified). Defaults to `"id"`.
+   * With no `map`, this column is dropped from the document body (it lives on as
+   * `_id`); with a `map`, the mapper owns the body and `_id` is added from here.
+   */
+  idColumn?: string;
   /**
-  * Run a parameterised SQL statement and return the result rows.
-  * @param text SQL text with driver-native positional placeholders.
-  * @param params Bound parameter values, positionally matched to `text`.
-  * @returns The rows the statement produced (empty for non-`SELECT`s that
-  * return no rows).
-  */
-  query: <Row = Record<string, unknown>>(text: string, params?: ReadonlyArray<unknown>) => Promise<Row[]>;
+   * Transform an external row into the stored document body. Omit for the default:
+   * every selected column except `idColumn` is copied verbatim. The returned object
+   * must not include `_id` — it is set from `idColumn`.
+   */
+  map?: (row: Record<string, unknown>) => Record<string, unknown>;
 }
-/**
-* Structural projection of a `pg` (node-postgres) `Client`/`Pool`. Only the
-* `query` method `fromNodePg` calls is required, kept structural for testing.
-*/
-interface NodePgLike {
-  query: (text: string, params?: ReadonlyArray<unknown>) => Promise<{
-    rows: unknown[];
-  }>;
+/** Options for {@link pullSourceRows}: the parameterised tenant query plus the row projection. */
+interface PullSourceOptions extends ProjectOptions {
+  /** Bound parameter values, positionally matched to `query` (the tenant scope binds here). */
+  params?: ReadonlyArray<unknown>;
+  /** The full tenant-membership query with driver-native placeholders (`$1` / `?`). */
+  query: string;
 }
 /**
-* Structural projection of a `postgres` (postgres.js) tagged-template client.
-* The adapter uses the `.unsafe(text, params)` escape hatch so callers keep
-* full control of the parameter list.
-*/
-interface PostgresJsLike {
-  unsafe: (text: string, params?: ReadonlyArray<unknown>) => Promise<unknown>;
-}
+ * Project one external row to a Lunora document: lift `idColumn` to a stringified
+ * `_id`, then either apply `map` or copy every other column verbatim. Throws when
+ * the id column is missing/nullish so a misconfigured query fails loudly rather than
+ * materializing rows under an `"undefined"` id.
+ *
+ * Delegates to `@lunora/shard-engine`'s `liftSourceId` — the single id-lift the declarative
+ * `.source()` poll loop also uses — so the manual bridge and the codegen path can
+ * never diverge in their missing-id handling.
+ */
+declare const projectSourceRow: (row: Record<string, unknown>, options?: ProjectOptions) => Record<string, unknown>;
 /**
-* Structural projection of a `mysql2/promise` connection/pool. `mysql2`'s
-* `execute` resolves to a `[rows, fields]` tuple; the adapter takes the first
-* element as the rows.
-*/
-interface Mysql2Like {
-  execute: (text: string, params?: ReadonlyArray<unknown>) => Promise<[unknown, unknown]>;
-}
+ * Run a parameterised tenant query against Hyperdrive and project every row to a
+ * Lunora document ready to hand to `materializeExternalRows`. Call this inside an
+ * **action** (where `ctx.sql` lives); pass the result to a mutation for the write.
+ */
+declare const pullSourceRows: (sql: SqlClient, options: PullSourceOptions) => Promise<Record<string, unknown>[]>;
+export { type HyperdriveConnection, type HyperdriveLike, type Mysql2Like, type NodePgLike, type PostgresJsLike, type ProjectOptions, type PullSourceOptions, type SqlClient,
 /**
-* Surface a Cloudflare Hyperdrive binding as a connection ready to feed a
-* user-supplied SQL driver.
-*
-* `@lunora/hyperdrive` deliberately **bundles no driver** — `postgres`, `pg` and
-* `mysql2` are heavy and the choice is the user's (they are `optional`
-* `peerDependencies`, never `dependencies`). This factory's only job is to lift
-* the binding's connection details out; the user constructs their own driver
-* from `connectionString` and wraps it with one of the {@link fromPostgresJs} /
-* {@link fromNodePg} / {@link fromMysql2} adapters to get a {@link SqlClient}.
-* @example
-* ```ts
-* import { createHyperdrive, fromPostgresJs } from "@lunora/hyperdrive";
-* import postgres from "postgres";
-*
-* // inside an action (never a query/mutation):
-* const { connectionString } = createHyperdrive(env.HYPERDRIVE);
-* ctx.sql = fromPostgresJs(postgres(connectionString));
-* const rows = await ctx.sql.query("select id from users where org = $1", [orgId]);
-* ```
-* @remarks
-* Hyperdrive talks to an **external** database Lunora has no visibility into.
-* Queries through `ctx.sql` are non-deterministic (action-only — enforced by the
-* `hyperdrive_outside_action` advisor lint) and external writes are NOT tracked
-* by Lunora live queries: subscriptions will not re-run when external rows
-* change. Use Hyperdrive to *integrate* an existing DB from an action; if you
-* want that data to be reactive, write a projection of it into a `defineSchema`
-* DO/D1 table.
-* @param binding The `env.HYPERDRIVE` binding (or a structural double).
-* @returns The raw `connectionString` plus the discrete connection parts.
-*/
-declare const createHyperdrive: (binding: HyperdriveLike) => {
-  config: HyperdriveConnection;
-  connectionString: string;
-};
+ * `@lunora/hyperdrive` — bring-your-own Postgres/MySQL for Lunora via Cloudflare
+ * Hyperdrive.
+ *
+ * Surfaces a Hyperdrive binding's connection string and a driver-agnostic
+ * {@link import("./types").SqlClient | SqlClient} bound to `ctx.sql` on
+ * **`ActionCtx` only**. External SQL is non-deterministic (action-only) and
+ * non-reactive (live queries do not track external writes) — integrate an
+ * existing DB, do not replace the Lunora data layer. See the README and
+ * {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive} JSDoc.
+ */
+createHyperdrive,
 /**
-* Wrap a `postgres` (postgres.js) client as a {@link SqlClient}.
-*
-* Uses the driver's `.unsafe(text, params)` escape hatch so the caller supplies
-* a plain SQL string with `$1, $2, …` placeholders and a positional params
-* array. postgres.js's `.unsafe` resolves to a row array.
-*/
-declare const fromPostgresJs: (client: PostgresJsLike) => SqlClient;
+ * `@lunora/hyperdrive` — bring-your-own Postgres/MySQL for Lunora via Cloudflare
+ * Hyperdrive.
+ *
+ * Surfaces a Hyperdrive binding's connection string and a driver-agnostic
+ * {@link import("./types").SqlClient | SqlClient} bound to `ctx.sql` on
+ * **`ActionCtx` only**. External SQL is non-deterministic (action-only) and
+ * non-reactive (live queries do not track external writes) — integrate an
+ * existing DB, do not replace the Lunora data layer. See the README and
+ * {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive} JSDoc.
+ */
+fromMysql2,
 /**
-* Wrap a `pg` (node-postgres) `Client` or `Pool` as a {@link SqlClient}.
-*
-* node-postgres returns a result object whose `rows` field holds the row array.
-*/
-declare const fromNodePg: (client: NodePgLike) => SqlClient;
+ * `@lunora/hyperdrive` — bring-your-own Postgres/MySQL for Lunora via Cloudflare
+ * Hyperdrive.
+ *
+ * Surfaces a Hyperdrive binding's connection string and a driver-agnostic
+ * {@link import("./types").SqlClient | SqlClient} bound to `ctx.sql` on
+ * **`ActionCtx` only**. External SQL is non-deterministic (action-only) and
+ * non-reactive (live queries do not track external writes) — integrate an
+ * existing DB, do not replace the Lunora data layer. See the README and
+ * {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive} JSDoc.
+ */
+fromNodePg,
 /**
-* Wrap a `mysql2/promise` connection or pool as a {@link SqlClient}.
-*
-* Use `?` placeholders (MySQL positional syntax). `mysql2`'s `execute` resolves
-* to a `[rows, fields]` tuple; the adapter returns the first element. For a
-* non-`SELECT` (DML), `mysql2` yields a `ResultSetHeader` object rather than a
-* row array, so the adapter normalises that to `[]` — matching the empty-array
-* contract the postgres.js / node-postgres adapters already honour.
-*/
-declare const fromMysql2: (connection: Mysql2Like) => SqlClient;
-export { type HyperdriveConnection, type HyperdriveLike, type Mysql2Like, type NodePgLike, type PostgresJsLike, type SqlClient, createHyperdrive, fromMysql2, fromNodePg, fromPostgresJs };
+ * `@lunora/hyperdrive` — bring-your-own Postgres/MySQL for Lunora via Cloudflare
+ * Hyperdrive.
+ *
+ * Surfaces a Hyperdrive binding's connection string and a driver-agnostic
+ * {@link import("./types").SqlClient | SqlClient} bound to `ctx.sql` on
+ * **`ActionCtx` only**. External SQL is non-deterministic (action-only) and
+ * non-reactive (live queries do not track external writes) — integrate an
+ * existing DB, do not replace the Lunora data layer. See the README and
+ * {@link import("./create-hyperdrive").createHyperdrive | createHyperdrive} JSDoc.
+ */
+fromPostgresJs, projectSourceRow, pullSourceRows };