@cfast/permissions 0.2.0 → 0.4.0

package/dist/{chunk-NCLN5YBQ.js → chunk-ISTOPBSB.js}

@@ -49,9 +49,26 @@ var ForbiddenError = class extends Error {
     };
   }
 };
+var PermissionRegistrationError = class extends Error {
+  /** The unresolved subject string that was passed to `grant()`. */
+  subject;
+  /** The available table names (both JS keys and SQL names) from the schema. */
+  availableTables;
+  constructor(subject, availableTables) {
+    const sorted = [...availableTables].sort();
+    const list = sorted.length === 0 ? "<empty schema>" : sorted.map((n) => `"${n}"`).join(", ");
+    super(
+      `grant() subject "${subject}" does not match any table in the schema. Available tables (by JS key and SQL name): ${list}. Did you forget to pass the schema as the second generic to definePermissions<User, typeof schema>()?`
+    );
+    this.name = "PermissionRegistrationError";
+    this.subject = subject;
+    this.availableTables = sorted;
+  }
+};
 
 export {
   getTableName,
   CRUD_ACTIONS,
-  ForbiddenError
+  ForbiddenError,
+  PermissionRegistrationError
 };

package/dist/{client-C7xdwHTk.d.ts → client-D6goQV8b.d.ts}

@@ -17,27 +17,61 @@ type DrizzleSQL = {
     getSQL(): unknown;
 };
 /**
- * A schema map: an object mapping table names to Drizzle table references.
+ * A schema map: an object mapping JS schema keys to Drizzle table references.
  *
  * Typically the result of `import * as schema from "./schema"`. Used as the
  * `TTables` generic parameter for {@link definePermissions}, {@link can}, and
  * the curried {@link grant} callback so that string subjects (e.g.
- * `"projects"`) are constrained to known table names at compile time.
+ * `"projects"` or `"project_versions"`) are constrained to known table names
+ * at compile time.
  */
 type SchemaMap = Record<string, DrizzleTable>;
 /**
- * Extracts the string-literal union of valid table names from a {@link SchemaMap}.
+ * Structural shape of a Drizzle table's static metadata used purely for
+ * type-level SQL-name extraction.
  *
- * Given `typeof schema` (where `schema` exports tables as named bindings),
- * `TableName<typeof schema>` is the union of all exported table-key strings.
+ * Drizzle tables expose their SQL name on a readonly `_.name` field (see
+ * `drizzle-orm/table` `Table._.name`). By narrowing against this shape we can
+ * extract `"project_versions"` from `typeof projectVersions` even though the
+ * runtime value lives on a `Symbol.for("drizzle:Name")` key.
  */
-type TableName<TTables extends SchemaMap> = Extract<keyof TTables, string>;
+type TableWithSqlName = {
+    _: {
+        name: string;
+    };
+};
+/**
+ * Extracts the SQL table name literal from a Drizzle table reference, or
+ * `never` when the argument is not a Drizzle table with a `_.name` field.
+ *
+ * @example
+ * ```ts
+ * const postVersions = sqliteTable("post_versions", { ... });
+ * type N = SqlNameOf<typeof postVersions>; // "post_versions"
+ * ```
+ */
+type SqlNameOf<T> = T extends TableWithSqlName ? T["_"]["name"] extends string ? T["_"]["name"] : never : never;
+/**
+ * Extracts the string-literal union of valid subject keys from a
+ * {@link SchemaMap}, including **both** the JS schema keys (e.g.
+ * `"postVersions"`) and the SQL table names (e.g. `"post_versions"`).
+ *
+ * The runtime side of `definePermissions<User, Schema>()` builds a
+ * matching lookup table keyed by both forms, so the two string forms are
+ * fully interchangeable — whichever matches your mental model.
+ *
+ * Without this, string subjects were accidentally constrained to JS keys
+ * only (#177), causing confusion when a schema's JS key differs from its
+ * SQL table name (e.g. `documentVersions` vs `document_versions`).
+ */
+type TableName<TTables extends SchemaMap> = Extract<keyof TTables, string> | SqlNameOf<TTables[keyof TTables]>;
 /**
  * The set of acceptable subject inputs for a grant or `can()` check.
  *
  * - A {@link DrizzleTable} object reference (the original form, always allowed).
- * - A string-literal table name from {@link TableName}, constrained to the
- *   provided `TTables` schema map at compile time when one is supplied.
+ * - A string-literal table name from {@link TableName} — either the JS schema
+ *   key (`"postVersions"`) or the SQL table name (`"post_versions"`) — both
+ *   resolve to the same underlying table at runtime.
  * - The literal `"all"` for grants that apply to every table.
  */
 type SubjectInput<TTables extends SchemaMap = SchemaMap> = DrizzleTable | TableName<TTables> | "all";
