llm/docs/1c-sql-knowledge-adapter.md

# 1C SQL Knowledge Adapter Notes

Date: 2026-06-20

This document records verified facts and next engineering steps for a 1C
metadata adapter that reads SQL storage transparently instead of guessing
metadata object names from physical table names.

## Current Position

The adapter must be specification- and evidence-driven:

- Read platform-maintained structure files from SQL tables such as `Params`,
  `Config`, `ConfigSave`, `ConfigCAS`, and `ConfigCASSave`.
- Treat `Params/DBNames*` as the authoritative map between GUIDs, storage roles,
  and numeric SQL suffixes.
- Preserve storage-role labels exactly as the platform stores them: `Document`,
  `Reference`, `Fld`, `VT`, `LineNo`, `InfoRg`, and so on.
- Use XML dumps as a validation oracle and name source, not as the only runtime
  source.
- Avoid semantic guesses such as "physical table name looks like document".

## UPO SQL Facts Verified

SQL inventory for the UPO database showed:

- `Config`: 59,134 rows.
- `ConfigSave`: 0 rows.
- `ConfigCAS`: 4,711 rows.
- `ConfigCASSave`: 0 rows.
- `Params`: 51 rows.
- `_ExtensionsInfo`: 18 rows.

Exported `Params/DBNames*` files:

- 12 `DBNames` files.
- 61,011 records in the main `DBNames`.
- 141 distinct storage roles.
- 52,668 distinct SQL GUIDs.

Important observed role counts:

- `Fld`: 46,396.
- `VT`: 2,081.
- `LineNo`: 2,081.
- `InfoRg`: 1,266.
- `Enum`: 1,244.
- `Reference`: 794.
- `Document`: 374.

Sample validation against physical SQL schema showed that roles such as
`Document`, `Reference`, `Enum`, `InfoRg`, and `AccumRg` can correspond to
physical tables, while roles such as `Fld`, `VT`, and `LineNo` are structural
parts and not standalone tables.

## UPO XML Cross-Check

Built a top-level XML GUID index from:

`Z:\codex\1C\XML\UPO\Структура базы 1с\Конфигурация`

The first-pass index intentionally scans only top-level metadata XML files:

- `Configuration.xml`
- `Category/ObjectName.xml`, for example `Documents/АвансовыйОтчет.xml`

It does not yet scan deep nested files such as forms, help, templates, and
layouts.

Index result:

- XML files scanned: 17,711.
- Top metadata objects found: 17,702.
- GUIDs found: 138,262.
- Parse/read errors: 0.

SQL/XML comparison result:

- SQL GUIDs: 52,668.
- XML GUIDs: 138,262.
- Matched SQL GUIDs: 51,609.
- Top-object matched SQL GUIDs: 5,227.
- Occurrence-only matched SQL GUIDs: 46,382.
- Unmatched SQL GUIDs: 1,059.

A deeper XML index also exists and scans nested XML files:

- XML files scanned: 47,577.
- Top objects found: 29,651.
- GUIDs found: 164,824.
- SQL GUIDs matched: 51,639.
- Top-object matched SQL GUIDs: 5,257.
- Occurrence-only matched SQL GUIDs: 46,382.
- Unmatched SQL GUIDs: 1,029.

The deeper pass only reduced unmatched SQL GUIDs by 30, so most remaining
unmatched records are likely extension records, service records, or objects
whose matching XML dump is not in the UPO configuration XML root.

Unmatched SQL GUIDs by source file after the deep comparison:

- `DBNames-Ext-93951a6d-3f96-11f0-9fe9-005056b59abc`: 676.
- `DBNames-Ext-1fa5d8e5-2a28-11ee-9fc3-0050569db20c`: 190.
- `DBNames-Ext-3653438a-eee5-11ef-9fe7-005056b59abc`: 115.
- `DBNames-Ext-7177af37-e5a7-11ed-9fba-0050569db20c`: 38.
- Other `DBNames-Ext-*` files: 10 or fewer each.

The unmatched distribution strongly points to extension metadata, not to
missing base configuration object XML.

After adding the XML root for UPO extensions:

`Z:\codex\1C\XML\UPO\Структура базы 1с\Расширения`

Extension XML index result:

