discussion framework migration
This commit is contained in:
@@ -0,0 +1,188 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user