Modules and configuration v26.5+ PREVIEW

A semantic Module is an immutable Kubling artifact containing a manifest and the semantic documents a VDB may load. Modules make model releases independent from the descriptor bundle while preserving exact identity and content verification.

Build and validate Modules with the Kubling CLI. Applications and deployment pipelines should not construct Module artifacts directly or depend on their internal distribution format.

Module source layout

The source directory must contain kubling-semantic-module.yaml at its root. Every document that can be loaded must appear in the manifest inventory.

kubling-semantic-module.yaml
semantic/
  operations.composition.yaml
  fragments/
    kubernetes.yaml
    delivery.yaml
  alignments/
    operations.yaml

Example manifest:

format: kubling-semantic-module
schemaVersion: 1
metadata:
  name: organizational-core
  version: 1.4.0
spec:
  documents:
    - semantic/operations.composition.yaml
    - semantic/fragments/kubernetes.yaml
    - semantic/fragments/delivery.yaml
    - semantic/alignments/operations.yaml

The module manifest version and the compiled semantic package version are independent contracts. Do not use one as a proxy for compatibility with the other.

Build the Module from its source directory:

mkdir -p dist
kdv bundle genmod ./organizational-core \
  --output ./dist/organizational-core-1.4.0

The output filename is a deployment concern. Module identity comes from the manifest, and repositories address it by name and version.

Declare modules in the descriptor bundle

semanticModules belongs in bundle-info.yaml, next to the descriptor bundle’s other module references:

virtualDatabases:
  - vdb/OperationsVDB.yaml
 
semanticModules:
  - name: organizational-core
    uri: kbl://organizational-core/1.4.0
    digest: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

The digest is required and must contain exactly 64 hexadecimal characters after sha256:. Kubling rejects the Module before loading when the resolved bytes do not match it.

Supported locations are:

• a local path, normalized to a file URI
• file:
• http: or https:
• kbl://module/version

For a kbl URI, the URI module name and version must match the configured name and the manifest identity.

Select a model in the VDB

The VDB descriptor selects the module and composition:

name: Operations
version: "1"
 
semanticModel:
  module: organizational-core
  composition: semantic/operations.composition.yaml
  activationFailurePolicy: failStartup

composition is relative to the selected module root. When module is omitted, it is relative to the VDB descriptor directory in the descriptor bundle.

A provider-only semantic model does not require an authored composition. Use an empty semanticModel object with an optional failure-policy override:

semanticModel:
  activationFailurePolicy: failStartup

Kubling then assembles the accepted provider fragments for that VDB. If none are available, the VDB is catalog-only.

Choose the activation policy

The application-level default is isolate:

semantic:
  activationFailurePolicy: isolate

A VDB may override it through semanticModel.activationFailurePolicy.

Use failStartup when a deployment is not useful unless its semantic contract is active. Use isolate when SQL and catalog workloads should stay available while the model is repaired.

Resolution limits

Kubling applies fixed acquisition limits before a module can influence the runtime:

Absolute, parent-traversal, URI-shaped and backslash-based Module paths are rejected. Duplicate paths and documents missing from the manifest inventory are rejected as well.

Deployment lifecycle

Semantic Modules are resolved once during bootstrap. Kubling verifies the Module, reads the selected composition, acquires provider fragments, validates all bindings and compiles the VDB package. There is no hot reload.

To publish a new model:

1. build a new Module with the Kubling CLI
2. publish it under a new immutable version
3. calculate and review its SHA-256 digest
4. update bundle-info.yaml and any VDB composition reference
5. deploy and restart the Kubling instance
6. verify the active package and digest through the semantic admin API

Continue with operations and diagnostics.