discussion framework migration
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
{"type":"meta","next_id":{"DSC":2,"AGD":1,"DEC":1,"PLN":1,"LSN":19,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
+90
@@ -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.
|
||||
+137
@@ -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`.
|
||||
+125
@@ -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`.
|
||||
+96
@@ -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.
|
||||
+146
@@ -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.
|
||||
+119
@@ -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.
|
||||
+45
@@ -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.
|
||||
|
||||
+61
@@ -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`
|
||||
+207
@@ -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".
|
||||
+63
@@ -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.
|
||||
+51
@@ -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.
|
||||
+41
@@ -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.
|
||||
+60
@@ -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.
|
||||
+115
@@ -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.
|
||||
+163
@@ -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.
|
||||
+58
@@ -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.
|
||||
+48
@@ -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.
|
||||
Reference in New Issue
Block a user