@dforge-core/metadata 0.0.1

package/dist/types.js

@@ -0,0 +1,7 @@
+// Shared types for the dForge authoring registries.
+//
+// These describe the *authoring* surface (what a module author / visual editor
+// works with), mirrored from the platform metadata seed data. Keep them free of
+// any runtime dependency so this package stays import-safe everywhere.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,uEAAuE"}

package/dist/webhooks.d.ts

@@ -0,0 +1,31 @@
+import type { EntityEvent } from "./triggers";
+/** Outbound payload shaping for a webhook subscription. */
+export interface WebhookPayload {
+    /** Field codes to include. If omitted, all visible fields are included. */
+    include?: string[];
+    /** Include previous field values on update/status_change events. */
+    includeOld?: boolean;
+}
+/** A single webhook subscription. */
+export interface WebhookSubscription {
+    /** Unique identifier within the module. */
+    code: string;
+    description: string;
+    /** Entity code that triggers this webhook. */
+    entity: string;
+    event: EntityEvent;
+    /** Formula evaluated against the record; webhook fires only if true. */
+    condition?: string;
+    /** Default endpoint URL (admin can override). */
+    endpointUrl?: string;
+    /** Secret code for the API key (from `dforge.secret`). */
+    secretCd?: string;
+    payload?: WebhookPayload;
+    /** Enabled (default true). */
+    enabled?: boolean;
+}
+/** A `webhooks.json` file. */
+export interface WebhooksFile {
+    subscriptions: WebhookSubscription[];
+}
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC9B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,oEAAoE;IACpE,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,qCAAqC;AACrC,MAAM,WAAW,mBAAmB;IACnC,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,8BAA8B;AAC9B,MAAM,WAAW,YAAY;IAC5B,aAAa,EAAE,mBAAmB,EAAE,CAAC;CACrC"}

package/dist/webhooks.js

@@ -0,0 +1,3 @@
+// Webhooks — authoring shape of `webhooks.json`. Mirror of webhooks.schema.json.
+export {};
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA,iFAAiF"}

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@dforge-core/metadata",
+	"version": "0.0.1",
+	"description": "Canonical dForge authoring registries — field types, base datatypes, column types, traits, data-view kinds and chart types — with derivation helpers. Runtime-dependency-free; the single source of truth shared by editors, the web app and the CLI.",
+	"license": "MIT",
+	"author": "dForge",
+	"homepage": "https://github.com/iash44/dForge-core/tree/main/clients/packages/metadata#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/iash44/dForge-core.git",
+		"directory": "clients/packages/metadata"
+	},
+	"bugs": {
+		"url": "https://github.com/iash44/dForge-core/issues"
+	},
+	"keywords": [
+		"dforge",
+		"metadata",
+		"field-type",
+		"trait",
+		"registry",
+		"low-code"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"source": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"dev": "tsc -p tsconfig.build.json --watch",
+		"test": "vitest run",
+		"prepack": "pnpm build",
+		"package": "pnpm pack"
+	},
+	"devDependencies": {
+		"@types/node": "^25.2.1",
+		"typescript": "^6.0.2",
+		"vitest": "^4.1.8"
+	}
+}

package/src/actions.ts

@@ -0,0 +1,38 @@
+// Actions — authoring shape of `ui/actions.json`.
+//
+// There is no published JSON schema for actions; this mirrors the shape used
+// across the core modules. Parameter declarations and logic live in the action
+// DSL file (`logic/actions/<script>.dsl`), not here.
+
+/**
+ * Execution mode. 'single' (default) and 'each' run the DSL per selected record;
+ * 'batch' runs once with all records exposed as `__records`.
+ */
+export type ActionExecutionMode = "single" | "each" | "batch";
+
+/** A single action declaration (value in the `ui/actions.json` map). */
+export interface ActionDef {
+	/** Human-readable description. */
+	description: string;
+	/** Button label. */
+	label: string;
+	/** Bootstrap icon class (e.g. 'bi-telephone-check'). */
+	icon: string;
+	/** Entity code this action targets. */
+	entityCode: string;
+	/** Per-record vs. batch execution. */
+	executionMode: ActionExecutionMode;
+	/** DSL script name (file under `logic/actions/<script>.dsl`). */
+	script: string;
+	/** Run inside a transaction (failures roll back). */
+	isTransacted?: boolean;
+	/** Display order. */
+	orderNum?: number;
+	/** Run in the background (newer `async`; some modules use `isAsync`). */
+	async?: boolean;
+	/** Alternate spelling of `async` used by some modules. Prefer `async`. */
+	isAsync?: boolean;
+}
+
+/** A `ui/actions.json` file: action code → definition. */
+export type ActionsFile = Record<string, ActionDef>;

package/src/aggregation.ts

@@ -0,0 +1,21 @@
+// Aggregation types — the kinds of aggregation a column/report value can use.
+//
+// Declared as a `const` object + derived union (not a TS `enum`) so the package
+// stays enum-free like the rest of its registries, while callers keep the
+// ergonomic `AggType.Sum` member access. `AggType.Sum === "sum"` at runtime, so
+// the value is interchangeable with the plain string everywhere.
+
+export const AggType = {
+	Sum: "sum",
+	Count: "count",
+	Avg: "avg",
+	Min: "min",
+	Max: "max",
+	Group: "group",
+} as const;
+
+/** One of the aggregation codes ("sum" | "count" | …). */
+export type AggType = (typeof AggType)[keyof typeof AggType];
+
+/** All aggregation types as an array (useful for iteration). */
+export const AGG_TYPE_LIST: readonly AggType[] = Object.values(AggType);

package/src/base-datatypes.ts

@@ -0,0 +1,53 @@
+// Base datatype registry — mirror of
+//   server/database/system-modules/metadata/seed-data/base_datatypes.json
+//
+// Plus the canonical mapping from an abstract base datatype to the default
+// PostgreSQL column type the platform generates. The visual editor uses this so
+// the author never has to type a raw SQL type.
+
+import type { BaseDatatypeCd } from "./types";
+
+export const baseDatatypes: readonly BaseDatatypeCd[] = [
+	"binary",
+	"bool",
+	"culture",
+	"cuid",
+	"date",
+	"guid",
+	"json",
+	"link",
+	"number",
+	"project",
+	"ref",
+	"set",
+	"string",
+	"time",
+	"timestamp",
+	"xml",
+] as const;
+
+// Default PostgreSQL type per base datatype. `null` entries are non-physical
+// (relationship/virtual) base types that never produce a column on their own.
+const BASE_TO_DB: Record<BaseDatatypeCd, string | null> = {
+	binary: "bytea",
+	bool: "bool",
+	culture: "varchar",
+	cuid: "cuid",
+	date: "date",
+	guid: "uuid",
+	json: "jsonb",
+	link: null,
+	number: "numeric",
+	project: "varchar",
+	ref: null,
+	set: null,
+	string: "varchar",
+	time: "time",
+	timestamp: "timestamptz",
+	xml: "xml",
+};
+
+/** Default PostgreSQL type for a base datatype, or `null` if non-physical. */
+export function baseToDbDatatype(base: string): string | null {
+	return (BASE_TO_DB as Record<string, string | null>)[base] ?? null;
+}

package/src/column-types.ts

@@ -0,0 +1,22 @@
+// Column-type registry — the seven column kinds a field can have. Letters match
+// the `column.column_type` values and entity.schema.json. The `name` /
+// `description` here drive the friendly "what kind of field is this?" picker.
+
+import type { ColumnTypeDef } from "./types";
+
+export const columnTypes: readonly ColumnTypeDef[] = [
+	{ cd: "D", name: "Value", description: "A plain data column stored on this entity." },
+	{ cd: "R", name: "Reference", description: "An N:1 lookup to another entity (foreign key)." },
+	{ cd: "S", name: "Child list", description: "A 1:N collection of child records from another entity." },
+	{ cd: "F", name: "Formula", description: "A virtual value calculated from a formula expression." },
+	{ cd: "G", name: "Generated", description: "A physical column auto-maintained by the database (aggregate or expression)." },
+	{ cd: "A", name: "Accumulation register", description: "Posts this document into a balance entity (single direction)." },
+	{ cd: "L", name: "Ledger register", description: "Posts document lines into movements + balances (double entry)." },
+] as const;
+
+const byCd = new Map<string, ColumnTypeDef>(columnTypes.map((ct) => [ct.cd, ct]));
+
+/** Look up a column type by letter. */
+export function getColumnType(cd: string): ColumnTypeDef | undefined {
+	return byCd.get(cd);
+}

package/src/data-views.ts

@@ -0,0 +1,139 @@
+// Data-view registries + the authoring shape of a `ui/data_views.json` file.
+//
+// `dataViewKinds` is the friendly picker list; `DataViewDef` and friends mirror
+// the structural `data_views.schema.json` so editors/MCP/CLI can build views.
+
+import type { Filter } from "./filter";
+import type { NamedKind } from "./types";
+
+export type { NamedKind };
+
+/** `viewType` values for `ui/data_views.json`. Source: data_views.schema.json. */
+export type ViewType =
+	| "grid"
+	| "list"
+	| "kanban"
+	| "calendar"
+	| "gallery"
+	| "tree-grid"
+	| "diagram"
+	| "master-detail"
+	| "library";
+
+/** Friendly picker list of the view kinds. */
+export const dataViewKinds: readonly NamedKind[] = [
+	{ cd: "grid", name: "Grid" },
+	{ cd: "list", name: "List" },
+	{ cd: "kanban", name: "Kanban" },
+	{ cd: "calendar", name: "Calendar" },
+	{ cd: "gallery", name: "Gallery" },
+	{ cd: "tree-grid", name: "Tree Grid" },
+	{ cd: "diagram", name: "Diagram" },
+	{ cd: "master-detail", name: "Master / Detail" },
+	{ cd: "library", name: "Library" },
+] as const;
+
+/** A column in a data source: shorthand string code or a configured object. */
+export type ViewColumn =
+	| string
+	| {
+			/** Column code. */
+			column_cd: string;
+			/** Column width in pixels. */
+			width?: number;
+			/** Whether the column is visible (default true). */
+			visible?: boolean;
+			/** Pin column to an edge. */
+			pinned?: "left" | "right";
+	  };
+
+/** One data source within a view. */
+export interface DataSource {
+	/** Entity code to query. */
+	entityCode: string;
+	/** Nesting level (0 = root, 1+ = detail). */
+	level?: number;
+	/** Human-readable label (used in master-detail tabs). */
+	label?: string;
+	/** Column configuration. */
+	columns?: ViewColumn[];
+	/** Set field on the parent entity linking to this detail level. */
+	parentSetField?: string;
+	/** Per-source filter; overrides the view-level filter for this source. */
+	filter?: Filter;
+	/** Per-source sort order (array of `{ c, d }` entries). */
+	order?: unknown;
+}
+
+export interface KanbanViewConfig {
+	/** Dropdown/flags/reference column to group cards by. */
+	groupByField: string;
+}
+
+export interface CalendarViewConfig {
+	/** Date/timestamp column used to place events. */
+	dateField: string;
+	/** Column shown as event title (defaults to the entity toString). */
+	titleField?: string;
+	/** Column whose value drives the event pill color. */
+	colorField?: string;
+}
+
+export interface TreeGridViewConfig {
+	/** Self-referencing FK column (parent record). */
+	parentField: string;
+	/** Node label field (defaults to entity toString). */
+	labelField?: string;
+	/** Field containing a Bootstrap icon class per node. */
+	iconField?: string;
+}
+
+export interface ListLevelConfig {
+	/** Entity code for this child level. */
+	entityCode: string;
+	/** FK column in the child entity linking back to the parent. */
+	foreignKey: string;
+	/** Columns to display inline for each child row. */
+	columns?: string[];
+}
+
+export interface ListViewConfig {
+	titleField?: string;
+	subtitleField?: string;
+	/** Hierarchical child levels for expandable list rows. */
+	levels?: ListLevelConfig[];
+}
+
+export interface DiagramViewConfig {
+	/** Column to group diagram nodes by. */
+	groupByField?: string;
+	/** Group values hidden by default. */
+	defaultHiddenGroups?: string[];
+}
+
+/** A single data view (value in the `ui/data_views.json` map). */
+export interface DataViewDef {
+	viewType: ViewType;
+	/** Human-readable view name. */
+	label?: string;
+	/** Bootstrap icon class (e.g. 'bi-bounding-box'). */
+	icon?: string;
+	description?: string;
+	/** Data sources (at least one; master-detail needs two). */
+	dataSources: DataSource[];
+	/** Default filter applied to all sources unless one declares its own. */
+	filter?: Filter;
+	/** Default sort order. */
+	order?: unknown;
+	/** View-type-specific configuration. */
+	viewConfig?:
+		| KanbanViewConfig
+		| CalendarViewConfig
+		| TreeGridViewConfig
+		| ListViewConfig
+		| DiagramViewConfig
+		| Record<string, unknown>;
+}
+
+/** A `ui/data_views.json` file: data view code → definition. */
+export type DataViewsFile = Record<string, DataViewDef>;

package/src/derive.ts

@@ -0,0 +1,63 @@
+// Derivation helpers — turn a friendly field-type choice into the physical
+// metadata the platform needs, so the author never types a raw SQL type.
+//
+// Defaults follow how core modules actually author fields (e.g. currency →
+// numeric(18,2), color → varchar(20)); callers may always override the result.
+
+import { baseToDbDatatype } from "./base-datatypes";
+import { getFieldType } from "./field-types";
+
+/** Total digits used when building a `numeric(total, scale)` type. */
+export const NUMERIC_TOTAL = 18;
+
+/** Field types whose natural storage is unbounded `text` rather than `varchar`. */
+const TEXT_BACKED = new Set(["textarea", "richtext", "code"]);
+
+export interface DeriveOptions {
+	/** Author-specified max length; overrides the field type's default. */
+	maxLen?: number | null;
+	/** Author-specified numeric scale; overrides the field type's default. */
+	precision?: number | null;
+}
+
+/**
+ * Derive the PostgreSQL `dbDatatype` for a field type. Returns `null` for
+ * field types backed by relationships/sets (lookup, grid) that have no physical
+ * column of their own. Unknown field types fall back to `varchar`.
+ */
+export function deriveDbDatatype(fieldTypeCd: string, options: DeriveOptions = {}): string | null {
+	const ft = getFieldType(fieldTypeCd);
+	if (!ft) return "varchar";
+
+	// Relationship-backed types (lookup → R, grid → S) never own a physical
+	// column — the FK lives on a separate hidden column.
+	if (ft.columnType === "R" || ft.columnType === "S") return null;
+
+	const base = baseToDbDatatype(ft.baseDatatypeCd);
+	if (base === null) return null; // other non-physical base (link/ref/set)
+
+	if (ft.baseDatatypeCd === "number") {
+		const precision = options.precision ?? ft.precision;
+		return precision != null ? `numeric(${NUMERIC_TOTAL},${precision})` : "numeric";
+	}
+
+	if (ft.baseDatatypeCd === "string") {
+		if (TEXT_BACKED.has(ft.cd)) return "text";
+		const maxLen = options.maxLen ?? ft.maxLen;
+		return maxLen != null ? `varchar(${maxLen})` : "varchar";
+	}
+
+	return base;
+}
+
+/** Default `params` to seed a new field of this type with (or `undefined`). */
+export function defaultParams(fieldTypeCd: string): Record<string, unknown> | undefined {
+	const ft = getFieldType(fieldTypeCd);
+	if (!ft?.defParams) return undefined;
+	return { ...ft.defParams };
+}
+
+/** The base datatype code a field type maps to (for `baseDatatypeCd` on F columns). */
+export function deriveBaseDatatype(fieldTypeCd: string): string | undefined {
+	return getFieldType(fieldTypeCd)?.baseDatatypeCd;
+}

package/src/entity.ts

@@ -0,0 +1,124 @@
+// Entity definition — authoring shape of an `entities/*.json` file.
+//
+// Mirror of entity.schema.json. Describes a table/view mapping: its fields
+// (see FieldDef in types.ts), traits, references, number sequence and the
+// register configs for accumulation/ledger entities.
+
+import type { FieldDef } from "./types";
+
+/** Trait codes valid in an entity's `traits` array (entity.schema.json enum). */
+export type TraitCd =
+	| "identity"
+	| "audit"
+	| "audit-full"
+	| "soft-delete"
+	| "sorting"
+	| "postable"
+	| "accumulation"
+	| "ledger"
+	| "period"
+	| "file-library";
+
+/** Foreign-key reference (legacy `references` block — prefer `link` on a field). */
+export interface EntityReference {
+	from: { field: string };
+	to: { entity: string; field: string };
+}
+
+/** Automatic document numbering config (entity `numberSequence`). */
+export interface NumberSequenceDef {
+	/** Column code that receives the auto-generated number. */
+	column: string;
+	/** Module setting code to resolve the prefix from (folder-scoped). */
+	prefixSettingCd?: string;
+	/** Fallback prefix when no setting is configured. */
+	defaultPrefix: string;
+	/** Format pattern. Placeholders: {prefix}, {yyyy}, {yy}, {mm}, {dd}, {seq:N}. */
+	pattern?: string;
+	/** Counter reset period (default: year). */
+	resetPeriod?: "year" | "month" | "day" | "never";
+}
+
+/** Period-entity config (`period` block; requires the `period` trait). */
+export interface PeriodConfig {
+	/** Format for the period key. Placeholders: {yyyy}, {yy}, {MM}, {dd}, {q}. */
+	keyFormat: string;
+}
+
+/** Dynamic sign determination based on a field value. */
+export interface SignConfig {
+	/** Field code that determines direction. */
+	field: string;
+	/** Values that mean increase. */
+	positive: string[];
+	/** Values that mean decrease. */
+	negative: string[];
+}
+
+/** Accumulation-registry config (`accumulation` block; requires the trait). */
+export interface AccumulationConfig {
+	/** Balance entity code (e.g. 'stock'). */
+	balanceEntity: string;
+	/** Balance lookup dimensions: field-name array or balance→document field map. */
+	dimensions: string[] | Record<string, string>;
+	/** Document field → balance field resource mappings. */
+	resources: Record<string, { balanceField: string }>;
+	/** Fixed posting direction for all postings. */
+	direction?: "increase" | "decrease";
+	/** Dynamic sign (alternative to `direction`). */
+	sign?: SignConfig;
+	autoCreateBalance?: boolean;
+	allowNegative?: boolean;
+	/** Document fields locked once posted. */
+	lockedFields?: string[];
+}
+
+/** One registry target within an L-column's `registries` array. */
+export interface LedgerRegistryEntry {
+	/** Movement entity code (e.g. 'posting_record'). */
+	movementEntity: string;
+	/** Line field → movement field mapping. */
+	movementMapping: Record<string, string>;
+	/** Balance entity code (e.g. 'balance_register'). */
+	balanceEntity: string;
+	balanceMapping: {
+		/** Balance row dimension columns. */
+		dimensions: string[];
+		/** Balance column for debit turnover. */
+		debitResource: string;
+		/** Balance column for credit turnover. */
+		creditResource: string;
+	};
+}
+
+/** A single entity definition (`entities/<code>.json`). */
+export interface EntityDef {
+	/** Qualified entity code to extend (e.g. 'fin.invoice') — turns this into an extension. */
+	extends?: string;
+	description?: string;
+	/** Database schema name override (defaults to module schema). */
+	schema?: string;
+	/** Database table/view name (defaults to entity code). */
+	dbObject?: string;
+	/** When true, maps to a SQL view (read-only, no DDL). */
+	isView?: boolean;
+	/** SELECT statement for view-backed entities (`isView=true`). */
+	viewSql?: string;
+	/** Display pattern using column placeholders, e.g. "{first_name} {last_name}". */
+	toString?: string;
+	/** Traits expanded at install time. */
+	traits?: TraitCd[];
+	/** Column definitions keyed by column code. */
+	fields: Record<string, FieldDef>;
+	/** Database constraints (unique, check, …); free-form per the schema. */
+	constraints?: Record<string, unknown>;
+	/** FK references (legacy format; prefer `link` on a field). */
+	references?: Record<string, EntityReference>;
+	/** Database index definitions; free-form per the schema. */
+	indexes?: Record<string, unknown>;
+	numberSequence?: NumberSequenceDef;
+	period?: PeriodConfig;
+	accumulation?: AccumulationConfig;
+	/** Entity-level platform behavior flags. */
+	params?: { restricted?: boolean } & Record<string, unknown>;
+}

package/src/field-types.ts

@@ -0,0 +1,68 @@
+// Field-type registry — mirror of
+//   server/database/system-modules/metadata/seed-data/field_types.json
+//
+// This is the authoring source of truth: an author picks a `fieldTypeCd` and the
+// editor derives `baseDatatypeCd` + `dbDatatype` from the entry here. Kept in
+// sync with the server seed by the parity test in test/registries.test.ts —
+// if that test fails after a seed change, regenerate this list.
+
+import type { FieldTypeCd, FieldTypeDef } from "./types";
+
+// `satisfies` (not `: readonly FieldTypeDef[]`) so the literal `cd` values are
+// preserved in the type — that powers the compile-time coverage guard below.
+export const fieldTypes = [
+	{ cd: "text", name: "Text", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+	{ cd: "email", name: "Email", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+	{ cd: "phone", name: "Phone", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+	{ cd: "url", name: "URL", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+	{ cd: "textarea", name: "Multiline Text", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+	{ cd: "number", name: "Number", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: null, useStringInFilter: false, defParams: { min: 0, max: 10000 } },
+	{ cd: "currency", name: "Currency", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: 2, useStringInFilter: false, defParams: { min: 0, max: 1000000 } },
+	{ cd: "percent", name: "Percent", columnType: "D", baseDatatypeCd: "number", supportedAgg: "CAM", maxLen: null, precision: 2, useStringInFilter: false, defParams: { min: 0, max: 100 } },
+	{ cd: "checkbox", name: "Checkbox", columnType: "D", baseDatatypeCd: "bool", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
+	{ cd: "date", name: "Date", columnType: "D", baseDatatypeCd: "date", supportedAgg: "CM", maxLen: null, precision: null, useStringInFilter: false },
+	{ cd: "datetime", name: "Date & Time", columnType: "D", baseDatatypeCd: "timestamp", supportedAgg: "CM", maxLen: null, precision: null, useStringInFilter: false },
+	{ cd: "time", name: "Time", columnType: "D", baseDatatypeCd: "time", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
+	{ cd: "dropdown", name: "Dropdown", columnType: "D", baseDatatypeCd: "string", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: true },
+	{ cd: "flags", name: "Flags", columnType: "D", baseDatatypeCd: "string", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: true, defParams: { style: "buttons" } },
+	{ cd: "json", name: "JSON Editor", columnType: "D", baseDatatypeCd: "json", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
+	{ cd: "hidden", name: "Hidden", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
+	{ cd: "color", name: "Color Picker", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: 20, precision: null, useStringInFilter: false },
+	{ cd: "image", name: "Image", columnType: "D", baseDatatypeCd: "binary", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
+	{ cd: "file", name: "File", columnType: "D", baseDatatypeCd: "binary", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
+	{ cd: "richtext", name: "Rich Text Editor", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+	{ cd: "lookup", name: "Lookup", columnType: "R", baseDatatypeCd: "guid", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: true },
+	{ cd: "user", name: "User Picker", columnType: "D", baseDatatypeCd: "cuid", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
+	{ cd: "grid", name: "Detail Grid", columnType: "S", baseDatatypeCd: "set", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
+	{ cd: "tags", name: "Tags", columnType: "D", baseDatatypeCd: "string", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: true },
+	{ cd: "entitylink", name: "Entity Link", columnType: "D", baseDatatypeCd: "json", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
+	{ cd: "code", name: "Code Editor", columnType: "D", baseDatatypeCd: "string", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
+] as const satisfies readonly FieldTypeDef[];
+
+// Compile-time coverage guard: every `FieldTypeCd` must have a row above, and
+// every row's `cd` must be a `FieldTypeCd`. If the union and the array drift
+// apart, one of these two assignments fails to compile.
+type _MissingFromArray = Exclude<FieldTypeCd, (typeof fieldTypes)[number]["cd"]>;
+type _MissingFromUnion = Exclude<(typeof fieldTypes)[number]["cd"], FieldTypeCd>;
+const _coverageOk: [_MissingFromArray, _MissingFromUnion] = [undefined as never, undefined as never];
+void _coverageOk;
+
+const byCd = new Map<string, FieldTypeDef>(fieldTypes.map((ft) => [ft.cd, ft]));
+
+/** Set of all known field type codes, for membership checks. */
+export const fieldTypeCds: ReadonlySet<string> = new Set(fieldTypes.map((ft) => ft.cd));
+
+/** Type guard: is `cd` one of the known field type codes? */
+export function isFieldTypeCd(cd: string | undefined): cd is FieldTypeCd {
+	return cd != null && fieldTypeCds.has(cd);
+}
+
+/** Look up a field type by code, or `undefined` if unknown. */
+export function getFieldType(cd: string): FieldTypeDef | undefined {
+	return byCd.get(cd);
+}
+
+/** Field types whose default column kind is `columnType` (e.g. "D" value types). */
+export function fieldTypesByColumnType(columnType: string): readonly FieldTypeDef[] {
+	return fieldTypes.filter((ft) => ft.columnType === columnType);
+}