@dforge-core/dforge-mcp 0.2.14 → 0.2.16

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

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

package/skills/dforge-mcp-author/references/column-types.md

@@ -36,8 +36,9 @@ Virtual N:1 lookup. No physical column. Always **paired with a hidden FK column*
 The example below is a **required** relation, so both halves carry `M`. For an optional
 one, drop it from both: FK `"E"`, Reference `"VE"`. `M` resolves to `isNullable: false`
 at install, so it is what makes the FK column `NOT NULL` — and while `M` is inert on the
-virtual Reference half, leaving it there over an optional FK reads as a required field to
-the next author. `dforge_entity_reference_add({ required })` emits both halves in step.
+virtual Reference half (at the entity level; a per-view override behaves differently, see
+`flags.md`), leaving it there over an optional FK reads as a required field to the next
+author. `dforge_entity_reference_add({ required })` emits both halves in step.
 
 ```json
 // Hidden FK column — physical, hidden. "E" instead of "EM" if the relation is optional.

package/skills/dforge-mcp-author/references/data-views.md

@@ -4,6 +4,8 @@ Data views define how users see and interact with entity data. One entity can ha
 
 Lives in: `ui/data_views.json`
 
+> **Not to be confused with entity views.** An *entity view* (`views` on an entity file) is column-level **security** — which columns a folder may see at all — and is what `folders.json`'s `viewName` binds. A *data view* is a presentation of an entity, referenced by a menu's `dataViewCode`. A third thing, `isView` + `viewSql` on an entity, means the entity is backed by a SQL view. See `security.md` → Column-level security.
+
 ## Structure
 
 ```json

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

@@ -2,19 +2,21 @@
 
 Column flags are single-letter codes concatenated into a string. Order doesn't matter — `"VEM"` and `"EMV"` are equivalent.
 
-Valid flags regex: `^[VIEMH]*$`
+Valid flags regex: `^[VIEM]*$`
 
 ## Flag letters
 
 | Letter | Name | Meaning |
 |---|---|---|
 | `V` | Visible | Column appears in grid / form / card views. Omit to hide from standard UI. |
-| `I` | Internal | Auto-managed by the platform. Used on PK columns, audit timestamps, system fields. Not shown in UI, not directly editable by users. |
+| `I` | Identity | Auto-managed by the platform. Used on PK columns, audit timestamps, system fields. Not shown in UI, not directly editable by users, excluded from required validation. |
 | `E` | Editable | User can modify the value in the UI. Omit for read-only. |
 | `M` | Mandatory | Required. Resolved into `isNullable: false` at install — see below. |
-| `H` | Hidden | Permanently hidden — never shown, not even in admin metadata views. Stronger than omitting `V`. |
 
-**Only these 5 letters are valid.** The platform rejects any other characters.
+**Only these 4 letters are valid.** The platform rejects any other characters.
+> **There is no `H` flag.** Earlier drafts listed one, described as "stronger than omitting `V`", and nothing ever read it — a column with `flags: "H"` is hidden because the string contains no `V`, not because it contains `H`. To hide a column, omit `V`. To hide it from specific folders (and make it unqueryable there), use an entity view. To render it as a hidden input, use `fieldTypeCd: "hidden"`.
+
+> **The same letters override per entity view.** `views.<v>.columns.<cd>.flags` re-flags a column for the folders bound to that view, while the entity keeps its own flags everywhere else. Same `^[VIEM]*$` vocabulary — see "Per-view overrides" below. See `security.md` → Column-level security.
 
 ## `M` is the platform's one notion of "required"
 
@@ -31,7 +33,8 @@ Four consequences worth knowing before you type a flag:
   entity and every offending field. It's a contradiction only you can resolve: drop
   `M` if the column is optional, or drop `isNullable` if it is required.
 - **`M` is inert on virtual (`R`/`S`/`F`) and identity columns** — nullability is
-  meaningless where there is no physical column. It won't fail, but `VEM` on a
+  meaningless where there is no physical column. (At the *entity* level; a per-view
+  override behaves differently — see "Per-view overrides".) It won't fail, but `VEM` on a
   Reference over an *optional* FK reads as a required field to the next author, which
   is exactly how these get out of step. Match the Reference to its FK.
 - **Adding `M` to a shipped field aborts the upgrade** on any tenant whose existing
