Initial SQL-only 1C adapter baseline

2026-07-22 03:03:47 +03:00
commit e2503b77e7
545 changed files with 184711 additions and 0 deletions
@@ -0,0 +1,91 @@
+# 1C Agent Coding Contract
+
+This contract is the default rule set for coding agents that work through the
+1C adapter.
+
+## Default View
+
+- Read current code and metadata from the working saved-state layer by default.
+- For REST calls, use `state=working`.
+- For MCP calls, use `source_state=working`.
+- Treat saved-state objects as current programming state even when they are not
+  activated yet.
+- Objects can exist only in saved-state and can later be activated or canceled.
+  Do not hide them from the agent view.
+
+## Compare Views
+
+- Use `state=both` or `source_state=all` only when the task needs a comparison
+  with activated runtime state.
+- Show the effective working text first.
+- Mark comparison details explicitly:
+  - `saved_state`: saved and not activated;
+  - `active`: activated runtime state;
+  - `text_source`: which layer produced the returned text;
+  - `comparison.differs`: whether both layers exist and differ.
+
+## Read Workflow
+
+Use public names and selectors:
+
+1. `extension.objects.find` with `state=working` to find extension objects.
+2. `code.search` with `state=working` to find routines or fragments.
+3. `code.read` with `state=working` to read the module or routine.
+4. `code.read` with `state=both` only for an explicit saved-vs-active check.
+
+Agents should ask for and report object names, routine names, and code text.
+They should not ask users for SQL tables, storage file names, stream indexes, or
+saved-state write flags during normal coding work.
+
+## Write Workflow
+
+All normal BSL writes go through `code.write`.
+
+Supported public edit shapes:
+
+- replace a whole module with `module_text`, `full_text`, or `code`;
+- replace one procedure or function with `routine_name` and `routine_text`;
+- replace one unique fragment with `old` and `new`; when `routine_name` is
+  supplied, the adapter scopes the replacement to that routine.
+
+`code.write` saves into saved-state automatically. A coding agent should simply
+say "save this code" and send the desired code text. It must not ask whether SQL
+saved-state apply flags are allowed.
+
+Every successful `code.write` response must show:
+
+- `write_mode.target=saved_state`;
+- `write_mode.activation_state=not_activated`;
+- `write_mode.production_apply=false`.
+
+## Hidden Storage Details
+
+The form module container marker `///----` is adapter-owned storage syntax.
+Public `code.read` and `code.search` responses must not expose it as BSL.
+Full-module writes must preserve the marker internally when the saved form
+payload requires it.
+
+Low-level methods such as `metadata.module.write_apply`, `metadata.write`, SQL
+tables, stream refs, and saved-state apply flags are diagnostic tools. They are
+not the default programming interface for agents.
+
+## Agent Response Shape
+
+When reporting a working saved-state result to a user, prefer concise wording:
+
+```text
+В working/save вижу формы:
+t_Форма
+tt_Форма3
+ФормаЭлемента
+
+Код читается из saved_state, еще не активирован.
+```
+
+If the user asks to compare active and saved state:
+
+```text
+Working/save: найдено, источник saved_state, не активировано.
+Active: не найдено.
+Эффективный код для программирования сейчас берется из saved_state.
+```