@brydio/manifest 0.1.0-alpha.33 → 0.1.0-alpha.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brydio/manifest",
-  "version": "0.1.0-alpha.33",
+  "version": "0.1.0-alpha.35",
   "description": "The shape of a Brydio app's manifest, its collections' schemas, and the checks that say what is wrong with one.",
   "type": "module",
   "license": "MIT",
@@ -10,7 +10,7 @@
     "url": "https://github.com/nakel-ola/brydio-sdk",
     "directory": "packages/manifest"
   },
-  "gitHead": "664471f08e89483e25fb1bd49dfd69709b575bfa",
+  "gitHead": "5bd1e984602ccea955d5755e613fe773ae4899ca",
   "exports": {
     ".": {
       "types": "./src/index.d.ts",

package/src/confirm-email.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * The confirmation email of a public form (FO04). Mirrors Brydio's
+ * `apps/api/src/apps/manifest/confirm-email.ts`; the two change together.
+ *
+ * An app only declares it: which field of a `publicSubmit` collection holds
+ * the visitor's address, and a short plain text to say. Brydio decides the
+ * rest — when it is sent, to whom, how often, from whom — so an anonymous
+ * page can never be used to send anybody anything else.
+ */
+export declare const CONFIRM_LIMITS: {
+    readonly subjectChars: 120;
+    readonly messageChars: 600;
+};
+export declare const confirmEmailSchema: z.ZodObject<{
+    field: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    link: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ConfirmEmailDeclared = z.infer<typeof confirmEmailSchema>;
+/** As the host reads it, on `CollectionSpec.confirmEmail`. */
+export interface ConfirmEmailSpec {
+    field: string;
+    subject: string | null;
+    message: string | null;
+    link: boolean;
+}
+export type ConfirmProblemCode = 'data_confirm_submit' | 'data_confirm_field' | 'data_confirm_text';
+export declare function confirmEmailProblems(collection: string, declared: {
+    schema: Record<string, unknown>;
+    publicSubmit?: boolean;
+    confirmEmail?: ConfirmEmailDeclared;
+}): {
+    code: ConfirmProblemCode;
+    collection: string;
+    field?: string;
+    message: string;
+}[];
+export declare function confirmEmailSpec(declared: ConfirmEmailDeclared): ConfirmEmailSpec;

package/src/confirm-email.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { FIELD_LIMITS, parseFieldType } from "./field-types.js";
+/**
+ * The confirmation email of a public form (FO04). Mirrors Brydio's
+ * `apps/api/src/apps/manifest/confirm-email.ts`; the two change together.
+ *
+ * An app only declares it: which field of a `publicSubmit` collection holds
+ * the visitor's address, and a short plain text to say. Brydio decides the
+ * rest — when it is sent, to whom, how often, from whom — so an anonymous
+ * page can never be used to send anybody anything else.
+ */
+export const CONFIRM_LIMITS = {
+    subjectChars: 120,
+    messageChars: 600,
+};
+export const confirmEmailSchema = z
+    .object({
+    /** A `string` field of the same collection: the visitor's address. */
+    field: z.string().min(1).max(FIELD_LIMITS.nameChars),
+    subject: z.string().min(1).max(CONFIRM_LIMITS.subjectChars).optional(),
+    /** Plain text; a blank line starts a new paragraph. */
+    message: z.string().min(1).max(CONFIRM_LIMITS.messageChars).optional(),
+    /** One button back to the public page the visitor answered. */
+    link: z.boolean().optional(),
+})
+    .strict();
+/** A link, an address a client would turn into one, or markup. */
+const NOT_PLAIN = /(?:[a-z][a-z0-9+.-]*:\/\/|www\.|[<>]|\]\(|mailto:)/i;
+export function confirmEmailProblems(collection, declared) {
+    const confirm = declared.confirmEmail;
+    if (!confirm)
+        return [];
+    const problems = [];
+    if (!declared.publicSubmit) {
+        problems.push({
+            code: 'data_confirm_submit',
+            collection,
+            message: `${collection} sends a confirmation email but visitors can't submit to it: mark it publicSubmit.`,
+        });
+    }
+    const raw = declared.schema[confirm.field];
+    let kind = null;
+    try {
+        kind = raw === undefined ? null : parseFieldType(raw).kind;
+    }
+    catch {
+        kind = null;
+    }
+    if (kind !== 'string') {
+        problems.push({
+            code: 'data_confirm_field',
+            collection,
+            field: confirm.field,
+            message: `${collection}.confirmEmail.field must name one of its string fields; ${confirm.field} is not.`,
+        });
+    }
+    for (const [key, text] of [
+        ['subject', confirm.subject],
+        ['message', confirm.message],
+    ]) {
+        if (text !== undefined && NOT_PLAIN.test(text)) {
+            problems.push({
+                code: 'data_confirm_text',
+                collection,
+                message: `${collection}.confirmEmail.${key} is plain text: no links, addresses or markup.`,
+            });
+        }
+    }
+    return problems;
+}
+export function confirmEmailSpec(declared) {
+    return {
+        field: declared.field,
+        subject: declared.subject?.trim() || null,
+        message: declared.message?.trim() || null,
+        link: declared.link === true,
+    };
+}

package/src/field-types.d.ts

@@ -34,6 +34,12 @@ export interface FieldType {
      * check, and a tool's change to it merges into the live text.
      */
     coedit?: boolean;
+    /**
+     * Kept in the plain `fields` column although its kind is not (P5): an
+     * open-schema table's multi-select and link lists, and the field naming a
+     * row's table. Set by the host only, never parsed from a manifest.
+     */
+    plain?: boolean;
 }
 /**
  * The bounds a schema and a record are held to (A3-F01-S03).

package/src/field-types.js

@@ -209,9 +209,9 @@ function parseEnumeration(values) {
     return { kind: 'enum', optional: false, values: values };
 }
 /** True for a type whose value lands in the plain `fields` column. */
-export const isStructured = (type) => STRUCTURED.has(type.kind);
+export const isStructured = (type) => STRUCTURED.has(type.kind) || type.plain === true;
 /** True for a type a list can be ordered by: structured, and one value. */
-export const isSortable = (type) => STRUCTURED.has(type.kind);
+export const isSortable = (type) => STRUCTURED.has(type.kind) || (type.plain === true && type.kind !== 'string[]');
 export const isSearchable = (type) => SEARCHABLE.has(type.kind);
 /**
  * The names of a schema's structured fields: the ones kept in plain beside the

package/src/index.d.ts

@@ -8,6 +8,8 @@ export { BRAND_FIELDS, BRAND_LIMITS, brandFilePath, brandPathsOf, brandProblems,
 export { BUNDLE_MANIFEST, BUNDLE_MAX_BYTES, BUNDLE_PATH_MAX_CHARS, bundleBytes, bundleHash, brandOf, bundleProblem, codeOf, isBundlePath, isScriptPath, sizeOf, type BundleFiles, type BundleProblem, type BundleProblemCode, } from './bundle.js';
 export { COLOUR_TOKENS, coeditedFields, FIELD_LIMITS, RESERVED_FIELDS, describeType, isCoedited, isSearchable, isSortable, isStructured, parseFieldType, structuredFields, valueProblem, valueSchema, FieldTypeInvalid, type DocumentOf, type FieldKind, type FieldType, type FieldValue, type FieldsOf, } from './field-types.js';
 export { appManifestSchema, collectionOf, collectionsOf, dataProblems, effectivePlacementKey, HOME_CARD_SIZES, labelOf, manifestExtensionsSchema, newAppManifestSchema, SIZED_PLACEMENT_KINDS, MAX_APP_SECRETS, MAX_SECRET_CHARS, PLACEMENT_KEY, SECRET_NAME, storedExtensionsSchema, type AppManifestWithData, type CollectionSpec, type DataProblem, type DataProblemCode, type DataProblemOptions, type HomeCardSize, type ManifestExtensions, type SecretSpec, } from './schema.js';
+export { OPEN_LIMITS, OPEN_TYPES, choicesProblem, definitionOf, definitionTypeProblem, describeField, fieldTypeOf, hasChoices, isPlainOpenType, keyFromName, keyProblem, missingRequired, moveValue, openSchemaProblems, openSpec, openValueProblem, type Moved, type OpenField, type OpenFieldChange, type OpenFieldValue, type OpenProblem, type OpenProblemCode, type OpenSchemaFlag, type OpenType, } from './open-schema.js';
+export { CONFIRM_LIMITS, confirmEmailProblems, confirmEmailSpec, type ConfirmEmailDeclared, type ConfirmEmailSpec, type ConfirmProblemCode, } from './confirm-email.js';
 export { DOCUMENT_LIMITS } from './document-limits.js';
 export { HOST_CAPABILITIES, KNOWN_HOST_GRANTS, isHostCapability, unknownHostGrant } from './grants.js';
 export { diffSchemas, migrationProblems, migrationSchema, migrationStepSchema, migrationsSchema, publishedMigrationProblems, schemaOf, type Migration, type MigrationCode, type MigrationProblem, type MigrationStep, type SchemaChange, } from './migrations.js';

package/src/index.js

@@ -8,6 +8,8 @@ export { BRAND_FIELDS, BRAND_LIMITS, brandFilePath, brandPathsOf, brandProblems,
 export { BUNDLE_MANIFEST, BUNDLE_MAX_BYTES, BUNDLE_PATH_MAX_CHARS, bundleBytes, bundleHash, brandOf, bundleProblem, codeOf, isBundlePath, isScriptPath, sizeOf, } from "./bundle.js";
 export { COLOUR_TOKENS, coeditedFields, FIELD_LIMITS, RESERVED_FIELDS, describeType, isCoedited, isSearchable, isSortable, isStructured, parseFieldType, structuredFields, valueProblem, valueSchema, FieldTypeInvalid, } from "./field-types.js";
 export { appManifestSchema, collectionOf, collectionsOf, dataProblems, effectivePlacementKey, HOME_CARD_SIZES, labelOf, manifestExtensionsSchema, newAppManifestSchema, SIZED_PLACEMENT_KINDS, MAX_APP_SECRETS, MAX_SECRET_CHARS, PLACEMENT_KEY, SECRET_NAME, storedExtensionsSchema, } from "./schema.js";
+export { OPEN_LIMITS, OPEN_TYPES, choicesProblem, definitionOf, definitionTypeProblem, describeField, fieldTypeOf, hasChoices, isPlainOpenType, keyFromName, keyProblem, missingRequired, moveValue, openSchemaProblems, openSpec, openValueProblem, } from "./open-schema.js";
+export { CONFIRM_LIMITS, confirmEmailProblems, confirmEmailSpec, } from "./confirm-email.js";
 export { DOCUMENT_LIMITS } from "./document-limits.js";
 export { HOST_CAPABILITIES, KNOWN_HOST_GRANTS, isHostCapability, unknownHostGrant } from "./grants.js";
 export { diffSchemas, migrationProblems, migrationSchema, migrationStepSchema, migrationsSchema, publishedMigrationProblems, schemaOf, } from "./migrations.js";

package/src/open-schema.d.ts

@@ -0,0 +1,128 @@
+import { type FieldType } from './field-types.js';
+import type { CollectionSpec } from './schema.js';
+/**
+ * Open-schema collections (P5).
+ *
+ * A collection flagged `openSchema: { fields: "columns", table?: "table" }`
+ * keeps the fields its manifest declares, and also the fields its companion
+ * collection's records define, per table. This file is the manifest half:
+ * which types a definition may name, what the companion must declare, how a
+ * definition reads as a `FieldType` the store already knows, and how a value
+ * moves when its field changes type. The store half is
+ * `apps/data/open-schema.ts`.
+ */
+/** The types a field definition may name. */
+export declare const OPEN_TYPES: readonly ["text", "long_text", "number", "currency", "percent", "rating", "date", "datetime", "checkbox", "select", "multi_select", "person", "link", "url", "email", "phone", "attachment"];
+export type OpenType = (typeof OPEN_TYPES)[number];
+export declare const OPEN_LIMITS: {
+    /** Live rows one table may hold (DB-Q2, owner 30 Sep): measured at this size. */
+    readonly rowsPerTable: 50000;
+    /** Live field definitions one table may hold. */
+    readonly fieldsPerTable: 200;
+    /** The highest a rating may be. */
+    readonly ratingMax: 10;
+};
+/** The flag as the manifest writes it. */
+export interface OpenSchemaFlag {
+    /** The companion collection whose records define the fields. */
+    fields: string;
+    /** A `string` field on both collections naming a row's or a definition's table. */
+    table?: string;
+}
+/** One live field, read from a companion record. */
+export interface OpenField {
+    /** The companion record's id. */
+    id: string;
+    /** Stable across renames: what rows, tools, filters and sorts use. */
+    key: string;
+    name: string;
+    type: OpenType;
+    /** Null for a collection with no `table`. */
+    table: string | null;
+    choices: string[];
+    required: boolean;
+    currency?: string;
+    precision?: number;
+    linkTo?: string;
+    description?: string;
+}
+export type OpenProblemCode = 'data_open_fields_unknown' | 'data_open_fields_shape' | 'data_open_table_unknown';
+export interface OpenProblem {
+    code: OpenProblemCode;
+    field?: string;
+    message: string;
+}
+/**
+ * Everything wrong with one collection's `openSchema`, given every
+ * collection's raw schema. Empty when it is right.
+ */
+export declare function openSchemaProblems(collection: string, flag: OpenSchemaFlag, data: Readonly<Record<string, {
+    schema: Record<string, unknown>;
+    openSchema?: OpenSchemaFlag;
+}>>): OpenProblem[];
+/** A definition's type as the store's own field type: what `checked` and the list path read. */
+export declare function fieldTypeOf(field: OpenField): FieldType;
+/** True for a type whose values a definition must list. */
+export declare const hasChoices: (type: OpenType) => boolean;
+/** A definition in a few words, for an answer or a tool: `Amount (deal_size): currency, USD`. */
+export declare function describeField(field: OpenField): string;
+/**
+ * A key made from a name: `"Deal size"` → `deal_size`, suffixed when taken.
+ * Always a field name the tools can use, never a reserved one.
+ */
+export declare function keyFromName(name: string, taken: ReadonlySet<string>): string;
+/** Why a key cannot be a field's key here, or null. */
+export declare function keyProblem(key: string, fixed: ReadonlySet<string>, taken: ReadonlySet<string>): string | null;
+/** The choices a definition lists, checked: some, short, distinct. */
+export declare function choicesProblem(type: OpenType, choices: readonly string[]): string | null;
+/**
+ * What the store's own field type cannot say about an open value: a web
+ * address, an email, a rating's range, a date with no time, the choices of a
+ * multi-select. Null when it is fine; `checked` then checks the rest.
+ */
+export declare function openValueProblem(field: OpenField, value: unknown): string | null;
+/** True when a create leaves a required field out. */
+export declare const missingRequired: (field: OpenField, value: unknown) => boolean;
+/** What happened to one value when its field changed. */
+export type Moved = {
+    outcome: 'kept' | 'converted';
+    value: unknown;
+} | {
+    outcome: 'cleared';
+};
+/**
+ * One value moved from a field's old definition to its new one (P5 retype):
+ * kept when it is still right, converted when it can be read as the new type,
+ * else cleared. Never invents a choice.
+ */
+export declare function moveValue(value: unknown, from: OpenField, to: OpenField): Moved;
+/**
+ * What a field definition's change did to its table's rows: counts, never
+ * values. `rows` is how many held a value for the field. A definition's
+ * `update` or `delete` answer carries it as `fieldChange` when values moved.
+ */
+export interface OpenFieldChange {
+    field: string;
+    op: 'retype' | 'choices' | 'delete';
+    rows: number;
+    kept: number;
+    converted: number;
+    cleared: number;
+}
+/** One value an open field may hold, as a row hands it out. */
+export type OpenFieldValue = string | number | boolean | string[] | null;
+/** Open types whose values are kept in the plain column: filtered, and all but the two lists sorted. */
+export declare const isPlainOpenType: (type: OpenType) => boolean;
+/**
+ * One companion record as a definition, or null when it cannot be one.
+ * `table` is the field naming its table, if the collection has tables.
+ */
+export declare function definitionOf(id: string, body: Record<string, unknown>, table: string | null): OpenField | null;
+/**
+ * The collection's spec with one table's live fields folded in: what a row
+ * is checked against and what a list filters and sorts on. A fixed field
+ * always wins over a definition of the same key.
+ */
+export declare function openSpec(base: CollectionSpec, fields: readonly OpenField[]): CollectionSpec;
+/** Why a definition's type and choices don't go together, or null. */
+export declare function definitionTypeProblem(body: Record<string, unknown>): string | null;

package/src/open-schema.js

@@ -0,0 +1,444 @@
+// A copy of Brydio's `apps/api/src/apps/manifest/open-schema.ts`, kept exact so
+// a companion the SDK accepts is one the server accepts, and a value moved by
+// the fake host is moved as the real store moves it. Only the part after
+// "The SDK's own" at the end is not the server's.
+import { FIELD_LIMITS, FIELD_NAME, isSortable, isStructured, parseFieldType, quoted, RESERVED_FIELDS, } from "./field-types.js";
+/**
+ * Open-schema collections (P5).
+ *
+ * A collection flagged `openSchema: { fields: "columns", table?: "table" }`
+ * keeps the fields its manifest declares, and also the fields its companion
+ * collection's records define, per table. This file is the manifest half:
+ * which types a definition may name, what the companion must declare, how a
+ * definition reads as a `FieldType` the store already knows, and how a value
+ * moves when its field changes type. The store half is
+ * `apps/data/open-schema.ts`.
+ */
+/** The types a field definition may name. */
+export const OPEN_TYPES = [
+    'text',
+    'long_text',
+    'number',
+    'currency',
+    'percent',
+    'rating',
+    'date',
+    'datetime',
+    'checkbox',
+    'select',
+    'multi_select',
+    'person',
+    'link',
+    'url',
+    'email',
+    'phone',
+    'attachment',
+];
+export const OPEN_LIMITS = {
+    /** Live rows one table may hold (DB-Q2, owner 30 Sep): measured at this size. */
+    rowsPerTable: 50_000,
+    /** Live field definitions one table may hold. */
+    fieldsPerTable: 200,
+    /** The highest a rating may be. */
+    ratingMax: 10,
+};
+/**
+ * What the companion must declare: the three it must have, and the kinds of
+ * the ones the host reads when they are there. Anything else is the app's own.
+ */
+const REQUIRED_COMPANION = { key: 'string', name: 'string', type: 'enum' };
+const OPTIONAL_COMPANION = {
+    choices: ['string[]'],
+    required: ['boolean'],
+    currency: ['string'],
+    precision: ['number'],
+    linkTo: ['string'],
+    description: ['string', 'text'],
+};
+const kindOf = (raw) => {
+    try {
+        return parseFieldType(raw);
+    }
+    catch {
+        // Its own problem is reported by the field check; nothing to add here.
+        return null;
+    }
+};
+/**
+ * Everything wrong with one collection's `openSchema`, given every
+ * collection's raw schema. Empty when it is right.
+ */
+export function openSchemaProblems(collection, flag, data) {
+    const companion = data[flag.fields];
+    if (!companion || flag.fields === collection) {
+        return [
+            {
+                code: 'data_open_fields_unknown',
+                message: `${collection}.openSchema.fields names ${flag.fields}, which must be another collection of this app.`,
+            },
+        ];
+    }
+    if (companion.openSchema) {
+        return [
+            {
+                code: 'data_open_fields_unknown',
+                message: `${flag.fields} defines ${collection}'s fields, so it cannot have open fields itself.`,
+            },
+        ];
+    }
+    const problems = [];
+    const shape = `${flag.fields} defines ${collection}'s fields`;
+    for (const [field, kind] of Object.entries(REQUIRED_COMPANION)) {
+        const type = field in companion.schema ? kindOf(companion.schema[field]) : null;
+        if (!type || type.kind !== kind || (field !== 'key' && type.optional)) {
+            problems.push({
+                code: 'data_open_fields_shape',
+                field,
+                message: kind === 'enum'
+                    ? `${shape}, so it needs type: a choice of some of ${quoted(OPEN_TYPES)}.`
+                    : `${shape}, so it needs ${field}: "${kind}${field === 'key' ? '?' : ''}".`,
+            });
+            continue;
+        }
+        if (kind === 'enum') {
+            const unknown = (type.values ?? []).find(value => !OPEN_TYPES.includes(value));
+            if (unknown) {
+                problems.push({
+                    code: 'data_open_fields_shape',
+                    field,
+                    message: `${flag.fields}.type offers "${unknown}", which is not an open field type; use some of ${quoted(OPEN_TYPES)}.`,
+                });
+            }
+        }
+    }
+    for (const [field, kinds] of Object.entries(OPTIONAL_COMPANION)) {
+        if (!(field in companion.schema))
+            continue;
+        const type = kindOf(companion.schema[field]);
+        if (type && !kinds.includes(type.kind)) {
+            problems.push({
+                code: 'data_open_fields_shape',
+                field,
+                message: `${flag.fields}.${field} is read by Brydio as ${kinds.join(' or ')}; declare it so.`,
+            });
+        }
+    }
+    if (flag.table !== undefined) {
+        for (const [name, schema] of [
+            [collection, data[collection]?.schema ?? {}],
+            [flag.fields, companion.schema],
+        ]) {
+            const type = flag.table in schema ? kindOf(schema[flag.table]) : null;
+            if (!type || type.kind !== 'string' || type.optional) {
+                problems.push({
+                    code: 'data_open_table_unknown',
+                    field: flag.table,
+                    message: `${collection}.openSchema.table is ${flag.table}, so ${name} needs ${flag.table}: "string", naming each record's table.`,
+                });
+            }
+        }
+    }
+    return problems;
+}
+// ---------------------------------------------------------------------------
+// Definitions
+/** A definition's type as the store's own field type: what `checked` and the list path read. */
+export function fieldTypeOf(field) {
+    switch (field.type) {
+        case 'text':
+        case 'url':
+        case 'email':
+        case 'phone':
+            return { kind: 'string', optional: true };
+        case 'long_text':
+            return { kind: 'text', optional: true };
+        case 'number':
+        case 'currency':
+        case 'percent':
+        case 'rating':
+            return { kind: 'number', optional: true };
+        case 'date':
+        case 'datetime':
+            return { kind: 'date', optional: true };
+        case 'checkbox':
+            return { kind: 'boolean', optional: true };
+        case 'select':
+            return { kind: 'enum', optional: true, values: field.choices };
+        case 'multi_select':
+            return { kind: 'string[]', optional: true, plain: true, values: field.choices };
+        case 'person':
+            return { kind: 'member', optional: true };
+        case 'link':
+            return { kind: 'string[]', optional: true, plain: true };
+        case 'attachment':
+            return { kind: 'string[]', optional: true };
+    }
+}
+/** True for a type whose values a definition must list. */
+export const hasChoices = (type) => type === 'select' || type === 'multi_select';
+/** A definition in a few words, for an answer or a tool: `Amount (deal_size): currency, USD`. */
+export function describeField(field) {
+    const extra = hasChoices(field.type)
+        ? `, one of ${quoted(field.choices)}`
+        : field.type === 'currency' && field.currency
+            ? `, ${field.currency}`
+            : '';
+    return `${field.key} ("${field.name}"): ${field.type.replace('_', ' ')}${extra}${field.required ? ', required' : ''}`;
+}
+/**
+ * A key made from a name: `"Deal size"` → `deal_size`, suffixed when taken.
+ * Always a field name the tools can use, never a reserved one.
+ */
+export function keyFromName(name, taken) {
+    const slug = name
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, FIELD_LIMITS.nameChars - 4) || 'field';
+    const base = /^[a-z]/.test(slug) ? slug : `f_${slug}`.slice(0, FIELD_LIMITS.nameChars - 4);
+    const free = (key) => !taken.has(key) && !RESERVED_FIELDS.has(key);
+    if (free(base))
+        return base;
+    for (let n = 2;; n += 1) {
+        if (free(`${base}_${n}`))
+            return `${base}_${n}`;
+    }
+}
+/** Why a key cannot be a field's key here, or null. */
+export function keyProblem(key, fixed, taken) {
+    if (!FIELD_NAME.test(key) || key.length > FIELD_LIMITS.nameChars) {
+        return `key "${key}" must be letters, digits and _, starting with a lower-case letter, at most ${FIELD_LIMITS.nameChars} characters.`;
+    }
+    if (RESERVED_FIELDS.has(key) || fixed.has(key))
+        return `key "${key}" is a field Brydio or the app already keeps.`;
+    if (taken.has(key))
+        return `key "${key}" is already a field of this table.`;
+    return null;
+}
+/** The choices a definition lists, checked: some, short, distinct. */
+export function choicesProblem(type, choices) {
+    if (!hasChoices(type))
+        return null;
+    if (!choices.length)
+        return `A ${type.replace('_', ' ')} field needs at least one choice.`;
+    if (choices.length > FIELD_LIMITS.enumValues)
+        return `A field may offer at most ${FIELD_LIMITS.enumValues} choices.`;
+    if (choices.some(choice => !choice.trim() || choice.length > FIELD_LIMITS.enumValueChars)) {
+        return `Each choice is 1 to ${FIELD_LIMITS.enumValueChars} characters.`;
+    }
+    if (new Set(choices).size !== choices.length)
+        return 'A field offers the same choice twice.';
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Values
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,6})?)?(Z|[+-]\d{2}:\d{2})$/;
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const PHONE = /^[+()0-9 .\-/]{3,40}$/;
+const isEmpty = (value) => value === undefined || value === null || value === '' || (Array.isArray(value) && value.length === 0);
+/**
+ * What the store's own field type cannot say about an open value: a web
+ * address, an email, a rating's range, a date with no time, the choices of a
+ * multi-select. Null when it is fine; `checked` then checks the rest.
+ */
+export function openValueProblem(field, value) {
+    if (value === null || value === undefined)
+        return null;
+    const named = `${field.key} ("${field.name}")`;
+    switch (field.type) {
+        case 'url':
+            return typeof value === 'string' && isWebAddress(value) ? null : `${named} must be a web address, starting http:// or https://.`;
+        case 'email':
+            return typeof value === 'string' && EMAIL.test(value) ? null : `${named} must be an email address.`;
+        case 'phone':
+            return typeof value === 'string' && PHONE.test(value) ? null : `${named} must be a phone number.`;
+        case 'rating':
+            return Number.isInteger(value) && value >= 0 && value <= OPEN_LIMITS.ratingMax
+                ? null
+                : `${named} must be a whole number from 0 to ${OPEN_LIMITS.ratingMax}.`;
+        case 'date':
+            return typeof value === 'string' && DATE_ONLY.test(value) && !Number.isNaN(Date.parse(value))
+                ? null
+                : `${named} must be a date, written YYYY-MM-DD.`;
+        case 'datetime':
+            return typeof value === 'string' && DATE_TIME.test(value) && !Number.isNaN(Date.parse(value))
+                ? null
+                : `${named} must be a date and time, written YYYY-MM-DDTHH:MM:SSZ.`;
+        case 'multi_select': {
+            if (!Array.isArray(value))
+                return null;
+            const wrong = value.find(one => typeof one !== 'string' || !field.choices.includes(one));
+            if (wrong !== undefined)
+                return `${named} may hold only ${quoted(field.choices)}.`;
+            return new Set(value).size === value.length ? null : `${named} names the same choice twice.`;
+        }
+        default:
+            return null;
+    }
+}
+/** True when a create leaves a required field out. */
+export const missingRequired = (field, value) => field.required && isEmpty(value);
+function isWebAddress(value) {
+    try {
+        const url = new URL(value);
+        return (url.protocol === 'http:' || url.protocol === 'https:') && value.length <= FIELD_LIMITS.stringChars;
+    }
+    catch {
+        return false;
+    }
+}
+const textOf = (value) => {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (Array.isArray(value))
+        return value.map(one => textOf(one) ?? '').filter(Boolean).join(', ');
+    return null;
+};
+const choiceOf = (choices, value) => choices.find(choice => choice === value) ?? choices.find(choice => choice.toLowerCase() === value.trim().toLowerCase());
+/**
+ * One value moved from a field's old definition to its new one (P5 retype):
+ * kept when it is still right, converted when it can be read as the new type,
+ * else cleared. Never invents a choice.
+ */
+export function moveValue(value, from, to) {
+    const moved = convert(value, from, to);
+    if (moved === undefined || isEmpty(moved))
+        return { outcome: 'cleared' };
+    const settled = openValueProblem(to, moved) === null;
+    if (!settled)
+        return { outcome: 'cleared' };
+    return { outcome: JSON.stringify(moved) === JSON.stringify(value) ? 'kept' : 'converted', value: moved };
+}
+function convert(value, from, to) {
+    const text = textOf(value);
+    switch (to.type) {
+        case 'text':
+            return text === null ? undefined : text.slice(0, FIELD_LIMITS.stringChars);
+        case 'long_text':
+            return text === null ? undefined : text.slice(0, FIELD_LIMITS.textChars);
+        case 'url':
+        case 'email':
+        case 'phone':
+            return text === null ? undefined : text.trim();
+        case 'number':
+        case 'currency':
+        case 'percent':
+        case 'rating': {
+            const number = typeof value === 'number'
+                ? value
+                : typeof value === 'boolean'
+                    ? Number(value)
+                    : typeof value === 'string' && value.trim()
+                        ? Number(value.trim().replace(/[\s,%$€£¥]/g, ''))
+                        : Number.NaN;
+            if (!Number.isFinite(number))
+                return undefined;
+            return to.type === 'rating' ? Math.round(number) : number;
+        }
+        case 'checkbox':
+            if (typeof value === 'boolean')
+                return value;
+            if (typeof value === 'number')
+                return value !== 0;
+            if (typeof value === 'string') {
+                if (/^(true|yes|y|1|x|checked|done)$/i.test(value.trim()))
+                    return true;
+                if (/^(false|no|n|0|unchecked)$/i.test(value.trim()))
+                    return false;
+            }
+            return undefined;
+        case 'date':
+        case 'datetime': {
+            if (typeof value !== 'string')
+                return undefined;
+            const head = value.trim();
+            if (to.type === 'date' && /^\d{4}-\d{2}-\d{2}/.test(head))
+                return head.slice(0, 10);
+            const at = Date.parse(DATE_ONLY.test(head) ? `${head}T00:00:00Z` : head);
+            if (Number.isNaN(at))
+                return undefined;
+            return to.type === 'date' ? new Date(at).toISOString().slice(0, 10) : new Date(at).toISOString();
+        }
+        case 'select': {
+            const candidates = Array.isArray(value) ? value : [text ?? ''];
+            for (const one of candidates) {
+                const found = typeof one === 'string' ? choiceOf(to.choices, one) : undefined;
+                if (found)
+                    return found;
+            }
+            return undefined;
+        }
+        case 'multi_select': {
+            const candidates = Array.isArray(value) ? value : (text ?? '').split(',');
+            const found = candidates
+                .map(one => (typeof one === 'string' ? choiceOf(to.choices, one) : undefined))
+                .filter((one) => Boolean(one));
+            return [...new Set(found)];
+        }
+        case 'person':
+            return from.type === 'person' ? value : undefined;
+        case 'link':
+        case 'attachment':
+            return from.type === to.type ? value : undefined;
+    }
+}
+/** Open types whose values are kept in the plain column: filtered, and all but the two lists sorted. */
+export const isPlainOpenType = (type) => !['text', 'long_text', 'url', 'email', 'phone', 'attachment'].includes(type);
+/**
+ * One companion record as a definition, or null when it cannot be one.
+ * `table` is the field naming its table, if the collection has tables.
+ */
+export function definitionOf(id, body, table) {
+    const { key, name, type } = body;
+    if (typeof key !== 'string' || typeof name !== 'string' || !OPEN_TYPES.includes(type)) {
+        return null;
+    }
+    const tableValue = table ? body[table] : null;
+    if (table && typeof tableValue !== 'string')
+        return null;
+    return {
+        id,
+        key,
+        name,
+        type: type,
+        table: tableValue ?? null,
+        choices: Array.isArray(body.choices) ? body.choices.filter((one) => typeof one === 'string') : [],
+        required: body.required === true,
+        ...(typeof body.currency === 'string' ? { currency: body.currency } : {}),
+        ...(typeof body.precision === 'number' ? { precision: body.precision } : {}),
+        ...(typeof body.linkTo === 'string' ? { linkTo: body.linkTo } : {}),
+        ...(typeof body.description === 'string' ? { description: body.description } : {}),
+    };
+}
+/**
+ * The collection's spec with one table's live fields folded in: what a row
+ * is checked against and what a list filters and sorts on. A fixed field
+ * always wins over a definition of the same key.
+ */
+export function openSpec(base, fields) {
+    const added = fields.filter(field => !base.fields[field.key]);
+    const types = Object.fromEntries(added.map(field => [field.key, fieldTypeOf(field)]));
+    const keys = added.map(field => field.key);
+    return {
+        ...base,
+        fields: { ...base.fields, ...types },
+        structured: [...base.structured, ...keys.filter(key => isStructured(types[key]))],
+        sortable: [...base.sortable, ...keys.filter(key => isSortable(types[key]))],
+        search: [...base.search, ...added.filter(field => field.type === 'text' || field.type === 'long_text').map(field => field.key)],
+    };
+}
+/** Why a definition's type and choices don't go together, or null. */
+export function definitionTypeProblem(body) {
+    const type = body.type;
+    if (typeof type !== 'string' || !OPEN_TYPES.includes(type))
+        return null;
+    const choices = Array.isArray(body.choices) ? body.choices.filter((one) => typeof one === 'string') : [];
+    return choicesProblem(type, choices);
+}

