Skip to main content

Versioning and stability

Digitorn ships under semantic versioning at the release level and an explicit YAML language version (schema_version).

YAML schema version​

The Digitorn YAML language has one shape today: the block layout documented in Language (app:, runtime:, agents:, tools:, ...). schema_version: 2 is accepted as a forward-compat marker on that shape - the compiler parses the field but doesn't branch on its value; there's no older flat shape it falls back to and nothing to auto-detect. Set it anyway so files are ready for whatever schema_version: 3 eventually changes.

What "frozen" means (schema v2)​

For the lifetime of schema_version: 2:

  • No required field is added. Every existing YAML keeps parsing without modification.
  • No required field is removed. Every field documented under Language keeps doing what it did.
  • No field type is narrowed. A field that accepts a string today won't reject the same string after an upgrade.
  • Default values are stable. If a field's default changed, the daemon would emit a deprecation warning and honour the previous default for at least one minor release.

What CAN change​

  • New optional fields. A new YAML key under any block, with a safe default, can land in any release.
  • New modules. New entries are added to tools.modules.<id>. Existing modules don't go away without deprecation.
  • New runtime.mode values. Adding modes is backward-compat; removing is not.
  • New CLI sub-commands. digitorn ... grows over time.
  • Internal implementation. Everything inside the daemon - the SQL schema, the IPC protocol between worker and child processes, the cache file layout - is internal and may change in any release.

Deprecation policy​

A field deprecated in 1.X.0 continues to work and emit a warning. It is removed no sooner than 1.(X+2).0. Deprecations are listed in the release notes published with each minor.

Daemon version​

The daemon's own version follows SemVer (MAJOR.MINOR.PATCH). This page covers the YAML language contract above; the daemon's internal HTTP routes and process internals aren't part of these docs (they're not a documented public surface).

Schema version field​

The optional schema_version declaration at the top of a YAML file is a forward-compat signal:

yaml
schema_version: 2

Setting it doesn't change what the compiler accepts - it's a forward-compat marker, nothing more. New apps should still set it.

Root-level aliases​

Two flat root keys are still accepted directly - modules: and capabilities:, folded into tools.modules / tools.capabilities at compile time. Nothing else at the root is aliased: any other flat top-level key (an old execution:, channels:, behavior:, ...) is an unknown-key compile error, not a silent reshape. See App Configuration → Top-level blocks for the two real aliases in full.

Module API​

Each module exposes a name, a description, and a set of actions (each with its own param schema and risk level) that becomes part of the schema_version: 2 contract once published. Anything a module doesn't expose as an action is free to change between releases.