Lexicon

• Cymatix has two vocabularies. The canonical one is standard software terminology — document, knowledge store, compressor, fragment, lifecycle tier. The other is the molecular-biology metaphor the project was built under — gene, genome, ribosome, codon, chromatin.
• This page is the bidirectional dictionary. Scan the legacy column to read older code, handoffs, and receipts; scan the canonical column when writing anything new.
• Both names work in Python. The canonical names are the real class definitions since R3; the biology names are one-line aliases declared beside them. Document is Gene is True in both directions, with no subclassing and no runtime cost.
• The wire and the SQL schema are still legacy-named on purpose. JSON keys such as gene_id, the <GENE src=…> blocks inside an assembled window, and every SQL table name are contracts with existing consumers. Renaming them changes delivered bytes, so it is gated separately — see below.
• In-repo, docs/ROSETTA.md is now a stub that points here. This page is the living document; add a row when a new term surfaces.

Where the vocabulary came from

• The original architecture was designed around a molecular-biology metaphor, and the metaphor did real work: a gene as the atomic unit of stored knowledge, a genome as the persistent store, a ribosome that reads raw text and emits a compressed unit, chromatin as the hot/warm/cold accessibility state, splicing as the act of dropping low-value fragments. The shape of the pipeline follows from that framing, not the other way round.
• The intellectual backstory is Agentome, a paper by this project's author that set out the biology framing before the engine existed. It is the reason the early code reads the way it does, and it is worth reading if you want the "why these names" answer rather than the "what do they mean" answer this page gives.
• The metaphor also imposes a cognitive tax. Every reader — human or LLM — has to hold two mental models in parallel, and the second one is not the one they arrived with. For a project whose design target is an agent reading its own documentation, that tax is paid on every turn.
• So the canonical lexicon moved to software terms, in waves, additively — never by deleting the old names. The phase table below records what shipped when.
• The helix → cymatix product rename is a different thing entirely. That was a change of product name (package helix_context → cymatix_context, HELIX_* → CYMATIX_*, helix.toml → cymatix.toml, CLI helix → cymatix), soft-renamed in 0.8.0 and completed as a clean break in 0.8.5 (2026-07-25): no alias package, no helix* console scripts, no helix_* MCP tools, no env mirror, no config fallback. It says nothing about biology-versus-software terms, and the mapping table below is unchanged by it. Historical docs — benchmarks, council verdicts, dated plans — keep the helix vocabulary deliberately; they are point-in-time records.

Mapping table

Identity vocabulary

The biology metaphor is not the only translation this project needs. The identity layer has near-synonyms in active use across design notes and handoffs. The canonical schema terms — org, party, participant, agent — stay; this table pins their intended meanings.

This is a reading layer, not a rename directive. New prose should prefer the canonical schema name while making the meaning explicit inline — "party (device)", "agent (software actor)".

Response and routing types (no biology twin)

These types travel on the wire between cymatix and its callers. They are response envelope vocabulary, not storage vocabulary — no metaphor applies, and they keep their engineering names everywhere.

Contract semantics for know / miss and the packet labels live on Agent Contract; the field-by-field JSON is on HTTP API.

Metric and label names are a contract

• Prometheus metric names and label values are queried by Grafana panels, alert rules, and ad-hoc PromQL. The same "don't rename what is already a contract" logic that freezes the SQL schema applies to them: cymatix does not rename metrics. cymatix_chromatin_state_total, cymatix_harmonic_edges_total, cymatix_ribosome_call_seconds, cymatix_genome_size_genes and the rest keep their names permanently.
• Dashboard panel titles do use the engineering vocabulary, with the legacy term referenced inline so panel-hunting stays one step ("Compressor call latency p95 by operation", description "Legacy term: ribosome call").
• The full metric-name-to-meaning table, the panel-title index, and the OTel gen_ai.* attribute namespace are on Observability — that page is the single home for the metric surface, so it is not duplicated here.

Terms that stay

Domain-specific technical terms with established meaning outside biology. Renaming them would lose precision or trade a small cognitive cost for a bigger one.

