> ## 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. # Ontology Evolution, Branching & Versioning > How the Insurance Ontology evolves without breaking active runs, queues, integrations, or the audit chain. Semver rules, deprecation, branching, pinning, compatibility tests, and replay. # 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. ```mermaid theme={null} stateDiagram-v2 [*] --> trunk trunk --> branch_proposal: fork(name) branch_proposal --> branch_active: review.approved branch_active --> branch_active: edit / commit branch_active --> shadow: promote(shadow) shadow --> shadow: dual-write & eval shadow --> trunk: merge(approved) shadow --> branch_active: revert branch_active --> archived: abandon trunk --> [*] ``` *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. A pinned object is read with the resolver `ontology.read(ref, asOf=pin)`. The substrate retains historic schemas; readers are version-aware. ## 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: 1. **Structural:** JSON Schema diff classifies the change (additive optional / additive required / narrowing / removal / rename) and validates the bump matches §6.1. 2. **Replay:** A sample of recent runs is replayed against the candidate version; deviations in Decision verdict beyond the noise band are flagged. 3. **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: 1. Disjoint additive changes always merge cleanly. 2. Same-property concurrent additions: the one with the higher pin-count wins; the other becomes a deprecation candidate. 3. Type changes from both branches: hard conflict; merge fails; resolution is by an explicit Decision tagged `ontology.merge.resolution`. 4. Marking changes always escalate to the security plane (§15) before merge. 5. Every merge produces a typed AuditEvent on the ontology chain with the diff, the algorithm path taken, and the resolver principal. ## 6.8 Cross-tenant boundary Each tenant has its own ontology release line. Ontology assets are not shared across tenants; convergence on a common base happens only via the platform's reference release, which a tenant chooses to consume on its own schedule. There is no automatic propagation of tenant-specific objects, properties, or markings.