@dforge-core/dforge-mcp 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -4,6 +4,112 @@ 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.11
+
+> Release prerequisite: publish `@dforge-core/metadata@0.0.9` first (adds the
+> `avatar`/`markdown` field types to the runtime registry — until then the field
+> tools reject them), then `pnpm install` + `sync-schemas` here.
+
+### Skill
+
+- **Action DSL: `select()` / `update()` / `delete()` documented.**
+  `select('module.entity', {columns, filter, orderBy, limit, offset})` is the
+  structured multi-row read: canonical `{c,o,v}`/`{g,i}` filter JSON (same
+  operators as data views), one-hop nav paths `'ref.target as alias'` that emit
+  LEFT JOINs, **fail-loud** semantics (unknown column/operator/nav path throws —
+  unlike UI filters, which drop the condition), and no folder row-filter/column
+  security (it hits the table directly; filter nav paths instead of `R`
+  columns). `update()`/`delete()` take a scalar PK **or** a `{col: val}` object
+  key (string ids coerced to the PK storage type; array and null keys rejected).
+  `query()` is repositioned as the escape hatch (aggregates, multi-hop joins,
+  CTEs, `FOR UPDATE`). New real example: `comm.dispatch_messages` (cron-scan
+  `select()` + scalar-key `update()`). Also documents `exit(message?, level?)` —
+  the DSL's early-return — and the rule to always qualify entity codes
+  (`update('comm.message', …)`) (`action-dsl.md`, `jobs.md`, `SKILL.md`).
+- **Formula date family completed + SQL-time parity** (`formulas.md`). Adds the
+  missing `WEEKDAY`, `DATE`, and period-boundary functions (`STARTMONTH`,
+  `ENDMONTH`, `STARTQUARTER`, `ENDQUARTER`, `STARTYEAR`, `ENDYEAR`,
+  `STARTNEXTMONTH` — optional arg defaults to today) and corrects
+  `DATEADD`/`DATEDIFF` signatures (string-literal units `'DAY'`/`'HOUR'`/
+  `'MINUTE'`/`'SECOND'`/`'MONTH'`/`'YEAR'`; `DATEDIFF(d1, d2, unit)` = `d2 − d1`).
+  The whole family now evaluates identically client-side and SQL-time (reports,
+  filters, sorts) — the server SQL translator gained the full set, so
+  `DATEDIFF([due_date], TODAY(), 'DAY')` no longer comes back NULL in reports.
+- **Field types** (`field-types.md`): added `avatar` (initials circle +
+  optional photo via `params.imageColumn`), `markdown` (Write/Preview editor,
+  distinct from `richtext` WYSIWYG — the alias table previously mapped
+  `markdown` → `richtext`, now wrong), and `list` (card-list rendering of a 1:N
+  set, sibling of `grid`).
+
+### Resources
+
+- **`dforge://reference/dsl` (`resources/docs/dsl-reference.md`) caught up with the
+  engine**: documents `select()`, `update()`, `delete()` (previously absent — the
+  reference stopped at `query()`/`insert()`), plus `entityLink()`, the
+  qualify-entity-codes rule, and scalar-vs-object key semantics.
+
+### Schema
+
+- **`entity.schema.json` re-vendored** (from `@dforge-core/metadata@0.0.9`):
+  `fieldTypeCd` enum gains `avatar`, `markdown`, `list`; `refFilter` description
+  now documents `@[field]` dynamic placeholders (resolved against the current
+  record at option load; an unset placeholder drops the condition, and lookups
+  re-resolve options on every open).
+
+## 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/dist/server.js

