@dforge-core/dforge-mcp 0.2.0 → 0.2.2

package/package.json

@@ -1,48 +1,48 @@
 {
-  "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.0",
-  "description": "MCP server for dForge module authoring. Exposes 34 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",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/dforge-core/dforge-mcp.git"
-  },
-  "bin": {
-    "dforge-mcp": "dist/server.js",
-    "dforge-install-skills": "scripts/install-skills.mjs"
-  },
-  "files": [
-    "dist/",
-    "docs/",
-    "resources/",
-    "skills/",
-    "scripts/install-skills.mjs",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "main": "dist/server.js",
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsup",
-    "sync-schemas": "node scripts/vendor-schemas.cjs",
-    "prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "install-skills": "node scripts/install-skills.mjs"
-  },
-  "dependencies": {
-    "@dforge-core/dforge-cli": "^0.2.7",
-    "@dforge-core/metadata": "^0.0.10",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^22.20.1",
-    "tsup": "^8.5.1",
-    "typescript": "^6.0.3",
-    "vitest": "^3.2.7"
-  }
+	"name": "@dforge-core/dforge-mcp",
+	"version": "0.2.2",
+	"description": "MCP server for dForge module authoring. Exposes 34 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",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dforge-core/dforge-mcp.git"
+	},
+	"bin": {
+		"dforge-mcp": "dist/server.js",
+		"dforge-install-skills": "scripts/install-skills.mjs"
+	},
+	"files": [
+		"dist/",
+		"docs/",
+		"resources/",
+		"skills/",
+		"scripts/install-skills.mjs",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"main": "dist/server.js",
+	"engines": {
+		"node": ">=18"
+	},
+	"scripts": {
+		"build": "tsup",
+		"sync-schemas": "node scripts/vendor-schemas.cjs",
+		"prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run",
+		"install-skills": "node scripts/install-skills.mjs"
+	},
+	"dependencies": {
+		"@dforge-core/dforge-cli": "^0.2.10",
+		"@dforge-core/metadata": "^0.0.12",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"zod": "^4.4.3"
+	},
+	"devDependencies": {
+		"@types/node": "^22.20.1",
+		"tsup": "^8.5.1",
+		"typescript": "^6.0.3",
+		"vitest": "^3.2.7"
+	}
 }

package/resources/docs/conventions.md

@@ -135,15 +135,14 @@ The entity file uses the same `fields` schema as regular entities, plus an `exte
 	"fields": {
 		"customer_id": {
 			"dbDatatype": "int8",
-			"isNullable": true,
-			"flags": "EM",
+			"flags": "E",
 			"orderNum": 34,
 			"description": "Customer FK"
 		},
 		"customer": {
 			"columnType": "R",
 			"fieldTypeCd": "lookup",
-			"flags": "VEM",
+			"flags": "VE",
 			"orderNum": 35,
 			"description": "Customer",
 			"link": {
@@ -641,7 +640,6 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 		},
 		"department_id": {
 			"dbDatatype": "cuid",
-			"fieldTypeCd": "hidden",
 			"flags": "EM",
 			"orderNum": 30,
 			"description": "Department ID"
@@ -715,8 +713,7 @@ For every foreign key relationship, create TWO columns:
 ```json
 "department_id": {
 	"dbDatatype": "cuid",
-	"fieldTypeCd": "hidden",
-	"flags": "EM",
+	"flags": "E",
 	"orderNum": 30,
 	"description": "Department ID"
 }
@@ -727,7 +724,7 @@ For every foreign key relationship, create TWO columns:
 "department": {
 	"columnType": "R",
 	"fieldTypeCd": "lookup",
-	"flags": "VEM",
+	"flags": "VE",
 	"orderNum": 35,
 	"description": "Department",
 	"link": {
@@ -752,8 +749,14 @@ For every foreign key relationship, create TWO columns:
 - Reference columns use `"link"` (not `"params"`) for entity binding
 - `link.entity` = target entity code, `link.thisKey` = local FK field, `link.otherKey` = remote PK field
 - `params` is used for other purposes (e.g., dropdown `options`)
-- Hidden FK column: `flags: "EM"` (no `V` = hidden from UI)
-- Visible reference column: `flags: "VEM"`, `columnType: "R"`
+- Hidden FK column: `flags: "E"` (no `V` = hidden from UI), `flags: "EM"` when the
+  relationship is genuinely required. `M` resolves to `isNullable: false` at install, so it
+  makes the FK `NOT NULL`; omitting both leaves the column nullable, which is the default.
+  Declaring `M` alongside `"isNullable": true` fails at pack time.
+- Visible reference column: `columnType: "R"`, `flags: "VE"` — or `"VEM"` when the FK is
+  required. **Keep the two in step.** `M` is inert on a virtual column (a Reference is
+  required exactly when its hidden FK is), so `VEM` over an optional FK changes nothing but
+  reads as a required field to the next author.
 - The FK column's `dbDatatype` **MUST match the referenced PK's type** — use `cuid` for `identity`-trait PKs (`cuid` is physically `int8`, **not** a UUID). A mismatch (e.g. FK `uuid` → PK `cuid`) fails install with *"foreign key constraint … cannot be implemented"*.
 
 ---

package/resources/docs/dsl-reference.md

@@ -90,7 +90,8 @@ execute:
 ### Current record (single / each mode)
 
 - `[fieldName]` — read or write a field on the current record
-- `[refField].[targetField]` — navigate via a Reference (FK) column to a field on the linked entity
+- `[refField].[targetField]` — navigate via a Reference (FK) column to a field on the linked entity. `[refField].targetField` (bare target) is accepted as an equivalent spelling. **Single-hop only** — `[a].[b].[c]` is a compile error; use `getRecord()` / `select()` to reach past one reference
+- `old[fieldName]` — the field's value *before* the change, in an action invoked by an event trigger. Read-only; reads `null` on `insert` events and outside triggers
 
 ```dsl
 # Read
@@ -148,9 +149,18 @@ var open = query(
     { s: 'open', cid: [customer_id] }
 )
 if (open.length == 0) { exit('Nothing open', 'info') }
-info('Open invoices: ' + open.length + ', total $' + open[0].total)
+for (var i = 0; i < open.length; i++) {
+    update('fin.invoice', open[i].invoice_id, { status: 'reminded' })
+}
+info('Reminded ' + open.length + ' open invoice(s)')
 ```
 
+> **Pooled connection.** The connection is handed to another request once your
+> statement finishes — so don't leave state behind on it: `SET LOCAL` not `SET`,
+> `pg_advisory_xact_lock()` not `pg_advisory_lock()`, `ON COMMIT DROP` on temp
+> tables. Don't assume the whole action is one transaction either — that depends
+> on the execution path. Applies to `query()` only.
+
 #### `insert(entityCd, fields) → record`
 Insert a row. Returns the inserted record as a dictionary (PKs populated, defaults applied, audit columns set).
 
@@ -221,7 +231,8 @@ The result is a **read-only** snapshot — writing to it (`rec.set(...)`) throws
 
 ```dsl
 var rec = getRecord('crm.customer', [customer_id])
-info('Customer: ' + rec.name + ' — credit limit $' + rec.credit_limit)
+if (rec.credit_limit == null) { error('Customer has no credit limit set') }
+[customer_name] = rec.name
 ```
 
 #### `getRecordOrNull(entityCd, key) → record | null`
@@ -238,7 +249,7 @@ Call a stored procedure with named args. Returns the proc's result row (or rows
 
 ```dsl
 var summary = callProc('fin.compute_balance', { account_id: [account_id], as_of: now() })
-info('Balance: ' + summary.balance)
+[closing_balance] = summary.balance
 ```
 
 #### `preloadRef(fkField)`
@@ -282,6 +293,8 @@ Fractional-unit arithmetic.
 #### `info(message, opts?)`, `warn(message, opts?)`
 Queue user-facing toast. `opts.links: [{entity, id}]` adds "open record" buttons.
 
+A message is a **receipt for work the action did**, not a way to publish a computed value. An action whose only output is `info('<some computed number>')` stores nothing — it can't be audited, re-read or reported on, and the value arrives unformatted. Build a report, a formula column, or an action that writes a result record instead. See `dforge://reference/action-dsl`, *When an action is the wrong tool*.
+
 ```dsl
 info('Created PO ' + po.po_number, {
     links: [{ entity: 'purchase_order', id: po.purchase_order_id }]
@@ -312,7 +325,10 @@ sendEmail([customer_id].[email], 'order_confirmation', {
 ```
 
 #### `error(message)`
-**Throw** — aborts execution and rolls back the **entire transaction** including any prior `insert()` / writes in this `execute:` block. Use for validation failures.
+**Throw** — aborts execution immediately. Use for validation failures. Whether
+prior `insert()` / writes in this `execute:` block are rolled back **depends on the
+execution path** and is not something to rely on — validate before writing
+anything (see the anti-pattern near the end of this document).
 
 ```dsl
 if ([rating] == null || [rating] < 1 || [rating] > 5) {
@@ -448,12 +464,21 @@ if (det != null) { var r = ocrExtract([doc_file], getSetting('ocr_endpoint_url')
 #### `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.
+columns are stored as **strings** so snowflake/cuid ids > 2^53 stay exact.
+
+The target entity is resolved at build time and stored **by id**, not by code:
+`entity_cd` is only unique per module, so a bare `'invoice'` would re-resolve at click
+time against the *reader's* folder module and could land on another module's entity.
+Always qualify the code you pass (`'fin.invoice'`).
+
+`description` is optional — omit it and the link is captioned with the entity's
+`toString` evaluated against `record`, the way records are captioned everywhere else.
+An explicit `description` still wins.
 
 ```dsl
 var task = insert('workspace.task', { title: 'Follow up' })
-insert('workspace.task_note', { link: entityLink('workspace.task', task, task.title) })
+# Captioned by workspace.task's toString — no third argument needed.
+insert('workspace.task_note', { link: entityLink('workspace.task', task) })
 ```
 
 #### `flush()`
@@ -766,17 +791,28 @@ execute:
     [last_touched] = now()
 ```
 
-### ❌ Assuming `error()` skips work done above
+### ❌ Assuming you know what `error()` does to work done above
 
-`error()` rolls back the **entire transaction** including prior `insert()` calls. Don't use it to "log and continue" — it's a hard abort.
+`error()` is a hard abort — never use it to "log and continue". What happens to
+writes made *before* it is **not something you can rely on**: it depends on the
+execution path. The same script keeps the row on one path and discards it on
+another, and the difference isn't visible in the action.
 
 ```dsl
-# WRONG — the insert below is rolled back when error fires
+# WRONG — is this insert kept or discarded? Depends on the path.
 execute:
-    insert('audit_log', { event: 'attempted_close', record_id: [id] })   # rolled back!
+    insert('audit_log', { event: 'attempted_close', record_id: [id] })   # unreliable!
     if ([balance_due] > 0) { error('Cannot close — balance owing') }
 ```
 
+Whether an `error()` unwinds earlier writes turns on whether that path opened a
+transaction — for a synchronous action, on whether the entity has `auditHistory`
+**and** whether the mode is `single` (in `batch` mode nothing covers the script);
+a background action has none at all and keeps everything written before the
+failure. This is a platform defect rather than a contract — actions are intended
+to be atomic — so don't design around it either way. Write the script so the
+question never arises: validate first.
+
 ```dsl
 # RIGHT — validate first, then perform side-effects
 execute:

package/resources/schemas/domains.schema.json

@@ -0,0 +1,78 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/domains.schema.json",
+	"title": "dForge Column Domains",
+	"description": "domains.json — reusable, named semantic types. A domain bundles a base datatype, a control, sizing and a shared option list under one code; columns reference it via \"domain\": \"module_cd.domain_cd\" instead of restating the definition. Structural fields are materialized onto each column at install; options stay on the domain and resolve at metadata-load time, so a shared list is authored and translated exactly once.",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/domain"
+	},
+	"propertyNames": {
+		"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+		"description": "Domain code. Must not contain '.', which is reserved for the qualified 'module_cd.domain_cd' form."
+	},
+	"$defs": {
+		"domain": {
+			"type": "object",
+			"required": ["baseDatatypeCd"],
+			"additionalProperties": false,
+			"properties": {
+				"description": {
+					"type": "string",
+					"description": "Human-readable label. Localizable via translations/<locale>.json under domains.<domain_cd>.label."
+				},
+				"baseDatatypeCd": {
+					"type": "string",
+					"description": "Base datatype the domain stands for (e.g. string, number, date, datetime, boolean). Required — it is what consuming columns' DDL is generated from."
+				},
+				"dbDatatype": {
+					"type": "string",
+					"description": "Physical Postgres type for consuming columns (e.g. varchar, int4, numeric). Omit to let it be inferred from fieldTypeCd."
+				},
+				"fieldTypeCd": {
+					"type": "string",
+					"description": "Control used to render/edit consuming columns (e.g. dropdown, radio, flags, text, number)."
+				},
+				"maxLen": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Max length for string-backed domains."
+				},
+				"precision": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Decimal precision for numeric domains."
+				},
+				"params": {
+					"type": "object",
+					"description": "Field-type config shared by every consuming column — most importantly the 'options' list for dropdown/radio/flags. Never copied onto columns: it resolves from the domain at load time, which is what lets its labels be translated once for all consumers.",
+					"properties": {
+						"options": {
+							"type": "array",
+							"description": "Option list. Each entry is either a bare string (value doubles as label) or an object. Per-locale label/icon/color overrides live in translations/<locale>.json under domains.<domain_cd>.options.<value>.",
+							"items": {
+								"oneOf": [
+									{ "type": "string" },
+									{
+										"type": "object",
+										"required": ["value"],
+										"additionalProperties": false,
+										"properties": {
+											"value": {
+												"type": "string",
+												"description": "The stored code. Never translatable — translations match on it."
+											},
+											"label": { "type": "string" },
+											"icon": { "type": "string" },
+											"color": { "type": "string" }
+										}
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

package/resources/schemas/entity.schema.json

@@ -130,7 +130,7 @@
 				"flags": {
 					"type": "string",
 					"pattern": "^[VIEMH]*$",
-					"description": "Display flags: V=Visible, I=Identity, E=Editable, M=Mandatory, H=Hidden"
+					"description": "Display flags: V=Visible, I=Identity, E=Editable, M=Mandatory, H=Hidden. M is resolved into isNullable:false at install, so it makes the column NOT NULL; it is inert on virtual (R/S/F) and identity columns. Declaring M together with isNullable:true is rejected at pack time."
 				},
 				"isPk": {
 					"type": "boolean",
@@ -138,7 +138,7 @@
 				},
 				"isNullable": {
 					"type": "boolean",
-					"description": "Whether the column allows NULL values"
+					"description": "Whether the column allows NULL values. Omitted means true (nullable) — only an explicit false, or the M flag which resolves to it, makes the column NOT NULL. Adding it to a column that existing tenant rows leave empty aborts the upgrade."
 				},
 				"isIdentity": {
 					"type": "boolean",
@@ -209,11 +209,29 @@
 					"type": "boolean",
 					"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."
 				},
+				"domain": {
+					"type": "string",
+					"description": "Reference to a reusable column domain, qualified as 'module_cd.domain_cd' (unqualified resolves within this module, then tenant-created domains). The domain supplies dbDatatype, baseDatatypeCd, fieldTypeCd, maxLen, precision and params; declaring any of those alongside 'domain' is rejected at install. The column keeps its own description, flags, orderNum, isNullable and isPk."
+				},
 				"refFilter": {
 					"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": [
+				{
+					"title": "Domain-backed column",
+					"description": "Physical column whose datatype, control, sizing and options all come from a reusable column domain. Requires 'domain' and must NOT restate what the domain owns.",
+					"required": ["domain"],
+					"properties": {
+						"link": false,
+						"dbDatatype": false,
+						"baseDatatypeCd": false,
+						"fieldTypeCd": false,
+						"maxLen": false,
+						"precision": false,
+						"params": false
+					}
+				},
 				{
 					"title": "Data column",
 					"description": "Physical DB column (columnType 'D' or unspecified). Requires 'dbDatatype'. Must NOT have 'link'.",

package/resources/schemas/triggers.schema.json

@@ -33,24 +33,24 @@
 				"event": {
 					"type": "string",
 					"enum": ["insert", "update", "delete", "status_change", "any"],
-					"description": "DB event that fires this trigger. 'status_change' only fires when the entity's status field actually changes value. 'any' fires for all insert/update/delete."
+					"description": "DB event that fires this trigger. 'status_change' only fires when the entity's status field actually changes value. 'any' fires for all insert/update/delete. Events are raised by the row change itself, whichever path wrote it \u2014 a user edit and an action's `[field] = value` both count \u2014 except for the DSL's insert()/update()/delete()/query() builtins writing OTHER records, which raise nothing."
 				},
 				"condition": {
 					"type": "string",
-					"description": "Optional formula expression — same shape as canExecute in action DSL. Uses `[field]` syntax to reference the affected record. Single-line, evaluates to boolean. If omitted, trigger fires for every matching event."
+					"description": "Optional formula expression — same shape as canExecute in action DSL. Uses `[field]` syntax to reference the affected record. Single-line, evaluates to boolean. If omitted, trigger fires for every matching event. Reference navigation (`[ref].[target]`) is REJECTED here: the event-time evaluator only reads columns of the changed row, so a nav path would resolve to null and the trigger would misfire. Navigate inside the action instead, or denormalise the value onto the watched entity."
 				},
 				"action": {
 					"type": "string",
-					"description": "Action code to invoke. The action must NOT use record-context (`[field]`) syntax in a way that requires the original triggering record — the trigger passes the record id via params. Cross-module form 'module.action' is supported."
+					"description": "Action code to invoke. The trigger binds the affected record to the action as RECORD CONTEXT, so the action reads its columns with `[field]` (and its PK with `[pk_column]`) exactly like a UI-invoked action — no lookup needed. The action's `entityCode` MUST equal this trigger's `entity`, and its `executionMode` must not be `batch`; both are enforced at pack time. Cross-module references use the qualified form 'module.action'."
 				},
 				"params": {
 					"type": "object",
-					"description": "Optional static parameters passed to the action at invocation time. Merged with the runtime-injected `record_id` / `record_old` (if event uses old-record diff)."
+					"description": "Optional STATIC parameters passed to the action at invocation time — the literal values written here, nothing else. Nothing is injected at runtime: there is no `record_id` param. The affected record arrives as record context (`[field]`), and its pre-change values as `old[field]` on update/delete/status_change events."
 				},
 				"async": {
 					"type": "boolean",
-					"default": false,
-					"description": "When true, the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls); background failures are logged, not surfaced to the caller. When false, the action runs synchronously inside the same transaction as the triggering insert/update/delete: if the action fails (e.g. calls error()), the whole mutation rolls back and the error is returned to the caller. Keep async:false actions fast — they run on the request's transaction."
+					"default": true,
+					"description": "When true (the default), the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls); background failures are logged, not surfaced to the caller. When false, the action runs synchronously inside the same transaction as the triggering insert/update/delete: if the action fails (e.g. calls error()), the whole mutation rolls back and the error is returned to the caller — so an async:false trigger can undo the user's write. Keep async:false actions fast; they run on the request's transaction."
 				}
 			},
 			"additionalProperties": false

package/skills/dforge-mcp-author/examples/simple-todo/entities/todo_item.json

@@ -23,6 +23,7 @@
 			"dbDatatype": "varchar",
 			"fieldTypeCd": "dropdown",
 			"flags": "VEM",
+			"formula": "'medium'",
 			"maxLen": 20,
 			"orderNum": 30,
 			"description": "Priority",

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

@@ -5,6 +5,26 @@ Actions are dForge's business logic. They are scripts with three declarative blo
 Lives in: `logic/actions/<action_name>.dsl`
 Registered in: `ui/actions.json`
 
+## When an action is the wrong tool
+
+An action exists to **change something**. Its message is a receipt for work that was done — not the output itself.
+
+Do **not** write an action whose `execute:` block only reads data, computes a value and reports it with `info()`. The result is a line of text that is never stored: it can't be audited, referenced, re-read or reported on, and every reader has to re-run the action to see it again. The value also reaches the user unformatted — a raw `query()` result carries no column metadata, so money renders as `1000.0099999999999` instead of `1,000.01`.
+
+If you are about to write a `check_…`, `calculate_…` or `show_…` action, build one of these instead:
+
+| What's actually needed | Build this |
+|---|---|
+| The user needs to **see** current numbers | A **report** or a data view — both are metadata-driven, so values format correctly, and the user can return to them any time without re-running anything. |
+| A derived value **belongs to the record** | A **formula column** (`columnType: "F"`) or a roll-up — computed on read, visible on the card and in grids, filterable and sortable. |
+| The **verdict itself matters** (approvals, credit checks, compliance) | An action that **writes a result record** — e.g. `credit_check(customer, checked_at, limit, outstanding, projected, verdict, checked_by)`. Now it's auditable and reportable, and `info()` becomes a legitimate receipt with a link to the new row. |
+| The check must **block** something | A **trigger** with `async: false`, or a `canExecute:` guard on the action being gated — enforcement, not narration. |
+
+Messages stay correct for exactly two things, and both are short by nature:
+
+- a **receipt** for a mutation that just happened — `info('Created PO ' + po.po_number, { links: [...] })`
+- a **refusal** that prevented one — `error('Period is closed')`
+
 ## Structure
 
 A DSL file has up to three blocks. All are optional (but `execute:` is needed to actually do something).
@@ -126,6 +146,17 @@ var note = params[note]             // no quotes around param name in this DSL
 > `null` key **throws** (a `col = NULL` predicate can never match), and array keys are rejected —
 > loop and mutate per id instead.
 
+> **These writes raise no events.** `insert()`, `update()`, `delete()` and `query()` are the raw
+> write layer: by design they skip folder row-filters, closed-period checks and registry state, and
+> they raise no trigger or webhook events either. Only the **acted-on record's own**
+> `[field] = value` raises them — that one is indistinguishable from a user editing the same field,
+> and fires the entity's `update` / `status_change` triggers exactly as the grid does.
+>
+> So a trigger on `b` will not see `update('b', …)` from an action bound to `a`. If `b` must react,
+> put the trigger on `a` — the entity the action is bound to — or make the change through `b`'s own
+> action. The symptom when you get this wrong is a trigger that simply never fires, with nothing in
+> the log to say why.
+
 ### select() — structured multi-row reads
 
 The read counterpart to `insert()`/`update()`/`delete()`. Entity codes are metadata-validated,
@@ -174,7 +205,7 @@ var queued = select('comm.message', {
 |---|---|
 | `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. |
+| `info('message')` | Show an informational message. A **receipt for work the action did** — not a way to publish a computed value; see *When an action is the wrong tool*. |
 | `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). |
 
@@ -203,7 +234,7 @@ var queued = select('comm.message', {
 | `addDays(date, n)` | Date | Add `n` days to a date, e.g. `addDays(now(), 30)`. |
 | `nextNumber('entity')` | String | Generate next value from a number sequence. Usually not needed — platform auto-fills on `insert()`. Use for pre-generating numbers. |
 | `callProc('proc_name', { args })` | Result | Call a stored procedure. Args are passed as named parameters. |
-| `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. the result of `insert()` or `getRecord()`); its PK columns are read and stored as **strings**, so snowflake/cuid ids (> 2^53) stay exact. Optional `description` sets the link's display text. |
+| `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. the result of `insert()` or `getRecord()`); its PK columns are read and stored as **strings**, so snowflake/cuid ids (> 2^53) stay exact. The entity is resolved at build time and stored **by id** — `entity_cd` is only unique per module, so always pass a qualified code (`'fin.invoice'`). Omit `description` and the link is captioned with the entity's `toString` against `record`; an explicit `description` wins. |
 
 > **Dates: `now()` in `execute:`, `TODAY()`/`NOW()` in formulas.** The `execute:` block runs as
 > JavaScript (Jint) and exposes **lowercase `now()`** only — `TODAY()` and `NOW()` (uppercase) are
@@ -464,14 +495,49 @@ In `ui/actions.json`:
 | `entityCode` | Yes | Which entity this action applies to |
 | `executionMode` | Yes | `"single"` (default) or `"each"` — runs per record, DSL uses `[field]`; or `"batch"` — runs once, DSL uses `for x in records { ... }` with `__records` |
 | `script` | Yes | DSL script name (without path or extension — matches filename in `logic/actions/`) |
-| `isTransacted` | Recommended | `true` = all changes roll back on error; `false` = partial commits possible |
+| `isTransacted` | Recommended | `true` = the first record that fails aborts the run; `false` = the failure is reported and the loop moves to the next record. It does **not** open a transaction — see *Don't assume your action is atomic* below |
 | `orderNum` | Recommended | Display order in the action menu |
 | `isAsync` | Optional | `true` = runs in background via Hangfire, user gets completion notification |
 
+## Don't assume your action is atomic
+
+An action is **not** reliably one transaction, and `isTransacted: true` does not
+make it one — it only decides whether the first failing record aborts the run.
+Whether the writes made before a failure survive depends on the execution path:
+
+| path | mode | writes before the failure |
+|---|---|---|
+| Sync execute, entity **with** `auditHistory` | `single` | rolled back |
+| Sync execute, entity **with** `auditHistory` | `batch` | **stay committed** |
+| Sync execute, entity without it | either | **stay committed** |
+| Scheduled job | — | rolled back |
+| Background (`isAsync: true`) action | either | **stay committed** |
+
+Both "rolled back" rows are a side effect of the audit machinery opening a
+transaction the action then inherits — and in `batch` mode it opens only after the
+script has finished, so it doesn't cover the script at all. Adding or removing
+`auditHistory`, or switching between `single` and `batch`, changes whether a failed
+action leaves partial writes behind, with no change to the action itself.
+
+**This is a platform defect, not a contract** — actions are intended to be atomic,
+and this table is what happens until that lands. So don't design around either
+outcome, and don't reach for `auditHistory` as an atomicity switch.
+
+**Write actions that don't depend on it:** do all validation up front and call
+`error()` before any `insert()` / `update()`, so there is nothing to unwind either
+way.
+
 ## SQL in query() — important notes
 
 `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.
 
+> **`query()` runs on a pooled, shared connection.** Once your statement — or the
+> surrounding transaction, where there is one — finishes, that connection is
+> handed to another request. So never leave state behind on it: use `SET LOCAL`
+> rather than `SET`, `pg_advisory_xact_lock()` rather than `pg_advisory_lock()`,
+> 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.)
 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.
@@ -479,6 +545,7 @@ In `ui/actions.json`:
 
 ## Common mistakes
 
+- Writing an action that only reads, computes and prints (`info('Balance: ' + total)`) — **wrong shape**, not just wrong formatting. Nothing is stored, so nobody can re-read the answer. Use a report, a formula column, or write a result record. → *When an action is the wrong tool* (top of this file)
 - Writing `params.note` instead of `params[note]` — **wrong**. Use bracket syntax for params.
 - Writing `params["note"]` — **also wrong in DSL syntax**. Use `params[note]` without quotes.
 - Writing `update [status] = 'Draft'` (declarative style) — **wrong**. Use `[status] = 'Draft'` (assignment).

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

@@ -33,8 +33,14 @@ Most columns. They map 1:1 to a physical SQL column.
 
 Virtual N:1 lookup. No physical column. Always **paired with a hidden FK column** that does hold the physical data. Together they form the **FK+Reference pattern**.
 
+The example below is a **required** relation, so both halves carry `M`. For an optional
+one, drop it from both: FK `"E"`, Reference `"VE"`. `M` resolves to `isNullable: false`
+at install, so it is what makes the FK column `NOT NULL` — and while `M` is inert on the
+virtual Reference half, leaving it there over an optional FK reads as a required field to
+the next author. `dforge_entity_reference_add({ required })` emits both halves in step.
+
 ```json
-// Hidden FK column — physical, hidden
+// Hidden FK column — physical, hidden. "E" instead of "EM" if the relation is optional.
 "account_id": {
     "dbDatatype": "cuid",
     "flags": "EM",
@@ -175,9 +181,10 @@ inside one aggregate must point at the **same** set column, and `COUNT(*)` is re
 
 > ⛔ **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.
+> nav resolution walks N:1 references only, never a 1:N set (however many hops it is given). The
+> column silently renders **empty** on the form, grid, and reports (no error). `F` is for same-row
+> expressions (`[qty] * [price]`) and N:1 reference navigation (`[account].[name]`, and multi-hop
+> chains — see `dforge://reference/formulas`).
 
 > ⛔ **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

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

@@ -64,8 +64,10 @@ Only include what your module actually uses — not every module needs `print_te
 
 **Every reference to another entity is two columns**:
 
-1. Hidden FK column with `flags: "EM"` and `dbDatatype` matching the target PK type
-2. Visible Reference column with `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags: "VEM"`, and a `link` object pointing at the target
+1. Hidden FK column with `flags: "E"` — `"EM"` when the relation is genuinely required — and `dbDatatype` matching the target PK type
+2. Visible Reference column with `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags: "VE"` / `"VEM"` **matching the FK**, and a `link` object pointing at the target
+
+`M` resolves to `isNullable: false` at install, so it is what makes the FK column `NOT NULL` — keep the two halves in step. `dforge_entity_reference_add({ required })` emits both correctly.
 
 Plus the actual FK constraint declared in the entity's `references` block.