- XML files scanned: 1,500.
- Top objects found: 1,206.
- GUIDs found: 7,776.

Combined base-configuration + extension XML comparison:

- Combined XML files: 49,077.
- Combined XML GUIDs: 171,630.
- Matched SQL GUIDs: 52,560.
- Top-object matched SQL GUIDs: 5,314.
- Occurrence-only matched SQL GUIDs: 47,246.
- Unmatched SQL GUIDs: 108.

The remaining unmatched SQL GUIDs are no longer a general metadata problem.
They are concentrated in extension records without matching XML dumps:

- `КонтурEDI`: 100 GUIDs.
- `РазвитиеФункционалаДР`: 7 GUIDs.
- `MCP1C`: 1 GUID.

The folder `ДатаМобайл_Онлайн_УНФ` has two XML candidates:

- `ДатаМобайл_Онлайн_УНФ`: 323 XML files.
- `ДатаМобайл_Онлайн_УНФ prod`: 328 XML files.

Both are treated as source variants for the same SQL extension name. The
adapter must preserve the XML source path and not collapse variants by
extension name.

## Config Object Files

Direct export from SQL `Config` by `FileName = <metadata GUID>` works for
sample metadata objects:

- `84e4c0c3-2a21-4aba-a7b0-f92b3f2878ec`: `Document.АвансовыйОтчет`.
- `40045984-a54c-42bd-8ea8-1c10672f40ec`:
  `Catalog.АвансовыйОтчетПрисоединенныеФайлы`.
- `00035364-b591-4e6a-9219-e27dac18f687`:
  `InformationRegister.СостоянияКонтрагентовБЭД`.

Observed storage format for these files:

- SQL table: `Config`.
- Key column: `FileName`.
- Payload column: `BinaryData`.
- Compression: raw deflate.
- Text encoding after decompression: UTF-8 with optional BOM.
- Parsed form: brace-based 1C serialized value tree.

The parsed payload contains object names, synonyms, generated type GUIDs,
references, and serialized property structures. This confirms that the adapter
can retrieve a selected metadata object directly from SQL without dumping the
whole configuration.

## Object Context Prototype

This section describes an obsolete prototype. It has been replaced by the
current resolver/context API:

- `scripts/resolve_1c_object.py`
- `scripts/get_1c_object_brief_context.py`
- `scripts/get_1c_object_metadata.py`
- `scripts/get_1c_object_artifacts.py`
- `scripts/get_1c_object_code_context.py`
- `scripts/get_1c_form_context.py`
- `scripts/get_1c_module.py`

The prototype proved that a focused context for one object by GUID or name can
include:

- DBNames source files and storage roles.
- SQL table/column candidates derived from DBNames roles.
- Extension identity when the object comes from `DBNames-Ext-*`.
- XML source candidates and source variants.
- Config file summary when that GUID has already been exported from SQL.

Validated cases:

- `84e4c0c3-2a21-4aba-a7b0-f92b3f2878ec`
  (`Document.АвансовыйОтчет`): base DBNames records + Config summary.
- `00035364-b591-4e6a-9219-e27dac18f687`
  (`InformationRegister.СостоянияКонтрагентовБЭД`): base DBNames records +
  Config summary.
- `198392a0-d153-472e-9d97-711a09dd29e0`
  (`ExchangePlan.ДатаМобайл_СписокТСД`): `DBNames-Ext-93951a6d...`,
  extension `ДатаМобайл_Онлайн_УНФ`, storage role `Node`, and two XML source
  variants.
- `00a81908-5d20-49bd-bdea-c8e0ba641f32`
  (`Document.АвансовыйОтчет` inside `ДатаМобайл_Онлайн_УНФ` XML): XML source
  variants exist, but there are no DBNames records. This is likely an extension
  modification/borrowed object rather than a new SQL storage object.

This distinction is important for the final adapter: extension objects can be
new storage objects, or they can be changes to existing configuration objects.

The old live flow resolved an object, exported `Config` and `ConfigCAS` rows by
GUID, and then rebuilt the focused context. Current scripts keep the same
read-only rule and use SQL credentials only from parameters/environment
variables.

Validated live SQL export:

- `00b28285-400e-44c2-99af-3557299cfd8b`
  (`Document.ЗаявкаОтпускКабинетСотрудника`): exported from `Config`, not found
  in `ConfigCAS`; parsed as raw-deflate UTF-8 brace tree.
