Knowledge Ontology¶

Overview¶

The ontology subsystem provides a typed knowledge framework for structured entity management. It layers on top of the Knowledge Graph, adding:

• Schema governance -- lifecycle stages for types and predicates (proposed → shadow → active)
• Truth maintenance -- temporal facts with source precedence and conflict detection
• Entity resolution -- alias-based deduplication with merge/split operations
• Property store -- typed entity properties with query support
• Access control -- role-based permissions (read/write/admin) per principal
• P2P exchange -- cross-network schema and fact synchronization

Architecture¶

OntologyService (facade)
├── Registry            — type + predicate definitions with schema versioning
├── TruthMaintainer     — temporal fact assertion, conflict detection, auto-resolution
├── EntityResolver      — alias management, merge/split, canonical ID resolution
├── PropertyStore       — typed entity properties, query by type + filters
├── ACLPolicy           — role-based operation gating (read/write/admin)
├── GovernanceEngine    — schema lifecycle FSM, rate limiting, explosion budget
├── ActionExecutor      — custom registered ontology actions
└── Graph Store         — underlying BoltDB triple store

All consumers interact through the OntologyService interface -- never reference internal components directly.

Schema Lifecycle¶

When governance is enabled, types and predicates follow a lifecycle FSM:

proposed → quarantined → proposed (retry)
proposed → shadow → active → deprecated
shadow → quarantined (rollback)

Rate limiting: Combined daily limit for type + predicate proposals (governance.maxNewPerDay). Monthly explosion budget caps total new proposals (governance.schemaExplosionBudget).

Auto-promotion: Types/predicates in shadow mode are promoted to active when usage count reaches governance.minUsageForPromotion.

Truth Maintenance¶

Facts are asserted with temporal metadata and source provenance:

AssertFact(subject, predicate, object, validFrom, validTo, source, confidence)

Temporal metadata keys:

Source precedence (higher = higher priority):

Conflicting facts on the same (subject, predicate) are auto-resolved when source precedence differs. Otherwise, conflicts are stored for manual resolution via ResolveConflict.

Entity Resolution¶

Entities can have multiple aliases pointing to a single canonical ID:

• DeclareSameAs(A, B) -- link two entity IDs as the same entity
• MergeEntities(canonical, duplicate) -- merge triples from duplicate into canonical
• SplitEntity(canonical, splitOut) -- reverse a merge
• Resolve(rawID) -- resolve any alias to its canonical ID

All triple queries automatically resolve aliases before searching the graph store.

Property Store¶

Entities have typed properties (key-value pairs) stored alongside their graph triples:

• SetEntityProperty -- set a property on an entity (with entity type tracking)
• GetEntityProperties -- retrieve all properties for an entity
• QueryEntities -- search entities by type and property filters
• GetEntity -- full entity view (properties + relationships)

Access Control¶

When ACL is enabled, operations are gated by permission level:

Roles are assigned per principal in configuration. P2P peers default to the p2pPermission level (default: write).

P2P Exchange¶

When both P2P and ontology are enabled, schemas and facts can be exchanged between peers:

• Schema exchange -- export/import type and predicate definitions as bundles
• Fact exchange -- assert facts from remote peers with source p2p_exchange
• Trust thresholds -- configurable minimum peer trust scores for schema vs. fact exchange
• Auto-import modes -- shadow (default), governed (subject to full lifecycle), or disabled

Agent Tools¶

The ontologist agent has access to 19+ tools:

Custom actions registered via ActionRegistry generate dynamic tools (ontology_action_*).

Configuration¶

See Configuration Reference for all configuration keys.

{
  "ontology": {
    "enabled": true,
    "governance": { "enabled": true },
    "acl": { "enabled": true, "roles": { "operator": "write", "librarian": "read" } },
    "exchange": { "enabled": true }
  }
}