llm/docs/1c-sql-protocol/rules/agent-contract.md

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.