Design Notes

1. Implementation status

• Stage-0 runs dynamically: values are evaluated and typed at runtime.
• reference.md flags the static type system, Arrow dataframe engine, and native/WASM compiler as planned but not in Stage-0.
• Design docs in .sources/vela/design describe the target compiler/runtime architecture.

2. Type system notes (planned)

design/TYPE_SYSTEM.md defines a typed front end with:

• row-polymorphic dataframes,
• Option[T] as T? in the typed view,
• traits/typeclasses (Ord, Num, Hash, Clone, and more),
• error conversion around ?,
• inferred nominally stable APIs and memory-tier typing.

These are design commitments, not fully implemented by the seed interpreter.

3. Memory model notes (planned details)

design/MEMORY_MODEL.md documents a tiered model:

• Tier-0 default, default immutable-by-default semantics,
• copy-on-write with optimization passes,
• reference counting with move semantics,
• mutable/dynamic collections and cycle-aware cleanup.

The docs also note that beginners should not be forced to reason about weak/strong ownership annotations in Tier-0 workflows.

4. Concurrency model (planned)

design/CONCURRENCY.md describes:

• structured concurrency and cancellation scopes,
• async/await with explicit checkpoints,
• channels and actors as safe shared-state patterns,
• supervisor/nursery style task orchestration,
• Send/Sync-style checks for ownership-tier code.

This is not presented as complete Stage-0 behavior.

5. Module system and toolchain (planned)

design/MODULES_AND_PACKAGES.md proposes use paths, package manifests (Vela.toml, lockfiles), and import visibility rules (pub and pub(crate)) beyond seed behavior.

6. How to read this page

Treat this section as the roadmap anchor:

• if you can run it with vela run from the seed, it is Stage-0 behavior;
• if the source is in design/* and marked planned, staged, or draft, treat it as not-yet in the seed.