@dforge-core/dforge-mcp 0.2.34 → 0.2.36

package/CHANGELOG.md

@@ -4,6 +4,64 @@ 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.2.36 — 2026-10-12
+
+**`settings.json` gains `$constraints`**: check constraints across a module's settings, SQL over
+setting codes (`"expression": "default_discount_pct <= max_discount_pct"`). The settings schema
+and `dforge://schema/translations` describe it.
+
+**Function libraries.** Helpers a module's actions share go in `logic/functions/*.dsl`; another
+module's functions are imported under `"functions"` in `deps/<module>.json` and called as
+`<module>.<fn>()`. `dforge_module_validate` and install check the imports.
+
+**A broken function library is reported once, as itself**, and a `ref` or `domain` may name a
+hyphenated module (`ref cdy-hr.department`); a qualified ref to an unknown module is refused at
+pack and validate.
+
+**DSL reference caught up** (`dforge://docs/dsl`, `action-dsl`): a Function libraries section
+(contents, names, state, imports, errors), the six register reads (`getBalance` ... `getCorrespondence`;
+the built-in count is now 42), text action params staying text, `ref` to a hyphenated module, the
+5-minute action-definition cache after a CLI install, and `query()` CTE and write-target qualification.
+
+**Module install reports a skip.** Installing a package whose version is already installed
+prints `already at vN — nothing installed (use --force to reinstall)` instead of success.
+
+**Register dimensions are never empty** (author skill): an empty dimension refuses the posting by
+design; use a default record, not `COALESCE(…, 0)`.
+
+## 0.2.35 — 2026-10-07
+
+**`addDays()` moves a date field** (dForge-core #1382). `addDays([order_date], 3)` used to
+return the date unchanged. `dforge://docs/dsl` and the author skill now say what the date
+builtins take: a date field, a `Date` or an ISO string. Any other value is now an error,
+where the platform used to pass it through unchanged.
+
+**An entity index is `fields` plus an optional `using`.** The installer used to skip an index
+declared with `columns` without a word; `pack`, `validate` and install now refuse it, and
+`dforge://schema/entity` types the index object. The flags reference no longer offers an
+index or the nonexistent `isUnique` for a unique column: that is a `unique` constraint.
+
+**A stored-procedure result column may name a `domain`** (dForge-core #1323), which supplies
+its control, datatype and options. `dforge://schema/stored-procedures` and the reports
+reference say so.
+
+**Register bindings** — `dforge://schema/entity` and `dforge://schema/registers` carry what
+the platform added since 0.0.34:
+
+- `groupLinesBy`: one movement per distinct value of the named line columns.
+- A `map` / `headerMap` / `dateField` value starting with `=` is an expression.
+- `dateTrunc` (`day`, `month`, `year`) on the binding's date.
+- A register `label`, translated under the new `registers` section of
+  `dforge://schema/translations`.
+- `recordChangesOnly` on an `info` register with a `recorder`, and `absentAs` on its
+  resources.
+
+The `accumulation` and `ledger` trait references now point at `registers.json` instead of
+column params.
+
+- Dependencies: `@dforge-core/metadata` `^0.0.35`, `@dforge-core/dforge-cli` `^0.2.28`.
+  Schemas pre-staged from dForge-core; re-vendored from metadata 0.0.35 at publish.
+
 ## 0.2.34 — 2026-10-06
 
 **A report has a `label` beside its `description`** (dForge-core 61ad762). The label is

package/dist/server.js

@@ -31002,7 +31002,7 @@ var import_node_crypto = require("crypto");
 var fs2 = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.27/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.28/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -31290,7 +31290,7 @@ function buildZedTasks() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.34/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.35/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -34602,7 +34602,7 @@ var path10 = __toESM(require("path"));
 var fs7 = __toESM(require("fs"));
 var path9 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.34/node_modules/@dforge-core/metadata/dist/dsl/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.35/node_modules/@dforge-core/metadata/dist/dsl/index.js
 var PUNCT3 = ["===", "!=="];
 var PUNCT2 = [
   "==",
@@ -38881,7 +38881,7 @@ var resources = [
   {
     uri: "dforge://docs/dsl",
     name: "dForge action DSL reference",
-    description: "Full reference for the dForge action DSL (logic/actions/*.dsl files): block structure (params/canExecute/onBeforeStart/execute), execution modes (single/each/batch), field-access syntax ([field], params[name], [ref].[field], records.*), all 30 built-in host functions (query/insert/error/exit/now/sendEmail/...), supported JS subset (ES5 via Esprima/Jint), common patterns, and pitfalls. **Load this before authoring any DSL action (Phase 2 of the wizard).**",
+    description: "Full reference for the dForge action DSL (logic/actions/*.dsl files): block structure (params/canExecute/onBeforeStart/execute), execution modes (single/each/batch), field-access syntax ([field], params[name], [ref].[field], records.*), all 42 built-in host functions, incl. register reads, plus function libraries (logic/functions/*.dsl) (query/insert/error/exit/now/sendEmail/...), supported JS subset (ES5 via Esprima/Jint), common patterns, and pitfalls. **Load this before authoring any DSL action (Phase 2 of the wizard).**",
     mimeType: "text/markdown",
     read: () => readVendored("docs/dsl-reference.md")
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.34",
+  "version": "0.2.36",
   "description": "MCP server for dForge module authoring. Exposes 35 scaffold/patch/validate/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",
@@ -26,8 +26,8 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@dforge-core/dforge-cli": "^0.2.27",
-    "@dforge-core/metadata": "^0.0.34",
+    "@dforge-core/dforge-cli": "^0.2.29",
+    "@dforge-core/metadata": "^0.0.37",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },

package/resources/docs/dsl-reference.md

@@ -133,6 +133,10 @@ execute:
     var maxDays = params[supplier].payment_terms
 ```
 
+A `ref` names the entity by its code, qualified as `module.entity` for another module; a hyphenated module code is fine (`ref cdy-hr.department`), the schema form `cdy_hr.department` is not. Pack and install refuse a `ref` to a module that is neither this one, a declared dependency nor a system module, and install refuses one naming no installed entity.
+
+A param declared with a text field type (`text`, `textarea`, ...) stays a string whatever JSON type the client sent: `007` keeps its zeros, and a barcode compares to a text column without a cast. No `'' + params[x]` workaround is needed. Every other param is unwrapped as before.
+
 ---
 
 ## Field access syntax
@@ -211,6 +215,8 @@ info('Reminded ' + open.length + ' open invoice(s)')
 > tables. Don't assume the whole action is one transaction either — that depends
 > on the execution path. Applies to `query()` only.
 
+> **Table names.** Bare names are qualified with the current module's schema after `FROM` / `JOIN` / `USING` and as the target of `INSERT INTO`, `MERGE INTO`, `UPDATE`; a qualified name (`wms.stock`) is left as written. A CTE name is a source only inside the query that declares its `WITH` (its own body only under `RECURSIVE`); a write target is always the real table, so `WITH t AS (...) UPDATE t ...` updates the module's `t`.
+
 #### `insert(entityCd, fields) → record`
 Insert a row. Returns the inserted record as a dictionary (PKs populated, defaults applied, audit columns set).
 
@@ -337,16 +343,20 @@ Current UTC timestamp.
 [completed_at] = now()
 ```
 
-#### `addDays(date, days) → DateTime`
-Add (or subtract with negative) integer days.
+#### `addDays(date, days) → same kind as date`
+Add (or subtract with negative) integer days. `date` is a date field, a `Date` or an ISO
+string. A date field stays a date and a `yyyy-MM-dd` string stays a string. Null stays null;
+any other value is an error.
 
 ```dsl
 [due_date] = addDays(now(), 30)
+[ship_date] = addDays([order_date], 3)
 var lastWeek = addDays(now(), -7)
 ```
 
 #### `addSeconds(date, seconds) → DateTime`, `addMinutes(date, minutes) → DateTime`
-Fractional-unit arithmetic.
+Fractional-unit arithmetic over the same inputs as `addDays`. The result has a time of day,
+so a date field or a `yyyy-MM-dd` string comes back as a `DateTime`.
 
 ```dsl
 [token_expires_at] = addMinutes(now(), 15)
@@ -703,13 +713,95 @@ if (meta != null && meta.priority == 'high') { notify([owner_id], 'High priority
 
 ---
 
+### Register reads
+
+The first argument names a **register** (`module_cd.register_cd`, as declared in that module's `registers.json`), not an entity. These only ask questions; a document posts through its `A` / `L` column.
+
+| Function | Returns | Description |
+|---|---|---|
+| `getBalance('module.register', dims?, asOf?)` | Object, per resource | Balance of an accumulation register. A dimension left out of `dims` is summed over. |
+| `getTurnover('module.register', dims, from, to)` | Object, `{in, out, net}` per resource | Movement over an interval. `dims` may be `null`; `from` and `to` are required. |
+| `getSlice('module.register', dims, onDate?, mode?)` | Object or `null` | One record of an information register, the latest on or before `onDate`, plus `_period`. No dimension may be omitted. |
+| `getAccountBalance('module.register', account, filter?, asOf?)` | Object, `{debit, credit, net}` per resource | Balance of one account of an accounting register. |
+| `getAccountTurnover('module.register', account, filter, from, to)` | Object, `{debit, credit, net}` per resource | Movement of one account over an interval. |
+| `getCorrespondence('module.register', debitAccount, creditAccount, filter, from, to)` | Object, per resource | Movement between two accounts. Needs `lineMode: "compound"`; refuses an analytic filter. |
+
+An analytic filter is the key alone (`{ cost_center: 42 }`) or `{ entity, value }` to name one entity of a union kind.
+
+---
+
+## Function libraries
+
+Helpers several actions share go once in `logic/functions/*.dsl`, never pasted into each action. A library is detected by presence; `manifest.json` declares nothing.
+
+```js
+// logic/functions/accounting.dsl
+var recNo = 0
+
+function round2(x) {
+    return Math.round(x * 100) / 100
+}
+
+function accountId(code) {
+    var rows = query('SELECT account_id FROM account WHERE code = @code', { code: code })
+    if (rows.length == 0) error('Account {code} does not exist.', { code: code })
+    return rows[0].account_id
+}
+```
+
+```js
+// logic/actions/commit_sale.dsl
+execute:
+    [amount] = round2([amount])
+    var account = accountId(getSetting('sale_account'))
+    recNo = recNo + 1
+```
+
+- **Contents.** Top-level `function` declarations and top-level `var` / `let` / `const`; any other top-level statement is refused at install. Every built-in an action has.
+- **No record context.** `[field]`, `[ref].[target]`, `params[...]` and `old[...]` are refused: pass values as arguments (`round2([amount])`). `[name]` standing alone is refused too, even where JavaScript would read an array; write a one-element array as `Array.of(name)`. An index (`rows[i]`) is fine.
+- **Names.** File names use letters, digits, `_`, `-`. A library may not declare a built-in's name, a JS global (`Math`, `Date`), `schema` or a `__` name. A name is declared once across a module's libraries. An action may not declare a global of a library's name (a top-level function or variable, or a `var` outside any function): delete the local copy. Inside a function, or a block-scoped `let` / `const`, a name may repeat.
+- **State.** Top-level variables start afresh on every run (each record of a `single` action, each batch, trigger fire and job run), so a counter like `recNo` never leaks between runs or users.
+- **Messages.** `error()` / `warn()` / `info()` / `exit()` texts in a library are translated from the module's `messages` block like an action's.
+- **Errors.** A runtime error names the file and line: `(logic/functions/tax.dsl, line 3)`. A library that does not compile is reported once, as itself (`Function library failed to compile:` with file and line), at pack, validate and install, not as undefined calls in the actions.
+- **Linked at run time**, not copied into actions: changing a library changes every action that calls it.
+- **Not available:** formulas (`F` columns, `canExecute:`) cannot call libraries; the in-app editor does not show them; Studio refuses a module that has libraries or imports.
+
+### Another module's functions
+
+List the functions under `"functions"` in that dependency's contract `deps/<module>.json`, then call them as `<module_with_underscores>.<fn>()`:
+
+```json
+{
+    "module": "cdy-accounting",
+    "version": ">=0.3.0",
+    "entities": {},
+    "functions": ["roleOf"]
+}
+```
+
+```js
+execute:
+    var account = cdy_accounting.roleOf([doc_type], 'stock')
+```
+
+- The namespace is the provider's code with `-` replaced by `_`, so `foo-bar` and `foo_bar` share one. Only the listed functions are in it; a call to another fails at install. Only a module in `dependencies` can be called.
+- The function runs as its provider: unqualified tables resolve in the provider's schema, `getSetting()` reads the provider's settings, its messages use the provider's translations. User, folder, transaction and run limits are the caller's.
+- A provider's top-level variables are its own, fresh per run.
+- Libraries may call imported functions too, and imports chain (a provider's functions call what the provider imports). Import only what you call yourself.
+- Install checks each imported name is a top-level function of the installed provider's libraries. A contract that imports only functions may declare `"entities": {}`.
+- A provider upgrade that drops an imported function is not re-checked against consumers: the call finds `undefined` at run time.
+
+**Definitions are cached.** The server reads an action's definition through a per-tenant cache (5 minutes), cleared on module install, uninstall and Studio publish. A CLI install is noticed only through a connected browser, so without one a changed action can run stale for up to 5 minutes.
+
+---
+
 ## JavaScript subset
 
 Esprima parses ES5; Jint executes.
 
 **Supported control flow:** `if / else`, `for`, `while`, `do...while`, `switch / case / default / break / continue`, `return` (only inside `function`), `try / catch / finally`, `throw`.
 
-**Supported declarations:** `var`, `function`. (No `let`, no `const`.)
+**Supported declarations:** `var`, `function`. (No `let`, no `const` in actions; a function library may use top-level `let` / `const`.)
 
 **Operators:** all standard arithmetic / comparison / logical / assignment, including ternary `? :`.
 
@@ -1056,6 +1148,15 @@ var q = query('SELECT * FROM customer WHERE name = ' + "'" + params[name] + "'",
 var q = query('SELECT * FROM customer WHERE name = @n', { n: params[name] })
 ```
 
+### ❌ Library and import mistakes
+
+- A **function library** (`logic/functions/*.dsl`) that reads `[field]` / `params[...]` / `old[...]`, uses `[name]` alone (write `Array.of(name)`), or has a top-level statement that is not a `function` / `var` / `let` / `const` -- all refused at install. Pass values in as arguments. See "Function libraries" above.
+- Keeping a **local copy** of a library function in an action (a top-level function, or a `var` of the same name outside any function) -- refused at install. Delete the copy.
+- Calling another module's function without importing it: list it under `"functions"` in `deps/<module>.json`, call it as `<module_with_underscores>.fn()`.
+- `ref cdy_hr.department` (schema form) in `params:` -- installs with no picker target. Write `ref cdy-hr.department`.
+- `'' + params[barcode]` to keep a text param text -- no longer needed.
+
+
 ### ❌ Forgetting to bump `[updated_at]` on writes
 
 The `audit` trait auto-maintains `last_updated` on INSERT/UPDATE if the column exists, but only via the standard data-access path. Direct `[field] = value` writes from DSL trigger the same path, so `last_updated` updates correctly. (No action needed — listed here as reassurance.)
@@ -1081,6 +1182,8 @@ The `audit` trait auto-maintains `last_updated` on INSERT/UPDATE if the column e
 | Send toast | `info('msg')`, `warn('msg')` |
 | Send email | `sendEmail(to, subj, body)` or `sendEmail(to, templateCd, dataObj)` |
 | Send inbox notification | `notify(userId, 'msg')` |
+| Call a shared helper | `round2([amount])` from `logic/functions/*.dsl` |
+| Call another module's helper | `cdy_accounting.roleOf(...)`, imported in `deps/<module>.json` |
 | Add days | `addDays(date, n)` |
 | Now | `now()` |
 

package/resources/schemas/entity.schema.json

@@ -114,7 +114,24 @@
 		},
 		"indexes": {
 			"type": "object",
-			"description": "Database index definitions"
+			"description": "Database indexes, keyed by index name (the Postgres index name). A register's journal and state tables need none declared: the platform builds the indexes its own reads and writes use.",
+			"additionalProperties": {
+				"type": "object",
+				"required": ["fields"],
+				"additionalProperties": false,
+				"properties": {
+					"fields": {
+						"type": "array",
+						"minItems": 1,
+						"items": { "type": "string" },
+						"description": "Indexed columns, in order. Install refuses any key other than fields and using - \"columns\", which a unique constraint accepts, included."
+					},
+					"using": {
+						"enum": ["btree", "hash", "gin", "gist", "brin"],
+						"description": "Index method. Omitted, btree."
+					}
+				}
+			}
 		},
 		"numberSequence": {
 			"$ref": "#/$defs/numberSequence",
@@ -242,9 +259,11 @@
 				"lineField": { "type": "string", "description": "The line's foreign-key column(s) to the header, comma-separated in the header's key order for a composite key." },
 				"stateField": { "type": "string", "description": "The bool column that records the posted state, when it is not the registry column itself. Written only by the register engine." },
 				"register": { "type": "string", "description": "The register this column posts to, as 'module_cd.register_cd' (declared in that module's registers.json). Binding to one replaces restating what the register is: the declaration supplies the state entity, dimensions, resources, journal, allowNegative and autoCreate, and this column keeps only what legitimately differs per writer — direction/sign, 'map' and 'dateField'." },
-				"map": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Register dimension or resource name -> this document's column carrying it. Every resource the register declares must be mapped (install refuses otherwise); a dimension left out binds to a column of the same name. Only meaningful with 'register'. On an accumulation (A) column a value may be a one-hop reference path, '<reference column>.<target column>', read through the reference at posting time (off the line when the binding posts from lines)." },
-				"headerMap": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Register dimension or resource name -> this DOCUMENT's column carrying it, for a binding that posts from LINES. A line binding reads every other value off the line, and a dimension that belongs to the document (a dealer, an organisation, a date) cannot be put on the line: a G column is a same-row expression or an aggregate over a child set, so it cannot read a parent. Explicit rather than a fallback, because 'not on the line, try the header' turns a typo into a silent read of an unrelated header column with the same name. Install refuses: a name on neither table, a field also named in 'map', a column also read off the line by 'map', a column that is part of the line's key, a column 'lockedFields' does not freeze (the posting is keyed by it, so it has to hold still while the document is posted), and a RESOURCE unless the register is 'info' (a quantity from the document would be added once per line; an information register's records replace rather than add). A value may be a one-hop reference path off the document, whose reference key column 'lockedFields' must then freeze." },
-				"dateField": { "type": "string", "description": "This document's date column, supplying the date the register stamps on each journal row. Required once the register declares a 'journalDate' — one writer that supplied none would make every balance read as of a date quietly short, across all writers. On an accumulation (A) column it may be a one-hop reference path, '<reference column>.<target column>'." },
+				"map": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Register dimension or resource name -> this document's column carrying it. Every resource the register declares must be mapped (install refuses otherwise); a dimension left out binds to a column of the same name. Only meaningful with 'register'. On an accumulation (A) column a value may be a one-hop reference path, '<reference column>.<target column>', read through the reference at posting time (off the line when the binding posts from lines), or an expression: a string starting with '=' holding an F-column formula over the same row with one-hop reference reads — \"=COALESCE([transit_warehouse_id], [dest_warehouse_id])\"." },
+				"headerMap": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Register dimension or resource name -> this DOCUMENT's column carrying it, for a binding that posts from LINES. A line binding reads every other value off the line, and a dimension that belongs to the document (a dealer, an organisation, a date) cannot be put on the line: a G column is a same-row expression or an aggregate over a child set, so it cannot read a parent. Explicit rather than a fallback, because 'not on the line, try the header' turns a typo into a silent read of an unrelated header column with the same name. Install refuses: a name on neither table, a field also named in 'map', a column also read off the line by 'map', a column that is part of the line's key, a column 'lockedFields' does not freeze (the posting is keyed by it, so it has to hold still while the document is posted), and a RESOURCE unless the register is 'info' (a quantity from the document would be added once per line; an information register's records replace rather than add). A value may be a one-hop reference path off the document, whose reference key column 'lockedFields' must then freeze, or an expression over the document ('=...', see 'map')." },
+				"groupLinesBy": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true, "description": "Line columns whose distinct values each post ONE movement, instead of one per line — a production report posting 'this unit worked today' once per unit with a count of 1. 'map' is then read over a group row: the grouped line columns, every column of the document, and one-hop reads through a reference of either, so an expression may mix the document and the group key. A quoted constant is stamped once per group; a numeric line column mapped to a resource is summed over the group. Install refuses: a binding that posts from the document, an L column, a grouped column the line does not store or 'lockedLineFields' does not freeze, a line column read that is neither grouped nor a summed resource, a non-numeric summed resource, a column both grouped and summed, an ungrouped line resource on an 'info' register, a name both the line and the document carry, and a document column read that 'lockedFields' does not freeze. Accumulation (A) columns only." },
+				"dateField": { "type": "string", "description": "This document's date column, supplying the date the register stamps on each journal row. Required once the register declares a 'journalDate' — one writer that supplied none would make every balance read as of a date quietly short, across all writers. On an accumulation (A) column it may be a one-hop reference path, '<reference column>.<target column>', or an expression over the document ('=...', see 'map')." },
+				"dateTrunc": { "type": "string", "enum": ["day", "month", "year"], "description": "Takes the date 'dateField' supplies back to the start of its day, month or year before the register stamps it — for a document that carries a time while the register's records sit on whole days. The calendar is the value's as stored; no time zone is applied. Needs 'dateField'. Accumulation (A) columns only." },
 				"skipPostingWhenEmpty": { "type": "array", "items": { "type": "string" }, "description": "THE EXCEPTION, not the normal way to model this — read the guide before declaring it. Register dimensions (by the register's names) whose empty value means THIS POSTING records nothing: the line, or the document when the binding posts from the document. One posting is skipped, never the register and never the document. When that is all the document would have recorded it is left unposted to this register, and the flag is per binding, so its other registers post as usual. An empty dimension NOT listed refuses the posting, naming the row and the dimension. It leaves a document fully posted while some of its lines produced no movement, which usually means the document is modelling two kinds of line in one table: since 'lineEntity' is declared per BINDING, prefer giving each register its own line table (goods lines post to stock, service lines do not) so that every line of each table posts. Declare this only when the distinction is not structural but lives in the data — a batch or serial number filled on some rows and not others — so there is no second table to put those rows in. Accumulation (A) columns only. Formerly skipWhenNull: a package using the old name is refused at install, while a tenant's already-stored params keep being read under it." },
 				"periodEntity": { "type": "string", "description": "Period entity this registry closes against — one of this module's, or 'module.entity' from a dependency." },
 				"periodDateField": { "type": "string", "description": "Header date column that resolves the period." },
@@ -253,6 +272,8 @@
 			},
 			"dependencies": {
 				"headerMap": ["lineEntity"],
+				"groupLinesBy": ["lineEntity"],
+				"dateTrunc": ["dateField"],
 				"lineEntity": ["lineField", "lockedLineFields"],
 				"lineField": ["lineEntity"],
 				"lockedLineFields": ["lineEntity"],

package/resources/schemas/registers.schema.json

@@ -19,7 +19,7 @@
 				"then": {
 					"required": ["entity"],
 					"properties": {
-						"period": false, "recorder": false,
+						"period": false, "recorder": false, "recordChangesOnly": false,
 						"chart": false, "composition": false, "analyticFields": false, "lineMode": false,
 						"account": false,
 						"debitAccount": false, "creditAccount": false,
@@ -36,7 +36,7 @@
 					"properties": {
 						"entity": false,
 						"period": false,
-						"recorder": false,
+						"recorder": false, "recordChangesOnly": false,
 						"chart": false, "composition": false, "analyticFields": false, "lineMode": false,
 						"account": false,
 						"debitAccount": false, "creditAccount": false,
@@ -76,7 +76,7 @@
 					"properties": {
 						"entity": false,
 						"period": false,
-						"recorder": false,
+						"recorder": false, "recordChangesOnly": false,
 						"journalDirection": false,
 						"allowNegative": false,
 						"autoCreate": false
@@ -106,7 +106,7 @@
 							}
 						}
 					],
-					"description": "An accounting register keys its postings by an account, not by a dimension tuple it declares once. What analytics a posting carries, and what each one MEANS, is a property of the account: measured on a production chart of 468 accounts, the analytic count runs 0 to 4 and slot 2 is Nomenclature on one account and Contracts on another. So the chart and the per-account composition are part of the declaration, and 'entity' \u2014 one row per dimension tuple \u2014 has nothing to name."
+					"description": "An accounting register keys its postings by an account, not by a dimension tuple it declares once. What analytics a posting carries, and what each one MEANS, is a property of the account: the analytic count differs from account to account, and slot 2 may be Nomenclature on one account and Contracts on another. So the chart and the per-account composition are part of the declaration, and 'entity' \u2014 one row per dimension tuple \u2014 has nothing to name."
 				}
 			}
 			,
@@ -146,6 +146,11 @@
 				"enum": ["balance", "turnover", "info", "accounting"],
 				"description": "Register kind. 'balance' keeps a running state per dimension tuple (1C регистр накопления / остатки); 'turnover' keeps none and answers only for intervals (1C регистр накопления / обороты), the majority of accumulation registers in practice; 'info' holds values that change over time, or a plain keyed lookup when it declares no period (1C регистр сведений). 'accounting' keys its postings by an account whose analytics the CHART declares, per account, because what an analytic slot means depends on the account it is on. Both of its line modes are posted and read."
 			},
+			"label": {
+				"type": "string",
+				"maxLength": 200,
+				"description": "Display name, shown wherever the register is offered beside entities (the query builder's From picker). Localized under the translation files' registers.<code>.label. The register code when omitted."
+			},
 			"description": {
 				"type": "string",
 				"maxLength": 500,
@@ -192,12 +197,12 @@
 					"accountField": {
 						"type": "string",
 						"pattern": "^[a-z_][a-z0-9_]*$",
-						"description": "Column on the totals entity holding the account a cached row belongs to. Required on an 'accounting' register and refused on every other kind: an accounting register is read per account, so that is what its cache is keyed by, and a compound posting names TWO accounts and folds into two cached rows — one per side, each taking that side's column of every two-sided dimension — so which column holds the one cannot be derived. The analytics are NOT in the key: measured on the base this is ported from, 24.3M postings carry 99.8M analytic rows, so the analytics are where the cardinality is and a cache keyed by them would be about as large as what it summarises. A read that narrows by an analytic goes to the postings, as a read of a part-period goes to them for its edges."
+						"description": "Column on the totals entity holding the account a cached row belongs to. Required on an 'accounting' register and refused on every other kind: an accounting register is read per account, so that is what its cache is keyed by, and a compound posting names TWO accounts and folds into two cached rows — one per side, each taking that side's column of every two-sided dimension — so which column holds the one cannot be derived. The analytics are NOT in the key: a posting typically carries several analytic values, so the analytics are where the cardinality is and a cache keyed by them would be about as large as what it summarises. A read that narrows by an analytic goes to the postings, as a read of a part-period goes to them for its edges."
 					},
 					"dimensions": {
 						"type": "array",
 						"items": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" },
-						"description": "Which of the register's dimensions the cache is grouped by; omitted, it is all of them. Only on an 'accounting' register. What it is for is a dimension a posting may legitimately leave empty — a two-sided one, where the measured original fills a currency only for the accounts that keep one. A cached row's key holds no NULL, so install refuses a cached dimension whose posting column is nullable, naming the two ways out: make the column mandatory, or leave the dimension out here and let the cache sum across it. A read that narrows by an uncached dimension goes to the postings."
+						"description": "Which of the register's dimensions the cache is grouped by; omitted, it is all of them. Only on an 'accounting' register. What it is for is a dimension a posting may legitimately leave empty — a two-sided one, such as a currency filled only for the accounts that keep one. A cached row's key holds no NULL, so install refuses a cached dimension whose posting column is nullable, naming the two ways out: make the column mandatory, or leave the dimension out here and let the cache sum across it. A read that narrows by an uncached dimension goes to the postings."
 					},
 					"resources": {
 						"type": "object",
@@ -239,12 +244,17 @@
 			"period": {
 				"type": "string",
 				"pattern": "^[a-z_][a-z0-9_]*$",
-				"description": "Column on an information register's entity holding the moment each record takes effect. Declaring it makes the register periodic, and 'the value as of a date' becomes the last record at or before it. Omit it for a plain keyed lookup with no history \u2014 121 of the 285 information registers in the 1C base measured for this design are of that shape, so it is the common case rather than a degenerate one. Only valid on 'info'."
+				"description": "Column on an information register's entity holding the moment each record takes effect. Declaring it makes the register periodic, and 'the value as of a date' becomes the last record at or before it. Omit it for a plain keyed lookup with no history \u2014 many information registers are of that shape, so it is a common case rather than a degenerate one. Only valid on 'info'."
 			},
 			"recorder": {
 				"type": "string",
 				"pattern": "^[a-z_][a-z0-9_]*$",
-				"description": "Column on an information register's entity where the platform stamps which document wrote each record \u2014 the same jsonb 'source' shape a journal row carries, holding { entity, pk, line, postedBy }. Declaring it makes the register SUBORDINATE to a document: an A column binds to it, posting writes its records, unposting deletes them, and the register's rows stop being something a user maintains. Omit it for an independent register, whose records are written by ordinary means. The split is not a nuance: measured on the 1C base this design is ported from, 115 of the 285 information registers are subordinate and hold 15.7M of the 20.8M rows, and no register is ever both. Only valid on 'info'."
+				"description": "Column on an information register's entity where the platform stamps which document wrote each record \u2014 the same jsonb 'source' shape a journal row carries, holding { entity, pk, line, postedBy }. Declaring it makes the register SUBORDINATE to a document: an A column binds to it, posting writes its records, unposting deletes them, and the register's rows stop being something a user maintains. Omit it for an independent register, whose records are written by ordinary means. The split is not a nuance: subordinate registers tend to hold most of the rows, and no register is ever both. Only valid on 'info'."
+			},
+			"recordChangesOnly": {
+				"type": "boolean",
+				"default": false,
+				"description": "Posting skips a record whose resources all equal the slice in effect on its period for the same dimensions: a document setting a value that is already so writes nothing, and still posts. A property of the register rather than of any writer, because the answer is in the register. Only valid on an 'info' register that declares a 'recorder'. A resource's 'absentAs' says what it compares as before anything is in effect; without it the first record is always written. 1C posting handlers commonly do the same, comparing the new value with the slice and an absent one as zero."
 			},
 			"chart": {
 				"type": "string",
@@ -268,7 +278,7 @@
 					"slot": {
 						"type": "string",
 						"pattern": "^[a-z_][a-z0-9_]*$",
-						"description": "Column holding the slot number: WHICH of the posting's analytic columns this analytic is written into. Positional storage is what the measured base's totals tables use, and it is available because the fill is dense \u2014 an unset analytic is written explicitly rather than omitted, so the declared count and the written count matched exactly across 348,227 analytic sets."
+						"description": "Column holding the slot number: WHICH of the posting's analytic columns this analytic is written into. Positional storage is what 1C's totals tables use, and it is available because the fill is dense \u2014 an unset analytic is written explicitly rather than omitted, so the declared count and the written count match exactly."
 					},
 					"analytic": {
 						"type": "string",
@@ -313,7 +323,7 @@
 				"minProperties": 1,
 				"maxProperties": 8,
 				"propertyNames": { "pattern": "^[a-z_][a-z0-9_]*$" },
-				"description": "Dimensions that are TWO-SIDED, with the posting column for each side. Measured on the base this design is ported from, one accounting register keeps Организация shared and splits Валюта and НалоговоеНазначение per side, while a second register in the same base splits one of its two \u2014 so which dimensions split is a property of the declaration and not of the mode. A dimension left in 'dimensions' stays shared: one column for the whole row. Only valid on a compound register.",
+				"description": "Dimensions that are TWO-SIDED, with the posting column for each side. One accounting register may keep the organisation shared and split the currency and tax purpose per side, while another splits only one of them \u2014 so which dimensions split is a property of the declaration and not of the mode. A dimension left in 'dimensions' stays shared: one column for the whole row. Only valid on a compound register.",
 				"additionalProperties": {
 					"type": "object",
 					"required": ["debitField", "creditField"],
@@ -338,7 +348,7 @@
 				"maxItems": 8,
 				"uniqueItems": true,
 				"items": { "type": "string", "pattern": "^[a-z_][a-z0-9_]*$" },
-				"description": "The posting entity's analytic slot columns, in slot order: slot 1 is written into the first, slot 2 into the second. Each is a jsonb entity link, because an analytic's value is a UNION \u2014 one kind in the measured base resolves to three different document types in the same column, which a 'link' naming one entity cannot type. The length of this array is how many analytics a posting can carry; an account declaring more than that is refused when it posts, not at install, because the platform does not parse a check constraint's expression. Only valid on 'accounting'."
+				"description": "The posting entity's analytic slot columns, in slot order: slot 1 is written into the first, slot 2 into the second. Each is a jsonb entity link, because an analytic's value is a UNION \u2014 one kind may resolve to several different document types in the same column, which a 'link' naming one entity cannot type. The length of this array is how many analytics a posting can carry; an account declaring more than that is refused when it posts, not at install, because the platform does not parse a check constraint's expression. Only valid on 'accounting'."
 			},
 			"lineMode": {
 				"type": "string",
@@ -373,7 +383,7 @@
 						"debitField": {
 							"type": "string",
 							"pattern": "^[a-z_][a-z0-9_]*$",
-							"description": "On an accounting register, the posting column holding this resource's debit side. Declared with 'creditField' and instead of 'field'. Measured on the base this design is ported from, its postings carry one shared amount plus three split by side, and a second accounting register in the same base splits differently again \u2014 so splitting is a property of the resource rather than of the kind. WHAT THE PAIR MEANS DEPENDS ON 'lineMode', which is mandatory, so exactly one reading applies at a time. Under 'classic' a row is one account on one side, so these are where the amount goes when the row is a debit or a credit and exactly one carries a value. Under 'compound' they are the debited side's value and the credited side's value of one resource on one row, and both may carry one \u2014 a currency amount whose two sides are in different currencies is two different numbers, which is why the pair exists at all."
+							"description": "On an accounting register, the posting column holding this resource's debit side. Declared with 'creditField' and instead of 'field'. One register's postings may carry one shared amount plus several split by side, and another register split differently again \u2014 so splitting is a property of the resource rather than of the kind. WHAT THE PAIR MEANS DEPENDS ON 'lineMode', which is mandatory, so exactly one reading applies at a time. Under 'classic' a row is one account on one side, so these are where the amount goes when the row is a debit or a credit and exactly one carries a value. Under 'compound' they are the debited side's value and the credited side's value of one resource on one row, and both may carry one \u2014 a currency amount whose two sides are in different currencies is two different numbers, which is why the pair exists at all."
 						},
 						"creditField": {
 							"type": "string",
@@ -385,6 +395,10 @@
 							"pattern": "^[a-z_][a-z0-9_]*$",
 							"description": "Column this resource accumulates into — on the state entity for a 'balance' register, on the journal for a 'turnover' one. On a COMPOUND accounting register it is the natural form: one row, one amount, this account debited and that one credited. A CLASSIC one refuses it, because a one-sided row carrying a shared column would hold an amount with nothing to say which side it fell on."
 						},
+						"absentAs": {
+							"type": ["number", "string", "boolean"],
+							"description": "Under the register's 'recordChangesOnly': what this resource compares as when no record is in effect yet, or the one in effect holds nothing. A number, a boolean or a string, read as the resource column's type. Omit it and an absent slice differs from every value, so the first record is always written; declare 0 to treat a first value of 0 as no change, as 1C does with ЕСТЬNULL(…, 0)."
+						},
 						"required": {
 							"type": "boolean",
 							"default": true,
@@ -397,7 +411,7 @@
 					},
 					"additionalProperties": false
 				},
-				"description": "The register's measured columns, keyed by resource name \u2014 what it accumulates ('balance', 'turnover') or what a slice of it returns ('info'), as opposed to the dimensions that key it. A binding maps a document column to each resource the register marks required. The 64 bound is generous because an 'info' register's resources are VALUES rather than quantities, and a register of settings legitimately carries dozens: measured on a base being ported, one register holding who signs which customs paper carries 28 \u2014 a post and a name per document kind, in two languages, for two factories \u2014 and its one reader names all 28. An accumulation register wanting more than a handful is usually several registers."
+				"description": "The register's measured columns, keyed by resource name \u2014 what it accumulates ('balance', 'turnover') or what a slice of it returns ('info'), as opposed to the dimensions that key it. A binding maps a document column to each resource the register marks required. The 64 bound is generous because an 'info' register's resources are VALUES rather than quantities, and a register of settings legitimately carries dozens \u2014 one holding who signs which document may carry a post and a name per document kind, in several languages, for several sites. An accumulation register wanting more than a handful is usually several registers."
 			},
 			"allowNegative": {
 				"type": "boolean",

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/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/SKILL.md

@@ -71,9 +71,9 @@ Full descriptions are on the tools themselves — this is the map.
 | Cross-cutting | `dforge_dependency_add`, `dforge_diagram_add` |
 
 **Composite tools first.** A relation, a roll-up, and a status column each span
-several coordinated keys, and hand-assembling them from `entity_field_add` is
+several coordinated keys, and hand-assembling them from `dforge_entity_field_add` is
 the top source of broken modules. The composite tools emit the whole shape and
-can't express the broken variants. Reach for `entity_field_add` only for a
+can't express the broken variants. Reach for `dforge_entity_field_add` only for a
 plain scalar column.
 
 ## Writing files: preview vs `apply`

package/skills/dforge-mcp-author/references/action-dsl.md

@@ -59,6 +59,10 @@ params:
 
 Types are a subset of column field types: `text`, `textarea`, `number`, `currency`, `percent`, `checkbox`, `date`, `datetime`, `dropdown`, `lookup`, `user`.
 
+A `ref` names the entity by its code, qualified as `module.entity` for another module; a hyphenated module code is fine (`ref cdy-hr.department`), the schema form `cdy_hr.department` is not. Pack and install refuse a `ref` to a module that is neither this one, a declared dependency nor a system module, and install refuses one naming no installed entity.
+
+A param declared with a text field type (`text`, `textarea`, ...) stays a string whatever JSON type the client sent: `007` keeps its zeros, and a barcode compares to a text column without a cast. No `'' + params[x]` workaround is needed. Every other param is unwrapped as before.
+
 Access in execute block: `params[param_name]` (bracket syntax, NOT dot syntax).
 
 #### Dropdown params: label the options, or borrow a domain
@@ -298,6 +302,21 @@ var queued = select('comm.message', {
 - `query()` remains the escape hatch for anything this shape can't express: aggregates, multi-hop
   joins, CTEs, `FOR UPDATE`.
 
+### Register reads
+
+The first argument names a **register** (`module_cd.register_cd`, as declared in that module's `registers.json`), not an entity. These only ask questions; a document posts through its `A` / `L` column.
+
+| Function | Returns | Description |
+|---|---|---|
+| `getBalance('module.register', dims?, asOf?)` | Object, per resource | Balance of an accumulation register. A dimension left out of `dims` is summed over. |
+| `getTurnover('module.register', dims, from, to)` | Object, `{in, out, net}` per resource | Movement over an interval. `dims` may be `null`; `from` and `to` are required. |
+| `getSlice('module.register', dims, onDate?, mode?)` | Object or `null` | One record of an information register, the latest on or before `onDate`, plus `_period`. No dimension may be omitted. |
+| `getAccountBalance('module.register', account, filter?, asOf?)` | Object, `{debit, credit, net}` per resource | Balance of one account of an accounting register. |
+| `getAccountTurnover('module.register', account, filter, from, to)` | Object, `{debit, credit, net}` per resource | Movement of one account over an interval. |
+| `getCorrespondence('module.register', debitAccount, creditAccount, filter, from, to)` | Object, per resource | Movement between two accounts. Needs `lineMode: "compound"`; refuses an analytic filter. |
+
+An analytic filter is the key alone (`{ cost_center: 42 }`) or `{ entity, value }` to name one entity of a union kind.
+
 ### Messaging
 
 | Function | Description |
@@ -348,7 +367,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. |
@@ -392,6 +411,67 @@ error('Insufficient stock. Available: {available}, requested: {requested}',
 > (undefined in `execute:`) that the server translates to an exact `::bigint` SQL literal.
 
 
+## Function libraries
+
+Helpers several actions share go once in `logic/functions/*.dsl`, never pasted into each action. A library is detected by presence; `manifest.json` declares nothing.
+
+```js
+// logic/functions/accounting.dsl
+var recNo = 0
+
+function round2(x) {
+    return Math.round(x * 100) / 100
+}
+
+function accountId(code) {
+    var rows = query('SELECT account_id FROM account WHERE code = @code', { code: code })
+    if (rows.length == 0) error('Account {code} does not exist.', { code: code })
+    return rows[0].account_id
+}
+```
+
+```js
+// logic/actions/commit_sale.dsl
+execute:
+    [amount] = round2([amount])
+    var account = accountId(getSetting('sale_account'))
+    recNo = recNo + 1
+```
+
+- **Contents.** Top-level `function` declarations and top-level `var` / `let` / `const`; any other top-level statement is refused at install. Every built-in an action has.
+- **No record context.** `[field]`, `[ref].[target]`, `params[...]` and `old[...]` are refused: pass values as arguments (`round2([amount])`). `[name]` standing alone is refused too, even where JavaScript would read an array; write a one-element array as `Array.of(name)`. An index (`rows[i]`) is fine.
+- **Names.** File names use letters, digits, `_`, `-`. A library may not declare a built-in's name, a JS global (`Math`, `Date`), `schema` or a `__` name. A name is declared once across a module's libraries. An action may not declare a global of a library's name (a top-level function or variable, or a `var` outside any function): delete the local copy. Inside a function, or a block-scoped `let` / `const`, a name may repeat.
+- **State.** Top-level variables start afresh on every run (each record of a `single` action, each batch, trigger fire and job run), so a counter like `recNo` never leaks between runs or users.
+- **Messages.** `error()` / `warn()` / `info()` / `exit()` texts in a library are translated from the module's `messages` block like an action's.
+- **Errors.** A runtime error names the file and line: `(logic/functions/tax.dsl, line 3)`. A library that does not compile is reported once, as itself (`Function library failed to compile:` with file and line), at pack, validate and install, not as undefined calls in the actions.
+- **Linked at run time**, not copied into actions: changing a library changes every action that calls it.
+- **Not available:** formulas (`F` columns, `canExecute:`) cannot call libraries; the in-app editor does not show them; Studio refuses a module that has libraries or imports.
+
+### Another module's functions
+
+List the functions under `"functions"` in that dependency's contract `deps/<module>.json`, then call them as `<module_with_underscores>.<fn>()`:
+
+```json
+{
+    "module": "cdy-accounting",
+    "version": ">=0.3.0",
+    "entities": {},
+    "functions": ["roleOf"]
+}
+```
+
+```js
+execute:
+    var account = cdy_accounting.roleOf([doc_type], 'stock')
+```
+
+- The namespace is the provider's code with `-` replaced by `_`, so `foo-bar` and `foo_bar` share one. Only the listed functions are in it; a call to another fails at install. Only a module in `dependencies` can be called.
+- The function runs as its provider: unqualified tables resolve in the provider's schema, `getSetting()` reads the provider's settings, its messages use the provider's translations. User, folder, transaction and run limits are the caller's.
+- A provider's top-level variables are its own, fresh per run.
+- Libraries may call imported functions too, and imports chain (a provider's functions call what the provider imports). Import only what you call yourself.
+- Install checks each imported name is a top-level function of the installed provider's libraries. A contract that imports only functions may declare `"entities": {}`.
+- A provider upgrade that drops an imported function is not re-checked against consumers: the call finds `undefined` at run time.
+
 ## Real examples from the codebase
 
 ### Simple field update (status transition)
@@ -650,6 +730,8 @@ In `ui/actions.json`:
 | `orderNum` | Recommended | Display order in the action menu |
 | `isAsync` | Optional | `true` **permits** background execution — it does not force it. A parameterless action is queued directly; one with params is offered to the user as both "Run" and "Run in Background". Queued runs get a completion notification |
 
+**Definitions are cached.** The server reads an action's definition through a per-tenant cache (5 minutes), cleared on module install, uninstall and Studio publish. A CLI install is noticed only through a connected browser, so without one a changed action can run stale for up to 5 minutes.
+
 ## Atomicity
 
 `isTransacted: true` makes the run **one transaction**, in both execution modes.
@@ -710,7 +792,7 @@ be either.
 > and `ON COMMIT DROP` on any temp table. Only `query()` can do any of this — the
 > structured built-ins emit plain DML — and nothing checks it statically.
 
-1. **Table names are schema-qualified** within the module: `crm.contact`, `wms.stock_movement`, `fin.invoice`. Use the module code as the schema prefix. (Module codes with a hyphen, e.g. `crm-fin`, cannot be schema-qualified in raw SQL — another reason to use the structured built-ins, which accept the qualified `module.entity` code.)
+1. **Bare table names are qualified automatically** with the current module's schema after `FROM` / `JOIN` / `USING`, and as the target of `INSERT INTO`, `MERGE INTO` and `UPDATE`. A name already qualified (`wms.stock_movement`) is left as written, so qualify only another module's table. Left alone: words that name no table (`IS DISTINCT FROM`, `EXTRACT(year FROM d)`, `FOR UPDATE`, `DO UPDATE SET`, `SELECT ... INTO var`), built-in set functions (`generate_series`, `unnest`), literals and comments. A CTE name is a source only inside the query that declares its `WITH` (and in its own body only under `RECURSIVE`); a write target is always the real table, so `WITH t AS (...) UPDATE t ...` updates the module's `t`. `;`-separated statements are each qualified. (Module codes with a hyphen, e.g. `crm-fin`, cannot be schema-qualified by hand in raw SQL; use the structured built-ins, which accept `module.entity`.)
 2. **Use `@param` placeholders** for values — NEVER concatenate user input into SQL strings. The engine auto-parameterizes.
 3. **SELECT, INSERT, UPDATE, DELETE all work** via `query()`. For reads, it returns row arrays. For writes, it executes the statement.
 4. **`insert()` is preferred over `query('INSERT ...')`**, `update()`/`delete()` over `query('UPDATE/DELETE ...')`, and `select()` over `query('SELECT ...')` for module entities — raw SQL skips auto-fill (PKs, audit, number sequences) and metadata validation.
@@ -731,6 +813,11 @@ be either.
 - Calling `TODAY()` or `NOW()` (uppercase) inside `execute:` — **wrong**, they're undefined there and install fails with `'TODAY' is not defined`. Use lowercase **`now()`** in `execute:`; `TODAY()`/`NOW()` are formula-only (`canExecute:`, formula columns).
 - Forgetting that `insert()` returns the full row — you can use `quote.quote_id` immediately after insert.
 - Using `[field]` inside a `query()` SQL string — **wrong**. `[field]` is resolved in JS scope, not inside SQL strings. Pass values as `@param` arguments.
+- A **function library** (`logic/functions/*.dsl`) that reads `[field]` / `params[...]` / `old[...]`, uses `[name]` alone (write `Array.of(name)`), or has a top-level statement that is not a `function` / `var` / `let` / `const` -- all refused at install. Pass values in as arguments. See *Function libraries*.
+- Keeping a **local copy** of a library function in an action (a top-level function, or a `var` of the same name outside any function) -- refused at install. Delete the copy.
+- Calling another module's function without importing it: list it under `"functions"` in `deps/<module>.json`, call it as `<module_with_underscores>.fn()`.
+- `ref cdy_hr.department` (schema form) in `params:` -- installs with no picker target. Write `ref cdy-hr.department`.
+- `'' + params[barcode]` to keep a text param text -- no longer needed.
 
 ## Internal API (advanced)
 

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

@@ -143,10 +143,13 @@ 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, except against a system module, where `{}` is a pure platform-version gate. Each entry 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) or a contract that imports only `functions`. 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`.
 
+- `functions` (optional) lists the library functions of that dependency you call: `"functions": ["roleOf"]`, called as `<module_with_underscores>.roleOf()`. Install checks each is a top-level function of the installed provider's libraries. A contract that imports only functions may declare `"entities": {}`. See *Function libraries* in `action-dsl.md`.
+- `logic/functions/*.dsl` (function libraries) is detected by presence. No `manifest.json` key declares it, and `actions` does not list it.
+
 Full schema: `dforge://schema/deps`.
 
 ## Extension entities

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

@@ -194,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

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-mcp-author/references/validation-checklist.md

@@ -135,6 +135,15 @@ For each action:
 - [ ] Referenced entities exist
 - [ ] Referenced parameters are declared in `params:`
 
+## Function libraries (`logic/functions/*.dsl`)
+
+- [ ] Only top-level `function` declarations and `var` / `let` / `const`; no other top-level statement
+- [ ] No `[field]`, `[ref].[target]`, `params[...]`, `old[...]`, and no `[name]` standing alone (use `Array.of(name)`); values come in as arguments
+- [ ] No name that is a built-in, a JS global, `schema` or starts with `__`; each name declared once across the libraries
+- [ ] No action keeps a local copy of a library function
+- [ ] Every imported function is listed under `"functions"` in `deps/<module>.json`, exists as a top-level function in the provider, and is called as `<module_with_underscores>.fn()`
+- [ ] A `ref` to another module in `params:` uses the module code (`ref cdy-hr.department`) and the module is a declared dependency
+
 ## Settings
 
 - [ ] `settings.json` exists if the module has any settings

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

@@ -10,8 +10,15 @@ module artifacts.
 
 **Before each phase:** run `dforge_module_inspect` and parse
 `files["_inspect.json"]` — never plan a patch against what you assume is there.
+For Phase 1, first present the proposed entity inventory based only on context
+already provided and get approval before any tool call; if that context is
+insufficient, ask the user for the missing information without calling tools.
+Immediately after approval, run the inspection before any file changes.
 **After each phase:** record it with
 `dforge_module_plan({ action: "complete_phase", moduleDir, phase: "N", note: "..." })`.
+If `dforge_module_inspect` or `dforge_module_plan` fails or is unavailable, stop,
+report the tool name and error to the user, and do not proceed to the next phase
+or patch files.
 
 ## Loading policy — one reference per step, at the step
 
@@ -34,6 +41,7 @@ flags, or column patterns.
 | Hide columns from a user type (column-level security) | `dforge://reference/security` (§Column-level security), `dforge://example/column-security/entities/product.json`, `dforge://example/column-security/ui/folders.json` | — |
 | Add a menu | `dforge://reference/menus`, `dforge://example/ui/menus.json` | — |
 | Add an action | `dforge://reference/action-dsl`, `dforge://example/logic/actions/mark_done.dsl`, `dforge://example/ui/actions.json` | `dforge://docs/dsl` |
+| Share helpers between actions, or call another module's functions | `dforge://reference/action-dsl` (§Function libraries): `logic/functions/*.dsl`, imports in `deps/<module>.json` | `dforge://schema/deps` |
 | Add a trigger | — | `dforge://schema/triggers`; condition syntax in `dforge://docs/dsl` |
 | Add a scheduled job | `dforge://reference/jobs` | `dforge://schema/jobs` |
 | Add a webhook | — | `dforge://schema/webhooks` |
@@ -67,6 +75,12 @@ Enough to author inline; load the linked reference for the full detail.
   size/precision. Common fixes: `number` not `integer`/`float`; `phone` not
   `phoneNumber`; `date` not `datePicker`; `timestamptz` not `datetime`; `bool`
   not `boolean`; `varchar`/`text` not `string`. → `field-types`
+- **Register dimensions are never empty.** An empty dimension refuses the
+  posting by design; do not make one optional or add a `COALESCE([x_id], 0)`
+  technical key. Variants: one `variant_id` dimension, with a default variant
+  for products without options. Untracked batch/series: a seeded default
+  record, not `0`. Optional analytics: accounting analytic slots or plain
+  columns. Ad hoc slices by an optional attribute: a report, not a dimension.
 - **Formula columns** (`columnType: "F"`): `baseDatatypeCd` required, no
   `dbDatatype`, `flags: "V"`. → `formulas`
 - **Roll-up totals** over a child set are Generated (`G`) columns with
@@ -126,7 +140,8 @@ Proposed entities (N):
 Loop with the user until they explicitly approve.
 
 **Pre-scaffold consistency checks** against `docs/DESIGN.md` — if any fail,
-surface it and go back to Phase 0c; don't silently adjust the design:
+surface it and go back to Phase 0 and re-run the design step that produced
+`docs/DESIGN.md`; don't silently adjust the design:
 
 1. Every FK in the relationship map has a corresponding field on the child.
 2. Every action's `canExecute` guard references a status value that exists.
@@ -147,13 +162,15 @@ approval, then patch. Reach for the **composite tools first**:
 
 **Field batching rule** — the only Phase 1 exception to one-at-a-time. A field
 is batchable only if ALL of: scalar primitive (string/integer/decimal/boolean/
-date), no FK or reference, no formula, and unambiguous nullability. Everything
-else goes one at a time. This never justifies batching entities, views, roles,
-actions, or reports.
+date), no FK or reference, no formula, and its nullability is stated explicitly
+by the user (required = M flag, optional = VE flag). Everything else goes one
+at a time. This never justifies batching entities, views, roles, actions, or
+reports.
 
 **Extension entities last.** `extends: "module.entity"`, `toString: null`,
 dotted manifest key. Snapshot the base entity's fields with
-`dforge_module_inspect` on the dependency dir when it's available locally;
+`dforge_module_inspect` on the dependency dir when the dependency module
+directory exists in the current workspace (check the `deps/<module>.json` path);
 otherwise document the known base fields and note that drift tracking is the
 user's responsibility.
 
@@ -209,7 +226,7 @@ must set `jobClass: 'long_running'`. `dforge_module_validate` flags violations.
 
 **3a. Default grids first.** Every entity gets a `viewType: "grid"` view with
 `dataSources: [{ entityCode, columns: [...] }]`. The scaffolder already wrote one
-per entity, so you'll often `view_modify` rather than `view_add`.
+per entity, so you'll often `dforge_view_modify` rather than `dforge_view_add`.
 
 View codes are semantic — the entity name (`feedback_item`), a plural
 (`invoices`), or descriptive (`invoices_kanban`). **Never use the literal code
@@ -279,12 +296,15 @@ stated trigger; every report's params sit on a dataset.
 ## Phase 5 — Security (5a required)
 
 1. **Inspect first.** The scaffolder pre-created `<code>.admin` with `SIUDC` on
-   every entity declared at scaffold time. It exists — don't re-create it
-   (`role_add` fails on an existing code; use `role_right_set` to amend).
+   every entity declared at scaffold time. Preserve this scaffold-generated
+   baseline role; don't re-create it (`dforge_role_add` fails on an existing
+   code; use `dforge_role_right_set` to amend). It is not an inferred user type.
 2. **Derive roles from the intake's user types and verbs.** Re-read the user-type
    sentences in `docs/REQUIREMENTS.md`. One role per distinct user type, named
-   `<code>.<user-type>`. **Forbidden:** a generic admin/contributor/viewer matrix
-   the user didn't ask for.
+   `<code>.<user-type>`. **Forbidden:** adding generic admin/contributor/viewer
+   roles or a matrix the user didn't ask for. The scaffold-generated
+   `<code>.admin` baseline is the sole exception; include its existing rights
+   when showing the actual rights matrix.
 3. **Reflect the role list back** before computing rights. Get confirmation.
 4. **Show the rights matrix as a table** (rows = entities/actions/reports,
    columns = roles, cells = rights strings), each cell explained by the verb it
@@ -332,16 +352,18 @@ When a later phase exposes a problem in an earlier one, in order:
 3. **Identify the target phase + decision.**
 4. **Get user sign-off**, including cascading impacts.
 5. **Apply the smallest tool that fits** — this overrides the phase labels:
-   `entity_field_add` over `entity_add`; `entity_field_rename` over remove+add;
-   `role_right_set` over `role_add`; `view_modify` over remove+add.
+   `dforge_entity_field_add` over `dforge_entity_add`;
+   `dforge_entity_field_rename` over remove+add;
+   `dforge_role_right_set` over `dforge_role_add`;
+   `dforge_view_modify` over remove+add.
 6. **Re-run `dforge_module_inspect`**, fix knock-on impacts, resume.
 
 **Multi-trigger rule:** if several phases expose gaps at once, resolve the
 **earliest-phase** gap first, complete its backtrack, re-inspect, then
 re-evaluate.
 
-**Rename and delete are handled for you** — `entity_field_rename`,
-`entity_field_remove`, `entity_rename`, `entity_delete` each propagate the
+**Rename and delete are handled for you** — `dforge_entity_field_rename`,
+`dforge_entity_field_remove`, `dforge_entity_rename`, `dforge_entity_delete` each propagate the
 cascade in one call. **Always apply the response's `deletes` as well as
 `files`** (or just pass `apply: true`, which guarantees it). Each tool surfaces
 what it could NOT auto-fix — reports, translations, menu labels, DSL bodies,