# Glossary

Minimal cross-cutting vocabulary. Terms appear here when several sections of
the documentation use them and a single canonical definition avoids drift.
Component-specific vocabulary stays in its component section.

The list will grow as the rest of the documentation is consolidated. For
distribution names (DevKit, dsviper, Viper), see [naming](naming.md).

```{glossary}

DSM
   The **Digital Substrate Model** — the declarative modeling language used to
   describe data structures: types, structures, attachments, function pools.
   Pure specification; runtime-independent. See {doc}`../dsm/index`.

Kibo
   The code generator. Reads a DSM model plus a {term}`Kibo template` and
   emits source code. Template-agnostic — the target language and runtime are
   determined by the template. See {doc}`../kibo/usage`.

Kibo template
   A parameterized recipe consumed by Kibo. Defines what code is emitted and
   for which target. `kibo-template-viper` is the official template that
   targets the dsviper runtime; other templates can target other runtimes.

dsviper
   The Python runtime — strongly typed Python API over the
   {term}`Viper` engine. Distributed exclusively on PyPI
   (`pip install dsviper`). See {doc}`naming` for how dsviper relates to
   DevKit and Viper.

Viper
   The C++ runtime engine that dsviper wraps. Carries the type system, commit
   DAG, and database tier. Currently not distributed standalone;
   See {doc}`naming`.

DevKit
   The Digital Substrate Python toolkit, distributed as a single ZIP. Carries
   the toolchain (Kibo, kibo-template-viper, dsviper-tools, offline docs) —
   not the dsviper runtime itself, which is fetched from PyPI. See
   {doc}`naming`.

dsviper-tools
   Tooling for the Database / CommitDatabase workflow of the dsviper
   ecosystem — `cdbe`, `dbe`, `dsm_util`, `commit_admin`, and the
   commit-database server. Available as a Qt Widgets variant
   (`dsviper-tools`) and a QML variant (`dsviper-tools-qml`).

dsviper-components
   Shared component library on top of dsviper — dialogs, views, helpers
   reusable by applications. Available as a Qt Widgets variant
   (`dsviper-components`) and a QML variant (`dsviper-components-qml`).

concept
   An abstract entity declared in DSM. A concept has no implementation of its
   own — it exists only through its {term}`keys <key>` and the
   {term}`attachments <attachment>` bound to those keys. See
   {doc}`../dsm/concepts`.

key
   An instance identifier for a concept. Created at runtime, backed by a UUID,
   typed by the concept it instantiates. Anywhere typed data references a
   particular instance, it does so through a key.

attachment
   A DSM construct binding a typed payload to a {term}`key`. The primary unit
   of data organization in a DSM model. See {doc}`../dsm/attachments`.

function pool
   A DSM construct grouping function prototypes associated with a concept or
   attachment — the callable side of the data model. See
   {doc}`../dsm/function_pools`.

definitions
   The runtime model — the metadata that mirrors a DSM file at runtime. What
   dsviper exposes through introspection (`DSMDefinitions`,
   `DefinitionsInspector`, …) and what every typed operation consults.

type / value
   The dual primitives of the metadata system. A **type** describes shape;
   a **value** is an instance carrying that type. Every value knows its type
   at runtime — that is what enables strong typing without boilerplate.

static API / dynamic API
   The two ways to use dsviper. **Static API** — a typed Python package
   generated by Kibo from your DSM model; gives you IDE autocompletion and
   type checking. **Dynamic API** — direct use of dsviper's runtime
   metadata, loading definitions at runtime; no code generation needed. Both
   share the same engine.

commit
   A node in the versioned-data DAG. Captures a set of {term}`mutations
   <mutation>` against a parent commit. Conceptually similar to a git commit,
   but for typed data rather than text. See {doc}`../dsviper/commit`.

commit DAG
   The directed acyclic graph formed by commits and their parent links.
   Storage and history of versioned data; supports branching, merging, and
   synchronization across clients.

mutation
   An opcode-level change applied to a value (`set`, `update`, `insert`,
   `remove`, …). Mutations are grouped atomically into a {term}`commit`.

blob
   Large opaque binary data stored alongside DSM-typed values. Indexed by a
   `BlobId`; stored through blob layouts and packs. Used for images, files,
   serialized assets, or any payload that does not benefit from typed
   structure. See {doc}`../dsviper/blobs`.

codec
   A serialization strategy — how typed values are encoded to and from bytes.
   Different codecs trade readability against size and speed.

reference application
   An application bundled or distributed for the purpose of demonstrating
   ecosystem usage end-to-end. `cdbe.py` and `dbe.py` exercise the dsviper
   API; `ge-py` and `ge-qml` exercise the *whole* chain (DSM, Kibo, template,
   components, runtime). Not products in their own right.

```