XML exports are development-time evidence only. They may be analyzed by repository scripts to infer and test generic SQL payload decoders, but the running connector is configured only with a SQL entry for base_id. It does not mount or read XML and rejects XML path arguments in runtime requests.

Standalone boundary

This directory is the service boundary for the adapter. It is still developed inside the current monorepo, but it should be kept movable as an independent project.

Service-owned files:

adapter_1c_server.py
contracts/openapi.yaml
policies/*.yaml
Dockerfile
docker-compose.yml
.env.example
pyproject.toml
service.yaml
sibling package ../parser

Repository-owned integration files:

plugins/1c/mcp/adapter_1c_mcp.py
plugins/1c/agent/
plugins/1c/rag/
plugins/1c/training/
top-level health and contract scripts under scripts/

The connector must not depend on RAG, training, or agent code. MCP and agent code may depend on the connector contract.

Local Run

From plugins/1c:

python connector/adapter_1c_server.py

From plugins/1c/connector after installing package dependencies:

python adapter_1c_server.py

Health without a concrete base:

Invoke-RestMethod http://localhost:8011/health

Live database calls require base_id and SQL connection configuration.

Configuration repository operations

Repository access is configured per base_id, preferably as a repository object inside the same JSON entry used by ONEC_SQL_BASES_JSON_FILE. The repository backend is never inferred from a bridge name or endpoint. Set backend explicitly to direct or karman_bridge; both backends execute the standard 1C Designer repository commands, while a Karman/Filebox bridge only relays the native opaque TCP stream.

See config/1c_repository_bases.example.json for a secret-free example. Passwords are resolved only from the configured environment-variable names. The adapter does not return them or store them in lock-session state.

When the adapter runs in a Linux container and Designer is installed on the Windows Docker host, use runner.kind=http. Run scripts/run_1c_repository_runner.py on Windows with its own external base configuration (example: config/1c_repository_runner_bases.example.json). The container sends only base_id, action, public object names, and commit comment; infobase/repository credentials remain on the Windows runner. Protect the runner with ONEC_REPOSITORY_RUNNER_TOKEN and a host firewall rule limited to the Docker host/container network.

The guarded workflow is:

repository.status (optionally probe=true);
repository.lock.plan with public 1C object names;
repository.lock with allow_repository_lock=true;
pass the returned lock_session_id to write preflight/apply;
repository.commit.plan and explicit repository.commit, or repository.unlock for only that adapter-owned session.

Apply operations are blocked for a repository-configured base unless an active adapter-owned lock session is supplied. Structural add/delete/rename plans are kept blocked for confirmation because parent and reference objects can also be required.

Docker Run

Create a local .env from .env.example, keep real passwords outside git, and run:

docker compose -f plugins/1c/connector/docker-compose.yml --env-file plugins/1c/connector/.env up -d --build

The compose build context is plugins/1c because the adapter imports the sibling parser package. If this service is moved to a separate repository, copy plugins/1c/parser into that repository or publish it as a package.

Standalone Extraction Checklist

When the adapter is eventually moved out of this monorepo:

Copy connector/ and parser/.
Keep contracts/openapi.yaml versioned with releases.
Keep policies with the service.
Keep service.yaml, pyproject.toml, Dockerfile, docker-compose.yml, and .env.example.
Move or duplicate contract checks that assert public behavior: check_1c_write_plan_contract.py, check_1c_extension_action_contract.py, check_1c_module_origin_contract.py, and check_1c_code_symbol_contract.py.
Do not move RAG datasets, training configs, or agent prompts into the adapter service unless they become runtime dependencies.

Live database access

Web management

The runtime SQL connection list can be viewed and edited at http://<adapter-host>:8011/admin/. The screen supports adding, editing, and deleting entries and writes them atomically to ONEC_SQL_BASES_JSON_FILE (normally /data/onec-sql-bases.json). Production-style deployments should set ONEC_ADAPTER_SERVICE_TOKEN; the browser keeps it only in session storage. For the isolated test profile, ONEC_ADAPTER_ALLOW_UNAUTHENTICATED_ADMIN=true explicitly permits access without a token. Stored SQL passwords are never returned by the API in either profile.

When ONEC_SQL_BASES_JSON is set directly, web editing is disabled because the environment value would override the file. Move the connection map to the configured JSON file before using the screen.

The adapter is not tied to one 1C database. Requests that read database-specific sources must pass base_id; otherwise the adapter returns base_id_required.

Mandatory SQL base access rule

base_id is the required settings key. Its entry contains the SQL server IP or host, SQL database name, login, and password (preferably through password_env). The adapter uses only that entry's existing credentials. It must never create or change SQL logins, database users, roles, or permissions.

Application data and the metadata structure are read-only. The only SQL write exception is a reviewed metadata saved-state change:

base configuration metadata → ConfigSave;
extension metadata → ConfigCASSave.

The exception does not permit writes to application-data tables, Config, or ConfigCAS, and does not activate the saved configuration. Saved-state writes remain gated by explicit opt-in, SHA-1 precondition, backup, transaction, and readback verification. The binding policy is policies/sql-base-access-policy.yaml.

Configure every base explicitly. Prefer password_env so secrets stay outside repository files:

{
  "upo_test": {
    "server": "sql-host.example.local",
    "database": "upo_test",
    "user": "configured_login",
    "password_env": "ONEC_SQL_PASSWORD_UPO_TEST"
  }
}

Set it as ONEC_SQL_BASES_JSON and pass the password separately as ONEC_SQL_PASSWORD_UPO_TEST, or mount the same JSON outside the repository and set ONEC_SQL_BASES_JSON_FILE to its container path. There is no implicit or default database connection.

Current live methods:

query.validate
query.run
extensions.list
schema.tables.list
storage.files.list
storage.file.get
metadata.dbnames.summary
metadata.kinds
metadata.objects.list
metadata.object.get
metadata.object.properties
metadata.object.property.write
metadata.object.decode
metadata.object.parts
metadata.object.modules
metadata.object.related
metadata.object.forms
metadata.object.templates
metadata.object.template.details
templates.read
templates.analyze
templates.map
metadata.route.resolve
metadata.form.decode
metadata.object.attributes
metadata.object.full
metadata.snapshot
codec.decode
codec.encode
extension.objects.find
modules.search
modules.read

Metadata methods require base_id and read live Params, Config, and ConfigCAS storage through SQL. They do not use filesystem route indexes as a source of truth. High-level metadata methods return 1C-facing data by default: object identity, synonyms, decoded semantic sections, forms, modules, and counts. Physical SQL table names, _Fld... columns, DBNames indexes, and storage routes are internal diagnostics and are exposed only by low-level methods (storage.*, schema.*, query.*, metadata.dbnames.*) or by passing include_storage=true.

Object-scoped adapter methods accept the same public selector shapes: ref, kind + name, guid, or MCP-friendly object_type/object_name/object_guid. ref may use Russian or English qualified metadata names such as Обработка.<Name> or Document.<Name>. Client, MCP, and agent code must not add conditions for concrete object names; the adapter owns generic selector normalization.

Saved-state client calls use the same name-first selectors together with layer=base_saved_state|extension_saved_state. SQL tables, file names, GUID owners, and module handles are diagnostic continuations exposed only with include_storage=true. Every public RPC follow-up is shaped as {"method": "...", "params": {...}}; payload is not the arguments field of next_call or next_resolution.

Layer write policy:

Config and ConfigCAS are active-applied and must be treated as read-only in adapter workflows.
ConfigSave and ConfigCASSave are saved, not yet applied layers and are the only writable targets for connector staging changes.
Base vs extension mapping:
- base config → ConfigSave
- extension config → ConfigCASSave
Production apply to active layers is out of scope for this connector and requires a separate human-controlled deployment path.

Agent-facing code write rule:

BSL edits must use code.write, not low-level SQL/write helpers.
The agent passes 1C names (object_type/object_name/routine_name) or a public path such as <extension>.<form>.<routine> plus full code text.
code.write automatically targets the saved-state layer and reports write_mode.target=saved_state with activation_state=not_activated.
Use code.read/code.search with the default working state for current programming-time code; use state=both only when an explicit saved vs active comparison is needed.

metadata.object.get returns a live object card and decoded semantic sections without physical SQL/storage traces by default. metadata.object.decode also returns a 1C-facing decoded object profile by default; pass include_storage=true only when adapter diagnostics need the underlying decoded payload metadata, record containers, or DBNames/storage routes.

metadata.object.properties is the unified property endpoint for every 1C metadata kind. It selects a kind-specific SQL decoder for Configuration, Constant, DocumentNumerator, IntegrationService, CommandGroup, ScheduledJob, and DocumentJournal, and otherwise returns the generic live semantic profile. XML exports are analysis evidence only and are never a runtime source for this method or any other adapter method.

metadata.object.property.write is the name-first saved-state writer for the standard identity properties synonym and comment. Pass a public object ref or kind + name. For an existing attribute, tabular section, dimension, or resource, also pass member_ref or member_kind + member_name; the adapter resolves the exact parent/member GUIDs and serialized tree path internally. The method supports plan, apply, apply_and_verify, and apply_and_rollback, requires explicit saved-state gates, and never writes active Config/ConfigCAS. Renaming an object and member, adding/removing collection items, and adding a new synonym locale remain intentionally disabled.

metadata.object.member.add adds one new object requisite or tabular-section column (Attribute) by cloning an existing attribute in the same collection. The caller passes only template_member_ref, new_member_name, and optionally synonym/comment; the adapter generates the GUID, preserves the template's type/settings, appends to the exact declared collection, and verifies the new identity after apply. Arbitrary type construction and deletion are not supported by this first structural route.

Managed form bodies in base Config are resolved from the public form GUID to the sibling <guid>.0 SQL payload. Command-bar buttons expose public command names when their SQL binding points to a common command or a recognized platform standard command; standard reference field -5 is exposed as a public ...Ref data path. Callers never need the internal GUIDs or field codes. Element event GUIDs are converted to platform event names (for example OnChange, ChoiceProcessing, AutoComplete, Selection, and table row events) and linked to their BSL handlers when the routine is present.

metadata.object.attributes is the preferred method for "show object attributes/requisites" questions. It returns 1C metadata attribute names and tabular section names from the live Config payload. For tabular sections, it also returns decoded column names when nested column records are present. Attributes and columns include decoded type evidence (date, boolean, string, number, reference) and visible type parameters such as string length, number precision/scale, or reference type GUID. Reference type GUIDs are resolved back to live metadata object names and synonyms when the referenced type exists in the base metadata. It must be preferred over SQL table/column inspection for user-facing answers. The object can be selected by guid, by kind + name, or by 1-based ordinal within metadata.objects.list for that kind.

metadata.object.full is the preferred high-level method for agent answers like "show everything about this document". It combines the live object card, semantic sections, decoded forms, BSL module profiles, and counts in one 1C-facing response. Module profiles include routine lists and lightweight BSL structural validation. Streams with BSL markers that are not complete modules are kept, but marked as completeness: fragment_or_invalid. Full module text is returned only with include_module_text=true. The method hides SQL/storage traces by default; pass include_storage=true only for adapter diagnostics.

metadata.object.parts returns object part roles by evidence: metadata payloads, form payloads, BSL stream containers, templates, and help/html payloads. Physical Config part keys and numeric suffixes are hidden by default and returned only with include_storage=true.

metadata.object.modules lists BSL stream modules discovered in those live parts. Public responses use 1C-facing names such as Модуль объекта; physical module_id values are returned only with include_storage=true.

metadata.object.related reads live related Config records referenced by known object-kind sections, such as document forms and templates. Missing references are returned explicitly with source_missing. Physical section paths and Config file names are hidden unless include_storage=true.

metadata.object.forms resolves object forms through metadata.object.related and then reads each form's live parts, including root 4 form payloads. Public responses show form names and part roles; physical payload keys are hidden unless include_storage=true.

extension.objects.find is the preferred first step for extension-specific tasks. It searches live extension metadata by extension, query, kind, or guid, returns object/template routes, and provides safe read_selector payloads for follow-up calls. It can recover extension manifest routes even when DBNames-Ext is incomplete; owner mismatches are returned as diagnostics instead of silently hiding the object.

metadata.route.resolve resolves ConfigCAS/DBNames routes for extension objects and child objects. Use it when a previous search returned a route handle or when the caller has a CAS file name but needs the live object route.

templates.read and templates.analyze read MXL/MOXCEL templates by owner selector, template selector, or direct ConfigCAS route. They return decoded template structure: dimensions, named areas with row/column ranges, text and parameter cells, column widths, cell text identifiers, cell parameters, area-to-cell coverage, area intersections, shape variants, and explicit capability flags. merged_ranges are reserved for authoritative merged-cell records; until the MOXCEL merge record is decoded, possible merges are exposed as merged_range_candidates with confidence: low.

Use view=summary|structure|full, sections, and max_* limits to keep responses small for agents. templates.map is the compact agent-facing wrapper over templates.analyze; it defaults to view=summary and is preferred when an agent needs a quick layout map instead of all decoded lists.

1C templates are not only tabular MXL/MOXCEL documents. The 1C template constructor offers these template types:

Табличный документ - tabular document, MXL/MOXCEL. This is the current deep decoder focus.
Текстовый документ - plain or structured text payload.
Двоичные данные - arbitrary binary payload.
Active document - Active document payload.
HTML документ - HTML payload.
Географическая схема - geographic schema.
Графическая схема - graphical schema.
Схема компоновки данных - data composition schema.
Макет оформления компоновки данных - data composition appearance template.
Внешняя компонента - external component payload.

Always identify the template type before applying a decoder. Current templates.* decoding is evidence-first for tabular documents; non-tabular templates should be surfaced with type, raw route, payload markers, preview, and explicit capability gaps until dedicated decoders are implemented.

For MOXCEL reverse engineering, request sections=moxel_records,diagnostics and optionally max_moxel_records. The response includes parser-level record head counts, grouped head samples with tree_position, and coordinate-like samples. Use top_level_records with a larger max_moxel_records to inspect ordered MOXCEL sections around a specific tree position. These diagnostics are not authoritative merged-cell records. For a narrow ordered window, pass moxel_record_start and moxel_record_end, for example 431..460. Use moxel_record_heads to keep only selected top-level record head codes, for example 1049761,1413047. Add moxel_record_context to include neighbor records around matched top-level records; context records are marked with match: false. top_level_record_summary summarizes the returned record window with position range, head counts, match count, and compact numeric-field variation by head. Its field_hints are low-confidence labels such as flag_like, small_enum_like, or coordinate_or_offset_like; use them as navigation hints, not as authoritative MOXCEL decoding. numeric_field_matrix then shows those hinted/varying field values per tree_position without returning every numeric item again, and field_runs compresses adjacent equal values in that matrix. field_transitions lists the switch points between those runs. cell_style_candidates exposes inline MOXCEL text cells with nearby scalar style evidence and following metadata nodes; treat it as a controlled-diff aid until border/font/alignment semantics are decoded. top_level_shapes groups top-level records by structural shape (head, list length, numeric/string counts) and includes sample positions. top_level_shape_candidates ranks rare/long/numeric-heavy shapes as low-confidence hints for manual layout/merge investigation. Each candidate can include rank and suggested_windows with a ready request_hint for the next focused templates.map call. Pass moxel_candidate_rank to focus top_level_records on that 1-based candidate rank without copying the request hint manually. Use moxel_candidate_window_index to select a later suggested window from the same candidate when the structural shape appears more than once. Use moxel_candidate_reasons, for example coordinate_like_prefix,long_record, to return only candidates containing all requested reason codes. Use moxel_candidate_min_score to keep only candidates above a heuristic score threshold. top_level_candidate_summary reports score and reason distributions plus the count returned after filters. Use moxel_candidate_heads to filter the candidate list by head code; use moxel_record_heads when filtering actual top-level records in a focused window. Use moxel_candidate_start/moxel_candidate_end to filter candidates by their top-level positions; use moxel_record_start/moxel_record_end when filtering returned records.

metadata.form.decode decodes one form payload into an evidence-first profile: event handlers, form items, attributes, commands, auxiliary table/command-bar records, and the embedded form module summary. Form records include stable paths back into the decoded tree for names, ids, localized titles, handler names, and known platform event ids. Counts include both returned and total record numbers so truncated responses are explicit. The profile also links form events and form commands to module routines, links command buttons to commands by GUID evidence, and marks handlers as resolved or missing.

modules.search searches live BSL text and returns snippets by default. Physical module ids and payload coordinates are hidden unless include_storage=true. Every public match includes a read_selector with method: "modules.read" and either an object selector or an opaque module_ref; agents should pass that selector to the next read call instead of requesting storage details. When resolve_owners=true, results also include counts.owner_resolved, counts.owner_unresolved, and diagnostics.owner_resolution so incomplete owner recovery is explicit. modules.read reads by object selector (ref, guid, kind + name, object_type/object_name/object_guid, or kind + 1-based object ordinal) and optional 1-based module_ordinal; it also accepts module_ref from a prior search result. The response hides source and payload metadata unless include_storage=true.

code.search is the agent-facing wrapper over module search. Its items include read_selector.method: "code.read" and preserve module_ref when that is the best available safe handle. code.read can consume that selector directly.

metadata.definition.find accepts public object references such as Обработка.<Name> or Document.<Name> in query and the common object selector aliases for scoped lookup. A single metadata object match is promoted to the top-level object field and the response includes related_selectors for the next public calls (metadata.object.get, metadata.object.full, metadata.object.modules, metadata.object.form.details, code.search, modules.search, and similar selectors allowed by the object's capabilities).

metadata.adapter.audit reports recognized metadata kinds, public kind counts, missing supported kinds when include_missing=true, and unmapped DBNames roles when include_unmapped=true. Missing entries are marked presence_status=supported_absent_in_selected_base; this is a statement about the selected infobase, not a claim that the adapter lacks that kind.

Use python scripts/check_1c_metadata_kind_fixtures.py --live from the repository root to check the reproducible rare-kind fixtures. The checker does not write SQL or create metadata. The fixture manifest pins the exact Designer version and external reference commit. The companion scripts/export_1c_extension_sources.ps1 performs a read-only test2 source export with operating-system integrated authentication and exposes no infobase-user or credential arguments.

codec.decode and codec.encode are low-level lossless helpers. A no-op encode from a live source keeps the original bytes exactly; modified text/tree payloads are encoded back using the original compression and text encoding envelope.

changes.propose reads one live storage payload, checks an optional expected_sha1, applies edits to decoded brace-tree paths in memory, and returns the re-encoded payload metadata for review. It never writes to SQL. Each edit has path, value, optional node_type (auto, atom, string), and optional expected_old. For stream payloads, an edit can use stream_index with either full text replacement or replace: {old, new}, plus optional expected_contains; stream headers are rebuilt with updated byte lengths before the payload is encoded back. Diagnostic source.module_id values returned by metadata.object.modules with include_storage=true or accepted by modules.read can be used directly; when the module id includes #stream:<index>, stream edits inherit that index unless an edit specifies its own stream_index. The response includes validation, produced by re-decoding the encoded proposal in memory. For BSL stream edits, validation also runs lightweight structural checks for routine, region, and preprocessor-block balance. Stream edits can also target a whole BSL routine with routine: {operation, name, text} where operation is replace, append, or upsert. Routine edits accept expected_old_contains and expected_old_sha1 as live preconditions against the current routine text; failed preconditions reject the proposal before any encoded review artifact is returned.

storage.* methods read 1C storage rows directly from SQL tables Params, Config, ConfigSave, ConfigCAS, and ConfigCASSave. They are diagnostic building blocks for the live metadata decoder; they do not create or read filesystem indexes.

Cache policy

The source of truth is the live database. A filesystem cache may be added only as a derived acceleration layer for expensive decoded metadata/module payloads, not for current table data. Cache entries must carry base_id, source fingerprint, generation time, TTL, and fresh/stale status. If freshness cannot be proven, the adapter must re-read live SQL or return an explicit stale-cache error.

Operational runbook: docs/runbooks/1c-operational-coding.md.