Extension patterns and boundaries

Documentation status: architecture — see Maturity and evidence.

A safe extension adds a reusable capability without moving business meaning into an opaque implementation.

Prefer registered capabilities, explicit adapters, published actions, declarative services, and replaceable concrete components. Name extension points by what they provide, not by an implementation technology. Generated host-language bindings are projections of runtime capabilities and should not be mirrored back into the ontology merely because an operationalization uses that language.

Avoid four recurring mistakes:

• hiding business workflow inside an extension instead of a declared process or action;
• exposing an implementation helper as a public capability;
• coupling the conceptual model to one UI, transport, or storage implementation when a registered boundary exists;
• accepting generated or external results before they pass the relevant parser, grammar, authorization, or runtime validation gate.

When the current metadata contract requires a concrete binding name, public examples normalize historical TXXX names to XXX. That normalization is editorial; it does not by itself certify the implementation name as a stable public API.