King Klown Logo
King Klown& KOA
Back to VM-ENGINE Overview

Technical Specifications

The machine operates on a strict set of normative documents (Docs 1–7). Below is the condensed engineering reference for the Data Model, Algorithm, and Pipeline.

1. Canonical Data Model

Inputs (Consumed)

  • DivisionRegistry: The stable universe of units and options. Defines the deterministic order_index for every option.
  • BallotTally: Votes per unit/option. Must referentially align with the Registry.
  • ParameterSet: The configuration map. Must explicitly set all Included VM-VARs (outcome-affecting variables).

Outputs (Produced)

  • Result: The canonical outcome. Contains allocations, aggregates, and the formula_id (FID).
  • RunRecord: The cryptographic audit trail. Contains input hashes, engine version, effective variables, and the TieLog.
  • FrontierMap (Optional): Per-unit diagnostics for the frontier gating model (if enabled).

2. Algorithmic Step Order

The engine must execute stages in this exact order to guarantee determinism. Ordering of units is always by ascending unit_id.

S0

Normalize & Seed

Canonicalize inputs. Bind algorithm family constants. Initialize RNG seed (no draws yet).

S1

Per-Unit Tallies

Load votes. Compute raw shares and base metrics required for gating.

S2

Gates (Sanity/Eligibility)

Apply Doc 4B gates. If a unit fails, mark Invalid and skip allocation. Record reasons.

S3

Frontier Hook

If enabled (VM-VAR-040), apply band/cut logic. Emit diagnostics to FrontierMap.

S4

Core Allocation

Compute allocations using the Algorithm Family rules (001-007). Deterministic; no RNG.

S5

Tie Resolution

If ties exist: Apply policy (050). If 'random', consume exactly k draws from RNG (052) and log event.

S6

Emit Artifacts

Build canonical Result and RunRecord. Compute FID. Self-verify all hashes before exit.

3. Gates & Edge Cases

Before allocation, every unit must pass a series of Gates. If any gate fails, the unit is marked Invalid, receives no allocation, and the reason is recorded in the RunRecord.

  • Sanity Gates: Data plausibility (e.g., votes ≤ ballots).
  • Eligibility Gates: Minimum turnout or share thresholds.
  • Validity Gates: Integrity floors (VM-VAR-031).

The "Invalid" State

There is no "provisional" allocation. A unit is either Valid or Invalid.

{ "unit_id": "U-001", "label": "Invalid", "allocations": [], "reasons": ["VM-VAR-020:min_turnout"] }

4. Pipeline Contracts

Exit Code 2Validation Error

Input schema violation, referential integrity failure, or ordering precondition unmet.

Exit Code 3Verification Failure

Post-run self-check failed. The computed hash of an artifact does not match its embedded ID.

Exit Code 5Spec Violation

Internal determinism breach (e.g., RNG used when policy is not 'random').