Skip to content

EIDOS Explorer — Developer Reference

This reference manual is compiled from the Documentation Knowledge Model (KM). All content is derived from verified source files — no assertions are made from memory.

Architecture at a Glance

EIDOS Explorer is a distributed graph service. Each domain's graph lives in one store:

mutations/ overlay (JSON-LD, mutable — the only store)
    + tree declaration (runtime domains.json)
    =
Effective Graph (in-memory, rebuilt on demand)

Since #935 S5a the backend reads no .eidos ZIP base; python -m tools.migration convert (tools/migration/eidos_archive.py) is the only .eidos reader left.

Core Concepts

  • Effective Graph — the merged in-memory view that all APIs query
  • Overlay — the mutable store every node and relation lives in
  • Domain — independently deployable subtree served by one backend instance

Key Workflows

Invariants

System-wide guarantees that all implementations must preserve:

Knowledge Model (KM) contributor notes

Every KM entity YAML carries a sources.verified_at_commit field that records the main-branch commit at which the entity was last verified against the source code. The following rules apply:

  • Always use the squash-merge commit on main, never a branch commit. When a PR is squash-merged, the pre-squash feature-branch SHAs are dropped from the reachable history; a pin pointing at one will fail the guard immediately.
  • Set or re-stamp the pin after merge, not before. The squash-merge SHA only exists once the PR lands on main; the correct workflow is to verify the entity, merge the PR, then update verified_at_commit to the resulting squash-merge commit on main.
  • The pin guard enforces this automatically. tests/test_verification_pin_guard.py runs on every CI pass and fails if any pin is not a reachable ancestor of origin/main (falls back to HEAD when the remote is not available). A red CI run with "non-ancestor pins" means the pin points at a commit that was never on main; bump it to the correct squash-merge SHA to fix it.