CodonTrace Genesis

A world small enough to replay, and a claim strict enough to refuse itself.
Research software. Not a proof of intelligence, and not a biological result.

CodonTrace Genesis is a laboratory you can run twice and get the same world back.

You set down a small place. Simple agents eat, survive, and reproduce. The energy of each birth comes out of the parent. The questions are evolutionary: does an antagonist push a lineage somewhere new, does a costly behavior hold its ground, does a line recover after its path is cut. The library exists so those questions can be asked without the answer being talked into shape afterwards. A birth names its parent. A checkpoint is the moment it was taken, not whatever the run became later. A number is stored beside the only scope it is allowed to have.

The aim is not to announce a Red Queen, an open-ended mind, or a medical device. The aim is a digital-evolution engine whose ledgers, forks, and verdicts stay weaker than the temptation to overclaim them. Four words are allowed at the end of a test, and only one of them is support, and only inside the model that was actually run: SUPPORTED_IN_MODEL, FALSIFIED_IN_MODEL, INCONCLUSIVE, BLOCKED_MEASUREMENT. On the 29 September 2026 ledger, the Red Queen is not proved. That ledger is the record of that program. It is not a permanent verdict for every later experiment.

Domain modules sit beside that life-loop. They do not replace it. The installable package is codontrace. Product naming for contributors lives in CONTRIBUTING.md and STYLE.md.

Local scientific tools

The local console has read-only scientific tools for recorded trajectories, seed comparisons, time-shift matrices, Price terms, mathematical output and reproduction code. Analysis is available for paused, stopped, failed and completed runs as well as live runs. A compatible local LLM can call these tools; charts and calculations run on the host. Inspecting other projects or board processes requires an explicit request.

T01–T05 are standalone REFERENCE pilots, not Genesis VM experiments. T11 has an ENGINE calibration route. Unimplemented adapters remain disabled. Recorded scientific support is accepted within its validated protocol and model; historic ledger flags are not universal conclusions about later runs.

Every run has its own card, counters, metrics, controls and chat thread. Pause/resume wait for worker acknowledgement. Restart (or play after stop/failure) creates a fresh run with the original parameters and preserves prior data; removing a run requires stopping it first. Default charts use that run alone; seed comparisons are explicit.

See implementation, scientific scope and local acceptance checks.

How to read a result

A number in this repository is not a conclusion. A standing verdict is one of four words, and only one of them may be attached to a test:

SUPPORTED_IN_MODEL · FALSIFIED_IN_MODEL · INCONCLUSIVE · BLOCKED_MEASUREMENT

The record of the 29 September 2026 program is docs/experiments/2026-09-29/VERDICT_LEDGER_V1.json. On that ledger hypothesis_supported is false and red_queen_proved is false. Those two flags belong to that ledger. A later experiment reports its own verdict. The confirmatory campaign of that ledger is not open. A green workflow is not a scientific result: the lint and typecheck job is continue-on-error, so a green run is not a mypy pass.

Van Valen’s Red Queen (1973) is the biological hypothesis these records are about. None of them establishes it, in the model or outside it. Open-ended intelligence and a Tokyo Type 1 pass (Channon 2024) stay blocked. Measurement of a trajectory is not a pass.

Figure style

Figures in this file use one palette. A later diagram should reuse these parameters rather than invent a second visual language.

%%{init: {'theme':'base','themeVariables': {'primaryColor':'#e7eef8','primaryTextColor':'#142033','primaryBorderColor':'#1f4e79','lineColor':'#1f4e79','secondaryColor':'#f3efe6','tertiaryColor':'#f7f5f0','fontFamily':'ui-sans-serif, system-ui, sans-serif','fontSize':'15px'}}}%%
flowchart LR
  world["World tick<br/>eat, survive, reproduce"] --> ledger["Ledgers<br/>energy, contact, birth, death"]
  ledger --> freeze["Checkpoint<br/>frozen at capture"]
  freeze --> digest["Digest<br/>recomputed on read"]
  digest --> gate["Claim gate<br/>scope written beside the number"]
  gate --> verdict["One standing verdict"]

The path above is an engineering path. Reaching the last box does not promote the run.