@@ -41,6 +44,33 @@ Four consequences worth knowing before you type a flag:
 
 Omitting both `M` and `isNullable` leaves the column nullable — that is the default.
 
+## Per-view overrides
+
+`views.<v>.columns.<cd>.flags` re-flags one column for the folders bound to that view. The letters are the same four, and `M` means the same thing — the installer folds it into **that override's** `isNullable`.
+
+Because a view writes no DDL, the requiredness `M` produces there is runtime-only. That is how you express **"nullable in the database, mandatory in this view"**, which no entity-level flag can say:
+
+```json
+"views": {
+  "compliance": {
+    "columns": {
+      "party_id": {},
+      "party_name": { "flags": "V" },
+      "vat_no":     { "flags": "VEM" },
+      "salary":     { "flags": "" }
+    }
+  }
+}
+```
+
+Three rules to keep straight:
+
+- **The letters replace, they don't merge.** The cascade is `COALESCE(view, entity)`. A non-empty string wins outright, so `{ "flags": "V" }` is read-only there however the entity flagged the column.
+- **`""` is a real value, omission is not.** An empty string means "no flags here" — neither visible nor editable. To inherit, leave the key out; `"flags": null` fails schema validation, since the property is typed `string`. (To inherit *everything*, set the whole column override to `{}` or `null`.)
+- **The `M` fold is one-directional.** Dropping `M` from a view's flags does NOT make the column optional — `isNullable` still `COALESCE`s to the entity value. Write `"isNullable": true` to loosen it, and only where the database actually allows null, or the save trades a clean validation error for a raw constraint violation.
+
+Unlike the entity level, `M` here is *not* inert on virtual or identity columns: the fold only reaches the runtime required check, so a view can mark a Reference required. (Identity columns stay excluded — they are never asked of the user.)
+
 ## Common column flag combinations
 
 | Flags | Meaning | Use case |
@@ -50,7 +80,7 @@ Omitting both `M` and `isNullable` leaves the column nullable — that is the de
 | `"V"` | Visible, read-only | Display-only, like formula columns or computed values |
 | `"E"` | Editable, **not visible** | Hidden FK column of an *optional* relation |
 | `"EM"` | Editable, Mandatory, **not visible** | Hidden FK column of a *required* relation |
-| `"I"` | Internal | Trait-provided columns (PK, audit timestamps). Platform-managed. |
+| `"I"` | Identity | Trait-provided columns (PK, audit timestamps). Platform-managed. |
 | `""` (empty) | No flags | Rare — column exists but is invisible and not editable |
 
 ## Rules
@@ -60,9 +90,9 @@ Omitting both `M` and `isNullable` leaves the column nullable — that is the de
 2. **Visible Reference columns**: `"VE"`, or `"VEM"` when the FK is required — **keep the
    two halves in step**. `dforge_entity_reference_add({ required })` sets both for you.
 3. **Formula columns**: usually `"V"` (visible, read-only). The user never edits them.
-4. **Trait columns** (PK, audit): use `"I"` (internal). These are set automatically by `traits: ["identity", "audit"]`.
+4. **Trait columns** (PK, audit): use `"I"` (identity). These are set automatically by `traits: ["identity", "audit"]`.
 5. **Don't use `I` on your own columns** — it's reserved for trait-provided and platform-managed columns.
-6. **Don't mix `I` with `V` or `E`** — internal columns are not user-facing.
+6. **Don't mix `I` with `V` or `E`** — identity columns are not user-facing.
 
 ## Entity rights flags (different namespace — roles only)
 
@@ -79,7 +109,7 @@ These letters appear in role `rights` declarations, **NOT** on column flags. Don
 
 So `"SIUD"` on a role grants full CRUD; `"SI"` grants read + create only.
 
