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.

docs/1c-sql-protocol/rules/evidence-and-safety.md

@@ -0,0 +1,55 @@
+# Evidence and safety rules
+
+## Evidence levels
+
+| Level | Meaning | Permitted use |
+|---|---|---|
+| Observed | Read from live SQL once | Diagnosis only |
+| Reproduced | Seen in independent before/after saves | Decoder rule candidate |
+| Round-trip proven | Decode → unchanged encode returns identical bytes | Safe read/transform component |
+| Activation proven | A human Configurator applied it and active SQL verified it | Controlled `upo_test` writer component |
+
+No rule may be promoted because a name, suffix, or payload shape “looks right”.
+
+## Codec boundary
+
+The configuration-storage specification is the adapter's sole authority for
+decoding and encoding. A writer is enabled only when the relevant version of
+that specification defines every changed byte and every dependent integrity
+atom, and round-trip evidence proves the encoder. Any remaining opaque atom is
+preserved byte-for-byte; if a requested edit requires changing it, the write is
+unsupported until the specification is extended by a controlled experiment.
+
+## Allowed mutation boundary
+
+- The adapter runtime uses SQL only.
+- `upo_test` may receive controlled writes to `ConfigSave` and
+  `ConfigCASSave` only.
+- `Config`, `ConfigCAS`, and application data are never direct write targets.
+- A write must have a live target resolution, optimistic SHA-1 precondition,
+  reversible evidence, atomic transaction, and readback verification.
+- Repository coordination is a separate policy; an adapter marker is not a
+  native repository lock.
+
+## Exact edits
+
+For BSL fragment replacement, provide one of:
+
+- an old fragment occurring exactly once;
+- a larger unique surrounding fragment;
+- a proven structural container path/offset plus original SHA-1.
+
+If a fragment occurs zero or more than once, do not choose arbitrarily. Return
+the count and candidate contexts. Deletion follows the same rule.
+
+## What an agent must report
+
+Every proposal and applied result must state:
+
+- active and saved layers used;
+- public target and SQL evidence retained internally;
+- original and new SHA-1 values;
+- paired files changed;
+- exact-match count;
+- rollback reference;
+- Configurator refresh guidance.