@dforge-core/metadata 0.0.32 → 0.0.34

package/schemas/translations.schema.json

@@ -32,9 +32,9 @@
 		},
 		"views": {
 			"type": "object",
-			"description": "Data view code → label.",
+			"description": "Data view code → label and description (the subtitle under the view title).",
 			"additionalProperties": {
-				"$ref": "#/$defs/labelOnly"
+				"$ref": "#/$defs/labelDesc"
 			}
 		},
 		"menus": {

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/entity.ts

@@ -162,12 +162,8 @@ export interface EntityDef {
 	description?: string;
 	/** Database schema name override (defaults to module schema). */
 	schema?: string;
-	/** Database table/view name (defaults to entity code). */
+	/** Database table 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;
 	/** Audit trail level; overrides the manifest's `auditHistory`. */
@@ -191,9 +187,8 @@ export interface EntityDef {
 	params?: { restricted?: boolean } & Record<string, unknown>;
 	/**
 	 * Entity views keyed by view name — the platform's column-level security.
-	 * Unrelated to `isView`/`viewSql` above (a SQL-view-backed entity) and to
-	 * `ui/data_views.json` (grids, kanban, calendars), both of which the word
-	 * "view" also names in this platform. A
+	 * Unrelated to `ui/data_views.json` (grids, kanban, calendars), which the
+	 * word "view" also names in this platform. A
 	 * folder binds one view per entity through `ui/folders.json`
 	 * (`entities.<code>.viewName`); users working in that folder see ONLY the
 	 * columns the view lists. An entity without views (or a folder naming the

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/translations.ts

@@ -47,7 +47,7 @@ export interface TranslationsFile {
 	domains?: Record<string, TranslatedWithOptions>;
 	/** Folder code (flat, not the path) → label. */
 	folders?: Record<string, { label?: string }>;
-	views?: Record<string, { label?: string }>;
+	views?: Record<string, { label?: string; desc?: string }>;
 	menus?: Record<string, TranslatedMenu>;
 	settings?: Record<string, { label?: string; desc?: string }>;
 	/** Module-qualified role code → label. */