- `198392a0-d153-472e-9d97-711a09dd29e0`
  (`ExchangePlan.ДатаМобайл_СписокТСД` from `ДатаМобайл_Онлайн_УНФ`): found in
  `DBNames-Ext-*` and XML, but not found as a direct `Config`/`ConfigCAS`
  `FileName`. Extension object payload storage needs a separate SQL decoding
  path.

## ConfigCAS Content Search

Full `ConfigCAS` export is feasible for UPO:

- Files: 4,711.
- Size: 31.65 MB.
- File names: 40-character hex content-addressed keys, not metadata GUIDs.
- Compression: mostly raw deflate; a few gzip files.

Added `scripts/index_1c_sql_cas.py`.

For `ExchangePlan.ДатаМобайл_СписокТСД`
(`198392a0-d153-472e-9d97-711a09dd29e0`), direct SQL export by `FileName`
returns no `Config`/`ConfigCAS` file, but content search across `ConfigCAS`
finds 18 files containing the object GUID.

Examples:

- `ce8bf17f61c08afbb29d565cc87b000f3f4cacee`: contains object-level strings
  `ДатаМобайл_СписокТСД` and `DataMobile: Список ТСД`; brace root begins with
  `1`, similar to direct `Config` object payloads.
- `283eb5f07ccc27fad05c347fff1bebe70a562c8e`: large form/module payload with
  handlers such as `ПриОткрытии` and `ПриСозданииНаСервере`; brace root begins
  with `4`.
- Several files with brace root `10` appear to be relationship/index/reference
  structures around the object.

The current CAS indexing path is handled by `scripts/index_1c_sql_cas.py` and
the unified route index builders. CAS hits are internal evidence, not a normal
agent-facing object API.

## Extension CAS Manifest

`_ExtensionsInfo._ExtensionZippedInfo` contains a direct pointer to the root
CAS file:

- First 4 bytes: observed marker.
- Next 20 bytes: raw SHA1 bytes of the extension root `ConfigCAS` file.
- Remaining bytes: small extension metadata, including a UTF-16LE text
  fragment with synonym/version-like information.

`ConfigCAS.FileName` equals `SHA1(BinaryData)` for the stored compressed bytes.
This was verified against sampled `ConfigCAS` rows.

Added scripts:

- `scripts/parse_1c_extension_zipped_info.py`
- `scripts/extract_1c_extension_cas_manifest.py`
- `scripts/build_1c_extension_manifests.py`

All 18 UPO extensions have root-CAS keys, and all root-CAS files exist in
`ConfigCAS-all`.

The root-CAS file contains an object manifest:

- A root package/header block.
- A package payload block.
- A manifest list of `object-id -> base64(20-byte sha1)` pairs.

The base64 value decodes to the CAS file key. Object IDs can be plain GUIDs or
GUIDs with suffixes such as `.0`, `.1`, `.3`.

Examples:

- `ДатаМобайл_Онлайн_УНФ` root CAS:
  `517f2fb723e10d966684e73dd515c798bdb4a66f`.
- `ExchangePlan.ДатаМобайл_СписокТСД`
  (`198392a0-d153-472e-9d97-711a09dd29e0`) maps directly to:
  - `ce8bf17f61c08afbb29d565cc87b000f3f4cacee`
  - `2563bd2a2cd7df17ec86fd885c64ebfedba91b20`
  - `065f05c9a874233dc0dc481213aa8241e2a564fe`
  - `4233c26d2552c53727396656e432fcbe198923db`
- `КонтурEDI` root CAS:
  `0739041b1cc0c8b4240f6688aa319ff74551fc74`.
- A `КонтурEDI` object
  (`687571a4-0a25-4d2c-b4cb-b7317ba8de2a`) maps directly to:
  - `8e9ce770a0622acc5c0dee519e4aa0acff3dce00`
  - `a5847e560d1795162d5502d5a783591ffa2911e8`

This means the adapter does not need to scan all `ConfigCAS` content to fetch an
extension object. The direct path is:

`_ExtensionsInfo -> _ExtensionZippedInfo -> root_cas_key -> root manifest -> object_id -> cas_key -> ConfigCAS.BinaryData`

