implements PLN-0127
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 61.95% (17766/28676)
* Branch Coverage: 52.69% (6860/13019)
* Lines of Code: 28676
* Cyclomatic Complexity: 11490
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 648
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 61.95% (17766/28676)
* Branch Coverage: 52.69% (6860/13019)
* Lines of Code: 28676
* Cyclomatic Complexity: 11490
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 648
Publish the console ABI authority map: runtime catalogs win, PBS stdlib is delivery. Recut specs 18, 8, and 6.2 and lock them with ConsoleAbiAuthoritySpecTest. Housekeep DSC-0061 with LSN-0064.
This commit is contained in:
+17
-6
@@ -15,6 +15,10 @@ This document defines the current contract between:
|
||||
Its purpose is to let compiler and runtime work in parallel without diverging on the most critical boundary:
|
||||
how host-backed SDK calls become load-time-resolved numeric syscalls.
|
||||
|
||||
PBS `declare host` / `[Host]` shells are compile-time delivery. The
|
||||
loader-facing catalog is runtime-owned. This document MUST NOT publish syscall
|
||||
IDs or `SyscallMeta`.
|
||||
|
||||
This document is intentionally narrower than a full PBX or VM specification.
|
||||
It focuses on loader behavior and the minimum artifact contract the loader must consume.
|
||||
|
||||
@@ -44,16 +48,20 @@ This document does not define:
|
||||
|
||||
This document follows two prior decisions:
|
||||
|
||||
1. Canonical host identity is defined by the hardware ABI as `(module, name, version)`.
|
||||
1. Canonical host identity is defined by the runtime host registry as `(module, name, version)`.
|
||||
2. User code does not declare host bindings directly; SDK/toolchain-controlled modules expose reserved `declare host` surfaces and the compiler lowers those usages into PBX host-binding metadata.
|
||||
|
||||
PBS shells MUST repeat identities already published by the runtime registry
|
||||
(`../runtime/docs/specs/runtime/16-host-abi-and-syscalls.md` and `SyscallMeta`).
|
||||
They MUST NOT invent `(module, name, version)`.
|
||||
|
||||
This document therefore treats:
|
||||
|
||||
- `declare host Gfx { fn draw_pixel(...); }`
|
||||
- `declare host LowGfx { [Host(module = "gfx2d", name = "clear", version = 1)] fn clear(...); }`
|
||||
|
||||
as compile-time surface only, and treats:
|
||||
|
||||
- `("gfx", "draw_pixel", 1)`
|
||||
- `("gfx2d", "clear", 1)`
|
||||
|
||||
as the normative runtime-facing identity.
|
||||
|
||||
@@ -63,7 +71,7 @@ The host-binding pipeline is:
|
||||
|
||||
1. User code imports SDK surfaces such as `Gfx` from `@sdk:gfx` and `Composer` from `@sdk:composer`.
|
||||
2. The compiler resolves those surfaces against the selected stdlib line.
|
||||
3. The compiler maps each host-backed SDK member to a canonical identity `(module, name, version)`.
|
||||
3. The compiler maps each host-backed SDK member to a canonical identity `(module, name, version)` that already exists in the runtime host registry.
|
||||
4. The compiler emits those required canonical identities into the PBX `SYSC` table.
|
||||
5. The compiler emits pre-load host call sites as `HOSTCALL <sysc_index>`.
|
||||
6. At cartridge load time, the loader resolves `SYSC` entries against the host syscall registry.
|
||||
@@ -84,7 +92,7 @@ Every host binding is identified by the triple:
|
||||
|
||||
Rules:
|
||||
|
||||
- `module` is the canonical host subsystem namespace, such as `gfx` or `audio`.
|
||||
- `module` is the canonical host subsystem namespace, such as `gfx2d` or `asset`.
|
||||
- `name` is the canonical host operation name within that module.
|
||||
- `version` is the canonical ABI version of that host operation.
|
||||
- This identity is stable across source languages and SDK naming styles.
|
||||
@@ -310,7 +318,10 @@ Rules:
|
||||
- the loader resolves only against this canonical registry,
|
||||
- unknown identities are load errors,
|
||||
- successful resolution yields numeric syscall identifiers and associated metadata,
|
||||
- the resolved metadata is authoritative for capability gating and later runtime verification.
|
||||
- the resolved metadata is authoritative for capability gating and later runtime verification,
|
||||
- PBS `declare host` / `[Host]` shells MUST repeat identities from this registry,
|
||||
- PBS shells MUST NOT invent `(module, name, version)`,
|
||||
- this specification MUST NOT publish the syscall catalog; runtime spec 16 and `SyscallMeta` do.
|
||||
|
||||
For the current asset runtime surface, the canonical registry entries include:
|
||||
|
||||
|
||||
+49
-30
@@ -16,7 +16,11 @@ Its purpose is to make the stdlib:
|
||||
|
||||
This document complements the normative language-level model in:
|
||||
|
||||
- [5. Manifest, Stdlib, and SDK Resolution Specification.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/docs/specs/pbs/5.%20Manifest,%20Stdlib,%20and%20SDK%20Resolution%20Specification.md)
|
||||
- [5. Manifest, Stdlib, and SDK Resolution Specification.md](5.%20Manifest%2C%20Stdlib%2C%20and%20SDK%20Resolution%20Specification.md)
|
||||
|
||||
This document is PBS packaging. It MUST NOT define console ABI. Intrinsic
|
||||
`final_id` values and host `SyscallMeta` remain runtime-owned. Physical stdlib
|
||||
path MUST NOT imply VM-owned versus host-backed ownership.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
@@ -53,52 +57,66 @@ The recommended Studio layout is:
|
||||
```text
|
||||
prometeu-compiler/frontends/prometeu-frontend-pbs/
|
||||
src/main/resources/
|
||||
stdlib/
|
||||
1/
|
||||
sdk/
|
||||
composer/
|
||||
main.pbs
|
||||
mod.barrel
|
||||
gfx/
|
||||
main.pbs
|
||||
mod.barrel
|
||||
asset/
|
||||
main.pbs
|
||||
mod.barrel
|
||||
audio/
|
||||
main.pbs
|
||||
mod.barrel
|
||||
core/
|
||||
math/
|
||||
main.pbs
|
||||
mod.barrel
|
||||
<target>/
|
||||
stdlib/
|
||||
1/
|
||||
core/
|
||||
color/
|
||||
main.pbs
|
||||
mod.barrel
|
||||
sdk/
|
||||
asset/
|
||||
main.pbs
|
||||
mod.barrel
|
||||
composer/
|
||||
main.pbs
|
||||
mod.barrel
|
||||
gfx/
|
||||
main.pbs
|
||||
mod.barrel
|
||||
input/
|
||||
main.pbs
|
||||
mod.barrel
|
||||
log/
|
||||
main.pbs
|
||||
mod.barrel
|
||||
```
|
||||
|
||||
Interpretation:
|
||||
|
||||
- `stdlib/1` selects stdlib major line `1`,
|
||||
- `<target>` is the `AppMode` export name (`game` for the current line-1 environment),
|
||||
- `game/stdlib/1` selects stdlib major line `1` for that target,
|
||||
- `sdk` and `core` are reserved project spaces,
|
||||
- `composer`, `gfx`, `audio`, `math` are module paths within those reserved spaces,
|
||||
- current line `1` modules are `color`, `asset`, `composer`, `gfx`, `input`, and `log`,
|
||||
- `main.pbs` and `mod.barrel` form the interface module contents.
|
||||
|
||||
Current line `1` MUST NOT be documented as shipping `audio` or `@core:math`.
|
||||
Those names are not packaged in the current environment. `@sdk:input` is a
|
||||
VM-owned builtin shell; its path does not make it host-backed.
|
||||
|
||||
## 5. Logical Mapping
|
||||
|
||||
The compiler must treat the physical layout as a logical stdlib environment.
|
||||
|
||||
Required mapping:
|
||||
|
||||
- `stdlib/<N>/sdk/gfx` -> `@sdk:gfx`
|
||||
- `stdlib/<N>/sdk/composer` -> `@sdk:composer`
|
||||
- `stdlib/<N>/sdk/asset` -> `@sdk:asset`
|
||||
- `stdlib/<N>/sdk/audio` -> `@sdk:audio`
|
||||
- `stdlib/<N>/core/math` -> `@core:math`
|
||||
- `stdlib/<N>/core/math/vector` -> `@core:math/vector`
|
||||
- `<target>/stdlib/<N>/<space>/<module>` -> `@<space>:<module>`
|
||||
|
||||
Current line `1` (`game`) mapping:
|
||||
|
||||
- `game/stdlib/1/core/color` -> `@core:color`
|
||||
- `game/stdlib/1/sdk/asset` -> `@sdk:asset`
|
||||
- `game/stdlib/1/sdk/composer` -> `@sdk:composer`
|
||||
- `game/stdlib/1/sdk/gfx` -> `@sdk:gfx`
|
||||
- `game/stdlib/1/sdk/input` -> `@sdk:input`
|
||||
- `game/stdlib/1/sdk/log` -> `@sdk:log`
|
||||
|
||||
Rules:
|
||||
|
||||
- physical storage is an implementation detail,
|
||||
- logical module identity is authoritative,
|
||||
- callers of the resolver should work with logical addresses such as `@sdk:gfx` and `@sdk:composer`, not resource paths.
|
||||
- callers of the resolver should work with logical addresses such as `@sdk:gfx` and `@core:color`, not resource paths,
|
||||
- physical path MUST NOT imply VM-owned versus host-backed ownership.
|
||||
|
||||
## 6. Module File Convention
|
||||
|
||||
@@ -150,7 +168,8 @@ Minimum operations:
|
||||
|
||||
- `resolve(@sdk:gfx)`
|
||||
- `resolve(@sdk:composer)`
|
||||
- `resolve(@core:math/vector)`
|
||||
- `resolve(@sdk:input)`
|
||||
- `resolve(@core:color)`
|
||||
|
||||
### 7.3 `StdlibModuleSource`
|
||||
|
||||
|
||||
@@ -7,6 +7,9 @@ Applies to: normative stdlib-facing API surface, reserved stdlib project spaces,
|
||||
|
||||
This document will define the normative user-facing standard-library surface for PBS.
|
||||
|
||||
This document is PBS delivery. It does not own console ABI. Intrinsic
|
||||
`final_id` values and host syscall metadata are runtime-owned.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
@@ -28,15 +31,22 @@ This document does not define:
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
2. `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
3. `6. VM-owned vs Host-backed.md`
|
||||
4. `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
5. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
6. This document
|
||||
1. Runtime intrinsic catalog (`../runtime/docs/vm-arch/INTRINSICS.csv`; Studio mirror `docs/vm-arch/INTRINSICS.csv`)
|
||||
2. Runtime host ABI (`../runtime/docs/specs/runtime/16-host-abi-and-syscalls.md` and `SyscallMeta`)
|
||||
3. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
4. `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
5. `6. VM-owned vs Host-backed.md`
|
||||
6. `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
7. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
8. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence specs, it is invalid.
|
||||
|
||||
This document MUST NOT define numeric syscall identifiers, intrinsic `final_id`
|
||||
values, or `SyscallMeta`. PBS `[Host]` and `[IntrinsicCall]` attributes MUST
|
||||
repeat identities already published by those runtime catalogs. They MUST NOT
|
||||
invent console ABI.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
@@ -57,6 +67,9 @@ The following inputs are already fixed elsewhere and must not be contradicted he
|
||||
- User code must import stdlib modules explicitly.
|
||||
- Canonical host identity comes from reserved host-binding metadata, not from source owner spelling.
|
||||
- VM-owned builtin type, builtin constant, and intrinsic surfaces may be exposed through reserved stdlib shells without transferring semantic ownership away from the VM.
|
||||
- Console ABI authority is runtime-owned. PBS stdlib is delivery.
|
||||
- Reserved project-space path (`@sdk:*` / `@core:*`) MUST NOT imply VM-owned versus host-backed ownership.
|
||||
- Current stdlib line `1` ships a VM-owned builtin input shell at `@sdk:input`. That exception does not make `@sdk:*` the VM-owned space.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
@@ -78,7 +91,10 @@ The following items remain to be closed in future agenda discussion.
|
||||
- Whether `@core:*` is specified as language-adjacent utility surface or as ordinary stdlib contract.
|
||||
- How stdlib API evolution is documented and conformance-tested.
|
||||
- Whether some interface modules remain toolchain-private and outside user-facing stdlib surface.
|
||||
- Whether builtin shells may appear in `@sdk:*` as well as `@core:*`, or whether `@sdk:*` should remain host-facing only by policy.
|
||||
|
||||
Settled by DEC-0048 and not reopened here:
|
||||
|
||||
- Builtin shells MAY appear in `@sdk:*` as well as `@core:*`. Path MUST NOT imply ownership. Current line `1` exception: `@sdk:input`.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
@@ -127,6 +143,12 @@ Rules:
|
||||
- but ownership remains governed by the VM-owned vs host-backed classification,
|
||||
- and placing a builtin shell in stdlib does not make it host-backed.
|
||||
|
||||
Current line `1` exception:
|
||||
|
||||
- `@sdk:input` exposes VM-owned builtin input types through `[BuiltinType]` and `[IntrinsicCall]`.
|
||||
- that module is not host-backed.
|
||||
- the `@sdk:*` preference for host-backed APIs still holds for new host modules.
|
||||
|
||||
## 11. Builtin Shell Surfaces
|
||||
|
||||
Reserved stdlib modules may expose builtin declarations as compile-time-only
|
||||
@@ -205,6 +227,10 @@ Their canonical runtime-facing identities still come from builtin metadata such
|
||||
as `BuiltinType(name="vec2", version=1)` and
|
||||
`BuiltinConst(target="vec2", name="zero", version=1)`.
|
||||
|
||||
Current stdlib line `1` ships `Color` at `@core:color`. The `@core:math` import
|
||||
above is an identity illustration, not a claim that `@core:math` is packaged in
|
||||
line `1`.
|
||||
|
||||
## 14. Deterministic Stdlib Surface Failures
|
||||
|
||||
At minimum, a conforming implementation must reject:
|
||||
@@ -214,3 +240,15 @@ At minimum, a conforming implementation must reject:
|
||||
3. a user-facing stdlib module that exports executable PBS bodies for builtin semantics,
|
||||
4. a stdlib line that exposes conflicting canonical builtin identities through the same resolved environment,
|
||||
5. a stdlib line that exposes conflicting canonical host identities through the same resolved environment.
|
||||
|
||||
## 15. Console ABI Non-Ownership
|
||||
|
||||
This specification MUST NOT:
|
||||
|
||||
1. define numeric syscall identifiers,
|
||||
2. define intrinsic `final_id` values,
|
||||
3. publish `SyscallMeta`,
|
||||
4. or treat PBS `[Host]` / `[IntrinsicCall]` attributes as the ABI catalog.
|
||||
|
||||
PBS shells MUST repeat identities already published by the runtime catalogs
|
||||
named in section 3.
|
||||
|
||||
Reference in New Issue
Block a user