@dforge-core/dforge-mcp 0.2.5 → 0.2.15

package/CHANGELOG.md

@@ -4,6 +4,190 @@ All notable changes to `@dforge-core/dforge-mcp`. This project uses semver-ish
 `0.1.0-rc.N` pre-release tags; the published version is set at publish time via
 the release workflow, so committed `package.json` versions are placeholders.
 
+## 0.2.15
+
+`canExecute` became a real server-side gate and `isTransacted` began opening a real
+transaction (platform change `5398a48b0`). Both had been documented here as the
+opposite — "a UI hint" and "does not open a transaction" — so this release is a
+correction pass across the authoring guidance, with no tool or schema changes.
+
+### Changed — `canExecute` is enforced, with a fail-open subset
+
+`action.execute` now evaluates the stored `can_execute_parsed` AST over every targeted
+record before any write and refuses the call with `ACTION_EXECUTION_FAIL`. So
+`canExecute: false` is a genuine "only automation may fire this" — the scheduler and
+triggers invoke the script engine directly and still bypass it.
+
+The server evaluator is a scalar walker, not the formula engine, and the client has its
+own separate gaps, so `references/action-dsl.md` and `dsl-reference.md` now carry a tier
+table instead of a single list:
+
+| tier | construct | client | server |
+|---|---|---|---|
+| 1 | **comparisons** (`=` `!=` `<` `<=` `>` `>=`) between fields and literals, combined with `AND` / `OR` / `NOT`; a bare `true` / `false` | evaluates | **enforces** |
+| 2 | arithmetic, `IN`, `BETWEEN`, any formula function | evaluates | fail-open |
+| 3 | ref navigation, `SUM` / `COUNT` / `AVG`, any unknown function (a typo included) | **fail-open (throws)** | fail-open |
+| — | `$[setting]` references | **evaluates as null** (no throw) | fail-open |
+
+Four things in there are easy to get wrong and are called out explicitly:
+
+- **A bare boolean field is not enforced.** The walker evaluates conditions, not values —
+  a field resolves only as an operand of a comparison — so `canExecute: [is_active]` and
+  `NOT [is_blocked]` fail open. Write `[is_active] = true` and `NOT ([is_blocked] = true)`.
+- **A misspelled function ships silently.** A `canExecute` is never validated against the
+  function set at install (`FindUnknownFunctions` is wired only into the formula-column
+  path), so `TOADY()` installs and enables the button for every record.
+- **Tier 3 mixed into a predicate is worse than useless**, because the two sides disagree
+  about short-circuiting: the server's `AND` / `OR` short-circuit, the client's evaluator
+  does not. `[status] = 'Pending' AND COUNT([lines]) > 0` on a non-`Pending` record throws
+  in the browser, is caught, and **enables** the button — then the server refuses the call.
+  An error where a greyed-out button was wanted. Count with a Generated (`G`) column and
+  compare the scalar. Mixing tier 1 with tier 2 is fine and is the normal shape.
+- **Settings do not work in `canExecute` at all** — the client resolver is stubbed to
+  `null` and the server has none, so the guard is unenforced server-side and tends to jam
+  the button *shut* client-side. Read them in `execute:`.
+
+`references/jobs.md` also stops promising that `canExecute: false` hides the button: the
+action stays in the toolbar, permanently disabled.
+
+### Changed — `isTransacted` opens a transaction, and defaults to `true`
+
+The *Don't assume your action is atomic* section is replaced by *Atomicity*. `true` now
+makes the whole run one transaction in both execution modes, covering the script's own
+`insert()` / `update()` / `query()` calls as well as the flush of `[field] = …`
+assignments, and it no longer depends on the entity carrying `auditHistory` — advice to
+reach for that trait as an atomicity switch is gone.
+
+`false` is documented per mode, because "failures are isolated" only ever made sense where
+there is a loop: `single` / `each` report the failure and continue with the next record,
+while a `batch` script is one invocation, so a failure just ends the run with its earlier
+writes committed and its `[field]` assignments never flushed.
+
+The background path is the exception, and it splits by mode too: the worker opens no
+transaction, so nothing is ever undone; its `single` / `each` loop still reads the flag for
+control flow, while its `batch` path never reads it at all — a queued `batch` action gets
+nothing from `isTransacted` in either direction.
+
+### Fixed — `isAsync` does not force background execution, and there is no Hangfire
+
+`isAsync: true` only *permits* queuing. The server branches on the `async` argument the
+request carries, so a parameterless action is queued directly while one with parameters is
+offered to the user as both "Run" (inline, transactional) and "Run in Background". Whether
+an action is atomic is therefore not answerable from the manifest alone.
+
+Two claims that dForge runs background actions "via Hangfire" are removed — the platform
+uses a hosted `BackgroundService` polling `background_action`, and `FileCleanupService`
+says so in as many words.
+
+### Changed — validation checklist
+
+Two new items under actions: that a `canExecute` meant to *gate* is written in the
+server-enforced subset, and that no bare boolean field is used as a whole condition. The
+`references/formulas.md` entry for `canExecute:` blocks now summarises the same rules and
+points at `action-dsl.md`.
+
+## 0.2.14
+
+Record reports — a report attached to an entity so it opens **from a record**, with the
+record's values feeding its parameters — plus a report-level home for report parameters,
+and the removal of two parameter spellings the installer never read.
+
+Requires `@dforge-core/metadata` ≥ 0.0.15 (bumped): the vendored
+`resources/schemas/reports.schema.json` served as `dforge://schema/reports` comes from
+there.
+
+### Added — record-report attachments
+
+A report in `ui/reports.json` gains an `entities` array. Each entry attaches the report to
+one entity, mapping report parameters to source columns on it:
+
+```jsonc
+"credit_check": {
+    "entities": [
+        { "entityCd": "parties.party", "params": { "customer_id": "party_id" }, "orderNum": 45 },
+        { "entityCd": "crm.quote",     "params": { "customer_id": "customer_id" }, "orderNum": 45 }
+    ]
+}
+```
+
+The report then appears on that record's toolbar and opens on a record-scoped route with
+the mapped params resolved server-side and hidden. `dforge_report_add` accepts and
+documents the block; `references/reports.md` gains a **Record reports** section with the
+rules (source-column allowlist, type compatibility, one attachment per (entity, report)
+pair, the `"metadata": ">=1.5.0"` gate, and the cross-module dependency bound).
+
+Note the two different `params` keys, which the tool description now calls out: on an
+attachment it is the *mapping* (param code → column); on the report or a dataset it is the
+*declaration*.
+
+### Added — `dforge_module_validate` checks reports
+
+Mirrors the server's new pack-time `ReportAttachmentValidator`, so these fail offline
+instead of at install against a live tenant:
+
+- a mapped param code neither the report-level `parameters` block nor any dataset declares;
+- a source column the entity doesn't have, or one that's a set / formula / free-text column;
+- two attachments to the same entity in one report (the second overwrites the first);
+- an attachment to a cross-module entity whose module isn't a declared dependency;
+- `isRequired`, a top-level `link`, or `fieldTypeCd` + `domain` together on a param;
+- a warning when a module ships attachments with no `metadata` dependency.
+
+### Added — report-level `parameters`
+
+Report parameters are **report-scoped**: the declaration is stored once per report
+(`report.param_set_id` → `param_set`), the authoring API is `report.params.save`, and
+`report.get` flattens per-dataset defaults report-wide before use. The installer had only
+ever read the per-dataset shorthand, so a report-level block was silently dropped and the
+report installed with no parameters at all — which is what made
+`crm-fin.customer_statement` and `wms-fin.vendor_statement` ship parameterless.
+
+Both declaration sites are now legal and mean the same thing; the installer merges them,
+**report level winning** on a code collision:
+
+```jsonc
+"customer_statement": {
+    "parameters": {
+        "customer_id": { "label": "Customer", "fieldTypeCd": "lookup",
+                         "params": { "link": { "entity": "parties.party" } }, "required": true }
+    },
+    "datasets": { "statement_invoices": { }, "statement_payments": { } }
+}
+```
+
+Declare at report level when several datasets use the parameter — `customer_statement` is
+exactly that case, and there is no meaningful dataset to attribute it to.
+`datasets.<cd>.params` stays the right shorthand for a single-dataset parameter, and every
+module written before this keeps working.
+
+`dforge_module_validate` merges both sites when resolving a record-report mapping, so a
+mapping onto a report-level parameter resolves exactly as install will resolve it.
+
+### Fixed — two report-param spellings that are silently ignored
+
+Unlike `parameters`, these are simply misspellings of keys that already exist, so they are
+gone from the schema rather than implemented — and the validator flags them at either
+declaration site:
+
+- **`isRequired`** — the key is `required`; the parameter installed as optional.
+- **top-level `link`** on a lookup parameter — it belongs under `params`; the parameter
+  installed with no autocomplete.
+
+`references/reports.md` also corrects the rights-key example from `report.<code>` to the
+colon form `report:<code>`, and the lookup parameter config from `params.entityCd` to
+`params.link.entity`.
+
+### Changed — steer calculation toward reports, not the DSL
+
+`action-dsl.md`'s *When an action is the wrong tool* now names the record report as the
+direct replacement for a `check_…` action — same toolbar entry point, but the user sees
+the open invoices and the ageing rather than just "FAILED" — and adds the general rule:
+**do not compute in the DSL what a report dataset already aggregates.** Sums, ratios,
+ageing buckets and exposure get formatting, drill-through, row caps and live re-reads for
+free from a report; DSL arithmetic over `select()` reproduces that badly, once, somewhere
+nothing else can reuse. Write DSL when the number must be *written down* or must *stop*
+something. The same steer is in `dsl-reference.md`, Phase 2a and Phase 3c of the
+`dforge-module-build` skill, and the validation checklist.
+
 ## 0.2.5
 
 Catches up with the platform's parameter-options work (dForge-core 1.20.0). A dropdown

