BPlatform specification
Login
Edit this page
featureStandard

Core.Syscall

Typed descriptor syscall facade for text and binary I/O.

Document layout: Feature capability layoutconforms
  • ## Purpose
  • ## Requirements

Core.Syscall Specification

Purpose

Typed descriptor syscall facade for text and binary I/O.

Requirements

Requirement: Typed descriptor facade for ReadWith and WriteWith

ReadWith / WriteWith MUST route via typed Descriptor, not raw fd integers in stream modules (SC-001). Core.Input / Core.Output / Core.Error MUST use Descriptor::Standard only (SC-004, IO-001, IO-002).

Scenario: Stream modules reject raw fd integers

  • GIVEN a call through Core.Input, Core.Output, or Core.Error
  • WHEN the implementation selects a descriptor
  • THEN only Descriptor::Standard is used and raw fd integers are not accepted in those stream modules

Requirement: Binary ReadBytes and WriteBytes for arbitrary descriptors

ReadBytes MUST support arbitrary non-negative fds via Descriptor::Raw (SC-002). WriteBytes MUST accept u8[] payloads for arbitrary fds (SC-003).

Scenario: Raw descriptor binary round-trip surface

  • GIVEN a non-negative file descriptor wrapped as Descriptor::Raw
  • WHEN a caller invokes ReadBytes or WriteBytes with a u8[] payload where applicable
  • THEN the call is accepted for that arbitrary descriptor rather than being limited to standard streams

Requirement: Stable SyscallError mapping across JIT and AOT

SyscallError mapping MUST be stable across JIT and AOT (SC-005).

Scenario: Same error class under JIT and AOT

  • GIVEN a syscall failure that maps to a documented SyscallError variant
  • WHEN the same failure is observed under JIT and under AOT
  • THEN both builds report the same SyscallError mapping

Requirement: Partial writes, EOF reads, and UTF-8 validation

On Linux, the write path MUST loop partial writes; reads MUST return short buffers on EOF (SC-006). Text Read MUST validate UTF-8 when building string (SC-007). Binary ReadBytes MUST NOT validate UTF-8 (SC-008).

Scenario: Text Read rejects invalid UTF-8

  • GIVEN a descriptor whose next bytes are not valid UTF-8
  • WHEN a caller invokes text Read to build a string
  • THEN UTF-8 validation fails rather than producing an invalid string

Requirement: InvalidFd and InvalidReadLimit guards

A negative fd MUST return InvalidFd before the syscall (SC-009). maxBytes < 1 MUST return InvalidReadLimit (SC-010).

Scenario: Negative fd rejected before syscall

  • GIVEN a caller supplies a negative file descriptor
  • WHEN a Core.Syscall read or write entry is invoked
  • THEN the call returns InvalidFd without performing the underlying syscall

Informative Source Provenance

The records below preserve migration history and are not normative except where text was extracted into a requirement above.

Source Record: Core.Syscall

Authority: informative provenance
Legacy path: /platform-spec/core-library/stability-and-api-shape/core-syscall/
Source: site/spec-content/platform-spec/core-library/stability-and-api-shape/core-syscall/content.md
SHA-256: f95c22f491d5508c581762cf0dc3e554cee867575464f13c2ed4e88a7da0bb46

Migrated source text 
<SpecSection title="What this feature specifies" id="what-this-feature-specifies">
`Core.Syscall` exposes typed `ReadWith` / `WriteWith` and binary `ReadBytes` / `WriteBytes` for arbitrary descriptors via `Descriptor::Raw`. Standard stream modules remain a restricted profile (**SC-004**, **IO-001** / **IO-002**).
</SpecSection>

<SpecSection title="Scope" id="scope">
- **In scope:** Typed descriptor facade (`Descriptor`, `ReadRequest`, `WriteRequest`, `SyscallError`), text and binary read/write for arbitrary fds, and stable error mapping across JIT/AOT.
- **Out of scope:** Console markup, terminal controls, and std-stream-only modules (`Core.Input`, `Core.Output`, `Core.Error`) which **must** use `Descriptor::Standard` only.
</SpecSection>

<SpecSection title="Implementation anchors" id="implementation-anchors">
- `compiler/corelib/packages/foundation/src/Core/Syscall.bd`
- `compiler/corelib/packages/foundation/src/Core/Syscall/`
- Runtime builtins: `compiler/crates/beskid_runtime/src/builtins/io.rs`
- Corelib tests: `compiler/corelib/beskid_corelib/tests/corelib_tests/src/system/Syscall*Tests.bd`
</SpecSection>

<SpecSection title="Contract statement" id="contract-statement">
| Surface | Rule |
| --- | --- |
| **SC-001** | `ReadWith` / `WriteWith` **must** route via typed `Descriptor`, not raw fd integers in stream modules. |
| **SC-004** | `Core.Input` / `Output` / `Error` **must** use `Descriptor::Standard` only (**IO-001**, **IO-002**). |
| **SC-005** | `SyscallError` mapping **must** be stable across JIT/AOT. |
</SpecSection>

## Decisions
<!-- spec:generate:adr-index -->
No ADRs published under **`adr/`** yet.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Contracts and edge cases](./articles/contracts-and-edge-cases/)
<!-- /spec:generate:article-index -->

Source Record: Contracts and edge cases

Authority: informative provenance
Legacy path: /platform-spec/core-library/stability-and-api-shape/core-syscall/articles/contracts-and-edge-cases/
Source: site/spec-content/platform-spec/core-library/stability-and-api-shape/core-syscall/articles/contracts-and-edge-cases/content.md
SHA-256: e0632b9797576fd5e3abfecf6c85c43dc9c012e11fdb1f07770a67c288ceebd8

Migrated source text 
## Normative requirements

| ID | Requirement |
| --- | --- |
| **SC-001** | `ReadWith` / `WriteWith` **must** route via typed `Descriptor`, not raw fd integers in stream modules. |
| **SC-002** | `ReadBytes` **must** support arbitrary non-negative fds via `Descriptor::Raw`. |
| **SC-003** | `WriteBytes` **must** accept `u8[]` payloads for arbitrary fds. |
| **SC-004** | `Core.Input` / `Output` / `Error` **must** use `Descriptor::Standard` only (**IO-001**, **IO-002**). |
| **SC-005** | `SyscallError` mapping **must** be stable across JIT/AOT. |
| **SC-006** | Linux write path **must** loop partial writes; read returns short buffers on EOF. |
| **SC-007** | Text `Read` **must** validate UTF-8 when building `string`. |
| **SC-008** | Binary `ReadBytes` **must not** validate UTF-8. |
| **SC-009** | Negative fd **must** return `InvalidFd` before syscall. |
| **SC-010** | `maxBytes < 1` **must** return `InvalidReadLimit`. |

## Implementation anchors

- `compiler/corelib/packages/foundation/src/Core/Syscall.bd`
- `compiler/corelib/packages/foundation/src/Core/Syscall/`