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

package/CHANGELOG.md

@@ -6,16 +6,83 @@ the release workflow, so committed `package.json` versions are placeholders.
 
 ## Unreleased
 
+**1C migration readiness and regressions.** `delta --apply` now reports per-module
+`ready` / `partial` status and exits 2 if state, totals or imported markers remain
+unsettled; retained retry markers are settled on a later run even without new rows.
+Dry runs do not certify readiness. `pnpm test:1c` covers conversion precision,
+reference/date semantics, failed settlement/retry and the per-entity reload restart
+contract using synthetic fixtures and mocked database boundaries. The loader remains
+a non-atomic migration-target reload; its restart procedure is documented.
+A new CI job (`.github/workflows/onec-tests.yml`) runs it on changes to the 1C scripts or tests. A module's retry
+markers (`df1c.unsettled`) are now cleared only for the entities it settled, not for the whole module.
+Placeholder, balance-state and yearly totals writers roll back failed transactions before
+restoring autocommit; settlement continues to the next module only after connection
+recovery, and failed recovery stops the command. Strict transaction-state tests cover
+original-error preservation, partial yearly commits, continuation and unrecoverable connections.
+Jobs authoring/schema guidance now describes `idempotencyKey` as reserved and not enforced.
+
+**Action scripts bypass entity rights.** `action-dsl.md` and `security.md` now state that `insert()` / `update()` /
+`delete()` / `query()` in an action script check neither entity rights nor column security nor the folder's row filter
+(core #1580): only `E` on the action is checked, so treat `E` as write access to everything the script touches.
+
+**`canExecute` is enforced in full on the server.** `action.execute` now computes arithmetic, `IN`, `BETWEEN`, formula
+functions, a bare boolean column, `[ref].[col]` navigation and extension columns in SQL, instead of letting them through, and
+`TODAY()` names the requester's day. A condition it cannot compute refuses the action. Install rejects `$[setting]`,
+`SUM` / `COUNT` / `AVG` and unknown function names in `canExecute`, so a module that used them stops installing: read
+settings and count children in `execute:` instead (a count belongs in a `G` column). `references/action-dsl.md`
+(`canExecute:`), `formulas.md` and `validation-checklist.md` are rewritten to match. The button still evaluates over the
+grid row, which has no extension columns and throws on `[ref].[col]`, so keep both out of a gate that must also disable the
+button. **Needs platform 1.28.12.**
+
+**Registers: `postAction` / `unpostAction`.** `references/registers.md` documents the register-binding column params that make a direct
+`data.insert` / `data.update` flipping the state flag need `E` on the post or unpost action, and the "May edit is not may
+post" pitfall: declare both and grant `E` only to the roles that may post. Each direction is checked only when its own key
+is set; actions and DSL `update()` are not re-checked. A binding with neither gets a pack / validate warning, silenced by
+`"editorMayPost": true`. **Needs a platform release after 1.28.12 (not in it).**
+
+## 0.2.46 — 2026-10-29
+
+Requires `@dforge-core/dforge-cli` 0.2.37 and `@dforge-core/metadata` 0.0.47; the vendored `dforge://schema/data-views` now accepts the grouping keys.
+
+**`SLICE()`: an information register's value on a date, per row.** A formula function for `F` columns —
+`SLICE('module.register', 'resource', date, 'dimension', value, …)`, 1C's `СрезПоследних` — so a print form prints each
+line's price on its document's date, read in the query that loads the lines. Database-only (the browser keeps the loaded
+value), read with the user's rights on the register, refused in `G` columns; install checks the register, resource and
+dimensions. `references/formulas.md` documents it, `print-templates.md` and `registers.md` point to it. Print responses
+(`print.render`, `print.renderPdf`, DSL `printPdf()`) now carry `warnings` for what printed empty, and an upgrade deletes
+the print templates a package no longer declares. **Needs a platform with the `SLICE()` release (CLI 0.2.37).**
+
+**Grids and lists group by a column.** A `grid` or `list` view's `viewConfig` can ship a default grouping:
+`groupByField`, `groupByOptions` (narrows the Group menu) and `collapsedGroups`, plus `inlineAdd` on a list.
+`dforge_module_validate` checks them as the install does (core `ViewGroupingValidator`, #1556): each named column is a
+dropdown, flags, reference or user column, `groupByOptions` includes `groupByField`, and `collapsedGroups` lists option
+values of a valid `groupByField`. `references/data-views.md` documents the keys and the validation checklist lists the
+rules. The vendored `dforge://schema/data-views` carries them from metadata 0.0.47. **Needs platform 1.28.11.**
+
 **`dforge-1c-import`: porting a 1C infobase.** A fifth skill. It carries the decisions a 1C port turns on, each with the
 measurement that settles it: a register's kind, where a posting takes each value, what to carry, physical columns through
 DBNames, vendor against client. It adds `references/loading.md` (copying the rows: swapped uuid halves, the empty reference
 and the empty date as values in register keys and periods, the year offset, enums by `_EnumOrder`, composite references,
 register state, triggers, dangling references, verification) and `references/print-forms.md` (MXL templates, the print
 procedure, `Строка`/`Формат` in SQL, reproducing 1C's slips, datasets as queries). `scripts/` ships the Python toolkit
-from a real port: it reads the configuration and DBNames from MS SQL without 1C, generates and validates modules, copies and
+from a real port: it exports the infobase without 1C, generates and validates modules, copies and
 reconciles the rows, checks postings and reads print templates, pointed at a port by `DF1C_ROOT` / `DF1C_PROJECT` and
 started from `scripts/project-template/`. `install-skills` installs it with the other four.
 
+The toolkit has two layers. `dump1c` is the only part that reads 1C. It reads either a server infobase on MS SQL or a
+file infobase (`1Cv8.1CD`, formats 8.2.14 and 8.3.8, through a pure-Python reader), and writes one export to `out/`:
+the configuration, DBNames, the schema, every table's rows as Parquet, and a manifest with the year offset and the
+horizons. Everything else reads that export, with DuckDB for the rows (`store.py`). The export is the same whichever
+kind of infobase it came from, so a project's `sources.QUERIES` are DuckDB SQL. **Breaking for an existing port:** a
+query written in T-SQL (`[_Fld12]`, `TOP`, `0x01`, `CONVERT`) fails until it is rewritten (`"_Fld12"`, `LIMIT`,
+`from_hex('01')`, `CAST`). `dump1c data --changes [--since <day>]` brings an MS SQL export up to date by reading
+only what 1C changed. It rebuilds each table's file in place, so `delta` follows a cutover in minutes rather than
+after a full export. It also catches accounting entries switched on or off without the document being written.
+Register totals and document journals are left out of the export by default; name one, or pass `--derived`, to
+export it. `delta` needs an MS SQL export: a file
+infobase has no database-wide rowversion. `meta` now finds the configuration's root from `root` instead of a GUID
+fixed to one configuration.
+
 ## 0.2.45 — 2026-10-25
 
 **English is the base locale, and it lives in the definitions.** Install never reads

package/dist/server.js

@@ -31002,7 +31002,7 @@ var import_node_crypto = require("crypto");
 var fs2 = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.36/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
+// node_modules/.pnpm/@dforge-core+dforge-cli@0.2.37/node_modules/@dforge-core/dforge-cli/dist/lib.mjs
 function buildManifest(opts, moduleId) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const manifest = {
@@ -31243,7 +31243,7 @@ function buildZedTasks() {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.46/node_modules/@dforge-core/metadata/dist/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.47/node_modules/@dforge-core/metadata/dist/index.js
 var AggType = {
   Sum: "sum",
   Count: "count",
@@ -34612,7 +34612,7 @@ var path10 = __toESM(require("path"));
 var fs7 = __toESM(require("fs"));
 var path9 = __toESM(require("path"));
 
-// node_modules/.pnpm/@dforge-core+metadata@0.0.46/node_modules/@dforge-core/metadata/dist/dsl/index.js
+// node_modules/.pnpm/@dforge-core+metadata@0.0.47/node_modules/@dforge-core/metadata/dist/dsl/index.js
 var PUNCT3 = ["===", "!=="];
 var PUNCT2 = [
   "==",
@@ -38255,6 +38255,73 @@ function checkMenus(ctx) {
   };
   for (const [mcode, m] of Object.entries(menus)) walk(m, `menus \u2192 ${mcode}`);
 }
+function checkViewGrouping(ctx) {
+  const { err, entities, fieldDefsOf, views } = ctx;
+  for (const [vcode, v] of Object.entries(views)) {
+    const viewType = v.viewType ?? "grid";
+    if (viewType !== "grid" && viewType !== "list") continue;
+    const config2 = v.viewConfig;
+    if (!config2 || typeof config2 !== "object" || Array.isArray(config2)) continue;
+    const cfg = config2;
+    const ent = v.dataSources?.[0]?.entityCode;
+    if (!ent) continue;
+    const defs = fieldDefsOf[ent];
+    if (!defs || entities[ent]?.extends) continue;
+    const where = `data_views \u2192 ${vcode}`;
+    const resolve8 = (key, cd) => {
+      const f = defs[cd];
+      if (!f) err(where, `names '${cd}' in '${key}', which entity '${ent}' does not define`);
+      else if (!isGroupable(f)) err(where, `names '${cd}' in '${key}', which is not a dropdown, reference or user column`);
+      else return f;
+      return void 0;
+    };
+    const readStrings = (key) => {
+      const val = cfg[key];
+      if (!Array.isArray(val)) return void 0;
+      const items = [];
+      for (const item of val) {
+        if (typeof item === "string") items.push(item);
+        else err(where, `has a non-string item in '${key}'`);
+      }
+      return items;
+    };
+    const groupBy = typeof cfg.groupByField === "string" ? cfg.groupByField : void 0;
+    const groupField = groupBy !== void 0 ? resolve8("groupByField", groupBy) : void 0;
+    const options = readStrings("groupByOptions");
+    if (options) {
+      for (const cd of options) resolve8("groupByOptions", cd);
+      if (groupBy !== void 0 && !options.includes(groupBy)) {
+        err(where, `has 'groupByOptions' without its 'groupByField' '${groupBy}'`);
+      }
+    }
+    const collapsed = readStrings("collapsedGroups");
+    if (collapsed) {
+      if (!groupField) err(where, "sets 'collapsedGroups' without a valid 'groupByField'");
+      else if (isDropdown(groupField)) {
+        const values = optionValues(groupField);
+        for (const val of collapsed.filter((c) => !values.has(c))) {
+          err(where, `lists '${val}' in 'collapsedGroups', which is not an option of '${groupBy}'`);
+        }
+      }
+    }
+  }
+}
+function isDropdown(f) {
+  return f.fieldTypeCd === "dropdown" || f.fieldTypeCd === "flags";
+}
+function isGroupable(f) {
+  return isDropdown(f) || f.fieldTypeCd === "user" || f.columnType === "R";
+}
+function optionValues(f) {
+  const result = /* @__PURE__ */ new Set();
+  const options = f.params?.options;
+  if (!Array.isArray(options)) return result;
+  for (const item of options) {
+    const val = item && typeof item === "object" ? item.value : item;
+    if (typeof val === "string" || typeof val === "number") result.add(String(val));
+  }
+  return result;
+}
 
 // src/tools/validate/security.ts
 var fs14 = __toESM(require("fs"));
@@ -38525,6 +38592,7 @@ var CHECKS = [
   checkEntityViews,
   checkDataViews,
   checkVisibleColumns,
+  checkViewGrouping,
   checkMenus,
   checkRoleRights,
   checkSelectCoverage,

package/package.json

@@ -1,49 +1,48 @@
 {
-	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.46-next",
-	"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",
-	"packageManager": "pnpm@12.14.0+sha512.c18ba6d87993d3d164cb5e8948f32b2c06ee854487e06cd8d86781342fb3e5bb4634367034711e86802baa9c37bea906ce1929ad08d70884c97d801df13389a6",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/dforge-core/dforge-mcp.git"
-	},
-	"bin": {
-		"dforge-mcp": "dist/server.js",
-		"dforge-install-skills": "scripts/install-skills.mjs"
-	},
-	"files": [
-		"dist/",
-		"docs/",
-		"resources/",
-		"skills/",
-		"scripts/install-skills.mjs",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"main": "dist/server.js",
-	"engines": {
-		"node": ">=18"
-	},
-	"scripts": {
-		"build": "tsup",
-		"sync-schemas": "node scripts/vendor-schemas.cjs",
-		"prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
-		"typecheck": "tsc --noEmit",
-		"test": "vitest run",
-		"install-skills": "node scripts/install-skills.mjs"
-	},
-	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.36",
-		"@dforge-core/metadata": "^0.0.46",
-		"@modelcontextprotocol/sdk": "^1.30.0",
-		"zod": "^4.4.3"
-	},
-	"devDependencies": {
-		"@types/node": "^26.2.0",
-		"tsup": "^8.5.1",
-		"typescript": "^6.0.3",
-		"vitest": "^4.1.10"
-	}
-}
+  "name": "@dforge-core/dforge-mcp",
+  "version": "0.2.48",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dforge-core/dforge-mcp.git"
+  },
+  "bin": {
+    "dforge-mcp": "dist/server.js",
+    "dforge-install-skills": "scripts/install-skills.mjs"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "resources/",
+    "skills/",
+    "scripts/install-skills.mjs",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "main": "dist/server.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@dforge-core/dforge-cli": "^0.2.37",
+    "@dforge-core/metadata": "^0.0.47",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsup",
+    "sync-schemas": "node scripts/vendor-schemas.cjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:1c": "python3 -m unittest discover -s test/onec -v",
+    "install-skills": "node scripts/install-skills.mjs"
+  }
+}

package/resources/docs/dsl-reference.md

@@ -569,7 +569,7 @@ if (info.mimeType != 'application/pdf') { error('Receipt must be PDF') }
 ```
 
 #### `printPdf(entityCd, key, templateCd)`
-Render a print template to a PDF as the current user and return the archived file as `{ fileId, fileName, mimeType, size, checksum }`; attach it with `sendEmail()`. Pass a qualified entity code. Not in a scheduled job or a background action; max 10 per run.
+Render a print template to a PDF as the current user and return the archived file as `{ fileId, fileName, mimeType, size, checksum }`, plus `warnings` when a value printed empty because the user may not read it; attach it with `sendEmail()`. Pass a qualified entity code. Not in a scheduled job or a background action; max 10 per run.
 
 ```dsl
 execute:

package/resources/schemas/data-views.schema.json

@@ -52,6 +52,7 @@
 			},
 			"additionalProperties": false,
 			"allOf": [
+				{ "$ref": "#/$defs/rules/grid" },
 				{ "$ref": "#/$defs/rules/kanban" },
 				{ "$ref": "#/$defs/rules/calendar" },
 				{ "$ref": "#/$defs/rules/tree-grid" },
@@ -62,6 +63,17 @@
 		},
 
 		"rules": {
+			"grid": {
+				"if": {
+					"properties": { "viewType": { "const": "grid" } },
+					"required": ["viewType"]
+				},
+				"then": {
+					"properties": {
+						"viewConfig": { "$ref": "#/$defs/gridViewConfig" }
+					}
+				}
+			},
 			"kanban": {
 				"if": {
 					"properties": { "viewType": { "const": "kanban" } },
@@ -131,6 +143,26 @@
 			}
 		},
 
+		"gridViewConfig": {
+			"type": "object",
+			"properties": {
+				"groupByField": {
+					"type": "string",
+					"description": "Dropdown, reference or user column the rows are grouped by under header rows"
+				},
+				"groupByOptions": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Columns the Group by menu offers; must include groupByField"
+				},
+				"collapsedGroups": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Option values of groupByField whose groups start collapsed"
+				}
+			},
+			"additionalProperties": false
+		},
 		"kanbanViewConfig": {
 			"type": "object",
 			"required": ["groupByField"],
@@ -195,6 +227,24 @@
 					"type": "array",
 					"items": { "$ref": "#/$defs/listLevelConfig" },
 					"description": "Hierarchical child levels for expandable list rows"
+				},
+				"groupByField": {
+					"type": "string",
+					"description": "Dropdown, reference or user column the rows are grouped by"
+				},
+				"groupByOptions": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Columns the user may regroup by; must include groupByField"
+				},
+				"collapsedGroups": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Option values of groupByField whose groups start collapsed"
+				},
+				"inlineAdd": {
+					"type": "boolean",
+					"description": "Show an add row in each group (at the top when ungrouped)"
 				}
 			},
 			"additionalProperties": false