package/src/schema.d.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { FieldTypeInvalid, type FieldType } from './field-types.js';
+import { type OpenProblemCode } from './open-schema.js';
+import { type ConfirmProblemCode } from './confirm-email.js';
 export { COLOUR_TOKENS, FIELD_LIMITS, parseFieldType, RESERVED_FIELDS, structuredFields, type FieldKind, type FieldType, } from './field-types.js';
 /**
  * What an app adds to `.brydio/app.json` to be more than a bundle of servers
@@ -143,8 +145,18 @@ declare const extensionShape: {
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         search: z.ZodOptional<z.ZodArray<z.ZodString>>;
         label: z.ZodOptional<z.ZodString>;
+        openSchema: z.ZodOptional<z.ZodObject<{
+            fields: z.ZodString;
+            table: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         publicRead: z.ZodOptional<z.ZodBoolean>;
         publicSubmit: z.ZodOptional<z.ZodBoolean>;
+        confirmEmail: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            subject: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+            link: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>>;
     tools: z.ZodOptional<z.ZodObject<{
         generated: z.ZodOptional<z.ZodBoolean>;
@@ -223,7 +235,7 @@ export interface DataProblem {
     field?: string;
     message: string;
 }
-export type DataProblemCode = FieldTypeInvalid['code'] | 'data_too_many_collections' | 'data_too_many_fields' | 'data_collection_name_format' | 'data_field_name_format' | 'data_field_reserved' | 'data_label_format' | 'data_label_taken' | 'data_project_field_twice' | 'data_search_unknown_field' | 'data_search_not_text' | 'grant_collection_missing' | 'grant_tool_missing' | 'custom_name_taken' | 'custom_collection_unknown' | 'custom_input_invalid' | 'placement_key_taken' | 'placement_screen_unknown' | 'placement_home_sizes' | 'placement_sizes_not_home' | 'placement_widget_sizes' | 'placement_tab_retired' | 'placement_public_shape' | 'placement_public_nothing' | 'placement_children_too_deep' | 'placement_create_tool_unknown' | 'placement_create_not_write' | 'secret_name_taken' | 'grant_secrets_missing';
+export type DataProblemCode = FieldTypeInvalid['code'] | OpenProblemCode | ConfirmProblemCode | 'data_too_many_collections' | 'data_too_many_fields' | 'data_collection_name_format' | 'data_field_name_format' | 'data_field_reserved' | 'data_label_format' | 'data_label_taken' | 'data_project_field_twice' | 'data_search_unknown_field' | 'data_search_not_text' | 'grant_collection_missing' | 'grant_tool_missing' | 'custom_name_taken' | 'custom_collection_unknown' | 'custom_input_invalid' | 'placement_key_taken' | 'placement_screen_unknown' | 'placement_home_sizes' | 'placement_sizes_not_home' | 'placement_widget_sizes' | 'placement_tab_retired' | 'placement_public_shape' | 'placement_public_nothing' | 'placement_children_too_deep' | 'placement_create_tool_unknown' | 'placement_create_not_write' | 'secret_name_taken' | 'grant_secrets_missing';
 type Additions = z.infer<z.ZodObject<typeof extensionShape>>;
 /**
  * Everything wrong with an app's additions that a type cannot say.
@@ -294,8 +306,18 @@ export declare const manifestExtensionsSchema: z.ZodObject<{
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         search: z.ZodOptional<z.ZodArray<z.ZodString>>;
         label: z.ZodOptional<z.ZodString>;
+        openSchema: z.ZodOptional<z.ZodObject<{
+            fields: z.ZodString;
+            table: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         publicRead: z.ZodOptional<z.ZodBoolean>;
         publicSubmit: z.ZodOptional<z.ZodBoolean>;
+        confirmEmail: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            subject: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+            link: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>>;
     tools: z.ZodOptional<z.ZodObject<{
         generated: z.ZodOptional<z.ZodBoolean>;
@@ -415,8 +437,18 @@ export declare const storedExtensionsSchema: z.ZodObject<{
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         search: z.ZodOptional<z.ZodArray<z.ZodString>>;
         label: z.ZodOptional<z.ZodString>;
+        openSchema: z.ZodOptional<z.ZodObject<{
+            fields: z.ZodString;
+            table: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         publicRead: z.ZodOptional<z.ZodBoolean>;
         publicSubmit: z.ZodOptional<z.ZodBoolean>;
+        confirmEmail: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            subject: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+            link: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>>;
     tools: z.ZodOptional<z.ZodObject<{
         generated: z.ZodOptional<z.ZodBoolean>;
@@ -571,8 +603,18 @@ export declare const appManifestSchema: z.ZodObject<{
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         search: z.ZodOptional<z.ZodArray<z.ZodString>>;
         label: z.ZodOptional<z.ZodString>;
+        openSchema: z.ZodOptional<z.ZodObject<{
+            fields: z.ZodString;
+            table: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         publicRead: z.ZodOptional<z.ZodBoolean>;
         publicSubmit: z.ZodOptional<z.ZodBoolean>;
+        confirmEmail: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            subject: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+            link: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>>;
     tools: z.ZodOptional<z.ZodObject<{
         generated: z.ZodOptional<z.ZodBoolean>;
@@ -731,8 +773,18 @@ export declare const newAppManifestSchema: z.ZodObject<{
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         search: z.ZodOptional<z.ZodArray<z.ZodString>>;
         label: z.ZodOptional<z.ZodString>;
+        openSchema: z.ZodOptional<z.ZodObject<{
+            fields: z.ZodString;
+            table: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         publicRead: z.ZodOptional<z.ZodBoolean>;
         publicSubmit: z.ZodOptional<z.ZodBoolean>;
+        confirmEmail: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            subject: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+            link: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>>;
     tools: z.ZodOptional<z.ZodObject<{
         generated: z.ZodOptional<z.ZodBoolean>;
@@ -812,6 +864,17 @@ export interface CollectionSpec {
     search: string[];
     /** The one `project` field, whose value is copied to `app_document.project_id`. */
     projectField: string | null;
