---
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.
