@dforge-core/dforge-mcp 0.2.46-next → 0.2.48

package/skills/dforge-1c-import/scripts/lib/store.py

@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+"""
+The infobase as everything past the export sees it: `out/data/<table>.parquet`, one view
+per table, queried with DuckDB. Nothing here knows whether the export came from MS SQL or
+from a file infobase - `dump1c` made them the same - and nothing past here talks to 1C.
+
+    cur = store.connect().cursor()
+    cur.execute('SELECT "_IDRRef", "_EnumOrder" FROM "_Enum12"')
+
+The SQL is DuckDB's, so a project's `sources.QUERIES` are too: names in double quotes
+(DuckDB matches them without regard to case), `LIMIT` for `TOP`, `from_hex('..')` - see
+`literal` - for a binary constant. The values are as 1C stores them: a server infobase's
+dates still carry its year offset (`year_offset()`), a boolean is binary(1).
+
+The cursor takes parameters the way pyodbc did, `execute(sql, a, b)` or `execute(sql, [a, b])`,
+so the readers of the infobase kept their shape when they stopped reading MS SQL.
+"""
+import codecs
+import json
+import os
+
+import paths
+
+DATA = os.path.join(paths.OUT, "data")
+MANIFEST = os.path.join(paths.OUT, "export.json")
+
+# A boolean as 1C stores it, binary(1): `_Posted`, `_Marked`, `_Folder`.
+TRUE = b"\x01"
+
+_MANIFEST = []
+
+
+def manifest():
+	if not _MANIFEST:
+		if not os.path.exists(MANIFEST):
+			raise SystemExit("no export in %s - run `1c.py dump1c all` first" % paths.OUT)
+		with codecs.open(MANIFEST, "r", "utf-8") as f:
+			_MANIFEST.append(json.load(f))
+	return _MANIFEST[0]
+
+
+def year_offset():
+	"""What 1C adds to a year when it stores a date: 2000 on MS SQL as a rule, 0 in a file."""
+	return int(manifest().get("year_offset", 0))
+
+
+def source_kind():
+	return manifest()["source"]["kind"]
+
+
+def horizon():
+	"""The oldest horizon any exported table was read after, or None for a file export.
+
+	Every change 1C committed below it is in the export. One mark for the whole export
+	rather than one per table is the cautious reading: a declared query may join tables
+	read at different moments, and a mark too low only re-reads, never misses.
+	"""
+	marks = [t.get("horizon") for t in manifest()["tables"].values()]
+	if not marks or any(m is None for m in marks):
+		return None
+	return bytes.fromhex(min(marks))
+
+
+def literal(raw):
+	"""A binary constant in SQL - what `0x...` was in T-SQL."""
+	return "from_hex('%s')" % bytes(raw).hex()
+
+
+def quote(name):
+	return '"%s"' % name.replace('"', '""')
+
+
+class Cursor(object):
+	def __init__(self, con):
+		self.con = con
+
+	def execute(self, sql, *params):
+		if len(params) == 1 and isinstance(params[0], (list, tuple)):
+			params = params[0]
+		self.con.execute(sql, list(params))
+		return self
+
+	@property
+	def description(self):
+		return self.con.description
+
+	def fetchone(self):
+		return self.con.fetchone()
+
+	def fetchall(self):
+		return self.con.fetchall()
+
+	def fetchmany(self, size):
+		return self.con.fetchmany(size)
+
+
+class Database(object):
+	def __init__(self):
+		import duckdb
+		self.con = duckdb.connect()
+		# Spill under out/, and only so far. A query that loses its window - a LATERAL join
+		# DuckDB filters above rather than at the scan - reads all 99.8 M analytic rows and
+		# spilled 17 GB before it died, nearly the whole of the disk it shared with the system.
+		spill = os.path.join(paths.OUT, ".duckdb")
+		self.con.execute("SET temp_directory = '%s'" % spill.replace("\\", "/").replace("'", "''"))
+		self.con.execute("SET max_temp_directory_size = '%s'" % os.environ.get("DF1C_DUCKDB_TEMP", "8GB"))
+		tables = manifest()["tables"]
+		for name in sorted(tables):
+			path = os.path.join(DATA, name + ".parquet")
+			if os.path.exists(path):
+				self.con.execute("CREATE VIEW %s AS SELECT * FROM read_parquet('%s')"
+				                 % (quote(name), path.replace("\\", "/").replace("'", "''")))
+		self.tables = tables
+
+	def cursor(self):
+		return Cursor(self.con.cursor())
+
+
+_DB = []
+
+
+def connect():
+	"""One DuckDB per process; each cursor is its own connection to it."""
+	if not _DB:
+		_DB.append(Database())
+	return _DB[0]

package/skills/dforge-1c-import/scripts/lib/totals.py

@@ -50,6 +50,7 @@ import sys
 import time
 
 import migrate
+import transactions
 
 GRANULARITIES = ("day", "month", "quarter", "year")
 
@@ -334,8 +335,7 @@ def rebuild(pg, plan):
 
 	insert = ("INSERT INTO %s (%s) VALUES (%s)"
 	          % (plan.totals, ", ".join(key + cols), ", ".join(["%s"] * (len(key) + len(cols)))))
