@dforge-core/metadata 0.0.33 → 0.0.35

package/schemas/seed_data.schema.json

@@ -12,11 +12,22 @@
 		},
 		"records": {
 			"type": "array",
-			"description": "Array of records, each record is an object with column_code → value",
+			"description": "Array of records, each record is an object with column_code → value. In demo-data/ a value may be a formula: { \"$f\": \"DATEADD(@yearStart, 42, 'DAY')\" }",
 			"items": {
 				"type": "object",
 				"additionalProperties": true
 			}
+		},
+		"repeat": {
+			"type": "object",
+			"description": "demo-data/ only: insert every record once per value of @var, from..to inclusive",
+			"required": ["to"],
+			"properties": {
+				"var": { "type": "string", "default": "i" },
+				"from": { "type": "integer", "default": 1 },
+				"to": { "type": "integer" }
+			},
+			"additionalProperties": false
 		}
 	},
 	"additionalProperties": false

package/schemas/settings.schema.json

@@ -10,7 +10,6 @@
 	"$defs": {
 		"setting": {
 			"type": "object",
-			"required": ["fieldTypeCd"],
 			"properties": {
 				"fieldTypeCd": {
 					"type": "string",
@@ -47,8 +46,32 @@
 				"params": {
 					"type": "object",
 					"description": "Field-type-specific parameters. Examples: dropdown → { options: [...] }; number → { min, max }; lookup → { link: { entity, otherKey } }."
+				},
+				"domain": {
+					"type": "string",
+					"description": "Reference to a reusable column domain. A bare 'domain_cd' means this module's own domain, then a tenant-created one, and never another module's, even one with the same code. 'module_cd.domain_cd' names a domain of any installed module; declare that module as a dependency. The domain supplies fieldTypeCd, baseDatatypeCd and params; declaring any of those alongside 'domain' is rejected at install. The setting keeps its own label, defaultValue, formula and required flag."
 				}
 			},
+			"oneOf": [
+				{
+					"title": "Domain-backed setting",
+					"description": "Setting whose control and option list come from a reusable column domain. Requires 'domain' and must NOT restate what the domain owns.",
+					"required": ["domain"],
+					"properties": {
+						"fieldTypeCd": false,
+						"baseDatatypeCd": false,
+						"params": false
+					}
+				},
+				{
+					"title": "Inline setting",
+					"description": "Setting that declares its own control and parameters. Requires 'fieldTypeCd'.",
+					"required": ["fieldTypeCd"],
+					"properties": {
+						"domain": false
+					}
+				}
+			],
 			"additionalProperties": false
 		}
 	}

package/schemas/stored_procedures.schema.json

@@ -117,9 +117,32 @@
 					"type": "object",
 					"description": "Control parameters, the same shape an entity column's `params` takes — `options` for a dropdown or flags, `currency`, `align`, and so on.",
 					"additionalProperties": true
+				},
+				"domain": {
+					"type": "string",
+					"description": "Reference to a reusable column domain. Unqualified resolves within this module, then tenant-created domains; 'module_cd.domain_cd' binds to that module. The domain supplies the control, datatype and option list — and its options are translated once, for every consumer."
 				}
 			},
-			"additionalProperties": false
+			"additionalProperties": false,
+			"oneOf": [
+				{
+					"title": "Domain-backed result column",
+					"description": "Defers to a column domain. Must not restate what the domain owns.",
+					"required": ["domain"],
+					"properties": {
+						"fieldTypeCd": false,
+						"baseDatatypeCd": false,
+						"params": false
+					}
+				},
+				{
+					"title": "Inline result column",
+					"description": "Declares its own control and datatype.",
+					"properties": {
+						"domain": false
+					}
+				}
+			]
 		}
 	}
 }

package/schemas/traits.schema.json

@@ -79,9 +79,34 @@
 						"serverDefault": { "$ref": "#/$defs/serverDefault" }
 					},
 					"additionalProperties": true
+				},
+				"domain": {
+					"type": "string",
+					"description": "Reference to a reusable column domain. A bare 'domain_cd' resolves in the module of the entity taking the trait, then tenant-created domains, so one generic trait gives each module its own list; 'module_cd.domain_cd' pins one module's domain for every entity. A module's own traits.json must qualify a domain the module itself defines: written bare, it would bind to a same-named domain of whichever module takes the trait, and pack rejects it. The domain supplies the type, control, sizing and options."
 				}
 			},
-			"additionalProperties": false
+			"additionalProperties": false,
+			"oneOf": [
+				{
+					"title": "Domain-backed trait field",
+					"description": "Defers to a column domain. Must not restate what the domain owns, and takes no 'link' — it is a plain scalar column.",
+					"required": ["domain"],
+					"properties": {
+						"link": false,
+						"dbDatatype": false,
+						"fieldTypeCd": false,
+						"maxLen": false,
+						"params": false
+					}
+				},
+				{
+					"title": "Inline trait field",
+					"description": "Declares its own type and control, as trait fields always have.",
+					"properties": {
+						"domain": false
+					}
+				}
+			]
 		},
 		"serverDefault": {
 			"type": "object",

package/schemas/translations.schema.json

@@ -58,6 +58,13 @@
 				"$ref": "#/$defs/labelOnly"
 			}
 		},
