Files
prometeu-runtime/docs/specs/runtime/01-time-model-and-cycles.md
T
bquarkz 23dc6fc66d
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
feat(runtime): add host wall clock and administrative UTC timestamps
2026-10-13 09:16:15 +01:00

6.7 KiB
Raw Blame History

Time Model and Cycles

Domain: machine timing and cycles Function: normative

Didactic companion: ../learn/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. 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:

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

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

Target CAP: PROMETEU-LITE
Frame Budget: 5,000 cycles

Frame 18231:
Used: 5,612 cycles

Primary cause:
enemy.updateAI(): 1,012 cycles

Program Registry v1 integration

The Dynamic/reference instruction table 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 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.

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 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 charges fixed calls before checks and bounded range calls as 4+8*N (at most 64 draws), retaining fault cycles and whole-instruction overshoot.