@dforge-core/dforge-mcp 0.2.35 → 0.2.36

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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

package/dist/server.js

@@ -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.35",
+  "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.28",
-    "@dforge-core/metadata": "^0.0.35",
+    "@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).
 
@@ -707,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 `? :`.
 
@@ -1060,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.)
@@ -1085,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/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 |
@@ -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/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/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,