neat/genome

First-class genome boundary for the proper-NEAT Step 7.1 lift.

This chapter owns the strict structural contract that sits between the NEAT controller and the executable Network phenotype. Its job is deliberately narrow in the first pass:

1. define the pure node-gene and connection-gene contract,
2. provide validated phenotype-to-genome and genome-to-phenotype adapters,
3. expose a pure genome-facing validation seam that later chapters can adopt without widening the public runtime Network surface.

Step 7.2a adds the first heredity-specific subchapter under genome/heredity/, where innovation-aligned connection-gene selection can move off the runtime crossover shelf while phenotype scaffolding stays in the Network layer.

Runtime activation state, species membership, controller replay metadata, and architecture allocation counters remain outside this boundary.

neat/genome/genome.types.ts

GenomeMaterializationRuntimeHints

Optional phenotype-only hints applied when materializing a Network from one strict genome contract.

These values do not become genome state. They exist so checkpoint import and other bridges can preserve non-genetic runtime metadata while the genotype boundary stays narrow.

NeatGenome

First-pass genotype contract for the proper-NEAT lift.

This is intentionally structural only. Replay state, species membership, controller-owned genome ids, caches, runtime node indexes, and activation traces stay outside this contract.

NeatGenomeCaptureOptions

Opt-in capture settings used when projecting runtime payloads into the strict genome contract.

NeatGenomeConnectionGene

Pure connection-gene contract owned by the NEAT subtree.

NeatGenomeExtensions

Versioned extension bag reserved for beyond-paper genome traits.

Step 7.1 keeps this bag optional and empty by default so the structural identity contract can land without immediately committing to extension semantics. Later phases can add opt-in traits here without widening the core node-gene and connection-gene shapes.

NeatGenomeExtensionValues

Typed extension payload reserved for additive beyond-paper genome traits.

NeatGenomeGatedBlockDescriptor

Descriptor for one explicit gated block stored in the extension bag.

Gated blocks preserve grouped gating intent without changing canonical connection-gene ownership. The descriptor is therefore about identity and checkpoint semantics, not about replacing individual connection genes. Disabled gated connection genes still count as dormant block structure until the connection or gater identity is removed from the genome.

NeatGenomeNodeGene

Pure node-gene contract owned by the NEAT subtree.

Array order carries the canonical interface ordering. Runtime node indexes do not belong here because they are phenotype-only bookkeeping rebuilt during materialization.

NeatGenomeNodeType

Canonical node-role literals supported by the first-pass NEAT genome boundary.

NeatGenomeRecurrentModuleDescriptor

Descriptor for one explicit recurrent module stored in the extension bag.

The executable graph still lives in canonical node and connection genes. This additive descriptor preserves the higher-level block identity so checkpoints and later mutation passes can tell an intentional recurrent module from an arbitrary cyclic subgraph. Disabling one referenced connection gene does not retire the module by itself; the descriptor stays valid until the referenced genes or gating ownership disappear structurally.

NeatGenomeRecurrentModuleKind

Supported recurrent-module kinds tracked by the Step 7.4 extension lane.

NeatGenomeValidationIssue

One finding produced by the pure genome validator.

NeatGenomeValidationIssueCode

Stable issue codes reported by the pure genome validator.

NeatGenomeValidationReport

Validation report for one strict genome contract.

neat/genome/genome.ts

assertValidGenomeContract

assertValidGenomeContract(
  genome: NeatGenome,
): void

Assert that one strict genome contract is valid.

Parameters:

• genome - Strict structural genome contract.

Returns: Nothing.

createCompatibilityGenomeView

createCompatibilityGenomeView(
  source: GenomeLike | NeatGenome | RuntimeCompatibilitySource,
): GenomeLike

Create the compatibility-layer view for a runtime phenotype or strict genome.

Native explicit-innovation flows are normalized through the strict genome contract. Deliberate fallback-innovation flows remain on the legacy runtime edge path so compatibility can keep using endpoint-derived synthetic ids.

Parameters:

• source - Runtime genome or strict genome contract.

Returns: Compatibility-layer genome view.

createGenomeFromNetwork

createGenomeFromNetwork(
  network: default,
  captureOptions: NeatGenomeCaptureOptions,
): NeatGenome

Convert one executable phenotype into the strict NEAT genome contract.

This is the phenotype-to-genome adapter introduced in Step 7.1. It strips runtime-only state and keeps only structural identity plus portable gene attributes.

Parameters:

• network - Executable phenotype.
• captureOptions - Optional opt-in runtime-to-genome extension capture settings.

Returns: Strict structural genome contract.

createGenomeFromNetworkJson

createGenomeFromNetworkJson(
  networkJson: NetworkJSON,
  captureOptions: NeatGenomeCaptureOptions,
): NeatGenome

Convert one versioned network JSON payload into the strict NEAT genome contract.

Parameters:

• networkJson - Versioned phenotype JSON payload.
• captureOptions - Optional opt-in runtime-to-genome extension capture settings.

Returns: Strict structural genome contract.

createNetworkFromGenome

createNetworkFromGenome(
  genome: NeatGenome,
  runtimeHints: GenomeMaterializationRuntimeHints,
): default

Materialize one executable phenotype from the strict genome contract.

Parameters:

• genome - Strict structural genome contract.
• runtimeHints - Optional phenotype-only metadata to preserve.

Returns: Executable runtime phenotype.

createNetworkJsonFromGenome

createNetworkJsonFromGenome(
  genome: NeatGenome,
  runtimeHints: GenomeMaterializationRuntimeHints,
): NetworkJSON

Convert one strict genome contract into the versioned network JSON payload understood by the runtime phenotype serializer.

Parameters:

• genome - Strict structural genome contract.
• runtimeHints - Optional phenotype-only metadata to preserve.

Returns: Versioned network JSON payload.

GenomeHereditySelectionContext

Pure selection context for innovation-aligned genome heredity.

This contract keeps the heredity pass structural-first: two strict genomes, the fitness or equality policy that decides disjoint inheritance, and the deterministic RNG that resolves matching-gene choices plus disabled-gene re-enable behavior.

GenomeHereditySourceParent

Stable parent labels used by the genome-owned heredity selector.

GenomeMaterializationRuntimeHints

Optional phenotype-only hints applied when materializing a Network from one strict genome contract.

These values do not become genome state. They exist so checkpoint import and other bridges can preserve non-genetic runtime metadata while the genotype boundary stays narrow.

NeatGenome

First-pass genotype contract for the proper-NEAT lift.

This is intentionally structural only. Replay state, species membership, controller-owned genome ids, caches, runtime node indexes, and activation traces stay outside this contract.

NeatGenomeCaptureOptions

Opt-in capture settings used when projecting runtime payloads into the strict genome contract.

NeatGenomeConnectionGene

Pure connection-gene contract owned by the NEAT subtree.

NeatGenomeConversionError

Raised when one boundary tries to project malformed state into the strict genome contract.

NeatGenomeExtensions

Versioned extension bag reserved for beyond-paper genome traits.

Step 7.1 keeps this bag optional and empty by default so the structural identity contract can land without immediately committing to extension semantics. Later phases can add opt-in traits here without widening the core node-gene and connection-gene shapes.

NeatGenomeExtensionValues

Typed extension payload reserved for additive beyond-paper genome traits.

NeatGenomeGatedBlockDescriptor

Descriptor for one explicit gated block stored in the extension bag.

Gated blocks preserve grouped gating intent without changing canonical connection-gene ownership. The descriptor is therefore about identity and checkpoint semantics, not about replacing individual connection genes. Disabled gated connection genes still count as dormant block structure until the connection or gater identity is removed from the genome.

NeatGenomeNodeGene

Pure node-gene contract owned by the NEAT subtree.

Array order carries the canonical interface ordering. Runtime node indexes do not belong here because they are phenotype-only bookkeeping rebuilt during materialization.

NeatGenomeNodeType

Canonical node-role literals supported by the first-pass NEAT genome boundary.

NeatGenomeRecurrentModuleDescriptor

Descriptor for one explicit recurrent module stored in the extension bag.

The executable graph still lives in canonical node and connection genes. This additive descriptor preserves the higher-level block identity so checkpoints and later mutation passes can tell an intentional recurrent module from an arbitrary cyclic subgraph. Disabling one referenced connection gene does not retire the module by itself; the descriptor stays valid until the referenced genes or gating ownership disappear structurally.

NeatGenomeRecurrentModuleKind

Supported recurrent-module kinds tracked by the Step 7.4 extension lane.

NeatGenomeValidationError

Raised when a strict genome contract fails validation.

issues

Structured validator findings attached to the thrown error.

NeatGenomeValidationIssue

One finding produced by the pure genome validator.

NeatGenomeValidationIssueCode

Stable issue codes reported by the pure genome validator.

NeatGenomeValidationReport

Validation report for one strict genome contract.