@@ -92,9 +126,61 @@ declare const CRUD_ACTIONS: readonly CrudAction[];
  *
  * @param columns - The table's column references for building filter expressions.
  * @param user - The current user object (from `@cfast/auth`).
+ * @param lookups - Resolved values from the grant's `with` map (see {@link Grant.with}).
+ *   Empty object when the grant declares no `with` map. Each key holds the awaited
+ *   result of the lookup function with the same name.
  * @returns A Drizzle SQL expression to restrict matching rows, or `undefined` for no restriction.
  */
-type WhereClause = (columns: Record<string, unknown>, user: unknown) => DrizzleSQL | undefined;
+type WhereClause = (columns: Record<string, unknown>, user: unknown, lookups: Record<string, unknown>) => DrizzleSQL | undefined;
+/**
+ * Minimal structural type for the read-only database handle passed to grant
+ * `with` lookup functions.
+ *
+ * Defined here so the permissions package stays independent of `@cfast/db`.
+ * The runtime instance is provided by `@cfast/db` (an unsafe-mode db) and
+ * is structurally compatible with this interface, so authors can call
+ * `db.query(table).findMany().run()` inside a lookup without casting.
+ *
+ * The `query` method is intentionally typed loosely (`unknown` arguments and
+ * results) to avoid pulling Drizzle generics into the permissions surface.
+ * Authors typically know exactly which table they are querying and cast the
+ * result inline.
+ */
+interface LookupDb {
+    query: (table: DrizzleTable | string) => {
+        findMany: (options?: unknown) => {
+            run: (params?: unknown) => Promise<unknown[]>;
+        };
+        findFirst: (options?: unknown) => {
+            run: (params?: unknown) => Promise<unknown>;
+        };
+    };
+}
+/**
+ * A single prerequisite lookup function for a grant's `with` map.
+ *
+ * Lookups run **before** the main query and their resolved values are passed
+ * as the third argument to the grant's {@link WhereClause}. Use them to gather
+ * data from other tables that a row-level filter depends on (for example,
+ * the set of friend ids that a user can see content for).
+ *
+ * Lookups receive an unsafe-mode db handle so they can read freely without
+ * recursively triggering permission checks. Their results are cached for the
+ * lifetime of the per-request `Db` instance, so a single lookup runs at most
+ * once even when the same grant is consulted multiple times.
+ *
+ * @typeParam TUser - The user type (typed via `definePermissions<TUser>`).
+ */
+type LookupFn<TUser = unknown> = (user: TUser, db: LookupDb) => Promise<unknown> | unknown;
+/**
+ * A map of named prerequisite lookups for a grant.
+ *
+ * Each value is a {@link LookupFn} whose resolved result is passed to the
+ * grant's `where` clause via the third `lookups` argument under the same key.
+ *
+ * @typeParam TUser - The user type (typed via `definePermissions<TUser>`).
+ */
+type WithLookups<TUser = unknown> = Record<string, LookupFn<TUser>>;
 /**
  * A single permission grant: an action on a subject, optionally restricted by a `where` clause.
  *
@@ -112,6 +198,37 @@ type Grant = {
      * or `"all"` for every table.
      */
     subject: DrizzleTable | string;
