esoul-sdk 0.4.0 → 0.6.0

package/dist/bindings.js

@@ -0,0 +1,163 @@
+/**
+ * WHAT STANDS BEHIND A SLOT.
+ *
+ * An app is an island until it can lean on another one. A storefront that
+ * wants real stock either keeps its own products table and guesses, or names
+ * a specific inventory app and is married to it forever. Neither is what a
+ * person means when they say "use my warehouse for this shop".
+ *
+ * So an app declares a SLOT and the CONTRACT it needs:
+ *
+ *   "uses": { "stock": { "contract": "stock/v1", "label": "Stock" } }
+ *
+ * and any app that can do the job declares that it does:
+ *
+ *   "provides": { "stock/v1": { "tools": ["reserve_stock"], "events": ["stock_low"], "models": ["Product"] } }
+ *
+ * The owner picks which app fills the slot, and the platform checks — at BIND
+ * time, once, loudly — that the provider really has every tool, event and
+ * table the contract names. Not at call time, where a missing tool is an
+ * error in front of a customer.
+ *
+ * Versions grow by ADDING. A provider on `stock/v2` satisfies a consumer
+ * asking for `stock/v1`, because v2 still has everything v1 named; the
+ * reverse is refused, because v1 has never heard of what v2 added. That one
+ * rule is what lets a storefront keep working while its provider moves on.
+ *
+ * Pure: no platform, no transport. The bind-time check, the workbench picker
+ * and the author's own tests all read this.
+ */
+export function parseContractId(raw) {
+    const m = /^([a-z][a-z0-9-]*)\/v(\d+)$/.exec(raw ?? "");
+    if (!m)
+        return null;
+    const version = Number(m[2]);
+    return Number.isSafeInteger(version) && version > 0 ? { name: m[1], version } : null;
+}
+export function formatContractId(c) {
+    return `${c.name}/v${c.version}`;
+}
+/**
+ * May this app fill this slot? Every reason it may not, in the author's
+ * words — a picker shows them, and a bind refuses on any of them.
+ *
+ * `contract` is the DEFINITION (what the contract requires). `facts` is what
+ * the candidate app really has. A provider's own `provides` block is a claim,
+ * and a claim is checked against both.
+ */
+export function checkBinding(args) {
+    const { wanted, contract, facts } = args;
+    const want = parseContractId(wanted);
+    if (!want)
+        return { ok: false, reasons: [`"${wanted}" is not a contract id — they look like "stock/v1"`] };
+    if (!contract)
+        return { ok: false, reasons: [`no contract "${wanted}" is known to this platform`] };
+    // The provider's claim: same name, version at least as high. Versions grow
+    // by adding, so a v2 provider still does everything v1 promised.
+    const claims = Object.keys(facts.provides)
+        .map((id) => ({ id, parsed: parseContractId(id) }))
+        .filter((c) => !!c.parsed && c.parsed.name === want.name);
+    if (!claims.length) {
+        return { ok: false, reasons: [`${facts.applicationType} does not provide "${want.name}"`] };
+    }
+    const usable = claims.filter((c) => c.parsed.version >= want.version).sort((a, b) => a.parsed.version - b.parsed.version)[0];
+    if (!usable) {
+        const best = claims.map((c) => c.id).join(", ");
+        return { ok: false, reasons: [`${facts.applicationType} provides ${best}, which is older than ${wanted} — a slot may be filled by the same version or a newer one, never an older one`] };
+    }
+    const decl = facts.provides[usable.id] ?? {};
+    const reasons = [];
+    const check = (kind, required, claimed, real) => {
+        for (const name of required) {
+            if (!(claimed ?? []).includes(name))
+                reasons.push(`${usable.id} does not offer the ${kind} "${name}" that ${wanted} requires`);
+            else if (!real.includes(name))
+                reasons.push(`${facts.applicationType} claims the ${kind} "${name}" but does not have it`);
+        }
+    };
+    check("tool", contract.tools, decl.tools, facts.tools);
+    check("event", contract.events, decl.events, facts.events);
+    check("table", contract.models, decl.models, facts.models);
+    if (reasons.length)
+        return { ok: false, reasons };
+    return { ok: true, via: usable.id, tools: decl.tools ?? [], events: decl.events ?? [], models: decl.models ?? [] };
+}
+/**
+ * The reducer behind `plugin/binding_set`. Deterministic: setting a slot
+ * replaces it, binding an empty nodeId clears it, and an unknown slot is
+ * ignored rather than invented — the slots are the manifest's, not the
+ * event's.
+ */
+export function reduceBinding(current, event, knownSlots) {
+    const slot = typeof event.slot === "string" ? event.slot : "";
+    if (!slot || !knownSlots.includes(slot))
+        return current;
+    const nodeId = typeof event.nodeId === "string" ? event.nodeId : "";
+    if (!nodeId) {
+        if (!(slot in current))
+            return current;
+        const { [slot]: _gone, ...rest } = current;
+        return rest;
+    }
+    return {
+        ...current,
+        [slot]: {
+            nodeId,
+            applicationType: typeof event.applicationType === "string" ? event.applicationType : "",
+            via: typeof event.via === "string" ? event.via : "",
+            ...(typeof event.at === "number" ? { boundAt: event.at } : {}),
+        },
+    };
+}
+/** The slots a manifest declares that nothing fills yet — the ones a seam refuses on. */
+export function unfilledRequiredSlots(uses, bindings) {
+    return Object.keys(uses ?? {}).filter((slot) => !uses[slot].optional && !bindings[slot]);
+}
+export function bindingEventName(applicationType) {
+    return `${applicationType}_binding_set`;
+}
+/**
+ * The event definition for one app's slots. `knownSlots` comes from the
+ * manifest, so an event naming a slot the app never declared is ignored
+ * rather than inventing one.
+ *
+ * Typed loosely on purpose: the SDK's `EventDefinition` lives in `types.ts`
+ * and this module stays free of it, so the same file can be read by the
+ * platform, the workbench and an author's tests without dragging the schema
+ * types along.
+ */
+export function defineBindingEvent(args) {
+    const eventName = bindingEventName(args.applicationType);
+    return {
+        eventName,
+        type: "Client",
+        triggerMeta: {
+            displayName: "App binding changed",
+            description: `Fires when someone points one of this app's slots at another app, or clears it. eventData: {slot, nodeId, applicationType, via}.`,
+            sampleVariables: ["event.slot", "event.applicationType"],
+        },
+        dataCreator: (a) => ({
+            eventName,
+            eventData: {
+                slot: String(a.slot ?? ""),
+                nodeId: String(a.nodeId ?? ""),
+                applicationType: String(a.applicationType ?? ""),
+                via: String(a.via ?? ""),
+                at: typeof a.at === "number" ? a.at : Date.now(),
+            },
+            timestamp: Date.now(),
+            workspaceId: a.workspaceId,
+            applicationId: a.applicationId || a.nodeId,
+            instanceName: a.instanceName,
+            chatIdSource: a.chatIdSource,
+        }),
+        processor: (state, event) => {
+            const next = reduceBinding(state._bindings ?? {}, event.eventData ?? {}, args.slots);
+            return next === (state._bindings ?? {}) ? state : { ...state, _bindings: next };
+        },
+    };
+}
+/** The bindings an app currently holds, from its folded state. */
+export function bindingsOf(state) {
+    return state?._bindings ?? {};
+}

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