## Extension Object Part Evidence

Added:

- `scripts/classify_1c_manifest_payloads.py`
- `scripts/analyze_1c_manifest_object_parts.py`

Important rule: manifest suffixes such as `.0`, `.1`, and `.3` are not accepted
as semantic labels by themselves. A suffix is only an object part key. The
adapter must identify the part from the payload grammar and direct evidence:
root shape, embedded block markers, declared stream lengths, hashes, and
matches against XML/BSL/HTML exports.

The broad structural profile across all UPO extension manifests found:

- 3,832 manifest entries.
- 9 suffix groups.
- Empty suffix: 2,174 entries.
- `.0`: 1,397 entries.
- `.1`: 65 entries.
- `.2`: 175 entries.
- `.3`: 11 entries.

The same suffix can carry different evidence, so a rule like ".0 means module"
is invalid. For example, `.0` entries include base64 blocks, BSL text, HTML, and
payloads with no simple textual evidence.

Object-level comparison was validated for `ExchangePlan.ДатаМобайл_СписокТСД`
(`198392a0-d153-472e-9d97-711a09dd29e0`) from extension
`ДатаМобайл_Онлайн_УНФ`.

Manifest entries:

- `198392a0-d153-472e-9d97-711a09dd29e0` ->
  `ce8bf17f61c08afbb29d565cc87b000f3f4cacee`
- `198392a0-d153-472e-9d97-711a09dd29e0.0` ->
  `2563bd2a2cd7df17ec86fd885c64ebfedba91b20`
- `198392a0-d153-472e-9d97-711a09dd29e0.1` ->
  `065f05c9a874233dc0dc481213aa8241e2a564fe`
- `198392a0-d153-472e-9d97-711a09dd29e0.3` ->
  `4233c26d2552c53727396656e432fcbe198923db`

Verified evidence:

- The base object part has brace root marker `1`, root length `8`, and contains
  object-level strings and GUIDs that match
  `ExchangePlans/ДатаМобайл_СписокТСД.xml`.
- The `.0` part has brace root marker `5`, root length `5`, and contains one
  `#base64` block. After UTF-8 decoding and line-ending normalization, that
  block equals `Ext/Help/ru.html`.
- The `.1` part has brace root marker `2`, root length `71`, and contains GUID
  pairs/flags. In this object-level XML comparison those GUIDs did not match
  the local XML files, so its role is still structural evidence only.
- The `.3` part is not a single brace text. It contains stream headers matching
  the observed byte pattern `hhhhhhhh hhhhhhhh 7fffffff`, where the hexadecimal
  values declare stream sizes. One stream has declared size `00000de3`
  (`3555` bytes) and matches `Ext/ManagerModule.bsl` by SHA1 exactly.

Broader extension scan:

- `scripts/summarize_1c_extension_manifest_xml_parts.py`
- `reports/1c-sql/upo/extension-manifest-xml-part-summary.json`

The scan covers all 18 extension manifests and available XML dumps. It confirms
that the same structural patterns appear across multiple extensions:

- `root=1, len=8`: top-level metadata object descriptions, matching the same
  shape as base `Config` objects such as documents and catalogs.
- `root=1, len=3`: child metadata objects such as forms/templates represented
  by their own GUIDs in the extension manifest.
- `root=4, len=10` and `root=4, len=11`: form payload structures.
- `root=8` with `MOXCEL`: spreadsheet/template payload structures.
- `stream_headers`: container payloads with declared byte lengths; one verified
  case matches a BSL module by SHA1.
- `#base64` blocks: embedded textual payloads; one verified case matches HTML
  help after UTF-8 decoding and line-ending normalization.

Available XML/manifest coverage examples:

- `ДатаМобайл_Онлайн_УНФ`: 358 manifest entries, 2 XML source variants,
  2,907 XML GUIDs, 265 XML GUIDs matched to manifest object IDs.
- `ДоработкаРарус`: 461 manifest entries, 405 XML files, 315 XML GUIDs matched.
- `РасширениеДляВыгрузкиВоФронты`: 68 manifest entries, 51 XML GUIDs matched.
- `РасширениеДляЗагрузкиИзФронтов`: 97 manifest entries, 81 XML GUIDs matched.
- `фс_ДоработкиОбщее`: 120 manifest entries, 95 XML GUIDs matched.
- `фс_Отчеты`: 137 manifest entries, 98 XML GUIDs matched.

