kibo-template-viper

Deprecated. This is the LTS-1.2 branch: the 1.2 pack, for kibo 1 and Template Model 1. It is deprecated and receives fixes only, for the life of the LTS-1.2 line. New projects use the kibo 2 line, on main; moving a project is covered by the migration guides.

First-party templated features targeting the Viper ecosystem (Viper C++ runtime + dsviper Python binding). Consumed by Kibo to generate the static API surface that lets C++ and Python developers work against typed wrappers instead of stringly-typed metadata.

Documentation

Full documentation: https://docs.digitalsubstrate.io/kibo-template-viper/

Maintainer design note for the Python & TypeScript proxy templates: DESIGN.md.

Part of the DevKit ecosystem.

Layout

cpp/                     # C++ surface templates targeting Viper C++ API
   Data/                 # struct, enum, concept, club implementations
   Database/             # SQLite persistence
   Stream/, Json/        # codecs
   ValueCodec, ValueType, ValueHasher
   Attachments/, AttachmentFunctionPool/, FunctionPool/
   Test/, TestApp/

python/                  # Python surface templates targeting dsviper API
   package/              # the importable Python package generated for a model

For the conceptual ground (templated feature, Template Model, the role of Kibo), see the user-facing docs:

• devkit-doc/source/kibo/usage.md
• devkit-doc/source/kibo/templates.md
• devkit-doc/source/kibo/template_model.md

Public contract

These templates are surface templates: each one is a static projection of one Viper runtime feature (Database, Codec, Stream, Attachments, …). They are part of the Viper public API by another name — modifying cpp/Database is no more anodyne than modifying viper/src/Viper/Viper_Database.hpp.

Versioning follows the Viper C++ API and dsviper Python API public- contract lines: any breaking change to a cpp/ template tracks the corresponding C++ API bump; same for python/ against dsviper.

Usage

Templates here are consumed by Kibo, which produces the generated code:

java -jar kibo-X.Y.Z.jar \
    -c cpp \
    -n MyApp \
    -d MyApp.dsm.json \
    -t /path/to/this/repo/cpp/Database \
    -o ./generated

In practice, dsm_util.py and the various generate.py scripts resolve this path automatically via the sibling-checkout convention or via the KIBO_TEMPLATES environment variable.

Third-party templates

This repo is for first-party templates only (DS-maintained). Third parties writing their own templated features follow the same .stg conventions but live in their own repos.

License

This project is licensed under the MIT License — see LICENSE.

The templates themselves are open source. Each template, when processed by Kibo against a user model, also emits a header comment in the generated file that records this licensing posture (templates: MIT, runtime: Commercial) so the licensing story remains visible to the end user of the DevKit.

Runtime dependency

Templates in this repository emit code that is not standalone — at runtime it depends on:

• viper (C++ runtime, for cpp/ templates) — proprietary, distributed under LicenseRef-DigitalSubstrate-Commercial-1.2.
• dsviper (Python runtime, for python/ templates) — proprietary Python wheel published on PyPI under LicenseRef-DigitalSubstrate-Commercial-1.2. See https://pypi.org/project/dsviper/.
• @digitalsubstrate/dsviper (Node binding, for typescript/ templates) — proprietary npm package over the same Viper runtime, under LicenseRef-DigitalSubstrate-Commercial-1.2. See https://www.npmjs.com/package/@digitalsubstrate/dsviper.

Compatible runtime versions

The runtime's MAJOR.MINOR is the compatibility contract — the on-disk format and public API are locked across a minor. The PATCH is versioned independently per binding, so the numbers differ between targets:

Templates	Runtime	Compatible versions
typescript	@digitalsubstrate/dsviper (npm)	>=1.2.16 <1.3.0
python	dsviper (PyPI wheel)	>=1.2.31 <1.3
cpp	viper (C++ runtime)	>=1.2.30 <1.3

These templates project the runtime's basic surface. When a template comes to need something a particular patch introduced, that becomes a floor, and where the generated output has a manifest, the floor belongs there: a pin the consumer's build reads cannot go stale, and it fails where someone will see it.

typescript is the one such case today. Its generated package.json pins >=1.2.16 <1.3.0: the generated vec/mat proxies call the binding's toArray(), which the binding settled on from 1.2.8 onward (a fixed-shape sequence is an array in JS, not a tuple), and a remote attachment function that only reads takes an AttachmentGetting, which the binding's call accepts from 1.2.14, and a write takes a CommitAttachmentMutating, the binding's name for it from 1.2.16.

The python and cpp outputs have no manifest to carry a pin, so their floor is this table's. A write takes a CommitAttachmentMutating, which dsviper names from 1.2.31 and the C++ runtime from 1.2.30. Against an older wheel, a generated Python module fails to import, as its annotations are evaluated when it loads; against an older checkout, the generated C++ does not compile.

The MIT license above governs the templates as source. The output of kibo produced from these templates is a derivative work of MIT material and remains free of obligations beyond the standard MIT notice; however, executing that output requires a runtime listed above, and the runtime's own licence applies independently. Any commercial deployment therefore requires a Commercial Licence from Digital Substrate for the relevant runtime.