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

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

@@ -0,0 +1,97 @@
+# Environment traps
+
+The things that cost hours the first time and minutes every time after. Written down so
+they cost minutes the first time.
+
+## 1C physical storage
+
+The infobase's SQL tables carry generated names; the configuration maps GUIDs to them.
+
+| prefix | what it is |
+|---|---|
+| `_Reference<N>` | catalog (справочник) |
+| `_Document<N>` | document; its tabular sections are `_Document<N>_VT<M>` |
+| `_InfoRg<N>` | information register; `_InfoRgSL<N>` is its slice-last cache |
+| `_AccumRg<N>` | accumulation register; `_AccumRgT<N>` its totals, `_AccumRgTn<N>` turnovers |
+| `_AccRg<N>` | accounting register |
+| `_Enum<N>` | enumeration; values carry `_EnumOrder`, never their names |
+| `_*ChngR<N>` | change registration for exchange — not the object's own data |
+
+Common columns: `_IDRRef` (16-byte GUID key), `_Period`, `_Active`, `_RecordKind`
+(0 receipt / 1 expense), `_RecorderRRef` + `_RecorderTRef` (the writing document, typed),
+`_LineNo`, `_Fld<N>` for every declared field in declaration order — dimensions first,
+then resources, then attributes.
+
+A field ending `RRef` is a single-type reference; a `_TYPE`/`_RTRef`/`_RRRef` triple is a
+composite one. `_IDRRef` bytes are stored with the halves swapped relative to the printed
+GUID.
+
+**Resolving a `_Fld` number to a name goes through `DBNames`, not through guessing.** The
+configuration keys every attribute by GUID, and `DBNames` holds a `Fld` entry per GUID
+giving its `_FldNNN`; the same file maps `VT` (a tabular section's table) and `LineNo`.
+Parse the object, collect its attributes with their GUIDs, and look each one up. Automate
+it once — everything else depends on it being right.
+
+Field numbers do run in declaration order from the object's base number, dimensions first,
+and distinct-value counts do look suggestive. Use that only to **check** a resolution you
+already made: two reference dimensions of similar shape swap silently, every query still
+runs, and every number downstream is confidently wrong.
+
+## The year offset
+
+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.
+
+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
+shifting it as well moves the value back two millennia.
+
+## An empty string is not NULL
+
+1C writes `''` where a value is absent. So `count(column)` counts it, and a column the
+infobase never filled reads as completely full. Sweep for text columns blank on every row
+before trusting any of them; the results split into stock fields the client does not use
+(fine) and columns the port read from the wrong source (not fine).
+
+## Shell: Cyrillic and backticks
+
+When commands are wrapped for execution, Cyrillic characters and backticks in the command
+text can break the wrapper before the command runs — the symptom is `command not found`
+for fragments of your own script, or a syntax error near a Cyrillic word.
+
+The fix that always works: write the script to a file with a file-writing tool, then run
+it by an ASCII-only path. Inside the file, Cyrillic is fine; in a pinch, `\uXXXX` escapes
+in the source keep the command itself ASCII.
+
+## Windows: `bash` is not the bash you want
+
+On Windows, `bash` on PATH resolves to WSL's, which lives in a different filesystem and
+fails with `execvpe(/bin/bash) failed` before reaching your script. Anything that shells
+out to a `.sh` needs Git's bash by full path:
+
+```
+C:\Program Files\Git\bin\bash.exe
+```
+
+This is invisible when working interactively from Git Bash and appears the moment a script
+does the same thing.
+
+## Python on Windows
+
+Output encoding defaults to the system codepage, so Cyrillic output raises
+`UnicodeEncodeError`. Set `PYTHONIOENCODING=utf-8`. When reading and writing files, name
+the encoding explicitly (`io.open(path, encoding="utf-8")`) rather than relying on the
+default.
+
+## Reading the infobase
+
+Read-only, always. Porting needs no writes to the source, and a `SELECT`-only credential
+makes that a property of the connection rather than a promise.
+
+No 1C licence is engaged by reading the SQL tables directly, which is what makes this
+approach available at all — but it also means nothing validates your reading of the
+metadata except the data itself.
+
+Guard the size of exploratory queries: a register of 14 million rows will answer a
+well-scoped question about one month in seconds and an unscoped one in minutes.

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

@@ -0,0 +1,161 @@
+# Copying the rows
+
+How the infobase's data gets into a dForge tenant once the modules are installed. The
+general shape of a migration script is in `dforge://reference/data-migration`. This file
+covers what is specific to 1C.
+
+## Copy, don't replay
+
+There are two routes:
+
+- **Through the API** (`data.set`, CSV import). Every document is re-posted on the way in.
+- **Straight into Postgres** with `COPY`.
+
+Take the second for the history. Re-posting needs the posting logic ported first. Once it
+is ported, its arithmetic has to match 1C's to the kopeck, or the imported balances differ
+from the ones the client reconciles against. It is also slow: millions of documents
+through RPC take days.
+
+A direct copy keeps the values 1C computed and runs at disk speed. The API route stays
+useful for one job: catching up the last days at cutover, while 1C is still live.
+
+## Shape the modules so the rows fit
+
+A copy is only mechanical if nothing has to be reshaped:
+
+- **Use the infobase's key as the key.** Key every entity by `_IDRRef` as a `uuid`. Then no
+  old-key → new-key table is needed and no reference has to be re-resolved.
+- **Line tables keep 1C's composite key**, `(<owner>_id, line_no)`, as
+  `_Document<N>_VT<M>` is keyed.
+- **Port the reference data as well.** Mirror `Номенклатура`, `Контрагенты`, `Склады`
+  rather than mapping them onto platform modules. Then a line's `product_id` is the same
+  16 bytes on both sides.
+- **Build the column map as the entities are generated**, not afterwards, so it cannot
+  drift from the schema. The map records which `_FldNNN` feeds each target column.
+  Authored entities, whose names were chosen by hand, get a map written by hand. Propose
+  it by running each 1C attribute name through the same naming function and declare only
+  the leftovers.
+- **Read the target's physical shape from the tenant itself** (`"dForge".entity`,
+  `information_schema`). Do not read it from the module files. The loader then cannot
+  disagree with what the installer built.
+
+## The conversions
+
+Everything else is column-level and mechanical. Write each conversion once, in the loader.
+
+| # | 1C storage | becomes | the trap |
+|---|---|---|---|
+| 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. |
+| 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. |
+| 7 | enum reference | option code | The value is a GUID into `_Enum<N>`. `_EnumOrder` is its position in the metadata, so read the options in that order and pair by position. Generate the dropdown from the enum: hand-written option lists come out short. |
+| 8 | composite reference: `_TYPE` + `_RTRef` + `_RRRef` | the key, plus a "which table" column where the port keeps one | The table number in `_RTRef` is the only thing that says what the row on the other end is. Map numbers to meanings via DBNames. |
+| 9 | `ХранилищеЗначения` (`image`) | `bytea`, copied as is | It declares itself a reference. Read as one, it becomes a uuid column that can never be filled. |
+| 10 | `nchar` padding | trimmed text | `_Code nchar(N)` shows trailing spaces. |
+| 11 | `''` | `''` or NULL, decided once | 1C writes `''` for "no value". Every emptiness check must test both. |
+
+### Register keys
+
+An information register has no key in 1C. Where the infobase kept one, it is `_SimpleKey`.
+For the rest, derive the key from the row: a uuid5 over the source table and the row's
+values. Then a re-run lands on the same key and a reload is idempotent.
+
+### Movement direction
+
+1C's convention depends on the register kind:
+
+- **Balance register.** Resources are unsigned. `_RecordKind` says which way the row went:
+  0 is a receipt (+1), 1 is an expense (−1). Refuse anything else; never default it.
+- **Turnover register.** Some authors kept the direction in the sign of the resource. Some
+  registers carry the two sides as separate resources, so every row is additive.
+
+Read which convention applies from the writer. Then fill the platform's direction stamp
+in the loader, not through a column default. An upgrade can arrive without the default,
+and every `SUM(value * direction)` silently becomes NULL.
+
+## What goes where for registers
+
+In 1C, posting writes movements to `_AccumRg<N>`, and `_AccumRgT<N>` caches period totals.
+In dForge, a register is an `A` column on the document plus a balance entity. In line
+mode the document's lines are the detail. So:
+
+- **Copy the documents and their lines.** `_Posted` becomes the register column's state.
+- **Copy the balances** from `_AccumRgT<N>`, or aggregate them from the movements. They are
+  1C's numbers, and those are what the client reconciles against.
+- **Do not copy line-mode movement rows.** They have nowhere to go: the lines are the detail.
+- **Close every period up to cutover after the load.** Unposting an imported document
+  recomputes its reversal from the lines. Where 1C's handler did more than sum the lines
+  (batch write-off, distribution), that reversal would not match what 1C wrote. The close
+  guard then refuses edit, unpost and delete on history.
+
+A raw `UPDATE` of a posted flag is refused (`DF006 REGISTRY_STATE_DIRECT`). Posting state
+is the engine's.
+
+## Order and triggers
+
+Postgres fires row triggers on `COPY`. The period lock and the posted-document guards
+would reject exactly the rows a migration writes. So:
+
+1. Load with `SET session_replication_role = 'replica'`.
+2. Load in dependency order: catalogs, then documents, then lines, then balances.
+3. Load self-referencing catalogs (parent hierarchies) in one pass with the constraint
+   suspended. A topological sort buys nothing.
+4. Re-enable the triggers, close the periods, verify.
+
+Keep ad-hoc measurement connections in **autocommit**. A long read transaction left open in
+a console holds a lock that blocks the next install's `ALTER` for as long as it stays open.
+
+## Dangling references
+
+1C does not enforce referential integrity. A copy arrives with references to rows deleted
+years ago. Prove it on the 1C side first: it is the infobase's state, not a load bug.
+There are three ways out:
+
+- **Null the reference.** The row stops saying what it said.
+- **Drop the FK.** You give up the integrity the port exists to gain.
+- **Create the missing row and mark it.** Give every ported catalog a read-only
+  `is_missing` flag. After a contour loads, walk the FKs and insert one flagged row per
+  missing key, its text columns carrying the key so it is traceable. **Recommended:** it
+  is the only option that keeps everything.
+
+Verification then counts `WHERE NOT is_missing`.
+
+## Verifying the load
+
+These checks are all cheap, and all should be automated from the first contour:
+
+- **Row counts** per source table against the target.
+- **Control sums** on every resource and every money column, 1C against Postgres. This is
+  the check that catches a decimal comma or a missed offset.
+- **Reference integrity.** Ask `pg_constraint`, not your own metadata: count every
+  single-column FK against its target, and compare every FK with the reference column's
+  declared target. A check that reads the same metadata the generator wrote agrees with
+  it by construction. A retargeted reference can keep its old FK for months.
+- **A sample of joins** resolving to the name a 1C report shows.
+
+Before the first load, ask the data what the specs claim: that a column is mandatory,
+wide enough, unique, and holds the declared kind. Do it in one pass, not one failed
+`COPY` at a time. The answers are usually the port being tidier than the business. For
+example, a "mandatory" kind may be empty on 95% of rows, and a "unique" plate number
+repeat after years of re-registrations.
+
+## Upgrades leave the physical table behind
+
+`module upgrade` can rewrite the metadata and leave the table as it was. Check this after
+any upgrade that changed a column:
+
+- a widened `varchar` still narrow;
+- a retargeted reference keeping its old FK;
+- a removed unique constraint still in place;
+- a type change not applied.
+
+The repair for widths is one query: join `entity_column` to `information_schema.columns`
+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.

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

