Table of Contents

Class ArchetypeRecord

Namespace
Typhon.Profiler
Assembly
Typhon.Profiler.dll

Describes an archetype registered with the engine's ArchetypeRegistry. Stored in a table near the start of a .typhon-trace file so the viewer can map ArchetypeId numbers in typed events (EcsSpawn, ClusterMigration, etc.) back to human-readable names without the wire format having to carry strings for every event.

public sealed class ArchetypeRecord
Inheritance
ArchetypeRecord
Inherited Members

Remarks

⚠️ A trace carries two incompatible archetype id spaces, and nothing about their types distinguishes them. ArchetypeId here — and in every typed event — is the per-process catalog id: assigned in registration order, capped at 4095, and never persisted. The low 16 bits of every EntityId in the same file are the per-database routing id, which is persisted. Both are ushort.

Comparing them directly (entityId & 0xFFFF == spawnEvent.ArchetypeId, or joining a touch summary's archetype id against a routing id read from the database) yields a plausible answer that is wrong for every archetype whose registration order differs from its persisted routing order — and it looks correct in a freshly-created database, where the two coincide. That is a bug which passes every fixture and fails on real data.

RoutingId exists to close that gap: it is the bridge from the catalog id to the durable identity. Resolve through TraceArchetypeIdentity rather than reading it directly — it is the one place that honours MultipleEnginesObserved. See claude/design/Apps/Workbench/10-database-and-profiles.md §5.3 and D-3.

Constructors

ArchetypeRecord() 

public ArchetypeRecord()

Fields

UnknownRoutingId

Sentinel meaning "this trace does not know the routing id" — either no engine was attached, or D-9 degradation removed it.

public const ushort UnknownRoutingId = 65535

Field Value

ushort

Properties

ArchetypeId

Archetype ID — matches ArchetypeMetadata.ArchetypeId in the engine. Per-process, registration-ordered, never persisted.

public ushort ArchetypeId { get; init; }

Property Value

ushort

Name

Display name — typically the archetype class's Type.Name.

public string Name { get; init; }

Property Value

string

RoutingId

The archetype's durable per-database routing id (ArchetypeR1.RoutingId) — the identity that persists across runs and that every EntityId embeds. UnknownRoutingId when unavailable: no engine attached, the archetype is unmapped in this database, or the capture observed more than one live engine and the value was withheld at close rather than written ambiguously (D-9).

public ushort RoutingId { get; init; }

Property Value

ushort

Remarks

Written once per capture, in this table only. Events are deliberately left alone — hot paths, many event kinds, no benefit over the table.