@reicek/neataptic-ts 0.1.26 → 0.1.27

package/src/neat/adaptive/core/README.md

@@ -1,39 +1,82 @@
 # neat/adaptive/core
 
-Contract map for the adaptive helper boundary.
+Reading map and stable index for the adaptive shared-vocabulary chapter.
+
+The other adaptive folders explain concrete feedback loops: acceptance
+rewrites scores, complexity rewrites structural budgets, mutation rewrites
+per-genome pressure, and lineage rewrites future diversity pressure. This
+folder exists for the question underneath all of them: what shared language
+lets those controllers stay narrow without each one inventing its own host
+contract, option slice, scratch-field names, and fallback constants?
+
+That is why `adaptive/core/` should be read as a glossary with ownership,
+not as a bag of types. `adaptive.core.types.ts` defines what adaptive
+helpers are allowed to read and rewrite. `adaptive.core.constants.ts`
+defines the shared defaults, mode names, and numeric guard rails that keep
+those helpers speaking the same policy dialect. This file is the stable
+import surface that points later helpers at both shelves without making them
+depend on file-by-file internals.
+
+A useful mental model is to treat the chapter as the protocol layer between
+adaptive controllers. Complexity, acceptance, mutation, and lineage each own
+a different control loop, but they still have to agree on the shape of the
+host, the option slices they may inspect, and the small amount of adaptive
+state they may persist across generations.
 
-The adaptive subtree works because each policy chapter can stay focused on a
-single feedback loop while still sharing one precise agreement about what it
-may read, what it may rewrite, and which option family owns each tuning
-decision. This file is that agreement.
+```mermaid
+flowchart TD
+  Core[adaptive core index] --> Types[types<br/>host contract and working shapes]
+  Core --> Constants[constants<br/>defaults modes and guard rails]
+  Types --> Acceptance[acceptance helpers]
+  Types --> Complexity[complexity helpers]
+  Types --> Mutation[mutation helpers]
+  Types --> Lineage[lineage helpers]
+  Constants --> Acceptance
+  Constants --> Complexity
+  Constants --> Mutation
+  Constants --> Lineage
+```
 
-Read the contracts in three passes:
+Read the chapter in three passes:
+
+1. start with `adaptive.core.types.ts` when the missing question is what an
+   adaptive helper may legally read or rewrite,
+2. continue through the re-exported aliases in this file when you want the
+   shortest stable import path for that vocabulary,
+3. finish with `adaptive.core.constants.ts` when the missing question is
+   which defaults, phase labels, thresholds, and clamps keep the adaptive
+   loops aligned.
+
+Example: type a new adaptive helper against the shared host contract instead
+of a broader `Neat` runtime surface.
+
+```ts
+import type {
+  NeatLikeWithAdaptive,
+  ComplexityBudgetConfig,
+} from './adaptive.core';
+
+function previewBudget(
+  engine: NeatLikeWithAdaptive,
+  config: ComplexityBudgetConfig,
+) {
+  return { generation: engine.generation, enabled: config.enabled ?? false };
+}
+```
 
-- start with `NeatLikeWithAdaptive` to see the runtime host surface and the
-  scratch fields adaptive controllers are allowed to maintain,
-- continue with the exported `*Config` aliases to see how complexity,
-  acceptance, mutation, operator adaptation, and lineage feedback each slice
-  the broader options object,
-- finish with `Genome`, `MutationSettings`, `MutationPartitions`, and
-  `MutationOutcome` when you want the normalized working shapes used inside
-  adaptive mutation helpers.
+Example: keep constants and contracts on one import path when an extracted
+helper needs both a typed option slice and a shared mode label.
 
-The matching defaults and mode labels live in `adaptive.core.constants.ts`.
-This file stays focused on contracts so the generated chapter reads as a
-bounded vocabulary map rather than a second controller implementation.
+```ts
+import type { PhasedComplexityConfig } from './adaptive.core';
+import { PHASE_COMPLEXIFY } from './adaptive.core.constants';
 
-```mermaid
-flowchart TD
-  Host[NeatLikeWithAdaptive host] --> Options[Adaptive option families]
-  Host --> Population[Population runtime state]
-  Host --> Scratch[Adaptive scratch fields and telemetry]
-  Options --> Complexity[Complexity and phased schedules]
-  Options --> Acceptance[Acceptance and minimal criterion]
-  Options --> Mutation[Mutation and operator adaptation]
-  Options --> Lineage[Ancestor uniqueness and lineage pressure]
+function isComplexifyPhase(config: PhasedComplexityConfig) {
+  return (config.initialPhase ?? PHASE_COMPLEXIFY) === PHASE_COMPLEXIFY;
+}
 ```
 
-## neat/adaptive/core/adaptive.core.types.ts
+## neat/adaptive/core/adaptive.core.ts
 
 ### AdaptiveMutationConfig
 
@@ -155,26 +198,40 @@ This isolates the alternating complexify/simplify schedule from the broader
 adaptive options object so phase-oriented helpers can stay narrow and think
 in terms of mode transitions instead of the entire adaptive policy surface.
 
-## neat/adaptive/core/adaptive.core.ts
+## neat/adaptive/core/adaptive.core.types.ts
 
-Index and reading map for the adaptive shared-vocabulary chapter.
+Contract map for the adaptive helper boundary.
 
-This file is intentionally thin. It does not define one more adaptive
-control loop; it points the rest of the subtree at the shared language that
-complexity, acceptance, mutation, and lineage helpers all reuse.
+The adaptive subtree works because each policy chapter can stay focused on a
+single feedback loop while still sharing one precise agreement about what it
+may read, what it may rewrite, and which option family owns each tuning
+decision. This file is that agreement.
 
-Read this chapter when you want the shortest route into `adaptive/core/`:
+Read the contracts in three passes:
 
-1. start with `adaptive.core.types.ts` to see the host contract, option
-   slices, and normalized working shapes,
-2. use the re-exported aliases in this file as the public index into that
-   contract map,
-3. finish with `adaptive.core.constants.ts` for the defaults, labels, and
-   guard rails that keep those adaptive loops speaking one vocabulary.
+- start with `NeatLikeWithAdaptive` to see the runtime host surface and the
+  scratch fields adaptive controllers are allowed to maintain,
+- continue with the exported `*Config` aliases to see how complexity,
+  acceptance, mutation, operator adaptation, and lineage feedback each slice
+  the broader options object,
+- finish with `Genome`, `MutationSettings`, `MutationPartitions`, and
+  `MutationOutcome` when you want the normalized working shapes used inside
+  adaptive mutation helpers.
+
+The matching defaults and mode labels live in `adaptive.core.constants.ts`.
+This file stays focused on contracts so the generated chapter reads as a
+bounded vocabulary map rather than a second controller implementation.
 
-Think of this file as the chapter's table of contents. The deeper semantics
-live in the types and constants files; this surface exists so downstream
-helpers can import one stable adaptive vocabulary from a single place.
+```mermaid
+flowchart TD
+  Host[NeatLikeWithAdaptive host] --> Options[Adaptive option families]
+  Host --> Population[Population runtime state]
+  Host --> Scratch[Adaptive scratch fields and telemetry]
+  Options --> Complexity[Complexity and phased schedules]
+  Options --> Acceptance[Acceptance and minimal criterion]
+  Options --> Mutation[Mutation and operator adaptation]
+  Options --> Lineage[Ancestor uniqueness and lineage pressure]
+```
 
 ### AdaptiveMutationConfig
 

package/src/neat/adaptive/core/adaptive.core.ts

@@ -1,22 +1,79 @@
 /**
- * Index and reading map for the adaptive shared-vocabulary chapter.
+ * Reading map and stable index for the adaptive shared-vocabulary chapter.
  *
- * This file is intentionally thin. It does not define one more adaptive
- * control loop; it points the rest of the subtree at the shared language that
- * complexity, acceptance, mutation, and lineage helpers all reuse.
+ * The other adaptive folders explain concrete feedback loops: acceptance
+ * rewrites scores, complexity rewrites structural budgets, mutation rewrites
+ * per-genome pressure, and lineage rewrites future diversity pressure. This
+ * folder exists for the question underneath all of them: what shared language
+ * lets those controllers stay narrow without each one inventing its own host
+ * contract, option slice, scratch-field names, and fallback constants?
  *
- * Read this chapter when you want the shortest route into `adaptive/core/`:
+ * That is why `adaptive/core/` should be read as a glossary with ownership,
+ * not as a bag of types. `adaptive.core.types.ts` defines what adaptive
+ * helpers are allowed to read and rewrite. `adaptive.core.constants.ts`
+ * defines the shared defaults, mode names, and numeric guard rails that keep
+ * those helpers speaking the same policy dialect. This file is the stable
+ * import surface that points later helpers at both shelves without making them
+ * depend on file-by-file internals.
  *
- * 1. start with `adaptive.core.types.ts` to see the host contract, option
- *    slices, and normalized working shapes,
- * 2. use the re-exported aliases in this file as the public index into that
- *    contract map,
- * 3. finish with `adaptive.core.constants.ts` for the defaults, labels, and
- *    guard rails that keep those adaptive loops speaking one vocabulary.
+ * A useful mental model is to treat the chapter as the protocol layer between
+ * adaptive controllers. Complexity, acceptance, mutation, and lineage each own
+ * a different control loop, but they still have to agree on the shape of the
+ * host, the option slices they may inspect, and the small amount of adaptive
+ * state they may persist across generations.
  *
- * Think of this file as the chapter's table of contents. The deeper semantics
- * live in the types and constants files; this surface exists so downstream
- * helpers can import one stable adaptive vocabulary from a single place.
+ * ```mermaid
+ * flowchart TD
+ *   Core[adaptive core index] --> Types[types<br/>host contract and working shapes]
+ *   Core --> Constants[constants<br/>defaults modes and guard rails]
+ *   Types --> Acceptance[acceptance helpers]
+ *   Types --> Complexity[complexity helpers]
+ *   Types --> Mutation[mutation helpers]
+ *   Types --> Lineage[lineage helpers]
+ *   Constants --> Acceptance
+ *   Constants --> Complexity
+ *   Constants --> Mutation
+ *   Constants --> Lineage
+ * ```
+ *
+ * Read the chapter in three passes:
+ *
+ * 1. start with `adaptive.core.types.ts` when the missing question is what an
+ *    adaptive helper may legally read or rewrite,
+ * 2. continue through the re-exported aliases in this file when you want the
+ *    shortest stable import path for that vocabulary,
+ * 3. finish with `adaptive.core.constants.ts` when the missing question is
+ *    which defaults, phase labels, thresholds, and clamps keep the adaptive
+ *    loops aligned.
+ *
+ * Example: type a new adaptive helper against the shared host contract instead
+ * of a broader `Neat` runtime surface.
+ *
+ * ```ts
+ * import type {
+ *   NeatLikeWithAdaptive,
+ *   ComplexityBudgetConfig,
+ * } from './adaptive.core';
+ *
+ * function previewBudget(
+ *   engine: NeatLikeWithAdaptive,
+ *   config: ComplexityBudgetConfig,
+ * ) {
+ *   return { generation: engine.generation, enabled: config.enabled ?? false };
+ * }
+ * ```
+ *
+ * Example: keep constants and contracts on one import path when an extracted
+ * helper needs both a typed option slice and a shared mode label.
+ *
+ * ```ts
+ * import type { PhasedComplexityConfig } from './adaptive.core';
+ * import { PHASE_COMPLEXIFY } from './adaptive.core.constants';
+ *
+ * function isComplexifyPhase(config: PhasedComplexityConfig) {
+ *   return (config.initialPhase ?? PHASE_COMPLEXIFY) === PHASE_COMPLEXIFY;
+ * }
+ * ```
  */
 export type {
   AdaptiveMutationConfig,

package/src/neat/adaptive/core/docs.order.json

@@ -0,0 +1,8 @@
+{
+  "introFile": "adaptive.core.ts",
+  "fileOrder": [
+    "adaptive.core.ts",
+    "adaptive.core.types.ts",
+    "adaptive.core.constants.ts"
+  ]
+}

package/src/neat/docs.order.json

@@ -0,0 +1,9 @@
+{
+  "introFile": "neat.defaults.constants.ts",
+  "fileOrder": [
+    "neat.defaults.constants.ts",
+    "neat.types.ts",
+    "neat.lineage.ts",
+    "neat.constants.ts"
+  ]
+}

package/src/neat/lineage/README.md

@@ -9,33 +9,135 @@ telemetry, diagnostics, or adaptive policy need to detect whether a run is
 still exploring multiple lineages or quietly collapsing onto descendants of a
 small ancestor set.
 
-The root chapter keeps two public read models together:
-
-- `buildAnc()` builds one genome's shallow ancestor set.
-- `computeAncestorUniqueness()` turns many shallow ancestor sets into one
-  sampled population signal.
-
-Read the chapter in this order:
-
-- `buildAnc()` when you want the raw ancestry evidence for one genome.
-- `computeAncestorUniqueness()` when you want the controller-facing summary
-  used by telemetry, diagnostics, or adaptive lineage pressure.
-- `core/` when you need the breadth-first traversal, pair sampling, or
-  Jaccard-distance mechanics behind the public helpers.
+In evolutionary systems, structural variety can be misleading on its own.
+Two genomes can look different because they drifted locally through weight
+updates or a few recent mutations while still descending from the same narrow
+branch. Lineage reads add the missing genealogical context. They let the
+controller ask whether today's population still contains multiple recent
+family stories or whether most of the search budget is now being spent on one
+ancestor neighborhood wearing several slightly different topologies.
+
+That distinction is useful because NEAT already has several other lenses on
+search health. Compatibility distance explains structural disagreement.
+Novelty explains behavioral difference. Score trends explain whether the
+current search path is paying off. Lineage contributes a separate clue: how
+much of the population's recent history is shared. If compatibility says
+genomes are spread out but lineage says they still share recent parents, the
+run may be exploring one branch in detail rather than keeping multiple
+evolutionary bets alive.
+
+The core algorithmic idea is intentionally simple. `buildAnc()` performs a
+bounded breadth-first walk over parent ids so it can recover a shallow family
+neighborhood for one genome. `computeAncestorUniqueness()` then samples genome
+pairs and compares those shallow ancestor sets with a Jaccard-style distance.
+The result is not a full phylogenetic tree or a museum-grade genealogy. It is
+a lightweight controller signal designed to stay cheap enough for runtime
+telemetry while still capturing whether the population's recent ancestry is
+broad or collapsing.
+
+Read this chapter with two silent reader questions in mind. First: what kind
+of historical evidence is lineage actually measuring? Second: why stop at a
+shallow ancestry window instead of walking every parent back to the origin?
+The answer to the first is recent overlap in parentage, not lifetime
+similarity. The answer to the second is that controller telemetry needs the
+ancestry evidence that is most actionable now. Shallow ancestry is usually a
+better indicator of current branch collapse, takeover, or recent divergence
+than an unbounded tree that keeps every distant common ancestor equally loud.
+
+One useful mental model is to treat lineage as the population's memory of
+"who recently came from whom." It does not replace structural or behavioral
+metrics. It complements them. A run with strong scores and low lineage
+uniqueness may be exploiting aggressively around one family. A run with high
+lineage uniqueness and weak scores may still be exploring many recent
+branches without yet consolidating progress. Seeing those regimes explicitly
+helps the rest of the telemetry and adaptation stack read less like a pile of
+unrelated numbers.
 
 ```mermaid
 flowchart TD
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
   Genome[Genome with parent ids] --> Ancestors[Shallow ancestor set]
   Population[Population genomes] --> Pairs[Sample genome pairs]
   Ancestors --> Distance[Compare ancestor overlap]
   Pairs --> Distance
   Distance --> Uniqueness[Ancestor uniqueness summary]
   Uniqueness --> Consumers[Telemetry diagnostics and adaptive lineage policy]
+
+  class Genome,Ancestors,Population,Pairs,Distance,Consumers base;
+  class Uniqueness accent;
+```
+
+A second view places lineage beside the other common NEAT health signals so
+a first-time reader can see what question each metric family is really
+answering.
+
+```mermaid
+flowchart LR
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  Population[Current population]:::base --> Compat[Compatibility distance<br/>How structurally different?]:::base
+  Population --> Novelty[Behavioral novelty<br/>How behaviorally different?]:::base
+  Population --> Fitness[Fitness trend<br/>How well is the run scoring?]:::base
+  Population --> Lineage[Lineage uniqueness<br/>How many recent families remain?]:::accent
 ```
 
-The root chapter stays compact on purpose. `core/` owns the queue mechanics,
-sampled pair generation, and distance aggregation so this file can stay
-focused on what the ancestry reads mean at the controller surface.
+A third view explains why the implementation stops after a bounded ancestry
+window instead of treating lineage as a full archive query.
+
+```mermaid
+flowchart TD
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  FullTree[Walk every ancestor forever]:::base --> Expensive[Expensive and historically noisy]:::base
+  Window[Walk only a shallow recent window]:::accent --> Actionable[Cheaper and better aligned to current takeover risk]:::base
+  Expensive --> Telemetry[Harder to reuse inside runtime telemetry]:::base
+  Actionable --> Telemetry
+```
+
+The root chapter therefore stays small in API surface but rich in meaning.
+`core/` owns the queue mechanics, sampled pair generation, and distance
+aggregation so this file can stay focused on what the ancestry reads mean at
+the controller surface. That separation is deliberate: the public question is
+not "how does the queue advance?" but "what kind of evidence does lineage add
+that the rest of the controller does not already have?"
+
+For background reading, the most relevant mathematical and traversal ideas
+are the breadth-first search used for the shallow family walk and the Jaccard
+index used to compare ancestor-set overlap. See Wikipedia contributors,
+[Breadth-first search](https://en.wikipedia.org/wiki/Breadth-first_search),
+and Wikipedia contributors,
+[Jaccard index](https://en.wikipedia.org/wiki/Jaccard_index), for compact
+background on the two ideas this chapter adapts into a runtime NEAT signal.
+
+Example: inspect the recent family neighborhood behind one genome.
+
+```ts
+const ancestorIds = neat.buildAnc(neat.population[0]);
+
+console.log([...ancestorIds].toSorted((leftId, rightId) => leftId - rightId));
+```
+
+Example: watch whether the run is collapsing onto a narrow recent lineage.
+
+```ts
+const ancestorUniqueness = neat.computeAncestorUniqueness();
+
+if (ancestorUniqueness < 0.2) {
+  console.log('Recent ancestry is collapsing into a narrow family band.');
+}
+```
+
+Practical reading order:
+
+1. Start with `buildAnc()` if you want direct evidence for one genome.
+2. Continue to `computeAncestorUniqueness()` if you want the controller-level
+   summary that can feed telemetry or adaptive policy.
+3. Finish in `core/` if you want the exact traversal, pair sampling, and set
+   distance mechanics.
 
 ## neat/lineage/lineage.ts
 

package/src/neat/lineage/lineage.ts

@@ -25,33 +25,135 @@ export type { GenomeLike, NeatLineageContext } from './core/lineage.types';
  * still exploring multiple lineages or quietly collapsing onto descendants of a
  * small ancestor set.
  *
- * The root chapter keeps two public read models together:
+ * In evolutionary systems, structural variety can be misleading on its own.
+ * Two genomes can look different because they drifted locally through weight
+ * updates or a few recent mutations while still descending from the same narrow
+ * branch. Lineage reads add the missing genealogical context. They let the
+ * controller ask whether today's population still contains multiple recent
+ * family stories or whether most of the search budget is now being spent on one
+ * ancestor neighborhood wearing several slightly different topologies.
  *
- * - `buildAnc()` builds one genome's shallow ancestor set.
- * - `computeAncestorUniqueness()` turns many shallow ancestor sets into one
- *   sampled population signal.
+ * That distinction is useful because NEAT already has several other lenses on
+ * search health. Compatibility distance explains structural disagreement.
+ * Novelty explains behavioral difference. Score trends explain whether the
+ * current search path is paying off. Lineage contributes a separate clue: how
+ * much of the population's recent history is shared. If compatibility says
+ * genomes are spread out but lineage says they still share recent parents, the
+ * run may be exploring one branch in detail rather than keeping multiple
+ * evolutionary bets alive.
  *
- * Read the chapter in this order:
+ * The core algorithmic idea is intentionally simple. `buildAnc()` performs a
+ * bounded breadth-first walk over parent ids so it can recover a shallow family
+ * neighborhood for one genome. `computeAncestorUniqueness()` then samples genome
+ * pairs and compares those shallow ancestor sets with a Jaccard-style distance.
+ * The result is not a full phylogenetic tree or a museum-grade genealogy. It is
+ * a lightweight controller signal designed to stay cheap enough for runtime
+ * telemetry while still capturing whether the population's recent ancestry is
+ * broad or collapsing.
  *
- * - `buildAnc()` when you want the raw ancestry evidence for one genome.
- * - `computeAncestorUniqueness()` when you want the controller-facing summary
- *   used by telemetry, diagnostics, or adaptive lineage pressure.
- * - `core/` when you need the breadth-first traversal, pair sampling, or
- *   Jaccard-distance mechanics behind the public helpers.
+ * Read this chapter with two silent reader questions in mind. First: what kind
+ * of historical evidence is lineage actually measuring? Second: why stop at a
+ * shallow ancestry window instead of walking every parent back to the origin?
+ * The answer to the first is recent overlap in parentage, not lifetime
+ * similarity. The answer to the second is that controller telemetry needs the
+ * ancestry evidence that is most actionable now. Shallow ancestry is usually a
+ * better indicator of current branch collapse, takeover, or recent divergence
+ * than an unbounded tree that keeps every distant common ancestor equally loud.
+ *
+ * One useful mental model is to treat lineage as the population's memory of
+ * "who recently came from whom." It does not replace structural or behavioral
+ * metrics. It complements them. A run with strong scores and low lineage
+ * uniqueness may be exploiting aggressively around one family. A run with high
+ * lineage uniqueness and weak scores may still be exploring many recent
+ * branches without yet consolidating progress. Seeing those regimes explicitly
+ * helps the rest of the telemetry and adaptation stack read less like a pile of
+ * unrelated numbers.
  *
  * ```mermaid
  * flowchart TD
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
  *   Genome[Genome with parent ids] --> Ancestors[Shallow ancestor set]
  *   Population[Population genomes] --> Pairs[Sample genome pairs]
  *   Ancestors --> Distance[Compare ancestor overlap]
  *   Pairs --> Distance
  *   Distance --> Uniqueness[Ancestor uniqueness summary]
  *   Uniqueness --> Consumers[Telemetry diagnostics and adaptive lineage policy]
