@dforge-core/dforge-mcp 0.2.15 → 0.2.17

package/CHANGELOG.md

@@ -4,6 +4,198 @@ 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.17
+
+A bridge module's `async: false` trigger **can** roll back its host module's write,
+and that is intended (platform issue #999). It is the same coupling a mandatory
+extension column already creates — mark one `M` and the host's own `data.insert`
+is refused with *"Missing required columns: …"* for a field the host knows nothing
+about. A bridge that can add a required field can add a required *condition*, and
+cross-module invariants are what bridge modules exist to enforce.
+
+What changed platform-side is that the veto now says who issued it, so the guidance
+here says what to point it at.
+
+### Changed — `async: false` is a refusal mechanism, not a reaction
+
+`dforge_trigger_add`'s `async` description and `dforge-module-build` Phase 2b both
+said only that a failure "rolls back the original change" — true, and read by an
+authoring agent as a footnote about transactions rather than as the decision it is.
+Both now state that the rollback reaches **another module's** entity, and the rule
+that follows: pick `async: false` to enforce an invariant, not merely to react,
+because a bug in the action blocks the host's workflow exactly as effectively as a
+real violation. Keep such an action to the check and put the rest behind
+`try`/`catch` or in an `async: true` trigger.
+
+### Changed — a blocked write names the module that blocked it
+
+Trigger failures now report error code **`TRIGGER_ACTION_FAIL`** (the other action
+phases keep `ACTION_EXECUTION_FAIL`), rendered as *Blocked by "crm-fin" (automation
+"on_invoice_posted"): Credit limit exceeded.* in the caller's locale, with the
+action's own `error()` text passed through. The module named is the one that
+**declared the trigger**, not the one owning the action — a bridge routinely
+subscribes its own trigger to an action living elsewhere, and what refused the write
+is the subscription. Nothing to change in a module for this; it is what an author
+should expect to see when their trigger fires.
+
+Nothing is rejected that was accepted before — `dforge_module_validate` is unchanged.
+
+## 0.2.16
+
+Entity views — the platform's **column-level security** — became reachable from a
+module package (platform change `e6e29b604`). A view is a named subset of an
+entity's columns declared under `views` on the entity file; a folder binds one per
+entity with `entities.<code>.viewName`, and users working there see only the
+columns that view lists. The schema had gained the property while nothing here
+knew about it, so authoring one meant an editor error on valid metadata and a
+refactor that could quietly break the module.
+
+### Added — entity views are validated offline
+
+`dforge_module_validate` now mirrors what the platform installer rejects, all of
+which is silent at runtime if it slips through:
+
+| Check | Why it matters |
+|---|---|
+| Column exists on the entity | A stale name is simply not in the view |
+| View lists the primary key | Records are addressed by it — the client cannot open a row without it |
+| View has at least one column | A view is the COMPLETE visible set, so an empty one would hide every field |
+| No two views differing only by case | A folder binds case-insensitively; only one could ever be reached |
+| No column listed twice under different casing | Both name one column and the later would silently win |
+| `formula` override only on a `columnType: "F"` column | Elsewhere that field is the SQL default and the install FAILS — a view cannot change a physical column's `DEFAULT` |
+| `folders.json` `viewName` resolves to a declared view | **Fails the install** — it does not fall back, because falling back shows every column |
+
+`"default"` is exempt from the last check and means "no view": every shipped module
+writes it, and the platform auto-creates a column-less row under that name for any
+entity reached without a folder binding.
+
+### Fixed — refactors reach into views
+
+`dforge_entity_field_rename` and `dforge_entity_field_remove` rewrote fields, links,
+formulas, data views and seed data but never touched `views.<v>.columns.<cd>`. Since
+the platform now rejects a view naming a column the entity does not have, a rename
+handed back a module that no longer installs. Both cascade into entity views now,
+including per-view `formula` overrides, preserving the view's column order (which is
+its display order). Removal warns when a view is left with no columns, or when a
+per-view formula still names a removed field — the same judgement-call warnings the
+tool already emitted for entity formulas.
+
+### Fixed — `viewName` was documented as a data view code
+
+It is not, and the mistake ran from `schemas/folders.schema.json` through
+`references/security.md` to `dforge-module-build`'s Phase 3, which claimed
+`"default"` was "a fallback alias the platform resolves to the entity's first
+declared view". It resolves to *no view* (the full column set), and any other
+undeclared name now fails the install — so the wrong mental model produced a hard
+error rather than a shrug. Data view codes are what a menu's `dataViewCode`
+references.
+
+### Changed
+
+- `@dforge-core/metadata` → `0.0.18`; `resources/schemas/` re-vendored, so
+  `entity.schema.json` carries `views` (with the per-column `formula` override), the
+  retired `H` flag and the per-view `M` fold below, and the editor stops flagging a
+  valid `views` block as an unknown property. The
+  `minimumReleaseAgeExclude` pin in `pnpm-workspace.yaml` moves with it — a caret on
+  a `0.0.x` version pins the patch, so the dep does not float onto a new metadata
+  release by itself.
+- `references/security.md` gains a **Column-level security** section — the layer the
+  3-layer model named but never documented — with the rules, the empty-override trap
+  (`COALESCE` skips NULL only, so `"flags": ""` means "no flags", not "inherit"), and
+  a table disambiguating the platform's three "views": entity views, data views, and
+  `isView`/`viewSql` SQL-backed entities.
+- Cross-references in `references/flags.md` (the same letters override per view),
+  `references/formulas.md` (the per-view override and its `"F"`-only rule) and
+  `references/data-views.md` (the name collision); two new lines in
+  `references/validation-checklist.md`; `dforge-module-build` Phase 5 gains guidance
+  on when column-level security is the right answer instead of more roles.
+- `dforge_module_inspect` reports `entityViews` per entity (name → column count).
+
+### Removed — the `H` flag
+
+`H` was in the flag vocabulary from the start, documented as "permanently hidden —
+stronger than omitting `V`", and **nothing ever read it**. A column carrying it was
+hidden because its flags string contained no `V`. The platform retired it
+(`abbedb009`), so `field-rules` now rejects `H` with a message pointing at the fix
+rather than at the generic "U/S/P are not flag letters" hint: omit `V` to hide a
+column, use an entity view to hide it from specific folders, `fieldTypeCd: "hidden"`
+to render it as a hidden input, and `I` to mark it platform-managed.
+
+`references/flags.md` and the `dforge://reference/flags` blurb drop it too, and both
+`^[VIEMH]+$` checks in `field-rules` are now `^[VIEM]+$`.
+
+### Added — `M` in a per-view override
+
+`views.<v>.columns.<cd>.flags` previously accepted `M` and did nothing with it: the
+platform's `MandatoryFlagNormalizer` folded `M` into `isNullable` for entity fields
+only. The fold now covers view overrides, so the shorthand means the same thing at
+both levels — and because a view writes no DDL, the requiredness it produces is
+runtime-only. That makes **"nullable in the database, mandatory in this view"**
+expressible for the first time:
+
+```json
+"vat_no": { "flags": "VEM" }                      // required in this view
+"vat_no": { "flags": "VE", "isNullable": false }  // the same thing, spelled out
+```
+
+`references/flags.md` gains a **Per-view overrides** section covering it, plus the
+two traps that come with it: the letters **replace** rather than merge (so
+`{ "flags": "V" }` is read-only however the entity flagged the column), and the `M`
+fold is **one-directional** — dropping `M` from a view does not make a column
+optional, since `isNullable` still inherits. `references/security.md` picks up the
+same note.
+
+### Fixed — smaller documentation corrections
+
+- **`I` was called "Internal" throughout `references/flags.md`.** The runtime reads
+  it as **Identity** (`EntityColumn.IsIdentity => HasFlag('I')`); the letter is
+  unchanged, the name was wrong in the letter table, two rules and the role-rights
+  disambiguation note.
+- **`"flags": null` was implied to mean "inherit".** It does not validate — the
+  property is typed `string`, so only OMITTING the key inherits. (To inherit
+  everything, set the whole column override to `{}` or `null`.)
+
+### Added — a worked example module
+
+`examples/column-security/` (served as `dforge://example/column-security/…`): one
+`product` entity carrying both stock and pricing, two folders showing two different
+column sets of it. It is the first bundled example with a `ui/folders.json` at all,
+so the *binding* half of column-level security had no example anywhere before.
+
+Its `accountant` view demonstrates both override kinds — `{ "flags": "V" }` making a
+column read-only in that view only, and a per-view `formula` computing margin as a
+percentage where the entity computes an amount — while `storekeeper` shows the plain
+case where the price columns are simply absent. The README lists the five ways a view
+fails the install, and a test pins the module at zero errors AND zero warnings, since
+a warning copied out of an example propagates into every module built from it.
+
+Note its manifest declares no `dataViews`/`menus`/`security` pointers: those files are
+found by convention and the manifest schema is `additionalProperties: false`.
+
+### Fixed — `simple-todo`'s manifest was not schema-valid
+
+It declared `dataViews`, `menus`, `actions`, `security` and `seedData` pointers. None
+of those are manifest properties, the schema is `additionalProperties: false`, and no
+shipped module declares them — every path is resolved by convention from the module
+root (`ui/data_views.json`, `security/roles.json`, …), here and in the platform alike.
+Removed. This matters more than a stray key usually would: the examples are served as
+resources and described to agents as mandatory structures to copy, so an invalid shape
+in one propagates into every module built from it.
+
+### Fixed — the view-column flag vocabulary
+
+`entity.schema.json` described a view column's `flags` as `I/E/V/O/G/S/F/X/W`, with the
+example `'VO'` "to expose it read-only". No such letters: the canonical set is
+`V/I/E/M/H` (`flagDefs`), the client `Column` honours `V`/`E`/`I`, and the installer
+resolves `M` into `isNullable`. Nothing reads `O`, `G`, `S`, `F`, `X` or `W`. Read-only
+is plain `"V"` — visible, not editable.
+
+`references/flags.md` here was already right, and both the new guidance and the
+`column-security` example use only `V`/`VE`. Fixed upstream and picked up with
+`@dforge-core/metadata` **0.0.17**, so `resources/schemas/entity.schema.json` now says
+the same thing — which matters because that is the copy the editor `$schema` binding
+validates against.
+
 ## 0.2.15
 
 `canExecute` became a real server-side gate and `isTransacted` began opening a real

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.14/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.15/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.15/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.20/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -33137,9 +33137,10 @@ function checkFieldSpec(where, field) {
       'dropdown options go under params.options, not at the field root, e.g. "params": { "options": [{ "value": "a", "label": "A" }] }.'
     );
   }
