@dforge-core/dforge-mcp 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -4,8 +4,25 @@ All notable changes to `@dforge-core/dforge-mcp`. This project uses semver-ish
 `0.1.0-rc.N` pre-release tags; the published version is set at publish time via
 the release workflow, so committed `package.json` versions are placeholders.
 
+## 0.1.5
+
+### Changed
+- Bumped `@dforge-core/metadata` to `^0.0.5`. The re-vendored `reports.schema.json`
+  now **structurally validates** KPI and chart panel `config` (previously an
+  unvalidated object, so `dforge_module_validate` only checked `vizType`):
+  aggregation-vs-formula KPI metrics are mutually exclusive and non-empty; formula
+  inputs and chart overlay `series` are shape-checked; charts require
+  `chartType`/`categoryCol`/`valueCol`.
+
 ## 0.1.3
 
+### Changed
+- Bumped the `@dforge-core/metadata` dependency to `^0.0.4` so the publish-time
+  schema vendoring (`prepublishOnly` → `vendor-schemas`) picks up the refreshed
+  `reports.schema.json` (`vizType: "kpi"` + KPI formula / cross-source config).
+  The vendored copy under `resources/schemas/` is regenerated on publish — it is
+  not hand-edited.
+
 ### Added
 - **Cross-source report metrics & charts (schema).** `reports.schema.json` now
   lists `kpi` as a `vizType` (was `metric`) and documents the two config shapes

package/dist/server.js

@@ -31155,6 +31155,7 @@ var fieldTypes = [
   { 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: "list", name: "Detail List", 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 }
@@ -31219,8 +31220,8 @@ var traits = [
     cd: "audit",
     description: "Creation and update timestamps",
     fields: {
-      created_date: { dbDatatype: "timestamptz", fieldTypeCd: "datetime", flags: "I", isNullable: false, formula: "NOW()", orderNum: 9901, description: "Created Date" },
-      last_updated: { dbDatatype: "timestamptz", fieldTypeCd: "datetime", flags: "I", isNullable: false, formula: "NOW()", orderNum: 9902, description: "Last Updated" }
+      created_date: { dbDatatype: "timestamptz", fieldTypeCd: "datetime", flags: "I", isNullable: false, orderNum: 9901, description: "Created Date", params: { serverDefault: { value: "now()", on: "insert" } } },
+      last_updated: { dbDatatype: "timestamptz", fieldTypeCd: "datetime", flags: "I", isNullable: false, orderNum: 9902, description: "Last Updated", params: { serverDefault: { value: "now()", on: "save" } } }
     }
   },
   {
@@ -31228,9 +31229,9 @@ var traits = [
     description: "Full audit with user tracking",
     includes: ["audit"],
     fields: {
-      created_by: { dbDatatype: "cuid", flags: "I", isNullable: false, orderNum: 9903, description: "Created By User ID" },
+      created_by: { dbDatatype: "cuid", flags: "I", isNullable: false, orderNum: 9903, description: "Created By User ID", params: { serverDefault: { value: "currentUser()", on: "insert" } } },
       created_by_user: { columnType: "R", fieldTypeCd: "lookup", flags: "I", orderNum: 9904, description: "Created By", link: { entity: "user", thisKey: "created_by", otherKey: "user_id" } },
-      last_updated_by: { dbDatatype: "cuid", flags: "I", isNullable: false, orderNum: 9905, description: "Last Updated By User ID" },
+      last_updated_by: { dbDatatype: "cuid", flags: "I", isNullable: false, orderNum: 9905, description: "Last Updated By User ID", params: { serverDefault: { value: "currentUser()", on: "save" } } },
       last_updated_by_user: { columnType: "R", fieldTypeCd: "lookup", flags: "I", orderNum: 9906, description: "Last Updated By", link: { entity: "user", thisKey: "last_updated_by", otherKey: "user_id" } }
     },
     references: {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.3",
+	"version": "0.1.5",
 	"description": "MCP server for dForge module authoring. Exposes scaffold/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
 	"license": "MIT",
 	"homepage": "https://github.com/iash44/dForge-core",
@@ -32,7 +32,7 @@
 	},
 	"dependencies": {
 		"@dforge-core/dforge-cli": "^0.2.2",
-		"@dforge-core/metadata": "^0.0.2",
+		"@dforge-core/metadata": "^0.0.5",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"zod": "^4.4.3"
 	},

package/resources/schemas/data-views.schema.json

@@ -10,12 +10,13 @@
 	"$defs": {
 		"dataView": {
 			"type": "object",
-			"required": ["viewType", "dataSources"],
+			"required": ["dataSources"],
 			"properties": {
 				"viewType": {
 					"type": "string",
-					"enum": ["grid", "list", "kanban", "calendar", "gallery", "tree-grid", "diagram", "master-detail", "library"],
-					"description": "View display type"
+					"enum": ["grid", "list", "kanban", "calendar", "gallery", "tree-grid", "diagram", "master-detail", "library", "matrix"],
+					"default": "grid",
+					"description": "View display type. Optional — omitted or unknown values fall back to 'grid' at runtime."
 				},
 				"label": {
 					"type": "string",
@@ -56,7 +57,8 @@
 				{ "$ref": "#/$defs/rules/tree-grid" },
 				{ "$ref": "#/$defs/rules/list" },
 				{ "$ref": "#/$defs/rules/diagram" },
-				{ "$ref": "#/$defs/rules/master-detail" }
+				{ "$ref": "#/$defs/rules/master-detail" },
+				{ "$ref": "#/$defs/rules/matrix" }
 			]
 		},
 
@@ -126,6 +128,18 @@
 						"dataSources": { "minItems": 2 }
 					}
 				}
+			},
+			"matrix": {
+				"if": {
+					"properties": { "viewType": { "const": "matrix" } },
+					"required": ["viewType"]
+				},
+				"then": {
+					"properties": {
+						"viewConfig": { "$ref": "#/$defs/matrixViewConfig" }
+					},
+					"required": ["viewConfig"]
+				}
 			}
 		},
 
@@ -233,6 +247,163 @@
 			"additionalProperties": false
 		},
 
