kamal/source2rosetta
1
0
Fork 0
Code Issues Pull requests Projects Releases 55 Packages Wiki Activity Actions
source2rosetta/crates/source2rosetta-core/src/model.rs
Kamal Tufekcic 3410a79b6a
Some checks failed
CI / fuzz (push) Successful in 2m2s
Details
CI / lint (push) Successful in 15s
Details
CI / test (push) Failing after 18s
Details
ship one record per function: merge the release set, gen reads it, descriptions as doc comments, gates for what was only claimed; v3.0
2026-08-02 22:01:36 +03:00

2368 lines
113 KiB
Rust
Raw Blame History

//! The canonical derived-gamedata model — the single in-memory representation the derivation produces
//! and the emitters consume. Deliberately format-agnostic (no serde_json shapes here): `render::*`
//! turns it into CSSharp JSON, Metamod VDF, etc. Keeping the shape here (not smeared through `json!`
//! call sites) is what lets one derivation feed every output format and a standalone generator.
use std::collections::BTreeMap;
/// A byte-pattern signature located in a specific library.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Sig {
pub library: String, // "server", "engine2", … (the module the pattern scans)
pub linux: String, // space-hex pattern with `?` wildcards, e.g. "55 48 89 ? E5"
}
/// One gamedata function: a vtable-method offset, a scan signature, or (rarely) both — plus, where we
/// have them, string ANCHORS that locate the same function a different way.
#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Entry {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub signature: Option<Sig>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub offset: Option<i64>, // vtable slot index (or a carried member offset)
/// For a vtable-OFFSET locator: the class whose vtable the slot was measured on.
///
/// Part of the locator, not decoration — a slot index alone locates nothing, since it is only meaningful
/// relative to a particular class's vtable. Taken from the class whose vtable the derivation actually
/// chained the offset through, never parsed out of the entry name: a method declared on a base class
/// routinely sits in a derived class's vtable, so the name's class and the measured class are different
/// facts and only the second one locates anything.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub class: Option<String>,
/// Distinctive string literals this function references, each unique to it within its library.
///
/// NOT a third locator competing with the sig-XOR-offset pair — a supplement with a DIFFERENT failure
/// mode. A byte signature is a snapshot of one build's codegen; a string survives a recompile that
/// moves instructions. So a consumer that can resolve anchors (ModSharp's `refs.strings`) has a
/// locator that keeps working across the window between Valve shipping a build and us republishing,
/// which is exactly when a byte pattern is most likely to have drifted.
///
/// Emitted alongside the signature, never instead of it: the two are independent, and a consumer
/// choosing between them is better served by having both than by our picking one.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub anchors: Vec<String>,
}
impl Entry {
/// A signature-only locator (the deriver's sig-XOR-offset invariant as a constructor).
pub fn signature(library: impl Into<String>, linux: impl Into<String>) -> Entry {
Entry {
signature: Some(Sig {
library: library.into(),
linux: linux.into(),
}),
offset: None,
class: None,
anchors: Vec::new(),
}
}
/// A vtable-offset-only locator.
pub fn offset(linux: i64) -> Entry {
Entry {
signature: None,
offset: Some(linux),
class: None,
anchors: Vec::new(),
}
}
}
/// The default output game-key when none is set — CS2's Steam content-dir token. Games-keyed emitters
/// (Metamod/Plugify) fall back to this so an older model JSON (no `game_key`) still renders as CS2.
fn default_game_key() -> String {
"csgo".to_string()
}
/// The derived gamedata for one build: function name -> entry. BTreeMap so iteration/output is
/// deterministically key-sorted, matching serde_json's Map key ordering byte-for-byte.
///
/// Serializing this IS the canonical "model JSON" — the single per-build artifact the deriver
/// publishes and the standalone `source2rosetta-gen` reads back to produce every framework's format.
#[derive(Debug, serde::Serialize, serde::Deserialize)]
pub struct Gamedata {
pub entries: BTreeMap<String, Entry>,
/// The game token the game-keyed emitters wrap output in (Metamod `Games { <game_key> {..} }`,
/// Plugify `{ "<game_key>": {..} }`). Persisted here because `source2rosetta-gen` renders from the model
/// JSON alone, with no access to the deriver's `GameProfile`. Defaults to CS2's `csgo`.
#[serde(default = "default_game_key")]
pub game_key: String,
}
impl Default for Gamedata {
fn default() -> Self {
Self {
entries: BTreeMap::new(),
game_key: default_game_key(),
}
}
}
/// Why the derivation could not produce a shipped locator — the closed domain the `unresolved` tier reports.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum FlagReason {
/// A catalogued signature that no longer resolves uniquely / wasn't recovered in the target.
SigDrifted,
/// A vtable offset whose recency-weighted vote fell below the confidence bar.
OffsetLowConf,
/// No chainable anchor / no reference history at all.
Unresolved,
/// The sig SHIPPED, but its ABI prototype shape drifted from the model consensus (review the prototype).
AbiDrift,
/// A signature DID resolve, and the address it resolved to is provably a different function — the
/// binary names it something else and the code operates on another class. Distinct from `SigDrifted`
/// because it calls for the opposite response: a drifted entry may simply reappear next build, while
/// this one says the catalogue's own signature is finding a decoy and the entry needs a new locator.
NameContradicted,
}
impl FlagReason {
/// The kebab id — the same string the `kebab-case` serialization emits, for callers that carry the
/// reason across to the monolith's `Unresolved.reason` (a `String`, kept stable for byte-reproducibility).
pub fn as_str(self) -> &'static str {
match self {
FlagReason::SigDrifted => "sig-drifted",
FlagReason::OffsetLowConf => "offset-low-conf",
FlagReason::Unresolved => "unresolved",
FlagReason::AbiDrift => "abi-drift",
FlagReason::NameContradicted => "name-contradicted",
}
}
}
/// A catalogue entry the derivation could NOT confidently produce. Emitted as a first-class sidecar
/// (never guessed into the gamedata — safety > recall) so it is both reviewable and machine-readable.
#[derive(Debug, Clone, serde::Serialize)]
pub struct Flagged {
pub name: String,
pub reason: FlagReason,
/// The signal we do have: the carried value, vote confidence, "no reference", …
pub detail: String,
}
impl Flagged {
pub fn new(name: impl Into<String>, reason: FlagReason, detail: impl Into<String>) -> Self {
Self {
name: name.into(),
reason,
detail: detail.into(),
}
}
}
impl Gamedata {
pub fn set_signature(
&mut self,
name: impl Into<String>,
library: impl Into<String>,
linux: impl Into<String>,
) {
self.entries.entry(name.into()).or_default().signature = Some(Sig {
library: library.into(),
linux: linux.into(),
});
}
pub fn set_offset(&mut self, name: impl Into<String>, linux: i64) {
self.entries.entry(name.into()).or_default().offset = Some(linux);
}
/// Record the class a vtable-offset locator is relative to.
pub fn set_class(&mut self, name: impl Into<String>, class: impl Into<String>) {
self.entries.entry(name.into()).or_default().class = Some(class.into());
}
/// Attach string anchors to `name`, creating the entry if the derivation reached it by no other route.
///
/// Deduplicated and order-preserving: the catalogue can carry the same anchor twice across variants,
/// and the emitted list is part of a byte-reproducible artifact, so it must not depend on how many
/// times a source repeated itself.
pub fn add_anchors<S: Into<String>>(
&mut self,
name: impl Into<String>,
anchors: impl IntoIterator<Item = S>,
) {
let e = self.entries.entry(name.into()).or_default();
for a in anchors {
let a = a.into();
if !a.is_empty() && !e.anchors.contains(&a) {
e.anchors.push(a);
}
}
}
pub fn len(&self) -> usize {
self.entries.len()
}
pub fn is_empty(&self) -> bool {
self.entries.is_empty()
}
}
// ===========================================================================================
// The tiered catalogue — WHERE each named function is. Four confidence tiers with provenance
// + live-validation folded inline. It is the locator half of what `merge` folds into the shipped
// `rosetta-<game>.json`, where each entry becomes one [`FunctionRecord`].
// A `MonoEntry` EMBEDS `Entry`, so the locator shape stays
// single-sourced on `render::locator_value` and never diverges. Lib-agnostic: an entry carries its
// `library` in the signature locator, so the monolith spans every derived library, not just libserver.
// ===========================================================================================
/// A monolith entry's confidence tier — its finer label within a section, serialized as kebab strings
/// (`core`, `valve-table`, `self-named`, `dict-exact`, `contextual`, `corroborated`, `high`, `medium`,
/// `low`). Declared most-confident first.
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum Tier {
Core,
/// Named by a table Valve compiled into the binary being derived — today the entity-IO datadesc,
/// whose records pair a handler name with the handler itself. The only naming source that is neither
/// inferred nor transferred from another build, so it outranks every tier below it: the binary is
/// vouching for its own function names. (It is still not [`Tier::Core`], which additionally means
/// cross-build history — fingerprint verification and drift detection — that one build cannot supply.
/// The Pulse binding table names far more functions but does not LOCATE them; it ships as its own
/// registry, see [`Bindings`].)
ValveTable,
SelfNamed,
/// Dictionary-corroborated by the FOLD (an exact hit in the harvested name catalogue).
DictExact,
Contextual,
/// Dictionary-corroborated by the EXPERIMENTAL band, and also the label the macOS ground-truth
/// transfer carries. Kept distinct from [`Tier::DictExact`] rather than merged: the two are produced
/// by different paths, and folding them together would additionally conflate ground-truth symbols
/// with dictionary guesses. Anything counting "corroborated" for display must count BOTH — see
/// [`Tier::is_dict_corroborated`].
Corroborated,
High,
Medium,
Low,
}
impl Tier {
/// Is this tier a dictionary/ground-truth corroboration, under either of its two labels?
pub fn is_dict_corroborated(self) -> bool {
matches!(self, Tier::DictExact | Tier::Corroborated)
}
}
/// Per-entry provenance, folded inline. Optional by tier: a `core` entry carries almost nothing, an
/// `experimental` guess carries the full grading.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct Provenance {
pub tier: Tier,
/// Raw address in THIS build — a debugging/trace anchor (the monolith is per-build, so it's coherent).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub addr: Option<String>,
/// The confidence LABEL as the harvest records it — `"high"` / `"medium"` / `"low"` — a separate axis
/// from `tier` (a self-named entry can still be low-confidence). A string, not a number.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub confidence: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub self_named: Option<bool>,
/// Return is struct-by-value → unsafe to naive-call (the `RetClass::ByValue` flag).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub by_value: Option<bool>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub ret_class: Option<String>,
/// `"catalogue"` | `"source2rosetta-nameext"` | `"contribution:<date>"` | …
#[serde(default, skip_serializing_if = "Option::is_none")]
pub source: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub rtti_class: Option<String>,
/// high_confidence tier only — the naming rationale.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub rationale: Option<String>,
/// experimental tier only — how the dictionary corroborated the guess (`"exact"` / `"bare"` / `"none"`).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub corroboration: Option<String>,
/// experimental tier only — the same name was guessed at more than one address.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub collision: Option<bool>,
/// experimental tier only — protobuf/serializer/foreign plumbing (flagged, kept for completeness).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub dead_weight: Option<bool>,
/// core only — the target's ABI prototype-shape differs from the model's consensus (`"target [..] vs
/// history [..]"`). The signature still ships (a drifted arg-list is a loader-hook seam a byte-sig can't
/// see, not a wrong locator), but a consumer that ptrace-calls it should re-check the prototype.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub abi_drift: Option<String>,
}
impl Tier {
/// The tier's kebab id — the same string the `kebab-case` serialization emits, for a deriver that needs
/// it as a plain `&str` (e.g. a count-by-tier tally) without going through serde.
pub fn as_str(self) -> &'static str {
match self {
Tier::Core => "core",
Tier::ValveTable => "valve-table",
Tier::SelfNamed => "self-named",
Tier::DictExact => "dict-exact",
Tier::Contextual => "contextual",
Tier::Corroborated => "corroborated",
Tier::High => "high",
Tier::Medium => "medium",
Tier::Low => "low",
}
}
/// Parse a tier from its kebab id (the inverse of the `kebab-case` serialization) — so a deriver holding
/// a tier as a computed string can lift it to the typed enum without a serde_json round-trip. `None` for
/// an unrecognised id (the caller decides whether that is a hard error).
pub fn from_id(s: &str) -> Option<Tier> {
Some(match s {
"core" => Tier::Core,
"valve-table" => Tier::ValveTable,
"self-named" => Tier::SelfNamed,
"dict-exact" => Tier::DictExact,
"contextual" => Tier::Contextual,
"corroborated" => Tier::Corroborated,
"high" => Tier::High,
"medium" => Tier::Medium,
"low" => Tier::Low,
_ => return None,
})
}
}
impl Provenance {
/// A provenance with only its tier set (all optional fields `None`) — the base for `core` entries and
/// the start point for functional-update construction (`Provenance { source: …, ..with_tier(t) }`).
pub fn with_tier(tier: Tier) -> Self {
Self {
tier,
addr: None,
confidence: None,
self_named: None,
by_value: None,
ret_class: None,
source: None,
rtti_class: None,
rationale: None,
corroboration: None,
collision: None,
dead_weight: None,
abi_drift: None,
}
}
}
/// One monolith function: a locator (the `signature`/`offset` model shape, flattened in from [`Entry`] so
/// the shape is single-sourced) plus its provenance and live-validation verdict.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct MonoEntry {
#[serde(flatten)]
pub locator: Entry,
/// The argument footprint read out of THIS build's machine code — see [`AbiShape`]. Absent when the
/// function's address wasn't resolvable offline.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub abi: Option<AbiShape>,
pub provenance: Provenance,
/// Live-validation verdict: `Some(true)` passed, `Some(false)` dropped confident-bad, `None` unvalidated.
#[serde(default)]
pub validated: Option<bool>,
/// The OTHER shipped names that locate this same function — key-sorted, never including this entry's own
/// name, and empty for the ~95% of entries that are the only name for their target.
///
/// Several names on one function is normal and not a defect: the catalogue is assembled from independent
/// sources that spell the same function differently (`CreateEntityByName`, `UTIL::CreateEntityByName`
/// and `CGameEntitySystem::CreateEntityByName` are one address), and dropping all but one would discard
/// whichever spelling a given consumer's existing code already uses. What was missing is that the
/// artifact never SAID so, which left a reader unable to tell an alias from two genuinely different
/// functions — and left anything generating per-function documentation writing several unrelated
/// accounts of one target.
///
/// **Scope: `core` + `high_confidence`, across the two tiers rather than within each.** `experimental` is
/// excluded because its names are unverified guesses, so a shared target there is not evidence of a
/// shared meaning — that band states the converse relation (one name guessed at several addresses)
/// through `provenance.collision`.
///
/// **A bare-slot entry is never grouped**, and that is a real gap rather than an absence of aliases: an
/// `offset` with no `class` names no vtable, so two of them carrying slot 3 are not evidence of anything.
/// Grouping them would put every unbound slot-3 entry in one bucket — 1,080 CS2 names in 70 fictitious
/// groups, measured. Only class-bound offsets and signatures are grouped.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub aliases: Vec<String>,
}
/// A function's SysV-AMD64 argument footprint, read out of the target binary rather than declared: how many
/// integer and float registers it takes as inputs, whether arguments also spill to the stack, and how it
/// returns. This is what makes a *declared* prototype checkable — a declaration whose arity contradicts the
/// footprint does not describe this build, and calling through it would load the wrong registers.
///
/// A lower bound, never an over-count (a forwarding thunk reads no argument register of its own), so a
/// disagreement is worth review rather than an automatic rejection.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct AbiShape {
/// Integer/pointer arguments, including an implicit `this`. Caps at 6 — the SysV register budget.
pub int: u8,
/// Floating arguments (XMM0..7).
pub float: u8,
/// Arguments also arrive on the stack: the real arity exceeds the register budget, so a caller filling
/// only registers is wrong.
#[serde(default, skip_serializing_if = "is_false")]
pub stack: bool,
/// Return class token: `ret=void` | `ret=int` | `ret=float` | `ret=byval` | `ret=?` (undetermined).
/// `ret=byval` is the sret case — UNSAFE to blind-call, since the caller must pass an output buffer.
pub ret: String,
}
fn is_false(b: &bool) -> bool {
!*b
}
/// A catalogued function the derivation could not confidently produce — kept in-file (never a shipped
/// locator) so the monolith is the complete catalogue picture.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct Unresolved {
pub reason: String, // "sig-drifted" | "offset-low-conf" | "unresolved" | …
pub detail: String,
}
/// Entry counts per section — a struct (not a map) so it serializes in this logical order, deterministically.
#[derive(Clone, Debug, Default, serde::Serialize, serde::Deserialize)]
pub struct Counts {
pub core: usize,
pub high_confidence: usize,
pub experimental: usize,
pub unresolved: usize,
}
/// The monolith's intrinsic release identity. NO wall-clock field — volatile release metadata (`produced_at`,
/// `status`, urls, sha256, `based_on`) lives in the per-buildid manifest, so the monolith is fully
/// byte-reproducible.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct MonoMeta {
pub game_key: String,
pub game: String, // display name
pub source_build: String,
/// `<game>-<buildid>-<patch>` — the buildid is embedded here; the per-buildid MANIFEST carries it as its
/// own field (volatile metadata is kept OUT of this byte-reproducible monolith).
pub version: String,
pub counts: Counts,
/// How many distinct functions carry more than one shipped name, and how many names that accounts for
/// — the two halves of [`MonoEntry::aliases`] seen from the release's side. Counted over
/// `core` + `high_confidence` together, since a group routinely spans the two tiers.
///
/// Worth reading before treating the tier counts as a function count: on CS2 roughly 5% of the resolved
/// surface is several names on one target, so `counts.core + counts.high_confidence` over-counts
/// FUNCTIONS by about that much while being exactly right about NAMES, which is what it says.
#[serde(default)]
pub alias_groups: usize,
#[serde(default)]
pub aliased_names: usize,
}
/// The full derived gamedata for one build — four confidence tiers, each a key-sorted map. [`merge`]
/// flattens it into the shipped artifact's `functions`, where the tier a name came from rides on the
/// record instead of deciding which map it lives in.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct Monolith {
pub meta: MonoMeta,
pub core: BTreeMap<String, MonoEntry>,
pub high_confidence: BTreeMap<String, MonoEntry>,
pub experimental: BTreeMap<String, MonoEntry>,
pub unresolved: BTreeMap<String, Unresolved>,
}
/// Which of the monolith's three SHIPPABLE tiers a render includes — cumulative, most-confident first
/// (`unresolved` is never rendered; it has no locator). The `--tier` arg of `source2rosetta-gen`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TierSelect {
/// `core` only — the guaranteed, live-validated set.
Core,
/// core + high_confidence — adds the promoted name-extrapolations.
HighConfidence,
/// core + high_confidence + experimental — every locatable guess.
Experimental,
}
impl TierSelect {
/// Parse the `--tier` id (the monolith tier names, plus a couple of intuitive aliases).
pub fn from_id(s: &str) -> Option<TierSelect> {
match s {
"core" => Some(TierSelect::Core),
"high_confidence" | "high-confidence" | "stable" => Some(TierSelect::HighConfidence),
"experimental" | "full" => Some(TierSelect::Experimental),
_ => None,
}
}
}
/// Every `--tier` id `from_id` accepts (canonical names) — for help text.
pub const TIER_IDS: &[&str] = &["core", "high_confidence", "experimental"];
impl Monolith {
/// Flatten the tiers up to `select` into one `name -> Entry` map — the input the flat framework emitters
/// (metamod/modsharp/swiftly/plugify) consume. Drops confident-bad entries (`validated == Some(false)`);
/// `unresolved` is never included (no locator); a more-confident tier wins a name collision.
pub fn select(&self, select: TierSelect) -> Gamedata {
let mut gd = Gamedata {
entries: BTreeMap::new(),
game_key: self.meta.game_key.clone(),
};
let mut add = |m: &BTreeMap<String, MonoEntry>| {
for (name, e) in m {
if e.validated == Some(false) {
continue;
}
gd.entries
.entry(name.clone())
.or_insert_with(|| e.locator.clone());
}
};
add(&self.core);
if select != TierSelect::Core {
add(&self.high_confidence);
}
if select == TierSelect::Experimental {
add(&self.experimental);
}
gd
}
}
// ===========================================================================================
// The binding registry — what the binary DECLARES about its own callable surface, as opposed to what the derivation infers about it: Valve registers every Pulse
// binding and entity-IO input with a name, author-facing documentation, and call metadata, and this is
// that data read back out. Kept OUT of the monolith on purpose — the monolith answers "where is this
// function", this answers "what may I do with it", and only the first belongs in a gamedata file.
// ===========================================================================================
/// How a Pulse binding is invoked — the receiver question, which decides whether a caller needs an
/// entity at all. Mutually exclusive by construction (the two flag bytes are never set together).
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum BindingKind {
/// A free function on a Pulse library class (`CPulseMathlib::Sin`) — no receiver.
Library,
/// A method on an entity API (`CBaseEntityAPI::GetAbsOrigin`) — needs an instance receiver.
Instance,
/// A Pulse cell's own entry point (`CPulseCell_Step_DebugLog::Run`) — invoked by the VM as it walks
/// a graph, not called by a graph author.
Cell,
}
/// The call metadata Valve records for a binding — a typed graph VM cannot register a binding without
/// knowing how it may be invoked, so this is the engine's own policy, read back rather than reasoned out.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct CallPolicy {
pub kind: BindingKind,
/// The binding writes state. The const-correctness axis: a caller that only observes can be run
/// where a mutation may not be.
pub mutates: bool,
/// The binding may suspend the calling cursor instead of completing within the frame.
pub blocking: bool,
/// The two metadata words exactly as read, so a consumer can re-derive meaning if a later build
/// repurposes a bit rather than silently inheriting this decoding.
pub raw: [u32; 2],
}
/// One Pulse binding: where it is, what Valve calls it, and how it may be invoked.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct Binding {
/// The module registering it — `server`, `pulse_system`, …
pub library: String,
/// The author-facing label ("Get Abs Origin").
#[serde(default, skip_serializing_if = "Option::is_none")]
pub display: Option<String>,
/// The author-facing documentation ("The entity origin (absolute).").
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
pub policy: CallPolicy,
/// The binding's declared parameters, in order, recovered from the descriptor accessor's own
/// initializer. Pulse is a TYPED graph VM, so this is the engine's own statement of how the
/// binding is called — not a transfer from another game and not a 2018-era declaration.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub params: Vec<PulseParam>,
/// The values it hands back. Pulse models returns as named out-parameters, so this is a LIST:
/// usually one `retval`, empty for a void binding, occasionally several.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub returns: Vec<PulseParam>,
/// Whether the signature above was recovered at all. An empty `params` on an untyped binding means
/// "not read"; on a typed one it means "takes nothing", and only this field separates them.
pub typed: bool,
/// Address of the binding's DESCRIPTOR ACCESSOR in this build — a lazy-init singleton returning the
/// static descriptor, not the bound function. It is the anchor a runtime walks to reach the
/// descriptor; it is NOT a locator for the named method, and no shipped gamedata entry points at it.
/// For an address that IS callable, see [`Binding::shim`].
pub descriptor: String,
/// Address of the binding's INVOCATION SHIM in this build — the record's third code pointer, and
/// unlike `descriptor` a real entry point. One per binding, never shared.
///
/// Calling it dispatches through Valve's own marshalling, which honours the DECLARED parameter types
/// in `params`: a value written into the argument blob is consumed according to its `PulseValueType_t`,
/// so a caller cannot smuggle a mistyped argument past it. Absent when the record's slot holds no
/// executable code.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub shim: Option<String>,
/// How to call [`Binding::shim`], and what a host must supply. Absent when there is no shim.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub call: Option<ShimCall>,
}
/// The invocation shim's calling contract: fixed across every binding, with a per-binding statement of
/// which slots that particular shim reads.
///
/// The signature is **seven integer arguments returning int**. Slot 5 (`r8`) is an array of POINTERS to the
/// argument values, element *k* at `+8+8k`. Slot 7 (the first stack slot) is the output sink. Slot 4
/// (`rcx`) is a Pulse host-service context, which is VM-owned. The return is `0` on dispatch and `-2` when
/// an entity-handle argument fails to resolve.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ShimCall {
/// What a host must supply beyond the argument array, decoded from `reads`:
///
/// * `args-only` — nothing else. The remaining slots may be null; **validated by calling every
/// eligible binding in both games.** This is the callable tier.
/// * `output-sink` — it returns a value, so it writes through a register-file object a host does not
/// have. Read the state through the `schema` section instead; the Pulse getters are redundant
/// with schema fields.
/// * `pulse-context` — needs a live `CPulseExecCursor` / graph instance. Not host-callable.
/// * `other-slots` — reads an argument slot whose role is not established (the `CPulseCell_*`
/// family, which are graph NODE implementations rather than API bindings). Not host-callable.
pub needs: String,
/// The argument slots this shim was measured to read, named in SysV order — the raw fact `needs` is
/// decoded from, kept beside it so a build that changes the contract can be re-read rather than
/// silently mis-labelled. The same rule `flags_raw` follows.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub reads: Vec<String>,
}
/// One Pulse parameter or return value, as the binding declares it.
///
/// Defined here rather than beside the reader so the deriver-free core crate can carry it: `gen` emits
/// these, and nothing about the shape depends on how it was read out of the binary.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct PulseParam {
/// The author-facing parameter name — `_Target` for the receiver, `retval` for a return.
pub name: String,
/// The `PulseValueType_t` enumerator, as the binary states it. Join it to the `enums` section of
/// the `schema` section's `enums` for the spelling; the raw value is kept because that is the fact.
#[serde(rename = "type")]
pub ty: i32,
/// The schema type the value refers to, where the binding NAMES one — which enum a
/// `PVAL_SCHEMA_ENUM` is, which struct an opaque handle wraps. Absent for the self-describing
/// types, and absent for a `PVAL_EHANDLE`'s entity class, which the initializer does not state —
/// see `entity_class` for where that comes from instead.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub type_name: Option<String>,
/// The entity class behind a `PVAL_EHANDLE` — `func_mover`, `basemodelentity`. NOT read from the
/// initializer, which never states it: it is Valve's own naming (`mappings/ehandle-classes.json`,
/// harvested from the published metadata) propagated across the parameters this build proves are
/// the same type. See [`PulseParam::type_token`] for what proves it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub entity_class: Option<String>,
/// An opaque per-build token identifying the parameter's CONCRETE type: the address of that type's
/// destructor, which the initializer stores beside the name. Two parameters carry the same token
/// exactly when they are the same type — including the entity class behind a `PVAL_EHANDLE`, which
/// nothing else in the binary distinguishes.
///
/// NOT serialized, deliberately. An address is meaningless outside the build it was read from, so
/// shipping it would invite a consumer to key on something that moves every release. It exists to
/// carry the grouping from the reader to the stage that names it, and no further.
#[serde(skip)]
pub type_token: u64,
}
/// One entity-IO input handler: the name a map fires, and the C++ method that answers it.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct EntityInput {
/// The input name entity IO addresses — `Kill`, `Enable`, `SetSpeed`.
pub input: String,
/// The class that owns this handler, recovered from the FIELD descriptors sharing its datadesc
/// array: a field is a `(member, offset)` pair the SchemaSystem states independently, so the class
/// whose schema contains every pair in the array owns it. Absent where the array's fingerprint fit
/// several classes or none — `InputEnable` is a distinct handler on 48 classes and guessing between
/// them is the thing this exists to stop.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub class: Option<String>,
/// The C++ handler — `InputKill`. NOT class-qualified: the record carries no owning class, which is
/// also why the same handler name legitimately appears at many addresses here.
pub handler: String,
pub library: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub abi: Option<AbiShape>,
pub addr: String,
}
/// One registered console command: the name a server operator or a mod types, and the function that
/// answers it. Unlike the Pulse registry this carries a real locator — the handler comes from the same
/// registration call as the name, not from a descriptor accessor beside it.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct ConsoleCommand {
/// The console-facing name, exactly as Valve compiled it — `bot_add`, `+bugvoice`.
pub name: String,
pub library: String,
/// Valve's own help text; absent when the registration passes none.
#[serde(default, skip_serializing_if = "String::is_empty")]
pub description: String,
/// The flag bits whose meaning is measured against Valve's published dump.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub flags: Vec<String>,
/// The raw flags word, kept beside the decoding so a build that repurposes a bit can be re-read
/// instead of silently mis-labelled — the same rule the Pulse policy word follows.
pub flags_raw: String,
/// How the registration passed its callback: `direct`, `interface` or `member`. Says how much
/// indirection produced the address, which is the honest measure of how far this is from the
/// instruction stream.
pub form: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub abi: Option<AbiShape>,
pub addr: String,
}
/// One ConVar the module registers — the configuration half of the console surface.
///
/// Emitted for the METADATA, not as a locator: a consumer finds a convar by name at runtime
/// (`ICvar::FindConVar`) with no gamedata at all, so the name alone would add nothing. The flags are the
/// payload — `cheat`, `replicated`, `release` are engine-DECLARED authority, and a host deciding what a
/// module may change is better served by what the engine says than by a hand-maintained allowlist.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct ConVar {
pub name: String,
pub library: String,
#[serde(default, skip_serializing_if = "String::is_empty")]
pub description: String,
/// FCVAR bits with a measured meaning — the same space console commands use.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub flags: Vec<String>,
/// The raw flags word. Empty when this registrar had no identifiable flags argument, which is honest
/// about the gap rather than reporting a zero that would read as "no flags set".
#[serde(default, skip_serializing_if = "String::is_empty")]
pub flags_raw: String,
/// Address of the ConVar object. It lives in `.bss`, so it holds nothing on disk — it is the anchor a
/// runtime walks to the live value, and what tells two registrations of one name apart.
pub addr: String,
}
/// One entity-IO output: an event an entity fires, and where its subscriber list lives on the instance.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct EntityOutput {
/// The entity-IO name a map or a mod wires to, e.g. `OnStartTouch`.
pub output: String,
/// The member holding it, e.g. `m_OnStartTouch` — usually the name with `m_` prepended, but not
/// reliably (`BombExplode` lives on `m_OnBombExplode`), so both ship.
pub member: String,
pub library: String,
/// Byte offset of the member within its entity — an output is data, not a function, so this is the
/// locator. (`CEntityIOOutput` is 24 bytes; see the `types` section of the schema artifact.)
pub offset: u32,
/// The class the member lives on, recovered by joining `(member, offset)` against the SchemaSystem.
/// Without it an offset is unusable wherever a name repeats: `OnBreak` exists at three different
/// offsets on three different classes, and reading the wrong one runs ~1 KB past the intended member
/// on a live entity. `None` only when the schema does not describe the member.
///
/// NB the member's TYPE is not carried here: the offline schema reader recovers names and offsets but
/// not types (those are runtime-resolved), and a handful of outputs are not the plain 24-byte
/// `CEntityIOOutput` — `CLogicCase::m_OnCase` is `CEntityIOOutput[32]`. Join `class` + `member`
/// against the `schema` section for the type before striding one.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub class: Option<String>,
}
/// The declared callable surface for one build. [`merge`] folds the function-keyed parts of it onto
/// the functions they describe and keeps the rest under [`Surfaces`].
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct Bindings {
pub meta: BindingsMeta,
/// Pulse bindings, keyed by their fully-qualified `Class::Method`.
pub pulse: BTreeMap<String, Binding>,
/// Entity-IO inputs, as a LIST: the handler name is not unique (one `InputEnable` per class), so
/// there is no honest key to map them by.
pub entity_inputs: Vec<EntityInput>,
/// Entity-IO outputs — the events an entity fires, as a LIST for the same reason as the inputs.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub entity_outputs: Vec<EntityOutput>,
/// Map classname -> the C++ class it constructs (`func_door` -> `CBaseDoor`). The join between the
/// vocabulary a level designer writes and the classes the `schema` section describes. No addresses:
/// the factory record binds names to names, not to a function.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub entity_classes: BTreeMap<String, String>,
/// Console commands, as a LIST: a handful of names are registered by more than one library, so
/// there is no honest key to map them by either.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub commands: Vec<ConsoleCommand>,
/// ConVars, a LIST for the same reason: one name can be registered by more than one library.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub convars: Vec<ConVar>,
/// VScript bindings — the surface Valve exposes to Lua, keyed by the SCRIPT-facing name a content
/// author types. A LIST rather than a map because a name is only unique per class, and the owning
/// class is not recoverable offline.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub vscript: Vec<VScriptBinding>,
}
/// One function Valve exposes to the script VM.
///
/// The fourth surface the binary documents about itself, and the only one that pairs a script-facing
/// name with a C++ name, an English description AND a return type in one record. It is disjoint from
/// everything else shipped here: measured against the catalogue, not one of the 1,652 Dota
/// implementations shares an address with a catalogued entry, and no name is shared either — a
/// `Script_TakeDamage` is a script-facing WRAPPER, a different function from the `TakeDamage` it wraps.
/// So these are additive, never a second account of something already described.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct VScriptBinding {
/// What a Lua author calls (`TakeDamage`).
pub name: String,
/// The class that owns this member (`CDOTA_BaseNPC`).
///
/// **Live-only, and absent from an offline build.** The class descriptor reaches the registration
/// through a register loaded from memory rather than a `lea`, so constant propagation recovers it for
/// none of the bindings; a running server resolves it through the record's owner pointer. This is the
/// same shape as a schema field's TYPE, which is a null placeholder on disk and is why an offline run
/// ships no typed netvars either.
///
/// Consumers that group by class — `api.json`, the `.d.ts` the Dota ecosystem publishes — need this
/// and cannot be rendered from a full build's output alone if it is missing.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub class: Option<String>,
/// The C++ binding this resolves to (`Script_TakeDamage`) — and the key under which the
/// implementation is folded into the catalogue, where it exists as a locator.
pub cpp: String,
pub library: String,
/// Valve's own English description, where the registration supplies one.
#[serde(default, skip_serializing_if = "String::is_empty")]
pub description: String,
/// The return type, decoded. Absent when the raw word is outside the corroborated set.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub ret: Option<String>,
/// The raw return-type word, kept beside the decoding so a build that renumbers `ScriptDataType_t`
/// can be re-read rather than silently mis-labelled — the rule `flags_raw` already follows.
pub ret_raw: u16,
/// The implementation address, or the vtable slot when the registration binds a virtual member.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub addr: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub vtable_slot: Option<u64>,
/// The prose for the function this binding resolves to — see [`FunctionRecord::doc`].
///
/// **Never on disk**, in either direction: it is joined at VIEW time by [`Rosetta::vscript`], which
/// reads it off the record the row was folded onto. That is the whole point of carrying it on the
/// row rather than looking it up by name in an emitter: an UNJOINED row bears a name that belongs
/// to another module's function, so a name lookup would hand it prose about code it is not.
#[serde(skip)]
pub doc: Option<Doc>,
}
/// The binding registry's intrinsic identity (no wall-clock field, same rationale as [`MonoMeta`]).
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct BindingsMeta {
pub game_key: String,
pub source_build: String,
pub pulse: usize,
/// Of those, how many carry a recovered typed signature.
#[serde(default)]
pub pulse_typed: usize,
/// Of those, how many carry a HOST-CALLABLE invocation shim (`call.needs == "args-only"`).
#[serde(default)]
pub pulse_callable: usize,
pub entity_inputs: usize,
#[serde(default)]
pub entity_outputs: usize,
#[serde(default)]
pub entity_classes: usize,
#[serde(default)]
pub commands: usize,
#[serde(default)]
pub convars: usize,
/// VScript bindings recovered.
#[serde(default)]
pub vscript: usize,
/// Of those, how many were attributed to an owning class. Zero on an offline build by construction —
/// the class is only readable from a running server.
#[serde(default)]
pub vscript_classed: usize,
/// Of those, how many folded into the catalogue as a locator. Lower than `vscript` by the
/// bindings whose implementation did not resolve and the handful whose C++ name is registered at
/// more than one address — dropped, not guessed, exactly as the datadesc handlers are.
#[serde(default)]
pub vscript_located: usize,
}
impl Bindings {
pub fn is_empty(&self) -> bool {
self.pulse.is_empty()
&& self.entity_inputs.is_empty()
&& self.entity_outputs.is_empty()
&& self.entity_classes.is_empty()
&& self.commands.is_empty()
}
}
// ===========================================================================================
// The prototype manifest — what a function TAKES, which a locator deliberately does not answer: a locator says where a function is, a prototype says how to call it, and
// the two have different sources and different lifetimes. Declarations are static and human-sourced;
// the VERDICT on each one is re-measured against every build.
// ===========================================================================================
/// The verdict on a declared prototype, judged against the footprint measured in THIS build.
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum AbiStatus {
/// The declared arity matches the measured footprint — safe to call through.
Verified,
/// The callee reads a register the declaration does not mention. The declaration does not describe
/// this build and MUST NOT be called through: such a call resolves, passes live validation, and then
/// leaves a register the callee reads unset.
Mismatch,
/// The declaration passes registers the callee never reads, and contradicts it in no register class.
///
/// NOT a mismatch, and separating the two is the point. The measured footprint is a documented LOWER
/// bound — a callee that ignores an argument, a forwarding thunk that reads none of its own, an
/// empty virtual override — so measuring FEWER arguments than declared is expected behaviour rather
/// than evidence against the declaration. `CBaseEntity::SetAbsAngles` is the shape: declared
/// `(this, float, float, float)`, measured `int=0 float=3`, every float agreeing exactly and only
/// the unread `this` differing. Calling through one merely loads a register nobody reads, which is
/// the opposite of the failure `Mismatch` names. 81 of CS2's 140 former mismatches are this.
LowerBound,
/// No measurement available to check it against.
Unverified,
/// Overloads the measurement could not separate.
Ambiguous,
/// A return type was declared and a parameter list was not, so there is no arity claim for the
/// binary to confirm or refute. `CALL_VIRTUAL(RET, …)` sites are the source: they say what comes
/// back and pass VALUES rather than types, so nothing about the signature can be read off them.
ReturnOnly,
}
impl AbiStatus {
pub fn as_str(self) -> &'static str {
match self {
AbiStatus::Verified => "verified",
AbiStatus::Mismatch => "mismatch",
AbiStatus::LowerBound => "lower-bound",
AbiStatus::Unverified => "unverified",
AbiStatus::Ambiguous => "ambiguous",
AbiStatus::ReturnOnly => "return-only",
}
}
}
/// One function's declared prototype and the verdict this build gives it.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct AbiEntry {
/// Which shipped tier the function is in. Cleared when folded onto a [`FunctionRecord`], which
/// states it already.
#[serde(default, skip_serializing_if = "String::is_empty")]
pub tier: String,
/// `exact` — the declaration names this function; `bare-name` — it names the same METHOD on some
/// class, claimed only because exactly one declaration bears that name and a measurement could
/// adjudicate.
pub matched_by: String,
pub status: AbiStatus,
/// Declared parameter TYPES — the thing a machine-derived arity cannot supply.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub params: Option<Vec<String>>,
/// Set when `params` is the FULL register-visible argument list, receiver included, because the
/// declaration was a function-pointer type rather than a mangled symbol. Absent means `this` is not
/// in the list and a caller has to supply it — the convention every Itanium-derived entry uses.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub params_complete: Option<bool>,
#[serde(rename = "const", default, skip_serializing_if = "Option::is_none")]
pub is_const: Option<bool>,
/// A DECLARED return type where one exists, else the measured register class — a far weaker
/// statement (see [`AbiShape`]), and one that is not evidence about the declared type.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub ret: Option<String>,
/// Omitted on an `ambiguous` verdict, where no declaration was chosen.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub provenance: Vec<String>,
/// The measured SysV footprint the verdict was reached against.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub derived: Option<AbiShape>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub note: Option<String>,
/// Every signature the declarations offered, whenever there was more than one — whether the
/// measurement went on to pick between them (see `note`) or could not, which is `ambiguous`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub overloads: Option<Vec<Vec<String>>>,
/// The vtable slot this build's shipped locator resolves through, present exactly when the locator
/// is a vtable offset that LIVE VALIDATION confirmed.
///
/// It states something no measurement can: a slot is only reachable through an object, so the
/// function HAS a receiver even where the footprint cannot see one. That case is not marginal —
/// a getter that returns a constant never reads `this`, and backward liveness reads that as no
/// argument at all, so `CBaseDoor::GetDataDescMap` measures `int=0` while genuinely taking one.
///
/// Live validation is part of the condition rather than a separate check, because it is what rules
/// out the one way an `offset` locator can fail to be a vtable slot: a carried MEMBER offset under a
/// name the deriver could not classify, which the live oracle reports as `Unknown`/`Oob` instead of
/// `Live`. An offline derive has no such evidence and therefore states no `vtable` at all —
/// a smaller emittable set, never a guessed receiver.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub vtable: Option<i64>,
/// The prose for this function — see [`FunctionRecord::doc`]. **Never on disk**: joined at VIEW
/// time by [`Rosetta::abi_manifest`], off the record this prototype belongs to, so that the call
/// sites a framework generates can carry it into an editor's tooltip.
#[serde(skip)]
pub doc: Option<Doc>,
}
impl AbiEntry {
/// Drop what the function record states for itself. The tier and the measured footprint the verdict
/// was reached against are both fields of the record this is folded onto — carrying them here too
/// would give one fact two homes, and two homes is how they come to disagree.
fn into_record_prototype(mut self) -> AbiEntry {
self.tier.clear();
self.derived = None;
self
}
/// An entry with only the fields every verdict carries — the base for functional-update construction.
pub fn blank() -> Self {
Self {
tier: String::new(),
matched_by: String::new(),
status: AbiStatus::Unverified,
params: None,
params_complete: None,
is_const: None,
ret: None,
provenance: Vec::new(),
derived: None,
note: None,
overloads: None,
vtable: None,
doc: None,
}
}
}
/// The prototype manifest's identity plus its verdict tally.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct AbiMeta {
pub game_key: String,
pub source_build: String,
/// Verdict tally — `status:verified`, `core:resolved`, `high_confidence:none`, …
pub counts: BTreeMap<String, usize>,
}
/// Every declared prototype this build could judge — [`merge`] folds each onto its function as
/// [`FunctionRecord::prototype`].
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct AbiManifest {
pub meta: AbiMeta,
pub functions: BTreeMap<String, AbiEntry>,
}
/// One typed schema field (the field NAME is the map key). `offset` is static; `ty`/`kind`/`size` are
/// runtime-resolved (empty/zero when derived offline without a live process).
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct Field {
pub offset: i32,
#[serde(rename = "type", default, skip_serializing_if = "String::is_empty")]
pub ty: String,
#[serde(default)]
pub kind: FieldKind,
pub size: usize,
pub name_hash: u64,
}
/// How a schema field holds its value — a closed runtime domain (Source-2 `CSchemaType` category).
/// Serializes to lowercase tokens, the values a schema consumer expects.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FieldKind {
/// Builtin / atomic / declared class / declared enum — held inline (the common case).
#[default]
Ref,
/// A pointer to the value.
Ptr,
/// A fixed-size inline array.
FixedArray,
}
/// A direct base class and the `this`-adjustment to reach it. The schema records these, and a consumer
/// needs them for the artifact's most basic question: `CCSPlayerPawn.m_iHealth` is not a field OF
/// `CCSPlayerPawn` — it is inherited, and only the base chain says where to look.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct BaseClass {
pub name: String,
pub offset: u32,
}
/// How a type travels when passed BY VALUE under the SysV-AMD64 convention — the fact a caller needs
/// that a field offset cannot supply.
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum SysvClass {
/// Travels in integer registers: pointers, handles, and small aggregates with any non-float member.
Integer,
/// Travels in SSE registers — an aggregate of 16 bytes or less whose members are all floating-point.
/// `Vector` (3 floats) is the case that bites: by value it costs TWO SSE registers, by reference one
/// integer register.
Sse,
/// Larger than 16 bytes, so it is passed in memory (effectively by reference) and returned through a
/// hidden pointer. Size alone settles this one.
Memory,
/// Size known but composition unknown, or size unknown — a caller must not guess.
Unknown,
}
/// Where a type's size came from — the honesty axis, since the two routes carry different confidence.
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum LayoutSource {
/// The SchemaSystem states the class's instance size outright.
Schema,
/// Inferred from the distance to the next field across many classes — exact for every primitive whose
/// size is independently known, but an inference nonetheless.
FieldGap,
/// Declared in the deriver, for the closed set of engine primitives the schema does not register.
Declared,
}
/// What a consumer needs to pass or hold a value of some type: how big it is, and how it travels.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct TypeLayout {
pub size: usize,
pub sysv: SysvClass,
pub source: LayoutSource,
/// How many field observations backed a `field-gap` size, and how many agreed — omitted for the other
/// sources, where the size is stated rather than inferred.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub observations: Option<usize>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub agreement: Option<usize>,
}
/// One enumerator: the name and the value it stands for.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct EnumValue {
pub name: String,
pub value: i64,
}
/// A registered enum — the semantic vocabulary behind an integer field. `m_MoveType = 2` is only
/// meaningful as `MOVETYPE_WALK`, and a register footprint can never recover that.
///
/// Unlike a field's TYPE, this is static data: the SchemaSystem records enum bindings in the binary, so
/// these are read from the image rather than from the running process.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct EnumDef {
/// Underlying integer width in bytes — 1 for `MoveType_t`, 4 for `gear_slot_t`. Recorded by the
/// binding, so the distinction is read rather than assumed.
pub size: u8,
/// Enumerators in DECLARATION order. A list, not a map: names are unique but values are not, since
/// aliases (`MOVETYPE_LAST` / `MOVETYPE_INVALID`) legitimately share one.
pub values: Vec<EnumValue>,
}
/// The typed schema, ships as the artifact's `schema` section. Merges field offsets with runtime types:
/// class -> field -> [`Field`], plus the enum vocabulary those fields refer to.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct Schema {
pub meta: SchemaMeta,
pub classes: BTreeMap<String, BTreeMap<String, Field>>,
/// Direct base classes per class. `classes` holds each class's OWN fields only, so resolving an
/// inherited member means walking this.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub bases: BTreeMap<String, Vec<BaseClass>>,
/// Registered enums by name. Empty on an older artifact that predates the enum walk.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub enums: BTreeMap<String, EnumDef>,
/// Size + SysV class for every type the fields above refer to — what a caller needs in order to pass
/// one, which neither an offset nor a register footprint can supply.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub types: BTreeMap<String, TypeLayout>,
}
/// The typed schema's intrinsic identity (no wall-clock field, same rationale as [`MonoMeta`]).
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct SchemaMeta {
pub game_key: String,
pub source_build: String,
pub typed: usize,
pub untyped: usize,
/// Registered enums recovered (0 on an artifact that predates the enum walk).
#[serde(default)]
pub enums: usize,
/// Types with a recovered size + SysV class.
#[serde(default)]
pub types: usize,
}
// ===========================================================================================
// The merged release artifact — the shipped `rosetta-<game>.json`. ONE record per function, joining
// what the four derivation stages each know about it: where it is, what its machine code was measured
// to take, what a declaration says it takes, what the binary declares may be done with it, and what it
// means. Those are separate STAGES with separate confidence, not separate artifacts: keyed by name,
// they describe one thing, and a consumer answering "may I call this, and how" needed all four open at
// once to find out.
//
// The split that survives is between what is FUNCTION-KEYED and what is not. A Pulse binding names no
// C++ function, an entity output is a member rather than a method, and a classname maps names to names
// — none of those has a function record to live on, so they stay whole under `surfaces`.
// ===========================================================================================
/// Which shipped tier a function record came from — the section names of the tiered catalogue, kept as
/// a per-record field now that the tiers are no longer separate maps.
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Section {
Core,
HighConfidence,
Experimental,
}
impl Section {
/// The section's id, the same string the serialization emits.
pub fn as_str(self) -> &'static str {
match self {
Section::Core => "core",
Section::HighConfidence => "high_confidence",
Section::Experimental => "experimental",
}
}
}
/// What a function is FOR, in plain language, for a reader who has the locator and still does not know
/// what the function does.
///
/// Keyed on the NAME rather than any locator, and deliberately SIGNATURE-FREE: arity, types and verdicts
/// live in [`FunctionRecord::prototype`] and are joined at render time, so a prototype changing under a
/// new build cannot make a description wrong.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct Description {
pub text: String,
/// How the text was arrived at — `derived` where the surrounding facts fix the meaning mechanically,
/// `generated` otherwise. Valve's own prose is NOT carried here: it rides the binding it came with,
/// and duplicating it would create a second place for one fact to go stale.
pub source: String,
}
/// One function's prose as an emitter prints it: the text, and where it came from.
///
/// Distinct from [`Description`] because it is a RESOLVED view over every place prose can live. A
/// `Description` is what this artifact authored; a `Doc` may equally be Valve's own text, lifted off the
/// binding that carried it. `source` says which, and every emitter prints it beside the text — a plugin
/// author acting on a sentence must never have to guess whether Valve wrote it or this project did.
#[derive(Clone, Debug)]
pub struct Doc {
/// Collapsed to ONE line (see [`one_line`]): every target embeds this in a comment, and two of the
/// three comment syntaxes involved end at a newline.
pub text: String,
/// [`Doc::VALVE`], or the authored [`Description::source`] id.
pub source: String,
}
impl Doc {
/// The `source` of text the binary itself carries. Not a value [`Description::source`] ever holds —
/// Valve's prose rides its binding — so it cannot collide with an authored id.
pub const VALVE: &'static str = "valve";
}
/// Collapse every whitespace run to a single space.
///
/// Load-bearing rather than cosmetic: 78 CS2 and 82 Dota descriptions contain a newline, and both the
/// C# `///` and the C++ `//` comment forms END at one — an unflattened description would put the rest
/// of Valve's sentence into the generated source as code.
pub(crate) fn one_line(s: &str) -> String {
s.split_whitespace().collect::<Vec<_>>().join(" ")
}
/// What the binary itself declares may be done with this function, where it declares anything at all.
///
/// Internally tagged, because the three cases carry genuinely different fields and a consumer switches on
/// which one it got: an entity-IO handler answers a name a map fires, a console handler answers a command
/// an operator types, and a VScript binding is the same function exposed to the script VM under another
/// name with Valve's own documentation attached.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
pub enum FunctionBinding {
EntityInput {
/// The input name entity IO addresses — `Kill`, `Enable`, `SetSpeed`.
input: String,
/// The owning class where the datadesc array's field descriptors identified one.
class: Option<String>,
},
Command {
command: String,
/// Valve's own help text, `null` where the registration passes none.
description: Option<String>,
/// FCVAR bits with a measured meaning, `null` where the word sets none of them.
flags: Option<Vec<String>>,
/// The raw flags word, kept beside the decoding so a build that repurposes a bit can be re-read.
flags_raw: String,
/// How the registration passed its callback — `direct`, `interface`, `member`.
callback_form: String,
},
Vscript {
/// What a Lua author types, as opposed to the C++ name this record is keyed by.
script_name: String,
class: Option<String>,
description: Option<String>,
ret: Option<String>,
ret_raw: u16,
},
}
/// One function, everything the release knows about it.
///
/// The locator is flattened in exactly as the tiered catalogue flattened it, so a consumer that only
/// wants an address reads the same shape as before. Everything after it is a different KIND of fact, and
/// the field names say which: `measured` is read out of this build's machine code, `prototype` is a human
/// declaration judged against that measurement, `binding` is the binary's own declaration about the
/// function, and `description` is authored prose.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct FunctionRecord {
pub tier: Section,
#[serde(flatten)]
pub locator: Entry,
/// The SysV argument footprint read out of this build — see [`AbiShape`]. Absent when the address
/// was not resolvable offline.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub measured: Option<AbiShape>,
/// Live-validation verdict, and it is THREE-VALUED: `true` passed, `false` dropped confident-bad,
/// `null` not checked here. Always emitted, never skipped — `null` is a statement (an offline build,
/// a library the vanilla server does not map, a non-vtable class) and an absent key would leave a
/// reader unable to tell it from a field this artifact forgot.
#[serde(default)]
pub validated: Option<bool>,
/// The other shipped names for this same function — see [`MonoEntry::aliases`].
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub aliases: Vec<String>,
pub provenance: Provenance,
/// The declared prototype and this build's verdict on it, where one was declared.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub prototype: Option<AbiEntry>,
/// What the binary declares may be done with this function — a LIST, because one function can be
/// several of them: `AddOutput` is registered on three classes at once, and a console name can be
/// registered by more than one library. Keeping only the last would assert one class as the class.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub bindings: Vec<FunctionBinding>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<Description>,
}
impl FunctionRecord {
/// The one piece of prose to print above this function, resolved across every place prose can be.
///
/// **Valve's own text always wins.** It is a statement by the people who wrote the function, read
/// out of the binary's own registries; [`Description`] is this project's reading of the build, and a
/// reading has no business overriding the source. So a generated description FILLS A GAP and never
/// displaces one — which also means the two can never disagree in a shipped output.
///
/// Between Valve's two registries the VScript one wins, because the two describe different things: a
/// script binding's description documents the FUNCTION, while a console registration's help text
/// documents the COMMAND that reaches it ("`sv_cheats <0/1>` — enable cheats") and is written for an
/// operator typing it, not a caller.
///
/// `None` where nothing describes the function at all, which is the majority: 5,287 of 8,361 CS2
/// records. An emitter renders those exactly as it did before descriptions existed.
pub fn doc(&self) -> Option<Doc> {
// Empty is not documented: a registration that passes an empty help string has said nothing,
// and skipping it here is what lets the search fall through to the next binding — and then to
// the generated text — instead of stopping on a blank.
let valve = |want_vscript: bool| {
self.bindings.iter().find_map(|b| {
match b {
FunctionBinding::Vscript { description, .. } if want_vscript => {
description.as_deref()
}
FunctionBinding::Command { description, .. } if !want_vscript => {
description.as_deref()
}
_ => None,
}
.filter(|d| !d.is_empty())
})
};
if let Some(text) = valve(true).or_else(|| valve(false)) {
return Some(Doc {
text: one_line(text),
source: Doc::VALVE.to_string(),
});
}
self.description.as_ref().map(|d| Doc {
text: one_line(&d.text),
source: d.source.clone(),
})
}
}
/// The typed schema, as a section of the merged artifact.
///
/// **Live-only.** Field types are runtime-resolved, so an offline build has no schema to state — which is
/// why [`Rosetta::schema`] is an explicit `null` rather than an absent key: absence would be
/// indistinguishable from a build that resolved zero classes.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct SchemaSection {
pub classes: BTreeMap<String, BTreeMap<String, Field>>,
pub bases: Option<BTreeMap<String, Vec<BaseClass>>>,
pub enums: Option<BTreeMap<String, EnumDef>>,
pub types: Option<BTreeMap<String, TypeLayout>>,
pub meta: Option<SchemaMeta>,
}
impl From<Schema> for SchemaSection {
fn from(s: Schema) -> Self {
fn opt<K, V>(m: BTreeMap<K, V>) -> Option<BTreeMap<K, V>> {
(!m.is_empty()).then_some(m)
}
SchemaSection {
classes: s.classes,
bases: opt(s.bases),
enums: opt(s.enums),
types: opt(s.types),
meta: Some(s.meta),
}
}
}
/// The declared surfaces that are NOT function-keyed, so cannot fold into a function record.
///
/// Each is here for its own reason rather than as a leftovers bin: a Pulse binding does not name a C++
/// function at all (its `shim` is an entry point into Valve's marshalling, not the bound method), an
/// entity output is a member offset rather than a method, a classname binds one name to another, a
/// ConVar is configuration rather than code, and an unlocated VScript binding is documentation for a
/// function this build could not place.
#[derive(Clone, Debug, Default, serde::Serialize, serde::Deserialize)]
pub struct Surfaces {
#[serde(default)]
pub pulse: BTreeMap<String, Binding>,
#[serde(default)]
pub entity_outputs: Vec<EntityOutput>,
#[serde(default)]
pub entity_classes: BTreeMap<String, String>,
#[serde(default)]
pub convars: Vec<ConVar>,
/// Declared rows that belong to no function record here. See [`Unjoined`].
#[serde(default)]
pub unjoined: Unjoined,
}
/// What the binary declares about functions this build does not describe — the other side of the
/// function-keyed joins, kept rather than dropped so the merge loses nothing the deriver read.
///
/// Two things put a row here, and they are different in kind. Either **nothing located it**: the
/// implementation did not resolve, or the handler's name was ambiguous and was dropped rather than
/// guessed. Or **the name belongs to another module's function**: a console name registered by two
/// libraries, or a script name registered in three, is several functions, while the catalogue holds one
/// entry under that name — so the rows from the other modules describe code this artifact does not
/// locate, and asserting them onto the one record it does would be a claim about the wrong function.
///
/// Each row keeps its own `library` and `addr`, which is what tells the two cases apart.
#[derive(Clone, Debug, Default, serde::Serialize, serde::Deserialize)]
pub struct Unjoined {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub entity_inputs: Vec<EntityInput>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub commands: Vec<ConsoleCommand>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub vscript: Vec<VScriptBinding>,
}
/// How many records each join reached — reported so a collapse in any one of them is visible in the
/// artifact rather than only in a derive log.
#[derive(Clone, Debug, Default, serde::Serialize, serde::Deserialize)]
pub struct Joined {
pub prototypes: usize,
pub bindings: JoinedBindings,
pub descriptions: usize,
}
#[derive(Clone, Debug, Default, serde::Serialize, serde::Deserialize)]
pub struct JoinedBindings {
#[serde(rename = "entity-input")]
pub entity_input: usize,
pub command: usize,
pub vscript: usize,
}
/// The merged artifact's identity — the catalogue's own release identity plus what the merge joined.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct RosettaMeta {
pub game_key: String,
pub game: String,
pub source_build: String,
pub version: String,
pub counts: Counts,
pub alias_groups: usize,
pub aliased_names: usize,
pub merged: bool,
pub joined: Joined,
}
/// The shipped `rosetta-<game>.json` — one file, one record per function.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct Rosetta {
pub meta: RosettaMeta,
pub functions: BTreeMap<String, FunctionRecord>,
/// Catalogued but not produced this build — no locator, so not a function record.
pub unresolved: BTreeMap<String, Unresolved>,
/// `None` on an offline build, serialized as an explicit `null`. See [`SchemaSection`].
pub schema: Option<SchemaSection>,
pub surfaces: Surfaces,
}
impl Rosetta {
/// The locators alone, at a confidence tier — what a framework's LOADER resolves through.
///
/// Drops entries live validation confidently rejected, the same rule the tiered catalogue applied:
/// a `validated: false` entry is one the running server disagreed with, and shipping it into a
/// loader would hand a consumer an address the deriver already knows is wrong.
pub fn gamedata(&self, select: TierSelect) -> Gamedata {
let keep = |t: Section| match select {
TierSelect::Core => t == Section::Core,
TierSelect::HighConfidence => t != Section::Experimental,
TierSelect::Experimental => true,
};
Gamedata {
entries: self
.functions
.iter()
.filter(|(_, r)| keep(r.tier) && r.validated != Some(false))
.map(|(n, r)| (n.clone(), r.locator.clone()))
.collect(),
game_key: self.meta.game_key.clone(),
}
}
/// The tiered catalogue view — the shape the CS# combined renderer works from, which needs the tiers
/// as separate sections in order to banner them differently.
pub fn to_monolith(&self) -> Monolith {
let mut m = Monolith {
meta: MonoMeta {
game_key: self.meta.game_key.clone(),
game: self.meta.game.clone(),
source_build: self.meta.source_build.clone(),
version: self.meta.version.clone(),
counts: self.meta.counts.clone(),
alias_groups: self.meta.alias_groups,
aliased_names: self.meta.aliased_names,
},
core: BTreeMap::new(),
high_confidence: BTreeMap::new(),
experimental: BTreeMap::new(),
unresolved: self.unresolved.clone(),
};
for (name, r) in &self.functions {
let section = match r.tier {
Section::Core => &mut m.core,
Section::HighConfidence => &mut m.high_confidence,
Section::Experimental => &mut m.experimental,
};
section.insert(
name.clone(),
MonoEntry {
locator: r.locator.clone(),
abi: r.measured.clone(),
provenance: r.provenance.clone(),
validated: r.validated,
aliases: r.aliases.clone(),
},
);
}
m
}
/// The declared prototypes, as the manifest the call-site emitters consume.
///
/// `tier` and `derived` are restored from the record, which is where the merge moved them — the
/// receiver test in `render::callable_shapes` reads the measured footprint, so a view that dropped
/// it would quietly emit fewer call sites than the data supports. `doc` is joined the same way, and
/// is what puts a sentence in a plugin author's editor tooltip rather than only in the artifact.
pub fn abi_manifest(&self) -> AbiManifest {
AbiManifest {
meta: AbiMeta {
game_key: self.meta.game_key.clone(),
source_build: self.meta.source_build.clone(),
counts: BTreeMap::new(),
},
functions: self
.functions
.iter()
.filter_map(|(n, r)| {
let p = r.prototype.as_ref()?;
Some((
n.clone(),
AbiEntry {
tier: r.tier.as_str().to_string(),
derived: r.measured.clone(),
doc: r.doc(),
..p.clone()
},
))
})
.collect(),
}
}
/// The VScript registry, whole: the members folded onto functions plus the ones that joined nowhere.
///
/// Both belong in a rendered API — a member Valve documents is part of the surface a script author
/// sees whether or not this build located its implementation.
///
/// A folded row also picks up its function's [`doc`](FunctionRecord::doc); an unjoined one does not,
/// and must not. Its C++ name may be a name another module's function also bears, so prose looked up
/// by that name would describe code this row is not — the same trap the merge itself refuses.
pub fn vscript(&self) -> Vec<VScriptBinding> {
let mut out: Vec<VScriptBinding> = self
.functions
.iter()
.flat_map(|(cpp, r)| {
r.bindings.iter().filter_map(move |b| match b {
FunctionBinding::Vscript {
script_name,
class,
description,
ret,
ret_raw,
} => Some(VScriptBinding {
name: script_name.clone(),
class: class.clone(),
cpp: cpp.clone(),
library: r
.locator
.signature
.as_ref()
.map(|s| s.library.clone())
.unwrap_or_default(),
description: description.clone().unwrap_or_default(),
ret: ret.clone(),
ret_raw: *ret_raw,
addr: r.provenance.addr.clone(),
vtable_slot: None,
doc: r.doc(),
}),
_ => None,
})
})
.collect();
out.extend(self.surfaces.unjoined.vscript.iter().cloned());
out
}
/// The typed schema as its own model — `None` on an offline build, where there is no schema to state.
pub fn typed_schema(&self) -> Option<Schema> {
let s = self.schema.as_ref()?;
Some(Schema {
meta: s.meta.clone().unwrap_or(SchemaMeta {
game_key: self.meta.game_key.clone(),
source_build: self.meta.source_build.clone(),
typed: 0,
untyped: 0,
enums: 0,
types: 0,
}),
classes: s.classes.clone(),
bases: s.bases.clone().unwrap_or_default(),
enums: s.enums.clone().unwrap_or_default(),
types: s.types.clone().unwrap_or_default(),
})
}
}
/// Fold the derivation's four outputs into one artifact.
///
/// A pure function of the models — it reads nothing from disk and infers nothing new, so every field in
/// the result is one a stage already produced. That is what makes the shape checkable against an
/// independent merge of the same inputs.
///
/// Joins are by NAME, and a record that finds no home is not silently dropped: an unjoinable VScript
/// row lands in [`Surfaces::unjoined`], so the merge is lossless: every declared row is either on the
/// function it describes or stated as a surface, and [`Joined`] counts which.
pub fn merge(
mono: Monolith,
abi: Option<AbiManifest>,
bindings: Option<Bindings>,
schema: Option<Schema>,
descriptions: BTreeMap<String, Description>,
) -> Rosetta {
let Monolith {
meta,
core,
high_confidence,
experimental,
unresolved,
} = mono;
let mut functions: BTreeMap<String, FunctionRecord> = BTreeMap::new();
for (tier, section) in [
(Section::Core, core),
(Section::HighConfidence, high_confidence),
(Section::Experimental, experimental),
] {
for (name, e) in section {
// Most-confident tier first, and FIRST WRITER WINS. The tiers are disjoint upstream, so this
// never fires — but if one ever did carry a name twice, keeping the first means a `core`
// function cannot be relabelled as an `experimental` guess by iteration order alone.
functions.entry(name).or_insert(FunctionRecord {
tier,
locator: e.locator,
measured: e.abi,
validated: e.validated,
aliases: e.aliases,
provenance: e.provenance,
prototype: None,
bindings: Vec::new(),
description: None,
});
}
}
let mut joined = Joined::default();
// The DECLARED prototype beside the MEASURED footprint: two different kinds of fact about one
// function, and the verdict on the first is reached against the second.
if let Some(abi) = abi {
for (name, row) in abi.functions {
if let Some(rec) = functions.get_mut(&name) {
rec.prototype = Some(row.into_record_prototype());
joined.prototypes += 1;
}
}
}
let mut surfaces = Surfaces::default();
if let Some(b) = bindings {
// A name is only unique WITHIN a module: `AddOutput` is registered in three libraries and
// `cl_particles_dumplist` in two, each a different function, while the catalogue holds one entry
// under that name. Attaching every registration to that one record would assert bindings that
// belong to code it does not locate — the bare-name trap, from the other direction. So a row is
// attached only when the record cannot contradict it: same library, or a record whose locator is
// a vtable slot and therefore names no library at all.
let joins = |rec: &FunctionRecord, lib: &str| {
rec.locator
.signature
.as_ref()
.is_none_or(|sig| sig.library == lib)
};
for r in b.entity_inputs {
let key = match &r.class {
Some(c) => format!("{c}::{}", r.handler),
None => r.handler.clone(),
};
match functions.get_mut(&key).filter(|rec| joins(rec, &r.library)) {
Some(rec) => {
rec.bindings.push(FunctionBinding::EntityInput {
input: r.input.clone(),
class: r.class.clone(),
});
joined.bindings.entity_input += 1;
}
None => surfaces.unjoined.entity_inputs.push(r),
}
}
for c in b.commands {
let key = format!("ConCommand::{}", c.name);
match functions.get_mut(&key).filter(|rec| joins(rec, &c.library)) {
Some(rec) => {
rec.bindings.push(FunctionBinding::Command {
command: c.name,
description: none_if_empty(c.description),
flags: (!c.flags.is_empty()).then_some(c.flags),
flags_raw: c.flags_raw,
callback_form: c.form,
});
joined.bindings.command += 1;
}
None => surfaces.unjoined.commands.push(c),
}
}
for v in b.vscript {
match functions
.get_mut(&v.cpp)
.filter(|rec| joins(rec, &v.library))
{
Some(rec) => {
rec.bindings.push(FunctionBinding::Vscript {
script_name: v.name,
class: v.class,
description: none_if_empty(v.description),
ret: v.ret,
ret_raw: v.ret_raw,
});
joined.bindings.vscript += 1;
}
None => surfaces.unjoined.vscript.push(v),
}
}
surfaces.pulse = b.pulse;
surfaces.entity_outputs = b.entity_outputs;
surfaces.entity_classes = b.entity_classes;
surfaces.convars = b.convars;
}
for (name, d) in descriptions {
if let Some(rec) = functions.get_mut(&name) {
rec.description = Some(d);
joined.descriptions += 1;
}
}
Rosetta {
meta: RosettaMeta {
game_key: meta.game_key,
game: meta.game,
source_build: meta.source_build,
version: meta.version,
counts: meta.counts,
alias_groups: meta.alias_groups,
aliased_names: meta.aliased_names,
merged: true,
joined,
},
functions,
unresolved,
schema: schema.map(SchemaSection::from),
surfaces,
}
}
/// An empty string is the artifact's way of saying a source supplied nothing; the merged record says so
/// with `null` instead, so a reader never has to know which spelling of absence a given surface used.
fn none_if_empty(s: String) -> Option<String> {
(!s.is_empty()).then_some(s)
}
#[cfg(test)]
mod merge_tests {
use super::*;
use serde_json::json;
/// Fixtures are built by DESERIALIZING the artifact shapes, so a test states what a reader sees on
/// disk rather than which constructor the deriver happened to use.
fn from<T: for<'de> serde::Deserialize<'de>>(v: serde_json::Value) -> T {
serde_json::from_value(v).expect("fixture parses as the artifact shape")
}
/// The keys of a serialized object, IN THE ORDER WRITTEN. `serde_json::Value` cannot answer this —
/// its map is key-sorted — and the order is part of what the artifact promises, so it is read back
/// off the text the way a consumer diffing two releases would see it.
fn field_order(json: &str) -> Vec<String> {
let (mut keys, mut depth, mut in_str, mut esc, mut cur) =
(Vec::new(), 0i32, false, false, String::new());
for c in json.chars() {
if in_str {
match c {
_ if esc => esc = false,
'\\' => esc = true,
'"' => in_str = false,
_ if depth == 1 => cur.push(c),
_ => {}
}
continue;
}
match c {
'"' => {
in_str = true;
cur.clear();
}
':' if depth == 1 && !cur.is_empty() => keys.push(std::mem::take(&mut cur)),
'{' | '[' => depth += 1,
'}' | ']' => depth -= 1,
_ => {}
}
}
keys
}
fn mono(entries: serde_json::Value) -> Monolith {
from(json!({
"meta": { "game_key": "csgo", "game": "CS2", "source_build": "b", "version": "cs2-1-0",
"counts": { "core": 1, "high_confidence": 1, "experimental": 0, "unresolved": 0 } },
"core": entries,
"high_confidence": {}, "experimental": {}, "unresolved": {},
}))
}
#[test]
fn merge_folds_every_stage_onto_one_record() {
let m = mono(json!({
"ConCommand::bot_add": {
"signature": { "library": "server", "linux": "55 48" },
"abi": { "int": 2, "float": 0, "ret": "ret=int" },
"provenance": { "tier": "valve-table" },
"validated": true,
}
}));
let abi: AbiManifest = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "counts": {} },
"functions": { "ConCommand::bot_add": {
"tier": "core", "matched_by": "engine-contract", "status": "verified",
"params": ["CCommandContext*"], "ret": "void" } },
}));
let bindings: Bindings = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "pulse": 0, "entity_inputs": 0 },
"pulse": {},
"entity_inputs": [],
"commands": [{ "name": "bot_add", "library": "server", "description": "adds a bot",
"flags": ["release"], "flags_raw": "0x4", "form": "direct",
"addr": "0x1" }],
}));
let desc: BTreeMap<String, Description> = from(json!({
"ConCommand::bot_add": { "text": "Adds a bot.", "source": "generated" }
}));
let r = merge(m, Some(abi), Some(bindings), None, desc);
assert_eq!(r.meta.joined.prototypes, 1);
assert_eq!(r.meta.joined.bindings.command, 1);
assert_eq!(r.meta.joined.descriptions, 1);
// The locator stays flattened, and every other stage is a named field beside it — which is the
// whole shape claim: one record, four kinds of fact, each labelled by where it came from.
let rec_json = serde_json::to_string(&r.functions["ConCommand::bot_add"]).unwrap();
assert_eq!(
field_order(&rec_json),
[
"tier",
"signature",
"measured",
"validated",
"provenance",
"prototype",
"bindings",
"description"
]
);
let v = serde_json::to_value(&r).unwrap();
let rec = &v["functions"]["ConCommand::bot_add"];
assert_eq!(rec["tier"], "core");
assert_eq!(rec["measured"]["int"], 2);
assert_eq!(rec["prototype"]["status"], "verified");
assert_eq!(rec["bindings"][0]["kind"], "command");
assert_eq!(rec["bindings"][0]["command"], "bot_add");
// the prototype sheds what the record already says
assert!(rec["prototype"].get("tier").is_none());
assert!(rec["prototype"].get("derived").is_none());
assert_eq!(rec["description"]["source"], "generated");
assert!(v["schema"].is_null()); // offline: an explicit null, never an absent key
}
#[test]
fn a_source_that_supplied_nothing_reads_as_null_not_as_empty() {
let m = mono(json!({ "ConCommand::x": { "offset": 3, "provenance": { "tier": "core" } } }));
let bindings: Bindings = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "pulse": 0, "entity_inputs": 0 },
"pulse": {}, "entity_inputs": [],
"commands": [{ "name": "x", "library": "server", "flags_raw": "0x0", "form": "direct",
"addr": "0x1" }],
}));
let v =
serde_json::to_value(merge(m, None, Some(bindings), None, BTreeMap::new())).unwrap();
let b = &v["functions"]["ConCommand::x"]["bindings"][0];
assert!(b["description"].is_null());
assert!(b["flags"].is_null());
assert_eq!(b["flags_raw"], "0x0");
}
#[test]
fn a_binding_from_another_library_is_not_asserted_onto_this_function() {
// One name, three registrations, three different functions — the catalogue holds the `server`
// one. The other two describe code this build does not locate, so they must not become claims
// about the function it does.
let m = mono(json!({ "AddOutput": {
"signature": { "library": "server", "linux": "55" },
"provenance": { "tier": "core" } } }));
let row = |lib: &str| {
json!({ "name": "AddOutput", "cpp": "AddOutput", "class": "CNativeOutputs",
"library": lib, "ret_raw": 0 })
};
let bindings: Bindings = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "pulse": 0, "entity_inputs": 0 },
"pulse": {}, "entity_inputs": [],
"vscript": [row("server"), row("engine2"), row("worldrenderer")],
}));
let r = merge(m, None, Some(bindings), None, BTreeMap::new());
assert_eq!(r.meta.joined.bindings.vscript, 1);
assert_eq!(r.functions["AddOutput"].bindings.len(), 1);
assert_eq!(r.surfaces.unjoined.vscript.len(), 2);
}
#[test]
fn the_views_hand_each_emitter_what_it_reads() {
let mut m = mono(json!({
"A::keep": { "signature": { "library": "server", "linux": "55" },
"abi": { "int": 2, "float": 0, "ret": "ret=int" },
"provenance": { "tier": "core" }, "validated": true },
"A::rejected": { "offset": 9, "provenance": { "tier": "core" }, "validated": false },
}));
// a guess, which `core` must not include
m.experimental.insert(
"A::guess".into(),
from(json!({ "offset": 4, "provenance": { "tier": "low" }, "validated": null })),
);
let abi: AbiManifest = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "counts": {} },
"functions": { "A::keep": { "tier": "core", "matched_by": "exact", "status": "verified",
"params": ["int"] } },
}));
let r = merge(m, Some(abi), None, None, BTreeMap::new());
// the locator half: tier-filtered, and an entry live validation rejected is not a locator
let core = r.gamedata(TierSelect::Core);
assert_eq!(core.entries.keys().collect::<Vec<_>>(), ["A::keep"]);
assert_eq!(
r.gamedata(TierSelect::Experimental).entries.len(),
2 // keep + guess; the rejected one stays out at every tier
);
// the prototype half: the two fields the merge moved onto the record are restored, because the
// receiver test in `render::callable_shapes` reads the measurement
let man = r.abi_manifest();
let e = &man.functions["A::keep"];
assert_eq!(e.tier, "core");
assert_eq!(e.derived.as_ref().map(|d| d.int), Some(2));
assert_eq!(man.meta.game_key, "csgo");
}
#[test]
fn the_script_api_view_carries_the_members_that_joined_and_the_ones_that_did_not() {
let m = mono(
json!({ "Script_Kill": { "signature": { "library": "server", "linux": "55" },
"provenance": { "tier": "core", "addr": "0x1" } } }),
);
let bindings: Bindings = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "pulse": 0, "entity_inputs": 0 },
"pulse": {}, "entity_inputs": [],
"vscript": [
{ "name": "Kill", "cpp": "Script_Kill", "class": "CBaseEntity", "library": "server",
"description": "Kills it", "ret": "void", "ret_raw": 0 },
{ "name": "Gone", "cpp": "Script_Gone", "class": "CBaseEntity", "library": "server",
"ret_raw": 0 },
],
}));
let r = merge(m, None, Some(bindings), None, BTreeMap::new());
let vs = r.vscript();
assert_eq!(vs.len(), 2); // one on its function, one unjoined — both are surface a script sees
let joined = vs.iter().find(|v| v.cpp == "Script_Kill").unwrap();
assert_eq!(joined.name, "Kill");
assert_eq!(joined.description, "Kills it");
assert_eq!(joined.library, "server"); // taken from the record's own locator
assert!(vs.iter().any(|v| v.cpp == "Script_Gone"));
assert!(r.typed_schema().is_none()); // offline: nothing to render a schema from
}
#[test]
fn valves_own_text_always_wins_and_a_generated_one_only_fills_a_gap() {
let vs = |cpp: &str, desc: &str| {
json!({ "name": "N", "cpp": cpp, "class": "C", "library": "server",
"description": desc, "ret_raw": 0 })
};
let m = mono(json!({
"ConCommand::documented": { "offset": 1, "provenance": { "tier": "core" } },
"ConCommand::help_only": { "offset": 2, "provenance": { "tier": "core" } },
"ConCommand::ours": { "offset": 3, "provenance": { "tier": "core" } },
"ConCommand::silent": { "offset": 4, "provenance": { "tier": "core" } },
}));
let bindings: Bindings = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "pulse": 0, "entity_inputs": 0 },
"pulse": {}, "entity_inputs": [],
// Both registries describe the first one. A console help string documents the COMMAND an
// operator types; the script registry documents the FUNCTION, so it is the one that wins.
"commands": [
{ "name": "documented", "library": "server", "flags_raw": "0x0", "form": "direct",
"addr": "0x1", "description": "type `documented 1` to do the thing" },
{ "name": "help_only", "library": "server", "flags_raw": "0x0", "form": "direct",
"addr": "0x2", "description": "Valve's help text" },
],
"vscript": [
// The first binding carries nothing: an empty registration has said nothing, so the
// search must fall THROUGH it rather than stop on a blank.
vs("ConCommand::documented", ""),
vs("ConCommand::documented", "Valve's script prose"),
],
}));
let desc: BTreeMap<String, Description> = from(json!({
"ConCommand::documented": { "text": "ours, and outranked", "source": "generated" },
"ConCommand::help_only": { "text": "ours, and outranked", "source": "generated" },
"ConCommand::ours": { "text": "a\nreading\tof this build", "source": "generated" },
}));
let r = merge(m, None, Some(bindings), None, desc);
let doc = |n: &str| r.functions[n].doc();
let d = doc("ConCommand::documented").unwrap();
assert_eq!(d.text, "Valve's script prose");
assert_eq!(d.source, Doc::VALVE);
let d = doc("ConCommand::help_only").unwrap();
assert_eq!(d.text, "Valve's help text");
assert_eq!(d.source, Doc::VALVE);
// Ours fills a gap, keeps its own source id, and arrives as ONE line whatever it was authored
// as — every target embeds it in a comment, and two of the three end at a newline.
let d = doc("ConCommand::ours").unwrap();
assert_eq!(d.text, "a reading of this build");
assert_eq!(d.source, "generated");
// Nothing describes it, which is the majority case: an emitter renders it as it always did.
assert!(doc("ConCommand::silent").is_none());
}
#[test]
fn prose_reaches_the_emitters_by_the_record_it_belongs_to_never_by_its_name() {
// The same trap the merge itself refuses, one layer up: an UNJOINED row bears a name that
// belongs to another module's function, so a view that looked prose up by name would hand it a
// sentence about code it is not.
let m = mono(
json!({ "GetName": { "signature": { "library": "server", "linux": "55" },
"provenance": { "tier": "core", "addr": "0x1" } } }),
);
let bindings: Bindings = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "pulse": 0, "entity_inputs": 0 },
"pulse": {}, "entity_inputs": [],
"vscript": [
{ "name": "GetName", "cpp": "GetName", "class": "C", "library": "server",
"ret_raw": 0 },
{ "name": "GetName", "cpp": "GetName", "class": "C", "library": "engine2",
"ret_raw": 0 },
],
}));
let desc: BTreeMap<String, Description> = from(json!({
"GetName": { "text": "the server one", "source": "generated" }
}));
let r = merge(m, None, Some(bindings), None, desc);
let vs = r.vscript();
let joined = vs.iter().find(|v| v.library == "server").unwrap();
assert_eq!(
joined.doc.as_ref().map(|d| d.text.as_str()),
Some("the server one")
);
let elsewhere = vs.iter().find(|v| v.library == "engine2").unwrap();
assert!(elsewhere.doc.is_none());
// The prototype view has no such hazard — it is keyed by the record — so it carries the prose.
let m2 = mono(json!({ "A::k": { "offset": 1, "provenance": { "tier": "core" } } }));
let abi: AbiManifest = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "counts": {} },
"functions": { "A::k": { "tier": "core", "matched_by": "exact", "status": "verified" } },
}));
let desc2: BTreeMap<String, Description> =
from(json!({ "A::k": { "text": "t", "source": "derived" } }));
let man = merge(m2, Some(abi), None, None, desc2).abi_manifest();
assert_eq!(
man.functions["A::k"]
.doc
.as_ref()
.map(|d| d.source.as_str()),
Some("derived")
);
}
#[test]
fn the_resolved_prose_is_a_view_and_never_reaches_the_artifact() {
// `doc` is joined at view time from facts the artifact already states. Serializing it would
// give one sentence two homes, and two homes is how they come to disagree.
let m = mono(json!({ "A::k": { "offset": 1, "provenance": { "tier": "core" } } }));
let abi: AbiManifest = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "counts": {} },
"functions": { "A::k": { "tier": "core", "matched_by": "exact", "status": "verified" } },
}));
let desc: BTreeMap<String, Description> =
from(json!({ "A::k": { "text": "t", "source": "generated" } }));
let r = merge(m, Some(abi), None, None, desc);
let v = serde_json::to_value(&r).unwrap();
assert!(v["functions"]["A::k"]["prototype"].get("doc").is_none());
assert_eq!(v["functions"]["A::k"]["description"]["text"], "t");
// and the view still produces it from what WAS written
let back: Rosetta = serde_json::from_value(v).unwrap();
assert_eq!(back.abi_manifest().functions["A::k"].doc.is_some(), true);
}
#[test]
fn every_declared_row_lands_exactly_once() {
// The merge must not be a filter: a row either describes a function this build ships, or it is
// stated as a surface. Nothing the deriver read may fall out between the two.
let m = mono(
json!({ "ConCommand::a": { "signature": { "library": "server", "linux": "55" },
"provenance": { "tier": "core" } } }),
);
let bindings: Bindings = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "pulse": 0, "entity_inputs": 0 },
"pulse": {},
"entity_inputs": [{ "input": "Kill", "handler": "nosuchfunction", "library": "server",
"addr": "0x1" }],
"commands": [
{ "name": "a", "library": "server", "flags_raw": "0x0", "form": "direct", "addr": "0x1" },
{ "name": "a", "library": "engine2", "flags_raw": "0x0", "form": "direct", "addr": "0x2" },
{ "name": "b", "library": "server", "flags_raw": "0x0", "form": "direct", "addr": "0x3" },
],
"vscript": [{ "name": "K", "cpp": "nope", "library": "server", "ret_raw": 0 }],
}));
let r = merge(m, None, Some(bindings), None, BTreeMap::new());
let (j, u) = (&r.meta.joined.bindings, &r.surfaces.unjoined);
assert_eq!((j.entity_input, u.entity_inputs.len()), (0, 1));
assert_eq!((j.command, u.commands.len()), (1, 2)); // one joined; the other library's + the unknown
assert_eq!((j.vscript, u.vscript.len()), (0, 1));
}
#[test]
fn a_vtable_located_record_cannot_contradict_a_library_so_it_keeps_the_binding() {
// A slot names no library, so there is nothing to check the row against — and refusing on
// absent evidence would drop bindings for every offset-located function.
let m = mono(json!({ "A::b": { "offset": 3, "provenance": { "tier": "core" } } }));
let bindings: Bindings = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "pulse": 0, "entity_inputs": 0 },
"pulse": {},
"entity_inputs": [{ "input": "Kill", "class": "A", "handler": "b",
"library": "engine2", "addr": "0x1" }],
}));
let r = merge(m, None, Some(bindings), None, BTreeMap::new());
assert_eq!(r.functions["A::b"].bindings.len(), 1);
}
#[test]
fn a_binding_with_no_function_record_survives_as_a_surface() {
let m = mono(json!({ "A::b": { "offset": 3, "provenance": { "tier": "core" } } }));
let bindings: Bindings = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "pulse": 0, "entity_inputs": 0 },
"pulse": {}, "entity_inputs": [],
"vscript": [{ "name": "Kill", "cpp": "Script_Kill", "library": "server", "ret_raw": 0 }],
}));
let r = merge(m, None, Some(bindings), None, BTreeMap::new());
assert_eq!(r.meta.joined.bindings.vscript, 0);
assert_eq!(r.surfaces.unjoined.vscript.len(), 1);
assert_eq!(r.surfaces.unjoined.vscript[0].cpp, "Script_Kill");
}
#[test]
fn the_artifact_reads_back_as_what_was_written() {
let m = mono(json!({ "A::b": {
"signature": { "library": "server", "linux": "55" },
"provenance": { "tier": "core" }, "aliases": ["UTIL::b"] } }));
let bindings: Bindings = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "pulse": 0, "entity_inputs": 0 },
"pulse": {},
"entity_inputs": [{ "input": "Kill", "class": "A", "handler": "b", "library": "server",
"addr": "0x1" }],
}));
let schema: Schema = from(json!({
"meta": { "game_key": "csgo", "source_build": "b", "typed": 1, "untyped": 0 },
"classes": { "A": { "m_i": { "offset": 4, "size": 4, "name_hash": 7 } } },
}));
let r = merge(m, None, Some(bindings), Some(schema), BTreeMap::new());
let back: Rosetta = serde_json::from_str(&serde_json::to_string(&r).unwrap()).unwrap();
assert_eq!(back.functions["A::b"].tier, Section::Core);
assert_eq!(back.functions["A::b"].aliases, ["UTIL::b"]);
assert!(matches!(
back.functions["A::b"].bindings[..],
[FunctionBinding::EntityInput { .. }]
));
assert_eq!(back.schema.unwrap().classes["A"]["m_i"].offset, 4);
}
}
#[cfg(test)]
mod monolith_tests {
use super::*;
#[test]
fn mono_entry_flattens_locator_and_kebabs_tier() {
let e = MonoEntry {
locator: Entry {
signature: None,
offset: Some(158),
class: None,
anchors: Vec::new(),
},
abi: None,
provenance: Provenance {
source: Some("catalogue".into()),
..Provenance::with_tier(Tier::Core)
},
validated: Some(true),
aliases: Vec::new(),
};
let v = serde_json::to_value(&e).unwrap();
assert_eq!(v["offset"], 158); // locator flattened to the top level
assert!(v.get("signature").is_none()); // None locator field omitted
assert_eq!(v["provenance"]["tier"], "core"); // kebab-case enum
assert_eq!(v["provenance"]["source"], "catalogue");
assert!(v["provenance"].get("confidence").is_none()); // None provenance field skipped
assert_eq!(v["validated"], true);
}
#[test]
fn experimental_entry_keeps_class_and_serializes_null_validated() {
let e = MonoEntry {
locator: Entry {
signature: None,
offset: Some(40),
class: Some("CFoo".into()),
anchors: Vec::new(),
},
abi: None,
provenance: Provenance {
confidence: Some("low".into()),
self_named: Some(false),
collision: Some(true),
dead_weight: Some(false),
..Provenance::with_tier(Tier::Low)
},
validated: None,
aliases: Vec::new(),
};
let v = serde_json::to_value(&e).unwrap();
assert_eq!(v["class"], "CFoo");
assert_eq!(v["provenance"]["tier"], "low");
assert_eq!(v["provenance"]["collision"], true);
assert_eq!(v["validated"], serde_json::Value::Null); // present as null, not omitted
}
#[test]
fn monolith_round_trips() {
let mut m = Monolith {
meta: MonoMeta {
game_key: "csgo".into(),
game: "CS2".into(),
source_build: "2026-07-15_003539".into(),
version: "cs2-12345-0".into(),
counts: Counts {
core: 1,
high_confidence: 0,
experimental: 0,
unresolved: 1,
},
alias_groups: 0,
aliased_names: 0,
},
core: BTreeMap::new(),
high_confidence: BTreeMap::new(),
experimental: BTreeMap::new(),
unresolved: BTreeMap::new(),
};
m.core.insert(
"A::b".into(),
MonoEntry {
locator: Entry {
signature: Some(Sig {
library: "server".into(),
linux: "55 48 89 E5".into(),
}),
offset: None,
class: None,
anchors: Vec::new(),
},
abi: None,
provenance: Provenance {
source: Some("catalogue".into()),
..Provenance::with_tier(Tier::Core)
},
validated: Some(true),
aliases: Vec::new(),
},
);
m.unresolved.insert(
"C::d".into(),
Unresolved {
reason: "sig-drifted".into(),
detail: "no unique/recovered signature in target".into(),
},
);
let s = serde_json::to_string_pretty(&m).unwrap();
let back: Monolith = serde_json::from_str(&s).unwrap();
assert_eq!(back.core.len(), 1);
assert_eq!(
back.core["A::b"]
.locator
.signature
.as_ref()
.unwrap()
.library,
"server"
);
assert_eq!(back.unresolved["C::d"].reason, "sig-drifted");
assert_eq!(back.meta.counts.unresolved, 1);
}
}
Reference in a new issue View git blame Copy permalink