@lunora/hyperdrive 1.0.0-alpha.21 → 1.0.0-alpha.211

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/README.md

@@ -42,7 +42,7 @@ Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-sa
 >
 > Hyperdrive talks to a database **Lunora does not own**. That breaks two invariants the rest of Lunora relies on:
 >
-> 1. **Non-deterministic (action-only).** A SQL query over Hyperdrive is a network call with an external, mutable result — exactly like `fetch`. It is **forbidden in `query`/`mutation`** (which must be deterministic so the coordinator can re-run them on OCC retry / subscription re-evaluation) and allowed **only in `action`s**. The `hyperdrive_outside_action` advisor lint flags `ctx.sql` used in a query/mutation.
+> 1. **Non-deterministic (action-only).** A SQL query over Hyperdrive is a network call with an external, mutable result — exactly like `fetch`. It is **forbidden in `query`/`mutation`** (which must be deterministic so the coordinator can re-run them on subscription re-evaluation; an OCC conflict surfaces as a `409` to the caller, not an internal retry) and allowed **only in `action`s**. The `hyperdrive_outside_action` advisor lint flags `ctx.sql` used in a query/mutation.
 > 2. **Non-reactive.** External writes do **not** flow through the Durable-Object / SQLite change-feed, so **Lunora live queries and subscriptions will NOT re-run** when an external Postgres/MySQL row changes. There is no honest way to make external writes reactive here.
 >
 > Use Hyperdrive to _read/write your existing DB from an action_. It is the **wrong** tool for "make my Postgres reactive". If you want external data to be reactive, write a **projection** of it into a `defineSchema` DO/D1 table from the action — that write _is_ tracked.
@@ -67,35 +67,55 @@ pnpm add mysql2     # mysql2        → fromMysql2
 
 ## Setup
 
