esoul-sdk 0.4.0 → 0.7.0

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

@@ -0,0 +1,229 @@
+/**
+ * THE RULE ENGINE — a manifest's `db` block turned into data, and decisions
+ * taken from that data.
+ *
+ * This module is the heart of the whole access story, and the reason it is
+ * pure, dependency-free and returns DATA is that three different things must
+ * agree about who may see what: the in-memory client an author writes unit
+ * tests against, the Prisma extension production runs, and the workbench box.
+ * If each re-derived the rules, "my tests pass" would mean nothing about
+ * production. So the rules compile ONCE, to a JSON artefact
+ * (`.esoul/rules.json`), and every client reads that same artefact.
+ *
+ * Two decisions are load-bearing and easy to get wrong:
+ *
+ * 1. **A read never refuses.** A row the caller may not see must read as
+ *    ABSENT — `null`, `0`, missing from the list — never as a refusal. A
+ *    refusal is an answer: "forbidden" on someone else's order id confirms
+ *    that the id exists. So read rules compile to a WHERE conjunct and the
+ *    worst case is a filter that matches nothing.
+ *
+ * 2. **"Not signed in" is not "not allowed."** A rule that needs an account
+ *    answers `login-required` to an anonymous caller, so the app can render a
+ *    sign-in wall. Answering `forbidden` there would tell a customer they may
+ *    never order, when the truth is they may, after signing in.
+ */
+/**
+ * What the engine needs to know about a caller — deliberately the narrowest
+ * shape that answers every principal, so this module couples to nothing. The
+ * platform's `PluginViewer` satisfies it structurally; so does a fake one in
+ * an author's unit test.
+ */
+export interface RuleViewer {
+    kind: "owner" | "member" | "visitor" | "anonymous" | "agent" | "internal";
+    /** The esoul account, when there is one. An agent carries its person's. */
+    userId: string | null;
+    /** Every id this caller has acted under (guest cookie ∪ account ∪ linked). */
+    viewerIds: string[];
+    /** The app's own word for this caller. */
+    role: string;
+}
+/**
+ * The closed list. A `default: never` in `principalOutcome` makes adding a
+ * variant here a COMPILE error until it is handled, and the test matrix is
+ * enumerated from `PRINCIPAL_KINDS` so it is also a test failure until it is
+ * proven. Both, because a principal that silently grants nothing looks exactly
+ * like a principal that works.
+ */
+export type Principal = 
+/** Anyone at all, signed in or not. */
+{
+    t: "anyone";
+}
+/** Any signed-in esoul account. */
+ | {
+    t: "account";
+}
+/** The account that created the row. Compiles to a filter, never a check. */
+ | {
+    t: "creator";
+}
+/** A caller holding this role in this app. */
+ | {
+    t: "role";
+    role: string;
+}
+/** Another app reading through a binding it was granted (`uses`/`provides`). */
+ | {
+    t: "apps";
+}
+/** This app's own server code — a task, a sweep, one op calling another. */
+ | {
+    t: "internal";
+};
+export declare const PRINCIPAL_KINDS: readonly ["anyone", "account", "creator", "role", "apps", "internal"];
+export type PrincipalKind = (typeof PRINCIPAL_KINDS)[number];
+export type Scope = "instance" | "workspace" | "user";
+export type RuleOp = "read" | "create" | "update" | "delete";
+export declare const RULE_OPS: readonly RuleOp[];
+export type FieldType = "string" | "text" | "int" | "float" | "boolean" | "datetime" | "json" | "ref";
+export interface CompiledField {
+    type: FieldType;
+    /** Set when `type === "ref"`: the model this points at (always this app's). */
+    ref?: string;
+    optional: boolean;
+    list: boolean;
+    default?: string | number | boolean;
+}
+export interface CompiledRule {
+    principals: Principal[];
+    /** `requires: "account"` — an anonymous caller gets `login-required`. */
+    requiresAccount: boolean;
+    /** `update` only: fields the row's creator may write even without a role. */
+    creatorMay: string[] | null;
+    /** When set, the only fields this rule permits writing at all. */
+    fields: string[] | null;
+}
+/**
+ * HOW an index is built, named by what the author wants to DO with it rather
+ * than by the mechanism:
+ *
+ * - `btree` (a plain `["a","b"]` group) — equality, ranges, ordering. Led by
+ *   the scope column, because every query the platform issues narrows to an
+ *   instance first.
+ * - `contains` — a LIST field, so `where: { tags: { has: "gifts" } }` is an
+ *   index lookup instead of a scan. Becomes a GIN index.
+ * - `text` — a string or text field, so `where: { name: { contains: "grey" } }`
+ *   is an index lookup. Becomes a GIN trigram index, which is the only kind
+ *   that can serve a substring search; a btree cannot.
+ *
+ * The last two are single-column and NOT scope-led: without `btree_gin` a GIN
+ * index cannot lead with the scope column, so Postgres combines it with the
+ * scope index instead. That is the right plan and it is worth knowing.
+ */
+export type IndexKind = "btree" | "contains" | "text";
+export interface CompiledIndex {
+    fields: string[];
+    kind: IndexKind;
+}
+export interface CompiledModel {
+    /** As declared: `Order`. */
+    name: string;
+    /** As called on the client: `order`. */
+    key: string;
+    scope: Scope;
+    /** `owner: "creator"` — rows belong to whoever created them. */
+    ownedByCreator: boolean;
+    fields: Record<string, CompiledField>;
+    sealed: string[];
+    unique: string[][];
+    indexes: CompiledIndex[];
+    /**
+     * Every field a `where` or `orderBy` may name. An unindexed filter is a
+     * table scan waiting to happen at a customer's scale, so it is refused with
+     * the index to add — the rule lands in the author's editor (the generated
+     * types key `orderBy` by exactly this list) and again at runtime.
+     */
+    filterable: string[];
+    rules: Record<RuleOp, CompiledRule>;
+}
+export interface CompiledRules {
+    version: 1;
+    pluginId: string;
+    models: Record<string, CompiledModel>;
+}
+/** 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"];
+/** Platform columns a caller may filter or sort by (each one is indexed). */
+export declare const PLATFORM_FILTERABLE: readonly ["id", "createdAt", "ownerId"];
+/** Scope keys an app may never supply itself — the platform injects them. */
+export declare const INJECTED_COLUMNS: readonly ["workspaceId", "nodeId", "ownerId", "createdBy"];
+/** Raw `db` block as it appears in plugin.json. */
+export interface ManifestDbModel {
+    scope?: string;
+    owner?: string;
+    fields: Record<string, string>;
+    sealed?: string[];
+    unique?: string[][];
+    /**
+     * A plain group (`["active","createdAt"]`) is a btree. An object names a
+     * kind: `{ fields: ["tags"], kind: "contains" }` for a list, or
+     * `{ fields: ["title"], kind: "text" }` for substring search.
+     */
+    indexes?: (string[] | {
+        fields: string[];
+        kind?: "btree" | "contains" | "text";
+    })[];
+    rules?: Record<string, unknown>;
+}
+export interface CompileInput {
+    pluginId: string;
+    db: Record<string, ManifestDbModel>;
+    /** From `roles.vocabulary`; a rule may only name a role this app declares. */
+    vocabulary?: string[];
+    /**
+     * From `roles.default.owner` — this app's own word for the workspace owner.
+     * It is what a model with NO rules falls back to, so an app whose vocabulary
+     * has no word spelled "owner" still gets the safe default rather than a
+     * compile error about a rule its author never wrote.
+     */
+    ownerRole?: string;
+}
+/** An authoring mistake. Thrown at build time, never at request time. */
+export declare class RuleCompileError extends Error {
+    readonly keyPath: string;
+    constructor(keyPath: string, message: string);
+}
+export declare function camelKey(model: string): string;
+/**
+ * Compile a manifest's `db` block. Throws `RuleCompileError` with the key path
+ * and the allowed values for anything an author got wrong — this runs at build
+ * and in the workbench, where a precise message is the whole product.
+ */
+export declare function compileRules(input: CompileInput): CompiledRules;
+export interface PlanContext {
+    /** True when this app is being read through a binding another app holds. */
+    viaBinding?: boolean;
+}
+export interface ReadPlan {
+    /** False ⇒ the caller sees nothing: a filter that matches no row. */
+    visible: boolean;
+    /** When set, only rows whose `ownerId` is in this list. */
+    ownerIn: string[] | null;
+}
+/**
+ * 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,
+ * so an id they may not see is indistinguishable from an id that never was.
+ */
+export declare function planRead(model: CompiledModel, viewer: RuleViewer, ctx?: PlanContext): ReadPlan;
+export type WritePlan = {
+    ok: true;
+    /** When set, only rows this caller owns. */
+    ownerIn: string[] | null;
+    /** When set, the only fields this caller may write. */
+    fields: string[] | null;
+} | {
+    ok: false;
+    code: "forbidden" | "login-required";
+    detail: string;
+};
+/**
+ * What this caller may CREATE, UPDATE or DELETE. Unlike a read, a write does
+ * refuse — and distinguishes "sign in first" from "never".
+ */
+export declare function planWrite(model: CompiledModel, op: Exclude<RuleOp, "read">, viewer: RuleViewer, ctx?: PlanContext): WritePlan;
+/** May this caller see the sealed fields of a row they can otherwise read? */
+export declare function canUnseal(viewer: RuleViewer, row: {
+    ownerId?: string | null;
+}): boolean;

