esoul-sdk 0.7.0 → 0.16.0

package/dist/db/client-core.d.ts

@@ -21,6 +21,7 @@
  * agree on the values.
  */
 import { type CompiledModel, type CompiledRules, type ReadPlan, type RuleViewer, type WritePlan } from "./compile-rules.js";
+import { type Narrowing } from "./custom-roles.js";
 export type Row = Record<string, unknown>;
 export type RefuseCode = "forbidden" | "login-required" | "invalid" | "not-bound" | "rate-limited";
 export type Refuse = (code: RefuseCode, message: string, detail?: string) => never;
@@ -52,6 +53,14 @@ export declare const FILTER_OPS: readonly ["in", "notIn", "not", "gt", "gte", "l
 /** The only operator a LIST field takes, and the only one a scalar does not. */
 export declare const LIST_ONLY_OPS: readonly ["has"];
 export type FilterOp = (typeof FILTER_OPS)[number];
+/**
+ * A MALFORMED CALL SAYS WHAT IS WRONG WITH IT. The reason is about the app's own
+ * code — a take over the cap, an unindexed filter — never about a viewer's data, so
+ * it rides in the message, where an author sees it: in a test, a tool result, a
+ * log. It used to be the bare word "invalid", with the reason tucked into `detail`
+ * that only a workbench box returns, so an author who asked for 201 rows was told
+ * nothing (2026-09-14).
+ */
 export declare function bad(c: Core, detail: string): never;
 /**
  * A caller-supplied scope key is REFUSED, never overridden. An app that sets
@@ -128,6 +137,35 @@ export declare function scopeConjunct(c: Core, model?: CompiledModel): ScopeConj
 export declare function scopeMatches(c: Core, row: Row, model?: CompiledModel): boolean;
 /** Sealed fields are readable by the row's owner and by the app's own task. */
 export declare function mayUnseal(c: Core, row: Row): boolean;
+/** Does this row fall inside the composed role's `where`? (Memory's predicate; Prisma spells `narrowWhere`.) */
+export declare function narrowMatches(plan: {
+    narrow: Narrowing;
+}, row: Row): boolean;
+/** The narrowing as Prisma conjuncts — one `{ field: value }` or `{ field: { in } }` per clause. */
+export declare function narrowWhere(plan: {
+    narrow: Narrowing;
+}): Record<string, unknown>[];
+/**
+ * A CREATE lands inside the caller's scope or not at all. For each scalar
+ * conjunct of the narrowing, a missing value is filled in (a customer's reading
+ * is theirs without saying so) and a different one is refused — a scoped role
+ * can no more write another customer's row than read it. A list conjunct is a
+ * membership check.
+ */
+export declare function withinScope(c: Core, plan: {
+    narrow: Narrowing;
+}, data: Row): Row;
+/** Fields the composed role may not see: read as null, exactly as a sealed field is for a stranger. */
+export declare function hideFields(plan: {
+    narrow: Narrowing;
+}, row: Row): Row;
+/**
+ * A move the composed role was not handed is refused, by name. `target` is the
+ * row as it stands; a data that does not touch the transition field is not a move.
+ */
+export declare function assertTransition(c: Core, plan: {
+    narrow: Narrowing;
+}, target: Row, data: Row): void;
 /**
  * Refuses, or hands back the plan — never both, never neither.
  *

package/dist/db/client-core.js

@@ -21,6 +21,7 @@
  * agree on the values.
  */
 import { INJECTED_COLUMNS, canUnseal, planRead, planWrite, } from "./compile-rules.js";
+import { rowMatchesNarrowing, transitionAllowed } from "./custom-roles.js";
 /** Standalone default so the package works with no host attached. */
 export const defaultRefuse = (code, message, detail) => {
     const err = new Error(message);
@@ -35,8 +36,16 @@ export const FILTER_OPS = ["in", "notIn", "not", "gt", "gte", "lt", "lte", "cont
 /** The only operator a LIST field takes, and the only one a scalar does not. */
 export const LIST_ONLY_OPS = ["has"];
 /* ───────────────────────── argument validation ────────────────────────── */
+/**
+ * A MALFORMED CALL SAYS WHAT IS WRONG WITH IT. The reason is about the app's own
+ * code — a take over the cap, an unindexed filter — never about a viewer's data, so
+ * it rides in the message, where an author sees it: in a test, a tool result, a
+ * log. It used to be the bare word "invalid", with the reason tucked into `detail`
+ * that only a workbench box returns, so an author who asked for 201 rows was told
+ * nothing (2026-09-14).
+ */
 export function bad(c, detail) {
-    return c.refuse("invalid", "invalid", detail);
+    return c.refuse("invalid", `invalid: ${detail}`, detail);
 }
 /**
  * A caller-supplied scope key is REFUSED, never overridden. An app that sets
@@ -194,6 +203,64 @@ export function mayUnseal(c, row) {
         return true;
     return canUnseal(c.viewer, row);
 }
+/* ───────────────────── a composed role's narrowing ───────────────────── */
+/** Does this row fall inside the composed role's `where`? (Memory's predicate; Prisma spells `narrowWhere`.) */
+export function narrowMatches(plan, row) {
+    return rowMatchesNarrowing(plan.narrow, row);
+}
+/** The narrowing as Prisma conjuncts — one `{ field: value }` or `{ field: { in } }` per clause. */
+export function narrowWhere(plan) {
+    const w = plan.narrow.where;
+    if (!w)
+        return [];
+    return Object.entries(w).map(([f, v]) => (Array.isArray(v) ? { [f]: { in: v } } : { [f]: v }));
+}
+/**
+ * A CREATE lands inside the caller's scope or not at all. For each scalar
+ * conjunct of the narrowing, a missing value is filled in (a customer's reading
+ * is theirs without saying so) and a different one is refused — a scoped role
+ * can no more write another customer's row than read it. A list conjunct is a
+ * membership check.
+ */
+export function withinScope(c, plan, data) {
+    const w = plan.narrow.where;
+    if (!w)
+        return data;
+    const out = { ...data };
+    for (const [field, v] of Object.entries(w)) {
+        if (Array.isArray(v)) {
+            if (out[field] === undefined || !v.includes(out[field])) {
+                c.refuse("forbidden", "forbidden", `${c.model.name}.create: ${field} must be one of ${v.map((x) => JSON.stringify(x)).join(", ")} for this caller`);
+            }
+        }
+        else if (out[field] === undefined)
+            out[field] = v;
+        else if (out[field] !== v)
+            c.refuse("forbidden", "forbidden", `${c.model.name}.create: ${field} is ${JSON.stringify(v)} for this caller, not ${JSON.stringify(out[field])}`);
+    }
+    return out;
+}
+/** Fields the composed role may not see: read as null, exactly as a sealed field is for a stranger. */
+export function hideFields(plan, row) {
+    if (!plan.narrow.hide.length)
+        return row;
+    const out = { ...row };
+    for (const f of plan.narrow.hide)
+        out[f] = null;
+    return out;
+}
+/**
+ * A move the composed role was not handed is refused, by name. `target` is the
+ * row as it stands; a data that does not touch the transition field is not a move.
+ */
+export function assertTransition(c, plan, target, data) {
+    const ok = transitionAllowed(plan.narrow, target, data);
+    if (ok === false) {
+        const t = plan.narrow.transitions;
+        const from = String(target[t.field]);
+        c.refuse("forbidden", "forbidden", `${c.model.name}.update: this role may move ${t.field} from "${from}" to ${(t.moves[from] ?? []).map((x) => `"${x}"`).join(", ") || "nothing"} — not "${String(data[t.field])}"`);
+    }
+}
 /* ─────────────────────────────── writes ───────────────────────────────── */
 /**
  * Refuses, or hands back the plan — never both, never neither.

package/dist/db/compile-rules.d.ts

@@ -35,8 +35,16 @@ export interface RuleViewer {
     userId: string | null;
     /** Every id this caller has acted under (guest cookie ∪ account ∪ linked). */
     viewerIds: string[];
-    /** The app's own word for this caller. */
+    /** The app's own word for this caller — for a composed role, the BASE word it stands on. */
     role: string;
+    /**
+     * A role the OWNER composed (custom-roles.ts): the compiled narrowing and the
+     * person's attribute values. Every rule naming `role` still applies; this can
+     * only take away — rows outside its `where`, fields it hides, moves it lacks.
+     */
+    custom?: CustomRoleGrant | null;
+    /** The person's attribute values from their grant, typed by `roles.attributes` — what a scoped rule's `viewer.<attribute>` reads. */
+    attrs?: Record<string, AttrValue>;
 }
 /**
  * The closed list. A `default: never` in `principalOutcome` makes adding a
@@ -58,10 +66,18 @@ export type Principal =
  | {
     t: "creator";
 }
-/** A caller holding this role in this app. */
+/**
+ * A caller holding this role in this app — optionally SCOPED to the rows a
+ * `where` names, with `viewer.<attribute>` filled from the person's grant:
+ * `{ "role": "customer", "where": { "customer": "viewer.customer" } }` is the
+ * whole of "a customer sees only their own readings", enforced on every
+ * read and write, always, by the manifest — not by anything an owner must
+ * remember to compose.
+ */
  | {
     t: "role";
     role: string;
+    where?: Record<string, WhereValue>;
 }
 /** Another app reading through a binding it was granted (`uses`/`provides`). */
  | {
@@ -73,6 +89,7 @@ export type Principal =
 };
 export declare const PRINCIPAL_KINDS: readonly ["anyone", "account", "creator", "role", "apps", "internal"];
 export type PrincipalKind = (typeof PRINCIPAL_KINDS)[number];
+import { type AttrType, type AttrValue, type CustomRoleGrant, type CustomRolesEnvelope, type CustomRolesEnvelopeRaw, type Narrowing, type WhereValue } from "./custom-roles.js";
 export type Scope = "instance" | "workspace" | "user";
 export type RuleOp = "read" | "create" | "update" | "delete";
 export declare const RULE_OPS: readonly RuleOp[];
@@ -141,6 +158,10 @@ export interface CompiledRules {
     version: 1;
     pluginId: string;
     models: Record<string, CompiledModel>;
+    /** What an owner-composed role may be made of (`roles.custom`), or null. */
+    custom?: CustomRolesEnvelope | null;
+    /** `roles.attributes` — what a grant may say about a person, and its type. Absent in an artefact generated before 0.14. */
+    attributes?: Record<string, AttrType>;
 }
 /** Stamped by the platform on every row. A manifest may not declare these. */
 export declare const PLATFORM_COLUMNS: readonly ["id", "workspaceId", "nodeId", "ownerId", "createdBy", "createdAt", "updatedAt", "deletedAt"];
@@ -178,7 +199,40 @@ export interface CompileInput {
      * compile error about a rule its author never wrote.
      */
     ownerRole?: string;
+    /** From `roles.custom` — the envelope an owner composes roles inside. */
+    custom?: CustomRolesEnvelopeRaw;
+    /** From `roles.attributes` — `{ customer: "int" }`: what a grant may carry, typed. */
+    attributes?: Record<string, string>;
+    /** Every surface name (ops, routes, tasks) — what `roles.custom.ops` may list. */
+    surfaces?: string[];
+}
+/**
+ * The parts of a `plugin.json` the rule compiler reads. Every place that compiles
+ * a MANIFEST goes through `compileManifestRules` — the generator, the install
+ * job, the author's `memoryDb`, the box. Callers that picked the fields out one
+ * by one each learned about `roles.custom` and then `roles.attributes` late, and
+ * the install job would have refused every app with a scoped rule (2026-09-14);
+ * a repo test now refuses a caller that reaches into `roles` itself.
+ */
+export interface ManifestForRules {
+    id?: string;
+    db?: Record<string, ManifestDbModel> | Record<string, never> | null;
+    roles?: {
+        vocabulary?: string[];
+        default?: {
+            owner?: string;
+        } & Record<string, string | undefined>;
+        custom?: CustomRolesEnvelopeRaw;
+        attributes?: Record<string, string>;
+    } | null;
+    ops?: unknown;
+    routes?: unknown;
+    kickableTasks?: unknown;
 }
+/** The compiler's input, from a manifest — the one reading of `roles`, `db` and the surfaces. */
+export declare function rulesInputFromManifest(m: ManifestForRules, pluginId?: string): CompileInput;
+/** Compile a manifest's rules. Throws `RuleCompileError` with the key path, as `compileRules` does. */
+export declare function compileManifestRules(m: ManifestForRules, pluginId?: string): CompiledRules;
 /** An authoring mistake. Thrown at build time, never at request time. */
 export declare class RuleCompileError extends Error {
     readonly keyPath: string;
@@ -200,6 +254,8 @@ export interface ReadPlan {
     visible: boolean;
     /** When set, only rows whose `ownerId` is in this list. */
     ownerIn: string[] | null;
+    /** A composed role's narrowing of this model: extra conjuncts and hidden fields. */
+    narrow: Narrowing;
 }
 /**
  * What this caller may READ. Never refuses — see the header. A caller with no
@@ -213,6 +269,8 @@ export type WritePlan = {
     ownerIn: string[] | null;
     /** When set, the only fields this caller may write. */
     fields: string[] | null;
+    /** A composed role's narrowing: rows it may touch, fields it hides, moves it may make. */
+    narrow: Narrowing;
 } | {
     ok: false;
     code: "forbidden" | "login-required";

package/dist/db/compile-rules.js

@@ -24,6 +24,7 @@
  *    never order, when the truth is they may, after signing in.
  */
 export const PRINCIPAL_KINDS = ["anyone", "account", "creator", "role", "apps", "internal"];
+import { ATTR_TYPES, compileEnvelope, mergeWhere, narrowingFor, resolveWhere } from "./custom-roles.js";
 export const RULE_OPS = ["read", "create", "update", "delete"];
 /* ───────────────────── columns the platform owns ──────────────────────── */
 /** Stamped by the platform on every row. A manifest may not declare these. */
@@ -41,6 +42,23 @@ export const PLATFORM_COLUMNS = [
 export const PLATFORM_FILTERABLE = ["id", "createdAt", "ownerId"];
 /** Scope keys an app may never supply itself — the platform injects them. */
 export const INJECTED_COLUMNS = ["workspaceId", "nodeId", "ownerId", "createdBy"];
+const surfaceNamesOf = (x) => (Array.isArray(x) ? x.map(String) : x && typeof x === "object" ? Object.keys(x) : []);
+/** The compiler's input, from a manifest — the one reading of `roles`, `db` and the surfaces. */
+export function rulesInputFromManifest(m, pluginId) {
+    return {
+        pluginId: pluginId ?? m.id ?? "app",
+        db: (m.db ?? {}),
+        vocabulary: m.roles?.vocabulary,
+        ownerRole: m.roles?.default?.owner,
+        custom: m.roles?.custom,
+        attributes: m.roles?.attributes,
+        surfaces: [...surfaceNamesOf(m.ops), ...surfaceNamesOf(m.routes), ...surfaceNamesOf(m.kickableTasks)],
+    };
+}
+/** Compile a manifest's rules. Throws `RuleCompileError` with the key path, as `compileRules` does. */
+export function compileManifestRules(m, pluginId) {
+    return compileRules(rulesInputFromManifest(m, pluginId));
+}
 /** An authoring mistake. Thrown at build time, never at request time. */
 export class RuleCompileError extends Error {
     keyPath;
@@ -88,7 +106,45 @@ function parseField(keyPath, spec, models) {
     }
     return field;
 }
-function parsePrincipal(keyPath, raw, vocabulary) {
+function parsePrincipal(keyPath, raw, vocabulary, ctx) {
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        const o = raw;
+        if (typeof o.role !== "string")
+            throw new RuleCompileError(`${keyPath}.role`, 'a scoped principal is { "role": "<word>", "where": { … } }');
+        const base = parsePrincipal(`${keyPath}.role`, o.role, vocabulary, ctx);
+        if (base.t !== "role")
+            throw new RuleCompileError(`${keyPath}.role`, `only a role of this app can be scoped — "${o.role}" is a principal`);
+        if (!o.where || typeof o.where !== "object" || Array.isArray(o.where) || !Object.keys(o.where).length) {
+            throw new RuleCompileError(`${keyPath}.where`, "a scoped principal names at least one field: { \"<field>\": <value> | [<values>] | \"viewer.<attribute>\" }");
+        }
+        const where = {};
+        for (const [field, value] of Object.entries(o.where)) {
+            const at = `${keyPath}.where.${field}`;
+            if (!ctx.fields.includes(field))
+                throw new RuleCompileError(at, `"${field}" is not a declared field — declared: ${ctx.fields.join(", ")}`);
+            if (!ctx.filterable.includes(field))
+                throw new RuleCompileError(at, `"${field}" has no index — a rule scoped by it would scan the table on every read; add it to indexes`);
+            if (typeof value === "string" && value.startsWith("viewer.")) {
+                const attr = value.slice(7);
+                if (!ctx.attributes[attr])
+                    throw new RuleCompileError(at, `"${value}" names no attribute — declare it in roles.attributes (${Object.keys(ctx.attributes).map((a) => `viewer.${a}`).join(", ") || "none declared"})`);
+            }
+            else if (Array.isArray(value)) {
+                if (!value.length)
+                    throw new RuleCompileError(at, "an empty list would match nothing");
+                for (const v of value)
+                    if (!["string", "number", "boolean"].includes(typeof v))
+                        throw new RuleCompileError(at, "values are strings, numbers or booleans");
+            }
+            else if (!["string", "number", "boolean"].includes(typeof value)) {
+                throw new RuleCompileError(at, "a value, a list of values, or viewer.<attribute>");
+            }
+            where[field] = value;
+        }
+        return { t: "role", role: base.role, where };
+    }
+    if (typeof raw !== "string")
+        throw new RuleCompileError(keyPath, `a principal is a word or { "role", "where" } — got ${typeof raw}`);
     switch (raw) {
         case "anyone":
             return { t: "anyone" };
@@ -108,17 +164,38 @@ function parsePrincipal(keyPath, raw, vocabulary) {
     }
     return { t: "role", role: raw };
 }
-function parseRule(keyPath, raw, fields, vocabulary, op) {
+/**
+ * A rule's principals are alternatives (any one grants), but a scope narrows by
+ * AND. Two shapes would therefore answer LESS than the author wrote, silently:
+ * `creator` beside a scoped role (own rows OR the scope — the plan can only give
+ * one), and two scopes for the same role (either scope — the plan keeps one).
+ * Refused by name until the engine carries a disjunction; a rule that says less
+ * than it means is the failure this compiler exists to prevent.
+ */
+function checkAlternatives(keyPath, principals) {
+    const scoped = principals.filter((p) => p.t === "role" && !!p.where);
+    if (scoped.length && principals.some((p) => p.t === "creator")) {
+        throw new RuleCompileError(keyPath, `"creator" and a scoped role (${scoped[0].role}) on one rule would mean own rows OR the scope, which a rule cannot say yet — scope by a field instead, or give the role one of the two`);
+    }
+    const seen = new Set();
+    for (const p of scoped) {
+        if (seen.has(p.role))
+            throw new RuleCompileError(keyPath, `"${p.role}" is scoped twice on one rule — merge the two where clauses into one (a list of values means any of them)`);
+        seen.add(p.role);
+    }
+    return principals;
+}
+function parseRule(keyPath, raw, fields, vocabulary, op, pctx) {
     const empty = { principals: [], requiresAccount: false, creatorMay: null, fields: null };
     if (raw === undefined)
         return empty;
     if (typeof raw === "string") {
-        return { ...empty, principals: [parsePrincipal(keyPath, raw, vocabulary)] };
+        return { ...empty, principals: checkAlternatives(keyPath, [parsePrincipal(keyPath, raw, vocabulary, pctx)]) };
     }
     if (Array.isArray(raw)) {
         return {
             ...empty,
-            principals: raw.map((p, i) => parsePrincipal(`${keyPath}[${i}]`, String(p), vocabulary)),
+            principals: checkAlternatives(keyPath, raw.map((p, i) => parsePrincipal(`${keyPath}[${i}]`, p, vocabulary, pctx))),
         };
     }
     if (typeof raw !== "object" || raw === null) {
@@ -126,7 +203,7 @@ function parseRule(keyPath, raw, fields, vocabulary, op) {
     }
     const o = raw;
     const roles = Array.isArray(o.roles) ? o.roles : [];
-    const principals = roles.map((p, i) => parsePrincipal(`${keyPath}.roles[${i}]`, String(p), vocabulary));
+    const principals = checkAlternatives(`${keyPath}.roles`, roles.map((p, i) => parsePrincipal(`${keyPath}.roles[${i}]`, p, vocabulary, pctx)));
     const checkFields = (list, label) => {
         if (list === undefined)
             return null;
@@ -162,6 +239,14 @@ export function compileRules(input) {
     const modelNames = Object.keys(input.db ?? {});
     const ownerRole = defaultRoleFor(input);
     const models = {};
+    const attributes = {};
+    for (const [name, type] of Object.entries(input.attributes ?? {})) {
+        if (!/^[a-z][a-z0-9_-]{0,30}$/.test(name))
+            throw new RuleCompileError(`roles.attributes.${name}`, "an attribute name is a-z, digits, - and _ (at most 31 characters)");
+        if (!ATTR_TYPES.includes(String(type)))
+            throw new RuleCompileError(`roles.attributes.${name}`, `unknown type "${type}" — allowed: ${ATTR_TYPES.join(", ")}`);
+        attributes[name] = type;
+    }
     for (const name of modelNames) {
         const raw = input.db[name];
         const at = `db.${name}`;
@@ -254,6 +339,13 @@ export function compileRules(input) {
         if (scope === "user" && raw.rules !== undefined) {
             throw new RuleCompileError(`${at}.rules`, "a `scope: user` model needs no rules — its rows are readable and writable only by the account that owns them");
         }
+        const filterable = [
+            ...new Set([
+                ...PLATFORM_FILTERABLE,
+                ...unique.flat(),
+                ...indexes.flatMap((i) => i.fields),
+            ]),
+        ].sort();
         const rawRules = (raw.rules ?? {});
         for (const key of Object.keys(rawRules)) {
             if (!["read", "create", "update", "delete", "write"].includes(key)) {
@@ -261,19 +353,13 @@ export function compileRules(input) {
             }
         }
         const write = rawRules.write;
+        const pctx = { fields: fieldNames, filterable, attributes };
         const rules = {
-            read: parseRule(`${at}.rules.read`, rawRules.read ?? defaultFor(scope, "read", ownerRole), fieldNames, input.vocabulary, "read"),
-            create: parseRule(`${at}.rules.create`, rawRules.create ?? write ?? defaultFor(scope, "create", ownerRole), fieldNames, input.vocabulary, "create"),
-            update: parseRule(`${at}.rules.update`, rawRules.update ?? write ?? defaultFor(scope, "update", ownerRole), fieldNames, input.vocabulary, "update"),
-            delete: parseRule(`${at}.rules.delete`, rawRules.delete ?? write ?? defaultFor(scope, "delete", ownerRole), fieldNames, input.vocabulary, "delete"),
+            read: parseRule(`${at}.rules.read`, rawRules.read ?? defaultFor(scope, "read", ownerRole), fieldNames, input.vocabulary, "read", pctx),
+            create: parseRule(`${at}.rules.create`, rawRules.create ?? write ?? defaultFor(scope, "create", ownerRole), fieldNames, input.vocabulary, "create", pctx),
+            update: parseRule(`${at}.rules.update`, rawRules.update ?? write ?? defaultFor(scope, "update", ownerRole), fieldNames, input.vocabulary, "update", pctx),
+            delete: parseRule(`${at}.rules.delete`, rawRules.delete ?? write ?? defaultFor(scope, "delete", ownerRole), fieldNames, input.vocabulary, "delete", pctx),
         };
-        const filterable = [
-            ...new Set([
-                ...PLATFORM_FILTERABLE,
-                ...unique.flat(),
-                ...indexes.flatMap((i) => i.fields),
-            ]),
-        ].sort();
         models[name] = {
             name,
             key: camelKey(name),
@@ -287,7 +373,8 @@ export function compileRules(input) {
             rules,
         };
     }
-    return { version: 1, pluginId: input.pluginId, models };
+    const custom = compileEnvelope(input.custom, Object.fromEntries(Object.entries(models).map(([name, m]) => [name, { fields: Object.keys(m.fields), filterable: m.filterable }])), input.surfaces ?? [], attributes);
+    return { version: 1, pluginId: input.pluginId, models, custom, attributes };
 }
 /**
  * With nothing declared, only the owner. The safe default is the one that
@@ -313,6 +400,10 @@ function defaultRoleFor(input) {
         return input.ownerRole;
     return input.vocabulary.includes("owner") ? "owner" : "internal";
 }
+/** The attribute values a scoped rule reads: the grant's, or the composed role's (the same grant, carried twice). */
+function attrsOf(v) {
+    return v.attrs ?? v.custom?.attrs;
+}
 function principalOutcome(p, v, ctx) {
     switch (p.t) {
         case "anyone":
@@ -323,8 +414,17 @@ function principalOutcome(p, v, ctx) {
         case "creator":
             // Never a check: this becomes `ownerId IN viewerIds` on the query.
             return v.viewerIds.length ? "own-rows" : "no";
-        case "role":
-            return v.role === p.role ? "grant" : "no";
+        case "role": {
+            if (v.role !== p.role)
+                return "no";
+            if (!p.where)
+                return "grant";
+            // Scoped: the rows the where names, with this person's attributes filled in.
+            // An attribute they were never given is "no" — this principal grants nothing;
+            // another principal (their own rows, say) may still.
+            const where = resolveWhere(p.where, attrsOf(v));
+            return where === false ? "no" : { scoped: where };
+        }
         case "apps":
             return ctx.viaBinding ? "grant" : "no";
         case "internal":
@@ -337,6 +437,15 @@ function principalOutcome(p, v, ctx) {
         }
     }
 }
+const OPEN = { where: null, hide: [], updateFields: null, transitions: null };
+/** The composed role's narrowing of this model — nothing, for a caller who holds none. */
+function narrowOf(model, viewer) {
+    return viewer.custom ? narrowingFor(viewer.custom, model.name) : OPEN;
+}
+/** A scoped principal's rows, on top of whatever a composed role already narrowed: both apply. */
+function scopedBy(narrow, where) {
+    return { ...narrow, where: mergeWhere(narrow.where, where) };
+}
 /**
  * What this caller may READ. Never refuses — see the header. A caller with no
  * grant gets `visible: false`, which the client turns into an empty result,
@@ -344,23 +453,44 @@ function principalOutcome(p, v, ctx) {
  */
 export function planRead(model, viewer, ctx = {}) {
     if (viewer.kind === "internal")
-        return { visible: true, ownerIn: null };
+        return { visible: true, ownerIn: null, narrow: OPEN };
     // A user-scoped model ignores rules: your rows, nobody else's.
     if (model.scope === "user") {
-        return viewer.viewerIds.length ? { visible: true, ownerIn: viewer.viewerIds } : { visible: false, ownerIn: null };
+        return viewer.viewerIds.length ? { visible: true, ownerIn: viewer.viewerIds, narrow: OPEN } : { visible: false, ownerIn: null, narrow: OPEN };
     }
+    // A composed role scoped by an attribute its holder lacks sees nothing at all.
+    const narrow = narrowOf(model, viewer);
+    if (narrow.where === false)
+        return { visible: false, ownerIn: null, narrow };
     let ownRows = false;
+    let scoped = null;
     for (const p of model.rules.read.principals) {
         const outcome = principalOutcome(p, viewer, ctx);
         if (outcome === "grant")
-            return { visible: true, ownerIn: null };
+            return { visible: true, ownerIn: null, narrow };
         if (outcome === "own-rows")
             ownRows = true;
+        else if (typeof outcome === "object")
+            scoped = outcome.scoped;
     }
     // `creator` only makes sense on a model that records one.
     if (ownRows && model.ownedByCreator)
-        return { visible: true, ownerIn: viewer.viewerIds };
-    return { visible: false, ownerIn: null };
+        return { visible: true, ownerIn: viewer.viewerIds, narrow };
+    if (scoped) {
+        const n = scopedBy(narrow, scoped);
+        return n.where === false ? { visible: false, ownerIn: null, narrow: n } : { visible: true, ownerIn: null, narrow: n };
+    }
+    return { visible: false, ownerIn: null, narrow };
+}
+/** The writable set a composed role leaves: the rule's, intersected with the role's, minus what it hides. */
+function narrowFields(op, fields, narrow, all) {
+    let out = fields;
+    if (op === "update" && narrow.updateFields) {
+        out = (out ?? all).filter((f) => narrow.updateFields.includes(f));
+    }
+    if (narrow.hide.length)
+        out = (out ?? all).filter((f) => !narrow.hide.includes(f));
+    return out;
 }
 /**
  * What this caller may CREATE, UPDATE or DELETE. Unlike a read, a write does
@@ -368,16 +498,22 @@ export function planRead(model, viewer, ctx = {}) {
  */
 export function planWrite(model, op, viewer, ctx = {}) {
     if (viewer.kind === "internal")
-        return { ok: true, ownerIn: null, fields: null };
+        return { ok: true, ownerIn: null, fields: null, narrow: OPEN };
     if (model.scope === "user") {
         // A row that belongs to an account needs an account to belong to.
         if (!viewer.userId) {
             return { ok: false, code: "login-required", detail: `${model.name} rows belong to an account; this caller has none` };
         }
-        return { ok: true, ownerIn: viewer.viewerIds, fields: null };
+        return { ok: true, ownerIn: viewer.viewerIds, fields: null, narrow: OPEN };
     }
+    const narrow = narrowOf(model, viewer);
+    if (narrow.where === false) {
+        return { ok: false, code: "forbidden", detail: `${model.name}.${op}: this role is scoped by an attribute its holder was never given` };
+    }
+    const all = Object.keys(model.fields);
     const rule = model.rules[op];
     let sawNeedsAccount = false;
+    let scoped = null;
     for (const p of rule.principals) {
         const outcome = principalOutcome(p, viewer, ctx);
         if (outcome === "grant") {
@@ -388,7 +524,7 @@ export function planWrite(model, op, viewer, ctx = {}) {
                     detail: `${model.name}.${op} requires a signed-in account`,
                 };
             }
-            return { ok: true, ownerIn: null, fields: rule.fields };
+            return { ok: true, ownerIn: null, fields: narrowFields(op, rule.fields, narrow, all), narrow };
         }
         if (outcome === "needs-account")
             sawNeedsAccount = true;
@@ -396,13 +532,25 @@ export function planWrite(model, op, viewer, ctx = {}) {
             if (rule.requiresAccount && !viewer.userId) {
                 return { ok: false, code: "login-required", detail: `${model.name}.${op} requires a signed-in account` };
             }
-            return { ok: true, ownerIn: viewer.viewerIds, fields: rule.fields };
+            return { ok: true, ownerIn: viewer.viewerIds, fields: narrowFields(op, rule.fields, narrow, all), narrow };
         }
+        if (typeof outcome === "object")
+            scoped = outcome.scoped;
+    }
+    // A scoped role: only the rows its where names (an update or delete outside
+    // them finds no row; a create must land inside them — the client fills or refuses).
+    if (scoped) {
+        if (rule.requiresAccount && !viewer.userId)
+            return { ok: false, code: "login-required", detail: `${model.name}.${op} requires a signed-in account` };
+        const n = scopedBy(narrow, scoped);
+        if (n.where === false)
+            return { ok: false, code: "forbidden", detail: `${model.name}.${op}: this role is scoped by an attribute its holder was never given` };
+        return { ok: true, ownerIn: null, fields: narrowFields(op, rule.fields, n, all), narrow: n };
     }
     // `creatorMay` is the last door: not your role, but your row, and only the
     // fields the app said a creator may touch (an order's note, never its price).
     if (op === "update" && rule.creatorMay && model.ownedByCreator && viewer.viewerIds.length) {
-        return { ok: true, ownerIn: viewer.viewerIds, fields: rule.creatorMay };
+        return { ok: true, ownerIn: viewer.viewerIds, fields: narrowFields(op, rule.creatorMay, narrow, all), narrow };
     }
     if (sawNeedsAccount || (rule.requiresAccount && !viewer.userId)) {
         return { ok: false, code: "login-required", detail: `${model.name}.${op} requires a signed-in account` };
@@ -416,7 +564,7 @@ export function planWrite(model, op, viewer, ctx = {}) {
 function describe(principals) {
     if (!principals.length)
         return "nobody";
-    return principals.map((p) => (p.t === "role" ? p.role : p.t)).join(", ");
+    return principals.map((p) => (p.t === "role" ? (p.where ? `${p.role} (scoped)` : p.role) : p.t)).join(", ");
 }
 /** May this caller see the sealed fields of a row they can otherwise read? */
 export function canUnseal(viewer, row) {