@pramen/server 0.0.48 → 0.0.50

package/src/runtime/acl.ts

@@ -15,6 +15,8 @@ import {
   type ResolverDb,
   type Role,
   type Validator,
+  type WhereRule,
+  type WhereValue,
   deny,
   isAllow,
   isDeny,
@@ -25,7 +27,8 @@ import {
 } from "../sdk/acl";
 import { and, compileWhere, evalExpr, FALSE, not, or, TRUE, type SqlExpr } from "./read-engine";
 import { BadRequest, PramenError } from "./errors";
-import type { FieldDef, RelationDef, SchemaDef } from "../sdk/schema";
+import type { CellValue, Row } from "../sdk/infer";
+import type { FieldDef, RelationDef, RelationDefs, SchemaDef } from "../sdk/schema";
 
 export class AclDenied extends PramenError {
   constructor(
@@ -61,6 +64,14 @@ export interface AclContext {
   /** The app schema — lets `where` rules traverse relations (`{ rel: { col } }`),
    * compiled to a subquery with the related entity's read scope AND-merged in. */
   readonly schema?: SchemaDef;
+  /** The tenant this request is for — the `x-pramen-tenant` value the DO was addressed
+   * with. Carried so a handler can mint a tenant-scoped capability (e.g. a signed page
+   * preview link) without the caller supplying, and thus being able to forge, a tenant. */
+  readonly tenant?: string;
+  /** Which substrate is serving this request — `"do"` (a Durable Object, the default) or
+   * `"d1"` (the shared D1 database, selected per-request with `x-pramen-store: d1`). A
+   * handler needs this when a capability it mints can only be redeemed on one of them. */
+  readonly store?: "do" | "d1";
   /** The partition this DO serves. When set, Db rejects any access to a table that
    * lives in a different partition (a partition-DO only owns its own tables). Unset
    * (e.g. the D1/Worker shared-store path) disables the guard — a no-op. */
@@ -150,7 +161,7 @@ function grantOf(rule: PolicyRules | RelationAclRule, where: SqlExpr | null, ent
     conditional: (rule.conditionalFields ?? []).map((cf) => ({
       // Cell-level `when` is evaluated per-row in memory (evalExpr), so it must stay
       // single-table — `allowRelations: false` rejects a relation key up front.
-      when: compileScopedWhere(cf.when as Record<string, unknown>, entity, ctx, depth, false),
+      when: compileScopedWhere(cf.when as WhereRule, entity, ctx, depth, false),
       fields: cf.fields,
     })),
     fieldsFns: rule.fieldsFn ? [rule.fieldsFn] : [],
@@ -168,7 +179,7 @@ function rolesOf(identity: Identity | null): string[] {
 }
 
 function getPath(obj: unknown, path: string): unknown {
-  return path.split(".").reduce<unknown>((acc, seg) => (acc == null ? undefined : (acc as Record<string, unknown>)[seg]), obj ?? undefined);
+  return path.split(".").reduce<unknown>((acc, seg) => (acc == null ? undefined : (acc as WhereRule)[seg]), obj ?? undefined);
 }
 
 const UNRESOLVED = Symbol("unresolved");
@@ -177,15 +188,18 @@ const UNRESOLVED = Symbol("unresolved");
 // $input marker (against the request input — a capability/by-key grant), or a
 // $now marker (the evaluation instant). An unresolvable marker yields UNRESOLVED,
 // which makes its rule match nothing. $now always resolves.
-function resolveValue(v: unknown, identity: Identity | null, input: unknown): unknown {
+/** A resolved where value, or the sentinel meaning "this marker could not resolve". */
+type ResolvedWhereValue = WhereValue | typeof UNRESOLVED;
+
+function resolveValue(v: WhereValue, identity: Identity | null, input: unknown): ResolvedWhereValue {
   if (isNowMarker(v)) return new Date().toISOString();
   if (isIdentityMarker(v)) {
     const value = getPath(identity, v.path);
-    return value === undefined ? UNRESOLVED : value;
+    return value === undefined ? UNRESOLVED : (value as WhereValue);
   }
   if (isInputMarker(v)) {
     const value = getPath(input, v.path);
-    return value === undefined ? UNRESOLVED : value;
+    return value === undefined ? UNRESOLVED : (value as WhereValue);
   }
   return v;
 }
@@ -199,22 +213,22 @@ function resolveValue(v: unknown, identity: Identity | null, input: unknown): un
 // whole rule — so `OR: [{ x: $identity(...) }, { public: true }]` still matches
 // the `public` branch for a caller whose marker can't resolve. (See the comment
 // on `compileScopedWhere`.)
-function resolveMarkers(rule: Record<string, unknown>, identity: Identity | null, input: unknown): Record<string, unknown> | null {
-  const out: Record<string, unknown> = {};
+function resolveMarkers(rule: WhereRule, identity: Identity | null, input: unknown): WhereRule | null {
+  const out: WhereRule = {};
   for (const [key, v] of Object.entries(rule)) {
     const isMarker = isIdentityMarker(v) || isInputMarker(v) || isNowMarker(v);
     if (v !== null && typeof v === "object" && !isMarker && !Array.isArray(v)) {
-      const ops: Record<string, unknown> = {};
-      for (const [op, val] of Object.entries(v as Record<string, unknown>)) {
+      const ops: WhereRule = {};
+      for (const [op, val] of Object.entries(v as WhereRule)) {
         if (op === "in" || op === "notIn") {
-          let arr: unknown;
+          let arr: ResolvedWhereValue;
           if (isIdentityMarker(val) || isInputMarker(val)) {
             arr = resolveValue(val, identity, input);
             if (arr === UNRESOLVED) return null;
           } else {
-            const mapped = (val as unknown[]).map((x) => resolveValue(x, identity, input));
+            const mapped = (val as WhereValue[]).map((x) => resolveValue(x, identity, input));
             if (mapped.some((x) => x === UNRESOLVED)) return null;
-            arr = mapped;
+            arr = mapped as WhereValue[];
           }
           if (!Array.isArray(arr)) return null; // marker must resolve to a list
           ops[op] = arr;
@@ -258,13 +272,13 @@ function pkOf(schema: SchemaDef | undefined, entity: string): string {
  * unreadable column is LIKE-oracle'able through the subquery). Nested relation keys
  * are skipped: they're re-scoped against THEIR own target's read scope downstream.
  * Mirrors Db.assertReadableWhere's recursion for the top-level user `where`. */
-function assertReadableRelationWhere(where: Record<string, unknown>, target: string, fields: string[], ctx: AclContext): void {
-  const targetRels = (ctx.schema?.[target]?.relations ?? {}) as Record<string, unknown>;
+function assertReadableRelationWhere(where: WhereRule, target: string, fields: string[], ctx: AclContext): void {
+  const targetRels: RelationDefs = ctx.schema?.[target]?.relations ?? {};
   for (const [k, v] of Object.entries(where)) {
     if (k === "AND" || k === "OR") {
-      for (const g of v as Record<string, unknown>[]) assertReadableRelationWhere(g, target, fields, ctx);
+      for (const g of v as WhereRule[]) assertReadableRelationWhere(g, target, fields, ctx);
     } else if (k === "NOT") {
-      assertReadableRelationWhere(v as Record<string, unknown>, target, fields, ctx);
+      assertReadableRelationWhere(v as WhereRule, target, fields, ctx);
     } else if (targetRels[k]) {
       continue;
     } else if (!fields.includes(k)) {
@@ -281,7 +295,7 @@ function relationPredicate(rel: RelationDef, nested: unknown, parentEntity: stri
   if (nested === null || typeof nested !== "object" || Array.isArray(nested)) {
     throw new BadRequest(`relation filter for '${rel.target}' must be an object`);
   }
-  let inner = compileScopedWhere(nested as Record<string, unknown>, rel.target, ctx, depth + 1);
+  let inner = compileScopedWhere(nested as WhereRule, rel.target, ctx, depth + 1);
 
   // Security: a relation filter must respect the target's read ACL (else it leaks).
   // Two distinct "no" outcomes, matching how the rest of the read path behaves:
@@ -297,7 +311,7 @@ function relationPredicate(rel: RelationDef, nested: unknown, parentEntity: stri
       inner = FALSE; // can't filter through a relation you can't read
     } else {
       if (tScope.fields !== null) {
-        assertReadableRelationWhere(nested as Record<string, unknown>, rel.target, tScope.fields, ctx);
+        assertReadableRelationWhere(nested as WhereRule, rel.target, tScope.fields, ctx);
       }
       if (tScope.where) inner = and(inner, tScope.where);
     }
@@ -336,7 +350,7 @@ function relationPredicate(rel: RelationDef, nested: unknown, parentEntity: stri
  * evaluated in memory and cannot do a SQL round-trip): a relation key then raises a
  * clear authoring error instead of emitting a `sub` node that throws at read time. */
 export function compileScopedWhere(
-  rule: Record<string, unknown>,
+  rule: WhereRule,
   entity: string,
   ctx: AclContext,
   depth = 0,
@@ -344,13 +358,13 @@ export function compileScopedWhere(
 ): SqlExpr {
   const relations = (ctx.schema?.[entity]?.relations ?? {}) as Record<string, RelationDef>;
   const parts: SqlExpr[] = [];
-  const plain: Record<string, unknown> = {};
+  const plain: WhereRule = {};
   for (const [k, v] of Object.entries(rule)) {
     if (k === "AND" || k === "OR") {
-      const groups = (v as Record<string, unknown>[]).map((g) => compileScopedWhere(g, entity, ctx, depth, allowRelations));
+      const groups = (v as WhereRule[]).map((g) => compileScopedWhere(g, entity, ctx, depth, allowRelations));
       parts.push(k === "AND" ? and(...groups) : or(...groups));
     } else if (k === "NOT") {
-      parts.push(not(compileScopedWhere(v as Record<string, unknown>, entity, ctx, depth, allowRelations)));
+      parts.push(not(compileScopedWhere(v as WhereRule, entity, ctx, depth, allowRelations)));
     } else if (relations[k]) {
       if (!allowRelations) {
         throw new BadRequest(`cell-level \`when\` cannot traverse relations: '${k}' (relations need a SQL round-trip)`);
@@ -420,7 +434,7 @@ export function resolveScope(ctx: AclContext, entity: string, action: Action, de
     if (isDeny(rule)) continue;
     if (isAllow(rule)) grants.push(ALLOW_GRANT);
     else {
-      const where = compileScopedWhere((rule.where ?? {}) as Record<string, unknown>, entity, ctx, depth);
+      const where = compileScopedWhere((rule.where ?? {}) as WhereRule, entity, ctx, depth);
       grants.push(grantOf(rule, where, entity, ctx, depth));
     }
   }
@@ -431,7 +445,7 @@ export function resolveScope(ctx: AclContext, entity: string, action: Action, de
  * Returns null (all fields) when the base is null or a resolver grants everything. */
 export function effectiveFields(
   scope: Scope,
-  row: Record<string, unknown>,
+  row: Row,
   identity: Identity | null,
 ): string[] | null {
   if (scope.fields === null) return null;
@@ -448,18 +462,18 @@ export function effectiveFields(
 /** Forced values + validators for a write, gathered from matched write policies.
  * `set` values are resolved against the identity; later policies override earlier. */
 export interface WriteRules {
-  set: Record<string, unknown>;
+  set: Row;
   validators: Validator[];
 }
 
 export function resolveWriteRules(ctx: AclContext, entity: string, action: Action): WriteRules {
-  const set: Record<string, unknown> = {};
+  const set: Row = {};
   const validators: Validator[] = [];
   for (const rule of matchedRules(ctx, entity, action)) {
     if (isAllow(rule) || isDeny(rule)) continue;
     if (rule.set) {
       for (const [col, v] of Object.entries(rule.set)) {
-        set[col] = typeof v === "function" ? (v as (i: Identity | null) => unknown)(ctx.identity) : v;
+        set[col] = typeof v === "function" ? (v as (i: Identity | null) => CellValue)(ctx.identity) : v;
       }
     }
     if (rule.validate) validators.push(rule.validate);
@@ -487,7 +501,7 @@ export function resolveRelationScope(
     if (isAllow(rule) || isDeny(rule)) continue;
     const rel = rule.relations?.[relName];
     if (rel?.directAccess) {
-      const relWhere = rel.where ? compileScopedWhere(rel.where as Record<string, unknown>, target, ctx, 0) : null;
+      const relWhere = rel.where ? compileScopedWhere(rel.where as WhereRule, target, ctx, 0) : null;
       grants.push(grantOf(rel, relWhere, target, ctx, 0));
     }
   }
@@ -496,9 +510,9 @@ export function resolveRelationScope(
 }
 
 /** Project a row to the permitted fields. null = all. */
-export function projectRow(row: Record<string, unknown>, fields: string[] | null): Record<string, unknown> {
+export function projectRow(row: Row, fields: string[] | null): Row {
   if (!fields) return row;
-  const out: Record<string, unknown> = {};
+  const out: Row = {};
   for (const f of fields) if (f in row) out[f] = row[f];
   return out;
 }

package/src/runtime/db.ts

@@ -24,6 +24,8 @@ import {
   type Scope,
 } from "./acl";
 import type { Validator } from "../sdk/acl";
+import type { CellValue, Row as SharedRow } from "../sdk/infer";
+import type { WhereRule } from "../sdk/acl";
 import {
   and,
   cmp,
@@ -48,7 +50,7 @@ import { partitionOf, triggersOf, triggerFires, type EntityFields, type FieldDef
 import { isValidUuid } from "../sdk/uuid";
 import type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, RelationsOf, RelationsResult, WhereClause } from "../sdk/infer";
 
-type Row = Record<string, unknown>;
+type Row = SharedRow;
 type Action = "read" | "create" | "update" | "delete";
 type Id = string | number | bigint;
 type Selected = Partial<Record<string, true>> | undefined;
@@ -174,7 +176,7 @@ function encodeCursor(order: OrderBy[], row: Row): string {
   return btoa(JSON.stringify(vals)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 
-function decodeCursor(s: string): unknown[] {
+function decodeCursor(s: string): CellValue[] {
   try {
     const arr = JSON.parse(atob(s.replace(/-/g, "+").replace(/_/g, "/")));
     if (!Array.isArray(arr)) throw new Error("not an array");
@@ -191,7 +193,7 @@ function decodeCursor(s: string): unknown[] {
 //         v non-null-> col > v (NULL cols excluded, they sort before)
 //   DESC: v null    -> nothing is strictly after a null    (FALSE; PK tiebreak advances)
 //         v non-null-> col < v OR col IS NULL (nulls sort after all non-nulls)
-function keysetCmp(o: OrderBy, value: unknown): SqlExpr {
+function keysetCmp(o: OrderBy, value: CellValue): SqlExpr {
   const desc = o.dir === "desc";
   if (value === null) return desc ? FALSE : isNull(o.column, true);
   return desc ? or(cmp("<", o.column, value), isNull(o.column)) : cmp(">", o.column, value);
@@ -200,7 +202,7 @@ function keysetCmp(o: OrderBy, value: unknown): SqlExpr {
 // Strictly-after predicate for a composite key: lexicographic comparison,
 // e.g. (a,b) after (a0,b0) => a>a0 OR (a=a0 AND b>b0); DESC columns flip to <. Each
 // column's comparison and the eq-tiebreaker are NULL-aware (eq() maps null→IS NULL).
-function keysetAfter(order: OrderBy[], values: unknown[]): SqlExpr {
+function keysetAfter(order: OrderBy[], values: CellValue[]): SqlExpr {
   const ors: SqlExpr[] = [];
   for (let i = 0; i < order.length; i++) {
     const parts: SqlExpr[] = [];
@@ -433,7 +435,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
     // Compiles the user's where relation-aware (relation keys → security-scoped
     // subqueries), then AND-merges the entity's own ACL row scope.
     if (userWhere) this.assertReadableWhere(from, scope, userWhere);
-    const userExpr: SqlExpr = userWhere ? compileScopedWhere(userWhere as Record<string, unknown>, from, this.acl) : TRUE;
+    const userExpr: SqlExpr = userWhere ? compileScopedWhere(userWhere as WhereRule, from, this.acl) : TRUE;
     const where = scope.where ? and(userExpr, scope.where) : userExpr;
     // A relation-traversal `where` (or a relation-traversing ACL scope) compiles to a
     // `sub` node over another table. Record those tables in `touched` so the live-query
@@ -473,7 +475,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
     const relations = this.schema[from]?.relations ?? {};
     for (const [k, v] of Object.entries(where as Record<string, unknown>)) {
       if (k === "AND" || k === "OR") {
-        for (const g of v as unknown[]) this.assertReadableWhere(from, scope, g);
+        for (const g of v as WhereRule[]) this.assertReadableWhere(from, scope, g);
       } else if (k === "NOT") {
         this.assertReadableWhere(from, scope, v);
       } else if (relations[k]) {
@@ -706,7 +708,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
   }
 
   /** Encode one write cell: JSON-stringify a json/fileRef value, then dialect-encode. */
-  private encodeCell(jsonCols: Set<string>, col: string, v: unknown): unknown {
+  private encodeCell(jsonCols: Set<string>, col: string, v: CellValue): CellValue {
     if (v != null && jsonCols.has(col)) return this.dialect.encode(JSON.stringify(v));
     return this.dialect.encode(v);
   }
@@ -767,7 +769,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
     const project = (row: Row): Row => this.stripHidden(rel.target, projectRow(row, effectiveFields(scope, row, this.acl.identity)));
     // One IN query per relation (no N+1). Match column before projecting (which
     // may drop the join column).
-    const fetchBy = async (col: string, values: unknown[]): Promise<Array<{ key: unknown; row: Row }>> => {
+    const fetchBy = async (col: string, values: CellValue[]): Promise<Array<{ key: CellValue; row: Row }>> => {
       if (values.length === 0) return [];
       const where = scope.where ? and(inList(col, values), scope.where) : inList(col, values);
       // Project the target to its readable columns (+ the join `col`, matched before
@@ -920,7 +922,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
     this.runValidators(validators, p);
     this.assertValidUuids(table, p);
 
-    const params: unknown[] = [];
+    const params: CellValue[] = [];
     const jsonCols = new Set(this.jsonColsOf(table));
     const assignments = cols
       .map((c) => {
@@ -943,7 +945,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
     this.assertInPartition(table);
     const scope = this.scopeFor(table, "delete");
     if (!scope.allowed) throw new AclDenied(table, "delete");
-    const params: unknown[] = [this.dialect.encode(id)];
+    const params: CellValue[] = [this.dialect.encode(id)];
     let sql = `DELETE FROM ${this.dialect.id(table)} WHERE ${this.dialect.id(this.pkOf(table))} = ${this.dialect.placeholder(1)}`;
     sql += this.scopeClause(scope.where, params);
     sql += this.returningClause("*");
@@ -953,7 +955,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
   }
 
   /** Escape hatch — raw SQL, NOT ACL-checked. For system/internal use only. */
-  async exec(sql: string, ...params: unknown[]): Promise<Row[]> {
+  async exec(sql: string, ...params: CellValue[]): Promise<Row[]> {
     return this.driver.exec(sql, params.map((p) => this.dialect.encode(p)));
   }
 
@@ -963,7 +965,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
     return this.dialect.returning ? ` RETURNING ${cols}` : "";
   }
 
-  private scopeClause(where: SqlExpr | null, params: unknown[]): string {
+  private scopeClause(where: SqlExpr | null, params: CellValue[]): string {
     if (!where) return "";
     const compiled = compileExpr(where, this.dialect, params);
     return compiled.sql === "1" ? "" : ` AND (${compiled.sql})`;

package/src/runtime/dev-token.ts

@@ -0,0 +1,36 @@
+// Mint an HS256 JWT for local development and tooling — what a real auth service would
+// issue, without running one.
+//
+// Extracted because it was already written twice (the `pramen` CLI and the repo's test
+// helper) and `@pramen/cms`'s own bin would have been a third. One implementation, in the
+// package that owns tokens.
+//
+// NOT an auth system: the dev fallback secret is public, so a token signed with it is
+// worthless anywhere `AUTH_SECRET` is set to something real. That is the point — it makes
+// a forgotten secret fail loudly rather than quietly accept dev tokens in production.
+
+/** The scaffolded oblaka.ts dev secret. Used only when AUTH_SECRET is unset. */
+export const DEV_SECRET = "dev-secret-change-me";
+
+function bytesToB64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+const strToB64url = (s: string): string => bytesToB64url(new TextEncoder().encode(s));
+
+/** Sign a dev JWT (1h). Secret: the `secret` argument, else `AUTH_SECRET`, else DEV_SECRET. */
+export async function signDevToken(payload: Record<string, unknown>, secret?: string): Promise<string> {
+  // `||`, not `??`: an AUTH_SECRET set to the empty string previously fell through to
+  // DEV_SECRET, and signing with an empty HMAC key instead would produce tokens the server
+  // rejects with no useful message.
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;
+  const key = secret || env?.AUTH_SECRET || DEV_SECRET;
+  const now = Math.floor(Date.now() / 1000);
+  const header = strToB64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+  const body = strToB64url(JSON.stringify({ iat: now, exp: now + 3600, ...payload }));
+  const data = `${header}.${body}`;
+  const cryptoKey = await crypto.subtle.importKey("raw", new TextEncoder().encode(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const sig = await crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(data));
+  return `${data}.${bytesToB64url(new Uint8Array(sig))}`;
+}

package/src/runtime/dispatch.ts

@@ -20,6 +20,8 @@ import type { Files } from "../sdk/files";
 import type { ResolverDb } from "../sdk/acl";
 import type { SchemaDef } from "../sdk/schema";
 import { authorizeHandler, type AppTaskMap, type HandlerContext, type HandlerKind, type HandlerMap, type Tasks } from "../sdk/handlers";
+import type { EnvBag } from "../sdk/handlers";
+import type { JsonValue } from "../sdk/infer";
 
 export interface DispatchResult {
   readonly result: unknown;
@@ -53,10 +55,10 @@ export async function dispatch(
   driver: Driver,
   kv: Kv,
   files: Files,
-  env: Readonly<Record<string, unknown>>,
+  env: EnvBag,
   acl: AclContext,
   name: string,
-  input: unknown,
+  input: JsonValue,
 ): Promise<DispatchResult> {
   const handler = handlers[name];
   if (!handler) throw new BadRequest(`unknown handler: ${name}`);
@@ -68,7 +70,7 @@ export async function dispatch(
   }
 
   // Validate/parse the request input at the boundary, if the handler declares it.
-  let parsed = input;
+  let parsed: unknown = input;
   if (handler.input) {
     try {
       parsed = handler.input(input);
@@ -90,6 +92,8 @@ export async function dispatch(
     files,
     env,
     identity: acl.identity,
+    tenant: acl.tenant ?? "main",
+    store: acl.store ?? "do",
     tasks: tasksFacade(driver, () => enqueued++),
     mail: createMail(env, kv),
     queue: createQueue(env),

package/src/runtime/driver.ts

@@ -11,7 +11,11 @@
 // in a Driver, rather than rewriting the engine. Live queries remain a DO-only
 // capability (they need a single writer + a stateful socket host).
 
-export type Row = Record<string, unknown>;
+/** A raw row exactly as the substrate returns it, before pramen's object↔JSON codec.
+ * Distinct from the decoded `Row` handlers see at the `Db` chokepoint. */
+export type DriverRow = Record<string, SqlValue>;
+
+import type { CellValue, SqlValue } from "../sdk/infer";
 
 export interface Dialect {
   /** Render an identifier (table/column), quoting as the backend requires. */
@@ -21,7 +25,7 @@ export interface Dialect {
   /** Whether INSERT/UPDATE/DELETE ... RETURNING is supported (SQLite/Postgres yes; MySQL no). */
   readonly returning: boolean;
   /** Coerce a JS value for binding (e.g. boolean → 0/1 on SQLite). */
-  encode(v: unknown): unknown;
+  encode(v: CellValue): CellValue;
 }
 
 const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -66,7 +70,7 @@ export interface Driver {
   readonly dialect: Dialect;
   /** Run a parameterized statement and return the result rows (empty for writes
    * without RETURNING). Params are already dialect-encoded by the caller. */
-  exec(sql: string, params: unknown[]): Promise<Row[]>;
+  exec(sql: string, params: CellValue[]): Promise<DriverRow[]>;
   /** Run `fn` inside a transaction: commit on resolve, roll back on throw. */
   transaction<T>(fn: () => Promise<T>): Promise<T>;
   /** Run a fixed sequence of write statements ATOMICALLY with FK checks deferred to the
@@ -83,8 +87,8 @@ export class DoSqliteDriver implements Driver {
   readonly dialect = sqliteDialect;
   constructor(private readonly storage: DurableObjectStorage) {}
 
-  async exec(sql: string, params: unknown[]): Promise<Row[]> {
-    return this.storage.sql.exec(sql, ...params).toArray() as Row[];
+  async exec(sql: string, params: CellValue[]): Promise<DriverRow[]> {
+    return this.storage.sql.exec(sql, ...params).toArray() as DriverRow[];
   }
 
   transaction<T>(fn: () => Promise<T>): Promise<T> {
@@ -124,9 +128,9 @@ export class D1Driver implements Driver {
     this.session = db.withSession(opts?.start ?? "first-unconstrained");
   }
 
-  async exec(sql: string, params: unknown[]): Promise<Row[]> {
+  async exec(sql: string, params: CellValue[]): Promise<DriverRow[]> {
     const stmt = params.length ? this.session.prepare(sql).bind(...params) : this.session.prepare(sql);
-    const { results } = await stmt.all<Row>();
+    const { results } = await stmt.all<DriverRow>();
     return results ?? [];
   }
 

package/src/runtime/errors.ts

@@ -34,6 +34,15 @@ export class Forbidden extends PramenError {
   }
 }
 
+/** 409 — the request conflicts with the current state of the resource. For
+ * optimistic concurrency (a stale `expectedVersion`) and for uniqueness clashes the
+ * caller could resolve by retrying with different input. */
+export class Conflict extends PramenError {
+  constructor(message = "conflict") {
+    super(message, 409, "conflict");
+  }
+}
+
 export interface ErrorBody {
   ok: false;
   error: string;

package/src/runtime/mail.ts

@@ -11,6 +11,7 @@
 // in-memory — so handlers work unchanged off-platform.
 
 import type { Kv } from "./kv";
+import type { EnvBag } from "../sdk/handlers";
 
 export interface MailAddress {
   email: string;
@@ -120,7 +121,7 @@ export class UnconfiguredMailAdapter implements MailAdapter {
  *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
  *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
  *    stash security emails in KV). */
-export function createMail(env: Readonly<Record<string, unknown>>, kv?: Kv): Mail {
+export function createMail(env: EnvBag, kv?: Kv): Mail {
   const binding = env.EMAIL as SendEmailBinding | undefined;
   const fromAddr = typeof env.MAIL_FROM === "string" && env.MAIL_FROM ? env.MAIL_FROM : undefined;
   if (binding && fromAddr) {

package/src/runtime/migrate.ts

@@ -43,6 +43,7 @@ import { digest } from "./digest";
 import { quoteIdent, type Driver } from "./driver";
 import { entitiesInPartition, partitionOf, validateSchema } from "../sdk/schema";
 import type { EntityFields, FieldDef, SchemaDef } from "../sdk/schema";
+import type { CellValue } from "../sdk/infer";
 
 export interface MigrationReport {
   changed: boolean;
@@ -306,7 +307,7 @@ async function rebuildTable(
   // rebuilt table whose FKs momentarily see stale rows), so run the whole sequence
   // ATOMICALLY: the D1 driver's batch() defers FK checks to the batch commit, and on the
   // DO the ambient boot transaction (+ defer set at migrate start) already covers it.
-  const stmts: { sql: string; params: unknown[] }[] = [];
+  const stmts: { sql: string; params: CellValue[] }[] = [];
   // Quarantine tables are bare column lists — untyped, no constraints, no FKs. Values
   // round-trip verbatim (they were already coerced by the original table's affinity).
   const bareCopy = (name: string, quotedCols: string[]): string => `CREATE TABLE ${quoteIdent(name)} (${quotedCols.join(", ")})`;

package/src/runtime/outbox.ts

@@ -19,6 +19,7 @@
 // task `id` as an idempotency key so they can dedupe across the rare retry.
 
 import type { Driver } from "./driver";
+import type { CellValue } from "../sdk/infer";
 
 export const OUTBOX_TABLE = "_pramen_outbox";
 
@@ -34,7 +35,7 @@ function backoffMs(attempts: number): number {
   return Math.min(2 ** attempts * 1000, 5 * 60_000); // 2s, 4s, 8s, … capped at 5min
 }
 
-const enc = (driver: Driver, params: unknown[]): unknown[] => params.map((p) => driver.dialect.encode(p));
+const enc = (driver: Driver, params: CellValue[]): CellValue[] => params.map((p) => driver.dialect.encode(p));
 
 /** Create the outbox table if absent. Idempotent — run on DO boot (and lazily on the
  * D1 path). Internal table (`_pramen_` prefix), never part of the user schema. */

package/src/runtime/protocol.ts

@@ -10,11 +10,13 @@
 //   { type: "result", id, result }   // reply to a one-shot call
 //   { type: "error",  id, error }
 
+import type { JsonValue } from "../sdk/infer";
+
 export interface SubscribeMsg {
   type: "subscribe";
   id: string;
   name: string;
-  input?: unknown;
+  input?: JsonValue;
 }
 export interface UnsubscribeMsg {
   type: "unsubscribe";
@@ -24,7 +26,7 @@ export interface CallMsg {
   type: "call";
   id: string;
   name: string;
-  input?: unknown;
+  input?: JsonValue;
 }
 
 export type ClientMsg = SubscribeMsg | UnsubscribeMsg | CallMsg;
@@ -38,7 +40,7 @@ export type ServerMsg =
 export interface Subscription {
   id: string;
   name: string;
-  input: unknown;
+  input: JsonValue;
   /** Tables the query read — the coarse prefilter for which writes might matter. */
   tables: string[];
   /** Digest of the last result pushed — used to suppress no-op (row-level) pushes. */

package/src/runtime/queue-consumer.ts

@@ -12,6 +12,8 @@
 import type { Mail } from "./mail";
 import type { Queue } from "./queue";
 import type { Kv } from "./kv";
+import type { EnvBag } from "../sdk/handlers";
+import type { JsonValue } from "../sdk/infer";
 
 /** One received message (the Cloudflare Queues `Message` shape). */
 export interface QueueMessage<Body = unknown> {
@@ -40,7 +42,7 @@ export interface QueueBatch<Body = unknown> {
  * tenant data via `ctx.callPrivileged`. */
 export interface QueueContext {
   /** The Worker environment (bindings + vars + secrets). */
-  readonly env: Readonly<Record<string, unknown>>;
+  readonly env: EnvBag;
   /** Project KV (cross-tenant). */
   readonly kv: Kv;
   /** Send email (the notification path). */
@@ -49,7 +51,7 @@ export interface QueueContext {
   readonly queue: Queue;
   /** Apply a privileged mutation into a tenant's DO (the consumer has no direct db).
    * The message body should carry the `tenant`. */
-  callPrivileged(opts: { name: string; input?: unknown; tenant?: string; roles?: string[]; partition?: string }): Promise<Response>;
+  callPrivileged(opts: { name: string; input?: JsonValue; tenant?: string; roles?: string[]; partition?: string }): Promise<Response>;
 }
 
 /** A queue consumer handler — runs once per message. Resolving ACKs the message;

package/src/runtime/queue.ts

@@ -19,6 +19,8 @@
 // that isn't bound FAILS CLOSED (throws) rather than silently dropping the message —
 // mirroring how ctx.mail fails closed without a transport.
 
+import type { EnvBag } from "../sdk/handlers";
+
 /** Cloudflare Queues content type for a sent message. Omitted ⇒ the platform default
  * (v8 structured clone). Use "json" for cross-runtime / external consumers. */
 export type QueueContentType = "text" | "bytes" | "json" | "v8";
@@ -131,7 +133,7 @@ export class MemoryQueueAdapter implements QueueAdapter {
 /** Discover the Cloudflare Queues producer bindings in an environment: any value that
  * exposes BOTH `send` and `sendBatch` functions (which excludes the email `send`-only
  * binding, KV, R2, D1, the DO namespace, …). Returns name → binding. */
-export function discoverQueueBindings(env: Readonly<Record<string, unknown>>): Record<string, QueueProducerBinding> {
+export function discoverQueueBindings(env: EnvBag): Record<string, QueueProducerBinding> {
   const out: Record<string, QueueProducerBinding> = {};
   for (const [name, value] of Object.entries(env)) {
     if (
@@ -150,6 +152,6 @@ export function discoverQueueBindings(env: Readonly<Record<string, unknown>>): R
  * producer bindings. Sending to an undeclared queue fails closed (the adapter throws).
  * There is no silent capture fallback — declare the `Queue` binding and it exists in
  * dev (lopata) and miniflare too. */
-export function createQueue(env: Readonly<Record<string, unknown>>): Queue {
+export function createQueue(env: EnvBag): Queue {
   return new Queue(new CloudflareQueueAdapter(discoverQueueBindings(env)));
 }