@@ -0,0 +1,154 @@
+/**
+ * THE CLIENT CORE — everything a plugin database client decides, with nothing
+ * about where the rows live.
+ *
+ * Two clients read an app's tables: the in-memory one an author's unit tests
+ * run against (and the workbench box), and the Prisma one production runs
+ * against. The differential test requires them to agree on every visible set
+ * for every viewer after every operation. That is only credible if they do not
+ * each re-implement the decisions — so the decisions live here, once, and a
+ * client supplies storage: "give me the rows matching this scope", "does a row
+ * with these unique values exist", "fetch this ref target".
+ *
+ * Every function takes the same `Core` handle and REFUSES through the injected
+ * `refuse`, so a refusal raised by a test and a refusal raised by production are
+ * the same object with the same code, and the package still works with no host
+ * attached.
+ *
+ * The one thing deliberately NOT here is `where` evaluation. Memory evaluates a
+ * filter in JS; Prisma hands it to Postgres. Both validate the filter's KEYS
+ * here first, and the differential test is what proves the two evaluators
+ * agree on the values.
+ */
+import { type CompiledModel, type CompiledRules, type ReadPlan, type RuleViewer, type WritePlan } from "./compile-rules.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;
+/** Standalone default so the package works with no host attached. */
+export declare const defaultRefuse: Refuse;
+export type Across = "owned-instances" | "my-rows";
+export type WriteOp = "create" | "update" | "delete";
+export interface ClientScope {
+    workspaceId: string;
+    nodeId: string;
+}
+/** What every decision needs. One per (client, model). */
+export interface Core {
+    rules: CompiledRules;
+    model: CompiledModel;
+    viewer: RuleViewer;
+    scope: ClientScope;
+    refuse: Refuse;
+    /** Read across instances — owner-only / own-rows-only, never for writes. */
+    across?: Across;
+    /** Workspaces this viewer owns, resolved by the PLATFORM, never by the app. */
+    ownedWorkspaceIds: string[];
+    /** True when another app is reading this one through a binding. */
+    viaBinding: boolean;
+}
+export declare const DEFAULT_TAKE = 50;
+export declare const MAX_TAKE = 200;
+export declare const FILTER_OPS: readonly ["in", "notIn", "not", "gt", "gte", "lt", "lte", "contains"];
+export type FilterOp = (typeof FILTER_OPS)[number];
+export declare function bad(c: Core, detail: string): never;
+/**
+ * A caller-supplied scope key is REFUSED, never overridden. An app that sets
+ * its own `nodeId` is either wrong or trying something, and overriding it
+ * quietly would hide both — in the author's tests as much as in production.
+ */
+export declare function assertNoInjectedKeys(c: Core, obj: Record<string, unknown> | undefined, where: string): void;
+/**
+ * Only declared, INDEXED fields (and the platform's indexed columns) may be
+ * filtered or sorted. An unindexed filter is a table scan at a customer's
+ * scale; the refusal names the index to add. The generated types carry the
+ * same list, so an author meets this in the editor first.
+ */
+export declare function assertFilterable(c: Core, keys: string[], where: string): void;
+/** The filter operators a `where` value may use — the same list both evaluators implement. */
+export declare function assertFilterShape(c: Core, where: Record<string, unknown> | undefined): void;
+export type OrderBy = Record<string, "asc" | "desc"> | Record<string, "asc" | "desc">[];
+export declare function orderTerms(c: Core, orderBy: OrderBy | undefined): Record<string, "asc" | "desc">[];
+export declare function pageWindow(c: Core, args: {
+    take?: number;
+    skip?: number;
+} | undefined): {
+    take: number;
+    skip: number;
+};
+/** Seeing soft-deleted rows is the owner's (or the app's own task's). */
+export declare function assertIncludeDeleted(c: Core, flag: boolean | undefined): void;
+export declare function readPlan(c: Core): ReadPlan;
+/**
+ * The owner filter a READ must apply, if any: the `my-rows` reach narrows to
+ * the caller's own ids regardless of rules; otherwise it is whatever the plan
+ * said (a `creator` grant, or a user-scoped model).
+ */
+export declare function ownerFilter(c: Core, plan: ReadPlan): string[] | null;
+/**
+ * The scope conjunct storage must apply — the ONE definition both clients
+ * use. Memory evaluates it as a predicate (`scopeMatches`); Prisma builds a
+ * `where` from it (`scopeWhere`). They are two views of this table:
+ *
+ *   model scope   | across             | conjunct
+ *   user          | any                | (none — the owner filter does the work; rows have no nodeId)
+ *   instance      | none               | workspaceId = ws AND nodeId = node
+ *   workspace     | none               | workspaceId = ws
+ *   any non-user  | my-rows            | (none — the owner filter narrows to the caller's own rows everywhere)
+ *   any non-user  | owned-instances    | workspaceId IN ownedWorkspaceIds
+ */
+export type ScopeConjunct = {
+    kind: "none";
+} | {
+    kind: "instance";
+    workspaceId: string;
+    nodeId: string;
+} | {
+    kind: "workspace";
+    workspaceId: string;
+} | {
+    kind: "workspaces";
+    workspaceIds: string[];
+};
+export declare function scopeConjunct(c: Core, model?: CompiledModel): ScopeConjunct;
+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;
+/**
+ * Refuses, or hands back the plan — never both, never neither.
+ *
+ * Narrowing is `"code" in plan`, not `plan.ok`: the repo-wide tsc runs with
+ * `strict: false`, where `ok: true | false` widens to `boolean` and a
+ * discriminated union stops narrowing. This package must satisfy the LOWER of
+ * the two configurations it is compiled under.
+ */
+export declare function writeGate(c: Core, op: WriteOp): Extract<WritePlan, {
+    ok: true;
+}>;
+export declare function checkWritableData(c: Core, data: Row, fields: string[] | null, op: string): void;
+export declare function ownerIdForNewRow(viewer: RuleViewer): string | null;
+/**
+ * The declared columns of a new row: what the caller gave, else the declared
+ * default, else null for an optional — and a refusal for a required field
+ * nobody supplied. Platform columns are `stampNewRow`'s.
+ */
+export declare function declaredValues(c: Core, data: Row): Row;
+/** The columns the platform owns on a new row. The app never sets these. */
+export declare function stampNewRow(c: Core, now: Date, id: string): Row;
+/**
+ * Declared uniqueness, among the LIVE rows of this scope. Storage answers
+ * "does one exist"; this decides what that means. (A database unique would
+ * also count soft-deleted rows and block re-creating after a delete, which is
+ * why the fragment emits a plain index for these groups — v1 limitation: a
+ * race window between check and insert, to be closed with a partial unique
+ * index in the DDL step.)
+ */
+export declare function assertUnique(c: Core, row: Row, exists: (group: string[], values: unknown[]) => Promise<boolean>): Promise<void>;
+/**
+ * A relation cannot cross scope (security pass, S3). A `ref:` value names a
+ * row of THIS app; that row must exist, be live, sit inside this client's
+ * scope for its OWN model, and — if that model is user-scoped — belong to the
+ * caller (unless the caller is the app's own task). Refused as `invalid` with
+ * the field named: the id may exist elsewhere, and a message that said "not
+ * yours" would confirm it.
+ */
+export declare function assertRefTargets(c: Core, data: Row, lookup: (refModel: CompiledModel, id: string) => Promise<Row | null>): Promise<void>;