package/dist/server.js

@@ -31002,7 +31002,7 @@ var import_node_crypto = require("crypto");
 var fs2 = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.13/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.14/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -31214,7 +31214,7 @@ function buildZedSettings() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.14/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.15/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -35146,9 +35146,20 @@ var reportAddSchema = {
     description: external_exports.string(),
     layout: external_exports.record(external_exports.string(), external_exports.unknown()),
     datasets: external_exports.record(external_exports.string(), external_exports.unknown()),
-    parameters: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+    parameters: external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe(
+      "Report-level parameter declarations \u2014 the canonical home for a param, and the only one that fits a param several datasets use. Merged with each dataset's `params` into the report's one param set; this block wins on a code collision."
+    ),
+    entities: external_exports.array(
+      external_exports.object({
+        entityCd: external_exports.string(),
+        params: external_exports.record(external_exports.string(), external_exports.string()).optional(),
+        orderNum: external_exports.number().int().optional()
+      }).passthrough()
+    ).optional().describe(
+      "RECORD-REPORT attachments \u2014 entities this report can be opened FROM, so it appears on the record's toolbar with the record's values feeding its params. Each entry: { entityCd, params: { <reportParamCd>: <sourceColumnOnThatEntity> }, orderNum? }. NOTE `params` here is the MAPPING (param \u2192 column), not a param declaration. Qualify a cross-module entityCd ('parties.party') and declare that module as a dependency. Source columns: the PK, a reference ('R') column, or a bounded scalar \u2014 never text/json/file. Requires 'metadata': '>=1.5.0' in the manifest."
+    )
   }).passthrough().describe(
-    "Full report spec per reports.schema.json: { description, layout: { panels: [...] }, datasets: { code: {...} }, parameters? }."
+    "Full report spec per reports.schema.json: { description, layout: { panels: [...] }, datasets: { code: {...} }, parameters?, entities?, reloadInterval? }. PARAMS ARE REPORT-SCOPED: declare them in the top-level `parameters` block, or as shorthand under `datasets.<cd>.params` when exactly one dataset uses the param \u2014 the installer merges both into the report's single param set, report level winning on a collision. A param several datasets use belongs at report level; there is no meaningful dataset to attribute it to. Within a param, use `required` (not `isRequired`) and nest a lookup's binding as `params: { link: { entity } }` (not a top-level `link`)."
   )
 };
 function reportAdd(args) {
@@ -35919,6 +35930,119 @@ function moduleValidate(args) {
       `folder code '${code2}' is used ${dupPaths.length} times (${dupPaths.join(", ")}). Codes must be unique across the whole tree: role rights say 'folder:${code2}' with no path, and translations key on 'folders.${code2}.label', so duplicates are ambiguous and silently collide.`
     );
   }
+  for (const [rcode, rawReport] of Object.entries(reports)) {
+    const report = rawReport ?? {};
+    const where = `ui/reports.json \u2192 ${rcode}`;
+    const declaredParams = /* @__PURE__ */ new Set();
+    const checkParamDef = (loc, pcode, pdef) => {
+      const p = pdef ?? {};
+      if ("isRequired" in p) {
+        err(
+          `${where} \u2192 ${loc}.${pcode}`,
+          "uses 'isRequired', which the installer does not read \u2014 the param installs as OPTIONAL. Rename it to 'required'."
+        );
+      }
+      if ("link" in p) {
+        err(
+          `${where} \u2192 ${loc}.${pcode}`,
+          'puts \'link\' at the top level, where the installer does not read it \u2014 a lookup param with no `params.link` has no autocomplete. Nest it: "params": { "link": { "entity": "\u2026" } }.'
+        );
+      }
+      if ("fieldTypeCd" in p && "domain" in p) {
+        err(
+          `${where} \u2192 ${loc}.${pcode}`,
+          "declares both 'fieldTypeCd' and 'domain' \u2014 install rejects the pair rather than picking a winner. A domain supplies the control; drop the fieldTypeCd."
+        );
+      }
+    };
+    const reportParams = report.parameters ?? {};
+    for (const [pcode, pdef] of Object.entries(reportParams)) {
+      declaredParams.add(pcode);
+      checkParamDef("parameters", pcode, pdef);
+    }
+    const datasets = report.datasets ?? {};
+    for (const [dcode, ds] of Object.entries(datasets)) {
+      const dsParams = ds?.params ?? {};
+      for (const [pcode, pdef] of Object.entries(dsParams)) {
+        declaredParams.add(pcode);
+        checkParamDef(`datasets.${dcode}.params`, pcode, pdef);
+      }
+    }
+    const attachments = report.entities;
+    if (attachments === void 0) continue;
+    if (!Array.isArray(attachments)) {
+      err(where, "'entities' must be an array of record-report attachments.");
+      continue;
+    }
+    const seen = /* @__PURE__ */ new Set();
+    for (const raw of attachments) {
+      const att = raw ?? {};
+      const entityCd = att.entityCd;
+      if (typeof entityCd !== "string" || entityCd.trim() === "") {
+        err(where, "an entry in 'entities' is missing 'entityCd'.");
+        continue;
+      }
+      const bare = entityCd.startsWith(`${manifest.code}.`) ? entityCd.slice(manifest.code.length + 1) : entityCd;
+      if (seen.has(bare)) {
+        err(
+          where,
+          `attaches to '${entityCd}' twice. One attachment per (entity, report) pair \u2014 merge the two 'params' maps into a single entry.`
+        );
+        continue;
+      }
+      seen.add(bare);
+      if (!isKnownEntity(entityCd)) {
+        err(
+          where,
+          `attaches to '${entityCd}', which is not a known entity (same-module, system, or a declared cross-module dependency). Qualify a foreign entity as 'module.entity' and add that module to the manifest's dependencies.`
+        );
+      }
+      const paramMap = att.params ?? {};
+      for (const [paramCd, source] of Object.entries(paramMap)) {
+        if (!declaredParams.has(paramCd)) {
+          err(
+            where,
+            `maps '${paramCd}' from '${entityCd}.${String(source)}', but '${paramCd}' is not a declared parameter of this report. Declare it in the report's 'parameters' block, or under the 'params' of the dataset that consumes it.`
+          );
+          continue;
+        }
+        if (typeof source !== "string" || source.trim() === "") {
+          err(where, `maps parameter '${paramCd}' from an empty source column on '${entityCd}'.`);
+          continue;
+        }
+        const fields = fieldDefsOf[bare];
+        if (!fields) continue;
+        const col = fields[source];
+        if (!col) {
+          err(
+            where,
+            `maps parameter '${paramCd}' from '${entityCd}.${source}', which is not a column of that entity.`
+          );
+          continue;
+        }
+        if (col.columnType === "S" || col.columnType === "F") {
+          err(
+            where,
+            `maps parameter '${paramCd}' from '${entityCd}.${source}', a ${col.columnType === "S" ? "set ('S')" : "formula ('F')"} column. Map the PK, a reference ('R') column, or a bounded scalar.`
+          );
+          continue;
+        }
+        const db = typeof col.dbDatatype === "string" ? col.dbDatatype.toLowerCase() : "";
+        if (col.columnType !== "R" && col.isPk !== true && /^(text|json|jsonb|bytea|uuid)$/.test(db)) {
+          err(
+            where,
+            `maps parameter '${paramCd}' from '${entityCd}.${source}' (dbDatatype '${db}'), which is not a valid record-report parameter source. Allowed: the entity PK, a reference column, or a bounded scalar (number, date/datetime, bool, dropdown/radio/flags code).`
+          );
+        }
+      }
+    }
+    if (seen.size > 0 && !deps.has("metadata")) {
+      warn(
+        where,
+        `declares record-report attachments but the manifest has no 'metadata' dependency. The 'entity_report' table ships with the metadata system module \u2014 add "metadata": ">=1.5.0" to dependencies so install fails loudly on a platform without it, rather than the attachment quietly doing nothing.`
+      );
+    }
+  }
   const roleCodes = Object.keys(roles);
   const localeFiles = fs11.existsSync(paths.translationsDir) ? fs11.readdirSync(paths.translationsDir).filter((f) => f.toLowerCase().endsWith(".json")).sort() : [];
   for (const raw of supportedLocales) {

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.5",
+	"version": "0.2.15",
 	"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",
-	"packageManager": "pnpm@11.21.0",
+	"packageManager": "pnpm@11.22.0+sha512.1ff870c4c6133dfd88fb2afc46dd13d47f09c9794b438c6fdb47ca98caf3bc16381ee0be93a091b8e3824cf01f889f46d7d9e20910fb0be1ab0fb5baa80dd621",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/dforge-core/dforge-mcp.git"
@@ -35,8 +35,8 @@
 		"install-skills": "node scripts/install-skills.mjs"
 	},
 	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.13",
