# Time Model and Cycles Domain: machine timing and cycles Function: normative Didactic companion: [`../learn/mental-model-time-and-cycles.md`](../../../discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md) ## 1 Scope This chapter defines the temporal contract of the PROMETEU machine. It covers: - machine base clock; - logical frame structure; - cycle accounting; - per-frame budget; - CAP interaction with time measurement. ## 2 System Base Clock Administrative UTC timestamps use the separate [host wall clock](11-portability-and-cross-platform-execution.md#41-administrative-host-wall-clock). Civil clock adjustments do not change logical time or cycle accounting. Host timeouts use monotonic elapsed time, independent of that adjustable civil clock. PROMETEU operates with a fixed **60 Hz** logical clock. This means: - 60 iterations of the machine loop per second; - each iteration corresponds to one logical frame; - the logical clock is stable regardless of host platform. ## 3 Logical Frame A PROMETEU frame represents a complete unit of machine execution. Conceptual stage order: ```text FRAME N INPUT UPDATE DRAW AUDIO SYNC ``` The machine guarantees: - fixed stage order; - deterministic repetition; - no implicit extra frames between logical frame boundaries. ## 4 PROMETEU Cycles ### 4.1 Definition A **PROMETEU cycle** is the abstract unit used to measure execution cost inside the machine. - VM instructions consume documented cycle cost; - peripheral operations also consume cycle cost; - cycle cost is independent of host wall-clock timing. ### 4.2 Properties Cycles are: - countable; - comparable; - stable across supported hosts; - suitable for certification and profiling. ## 5 Per-Frame Budget Each frame has a maximum cycle budget. This budget: - is reset every frame; - does not accumulate unused cycles; - represents the capacity of the virtual execution envelope for that frame. ### 5.1 Conceptual Example ```text Frame Budget: 10,000 cycles Used: - Update logic: 4,200 - Draw calls: 3,100 - Audio: 900 Remaining: 1,800 cycles ``` ## 6 Work Distribution Over Time PROMETEU does not require all logic to run every frame. Machine-visible work may be distributed over time, for example: - enemy logic every 2 frames; - pathfinding every 4 frames; - timers based on frame count; - subsystem-specific update cadence. Such distribution changes cycle pressure and is part of the observable execution model. ## 7 CAP Interaction The **CAP** defines contextual technical limits such as: - maximum cycle budget per frame; - memory limits; - peripheral call limits. ### 7.1 CAP Does Not Block Execution Fundamental rules: - the game always runs; - the game can always be packaged; - the game can always be played. CAP does not prevent execution. ### 7.2 CAP Generates Evidence When CAP is active, PROMETEU measures and records: - average cycle usage per frame; - cycle peaks; - problematic frames; - cost distribution. These data feed certification artifacts without changing cartridge semantics. ## 8 Time-Based Certification PROMETEU certification may analyze: - average cycle usage per frame; - maximum peaks; - problematic frames; - dominant cost sources. ### 8.1 Conceptual Example ```text Target CAP: PROMETEU-LITE Frame Budget: 5,000 cycles Frame 18231: Used: 5,612 cycles Primary cause: enemy.updateAI(): 1,012 cycles ``` ## Program Registry integration The [Dynamic/reference instruction table](02c-program-registry-and-pbx-v0.md#dynamic-and-reference-instructions) specifies fixed costs of 8/4/3/4/4/5/4 cycles for opcodes 0x0090–0x0096. Each decoded attempt charges once, including a trap. Input retains the existing one-cycle INTRINSIC rule. Load work quotas are deterministic analysis units, not execution cycles or a wall-clock timeout. ## Collection Attempt Charging The [collection ISA table](02-vm-instruction-set.md#typed-collection-instructions) defines complete costs. Metadata widths determine costs independently of native sizeof, allocator, timing, optimizer and GC. Each decoded collection attempt is charged exactly once before validation/refusal. Fixed costs apply even to underflow, invalid receiver, bounds and rejected value groups. ARRAY_NEW charges 8 + N*w(E) whenever an available exact Int64 length is in 0..u32::MAX, including quota/allocation refusal; absent, wrong-carrier, negative or above-u32 length charges eight. Rejected loads execute and charge no guest instruction. ARRAY_COPY charges C=4+2*N*W when all five temporary operands are available and count is exact Int64 in 0..u32::MAX. W comes from immutable Registry element storage. Charge C before receiver/range/group validation and scratch reservation, retaining it on refusal. Otherwise charge base 4 and preserve ordinary fault precedence. Checked cost overflow charges base 4 and traps SizeOverflow before ordinary validation. Never inspect frame locals as missing operands. Empty copies still validate and cost 4; identity/overlap give no discount. Ten one-slot elements cost 24 on success, invalid receiver/range or scratch refusal. Full validation order is defined in the [copy contract](02-vm-instruction-set.md#typed-array-range-copy). Examples: empty Struct/Array costs eight; a Struct containing Int32, vec2 and Trait costs thirteen; ten vec2 elements cost twenty-eight even on quota refusal; pixel GET costs six including bounds failure; pixel SET costs seven including group rejection; LEN costs three including receiver failure. Charged cycles are never refunded by rollback. Budget admission remains between instructions. Zero executes nothing. A positive remaining budget admits the entire next instruction, which may overshoot; continuation then returns BudgetExhausted before the following instruction. Thus ARRAY_NEW of ten vec2 under run_budget(1) consumes twenty-eight cycles. Trap takes priority on refusal, with the same cycle delta and no successful target step. steps_executed counts only successful steps; cycles_used includes failed attempts. Collection operations add no implicit frame sync, tick, GC or coroutine switch, no extra length cap and no cycle pre-admission rule. ## Typed Callable Costs Charge each admitted attempt once, including trap: MAKE_CLOSURE 8+C (declared capture-slot sum), CALL_CLOSURE 6, GET_CAPTURE 2+W (selected complete-group width), CALL_TRAIT 6. Direct CALL/RET retain 5/4. No extra callback budget, partial-instruction pause or GC-cycle redesign. Zero budget executes nothing; positive budget may admit an instruction that overshoots. Root-return GC does not grant cycles, advance frames or invoke guest cleanup. ## Mathematical intrinsic attempts The [numeric contract](02d-gameplay-math-and-numeric-semantics.md) publishes fixed total call costs: min/max/abs/conversions 2, clamp and rounding 4, vec2.dot 10, sqrt 16, sin/cos 32, vec2.length 40, atan2 48. Charge known mathematical attempts before checks and scratch reservations, including failure, exactly once without an extra generic INTRINSIC cycle. Zero budget begins no attempt; positive budget admits the complete operation and retains the existing overshoot rule. Argument-producing bytecode costs remain additional. Input/color and other intrinsic/opcode costs and accounting remain unchanged. CPU timings never change guest-visible cycle weights. ## Random core integration The [random core](02e-vm-owned-random-core.md) charges fixed calls before checks and bounded range calls as 4+8*N (at most 64 draws), retaining fault cycles and whole-instruction overshoot. ## Identity and hash attempts The [identity/hash contract](02f-vm-identity-and-value-hashing.md) charges 8+w(T) for reference hash, 4+w(A)+w(B) for identity comparison, eight for scalar numeric hashes, and 8+n resident UTF-8 bytes for String. Known lengths charge before traversal/refusal; null/wrong/unavailable String carriers charge eight. Checked cost overflow charges base and faults. These are total attempted costs, without a generic extra INTRINSIC cycle or refunds. Existing whole-instruction overshoot and zero-budget rules apply; the operations introduce no safepoint.