package/skills/dforge-1c-import/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dforge-1c-import
-description: How to port a 1C:Enterprise 8 infobase (УТП, УПП, УТ, БП or a configuration built on them) to dForge modules — how to decide a register's kind, where a posting takes each value from, what to carry and what to drop, and how to check every one of those decisions against the data instead of guessing. Use this whenever the work involves a 1C infobase, a 1C configuration, MS SQL tables named _Reference/_Document/_AccumRg/_InfoRg/_AccRg, регистры, проведение, ОбработкаПроведения, Движения, партионный учёт, or migrating a client off 1C onto dForge — including when the user only says "the client's old system" and the tables turn out to be 1C's, and including when they ask only for a piece of it such as "which register kind should this be" or "why does this document write more rows than 1C does". Also covers copying the rows (keys, dates, enums, composite references, empty values, reconciliation) and porting 1C print forms (MXL templates, Строка/Формат, НСтр) to dForge print templates.
+description: How to port a 1C:Enterprise 8 infobase (УТП, УПП, УТ, БП or a configuration built on them) to dForge modules — how to decide a register's kind, where a posting takes each value from, what to carry and what to drop, and how to check every one of those decisions against the data instead of guessing. Use this whenever the work involves a 1C infobase, a 1C configuration, a file infobase (1Cv8.1CD), MS SQL tables named _Reference/_Document/_AccumRg/_InfoRg/_AccRg, регистры, проведение, ОбработкаПроведения, Движения, партионный учёт, or migrating a client off 1C onto dForge — including when the user only says "the client's old system" and the tables turn out to be 1C's, and including when they ask only for a piece of it such as "which register kind should this be" or "why does this document write more rows than 1C does". Also covers copying the rows (keys, dates, enums, composite references, empty values, reconciliation) and porting 1C print forms (MXL templates, Строка/Формат, НСтр) to dForge print templates.
 ---
 
 # Porting a 1C infobase to dForge
