@lunora/hyperdrive 1.0.0-alpha.3 → 1.0.0-alpha.30

package/dist/global.d.mts

@@ -1,13 +1,18 @@
 import { DatabaseWriterLike } from '@lunora/do';
 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-C6SU6Aw3.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

package/dist/global.d.ts

@@ -1,13 +1,18 @@
 import { DatabaseWriterLike } from '@lunora/do';
 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-C6SU6Aw3.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

package/dist/global.mjs

@@ -1,6 +1,6 @@
 import { createSqlCtxDb } from '@lunora/sql-store';
-import { postgresDialect, mysqlDialect } from './packem_shared/postgresDialect-oNhZ58s8.mjs';
-import { buildMysqlExec, buildPgExec } from './packem_shared/buildPgExec-DBbCjyq3.mjs';
+import { postgresDialect, mysqlDialect } from './packem_shared/mysqlDialect-BHz03Grz.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) });

package/dist/index.d.mts

@@ -1,108 +1,4 @@
-/**
-* 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. */
-  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;
-}
-/**
-* 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 {
-  /**
-  * 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[]>;
-}
-/**
-* 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[];
-  }>;
-}
-/**
-* 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>;
-}
-/**
-* 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]>;
-}
+import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as SqlClient, N as NodePgLike, P as PostgresJsLike } from "./packem_shared/types.d-C6SU6Aw3.mjs";
 /**
 * Surface a Cloudflare Hyperdrive binding as a connection ready to feed a
 * user-supplied SQL driver.
@@ -162,4 +58,43 @@ declare const fromNodePg: (client: NodePgLike) => SqlClient;
 * 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 };
+/** 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;
+  /**
+  * 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>;
+}
+/** 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;
+}
+/**
+* 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/do`'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>;
+/**
+* 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, createHyperdrive, fromMysql2, fromNodePg, fromPostgresJs, projectSourceRow, pullSourceRows };

package/dist/index.d.ts

@@ -1,108 +1,4 @@
-/**
-* 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. */
-  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;
-}
-/**
-* 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 {
-  /**
-  * 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[]>;
-}
-/**
-* 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[];
-  }>;
-}
-/**
-* 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>;
-}
-/**
-* 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]>;
-}
+import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as SqlClient, N as NodePgLike, P as PostgresJsLike } from "./packem_shared/types.d-C6SU6Aw3.js";
 /**
 * Surface a Cloudflare Hyperdrive binding as a connection ready to feed a
 * user-supplied SQL driver.
@@ -162,4 +58,43 @@ declare const fromNodePg: (client: NodePgLike) => SqlClient;
 * 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 };
+/** 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;
+  /**
+  * 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>;
+}
+/** 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;
+}
+/**
+* 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/do`'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>;
+/**
+* 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, createHyperdrive, fromMysql2, fromNodePg, fromPostgresJs, projectSourceRow, pullSourceRows };

package/dist/index.mjs

@@ -1 +1,2 @@
 export { createHyperdrive, fromMysql2, fromNodePg, fromPostgresJs } from './packem_shared/createHyperdrive-DD8GoDZo.mjs';
+export { projectSourceRow, pullSourceRows } from './packem_shared/projectSourceRow-DtKuMRIm.mjs';

package/dist/packem_shared/{postgresDialect-oNhZ58s8.mjs → mysqlDialect-BHz03Grz.mjs}

@@ -67,7 +67,12 @@ const postgresDialect = {
   },
   name: "postgres",
   supportsReturning: true,
-  tableExists: (table) => sql`SELECT table_name FROM information_schema.tables WHERE table_name = ${table}`
+  // Restrict to schemas on the effective search_path (excluding the implicit
+  // pg_catalog with `false`) so an unqualified name resolves exactly as CREATE
+  // TABLE / SELECT would. Without this filter the probe sees same-named tables in
+  // OTHER schemas of the same database (a common multi-tenant/multi-env Hyperdrive
+  // setup), reporting a companion table that does not exist on the search_path.
+  tableExists: (table) => sql`SELECT table_name FROM information_schema.tables WHERE table_schema = ANY (current_schemas(false)) AND table_name = ${table}`
 };
 const mysqlDialect = {
   affectedRows: (result) => result.rowsAffected,
@@ -88,8 +93,13 @@ const mysqlDialect = {
     { name: "id", type: "VARCHAR(768) PRIMARY KEY" },
     { name: "_creationTime", type: "DOUBLE NOT NULL" }
   ],
-  // InnoDB can't index a TEXT/LONGTEXT/BLOB column without a key prefix; bound it to 768 chars.
-  indexKeyPrefix: (kind) => MYSQL_PREFIX_INDEX_RE.test(mysqlColumnType(kind)) ? 768 : void 0,
+  // InnoDB can't index a TEXT/LONGTEXT/BLOB column without a key prefix. Bound it
+  // to 191 chars (191 × 4 = 764 bytes under utf8mb4), matching the rank-companion
+  // convention: a flat 768-char prefix is 3072 bytes — exactly InnoDB's whole-index
+  // key limit — so ANY composite index containing a string field (e.g.
+  // `.index("by_project", ["projectId", "seq"])`) would exceed 3072 and fail CREATE
+  // INDEX with ER_TOO_LONG_KEY. 191 leaves room for several columns under the cap.
+  indexKeyPrefix: (kind) => MYSQL_PREFIX_INDEX_RE.test(mysqlColumnType(kind)) ? 191 : void 0,
   isUniqueViolation: (error) => {
     const candidate = error;
     return candidate.errno === 1062 || candidate.code === "ER_DUP_ENTRY";

package/dist/packem_shared/projectSourceRow-DtKuMRIm.mjs

@@ -0,0 +1,10 @@
+import { liftSourceId } from '@lunora/do';
+
+const projectSourceRow = (row, options = {}) => liftSourceId(row, options);
+const pullSourceRows = async (sql, options) => {
+  const { idColumn, map, params, query } = options;
+  const rows = await sql.query(query, params);
+  return rows.map((row) => projectSourceRow(row, { idColumn, map }));
+};
+
+export { projectSourceRow, pullSourceRows };

package/dist/packem_shared/types.d-C6SU6Aw3.d.mts

@@ -0,0 +1,113 @@
+/**
+* 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. */
+  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;
+}
+/**
+* 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 {
+  /**
+  * Run a parameterised SQL statement and return the result rows.
+  *
+  * SECURITY: `text` is executed verbatim — the package never rewrites or
+  * escapes it. NEVER interpolate untrusted/user input into `text`; put every
+  * value in `params` and reference it with a positional placeholder (`$1`/`?`).
+  * Building `text` by string-concatenating request data is a SQL-injection
+  * sink against your own Postgres/MySQL. Identifiers (table/column names) can't
+  * be parameterised — allowlist them against a fixed set, don't interpolate.
+  * @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[]>;
+}
+/**
+* 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[];
+  }>;
+}
+/**
+* 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>;
+}
+/**
+* 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]>;
+}
+export { HyperdriveLike as H, Mysql2Like as M, NodePgLike as N, PostgresJsLike as P, SqlClient as S, HyperdriveConnection as a };

package/dist/packem_shared/types.d-C6SU6Aw3.d.ts

@@ -0,0 +1,113 @@
+/**
+* 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. */
+  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;
+}
+/**
+* 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 {
+  /**
+  * Run a parameterised SQL statement and return the result rows.
+  *
+  * SECURITY: `text` is executed verbatim — the package never rewrites or
+  * escapes it. NEVER interpolate untrusted/user input into `text`; put every
+  * value in `params` and reference it with a positional placeholder (`$1`/`?`).
+  * Building `text` by string-concatenating request data is a SQL-injection
+  * sink against your own Postgres/MySQL. Identifiers (table/column names) can't
+  * be parameterised — allowlist them against a fixed set, don't interpolate.
+  * @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[]>;
+}
+/**
+* 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[];
+  }>;
+}
+/**
+* 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>;
+}
+/**
+* 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]>;
+}
+export { HyperdriveLike as H, Mysql2Like as M, NodePgLike as N, PostgresJsLike as P, SqlClient as S, HyperdriveConnection as a };