+		"matrixViewConfig": {
+			"type": "object",
+			"description": "Matrix (pivot) view: rowAxis × colAxis grid with a value-source cell entity holding one record per (rowKey, colKey).",
+			"required": ["rowAxis", "colAxis", "cell"],
+			"properties": {
+				"rowAxis": {
+					"description": "Row axis values: an entity's records ('dataset') or a column's dropdown options ('dropdown').",
+					"oneOf": [
+						{ "$ref": "#/$defs/matrixDatasetAxis" },
+						{ "$ref": "#/$defs/matrixDropdownAxis" }
+					]
+				},
+				"colAxis": {
+					"description": "Column axis values: 'dataset', 'dropdown', or a generated 'date' window.",
+					"oneOf": [
+						{ "$ref": "#/$defs/matrixDatasetAxis" },
+						{ "$ref": "#/$defs/matrixDropdownAxis" },
+						{ "$ref": "#/$defs/matrixDateAxis" }
+					]
+				},
+				"cell": { "$ref": "#/$defs/matrixCellConfig" }
+			},
+			"additionalProperties": false
+		},
+		"matrixDatasetAxis": {
+			"type": "object",
+			"description": "Dataset axis — axis values are the records of an entity.",
+			"required": ["kind", "entity", "labelField"],
+			"properties": {
+				"kind": { "const": "dataset" },
+				"entity": {
+					"type": "string",
+					"description": "Axis-source entity code (e.g. 'account', 'accounting_period')"
+				},
+				"labelField": {
+					"type": "string",
+					"description": "Column shown as the axis header label"
+				},
+				"keyField": {
+					"type": "string",
+					"description": "Column whose value is the match key. Defaults to the axis entity's PK."
+				},
+				"lockedField": {
+					"type": "string",
+					"description": "Boolean column; when true, that axis value's cells are read-only even in edit mode (e.g. a period's 'closed' flag)"
+				},
+				"filter": {
+					"$ref": "#/$defs/filter",
+					"description": "Optional filter scoping which axis records load (e.g. row axis scoped to 'statement == IncomeStatement')"
+				},
+				"hideEmpty": {
+					"type": "boolean",
+					"description": "COLUMN axis only — hide axis values that have no cell record in any row (e.g. periods with no posted activity), so a P&L doesn't trail off into empty months. Data-driven and reactive; ignored if it would hide every column."
+				},
+				"rangeControl": {
+					"type": "boolean",
+					"description": "COLUMN axis only — show a From/To range control above the matrix so the user can narrow the visible columns to a span (e.g. a quarter or a single year of periods). The chosen span persists in the view options and composes with hideEmpty."
+				},
+				"sort": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/matrixAxisSort" },
+					"description": "Sort applied to the axis records"
+				}
+			},
+			"additionalProperties": false
+		},
+		"matrixDropdownAxis": {
+			"type": "object",
+			"description": "Dropdown axis — axis values are the options of a dropdown/flags column, read from its params.options.",
+			"required": ["kind", "column"],
+			"properties": {
+				"kind": { "const": "dropdown" },
+				"column": {
+					"type": "string",
+					"description": "'entity.column' reference to a dropdown/flags column whose options are the axis"
+				},
+				"values": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Optional subset + order of option values to render as columns (the option 'value' codes), the way kanban lanes are chosen. Omit to show every option in field order; values not matching an option are ignored."
+				}
+			},
+			"additionalProperties": false
+		},
+		"matrixDateAxis": {
+			"type": "object",
+			"description": "Date axis — axis values generated from a date window rather than entity records. Column axis only.",
+			"required": ["kind", "grain", "window"],
+			"properties": {
+				"kind": { "const": "date" },
+				"grain": {
+					"const": "day",
+					"description": "Column granularity. v1: 'day'."
+				},
+				"window": {
+					"const": "week",
+					"description": "How many columns are shown. v1: 'week' (7 days, Monday-start)."
+				}
+			},
+			"additionalProperties": false
+		},
+		"matrixAxisSort": {
+			"type": "object",
+			"required": ["col"],
+			"properties": {
+				"col": { "type": "string", "description": "Axis-entity column to sort by" },
+				"dir": { "type": "string", "enum": ["asc", "desc"], "description": "Sort direction (defaults to 'asc')" }
+			},
+			"additionalProperties": false
+		},
+		"matrixCellConfig": {
+			"type": "object",
+			"description": "The value-source cell of a matrix — one record per (rowKey, colKey).",
+			"required": ["entity", "rowKey", "colKey", "fields"],
+			"properties": {
+				"entity": {
+					"type": "string",
+					"description": "Cell entity code (the view's primary data source)"
+				},
+				"rowKey": {
+					"type": "string",
+					"description": "Cell column matching the row axis key"
+				},
+				"colKey": {
+					"type": "string",
+					"description": "Cell column matching the column axis key"
+				},
+				"fields": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Cell columns rendered inside each cell, in order"
+				},
+				"cardinality": {
+					"const": "one",
+					"description": "v1 supports a single record per cell"
+				},
+				"editable": {
+					"type": "boolean",
+					"description": "Whether cells edit in place"
+				},
+				"drill": {
+					"type": "boolean",
+					"description": "When true, read-only cell values become clickable and open the cell's record (where its child sets are shown)"
+				},
+				"seedFromRow": {
+					"type": "object",
+					"additionalProperties": { "type": "string" },
+					"description": "On empty-cell insert, copy values from the row axis record into the new cell record: { cellField: rowAxisField }"
+				},
+				"seedCurrentUser": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "On empty-cell insert, set these cell fields to the current user id"
+				}
+			},
+			"additionalProperties": false
+		},
 		"viewColumn": {
 			"oneOf": [
 				{

package/resources/schemas/deps.schema.json

@@ -0,0 +1,84 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/deps.schema.json",
+	"title": "dForge Module Dependency Contract",
+	"description": "Declares everything a consumer module consumes from one dependency: the entities, columns (with base datatype), and the provenance of each usage. One file per dependency at modules/<consumer>/deps/<provider>.json. The dependency is the source of truth; this file is the consumer's import list. See docs/modules/dependency-contracts.md.",
+	"type": "object",
+	"required": ["module", "version", "entities"],
+	"additionalProperties": false,
+	"properties": {
+		"module": {
+			"type": "string",
+			"description": "Code of the dependency (provider) module this contract is against (e.g. 'parties'). Matches a key in the consumer manifest's 'dependencies'."
+		},
+		"version": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Semver range the consumer requires of the provider (e.g. '>=0.1.0'). Should agree with the consumer manifest's dependency range for this module."
+		},
+		"entities": {
+			"type": "object",
+			"description": "Consumed provider entities, keyed by entity code (e.g. 'party').",
+			"minProperties": 1,
+			"additionalProperties": { "$ref": "#/definitions/entityContract" }
+		}
+	},
+	"definitions": {
+		"entityContract": {
+			"type": "object",
+			"required": ["pk", "use"],
+			"additionalProperties": false,
+			"description": "What the consumer needs from one provider entity.",
+			"properties": {
+				"pk": {
+					"type": "string",
+					"description": "The provider entity's primary-key column — the structural anchor every reference into the entity joins on. Note: the label/display column is NOT declared (display is the provider's concern, resolved from its toString)."
+				},
+				"use": {
+					"$ref": "#/definitions/provenanceList",
+					"description": "Entity-level provenance: why this entity is consumed (a ref targets it, the consumer extends it, a role grants on it, a view/report/print/action touches it)."
+				},
+				"columns": {
+					"type": "object",
+					"description": "Provider columns the consumer actually reads, writes, or joins on. Omit entirely for extension-only targets that touch no existing provider column.",
+					"additionalProperties": { "$ref": "#/definitions/columnContract" }
+				}
+			}
+		},
+		"columnContract": {
+			"type": "object",
+			"required": ["type", "use"],
+			"additionalProperties": false,
+			"description": "A single consumed provider column.",
+			"properties": {
+				"type": {
+					"type": "string",
+					"enum": ["int2", "int4", "int8", "smallint", "integer", "bigint", "numeric", "decimal", "float4", "float8", "real", "money", "varchar", "text", "char", "bpchar", "bool", "boolean", "date", "time", "timetz", "timestamp", "timestamptz", "uuid", "json", "jsonb", "bytea"],
+					"description": "The provider column's STORAGE CLASS — its physical Postgres type with any length/scale stripped (int8, varchar, numeric, bool, date, timestamptz, jsonb, ...). Mirrors DdlService.ResolveDbType: dForge's 'cuid' Snowflake PK normalizes to int8 (use 'int8', not 'cuid'); varchar(n) -> varchar; fieldTypeCd 'currency'/'percent' -> numeric; 'number' -> int4. Pin the storage class (not a coarse base type) so an FK/lookup is meaningful: an int8 key is satisfiable by int8, not by any 'number'. The satisfaction check compares via EntityValidator.AreTypesCompatible (varchar==text, int8==bigint). This enum is a closed allowlist to catch typos at author time; extend it (and DependencyContractValidator.ValidColumnTypes, kept in lockstep) if a provider column legitimately uses a type not listed."
+				},
+				"use": {
+					"$ref": "#/definitions/provenanceList",
+					"description": "Per-column provenance: which symbols read/write/join on this column."
+				},
+				"mode": {
+					"type": "string",
+					"enum": ["read", "write"],
+					"default": "read",
+					"description": "Whether the consumer reads or writes this column. 'write' (e.g. an action that inserts/updates the provider row) additionally implies an insert/update right and a settable column. Default 'read'; omit for reads."
+				}
+			}
+		},
+		"provenanceList": {
+			"type": "array",
+			"minItems": 1,
+			"uniqueItems": true,
+			"description": "One or more usage tokens. Each names the consuming symbol so the completeness lint can reconcile declared usage against actual usage.",
+			"items": { "$ref": "#/definitions/provenance" }
+		},
+		"provenance": {
+			"type": "string",
+			"pattern": "^(extends:[^.]+\\.[^.]+|(ref|formula|action|view|report|print|role):.+)$",
+			"description": "A usage token of the form '<kind>:<symbol>'. Kinds: ref:<entity.column> (a link column joins to the dependency; the entity is qualified <module>.<entity> when it's an extension host), extends:<module.entity> (the consumer extends the provider entity — MUST be fully qualified, e.g. extends:parties.party, never bare extends:party), formula:<entity.column> (a formula nav path reads it), action:<action_cd> (DSL reads/writes it, incl. raw query() SQL), view:<view_cd> (a data view's dataSource targets it), report:<report_cd> (a report queries it), print:<template_cd> (a print template navigates into it), role:<role_cd> (a security role grants rights on the entity). Note: 'display' is intentionally NOT a kind — the label is the provider's concern."
+		}
+	}
+}

package/resources/schemas/entity.schema.json

@@ -4,12 +4,15 @@
 	"title": "dForge Entity Definition",
 	"description": "Defines an entity (table/view mapping) for a dForge module",
 	"type": "object",
-	"required": ["fields"],
+	"anyOf": [
+		{ "required": ["fields"] },
+		{ "required": ["traits"] }
+	],
 	"properties": {
 		"extends": {
 			"type": "string",
-			"pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$",
-			"description": "Qualified entity code of the target entity to extend (e.g. 'fin.invoice'). When set, this entity definition adds columns to an existing entity owned by another module instead of creating a new entity. Physical columns are stored in a 1:1 extension table."
+			"pattern": "^[a-z][a-z0-9_-]*\\.[a-z][a-z0-9_]*$",
+			"description": "Qualified entity code of the target entity to extend, as '<module>.<entity>' (e.g. 'fin.invoice' or 'cdy-tax.tax_invoice_issued_line'). The module part may contain hyphens (module codes are hyphenated, e.g. 'crm-fin'); the entity part is snake_case. When set, this entity definition adds columns to an existing entity owned by another module instead of creating a new entity. Physical columns are stored in a 1:1 extension table."
 		},
 		"description": {
 			"type": "string",
@@ -180,10 +183,10 @@
 									{ "type": "string" },
 									{
 										"type": "object",
-										"required": ["value", "label"],
+										"required": ["value"],
 										"properties": {
 											"value": { "type": "string" },
-											"label": { "type": "string" },
+											"label": { "type": "string", "description": "Display text. Optional — the runtime falls back to `value` when omitted (column.ts: label = o.label ?? value)." },
 											"icon": { "type": "string" },
 											"color": { "type": "string" }
 										},
@@ -192,6 +195,9 @@
 								]
 							},
 							"description": "Options for dropdown/flags field types"
+						},
+						"serverDefault": {
+							"$ref": "#/$defs/serverDefault"
 						}
 					}
 				},
