@pramen/server 0.0.48 → 0.0.49

package/dist/sdk/acl.d.ts

@@ -1,3 +1,4 @@
+import type { CellValue, JsonValue, Row } from "./infer";
 export type Action = "read" | "create" | "update" | "delete";
 /** Runtime identity. Augment with your own properties (userId, tier, …). */
 export interface Identity {
@@ -8,7 +9,7 @@ export interface Identity {
      * expiry per message (see durable-object.ts). Absent for non-expiring / synthetic
      * (callPrivileged) identities, which are therefore never treated as expired. */
     exp?: number;
-    [key: string]: unknown;
+    [key: string]: JsonValue | undefined;
 }
 declare const IDENTITY_MARKER: unique symbol;
 export interface IdentityMarker {
@@ -17,7 +18,7 @@ export interface IdentityMarker {
 }
 /** Reference an identity property in a policy `where`, resolved per request. */
 export declare function $identity(path: string): IdentityMarker;
-export declare function isIdentityMarker(v: unknown): v is IdentityMarker;
+export declare function isIdentityMarker(v: WhereValue): v is IdentityMarker;
 declare const INPUT_MARKER: unique symbol;
 export interface InputMarker {
     readonly [INPUT_MARKER]: true;
@@ -28,7 +29,7 @@ export interface InputMarker {
  * caller can read a row only by presenting its unguessable key, without being able
  * to enumerate. An absent input value makes the rule match nothing (safe deny). */
 export declare function $input(path: string): InputMarker;
-export declare function isInputMarker(v: unknown): v is InputMarker;
+export declare function isInputMarker(v: WhereValue): v is InputMarker;
 declare const NOW_MARKER: unique symbol;
 export interface NowMarker {
     readonly [NOW_MARKER]: true;
@@ -49,7 +50,7 @@ export interface NowMarker {
  * `toISOString()` — as the CMS `publish` field does — or compare it against
  * `expr.now()`-shaped values only. */
 export declare function $now(): NowMarker;
-export declare function isNowMarker(v: unknown): v is NowMarker;
+export declare function isNowMarker(v: WhereValue): v is NowMarker;
 export interface AllowMarker {
     readonly kind: "allow";
 }
@@ -58,8 +59,14 @@ export interface DenyMarker {
 }
 export declare function allow(): AllowMarker;
 export declare function deny(): DenyMarker;
-/** A where rule: column -> value, where value may be a literal or an $identity marker. */
-export type WhereRule = Record<string, unknown | IdentityMarker>;
+/** A value inside a `where` rule: a literal cell value, a per-request marker, an
+ * operator object (`{ gte: 5 }`), a nested relation predicate, or an AND/OR group. */
+export type WhereValue = CellValue | IdentityMarker | InputMarker | NowMarker | WhereRule | WhereValue[];
+/** A where rule: column (or `AND`/`OR`/`NOT`) -> value. An interface so it can recur
+ * through `WhereValue` for nested relation predicates and boolean groups. */
+export interface WhereRule {
+    [key: string]: WhereValue;
+}
 /** A per-row (cell-level) field grant: `fields` are permitted only for rows that
  * match `when`. Additive over the policy's flat `fields` — a conditional grant can
  * only ever ADD fields, never remove them. */
@@ -71,7 +78,7 @@ export interface ConditionalFields {
 /** Escape hatch for cell-level ACL: a late per-row resolver. Given the identity and
  * the fetched (or candidate, on write) row, returns the extra permitted fields —
  * additive over `fields`; `null` means all fields for that row. */
-export type FieldsFn = (identity: Identity | null, row: Record<string, unknown>) => string[] | null;
+export type FieldsFn = (identity: Identity | null, row: Row) => string[] | null;
 /** Per-relation ACL inside a parent read policy. */
 export interface RelationAclRule {
     /** Permit traversal to the related entity via this relation even if it has no
@@ -87,11 +94,11 @@ export interface RelationAclRule {
     fieldsFn?: FieldsFn;
 }
 /** A forced column value on write: a literal, or computed from the identity. */
-export type SetValue = unknown | ((identity: Identity | null) => unknown);
+export type SetValue = CellValue | ((identity: Identity | null) => CellValue);
 /** Server-side validation on write; throw to reject. Runs on the final values. */
 export type Validator = (args: {
     identity: Identity | null;
-    values: Record<string, unknown>;
+    values: Row;
 }) => void;
 export interface PolicyRules {
     /** Row-level predicate (AND of equalities). Omit/empty = all rows. */
@@ -117,13 +124,13 @@ export interface PolicyRules {
 export interface ResolverDb {
     find(spec: {
         from: string;
-        where?: Record<string, unknown>;
+        where?: WhereRule;
         orderBy?: {
             column: string;
             dir?: "asc" | "desc";
         };
         limit?: number;
-    }): Promise<Array<Record<string, unknown>>>;
+    }): Promise<Row[]>;
 }
 export interface ResolverContext {
     readonly identity: Identity | null;

package/dist/sdk/handlers.d.ts

@@ -6,6 +6,12 @@ import type { Queue } from "../runtime/queue";
 import type { Identity } from "./acl";
 import type { Files } from "./files";
 import type { SchemaDef } from "./schema";
+import type { JsonValue } from "./infer";
+/** The Worker/DO environment as an open, read-only bag: Cloudflare bindings (KV, R2,
+ * D1, Queues, …) alongside vars and secrets. Deliberately open and opaque — an app
+ * declares its own bindings, so the value type cannot be enumerated here; read a value
+ * and narrow it at the use site (`ctx.env.STRIPE_SECRET_KEY as string`). */
+export type EnvBag = Readonly<Record<string, unknown>>;
 export interface HandlerContext<S extends SchemaDef = SchemaDef> {
     /** Schema-typed repository: find/insert/update/delete inferred from S. */
     readonly db: Db<S>;
@@ -25,7 +31,7 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
      * Use it to call external services from handlers — Cloudflare bindings (e.g. the
      * `send_email` binding for Cloudflare Email Sending) or third-party APIs (Stripe, …). Loosely typed;
      * cast a value at the use site, e.g. `ctx.env.STRIPE_SECRET_KEY as string`. */
-    readonly env: Readonly<Record<string, unknown>>;
+    readonly env: EnvBag;
     /** Resolved identity for this request (null = anonymous). */
     readonly identity: Identity | null;
     /** Deferred side-effects (a transactional outbox). `tasks.enqueue` persists a task
@@ -100,7 +106,7 @@ export interface Handler<I = unknown, O = unknown> {
     readonly run: (ctx: HandlerContext<any>, input: I) => O | Promise<O>;
     /** Optional boundary validator: parse/validate the raw request input, throwing
      * to reject (surfaced as a 400). Its return type fixes the handler's input. */
-    readonly input?: (raw: unknown) => unknown;
+    readonly input?: (raw: JsonValue) => unknown;
     /** Optional DO partition this handler runs in (static, server-side). The Worker
      * routes the request to the matching partition-DO before dispatch. Absent ⇒ the
      * default partition (routed to the bare tenant key). */
@@ -109,7 +115,7 @@ export interface Handler<I = unknown, O = unknown> {
     readonly auth?: HandlerAuth;
 }
 export interface HandlerOpts<I> {
-    input?: (raw: unknown) => I;
+    input?: (raw: JsonValue) => I;
     /** DO partition this handler runs in. Absent ⇒ the default partition. */
     partition?: string;
     /** Authorization to CALL this handler (see HandlerAuth) — gate non-`ctx.db` handlers. */

package/dist/sdk/infer.d.ts

@@ -5,6 +5,23 @@ export type { FileRef } from "./files";
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
+/** A JSON object — the object arm of `JsonValue`, named so it can be referenced
+ * directly (e.g. an identity's claims, a `t.json()` column's object form). */
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+/** A raw value as the substrate stores/returns it, before pramen's object↔JSON codec.
+ * DO SQLite and D1 hand back exactly these; BLOB columns arrive as an ArrayBuffer. */
+export type SqlValue = string | number | bigint | boolean | null | ArrayBuffer;
+/** A decoded column value as handlers see it at the `Db` chokepoint: any JSON value,
+ * a `fileRef` column's metadata, or — for an eager-loaded relation — the related
+ * row(s) grafted onto the parent under the relation name. */
+export type CellValue = SqlValue | JsonValue | FileRef | Row | Row[];
+/** A decoded database row — column name -> decoded value. An interface (not a
+ * `Record` alias) so it can recur through `CellValue` for eager-loaded relations. */
+export interface Row {
+    [column: string]: CellValue;
+}
 /** SQL field type -> TypeScript value type. */
 export type FieldTsType<D extends FieldDef> = D["type"] extends "text" ? string : D["type"] extends "boolean" ? boolean : D["type"] extends "json" ? JsonValue : D["type"] extends "fileRef" ? FileRef : D["type"] extends "uuid" ? string : number;
 /** A column is non-null iff it's NOT NULL or a primary key. */

package/dist/worker.d.ts

@@ -1,3 +1,4 @@
+import type { JsonValue } from "./sdk/infer";
 import { type QueueProducerBinding } from "./runtime/queue";
 import { type QueueBatch } from "./runtime/queue-consumer";
 import type { PramenApp } from "./pramen";
@@ -65,7 +66,7 @@ export declare function useD1Store(opts: {
  * DO's JSON response (`{ ok, result }` / `{ ok: false, … }`). */
 export declare function callPrivileged(env: Env, opts: {
     name: string;
-    input?: unknown;
+    input?: JsonValue;
     tenant?: string;
     roles?: string[];
     partition?: string;

package/dist/worker.js

@@ -18,6 +18,10 @@ import { Kv, isSessionDenied } from "./runtime/kv";
 import { listDOs, partitionDoName } from "./runtime/registry";
 import { createFiles, handleFileRequest, handleMediaRequest, R2Adapter } from "./runtime/storage";
 import { DEFAULT_PARTITION, partitionsOf } from "./sdk/schema";
+/** Widen the closed `Env` interface to the open `EnvBag` handlers and services see.
+ * Spreading yields an anonymous object type, which TypeScript gives an implicit index
+ * signature — so this needs no type assertion. */
+const envBag = (env) => ({ ...env });
 /** The secret used to sign/verify file tokens — a dedicated FILES_SECRET if set,
  * else AUTH_SECRET (so HS256 setups work out of the box). */
 const filesSecret = (env) => env.FILES_SECRET || env.AUTH_SECRET;
@@ -172,7 +176,8 @@ export function makeWorker(app) {
         const files = createFiles({ tenant: "main", secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
         const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
         const kv = new Kv(env.KV);
-        return { db, kv, files, env: env, identity, tasks: tasksFacade(driver), mail: createMail(env, kv), queue: createQueue(env) };
+        const bag = envBag(env);
+        return { db, kv, files, env: bag, identity, tasks: tasksFacade(driver), mail: createMail(bag, kv), queue: createQueue(bag) };
     };
     /** Drain the D1 outbox in the Worker (no DO/alarm on this path) — called by the
      * /admin/tasks/drain route with `x-pramen-store: d1`, and by `scheduled()` (Cron). */
@@ -216,7 +221,7 @@ export function makeWorker(app) {
             for (const r of app.routes ?? []) {
                 if (request.method === r.method && url.pathname === r.path) {
                     const routeCtx = { callPrivileged: (opts) => callPrivileged(env, opts) };
-                    return r.handler(request, env, routeCtx);
+                    return r.handler(request, envBag(env), routeCtx);
                 }
             }
             // CORS (opt-in via CORS_ORIGINS) for cross-origin browser clients. Answer the
@@ -396,9 +401,10 @@ export function makeWorker(app) {
                 }
                 // (isLive is excluded by useD1Store — live always routes to the DO below.)
                 const name = url.pathname.replace(/^\/rpc\//, "");
-                let input;
+                // The RPC body is JSON — parse it into the domain type once, here at the boundary.
+                let input = null;
                 if (request.method === "POST")
-                    input = await request.json().catch(() => undefined);
+                    input = ((await request.json().catch(() => null)) ?? null);
                 // Pick where the D1 session may start its first read. A mutation ALWAYS pins the
                 // primary (`first-primary` is a superset of read-your-writes) so a read-modify-write
                 // can't run off a lagging replica — an inbound bookmark must not widen that window.
@@ -414,10 +420,10 @@ export function makeWorker(app) {
                     start = "first-unconstrained";
                 const driver = new D1Driver(env.DB, { start });
                 const files = createFiles({ tenant, secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
-                const envBag = env;
+                const bag = envBag(env);
                 try {
                     await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
-                    const { result, enqueued } = await dispatch(app.handlers, app.schema, driver, new Kv(env.KV), files, envBag, { acl: d1Acl, identity }, name, input);
+                    const { result, enqueued } = await dispatch(app.handlers, app.schema, driver, new Kv(env.KV), files, bag, { acl: d1Acl, identity }, name, input);
                     // Kick an immediate drain in the request tail when this handler enqueued tasks
                     // (e.g. sendMagicLinkEmail). Without this, tasks wait for the next Cron trigger
                     // — up to a full minute. `waitUntil` lets the response return now while the
@@ -488,13 +494,13 @@ export function makeWorker(app) {
         // handler (ACK on success / RETRY on throw, per message). A consumer is Worker-level
         // (no tenant DO): its ctx carries env/kv/mail/queue + callPrivileged to reach a DO.
         async queue(batch, env) {
-            const envBag = env;
+            const bag = envBag(env);
             const kv = new Kv(env.KV);
             const ctx = {
-                env: envBag,
+                env: bag,
                 kv,
-                mail: createMail(envBag, kv),
-                queue: createQueue(envBag),
+                mail: createMail(bag, kv),
+                queue: createQueue(bag),
                 callPrivileged: (opts) => callPrivileged(env, opts),
             };
             await dispatchQueueBatch(app.queues ?? {}, ctx, batch);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.48",
+  "version": "0.0.49",
   "description": "pramen server runtime — schema, ACL, ORM, live queries, files, and the createPramen(app) factory for Cloudflare Workers + Durable Objects.",
   "license": "MIT",
   "repository": {

package/src/auth.ts

@@ -11,6 +11,7 @@
 // non-standard claims pass through.
 
 import type { Identity } from "./sdk/acl";
+import type { JsonObject } from "./sdk/infer";
 
 const STANDARD_CLAIMS = new Set(["exp", "iat", "nbf", "iss", "aud", "jti", "sub", "role", "roles", "userId"]);
 
@@ -34,7 +35,7 @@ interface JwtHeader {
 /** Verifies a JWT and returns its claims, or null if invalid. Implementations
  * differ only in how they verify the signature. */
 export interface VerifyStrategy {
-  verify(token: string): Promise<Record<string, unknown> | null>;
+  verify(token: string): Promise<JsonObject | null>;
 }
 
 /** Verify a signature over `${header}.${payload}` for the parsed header. */
@@ -69,7 +70,7 @@ async function verifyJwt(
   token: string,
   verifySignature: SignatureVerifier,
   opts: VerifyOptions = {},
-): Promise<Record<string, unknown> | null> {
+): Promise<JsonObject | null> {
   const parts = token.split(".");
   if (parts.length !== 3) return null;
   const [h, p, sig] = parts;
@@ -89,7 +90,7 @@ async function verifyJwt(
   }
   if (!valid) return null;
 
-  let payload: Record<string, unknown>;
+  let payload: JsonObject;
   try {
     payload = JSON.parse(b64urlToString(p!));
   } catch {
@@ -113,7 +114,7 @@ export class HmacStrategy implements VerifyStrategy {
     private readonly opts: VerifyOptions = {},
   ) {}
 
-  verify(token: string): Promise<Record<string, unknown> | null> {
+  verify(token: string): Promise<JsonObject | null> {
     return verifyJwt(
       token,
       async (input, signature, header) => {
@@ -152,7 +153,7 @@ export class JwksStrategy implements VerifyStrategy {
     private readonly opts: VerifyOptions = {},
   ) {}
 
-  verify(token: string): Promise<Record<string, unknown> | null> {
+  verify(token: string): Promise<JsonObject | null> {
     return verifyJwt(
       token,
       async (input, signature, header) => {
@@ -219,7 +220,7 @@ export class JwksStrategy implements VerifyStrategy {
   }
 }
 
-function toIdentity(claims: Record<string, unknown>): Identity {
+function toIdentity(claims: JsonObject): Identity {
   const roles = Array.isArray(claims.roles)
     ? (claims.roles as string[])
     : typeof claims.role === "string"

package/src/cli.ts

@@ -21,7 +21,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { createTableSql } from "./runtime/ddl";
 import { schemaHash } from "./runtime/migrate";
-import { diffSchemaShape, schemaShape, type SchemaShape } from "./runtime/schema-diff";
+import { diffSchemaFingerprint, schemaFingerprint, type SchemaFingerprint } from "./runtime/schema-diff";
 import { entitiesInPartition, partitionsOf, type SchemaDef } from "./sdk/schema";
 
 /** Mint an HS256 JWT — mirrors what a real auth service would issue, for local
@@ -36,6 +36,9 @@ function bytesToB64url(bytes: Uint8Array): string {
 }
 const strToB64url = (s: string) => bytesToB64url(new TextEncoder().encode(s));
 
+/** The dev JWT claims `pramen token` mints. */
+type TokenClaims = { sub: string; roles: string[]; tenants?: string[] };
+
 async function sign(payload: Record<string, unknown>): Promise<string> {
   const secret = process.env.AUTH_SECRET || DEV_SECRET;
   const now = Math.floor(Date.now() / 1000);
@@ -102,7 +105,7 @@ Usage: pramen <command>
   init [dir]                scaffold a new project (app.ts + worker.ts + oblaka.ts)
   schema sql                print CREATE TABLE statements for the schema
   schema hash               print the schema hash
-  schema snapshot           save the schema shape to .pramen/schema.json
+  schema snapshot           save the schema fingerprint to .pramen/schema.json
   schema diff               compare the schema to the snapshot (safe vs unsafe)
   schema status             compare a deployed tenant's schema to the local schema
                             [--tenant t] [--url u] [--token jwt]
@@ -126,20 +129,27 @@ async function schemaCmd(sub: string | undefined): Promise<void> {
   if (sub === "snapshot") {
     const { schema } = await loadApp();
     mkdirSync(dirname(snapshotPath), { recursive: true });
-    const snap = { hash: schemaHash(schema), shape: schemaShape(schema) };
+    const snap = { hash: schemaHash(schema), fingerprint: schemaFingerprint(schema) };
     writeFileSync(snapshotPath, JSON.stringify(snap, null, 2) + "\n");
-    console.log(`wrote ${snapshotPath} (${Object.keys(snap.shape).length} tables)`);
+    console.log(`wrote ${snapshotPath} (${Object.keys(snap.fingerprint).length} tables)`);
     return;
   }
   if (sub === "diff") {
     const { schema } = await loadApp();
-    const next = schemaShape(schema);
+    const next = schemaFingerprint(schema);
     if (!existsSync(snapshotPath)) {
       console.log("no snapshot — run `pramen schema snapshot` to set a baseline.");
       return;
     }
-    const prev = (JSON.parse(readFileSync(snapshotPath, "utf8")) as { shape: SchemaShape }).shape;
-    const changes = diffSchemaShape(prev, next);
+    // `fingerprint` was called `shape` before; keep reading an existing snapshot so an
+    // upgrade doesn't force a re-baseline.
+    const snap = JSON.parse(readFileSync(snapshotPath, "utf8")) as {
+      fingerprint?: SchemaFingerprint;
+      // the pre-rename key, quoted because it names a stored JSON field, not a symbol
+      "shape"?: SchemaFingerprint;
+    };
+    const prev = snap.fingerprint ?? snap["shape"] ?? {};
+    const changes = diffSchemaFingerprint(prev, next);
     if (changes.length === 0) {
       console.log("no changes since snapshot.");
       return;
@@ -203,7 +213,7 @@ async function schemaCmd(sub: string | undefined): Promise<void> {
       console.log(`live:    ${live.hash ?? "(none)"}`);
       console.log(`current: ${current}`);
       console.log(upToDate ? "✓ up to date" : "⚠ BEHIND — migrates on the tenant's next boot");
-      const want = schemaShape(subset);
+      const want = schemaFingerprint(subset);
       for (const table of Object.keys(want)) {
         const liveCols = new Set(live.tables[table] ?? []);
         const missing = Object.keys(want[table]!.columns).filter((col) => !liveCols.has(col));
@@ -222,7 +232,9 @@ async function tokenCmd(args: string[]): Promise<void> {
   if (!sub) fail("token: <sub> required");
   const roles = pos.slice(1);
   const tenants = flag("tenant")?.split(",");
-  console.log(await sign({ sub, roles: roles.length ? roles : ["admin"], ...(tenants ? { tenants } : {}) }));
+  const claims: TokenClaims = { sub, roles: roles.length ? roles : ["admin"] };
+  if (tenants) claims.tenants = tenants;
+  console.log(await sign(claims));
 }
 
 function initCmd(args: string[]): void {

package/src/durable-object.ts

@@ -34,6 +34,8 @@ import type { Identity } from "./sdk/acl";
 import type { HandlerContext } from "./sdk/handlers";
 import type { PramenApp } from "./pramen";
 import type { ClientMsg, ServerMsg, Subscription } from "./runtime/protocol";
+import type { EnvBag } from "./sdk/handlers";
+import type { JsonValue } from "./sdk/infer";
 
 /** Durable per-socket state — kept SMALL and stable, since it rides the WebSocket
  * attachment which workerd caps at ~2 KB. Only auth/routing identity lives here so it
@@ -208,9 +210,10 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     }
 
     const name = new URL(request.url).pathname.replace(/^\/rpc\//, "");
-    let input: unknown;
+    // The RPC body is JSON — parse it into the domain type once, here at the boundary.
+    let input: JsonValue = null;
     if (request.method === "POST") {
-      input = await request.json().catch(() => undefined);
+      input = ((await request.json().catch(() => null)) ?? null) as JsonValue;
     }
 
     try {
@@ -354,12 +357,12 @@ export class PramenDOBase extends DurableObject<DoEnv> {
 
     switch (msg.type) {
       case "subscribe":
-        return this.onSubscribe(ws, msg.id, msg.name, msg.input);
+        return this.onSubscribe(ws, msg.id, msg.name, msg.input ?? null);
       case "unsubscribe":
         this.setSubs(ws, this.getSubs(ws).filter((s) => s.id !== msg.id));
         return;
       case "call":
-        return this.onCall(ws, msg.id, msg.name, msg.input);
+        return this.onCall(ws, msg.id, msg.name, msg.input ?? null);
       default:
         return this.send(ws, { type: "error", id: "", error: "unknown message type" });
     }
@@ -381,7 +384,7 @@ export class PramenDOBase extends DurableObject<DoEnv> {
 
   // --- live-query internals ---
 
-  private async onSubscribe(ws: WebSocket, id: string, name: string, input: unknown): Promise<void> {
+  private async onSubscribe(ws: WebSocket, id: string, name: string, input: JsonValue): Promise<void> {
     const att = this.getAttachment(ws);
     const subs = this.getSubs(ws);
     try {
@@ -402,7 +405,7 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     }
   }
 
-  private async onCall(ws: WebSocket, id: string, name: string, input: unknown): Promise<void> {
+  private async onCall(ws: WebSocket, id: string, name: string, input: JsonValue): Promise<void> {
     const att = this.getAttachment(ws);
     let outcome: Awaited<ReturnType<typeof dispatch>>;
     try {
@@ -603,8 +606,12 @@ export class PramenDOBase extends DurableObject<DoEnv> {
 
   // The DO env (bindings + vars + secrets) handed to handlers as ctx.env. Loosely
   // typed at the boundary so handlers can read any var/secret without a DoEnv cast.
-  private get envBag(): Readonly<Record<string, unknown>> {
-    return this.env as unknown as Record<string, unknown>;
+  private widenedEnv: EnvBag | null = null;
+  private get envBag(): EnvBag {
+    // `this.env` is fixed for the DO's lifetime, so widen it once. This getter is read
+    // inside the per-subscription live-query loop, where a copy per read would allocate
+    // one whole binding bag per subscription on every write.
+    return (this.widenedEnv ??= { ...this.env });
   }
 
   // One Files facade per DO (a DO serves one tenant). Backed by the R2 binding;

package/src/index.ts

@@ -31,7 +31,7 @@ export type {
 // --- app + handlers ---
 export { createApp } from "./sdk/app";
 export { query, mutation, authorizeHandler } from "./sdk/handlers";
-export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap, BootstrapContext, BootstrapFn } from "./sdk/handlers";
+export type { EnvBag, Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap, BootstrapContext, BootstrapFn } from "./sdk/handlers";
 
 // --- ACL ---
 export { $identity, $input, $now, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker, isNowMarker } from "./sdk/acl";
@@ -64,6 +64,10 @@ export type {
   InferRow,
   InferUpdate,
   JsonValue,
+  JsonObject,
+  SqlValue,
+  CellValue,
+  Row,
   ProjectedRow,
   RelationsOf,
   RelationsResult,
@@ -95,4 +99,4 @@ export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/erro
 
 // --- substrate seam (advanced: bring your own SQL backend) ---
 export { sqliteDialect, postgresDialect, DoSqliteDriver, D1Driver } from "./runtime/driver";
-export type { Driver, Dialect, Row } from "./runtime/driver";
+export type { Driver, Dialect, DriverRow } from "./runtime/driver";

package/src/pramen.ts

@@ -18,12 +18,14 @@ import { validateTriggerTasks, type SchemaDef } from "./sdk/schema";
 import type { AppTaskMap, HandlerMap, BootstrapFn } from "./sdk/handlers";
 import type { AppQueueMap, QueueBatch } from "./runtime/queue-consumer";
 import type { Role } from "./sdk/acl";
+import type { EnvBag } from "./sdk/handlers";
+import type { JsonValue } from "./sdk/infer";
 
 /** Injected into a public route's handler — forward a privileged mutation into the
  * tenant's DO without the handler importing any deploy-side code (so app.ts stays
  * authoring-only). The synthetic identity defaults to the admin role. */
 export interface RouteContext {
-  callPrivileged(opts: { name: string; input?: unknown; tenant?: string; roles?: string[] }): Promise<Response>;
+  callPrivileged(opts: { name: string; input?: JsonValue; tenant?: string; roles?: string[] }): Promise<Response>;
 }
 
 /** A public, pre-auth route — matched before identity resolution, so it can host a
@@ -36,7 +38,7 @@ export interface PublicRoute {
   method: string;
   /** Exact pathname to match (e.g. "/stripe/webhook"). */
   path: string;
-  handler: (request: Request, env: Readonly<Record<string, unknown>>, ctx: RouteContext) => Response | Promise<Response>;
+  handler: (request: Request, env: EnvBag, ctx: RouteContext) => Response | Promise<Response>;
 }
 
 /** The user-facing app: a schema, the handler map, ACL roles, and optional public