@pramen/server 0.0.48 → 0.0.50

package/dist/runtime/read-engine.d.ts

@@ -1,3 +1,5 @@
+import type { WhereRule } from "../sdk/acl";
+import type { CellValue, Row } from "../sdk/infer";
 import type { Dialect } from "./driver";
 export type CmpOp = "=" | "!=" | ">" | ">=" | "<" | "<=" | "LIKE";
 /** Substring match mode for the structured string operators (auto-escaping, so the
@@ -11,11 +13,11 @@ export type SqlExpr = {
     t: "cmp";
     op: CmpOp;
     col: string;
-    value: unknown;
+    value: CellValue;
 } | {
     t: "in";
     col: string;
-    values: unknown[];
+    values: CellValue[];
     negate: boolean;
 } | {
     t: "null";
@@ -45,28 +47,28 @@ export type SqlExpr = {
 };
 export declare const TRUE: SqlExpr;
 export declare const FALSE: SqlExpr;
-export declare const cmp: (op: CmpOp, col: string, value: unknown) => SqlExpr;
+export declare const cmp: (op: CmpOp, col: string, value: CellValue) => SqlExpr;
 export declare const isNull: (col: string, negate?: boolean) => SqlExpr;
-export declare const inList: (col: string, values: unknown[], negate?: boolean) => SqlExpr;
+export declare const inList: (col: string, values: CellValue[], negate?: boolean) => SqlExpr;
 export declare const strMatch: (col: string, needle: string, mode: StrMode) => SqlExpr;
 export declare const and: (...parts: SqlExpr[]) => SqlExpr;
 export declare const or: (...parts: SqlExpr[]) => SqlExpr;
 export declare const not: (expr: SqlExpr) => SqlExpr;
 /** Equality (null -> IS NULL). Used by ACL scope building and relation loads. */
-export declare const eq: (col: string, value: unknown) => SqlExpr;
+export declare const eq: (col: string, value: CellValue) => SqlExpr;
 /** Compile a structured user predicate into a SqlExpr.
  * Shapes: { col: value } (eq) | { col: { gt, lt, in, like, isNull, … } } | { AND: [...] } | { OR: [...] } */
-export declare function compileWhere(input: Record<string, unknown>): SqlExpr;
+export declare function compileWhere(input: WhereRule): SqlExpr;
 export interface CompiledSql {
     readonly sql: string;
-    readonly params: unknown[];
+    readonly params: CellValue[];
 }
-export declare function compileExpr(expr: SqlExpr, dialect: Dialect, params?: unknown[]): CompiledSql;
+export declare function compileExpr(expr: SqlExpr, dialect: Dialect, params?: CellValue[]): CompiledSql;
 /** Evaluate a compiled predicate against an in-memory row. Mirrors compileExpr's
  * 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 declare function evalExpr(expr: SqlExpr, row: Record<string, unknown>): boolean;
+export declare function evalExpr(expr: SqlExpr, row: Row): boolean;
 export interface OrderBy {
     column: string;
     dir?: "asc" | "desc";

package/dist/runtime/read-engine.js

@@ -44,7 +44,10 @@ export function compileWhere(input) {
 function columnPredicate(col, v) {
     if (v !== null && typeof v === "object" && !Array.isArray(v)) {
         const ops = [];
-        for (const [op, val] of Object.entries(v)) {
+        for (const [op, operand] of Object.entries(v)) {
+            // Markers are resolved upstream (runtime/acl.ts), so an operator's operand is a
+            // literal cell value by this point.
+            const val = operand;
             switch (op) {
                 case "eq":
                     ops.push(eq(col, val));

package/dist/runtime/registry.d.ts

@@ -25,4 +25,7 @@ export declare 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 declare 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 declare function listDOs(kv: KvLister): Promise<DoRef[]>;

package/dist/runtime/registry.js

@@ -65,9 +65,6 @@ export function parseRegistryKey(key) {
         return { tenant: rest, partition: DEFAULT_PARTITION };
     return { tenant: rest.slice(0, sep), partition: rest.slice(sep + 1) };
 }
-/** 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) {
     const out = [];
     let cursor;

package/dist/runtime/schema-diff.d.ts

@@ -1,6 +1,6 @@
 import type { SchemaDef } 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;
@@ -11,13 +11,13 @@ export interface ColumnShape {
     default?: string;
 }
 /** 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 declare function schemaShape(schema: SchemaDef): SchemaShape;
+export type SchemaFingerprint = Record<string, TableFingerprint>;
+export declare function schemaFingerprint(schema: SchemaDef): SchemaFingerprint;
 export interface SchemaChange {
     kind: "add-table" | "drop-table" | "add-column" | "drop-column" | "change-type" | "change-column" | "move-partition";
     table: string;
@@ -34,4 +34,4 @@ export interface SchemaChange {
      * cross-DO data migration). Reported for honesty. */
     appliesOnBoot: boolean;
 }
