@dforge-core/metadata 0.0.33 → 0.0.34

package/schemas/reports.schema.json

@@ -12,9 +12,13 @@
 			"type": "object",
 			"required": ["description", "layout", "datasets"],
 			"properties": {
+				"label": {
+					"type": "string",
+					"description": "Report name: the page title, breadcrumb and parameter dialog. Recommended: without it the description is the name, and module pack, validate and install warn"
+				},
 				"description": {
 					"type": "string",
-					"description": "Human-readable report title"
+					"description": "What the report shows, under its name on the page. The name too when label is omitted"
 				},
 				"layout": {
 					"$ref": "#/$defs/layout"
@@ -242,8 +246,8 @@
 				},
 				"datasetType": {
 					"type": "string",
-					"enum": ["Q", "S"],
-					"description": "Q = SQL/entity query, S = stored procedure"
+					"enum": ["Q", "S", "R"],
+					"description": "Q = SQL/entity query, S = stored procedure, R = an accounting register read over an interval"
 				},
 				"query": {
 					"$ref": "#/$defs/query",
@@ -253,6 +257,10 @@
 					"type": "string",
 					"description": "Used when datasetType is 'S': the stored-procedure code, as `logic/stored_procedures.json` keys it — NOT the PostgreSQL function name and never schema-qualified. `module.spCd` binds a dependency's procedure. Resolved to `report_ds.sp_id` at install. A role granting `report:<code>` must also grant `sp:<spCd>`, which no admin UI can add afterwards."
 				},
+				"register": {
+					"$ref": "#/$defs/registerSource",
+					"description": "Used when datasetType is 'R'"
+				},
 				"columnsDef": {
 					"type": "object",
 					"description": "Optional column metadata overrides: field code → { label, visible, ... }",
@@ -294,6 +302,63 @@
 			"additionalProperties": false
 		},
 
+		"registerSource": {
+			"type": "object",
+			"description": "An accounting register read over an interval: one row per account of the register's chart, with opening_debit, opening_credit, turnover_debit, turnover_credit, closing_debit and closing_credit for one resource. Balances are netted per account — shown on the side they fall on. Whole periods are read from the register's totals cache, the part-periods at the edges from its postings. Needs Select on the register's posting entity and on the chart.",
+			"required": ["name", "resource", "interval"],
+			"properties": {
+				"name": {
+					"type": "string",
+					"pattern": "^[^.]+\\.[^.]+$",
+					"description": "The register, `module_cd.register_cd`. This module's own, or a declared dependency's. It must be an accounting register."
+				},
+				"resource": {
+					"type": "string",
+					"description": "The one resource the six balance columns are about."
+				},
+				"interval": {
+					"type": "object",
+					"description": "The days read between, both inclusive: two date params (`from` / `to` as `@param`), or the record of `entity` a key param finds (`key` as `@param`) with `from` / `to` naming its two date columns.",
+					"required": ["from", "to"],
+					"properties": {
+						"entity": { "type": "string", "description": "Entity holding the interval, e.g. an accounting period." },
+						"key": { "type": "string", "pattern": "^@.+", "description": "Param holding that entity's key." },
+						"from": { "type": "string", "description": "`@param`, or the entity's first-day column." },
+						"to": { "type": "string", "description": "`@param`, or the entity's last-day column." }
+					},
+					"additionalProperties": false
+				},
+				"columns": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Columns to show, in order: chart columns in nav notation, `<chart>.<column>` (e.g. 'account.account_code'), and any of the six balance columns, bare. Naming no balance column shows all six; a rollup always emits all six."
+				},
+				"filter": {
+					"$ref": "#/$defs/filter",
+					"description": "A filter over the chart, in the same nav notation; `@param` values allowed."
+				},
+				"sort": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/sortClause" },
+					"description": "Chart columns to sort by, in nav notation. Ignored under a rollup, which sorts by its tree."
+				},
+				"rollup": {
+					"type": "object",
+					"description": "The query rollup without 'leafKey' and 'measures': the rows are accounts and the six balance columns are the measures.",
+					"required": ["tree", "treeKey", "parentField", "labels"],
+					"properties": {
+						"tree": { "type": "string" },
+						"treeKey": { "type": "string" },
+						"parentField": { "type": "string" },
+						"labels": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+						"order": { "type": "string" }
+					},
+					"additionalProperties": false
+				}
+			},
+			"additionalProperties": false
+		},
+
 		"rollup": {
 			"type": "object",
 			"description": "Hierarchy rollup: roll the flat leaf result up a self-referencing tree so parent rows carry the SUM of their descendants. Emits one row per tree node (leaf + ancestor), plus '_level' (depth from root) and '_isLeaf'. Measures must be additively-rollable (physical additive columns or LINEAR formulas of them, e.g. closing = opening + turnover); non-linear measures (ratios, products) are not valid and need a computed-row feature instead.",
@@ -354,7 +419,7 @@
 				},
 				"domain": {
 					"type": "string",
-					"description": "Column domain (`domain_cd` or `module_cd.domain_cd`) the parameter borrows its control and option list from. The options and their translations stay on the domain, so a list shared with an entity column is authored once. The DSL equivalent for action params is `paramCd: domain <domainCd>`.",
+					"description": "Column domain the parameter borrows its control and option list from. 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 options and their translations stay on the domain, so a list shared with an entity column is authored once. The DSL equivalent for action params is `paramCd: domain <domainCd>`.",
 					"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*(\\.[a-zA-Z_][a-zA-Z0-9_]*)?$"
 				},
 				"label": { "type": "string" },

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/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/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>;