189 lines
7.4 KiB
Markdown
189 lines
7.4 KiB
Markdown
# PBS Standard Library Surface Specification
|
|
|
|
Status: Draft v0 (Skeleton)
|
|
Applies to: normative stdlib-facing API surface, reserved stdlib project spaces, and versioned standard-library contracts exposed to PBS programs
|
|
|
|
## 1. Purpose
|
|
|
|
This document will define the normative user-facing standard-library surface for PBS.
|
|
|
|
## 2. Scope
|
|
|
|
This document is intended to define:
|
|
|
|
- what counts as part of the PBS stdlib contract,
|
|
- how stdlib modules are grouped and versioned,
|
|
- which APIs are normative versus implementation-private,
|
|
- how VM-owned builtin shells are exposed to user code,
|
|
- how reserved stdlib project spaces expose user-facing surfaces over host-backed capabilities.
|
|
|
|
This document does not define:
|
|
|
|
- one physical packaging layout,
|
|
- registry/publication mechanics,
|
|
- host loader behavior,
|
|
- implementation-private helper modules.
|
|
|
|
## 3. Authority and Precedence
|
|
|
|
Normative precedence:
|
|
|
|
1. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
|
2. `8. Stdlib Environment Packaging and Loading Specification.md`
|
|
3. `6. VM-owned vs Host-backed.md`
|
|
4. `6.1. Intrinsics and Builtin Types Specification.md`
|
|
5. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
6. This document
|
|
|
|
If a rule here conflicts with higher-precedence specs, it is invalid.
|
|
|
|
## 4. Normative Inputs
|
|
|
|
This document depends on, at minimum:
|
|
|
|
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
|
- `6. VM-owned vs Host-backed.md`
|
|
- `6.1. Intrinsics and Builtin Types Specification.md`
|
|
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
- `8. Stdlib Environment Packaging and Loading Specification.md`
|
|
|
|
## 5. Already-Settled Inputs
|
|
|
|
The following inputs are already fixed elsewhere and must not be contradicted here:
|
|
|
|
- Reserved stdlib project spaces include `@sdk:*` and `@core:*`.
|
|
- Stdlib interface modules are compile-time-only and loaded as PBS-like modules.
|
|
- Stdlib interface modules may include service facades whose bodies delegate to reserved host owners; such bodies are source-surface ergonomics and not standalone runtime modules.
|
|
- User code must import stdlib modules explicitly.
|
|
- 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.
|
|
|
|
## 6. Initial Section Targets
|
|
|
|
At minimum, the completed document should contain normative sections for:
|
|
|
|
1. stdlib contract boundaries,
|
|
2. reserved stdlib project spaces and module families,
|
|
3. normative versus non-normative API surfaces,
|
|
4. VM-owned builtin shells exposed to user code,
|
|
5. host-backed SDK surfaces exposed to user code,
|
|
6. versioning and deprecation expectations for stdlib APIs.
|
|
|
|
## 7. TODO
|
|
|
|
The following items remain to be closed in future agenda discussion.
|
|
|
|
- Which stdlib modules are mandatory in each active stdlib line.
|
|
- Which APIs are part of the normative core teaching surface versus optional library growth.
|
|
- Whether `@core:*` is specified as language-adjacent utility surface or as ordinary stdlib contract.
|
|
- How stdlib API evolution is documented and conformance-tested.
|
|
- 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.
|
|
|
|
## 8. Non-Goals
|
|
|
|
- Replacing the resolution/packaging specs.
|
|
- Defining all future libraries in one pass.
|
|
- Hardcoding one distribution format.
|
|
|
|
## 9. Exit Criteria
|
|
|
|
This document is ready to move beyond skeleton status only when:
|
|
|
|
1. the normative user-facing stdlib surface is explicitly bounded,
|
|
2. reserved project-space API responsibilities are clear,
|
|
3. VM-owned and host-backed stdlib surfaces are explicitly separated,
|
|
4. stdlib versioning and deprecation expectations are aligned with compatibility policy,
|
|
5. the document no longer relies on unresolved `TODO` items for ordinary v1 stdlib contract claims.
|
|
|
|
## 10. Reserved Project-Space Responsibilities
|
|
|
|
The current stdlib direction distinguishes two user-facing reserved spaces.
|
|
|
|
### 10.1 `@core:*`
|
|
|
|
`@core:*` is the preferred surface for VM-owned declarations that belong to the
|
|
language-adjacent semantic platform.
|
|
|
|
Examples:
|
|
|
|
- builtin type shells,
|
|
- builtin constants,
|
|
- and other VM-owned helper declarations that are not host capability surfaces.
|
|
|
|
### 10.2 `@sdk:*`
|
|
|
|
`@sdk:*` is the preferred surface for host-backed capability-facing APIs.
|
|
|
|
Examples:
|
|
|
|
- `declare host` surfaces,
|
|
- capability-facing wrappers over host services,
|
|
- and domain SDK modules whose execution meaning ultimately depends on host-backed operations.
|
|
|
|
Rules:
|
|
|
|
- source packaging location is part of the stdlib contract surface,
|
|
- 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.
|
|
|
|
## 11. Builtin Shell Surfaces
|
|
|
|
Reserved stdlib modules may expose builtin declarations as compile-time-only
|
|
shells.
|
|
|
|
Rules:
|
|
|
|
- stdlib builtin shells may expose `declare builtin type` declarations,
|
|
- stdlib builtin shells may expose reserved `declare const` declarations carrying `BuiltinConst(...)`,
|
|
- stdlib builtin shells may expose builtin methods carrying `IntrinsicCall(...)`,
|
|
- these shells exist for import, name resolution, type checking, and lowering,
|
|
- and these shells do not provide executable PBS bodies for builtin behavior.
|
|
|
|
Stdlib is therefore the delivery surface, not the semantic owner.
|
|
|
|
## 12. Host-backed SDK Surfaces
|
|
|
|
Reserved stdlib modules may expose host-backed declarations as compile-time-only
|
|
shells.
|
|
|
|
Rules:
|
|
|
|
- host-backed stdlib surfaces use `declare host`,
|
|
- host-backed stdlib modules may also expose `declare service` facades that call internal non-public host owners,
|
|
- host-backed method signatures carry `Host(...)`,
|
|
- internal low-level host owners can remain non-public via `mod` barrel visibility while higher-level services are exported with `pub`,
|
|
- user code may import those host owners through ordinary stdlib module imports,
|
|
- and lowering continues through canonical host identity, `SYSC`, `HOSTCALL`, loader resolution, and final `SYSCALL`.
|
|
|
|
## 13. Stdlib Contract Expectations for Builtin MVP
|
|
|
|
For the current builtin MVP, stdlib should be able to expose at least:
|
|
|
|
1. a builtin type shell for `Color`,
|
|
2. a builtin type shell for `Vec2`,
|
|
3. a builtin type shell for `Pixel`,
|
|
4. a builtin constant shell for `vec2.zero`,
|
|
5. and any associated documentation-level or teaching-level module organization needed to make those surfaces discoverable.
|
|
|
|
Illustrative example:
|
|
|
|
```pbs
|
|
import { Vec2, ZERO } from @core:math;
|
|
```
|
|
|
|
The imported names are source-visible conveniences.
|
|
Their canonical runtime-facing identities still come from builtin metadata such
|
|
as `BuiltinType(name="vec2", version=1)` and
|
|
`BuiltinConst(target="vec2", name="zero", version=1)`.
|
|
|
|
## 14. Deterministic Stdlib Surface Failures
|
|
|
|
At minimum, a conforming implementation must reject:
|
|
|
|
1. a stdlib builtin shell that attempts to use host-binding metadata for VM-owned intrinsic behavior,
|
|
2. a stdlib host shell that attempts to use builtin metadata in place of host-binding metadata,
|
|
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,
|
|
5. a stdlib line that exposes conflicting canonical host identities through the same resolved environment.
|