Compare commits
3
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
2b881f5a76
|
||
|
|
4d8dcf28bb | ||
|
|
d7c2ec880f
|
@@ -1,10 +1,10 @@
|
|||||||
{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":47,"PLN":126,"LSN":63,"CLSN":1}}
|
{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":49,"PLN":128,"LSN":65,"CLSN":1}}
|
||||||
{"type":"discussion","id":"DSC-0065","status":"open","ticket":"multi-frontend-avoid-premature-abstractions","title":"Evitar abstracoes prematuras na preparacao multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","multi-frontend","simplicity"],"agendas":[{"id":"AGD-0068","file":"AGD-0068-multi-frontend-avoid-premature-abstractions.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
{"type":"discussion","id":"DSC-0065","status":"open","ticket":"multi-frontend-avoid-premature-abstractions","title":"Evitar abstracoes prematuras na preparacao multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","multi-frontend","simplicity"],"agendas":[{"id":"AGD-0068","file":"AGD-0068-multi-frontend-avoid-premature-abstractions.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||||
{"type":"discussion","id":"DSC-0064","status":"open","ticket":"multi-frontend-architectural-tests","title":"Testes arquiteturais para fronteiras multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","tests","multi-frontend"],"agendas":[{"id":"AGD-0067","file":"AGD-0067-multi-frontend-architectural-tests.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
{"type":"discussion","id":"DSC-0064","status":"open","ticket":"multi-frontend-architectural-tests","title":"Testes arquiteturais para fronteiras multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","tests","multi-frontend"],"agendas":[{"id":"AGD-0067","file":"AGD-0067-multi-frontend-architectural-tests.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||||
{"type":"discussion","id":"DSC-0063","status":"open","ticket":"multi-frontend-synthetic-test-frontend","title":"Frontend sintetico de teste para provar neutralidade do pipeline","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","frontend","tests","backend","multi-frontend"],"agendas":[{"id":"AGD-0066","file":"AGD-0066-multi-frontend-synthetic-test-frontend.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
{"type":"discussion","id":"DSC-0063","status":"open","ticket":"multi-frontend-synthetic-test-frontend","title":"Frontend sintetico de teste para provar neutralidade do pipeline","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","frontend","tests","backend","multi-frontend"],"agendas":[{"id":"AGD-0066","file":"AGD-0066-multi-frontend-synthetic-test-frontend.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||||
{"type":"discussion","id":"DSC-0062","status":"done","ticket":"multi-frontend-pvm-neutrality","title":"Neutralidade da PVM e identificacao PBX independente de PBS","created_at":"2026-07-15","updated_at":"2026-09-18","tags":["vm-arch","runtime","pvm","pbx","compiler","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0061","file":"discussion/lessons/DSC-0062-multi-frontend-pvm-neutrality/LSN-0061-pbx-runtime-boundary.md","status":"done","created_at":"2026-09-18","updated_at":"2026-09-18"}]}
|
{"type":"discussion","id":"DSC-0062","status":"done","ticket":"multi-frontend-pvm-neutrality","title":"Neutralidade da PVM e identificacao PBX independente de PBS","created_at":"2026-07-15","updated_at":"2026-09-18","tags":["vm-arch","runtime","pvm","pbx","compiler","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0061","file":"discussion/lessons/DSC-0062-multi-frontend-pvm-neutrality/LSN-0061-pbx-runtime-boundary.md","status":"done","created_at":"2026-09-18","updated_at":"2026-09-18"}]}
|
||||||
{"type":"discussion","id":"DSC-0061","status":"open","ticket":"multi-frontend-sdk-canonical-definition","title":"Auditoria e centralizacao gradual da definicao canonica do SDK","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","sdk","stdlib","hostcalls","intrinsics","multi-frontend"],"agendas":[{"id":"AGD-0064","file":"AGD-0064-multi-frontend-sdk-canonical-definition.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
{"type":"discussion","id":"DSC-0061","status":"done","ticket":"multi-frontend-sdk-canonical-definition","title":"Auditoria e centralizacao gradual da definicao canonica do SDK","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","sdk","stdlib","hostcalls","intrinsics","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0064","file":"discussion/lessons/DSC-0061-multi-frontend-sdk-canonical-definition/LSN-0064-runtime-owns-console-abi-pbs-is-delivery.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
|
||||||
{"type":"discussion","id":"DSC-0060","status":"open","ticket":"multi-frontend-validation-boundaries","title":"Separar validacoes de linguagem e validacoes de plataforma","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","backend","validation","multi-frontend"],"agendas":[{"id":"AGD-0063","file":"AGD-0063-multi-frontend-validation-boundaries.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
{"type":"discussion","id":"DSC-0060","status":"done","ticket":"multi-frontend-validation-boundaries","title":"Separar validacoes de linguagem e validacoes de plataforma","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","compiler-pbs","backend","validation","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0063","file":"discussion/lessons/DSC-0060-multi-frontend-validation-boundaries/LSN-0063-language-vs-platform-validation-ownership.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
|
||||||
{"type":"discussion","id":"DSC-0059","status":"done","ticket":"multi-frontend-common-lifecycle","title":"Extrair lifecycle comum das responsabilidades do frontend PBS","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","compiler-pbs","lifecycle","backend","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0062","file":"discussion/lessons/DSC-0059-multi-frontend-common-lifecycle/LSN-0062-common-lifecycle-assembly-stage.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
|
{"type":"discussion","id":"DSC-0059","status":"done","ticket":"multi-frontend-common-lifecycle","title":"Extrair lifecycle comum das responsabilidades do frontend PBS","created_at":"2026-07-15","updated_at":"2026-09-19","tags":["compiler","compiler-general","compiler-pbs","lifecycle","backend","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0062","file":"discussion/lessons/DSC-0059-multi-frontend-common-lifecycle/LSN-0062-common-lifecycle-assembly-stage.md","status":"done","created_at":"2026-09-19","updated_at":"2026-09-19"}]}
|
||||||
{"type":"discussion","id":"DSC-0058","status":"done","ticket":"multi-frontend-serializable-ir","title":"Manter a IR comum serializavel por design","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","ir","backend","serialization","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0060","file":"discussion/lessons/DSC-0058-multi-frontend-serializable-ir/LSN-0060-data-contract-first-for-serializable-irbackend.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
{"type":"discussion","id":"DSC-0058","status":"done","ticket":"multi-frontend-serializable-ir","title":"Manter a IR comum serializavel por design","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","ir","backend","serialization","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0060","file":"discussion/lessons/DSC-0058-multi-frontend-serializable-ir/LSN-0060-data-contract-first-for-serializable-irbackend.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||||
{"type":"discussion","id":"DSC-0057","status":"done","ticket":"multi-frontend-frontend-backend-contract","title":"Estabilizar contrato entre frontend e backend comum","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","ir","backend","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0059","file":"discussion/lessons/DSC-0057-multi-frontend-frontend-backend-contract/LSN-0059-common-irbackend-handoff-and-backend-guardrails.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
{"type":"discussion","id":"DSC-0057","status":"done","ticket":"multi-frontend-frontend-backend-contract","title":"Estabilizar contrato entre frontend e backend comum","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","ir","backend","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0059","file":"discussion/lessons/DSC-0057-multi-frontend-frontend-backend-contract/LSN-0059-common-irbackend-handoff-and-backend-guardrails.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||||
|
|||||||
+129
@@ -0,0 +1,129 @@
|
|||||||
|
---
|
||||||
|
id: LSN-0063
|
||||||
|
ticket: multi-frontend-validation-boundaries
|
||||||
|
title: Language vs platform validation ownership
|
||||||
|
created: 2026-09-19
|
||||||
|
tags: [compiler, compiler-general, compiler-pbs, backend, validation, multi-frontend]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Language vs platform validation ownership
|
||||||
|
|
||||||
|
## Original Problem
|
||||||
|
|
||||||
|
PBS mixed two kinds of rejection. Some failures only make sense with the
|
||||||
|
language: syntax, types, markers, barrel files, imports. Others belong to any
|
||||||
|
executable frontend: malformed `IRBackend`, invalid lifecycle declarations,
|
||||||
|
missing assembled wrappers, host-capability identity, bytecode/preload.
|
||||||
|
|
||||||
|
Without an ownership rule, the next frontend would copy PBS validators, or the
|
||||||
|
common layer would start knowing `[Init]`, barrel, and `E_SEM_*`. Spec 19 was
|
||||||
|
still titled as PBS verification, and the PBS diagnostics catalog listed
|
||||||
|
wrapper and boot-guard failures as PBS coverage.
|
||||||
|
|
||||||
|
Lifecycle assembly had already moved (`LSN-0062`). That proved the pattern. It
|
||||||
|
did not inventory the rest.
|
||||||
|
|
||||||
|
## Consolidated Decision
|
||||||
|
|
||||||
|
A validation lives at the lowest layer that understands the failure without
|
||||||
|
knowing the source language.
|
||||||
|
|
||||||
|
- Language: needs AST, tokens, a language marker, a barrel, or another source
|
||||||
|
rule.
|
||||||
|
- Platform: can be checked on `IRBackend`, `IRLifecycleDeclaration`, IRVM, PBX,
|
||||||
|
host/capability tables, or ids.
|
||||||
|
|
||||||
|
The discussion published that matrix. It did not extract a generic
|
||||||
|
validator-core and did not move validators whose common contract is not closed.
|
||||||
|
|
||||||
|
Host admission is split. PBS owns the source shape of `[Host]` and
|
||||||
|
`[Capability]`. Platform owns canonical `(module, name, version)` identity and
|
||||||
|
capability consistency once those facts exist on `IRReservedMetadata`. The
|
||||||
|
current validator may stay in the PBS package until a later plan. `E_HOST_*`
|
||||||
|
is not eternal PBS semantics.
|
||||||
|
|
||||||
|
The same fact may exist on both sides with distinct identities. PBS can report
|
||||||
|
`E_SEM_MISSING_PROJECT_FRAME`; the common layer still rejects an executable
|
||||||
|
declaration with no frame root.
|
||||||
|
|
||||||
|
Platform codes are `COMMON_*`, `LOWER_IRVM_*`, or `MARSHAL_*`. PBS keeps
|
||||||
|
`E_PARSE_*`, `E_SEM_*`, `E_LINK_*`, and `E_HOST_*`. Copy origin/span when
|
||||||
|
present; a missing origin is a structural error, not a reason to invent a span.
|
||||||
|
|
||||||
|
Linking and barrel stay language-owned. `Addressable` is platform-owned and was
|
||||||
|
classified only. SDK canonical source and the broad architectural harness stay
|
||||||
|
on adjacent discussions.
|
||||||
|
|
||||||
|
## Final Implementation
|
||||||
|
|
||||||
|
The work was editorial and test-facing.
|
||||||
|
|
||||||
|
Spec 19 is now `Compiler Verification and Safety Checks Specification`. Gates
|
||||||
|
S-U and S-I are unchanged. Section 11 states the classification rule, the
|
||||||
|
English ownership matrix, diagnostic identity, dual reporting, and the
|
||||||
|
host-admission split. It explicitly refuses validator-core extraction and
|
||||||
|
package moves.
|
||||||
|
|
||||||
|
PBS diagnostics spec 12 keeps marker, syntax, semantics, linking, and
|
||||||
|
host-attribute coverage. Common structural failures now point at spec 19
|
||||||
|
section 11 and spec 20 instead of appearing as PBS required coverage.
|
||||||
|
|
||||||
|
Spec 20 cross-references that same compiler-general ownership. The conformance
|
||||||
|
matrix added `G19-11.1` through `G19-11.6` and `PBS12-11`.
|
||||||
|
`CommonBackendArchitectureTest` now guards `backend/`, `lifecycle/`, and all
|
||||||
|
common pipeline stages. `ValidationOwnershipSpecTest` locks the title, matrix,
|
||||||
|
and PBS recut.
|
||||||
|
|
||||||
|
`PbsHostAdmissionValidator` remains under `p.studio.compiler.pbs`. No linking
|
||||||
|
or asset production code moved.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
Language-owned:
|
||||||
|
|
||||||
|
- parse errors;
|
||||||
|
- `[Init]` / `[Frame]` signature and colocation;
|
||||||
|
- barrel and import failures;
|
||||||
|
- `host call not allowed during init`.
|
||||||
|
|
||||||
|
Platform-owned and already implemented:
|
||||||
|
|
||||||
|
- invalid `IRLifecycleDeclaration`;
|
||||||
|
- assembled wrapper, boot guard, and synthetic origin preconditions;
|
||||||
|
- IRVM and marshal rejection families.
|
||||||
|
|
||||||
|
Classified as platform, not moved:
|
||||||
|
|
||||||
|
- canonical host-binding identity on `IRReservedMetadata`;
|
||||||
|
- `Addressable` / asset path.
|
||||||
|
|
||||||
|
Dual reporting:
|
||||||
|
|
||||||
|
- missing `[Frame]` in PBS source is `E_SEM_MISSING_PROJECT_FRAME`;
|
||||||
|
- an executable declaration without frame root is a common structural error.
|
||||||
|
|
||||||
|
## Pitfalls
|
||||||
|
|
||||||
|
- Do not treat “classified as platform” as “move the class now.” Host admission
|
||||||
|
still waits on the SDK source discussion.
|
||||||
|
- Do not merge language and platform failures into one hybrid code. Two
|
||||||
|
identities are cheaper than a lost message.
|
||||||
|
- Do not put PBS governance or PBS diagnostics in charge of compiler-general
|
||||||
|
safety gates.
|
||||||
|
- Do not scan PBS frontend sources with the platform architecture guard. The
|
||||||
|
guard is for common validators, not for the language package that must remain.
|
||||||
|
- Do not invent a validator-core because several common checks exist. They
|
||||||
|
already live on their stages.
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- Decision: `DEC-0047`
|
||||||
|
- Plan: `PLN-0126`
|
||||||
|
- Related lesson: `LSN-0062` - Common lifecycle assembly after frontend declaration
|
||||||
|
- Related lesson: `LSN-0059` - Common IRBackend handoff and backend guardrails
|
||||||
|
- `docs/specs/compiler/19. Verification and Safety Checks Specification.md`
|
||||||
|
- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md`
|
||||||
|
- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
|
||||||
|
- `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`
|
||||||
|
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/ValidationOwnershipSpecTest.java`
|
||||||
|
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/CommonBackendArchitectureTest.java`
|
||||||
+121
@@ -0,0 +1,121 @@
|
|||||||
|
---
|
||||||
|
id: LSN-0064
|
||||||
|
ticket: multi-frontend-sdk-canonical-definition
|
||||||
|
title: Runtime owns console ABI; PBS is delivery
|
||||||
|
created: 2026-09-19
|
||||||
|
tags: [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`
|
||||||
@@ -1,76 +0,0 @@
|
|||||||
---
|
|
||||||
id: AGD-0063
|
|
||||||
ticket: multi-frontend-validation-boundaries
|
|
||||||
title: Separar validacoes de linguagem e validacoes de plataforma
|
|
||||||
status: open
|
|
||||||
created: 2026-07-15
|
|
||||||
resolved:
|
|
||||||
decision:
|
|
||||||
tags: [compiler, compiler-general, compiler-pbs, backend, validation, multi-frontend]
|
|
||||||
---
|
|
||||||
|
|
||||||
# Agenda - Separar validacoes de linguagem e plataforma
|
|
||||||
|
|
||||||
## Objetivo
|
|
||||||
|
|
||||||
Domain owner: `compiler/general`, com impacto em `compiler/pbs`.
|
|
||||||
|
|
||||||
Definir onde cada validacao deve viver: PBS para sintaxe e semantica da linguagem; compiler core/backend para entrypoints, exports, hostcalls, capabilities, layouts, IR e bytecode.
|
|
||||||
|
|
||||||
## Contexto atual
|
|
||||||
|
|
||||||
O PBS concentra parsing, semantica, lowering e algumas validacoes que podem ser universais. O backend ja possui validadores para IRVM, bytecode e precondicoes de lowering.
|
|
||||||
|
|
||||||
## Escopo
|
|
||||||
|
|
||||||
- Mapear diagnostics e validacoes atuais.
|
|
||||||
- Classificar cada uma como linguagem ou plataforma.
|
|
||||||
- Definir regra: colocar a validacao no nivel mais baixo que a compreende sem conhecer a linguagem.
|
|
||||||
|
|
||||||
## Fora de escopo
|
|
||||||
|
|
||||||
- Reescrever todas as mensagens diagnosticas.
|
|
||||||
- Mudar codigos de erro sem necessidade.
|
|
||||||
- Transferir validacoes antes de existir contrato comum suficiente.
|
|
||||||
|
|
||||||
## Arquivos e componentes a inspecionar
|
|
||||||
|
|
||||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/...`
|
|
||||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/...`
|
|
||||||
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/...`
|
|
||||||
- `docs/specs/compiler/19. Verification and Safety Checks Specification.md`
|
|
||||||
- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md`
|
|
||||||
|
|
||||||
## Alteracoes propostas
|
|
||||||
|
|
||||||
Opcao A: criar matriz de ownership de validacoes antes de mover codigo.
|
|
||||||
|
|
||||||
Opcao B: mover validacoes junto com lifecycle/IR quando cada fronteira for tocada.
|
|
||||||
|
|
||||||
Recomendacao inicial: matriz primeiro; migracao so quando uma decisao posterior fechar lifecycle e IR.
|
|
||||||
|
|
||||||
## Estrategia de implementacao
|
|
||||||
|
|
||||||
Auditar testes de erro existentes, agrupar por origem, decidir ownership e adicionar testes de regressao para impedir que o backend importe PBS.
|
|
||||||
|
|
||||||
## Testes necessarios
|
|
||||||
|
|
||||||
- Testes PBS para erros de sintaxe/semantica continuam no frontend.
|
|
||||||
- Testes comuns para IR malformada, hostcall inexistente, export duplicado e lifecycle invalido.
|
|
||||||
- Teste arquitetural de ausencia de imports PBS em validadores comuns.
|
|
||||||
|
|
||||||
## Criterios de aceitacao
|
|
||||||
|
|
||||||
- Validacoes da plataforma sao expressas sem conceitos PBS.
|
|
||||||
- Validacoes PBS continuam preservadas e especificas.
|
|
||||||
|
|
||||||
## Riscos
|
|
||||||
|
|
||||||
- Perder qualidade de diagnostico ao mover validacao para camada comum.
|
|
||||||
- Duplicar validacoes em vez de estabelecer ownership.
|
|
||||||
|
|
||||||
## Decisoes que devem ser registradas
|
|
||||||
|
|
||||||
- Matriz de validacoes e ownership.
|
|
||||||
- Politica de diagnosticos quando o erro comum ainda precisa de source span de frontend.
|
|
||||||
|
|
||||||
@@ -1,78 +0,0 @@
|
|||||||
---
|
|
||||||
id: AGD-0064
|
|
||||||
ticket: multi-frontend-sdk-canonical-definition
|
|
||||||
title: Auditoria e centralizacao gradual da definicao canonica do SDK
|
|
||||||
status: open
|
|
||||||
created: 2026-07-15
|
|
||||||
resolved:
|
|
||||||
decision:
|
|
||||||
tags: [compiler, compiler-general, sdk, stdlib, hostcalls, intrinsics, multi-frontend]
|
|
||||||
---
|
|
||||||
|
|
||||||
# Agenda - Centralizar a definicao do SDK
|
|
||||||
|
|
||||||
## Objetivo
|
|
||||||
|
|
||||||
Domain owner: `compiler/general`, com referencias a `compiler/pbs` e `vm-arch`.
|
|
||||||
|
|
||||||
Auditar onde hostcalls, intrinsics, tipos fundamentais e APIs do console sao definidos hoje antes de propor uma fonte canonica do SDK.
|
|
||||||
|
|
||||||
## Contexto atual
|
|
||||||
|
|
||||||
Existem specs em `docs/vm-arch/INTRINSICS.csv`, docs de stdlib em `docs/specs/compiler/18. Standard Library Surface Specification.md`, specs PBS de stdlib e host ABI, alem de possiveis registries em codigo e fixtures.
|
|
||||||
|
|
||||||
## Escopo
|
|
||||||
|
|
||||||
- Mapear fontes atuais da verdade.
|
|
||||||
- Identificar definicoes geradas, duplicadas e manuais.
|
|
||||||
- Propor caminho gradual para um schema canonico.
|
|
||||||
|
|
||||||
## Fora de escopo
|
|
||||||
|
|
||||||
- Migracao grande do SDK.
|
|
||||||
- Gerar bindings para C#, Kotlin, TypeScript ou outras linguagens.
|
|
||||||
- Escolher formato definitivo antes da auditoria.
|
|
||||||
|
|
||||||
## Arquivos e componentes a inspecionar
|
|
||||||
|
|
||||||
- `docs/vm-arch/INTRINSICS.csv`
|
|
||||||
- `docs/specs/compiler/18. Standard Library Surface Specification.md`
|
|
||||||
- `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
|
||||||
- `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
|
|
||||||
- `prometeu-compiler/...` registries de hostcalls/intrinsics/stdlib
|
|
||||||
- runtime/PVM quando presente no workspace ou submodulos relacionados
|
|
||||||
|
|
||||||
## Alteracoes propostas
|
|
||||||
|
|
||||||
Opcao A: agenda de auditoria pura, produzindo mapa de fontes e duplicacoes.
|
|
||||||
|
|
||||||
Opcao B: criar schema canonico minimo depois da auditoria, sem migrar todos os consumidores.
|
|
||||||
|
|
||||||
Recomendacao inicial: primeiro fechar auditoria; so uma decision posterior deve escolher formato e migracao.
|
|
||||||
|
|
||||||
## Estrategia de implementacao
|
|
||||||
|
|
||||||
Listar cada hostcall/intrinsic/tipo fundamental em suas fontes atuais, comparar assinatura, capability, versao e docs, e classificar divergencias.
|
|
||||||
|
|
||||||
## Testes necessarios
|
|
||||||
|
|
||||||
- Testes de paridade entre registry runtime/backend e specs existentes, se ja houver fonte estruturada.
|
|
||||||
- Testes de nao divergencia para IDs e assinaturas apos qualquer centralizacao.
|
|
||||||
|
|
||||||
## Criterios de aceitacao
|
|
||||||
|
|
||||||
- Existe mapa claro de fonte real da verdade.
|
|
||||||
- Duplicacoes e divergencias ficam registradas.
|
|
||||||
- Nenhuma migracao ampla e iniciada sem nova decisao.
|
|
||||||
|
|
||||||
## Riscos
|
|
||||||
|
|
||||||
- Tratar docs como fonte real quando o codigo ja diverge.
|
|
||||||
- Iniciar geracao antes de saber quem consome cada definicao.
|
|
||||||
|
|
||||||
## Decisoes que devem ser registradas
|
|
||||||
|
|
||||||
- Fonte canonica proposta.
|
|
||||||
- Campos obrigatorios do SDK.
|
|
||||||
- Sequencia de migracao segura.
|
|
||||||
|
|
||||||
@@ -82,7 +82,8 @@ The following inputs are already fixed elsewhere and must not be contradicted he
|
|||||||
- Stable source span metadata is required at the token level and must remain useful to later diagnostics.
|
- Stable source span metadata is required at the token level and must remain useful to later diagnostics.
|
||||||
- Traps are fatal runtime outcomes rather than a recoverable userland diagnostic flow.
|
- Traps are fatal runtime outcomes rather than a recoverable userland diagnostic flow.
|
||||||
- Qualitative cost facts such as retention-bearing operations and host-boundary crossings are normative, but quantitative performance metrics are not.
|
- Qualitative cost facts such as retention-bearing operations and host-boundary crossings are normative, but quantitative performance metrics are not.
|
||||||
- Topic `19` requires deterministic diagnostics for globals, lifecycle markers, init admission, and published-wrapper structural failures.
|
- PBS requires deterministic diagnostics for source-form globals, lifecycle markers, and init admission.
|
||||||
|
- Published-wrapper, boot-guard, synthetic-origin, and invalid-lifecycle-declaration failures are compiler-general. See `docs/specs/compiler/19. Verification and Safety Checks Specification.md` section 11 and `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
|
||||||
|
|
||||||
## 6. Required Diagnostic Phases
|
## 6. Required Diagnostic Phases
|
||||||
|
|
||||||
@@ -97,6 +98,8 @@ PBS-facing tooling must distinguish at least the following external diagnostic p
|
|||||||
|
|
||||||
`linking` is a first-class phase in the external diagnostics contract and must not be collapsed away into a generic resolution bucket.
|
`linking` is a first-class phase in the external diagnostics contract and must not be collapsed away into a generic resolution bucket.
|
||||||
|
|
||||||
|
The `host-binding/capability admission` phase covers the source shape of `[Host]` and `[Capability]`. Canonical host-binding identity and capability consistency over `IRReservedMetadata` are platform-owned and are not moved by this specification.
|
||||||
|
|
||||||
This document does not require one finer-grained public phase split for verifier internals, artifact offsets, or transport-specific backend stages beyond what is stated here.
|
This document does not require one finer-grained public phase split for verifier internals, artifact offsets, or transport-specific backend stages beyond what is stated here.
|
||||||
|
|
||||||
## 7. Required Diagnostic Identity, Payload, and Attribution
|
## 7. Required Diagnostic Identity, Payload, and Attribution
|
||||||
@@ -180,7 +183,7 @@ At minimum, the PBS diagnostics baseline must cover:
|
|||||||
5. malformed, unauthorized, or capability-rejected host usage required by `6.2. Host ABI Binding and Loader Resolution Specification.md` and `7. Cartridge Manifest and Runtime Capabilities Specification.md`,
|
5. malformed, unauthorized, or capability-rejected host usage required by `6.2. Host ABI Binding and Loader Resolution Specification.md` and `7. Cartridge Manifest and Runtime Capabilities Specification.md`,
|
||||||
6. source-attributable backend-originated failures that remain user-actionable under normative lowering or load-facing rules.
|
6. source-attributable backend-originated failures that remain user-actionable under normative lowering or load-facing rules.
|
||||||
7. dependency-scoped fail-fast admission at frontend boundary: when one module is rejected, modules that import it (directly or transitively) must not be emitted, while diagnostics collection for independent modules must continue.
|
7. dependency-scoped fail-fast admission at frontend boundary: when one module is rejected, modules that import it (directly or transitively) must not be emitted, while diagnostics collection for independent modules must continue.
|
||||||
8. lifecycle and globals diagnostics required by topic `19`, including:
|
8. lifecycle-marker and source-form global diagnostics, including:
|
||||||
- `global initializer uses unsupported form`,
|
- `global initializer uses unsupported form`,
|
||||||
- `global dependency cycle detected`,
|
- `global dependency cycle detected`,
|
||||||
- `global import must resolve through a global barrel entry`,
|
- `global import must resolve through a global barrel entry`,
|
||||||
@@ -195,14 +198,7 @@ At minimum, the PBS diagnostics baseline must cover:
|
|||||||
- `Init attribute target invalid`,
|
- `Init attribute target invalid`,
|
||||||
- `InitAllowed is valid only on SDK host methods`,
|
- `InitAllowed is valid only on SDK host methods`,
|
||||||
- `host call not allowed during init`.
|
- `host call not allowed during init`.
|
||||||
9. common lifecycle structural diagnostics owned by lifecycle assembly and backend preconditions, including:
|
9. compiler-general lifecycle-assembly and IRVM-precondition failures, which this PBS catalog MUST NOT claim as PBS required coverage; see `docs/specs/compiler/19. Verification and Safety Checks Specification.md` section 11 and `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
|
||||||
- invalid or unresolved lifecycle declaration ids and roles,
|
|
||||||
- missing frame root on an executable declaration,
|
|
||||||
- frontend-preassembled derived lifecycle artifacts,
|
|
||||||
- `synthetic wrapper entrypoint missing`,
|
|
||||||
- `published entrypoint is not function index 0`,
|
|
||||||
- `hidden boot guard is missing`,
|
|
||||||
- `synthetic callable origin missing`.
|
|
||||||
10. symbolic asset-reference diagnostics required by backend-owned `Addressable` resolution, including:
|
10. symbolic asset-reference diagnostics required by backend-owned `Addressable` resolution, including:
|
||||||
- unresolved terminal asset reference,
|
- unresolved terminal asset reference,
|
||||||
- namespace-versus-terminal asset misuse,
|
- namespace-versus-terminal asset misuse,
|
||||||
|
|||||||
+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:
|
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.
|
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.
|
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.
|
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:
|
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.
|
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:
|
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:
|
as compile-time surface only, and treats:
|
||||||
|
|
||||||
- `("gfx", "draw_pixel", 1)`
|
- `("gfx2d", "clear", 1)`
|
||||||
|
|
||||||
as the normative runtime-facing identity.
|
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`.
|
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.
|
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.
|
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>`.
|
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.
|
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:
|
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.
|
- `name` is the canonical host operation name within that module.
|
||||||
- `version` is the canonical ABI version of that host operation.
|
- `version` is the canonical ABI version of that host operation.
|
||||||
- This identity is stable across source languages and SDK naming styles.
|
- This identity is stable across source languages and SDK naming styles.
|
||||||
@@ -310,7 +318,10 @@ Rules:
|
|||||||
- the loader resolves only against this canonical registry,
|
- the loader resolves only against this canonical registry,
|
||||||
- unknown identities are load errors,
|
- unknown identities are load errors,
|
||||||
- successful resolution yields numeric syscall identifiers and associated metadata,
|
- 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:
|
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:
|
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
|
## 2. Scope
|
||||||
|
|
||||||
@@ -53,52 +57,66 @@ The recommended Studio layout is:
|
|||||||
```text
|
```text
|
||||||
prometeu-compiler/frontends/prometeu-frontend-pbs/
|
prometeu-compiler/frontends/prometeu-frontend-pbs/
|
||||||
src/main/resources/
|
src/main/resources/
|
||||||
stdlib/
|
<target>/
|
||||||
1/
|
stdlib/
|
||||||
sdk/
|
1/
|
||||||
composer/
|
core/
|
||||||
main.pbs
|
color/
|
||||||
mod.barrel
|
main.pbs
|
||||||
gfx/
|
mod.barrel
|
||||||
main.pbs
|
sdk/
|
||||||
mod.barrel
|
asset/
|
||||||
asset/
|
main.pbs
|
||||||
main.pbs
|
mod.barrel
|
||||||
mod.barrel
|
composer/
|
||||||
audio/
|
main.pbs
|
||||||
main.pbs
|
mod.barrel
|
||||||
mod.barrel
|
gfx/
|
||||||
core/
|
main.pbs
|
||||||
math/
|
mod.barrel
|
||||||
main.pbs
|
input/
|
||||||
mod.barrel
|
main.pbs
|
||||||
|
mod.barrel
|
||||||
|
log/
|
||||||
|
main.pbs
|
||||||
|
mod.barrel
|
||||||
```
|
```
|
||||||
|
|
||||||
Interpretation:
|
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,
|
- `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.
|
- `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
|
## 5. Logical Mapping
|
||||||
|
|
||||||
The compiler must treat the physical layout as a logical stdlib environment.
|
The compiler must treat the physical layout as a logical stdlib environment.
|
||||||
|
|
||||||
Required mapping:
|
Required mapping:
|
||||||
|
|
||||||
- `stdlib/<N>/sdk/gfx` -> `@sdk:gfx`
|
- `<target>/stdlib/<N>/<space>/<module>` -> `@<space>:<module>`
|
||||||
- `stdlib/<N>/sdk/composer` -> `@sdk:composer`
|
|
||||||
- `stdlib/<N>/sdk/asset` -> `@sdk:asset`
|
Current line `1` (`game`) mapping:
|
||||||
- `stdlib/<N>/sdk/audio` -> `@sdk:audio`
|
|
||||||
- `stdlib/<N>/core/math` -> `@core:math`
|
- `game/stdlib/1/core/color` -> `@core:color`
|
||||||
- `stdlib/<N>/core/math/vector` -> `@core:math/vector`
|
- `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:
|
Rules:
|
||||||
|
|
||||||
- physical storage is an implementation detail,
|
- physical storage is an implementation detail,
|
||||||
- logical module identity is authoritative,
|
- 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
|
## 6. Module File Convention
|
||||||
|
|
||||||
@@ -150,7 +168,8 @@ Minimum operations:
|
|||||||
|
|
||||||
- `resolve(@sdk:gfx)`
|
- `resolve(@sdk:gfx)`
|
||||||
- `resolve(@sdk:composer)`
|
- `resolve(@sdk:composer)`
|
||||||
- `resolve(@core:math/vector)`
|
- `resolve(@sdk:input)`
|
||||||
|
- `resolve(@core:color)`
|
||||||
|
|
||||||
### 7.3 `StdlibModuleSource`
|
### 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 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
|
## 2. Scope
|
||||||
|
|
||||||
This document is intended to define:
|
This document is intended to define:
|
||||||
@@ -28,15 +31,22 @@ This document does not define:
|
|||||||
|
|
||||||
Normative precedence:
|
Normative precedence:
|
||||||
|
|
||||||
1. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
1. Runtime intrinsic catalog (`../runtime/docs/vm-arch/INTRINSICS.csv`; Studio mirror `docs/vm-arch/INTRINSICS.csv`)
|
||||||
2. `8. Stdlib Environment Packaging and Loading Specification.md`
|
2. Runtime host ABI (`../runtime/docs/specs/runtime/16-host-abi-and-syscalls.md` and `SyscallMeta`)
|
||||||
3. `6. VM-owned vs Host-backed.md`
|
3. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||||
4. `6.1. Intrinsics and Builtin Types Specification.md`
|
4. `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||||
5. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
5. `6. VM-owned vs Host-backed.md`
|
||||||
6. This document
|
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.
|
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
|
## 4. Normative Inputs
|
||||||
|
|
||||||
This document depends on, at minimum:
|
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.
|
- User code must import stdlib modules explicitly.
|
||||||
- Canonical host identity comes from reserved host-binding metadata, not from source owner spelling.
|
- 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.
|
- 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
|
## 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.
|
- Whether `@core:*` is specified as language-adjacent utility surface or as ordinary stdlib contract.
|
||||||
- How stdlib API evolution is documented and conformance-tested.
|
- How stdlib API evolution is documented and conformance-tested.
|
||||||
- Whether some interface modules remain toolchain-private and outside user-facing stdlib surface.
|
- 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
|
## 8. Non-Goals
|
||||||
|
|
||||||
@@ -127,6 +143,12 @@ Rules:
|
|||||||
- but ownership remains governed by the VM-owned vs host-backed classification,
|
- 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.
|
- 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
|
## 11. Builtin Shell Surfaces
|
||||||
|
|
||||||
Reserved stdlib modules may expose builtin declarations as compile-time-only
|
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
|
as `BuiltinType(name="vec2", version=1)` and
|
||||||
`BuiltinConst(target="vec2", name="zero", version=1)`.
|
`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
|
## 14. Deterministic Stdlib Surface Failures
|
||||||
|
|
||||||
At minimum, a conforming implementation must reject:
|
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,
|
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,
|
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.
|
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.
|
||||||
|
|||||||
@@ -1,18 +1,21 @@
|
|||||||
# PBS Verification and Safety Checks Specification
|
# Compiler Verification and Safety Checks Specification
|
||||||
|
|
||||||
Status: Draft v1 (Quality-Gate Baseline)
|
Status: Draft v1 (Quality-Gate Baseline)
|
||||||
Applies to: test-backed safety gates for backend compiler stages and integration regression safety checks against runtime
|
Applies to: test-backed safety gates for common compiler stages, validation ownership across executable frontends, and integration regression safety checks against runtime
|
||||||
|
|
||||||
## 1. Purpose
|
## 1. Purpose
|
||||||
|
|
||||||
This document defines the minimum safety/verification quality gates that must be enforced for executable backend pipelines.
|
This document defines the minimum safety/verification quality gates that must be enforced for executable compiler pipelines, and the ownership rule that separates language validation from platform validation.
|
||||||
|
|
||||||
Its purpose is to keep safety measurable and deterministic across:
|
Its purpose is to keep safety measurable and deterministic across:
|
||||||
|
|
||||||
- lowering,
|
- lowering,
|
||||||
- optimization,
|
- optimization,
|
||||||
- emission,
|
- emission,
|
||||||
- and runtime integration boundaries.
|
- runtime integration boundaries,
|
||||||
|
- and the classification of diagnostics that every executable frontend must obey.
|
||||||
|
|
||||||
|
PBS is the current executable frontend. It is an example, not the owner of this specification.
|
||||||
|
|
||||||
## 2. Scope
|
## 2. Scope
|
||||||
|
|
||||||
@@ -20,37 +23,41 @@ This document defines:
|
|||||||
|
|
||||||
- mandatory compiler-stage safety checks for executable pipeline stages,
|
- mandatory compiler-stage safety checks for executable pipeline stages,
|
||||||
- conditional integration safety regression checks against runtime line,
|
- conditional integration safety regression checks against runtime line,
|
||||||
- and evidence requirements for safety-related support claims.
|
- evidence requirements for safety-related support claims,
|
||||||
|
- and validation-ownership rules that apply to all executable frontends.
|
||||||
|
|
||||||
This document does not define:
|
This document does not define:
|
||||||
|
|
||||||
- full runtime verifier algorithm internals,
|
- full runtime verifier algorithm internals,
|
||||||
- formal proof of all runtime safety properties,
|
- formal proof of all runtime safety properties,
|
||||||
- or one mandatory verifier/optimizer architecture.
|
- one mandatory verifier/optimizer architecture,
|
||||||
|
- PBS syntax or static-semantics catalogs,
|
||||||
|
- or a generic validator-core package.
|
||||||
|
|
||||||
## 3. Authority and Precedence
|
## 3. Authority and Precedence
|
||||||
|
|
||||||
Normative precedence:
|
Normative precedence:
|
||||||
|
|
||||||
1. `docs/pbs/specs/2. Governance and Versioning.md`
|
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||||
2. `docs/pbs/specs/12. Diagnostics Specification.md`
|
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||||
3. `20. IRBackend to IRVM Lowering Specification.md`
|
3. `20. IRBackend to IRVM Lowering Specification.md`
|
||||||
4. `21. IRVM Optimization Pipeline Specification.md`
|
4. `21. IRVM Optimization Pipeline Specification.md`
|
||||||
5. `15. Bytecode and PBX Mapping Specification.md`
|
5. `15. Bytecode and PBX Mapping Specification.md`
|
||||||
6. `13. Conformance Test Specification.md`
|
6. `13. Conformance Test Specification.md`
|
||||||
7. This document
|
7. This document
|
||||||
|
8. Frontend diagnostics specifications, including `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md`, for language-owned coverage only
|
||||||
|
|
||||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
If a rule here conflicts with a higher-precedence authority, it is invalid. Frontend diagnostics documents MUST NOT redefine compiler-general safety gates or platform validation ownership.
|
||||||
|
|
||||||
## 4. Normative Inputs
|
## 4. Normative Inputs
|
||||||
|
|
||||||
This document depends on:
|
This document depends on:
|
||||||
|
|
||||||
- `docs/pbs/specs/12. Diagnostics Specification.md`
|
|
||||||
- `13. Conformance Test Specification.md`
|
- `13. Conformance Test Specification.md`
|
||||||
- `15. Bytecode and PBX Mapping Specification.md`
|
- `15. Bytecode and PBX Mapping Specification.md`
|
||||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||||
- `21. IRVM Optimization Pipeline Specification.md`
|
- `21. IRVM Optimization Pipeline Specification.md`
|
||||||
|
- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md` as the current frontend diagnostics catalog, not as the owner of this specification
|
||||||
|
|
||||||
## 5. Safety Gate Model
|
## 5. Safety Gate Model
|
||||||
|
|
||||||
@@ -133,3 +140,74 @@ This document is healthy when:
|
|||||||
2. executable backends have explicit S-I status (`pass`/`fail`/`deferred`),
|
2. executable backends have explicit S-I status (`pass`/`fail`/`deferred`),
|
||||||
3. integration safety regressions are preserved in tests,
|
3. integration safety regressions are preserved in tests,
|
||||||
4. and safety-related support claims remain evidence-backed.
|
4. and safety-related support claims remain evidence-backed.
|
||||||
|
|
||||||
|
## 11. Validation Ownership
|
||||||
|
|
||||||
|
A validation MUST live at the lowest layer that understands the failure without knowing the source language.
|
||||||
|
|
||||||
|
- A check is language-owned if it needs AST, tokens, a language marker, a barrel, or another source-language rule.
|
||||||
|
- A check is platform-owned if it can be performed on `IRBackend`, `IRLifecycleDeclaration`, IRVM, PBX, host/capability tables, or ids.
|
||||||
|
|
||||||
|
Adding a validation MUST record:
|
||||||
|
|
||||||
|
1. the input artifact the check reads;
|
||||||
|
2. whether that artifact is language source/AST/marker or a common contract;
|
||||||
|
3. the matrix owner;
|
||||||
|
4. the code family (`E_PARSE_*` / `E_SEM_*` / `E_LINK_*` / `E_HOST_*` versus `COMMON_*` / `LOWER_IRVM_*` / `MARSHAL_*`);
|
||||||
|
5. whether the span comes from a common-contract origin or from language tokens/AST.
|
||||||
|
|
||||||
|
If item 2 is both, the implementation MUST emit two diagnostics with distinct identities, not one hybrid.
|
||||||
|
|
||||||
|
### 11.1 Diagnostic identity and span
|
||||||
|
|
||||||
|
Platform diagnostics MUST use `COMMON_*`, `LOWER_IRVM_*`, or `MARSHAL_*` codes and the phase of the pipeline stage that reports them.
|
||||||
|
|
||||||
|
PBS MUST keep its current `E_PARSE_*`, `E_SEM_*`, `E_LINK_*`, and `E_HOST_*` codes.
|
||||||
|
|
||||||
|
This specification MUST NOT rewrite diagnostic messages or renumber existing codes.
|
||||||
|
|
||||||
|
Common code MUST copy origin/span when the declaration, instruction, or metadata carries one. A missing origin MUST be a structural error. Implementations MUST NOT invent a span.
|
||||||
|
|
||||||
|
The same fact MAY exist on both sides. PBS explains the language rule; the common layer rejects an invalid handoff even when the frontend has no PBS markers. The two errors MUST keep distinct identities. Example: `E_SEM_MISSING_PROJECT_FRAME` and a missing frame root on an executable `IRLifecycleDeclaration`.
|
||||||
|
|
||||||
|
### 11.2 Initial ownership matrix
|
||||||
|
|
||||||
|
| Family | Owner | Status | Notes |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| Parse / syntax (`ParseErrors`) | `compiler/pbs` | language | remains |
|
||||||
|
| Type, flow, declaration, const, and source-form global semantics | `compiler/pbs` | language | remains |
|
||||||
|
| Markers `[Init]`, `[Frame]`, `InitAllowed`, signature, colocation | `compiler/pbs` | language | already split by lifecycle assembly |
|
||||||
|
| `host call not allowed during init` | `compiler/pbs` | language | marker/source rule |
|
||||||
|
| PBS linking (`PbsLinkErrors`, barrel, import, visibility) | `compiler/pbs` | language | do not extract |
|
||||||
|
| Source shape of `[Host]` / `[Capability]` | `compiler/pbs` | language | host-admission split |
|
||||||
|
| Canonical host-binding identity and capability over `IRReservedMetadata` | `compiler/general` | platform | classified; validator remains in the PBS package until a later plan |
|
||||||
|
| Lifecycle assembler | `compiler/general` | platform | already implemented |
|
||||||
|
| IRVM preconditions for wrapper, boot guard, origin | `compiler/general` | platform | already implemented |
|
||||||
|
| `IRVMValidator`, lowering, marshal/bytecode | `compiler/general` | platform | already implemented |
|
||||||
|
| `Addressable` / asset path | `compiler/general` | platform | classified; no extra migration in this specification |
|
||||||
|
| Gates S-U/S-I | `compiler/general` | platform | this document |
|
||||||
|
|
||||||
|
### 11.3 Host admission, assets, and linking
|
||||||
|
|
||||||
|
Host admission is split:
|
||||||
|
|
||||||
|
- language owns the source shape of `[Host]` and `[Capability]`;
|
||||||
|
- platform owns canonical binding identity `(module, name, version)`, unknown capability, undeclared capability, and inconsistent binding once those facts exist on `IRReservedMetadata`.
|
||||||
|
|
||||||
|
`PbsHostAdmissionValidator` MAY remain in the PBS package until a later plan. `E_HOST_*` MUST NOT be treated as eternal PBS semantics.
|
||||||
|
|
||||||
|
`Addressable` / asset-path resolution is platform-owned. This specification classifies it and MUST NOT move additional asset code.
|
||||||
|
|
||||||
|
PBS linking, barrel files, and `PbsLinkErrors` remain language-owned. `ResolveDeps` does not authorize extracting them.
|
||||||
|
|
||||||
|
### 11.4 What this section does not authorize
|
||||||
|
|
||||||
|
This specification MUST NOT be read as authorizing:
|
||||||
|
|
||||||
|
- a generic validator-core package;
|
||||||
|
- moving `PbsHostAdmissionValidator` into a common package;
|
||||||
|
- moving asset-resolution production code;
|
||||||
|
- extracting PBS linking;
|
||||||
|
- or reopening lifecycle-assembly ownership.
|
||||||
|
|
||||||
|
Platform validators MUST NOT import `p.studio.compiler.pbs` and MUST NOT discover roles from `__pbs.` prefixes.
|
||||||
|
|||||||
@@ -151,6 +151,8 @@ Lowering from `IRBackend` to `IRVM` may start only when:
|
|||||||
|
|
||||||
Declaration validation, role uniqueness, explicit order, and rejection of frontend-preassembled derived artifacts belong to `LifecycleAssemblerService`. `IRBackend -> IRVM` MUST keep only backend preconditions on the assembled graph, such as published-wrapper identity, synthetic origin presence, and hidden boot-guard presence. It MUST NOT reconstruct lifecycle order from callable names.
|
Declaration validation, role uniqueness, explicit order, and rejection of frontend-preassembled derived artifacts belong to `LifecycleAssemblerService`. `IRBackend -> IRVM` MUST keep only backend preconditions on the assembled graph, such as published-wrapper identity, synthetic origin presence, and hidden boot-guard presence. It MUST NOT reconstruct lifecycle order from callable names.
|
||||||
|
|
||||||
|
Those common structural diagnostics are compiler-general. Classification, code families, and dual language/platform reporting are owned by `docs/specs/compiler/19. Verification and Safety Checks Specification.md` section 11. They MUST NOT be catalogued as PBS-facing required coverage.
|
||||||
|
|
||||||
## 6. IRVM Model Obligations
|
## 6. IRVM Model Obligations
|
||||||
|
|
||||||
`IRVM` v1 is a quasi-ISA backend form:
|
`IRVM` v1 is a quasi-ISA backend form:
|
||||||
|
|||||||
@@ -3,7 +3,7 @@
|
|||||||
Status: Draft v1 (Traceability Baseline)
|
Status: Draft v1 (Traceability Baseline)
|
||||||
Applies to: compiler/backend conformance traceability for canonical stage order and entrypoint-specific contracts
|
Applies to: compiler/backend conformance traceability for canonical stage order and entrypoint-specific contracts
|
||||||
|
|
||||||
Last Updated: 2026-09-18
|
Last Updated: 2026-09-19
|
||||||
|
|
||||||
## 1. Purpose
|
## 1. Purpose
|
||||||
|
|
||||||
@@ -40,6 +40,13 @@ to concrete positive/negative test evidence and current status.
|
|||||||
| G19-5.2.6 | Gate S-I MUST reject missing capability at load-time. | N/A | `BackendGateIIntegrationTest#gateI_rejectMissingCapability` | pass | |
|
| G19-5.2.6 | Gate S-I MUST reject missing capability at load-time. | N/A | `BackendGateIIntegrationTest#gateI_rejectMissingCapability` | pass | |
|
||||||
| G19-5.2.7 | Gate S-I MUST cover valid VM-owned intrinsic path. | `BackendGateIIntegrationTest#gateI_validIntrinsicPath` | N/A | pass | |
|
| G19-5.2.7 | Gate S-I MUST cover valid VM-owned intrinsic path. | `BackendGateIIntegrationTest#gateI_validIntrinsicPath` | N/A | pass | |
|
||||||
| G19-5.2.8 | Gate S-I MUST cover repeatability across runtime line. | `RuntimeBackedCompatibilityAdapterTest#checkMustPassInStrictModeWhenRuntimeCommandIsValid`; `RuntimeBackedCompatibilityAdapterTest#checkMustBeRepeatableAcrossDeclaredRuntimeLinesInStrictMode` | `RuntimeBackedCompatibilityAdapterTest#checkMustFailInStrictModeWhenRuntimeCommandIsUnavailable` | pass | Multi-line repeatability is asserted with strict runtime-backed checks over distinct declared runtime lines. |
|
| G19-5.2.8 | Gate S-I MUST cover repeatability across runtime line. | `RuntimeBackedCompatibilityAdapterTest#checkMustPassInStrictModeWhenRuntimeCommandIsValid`; `RuntimeBackedCompatibilityAdapterTest#checkMustBeRepeatableAcrossDeclaredRuntimeLinesInStrictMode` | `RuntimeBackedCompatibilityAdapterTest#checkMustFailInStrictModeWhenRuntimeCommandIsUnavailable` | pass | Multi-line repeatability is asserted with strict runtime-backed checks over distinct declared runtime lines. |
|
||||||
|
| G19-11.1 | A validation MUST live at the lowest layer that understands the failure without knowing the source language. | `ValidationOwnershipSpecTest#spec19MustBeCompilerGeneralAndPublishValidationOwnership` | N/A | pass | Spec 19 section 11 states the classification rule. |
|
||||||
|
| G19-11.2 | Spec 19 MUST publish the validation ownership matrix. | `ValidationOwnershipSpecTest#spec19MustBeCompilerGeneralAndPublishValidationOwnership` | N/A | pass | Matrix families include parse/syntax, PBS linking, and lifecycle assembler. |
|
||||||
|
| G19-11.3 | Platform diagnostics MUST use `COMMON_*` / `LOWER_IRVM_*` / `MARSHAL_*` and MUST copy origin/span when present. | `ValidationOwnershipSpecTest#spec19MustBeCompilerGeneralAndPublishValidationOwnership`; `LifecycleAssemblerServiceTest#assembleMustRejectMissingFrameRootWithoutRepair` | N/A | pass | Code families and span policy are normative in spec 19 section 11.1. |
|
||||||
|
| G19-11.4 | The same fact MAY exist as a language diagnostic and a platform diagnostic with distinct identities. | `ValidationOwnershipSpecTest#spec19MustBeCompilerGeneralAndPublishValidationOwnership` | N/A | pass | Dual reporting is required when a check reads both source and common contract. |
|
||||||
|
| G19-11.5 | Host admission MUST split source attribute shape from canonical `IRReservedMetadata` identity without moving the PBS validator in this plan. | `ValidationOwnershipSpecTest#spec19MustBeCompilerGeneralAndPublishValidationOwnership` | N/A | pass | Classified as platform; validator remains in the PBS package. |
|
||||||
|
| G19-11.6 | Platform validators MUST NOT import PBS packages or match `__pbs.` prefixes. | `CommonBackendArchitectureTest#commonBackendMustNotImportPbsFrontendPackages`; `CommonBackendArchitectureTest#commonLifecycleAndBackendMustNotDiscoverRolesFromPbsNamePrefixes` | N/A | pass | Guard covers backend, lifecycle, and all common pipeline stages. |
|
||||||
|
| PBS12-11 | PBS diagnostics MUST NOT claim common structural lifecycle/IRVM failures as PBS required coverage. | `ValidationOwnershipSpecTest#pbsDiagnosticsMustNotClaimCommonStructuralFailures` | N/A | pass | PBS spec 12 points those failures at spec 19 section 11 and spec 20. |
|
||||||
| G20-4.1.1 | `IRBackend` MUST be the common frontend-to-backend executable handoff. | `LowerToIRVMServiceTest#lowerMustAcceptManuallyConstructedCommonIRBackend` | N/A | pass | Direct backend lowering from manually constructed common IRBackend proves PBS parser/frontend services are not required. |
|
| G20-4.1.1 | `IRBackend` MUST be the common frontend-to-backend executable handoff. | `LowerToIRVMServiceTest#lowerMustAcceptManuallyConstructedCommonIRBackend` | N/A | pass | Direct backend lowering from manually constructed common IRBackend proves PBS parser/frontend services are not required. |
|
||||||
| G20-4.1.2 | Common backend code MUST NOT depend on `p.studio.compiler.pbs`. | `CommonBackendArchitectureTest#commonBackendMustNotImportPbsFrontendPackages` | N/A | pass | Source-level architectural guard rejects PBS frontend imports in common backend packages. |
|
| G20-4.1.2 | Common backend code MUST NOT depend on `p.studio.compiler.pbs`. | `CommonBackendArchitectureTest#commonBackendMustNotImportPbsFrontendPackages` | N/A | pass | Source-level architectural guard rejects PBS frontend imports in common backend packages. |
|
||||||
| G20-4.1.3 | Public `IRBackend` contract MUST NOT expose PBS AST, token, parser, semantic, or editorial types. | `IRBackendExecutableContractTest#publicIRBackendContractMustNotExposePbsTypes` | N/A | pass | Reflection guard covers public contract fields, constructors, methods, and record components. |
|
| G20-4.1.3 | Public `IRBackend` contract MUST NOT expose PBS AST, token, parser, semantic, or editorial types. | `IRBackendExecutableContractTest#publicIRBackendContractMustNotExposePbsTypes` | N/A | pass | Reflection guard covers public contract fields, constructors, methods, and record components. |
|
||||||
|
|||||||
+7
@@ -36,6 +36,13 @@ class BackendConformanceMatrixSpecTest {
|
|||||||
"G19-5.2.6",
|
"G19-5.2.6",
|
||||||
"G19-5.2.7",
|
"G19-5.2.7",
|
||||||
"G19-5.2.8",
|
"G19-5.2.8",
|
||||||
|
"G19-11.1",
|
||||||
|
"G19-11.2",
|
||||||
|
"G19-11.3",
|
||||||
|
"G19-11.4",
|
||||||
|
"G19-11.5",
|
||||||
|
"G19-11.6",
|
||||||
|
"PBS12-11",
|
||||||
"G20-4.1.1",
|
"G20-4.1.1",
|
||||||
"G20-4.1.2",
|
"G20-4.1.2",
|
||||||
"G20-4.1.3",
|
"G20-4.1.3",
|
||||||
|
|||||||
+1
-1
@@ -17,7 +17,7 @@ class CommonBackendArchitectureTest {
|
|||||||
private static final List<String> GUARDED_RELATIVE_ROOTS = List.of(
|
private static final List<String> GUARDED_RELATIVE_ROOTS = List.of(
|
||||||
"backend",
|
"backend",
|
||||||
"lifecycle",
|
"lifecycle",
|
||||||
"workspaces/stages/AssembleLifecyclePipelineStage.java");
|
"workspaces/stages");
|
||||||
private static final String FORBIDDEN_PBS_PACKAGE = "p.studio.compiler.pbs";
|
private static final String FORBIDDEN_PBS_PACKAGE = "p.studio.compiler.pbs";
|
||||||
private static final String FORBIDDEN_PBS_PREFIX = "__pbs.";
|
private static final String FORBIDDEN_PBS_PREFIX = "__pbs.";
|
||||||
|
|
||||||
|
|||||||
+109
@@ -0,0 +1,109 @@
|
|||||||
|
package p.studio.compiler.specs;
|
||||||
|
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
import java.io.IOException;
|
||||||
|
import java.nio.file.Files;
|
||||||
|
import java.nio.file.Path;
|
||||||
|
|
||||||
|
import static org.junit.jupiter.api.Assertions.assertFalse;
|
||||||
|
import static org.junit.jupiter.api.Assertions.assertTrue;
|
||||||
|
import static org.junit.jupiter.api.Assertions.fail;
|
||||||
|
|
||||||
|
class ConsoleAbiAuthoritySpecTest {
|
||||||
|
private static final String SPEC_18 =
|
||||||
|
"docs/specs/compiler/18. Standard Library Surface Specification.md";
|
||||||
|
private static final String PBS_SPEC_8 =
|
||||||
|
"docs/specs/compiler-languages/pbs/8. Stdlib Environment Packaging and Loading Specification.md";
|
||||||
|
private static final String PBS_SPEC_6_2 =
|
||||||
|
"docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md";
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void spec18MustTreatStdlibAsDeliveryAndMustNotOwnConsoleAbi() throws IOException {
|
||||||
|
final var content = Files.readString(locateRepoRoot().resolve(SPEC_18));
|
||||||
|
|
||||||
|
assertTrue(
|
||||||
|
content.contains("This document is PBS delivery. It does not own console ABI."),
|
||||||
|
"spec 18 must state that PBS stdlib is delivery, not console ABI");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("This document MUST NOT define numeric syscall identifiers, intrinsic `final_id`"),
|
||||||
|
"spec 18 must forbid defining syscall IDs and intrinsic final IDs");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("or `SyscallMeta`"),
|
||||||
|
"spec 18 must forbid publishing SyscallMeta");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("## 15. Console ABI Non-Ownership"),
|
||||||
|
"spec 18 must contain Console ABI Non-Ownership");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("Reserved project-space path (`@sdk:*` / `@core:*`) MUST NOT imply VM-owned versus host-backed ownership."),
|
||||||
|
"spec 18 must state that @sdk/@core paths do not imply ownership");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("Current stdlib line `1` ships a VM-owned builtin input shell at `@sdk:input`."),
|
||||||
|
"spec 18 must record @sdk:input as the current builtin exception");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void spec8MustDocumentCurrentGameStdlibLayout() throws IOException {
|
||||||
|
final var content = Files.readString(locateRepoRoot().resolve(PBS_SPEC_8));
|
||||||
|
final var layoutFence = extractFirstTextFence(content);
|
||||||
|
|
||||||
|
assertTrue(content.contains("game/stdlib/1"), "spec 8 must document game/stdlib/1");
|
||||||
|
assertTrue(content.contains("game/stdlib/1/core/color"), "spec 8 must map @core:color");
|
||||||
|
assertTrue(content.contains("game/stdlib/1/sdk/input"), "spec 8 must map @sdk:input");
|
||||||
|
assertTrue(content.contains("game/stdlib/1/sdk/log"), "spec 8 must map @sdk:log");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("Physical stdlib\npath MUST NOT imply VM-owned versus host-backed ownership."),
|
||||||
|
"spec 8 must state that packaging path does not imply ownership");
|
||||||
|
assertTrue(layoutFence.contains("core/\n color/"), "layout fence must include core/color");
|
||||||
|
assertTrue(layoutFence.contains("input/"), "layout fence must include sdk/input");
|
||||||
|
assertTrue(layoutFence.contains("log/"), "layout fence must include sdk/log");
|
||||||
|
assertFalse(layoutFence.contains("audio/"), "layout fence must not ship audio as a current module");
|
||||||
|
assertFalse(layoutFence.contains("math/"), "layout fence must not ship core/math as a current module");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void spec62MustRequirePbsHostShellsToRepeatRuntimeRegistry() throws IOException {
|
||||||
|
final var content = Files.readString(locateRepoRoot().resolve(PBS_SPEC_6_2));
|
||||||
|
|
||||||
|
assertTrue(
|
||||||
|
content.contains("PBS shells MUST repeat identities already published by the runtime registry"),
|
||||||
|
"spec 6.2 must require PBS shells to repeat the runtime registry");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("They MUST NOT invent `(module, name, version)`."),
|
||||||
|
"spec 6.2 must forbid inventing canonical host identity");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("This document MUST NOT publish syscall\nIDs or `SyscallMeta`."),
|
||||||
|
"spec 6.2 must not publish the syscall catalog");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("(\"gfx2d\", \"clear\", 1)"),
|
||||||
|
"spec 6.2 authority example must use a current runtime identity");
|
||||||
|
}
|
||||||
|
|
||||||
|
private static String extractFirstTextFence(final String content) {
|
||||||
|
final var startToken = "```text";
|
||||||
|
final var start = content.indexOf(startToken);
|
||||||
|
if (start < 0) {
|
||||||
|
fail("spec 8 must contain a text layout fence");
|
||||||
|
}
|
||||||
|
final var fenceStart = start + startToken.length();
|
||||||
|
final var end = content.indexOf("```", fenceStart);
|
||||||
|
if (end < 0) {
|
||||||
|
fail("spec 8 layout fence is unclosed");
|
||||||
|
}
|
||||||
|
return content.substring(fenceStart, end);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static Path locateRepoRoot() {
|
||||||
|
var cursor = Path.of(System.getProperty("user.dir")).toAbsolutePath().normalize();
|
||||||
|
while (cursor != null) {
|
||||||
|
final var hasDocs = Files.isDirectory(cursor.resolve("docs/specs/compiler"));
|
||||||
|
final var hasCompiler = Files.isDirectory(cursor.resolve("prometeu-compiler"));
|
||||||
|
if (hasDocs && hasCompiler) {
|
||||||
|
return cursor;
|
||||||
|
}
|
||||||
|
cursor = cursor.getParent();
|
||||||
|
}
|
||||||
|
fail("could not locate repository root from working directory");
|
||||||
|
throw new IllegalStateException("unreachable");
|
||||||
|
}
|
||||||
|
}
|
||||||
+80
@@ -0,0 +1,80 @@
|
|||||||
|
package p.studio.compiler.specs;
|
||||||
|
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
import java.io.IOException;
|
||||||
|
import java.nio.file.Files;
|
||||||
|
import java.nio.file.Path;
|
||||||
|
import java.util.List;
|
||||||
|
|
||||||
|
import static org.junit.jupiter.api.Assertions.assertFalse;
|
||||||
|
import static org.junit.jupiter.api.Assertions.assertTrue;
|
||||||
|
import static org.junit.jupiter.api.Assertions.fail;
|
||||||
|
|
||||||
|
class ValidationOwnershipSpecTest {
|
||||||
|
private static final String SPEC_19 =
|
||||||
|
"docs/specs/compiler/19. Verification and Safety Checks Specification.md";
|
||||||
|
private static final String PBS_SPEC_12 =
|
||||||
|
"docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md";
|
||||||
|
private static final List<String> PBS_FORBIDDEN_COMMON_COVERAGE = List.of(
|
||||||
|
"synthetic wrapper entrypoint missing",
|
||||||
|
"published entrypoint is not function index 0",
|
||||||
|
"hidden boot guard is missing",
|
||||||
|
"synthetic callable origin missing");
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void spec19MustBeCompilerGeneralAndPublishValidationOwnership() throws IOException {
|
||||||
|
final var content = Files.readString(locateRepoRoot().resolve(SPEC_19));
|
||||||
|
|
||||||
|
assertFalse(
|
||||||
|
content.startsWith("# PBS Verification"),
|
||||||
|
"spec 19 must not be titled as PBS Verification");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("# Compiler Verification and Safety Checks Specification"),
|
||||||
|
"spec 19 must use the compiler-general title");
|
||||||
|
assertTrue(content.contains("## 11. Validation Ownership"), "spec 19 must contain Validation Ownership");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("lowest layer that understands the failure without knowing the source language"),
|
||||||
|
"spec 19 must state the classification MUST");
|
||||||
|
assertTrue(content.contains("Parse / syntax"), "spec 19 matrix must include parse/syntax");
|
||||||
|
assertTrue(content.contains("PBS linking"), "spec 19 matrix must include PBS linking");
|
||||||
|
assertTrue(content.contains("Lifecycle assembler"), "spec 19 matrix must include lifecycle assembler");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("Canonical host-binding identity"),
|
||||||
|
"spec 19 matrix must include the host-admission split");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("MUST NOT import `p.studio.compiler.pbs`"),
|
||||||
|
"spec 19 must forbid PBS imports in platform validators");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void pbsDiagnosticsMustNotClaimCommonStructuralFailures() throws IOException {
|
||||||
|
final var content = Files.readString(locateRepoRoot().resolve(PBS_SPEC_12));
|
||||||
|
|
||||||
|
for (final var forbidden : PBS_FORBIDDEN_COMMON_COVERAGE) {
|
||||||
|
assertFalse(
|
||||||
|
content.contains(forbidden),
|
||||||
|
"PBS spec 12 must not list common structural coverage: " + forbidden);
|
||||||
|
}
|
||||||
|
assertTrue(
|
||||||
|
content.contains("docs/specs/compiler/19. Verification and Safety Checks Specification.md"),
|
||||||
|
"PBS spec 12 must point common structural failures at spec 19");
|
||||||
|
assertTrue(
|
||||||
|
content.contains("init function must have signature fn name() -> void"),
|
||||||
|
"PBS spec 12 must retain lifecycle-marker coverage");
|
||||||
|
}
|
||||||
|
|
||||||
|
private static Path locateRepoRoot() {
|
||||||
|
var cursor = Path.of(System.getProperty("user.dir")).toAbsolutePath().normalize();
|
||||||
|
while (cursor != null) {
|
||||||
|
final var hasDocs = Files.isDirectory(cursor.resolve("docs/specs/compiler"));
|
||||||
|
final var hasCompiler = Files.isDirectory(cursor.resolve("prometeu-compiler"));
|
||||||
|
if (hasDocs && hasCompiler) {
|
||||||
|
return cursor;
|
||||||
|
}
|
||||||
|
cursor = cursor.getParent();
|
||||||
|
}
|
||||||
|
fail("could not locate repository root from working directory");
|
||||||
|
throw new IllegalStateException("unreachable");
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user