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

name, description

name	description
onec-sql-extension-adapter	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 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.