+    /**
+     * Fields defined at runtime (P5): the companion collection, and the field
+     * naming a row's table (null: one table per instance). The store reads the
+     * live definitions; `fields` here holds only the manifest's own.
+     */
+    openSchema?: {
+        fields: string;
+        table: string | null;
+    };
+    /** On a companion: the open collection whose fields its records define (P5). */
+    definesFieldsOf?: string;
 }
 /**
  * The singular a collection's tools are named with: the manifest's, else the

package/src/schema.js

@@ -2,6 +2,8 @@ import { z } from 'zod';
 import { MANIFEST_LIMITS, SEMVER_FORMAT, baseManifestSchema as manifestSchema } from "./base.js";
 import { COLLECTION_NAME, FIELD_LIMITS, FIELD_NAME, FieldTypeInvalid, isSearchable, isSortable, isStructured, parseFieldType, RESERVED_FIELDS, } from "./field-types.js";
 import { migrationsSchema } from "./migrations.js";
+import { openSchemaProblems } from "./open-schema.js";
+import { confirmEmailProblems, confirmEmailSchema } from "./confirm-email.js";
 export { COLOUR_TOKENS, FIELD_LIMITS, parseFieldType, RESERVED_FIELDS, structuredFields, } from "./field-types.js";
 /**
  * What an app adds to `.brydio/app.json` to be more than a bundle of servers
@@ -106,6 +108,18 @@ const collectionSchema = z.object({
     search: z.array(z.string()).optional(),
     /** The singular noun the tools are named with: `issue` gives `create_issue`. */
     label: z.string().optional(),