@@ -341,7 +341,8 @@ judgement above, written down.
 Do not write the mechanical half again. `scripts/` in this skill's directory holds the
 Python library that did it on a real port:
 
-- reading the configuration and DBNames straight from MS SQL;
+- exporting the infobase (configuration, DBNames, schema, rows) to `out/`, from MS SQL or
+  from a file infobase (`1Cv8.1CD`). Every later step reads the export, never 1C;
 - parsing the metadata;
 - inventorying registers and handlers;
 - generating and validating modules;

package/skills/dforge-1c-import/references/environment.md

@@ -41,7 +41,8 @@ runs, and every number downstream is confidently wrong.
 
 1C shifts stored dates by the infobase's `_YearOffset` — commonly 2000, so `4012` in the
 column is 2012, and the empty date `0001-01-01` lands on `2001-01-01` and should become
-NULL.
+NULL. That is a server infobase. A file infobase stores real dates (offset 0). The export
+records which applies in `export.json`, and `store.year_offset()` reads it from there.
 
 It applies to **stored datetime columns only**. A date the configuration formatted into a
 string (`НачалоДня(Дата)` assigned to a `Строка(10)` dimension) carries the real year, and

package/skills/dforge-1c-import/references/loading.md

@@ -47,7 +47,7 @@ Everything else is column-level and mechanical. Write each conversion once, in t
 |---|---|---|---|
 | 1 | `_IDRRef binary(16)` | `uuid` | 1C stores the two 8-byte halves swapped relative to the printed GUID. In SQL: `substr(h,17)\|\|substr(h,1,16)` over the hex. Check it once by joining a line to its catalog and seeing the expected name. |
 | 2 | sixteen zero bytes | `NULL` in a link | Left as-is, it is a uuid pointing at nothing, and the FK rejects the load. **In a register dimension it is a value, not an absence:** keep it as the nil uuid in a key column, because NULL ≠ NULL in a balance, a GROUP BY or a unique key. |
