Story: Codegen infrastructure follow-ups from DQ commissioning

Table of Contents

This page documents a story in Product backlog — inbox, carried unfinished from Sprint 24 at close. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

Split from Sprint 23's Commission ores.qt.dq — full-stack codegen for the DQ component at close: while commissioning DQ entities, four genuine codegen infrastructure gaps surfaced that aren't specific to DQ and shouldn't be lumped in with finishing DQ's own remaining entities (see Commission remaining DQ entities for that DQ-specific follow-on):

  1. No static lint for entity .org models flagging missing variability knobs for their stereotype.
  2. The NATS command/event pipeline is modelled as five independent ores.cpp.nats-* facets that should be one facet with five archetypes.
  3. =lookup_entity=/table SQL templates only support a single-column primary key, blocking any compound-natural-key entity (subject_area is the immediate blocker, but this is a general template gap).
  4. 10 more lookup_entity models outside DQ (iam: tenant_type/ tenant_status/account_type; trading: party_role_type/ trade_id_type/trade_type/lifecycle_event; analytics: pricing_engine_type; dq: artefact_type/report_definition/ synthetic_fx_spot_config/lei_entity/lei_relationship) still need migrating to domain_entity, so ores.codegen.lookup_entity can finally be retired.

Status

Field Value
State STARTED
Carried from Sprint 24 (unfinished at close)
Now Not yet started.
Waiting on Unify entity key modeling — its compound natural-key task was abandoned here and moved there.
Next Pick up the entity lint or NATS facet consolidation tasks; compound-key work continues on the other story.
Last touched 2026-07-21

Acceptance

  • A compass codegen entity lint command exists, flagging missing variability knobs per model stereotype.
  • The five ores.cpp.nats-* facets are consolidated into one facet with five archetypes.
  • lookup_entity/table SQL templates support a compound natural-key primary key; subject_area unblocked as a result.
  • All 10 remaining non-DQ lookup_entity models migrated to domain_entity; ores.codegen.lookup_entity's #+type:, loader, and dedicated dispatch retired.

Tasks

Task State Start End Description
Support compound natural keys in lookup_entity/table SQL templates ABANDONED 2026-07-22 2026-07-22 Superseded by Unify entity key modeling — the narrower plan would have been discarded once that story's unified template/syntax landed.
Add compass codegen entity lint — flag missing variability knobs on a model BACKLOG     A static sanity-check command that parses an entity .org model, classifies its stereotype, and warns about knobs it expects for that stereotype but doesn't find.
Consolidate the five ores.cpp.nats-* facets into one facet with five archetypes BACKLOG     A single ores.cpp.nats facet with five archetypes underneath would model the NATS command/event pipeline more accurately than five independent facets.
Migrate the remaining 10 lookup_entity models to domain_entity; retire ores.codegen.lookup_entity BACKLOG     Migrate each of the 10 remaining lookup_entity models the same way 464B5EC6 migrated DQ's 5, then retire ores.codegen.lookup_entity's #+type:, loader, and dispatch.
Support compound primary keys in repository templates (single-row and batch) DONE 2026-07-24 2026-07-25 The repository .hpp/.cpp templates (cpp_domain_type_repository.{hpp,cpp}.mustache, tangled from ores.cpp.repository.repository_header.org and ores.cpp.repository.repository_impl.org) still assume a single-column {{primary_key.column}} throughout signatures, where() clauses, order_by(), read_latest/read_all/read_at_version/remove, including the batch (vector) variants. subject_area (compound natural key: name, domain_name) cannot round-trip through the repository layer until these are converted to iterate {{#primary_key.columns}}. Single-row ops: AND all key columns in where(). Batch ops: sqlgen has no tuple/composite IN (confirmed via source inspection of sqlgen::transpilation::conditions and upstream issue getml/sqlgen#107) – implement via per-column .in() over-fetch (cross-product candidate set) followed by exact key-tuple filtering in C++. Regenerate subject_area's repository, verify it builds, then verify subject_area end-to-end through service/messaging/Qt.
Migrate all codegen entities to the nested identity/audit struct shape BACKLOG     Standardise every codegen-generated domain entity (refdata and any other flat-generated component) on the C1202 nested identity/audit sub-struct shape already used by trading instruments, so every facet template can drop its flat-vs-nested branching and the whole codebase converges on one entity shape.

Decisions

  • Compound primary keys are modeled as primary_key.columns (an ordered list), computed once in core.py into ready-made join strings (where_and, order_by_cols, batch_params, batch_in_and, log_fields, etc.) that templates splice in directly, rather than repeating nested mustache loops across every repository/service/protocol template. Single-column entities are the len(columns) = 1= degenerate case — no separate code path.
  • Batch (vector) reads/removes for a compound key use a per-column .in() over-fetch (cross-product candidate superset) followed by exact key-tuple filtering in C++, since sqlgen has no tuple/ composite IN support (confirmed against sqlgen source and upstream getml/sqlgen#107).
  • Qt codegen (controller, MDI window, client model, detail dialog templates) was explicitly not extended for compound keys as part of this work — it assumes a single-column key end-to-end, including a shared, cross-entity HistoryDialog signal contract used by every entity's controller, not just subject_area's. Extending it safely needs its own design pass; filed as capture: Extend Qt codegen for compound primary keys.

Out of scope

  • DQ-entity-specific remaining work (subject_area commissioning itself, history-dialog migration, change_reason_code bug, Librarian tree regression) — see Commission remaining DQ entities.

Emacs 29.3 (Org mode 9.6.15)