-**Note**: the `I` in column flags (Internal) and the `I` in role rights (Insert) are different concepts using the same letter. Context makes them unambiguous — column flags go on entity fields, role rights go on `security/roles.json`.
+**Note**: the `I` in column flags (Identity) and the `I` in role rights (Insert) are different concepts using the same letter. Context makes them unambiguous — column flags go on entity fields, role rights go on `security/roles.json`.
 
 ## How uniqueness, PKs, and search work
 
@@ -101,4 +131,6 @@ These are **NOT** flag letters. They're separate properties on the column defini
 - Putting `M` on a Reference whose hidden FK is optional — inert, but it misreports the field as required.
 - Using `"VEM"` on trait-provided columns (PK, audit) — **don't**. Traits set their own flags (`"I"`).
 - Using `"I"` on business columns — **don't**. `I` means "platform-managed"; regular business columns use `V`/`E`/`M`.
+- Expecting a per-view `{ "flags": "VE" }` to make a column **optional** because it drops `M` — it doesn't. `isNullable` still inherits; write `"isNullable": true`.
+- Writing `"flags": null` in a view override to inherit — fails validation. Omit the key.
 - Using long names like `"Visible,Editable"` — **wrong**. Single letters concatenated: `"VE"`.

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

@@ -3,7 +3,19 @@
 Formulas are used in:
 
 - **Formula columns** (`columnType: "F"`) — computed values
-- **Action `canExecute:` blocks** — availability checks
+- **Per-view formula overrides** (`views.<v>.columns.<cd>.formula`) — one entity view
+  computing a column differently from the entity. Allowed **only** on a column the
+  entity declares as `columnType: "F"`; on any other column the install FAILS, because
+  there that field holds the SQL default and a view cannot change a physical column's
+  `DEFAULT`. (There is no per-view default value for a normal column.) Same rules as an
+  `F` column otherwise: it must parse, call only implemented functions, and not
+  aggregate over a 1:N set. See `security.md` → Column-level security.
+- **Action `canExecute:` blocks** — availability checks. Evaluated on both sides
+  and **enforced** by `action.execute`, but only over a narrow subset: comparisons
+  between fields and literals combined with `AND` / `OR` / `NOT`. Functions,
+  arithmetic, ref navigation, `$[setting]` reads and a bare boolean field all fail
+  open server-side, and some of them throw client-side. See the `canExecute:`
+  section in [action-dsl.md](action-dsl.md).
 - **Default values** — a setting's `formula` (e.g. `"formula": "TODAY()"`) or a formula (`F`) column. Note: entity *data* columns have **no** `default`/`defaultValue` key — model a default with an `F` column or set it in action/trigger logic.
 - **Filter expressions** (partially)
 - **Validation expressions** (partially)

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

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

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

@@ -213,7 +213,7 @@ Lives in: `ui/folders.json`
 
 | Property | Type | Description |
 |---|---|---|
-| `viewName` | string | Default data view (usually `"default"`) |
+| `viewName` | string | Entity view to bind — a key under the entity's `views` (see [Column-level security](#column-level-security-entity-views)), **not** a `ui/data_views.json` code. `"default"` means "no view" (full column set). |
 | `quickAdd` | boolean | Show "+" quick-add button (`true` for main entities, `false` for detail/line items) |
 | `rowFilter` | object | Row-level filter scoping which records are visible in this folder |
 
@@ -226,6 +226,82 @@ Row filters use a compact filter object with:
 
 This is how **row-level security** works in the module package — subfolders with `rowFilter` restrict which rows are visible. Users assigned to "Central Warehouse" only see stock where `warehouse_id = 2001`.
 
