@dforge-core/dforge-mcp 0.2.24 → 0.2.26

package/CHANGELOG.md

@@ -4,6 +4,67 @@ 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.26
+
+`logic/stored_procedures.json` is now something this server can describe. It had no
+schema, no reference and no resource — yet a `datasetType: "S"` dataset is unusable
+without it, because that file is what registers the function as the `spCd` a dataset
+binds and the `sec_object` an `sp:` right is granted on. An author who reached the
+install error demanding the file had nothing to read and guessed at its shape
+(dForge-core#1191). `dforge://schema/stored-procedures` serves it now, and
+`dforge://reference/reports` gained the declaration block, the `functionName` rule —
+it names the FUNCTION, not the `logic/reports/*.sql` script that creates it, and
+nothing in the file ever names a script — and the missing-declaration mistake.
+
+**`reports.schema.json` was actively wrong about the field an SP dataset binds
+through.** It declared `procedureName` under `additionalProperties: false`, so the
+schema this server serves *rejected* the real `spCd` and accepted a name the platform
+has never read. Re-vendored from `@dforge-core/metadata` 0.0.29, which fixes it.
+
+The same bump corrects `entity.schema.json`, which had drifted two releases behind:
+a column's `pattern` / `patternFlags` (format rules are metadata now, enforced in the
+browser and again on `data.insert` / `data.update`) and `lockedFields` on an
+accumulation register.
+
+The references also stop contradicting themselves on parameter codes. A report
+parameter must be spelled exactly as the procedure declares its `paramCd` —
+`report.run` resolves each argument by that code alone and neither adds nor strips a
+prefix — but the worked example named report parameters `customer_id` against a
+procedure declaring `p_customer_id`, which binds NULL and makes the filter silently
+disappear. Aligned, with the rule stated beside it.
+
+**Still missing:** no tool here writes `logic/stored_procedures.json`, and
+`dforge_report_add` takes its `datasets` map unvalidated — so an agent building an SP
+report still emits the `.sql` file and the dataset and no declaration, which is the
+shape that produced dForge-core#1191 in the first place.
+
+## 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

@@ -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.19/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.20/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -31283,7 +31283,7 @@ function buildZedTasks() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.27/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.29/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.27/node_modules/@dforge-core/metadata/dist/dsl/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.29/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) {
@@ -38042,6 +38043,11 @@ var resources = [
     "Reports JSON schema",
     "JSON Schema for ui/reports.json \u2014 map of report code \u2192 { description, layout.panels[], datasets, parameters? }. Datasets and panel queries reuse the filter shape from data_views."
   ),
+  schema(
+    "stored-procedures",
+    "Stored procedures JSON schema",
+    "JSON Schema for logic/stored_procedures.json \u2014 map of stored-procedure code \u2192 { functionName, schemaName?, params?, columns? }. Required for any report dataset with datasetType 'S': the .sql file under logic/reports/ creates the function, this file registers it as the spCd a dataset binds and the sec_object an sp: right is granted on. functionName names the FUNCTION, never the script."
+  ),
   {
     uri: "dforge://docs/conventions",
     name: "dForge module conventions",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.24",
+	"version": "0.2.26",
 	"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",
@@ -35,8 +35,8 @@
 		"install-skills": "node scripts/install-skills.mjs"
 	},
 	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.19",
-		"@dforge-core/metadata": "^0.0.27",
+		"@dforge-core/dforge-cli": "^0.2.20",
+		"@dforge-core/metadata": "^0.0.29",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"zod": "^4.4.3"
 	},

package/resources/schemas/entity.schema.json

@@ -363,6 +363,15 @@
 						},
 						"serverDefault": {
 							"$ref": "#/$defs/serverDefault"
+						},
+						"pattern": {
+							"type": "string",
+							"description": "Format rule for this column, as an ECMAScript regex source. Overrides the field type's own pattern (field_type.def_params.pattern, which is what makes email/phone/url reject a malformed value). Enforced in the browser and again on data.insert / data.update, so keep to constructs both engines read alike: [0-9] and \\d are the same there, \\s is normalized to JavaScript's set, and a pattern that will not compile is skipped by both rather than enforced by one."
+						},
+						"patternFlags": {
+							"type": "string",
+							"description": "Flags for 'pattern', as a JavaScript regex literal would carry them; 'i' and 'm' are the two honoured, each at most once — the RegExp constructor rejects a repeated flag, and a rule the browser cannot compile is skipped there and would then be enforced by the API alone. JavaScript has no inline (?i), so case-insensitivity has to be stated here.",
+							"pattern": "^(i|m|im|mi)?$"
 						}
 					}
 				},
