@pramen/server 0.0.48 → 0.0.49

package/src/runtime/read-engine.ts

@@ -6,11 +6,14 @@
 // AND/OR groups) and ACL row-level scopes be merged before compilation. Column
 // names come from developer code (schema keys); values are always parameterized.
 
+import type { WhereRule, WhereValue } from "../sdk/acl";
+import type { CellValue, Row } from "../sdk/infer";
+
 import type { Dialect } from "./driver";
 
 // In-process value coercion for evalExpr (SQLite-style booleans). SQL-side encoding
 // goes through the active Dialect; this mirrors it for the cell-ACL `when` evaluator.
-function bind(v: unknown): unknown {
+function bind(v: CellValue): CellValue {
   return typeof v === "boolean" ? (v ? 1 : 0) : v;
 }
 
@@ -23,8 +26,8 @@ export type StrMode = "contains" | "prefix" | "suffix";
 export type SqlExpr =
   | { t: "true" }
   | { t: "false" }
-  | { t: "cmp"; op: CmpOp; col: string; value: unknown }
-  | { t: "in"; col: string; values: unknown[]; negate: boolean }
+  | { t: "cmp"; op: CmpOp; col: string; value: CellValue }
+  | { t: "in"; col: string; values: CellValue[]; negate: boolean }
   | { t: "null"; col: string; negate: boolean }
   // Structured substring match — the needle is escaped and wrapped, so `%`/`_` in the
   // input match literally (unlike raw `like`, where the caller controls wildcards).
@@ -39,28 +42,28 @@ export type SqlExpr =
 
 export const TRUE: SqlExpr = { t: "true" };
 export const FALSE: SqlExpr = { t: "false" };
-export const cmp = (op: CmpOp, col: string, value: unknown): SqlExpr => ({ t: "cmp", op, col, value });
+export const cmp = (op: CmpOp, col: string, value: CellValue): SqlExpr => ({ t: "cmp", op, col, value });
 export const isNull = (col: string, negate = false): SqlExpr => ({ t: "null", col, negate });
-export const inList = (col: string, values: unknown[], negate = false): SqlExpr => ({ t: "in", col, values, negate });
+export const inList = (col: string, values: CellValue[], negate = false): SqlExpr => ({ t: "in", col, values, negate });
 export const strMatch = (col: string, needle: string, mode: StrMode): SqlExpr => ({ t: "strmatch", col, needle, mode });
 export const and = (...parts: SqlExpr[]): SqlExpr => ({ t: "and", parts });
 export const or = (...parts: SqlExpr[]): SqlExpr => ({ t: "or", parts });
 export const not = (expr: SqlExpr): SqlExpr => ({ t: "not", expr });
 
 /** Equality (null -> IS NULL). Used by ACL scope building and relation loads. */
-export const eq = (col: string, value: unknown): SqlExpr => (value === null ? isNull(col) : cmp("=", col, value));
+export const eq = (col: string, value: CellValue): SqlExpr => (value === null ? isNull(col) : cmp("=", col, value));
 
 /** Compile a structured user predicate into a SqlExpr.
  * Shapes: { col: value } (eq) | { col: { gt, lt, in, like, isNull, … } } | { AND: [...] } | { OR: [...] } */
-export function compileWhere(input: Record<string, unknown>): SqlExpr {
+export function compileWhere(input: WhereRule): SqlExpr {
   const parts: SqlExpr[] = [];
   for (const [k, v] of Object.entries(input)) {
     if (k === "AND") {
-      parts.push(and(...(v as Record<string, unknown>[]).map(compileWhere)));
+      parts.push(and(...(v as WhereRule[]).map(compileWhere)));
     } else if (k === "OR") {
-      parts.push(or(...(v as Record<string, unknown>[]).map(compileWhere)));
+      parts.push(or(...(v as WhereRule[]).map(compileWhere)));
     } else if (k === "NOT") {
-      parts.push(not(compileWhere(v as Record<string, unknown>)));
+      parts.push(not(compileWhere(v as WhereRule)));
     } else {
       parts.push(columnPredicate(k, v));
     }
@@ -68,10 +71,13 @@ export function compileWhere(input: Record<string, unknown>): SqlExpr {
   return parts.length ? and(...parts) : TRUE;
 }
 
-function columnPredicate(col: string, v: unknown): SqlExpr {
+function columnPredicate(col: string, v: WhereValue): SqlExpr {
   if (v !== null && typeof v === "object" && !Array.isArray(v)) {
     const ops: SqlExpr[] = [];
-    for (const [op, val] of Object.entries(v as Record<string, unknown>)) {
+    for (const [op, operand] of Object.entries(v as WhereRule)) {
+      // Markers are resolved upstream (runtime/acl.ts), so an operator's operand is a
+      // literal cell value by this point.
+      const val = operand as CellValue;
       switch (op) {
         case "eq": ops.push(eq(col, val)); break;
         case "ne": ops.push(val === null ? isNull(col, true) : cmp("!=", col, val)); break;
@@ -83,23 +89,23 @@ function columnPredicate(col: string, v: unknown): SqlExpr {
         case "contains": ops.push(strMatch(col, String(val), "contains")); break;
         case "startsWith": ops.push(strMatch(col, String(val), "prefix")); break;
         case "endsWith": ops.push(strMatch(col, String(val), "suffix")); break;
-        case "in": ops.push(inList(col, val as unknown[])); break;
-        case "notIn": ops.push(inList(col, val as unknown[], true)); break;
+        case "in": ops.push(inList(col, val as CellValue[])); break;
+        case "notIn": ops.push(inList(col, val as CellValue[], true)); break;
         case "isNull": ops.push(isNull(col, !val)); break; // isNull:true => IS NULL
         default: throw new Error(`unknown operator: ${op}`);
       }
     }
     return ops.length ? and(...ops) : TRUE;
   }
-  return eq(col, v);
+  return eq(col, v as CellValue);
 }
 
 export interface CompiledSql {
   readonly sql: string;
-  readonly params: unknown[];
+  readonly params: CellValue[];
 }
 
-export function compileExpr(expr: SqlExpr, dialect: Dialect, params: unknown[] = []): CompiledSql {
+export function compileExpr(expr: SqlExpr, dialect: Dialect, params: CellValue[] = []): CompiledSql {
   switch (expr.t) {
     case "true":
       return { sql: "1", params };
@@ -168,7 +174,7 @@ function likeToRegex(pattern: string): RegExp {
  * semantics (bound-boolean coercion, NULL compares false, empty-IN, LIKE) so the
  * declarative cell-ACL `when` path can decide per-row field visibility without a
  * round-trip to SQLite. */
-export function evalExpr(expr: SqlExpr, row: Record<string, unknown>): boolean {
+export function evalExpr(expr: SqlExpr, row: Row): boolean {
   switch (expr.t) {
     case "true":
       return true;
@@ -245,7 +251,7 @@ export type AggFn = "count" | "sum" | "avg" | "min" | "max";
 const AGG_SQL: Record<AggFn, string> = { count: "COUNT", sum: "SUM", avg: "AVG", min: "MIN", max: "MAX" };
 
 export function compileCount(from: string, dialect: Dialect, where?: SqlExpr): CompiledSql {
-  const params: unknown[] = [];
+  const params: CellValue[] = [];
   let sql = `SELECT COUNT(*) AS n FROM ${dialect.id(from)}`;
   if (where && where.t !== "true") sql += ` WHERE ${compileExpr(where, dialect, params).sql}`;
   return { sql, params };
@@ -265,7 +271,7 @@ export function compileAggregate(
   },
   dialect: Dialect,
 ): CompiledSql {
-  const params: unknown[] = [];
+  const params: CellValue[] = [];
   const cols: string[] = [];
   for (const g of spec.groupBy ?? []) cols.push(dialect.id(g));
   for (const [key, agg] of Object.entries(spec.aggregations)) {
@@ -279,7 +285,7 @@ export function compileAggregate(
 }
 
 export function compileSelect(spec: QuerySpec, dialect: Dialect): CompiledSql {
-  const params: unknown[] = [];
+  const params: CellValue[] = [];
   const cols = spec.columns && spec.columns.length > 0 ? spec.columns.map((c) => dialect.id(c)).join(", ") : "*";
   let sql = `SELECT ${cols} FROM ${dialect.id(spec.from)}`;
 

package/src/runtime/registry.ts

@@ -79,7 +79,11 @@ export function parseRegistryKey(key: string): DoRef | null {
 /** Enumerate every registered `(tenant, partition)` pair from the registry KV.
  * Paginates over the full listing (cursor / list_complete) — never truncates at the
  * 1000-key page limit. */
-export async function listDOs(kv: KVNamespace): Promise<DoRef[]> {
+/** The slice of KV that DO enumeration needs — narrower than the whole namespace, so
+ * callers (and test doubles) only have to provide `list`. */
+export type KvLister = Pick<KVNamespace, "list">;
+
+export async function listDOs(kv: KvLister): Promise<DoRef[]> {
   const out: DoRef[] = [];
   let cursor: string | undefined;
   for (;;) {

package/src/runtime/schema-diff.ts

@@ -21,7 +21,7 @@ import type { FieldDef, SchemaDef } from "../sdk/schema";
 import { partitionOf } from "../sdk/schema";
 
 /** The comparable fingerprint of a single column: type + migration-relevant modifiers. */
-export interface ColumnShape {
+export interface ColumnFingerprint {
   type: string;
   notNull?: boolean;
   unique?: boolean;
@@ -33,16 +33,16 @@ export interface ColumnShape {
 }
 
 /** The comparable fingerprint of a table: its partition + each column's shape. */
-export interface TableShape {
+export interface TableFingerprint {
   partition: string;
-  columns: Record<string, ColumnShape>;
+  columns: Record<string, ColumnFingerprint>;
 }
 
 /** table -> table shape. The comparable surface of a schema. */
-export type SchemaShape = Record<string, TableShape>;
+export type SchemaFingerprint = Record<string, TableFingerprint>;
 
-function columnShape(f: FieldDef): ColumnShape {
-  const c: ColumnShape = { type: f.type };
+function columnFingerprint(f: FieldDef): ColumnFingerprint {
+  const c: ColumnFingerprint = { type: f.type };
   if (f.notNull) c.notNull = true;
   if (f.unique) c.unique = true;
   if (f.primaryKey) c.primaryKey = true;
@@ -53,27 +53,27 @@ function columnShape(f: FieldDef): ColumnShape {
   return c;
 }
 
-export function schemaShape(schema: SchemaDef): SchemaShape {
-  const out: SchemaShape = {};
+export function schemaFingerprint(schema: SchemaDef): SchemaFingerprint {
+  const out: SchemaFingerprint = {};
   for (const [table, def] of Object.entries(schema)) {
-    const columns: Record<string, ColumnShape> = {};
-    for (const [col, f] of Object.entries(def.fields)) columns[col] = columnShape(f as FieldDef);
+    const columns: Record<string, ColumnFingerprint> = {};
+    for (const [col, f] of Object.entries(def.fields)) columns[col] = columnFingerprint(f as FieldDef);
     out[table] = { partition: partitionOf(schema, table), columns };
   }
   return out;
 }
 
 /** The modifier fields compared for a `change-column` (everything but `type`). */
-const MODIFIER_KEYS: (keyof ColumnShape)[] = ["notNull", "unique", "primaryKey", "generated", "hidden", "default"];
+const MODIFIER_KEYS: (keyof ColumnFingerprint)[] = ["notNull", "unique", "primaryKey", "generated", "hidden", "default"];
 
 /** Does `next` tighten a constraint `prev` lacked (add NOT NULL / UNIQUE / PRIMARY KEY)?
  * Such a change may require the destructive gate or be skipped when the live data
  * conflicts (NULL rows / duplicates) — so the diff flags it `destructive`. */
-function tightensConstraint(prev: ColumnShape, next: ColumnShape): boolean {
+function tightensConstraint(prev: ColumnFingerprint, next: ColumnFingerprint): boolean {
   return (!!next.notNull && !prev.notNull) || (!!next.unique && !prev.unique) || (!!next.primaryKey && !prev.primaryKey);
 }
 
-function modifierDiff(prev: ColumnShape, next: ColumnShape): string | null {
+function modifierDiff(prev: ColumnFingerprint, next: ColumnFingerprint): string | null {
   const parts: string[] = [];
   for (const k of MODIFIER_KEYS) {
     if (prev[k] !== next[k]) parts.push(`${k}: ${fmt(prev[k])} → ${fmt(next[k])}`);
@@ -102,7 +102,7 @@ export interface SchemaChange {
   appliesOnBoot: boolean;
 }
 
-export function diffSchemaShape(prev: SchemaShape, next: SchemaShape): SchemaChange[] {
+export function diffSchemaFingerprint(prev: SchemaFingerprint, next: SchemaFingerprint): SchemaChange[] {
   const changes: SchemaChange[] = [];
 
   for (const table of Object.keys(next)) {

package/src/sdk/acl.ts

@@ -6,6 +6,8 @@
 // and/or a set of permitted `fields`. Access is deny-by-default; policies only
 // ever grant. Across the identity's roles, grants OR-merge (any role can allow).
 
+import type { CellValue, JsonValue, Row } from "./infer";
+
 export type Action = "read" | "create" | "update" | "delete";
 
 /** Runtime identity. Augment with your own properties (userId, tier, …). */
@@ -17,7 +19,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;
 }
 
 // --- $identity markers: reference an identity property inside a where rule ---
@@ -34,8 +36,8 @@ export function $identity(path: string): IdentityMarker {
   return { [IDENTITY_MARKER]: true, path };
 }
 
-export function isIdentityMarker(v: unknown): v is IdentityMarker {
-  return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[IDENTITY_MARKER] === true;
+export function isIdentityMarker(v: WhereValue): v is IdentityMarker {
+  return typeof v === "object" && v !== null && (v as Partial<IdentityMarker>)[IDENTITY_MARKER] === true;
 }
 
 // --- $input markers: reference a request-input field inside a where rule, for a
@@ -56,8 +58,8 @@ export function $input(path: string): InputMarker {
   return { [INPUT_MARKER]: true, path };
 }
 
-export function isInputMarker(v: unknown): v is InputMarker {
-  return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[INPUT_MARKER] === true;
+export function isInputMarker(v: WhereValue): v is InputMarker {
+  return typeof v === "object" && v !== null && (v as Partial<InputMarker>)[INPUT_MARKER] === true;
 }
 
 // --- $now markers: the request's evaluation instant inside a where rule, for a
@@ -88,8 +90,8 @@ export function $now(): NowMarker {
   return { [NOW_MARKER]: true };
 }
 
-export function isNowMarker(v: unknown): v is NowMarker {
-  return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[NOW_MARKER] === true;
+export function isNowMarker(v: WhereValue): v is NowMarker {
+  return typeof v === "object" && v !== null && (v as Partial<NowMarker>)[NOW_MARKER] === true;
 }
 
 // --- allow / deny markers ---
@@ -110,8 +112,21 @@ export function deny(): DenyMarker {
 
 // --- policy rules ---
 
-/** 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
@@ -125,7 +140,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 {
@@ -143,10 +158,10 @@ export interface RelationAclRule {
 }
 
 /** 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> }) => void;
+export type Validator = (args: { identity: Identity | null; values: Row }) => void;
 
 export interface PolicyRules {
   /** Row-level predicate (AND of equalities). Omit/empty = all rows. */
@@ -175,10 +190,10 @@ 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 {

package/src/sdk/handlers.ts

@@ -10,6 +10,13 @@ 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. */
@@ -30,7 +37,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
@@ -119,7 +126,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). */
@@ -129,7 +136,7 @@ export interface Handler<I = unknown, O = unknown> {
 }
 
 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/src/sdk/infer.ts

@@ -11,6 +11,27 @@ export type { FileRef } from "./files";
 /** Any JSON-serializable value — the type of a `t.json()` column. */
 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

package/src/worker.ts

@@ -6,6 +6,8 @@
 
 import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity, type VerifyOptions, type VerifyStrategy } from "./auth";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
+import type { EnvBag } from "./sdk/handlers";
+import type { JsonValue } from "./sdk/infer";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { createMail } from "./runtime/mail";
 import { createQueue, type QueueProducerBinding } from "./runtime/queue";
@@ -23,6 +25,11 @@ import type { HandlerContext } from "./sdk/handlers";
 import { DEFAULT_PARTITION, partitionsOf } from "./sdk/schema";
 import type { PramenApp } from "./pramen";
 
+/** 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): EnvBag => ({ ...env });
+
 export interface Env {
   PRAMEN: DurableObjectNamespace;
   /** Project KV — tenant registry (`tenant:` keys) + handler ctx.kv (`app:` keys). */
@@ -149,7 +156,7 @@ function partitionStubFor(env: Env, tenant: string, partition: string = DEFAULT_
  * DO's JSON response (`{ ok, result }` / `{ ok: false, … }`). */
 export async function callPrivileged(
   env: Env,
-  opts: { name: string; input?: unknown; tenant?: string; roles?: string[]; partition?: string },
+  opts: { name: string; input?: JsonValue; tenant?: string; roles?: string[]; partition?: string },
 ): Promise<Response> {
   const tenant = opts.tenant ?? "main";
   const partition = opts.partition ?? DEFAULT_PARTITION;
@@ -235,7 +242,8 @@ export function makeWorker(app: PramenApp) {
     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 as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver), mail: createMail(env as unknown as Record<string, unknown>, kv), queue: createQueue(env as unknown as Record<string, unknown>) };
+    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
@@ -281,7 +289,7 @@ export function makeWorker(app: PramenApp) {
     for (const r of app.routes ?? []) {
       if (request.method === r.method && url.pathname === r.path) {
         const routeCtx = { callPrivileged: (opts: Parameters<typeof callPrivileged>[1]) => callPrivileged(env, opts) };
-        return r.handler(request, env as unknown as Record<string, unknown>, routeCtx);
+        return r.handler(request, envBag(env), routeCtx);
       }
     }
 
@@ -473,8 +481,9 @@ export function makeWorker(app: PramenApp) {
       }
       // (isLive is excluded by useD1Store — live always routes to the DO below.)
       const name = url.pathname.replace(/^\/rpc\//, "");
-      let input: unknown;
-      if (request.method === "POST") input = await request.json().catch(() => undefined);
+      // 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(() => null)) ?? null) as JsonValue;
 
       // 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
@@ -489,10 +498,10 @@ export function makeWorker(app: PramenApp) {
 
       const driver = new D1Driver(env.DB, { start });
       const files = createFiles({ tenant, secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
-      const envBag = env as unknown as Record<string, unknown>;
+      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
@@ -567,13 +576,13 @@ export function makeWorker(app: PramenApp) {
     // 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: QueueBatch, env: Env): Promise<void> {
-      const envBag = env as unknown as Record<string, unknown>;
+      const bag = envBag(env);
       const kv = new Kv(env.KV);
       const ctx: QueueContext = {
-        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);