docs: replace ephemeral workflow references with durable lessons
This commit is contained in:
@@ -3,7 +3,9 @@
|
||||
Domain: VM program metadata, binary format, typed storage and resource boundaries
|
||||
Function: normative
|
||||
|
||||
This chapter publishes DEC-0045 through PLN-0176. It defines the required v1 contract; implementation is being migrated and this publication is not a claim that all execution paths already satisfy it. The callable/closure/coroutine type boundary remains separately specified: no provisional untyped reference type is authorized. Existing closure/coroutine behavior must be preserved until its approved replacement can be integrated.
|
||||
This chapter defines the required v1 contract; implementation is being migrated and this publication is not a claim that all execution paths already satisfy it. The callable/closure/coroutine type boundary remains separately specified: no provisional untyped reference type is authorized. Existing closure/coroutine behavior must be preserved until its approved replacement can be integrated.
|
||||
|
||||
Didactic companion: [Registry Boundaries and Owned Values](../../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md).
|
||||
|
||||
The requirements below use MUST/MUST NOT semantics. The Registry owns type/function identity, storage shapes and signatures; other chapters retain authority over scheduling, collection operations, cartridge boot and host ABI behavior outside these requirements.
|
||||
|
||||
|
||||
@@ -9,8 +9,7 @@ Didactic companion: [`../learn/mental-model-gfx.md`](../runtime/learn/mental-mod
|
||||
|
||||
The **GFX** peripheral is responsible for generating images in PROMETEU.
|
||||
|
||||
`DEC-0030` defines the current logical render boundary. PROMETEU render
|
||||
production is split from render implementation:
|
||||
PROMETEU logical render production is separate from render implementation:
|
||||
|
||||
```text
|
||||
domain buffers during logical frame
|
||||
@@ -121,8 +120,10 @@ This guarantees:
|
||||
|
||||
## 4. Asynchronous Render Boundary
|
||||
|
||||
`DEC-0031` defines the asynchronous render boundary. The contract applies even
|
||||
when the current implementation consumes submissions synchronously.
|
||||
The asynchronous render boundary applies even when the current implementation
|
||||
consumes submissions synchronously. [Render Workers Need a Closed Packet Contract](../../../discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md)
|
||||
explains the packet and ownership model; [Render Workers Publish Frames, Hosts Present Them](../../../discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md)
|
||||
explains its worker/publication implementation.
|
||||
|
||||
### 4.1 Complete packet contract
|
||||
|
||||
|
||||
@@ -7,9 +7,9 @@ Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../
|
||||
|
||||
## 1 Scope
|
||||
|
||||
This chapter defines the machine-visible diagnostics and profiling surface of PROMETEU after `DEC-0009`.
|
||||
This chapter defines the machine-visible diagnostics and profiling surface of PROMETEU.
|
||||
|
||||
`DEC-0009` locks debug tooling and certification output as host-owned concerns. The runtime machine contract therefore exposes only bounded operational diagnostics and deterministic telemetry production, not a general-purpose guest-visible debug surface.
|
||||
Debug tooling and certification output are host-owned concerns. The runtime machine contract therefore exposes only bounded operational diagnostics and deterministic telemetry production, not a general-purpose guest-visible debug surface. The rationale is explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md).
|
||||
|
||||
It covers:
|
||||
|
||||
|
||||
@@ -2,9 +2,11 @@
|
||||
|
||||
**Domain:** runtime host tooling. **Function:** normative.
|
||||
|
||||
This chapter implements Studio DSC-0068 / DEC-0060 baseline v1, runtime phase
|
||||
of PLN-0139. The host owns this wire contract. It does not change guest ABI,
|
||||
firmware, VM, frame/input semantics or the desktop DevTools protocol.
|
||||
This chapter defines the v1 automation wire contract owned by the headless host.
|
||||
It does not change guest ABI, firmware, VM, frame/input semantics or the desktop
|
||||
DevTools protocol.
|
||||
|
||||
The observation model is explained in [Deterministic Observation Must Follow the Active Producer](../../../discussion/lessons/DSC-0050-headless-automation-host-hardening/LSN-0058-deterministic-observation-must-follow-the-active-producer.md).
|
||||
|
||||
## Process and transport
|
||||
|
||||
|
||||
@@ -129,7 +129,7 @@ Even with `codec = NONE`, `GLYPH` still requires bank-specific decode from its s
|
||||
|
||||
#### 4.1.1 Metadata Normalization
|
||||
|
||||
Following `DEC-0004`, the `AssetEntry.metadata` field must be structured in segmented form to avoid ambiguity.
|
||||
The `AssetEntry.metadata` field must be structured in segmented form to avoid ambiguity. [Typed Helpers for Asset Metadata](../../../discussion/lessons/DSC-0017-asset-metadata-normalization/LSN-0023-typed-asset-metadata-helpers.md) explains the typed parsing pattern for this structure.
|
||||
|
||||
Required effective metadata fields for `GLYPH` at the root level:
|
||||
|
||||
@@ -281,9 +281,11 @@ Rules:
|
||||
- the visible contract MUST NOT expose byte-oriented bank occupancy as the canonical summary;
|
||||
- canonical bank names are `GLYPH` and `SOUNDS`;
|
||||
- detailed occupancy inspection remains host-owned and slot-based through slot references, not bank byte totals;
|
||||
- public runtime specs MUST NOT treat `bank.slot_info` or JSON bank inspection payloads as the long-term guest ABI after `DEC-0009`;
|
||||
- public runtime specs MUST NOT treat `bank.slot_info` or JSON bank inspection payloads as the long-term guest ABI;
|
||||
- any residual byte accounting MAY exist internally, but it is not part of the visible bank telemetry contract.
|
||||
|
||||
The rationale for this boundary is explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md).
|
||||
|
||||
## 6 Load Lifecycle
|
||||
|
||||
The runtime asset manager exposes a staged lifecycle:
|
||||
|
||||
@@ -15,7 +15,7 @@ It focuses on:
|
||||
|
||||
Operational policies such as capabilities, fault classes, determinism, GC interaction, budgeting, and blocking are split into a companion chapter.
|
||||
|
||||
Per `DEC-0009`, debug tooling and certification are host-owned concerns. This chapter therefore excludes general-purpose guest-visible debug syscalls from the canonical public ABI.
|
||||
Debug tooling and certification are host-owned concerns. This chapter therefore excludes general-purpose guest-visible debug syscalls from the canonical public ABI. The rationale is explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md).
|
||||
|
||||
## 1 Design Principles
|
||||
|
||||
@@ -246,7 +246,7 @@ ordering model.
|
||||
|
||||
### Bank diagnostics surface (`bank`, v1)
|
||||
|
||||
`DEC-0009` narrows the public bank contract:
|
||||
The public bank contract is bounded:
|
||||
|
||||
- `bank.info(bank_type) -> (used_slots, total_slots)` is the only surviving public bank diagnostic shape in v1;
|
||||
- `bank.info` exists only as a cheap deterministic operational summary aligned with the slot-first bank telemetry contract from [`15-asset-management.md`](15-asset-management.md);
|
||||
@@ -256,10 +256,13 @@ ordering model.
|
||||
|
||||
### Render surfaces (`composer`, `gfx2d`, `gfxui`, v1)
|
||||
|
||||
`DEC-0030` splits logical render production from render implementation. Public
|
||||
Logical render production is separate from render implementation. Public
|
||||
render syscalls mutate app-mode-specific domain buffers. They do not directly
|
||||
publish a framebuffer and do not call host presentation APIs.
|
||||
|
||||
[Render Workers Publish Frames, Hosts Present Them](../../../discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md)
|
||||
explains the ownership and publication model.
|
||||
|
||||
The canonical flow is:
|
||||
|
||||
```text
|
||||
|
||||
@@ -9,7 +9,7 @@ It complements [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md), whi
|
||||
|
||||
Unless a domain chapter explicitly narrows behavior further, this chapter is the transversal policy for all syscalls in v1.
|
||||
|
||||
Per `DEC-0009`, guest-visible syscalls must not exist merely for debug convenience or certification plumbing. Those concerns belong to host-owned tooling.
|
||||
Guest-visible syscalls must not exist merely for debug convenience or certification plumbing. Those concerns belong to host-owned tooling, as explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md).
|
||||
|
||||
## 1 Error Model: Faults vs Status Returns
|
||||
|
||||
|
||||
@@ -23,9 +23,8 @@ Does not belong in `docs/specs/runtime/` as the primary canonical source:
|
||||
- bytecode-level ISA:
|
||||
[`../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:
|
||||
`discussion/workflow/agendas/`, `discussion/workflow/decisions/` and `discussion/workflow/plans/`.
|
||||
[`../learn/README.md`](../runtime/learn/README.md) and
|
||||
[published lessons](../../../discussion/lessons/).
|
||||
|
||||
## Organization Rules
|
||||
|
||||
|
||||
Reference in New Issue
Block a user