%%{init: {'theme':'base','themeVariables': {'primaryColor':'#e7eef8','primaryTextColor':'#142033','primaryBorderColor':'#1f4e79','lineColor':'#1f4e79','secondaryColor':'#f3efe6','tertiaryColor':'#f4e4dc','fontFamily':'ui-sans-serif, system-ui, sans-serif','fontSize':'15px'}}}%%
flowchart TB
  unit["One unit<br/>history, seed, run, intervention"] --> interval["Student-t interval<br/>defined, and not covering zero"]
  interval --> floor["At least 16 independent units<br/>the ClaimGate seed floor"]
  floor --> isolated["Isolation verified<br/>settings differ only on the target factor"]
  isolated --> allowed["Eligible to be discussed as in-model support"]
  allowed --> blocked["Still blocked<br/>AGI, consciousness, Tokyo Type 1 pass,<br/>biological Red Queen proved"]
  classBlocked["A checkpoint of the same unit"] -.-> unit
  slopeBlocked["A non-zero slope, with no own-lag baseline"] -.-> blocked

Hurlbert (1984) is the reason a checkpoint is not a second replicate. Granger (1969) is the reason a slope is not a predictive gain: the comparison is a restricted regression on the target’s own lag against an unrestricted regression that also includes the source. This library reports the fractional drop in residual sum of squares. It does not report an F test, and an empty control list leaves the result a confounded_candidate.

What the current model refuses to mix up

These are contracts of the software. They are not findings about organisms.

The historical estimators stay in the tree so an old number can be reproduced and then not reused as the corrected estimand. A locked WAVE classifier that still reads pass_prelim does not set red_queen_proved.

What it is

• A Python research library for controlled digital-evolution and artificial-life experiments.
• A replay and audit layer: specs, runtime digests, manifests.
• Mechanism instrumentation: ablations, treatment and control, delayed outcomes.
• A claim-gated workflow. A software capability and a runtime observation are allowed. A strong scientific conclusion is not auto-promoted.
• One biomedical port and one hardware arm on that same auditor. Further modules attach without a second engine.

What it is not

CodonTrace Genesis is not currently presented as:

• proof of artificial general intelligence, consciousness, or collective intelligence
• proof of open-ended intelligence, or a Tokyo Type 1 pass (Channon 2024)
• a biological evolution simulator or a wet-lab chemistry engine
• a replacement for Avida (Ofria and Wilke 2004), MABE, DEAP, QDax, or pyribs
• a physical-robot platform (SimEsp32Bridge is an engineering stub)
• a medical device, SaMD, IVD, FDA or CE clearance, or an ASME V&V 40 certification
• an Avida or MABE campaign runner (those ClaimGate adapters stay skeletons until audited published tables exist)

Claims have to pass evidence gates. See CLAIMS.md and docs/WHY_NOT_INTELLIGENCE_YET.md.

Status

Phases A–L

Phases A–G are the earlier 0.3.0b3 substrate. Phases H–L, HE01 SCHEMA v7, and the discovery ClaimGate pipeline shipped in public 0.3.0b4.

Still blocked: bare collective_intelligence, intelligence, AGI, tokyo_type1_passed, and Avida replacement. Smoke never sets ClaimGate flags. Digests are never invented.

Installation

Python 3.11–3.14. CI smokes Ubuntu, Windows, and macOS on that range. The PyPI wheel is codontrace==0.3.0b30, built from the v0.3.0b30 release. An editable install of main prints the git identity from pyproject.toml.

pip install codontrace==0.3.0b30

pip install "codontrace[research]==0.3.0b30"
pip install "codontrace[causal]==0.3.0b30"
pip install "codontrace[qd]==0.3.0b30"
pip install "codontrace[swarm]==0.3.0b30"   # MQTT 5 bridge (paho-mqtt)

From source, which may be ahead of PyPI:

git clone https://github.com/Parvaz-Jamei/codontrace-genesis.git
cd codontrace-genesis
python -m pip install -e ".[dev,research,causal,qd]"
python -c "import codontrace; print(codontrace.__version__)"

Do not treat the version tuple as a phase fence, and do not tag or publish from a red or queued CI.

Quick start

The beginner API returns the agent, the world, the trace, and an optional explanation.

from codontrace import WhiteBoxAgent, World2D

world = World2D.from_ascii("""
....
.A*.
....
""")

agent = WhiteBoxAgent.from_world(world, genome="101111000", initial_atp=5.0)
result = agent.run_trial(world, steps=3, explain=True)

print(result.agent.position)
print(result.explanation.summary if result.explanation else "no explanation")