package/dist/db/compile-rules.js

@@ -0,0 +1,426 @@
+/**
+ * THE RULE ENGINE — a manifest's `db` block turned into data, and decisions
+ * taken from that data.
+ *
+ * This module is the heart of the whole access story, and the reason it is
+ * pure, dependency-free and returns DATA is that three different things must
+ * agree about who may see what: the in-memory client an author writes unit
+ * tests against, the Prisma extension production runs, and the workbench box.
+ * If each re-derived the rules, "my tests pass" would mean nothing about
+ * production. So the rules compile ONCE, to a JSON artefact
+ * (`.esoul/rules.json`), and every client reads that same artefact.
+ *
+ * Two decisions are load-bearing and easy to get wrong:
+ *
+ * 1. **A read never refuses.** A row the caller may not see must read as
+ *    ABSENT — `null`, `0`, missing from the list — never as a refusal. A
+ *    refusal is an answer: "forbidden" on someone else's order id confirms
+ *    that the id exists. So read rules compile to a WHERE conjunct and the
+ *    worst case is a filter that matches nothing.
+ *
+ * 2. **"Not signed in" is not "not allowed."** A rule that needs an account
+ *    answers `login-required` to an anonymous caller, so the app can render a
+ *    sign-in wall. Answering `forbidden` there would tell a customer they may
+ *    never order, when the truth is they may, after signing in.
+ */
+export const PRINCIPAL_KINDS = ["anyone", "account", "creator", "role", "apps", "internal"];
+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. */
+export const PLATFORM_COLUMNS = [
+    "id",
+    "workspaceId",
+    "nodeId",
+    "ownerId",
+    "createdBy",
+    "createdAt",
+    "updatedAt",
+    "deletedAt",
+];
+/** Platform columns a caller may filter or sort by (each one is indexed). */
+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"];
+/** An authoring mistake. Thrown at build time, never at request time. */
+export class RuleCompileError extends Error {
+    keyPath;
+    constructor(keyPath, message) {
+        super(`${keyPath}: ${message}`);
+        this.keyPath = keyPath;
+        this.name = "RuleCompileError";
+    }
+}
+const FIELD_TYPES = ["string", "text", "int", "float", "boolean", "datetime", "json"];
+// Positional groups, not named ones: the repo-wide tsc targets below ES2018.
+// [1] base type, [2] "[]" for a list, [3] "?" for optional, [4] the default.
+const FIELD_SPEC = /^([a-z]+|ref:[A-Za-z][A-Za-z0-9_]*)(\[\])?(\?)?(?:=(.*))?$/;
+export function camelKey(model) {
+    return model.charAt(0).toLowerCase() + model.slice(1);
+}
+function parseField(keyPath, spec, models) {
+    const m = FIELD_SPEC.exec(spec);
+    if (!m) {
+        throw new RuleCompileError(keyPath, `unreadable field spec "${spec}" — allowed: ${FIELD_TYPES.join(", ")}, ref:<Model>; suffix ? for optional, [] for a list, =value for a default`);
+    }
+    const [, base, list, opt, def] = m;
+    const isRef = base.startsWith("ref:");
+    const type = isRef ? "ref" : base;
+    if (!isRef && !FIELD_TYPES.includes(type)) {
+        throw new RuleCompileError(keyPath, `unknown type "${base}" — allowed: ${FIELD_TYPES.join(", ")}, ref:<Model>`);
+    }
+    const ref = isRef ? base.slice(4) : undefined;
+    if (ref && !models.includes(ref)) {
+        throw new RuleCompileError(keyPath, `ref:${ref} names no model of this app — declared: ${models.join(", ") || "(none)"}. A relation to a platform table is never allowed.`);
+    }
+    const field = { type, optional: !!opt, list: !!list };
+    if (ref)
+        field.ref = ref;
+    if (def !== undefined) {
+        field.default =
+            type === "int" || type === "float"
+                ? Number(def)
+                : type === "boolean"
+                    ? def === "true"
+                    : def;
+        if ((type === "int" || type === "float") && Number.isNaN(field.default)) {
+            throw new RuleCompileError(keyPath, `default "${def}" is not a number`);
+        }
+    }
+    return field;
+}
+function parsePrincipal(keyPath, raw, vocabulary) {
+    switch (raw) {
+        case "anyone":
+            return { t: "anyone" };
+        case "account":
+            return { t: "account" };
+        case "creator":
+            return { t: "creator" };
+        case "apps":
+            return { t: "apps" };
+        case "internal":
+            return { t: "internal" };
+        default:
+            break;
+    }
+    if (vocabulary && !vocabulary.includes(raw)) {
+        throw new RuleCompileError(keyPath, `"${raw}" is neither a principal nor a role this app declares — principals: anyone, account, creator, apps, internal; roles: ${vocabulary.join(", ") || "(none declared)"}`);
+    }
+    return { t: "role", role: raw };
+}
+function parseRule(keyPath, raw, fields, vocabulary, op) {
+    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)] };
+    }
+    if (Array.isArray(raw)) {
+        return {
+            ...empty,
+            principals: raw.map((p, i) => parsePrincipal(`${keyPath}[${i}]`, String(p), vocabulary)),
+        };
+    }
+    if (typeof raw !== "object" || raw === null) {
+        throw new RuleCompileError(keyPath, `a rule is "anyone", a list of principals, or an object — got ${typeof raw}`);
+    }
+    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 checkFields = (list, label) => {
+        if (list === undefined)
+            return null;
+        if (!Array.isArray(list))
+            throw new RuleCompileError(`${keyPath}.${label}`, "must be a list of field names");
+        for (const f of list) {
+            if (!fields.includes(String(f))) {
+                throw new RuleCompileError(`${keyPath}.${label}`, `"${f}" is not a declared field — declared: ${fields.join(", ")}`);
+            }
+        }
+        return list.map(String);
+    };
+    const creatorMay = checkFields(o.creatorMay, "creatorMay");
+    if (creatorMay && op !== "update") {
+        throw new RuleCompileError(`${keyPath}.creatorMay`, "only an `update` rule may narrow what a creator writes");
+    }
+    if (o.requires !== undefined && o.requires !== "account") {
+        throw new RuleCompileError(`${keyPath}.requires`, `only "account" is a requirement — got "${String(o.requires)}"`);
+    }
+    return {
+        principals,
+        requiresAccount: o.requires === "account",
+        creatorMay,
+        fields: checkFields(o.fields, "fields"),
+    };
+}
+/**
+ * Compile a manifest's `db` block. Throws `RuleCompileError` with the key path
+ * and the allowed values for anything an author got wrong — this runs at build
+ * and in the workbench, where a precise message is the whole product.
+ */
+export function compileRules(input) {
+    const modelNames = Object.keys(input.db ?? {});
+    const ownerRole = defaultRoleFor(input);
+    const models = {};
+    for (const name of modelNames) {
+        const raw = input.db[name];
+        const at = `db.${name}`;
+        if (!raw || typeof raw !== "object")
+            throw new RuleCompileError(at, "must be an object");
+        if (!/^[A-Z][A-Za-z0-9]{0,40}$/.test(name)) {
+            throw new RuleCompileError(at, "a model name is CamelCase, starts with a capital, at most 41 characters");
+        }
+        const scope = (raw.scope ?? "instance");
+        if (!["instance", "workspace", "user"].includes(scope)) {
+            throw new RuleCompileError(`${at}.scope`, `unknown scope "${raw.scope}" — allowed: instance, workspace, user`);
+        }
+        if (raw.owner !== undefined && raw.owner !== "creator") {
+            throw new RuleCompileError(`${at}.owner`, `only "creator" is an owner — got "${raw.owner}"`);
+        }
+        const fieldNames = Object.keys(raw.fields ?? {});
+        if (!fieldNames.length)
+            throw new RuleCompileError(`${at}.fields`, "a model declares at least one field");
+        const fields = {};
+        for (const f of fieldNames) {
+            if (PLATFORM_COLUMNS.includes(f)) {
+                throw new RuleCompileError(`${at}.fields.${f}`, `"${f}" is a column the platform owns and stamps — it may not be declared. Platform columns: ${PLATFORM_COLUMNS.join(", ")}`);
+            }
+            fields[f] = parseField(`${at}.fields.${f}`, String(raw.fields[f]), modelNames);
+        }
+        // An index may also name a platform column that exists on every row —
+        // `createdAt` above all, because paging a customer's orders newest-first is
+        // the first thing every app does. The scope columns are indexed by the
+        // platform already and are not an app's to declare.
+        const INDEXABLE_PLATFORM = ["id", "createdAt", "updatedAt", "ownerId"];
+        const checkColumns = (groups, label) => {
+            if (!groups)
+                return [];
+            for (const group of groups) {
+                for (const col of group) {
+                    if (!fieldNames.includes(col) && !INDEXABLE_PLATFORM.includes(col)) {
+                        throw new RuleCompileError(`${at}.${label}`, `"${col}" is neither a declared field nor an indexable platform column — declared: ${fieldNames.join(", ")}; platform: ${INDEXABLE_PLATFORM.join(", ")}`);
+                    }
+                }
+            }
+            return groups.map((g) => [...g]);
+        };
+        const unique = checkColumns(raw.unique, "unique");
+        /**
+         * `indexes` takes a plain group (`["active","createdAt"]`) or a kind
+         * (`{ "fields": ["tags"], "kind": "contains" }`). A kind is refused when
+         * the field cannot support it, by name — an author who indexed a list for
+         * text search would otherwise get a working build and a sequential scan
+         * at their customers' expense.
+         */
+        const indexes = (raw.indexes ?? []).map((entry, i) => {
+            const where = `${at}.indexes[${i}]`;
+            if (Array.isArray(entry))
+                return { fields: checkColumns([entry], "indexes")[0], kind: "btree" };
+            if (!entry || typeof entry !== "object") {
+                throw new RuleCompileError(where, 'an index is a list of columns (["a","b"]) or { "fields": [...], "kind": "contains" | "text" }');
+            }
+            const e = entry;
+            if (!Array.isArray(e.fields) || !e.fields.length)
+                throw new RuleCompileError(`${where}.fields`, "name at least one field");
+            const flds = checkColumns([e.fields.map(String)], "indexes")[0];
+            const kind = e.kind === undefined ? "btree" : String(e.kind);
+            if (kind !== "btree" && kind !== "contains" && kind !== "text") {
+                throw new RuleCompileError(`${where}.kind`, `unknown kind "${kind}" — allowed: btree, contains, text`);
+            }
+            if (kind !== "btree") {
+                if (flds.length !== 1)
+                    throw new RuleCompileError(`${where}.fields`, `a "${kind}" index covers exactly one field`);
+                const f = fields[flds[0]];
+                if (!f)
+                    throw new RuleCompileError(`${where}.fields`, `"${flds[0]}" is a platform column; a "${kind}" index covers one of your own fields`);
+                if (kind === "contains" && !f.list) {
+                    throw new RuleCompileError(`${where}`, `"${flds[0]}" is not a list — a "contains" index is for a list field (e.g. "tags": "string[]"). For substring search on text use "kind": "text".`);
+                }
+                if (kind === "text" && (f.list || (f.type !== "string" && f.type !== "text"))) {
+                    throw new RuleCompileError(`${where}`, `"${flds[0]}" is ${f.list ? "a list" : `a ${f.type}`} — a "text" index is for a single string or text field.`);
+                }
+            }
+            return { fields: flds, kind };
+        });
+        const sealed = raw.sealed ?? [];
+        for (const f of sealed) {
+            if (!fieldNames.includes(f)) {
+                throw new RuleCompileError(`${at}.sealed`, `"${f}" is not a declared field — declared: ${fieldNames.join(", ")}`);
+            }
+        }
+        // A user-scoped model belongs to ONE account and nobody else reads it. A
+        // rule there could only ever widen that, so it is refused rather than
+        // quietly ignored — an author who wrote one believed something false.
+        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 rawRules = (raw.rules ?? {});
+        for (const key of Object.keys(rawRules)) {
+            if (!["read", "create", "update", "delete", "write"].includes(key)) {
+                throw new RuleCompileError(`${at}.rules.${key}`, "allowed: read, create, update, delete, write");
+            }
+        }
+        const write = rawRules.write;
+        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"),
+        };
+        const filterable = [
+            ...new Set([
+                ...PLATFORM_FILTERABLE,
+                ...unique.flat(),
+                ...indexes.flatMap((i) => i.fields),
+            ]),
+        ].sort();
+        models[name] = {
+            name,
+            key: camelKey(name),
+            scope,
+            ownedByCreator: raw.owner === "creator",
+            fields,
+            sealed: [...sealed],
+            unique,
+            indexes,
+            filterable,
+            rules,
+        };
+    }
+    return { version: 1, pluginId: input.pluginId, models };
+}
+/**
+ * With nothing declared, only the owner. The safe default is the one that
+ * cannot leak: an author who forgets a rule gets an app that works for them
+ * and refuses everyone else, which they notice immediately.
+ */
+function defaultFor(scope, _op, ownerRole) {
+    return scope === "user" ? undefined : [ownerRole];
+}
+/**
+ * WHOSE word the missing rule names. An app that declares no vocabulary means
+ * the plain word "owner". An app that declares one means ITS word for the
+ * workspace owner, which is why `roles.default.owner` is read here — otherwise
+ * an app whose people are called "requester" and "agent" would fail to compile
+ * on a rule its author never wrote. An app that gives the owner no word at all
+ * (`"none"`) gets the only default that cannot leak and cannot crash: its own
+ * server code, and nobody else, until the author writes a rule.
+ */
+function defaultRoleFor(input) {
+    if (!input.vocabulary?.length)
+        return "owner";
+    if (input.ownerRole && input.vocabulary.includes(input.ownerRole))
+        return input.ownerRole;
+    return input.vocabulary.includes("owner") ? "owner" : "internal";
+}
+function principalOutcome(p, v, ctx) {
+    switch (p.t) {
+        case "anyone":
+            return "grant";
+        case "account":
+            // An agent acting for a signed-in person IS that account.
+            return v.userId ? "grant" : "needs-account";
+        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 "apps":
+            return ctx.viaBinding ? "grant" : "no";
+        case "internal":
+            return v.kind === "internal" ? "grant" : "no";
+        default: {
+            // Adding a principal without handling it here is a COMPILE error.
+            const exhaustive = p;
+            void exhaustive;
+            return "no";
+        }
+    }
+}
+/**
+ * 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,
+ * so an id they may not see is indistinguishable from an id that never was.
+ */
+export function planRead(model, viewer, ctx = {}) {
+    if (viewer.kind === "internal")
+        return { visible: true, ownerIn: null };
+    // 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 };
+    }
+    let ownRows = false;
+    for (const p of model.rules.read.principals) {
+        const outcome = principalOutcome(p, viewer, ctx);
+        if (outcome === "grant")
+            return { visible: true, ownerIn: null };
+        if (outcome === "own-rows")
+            ownRows = true;
+    }
+    // `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 };
+}
+/**
+ * What this caller may CREATE, UPDATE or DELETE. Unlike a read, a write does
+ * refuse — and distinguishes "sign in first" from "never".
+ */
+export function planWrite(model, op, viewer, ctx = {}) {
+    if (viewer.kind === "internal")
+        return { ok: true, ownerIn: null, fields: null };
+    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 };
+    }
+    const rule = model.rules[op];
+    let sawNeedsAccount = false;
+    for (const p of rule.principals) {
+        const outcome = principalOutcome(p, viewer, ctx);
+        if (outcome === "grant") {
+            if (rule.requiresAccount && !viewer.userId) {
+                return {
+                    ok: false,
+                    code: "login-required",
+                    detail: `${model.name}.${op} requires a signed-in account`,
+                };
+            }
+            return { ok: true, ownerIn: null, fields: rule.fields };
+        }
+        if (outcome === "needs-account")
+            sawNeedsAccount = true;
+        if (outcome === "own-rows" && model.ownedByCreator) {
+            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 };
+        }
+    }
+    // `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 };
+    }
+    if (sawNeedsAccount || (rule.requiresAccount && !viewer.userId)) {
+        return { ok: false, code: "login-required", detail: `${model.name}.${op} requires a signed-in account` };
+    }
+    return {
+        ok: false,
+        code: "forbidden",
+        detail: `${model.name}.${op} allows ${describe(rule.principals)}; this caller is ${viewer.kind}/${viewer.role}`,
+    };
+}
+function describe(principals) {
+    if (!principals.length)
+        return "nobody";
+    return principals.map((p) => (p.t === "role" ? p.role : p.t)).join(", ");
+}
+/** May this caller see the sealed fields of a row they can otherwise read? */
+export function canUnseal(viewer, row) {
+    if (viewer.kind === "internal")
+        return true;
+    return !!row.ownerId && viewer.viewerIds.includes(row.ownerId);
+}