Extensions without XML dumps can still be decoded through the root manifest and
CAS files, but their semantic mapping must be proven from payload structure,
DBNames roles, and eventually generated/exported XML:

- `КонтурEDI`
- `РазвитиеФункционалаДР`
- `MCP1C`
- `ИнструментыРазработчикаTormozit`
- `Модуль1СEDI`

## Base Config Object Evidence

Added:

- `scripts/analyze_1c_config_object_xml.py`

The base configuration `Config` table uses the same object-description grammar
observed for base extension object parts:

- SQL table: `Config`.
- Key: `FileName = metadata GUID`.
- Payload: raw-deflate data.
- Text: UTF-8 with BOM.
- Parsed structure: brace tree.

Validated base objects:

- `Document.АвансовыйОтчет`
  (`84e4c0c3-2a21-4aba-a7b0-f92b3f2878ec`): `root=1`, `len=8`,
  strings/GUIDs match `Documents/АвансовыйОтчет.xml`.
- `Catalog.АвансовыйОтчетПрисоединенныеФайлы`
  (`40045984-a54c-42bd-8ea8-1c10672f40ec`): `root=1`, `len=8`,
  strings/GUIDs match `Catalogs/АвансовыйОтчетПрисоединенныеФайлы.xml`.
- `InformationRegister.СостоянияКонтрагентовБЭД`
  (`00035364-b591-4e6a-9219-e27dac18f687`): `root=1`, `len=9`,
  strings/GUIDs match `InformationRegisters/СостоянияКонтрагентовБЭД.xml`.
- `Document.ЗаявкаОтпускКабинетСотрудника`
  (`00b28285-400e-44c2-99af-3557299cfd8b`): `root=1`, `len=8`,
  strings/GUIDs match `Documents/ЗаявкаОтпускКабинетСотрудника.xml`.

This supports the working model: extension manifests add a CAS-addressed
package layer, but the actual metadata object description payload largely uses
the same grammar as base `Config` object files.

## Unified Route Index

Added:

- `scripts/build_1c_unified_object_route_index.py`
- `scripts/query_1c_unified_object_route.py`

The route index is the first adapter-shaped artifact. For each GUID it records
only deterministic routes and observed payload signatures:

- DBNames storage records.
- XML top-object records and occurrence count.
- Direct base `Config` routes when a `Config` payload file is available.
- Extension manifest/CAS routes with `object_id`, suffix, CAS key, root CAS
  file, and payload signature.

Generated report:

- `reports/1c-sql/upo/unified-object-route-index.json`

Result:

- Indexed GUID nodes: 173,034.
- GUIDs with DBNames storage: 52,668.
- GUIDs with XML top-object records: 30,587.
- GUIDs with extension manifest/CAS routes: 2,253.
- GUIDs with currently exported direct base Config routes: 4.

Control routes:

- `Document.АвансовыйОтчет`
  (`84e4c0c3-2a21-4aba-a7b0-f92b3f2878ec`): route kinds
  `base_config_direct`, `dbnames_storage`, `xml_top_object`.
- `ExchangePlan.ДатаМобайл_СписокТСД`
  (`198392a0-d153-472e-9d97-711a09dd29e0`): route kinds
  `extension_manifest_cas`, `dbnames_storage`, `xml_top_object`.
- `Form.ФормаВыбора`
  (`db752e57-6327-4bac-a97a-d5aef0004302`): route kinds
  `extension_manifest_cas`, `xml_top_object`; no DBNames storage record because
  it is a metadata child object rather than a separate SQL data table.
- `Template.Бейджи`
  (`1ea5e231-9d10-4316-9239-6f72882aeb4a`): route kinds
  `extension_manifest_cas`, `xml_top_object`; `.0` payload marker is `MOXCEL`.
- `КонтурEDI` object
  (`687571a4-0a25-4d2c-b4cb-b7317ba8de2a`): route kinds
  `extension_manifest_cas`, `dbnames_storage`; XML is absent, but the object is
  still directly reachable through SQL/CAS.

This is the desired runtime direction: the agent asks the adapter for a route,
then fetches only the required payload instead of scanning the whole
configuration.