A research run uses an explicit spec. Empty research defaults are not a life-loop: ResourceConfig.density=0 and a same-cell reproduction rule do not make a Darwinian substrate. Use the preset.

from codontrace.genesis import GenesisEngine, GenesisRuntimeProfile

spec = GenesisRuntimeProfile.life_loop_world(seed=7, tick_count=12, population=6)
result = GenesisEngine.from_spec(spec).run_ticks()
print(result.digest()[:24])

Opt-in presets (sexual recombination, fluctuating environments, multi-generation measurement, materials, and the H–L harnesses) stay off unless requested, so earlier digest pins remain stable. Print-only smokes live under examples/.

Console

The console process does not import the evolution engine and does not set red_queen_proved. A launch without a script name starts scripts/rq_full_engine_parallel.py as a child. Explicit T01–T05 launches use standalone REFERENCE runners; T11 uses the ENGINE calibration adapter. Backend labels are recorded in the manifest and never inferred into proof from a script name. A gate row is the catalog plus the latest preview in the browser, not a pytest pass. On startup, and again every 24 hours, it asks GitHub whether a newer release exists. That query does not push. A clean checkout of this repository can fast-forward; a wheel install is left as it is.

The same command works on Linux, Windows, and macOS after a normal install. No extra package and no Node process are required to open the page.

python -m codontrace.console

The bind defaults to 0.0.0.0 and port 8765. If 8765 is taken, the next ports are tried. --host, --port, and --open change the bind and can open a browser. Workers are an integer of at least 1. The default in a launch request is 2. The recommended count is the number of CPUs the process is allowed to use, not a fixed cap of 4. A requested core list is rejected unless every id is in that allowed set. A pause request stays PAUSING until the worker ack arrives; the request file alone is not a pause. A temperature is reported only when the machine exposes a sensor file. Windows does not have a load average, so that field stays unmeasured there.

The page source lives in console/. Rebuild it with Node only when the interface itself changes; the result is stored under src/codontrace/console/static and shipped inside the wheel. The server is codontrace.console and does not import engine.py.

Claim policy

ScientificClaimGate can allow collective_intelligence_candidate only when the full honest flag set is present, including replay. It does not allow bare collective_intelligence, intelligence, AGI, tokyo_type1_passed, or Avida replacement. Policy: CLAIMS.md. Ladder: docs/protocol/CLAIM_LADDER_PROTOCOL_v0.1.md.

Architecture

The product is the engine. It does not know medicine or hardware. A new module is a DomainProfile or an adapter. It is not a copy of the engine.

%%{init: {'theme':'base','themeVariables': {'primaryColor':'#e7eef8','primaryTextColor':'#142033','primaryBorderColor':'#1f4e79','lineColor':'#1f4e79','secondaryColor':'#f3efe6','tertiaryColor':'#f7f5f0','fontFamily':'ui-sans-serif, system-ui, sans-serif','fontSize':'15px'}}}%%
flowchart TB
  engine["GenesisEngine<br/>ticks, digest, replay"] --> bundle["claimgate_bundle_v1"]
  bundle --> audit["audit_bundle"]
  audit --> ladder["Ladder 0–5<br/>no forbidden alias"]
  bio["Biomedical DomainProfile<br/>declared evidence table"] --> audit
  hw["Hardware arm<br/>SimEsp32Bridge"] --> audit
  foreign["Avida .dat or MABE CSV<br/>read-only adapter"] --> audit

ALIFE is the default profile. BIOMEDICAL and HARDWARE are the two extra profiles that ship now. The biomedical port stores ASME V&V 40, FDA 2023, IEC 62304, and IMDRF wording as labels. It ranks a phenomena table and caps a coupled model at its weakest submodel. A study file closes a phenomenon only when that arm was executed. A typed rank does not. Declared model risk has its own bar. The bar does not move the claim ladder. Strings such as asme_vv40_passed, fda_cleared, and samd_certified raise ConfigurationError. This is not SaMD.

from codontrace.claimgate import audit_bundle
from codontrace.claimgate.adapters.codontrace import bundle_from_hard_experiment_01

report = audit_bundle(bundle_from_hard_experiment_01())
print(report.achieved_level, report.public_name, report.missing_for_next)

from codontrace.claimgate import audit_bundle
from codontrace.claimgate.adapters.biomedical import bundle_from_device_model_cou

