Ontology

The Ontology is the Intelligence-plane semantic contract that shared entities, relationships, and policy terms resolve against. It does not replace operational systems of record; it prevents agents, tools, evidence, and policy from silently assigning different meanings to an “order” or a “customer.”

Definition

A versioned, governed schema that defines canonical entity_types, relationship_types, attribute types, derived fields, and validation rules. Every record in the Knowledge Graph, every CEID in the Identity Layer, and every reference inside a Context Pack resolves against an explicit ontology version.

An ontology defines meaning and classification; it grants no actor authority or data-release permission. Profile-aware Execution Contract admission pins the relevant artifact/release and applies current grant, data-flow and boundary requirements separately. The TypeScript compiler consumes supplied references; production registry/ontology adapters must actually verify compatibility and resolved bytes.

Why it exists

Across a real enterprise, the same word means different things in different systems. CRM “customer” includes prospects; OMS “customer” requires a paid order; finance “customer” is a billing entity. If agents reason against ad-hoc fields, they produce decisions that look right in one system and wrong in another. The Ontology gives the runtime a shared, governed vocabulary so policy, retrieval, and decision contracts compose while source systems retain authority for their records.

How it works

1. Authored: domain owners propose changes against the active version.
2. Validated: changes are checked for breaking compatibility, derived-field correctness, and reference integrity.
3. Approved: governance review for high-risk types (PII, regulated, financial).
4. Published: a new ontology version is pinned per environment and rolled out.
5. Migrated: dependent indices, packs, and decision specs are revalidated against the new version.

Schema elements

Versioning and compatibility

Changes fall into three classes:

• Additive — new entity types, new optional attributes, new relationships. Existing shapes may remain compatible, but evaluate affected retrieval, classification, data routes and dependent packs before promotion; additional context or relationships can still change behavior.
• Refining — narrowing a type, tightening a constraint, deprecating an attribute. Requires deprecation window and migration plan; old packs can compile with a warning until the deprecation window closes.
• Breaking — removing a type or relationship, renaming a CEID format, changing classification upward. Requires a major version bump, a redirect/aliasing rule, and an explicit migration of dependent packs.

The runtime refuses to compile a Context Pack against an ontology version it does not satisfy. The error names the missing or incompatible element so the pack author can fix it.

Schema evolution governance

• Changes are merged through a version-controlled repo with required review.
• Breaking changes require an active deprecation period and a documented migration.
• Each environment pins one ontology version; promotion from staging to production is a deliberate step.
• A change-set diff (added / removed / refined) is published with every version so dependent teams can plan.

Improvement surface

The Ontology participates in the Improvement Loop as an Intelligence-plane artifact, but it is not a free-form search surface. Autotune and reviewer agents may propose ontology changes only when the proposal is backed by traces, failed compiles, unresolved entities, or repeated operator corrections.

Breaking changes, classification downgrades, CEID format changes, and relationship removals are never auto-tunable. They are governance events. The Improvement Loop can open a proposal, but promotion requires domain-owner approval, migration evidence, and replay against the dependent Context Packs and Decision Specs.

Protected policy/release administration and required independent approval follow Control Profiles. A proposal cannot lower its own classification or control requirements. Changed semantics need new immutable versions and impact review; saved checkpoints must not silently adopt the new interpretation.

Derived fields

Derived fields are pure functions, not stored facts. They run with explicit inputs and full access to their evidence refs. Time-dependent fields receive a pinned evaluation time from the run or replay envelope; they never read ambient wall-clock time.

derived_fields:
  - name: is_high_value_customer
    type: boolean
    expression: "lifetime_value_inr > 100000 AND tenure_days > 180"
    inputs:
      - Customer.lifetime_value_inr
      - Customer.tenure_days

Validation rules execute alongside derived fields and surface violations as conflicts to the Knowledge Graph.

Derived values retain source provenance and explicit label-combination policy. Declassification needs a bound approved transformation and actual recipient/processor checks; numeric confidence or lexical label ordering cannot authorize release. Domain amount fields in the example are ontology attributes, distinct from ActionBinding.amount’s explicit currency and non-negative integer minor units. Budget cost units have their own declared quantum and no implicit FX conversion.

Identity alignment

CEIDs (Canonical Entity IDs) are generated and resolved by the Identity Layer. The Ontology defines the entity types, relationship rules, classification rules, and constraints that a CEID must resolve against. A change that invalidates existing CEID resolution is a breaking ontology change.

Interfaces

Inputs

• Source schemas, business glossaries, regulatory definitions
• Entity-resolution rules and confidence thresholds
• Domain-owner approvals

Outputs

• Versioned ontology bundles
• Compatibility report between adjacent versions
• Migration scripts for refining and breaking changes
• Validation rules consumed by the Knowledge Graph

Failure modes

• Implicit semantic drift across teams when changes are not classified honestly (a “refining” change that is actually breaking).
• Derived fields that depend on stale inputs and silently mislead retrieval.
• Ontology change merged without dependent-pack revalidation, breaking compilations in production.
• PII-classified attribute downgraded to INTERNAL, opening a write-back path that violates Memory governance.
• Multiple ontology versions live in the same environment because promotion was not atomic.

Operational concerns

• One pinned ontology version per environment.
• Atomic promotion across the snapshot index, the Context Pack registry, and the Decision Catalog.
• Backward compatibility for at least one minor version during deprecation windows.
• Staged rollout with shadow-compile of packs before flipping reads.
• Audit trail of approver, change class, and migration outcome.

Evaluation metrics

• Compilation success rate against the active ontology version.
• Number of breaking changes per release window.
• Mean time from authored change to production rollout.
• Migration completeness (zero open dependents at version cut-over).
• Drift detected between sibling environments (should be one minor version at most).

Example

A minimal slice of a support-domain ontology:

ontology_version: "ont.support@4.2.0"
entity_types:
  - name: Customer
    ceid_format: "customer:cus_<id>"
    attributes:
      - { name: email, type: string, classification: CONFIDENTIAL }
      - { name: lifetime_value_inr, type: number, classification: INTERNAL }
      - { name: tenure_days, type: integer, classification: INTERNAL }
    lifecycle_states: [active, dormant, churned]
  - name: Order
    ceid_format: "order:ord_<id>"
    attributes:
      - { name: total_amount_inr, type: number, classification: INTERNAL }
      - { name: created_at, type: timestamp, classification: INTERNAL }
relationship_types:
  - name: order_belongs_to_customer
    from: Order
    to: Customer
    cardinality: many_to_one
constraints:
  - "Order.total_amount_inr >= 0"
derived_fields:
  - name: order_age_days
    type: integer
    expression: "days_between(evaluation_time, Order.created_at)"
    inputs: [evaluation_time, Order.created_at]

Common misconceptions

• It is not a database schema. Database schemas are physical layouts; the ontology is the semantic contract above them.
• A shared semantic contract does not require one database product. Cross-team agents need versioned meaning and compatibility rules; deployments may materialize them through different stores and services.
• It is not free to change. The runtime treats ontology changes as governance events, not config tweaks.