@dforge-core/dforge-mcp 0.2.33 → 0.2.35

package/resources/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/resources/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/resources/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/resources/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/resources/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/resources/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/skills/dforge-mcp-author/references/action-dsl.md

@@ -348,7 +348,7 @@ error('Insufficient stock. Available: {available}, requested: {requested}',
 | Function | Returns | Description |
 |---|---|---|
 | `now()` | DateTime | Current date/time. Use for `date`, `datetime`, and `timestamp` fields. **Lowercase** — this is the execute-block date function. |
-| `addDays(date, n)` | Date | Add `n` days to a date, e.g. `addDays(now(), 30)`. |
+| `addDays(date, n)` | Same as `date` | Add `n` days to a date field, a `Date` or an ISO string, e.g. `addDays([order_date], 3)`. Null stays null; anything else is an error. |
 | `addMinutes(date, n)` | DateTime | Add `n` minutes, e.g. `addMinutes(now(), 15)`. |
 | `addSeconds(date, n)` | DateTime | Add `n` seconds. |
 | `currentUserId()` | Long | The acting user's tenant user ID. |

package/skills/dforge-mcp-author/references/conventions.md

@@ -42,8 +42,7 @@ my_module/
 │   ├── menus.json
 │   ├── actions.json
 │   ├── folders.json
-│   └── reports/
-│       └── <report>.json
+│   └── reports.json
 ├── security/
 │   └── roles.json
 ├── settings.json
@@ -54,6 +53,7 @@ my_module/
 │   └── de-DE.json              # IETF tags, one file per non-English locale
 ├── print_templates/
 │   └── <template>.scriban
+├── migrations/                  # upgrade data scripts, <version>.sql
 ├── files/                       # static assets
 └── webhooks.json                # optional
 ```
@@ -144,7 +144,8 @@ Both use **semver** (`MAJOR.MINOR.PATCH`).
 - If you added a new entity or column → bump both `version` and `dbSchemaVersion`.
 - If you changed a view or menu → bump `version` only.
 - If you changed translations only → bump `version` only.
-- The installer uses `dbSchemaVersion` to decide whether to run schema migrations. Wrong version = skipped migrations.
+- The installer uses `dbSchemaVersion` to decide whether to apply schema changes. Wrong version = skipped DDL.
+- Data a new version reshapes (backfill, move rows, drop a table it no longer declares) goes in `migrations/<version>.sql`, named by `version`, run once on an upgrade from below it. See `manifest.md` § Upgrade migrations.
 - **Never ship a package without bumping at least `version`** from the previous release. The installer may reject or silently skip a re-install with the same version.
 - For brand-new modules, start at `version: "0.1.0"` and `dbSchemaVersion: "0.0.1"`.
 

package/skills/dforge-mcp-author/references/flags.md

@@ -118,12 +118,12 @@ These are **NOT** flag letters. They're separate properties on the column defini
 | Need | How to declare | NOT this |
 |---|---|---|
 | Primary key | `"isPk": true` (or use `identity` trait) | NOT a `P` flag |
-| Unique column | Add a unique index in the entity's `indexes` block, or `"isUnique": true` | NOT a `U` flag |
+| Unique column | A `unique` constraint in the entity's `constraints` block: `"ux_code": { "type": "unique", "fields": ["code"] }` | NOT a `U` flag, NOT an index |
 | Searchable | Configure in data view columns or search settings | NOT an `S` flag |
 
 ## Mistakes to avoid
 
-- Using `"U"` for unique — **not a valid flag**. Use `"isUnique": true` or indexes.
+- Using `"U"` for unique — **not a valid flag**. Use a `unique` constraint. There is no `isUnique` property, and an entry in `indexes` is never unique.
 - Using `"S"` for searchable — **not a valid flag**.
 - Using `"P"` for primary key — **not a valid flag**. Use `"isPk": true` or the `identity` trait.
 - Declaring `M` **and** `"isNullable": true` on the same field — a contradiction that fails the pack.

package/skills/dforge-mcp-author/references/manifest.md

@@ -111,7 +111,7 @@ Dependencies are a map of module codes to semver ranges. The installer checks th
 
 **Declare a dependency only on a module you actually consume something from** — an entity you reference with a link column, extend, grant rights on, or read in a view, report, formula or action. Every entry you write here obliges you to write a matching `deps/<module>.json` contract (below), so a speculative dependency is not free.
 
-**Do not depend on `admin`.** It — like `metadata` and `workspace` — is a system module, provisioned into every tenant before any other module installs. Depending on it buys nothing. The one legitimate reason to name a system module is to require a **minimum platform version** for a feature you use, e.g. `"metadata": ">=1.5.0"` for record-report attachments; that still needs a contract naming the entity the feature introduced.
+**Do not depend on `admin`.** It — like `metadata`, `workspace` and `sys-billing` — is a system module, provisioned into every tenant before any other module installs. Depending on it buys nothing. The one legitimate reason to name a system module is to require a **minimum platform version** for a feature you use, e.g. `"metadata": ">=1.5.0"` for record-report attachments. Its contract names the entity the feature introduced, or declares `"entities": {}` when the feature introduced none (`"admin": ">=1.21.0"` for upgrade migrations).
 
 **For bridge modules** (`crm-fin`, `wms-fin`, etc.), depend on both sides:
 
@@ -143,7 +143,7 @@ Every entry in `dependencies` needs a contract file at `deps/<module_code>.json`
 ```
 
 - `version` must be the same range as the manifest's dependency entry.
-- `entities` needs at least one entry; each needs a `pk` and a non-empty `use`.
+- `entities` needs at least one entry, except against a system module, where `{}` is a pure platform-version gate. Each entry needs a `pk` and a non-empty `use`.
 - `columns` is optional — omit it when you touch no specific column of that entity. Declare only real storage columns you read, write or join on, at their **storage class** (`int8`, `varchar`, `numeric`, `bool`, `date`, `timestamptz`, …; a `cuid` PK is `int8`). Never declare a virtual column (`R`/`S`/`F`) or a column your own extension adds.
 - `use` tokens are `<kind>:<symbol>` where kind is `ref`, `extends`, `formula`, `action`, `view`, `report`, `print` or `role`. `extends` must be fully qualified: `extends:parties.party`.
 
@@ -174,4 +174,22 @@ The extension file has `"extends": "fin.invoice"` inside. See MODULE_CONVENTIONS
 
 - Bump `version` on every release (bug fix, feature add, etc.).
 - Bump `dbSchemaVersion` **only** when the DB schema changes. If you added an action but no new columns, `version` goes up but `dbSchemaVersion` stays the same.
-- The installer uses `dbSchemaVersion` to decide whether to run migrations.
+- The installer uses `dbSchemaVersion` to decide whether to apply schema changes. Upgrade **data** scripts under `migrations/` are keyed by `version` instead — see below.
+
+## Upgrade migrations (`migrations/`)
+
+A table or column change needs no script: the installer generates the DDL. A script is for the DATA a new version reshapes — filling a new column from an old one, moving rows to a new table, dropping a table the new version no longer declares (the platform never drops one on its own).
+
+```
+migrations/
+└── 0.11.0.sql      # runs on an upgrade from below 0.11.0 to 0.11.0 or later
+```
+
+- **Name** — the module `version` the file upgrades to, `MAJOR.MINOR.PATCH.sql`. Keyed by `version`, not `dbSchemaVersion`. A misnamed file, or one newer than the manifest `version`, fails the package at load.
+- **When** — on an upgrade only: every file above the installed version and no higher than the package's, in ascending order. A fresh install or a same-version reinstall runs none.
+- **Where** — inside the install transaction, after the new tables and columns exist and before `NOT NULL` is applied or a register's `totals` cache is rebuilt. A table the new version removed is still there to read. A failing script rolls the upgrade back and the module stays on the old version; refuse unconvertible data with `RAISE EXCEPTION '…'`, which the operator sees.
+- **Ids** — `"dForge".next_id()` mints a row id in SQL. Declare `"admin": ">=1.21.0"` in `dependencies`; that is also what guarantees a platform that runs migrations.
+- **Locks** — a script writing a posted document or its register journal wraps the writes in `SELECT set_config('registry.posting', 'true', true);` … `'false'`, so the post locks stand aside. Period locks do not; reopen a closed period and close it again.
+- A `kind: "pack"` module cannot carry migrations.
+
+Reference: `modules/gl/migrations/0.11.0.sql` in dForge-core.

package/skills/dforge-mcp-author/references/reports.md

@@ -7,11 +7,14 @@ SP files: `logic/reports/rpt_*.sql`
 
 ## Structure
 
-A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...] }`), optional per-dataset `params`, and an optional `entities` array (record-report attachments). Panels reference datasets by code via `datasetCd`.
+A report has a `label`, a `description`, a `datasets` map, a `layout` object (`{ panels: [...] }`), optional per-dataset `params`, and an optional `entities` array (record-report attachments). Panels reference datasets by code via `datasetCd`.
+
+**Name it with `label`, describe it with `description`.** `label` is the report's name: page title, breadcrumb and parameter dialog. `description` says what it shows and appears under the label, as a data view's does. Without a `label` the description becomes the name, so a sentence ends up as the page title. `dforge_module_validate`, `module pack` and install warn about it; install does not refuse it. Translate the name as `reports.<cd>.label`.
 
 ```json
 {
     "sales_pipeline": {
+        "label": "Sales Pipeline",
         "description": "Open opportunities by stage",
         "datasets": {
             "pipeline": {
@@ -191,6 +194,10 @@ granted on. Keyed by stored-procedure code, which may not contain a dot.
 - **`params`** is the call signature, in order — omit it for a zero-argument function.
 - **`columns`** is optional; without it install derives the result columns from the
   function's `RETURNS TABLE (…)`.
+- A result column may name a **`domain`** (`domain_cd` or `module_cd.domain_cd`) instead of
+  `fieldTypeCd` / `baseDatatypeCd` / `params`: a status the function returns then shows its
+  labels without restating the entity's option list. Naming a domain and restating any of
+  the three is refused.
 - Schema: `stored_procedures.schema.json`.
 
 ## Parameters
@@ -341,7 +348,8 @@ A report can be **attached to an entity** so it opens from a record — the way
 
 ```json
 "credit_check": {
-    "description": "Customer Credit Check — limit against outstanding AR and open quotes",
+    "label": "Credit Check",
+    "description": "Credit limit against outstanding AR and open quotes",
     "entities": [
         { "entityCd": "parties.party", "params": { "customer_id": "party_id" }, "orderNum": 45 },
         { "entityCd": "crm.quote",     "params": { "customer_id": "customer_id" }, "orderNum": 45 }

package/skills/dforge-mcp-author/references/traits.md

@@ -104,13 +104,13 @@ Use in combination with `accumulation` or `ledger` traits for accounting/registr
 
 ### `accumulation`
 
-**Marker trait — adds no columns.** Indicates the entity is an accumulation register. Configuration lives in `A`-type column params (balance entity, dimensions, resources).
+**Marker trait — adds no columns.** Indicates the entity is an accumulation register. The register itself is declared once in the module's `registers.json`; an `A`-type column only binds to it (`register`, `map`, `dateField`, …). Schema: `dforge://schema/registers`.
 
 Advanced feature for accounting/registry modules.
 
 ### `ledger`
 
-**Marker trait — adds no columns.** Indicates the entity uses double-entry bookkeeping. Configuration lives in `L`-type column params (lines, movement entity, balance entity).
+**Marker trait — adds no columns.** Indicates the entity uses double-entry bookkeeping. The `accounting` register is declared in `registers.json`; an `L`-type column binds to it.
 
 Advanced feature for accounting modules.
 

package/skills/dforge-module-build/SKILL.md

@@ -237,6 +237,10 @@ If none fire, skip specialized views for that entity.
 **3c. Reports** only when aggregation/grouping isn't covered by views — or when
 Phase 2a sent you here because the "action" only wanted to show a number.
 
+Give each report a short `label` (its name: page title, breadcrumb, parameter
+dialog) and a `description` of what it shows, which appears under the label.
+Without a label the description becomes the title, and validate/pack warn.
+
 Params are **report-scoped**: declare them in the report-level `parameters`
 block, or as shorthand under `datasets.<cd>.params` when exactly one dataset uses
 the param. The installer merges both into the report's one param set, report level

package/skills/dforge-module-ship/SKILL.md

@@ -101,6 +101,11 @@ role / trigger / job counts. Then confirm both version strings with the user:
 - **`version`** — always bump (semver) before packing.
 - **`dbSchemaVersion`** — bump only if entity fields were added, removed, or
   type-changed since the last install.
+- **Data on upgrade** — if the new version moves or reshapes existing rows, or
+  removes an entity whose table must go, ship `migrations/<version>.sql` named by
+  the new `version` and declare `"admin": ">=1.21.0"`. The installer generates the
+  DDL; it never moves data or drops a table on its own. See
+  `dforge://docs/conventions` § Upgrade Migrations.
 
 Get explicit confirmation on both before packing. This version confirmation
 applies only to the initial pack. During the install-fix loop, re-pack without