-export declare function diffSchemaShape(prev: SchemaShape, next: SchemaShape): SchemaChange[];
+export declare function diffSchemaFingerprint(prev: SchemaFingerprint, next: SchemaFingerprint): SchemaChange[];

package/dist/runtime/schema-diff.js

@@ -17,7 +17,7 @@
 // still CANNOT be enacted on boot (a partition is a separate Durable Object — it needs a
 // manual cross-DO data migration), so it stays `appliesOnBoot: false`.
 import { partitionOf } from "../sdk/schema";
-function columnShape(f) {
+function columnFingerprint(f) {
     const c = { type: f.type };
     if (f.notNull)
         c.notNull = true;
@@ -35,12 +35,12 @@ function columnShape(f) {
         c.default = JSON.stringify(f.default);
     return c;
 }
-export function schemaShape(schema) {
+export function schemaFingerprint(schema) {
     const out = {};
     for (const [table, def] of Object.entries(schema)) {
         const columns = {};
         for (const [col, f] of Object.entries(def.fields))
-            columns[col] = columnShape(f);
+            columns[col] = columnFingerprint(f);
         out[table] = { partition: partitionOf(schema, table), columns };
     }
     return out;
@@ -64,7 +64,7 @@ function modifierDiff(prev, next) {
 function fmt(v) {
     return v === undefined ? "—" : String(v);
 }
-export function diffSchemaShape(prev, next) {
+export function diffSchemaFingerprint(prev, next) {
     const changes = [];
     for (const table of Object.keys(next)) {
         const pt = prev[table];

package/dist/runtime/storage.d.ts

@@ -1,4 +1,5 @@
 import type { Files, HeadResult } from "../sdk/files";
+import { isUsableSecret, type ExpiringToken } from "./token";
 export type { Files, FileRef, HeadResult, SignDownloadOpts, SignUploadOpts } from "../sdk/files";
 export interface PutResult {
     key: string;
@@ -40,17 +41,16 @@ export declare class MemoryAdapter implements StorageAdapter {
     head(key: string): Promise<HeadResult | null>;
     delete(key: string): Promise<void>;
 }
-interface FileToken {
+interface FileToken extends ExpiringToken {
     /** tenant */ t: string;
     /** key */ k: string;
     /** op */ op: "get" | "put";
-    /** expiry (epoch seconds) */ exp: number;
     /** content-type (put: enforced; get: disposition hint) */ ct?: string;
     /** max size in bytes (put only) */ max?: number;
     /** filename (download disposition) */ fn?: string;
 }
 /** Verify a file token's signature + expiry; returns the payload or null. */
-export declare function verifyToken(raw: string, secret: string): Promise<FileToken | null>;
+export declare const verifyFileToken: (raw: string, secret: string) => Promise<FileToken | null>;
 export interface FilesConfig {
     tenant: string;
     secret: string;
@@ -63,7 +63,7 @@ export interface FilesConfig {
  * treated as unconfigured — fail closed rather than mint forgeable urls. The dev
  * defaults satisfy it; production should set a strong, random FILES_SECRET. */
 export declare const MIN_FILES_SECRET_LEN = 16;
-export declare function isUsableFilesSecret(secret: string | undefined | null): secret is string;
+export declare const isUsableFilesSecret: typeof isUsableSecret;
 /** Construct the per-tenant `ctx.files` facade. */
 export declare function createFiles(cfg: FilesConfig): Files;
 /** Serve the file endpoints. Returns a Response for any `/files/*` path, or null

package/dist/runtime/storage.js

@@ -15,6 +15,7 @@
 // R2 binding and stays backend-agnostic. URLs are RELATIVE so the server never
 // needs to know its own public origin — the client resolves them against its base.
 import { BadRequest, PramenError } from "./errors";
+import { signToken, verifyToken, isUsableSecret, MIN_TOKEN_SECRET_LEN } from "./token";
 /** R2 — the Cloudflare default. Wraps an R2 bucket binding. Streaming: bytes flow
  * directly between the client and R2 in the Worker, never through the DO. */
 export class R2Adapter {
@@ -84,63 +85,9 @@ function bytesToStream(bytes) {
         },
     });
 }
-// --- base64url (shared shape with auth.ts/jwt.ts) ---
-function bytesToB64url(bytes) {
-    let bin = "";
-    for (const b of bytes)
-        bin += String.fromCharCode(b);
-    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function b64urlToBytes(s) {
-    const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (s.length % 4)) % 4);
-    const bin = atob(b64);
-    const out = new Uint8Array(bin.length);
-    for (let i = 0; i < bin.length; i++)
-        out[i] = bin.charCodeAt(i);
-    return out;
-}
-const strToB64url = (s) => bytesToB64url(new TextEncoder().encode(s));
-const b64urlToStr = (s) => new TextDecoder().decode(b64urlToBytes(s));
-async function hmacKey(secret) {
-    return crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
-        "sign",
-        "verify",
-    ]);
-}
-async function signToken(token, secret) {
-    const data = strToB64url(JSON.stringify(token));
-    const key = await hmacKey(secret);
-    const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
-    return `${data}.${bytesToB64url(new Uint8Array(sig))}`;
-}
+const signFileToken = (token, secret) => signToken(token, secret);
 /** Verify a file token's signature + expiry; returns the payload or null. */
-export async function verifyToken(raw, secret) {
-    const dot = raw.indexOf(".");
-    if (dot < 0)
-        return null;
-    const data = raw.slice(0, dot);
-    const sig = raw.slice(dot + 1);
-    let ok;
-    try {
-        const key = await hmacKey(secret);
-        ok = await crypto.subtle.verify("HMAC", key, b64urlToBytes(sig), new TextEncoder().encode(data));
-    }
-    catch {
-        return null;
-    }
-    if (!ok)
-        return null;
-    let payload;
-    try {
-        payload = JSON.parse(b64urlToStr(data));
-    }
-    catch {
-        return null;
-    }
-    if (typeof payload.exp !== "number" || Math.floor(Date.now() / 1000) >= payload.exp)
-        return null;
-    return payload;
-}
+export const verifyFileToken = (raw, secret) => verifyToken(raw, secret);
 // --- key generation ---
 function randomKeySuffix() {
     const bytes = new Uint8Array(16);
@@ -188,10 +135,8 @@ function contentDisposition(name) {
  * would be forgeable (HMAC over an empty/weak key). Below this, file storage is
  * treated as unconfigured — fail closed rather than mint forgeable urls. The dev
  * defaults satisfy it; production should set a strong, random FILES_SECRET. */
-export const MIN_FILES_SECRET_LEN = 16;
-export function isUsableFilesSecret(secret) {
-    return typeof secret === "string" && secret.length >= MIN_FILES_SECRET_LEN;
-}
+export const MIN_FILES_SECRET_LEN = MIN_TOKEN_SECRET_LEN;
+export const isUsableFilesSecret = isUsableSecret;
 const filesUnconfigured = () => new PramenError("file storage is not configured (set a strong FILES_SECRET)", 503, "unavailable");
 /** Construct the per-tenant `ctx.files` facade. */
 export function createFiles(cfg) {
@@ -210,7 +155,7 @@ export function createFiles(cfg) {
             const seg = opts.prefix ? `${safePrefix(opts.prefix)}/` : "";
             const key = `${prefix}${seg}${randomKeySuffix()}`;
             const exp = Math.floor(Date.now() / 1000) + (opts.expiresIn ?? 900);
-            const token = await signToken({ t: cfg.tenant, k: key, op: "put", exp, ct, max: opts.maxSize, fn: opts.filename }, cfg.secret);
+            const token = await signFileToken({ t: cfg.tenant, k: key, op: "put", exp, ct, max: opts.maxSize, fn: opts.filename }, cfg.secret);
             const ref = { key, size: 0, contentType: ct, filename: opts.filename, uploadedAt: Date.now() };
             return { url: `${base}/upload?token=${encodeURIComponent(token)}`, ref };
         },
@@ -221,7 +166,7 @@ export function createFiles(cfg) {
             const key = ensureOwnKey(r.key);
             const exp = Math.floor(Date.now() / 1000) + (opts?.expiresIn ?? 3600);
             const fn = opts?.download ? (typeof ref === "string" ? undefined : ref.filename) : undefined;
-            const token = await signToken({ t: cfg.tenant, k: key, op: "get", exp, fn }, cfg.secret);
+            const token = await signFileToken({ t: cfg.tenant, k: key, op: "get", exp, fn }, cfg.secret);
             return { url: `${base}/download?token=${encodeURIComponent(token)}`, expiresAt: exp * 1000 };
         },
         head: (key) => cfg.adapter.head(ensureOwnKey(key)),
@@ -258,7 +203,7 @@ export async function handleFileRequest(request, opts) {
     const raw = url.searchParams.get("token");
     if (!raw)
         return fileError(401, "unauthorized", "missing token");
-    const token = await verifyToken(raw, opts.secret);
+    const token = await verifyFileToken(raw, opts.secret);
     if (!token)
         return fileError(403, "forbidden", "invalid or expired token");
     try {

package/dist/runtime/token.d.ts

@@ -0,0 +1,22 @@
+/** Every signed token carries an expiry (epoch seconds); `verifyToken` enforces it. */
+export interface ExpiringToken {
+    exp: number;
+}
+export declare function bytesToB64url(bytes: Uint8Array): string;
+export declare function b64urlToBytes(s: string): Uint8Array;
+export declare const strToB64url: (s: string) => string;
+export declare const b64urlToStr: (s: string) => string;
+/** Sign a payload into a capability token. */
+export declare function signToken<T extends ExpiringToken>(payload: T, secret: string): Promise<string>;
+/** Verify a token's signature and expiry; returns the payload, or `null` for anything
+ * malformed, forged, or expired. The caller decides what the payload authorizes — this
+ * only attests that we minted it and that it is still in date. */
+export declare function verifyToken<T extends ExpiringToken>(raw: string, secret: string): Promise<T | null>;
+/** A signing secret must be present and non-trivial, else tokens are forgeable (an HMAC
+ * over an empty or weak key). Below this length the feature is treated as UNCONFIGURED and
+ * fails closed, rather than minting urls that anyone can forge. */
+export declare const MIN_TOKEN_SECRET_LEN = 16;
+export declare function isUsableSecret(secret: unknown): secret is string;
+/** Resolve a signing secret from env by preference order, skipping any that is absent or
+ * too weak. Returns `undefined` when nothing usable is configured — callers fail closed. */
+export declare function resolveSecret(env: Readonly<Record<string, unknown>>, names: readonly string[]): string | undefined;

package/dist/runtime/token.js

@@ -0,0 +1,88 @@
+// Signed, self-expiring capability tokens (HMAC-SHA256 over a JSON payload).
+//
+// pramen already owns the edge and a secret, so a capability url needs no session and no
+// store: the payload IS the grant, and the signature is what makes it unforgeable. Signed
+// file urls were the first user (`runtime/storage.ts`); page preview links are the second
+// (`@pramen/cms`). Both mint in a handler and redeem in the Worker, unauthenticated.
+//
+// Pure WebCrypto — synchronous in the sense that matters (no stream I/O), so it is safe to
+// call from inside the DO's storage.transaction().
+//
+// A token is `<b64url(json)>.<b64url(sig)>`. It is deliberately NOT a JWT: no alg field to
+// confuse, no header to downgrade, one algorithm, verified before the payload is parsed.
+export function bytesToB64url(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function b64urlToBytes(s) {
+    const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (s.length % 4)) % 4);
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+export const strToB64url = (s) => bytesToB64url(new TextEncoder().encode(s));
+export const b64urlToStr = (s) => new TextDecoder().decode(b64urlToBytes(s));
+async function hmacKey(secret) {
+    return crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+        "sign",
+        "verify",
+    ]);
+}
+/** Sign a payload into a capability token. */
+export async function signToken(payload, secret) {
+    const data = strToB64url(JSON.stringify(payload));
+    const key = await hmacKey(secret);
+    const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
+    return `${data}.${bytesToB64url(new Uint8Array(sig))}`;
+}
+/** Verify a token's signature and expiry; returns the payload, or `null` for anything
+ * malformed, forged, or expired. The caller decides what the payload authorizes — this
+ * only attests that we minted it and that it is still in date. */
+export async function verifyToken(raw, secret) {
+    const dot = raw.indexOf(".");
+    if (dot < 0)
+        return null;
+    const data = raw.slice(0, dot);
+    const sig = raw.slice(dot + 1);
+    let ok;
+    try {
+        const key = await hmacKey(secret);
+        ok = await crypto.subtle.verify("HMAC", key, b64urlToBytes(sig), new TextEncoder().encode(data));
+    }
+    catch {
+        return null;
+    }
+    if (!ok)
+        return null;
+    let payload;
+    try {
+        payload = JSON.parse(b64urlToStr(data));
+    }
+    catch {
+        return null;
+    }
+    if (typeof payload.exp !== "number" || Math.floor(Date.now() / 1000) >= payload.exp)
+        return null;
+    return payload;
+}
+/** A signing secret must be present and non-trivial, else tokens are forgeable (an HMAC
+ * over an empty or weak key). Below this length the feature is treated as UNCONFIGURED and
+ * fails closed, rather than minting urls that anyone can forge. */
+export const MIN_TOKEN_SECRET_LEN = 16;
+export function isUsableSecret(secret) {
+    return typeof secret === "string" && secret.length >= MIN_TOKEN_SECRET_LEN;
+}
+/** Resolve a signing secret from env by preference order, skipping any that is absent or
+ * too weak. Returns `undefined` when nothing usable is configured — callers fail closed. */
+export function resolveSecret(env, names) {
+    for (const name of names) {
+        const v = env[name];
+        if (isUsableSecret(v))
+            return v;
+    }
+    return undefined;
+}

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,9 +31,16 @@ 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;
+    /** The tenant this request is for (the `x-pramen-tenant` value; `"main"` by default).
+     * Server-resolved, never caller-supplied — safe to embed in a signed capability. */
+    readonly tenant: string;
+    /** Which substrate is serving this request: `"do"` (a Durable Object) or `"d1"`. Only
+     * the DO path has a stub the Worker can call back into, so a handler minting a
+     * capability redeemed through `callPrivileged` must refuse on `"d1"`. */
+    readonly store: "do" | "d1";
     /** Deferred side-effects (a transactional outbox). `tasks.enqueue` persists a task
      * row in the SAME transaction as a mutation (atomic with the data write); a drainer
      * runs the matching `app.tasks` handler after commit, off the write path, with
@@ -100,7 +113,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 +122,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;