Documentation Index
Fetch the complete documentation index at: https://docs.uselayerup.com/llms.txt
Use this file to discover all available pages before exploring further.
06 — Ontology evolution, branching & versioning.
The Ontology is a long-lived contract that must evolve without breaking active runs, active queues, active integrations, or the audit chain. This section specifies how it evolves — semver rules, deprecation windows, branching for parallel evolution, version pinning at the agent and tool level, schema-compatibility tests, and replay against historic versions.6.1 Versioning model
Each ontology object is independently versioned under a strict semver discipline, and the ontology as a whole has a release version that pins a coherent set of object versions.| Change kind | Bump | Examples | Migration |
|---|---|---|---|
| Additive optional | minor | New optional property; new enum variant; new link with cardinality 0..N | None required; consumers transparently see new fields. |
| Additive required (with default) | minor | New required property with a derivable or default value | Backfill via mapping; default applied at projection time. |
| Required with no default | major | New required property that cannot be defaulted | Dual-write window; both versions live concurrently. |
| Type narrowing | major | String → enum; nullable → non-nullable | Validation pass over historic records; quarantine rejects. |
| Removal | major | Property dropped; link cardinality changed downward | Deprecation period of at least one minor; readers updated first. |
| Rename | major | Property renamed | Aliasing: old name continues to read for one major; writes go to new name. |
| Marking change | major | Default marking elevated | Re-classification batch; access caches invalidated. |
6.2 Deprecation discipline
- Deprecated fields must remain readable for two minor versions after the deprecation announcement.
- Deprecation is itself a typed AuditEvent on the ontology version chain.
- Tools and agents pinned to a deprecated version produce an Exception (kind
ontology.deprecated_pin) at run start; runs continue but operators see a warning. - Removal across a major bump is gated by a release-gate check that no production agent or tool still pins the removed field.
6.3 Branching
The ontology supports branches for parallel evolution: a tenant may need to stage a major change against a subset of agents and tools without affecting production. Branches are first-class; a branch is named, owned, and has a lifecycle. Fig. 6.1 — Ontology branching state diagram. A branch may be promoted to shadow, where it dual-writes against trunk and is exercised by a candidate model/prompt set, before merging.6.4 Pinning
Every agent definition, tool signature, mapping definition, and prompt revision pins to an ontology version. The pin is a tuple(release, branch?). Pins are recorded in
the run’s model lineage (§4.3) and in every Decision’s
metadata. A run executed against a pinned version sees a frozen contract regardless
of subsequent ontology changes on trunk.
6.5 Schema-compatibility tests
Every ontology change passes through a compatibility test pack before it can be promoted. The pack runs three classes of test:- Structural: JSON Schema diff classifies the change (additive optional / additive required / narrowing / removal / rename) and validates the bump matches §6.1.
- Replay: A sample of recent runs is replayed against the candidate version; deviations in Decision verdict beyond the noise band are flagged.
- Consumer: Every active tool, mapping, and agent declaring a pin to the changed object is re-validated; pins that no longer satisfy contract block promotion.
6.6 Replay against historic versions
Replay (§4.7) of an old run resolves the ontology version captured in the run’s model lineage; it does not “upgrade” the run to current trunk. This guarantees that a regulator-driven re-execution of a Decision produces the exact ontology contract that was in force at decision time.6.7 Reconciliation merge algorithm
When a shadow branch merges into trunk, conflicts are resolved per a fixed algebra:- Disjoint additive changes always merge cleanly.
- Same-property concurrent additions: the one with the higher pin-count wins; the other becomes a deprecation candidate.
- Type changes from both branches: hard conflict; merge fails; resolution is by an explicit Decision tagged
ontology.merge.resolution. - Marking changes always escalate to the security plane (§15) before merge.
- Every merge produces a typed AuditEvent on the ontology chain with the diff, the algorithm path taken, and the resolver principal.