Table of Contents

Struct CacheHeader

Namespace
Typhon.Profiler
Assembly
Typhon.Profiler.dll

Fixed 128-byte header at the start of a .typhon-trace-cache file. Contains the source-file fingerprint (for invalidation), format versioning, and a pointer to the section table.

public struct CacheHeader
Inherited Members

Fields

ChunkerVersion

Version tag for the chunker / fold policy. Bump whenever TickCap, ByteCap, or the async-completion fold logic changes in a way that makes old caches incorrect. Readers that see a different ChunkerVersion treat the cache as stale and rebuild.

public ushort ChunkerVersion

Field Value

ushort

CreatedUtcTicks

UTC timestamp when this cache was built (DateTime.UtcNow.Ticks). Informational; not used for invalidation.

public long CreatedUtcTicks

Field Value

long

CurrentVersion

Current cache format version written by this build. Matches the expected Version on read.

public const ushort CurrentVersion = 1

Field Value

ushort

Flags

Flag bits. See CacheHeaderFlags. Bit 0 (IsSelfContained) marks a cache that doesn't need a sibling .typhon-trace source — its metadata tables (header / systems / archetypes / component types) are carried inside the SourceMetadata section. Live-attach session saves write self-contained caches; readers that see the flag skip the source-file open and project metadata from the embedded bytes. Bits 1-15: reserved (must write 0; readers ignore unknown bits).

public ushort Flags

Field Value

ushort

Magic

File magic: ASCII "TPCH" (0x48_43_50_54 little-endian).

public uint Magic

Field Value

uint

MagicValue

File magic constant: ASCII "TPCH" (little-endian).

public const uint MagicValue = 1212371028

Field Value

uint

Reserved

Padding to 128 bytes. Zero-initialized; readers must ignore.

public byte* Reserved

Field Value

byte*

SectionTableLength

Length in bytes of the section table (== SectionTableEntry.SizeInBytes × entry count).

public long SectionTableLength

Field Value

long

SectionTableOffset

Offset (in bytes from the start of the cache file) of the section table.

public long SectionTableOffset

Field Value

long

SourceFingerprint

32-byte identifier for invalidation / cache identity:

  • Source-derived caches (default): SHA-256 of (source mtime-ticks + source length + first 4 KB + last 4 KB). If the source file changes meaningfully, the fingerprint mismatches and the cache is discarded on next open. Cheap (~1 ms) and collision-resistant.
  • Self-contained caches (IsSelfContained set): no source file exists. The 32 bytes carry an arbitrary session-derived identifier (e.g. session GUID + zero-padding); readers must NOT treat the value as a file fingerprint.
public byte* SourceFingerprint

Field Value

byte*

SourceFingerprintOffset

Byte offset of SourceFingerprint from the start of the struct. Single source of truth for callers that need to patch the field via a span (e.g. the trailer-write path which constructs the header by value and copies the identifier in via MemoryMarshal). Computed from the field declaration order: Magic (4) + Version (2) + Flags (2) = 8.

public const int SourceFingerprintOffset = 8

Field Value

int

SourceVersion

Copy of the source file's Version. If the source format revs, caches built against the old format are automatically invalidated without relying on fingerprint alone.

public ushort SourceVersion

Field Value

ushort

Version

Cache format version. Current: 1. Bump on breaking layout changes.

public ushort Version

Field Value

ushort

Methods

SetIdentifier(ref CacheHeader, ReadOnlySpan<byte>)

Copy the 32-byte identifier into the SourceFingerprint slot of header. Used by trailer-write paths that build the header by value: source-derived close (fingerprint of the source file) and self-contained save (arbitrary session-derived ID — readers must NOT treat the value as a hash; see SourceFingerprint doc).

public static void SetIdentifier(ref CacheHeader header, ReadOnlySpan<byte> identifier)

Parameters

header CacheHeader
identifier ReadOnlySpan<byte>