Metadata catalogue and page resolution¶
Issue #114 promotes the executable #112 spike into the production
ui-metadata crate. The crate consumes the versioned contracts from
plugin-contract::ui; it does not contain CRM resource names, persistence
types, HTTP behavior, or React rendering.
Catalogue lifecycle¶
MetadataCatalogue accepts validated PluginUiPackage values. Every document
must be owned by the package's plugin ID, and the combined catalogue must pass
the shared UI contract validator. Node components must resolve either to an
explicitly registered host component or to a component definition in the
combined bundle. A package remains catalogued when disabled,
but only enabled packages can own pages or contribute to a resolved snapshot.
An enabled package with a missing or disabled dependency fails resolution with
a structured diagnostic.
Package replacement and persistence are intentionally delegated to the plugin lifecycle work in #18 and #19. Callers should construct a candidate catalogue, validate it, and swap it atomically only after plugin lifecycle checks pass.
Deterministic layer order¶
The resolver starts from the owning page and selects the highest-priority matching variant using only the bounded condition AST. It then applies layers in this order:
- enabled plugin contributions in dependency/topological order;
- published tenant patches compatible with the page definition version;
- non-structural user preferences from a closed property enum.
Within a layer, priority and stable contribution ID break ordering ties. Input, filesystem, and database iteration order do not affect the result. Two writes to the same node property in the same layer are an error; a later layer may intentionally override an earlier layer.
All six stable-ID operations are supported: inside, before, after,
move, configure, and restricted replace. Replacement must retain the
target node ID, and moving a node into its own subtree is rejected.
Publication and upgrade safety¶
Tenant patches declare an inclusive/exclusive compatible definition-version range. Resolution works on clones and returns an immutable value, so a missing anchor, incompatible version, ambiguous write, or dependency failure cannot mutate the catalogue or the last published result. The caller can therefore retry with the prior publication as a rollback input.
ResolvedPage records the selected variant, all source/dependency plugin
versions, tenant publication versions, and a SHA-256 content hash over its
canonical deterministic representation. Later API caching in #116 can use
these values without inventing a second composition model.