-  if (typeof v.flags === "string" && v.flags.length > 0 && !/^[VIEMH]+$/.test(v.flags)) {
+  if (typeof v.flags === "string" && v.flags.length > 0 && !/^[VIEM]+$/.test(v.flags)) {
+    const hint = v.flags.includes("H") ? " There is no 'H' flag \u2014 a column is hidden by omitting 'V'." : " U/S/P are not flag letters.";
     err(
-      `flags '${v.flags}' contains invalid letters \u2014 use only V/I/E/M/H (e.g. VEM, VE, V, E). U/S/P are not flag letters.`
+      `flags '${v.flags}' contains invalid letters \u2014 use only V/I/E/M (e.g. VEM, VE, V, E).${hint}`
     );
   }
   if (typeof v.flags === "string" && v.flags.includes("M") && v.isNullable === true) {
@@ -33186,7 +33187,7 @@ function checkFieldSpec(where, field) {
     if (typeof v.formula !== "string" || v.formula.trim() === "") {
       err("formula column (columnType 'F') requires a non-empty 'formula' expression.");
     }
-    if (typeof v.flags === "string" && v.flags !== "V" && /^[VIEMH]+$/.test(v.flags)) {
+    if (typeof v.flags === "string" && v.flags !== "V" && /^[VIEM]+$/.test(v.flags)) {
       warn(
         `formula column has flags '${v.flags}' \u2014 a computed column is read-only, expected flags 'V'.`
       );
@@ -33717,6 +33718,23 @@ function entityFieldRename(args) {
       changes.push(`references.${rname}.from.field`);
     }
   }
+  const entityViews = entity.views ?? {};
+  for (const [vname, v] of Object.entries(entityViews)) {
+    const cols = v.columns;
+    if (!cols) continue;
+    if (oldName in cols) {
+      v.columns = renameKey(cols, oldName, newName);
+      changes.push(`views.${vname}.columns.${oldName}`);
+    }
+    for (const [cn, ov] of Object.entries(
+      v.columns
+    )) {
+      if (ov && typeof ov.formula === "string" && ov.formula.includes(oldToken)) {
+        ov.formula = ov.formula.split(oldToken).join(newToken);
+        changes.push(`views.${vname}.${cn}.formula`);
+      }
+    }
+  }
   files[rel(paths.root, entityPath)] = jsonText(entity);
   for (const [oname, orel] of Object.entries(manifest.entities ?? {})) {
     if (oname === entityName || oname.includes(".")) continue;
@@ -33840,6 +33858,31 @@ function entityFieldRemove(args) {
       changes.push(`references.${rn}`);
     }
   }
+  const entityViews = entity.views ?? {};
+  for (const [vname, v] of Object.entries(entityViews)) {
+    const cols = v.columns;
+    if (!cols) continue;
+    const kept = {};
+    for (const [k, val] of Object.entries(cols)) if (!removed.has(k)) kept[k] = val;
+    if (Object.keys(kept).length !== Object.keys(cols).length) {
+      v.columns = kept;
+      changes.push(`views.${vname}.columns`);
+    }
+    if (Object.keys(kept).length === 0) {
+      warnings.push(
+        `view '${vname}' has no columns left \u2014 delete the view, or give it columns (an empty view fails the install)`
+      );
+    }
+    for (const [cn, ov] of Object.entries(kept)) {
+      if (ov && typeof ov.formula === "string") {
+        for (const r of removed) {
+          if (ov.formula.includes(`[${r}]`)) {
+            warnings.push(`formula in view '${vname}'.${cn} still references removed '[${r}]'`);
+          }
+        }
+      }
+    }
+  }
   files[rel(paths.root, entityPath)] = jsonText(entity);
   for (const [fn, f] of Object.entries(entity.fields)) {
     if (typeof f.formula !== "string") continue;
@@ -35372,6 +35415,11 @@ function moduleInspect(args) {
       fieldCount: Object.keys(fields).length,
       fields: Object.keys(fields),
       hasNumberSequence: Boolean(e.numberSequence),
+      entityViews: Object.fromEntries(
+        Object.entries(e.views ?? {}).map(
+          ([vname, v]) => [vname, Object.keys(v?.columns ?? {}).length]
+        )
+      ),
       // Read as an OWN property — `toString` is inherited from
       // Object.prototype, so a plain `e.toString` reports the built-in
       // function (which JSON.stringify then silently drops) for every
@@ -35615,6 +35663,67 @@ function moduleValidate(args) {
       }
     }
   }
+  for (const [name, e] of Object.entries(entities)) {
+    const entityViews = e.views ?? {};
+    if (Object.keys(entityViews).length === 0) continue;
+    const fields = fieldDefsOf[name] ?? {};
+    const cols = columnsOf[name];
+    const pk = pkOf2(name);
+    const byLower = /* @__PURE__ */ new Map();
+    for (const vname of Object.keys(entityViews)) {
+      const list = byLower.get(vname.trim().toLowerCase()) ?? [];
+      list.push(vname);
+      byLower.set(vname.trim().toLowerCase(), list);
+    }
+    for (const [, spellings] of byLower) {
+      if (spellings.length > 1) {
+        err(
+          `entities/${name}.json \u2192 views`,
+          `views ${spellings.map((v) => `'${v}'`).join(" and ")} differ only by case or surrounding whitespace. A folder binds a view case-insensitively, so only one could ever be reached.`
+        );
+      }
+    }
+    for (const [vname, view] of Object.entries(entityViews)) {
+      const where = `entities/${name}.json \u2192 views.${vname}`;
+      const vcols = view?.columns ?? void 0;
+      if (!vcols || Object.keys(vcols).length === 0) {
+        err(
+          where,
+          "lists no columns. A view is the COMPLETE set of columns visible in a folder bound to it, so an empty one would hide every field \u2014 the installer rejects it."
+        );
+        continue;
+      }
+      const declared = Object.keys(vcols);
+      for (const cd of declared) {
+        if (cols && !cols.has(cd)) {
+          err(where, `column '${cd}' is not a field on entity '${name}'`);
+        }
+      }
+      const dupes = declared.filter(
+        (c, i) => declared.findIndex((o) => o.toLowerCase() === c.toLowerCase()) !== i
+      );
+      for (const d of dupes) {
+        err(where, `lists column '${d}' more than once (differing only by case)`);
+      }
+      if (pk && !declared.some((c) => c.toLowerCase() === pk.toLowerCase())) {
+        err(
+          where,
+          `omits the primary key '${pk}'. A view must list it \u2014 records are addressed by it. To keep it off the screen, drop 'V' from its flags instead of omitting it.`
+        );
+      }
+      for (const [cd, ovRaw] of Object.entries(vcols)) {
+        const ov = ovRaw ?? {};
+        if (typeof ov.formula !== "string" || ov.formula.trim() === "") continue;
+        const colType = fields[cd]?.columnType;
+        if (colType !== "F") {
+          err(
+            `${where}.columns.${cd}`,
+            `sets a formula on a column of type '${colType ?? "D"}'. A view formula is only evaluated on a Formula ("F") column \u2014 on any other column that field holds the SQL default, and the override would do nothing.`
+          );
+        }
+      }
+    }
+  }
   const views = readJsonOrDefault(paths.dataViews, {});
   const viewCodes = new Set(Object.keys(views));
   for (const [vcode, v] of Object.entries(views)) {
@@ -35930,6 +36039,30 @@ 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.`
     );
   }
+  const folderNodes = [
+    { path: "(root)", node: folderRoot },
+    ...walkFolders(folderRoot).map((f) => ({ path: f.path, node: f.node }))
+  ];
+  for (const { path: fpath, node } of folderNodes) {
+    const bindings = node.entities ?? {};
+    for (const [entityCd, binding] of Object.entries(bindings)) {
+      const viewName = (binding ?? {})?.viewName;
+      if (typeof viewName !== "string" || viewName.trim() === "") continue;
+      if (viewName.trim().toLowerCase() === "default") continue;
+      if (entityCd.includes(".")) continue;
+      const e = entities[entityCd];
+      if (!e) continue;
+      const declared = Object.keys(
+        e.views ?? {}
+      ).map((v) => v.trim().toLowerCase());
+      if (!declared.includes(viewName.trim().toLowerCase())) {
+        err(
+          `ui/folders.json \u2192 ${fpath} \u2192 entities.${entityCd}`,
+          `viewName '${viewName}' is not declared under 'views' in entities/${entityCd}.json. This fails the install: an unresolved view would show every column of the entity, which is the opposite of what naming one asks for. Declare the view, or drop 'viewName' (or use "default", which means no view).`
+        );
+      }
+    }
+  }
   for (const [rcode, rawReport] of Object.entries(reports)) {
     const report = rawReport ?? {};
     const where = `ui/reports.json \u2192 ${rcode}`;
@@ -36115,7 +36248,7 @@ var triggerAddSchema = {
     "STATIC params only \u2014 the literal values given here. Nothing is injected at runtime; there is no record_id param. The affected record arrives as record context ([field]), its pre-change values as old[field]."
   ),
   async: external_exports.boolean().default(true).describe(
-    "When true (the platform default), the action runs in background \u2014 recommended for slow actions. When false, it runs in the caller's transaction, so a failing action ROLLS BACK the user's original write."
+    "When true (the platform default), the action runs in background \u2014 recommended for slow actions. When false, it runs in the caller's transaction, so a failing action ROLLS BACK the user's original write. That applies to a trigger on ANOTHER module's entity too: a bridge module CAN veto its host's write, the same way a mandatory extension column already refuses one. So async:false is a refusal mechanism \u2014 pick it to enforce an invariant, not merely to react, because a bug in the action blocks the host's workflow just as effectively as a real violation. The rollback is reported to the user as TRIGGER_ACTION_FAIL, naming the blocking module and trigger."
   )
 };
 function triggerAdd(args) {
@@ -36350,6 +36483,15 @@ function matrixExample(relPath, description) {
     read: () => readSkill(`examples/matrix-budget/${relPath}`)
   };
 }
+function columnSecurityExample(relPath, description) {
+  return {
+    uri: `dforge://example/column-security/${relPath}`,
+    name: `Example: column-security/${relPath}`,
+    description,
+    mimeType: relPath.endsWith(".json") ? "application/json" : "text/plain",
+    read: () => readSkill(`examples/column-security/${relPath}`)
+  };
+}
 var resources = [
   schema(
     "manifest",
@@ -36359,7 +36501,7 @@ var resources = [
   schema(
     "entity",
     "Entity JSON schema",
-    "JSON Schema for entity files under entities/*.json (description, dbObject, toString, traits, fields)."
+    "JSON Schema for entity files under entities/*.json (description, dbObject, toString, traits, fields, views)."
   ),
   schema(
     "domains",
@@ -36442,7 +36584,7 @@ var resources = [
   },
   // ── Per-element authoring references (skills/.../references/*.md) ──────
   reference("field-types", "Field types \u2014 fieldTypeCd (UI control) vs dbDatatype (SQL type), and the correct value for each. Load before adding any field."),
-  reference("flags", "Column flags \u2014 only V/I/E/M/H; valid combos (VEM/VE/V/EM/I) and why 'VEMHI' is invalid. Load before setting any flags."),
+  reference("flags", "Column flags \u2014 only V/I/E/M (there is no H); valid combos (VEM/VE/V/EM/I), how M folds into isNullable, and how the same letters override per entity view. Load before setting any flags."),
   reference("column-types", "The FK + Reference two-column pattern (the #1 source of broken modules) and Set columns. Load before any relation."),
   reference("column-domains", "Column domains: a reusable field type (datatype + control + shared option list) referenced via a single `domain` key. Use when the same enum/type repeats across columns. Load before authoring domains.json or a domain-backed column."),
   reference("formulas", "Formula columns (columnType 'F'): baseDatatypeCd, no dbDatatype, flags 'V', and the formula expression grammar."),
@@ -36488,7 +36630,13 @@ var resources = [
   matrixExample("entities/budget_category.json", "Matrix row-axis (dataset) entity."),
   matrixExample("manifest.json", "Matrix example manifest (entities + dataViews + roles + seed)."),
   matrixExample("security/roles.json", "Matrix example roles: S on the axis entity, SIUD on the editable cell entity."),
-  matrixExample("seed-data/01-categories.json", "Matrix example seed: row-axis category records.")
+  matrixExample("seed-data/01-categories.json", "Matrix example seed: row-axis category records."),
+  columnSecurityExample("entities/product.json", `Canonical ENTITY VIEWS (column-level security): one entity, two views \u2014 'storekeeper' (a plain column subset, prices absent entirely) and 'accountant' (with a per-column flags override making a column read-only in that view only, and a per-view formula override on an "F" column). Both list the primary key, which a view must.`),
+  columnSecurityExample("ui/folders.json", "The BINDING half: two folders over one entity, each with a different entities.product.viewName. Without this the views exist and nothing uses them; with a name no view declares, the install fails rather than falling back to the full column set."),
+  columnSecurityExample("security/roles.json", "Roles for the two folders. Note rights are per ENTITY, not per column \u2014 the column dimension is the entity view, not the role."),
+  columnSecurityExample("ui/data_views.json", "The data view lists EVERY column including prices \u2014 correct: presentation is one axis, the folder's entity view decides what a user may see of it. You do not maintain one data view per role."),
+  columnSecurityExample("manifest.json", "Column-security example manifest. Note it declares no dataViews/menus/security pointers \u2014 those files are found by convention, and the manifest schema is additionalProperties:false."),
+  columnSecurityExample("README.md", "Why entity views exist, what each of the two views demonstrates, and the five ways a view fails the install.")
 ];
 function readVendored(rel2) {
   const p = path16.join(RESOURCES_DIR, rel2);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.15",
+	"version": "0.2.17",
 	"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.14",
-		"@dforge-core/metadata": "^0.0.15",
+		"@dforge-core/dforge-cli": "^0.2.15",
+		"@dforge-core/metadata": "^0.0.20",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"zod": "^4.4.3"
 	},

package/resources/docs/conventions.md

@@ -426,7 +426,7 @@ slashes.
 - **The whole file is the root folder.** Top-level fields (`label`, `description`, `color`, `entities`) belong to the root.
 - **Subfolders nest under `children`** (a dictionary keyed by path segment).
 - **Each child key is a single path segment** — lowercase letters, digits, dashes, and underscores only, no slashes. Pattern: `^[a-z0-9][a-z0-9_-]*$`. Slashes are forbidden in keys because deeper trees use `children` recursively, not slashes in keys.
-- **`entities` is a dictionary** mapping entity codes to settings objects. Each entity has `viewName` (string or null), `quickAdd` (boolean), and an optional `rowFilter`.
+- **`entities` is a dictionary** mapping entity codes to settings objects. Each entity has `viewName` (an **entity view** name — see below — or null), `quickAdd` (boolean), and an optional `rowFilter`.
 - **`inheritSecurity`** is allowed only on child folders. The root has no parent to inherit from, so the field is rejected at the root level with a clear error.
 - **Children can have their own children**, recursively, for arbitrary tree depth.
 
@@ -464,6 +464,78 @@ The DB still has a `UNIQUE INDEX` on `(module_id, folder_path)` as
 defense-in-depth, and `FolderTreeFlattener` validates the file format
 before the install pipeline touches the database.
 
+### Entity views — column-level security
+
+An **entity view** is a named subset of an entity's columns, declared on the entity file and bound per folder. Users working in that folder see **only** the columns the view lists — the rest are neither visible nor queryable there. This is the column-level layer of the security model; roles grant rights per *entity*, never per field.
+
+Two halves, both required:
+
+| File | Key | Effect |
+|------|-----|--------|
+| `entities/<entity>.json` | `views.<viewName>.columns` | Declares the view and its column set |
+| `ui/folders.json` | `entities.<code>.viewName` | Binds that view for this entity in this folder |
+
+```jsonc
+"views": {
+	"storekeeper": {
+		"columns": {
+			"product_id": {},
+			"name": {},
+			"quantity": {}
+		}
+	},
+	"accountant": {
+		"columns": {
+			"product_id": {},
+			"name": {},
+			"quantity": { "flags": "V" },
+			"cost_price": {},
+			"sale_price": {}
+		}
+	}
+}
+```
+
+**Per-column overrides** (all optional, each falls back to the entity-level value): `flags`, `orderNum`, `isNullable`, `editMask`, `displayFmt`, `refFilter`, `params`, `formula`. `{}` means "expose this column, override nothing".
+
+**An empty override is a value, not an absence.** The runtime merges view over entity with `COALESCE(view, entity)`, which skips NULL only — so `"flags": ""` means "no flags in this view" (a column neither visible nor editable) and `"params": {}` suppresses the entity-level params rather than inheriting them. Omit the key entirely to inherit.
+
+`formula` lets one view compute a column differently from the entity, and only on a column the entity declares as `columnType: "F"` — elsewhere that field holds the SQL default, so an override there would be inert.
+
+**Rules the installer enforces** (each is silent at runtime, which is why they fail the install instead):
+
+- A column absent from `columns` is **hidden**. That is the mechanism, not an oversight.
+- A view must list the **primary key** — records are addressed by it. Keep it off screen by dropping `V` from its flags instead of omitting it.
+- A column code that doesn't exist, a view with **no** columns, one column listed twice under different casing, or two views whose names differ only by case (a folder binds case-insensitively, so only one could ever be reached).
+- Views belong to the entity's **own** module; an `extends` extension declaring `views` is rejected, since a view enumerates the complete column set.
+- A `viewName` that no view declares, or one naming a column-less view, **fails the install**. It does not fall back: the fallback is the full column set, so a typo would quietly *unrestrict* the folder.
+
+**`"default"` is the one exempt name** and means "no view" (full column set). It is what the ~100 shipped folder entries write, what `FolderExporter` writes back for a NULL `view_name`, and what the runtime auto-creates (column-less) for an entity reached without a folder binding — so rejecting it would fail every install. A module that really declares a view named `default` still gets it bound.
+
+Don't confuse the three things called "view": an **entity view** (`views`, this section) is column security; a **data view** (`ui/data_views.json`, referenced by a menu's `dataViewCode`) is a grid/kanban/calendar; `isView` + `viewSql` on an entity means it is backed by a SQL view. `folders.json`'s `viewName` binds the first.
+
+## Column Domains (`domains.json`)
+
+A **domain** is a reusable, named semantic type: a base datatype, a control, sizing, and a shared option list under one code. Columns reference it instead of restating the definition.
+
+```json
+{
+	"doc_status": {
+		"description": "Document Status",
+		"baseDatatypeCd": "string",
+		"dbDatatype": "varchar",
+		"maxLen": 20,
+		"fieldTypeCd": "dropdown",
+		"params": {
+			"options": [
+				{ "value": "draft", "label": "Draft" },
+				{ "value": "posted", "label": "Posted", "color": "#0a0" }
+			]
+		}
+	}
+}
+```
+
 ### 5. Security Roles (`security/roles.json`)
 
 ```json
@@ -939,6 +1011,7 @@ When creating a module, ensure:
 - [ ] `menus.json` uses nested dictionaries with `children` (not arrays)
 - [ ] `menus.json` leaf items use `dataViewCode` (not `viewCode`)
 - [ ] `folders.json` uses entity dictionary with `{ viewName, quickAdd }` objects
+- [ ] Every `viewName` is `"default"` (= no view) or a view the entity declares under `views`; each declared view lists the primary key and at least one column
 - [ ] `roles.json` uses `"rights"` property (not `"entityRights"`)
 - [ ] Seed data files are numbered for FK dependency order (01-, 02-, etc.)
 - [ ] Seed data includes explicit numeric (int8) PKs for cross-entity references — NOT UUID strings (`cuid` is `int8`)

package/resources/schemas/deps.schema.json

@@ -40,7 +40,7 @@
 				},
 				"columns": {
 					"type": "object",
-					"description": "Provider columns the consumer actually reads, writes, or joins on. Omit entirely for extension-only targets that touch no existing provider column.",
+					"description": "Provider columns the consumer actually reads, writes, or joins on. Omit entirely for extension-only targets that touch no existing provider column. A column your OWN 'extends' file adds to the provider needs no entry either — the platform exempts those and validates them separately — and a VIRTUAL extension field (columnType R/S/F: the lookup beside an FK, a reverse set, a formula) must never be listed at all: it is metadata, never a provider storage column, so no storage class can ever match and the install-time satisfaction check rejects the declaration. Declare the FK you add (e.g. trip_id), never the lookup beside it (trip).",
 					"additionalProperties": { "$ref": "#/definitions/columnContract" }
 				}
 			}