@@ -309,6 +315,30 @@
 			},
 			"additionalProperties": false
 		},
+		"serverDefault": {
+			"type": "object",
+			"description": "Platform-computed value filled server-side on write (used by the audit / audit-full traits). Resolved by the write pipeline (data.insert/update and DSL insert/update) — not a formula.",
+			"required": ["value"],
+			"properties": {
+				"value": {
+					"type": "string",
+					"enum": ["now()", "currentUser()"],
+					"description": "Whitelisted server-context expression: now() → transaction clock, currentUser() → caller's user id."
+				},
+				"on": {
+					"type": "string",
+					"enum": ["insert", "update", "save"],
+					"default": "insert",
+					"description": "Phase(s) in which the value is applied. 'save' = both insert and update."
+				},
+				"ifEmpty": {
+					"type": "boolean",
+					"default": false,
+					"description": "When true, only fill if the caller did not provide a value; when false (default), always override."
+				}
+			},
+			"additionalProperties": false
+		},
 		"numberSequence": {
 			"type": "object",
 			"description": "Automatic document numbering. Auto-generates a formatted number on INSERT when the target column is empty.",

package/resources/schemas/manifest.schema.json

@@ -18,8 +18,10 @@
 		},
 		"code": {
 			"type": "string",
-			"pattern": "^[a-z][a-z0-9_-]*$",
-			"description": "Human-readable module code (becomes schema name and module_cd in DB)"
+			"minLength": 2,
+			"maxLength": 64,
+			"pattern": "^[a-z][a-z0-9]*([._-][a-z0-9]+)*$",
+			"description": "Module code — becomes the schema name and module_cd in DB, and the public marketplace slug. Lowercase letters and digits, with single '.', '-', or '_' separators (no consecutive, leading, or trailing separator); 2–64 chars, must start with a letter and end alphanumeric. Mirrors the marketplace publish validator (ModulePublishService.ModuleCodePattern)."
 		},
 		"kind": {
 			"type": "string",

package/resources/schemas/reports.schema.json

@@ -51,8 +51,8 @@
 			"properties": {
 				"vizType": {
 					"type": "string",
-					"enum": ["table", "chart", "metric", "pivot"],
-					"description": "Visualization type"
+					"enum": ["table", "chart", "kpi", "pivot", "tree", "markdown"],
+					"description": "Visualization type. For any chart the vizType is `chart`; the chart kind goes in `config.chartType`."
 				},
 				"datasetCd": {
 					"type": "string",
@@ -61,9 +61,142 @@
 				"title": { "type": "string" },
 				"config": {
 					"type": "object",
-					"description": "Viz-type-specific configuration. For chart: { chartType, categoryCol, valueCol, agg, chartSize }. For table: { groupRules, aggregations }."
+					"description": "Viz-type-specific configuration. `kpi` and `chart` are structurally validated (see kpiConfig / chartConfig below); `table`/`pivot`/`tree`/`markdown` accept any object."
 				}
 			},
+			"additionalProperties": false,
+			"allOf": [
+				{
+					"if": { "required": ["vizType"], "properties": { "vizType": { "const": "kpi" } } },
+					"then": { "properties": { "config": { "$ref": "#/$defs/kpiConfig" } } }
+				},
+				{
+					"if": { "required": ["vizType"], "properties": { "vizType": { "const": "chart" } } },
+					"then": { "properties": { "config": { "$ref": "#/$defs/chartConfig" } } }
+				}
+			]
+		},
+
+		"aggFunc": {
+			"type": "string",
+			"enum": ["sum", "avg", "min", "max", "count"],
+			"description": "Aggregation function."
+		},
+
+		"kpiConfig": {
+			"type": "object",
+			"description": "KPI panel config: one or more metric cards.",
+			"required": ["metrics"],
+			"properties": {
+				"metrics": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "$ref": "#/$defs/kpiMetric" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"kpiMetric": {
+			"type": "object",
+			"description": "A KPI metric — EITHER an aggregation metric (`column` + `agg`, and no formula/inputs) OR a formula metric (`formula` + `inputs`, and no column/agg).",
+			"properties": {
+				"column": { "type": "string", "description": "Column to aggregate (aggregation metric)." },
+				"agg": { "$ref": "#/$defs/aggFunc" },
+				"formula": { "type": "string", "description": "Expression over `[alias]` inputs, e.g. '[won] / [all] * 100' (formula metric)." },
+				"inputs": {
+					"type": "array",
+					"minItems": 1,
+					"description": "Named aggregation inputs the formula references by `[alias]`.",
+					"items": { "$ref": "#/$defs/kpiInput" }
+				},
+				"format": { "$ref": "#/$defs/metricFormat" },
+				"display": { "type": "string", "enum": ["value", "gauge", "progress", "sparkline", "icon"] },
+				"label": { "type": "string" },
+				"target": { "type": "number" },
+				"min": { "type": "number" },
+				"max": { "type": "number" },
+				"icon": { "type": "string" },
+				"sparklineDimension": { "type": "string" }
+			},
+			"additionalProperties": false,
+			"allOf": [
+				{
+					"if": { "required": ["formula"] },
+					"then": {
+						"required": ["formula", "inputs"],
+						"not": { "anyOf": [ { "required": ["column"] }, { "required": ["agg"] } ] }
+					},
+					"else": {
+						"required": ["column", "agg"],
+						"not": { "anyOf": [ { "required": ["formula"] }, { "required": ["inputs"] } ] }
+					}
+				}
+			]
+		},
+
+		"kpiInput": {
+			"type": "object",
+			"description": "One named aggregation a formula metric references by `[alias]`.",
+			"required": ["alias", "column", "agg"],
+			"properties": {
+				"alias": { "type": "string", "description": "Token used in the formula as `[alias]`." },
+				"column": { "type": "string" },
+				"agg": { "$ref": "#/$defs/aggFunc" },
+				"source": { "type": "string", "description": "Sibling dataset code to aggregate over (CROSS-DATASET); omit = the panel's own dataset." }
+			},
+			"additionalProperties": false
+		},
+
+		"metricFormat": {
+			"type": "object",
+			"description": "Formula-result format. OMIT for Auto — inherits the first input column's own formatter (currency/grouping).",
+			"properties": {
+				"style": { "type": "string", "enum": ["number", "percent"] },
+				"decimals": { "type": "integer", "minimum": 0 }
+			},
+			"additionalProperties": false
+		},
+
+		"chartConfig": {
+			"type": "object",
+			"description": "Chart panel config. The chart kind is `chartType`; the panel `vizType` is always `chart`.",
+			"required": ["chartType", "categoryCol", "valueCol"],
+			"properties": {
+				"chartType": {
+					"type": "string",
+					"enum": ["bar", "horizontalBar", "stackedBar", "combo", "line", "area", "pie", "doughnut", "scatter", "bubble", "funnel", "heatmap"]
+				},
+				"categoryCol": { "type": "string" },
+				"valueCol": { "type": "string" },
+				"agg": { "$ref": "#/$defs/aggFunc" },
+				"seriesCol": { "type": "string", "description": "Split-by dimension (same dataset)." },
+				"sizeCol": { "type": "string", "description": "Bubble radius column." },
+				"chartSize": { "type": "string", "enum": ["sm", "m", "l", "xl"] },
+				"clickAction": { "type": "string", "enum": ["crossFilter", "drillThrough", "none"] },
+				"showTrend": { "type": "boolean" },
+				"series": {
+					"description": "CROSS-SOURCE overlay series (bar/horizontalBar/line/area) — a single series OR an array. Each aligns on the shared category axis.",
+					"oneOf": [
+						{ "$ref": "#/$defs/chartSeries" },
+						{ "type": "array", "items": { "$ref": "#/$defs/chartSeries" } }
+					]
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"chartSeries": {
+			"type": "object",
+			"description": "One cross-source overlay series.",
+			"required": ["categoryCol", "valueCol", "agg"],
+			"properties": {
+				"source": { "type": "string", "description": "Sibling dataset code; omit = the panel's own dataset." },
+				"categoryCol": { "type": "string" },
+				"valueCol": { "type": "string" },
+				"agg": { "$ref": "#/$defs/aggFunc" },
+				"label": { "type": "string" }
+			},
 			"additionalProperties": false
 		},
 
@@ -121,11 +254,40 @@
 				"sort": {
 					"type": "array",
 					"items": { "$ref": "#/$defs/sortClause" }
+				},
+				"rollup": {
+					"$ref": "#/$defs/rollup"
 				}
 			},
 			"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.",
+			"required": ["tree", "treeKey", "parentField", "leafKey", "measures", "labels"],
+			"properties": {
+				"tree": { "type": "string", "description": "Entity code that owns the hierarchy (e.g. 'account')." },
+				"treeKey": { "type": "string", "description": "Primary-key column of the tree entity (e.g. 'account_id')." },
+				"parentField": { "type": "string", "description": "Self-referencing parent FK on the tree entity; roots have it NULL (e.g. 'parent_account_id')." },
+				"leafKey": { "type": "string", "description": "Column on the query entity identifying the tree node a row belongs to (e.g. 'account_id' on balance_register)." },
+				"measures": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "type": "string" },
+					"description": "Value column codes (on the query entity) to SUM into ancestors. Must be additively-rollable."
+				},
+				"labels": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "type": "string" },
+					"description": "Node-describing columns, expressed as the report column keys ('account.account_code'). Sourced from the tree entity's physical column (the segment after the dot); emitted under the same key so the report layout is unchanged."
+				},
+				"order": { "type": "string", "description": "Tree-entity column code for pre-order sort (e.g. 'account_code'), resolved through metadata to its physical column. Assumes hierarchy-sortable codes; defaults to treeKey." }
+			},
+			"additionalProperties": false
+		},
+
 		"sortClause": {
 			"type": "object",
 			"required": ["c"],

package/resources/schemas/traits.schema.json

@@ -66,6 +66,38 @@
 					},
 					"required": ["entity", "thisKey", "otherKey"],
 					"additionalProperties": false
+				},
+				"params": {
+					"type": "object",
+					"description": "Field-type-specific configuration; same shape as entity field params (e.g. serverDefault).",
+					"properties": {
+						"serverDefault": { "$ref": "#/$defs/serverDefault" }
+					},
+					"additionalProperties": true
+				}
+			},
+			"additionalProperties": false
+		},
+		"serverDefault": {
+			"type": "object",
+			"description": "Platform-computed value filled server-side on write (used by the audit / audit-full traits). Resolved by the write pipeline — not a formula.",
+			"required": ["value"],
+			"properties": {
+				"value": {
+					"type": "string",
+					"enum": ["now()", "currentUser()"],
+					"description": "Whitelisted server-context expression: now() → transaction clock, currentUser() → caller's user id."
+				},
+				"on": {
+					"type": "string",
+					"enum": ["insert", "update", "save"],
+					"default": "insert",
+					"description": "Phase(s) in which the value is applied. 'save' = both insert and update."
+				},
+				"ifEmpty": {
+					"type": "boolean",
+					"default": false,
+					"description": "When true, only fill if the caller did not provide a value; when false (default), always override."
 				}
 			},
 			"additionalProperties": false