+		"registers": {
+			"type": "object",
+			"description": "Register code (as registers.json keys it) → label and description.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelDesc"
+			}
+		},
 		"reports": {
 			"type": "object",
 			"description": "Report code → label, dataset captions and parameter labels.",

package/src/dsl/builtins.ts

@@ -1,6 +1,11 @@
 // The DSL's platform globals. Signatures and prose track
-// dforge-mcp/skills/dforge-mcp-author/references/action-dsl.md — that file is
-// the source of truth; re-sync when it changes.
+// skills/dforge-module-author/references/action-dsl.md — that file is the source
+// of truth; re-sync when it changes. (The path used to name a dforge-mcp
+// checkout, which this repo has no such directory for.)
+//
+// The list itself is pinned against the server's DslBuiltins.FunctionNames by
+// test/dsl-builtins.test.ts, in both directions: a builtin core defines and this
+// catalog omits is reported as dsl/unknown-builtin on correct code.
 
 export interface Builtin {
 	name: string;
@@ -71,6 +76,46 @@ export const BUILTINS: Builtin[] = [
 		doc: "Load the referenced record for a FK column. Read its fields with `ref.get('field')`.",
 	},
 
+	// Register reads. The first argument names a REGISTER (`module_cd.register_cd`,
+	// declared in that module's registers.json) and not an entity, so none of these
+	// carries `entityArg` — entity-code completion there would offer the wrong list.
+	{
+		name: "getBalance",
+		signature: "getBalance(register, dims?, asOf?)",
+		returns: "object",
+		doc: "Balance of an accumulation register per resource. A dimension left out of `dims` is summed over, so passing none gives the register's total. `asOf` reads as of a date instead of now.",
+	},
+	{
+		name: "getTurnover",
+		signature: "getTurnover(register, dims, from, to)",
+		returns: "object",
+		doc: "What moved through a register over an interval: `{in, out, net}` per resource. `dims` may be `null` to sum over every dimension; `from` and `to` are both required.",
+	},
+	{
+		name: "getSlice",
+		signature: "getSlice(register, dims, onDate?, mode?)",
+		returns: "object | null",
+		doc: "One record of an information register — the latest on or before `onDate`, or `null` when there is none. Returns the record plus `_period`. Unlike a balance, a dimension may NOT be omitted: a slice is one keyed record, not a sum.",
+	},
+	{
+		name: "getAccountBalance",
+		signature: "getAccountBalance(register, account, filter?, asOf?)",
+		returns: "object",
+		doc: "Balance of one account of an accounting register: `{debit, credit, net}` per resource. `filter` narrows by a dimension, or by an analytic kind the ACCOUNT declares — an analytic takes the key alone, or `{ entity, value }` to name one entity of a kind that is a union of several.",
+	},
+	{
+		name: "getAccountTurnover",
+		signature: "getAccountTurnover(register, account, filter, from, to)",
+		returns: "object",
+		doc: "What moved through one account over an interval: `{debit, credit, net}` per resource. `filter` narrows as in `getAccountBalance` and may be `null`; `from` and `to` are both required.",
+	},
+	{
+		name: "getCorrespondence",
+		signature: "getCorrespondence(register, debitAccount, creditAccount, filter, from, to)",
+		returns: "object",
+		doc: "What moved between two accounts over an interval. Needs `lineMode: \"compound\"` — a classic register records the other half of an entry as an untied second row and cannot answer this. `filter` narrows by dimensions the two sides share, never by an analytic (an analytic belongs to one account and this read names two).",
+	},
+
 	// Messaging
 	{
 		name: "error",

package/src/index.ts

@@ -148,7 +148,7 @@ export type {
 	SetSection,
 	TabGroupSection,
 } from "./card-layouts";
-export type { SeedDataFile } from "./seed-data";
+export type { SeedDataFile, SeedDataRepeat } from "./seed-data";
 export type { ActionsFile, ActionDef, ActionExecutionMode } from "./actions";
 
 // Flag catalog — the only letters valid on an authored column, at field level and

package/src/reports.ts

@@ -120,12 +120,33 @@ export interface ColumnDef {
 	width?: number;
 }
 
+/**
+ * An accounting register read over an interval: one row per account of the register's chart,
+ * with opening, turnover and closing debit/credit for one resource, netted per account.
+ */
+export interface RegisterSource {
+	/** The register, `module_cd.register_cd`. */
+	name: string;
+	/** The one resource the six balance columns are about. */
+	resource: string;
+	/** Two date params, or the record of `entity` a key param finds and its two date columns. */
+	interval: { entity?: string; key?: string; from: string; to: string };
+	/** Chart columns in nav notation, `<chart>.<column>`. */
+	columns?: string[];
+	/** A filter over the chart, in the same nav notation. */
+	filter?: Filter;
+	/** Chart columns to sort by, in nav notation. */
+	sort?: SortClause[];
+	/** The query rollup without `leafKey` and `measures`. */
+	rollup?: { tree: string; treeKey: string; parentField: string; labels: string[]; order?: string };
+}
+
 /** A report dataset (value in the report's `datasets` map). */
 export interface Dataset {
 	/** Display label (used in panel headings if no `title`). */
 	caption?: string;
-	/** Q = SQL/entity query, S = stored procedure. */
-	datasetType: "Q" | "S";
+	/** Q = SQL/entity query, S = stored procedure, R = an accounting register read over an interval. */
+	datasetType: "Q" | "S" | "R";
 	/** Used when `datasetType` is 'Q'. */
 	query?: ReportQuery;
 	/**
@@ -134,6 +155,8 @@ export interface Dataset {
 	 * and never schema-qualified. `module.spCd` binds a dependency's procedure.
 	 */
 	spCd?: string;
+	/** Used when `datasetType` is 'R'. */
+	register?: RegisterSource;
 	/** Optional column metadata overrides: field code → override. */
 	columnsDef?: Record<string, ColumnDef>;
 	/**
@@ -188,7 +211,9 @@ export interface ReportLayout {
 
 /** A single report (value in the `ui/reports.json` map). */
 export interface ReportDef {
-	/** Human-readable report title. */
+	/** Report name: page title, breadcrumb and menu entry. Omit and `description` is the name. */
+	label?: string;
+	/** What the report shows, under its name on the page. */
 	description: string;
 	layout: ReportLayout;
 	/** Dataset code → dataset definition. */

package/src/seed-data.ts

@@ -5,6 +5,14 @@
 export interface SeedDataFile {
 	/** Target entity code. */
 	entityCode: string;
-	/** Records to insert; each is a `column_code → value` map. */
+	/** Records to insert; each is a `column_code → value` map. In `demo-data/` a value may be `{ "$f": "<formula>" }`. */
 	records: Record<string, unknown>[];
+	/** `demo-data/` only: insert every record once per value of `@var`, `from`..`to` inclusive. */
+	repeat?: SeedDataRepeat;
+}
+
+export interface SeedDataRepeat {
+	var?: string;
+	from?: number;
+	to: number;
 }

package/src/settings.ts

@@ -3,12 +3,8 @@
 /** Underlying primitive datatype for a setting. */
 export type SettingBaseDatatype = "string" | "number" | "bool" | "date" | "dateTime" | "time" | "json";
 
-/** A single setting definition (value in the settings map). */
-export interface SettingDef {
-	/** Field type code (must match a `dforge.field_type` code). */
-	fieldTypeCd: string;
-	/** Underlying primitive datatype (older settings declare this explicitly). */
-	baseDatatypeCd?: SettingBaseDatatype;
+/** Properties carried by every setting regardless of where its control comes from. */
+export interface SettingDefBase {
 	/** Display label (preferred for new settings). */
 	label?: string;
 	/** Display label (older style). Prefer `label`. */
@@ -21,9 +17,26 @@ export interface SettingDef {
 	formula?: string;
 	/** If true, must be set somewhere in the folder chain for install to proceed. */
 	required?: boolean;
-	/** Field-type-specific parameters (dropdown options, min/max, lookup link, …). */
-	params?: Record<string, unknown>;
 }
 
+/** A setting declares its control inline or borrows it from a reusable column domain. */
+export type SettingDef =
+	| (SettingDefBase & {
+		/** Field type code (must match a `dforge.field_type` code). */
+		fieldTypeCd: string;
+		/** Underlying primitive datatype (older settings declare this explicitly). */
+		baseDatatypeCd?: SettingBaseDatatype;
+		/** Field-type-specific parameters (dropdown options, min/max, lookup link, …). */
+		params?: Record<string, unknown>;
+		domain?: never;
+	})
+	| (SettingDefBase & {
+		/** Column domain supplying fieldTypeCd, baseDatatypeCd and params. */
+		domain: string;
+		fieldTypeCd?: never;
+		baseDatatypeCd?: never;
+		params?: never;
+	});
+
 /** A `settings.json` file: setting code → definition. */
 export type SettingsFile = Record<string, SettingDef>;

package/src/stored-procedures.ts

@@ -72,4 +72,11 @@ export interface SpColumnDef {
 	width?: number;
 	/** Control parameters, the same shape an entity column's `params` takes. */
 	params?: Record<string, unknown>;
+	/**
+	 * Reusable column domain supplying the control, datatype and option list.
+	 * Unqualified resolves within this module, then tenant-created domains;
+	 * `module_cd.domain_cd` binds to that module. Mutually exclusive with
+	 * `fieldTypeCd`, `baseDatatypeCd` and `params`.
+	 */
+	domain?: string;
 }