Skip to content

Section 14: Standard Library and Built-in APIs

TECHSPEC-14 — Section 14 · Version 0.1 · Status: Initial Draft

Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.

1. Standard Library Philosophy

The standard library provides common functionality through consistent, documented, and verifiable APIs.

Standard library functions must follow the same language rules as ordinary functions.

Built-in functionality must not receive exemptions from type safety, contracts, effect declarations, or error handling.

2. Initial Library Categories

The standard library is divided into these categories:

  • CORE: Fundamental language operations and utilities.
  • MATH: Numeric operations and mathematical functions.
  • COLLECTIONS: Lists, maps, sets, and other data structures.
  • TEXT: String manipulation, encoding, and parsing.
  • IO: Input and output operations.
  • FILESYSTEM: File and directory operations.
  • NETWORK: Network communication and protocols.
  • DATABASE: Database access and transactions.
  • CONCURRENCY: Tasks, synchronization, and message passing.
  • TIME: Clocks, timers, and date operations.
  • SECURITY: Cryptographic and security-related operations.
  • SERIALIZATION: Conversion between structured data formats.

3. Standard Function Requirements

Every standard library function must define:

  • Function signature.
  • Input and output types.
  • Preconditions.
  • Postconditions.
  • Side effects.
  • Required permissions.
  • Possible failures.
  • Resource requirements.
  • Verification status.
  • Known limitations.

Rules: - Functions must not perform undeclared effects. - Functions must not hide possible failures. - Public APIs must have stable, documented behavior. - Implementations must preserve their declared contracts. - Unsupported guarantees must be identified explicitly.

4. API Consistency

Standard library APIs must follow consistent naming and behavior conventions.

Rules: - Equivalent operations should use consistent naming. - Similar functions should use compatible parameter conventions. - Return types should communicate success and failure consistently. - Optional values must use explicit optional types. - Resource acquisition and release must follow ownership rules. - Breaking API changes must be documented and versioned.

5. External System Integration

Libraries that interact with external systems must declare their effects and permissions.

Examples: - Filesystem functions require filesystem permissions. - Network functions require network permissions. - Database functions require database permissions. - System functions require appropriate operating-system permissions.

Rules: - External data must be treated as untrusted until validated. - External failures must be represented explicitly. - Timeouts and cancellation must be supported where applicable. - External resources must have defined ownership and lifetimes. - Successful API invocation must not be confused with successful external completion.

6. Standard Library Verification

The standard library must have its own verification and testing requirements.

Rules: - Public functions must have contract tests. - Critical functions should receive additional property-based and boundary testing. - Security-sensitive functions require appropriate security review. - Formal verification should be used where practical and meaningful. - Verification evidence must identify the exact library version. - Known limitations must be documented.

7. Compiler and Runtime Responsibilities

The compiler and runtime must: - Resolve standard library APIs. - Validate function signatures and contracts. - Enforce declared effects and permissions. - Preserve typed failure behavior. - Track library versions. - Make standard library documentation accessible to AI agents.

8. Design Goal

AI agents must be able to use standard functionality without relying on undocumented behavior or hidden assumptions.

The standard library must provide predictable operations with explicit guarantees and honest verification records.

Source file: TECHSPEC-14.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.