-		"@dforge-core/metadata": "^0.0.14",
+		"@dforge-core/dforge-cli": "^0.2.14",
+		"@dforge-core/metadata": "^0.0.15",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"zod": "^4.4.3"
 	},

package/resources/docs/dsl-reference.md

@@ -14,7 +14,8 @@ params:
 
 canExecute:
     # Single-expression formula returning boolean
-    # Determines whether the action button is enabled for current record(s)
+    # Enables/disables the button AND is re-checked server-side on execute
+    # (see "canExecute is enforced, with a fail-open subset")
 
 onBeforeStart:
     # Pre-queue initialization (async / background actions only)
@@ -396,12 +397,68 @@ For "who did this", prefer the platform audit columns (`created_by` /
 predicates in `canExecute:` or a formula column, use `CURRENT_USER_ID()`, which
 the server translates to an exact `::bigint` SQL literal.
 
+> **The table above is about `execute:` (JavaScript).** The *formula* engine —
+> `canExecute:`, formula columns, filters, reports — keeps large integer literals
+> exact: the parser holds them as 64-bit integers and serializes anything past
+> 2^53 as text so the browser cannot round it. `canExecute: [owner_id] = 215117312238288897`
+> compares against the id you wrote. `CURRENT_USER_ID()` is still the better way to
+> say "mine" — it does not hard-code an id — but a literal is no longer a
+> correctness trap on that side.
+
+## canExecute is enforced, with a fail-open subset
+
+`canExecute:` is evaluated **twice**: by the browser to decide whether the button
+is **enabled** (the action stays in the toolbar, greyed out — it is not hidden),
+and by `action.execute` over every targeted record before any write. A
+record in the wrong state is refused with `ACTION_EXECUTION_FAIL`, so the predicate
+is a gate rather than a UI hint, and `canExecute: false` is the way to make an
+action fireable only by a trigger or a scheduled job (both invoke the script engine
+directly and bypass the check).
+
+**Both evaluators have gaps, and both fail open**, but not the same gaps. The
+server is a scalar walker and lets anything richer through. The client implements
+the whole documented formula function set, so ordinary functions evaluate there
+normally; it throws — and its `catch` **enables** the button — on ref navigation,
+on the set aggregates `SUM` / `COUNT` / `AVG` (deliberately not formula functions;
+counting belongs in a Generated `G` column), and on any name it does not know, a
+typo included — a `canExecute:` is never validated against the function set at
+install, so `TOADY()` ships and enables the button for every record.
+`$[setting]` references are a separate case again: they do not throw, the client
+resolver is stubbed to `null`, and the server has no settings resolver — so a
+settings-dependent guard is unenforced server-side and resolves unpredictably in
+the browser. Read settings in `execute:` instead.
+
+| tier | construct | client | server |
+|---|---|---|---|
+| 1 | **comparisons** (`=` `==` `!=` `<>` `>` `>=` `<` `<=`) between `[field]`s and literals, combined with `AND` / `OR` / `NOT`; a bare `true` / `false` | evaluates | **enforces** |
+| 2 | arithmetic, `IN`, `BETWEEN`, any formula function (`TODAY`, `IF`, `DATEADD`, `REGEX_MATCH`, `CURRENT_USER_ID`, …) | evaluates | fail-open |
+| 3 | ref navigation, `SUM` / `COUNT` / `AVG`, any unknown function (a typo included) | **fail-open (throws)** | fail-open |
+| — | `$[setting]` references | **evaluates as null** (no throw) | fail-open |
+
+**A bare boolean column is not tier 1.** The walker evaluates conditions, not
+values — a `[field]` resolves only as an operand of a comparison — so
+`canExecute: [is_active]` and `canExecute: NOT [is_blocked]` fail open. Write
+`[is_active] = true` and `NOT ([is_blocked] = true)`. A bare `false` is fine: it is
+a complete condition, which is what makes the `canExecute: false` idiom work.
+
+Tier 1 + tier 2 is the normal shape and behaves correctly: the client evaluates the
+whole predicate so the button state is right, and the server short-circuits `AND` /
+`OR` so the tier-1 half is still enforced.
+
+**Tier 3 is what breaks.** The server short-circuits, the client does not, so
+`[status] = 'Pending' AND COUNT([lines]) > 0` on a non-`Pending` record still
+evaluates `COUNT` in the browser, throws, and the button is **enabled** — then the
+server refuses the call. A `canExecute:` is not validated against the function set
+at install, so that spelling ships silently. Count with a `G` column and compare the
+scalar; denormalise instead of navigating; put the rest in `execute:` behind
+`error()`.
+
 ### Messaging & notifications
 
 #### `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*.
+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 **record report** (a report with an `entities` attachment: it lands on the same record toolbar, but shows the numbers *and* the rows behind them, re-read live on every open), a formula column, or an action that writes a result record instead. Do not compute in DSL what a report dataset already aggregates. See `dforge://reference/action-dsl`, *When an action is the wrong tool*, and `dforge://reference/reports`.
 
 ```dsl
 info('Created PO ' + po.po_number, {

package/resources/schemas/data-views.schema.json

@@ -247,11 +247,51 @@
 			"additionalProperties": false
 		},
 
+		"calculatedMember": {
+			"type": "object",
+			"description": "A synthetic, read-only member of a pivot-like view — a row (default) or column derived by a formula over other members at each cross-axis position. Platform-generic: any pivot-like surface consumes the same shape, so a module declares the metric in config with no platform code change. Pure presentation — no storage, evaluated client-side by the stock formula engine.",
+			"required": ["key", "label", "refs", "formula"],
+			"properties": {
+				"key": { "type": "string", "description": "Stable render key. Must not collide with a real member key." },
+				"axis": { "type": "string", "enum": ["row", "column"], "default": "row", "description": "Which axis the member is added to. A calculated ROW is a formula over other rows evaluated once per column; a calculated COLUMN is the transpose." },
+				"label": { "type": "string", "description": "Member label shown in the row/column head." },
+				"field": { "type": "string", "description": "Value field the refs read. Defaults to the surface's first value field." },
+				"refs": {
+					"type": "object",
+					"description": "Formula bracket-alias → referenced member identity on the same axis.",
+					"additionalProperties": { "type": "string" }
+				},
+				"formula": { "type": "string", "description": "Formula over the aliases, e.g. `[gp] / [rev] * 100`. Same `[name]` syntax as column formulas. A non-finite result (÷0, missing denominator) renders empty." },
+				"position": {
+					"description": "Placement on the axis. Defaults to the end.",
+					"oneOf": [
+						{ "type": "object", "required": ["after"], "properties": { "after": { "type": "string", "description": "Key of the member to place this one after." } }, "additionalProperties": false },
+						{ "type": "object", "required": ["at"], "properties": { "at": { "type": "string", "enum": ["end"] } }, "additionalProperties": false }
+					]
+				},
+				"depth": { "type": "integer", "minimum": 0, "description": "Indent depth (row members only; 0 = top level)." },
+				"format": {
+					"type": "object",
+					"description": "Display format for the result.",
+					"properties": {
+						"style": { "type": "string", "enum": ["number", "percent"], "default": "number" },
+						"decimals": { "type": "integer", "minimum": 0, "default": 1 }
+					},
+					"additionalProperties": false
+				}
+			},
+			"additionalProperties": false
+		},
 		"matrixViewConfig": {
 			"type": "object",
 			"description": "Matrix (pivot) view: rowAxis × colAxis grid with a value-source cell entity holding one record per (rowKey, colKey).",
 			"required": ["rowAxis", "colAxis", "cell"],
 			"properties": {
+				"calculatedMembers": {
+					"type": "array",
+					"description": "Synthetic read-only members derived by formula over OTHER members' values (e.g. a Gross Margin % row). Spliced into the rendered axis; never loaded or saved.",
+					"items": { "$ref": "#/$defs/calculatedMember" }
+				},
 				"rowAxis": {
 					"description": "Row axis values: an entity's records ('dataset') or a column's dropdown options ('dropdown').",
 					"oneOf": [

package/resources/schemas/manifest.schema.json

@@ -133,6 +133,12 @@
 			"items": { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$" },
 			"description": "Non-English locales the package promises to translate. Each entry MUST match a translations/<locale>.json file, and every translatable resource (entity/field labels, folders, views, menus + items, actions + params, reports + datasets + params, settings) MUST have a label in that file. English is the default — don't list 'en' or 'en-US'."
 		},
+		"features": {
+			"type": "array",
+			"items": { "type": "string", "enum": ["report-security"] },
+			"uniqueItems": true,
+			"description": "Opt-in platform behaviours this package was authored for. Absent or empty = the pre-feature behaviour for all of them, so a module written before a feature existed keeps working until its author declares it and republishes. Unknown names are REJECTED at package load, never ignored — a misspelled feature would silently leave the old behaviour in place while the manifest claims otherwise. Values: 'report-security' = this module's reports require 'E' on their sec_object; declare the matching \"report:<code>\": \"E\" grants in security/roles.json first, or the reports go dark for every role."
+		},
 		"created": {
 			"type": "string",
 			"format": "date",

package/resources/schemas/reports.schema.json

@@ -24,10 +24,42 @@
 					"description": "Map of dataset code → dataset definition. Panels reference datasets by code via `datasetCd`.",
 					"additionalProperties": { "$ref": "#/$defs/dataset" }
 				},
+				"reloadInterval": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Auto-refresh interval in seconds. Omit (or 0) for no auto-refresh."
+				},
 				"parameters": {
 					"type": "object",
-					"description": "Report-level parameters (alternative to per-dataset `params`). Map of param code → param definition.",
+					"description": "Report-level parameter declarations — the canonical home for a parameter, and the only one that fits a parameter several datasets use. Parameters are report-scoped throughout the platform: one `param_set` per report, `report.params.save` in the authoring API, and `report.get` flattens per-dataset defaults report-wide before use. A parameter declared under a dataset's `params` is shorthand for declaring it here; the installer merges both into one set, with this block winning on a code collision.",
 					"additionalProperties": { "$ref": "#/$defs/paramDef" }
+				},
+				"entities": {
+					"type": "array",
+					"description": "Record-report attachments: entities this report can be opened from, with the mapping from report parameter to source column on that entity. Each entry becomes one `dForge.entity_report` row. See docs/business-logic/record-reports.md.",
+					"items": { "$ref": "#/$defs/entityAttachment" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"entityAttachment": {
+			"type": "object",
+			"description": "One (entity, report) attachment. The binding is per-attachment, not per-report — the same report can attach to several entities with different parameter mappings.",
+			"required": ["entityCd"],
+			"properties": {
+				"entityCd": {
+					"type": "string",
+					"description": "Entity the report attaches to, qualified `module.entity` for anything outside the declaring module. The owning module must be this module or a declared dependency."
+				},
+				"params": {
+					"type": "object",
+					"description": "Parameter mapping: report param code → source column on the entity. Stored as `entity_report.param_map` and resolved server-side from the record's PK. Source columns are limited to the PK, reference (`R`) columns, and bounded scalars (number, date/datetime, bool, dropdown/radio/flags code); source and target must be type-compatible. Params left unmapped keep their normal behaviour (default value, or prompt the user).",
+					"additionalProperties": { "type": "string" }
+				},
+				"orderNum": {
+					"type": "integer",
+					"description": "Sort position in the record's combined action + report menu."
 				}
 			},
 			"additionalProperties": false
@@ -228,7 +260,7 @@
 				},
 				"params": {
 					"type": "object",
-					"description": "Dataset-level parameters (alternative to top-level `parameters`)",
+					"description": "Parameters declared on this dataset — shorthand for the report-level `parameters` block, convenient when exactly one dataset uses the parameter. Either way the parameter is REPORT-scoped: `ReportRegistrar` merges the report-level block and every dataset's `params` into the report's one `param_set`, so a parameter declared here serves the whole report (the param bar, saved param sets, `@param` filters in any dataset, and record-report `entities[].params` mappings). On a code collision the report-level block wins. Declare a parameter used by several datasets at report level — there is no meaningful dataset to attribute it to.",
 					"additionalProperties": { "$ref": "#/$defs/paramDef" }
 				}
 			},
@@ -330,30 +362,22 @@
 					"type": "integer",
 					"description": "Display order of the parameter in the report's parameter form. Read by ReportRegistrar (paramDef.OrderNum); falls back to declaration order when omitted."
 				},
+				"columnType": {
+					"type": "string",
+					"enum": ["R"],
+					"description": "Declares a REFERENCE parameter: its submitted value is the whole picked record rather than the bare key. The JSON counterpart of the action DSL's `paramCd: ref <entityCd>`, stored in the same `param.column_type`. Optional — omitting it (a plain `lookup`) submits the key, which is what a filter comparing against a reference column needs, since the server destructures a key object across every key column and ignores non-key fields. Declare \"R\" when the report wants the record itself, not just its identity."
+				},
 				"required": {
 					"type": "boolean",
 					"default": false,
-					"description": "Whether the user must provide a value (older modules also use `isRequired`)"
-				},
-				"isRequired": {
-					"type": "boolean",
-					"description": "Alternate spelling of `required` used by some modules. Prefer `required` for new code."
+					"description": "Whether the user must provide a value. Stored inverted as `param.is_nullable`. There is no `isRequired` spelling — `ReportParamDef` reads this key only."
 				},
 				"default": {
 					"description": "Default value applied if the user doesn't provide one"
 				},
-				"link": {
-					"type": "object",
-					"description": "Entity link for lookup-type params (alternative to nesting under `params.link`). Shape: { entity: '<code>', otherKey?: '<column>' }.",
-					"properties": {
-						"entity": { "type": "string" },
-						"otherKey": { "type": "string" }
-					},
-					"additionalProperties": false
-				},
 				"params": {
 					"type": "object",
-					"description": "Field-type-specific params (e.g. lookup → { link: { entity, otherKey } })"
+					"description": "Field-type-specific params, nested under this key — there is no top-level `link`. A `lookup` param needs `{ \"link\": { \"entity\": \"<code>\", \"otherKey\": \"<column>\" } }`; `otherKey` auto-fills from the target's PK when omitted. Without `params.link` a lookup param installs, warns, and has no autocomplete."
 				}
 			},
 			"additionalProperties": false

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

