@dforge-core/dforge-mcp 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -4,6 +4,60 @@ All notable changes to `@dforge-core/dforge-mcp`. This project uses semver-ish
 `0.1.0-rc.N` pre-release tags; the published version is set at publish time via
 the release workflow, so committed `package.json` versions are placeholders.
 
+## 0.1.10
+
+### Schema
+- **`entity.schema.json`: `references` gains `onDelete` / `onUpdate`.** Both
+  accept `cascade` | `setNull` | `restrict` | `noAction` (omitted = `noAction`,
+  a plain FK). `setNull` requires a nullable FK column; `onUpdate` is a no-op for
+  immutable `cuid` PKs but matters for entities keyed on a natural/mutable PK.
+  The keys were already documented in the skill (0.1.6) but rejected by the
+  vendored schema — `dforge_module_validate` now accepts them.
+- **`triggers.schema.json`: clarified `async` semantics.** The description now
+  spells out that `async: false` runs the action *synchronously inside the
+  triggering transaction* (an `error()` rolls the whole mutation back and
+  surfaces to the caller), while `async: true` commits first and only logs
+  failures — so `async: false` actions must stay fast.
+
+### Skill
+- `dforge-mcp-author`: **corrected roll-up totals — use a Generated (`G`) column,
+  not a Formula (`F`) column.** Previous guidance (0.1.x) told authors to put
+  `SUM([set].[field])` in an `F` column; the formula runtime has no
+  `SUM`/`COUNT`/`AVG` and its nav resolution only walks single-hop N:1
+  references, so an `F` set-aggregate **silently renders empty** with no error.
+  The correct shape is a `G` column with `dbDatatype` + `formula` (no `link` /
+  `baseDatatypeCd`), which the installer maintains with a DB trigger on the child
+  table — stored, so it is filterable and sortable. The pre-existing rule still
+  holds: aggregate only a **physical** child column (`D`, or a same-row `G`);
+  a virtual `F`/`R`/`S` child fails install with
+  `db_error: column old.<field> does not exist`. Also documents the supported
+  aggregates (`SUM`/`COUNT`/`AVG`/`MIN`/`MAX`), empty-set results (`SUM`/`COUNT`
+  → `0`; `MIN`/`MAX`/`AVG` → `NULL`), the same-set restriction, and that
+  `COUNT(*)` is rejected in favour of `COUNT([lines])`
+  (`column-types.md`, `formulas.md`, `SKILL.md`, `validation-checklist.md`).
+
+## 0.1.9
+
+### Changed
+- Bumped `@dforge-core/metadata` to `^0.0.8` (re-vendored schemas).
+
+### Skill
+- `dforge-mcp-author`: documentation updates to the action-DSL and field-type
+  references (no tool/behavior changes).
+  - **`getRecord` throws; `getRecordOrNull` is the nullable variant.** Corrected
+    the docs: `getRecord(entityCd, key)` raises a localized "not found" error
+    instead of returning `null`, so the old `if (rec == null)` guard was dead
+    code — use `getRecordOrNull(entityCd, key)` when absence is an expected
+    outcome (optional lookup, upsert probe). Also documents compound keys
+    (`getRecord('gl.tag', { tag_group: 'REGION', tag_code: 'EU' })`), dot /
+    `.get()` field access, and that the returned snapshot is **read-only**
+    (`dsl-reference.md`, `action-dsl.md`).
+  - **`file` / `image` columns are stored as `jsonb`, not `bytea`.** Despite the
+    `binary` base datatype, the column holds a JSON metadata reference
+    (`{ storagePath, fileName, … }`) while the bytes live in file storage — the
+    field tools derive `jsonb`, so never set `dbDatatype: "bytea"`
+    (`field-types.md`).
+
 ## 0.1.8
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.9",
+	"version": "0.1.10",
 	"description": "MCP server for dForge module authoring. Exposes scaffold/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
 	"license": "MIT",
 	"homepage": "https://github.com/iash44/dForge-core",

package/skills/dforge-mcp-author/SKILL.md