-| 3 | `datetime` | date/timestamp minus `_YearOffset` | The offset is commonly 2000. The empty date `0001-01-01` lands on `2001-01-01` and becomes NULL. **On an information register's period it is a value:** "in force since the beginning". Load it as NULL and the slice (`period <= @date`) never finds the row. |
+| 3 | `datetime` | date/timestamp minus `_YearOffset` | The offset is commonly 2000 on MS SQL, and 0 in a file infobase (`export.json` says which). The empty date `0001-01-01` lands on `2001-01-01` and becomes NULL. **On an information register's period it is a value:** "in force since the beginning". Load it as NULL and the slice (`period <= @date`) never finds the row. |
 | 4 | a date 1C formatted into a string (`13.01.2016` in `nvarchar`) | `date` | No offset: nothing stored a datetime there. |
 | 5 | a number in a string column | numeric | Decimal comma, nbsp or space as the thousands separator. |
 | 6 | `binary(1)` flags | `bool` | `_Marked`, `_Posted`, `_Folder`. Check `_Folder`'s polarity against a known group and a known item. Do not trust the name. |
@@ -158,4 +158,7 @@ and alter the pairs that disagree. Never narrow one that holds something longer.
 ## Incremental re-runs
 
 1C's `_Version` (rowversion) gives a cheap delta. Take the high-water mark **before** the