@@ -11,11 +11,14 @@ An action exists to **change something**. Its message is a receipt for work that
 
 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`.
 
+**Do not compute in the DSL what a report can compute.** Sums, ratios, ageing buckets, exposure, "how much is outstanding" — a report dataset already does aggregation, formatting, drill-through and row caps, and it re-reads live data every time it opens. DSL arithmetic over `select()` results reproduces that badly, once, in a place nothing else can reuse. Reach for the DSL when the number has to be **written down** or has to **stop** something; reach for a report when it has to be **looked at**.
+
 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. |
+| The user needs to **see** current numbers **for the record they're on** | A **record report** — a report with an `entities` attachment, which puts it on that record's toolbar and feeds its params from the record. This is the direct replacement for a `check_…` action: same entry point, but the user sees the open invoices and the ageing, not just "FAILED". See `references/reports.md`. |
+| The user needs to **see** current numbers generally | 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. |
@@ -95,7 +98,68 @@ preference:
 
 ### `canExecute:` — availability formula
 
-A formula expression (same grammar as formula columns) that evaluates to true/false. When false, the action button is hidden or disabled in the UI.
+A formula expression (same grammar as formula columns) that evaluates to true/false.
+
+**It is enforced on both sides.** The client evaluates it to decide whether the
+button is **enabled** — the action stays in the toolbar either way, greyed out
+rather than hidden. `action.execute` evaluates it again server-side over every
+targeted record, before any write, and refuses the call with
+`ACTION_EXECUTION_FAIL` when a record is in the wrong state. So it is a real gate,
+not a UI hint — a caller hitting the API directly cannot approve an
+already-rejected record.
+
+Two consequences worth designing around:
+
+- **`canExecute: false` is the idiom for an action only automation may fire.** The
+  server refuses it through `action.execute`; triggers and scheduled jobs invoke
+  the script engine directly and are unaffected.
+- **Both evaluators have gaps, and both fail open.** The server is a scalar walker
+  — comparisons between fields and literals, combined with `AND` / `OR` / `NOT`,
+  nothing else — and lets anything richer through. The client implements the full documented formula
+  function set, so ordinary functions are fine there; it throws (and its `catch`
+  **enables** the button) on **ref navigation** (`[ref].target`), on the set
+  aggregates **`SUM` / `COUNT` / `AVG`** (deliberately not formula functions —
+  counting is a Generated `G` column's job), and on **any name it does not know, a
+  typo included** — a `canExecute` is never validated against the function set at
+  install, so `TOADY()` ships and enables the button for every record.
+- **`$[setting]` references are a separate case.** They do not throw: the client's
+  resolver is stubbed to `null`, so the predicate resolves however that operator
+  treats null (an ordered comparison against null is `false`, so it tends to
+  *disable* the button), while the server has no settings resolver and fails open.
+  Keep settings out of `canExecute` and read them in `execute:` instead.
+
+| tier | construct | client | server |
+|---|---|---|---|
+| 1 | **comparisons** (`=` `!=` `<` `<=` `>` `>=`) between fields and literals, combined with `AND` / `OR` / `NOT`; a bare `true` / `false` | evaluates | **enforces** |
+| 2 | arithmetic, `IN`, `BETWEEN`, any formula function | evaluates | fail-open |
+| 3 | ref navigation, `SUM` / `COUNT` / `AVG`, any unknown function (a typo included) | **fail-open (throws)** | fail-open |
+| — | `$[setting]` references | **evaluates as null** (no throw) | fail-open |
+
+**A bare boolean column is not tier 1.** The walker evaluates conditions, not
+values — a field is only resolvable as an operand of a comparison — so
+`canExecute: [is_active]` and `canExecute: NOT [is_blocked]` fail open. Write
+`[is_active] = true` and `NOT ([is_blocked] = true)`. (`canExecute: false` is fine:
+a bare literal is a complete condition.)
+
+Mixing tier 1 and tier 2 is the normal, healthy shape: the client evaluates the
+whole thing so the button state is right, and the server short-circuits `AND` /
+`OR` so the tier-1 half is still enforced.
+
+**Tier 3 is what breaks.** The server short-circuits, the client does not — so
+`[status] = 'Pending' AND COUNT([lines]) > 0` on a non-`Pending` record still
+evaluates `COUNT` in the browser, throws, and the button is **enabled**, then the
+server refuses the call: an error where a greyed-out button was wanted. And a
+`canExecute` is not validated against the function set at install, so that spelling
+ships silently. Count with a `G` column and compare the scalar
+(`[detail_count] > 0`); denormalise instead of navigating; put anything genuinely
+unexpressible in `execute:` behind `error()`.
+
+> Never make `canExecute` the *only* guard for something that must hold. Between
+> the fail-open rules on both sides, the enqueue-only check on background runs, and
+> the fact that the client evaluates over the grid row (which does not carry
+> extension columns) while the server evaluates over a full record load, the
+> authoritative check belongs in `execute:` — validate and `error()` before the
+> first write.
 
 ```
 canExecute:
@@ -114,7 +178,7 @@ canExecute:
     [quantity] >= 0
 ```
 
-Uses formula syntax: `[field]` for field access, `=` / `!=` / `<` / `>` / `AND` / `OR` operators, `TODAY()`, etc.
+Uses formula syntax: `[field]` for field access, `=` / `!=` / `<` / `>` / `AND` / `OR` operators, `TODAY()`, etc. — but see the fail-open note above: only the scalar comparison subset is enforced server-side.
 
 **Note**: `canExecute` uses single `=` for equality (formula syntax), NOT `==` (JS syntax).
 
@@ -532,7 +596,9 @@ In `batch` mode, access individual records with `__records.get(i)`, the count wi
 
 ## Async actions
 
-For long-running actions, set `"isAsync": true` in `ui/actions.json`. The action runs in the background via Hangfire, and the user gets a completion notification via SSE. The DSL syntax is the same.
+For long-running actions, set `"isAsync": true` in `ui/actions.json`. That **permits** background execution: the call is queued as a `background_action` row and picked up by `BackgroundActionService` (a hosted `BackgroundService` polling every ~10s — there is no Hangfire in dForge), and the user gets a completion notification via SSE. The DSL syntax is the same.
+
+`isAsync` does not force it. `action.execute` carries its own `async` argument and the server branches on that, so a parameterless action is queued directly while one with parameters is offered to the user as both "Run" (inline) and "Run in Background". Note that a queued run has **no wrapping transaction** — see *Atomicity* below.
 
 ## Registering the action
 
@@ -573,37 +639,58 @@ 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` = 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 |
+| `isTransacted` | Recommended | `true` = the whole run is **one transaction**: the first failure aborts it *and* rolls back everything already written. `false` = no transaction, and what happens next depends on the mode — `single`/`each` report the failure and carry on with the next record, keeping what succeeded; a `batch` script is one invocation, so a failure just ends the run there with its earlier writes committed and its `[field]` assignments never flushed. **Defaults to `true`** when omitted — see *Atomicity* below |
 | `orderNum` | Recommended | Display order in the action menu |
-| `isAsync` | Optional | `true` = runs in background via Hangfire, user gets completion notification |
+| `isAsync` | Optional | `true` **permits** background execution — it does not force it. A parameterless action is queued directly; one with params is offered to the user as both "Run" and "Run in Background". Queued runs get a completion notification |
+
+## Atomicity
+
+`isTransacted: true` makes the run **one transaction**, in both execution modes.
+The first failing record aborts the run and every write the run made — including
+those for records that already succeeded — is rolled back. It covers the script's
+own `insert()` / `update()` / `query()` calls as well as the flush of `[field] = …`
+assignments. It does not depend on the entity carrying `auditHistory`.
 
-## Don't assume your action is atomic
+`isTransacted: false` is the opposite contract — no transaction — and what it means
+depends on the mode:
 