+    /**
+     * Fields defined at runtime as records of another collection (P5): `fields`
+     * names it, and `table`, when given, the `string` field on both naming
+     * which table a row or a definition belongs to.
+     */
+    openSchema: z
+        .object({
+        fields: z.string().min(1).max(FIELD_LIMITS.nameChars),
+        table: z.string().min(1).max(FIELD_LIMITS.nameChars).optional(),
+    })
+        .strict()
+        .optional(),
     /**
      * A visitor on one of the app's public pages may `get` and `list` every
      * record of this collection in that instance (P3).
@@ -117,6 +131,13 @@ const collectionSchema = z.object({
      * `publicRead` is set too (P3).
      */
     publicSubmit: z.boolean().optional(),
+    /**
+     * Brydio emails the visitor once after a public submission here (FO04):
+     * `field` names a `string` field holding their address; `subject` and
+     * `message` are short plain text; `link` adds a button back to the page.
+     * Needs `publicSubmit`. Brydio decides when, how often and from whom.
+     */
+    confirmEmail: confirmEmailSchema.optional(),
 });
 const screenSchema = z.object({
     /**
@@ -327,6 +348,29 @@ export function dataProblems(additions, options = {}) {
             }
         }
     }
+    // Open-schema collections (P5): the companion is declared, shaped as the
+    // host reads it, and defines one collection's fields at most.
+    const companions = new Map();
+    for (const [collection, declared] of collections) {
+        if (!declared.openSchema)
+            continue;
+        for (const problem of openSchemaProblems(collection, declared.openSchema, additions.data ?? {})) {
+            problems.push({ ...problem, collection });
+        }
+        const other = companions.get(declared.openSchema.fields);
+        if (other) {
+            problems.push({
+                code: 'data_open_fields_unknown',
+                collection,
+                message: `${declared.openSchema.fields} already defines ${other}'s fields; give ${collection} its own.`,
+            });
+        }
+        companions.set(declared.openSchema.fields, collection);
+    }
+    // A confirmation email names a string field of a collection visitors submit to (FO04).
+    for (const [collection, declared] of collections) {
+        problems.push(...confirmEmailProblems(collection, declared));
+    }
     // What the app keeps must be what it asks to keep (A3-F06-S01): a
     // collection the grants leave out would be data a workspace never agreed to
     // hold, found only when the first write is refused.
@@ -612,8 +656,16 @@ export function labelOf(collection, label) {
  */
 export function collectionsOf(manifest) {
     const parsed = storedExtensionsSchema.parse({ data: manifest.data ?? {} });
+    const owners = new Map(Object.entries(parsed.data ?? {}).flatMap(([name, declared]) => declared.openSchema ? [[declared.openSchema.fields, { name, flag: declared.openSchema }]] : []));
     return Object.entries(parsed.data ?? {}).map(([name, declared]) => {
-        const fields = Object.fromEntries(Object.entries(declared.schema).map(([field, raw]) => [field, parseFieldType(raw)]));
+        const owner = owners.get(name);
+        // The field naming a row's table is kept in plain on both sides, so a
+        // table is filtered and counted without decrypting a row (P5).
+        const tableField = declared.openSchema?.table ?? owner?.flag.table;
+        const fields = Object.fromEntries(Object.entries(declared.schema).map(([field, raw]) => {
+            const type = parseFieldType(raw);
+            return [field, field === tableField ? { ...type, plain: true } : type];
+        }));
         const label = labelOf(name, declared.label);
         const names = Object.keys(fields);
         return {
@@ -625,6 +677,10 @@ export function collectionsOf(manifest) {
             sortable: names.filter(field => isSortable(fields[field])),
             search: declared.search ?? [],
             projectField: names.find(field => fields[field].kind === 'project') ?? null,
+            ...(declared.openSchema
+                ? { openSchema: { fields: declared.openSchema.fields, table: declared.openSchema.table ?? null } }
+                : {}),
+            ...(owner ? { definesFieldsOf: owner.name } : {}),
         };
     });
 }