Story: Commission ores.qt.dq — full-stack codegen for the DQ component

Table of Contents

This page documents a story in Sprint 23. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

Every DQ entity ends up with a real .org codegen model and standard generated core/service/handler/protocol/repository/Qt files – zero hand-written entity-specific code anywhere in the DQ stack (server or Qt). Concretely:

  • Retire the hand-written combined badge_handler.hpp=/ =badge_service.hpp=/=badge_service.cpp=/=badge_protocol.hpp (in ores.dq.core=/=ores.dq.api), replacing badge_severity=/ =badge_definition=/=code_domain's list/save/delete/history routing with the already-generated, currently-unwired per-entity handlers (badge_severity_handler.hpp, etc.), each registered via the standard register_<entity>_handlers() sub-registrar pattern (see ores.refdata.core's registrar.cpp for the convention this component should follow). badge_mapping (a junction) needs its own investigation first – see the junction codegen path/namespace drift capture filed during the badge migration work.
  • Author .org models (none exist today) for data_domain, subject_area, catalog, change_reason, and change_reason_category – currently entirely hand-written, including their Qt layer, living in ores.qt.refdata.
  • Stand up ores.qt.dq as a real, built Qt library: add its CMakeLists.txt (the directory and 3 entities' generated files already exist from the badge migration work, just never wired into the build), wire it into projects/ores.qt/CMakeLists.txt, and create a new DqPlugin (mirroring RefdataPlugin=/=AdminPlugin) that owns it and contributes the Data &Quality menu (see the sibling Clean up application menus story for the menu structure this feeds into – that story owns the overall menu redesign decision; this story only needs to land Data Quality's own menu correctly).
  • Retire the hand-written BadgeDefinitionController=/ =BadgeSeverityController (in ores.qt.admin) and CodeDomainController (in ores.qt.refdata, including its hand-wired BadgeMappingsTab, which needs to move to a real paste block on the regenerated CodeDomainDetailDialog once it's actually generated rather than hand-written), replacing them with the generated controllers already sitting in ores.qt/dq.
  • Along the way, this closes the two bugs found while testing the badge migration: Code Domain saves not prompting for a change reason (hand-written dialogs never got the standard promptChangeReason() call every generated dialog has), and not eventing (the old hand-written handler never published an entity-change event, unlike what codegen generates by default).

Status

Field Value
State DONE
Parent sprint Sprint 23
Now Closed: catalog/change_reason/change_reason_category/data_domain commissioned onto standard codegen; lookup_entity architecture unified into domain_entity; entity .org scaffolding tooling built. Remaining scope split into two Sprint 24 stories.
Waiting on Nothing.
Next See the two Sprint 24 follow-on stories.
Last touched 2026-07-21

Acceptance

  • catalog, change_reason, change_reason_category, and data_domain each have a codegen .org model and standard generated core/ repository/service/handler/protocol code, replacing their hand-written equivalents; build and tests green.
  • lookup_entity (as a distinct codegen metatype) is retired in favour of domain_entity for DQ's entities, unblocking their C++ generation.
  • An entity .org model scaffolding command exists, pre-filled with correct variability knobs by kind (regular/enum/junction).
  • A complete inventory of DQ entities and their codegen/hand-written status exists.

Tasks

Task State Start End Description
Scaffold story: Commission ores.qt.dq — full-stack codegen for the DQ component DONE 2026-07-16 2026-07-16 Story scaffolding rides this task: documents, sprint wiring, and the scaffold PR. Close it before merging that PR.
Inventory all DQ entities and their current codegen/hand-written status DONE 2026-07-17 2026-07-17 Initial task for: Commission ores.qt.dq — full-stack codegen for the DQ component
Commission catalog/change_reason/change_reason_category/data_domain onto standard codegen DONE 2026-07-18 2026-07-21 Author codegen .org models for four simple code-list-shaped DQ entities (catalog, change_reason, change_reason_category, data_domain) and regenerate their core/repository/service/handler/protocol layers, retiring the hand-written equivalents. subject_area split out to Sprint 24 (blocked on compound natural-key support).
Scaffold model .org files per entity type (regular/enum/junction) DONE 2026-07-17 2026-07-18 Add codegen support to generate a new entity model .org skeleton pre-filled with all variability knobs set correctly, by kind (regular/enum/junction), derived by sampling known-good reference entities (e.g. book, currency) rather than ad-hoc copy-paste. Use the resulting templates for all new DQ entity models going forward.
Extend lookup_entity scaffolding to cover DQ's simple entities' variability DONE 2026-07-18 2026-07-18 compass add lookup_entity's has_coding_scheme/has_image_id/has_artefact_insert_fn knobs are hardcoded false in the template with no CLI flags at all, and the template only models a single-column Primary key – but ores.dq.subject_area's real table has a compound natural key (name, domain_name). Parameterize the boolean knobs like entity_org's –entity-<knob> flags, and extend the Primary key section to support a compound natural key so subject_area (and any future compound-key lookup entity) can be modeled accurately.
Fix lookup_entity model_type mapping so SQL/C++ actually generate DONE 2026-07-18 2026-07-18 core.py maps #+type: ores.codegen.lookup_entity to internal model_type 'enum', but no SQL or C++ archetype's declared model_types matches that shape (ores.sql.schema.table_create.org declares 'schema'; ores.cpp.enum.org expects an 'enum' data key that org_loader's lookup-entity loader never produces). As a result no lookup_entity model in the repo – new or pre-existing (artefact_type, tenant_type family, etc.) – can regenerate SQL or C++ via codegen regenerate. Fix the mapping/dispatch so lookup_entity models generate correctly, verified against catalog.org and an existing entity.
Migrate lookup_entity into domain_entity; retire the lookup_entity type/loader/pipeline DONE 2026-07-18 2026-07-18 lookup_entity (#+type: ores.codegen.lookup_entity) is architectural duplication, not a distinct metatype: domain_entity already supports its exact shape via has_uuid_primary_key: false plus a plain natural-key primary key (confirmed via ores.refdata.country.org). Add has_coding_scheme/has_image_id/has_artefact_insert_fn as domain_entity knobs, migrate all 15 existing lookup_entity org models to #+type: ores.codegen.entity with has_uuid_primary_key: false, then retire ores.codegen.lookup_entity's separate #+type:, org_loader.py loader, and any dedicated dispatch – reusing domain_entity's existing, working column/cpp_type/template pipeline instead of building or maintaining a second one. Supersedes patching lookup_entity's own C++ generation gap in place (see DDBD522D).

Decisions

  • Task breakdown: one task per DQ entity (badge_severity, badge_definition, code_domain, badge_mapping, data_domain, subject_area, catalog, change_reason, change_reason_category, plus any others the inventory task turns up), each covering that entity's full switchover (retire hand-written code, wire in generated code, author a model first if none exists) end to end – not split by layer (e.g. not "all handlers" then "all Qt" as separate tasks). The ores.qt.dq library/=DqPlugin= scaffolding itself is a one-time prerequisite, its own task, done once before the first entity that needs it.
  • Closed at Sprint 23's end with acceptance narrowed to the four entities actually fully commissioned (catalog, change_reason, change_reason_category, data_domain), rather than left open indefinitely. Remaining scope split into two Sprint 24 stories by kind of work: DQ-entity-specific completion (subject_area, history-dialog migration, change_reason_code bug, Librarian tree regression) vs. general codegen-infrastructure gaps (entity lint, NATS facet consolidation, compound natural-key SQL support, remaining non-DQ lookup_entity migrations) that surfaced along the way but aren't specific to DQ.

Out of scope

Emacs 29.3 (Org mode 9.6.15)