+    /**
+     * Optional prerequisite lookups that resolve **before** the main query and
+     * are passed to the {@link where} clause as its third argument.
+     *
+     * Each lookup receives the current user and an unsafe-mode db handle and
+     * may return any value (synchronously or as a promise). Results are cached
+     * per `Db` instance, so a single lookup runs at most once per request even
+     * when the same grant participates in multiple queries.
+     *
+     * @example
+     * ```ts
+     * grant("read", recipes, {
+     *   with: {
+     *     friendIds: async (user, db) => {
+     *       const rows = await db
+     *         .query(friendGrants)
+     *         .findMany({ where: eq(friendGrants.grantee, user.id) })
+     *         .run();
+     *       return (rows as { target: string }[]).map((r) => r.target);
+     *     },
+     *   },
+     *   where: (recipe, user, { friendIds }) =>
+     *     or(
+     *       eq(recipe.visibility, "public"),
+     *       eq(recipe.authorId, user.id),
+     *       inArray(recipe.authorId, friendIds as string[]),
+     *     ),
+     * });
+     * ```
+     */
+    with?: WithLookups;
     /** Optional row-level filter that restricts which rows this grant covers. */
     where?: WhereClause;
 };
@@ -127,8 +244,20 @@ type Grant = {
  * @typeParam TTables - Optional schema map (e.g. `typeof schema`) used to
  *   constrain string subjects to known table-name literals.
  */
-type GrantFn<TUser, TTables extends SchemaMap = SchemaMap> = (action: PermissionAction, subject: SubjectInput<TTables>, options?: {
-    where?: (columns: Record<string, unknown>, user: TUser) => DrizzleSQL | undefined;
+type GrantFn<TUser, TTables extends SchemaMap = SchemaMap> = <TWith extends WithLookups<TUser> = WithLookups<TUser>>(action: PermissionAction, subject: SubjectInput<TTables>, options?: {
+    /**
+     * Prerequisite lookups whose resolved values are passed to {@link where}
+     * via its third argument. See {@link Grant.with}.
+     */
+    with?: TWith;
+    /**
+     * Row-level filter. The third argument exposes the resolved values from
+     * {@link with}, keyed by the same names; pass an empty `with` map (or
+     * omit it) when the filter does not need cross-table data.
+     */
+    where?: (columns: Record<string, unknown>, user: TUser, lookups: {
+        [K in keyof TWith]: Awaited<ReturnType<TWith[K]>>;
+    }) => DrizzleSQL | undefined;
 }) => Grant;
 /**
  * Structural description of a permission requirement.
@@ -250,5 +379,28 @@ declare class ForbiddenError extends Error {
         role: string | undefined;
     };
 }
+/**
+ * Error thrown at **permission-definition time** when a string-form subject
+ * passed to the `grant` callback inside
+ * `definePermissions<User, typeof schema>()` cannot be resolved to a real
+ * Drizzle table reference from the schema map.
+ *
+ * This is the runtime sibling of the compile-time constraint on
+ * {@link TableName} — it catches cases where the schema generic was skipped,
+ * the string was typed wrong (typo, wrong case), or the table was removed
+ * from the schema without updating the grant.
+ *
+ * Unlike {@link ForbiddenError} (thrown per-request on a permission check),
+ * `PermissionRegistrationError` is thrown **once at startup** from
+ * `definePermissions()` — so a misconfigured grant fails fast and loud
+ * instead of silently matching nothing at query time.
+ */
+declare class PermissionRegistrationError extends Error {
+    /** The unresolved subject string that was passed to `grant()`. */
+    readonly subject: string;
+    /** The available table names (both JS keys and SQL names) from the schema. */
+    readonly availableTables: readonly string[];
+    constructor(subject: string, availableTables: readonly string[]);
+}
 
-export { CRUD_ACTIONS as C, type DrizzleTable as D, ForbiddenError as F, type Grant as G, type PermissionsConfig as P, type SchemaMap as S, type TableName as T, type WhereClause as W, type Permissions as a, type PermissionAction as b, type SubjectInput as c, type PermissionDescriptor as d, type PermissionCheckResult as e, type CrudAction as f, type GrantFn as g, getTableName as h };
+export { CRUD_ACTIONS as C, type DrizzleTable as D, ForbiddenError as F, type Grant as G, type LookupDb as L, type PermissionsConfig as P, type SchemaMap as S, type TableName as T, type WithLookups as W, type Permissions as a, type PermissionAction as b, type SubjectInput as c, type WhereClause as d, type PermissionDescriptor as e, type PermissionCheckResult as f, type CrudAction as g, type GrantFn as h, type LookupFn as i, PermissionRegistrationError as j, type SqlNameOf as k, getTableName as l };

package/dist/client.d.ts

@@ -1 +1 @@
-export { f as CrudAction, F as ForbiddenError, b as PermissionAction, e as PermissionCheckResult, d as PermissionDescriptor } from './client-C7xdwHTk.js';
+export { g as CrudAction, F as ForbiddenError, b as PermissionAction, f as PermissionCheckResult, e as PermissionDescriptor } from './client-D6goQV8b.js';

package/dist/client.js

@@ -1,6 +1,6 @@
 import {
   ForbiddenError
-} from "./chunk-NCLN5YBQ.js";
+} from "./chunk-ISTOPBSB.js";
 export {
   ForbiddenError
 };

package/dist/index.d.ts

@@ -1,20 +1,44 @@
-import { P as PermissionsConfig, a as Permissions, S as SchemaMap, b as PermissionAction, c as SubjectInput, W as WhereClause, G as Grant, d as PermissionDescriptor, e as PermissionCheckResult } from './client-C7xdwHTk.js';
-export { C as CRUD_ACTIONS, f as CrudAction, D as DrizzleTable, F as ForbiddenError, g as GrantFn, T as TableName, h as getTableName } from './client-C7xdwHTk.js';
+import { P as PermissionsConfig, a as Permissions, S as SchemaMap, b as PermissionAction, c as SubjectInput, W as WithLookups, d as WhereClause, G as Grant, e as PermissionDescriptor, f as PermissionCheckResult } from './client-D6goQV8b.js';
+export { C as CRUD_ACTIONS, g as CrudAction, D as DrizzleTable, F as ForbiddenError, h as GrantFn, L as LookupDb, i as LookupFn, j as PermissionRegistrationError, k as SqlNameOf, T as TableName, l as getTableName } from './client-D6goQV8b.js';
 
 /**
  * Creates a permission configuration that can be shared between server-side
  * enforcement (`@cfast/db`) and client-side introspection (`@cfast/actions`).
  *
- * Supports three calling styles:
- * - **Direct:** `definePermissions(config)` when no custom user type is needed.
- * - **Curried (user only):** `definePermissions<MyUser>()(config)` for typed
- *   `where` clause user parameters.
- * - **Curried (user + tables):** `definePermissions<MyUser, typeof schema>()(config)`
- *   to additionally constrain string subjects passed to the `grant` callback
- *   to known table names from the schema map.
+ * Supports four calling styles:
  *
- * @param config - The permissions configuration with roles, grants, and optional hierarchy.
- * @returns A {@link Permissions} object containing roles, raw grants, and hierarchy-expanded `resolvedGrants`.
+ * 1. **Direct:** `definePermissions(config)` — when no custom user type and
+ *    no schema map is needed.
+ *
+ * 2. **Curried (user only):** `definePermissions<MyUser>()(config)` — types
+ *    the `user` parameter inside `where` clauses. String subjects are still
+ *    accepted but are **not** compile-time or runtime validated against a
+ *    schema; they are stored as opaque strings and matched by `getTableName`.
+ *
+ * 3. **Curried (user + schema types only, no runtime schema):**
+ *    `definePermissions<MyUser, typeof schema>()(config)` — constrains
+ *    string subjects to `"jsKey" | "sql_name"` at compile time, but at
+ *    runtime still stores strings opaquely. Prefer style (4) when you can.
+ *
+ * 4. **Curried with runtime schema (RECOMMENDED):**
+ *    `definePermissions<MyUser, typeof schema>({ schema })(config)` — walks
+ *    the schema at startup and resolves every string-form subject to the
+ *    exact Drizzle table reference the schema uses. This is the only form
+ *    that lets string-form grants work with Drizzle relational `with`
+ *    queries, because Drizzle identifies tables by reference, not name
+ *    (see issues #146, #175, #177).
+ *
+ *    - Unknown strings throw {@link PermissionRegistrationError} **at
+ *      startup** (fast, loud failure instead of silently matching nothing).
+ *    - Both the JS key (`"documentVersions"`) and the SQL table name
+ *      (`"document_versions"`) resolve to the same table reference.
+ *    - Object-form subjects still work unchanged.
+ *
+ * @param configOrOptions - Either the permissions config (style 1) or the
+ *   resolver options `{ schema }` (style 4). When omitted entirely, returns
+ *   the curried form (styles 2 and 3).
+ * @returns A {@link Permissions} object, or a function that takes a config
+ *   and returns one.
  *
  * @example
  * ```typescript
@@ -23,31 +47,30 @@ export { C as CRUD_ACTIONS, f as CrudAction, D as DrizzleTable, F as ForbiddenEr
  * import * as schema from "./schema";
  * const { posts, comments } = schema;
  *
- * // Direct form — accepts table objects
+ * // Style 1 — direct, accepts table objects
  * const permissions = definePermissions({
  *   roles: ["anonymous", "user", "admin"] as const,
  *   grants: {
  *     anonymous: [
  *       grant("read", posts, { where: (p) => eq(p.published, true) }),
  *     ],
- *     user: [
- *       grant("read", posts),
- *       grant("create", posts),
- *     ],
+ *     user: [grant("read", posts), grant("create", posts)],
  *     admin: [grant("manage", "all")],
  *   },
  * });
  *
- * // Curried form — string subjects constrained to known tables
+ * // Style 4 — recommended: runtime-resolved string subjects
  * type AuthUser = { id: string };
- * const perms = definePermissions<AuthUser, typeof schema>()({
+ * const perms = definePermissions<AuthUser, typeof schema>({ schema })({
  *   roles: ["user", "admin"] as const,
  *   grants: (grant) => ({
  *     user: [
- *       grant("read", "posts"),               // string form
- *       grant("update", posts, {              // object form still works
+ *       grant("read", "posts"),                // JS key — resolves
+ *       grant("create", "post_versions"),      // SQL name — also resolves
+ *       grant("update", posts, {               // object form still works
  *         where: (p, u) => eq(p.authorId, u.id),
  *       }),
+ *       // grant("read", "unknownTable"),      // throws at startup
  *     ],
  *     admin: [grant("manage", "all")],
  *   }),
@@ -55,6 +78,9 @@ export { C as CRUD_ACTIONS, f as CrudAction, D as DrizzleTable, F as ForbiddenEr
  * ```
  */
 declare function definePermissions<TRoles extends readonly string[]>(config: PermissionsConfig<TRoles>): Permissions<TRoles>;
+declare function definePermissions<TUser, TTables extends SchemaMap>(options: {
+    schema: TTables;
+}): <TRoles extends readonly string[]>(config: PermissionsConfig<TRoles, TUser, TTables>) => Permissions<TRoles>;
 declare function definePermissions<TUser, TTables extends SchemaMap = SchemaMap>(): <TRoles extends readonly string[]>(config: PermissionsConfig<TRoles, TUser, TTables>) => Permissions<TRoles>;
 
 /**
@@ -95,11 +121,33 @@ declare function definePermissions<TUser, TTables extends SchemaMap = SchemaMap>
  *   where: (post, user) => eq(post.authorId, user.id),
  * });
  *
+ * // Cross-table grant: read recipes that public, owned by the user, or
+ * // owned by a friend (resolved via a prerequisite lookup that runs once
+ * // per request and is cached for subsequent reads).
+ * grant("read", recipes, {
+ *   with: {
+ *     friendIds: async (user, db) => {
+ *       const rows = await db
+ *         .query(friendGrants)
+ *         .findMany({ where: eq(friendGrants.grantee, user.id) })
+ *         .run();
+ *       return (rows as { target: string }[]).map((r) => r.target);
+ *     },
+ *   },
+ *   where: (recipe, user, { friendIds }) =>
+ *     or(
+ *       eq(recipe.visibility, "public"),
+ *       eq(recipe.authorId, user.id),
+ *       inArray(recipe.authorId, friendIds as string[]),
+ *     ),
+ * });
+ *
  * // Full access to everything
  * grant("manage", "all");
  * ```
  */
 declare function grant<TTables extends SchemaMap = SchemaMap>(action: PermissionAction, subject: SubjectInput<TTables>, options?: {
+    with?: WithLookups;
     where?: WhereClause;
 }): Grant;
 
@@ -215,4 +263,4 @@ type UserWithRoles = {
 declare function resolveGrants(permissions: Permissions, user: UserWithRoles): Grant[];
 declare function resolveGrants(permissions: Permissions, roles: readonly string[]): Grant[];
 
-export { Grant, PermissionAction, PermissionCheckResult, PermissionDescriptor, Permissions, PermissionsConfig, SchemaMap, SubjectInput, type UserWithRoles, WhereClause, can, checkPermissions, definePermissions, grant, resolveGrants };
+export { Grant, PermissionAction, PermissionCheckResult, PermissionDescriptor, Permissions, PermissionsConfig, SchemaMap, SubjectInput, type UserWithRoles, WhereClause, WithLookups, can, checkPermissions, definePermissions, grant, resolveGrants };

package/dist/index.js

@@ -1,22 +1,58 @@
 import {
   CRUD_ACTIONS,
   ForbiddenError,
+  PermissionRegistrationError,
   getTableName
-} from "./chunk-NCLN5YBQ.js";
+} from "./chunk-ISTOPBSB.js";
 
 // src/grant.ts
 function grant(action, subject, options) {
   return {
     action,
     subject,
+    with: options?.with,
     where: options?.where
   };
 }
 
 // src/define-permissions.ts
-function buildPermissions(config) {
+function buildSchemaLookup(schema) {
+  const lookup = /* @__PURE__ */ new Map();
+  const available = /* @__PURE__ */ new Set();
+  if (!schema) return { lookup, available: [] };
+  for (const [jsKey, table] of Object.entries(schema)) {
+    if (!table || typeof table !== "object" && typeof table !== "function") {
+      continue;
+    }
+    lookup.set(jsKey, table);
+    available.add(jsKey);
+    const sqlName = getTableName(table);
+    if (sqlName && sqlName !== "unknown") {
+      lookup.set(sqlName, table);
+      available.add(sqlName);
+    }
+  }
+  return { lookup, available: [...available] };
+}
+function makeSchemaAwareGrant(lookup, available) {
+  const schemaGrant = ((action, subject, options) => {
+    if (typeof subject !== "string" || subject === "all") {
+      return grant(action, subject, options);
+    }
+    const resolved = lookup.get(subject);
+    if (!resolved) {
+      throw new PermissionRegistrationError(subject, available);
+    }
+    return grant(action, resolved, options);
+  });
+  return schemaGrant;
+}
+function buildPermissions(config, schema) {
   const { roles, hierarchy } = config;
-  const grantFn = grant;
+  const grantFn = schema ? (() => {
+    const { lookup, available } = buildSchemaLookup(schema);
+    return makeSchemaAwareGrant(lookup, available);
+  })() : grant;
   const grants = typeof config.grants === "function" ? config.grants(grantFn) : config.grants;
   const resolvedGrants = resolveHierarchy(roles, grants, hierarchy);
   return {
@@ -25,11 +61,20 @@ function buildPermissions(config) {
     resolvedGrants
   };
 }
-function definePermissions(config) {
-  if (config === void 0) {
+function definePermissions(configOrOptions) {
+  if (configOrOptions === void 0) {
     return (c) => buildPermissions(c);
   }
-  return buildPermissions(config);
+  if (isSchemaOptions(configOrOptions)) {
+    const { schema } = configOrOptions;
+    return (c) => buildPermissions(c, schema);
+  }
+  return buildPermissions(configOrOptions);
+}
+function isSchemaOptions(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return v.schema !== void 0 && typeof v.schema === "object" && v.schema !== null && v.roles === void 0;
 }
 function resolveHierarchy(roles, grants, hierarchy) {
   if (!hierarchy) {
@@ -143,36 +188,48 @@ function resolveGrants(permissions, userOrRoles) {
     const key = `${g.action}:${getSubjectKey(g.subject)}`;
     let group = groups.get(key);
     if (!group) {
-      group = { action: g.action, subject: g.subject, wheres: [] };
+      group = { action: g.action, subject: g.subject, grants: [] };
       groups.set(key, group);
     }
-    group.wheres.push(g.where);
+    group.grants.push(g);
   }
   const result = [];
   for (const group of groups.values()) {
-    const hasUnrestricted = group.wheres.some((w) => w === void 0);
+    const hasUnrestricted = group.grants.some((g) => !g.where);
     if (hasUnrestricted) {
       result.push({ action: group.action, subject: group.subject });
-    } else {
-      const whereFns = group.wheres.filter(
-        (w) => w !== void 0
+      continue;
+    }
+    const withLookups = group.grants.filter((g) => g.with !== void 0);
+    const plain = group.grants.filter((g) => g.with === void 0 && g.where);
+    for (const g of withLookups) {
+      result.push({
+        action: group.action,
+        subject: group.subject,
+        with: g.with,
+        where: g.where
+      });
+    }
+    if (plain.length === 1) {
+      result.push({
+        action: group.action,
+        subject: group.subject,
+        where: plain[0].where
+      });
+    } else if (plain.length > 1) {
+      const whereFns = plain.map(
+        (g) => g.where
+      );
+      const merged = (columns, user, lookups) => or(
+        ...whereFns.map(
+          (fn) => toSQLWrapper(fn(columns, user, lookups))
+        )
       );
-      if (whereFns.length === 1) {
-        result.push({
-          action: group.action,
-          subject: group.subject,
-          where: whereFns[0]
-        });
-      } else {
-        const merged = (columns, user) => or(
-          ...whereFns.map((fn) => toSQLWrapper(fn(columns, user)))
-        );
-        result.push({
-          action: group.action,
-          subject: group.subject,
-          where: merged
-        });
-      }
+      result.push({
+        action: group.action,
+        subject: group.subject,
+        where: merged
+      });
     }
   }
   return result;
@@ -180,6 +237,7 @@ function resolveGrants(permissions, userOrRoles) {
 export {
   CRUD_ACTIONS,
   ForbiddenError,
+  PermissionRegistrationError,
   can,
   checkPermissions,
   definePermissions,

package/llms.txt

@@ -32,34 +32,39 @@ const permissions = definePermissions({
 });
 ```
 
-**Curried form** for typed user in WHERE clauses:
-```typescript
-const permissions = definePermissions<MyUser>()({
-  roles: [...] as const,
-  grants: (grant) => ({
-    user: [ grant("update", posts, { where: (post, user) => eq(post.authorId, user.id) }) ],
-    // ...
-  }),
-});
-```
+**Curried form with schema (RECOMMENDED)** — pass the schema as a runtime argument to resolve string subjects to the exact same Drizzle table reference your schema uses. This is the only form that lets string-form grants work with Drizzle relational `with` queries, because `@cfast/db` identifies tables by reference (not name):
 
-**Curried form with schema** to constrain string subjects to known table names at compile time:
 ```typescript
 import * as schema from "./schema";
 
-const permissions = definePermissions<MyUser, typeof schema>()({
+const permissions = definePermissions<MyUser, typeof schema>({ schema })({
   roles: ["member", "admin"] as const,
   grants: (grant) => ({
     member: [
-      grant("read", "projects"),                  // ✓ string form, type-checked
+      grant("read", "projects"),                  // ✓ JS key
+      grant("read", "project_versions"),          // ✓ SQL name (snake_case)
       grant("read", schema.projects),             // ✓ object form still works
-      // grant("read", "unknownTable"),           // ✗ TypeScript error
+      // grant("read", "unknownTable"),           // ✗ TypeScript error + runtime throw
     ],
     admin: [grant("manage", "all")],
   }),
 });
 ```
 
+Both JS schema keys (e.g. `"projectVersions"`) and SQL table names (e.g. `"project_versions"`) resolve to the same table reference. Unknown strings throw `PermissionRegistrationError` at **startup** — fast, loud failure instead of silently matching nothing at query time.
+
+**Curried form without runtime schema** — legacy shape that types the `user` parameter but does not resolve strings. String subjects are stored opaquely and matched by name only; cross-table `with` relational queries will silently return empty arrays. Prefer the recommended form above:
+
+```typescript
+const permissions = definePermissions<MyUser>()({
+  roles: [...] as const,
+  grants: (grant) => ({
+    user: [ grant("update", posts, { where: (post, user) => eq(post.authorId, user.id) }) ],
+    // ...
+  }),
+});
+```
+
 **Returns** `Permissions<TRoles>`:
 ```typescript
 type Permissions<TRoles> = {
@@ -71,11 +76,61 @@ type Permissions<TRoles> = {
 
 ### `grant(action, subject, options?): Grant`
 ```typescript
-grant(action: PermissionAction, subject: DrizzleTable | string, options?: { where?: WhereClause }): Grant
+grant(action: PermissionAction, subject: DrizzleTable | string, options?: {
+  with?: WithLookups;
+  where?: WhereClause;
+}): Grant
 ```
 - `PermissionAction`: `"read" | "create" | "update" | "delete" | "manage"`
-- `WhereClause`: `(columns, user) => DrizzleSQL | undefined`
-- `subject` may be a Drizzle table object, a string table name (e.g. `"projects"`), or `"all"`. String and object forms are interchangeable at runtime — both are normalized to the same key by `getTableName()`. To get compile-time validation that a string subject is a known table, use the `definePermissions<User, typeof schema>()` curried form.
+- `WhereClause`: `(columns, user, lookups) => DrizzleSQL | undefined`
+- `WithLookups`: `Record<string, (user, db) => Promise<unknown> | unknown>`
+- `subject` may be a Drizzle table object, a string table name (JS key **or** SQL name), or `"all"`. When called via the `grant` callback inside `definePermissions<User, typeof schema>({ schema })`, string subjects are resolved at startup to the exact same Drizzle table reference the schema uses, and unknown strings throw `PermissionRegistrationError`. When called standalone (not via the schema-aware callback), string subjects are stored opaquely and matched by name — prefer the resolved form so cross-table relational `with` queries work correctly.
+
+#### Cross-table grants via `with`
+
+When a row-level filter needs data from another table (e.g. "recipes are visible if the user is in the recipe author's friend list"), declare the prerequisite read in the `with` map. Each entry runs **before** the main query, its result is passed to `where` under the same name, and results are cached per-request via the `Db` instance — a lookup runs at most once per request even when consulted by multiple queries.
+
+```typescript
+import { definePermissions } from "@cfast/permissions";
+import { eq, inArray, or } from "drizzle-orm";
+import * as schema from "./schema";
+const { recipes, friendGrants } = schema;
+
+type AppUser = { id: string; roles: string[] };
+
+export const permissions = definePermissions<AppUser, typeof schema>({ schema })({
+  roles: ["user"] as const,
+  grants: (g) => ({
+    user: [
+      g("read", recipes, {
+        with: {
+          // db is an unsafe-mode handle so the lookup itself isn't filtered.
+          friendIds: async (user, db) => {
+            const rows = await db
+              .query(friendGrants)
+              .findMany({ where: eq(friendGrants.grantee, user.id) })
+              .run();
+            return (rows as { target: string }[]).map((r) => r.target);
+          },
+        },
+        where: (recipe, user, { friendIds }) =>
+          or(
+            eq(recipe.visibility, "public"),
+            eq(recipe.authorId, user.id),
+            inArray(recipe.authorId, friendIds as string[]),
+          ),
+      }),
+    ],
+  }),
+});
+```
+
+Notes on `with` semantics:
+- Lookup functions receive the user and a `LookupDb` (the unsafe sibling of the per-request `Db`); they may return any value, sync or async.
+- Multiple lookups in a single grant resolve in **parallel** before the where clause is invoked.
+- Results live in a per-`Db` cache keyed by grant identity, so the same grant participating in many `findMany`/`findFirst`/`paginate`/`update`/`delete` calls during one request only triggers each lookup once.
+- A sibling **unrestricted** grant (e.g. an admin role) collapses the group, so the lookup is skipped entirely.
+- A `with`-grant is never folded into another grant's `where` closure during `resolveGrants` — it stays a standalone grant so its lookup map can resolve independently.
 
 ### `checkPermissions(role, permissions, descriptors): PermissionCheckResult`
 ```typescript
@@ -118,6 +173,20 @@ class ForbiddenError extends Error {
 }
 ```
 
+Thrown at request time when a permission check fails (row-level denial).
+
+### `PermissionRegistrationError`
+```typescript
+import { PermissionRegistrationError } from "@cfast/permissions";
+
+class PermissionRegistrationError extends Error {
+  readonly subject: string;                 // the unresolved string
+  readonly availableTables: readonly string[]; // sorted JS keys + SQL names
+}
+```
+
+Thrown **at startup** from `definePermissions<User, typeof schema>({ schema })(...)` when a string-form grant subject does not match any table in the schema. Fast, loud failure so a typo or a removed table surfaces immediately instead of silently matching nothing at query time.
+
 ### `can(grants, action, table): boolean`
 ```typescript
 import { can } from "@cfast/permissions";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/permissions",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Isomorphic, composable permission system with Drizzle-native row-level access control",
   "keywords": [
     "cfast",