# 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/`.