129 lines
6.3 KiB
Markdown
129 lines
6.3 KiB
Markdown
# Extension saved-state overlay (`ConfigCASSave`)
|
||
|
||
> **Deployment and integration-test target:** `adapter-1c-mcp` runs on
|
||
> `docker.cin.su`. Use that host for deployment and live adapter checks;
|
||
> `test-docker` is staging only and requires an explicit request.
|
||
|
||
## Canonical object-module overlay: activation evidence
|
||
|
||
For extension GUID `E` and object GUID `O`, the overlay uses:
|
||
|
||
```text
|
||
E__configinfo
|
||
E__O
|
||
E__O.S
|
||
```
|
||
|
||
This route is now human-confirmed in two independently selected extension
|
||
object-module cases on `upo_test`:
|
||
|
||
| Extension | Object | Public test | Human confirmation |
|
||
|---|---|---|---|
|
||
| `test2` | Common form/module fixture | prior `change-10` experiment | Configurator applied overlay into `ConfigCAS` |
|
||
| `фс_Отчеты` | `Report._ПоступлениеТовара` object module | `//Пример - 3` → `//Тест - 3` | Configurator displayed `//Тест - 3` in the extension editor |
|
||
|
||
The descriptor and module are separate objects. A pending extension may contain
|
||
only rows changed manually by the user; the root `__configinfo` map can still
|
||
refer to unchanged active parts. An adapter must preserve those rows and all
|
||
their map entries.
|
||
|
||
For the separately observed hash-keyed overlay, the equivalent boundary is the
|
||
live extension `root_cas_key`: an automatic first-write copy must include that
|
||
root manifest together with the selected object parts. A leaf module key alone
|
||
is not a complete working-copy selection boundary.
|
||
|
||
## Hash-keyed first-write status
|
||
|
||
In `upo_test` / `фс_Отчеты`, copying the complete evidenced hash-key group
|
||
from `ConfigCAS` to `ConfigCASSave` under unchanged hash names produced a
|
||
byte-for-byte SQL readback, but Configurator continued to read the active
|
||
`ConfigCAS` module. Therefore a same-name hash copy is **not** a working-copy
|
||
protocol.
|
||
|
||
The active extension root has since been decoded as the equivalent logical
|
||
file map: it contains `"<object-guid>[.suffix]",Base64(SHA-1(payload))`
|
||
pairs, including the target descriptor and the selected BSL module. For the evidenced
|
||
object-module family the initial overlay maps exactly three active files to:
|
||
|
||
```text
|
||
root manifest -> E__configinfo
|
||
object descriptor -> E__O
|
||
object `.S` module -> E__O.S, where `.S` is the suffix of the exact resolved
|
||
BSL stream (for example `.0` or `.2`)
|
||
```
|
||
|
||
The adapter must reject any incomplete route and must never fall back to
|
||
unchanged hash names. The map and all service atoms are copied verbatim on the
|
||
first overlay; subsequent writes update only the proven file-SHA reference.
|
||
|
||
### Exact prepare/write algorithm
|
||
|
||
1. Resolve the extension, public object `O`, active descriptor and active `.S`
|
||
BSL stream from the extension manifest.
|
||
2. Decode the selected active root. Require exactly one map entry for `O` and
|
||
exactly one for the selected `O.S`; require their SHA-1 values to equal the selected
|
||
active descriptor/module payloads.
|
||
3. If the overlay is absent, atomically copy only those three sources as
|
||
`E__configinfo`, `E__O`, and `E__O.S`. Do not copy the whole extension.
|
||
4. If it exists, preserve pending rows and maps; never overwrite another
|
||
change. Prepare may add only missing object parts.
|
||
5. Replace BSL only after the exact old fragment, source SHA-1, extension,
|
||
public object and module stream agree. For an object module, update the one
|
||
`O.S` SHA-1 value in `E__configinfo` in the same transaction and preserve
|
||
service atoms byte-for-byte.
|
||
6. Re-read the BSL and both changed rows. `apply_and_rollback` must restore
|
||
the module and remove adapter-created first-overlay rows.
|
||
|
||
`code.write` callers provide only public selectors and the replacement. The
|
||
adapter owns storage mapping, preparation, paired update and rollback.
|
||
|
||
## Rejected approaches (retain as regression hazards)
|
||
|
||
- Copying `ConfigCAS` hash rows to `ConfigCASSave` under the same names. It
|
||
produced correct SQL readback but Configurator ignored it for `фс_Отчеты`.
|
||
- Writing only the BSL module payload. The map continues to point to the old
|
||
SHA-1 and Configurator reports a collection/hash-version error.
|
||
- Generating `__configinfo`, its service atoms, or logical file mappings from
|
||
names alone. The adapter must first decode the actual selected root map.
|
||
- Replacing the entire compressed module container. Only the declared BSL
|
||
prefix codec is allowed; opaque stream tail bytes must remain unchanged.
|
||
- Resolving an already selected object-module path through generic metadata
|
||
path traversal. Its module suffix is a BSL container, so this can fail before the
|
||
saved-state writer sees the exact module route.
|
||
|
||
## Proven incremental write protocol
|
||
|
||
For a form module change:
|
||
|
||
1. Read the current `E__configinfo` from `ConfigCASSave` if it exists;
|
||
otherwise derive a complete initial overlay from active `ConfigCAS`.
|
||
2. Resolve the form descriptor and module hashes from that map.
|
||
3. Patch the module with a unique BSL anchor and lossless payload codec.
|
||
4. Replace exactly the Base64(SHA-1(raw module bytes)) value paired with
|
||
logical name `O.0` in `E__configinfo`.
|
||
5. Preserve every unrelated map entry and service atom byte-for-byte.
|
||
6. In one transaction insert missing `E__O`/`E__O.0` rows and update
|
||
`E__configinfo`, with compare-and-set SHA-1 preconditions.
|
||
|
||
The adapter core exposes a pure `build_extension_saved_state_pair_plan` helper
|
||
for steps 3–5. It refuses a plan when the ConfigInfo map does not reference the
|
||
current saved stream, so a later transaction cannot silently overwrite a
|
||
divergent human overlay.
|
||
|
||
For an already existing single-part pending stream, the paired writer locks the
|
||
module and `__configinfo`, verifies both preconditions, writes both payloads
|
||
and their `DataSize` values in one transaction, keeps independent rollback
|
||
evidence, and verifies both rows afterwards. `__configinfo` itself is never a
|
||
primary editable stream. Missing overlay rows still use the separate prepare
|
||
route before this writer may update them.
|
||
|
||
This protocol was activation-proven in the `test2` experiment. It is not yet
|
||
a universal proof for every 1C platform version or every extension object
|
||
class; new classes require their own evidence record.
|
||
|
||
## Important overlay behaviour
|
||
|
||
An external SQL overlay write does not set the Configurator’s in-memory dirty
|
||
flag. Its visibility therefore depends on the current session. See
|
||
[Configurator refresh behaviour](../operations/configurator-cache.md).
|