-1. Create the Hyperdrive config and mint its id (Lunora can't fabricate the remote id):
+Importing `@lunora/hyperdrive` (or reading `ctx.sql`) is enough: `lunora dev` and `lunora deploy` add a `HYPERDRIVE` binding to `wrangler.jsonc` for you, with a placeholder `id`.
+
+- **In dev**, `ctx.sql` runs against an embedded Postgres ([PGlite](https://pglite.dev)) with its data in `.wrangler/state/lunora-pglite`, under `lunora dev`, `vite dev` and `vite preview`. It needs two optional packages (`lunora dev` says so when they are missing):
 
     ```sh
-    wrangler hyperdrive create my-db --connection-string="postgres://user:pass@host:5432/db" # gitleaks:allow -- placeholder, not a real secret
+    pnpm add -D @electric-sql/pglite @electric-sql/pglite-socket
     ```
 
-2. Add the binding to `wrangler.jsonc` (use `localConnectionString` for local dev):
+    To use your own database, set `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE` (the last part is the binding name) or `localConnectionString` on the binding. The embedded database speaks PostgreSQL: a project whose only SQL driver is `mysql2` gets a warning and must set that variable to a local MySQL of its own. A plain `wrangler dev` that Lunora does not start has no embedded database either: set the variable (or `localConnectionString`) there too.
+
+- **On deploy**, set the origin's connection string and a token that may edit Hyperdrive (`CLOUDFLARE_API_TOKEN` with _Hyperdrive: Edit_, plus `CLOUDFLARE_ACCOUNT_ID`):
 
-    ```jsonc
-    {
-        "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<id from step 1>", "localConnectionString": "postgres://user:pass@localhost:5432/db" }], // gitleaks:allow -- placeholder, not a real secret
-    }
+    ```sh
+    LUNORA_HYPERDRIVE_URL="postgres://user:pass@host:5432/db" lunora deploy # gitleaks:allow -- placeholder, not a real secret
     ```
 
+    The variable is `LUNORA_<BINDING>_URL`. Lunora creates a config named after the deployed Worker (so `--env staging` gets its own) and the binding, or reuses one with that name that reaches the same database, and writes its `id` into `wrangler.jsonc`. A same-named config for another database stops the deploy. The connection string is only sent to Cloudflare, never written to a file or logged.
+
+Prefer to manage it yourself? Run `wrangler hyperdrive create my-db --connection-string=...` and put the `id` in the binding; Lunora then leaves it alone.
+
 ## Usage
 
-`ctx.sql` is wired by codegen onto `ActionCtx` only — never `QueryCtx`/`MutationCtx`. The procedure builders (`action`, `v`) and `api` come from your app-local generated modules:
+`ctx.sql` is wired by codegen onto `ActionCtx` only — never `QueryCtx`/`MutationCtx`, and it is `readonly`, so it is built once at the app level rather than assigned in a handler. Codegen emits a `sql` config thunk for it (`createHyperdrive` returns connection info; only you know which driver wraps it):
 
 ```ts
+// src/server/index.ts
+import type { HyperdriveLike } from "@lunora/hyperdrive";
 import { createHyperdrive, fromPostgresJs } from "@lunora/hyperdrive";
 import postgres from "postgres";
 
+import { defineApp } from "../../lunora/_generated/app";
+
+const app = defineApp<Env>()
+    .shard((env) => env.SHARD)
+    .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE as HyperdriveLike).connectionString)))
+    .build();
+
+export const ShardDO = app.ShardDO;
+```
+
+Hand-composing the worker instead? The same thunk is `createShardDO({ sql: (env) => … })`. Without it, every `ctx.sql` method throws a message pointing back at this wiring.
+
+Handlers then just read it. The procedure builders (`action`, `v`) and `api` come from your app-local generated modules:
+
+```ts
 import { api } from "@/lunora/_generated/api";
 import { action, v } from "@/lunora/_generated/server";
 
 export const syncCustomer = action.input({ orgId: v.string() }).action(async ({ args: { orgId }, ctx }) => {
-    const { connectionString } = createHyperdrive(ctx.env.HYPERDRIVE);
-    ctx.sql = fromPostgresJs(postgres(connectionString));
-
     const rows = await ctx.sql.query<{ id: string; name: string }>("select id, name from customers where org = $1", [orgId]);
 
     // Want it reactive? Project it into a Lunora table — THIS write is tracked.
@@ -113,6 +133,44 @@ export const syncCustomer = action.input({ orgId: v.string() }).action(async ({
 | `pg` (node-postgres)     | `fromNodePg`     | `$1, $2, …`  |
 | `mysql2/promise`         | `fromMysql2`     | `?`          |
 
+## Reactive reads over your schema: the `.source()` modifier
+
+The projection above is the escape hatch. For the common case — an existing Postgres you are not going to move, and a read path that should feel live — declare the source on the table and Lunora runs the whole loop on the shard's alarm: pull, diff, materialize, poke subscribers. No action, no mutation, no cron to write:
+
+```ts
+// lunora/schema.ts
+export default defineSchema({
+    messages: defineTable({ body: v.string(), channelId: v.string() })
+        .shardBy("channelId")
+        .source({
+            binding: "HYPERDRIVE_MESSAGES",
+            query: 'select id, body, channel_id as "channelId" from messages where channel_id = $1',
+            tenantBy: (shardKey) => [shardKey], // mandatory under .shardBy() — the tenant boundary
+        }),
+});
+
+export const channelMessages = defineShape({ table: "messages", where: () => ({}) });
+```
+
+Supply the driver once, on the app builder — required, or every tick records `no sourceClient resolved for binding "…"` and the table stays empty. Lunora memoizes it per binding:
+
+```ts
+export default defineApp<Env>()
+    .shard((env) => env.SHARD)
+    .sourceClient((env, binding) => fromPostgresJs(postgres((env[binding] as { connectionString: string }).connectionString)))
+    .build();
+```
+
+Clients subscribe with the shape they would use over any table — external data stops being external once it is materialized.
+
+Three things to know before you build on it:
+
+- **It polls; it is not logical replication.** Freshness is the refresh cadence: every alarm tick by default, `refresh: { everyMs }` to throttle, `refresh: "manual"` to drive it yourself. Writes from other systems land on the next pull.
+- **`tenantBy` is the isolation boundary.** `defineSchema` throws at load if a sourced `.shardBy()` table omits it, and the `external_source_unscoped` advisor lint catches it at build time. Without it, one tenant's DO pulls every tenant's rows.
+- **`mode: "full-pull"` (the default) diffs the whole slice each tick**, so upstream deletes are detected for free, at a bench ceiling around 10k rows. Past that, `mode: "incremental"` pulls only rows past a durable watermark via a cursor column. An incremental slice cannot see a delete on its own — an absent row means "unchanged", not "deleted" — so it **requires** a delete-visibility path: either `reconcileEveryMs` (a periodic full-pull sweep) or `softDeleteColumn` (an upstream tombstone column the cursor query returns, so do not filter it out). `defineSchema` throws and the `external_source_incremental_no_delete_path` lint fails the build if an incremental source declares neither.
+
+`.source()` cannot be combined with `.global()` — they are contradictory tiers, and `defineSchema` rejects it.
+
 ## Reactive `.global()` over Hyperdrive
 
 The `@lunora/hyperdrive/global` subpath is the opposite trade-off: Lunora **owns** the schema and a `.global()` table gets a real column-per-field layout on your Postgres/MySQL, with every write routed through the shared store core. Live queries stay reactive — identical to D1 — because the writer drives the same broadcast hook. Build the writer inside the Durable Object that hosts the `.global()` store and inject it as `globalDb`:
@@ -127,7 +185,7 @@ const globalDb = createPostgresGlobalCtxDb({ query: (text, params) => sql.unsafe
 
 For MySQL use `createMysqlGlobalCtxDb` with a `mysql2/promise` pool created with `flags: ["FOUND_ROWS"]` — without `CLIENT_FOUND_ROWS` the affected-rows OCC guard sees changed (not matched) rows and raises spurious conflicts. Lower-level building blocks (`buildPgExec`, `buildMysqlExec`, `postgresDialect`, `mysqlDialect`, `createHyperdriveGlobalCtxDb`) are exported for custom wiring.
 
-> This README covers the basics. For the full API and the determinism/realtime rationale, see the **[documentation](https://lunora.sh/docs/addons/hyperdrive)**.
+> This README covers the basics. For the full API and the determinism/realtime rationale, see the **[documentation](https://lunora.sh/docs/packages/hyperdrive)**.
 
 ## Non-goals
 

package/dist/global.d.mts

@@ -1,47 +1,160 @@
-import { DatabaseWriterLike } from '@lunora/do';
+/**
+ * `@lunora/hyperdrive/global` — a Postgres/MySQL database reached through
+ * Cloudflare Hyperdrive (PlanetScale, Neon, RDS, …) as a **first-class,
+ * reactive** `.global()` storage backend for Lunora, alongside D1.
+ *
+ * Unlike the package's `ctx.sql` surface (an action-only, non-reactive escape
+ * hatch for an external DB), this makes Lunora the **owner** of the schema:
+ * `.global()` tables get a real column-per-field layout and all writes route
+ * through the shared store core (`createSqlCtxDb` from `@lunora/sql-store`) with
+ * a Postgres or MySQL {@link postgresDialect}/{@link mysqlDialect} and a
+ * Hyperdrive-backed {@link SqlExec}. The returned `DatabaseWriterLike` is
+ * injected as `globalDb` into `createShardCtxDb`, whose broadcast hook drives
+ * live queries — so subscriptions stay reactive with zero extra wiring,
+ * identical to D1.
+ *
+ * Drivers (`postgres`/`pg`/`mysql2`) are optional peer deps — bring your own,
+ * constructed from the `HYPERDRIVE` binding's connection string. The binding is
+ * reachable from inside the Durable Object that hosts the writer; cache the
+ * driver on the DO instance and rebuild it lazily after hibernation.
+ *
+ * **MySQL connections must enable `CLIENT_FOUND_ROWS`** (mysql2:
+ * `createPool({ flags: ["FOUND_ROWS"] })`) so the affected-rows OCC guard sees
+ * matched (not changed) rows — see {@link buildMysqlExec}.
+ */
+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-B2JdXSms.mjs";
+import { VectorMetric, VectorizeIndexLike } from '@lunora/platform';
+/**
+ * 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;
 /**
-* 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.
-*/
+ * 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, widened with the
+ * (optional, structural) shape {@link assertFoundRows}'s `CLIENT_FOUND_ROWS`
+ * probe reads.
+ *
+ * A real `mysql2/promise` connection/pool exposes the merged client-flags
+ * bitmask synchronously, but at two different depths depending on which one it
+ * is, and NEITHER is in `mysql2`'s own `.d.ts` — its `Pool extends Connection`
+ * signature claims a top-level `config`, but at runtime a `mysql2/promise`
+ * `Pool` has none; the real value lives one level down, on the core pool it
+ * wraps:
+ *
+ * - a single `Connection`/`PoolConnection` → `connection.config.clientFlags`
+ * - a `Pool` (the `createPool({ flags: ["FOUND_ROWS"] })` example above) →
+ * `pool.pool.config.connectionConfig.clientFlags`
+ *
+ * Because those paths are undocumented driver internals, `global-dialect.test.ts`
+ * pins them against a REAL `mysql2` pool (built without connecting) rather than
+ * only against hand-written doubles — if a `mysql2` release relocates them, the
+ * probe would otherwise degrade silently to the warn branch and the OCC guard
+ * would go unchecked.
+ *
+ * The probe fields are typed `unknown` publicly: the paths are not in `mysql2`'s
+ * typings, so spelling them out made a real `createPool(...)` fail to type-check
+ * (TS2345, weak-type mismatch on `config`). {@link readMysqlClientFlags} reads
+ * them through the internal `FlagProbeShape` instead, and a minimal test double
+ * (only `execute`) resolves to "undeterminable" rather than a `TypeError`.
+ */
+type Mysql2Execute = Mysql2Like & {
+  config?: unknown;
+  pool?: unknown;
+};
+/**
+ * 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. Verified
+ * once here at construction — see {@link assertFoundRows} — never per statement.
+ *
+ * `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;
+/** Options for {@link createPgVectorIndex}. */
+interface PgVectorIndexOptions {
+  /** Postgres client — the same `SqlClient` the Hyperdrive global store takes. */
+  client: SqlClient;
+  /**
+   * Vector width. Must match the embedder's output and the `dimensions` on the
+   * schema's `.vectorize(...)`; Postgres enforces it per row, so a mismatch
+   * surfaces as a write error rather than silently bad neighbours.
+   */
+  dimensions: number;
+  /** Distance metric. Defaults to `"cosine"`, matching the common embedding case. */
+  metric?: VectorMetric;
+  /**
+   * Names the backing table (`__vec_<name>`), derived rather than configurable —
+   * a second name for one index is a way to lose data, not a feature.
+   *
+   * This is NOT required to equal the key in the shard's `vectors` map, and often
+   * cannot: that key mirrors the schema's `.vectorize({ index })`, which may carry
+   * hyphens (`"docs-body"`), while this must be a bare SQL identifier. Keep it
+   * stable — changing it points the index at a different, empty table.
+   */
+  name: string;
+}
+/**
+ * Build a `pgvector`-backed vector index that satisfies {@link VectorizeIndexLike}.
+ *
+ * Requires the `vector` extension to be installable by the connecting role
+ * (`CREATE EXTENSION IF NOT EXISTS vector`). On a managed Postgres where the
+ * role cannot create extensions, install it once out-of-band; the statement is
+ * then a no-op.
+ * @param options See {@link PgVectorIndexOptions}.
+ * @returns An index object the shard's `vectors` map accepts as-is.
+ */
+declare const createPgVectorIndex: (options: PgVectorIndexOptions) => VectorizeIndexLike;
 /** Which engine a Hyperdrive-backed `.global()` store targets. */
 type HyperdriveEngine = "mysql" | "postgres";
 /** Options for {@link createHyperdriveGlobalCtxDb}: the store options minus `exec`/`dialect`, plus the engine and a built `SqlExec`. */
@@ -52,18 +165,14 @@ 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"]`). */
 declare const createMysqlGlobalCtxDb: (connection: Mysql2Execute, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
-export { CreateHyperdriveGlobalCtxDbOptions, HyperdriveEngine, type Mysql2Execute, type RowClient, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createMysqlGlobalCtxDb, createPostgresGlobalCtxDb, mysqlDialect, postgresDialect };
+export { CreateHyperdriveGlobalCtxDbOptions, HyperdriveEngine, type Mysql2Execute, type PgVectorIndexOptions, type RowClient, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createMysqlGlobalCtxDb, createPgVectorIndex, createPostgresGlobalCtxDb, mysqlDialect, postgresDialect };

package/dist/global.d.ts

@@ -1,47 +1,160 @@
-import { DatabaseWriterLike } from '@lunora/do';
+/**
+ * `@lunora/hyperdrive/global` — a Postgres/MySQL database reached through
+ * Cloudflare Hyperdrive (PlanetScale, Neon, RDS, …) as a **first-class,
+ * reactive** `.global()` storage backend for Lunora, alongside D1.
+ *
+ * Unlike the package's `ctx.sql` surface (an action-only, non-reactive escape
+ * hatch for an external DB), this makes Lunora the **owner** of the schema:
+ * `.global()` tables get a real column-per-field layout and all writes route
+ * through the shared store core (`createSqlCtxDb` from `@lunora/sql-store`) with
+ * a Postgres or MySQL {@link postgresDialect}/{@link mysqlDialect} and a
+ * Hyperdrive-backed {@link SqlExec}. The returned `DatabaseWriterLike` is
+ * injected as `globalDb` into `createShardCtxDb`, whose broadcast hook drives
+ * live queries — so subscriptions stay reactive with zero extra wiring,
+ * identical to D1.
+ *
+ * Drivers (`postgres`/`pg`/`mysql2`) are optional peer deps — bring your own,
+ * constructed from the `HYPERDRIVE` binding's connection string. The binding is
+ * reachable from inside the Durable Object that hosts the writer; cache the
+ * driver on the DO instance and rebuild it lazily after hibernation.
+ *
+ * **MySQL connections must enable `CLIENT_FOUND_ROWS`** (mysql2:
+ * `createPool({ flags: ["FOUND_ROWS"] })`) so the affected-rows OCC guard sees
+ * matched (not changed) rows — see {@link buildMysqlExec}.
+ */
+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-B2JdXSms.js";
+import { VectorMetric, VectorizeIndexLike } from '@lunora/platform';
+/**
+ * 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;
 /**
-* 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.
-*/
+ * 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, widened with the
+ * (optional, structural) shape {@link assertFoundRows}'s `CLIENT_FOUND_ROWS`
+ * probe reads.
+ *
+ * A real `mysql2/promise` connection/pool exposes the merged client-flags
+ * bitmask synchronously, but at two different depths depending on which one it
+ * is, and NEITHER is in `mysql2`'s own `.d.ts` — its `Pool extends Connection`
+ * signature claims a top-level `config`, but at runtime a `mysql2/promise`
+ * `Pool` has none; the real value lives one level down, on the core pool it
+ * wraps:
+ *
+ * - a single `Connection`/`PoolConnection` → `connection.config.clientFlags`
+ * - a `Pool` (the `createPool({ flags: ["FOUND_ROWS"] })` example above) →
+ * `pool.pool.config.connectionConfig.clientFlags`
+ *
+ * Because those paths are undocumented driver internals, `global-dialect.test.ts`
+ * pins them against a REAL `mysql2` pool (built without connecting) rather than
+ * only against hand-written doubles — if a `mysql2` release relocates them, the
+ * probe would otherwise degrade silently to the warn branch and the OCC guard
+ * would go unchecked.
+ *
+ * The probe fields are typed `unknown` publicly: the paths are not in `mysql2`'s
+ * typings, so spelling them out made a real `createPool(...)` fail to type-check
+ * (TS2345, weak-type mismatch on `config`). {@link readMysqlClientFlags} reads
+ * them through the internal `FlagProbeShape` instead, and a minimal test double
+ * (only `execute`) resolves to "undeterminable" rather than a `TypeError`.
+ */
+type Mysql2Execute = Mysql2Like & {
+  config?: unknown;
+  pool?: unknown;
+};
+/**
+ * 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. Verified
+ * once here at construction — see {@link assertFoundRows} — never per statement.
+ *
+ * `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;
+/** Options for {@link createPgVectorIndex}. */
+interface PgVectorIndexOptions {
+  /** Postgres client — the same `SqlClient` the Hyperdrive global store takes. */
+  client: SqlClient;
+  /**
+   * Vector width. Must match the embedder's output and the `dimensions` on the
+   * schema's `.vectorize(...)`; Postgres enforces it per row, so a mismatch
+   * surfaces as a write error rather than silently bad neighbours.
+   */
+  dimensions: number;
+  /** Distance metric. Defaults to `"cosine"`, matching the common embedding case. */
+  metric?: VectorMetric;
+  /**
+   * Names the backing table (`__vec_<name>`), derived rather than configurable —
+   * a second name for one index is a way to lose data, not a feature.
+   *
+   * This is NOT required to equal the key in the shard's `vectors` map, and often
+   * cannot: that key mirrors the schema's `.vectorize({ index })`, which may carry
+   * hyphens (`"docs-body"`), while this must be a bare SQL identifier. Keep it
+   * stable — changing it points the index at a different, empty table.
+   */
+  name: string;
+}
+/**
+ * Build a `pgvector`-backed vector index that satisfies {@link VectorizeIndexLike}.
+ *
+ * Requires the `vector` extension to be installable by the connecting role
+ * (`CREATE EXTENSION IF NOT EXISTS vector`). On a managed Postgres where the
+ * role cannot create extensions, install it once out-of-band; the statement is
+ * then a no-op.
+ * @param options See {@link PgVectorIndexOptions}.
+ * @returns An index object the shard's `vectors` map accepts as-is.
+ */
+declare const createPgVectorIndex: (options: PgVectorIndexOptions) => VectorizeIndexLike;
 /** Which engine a Hyperdrive-backed `.global()` store targets. */
 type HyperdriveEngine = "mysql" | "postgres";
 /** Options for {@link createHyperdriveGlobalCtxDb}: the store options minus `exec`/`dialect`, plus the engine and a built `SqlExec`. */
@@ -52,18 +165,14 @@ 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"]`). */
 declare const createMysqlGlobalCtxDb: (connection: Mysql2Execute, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
-export { CreateHyperdriveGlobalCtxDbOptions, HyperdriveEngine, type Mysql2Execute, type RowClient, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createMysqlGlobalCtxDb, createPostgresGlobalCtxDb, mysqlDialect, postgresDialect };
+export { CreateHyperdriveGlobalCtxDbOptions, HyperdriveEngine, type Mysql2Execute, type PgVectorIndexOptions, type RowClient, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createMysqlGlobalCtxDb, createPgVectorIndex, createPostgresGlobalCtxDb, mysqlDialect, postgresDialect };

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 c}from"@lunora/sql-store";import{postgresDialect as l,mysqlDialect as s}from"./packem_shared/mysqlDialect-BS1Sz60B.mjs";import{buildMysqlExec as a,buildPgExec as i}from"./packem_shared/buildMysqlExec-CjkrA5JG.mjs";import{createPgVectorIndex as d}from"./packem_shared/createPgVectorIndex-CSNnG065.mjs";const r=({engine:e,exec:t,...o})=>c({...o,dialect:e==="postgres"?l:s,exec:t}),p=(e,t)=>r({...t,engine:"postgres",exec:i(e)}),g=(e,t)=>r({...t,engine:"mysql",exec:a(e)});export{a as buildMysqlExec,i as buildPgExec,r as createHyperdriveGlobalCtxDb,g as createMysqlGlobalCtxDb,d as createPgVectorIndex,p as createPostgresGlobalCtxDb,s as mysqlDialect,l as postgresDialect};