@dforge-core/dforge-mcp 0.2.23 → 0.2.25

package/CHANGELOG.md

@@ -4,6 +4,33 @@ 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.25
+
+`sp:` is now a legal role-rights key. It always was, at install — `SecurityRegistrar`
+resolves `sp:<cd>` and `sp:<module>.<cd>` against a stored procedure's sec_object, and
+`report.run` enforces `E` on it for every `datasetType: "S"` dataset, on top of the
+report's own right. This server's key validator did not know the prefix, so
+`dforge_role_add` and `dforge_role_right_set` rejected the one grant such a report needs,
+and nothing in the references mentioned it. A module built here with an SP-backed report
+therefore shipped a report that answered `PERMISSION_DENIED` for everyone, unfixably: the
+role-rights admin UI lists entities, actions and reports only, so no tenant admin can add
+an SP grant afterwards (dForge-core#1146).
+
+`report:` and `sp:` also accept the qualified `module.code` form now, which the installer
+has always resolved cross-module. `action:` and `folder:` still do not — the installer
+resolves those within the module, so a dotted one grants nothing.
+
+`references/security.md` gains the two-grant rule; `references/reports.md` loses two
+claims that were never true: that the platform injects `p_folder_uid` / `p_user_id` as an
+SP function's first two params (it passes exactly the declared params and nothing else,
+so such a function is uncallable and the install now says so), and that multi-result-set
+refcursor datasets work (they install and return nothing). Both files also carry the SP param types the
+runtime binds, now that dForge-core binds every scalar one (a `numeric` param used to go
+over as text and fail the call) and rejects the rest at install.
+
+The matching pack-time check lives in dForge-core (`ReportSpRightsValidator`), so
+`dforge_module_pack` picks it up through the CLI it shells out to.
+
 ## 0.2.23
 
 The DSL checker was written twice. This server had one — regexes over

package/dist/server.js

@@ -31283,7 +31283,7 @@ function buildZedTasks() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.26/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.27/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -31633,8 +31633,9 @@ function isReadyToScaffold(moduleDir) {
   return fs.existsSync(v) && fs.readFileSync(v, "utf8").includes("readyToScaffold: true");
 }
 var RIGHTS_ENTITY = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$/;
-var RIGHTS_OBJECT = /^(action|report|folder):[a-z][a-z0-9_]*$/;
-var RIGHTS_OBJECT_DOT = /^(action|report|folder)\.[a-z]/;
+var RIGHTS_OBJECT = /^(action|folder):[a-z][a-z0-9_]*$/;
+var RIGHTS_OBJECT_QUALIFIABLE = /^(report|sp):[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$/;
+var RIGHTS_OBJECT_DOT = /^(action|report|sp|folder)\.[a-z]/;
 function assertValidRightKey(key) {
   if (RIGHTS_OBJECT_DOT.test(key)) {
     const fixed = key.replace(".", ":");
@@ -31642,9 +31643,9 @@ function assertValidRightKey(key) {
       `Rights key '${key}' uses a dot for an action/report/folder \u2014 use a colon: '${fixed}'. (A dot is only for cross-module entities like 'fin.invoice'.)`
     );
   }
-  if (RIGHTS_OBJECT.test(key) || RIGHTS_ENTITY.test(key)) return;
+  if (RIGHTS_OBJECT.test(key) || RIGHTS_OBJECT_QUALIFIABLE.test(key) || RIGHTS_ENTITY.test(key)) return;
   throw new Error(
-    `Invalid rights key '${key}'. Use a same-module entity ('product'), a cross-module entity ('fin.invoice'), or a colon-prefixed object ('action:approve', 'report:summary', 'folder:east').`
+    `Invalid rights key '${key}'. Use a same-module entity ('product'), a cross-module entity ('fin.invoice'), or a colon-prefixed object ('action:approve', 'report:summary', 'sp:rpt_totals', 'folder:east'). Only report: and sp: may be qualified ('report:fin.ar_aging').`
   );
 }
 function assertValidRightValue(key, value, allowEmpty) {
@@ -31659,13 +31660,13 @@ function assertValidRightValue(key, value, allowEmpty) {
       `Invalid rights '${value}' on '${key}'. Use S/I/U/D/C for entities, or 'E' for actions/reports/folders.`
     );
   }
-  const isObject2 = /^(action|report|folder):/.test(key);
+  const isObject2 = /^(action|report|sp|folder):/.test(key);
   if (isObject2 && value !== "E") {
     throw new Error(`Object '${key}' takes 'E' (Execute), got '${value}'.`);
   }
   if (!isObject2 && value.includes("E")) {
     throw new Error(
-      `'${key}' is granted 'E' but has no action:/report:/folder: prefix \u2014 entity rights are S/I/U/D/C. If '${key}' is an action or report, prefix it (e.g. 'action:${key}' or 'report:${key}').`
+      `'${key}' is granted 'E' but has no action:/report:/sp:/folder: prefix \u2014 entity rights are S/I/U/D/C. If '${key}' is an action or report, prefix it (e.g. 'action:${key}' or 'report:${key}').`
     );
   }
 }
@@ -34448,7 +34449,7 @@ function entityDelete(args) {
 // src/tools/action-add.ts
 var path9 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.26/node_modules/@dforge-core/metadata/dist/dsl/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.27/node_modules/@dforge-core/metadata/dist/dsl/index.js
 var PUNCT3 = ["===", "!=="];
 var PUNCT2 = [
   "==",
@@ -36654,7 +36655,7 @@ var roleAddSchema = {
   ),
   description: external_exports.string(),
   rights: external_exports.record(external_exports.string(), external_exports.string()).describe(
-    "Map: object code \u2192 rights string. Keys: same-module entity bare ('product'), cross-module entity dotted ('fin.invoice'), action/report/folder with a COLON prefix ('action:approve', 'report:summary', 'folder:east') \u2014 never a dot. Values: entities use 'S'/'I'/'U'/'D'/'C' (e.g. 'SIUDC'); actions/reports/folders use 'E'. To deny, omit the key (never map to '')."
+    "Map: object code \u2192 rights string. Keys: same-module entity bare ('product'), cross-module entity dotted ('fin.invoice'), action/report/SP/folder with a COLON prefix ('action:approve', 'report:summary', 'sp:rpt_totals', 'folder:east') \u2014 never a dot. Values: entities use 'S'/'I'/'U'/'D'/'C' (e.g. 'SIUDC'); actions/reports/SPs/folders use 'E'. A report with a datasetType 'S' dataset needs BOTH 'report:<cd>' and 'sp:<spCd>'. To deny, omit the key (never map to '')."
   )
 };
 function roleAdd(args) {
@@ -36807,10 +36808,10 @@ var roleRightSetSchema = {
   moduleDir: external_exports.string(),
   roleCode: external_exports.string().describe("Role code as it appears in security/roles.json (e.g. 'crm.admin')."),
   object: external_exports.string().describe(
-    "Object to grant rights on. Same-module entity: bare ('product'). Cross-module entity: dotted ('fin.invoice'). Action/report/folder: COLON prefix ('action:approve', 'report:summary', 'folder:east') \u2014 never a dot."
+    "Object to grant rights on. Same-module entity: bare ('product'). Cross-module entity: dotted ('fin.invoice'). Action/report/SP/folder: COLON prefix ('action:approve', 'report:summary', 'sp:rpt_totals', 'folder:east') \u2014 never a dot. A report whose dataset is datasetType 'S' ALSO needs 'sp:<spCd>' \u2014 report.run enforces both, and the admin UI cannot grant SP rights later."
   ),
   rights: external_exports.string().describe(
-    "Rights string. Entities: any combination of S/I/U/D/C (use '' to revoke all). Actions/reports/folders: 'E' or '' to revoke."
+    "Rights string. Entities: any combination of S/I/U/D/C (use '' to revoke all). Actions/reports/SPs/folders: 'E' or '' to revoke."
   )
 };
 function roleRightSet(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.23",
+	"version": "0.2.25",
 	"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",
@@ -36,7 +36,7 @@
 	},
 	"dependencies": {
 		"@dforge-core/dforge-cli": "^0.2.19",
-		"@dforge-core/metadata": "^0.0.26",
+		"@dforge-core/metadata": "^0.0.27",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"zod": "^4.4.3"
 	},

package/resources/schemas/card-layouts.schema.json

@@ -0,0 +1,141 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "dForge Module Card Layouts",
+	"description": "Module-shipped card (form) layouts for a dForge module package (ui/card_layouts.json). Each key is the layout_name stored in dForge.entity_view_layout. Rows written from here carry module_id, so they are recreated on every install and removed on uninstall; a layout the tenant drew in the card editor has module_id NULL and is never touched.",
+	"type": "object",
+	"additionalProperties": {
+		"type": "object",
+		"properties": {
+			"entity": {
+				"type": "string",
+				"description": "Entity code the layout belongs to. Unqualified means this module owns the entity; the cross-module form 'module.entity' targets another module's entity (a bridge module shipping a layout for its host)."
+			},
+			"view": {
+				"type": "string",
+				"default": "default",
+				"description": "Entity view the layout hangs off, matching an entity_view row's view_name. Defaults to 'default' — the same fallback entity.getLayouts and entity.saveLayout use for an entity with no folder binding of its own. Matched against the entity's declared views case-insensitively, and filed under their spelling; the installer creates the view row only when nothing matches."
+			},
+			"isDefault": {
+				"type": "boolean",
+				"default": false,
+				"description": "Whether this layout opens by default. Honoured on FIRST install only, and only when the view has no default layout yet — once a tenant has chosen their own default, an upgrade does not take it back."
+			},
+			"description": {
+				"type": "string",
+				"description": "Human-readable note for the package author. Not stored."
+			},
+			"layout": {
+				"$ref": "#/$defs/cardLayout",
+				"description": "The layout body, stored verbatim into entity_view_layout.layout. Same shape the card editor saves."
+			}
+		},
+		"required": ["entity", "layout"],
+		"additionalProperties": false
+	},
+	"$defs": {
+		"cardLayout": {
+			"type": "object",
+			"properties": {
+				"sections": {
+					"type": "array",
+					"description": "Ordered sections rendered down the card.",
+					"items": { "$ref": "#/$defs/section" }
+				},
+				"sets": {
+					"type": "object",
+					"description": "Per-set-field view config, keyed by the set column code. Chooses the renderer a detail grid uses ('grid' or 'list') and its persisted options.",
+					"additionalProperties": {
+						"type": "object",
+						"properties": {
+							"viewType": {
+								"type": "string",
+								"enum": ["grid", "list"],
+								"description": "Set renderer. Defaults to the column's own metadata."
+							},
+							"options": {
+								"type": "object",
+								"description": "Opaque per-renderer options, passed verbatim to the set registration."
+							}
+						},
+						"additionalProperties": false
+					}
+				}
+			},
+			"required": ["sections"],
+			"additionalProperties": false
+		},
+		"section": {
+			"oneOf": [
+				{ "$ref": "#/$defs/columnGroupSection" },
+				{ "$ref": "#/$defs/setSection" },
+				{ "$ref": "#/$defs/tabGroupSection" }
+			]
+		},
+		"columnGroupSection": {
+			"type": "object",
+			"description": "A group of fields laid out in 1, 2 or 3 columns.",
+			"properties": {
+				"type": { "const": "columnGroup" },
+				"code": { "type": "string", "description": "Section code, unique within the layout." },
+				"label": { "type": "string", "description": "Section heading, in the module's authoring language. The installer gives it an entity_column_group row keyed on this section's code, so translations/<locale>.json localizes it under entities.<entity>.columnGroups.<code>.label and the card shows the localized heading." },
+				"cols": { "type": "integer", "minimum": 1, "maximum": 3, "description": "Field columns across the group. Defaults to the card's own setting." },
+				"columns": {
+					"type": "array",
+					"description": "Fields in the group, in render order. A bare string is the column code; the object form adds pixel sizing.",
+					"items": {
+						"oneOf": [
+							{ "type": "string" },
+							{
+								"type": "object",
+								"properties": {
+									"column_cd": { "type": "string", "description": "Column code on this entity." },
+									"width": { "type": "integer", "minimum": 1, "description": "Field width in px." },
+									"height": { "type": "integer", "minimum": 1, "description": "Field height in px — for multiline/textarea fields." }
+								},
+								"required": ["column_cd"],
+								"additionalProperties": false
+							}
+						]
+					}
+				}
+			},
+			"required": ["type", "code", "columns"],
+			"additionalProperties": false
+		},
+		"setSection": {
+			"type": "object",
+			"description": "An embedded detail grid for a 1:N set column — the master/detail building block. The label comes from the column's own metadata.",
+			"properties": {
+				"type": { "const": "set" },
+				"code": { "type": "string", "description": "Section code, unique within the layout." },
+				"setField": { "type": "string", "description": "Set column code on this entity (columnType 'S')." }
+			},
+			"required": ["type", "code", "setField"],
+			"additionalProperties": false
+		},
+		"tabGroupSection": {
+			"type": "object",
+			"description": "A tab bar whose tabs are other sections. This is how a record shows several detail grids without stacking them down one long form.",
+			"properties": {
+				"type": { "const": "tabGroup" },
+				"code": { "type": "string", "description": "Section code, unique within the layout." },
+				"tabs": {
+					"type": "array",
+					"minItems": 1,
+					"description": "Tabs in order. Each references a columnGroup section by its code, or a set column by its column code.",
+					"items": {
+						"type": "object",
+						"properties": {
+							"type": { "type": "string", "enum": ["section", "set"] },
+							"code": { "type": "string", "description": "The referenced section's code, or the set column's code." }
+						},
+						"required": ["type", "code"],
+						"additionalProperties": false
+					}
+				}
+			},
+			"required": ["type", "code", "tabs"],
+			"additionalProperties": false
+		}
+	}
+}

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

@@ -14,7 +14,7 @@
 			"properties": {
 				"viewType": {
 					"type": "string",
-					"enum": ["grid", "list", "kanban", "calendar", "gallery", "tree-grid", "diagram", "master-detail", "library", "matrix"],
+					"enum": ["grid", "list", "kanban", "calendar", "gallery", "tree-grid", "diagram", "library", "matrix"],
 					"default": "grid",
 					"description": "View display type. Optional — omitted or unknown values fall back to 'grid' at runtime."
 				},
@@ -57,7 +57,6 @@
 				{ "$ref": "#/$defs/rules/tree-grid" },
 				{ "$ref": "#/$defs/rules/list" },
 				{ "$ref": "#/$defs/rules/diagram" },
-				{ "$ref": "#/$defs/rules/master-detail" },
 				{ "$ref": "#/$defs/rules/matrix" }
 			]
 		},
