Files
prometeu-runtime/docs/specs/runtime/01-time-model-and-cycles.md
T
bquarkz 86bade3e1f
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
feat(vm): add typed array and struct guest operations
Add seven Registry-backed collection opcodes with bounded verification, complete value groups, transactional publication and exact attempt costs. Publish ISA, memory and cycle contracts, producer handoff and the completed lesson.

Validate with 925 workspace tests, optimized collection suites and all eight coverage domain gates. Make headless fixture directory names unique for parallel tests.
2026-10-08 10:36:20 +01:00

5.1 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

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.