diff --git a/README.md b/README.md index 98d07859..29489374 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ PROMETEU is the machine. The VM/runtime is one subsystem inside that machine. Authoritative documents: - [`docs/runtime/virtual-machine/ARCHITECTURE.md`](docs/vm-arch/ARCHITECTURE.md) is normative for VM/runtime invariants. -- [`docs/runtime/specs/README.md`](docs/specs/README.md) describes the broader PROMETEU machine, hardware model, and fantasy console context. +- [`docs/runtime/specs/README.md`](docs/specs/runtime/README.md) describes the broader PROMETEU machine, hardware model, and fantasy console context. - Supporting material under `docs/` may expand, explain, or propose changes, but it must not silently collapse the whole machine into the VM layer. --- diff --git a/docs/specs/01-time-model-and-cycles.md b/docs/specs/runtime/01-time-model-and-cycles.md similarity index 100% rename from docs/specs/01-time-model-and-cycles.md rename to docs/specs/runtime/01-time-model-and-cycles.md diff --git a/docs/specs/02-vm-instruction-set.md b/docs/specs/runtime/02-vm-instruction-set.md similarity index 96% rename from docs/specs/02-vm-instruction-set.md rename to docs/specs/runtime/02-vm-instruction-set.md index 3313b495..649de59f 100644 --- a/docs/specs/02-vm-instruction-set.md +++ b/docs/specs/runtime/02-vm-instruction-set.md @@ -12,7 +12,7 @@ It is intentionally narrower than the broader machine specs: - verifier boundary; - relationship between the VM and adjacent specs. -For the bytecode-level instruction contract, see [`../virtual-machine/ISA_CORE.md`](../vm-arch/ISA_CORE.md). +For the bytecode-level instruction contract, see [`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md). ## 1 Scope @@ -67,7 +67,7 @@ Each frame: ## 4 Instruction Families -The public VM instruction surface is documented at the bytecode level in [`../virtual-machine/ISA_CORE.md`](../vm-arch/ISA_CORE.md). At the machine/spec level, the instruction families are: +The public VM instruction surface is documented at the bytecode level in [`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md). At the machine/spec level, the instruction families are: - execution control: - `NOP`, `HALT`, `JMP`, `JMP_IF_FALSE`, `JMP_IF_TRUE`, `TRAP`, `FRAME_SYNC` diff --git a/docs/specs/02a-vm-values-and-calling-convention.md b/docs/specs/runtime/02a-vm-values-and-calling-convention.md similarity index 100% rename from docs/specs/02a-vm-values-and-calling-convention.md rename to docs/specs/runtime/02a-vm-values-and-calling-convention.md diff --git a/docs/specs/02b-vm-function-values-and-closures.md b/docs/specs/runtime/02b-vm-function-values-and-closures.md similarity index 100% rename from docs/specs/02b-vm-function-values-and-closures.md rename to docs/specs/runtime/02b-vm-function-values-and-closures.md diff --git a/docs/specs/03-memory-stack-heap-and-allocation.md b/docs/specs/runtime/03-memory-stack-heap-and-allocation.md similarity index 100% rename from docs/specs/03-memory-stack-heap-and-allocation.md rename to docs/specs/runtime/03-memory-stack-heap-and-allocation.md diff --git a/docs/specs/04-gfx-peripheral.md b/docs/specs/runtime/04-gfx-peripheral.md similarity index 100% rename from docs/specs/04-gfx-peripheral.md rename to docs/specs/runtime/04-gfx-peripheral.md diff --git a/docs/specs/05-audio-peripheral.md b/docs/specs/runtime/05-audio-peripheral.md similarity index 100% rename from docs/specs/05-audio-peripheral.md rename to docs/specs/runtime/05-audio-peripheral.md diff --git a/docs/specs/06-input-peripheral.md b/docs/specs/runtime/06-input-peripheral.md similarity index 100% rename from docs/specs/06-input-peripheral.md rename to docs/specs/runtime/06-input-peripheral.md diff --git a/docs/specs/07-touch-peripheral.md b/docs/specs/runtime/07-touch-peripheral.md similarity index 100% rename from docs/specs/07-touch-peripheral.md rename to docs/specs/runtime/07-touch-peripheral.md diff --git a/docs/specs/08-save-memory-and-memcard.md b/docs/specs/runtime/08-save-memory-and-memcard.md similarity index 100% rename from docs/specs/08-save-memory-and-memcard.md rename to docs/specs/runtime/08-save-memory-and-memcard.md diff --git a/docs/specs/09-events-and-concurrency.md b/docs/specs/runtime/09-events-and-concurrency.md similarity index 100% rename from docs/specs/09-events-and-concurrency.md rename to docs/specs/runtime/09-events-and-concurrency.md diff --git a/docs/specs/09a-coroutines-and-cooperative-scheduling.md b/docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md similarity index 100% rename from docs/specs/09a-coroutines-and-cooperative-scheduling.md rename to docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md diff --git a/docs/specs/10-debug-inspection-and-profiling.md b/docs/specs/runtime/10-debug-inspection-and-profiling.md similarity index 100% rename from docs/specs/10-debug-inspection-and-profiling.md rename to docs/specs/runtime/10-debug-inspection-and-profiling.md diff --git a/docs/specs/11-portability-and-cross-platform-execution.md b/docs/specs/runtime/11-portability-and-cross-platform-execution.md similarity index 100% rename from docs/specs/11-portability-and-cross-platform-execution.md rename to docs/specs/runtime/11-portability-and-cross-platform-execution.md diff --git a/docs/specs/12-firmware-pos-and-prometeuhub.md b/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md similarity index 100% rename from docs/specs/12-firmware-pos-and-prometeuhub.md rename to docs/specs/runtime/12-firmware-pos-and-prometeuhub.md diff --git a/docs/specs/13-cartridge.md b/docs/specs/runtime/13-cartridge.md similarity index 100% rename from docs/specs/13-cartridge.md rename to docs/specs/runtime/13-cartridge.md diff --git a/docs/specs/14-boot-profiles.md b/docs/specs/runtime/14-boot-profiles.md similarity index 100% rename from docs/specs/14-boot-profiles.md rename to docs/specs/runtime/14-boot-profiles.md diff --git a/docs/specs/15-asset-management.md b/docs/specs/runtime/15-asset-management.md similarity index 100% rename from docs/specs/15-asset-management.md rename to docs/specs/runtime/15-asset-management.md diff --git a/docs/specs/16-host-abi-and-syscalls.md b/docs/specs/runtime/16-host-abi-and-syscalls.md similarity index 100% rename from docs/specs/16-host-abi-and-syscalls.md rename to docs/specs/runtime/16-host-abi-and-syscalls.md diff --git a/docs/specs/16a-syscall-policies.md b/docs/specs/runtime/16a-syscall-policies.md similarity index 100% rename from docs/specs/16a-syscall-policies.md rename to docs/specs/runtime/16a-syscall-policies.md diff --git a/docs/specs/README.md b/docs/specs/runtime/README.md similarity index 94% rename from docs/specs/README.md rename to docs/specs/runtime/README.md index f8429fff..9508d066 100644 --- a/docs/specs/README.md +++ b/docs/specs/runtime/README.md @@ -19,9 +19,9 @@ Belongs in `docs/runtime/specs/`: Does not belong in `docs/runtime/specs/` as the primary canonical source: - internal architectural invariants of the VM/runtime: - [`../virtual-machine/ARCHITECTURE.md`](../vm-arch/ARCHITECTURE.md); + [`../virtual-machine/ARCHITECTURE.md`](../../vm-arch/ARCHITECTURE.md); - bytecode-level ISA: - [`../virtual-machine/ISA_CORE.md`](../vm-arch/ISA_CORE.md); + [`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md); - pedagogical guides and learning material: [`../learn/README.md`](../runtime/learn/README.md); - agendas, proposals, and plans: @@ -87,8 +87,8 @@ In the current state, no chapter under the active `docs/runtime/specs/` root is ## Authority Model - `docs/runtime/specs/` defines the PROMETEU machine and its external execution surfaces. -- [`../virtual-machine/ARCHITECTURE.md`](../vm-arch/ARCHITECTURE.md) remains the canonical authority for internal VM/runtime invariants. -- [`../virtual-machine/ISA_CORE.md`](../vm-arch/ISA_CORE.md) remains the authority for the bytecode ISA. +- [`../virtual-machine/ARCHITECTURE.md`](../../vm-arch/ARCHITECTURE.md) remains the canonical authority for internal VM/runtime invariants. +- [`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md) remains the authority for the bytecode ISA. - When a chapter here touches the VM, it may complement but must not contradict the canonical VM/runtime architecture. ## Rules for Future Chapters diff --git a/docs/vm-arch/ARCHITECTURE.md b/docs/vm-arch/ARCHITECTURE.md index 4f03840b..6b5a883b 100644 --- a/docs/vm-arch/ARCHITECTURE.md +++ b/docs/vm-arch/ARCHITECTURE.md @@ -9,7 +9,7 @@ Scope boundary: - PROMETEU itself is a fantasy handheld / fantasy console with a broader machine model, firmware model, cartridge model, and virtual hardware surface. - This document does not define the whole PROMETEU machine. - This document defines the VM/runtime subsystem that executes bytecode inside that machine. -- For broader machine-level framing, see [`../specs/README.md`](../specs/README.md). +- For broader machine-level framing, see [`../specs/README.md`](../specs/runtime/README.md). Document roles: