@dforge-core/metadata 0.0.9 → 0.0.11

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to `@dforge-core/metadata` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.10] — 2026-07-24
+
+### Added
+
+- **Column domains** — a reusable, named semantic type (base datatype + control +
+  sizing + shared option list) that a column references via `FieldDef.domain`
+  (`"module_cd.domain_cd"`) instead of restating the definition. The domain supplies
+  `baseDatatypeCd`, `dbDatatype`, `fieldTypeCd`, `maxLen`, `precision` and `params`;
+  declaring any of those alongside `domain` is rejected at install.
+  - `schemas/domains.schema.json` — the `domains.json` authoring schema (re-vendored
+    from `docs/schemas`). Each domain requires `baseDatatypeCd`; `params.options`
+    carries the shared dropdown/radio/flags option list.
+  - `schemas/entity.schema.json` — new "Domain-backed column" branch: `required: ["domain"]`,
+    forbidding restatement of the domain-owned fields.
+  - `DomainsFile` / `DomainDef` types (`src/domains.ts`) — typed authoring surface for
+    `domains.json`; `FieldDef` gains `domain?: string`.
+
 ## [0.0.9] — 2026-07-22
 
 ### Added

package/dist/domains.d.ts

@@ -0,0 +1,32 @@
+import type { BaseDatatypeCd, FieldTypeCd, FieldOption } from "./types";
+/** A single reusable column domain. */
+export interface DomainDef {
+    /** Human-readable label. Localizable via `translations/<locale>.json` → `domains.<code>.label`. */
+    description?: string;
+    /**
+     * Base datatype the domain stands for. Required — it is what a consuming column's
+     * DDL is generated from.
+     */
+    baseDatatypeCd: BaseDatatypeCd;
+    /** Physical Postgres type for consuming columns; omit to infer from `fieldTypeCd`. */
+    dbDatatype?: string;
+    /** Control used to render/edit consuming columns (e.g. `dropdown`, `text`, `number`). */
+    fieldTypeCd?: FieldTypeCd;
+    /** Max length for string-backed domains. */
+    maxLen?: number;
+    /** Decimal precision for numeric domains. */
+    precision?: number;
+    /**
+     * Field-type config shared by every consuming column — most importantly the option
+     * list for `dropdown`/`radio`/`flags`. Never copied onto columns: it resolves from
+     * the domain at load time, which is what lets its labels be translated once for all
+     * consumers. Per-locale label/icon/color overrides live in `translations/<locale>.json`
+     * under `domains.<code>.options.<value>`.
+     */
+    params?: {
+        options?: (string | FieldOption)[];
+    } & Record<string, unknown>;
+}
+/** A `domains.json` file: reusable column domains keyed by domain code. */
+export type DomainsFile = Record<string, DomainDef>;
+//# sourceMappingURL=domains.d.ts.map

package/dist/domains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../src/domains.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAExE,uCAAuC;AACvC,MAAM,WAAW,SAAS;IACzB,mGAAmG;IACnG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,EAAE,cAAc,CAAC;IAC/B,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1E;AAED,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC"}

package/dist/domains.js

@@ -0,0 +1,10 @@
+// Column domains — authoring shape of `domains.json`. Mirror of domains.schema.json.
+//
+// A domain is a reusable, named semantic type: a base datatype, a control, sizing and
+// a shared option list under one code (e.g. `doc_status`). A column references it via
+// `FieldDef.domain` ("module_cd.domain_cd") instead of restating the definition. The
+// structural fields are materialized onto each column at install; `params` (the option
+// list) stays on the domain and resolves at load time, so a shared list is authored and
+// translated exactly once. See docs/modules/MODULE_CONVENTIONS.md.
+export {};
+//# sourceMappingURL=domains.js.map

package/dist/domains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domains.js","sourceRoot":"","sources":["../src/domains.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,EAAE;AACF,sFAAsF;AACtF,sFAAsF;AACtF,qFAAqF;AACrF,uFAAuF;AACvF,wFAAwF;AACxF,mEAAmE"}

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { vizTypes, chartTypes, type ReportsFile, type ReportDef, type ReportLayo
 export type { ManifestDef, ManifestAuthor, ModuleDependency } from "./manifest";
 export type { DepsFile, DepEntity, DepColumn, DepColumnType, DepColumnMode, DepProvenance, DepProvenanceKind } from "./deps";
 export { DEP_COLUMN_TYPES } from "./deps";
+export type { DomainsFile, DomainDef } from "./domains";
 export type { MenusFile, MenuDef, MenuItemDef, MenuItemType } from "./menus";
 export type { FoldersFile, FolderDef, FolderEntityBinding } from "./folders";
 export type { RolesFile, RoleDef } from "./roles";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,EAAE;AACF,8BAA8B;AAC9B,gFAAgF;AAChF,gFAAgF;AAChF,yCAAyC;AACzC,0EAA0E;AAC1E,iFAAiF;AACjF,+EAA+E;AAC/E,iDAAiD;AACjD,EAAE;AACF,8EAA8E;AAC9E,4CAA4C;AAkB5C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC9G,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,aAAa,GAEb,MAAM,UAAU,CAAC;AAiBlB,+EAA+E;AAC/E,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,EACN,aAAa,GAYb,MAAM,cAAc,CAAC;AAEtB,OAAO,EACN,QAAQ,EACR,UAAU,GAUV,MAAM,WAAW,CAAC;AAInB,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAY1C,mEAAmE;AACnE,sDAAsD;AACtD,MAAM,CAAC,MAAM,QAAQ,GAAqE;IACzF,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE;IAChC,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE;IACjC,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE;IACjC,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE;IAClC,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE;CACtB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,EAAE;AACF,8BAA8B;AAC9B,gFAAgF;AAChF,gFAAgF;AAChF,yCAAyC;AACzC,0EAA0E;AAC1E,iFAAiF;AACjF,+EAA+E;AAC/E,iDAAiD;AACjD,EAAE;AACF,8EAA8E;AAC9E,4CAA4C;AAkB5C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC9G,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,aAAa,GAEb,MAAM,UAAU,CAAC;AAiBlB,+EAA+E;AAC/E,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,EACN,aAAa,GAYb,MAAM,cAAc,CAAC;AAEtB,OAAO,EACN,QAAQ,EACR,UAAU,GAUV,MAAM,WAAW,CAAC;AAInB,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAa1C,mEAAmE;AACnE,sDAAsD;AACtD,MAAM,CAAC,MAAM,QAAQ,GAAqE;IACzF,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE;IAChC,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE;IACjC,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE;IACjC,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE;IAClC,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE;CACtB,CAAC"}

package/dist/types.d.ts

@@ -91,6 +91,13 @@ export interface FieldDef {
      * Absent ⇒ treated as an acyclic hierarchy guarded at the DB level.
      */
     cyclic?: boolean;
+    /**
+     * Reference to a reusable column domain, qualified as `module_cd.domain_cd`
+     * (unqualified resolves within the current module first, then tenant-created
+     * domains). Supplies `baseDatatypeCd`, `dbDatatype`, `fieldTypeCd`, `maxLen`,
+     * `precision` and `params`; declaring any of those alongside `domain` fails install.
+     */
+    domain?: string;
     /** Filter criteria for reference lookups. */
     refFilter?: unknown;
     /** Field-type-specific configuration (dropdown options, register config, …). */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,60 +1,60 @@
 {
-	"name": "@dforge-core/metadata",
-	"version": "0.0.9",
-	"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"
-		},
-		"./schemas/*": "./schemas/*",
-		"./package.json": "./package.json"
-	},
-	"files": [
-		"dist",
-		"src",
-		"schemas",
-		"CHANGELOG.md"
-	],
-	"scripts": {
-		"sync-schemas": "node scripts/sync-schemas.mjs",
-		"build": "tsc -p tsconfig.build.json",
-		"dev": "tsc -p tsconfig.build.json --watch",
-		"test": "vitest run",
-		"prepack": "pnpm sync-schemas && pnpm build",
-		"package": "pnpm pack"
-	},
-	"devDependencies": {
-		"@types/node": "^25.9.4",
-		"ajv": "^8.20.0",
-		"typescript": "^6.0.3",
-		"vitest": "^4.1.9"
-	}
+  "name": "@dforge-core/metadata",
+  "version": "0.0.11",
+  "description": "Canonical dForge authoring registries \u2014 field types, base datatypes, column types, traits, data-view kinds and chart types \u2014 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"
+    },
+    "./schemas/*": "./schemas/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "schemas",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "sync-schemas": "node scripts/sync-schemas.mjs",
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "test": "vitest run",
+    "prepack": "pnpm sync-schemas && pnpm build",
+    "package": "pnpm pack"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.4",
+    "ajv": "^8.20.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
 }