bundle = bundle_from_device_model_cou(
    question_of_interest="Would this score table support the claim?",
    context_of_use="Declared table only; no implant.",
    model_influence=2,
    decision_consequence=3,
    treatment_scores=(0.12, 0.11, 0.13),
    control_scores=(0.20, 0.19, 0.21),
    device_software_kind="simd_declared",
    iec_62304_class="B",
    imdrf_n12_category="II",
    fda_2023_evidence=(1, 3, 8),
    physics_based=True,
)
print(audit_bundle(bundle).achieved_level, bundle.extra["domain"], bundle.extra["model_risk"])

The second call stays on the biomedical port. It does not start the engine. Map: docs/ARCHITECTURE_PORTS.md. Biomedical scope: docs/BIOMEDICAL_ENGINEERING.md. Replay contract: docs/ENGINE_REPLAY_CONTRACT.md.

Documentation

The benchmark smoke is a functionality check. It is not evidence of collective intelligence.

python -m pytest tests/examples/test_collective_joss_evidence_benchmark_smoke.py -q

Orange Pi Zero 3 long program

The program is docs/campaigns/orange_pi_zero3_long_program.md. It is a design and an acceptance spec. It has not been executed as a campaign, and no board rate has been measured. Implemented T01–T05 REFERENCE pilots, T11 ENGINE calibration, and remaining adapter gaps are documented in docs/campaigns/T01_T12_READINESS.md.

Testing

python -m compileall -q src tests examples tools
python -m pytest tests/genesis_gates -q
python -m pytest tests/science_gates -q
python -m pytest tests -q

These are broader suites; passing a focused patch suite does not imply that every repository test was run. The current CI workflow defines its required gates. Tiers: REPRODUCIBILITY.md.

Citation

Cite the versioned software release. The DOI is the software archive, not a campaign archive.

@software{codontrace_genesis_2026,
  title = {CodonTrace Genesis},
  author = {Jamei, Parvaz},
  version = {0.3.0b30},
  doi = {10.5281/zenodo.20337435},
  url = {https://github.com/Parvaz-Jamei/codontrace-genesis},
  note = {0.3.0b30 is the git identity, the GitHub release v0.3.0b30 and the PyPI wheel 0.3.0b30. Already published tags are not recut. The DOI is the software archive, not a campaign archive.}
}

CITATION.cff is included for citation tools. Use of the software does not imply co-authorship.

Works named above

These are the sources the contracts are answerable to. Naming them is not a claim that this repository has reproduced them.

• Granger, C. W. J. 1969. Investigating causal relations by econometric models and cross-spectral methods. Econometrica 37:424–438.
• Hurlbert, S. H. 1984. Pseudoreplication and the design of ecological field experiments. Ecological Monographs 54:187–211.
• Ofria, C., and C. O. Wilke. 2004. Avida: a software platform for research in computational evolutionary biology. Artificial Life 10:191–229.
• Student. 1908. The probable error of a mean. Biometrika 6:1–25.
• Van Valen, L. 1973. A new evolutionary law. Evolutionary Theory 1:1–30.

License

CodonTrace Genesis is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), so that modified, redistributed, and network-deployed versions stay inspectable.

Commercial or proprietary use that cannot comply with that license may contact the author for a separate license.

See LICENSE and NOTICE.

Author

Parvaz Jamei

GitHub: @Parvaz-Jamei

CodonTrace Genesis — replayable evidence for digital evolution. A run is not a verdict.

Scientific charts: two modes

As recorded displays the selected run with no user filters, smoothing or statistical transform. Bounded source reads and display downsampling are disclosed in provenance; this is not a full-file raw-data export. Configurable / LLM uses the same read-only scientific_plot tool and typed options for metric, seed range, generation range, exact arm, palette and axes. Available geometries: line, step, area, scatter, bubble, bar, histogram, ECDF, Tukey box, Gaussian KDE density, violin, pairwise Pearson correlation heatmap and recorded error bars. Existing measured time-shift and confusion-matrix tools remain available.

Charts have SVG/PNG export, displayed-data tables, JSON with provenance, labels and line dash patterns. No arbitrary model code runs. Invalid log coordinates, absent paired measurements and fabricated intervals are rejected. KDE bandwidth and pair counts are recorded; repeated generations are not independent replicates.

OpenAI / GPT and DeepSeek

