@dforge-core/dforge-mcp 0.2.37 → 0.2.38

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.38 — 2026-10-12
+
+**A register column's `map` may name a debit and a credit column.** On an accounting (`L`) column,
+a resource the register splits by side maps to `{ "debit": "<line column>", "credit": "<line column>" }`;
+install requires it. `dforge://schema/entity` now allows it (metadata 0.0.39). Before this,
+`gl`, `acc-registry` and any module with a two-sided ledger failed schema validation.
+
+**A registers reference.** `dforge://reference/registers` covers the register kinds (balance, turnover,
+information, accounting classic and compound), `registers.json`, binding a document from its `A` / `L`
+columns, the DSL and report reads, and the common mistakes.
+
+**Demo data is documented.** The conventions reference gains a "Demo data" section: `demo-data/` beside
+`seed-data/`, loaded on request; `$f` formulas, `repeat`, and `vars.json`; the workspace-type gate.
+
+**Three schemas are served.** `dforge://schema/registers`, `card-layouts` and `demo-vars` were vendored or
+new but not registered. `demo-vars` is the schema for `demo-data/vars.json` (metadata 0.0.38).
+
 ## 0.2.37 — 2026-10-12
 
 **Author references brought in line with the hand-authoring copy in dForge-core.** Content that

package/dist/server.js