@@ -0,0 +1,210 @@
+# The measurements
+
+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.
+
+Adapt names; the shapes are the point.
+
+## Contents
+
+1. Does this register need a collapse?
+2. Which kind is it?
+3. Would accumulation ever accumulate?
+4. Did the collapse actually happen?
+5. Is a guard in the handler alive?
+6. Does anything read this?
+7. Is a column's type a lie?
+8. Is a text column really full?
+9. Which costing method does the base use?
+
+---
+
+## 1. Does this register need a collapse?
+
+The handler's `Свернуть` is the signal; these two confirm it and size it.
+
+```sql
+-- how often the lines of one document repeat a dimension
+select repeats, count(*) as documents from (
+  select <doc_fk>, count(*) - count(distinct <dim>) as repeats
+  from <line_table> group by 1) x
+group by 1 order by 1 limit 10;
+
+-- lines in, rows 1C actually wrote out, for the same documents
+select sum(lines) as lines, sum(rows_1c) as rows_1c from (
+  select d.<pk> id,
+    (select count(*) from <line_table> l where l.<doc_fk> = d.<pk>) as lines,
+    (select count(*) from <register> r where r.recorder = d.<pk>) as rows_1c
+  from <documents> d) y;
+```
+
+`lines > rows_1c` means the collapse is load-bearing.
+
+## 2. Which kind is it?
+
+```sql
+select count(*) as rows,
+       count(distinct (<dims>)) as distinct_keys,
+       count(distinct recorder) as writing_documents
+from <register>;
+```
+
+`rows = distinct_keys` means one row per key — a table of records, not a journal. Combine
+with question 1: one row per key *and* repeating lines means the writer collapses, which
+is `balance` in dForge regardless of the 1C family.
+
+## 3. Would accumulation ever accumulate?
+
+```sql
+select docs_per_key, count(*) as keys from (
+  select <key columns>, count(*) as docs_per_key
+  from <documents>
+  where coalesce(deletion_mark, false) = false
+  group by <key columns>) z
+group by 1 order by 1;
+```
+
+One output row showing `1` retires the objection that `balance` would add two openings
+together. Record the number in the declaration; it is the answer to the question the next
+reader will ask.
+
+## 4. Did the collapse actually happen?
+
+Two traps here, and they pull in opposite directions.
+
+Resource **totals** match whether the engine collapsed or not, because a sum is a sum. So
+totals alone cannot show a collapse. But row counts alone cannot either: against a
+register that already holds the migrated rows, a posting that did **nothing** adds no rows
+and creates no duplicate keys — and so passes a check built only on counts. A posting that
+updated the *wrong* existing key passes it too.
+
+What settles it is the expected delta **per full dimension tuple**, checked in both
+directions. Compute what the lines say each tuple should move, before posting:
+
+```sql
+-- expected, read through the binding's own map and headerMap
+select <dims>, sum(<resource>) as expected
+from <line_table> l join <documents> d on d.<pk> = l.<doc_fk>
+where d.<pk> = '<doc>'
+group by <dims>;
+```
+
+Then post, and compare per tuple rather than in aggregate:
+
+```sql
+select r.<dims>, r.<resource> - b.<resource> as moved
+from <register> r join <baseline snapshot> b using (<dims>);
+```
+
+Three things must hold together, and any one alone is weak:
+
+1. every expected tuple moved by exactly its expected amount;
+2. no tuple outside the expected set moved at all;
+3. after unposting, every tuple is back at the baseline.
+
+Point 2 is what catches an update to the wrong key; point 3 is what catches a posting that
+silently did nothing, because a no-op also unposts to nothing and the baseline never
+moved. Snapshot the register's rows for the affected tuples before posting so the
+comparison has something to be against.
+
+And separately, since it is cheap:
+
+```sql
+select count(*) as keys_with_two_rows from (
+  select 1 from <register> group by <dims> having count(*) > 1) x;
+```
+
+## 5. Is a guard in the handler alive?
+
+`Если Стр.Количество <> 0` guards a loop. Has it ever fired?
+
+```sql
+select count(*) as lines,
+       count(*) filter (where <col> = 0)  as would_be_skipped,
+       count(*) filter (where <col> <> 0) as actually_written
+from <line_table>;
+```
+
+Zero skipped over years of data means the guard is dead code. Porting it as a platform
+feature would be paying for nothing.
+
+## 6. Does anything read this?
+
+A grep over the extracted configuration modules, not a query. Count the objects naming the
+register, split by whether the object is the client's own (lowercase prefix before a
+capital) or the vendor's, and look at what appears near each mention. If the only mentions
+are the writing document and `УдалитьДвиженияРегистратора`, nothing reads it.
+
+Do this before carrying a journal, a recorder link, or any mechanism that exists to
+support a reader.
+
+## 7. Is a column's type a lie?
+
+Sweep every text column at once rather than meeting them one at a time. Build the union
+from `information_schema.columns` in the module schemas, then:
+
+```sql
+select '<schema>.<table>.<col>' as col, count(*) as n
+from "<schema>"."<table>"
+where "<col>" ~ '^[0-9]{2}\.[0-9]{2}\.[0-9]{4}( |$)'
+```
+
+A hit is a date the 1C author declared as a string. Expect very few — in the base measured,
+one column out of 611 — which is what makes the sweep worth running once and never
+worrying again.
+
+## 8. Is a text column really full?
+
+```sql
+select count(*) as rows,
+       count(*) filter (where <col> is null)  as nulls,
+       count(*) filter (where <col> = '')     as empty_strings,
+       count(*) filter (where coalesce(<col>, '') <> '') as actually_filled
+from <table>;
+```
+
+`nulls = 0` while `actually_filled = 0` is the signature of a column read from a field the
+infobase never writes. It is invisible to `count(column)`.
+
+## 9. Which costing method does the base use?
+
+The accounting policy register will name an enum position and the configuration text may
+not resolve it. The movements answer it several ways, and agreement across them is the
+point — any one alone can mislead.
+
+```sql
+-- A. batches touched by one write-off. Average costing writes off proportionally across
+--    every batch in stock, so a heavy concentration at 1 rules it out.
+select batches, count(*) as expenses from (
+  select _RecorderRRef, <item>, <warehouse>, count(distinct <batch>) as batches
+  from <batch_register>
+  where _RecordKind = 1 and _Period >= ? and _Period < ?
+  group by 1,2,3) x
+group by 1 order by 1;
+
+-- B. distinct unit costs per item and warehouse within one month.
+--    A period-weighted average gives exactly one.
+select prices, count(*) from (
+  select <item>, <warehouse>,
+         count(distinct round(<amount> / nullif(<qty>, 0), 4)) as prices
+  from <batch_register>
+  where _RecordKind = 1 and _Period >= ? and _Period < ? and <qty> <> 0
+  group by 1,2) y
+group by 1 order by 1;
+
+-- C. was there a choice at all? (validity check: zero-stock cases mean the
+--    balance arithmetic is wrong and nothing below can be believed)
+--    then, among those with a choice, was the oldest batch in stock taken?
+--    FIFO takes the oldest; LIFO the newest; neither dominating means no rule
+--    is followed and the batch is effectively identified rather than queued.
+```
+
+Read C carefully: "the oldest batch ever received" is a different question from "the oldest
+batch that still had stock at that moment", and only the second is FIFO. The first gives a
+muddle and will mislead you.
+
+Whatever the answer, it changes the question put to the client rather than replacing it:
+not *"which method do you use"* — the base answers that — but *"is that what you meant, and
+should it stay that way"*. A rule nobody enforces may be accepted practice or an accident.

