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

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.