Initial project import

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

@@ -0,0 +1,51 @@
+# 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.