@@ -110,7 +110,7 @@ Always-on cheat-sheet — enough to author inline; load the linked `references/*
 - **Flags** = letters from `V I E M H` only (no `U`/`S`/`P`): `VEM` required+visible, `VE` optional+visible, `V` read-only, `EM` hidden FK, `I` trait-provided. → `flags.md`
 - **Field types:** `fieldTypeCd` = UI control, `dbDatatype` = SQL type. **Omit `dbDatatype` on plain data columns — it's derived from `fieldTypeCd`** (`currency` → `numeric(18,2)`, `text` → `varchar`). Only set it for a **hidden FK** (no `fieldTypeCd`, so use the target PK type `cuid`) or to override size/precision. When you do set it: never the same as `fieldTypeCd`, and never `"number"` (use `int`/`bigint`/`numeric`). Common `fieldTypeCd` fixes: `number` not `integer`/`float`, `phone` not `phoneNumber`, `date` not `datePicker`. Common `dbDatatype` fixes: `timestamptz` not `datetime`/`timestamp`, `bool` not `boolean`, `varchar`/`text` not `string`. (Invalid `fieldTypeCd`/`columnType` are now rejected at authoring time.) → `field-types.md`
 - **Formula columns** (`columnType: "F"`): `baseDatatypeCd` required, no `dbDatatype`, `flags: "V"`. → `formulas.md`
-- **Roll-up totals** over a child set → Formula `F` with `SUM([set].[field])` (query-time). Never a Generated `G` column aggregating a virtual `F`/`R`/`S` child — its DB trigger reads `OLD.<field>` and install fails (`column old.<field> does not exist`). → `column-types.md`
+- **Roll-up totals** over a child set → Generated `G` column with `SUM([set].[field])` (`dbDatatype` + `formula`, no `link`/`baseDatatypeCd`); the installer maintains it with a DB trigger. **Not** a Formula `F` — an `F` set-aggregate is unsupported and silently renders empty. Aggregate only a **physical** child column (`D` or same-row `G`); a virtual `F`/`R`/`S` child fails install (`column old.<field> does not exist`). → `column-types.md`
 - **Column defaults:** entity *data* columns have **no** `defaultValue`/`default` key. Set a default via a formula (`"formula": "TODAY()"`, `"formula": "'draft'"`) or in action/trigger logic. `defaultValue` is **settings-only**. → `field-types.md`
 - **Traits:** default `["identity", "audit"]`; `audit-full` (when the user needs *who*-tracking) adds required `created_by`/`last_updated_by` with no default — if such an entity is **seeded**, set both to the System user `0` in every record, or don't seed it. → `traits.md`
 - **`toString`:** every entity needs one, `{column}` braces, e.g. `"{first_name} {last_name}"`.
@@ -209,7 +209,7 @@ Push back on verb-less answers ("admins and users" → "What does an admin do th
 2. Every action's `canExecute` guard references a status value that exists in that entity's options list.
 3. Every seed record's FK references a parent entity that also has seed data (referential integrity in load order).
 4. Every formula column uses only fields that exist on the same entity or a directly referenced entity (exactly 1 FK hop). Transitive references (2+ hops) are async and must have been flagged in the Phase 0c gap scan.
-5. Any `SUM([set].[field])` formula is flagged as version-dependent.
+5. Any set aggregate (`SUM`/`COUNT`/`AVG`/`MIN`/`MAX` over `[set].[field]`) is a Generated (`G`) column — never a Formula (`F`) column (an `F` set-aggregate silently renders empty) — and aggregates only a **physical** child column (`D` or same-row `G`), never a virtual `F`/`R`/`S` child.
 6. Every seeded entity handles audit traits: if it uses `audit-full`, every seed record sets `created_by`/`last_updated_by` to the System user `0` (else use `audit` / don't seed it) — `audit-full`'s required user columns otherwise fail seed install.
 
 Once all checks pass, present a brief summary (entity count, action count) and ask for final confirmation before calling `dforge_module_create`.
@@ -380,7 +380,7 @@ Load `dforge://reference/validation-checklist`. Run through **every section** in
 **Top install-blockers — scan these first** (each is a documented real install failure the platform validator rejects):
 
 1. **DSL dates:** `execute:` blocks use lowercase `now()`; never `TODAY()`/`NOW()` (formula-only → `'TODAY' is not defined`).
