prometeu-studio/docs/compiler/general/specs/18. Standard Library Surface Specification.md

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:

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.