From 5df15d0c6d33a3b2d89096e07ed880fc564b062b Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Tue, 10 Mar 2026 09:26:51 +0000 Subject: [PATCH] spec core sync 16 and 16a --- .../PR001-spec-core-sync-16-and-16a.md | 39 ------------------- .../runtime/specs/16-host-abi-and-syscalls.md | 13 ++++++- docs/runtime/specs/16a-syscall-policies.md | 26 +++++++++++-- 3 files changed, 34 insertions(+), 44 deletions(-) delete mode 100644 docs/runtime/pull-requests/PR001-spec-core-sync-16-and-16a.md diff --git a/docs/runtime/pull-requests/PR001-spec-core-sync-16-and-16a.md b/docs/runtime/pull-requests/PR001-spec-core-sync-16-and-16a.md deleted file mode 100644 index fc584569..00000000 --- a/docs/runtime/pull-requests/PR001-spec-core-sync-16-and-16a.md +++ /dev/null @@ -1,39 +0,0 @@ -# PR001 - Spec Core Sync 16 and 16a - -## Briefing - -As decisions `007`, `008`, `009` e `010` fixaram um modelo status-first por dominio. - -Precisamos consolidar esse nucleo em specs de ABI/policy para evitar interpretacao divergente durante implementacao. - -## Alvo - -Atualizar as specs base para refletir: - -- fronteira canonica `Trap`/`status`/`Panic`; -- regra de quando syscall pode permanecer `void`; -- regra de quando `status:int` em retorno e obrigatorio; -- proibicao de no-op silencioso quando ha erro operacional observavel. - -Arquivos principais: - -- `docs/runtime/specs/16-host-abi-and-syscalls.md` -- `docs/runtime/specs/16a-syscall-policies.md` - -## Fora de Escopo - -- mudanca de implementacao em runtime; -- mudanca de assinatura de syscall em codigo; -- atualizacao de stress cart. - -## Critérios de Aceite - -- `16` e `16a` citam explicitamente o contrato status-first como politica transversal; -- `16a` documenta regra de retorno por operacao (`void` vs `status`); -- `16a` documenta no-op silencioso proibido para erros operacionais; -- texto nao conflita com decisions `007`/`008`/`009`/`010`. - -## Tests - -- revisao de consistencia documental (diff + leitura cruzada com decisions); -- verificador de links markdown do repositorio, se aplicavel. diff --git a/docs/runtime/specs/16-host-abi-and-syscalls.md b/docs/runtime/specs/16-host-abi-and-syscalls.md index 46469736..7d03234e 100644 --- a/docs/runtime/specs/16-host-abi-and-syscalls.md +++ b/docs/runtime/specs/16-host-abi-and-syscalls.md @@ -24,6 +24,7 @@ The syscall ABI follows these rules: 3. **Load-time resolution**: symbolic host bindings are resolved before execution. 4. **Metadata-driven execution**: arity and result shape come from syscall metadata. 5. **Not first-class**: syscalls are callable but not ordinary function values. +6. **Status-first operational policy**: across syscall domains, operationally observable failure must surface through explicit `status` values, while only structural violations fault as `Trap` and only internal invariant breaks escalate as `Panic`. ## 2 Canonical Syscall Identity @@ -92,6 +93,12 @@ Execution steps: 3. the syscall executes in the host environment; 4. the syscall produces exactly the declared `ret_slots`. +The execution result must respect the canonical runtime boundary defined with [`16a-syscall-policies.md`](16a-syscall-policies.md): + +- successful or operationally rejected execution returns values in the declared stack shape; +- `Trap` is reserved for structural ABI misuse or invalid call shape; +- `Panic` is reserved for runtime/host invariant failure. + ## 5 Syscall Metadata Table Each syscall is defined by metadata. @@ -150,10 +157,12 @@ After execution, the syscall leaves exactly `ret_slots` values on the stack. Composite results use multiple stack slots rather than implicit hidden structures. -Return shape must also follow the operational policy in [`16a-syscall-policies.md`](16a-syscall-policies.md): +Return shape must also follow the transversal status-first policy in [`16a-syscall-policies.md`](16a-syscall-policies.md): -- operations with observable operational failure paths should expose an explicit `status:int` return; +- when a syscall exposes operational failure, `status:int` is the canonical first return slot; +- operations with observable operational failure paths must expose that explicit `status:int` return; - operations with no real operational error path may remain `void` (`ret_slots = 0`); +- if extra payload is returned together with `status`, the payload must follow the leading status slot in the declared stack shape; - stack shape remains strict in both cases and must match syscall metadata exactly. ### MEMCARD game surface (`mem`, v1) diff --git a/docs/runtime/specs/16a-syscall-policies.md b/docs/runtime/specs/16a-syscall-policies.md index aee31be6..fb940b1f 100644 --- a/docs/runtime/specs/16a-syscall-policies.md +++ b/docs/runtime/specs/16a-syscall-policies.md @@ -7,9 +7,11 @@ This chapter defines the operational policies that sit on top of the host ABI. It complements [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md), which defines the structural ABI itself. +Unless a domain chapter explicitly narrows behavior further, this chapter is the transversal policy for all syscalls in v1. + ## 1 Error Model: Faults vs Status Returns -Syscalls use a hybrid model. +Syscalls use a status-first hybrid model. ### Fault conditions @@ -35,7 +37,7 @@ Faults are split into two runtime classes: ### Status returns -Normal operational conditions should be represented as values in return slots. +Normal operational success and operational failure conditions should be represented as values in return slots. Examples: @@ -43,20 +45,38 @@ Examples: - audio voice unavailable; - persistent storage full. +When a syscall returns `status`, that `status:int` occupies the first return slot. +Any additional payload is domain-defined and follows that leading status slot. + ### Return shape policy (`void` vs `status`) This policy is normative: -- if an operation has observable operational failure modes, it should return `status:int` explicitly; +- if an operation has observable operational failure modes, it must return `status:int` explicitly; +- if an operation can be operationally rejected, ignored, deferred with failure, or conclude with guest-observable `no_effect`, it is not eligible to remain `void`; - if an operation has no real operational error path, it may remain `void` (`ret_slots = 0`); - `status` coding is domain-owned and may differ by operation, but must be deterministic and documented. +Practical rule: + +- `void` is allowed only for operations whose non-fault path is effectively unconditional success; +- any operation with a meaningful operational non-success outcome must surface that outcome through `status`, not through absence of return values. + ### No-op policy Silent no-op is not allowed when an operation can fail operationally in a guest-observable way. In those cases, the runtime must return explicit `status` instead of masking failure as implicit success. +Implicit fallback is also forbidden when it hides an operational error or state rejection that the guest could observe or reason about. + +This means operational problems must not be reclassified as: + +- silent success; +- silent ignore; +- `Trap`, when the failure is not structural; +- `Panic`, when the failure is not an internal invariant break. + ## 2 Capability System Each syscall requires a declared capability.