package/schemas/domains.schema.json

@@ -0,0 +1,78 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/domains.schema.json",
+	"title": "dForge Column Domains",
+	"description": "domains.json — reusable, named semantic types. A domain bundles a base datatype, a control, sizing and a shared option list under one code; columns reference it via \"domain\": \"module_cd.domain_cd\" instead of restating the definition. Structural fields are materialized onto each column at install; options stay on the domain and resolve at metadata-load time, so a shared list is authored and translated exactly once.",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/domain"
+	},
+	"propertyNames": {
+		"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+		"description": "Domain code. Must not contain '.', which is reserved for the qualified 'module_cd.domain_cd' form."
+	},
+	"$defs": {
+		"domain": {
+			"type": "object",
+			"required": ["baseDatatypeCd"],
+			"additionalProperties": false,
+			"properties": {
+				"description": {
+					"type": "string",
+					"description": "Human-readable label. Localizable via translations/<locale>.json under domains.<domain_cd>.label."
+				},
+				"baseDatatypeCd": {
+					"type": "string",
+					"description": "Base datatype the domain stands for (e.g. string, number, date, datetime, boolean). Required — it is what consuming columns' DDL is generated from."
+				},
+				"dbDatatype": {
+					"type": "string",
+					"description": "Physical Postgres type for consuming columns (e.g. varchar, int4, numeric). Omit to let it be inferred from fieldTypeCd."
+				},
+				"fieldTypeCd": {
+					"type": "string",
+					"description": "Control used to render/edit consuming columns (e.g. dropdown, radio, flags, text, number)."
+				},
+				"maxLen": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Max length for string-backed domains."
+				},
+				"precision": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Decimal precision for numeric domains."
+				},
+				"params": {
+					"type": "object",
+					"description": "Field-type config shared by every consuming column — most importantly the 'options' list for dropdown/radio/flags. Never copied onto columns: it resolves from the domain at load time, which is what lets its labels be translated once for all consumers.",
+					"properties": {
+						"options": {
+							"type": "array",
+							"description": "Option list. Each entry is either a bare string (value doubles as label) or an object. Per-locale label/icon/color overrides live in translations/<locale>.json under domains.<domain_cd>.options.<value>.",
+							"items": {
+								"oneOf": [
+									{ "type": "string" },
+									{
+										"type": "object",
+										"required": ["value"],
+										"additionalProperties": false,
+										"properties": {
+											"value": {
+												"type": "string",
+												"description": "The stored code. Never translatable — translations match on it."
+											},
+											"label": { "type": "string" },
+											"icon": { "type": "string" },
+											"color": { "type": "string" }
+										}
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

package/schemas/entity.schema.json

@@ -209,11 +209,29 @@
 					"type": "boolean",
 					"description": "On a self-referencing reference column (R column whose link.entity is the owning entity), set true to ALLOW parent/child cycles. When absent the self-reference is treated as an acyclic hierarchy and DB-level guards reject loops. Ignored on non-self-referencing columns."
 				},
+				"domain": {
+					"type": "string",
+					"description": "Reference to a reusable column domain, qualified as 'module_cd.domain_cd' (unqualified resolves within this module, then tenant-created domains). The domain supplies dbDatatype, baseDatatypeCd, fieldTypeCd, maxLen, precision and params; declaring any of those alongside 'domain' is rejected at install. The column keeps its own description, flags, orderNum, isNullable and isPk."
+				},
 				"refFilter": {
 					"description": "Filter criteria for reference lookups. Condition values support @[field] placeholders resolved against the current record at lookup time (e.g. {\"c\":\"channel\",\"o\":\"eq\",\"v\":\"@[channel]\"} narrows options to rows matching the record's own channel); a condition whose placeholder is unset is dropped rather than matching nothing."
 				}
 			},
 			"oneOf": [
+				{
+					"title": "Domain-backed column",
+					"description": "Physical column whose datatype, control, sizing and options all come from a reusable column domain. Requires 'domain' and must NOT restate what the domain owns.",
+					"required": ["domain"],
+					"properties": {
+						"link": false,
+						"dbDatatype": false,
+						"baseDatatypeCd": false,
+						"fieldTypeCd": false,
+						"maxLen": false,
+						"precision": false,
+						"params": false
+					}
+				},
 				{
 					"title": "Data column",
 					"description": "Physical DB column (columnType 'D' or unspecified). Requires 'dbDatatype'. Must NOT have 'link'.",

package/schemas/triggers.schema.json

@@ -37,20 +37,20 @@
 				},
 				"condition": {
 					"type": "string",
-					"description": "Optional formula expression — same shape as canExecute in action DSL. Uses `[field]` syntax to reference the affected record. Single-line, evaluates to boolean. If omitted, trigger fires for every matching event."
+					"description": "Optional formula expression — same shape as canExecute in action DSL. Uses `[field]` syntax to reference the affected record. Single-line, evaluates to boolean. If omitted, trigger fires for every matching event. Reference navigation (`[ref].[target]`) is REJECTED here: the event-time evaluator only reads columns of the changed row, so a nav path would resolve to null and the trigger would misfire. Navigate inside the action instead, or denormalise the value onto the watched entity."
 				},
 				"action": {
 					"type": "string",
-					"description": "Action code to invoke. The action must NOT use record-context (`[field]`) syntax in a way that requires the original triggering record — the trigger passes the record id via params. Cross-module form 'module.action' is supported."
+					"description": "Action code to invoke. The trigger binds the affected record to the action as RECORD CONTEXT, so the action reads its columns with `[field]` (and its PK with `[pk_column]`) exactly like a UI-invoked action — no lookup needed. The action's `entityCode` MUST equal this trigger's `entity`, and its `executionMode` must not be `batch`; both are enforced at pack time. Cross-module references use the qualified form 'module.action'."
 				},
 				"params": {
 					"type": "object",
-					"description": "Optional static parameters passed to the action at invocation time. Merged with the runtime-injected `record_id` / `record_old` (if event uses old-record diff)."
+					"description": "Optional STATIC parameters passed to the action at invocation time — the literal values written here, nothing else. Nothing is injected at runtime: there is no `record_id` param. The affected record arrives as record context (`[field]`), and its pre-change values as `old[field]` on update/delete/status_change events."
 				},
 				"async": {
 					"type": "boolean",
-					"default": false,
-					"description": "When true, the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls); background failures are logged, not surfaced to the caller. When false, the action runs synchronously inside the same transaction as the triggering insert/update/delete: if the action fails (e.g. calls error()), the whole mutation rolls back and the error is returned to the caller. Keep async:false actions fast — they run on the request's transaction."
+					"default": true,
+					"description": "When true (the default), the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls); background failures are logged, not surfaced to the caller. When false, the action runs synchronously inside the same transaction as the triggering insert/update/delete: if the action fails (e.g. calls error()), the whole mutation rolls back and the error is returned to the caller — so an async:false trigger can undo the user's write. Keep async:false actions fast; they run on the request's transaction."
 				}
 			},
 			"additionalProperties": false

package/src/domains.ts

@@ -0,0 +1,40 @@
+// Column domains — authoring shape of `domains.json`. Mirror of domains.schema.json.
+//
+// A domain is a reusable, named semantic type: a base datatype, a control, sizing and
+// a shared option list under one code (e.g. `doc_status`). A column references it via
+// `FieldDef.domain` ("module_cd.domain_cd") instead of restating the definition. The
+// structural fields are materialized onto each column at install; `params` (the option
+// list) stays on the domain and resolves at load time, so a shared list is authored and
+// translated exactly once. See docs/modules/MODULE_CONVENTIONS.md.
+
+import type { BaseDatatypeCd, FieldTypeCd, FieldOption } from "./types";
+
+/** A single reusable column domain. */
+export interface DomainDef {
+	/** Human-readable label. Localizable via `translations/<locale>.json` → `domains.<code>.label`. */
+	description?: string;
+	/**
+	 * Base datatype the domain stands for. Required — it is what a consuming column's
+	 * DDL is generated from.
+	 */
+	baseDatatypeCd: BaseDatatypeCd;
+	/** Physical Postgres type for consuming columns; omit to infer from `fieldTypeCd`. */
+	dbDatatype?: string;
+	/** Control used to render/edit consuming columns (e.g. `dropdown`, `text`, `number`). */
+	fieldTypeCd?: FieldTypeCd;
+	/** Max length for string-backed domains. */
+	maxLen?: number;
+	/** Decimal precision for numeric domains. */
+	precision?: number;
+	/**
+	 * Field-type config shared by every consuming column — most importantly the option
+	 * list for `dropdown`/`radio`/`flags`. Never copied onto columns: it resolves from
+	 * the domain at load time, which is what lets its labels be translated once for all
+	 * consumers. Per-locale label/icon/color overrides live in `translations/<locale>.json`
+	 * under `domains.<code>.options.<value>`.
+	 */
+	params?: { options?: (string | FieldOption)[] } & Record<string, unknown>;
+}
+
+/** A `domains.json` file: reusable column domains keyed by domain code. */
+export type DomainsFile = Record<string, DomainDef>;

package/src/index.ts

@@ -92,6 +92,7 @@ export {
 export type { ManifestDef, ManifestAuthor, ModuleDependency } from "./manifest";
 export type { DepsFile, DepEntity, DepColumn, DepColumnType, DepColumnMode, DepProvenance, DepProvenanceKind } from "./deps";
 export { DEP_COLUMN_TYPES } from "./deps";
+export type { DomainsFile, DomainDef } from "./domains";
 export type { MenusFile, MenuDef, MenuItemDef, MenuItemType } from "./menus";
 export type { FoldersFile, FolderDef, FolderEntityBinding } from "./folders";
 export type { RolesFile, RoleDef } from "./roles";

package/src/types.ts

@@ -151,6 +151,13 @@ export interface FieldDef {
 	 * Absent ⇒ treated as an acyclic hierarchy guarded at the DB level.
 	 */
 	cyclic?: boolean;
+	/**
+	 * Reference to a reusable column domain, qualified as `module_cd.domain_cd`
+	 * (unqualified resolves within the current module first, then tenant-created
+	 * domains). Supplies `baseDatatypeCd`, `dbDatatype`, `fieldTypeCd`, `maxLen`,
+	 * `precision` and `params`; declaring any of those alongside `domain` fails install.
+	 */
+	domain?: string;
 	/** Filter criteria for reference lookups. */
 	refFilter?: unknown;
 	/** Field-type-specific configuration (dropdown options, register config, …). */