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