SPEC-EVO-002 — Graph Engine

Purpose

The graph engine makes relationships between research objects first-class while preserving Markdown as canonical serialization.

Canonical edge model

Every relationship MUST declare a source OID, target OID, edge type, and provenance. Core edge types are:

• supports
• contradicts
• derived_from
• answers
• refines
• replaces
• depends_on
• references
• uses
• supersedes

Custom edge types MAY be added only through a registered extension and MUST NOT redefine core semantics.

Requirements

1. All graph nodes MUST resolve to canonical OIDs.
2. Broken targets, duplicate edge identities, and invalid edge types MUST fail strict validation.
3. Edge direction MUST be preserved.
4. Edge provenance MUST identify the declaring object or relationship record.
5. The generated graph MUST be reproducible from repository content.
6. Circular relationships MAY exist unless prohibited by a specific edge contract; prohibited cycles MUST be reported with a traversable path.
7. Graph indexes MUST be disposable and rebuildable.

Operations

QLens SHOULD provide neighborhood traversal, reverse references, path discovery, orphan detection, unsupported-meaning detection, contradiction discovery, and impact analysis.

Acceptance criteria

• A clean rebuild produces a deterministic node and edge set.
• Removing an index does not remove knowledge.
• A changed edge is visible in Git history.
• A user can identify every reasoning object affected by a selected evidence object.

Non-goals

The graph engine is not an independent source of truth and MUST NOT require a server database for basic repository operation.