-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:
+- **`single` / `each`**: each record stands alone. The failure is reported, the loop
+  carries on with the next record, and what the earlier records wrote is kept.
+- **`batch`**: there is one script invocation and no loop to continue, so a failure
+  simply ends the run. Whatever the script had already written with `insert()` /
+  `update()` is committed, and the pending `[field] = …` assignments are never
+  flushed. There is nothing "independent" about it — which is why `batch` +
+  `isTransacted: false` is a shape to avoid.
 
-| path | mode | writes before the failure |
+| path | `isTransacted: true` | `isTransacted: false` |
 |---|---|---|
-| 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.
+| Sync execute, `single` | whole selection rolled back | writes stay committed |
+| Sync execute, `batch` | whole run rolled back | writes stay committed |
+| Scheduled job | rolled back | rolled back (the dispatcher owns the transaction) |
+| **Queued to background**, `single` / `each` | **stays committed** (run still aborts at the first failure) | **stays committed** (run continues) |
+| **Queued to background**, `batch` | **stays committed** (flag not read at all) | **stays committed** (same) |
+
+**The background row is the exception and it is a known platform gap.** The
+background worker opens no transaction, so an action that is atomic when run
+inline is not when the same call is queued. The rollback half is lost outright;
+what survives depends on the mode. The worker's `single` / `each` loop still reads
+`isTransacted` to decide whether to abort after the first failed record or carry
+on, so there `true` means "stop here", not "undo". Its `batch` path never reads the
+flag — one invocation, ending on failure either way — so a queued `batch` action
+gets nothing from `isTransacted` at all. And which one happens is decided by
+the *request*, not by the manifest: `isAsync: true` only permits queuing, and an
+action with parameters is offered to the user as both "Run" (inline, transactional)
+and "Run in Background" (queued, not). So an `isAsync` action cannot be assumed to
+be either.
+
+**Two things that follow for how you write actions:**
+
+1. **Declare `isTransacted: true`** — which is also the default — for anything that
+   writes more than one row. Do *not* reach for `auditHistory` as an atomicity
+   switch; that was a workaround for a defect that no longer exists.
+2. **Still validate up front.** Call `error()` before the first `insert()` /
+   `update()` where you can, so a background-queued run has nothing to unwind
+   either. This is the only guard that holds on every path.
 
 ## SQL in query() — important notes
 

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

@@ -3,7 +3,12 @@
 Formulas are used in:
 
 - **Formula columns** (`columnType: "F"`) — computed values
-- **Action `canExecute:` blocks** — availability checks
+- **Action `canExecute:` blocks** — availability checks. Evaluated on both sides
+  and **enforced** by `action.execute`, but only over a narrow subset: comparisons
+  between fields and literals combined with `AND` / `OR` / `NOT`. Functions,
+  arithmetic, ref navigation, `$[setting]` reads and a bare boolean field all fail
+  open server-side, and some of them throw client-side. See the `canExecute:`
+  section in [action-dsl.md](action-dsl.md).
 - **Default values** — a setting's `formula` (e.g. `"formula": "TODAY()"`) or a formula (`F`) column. Note: entity *data* columns have **no** `default`/`defaultValue` key — model a default with an `F` column or set it in action/trigger logic.
 - **Filter expressions** (partially)
 - **Validation expressions** (partially)

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

@@ -74,7 +74,10 @@ execute:
     }
 ```
 
-Hide the action from the UI with `canExecute: false` — the scheduler bypasses the check:
+Gate the action to automation only with `canExecute: false`. The button is left in
+the toolbar but permanently **disabled**, and `action.execute` refuses the call
+server-side, while the scheduler — which invokes the script engine directly — is
+unaffected:
 
 ```
 canExecute:

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

@@ -71,6 +71,35 @@ The manifest lists every file in the package by logical key. The installer reads
 | `supportedLocales` | string[] | IETF locale tags that the module ships translations for, e.g. `["de-DE", "uk-UA"]`. Files are **auto-discovered** at `./translations/{locale}.json` — there is no per-file manifest entry. English (`en`/`en-*`) is the default and must not be listed. |
 | `printTemplates` | object | `{ "template_code": "./print_templates/template.scriban" }` |
 | `webhooks` | string | path to `./webhooks.json` |
+| `features` | string[] | Opt-in platform behaviours this package was authored for, e.g. `["report-security"]`. Absent/empty = the pre-feature behaviour. See **Feature opt-ins** below. |
+
+## Feature opt-ins
+
+`dependencies` answers "does the platform have this?". `features` answers "should this behaviour apply to **my** module?".
+
+They exist for opposite failure modes. A dependency is a hard gate — the module will not install without it. A feature is the reverse: the platform already has the behaviour, but switching it on for every installed module at once would break every package written before it existed. So it stays off per module until the author asks for it.
+
+```json
+"features": ["report-security"]
+```
+
+| Feature | Effect |
+|---|---|
+| `report-security` | This module's reports require the `E` right on their security object — checked when running or opening a report and when reading or changing its saved presets and panel layouts. Without it, a report is reachable by anyone who can read the underlying data. |
+
+**Adopting one is two releases, in order:**
+
+1. Add `"report:<report_code>": "E"` to every role in `security/roles.json` that should reach each report. Bump `version`, install.
+2. Add `"features": ["report-security"]`. Bump `version` again, install.
+
+Do it in the other order and every report in the module denies for every role until the grants land. Both steps need a version bump — a same-version install is skipped, so the tenant would keep the old manifest.
+
+**Rules:**
+
+- Unknown names are **rejected** at package load, not ignored. A misspelled `report-securty` would otherwise leave the old behaviour in place while the manifest claims the protection is on.
+- Casing and surrounding whitespace are normalised; the canonical spelling is lowercase.
+- Removing a feature genuinely removes it on the next install — an opt-in is a migration window, not a one-way door.
+- Installing against an older platform that predates the feature is safe: unknown manifest keys are ignored there, so the module runs the old behaviour.
 
 ## Dependencies
 

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

@@ -7,7 +7,7 @@ SP files: `logic/reports/rpt_*.sql`
 
 ## Structure
 