-read, so a row 1C changes during the read is picked up next time rather than lost.
+read, so a row 1C changes during the read is picked up next time rather than lost. The
+export takes it before each table and records it in `export.json`. Only a server infobase
+has one. In a file infobase `_Version` is a counter per table, so a file infobase is
+reloaded whole, which its size allows.

package/skills/dforge-1c-import/references/measurements.md

@@ -3,7 +3,7 @@
 Each decision in SKILL.md has a query that settles it. They are written against a loaded
 dForge tenant (Postgres) because that is where both sides are comparable — the 1C rows and
 what the platform writes. Where the question can only be asked of the infobase, the query
-is against MS SQL and says so.
+is against the export (DuckDB over `out/data/`, via `store.connect()`) and says so.
 
 Adapt names; the shapes are the point.
 

package/skills/dforge-1c-import/scripts/README.md

@@ -1,7 +1,8 @@
 # The 1C porting toolkit
 
-A Python library that reads a 1C:Enterprise 8 infobase hosted on MS SQL Server. It needs
-no 1C software and no licence. From the infobase it:
+A Python library that reads a 1C:Enterprise 8 infobase, either a server infobase on MS SQL
+Server or a file infobase (`1Cv8.1CD`). It needs no 1C software and no licence. From the
+infobase it:
 
 - generates dForge modules;
 - copies the rows;
