Intrepid/prometeu-studio
Intrepid/prometeu-studio
4
0
Fork 0
Code Pull Requests Activity
prometeu-studio/discussion/lessons/DSC-0061-multi-frontend-sdk-canonical-definition/LSN-0064-runtime-owns-console-abi-pbs-is-delivery.md
bQUARKz 2b881f5a76
Some checks are pending
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
Details
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.
Details
Test / Build skipped: 15, passed: 648
Details
implements PLN-0127 
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.
2026-09-19 02:35:05 +01:00

5.1 KiB
Raw Blame History

id ticket title created tags
LSN-0064 multi-frontend-sdk-canonical-definition Runtime owns console ABI; PBS is delivery 2026-09-19
compiler
compiler-general
sdk
stdlib
hostcalls
intrinsics
multi-frontend

Runtime owns console ABI; PBS is delivery

Original Problem

"SDK" mixed three layers: platform ABI, PBS stdlib shells, and docs. The PBS compiler reads [Host] and [IntrinsicCall] from .pbs files. It does not read the runtime registry. Intrinsics already had a CSV in the runtime repository, a handwritten Java enum, and a disabled parity test. Spec 8 documented audio and @core:math. Disk had game/stdlib/1 with color, asset, composer, gfx, input, and log. Spec 18 preferred @sdk:* for host APIs while @sdk:input was a builtin.

There is no second language in this phase. The risk was not a missing generic SDK. The risk was treating PBS shells, or a stale spec, as console ABI. DEC-0047 had already classified canonical host identity as platform-owned and left PbsHostAdmissionValidator in the PBS package until a shared source existed.

Consolidated Decision

This discussion was an audit. It published an authority map. It did not create a canonical schema, generate bindings, enable intrinsic parity, or move the host-admission validator.

The console has two distinct axes:

  • VM-owned intrinsics, identity canonical_name@version plus final_id;
  • host-backed calls, identity (module, name, version) plus capability.

Do not unify those axes into one catalog while PBS is the only frontend.

Conflict resolution:

  • Intrinsic conflict: runtime/docs/vm-arch/INTRINSICS.csv wins. Studio docs/vm-arch/INTRINSICS.csv is a mirror. IRVMIntrinsicDefinition is derived. PBS [BuiltinType] / [IntrinsicCall] shells are delivery.
  • Host conflict: runtime spec 16 and SyscallMeta win. PBS [Host] attributes must not define ABI. They declare the shell the PBS compiler reads today.

@sdk:* / @core:* paths must not imply ownership. @sdk:input is a registered builtin exception. It was not moved to @core.

PBS conformance means PBS shells and docs match runtime ABI, not the reverse. PbsHostAdmissionValidator may stay in the PBS package. E_HOST_* is not eternal PBS semantics.

Final Implementation

The work was editorial and test-facing.

Spec 18 now states that PBS stdlib is delivery and must not define syscall IDs, intrinsic final_id values, or SyscallMeta. Runtime catalogs outrank it. @sdk:input is recorded as the current builtin exception.

Spec 8 now documents <target>/stdlib/<N>/... with current line 1 at game/stdlib/1: core/color and sdk/{asset,composer,gfx,input,log}. It no longer ships audio or @core:math as current modules.

Spec 6.2 now requires PBS host shells to repeat the runtime registry and forbids inventing (module, name, version). The authority example is ("gfx2d", "clear", 1).

ConsoleAbiAuthoritySpecTest locks those sentences. No production compiler code, stdlib .pbs, or validator package moved. The intrinsic parity test stays disabled.

Examples

Runtime wins:

  • color.rgb@1 / final_id 0x1101 come from INTRINSICS.csv;
  • ("gfx2d", "clear", 1) and ("asset", "load", 1) come from SyscallMeta.

PBS delivers, and does not own, those identities:

  • @core:color with [BuiltinType(name = "color", version = 1)];
  • @sdk:gfx LowGfx.clear with [Host(module = "gfx2d", name = "clear", version = 1)];
  • @sdk:input with [BuiltinType] / [IntrinsicCall] under @sdk.

Stale docs that the recut removed as current line-1 inventory:

  • stdlib/1/sdk/audio;
  • @core:math as a packaged module.

Pitfalls

  • Do not treat PBS stdlib as the ABI catalog because the compiler already reads it. That is convenience, not authority.
  • Do not create HOSTCALLS.csv or generate the Java enum because the map now exists. A catalog waits on a second consumer.
  • Do not move PbsHostAdmissionValidator on the strength of this map. DEC-0047 classified identity as platform; this discussion published who wins; the validator still has no shared catalog to consume.
  • Do not read @sdk as host and @core as VM. Path is packaging. @sdk:input is builtin.
  • Do not enable IRVMIntrinsicRegistryParityTest as a side effect of a doc recut. That is compiler/runtime sync, not PBS packaging conformance.
  • Do not put the authority map only in a decision. Housekeep deletes workflow artifacts. Specs and this lesson keep the map.

References

  • Decision: DEC-0048
  • Plan: PLN-0127
  • Related lesson: LSN-0063 - Language vs platform validation ownership
  • Related lesson: LSN-0061 - PBX is the language-neutral runtime boundary
  • docs/specs/compiler/18. Standard Library Surface Specification.md
  • docs/specs/compiler-languages/pbs/8. Stdlib Environment Packaging and Loading Specification.md
  • docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md
  • docs/vm-arch/README.md
  • ../runtime/docs/vm-arch/INTRINSICS.csv
  • ../runtime/docs/specs/runtime/16-host-abi-and-syscalls.md
  • prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/ConsoleAbiAuthoritySpecTest.java