Vitte

Compiler contract <-> stdlib

This document defines the stable contract between the Vitte compiler and the stdlib runtime surface.

Terminology used in the doc and CLI:

  • “Vitte binding surface” replaces “libc surface”.
  • “Vitte binding” replaces “interop C”.

1. Source of truth

  • Versioned ABI surface file: stdlib_abi_surface_v1.txt (historical name).
  • Next ABI version: stdlib_abi_surface_v2.txt (historical name).
  • Source root of the stdlib: dedicated source tree.
  • Runtime ABI header: src/compiler/backends/runtime/vitte_runtime.vitl.

2. Stable stdlib profiles

--runtime-profile controls which stdlib modules are allowed. --stdlib-profile is kept as a historical alias.

  • core (history minimal): only core/**.
  • desktop (history full): all stdlib modules.
  • system (history kernel): core/** + kernel/**.
  • arduino: core/** + arduino/**.

If an import is not authorized, the compiler emits E1010. If a stdlib module is missing, the compiler emits E1014.

Module levels:

  • public: stable import surface.
  • internal: private namespace (*/internal/*), blocked without owner (E1016).
  • experimental: activation only with --allow-experimental (E1015).

3. Strictness of imports

--strict-imports (aka --strict-bridge) imposes import hygiene:

  • explicit alias required on use/pull (E1011).
  • explicit aliases must be used (E1012).
  • non-canonical relative paths are rejected (E1013).

4. Runtime/Vitte link error boundary

  • Parse layer: E000x.
  • Resolve layer: E100x (includes stdlib/import constraints).
  • IR layer: E200x.
  • Backend layer/toolchain: E300x.

5. Tools

  • Export stdlib symbol map:
  • vitte check --dump-stdlib-map <file.vit>
  • Export the full module index:
  • vitte check --dump-module-index <file.vit>
  • Graph and doctor:
  • vitte mod graph <file.vit>
  • vitte mod doctor <file.vit>
  • Check surface ABI against stdlib source:
  • tools/lint_stdlib_api.py
  • ABI compatibility issue:
  • tools/check_stdlib_abi_compat.py
  • Profile Snapshots:
  • tools/stdlib_profile_snapshots.sh

6. Binding surface name

For documentation and examples of system/Vitte binding, prefer stdlib-oriented names:

  • print
  • read
  • path
  • env
  • bytes
  • alloc
  • process

Bridge module plan in the doc:

  • bridge/io
  • bridge/memory
  • bridge/system
  • bridge/time
  • bridge/net