Construction Kit Library Management

OctoMesh provides built-in tools for managing Construction Kit (CK) model libraries across tenants. This includes browsing available libraries from catalogs, checking compatibility, resolving dependencies, and importing libraries with full dependency resolution.

Catalog Sources

CK model libraries are distributed through catalogs. OctoMesh supports multiple catalog sources:

Catalog	Description	Default
EmbeddedResource	System models embedded in the service binaries	Always active
PublicGitHub	Public GitHub repository with released CK libraries	Enabled
PrivateGitHub	Private GitHub repository for development/pre-release libraries	Disabled in production
LocalFileSystem	Local file system for development use	Disabled in production

Catalog sources can be configured per environment via Helm values or environment variables.

System-Managed Models

Models whose name is System or starts with System. (e.g., System.Identity, System.Communication) are managed by the OctoMesh services themselves. These models:

• Are imported automatically during tenant creation and service startup
• Cannot be updated by users through the Library Management UI or CLI
• Are shown with a "Service-Managed" badge in the Library Overview
• Are excluded from the "Fix All" batch operation

Version Compatibility

When evaluating whether a CK library can be imported into a tenant, OctoMesh checks transitive compatibility against installed system model versions:

• The check walks the full dependency chain recursively
• For each dependency on a system-managed model, the major version must match the installed version
• Example: If System-2.0.7 is installed, a library requiring System-3.0.0 (different major) is incompatible
• A library requiring System-2.0.3 is compatible (same major, installed version is higher)

Incompatible libraries are flagged in both the UI and CLI and cannot be imported.

Dependency Resolution

When importing a CK library, OctoMesh automatically resolves its full dependency tree:

1. Fetch the target model from the catalog
2. Walk its Dependencies list (exact version references)
3. For each dependency, recursively resolve sub-dependencies
4. Deduplicate by model name, keeping the highest required version
5. Exclude system-managed models (they are managed by services)
6. Order topologically (dependencies before dependents)

The result is a flat, ordered list of models to import. Each model is imported sequentially via Hangfire background jobs, ensuring that dependencies are available before dependents are imported.

How Version Ranges Become Exact Pins

A source ckModel.yaml declares dependencies as version ranges (Basic.Energy-[1.3,2.0)), but a compiled CK library carries exact dependency pins. The compiler resolves each range against the catalogs — picking the highest published version that satisfies the range — and freezes the result into the compiled model. From then on, every import of that library requires exactly the frozen versions.

This compile-time pinning is why dependency bumps cascade: when Basic.Energy publishes a new version, an already-compiled dependent like EnergyCommunity still pins the old one. The dependent must be rebuilt and republished (with a version bump — the SemVer gate enforces this) before a tenant can hold both. See Versioning Rules for the full rule set, including the different floor-based resolution used by blueprints.

Import Pipeline

The import flow uses the existing asynchronous job pipeline:

Display-Rule Backfill

If an imported model changes the display name rules declared on its types, existing entities of the affected type subtrees are updated by an automatic background sweep that recomputes rtDisplayName / rtDisplayDescription. The sweep is durable and retried (tracked in the system collection display_rule_sweep); no manual action is required.

Authorization

CK library management operations are protected by the Data Model Management authorization policy:

Operation	Required Scope
Browse catalogs (list, search)	octo_api.read_only or octo_api
View library status	octo_api.read_only or octo_api
Resolve dependencies	octo_api.read_only or octo_api
Import models / Refresh caches	octo_api.data_model_management or octo_api

The DataModelManagement role is included in the default TenantOwners group.

REST API Endpoints

System Scope

Method	Endpoint	Description
GET	system/v1/ckmodelcatalog	List all models from all catalogs
GET	system/v1/ckmodelcatalog/search?q={term}	Search models
GET	system/v1/ckmodelcatalog/catalogs	List catalog sources
GET	system/v1/ckmodelcatalog/{catalogName}	List models from specific catalog
POST	system/v1/ckmodelcatalog/refresh	Refresh all catalog caches

Tenant Scope

Method	Endpoint	Description
GET	{tenantId}/v1/models/LibraryStatus	Merged view: installed + catalog
POST	{tenantId}/v1/models/ResolveDependenciesBatch	Resolve dependency trees
POST	{tenantId}/v1/models/ImportFromCatalogBatch	Batch import with jobs
POST	{tenantId}/v1/models/CheckUpgrade	Pre-flight migration check
POST	{tenantId}/v1/models/ImportFromCatalog	Single model import