Initial SQL-only 1C adapter baseline

plugins/1c/parser/README.md

@@ -0,0 +1,83 @@
+# 1C SQL Parser Core
+
+This package contains universal parser primitives for 1C SQL metadata storage.
+It must not hardcode object names, GUIDs, or table numbers from a concrete
+infobase.
+
+## Modules
+
+- `payload.py`: compression decoding, text decoding, and generic brace-tree
+  parser.
+- `dbnames.py`: parser for `Params/DBNames*` files.
+- `extensions.py`: parser for `_ExtensionZippedInfo` blobs and extension root
+  CAS manifests.
+- `config_object.py`: conservative identity extraction for top-level metadata
+  object payloads.
+- `storage.py`: mechanical DBNames role to physical SQL name route helpers.
+- `config_sections.py`: mechanical section summaries for Config brace trees.
+- `child_records.py`: mechanical child-record boundary detection for section
+  containers.
+- `xml_metadata.py`: small XML metadata extractor used as validation oracle.
+- `structured_metadata.py`: evidence-based projection from Config payloads to
+  normalized metadata records.
+
+## Current Guarantees
+
+The parser can currently:
+
+- decode raw-deflate Config payloads;
+- parse brace trees without semantic guesses;
+- read DBNames records as `{guid, storage_role, sql_number}`;
+- read extension root CAS keys from `_ExtensionZippedInfo`;
+- read extension manifest `object_id -> cas_key` entries.
+- extract top-level metadata identity when the observed identity block is
+  present: GUID, name, localized synonyms, and evidence path.
+- map DBNames table-like roles to physical table-name candidates and field roles
+  to physical column-name candidates.
+- summarize Config tree sections by path, shape, strings, and GUIDs without
+  semantic labels.
+- map repeated object-kind sections to XML metadata categories by exact
+  name/synonym/UUID evidence.
+- project proven sections into normalized metadata records with per-item
+  evidence paths.
+- attach child metadata items to concrete section record paths when a declared
+  child-record container is present.
+
+## Non-Goals At This Layer
+
+This layer does not know concrete configuration objects. For example, it does
+not know that a particular database has `Document.АвансовыйОтчет`.
+
+Concrete infobase snapshots are built by applying this parser to SQL files and
+then resolving routes.
+
+## Smoke Test
+
+From repository root:
+
+```powershell
+$env:PYTHONIOENCODING='utf-8'
+@'
+from pathlib import Path
+import sys, json
+sys.path.insert(0, str(Path('plugins/1c').resolve()))
+from parser.dbnames import parse_dbnames_file
+from parser.payload import parse_payload_file, root_signature
+from parser.storage import storage_routes
+
+db = parse_dbnames_file(Path('reports/1c-sql/upo/Params/DBNames'))
+config = parse_payload_file(Path('reports/1c-sql/upo/Config-samples/84e4c0c3-2a21-4aba-a7b0-f92b3f2878ec'))
+print(len(db['records']), root_signature(config['tree']))
+print(storage_routes(db['records'][:1])[0])
+'@ | python -
+```
+
+## Current Use
+
+This package is a library layer for current adapter rebuild scripts. Normal
+agent work should not call these primitives directly; use the tools listed in
+`plugins/1c/tools/README.md`.
+
+The latest adapter flow resolves objects by 1C names, then reads metadata,
+forms, modules, data views, and patch workspaces through the public scripts in
+`scripts/`.