@@ -569,7 +578,7 @@
 		"accumulationConfig": {
 			"type": "object",
 			"description": "Configuration for simple accumulation (document without lines, e.g. receipt → stock).",
-			"required": ["balanceEntity", "dimensions", "resources"],
+			"required": ["balanceEntity", "dimensions", "resources", "lockedFields"],
 			"properties": {
 				"balanceEntity": { "type": "string", "description": "Balance entity code (e.g. 'stock')" },
 				"dimensions": {
@@ -596,7 +605,6 @@
 				"allowNegative": { "type": "boolean", "default": true },
 				"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/reports.schema.json

@@ -249,9 +249,9 @@
 					"$ref": "#/$defs/query",
 					"description": "Used when datasetType is 'Q'"
 				},
-				"procedureName": {
+				"spCd": {
 					"type": "string",
-					"description": "Used when datasetType is 'S'"
+					"description": "Used when datasetType is 'S': the stored-procedure code, as `logic/stored_procedures.json` keys it — NOT the PostgreSQL function name and never schema-qualified. `module.spCd` binds a dependency's procedure. Resolved to `report_ds.sp_id` at install. A role granting `report:<code>` must also grant `sp:<spCd>`, which no admin UI can add afterwards."
 				},
 				"columnsDef": {
 					"type": "object",

package/resources/schemas/stored-procedures.schema.json

@@ -0,0 +1,125 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "dForge Module Stored Procedures",
+	"description": "Stored-procedure declarations for a dForge module package (logic/stored_procedures.json). Each entry registers one PostgreSQL function as a procedure a report dataset can bind with `datasetType: \"S\"` and `spCd`. The SQL that creates the function ships separately, as a CREATE OR REPLACE FUNCTION script under logic/reports/; this file does not name the script, it names the function the script creates. See docs/business-logic/stored-procedures.md.",
+	"type": "object",
+	"additionalProperties": {
+		"type": "object",
+		"required": ["functionName"],
+		"description": "Keyed by stored-procedure code (sp_cd) — module-internal, referenced from a dataset's `spCd` and a role's `sp:` right. It may not contain a dot: a dot is the module qualifier in both of those key spaces.",
+		"properties": {
+			"description": {
+				"type": "string",
+				"description": "Label for the procedure, shown in the report editor's procedure picker. Defaults to the code."
+			},
+			"schemaName": {
+				"type": "string",
+				"pattern": "^[a-zA-Z_][a-zA-Z0-9_\\-]*$",
+				"description": "PostgreSQL schema holding the function. Defaults to the module's own schema, which is what a module-shipped function normally uses."
+			},
+			"functionName": {
+				"type": "string",
+				"pattern": "^[a-zA-Z_][a-zA-Z0-9_\\-]*$",
+				"description": "The PostgreSQL function's own name, unqualified — `report.run` calls SELECT * FROM \"schemaName\".\"functionName\"(...). Required: it is the one fact this file exists to record, and install fails naming it when absent."
+			},
+			"returnsTable": {
+				"type": "boolean",
+				"default": true,
+				"description": "The function is set-returning (RETURNS TABLE / SETOF). The only shape report.run projects."
+			},
+			"params": {
+				"type": "array",
+				"description": "The call signature, in order: report.run passes exactly one positional argument per entry and NOTHING else — no folder, no user. A function taking p_folder_uid / p_user_id can never be called, and install rejects the arity mismatch. Omit the block for a function taking no arguments.",
+				"items": { "$ref": "#/$defs/param" }
+			},
+			"columns": {
+				"type": "array",
+				"description": "Result columns, stored in dForge.sp_column and used to project the dataset. Omit the block and the registrar derives them from the function's own RETURNS TABLE / OUT column names. Declare it to set labels, widths, a currency/percent control or a refEntityCd link — a declared list is used as written and never merged with the signature. A function returning an unnamed SETOF composite or a bare scalar declares no column names, so it must list them here.",
+				"items": { "$ref": "#/$defs/column" }
+			}
+		},
+		"additionalProperties": false
+	},
+
+	"$defs": {
+		"param": {
+			"type": "object",
+			"required": ["paramCd"],
+			"properties": {
+				"paramCd": {
+					"type": "string",
+					"maxLength": 50,
+					"description": "Parameter code. Conventionally the function's own argument name (p_customer_id), though the call is positional."
+				},
+				"pgType": {
+					"type": "string",
+					"default": "bigint",
+					"description": "PostgreSQL type of the argument — this is what binds the value, and it is carried even when the value is null so an omitted optional argument arrives as a TYPED null. Defaults to `bigint`, so declare it for every argument that is not one. One of: bigint, integer, smallint, numeric, real, double precision, text, boolean, uuid, date, timestamp, timestamptz, time — or any alias PostgreSQL treats as the same type (int8, int4, int, int2, decimal, float8, float4, varchar, character varying, char, bpchar, bool, timestamp without time zone, timestamp with time zone, time without time zone). Case does not matter and a type modifier is ignored, so `numeric(18,2)` may be pasted straight from the signature. jsonb, arrays, enums and citext cannot be bound and are rejected at install. Enforced by SpParamTypes, which is where this list lives — left out of an enum here so the spellings install accepts are not flagged by an editor.",
+					"examples": ["bigint", "text", "date", "numeric(18,2)", "timestamptz", "uuid", "boolean"]
+				},
+				"fieldTypeCd": {
+					"type": "string",
+					"description": "Control the report editor copies into the report param when the procedure is bound there. Optional — derived from pgType when omitted."
+				},
+				"label": {
+					"type": "string",
+					"description": "Parameter label for that same copy."
+				},
+				"required": {
+					"type": "boolean",
+					"default": true,
+					"description": "Whether the parameter must have a value. Give every optional one DEFAULT NULL in the function signature."
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"column": {
+			"type": "object",
+			"required": ["columnCd"],
+			"properties": {
+				"columnCd": {
+					"type": "string",
+					"maxLength": 100,
+					"description": "Result column name as the function returns it. Unique within the procedure."
+				},
+				"label": {
+					"type": "string",
+					"description": "Column header. Defaults to the code."
+				},
+				"fieldTypeCd": {
+					"type": "string",
+					"default": "text",
+					"description": "Control that renders the value (number, currency, date, dropdown, flags, ...)."
+				},
+				"baseDatatypeCd": {
+					"type": "string",
+					"default": "string",
+					"description": "Underlying datatype the value is read as."
+				},
+				"orderNum": {
+					"type": "integer",
+					"description": "Display order. Defaults to declaration order in steps of 10."
+				},
+				"refEntityCd": {
+					"type": "string",
+					"description": "Entity this column links to, making the value clickable. Resolved within this module and its dependencies."
+				},
+				"refColumnCd": {
+					"type": "string",
+					"description": "Column in the result holding the FK value for that link, when it is not this column."
+				},
+				"width": {
+					"type": "integer",
+					"description": "Column width in pixels."
+				},
+				"params": {
+					"type": "object",
+					"description": "Control parameters, the same shape an entity column's `params` takes — `options` for a dropdown or flags, `currency`, `align`, and so on.",
+					"additionalProperties": true
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

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

@@ -87,8 +87,8 @@ For SQL the query builder can't express — window functions, CTEs, cross-schema
     "datasetType": "S",
     "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": { "link": { "entity": "account" } } }
+        "p_as_of_date": { "fieldTypeCd": "date", "label": "As of Date", "required": true, "default": "=NOW()" },
+        "p_customer_id": { "fieldTypeCd": "lookup", "label": "Customer", "required": false, "params": { "link": { "entity": "account" } } }
     },
     "columnsDef": {
         "customer_name": { "label": "Customer", "fieldTypeCd": "text", "baseDatatypeCd": "string", "width": 200 },
@@ -100,11 +100,22 @@ 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.
+- `spCd` — the stored-procedure **code**: the key of an entry in `logic/stored_procedures.json`, never schema-qualified, resolved to `sp_id` at install. By convention it is spelled the same as the function it declares, but it is the code that is matched, not the function name. (**Not** `sp` or `procedureName`.)
+- `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.
+- **The parameter code must match the procedure's declared `paramCd` exactly.** `report.run`
+  resolves each argument by that code alone — no prefix is added or stripped — so a report
+  offering `customer_id` against a procedure declaring `p_customer_id` passes NULL and the
+  filter silently does nothing. Prefix the report parameter too (as above), or drop the
+  prefix from `paramCd`; the SQL argument name is unconstrained either way, the call being
+  positional.
 
-**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 +130,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 +144,54 @@ $$;
 ```
 
 **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`.
+
+### The declaration — `logic/stored_procedures.json`
+
+The function existing in the database is not enough: this file is what creates the
+`stored_procedure` row an `spCd` resolves to and the `sec_object` an `sp:` right is
+granted on. Keyed by stored-procedure code, which may not contain a dot.
+
+```json
+{
+    "rpt_ar_aging": {
+        "description": "AR Aging",
+        "functionName": "rpt_ar_aging",
+        "params": [
+            { "paramCd": "p_as_of_date",  "pgType": "date",   "fieldTypeCd": "date",   "label": "As of Date", "required": true },
+            { "paramCd": "p_customer_id", "pgType": "bigint", "fieldTypeCd": "lookup", "label": "Customer",   "required": false }
+        ]
+    }
+}
+```
+
+- **`functionName` is required** — the function's own name, unqualified. It is **not** the
+  path of the `.sql` file: nothing here names a script, because every `logic/reports/*.sql`
+  runs at install regardless. Omitting it fails the package at load, on `pack`/`validate`
+  and every install path alike.
+- **`schemaName`** is optional, defaulting to the module's own schema.
+- **`params`** is the call signature, in order — omit it for a zero-argument function.
+- **`columns`** is optional; without it install derives the result columns from the
+  function's `RETURNS TABLE (…)`.
+- Schema: `stored_procedures.schema.json`.
 
 ## Parameters
 
@@ -354,13 +407,22 @@ 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**.
+- Shipping an SP's `.sql` file and its dataset but no `logic/stored_procedures.json` entry —
+  the function exists, the dataset names something, and nothing connects the two.
+- Writing `file` / `function` in `logic/stored_procedures.json` — the one required field is
+  `functionName`, and it names the function, not the script that creates it.
+- Naming a report parameter `customer_id` for a procedure param declared `p_customer_id` —
+  the lookup is by exact code, so the argument binds NULL and the filter quietly disappears.
+- 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`)