Story: Codegen model safety guardrails

Table of Contents

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

Goal

Before the C++ template audit (Refactor ores.codegen C++ generation) begins, close the known silent failure modes in ores.codegen that would cause the audit to produce misleading results:

  1. Missing component_include / component_core fields cause generated files to land in a non-existent projects/ores.<component>/ directory. Git diff reports "clean" because the output is untracked — a false pass.
  2. Running --profile sql on a _domain_entity.json model silently uses sql_schema_domain_entity_create.mustache (the old template) rather than the new unified template, even when a _table.json exists for the same entity.
  3. The all-cpp profile excludes Qt, nats-eventing, and all non-temporal variants. Claiming "zero diff" after running all-cpp leaves Qt and non-temporal drift undetected.
  4. Non-temporal entities run through the temporal all-cpp profile silently produce C++ with audit columns (version, modified_by, recorded_at) that do not exist in the database table.

These guardrails convert silent wrong-path output and false "clean" signals into loud, actionable errors. They make the subsequent C++ audit trustworthy.

See Codegen architecture analysis and unified model roadmap for full context.

Status

Field Value
State BACKLOG
Parent sprint Sprint 21
Now Not yet started.
Waiting on Nothing. Should start before C++ audit Task 1.
Next Implement guard for missing component_include.
Last touched 2026-05-30

Acceptance

  • generate.py raises a ValueError when a _domain_entity.json model is missing component_include or component_core; codegen.py catches it, logs a clean human-readable error message naming the missing field and the model file, and exits non-zero. No raw Python traceback is shown to the user.
  • Running --profile sql on a _domain_entity.json model that has a corresponding _table.json in the same directory raises an error or warning directing the user to use the _table.json model instead.
  • Running --profile all on a _domain_entity.json model raises an error (extending the existing guard that already blocks table and schema models).
  • A comment or --help note documents which facets all-cpp covers and that Qt requires a separate --profile qt invocation.
  • CI passes. No production C++ files are changed by this story.

Tasks

Task State Start End Description
Task: Guard missing component_include/component_core in generator.py BACKLOG     Raise an error at generation time when component_include or component_core is absent from a domain_entity model.
Task: Block dual-template SQL generation for domain_entity models BACKLOG     Extend the –profile all guard and add a warning when –profile sql is run against a domain_entity with a co-located _table.json.
Task: Document all-cpp profile limitations BACKLOG     Add –help annotation and CLI output note explaining Qt is excluded from all-cpp; add guard that warns when a model lacks is_temporal and a temporal profile is used.

Decisions

  • Errors not warnings for missing fields. The component_include fallback silently writes to the wrong path; a warning is easily ignored. An error forces the model to be fixed before generation proceeds.
  • Warn, not error, for dual-template SQL. The _domain_entity.json SQL output may legitimately be used for non-refdata components that have no _table.json yet. A warning with clear guidance is safer than a hard error until all components have migrated to _table.json models.

Out of scope

Emacs 29.1 (Org mode 9.6.6)