m/llm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9d7c4f38f32afd8713a381383748d8a67e2a7299
llm/docs/1c-sql-knowledge-adapter.md
T

22 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink