Taxonomy Semantic Graphs

Experimental Feature

Semantic Graphs are an experimental extension to the taxonomy system. They power the drift detection engine and may change without notice.

Overview

Every Mandaitor taxonomy now includes an optional semantic graph that models relationships between actions beyond the existing parent-child hierarchy. While the hierarchy tells you that construction.validation.approve is a child of construction.validation, the semantic graph tells you that approve conflicts with reject, that inspect precedes approve, and that flag escalates to halt.

Relationship Types

Type	Direction	Semantics	Use in Drift Detection
IMPLIES	A → B	A logically leads to B	Expected workflow patterns
CONFLICTS	A ↔ B	A and B should not co-occur in the same session	Conflict detection
ESCALATES_TO	A → B	B is a higher-authority version of A	Escalation tracking
PART_OF	A → B	A is a sub-step of B	Cluster membership
PRECEDES	A → B	A should happen before B	Sequence validation

Each edge carries a weight between 0.0 and 1.0 indicating the strength of the relationship, and an optional rationale explaining why the relationship exists.

Auto-Inference

Semantic graphs are primarily auto-inferred from the taxonomy's existing metadata:

1. Parent-child hierarchy → PART_OF edges (child is part of parent)
2. Shared tags → IMPLIES edges between actions with overlapping tags
3. Risk level progression → ESCALATES_TO edges between actions where one has a higher risk level than another in the same domain
4. Conflicting tags → CONFLICTS edges between actions tagged with opposing concepts (e.g., "approval" vs. "rejection")

The SemanticGraphEngine in @mandaitor/taxonomy-core handles this inference:

import { SemanticGraphEngine } from "@mandaitor/taxonomy-core";

const engine = new SemanticGraphEngine();
const graph = engine.inferSemanticGraph(taxonomy.actions);

// Query relationships
const conflicts = engine.getConflicts("construction.validation.approve");
// → [{ target: "construction.validation.reject", weight: 0.9 }]

const distance = engine.semanticDistance(
  "construction.validation.inspect",
  "construction.validation.approve",
);
// → 0.15 (close — inspect implies approve)

Manual Overrides

Taxonomy contributors can define explicit semantic edges that supplement or override the auto-inferred graph. These are defined in a semantic-graph.ts file within each taxonomy package:

import type { SemanticEdge } from "@mandaitor/taxonomy-core";

export const semanticEdges: SemanticEdge[] = [
  {
    source: "construction.validation.inspect",
    target: "construction.validation.approve",
    type: "PRECEDES",
    weight: 0.85,
    rationale: "Inspection should precede approval in standard workflow",
  },
];

Available Graphs

Semantic graphs are available for all eight industry taxonomies:

• Aviation
• Construction
• Defence & ISR
• Healthcare
• Maritime
• Real Estate
• Space
• Venture Capital

Each graph is auto-generated from the taxonomy's action definitions and can be extended with manual overrides by taxonomy contributors.