@dforge-core/dforge-mcp 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -4,6 +4,231 @@ 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.3
+
+Catches up with the platform's current-user work: `currentUserId()` exists now,
+and the three ways an author can get this wrong each get their own diagnostic
+instead of a generic "unknown function".
+
+### Fixed — `dforge_action_check` flagged real built-ins as unknown
+
+`DSL_BUILTINS` is a hand-maintained mirror of `DslBuiltins.FunctionNames` in
+dForge-core, and it had drifted: `addMinutes`, `applyProfile` and
+`getFileBase64` were missing, so a module using them was told its correct code
+was wrong. Nothing compared the two lists, which is why it went unnoticed.
+`test/dsl-builtins-drift.test.ts` now asserts they match in both directions,
+parsing the authoritative list out of a sibling dForge-core checkout.
+
+### Added — `userId()` and `CURRENT_USER_ID()` diagnostics
+
+- **`userId()`** is now an `error` (`user-id-called-as-function`) carrying the
+  platform's own sentence: *'userId' is a value, not a function — write 'userId'
+  without parentheses, or 'currentUserId()'*. It used to draw only a generic
+  `unknown-builtin` warning that called `userId` "not a DSL host function",
+  which is misleading — it is a host value, just not callable. The platform
+  rejects this at compile time now, so the checker matches its severity.
+- **`CURRENT_USER_ID()`** in `execute:` joins `TODAY()`/`NOW()` as formula-only.
+  The message is per-function rather than date-specific, so it points at
+  `currentUserId()` here and `now()` there.
+- **`currentUserId()`** and bare **`userId`** both check clean.
+
+### Changed — reference docs
+
+`dsl-reference.md` and the skill's `action-dsl.md` gain the full built-in list,
+the formula-vs-`execute:` split for `CURRENT_USER_ID()`, and the 64-bit id
+contract: ids are BigInt inside `execute:` and stay exact, arithmetic mixing
+BigInt and Number throws, and a large id written as a bare numeric literal
+rounds before the comparison runs. The skill reference also drops
+`IF(condition, trueVal, falseVal)`, which it listed as an `execute:` ternary
+helper — it is formula-only and the compiler rejects it.
+
+## 0.2.2
+
+Mirrors the platform change that gives the `M` column flag its meaning — in the
+docs, in the schemas, and in the tools that emit flags — and catches up the
+formula and `entityLink()` references with the platform work since 0.2.1.
+
+### Fixed — the relation tools emitted `NOT NULL` for every optional relation
+
+The `M` change turned an inert flag into a physical constraint, which made three
+places that hard-coded it actively wrong. All three now take `M` from whether the
+relation is actually required, and put it on **both** halves in step:
+
+- **`dforge_entity_reference_add`** emitted the hidden FK as `flags: "EM"`
+  unconditionally, whatever `required` said. Post-change that made every optional
+  relation's FK column `NOT NULL` while its own Reference half said `"VE"` — a pair
+  that contradicts itself. It now emits FK `"EM"` + Reference `"VEM"` when
+  `required`, and FK `"E"` + Reference `"VE"` when not. Reusing a half-built FK
+  normalizes to the same shape, and drops a lingering `"isNullable": true` when the
+  relation is required rather than emitting a pair the platform rejects at pack.
+- **`dforge_dbml_import` / `dforge_module_import`** did the same for every imported
+  FK. They now read the source column's nullability — a DBML `[not null]` on the FK
+  is carried onto the reference (the FK column itself is dropped from `columns`, so
+  it was being lost) and `required` is accepted explicitly on a table-spec reference.
+- **`isHiddenFk()`** required `M` to recognize the hidden half of a pair, so an
+  optional FK (`"E"`) became invisible to every rule keyed off it. `M` is not part
+  of the shape — it marks the relation required.
+- **Set columns** are emitted `"VE"`, not `"VEM"`: `M` is inert on a virtual column,
+  but it reads as "this grid must be non-empty", which nothing enforces.
+
+### Added — the validator catches the `M` / `isNullable` contradiction
+
+`dforge_module_validate` (and the authoring-time field schema) now error on a field
+declaring `M` together with `"isNullable": true`, naming the field. The platform
+rejects this at pack time; catching it here says which column while you can still
+see it. On a virtual column the message says so instead of offering both fixes.
+
+### Changed — the `M` column flag now means "required" (platform mirror)
+
+- **`M` resolves to `isNullable: false` at install.** The flag was documented as
+  "mandatory" but was inert — nothing on the server or the client read it, so a
+  column declared `"flags": "VEM"` rendered without a red asterisk and saved
+  empty. It is now folded into `isNullable`, the platform's single notion of
+  required, and everything downstream keys off that: `NOT NULL` in generated
+  DDL, the `data.insert` required-column check, the client asterisk.
+- **Declaring `M` together with `"isNullable": true` is now a hard error** at
+  pack time, naming the entity and every offending field — it is a contradiction
+  only the author can resolve. **This repo shipped exactly that combination** in
+  the extension example in `resources/docs/conventions.md` (`customer_id`, `"flags":
+  "EM"` with `"isNullable": true`), so a module authored from that pattern could
+  not pack. Corrected to `"flags": "E"`, matching the real `crm-fin` module.
+- **The FK+Reference rule no longer prescribes `M` by default.** A hidden FK is
+  `flags: "E"`, or `"EM"` when the relationship is genuinely required; omitting
+  both leaves the column nullable, which is the default — so the examples no
+  longer spell out `"isNullable": true` either. Keep the visible Reference in
+  step (`VE` / `VEM`): `M` is inert on a virtual column, so `VEM` over an
+  optional FK changes nothing but reads as a required field to the next author,
+  which is precisely how the broken example above went unnoticed.
+- **An upgrade now reconciles nullability in both directions.** Previously
+  neither direction reached an existing table: `ADD COLUMN IF NOT EXISTS` no-ops
+  on a column that is already there, and the only nullability statement emitted
+  was `DROP NOT NULL`, and that only for an *explicit* `isNullable: true`. So
+  adding `M` to a shipped field silently did nothing on upgraded tenants (it
+  worked on a fresh install, which goes through `CREATE TABLE`), and merely
+  deleting `M` left the constraint standing, failing later inserts with a raw
+  Postgres 23502.
+- **Authoring consequence:** adding `M` to a field that existing tenant rows
+  leave empty now **aborts the upgrade**, rolled back, naming the column and its
+  NULL row count — rather than committing a tenant whose API enforces a rule its
+  data already breaks. Give the column a `params.serverDefault` if the install
+  should backfill it. Removing `M` is always safe.
+- **`params.serverDefault` now works on a required column.** The platform's
+  required-for-insert check excluded `formula` and `numberSequence` but not
+  `serverDefault`, so an insert omitting such a column was rejected as missing
+  even though the INSERT would have supplied the value. An `on: "update"`
+  default stays required — it does not fire on insert.
+- **Also corrected in `conventions.md`:** the hidden-FK examples carried
+  `"fieldTypeCd": "hidden"`, which makes install warn that a `cuid` column
+  (group *number*) is bound to a *text* field type and can misbind filter/DML
+  values at runtime (`operator does not exist: bigint = text`). A hidden FK is
+  `dbDatatype: "cuid"` + `flags` — no `fieldTypeCd`.
+
+### Changed — formula navigation at SQL time is no longer single-hop
+
+`formulas.md` and `column-types.md` still described the report/query translator as
+single-hop-only, and told authors to keep report-bound formulas to one hop. That
+stopped being true upstream:
+
+- **Multi-hop `[a].[b].[c]` translates**, one `LEFT JOIN` per hop, each with the
+  same soft-deny rights check as a reference display column. A nav path may land on
+  a *formula* column of the referenced entity, whose own hops are joined off that
+  alias — which is what makes a two-level formula reachable through a reference.
+- **Hops are counted from the query's root** and capped at `MaxNavigationDepth`, so
+  the hops spent reaching a formula reduce the budget left for its own navigation.
+- **What is still unsupported changed shape:** `$[Setting]` references, paths past
+  the cap, **extension-table columns** (they live in a separate 1:1 table needing
+  its own JOIN), and misauthored paths. All come back NULL with a response warning.
+- **Warning wording follows the clause** — a SELECT slot goes empty, an ORDER BY
+  term is dropped so rows come back in a different order, a WHERE condition is
+  dropped so *more* rows come back than were asked for. Documented, because the
+  third one is the only failure that silently widens a result set.
+- **Comparison is null-safe and two-valued** in every context: `null = null` is
+  true, `[x] != null` is true for any non-null `x`, and SQL-time `=`/`!=` translate
+  to `IS NOT DISTINCT FROM` / `IS DISTINCT FROM` so a card and a report agree.
+- Corrected in both files: nav resolution walks N:1 references only, **never a 1:N
+  set**, however many hops it is given — the reason `SUM([set].[field])` in an `F`
+  column renders empty. That was previously attributed to the single-hop limit.
+
+### Changed — `entityLink()` stores the entity id and captions from `toString`
+
+`entity_cd` is only unique per module, so storing the bare code meant a link built
+as `entityLink('fin.invoice', …)` re-resolved at click time against the *reader's*
+folder module and could land on another module's `invoice`. It now stores the
+resolved entity id. The display caption comes from the entity's `toString`
+evaluated against the record (an explicit `description` still wins) — previously
+the entity's own description, which names the table, not the record. Documented in
+`action-dsl.md`, `field-types.md` and the `dforge://reference/dsl` resource, with
+the reminder to pass a qualified code.
+
+### Changed — dependencies
+
+- **`@dforge-core/metadata` `^0.0.10` → `^0.0.12`**, and the vendored schemas
+  re-generated from it. `entity.schema.json` and `triggers.schema.json` were stale:
+  they still described `M` as plain "Mandatory" with no mention of `isNullable`, and
+  omitted that DSL `insert()`/`update()`/`delete()`/`query()` writes to *other*
+  records raise no trigger events.
+- **`@dforge-core/dforge-cli` `^0.2.7` → `^0.2.10`.**
+
+## 0.2.1
+
+Adds the column-domain schema that `dforge_module_inspect` already reported on,
+and corrects three areas where the schemas and reference docs described
+behavior the platform doesn't have.
+
+### Added — column domains
+
+- **`resources/schemas/domains.schema.json`** — `domains.json` had no schema, so
+  the one file that defines reusable semantic types was the only module file
+  authored blind. A domain bundles a base datatype, a control, sizing and a
+  shared option list under one code. Structural fields (`dbDatatype`,
+  `baseDatatypeCd`, `fieldTypeCd`, `maxLen`, `precision`) are materialized onto
+  each consuming column at install; `params` — most importantly `options` —
+  stays on the domain and resolves at metadata-load time, which is what lets a
+  shared list be authored and translated exactly once.
+- **`entity.schema.json` gains `domain`** plus a *Domain-backed column* branch in
+  the column `oneOf`. Referencing a domain and restating what it owns is
+  rejected at install, so the schema now refuses the same combination rather
+  than letting it through to a failed install.
+
+### Fixed — trigger semantics were documented wrong
+
+`triggers.schema.json` and `dforge_trigger_add` both described an invocation
+contract the runtime doesn't implement, and agents wrote actions against it:
+
+- **There is no injected `record_id` param.** The trigger binds the affected
+  record to the action as *record context* — the action reads it with `[field]`
+  and its PK with `[pk_column]`, exactly like a UI-invoked action, with
+  pre-change values as `old[field]` on update/delete/status_change. `params` is
+  static-only: the literal values written in the trigger, nothing else.
+- **The action's `entityCode` must equal the trigger's `entity`**, and its
+  `executionMode` must not be `batch` — both enforced at pack time. The old
+  description said the opposite, warning the action must *not* rely on the
+  triggering record.
+- **`condition` rejects reference navigation.** The event-time evaluator reads
+  only columns of the changed row, so `[ref].[target]` resolves to null and the
+  trigger misfires. Navigate inside the action, or denormalise onto the watched
+  entity.
+- **`async` defaults to `true`**, matching the platform. The tool defaulted it to
+  `false`, so every trigger added without an explicit `async` ran synchronously
+  inside the user's transaction — where a failing action rolls back their write.
+
+### Fixed — actions are not reliably atomic
+
+- **`isTransacted` does not open a transaction.** It only decides whether the
+  first failing record aborts the run or the loop continues. Whether writes made
+  before a failure survive depends on the execution path: `auditHistory` on the
+  entity, `single` vs `batch`, sync vs background. `action-dsl.md` now tabulates
+  all six combinations, and `dsl-reference.md` no longer claims `error()` rolls
+  back the whole transaction. This is a platform defect rather than a contract —
+  actions are intended to be atomic — so both documents say to validate before
+  writing anything, and not to design around either outcome.
+- **`query()` runs on a pooled, shared connection**, which nothing checks
+  statically and neither document mentioned: `SET LOCAL` not `SET`,
+  `pg_advisory_xact_lock()` not `pg_advisory_lock()`, `ON COMMIT DROP` on temp
+  tables.
+- Documented `old[fieldName]`, and the single-hop limit on `[ref].[target]` —
+  `[a].[b].[c]` is a compile error, not a slow path.
+
 ## 0.2.0
 
 Tools go from 27 → 34; the single wizard skill splits into a router plus three

package/dist/server.js

@@ -31299,7 +31299,7 @@ var traits = [
     cd: "sorting",
     description: "Display order",
     fields: {
-      order_num: { dbDatatype: "int4", fieldTypeCd: "number", flags: "VEM", orderNum: 9920, description: "Order" }
+      order_num: { dbDatatype: "int4", fieldTypeCd: "number", flags: "VE", orderNum: 9920, description: "Order" }
     }
   },
   { cd: "postable", description: "Document posting support (marker trait \u2014 actual state managed by A/L columns)", fields: {} },
@@ -31309,11 +31309,11 @@ var traits = [
     cd: "period",
     description: "Period entity with key format, closed flag, date range",
     fields: {
-      period_key: { dbDatatype: "varchar", fieldTypeCd: "text", flags: "VEM", isPk: true, isNullable: false, maxLen: 20, orderNum: 1, description: "Period Key" },
-      description: { dbDatatype: "varchar", fieldTypeCd: "text", flags: "VEM", maxLen: 100, orderNum: 30, description: "Description" },
-      closed: { dbDatatype: "bool", fieldTypeCd: "checkbox", flags: "VEM", isNullable: false, formula: "false", orderNum: 40, description: "Closed" },
-      start_date: { dbDatatype: "date", fieldTypeCd: "date", flags: "VEM", orderNum: 50, description: "Start Date" },
-      end_date: { dbDatatype: "date", fieldTypeCd: "date", flags: "VEM", orderNum: 60, description: "End Date" }
+      period_key: { dbDatatype: "varchar", fieldTypeCd: "text", flags: "VE", isPk: true, isNullable: false, maxLen: 20, orderNum: 1, description: "Period Key" },
+      description: { dbDatatype: "varchar", fieldTypeCd: "text", flags: "VE", maxLen: 100, orderNum: 30, description: "Description" },
+      closed: { dbDatatype: "bool", fieldTypeCd: "checkbox", flags: "VE", isNullable: false, formula: "false", orderNum: 40, description: "Closed" },
+      start_date: { dbDatatype: "date", fieldTypeCd: "date", flags: "VE", orderNum: 50, description: "Start Date" },
+      end_date: { dbDatatype: "date", fieldTypeCd: "date", flags: "VE", orderNum: 60, description: "End Date" }
     }
   }
 ];
@@ -32652,7 +32652,10 @@ var tableSpec = external_exports.object({
     external_exports.object({
       column: codeRe.describe("FK column on THIS table (a hidden cuid column is generated for it)."),
       toTable: codeRe.describe("Target entity code."),
-      toColumn: codeRe.optional().describe("Target PK column; defaults to {toTable}_id.")
+      toColumn: codeRe.optional().describe("Target PK column; defaults to {toTable}_id."),
+      required: external_exports.boolean().optional().describe(
+        "Whether the relation is required \u2014 puts 'M' on both halves (FK 'EM', Reference 'VEM'), which is what makes the FK column NOT NULL. Default: nullable."
+      )
     })
   ).optional()
 });
