# Contract for an agent using the 1C SQL adapter

The agent is a consumer of evidence returned by the adapter. It must never
turn a plausible interpretation into a fact.

## Fundamental adapter rule

The adapter is a **SQL codec**, not an expert system for 1C. It reads and
writes only according to the versioned configuration-storage specification
that has been decoded from live SQL and recorded in this knowledge base.
It may expose a semantic name only when that mapping is proven by the decoder.
For an unknown carrier, field, child object, byte range, checksum, or service
atom, the only valid result is `unsupported`, `partial`, or `ambiguous` with
the observed evidence. It must not synthesize a structure, BSL, or value to
make an operation appear complete.

## Required behaviour

- Start from a public 1C name/ref supplied by the user.
- Ask the adapter to resolve the live route; internal GUIDs, SQL numbers and
  file names remain adapter implementation details.
- Use public `code.read`, `code.search`, and `code.write` for normal BSL work.
  Never pass or request `ConfigCAS`, `ConfigCASSave`, a payload hash, a
  canonical saved filename, or a stream index. Those are diagnostic evidence,
  not an agent-facing selector contract.
- Read the target bytes before proposing any edit.
- Quote the exact proven fragment, its count, and the selected layer.
- For a write, require a plan/preflight and retain the returned rollback and
  refresh guidance.
- State `unknown`, `ambiguous`, or `protocol_incomplete` when evidence is
  absent. Ask for a larger fragment or a human Configurator action instead of
  guessing.

## Forbidden behaviour

- Invent BSL procedures, form controls, field paths, joins, storage tables,
  module streams, extension ownership, or `__configinfo` atoms.
- Claim that a SQL saved-state edit is active before active-layer verification.
- Claim a repository lock merely because an adapter request was recorded.
- Tell the user that the Configurator UI has refreshed unless the required
  close/reopen boundary was completed by the human.
- Write directly to active configuration or application tables.
- Work around a public-route failure by retrying against an internal module
  reference. Report the public `not_found`, `ambiguous`, `unsupported`, or
  `protocol_incomplete` result so the adapter can be corrected.

## Write-result language

Use the adapter’s `configurator_refresh` object verbatim in human-facing
instructions. Do not collapse `object`, `extension`, and `configuration` into
the same generic “restart” advice.