implements PLN-0127
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 61.95% (17766/28676)
* Branch Coverage: 52.69% (6860/13019)
* Lines of Code: 28676
* Cyclomatic Complexity: 11490
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 648
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 61.95% (17766/28676)
* Branch Coverage: 52.69% (6860/13019)
* Lines of Code: 28676
* Cyclomatic Complexity: 11490
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 648
Publish the console ABI authority map: runtime catalogs win, PBS stdlib is delivery. Recut specs 18, 8, and 6.2 and lock them with ConsoleAbiAuthoritySpecTest. Housekeep DSC-0061 with LSN-0064.
This commit is contained in:
@@ -1,9 +1,9 @@
|
||||
{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":48,"PLN":127,"LSN":64,"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-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-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":"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-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"}]}
|
||||
|
||||
+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,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.
|
||||
|
||||
Reference in New Issue
Block a user