A timestamp is the time an object returns at which it will change states. These are normally measured in seconds from midnight GMT of January 1, 1970.
Positive timestamps, or "hard events", will "drive" the simulation, causing it to continue executing. As long as there is a non-negative, non-TS_NEVER timestamp returned from at least one object, the simulation will continue.
Negative timestamps, or "soft events", are still indicative of an object's state change, but is one that will not drive the simulation, that will allow the simulation to end with an answer even if there are more possible events. The Residential/Water_heater : water heater is a good example, as it will continue heating up and cooling off endlessly, whether or not we are interested in its constant march.
Three special timestamps exist. "TS_NEVER" indicates that an object will not change by the time the simulation stops. "TS_INIT" is synonymous with the starting time of the simulation. "TS_INVALID" indicates that the simulation has reached an invalid state and its contents are sufficiently arbitrary as to be useless and unrecoverable.
If an object returns a timestamp that is prior to the current clock time, the simulation will report as much and exit ungracefully.
If an object returns a timestamp equal to the current clock time, it is asking the core to iterate on the current time, in order to facilitate iterative solvers. Objects should be able to recognize when this happens and either calculate accordingly or carry the previous solution forward.