@@ -32764,13 +32767,19 @@ function buildImportedEntity(table) {
   const references = {};
   for (const ref of table.references ?? []) {
     const otherKey = ref.toColumn ?? `${ref.toTable}_id`;
-    fields[ref.column] = { dbDatatype: "cuid", flags: "EM", orderNum: order, description: titleCase(ref.column) };
+    const required2 = ref.required === true || table.columns.find((c) => c.name === ref.column)?.required === true;
+    fields[ref.column] = {
+      dbDatatype: "cuid",
+      flags: required2 ? "EM" : "E",
+      orderNum: order,
+      description: titleCase(ref.column)
+    };
     order += 10;
     const refName = ref.column.endsWith("_id") ? ref.column.slice(0, -3) : `${ref.column}_ref`;
     fields[refName] = {
       columnType: "R",
       fieldTypeCd: "lookup",
-      flags: "VEM",
+      flags: required2 ? "VEM" : "VE",
       orderNum: order,
       description: titleCase(refName),
       link: { entity: ref.toTable, thisKey: ref.column, otherKey }
@@ -32864,7 +32873,13 @@ function parseDbml(dbml) {
     const references = t.refs.map((r) => {
       const targetPk = byName.get(r.toTable)?.pk;
       const toColumn = targetPk && r.toColumn === targetPk ? void 0 : r.toColumn;
-      return { column: r.column, toTable: r.toTable, ...toColumn ? { toColumn } : {} };
+      const required2 = t.columns.find((c) => c.name === r.column)?.required === true;
+      return {
+        column: r.column,
+        toTable: r.toTable,
+        ...toColumn ? { toColumn } : {},
+        ...required2 ? { required: true } : {}
+      };
     });
     const columns = t.columns.filter((c) => !refColNames.has(c.name));
     const spec = { name: t.name, columns: columns.length ? columns : [{ name: "name", sqlType: "varchar" }] };
@@ -33094,7 +33109,13 @@ function checkFieldSpec(where, field) {
   }
   if (typeof v.flags === "string" && v.flags.length > 0 && !/^[VIEMH]+$/.test(v.flags)) {
     err(
-      `flags '${v.flags}' contains invalid letters \u2014 use only V/I/E/M/H (e.g. VEM, VE, V, EM). U/S/P are not flag letters.`
+      `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.`
+    );
+  }
+  if (typeof v.flags === "string" && v.flags.includes("M") && v.isNullable === true) {
+    const virtual = typeof v.columnType === "string" && ["R", "S", "F"].includes(v.columnType);
+    err(
+      `flags '${v.flags}' includes 'M' (mandatory) while "isNullable": true \u2014 a contradiction that fails at pack time. 'M' is resolved into isNullable:false at install. Drop 'M' if the column is optional, or remove "isNullable": true if it is required.${virtual ? " (On a virtual column 'M' is inert anyway \u2014 drop it.)" : ""}`
     );
   }
   if (typeof v.fieldTypeCd === "string" && v.fieldTypeCd.length > 0 && !isFieldTypeCd(v.fieldTypeCd)) {
@@ -33179,7 +33200,7 @@ function checkFieldSpec(where, field) {
     }
     if (v.dbDatatype !== void 0) {
       err(
-        "reference column (columnType 'R') must NOT set 'dbDatatype' \u2014 the physical column is the paired hidden FK (flags 'EM'), not this one."
+        "reference column (columnType 'R') must NOT set 'dbDatatype' \u2014 the physical column is the paired hidden FK (flags 'EM' when required, else 'E'), not this one."
       );
     }
   }
@@ -33227,9 +33248,10 @@ var fieldSchema = external_exports.object({
   }
 }).describe(
   `Field spec. RULES (load dforge://reference/flags, /field-types, /column-types first):
-\u2022 flags = a subset of V/E/M only. NEVER combine I or H with them. VEM = required+visible; VE = optional+visible; V = read-only/formula; EM = hidden FK. 'VEMHI' is INVALID.
+\u2022 flags = a subset of V/E/M only. NEVER combine I or H with them. VEM = required+visible; VE = optional+visible; V = read-only/formula; EM/E = hidden FK (required/optional). 'VEMHI' is INVALID.
+\u2022 'M' means required: it is resolved into isNullable:false at install, so it makes the column NOT NULL. Declaring 'M' AND "isNullable": true fails the pack. 'M' is inert on virtual (R/S/F) and identity columns \u2014 don't put it there.
 \u2022 dbDatatype is AUTO-DERIVED from fieldTypeCd when omitted (e.g. currency \u2192 numeric(18,2), text \u2192 varchar) \u2014 only set it to override. Values: bool, varchar, text, int, bigint, numeric, timestamptz, date, time, cuid, json. NOT boolean/string/datetime/integer/timestamp/number \u2014 'number' is a fieldTypeCd, not a dbDatatype.
-\u2022 A relation is TWO fields: hidden FK (dbDatatype:'cuid', flags:'EM', NO fieldTypeCd) + a Reference (columnType:'R', fieldTypeCd:'lookup', flags:'VEM', link:{entity,thisKey,otherKey}). otherKey = the target entity's PK ('{entity}_id'), never 'id'.
+\u2022 A relation is TWO fields: hidden FK (dbDatatype:'cuid', flags:'EM' if required else 'E', NO fieldTypeCd) + a Reference (columnType:'R', fieldTypeCd:'lookup', flags:'VEM'/'VE' to match, link:{entity,thisKey,otherKey}). Keep the two halves in step. otherKey = the target entity's PK ('{entity}_id'), never 'id'. Prefer dforge_entity_reference_add, which emits both.
 \u2022 Formula column: columnType:'F', baseDatatypeCd set, NO dbDatatype, flags:'V'.
 \u2022 Column DEFAULTS use 'formula' (e.g. "'draft'" or "TODAY()"), NOT 'defaultValue' (settings-only).
 \u2022 dropdown options go under params.options = [{value,label}] objects, never at the field root and never bare strings.`
@@ -33324,7 +33346,9 @@ var entityReferenceAddSchema = {
   ),
   fkField: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).optional().describe("Override the hidden FK column name. Default: '<name>_id'."),
   label: external_exports.string().optional().describe("Display label for the reference column. Default: derived from name."),
-  required: external_exports.boolean().default(true).describe("true \u2192 flags 'VEM' (required); false \u2192 'VE' (optional). Mirrors the FK's nullability."),
+  required: external_exports.boolean().default(true).describe(
+    "Whether the relation is required. true \u2192 FK 'EM' + Reference 'VEM'; false \u2192 FK 'E' + Reference 'VE'. 'M' resolves to isNullable:false at install, so this is what makes the FK column NOT NULL."
+  ),
   targetPk: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).optional().describe(
     "The parent's PK column. Default '{targetEntity}_id' (what the identity trait provides). Never 'id'."
   ),
@@ -33352,16 +33376,23 @@ function entityReferenceAdd(args) {
     );
   }
   const reusedFk = Boolean(existingFk);
+  const fkFlags = args.required ? "EM" : "E";
+  const refFlags = args.required ? "VEM" : "VE";
   const fkFixes = [];
   if (existingFk) {
-    const flags2 = typeof existingFk.flags === "string" ? existingFk.flags : "";
+    const flags = typeof existingFk.flags === "string" ? existingFk.flags : "";
     if (existingFk.dbDatatype !== "cuid") {
       fkFixes.push(
         `dbDatatype ${existingFk.dbDatatype === void 0 ? "(unset)" : `'${String(existingFk.dbDatatype)}'`} \u2192 'cuid' (the target PK type)`
       );
     }
-    if (flags2 !== "EM") {
-      fkFixes.push(`flags '${flags2 || "(unset)"}' \u2192 'EM' (hidden, not user-visible)`);
+    if (flags !== fkFlags) {
+      fkFixes.push(
+        `flags '${flags || "(unset)"}' \u2192 '${fkFlags}' (hidden, not user-visible; ${args.required ? "'M' because the relation is required" : "no 'M' because the relation is optional"})`
+      );
+    }
+    if (args.required && existingFk.isNullable === true) {
+      fkFixes.push(`dropped "isNullable": true (contradicts the 'M' flag on a required relation; pack rejects the pair)`);
     }
     if (existingFk.fieldTypeCd !== void 0) {
       fkFixes.push(
@@ -33380,21 +33411,21 @@ function entityReferenceAdd(args) {
     }
   }
   const label = args.label ?? pascal(args.name).replace(/([a-z])([A-Z])/g, "$1 $2");
-  const flags = args.required ? "VEM" : "VE";
   const base = args.orderNum ?? nextOrderNum(fields);
   if (existingFk) {
-    const { fieldTypeCd: _ft, columnType: _ct, ...keep } = existingFk;
+    const { fieldTypeCd: _ft, columnType: _ct, isNullable: _in, ...rest } = existingFk;
+    const keep = args.required ? rest : { ...rest, ..._in === void 0 ? {} : { isNullable: _in } };
     fields[fkField] = {
       ...keep,
       dbDatatype: "cuid",
-      flags: "EM",
+      flags: fkFlags,
       orderNum: typeof existingFk.orderNum === "number" ? existingFk.orderNum : base,
       description: typeof existingFk.description === "string" ? existingFk.description : `${label} ID`
     };
   } else {
     fields[fkField] = {
       dbDatatype: "cuid",
-      flags: "EM",
+      flags: fkFlags,
       orderNum: base,
       description: `${label} ID`
     };
@@ -33402,7 +33433,7 @@ function entityReferenceAdd(args) {
   fields[args.name] = {
     columnType: "R",
     fieldTypeCd: "lookup",
-    flags,
+    flags: refFlags,
     orderNum: base + 5,
     description: label,
     link: { entity: args.targetEntity, thisKey: fkField, otherKey: targetPk }
@@ -33499,7 +33530,9 @@ function entityRollupAdd(args) {
     fields[setField] = {
       columnType: "S",
       fieldTypeCd: "grid",
-      flags: "VEM",
+      // No 'M': a Set is virtual, so 'M' is inert on it — but it would read as
+      // "this grid must be non-empty", which nothing enforces.
+      flags: "VE",
       orderNum: nextOrderNum(fields),
       description: pascal(setField).replace(/([a-z])([A-Z])/g, "$1 $2"),
       link: { entity: args.childEntity, thisKey: pkOf(args.entity), otherKey: childFk }
@@ -34144,10 +34177,13 @@ var path9 = __toESM(require("path"));
 var BLOCKS = ["params", "canExecute", "onBeforeStart", "execute"];
 var DSL_BUILTINS = /* @__PURE__ */ new Set([
   "addDays",
+  "addMinutes",
   "addSeconds",
+  "applyProfile",
   "callApi",
   "callProc",
   "callService",
+  "currentUserId",
   "delete",
   "detectDocument",
   "download",
@@ -34155,6 +34191,7 @@ var DSL_BUILTINS = /* @__PURE__ */ new Set([
   "error",
   "exit",
   "flush",
+  "getFileBase64",
   "getFileInfo",
   "getFileUrl",
   "getRecord",
@@ -34208,7 +34245,12 @@ var JS_RESERVED = /* @__PURE__ */ new Set([
   "RegExp",
   "Error"
 ]);
-var FORMULA_ONLY = ["TODAY", "NOW"];
+var VALUE_MEMBERS = /* @__PURE__ */ new Set(["userId"]);
+var FORMULA_ONLY = {
+  TODAY: "now()",
+  NOW: "now()",
+  CURRENT_USER_ID: "currentUserId()"
+};
 function blank(src) {
   let out = "";
   let i = 0;
@@ -34337,17 +34379,25 @@ function checkDsl(src, opts = {}) {
   const execCode = execBlock ? code2.slice(execBlock.start, execBlock.end) : "";
   const execOffset = execBlock ? execBlock.start : 0;
   if (execBlock) {
-    for (const fn of FORMULA_ONLY) {
+    for (const [fn, replacement] of Object.entries(FORMULA_ONLY)) {
       const re = new RegExp(`\\b${fn}\\s*\\(\\s*\\)`, "g");
       for (const m of execCode.matchAll(re)) {
         add(
           "error",
           "execute-formula-date",
-          `the execute: block calls ${fn}(), which is undefined at runtime \u2014 install fails with "'${fn}' is not defined". Use lowercase now() in execute:. ${fn}() is formula-only (canExecute:, formula columns).`,
+          `the execute: block calls ${fn}(), which is undefined at runtime \u2014 install fails with "'${fn}' is not defined". Use ${replacement} in execute:. ${fn}() is formula-only (canExecute:, formula columns).`,
           lineOf(src, execOffset + (m.index ?? 0))
         );
       }
     }
+    for (const m of execCode.matchAll(/\buserId\s*\(/g)) {
+      add(
+        "error",
+        "user-id-called-as-function",
+        "'userId' is a value, not a function \u2014 write 'userId' without parentheses, or 'currentUserId()'.",
+        lineOf(src, execOffset + (m.index ?? 0))
+      );
+    }
   }
   const recordRefs = [...code2.matchAll(/(?<![\w\]$])\[([a-z][a-z0-9_]*)\]/g)];
   const mode = (opts.executionMode ?? "").toLowerCase();
@@ -34411,7 +34461,7 @@ function checkDsl(src, opts = {}) {
   const reported = /* @__PURE__ */ new Set();
   for (const m of code2.matchAll(/(?<![.\w$])([A-Za-z_$][\w$]*)\s*\(/g)) {
     const fn = m[1];
-    if (DSL_BUILTINS.has(fn) || JS_RESERVED.has(fn) || local.has(fn) || reported.has(fn) || FORMULA_ONLY.includes(fn)) {
+    if (DSL_BUILTINS.has(fn) || JS_RESERVED.has(fn) || local.has(fn) || reported.has(fn) || fn in FORMULA_ONLY || VALUE_MEMBERS.has(fn)) {
       continue;
     }
     reported.add(fn);
@@ -36505,7 +36555,7 @@ server.registerTool(
   "dforge_entity_reference_add",
   {
     title: "Add a relation (FK + Reference)",
-    description: "PHASE 1: Add a relation between two entities in ONE call. Emits the complete FK+Reference pattern \u2014 the documented #1 source of broken modules \u2014 as all three of its parts: the hidden FK column (dbDatatype 'cuid', flags 'EM', no fieldTypeCd), the visible Reference column (columnType 'R', fieldTypeCd 'lookup', flags VEM/VE, link{entity,thisKey,otherKey}), and the `references` block entry. Use this instead of two dforge_entity_field_add calls \u2014 it can't emit the one-column form that fails install.",
+    description: "PHASE 1: Add a relation between two entities in ONE call. Emits the complete FK+Reference pattern \u2014 the documented #1 source of broken modules \u2014 as all three of its parts: the hidden FK column (dbDatatype 'cuid', flags 'EM'/'E', no fieldTypeCd), the visible Reference column (columnType 'R', fieldTypeCd 'lookup', flags 'VEM'/'VE', link{entity,thisKey,otherKey}), and the `references` block entry. `required` sets 'M' on both halves in step \u2014 'M' resolves to isNullable:false at install, so it is what makes the FK NOT NULL. Use this instead of two dforge_entity_field_add calls \u2014 it can't emit the one-column form that fails install.",
     inputSchema: { ...entityReferenceAddSchema, ...applyInput }
   },
   envelope(entityReferenceAdd)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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",
@@ -34,8 +34,8 @@
     "install-skills": "node scripts/install-skills.mjs"
   },
   "dependencies": {
-    "@dforge-core/dforge-cli": "^0.2.7",
-    "@dforge-core/metadata": "^0.0.10",
+    "@dforge-core/dforge-cli": "^0.2.10",
+    "@dforge-core/metadata": "^0.0.12",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3"
   },

package/resources/docs/conventions.md

@@ -135,15 +135,14 @@ The entity file uses the same `fields` schema as regular entities, plus an `exte
 	"fields": {
 		"customer_id": {
 			"dbDatatype": "int8",
-			"isNullable": true,
-			"flags": "EM",
+			"flags": "E",
 			"orderNum": 34,
 			"description": "Customer FK"
 		},
 		"customer": {
 			"columnType": "R",
 			"fieldTypeCd": "lookup",
-			"flags": "VEM",
+			"flags": "VE",
 			"orderNum": 35,
 			"description": "Customer",
 			"link": {
@@ -641,7 +640,6 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 		},
 		"department_id": {
 			"dbDatatype": "cuid",
-			"fieldTypeCd": "hidden",
 			"flags": "EM",
 			"orderNum": 30,
 			"description": "Department ID"
@@ -715,8 +713,7 @@ For every foreign key relationship, create TWO columns:
 ```json
 "department_id": {
 	"dbDatatype": "cuid",
-	"fieldTypeCd": "hidden",
-	"flags": "EM",
+	"flags": "E",
 	"orderNum": 30,
 	"description": "Department ID"
 }
@@ -727,7 +724,7 @@ For every foreign key relationship, create TWO columns:
 "department": {
 	"columnType": "R",
 	"fieldTypeCd": "lookup",
-	"flags": "VEM",
+	"flags": "VE",
 	"orderNum": 35,
 	"description": "Department",
 	"link": {
@@ -752,8 +749,14 @@ For every foreign key relationship, create TWO columns:
 - Reference columns use `"link"` (not `"params"`) for entity binding
 - `link.entity` = target entity code, `link.thisKey` = local FK field, `link.otherKey` = remote PK field
 - `params` is used for other purposes (e.g., dropdown `options`)
-- Hidden FK column: `flags: "EM"` (no `V` = hidden from UI)
-- Visible reference column: `flags: "VEM"`, `columnType: "R"`
+- Hidden FK column: `flags: "E"` (no `V` = hidden from UI), `flags: "EM"` when the
+  relationship is genuinely required. `M` resolves to `isNullable: false` at install, so it
+  makes the FK `NOT NULL`; omitting both leaves the column nullable, which is the default.
+  Declaring `M` alongside `"isNullable": true` fails at pack time.
+- Visible reference column: `columnType: "R"`, `flags: "VE"` — or `"VEM"` when the FK is
+  required. **Keep the two in step.** `M` is inert on a virtual column (a Reference is
+  required exactly when its hidden FK is), so `VEM` over an optional FK changes nothing but
+  reads as a required field to the next author.
 - The FK column's `dbDatatype` **MUST match the referenced PK's type** — use `cuid` for `identity`-trait PKs (`cuid` is physically `int8`, **not** a UUID). A mismatch (e.g. FK `uuid` → PK `cuid`) fails install with *"foreign key constraint … cannot be implemented"*.
 
 ---

package/resources/docs/dsl-reference.md

@@ -149,7 +149,10 @@ var open = query(
     { s: 'open', cid: [customer_id] }
 )
 if (open.length == 0) { exit('Nothing open', 'info') }
-info('Open invoices: ' + open.length + ', total $' + open[0].total)
+for (var i = 0; i < open.length; i++) {
+    update('fin.invoice', open[i].invoice_id, { status: 'reminded' })
+}
+info('Reminded ' + open.length + ' open invoice(s)')
 ```
 
 > **Pooled connection.** The connection is handed to another request once your
@@ -228,7 +231,8 @@ The result is a **read-only** snapshot — writing to it (`rec.set(...)`) throws
 
 ```dsl
 var rec = getRecord('crm.customer', [customer_id])
-info('Customer: ' + rec.name + ' — credit limit $' + rec.credit_limit)
+if (rec.credit_limit == null) { error('Customer has no credit limit set') }
+[customer_name] = rec.name
 ```
 
 #### `getRecordOrNull(entityCd, key) → record | null`
@@ -245,7 +249,7 @@ Call a stored procedure with named args. Returns the proc's result row (or rows
 
 ```dsl
 var summary = callProc('fin.compute_balance', { account_id: [account_id], as_of: now() })
-info('Balance: ' + summary.balance)
+[closing_balance] = summary.balance
 ```
 
 #### `preloadRef(fkField)`
@@ -284,11 +288,75 @@ Fractional-unit arithmetic.
 [token_expires_at] = addMinutes(now(), 15)
 ```
 
+### Current user
+
+#### `currentUserId() → long`, `userId → long`
+The acting user's tenant user ID. Two spellings for the same value — `userId` is
+a **bare identifier**, `currentUserId()` is the call form. Both are always
+available; use whichever reads better.
+
+```dsl
+[approved_by_id] = userId
+[created_by_id] = currentUserId()
+notify(userId, 'Done')
+```
+
+`userId()` — the value spelled as a call — is **rejected at compile time**:
+
+```
+'userId' is a value, not a function — write 'userId' without parentheses, or 'currentUserId()'
+```
+
+`CURRENT_USER_ID()` is **not** available in `execute:` — it is a *formula* function,
+valid in `canExecute:`, formula columns, filters and reports, exactly like
+`TODAY()`/`NOW()` vs `now()`. Same split, same reason: `execute:` is JavaScript,
+the rest is the formula engine.
+
+#### 64-bit ids are BigInt
+
+JS numbers are doubles (53 mantissa bits); dForge ids are 58-bit snowflakes. Any
+`long` outside ±2^53 — user ids, PKs, FKs — reaches the script as a JS **BigInt**,
+so ids stay exact through reads, writes and comparisons. Smaller `int8` values
+(counters, quantities) stay ordinary numbers, so arithmetic on them is unchanged.
+
+```dsl
+[copy] = [owner_id]                            # exact round-trip
+[is_mine] = currentUserId() == [last_updated_by]   # exact — both sides BigInt
+[label] = '' + [owner_id]                      # "200650220910936067"
+```
+
+Two operations throw instead of rounding silently:
+
+```dsl
+[x] = [owner_id] + 1               # Cannot mix BigInt and other types
+[x] = Number([owner_id]) + 1       # explicit — and accepts the rounding
+
+[x] = JSON.stringify([owner_id])   # Do not know how to serialize a BigInt
+[payload] = { id: [owner_id] }     # assign the object; jsonb writes the number
+```
+
+Never write a large id as a bare numeric literal — the literal itself rounds
+before the comparison runs:
+
+| Comparison | Result |
+|---|---|
+| `[owner_id] == 200650220910936067` | ❌ literal rounded to `…064` |
+| `[owner_id] == '200650220910936067'` | ✅ string coerces to BigInt |
+| `[owner_id] == 200650220910936067n` | ✅ BigInt literal |
+| `[owner_id] === '200650220910936067'` | ❌ strict equality, different types |
+
+For "who did this", prefer the platform audit columns (`created_by` /
+`last_updated_by`) — filled server-side, no script involved. For ownership
+predicates in `canExecute:` or a formula column, use `CURRENT_USER_ID()`, which
+the server translates to an exact `::bigint` SQL literal.
+
 ### Messaging & notifications
 
 #### `info(message, opts?)`, `warn(message, opts?)`
 Queue user-facing toast. `opts.links: [{entity, id}]` adds "open record" buttons.
 
+A message is a **receipt for work the action did**, not a way to publish a computed value. An action whose only output is `info('<some computed number>')` stores nothing — it can't be audited, re-read or reported on, and the value arrives unformatted. Build a report, a formula column, or an action that writes a result record instead. See `dforge://reference/action-dsl`, *When an action is the wrong tool*.
+
 ```dsl
 info('Created PO ' + po.po_number, {
     links: [{ entity: 'purchase_order', id: po.purchase_order_id }]
@@ -453,17 +521,36 @@ var det = detectDocument(data.raw_text)     // { profile: 'proc.bill_of_lading',
 if (det != null) { var r = ocrExtract([doc_file], getSetting('ocr_endpoint_url'), null, { profile: det.profile }) }
 ```
 
+#### `applyProfile(json, profile) → object`
+Map an already-extracted JSON payload through a registered extraction profile's
+field schema, without re-running OCR. Use when the raw JSON came from somewhere
+other than `ocrExtract()` — a webhook payload, a stored response, a re-process of
+an earlier extraction.
+
+```dsl
+var mapped = applyProfile(tryParseJson([raw_payload]), 'proc.bill_of_lading')
+```
+
 ### Utility
 
 #### `entityLink(entityCd, record, description?) → link value`
 Build a clickable link to any entity record for storing in an `entitylink` (jsonb)
 column. `record` is a row object (e.g. from `insert()` / `getRecord()`); its PK
-columns are stored as **strings** so snowflake/cuid ids > 2^53 stay exact. Optional
-`description` sets the display text.
+columns are stored as **strings** so snowflake/cuid ids > 2^53 stay exact.
+
+The target entity is resolved at build time and stored **by id**, not by code:
+`entity_cd` is only unique per module, so a bare `'invoice'` would re-resolve at click
+time against the *reader's* folder module and could land on another module's entity.
+Always qualify the code you pass (`'fin.invoice'`).
+
+`description` is optional — omit it and the link is captioned with the entity's
+`toString` evaluated against `record`, the way records are captioned everywhere else.
+An explicit `description` still wins.
 
 ```dsl
 var task = insert('workspace.task', { title: 'Follow up' })
-insert('workspace.task_note', { link: entityLink('workspace.task', task, task.title) })
+# Captioned by workspace.task's toString — no third argument needed.
+insert('workspace.task_note', { link: entityLink('workspace.task', task) })
 ```
 
 #### `flush()`

package/resources/schemas/entity.schema.json

@@ -130,7 +130,7 @@
 				"flags": {
 					"type": "string",
 					"pattern": "^[VIEMH]*$",
-					"description": "Display flags: V=Visible, I=Identity, E=Editable, M=Mandatory, H=Hidden"
+					"description": "Display flags: V=Visible, I=Identity, E=Editable, M=Mandatory, H=Hidden. M is resolved into isNullable:false at install, so it makes the column NOT NULL; it is inert on virtual (R/S/F) and identity columns. Declaring M together with isNullable:true is rejected at pack time."
 				},
 				"isPk": {
 					"type": "boolean",
@@ -138,7 +138,7 @@
 				},
 				"isNullable": {
 					"type": "boolean",
-					"description": "Whether the column allows NULL values"
+					"description": "Whether the column allows NULL values. Omitted means true (nullable) — only an explicit false, or the M flag which resolves to it, makes the column NOT NULL. Adding it to a column that existing tenant rows leave empty aborts the upgrade."
 				},
 				"isIdentity": {
 					"type": "boolean",

package/resources/schemas/triggers.schema.json

@@ -33,7 +33,7 @@
 				"event": {
 					"type": "string",
 					"enum": ["insert", "update", "delete", "status_change", "any"],
-					"description": "DB event that fires this trigger. 'status_change' only fires when the entity's status field actually changes value. 'any' fires for all insert/update/delete."
+					"description": "DB event that fires this trigger. 'status_change' only fires when the entity's status field actually changes value. 'any' fires for all insert/update/delete. Events are raised by the row change itself, whichever path wrote it \u2014 a user edit and an action's `[field] = value` both count \u2014 except for the DSL's insert()/update()/delete()/query() builtins writing OTHER records, which raise nothing."
 				},
 				"condition": {
 					"type": "string",

package/skills/dforge-mcp-author/examples/simple-todo/entities/todo_item.json

@@ -23,6 +23,7 @@
 			"dbDatatype": "varchar",
 			"fieldTypeCd": "dropdown",
 			"flags": "VEM",
+			"formula": "'medium'",
 			"maxLen": 20,
 			"orderNum": 30,
 			"description": "Priority",

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

@@ -5,6 +5,26 @@ Actions are dForge's business logic. They are scripts with three declarative blo
 Lives in: `logic/actions/<action_name>.dsl`
 Registered in: `ui/actions.json`
 
+## When an action is the wrong tool
+
+An action exists to **change something**. Its message is a receipt for work that was done — not the output itself.
+
+Do **not** write an action whose `execute:` block only reads data, computes a value and reports it with `info()`. The result is a line of text that is never stored: it can't be audited, referenced, re-read or reported on, and every reader has to re-run the action to see it again. The value also reaches the user unformatted — a raw `query()` result carries no column metadata, so money renders as `1000.0099999999999` instead of `1,000.01`.
+
+If you are about to write a `check_…`, `calculate_…` or `show_…` action, build one of these instead:
+
+| What's actually needed | Build this |
+|---|---|
+| The user needs to **see** current numbers | A **report** or a data view — both are metadata-driven, so values format correctly, and the user can return to them any time without re-running anything. |
+| A derived value **belongs to the record** | A **formula column** (`columnType: "F"`) or a roll-up — computed on read, visible on the card and in grids, filterable and sortable. |
+| The **verdict itself matters** (approvals, credit checks, compliance) | An action that **writes a result record** — e.g. `credit_check(customer, checked_at, limit, outstanding, projected, verdict, checked_by)`. Now it's auditable and reportable, and `info()` becomes a legitimate receipt with a link to the new row. |
+| The check must **block** something | A **trigger** with `async: false`, or a `canExecute:` guard on the action being gated — enforcement, not narration. |
+
+Messages stay correct for exactly two things, and both are short by nature:
+
+- a **receipt** for a mutation that just happened — `info('Created PO ' + po.po_number, { links: [...] })`
+- a **refusal** that prevented one — `error('Period is closed')`
+
 ## Structure
 
 A DSL file has up to three blocks. All are optional (but `execute:` is needed to actually do something).
@@ -126,6 +146,17 @@ var note = params[note]             // no quotes around param name in this DSL
 > `null` key **throws** (a `col = NULL` predicate can never match), and array keys are rejected —
 > loop and mutate per id instead.
 
+> **These writes raise no events.** `insert()`, `update()`, `delete()` and `query()` are the raw
+> write layer: by design they skip folder row-filters, closed-period checks and registry state, and
+> they raise no trigger or webhook events either. Only the **acted-on record's own**
+> `[field] = value` raises them — that one is indistinguishable from a user editing the same field,
+> and fires the entity's `update` / `status_change` triggers exactly as the grid does.
+>
+> So a trigger on `b` will not see `update('b', …)` from an action bound to `a`. If `b` must react,
+> put the trigger on `a` — the entity the action is bound to — or make the change through `b`'s own
+> action. The symptom when you get this wrong is a trigger that simply never fires, with nothing in
+> the log to say why.
+
 ### select() — structured multi-row reads
 
 The read counterpart to `insert()`/`update()`/`delete()`. Entity codes are metadata-validated,
@@ -174,7 +205,7 @@ var queued = select('comm.message', {
 |---|---|
 | `error('message')` | **Abort** the action and show an error to the user. Rolls back all changes. |
 | `warn('message')` | Show a warning but continue execution. |
-| `info('message')` | Show an informational message. |
+| `info('message')` | Show an informational message. A **receipt for work the action did** — not a way to publish a computed value; see *When an action is the wrong tool*. |
 | `exit('message'?, 'level'?)` | **Stop the script early without error** — changes made so far are kept. Level `'info'` (default) or `'warn'` styles the message. This is the DSL's early-return: a bare `return` is not valid at the top level of `execute:`. |
 | `notify(userId, 'message')` | Send an in-app notification to a specific user. First arg is a user ID (typically `[owner_id]` or similar). |
 
@@ -193,17 +224,34 @@ var queued = select('comm.message', {
 | `getFileBase64(fileFieldValue)` | String | Read a file from storage and return its content as a base64-encoded string. Use with `callApi()` to send files to AI APIs. Max 10 MB. Example: `getFileBase64([document_file])`. |
 | `getFileUrl(fileFieldValue)` | String | Generate a temporary signed download URL (relative path) for a file field. Use in email templates or notifications — not for `callApi()`. |
 | `getSecret('secret_cd')` | String | Retrieve a decrypted secret value (API keys, tokens). Secrets are managed in the admin UI. |
+| `getFileInfo(fileFieldValue)` | Object \| null | File metadata for a file field. |
+| `download(url, fileName?)` | — | Fetch a URL into tenant storage. |
+| `callService('name', { args })` | Any | Invoke a registered host service. |
+
+### Files, settings, document extraction
+
+| Function | Returns | Description |
+|---|---|---|
+| `getSetting('setting_cd')` | Any | Read a module setting, resolved through the folder chain (current folder → parents → module default). |
+| `ocrExtract(fileField, endpointBaseUrl, schema?, opts?)` | Object | Run OCR extraction against a document. `opts.profile` selects a registered extraction profile, e.g. `{ profile: 'proc.bill_of_lading' }`. |
+| `detectDocument(rawText)` | Object \| null | Score text against reachable extraction profiles; returns the best match `{ profile, docType, score }` or `null`. |
+| `applyProfile(json, 'module.profile_cd')` | Object | Map already-extracted JSON through a profile's field schema, without re-running OCR. |
 
 ### Utilities
 
 | Function | Returns | Description |
 |---|---|---|
 | `now()` | DateTime | Current date/time. Use for `date`, `datetime`, and `timestamp` fields. **Lowercase** — this is the execute-block date function. |
-| `IF(condition, trueVal, falseVal)` | Any | Ternary helper. |
 | `addDays(date, n)` | Date | Add `n` days to a date, e.g. `addDays(now(), 30)`. |
+| `addMinutes(date, n)` | DateTime | Add `n` minutes, e.g. `addMinutes(now(), 15)`. |
+| `addSeconds(date, n)` | DateTime | Add `n` seconds. |
+| `currentUserId()` | Long | The acting user's tenant user ID. |
+| `userId` | Long | Same value as `currentUserId()`, as a **bare identifier — no parentheses**. `userId()` is a compile error; there is no `current_user_id()`. |
+| `flush()` | — | Flush pending writes so a following read sees them. |
+| `tryParseJson(value)` | Any \| null | Parse JSON, returning `null` on failure instead of throwing. |
 | `nextNumber('entity')` | String | Generate next value from a number sequence. Usually not needed — platform auto-fills on `insert()`. Use for pre-generating numbers. |
 | `callProc('proc_name', { args })` | Result | Call a stored procedure. Args are passed as named parameters. |
-| `entityLink('entityCd', record, description?)` | Link value | Build a clickable link to any entity record, for storing in an `entitylink` (jsonb) column. `record` is a row object (e.g. the result of `insert()` or `getRecord()`); its PK columns are read and stored as **strings**, so snowflake/cuid ids (> 2^53) stay exact. Optional `description` sets the link's display text. |
+| `entityLink('entityCd', record, description?)` | Link value | Build a clickable link to any entity record, for storing in an `entitylink` (jsonb) column. `record` is a row object (e.g. the result of `insert()` or `getRecord()`); its PK columns are read and stored as **strings**, so snowflake/cuid ids (> 2^53) stay exact. The entity is resolved at build time and stored **by id** — `entity_cd` is only unique per module, so always pass a qualified code (`'fin.invoice'`). Omit `description` and the link is captioned with the entity's `toString` against `record`; an explicit `description` wins. |
 
 > **Dates: `now()` in `execute:`, `TODAY()`/`NOW()` in formulas.** The `execute:` block runs as
 > JavaScript (Jint) and exposes **lowercase `now()`** only — `TODAY()` and `NOW()` (uppercase) are
@@ -212,6 +260,32 @@ var queued = select('comm.message', {
 > columns, and other formula contexts; use `now()` everywhere inside `execute:`. (Uppercase `NOW()`
 > is also fine *inside a raw SQL string* passed to `query()`, because that's SQL, not JS.)
 
+> **`IF()` is formula-only too.** It was previously listed here as a ternary helper — that was
+> wrong. `IF(cond, a, b)` is a **formula-engine** function, valid in `canExecute:` and formula
+> columns, and **undefined in `execute:`** (install fails with `'IF' is not defined`). Inside
+> `execute:` use the JavaScript conditional operator: `var x = cond ? a : b`.
+
+> **64-bit ids are BigInt in `execute:`.** JS numbers are doubles (53 mantissa bits) and dForge
+> ids are 58-bit snowflakes, so any `long` outside ±2^53 — user ids, PKs, FKs — reaches the script
+> as a JS **BigInt**. Ids stay exact through reads, writes and comparisons, including
+> `currentUserId() == [last_updated_by]`. Smaller `int8` values (counters, quantities) stay
+> ordinary numbers, so arithmetic on them is unchanged.
+>
+> Two operations throw rather than round silently, each with a working form:
+> `[owner_id] + 1` → use `Number([owner_id]) + 1` (explicit, and accepts the rounding);
+> `JSON.stringify([owner_id])` → assign the object instead (`[payload] = { id: [owner_id] }`),
+> which serializes correctly on the write path.
+>
+> Never write a large id as a bare numeric literal — the literal itself rounds before the
+> comparison runs. `[owner_id] == 2006…067` is **false**; quote it (`== '2006…067'`) or suffix
+> it with `n` (`== 2006…067n`). Comparing two id columns needs neither.
+>
+> For "who did this", the platform audit columns (`created_by` / `last_updated_by`) remain the
+> better answer — filled server-side, no script involved. For ownership predicates use
+> **`CURRENT_USER_ID()`** in `canExecute:` or a formula column — a *formula-engine* function
+> (undefined in `execute:`) that the server translates to an exact `::bigint` SQL literal.
+
+
 ## Real examples from the codebase
 
 ### Simple field update (status transition)
@@ -514,6 +588,7 @@ way.
 
 ## Common mistakes
 
+- Writing an action that only reads, computes and prints (`info('Balance: ' + total)`) — **wrong shape**, not just wrong formatting. Nothing is stored, so nobody can re-read the answer. Use a report, a formula column, or write a result record. → *When an action is the wrong tool* (top of this file)
 - Writing `params.note` instead of `params[note]` — **wrong**. Use bracket syntax for params.
 - Writing `params["note"]` — **also wrong in DSL syntax**. Use `params[note]` without quotes.
 - Writing `update [status] = 'Draft'` (declarative style) — **wrong**. Use `[status] = 'Draft'` (assignment).

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

@@ -33,8 +33,14 @@ Most columns. They map 1:1 to a physical SQL column.
 
 Virtual N:1 lookup. No physical column. Always **paired with a hidden FK column** that does hold the physical data. Together they form the **FK+Reference pattern**.
 
+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.
+
 ```json
-// Hidden FK column — physical, hidden
+// Hidden FK column — physical, hidden. "E" instead of "EM" if the relation is optional.
 "account_id": {
     "dbDatatype": "cuid",
     "flags": "EM",
@@ -175,9 +181,10 @@ inside one aggregate must point at the **same** set column, and `COUNT(*)` is re
 
 > ⛔ **Do not use a Formula (`F`) column for set aggregation.** `SUM([set].[field])` in an `F`
 > column is **not supported** by the engine — the formula runtime has no `SUM`/`COUNT`/`AVG`, and
-> nav resolution only walks single-hop N:1 references, never a 1:N set. The column silently renders
-> **empty** on the form, grid, and reports (no error). `F` is for same-row expressions
-> (`[qty] * [price]`) and single-hop reference navigation (`[account].[name]`) only.
+> nav resolution walks N:1 references only, never a 1:N set (however many hops it is given). The
+> column silently renders **empty** on the form, grid, and reports (no error). `F` is for same-row
+> expressions (`[qty] * [price]`) and N:1 reference navigation (`[account].[name]`, and multi-hop
+> chains — see `dforge://reference/formulas`).
 
 > ⛔ **The aggregated child column must be physical.** A `G` trigger reads the child's `OLD`/`NEW`
 > physical values, so aggregating a **virtual** child column (`F`/`R`/`S`) fails at install with

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

@@ -64,8 +64,10 @@ Only include what your module actually uses — not every module needs `print_te
 
 **Every reference to another entity is two columns**:
 
-1. Hidden FK column with `flags: "EM"` and `dbDatatype` matching the target PK type
-2. Visible Reference column with `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags: "VEM"`, and a `link` object pointing at the target
+1. Hidden FK column with `flags: "E"` — `"EM"` when the relation is genuinely required — and `dbDatatype` matching the target PK type
+2. Visible Reference column with `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags: "VE"` / `"VEM"` **matching the FK**, and a `link` object pointing at the target
+
+`M` resolves to `isNullable: false` at install, so it is what makes the FK column `NOT NULL` — keep the two halves in step. `dforge_entity_reference_add({ required })` emits both correctly.
 
 Plus the actual FK constraint declared in the entity's `references` block.
 

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

@@ -67,8 +67,8 @@ If none of an entity's fields are visible (or only its set/child-collection colu
 ```jsonc
 // WRONG — grid over an entity whose fields are all hidden (no "V")
 "fields": {
-    "code": { "fieldTypeCd": "text", "flags": "EM" },   // E=editable, M=… but no V
-    "lines": { "columnType": "S", "flags": "VEM" }        // visible, but a SET — doesn't count for a grid
+    "code": { "fieldTypeCd": "text", "flags": "EM" },   // E=editable, M=required, but no V
+    "lines": { "columnType": "S", "flags": "VE" }        // visible, but a SET — doesn't count for a grid
 }
 // RIGHT — at least one visible scalar field
 "fields": {

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

@@ -72,7 +72,7 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 | `user` | `cuid` | `D` | User picker. Writes a user ID directly, no paired FK needed. |
 | `grid` | `set` | `S` | Detail grid of related records (1:N backwards reference). Used with `link` declaring the relation. |
 | `list` | `set` | `S` | Detail list — same 1:N set as `grid`, rendered as a card list instead of a table. |
-| `entitylink` | `json` | `D` | Polymorphic link to any entity (stores `{entity, id}` pair). Populate from action DSL with the `entityLink('entityCd', record, description?)` built-in (see `action-dsl.md`). |
+| `entitylink` | `json` | `D` | Polymorphic link to any entity — stores the **resolved entity id** plus the record's PK (as strings) and a display caption. Populate from action DSL with the `entityLink('entityCd', record, description?)` built-in; pass a qualified entity code (see `action-dsl.md`). |
 
 ## JSON
 

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

@@ -11,26 +11,54 @@ Valid flags regex: `^[VIEMH]*$`
 | `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. |
 | `E` | Editable | User can modify the value in the UI. Omit for read-only. |
-| `M` | Mandatory | Required (NOT NULL + UI enforcement). |
+| `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.
 
+## `M` is the platform's one notion of "required"
+
+At install, `MandatoryFlagNormalizer` folds `M` into `isNullable: false` before DDL
+generation. Everything downstream reads only `isNullable`: the `NOT NULL` in the
+generated DDL, `data.insert`'s required-column check, and the red asterisk on the
+client. There is no second signal.
+
+Four consequences worth knowing before you type a flag:
+
+- **`M` makes the column `NOT NULL`.** It is not decoration and not a UI hint. Put it
+  on a column only when a row is genuinely meaningless without the value.
+- **`M` together with `"isNullable": true` is a hard error at pack time**, naming the
+  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
+  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
+  rows leave it empty — rolled back, naming the column and its NULL row count. Give
+  the column a `params.serverDefault` if the install should backfill it. Removing `M`
+  is always safe.
+
+Omitting both `M` and `isNullable` leaves the column nullable — that is the default.
+
 ## Common column flag combinations
 
 | Flags | Meaning | Use case |
 |---|---|---|
-| `"VEM"` | Visible, Editable, Mandatory | Required field shown in UI (most business fields) |
-| `"VE"` | Visible, Editable, optional | Nullable field |
+| `"VEM"` | Visible, Editable, Mandatory | Required field shown in UI |
+| `"VE"` | Visible, Editable, optional | Nullable field — the common case for most business fields |
 | `"V"` | Visible, read-only | Display-only, like formula columns or computed values |
-| `"EM"` | Editable, Mandatory, **not visible** | Hidden FK columns in the FK+Reference pattern |
+| `"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. |
 | `""` (empty) | No flags | Rare — column exists but is invisible and not editable |
 
 ## Rules
 
-1. **Hidden FK columns**: always `"EM"`. They must be writeable (E) and required (M), but never shown (no V).
-2. **Visible Reference columns**: always `"VEM"`. The user sees and edits the lookup picker.
+1. **Hidden FK columns**: `"E"`, or `"EM"` when the relationship is genuinely required.
+   Writeable (E), never shown (no V). `M` here is what makes the FK `NOT NULL`.
+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"]`.
 5. **Don't use `I` on your own columns** — it's reserved for trait-provided and platform-managed columns.
@@ -68,6 +96,9 @@ These are **NOT** flag letters. They're separate properties on the column defini
 - Using `"U"` for unique — **not a valid flag**. Use `"isUnique": true` or indexes.
 - Using `"S"` for searchable — **not a valid flag**.
 - Using `"P"` for primary key — **not a valid flag**. Use `"isPk": true` or the `identity` trait.
+- Declaring `M` **and** `"isNullable": true` on the same field — a contradiction that fails the pack.
+- Reaching for `"VEM"` by default — `M` now means `NOT NULL`. Most business fields are `"VE"`.
+- 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`.
 - Using long names like `"Visible,Editable"` — **wrong**. Single letters concatenated: `"VE"`.

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

@@ -26,6 +26,12 @@ The same grammar applies everywhere.
 `CONTAINS` / `STARTS_WITH` / `ENDS_WITH` are infix operators, not functions — write
 `[note] CONTAINS 'urgent'`, never `CONTAINS([note], 'urgent')`.
 
+**Comparison is null-safe and two-valued in every context.** `null = null` is true, and
+`[x] != null` is true for any non-null `x`. There is no SQL-style third "unknown" answer,
+so `IF([completed_date] != null, 100, 0)` gives the same result on the record card and in
+a report. At SQL time `=` / `!=` translate to `IS NOT DISTINCT FROM` / `IS DISTINCT FROM`
+to preserve that.
+
 ## Examples
 
 ```
@@ -156,8 +162,9 @@ like any other boolean. A bare `date` column is treated as a **local calendar da
 - `AVG`, `MIN`, `MAX` similarly
 
 > ⚠️ **Set aggregation is NOT a Formula (`F`) feature.** `SUM([set].[field])` in an `F` column is
-> unsupported by the engine — the formula runtime has no `SUM`/`COUNT`/`AVG`, and nav resolution
-> only walks single-hop N:1 references, never a 1:N set. It silently renders **empty** (no error).
+> unsupported by **either** engine — the formula runtime has no `SUM`/`COUNT`/`AVG`, and nav
+> resolution walks N:1 references only, never a 1:N set, however many hops it is given. It
+> silently renders **empty** (no error).
 
 Put set aggregations in a **Generated (`G`) column** instead. The installer detects the set
 navigation and maintains the value with a database trigger on the child table. The aggregated
@@ -186,9 +193,20 @@ and the JSON shape: `column-types.md` → "Roll-up totals over child rows — us
 [account].[primary_contact].[phone]      -- chained
 ```
 
-Navigation works through `columnType: "R"` columns (reference columns). Chains of length 1 are **synchronous** and resolved instantly. Chains of length ≥ 2 are **asynchronous** — the formula engine resolves them after the initial data load.
+Navigation works through `columnType: "R"` columns (reference columns) — every step except the last must be a Reference, and the last reads a field on the final referenced record. Chains of length 1 are **synchronous** and resolved instantly. Chains of length ≥ 2 are **asynchronous** — the formula engine resolves them after the initial data load.
+
+**SQL-time (reports, filters, sorts).** Multi-hop navigation works here too: QueryBuilder pre-scans the formula and registers one `LEFT JOIN` per hop, then the translator resolves the path against the final alias. A nav path may also land on a *formula* column of the referenced entity — that formula is translated against the referenced entity's alias, and its own hops are joined off that alias. The same nav map drives formula columns in filters and ORDER BY, so filtering and sorting a report by a nav-formula column works.
+
+Hops are counted from the query's **root** entity and capped at `MaxNavigationDepth`, whether they come from a dotted column, a formula's own navigation, or the combination — so the hops spent reaching a formula reduce the budget left for that formula's own navigation.
+
+Still unavailable at SQL time — the column comes back NULL and the **response carries a warning** naming the column and the reason:
+
+- Settings references `$[SettingName]`
+- Navigation past the hop cap
+- **Extension-table columns** — a column an extension module added lives in a separate 1:1 ext table needing its own JOIN, and every alias the translator emits is the entity's own base alias. Applies to the hidden FK and to the Reference built on it, on the query's own entity as well as a referenced one
+- **Misauthored nav paths** — a final segment that isn't a column of the referenced entity, or a dot after something that isn't a Reference (`account.account_name.foo`)
 
-**SQL-time (reports, filters, sorts):** single-hop navigation (`[ref].[field]`) is translated to a `LEFT JOIN` and computes in reports and query datasets. Multi-hop chains and `$[Setting]` references are **not** available at SQL time — the column returns NULL there and the response carries a warning naming the column. Keep report-bound formulas to single-hop navigation.
+Warning wording follows the clause, because the same unresolvable path costs a different thing in each: a SELECT slot goes NULL (*"could not be computed and will be empty"*), an ORDER BY term is dropped so rows come back in a different order (*"Sorting by … was skipped"*), and a WHERE condition is dropped so **more** rows come back than were asked for (*"Filter on … was ignored"*). Untranslatable formula filters are never dropped silently.
 
 ## Sync vs async formulas
 

package/skills/dforge-mcp-author/references/schema-import.md

@@ -79,8 +79,10 @@ If the source uses non-standard audit column names (e.g. `date_created`, `modifi
 
 For each FK, create **two columns** following the FK+Reference pattern:
 
-1. Hidden FK column: `flags: "EM"`, matching `dbDatatype`
-2. Visible Reference column: `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags: "VEM"`, with `link`
+1. Hidden FK column: `flags: "E"` — `"EM"` only when the source column is `NOT NULL` — matching `dbDatatype`
+2. Visible Reference column: `columnType: "R"`, `fieldTypeCd: "lookup"`, `flags` **matching the FK** (`"VE"` / `"VEM"`), with `link`
+
+`M` resolves to `isNullable: false` at install, so carrying it onto an FK the source declares nullable would import the column as `NOT NULL`. `dforge_dbml_import` / `dforge_module_import` take `M` from the source's own nullability.
 
 Plus declare the constraint in the entity's `references` block.
 

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

@@ -42,8 +42,9 @@ For each entity:
 ### FK+Reference pattern
 
 - [ ] Every reference column (`columnType: "R"`) has a paired hidden FK column
-- [ ] The hidden FK column has `flags: "EM"` (not `V`, not `I`)
-- [ ] The reference column has `flags: "VEM"`, `fieldTypeCd: "lookup"`, and a `link` object
+- [ ] The hidden FK column has `flags: "E"` — `"EM"` only if the relation is required (not `V`, not `I`)
+- [ ] The reference column has `flags` **matching the FK** (`"VE"` / `"VEM"`), `fieldTypeCd: "lookup"`, and a `link` object
+- [ ] No field declares `M` together with `"isNullable": true` — that combination fails the pack
 - [ ] `link.entity` points to an entity that exists (in this module or a dependency)
 - [ ] `link.thisKey` matches the FK column name on this entity
 - [ ] `link.otherKey` matches the PK column name on the target entity

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

@@ -57,8 +57,10 @@ Enough to author inline; load the linked reference for the full detail.
 - **A relation is TWO columns + a references entry.** Use
   `dforge_entity_reference_add` — it emits all three parts. → `column-types`
 - **Flags** are letters from `V I E M H` only (never `U`/`S`/`P`): `VEM`
-  required+visible, `VE` optional+visible, `V` read-only, `EM` hidden FK, `I`
-  trait-provided. → `flags`
+  required+visible, `VE` optional+visible, `V` read-only, `E`/`EM` hidden FK
+  (optional/required), `I` trait-provided. `M` means required — it resolves to
+  `isNullable: false`, so it makes the column `NOT NULL`; don't spend it as
+  decoration, and never pair it with `"isNullable": true`. → `flags`
 - **`fieldTypeCd` = UI control; `dbDatatype` = SQL type.** Omit `dbDatatype` on
   plain data columns — it's derived. Set it only for a hidden FK or to override
   size/precision. Common fixes: `number` not `integer`/`float`; `phone` not
@@ -168,9 +170,14 @@ to fill a sub-step** — a pure CRUD module skips Phase 2 entirely (record it wi
 | 2c Jobs | a cron timer fires | `dforge_job_add` |
 | 2d Webhooks | a DB event → outbound POST | `dforge_webhook_add` |
 
-**2a Actions.** Load all four resources in the action row — the wrong-field-
-access / wrong-batch-flag / wrong-`ui/actions.json`-property mistakes only
-surface when you cross-check them. Draft the DSL, run
+**2a Actions.** First check the action is an action at all: it must **change**
+something. If the `execute:` block would only read, compute and `info()` the
+answer, build a report, a formula column, or an action that writes a result
+record instead — a printed number is never stored and can't be re-read
+(`dforge://reference/action-dsl`, *When an action is the wrong tool*). Then load
+all four resources in the action row — the wrong-field-access /
+wrong-batch-flag / wrong-`ui/actions.json`-property mistakes only surface when
+you cross-check them. Draft the DSL, run
 **`dforge_action_check({ dslBody, executionMode })`** to catch install failures
 before committing, then `dforge_action_add`. One action per turn.