Acceptance: verify round-trip restoration for core OpenROAD component types #8

Purpose

This issue is not a general checklist for whether Gorak can read or edit OpenROAD component types.

Gorak already declares readable/editable support for the core component types below. The purpose of this issue is to build a deliberate acceptance suite that proves each supported source form can survive the complete Gorak round trip without losing source meaning or required metadata.

In other words, for each supported type we want evidence for the contract:

authoritative OpenROAD source → Gorak readable source → fresh/independent OpenROAD source database → authoritative re-export

and we want the final source to be semantically equivalent to the original, with any expected canonicalisation explicitly understood and tested.

Currently supported readable component types

Create representative acceptance fixtures and live round-trip evidence for:

• Frames (framesource)
• 4GL procedures (proc4glsource)
• Userclasses (classsource)
• 3GL procedures (proc3glsource)
• Constants (constsource)
• Globals (globsource)
• Include/shared scripts (scriptsource)
• Ghost frames (ghostsource)

For every type, the acceptance case should exercise more than a trivial empty component where practical. Include the metadata, scripts/declarations, attributes/methods/tagged values, defaults, layout data, or other source structures that matter for that component type.

Acceptance criteria

For each component type:

• Export a representative authoritative source object from OpenROAD.
• Encode it into Gorak's tracked readable representation.
• Verify a fresh checkout contains everything required to reconstruct it; no original .openroad cache or author-machine state may be required.
• Push/reconstruct it into an independent disposable OpenROAD source database.
• Re-export the reconstructed source using the authoritative OpenROAD path.
• Compare the reconstructed result with the original source contract and verify semantic equivalence.
• Run a second export/reconstruction cycle where useful to prove the result is stable/canonical rather than merely accepted once.
• Compile/open/run the reconstructed object where that provides meaningful additional acceptance evidence.
• Record any intentional canonicalisation or OpenROAD-generated differences explicitly rather than silently weakening the comparison.
• Add automated regression coverage for every bug or representation gap discovered by the live acceptance case.

Frames should include explicit Workbench visual acceptance in addition to machine comparison because layout/default behaviour can be semantically important even when serialized source appears equivalent.

External classes/libraries

extlibsource is not currently in Gorak's declared editable SUPPORTED_TYPES set, so do not mark it as already covered by the same contract.

• Investigate external classes/libraries (extlibsource) separately and decide what support/round-trip contract Gorak should provide before adding it to the accepted core set.

Scope distinction

Track the normal readable/XML-backed synchronization path separately from experimental native/direct-storage work. Passing this acceptance suite should prove the ordinary public Gorak source contract; it should not depend on experimental ii_srcobj_encoded decoding or native restore functionality.

Field templates and other OpenROAD source forms remain out of scope until they are deliberately added to the supported source contract.