+ *
+ *   class Genome,Ancestors,Population,Pairs,Distance,Consumers base;
+ *   class Uniqueness accent;
+ * ```
+ *
+ * A second view places lineage beside the other common NEAT health signals so
+ * a first-time reader can see what question each metric family is really
+ * answering.
+ *
+ * ```mermaid
+ * flowchart LR
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Population[Current population]:::base --> Compat[Compatibility distance<br/>How structurally different?]:::base
+ *   Population --> Novelty[Behavioral novelty<br/>How behaviorally different?]:::base
+ *   Population --> Fitness[Fitness trend<br/>How well is the run scoring?]:::base
+ *   Population --> Lineage[Lineage uniqueness<br/>How many recent families remain?]:::accent
+ * ```
+ *
+ * A third view explains why the implementation stops after a bounded ancestry
+ * window instead of treating lineage as a full archive query.
+ *
+ * ```mermaid
+ * flowchart TD
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   FullTree[Walk every ancestor forever]:::base --> Expensive[Expensive and historically noisy]:::base
+ *   Window[Walk only a shallow recent window]:::accent --> Actionable[Cheaper and better aligned to current takeover risk]:::base
+ *   Expensive --> Telemetry[Harder to reuse inside runtime telemetry]:::base
+ *   Actionable --> Telemetry
+ * ```
+ *
+ * The root chapter therefore stays small in API surface but rich in meaning.
+ * `core/` owns the queue mechanics, sampled pair generation, and distance
+ * aggregation so this file can stay focused on what the ancestry reads mean at
+ * the controller surface. That separation is deliberate: the public question is
+ * not "how does the queue advance?" but "what kind of evidence does lineage add
+ * that the rest of the controller does not already have?"
+ *
+ * For background reading, the most relevant mathematical and traversal ideas
+ * are the breadth-first search used for the shallow family walk and the Jaccard
+ * index used to compare ancestor-set overlap. See Wikipedia contributors,
+ * [Breadth-first search](https://en.wikipedia.org/wiki/Breadth-first_search),
+ * and Wikipedia contributors,
+ * [Jaccard index](https://en.wikipedia.org/wiki/Jaccard_index), for compact
+ * background on the two ideas this chapter adapts into a runtime NEAT signal.
+ *
+ * Example: inspect the recent family neighborhood behind one genome.
+ *
+ * ```ts
+ * const ancestorIds = neat.buildAnc(neat.population[0]);
+ *
+ * console.log([...ancestorIds].toSorted((leftId, rightId) => leftId - rightId));
+ * ```
+ *
+ * Example: watch whether the run is collapsing onto a narrow recent lineage.
+ *
+ * ```ts
+ * const ancestorUniqueness = neat.computeAncestorUniqueness();
+ *
+ * if (ancestorUniqueness < 0.2) {
+ *   console.log('Recent ancestry is collapsing into a narrow family band.');
+ * }
  * ```
  *
- * The root chapter stays compact on purpose. `core/` owns the queue mechanics,
- * sampled pair generation, and distance aggregation so this file can stay
- * focused on what the ancestry reads mean at the controller surface.
+ * Practical reading order:
+ *
+ * 1. Start with `buildAnc()` if you want direct evidence for one genome.
+ * 2. Continue to `computeAncestorUniqueness()` if you want the controller-level
+ *    summary that can feed telemetry or adaptive policy.
+ * 3. Finish in `core/` if you want the exact traversal, pair sampling, and set
+ *    distance mechanics.
  */
 
 /**