Codegen model unification analysis

ORE Studio's ores.codegen architecture generates C++, SQL, and Qt artefacts from org-mode model files. Today the same logical entity is described by two parallel org-mode model types: a domain_entity file (ores.refdata.<name>.org) and, for some entities, a separate table file (ores.refdata.<name>_table.org). The two types are governed by the same conceptual schema (see the org entity meta model and the codegen input org-file schema reference) but are detected, parsed, and rendered through entirely separate code paths.

This split creates three problems: confusion (two files of record per entity), redundancy (overlapping column and identity declarations), and a live overwrite risk (both files can target the identical SQL output path, and the entity pathway produces a structurally incomplete file).

This document establishes the current state, inventories every model in projects/ores.refdata/modeling/, classifies each by type, enumerates the six concrete blockers to unification, and recommends a migration to a single org file per entity that carries all SQL, C++, and Qt sections.

Complete inventory of projects/ores.refdata/modeling/, classified by model type. See the entity coverage matrix for the corresponding generation coverage per layer.

1. Two incompatible SQL templates with divergent data shapes. sql_schema_create.mustache consumes table.validation_fn.tenant_scope, table.insert_trigger.validations[], table.coding_scheme, and table.has_tenant_id. sql_schema_domain_entity_create.mustache consumes the domain_entity root key and paste-marker fragments. No single template currently handles both richness levels.
2. get_model_type() and load_model() are hard-coupled to filename suffixes. Merging requires detection based on #+type: frontmatter rather than filename patterns, plus a unified parse path.
3. Entirely separate parsers. load_org_table_model() and load_org_model() share no code. The * Validation function and * Insert trigger sections are not parsed by load_org_model() at all.
4. The refdata vs refdata-cpp component split relies on the two file types being separate. Unification collapses this into one component with one discovery glob.
5. SQL-only entities must remain expressible. currency and purpose_type have no C++ layer. A unified schema needs #+sql_only: true (or equivalent) so the generator suppresses C++ profile dispatch for those entities.
6. The = C++ / * Qt= subsection is mandatory in the current load_org_model() preprocessing path. Roughly 200 lines of field derivation assume a C++ context. Making all C++ fields optional requires significant defensive template logic, or an explicit #+has_qt: false guard.

A single ores.codegen.entity file per entity, containing all SQL, C++, and Qt sections. Concretely:

• The table-specific sections move into the entity file schema: * Validation function, * Insert trigger / ** Validations, #+has_tenant_id, #+coding_scheme, and #+image_id.
• The refdata and refdata-cpp component entries in the component catalogue merge into one component with one discovery glob.
• The ores.codegen.table type is retired. The 11 *_table.org files are migrated into their entity counterparts (or, for table-only entities, into new sql_only entity files).
• A #+sql_only: true flag handles SQL-only entities (currency, purpose_type), suppressing C++ and Qt profile dispatch.
• The SQL overwrite risk is eliminated: one file, one SQL output path, one template capable of the full validation-function and insert-trigger body.

The unified file schema is governed by the org entity meta model and the variability (profile) metamodel, with sql_only and has_qt as new variability points.

The recommended order minimises overwrite risk during the transition and keeps the generator runnable at each step.

1. Detection by frontmatter. Change get_model_type() to read #+type: rather than the filename suffix. Keep the filename-suffix fallback temporarily so existing files still resolve. This unblocks blocker 2 without moving any content.
2. Unify the SQL template. Extend sql_schema_domain_entity_create.mustache (or fold both into a single template) so the domain_entity data shape carries the full validation-function body and insert-trigger validations — sourced from the migrated sections, not the paste-marker stub. This retires the distinction at the template layer (blocker 1).
3. Merge the parsers. Teach load_org_model() to parse the * Validation function and * Insert trigger sections, and to populate has_tenant_id, coding_scheme, and image_id. Reuse the logic from load_org_table_model(); then delete the table loader (blocker 3).
4. Add the variability guards. Introduce #+sql_only: true and #+has_qt: false. Make C++ and Qt field derivation conditional on these flags so SQL-only entities and C++-without-Qt entities are expressible (blockers 5 and 6).
5. Migrate content, one entity at a time. For each of the 9 dual-file entities, move the _table.org sections into the entity file, verify the generated SQL is byte-identical to the table-pathway output, then delete the _table.org file. For the 2 table-only entities (currency, purpose_type), create sql_only entity files and delete the table files. Use the domain entity evaluation checklist and the entity commissioning process to validate each migrated entity.
6. Collapse the components. Merge refdata and refdata-cpp into one component with a single discovery glob over ores.refdata.*.org (excluding junctions and the module index). Remove the dead models_dir entries (blocker 4).
7. Retire the table type. Once no *_table.org files remain, remove the table branch from get_model_type(), load_model(), and the profile matrix. Junctions remain a distinct type and are out of scope for this merge.

• Org entity meta model
• ores.codegen architecture
• Facet catalogue
• Component catalogue
• Codegen input org-file schema reference
• Entity commissioning process reference
• Domain entity evaluation checklist
• Entity coverage matrix
• ORE Studio Variability Model (Profile Metamodel)