Class TraceArchetypeIdentity

Namespace

Typhon.Profiler

Assembly

Typhon.Profiler.dll

The single sanctioned way to resolve an archetype id read out of a trace. Built once from a trace's header + archetype table; every consumer that needs to know "which archetype is this?" goes through here rather than touching RoutingId or, worse, comparing raw ids.

public sealed class TraceArchetypeIdentity

Inheritance

object

TraceArchetypeIdentity

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

⚠️ Why this type exists. A trace carries archetype identity in two incompatible ushort spaces (see the remarks on ArchetypeRecord): the per-process catalog id in events and in this table, and the per-database routing id in the low 16 bits of every EntityId. Writing entityId & 0xFFFF == spawnEvent.ArchetypeId compiles, reads naturally, and is wrong for every archetype whose registration order differs from its persisted routing order — while being right in any freshly-created test database, where the two happen to coincide. Funnelling resolution through one type is what keeps that mistake from being re-invented in each new consumer.

Names are the safe join key; routing ids are the precise one. TryGetName(ushort, out string) always works. TryGetRoutingId(ushort, out ushort) deliberately fails closed — it returns false when the capture observed more than one live engine (MultipleEnginesObserved, design D-9), when the trace never knew the id, and when the archetype is simply not in the table. A caller that cannot get a routing id should fall back to a name join or omit the bridge entirely; it must never fall back to the catalog id.

Constructors

TraceArchetypeIdentity(in TraceFileHeader, IReadOnlyList<ArchetypeRecord>)

Builds the resolver from a trace's header and archetype table.

public TraceArchetypeIdentity(in TraceFileHeader header, IReadOnlyList<ArchetypeRecord> archetypes)

Parameters

header TraceFileHeader

The trace header — consulted for MultipleEnginesObserved.

archetypes IReadOnlyList<ArchetypeRecord>

The trace's archetype table, as returned by ReadArchetypes().

Exceptions

ArgumentNullException

archetypes is null.

Properties

RoutingIdsAvailable

false when this trace carries no usable routing ids at all — either it observed multiple engines (D-9) or it was written with no engine attached. Consumers can check this once to decide whether a routing-id-based bridge is offered at all, rather than probing per archetype.

public bool RoutingIdsAvailable { get; }

Property Value

bool

Methods

TryGetName(ushort, out string)

Resolves a trace catalog id to its archetype name — the drift-tolerant join key, and the one that always works. Returns false for an id the trace's archetype table does not describe.

public bool TryGetName(ushort catalogId, out string name)

Parameters

catalogId ushort

A catalog id as carried by trace events and ArchetypeId.

name string

Receives the archetype name, or null.

Returns

bool

TryGetRoutingId(ushort, out ushort)

Resolves a trace catalog id to the database's durable routing id — the identity embedded in every EntityId. Fails closed: returns false whenever the answer would be a guess, including the multi-engine case where the trace deliberately carries no routing ids at all (D-9).

public bool TryGetRoutingId(ushort catalogId, out ushort routingId)

Parameters

catalogId ushort

A catalog id as carried by trace events and ArchetypeId.

routingId ushort

Receives the routing id, or UnknownRoutingId.

Returns

bool