DNA

How a holon's identity is composed from chromosomes

A holon's DNA is its identity, expressed as an ordered sequence of chromosomes. Each chromosome captures one element of what the holon is or does—a value it holds, a tool it uses, a practice it observes. The DNA sequence is what makes a holon recognizable as itself: distinct from the holons around it, even when they share members or resources.

The @holons/core/dna domain provides the canonical model—the same chromosomes, sequences, and validation rules used by every interface in the Harvest monorepo.

Concepts

Chromosome

A single element of identity:

interface Chromosome {
  id: string;
  holonId: string;
  name: string;
  type: 'value' | 'tool' | 'practice';
  description: string;
  createdAt: number;
  updatedAt: number;
  icon?: string;
  color?: string;
}

Three types, by design:

Value — what the holon cares about (e.g. "regeneration", "transparency", "care").
Tool — what it uses (e.g. "Telegram", "sociocracy", "permaculture").
Practice — what it does regularly (e.g. "weekly check-in", "rotating stewardship", "consent-based decisions").

Each chromosome lives in the holon's ChromosomeLibrary—the set of available pieces. Not every chromosome in the library is part of the DNA; the DNA is a curated, ordered subset.

DNA Sequence

interface DNASequence {
  holonId: string;
  chromosomeIds: string[]; // Ordered, unique, max 20
  createdAt: number;
  updatedAt: number;
  version: number;
}

Constraints enforced by validation:

Ordered. Sequence order matters—earlier chromosomes are more defining.
Unique. No chromosome appears twice in a sequence.
Bounded. MAX_CHROMOSOMES_PER_DNA caps the sequence at 20.
Referentially valid. Every ID in the sequence must point to a real chromosome in the library.
Versioned. The sequence carries a version counter for optimistic concurrency.

Seed data

@holons/core/dna/seed-data ships default chromosomes so a new holon doesn't start from a blank slate:

defaultValues — common starting values
defaultTools — typical tools
defaultPractices — frequently useful practices
getAllDefaultChromosomes() / getDefaultChromosomesByType(type) — accessors

A newly created holon usually has its library seeded with these (seedChromosomeLibrary) and then evolves over time.

Operations

The public functions exported by @holons/core/dna:

Function

Purpose

getChromosomeLibrary(holonId)

Load the full library for a holon

getChromosome(holonId, id)

Read a single chromosome

addChromosome(holonId, chromosome)

Add a new chromosome to the library

updateChromosome(holonId, id, patch)

Modify an existing chromosome

removeChromosome(holonId, id)

Remove a chromosome (with sequence-reference checks)

getDNASequence(holonId)

Load the current DNA sequence

saveDNASequence(holonId, sequence)

Persist a new sequence (validated first)

seedChromosomeLibrary(holonId)

Initialize a library with defaults

subscribeToChromosomeLibrary(holonId, cb)

Live updates

subscribeToDNASequence(holonId, cb)

Live updates

And the pure validation helpers:

Function

Purpose

validateChromosome(chromosome)

Field-level validation

validateDNA(sequence, library)

Whole-sequence validation against a library

validateDNASequence(sequence)

Structural validation (ordering, uniqueness, bounds)

findDuplicates(sequence) / findInvalidReferences(sequence, library)

Diagnostics for validateDNA

createDNAError(type, message)

Construct a typed DNAValidationError

DNAValidationError distinguishes between duplicate, max_length, invalid_reference, and missing_required failures, so UIs can surface specific feedback rather than a generic "invalid."

Governance interplay

DNA changes are typically not made unilaterally. The common pattern:

A member opens a Council proposal: "Add chromosome consent-based decisions to our practices."
Members vote.
On agreement, the chromosome is added (addChromosome) and the sequence updated (saveDNASequence).

This binds DNA to the holon's governance: identity drifts only when the holon consents to it.

MCP tool surface

The MCP server exposes 12 tools in the dna domain — full chromosome and sequence management, validation, and library seeding. An AI agent connected via MCP can propose, validate, and (if its actor has standing) commit DNA changes directly.