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

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:
2026-09-19 02:35:05 +01:00
parent 4d8dcf28bb
commit 2b881f5a76
7 changed files with 343 additions and 123 deletions
@@ -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:
@@ -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.