@@ -118,17 +117,6 @@
 					}
 				}
 			},
-			"master-detail": {
-				"if": {
-					"properties": { "viewType": { "const": "master-detail" } },
-					"required": ["viewType"]
-				},
-				"then": {
-					"properties": {
-						"dataSources": { "minItems": 2 }
-					}
-				}
-			},
 			"matrix": {
 				"if": {
 					"properties": { "viewType": { "const": "matrix" } },
@@ -493,7 +481,7 @@
 				},
 				"label": {
 					"type": "string",
-					"description": "Human-readable label for this data source (used in master-detail tabs)"
+					"description": "Human-readable label for this data source"
 				},
 				"columns": {
 					"type": "array",

package/resources/schemas/entity.schema.json

@@ -38,6 +38,10 @@
 		"toString": {
 			"description": "Display pattern using column placeholders, e.g. \"{first_name} {last_name}\". Optional in extension entities (with `extends`). No `type` constraint here because `toString` collides with Object.prototype.toString in JSON validators — they read the inherited function and reject it, even when the property is absent from the JSON."
 		},
+		"comments": {
+			"type": "boolean",
+			"description": "Records of this entity accept comments \u2014 the composer and thread appear on the record card, beside the audit history. Opt-in per entity; `comments` in the manifest sets a module-wide default that this overrides in both directions."
+		},
 		"traits": {
 			"type": "array",
 			"description": "Entity traits expanded during module install (authoring shortcut). Trait definitions loaded from DB (seeded by metadata module).",
@@ -221,9 +225,48 @@
 			},
 			"additionalProperties": false
 		},
+		"registryColumnParams": {
+			"type": "object",
+			"description": "params of an accumulation (A) or ledger (L) registry column. The lock lists are what BOTH generated guards freeze — the posted-document guard while the document is posted, the period guard while its period is closed — and they are required: install refuses a registry column that omits or empties them. The header's periodDateField and the state column are watched in addition, whatever the list says.",
+			"required": ["lockedFields"],
+			"properties": {
+				"lockedFields": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "type": "string", "minLength": 1 },
+					"description": "Header fields frozen while the document is posted and while its period is closed. Required. [\"*\"] freezes the whole row."
+				},
+				"lockedLineFields": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "type": "string", "minLength": 1 },
+					"description": "Line fields frozen under a posted or period-closed header. Required when lineEntity is declared, rejected when it is not. [\"*\"] freezes the whole row; the line's foreign key to the header is watched in addition."
+				},
+				"lineEntity": { "type": "string", "description": "The line entity, defined in this module. Declare together with lineField and lockedLineFields, or none of the three for a document without lines." },
+				"lineField": { "type": "string", "description": "The line's foreign-key column(s) to the header, comma-separated in the header's key order for a composite key." },
+				"stateField": { "type": "string", "description": "The bool column that records the posted state, when it is not the registry column itself. Written only by the register engine." },
+				"periodEntity": { "type": "string", "description": "Period entity this registry closes against — one of this module's, or 'module.entity' from a dependency." },
+				"periodDateField": { "type": "string", "description": "Header date column that resolves the period." },
+				"periodKeyField": { "type": "string", "default": "period_key" },
+				"periodClosedField": { "type": "string", "default": "closed" }
+			},
+			"dependencies": {
+				"lineEntity": ["lineField", "lockedLineFields"],
+				"lineField": ["lineEntity"],
+				"lockedLineFields": ["lineEntity"],
+				"periodEntity": ["periodDateField"]
+			},
+			"additionalProperties": true
+		},
 		"field": {
 			"type": "object",
 			"description": "Entity column/field definition",
+			"allOf": [
+				{
+					"if": { "required": ["columnType"], "properties": { "columnType": { "enum": ["A", "L"] } } },
+					"then": { "required": ["params"], "properties": { "params": { "$ref": "#/$defs/registryColumnParams" } } }
+				}
+			],
 			"properties": {
 				"dbDatatype": {
 					"type": "string",
@@ -551,8 +594,9 @@
 				"sign": { "$ref": "#/$defs/signConfig", "description": "Dynamic sign based on a field value (alternative to direction)" },
 				"autoCreateBalance": { "type": "boolean", "default": true },
 				"allowNegative": { "type": "boolean", "default": true },
-				"lockedFields": { "type": "array", "items": { "type": "string" }, "description": "Document fields locked when posted" }
+				"lockedFields": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Document fields locked when posted. Required; [\"*\"] freezes the whole row." }
 			},
+			"required": ["lockedFields"],
 			"additionalProperties": false
 		},
 		"signConfig": {

package/resources/schemas/manifest.schema.json

@@ -107,6 +107,10 @@
 			"enum": ["none", "minimal", "full"],
 			"description": "Default audit history mode for entities in this module ('full' captures every field change; 'minimal' captures only inserts/deletes; 'none' disables). Individual entities can override."
 		},
+		"comments": {
+			"type": "boolean",
+			"description": "Default for `comments` on every entity in this module. Individual entities override it, including overriding true with false."
+		},
 		"entities": {
 			"type": "object",
 			"description": "Entity definitions and extensions: entity code → relative path to entity JSON file. Dotted keys (e.g. 'fin.invoice') indicate extensions of other modules' entities (the entity file must have an 'extends' property).",

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

@@ -101,10 +101,15 @@ For SQL the query builder can't express — window functions, CTEs, cross-schema
 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.
+- `columnsDef` — labels, widths and formats for the columns, keyed by column code. Optional
+  since the registrar derives a procedure's columns from its `RETURNS TABLE (…)` signature;
+  ship it when you want a label or a width rather than the bare column code. It is an
+  **override** — `report.run` projects `dForge.sp_column`, and `columnsDef` only restyles it.
+  A function returning an unnamed `SETOF <composite>` or a bare scalar declares no column
+  names, so that one needs an explicit `columns` block in `logic/stored_procedures.json`.
 - 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):
+**Multi-result-set SPs** map extra datasets to the same function via `parentDatasetCd` (the dataset that owns the SP call) + `parentRef` (the named refcursor). **Not wired at runtime**: both columns install, but `report.run` executes only datasets holding their own `sp_id`, so a child dataset returns nothing. Give each dataset its own function until that changes.
 
 ```json
 "datasets": {
@@ -119,10 +124,8 @@ SP files live in `logic/reports/` and follow this convention:
 
 ```sql
 CREATE OR REPLACE FUNCTION crm.rpt_ar_aging(
-    p_folder_uid uuid,        -- REQUIRED: injected by platform (folder context)
-    p_user_id bigint,         -- REQUIRED: injected by platform (current user)
-    p_as_of_date date DEFAULT NULL,    -- User parameter
-    p_customer_id bigint DEFAULT NULL  -- User parameter (optional)
+    p_as_of_date date DEFAULT NULL,    -- one per declared param, in declaration order
+    p_customer_id bigint DEFAULT NULL
 )
 RETURNS TABLE ( customer_name text, current_amount numeric, total numeric )
 LANGUAGE sql STABLE
@@ -135,10 +138,25 @@ $$;
 ```
 
 **Rules for SP functions:**
-- First two params are **always** `p_folder_uid uuid` and `p_user_id bigint` — injected by the platform.
-- User params come after, `DEFAULT NULL` for optional ones (order matches `params` declaration order).
-- `RETURNS TABLE (...)` for a single set; `RETURNS SETOF refcursor` for multi-set (mapped via `parentRef`).
-- Use the module's schema prefix (`crm.rpt_*`), `STABLE` volatility, and filter by `p_folder_uid` / `p_user_id` where needed — **security is your responsibility**.
+- The signature is **exactly** the params declared in `logic/stored_procedures.json`, in that
+  order. `report.run` passes one positional argument per declared param and **nothing else** —
+  there is no folder or user argument, and a function taking one can never be called. Install
+  rejects the mismatch (`no callable PostgreSQL function … with N argument(s)`).
+- `DEFAULT NULL` for optional params — an empty one arrives as a typed NULL.
+- `pgType` must be a scalar type the runtime binds: `bigint`, `integer`, `smallint`,
+  `numeric`, `real`, `double precision`, `text`, `boolean`, `uuid`, `date`, `timestamp`,
+  `timestamptz`, `time`, or an alias of one. A type modifier is ignored, so
+  `numeric(18,2)` is fine. `jsonb`, arrays, enums and `citext` are rejected at install.
+- `paramCd` is capped at 50 characters, and a declared `fieldTypeCd` must be a real one —
+  both are checked at install, because binding the SP in the report editor copies them
+  into report params.
+- `RETURNS TABLE (...)`.
+- Use the module's schema prefix (`crm.rpt_*`) and `STABLE` volatility.
+- **Security is your responsibility, and the function has no context to work from**: it is not
+  told the folder or the user, so an SP dataset cannot be row-level scoped the way a `"Q"`
+  dataset is. Use `"Q"` for anything that must be filtered per user, and keep `"S"` for
+  aggregates that are safe for everyone holding the report's grant.
+- Grant **both** `report:<code>` and `sp:<spCd>` — see `references/security.md`.
 
 ## Parameters
 
@@ -354,13 +372,16 @@ A dependency's report is granted with the qualified form, `"report:fin.ar_aging"
 - Setting the chart kind as `vizType` (`"vizType": "bar"`) — the panel `vizType` is `"chart"`; the kind goes in `config.chartType`.
 - Using `entityCode` / `groupBy` / `aggregations` on a dataset — use `query.entityCd` + `query.columns`, and aggregate in the viz (`agg`, `metrics`).
 - Using `sp` / `procedureName` for an SP dataset — the field is `spCd`.
-- Forgetting `columnsDef` on an SP dataset — **required**.
+- Assuming an SP dataset must carry `columnsDef` — it is an override over the columns the
+  registrar derives from the function signature, not the source of them.
 - 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.
+- Giving an SP function `p_folder_uid` / `p_user_id` params — the platform passes neither, so install rejects the function as uncallable. The signature is exactly the declared params.
+- Granting only `report:<code>` on a report with a `datasetType: "S"` dataset — it also needs `sp:<spCd>`, or every user gets PERMISSION_DENIED on open.
+- Declaring an SP param as `jsonb`, an array, an enum or `citext` — the runtime binds scalar types only (`bigint`, `integer`, `smallint`, `numeric`, `real`, `double precision`, `text`, `boolean`, `uuid`, `date`, `timestamp`, `timestamptz`, `time` and their aliases), and install rejects anything else. `citext` looks like `text` but is a distinct type PostgreSQL will not resolve a text argument against.
 - 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/security.md

@@ -75,11 +75,11 @@ Example:
 | `D` | Delete (remove rows) |
 | `C` | Clone (duplicate a row as a new record) |
 
-### Action/Report/Folder rights
+### Action/Report/SP/Folder rights
 
 | Letter | Permission |
 |---|---|
-| `E` | Execute (run the action/report, access the folder) |
+| `E` | Execute (run the action/report/stored procedure, access the folder) |
 
 ### Common combinations
 
@@ -100,8 +100,13 @@ Role rights map object codes (entities, actions, reports) to rights strings. Obj
 - `fin.invoice` — the entity "invoice" in the `fin` module (cross-module entity — **dot**)
 - `action:send_welcome` — an action named "send_welcome" (**colon**)
 - `report:sales_pipeline` — a report named "sales_pipeline" (**colon**)
+- `sp:rpt_sales_totals` — a stored procedure from `logic/stored_procedures.json` (**colon**)
 - `folder:customers` — the folder with code "customers" (**colon**)
 
+`report:` and `sp:` also take a qualified form — `report:fin.ar_aging`, `sp:fin.rpt_ar_aging` — to
+grant on a **dependency's** report or stored procedure. `action:` and `folder:` do not: the
+installer resolves those within this module only, so a dotted one silently grants nothing.
+
 > **Separator matters — colon for non-entity objects, dot only for cross-module entities.**
 > Actions, reports and folders are prefixed with a **colon**: `action:<code>`, `report:<code>`,
 > `folder:<code>`. A **dot** is reserved for a cross-module *entity* (`module.entity`, e.g.
@@ -118,7 +123,28 @@ Role rights map object codes (entities, actions, reports) to rights strings. Obj
 4. **Never grant `D` (Delete) to a rep-level role** unless deletion is a normal part of their job. Audit trails prefer soft-delete or update.
 5. **Always grant the admin role `SIUDC` on everything the module owns.**
 6. **Action and report access** — grant `E` on specific action/report codes, or omit them entirely (defaulting to no access).
-7. **Folder access** is granted separately — roles can reference folder codes, but folder definitions themselves live in `ui/folders.json`.
+7. **A report with a `datasetType: "S"` dataset needs TWO grants** — `report:<code>` **and**
+   `sp:<spCd>` for the stored procedure the dataset binds. `report.run` enforces the SP's own
+   sec_object on top of the report's right, so granting only the report yields
+   `PERMISSION_DENIED` on open. There is no recovery after install: the role-rights admin UI
+   lists entities, actions and reports only, so a tenant admin cannot add an SP grant by hand.
+   `dforge_module_pack` fails the build when a role grants such a report and no role grants
+   the SP — for the module's own SP. A dependency's SP is left to install: its grant may
+   ship with the dependency's own role, and rights are additive across the roles a user holds.
+
+```json
+{
+    "sales.analyst": {
+        "description": "Sales Analyst",
+        "rights": {
+            "opportunity": "S",
+            "report:sales_totals": "E",
+            "sp:rpt_sales_totals": "E"
+        }
+    }
+}
+```
+8. **Folder access** is granted separately — roles can reference folder codes, but folder definitions themselves live in `ui/folders.json`.
 
 ## Folders (`ui/folders.json`)