@@ -31290,7 +31290,7 @@ function buildZedTasks() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.37/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.39/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -34622,7 +34622,7 @@ var path10 = __toESM(require("path"));
 var fs7 = __toESM(require("fs"));
 var path9 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.37/node_modules/@dforge-core/metadata/dist/dsl/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.39/node_modules/@dforge-core/metadata/dist/dsl/index.js
 var PUNCT3 = ["===", "!=="];
 var PUNCT2 = [
   "==",
@@ -35549,9 +35549,9 @@ var BUILTINS = [
   },
   // Utilities
   { name: "now", signature: "now()", returns: "datetime", doc: "Current date/time. Lowercase \u2014 this is the execute-block date function." },
-  { name: "addDays", signature: "addDays(date, n)", returns: "date", doc: "Add `n` days to a date." },
-  { name: "addMinutes", signature: "addMinutes(date, n)", returns: "datetime", doc: "Add `n` minutes." },
-  { name: "addSeconds", signature: "addSeconds(date, n)", returns: "datetime", doc: "Add `n` seconds." },
+  { name: "addDays", signature: "addDays(date, n)", returns: "date | string", doc: "Add `n` days. Takes a date field, a `Date` or an ISO string; a date field stays a date and a `yyyy-MM-dd` string stays a string. Null stays null; any other value is an error." },
+  { name: "addMinutes", signature: "addMinutes(date, n)", returns: "datetime", doc: "Add `n` minutes. Takes a date field, a `Date` or an ISO string; the result is a timestamp. Null stays null; any other value is an error." },
+  { name: "addSeconds", signature: "addSeconds(date, n)", returns: "datetime", doc: "Add `n` seconds. Takes a date field, a `Date` or an ISO string; the result is a timestamp. Null stays null; any other value is an error." },
   { name: "currentUserId", signature: "currentUserId()", returns: "long", doc: "The acting user's tenant user ID." },
   { name: "flush", signature: "flush()", returns: "void", doc: "Flush pending writes so a following read sees them." },
   { name: "tryParseJson", signature: "tryParseJson(value)", returns: "any | null", doc: "Parse JSON, returning `null` on failure instead of throwing." },
@@ -38891,6 +38891,21 @@ var resources = [
     "Stored procedures JSON schema",
     "JSON Schema for logic/stored_procedures.json \u2014 map of stored-procedure code \u2192 { functionName, schemaName?, params?, columns? }. Required for any report dataset with datasetType 'S': the .sql file under logic/reports/ creates the function, this file registers it as the spCd a dataset binds and the sec_object an sp: right is granted on. functionName names the FUNCTION, never the script."
   ),
+  schema(
+    "registers",
+    "Registers JSON schema",
+    "JSON Schema for registers.json at the module root \u2014 map of register code \u2192 { kind (balance | turnover | info | accounting), dimensions, resources, journal/entity, totals, ... }. Documents bind to a register from their A / L columns instead of restating it."
+  ),
+  schema(
+    "card-layouts",
+    "Card layouts JSON schema",
+    "JSON Schema for ui/card_layouts.json \u2014 layout name \u2192 sections (columnGroup, set, tabGroup). Master/detail is a card layout with a tabGroup of set tabs, not a view type."
+  ),
+  schema(
+    "demo-vars",
+    "Demo data variables JSON schema",
+    'JSON Schema for demo-data/vars.json \u2014 a flat map of variable name \u2192 literal or { "$f": formula }. Demo-data formulas read them as @name.'
+  ),
   {
     uri: "dforge://docs/conventions",
     name: "dForge module conventions",
@@ -38934,6 +38949,7 @@ var resources = [
     mimeType: "text/x-python",
     read: () => readSkill("scripts/xlsx_to_model.py")
   },
+  reference("registers", "Registers: accumulation (balance / turnover / info) and accounting (classic / compound) registers, registers.json, binding a document from its A / L columns (map, per-side debit/credit objects), and the reads. Load before authoring registers.json or an A / L column."),
   reference("data-migration", "Migrating data from a legacy database."),
   reference("manifest", "manifest.json shape: moduleId UUID, semver, entities map, locale-keyed translations, security block."),
   reference("validation-checklist", "Final pre-pack self-review checklist covering every file type."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.37",
+  "version": "0.2.38",
   "description": "MCP server for dForge module authoring. Exposes 35 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",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@dforge-core/dforge-cli": "^0.2.29",
-    "@dforge-core/metadata": "^0.0.37",
+    "@dforge-core/metadata": "^0.0.39",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },

package/resources/schemas/demo-vars.schema.json

@@ -0,0 +1,28 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/demo_vars.schema.json",
+	"title": "dForge Demo Data Variables",
+	"description": "demo-data/vars.json: the variables demo-data formulas read as @name. A flat map of variable name to value. It is not a data file; the loader skips it, and each module has its own (nothing is shared between modules).",
+	"type": "object",
+	"propertyNames": {
+		"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+		"description": "A letter or underscore, then letters, digits or underscores. Names are case-insensitive, and a repeat variable of the same name shadows the file's."
+	},
+	"additionalProperties": {
+		"description": "A plain value (string, number, boolean or null) is substituted as a literal. { \"$f\": \"...\" } is a formula expanded where the variable is used, e.g. { \"$f\": \"DATEADD(TODAY(), -30, 'DAY')\" }; it may read other variables with @name (a cycle fails the install) but not [column] values.",
+		"oneOf": [
+			{ "type": ["string", "number", "boolean", "null"] },
+			{
+				"type": "object",
+				"required": ["$f"],
+				"properties": {
+					"$f": {
+						"type": "string",
+						"description": "Formula whose result is the variable's value"
+					}
+				},
+				"additionalProperties": false
+			}
+		]
+	}
+}

package/resources/schemas/entity.schema.json

@@ -259,7 +259,7 @@
 				"lineField": { "type": "string", "description": "The line's foreign-key column(s) to the header, comma-separated in the header's key order for a composite key." },
 				"stateField": { "type": "string", "description": "The bool column that records the posted state, when it is not the registry column itself. Written only by the register engine." },
 				"register": { "type": "string", "description": "The register this column posts to, as 'module_cd.register_cd' (declared in that module's registers.json). Binding to one replaces restating what the register is: the declaration supplies the state entity, dimensions, resources, journal, allowNegative and autoCreate, and this column keeps only what legitimately differs per writer — direction/sign, 'map' and 'dateField'." },
-				"map": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Register dimension or resource name -> this document's column carrying it. Every resource the register declares must be mapped (install refuses otherwise); a dimension left out binds to a column of the same name. Only meaningful with 'register'. On an accumulation (A) column a value may be a one-hop reference path, '<reference column>.<target column>', read through the reference at posting time (off the line when the binding posts from lines), or an expression: a string starting with '=' holding an F-column formula over the same row with one-hop reference reads — \"=COALESCE([transit_warehouse_id], [dest_warehouse_id])\"." },
+				"map": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "object", "required": ["debit", "credit"], "additionalProperties": false, "properties": { "debit": { "type": "string" }, "credit": { "type": "string" } } } ] }, "description": "Register dimension or resource name -> this document's column carrying it. On an accounting (L) column a resource or dimension the register splits by side maps to { \"debit\": \"<line column>\", \"credit\": \"<line column>\" } instead of one column. Every resource the register declares must be mapped (install refuses otherwise); a dimension left out binds to a column of the same name. Only meaningful with 'register'. On an accumulation (A) column a value may be a one-hop reference path, '<reference column>.<target column>', read through the reference at posting time (off the line when the binding posts from lines), or an expression: a string starting with '=' holding an F-column formula over the same row with one-hop reference reads — \"=COALESCE([transit_warehouse_id], [dest_warehouse_id])\"." },
 				"headerMap": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Register dimension or resource name -> this DOCUMENT's column carrying it, for a binding that posts from LINES. A line binding reads every other value off the line, and a dimension that belongs to the document (a dealer, an organisation, a date) cannot be put on the line: a G column is a same-row expression or an aggregate over a child set, so it cannot read a parent. Explicit rather than a fallback, because 'not on the line, try the header' turns a typo into a silent read of an unrelated header column with the same name. Install refuses: a name on neither table, a field also named in 'map', a column also read off the line by 'map', a column that is part of the line's key, a column 'lockedFields' does not freeze (the posting is keyed by it, so it has to hold still while the document is posted), and a RESOURCE unless the register is 'info' (a quantity from the document would be added once per line; an information register's records replace rather than add). A value may be a one-hop reference path off the document, whose reference key column 'lockedFields' must then freeze, or an expression over the document ('=...', see 'map')." },
 				"groupLinesBy": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true, "description": "Line columns whose distinct values each post ONE movement, instead of one per line — a production report posting 'this unit worked today' once per unit with a count of 1. 'map' is then read over a group row: the grouped line columns, every column of the document, and one-hop reads through a reference of either, so an expression may mix the document and the group key. A quoted constant is stamped once per group; a numeric line column mapped to a resource is summed over the group. Install refuses: a binding that posts from the document, an L column, a grouped column the line does not store or 'lockedLineFields' does not freeze, a line column read that is neither grouped nor a summed resource, a non-numeric summed resource, a column both grouped and summed, an ungrouped line resource on an 'info' register, a name both the line and the document carry, and a document column read that 'lockedFields' does not freeze. Accumulation (A) columns only." },
 				"dateField": { "type": "string", "description": "This document's date column, supplying the date the register stamps on each journal row. Required once the register declares a 'journalDate' — one writer that supplied none would make every balance read as of a date quietly short, across all writers. On an accumulation (A) column it may be a one-hop reference path, '<reference column>.<target column>', or an expression over the document ('=...', see 'map')." },