Settings → Cloud models supports official OpenAI and DeepSeek APIs alongside the existing local analyst, local server and GGUF choices. Save a key or set OPENAI_API_KEY / DEEPSEEK_API_KEY on the server, then discover/refresh account model IDs. Namespaced model choices route authenticated requests to the matching provider, including scientific tools. API errors remain explicit; they are not silently presented as local-model answers.

Keys never enter model messages, browser storage or returned catalogs. Saved keys live in the server configuration file with mode 0600 on POSIX; environment keys take precedence. For remote configuration use CODONTRACE_SETTINGS_TOKEN or a local SSH tunnel. Remote chat/scientific tools also require CODONTRACE_API_TOKEN, entered separately in Settings; without it these operations accept only direct loopback clients. Use HTTPS or SSH for credential transport. Local model timeout remains 1800 seconds by default. Selecting a cloud model sends message/selected-run context to that provider and uses account API credits. Actual paid-account compatibility must be verified locally; model listing does not prove endpoint/tool support.

Optional Wi-Fi sensor swarm

Board-neutral telemetry, host-side processing policies, bounded cooperative sensing and a standalone dashboard. See setup and API, research plan and sources. Firmware remains outside Genesis. Synthetic probes are engineering checks, not physical discoveries.

Simulation Atlas

A React isometric generation viewer with seed selection, layer playback, explicit lifecycle records and SVG image-sequence export. Recording and panel guide.

Swarm decision support (V4)

Bounded split-residual calibration, freshness-aware advisory scheduling over actual node snapshots, and paired capsule shadow comparison are available through the authenticated Swarm API. The LLM can read saved per-seed decision reports without device commands. See research assumptions, examples and five-phase evaluation. These components do not assert conformal coverage under arbitrary time dependence, optimal scheduling, SPIBB safety, or physical rollback without an acknowledgement.

Swarm V5 adds backward-compatible typed sensor observations, explicit host normalization, an FDCxCapSense reading adapter, hash-chained journal segments and explicit recovery. Receipt/visualization support is distinct from scalar processing support. See the V5 audit for tested behavior and remaining hardware/performance limits.

Swarm journals write a hashed state checkpoint at every segment rotation. Startup restores the newest checkpoint verified against the current journal (its segment must be live and its chain must match that segment's final record), hash-checks the covered live segments without re-applying them, and replays only later records. Without a usable checkpoint it replays the whole chain automatically, including events.jsonl.archive/, which also verifies the archive-to-live link; journal_recover (optionally full_replay: true) works even when normal opening fails. journal_retention_bytes moves covered segments to the archive (data is kept; archive_max_bytes is the only setting that deletes archived segments); checkpoint and retention problems are reported as checkpoint_health and retention_health and never block journal writes. Integrity scope: the SHA-256 chain is unkeyed, so it detects corruption and accidental edits, not a deliberate rewrite by someone with write access. Startup checks every live record; archived segments are checked only by full replay. Removing trailing records or the whole active file leaves a consistent shorter history and is not detected without an external anchor (for example, copying journal_digest elsewhere). Writers in other processes are serialized by a lock file with a bounded wait (lock_timeout_s, default 2 s); a coordinator instance that is behind another writer refuses to write ("journal changed externally") until journal_recover reloads it. The service keeps at most 32 coordinators in memory and evicts idle ones least-recently-used first; service.coordinator() pins the instance it returns (the MQTT bridge uses it, so bridge and console share one instance) until service.release(). A swarm whose recorded history cannot be loaded answers every request except journal_recover with HTTP 409 {"ok": false, "error": "recovery_required"} and is never served from placeholder state. The MQTT bridge always acknowledges telemetry, because MQTT 5 brokers resend an unacknowledged message only after a reconnect to a persistent session, never on the same connection, and unacknowledged messages would fill the broker's in-flight window. Journaled readings count as journaled; duplicate or reordered sequence numbers are acknowledged, counted as duplicates and not journaled; invalid messages count as rejected. On a journal error the bridge retries briefly; if that fails the reading is acknowledged and recorded as lost (lost counter and a bounded recent_losses list with node, boot and sequence, no values) and bridge.health() reports degraded until the next successful write. connect(session_expiry_s=..., client_id=...) optionally requests a persistent broker session so readings published while the bridge is offline are queued by the broker. Read-only Swarm actions on an unknown swarm id answer from empty state without creating folders or lock files.