-2. **Roll-ups:** a total over a child set is a Formula (`F`) column with `SUM([set].[field])` — never a Generated (`G`) column aggregating a virtual `F`/`R`/`S` child (→ `db_error: column old.<field> does not exist`).
+2. **Roll-ups:** a total over a child set is a Generated (`G`) column with `SUM([set].[field])` (`dbDatatype` + `formula`) — never a Formula (`F`) column (an `F` set-aggregate silently renders empty). Aggregate only a **physical** child column (`D` or same-row `G`); a virtual `F`/`R`/`S` child fails install (→ `db_error: column old.<field> does not exist`).
 3. **Rights keys:** actions/reports/folders use a **colon** (`action:x`, `report:x`, `folder:x`); entities are bare or cross-module-dotted; deny by omitting the key, never `""`.
 4. **Manifest:** no `translations` key (translation files auto-discovered; non-English locales → `supportedLocales`).
 5. **Column defaults:** set via `formula` / `numberSequence` / DSL — never a `defaultValue` key on an entity field.

package/skills/dforge-mcp-author/references/column-types.md

@@ -10,9 +10,9 @@ Every column has a `columnType` (optional for the default physical type). Seven
 | `"F"` | No | **Formula column** — virtual computed value. Evaluated by the formula engine. |
 | `"A"` | Yes | **Accumulation register column** — stores posted state for accumulation registers. Advanced (accounting modules). |
 | `"L"` | Yes | **Ledger register column** — stores posted state for double-entry bookkeeping. Advanced (accounting modules). |
-| `"G"` | Yes | **Generated column** — DB-level computed aggregate (e.g. SUM over child set via trigger, or PostgreSQL `GENERATED ALWAYS AS`). The aggregated child column **must be physical** (a `D` column) — never a virtual `F`/`R`/`S` column. For a simple roll-up total, prefer `F` (see below). |
+| `"G"` | Yes | **Generated column** — DB-level computed value. Two strategies, auto-detected from the formula: a **trigger-based aggregate over a child set** (`SUM([lines].[amount])`), or a same-row PostgreSQL `GENERATED ALWAYS AS` (`[qty] * [price]`). This is the correct type for **roll-up totals over child rows** (see below). The aggregated child column **must be physical** (a `D` column, or a same-row `G`) — never a virtual `F`/`R`/`S` column. |
 
-**For most module development, you'll only use D, R, S, and F.** Types A, L, and G are for advanced accounting/registry modules that use the `postable`, `accumulation`, or `ledger` traits.
+**For most module development, you'll use D, R, S, and F.** Add `G` when you need a **roll-up total over a child set** (`SUM`/`COUNT`/`AVG`/`MIN`/`MAX`) — see below. Types A and L are for advanced accounting/registry modules that use the `postable`, `accumulation`, or `ledger` traits.
 
 ## Data columns (`columnType` omitted or `"D"`)
 