-	pg.autocommit = False
-	try:
+	with transactions.writing(pg):
 		for year in years:
 			cur.execute("SET LOCAL session_replication_role = 'replica'")
 			cur.execute("DELETE FROM %s WHERE %s >= %%s AND %s < %%s"
@@ -344,8 +344,6 @@ def rebuild(pg, plan):
 			if by_year.get(year):
 				cur.executemany(insert, by_year[year])
 			pg.commit()
-	finally:
-		pg.autocommit = True
 	print("%-28s %7d rows written over %d year(s)   checks %.0fs, fold %.0fs, write %.0fs"
 	      % (name(plan), len(rows), len(years), scanned - started, read - scanned,
 	         time.time() - read))

package/skills/dforge-1c-import/scripts/lib/transactions.py

@@ -0,0 +1,28 @@
+"""Transaction cleanup shared by the migration settlement writers."""
+from contextlib import contextmanager
+
+
+class ConnectionRecoveryError(RuntimeError):
+	"""The connection cannot safely be reused; abort rather than try another module."""
+
+
+def recover(pg):
+	"""Rollback before changing mode: psycopg2 forbids it in an active transaction."""
+	try:
+		pg.rollback()
+		pg.autocommit = True
+	except Exception as error:
+		raise ConnectionRecoveryError("cannot restore migration connection: %s" % error) from error
+
+
+@contextmanager
+def writing(pg):
+	"""Writers commit explicitly; on any failure, rollback before restoring autocommit."""
+	pg.autocommit = False
+	try:
+		yield
+	except BaseException:
+		recover(pg)
+		raise
+	else:
+		pg.autocommit = True

package/skills/dforge-1c-import/scripts/project-template/.env.example

@@ -0,0 +1,24 @@
+# Copy to <port root>/.env and fill in. `.env` never goes into a commit.
+#
+# None of these has a default, deliberately: a default naming one infobase would make the
+# toolkit quietly read or write that infobase whenever a variable was forgotten.
+
+# DF1C_ROOT and DF1C_PROJECT are exported in the shell, not set here: this file is found
+# through DF1C_ROOT (<root>/.env), so it cannot say where the root is.
+
+# The infobase, read-only: a server infobase on MS SQL (with DF1C_USER empty, Windows
+# authentication is used) ...
+DF1C_SERVER=
+DF1C_DB=
+DF1C_USER=
+DF1C_PASS=
+# ... or a file infobase: the 1Cv8.1CD, or the folder holding it. Set this or the four above.
+# Point it at a copy, or close the infobase first.
+DF1C_FILE=
+
+# The dForge tenant and its Postgres, for loading and checks
+DF_TENANT=
+DF_PG_HOST=localhost
+DF_PG_PORT=
+DF_PG_USER=
+DF_PG_PASS=

package/skills/dforge-1c-import/scripts/project-template/sources.py

@@ -6,6 +6,16 @@ records each column's 1C source as it emits the column. These four names exist b
 `binding.py` requires them; they stay empty for as long as no module here is written by
 hand. If one ever is, this is where its columns say where they came from - see
 `tools/project/sources.py` for the shape.
+
+A query in QUERIES runs on the export (`lib/store.py`), so it is DuckDB SQL, not T-SQL:
+`"_Fld123"` rather than `[_Fld123]`, `LIMIT` rather than `TOP`, `from_hex('01')` rather
+than `0x01`.
+
+Put a `/*window:<alias>*/` marker in the WHERE of the scan it narrows, and do not turn
+T-SQL's CROSS APPLY into a LATERAL join: DuckDB applies a filter written above a LATERAL
+after the join, so a query narrowed to one recorder still reads every analytic row - on
+99.8 M it ran out of memory and spilled 17 GB. A nested SELECT over the table, with the
+marker in its own WHERE, ran in under a second. Spill is capped at DF1C_DUCKDB_TEMP (8GB).
 """
 
 ENUMS = {}

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

@@ -117,53 +117,54 @@ Two consequences worth designing around:
 - **`canExecute: false` is the idiom for an action only automation may fire.** The
   server refuses it through `action.execute`; triggers and scheduled jobs invoke
   the script engine directly and are unaffected.
-- **Both evaluators have gaps, and both fail open.** The server is a scalar walker
-  — comparisons between fields and literals, combined with `AND` / `OR` / `NOT`,
-  nothing else — and lets anything richer through. The client implements the full documented formula
-  function set, so ordinary functions are fine there; it throws (and its `catch`
-  **enables** the button) on **ref navigation** (`[ref].target`), on the set
-  aggregates **`SUM` / `COUNT` / `AVG`** (deliberately not formula functions —
-  counting is a Generated `G` column's job), and on **any name it does not know, a
-  typo included** — a `canExecute` is never validated against the function set at
-  install, so `TOADY()` ships and enables the button for every record.
-- **`$[setting]` references are a separate case.** They do not throw: the client's
-  resolver is stubbed to `null`, so the predicate resolves however that operator
-  treats null (an ordered comparison against null is `false`, so it tends to
-  *disable* the button), while the server has no settings resolver and fails open.
-  Keep settings out of `canExecute` and read them in `execute:` instead.
-
-| tier | construct | client | server |
-|---|---|---|---|
-| 1 | **comparisons** (`=` `!=` `<` `<=` `>` `>=`) between fields and literals, combined with `AND` / `OR` / `NOT`; a bare `true` / `false` | evaluates | **enforces** |
-| 2 | arithmetic, `IN`, `BETWEEN`, any formula function | evaluates | fail-open |
-| 3 | ref navigation, `SUM` / `COUNT` / `AVG`, any unknown function (a typo included) | **fail-open (throws)** | fail-open |
-| — | `$[setting]` references | **evaluates as null** (no throw) | fail-open |
-
-**A bare boolean column is not tier 1.** The walker evaluates conditions, not
-values — a field is only resolvable as an operand of a comparison — so
-`canExecute: [is_active]` and `canExecute: NOT [is_blocked]` fail open. Write
-`[is_active] = true` and `NOT ([is_blocked] = true)`. (`canExecute: false` is fine:
-a bare literal is a complete condition.)
-
-Mixing tier 1 and tier 2 is the normal, healthy shape: the client evaluates the
-whole thing so the button state is right, and the server short-circuits `AND` /
-`OR` so the tier-1 half is still enforced.
-
-**Tier 3 is what breaks.** The server short-circuits, the client does not — so
-`[status] = 'Pending' AND COUNT([lines]) > 0` on a non-`Pending` record still
-evaluates `COUNT` in the browser, throws, and the button is **enabled**, then the
-server refuses the call: an error where a greyed-out button was wanted. And a
-`canExecute` is not validated against the function set at install, so that spelling
-ships silently. Count with a `G` column and compare the scalar
-(`[detail_count] > 0`); denormalise instead of navigating; put anything genuinely
-unexpressible in `execute:` behind `error()`.
+- **The server evaluates the whole formula, and refuses what it cannot read.**
+  (Needs platform 1.28.12; older platforms let these through, so the gate is not enforced there.)
+  Comparisons between fields and literals (with `AND` / `OR` / `NOT`, a bare
+  `true` / `false`) are checked in-process; anything richer — arithmetic, `IN`,
+  `BETWEEN`, formula functions, a bare boolean field, `[ref].[col]`
+  navigation — is computed in SQL over the record, by the same translator as formula
+  columns (chained hops are followed up to a depth cap; a null ref gives `NULL`, which
+  counts as not true). A condition the server cannot evaluate (`$[setting]` references, set
+  aggregates `SUM` / `COUNT` / `AVG`, an unknown function name, a typo included)
+  **refuses the action** with `ACTION_EXECUTION_FAIL` ("cannot be evaluated by the
+  server") instead of allowing it. A `NULL` result counts as not true.
+  Comparisons themselves are null-safe and two-valued (see `formulas.md`), so an empty
+  field does not make `NOT ([x] = 'A')` unknown.
+- **The client has gaps of its own, and its failures enable the button.** It
+  throws (and its `catch` **enables** the button) on **ref navigation**
+  (`[ref].target`), on **`SUM` / `COUNT` / `AVG`** (deliberately not formula
+  functions — counting is a Generated `G` column's job) and on **any name it does
+  not know, a typo included** (install refuses the last two, see below).
+- **`$[setting]` references** resolve to `null` in the client (an ordered comparison
+  against null is `false`, so it tends to *disable* the button) and are refused by
+  the server and at install (platform 1.28.12 and later). Keep settings out of `canExecute` and read them in `execute:` instead.
+- **`TODAY()`** names the requester's calendar day on the server too (their time
+  zone: the request's, else the user profile's, else the workspace's, else UTC; a profile zone of
+  `UTC` counts as unset). The button is evaluated in the browser and is meant to name the same
+  day; `execute:` stays the authority.
+- **Install refuses** a `canExecute` that uses `$[setting]`, `SUM` / `COUNT` / `AVG`
+  or an unknown function name (a typo included), since the server could never run
+  the action. Read settings and count children in `execute:` instead.
+
+| construct | client | server |
+|---|---|---|
+| comparisons between fields and literals, `AND` / `OR` / `NOT`, bare `true` / `false` | evaluates | evaluates |
+| arithmetic, `IN`, `BETWEEN`, formula functions, bare boolean field | evaluates | evaluates (SQL) |
+| `[ref].[col]` navigation | **throws, button enabled** | evaluates (SQL) |
+| `SUM` / `COUNT` / `AVG`, unknown function (a typo included) | **throws, button enabled** | **refused at install**; if one is already installed, `action.execute` refuses it |
+| `$[setting]` references | evaluates as null | **refused at install**; if already installed, `action.execute` refuses it |
+
+Both evaluators agreeing is the healthy shape; the one to design around is a
+construct the client throws on, which leaves a button that is enabled and then
+refused. Count with a `G` column and compare the scalar (`[detail_count] > 0`);
+denormalise instead of navigating; put anything genuinely unexpressible in
+`execute:` behind `error()`.
 
 > Never make `canExecute` the *only* guard for something that must hold. Between
-> the fail-open rules on both sides, the enqueue-only check on background runs, and
-> the fact that the client evaluates over the grid row (which does not carry
-> extension columns) while the server evaluates over a full record load, the
-> authoritative check belongs in `execute:` — validate and `error()` before the
-> first write.
+> the enqueue-only check on background runs and the fact that the client evaluates
+> over the grid row (which does not carry extension columns) while the server
+> evaluates over a full record load, the authoritative check belongs in
+> `execute:` — validate and `error()` before the first write.
 
 ```
 canExecute:
@@ -226,6 +227,8 @@ var note = params[note]             // no quotes around param name in this DSL
 
 ### Data operations
 
+**No entity rights are checked inside a script.** `insert()`, `update()`, `delete()` and `query()` do not look at the signed-in user's `S`/`I`/`U`/`D` on the entity, nor at column security or the folder's row filter. Only `E` on the action is checked, when it is run. A user with `S` only on an entity can still change it through an action they may execute (core #1580). Treat `E` on an action as write access to everything its script touches; to keep a log free of changes, grant `E` on no action that writes to it.
+
 | Function | Returns | Description |
 |---|---|---|
 | `insert('entity', { field: value, … })` | Inserted row object | Insert a new record. Returns the full row including auto-filled columns (PK, audit, number sequences). Access returned fields with `result.field_name`. |
@@ -359,7 +362,7 @@ error('Insufficient stock. Available: {available}, requested: {requested}',
 
 | Function | Returns | Description |
 |---|---|---|
-| `printPdf('module.entity', key, templateCd)` | `{ fileId, fileName, mimeType, size, checksum }` | Render a print template to a PDF **as the current user** (the record is read under their rights and the folder's row filter) and archive it. A descriptor, never the bytes: attach it with `sendEmail()`. Always pass a qualified entity code. Not available in a scheduled job or a background action, refused in a computing-only run, max 10 per run; each render holds the action's transaction open. |
+| `printPdf('module.entity', key, templateCd)` | `{ fileId, fileName, mimeType, size, checksum }`, plus `warnings` when a value printed empty because the user may not read it | Render a print template to a PDF **as the current user** (the record is read under their rights and the folder's row filter) and archive it. A descriptor, never the bytes: attach it with `sendEmail()`. Always pass a qualified entity code. Not available in a scheduled job or a background action, refused in a computing-only run, max 10 per run; each render holds the action's transaction open. |
 | `downloadText(content, fileName, encoding?, mimeType?)` | URL string | Hand the user a text file the script built. `encoding` is `utf-8` by default; `windows-1251`, `cp866`, `koi8-u` and other code pages work, and a character the encoding cannot represent is an error. Line endings are written as given (join with `'\r\n'` for CR LF), no BOM. Returns the signed download URL (valid an hour). An action has one download: a later call replaces the earlier. In a background or scheduled run nobody receives it, so pass the URL on in `notify()`. Max 10 MB per file, 10 files per run. |
 | `attachText(content, fileName, encoding?, mimeType?)` | descriptor | Build a text file for `sendEmail()`'s fourth argument, keeping its `mimeType` (e.g. an `.ics` as `text/calendar`). Same encodings as `downloadText()`; max 10 MB per file, 10 files per run shared with the download functions. Works in a scheduled job. |
 | `attachBase64(base64, fileName, mimeType?)` | descriptor | `attachText()` for bytes. |

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

@@ -118,8 +118,8 @@ See [flags.md](flags.md) for the flag string, [column-types.md](column-types.md)
 
 | `viewType` | Description | `viewConfig` | When to use |
 |---|---|---|---|
-| `grid` | Spreadsheet-style table with sortable columns | — | Default for most entities; bulk data |
-| `list` | Compact list view | — | Mobile-friendly, card-sized items |
+| `grid` | Spreadsheet-style table with sortable columns | `groupByField`, `groupByOptions`, `collapsedGroups` (all optional) | Default for most entities; bulk data |
+| `list` | Compact list view | `groupByField`, `groupByOptions`, `collapsedGroups`, `inlineAdd`, `levels` (all optional) | Mobile-friendly, card-sized items |
 | `kanban` | Columns grouped by a status field | `groupByField` | Workflow entities with stages (deals, tickets) |
 | `gallery` | Image-forward card grid | — | Image-heavy entities (products, real estate) |
 | `tree-grid` | Hierarchical grid with expand/collapse | — | Tree structures (folders, categories, org charts) |
@@ -151,6 +151,42 @@ Some view types need additional configuration via the `viewConfig` property:
 
 `groupByField` — the dropdown/status column to group cards by. Each distinct value becomes a kanban column.
 
+### Grid and list grouping
+
+A `grid` or `list` view can ship a default grouping. Rows split under a header per value (colour or icon, label, count),
+and a header click folds its group away. Every key is optional; without them the view is ungrouped.
+
+```json
+{
+    "tickets_grid": {
+        "viewType": "grid",
+        "label": "Tickets",
+        "dataSources": [{
+            "entityCode": "ticket",
+            "columns": ["subject", "status", "priority", "assignee_id"]
+        }],
+        "viewConfig": {
+            "groupByField": "status",
+            "groupByOptions": ["status", "priority", "assignee_id"],
+            "collapsedGroups": ["closed"]
+        }
+    }
+}
+```
+
+- `groupByField`: the column the rows are grouped by. It must be a dropdown, flags, reference (`columnType: "R"`) or
+  `user` column.
+- `groupByOptions`: the columns the Group menu offers. Each follows the same rule, and the list must include
+  `groupByField`. Leave it out to offer every groupable column.
+- `collapsedGroups`: values of `groupByField` whose groups start folded. It needs a valid `groupByField`, and for a
+  dropdown each entry must be one of its option values.
+- `inlineAdd` (`list` only): an add row in each group, or at the top when ungrouped.
+
+The install refuses a view that breaks these rules, and `dforge_module_validate` reports it first. The default is a
+single level. A user can stack more levels (priority, then status) from the gear menu; that choice lives in their
+session, not in the module. A grouped grid loads up to 2,000 rows instead of paging and warns past that. Needs platform
+1.28.11.
+
 ### Calendar
 
 ```json

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

@@ -11,11 +11,12 @@ Formulas are used in:
   `F` column otherwise: it must parse, call only implemented functions, and not
   aggregate over a 1:N set. See `security.md` → Column-level security.
 - **Action `canExecute:` blocks** — availability checks. Evaluated on both sides
-  and **enforced** by `action.execute`, but only over a narrow subset: comparisons
-  between fields and literals combined with `AND` / `OR` / `NOT`. Functions,
-  arithmetic, ref navigation, `$[setting]` reads and a bare boolean field all fail
-  open server-side, and some of them throw client-side. See the `canExecute:`
-  section in [action-dsl.md](action-dsl.md).
+  and **enforced** by `action.execute`: the server computes the whole formula
+  (functions, arithmetic, navigation included) and **refuses** the call when
+  it cannot read it (`$[setting]` reads, `SUM` / `COUNT` / `AVG`, unknown
+  functions). The client throws on navigation, set aggregates and unknown names,
+  which leaves the button enabled. See the `canExecute:` section in
+  [action-dsl.md](action-dsl.md).
 - **Default values** — a setting's `formula` (e.g. `"formula": "TODAY()"`) or a formula (`F`) column. Note: entity *data* columns have **no** `default`/`defaultValue` key — model a default with an `F` column or set it in action/trigger logic.
 - **Filter expressions** (partially)
 - **Validation expressions** (partially)
@@ -142,11 +143,42 @@ The whole date family evaluates identically **client-side and SQL-time** (report
   `'bool'`/`'boolean'`, `'date'`, `'datetime'`/`'timestamp'`/`'timestamptz'`
 - `CURRENT_USER_ID()` — the id of the requesting user
 
+### Register functions
+
+- `SLICE('module.register', 'resource', date, 'dimension', value, …)` — an information
+  register's value in effect on `date` (1C `СрезПоследних`): the resource of the newest record
+  at or before the date whose dimensions equal the values, null when none is. The register,
+  resource and dimension names are text literals; the date and the values are expressions over
+  the row, so a document line reads its price on its document's date:
+  `SLICE('pricing.item_price', 'price', [doc].[doc_date], 'item_id', [item_id], 'price_type_id', [doc].[price_type_id])`.
+  Every dimension must be given; a register without `period` takes `null` as the date.
+  - **Computed by the database only** — in a print form, a report, and `data.get` naming the
+    column. The browser does not recompute it on edit; it keeps the value the server loaded.
+  - Read with the user's rights on the register's records: Select in the folder, the folder's
+    row filter, the resource and every dimension column visible in the folder's view. Otherwise
+    the cell is empty and the response carries a warning. That includes a row filter over the
+    records that cannot be applied (a dotted path or an extension column): the `SLICE()` comes
+    back empty with a warning instead of failing the whole query.
+  - Install refuses a register that is not an `info` register of this module or of a
+    dependency (a register of another kind "has no slice"), an unknown resource or dimension, a
+    missing dimension, and a literal `null` as a dimension value or as the date of a register
+    that declares a `period` (it matches no record). A `null` that only appears at runtime, such
+    as a line with an empty price type, still gives an empty cell, with no warning.
+    `dforge_module_validate` and `dforge_module_pack` (the CLI's static checks) catch only a
+    malformed call, such as a name that is not a text literal or a dimension without its value;
+    whether the register, resource and dimensions exist is known at install.
+  - Refused at install in a `G` column: it is computed when a row is written and would not
+    follow a record added to the register later. Use an `F` column.
+  - Newest record only: there is no `first` mode as `getSlice` has. Each row is one index
+    descent of the register's `(dimensions, period)` index, which the platform creates.
+  - The date is compared as `period <= date`: against a `timestamp` period, a date-only
+    document date is midnight, so a record later that day is not in the slice.
+
 ### Client-side vs SQL-time evaluation
 
 An `F` column is evaluated **client-side** in grids and cards, but translated to **SQL** when a
 report selects it, or when it is used in a filter or sort. **Every function listed here is
-implemented in both**, so a column reads the same in a grid and in a report; a test executes
+implemented in both** — except `SLICE()`, which only the database computes — so a column reads the same in a grid and in a report; a test executes
 each one against PostgreSQL and diffs the result against the client runtime.
 
 Four deliberate points of agreement, because the engines disagree by nature:

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

@@ -33,7 +33,7 @@ Lives in: `logic/jobs.json` at the module root. Schema: [`docs/schemas/jobs.sche
 | `timeout`        | Yes      |              | Hard timeout in seconds. Range `(0, 3600]`. **No implicit default.** `timeout > 300` requires `class: "long_running"`.               |
 | `class`          | No       | `"standard"` | `"standard"` (≤ 300 s) or `"long_running"` (≤ 3600 s). Explicit opt-in for heavy jobs.                                               |
 | `concurrency`    | No       | `1`          | Max parallel runs `[1, 5]`. `1` = single-instance.                                                                                   |
-| `idempotencyKey` | No       |              | Template like `"{job_cd}:{run.month}"`. Successful run with same key blocks re-dispatch.                                             |
+| `idempotencyKey` | No       |              | **Not enforced yet.** Accepted and stored; the Scheduler does not read it. Scheduled slots deduplicate `(job, scheduled_at)`, not business keys across slots. Guard business idempotency inside the action; manual triggers skip the slot check.                                             |
 | `timeZone`       | No       | tenant tz    | IANA name. Falls back to `auth.tenant.time_zone`.                                                                                    |
 | `params`         | No       | `{}`         | Static parameters passed to the action as `__params`. Manifest-fixed — an admin cannot change them. For tenant-configurable values use module settings, resolved from the job's folder (below).       |
 | `enabled`        | No       | `true`       | `false` fully disables — no scheduler, no manual trigger.                                                                            |

package/skills/dforge-mcp-author/references/print-templates.md

@@ -73,7 +73,9 @@ A printed set, nested or not, needs **Select** on its entity in the folder, as `
 
 A currency column prints its glyph for the common codes (`EUR` → `€`, `USD` → `$`, `GBP` → `£`, `UAH` → `₴`, `PLN` → `zł`); other codes print as the code. `format_currency` follows the same mapping.
 
-Formula columns (`F`) are read in the same SQL as the record, as `data.get` does, so a formula that navigates references or calls a SQL function prints what the grid shows, and `TODAY()` / `NOW()` work. A formula the SQL translator cannot express prints empty and the response carries a warning naming the column.
+Formula columns (`F`) are read in the same SQL as the record, as `data.get` does, so a formula that navigates references prints what the grid shows, and `TODAY()` / `NOW()` work. A formula uses the built-in formula functions only: it cannot call a module's SQL function. A formula the SQL translator cannot express, or one reading what the user may not read, prints empty, and `print.render` / `print.renderPdf` return it in `warnings` (a line column's prefixed with its set's name); the card's PDF button shows them.
+
+A value that changes over time — a price, an employee's position, an organization's code — lives in an information register: print it as it stood on the document's date with a `SLICE()` formula column on the line or the document (see formulas.md). Each line reads its own value in the query that loads the set.
 
 **Sets: loading and order.** A set is loaded when the template's Liquid code (`{% … %}` or `{{ … }}`) mentions its name anywhere: a `for`, a filter, a condition, `.size`, `.first`. Plain text, `{% comment %}` / `{% raw %}` blocks, string literals and the member of a path (`rec.lines`) do not count, and a snippet's code is not scanned (mention the set in the host template). Rows come in primary-key order; sort in the template:
 
@@ -85,6 +87,21 @@ Formula columns (`F`) are read in the same SQL as the record, as `data.get` does
 
 `sort` takes a column code and sorts the value as the template sees it (a dropdown or reference sorts by its label). Text order follows the engine, not the database collation. `{# … #}` after an expression in examples is a note for the reader, not syntax: write a real comment as `{% comment %} … {% endcomment %}`.
 
+## Computed values and grouped rows
+
+| The form needs | Do |
+| --- | --- |
+| A value of the record or of a record it references (the organization's requisites as one block) | An `F` column on the entity: references and built-in functions |
+| A value per line (places, weight through the product's units) | An `F` column on the line entity, printed as `line.<col>` |
+| One total over a set | Over a stored line column (`D`, or a `G` on the line): a `G` column on the document (`SUM([lines].[amount])`). Over a line `F` column: a `plus` accumulator in the loop, `{% assign s = 0 %}{% for l in lines %}{% assign s = s \| plus: l.places %}{% endfor %}`, since a `G` cannot sum an `F` child (install fails with `column old.<field> does not exist`) |
+| Lines grouped by a column, totals per group (by product and series, by VAT rate, a packing list by pallet) | **Not available in the print context yet.** It prints the record and its sets as stored |
+
+For the last row, do not work around it:
+
+- **Not in Liquid filters.** `where`, `sum`, `group_by` and `where_exp` run in the LiquidJS preview, but Scriban (the print) fails with "The function `where` was not found". Filter and total with `{% if %}` and `plus` inside a `for`, which both engines run.
+- **Not a print table filled by an action.** It stores a copy of the document that drifts from it.
+- **Not a stored procedure.** The grouping itself is a grouped query (`references/queries.md`): `group` on the column, `sum` over a line `F` column.
+
 ## Custom filters
 
 | Filter                                          | Example                                                | Output                       |
@@ -113,7 +130,7 @@ Full mechanics + an EPC SEPA QR worked example: [`docs/ui/print-qr-codes.md`](..
 
 ### Amount in words
 
-The platform has no number-to-words filter. The `common-words` module (`modules/common-words`, a dependency to declare) ships snippets that write an amount or a plain quantity out in Ukrainian, English or German. Set the inputs, then include:
+The platform has no number-to-words filter. The `common-words` module (`modules/common-words`, a dependency to declare) ships snippets that write an amount or a plain quantity out in Ukrainian, Russian, English or German. Set the inputs, then include:
 
 ```liquid
 {% assign words_amount = total %}
@@ -122,9 +139,17 @@ The platform has no number-to-words filter. The `common-words` module (`modules/
 {% include 'common-words.money' %}
 ```
 
-1234.56 EUR prints «eintausendzweihundertvierunddreißig Euro 56 Cent». `words_amount` must be a numeric field, not text. `words_currency` is an ISO 4217 code in any case; an unlisted currency prints its code. `words_lang` is `uk` (default), `en` or `de`; an unknown code prints `[common-words: unknown language xx]`. `words_cap = true` capitalises the first letter. `common-words.money` only picks the language; `money_uk` / `money_en` / `money_de` can be included directly, and `common-words.quantity` writes a count of things («двадцять одна штука», «twenty-one pieces»): `words_number` (numeric, a fraction rounds half up), optional `words_unit` (forms joined by `|`: three for Ukrainian, two for English and German) and `words_gender` (`m` / `f` / `n`), plus `words_lang` and `words_cap` as above. The text lives in the module, so a fix or a new currency is a module update; a new language is a new `money_xx.html` plus a line in `money.html`.
+1234.56 EUR prints «eintausendzweihundertvierunddreißig Euro 56 Cent». `words_amount` must be a numeric field, not text. `words_currency` is an ISO 4217 code in any case; an unlisted currency prints its code. `words_lang` is `uk` (default), `ru`, `en` or `de`; an unknown code prints `[common-words: unknown language xx]`. `words_cap = true` capitalises the first letter. `common-words.money` only picks the language; `money_uk` / `money_ru` / `money_en` / `money_de` can be included directly, and `common-words.quantity` writes a count of things («двадцять одна штука», «twenty-one pieces»): `words_number` (numeric, a fraction rounds half up), optional `words_unit` (forms joined by `|`: three for Ukrainian and Russian, two for English and German) and `words_gender` (`m` / `f` / `n`), plus `words_lang` and `words_cap` as above; `quantity_uk` / `quantity_ru` can be included directly too. The text lives in the module, so a fix or a new currency is a module update; a new language is a new `money_xx.html` plus a line in `money.html`.
+
+`quantity_uk` and `quantity_ru` also write a fraction in words. With `words_minor` + `words_minor_digits` (1–6) the fraction gets its own unit, as 1C's ЧислоПрописью does for a weight: «одна тысяча двести пятьдесят кг. пятьсот г.» (a zero fraction prints «ноль г.»). With `words_decimal = true` the number is a decimal fraction up to three digits, trailing zeros dropped: «двадцять одна ціла дванадцять сотих тонни». The unit comes in the 2–4 form, or as `words_unit_fraction` ('кілограма' for a Ukrainian masculine unit). The grammar is correct where 1C's is not: 1.001 is «одна ціла одна тисячна». English and German take neither input.
+
+Snippets run on Scriban (print) and LiquidJS (preview), so write them for both:
 
-Snippets run on Scriban (print) and LiquidJS (preview), so write them for both: no `floor` on big numbers, no number taken from `split` / `slice`, plain `{% comment %}` without trim dashes.
+- No `floor` on big numbers: Scriban's goes through a double and rounds them up.
+- No `modulo: 1` on a fraction without snapping the whole part with `round`. LiquidJS 10.30 leaves float noise: `0.44 | modulo: 1` is 0.43999999999999995.
+- Round a fraction half up on its decimal digits, read from the number's text (`append: ''`; the server may print a comma; a browser double under 1e-6 prints as `5e-7`), never by `times` / `plus: 0.5` / `floor`. A double's text is the shortest decimal it stands for, so this matches the server's decimals both on a tie (960.015 → 02) and just below one (1000000000.0049999 → 00). No epsilon can do both.
+- No number taken from `split` / `slice`. A digit is read as `'x0123456789' | split: ch | first | size | minus: 1`.
+- Plain `{% comment %}` without trim dashes.
 
 ## Module package layout
 
@@ -187,7 +212,7 @@ my_module/
 - **Writing an amount in words by hand.** Include `common-words.money` instead of a custom filter or lookup table.
 - **Module-installed template renamed in editor.** The editor preserves the original `template_cd` so `{% include %}` references stay intact — don't try to work around it.
 
-Module-installed print-template rows can't be deleted from the editor — uninstall the owning module to remove them.
+Module-installed print-template rows can't be deleted from the editor. A template or snippet the package no longer declares is deleted on upgrade (dropped from `print_templates.json`, moved to another entity, or the file gone entirely); tenant-authored rows are never touched. To retire a template, remove it from the package, and remove or repoint any scheduled print subscription that names it: nothing references a template by key, so the subscription is not blocked, and its next run fails and suspends it.
 
 ## Reference
 

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

@@ -12,7 +12,8 @@ Lives in: `ui/queries.json`
 | Simple aggregation — "totals by X" | **Pre-built query** (`ui/queries.json`) |
 | Ad-hoc exploration by the user | **Query Builder** (runtime, no module authoring needed) |
 | Complex multi-dataset visualizations with charts/KPIs | **Report** (`ui/reports.json`) |
-| Full SQL with window functions, CTEs, cross-schema | **Report with stored procedure** |
+| Totals grouped by a reference, or summing a value computed per row (lines by product, totals by VAT rate) | **Pre-built query**: `group` on the reference, `sum` over an `F` column of the entity (see *Calculated columns*) |
+| Full SQL with window functions, CTEs, cross-schema, or a formula over an aggregate (`CEIL(SUM(qty) / box)`) | **Report with stored procedure** |
 
 Queries fill the gap between views (flat, no aggregation) and reports (heavy, need layout config).
 
@@ -131,6 +132,17 @@ Columns can traverse references up to 2 levels deep:
 
 The query engine automatically JOINs the referenced entities.
 
+A reference path can be grouped or aggregated like any column: `{ "c": "product.unit", "agg": "group" }`.
+
+### Calculated columns
+
+A value computed per row is aggregated in two ways:
+
+- **An `F` column of the entity**, named by its code: `{ "c": "places", "agg": "sum" }`. Its formula may navigate references (`[qty] / [product].[box_qty]`). This is the way for anything that reads another entity.
+- **An ad-hoc formula** in the query: `{ "formula": "[qty] * [price]", "agg": "sum", "alias": "amount" }`. It reads the root entity's own columns only: a navigation path fails the request.
+
+The aggregate is applied to the row value, `SUM(formula)`. A formula over the aggregate (`SUM([a]) / COUNT([a])`, `CEIL(SUM([qty]) / [box_qty])`) is not expressible: in grouped mode a column without `agg` is dropped, and `SUM` / `COUNT` are not formula functions. That needs a stored procedure. The query is grouped when at least one column, plain or formula, has `agg: "group"`; there is no `grouping` switch. Aggregates without a `group` column are not a grand total: the request runs as an ungrouped row query and the aggregates are ignored, with no error.
+
 ### Filters
 
 Filters use the standard JSON filter format (see `references/filters.md`): `{ "c": column, "o": operator, "v": value }`.
@@ -306,7 +318,10 @@ Query names and descriptions are translated in each non-English `translations/<l
 
 - Putting SQL in the `query` object — **wrong**. Queries use the JSON format, not raw SQL. For raw SQL, use stored procedures in reports.
 - Using `"column"` instead of `"c"` in columns/filters — **wrong**. Use the short keys.
-- Forgetting `"agg"` on columns in grouped mode — every column needs an aggregation assignment.
+- Forgetting `"agg"` on columns in grouped mode — a column without one is dropped from the result.
+- Only aggregates, no `group` column, expecting one total row — **runs ungrouped**, the aggregates ignored and no error. Group by a constant-valued column, or total in a `G` column or a report.
+- Writing a stored procedure to group lines and sum them — **wrong tool**. Grouping by a reference and summing an `F` column is a grouped query, and it runs under the user's entity, column and row-level security, which a stored procedure bypasses. Reach for SQL only for what the JSON cannot say (a formula over an aggregate, window functions, CTEs).
+- Navigating a reference inside an ad-hoc `formula` (`[product].[box_qty]`) — **fails**. Declare an `F` column on the entity and aggregate it by code.
 - Referencing columns from unrelated entities — queries can only traverse the root entity's references.
 - Using `@TODAY`, `@CURRENT_USER`, or any `@placeholder` syntax in filter values — **wrong**. Queries do not support parameter substitution. Use the function operator instead: `{ "c": "due_date", "o": "f", "v": { "fn": "isPast" } }`.
 - Using a function as the value of a comparison operator (`<`, `>`, `=`, `!=`, `between`) — **wrong**. Functions are standalone conditions, valid only with `"o": "f"` (full detail + examples under "Dynamic date and user filters" above). `{ "c": "due_date", "o": "<", "v": { "fn": "isToday" } }` is invalid; use `{ "c": "due_date", "o": "f", "v": { "fn": "isPast" } }`.