@dforge-core/dforge-mcp 0.2.0 → 0.2.1

package/dist/server.js

@@ -35900,16 +35900,18 @@ var triggerAddSchema = {
   event: external_exports.enum(["insert", "update", "delete", "status_change", "any"]).describe(
     "insert/update/delete are obvious. status_change fires only when status field changes value. 'any' fires for all insert/update/delete."
   ),
-  action: external_exports.string().describe("Action code to invoke. Cross-module dotted form ('module.action') supported."),
+  action: external_exports.string().describe(
+    "Action code to invoke. The trigger binds the affected record to the action as RECORD CONTEXT \u2014 the action reads it with [field] / [pk_column], and old[field] for pre-change values. The action's entityCode MUST match this trigger's entity, and its executionMode must not be 'batch' (both rejected at pack time). Cross-module dotted form ('module.action') supported."
+  ),
   description: external_exports.string().optional(),
   condition: external_exports.string().optional().describe(
-    "Optional formula expression (same shape as canExecute) using `[field]` syntax. Single-line boolean. If omitted, trigger fires on every matching event."
+    "Optional formula expression (same shape as canExecute) using `[field]` syntax. Single-line boolean. If omitted, trigger fires on every matching event. Reference navigation (`[ref].[target]`) is REJECTED here \u2014 the event-time evaluator only reads columns of the changed row. Navigate inside the action instead."
   ),
   params: external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe(
-    "Static params merged into the action invocation alongside auto-injected record_id."
+    "STATIC params only \u2014 the literal values given here. Nothing is injected at runtime; there is no record_id param. The affected record arrives as record context ([field]), its pre-change values as old[field]."
   ),
-  async: external_exports.boolean().default(false).describe(
-    "When true, the action runs in background (recommended for slow actions). When false, runs in the same transaction \u2014 action failure rolls back the original DB change."
+  async: external_exports.boolean().default(true).describe(
+    "When true (the platform default), the action runs in background \u2014 recommended for slow actions. When false, it runs in the caller's transaction, so a failing action ROLLS BACK the user's original write."
   )
 };
 function triggerAdd(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",

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
@@ -151,6 +152,12 @@ if (open.length == 0) { exit('Nothing open', 'info') }
 info('Open invoices: ' + open.length + ', total $' + open[0].total)
 ```
 
+> **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).
 
@@ -312,7 +319,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) {
@@ -766,17 +776,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

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

@@ -37,20 +37,20 @@
 				},
 				"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/references/action-dsl.md

@@ -464,14 +464,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.