Initial project import

.codex/skills/onec-sql-extension-adapter/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: onec-sql-extension-adapter
+description: Develop, diagnose, or test this repository's SQL-only 1C adapter, especially extension saved-state preparation and public code writes. Use only inside the adapter repository; do not use it for ordinary client projects that consume the adapter API.
+---
+
+# 1C SQL Extension Adapter Development
+
+Use this project-local skill while changing or diagnosing the adapter itself. It protects the boundary between a simple client API and the adapter's private SQL implementation.
+
+## Two contracts — never mix them
+
+### Client / consuming-project contract
+
+Callers use only public high-level operations and business selectors: `base_id`, extension name, object reference/name, requested change, and normal confirmation scope. They may read or write through the adapter, but they must not know or supply SQL table names, module references, stream indexes, file keys, hashes, containers, or serialization details.
+
+An absent row in `ConfigCASSave` is not a caller problem. A caller must never be told to create it, save an extension again, initialize Configurator, or discover a technical route merely because the adapter failed to prepare saved state.
+
+### Adapter-development contract
+
+The adapter owns all SQL state preparation. For an extension write it must, from public selectors, resolve the exact extension layer, determine the writable module, create missing `ConfigCASSave` rows through the already proven copy path, write, reread, and report the result. Its implementation may inspect SQL evidence, but must never invent a container, mapping, payload, or reverse codec.
+
+## Mandatory investigation workflow
+
+1. Reproduce using the same public request that a client uses. Preserve its request ID and timings.
+2. Confirm the target through public read/search APIs: object owner, extension origin, module ordinal, and the exact old text. Do not infer from names alone.
+3. Inspect active and saved state independently. Classify each component as present-and-matching, absent, mismatched, ambiguous, or unreadable.
+4. Select the storage-key layout from live evidence in that base and extension family. A successful base-configuration `ConfigSave` path does not prove an extension `ConfigCASSave` path; equally, one canonical descriptor layout does not license renaming hash-keyed rows in another layout. A hash-keyed active extension root may itself decode to the proven logical file map; only then may it be mapped to canonical saved-state names.
+5. If the project has already proven the copy codec for the selected layout, use it for an absent component. Do not discard that proof merely because a new generic resolver expects a different descriptor or `__configinfo`. If a genuinely new layout is encountered, return a protocol-specific blocked result and develop it; never turn that gap into a Configurator instruction for the client.
+6. Test the exact public route with `plan`, then a controlled `apply_and_rollback` on `upo_test`. Verify readback and cleanup. Only then enable `apply_and_verify` for the route.
+
+Read [the protocol and test reference](references/protocol-and-test-matrix.md) before altering saved-state preparation or interpreting its errors.
+
+## Error taxonomy
+
+| Result | Meaning | Required next step |
+|---|---|---|
+| `public_write_route_unresolved` | Public-to-internal resolver did not identify one safe route. | Repair the resolver using live evidence; do not ask the caller for coordinates. |
+| `extension_saved_state_prepare_protocol_unproven` | A needed saved-state part is missing and the reverse codec has not been proven for this layout. | Adapter protocol development and fixture testing. |
+| Transport closure / timeout | Request lifecycle or deployment interruption. | Correlate REST and MCP audit events before diagnosing SQL. |
+| `applied: true` | SQL reread matched the requested write. | Do not claim Configurator acceptance or activation without human confirmation. |
+
+## Non-negotiable rules
+
+- Keep extension scope exact. Same GUID/name in another extension is not permission to write there.
+- Treat diagnostic SQL and raw file keys as adapter-private evidence, never as public API inputs.
+- Log request ID, public selectors, resolver phase, safe state classification, duration, result, and sanitized failure details. Do not log secrets or raw content unnecessarily.
+- Do not automate, emulate, or require Configurator. A human confirmation is the only evidence of Configurator visibility/activation.
+- `upo_test` is the sole default mutation target. Treat `upo` as read-only unless the user explicitly authorizes a write.
+- Update the API contract and runbook whenever public behavior, error meaning, or test coverage changes.
+
+## Known dead ends in this project
+
+- **Do not require a Configurator "initialisation" or another save because a target `ConfigCASSave` row is absent.** Missing rows are the normal first-write case handled inside the adapter.
+- **Do not replace the proven `ConfigCAS → ConfigCASSave` copy route with an unconditional canonical-name map.** A live hash key is not itself a logical filename. Canonical names are permitted only after decoding the selected extension root and proving its exact `O` / `O.0` SHA-1 map and extension GUID. For that evidenced family, copy `root → E__configinfo`, `O → E__O`, and `O.0 → E__O.0` atomically; otherwise return `extension_saved_state_prepare_protocol_unproven`.
+- **Do not copy active extension hash keys into `ConfigCASSave` under the same hash names and call it verified.** In `upo_test/фс_Отчеты` this passed SQL reread but Configurator continued to select `ConfigCAS`. SQL readback alone is not working-copy evidence.
+- **Do not send an object-module canonical `.0` path back through generic metadata path decoding when a public object selector or concrete stream already resolved it.** It is a BSL container, not a metadata tree path; route it directly through the extension saved-state resolver.
+- **Do not let a plan-only resolver redefine the write protocol.** `plan` may say preparation is needed; apply must execute the proven preparation route after its normal gate.
+- **Do not make a client retry with a module reference or storage coordinates.** That only hides the adapter regression and breaks every consuming project.