@@ -18,6 +19,55 @@ scripts/
   project-template/     what a new port starts its project package from
 ```
 
+## Two layers: export, then everything else
+
+Only one step reads 1C itself. `dump1c` exports the infobase to `out/`, and every later
+step reads that export, never the infobase.
+
+| layer | modules | reads | writes |
+|---|---|---|---|
+| export | `dump1c` · `source_mssql` · `source_file` · `onecd` | the infobase: MS SQL (`DF1C_SERVER`/`DF1C_DB`) or a `.1CD` file (`DF1C_FILE`) | `out/config/`, `dbnames.json`, `schema.json`, `data/<table>.parquet`, `export.json` |
+| everything else | `store` and every other module | `out/`. Rows are queried with DuckDB through `store.connect()` | modules, the tenant, reports |
+
+The export looks the same whichever kind of infobase it came from:
+
+- names are spelt the MS SQL way (`_Reference12`, `_Fld345RRef`). A file infobase keeps
+  them in capitals, and DBNames supplies the spelling back;
+- the schema uses MS SQL type names (`binary(16)`, `nvarchar`, `numeric`, `datetime`);
+- booleans are `binary(1)`.
+
+Rows are kept as 1C stores them. `export.json` records the infobase's year offset: usually
+2000 on MS SQL, always 0 in a file infobase. It also records the horizon (`MIN_ACTIVE_ROWVERSION()`)
+taken before each table was read.
+
+- **SQL over the export is DuckDB's.** That includes a project's `sources.QUERIES`. Quote
+  names with double quotes (case does not matter), use `LIMIT` instead of `TOP`, write
+  a binary constant as `from_hex('01')` instead of `0x01`, and use `CAST` instead of
+  `CONVERT`. A port whose queries were written in T-SQL has to rewrite them.
+- **`dump1c data --changes` reads only what 1C changed** since the export (or `--since
+  <day>`). It works table by table:
+  - objects are re-read by `_Version` above the mark, and deletions are found by key;
+  - tabular parts are re-read through their changed owners;
+  - register movements are re-read through their changed recorders;
+  - anything else is re-read whole.
+
+  It rewrites each table's file to what a full export would hold. On an infobase of 2.7 M
+  objects, it reads the keys in a few seconds instead of a full export of 1.5 h.
+
+  On an accounting register it also compares each recorder's count of inactive entries.
+  Switching entries on or off ("Включить/выключить проводки") rewrites them without
+  writing the document, so `_Version` does not show it.
+- **Totals and document journals are left out by default** (`_AccumRgT`, `_AccumRgTn`,
+  `_AccRgAT`, `_AccRgCT`, `_DocumentJournal`). 1C derives them from other tables, they
+  have no `_Version`, and `--changes` would read them in full on every run: 53.7 M of
+  313 M rows. Name one, or pass `--derived`, to export it. `seedstate verify` says which
+  totals table it needs.
+- **`delta` needs an MS SQL export.** In a file infobase `_Version` is a counter per table,
+  not a rowversion for the whole database, so a file export has no horizon. Re-export it
+  and reload with `migrate run <module> --truncate`.
+- **Read a file infobase while 1C is not writing to it.** Copy the `.1CD` first, or close
+  the infobase.
+
 ## Library and project
 
 - **`lib/` knows 1C and dForge**: how a configuration is stored, how its metadata
@@ -42,14 +92,17 @@ Then regenerate. If a port keeps needing hand edits, the generator is wrong.
 ## Setup
 
 - Python 3.7+.
-- `pyodbc` and an ODBC driver for SQL Server (driver 17 or 18), to read the infobase.
+- `pyarrow` and `duckdb`, to write and read the export (on 3.7: `pyarrow==12.0.1`,
+  `duckdb==1.1.3`).
+- `pyodbc` and an ODBC driver for SQL Server (driver 17 or 18), only to export a server
+  infobase. A file infobase needs nothing more.
 - `psycopg2`, to load and check the tenant.
 - `jsonschema`, for `validate`.
 - Node with `liquidjs` in `PRINT_NODE_DIR`, only for `printgen preview`.
 
 On Windows, set `PYTHONIOENCODING=utf-8`.
 
-Lay out a port directory and point the toolkit at it:
+Lay out a port directory, copy `project-template/.env.example` to `<root>/.env` and fill it in, and export `DF1C_ROOT` / `DF1C_PROJECT` in the shell:
 
 ```
 myport/
