52 lines
2.5 KiB
Markdown
52 lines
2.5 KiB
Markdown
# 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.
|