-A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...] }`), and optional `parameters`. Panels reference datasets by code via `datasetCd`.
+A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...] }`), optional per-dataset `params`, and an optional `entities` array (record-report attachments). Panels reference datasets by code via `datasetCd`.
 
 ```json
 {
@@ -17,12 +17,18 @@ A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...
             "pipeline": {
                 "caption": "Pipeline Data",
                 "datasetType": "Q",
+                "params": {
+                    "min_amount": { "fieldTypeCd": "number", "label": "Min Amount", "required": false, "default": 0 }
+                },
                 "query": {
                     "entityCd": "opportunity",
                     "columns": ["stage", "amount", "lead_source", "customer.name"],
                     "filter": {
                         "g": "and",
-                        "i": [ { "c": "stage", "o": "nIn", "v": ["Closed Won", "Closed Lost"] } ]
+                        "i": [
+                            { "c": "stage", "o": "nIn", "v": ["Closed Won", "Closed Lost"] },
+                            { "c": "amount", "o": "grEq", "v": "@min_amount" }
+                        ]
                     },
                     "sort": [ { "c": "amount", "d": "desc" } ]
                 }
@@ -38,9 +44,6 @@ A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...
                 },
                 { "vizType": "table", "datasetCd": "pipeline", "title": "Pipeline Detail" }
             ]
-        },
-        "parameters": {
-            "min_amount": { "fieldTypeCd": "number", "label": "Min Amount", "required": false, "default": 0 }
         }
     }
 }
@@ -85,7 +88,7 @@ For SQL the query builder can't express — window functions, CTEs, cross-schema
     "spCd": "rpt_ar_aging",
     "params": {
         "as_of_date": { "fieldTypeCd": "date", "label": "As of Date", "required": true, "default": "=NOW()" },
-        "customer_id": { "fieldTypeCd": "lookup", "label": "Customer", "required": false, "params": { "entityCd": "account" } }
+        "customer_id": { "fieldTypeCd": "lookup", "label": "Customer", "required": false, "params": { "link": { "entity": "account" } } }
     },
     "columnsDef": {
         "customer_name": { "label": "Customer", "fieldTypeCd": "text", "baseDatatypeCd": "string", "width": 200 },
@@ -99,7 +102,7 @@ Key differences from entity datasets:
 - `datasetType: "S"`.
 - `spCd` — the stored-procedure code (the function name **without** the schema prefix; resolved to `sp_id` at install). (**Not** `sp` or `procedureName`.)
 - `columnsDef` — **required** — the platform can't infer columns from a function.
-- Params can be per-dataset or per-report.
+- Params work exactly as they do for an entity dataset, and `datasetType` makes no difference: declare them at report level (`parameters`) or on the dataset (`params`). Report level wins on a code collision.
 
 **Multi-result-set SPs** map extra datasets to the same function via `parentDatasetCd` (the dataset that owns the SP call) + `parentRef` (the named refcursor):
 
@@ -139,16 +142,33 @@ $$;
 
 ## Parameters
 
-Parameters prompt the user before running the report. Declare them per-report (`parameters`) or per-dataset (`params`).
+Parameters prompt the user before running the report.
+
+**Parameters are report-scoped**, so there are two legal declaration sites and they mean the same thing:
+
+- **`parameters`** at report level — the canonical home, and the only one that fits a param several datasets use.
+- **`datasets.<cd>.params`** — shorthand, fine when exactly one dataset uses it. Every module written before this existed uses it, and it stays fully supported.
+
+The installer merges both into the report's single param set (**report level wins** on a code collision), so either way the param serves the whole report: the param bar, saved param sets, `@param` filters in *any* dataset, and record-report mappings.
+
+> Why report-scoped: the declaration is stored once per report (`report.param_set_id` → `param_set`), the authoring API is `report.params.save`, and `report.get` flattens per-dataset defaults report-wide before use. There is no dataset-scoped parameter behaviour to choose between.
 
 ```json
 "parameters": {
-    "start_date": { "fieldTypeCd": "date", "label": "Start Date", "required": true, "default": "=STARTMONTH()" },
-    "status":   { "domain": "fin.doc_status", "label": "Status" },
-    "region": { "fieldTypeCd": "dropdown", "label": "Region", "params": { "options": [
-        { "value": "north", "label": "North" }, { "value": "south", "label": "South" }
-    ] } },
-    "customer": { "fieldTypeCd": "lookup", "label": "Customer", "params": { "entityCd": "account" } }
+    "customer": { "fieldTypeCd": "lookup", "label": "Customer", "params": { "link": { "entity": "account" } } }
+},
+"datasets": {
+    "sales": {
+        "datasetType": "Q",
+        "params": {
+            "start_date": { "fieldTypeCd": "date", "label": "Start Date", "required": true, "default": "=STARTMONTH()" },
+            "status":   { "domain": "fin.doc_status", "label": "Status" },
+            "region": { "fieldTypeCd": "dropdown", "label": "Region", "params": { "options": [
+                { "value": "north", "label": "North" }, { "value": "south", "label": "South" }
+            ] } }
+        },
+        "query": { "entityCd": "invoice", "columns": ["invoice_number", "total"] }
+    }
 }
 ```
 
@@ -159,9 +179,11 @@ Parameters prompt the user before running the report. Declare them per-report (`
 | `label` | Display label in the parameter dialog |
 | `required` | Whether the user must fill this before running |
 | `default` | Plain value or `=`-prefixed formula (`"=NOW()"`, `"=STARTMONTH()"`, `"=TODAY()"`) |
-| `params` | Extra config — `options` for dropdowns, `entityCd` for lookups |
+| `params` | Extra config — `options` for dropdowns, `link: { entity, otherKey? }` for lookups |
 | `orderNum` | Display order in the parameter form (falls back to declaration order) |
 
+Two spellings that look right and are silently ignored: **`isRequired`** (the key is `required`, so the param installs as optional) and a **top-level `link`** (it must be nested under `params`, so the lookup installs with no autocomplete). Both are validator errors.
+
 **Dropdown params: prefer `domain`, and never ship bare codes.** A list shared with a column belongs on a `column_domain` — bind the param to it and the options plus their translations are authored once (`column-domains.md`). For a list that exists only for this report, write the rich option form (`{ "value": "north", "label": "North" }`); a bare `"options": ["north", "south"]` renders the raw codes in **every** locale, English included. Per-locale labels go under `reports.<cd>.params.<param_cd>.options` (`translations.md`).
 
 Reference a parameter with `@param_code` inside a query filter value:
@@ -260,14 +282,72 @@ Dashboard KPI/chart *tiles* get the same support via a `sources` map in the tile
 
 `config.chartSize` ∈ `sm | m | l | xl` controls the default chart height (`m` when omitted).
 
+## Record reports (`entities`)
+
+A report can be **attached to an entity** so it opens from a record — the way a print template does — with the record's values feeding its parameters. Add an `entities` array to the report:
+
+```json
+"credit_check": {
+    "description": "Customer Credit Check — limit against outstanding AR and open quotes",
+    "entities": [
+        { "entityCd": "parties.party", "params": { "customer_id": "party_id" }, "orderNum": 45 },
+        { "entityCd": "crm.quote",     "params": { "customer_id": "customer_id" }, "orderNum": 45 }
+    ],
+    "parameters": {
+        "customer_id": {
+            "label": "Customer",
+            "fieldTypeCd": "lookup",
+            "params": { "link": { "entity": "parties.party" } },
+            "required": true
+        }
+    },
+    "layout": { "panels": [ { "vizType": "table", "datasetCd": "open_invoices" } ] },
+    "datasets": {
+        "open_invoices": {
+            "caption": "Open Invoices",
+            "datasetType": "Q",
+            "query": {
+                "entityCd": "invoice",
+                "columns": ["invoice_number", "due_date", "amount_due"],
+                "filter": { "g": "and", "i": [ { "c": "customer_id", "o": "eq", "v": "@customer_id" } ] }
+            }
+        }
+    }
+}
+```
+
+Each entry becomes one attachment row, and the report gains a toolbar entry on that entity's record. Note the two different `params` keys:
+
+- `entities[].params` — the **mapping**: report param code → **source column on the attached entity**.
+- `parameters` / `datasets.<cd>.params` — the param **declaration**. The mapping can only name codes declared in one of those.
+
+| Rule | Detail |
+|---|---|
+| `entityCd` | Qualified `module.entity` for anything outside this module, and that module must be a **declared dependency**. |
+| Source columns | The entity PK, a reference (`R`) column, or a bounded scalar (number, date/datetime, bool, dropdown/radio/flags code). `text`, `json`, `file`/`image` are rejected. |
+| Types | Source and target must be compatible; only `lookup`↔`number` and `date`↔`datetime` widen. A names-only match like `{ "customer_id": "created_date" }` is an error, not a runtime surprise. |
+| One per pair | One attachment per (entity, report). Two entries for the same entity overwrite each other. |
+| Unmapped params | Keep their normal behaviour — default value, or prompt the user. |
+| Mapped params | Are **hidden** on the record-report page. The URL is about this record; pivoting means going back to a record. |
+| Dependency | Declare `"metadata": ">=1.5.0"` — the attachment table ships with the metadata system module, so this is the gate that fails loudly on an older platform instead of the attachment quietly doing nothing. This is metadata's **`version`**; dependency ranges are never checked against `dbSchemaVersion`, so do not use the `1.4.0` of the migration that creates the table. |
+| Rights | Report `E` is still required. A bridge role must grant `E` on the report **and** `S` on the dataset entities. |
+
+There is no `canExecute` on an attachment: if the record exists the report is meaningful for it, and an empty report is a legitimate answer.
+
+> **Prefer a record report over an action that calculates.** See *When an action is the wrong tool* in `references/action-dsl.md`. If the `execute:` block only reads, computes and `info()`s a number, it is not an action — a printed number is never stored, can't be re-read, and shows the verdict without the working. Attach a report instead: it gets you KPI tiles, charts, the underlying rows, drill-through, saved layouts and row caps for free, and the DSL you don't write is DSL that can't drift from the data.
+>
+> Keep it an action when it **changes** something — writing the result to a column, creating a record, or *blocking* a transition. "Explain the number" is a report; "refuse the over-limit quote" is an action or trigger.
+
 ## Grants
 
