evolution.h File Reference

Harness evolution loop — compiler as evolutionary oracle (issue #80). More...

#include <neograph/api.h>
#include <neograph/graph/types.h>
#include <neograph/graph/compiler.h>
#include <neograph/graph/validator.h>
#include <functional>
#include <optional>
#include <random>
#include <string>
#include <vector>

Include dependency graph for evolution.h:

Go to the source code of this file.

Classes
struct	neograph::graph::EvolutionConfig
	Parameters for one evolution generation. More...
struct	neograph::graph::EvolutionResult
	Result of one evolution run. More...
struct	neograph::graph::Individual
	One individual in the population. More...
struct	neograph::graph::MutationResult
	Result of applying a single mutation. More...
struct	neograph::graph::Score
	Score of a single graph run against a task. More...
struct	neograph::graph::Task
	A task is a fixed-input → expected-output contract that a compiled graph should satisfy. More...

Typedefs
using	neograph::graph::MutationOp = std::function< MutationResult(const json &core, std::mt19937 &rng)>
	Mutation operator: deterministic function (input core + rng) → result.

Enumerations
enum class	neograph::graph::MutationKind : uint8_t { TOGGLE_CONDITIONAL_EDGE = 0 , TOGGLE_BARRIER , ADD_EDGE , REMOVE_EDGE }
	Catalog of built-in mutation operators, returned by all_operators(). More...

Functions
NEOGRAPH_API std::vector< MutationOp >	neograph::graph::all_operators ()
	Return a vector of one operator per MutationKind.
NEOGRAPH_API Score	neograph::graph::evaluate (const json &core, const Task &task, const NodeContext &ctx)
	Scorer function: compile-gate + run + compare against task.
NEOGRAPH_API EvolutionResult	neograph::graph::evolve (const json &seed_core, const Task &task, const EvolutionConfig &config=EvolutionConfig{})
	Run the evolution loop.
NEOGRAPH_API json	neograph::graph::to_json (const EvolutionResult &result)
	Serialize an EvolutionResult as a JSON lineage document.

Detailed Description

Harness evolution loop — compiler as evolutionary oracle (issue #80).

Three layers:

1. Mutation operators — strict Core topology mutations that preserve schema validity. Each operator takes a strict Core JSON topology and a deterministic seed, returns a mutated Core document, or nullopt when the mutation cannot be applied to the given graph.
2. Task + Scorer — a fixed-input → expected-output contract, with a scoring function that executes a CompiledGraph against it.
3. Selection loop — given N mutations per generation, compile-gate each (zero-cost), run evaluation on survivors, keep top K.

Genealogy

Every evolutionary run produces a diffable strict Core JSON lockfile. It is suitable for canonical interchange, git review, and rollback without a separate source-language map.

Design constraints

• Core-owned mutation space: operators mutate only known strict Core fields (conditional edges, barriers, and graph edges). This keeps source language semantics out of the evolutionary API while retaining a high ratio of structurally valid offspring.
• Deterministic: same seed → same mutation sequence. Crucial for bisection and A/B comparison.
• Zero-cost gate first: every mutation passes through GraphCompiler + GraphValidator before evaluation. Invalid offspring are rejected without execution, and the rejection rate is itself a metric (high rejection = mutation operator is producing junk).

Definition in file evolution.h.

Typedef Documentation

MutationOp

using neograph::graph::MutationOp = typedef std::function<MutationResult(const json& core, std::mt19937& rng)>

Mutation operator: deterministic function (input core + rng) → result.

The operator reads from rng for any stochastic choices; giving the same rng state to the same input produces the same output.

Definition at line 66 of file evolution.h.

Enumeration Type Documentation

MutationKind

enum class neograph::graph::MutationKind : uint8_t

strong

Catalog of built-in mutation operators, returned by all_operators().

Enumerator
TOGGLE_CONDITIONAL_EDGE	Add or remove a conditional_edges entry on a node.
TOGGLE_BARRIER	Toggle a barrier on/off for a fan-in node (add or remove the barrier spec).
ADD_EDGE	Add a new edge from a node to another reachable node.
REMOVE_EDGE	Remove an existing plain edge.

Definition at line 69 of file evolution.h.

Function Documentation

all_operators()

NEOGRAPH_API std::vector< MutationOp > neograph::graph::all_operators

(

)

Return a vector of one operator per MutationKind.

Each operator is a self-contained MutationOp that reads from the provided rng.

References neograph::graph::all_operators().

Referenced by neograph::graph::all_operators().

evaluate()

NEOGRAPH_API Score neograph::graph::evaluate	(	const json &	core,
		const Task &	task,
		const NodeContext &	ctx
	)

Scorer function: compile-gate + run + compare against task.

Returns a Score.

References neograph::graph::evaluate().

Referenced by neograph::graph::evaluate().

to_json()

NEOGRAPH_API json neograph::graph::to_json

(

const EvolutionResult &

result

)

Serialize an EvolutionResult as a JSON lineage document.

Contains the full genealogy, compile-gate stats, and best individual.