@businessdash/sdk 0.9.60

package/src/data-model-schema.ts

@@ -0,0 +1,4042 @@
+/**
+ * `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.
+ */
+
+// ── Field types ──────────────────────────────────────────────────────
+
+/**
+ * Value kinds a field can hold. Mirrors the platform's FieldType catalog.
+ * Not every entry is accepted by the push endpoint yet — see
+ * `UNSUPPORTED_FIELD_TYPES`.
+ */
+import type { EnumEntry } from "./enums.js";
+
+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",
+] as const;
+
+export type FieldType = (typeof FIELD_TYPES)[number];
+
+export function isFieldType(value: string): value is FieldType {
+	return (FIELD_TYPES as readonly string[]).includes(value);
+}
+
+// ── Fields Builder API ──────────────────────────────────────────────────
+
+/** Common field options that can be chained. */
+export interface FieldOptions {
+	required?: boolean;
+	nullable?: boolean;
+	defaultValue?: unknown;
+	indexed?: boolean;
+	unique?: boolean;
+	description?: string;
+}
+
+/** Relation metadata for relationship descriptors. */
+export interface RelationMetadata {
+	type: "one-to-many" | "many-to-many";
+	targetCollection: string;
+	joinCollectionName?: string;
+	fields?: Record<string, AnyFieldBuilder>;
+	onDeleteAction?: DeleteAction;
+}
+
+/** Builder for a single field definition. */
+export interface FieldBuilder<
+	T extends FieldType = FieldType,
+	TValue = InferJsType<T>,
+	TRequired extends boolean = false,
+	TNullable extends boolean = true,
+> {
+	readonly __valueType?: TValue;
+	readonly __requiredType?: TRequired;
+	readonly __nullableType?: TNullable;
+	required: () => FieldBuilder<T, TValue, true, false>;
+	optional: () => FieldBuilder<T, TValue, false, true>;
+	nullable: <TNextNullable extends boolean = true>(
+		value?: TNextNullable,
+	) => FieldBuilder<T, TValue, TRequired, TNextNullable>;
+	default: (value: unknown) => FieldBuilder<T, TValue, TRequired, TNullable>;
+	indexed: (value?: boolean) => FieldBuilder<T, TValue, TRequired, TNullable>;
+	unique: (value?: boolean) => FieldBuilder<T, TValue, TRequired, TNullable>;
+	description: (text: string) => FieldBuilder<T, TValue, TRequired, TNullable>;
+	helper: (text: string) => FieldBuilder<T, TValue, TRequired, TNullable>;
+	formElement: (
+		element: AllFormElements,
+		metadata?: ElementMetadata,
+	) => FieldBuilder<T, TValue, TRequired, TNullable>;
+	validate: (
+		rules: ValidationRules,
+	) => FieldBuilder<T, TValue, TRequired, TNullable>;
+	dynamicOptions: (
+		config: DynamicOptionsDef,
+	) => FieldBuilder<T, TValue, TRequired, TNullable>;
+	requiredIf: (
+		condition: RequiredIfCondition,
+	) => FieldBuilder<T, TValue, false, TNullable>;
+	regex: (
+		pattern: RegExp | string,
+	) => FieldBuilder<T, TValue, TRequired, TNullable>;
+	check: (
+		sqlExpression: string,
+	) => FieldBuilder<T, TValue, TRequired, TNullable>;
+	strategy: (
+		mode: StorageStrategy,
+		separateTableName?: string,
+	) => FieldBuilder<T, TValue, TRequired, TNullable>;
+	encrypted: () => FieldBuilder<T, TValue, TRequired, TNullable>;
+	encryptedLight: () => FieldBuilder<T, TValue, TRequired, TNullable>;
+	private: () => FieldBuilder<T, TValue, TRequired, TNullable>;
+	references: (
+		targetCollection: string,
+		onDelete?: "restrict" | "setNull" | "cascade",
+	) => FieldBuilder<"RELATION", string, TRequired, TNullable>;
+	/**
+	 * This record may reference SEVERAL of `targetCollection`.
+	 *
+	 * That's the whole declaration — there is no join table to name, design, or
+	 * maintain. BIAB stores every link in one universal link table, so "many"
+	 * is a property of the relation rather than a second collection the author
+	 * has to invent and keep in step.
+	 *
+	 * `fields` optionally declares values that belong to the PAIRING rather than
+	 * to either side ("this technology, at expert level").
+	 *
+	 * `joinCollectionName` is accepted for backwards compatibility and ignored;
+	 * nothing has ever read it.
+	 */
+	belongsToMany: (
+		targetCollection: string,
+		options?: {
+			/** @deprecated Ignored — BIAB has no per-pair join table to name. */
+			joinCollectionName?: string;
+			fields?: Record<string, AnyFieldBuilder>;
+		},
+	) => FieldBuilder<"RELATION", string[], TRequired, TNullable>;
+	onDelete: (
+		action: DeleteAction,
+	) => FieldBuilder<T, TValue, TRequired, TNullable>;
+	build: () => FieldDefinition;
+}
+
+export type AnyFieldBuilder = FieldBuilder<
+	FieldType,
+	unknown,
+	boolean,
+	boolean
+>;
+
+type RequiredFromOptions<O> = O extends { required: true } ? true : false;
+
+type NullableFromOptions<O> = O extends { nullable: infer N extends boolean }
+	? N
+	: O extends { required: true }
+		? false
+		: true;
+
+type EnumValue<T> = T extends { values: readonly (infer V extends string)[] }
+	? V
+	: T extends readonly (infer Entry)[]
+		? Entry extends string
+			? Entry
+			: Entry extends { value: infer V extends string }
+				? V
+				: never
+		: string;
+
+/** Runtime value stored by a measurement field. */
+export interface MeasurementValue {
+	value: number;
+	unit: string;
+}
+
+/** A field builder whose required and nullable flags were supplied as options. */
+export type ConfiguredFieldBuilder<
+	T extends FieldType,
+	TValue,
+	O extends FieldOptions | undefined,
+> = FieldBuilder<T, TValue, RequiredFromOptions<O>, NullableFromOptions<O>>;
+
+/** Infer the submitted/runtime value represented by a single field builder. */
+export type InferFieldValue<B> =
+	B extends FieldBuilder<
+		infer _T,
+		infer TValue,
+		infer _TRequired,
+		infer TNullable
+	>
+		? true extends TNullable
+			? TValue | null
+			: TValue
+		: never;
+
+type RequiredFieldKeys<F extends Record<string, AnyFieldBuilder>> = {
+	[K in keyof F]-?: F[K] extends FieldBuilder<
+		infer _T,
+		infer _TValue,
+		infer TRequired,
+		infer _TNullable
+	>
+		? TRequired extends true
+			? K
+			: never
+		: never;
+}[keyof F];
+
+type OptionalFieldKeys<F extends Record<string, AnyFieldBuilder>> = Exclude<
+	keyof F,
+	RequiredFieldKeys<F>
+>;
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+/** Infer an object value type from a map of BIAB field declarations. */
+export type InferFieldsValues<F extends Record<string, AnyFieldBuilder>> =
+	Simplify<
+		{
+			[K in RequiredFieldKeys<F>]: InferFieldValue<F[K]>;
+		} & {
+			[K in OptionalFieldKeys<F>]?: InferFieldValue<F[K]> | undefined;
+		}
+	>;
+
+/** Result of calling a fields method (e.g., fields.text()) */
+export interface FieldSpec extends FieldDefinition {}
+
+/** The fields namespace object — entry point for the fluent field API. */
+export interface Fields {
+	text: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"TEXT", string, O>;
+	number: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"NUMBER", number, O>;
+	numeric: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"NUMERIC", number, O>;
+	boolean: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"BOOLEAN", boolean, O>;
+	date: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"DATE", string, O>;
+	dateTime: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"DATE_TIME", string, O>;
+	uuid: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"UUID", string, O>;
+	enum: <
+		const T extends
+			| readonly (string | { value: string; label?: string })[]
+			| { values: readonly string[]; entries: EnumEntry[] },
+		O extends FieldOptions | undefined = undefined,
+	>(
+		values: T,
+		options?: O,
+	) => ConfiguredFieldBuilder<"SELECT", EnumValue<T>, O>;
+	multiEnum: <
+		const T extends
+			| readonly (string | { value: string; label?: string })[]
+			| { values: readonly string[]; entries: EnumEntry[] },
+		O extends FieldOptions | undefined = undefined,
+	>(
+		values: T,
+		options?: O,
+	) => ConfiguredFieldBuilder<"MULTI_SELECT", EnumValue<T>[], O>;
+	reference: <
+		O extends
+			| (FieldOptions & {
+					onDelete?: "restrict" | "setNull" | "cascade";
+			  })
+			| undefined = undefined,
+	>(
+		targetCollection: string,
+		options?: O,
+	) => ConfiguredFieldBuilder<"RELATION", string, O>;
+	relation: () => FieldBuilder<"RELATION", string>;
+	url: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"TEXT", string, O>;
+	email: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"EMAILS", string, O>;
+	phone: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"PHONES", string, O>;
+	richText: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"RICH_TEXT", string, O>;
+	json: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"RAW_JSON", unknown, O>;
+	array: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"ARRAY", unknown[], O>;
+	measurement: <O extends FieldOptions | undefined = undefined>(
+		config: MeasurementDef,
+		options?: O,
+	) => ConfiguredFieldBuilder<"RAW_JSON", MeasurementValue, O>;
+	object: <
+		F extends Record<string, AnyFieldBuilder>,
+		O extends FieldOptions | undefined = undefined,
+	>(
+		config: { properties: F } | F,
+		options?: O,
+	) => ConfiguredFieldBuilder<"RAW_JSON", InferFieldsValues<F>, O>;
+	file: <O extends FieldOptions | undefined = undefined>(
+		config?: FileDef,
+		options?: O,
+	) => ConfiguredFieldBuilder<"FILES", unknown[], O>;
+	address: <O extends FieldOptions | undefined = undefined>(
+		config?: AddressDef,
+		options?: O,
+	) => ConfiguredFieldBuilder<"RAW_JSON", Record<string, unknown>, O>;
+	geo: <O extends FieldOptions | undefined = undefined>(
+		options?: O,
+	) => ConfiguredFieldBuilder<"RAW_JSON", Record<string, unknown>, O>;
+}
+
+/** Internal builder state */
+interface BuilderState extends FieldOptions {
+	type: FieldType | "__relation__";
+	options?: SelectOption[];
+	relationTarget?: string;
+	onDelete?: RelationOnDelete;
+	relationMeta?: RelationMetadata;
+	relationCardinality?: "one" | "many";
+	linkAttributes?: LinkAttributeDefinition[];
+	formElement?: AllFormElements;
+	elementMetadata?: ElementMetadata;
+	validation?: ValidationRules;
+	helperText?: string;
+	dynamicOptions?: DynamicOptionsDef;
+	strategy?: StorageStrategy;
+	separateTableName?: string;
+	encryption?: EncryptionMode;
+	isPrivate?: boolean;
+}
+
+/** Runtime implementation shape; public builder generics are compile-time only. */
+interface RuntimeFieldBuilder {
+	__relationMeta?: RelationMetadata;
+	required(): RuntimeFieldBuilder;
+	optional(): RuntimeFieldBuilder;
+	nullable(value?: boolean): RuntimeFieldBuilder;
+	default(value: unknown): RuntimeFieldBuilder;
+	indexed(value?: boolean): RuntimeFieldBuilder;
+	unique(value?: boolean): RuntimeFieldBuilder;
+	description(text: string): RuntimeFieldBuilder;
+	helper(text: string): RuntimeFieldBuilder;
+	formElement(
+		element: AllFormElements,
+		metadata?: ElementMetadata,
+	): RuntimeFieldBuilder;
+	validate(rules: ValidationRules): RuntimeFieldBuilder;
+	dynamicOptions(config: DynamicOptionsDef): RuntimeFieldBuilder;
+	requiredIf(condition: RequiredIfCondition): RuntimeFieldBuilder;
+	regex(pattern: RegExp | string): RuntimeFieldBuilder;
+	check(sqlExpression: string): RuntimeFieldBuilder;
+	strategy(
+		mode: StorageStrategy,
+		separateTableName?: string,
+	): RuntimeFieldBuilder;
+	encrypted(): RuntimeFieldBuilder;
+	encryptedLight(): RuntimeFieldBuilder;
+	private(): RuntimeFieldBuilder;
+	references(
+		targetCollection: string,
+		onDelete?: "restrict" | "setNull" | "cascade",
+	): RuntimeFieldBuilder;
+	belongsToMany(
+		targetCollection: string,
+		options: {
+			joinCollectionName: string;
+			fields?: Record<string, AnyFieldBuilder>;
+		},
+	): RuntimeFieldBuilder;
+	onDelete(action: DeleteAction): RuntimeFieldBuilder;
+	build(): FieldDefinition;
+}
+
+/** Create a field builder with chainable methods. */
+function createFieldBuilder<TBuilder = AnyFieldBuilder>(
+	initialState: BuilderState,
+): TBuilder {
+	const state: BuilderState = { ...initialState };
+
+	const builder: RuntimeFieldBuilder = {
+		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 as ObjectSchemaDef | undefined;
+			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 as unknown as TBuilder;
+}
+
+/** Extract relation metadata from a builder (used by collection()). */
+function getRelationMeta(
+	builder: AnyFieldBuilder,
+): RelationMetadata | undefined {
+	return (
+		builder as unknown as { __relationMeta: RelationMetadata | undefined }
+	).__relationMeta;
+}
+
+/** Convert snake_case or camelCase to Title Case for labels. */
+function toLabel(text: string): string {
+	// 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?: string): string {
+	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:
+		| readonly (string | { value: string; label?: string })[]
+		| { values: readonly string[]; entries: EnumEntry[] },
+): SelectOption[] {
+	// Handle both raw arrays and Enums() return objects
+	const arr = Array.isArray(values)
+		? values
+		: (values as { entries: (string | { value: string; label?: string })[] })
+				.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: Record<string, AnyFieldBuilder> | undefined,
+): LinkAttributeDefinition[] | undefined {
+	if (!fields) return undefined;
+	const out: LinkAttributeDefinition[] = [];
+	for (const [name, builder] of Object.entries(fields)) {
+		const built = builder.build();
+		const type: LinkAttributeDefinition["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: BuilderState): FieldDefinition {
+	const universalIdentifier = generateUniversalIdentifier();
+
+	const recommendedFormElements = isFieldType(state.type)
+		? getRecommendedFormElements(state.type)
+		: [];
+
+	const fieldDef: FieldDefinition = {
+		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: 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: ObjectPropertyDef[] = 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 = fields;
+
+/** Convert a table name to singular/plural names and labels. */
+function parseTableName(tableName: string): {
+	nameSingular: string;
+	namePlural: string;
+	labelSingular: string;
+	labelPlural: string;
+	labelIdentifierFieldName: string;
+} {
+	// 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: string) =>
+		str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
+
+	return {
+		nameSingular: toCamelCase(singularForLabel),
+		namePlural: toCamelCase(pluralForLabel),
+		labelSingular: toLabel(singularForLabel),
+		labelPlural: toLabel(pluralForLabel),
+		labelIdentifierFieldName: toCamelCase(singularForLabel),
+	};
+}
+
+/** Collection definition options */
+export interface CollectionOptions<
+	F extends Record<string, AnyFieldBuilder> = Record<string, AnyFieldBuilder>,
+> {
+	fields: F;
+	description?: string;
+	icon?: string;
+	visibility?: "private" | "authenticated" | "public";
+	labelIdentifierFieldName?: string;
+	/**
+	 * Stable identity override. Usually unnecessary because collection()
+	 * derives a deterministic UUID from tableName.
+	 */
+	universalIdentifier?: string;
+	/** Override the primary key strategy for this collection. */
+	idType?: PrimaryKeyType;
+	/** Row-level security policies for this collection. */
+	rlsPolicies?: RlsPolicyConfig[];
+}
+
+/** Collection definition returned by collection(). */
+export interface CollectionDefinition<
+	F extends Record<string, AnyFieldBuilder> = Record<string, AnyFieldBuilder>,
+> extends ObjectDefinition {
+	fields: FieldDefinition[];
+	relations?: Array<{
+		fieldName: string;
+		meta: RelationMetadata;
+	}>;
+	/** Primary key strategy override for this collection. */
+	idType?: PrimaryKeyType;
+	/** Row-level security policies. */
+	rlsPolicies?: RlsPolicyConfig[];
+	/** Phantom type for field inference. */
+	__fields?: F;
+}
+
+/**
+ * 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<F extends Record<string, AnyFieldBuilder>>(
+	tableName: string,
+	options: CollectionOptions<F>,
+): CollectionDefinition<F> {
+	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: CollectionDefinition["relations"] = [];
+	let fieldIndex = 0;
+	const fields: FieldDefinition[] = [];
+	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" as ObjectKind,
+		...(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: readonly FieldType[] = ["MORPH_RELATION"];
+
+/** Relation values live in a link table, not in the record's own storage. */
+export const RELATION_FIELD_TYPES: readonly FieldType[] = [
+	"RELATION",
+	"MORPH_RELATION",
+];
+
+export function isRelationFieldType(type: FieldType): boolean {
+	return RELATION_FIELD_TYPES.includes(type);
+}
+
+// ── Enums (SELECT options) ───────────────────────────────────────────
+
+/**
+ * One value in a SELECT / MULTI_SELECT field — what BIAB calls an "enum".
+ * Not a native Postgres enum: options are metadata, so adding or relabelling
+ * one costs no migration.
+ */
+export type SelectOption = {
+	/** The value a record actually stores. */
+	value: string;
+	label: string;
+	position: number;
+	color?: string;
+	/**
+	 * Stable identity for this option, surviving a `value` rename.
+	 *
+	 * OPTIONAL, and the reason matters. Records store the option's `value`
+	 * string, so renaming `"filed"` → `"submitted"` would otherwise read as
+	 * remove-plus-add: a destructive-looking plan for a safe change, and every
+	 * row holding the old string quietly fails validation. With an identifier,
+	 * the diff sees a rename and backfills the rows.
+	 *
+	 * Omit it and nothing breaks — the diff falls back to matching on `value`,
+	 * which is exactly the pre-existing behavior. Supply it and renames become
+	 * safe. That's why this is additive rather than required: no migration is
+	 * forced on options that already exist.
+	 */
+	universalIdentifier?: string;
+};
+
+// ── Fields ───────────────────────────────────────────────────────────
+
+/** What happens to a record that something else still links to. */
+export type RelationOnDelete = "restrict" | "setNull" | "cascade";
+
+/** Delete action modifier for the fluent relation chain. */
+export type DeleteAction = "CASCADE" | "RESTRICT" | "SET NULL" | "NO ACTION";
+
+/** Primary key strategy for auto-injected id fields. */
+export type PrimaryKeyType = "uuid" | "integer";
+
+const DELETE_ACTION_TO_ON_DELETE: Record<
+	DeleteAction,
+	RelationOnDelete | undefined
+> = {
+	CASCADE: "cascade",
+	RESTRICT: "restrict",
+	"SET NULL": "setNull",
+	"NO ACTION": undefined,
+};
+
+// ── Form Element Types ───────────────────────────────────────────────
+
+export type ExtTextType =
+	| "short_text"
+	| "long_text"
+	| "email"
+	| "url"
+	| "rich_text_input"
+	| "dropdown"
+	| "radio_group"
+	| "checkbox_group"
+	| "choice_cards"
+	| "services_selector"
+	| "phone_number"
+	| "date"
+	| "credit_card"
+	| "collection_select"
+	| "timePicker"
+	| "time_picker.date"
+	| "time_picker.time"
+	| "color";
+
+export type ExtObjectType =
+	| "address_group"
+	| "measurement"
+	| "availability"
+	| "object"
+	| "geo"
+	| "date_range"
+	| "time_picker_timeslot"
+	| "time_picker_datetime";
+
+export type ExtArrayType =
+	| "multi-select"
+	| "checkbox_group_many"
+	| "choice_cards_many"
+	| "services_selector_many"
+	| "tags"
+	| "formFileValue";
+
+export type ExtBooleanType = "yes_no_toggle" | "yes_no_checkbox";
+
+export type ExtNumberType =
+	| "number"
+	| "phone_number_basic"
+	| "currency"
+	| "range"
+	| "star_rating"
+	| "happiness_rating";
+
+export type AllFormElements =
+	| ExtTextType
+	| ExtObjectType
+	| ExtArrayType
+	| ExtBooleanType
+	| ExtNumberType;
+
+export type ChoiceCardDef = {
+	name: string;
+	icon?: string;
+	image_url?: string;
+	price?: number;
+	link_url?: string;
+	product_id?: string;
+	description?: string;
+};
+
+export type RangeDef = {
+	min: number;
+	max: number;
+	step?: number;
+	unit: "number" | "percentage" | "currency";
+};
+
+// ── Measurement Types ────────────────────────────────────────────────
+
+export type MeasurementCategory =
+	| "sound"
+	| "pressure"
+	| "torque"
+	| "speed"
+	| "time"
+	| "area"
+	| "volume"
+	| "power"
+	| "energy"
+	| "storage"
+	| "storageSpeed"
+	| "frequency"
+	| "temperature"
+	| "mass"
+	| "length"
+	| "currency"
+	| (string & {});
+
+export const PREDEFINED_UNITS: Record<string, readonly string[]> = {
+	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"],
+} as const;
+
+export type MeasurementDef = {
+	category: MeasurementCategory;
+	unitPicker: "fixed" | "userDefined";
+	default_unit: string;
+	resolve_to_your_unit: string;
+	allow_decimals: boolean;
+};
+
+// ── Object Field Types ───────────────────────────────────────────────
+
+export type ObjectPropertyDef = {
+	name: string;
+	label?: string;
+	field: FieldDefinition;
+};
+
+export type ObjectSchemaDef = {
+	properties: ObjectPropertyDef[];
+	strategy?: StorageStrategy;
+	separateTableName?: string;
+};
+
+// ── Dynamic Options Types ────────────────────────────────────────────
+
+export type DynamicOptionsDef = {
+	endpoint: string;
+	cachePolicy?: "stale-while-revalidate" | "no-cache" | "cache-first";
+	method?: "GET" | "POST";
+	headers?: Record<string, string>;
+};
+
+// ── Storage / Encryption / RLS Types ─────────────────────────────────
+
+export type StorageStrategy = "flattened" | "jsonb" | "separateTable";
+
+export type EncryptionMode = "none" | "user" | "master";
+
+export type RlsPolicyConfig = {
+	roles: ("authenticated" | "anonymous" | "admin" | string)[];
+	actions: ("read" | "write" | "update" | "delete")[];
+	expression?: string;
+};
+
+// ── Conditional Validation Types ─────────────────────────────────────
+
+export type RequiredIfCondition = {
+	fieldRef: string;
+	op: "equals" | "notEquals";
+	values: unknown[];
+};
+
+// ── File Field Types ─────────────────────────────────────────────────
+
+export type FileDef = {
+	max_size_mb?: number;
+	allowed_mimetypes?: string[];
+};
+
+// ── Address Field Types ──────────────────────────────────────────────
+
+export type AddressDef = {
+	require_postal_code?: boolean;
+	restrict_countries?: string[];
+};
+
+export type ElementMetadata =
+	| ChoiceCardDef[]
+	| RangeDef
+	| MeasurementDef
+	| ObjectSchemaDef
+	| FileDef
+	| AddressDef
+	| undefined;
+
+// ── Validation Rules ─────────────────────────────────────────────────
+
+export type SpecialDateValue = "today()" | string | Date;
+
+export interface ValidationRules {
+	lessThan?: number;
+	greaterThan?: number;
+	lessThanToday?: boolean;
+	greaterThanToday?: boolean;
+	specificDateValue?: SpecialDateValue;
+	minLength?: number;
+	maxLength?: number;
+	floor?: boolean;
+	isDecimal?: boolean;
+	round?: number;
+	positive?: boolean;
+	notNull?: boolean;
+	requiredIf?: RequiredIfCondition;
+	regex?: RegExp | string;
+	checkExpression?: string;
+}
+
+/** Runtime field value validator using ValidationRules. */
+export function validateFieldValue(
+	value: unknown,
+	rules: ValidationRules,
+	context?: Record<string, unknown>,
+): { valid: boolean; value: unknown; error?: string } {
+	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 as string | unknown[]).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: { value: unknown; unit: string },
+	meta: MeasurementDef,
+): { valid: boolean; value?: { value: number; unit: string }; error?: string } {
+	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: Partial<Record<FieldType, AllFormElements[]>> = {
+	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: FieldType): AllFormElements[] {
+	return FIELD_FORM_ELEMENT_MAP[fieldType] ?? [];
+}
+
+function isValidFormElement(
+	fieldType: FieldType,
+	elementName: string,
+): boolean {
+	const allowed = FIELD_FORM_ELEMENT_MAP[fieldType];
+	if (!allowed) return false;
+	return allowed.some((e) => e === elementName);
+}
+
+export type FieldDefinition = {
+	/** Stable identity. Survives renames — the diff keys on this, never on `name`. */
+	universalIdentifier: string;
+	/** camelCase. Doubles as the storage key, so renaming it backfills every row. */
+	name: string;
+	label: string;
+	type: FieldType;
+	icon?: string;
+	description?: string;
+	isRequired?: boolean;
+	isNullable?: boolean;
+	isUnique?: boolean;
+	defaultValue?: unknown;
+	isIndexed?: boolean;
+	isPrimaryKey?: boolean;
+	isAutoIncrement?: boolean;
+	position?: number;
+	/** Explicitly chosen form element for rendering. */
+	formElement?: AllFormElements;
+	/** Metadata payload for complex form elements (choice_cards options, range bounds). */
+	elementMetadata?: ElementMetadata;
+	/** Auto-populated list of compatible form elements for this field type. */
+	recommendedFormElements?: AllFormElements[];
+	/** Validation constraints for this field. */
+	validation?: ValidationRules;
+	/** Inline helper/instruction text displayed next to the field. */
+	helperText?: string;
+	/** Dynamic options endpoint for dropdown/radio/etc. */
+	dynamicOptions?: DynamicOptionsDef;
+	options?: SelectOption[];
+	relationTarget?: string;
+	onDelete?: RelationOnDelete;
+	/**
+	 * RELATION only — how many targets one source record may link to.
+	 * `"one"` makes this a single-value reference (a new pick replaces the old);
+	 * `"many"` (the default, and what `belongsToMany` sets) is a join table.
+	 */
+	relationCardinality?: "one" | "many";
+	/**
+	 * RELATION + `many` only — typed payload carried ON EACH LINK, compiled from
+	 * `belongsToMany(..., { fields })`. This is what turns a bare pair of ids into
+	 * a real join table: "which technologies, and at what proficiency".
+	 */
+	linkAttributes?: LinkAttributeDefinition[];
+	/** Storage strategy for object fields. */
+	strategy?: StorageStrategy;
+	/** Custom side-table name for separateTable strategy. */
+	separateTableName?: string;
+	/** Field-level encryption mode. */
+	encryption?: EncryptionMode;
+	/** Strip from public API responses. */
+	isPrivate?: boolean;
+};
+
+/** One typed attribute carried on a many-to-many link row. Mirrors
+ *  `LinkAttributeDef` on the BIAB side (`src/shared/data-model/link-attributes.ts`). */
+export type LinkAttributeDefinition = {
+	name: string;
+	label: string;
+	type: "TEXT" | "NUMBER" | "BOOLEAN" | "SELECT";
+	options?: string[];
+	isRequired?: boolean;
+	description?: string;
+};
+
+const NAME_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
+
+function assertSelectOptions(def: FieldDefinition): void {
+	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<string>();
+	const identifiers = new Set<string>();
+	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: FieldDefinition): void {
+	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<T extends FieldDefinition>(
+	definition: T,
+): Readonly<T> {
+	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);
+}
+
+// ── Objects & Collections ────────────────────────────────────────────
+
+export type ObjectKind = "standard" | "custom";
+
+/**
+ * Who may read an object's rows from outside your server.
+ *
+ * - `private` (default) — your server only, with a secret key. Nothing on the
+ *   public internet can read it.
+ * - `authenticated` — any customer signed in to your site, via tenant auth.
+ * - `public` — anyone at all, with a publishable (`pk_…`) key.
+ *
+ * ⚠️ `authenticated` means **any signed-in customer can read every row of this
+ * object**. It does NOT scope rows to the customer they belong to — that's
+ * row-level ownership, which this flag does not do. Never use `authenticated`
+ * to keep one customer's data away from another's.
+ *
+ * Applies to reads from outside only. Your dashboard always sees everything.
+ */
+export type ObjectVisibility = "private" | "authenticated" | "public";
+
+export const objectVisibilityValues: readonly ObjectVisibility[] = [
+	"private",
+	"authenticated",
+	"public",
+];
+
+export type ObjectDefinition = {
+	/** Stable identity. Survives renames. */
+	universalIdentifier: string;
+	/** `custom` (a new table) or `standard` (custom fields on a BIAB entity). */
+	kind?: ObjectKind;
+	/**
+	 * Who may read these rows from outside. Defaults to `private`.
+	 *
+	 * Declaring it here makes exposure reviewable in a pull request instead of
+	 * a setting someone flipped once. It still only PROPOSES: like every other
+	 * part of the model, a human promotes it before it takes effect.
+	 *
+	 * See {@link ObjectVisibility} — especially what `authenticated` does not do.
+	 */
+	visibility?: ObjectVisibility;
+	nameSingular: string;
+	namePlural: string;
+	labelSingular: string;
+	labelPlural: string;
+	icon?: string;
+	description?: string;
+	/** Which field is a record's headline. Must be one of `fields`. */
+	labelIdentifierFieldName?: string;
+	/**
+	 * `kind: "standard"` only — the BIAB entity these fields attach to
+	 * (e.g. "contact"). The object's own system fields stay immutable from
+	 * the CLI; only custom fields are yours to declare.
+	 */
+	standardEntityName?: string;
+	/** Which feature owns this table (set via SchemaBoundary). */
+	featureId?: string;
+	fields: FieldDefinition[];
+};
+
+function internalDefineObject<T extends ObjectDefinition>(
+	definition: T,
+): Readonly<T & { kind: ObjectKind }> {
+	if (!definition.universalIdentifier) {
+		throw new Error("defineField: universalIdentifier is required.");
+	}
+	for (const key of ["nameSingular", "namePlural"] as const) {
+		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<string>();
+	const identifiers = new Set<string>();
+	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: FieldDefinition | ObjectDefinition,
+): definition is ObjectDefinition {
+	return (
+		typeof definition === "object" &&
+		definition !== null &&
+		("nameSingular" in definition || "fields" in definition)
+	);
+}
+
+export function defineCollection<T extends FieldDefinition>(
+	definition: T,
+): Readonly<T>;
+export function defineCollection<T extends ObjectDefinition>(
+	definition: T,
+): Readonly<T & { kind: ObjectKind }>;
+export function defineCollection(
+	definition: FieldDefinition | ObjectDefinition,
+):
+	| Readonly<FieldDefinition>
+	| Readonly<ObjectDefinition & { kind: ObjectKind }> {
+	if (isObjectDefinitionInput(definition)) {
+		return internalDefineObject(definition);
+	}
+	return internalDefineField(definition);
+}
+
+export function defineField<T extends ObjectDefinition>(
+	definition: T,
+): Readonly<T & { kind: ObjectKind }>;
+export function defineField<T extends FieldDefinition>(
+	definition: T,
+): Readonly<T>;
+export function defineField(
+	definition: FieldDefinition | ObjectDefinition,
+):
+	| Readonly<FieldDefinition>
+	| Readonly<ObjectDefinition & { kind: ObjectKind }> {
+	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<T extends ObjectDefinition>(
+	definition: T,
+): Readonly<T & { kind: ObjectKind }> {
+	console.warn(
+		"[@businessdash/sdk] defineObject is deprecated. Please use defineField (or defineCollection) instead.",
+	);
+	return internalDefineObject(definition);
+}
+
+// ── The model ────────────────────────────────────────────────────────
+
+export type DataModelInput = {
+	objects?: ObjectDefinition[];
+	collections?: ObjectDefinition[];
+	/** Free-form provenance carried into the artifact (git sha, app name, …). */
+	metadata?: Record<string, string | number | boolean>;
+};
+
+export type DataModelArtifact = {
+	$schema: "https://biab.app/schemas/data-model/v1";
+	version: 1;
+	metadata: Record<string, string | number | boolean>;
+	objects: Array<{
+		universalIdentifier: string;
+		kind: ObjectKind;
+		nameSingular: string;
+		namePlural: string;
+		labelSingular: string;
+		labelPlural: string;
+		/**
+		 * Omitted entirely when private — see the note in `build()`. Absent
+		 * means private; the two are the same model and must hash the same.
+		 */
+		visibility?: ObjectVisibility;
+		icon?: string;
+		description?: string;
+		labelIdentifierFieldName?: string;
+		standardEntityName?: string;
+		fields: Array<{
+			universalIdentifier: string;
+			name: string;
+			label: string;
+			type: FieldType;
+			icon?: string;
+			description?: string;
+			isNullable?: boolean;
+			isUnique?: boolean;
+			isIndexed?: boolean;
+			isPrimaryKey?: boolean;
+			isAutoIncrement?: boolean;
+			formElement?: AllFormElements;
+			elementMetadata?: ElementMetadata;
+			recommendedFormElements?: AllFormElements[];
+			validation?: ValidationRules;
+			helperText?: string;
+			defaultValue?: unknown;
+			position?: number;
+			options?: SelectOption[];
+			relationTarget?: string;
+			onDelete?: RelationOnDelete;
+			strategy?: StorageStrategy;
+			separateTableName?: string;
+		}>;
+	}>;
+};
+
+export type DataModelClientShape = {
+	readonly objects: readonly Readonly<ObjectDefinition>[];
+	/** The document to upload. */
+	toJSONSchema(): DataModelArtifact;
+	/** SHA-256 of the canonicalized artifact. The server recomputes and compares. */
+	checksum(): Promise<string>;
+};
+
+/**
+ * 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: unknown): unknown {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(canonicalize);
+	const out: Record<string, unknown> = {};
+	for (const k of Object.keys(value as Record<string, unknown>).sort()) {
+		if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+		out[k] = canonicalize((value as Record<string, unknown>)[k]);
+	}
+	return out;
+}
+
+async function sha256Hex(input: string): Promise<string> {
+	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: Record<string, unknown>,
+): Promise<string> {
+	return sha256Hex(JSON.stringify(canonicalize(body)));
+}
+
+/** Global options for createSchema(). */
+export interface SchemaOptions {
+	/** Default primary key strategy across all collections. Defaults to 'uuid'. */
+	defaultIdType?: PrimaryKeyType;
+}
+
+/**
+ * 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: DataModelInput,
+	options: SchemaOptions = {},
+): DataModelClientShape {
+	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: PrimaryKeyType = 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 as CollectionDefinition;
+		const hasId =
+			col.fields.some((f) => f.name === "id") ||
+			col.fields.some((f) => f.isPrimaryKey);
+		if (hasId) continue;
+		const idStrategy: PrimaryKeyType = 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<string, ObjectDefinition>();
+	const byName = new Map<string, ObjectDefinition>();
+	const names = new Set<string>();
+	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<string>();
+		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: ObjectDefinition[] = [];
+	for (const object of objects) {
+		const objectWithRelations = object as CollectionDefinition;
+		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: RelationOnDelete =
+				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: PrimaryKeyType =
+				(object as CollectionDefinition).idType ?? globalIdType;
+			const junctionIdUid = generateUniversalIdentifier(
+				`biab:collection:${joinSingular}:field:id`,
+			);
+
+			const junctionFields: FieldDefinition[] = [
+				{
+					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: ObjectDefinition = {
+				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: DataModelArtifact | null = null;
+
+	function build(): DataModelArtifact {
+		if (cached) return cached;
+		const out: DataModelArtifact = {
+			$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() as unknown as Record<string, unknown>,
+			);
+		},
+	};
+}
+
+/**
+ * @deprecated Use `createSchema` instead. `defineDataModel` will be removed in a future release.
+ */
+export function defineDataModel(input: DataModelInput): DataModelClientShape {
+	console.warn(
+		"[@businessdash/sdk] defineDataModel is deprecated. Please use createSchema instead.",
+	);
+	return createSchema(input);
+}
+
+// ── Form + Schema Orchestrator ────────────────────────────────────────────
+// Layout wrappers that live entirely outside the database layer — collections
+// stay pure. The parser validates every layout reference against the compiled
+// schema and throws on any mismatch.
+
+export type ProgressStyle = "multi-step" | "progress_bar";
+
+export type LogicalOperator = "AND" | "OR";
+
+export type RuleMatchOperator = "equals" | "not_equals" | "any_of" | "none_of";
+
+export interface EvaluationRule {
+	fieldRef: string;
+	op: RuleMatchOperator;
+	values: unknown[];
+}
+
+// ── Type utilities for compile-time field path inference ──────────────
+
+/** Map a FieldType to its corresponding JavaScript runtime type. */
+export type InferJsType<T extends FieldType> = T extends
+	| "NUMBER"
+	| "NUMERIC"
+	| "CURRENCY"
+	| "RATING"
+	| "POSITION"
+	? number
+	: T extends "BOOLEAN"
+		? boolean
+		: T extends "ARRAY" | "MULTI_SELECT" | "FILES"
+			? unknown[]
+			: T extends "RAW_JSON" | "ADDRESS"
+				? unknown
+				: string;
+
+/** Infer the submitted/runtime object for one collection declaration. */
+export type InferCollectionValues<C> =
+	C extends CollectionDefinition<infer F> ? InferFieldsValues<F> : never;
+
+/**
+ * Infer values for a field map, one collection, or a map of collections used
+ * by a custom form.
+ */
+export type InferFormValues<T> = T extends CollectionDefinition
+	? InferCollectionValues<T>
+	: T extends Record<string, AnyFieldBuilder>
+		? InferFieldsValues<T>
+		: T extends Record<string, CollectionDefinition>
+			? { [K in keyof T]: InferCollectionValues<T[K]> }
+			: never;
+
+/** Infer a keyed value map for an entire schema's collection declarations. */
+export type InferSchemaValues<T extends Record<string, CollectionDefinition>> =
+	{
+		[K in keyof T]: InferCollectionValues<T[K]>;
+	};
+
+/** Extract all "collectionName.fieldName" paths from a tuple of CollectionDefinitions. */
+export type ExtractFieldPaths<C extends readonly CollectionDefinition[]> = {
+	[I in keyof C]: C[I] extends CollectionDefinition<infer F>
+		? {
+				[K in keyof F & string]: C[I]["nameSingular"] extends string
+					? `${C[I]["nameSingular"]}.${K}`
+					: never;
+			}[keyof F & string]
+		: never;
+}[number];
+
+/** Resolve a dot path like "projects.budget" to its JS type. */
+export type FindFieldTypeByPath<
+	Path extends string,
+	C extends readonly CollectionDefinition[],
+> =
+	C[number] extends CollectionDefinition<infer F>
+		? Path extends `${infer N}.${infer K}`
+			? K extends keyof F
+				? InferFieldValue<F[K]>
+				: never
+			: never
+		: never;
+
+/** A conditional rule with compile-time validation against the schema. */
+export type SecureEvalRule<
+	C extends readonly CollectionDefinition[],
+	Path extends ExtractFieldPaths<C> = ExtractFieldPaths<C>,
+> = {
+	fieldReference: Path;
+	op: "equals" | "not_equals" | "any_of" | "none_of";
+	values: FindFieldTypeByPath<Path, C>[];
+};
+
+// ── Layout node types ─────────────────────────────────────────────────
+
+export interface OptionGroup<
+	C extends readonly CollectionDefinition[] = readonly CollectionDefinition[],
+> {
+	name: string;
+	nodes: FormNode<C>[];
+	helperText?: string;
+}
+
+export type FormNode<
+	C extends readonly CollectionDefinition[] = readonly CollectionDefinition[],
+> =
+	| {
+			type: "render_collection";
+			collectionId: ExtractFieldPaths<C> extends never
+				? string
+				: C[number]["nameSingular"];
+			helperText?: string;
+	  }
+	| {
+			type: "step_group";
+			name: string;
+			helperText?: string;
+			children: FormNode<C>[];
+	  }
+	| {
+			type: "conditional_group";
+			fieldReference: ExtractFieldPaths<C> extends never
+				? string
+				: ExtractFieldPaths<C>;
+			condition: "any_of" | "all_of" | "equals";
+			values: unknown[];
+			rules?: SecureEvalRule<C>[];
+			helperText?: string;
+			children: FormNode<C>[];
+	  }
+	| {
+			type: "or_group";
+			helperText?: string;
+			button_label?: string;
+			options: OptionGroup<C>[];
+	  }
+	| {
+			type: "multi_populator";
+			collectionId: ExtractFieldPaths<C> extends never
+				? string
+				: C[number]["nameSingular"];
+			max_entries?: number;
+			button_label?: string;
+			helperText?: string;
+	  };
+
+// ── 0.9.50 layout container node types ────────────────────────────────
+
+export interface FormStepNode {
+	type: "form_step";
+	name: string;
+	showTitle?: boolean;
+	helperText?: string;
+	children: LayoutNode[];
+}
+
+export interface ConditionalBlockNode {
+	type: "conditional_block";
+	matchStrategy: LogicalOperator;
+	rules: EvaluationRule[];
+	showTitle?: boolean;
+	helperText?: string;
+	children: LayoutNode[];
+}
+
+export interface MultiPopulatorNode {
+	type: "multi_populator";
+	max_entries?: number;
+	button_label?: string;
+	showTitle?: boolean;
+	helperText?: string;
+	/**
+	 * Where each repeated entry is persisted. When omitted, the orchestrator
+	 * infers `separateTable` from the repeater's single child collection.
+	 */
+	output?: MultiPopulatorOutput;
+	/**
+	 * Field template for JSONB entries. Secondary-table repeaters derive their
+	 * fields from the target collection instead.
+	 */
+	entryFields?: FieldDefinition[];
+	children: LayoutNode[];
+}
+
+export type MultiPopulatorOutput =
+	| {
+			strategy: "jsonb";
+			/** Existing `collection.field` whose field declares `.strategy("jsonb")`. */
+			fieldRef: string;
+	  }
+	| {
+			strategy: "separateTable";
+			/** Target collection; inferred when the repeater has exactly one child collection. */
+			collectionId?: string;
+	  };
+
+export interface MultiPopulatorConfig {
+	max_entries?: number;
+	button_label?: string;
+	showTitle?: boolean;
+	helperText?: string;
+	output?: MultiPopulatorOutput;
+	/**
+	 * Schema for one JSONB array entry. Required for `output.strategy: "jsonb"`
+	 * and invalid for secondary-table output.
+	 */
+	entryFields?: Record<string, AnyFieldBuilder>;
+}
+
+export interface OrConditionNode {
+	type: "or_condition";
+	showTitle?: boolean;
+	helperText?: string;
+	button_label?: string;
+	branches: OptionGroup[];
+}
+
+export interface CollectionRefNode {
+	type: "render_collection";
+	collectionId: string;
+	helperText?: string;
+}
+
+export type LayoutNode =
+	| FormStepNode
+	| ConditionalBlockNode
+	| MultiPopulatorNode
+	| OrConditionNode
+	| CollectionRefNode;
+
+export interface FormOrchestrationOptions {
+	defaultIdType?: PrimaryKeyType;
+	consecutive?: boolean;
+	progress?: boolean;
+	progress_style?: ProgressStyle;
+}
+
+export interface FormAndSchemaConfig<
+	C extends readonly CollectionDefinition[] = readonly CollectionDefinition[],
+> {
+	collections: C;
+	layout: FormNode<C>[];
+	options?: FormOrchestrationOptions;
+}
+
+/** A custom-form draft generated from one compiled collection. */
+export type GeneratedFormCandidate = {
+	/** Stable key used by BIAB to update this generated draft idempotently. */
+	sourceKey: string;
+	name: string;
+	slug: string;
+	description: string;
+	fields: Array<{
+		id: string;
+		label: string;
+		/** BIAB custom-form renderer element type. */
+		type: string;
+		required: boolean;
+		outputKey: string;
+		options?: string[];
+		defaultValue?: string | boolean;
+		placeholder?: string;
+		helpText?: string;
+		regexPattern?: string;
+		validation?: { min?: number; max?: number };
+		collectionSelectConfig?: {
+			collectionKey: string;
+			labelField?: string;
+			valueMode: "id";
+			multi?: boolean;
+		};
+	}>;
+	settings: {
+		isConsecutive: boolean;
+		showProgress: boolean;
+		progressStyle?: "bar" | "steps";
+		generatedFrom: {
+			kind: "data_model";
+			sourceKey: string;
+			objectIdentifier?: string;
+			objectIdentifiers?: string[];
+		};
+		actions: Array<{
+			id: string;
+			type: "create_records";
+			enabled: true;
+			mapping: Record<string, string>;
+			config: {
+				composite: {
+					creates: Array<{
+						alias: string;
+						object: string;
+						fieldMap: Record<string, string>;
+						links?: Array<{ field: string; to: string }>;
+					}>;
+				};
+			};
+		}>;
+	};
+};
+
+// ── Schema Boundary ──────────────────────────────────────────────────
+
+export type BoundaryMetadata = {
+	featureId: string;
+	name: string;
+	description?: string;
+};
+
+export type SchemaBoundaryNode = {
+	type: "schema_boundary";
+	meta: BoundaryMetadata;
+	children: (CollectionDefinition | SchemaBoundaryNode | LayoutNode)[];
+};
+
+/**
+ * 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: BoundaryMetadata,
+	...children: (CollectionDefinition | SchemaBoundaryNode | LayoutNode)[]
+): SchemaBoundaryNode {
+	return { type: "schema_boundary", meta, children };
+}
+
+/**
+ * @deprecated Use `layoutContainers` instead. This API will be removed in a future release.
+ */
+export const layout = {
+	step: <
+		C extends readonly CollectionDefinition[] = readonly CollectionDefinition[],
+	>(
+		name: string,
+		children: FormNode<C>[],
+		options?: { helperText?: string },
+	): FormNode<C> =>
+		({
+			type: "step_group",
+			name,
+			...(options?.helperText !== undefined
+				? { helperText: options.helperText }
+				: {}),
+			children,
+		}) as FormNode<C>,
+	collection: <
+		C extends readonly CollectionDefinition[] = readonly CollectionDefinition[],
+	>(
+		collectionId: string,
+		options?: { helperText?: string },
+	): FormNode<C> =>
+		({
+			type: "render_collection",
+			collectionId,
+			...(options?.helperText !== undefined
+				? { helperText: options.helperText }
+				: {}),
+		}) as FormNode<C>,
+	conditional: <
+		C extends readonly CollectionDefinition[] = readonly CollectionDefinition[],
+	>(
+		fieldReference: string,
+		condition: "any_of" | "all_of" | "equals",
+		values: unknown[],
+		rules: SecureEvalRule<C>[] | undefined,
+		children: FormNode<C>[],
+		options?: { helperText?: string },
+	): FormNode<C> =>
+		({
+			type: "conditional_group",
+			fieldReference,
+			condition,
+			values,
+			rules,
+			...(options?.helperText !== undefined
+				? { helperText: options.helperText }
+				: {}),
+			children,
+		}) as FormNode<C>,
+	or: <
+		C extends readonly CollectionDefinition[] = readonly CollectionDefinition[],
+	>(
+		options: OptionGroup<C>[],
+		containerOptions?: { helperText?: string; button_label?: string },
+	): FormNode<C> =>
+		({
+			type: "or_group",
+			options,
+			...(containerOptions?.helperText !== undefined
+				? { helperText: containerOptions.helperText }
+				: {}),
+			...(containerOptions?.button_label !== undefined
+				? { button_label: containerOptions.button_label }
+				: {}),
+		}) as FormNode<C>,
+	multiPopulator: <
+		C extends readonly CollectionDefinition[] = readonly CollectionDefinition[],
+	>(
+		collectionId: string,
+		options?: {
+			max_entries?: number;
+			button_label?: string;
+			helperText?: string;
+		},
+	): FormNode<C> =>
+		({
+			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 }
+				: {}),
+		}) as FormNode<C>,
+};
+
+// ── layoutContainers (0.9.50+) ─────────────────────────────────────────────
+
+/**
+ * Semantic layout wrappers for form structure. Each container isolates
+ * UI flow rules without contaminating your core database collections.
+ *
+ * ```ts
+ * import { layoutContainers } from "@businessdash/sdk";
+ * const { FormStep, ConditionalBlock, MultiPopulator, OrCondition } = layoutContainers;
+ * ```
+ */
+type LayoutChild = LayoutNode | CollectionDefinition;
+
+function createFormStepNode(
+	name: string,
+	options: { showTitle?: boolean; helperText?: string } = {},
+	...children: LayoutChild[]
+): FormStepNode {
+	return {
+		type: "form_step",
+		name,
+		...(options.showTitle !== undefined
+			? { showTitle: options.showTitle }
+			: {}),
+		...(options.helperText !== undefined
+			? { helperText: options.helperText }
+			: {}),
+		children: children as LayoutNode[],
+	} as FormStepNode;
+}
+
+function createConditionalBlockNode(
+	config: {
+		matchStrategy: LogicalOperator;
+		rules: EvaluationRule[];
+		showTitle?: boolean;
+		helperText?: string;
+	},
+	...children: LayoutChild[]
+): ConditionalBlockNode {
+	return {
+		type: "conditional_block",
+		matchStrategy: config.matchStrategy,
+		rules: config.rules,
+		...(config.showTitle !== undefined ? { showTitle: config.showTitle } : {}),
+		...(config.helperText !== undefined
+			? { helperText: config.helperText }
+			: {}),
+		children: children as LayoutNode[],
+	} as ConditionalBlockNode;
+}
+
+function createMultiPopulatorNode(
+	config: MultiPopulatorConfig = {},
+	...children: LayoutChild[]
+): MultiPopulatorNode {
+	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 as LayoutNode[],
+	} as MultiPopulatorNode;
+}
+
+function createOrConditionNode(
+	options: {
+		showTitle?: boolean;
+		helperText?: string;
+		button_label?: string;
+	} = {},
+	branches: OptionGroup[] = [],
+): OrConditionNode {
+	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,
+	} as OrConditionNode;
+}
+
+export const layoutContainers = {
+	FormStep: createFormStepNode,
+	ConditionalBlock: createConditionalBlockNode,
+	MultiPopulator: createMultiPopulatorNode,
+	OrCondition: createOrConditionNode,
+};
+
+// ── createFormSchemaOrchestrator (0.9.50+) ────────────────────────────
+
+function toSlug(value: string): string {
+	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: AllFormElements): string {
+	const aliases: Partial<Record<AllFormElements, string>> = {
+		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: readonly Readonly<ObjectDefinition>[],
+	options: FormOrchestrationOptions,
+): GeneratedFormCandidate[] {
+	// 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<string, Readonly<ObjectDefinition>>();
+	for (const object of objects) {
+		objectByIdentifier.set(object.universalIdentifier, object);
+		objectByIdentifier.set(object.nameSingular, object);
+	}
+
+	return objects.flatMap((object) => {
+		const fieldMap: Record<string, string> = {};
+		const formFields: GeneratedFormCandidate["fields"] = [];
+
+		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" as const,
+								// 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" as const)
+										: ("steps" as const),
+							}
+						: {}),
+					generatedFrom: {
+						kind: "data_model" as const,
+						sourceKey,
+						objectIdentifier: object.universalIdentifier,
+						objectIdentifiers: [object.universalIdentifier],
+					},
+					actions: [
+						{
+							id: generateUniversalIdentifier(
+								`biab:generated-form:${object.universalIdentifier}:action:create-record`,
+							),
+							type: "create_records" as const,
+							enabled: true as const,
+							mapping: {},
+							config: {
+								composite: {
+									creates: [
+										{
+											alias: object.nameSingular,
+											object: object.universalIdentifier,
+											fieldMap,
+										},
+									],
+								},
+							},
+						},
+					],
+				},
+			},
+		];
+	});
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Single-resource action forms
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The three atomic operations generated for one collection. */
+export interface SingleResourceForms {
+	/** The collection this bundle operates on (its universalIdentifier). */
+	collectionId: string;
+	create: GeneratedFormCandidate;
+	edit: GeneratedFormCandidate;
+	delete: GeneratedFormCandidate;
+	/**
+	 * Collections this one points at, so an operator can see at a glance what a
+	 * form depends on.
+	 *
+	 * INFORMATIONAL ONLY. Nothing needs to "inject" these: a relation field's
+	 * generated picker already carries `collectionSelectConfig.collectionKey`,
+	 * and options load live at render. This list is for humans, not plumbing.
+	 */
+	dependencies: string[];
+}
+
+export interface SingleResourceFormOptions extends FormOrchestrationOptions {
+	/**
+	 * Sibling collections, used ONLY to describe what a delete would cascade to.
+	 * Omit and the delete form makes no cascade claim at all — silence beats a
+	 * confident sentence that might be wrong about someone's data.
+	 */
+	relatedObjects?: readonly Readonly<ObjectDefinition>[];
+}
+
+/** A record picker for one collection — "which row are we acting on?". */
+function recordIdentityField(
+	object: Readonly<ObjectDefinition>,
+	purpose: "edit" | "delete",
+): GeneratedFormCandidate["fields"][number] {
+	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" as const,
+		},
+	};
+}
+
+/**
+ * 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: Readonly<ObjectDefinition>,
+	related: readonly Readonly<ObjectDefinition>[],
+): string {
+	const cascades: string[] = [];
+	const blocks: string[] = [];
+	// `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: string | undefined) =>
+		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: Readonly<ObjectDefinition>,
+	options: SingleResourceFormOptions = {},
+): SingleResourceForms {
+	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: GeneratedFormCandidate = {
+		...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: GeneratedFormCandidate = {
+		...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: GeneratedFormCandidate = {
+		...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): t is string => typeof t === "string"),
+		),
+	];
+
+	return {
+		collectionId: object.universalIdentifier,
+		create,
+		edit,
+		delete: del,
+		dependencies,
+	};
+}
+
+function isCollectionDefinition(node: unknown): node is CollectionDefinition {
+	// 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: unknown): node is SchemaBoundaryNode {
+	return (
+		typeof node === "object" &&
+		node !== null &&
+		"type" in node &&
+		node.type === "schema_boundary"
+	);
+}
+
+function walkTreeForCollections(
+	boundaries: (SchemaBoundaryNode | CollectionDefinition)[],
+	collections: CollectionDefinition[],
+	featureTags: Record<string, string>,
+	inheritedFeatureId?: string,
+): LayoutNode[] {
+	const layoutNodes: LayoutNode[] = [];
+
+	for (const node of boundaries) {
+		if (isSchemaBoundaryNode(node)) {
+			const fid = node.meta.featureId;
+			const children = walkTreeForCollections(
+				node.children as (SchemaBoundaryNode | CollectionDefinition)[],
+				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 as LayoutNode & { branches?: OptionGroup[] };
+			if (
+				layoutNode.type === "form_step" ||
+				layoutNode.type === "conditional_block" ||
+				layoutNode.type === "multi_populator"
+			) {
+				const children = walkTreeForCollections(
+					(layoutNode.children || []) as unknown as (
+						| SchemaBoundaryNode
+						| CollectionDefinition
+					)[],
+					collections,
+					featureTags,
+					inheritedFeatureId,
+				);
+				layoutNodes.push({ ...layoutNode, children } as LayoutNode);
+			} else if (layoutNode.type === "or_condition") {
+				const branches = (layoutNode.branches || []).map((branch) => ({
+					...branch,
+					nodes: walkTreeForCollections(
+						branch.nodes as unknown as (
+							| SchemaBoundaryNode
+							| CollectionDefinition
+						)[],
+						collections,
+						featureTags,
+						inheritedFeatureId,
+					),
+				}));
+				layoutNodes.push({ ...layoutNode, branches } as LayoutNode);
+			} 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 as 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: (SchemaBoundaryNode | CollectionDefinition | LayoutNode)[],
+	options: FormOrchestrationOptions = {},
+): {
+	databaseSchema: DataModelClientShape;
+	uiFormTree: LayoutNode[];
+	/**
+	 * Inactive form drafts the CLI can include with the schema proposal.
+	 * Every field uses its explicit formElement or the first compatible
+	 * recommendedFormElements entry.
+	 */
+	generatedForms: GeneratedFormCandidate[];
+	formControlSettings: {
+		consecutive: boolean;
+		progress: boolean;
+		progressStyle?: ProgressStyle;
+	};
+	featureTags: Record<string, string>;
+} {
+	if (!Array.isArray(boundaries)) {
+		throw new Error(
+			"[BusinessDash SDK] createFormSchemaOrchestrator: `boundaries` must be an array of SchemaBoundaryNode | CollectionDefinition | LayoutNode.",
+		);
+	}
+	const collections: CollectionDefinition[] = [];
+	const featureTags: Record<string, string> = {};
+	const uiFormTree = walkTreeForCollections(
+		boundaries as (SchemaBoundaryNode | CollectionDefinition)[],
+		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: SchemaOptions =
+		options.defaultIdType !== undefined
+			? { defaultIdType: options.defaultIdType }
+			: {};
+
+	const compiledDatabaseSchema = createSchema({ collections }, schemaOptions);
+
+	const dbCollectionMap = new Map<
+		string,
+		{ name: string; fields: FieldDefinition[] }
+	>();
+	for (const col of compiledDatabaseSchema.objects) {
+		dbCollectionMap.set(
+			col.nameSingular,
+			col as unknown as { name: string; fields: FieldDefinition[] },
+		);
+	}
+
+	function renderedCollectionIds(nodes: LayoutNode[]): string[] {
+		const ids: string[] = [];
+		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 as LayoutNode[]));
+				}
+			}
+		}
+		return ids;
+	}
+
+	function generatedLayoutForms(
+		nodes: LayoutNode[],
+		collectionForms: GeneratedFormCandidate[],
+	): GeneratedFormCandidate[] {
+		const generated: GeneratedFormCandidate[] = [];
+		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: LayoutNode[]) => {
+			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 is Readonly<ObjectDefinition> =>
+									object !== undefined,
+							);
+						const identifiers = new Set(
+							objects.map((object) => object.universalIdentifier),
+						);
+						const aliasByIdentifier = new Map(
+							objects.map((object) => [
+								object.universalIdentifier,
+								object.nameSingular,
+							]),
+						);
+						const fields: GeneratedFormCandidate["fields"] = [];
+						const creates: GeneratedFormCandidate["settings"]["actions"][number]["config"]["composite"]["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: Array<{ field: string; to: string }> = [];
+
+							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" as const)
+														: ("steps" as const),
+											}
+										: {}),
+									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 as LayoutNode[]);
+					}
+				}
+			}
+		};
+		walk(nodes);
+		return generated;
+	}
+
+	function validateAndAlignLayout(nodes: LayoutNode[]) {
+		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 as LayoutNode[]);
+				}
+			}
+		}
+	}
+
+	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,
+	};
+}