New lookup entity: two undocumented manual wiring steps (NATS handler registrar, tenant-provisioning copy block)

Table of Contents

This page is a capture in the inbox bucket of the product backlog — a pre-sprint idea, not yet pulled into a sprint as a story.

What

Adding a new codegen'd lookup entity requires two hand-edits the codegen workflow doesn't cover or document. First, the generated NATS CRUD handlers must be registered in projects/ores.refdata/core/src/messaging/registrar.cpp – only the eventing registrar (event_registrar.cpp) gets proactively wired by convention; the request/response handler registrar is a separate, hand-maintained dispatch list codegen never touches. Second, a copy block must be added to projects/ores.sql/create/iam/iam_tenant_provisioner_create.sql so the new entity's system-tenant seed rows get copied into newly (or already-) provisioned tenants, matching the existing book_statuses/regulatory_book_types/purpose_types blocks. Either fix the codegen profile to generate these two wiring points automatically, or document them explicitly as required manual steps in the entity-creation runbook (codegen-add-entity skill / entity_lifecycle.md).

Why

Both gaps are silent: no build or test failure catches them, only a runtime symptom found via manual QA – a "Failed to fetch … from server" error for the missing handler registration, or an empty list for a real tenant for the missing tenant-provisioning copy. They surfaced while adding book_purpose_type (see Add book_purpose_type lookup entity to book), but neither gap is specific to that entity – book_status=/=regulatory_book_type=/=purpose_type only avoided it because whoever added them (in earlier sprints) happened to remember both steps by hand. Left undocumented, every future lookup entity is one missed step away from the same silent failure, and the failure mode gives almost no signal pointing back at "you forgot to wire the registrar" – it just looks like a server-side bug.

References

See also

Emacs 29.3 (Org mode 9.6.15)