package/skills/dforge-mcp-author/SKILL.md

@@ -145,7 +145,7 @@ Load these by URI, one per step, at the step that needs them.
 **Per-element references** — `dforge://reference/<name>`:
 `field-types`, `flags`, `column-types`, `column-domains`, `formulas`, `traits`,
 `data-views`, `menus`, `action-dsl`, `filters`, `security`, `reports`,
-`settings`, `jobs`, `number-sequences`, `document-extraction`,
+`settings`, `jobs`, `number-sequences`, `registers`, `document-extraction`,
 `print-templates`, `translations`, `queries`, `schema-import`, `excel-import`,
 `data-migration`, `manifest`, `validation-checklist`, `conventions`.
 

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

@@ -112,6 +112,21 @@ Use explicit **numeric** PKs in seed data so cross-file references work. The `id
 
 **Common mistake**: using UUID strings like `"10000000-0000-0000-0000-000000000001"` — **wrong**. The `cuid` datatype is a numeric `int8`, not a UUID string. Seed data PKs must be numbers. Use a numbering scheme that avoids collisions (e.g. 1001-1099 for countries, 2001-2099 for regions, etc.).
 
+## Demo data
+
+Sample records live in `demo-data/`, not `seed-data/`. `seed-data/` holds reference tables every install needs; `demo-data/` is loaded only on request, so a workspace for real work does not start full of fake customers and invoices.
+
+- **Same file shape as seed data** (`entityCode` + `records`, numbered prefixes for FK order, explicit primary keys), and the same schema.
+- **Loaded on request:** `dforge-cli module install … --with-demo-data`, the "Install demo data" checkbox in the install dialogs, or `dforge-cli data demo add` on an installed module. A module's dependencies' demo data loads first. Rows already there are left alone, so repeating is safe.
+- **Workspace type gates it:** a `production` workspace refuses demo data; `staging` or an unset type needs confirmation (`--yes`).
+- **A value can be a formula**, evaluated once at insert: `{ "$f": "DATEADD(TODAY(), -80, 'DAY')" }`. `[column]` reads another column of the same row, and `@name` reads a variable. `TODAY()`, `DATEADD`, `YEAR`, `FORMAT` and `CONCAT` exist. Relative dates keep a scenario intact whatever the install date.
+- **`repeat`** builds several rows from one template, with `@m` in formulas.
+- **`demo-data/vars.json`** declares the variables: a flat `{ "name": value }` map, where a value is a literal or `{ "$f": "formula" }` and may read other variables. It is not a data file; the loader skips it, and each module has its own.
+- **References by text:** a reference column may name its target by its `toString` text instead of a numeric key; no match, or two, is an error.
+- **Not re-evaluated:** a formula runs at insert; an upgrade never recomputes it.
+
+Depth: the platform changelog entry "Demo data: its own folder, formulas, and a checkbox at install".
+
 ## Translations
 
 Translation files live in `translations/` and are named after the **IETF locale tag** (`de-DE.json`, `uk-UA.json`, etc.). Filenames are auto-discovered; declare which ones you ship in `manifest.supportedLocales`. English is the default — labels and descriptions live in entity/view JSON, so **don't** create `en.json` or `en-US.json` (they're skipped by the installer).

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

@@ -0,0 +1,274 @@
+# Registers Reference
+
+A **register** is a declared store of movements or values that documents write to by posting, and that the platform reads back with fixed primitives. Declare it once in `registers.json`; documents bind to it from an `A` or `L` column.
+
+Lives in: `registers.json` at the module root (a keyed dictionary, like `logic/jobs.json`). Schema: [`docs/schemas/registers.schema.json`](../../../docs/schemas/registers.schema.json); binding params: `registryColumnParams` in [`docs/schemas/entity.schema.json`](../../../docs/schemas/entity.schema.json). Full guide: [`docs/business-logic/registers.md`](../../../docs/business-logic/registers.md). Check with `dforge_module_validate`, then `dforge_module_pack` and `dforge_module_install`.
+
+## Register or plain table?
+
+| You need | Use |
+|---|---|
+| Running quantity or amount per key, with undo on unpost | `balance` register |
+| "How much moved in a period", no running total | `turnover` register |
+| A value that changes over time, or a keyed lookup, with "value as of a date" | `info` register |
+| Double-entry postings by account, with analytics | `accounting` register |
+| Ordinary master or transactional data nobody aggregates by key | Plain entity |
+| An ad hoc slice by an optional attribute | A report, not a dimension |
+
+A register earns its place when something must be guarded or cached by its key: a negative-stock check, a unique slice, a period lock. Posting and unposting are then the platform's job, not a DSL's.
+
+## The kinds
+
+| `kind` | Keeps | Written by | Read by | Key rules |
+|---|---|---|---|---|
+| `balance` | State row per dimension tuple, plus optional journal | `A` column | `getBalance`, `getTurnover` | Needs `entity`. Set `journal`, `journalDirection`, `journalDate` from the start. `allowNegative` default `false`, `autoCreate` default `true`. |
+| `turnover` | Journal only | `A` column | `getTurnover` | No `entity`, no `allowNegative`/`autoCreate`. `journal`, `journalDirection`, `journalDate` mandatory. `getBalance` refuses it. |
+| `info` | One table of records | `data.set` (independent) or `A` column (subordinate, has `recorder`) | `getSlice` | Needs `entity`, no `journal`. Optional `period`. Independent: unique constraint over dimensions + `period`. Binding needs a `recorder`. |
+| `accounting`, `classic` | Postings, one account per row | `L` column | `getAccountBalance`, `getAccountTurnover`, dataset `R` | `chart`, `account`, `analyticFields`, `composition`. Every resource split `debitField`/`creditField`. No correspondence. |
+| `accounting`, `compound` | Postings, debit and credit account on one row | `L` column | Same, plus `getCorrespondence` | `debitAccount` != `creditAccount`, per-side analytic arrays, optional `sideDimensions`. Resource shared (`field`) or split. Balance check refused. |
+
+Every register needs `dimensions` (1-8 columns) and `resources` (1-64). A resource is `required` by default; set `"required": false` when only some writers supply it. A property a kind refuses fails install; it is never ignored.
+
+## `registers.json`
+
+Register codes: lowercase letters, digits, underscores. A document addresses one as `module_cd.register_cd`. `label` gives it a translatable name.
+
+### Balance (`wms-registry.stock`)
+
+```json
+{
+    "stock": {
+        "kind": "balance",
+        "label": "Stock on Hand",
+        "entity": "stock",
+        "journal": "stock_movement",
+        "journalDirection": "movement_direction",
+        "journalDate": "movement_date",
+        "dimensions": ["warehouse_id", "product_id"],
+        "resources": { "quantity": { "field": "quantity" } },
+        "allowNegative": false,
+        "autoCreate": true
+    }
+}
+```
+
+### Turnover (`wms-registry.product_flow`)
+
+```json
+{
+    "product_flow": {
+        "kind": "turnover",
+        "journal": "product_flow",
+        "journalDirection": "flow_direction",
+        "journalDate": "flow_date",
+        "dimensions": ["warehouse_id", "product_id"],
+        "resources": {
+            "received": { "field": "received", "required": false },
+            "shipped": { "field": "shipped", "required": false }
+        }
+    }
+}
+```
+
+### Info (`wms-registry.outlet_price`, subordinate)
+
+```json
+{
+    "outlet_price": {
+        "kind": "info",
+        "entity": "outlet_price",
+        "recorder": "source",
+        "period": "effective_from",
+        "dimensions": ["warehouse_id", "product_id"],
+        "resources": {
+            "price": { "field": "price" },
+            "currency_cd": { "field": "currency_cd", "required": false }
+        }
+    }
+}
+```
+
+`recorder` is a jsonb column the platform stamps with the writing document. Add `"recordChangesOnly": true` (and `absentAs` per resource) to skip a record equal to the slice already in effect.
+
+### Accounting, classic (`acc-registry.gl`)
+
+```json
+{
+    "gl": {
+        "kind": "accounting",
+        "lineMode": "classic",
+        "chart": "account",
+        "journal": "gl_acc_posting",
+        "journalDate": "posted_on",
+        "account": "account_id",
+        "composition": {
+            "entity": "account_analytic",
+            "account": "account_id",
+            "slot": "slot_no",
+            "analytic": "analytic_kind_cd"
+        },
+        "analyticFields": ["analytic1", "analytic2", "analytic3", "analytic4"],
+        "dimensions": ["period_key"],
+        "resources": {
+            "amount": { "debitField": "debit_amount", "creditField": "credit_amount" }
+        }
+    }
+}
+```
+
+`composition` is where the chart says which analytic kind each account carries in which slot. It is required exactly when slot columns are declared; `"analyticFields": []` needs none. Its entity needs a unique constraint over `(account, slot)`.
+
+### Accounting, compound (`acc-registry.gl_corr`)
+
+```json
+{
+    "gl_corr": {
+        "kind": "accounting",
+        "lineMode": "compound",
+        "chart": "account",
+        "journal": "gl_corr_posting",
+        "journalDate": "posted_on",
+        "debitAccount": "debit_account_id",
+        "creditAccount": "credit_account_id",
+        "composition": { "entity": "account_analytic", "account": "account_id", "slot": "slot_no", "analytic": "analytic_kind_cd" },
+        "debitAnalyticFields": ["dt_analytic1", "dt_analytic2"],
+        "creditAnalyticFields": ["ct_analytic1", "ct_analytic2"],
+        "dimensions": ["period_key", "organization_id", "currency_cd"],
+        "sideDimensions": {
+            "currency_cd": { "debitField": "dt_currency_cd", "creditField": "ct_currency_cd" }
+        },
+        "resources": {
+            "amount": { "field": "amount" },
+            "currency_amount": { "debitField": "dt_currency_amount", "creditField": "ct_currency_amount" }
+        }
+    }
+}
+```
+
+The slot cap lives in three places that must agree: the posting's slot columns, `analyticFields`, and the chart's check constraint on the composition table. The platform does not parse that check; a mismatch is refused at post time.
+
+## Binding a document
+
+A register column is a `bool` state column. `A` writes `balance`, `turnover` and `info`; `L` writes `accounting`. Install resolves `register` and refuses an undeclared one.
+
+### `A` column (`wms-registry.stock`)
+
+```json
+"stock_out": {
+    "columnType": "A",
+    "dbDatatype": "bool",
+    "flags": "V",
+    "description": "Stock Out (source)",
+    "params": {
+        "stateField": "stock_out_state",
+        "register": "wms-registry.stock",
+        "direction": "decrease",
+        "dateField": "transfer_date",
+        "map": {
+            "warehouse_id": "source_warehouse_id",
+            "product_id": "product_id",
+            "quantity": "quantity"
+        },
+        "lockedFields": ["transfer_date", "source_warehouse_id", "product_id", "quantity"]
+    }
+}
+```
+
+| Param | Meaning |
+|---|---|
+| `register` | `module_cd.register_cd`. Do not combine with inline `registries`. |
+| `direction` | `increase` or `decrease`. Refused on `info`. `sign` decides per row instead. |
+| `dateField` | Document date stamped into `journalDate` or `period`. Required once the register declares either. Must be in `lockedFields`. `dateTrunc` (`day`/`month`/`year`) truncates it. |
+| `map` | Register name to column. A dimension left out binds to the column of the same name. Every required resource must be mapped. |
+| `lineEntity` + `lineField` | Post from lines: one movement per line. Declared per binding. Needs `lockedLineFields`. |
+| `headerMap` | On a line posting, register name to a **document** column. A resource may come from the document only on an `info` register. Every column must be in `lockedFields`. |
+| `groupLinesBy` | One movement per distinct value of these line columns. `map` is read over a group row; numeric resources are summed. |
+| `skipPostingWhenEmpty` | Dimensions whose emptiness means "this row posts nothing". The exception, see below. |
+| `lockedFields` / `lockedLineFields` | Columns frozen while posted. `["*"]` freezes the whole row. |
+| `movementMapping` | Journal attribute column to document or line column. |
+
+### `map` value forms
+
+| Form | Example | Notes |
+|---|---|---|
+| Column | `"qty"` | The default. |
+| One-hop path | `"product.product_group"` | Root is an `R` column with a `link`. The reference key column must be locked. Two hops refused. |
+| Expression | `"=COALESCE([transit_warehouse_id], [dest_warehouse_id])"` | Leading `=`, `F`-column formula, one-hop `[ref].[col]` reads. Every column read must be locked. |
+| Quoted constant | `"'1'"` | Stamped as is. A resource constant must be a number, outside `info`. |
+| Per-side object | `{ "debit": "dt_currency_cd", "credit": "ct_currency_cd" }` | `L` column only. For a resource or dimension the register splits by side. Both sides named. |
+
+The per-side object shape was missing from the entity schema until metadata 0.0.39. Validate with metadata 0.0.39 or later.
+
+Paths, expressions, `dateTrunc`, `headerMap`, `groupLinesBy` and `skipPostingWhenEmpty` are `A`-only. An `L` column refuses them.
+
+### `L` column (`acc-registry.gl_corr`)
+
+```json
+"params": {
+    "register": "acc-registry.gl_corr",
+    "lineEntity": "gl_corr_line",
+    "lineField": "gl_corr_entry_id",
+    "debitAccountField": "debit_account_id",
+    "creditAccountField": "credit_account_id",
+    "dateField": "entry_date",
+    "periodDimField": "period_key",
+    "map": {
+        "organization_id": "organization_id",
+        "currency_cd": { "debit": "dt_currency_cd", "credit": "ct_currency_cd" },
+        "amount": "amount",
+        "currency_amount": { "debit": "dt_currency_amount", "credit": "ct_currency_amount" }
+    },
+    "debitAnalytics": { "cost_center": "dt_cost_center_id" },
+    "creditAnalytics": { "counterparty": "ct_counterparty_id" },
+    "lockedFields": ["entry_date", "period_key"],
+    "lockedLineFields": ["*"]
+}
+```
+
+- Classic uses `accountField` and `analytics`. Compound uses `debitAccountField` + `creditAccountField` and `debitAnalytics` / `creditAnalytics`. Mixing them is refused.
+- `analytics` maps an analytic **kind** to a line column. The chart decides the slot per account, so one line column can land in `analytic1` on one account and `analytic2` on another.
+- `lineEntity` and `lineField` are required. `lockedLineFields` must cover every line column the posting copies, or be `["*"]`.
+- Every register dimension must be mapped, be a same-name line column, or be the `periodDimField` (a shared dimension).
+- `validation.balanced: ["amount"]` checks debits equal credits on classic. It is refused on compound, which balances by construction.
+
+## Reads
+
+| Read | Kinds | Returns |
+|---|---|---|
+| `getBalance(register, dims?, asOf?)` | `balance` | `{ resource: value }`, zeros when empty |
+| `getTurnover(register, dims, from, to)` | `balance`, `turnover` | `{ resource: { in, out, net } }` |
+| `getSlice(register, dims, onDate?, mode?)` | `info` | Record plus `_period`, or `null`. `mode` is `last` (default) or `first`. |
+| `getAccountBalance(register, account, filter?, asOf?)` | `accounting` | `{ resource: { debit, credit, net } }` |
+| `getAccountTurnover(register, account, filter, from, to)` | `accounting` | Same shape |
+| `getCorrespondence(register, debitAccount, creditAccount, filter, from, to)` | compound | Same shape |
+
+```
+execute:
+    var onHand = getBalance("wms-registry.stock", { warehouse_id: [warehouse_id], product_id: [product_id] })
+    var price = getSlice("wms-registry.outlet_price", { warehouse_id: [warehouse_id], product_id: [product_id] }, [order_date])
+```
+
+- A dimension left out is summed over by `getBalance` and `getTurnover`. `getSlice` refuses an omitted dimension.
+- As-of reads and `getTurnover` need a journal with both stamps.
+- A read of the wrong kind is refused, naming the right one.
+- DSL reads are gated by the action's Execute right, not Select on the register tables.
+- **Reports:** a dataset with `"datasetType": "R"` reads an accounting register over an interval. It returns one row per chart account with `opening_*`, `turnover_*` and `closing_*` debit and credit for one resource. See [`reports.md`](reports.md) and [`docs/business-logic/gl-ledger-to-declared-register.md`](../../../docs/business-logic/gl-ledger-to-declared-register.md).
+
+## Totals cache
+
+`totals` caches the turnover inside each `day`/`month`/`quarter`/`year`, never a closing balance, so a backdated posting touches one row. Declare an `entity` whose PRIMARY KEY is exactly (dimensions, `periodField`), with `inField`/`outField` per resource (`debitField`/`creditField` and an `accountField` on accounting). Posting maintains it; install rebuilds it when its shape changes. Not available on `info`. Details: registers.md section 8.4.
+
+## Common mistakes
+
+- **Undeclared or unqualified register.** `params.register` must be `module_cd.register_cd` and exist. Install fails, not the first posting.
+- **Unmapped required resource.** Map it, or mark the resource `"required": false` when only some writers supply it.
+- **Empty dimension.** An empty dimension refuses the posting. `skipPostingWhenEmpty` is the exception: it leaves a document posted while some lines moved nothing. Prefer one line table per binding. Use it only when the distinction lives in the data, such as a serial number filled on some rows.
+- **Missing or unlocked `dateField`.** Required once the register has `journalDate` or `period`, and it must be in `lockedFields`.
+- **Key over dimensions.** The journal, a subordinate `info` register's records and an `autoCreate` state table are written by the platform. Each needs **one** surrogate primary key of type `bigint` (`identity`/`cuid`) or `uuid`. A key over dimensions, a multi-column key, a text key and `int4` are refused.
+- **State column narrower than the journal column.** It must hold the journal's value exactly, or unposting cannot take back what posting added.
+- **Two resources from one document column**, or two resources storing into one register column. Refused.
+- **Binding to an independent `info` register.** Refused. Write it with `data.set`, or give it a `recorder`.
+- **Direct writes to register tables.** They are ordinary entities. Withhold `I`/`U`/`D` on state, journal and cache in the module's roles.
+- **`A`/`L` column in an `extends` entity.** An `A` column is allowed (a bridge posts another module's document; the state lives in the bridge's `_ext` table). An `L` column is allowed but not yet tested. See [`register-posting-from-extensions.md`](../../../docs/business-logic/register-posting-from-extensions.md).
+- **`mark-imported` is not `post`.** A document posted in another system is marked with `dforge-cli register mark-imported --entity <e> --state-column <col> --where "<sql>"`. Its state column stays false, and the engine refuses to post or unpost it. Do not set the flag by hand.
+- **Posting a mark-imported document, or unposting a receipt a later shipment consumed** (with `allowNegative: false`), is refused with `REGISTER_NEGATIVE_BALANCE` or an imported-document error.