@lunora/hyperdrive 1.0.0-alpha.115 → 1.0.0-alpha.116

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.

package/dist/index.d.mts

@@ -14,9 +14,14 @@ import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as S
  * 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));
+ * // Wire the client once, on the app builder — called per shard construction,
+ * // not per request. `ctx.sql` is emitted `readonly`; it is never assigned.
+ * const app = defineApp<Env>()
+ *     .shard((env) => env.SHARD)
+ *     .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE).connectionString)))
+ *     .build();
+ *
+ * // Then, inside an action (never a query/mutation):
  * const rows = await ctx.sql.query("select id from users where org = $1", [orgId]);
  * ```
  * @remarks

package/dist/index.d.ts

@@ -14,9 +14,14 @@ import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as S
  * 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));
+ * // Wire the client once, on the app builder — called per shard construction,
+ * // not per request. `ctx.sql` is emitted `readonly`; it is never assigned.
+ * const app = defineApp<Env>()
+ *     .shard((env) => env.SHARD)
+ *     .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE).connectionString)))
+ *     .build();
+ *
+ * // Then, inside an action (never a query/mutation):
  * const rows = await ctx.sql.query("select id from users where org = $1", [orgId]);
  * ```
  * @remarks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/hyperdrive",
-  "version": "1.0.0-alpha.115",
+  "version": "1.0.0-alpha.116",
   "description": "Bring-your-own Postgres/MySQL for Lunora via Cloudflare Hyperdrive: a driver-agnostic, action-only ctx.sql",
   "keywords": [
     "cloudflare",
@@ -51,9 +51,9 @@
   },
   "dependencies": {
     "@lunora/errors": "1.0.0-alpha.36",
-    "@lunora/platform": "1.0.0-alpha.30",
-    "@lunora/shard-engine": "1.0.0-alpha.64",
-    "@lunora/sql-store": "1.0.0-alpha.116",
+    "@lunora/platform": "1.0.0-alpha.31",
+    "@lunora/shard-engine": "1.0.0-alpha.66",
+    "@lunora/sql-store": "1.0.0-alpha.118",
     "drizzle-orm": "^0.45.2"
   },
   "peerDependencies": {