• SEMA — semantic embedding alignment. Cymatix-coined, not biological.
• TCM — Temporal Context Model (Howard & Kahana, 2002). An established psychology-literature acronym.
• cymatics — vibrational pattern math; scoring/cymatics.py references physics, not biology. (What the stage actually does, and the honesty caveat about it, is on Retrieval Dimensions.)
• SPLADE — Sparse Lexical AnD Expansion model, from the IR community.
• CWoLa — Classification Without Labels, from weakly-supervised learning.
• ellipticity and denatured — CD-spectroscopy and physics terms that happen to sit next to the biology ones. Not renamed.
• ScoreRift — proper noun for the audit subsystem.
• PWPC — proper noun for a joint experiment.
• cymatix itself — the product name.

What is still legacy-named, and why

Two surfaces were deliberately left alone. Both are contracts with something outside the repository.

The wire surface — tracked as #417, not taken in 0.9.1:

• The <GENE src=…> blocks that wrap each spliced fragment in an assembled context window.
• The [gene= legibility headers emitted during assembly.
• Decoder prompt text that names gene / genome / chromatin when instructing the compressor model.
• JSON keys returned over HTTP, CLI, and MCP — expressed_gene_ids, gene_id_match, do_not_answer_from_genome, gene_id.
• /stats response keys — open / euchromatin / heterochromatin.

Renaming any of these changes delivered bytes, not just a label. The closest precedent is the 0.9.0 neutralize_control_tags flip, which touched a narrow literal-string case and was still gated on a 141/141 byte-identical-window receipt. A wire rename is a strictly larger surface, so it needs its own byte-level A/B gate at full-scale — v1.0-scale work, not a patch release.

The SQL schema — frozen, and never part of any tier of this migration. Tables and columns (genes, codons, gene_attribution, harmonic_links, chromatin_state) stay as they are. Renaming would force a migration on every existing store, and the cognitive tax at the SQL layer is paid by comparatively few readers. The default store file on disk is likewise still genomes/main/genome.db, and code blocks across this wiki reproduce it verbatim rather than faking a rename the code does not have.

Rename phases

R4 sat deferred (#87) from May 2026 through the 0.9.1 cycle. It ships as the Tier 2 half of the 0.9.1 lexicon pass; the three tiers are:

• Tier 1 — documentation prose. Repo docs use software terms; dated records keep their original vocabulary untouched.
• Tier 2 — additive aliases on every operator-facing surface. Shipped in 0.9.1 via #419; listed below.
• Tier 3 — the wire surface. Deferred to #417.

The Tier 2 aliases

Every legacy spelling keeps working, unchanged. Nothing is deprecated in the sense of "will stop working".

Collision rule: the legacy name wins, and a WARNING names both. If a config carries both [compressor] and [ribosome], the [ribosome] block is the one that binds. The rule is deliberately conservative — an operator with both spellings in play gets the behavior their existing file already had, not a silent change.

The CLI is the one exception. --max-docs and --max-genes share an argparse destination, so passing both is plain last-wins, not legacy-wins.

Using the canonical names

# One import point for the canonical surface.
from cymatix_context.aliases import (
    Document, KnowledgeStore, Compressor,
    DocumentTags, DocumentSignals, LifecycleTier, DocumentAttribution,
)

# The legacy names are aliases of the same objects. Identity holds both ways.
from cymatix_context.schemas import Gene, PromoterTags
assert Document is Gene
assert DocumentTags is PromoterTags
assert Document.__name__ == "Document"   # canonical is the real class

cymatix document get <id> --json     # canonical
cymatix gene get <id> --json         # legacy alias, identical output

cymatix_document_get(document_id)    # canonical MCP tool
cymatix_gene_get(gene_id)            # legacy alias, same behavior

Pydantic field names (gene_id, promoter, epigenetics, chromatin, codons) and the SQL contracts are unchanged by any of the above.

Go deeper

• cymatix_context/aliases.py — the single canonical import point, plus the _RENAME_LOG provenance table
• cymatix_context/schemas.py — where the canonical classes and their one-line legacy aliases are declared side by side
• docs/ROSETTA.md — the in-repo stub that points here
• Agentome — the paper the biology framing came from
• #417 — the Tier 3 wire-surface remainder, with the gate it has to clear
• Next: Configuration · Observability · Architecture Map · Roadmap and Releases