@@ -147,33 +147,43 @@ Do **not** include `dbDatatype` on formula columns (there's no physical storage)
 
 See `formulas.md` for syntax.
 
-## Roll-up totals over child rows — use `F`, not `G`
+## Roll-up totals over child rows — use `G`, not `F`
 
 To total a child set on a header (line items → order total, movements → quantity on hand),
-**use a Formula column (`"F"`) with `SUM([set].[field])`**. It is computed at query time, so it
-can reference **any** child column — including the child's own formula columns.
+**use a Generated column (`"G"`) with `SUM([set].[field])`**. The installer detects the set
+navigation and generates a database trigger on the child table that keeps the parent value current
+on every child insert/update/delete. Because the value is **physically stored**, it displays
+everywhere (grid, form, reports) and is **filterable and sortable** in queries.
 
 ```json
-// purchase_order.total_amount — query-time roll-up (installs cleanly)
+// purchase_order.total_amount — trigger-maintained roll-up
 "total_amount": {
-    "columnType": "F",
-    "fieldTypeCd": "currency",
-    "baseDatatypeCd": "number",
+    "columnType": "G",
+    "dbDatatype": "numeric(18,2)",
+    "formula": "SUM([lines].[amount])",
     "flags": "V",
     "orderNum": 90,
-    "formula": "SUM([lines].[line_total])",      // line_total may itself be a formula column
     "description": "Total Amount"
 }
 ```
 
-> ⛔ **Never make a `G` (Generated) column aggregate a virtual `F` column.** A `G` aggregate is
-> maintained by a database trigger that reads the child's `OLD`/`NEW` *physical* values. A formula
-> (`F`) column has no physical storage, so the trigger references a column that doesn't exist and
-> **install fails** with `db_error: column old.<field> does not exist`. If you need a stored
-> (`G`) aggregate over a *derived* quantity (e.g. a signed movement quantity), make that child
-> column **physical** first — either a plain `D` column written by the action logic, or a
-> same-row `G`/`GENERATED ALWAYS AS` column with a `dbDatatype` — then aggregate that. For most
-> modules a query-time `F` roll-up is the right choice; reserve `G` for high-volume stored aggregates.
+A `"G"` roll-up requires `dbDatatype` and `formula`; it must **not** have `link` or
+`baseDatatypeCd`. Supported aggregate functions: `SUM`, `COUNT`, `AVG`, `MIN`, `MAX` (`SUM`/`COUNT`
+default to `0` when there are no children; `MIN`/`MAX`/`AVG` return `NULL`). All set references
+inside one aggregate must point at the **same** set column, and `COUNT(*)` is rejected — write
+`COUNT([lines])`.
+
+> ⛔ **Do not use a Formula (`F`) column for set aggregation.** `SUM([set].[field])` in an `F`
+> column is **not supported** by the engine — the formula runtime has no `SUM`/`COUNT`/`AVG`, and
+> nav resolution only walks single-hop N:1 references, never a 1:N set. The column silently renders
+> **empty** on the form, grid, and reports (no error). `F` is for same-row expressions
+> (`[qty] * [price]`) and single-hop reference navigation (`[account].[name]`) only.
+
+> ⛔ **The aggregated child column must be physical.** A `G` trigger reads the child's `OLD`/`NEW`
+> physical values, so aggregating a **virtual** child column (`F`/`R`/`S`) fails at install with
+> `db_error: column old.<field> does not exist`. To roll up a *derived* quantity (e.g. a signed
+> movement amount), make that child column physical first — a plain `D` column written by action
+> logic, or a same-row `G`/`GENERATED ALWAYS AS` column with a `dbDatatype` — then aggregate that.
 
 ## Quick reference: which columnType do I use?
 
@@ -183,6 +193,6 @@ can reference **any** child column — including the child's own formula columns
 - **"Compute full_name from first_name + last_name"** → `"F"`
 - **"User picker" (points to admin.user)** → omit `columnType`, use `fieldTypeCd: "user"` (writes user ID directly, no paired FK)
 - **"Polymorphic link to any entity"** → omit `columnType`, use `fieldTypeCd: "entitylink"` (stored as JSON)
-- **"Roll-up total over child rows"** (line items → header total, movements → quantity on hand) → `"F"` with `SUM([set].[field])` (query-time; see "Roll-up totals" above). Reserve `"G"` for high-volume *stored* aggregates, and only over a **physical** child column — never over an `F` column.
+- **"Roll-up total over child rows"** (line items → header total, movements → quantity on hand) → `"G"` with `SUM([set].[field])` (trigger-maintained, stored; see "Roll-up totals" above). Aggregate only a **physical** child column — never an `F`/`R`/`S` column. Do **not** use `"F"` for set aggregation — it silently renders empty.
 - **"Accumulation register state"** → `"A"` (advanced accounting — requires `postable` + `accumulation` traits)
 - **"Double-entry ledger state"** → `"L"` (advanced accounting — requires `postable` + `ledger` traits)

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

@@ -83,19 +83,32 @@ FORMAT([created_date], "yyyy-MM-dd")
 - `NULLIF(a, b)` — null if equal, else a
 - `ISNULL(x)` — boolean null check
 
-### Aggregation (on set columns)
+### Aggregation over a child set — use a Generated (`G`) column, not `F`
 
-- `COUNT([set_column])` — count related rows
-- `SUM([set_column].[field])` — sum a child field over a set
+- `SUM([set].[field])` — sum a child field over a set
+- `COUNT([set])` — count related rows (`COUNT(*)` is rejected)
 - `AVG`, `MIN`, `MAX` similarly
 
-Put set aggregations in a **Formula (`F`) column** — they evaluate at query time and may reference
-any child column, including the child's own formula columns, e.g. `SUM([lines].[line_total])`.
+> ⚠️ **Set aggregation is NOT a Formula (`F`) feature.** `SUM([set].[field])` in an `F` column is
+> unsupported by the engine — the formula runtime has no `SUM`/`COUNT`/`AVG`, and nav resolution
+> only walks single-hop N:1 references, never a 1:N set. It silently renders **empty** (no error).
 
-> ⛔ Do **not** put a `SUM([set].[field])` in a **Generated (`G`)** column unless `field` is a
-> *physical* (`D`) column. A `G` aggregate is maintained by a DB trigger that reads the child's
-> `OLD`/`NEW` physical values; aggregating a virtual `F` child fails at install with
-> `db_error: column old.<field> does not exist`. See `column-types.md` → "Roll-up totals over child rows".
+Put set aggregations in a **Generated (`G`) column** instead. The installer detects the set
+navigation and maintains the value with a database trigger on the child table. The aggregated
+child column must be **physical** (a `D` column, or a same-row `G`) — never a virtual `F`/`R`/`S`
+column, which fails at install with `db_error: column old.<field> does not exist`. Full details
+and the JSON shape: `column-types.md` → "Roll-up totals over child rows — use `G`, not `F`".
+
+```json
+"total_amount": {
+    "columnType": "G",
+    "dbDatatype": "numeric(18,2)",
+    "formula": "SUM([lines].[amount])",
+    "flags": "V",
+    "orderNum": 90,
+    "description": "Total Amount"
+}
+```
 
 ## Navigation (dot notation)
 

package/skills/dforge-mcp-author/references/validation-checklist.md

@@ -7,7 +7,7 @@ Run through this checklist **before** declaring a module complete. Always start
 These five have each caused a real install failure. Check them before the section-by-section pass:
 
 - [ ] **DSL dates** — `execute:` blocks use lowercase `now()`, never `TODAY()`/`NOW()` (formula-only; otherwise install fails `'TODAY' is not defined`)
-- [ ] **Roll-up totals** — a sum over a child set is a Formula (`F`) column with `SUM([set].[field])`, **not** a Generated (`G`) column over a virtual `F`/`R`/`S` child (otherwise `db_error: column old.<field> does not exist`)
+- [ ] **Roll-up totals** — a sum over a child set is a Generated (`G`) column with `SUM([set].[field])` (`dbDatatype` + `formula`, no `link`/`baseDatatypeCd`), **not** a Formula (`F`) column (an `F` set-aggregate silently renders empty). The aggregated child column must be physical (`D` or same-row `G`) — never a virtual `F`/`R`/`S` child (otherwise `db_error: column old.<field> does not exist`)
 - [ ] **Rights keys** — actions/reports/folders use a **colon** (`action:x`, `report:x`, `folder:x`); entities bare or cross-module-dotted; deny by omitting the key, never `""`
 - [ ] **Manifest** — no `translations` key (auto-discovered; non-English locales go in `supportedLocales`)
 - [ ] **Column defaults** — set via `formula` / `numberSequence` / DSL, never a `defaultValue` key on an entity field