package/dist/db/client-core.js

@@ -0,0 +1,274 @@
+/**
+ * THE CLIENT CORE — everything a plugin database client decides, with nothing
+ * about where the rows live.
+ *
+ * Two clients read an app's tables: the in-memory one an author's unit tests
+ * run against (and the workbench box), and the Prisma one production runs
+ * against. The differential test requires them to agree on every visible set
+ * for every viewer after every operation. That is only credible if they do not
+ * each re-implement the decisions — so the decisions live here, once, and a
+ * client supplies storage: "give me the rows matching this scope", "does a row
+ * with these unique values exist", "fetch this ref target".
+ *
+ * Every function takes the same `Core` handle and REFUSES through the injected
+ * `refuse`, so a refusal raised by a test and a refusal raised by production are
+ * the same object with the same code, and the package still works with no host
+ * attached.
+ *
+ * The one thing deliberately NOT here is `where` evaluation. Memory evaluates a
+ * filter in JS; Prisma hands it to Postgres. Both validate the filter's KEYS
+ * here first, and the differential test is what proves the two evaluators
+ * agree on the values.
+ */
+import { INJECTED_COLUMNS, canUnseal, planRead, planWrite, } from "./compile-rules.js";
+/** Standalone default so the package works with no host attached. */
+export const defaultRefuse = (code, message, detail) => {
+    const err = new Error(message);
+    err.name = "PluginAccessError";
+    err.code = code;
+    err.detail = detail;
+    throw err;
+};
+export const DEFAULT_TAKE = 50;
+export const MAX_TAKE = 200;
+export const FILTER_OPS = ["in", "notIn", "not", "gt", "gte", "lt", "lte", "contains"];
+/* ───────────────────────── argument validation ────────────────────────── */
+export function bad(c, detail) {
+    return c.refuse("invalid", "invalid", detail);
+}
+/**
+ * A caller-supplied scope key is REFUSED, never overridden. An app that sets
+ * its own `nodeId` is either wrong or trying something, and overriding it
+ * quietly would hide both — in the author's tests as much as in production.
+ */
+export function assertNoInjectedKeys(c, obj, where) {
+    if (!obj)
+        return;
+    for (const key of Object.keys(obj)) {
+        if (INJECTED_COLUMNS.includes(key)) {
+            bad(c, `${c.model.name}.${where} may not name "${key}" — the platform stamps and filters it. ` +
+                `An app that sets its own scope is either wrong or trying something; overriding it quietly would hide both.`);
+        }
+    }
+}
+/**
+ * Only declared, INDEXED fields (and the platform's indexed columns) may be
+ * filtered or sorted. An unindexed filter is a table scan at a customer's
+ * scale; the refusal names the index to add. The generated types carry the
+ * same list, so an author meets this in the editor first.
+ */
+export function assertFilterable(c, keys, where) {
+    for (const key of keys) {
+        if (c.model.filterable.includes(key))
+            continue;
+        if (c.model.fields[key]) {
+            bad(c, `${c.model.name}.${where} names "${key}", which has no index — add it to plugin.json ` +
+                `db.${c.model.name}.indexes (e.g. [["${key}"]]). Filtering an unindexed column is a table scan.`);
+        }
+        bad(c, `${c.model.name}.${where} names "${key}", which is not a field of ${c.model.name} — ` +
+            `filterable here: ${c.model.filterable.join(", ")}`);
+    }
+}
+/** The filter operators a `where` value may use — the same list both evaluators implement. */
+export function assertFilterShape(c, where) {
+    if (!where)
+        return;
+    for (const [key, cond] of Object.entries(where)) {
+        if (cond !== null && typeof cond === "object" && !(cond instanceof Date) && !Array.isArray(cond)) {
+            for (const op of Object.keys(cond)) {
+                if (!FILTER_OPS.includes(op)) {
+                    bad(c, `${c.model.name}.where.${key}: unknown filter "${op}" — allowed: ${FILTER_OPS.join(", ")}`);
+                }
+            }
+        }
+    }
+}
+export function orderTerms(c, orderBy) {
+    if (!orderBy)
+        return [];
+    const terms = Array.isArray(orderBy) ? orderBy : [orderBy];
+    for (const t of terms)
+        assertFilterable(c, Object.keys(t), "orderBy");
+    return terms;
+}
+export function pageWindow(c, args) {
+    const take = args?.take ?? DEFAULT_TAKE;
+    if (take > MAX_TAKE)
+        bad(c, `take must be ${MAX_TAKE} or fewer — asked for ${take}. Page with \`cursor\`.`);
+    if (take < 0)
+        bad(c, "take must not be negative");
+    const skip = args?.skip ?? 0;
+    if (skip < 0)
+        bad(c, "skip must not be negative");
+    return { take, skip };
+}
+/** Seeing soft-deleted rows is the owner's (or the app's own task's). */
+export function assertIncludeDeleted(c, flag) {
+    if (flag && c.viewer.kind !== "internal" && c.viewer.role !== "owner") {
+        bad(c, `${c.model.name}: includeDeleted is the owner's`);
+    }
+}
+/* ─────────────────────────────── reads ────────────────────────────────── */
+export function readPlan(c) {
+    return planRead(c.model, c.viewer, { viaBinding: c.viaBinding });
+}
+/**
+ * The owner filter a READ must apply, if any: the `my-rows` reach narrows to
+ * the caller's own ids regardless of rules; otherwise it is whatever the plan
+ * said (a `creator` grant, or a user-scoped model).
+ */
+export function ownerFilter(c, plan) {
+    if (c.across === "my-rows")
+        return c.viewer.viewerIds;
+    return plan.ownerIn;
+}
+export function scopeConjunct(c, model = c.model) {
+    if (model.scope === "user")
+        return { kind: "none" };
+    if (c.across === "my-rows")
+        return { kind: "none" };
+    if (c.across === "owned-instances")
+        return { kind: "workspaces", workspaceIds: c.ownedWorkspaceIds };
+    if (model.scope === "workspace")
+        return { kind: "workspace", workspaceId: c.scope.workspaceId };
+    return { kind: "instance", workspaceId: c.scope.workspaceId, nodeId: c.scope.nodeId };
+}
+export function scopeMatches(c, row, model = c.model) {
+    const s = scopeConjunct(c, model);
+    switch (s.kind) {
+        case "none":
+            return true;
+        case "instance":
+            return row.workspaceId === s.workspaceId && row.nodeId === s.nodeId;
+        case "workspace":
+            return row.workspaceId === s.workspaceId;
+        case "workspaces":
+            return s.workspaceIds.includes(String(row.workspaceId));
+    }
+}
+/** Sealed fields are readable by the row's owner and by the app's own task. */
+export function mayUnseal(c, row) {
+    if (!c.model.sealed.length)
+        return true;
+    return canUnseal(c.viewer, row);
+}
+/* ─────────────────────────────── writes ───────────────────────────────── */
+/**
+ * Refuses, or hands back the plan — never both, never neither.
+ *
+ * Narrowing is `"code" in plan`, not `plan.ok`: the repo-wide tsc runs with
+ * `strict: false`, where `ok: true | false` widens to `boolean` and a
+ * discriminated union stops narrowing. This package must satisfy the LOWER of
+ * the two configurations it is compiled under.
+ */
+export function writeGate(c, op) {
+    if (c.across)
+        bad(c, `${c.model.name}.${op}: a cross-instance client is read-only`);
+    const plan = planWrite(c.model, op, c.viewer, { viaBinding: c.viaBinding });
+    if ("code" in plan) {
+        return c.refuse(plan.code, plan.code === "login-required" ? "login-required" : "forbidden", plan.detail);
+    }
+    return plan;
+}
+export function checkWritableData(c, data, fields, op) {
+    assertNoInjectedKeys(c, data, `${op} data`);
+    if (data.id !== undefined)
+        bad(c, `${c.model.name}.${op}: the platform mints \`id\``);
+    for (const key of Object.keys(data)) {
+        if (!c.model.fields[key]) {
+            bad(c, `${c.model.name}.${op}: "${key}" is not a declared field — declared: ${Object.keys(c.model.fields).join(", ")}`);
+        }
+        if (fields && !fields.includes(key)) {
+            c.refuse("forbidden", "forbidden", `${c.model.name}.${op}: this caller may write ${fields.join(", ")} — not "${key}"`);
+        }
+    }
+}
+export function ownerIdForNewRow(viewer) {
+    return viewer.userId ?? viewer.viewerIds[0] ?? null;
+}
+/**
+ * The declared columns of a new row: what the caller gave, else the declared
+ * default, else null for an optional — and a refusal for a required field
+ * nobody supplied. Platform columns are `stampNewRow`'s.
+ */
+export function declaredValues(c, data) {
+    const out = {};
+    for (const [name, field] of Object.entries(c.model.fields)) {
+        if (data[name] !== undefined)
+            out[name] = data[name];
+        // A list is empty until something is put in it. Postgres and Prisma agree:
+        // a scalar list has no null and no scalar default, so "nobody said" is `[]`,
+        // never a missing-required refusal.
+        else if (field.list)
+            out[name] = [];
+        else if (field.default !== undefined)
+            out[name] = field.default;
+        else if (field.optional)
+            out[name] = null;
+        else
+            bad(c, `${c.model.name}.create: "${name}" is required`);
+    }
+    return out;
+}
+/** The columns the platform owns on a new row. The app never sets these. */
+export function stampNewRow(c, now, id) {
+    return {
+        id,
+        workspaceId: c.scope.workspaceId,
+        nodeId: c.model.scope === "user" ? null : c.scope.nodeId,
+        ownerId: c.model.ownedByCreator || c.model.scope === "user" ? ownerIdForNewRow(c.viewer) : null,
+        createdBy: { kind: c.viewer.kind, userId: c.viewer.userId },
+        createdAt: now,
+        updatedAt: now,
+        deletedAt: null,
+    };
+}
+/**
+ * Declared uniqueness, among the LIVE rows of this scope. Storage answers
+ * "does one exist"; this decides what that means. (A database unique would
+ * also count soft-deleted rows and block re-creating after a delete, which is
+ * why the fragment emits a plain index for these groups — v1 limitation: a
+ * race window between check and insert, to be closed with a partial unique
+ * index in the DDL step.)
+ */
+export async function assertUnique(c, row, exists) {
+    for (const group of c.model.unique) {
+        const values = group.map((col) => row[col]);
+        if (values.some((v) => v == null))
+            continue;
+        if (await exists(group, values))
+            bad(c, `${c.model.name}.create: a row with this ${group.join("+")} already exists`);
+    }
+}
+/**
+ * A relation cannot cross scope (security pass, S3). A `ref:` value names a
+ * row of THIS app; that row must exist, be live, sit inside this client's
+ * scope for its OWN model, and — if that model is user-scoped — belong to the
+ * caller (unless the caller is the app's own task). Refused as `invalid` with
+ * the field named: the id may exist elsewhere, and a message that said "not
+ * yours" would confirm it.
+ */
+export async function assertRefTargets(c, data, lookup) {
+    for (const [name, field] of Object.entries(c.model.fields)) {
+        if (field.type !== "ref" || !field.ref)
+            continue;
+        const value = data[name];
+        if (value === undefined || value === null)
+            continue;
+        const target = c.rules.models[field.ref];
+        if (!target)
+            bad(c, `${c.model.name}.${name}: ref:${field.ref} names no model`);
+        const ids = field.list ? (Array.isArray(value) ? value : [value]) : [value];
+        for (const id of ids) {
+            if (typeof id !== "string" || !id)
+                bad(c, `${c.model.name}.${name}: a ref is the target row's id (a string)`);
+            const row = await lookup(target, id);
+            const ok = !!row &&
+                !row.deletedAt &&
+                scopeMatches(c, row, target) &&
+                (target.scope !== "user" || c.viewer.kind === "internal" || (!!row.ownerId && c.viewer.viewerIds.includes(String(row.ownerId))));
+            if (!ok)
+                bad(c, `${c.model.name}.${name}: no ${target.name} "${id}" in this ${target.scope === "user" ? "account" : "instance"}`);
+        }
+    }
+}