discussion framework migration

This commit is contained in:
2026-03-27 04:52:13 +00:00
parent 21030f5c08
commit 7e3e8c81f5
19 changed files with 178 additions and 32 deletions
@@ -0,0 +1,90 @@
---
id: LSN-0001
ticket: legacy-runtime-learn-import
title: PROMETEU Learn
created: 2026-03-27
tags: [migration, tech-debt]
---
# PROMETEU Learn
This area contains pedagogical material about the PROMETEU machine.
It exists to explain the fantasy handheld's mental model, influences, tradeoffs, and design implications without contaminating the normative specs with pedagogical framing.
## Authority
- `discussion/lessons/` is not a canonical source of technical contract.
- The machine's normative surfaces live in [`../specs/`](../../specs/README.md).
- The VM/runtime's internal invariants live in [`../virtual-machine/ARCHITECTURE.md`](../../vm-arch/ARCHITECTURE.md).
## Reading Order
If someone is entering the machine model now, the most useful order is:
1. [`mental-model-time-and-cycles.md`](LSN-0017-mental-model-time-and-cycles.md)
2. [`mental-model-portability-and-cross-platform.md`](LSN-0014-mental-model-portability-and-cross-platform.md)
3. [`mental-model-observability-and-debugging.md`](LSN-0013-mental-model-observability-and-debugging.md)
4. [`mental-model-status-first-and-fault-thinking.md`](LSN-0016-mental-model-status-first-and-fault-thinking.md)
5. then the peripherals and specific domains
## Core Mental Models
- [`mental-model-time-and-cycles.md`](LSN-0017-mental-model-time-and-cycles.md)
- [`mental-model-portability-and-cross-platform.md`](LSN-0014-mental-model-portability-and-cross-platform.md)
- [`mental-model-observability-and-debugging.md`](LSN-0013-mental-model-observability-and-debugging.md)
- [`mental-model-status-first-and-fault-thinking.md`](LSN-0016-mental-model-status-first-and-fault-thinking.md)
## Peripheral Mental Models
- [`mental-model-gfx.md`](LSN-0011-mental-model-gfx.md)
- [`mental-model-audio.md`](LSN-0010-mental-model-audio.md)
- [`mental-model-asset-management.md`](LSN-0009-mental-model-asset-management.md)
- [`mental-model-input.md`](LSN-0012-mental-model-input.md)
- [`mental-model-touch.md`](LSN-0018-mental-model-touch.md)
- [`mental-model-save-memory-and-memcard.md`](LSN-0015-mental-model-save-memory-and-memcard.md)
## Historical Snapshots
These files preserve the rationale of decisions already absorbed by specs and/or implementation. They are useful for context, but they should not be read as the primary current contract.
- [`historical-gfx-status-first-fault-and-return-contract.md`](LSN-0006-historical-gfx-status-first-fault-and-return-contract.md)
- [`historical-audio-status-first-fault-and-return-contract.md`](LSN-0003-historical-audio-status-first-fault-and-return-contract.md)
- [`historical-asset-status-first-fault-and-return-contract.md`](LSN-0002-historical-asset-status-first-fault-and-return-contract.md)
- [`historical-cartridge-boot-protocol-and-manifest-authority.md`](LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md)
- [`historical-game-memcard-slots-surface-and-semantics.md`](LSN-0005-historical-game-memcard-slots-surface-and-semantics.md)
- [`historical-retired-fault-and-input-decisions.md`](LSN-0007-historical-retired-fault-and-input-decisions.md)
## Naming Convention
- `mental-model-*.md`: consolidated pedagogical entry point.
- `historical-*.md`: historical snapshot, retired rationale, or material consolidated elsewhere.
- `README.md`: area map and navigation.
## Rules
- material in `learn` may explain, compare, teach, and provide context;
- material in `learn` must not redefine the normative contract of the specs;
- when a topic has both a spec and a pedagogical guide, the guide should point to the corresponding spec;
- when there is both a historical snapshot and a consolidated guide for the same topic, the consolidated guide should be the entry point;
- snapshots must make clear that they are historical and point to the current normative anchors.
## When To Create A Pair
Create a `spec` + `learn` pair when the topic:
- needs a stable technical contract and a mental model;
- has strong historical, pedagogical, or design-rationale weight;
- risks turning into manifesto text inside the normative spec;
- requires examples, comparisons, or intuition that do not belong in the contract.
If the topic is small and strictly contractual, the chapter may live only in `specs`.
## Learn Refactoring Rule
When `learn` accumulates too many snapshots:
- consolidate repeated ideas into larger pedagogical guides;
- reduce chronological redundancy;
- keep snapshots only as historical trace and backlink;
- reorganize by mental model, not by decision order.
@@ -0,0 +1,137 @@
---
id: LSN-0002
ticket: legacy-runtime-learn-import
title: Historical Snapshot - Asset Status-First Fault and Return Contract
created: 2026-03-27
tags: [migration, tech-debt]
---
# Historical Snapshot - Asset Status-First Fault and Return Contract
Status: historical snapshot in `learn`, not normative.
Current normative anchors:
- [`../specs/15-asset-management.md`](../../specs/15-asset-management.md)
- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
- [`mental-model-status-first-and-fault-thinking.md`](LSN-0016-mental-model-status-first-and-fault-thinking.md)
## Status
Accepted
## Context
Agenda `006-asset-fault-semantics-and-surface.md` exposed inconsistency in the `asset` domain:
- `asset.status` already used numeric status;
- `asset.load` was still escalating operational failure to `Panic`;
- `asset.commit`/`asset.cancel` were `void` with silent no-op in several cases.
To align the domain with `16a`, a status-first contract was adopted for `asset`.
## Decision
### 1. Fault-class boundary in `asset`
`asset` follows:
- `Trap`: structural ABI/call violation (type, arity, capability, shape).
- `status` (integer): recoverable operational domain error.
- `Panic`: internal runtime/host invariant break only.
### 2. Canonical domain surface
The final MVP surface is:
- `asset.load(name, kind, slot) -> (status:int, handle:int)`
- `asset.status(handle) -> status:int`
- `asset.commit(handle) -> status:int`
- `asset.cancel(handle) -> status:int`
Rules:
- `handle` is only valid when `status == ASSET_OK`;
- on `load` failure, `handle` must be `0`.
### 3. Silent no-op forbidden
Silent no-op is not allowed for operations with possible operational error.
Cases such as:
- unknown handle;
- invalid lifecycle transition;
- invalid slot;
- missing asset;
must return explicit `status`.
### 4. `asset.load` (request path)
Operational request failures must become `status`, including:
- `ASSET_NOT_FOUND`;
- `SLOT_KIND_MISMATCH`;
- `SLOT_INDEX_INVALID`;
- `BACKEND_ERROR`.
`Panic` must not be used for operational `load` failure.
### 5. `asset.status` (lifecycle path)
`asset.status` remains the source of truth for the asynchronous lifecycle.
Lifecycle codes should cover:
- `PENDING`
- `LOADING`
- `READY`
- `COMMITTED`
- `CANCELED`
- `ERROR`
- `UNKNOWN_HANDLE`
### 6. `asset.commit` and `asset.cancel`
Both operations must return `status`.
Minimum response table:
- `ASSET_OK` (action accepted/completed for the current state)
- `UNKNOWN_HANDLE`
- `INVALID_STATE`
### 7. Relationship with the `bank` domain
Residency/slot errors remain in the `asset` domain.
`bank` remains an inspection domain (`info`, `slot_info`) and does not absorb operational errors from asset lifecycle mutation.
### 8. Compatibility and migration
There is no backward-compatibility requirement for this change.
It is allowed to:
- change `ret_slots` for `asset.load`, `asset.commit`, and `asset.cancel`;
- adjust registry/loader/dispatch/runtime to the new contract;
- regenerate the stress test with the new signatures.
## Consequences
### Positive
- removes improper operational `Panic` from the `asset` domain;
- makes lifecycle flow observable and consistent;
- eliminates no-op ambiguity in `commit`/`cancel`.
### Costs
- requires ABI migration of `asset` syscalls;
- requires updates to tests and generated artifacts.
## Required Follow-up
- agenda `006-asset-fault-semantics-and-surface.md` should be considered absorbed and removed;
- specs `15` and `16a` should absorb the final contract when implementation is stable;
- the syscall registry should reflect the final operation shape (`ret_slots`) for `asset`.
@@ -0,0 +1,125 @@
---
id: LSN-0003
ticket: legacy-runtime-learn-import
title: Historical Snapshot - Audio Status-First Fault and Return Contract
created: 2026-03-27
tags: [migration, tech-debt]
---
# Historical Snapshot - Audio Status-First Fault and Return Contract
Status: historical snapshot in `learn`, not normative.
Current normative anchors:
- [`../specs/05-audio-peripheral.md`](../../specs/05-audio-peripheral.md)
- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
- [`mental-model-status-first-and-fault-thinking.md`](LSN-0016-mental-model-status-first-and-fault-thinking.md)
## Status
Accepted
## Context
Agenda `005-audio-fault-semantics-and-surface.md` exposed ambiguity in the `audio` domain:
- silent no-op/fallback for operational failures;
- `void` operations even when real failure is possible;
- risk of escalating app errors to `Panic`.
To align with `16a`, the `audio` domain adopts a status-first policy.
## Decision
### 1. Fault-class boundary in `audio`
`audio` follows this taxonomy:
- `Trap`: structural ABI/call violation (type, arity, capability, shape).
- `status` (integer): recoverable operational domain error.
- `Panic`: internal runtime/host invariant break only.
### 2. Per-operation return policy
Not every syscall needs to return `status`.
Canonical rule:
- if the operation can fail operationally, it should return `status: int` (`ret_slots >= 1`);
- if the operation has no real operational error path, it may remain `void`.
For the current MVP:
- `audio.play` should return `status`;
- `audio.play_sample` should return `status`.
### 3. No-op and fallback
Silent no-op is not allowed in operations with possible operational error.
Implicit fallback is also not allowed when it masks a domain error.
Forbidden examples:
- implicit fallback to default `bank_id` when the asset is not found;
- ignoring invalid `voice_id` without explicit return.
### 4. Per-operation status table
Each `audio` operation that returns `status` must define integer codes normatively.
The minimum table for `play`/`play_sample` should cover, when applicable:
- `OK`;
- `VOICE_INVALID`;
- `ASSET_NOT_FOUND`;
- `SAMPLE_NOT_FOUND`;
- `ARG_RANGE_INVALID`;
- `NO_EFFECT` (only when a valid and explicit no-effect case exists).
### 5. Numeric ranges
Numeric inputs with normative ranges (`volume`, `pan`, `pitch`) must have explicit policy.
When outside the accepted range:
- return range-error `status`;
- do not mask it as silent success.
### 6. Panic hygiene
App argument errors must not escalate to `Panic`.
These cases should be classified as:
- `Trap` (structural); or
- `status` (operational, according to the operation).
### 7. Compatibility and migration
There is no backward-compatibility requirement for this change.
It is allowed to:
- adjust `audio` syscall signatures (including `ret_slots`);
- update registry/loader/runtime with the new contract;
- regenerate the stress test with the final signatures.
## Consequences
### Positive
- reduces silent behavior in audio operational errors;
- makes audio calls observable and testable;
- aligns `audio` with the general `16a` model.
### Costs
- requires ABI changes to audio syscalls;
- requires updates to tests and stress artifacts.
## Required Follow-up
- agenda `005-audio-fault-semantics-and-surface.md` should be considered absorbed and removed;
- specs `05` and `16a` should absorb the final contract when implementation is stable;
- the syscall registry should reflect the final `ret_slots` and status codes for `audio`.
@@ -0,0 +1,96 @@
---
id: LSN-0004
ticket: legacy-runtime-learn-import
title: Historical Cartridge Boot Protocol and Manifest Authority
created: 2026-03-27
tags: [migration, tech-debt]
---
# Historical Cartridge Boot Protocol and Manifest Authority
Status: pedagogical / historical
Normative anchors:
- [`../specs/13-cartridge.md`](../../specs/13-cartridge.md)
- [`../specs/12-firmware-pos-and-prometeuhub.md`](../../specs/12-firmware-pos-and-prometeuhub.md)
- [`../specs/14-boot-profiles.md`](../../specs/14-boot-profiles.md)
This document records the historical rationale behind removing `entrypoint` from the cartridge manifest and moving cartridge boot authority into the executable artifact itself.
It is not a normative contract. The current contract lives in the specs above.
## Core Shift
The older runtime model treated `entrypoint` as cartridge metadata:
- `manifest.json` declared the callable to run;
- loader and cartridge DTOs propagated that string;
- VM initialization accepted textual resolution;
- runtime state tracked the current entrypoint as if boot authority were part of runtime metadata.
The newer model treats boot as executable protocol:
- the cartridge artifact itself defines the physical boot target;
- the executable entrypoint is always `func_id = 0`;
- firmware selects the cartridge, but not the callable inside it;
- nominal exports may still exist, but they do not decide boot.
## Why The Old Model Was Weak
The manifest-driven model created duplicate authority between compiler and runtime.
That duplication had three concrete effects:
- it let the manifest override what should have been fixed by the compiled artifact;
- it mixed symbolic, numeric, and fallback boot paths in the VM;
- it made boot failures less deterministic and less explainable.
In practice, the machine was carrying too much flexibility at the exact boundary where it needed a single source of truth.
## Why `func_id = 0` Became The Right Boundary
Boot is not user-facing metadata. It is part of executable structure.
By fixing boot at `func_id = 0`, the machine gets:
- one authority for startup;
- a simpler cartridge manifest;
- a more deterministic VM initialization path;
- clearer failure semantics when the artifact is malformed.
This also keeps the cartridge manifest focused on package metadata such as identity, version, mode, and capabilities, instead of turning it into an execution control surface.
## What Stayed Flexible
This change did not ban nominal exports from the bytecode image.
Exports still make sense for:
- linking;
- introspection;
- debug-oriented naming.
What changed is narrower and more important:
- exports are no longer boot authority.
## Runtime Consequence
Once boot became protocol-driven, the runtime was simplified:
- `entrypoint` disappeared from cartridge manifest and loader types;
- VM initialization stopped accepting textual boot resolution;
- runtime state no longer needed to track `current_entrypoint` for cartridge startup;
- the stress cartridge generator was updated to emit the new manifest shape.
The canonical initialization failure remained `VmInitError::EntrypointNotFound`, but its meaning hardened to "protocol boot target is absent or invalid".
## Historical Trace
This model was closed through the historical pipeline:
- agenda `025`
- decision `025`
- PR `025` for spec propagation
- PR `026` for runtime propagation
Those working artifacts were intentionally pruned after implementation so that `agendas/`, `decisions/`, and `pull-requests/` remain focused on live work.
@@ -0,0 +1,146 @@
---
id: LSN-0005
ticket: legacy-runtime-learn-import
title: Historical Snapshot - Game Memcard Slots Surface and Semantics
created: 2026-03-27
tags: [migration, tech-debt]
---
# Historical Snapshot - Game Memcard Slots Surface and Semantics
Status: historical snapshot in `learn`, not normative.
Current normative anchors:
- [`../specs/08-save-memory-and-memcard.md`](../../specs/08-save-memory-and-memcard.md)
- [`../specs/16-host-abi-and-syscalls.md`](../../specs/16-host-abi-and-syscalls.md)
- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
- [`mental-model-save-memory-and-memcard.md`](LSN-0015-mental-model-save-memory-and-memcard.md)
- [`mental-model-status-first-and-fault-thinking.md`](LSN-0016-mental-model-status-first-and-fault-thinking.md)
## Status
Accepted
## Context
Games need predictable, portable persistence for save/config/blob data without broad filesystem access.
Agenda `013-game-memcard-slots-surface-and-semantics.md` consolidated the product inputs:
- `game` uses `32` slots per game;
- maximum payload per slot is `32KB`;
- the game accesses only slots owned by its own `app_id`;
- persistence is explicit, with atomic `commit` per slot;
- save copy/export/import happens outside the game (Hub/OS).
This decision closes the v1 contract for the `game` profile while using decision `003` as the byte data plane.
## Decision
### 1. Base capacity and ownership contract
- each game has exactly `32` logical slots (`0..31`);
- each slot offers up to `32 * 1024` bytes of usable payload;
- userland access is restricted to the `app_id` that owns the loaded cart;
- there is no path-based access for games in v1.
### 2. Minimum memcard surface (status-first)
- `slot_count() -> (status:int, count:int)`
- `slot_stat(slot:int) -> (status:int, state:int, used_bytes:int, generation:int, checksum:int)`
- `slot_read(slot:int, buf:HeapRef<Bytes>, offset:int, max_bytes:int) -> (status:int, bytes_read:int)`
- `slot_write(slot:int, buf:HeapRef<Bytes>, offset:int, len:int) -> (status:int, bytes_written:int)`
- `slot_commit(slot:int) -> status:int`
- `slot_clear(slot:int) -> status:int`
Rules:
- `status` is always the first return value;
- byte operations use `HeapRef<Bytes>` plus an explicit window (`offset`, `max_bytes`/`len`);
- shape follows the policy in `16a`.
### 3. Runtime-owned digital envelope per slot
Each slot keeps canonical runtime-owned metadata:
- owning `app_id`;
- `slot_index`;
- `save_uuid`;
- `generation`;
- `payload_size`;
- `checksum`;
- `state` (`EMPTY`, `STAGED`, `COMMITTED`, `CORRUPT`).
`generation` and `checksum` are not manually controlled by userland:
- `generation` increments on each successful `slot_commit`;
- `checksum` is recalculated by the runtime on the persisted payload.
### 4. Visual envelope for Hub/OS
The slot exposes visual metadata for UX outside the game:
- `label`;
- `subtitle`;
- `updated_at` (or equivalent logical counter);
- `icon_ref` (static in v1, extensible to future animation).
### 5. Write policy and atomicity
- `slot_write` changes staging (it does not persist to the final destination);
- `slot_commit` applies per-slot atomic persistence;
- silent partial success is forbidden;
- on commit failure, it returns error `status` and preserves the atomicity invariant.
### 6. Fault-class boundary
`memcard(game)` follows `16a`:
- `Trap`: structural error (slot out of range, invalid/dead `HeapRef`, invalid window, invalid ABI shape);
- `status`: operational domain error;
- `Panic`: internal invariant break only.
Minimum domain status catalog:
- `OK`;
- `EMPTY`;
- `NOT_FOUND`;
- `NO_SPACE`;
- `ACCESS_DENIED`;
- `CORRUPT`;
- `CONFLICT`;
- `UNAVAILABLE`;
- `INVALID_STATE`.
### 7. Copy/export/import policy (outside the game)
- copy/export/import is a Hub/OS responsibility;
- the game does not receive an API to copy slots between apps;
- v1 validates ownership by `app_id` on import;
- conflict and corruption must be reflected through domain status and Hub UX.
### 8. Integration with host storage
- physical namespace isolated by `app_id`;
- physical per-slot representation is internal to the runtime/host;
- persistence should use an atomic strategy (temporary file + flush + platform-equivalent rename).
## Consequences
### Positive
- closes the `game` save contract without opening broad FS access;
- makes copy/export/import a system flow (Hub/OS), not a userland flow;
- standardizes slot integrity/versioning through `generation` + `checksum`.
### Costs
- requires per-slot staging/atomic commit implementation;
- requires explicit specification of the export/import format in Hub/OS;
- requires alignment with memcard and ABI specs.
## Required Follow-up
- agenda `013-game-memcard-slots-surface-and-semantics.md` should be considered closed and removed;
- `specs/08-save-memory-and-memcard.md` should absorb this contract (`32 x 32KB`, slots by `app_id`, atomic commit);
- `specs/16-host-abi-and-syscalls.md` and `specs/16a-syscall-policies.md` should absorb the surface and fault/status matrix.
@@ -0,0 +1,119 @@
---
id: LSN-0006
ticket: legacy-runtime-learn-import
title: Historical Snapshot - GFX Status-First Fault and Return Contract
created: 2026-03-27
tags: [migration, tech-debt]
---
# Historical Snapshot - GFX Status-First Fault and Return Contract
Status: historical snapshot in `learn`, not normative.
Current normative anchors:
- [`../specs/04-gfx-peripheral.md`](../../specs/04-gfx-peripheral.md)
- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
- [`mental-model-status-first-and-fault-thinking.md`](LSN-0016-mental-model-status-first-and-fault-thinking.md)
## Status
Accepted
## Context
Agenda `004-gfx-fault-semantics-and-command-contract.md` consolidated that the `gfx` domain had ambiguity between:
- unnecessary `Trap`/`Panic` for operational errors;
- silent no-op;
- `void` calls in operations that may fail operationally.
To align with `16a`, a status-first policy was adopted for the `gfx` domain.
## Decision
### 1. Fault-class boundary in `gfx`
`gfx` follows this taxonomy:
- `Trap`: structural ABI/call violation (type, arity, capability, shape).
- `status` (integer): recoverable operational domain error.
- `Panic`: internal runtime/host invariant break only.
### 2. Per-operation return policy
Not every `gfx` syscall needs to return `status`.
Canonical rule:
- if the operation can produce observable operational error, it should return `status: int` (`ret_slots >= 1`);
- if the operation has no real operational error path, it may remain `void`.
### 3. Per-operation status table
Each `gfx` operation that returns `status` must declare its own integer code table.
The table should cover, when applicable:
- missing resource (`asset_not_found`);
- invalid index (`invalid_sprite_index`);
- out-of-range argument (`invalid_arg_range`);
- no operational effect (`no_effect`), when applicable.
### 4. No-op policy
Silent no-op is not allowed in operations that can fail operationally.
When there is operational failure/ignoring:
- the call must return explicit `status`;
- the result must not be disguised as implicit success.
### 5. `gfx.set_sprite` contract
`set_sprite` must not depend on implicit fallback to a default bank.
Cases such as:
- missing/not-found `asset_name`;
- `sprite_index` out of range;
- `palette_id`/`priority` out of range;
must be reported via `status` according to the operation table.
### 6. Panic hygiene
App argument errors must not escalate to `Panic`.
Helpers and dispatch must map those cases to:
- `Trap` (when structural); or
- `status` (when operational, for operations with status return).
### 7. Compatibility and migration
There is no backward-compatibility requirement for this change.
It is allowed to:
- adjust `gfx` syscall signatures (especially `ret_slots`);
- update registry/loader/runtime in line with the final matrix;
- regenerate stress-test artifacts with the new contract.
## Consequences
### Positive
- reduces improper `Trap`/`Panic` in the graphics domain;
- eliminates silent behavior in commands with operational error;
- makes return contracts more consistent and testable.
### Costs
- requires updates to syscall metadata and dispatch;
- requires updates to tests and the stress generator.
## Required Follow-up
- agenda `004-gfx-fault-semantics-and-command-contract.md` should be considered absorbed and removed;
- specs `04` and `16a` should absorb the final contract when implementation is stable;
- the final per-syscall matrix (`void` vs `status`) and code table should be reflected in the syscall registry.
@@ -0,0 +1,45 @@
---
id: LSN-0007
ticket: legacy-runtime-learn-import
title: Retired Decisions 004-005 (Historical Notes)
created: 2026-03-27
tags: [migration, tech-debt]
---
# Retired Decisions 004-005 (Historical Notes)
This file keeps historical rationale from decisions that were retired after being absorbed by specs.
Status: pedagogical / historical (not normative).
## Mapping
- Retired `004-host-fault-taxonomy.md`
- Canonical source now: `../specs/16a-syscall-policies.md`
- Retired `005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
- Canonical sources now:
- `../specs/06-input-peripheral.md`
- `../specs/16-host-abi-and-syscalls.md`
- `../specs/16a-syscall-policies.md`
## Historical Rationale Snapshot
### 1) Why input left syscall path in v1
- repeated input reads through syscall would force large value transport;
- deterministic frame snapshot works better as VM-owned intrinsic surface;
- frontend syntax should stay language-specific while VM contract stays language-agnostic.
### 2) Why fault taxonomy was tightened
- operational domain outcomes should be returned as `status`;
- `Trap` should represent structural ABI misuse from guest side;
- `Panic` should represent runtime invariant break;
- broad `Unavailable` usage was causing severity ambiguity.
## Practical Outcome
- Input is VM-owned and deterministic per logical frame.
- Host-backed syscall ABI remains structurally stable.
- Domain agendas now anchor fault discussions on spec `16a`, not on retired decisions.
@@ -0,0 +1,61 @@
---
id: LSN-0008
ticket: legacy-runtime-learn-import
title: Historical VM Core and Assets (Retired Decisions)
created: 2026-03-27
tags: [migration, tech-debt]
---
# Historical VM Core and Assets (Retired Decisions)
This document consolidates the historical rationale and mental models from retired decisions regarding VM-owned stateful core, byte transfer protocol, filesystem fault policies, and asset management.
Status: Pedagogical / Historical (not normative).
## 1. VM-Owned Stateful Core and Byte Transfer
### Rationale for Stateful Core (Retired Decision 006)
- **Problem**: Lack of a canonical contract for stateful VM-owned resources led to divergence in handles, lifecycles, and ABI shapes.
- **Solution**: Represent stateful resources as `HeapRef<TBuiltinState>` with anti-stale mechanisms (index + generation).
- **Lifecycle**: Every stateful domain must explicitly define `create`, `read/query`, `update`, and `destroy`.
- **Fault Model**: `Trap` for structural errors (invalid ABI, stale handles), `status` for domain operational failures.
### Rationale for Byte Transfer Protocol (Retired Decision 003)
- **Goal**: Establish a canonical protocol for moving bytes between host and guest without binary-to-string conversion or host-owned handles.
- **Protocol**: Uses `Value::Byte` as a primitive and `HeapRef(Byte)` (ObjectKind::Bytes) as the canonical buffer.
- **Signatures**:
- `read(host_handle, host_offset, dst_ref, dst_offset, max_bytes) -> (status, bytes_transferred, eof)`
- `write(host_handle, host_offset, src_ref, src_offset, max_bytes) -> (status, bytes_transferred)`
- **Impact**: Unified data plane for `fs` and data banks, giving the guest explicit control over memory.
## 2. Filesystem Fault Policy (Retired Decision 007)
### Core Policy
- **Trap**: Structural violations (invalid signatures, dead HeapRefs, invalid byte windows).
- **Status**: Operational conditions (not found, access denied, storage full, transient backend errors).
- **No Partial Success**: `write` operations must not report silent partial success; failure to complete the full contract results in a domain failure status.
## 3. Asset Management and `assets.pa` Contract
### Autocontained Runtime Contract (Retired Decision 011)
- **Transition**: Moved from fragmented `manifest.json` + `assets.pa` to a single autocontained `assets.pa` artifact.
- **Envelope v1**: Fixed binary prelude + JSON header (asset_table + preload) + Binary payload.
- **Memory Efficiency**: The runtime must not require the entire payload to be resident in RAM; slices are resolved using offsets relative to the payload region.
### Preload and Identity (Retired Decision 012)
- **Identity**: `PreloadEntry` moved from name-based to ID-based (`{ asset_id, slot }`).
- **Semantics**: `asset_id` follows Java `int` (32-bit signed) semantics to ensure cross-platform compatibility.
- **Validation**: Preload is validated during bootstrap against the `asset_table`. Invalid IDs or slot clashes (same bank_type and slot) are structural errors that abort boot.
## References
- **Specs**:
- `../specs/15-asset-management.md`
- `../specs/16-host-abi-and-syscalls.md`
- `../specs/16a-syscall-policies.md`
- **Source Decisions (Archived)**:
- `003-vm-owned-byte-transfer-protocol.md`
- `006-vm-owned-stateful-core-contract.md`
- `007-filesystem-fault-core-policy.md`
- `011-assets-pa-autocontained-runtime-contract.md`
- `012-assets-preload-asset-id-contract.md`
@@ -0,0 +1,207 @@
---
id: LSN-0009
ticket: legacy-runtime-learn-import
title: Asset Management Mental Model
created: 2026-03-27
tags: [migration, tech-debt]
---
# Asset Management Mental Model
Status: pedagogical
Companion specs:
- [`../specs/13-cartridge.md`](../../specs/13-cartridge.md)
- [`../specs/15-asset-management.md`](../../specs/15-asset-management.md)
- [`../specs/04-gfx-peripheral.md`](../../specs/04-gfx-peripheral.md)
Origin decisions:
- [`../decisions/011-assets-pa-autocontained-runtime-contract.md`](../decisions/011-assets-pa-autocontained-runtime-contract.md)
- [`../decisions/013-asset-codec-none-vs-raw.md`](../decisions/013-asset-codec-none-vs-raw.md)
PROMETEU treats assets as a self-contained cart artifact, not as metadata scattered across `manifest.json`, the loader, and the runtime.
## One Runtime Artifact
The right mental model is:
- `manifest.json` identifies the cart and its capabilities;
- `assets.pa` carries the runtime-facing asset contract;
- the runtime consumes that contract without depending on auxiliary tooling artifacts.
That avoids mixing:
- cart editorial metadata;
- internal packer details;
- runtime loading policy.
## Why `assets.pa` Owns The Asset Contract
`assets.pa` puts into the same binary:
- a fixed prelude to locate the header;
- a JSON header that is easy to inspect;
- the cold binary payload of the assets.
That split exists to preserve two properties at the same time:
- fixed cost to open and validate the artifact;
- a readable header that is simple to debug.
The important point is not the format by itself. The important point is that the runtime finds everything it needs for assets behind one stable boundary.
## `preload` Is Not `asset_table`
Both live in the header, but they serve different roles:
- `asset_table` is the live asset-resolution index for the entire execution;
- `preload` is only a boot-time instruction for initial residency.
A short way to think about it:
- `asset_table` stays;
- `preload` passes.
That prevents the runtime from treating preload as permanent metadata when, in practice, it is only an initial loading impulse.
## Payload-Relative Thinking
`AssetEntry` offsets are relative to the start of the payload, not to the start of the whole file.
That choice preserves the semantics of the `asset` domain:
- `AssetEntry` describes where content sits inside the cold-byte region;
- the outer envelope can evolve without contaminating each entry with container details.
The runtime only needs to resolve:
```text
payload_base + entry.offset
```
## Slice-First Loading
The correct loading mental model is not:
```text
ROM -> load the whole assets.pa into RAM -> look up asset
```
The correct flow is:
```text
ROM -> open_slice -> CODEX/decode -> Bank
```
or, when the codec requires it:
```text
ROM -> open_slice -> temporary blob -> CODEX/decode -> Bank
```
That matters because PROMETEU was designed for low-cost hardware. Keeping the whole payload resident as a baseline wastes memory, couples IO to a monolithic blob, and weakens the runtime's real boundary.
## `OP_MODE` Belongs To The Runtime
The cart describes the asset. The runtime decides how to consume the slice.
In v1, that decision comes from the `codec`/CODEX:
- some assets can be read directly from the limited view;
- others require temporary materialization before decode.
The key point is to separate:
- the asset storage contract;
- the generic codec layer, when one exists;
- the operational strategy for reading and decode.
## Specialized Banks vs Generic Banks
The current asset model works better if you do not treat every bank as equally generic.
Some banks are specialized:
- `TILES`
- `SOUNDS`
For these, the bank contract already carries most of the important format rules. That means:
- serialized layout belongs primarily to the bank contract;
- metadata validation belongs primarily to the bank contract;
- `codec` may be absent or minimal.
Other banks may be more generic in the future, such as a `BLOB`-style bank.
For those, `codec` can do more real work and describe a broader generic transformation pipeline for the payload.
That is the right hierarchy:
- specialized bank first;
- generic codec layer second.
Not the other way around.
## Why `NONE` Matters
The move from `RAW` to `NONE` is not just a rename. It fixes the mental model.
`RAW` encouraged the wrong intuition that the bytes were somehow already "raw" in the runtime sense. But for specialized banks that is often false.
`NONE` is better because it says only this:
- there is no additional generic codec layer.
It does not say:
- there is no bank-specific decode;
- there is no transformation before residency;
- serialized bytes and resident memory are identical.
## Serialized Form Is Not Resident Form
One of the most important asset-management lessons in the current runtime is that `codec = NONE` does not mean "bitwise identical to in-memory layout".
The tile-bank path is the concrete example:
- there is no additional generic codec layer for the asset;
- the serialized payload stores indexed pixels as packed `4bpp`;
- the palette table remains serialized as `RGB565` little-endian;
- the runtime expands pixels into one `u8` index per pixel after decode.
That is exactly why `codec` and bank contract must stay separate in the mental model:
- `codec` may be absent;
- the bank-specific decode may still be real and mandatory.
That is why `AssetEntry.size` and `AssetEntry.decoded_size` must be thought of as different concepts:
- `size` is transport cost inside `assets.pa`;
- `decoded_size` is resident-bank cost after materialization.
If those two numbers are treated as interchangeable, telemetry, budgets, and validation all become misleading.
## Tile Banks Teach The Real Boundary
Tile banks are useful because they show the real separation of concerns:
- `assets.pa` defines the serialized envelope and metadata needed to reconstruct the bank;
- the runtime validates that metadata against the expected v1 contract;
- the resident `TileBank` is a runtime object, not a direct view over the cold bytes.
This is the right PROMETEU mental model:
- cartridge asset bytes are transport;
- bank objects are execution state.
## Why This Fits PROMETEU
This model fits the project well because:
- it reduces dependence on metadata scattered through `manifest.json`;
- it separates `packer`, `shipper`, and runtime more cleanly;
- it allows early failure when `Capability::Asset` requires `assets.pa`;
- it preserves a runtime that can run on desktop and on low-cost dedicated hardware.
When thinking about assets in PROMETEU, think less in terms of "a manifest with attachments" and more in terms of "a cart with an asset artifact that explains itself".
@@ -0,0 +1,63 @@
---
id: LSN-0010
ticket: legacy-runtime-learn-import
title: Audio Mental Model
created: 2026-03-27
tags: [migration, tech-debt]
---
# Audio Mental Model
Status: pedagogical
Companion spec: [`../specs/05-audio-peripheral.md`](../../specs/05-audio-peripheral.md)
The right mental model for audio in PROMETEU is an active peripheral with a budget, not "automatic sound".
## Philosophy
Sound:
- consumes time;
- consumes memory;
- uses finite channels;
- depends on explicit commands.
That brings PROMETEU closer to classic consoles and arcades where the game "talks" to an audio block with its own rules.
## Audio CPU Metaphor
A useful metaphor is:
```text
[Game CPU] -> sends commands at 60 Hz -> [AUDIO Peripheral]
|
v
Voices + Mixer
|
v
PCM Output
```
This metaphor does not require a dedicated thread. It only separates responsibilities:
- the machine defines the logical model;
- the host decides how to deliver continuous buffers;
- the game speaks in commands, not direct backend manipulation.
## Good Habits
- reuse samples;
- limit simultaneous voices;
- treat sound as an intentional event;
- separate music and effects;
- avoid triggering the same sound every frame.
## Historical Direction
The main influences here are:
- NES, for the clarity of limited channels;
- SNES, for sample playback and mixing;
- CPS-2 and Neo Geo, for the feeling of headroom and sample presence.
PROMETEU abstracts those references. It does not try to reproduce any of those systems literally.
@@ -0,0 +1,99 @@
---
id: LSN-0011
ticket: legacy-runtime-learn-import
title: GFX Mental Model
created: 2026-03-27
tags: [migration, tech-debt]
---
# GFX Mental Model
Status: pedagogical
Companion spec: [`../specs/04-gfx-peripheral.md`](../../specs/04-gfx-peripheral.md)
Related asset spec: [`../specs/15-asset-management.md`](../../specs/15-asset-management.md)
PROMETEU treats graphics as an explicit peripheral, not as a modern GPU.
The right mental model is a retro 2D machine with:
- framebuffer;
- tile banks;
- tile layers;
- sprites ordered by draw order;
- deterministic composition per frame.
## Why This Exists
The goal is not to imitate historical hardware byte for byte. The goal is to capture the family of constraints and visual language of consoles such as SNES, CPS-2, and Neo Geo in a small, portable contract that can run on desktop and DIY hardware.
That produces some important consequences:
- draw order matters more than "effects";
- palettes matter as part of asset design;
- the programmer thinks in terms of rasterization, not shaders;
- visual cost becomes more observable.
## What The GFX Is Not
PROMETEU GFX is not:
- a modern GPU pipeline;
- an RGBA framebuffer with arbitrary alpha;
- a shader system;
- automatic post-processed composition.
Those absences are deliberate. They force a visual language closer to classic consoles and keep the contract executable in modest environments.
## Practical Intuition
- Tile layers exist for world and scenery.
- HUD exists for fixed information and should remain decoupled from the camera.
- Sprites exist for moving entities, and their depth depends on order and priority.
- Palettes exist to vary visual state without duplicating tile art.
- Fade exists as a discrete special effect, not as generic alpha.
## Palette Thinking
A good way to think about PROMETEU is that art and color are not the same thing.
The tile is the shape. The palette is the visual state.
That enables:
- enemy variation;
- biome changes;
- damage, ice, poison, power-up states;
- HUD themes;
- day and night cycles.
In the current tile-bank v1 baseline, this palette model is intentionally bounded:
- each bank carries `64` palettes;
- each palette carries `16` colors;
- `palette_id` is therefore a small runtime-facing selector, not an open-ended color namespace.
That limit is not incidental bookkeeping. It is part of how art packaging, runtime validation, and rendering stay aligned.
## Tile Banks Are Decoded Runtime Objects
The most useful intuition is to separate three layers:
- authored indexed art;
- serialized cart payload;
- resident runtime bank.
For tile banks in v1:
- authored pixels are logical indices `0..15`;
- serialized payload stores those indices as packed `4bpp`;
- runtime memory expands them to one `u8` index per pixel after decode.
So when reading the graphics model, do not imagine the renderer reading packed nibbles directly from cartridge storage. The renderer consumes a decoded `TileBank` object whose memory shape is optimized for runtime lookup, not for transport density.
## Use Cases
- area transition with `Scene Fade`;
- HUD transition with `HUD Fade`;
- damage flash or teleport flash;
- global palette swap for weather or world state.
@@ -0,0 +1,51 @@
---
id: LSN-0012
ticket: legacy-runtime-learn-import
title: Input Mental Model
created: 2026-03-27
tags: [migration, tech-debt]
---
# Input Mental Model
Status: pedagogical
Companion spec: [`../specs/06-input-peripheral.md`](../../specs/06-input-peripheral.md)
PROMETEU treats input as sampled state, not as an asynchronous event.
## State Versus Event
The most important model to understand is:
- a button does not "fire" an action by itself;
- a button changes state;
- the game reads that state during the frame.
That looks much more like classic console register polling than like modern UI callbacks.
## Why This Matters
This model:
- improves determinism;
- simplifies replay;
- makes debugging easier;
- makes the frame loop easier to read.
It also fits PROMETEU's identity better as a machine strongly inspired by retro hardware and DIY construction.
## Good Habits
- read input in `UPDATE`;
- map actions, not physical keys;
- separate input reading from heavy logic;
- treat polling as part of the frame budget.
## Teaching Value
The input peripheral helps teach:
- the difference between state and event;
- temporal sampling;
- synchronization between input and logic;
- determinism in interactive systems.
@@ -0,0 +1,41 @@
---
id: LSN-0013
ticket: legacy-runtime-learn-import
title: Observability and Debugging
created: 2026-03-27
tags: [migration, tech-debt]
---
# Observability and Debugging
Status: pedagogical
Companion spec: [`../specs/10-debug-inspection-and-profiling.md`](../../specs/10-debug-inspection-and-profiling.md)
PROMETEU was designed to be observable.
## Debug Philosophy
There are three central ideas here:
1. state comes before abstraction;
2. time is a first-class citizen;
3. observing must not alter the logical result.
That pushes the project toward a debugging style that is closer to machine reasoning and farther from "trial and error".
## Why This Matters
When the machine exposes stacks, heap, cycles, buffers, and faults consistently, the programmer can:
- locate real cost;
- correlate time and memory;
- justify technical decisions;
- debug without inventing magical explanations.
## Teaching Value
This pedagogical surface exists because PROMETEU also wants to teach how systems are analyzed:
- debugging as informed observation;
- profiling as evidence reading;
- certification as a reproducible technical report.
@@ -0,0 +1,60 @@
---
id: LSN-0014
ticket: legacy-runtime-learn-import
title: Portability and Cross-Platform Execution
created: 2026-03-27
tags: [migration, tech-debt]
---
# Portability and Cross-Platform Execution
Status: pedagogical
Companion spec: [`../specs/11-portability-and-cross-platform-execution.md`](../../specs/11-portability-and-cross-platform-execution.md)
PROMETEU treats portability as an architectural property of the machine, not as an after-the-fact adaptation.
## Core Idea
The main point is simple:
- the machine defines the semantics;
- the host performs presentation and physical integration;
- the cartridge does not negotiate behavior with the operating system.
That avoids the common notion that each platform has "its own version" of game logic.
## Why This Matters
When time, memory, input, audio, and graphics are defined by the machine, the following become easier:
- deterministic replay;
- reproducible certification;
- execution on desktop, mobile, and DIY hardware;
- clean separation between semantics and adaptation.
## Practical Separation
A useful way to think about it is:
- the cartridge carries program and assets;
- the VM/runtime executes the logic;
- the host shows pixels, delivers audio, and collects physical input;
- the host does not redefine the game's rules.
## What Portability Does Not Mean
PROMETEU does not promise:
- the same physical latency;
- the same power consumption;
- the same raw host throughput.
It promises logical consistency. That is what matters to the machine's identity.
## Teaching Value
This model helps teach:
- the difference between logic and presentation;
- why modern engines often lose determinism;
- how to design portable software without relying on luck.
@@ -0,0 +1,115 @@
---
id: LSN-0015
ticket: legacy-runtime-learn-import
title: Save Memory and MEMCARD
created: 2026-03-27
tags: [migration, tech-debt]
---
# Save Memory and MEMCARD
Status: pedagogical
Companion spec: [`../specs/08-save-memory-and-memcard.md`](../../specs/08-save-memory-and-memcard.md)
Historical snapshot: [`historical-game-memcard-slots-surface-and-semantics.md`](LSN-0005-historical-game-memcard-slots-surface-and-semantics.md)
PROMETEU treats persistence as explicit hardware, not as invisible save behavior.
## Mental Model
MEMCARD is not save state. It is a persistence device controlled by the game.
That implies:
- known size;
- observable cost;
- the need for `commit()`;
- the possibility of failure;
- a data format under the game's control.
## Slot Thinking
The right model is not "the game saves files". The right model is "the game talks to slots".
That changes how you think about persistence:
- capacity is finite and known;
- each slot has identity and state;
- ownership belongs to the cart's `app_id`;
- the game does not get broad access to the host filesystem.
That choice exists to preserve:
- portability;
- isolation between apps;
- predictable save UX;
- a contract that runs on desktop and dedicated hardware.
## Staged Versus Committed
An important MEMCARD intuition is the difference between:
- changing content in staging;
- making the write actually persistent.
`commit()` existe para separar essas duas fases.
That teaches a more honest model of persistence:
- writing is not yet persisting;
- persisting has a cost;
- persisting can fail;
- atomicity matters.
## Why Explicit Commit Matters
`commit()` exists to make persistence a visible technical decision.
Without it, there is no illusion that "saving simply happened". The game must decide when it wants to:
- materialize a write;
- accept the cost;
- deal with the risk of loss or corruption.
## Runtime-Owned Metadata
Even when the payload belongs to the game, some aspects of the slot belong to the machine:
- integrity;
- generation/versioning;
- slot state;
- ownership isolation.
That prevents each game from reinventing its own basic persistence semantics and lets tooling and Hub/OS present save data coherently.
## Hub/OS Role
PROMETEU separates clearly:
- the game writes and reads its own slots;
- the Hub/OS handles export, import, copy, and save presentation.
That separation prevents userland from becoming a mini file manager and keeps system operations in the right layer.
## Tooling Surface
External tools may expose utilities such as:
- create or reset MEMCARD;
- import and export `.mem`;
- inspect size and usage;
- associate cards with projects.
Those surfaces are auxiliary. They do not change the machine contract.
## Why This Is Better Than Broad FS For Games
For the `game` profile, the slot model is better than exposing a broad filesystem because:
- it reduces ambiguity around path, permission, and ownership;
- it makes controlled import/export easier;
- it improves compatibility across hosts;
- it makes it clearer what a "valid save" means to the machine.
## Why This Fits PROMETEU
This model fits well with the project's console heritage and DIY focus: persistence is part of the machine design, not convenience hidden inside the host.
@@ -0,0 +1,163 @@
---
id: LSN-0016
ticket: legacy-runtime-learn-import
title: Status-First and Fault Thinking
created: 2026-03-27
tags: [migration, tech-debt]
---
# Status-First and Fault Thinking
Status: pedagogical
Companion specs:
- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
- [`../specs/04-gfx-peripheral.md`](../../specs/04-gfx-peripheral.md)
- [`../specs/05-audio-peripheral.md`](../../specs/05-audio-peripheral.md)
- [`../specs/08-save-memory-and-memcard.md`](../../specs/08-save-memory-and-memcard.md)
- [`../specs/15-asset-management.md`](../../specs/15-asset-management.md)
PROMETEU uses a status-first model so the host/runtime boundary does not hide operational errors as silence, improper `Trap`, or accidental `Panic`.
## Core Split
The right mental model is:
- `Trap` for structural contract violations;
- `status` for observable operational results;
- `Panic` for internal invariant breaks.
A short way to think about it:
- the guest called it wrong: `Trap`;
- the guest called it correctly, but the domain could not complete it: `status`;
- the runtime broke internally: `Panic`.
## Why This Exists
Without that separation, host-backed systems tend to degrade into a bad mix of:
- `void` in operations that can really fail;
- implicit fallback;
- silent no-op;
- escalation of app errors into `Panic`.
Status-first exists to make behavior:
- observable;
- deterministic;
- testable;
- documentable per domain.
## Return Shape Rule
The most important practical rule is simple:
- if the operation can fail operationally, it should return `status`;
- if the operation has no real operational failure path, it may be `void`.
That prevents contracts in which the guest cannot distinguish:
- success;
- rejection;
- absence of effect;
- backend unavailable;
- missing asset or resource.
## Silent Failure Is Not Allowed
In PROMETEU, an operational error cannot be disguised as:
- implicit success;
- ignoring the call;
- automatic fallback to another resource;
- `Trap`, when the problem is not structural;
- `Panic`, when the problem is not internal.
If the guest can perceive the difference, that difference should appear as `status`.
## Reading The Boundary
When reading or designing a syscall, use this sequence:
1. Is the call structurally correct?
2. Does the guest have permission/capability to use the surface?
3. Can the domain execute the operation with the current resources?
4. Is there additional payload that only makes sense when `status` indicates success?
That reading tends to produce cleaner contracts, for example:
- `asset.load(...) -> (status, handle)`
- `mem.slot_read(...) -> (status, payload, bytes_read)`
- operations without a real failure path remain `void`
## Domain Intuition
### GFX
In `gfx`, the typical problem is not "the syscall exploded". The typical problem is:
- missing sprite;
- index outside the operational range;
- invalid argument for the operation;
- a call with no real effect.
Those cases call for `status`, not silence.
### Audio
In `audio`, the model prevents things like:
- an invalid voice being ignored;
- a missing sample turning into silent fallback;
- an out-of-range parameter looking like success.
Audio should behave like a finite, explicit peripheral, not like "automatic sound".
### Asset
In `asset`, status-first better separates:
- request errors;
- asynchronous lifecycle;
- invalid commit/cancel;
- unknown handle.
That fits the request + poll + commit model instead of pretending loading is instantaneous.
### FS / MEMCARD
In persistence, status-first prevents the worst category of error: "it seemed to save".
Casos como:
- slot vazio;
- storage cheio;
- conflito;
- corrupcao;
- backend indisponivel;
must appear as observable state because the game and the Hub/OS need to react to them.
## Design Smells
Signs that the contract is still weak:
- the operation can fail, but returns `void`;
- there is implicit fallback to a default resource;
- the documentation depends on "in practice this should not happen";
- `Panic` appears for app input errors;
- the same domain mixes silent no-op and explicit status;
- return payload does not make clear when it is valid.
## Historical Anchors
This guide consolidates the intuition that first appeared in these historical snapshots:
- [`historical-gfx-status-first-fault-and-return-contract.md`](LSN-0006-historical-gfx-status-first-fault-and-return-contract.md)
- [`historical-audio-status-first-fault-and-return-contract.md`](LSN-0003-historical-audio-status-first-fault-and-return-contract.md)
- [`historical-asset-status-first-fault-and-return-contract.md`](LSN-0002-historical-asset-status-first-fault-and-return-contract.md)
- [`historical-game-memcard-slots-surface-and-semantics.md`](LSN-0005-historical-game-memcard-slots-surface-and-semantics.md)
- [`historical-retired-fault-and-input-decisions.md`](LSN-0007-historical-retired-fault-and-input-decisions.md)
Use the snapshots for historical context. Use the specs for the current normative contract.
@@ -0,0 +1,58 @@
---
id: LSN-0017
ticket: legacy-runtime-learn-import
title: Time Model and Cycles
created: 2026-03-27
tags: [migration, tech-debt]
---
# Time Model and Cycles
Status: pedagogical
Companion spec: [`../specs/01-time-model-and-cycles.md`](../../specs/01-time-model-and-cycles.md)
PROMETEU treats time as an explicit part of the machine.
## Core Idea
Nothing happens "for free" or "instantly". The programmer should think in terms of:
- machine rhythm;
- cost per frame;
- distribution of work over time;
- the architectural impact of when each system runs.
## Why Cycles Instead of Milliseconds
Milliseconds vary with platform, jitter, and real hardware. Cycles provide a cost metric that belongs to the PROMETEU machine rather than to the host.
That makes it easier to compare solutions, teach cost, and reason about performance without hiding the bill behind the operating system.
## Temporal Distribution As Design
One of the most important intuitions in PROMETEU is that optimization is not only about "doing less", it is about deciding **when** to do it.
Useful examples:
- AI at 30 Hz;
- pathfinding at 15 Hz;
- frame-count-driven timers;
- separation between heavy update work and presentation.
## Why CAP Fits Here
CAP reinforces this reading of time as technical evidence. It does not exist to block execution, but to make visible:
- spikes;
- bottlenecks;
- cost distribution;
- temporal architecture decisions.
## Teaching Value
This model helps teach:
- execution planning;
- technical tradeoffs;
- reading real profiling evidence;
- temporal organization as an architectural tool.
@@ -0,0 +1,48 @@
---
id: LSN-0018
ticket: legacy-runtime-learn-import
title: Touch Mental Model
created: 2026-03-27
tags: [migration, tech-debt]
---
# Touch Mental Model
Status: pedagogical
Companion spec: [`../specs/07-touch-peripheral.md`](../../specs/07-touch-peripheral.md)
PROMETEU uses TOUCH as an absolute, deterministic pointer, not as a gesture-rich surface.
## Design Intuition
The central principle is simple:
- a single active pointer;
- no implicit gestures;
- no acceleration;
- no heuristics;
- the same behavior on desktop, mobile, and dedicated hardware.
If a behavior cannot be guaranteed portably, it does not enter the machine.
## Why Single Pointer
Physical multitouch may exist on the host, but the machine chooses a single logical pointer to avoid:
- capture ambiguities;
- differences between platforms;
- semantic shifts between mouse, real touch, and built-in touchscreen.
## Good Uses
TOUCH works well for:
- UI;
- direct selection;
- drag-and-drop;
- pointing puzzles;
- trails, cuts, and contact-based mechanics.
## What Games Must Do Themselves
If a game wants gestures, swipe, long-press, or smoothing, it must build that on top of the raw per-frame state. The peripheral does not interpret intent.