@@ -31180,6 +31180,7 @@ var AGG_TYPE_LIST = Object.values(AggType);
 // node_modules/@dforge-core/metadata/dist/field-types.js
 var fieldTypes = [
   { cd: "text", name: "Text", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+  { cd: "avatar", name: "Avatar Name", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "email", name: "Email", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "phone", name: "Phone", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "url", name: "URL", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
@@ -31198,6 +31199,7 @@ var fieldTypes = [
   { cd: "color", name: "Color Picker", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: 20, precision: null, useStringInFilter: false },
   { cd: "image", name: "Image", columnType: "D", baseDatatypeCd: "binary", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
   { cd: "file", name: "File", columnType: "D", baseDatatypeCd: "binary", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "markdown", name: "Markdown", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "richtext", name: "Rich Text Editor", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "lookup", name: "Lookup", columnType: "R", baseDatatypeCd: "guid", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: true },
   { cd: "user", name: "User Picker", columnType: "D", baseDatatypeCd: "cuid", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
@@ -31355,7 +31357,7 @@ function expandTraits(traitCds, entityName) {
 
 // node_modules/@dforge-core/metadata/dist/derive.js
 var NUMERIC_TOTAL = 18;
-var TEXT_BACKED = /* @__PURE__ */ new Set(["textarea", "richtext", "code"]);
+var TEXT_BACKED = /* @__PURE__ */ new Set(["textarea", "markdown", "richtext", "code"]);
 var DB_DATATYPE_OVERRIDE = {
   file: "jsonb",
   image: "jsonb"

package/package.json

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

package/resources/docs/conventions.md

@@ -562,7 +562,7 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 - `schedule` — five fields, minute granularity (sub-minute schedules are rejected at install)
 - `timeout` — required, in seconds, range `(0, 3600]`
 - `timeout > 300` requires `"class": "long_running"` (the standard pool is capped at 300s)
-- Referenced action must NOT use `[field]` or `for x in records` — scheduled fires have no record context. Install fails fast if it does. Use `query()` / `insert()` for table-level work.
+- Referenced action must NOT use `[field]` or `for x in records` — scheduled fires have no record context. Install fails fast if it does. Use `select()` / `insert()` / `update()` for table-level work.
 - Max 50 jobs per module
 - Optional `timeZone` (IANA name) overrides `auth.tenant.time_zone` for that job
 - Use `paused: true` to freeze a job during incidents — admin "Run now" still works while the cron path is silent

package/resources/docs/dsl-reference.md

@@ -130,10 +130,13 @@ execute:
 
 ---
 
-## Built-in functions (30)
+## Built-in functions
 
 All exposed by `ActionScriptEngine.cs` as host globals — no `import` needed.
 
+> **Entity codes: always qualify** (`'comm.message'`, not `'message'`) in every data
+> built-in, even inside the owning module.
+
 ### Database & data
 
 #### `query(sql, params?) → array`
@@ -168,6 +171,46 @@ var po = insert('purchase_order', { supplier_id: params[supplier].supplier_id })
 insert('po_line', { po_id: po.purchase_order_id, product_id: [product_id], qty: 1 })
 ```
 
+#### `select(entityCd, opts?) → array`
+Structured multi-row read — the counterpart to `insert()`/`update()`/`delete()`; prefer
+it over `query()` for row-shaped reads. `opts` (all optional): `columns` (paths; a
+one-hop nav path `'ref.target as alias'` LEFT JOINs the referenced entity; formula
+columns translate to SQL; default = all physical columns), `filter` (canonical
+`{c,o,v}`/`{g,i}` filter JSON, nav paths allowed), `orderBy` (`'-'` prefix =
+descending; default = PK), `limit`, `offset`. **Fail-loud:** an unknown column,
+operator, or nav path throws instead of silently dropping the condition. Hits the
+table directly (no folder row-filter / column security); a plain reference (`R`)
+column can't be selected or string-filtered — use the FK column or a nav path.
+`query()` remains the escape hatch (aggregates, multi-hop joins, CTEs, `FOR UPDATE`).
+
+```dsl
+var queued = select('comm.message', {
+    columns: ['message_id', 'to_addr', 'to_point.value as point_value', 'subject'],
+    filter: { g: 'and', i: [
+        { c: 'status', o: '=', v: 'queued' },
+        { c: 'channel', o: '=', v: 'email' }
+    ] },
+    orderBy: ['message_id'],
+    limit: 10
+})
+```
+
+#### `update(entityCd, key, fields) → int`
+Update the row(s) matched by `key`; returns rows affected. Refreshes update-phase
+server defaults (audit `last_updated` / `last_updated_by`) and coerces values like
+`insert()`. `key` is a scalar PK (`update('task', 42, {…})`) or an object
+(`{ task_id: 42 }`; multiple entries for a compound key). Scalar string ids are
+coerced to the PK storage type (snowflake-as-string binds `int8`). A null key
+**throws**; array keys are rejected — loop and mutate per id.
+
+```dsl
+update('comm.message', msg.message_id, { status: 'sent', sent_at: now() })
+```
+
+#### `delete(entityCd, key) → int`
+Delete the row(s) matched by `key`; returns rows affected. Same key shapes and
+rules as `update()`.
+
 #### `getRecord(entityCd, key) → record`
 Fetch a single record by key. **Throws** a localized "not found" error if no row
 matches — the safe default for a lookup that should always resolve (e.g. an FK you
@@ -376,6 +419,17 @@ if (!result.isValid) { error('Validation failed: ' + result.errors[0]) }
 
 ### Utility
 
+#### `entityLink(entityCd, record, description?) → link value`
+Build a clickable link to any entity record for storing in an `entitylink` (jsonb)
+column. `record` is a row object (e.g. from `insert()` / `getRecord()`); its PK
+columns are stored as **strings** so snowflake/cuid ids > 2^53 stay exact. Optional
+`description` sets the display text.
+
+```dsl
+var task = insert('workspace.task', { title: 'Follow up' })
+insert('workspace.task_note', { link: entityLink('workspace.task', task, task.title) })
+```
+
 #### `flush()`
 Commit pending changes mid-script AND broadcast SSE updates to connected clients. **Async / background actions only** — in sync actions, everything commits at the end automatically.
 

package/resources/schemas/entity.schema.json

@@ -120,10 +120,10 @@
 				"fieldTypeCd": {
 					"type": "string",
 					"enum": [
-						"text", "email", "phone", "url", "textarea", "number", "currency", "percent",
+						"text", "avatar", "email", "phone", "url", "textarea", "number", "currency", "percent",
 						"checkbox", "date", "datetime", "time",
 						"dropdown", "flags", "tags", "json", "hidden", "color", "image", "file",
-						"richtext", "lookup", "user", "grid", "entitylink", "code"
+						"markdown", "richtext", "lookup", "user", "grid", "list", "entitylink", "code"
 					],
 					"description": "UI field type code from field_type table"
 				},
@@ -210,7 +210,7 @@
 					"description": "On a self-referencing reference column (R column whose link.entity is the owning entity), set true to ALLOW parent/child cycles. When absent the self-reference is treated as an acyclic hierarchy and DB-level guards reject loops. Ignored on non-self-referencing columns."
 				},
 				"refFilter": {
-					"description": "Filter criteria for reference lookups"
+					"description": "Filter criteria for reference lookups. Condition values support @[field] placeholders resolved against the current record at lookup time (e.g. {\"c\":\"channel\",\"o\":\"eq\",\"v\":\"@[channel]\"} narrows options to rows matching the record's own channel); a condition whose placeholder is unset is dropped rather than matching nothing."
 				}
 			},
 			"oneOf": [

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`.
@@ -274,7 +274,7 @@ For each trigger, propose: entity + event + (optional) condition formula + targe
 Load the "scheduled job" row from the Loading policy table (`dforge://reference/jobs` + `dforge://schema/jobs`).
 
 Constraints baked into the tool:
-- Action MUST NOT use record-context (`[field]`) syntax — jobs run as system user with NO current record. Wrap any record-context action in a thin job-friendly action that uses `query()` to fetch the records it needs.
+- Action MUST NOT use record-context (`[field]`) syntax — jobs run as system user with NO current record. Wrap any record-context action in a thin job-friendly action that uses `select()` (or `query()`) to fetch the records it needs.
 - `timeout` is required, ≤ 3600s.
 - If `timeout > 300`, you MUST set `jobClass: 'long_running'`.
 
@@ -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/action-dsl.md

@@ -106,11 +106,68 @@ var note = params[note]             // no quotes around param name in this DSL
 | Function | Returns | Description |
 |---|---|---|
 | `insert('entity', { field: value, … })` | Inserted row object | Insert a new record. Returns the full row including auto-filled columns (PK, audit, number sequences). Access returned fields with `result.field_name`. |
-| `query('SQL', { arg: value })` | Array of row objects | Execute parameterized SQL. Use `@argName` placeholders. Schema-qualified table names (`crm.contact`). Access row fields with `row.field_name` or `row['field_name']`. |
-| `getRecord('entity', key)` | Row object | Fetch a single record by key (qualified `module.entity` supported). `key` is a scalar PK or an object for a compound key (`{ col_a: 1, col_b: 'x' }`). Access fields with `rec.field_name` (or `rec.get('field_name')`). **Throws** a localized "not found" error if absent. |
+| `select('entity', opts?)` | Array of row objects | Structured multi-row read — see "select()" below. `opts` = `{columns, filter, orderBy, limit, offset}`, all optional. Prefer over `query()` for row-shaped reads. |
+| `update('entity', key, { field: value, … })` | Rows affected (number) | Update the row(s) matched by `key`. Refreshes update-phase server defaults (audit `last_updated` / `last_updated_by`) and coerces values like `insert()`. |
+| `delete('entity', key)` | Rows affected (number) | Delete the row(s) matched by `key`. |
+| `query('SQL', { arg: value })` | Array of row objects | Execute parameterized SQL. Use `@argName` placeholders. Schema-qualified table names (`crm.contact`). Access row fields with `row.field_name` or `row['field_name']`. **Escape hatch** — prefer `select()`/`update()`/`delete()` when the structured shape fits. |
+| `getRecord('entity', key)` | Row object | Fetch a single record by key. Access fields with `rec.field_name` (or `rec.get('field_name')`). **Throws** a localized "not found" error if absent. |
 | `getRecordOrNull('entity', key)` | Row object or `null` | Like `getRecord`, but returns `null` instead of throwing when the row is absent — use for an expected-absence lookup, guarded with `if (rec == null)`. |
 | `preloadRef('fk_column')` | Row object | Load the referenced record for a FK column. Access its fields with `ref.get('field')`. |
 
+> **Entity codes: always qualify.** Every data built-in (`select`, `insert`, `update`, `delete`,
+> `getRecord`, `nextNumber`) accepts a qualified `module.entity` code — write `update('comm.message', …)`,
+> not `update('message', …)`, even inside the owning module. It reads unambiguously and keeps the
+> script correct if it's ever moved to a bridge module.
+
+> **Keys: scalar or object.** In `update()` / `delete()` / `getRecord()` / `getRecordOrNull()`,
+> `key` is either a scalar PK value (`update('task', 42, {…})` — single-column PK only) or an
+> object (`{ task_id: 42 }`; multiple entries for compound keys). Scalar **string** ids are coerced
+> to the PK's storage type, so a snowflake id carried as a string binds as `int8`, not text. A
+> `null` key **throws** (a `col = NULL` predicate can never match), and array keys are rejected —
+> loop and mutate per id instead.
+
+### select() — structured multi-row reads
+
+The read counterpart to `insert()`/`update()`/`delete()`. Entity codes are metadata-validated,
+values are parameterized and type-coerced per column, and reference navigation replaces
+hand-written LEFT JOINs. A bare `select('entity')` reads every physical column of every row,
+ordered by PK.
+
+```javascript
+var queued = select('comm.message', {
+    columns: ['message_id', 'to_addr', 'to_point.value as point_value', 'subject'],
+    filter: { g: 'and', i: [
+        { c: 'status', o: '=', v: 'queued' },
+        { c: 'channel', o: '=', v: 'email' },
+        { g: 'or', i: [
+            { c: 'to_addr', o: '!null' },
+            { c: 'to_point.value', o: '!null' }
+        ] }
+    ] },
+    orderBy: ['message_id'],
+    limit: 10
+})
+// queued = [{ message_id: 123, to_addr: null, point_value: 'a@b.c', subject: '…' }, …]
+```
+
+| Option | Shape | Notes |
+|---|---|---|
+| `columns` | array of strings | Column paths. A one-hop nav path `'ref.target'` LEFT JOINs the referenced entity; `' as alias'` renames the key in the returned rows (avoids bracket-indexed `row['ref.target']` access). Formula columns are translated to SQL. Defaults to all physical columns. |
+| `filter` | object | The platform's canonical filter JSON — `{c, o, v}` conditions inside `{g, i}` groups, same operators as data views (`=`, `!=`, `>`, `in`, `start`, `contains`, `null`, `!null`, `between`, …; see `filters.md`). Nav paths work here too. |
+| `orderBy` | array of strings | Column paths; `'-'` prefix for descending (`['-message_id']`). Defaults to the PK for deterministic results. |
+| `limit` / `offset` | int | Positive / non-negative. |
+
+- **Fail-loud:** unlike UI filters (which drop untranslatable conditions with a warning),
+  `select()` **throws** on an unknown column, unknown operator, or unresolvable nav path — a
+  silently narrowed filter in an action means processing the wrong rows.
+- **Low-level:** like the other data built-ins, `select()` hits the table directly — no folder
+  row-filter, column security, or reference display machinery. A plain reference (`R`) column has
+  no value here; select its FK column or a nav path (the error message says which). String
+  operators on a reference column are rejected for the same reason — filter a nav path like
+  `'customer.company_name'` instead.
+- `query()` remains the escape hatch for anything this shape can't express: aggregates, multi-hop
+  joins, CTEs, `FOR UPDATE`.
+
 ### Messaging
 
 | Function | Description |
@@ -118,6 +175,7 @@ var note = params[note]             // no quotes around param name in this DSL
 | `error('message')` | **Abort** the action and show an error to the user. Rolls back all changes. |
 | `warn('message')` | Show a warning but continue execution. |
 | `info('message')` | Show an informational message. |
+| `exit('message'?, 'level'?)` | **Stop the script early without error** — changes made so far are kept. Level `'info'` (default) or `'warn'` styles the message. This is the DSL's early-return: a bare `return` is not valid at the top level of `execute:`. |
 | `notify(userId, 'message')` | Send an in-app notification to a specific user. First arg is a user ID (typically `[owner_id]` or similar). |
 
 ### Email
@@ -315,6 +373,42 @@ execute:
     info('Received ' + poLines.length + ' line(s) from PO ' + [po_number])
 ```
 
+> The two `query()` reads and the raw `query('UPDATE …')` above predate `select()`/`update()` —
+> today each would be a structured call (`select('wms.stock', { filter: … })`,
+> `update('wms.stock', stockId, { quantity: newQty })`).
+
+### select() + update() with a scalar key (cron-scan dispatch)
+
+From `modules/comm/logic/actions/dispatch_messages.dsl` (a scheduled-job action — no record context):
+
+```
+execute:
+    var queued = select('comm.message', {
+        columns: ['message_id', 'to_addr', 'to_point.value as point_value', 'subject', 'body_html', 'body_text', 'attempt_count'],
+        filter: { g: 'and', i: [
+            { c: 'status', o: '=', v: 'queued' },
+            { c: 'channel', o: '=', v: 'email' }
+        ] },
+        orderBy: ['message_id'],
+        limit: 10
+    })
+
+    if (queued.length == 0) {
+        exit('No queued messages', 'info')
+    }
+
+    for (var i = 0; i < queued.length; i++) {
+        var msg = queued[i]
+        sendEmail(msg.to_addr || msg.point_value, msg.subject, msg.body_html || msg.body_text || '')
+
+        update('comm.message', msg.message_id, {
+            status: 'sent',
+            sent_at: now(),
+            attempt_count: (msg.attempt_count || 0) + 1
+        })
+    }
+```
+
 ## Execution modes
 
 Actions run in one of two modes, declared in `ui/actions.json`:
@@ -376,10 +470,12 @@ In `ui/actions.json`:
 
 ## SQL in query() — important notes
 
-1. **Table names are schema-qualified** within the module: `crm.contact`, `wms.stock_movement`, `fin.invoice`. Use the module code as the schema prefix.
+`query()` is the **escape hatch** — reach for it only when the structured built-ins can't express the read/write (aggregates, multi-hop joins, CTEs, `FOR UPDATE`). For row-shaped work prefer `select()` / `insert()` / `update()` / `delete()`: they validate entity codes against metadata, coerce values per column, and (for `insert`/`update`) maintain auto-fill and audit columns.
+
+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.)
 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 ...')`** for inserting into module entities — it handles auto-fill (PKs, audit, number sequences). Use raw `query('INSERT ...')` only for cross-module or system tables.
+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.
 
 ## Common mistakes
 
@@ -387,7 +483,10 @@ In `ui/actions.json`:
 - Writing `params["note"]` — **also wrong in DSL syntax**. Use `params[note]` without quotes.
 - Writing `update [status] = 'Draft'` (declarative style) — **wrong**. Use `[status] = 'Draft'` (assignment).
 - Writing `insert('entity', field1, value1)` (positional args) — **wrong**. Use `insert('entity', { field: value })` (object).
-- Writing `query('entity', filter)` (filter object) — **wrong**. `query()` takes raw SQL strings with `@param` placeholders.
+- Writing `query('entity', filter)` (filter object) — **wrong**. `query()` takes raw SQL strings with `@param` placeholders. A structured read is `select('entity', { filter: … })`.
+- Passing an **array of ids** as the `key` of `update()`/`delete()` — **rejected**. Loop over the ids and mutate one at a time.
+- Selecting or string-filtering a plain reference (`R`) column in `select()` — **throws**. Use the FK column or a nav path (`'customer.company_name'`).
+- Unqualified entity codes (`update('message', …)`) — works inside the owning module but **always prefer the qualified form** (`update('comm.message', …)`).
 - Forgetting `var` in loops — `for (i = 0; ...)` creates a global. Always `for (var i = 0; ...)`.
 - Using ES6 syntax (`const`, `let`, `=>`, template literals) — **may not work**. Jint supports ES5.1 primarily. Stick to `var`, `function`, string concatenation with `+`.
 - 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).

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/field-types.md

@@ -15,11 +15,13 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 | `fieldTypeCd` | `baseDatatypeCd` | Description | Common `dbDatatype` | Params |
 |---|---|---|---|---|
 | `text` | `string` | Single-line text | `varchar` (with `maxLen`) | `maxLen` |
+| `avatar` | `string` | Person/company name rendered as an initials circle; optional photo. | `varchar` | `imageColumn` (an `image` column on the same entity to use as the photo) |
 | `email` | `string` | Email address. Client-side format validation. | `varchar` 250 | — |
 | `phone` | `string` | Phone/telephone. | `varchar` 50 | — |
 | `url` | `string` | Web URL. | `varchar` 500 | — |
 | `textarea` | `string` | Multi-line plain text. | `text` | `defaultLines`, `maxLines` |
-| `richtext` | `string` | Rich text editor (HTML). | `text` | — |
+| `markdown` | `string` | Markdown editor (Write/Preview tabs), rendered sanitized. | `text` | — |
+| `richtext` | `string` | Rich text WYSIWYG editor, stores sanitized HTML. | `text` | — |
 | `code` | `string` | Code editor with syntax highlighting. | `text` | `language` |
 | `dropdown` | `string` | Fixed list of options. | `varchar` | `options: ["a","b",…]` or `[{value,label,icon,color}]` |
 | `flags` | `string` | Multiple checkboxes with letter flags. | `varchar` | `optionSets`, `style: "buttons"` |
@@ -67,6 +69,7 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 | `lookup` | `guid` | `R` | Reference to another entity (always paired with a hidden FK column — see SKILL.md "FK+Reference pattern") |
 | `user` | `cuid` | `D` | User picker. Writes a user ID directly, no paired FK needed. |
 | `grid` | `set` | `S` | Detail grid of related records (1:N backwards reference). Used with `link` declaring the relation. |
+| `list` | `set` | `S` | Detail list — same 1:N set as `grid`, rendered as a card list instead of a table. |
 | `entitylink` | `json` | `D` | Polymorphic link to any entity (stores `{entity, id}` pair). Populate from action DSL with the `entityLink('entityCd', record, description?)` built-in (see `action-dsl.md`). |
 
 ## JSON
@@ -137,7 +140,8 @@ These are the field type names LLMs tend to invent. **They are all wrong.**
 | `picture`, `photo` | `image` |
 | `attachment` | `file` |
 | `multiline` | `textarea` |
-| `richText`, `markdown` | `richtext` |
+| `md` | `markdown` |
+| `richText`, `wysiwyg`, `html` | `richtext` |
 | `userPicker` | `user` |
 | `phoneNumber` | `phone` |
 

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

@@ -70,10 +70,15 @@ FORMAT([created_date], "yyyy-MM-dd")
 
 - `TODAY()` — current date
 - `NOW()` — current datetime with timezone
-- `YEAR(d)`, `MONTH(d)`, `DAY(d)` — date parts
+- `YEAR(d)`, `MONTH(d)`, `DAY(d)` — date parts (`MONTH` is 1-based)
 - `HOUR(dt)`, `MINUTE(dt)`, `SECOND(dt)` — time parts
-- `DATEADD(d, count, unit)` — add time (unit: `day`, `month`, `year`, `hour`, `minute`)
-- `DATEDIFF(a, b, unit)` — difference between dates
+- `WEEKDAY(d)` — day of week, `0` = Sunday
+- `DATE(y, m, d)` — build a date from parts; `DATE(v)` casts a value to a date
+- `DATEADD(d, count, unit)` — add time; unit is a **string literal**: `'DAY'`, `'HOUR'`, `'MINUTE'`, `'SECOND'`, `'MONTH'`, `'YEAR'` (plural forms accepted)
+- `DATEDIFF(d1, d2, unit)` — difference `d2 − d1` in the given unit (same unit list). `DAY`/`HOUR`/`MINUTE`/`SECOND` floor the elapsed time; `MONTH`/`YEAR` are calendar-component deltas. E.g. days overdue: `DATEDIFF([due_date], TODAY(), 'DAY')`
+- `STARTMONTH(d?)`, `ENDMONTH(d?)`, `STARTQUARTER(d?)`, `ENDQUARTER(d?)`, `STARTYEAR(d?)`, `ENDYEAR(d?)`, `STARTNEXTMONTH(d?)` — period boundaries; the argument is optional and defaults to today
+
+The whole date family evaluates identically **client-side and SQL-time** (reports, filters, sorts on formula columns) — the SQL translator mirrors the client runtime, including `MONTH` 1-based and `WEEKDAY` 0=Sunday. Unit arguments must be string literals; an unknown unit fails loud with the accepted list.
 
 ### Logical functions
 
@@ -83,19 +88,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).
+
+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`".
 
-> ⛔ 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".
+```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/jobs.md

@@ -62,7 +62,7 @@ Scheduled actions run with **no record bound**. Specifically:
 - `notify()` writes to inbox only (no live SSE in Phase 1)
 - `sendEmail()` raw mode only in Phase 1
 
-**Record context is forbidden.** The install pipeline rejects any action whose compiled DSL references `[field]` or `for x in records { … }` — those compile to `__r.` / `__records.` which would `ReferenceError` at fire time. Refactor to operate via `query()` / `insert()`:
+**Record context is forbidden.** The install pipeline rejects any action whose compiled DSL references `[field]` or `for x in records { … }` — those compile to `__r.` / `__records.` which would `ReferenceError` at fire time. Refactor to operate via `select()` / `insert()` / `update()`:
 
 ```
 execute:
@@ -132,7 +132,7 @@ Full source: [`modules/chore/`](../../../modules/chore/).
 ## Common mistakes
 
 - **Cross-module action reference.** A job in `crm` cannot reference an action in `fin`. Declare a thin `crm.run_fin_thing` action in your own module and bind the job to that.
-- **Record-bound action.** Any `[field]` or `for x in records` in the DSL fails install — the action has no record at fire time. Refactor to `query()`/`insert()`.
+- **Record-bound action.** Any `[field]` or `for x in records` in the DSL fails install — the action has no record at fire time. Refactor to `select()`/`insert()`/`update()`.
 - **Missing `timeout`.** Required, no default. Pick 30 s if you don't know; bump when you have evidence.
 - **`timeout > 300` without `class: "long_running"`.** Install fails. Heavy jobs are an explicit opt-in.
 - **Sub-minute cron.** The scheduler ticks every 60 s. Anything finer is dishonest — declare a minute cron.

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