.codex/skills/onec-sql-extension-adapter/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "1C SQL Adapter Development"
+  short_description: "Safe development of 1C SQL extension writes"
+  default_prompt: "Use $onec-sql-extension-adapter to diagnose or extend the adapter safely."

.codex/skills/onec-sql-extension-adapter/references/protocol-and-test-matrix.md

@@ -0,0 +1,36 @@
+# Extension saved-state protocol and test matrix
+
+## Evidence threshold
+
+A writable extension path is proven only when all of the following are evidenced in a live test base:
+
+1. The public selector resolves to exactly one extension-owned object and module.
+2. The active representation and extension layer are identified without cross-layer ambiguity.
+3. The corresponding saved-state mapping is observed, including how an absent part is prepared.
+4. The exact inverse codec is exercised on a controlled target.
+5. Readback proves the requested text replacement.
+6. `apply_and_rollback` restores the edited stream and removes every adapter-created overlay item.
+7. Before enabling a new layout generally, a human confirms that Configurator displays the saved-state change.
+
+Never infer step 3 from an unrelated base object, a different extension, a filename convention, or an assumed `__configinfo` record. Raw saved-state keys may be hash-based or layout-specific. A hash key may be converted to a canonical saved-state name only when the selected active root itself has been decoded and contains the exact logical `O` / `O.0` to SHA-1 mapping. This is evidence for the three-file mapping, not a naming convention.
+
+## Minimum regression matrix
+
+| Case | What it proves |
+|---|---|
+| Base configuration saved write | Base `Config` to `ConfigSave`; not extension behavior. |
+| Extension with an existing saved module | Read/write codec for an existing extension saved entry. |
+| Extension module absent from saved state | Internal automatic preparation of a missing entry. |
+| Hash-keyed active extension root that decodes to a logical file map | Create exactly `root → E__configinfo`, `O → E__O`, `O.0 → E__O.0`; preserve root service atoms verbatim. |
+| Opaque hash-keyed extension layout | Return `extension_saved_state_prepare_protocol_unproven`; never insert same-name hash copies. |
+| Canonical descriptor overlay, if evidenced | Use its paired-container codec only for that observed layout. |
+| Extension with no usable saved overlay | Correct blocked result until a codec is proven; no caller workaround. |
+| Duplicate-looking object in another extension | Exact extension isolation. |
+| `apply_and_rollback` | Write, reread, rollback, and cleanup. |
+| Docker replacement during a long call | Graceful request lifecycle and audit correlation. |
+
+## Safe public acceptance test
+
+The test request contains only public fields: base ID, extension name, object ref/name, module ordinal or unambiguous module selector, `old`, `new`, mode, and normal repository-coordination scope. It must not contain `ConfigCASSave`, `module_ref`, stream index, file key, table name, SQL text, or a serialization payload.
+
+Success means `applied: true` and a subsequent public search/read no longer finds `old` in the selected module. This proves SQL readback only. Configurator visibility requires separate human confirmation; activation/save remains outside this SQL-only adapter.