@businessdash/sdk 0.9.60

package/dist/data-model-schema.js

@@ -0,0 +1,2295 @@
+/**
+ * `defineDataModel` — declare an org's custom database (tables + enums) in
+ * code, push it with `biab-dev sync-data-model`, promote it in the dashboard.
+ *
+ * Deliberately SEPARATE from `marketing-schema.ts`. A website's content shape
+ * and an org's database shape are different artifacts with different review
+ * cadence, blast radius, and plausibly different owners — so they get separate
+ * config files, commands, endpoints, and API scopes. Nothing is shared but the
+ * transport conventions (canonical checksum, draft/published slots).
+ *
+ *   biab.config.ts             → defineSiteMarketingSchema → sync-schema
+ *   biab.data-model.config.ts  → defineDataModel           → sync-data-model
+ *
+ * Pure builders — no DB, no network, no side effects. Validation here is about
+ * catching a typo in CI before it becomes a push; the server re-validates
+ * everything it receives and is the real authority.
+ *
+ * See Resources/BIAB-Data-Model-CLI-Plan.md for the full design.
+ */
+export const FIELD_TYPES = [
+    "TEXT",
+    "NUMBER",
+    "NUMERIC",
+    "BOOLEAN",
+    "DATE",
+    "DATE_TIME",
+    "UUID",
+    "SELECT",
+    "MULTI_SELECT",
+    "RATING",
+    "POSITION",
+    "CURRENCY",
+    "EMAILS",
+    "PHONES",
+    "LINKS",
+    "ADDRESS",
+    "FULL_NAME",
+    "ACTOR",
+    "RELATION",
+    "MORPH_RELATION",
+    "FILES",
+    "RICH_TEXT",
+    "RAW_JSON",
+    "ARRAY",
+    "TS_VECTOR",
+];
+export function isFieldType(value) {
+    return FIELD_TYPES.includes(value);
+}
+/** Create a field builder with chainable methods. */
+function createFieldBuilder(initialState) {
+    const state = { ...initialState };
+    const builder = {
+        required() {
+            state.required = true;
+            state.nullable = false;
+            return builder;
+        },
+        optional() {
+            state.required = false;
+            state.nullable = true;
+            return builder;
+        },
+        nullable(value = true) {
+            state.nullable = value;
+            return builder;
+        },
+        default(value) {
+            state.defaultValue = value;
+            return builder;
+        },
+        indexed(value = true) {
+            state.indexed = value;
+            return builder;
+        },
+        unique(value = true) {
+            state.unique = value;
+            return builder;
+        },
+        description(text) {
+            state.description = text;
+            return builder;
+        },
+        helper(text) {
+            state.helperText = text;
+            return builder;
+        },
+        formElement(element, metadata) {
+            state.formElement = element;
+            state.elementMetadata = metadata;
+            return builder;
+        },
+        validate(rules) {
+            state.validation = { ...state.validation, ...rules };
+            return builder;
+        },
+        dynamicOptions(config) {
+            state.dynamicOptions = config;
+            return builder;
+        },
+        requiredIf(condition) {
+            state.validation = { ...state.validation, requiredIf: condition };
+            return builder;
+        },
+        regex(pattern) {
+            state.validation = { ...state.validation, regex: pattern };
+            return builder;
+        },
+        check(sqlExpression) {
+            state.validation = {
+                ...state.validation,
+                checkExpression: sqlExpression,
+            };
+            return builder;
+        },
+        strategy(mode, separateTableName) {
+            state.strategy = mode;
+            const meta = state.elementMetadata;
+            if (meta && "properties" in meta) {
+                meta.strategy = mode;
+                if (separateTableName)
+                    meta.separateTableName = separateTableName;
+            }
+            if (separateTableName)
+                state.separateTableName = separateTableName;
+            return builder;
+        },
+        encrypted() {
+            state.encryption = "user";
+            return builder;
+        },
+        encryptedLight() {
+            state.encryption = "master";
+            return builder;
+        },
+        private() {
+            state.isPrivate = true;
+            return builder;
+        },
+        references(targetCollection, onDelete = "restrict") {
+            state.relationMeta = { type: "one-to-many", targetCollection };
+            builder.__relationMeta = state.relationMeta;
+            state.type = "RELATION";
+            state.relationTarget = targetCollection;
+            // A reference holds ONE target — picking another replaces it, rather
+            // than quietly accumulating into a set. (Relations promoted before
+            // cardinality existed carry none and keep the old "many" behaviour, so
+            // this only applies to models pushed from here on.)
+            state.relationCardinality = "one";
+            state.onDelete = onDelete;
+            return builder;
+        },
+        belongsToMany(targetCollection, options) {
+            state.relationMeta = {
+                type: "many-to-many",
+                targetCollection,
+                ...(options?.joinCollectionName !== undefined
+                    ? { joinCollectionName: options.joinCollectionName }
+                    : {}),
+                ...(options?.fields !== undefined ? { fields: options.fields } : {}),
+            };
+            if (state.relationMeta)
+                builder.__relationMeta = state.relationMeta;
+            // "RELATION", not the "__relation__" placeholder: the placeholder isn't a
+            // real FieldType, so `getRecommendedFormElements` returned nothing for it
+            // and the generator skipped the field for having no element to render.
+            // A many-to-many is a relation like any other — same type as
+            // `.references()`, distinguished only by its cardinality.
+            state.type = "RELATION";
+            // A many-to-many is still a RELATION pointing at a target — without
+            // this the built field carried no `relationTarget` and the server
+            // rejected the whole push ("RELATION requires relationTarget"), so
+            // belongsToMany type-checked but could never be applied.
+            state.relationTarget = targetCollection;
+            state.relationCardinality = "many";
+            // Values belonging to the PAIRING become typed attributes on the link.
+            // Only assign when there are any — `exactOptionalPropertyTypes` treats
+            // an explicit `undefined` as different from an absent key.
+            const linkAttrs = compileLinkAttributes(options?.fields);
+            if (linkAttrs)
+                state.linkAttributes = linkAttrs;
+            return builder;
+        },
+        onDelete(action) {
+            if (!state.relationMeta) {
+                throw new Error("onDelete() requires a relationship — chain it after .references() or .belongsToMany().");
+            }
+            state.relationMeta.onDeleteAction = action;
+            builder.__relationMeta = state.relationMeta;
+            if (action !== "NO ACTION") {
+                state.onDelete = DELETE_ACTION_TO_ON_DELETE[action];
+            }
+            else {
+                delete state.onDelete;
+            }
+            return builder;
+        },
+        build() {
+            return buildFieldDefinition(state);
+        },
+    };
+    return builder;
+}
+/** Extract relation metadata from a builder (used by collection()). */
+function getRelationMeta(builder) {
+    return builder.__relationMeta;
+}
+/** Convert snake_case or camelCase to Title Case for labels. */
+function toLabel(text) {
+    // Split on underscores, hyphens, or camelCase boundaries
+    return text
+        .replace(/([a-z])([A-Z])/g, "$1 $2") // camelCase -> "camel Case"
+        .replace(/[_-]+/g, " ") // snake_case, kebab-case -> "snake case"
+        .trim()
+        .split(/\s+/)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join(" ");
+}
+/**
+ * Generate a universal identifier.
+ *
+ * A declaration is evaluated on every CLI run, so identities derived from
+ * collection/field names MUST be deterministic. Otherwise an unchanged config
+ * looks like a drop-and-recreate migration. Call without a seed only for the
+ * legacy object API, where callers already provide explicit identities.
+ */
+function generateUniversalIdentifier(seed) {
+    if (seed !== undefined) {
+        const words = [2166136261, 2246822519, 3266489917, 668265263];
+        for (let wordIndex = 0; wordIndex < words.length; wordIndex++) {
+            let hash = words[wordIndex];
+            for (let index = 0; index < seed.length; index++) {
+                hash ^= seed.charCodeAt(index) + wordIndex * 31;
+                hash = Math.imul(hash, 16777619 + wordIndex * 2);
+            }
+            words[wordIndex] = hash >>> 0;
+        }
+        const hex = words
+            .map((word) => word.toString(16).padStart(8, "0"))
+            .join("");
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+    }
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback for non-browser environments
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/** Convert field options to SelectOption array for enums. */
+function optionsToSelectOptions(values) {
+    // Handle both raw arrays and Enums() return objects
+    const arr = Array.isArray(values)
+        ? values
+        : values
+            .entries;
+    return arr.map((v, index) => {
+        if (typeof v === "string") {
+            return {
+                value: v,
+                label: toLabel(v),
+                position: index,
+            };
+        }
+        return {
+            value: v.value,
+            label: v.label ?? toLabel(v.value),
+            position: index,
+        };
+    });
+}
+/**
+ * Compile a `belongsToMany({ fields })` declaration into link-attribute
+ * definitions — the typed payload each link row may carry.
+ *
+ * A join's columns are declared with the same field builders as a collection's,
+ * but a link is an EDGE, not a record: only a small set of value kinds makes
+ * sense on one. Anything richer is asking for a real collection, so it maps to
+ * TEXT rather than silently pretending to be supported.
+ */
+function compileLinkAttributes(fields) {
+    if (!fields)
+        return undefined;
+    const out = [];
+    for (const [name, builder] of Object.entries(fields)) {
+        const built = builder.build();
+        const type = built.type === "NUMBER" || built.type === "NUMERIC"
+            ? "NUMBER"
+            : built.type === "BOOLEAN"
+                ? "BOOLEAN"
+                : built.type === "SELECT"
+                    ? "SELECT"
+                    : "TEXT";
+        out.push({
+            name,
+            label: built.label || name,
+            type,
+            ...(type === "SELECT" && built.options
+                ? { options: built.options.map((o) => o.value) }
+                : {}),
+            ...(built.isRequired ? { isRequired: true } : {}),
+            ...(built.description ? { description: built.description } : {}),
+        });
+    }
+    return out.length > 0 ? out : undefined;
+}
+/** Build a complete FieldDefinition from builder state. */
+function buildFieldDefinition(state) {
+    const universalIdentifier = generateUniversalIdentifier();
+    const recommendedFormElements = isFieldType(state.type)
+        ? getRecommendedFormElements(state.type)
+        : [];
+    const fieldDef = {
+        universalIdentifier,
+        name: "", // Will be set by collection()
+        label: "", // Will be set by collection()
+        type: state.type === "__relation__" ? "RELATION" : state.type,
+        ...(state.description !== undefined
+            ? { description: state.description }
+            : {}),
+        ...(state.required !== undefined ? { isRequired: state.required } : {}),
+        isNullable: state.nullable ?? !state.required,
+        ...(state.unique !== undefined ? { isUnique: state.unique } : {}),
+        defaultValue: state.defaultValue,
+        ...(state.indexed !== undefined ? { isIndexed: state.indexed } : {}),
+        ...(state.formElement !== undefined
+            ? { formElement: state.formElement }
+            : {}),
+        ...(state.elementMetadata !== undefined
+            ? { elementMetadata: state.elementMetadata }
+            : {}),
+        ...(recommendedFormElements.length > 0 ? { recommendedFormElements } : {}),
+        ...(state.validation !== undefined ? { validation: state.validation } : {}),
+        ...(state.helperText !== undefined ? { helperText: state.helperText } : {}),
+        ...(state.dynamicOptions !== undefined
+            ? { dynamicOptions: state.dynamicOptions }
+            : {}),
+        ...(state.options !== undefined ? { options: state.options } : {}),
+        ...(state.relationTarget !== undefined
+            ? { relationTarget: state.relationTarget }
+            : {}),
+        ...(state.relationCardinality !== undefined
+            ? { relationCardinality: state.relationCardinality }
+            : {}),
+        ...(state.linkAttributes !== undefined
+            ? { linkAttributes: state.linkAttributes }
+            : {}),
+        ...(state.onDelete !== undefined ? { onDelete: state.onDelete } : {}),
+        ...(state.strategy !== undefined ? { strategy: state.strategy } : {}),
+        ...(state.separateTableName !== undefined
+            ? { separateTableName: state.separateTableName }
+            : {}),
+        ...(state.encryption !== undefined && state.encryption !== "none"
+            ? { encryption: state.encryption }
+            : {}),
+        ...(state.isPrivate ? { isPrivate: true } : {}),
+    };
+    // Set position to a default (will be overridden by collection)
+    fieldDef.position = 0;
+    return fieldDef;
+}
+/** The fields builder namespace — exported for consumer use. */
+export const fields = {
+    text(options) {
+        return createFieldBuilder({ type: "TEXT", ...options });
+    },
+    number(options) {
+        return createFieldBuilder({ type: "NUMBER", ...options });
+    },
+    numeric(options) {
+        return createFieldBuilder({ type: "NUMERIC", ...options });
+    },
+    boolean(options) {
+        return createFieldBuilder({ type: "BOOLEAN", ...options });
+    },
+    date(options) {
+        return createFieldBuilder({ type: "DATE", ...options });
+    },
+    dateTime(options) {
+        return createFieldBuilder({ type: "DATE_TIME", ...options });
+    },
+    uuid(options) {
+        return createFieldBuilder({ type: "UUID", ...options });
+    },
+    enum(values, options) {
+        return createFieldBuilder({
+            type: "SELECT",
+            options: optionsToSelectOptions(values),
+            ...options,
+        });
+    },
+    multiEnum(values, options) {
+        return createFieldBuilder({
+            type: "MULTI_SELECT",
+            options: optionsToSelectOptions(values),
+            ...options,
+        });
+    },
+    reference(targetCollection, options) {
+        return createFieldBuilder({
+            type: "RELATION",
+            relationTarget: targetCollection, // Will be resolved to universalIdentifier by collection()
+            onDelete: options?.onDelete ?? "restrict",
+            ...options,
+        });
+    },
+    relation() {
+        return createFieldBuilder({ type: "__relation__" });
+    },
+    url(options) {
+        return createFieldBuilder({ type: "TEXT", ...options });
+    },
+    email(options) {
+        return createFieldBuilder({ type: "EMAILS", ...options });
+    },
+    phone(options) {
+        return createFieldBuilder({ type: "PHONES", ...options });
+    },
+    richText(options) {
+        return createFieldBuilder({ type: "RICH_TEXT", ...options });
+    },
+    json(options) {
+        return createFieldBuilder({ type: "RAW_JSON", ...options });
+    },
+    array(options) {
+        return createFieldBuilder({ type: "ARRAY", ...options });
+    },
+    measurement(config, options) {
+        return createFieldBuilder({
+            type: "RAW_JSON",
+            formElement: "measurement",
+            elementMetadata: config,
+            ...options,
+        });
+    },
+    object(config, options) {
+        const props = "properties" in config ? config.properties : config;
+        const properties = Object.entries(props).map(([name, builder]) => ({
+            name,
+            field: builder.build(),
+        }));
+        return createFieldBuilder({
+            type: "RAW_JSON",
+            formElement: "object",
+            elementMetadata: { properties },
+            ...options,
+        });
+    },
+    file(config, options) {
+        return createFieldBuilder({
+            type: "FILES",
+            formElement: "formFileValue",
+            elementMetadata: config,
+            ...options,
+        });
+    },
+    address(config, options) {
+        return createFieldBuilder({
+            type: "RAW_JSON",
+            formElement: "address_group",
+            elementMetadata: config,
+            ...options,
+        });
+    },
+    geo(options) {
+        return createFieldBuilder({
+            type: "RAW_JSON",
+            formElement: "geo",
+            ...options,
+        });
+    },
+};
+/**
+ * Compact alias for `fields`. Same object, shorter name.
+ *
+ * ```ts
+ * import { bd } from "@businessdash/sdk";
+ *
+ * collection("features", {
+ *   fields: {
+ *     name: bd.text().required(),
+ *   },
+ * });
+ * ```
+ */
+export const bd = fields;
+/** Convert a table name to singular/plural names and labels. */
+function parseTableName(tableName) {
+    // For labels, keep underscores so toLabel can convert them properly
+    // For names, convert to camelCase (no underscores)
+    const singularForLabel = tableName.endsWith("ies")
+        ? `${tableName.slice(0, -3)}y`
+        : tableName.replace(/_?s$/, "");
+    const pluralForLabel = tableName;
+    const toCamelCase = (str) => str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
+    return {
+        nameSingular: toCamelCase(singularForLabel),
+        namePlural: toCamelCase(pluralForLabel),
+        labelSingular: toLabel(singularForLabel),
+        labelPlural: toLabel(pluralForLabel),
+        labelIdentifierFieldName: toCamelCase(singularForLabel),
+    };
+}
+/**
+ * Define a collection (table) with a fluent fields API.
+ *
+ * @example
+ * ```ts
+ * const FeatureStatus = Enums(["planned", "inProgress", "completed"]);
+ *
+ * const featureGroups = collection("feature_groups", {
+ *   fields: {
+ *     name: fields.text().required(),
+ *     category_id: fields.reference("categories").required(),
+ *     status: fields.enum(FeatureStatus).default("planned"),
+ *     icon: fields.text().optional(),
+ *     image_url: fields.url().optional(),
+ *   },
+ * });
+ * ```
+ */
+export function collection(tableName, options) {
+    const { nameSingular, namePlural, labelSingular, labelPlural, labelIdentifierFieldName, } = parseTableName(tableName);
+    const universalIdentifier = options.universalIdentifier ??
+        generateUniversalIdentifier(`biab:collection:${nameSingular}`);
+    // Build fields with proper names and labels, collecting relation metadata
+    const fieldEntries = Object.entries(options.fields);
+    const relations = [];
+    let fieldIndex = 0;
+    const fields = [];
+    for (const [fieldName, builder] of fieldEntries) {
+        const relationMeta = getRelationMeta(builder);
+        if (relationMeta) {
+            relations.push({ fieldName, meta: relationMeta });
+        }
+        // A many-to-many USED TO be dropped here: the parent got no field at all,
+        // on the assumption that the link belonged to a separate join collection
+        // the author would build a second form for. That's the leak — it forced
+        // everyone to understand join tables to fill in a relationship.
+        //
+        // It now compiles to a normal RELATION field on the parent (cardinality
+        // "many"), so the generator gives it a live multi-picker and the link rows
+        // are written from the same form. The link storage is still the universal
+        // link table; there is no per-pair collection to name or maintain.
+        const fieldDef = builder.build();
+        fields.push({
+            ...fieldDef,
+            universalIdentifier: generateUniversalIdentifier(`biab:collection:${nameSingular}:field:${fieldName}`),
+            name: fieldName,
+            label: toLabel(fieldName),
+            position: fieldIndex,
+        });
+        fieldIndex++;
+    }
+    // Resolve reference targets (collection names -> universalIdentifiers)
+    // This would need a registry of all collections to work properly
+    // For now, we store the target collection name and let the consumer resolve it
+    return {
+        universalIdentifier,
+        nameSingular,
+        namePlural,
+        labelSingular,
+        labelPlural,
+        labelIdentifierFieldName: options.labelIdentifierFieldName ??
+            (options.fields["name"]
+                ? "name"
+                : (fields[0]?.name ?? labelIdentifierFieldName)),
+        ...(options.icon !== undefined ? { icon: options.icon } : {}),
+        ...(options.description !== undefined
+            ? { description: options.description }
+            : {}),
+        ...(options.visibility !== undefined
+            ? { visibility: options.visibility }
+            : {}),
+        ...(options.idType !== undefined ? { idType: options.idType } : {}),
+        kind: "custom",
+        ...(options.rlsPolicies !== undefined
+            ? { rlsPolicies: options.rlsPolicies }
+            : {}),
+        fields,
+        ...(relations.length > 0 ? { relations } : {}),
+    };
+}
+/**
+ * Polymorphic relations (one field pointing at several object kinds) aren't
+ * accepted yet. Declaring one fails fast here rather than at upload.
+ */
+export const UNSUPPORTED_FIELD_TYPES = ["MORPH_RELATION"];
+/** Relation values live in a link table, not in the record's own storage. */
+export const RELATION_FIELD_TYPES = [
+    "RELATION",
+    "MORPH_RELATION",
+];
+export function isRelationFieldType(type) {
+    return RELATION_FIELD_TYPES.includes(type);
+}
+const DELETE_ACTION_TO_ON_DELETE = {
+    CASCADE: "cascade",
+    RESTRICT: "restrict",
+    "SET NULL": "setNull",
+    "NO ACTION": undefined,
+};
+export const PREDEFINED_UNITS = {
+    sound: ["dB"],
+    pressure: ["Pa", "kPa", "bar", "psi", "atm", "mmHg"],
+    torque: ["in-lb", "N-m", "ft-lb", "kgf-m"],
+    speed: ["m/s", "km/h", "mph", "ft/s", "kn", "ly/yr", "c", "Mach"],
+    time: ["ms", "s", "min", "h", "day", "wk", "yr"],
+    area: ["m2", "km2", "ft2", "ac", "ha", "mi2"],
+    volume: ["mL", "L", "m3", "fl oz", "cup", "pt", "qt", "gal"],
+    power: ["W", "kW", "MW", "GW", "hp"],
+    energy: ["J", "kJ", "Wh", "kWh", "MWh", "cal", "kcal"],
+    storage: ["B", "KB", "MB", "GB", "TB", "PB", "KiB", "MiB", "GiB", "TiB"],
+    storageSpeed: ["MHz", "MT/s", "GB/s", "MB/s", "IOPS", "GT/s"],
+    frequency: ["Hz", "kHz", "MHz", "GHz", "THz"],
+    temperature: ["C", "F", "K"],
+    mass: ["mg", "g", "kg", "t", "oz", "lb", "st"],
+    length: ["nm", "µm", "mm", "cm", "m", "km", "in", "ft", "yd", "mi"],
+    currency: ["USD", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "CNY", "INR"],
+};
+/** Runtime field value validator using ValidationRules. */
+export function validateFieldValue(value, rules, context) {
+    if (value === undefined || value === null || value === "") {
+        if (rules.notNull) {
+            return {
+                valid: false,
+                value,
+                error: "Value is required and cannot be null or empty.",
+            };
+        }
+        if (rules.requiredIf && context) {
+            const refValue = context[rules.requiredIf.fieldRef];
+            const conditionMet = rules.requiredIf.op === "equals"
+                ? rules.requiredIf.values.includes(refValue)
+                : !rules.requiredIf.values.includes(refValue);
+            if (conditionMet) {
+                return {
+                    valid: false,
+                    value,
+                    error: `This field is required when "${rules.requiredIf.fieldRef}" ${rules.requiredIf.op === "equals" ? "equals" : "does not equal"} one of [${rules.requiredIf.values.join(", ")}].`,
+                };
+            }
+        }
+        return { valid: true, value: null };
+    }
+    // String / array length checks — also return early for plain strings/arrays
+    // when no date rule applies (date values are strings that need further checks).
+    if (typeof value === "string" || Array.isArray(value)) {
+        const len = value.length;
+        if (rules.minLength !== undefined && len < rules.minLength) {
+            return {
+                valid: false,
+                value,
+                error: `Must contain at least ${rules.minLength} entries or characters.`,
+            };
+        }
+        if (rules.maxLength !== undefined && len > rules.maxLength) {
+            return {
+                valid: false,
+                value,
+                error: `Must contain no more than ${rules.maxLength} entries or characters.`,
+            };
+        }
+        if (rules.regex && typeof value === "string") {
+            const pattern = typeof rules.regex === "string" ? new RegExp(rules.regex) : rules.regex;
+            if (!pattern.test(value)) {
+                return {
+                    valid: false,
+                    value,
+                    error: `Value does not match the required pattern.`,
+                };
+            }
+        }
+        const hasDateRule = rules.lessThanToday || rules.greaterThanToday || rules.specificDateValue;
+        if (!hasDateRule) {
+            return { valid: true, value };
+        }
+    }
+    // Date checks — must run before numeric NaN short-circuit (date strings
+    // like "2000-01-01" are NaN when cast to Number but still need validation).
+    if (rules.lessThanToday ||
+        rules.greaterThanToday ||
+        rules.specificDateValue) {
+        if (typeof value !== "string" && typeof value !== "number") {
+            return { valid: false, value, error: "Value is not a valid date." };
+        }
+        const targetTime = new Date(value).getTime();
+        if (Number.isNaN(targetTime)) {
+            return { valid: false, value, error: "Value is not a valid date." };
+        }
+        const now = new Date();
+        const todayStart = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+        if (rules.lessThanToday && targetTime >= todayStart) {
+            return {
+                valid: false,
+                value,
+                error: "Date must be historical (less than today).",
+            };
+        }
+        if (rules.greaterThanToday && targetTime <= todayStart) {
+            return {
+                valid: false,
+                value,
+                error: "Date must be a future target (greater than today).",
+            };
+        }
+        if (rules.specificDateValue === "today()" && targetTime !== todayStart) {
+            return {
+                valid: false,
+                value,
+                error: "Date value must map exactly to today.",
+            };
+        }
+        return { valid: true, value };
+    }
+    // Numeric checks
+    const numericValue = Number(value);
+    if (Number.isNaN(numericValue)) {
+        return { valid: true, value };
+    }
+    if (rules.positive && numericValue < 0) {
+        return {
+            valid: false,
+            value: numericValue,
+            error: "Value must be a positive number (greater than or equal to 0).",
+        };
+    }
+    if (rules.lessThan !== undefined && numericValue >= rules.lessThan) {
+        return {
+            valid: false,
+            value: numericValue,
+            error: `Value must be strictly less than ${rules.lessThan}.`,
+        };
+    }
+    if (rules.greaterThan !== undefined && numericValue <= rules.greaterThan) {
+        return {
+            valid: false,
+            value: numericValue,
+            error: `Value must be strictly greater than ${rules.greaterThan}.`,
+        };
+    }
+    if (rules.isDecimal && numericValue % 1 === 0) {
+        return {
+            valid: false,
+            value: numericValue,
+            error: "Value must contain an active decimal fractional component.",
+        };
+    }
+    // Transform: apply rounding or floor
+    let transformed = numericValue;
+    if (rules.round !== undefined) {
+        const factor = 10 ** rules.round;
+        transformed = Math.round(transformed * factor) / factor;
+    }
+    else if (rules.floor) {
+        transformed = Math.floor(transformed);
+    }
+    if (transformed !== numericValue) {
+        return { valid: true, value: transformed };
+    }
+    return { valid: true, value: numericValue };
+}
+/** Runtime measurement value validator. */
+export function validateAndResolveMeasurement(input, meta) {
+    if (input.value === undefined || input.value === null) {
+        return { valid: true };
+    }
+    const numValue = Number(input.value);
+    if (Number.isNaN(numValue)) {
+        return { valid: false, error: "Measurement value must be a valid number." };
+    }
+    if (!meta.allow_decimals && numValue % 1 !== 0) {
+        return {
+            valid: false,
+            error: `Decimals are not allowed for measurement category "${meta.category}".`,
+        };
+    }
+    if (meta.unitPicker === "fixed" && meta.category in PREDEFINED_UNITS) {
+        const allowed = PREDEFINED_UNITS[meta.category];
+        if (allowed && !allowed.includes(input.unit)) {
+            return {
+                valid: false,
+                error: `Unit "${input.unit}" is not in the fixed set [${allowed.join(", ")}] for category "${meta.category}".`,
+            };
+        }
+    }
+    let finalValue = numValue;
+    if (meta.resolve_to_your_unit && input.unit !== meta.resolve_to_your_unit) {
+        finalValue = numValue;
+    }
+    return {
+        valid: true,
+        value: { value: finalValue, unit: meta.resolve_to_your_unit || input.unit },
+    };
+}
+/** Compatibility map: FieldType → valid form element names. */
+const FIELD_FORM_ELEMENT_MAP = {
+    TEXT: [
+        "short_text",
+        "long_text",
+        "email",
+        "url",
+        "rich_text_input",
+        "dropdown",
+        "radio_group",
+        "choice_cards",
+        "services_selector",
+        "phone_number",
+        "date",
+        "credit_card",
+        "collection_select",
+        "timePicker",
+        "time_picker.date",
+        "time_picker.time",
+        "color",
+    ],
+    NUMBER: [
+        "number",
+        "currency",
+        "range",
+        "star_rating",
+        "happiness_rating",
+        "phone_number_basic",
+    ],
+    NUMERIC: [
+        "number",
+        "currency",
+        "range",
+        "star_rating",
+        "happiness_rating",
+        "phone_number_basic",
+    ],
+    BOOLEAN: ["yes_no_toggle", "yes_no_checkbox"],
+    DATE: ["date", "date_range"],
+    DATE_TIME: [
+        "timePicker",
+        "time_picker.date",
+        "time_picker.time",
+        "time_picker_timeslot",
+        "time_picker_datetime",
+        "date_range",
+    ],
+    UUID: ["short_text"],
+    SELECT: ["dropdown", "radio_group"],
+    MULTI_SELECT: ["multi-select", "checkbox_group", "tags"],
+    RELATION: ["collection_select"],
+    RICH_TEXT: ["rich_text_input"],
+    RAW_JSON: [
+        "address_group",
+        "measurement",
+        "availability",
+        "date_range",
+        "object",
+        "geo",
+        "time_picker_timeslot",
+        "time_picker_datetime",
+    ],
+    ARRAY: [
+        "multi-select",
+        "checkbox_group_many",
+        "choice_cards_many",
+        "services_selector_many",
+        "tags",
+        "formFileValue",
+    ],
+    EMAILS: ["email"],
+    PHONES: ["phone_number", "phone_number_basic"],
+    RATING: ["star_rating", "happiness_rating"],
+    CURRENCY: ["currency"],
+    FILES: ["formFileValue"],
+};
+function getRecommendedFormElements(fieldType) {
+    return FIELD_FORM_ELEMENT_MAP[fieldType] ?? [];
+}
+function isValidFormElement(fieldType, elementName) {
+    const allowed = FIELD_FORM_ELEMENT_MAP[fieldType];
+    if (!allowed)
+        return false;
+    return allowed.some((e) => e === elementName);
+}
+const NAME_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
+function assertSelectOptions(def) {
+    const isSelect = def.type === "SELECT" || def.type === "MULTI_SELECT";
+    if (!isSelect) {
+        if (def.options && def.options.length > 0) {
+            throw new Error(`defineField: "${def.name}" is a ${def.type} field but declares options — options belong to SELECT / MULTI_SELECT.`);
+        }
+        return;
+    }
+    if (!def.options || def.options.length === 0) {
+        throw new Error(`defineField: ${def.type} field "${def.name}" requires at least one option.`);
+    }
+    const values = new Set();
+    const identifiers = new Set();
+    for (const option of def.options) {
+        if (!option.value) {
+            throw new Error(`defineField: ${def.type} field "${def.name}" has an option with an empty value.`);
+        }
+        if (values.has(option.value)) {
+            throw new Error(`defineField: ${def.type} field "${def.name}" has duplicate option value "${option.value}".`);
+        }
+        values.add(option.value);
+        // Identity is optional, but a duplicated one is always a copy-paste
+        // bug — it would make two options indistinguishable to the diff.
+        if (option.universalIdentifier) {
+            if (identifiers.has(option.universalIdentifier)) {
+                throw new Error(`defineField: ${def.type} field "${def.name}" reuses option universalIdentifier "${option.universalIdentifier}" — each option needs its own.`);
+            }
+            identifiers.add(option.universalIdentifier);
+        }
+    }
+}
+function assertRelation(def) {
+    if (def.type === "RELATION") {
+        if (!def.relationTarget) {
+            throw new Error(`defineField: RELATION field "${def.name}" requires relationTarget (the universalIdentifier of the object it points at).`);
+        }
+        return;
+    }
+    if (def.relationTarget) {
+        throw new Error(`defineField: "${def.name}" is a ${def.type} field but declares relationTarget — that belongs to RELATION fields.`);
+    }
+    if (def.onDelete) {
+        throw new Error(`defineField: "${def.name}" is a ${def.type} field but declares onDelete — that belongs to RELATION fields.`);
+    }
+}
+function internalDefineField(definition) {
+    if (!definition.universalIdentifier) {
+        throw new Error("defineCollection: universalIdentifier is required.");
+    }
+    if (!definition.name || !NAME_PATTERN.test(definition.name)) {
+        throw new Error(`defineCollection: name "${definition.name}" must be camelCase, starting with a lowercase letter.`);
+    }
+    if (!definition.label) {
+        throw new Error(`defineCollection: "${definition.name}" requires a label.`);
+    }
+    if (!isFieldType(definition.type)) {
+        throw new Error(`defineCollection: unknown field type "${definition.type}" on "${definition.name}".`);
+    }
+    if (UNSUPPORTED_FIELD_TYPES.includes(definition.type)) {
+        throw new Error(`defineCollection: field type ${definition.type} isn't supported yet (on "${definition.name}").`);
+    }
+    assertSelectOptions(definition);
+    assertRelation(definition);
+    return Object.freeze(definition);
+}
+export const objectVisibilityValues = [
+    "private",
+    "authenticated",
+    "public",
+];
+function internalDefineObject(definition) {
+    if (!definition.universalIdentifier) {
+        throw new Error("defineField: universalIdentifier is required.");
+    }
+    for (const key of ["nameSingular", "namePlural"]) {
+        const value = definition[key];
+        if (!value || !NAME_PATTERN.test(value)) {
+            throw new Error(`defineField: ${key} "${value}" must be camelCase, starting with a lowercase letter.`);
+        }
+    }
+    if (definition.nameSingular === definition.namePlural) {
+        throw new Error(`defineField: nameSingular and namePlural are both "${definition.nameSingular}" — they must differ, since routes and views derive from them.`);
+    }
+    if (!definition.labelSingular || !definition.labelPlural) {
+        throw new Error(`defineField: "${definition.nameSingular}" requires labelSingular and labelPlural.`);
+    }
+    if (definition.visibility !== undefined &&
+        !objectVisibilityValues.includes(definition.visibility)) {
+        throw new Error(`defineField: "${definition.nameSingular}" has visibility "${definition.visibility}" — must be one of ${objectVisibilityValues.join(", ")}.`);
+    }
+    const kind = definition.kind ?? "custom";
+    if (kind === "standard" && !definition.standardEntityName) {
+        throw new Error(`defineField: standard object "${definition.nameSingular}" requires standardEntityName.`);
+    }
+    if (kind === "custom" && definition.standardEntityName) {
+        throw new Error(`defineField: custom object "${definition.nameSingular}" must not set standardEntityName.`);
+    }
+    if (definition.fields.length === 0) {
+        throw new Error(`defineField: "${definition.nameSingular}" declares no fields.`);
+    }
+    const names = new Set();
+    const identifiers = new Set();
+    for (const field of definition.fields) {
+        if (names.has(field.name)) {
+            throw new Error(`defineField: duplicate field name "${field.name}" on "${definition.nameSingular}".`);
+        }
+        names.add(field.name);
+        if (identifiers.has(field.universalIdentifier)) {
+            throw new Error(`defineField: duplicate field universalIdentifier "${field.universalIdentifier}" on "${definition.nameSingular}".`);
+        }
+        identifiers.add(field.universalIdentifier);
+    }
+    if (definition.labelIdentifierFieldName &&
+        !names.has(definition.labelIdentifierFieldName)) {
+        throw new Error(`defineField: labelIdentifierFieldName "${definition.labelIdentifierFieldName}" isn't a field on "${definition.nameSingular}".`);
+    }
+    return Object.freeze({ ...definition, kind });
+}
+/**
+ * The dispatch rule both `defineCollection` and `defineField` run on: an
+ * OBJECT definition names itself and carries fields; a FIELD definition does
+ * neither. Named once as a predicate so TypeScript narrows the union instead
+ * of the implementations falling back to `any` — and so the two entry points
+ * cannot drift apart on what "is an object" means.
+ *
+ * Stays defensive about non-objects: these are public entry points and
+ * consumers pass what they pass.
+ */
+function isObjectDefinitionInput(definition) {
+    return (typeof definition === "object" &&
+        definition !== null &&
+        ("nameSingular" in definition || "fields" in definition));
+}
+export function defineCollection(definition) {
+    if (isObjectDefinitionInput(definition)) {
+        return internalDefineObject(definition);
+    }
+    return internalDefineField(definition);
+}
+export function defineField(definition) {
+    if (isObjectDefinitionInput(definition)) {
+        return internalDefineObject(definition);
+    }
+    console.warn("[@businessdash/sdk] Using defineField for column/field definitions is deprecated. Please use defineCollection for field definitions instead, and defineField (or defineCollection) for table/collection definitions.");
+    return internalDefineField(definition);
+}
+/**
+ * @deprecated Use `defineField` (or `defineCollection`) instead. `defineObject` will be removed in a future release.
+ */
+export function defineObject(definition) {
+    console.warn("[@businessdash/sdk] defineObject is deprecated. Please use defineField (or defineCollection) instead.");
+    return internalDefineObject(definition);
+}
+/**
+ * Sort keys recursively so two functionally identical models hash the same.
+ * Must mirror the server's canonicalization byte-for-byte, or every push
+ * fails the checksum check.
+ *
+ * Arrays keep their order on purpose: an option list's order is meaningful
+ * (it's the render order), so `[draft, filed]` is NOT `[filed, draft]`.
+ */
+function canonicalize(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    const out = {};
+    for (const k of Object.keys(value).sort()) {
+        if (k === "__proto__" || k === "constructor" || k === "prototype")
+            continue;
+        out[k] = canonicalize(value[k]);
+    }
+    return out;
+}
+async function sha256Hex(input) {
+    const buf = new TextEncoder().encode(input);
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", buf);
+    return Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+export async function computeDataModelChecksum(body) {
+    return sha256Hex(JSON.stringify(canonicalize(body)));
+}
+/**
+ * Declare the org's custom database schema. Default-export the result from
+ * `biab.data-model.config.ts`.
+ *
+ * ```ts
+ * export default createSchema({
+ *   collections: [
+ *     defineField({
+ *       universalIdentifier: "6f1c…",
+ *       nameSingular: "permit", namePlural: "permits",
+ *       labelSingular: "Permit", labelPlural: "Permits",
+ *       labelIdentifierFieldName: "title",
+ *       fields: [
+ *         defineCollection({ universalIdentifier: "a2b4…", name: "title", label: "Title", type: "TEXT" }),
+ *       ],
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export function createSchema(input, options = {}) {
+    const objects = input.collections ?? input.objects ?? [];
+    const metadata = input.metadata ?? {};
+    if (objects.length === 0) {
+        throw new Error("createSchema: declare at least one collection.");
+    }
+    const globalIdType = options.defaultIdType ?? "uuid";
+    // Auto-inject primary key id field for any mutable collection that doesn't define one.
+    // Frozen objects (from the old defineField/defineCollection API) are skipped — they
+    // explicitly declare all their fields.
+    for (const object of objects) {
+        if (Object.isFrozen(object))
+            continue;
+        const col = object;
+        const hasId = col.fields.some((f) => f.name === "id") ||
+            col.fields.some((f) => f.isPrimaryKey);
+        if (hasId)
+            continue;
+        const idStrategy = col.idType ?? globalIdType;
+        const idUid = generateUniversalIdentifier(`biab:collection:${object.nameSingular}:field:id`);
+        col.fields.unshift({
+            universalIdentifier: idUid,
+            name: "id",
+            label: "ID",
+            type: idStrategy === "integer" ? "NUMBER" : "UUID",
+            isPrimaryKey: true,
+            isRequired: true,
+            isNullable: false,
+            isAutoIncrement: idStrategy === "integer",
+            position: 0,
+        });
+        // Shift existing field positions
+        for (let i = 1; i < col.fields.length; i++) {
+            const f = col.fields[i];
+            if (f)
+                f.position = i;
+        }
+    }
+    // Cross-object checks. defineObject can only see itself, so uniqueness
+    // across the model and relation targets have to be settled here.
+    const byIdentifier = new Map();
+    const byName = new Map();
+    const names = new Set();
+    for (const object of objects) {
+        if (byIdentifier.has(object.universalIdentifier)) {
+            throw new Error(`defineDataModel: two objects share universalIdentifier "${object.universalIdentifier}" ("${object.nameSingular}" and "${byIdentifier.get(object.universalIdentifier)?.nameSingular}").`);
+        }
+        byIdentifier.set(object.universalIdentifier, object);
+        byName.set(object.nameSingular, object);
+        byName.set(object.namePlural, object);
+        const seen = new Set();
+        for (const name of [object.nameSingular, object.namePlural]) {
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            if (names.has(name)) {
+                throw new Error(`defineDataModel: object name "${name}" is used twice — names must be unique across the model.`);
+            }
+            names.add(name);
+        }
+    }
+    // Auto-generate junction collections for many-to-many relations
+    const generatedJunctions = [];
+    for (const object of objects) {
+        const objectWithRelations = object;
+        if (!objectWithRelations.relations)
+            continue;
+        for (const rel of objectWithRelations.relations) {
+            if (rel.meta.type !== "many-to-many")
+                continue;
+            const targetName = rel.meta.targetCollection;
+            const targetObj = byName.get(targetName);
+            if (!targetObj) {
+                throw new Error(`defineDataModel: "${object.nameSingular}.${rel.fieldName}" belongsToMany "${targetName}", which no object in this model declares.`);
+            }
+            const joinName = rel.meta.joinCollectionName ??
+                `${object.nameSingular}_${targetObj.nameSingular}`;
+            const { nameSingular: joinSingular, namePlural: joinPlural, labelSingular: joinLabelSingular, labelPlural: joinLabelPlural, } = parseTableName(joinName);
+            // Build FK fields from junction to source (left side) and target (right side)
+            const selfRelation = object.universalIdentifier === targetObj.universalIdentifier;
+            const capitalizedSource = object.nameSingular.charAt(0).toUpperCase() +
+                object.nameSingular.slice(1);
+            const sourceFkName = selfRelation
+                ? `source${capitalizedSource}Id`
+                : `${object.nameSingular}Id`;
+            const targetFkName = selfRelation
+                ? `target${capitalizedSource}Id`
+                : `${targetObj.nameSingular}Id`;
+            const junctionUid = generateUniversalIdentifier(`biab:collection:${joinSingular}`);
+            const sourceUid = generateUniversalIdentifier(`biab:collection:${joinSingular}:field:${sourceFkName}`);
+            const targetUid = generateUniversalIdentifier(`biab:collection:${joinSingular}:field:${targetFkName}`);
+            // Resolve cascade behavior: explicit onDeleteAction, then default to CASCADE
+            const junctionOnDelete = rel.meta.onDeleteAction !== undefined
+                ? (DELETE_ACTION_TO_ON_DELETE[rel.meta.onDeleteAction] ?? "cascade")
+                : "cascade";
+            // Determine id strategy for junction (use source collection's idType or global)
+            const junctionIdType = object.idType ?? globalIdType;
+            const junctionIdUid = generateUniversalIdentifier(`biab:collection:${joinSingular}:field:id`);
+            const junctionFields = [
+                {
+                    universalIdentifier: junctionIdUid,
+                    name: "id",
+                    label: "ID",
+                    type: junctionIdType === "integer" ? "NUMBER" : "UUID",
+                    isPrimaryKey: true,
+                    isRequired: true,
+                    isNullable: false,
+                    isAutoIncrement: junctionIdType === "integer",
+                    position: 0,
+                },
+                {
+                    universalIdentifier: sourceUid,
+                    name: sourceFkName,
+                    label: toLabel(sourceFkName),
+                    type: "RELATION",
+                    relationTarget: object.universalIdentifier,
+                    onDelete: junctionOnDelete,
+                    isNullable: false,
+                    recommendedFormElements: ["collection_select"],
+                    position: 1,
+                },
+                {
+                    universalIdentifier: targetUid,
+                    name: targetFkName,
+                    label: toLabel(targetFkName),
+                    type: "RELATION",
+                    relationTarget: targetObj.universalIdentifier,
+                    onDelete: junctionOnDelete,
+                    isNullable: false,
+                    recommendedFormElements: ["collection_select"],
+                    position: 2,
+                },
+            ];
+            // Add any additional fields
+            if (rel.meta.fields) {
+                let pos = 3;
+                for (const [addName, addBuilder] of Object.entries(rel.meta.fields)) {
+                    const addDef = addBuilder.build();
+                    junctionFields.push({
+                        ...addDef,
+                        universalIdentifier: generateUniversalIdentifier(`biab:collection:${joinSingular}:field:${addName}`),
+                        name: addName,
+                        label: toLabel(addName),
+                        position: pos,
+                    });
+                    pos++;
+                }
+            }
+            const junctionObj = {
+                universalIdentifier: junctionUid,
+                kind: "custom",
+                nameSingular: joinSingular,
+                namePlural: joinPlural,
+                labelSingular: joinLabelSingular,
+                labelPlural: joinLabelPlural,
+                labelIdentifierFieldName: sourceFkName,
+                fields: junctionFields,
+            };
+            generatedJunctions.push(junctionObj);
+            byIdentifier.set(junctionUid, junctionObj);
+            byName.set(joinSingular, junctionObj);
+            byName.set(joinPlural, junctionObj);
+            names.add(joinSingular);
+            names.add(joinPlural);
+        }
+    }
+    // Append generated junction collections to the objects list
+    objects.push(...generatedJunctions);
+    // Resolve relation targets by collection name (allowing name-based references)
+    for (const object of objects) {
+        for (const field of object.fields) {
+            if (field.type !== "RELATION" || !field.relationTarget)
+                continue;
+            if (!byIdentifier.has(field.relationTarget) &&
+                byName.has(field.relationTarget)) {
+                field.relationTarget = byName.get(field.relationTarget).universalIdentifier;
+            }
+        }
+    }
+    // A relation pointing at an object that isn't in the model can never be
+    // resolved. Catch it here rather than as a server-side NOT_FOUND.
+    for (const object of objects) {
+        for (const field of object.fields) {
+            if (field.type !== "RELATION" || !field.relationTarget)
+                continue;
+            if (!byIdentifier.has(field.relationTarget)) {
+                throw new Error(`defineDataModel: "${object.nameSingular}.${field.name}" points at "${field.relationTarget}", which no object in this model declares.`);
+            }
+        }
+    }
+    // Validate form element compatibility
+    for (const object of objects) {
+        if (Object.isFrozen(object))
+            continue;
+        for (const field of object.fields) {
+            if (!field.formElement)
+                continue;
+            const isValid = isValidFormElement(field.type, field.formElement);
+            if (!isValid) {
+                const recommended = getRecommendedFormElements(field.type);
+                console.warn(`[BusinessDash SDK] Form element mismatch in "${object.nameSingular}.${field.name}": ` +
+                    `"${field.formElement}" does not fulfill field type "${field.type}". ` +
+                    (recommended.length > 0
+                        ? `Recommended: [${recommended.join(", ")}]`
+                        : "No compatible elements for this field type."));
+            }
+        }
+    }
+    // Compile-time validation rule checks
+    for (const object of objects) {
+        if (Object.isFrozen(object))
+            continue;
+        for (const field of object.fields) {
+            const rules = field.validation;
+            if (!rules)
+                continue;
+            const name = `"${object.nameSingular}.${field.name}"`;
+            // Numerical type gating
+            const isNumeric = field.type === "NUMBER" || field.type === "NUMERIC";
+            const isTextOrArray = field.type === "TEXT" || field.type === "ARRAY";
+            // minLength / maxLength only on TEXT or ARRAY
+            if ((rules.minLength !== undefined || rules.maxLength !== undefined) &&
+                !isTextOrArray) {
+                throw new Error(`[BusinessDash SDK] Validation error on ${name}: "minLength" and "maxLength" are only applicable to TEXT or ARRAY, not "${field.type}".`);
+            }
+            if ((rules.minLength !== undefined && rules.minLength < 0) ||
+                (rules.maxLength !== undefined && rules.maxLength < 0)) {
+                throw new Error(`[BusinessDash SDK] Validation error on ${name}: "minLength" and "maxLength" must be positive integers.`);
+            }
+            if (rules.minLength !== undefined &&
+                rules.maxLength !== undefined &&
+                rules.minLength > rules.maxLength) {
+                throw new Error(`[BusinessDash SDK] Validation error on ${name}: "minLength" (${rules.minLength}) cannot exceed "maxLength" (${rules.maxLength}).`);
+            }
+            // Numeric boundary checks
+            if (rules.lessThan !== undefined &&
+                rules.greaterThan !== undefined &&
+                rules.greaterThan >= rules.lessThan) {
+                throw new Error(`[BusinessDash SDK] Validation error on ${name}: "greaterThan" (${rules.greaterThan}) must be strictly less than "lessThan" (${rules.lessThan}).`);
+            }
+            // Math rules gated to numeric fields
+            if ((rules.floor ||
+                rules.isDecimal ||
+                rules.round !== undefined ||
+                rules.positive) &&
+                !isNumeric) {
+                throw new Error(`[BusinessDash SDK] Validation error on ${name}: "floor", "isDecimal", "round", and "positive" are only applicable to NUMBER/NUMERIC, not "${field.type}".`);
+            }
+            // round must be non-negative integer
+            if (rules.round !== undefined &&
+                (rules.round < 0 || !Number.isInteger(rules.round))) {
+                throw new Error(`[BusinessDash SDK] Validation error on ${name}: "round" must be a non-negative whole integer (0, 1, 2, ...).`);
+            }
+            // floor and round conflict
+            if (rules.floor && rules.round !== undefined) {
+                throw new Error(`[BusinessDash SDK] Validation error on ${name}: "floor" and "round" cannot be applied together.`);
+            }
+            // floor/round with isDecimal conflict
+            if ((rules.floor || rules.round !== undefined) && rules.isDecimal) {
+                throw new Error(`[BusinessDash SDK] Validation error on ${name}: "floor" or "round" returns whole integers, neutralizing "isDecimal".`);
+            }
+            // Date conflict checks
+            if (rules.lessThanToday && rules.greaterThanToday) {
+                throw new Error(`[BusinessDash SDK] Validation error on ${name}: cannot be both "lessThanToday" and "greaterThanToday".`);
+            }
+        }
+    }
+    let cached = null;
+    function build() {
+        if (cached)
+            return cached;
+        const out = {
+            $schema: "https://biab.app/schemas/data-model/v1",
+            version: 1,
+            metadata: { ...metadata },
+            objects: objects.map((object) => ({
+                universalIdentifier: object.universalIdentifier,
+                kind: object.kind ?? "custom",
+                nameSingular: object.nameSingular,
+                namePlural: object.namePlural,
+                labelSingular: object.labelSingular,
+                labelPlural: object.labelPlural,
+                // ⚠️ Omitted when private — including when someone wrote
+                // `visibility: 'private'` by hand. Absent and private are the same
+                // model, so they must produce the same bytes.
+                //
+                // This is a checksum constraint, not a style choice. The CLI hashes
+                // the artifact and the server recomputes it against a pinned golden
+                // digest. Materializing this key would put `visibility` into EVERY
+                // object of EVERY existing config and change every checksum that has
+                // ever been computed — for a field nobody set.
+                ...(object.visibility !== undefined && object.visibility !== "private"
+                    ? { visibility: object.visibility }
+                    : {}),
+                ...(object.icon !== undefined ? { icon: object.icon } : {}),
+                ...(object.description !== undefined
+                    ? { description: object.description }
+                    : {}),
+                ...(object.labelIdentifierFieldName !== undefined
+                    ? { labelIdentifierFieldName: object.labelIdentifierFieldName }
+                    : {}),
+                ...(object.standardEntityName !== undefined
+                    ? { standardEntityName: object.standardEntityName }
+                    : {}),
+                fields: object.fields.map((field) => ({
+                    universalIdentifier: field.universalIdentifier,
+                    name: field.name,
+                    label: field.label,
+                    type: field.type,
+                    ...(field.icon !== undefined ? { icon: field.icon } : {}),
+                    ...(field.description !== undefined
+                        ? { description: field.description }
+                        : {}),
+                    ...(field.isNullable !== undefined
+                        ? { isNullable: field.isNullable }
+                        : {}),
+                    ...(field.isUnique !== undefined ? { isUnique: field.isUnique } : {}),
+                    ...(field.isIndexed !== undefined
+                        ? { isIndexed: field.isIndexed }
+                        : {}),
+                    ...(field.isPrimaryKey !== undefined
+                        ? { isPrimaryKey: field.isPrimaryKey }
+                        : {}),
+                    ...(field.isAutoIncrement !== undefined
+                        ? { isAutoIncrement: field.isAutoIncrement }
+                        : {}),
+                    ...(field.defaultValue !== undefined
+                        ? { defaultValue: field.defaultValue }
+                        : {}),
+                    ...(field.position !== undefined ? { position: field.position } : {}),
+                    ...(field.options !== undefined ? { options: field.options } : {}),
+                    ...(field.relationTarget !== undefined
+                        ? { relationTarget: field.relationTarget }
+                        : {}),
+                    ...(field.onDelete !== undefined ? { onDelete: field.onDelete } : {}),
+                    ...(field.strategy !== undefined ? { strategy: field.strategy } : {}),
+                    ...(field.separateTableName !== undefined
+                        ? { separateTableName: field.separateTableName }
+                        : {}),
+                    ...(field.formElement !== undefined
+                        ? { formElement: field.formElement }
+                        : {}),
+                    ...(field.elementMetadata !== undefined
+                        ? { elementMetadata: field.elementMetadata }
+                        : {}),
+                    ...(field.recommendedFormElements !== undefined
+                        ? { recommendedFormElements: field.recommendedFormElements }
+                        : {}),
+                    ...(field.validation !== undefined
+                        ? { validation: field.validation }
+                        : {}),
+                    ...(field.helperText !== undefined
+                        ? { helperText: field.helperText }
+                        : {}),
+                    ...(field.dynamicOptions !== undefined
+                        ? { dynamicOptions: field.dynamicOptions }
+                        : {}),
+                })),
+            })),
+        };
+        cached = out;
+        return out;
+    }
+    return {
+        objects: objects.map((o) => Object.freeze(o)),
+        toJSONSchema: build,
+        async checksum() {
+            return computeDataModelChecksum(build());
+        },
+    };
+}
+/**
+ * @deprecated Use `createSchema` instead. `defineDataModel` will be removed in a future release.
+ */
+export function defineDataModel(input) {
+    console.warn("[@businessdash/sdk] defineDataModel is deprecated. Please use createSchema instead.");
+    return createSchema(input);
+}
+/**
+ * Group collections (and nested boundaries) under a named feature.
+ * The orchestrator flattens these when building the schema graph.
+ *
+ * ```ts
+ * SchemaBoundary(
+ *   { featureId: "crm", name: "CRM", description: "Contact management" },
+ *   collection("contacts", { fields: { name: fields.text() } }),
+ * )
+ * ```
+ */
+export function SchemaBoundary(meta, ...children) {
+    return { type: "schema_boundary", meta, children };
+}
+/**
+ * @deprecated Use `layoutContainers` instead. This API will be removed in a future release.
+ */
+export const layout = {
+    step: (name, children, options) => ({
+        type: "step_group",
+        name,
+        ...(options?.helperText !== undefined
+            ? { helperText: options.helperText }
+            : {}),
+        children,
+    }),
+    collection: (collectionId, options) => ({
+        type: "render_collection",
+        collectionId,
+        ...(options?.helperText !== undefined
+            ? { helperText: options.helperText }
+            : {}),
+    }),
+    conditional: (fieldReference, condition, values, rules, children, options) => ({
+        type: "conditional_group",
+        fieldReference,
+        condition,
+        values,
+        rules,
+        ...(options?.helperText !== undefined
+            ? { helperText: options.helperText }
+            : {}),
+        children,
+    }),
+    or: (options, containerOptions) => ({
+        type: "or_group",
+        options,
+        ...(containerOptions?.helperText !== undefined
+            ? { helperText: containerOptions.helperText }
+            : {}),
+        ...(containerOptions?.button_label !== undefined
+            ? { button_label: containerOptions.button_label }
+            : {}),
+    }),
+    multiPopulator: (collectionId, options) => ({
+        type: "multi_populator",
+        collectionId,
+        ...(options?.max_entries !== undefined
+            ? { max_entries: options.max_entries }
+            : {}),
+        ...(options?.button_label !== undefined
+            ? { button_label: options.button_label }
+            : {}),
+        ...(options?.helperText !== undefined
+            ? { helperText: options.helperText }
+            : {}),
+    }),
+};
+function createFormStepNode(name, options = {}, ...children) {
+    return {
+        type: "form_step",
+        name,
+        ...(options.showTitle !== undefined
+            ? { showTitle: options.showTitle }
+            : {}),
+        ...(options.helperText !== undefined
+            ? { helperText: options.helperText }
+            : {}),
+        children: children,
+    };
+}
+function createConditionalBlockNode(config, ...children) {
+    return {
+        type: "conditional_block",
+        matchStrategy: config.matchStrategy,
+        rules: config.rules,
+        ...(config.showTitle !== undefined ? { showTitle: config.showTitle } : {}),
+        ...(config.helperText !== undefined
+            ? { helperText: config.helperText }
+            : {}),
+        children: children,
+    };
+}
+function createMultiPopulatorNode(config = {}, ...children) {
+    const entryFields = config.entryFields
+        ? Object.entries(config.entryFields).map(([name, builder], position) => {
+            const relationMeta = getRelationMeta(builder);
+            if (relationMeta?.type === "many-to-many") {
+                throw new Error(`[BusinessDash SDK] MultiPopulator JSONB entry field "${name}" cannot use belongsToMany(). Use a secondary-table output for relational entries.`);
+            }
+            return {
+                ...builder.build(),
+                name,
+                label: toLabel(name),
+                position,
+            };
+        })
+        : undefined;
+    return {
+        type: "multi_populator",
+        ...(config.max_entries !== undefined
+            ? { max_entries: config.max_entries }
+            : {}),
+        ...(config.button_label !== undefined
+            ? { button_label: config.button_label }
+            : {}),
+        ...(config.showTitle !== undefined ? { showTitle: config.showTitle } : {}),
+        ...(config.helperText !== undefined
+            ? { helperText: config.helperText }
+            : {}),
+        ...(config.output !== undefined ? { output: config.output } : {}),
+        ...(entryFields !== undefined ? { entryFields } : {}),
+        children: children,
+    };
+}
+function createOrConditionNode(options = {}, branches = []) {
+    return {
+        type: "or_condition",
+        ...(options.showTitle !== undefined
+            ? { showTitle: options.showTitle }
+            : {}),
+        ...(options.helperText !== undefined
+            ? { helperText: options.helperText }
+            : {}),
+        ...(options.button_label !== undefined
+            ? { button_label: options.button_label }
+            : {}),
+        branches,
+    };
+}
+export const layoutContainers = {
+    FormStep: createFormStepNode,
+    ConditionalBlock: createConditionalBlockNode,
+    MultiPopulator: createMultiPopulatorNode,
+    OrCondition: createOrConditionNode,
+};
+// ── createFormSchemaOrchestrator (0.9.50+) ────────────────────────────
+function toSlug(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[^a-zA-Z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase();
+}
+/**
+ * Schema declarations use descriptive SDK element names; persisted custom
+ * forms use the renderer's compact names. Keep the translation at the
+ * artifact boundary so declarations and form storage do not leak into one
+ * another.
+ */
+function toPersistedFormElement(element) {
+    const aliases = {
+        short_text: "text",
+        long_text: "textarea",
+        dropdown: "select",
+        radio_group: "radio",
+        yes_no_toggle: "boolean",
+        yes_no_checkbox: "boolean_checkbox",
+        "multi-select": "multi_select",
+        checkbox_group: "checkbox",
+        checkbox_group_many: "checkbox",
+        choice_cards_many: "choice_cards",
+        services_selector: "service_selector",
+        services_selector_many: "service_selector",
+        phone_number: "phone",
+        phone_number_basic: "phone",
+        timePicker: "time_picker",
+        "time_picker.date": "date",
+        "time_picker.time": "time_picker",
+        time_picker_timeslot: "time_picker",
+        time_picker_datetime: "time_picker",
+        address_group: "address",
+        range: "slider",
+        formFileValue: "file_upload",
+    };
+    return aliases[element] ?? element;
+}
+function generateCollectionFormCandidates(objects, options) {
+    // Indexed by BOTH universalIdentifier and nameSingular: `relationTarget` is
+    // written by the author as a collection name and is only resolved to a uid
+    // later in the pipeline. Looking up by uid alone silently found nothing, so a
+    // relation rendered as a picker with no collection wired to it.
+    const objectByIdentifier = new Map();
+    for (const object of objects) {
+        objectByIdentifier.set(object.universalIdentifier, object);
+        objectByIdentifier.set(object.nameSingular, object);
+    }
+    return objects.flatMap((object) => {
+        const fieldMap = {};
+        const formFields = [];
+        for (const field of object.fields) {
+            if (field.isPrimaryKey || field.isAutoIncrement || field.isPrivate)
+                continue;
+            const declaredElement = field.formElement ?? field.recommendedFormElements?.[0];
+            if (!declaredElement)
+                continue;
+            const type = toPersistedFormElement(declaredElement);
+            const id = generateUniversalIdentifier(`biab:generated-form:${object.universalIdentifier}:field:${field.universalIdentifier}`);
+            fieldMap[field.name] = id;
+            const relationTarget = field.relationTarget
+                ? objectByIdentifier.get(field.relationTarget)
+                : undefined;
+            const regex = field.validation?.regex;
+            const min = field.validation?.minLength ??
+                (field.validation?.greaterThan !== undefined
+                    ? field.validation.greaterThan
+                    : undefined);
+            const max = field.validation?.maxLength ??
+                (field.validation?.lessThan !== undefined
+                    ? field.validation.lessThan
+                    : undefined);
+            formFields.push({
+                id,
+                label: field.label,
+                type,
+                required: field.isRequired === true || field.isNullable === false,
+                outputKey: field.name,
+                ...(field.options
+                    ? { options: field.options.map((option) => option.value) }
+                    : {}),
+                ...(typeof field.defaultValue === "string" ||
+                    typeof field.defaultValue === "boolean"
+                    ? { defaultValue: field.defaultValue }
+                    : {}),
+                ...(field.helperText ? { helpText: field.helperText } : {}),
+                ...(regex
+                    ? {
+                        regexPattern: typeof regex === "string" ? regex : regex.source,
+                    }
+                    : {}),
+                ...(min !== undefined || max !== undefined
+                    ? {
+                        validation: {
+                            ...(min !== undefined ? { min } : {}),
+                            ...(max !== undefined ? { max } : {}),
+                        },
+                    }
+                    : {}),
+                ...(type === "collection_select" && relationTarget
+                    ? {
+                        collectionSelectConfig: {
+                            collectionKey: relationTarget.universalIdentifier,
+                            ...(relationTarget.labelIdentifierFieldName
+                                ? { labelField: relationTarget.labelIdentifierFieldName }
+                                : {}),
+                            valueMode: "id",
+                            // The relation's cardinality decides the picker, so an author
+                            // never configures "multi" — declaring that a record can
+                            // reference several of something IS the declaration that the
+                            // picker takes several. The join table stays invisible.
+                            ...(field.relationCardinality === "many"
+                                ? { multi: true }
+                                : {}),
+                        },
+                    }
+                    : {}),
+            });
+        }
+        if (formFields.length === 0)
+            return [];
+        const sourceKey = `data-model:${object.universalIdentifier}`;
+        return [
+            {
+                sourceKey,
+                name: `${object.labelSingular} Form`,
+                slug: `${toSlug(object.nameSingular)}-form`,
+                description: object.description ??
+                    `Create one ${object.labelSingular.toLowerCase()} record.`,
+                fields: formFields,
+                settings: {
+                    isConsecutive: options.consecutive ?? false,
+                    showProgress: options.progress ?? options.consecutive ?? false,
+                    ...(options.progress_style
+                        ? {
+                            progressStyle: options.progress_style === "progress_bar"
+                                ? "bar"
+                                : "steps",
+                        }
+                        : {}),
+                    generatedFrom: {
+                        kind: "data_model",
+                        sourceKey,
+                        objectIdentifier: object.universalIdentifier,
+                        objectIdentifiers: [object.universalIdentifier],
+                    },
+                    actions: [
+                        {
+                            id: generateUniversalIdentifier(`biab:generated-form:${object.universalIdentifier}:action:create-record`),
+                            type: "create_records",
+                            enabled: true,
+                            mapping: {},
+                            config: {
+                                composite: {
+                                    creates: [
+                                        {
+                                            alias: object.nameSingular,
+                                            object: object.universalIdentifier,
+                                            fieldMap,
+                                        },
+                                    ],
+                                },
+                            },
+                        },
+                    ],
+                },
+            },
+        ];
+    });
+}
+/** A record picker for one collection — "which row are we acting on?". */
+function recordIdentityField(object, purpose) {
+    return {
+        id: generateUniversalIdentifier(`biab:generated-form:${object.universalIdentifier}:${purpose}:record`),
+        label: object.labelSingular,
+        type: "collection_select",
+        required: true,
+        outputKey: "recordId",
+        helpText: `Which ${object.labelSingular.toLowerCase()} to ${purpose}.`,
+        collectionSelectConfig: {
+            collectionKey: object.universalIdentifier,
+            ...(object.labelIdentifierFieldName
+                ? { labelField: object.labelIdentifierFieldName }
+                : {}),
+            valueMode: "id",
+        },
+    };
+}
+/**
+ * What deleting one record of this collection would take with it.
+ *
+ * Read from the relations that actually point AT this collection and their
+ * declared `onDelete`, rather than asserting a generic "respects referential
+ * integrity" — which would be a promise the model may not keep.
+ */
+function describeDeleteImpact(object, related) {
+    const cascades = [];
+    const blocks = [];
+    // `relationTarget` is written by the author as a collection NAME and only
+    // resolved to a universalIdentifier later in the pipeline, so match on either
+    // — otherwise this silently finds nothing and every delete looks consequence-free.
+    const identifies = (target) => target === object.universalIdentifier || target === object.nameSingular;
+    for (const other of related) {
+        if (other.universalIdentifier === object.universalIdentifier)
+            continue;
+        for (const field of other.fields) {
+            if (!identifies(field.relationTarget))
+                continue;
+            if (field.onDelete === "cascade")
+                cascades.push(other.labelPlural);
+            else if ((field.onDelete ?? "restrict") === "restrict") {
+                blocks.push(other.labelPlural);
+            }
+        }
+    }
+    const parts = [
+        `Permanently remove this ${object.labelSingular.toLowerCase()}.`,
+    ];
+    if (cascades.length > 0) {
+        parts.push(`Linked ${[...new Set(cascades)].join(", ")} will be deleted with it.`);
+    }
+    if (blocks.length > 0) {
+        parts.push(`It can't be deleted while ${[...new Set(blocks)].join(", ")} still reference it.`);
+    }
+    return parts.join(" ");
+}
+/**
+ * Generate the three atomic, single-record forms for one collection — Create,
+ * Edit and Delete — instead of one big multi-step wizard.
+ *
+ * Relation fields become live collection pickers automatically, single or
+ * multi according to the relation's own cardinality, so a many-to-many is
+ * filled in inline and the join table never surfaces as a concept.
+ *
+ * Lineage: `create` deliberately KEEPS the base `data-model:<uid>` sourceKey
+ * that the one-form-per-collection generator has always used, so promoting a
+ * model that previously produced a single form updates that draft rather than
+ * orphaning it and creating a duplicate. `edit` and `delete` take suffixed keys
+ * off the same stem.
+ */
+export function createSingleResourceForm(object, options = {}) {
+    const { relatedObjects, ...orchestration } = options;
+    // Reuse the existing per-collection generator rather than re-deriving field
+    // mapping, element choice and picker config — one place decides how a
+    // collection becomes a form.
+    //
+    // Siblings are passed in so relation targets RESOLVE: a picker needs its
+    // target's identifier and label field, and without them in the map the field
+    // renders as a picker wired to nothing. `.filter` keeps the subject first and
+    // prevents a duplicate candidate for it.
+    const generatorInput = [
+        object,
+        ...(relatedObjects ?? []).filter((o) => o.universalIdentifier !== object.universalIdentifier),
+    ];
+    const generated = generateCollectionFormCandidates(generatorInput, orchestration);
+    const base = generated.find((c) => c.settings.generatedFrom.objectIdentifier === object.universalIdentifier);
+    if (!base) {
+        throw new Error(`createSingleResourceForm: "${object.nameSingular}" has no form-renderable fields.`);
+    }
+    const human = object.labelSingular;
+    const slugBase = toSlug(object.nameSingular);
+    const create = {
+        ...base,
+        name: `Add ${human}`,
+        description: `Create one ${human.toLowerCase()}.`,
+    };
+    // Edit reuses create's fields, prefixed by a picker for WHICH record. The
+    // record's id is identity, not an answer — it's a picker, never a text box
+    // someone can retype into a different row.
+    const editSourceKey = `${base.sourceKey}:edit`;
+    const edit = {
+        ...base,
+        sourceKey: editSourceKey,
+        name: `Edit ${human}`,
+        slug: `${slugBase}-edit`,
+        description: `Update an existing ${human.toLowerCase()}.`,
+        fields: [recordIdentityField(object, "edit"), ...base.fields],
+        settings: {
+            ...base.settings,
+            generatedFrom: {
+                ...base.settings.generatedFrom,
+                sourceKey: editSourceKey,
+            },
+        },
+    };
+    // Delete carries no data fields — a picker and a plain statement of
+    // consequences. It intentionally keeps no `create_records` action: this form
+    // removes a row, it doesn't make one.
+    const deleteSourceKey = `${base.sourceKey}:delete`;
+    const del = {
+        ...base,
+        sourceKey: deleteSourceKey,
+        name: `Delete ${human}`,
+        slug: `${slugBase}-delete`,
+        description: describeDeleteImpact(object, relatedObjects ?? []),
+        fields: [recordIdentityField(object, "delete")],
+        settings: {
+            ...base.settings,
+            generatedFrom: {
+                ...base.settings.generatedFrom,
+                sourceKey: deleteSourceKey,
+            },
+            actions: [],
+        },
+    };
+    // Relation targets, as declared. Informational — the generated pickers already
+    // carry their own `collectionKey`, so nothing consumes this to wire anything.
+    const dependencies = [
+        ...new Set(object.fields
+            .map((f) => f.relationTarget)
+            .filter((t) => typeof t === "string")),
+    ];
+    return {
+        collectionId: object.universalIdentifier,
+        create,
+        edit,
+        delete: del,
+        dependencies,
+    };
+}
+function isCollectionDefinition(node) {
+    // No casts: `typeof node === "object" && node !== null` narrows to `object`,
+    // and `in` operates on that directly.
+    return (typeof node === "object" &&
+        node !== null &&
+        !("type" in node) &&
+        "nameSingular" in node &&
+        "fields" in node);
+}
+function isSchemaBoundaryNode(node) {
+    return (typeof node === "object" &&
+        node !== null &&
+        "type" in node &&
+        node.type === "schema_boundary");
+}
+function walkTreeForCollections(boundaries, collections, featureTags, inheritedFeatureId) {
+    const layoutNodes = [];
+    for (const node of boundaries) {
+        if (isSchemaBoundaryNode(node)) {
+            const fid = node.meta.featureId;
+            const children = walkTreeForCollections(node.children, collections, featureTags, fid);
+            layoutNodes.push(...children);
+        }
+        else if (isCollectionDefinition(node)) {
+            collections.push(node);
+            if (inheritedFeatureId) {
+                featureTags[node.nameSingular] = inheritedFeatureId;
+            }
+            layoutNodes.push({
+                type: "render_collection",
+                collectionId: node.nameSingular,
+            });
+        }
+        else {
+            const layoutNode = node;
+            if (layoutNode.type === "form_step" ||
+                layoutNode.type === "conditional_block" ||
+                layoutNode.type === "multi_populator") {
+                const children = walkTreeForCollections((layoutNode.children || []), collections, featureTags, inheritedFeatureId);
+                layoutNodes.push({ ...layoutNode, children });
+            }
+            else if (layoutNode.type === "or_condition") {
+                const branches = (layoutNode.branches || []).map((branch) => ({
+                    ...branch,
+                    nodes: walkTreeForCollections(branch.nodes, collections, featureTags, inheritedFeatureId),
+                }));
+                layoutNodes.push({ ...layoutNode, branches });
+            }
+            else if (layoutNode.type === "render_collection") {
+                const col = collections.find((c) => c.nameSingular === layoutNode.collectionId);
+                if (!col && collections.length > 0) {
+                    throw new Error(`[BusinessDash SDK] Layout references unknown collection "${layoutNode.collectionId}".`);
+                }
+                layoutNodes.push(layoutNode);
+            }
+        }
+    }
+    return layoutNodes;
+}
+/**
+ * Compile a layout tree into a pure database schema + UI form tree.
+ *
+ * Unlike the previous API which required separate `collections` and `layout`
+ * properties, this new signature accepts a flat array of `SchemaBoundary`,
+ * `collection()` definitions, and layout containers — extracting collections
+ * and the visual render graph from the same expression tree.
+ *
+ * ```ts
+ * const result = createFormSchemaOrchestrator([
+ *   SchemaBoundary(
+ *     { featureId: "crm", name: "CRM" },
+ *     collection("contacts", { fields: { name: bd.text().required() } }),
+ *   ),
+ * ], { defaultIdType: "uuid", consecutive: true });
+ * ```
+ */
+export function createFormSchemaOrchestrator(boundaries, options = {}) {
+    if (!Array.isArray(boundaries)) {
+        throw new Error("[BusinessDash SDK] createFormSchemaOrchestrator: `boundaries` must be an array of SchemaBoundaryNode | CollectionDefinition | LayoutNode.");
+    }
+    const collections = [];
+    const featureTags = {};
+    const uiFormTree = walkTreeForCollections(boundaries, collections, featureTags);
+    if (collections.length === 0) {
+        throw new Error("[BusinessDash SDK] createFormSchemaOrchestrator: No collections found. Pass collection() directly, inside an optional SchemaBoundary(), or under an optional layout container.");
+    }
+    const schemaOptions = options.defaultIdType !== undefined
+        ? { defaultIdType: options.defaultIdType }
+        : {};
+    const compiledDatabaseSchema = createSchema({ collections }, schemaOptions);
+    const dbCollectionMap = new Map();
+    for (const col of compiledDatabaseSchema.objects) {
+        dbCollectionMap.set(col.nameSingular, col);
+    }
+    function renderedCollectionIds(nodes) {
+        const ids = [];
+        for (const node of nodes) {
+            if (node.type === "render_collection") {
+                ids.push(node.collectionId);
+            }
+            else if (node.type === "form_step" ||
+                node.type === "conditional_block" ||
+                node.type === "multi_populator") {
+                ids.push(...renderedCollectionIds(node.children));
+            }
+            else if (node.type === "or_condition") {
+                for (const branch of node.branches) {
+                    ids.push(...renderedCollectionIds(branch.nodes));
+                }
+            }
+        }
+        return ids;
+    }
+    function generatedLayoutForms(nodes, collectionForms) {
+        const generated = [];
+        const objectByName = new Map(compiledDatabaseSchema.objects.map((object) => [
+            object.nameSingular,
+            object,
+        ]));
+        const formByObjectIdentifier = new Map(collectionForms.map((form) => [
+            form.settings.generatedFrom.objectIdentifier,
+            form,
+        ]));
+        const walk = (candidates) => {
+            for (const node of candidates) {
+                if (node.type === "form_step") {
+                    const collectionIds = [
+                        ...new Set(renderedCollectionIds(node.children)),
+                    ];
+                    // A one-collection step is already represented by its collection
+                    // candidate. Composite steps are additional CLI choices.
+                    if (collectionIds.length > 1) {
+                        const objects = collectionIds
+                            .map((id) => objectByName.get(id))
+                            .filter((object) => object !== undefined);
+                        const identifiers = new Set(objects.map((object) => object.universalIdentifier));
+                        const aliasByIdentifier = new Map(objects.map((object) => [
+                            object.universalIdentifier,
+                            object.nameSingular,
+                        ]));
+                        const fields = [];
+                        const creates = [];
+                        for (const object of objects) {
+                            const base = formByObjectIdentifier.get(object.universalIdentifier);
+                            if (!base)
+                                continue;
+                            const fieldMap = {
+                                ...base.settings.actions[0].config.composite.creates[0]
+                                    .fieldMap,
+                            };
+                            const links = [];
+                            for (const schemaField of object.fields) {
+                                if (schemaField.type !== "RELATION" ||
+                                    !schemaField.relationTarget ||
+                                    !identifiers.has(schemaField.relationTarget)) {
+                                    continue;
+                                }
+                                delete fieldMap[schemaField.name];
+                                const targetAlias = aliasByIdentifier.get(schemaField.relationTarget);
+                                if (targetAlias) {
+                                    links.push({
+                                        field: schemaField.name,
+                                        to: `$${targetAlias}`,
+                                    });
+                                }
+                            }
+                            for (const field of base.fields) {
+                                if (!(field.outputKey in fieldMap))
+                                    continue;
+                                const outputKey = `${object.nameSingular}${field.outputKey
+                                    .charAt(0)
+                                    .toUpperCase()}${field.outputKey.slice(1)}`;
+                                fields.push({
+                                    ...field,
+                                    label: `${object.labelSingular}: ${field.label}`,
+                                    outputKey,
+                                });
+                            }
+                            creates.push({
+                                alias: object.nameSingular,
+                                object: object.universalIdentifier,
+                                fieldMap,
+                                ...(links.length > 0 ? { links } : {}),
+                            });
+                        }
+                        if (fields.length > 0 && creates.length > 1) {
+                            const sourceKey = `data-model-layout:${node.name}`;
+                            generated.push({
+                                sourceKey,
+                                name: `${toLabel(node.name)} Form`,
+                                slug: `${toSlug(node.name)}-form`,
+                                description: node.helperText ??
+                                    `Create related ${objects
+                                        .map((object) => object.labelPlural.toLowerCase())
+                                        .join(", ")} in one submission.`,
+                                fields,
+                                settings: {
+                                    isConsecutive: options.consecutive ?? false,
+                                    showProgress: options.progress ?? options.consecutive ?? false,
+                                    ...(options.progress_style
+                                        ? {
+                                            progressStyle: options.progress_style === "progress_bar"
+                                                ? "bar"
+                                                : "steps",
+                                        }
+                                        : {}),
+                                    generatedFrom: {
+                                        kind: "data_model",
+                                        sourceKey,
+                                        objectIdentifiers: objects.map((object) => object.universalIdentifier),
+                                    },
+                                    actions: [
+                                        {
+                                            id: generateUniversalIdentifier(`biab:generated-form:${sourceKey}:action:create-records`),
+                                            type: "create_records",
+                                            enabled: true,
+                                            mapping: {},
+                                            config: { composite: { creates } },
+                                        },
+                                    ],
+                                },
+                            });
+                        }
+                    }
+                    walk(node.children);
+                }
+                else if (node.type === "conditional_block" ||
+                    node.type === "multi_populator") {
+                    walk(node.children);
+                }
+                else if (node.type === "or_condition") {
+                    for (const branch of node.branches) {
+                        walk(branch.nodes);
+                    }
+                }
+            }
+        };
+        walk(nodes);
+        return generated;
+    }
+    function validateAndAlignLayout(nodes) {
+        for (const node of nodes) {
+            if (node.type === "render_collection") {
+                if (!dbCollectionMap.has(node.collectionId)) {
+                    throw new Error(`[BusinessDash SDK] Form layout references collection "${node.collectionId}" ` +
+                        "which does not exist in the declared collections block.");
+                }
+            }
+            if (node.type === "conditional_block") {
+                for (const rule of node.rules) {
+                    const parts = rule.fieldRef.split(".");
+                    if (parts.length !== 2) {
+                        throw new Error(`[BusinessDash SDK] Conditional rule fieldRef "${rule.fieldRef}" must be in "collectionName.fieldName" format.`);
+                    }
+                    const targetCollection = parts[0];
+                    const targetField = parts[1];
+                    const collectionDef = dbCollectionMap.get(targetCollection);
+                    if (!collectionDef) {
+                        throw new Error(`[BusinessDash SDK] Conditional rule references collection "${targetCollection}" in fieldRef "${rule.fieldRef}" which does not exist.`);
+                    }
+                    const field = collectionDef.fields.find((f) => f.name === targetField);
+                    if (!field) {
+                        throw new Error(`[BusinessDash SDK] Conditional rule references field "${targetField}" in collection "${targetCollection}" which does not exist.`);
+                    }
+                }
+            }
+            if (node.type === "multi_populator") {
+                if (node.max_entries !== undefined &&
+                    (!Number.isInteger(node.max_entries) || node.max_entries < 1)) {
+                    throw new Error("[BusinessDash SDK] MultiPopulator max_entries must be a positive whole number.");
+                }
+                const renderedIds = [...new Set(renderedCollectionIds(node.children))];
+                const output = node.output;
+                if (!output) {
+                    if (renderedIds.length !== 1) {
+                        throw new Error("[BusinessDash SDK] MultiPopulator without an explicit output must contain exactly one child collection so separate-table storage can be inferred.");
+                    }
+                    node.output = {
+                        strategy: "separateTable",
+                        collectionId: renderedIds[0],
+                    };
+                }
+                else if (output.strategy === "separateTable") {
+                    if (node.entryFields !== undefined) {
+                        throw new Error("[BusinessDash SDK] MultiPopulator entryFields are only valid for JSONB output. Define secondary-table fields on the target collection.");
+                    }
+                    const collectionId = output.collectionId ??
+                        (renderedIds.length === 1 ? renderedIds[0] : undefined);
+                    if (!collectionId) {
+                        throw new Error("[BusinessDash SDK] MultiPopulator separateTable output requires collectionId unless exactly one child collection can be inferred.");
+                    }
+                    if (!dbCollectionMap.has(collectionId)) {
+                        throw new Error(`[BusinessDash SDK] MultiPopulator separateTable output references collection "${collectionId}" which does not exist.`);
+                    }
+                    if (renderedIds.length > 0 && !renderedIds.includes(collectionId)) {
+                        throw new Error(`[BusinessDash SDK] MultiPopulator separateTable output targets "${collectionId}", but that collection is not rendered by the repeater.`);
+                    }
+                    node.output = { strategy: "separateTable", collectionId };
+                }
+                else {
+                    if (node.children.length > 0) {
+                        throw new Error("[BusinessDash SDK] MultiPopulator JSONB output defines its repeated shape with entryFields and cannot also contain child collections or layout nodes.");
+                    }
+                    if (!node.entryFields || node.entryFields.length === 0) {
+                        throw new Error("[BusinessDash SDK] MultiPopulator JSONB output requires at least one entryFields declaration.");
+                    }
+                    const parts = output.fieldRef.split(".");
+                    if (parts.length !== 2) {
+                        throw new Error(`[BusinessDash SDK] MultiPopulator JSONB fieldRef "${output.fieldRef}" must be in "collectionName.fieldName" format.`);
+                    }
+                    const targetCollection = parts[0];
+                    const targetField = parts[1];
+                    const collectionDef = dbCollectionMap.get(targetCollection);
+                    if (!collectionDef) {
+                        throw new Error(`[BusinessDash SDK] MultiPopulator JSONB output references collection "${targetCollection}" which does not exist.`);
+                    }
+                    const field = collectionDef.fields.find((candidate) => candidate.name === targetField);
+                    if (!field) {
+                        throw new Error(`[BusinessDash SDK] MultiPopulator JSONB output references field "${targetField}" in collection "${targetCollection}" which does not exist.`);
+                    }
+                    if (field.type !== "RAW_JSON" && field.type !== "ARRAY") {
+                        throw new Error(`[BusinessDash SDK] MultiPopulator JSONB output field "${output.fieldRef}" must use bd.json(), bd.object(), or bd.array(); received "${field.type}".`);
+                    }
+                    if (field.strategy !== "jsonb") {
+                        throw new Error(`[BusinessDash SDK] MultiPopulator JSONB output field "${output.fieldRef}" must declare .strategy("jsonb").`);
+                    }
+                }
+            }
+            if (node.type === "form_step" ||
+                node.type === "conditional_block" ||
+                node.type === "multi_populator") {
+                validateAndAlignLayout(node.children);
+            }
+            else if (node.type === "or_condition") {
+                for (const branch of node.branches) {
+                    validateAndAlignLayout(branch.nodes);
+                }
+            }
+        }
+    }
+    validateAndAlignLayout(uiFormTree);
+    const progress = options.progress ?? !!options.consecutive;
+    const progressStyle = options.progress_style ?? (progress ? "multi-step" : undefined);
+    const collectionForms = generateCollectionFormCandidates(compiledDatabaseSchema.objects, options);
+    return {
+        databaseSchema: compiledDatabaseSchema,
+        uiFormTree,
+        generatedForms: [
+            ...generatedLayoutForms(uiFormTree, collectionForms),
+            ...collectionForms,
+        ],
+        formControlSettings: {
+            consecutive: options.consecutive ?? false,
+            progress,
+            ...(progressStyle !== undefined ? { progressStyle } : {}),
+        },
+        featureTags,
+    };
+}
+//# sourceMappingURL=data-model-schema.js.map