+## Column-level security (entity views)
+
+> Worked example: `dforge://example/column-security/` — one entity, two folders, two
+> column sets. Its README walks the overrides and the ways a view fails the install.
+
+Layer 2 of the model. A **entity view** is a named subset of an entity's columns, declared on the entity itself; a folder binds one per entity. Users working in that folder see **only** the columns the view lists — the rest are neither visible nor queryable there.
+
+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 |
+
+```json
+{
+    "fields": { "product_id": {}, "name": {}, "price": {}, "cost": {}, "quantity": {} },
+    "views": {
+        "accountant": {
+            "columns": {
+                "product_id": {},
+                "name": { "flags": "V" },
+                "price": { "flags": "VE" },
+                "cost": { "flags": "V" }
+            }
+        },
+        "storekeeper": {
+            "columns": {
+                "product_id": {},
+                "name": { "flags": "V" },
+                "quantity": { "flags": "VE" }
+            }
+        }
+    }
+}
+```
+
+```json
+"entities": { "product": { "viewName": "accountant", "quickAdd": true } }
+```
+
+The storekeeper folder cannot see `price` or `cost` at all — not on screen, not through a filter, not in an export.
+
+**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`, 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 — `"flags": null` fails schema validation. See `flags.md` for the flag letters.
+
+> **`M` works in a view override too**, folding into that override's `isNullable`. Since a view writes no DDL, the requiredness is runtime-only — which is how a column nullable in the database is made mandatory inside one view: `{ "flags": "VEM" }`. The fold is one-directional: dropping `M` does not loosen the column, because `isNullable` still inherits. See `flags.md` → Per-view overrides.
+
+`formula` lets one view compute a column differently from the entity — same DSL as a field's `formula`, and **only on a column the entity declares as `columnType: "F"`**; elsewhere the install fails, because there that field holds the SQL default and a view cannot change a physical column's `DEFAULT`. There is no per-view default value for a normal column. See `formulas.md`.
+
+### Rules the installer enforces
+
+Each of these is an install-time error, and each is silent at runtime if it slips through — which is why `dforge_module_validate` checks them offline:
+
+- A column absent from `columns` is **hidden**. That is the mechanism, not an oversight.
+- A view must list the entity's **primary key** — records are addressed by it. To keep it off screen, drop `V` from its flags instead of omitting it.
+- A column code that doesn't exist on the entity, a view with **no columns**, the same column listed twice under different casing, or two views on one entity whose names differ only by case (a folder binds case-insensitively, so only one could ever be reached).
+- Views must be declared on the entity's **own** module. An `extends` extension declaring `views` is rejected — a view enumerates the complete column set, which an extension does not own.
+- A `viewName` that no view declares, or one naming a view with no columns, **fails the install**. It does not fall back: the fallback is the entity's full column set, so a typo would quietly *unrestrict* the folder.
+- Columns removed from a view are reaped on upgrade — that is the security change the author asked for. Whole views are not: `entity_view` also holds tenant views from the card-layout editor, and the installer cannot tell them apart.
+
+### `"default"` is the one exempt name
+
+`"viewName": "default"` means **no view** (full column set) and declares nothing. It is what every shipped module writes, and what the runtime auto-creates for an entity reached without a folder binding — so it is exempt from the checks above. A module that really declares a view named `default` still gets it bound.
+
+### Don't confuse the three "views"
+
+| Term | Where | What it is |
+|---|---|---|
+| **Entity view** | `entities/*.json` → `views` | Column-level security (this section) |
+| **Data view** | `ui/data_views.json` | A grid / kanban / calendar over an entity (`data-views.md`) |
+| **SQL view** | `entities/*.json` → `isView` + `viewSql` | An entity backed by a SQL view instead of a table |
+
+`viewName` in `folders.json` binds the first. Menus' `dataViewCode` references the second.
+
 ### When to use subfolders
 
 - **Multi-location modules** (warehouses, offices, branches) — one subfolder per location, filtered by location FK

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

@@ -105,6 +105,8 @@ For each entity:
 ## Security
 
 - [ ] `security/roles.json` exists (at least one role)
+- [ ] Every entity view (`views.<v>.columns` on an entity) lists the entity's **primary key**, names only real columns, and has at least one column — each of these fails the install
+- [ ] Every `viewName` in `ui/folders.json` is either `"default"` (= no view) or a view that entity actually declares — an unresolved name fails the install rather than falling back
 - [ ] Every role has `description` and `rights` (both required; no `label` field in `roles.json` — the `roles.schema.json` sets `additionalProperties: false`, so any extra field including `label` is rejected here). `description` is the English display-name fallback; **localized role labels live in the translation files** (`roles.<code>.label`) and are completeness-enforced — see Translations below.
 - [ ] The field name is `rights`, NOT `entityRights`
 - [ ] Rights strings use only valid letters: `SIUDC` for entities, `E` for actions/reports/folders
@@ -119,6 +121,16 @@ For each action:
 - [ ] DSL file exists at `logic/actions/<script>.dsl`, where `<script>` is the bare filename in the action's `script` field (no path, no `.dsl` extension)
 - [ ] DSL file has `params:`, `canExecute:`, and `execute:` blocks
 - [ ] `canExecute:` is a valid formula expression
+- [ ] If `canExecute:` is meant to **gate** and not just grey out a button, its
+      guard is expressed in the server-enforced subset — **comparisons** between
+      fields and literals, combined with `AND` / `OR` / `NOT`. Function calls
+      (`TODAY()`, `COUNT()`, `CURRENT_USER_ID()`), arithmetic, ref navigation and
+      `$[setting]` reads are fail-open server-side and are advisory only
+- [ ] No **bare boolean field** as a whole condition — `[is_active]` and
+      `NOT [is_blocked]` are not enforced (a field is only an operand). Write
+      `[is_active] = true` / `NOT ([is_blocked] = true)`
+- [ ] Anything that MUST hold is also checked in `execute:` with `error()` — a
+      `canExecute` alone is never the authoritative guard
 - [ ] `execute:` uses only documented built-in functions
 - [ ] Referenced entities exist
 - [ ] Referenced parameters are declared in `params:`

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

@@ -31,6 +31,7 @@ flags, or column patterns.
 | Add a grid / list view | `dforge://reference/data-views`, `dforge://example/ui/data_views.json` | — |
 | Add a matrix (pivot) view | `dforge://reference/data-views` (§Matrix), `dforge://example/matrix-budget/ui/data_views.json`, `dforge://example/matrix-budget/entities/budget_line.json` | — |
 | Add kanban / calendar / tree-grid / master-detail | `dforge://reference/data-views` | `dforge://schema/data-views` |
+| Hide columns from a user type (column-level security) | `dforge://reference/security` (§Column-level security), `dforge://example/column-security/entities/product.json`, `dforge://example/column-security/ui/folders.json` | — |
 | Add a menu | `dforge://reference/menus`, `dforge://example/ui/menus.json` | — |
 | Add an action | `dforge://reference/action-dsl`, `dforge://example/logic/actions/mark_done.dsl`, `dforge://example/ui/actions.json` | `dforge://docs/dsl` |
 | Add a trigger | — | `dforge://schema/triggers`; condition syntax in `dforge://docs/dsl` |
@@ -204,8 +205,11 @@ per entity, so you'll often `view_modify` rather than `view_add`.
 
 View codes are semantic — the entity name (`feedback_item`), a plural
 (`invoices`), or descriptive (`invoices_kanban`). **Never use the literal code
-`default`**; `ui/folders.json`'s `viewName: "default"` is a fallback alias the
-platform resolves to the entity's first declared view.
+`default`.** Note that `ui/folders.json`'s `viewName` is a different axis
+entirely: it binds an *entity view* (column-level security, declared under
+`views` on the entity file), not a data view code. `"default"` there means "no
+entity view — show the full column set", and any other name the entity does not
+declare **fails the install**. See `references/security.md`.
 
 Then wire menus with `dforge_menu_add` — a section node per group, leaves
 pointing at the views.
@@ -273,6 +277,13 @@ stated trigger; every report's params sit on a dataset.
 4. **Show the rights matrix as a table** (rows = entities/actions/reports,
    columns = roles, cells = rights strings), each cell explained by the verb it
    maps to. Get sign-off.
+5. **Column-level security only when the intake asks for it.** Roles grant rights
+   per entity, not per field. When a user type must not see specific *columns*
+   (salaries, cost prices, personal data), that is an **entity view**: declare
+   `views.<name>.columns` on the entity and bind it with `viewName` on the folder
+   that user type works in. Don't reach for it otherwise — a view is the complete
+   column list, so it is one more list to keep in step with the fields. Rules and
+   the worked example: `references/security.md` → Column-level security.
 5. `dforge_role_add` for new roles; `dforge_role_right_set` per grant when
    amending an existing one.