SelectedGenomeConnectionGene

One inherited connection gene selected by the genome-owned heredity pass.

The source-parent label preserves parent provenance for runtime adapters and future narrow seams without pushing runtime node indexing into the genome surface.

selectGenomeHeredityConnectionGenes

selectGenomeHeredityConnectionGenes(
  context: GenomeHereditySelectionContext,
): SelectedGenomeConnectionGene[]

Select inherited connection genes using only the strict genome contract.

Step 7.2a moves innovation-aligned heredity selection behind the genome boundary without widening the runtime crossover facade. The runtime shelf still owns node scaffolding and phenotype materialization, while this helper owns three structural decisions:

1. collect parent connection genes by preserved innovation number,
2. resolve matching, disjoint, and excess inheritance from scores plus equal-mode policy,
3. apply the explicit disabled-gene re-enable rule through the inherited RNG.

Parameters:

• context - Pure genome heredity context.

Returns: Ordered inherited connection genes plus their source-parent labels.

Example:

const selectedGenes = selectGenomeHeredityConnectionGenes({
  parent1Genome,
  parent2Genome,
  parent1Score: 2,
  parent2Score: 1,
  equal: false,
  randomGenerator: () => 0.25,
});

validateGenomeContract

validateGenomeContract(
  genome: NeatGenome,
): NeatGenomeValidationReport

Validate one strict genome contract.

Parameters:

• genome - Strict structural genome contract.

Returns: Structured validation report.

neat/genome/genome.errors.ts

NeatGenomeConversionError

Raised when one boundary tries to project malformed state into the strict genome contract.

NeatGenomeValidationError

Raised when a strict genome contract fails validation.

issues

Structured validator findings attached to the thrown error.

neat/genome/genome.utils.ts

assertValidGenomeContract

assertValidGenomeContract(
  genome: NeatGenome,
): void

Assert that one strict genome contract is valid.

Parameters:

• genome - Strict structural genome contract.

Returns: Nothing.

createCompatibilityGenomeView

createCompatibilityGenomeView(
  source: GenomeLike | NeatGenome | RuntimeCompatibilitySource,
): GenomeLike

Create the compatibility-layer view for a runtime phenotype or strict genome.

Native explicit-innovation flows are normalized through the strict genome contract. Deliberate fallback-innovation flows remain on the legacy runtime edge path so compatibility can keep using endpoint-derived synthetic ids.

Parameters:

• source - Runtime genome or strict genome contract.

Returns: Compatibility-layer genome view.

createGenomeFromNetwork

createGenomeFromNetwork(
  network: default,
  captureOptions: NeatGenomeCaptureOptions,
): NeatGenome

Convert one executable phenotype into the strict NEAT genome contract.

This is the phenotype-to-genome adapter introduced in Step 7.1. It strips runtime-only state and keeps only structural identity plus portable gene attributes.

Parameters:

• network - Executable phenotype.
• captureOptions - Optional opt-in runtime-to-genome extension capture settings.

Returns: Strict structural genome contract.

createGenomeFromNetworkJson

createGenomeFromNetworkJson(
  networkJson: NetworkJSON,
  captureOptions: NeatGenomeCaptureOptions,
): NeatGenome

Convert one versioned network JSON payload into the strict NEAT genome contract.

Parameters:

• networkJson - Versioned phenotype JSON payload.
• captureOptions - Optional opt-in runtime-to-genome extension capture settings.

Returns: Strict structural genome contract.

createNetworkFromGenome

createNetworkFromGenome(
  genome: NeatGenome,
  runtimeHints: GenomeMaterializationRuntimeHints,
): default

Materialize one executable phenotype from the strict genome contract.

Parameters:

• genome - Strict structural genome contract.
• runtimeHints - Optional phenotype-only metadata to preserve.

Returns: Executable runtime phenotype.

createNetworkJsonFromGenome

createNetworkJsonFromGenome(
  genome: NeatGenome,
  runtimeHints: GenomeMaterializationRuntimeHints,
): NetworkJSON

Convert one strict genome contract into the versioned network JSON payload understood by the runtime phenotype serializer.

Parameters:

• genome - Strict structural genome contract.
• runtimeHints - Optional phenotype-only metadata to preserve.

Returns: Versioned network JSON payload.

validateGenomeContract

validateGenomeContract(
  genome: NeatGenome,
): NeatGenomeValidationReport

Validate one strict genome contract.

Parameters:

• genome - Strict structural genome contract.

Returns: Structured validation report.