spec core sync 16 and 16a

docs/runtime/pull-requests/PR001-spec-core-sync-16-and-16a.md

@@ -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.

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)

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.