@drhomet/mithaq 0.1.1 → 0.2.0

package/dist/mithaq/define.d.ts

@@ -1,6 +1,9 @@
 import { type FieldList, type RowFieldWhere } from './rows.ts';
 import type { Ref } from './user.ts';
-import { type ContextOf, type DefaultLists, type OperationDeclaration, type SchemasOf } from '../asas/runner/steps.ts';
+import { defaultGlobalOperations, defaultOperations, type ContextOf, type DefaultLists, type OperationDeclaration, type SchemasOf } from '../asas/runner/steps.ts';
+import { defaultFields, defaultGlobalFields } from '../base/fields.ts';
+import { draftFields, versionOperations } from '../versions/versions.ts';
+import type { KayanVersions } from '../versions/index.ts';
 import type { DerivedInput, OperationParsed } from '../asas/runner/write.ts';
 import type { Language } from './language.ts';
 import type { ActorBoundAccess, Access, Field, FieldOf, Indexes, KayanService, KindValue, LocalesOf, MessageTree, RuntimeField, ServiceOf } from './types.ts';
@@ -14,6 +17,7 @@ type KayanAuthOf<Targets> = AuthStrategy | {
     server: (targets: Targets, vocabulary: {
         catalog: readonly string[];
         statements: Readonly<Record<string, readonly string[]>>;
+        referenced: (id: string) => Promise<number>;
     }) => unknown;
 };
 type StrayLocales<Copy, Locale extends string> = {
@@ -125,6 +129,45 @@ type NamedSchema<Name> = [Name] extends [undefined] ? {
 } : {
     schema: Name;
 };
+type CheckedFields<L extends Language, Fields extends Record<string, FieldOf<L>>> = Fields & {
+    [N in keyof Fields]: {
+        [Key in Exclude<keyof Fields[N], keyof Field<string, L['rules']>>]: never;
+    } & StrayLocales<Fields[N]['label'], LocalesOf<L>> & StrayDescription<Fields[N], LocalesOf<L>> & StrayPlaceholder<Fields[N], LocalesOf<L>> & TenantBinding<L, Fields[N]>;
+};
+type AnyFunction = (...args: never) => unknown;
+/**
+ * `operations` written as data `O`, or as a function of the defaults whose result is `R`. The two
+ * are told apart by `O` having no keys, never by a union: under a union TypeScript stops checking a
+ * written object for excess properties, and a misspelled key would pass. A stray key in a returned
+ * object, which no excess check reaches, is refused by name.
+ */
+type DeclaredOperations<L extends Language, Fields extends Record<string, RuntimeField>, O, R, Defaults> = O & ([keyof O] extends [never] ? ((args: {
+    defaults: Defaults;
+}) => R & NoInfer<Record<string, OperationOf<L, Fields, never>> & {
+    [Name in keyof R]: OperationOf<L, Fields, DataOf<L, Fields, R[Name]>> & {
+        [Key in Exclude<keyof R[Name], keyof OperationOf<L, Fields, never>>]?: never;
+    };
+}>) | NoInfer<Record<string, OperationOf<L, Fields, never>>> : NoInfer<Record<string, OperationOf<L, Fields, never>>> & NoInfer<{
+    [Name in keyof O]: OperationOf<L, Fields, DataOf<L, Fields, O[Name]>>;
+}>);
+/** The operations a kayan declared, whichever way it wrote them. */
+type OperationsOf<O, R> = [keyof O] extends [never] ? ([O] extends [AnyFunction] ? R : O) : O;
+/** Data, or a function of what the language offers that returns it, run once where the kayan is declared. */
+type OverDefaults<Declared, Defaults> = Declared | ((args: {
+    defaults: Defaults;
+}) => Declared);
+/** The name of the language's versions target, which a kayan keeps versions through by writing an entry under it. */
+type VersionsKey<L extends Language> = {
+    [Name in keyof L['targets']]: L['targets'][Name] extends {
+        capability: 'versions';
+    } ? Name : never;
+}[keyof L['targets']];
+/** What `fields: ({ defaults }) => ...` is handed: the id and timestamps, and the status field of a kayan that keeps drafts. */
+type FieldDefaults<Kept> = typeof defaultFields & (Kept extends {
+    readonly drafts: true | object;
+} ? typeof draftFields : unknown);
+/** What `operations: ({ defaults }) => ...` is handed: the shipped operations, and the version ones of a kayan that keeps versions. */
+type OperationDefaults<Kept> = typeof defaultOperations & ([Kept] extends [undefined] ? unknown : typeof versionOperations);
 type Paths<Fields> = Extract<keyof Fields, string> | {
     [Name in Extract<keyof Fields, string>]: Fields[Name] extends {
         relationTo: () => {
@@ -160,7 +203,7 @@ type CheckedRows<AccessDef, Fields, L extends Language> = AccessDef extends {
     };
 } : unknown;
 /** Bound to one language, so a kayan is checked against that language's kinds. */
-export declare const defineKayan: <const L extends Language>(language: L) => <const Name extends string, const Fields extends Record<string, FieldOf<L>>, const Messages extends MessageTree<LocalesOf<L>> = Record<never, never>, const O extends Record<string, OperationOf<L, Fields, never>> = Record<never, never>, const AccessDef extends ({
+export declare const defineKayan: <const L extends Language>(language: L) => <const Name extends string, const Fields extends Record<string, FieldOf<L>>, const Messages extends MessageTree<LocalesOf<L>> = Record<never, never>, const O extends Record<string, OperationOf<L, Fields, never>> | AnyFunction = Record<never, never>, const AccessDef extends ({
     create?: Access;
     read?: Access;
     update?: Access;
@@ -176,12 +219,16 @@ export declare const defineKayan: <const L extends Language>(language: L) => <co
     read?: Access;
     update?: Access;
     delete?: Access;
-}, const StoreName extends StoreKeys<L['targets']> | undefined = undefined, const SchemaName extends SchemaKeys<L['targets']> | undefined = undefined, const Auth extends KayanAuthOf<L['targets']> | undefined = undefined, const DbName extends string | undefined = undefined>(kayan: {
+}, const StoreName extends StoreKeys<L['targets']> | undefined = undefined, const SchemaName extends SchemaKeys<L['targets']> | undefined = undefined, const Auth extends KayanAuthOf<L['targets']> | undefined = undefined, const DbName extends string | undefined = undefined, const Kept extends KayanVersions | undefined = undefined, const R = Record<never, never>>(kayan: {
     name: Name;
     /** The provider that authenticates this kayan: `betterAuth({ server })`, `local({ secret })`, or a strategy. */
     auth?: Auth;
-    /** Every key on a field is one the language named: a stray one is `never`. */
-    fields: Fields & { [N in keyof Fields]: { [Key in Exclude<keyof Fields[N], keyof Field<string, L['rules']>>]: never; } & StrayLocales<Fields[N]['label'], LocalesOf<L>> & StrayDescription<Fields[N], LocalesOf<L>> & StrayPlaceholder<Fields[N], LocalesOf<L>> & TenantBinding<L, Fields[N]>; };
+    /**
+     * The fields, in column order: `{ ...defaultFields, title }`, or `({ defaults }) => ({ ...defaults, title })`.
+     * TypeScript types a callback beside them that reads the fields, such as an operation's `input`
+     * over the derived shapes, before it reads what the function returns, so such a kayan writes them as an object.
+     */
+    fields: OverDefaults<CheckedFields<L, Fields>, FieldDefaults<Kept>>;
     /** This kayan's own copy, nested by the parts of each key. A key a field's own `label` also claims is a collision. */
     messages?: Messages & { [Key in keyof Messages]: StrayMessages<Messages[Key], LocalesOf<L>>; };
     /** Where `mithaq generate messages` writes this kayan's file, if not the default. */
@@ -189,14 +236,14 @@ export declare const defineKayan: <const L extends Language>(language: L) => <co
     /** What each target of this build says about this kayan, by the target's name: `{ drizzle: pgTable(...) }`, `targets.<screen>`, `targets.service`. */
     targets?: KayanTargetsOf<L, Fields, {
         service?: {
-            /** Every operation this kayan answers, and nothing else: `{ ...defaultOperations, archive }`. */
-            operations?: O & NoInfer<Record<string, OperationOf<L, Fields, never>>> & NoInfer<{ [Name_1 in keyof O]: OperationOf<L, Fields, DataOf<L, Fields, O[Name_1]>>; }>;
+            /** Every operation this kayan answers, and nothing else: `{ ...defaultOperations, archive }`, or `({ defaults }) => ({ ...defaults, archive })`. */
+            operations?: DeclaredOperations<L, Fields, O, R, OperationDefaults<Kept>>;
             /** The store this kayan is written through. One of the language's targets. */
             store?: StoreName;
             /** The target a write is validated against. One of the language's targets. */
             schema?: SchemaName;
         };
-    }>;
+    }> & { [Name_1 in VersionsKey<L>]?: Kept; };
     /** This kayan's own open bag, for the project's own code. Nothing in mithaq reads it, and it stays on the server. */
     custom?: Record<string, unknown>;
     access?: AccessDef & CheckedRows<AccessDef, Fields, L>;
@@ -221,7 +268,7 @@ export declare const defineKayan: <const L extends Language>(language: L) => <co
     out?: string;
     targets: KayanTargetsOf<L, Fields, {
         service: {
-            operations: NoInfer<O>;
+            operations: NoInfer<OperationsOf<O, R>>;
         } & NamedStore<StoreName> & NamedSchema<SchemaName>;
     }>;
     custom?: Record<string, unknown>;
@@ -242,10 +289,10 @@ type GlobalAccess = {
  * Declares a global, a kayan of one row. It spreads `defaultGlobalFields` and runs
  * `defaultGlobalOperations`; a tenant field makes it one row per tenant.
  */
-export declare const defineGlobal: <const L extends Language>(language: L) => <const Name extends string, const Fields extends Record<string, FieldOf<L>>, const Messages extends MessageTree<LocalesOf<L>> = Record<never, never>, const O extends Record<string, OperationOf<L, Fields, never>> = Record<never, never>, const AccessDef extends GlobalAccess = Record<never, never>, const StoreName extends StoreKeys<L['targets']> | undefined = undefined, const SchemaName extends SchemaKeys<L['targets']> | undefined = undefined, const DbName extends string | undefined = undefined>(global: {
+export declare const defineGlobal: <const L extends Language>(language: L) => <const Name extends string, const Fields extends Record<string, FieldOf<L>>, const Messages extends MessageTree<LocalesOf<L>> = Record<never, never>, const O extends Record<string, OperationOf<L, Fields, never>> | AnyFunction = Record<never, never>, const AccessDef extends GlobalAccess = Record<never, never>, const StoreName extends StoreKeys<L['targets']> | undefined = undefined, const SchemaName extends SchemaKeys<L['targets']> | undefined = undefined, const DbName extends string | undefined = undefined, const R = Record<never, never>>(global: {
     name: Name;
-    /** Every key on a field is one the language named: a stray one is `never`. */
-    fields: Fields & { [N in keyof Fields]: { [Key in Exclude<keyof Fields[N], keyof Field<string, L['rules']>>]: never; } & StrayLocales<Fields[N]['label'], LocalesOf<L>> & StrayDescription<Fields[N], LocalesOf<L>> & StrayPlaceholder<Fields[N], LocalesOf<L>> & TenantBinding<L, Fields[N]>; };
+    /** The fields, in column order: `{ ...defaultFields, ...defaultGlobalFields, siteTitle }`, or `({ defaults }) => ({ ...defaults, siteTitle })`. */
+    fields: OverDefaults<CheckedFields<L, Fields>, typeof defaultFields & typeof defaultGlobalFields>;
     /** This global's own copy, nested by the parts of each key, as on any kayan. */
     messages?: Messages & { [Key in keyof Messages]: StrayMessages<Messages[Key], LocalesOf<L>>; };
     /** Where `mithaq generate messages` writes this global's file, if not the default. */
@@ -253,8 +300,8 @@ export declare const defineGlobal: <const L extends Language>(language: L) => <c
     /** What each target says about this global, exactly as on any kayan. */
     targets?: KayanTargetsOf<L, Fields, {
         service?: {
-            /** The two operations a global runs, `defaultGlobalOperations` or a list of the same names. */
-            operations?: O;
+            /** The two operations a global runs, `defaultGlobalOperations` or a list of the same names, or `({ defaults }) => defaults`. */
+            operations?: DeclaredOperations<L, Fields, O, R, typeof defaultGlobalOperations>;
             /** The store this global is written through. One of the language's targets. */
             store?: StoreName;
             /** The target a write is validated against. One of the language's targets. */
@@ -279,7 +326,7 @@ export declare const defineGlobal: <const L extends Language>(language: L) => <c
     out?: string;
     targets: KayanTargetsOf<L, Fields, {
         service: {
-            operations: NoInfer<O>;
+            operations: NoInfer<OperationsOf<O, R>>;
         } & NamedStore<StoreName> & NamedSchema<SchemaName>;
     }>;
     custom?: Record<string, unknown>;

package/dist/mithaq/define.js

@@ -1,10 +1,16 @@
 import { applyRows, rowFields, rowsOf } from './rows.js';
-import { languageRows, serviceTargetOf, tenantDefaults } from './language.js';
-import { resolveOperations } from '../asas/runner/steps.js';
+import { isVersions, languageRows, serviceTargetOf, tenantDefaults } from './language.js';
+import { defaultGlobalOperations, defaultOperations, resolveOperations } from '../asas/runner/steps.js';
+import { defaultFields, defaultGlobalFields } from '../base/fields.js';
+import { draftFields, versionOperations } from '../versions/versions.js';
+const overDefaults = (declared, defaults) => typeof declared === 'function' ? declared({ defaults }) : declared;
 /** Bound to one language, so a kayan is checked against that language's kinds. */
 export const defineKayan = (language) => (kayan) => {
-    // The key order is the column order: nothing is merged in and nothing is moved.
-    const fields = Object.fromEntries(Object.entries(kayan.fields).map(([name, field]) => [name, tenantDefaults(language, field)]));
+    const versioning = Object.keys(language.targets).find((name) => isVersions(language.targets[name]));
+    const kept = versioning === undefined ? undefined : kayan.targets?.[versioning];
+    const declaredFields = overDefaults(kayan.fields, { ...defaultFields, ...(kept?.drafts && draftFields) });
+    // The key order is the column order but for the timestamps, which a new table puts last: nothing is merged in.
+    const fields = Object.fromEntries(Object.entries(declaredFields).map(([name, field]) => [name, tenantDefaults(language, field)]));
     // A tenant-owned kayan inherits the language's rows; one opts out on its access.
     const declared = kayan.access;
     const owned = Object.values(fields).some((field) => field.targets?.tenant !== undefined);
@@ -22,7 +28,8 @@ export const defineKayan = (language) => (kayan) => {
     }
     // A steps function runs once, here, so the kayan carries data a tool reads without calling anything.
     const own = kayan.targets?.service;
-    const operations = resolveOperations(own?.operations, serviceTargetOf(language));
+    const declaredOperations = overDefaults(own?.operations, { ...defaultOperations, ...(kept && versionOperations) });
+    const operations = resolveOperations(declaredOperations, serviceTargetOf(language));
     return {
         ...kayan,
         ...(compiled ? { access: applyRows(compiled, declared) } : {}),
@@ -36,8 +43,15 @@ export const defineKayan = (language) => (kayan) => {
  */
 export const defineGlobal = (language) => {
     const kayan = defineKayan(language);
-    return (global) => 
-    // `defineKayan`'s own access object, untouched: a rebuilt one would drop the rows
-    // marker, and the permission check would stand aside for every global operation.
-    ({ ...kayan(global), single: true });
+    return (global) => {
+        const service = global.targets?.service;
+        const declared = {
+            ...global,
+            fields: overDefaults(global.fields, { ...defaultFields, ...defaultGlobalFields }),
+            targets: { ...global.targets, service: { ...service, operations: overDefaults(service?.operations, defaultGlobalOperations) } },
+        };
+        // `defineKayan`'s own access object, untouched: a rebuilt one would drop the rows
+        // marker, and the permission check would stand aside for every global operation.
+        return ({ ...kayan(declared), single: true });
+    };
 };

package/dist/mithaq/generate-messages.js

@@ -8,9 +8,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { Refusal } from './refusal.js';
+import { flattenMessageFile, nestMessageFile } from './message-file.js';
 const fileOf = (name, out, directory, root) => out ? new URL(out, root) : new URL(`${name}.json`, directory);
 // What is on disk wins: these files are the project's to translate, so a run adds a
-// missing key and never deletes or rewrites one.
+// missing key and keeps every translation when rewriting the file shape.
 const merge = (copy, current, locales) => {
     if (typeof copy === 'function')
         return null;
@@ -75,7 +76,7 @@ export const generateMessages = async ({ registry, directory, check = false, roo
     let floor = {};
     for (const [at, scope] of registry.scopes.entries()) {
         const file = files[at];
-        const current = committed[at];
+        const current = flattenMessageFile({ file: committed[at], locales: registry.locales });
         const wanted = { ...current };
         for (const key of Object.keys(current)) {
             if (!Object.hasOwn(scope.keys, key))
@@ -108,8 +109,8 @@ export const generateMessages = async ({ registry, directory, check = false, roo
                     report.missing.push(`${scope.name}.${key} has no "${locale}".`);
             }
         }
-        const source = `${JSON.stringify(Object.fromEntries(Object.keys(wanted).sort().map((key) => [key, wanted[key]])), null, 2)}\n`;
-        if (source === `${JSON.stringify(current, null, 2)}\n`)
+        const source = `${JSON.stringify(nestMessageFile(wanted), null, 2)}\n`;
+        if (source === `${JSON.stringify(committed[at], null, 2)}\n`)
             continue;
         report.changed.push(scope.out ?? `${scope.name}.json`);
         if (check)

package/dist/mithaq/language.d.ts

@@ -7,6 +7,7 @@ import type { VersionsTarget } from '../versions/index.ts';
 import type { StorageTarget } from '../storage/storage.ts';
 import { buildAsas, type HttpPlug } from '../asas/build.ts';
 import type { AuthConfig } from '../asas/build.ts';
+import type { DeclarationStore } from '../asas/runner/write.ts';
 import type { AuditHandler, Derives, DerivedShapes } from '../asas/runner/steps.ts';
 import type { Where } from './where.ts';
 import { defineGlobal, defineKayan } from './define.ts';
@@ -100,12 +101,16 @@ export type TenantTarget<RelationTo extends string = string> = {
     readonly capability: 'tenant';
     readonly relationTo: RelationTo;
     readonly onDelete: 'restrict';
+    /** A new row on a tenant-owned kayan takes the active organization, through an operation or a step's insert/upsert; naming another organization is refused. */
+    readonly newRows: 'active';
+    /** How many organizations the project holds; in `'one'` a `connect()` over more refuses to start. */
+    readonly organizations: 'one' | 'many';
     readonly field: TenantField<RelationTo>;
     /**
-     * Whether this actor is platform staff in the trusted platform app, who may read every
+     * Whether this actor is backoffice staff in the trusted backoffice app, who may read every
      * tenant's rows with `tenant: 'all'` and never write through it. Absent, no one may.
      */
-    readonly platform?: (args: {
+    readonly backoffice?: (args: {
         user: unknown;
     }) => boolean | Promise<boolean>;
 };
@@ -136,6 +141,15 @@ export type Store<Kinds extends Record<string, Kind> = Record<string, Kind>, Rul
         kayan: string;
         data: Record<string, unknown>;
     }): Promise<Row>;
+    /** Insert or update by the declared unique index `on` names, or by `on: ['id']` without a declared unique index, with key values in `data`. An increment inserts its amount or adds it to the existing value. Returns the row with its existing identity kept. */
+    upsert(args: {
+        tx: Tx;
+        kayan: string;
+        on: readonly string[];
+        data: Record<string, unknown>;
+        where?: Where;
+    }): Promise<Row>;
+    /** `{ field: { $inc: n } }` adds a safe integer in the database to an integer field, alongside plain values. Store writes skip validation; enforce quantities that must not become negative with a database CHECK. Returns the changed row. */
     update(args: {
         tx: Tx;
         kayan: string;
@@ -154,8 +168,14 @@ export type Store<Kinds extends Record<string, Kind> = Record<string, Kind>, Rul
         kayan: string;
         args: {
             limit: number;
-            /** A store must hold the rows it returns until the transaction ends: a step that compares a row, such as `expectedUpdatedAt`, relies on it. */
-            lock?: 'update';
+            /**
+             * Hold returned rows until this transaction ends. `update` excludes every competing lock;
+             * `noKeyUpdate` keeps their values unchanged by others while allowing `keyShare` readers;
+             * `share` keeps them as read while allowing other `share` and `keyShare` readers;
+             * `keyShare` keeps their identity and unique keys, allowing other values to change.
+             * Every mode requires a transaction; a lock without one must throw.
+             */
+            lock?: 'update' | 'noKeyUpdate' | 'share' | 'keyShare';
             page: number;
             sort: {
                 field: string;
@@ -168,6 +188,13 @@ export type Store<Kinds extends Record<string, Kind> = Record<string, Kind>, Rul
         docs: Row[];
         totalDocs: number;
     }>;
+    /** Exact total of an integer, number or decimal field, as a decimal string so no value passes through a float; empty selections return '0'. */
+    sum(args: {
+        tx?: Tx;
+        kayan: string;
+        field: string;
+        where?: Where;
+    }): Promise<string>;
     /** Counts matching rows without loading them. Without it, `find` with a limit of `0` is asked. */
     count?(args: {
         kayan: string;
@@ -178,6 +205,18 @@ export type Store<Kinds extends Record<string, Kind> = Record<string, Kind>, Rul
     }): Promise<number>;
     destroy(): Promise<void>;
 };
+/** The runner keeps bound string-name calls behind the declaration boundary: access and field masks are skipped, tenant scope is not. Upsert fills the tenant from the active organization and refuses another value. Never expose privileged rows or fields through step output. */
+export type RawStepStore = Pick<Store, 'find' | 'insert' | 'remove' | 'update' | 'upsert' | 'sum'> & {
+    /** Holds existing ids in ascending order until the transaction ends, deduplicated; any missing or foreign id is a 404. Requires a transaction. */
+    hold(args: {
+        tx: unknown;
+        kayan: string;
+        ids: readonly unknown[];
+        mode: NonNullable<Parameters<Store['find']>[0]['args']['lock']>;
+    }): Promise<void>;
+};
+/** A step names a kayan by its declaration; fields and values follow that declaration, as with tools.of. */
+export type StepStore = DeclarationStore;
 /** A target that holds rows. Takes `undefined`, so a caller can name the bad target in its own throw. */
 export declare const isStore: (target: RuntimeTarget | undefined) => target is RuntimeStore;
 /** A target that says who may do what. */

package/dist/mithaq/message-file.d.ts

@@ -0,0 +1,13 @@
+/** A translated leaf, an opaque resolver result, or a function's unverifiable marker. */
+export type MessageEntry = Record<string, string> | string | null;
+type Branch = {
+    [key: string]: MessageEntry | Branch;
+};
+/** Reads both release formats, keeping a parent's own value separate from its children. */
+export declare const flattenMessageFile: ({ file, locales }: {
+    file: Record<string, unknown>;
+    locales: readonly string[];
+}) => Record<string, MessageEntry>;
+/** A value gets `$value` only when another key needs to pass through it. */
+export declare const nestMessageFile: (entries: Record<string, MessageEntry>) => Branch;
+export {};

package/dist/mithaq/message-file.js

@@ -0,0 +1,29 @@
+const branch = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Reads both release formats, keeping a parent's own value separate from its children. */
+export const flattenMessageFile = ({ file, locales }) => {
+    const entries = [];
+    const walk = (node, parts) => {
+        for (const [name, value] of Object.entries(node)) {
+            const path = [...parts, name];
+            if (name === '$value')
+                entries.push([parts.join('.'), value]);
+            else if (branch(value) && !(Object.values(value).every((one) => typeof one === 'string') && (!Object.keys(value).length || Object.keys(value).some((key) => locales.includes(key)))))
+                walk(value, path);
+            else
+                entries.push([path.join('.'), value]);
+        }
+    };
+    walk(file, []);
+    return Object.fromEntries(entries);
+};
+/** A value gets `$value` only when another key needs to pass through it. */
+export const nestMessageFile = (entries) => {
+    const result = Object.create(null);
+    const keys = Object.keys(entries).sort();
+    for (const key of keys) {
+        const parts = [...key.split('.'), ...(keys.some((other) => other.startsWith(`${key}.`)) ? ['$value'] : [])];
+        const last = parts.pop();
+        parts.reduce((node, part) => (node[part] ??= Object.create(null)), result)[last] = entries[key];
+    }
+    return result;
+};

package/dist/mithaq/messages.js

@@ -42,6 +42,11 @@ export const messagesOf = ({ language, kayanList, resolver, }) => {
                 continue;
             claim(name, `field "${name}" label`, field.label);
         }
+        // Screens share this fallback key, so the first description is claimed once.
+        const describe = (screen) => kayan.targets?.[screen]?.description;
+        const described = Object.keys(language.targets).find((screen) => language.targets[screen].capability === 'screen' && describe(screen));
+        if (described)
+            claim('page.description', `screen "${described}" description`, describe(described));
         // Claimed once per field however many screens ask for it.
         for (const [name, operation] of Object.entries(kayan.operations)) {
             const fields = Object.entries(operation.targets ?? {}).flatMap(([screen, block]) => language.targets[screen]?.capability === 'screen' ? Object.entries(block?.fields ?? {}) : []);

package/dist/mithaq/resolve.js

@@ -1,6 +1,7 @@
 import { admissions, rowsOf, rowsOfField } from './rows.js';
 import { isRef, refuseLiteral } from './user.js';
-import { bulkSeals, defaultGlobalOperations, holdOutput, readSeals, resolveOperations, sealOf, storeSeals, versionSeals, } from '../asas/runner/steps.js';
+import { jsonSchemaCheck } from '../base/json-schema.js';
+import { bulkSeals, defaultGlobalOperations, holdOutput, readSeals, resolveOperations, sealOf, foreignCopyOf, storeSeals, versionSeals, } from '../asas/runner/steps.js';
 import { kayanServiceKeys, unsortable } from './types.js';
 import { compareDecimals } from '../base/decimal.js';
 import { isAccess, isScreen, isService, isStorage, isStore, isTenant, isVersions, serviceTargetOf, tenantDefaults } from './language.js';
@@ -17,7 +18,7 @@ export const versionsTableOf = (kayan) => `_${kayan.table}_versions`;
 /** The default indexes a `unique` rule makes, which a store may build as the column's own constraint. */
 export const uniqueRuleIndexes = new WeakSet();
 export const isPlainIdentifier = (value) => value.length <= 63 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
-const fixed = new Set(['access', 'column', 'custom', 'dbName', 'description', 'kayan', 'kind', 'kindTargets', 'label', 'locales', 'name', 'now', 'operators', 'options', 'placeholder', 'prefix', 'schemaTarget', 'sortable', 'suffix', 'target', 'targets', 'rules']);
+const fixed = new Set(['access', 'column', 'custom', 'dbName', 'description', 'jsonSchema', 'kayan', 'kind', 'kindTargets', 'label', 'locales', 'maxBytes', 'name', 'now', 'operators', 'options', 'placeholder', 'prefix', 'schemaTarget', 'sortable', 'suffix', 'target', 'targets', 'rules']);
 // Every list holds exactly one store or managed read step, and none of the three
 // the runner owns; the effect is read off that one step, so it is never declared.
 const effects = {
@@ -102,6 +103,11 @@ const sealed = (kayan, operation, declaration, service) => {
     if (list.some((step) => typeof step !== 'function')) {
         throw new Error(`${where} has a step that is not a function.`);
     }
+    // Its errors, actors and secret columns are unknown here too, so two copies are refused, never bridged.
+    const foreign = list.filter((step) => !sealOf(step)).map(foreignCopyOf).find(Boolean);
+    if (foreign) {
+        throw new Error(`${where} holds a step another copy of mithaq sealed, loaded from ${foreign}, beside this one at ${import.meta.url}. Install one copy: name mithaq by the same spec, with the same peers, in every package that imports it, so the package manager links it once.`);
+    }
     const held = list.map(sealOf);
     for (const seal of held) {
         const owned = seal && runnerSteps[seal];
@@ -134,7 +140,7 @@ const sealed = (kayan, operation, declaration, service) => {
     return resolved({ effect });
 };
 // `onDelete` is a rule too, so on a relationship it is still checked against every target.
-const relationshipKeys = new Set(['hasMany', 'mode', 'relationTo']);
+const relationshipKeys = new Set(['filterOptions', 'hasMany', 'mode', 'relationTo']);
 const joinKeys = new Set(['defaultLimit', 'defaultSort', 'on', 'relationTo']);
 /** Names that reach the prototype rather than a key an actor carries. */
 const unsafeKeys = new Set(['__proto__', 'constructor', 'prototype']);
@@ -144,7 +150,7 @@ const targetOf = (who, named, language, role) => {
     const target = language.targets[named];
     if (!target || isStore(target) !== (role === 'store')) {
         throw new Error(role === 'store'
-            ? `${who} names store "${named}", which is not a store: a store target declares capability "store" and has init, connect, transaction, insert, update, remove, find and destroy beside kinds and rules.`
+            ? `${who} names store "${named}", which is not a store: a store target declares capability "store" and has init, connect, transaction, insert, update, upsert, remove, find, sum and destroy beside kinds and rules.`
             : `${who} names schema "${named}", which is not a schema target: a schema target has kinds and rules, and does not declare capability "store".`);
     }
     if (role === 'schema' && typeof target.derive !== 'function') {
@@ -183,7 +189,7 @@ const nameOf = (relationTo) => typeof relationTo === 'function' ? String(relatio
 const tenantField = ({ where, field, language }) => {
     const target = language.targets.tenant;
     if (!isTenant(target)) {
-        throw new Error(`${where} is bound through targets.tenant, and this language lays down no tenant target. Add tenant: betterAuthTenant({ relationTo, onDelete: 'restrict' }) to its targets, or drop targets.tenant from the field.`);
+        throw new Error(`${where} is bound through targets.tenant, and this language lays down no tenant target. Add tenant: betterAuthTenant({ relationTo, onDelete: 'restrict', newRows: 'active', organizations }) to its targets, or drop targets.tenant from the field.`);
     }
     const bound = tenantDefaults(language, field);
     const rules = bound.rules ?? {};
@@ -212,6 +218,10 @@ const tenantField = ({ where, field, language }) => {
     }
     return bound;
 };
+const messageName = (where, name) => {
+    if (name.startsWith('$'))
+        throw new Error(`${where} "${name}" is reserved: names starting with "$" are reserved for message-file values.`);
+};
 // A key written flat is refused with the nesting spelled out. A node holding both a
 // sentence and a group, or nothing, is refused: either reading would destroy copy.
 const flattenMessages = (where, messages, locales, parts = []) => 
@@ -219,6 +229,8 @@ const flattenMessages = (where, messages, locales, parts = []) =>
 // runs the setter, so the copy would vanish and the prototype be whatever was written.
 Object.fromEntries(Object.entries(messages).flatMap(([key, value]) => {
     const path = [...parts, ...key.split('.')];
+    if (key.startsWith('$'))
+        throw new Error(`Kayan "${where}" message key "${path.join('.')}" is reserved: names starting with "$" are reserved for message-file values.`);
     if (key.includes('.')) {
         throw new Error(`Kayan "${where}" writes the message key "${path.join('.')}" flat. Nest it under "${key.split('.')[0]}": messages: ${path.map((part) => `{ ${part}: `).join('')}...${' }'.repeat(path.length)}.`);
     }
@@ -295,12 +307,14 @@ export const resolve = (kayanList, language) => {
     // For a table written as plain data, which `kind` does not type. A rule may ship no
     // sentence; every kind refuses the value it is handed.
     for (const [name, kind] of Object.entries(language.kinds)) {
+        messageName("The language's kind", name);
         if (!kind.message) {
             throw new Error(`The language's kind "${name}" declares no message, so a value it refuses has no sentence to show.`);
         }
     }
     // A typo would otherwise exclude nothing in silence.
     for (const [name, one] of Object.entries(language.rules)) {
+        messageName("The language's rule", name);
         const missing = one.excludes?.find((other) => !Object.hasOwn(language.rules, other));
         if (missing) {
             throw new Error(`The language's rule "${name}" excludes "${missing}", which is not a rule the language names.`);
@@ -466,6 +480,9 @@ export const resolve = (kayanList, language) => {
     if (isTenant(tenantTarget) && tenantTarget.onDelete !== 'restrict') {
         throw new Error(`The tenant target declares onDelete ${JSON.stringify(tenantTarget.onDelete)}, and a tenant takes onDelete: 'restrict' alone.`);
     }
+    if (isTenant(tenantTarget) && tenantTarget.newRows !== 'active') {
+        throw new Error(`The tenant target declares newRows ${JSON.stringify(tenantTarget.newRows)}, and a tenant takes newRows: 'active' alone.`);
+    }
     const byName = new Map(kayanList.map((kayan) => [kayan.name, kayan]));
     const resolved = kayanList.map((kayan) => {
         if (kayan.targets && Object.hasOwn(kayan.targets, 'tenant')) {
@@ -500,6 +517,9 @@ export const resolve = (kayanList, language) => {
                 continue;
             throw new Error(`Kayan "${kayan.name}" writes "targets.service.${key}", which is no key of a kayan's service target. A kayan writes ${kayanServiceKeys.join(', ')} there.`);
         }
+        if (typeof own.operations === 'function') {
+            throw new Error(`Kayan "${kayan.name}" writes its operations as a function, which only defineKayan and defineGlobal run, since they know the defaults it is handed. Declare it with defineKayan, or write its operations as an object: { ...defaultOperations, archive }.`);
+        }
         return {
             ...kayan,
             // Flattened here, so every reader of a resolved kayan sees the key space a generated file carries.
@@ -513,6 +533,7 @@ export const resolve = (kayanList, language) => {
             // Run again for a kayan written as plain data. `false` would remove nothing from
             // the kayan's own record, so it is refused by name.
             operations: Object.fromEntries(Object.entries(resolveOperations(own.operations, service)).filter(([operation, declaration]) => {
+                messageName(`Kayan "${kayan.name}" operation`, operation);
                 if (declaration === false) {
                     throw new Error(`Kayan "${kayan.name}" operation "${operation}" is false, and false is no operation. Leave "${operation}" out of the object instead: const { ${operation}, ...rest } = defaultOperations.`);
                 }
@@ -533,10 +554,9 @@ export const resolve = (kayanList, language) => {
                         required: field.rules?.required ?? false,
                         // A join holds no column here, so `providedBy: never` keeps the key off every write shape.
                         ...(field.kind === 'join' && { providedBy: { create: 'never', update: 'never' } }),
-                        // A `hasMany` field holds no column on this table; its join rows go with the parent by cascade.
-                        ...(pointsAtRow(field.kind) && field.relationTo && !field.hasMany && {
-                            // A required field restricts, since `set null` would break it; any other takes its kind's default.
-                            onDelete: field.rules?.onDelete ?? (field.rules?.required ? 'restrict' : language.kinds[field.kind].onDelete),
+                        // A required field and a set restrict, since neither has a null to set; any other takes its kind's default.
+                        ...(pointsAtRow(field.kind) && field.relationTo && {
+                            onDelete: field.rules?.onDelete ?? (field.rules?.required || field.hasMany ? 'restrict' : language.kinds[field.kind].onDelete),
                         }),
                     },
                     // A join builds no column, but takes a name so the one place that prints it prints no blank.
@@ -593,6 +613,35 @@ export const resolve = (kayanList, language) => {
             }
         }
     };
+    const jsonSchemaNamed = (where, field) => {
+        if (field.kind !== 'json' && field.maxBytes !== undefined)
+            throw new Error(`${where} has a maxBytes, and kind "${field.kind}" takes none; only a json field does.`);
+        if (field.kind === 'json' && !(Number.isInteger(field.maxBytes) && field.maxBytes > 0)) {
+            throw new Error(`${where} is json and names no maxBytes; name maxBytes: defaultJsonMaxBytes, or a whole number of its own.`);
+        }
+        const { jsonSchema } = field;
+        if (jsonSchema === undefined)
+            return;
+        if (field.kind !== 'json')
+            throw new Error(`${where} has a jsonSchema, and kind "${field.kind}" takes none; only a json field does.`);
+        const schema = jsonSchema?.schema;
+        if (typeof schema !== 'boolean' && (!schema || typeof schema !== 'object' || Array.isArray(schema))) {
+            throw new Error(`${where} jsonSchema names no "schema"; a schema is held in the field and never fetched from its "uri".`);
+        }
+        const { uri, fileMatch } = jsonSchema;
+        if ((uri !== undefined && typeof uri !== 'string') || (fileMatch !== undefined && !(Array.isArray(fileMatch) && fileMatch.every((one) => typeof one === 'string')))) {
+            throw new Error(`${where} jsonSchema "fileMatch" is a list of strings and "uri" a string.`);
+        }
+    };
+    // Else every create that leaves the field out would be refused for a value it never sent.
+    const jsonDefaultNamed = (where, field) => {
+        const value = field.rules?.defaultValue;
+        if (field.kind !== 'json' || value === undefined || isRef(value))
+            return;
+        if (new TextEncoder().encode(JSON.stringify(value)).length > field.maxBytes || (field.jsonSchema && !jsonSchemaCheck(field)(value))) {
+            throw new Error(`${where} defaultValue is refused by its own jsonSchema or maxBytes.`);
+        }
+    };
     const declaredTargets = (where, wrote, known = targetNames) => {
         for (const name of Object.keys(wrote ?? {})) {
             if (known.has(name))
@@ -609,6 +658,7 @@ export const resolve = (kayanList, language) => {
         targetOf(`Kayan "${kayan.name}"`, kayan.schema, language, 'schema');
         for (const field of Object.values(kayan.fields)) {
             const where = `Kayan "${kayan.name}" field "${field.name}"`;
+            messageName(`Kayan "${kayan.name}" field`, field.name);
             declaredTargets(where, field.targets);
             // The field found must be a relationship pointing back here, or the join would read
             // a column that is no pointer back and answer another row's rows.
@@ -674,10 +724,17 @@ export const resolve = (kayanList, language) => {
                 if (Object.hasOwn(field, 'mode')) {
                     throw new Error(`${where} carries "mode", which a field does not take: a relationship points at one row, and "hasMany: true" makes it hold a set.`);
                 }
+                // Its delete would fail in the database on the not-null column instead.
+                if (!field.hasMany && field.rules?.required && field.rules.onDelete === 'set null') {
+                    throw new Error(`${where} is required and declares onDelete "set null", and a required column holds no null. Write "restrict" or "cascade".`);
+                }
                 // A rule that silently builds nothing is what this file exists to prevent.
                 // `required` is not one: the schema target reads it off the array.
                 if (field.hasMany) {
-                    const columnRule = ['defaultValue', 'index', 'onDelete', 'unique'].find((rule) => field.rules?.[rule] !== undefined);
+                    if (field.rules?.onDelete === 'set null') {
+                        throw new Error(`${where} is a relationship with hasMany and onDelete "set null", and a set's join row holds no null. Write "restrict", which keeps the row while a set names it, or "cascade", which takes it out of every set.`);
+                    }
+                    const columnRule = ['defaultValue', 'index', 'unique'].find((rule) => field.rules?.[rule] !== undefined);
                     if (columnRule) {
                         throw new Error(`${where} is a relationship with hasMany, which the store holds as a join table and not as a column of this kayan, so rule "${columnRule}" would build nothing. Declare it on the kayan this field points at, or drop it.`);
                     }
@@ -694,6 +751,8 @@ export const resolve = (kayanList, language) => {
             }
             optionsNamed(where, field.kind, field);
             affixesNamed(where, field.kind, field);
+            jsonSchemaNamed(where, field);
+            jsonDefaultNamed(where, field);
             for (const [screen, block] of Object.entries(field.targets ?? {})) {
                 if (!isScreen(language.targets[screen]))
                     continue;
@@ -849,6 +908,7 @@ export const resolve = (kayanList, language) => {
             const inputs = Object.entries(declaration.targets ?? {}).flatMap(([screen, block]) => isScreen(language.targets[screen]) ? Object.entries(block.fields ?? {}) : []);
             for (const [name, field] of inputs) {
                 const where = `Kayan "${kayan.name}" operation "${operation}" field "${name}"`;
+                messageName(`Kayan "${kayan.name}" operation "${operation}" field`, name);
                 declaredTargets(where, field.targets);
                 optionsNamed(where, field.kind, field);
                 affixesNamed(where, field.kind, field);