@@ -63,6 +116,7 @@ myport/
 DF1C_ROOT=/path/to/myport
 DF1C_PROJECT=/path/to/myport/project
 DF1C_SERVER=<sql server>   DF1C_DB=<infobase db>   DF1C_USER= DF1C_PASS=   # read-only login; Windows auth when USER is empty
+DF1C_FILE=<path to 1Cv8.1CD, or its folder>                                 # a file infobase instead of the two above
 DF_TENANT=<tenant code>    DF_PG_HOST= DF_PG_PORT= DF_PG_USER= DF_PG_PASS=  # the tenant's Postgres, for load and checks
 ```
 
@@ -76,7 +130,7 @@ docstring with its options, and `python 1c.py --list` lists them all.
 
 | # | step | command |
 |---|---|---|
-| 1 | Read the configuration and DBNames from the SQL tables | `dump1c probe` · `dump1c dbnames` · `dump1c schema` · `dump1c extract` |
+| 1 | Export the infobase: configuration, DBNames, schema, rows | `dump1c probe` · `dump1c all`, or one at a time: `dump1c dbnames` · `schema` · `extract` · `data [table ...]` |
 | 2 | Parse the metadata, resolve type GUIDs, join the physical schema | `meta allobjects` · `typemap` · `analyze` · `attrs <Object>` · `explore <Object>` |
 | 3 | Extract the module texts (posting handlers, print procedures) | `extract_code` · `unpack <Object> --code` |
 | 4 | Inventory: what exists, what is used, what is the client's | `inventory` · `docusage` · `custom` · `sizing` · `subsystems` |
@@ -86,7 +140,7 @@ docstring with its options, and `python 1c.py --list` lists them all.
 | 8 | Install them | `npx -y @dforge-core/dforge-cli@latest module install ...`, or `rebuild --code <tenant> --install` |
 | 9 | Copy the rows and reconcile | `migrate plan\|check\|run\|verify\|fill <module>` · `integrity` · `columnmap <module>` |
 | 10 | Post state and registers | `posted [--mark]` · `posting` · `seedstate` · `totals` · `coverage` |
-| 11 | Catch up with what 1C changed | `delta --baseline` · `delta [--apply]` |
+| 11 | Catch up with what 1C changed (MS SQL exports only) | once: `dump1c data --objects` (delta needs every object's keys); then `dump1c data --changes`, `delta --baseline` · `delta [--apply]` |
 | 12 | Print forms and reports | `mxl list [--client]` · `mxl dump <Object>` · `printgen <spec>` · `printgen preview <spec> <form> <key>` · `reportgen <spec>` |
 | 13 | External reports and processings stored in the infobase | `external` |
 
@@ -95,7 +149,7 @@ reproducible.
 
 ## Rules the toolkit assumes
 
-- **The infobase is read-only.** Use a SELECT-only login.
+- **The infobase is read-only.** Use a SELECT-only login. Read a file infobase from a copy.
 - **Open ad-hoc database connections in autocommit.** A read transaction left open
   blocks the next install's `ALTER`.
 - **Resolve a physical column (`_FldNNN`) only through DBNames** (`attrs`, `columnmap`).
@@ -108,3 +162,30 @@ reproducible.
 This copy is kept in step with the port it was developed on (`tools/lib`, `tools/1c.py`
 there). Fixes made in a port go back to the library here. A project's own files never
 come here.
+
+### Regression checks and restart contract
+
+From the MCP repository root: `pnpm test:1c` (Python 3, standard library only).
+These tests use synthetic inputs and mocked database boundaries, never a tenant or
+source infobase. They cover conversions, COPY encoding, settlement failure/retry and
+the initial loader's committed-per-entity restart contract; they do not replace
+Parquet/DuckDB/PostgreSQL integration or real source-to-target reconciliation.
+
+`delta --apply` prints each module's `ready` or `partial` status. Exit 0 means all
+selected modules settled; exit 2 means data may have committed but settlement is
+incomplete (state/totals drift or markers not converged, including `--no-mark`
+when markers are needed). Resolve the reported problem and rerun `--apply`;
+persisted unsettled entities are checked even when the new delta has no changes.
+Dry runs report `dry_run` and do not certify readiness. Settlement write failures
+roll back the current transaction before restoring autocommit; ordinary failures
+report `partial` and allow the next module to run on a clean connection. Failure to
+rollback or restore the connection stops the command immediately. Previously
+committed entities/years remain committed; a rollback does not undo the whole import.
+Exit 0 does not replace the wider migration reconciliation.
+
+`migrate run --truncate` is a destructive reload into an isolated migration target,
+not an atomic refresh of a live application: clearing commits before loading and
+each entity commits separately. If interrupted, keep users out, repair the cause,
+rerun the same complete selection with `--truncate` from the same export, then
+reconcile again. Do not use an append rerun to recover a partially loaded target.
+For an active target, load/reconcile a separate database and switch only afterward.

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

@@ -224,8 +224,8 @@ def main():
 	if sys.argv[1] == "--model":
 		out_path, names = sys.argv[2], sys.argv[3:]
 		lines = ["# Transport & shipping contour - extracted model", "",
-		         "Generated from the `%s` MS SQL infobase without 1C software."
-	         % os.environ.get("DF1C_DB", "source"), ""]
+		         "Generated from the `%s` infobase without 1C software."
+	         % (os.environ.get("DF1C_DB") or os.path.basename(os.environ.get("DF1C_FILE") or "source")), ""]
 		for name in names:
 			guid, fields = fields_of(name, objects, types)
 			row = report.get(name, {})