-Grant report access with the `E` right:
+Grant report access with the `E` right — a **colon** prefix, never a dot:
 
 ```json
-"rights": { "report.sales_pipeline": "E" }
+"rights": { "report:sales_pipeline": "E" }
 ```
 
+A dependency's report is granted with the qualified form, `"report:fin.ar_aging": "E"` — bridge modules need this to grant on a report they attach but do not own.
+
 ## Common mistakes
 
 - Using a bare `"layout": [ ... ]` array — `layout` is an **object**: `"layout": { "panels": [ ... ] }`.
@@ -276,5 +356,11 @@ Grant report access with the `E` right:
 - Using `sp` / `procedureName` for an SP dataset — the field is `spCd`.
 - Forgetting `columnsDef` on an SP dataset — **required**.
 - Forgetting to grant `E` on the report in at least one role — it becomes invisible.
+- Writing the rights key as `report.<code>` — actions/reports/folders take a **colon**: `report:<code>`.
+- Writing `isRequired` instead of `required`, or a top-level `link` instead of `params.link` — both are ignored at install.
+- Declaring both `fieldTypeCd` and `domain` on one param — install rejects the pair rather than picking a winner.
+- Mapping a record-report attachment onto a param no dataset declares, or from a `text`/`json` column — both are rejected.
+- Attaching a report to another module's entity without declaring that module as a dependency.
 - Forgetting `p_folder_uid` / `p_user_id` as the first two SP function params — the call fails.
 - Referencing a parameter as `$param` — use `@param_code` in filters.
+- Writing an action that computes a number and `info()`s it, where a record report would show the working.

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

@@ -73,6 +73,9 @@ For each entity:
 - [ ] Each source has `entityCode` and `columns`
 - [ ] `entityCode` points to an entity that exists
 - [ ] Column codes in `columns` all exist on the entity
+- [ ] No `columns` entry is a **set** (`columnType: "S"`) — a 1:N collection has no per-row value to put in a column; show it on the record card instead. **Rejected at validate/pack**
+- [ ] No `columns` entry is a **dotted navigation path** (`owner.email`, `account.company_name`) — a view's column list is matched against the entity's own columns, so a dotted entry resolves to nothing. Add a Reference (`R`) or Formula (`F`) column to the entity and list that. **Rejected at validate/pack**
+- [ ] A listed column does **not** need `V` in its flags — the renderer promotes anything the list names (that is how trait-contributed `created_by_user`, flagged `I`, appears). Listing a non-`V` column is valid intent, not a mistake
 - [ ] The rendered entity has **at least one visible scalar column** (a field with `V` in `flags`, `columnType` not `S`) — a grid/list/kanban/etc. view over an entity whose fields are all hidden (or only sets) is **rejected** at validate/pack and would render "No visible columns configured for this entity." `diagram`/`matrix`/`library` are exempt
 - [ ] If set, `viewType` is from the supported list (`grid`, `list`, `kanban`, `calendar`, `gallery`, `tree-grid`, `diagram`, `master-detail`, `library`, `matrix`)
 - [ ] A `matrix` view has a `viewConfig` with `rowAxis`, `colAxis`, and `cell` (cell `entity` matches the primary `dataSources` entity; `rowKey`/`colKey` are real cell columns)
@@ -89,6 +92,16 @@ For each entity:
 - [ ] Every `reportCode` points to a report that exists
 - [ ] `orderNum` is set on each node for deterministic ordering
 
+## Reports (`ui/reports.json`)
+
+- [ ] Params are declared in the report-level `parameters` block, or under `datasets.<cd>.params` — a param several datasets use belongs at report level (the installer merges both; report level wins on a collision)
+- [ ] Params use `required` (not `isRequired`), and a lookup nests its binding as `params: { link: { entity } }` (not a top-level `link`)
+- [ ] No param declares both `fieldTypeCd` and `domain`
+- [ ] `layout` is an object (`{ "panels": [...] }`), and the chart kind is `config.chartType` with `vizType: "chart"`
+- [ ] Record-report attachments (`entities`): every mapped param code is declared at report level or on a dataset; every source column is the PK, a reference (`R`) column, or a bounded scalar; cross-module `entityCd` is qualified and its module is a declared dependency
+- [ ] A module with attachments declares `"metadata": ">=1.5.0"`
+- [ ] No `check_…` / `calculate_…` action exists that a record report should be
+
 ## Security
 
 - [ ] `security/roles.json` exists (at least one role)
@@ -106,6 +119,16 @@ For each action:
 - [ ] DSL file exists at `logic/actions/<script>.dsl`, where `<script>` is the bare filename in the action's `script` field (no path, no `.dsl` extension)
 - [ ] DSL file has `params:`, `canExecute:`, and `execute:` blocks
 - [ ] `canExecute:` is a valid formula expression
+- [ ] If `canExecute:` is meant to **gate** and not just grey out a button, its
+      guard is expressed in the server-enforced subset — **comparisons** between
+      fields and literals, combined with `AND` / `OR` / `NOT`. Function calls
+      (`TODAY()`, `COUNT()`, `CURRENT_USER_ID()`), arithmetic, ref navigation and
+      `$[setting]` reads are fail-open server-side and are advisory only
+- [ ] No **bare boolean field** as a whole condition — `[is_active]` and
+      `NOT [is_blocked]` are not enforced (a field is only an operand). Write
+      `[is_active] = true` / `NOT ([is_blocked] = true)`
+- [ ] Anything that MUST hold is also checked in `execute:` with `error()` — a
+      `canExecute` alone is never the authoritative guard
 - [ ] `execute:` uses only documented built-in functions
 - [ ] Referenced entities exist
 - [ ] Referenced parameters are declared in `params:`

package/skills/dforge-module-build/SKILL.md

@@ -172,9 +172,12 @@ to fill a sub-step** — a pure CRUD module skips Phase 2 entirely (record it wi
 
 **2a Actions.** First check the action is an action at all: it must **change**
 something. If the `execute:` block would only read, compute and `info()` the
-answer, build a report, a formula column, or an action that writes a result
-record instead — a printed number is never stored and can't be re-read
-(`dforge://reference/action-dsl`, *When an action is the wrong tool*). Then load
+answer, build a **record report** (a report with an `entities` attachment — same
+toolbar entry point, but it shows the working and re-reads live data), a formula
+column, or an action that writes a result record instead — a printed number is
+never stored and can't be re-read (`dforge://reference/action-dsl`, *When an
+action is the wrong tool*). Do not compute in DSL what a report dataset already
+aggregates. Then load
 all four resources in the action row — the wrong-field-access /
 wrong-batch-flag / wrong-`ui/actions.json`-property mistakes only surface when
 you cross-check them. Draft the DSL, run
@@ -219,10 +222,31 @@ pointing at the views.
 
 If none fire, skip specialized views for that entity.
 
-**3c. Reports** only when aggregation/grouping isn't covered by views.
+**3c. Reports** only when aggregation/grouping isn't covered by views — or when
+Phase 2a sent you here because the "action" only wanted to show a number.
+
+Params are **report-scoped**: declare them in the report-level `parameters`
+block, or as shorthand under `datasets.<cd>.params` when exactly one dataset uses
+the param. The installer merges both into the report's one param set, report level
+winning on a collision — so a param several datasets share belongs at report level.
+Grant with a **colon** key: `"report:<code>": "E"`.
+
+A report that answers a question *about one record* takes an `entities`
+attachment, which puts it on that record's toolbar with the record's values
+feeding its params:
+
+```json
+"entities": [ { "entityCd": "parties.party", "params": { "customer_id": "party_id" }, "orderNum": 45 } ]
+```
+
+`entities[].params` is the **mapping** (report param → source column), not a
+param declaration. Qualify a cross-module `entityCd` and declare that module as a
+dependency; add `"metadata": ">=1.5.0"` too. Source columns are limited to the
+PK, a reference column, or a bounded scalar. Full rules:
+`dforge://reference/reports`.
 
 **Exit:** every entity has a grid and a menu entry; every specialized view has a
-stated trigger.
+stated trigger; every report's params sit on a dataset.
 
 ## Phase 4 — Polish (mostly optional)