package/skills/dforge-1c-import/references/print-forms.md

@@ -0,0 +1,148 @@
+# Porting 1C print forms
+
+The platform's side of this (manifest, context, snippets, Scriban versus LiquidJS) is in
+`dforge://reference/print-templates`; queries are in `dforge://reference/queries`. This
+file covers what a 1C form brings with it.
+
+## What a 1C form is
+
+1C prints in two steps:
+
+1. The document's print procedure (`Печать…`, often in a shared module) computes almost
+   every value. It folds lines by product and series, takes places and packs through the
+   series' packaging, looks prices up at the date, totals, and assembles the
+   organization's requisites into one text.
+2. A spreadsheet template (макет, `MOXCEL`) is filled area by area with those values.
+
+So the template alone is not the form. **Read the procedure first.** It holds the
+requirement. The template is only the layout.
+
+The dForge form mirrors the two steps:
+
+| 1C | dForge |
+|---|---|
+| the print procedure | the template's datasets: a query, with F columns for per-line arithmetic |
+| the template (макет) | an HTML template with its CSS |
+| the shared printing library (requisites, contact info, amounts in words) | shared datasets and snippets, e.g. the platform's `common-words` for amounts and quantities in words |
+
+## Reading the template
+
+A template is the object's metadata group `{3daea016-69b7-4ed4-9453-127911372fe6, n,
+guid…}`. Each template's `<guid>.txt` names it and its body is `<guid>.0.txt`. A spreadsheet
+body starts `MOXCEL` and continues as a brace list:
+
+- **Rows** with their cells. A cell is one of:
+  - `{0, format}` — empty;
+  - `{16, format, {1,1,{lang,text}}}` — text, or a parameter when `lang` is `""`;
+  - `{20, …, {"U"}, …}` — a template string whose `[Name]` parts are parameters.
+- **Column sets**, **merges** and **named areas**. An area is rows (kind 1) or columns
+  (kind 2), with inclusive bounds.
+- **Formats.** Each is a bit mask followed by its values, low bit first: font index (1),
+  left/top/right/bottom border (2/4/8/16), height (64), width (128). The remaining bits
+  (alignment, placement) can be carried by number.
+- **Fonts.**
+
+Dump each template to HTML and JSON: areas, cells, parameters, merges, widths, fonts,
+borders. **Author the form from the dump; do not convert it.** 1C's layout is a grid of up
+to ~50 narrow columns. A faithful HTML copy of it is unmaintainable. Keep the form's
+logical columns and labels.
+
+Which areas the procedure outputs, and in what order, is the form's real structure. Typical
+areas are header, line, subtotal per group, total and signatures.
+
+## Inventory before porting
+
+- **List the forms per document from the print command's handler**, not from the
+  templates. An object can carry dead templates. Templates the code names only for dates
+  before some year print only old documents: record them and skip them.
+- **Count how often each variant fires** on recent documents. A variant is a template
+  chosen by a flag on the buyer or the contract, or a "per code" text. A variant used by
+  278 documents since last year is worth a template. One used by none may still be worth a
+  column.
+- **External print processings** (`ВнешниеОбработки`) live in the infobase as stored
+  binaries, not in the configuration. Inventory them separately.
+
+## Reproduce what 1C prints, including its slips
+
+The client compares the new printout to the old one. Where 1C's code has a defect, the
+printout has the defect, and the client knows the printout. Reproduce it, and say so in
+a comment at the place. Common ones:
+
+- **A misspelt variable** makes a lookup find nothing. For example, a phone kind read from
+  a misnamed variable means no phone ever prints. Print nothing.
+- **A field list with spaces** (`"НомерСчета, Банк, АдресБанка"`) passed where 1C expects
+  no spaces fills only the first field.
+- **A test on the wrong attribute**, such as an IBAN check on the account's name instead
+  of its number. Do the same test.
+- **Mixed Cyrillic and Latin letters** in a literal (`с` against `c`). Copy them byte for
+  byte.
+- **Language codes** in `НСтр("ru = '…'; en = '…'", Lang)` are matched case-insensitively,
+  so `"Ru"` finds `ru`.
+
+If the client later asks to fix one, it is a one-line change with the comment pointing
+at it.
+
+## Formatting numbers and dates as 1C does
+
+| 1C | output | Postgres equivalent |
+|---|---|---|
+| `Строка(n)`, `Формат(n)` without a format | thousands grouped by nbsp, decimal comma, no trailing zeros | `replace(replace(rtrim(rtrim(to_char(n,'FM999G999G999G990D9999999999'),'0'),'.'),',',E' '),'.',',')` (the `G`/`D` result depends on `lc_numeric`; check it) |
+| `Формат(n, "ЧДЦ=2")` | always 2 decimals | `to_char(n, 'FM999G999G990D00')` then the same separators |
+| `Формат(n, "ЧРД=.")` | decimal point | the replacement above with `.` |
+| `Формат(n, "ЧГ=0")` | no grouping | drop `G` |
+| `Формат(d, "ДФ=dd.MM.yyyy")` | `13.01.2016` | `to_char(d, 'DD.MM.YYYY')` |
+| a date parameter output as is | `13.01.2016 9:05:00` (hour without a leading zero) | `to_char(d, 'DD.MM.YYYY FMHH24:MI:SS')` |
+
+Before choosing the precision a price prints with, measure how many stored values actually
+have more decimals. Do not trust the declared precision: stored prices can carry a third
+decimal on most rows.
+
+Amounts and quantities in words should come from a shared snippet (the platform's
+`common-words`), not per-form code. Verify it on the client's real values against 1C's
+`ЧислоПрописью` output: thousands of values, every case. Expect differences only where 1C
+is ungrammatical, and agree them with the client.
+
+## Datasets: queries, and where a query falls short
+
+Prefer a query dataset. It runs under the user's rights and folder filters, which a stored
+procedure bypasses.
+
+- **Put per-line arithmetic into F columns on the line entity**: weight = places × place
+  weight, packs, the VAT percentage through a `SWITCH`, a group section through `IN`.
+- **Let the query group and sum** (`agg: group | sum`).
+- **Accumulate totals in the template.** The server engine has no `where`, `sum` or
+  `group_by` filters, but `plus`, `times`, `round` and `ceil` work.
+- **A dataset is always an array.** Take a header row with
+  `{% assign h = header | first %}`.
+
+A query cannot (yet) express these, so the dataset stays a procedure until it can:
+
+- a value in force at a date (`СрезПоследних`: prices, positions, codes, shelf lives);
+- a filter through a reverse set or a polymorphic reference;
+- string aggregation;
+- a join on columns that are not a reference;
+- formulas over aggregates.
+
+1C rounds after folding (`round(price × SUM(qty))`). A query sums a per-line formula. The two
+differ only where lines fold. Measure how many documents that touches, then agree it.
+
+## Verifying a ported form
+
+1. **Compare the dataset with the procedure's output.** Pick tens of random recent
+   documents and compare every field, line by line. Zero differences is the bar. An F
+   column rewritten from a procedure gets the same check.
+2. **Render previews on real documents** for every variant: each language, each flag,
+   with and without the optional blocks. Screenshot them against 1C's printout where one
+   is available.
+3. **Measure the data each block depends on.** How many recent documents have the date,
+   the indicators, the shelf life? A block empty on every document is either 1C's state
+   (record it) or a column read from the wrong source (fix it).
+
+## Generating templates
+
+When several forms share blocks (requisites, a lines table, signatures, a certificate
+body), write the templates from one generator. Do not hand-copy HTML. Keep the generator
+in the project, regenerate on every change, and never edit its output.
+
+In Python, keep each formatted literal its own expression. Adjacent string literals
+concatenate **before** `%` applies, which produces format errors far from the cause.