Repository navigation
Docs: surface adopter constraints (registry.extend for new top-level types; refs index only object.*; dbImport/dialect required for DB-less projects) #194
Description
Three constraints surfaced while building a real consumer project (a CLI system monitor — all value objects, no database). Each was resolvable, but none was obvious from the docs.
1. metadata.root childRules are closed
Adding new top-level node types (e.g. custom adapter.* / probe.* subtypes via a provider) requires registry.extend; without it the model fails to load with ERR_CHILD_NOT_ALLOWED. Worth a short "defining custom top-level types" doc section.
2. Declarative reference resolution only indexes object.* nodes
Cross-references from a template/adapter to a non-object.* node aren't resolved by the built-in resolver and must be hand-walked in a provider validate hook. Adopters modeling references to non-object nodes should know this up front.
3. MetaobjectsGenConfig requires dbImport + dialect even when no DB code is generated
A project that declares only value objects (no write-through entities) generates zero DB / query / route code — yet omitting dbImport/dialect is a tsc type error, so they end up as dead-but-mandatory config.
Ask: make dbImport/dialect optional when the model has no write-through entities, or document that they're required regardless and inert for value-object-only models.
Context
All three came up in a from-scratch TypeScript adopter (the smon system monitor). Happy to link the repo/config if useful.
Activity
fix(#194): resolve non-object references + make dbImport/dialect opti…
feat(#232): stamp codegen engine version in gen-state + warn on chang…
fix(#194): resolve non-object references + make dbImport/dialect opti…
dmealing commentedon Aug 4, 2026
All three constraints are addressed on
main— two of them fixed rather than documented.1.
metadata.rootchild rules are closed — documented.docs/features/extending-with-providers.mdnow carries a "Defining a custom top-level node type" section spelling out that registering the subtype is not enough: a provider must alsoregistry.extend(TYPE_METADATA, SUBTYPE_ROOT, { childRules: [...] })to license it as a permitted child, or the node fails to load withERR_CHILD_NOT_ALLOWED.2. Reference resolution only indexed
object.*nodes — fixed in code (43d90ca1). The loader's symbol table is now keyed per node type, so a reference to any registered top-level node kind resolves under the same ADR-0042 package-local contract (FQN-exact, else the referrer's package, else root-level), and the unresolved-error message names the actual target kind. Object-target references are byte-identical — the whole conformance corpus is unchanged; the change is strictly enabling.3.
dbImport/dialectrequired for a DB-less project — fixed in code (43d90ca1). Both are now optional, so a value-object-only model no longer has to supply dead-but-mandatory placeholders.The interim "Adopter constraints" doc block that described 2 and 3 as live limitations was removed when they were fixed, so the docs don't now describe constraints that no longer exist.
Shipped via PR #245. Unreleased — rides the next npm cut; see
CHANGELOG.md[Unreleased].chore(release): 0.20.13 coordinated (npm/PyPI/NuGet 0.20.13 · Maven 7…
docs: propagate 0.20.13 / 7.20.13 across README, llms.txt, port docs …
fix(codegen-ts): dbImport is a generator's need, not the model's