Top matched XML kinds:

- `Enum`: 1,238.
- `InformationRegister`: 1,237.
- `Constant`: 1,126.
- `Catalog`: 779.
- `Document`: 371.
- `ScheduledJob`: 212.
- `AccumulationRegister`: 142.

This confirms the main approach: SQL `DBNames` GUIDs can be connected to real
configuration objects and Russian names through XML GUIDs without deriving
meaning from `_DocumentNN` or `_ReferenceNN` table names.

## Current Artifacts

This file is now historical research background. The active API contract is
`docs/1c-adapter-api-contract.md`; the active tool list is
`plugins/1c/tools/README.md`.

Current source/evidence builders:

- `scripts/export_1c_sql_files.ps1`
- `scripts/export_1c_sql_extensions_info.ps1`
- `scripts/inspect_1c_sql_files.py`
- `scripts/extract_1c_dbnames.py`
- `scripts/build_1c_xml_guid_index.py`
- `scripts/compare_1c_sql_xml_guids.py`
- `scripts/index_1c_sql_cas.py`
- `scripts/parse_1c_extension_zipped_info.py`
- `scripts/extract_1c_extension_cas_manifest.py`
- `scripts/build_1c_extension_inventory.py`
- `scripts/build_1c_extension_manifests.py`
- `scripts/build_1c_unified_object_route_index.py`

Current agent-facing adapter scripts:

- `scripts/resolve_1c_object.py`
- `scripts/get_1c_object_brief_context.py`
- `scripts/get_1c_object_metadata.py`
- `scripts/search_1c_object_context.py`
- `scripts/get_1c_object_artifacts.py`
- `scripts/get_1c_object_code_context.py`
- `scripts/get_1c_module.py`
- `scripts/get_1c_form_context.py`
- `scripts/read_1c_object_view.py`
- `scripts/plan_1c_task_context.py`
- `scripts/build_1c_task_evidence.py`
- `scripts/propose_1c_task_changes.py`
- `scripts/create_1c_patch_workspace.py`
- `scripts/check_1c_patch_preflight.py`

Current core reports:

- `reports/1c-sql/upo/dbnames.json`
- `reports/1c-sql/upo/xml-guid-index-combined.json`
- `reports/1c-sql/upo/sql-xml-guid-compare-combined.json`
- `reports/1c-sql/upo/unified-object-route-index.json`
- `reports/1c-sql/upo/structured-metadata-all-kinds-dbnames-summary.json`
- `reports/1c-sql/upo/predicted-column-validation.json`
- `reports/1c-sql/upo/enum-presentation-map.json`

Current task sample reports:

- `reports/1c-sql/upo/object-brief-context-prihodnaya-nakladnaya-effective.json`
- `reports/1c-sql/upo/object-metadata-prihodnaya-nakladnaya-effective.json`
- `reports/1c-sql/upo/form-context-prihodnaya-nakladnaya-effective.json`
- `reports/1c-sql/upo/module-prihodnaya-nakladnaya-object-effective.json`
- `reports/1c-sql/upo/task-plan-prihodnaya-nakladnaya-ceny-srok.json`
- `reports/1c-sql/upo/task-evidence-prihodnaya-nakladnaya-ceny-srok.json`
- `reports/1c-sql/upo/task-change-proposal-prihodnaya-nakladnaya-ceny-srok.json`
- `reports/1c-sql/upo/patch-workspaces/prihodnaya-nakladnaya-ceny-srok/manifest.json`
- `reports/1c-sql/upo/patch-preflight-prihodnaya-nakladnaya-ceny-srok.json`

## Open Risks

- Some extension XML exports may be absent; SQL/CAS evidence must then fill the
  gap without guessing from physical table names.
- Direct SQL writes to configuration storage are not accepted as safe. The
  supported write path is an extension patch workspace plus human/apply gates.
- More object kinds need read-view smoke coverage, but the adapter API must
  remain kind-neutral.

## Next Steps

1. Keep the current adapter surface stable: resolve by 1C name, then read
   metadata, form, module, data view, and patch workspace evidence.
2. Expand SQL/CAS-backed form/module extraction where XML export evidence is
   missing.
3. Add regression tests for all major metadata object kinds through the same
   `effective/base/extension` view model.