Architecture: Stochastic Loot Engine

Architecture: Stochastic Loot Engine

Component Decomposition

The system is organized into three layers with a cross-cutting vocabulary and algebraic law specification.

Domain Layer

Responsible for core type definitions, smart constructors, and invariant enforcement.

Component	Source File	Responsibility
Skill Primitive	skill.py	Unified skill type with triggers, conditions, effects, tags, modifiers, charge cost, cooldown, and stack behavior. Immutable Pydantic model.
Item Template	item_template.py	Parameterized schema for item generation: class affinity, modifier slots, granted skills, rarity floor, covariance matrix.
Charge System	charge.py	Universal resource primitive: pool formula, replenishment model, deficit state transitions.
Condition Temporality	condition.py	Three-class condition taxonomy with evaluator registry pattern. Discriminated union of spatial, decaying, and accumulating conditions.
Ascender	ascender.py	MVP character model that holds a loadout and charge state.
Vocabulary	vocabulary.py	Event-token registry and the closed damage-type registry (DamageType/DAMAGE_TYPES); producible-state and ambient-state tables live in verification.py.

Generation Layer

Responsible for procedural item generation and runtime instance rolling.

Component	Source File	Responsibility
Template Generator	template_generator.py	Schema-driven template generation with class affinity and modifier covariance.
Item Instance	item_instance.py	Runtime rarity tier rolling, Beta-distribution sampling, and modifier value mapping.

Verification Layer

Responsible for loadout verification across three layers: static, compositional, and stochastic.

Component	Source File	Responsibility
Loadout	loadout.py	Loadout assembly and the effective skill/roll mapping.
Trigger Graph	graph_builder.py	Directed multigraph G(L) over skill instances, built by effect→trigger matching.
Cycle Detector	cycle_detector.py	DFS elementary-cycle detection, dedup, and rolled-value-aware supercriticality classification.
Combo Surface	combo_surface.py	Cross-pathway boundary analysis: flags G(L) edges crossing restricted pathway pairs; Layer II opt-in via skill_pathways.
Verification	verification.py	Layer II orchestration: reachability, condition satisfiability, sustainability, and the report.

Cross-Cutting Concerns

Component	Source File	Responsibility
Modifier Aggregation	aggregation.py	Two-layer aggregation pipeline: additive sum then multiplicative product. Enforces cross-layer ordering law.

Dependency Relationships

Vocabulary
    |
    +---> Skill
    |       |
    |       +---> ItemTemplate (granted skills)
    |       |
    |       +---> Condition (evaluates skill conditions)
    |       |
    |       +---> Aggregation (modifier layers)
    |       |
    |       +---> Charge (costs and recovery)
    |
    +---> ItemTemplate
    |       |
    |       +---> TemplateGenerator
    |       |
    |       +---> ItemInstance (rolls from template)
    |
    +---> Loadout
            |
            +---> TriggerGraph (builds from loadout skills)
            |       |
            |       +---> ComboSurface (cross-pathway edge check, opt-in)
            |
            +---> Charge (sustainability ratio)

Key Dependencies

• Skill depends on Vocabulary (trigger tokens, effect emissions), Condition (condition evaluation), Charge (cost semantics), and Aggregation (modifier layers).
• ItemTemplate depends on Skill (granted skills) and Vocabulary (class affinity tokens).
• TemplateGenerator depends on ItemTemplate (produces templates) and Vocabulary (schema constraints).
• ItemInstance depends on ItemTemplate (rolls from template parameters) and Charge (rarity-driven cost scaling).
• Loadout depends on Skill (assembles instances), ItemInstance (equipped items), and Charge (pool and recovery).
• TriggerGraph depends on Loadout (constructs from assembled skills) and Condition (edge predicate satisfiability).
• ComboSurface depends on TriggerGraph (scans its edges against restricted pathway pairs); Layer II verification invokes it opt-in via the external skill_pathways mapping (by convention Ascender.build_skill_pathways(), whose positional keys are the node ids), since pathway provenance (e.g. CLASS_SKILL vs INTRINSIC) is unrecoverable from the Loadout alone — pathway fields on Skill are forbidden by contract.
• Aggregation depends on Skill (reads modifier declarations) and is used by Loadout (computes effective modifiers).

Interface Contracts

Skill Production Rule

A skill is expressed as: WHEN <Trigger> IF <Condition> DO <Effect> TAGGED <TagSet>. The interface between Skill and TriggerGraph is the trigger-emission vocabulary: every effect that emits a trigger must use a token declared in Vocabulary.

Modifier Slot Interface

ItemTemplate declares modifier slots as ordered tuples of (ModifierType, LayerDeclaration, SupportRange). The aggregation pipeline receives a flat list of modifiers from the loadout and must group by layer before applying the two-layer operation.

Condition Evaluator Registry

Condition temporality classes plug into the evaluation system via a register_evaluator() registry. New condition types require: a discriminator value in the Pydantic discriminated union, an evaluator function satisfying the ConditionEvaluator Protocol, and registration at module load time.

LoadoutReport Schema

The verification pipeline produces a typed report with fields: loadout_id, outlier_class, outlier_probability, expected_margin, deficit_death_prob, dominant_cycle, sparsity_compliant, and warnings. This is the primary output interface of the verification layer, implemented in report.py as a projection of CompositionalReport + StochasticReport. The event-sourced pipeline (pipeline.py) emits the six-event sequence (TemplateRegistered → LoadoutAssembled → GraphConstructed → CyclesDetected → StochasticSampleCompleted → ReportFinalized) and finalizes this report; the deterministic fold makes any event prefix a replayable checkpoint. deficit_death_prob is a placeholder clamp(1 − η, 0, 1) pending empirical calibration.

Related architecture documents

• Verification layers — the three-layer static / compositional / stochastic verification stack.
• Gain and cost model — the concrete gain(C, v) / cost(C) model and the locally bounded restatement of Law 8.
• Layer III sample complexity — sample-size and confidence-interval guarantees for the stochastic verifier, with the importance-sampling variance-reduction regime.